Codex CLI 설치 방법: Windows·macOS 설치와 확인 (WSL 없이)

Codex CLI 요구사항 문서는 Windows 11 옆에 “via WSL2”를 붙여 두었습니다. 그런데 README는 WSL 얘기 없이 PowerShell 설치 명령을 안내하죠. 두 문서가 서로 다른 말을 하는 셈이에요.

Windows 11 테스트 환경에서 직접 해 보니 WSL은 필요 없었습니다. Node.js가 있으면 npm install -g @openai/codex 한 줄로 깔리고, 새 터미널에서 codex --version이 codex-cli 0.158.0 같은 줄을 찍으면 설치는 끝난 겁니다. 그다음 codex를 실행해 ChatGPT 계정(Plus 이상)이나 API 키로 로그인하면 바로 쓸 수 있어요.

Codex CLI는 OpenAI가 만든 터미널용 코딩 에이전트입니다. 프로젝트 폴더에서 말로 일을 시키면 코드를 읽고 고치고 명령을 실행해요.

2026년 9월 11일 Ubuntu 24.04에서 0.154.0을, 9월 28일 Windows 11 · PowerShell 5.1에서 0.158.0을 npm으로 설치해 확인했고(10월 16일 0.162.1로 첫 설치 상태를 다시 확인), 설치 방법과 요구사항은 9월 11일 OpenAI 공식 저장소 문서 기준입니다.

어떤 방법으로 깔까

이미 Node.js를 쓰고 있다면 npm이 제일 손이 덜 갑니다. 설치는 7초면 끝나요.

npm install -g @openai/codex

added 2 packages in 7s

다른 방법은 상황에 맞게 하나만 고르면 됩니다.

상황	설치 명령
Node.js가 있다	npm install -g @openai/codex
macOS + Homebrew	brew install --cask codex
Node.js 없음, macOS·Linux	curl -fsSL https://chatgpt.com/codex/install.sh | sh
Node.js 없음, Windows	powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

macOS에서 npm과 Homebrew 중 무엇이 나은지는 이미 쓰는 쪽을 따르면 됩니다. Homebrew를 쓰고 있다면 brew install --cask codex로 업데이트까지 Homebrew에 맡길 수 있어 편하고, Node.js를 쓰고 있다면 npm도 차이가 없어요.

이 밖에 GitHub Releases에서 macOS(Apple Silicon·x86_64)와 Linux(x86_64·arm64) 실행 파일을 직접 받거나, 여러 플랫폼에서 같은 버전을 고정하는 DotSlash 배포판을 쓸 수도 있습니다. 회사 환경처럼 npm 전역 설치를 쓸 수 없다면 이쪽이 대안이에요.

npm 출력의 “2 packages”는 정상입니다. CLI 본체(@openai/codex)와 운영체제·CPU에 맞는 실행 파일 패키지(예: @openai/codex-linux-x64)가 따로 깔리거든요.

설치 전에 갖춰야 할 것은 많지 않습니다.

• 운영체제: macOS 12 이상, Ubuntu 20.04 이상 / Debian 10 이상, Windows 11
• 메모리: 4GB 이상(8GB 권장)
• Git: 2.23 이상(PR 관련 기능용, 없어도 설치는 됩니다)
• 계정: ChatGPT Plus·Pro·Business·Edu·Enterprise 중 하나, 또는 API 키. 요금제 구성은 자주 바뀌니 OpenAI Codex 저장소 README에서 확인하세요.

깔렸는지 확인하기

새 터미널을 열고 이 한 줄을 실행합니다.

codex --version

codex-cli 0.154.0

이 줄이 나오면 성공입니다. command not found나 “인식되지 않습니다”가 나오면 새 터미널을 열었는지, npm 전역 설치 폴더가 PATH에 있는지부터 보세요.

그다음은 codex doctor예요. 설치·설정·인증·네트워크를 한 번에 점검하는데, 로그인 전에는 인증만 실패로 나옵니다.

✗ auth   no Codex credentials were found - Run codex login or provide an API key through a supported auth env var.
      auth storage mode        File
      auth file                ~/.codex/auth.json
✓ config loaded
      config.toml              ~/.codex/config.toml

auth의 ✗는 아직 로그인하지 않았다는 뜻일 뿐이라 놀랄 필요 없습니다. 설치가 됐다는 건 config loaded의 ✓가 말해 줘요.

계정 없이 설치만 먼저 해 봐도 됩니다. 설치, codex --version, codex doctor, codex sandbox는 로그인 없이 동작하고, 실제로 일을 시킬 때만 로그인이 필요합니다.

Windows에서는 WSL 없이 됐다

Windows 11 · PowerShell 5.1 · Node.js 24 · npm 11에서 깔려 있던 0.153.4를 그대로 올렸습니다.

npm install -g @openai/codex@latest
codex --version

changed 2 packages in 6s
codex-cli 0.158.0

로그인 전 상태에서 codex doctor --summary를 돌리면 핵심 줄은 이렇습니다.

Codex Doctor v0.158.0 · windows-x86_64
…
   ⚠ security     Microsoft Defender can interfere with Codex. Verify Codex exclusions.
   ✗ auth         no Codex credentials were found - …
   ⚠ websocket    Responses WebSocket failed; HTTPS fallback may still work - …
…
  ✓ sandbox      restricted fs + restricted network · approval OnRequest
…
21 ok · 1 idle · 3 notes · 2 warn · 1 fail failed

sandbox 줄이 처음 설치한 상태의 기본값입니다. 파일 시스템과 네트워크를 모두 제한하고, 필요할 때 승인을 묻는다는 뜻이에요. 이 기본값이 실제로 무엇을 막는지는 Codex CLI 샌드박스 모드가 막는 곳에 썼습니다.

설정 파일 위치는 운영체제와 상관없이 ~/.codex/config.toml이고, Windows라면 %USERPROFILE%\.codex\config.toml입니다.

해 보니 예상과 달랐던 것

경고가 둘 떴는데, 둘 다 당장 손댈 일은 아니었습니다.

WebSocket 경고는 프록시·VPN·방화벽을 확인하라고 하지만, 네트워크를 뒤질 필요는 없었어요. 로그인한 뒤 같은 환경에서 다시 돌리자 같은 항목이 connected (HTTP 101 Switching Protocols)로 바뀌더라고요. 인증 정보가 없어 연결이 거절된 것으로 추정하는데, 이 경우를 설명한 공식 문서는 찾지 못했습니다.

Defender 경고는 Windows에서만 뜹니다. 상세 출력은 codex.exe, codex-windows-sandbox-setup.exe, codex-command-runner.exe, codex-code-mode-host.exe와 서명된 Codex 앱을 경로·인증서 예외에 넣으라고 안내해요. 이번에는 실제로 막힌 것이 없었으니, 실행이 막히거나 느려질 때 넣어도 됩니다.

0.158.0 때는 업데이트 알림이 늦었습니다. 캐시된 최신 버전은 0.154.0(마지막 확인 2026-09-10)인데 실제 최신은 0.158.0이었거든요. 새 버전이 나왔는지는 npm view @openai/codex version으로 직접 보는 편이 정확합니다.

하나 더, codex doctor는 경고만 있으면 종료 코드 0, 실패가 있으면 1이었습니다. 스크립트에서 설치 점검에 쓴다면 이걸 기준으로 삼으면 돼요.

0.162.1에서 다시 본 첫 설치 상태

10월 16일 0.162.1에서 CODEX_HOME을 빈 폴더로 돌려, 막 설치하고 로그인하기 전과 같은 상태로 codex doctor --summary를 다시 돌렸습니다.

Codex Doctor v0.162.1 · windows-x86_64

Notes
   ↑ updates      0.163.0 available (current 0.162.1)
   ⚠ security     Microsoft Defender can interfere with Codex. Verify Codex exclusions.
   ✗ auth         no Codex credentials were found - …
   ⚠ websocket    Responses WebSocket failed; HTTPS fallback may still work - …
…
  ✓ sandbox      restricted fs + restricted network · approval OnRequest
…
21 ok · 1 idle · 4 notes · 2 warn · 1 fail failed

경고 둘과 인증 실패, 샌드박스 기본값은 0.158.0 때와 같았고 종료 코드도 1이었습니다. 달라진 건 맨 위 updates 줄이에요. 이번에는 새 버전 0.163.0을 바로 알려 줬고, npm view @openai/codex version도 같은 0.163.0이었습니다.

로그인하고 처음 쓸 명령

프로젝트 폴더에서 codex를 실행하면 로그인 절차가 시작됩니다. 10월 17일 0.162.1을 빈 CODEX_HOME으로 처음 띄우자 이런 화면이 나왔어요.

Sign in with ChatGPT를 고르면 브라우저에서 ChatGPT 계정으로 로그인하고, Provide your own API key는 API 키를 써서 쓴 만큼 결제합니다. 가운데 Sign in with Device Code는 브라우저를 띄울 수 없는 곳(원격 서버 등)에서 다른 기기로 일회용 코드를 넣어 로그인하는 방법이에요.

로그인만 따로 하려면 codex login을 씁니다. 로그인이 됐는지는 이렇게 확인합니다(Windows 11, 0.158.0).

codex login status

Logged in using ChatGPT

처음에는 이 정도 하위 명령만 알면 충분합니다.

• codex — 대화형 세션 시작
• codex exec "<지시>" — 대화 없이 한 번 실행하고 끝내기(별칭 e)
• codex review — 대화 없이 코드 리뷰
• codex doctor — 설치·설정·인증·네트워크 진단
• codex mcp — MCP 서버 관리(list·add·remove 등).
• codex update — 최신 버전으로 올리기
• codex logout — 인증 정보 지우기

실행 옵션도 셋이면 시작할 수 있어요. -s(--sandbox)는 명령이 어디까지 쓸 수 있는지(read-only, workspace-write, danger-full-access), -a(--ask-for-approval)는 실행 전에 승인을 언제 받는지(on-request, never), -c key=value는 설정 값을 이번 실행에만 덮어쓰는 옵션입니다.

설정 파일은 ~/.codex에

설정 파일은 ~/.codex/config.toml(Windows는 %USERPROFILE%\.codex\config.toml)이고, 없어도 기본값으로 잘 돕니다. 설정을 만지기 시작하면 이 세 가지가 헷갈리기 쉬워요.

• --profile <이름>을 주면 config.toml 위에 같은 폴더의 <이름>.config.toml을 얹습니다. 프로필은 config.toml 안의 표가 아니라 별도 파일이에요.
• 기준 폴더는 CODEX_HOME 환경 변수로 바꿀 수 있고, 기본은 ~/.codex입니다.
• 인증 정보를 파일로 저장하면 같은 폴더에 auth.json이 생깁니다(운영체제 키체인에 저장하면 생기지 않습니다).

주의: ~/.codex 폴더는 다른 사람과 공유하거나 저장소에 커밋하지 마세요. 인증 정보가 함께 들어 있을 수 있습니다.

같은 키를 여러 곳에 적었을 때 어느 값이 이기는지는 Codex CLI config.toml 우선순위에서 이어집니다.

업데이트와 삭제

업데이트는 codex update 한 줄입니다. npm으로 깔았다면 npm install -g @openai/codex@latest도 같아요. 삭제는 설치한 방법의 반대로 합니다.

npm uninstall -g @openai/codex     # npm으로 설치했을 때
brew uninstall --cask codex        # Homebrew로 설치했을 때

패키지를 지워도 ~/.codex 폴더(설정·인증 정보)는 남습니다. 완전히 정리하려면 이 폴더도 직접 지우세요.

다른 사람들이 겪은 설치 오류

아래 세 건은 GitHub 공개 이슈에 올라온 사례입니다. 앞의 둘은 결국 npm 전역 폴더 권한 문제예요. 설치에 관리자 권한이 필요 없는 게 정상인데, 그 폴더가 root 소유로 남아 있을 때만 이런 오류가 납니다.

EACCES: permission denied, mkdir ‘/usr/lib/node_modules/@openai/codex’

npm install -g @openai/codex가 /usr/lib/node_modules/@openai/codex 폴더를 만들다 권한 거부로 실패한 사례입니다(Frulfump, 2025-07-08, #1480).

npm 전역 설치 폴더의 소유자가 현재 사용자가 아니라서 생기는 일이에요. 예전에 sudo npm install -g로 무언가를 깔았다면 그 폴더가 root 소유로 남습니다. 전역 설치 폴더를 홈 아래로 옮기면 풀립니다.

npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH   # ~/.bashrc 같은 셸 설정에도 추가
npm install -g @openai/codex

sudo를 붙이면 당장은 설치됩니다. 하지만 그렇게 만든 root 소유 폴더가 바로 이 오류의 원인이라, 다음 설치나 업데이트에서 같은 일이 반복돼요. npm도 전역 폴더를 홈 아래로 옮기는 쪽을 권하고, 저도 그쪽을 권합니다.

The operation was rejected by your operating system

Linux에서 npm install -g @openai/codex가 “The operation was rejected by your operating system. It is likely you do not have the permissions to access this file as the current user”로 실패한 사례입니다(runujhkj, 2026-02-01, #10342).

위 EACCES와 같은 권한 문제가 다른 문구로 나온 것으로 보입니다. 위처럼 전역 설치 위치를 홈 아래로 옮기거나, 그 폴더의 소유권을 현재 사용자로 되돌리면 됩니다(chown 등).

Unable to locate Codex CLI binaries. Ensure @openai/codex is installed with optional dependencies.

Windows의 Next.js 프로젝트에서 @openai/codex-sdk를 불러 쓰다가 이 메시지와 함께 TypeError: The argument 'filename' must be a file URL object, file URL string, or absolute path string.이 찍힌 사례입니다(zy445566, 2026-04-01, #16408, Codex 0.118.0, 계획 없음으로 종료).

원인은 확정되지 않았습니다. 메시지는 선택적 의존성을 의심하라고 하지만 그것이 빠졌다는 근거는 이슈에 없고, TypeError의 경로가 파일 경로가 아니라 번들러가 붙인 모듈 식별자 형태였다는 점만 확인돼요.

보고자는 SDK의 codexPathOverride 옵션으로 실행 파일 경로를 직접 지정해 우회했습니다. 터미널에서 codex를 실행하다 이 메시지를 봤다면 상황이 다르니, codex --version이 동작하는지부터 확인하세요.

마치며

설치 자체는 정말 한 줄이었습니다. 눈여겨볼 건 그 뒤 codex doctor가 찍는 ✗와 경고였는데, 로그인 전에 뜨는 것들은 대부분 그냥 두면 되는 것들이었어요. 문서끼리 WSL 얘기가 엇갈려도 Windows 11에서는 npm 설치부터 진단까지 WSL 없이 됐고요.

설치를 마쳤다면 프로젝트 폴더에서 codex를 실행해 로그인하고, codex login status로 확인해 보세요. 로그인한 뒤 Windows에서 실제로 써 보다 401이나 모델 이름 때문에 400이 나면 Codex CLI 오류 7가지를 보시면 됩니다.

그다음으로는 Codex가 어디까지 파일을 고칠 수 있는지 정하는 Codex CLI 샌드박스 모드와 승인 정책을 권합니다. 남은 한도가 궁금하면 Codex 사용량·한도 확인이, 다른 CLI도 함께 쓴다면 AI 코딩 CLI 설치 길잡이가 출발점입니다.