코덱스(Codex CLI)는 OpenAI의 터미널 AI 에이전트입니다. ChatGPT 웹의 Codex와 같은 계열이지만, 이건 내 컴퓨터에서 직접 파일을 다루는 CLI 버전입니다. 결론부터 — 설치는 아래 한 줄입니다. npm 방식에는 Node.js와 npm이 필요합니다. 여러 AI CLI를 함께 쓸 때는 Node.js 22 이상을 공통 기준으로 준비할 수 있지만, 이를 Codex의 필수 최소 버전으로 해석하면 안 됩니다.
npm install -g @openai/codex패키지 이름부터 확인하세요: npm install -g codex로 치면 안 됩니다. 스코프 없는 codex는 OpenAI 공식 Codex CLI 패키지가 아닙니다. 반드시 @openai/를 붙이세요.
설치 — 윈도우와 맥
Node.js 설치를 생략하고 싶다면 npm 대신 공식 단독 설치 스크립트를 사용할 수 있습니다. 설치 조건은 OpenAI 공식 CLI 안내를 함께 확인하세요. 윈도우 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를 선택해 브라우저에서 로그인합니다. 2026년 10월 2일 공식 안내상 Codex CLI는 Free·Go를 포함한 ChatGPT 플랜에서 사용할 수 있으며, 사용 한도는 플랜별로 다릅니다. API 키 방식은 별도 API 과금이 적용됩니다. Codex Cloud의 대상은 CLI와 다르므로 공식 이용 대상·한도 안내를 확인하세요.
기본 사용법
- 처음에는
codex --sandbox read-only --ask-for-approval on-request로 읽기 전용 설정을 선택하고 “이 연습 프로젝트의 구조만 설명해줘”라고 요청하세요. 파일 편집·명령 실행이 필요한 경우에는 권한 설정과 제안을 확인한 뒤 진행합니다. - /model — 사용할 모델을 바꿉니다. 실행 화면 상단에 현재 모델이 표시됩니다.
- 에디터에서 쓰고 싶다면 VS Code·Cursor용 확장도 있고,
codex app으로 데스크톱 앱도 열 수 있습니다.
코덱스 설치가 안 될 때
- “codex를 찾을 수 없습니다” — 터미널을 새로 연 뒤 Windows PowerShell의
Get-Command codex -All또는 macOS·Linux의command -v codex로 실제 경로를 확인하세요. 설치 실패인지 PATH 문제인지 먼저 나눕니다. - 설치 중 오류 —
node --version·npm 버전과 오류 본문을 확인하세요. 버전 외에도 권한·네트워크·PATH 문제가 있을 수 있으며, Node22 미만이라는 이유만으로 실패를 확정하지 마세요. - 설치했는데 이상한 게 실행됨 — 스코프 없는 codex 패키지를 깔았을 가능성이 큽니다. 먼저 실행 경로와
npm list -g --depth=0결과에서 패키지를 확인하세요. 원치 않는 codex 패키지임을 확인한 경우에만 제거하고@openai/codex를 설치하세요.
같이 보면 좋은 글
Claude Code·Gemini·Grok까지 8종 CLI 설치 명령을 한 번에 보려면 AI 코딩 CLI 설치 총정리를 참고하세요. 여러 에이전트를 팀처럼 굴리는 방법은 멀티에이전트 정리 글에 있습니다.
참고: @openai/codex — npm 공식 패키지
인증·작업 권한: 공식 로그인 안내 · 승인·보안 설정 안내
설치 오류는 오류 본문을 기준으로 나눕니다. 엔진 요구 메시지면 표시된 버전 조건을, EACCES·EPERM이면 설치 권한을, 다운로드 실패면 네트워크·프록시를, 바이너리 실행 오류면 지원 OS·아키텍처를 확인하세요. 로그인이 막히면 재설치보다 계정·조직의 이용 권한부터 확인합니다.
CLI로 만든 확장을 스토어에 올리실 계획이라면 — AI로 만든 크롬 확장이 웹스토어 심사에서 걸리는 지점 6가지에 권한·원격 코드·난독화처럼 코드를 짜는 단계에서 미리 잡아야 하는 항목을 정리해 뒀습니다.
관련 글: ChatGPT·Claude 대화를 옵시디언에 정리하는 법 — 옵시디언으로 옮겨 정리하는 방법
설치 후 사용할 모델을 고른다면 Opus 5.5 vs Sol 6.0 성능·가격 비교에서 코딩과 반복 업무의 차이를 확인하세요.
ChatGPT·Claude·Gemini 대화를 마크다운·PDF·옵시디언 노트로 한 번에 저장하려면 → AI Chat Exporter(PC Wise AI 운영 크롬 확장; 제공 기능·요금·데이터 처리 방식은 제품 페이지에서 확인)
답글 남기기