Ch7. exec/자동화

Codex는 비대화형 실행으로 스크립트/CI 환경에서도 돌릴 수 있습니다. 리뷰, 정적 분석, 문서화 같은 반복 작업을 자동화하는 데 쓰면 됩니다.

언제 codex exec를 쓰나

• CI에서 "레포 상태 요약/리뷰/체크리스트 생성"처럼 머신이 소비할 출력이 필요할 때
• 로컬에서 반복 작업(릴리즈 노트 작성, 마이그레이션 체크 등)을 스크립트로 고정하고 싶을 때
• 장시간 세션 대신 "한 번 실행 → 결과 파일 저장" 형태로 운영하고 싶을 때

핵심 옵션(현업에서 바로 쓰는 것)

1) JSONL 이벤트 스트림(--json)

--json을 켜면 stdout이 JSON Lines(JSONL)로 흘러서, 실행 중 이벤트를 그대로 파이프라인으로 받습니다.

codex exec --json "summarize the repo structure" | jq

2) 최종 메시지만 파일로 저장(-o/--output-last-message)

최종 결과만 필요할 때는 "마지막 메시지"만 파일로 저장하는 쪽이 관리가 쉽습니다.

codex exec -o ./codex-last.md "write release notes for the last PR"

3) 스키마 강제(--output-schema)

후속 스텝이 구조화된 데이터를 요구한다면 JSON Schema를 강제하세요.

codex exec \
  --output-schema ./schema.json \
  -o ./result.json \
  "extract breaking changes and output JSON"

4) 권한/자율성 제어(--sandbox, approval policy)

• 읽기 전용(질의/요약): --sandbox read-only
• 수정 허용(자동 편집): --sandbox workspace-write와 명시적인 approval policy 조합
• full access(주의): --sandbox danger-full-access 또는 --yolo(샌드박스/승인 우회)

5) exec resume(세션 이어가기)

이전 exec 결과를 이어서 작업할 수 있습니다.

codex exec resume --last "위 결과에서 breaking change만 다시 정리해줘"

CI 운영 팁

• 키 분리: 비대화형 실행은 CODEX_API_KEY로 분리하되, untrusted repository code와 같은 job-wide env로 노출하지 않음
• 레포 체크 우회 금지(기본): Git 리포지토리 체크를 우회하는 --skip-git-repo-check는 "격리된 안전 환경"에서만 예외로 허용
• 권한은 단계적으로: 기본은 read-only로 두고, 쓰기가 필요할 때만 "작업 단위로" 올리기

GitHub Action(운영 표준화)

GitHub Actions에서 Codex를 돌릴 때는 openai/codex-action@v1을 씁니다. safety-strategy: drop-sudo를 그대로 두고, 필요한 샌드박스 모드를 명시하세요.

jobs:
  codex:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: openai/codex-action@v1
        with:
          safety-strategy: drop-sudo
          sandbox: workspace-write
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

App-Server Exec: 스트리밍 실행 (0.113.0)

0.113.0부터 codex exec가 app-server 기반 in-process 경로로 바뀌어서, 명령을 실행하면 stdin/stdout/stderr를 실시간으로 스트리밍받습니다. TTY/PTY까지 지원해 인터랙티브 프로그램과도 연동됩니다.

주요 변경점

• 스트리밍 I/O: exec가 도는 동안 stdout/stderr가 실시간으로 흐릅니다. 긴 빌드나 테스트를 돌릴 때 진행 상황을 바로 확인합니다.
• TTY/PTY 지원: 터미널 제어가 필요한 도구(예: less, top, 대화형 설치 스크립트)도 exec 안에서 씁니다.
• stdin 스트리밍: 파이프라인에서 입력을 실시간으로 흘려보내므로 복잡한 자동화 체인에 잘 맞습니다.

# 스트리밍 exec — 실시간으로 빌드 로그 확인
codex exec --json "run the full test suite" | jq --unbuffered '.content'

# stdin을 통한 데이터 전달
cat large-dataset.csv | codex exec "analyze this CSV and summarize trends"

실험적 Code Mode (0.114.0)

0.114.0에서 도입된 실험적 code mode는 코딩 작업만을 위한 격리된 워크플로우입니다. 일반 대화와 코드 편집을 갈라서, 에이전트가 코딩에만 집중하도록 환경을 좁힙니다.

특징

• 격리된 코딩 환경: 파일 편집, 테스트 실행, 빌드 등 코딩 관련 도구만 활성화
• 컨텍스트 집중: 불필요한 대화 컨텍스트를 배제하고 코드 변경에만 초점
• 자동화 친화적: CI/CD 파이프라인에서 "코드 수정만 수행" 시나리오에 최적

# code mode로 실행
codex exec --mode code "fix all TypeScript type errors in src/"

Hooks 엔진 (0.114.0 → 0.124.0)

0.114.0에서 실험적 hooks 엔진이 추가됐고, 0.124.0에서 stable로 올라섰습니다. SessionStart와 Stop 이벤트에 커스텀 로직을 걸어두면 exec 자동화의 전후 처리를 선언적으로 관리합니다.

활용 예시

• SessionStart: 환경 변수 검증, 의존성 프리로드, 감사 로그 시작
• Stop: 결과 요약 저장, 알림 발송, 리소스 정리

[features]
codex_hooks = true

[[hooks.SessionStart]]
matcher = "startup|resume"

[[hooks.SessionStart.hooks]]
type = "command"
command = "echo 'Codex session started' >> /var/log/codex-audit.log"

[[hooks.Stop]]

[[hooks.Stop.hooks]]
type = "command"
command = "curl -X POST https://slack.webhook/... -d '{\"text\": \"Codex 작업 완료\"}'"

App-Server Filesystem RPCs + Python SDK (0.115.0)

0.115.0에서 app-server에 파일시스템 RPC(읽기/쓰기/복사)가 추가되었으며, 새로운 Python SDK가 출시됐습니다.

주요 변경점

• Filesystem RPCs: file/read, file/write, file/copy 엔드포인트로 app-server에서 파일을 바로 조작합니다. 기존 exec 명령에서 cat/cp를 호출하던 방식보다 오버헤드가 적습니다
• Python SDK: JavaScript/TypeScript SDK에 이어 Python SDK가 추가돼, Python 기반 파이프라인에서 Codex를 네이티브로 통합합니다
• view_image 풀해상도 요청: 모델이 view_image 도구로 원본 해상도 이미지를 검사하므로 UI 스크린샷 기반 디버깅에 잘 맞습니다

# Python SDK 예시
from codex import CodexClient

client = CodexClient()
result = client.exec("summarize the repo structure", sandbox="read-only")
print(result.last_message)

codex exec의 prompt + stdin 조합 (0.118.0)

0.118.0부터 codex exec는 stdin 입력과 별도 프롬프트 인자를 함께 받는 워크플로우를 공식 지원합니다. 이제 파이프 입력을 넘기면서도 작업 지시를 따로 명시해 둡니다.

cat coverage-summary.txt | codex exec "summarize the regressions and suggest next fixes"

실험적 codex exec-server (0.119.0)

0.119.0에서 실험적 codex exec-server 서브커맨드가 추가됐습니다. 릴리즈 노트를 보면 app-server/remote 경로를 더 또렷하게 갈라서 자동화 파이프라인에 연결하려는 흐름으로 읽는 게 맞습니다.

codex exec-server --help

• 적합한 경우: 내부 런타임이나 사내 에이전트 허브가 Codex 실행을 서비스처럼 감싸야 할 때
• 장점: remote --cd 전달, egress websocket transport, sandbox-aware filesystem APIs와 함께 app-server 계열 자동화를 더 일관되게 묶음
• 주의: 아직 실험적 기능이라, 팀 표준에 넣을 때는 버전을 0.119.x 이상으로 핀 고정하고 인터페이스가 바뀔 수 있다는 전제로 문서화하세요

codex remote-control (0.130.0)

0.130.0에서 headless, remotely controllable app-server를 띄우는 더 단순한 entrypoint로 codex remote-control이 추가됐습니다. 원격 TUI, 내부 agent hub, 사내 운영 콘솔에서 Codex app-server를 오래 띄워두는 팀이라면 기존 app-server/exec-server 실험 경로와 나란히 비교해 보세요.

• 적합한 경우: code workspace는 원격 host에 있고, local TUI나 내부 UI가 WebSocket으로 제어해야 할 때
• 운영 기준: non-local listener는 인증과 TLS를 먼저 구성하고, capability token 또는 signed bearer token을 비밀로 관리
• 검증 기준: large thread pagination, config refresh, resume/fork가 실제 클라이언트에서 기대대로 동작하는지 smoke test에 포함

codex app-server --stdio와 app-server schema (0.136.0)

0.136.0에서 app-server integrations는 codex app-server --stdio 진입점과 richer MCP server status를 얻었습니다. Codex app-server는 JSON-RPC 스타일의 thread/turn API를 제공하므로, 내부 제품에 Codex를 깊게 붙이는 팀이라면 codex exec wrapper보다 app-server를 직접 붙이는 쪽이 더 깔끔합니다.

운영 기준:

• stdio transport는 로컬 process boundary 안에서 JSONL로 통신하므로 localhost WebSocket을 열 필요가 없음
• generate-ts / generate-json-schema로 쓰는 Codex 버전에 맞는 schema를 만들어 클라이언트 drift를 줄임
• thread API는 start/resume/fork/archive를 모두 다루므로, 앱 UI에는 archived/unarchived event와 turn status를 표시
• app-server를 CI 자동화에 무리하게 끌어쓰기보다, 반복 job은 Codex SDK나 codex exec를 먼저 검토

codex app-server --stdio
codex app-server generate-json-schema --out ./schemas

App-server/debug 및 cloud exec 보강 (0.138.0~0.139.0)

0.138.0부터 app-server integrations는 account token usage를 읽고, CLI/app-server 인증 흐름은 ChatGPT v2 personal access token을 지원합니다. 원격 host나 내부 agent hub를 운영하는 팀은 "토큰 갱신", "사용량 조회", "권한 회수"를 하나의 runbook으로 묶으세요.

0.139.0에서는 OpenAI Codex cloud environment용 exec agent provider가 추가됐고, codex debug app-server send-message-v2를 다시 쓸 수 있게 됐습니다. app-server v2 클라이언트를 직접 붙인 팀은 이 debug command를 smoke test에 넣어 message send 경로가 깨지지 않았는지 확인하세요.

codex debug app-server send-message-v2 --help
codex debug models

운영 기준:

• code mode web search를 허용하는 자동화는 검색 출처와 실행 시각을 로그에 남기고, 네트워크 차단 환경에서는 별도 fallback을 정의
• app-server schema generation, send-message-v2, account token usage 조회를 release upgrade checklist에 포함
• ChatGPT v2 personal access token을 쓰는 host는 토큰 발급자, 만료, 저장 위치, 폐기 절차를 문서화
• Codex cloud exec provider는 local codex exec와 같은 권한 모델로 가정하지 말고, cloud environment 요구사항과 별도 검증
• plugin marketplace install/upgrade 자동화는 --json 출력의 selected/upgraded/error 필드를 로그로 보존

이미지 입력과 파일 path 노출 (0.138.0)

codex exec --image와 앱/CLI 이미지 첨부 흐름은 0.138.0 이후 모델이 저장된 파일 path를 더 잘 참조합니다. UI 스크린샷을 첨부한 뒤 후속 수정이나 이미지 편집을 요청하는 자동화라면 "이미지를 다시 설명"하기보다 저장된 path와 관련 파일을 함께 넘기는 쪽이 안정적입니다.

codex exec --image ./screenshots/mobile-nav.png \
  "Find UI regressions and produce a concise fix plan"

주의할 점:

• 이미지 path는 로컬/원격/worktree 환경에 따라 해석 기준이 달라지므로 --cd와 workspace root를 명시
• 민감한 스크린샷은 파일 보존 기간과 artifact 업로드 대상을 별도로 제한
• image edit가 referenced file path를 따라가므로, 같은 이름의 임시 파일이 섞이지 않게 run directory를 고정

codex exec resume --output-schema (0.132.0)

0.132.0부터 codex exec resume도 --output-schema를 받습니다. 기존 세션 맥락을 이어가면서도 후속 파이프라인이 요구하는 JSON Schema 계약을 지켜야 하는 자동화에 쓸모가 있습니다.

codex exec resume --last \
  --output-schema ./schemas/release-note.json \
  -o ./release-note.json \
  "이전 분석을 기준으로 릴리즈 노트를 구조화해줘"

• 적합한 경우: 긴 조사/수정 세션을 이어받아 최종 산출물만 JSON으로 고정해야 할 때
• 주의: resume된 세션의 이전 맥락이 출력에 영향을 주므로, schema만으로 사실 관계가 보장된다고 믿지 말고 검증 단계를 따로 두세요

Python SDK auth/turn API (0.131.0~0.132.0)

Python SDK는 openai-codex / openai_codex 경로로 정리됐고, API key login, ChatGPT browser/device-code flows, account inspection, logout API, plain string input, richer TurnResult를 지원합니다. Python 기반 사내 자동화라면 CLI wrapper만 쓰지 않고 SDK를 직접 써도 될 만큼 무르익었습니다.

운영 기준:

• CLI와 SDK가 같은 auth 정책을 쓰는지 확인
• TurnResult의 usage/timing을 비용 리포트에 반영
• SDK 자동화도 CLI와 동일한 sandbox/approval/runbook 검증 대상으로 취급

Code Mode의 MCP outputSchema 전달 (0.120.0)

0.120.0부터 code mode의 tool declaration이 MCP outputSchema를 담을 수 있어, structured tool result가 더 정확한 타입 정보를 유지합니다.

• 효과: MCP 도구가 구조화된 JSON을 반환할 때 downstream 자동화가 타입을 덜 추측함
• 적합한 곳: schema 기반 리포트 생성, codex exec 뒤 후속 파이프라인이 구조화 출력을 소비하는 시나리오
• 운영 팁: --output-schema와 MCP 측 outputSchema를 같이 쓴다면, 어느 레이어가 최종 계약인지 팀 기준으로 하나만 authoritative source로 정하세요

격리 exec 실행 + 대형 패치 안정화 (0.122.0)

0.122.0에서는 codex exec를 더 재현성 있게 돌리기 위한 두 가지 축이 강화됐습니다.

• 격리 실행 플래그: changelog 기준으로 --ignore-user-config, --ignore-rules가 추가돼, CI나 실험 실행에서 개인 설정과 로컬 rules를 빼고 정책을 검증합니다
• 대형 파일 patching 개선: 큰 파일을 다루는 자동 수정에서 patch 정확도가 높아져, 대규모 리팩터링이나 코드젠 후속 정리에 더 유리합니다

Codex SDK

CLI보다 더 세밀한 제어가 필요하면 Codex SDK로 내부 도구나 파이프라인에 직접 통합합니다. 예: 작업 상태 저장/재시도, 도구 호출 라우팅, 내부 정책 강제 등.

Codex as MCP Server (Agents SDK 연동)

Codex를 MCP 서버로 실행하면 OpenAI Agents SDK에서 멀티에이전트 워크플로우를 구성합니다.

# Codex를 MCP 서버로 시작
codex mcp-server

Agents SDK에서 codex 툴(세션 시작)과 codex-reply 툴(대화 이어가기)을 사용해 Project Manager → Designer → Developer → Tester 같은 역할 기반 파이프라인을 구축할 수 있습니다.

참고 문서

• 비대화형 실행: https://developers.openai.com/codex/noninteractive (영어)
• Codex CLI 개요: https://developers.openai.com/codex/cli (영어)
• Codex GitHub Action: https://developers.openai.com/codex/github-action (영어)
• Codex SDK: https://developers.openai.com/codex/sdk (영어)
• Agents SDK 가이드: https://developers.openai.com/codex/guides/agents-sdk (영어)
• 보안(샌드박스/승인 플래그): https://developers.openai.com/codex/security (영어)