codex-cli

# OpenAI Codex CLI OpenAI 의 코딩 에이전트 CLI(`codex`)를 Claude Code 세션 안에서 안전하게 호출하기 위한 스킬. (참고: codex-cli 0.128 / 2026-04 기준) Codex CLI 는 Claude Code 와 같은 결의 코딩 에이전트지만 모델이 OpenAI(이 빌드 기본은 `gpt-5.5`, 또는 `--oss` 로컬) 라는 점이 핵심 차이. 이 스킬은 주로 **`codex exec` 비대화형 호출**을 통해 Claude 가 자신의 작업에 OpenAI 시각을 더하거나, 독립 작업을 위임할 때 쓴다. **중요한 동작 원리.** `codex exec` 는 비대화형이므로 승인(approval) 개념 자체가 없다. 모든 명령은 자동으로 시도되고, 위험성은 오직 `--sandbox` 정책으로만 제어한다. 따라서 인터랙티브 `codex` 의 `--ask-for-approval` 플래그는 `codex exec` 에서 **에러**를 낸다. 이 스킬의 모든 예제는 이 점을 반영한다. ## 언제 쓰는가 - **두 번째 의견(second opinion)**. 중요한 설계·디버깅 결정에 OpenAI 모델의 독립 분석을 받고 싶을 때 - **병렬 위임**. 메인 컨텍스트를 보호하면서 Codex 에 별개 하위 작업(빌드 검증, 리팩터 초안 등)을 시킬 때 - **코드 리뷰**. `codex review` 로 브랜치/커밋/언커밋 변경을 비대화형 리뷰 - **JSON 자동화**. `--json --output-last-message` 조합으로 결과를 파일·파이프라인에 흘려보낼 때 - **MCP 동기화**. Codex 에 MCP 서버를 등록·관리해 도구 풀을 확장할 때 대화형 TUI(`codex` 인자 없이) 자체는 사람이 직접 다루는 모드라, 에이전트 입장에서는 거의 항상 `codex exec` 를 쓴다. ## 사전 점검 (호출 전 1회) ```bash codex --version # 설치 확인 codex login status # 인증 상태 (logged in 이면 OK) ``` `codex login status` 가 실패하면 사용자에게 다음 중 하나를 안내한다. ```bash codex login # ChatGPT OAuth (권장) codex login --device-auth # 헤드리스 환경 printenv OPENAI_API_KEY | codex login --with-api-key # API 키 사용 ``` API 키 모드는 사용량이 OpenAI Platform 결제로 계산되므로 ChatGPT Plus/Pro/Team 구독자라면 OAuth 로그인이 비용상 유리하다. ## 핵심 패턴: `codex exec` 기본 골격. ```bash codex exec [OPTIONS] "프롬프트" ``` 작은 작업이라도 Claude 가 호출할 때는 **항상 비대화형 옵션을 명시**한다. 그렇지 않으면 TUI 가 떠서 세션이 멈춘다. ### 1) 안전한 읽기 전용 호출 (분석·리뷰) ```bash codex exec \ --sandbox read-only \ --skip-git-repo-check \ --output-last-message /tmp/codex-out.md \ "이 디렉토리의 src/auth/*.ts 파일을 읽고 잠재적 보안 취약점을 마크다운 표로 정리해라" ``` `read-only` 샌드박스는 부작용이 없어 자동화의 가장 안전한 기본값이다. 결과물은 `--output-last-message` 로 받는 게 확실하다(stdout 에는 헤더·진행 로그·토큰 사용량이 섞인다). ### 2) 워크스페이스 쓰기 호출 (패치 생성) ```bash codex exec \ --sandbox workspace-write \ --cd /path/to/repo \ --output-last-message /tmp/codex-patch.md \ "tests/integration/login.spec.ts 에서 401 케이스가 빠져 있다. 추가하고 npm test 로 통과시켜라" ``` `workspace-write` 는 작업 루트(또는 `--cd`)와 `--add-dir` 로 추가한 디렉토리에만 쓰기를 허용한다. 비대화형이라 사람에게 묻지 않으므로, 결과를 사용자에게 다시 보여 주고 검토받는 흐름을 유지하라. ### 3) JSONL 이벤트 스트림 (파이프라인 통합) ```bash codex exec \ --json \ --sandbox read-only \ --output-last-message /tmp/last.txt \ "package.json 의 의존성을 분석해 outdated 한 것만 JSON 배열로 알려줘" \ > /tmp/codex.jsonl ``` `--json` 은 줄 단위 JSON 이벤트(시작·도구 호출·메시지·완료)를 stdout 에 흘리고, `--output-last-message` 는 모델 최종 답만 별도 파일로 떨어뜨린다. CI 자동화에서는 둘을 함께 쓴다. ### 4) 출력 스키마 강제 ```bash codex exec \ --output-schema /tmp/schema.json \ --output-last-message /tmp/result.json \ --sandbox read-only \ "이 README 에서 설치 명령어들을 추출해 schema 에 맞춰 JSON 으로 반환" ``` `--output-schema` 에 JSON Schema 파일 경로를 주면 최종 응답이 그 형태로 검증된다. 표/엔터티 추출 같은 구조화 작업에 쓴다. ### 5) stdin 으로 큰 컨텍스트 전달 ```bash git diff main..HEAD | codex exec \ --sandbox read-only \ -o /tmp/review.md \ "표준 입력으로 들어온 diff 를 리뷰해라. 위험·개선·테스트 가능성 순으로 정리" ``` PROMPT 인자에 `-` 만 주거나 인자를 생략하면 stdin 전체가 프롬프트가 된다. PROMPT 와 stdin 을 동시에 주면 stdin 이 `<stdin>` 블록으로 덧붙는다. ### 6) 이미지 첨부 ```bash codex exec -i screenshot.png \ --sandbox read-only \ -o /tmp/codex-out.md \ "이 스크린샷의 UI 구조를 React 컴포넌트 트리로 표현해줘" ``` `-i` 는 반복 가능. PNG/JPG/WebP 등을 멀티 첨부할 수 있다. ## 샌드박스 정책 가이드 | Sandbox | 적합한 상황 | |---------|-------------| | `read-only` | 분석·문서화·리뷰. **에이전트 호출 기본값.** | | `workspace-write` | 자동화된 패치 생성. 작업 루트·`--add-dir` 만 쓰기 가능. | | `danger-full-access` | 사용 금지 — 사용자의 명시 요청 + 격리 환경에서만. | `--dangerously-bypass-approvals-and-sandbox`(별칭 `--yolo`)는 격리된 컨테이너 외부에서는 절대 쓰지 않는다. > **인터랙티브 `codex` 는 다르다.** TUI 모드에서만 `-a, --ask-for-approval <untrusted|on-request|never>` 가 의미를 가진다. `codex exec` 에 같은 플래그를 주면 즉시 에러로 종료하므로 절대 섞지 말 것. ## 모델 / 프로파일 선택 ```bash codex exec -m gpt-5.5 "..." # 모델 직접 지정 codex exec -p review "..." # ~/.codex/config.toml 의 [profiles.review] 사용 codex exec --oss --local-provider ollama -m gpt-oss:20b "..." # 로컬 OSS 모델 ``` 기본 모델은 ChatGPT 계정 플랜과 `~/.codex/config.toml` 의 `model =` 설정에 따른다 (이 빌드 기본 `gpt-5.5`). 모델 카탈로그는 `codex debug models` 로 확인. `-c model_reasoning_effort=high` 같은 인라인 오버라이드도 동일 효과. ## 두 번째 의견(second opinion) 패턴 Claude 의 분석을 그대로 두고, 같은 입력을 OpenAI 에 한 번 더 돌려 비교하는 구조. ```bash # 1) Claude 가 결론을 적어 둔 메모 echo "## Claude 결론\n$CLAUDE_CONCLUSION" > /tmp/handoff.md echo "## 원본 컨텍스트" >> /tmp/handoff.md cat path/to/relevant.ts >> /tmp/handoff.md # 2) Codex 에 독립 판단 요청 codex exec \ --sandbox read-only \ -o /tmp/codex-opinion.md \ "$(cat /tmp/handoff.md)\n\n위 결론에 동의하는지, 놓친 부분은 없는지 독립적으로 판단해 마크다운으로 답해라." ``` 핵심은 Claude 의 결론을 같이 넘기되 "독립적으로" 판단하라고 명시하는 것. 동일 모델 반복보다 가짜 합의(echo chamber)를 줄인다. ## 코드 리뷰: `codex review` 브랜치/커밋/언커밋 단위로 리뷰만 돌리는 전용 서브커맨드. `codex exec` 와 달리 리뷰 포맷이 정형화돼 있다. ```bash codex review --base main # main 대비 현재 브랜치 codex review --uncommitted # 스테이징·언스테이징·언트랙 codex review --commit abc1234 # 특정 커밋 codex review --base main --title "Auth refactor" # 요약 헤더용 제목 codex review - # stdin 으로 커스텀 지시 받기 ``` `-c model="..."`, `--enable`/`--disable` 같은 글로벌 플래그도 동일하게 받는다. 결과는 stdout 으로 흘러나오므로 `tee` 로 저장한다. ## 세션 재개·포크 ```bash codex resume --last # 가장 최근 인터랙티브 세션 재개 (TUI) codex resume --all # 모든 디렉토리의 세션 중 선택 codex exec resume --last "추가 지시" # 비대화형으로 마지막 exec 세션 이어가기 codex fork --last # 분기 (원본 보존) ``` `codex exec` 도 기본적으로 세션을 디스크에 남긴다. 일회성이라면 `--ephemeral` 로 비활성화. ## MCP 서버 관리 ```bash codex mcp list codex mcp add my-tool -- node mcp-server.js # stdio 서버 codex mcp add web-tool --url https://mcp.example.com # HTTP 서버 codex mcp add github --url https://api.githubcopilot.com/mcp \ --bearer-token-env-var GITHUB_TOKEN codex mcp get my-tool --json codex mcp login web-tool --scopes "read:repo,write:repo" codex mcp remove my-tool ``` Claude Code 의 `claude mcp` 와 별개로, Codex 자신이 사용하는 MCP 풀을 관리한다. 같은 서버를 두 CLI 가 공유하려면 양쪽에 각각 등록한다. Codex 자체를 MCP 서버로 띄우려면(다른 에이전트의 도구로 노출): ```bash codex mcp-server # stdio 기반. 호출 측 MCP 클라이언트가 spawn ``` ## 자주 쓰는 글로벌 옵션 | 플래그 | 효과 | |--------|------| | `-c key=value` | `~/.codex/config.toml` 값을 임시 오버라이드. 값은 TOML 로 파싱 (실패 시 문자열). 예: `-c model="gpt-5.4-high" -c 'sandbox_permissions=["disk-full-read-access"]'` | | `--enable <feature>` / `--disable <feature>` | 피처 플래그 토글. `codex features list` 로 목록 확인 | | `-C, --cd <DIR>` | 작업 루트 변경 | | `--add-dir <DIR>` | `workspace-write` 에서 추가로 쓰기 가능한 디렉토리 | | `--skip-git-repo-check` | Git 리포지토리 밖에서도 실행 | | `--ignore-user-config` | `config.toml` 무시 (재현성 보장) | | `--ignore-rules` | 사용자/프로젝트 execpolicy `.rules` 무시 | | `--search` | `web_search` 툴 활성화 (라이브 검색) | 전체 플래그·서브커맨드 목록은 `references/cli-reference.md` 참고. ## 비용·속도 가이드 - 단발성 분석은 `--sandbox read-only` + 짧은 프롬프트가 가장 저렴·빠름 - 큰 컨텍스트는 stdin 으로 흘려라(인자 길이 제한·이스케이프 회피) - 동일 작업을 반복할 거라면 `~/.codex/config.toml` 에 프로파일 정의하고 `-p name` 으로 호출 — 인자 노이즈 감소 - 매 호출마다 세션이 디스크에 남는다. 일회성·민감 데이터는 `--ephemeral` ## 안티패턴 - **TUI 모드 호출**. 인자 없는 `codex` 또는 `codex "..."`(서브커맨드 없이)는 풀스크린 TUI. 자동화에서 절대 쓰지 말 것 — 항상 `codex exec` 로 시작. - **`codex exec` 에 `--ask-for-approval` 부착**. 비대화형엔 승인 개념이 없어 즉시 에러로 종료한다. 인터랙티브 `codex` 전용 옵션이다. - **`--yolo`/`-c sandbox=danger-full-access`**. 사용자의 명시 동의 없이 절대 사용 금지. - **stdout 만으로 결과 파싱**. 진행 이벤트가 섞여 들어온다. `--output-last-message` 로 최종 메시지만 파일 캡처. - **장시간 작업을 포그라운드로**. 5분 이상 걸릴 작업은 Bash `run_in_background: true` 와 결합하고, 완료 알림으로 결과 파일을 읽는다. - **민감 정보 로그 남김**. 기본 세션은 `~/.codex/sessions/` 에 저장된다. 비밀 데이터는 `--ephemeral` 또는 사용자 동의 후 삭제. ## 트러블슈팅 - `not logged in` → `codex login status` 후 위 로그인 명령 중 택일 - `not in a git repository` → `--skip-git-repo-check` - `unexpected argument '--ask-for-approval'` → `codex exec` 에 인터랙티브 전용 플래그를 줬다. 빼고 `--sandbox` 만 사용. - TUI 가 떠서 멈춤 → `codex exec` 가 아닌 `codex` 로 호출했는지 확인 - 출력이 어디 갔는지 모를 때 → `--json` 으로 이벤트 스트림 확인 + `--output-last-message` 로 최종 답 분리 - `workspace-write` 인데 권한 거부 → 파일이 작업 루트 밖. `--add-dir` 또는 `--cd` 로 루트 변경 - 모델·플랜 한도 초과 → `-m` 으로 다른 모델 지정, 또는 `--oss` + 로컬 모델 ## 확장 레퍼런스 - `references/cli-reference.md` — 전체 서브커맨드·플래그·예제 (exec / review / resume / fork / login / mcp / sandbox / features / cloud / app-server / debug 등)