TL;DR
- OpenAI Codex CLI는
npm install -g @openai/codex한 줄로 설치, GPT-5.5를 백엔드로 쓰는 터미널 코딩 에이전트다. - 서브커맨드 20개 + 슬래시 커맨드 21개 + 글로벌 플래그 15개 + exec 전용 플래그 8개 = 73개 명령어 체계를 갖춘다.
- Claude Code와 경쟁 구도지만 역할이 다르다 — CI/자율 에이전트는 Codex, 대형 컨텍스트·IDE 통합은 Claude Code.
Claude Code vs Codex CLI: 무엇을 써야 하나
| 기준 | Claude Code | Codex CLI |
|---|---|---|
| 컨텍스트 윈도우 | 1M 토큰 | 400K 토큰 |
| CI/자율 에이전트 | 가능하나 설정 필요 | codex exec 네이티브 |
| 내장 샌드박스 | 없음 (외부 의존) | ✅ 3단계 정책 |
| IDE 통합 | VS Code, JetBrains 플러그인 | 터미널 중심 |
| 모델 | Claude Sonnet/Opus 4.x | GPT-5.5 / GPT-5.3-Spark |
| 로컬 OSS 모델 | 미지원 | --oss (Ollama 연동) |
2026년 5월 기준, AI 코딩 에이전트 선택지는 사실상 두 개로 좁혀졌다. 둘을 비교하기 전에 포지셔닝을 먼저 정리하자.
Codex는 처음엔 GPT-2 시대의 코드 특화 모델 이름이었다. 지금은 다르다. GPT-5.4부터 코딩 특화 로직이 GPT 범용 모델에 통합됐고, Codex CLI는 GPT-5.5를 백엔드로 돌리는 터미널 에이전트 프레임워크가 됐다.
핵심 차이 하나: 컨텍스트 윈도우. Claude Sonnet 4.6는 1M 토큰, Codex(GPT-5.x)는 400K 토큰이다. 대형 모노레포에서 전체 소스를 올리는 분석 작업이라면 Claude Code가 명확하게 앞선다.
그럼에도 Codex가 유의미한 이유는 두 가지다.
① codex exec — CI/자율 실행 최적화: 비대화형 실행 모드는 GitHub Actions에 바로 붙는다. --json 플래그로 줄 구분 JSON 이벤트를 파이프하면 CI 로그 파싱이 깔끔해진다.
② 내장 샌드박스: 별도 설정 없이 --sandbox workspace-write 한 줄로 파일시스템 격리가 된다. Claude Code에서 이 수준의 격리를 구현하려면 Docker나 devcontainer를 직접 구성해야 한다.
설치 & 첫 실행
# npm (Node 18+ 필요)
npm install -g @openai/codex
# macOS Homebrew
brew install --cask codex
# zsh 자동완성 활성화
codex completion zsh >> ~/.zshrc && source ~/.zshrc
# 인증
codex login # OAuth / 디바이스 플로우 / API 키
codex login status # 인증 상태 확인
# 인터랙티브 시작
codex
토스, 카카오, 네이버처럼 사내 Git 서버를 사용하는 환경이라면 --cd로 워크스페이스를 지정하고 --add-dir로 공유 라이브러리 디렉터리의 쓰기 권한을 부여한다.
codex --cd /home/user/my-service --add-dir /shared/libs
73개 명령어 체계: 카테고리별 완전 정복
1. 세션 관리 (5개)
codex # 인터랙티브 TUI 시작
codex resume [SESSION_ID] # 이전 세션 재개
codex fork [SESSION_ID] # 세션 브랜치 (트랜스크립트 보존)
codex exec "태스크 설명" # 비대화형 실행 (CI용)
codex exec resume [ID] # 이전 비대화형 세션 재개
2. 클라우드 태스크 (3개)
codex cloud "PR 리뷰해줘" # 클라우드 태스크 생성/관리
codex cloud list # 최근 태스크 목록 (필터/페이지네이션)
codex apply TASK_ID # 클라우드 태스크 diff를 로컬에 적용
codex cloud는 밤새 돌리는 대규모 리팩터링에 특히 유용하다. 터미널을 닫아도 클라우드에서 실행이 계속되고, 다음 날 codex apply로 결과를 당겨온다.
3. 인증 (3개)
codex login # OAuth / 디바이스 플로우 / API 키 인증
codex login status # 인증 상태 확인
codex logout # 자격증명 삭제
4. MCP 서버 관리 (4개)
codex mcp # MCP 서버 관리 (list/add/remove/authenticate)
codex mcp-server # Codex를 MCP 서버로 stdio 실행
codex plugin marketplace # 플러그인 마켓플레이스
config.toml에서 GitHub, Jira, Slack 등 내부 시스템을 MCP로 연결할 수 있다.
# ~/.config/codex/config.toml
[mcp.servers.github]
type = "stdio"
command = "gh-mcp-server"
5. 데스크탑 & 앱서버 (2개)
codex app [PATH] # Codex Desktop 실행 (macOS/Windows)
codex app-server # 로컬 앱서버 실행 (WebSocket 원격 연결용)
6. 피처 플래그 (3개)
codex features list # 현재 피처 플래그 상태
codex features enable <feature> # 영구 활성화
codex features disable <feature> # 영구 비활성화
7. 유틸리티 (5개)
codex update # CLI 최신 버전 업데이트
codex sandbox # Codex 샌드박스 내 임의 명령 실행
codex completion zsh # 쉘 자동완성 생성 (bash/fish/PowerShell/elvish)
codex execpolicy # 실행 정책 사전 검증
codex debug models # 모델 카탈로그 JSON 출력
8. 글로벌 플래그 (15개)
--add-dir <path> # 추가 디렉터리 쓰기 허용
--ask-for-approval, -a <mode> # 승인 타이밍: untrusted|on-request|never
--cd, -C <path> # 실행 전 작업 디렉터리 변경
--config, -c <key=value> # 설정 오버라이드 (반복 가능)
--dangerously-bypass-approvals-and-sandbox # --yolo: 외부 샌드박스 환경 전용
--disable / --enable <feature> # 피처 플래그 강제 토글
--image, -i <path> # 이미지 파일 첨부 (스크린샷/디자인 스펙)
--model, -m <string> # 모델 오버라이드 (기본: gpt-5.5)
--no-alt-screen # TUI 대체 화면 비활성화
--oss # Ollama 연동 로컬 OSS 모델 사용
--profile, -p <string> # 설정 프로파일 선택
--remote <ws://host:port> # 원격 앱서버에 TUI 연결
--remote-auth-token-env <ENV_VAR> # 원격 인증 토큰 환경변수 지정
--sandbox, -s <policy> # read-only|workspace-write|danger-full-access
--search # 실시간 웹 검색 모드 활성화
9. codex exec 전용 플래그 (8개)
--color <always|never|auto> # ANSI 색상 제어
--ephemeral # 세션 파일 미저장 (CI 일회성 실행)
--ignore-rules # execpolicy 규칙 파일 스킵
--ignore-user-config # config.toml 스킵
--json # 줄 구분 JSON 이벤트 출력
--output-last-message, -o # 마지막 응답을 파일로 저장
--output-schema # JSON Schema로 출력 검증
--skip-git-repo-check # Git 리포 외부 실행 허용
10. 슬래시 커맨드 (21개 — TUI 내에서 / 입력)
/model 모델 전환 (gpt-5.5 ↔ gpt-5.3-spark 등)
/fast Fast 모드 토글
/permissions 승인 요구사항 조정 (Auto / Read Only 등)
/plan 구현 전 계획 모드 진입 (코드 작성 전 검토)
/goal 세션 목표 설정
/personality 커뮤니케이션 스타일 변경
/status 세션 설정 + 토큰 사용량 확인
/clear 터미널 초기화 + 새 대화 시작
/new 같은 세션 내 새 대화
/fork 현재 대화를 새 스레드로 브랜치
/side 임시 사이드 대화 (집중 질문 전용)
/resume 저장된 대화 복원
/compact 이전 대화 요약 → 컨텍스트 확보
/diff 커밋 전 Git 변경사항 리뷰
/review 코드 리뷰 워크플로우 시작
/mention 특정 파일 포커스 첨부
/copy 최신 응답 클립보드 복사 (단축키: Ctrl+O)
/init 프로젝트 초기화
/mcp MCP 서버 관리
/debug-config 설정 디버깅
/exit /quit 세션 종료
실무 패턴: GitHub Actions CI에 Codex 붙이기
PR이 열릴 때마다 Codex가 자동으로 코드 리뷰를 수행하는 패턴이다.
# .github/workflows/codex-review.yml
name: Codex PR Review
on: [pull_request]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Codex CLI
run: npm install -g @openai/codex
- name: Run Codex review
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
CODEX_HOME: /tmp/codex-home
run: |
codex exec \
--sandbox workspace-write \
--ask-for-approval never \
--json \
--output-last-message review-result.txt \
"변경된 파일을 리뷰하고 보안 취약점, 성능 이슈, 코드 스타일 위반을 JSON으로 보고해줘"
- name: Post review comment
run: |
gh pr comment ${{ github.event.pull_request.number }} \
--body "$(cat review-result.txt)"
--ask-for-approval never와 --sandbox workspace-write의 조합이 핵심이다. 승인 없이 실행하되 워크스페이스 밖엔 쓰지 못하도록 격리한다. CODEX_HOME 환경변수로 세션 파일 경로를 명시하면 러너 간 충돌을 방지할 수 있다.
주의사항
--yolo는 프로덕션에서 쓰지 마라. 공식 문서에서도 "only in hardened environments"라고 명시한다. 로컬 개발에서 속도를 위해 켜고 싶다면 반드시 Docker 컨테이너 내부에서만 사용한다.
Windows 사용자: PowerShell 네이티브 지원은 되지만, 샌드박스 기능은 WSL2 환경이 더 안정적이다. Windows Sandbox도 지원되나 설정이 복잡하다.
컨텍스트 한계: 400K 토큰은 중소규모 서비스에선 충분하지만, 카카오페이·토스 규모의 멀티-레포 전체 분석에는 부족할 수 있다. 이 경우 codex cloud로 작업을 분할하거나, 대형 컨텍스트가 필요한 분석은 Claude Code와 병행한다.
비용 0원 실험: --oss 플래그와 Ollama를 조합하면 로컬 OSS 모델로 API 비용 없이 Codex CLI 기능 전체를 테스트할 수 있다. ollama pull qwen2.5-coder:32b 후 codex --oss로 진입하면 된다.
결론: 둘 다 써라
2026년 최고의 엔지니어들은 선택하지 않는다. Claude Code와 Codex CLI를 역할에 따라 나눠 쓴다.
- Claude Code: 대형 컨텍스트 분석, IDE 통합 페어 프로그래밍, 복잡한 리팩터링
- Codex CLI: CI 자율 에이전트, PR 자동 리뷰,
codex cloud비동기 태스크
73개 명령어 체계는 처음엔 복잡해 보인다. 실무에서 자주 쓰는 건 10개 남짓이다. codex exec, --sandbox, --ask-for-approval, /plan, /diff — 이 다섯 가지를 먼저 체득하면 나머지는 자연스럽게 따라온다.
참고 자료