codex exec

codex exec가 하는 일

평소 codex를 실행하면 대화형 화면이 열립니다. codex exec는 이 화면 없이 작업 한 건을 실행하고 종료합니다. 공식 문서는 스크립트와 CI에서 쓰는 비대화식 모드로 설명합니다.

출력 방식이 중요합니다. 진행 과정은 stderr로 흘러가고, stdout에는 최종 에이전트 메시지만 나옵니다. 그래서 리다이렉트하거나 파이프로 넘기기 쉽습니다. 작업은 따옴표 안의 인자 하나로 전달합니다.

codex exec "summarize the repository structure and list the top 5 risky areas"
codex exec "generate release notes for the last 10 commits" | tee release-notes.md

권한: 기본은 읽기 전용

기본 샌드박스는 읽기 전용입니다. 코드를 읽고 요약하는 일은 되지만 파일을 고치지는 못합니다. 수정까지 맡기려면 --sandbox workspace-write를 줍니다.

--sandbox danger-full-access는 넓은 접근을 허용합니다. 문서는 격리된 CI 러너나 컨테이너 같은 통제된 환경에서만 쓰라고 안내합니다. 내 노트북에서 습관처럼 쓸 옵션이 아닙니다.

• --full-auto는 더 이상 지원되지 않습니다. --sandbox workspace-write로 바꾸거나, 승인 요청을 자동 검토로 넘기는 --approve-for-me를 씁니다.
• --ignore-user-config는 $CODEX_HOME/config.toml을 건너뜁니다. --ignore-rules는 사용자와 프로젝트의 execpolicy .rules 파일을 건너뜁니다.
• 필수(required = true)로 설정한 MCP 서버가 시작에 실패하면 계속 진행하지 않고 오류로 종료합니다.
• --ephemeral을 붙이면 세션 기록 파일을 디스크에 남기지 않습니다.

결과를 기계가 읽게 만들기

--json을 주면 stdout이 JSON Lines 이벤트 스트림이 됩니다. thread.started, turn.completed, turn.failed, item.*, error 같은 이벤트가 나오고, 항목에는 에이전트 메시지, 명령 실행, 파일 변경, 웹 검색, 계획 갱신 등이 있습니다.

최종 메시지만 파일로 받으려면 -o(--output-last-message) 경로를 씁니다. 파일에 쓰면서 stdout에도 그대로 출력됩니다. 응답 형식을 고정하고 싶으면 --output-schema에 JSON Schema 파일을 줍니다. 최종 응답이 그 스키마에 맞는 JSON으로 나옵니다.

codex exec "summarize the changes" -o ./summary.md

codex exec "Extract project metadata" \
  --output-schema ./schema.json \
  -o ./project-metadata.json

표준 입력, 이어가기, 인증

표준 입력은 두 가지로 씁니다. 인자로 지시문을 주고 파이프로 자료를 넘기면, 파이프 내용은 참고 자료가 됩니다. 인자를 생략하거나 - 를 쓰면 표준 입력 전체가 프롬프트가 됩니다.

이전 실행을 이어가려면 resume을 씁니다. --last는 가장 최근 세션이고, 세션 ID를 직접 줄 수도 있습니다.

인증은 기본적으로 CLI에 저장된 로그인을 재사용합니다. CI에서는 CODEX_API_KEY를 해당 실행에만 지정하는 방법이 있습니다. 문서는 저장소가 제어하는 코드를 실행하는 워크플로에서 OPENAI_API_KEY나 CODEX_API_KEY를 잡(job) 전체 환경변수로 두지 말라고 경고합니다. 빌드 스크립트나 의존성이 키를 읽을 수 있기 때문입니다.

Git 저장소 안에서 실행해야 합니다. --skip-git-repo-check는 환경이 안전할 때만 쓰라고 합니다. GitHub Actions에서는 CLI를 직접 설치해 키를 넘기는 대신 openai/codex-action을 쓰라고 안내합니다.

npm test 2>&1 \
  | codex exec "summarize the failing tests and propose the smallest likely fix" \
  | tee test-summary.md

codex exec "review the change for race conditions"
codex exec resume --last "fix the race conditions you found"

실제 예시

npm test 2>&1 | codex exec "summarize the failing tests and propose the smallest likely fix" | tee test-summary.md

codex exec "Extract project metadata" --output-schema ./schema.json -o ./project-metadata.json

흔한 실수와 쓰지 말아야 할 때

• 기본이 읽기 전용이라 "고쳐 줘"라고만 쓰면 수정되지 않습니다. 수정이 필요하면 --sandbox workspace-write를 직접 주세요.
• --sandbox danger-full-access를 개인 컴퓨터에서 쓰지 마세요. 격리된 CI 환경용입니다.
• API 키를 CI 잡 전체 환경변수로 넣으면 빌드 스크립트와 의존성이 읽을 수 있습니다. 해당 실행에만 지정하세요.
• 옛 글에 나오는 --full-auto는 더 이상 지원되지 않습니다.
• ChatGPT 로그인 인증(~/.codex/auth.json)을 CI에 올리는 방법은 신뢰할 수 있는 러너용 고급 옵션입니다. 이 파일은 비밀번호처럼 다루고, 공개 저장소에는 쓰지 말라고 문서가 경고합니다.

자주 묻는 질문