코덱스 설치방법 — ChatGPT Codex CLI 윈도우·맥 총정리

코덱스(Codex CLI)는 OpenAI의 터미널 AI 에이전트입니다. ChatGPT 웹의 Codex와 같은 계열이지만, 이건 내 컴퓨터에서 직접 파일을 다루는 CLI 버전입니다. 결론부터 — 설치는 아래 한 줄입니다. 단, Node.js 22 이상이 필요합니다.

npm install -g @openai/codex

가장 흔한 실패 원인부터: npm install -g codex로 치면 안 됩니다. 스코프 없는 codex는 2012년에 등록된 전혀 무관한 패키지입니다. 반드시 @openai/를 붙이세요.

설치 — 윈도우와 맥

Node.js가 없거나 버전이 낮다면(node --version으로 확인, 22 미만이면 교체) npm 대신 공식 설치 스크립트를 쓰는 게 편합니다. 윈도우 PowerShell:

irm https://chatgpt.com/codex/install.ps1 | iex

맥·리눅스:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

맥은 Homebrew도 됩니다: brew install --cask codex. 설치 확인은 codex --version.

설치 후 첫 실행 — ChatGPT 계정으로 로그인

터미널에서 codex를 입력하면 시작됩니다. 처음 실행하면 Sign in with ChatGPT를 선택해 브라우저에서 로그인합니다. ChatGPT Plus·Pro·Business·Edu·Enterprise 요금제에 포함돼 있어 별도 결제가 필요 없고, API 키 방식도 지원합니다.

기본 사용법

• 실행 후 그냥 할 일을 입력하면 됩니다 — “이 프로젝트 구조 설명해줘” 같은 식.
• /model — 사용할 모델을 바꿉니다. 실행 화면 상단에 현재 모델이 표시됩니다.
• 에디터에서 쓰고 싶다면 VS Code·Cursor용 확장도 있고, codex app으로 데스크톱 앱도 열 수 있습니다.

코덱스 설치가 안 될 때

• “codex를 찾을 수 없습니다” — 터미널 재시작(PATH 문제). 그래도 안 되면 재부팅.
• 설치 중 오류 — 십중팔구 Node 버전입니다. 22 미만이면 LTS로 재설치하세요.
• 설치했는데 이상한 게 실행됨 — 스코프 없는 codex 패키지를 깔았을 가능성이 큽니다. npm uninstall -g codex 후 @openai/codex로 다시 설치하세요.

같이 보면 좋은 글

Claude Code·Gemini·Grok까지 네 가지 CLI 설치 명령을 한 번에 보려면 AI 코딩 CLI 설치 총정리를 참고하세요. 여러 에이전트를 팀처럼 굴리는 방법은 멀티에이전트 정리 글에 있습니다.

참고: @openai/codex — npm 공식 패키지