name: using-codex-exec description: | Run Codex CLI non-interactive (codex exec, codex review). Trigger: 'codex exec', 'codex 실행', '비대화형 codex', 'codex review', '--yolo'. NOT for harness 동기화 (use syncing-codex-harness). NOT for claude -p (use using-claude-p).

Codex Exec 사용

Claude Code 세션 내부에서 codex exec를 정확하고 반복 가능하게 실행하는 절차를 다룬다.

작성 기준

• 확인 날짜: 2026-03-15
• 확인 버전: codex-cli 0.114.0
• 재검증: codex --version && codex exec --help && codex exec review --help

CLI 버전이 바뀌면 플래그/동작이 달라질 수 있으므로, 실행 전 도움말로 확인한다.

범위

의사결정 트리

codex exec 실행이 필요한가?
│
├─ 코드 리뷰인가?
│  ├─ YES → 커스텀 리뷰 지시가 필요한가?
│  │  ├─ YES ─────────────────────────────────────────────┐
│  │  │  ⚠️ review에서 PROMPT과 scope flag                 │
│  │  │  동시 사용 불가 (Known Issue #7825)                 │
│  │  │                                                    │
│  │  │  방법 A: AGENTS.md에 리뷰 지시 배치 후              │
│  │  │         review --base/--uncommitted 실행           │
│  │  │         (영구 지시, review의 diff 스코핑 유지)       │
│  │  │                                                    │
│  │  │  방법 B: codex exec에 diff + 지시를                 │
│  │  │         프롬프트로 직접 전달 (review 서브커맨드 미사용)│
│  │  │         (1회성 지시, 가장 유연)                      │
│  │  │                                                    │
│  │  │  → references/patterns.md 패턴 3, 4 참조           │
│  │  └──────────────────────────────────────────────────┘
│  │
│  └─ NO → codex exec review + scope flag
│          → references/patterns.md 패턴 2 참조
│
├─ 세션 재개인가?
│  └─ YES → codex exec resume --last 또는 <session-id>
│           ⚠️ --ephemeral 세션은 resume 불가
│
└─ 일반 실행 → codex exec --full-auto [-o result.md]
               → references/patterns.md 패턴 1 참조

명령 alias

호환성 매트릭스

exec 전용 플래그 (review 미지원)

review 전용 플래그

exec · review 공통 플래그

⚠️ review 상호 배타 규칙

다음 4개 인자는 모두 상호 배타적 — 한 번에 하나만 사용 가능:

위반 시 에러:

error: the argument '[PROMPT]' cannot be used with '--base <BRANCH>'
error: the argument '--base <BRANCH>' cannot be used with '--uncommitted'

근본 원인과 상세 분석: references/known-issues.md §1

입력 방법

표준 실행 절차

일반 exec

프롬프트를 파일로 작성하고, stdin 파이프로 전달하며, -o로 결과를 저장한다:

cat > /tmp/prompt.md <<'PROMPT'
이 변경의 배포 리스크를 3개 이내로 지적한다.
PROMPT

cat /tmp/prompt.md | codex exec --full-auto -o /tmp/result.md 2>&1

인라인 프롬프트도 가능하다 (짧은 질의에 한해):

codex exec --full-auto "git diff 기준으로 회귀 가능성 한 줄 요약"

코드 리뷰 — scope flag만 사용 (커스텀 지시 불필요)

codex exec review --base main --full-auto > /tmp/review.md 2>&1
codex exec review --uncommitted --full-auto > /tmp/review.md 2>&1
codex exec review --commit <sha> --full-auto > /tmp/review.md 2>&1

review 결과를 파일 저장하려면 stdout 리다이렉트(> file 2>&1)를 사용한다. -o는 review --help에 표시되지만 upstream bug(#12502)로 빈 파일을 생성한다.

코드 리뷰 — 커스텀 지시 필요

PROMPT과 scope flag이 상호 배타이므로, 두 가지 대안 중 선택한다:

방법 A — AGENTS.md 활용 (영구 지시, review diff 스코핑 유지)

프로젝트 AGENTS.md 또는 ~/.codex/AGENTS.override.md에 리뷰 정책을 배치한 뒤, scope flag으로 review를 실행하면 지시가 자동 적용된다. (지시 파일 우선순위: references/patterns.md 패턴 3 참조)

방법 B — exec 우회 (1회성 지시, 최대 유연성)

codex exec (review 미사용)에 git diff 출력과 커스텀 지시를 프롬프트로 직접 전달한다. -o로 결과 저장이 가능하고, 프롬프트 내용을 자유롭게 구성할 수 있다.

상세 명령과 예제: references/patterns.md 패턴 3, 4

세션 재개

codex exec resume --last          # 마지막 세션 재개
codex exec resume <session-id>    # 특정 세션 재개
codex exec resume --last --all    # cwd 필터 해제하여 전체 세션 중 최신 재개

⚠️ --ephemeral 세션은 파일이 저장되지 않으므로 resume 불가. No saved session found 에러 발생.

Gotchas

1. --search는 exec에서 미동작: error: unexpected argument '--search' found. 대안: -c web_search=live
2. --full-auto는 --sandbox를 묵묵히 override: -s read-only 명시해도 workspace-write로 강제됨
3. CODEX_API_KEY는 exec 전용: interactive TUI와 VS Code extension에서는 무시됨. OPENAI_API_KEY는 auth 체인에 미참여 (TUI prefill 전용). 우선순위: CODEX_API_KEY > ephemeral tokens > auth.json (상세: known-issues.md 워크트리 참고)
4. ephemeral 세션 resume 불가: --ephemeral으로 실행한 세션은 파일 미저장되어 No saved session found 에러 발생
5. codex review (top-level) vs codex exec review: 전자는 -m, --full-auto, --json, -o 등 미지원. 비대화형 자동화에는 반드시 codex exec review 사용
6. Bash tool sandbox에서 & + $! 미작동: Claude Code의 Bash tool에서 background process PID 캡처($!)가 리터럴 문자열로 반환됨. shell-level 병렬 대신 8개 병렬 Bash tool 호출 (LLM 블로킹 방지 시 run_in_background: true) + "$(cat file)" 인라인 인자를 사용한다. 상세: known-issues.md §11

모델 사용 원칙

• 기본 모델: ~/.codex/config.toml의 model 값을 따른다.
• 리뷰 전용 모델: review_model 설정으로 분리 가능하다.
• 실무 원칙:
  1. -m을 생략하고 기본 모델을 사용한다.
  2. model is not supported 오류 시 -m을 제거하고 재시도한다.
  3. 모델명을 매번 다르게 혼용하지 않는다.

운영 체크리스트

실행 전:

• codex --version으로 기대 버전 확인
• pwd가 대상 저장소 루트인지 확인
• 프롬프트 파일 경로와 결과 파일 경로를 분리

실행 후:

• 결과 파일 생성 여부 확인 (-o 또는 리다이렉트)
• 빈 결과 시 stderr 로그부터 확인
• 다음 라운드 입력에 반영할 액션 항목만 추출

하지 말아야 할 패턴

참조

• 상황별 실행 패턴: references/patterns.md
• 제한사항/트러블슈팅: references/known-issues.md

문서와 CLI 동작이 다를 때는 CLAUDE.md의 "스킬 문서 불일치 시 행동 원칙"을 따른다. codex exec --help / codex exec review --help 출력이 이 문서보다 항상 우선하는 진실 원천이다.