빠른 흐름
npm i -g @openai/codex
codex
npm i -g @openai/codex@latest설치와 실행
CLI는 현재 터미널의 작업 디렉터리에서 동작한다
Codex CLI는 로컬 터미널에서 실행하는 coding agent입니다. 실행한 디렉터리를 기준으로 파일을 읽고, 설정된 권한 안에서 파일 수정과 명령 실행을 수행합니다. 따라서 설치보다 먼저 중요한 것은 "어느 디렉터리에서 codex를 시작하는가"입니다. 저장소 루트에서 시작하면 AGENTS.md, Git 상태, 테스트 명령을 함께 읽기 쉽습니다.
cd my-repo
codex잘못된 상위 디렉터리에서 실행하면 sandbox 범위가 불필요하게 넓어지고, 하위 디렉터리에서 실행하면 필요한 설정 파일이나 패키지 루트를 놓칠 수 있습니다.
설치 방식은 팀 환경에 맞춰 고정한다
공식 문서는 npm 설치와 플랫폼별 설치 방식을 제공합니다. 팀에서 Node.js 기반 도구를 이미 쓰고 있다면 npm 전역 설치가 가장 단순합니다. macOS 팀은 Homebrew, Windows 팀은 PowerShell 설치 스크립트나 npm 설치를 검토할 수 있습니다. 중요한 것은 각 개발자가 다른 설치 경로를 임의로 섞지 않도록 팀 문서에 기준을 남기는 것입니다.
# npm
npm i -g @openai/codex
# upgrade
npm i -g @openai/codex@latestCodex CLI는 버전이 자주 갱신될 수 있으므로, 문제 재현 시에는 codex --version 같은 버전 확인 결과를 함께 남기는 편이 좋습니다.
인증은 ChatGPT 계정과 API key 흐름을 구분한다
처음 codex를 실행하면 로그인 흐름을 거칩니다. 일반 사용자는 ChatGPT 계정으로 로그인해 자신의 플랜에 포함된 Codex 사용량을 쓰는 흐름이 자연스럽습니다. API key 방식은 별도 개발자 플랫폼 설정과 비용 경계를 갖기 때문에 팀 자동화나 API 기반 실행에서 더 명확합니다.
인증 선택
- 개인/팀 플랜 기반 사용: ChatGPT 계정 로그인
- CI, 자동화, 분리 과금: API key 기반 설정공유 머신에서는 작업 후 로그아웃과 local credential 정리를 명확히 해야 합니다. 특히 회의실 PC나 임시 VM에서 로그인한 경우 세션이 남지 않도록 확인합니다.
운영 기준
| 상황 | 먼저 확인할 것 |
|---|---|
| 처음 설치 | npm i -g @openai/codex 또는 팀 기준 설치 방식 |
| 작업 시작 | 저장소 루트에서 codex 실행 |
| 버전 이슈 재현 | CLI 버전과 changelog 확인 |
| 개인 작업 | ChatGPT 계정 로그인 |
| 자동화·분리 과금 | API key 설정 |
| 공유 장비 사용 | 로그아웃과 credential 정리 |
주의할 점
설치 명령만 맞아도 실행 위치가 틀리면 작업 범위가 흔들립니다. Codex CLI는 현재 디렉터리를 기준으로 저장소를 읽고 명령을 실행하므로, 항상 의도한 프로젝트 루트에서 시작하고 권한 설정을 먼저 확인하는 편이 안전합니다.
CLI 업그레이드는 기능 개선과 동작 변경을 함께 가져올 수 있습니다. 팀 단위로 쓰는 경우에는 "항상 latest"보다 검증된 버전을 기준으로 맞추고, 특정 문제를 확인할 때만 최신 버전으로 재현하는 방식이 관리하기 쉽습니다.
참고 링크
3 sources