한 줄 정의

Codex CLI는 OpenAI의 Codex를 터미널 CLI에서 쓰는 코딩 에이전트 도구야. 공식 문서 기준으로 선택한 디렉터리의 코드를 읽고, 파일을 바꾸고, 명령을 실행할 수 있어.

Codex CLI는 범위부터 좁혀서 읽어야 해. Codex 전체 제품군에는 앱, IDE extension, cloud task가 섞여 있지만, Codex CLI는 개발자가 터미널에서 켜고 로컬 작업 디렉터리 안에서 다루는 클라이언트야. 그래서 Claude Code와 비교할 때도 “어느 모델이 더 좋나”보다 “우리 저장소에서 어떤 권한과 로그를 허용할 수 있나”를 먼저 봐야 해.

실제로 무엇을 하나

설치는 npm i -g @openai/codex로 시작하고, 실행은 터미널에서 codex를 입력해. 첫 실행 때는 ChatGPT 계정이나 API 키로 인증해. macOS, Windows, Linux를 지원하고, Windows에서는 PowerShell의 Windows 샌드박스나 WSL2 흐름을 고를 수 있어.

작업 권한은 승인 모드에서 갈려. 이 3가지를 먼저 나눠야 같은 Codex CLI라도 보안 검토 도구인지, 자동 수정 도구인지, 위험한 전체 권한 실행인지 구분할 수 있어.

  • Auto: 기본값이야. 작업 디렉터리 안의 파일 읽기, 수정, 명령 실행을 허용해.
  • Read-only: 파일을 읽고 계획을 세우는 쪽에 가까워. 보안 심사나 첫 검토에 맞아.
  • Full Access: 네트워크와 더 넓은 머신 접근까지 열 수 있어. 신뢰한 저장소와 격리된 환경에서만 후보가 돼.

반복 작업에는 codex exec가 붙어. 대화형 TUI를 열지 않고 스크립트나 CI에서 실행할 수 있고, 기본은 read-only 샌드박스야. 실제 수정을 맡기려면 codex exec --sandbox workspace-write "작업 지시"처럼 권한을 좁게 열어야 해. danger-full-access는 격리한 CI runner나 컨테이너처럼 통제된 곳에서만 후보가 돼.

외부 문서나 도구를 붙일 때는 MCP를 쓸 수 있어. Codex는 CLI와 IDE extension에서 MCP 서버를 지원하고, 기본 설정은 ~/.codex/config.toml, 신뢰한 프로젝트에서는 .codex/config.toml에도 둘 수 있어. 이 설정에는 환경 변수와 토큰이 들어갈 수 있으니, 저장소에 들어가도 되는 값과 로컬에만 남겨야 하는 값을 먼저 나눠야 해.

왜 중요한가

Codex CLI는 단순한 코드 추천기가 아니라 로컬 파일과 셸 명령을 만지는 작업 표면이야. 도입하면 생산성보다 먼저 권한 설계가 따라와. 누가 Auto를 쓸 수 있는지, Read-only 검토를 언제 거칠지, workspace-write 자동화를 CI에 올려도 되는지 같은 규칙이 없으면 편한 만큼 실수 범위도 넓어져.

Claude Code 대체 논의에서도 판단은 여기서 갈려. Reddit의 r/LocalLLaMA 글들은 Claude Code처럼 터미널, 파일 접근, 에이전트 실행감을 주는 대안을 찾는 수요를 보여줘. 하지만 그런 글은 제품 사실이나 성능 결론이 아니라 커뮤니티 신호에 가까워. 실제 판단은 자기 저장소에서 승인 대기 횟수, 테스트 통과율, 리뷰에서 되돌린 diff 비율을 재야 해.

비용도 도입 판단을 바꿔. Codex Pricing 문서 기준으로는 세 경로를 따로 봐야 해.

  • Plus: $20/month로 CLI, IDE extension, web, iOS의 Codex를 포함해. 개인 실험이나 작은 파일럿에 먼저 맞아.
  • Pro: from $100/month라서 더 긴 코딩 세션이나 개인 고강도 사용을 볼 때 비교 대상이 돼.
  • API Key: 공유 CI 자동화에는 깔끔하지만 GitHub code review나 Slack 같은 cloud 기능은 포함하지 않아.

개인 실험, 팀 CI, 조직 감사 로그가 필요한 배포 전 검토를 같은 플랜처럼 묶으면 바로 헷갈려. Enterprise 감사 로그나 사용량 모니터링이 필요한 팀은 개인 플랜 숫자만 보고 결정하면 안 돼.

언제 쓰나 / 언제 보류하나

Codex CLI는 터미널 중심으로 일하고, git diff와 테스트로 변경을 되돌릴 수 있는 팀에 먼저 맞아. 릴리스 노트 초안, 실패 로그 요약, 반복 리팩터링 후보 탐색, PR 전 정적 점검처럼 입력과 확인 절차가 뚜렷한 일은 codex exec로 작게 시험하기 좋아.

모델 선택은 작업 크기에 맞춰 보면 돼. OpenAI 문서는 대부분의 Codex 작업에서 GPT-5.5를 먼저 보라고 안내하고, 계정에 보이지 않으면 GPT-5.4를 쓰라고 해. gpt-5.4-mini는 가벼운 코딩 작업이나 하위 에이전트처럼 빠른 반복이 중요한 경우에 어울려. API 키 인증에서는 최신 모델 접근이 늦을 수 있으니, “어떤 모델을 쓸 수 있나”와 “어떤 인증 방식으로 돌리나”를 같이 확인해야 해.

보류해야 할 때도 분명해. 작업 디렉터리 밖 접근 요청이 반복되거나, 비밀키가 섞인 로컬 환경에서 MCP 서버를 많이 붙이거나, Full Access가 필요하다는 말이 먼저 나오면 Read-only부터 다시 시작하는 편이 안전해. 조직 차원의 감사 로그와 사용량 모니터링이 필수라면 Enterprise 쪽 기능을 확인하기 전까지 운영 도입은 늦추는 게 맞아.

비교할 때 헷갈리기 쉬운 점

Benchmark는 선택을 돕지만 결론을 대신하지 않아. Terminal-Bench 공식 페이지는 2.0을 89개 과제로, 1.0을 80개 과제로 보여줘. 또 3.0은 in progress 상태야. 이 숫자는 터미널 에이전트 평가 범위를 알려줄 뿐, Codex CLI가 어떤 팀의 저장소에서 Claude Code보다 낫다는 증거는 아니야.

Reddit의 Kimi K2.6 대체 논의도 비슷해. 어떤 사용자는 Opus 대체 가능성을 말하고, 다른 댓글은 로컬 실행 비용과 속도를 문제 삼아. 이건 “사람들이 대체재를 찾고 있다”는 신호로는 쓸 수 있지만, Codex CLI의 지원 OS, 승인 모드, 가격, 모델 접근 같은 제품 사실은 OpenAI 공식 문서에서 다시 확인해야 해.

자주 생기는 오해는 Codex CLI와 Codex를 같은 말로 쓰는 거야. Codex는 더 넓은 코딩 에이전트 제품군이고, Codex CLI는 그중 터미널 표면이야. 설치 명령, codex exec, 승인 모드, 로컬 설정 파일을 이야기할 때는 Codex CLI로 범위를 좁혀야 판단이 흐려지지 않아.