Ch7. exec/자동화

Codex는 비대화형 실행을 통해 스크립트/CI 환경에서 사용할 수 있습니다. 이를 통해 리뷰/정적 분석/문서화 같은 반복 작업을 자동화할 수 있습니다.

언제 `codex exec`를 쓰나

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

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

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

--json을 켜면 stdout이 JSON Lines(JSONL)로 흐르며, 실행 중 이벤트를 파이프라인으로 받을 수 있습니다.

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

0.125.0: reasoning token usage 포함

0.125.0부터 codex exec --json 이벤트에는 reasoning token usage도 포함됩니다. 비용/지연을 모델별로 비교하려는 팀은 이제 별도 추정보다 실행 로그 자체를 기준으로 측정할 수 있습니다.

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(샌드박스/승인 우회)

`--full-auto` deprecated

공식 non-interactive 문서 기준으로 codex exec --full-auto는 compatibility flag로 남아 있지만 deprecated입니다. 새 자동화는 --sandbox workspace-write처럼 sandbox를 직접 지정하고, 팀 승인 정책은 config/requirements로 분리하는 편이 안전합니다.

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

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

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

CI 운영 팁

키 분리: 비대화형 실행은 CODEX_API_KEY로 분리
레포 체크 우회 금지(기본): 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"

성능 개선

app-server 경로는 기존 프로세스 포크 방식 대비 실행 오버헤드가 줄어들어, 특히 짧은 반복 실행(CI 체크 등)에서 체감 속도가 개선됩니다.

실험적 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/"

실험적 기능

code mode는 실험 단계이며, 향후 인터페이스가 변경될 수 있습니다. 프로덕션 CI에 적용 전 충분히 테스트하세요.

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 작업 완료\"}'"

CI 연동 팁

hooks를 활용하면 exec 전후에 Slack 알림, 메트릭 수집, 아티팩트 업로드 등을 별도 스크립트 없이 config만으로 구성할 수 있습니다.

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"

운영 포인트

이전에도 비슷한 파이프 조합을 시도할 수 있었지만, 0.118.0부터는 "입력 데이터"와 "작업 지시"를 함께 넘기는 패턴이 공식 릴리즈 노트에 올라온 안정 경로입니다. CI 파이프라인에서 로그/리포트를 넣고 별도 지시문을 유지하는 형태에 적합합니다.

실험적 `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 exec-server는 현재 공식 non-interactive 문서보다 changelog/release에서 먼저 확인되는 항목입니다. 운영 자동화에 넣을 때는 --help 출력과 릴리즈 노트를 함께 기준으로 삼는 편이 안전합니다.

`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에 포함

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 정확도가 높아져, 대규모 리팩터링이나 코드젠 후속 정리에 더 유리합니다

운영 팁

자동화 품질을 비교 실험할 때는 "기본 exec"과 "ignore-user-config/ignore-rules exec"를 나눠 실행해 개인 환경 의존성이 얼마나 개입하는지 먼저 측정하는 편이 좋습니다.

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 (영어)

Codex는 비대화형 실행을 통해 스크립트/CI 환경에서 사용할 수 있습니다. 이를 통해 리뷰/정적 분석/문서화 같은 반복 작업을 자동화할 수 있습니다.

언제 `codex exec`를 쓰나

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

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

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

--json을 켜면 stdout이 JSON Lines(JSONL)로 흐르며, 실행 중 이벤트를 파이프라인으로 받을 수 있습니다.

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

0.125.0: reasoning token usage 포함

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(샌드박스/승인 우회)

`--full-auto` deprecated

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

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

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

CI 운영 팁

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

GitHub Action(운영 표준화)

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)

주요 변경점

스트리밍 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"

성능 개선

app-server 경로는 기존 프로세스 포크 방식 대비 실행 오버헤드가 줄어들어, 특히 짧은 반복 실행(CI 체크 등)에서 체감 속도가 개선됩니다.

실험적 Code Mode (0.114.0)

특징

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

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

실험적 기능

code mode는 실험 단계이며, 향후 인터페이스가 변경될 수 있습니다. 프로덕션 CI에 적용 전 충분히 테스트하세요.

Hooks 엔진 (0.114.0 → 0.124.0)

활용 예시

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 작업 완료\"}'"

CI 연동 팁

hooks를 활용하면 exec 전후에 Slack 알림, 메트릭 수집, 아티팩트 업로드 등을 별도 스크립트 없이 config만으로 구성할 수 있습니다.

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)

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

운영 포인트

실험적 `codex exec-server` (0.119.0)

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)

적합한 경우: 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에 포함

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

Codex as MCP Server (Agents SDK 연동)

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

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

참고 문서

비대화형 실행: 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 (영어)

Ch7. exec/자동화

목차

Ch7. exec/자동화

목차