codex exec와 구조화 출력으로 자동화하기

스크립트에서 Codex의 결과를 사용하려면 자연어 답변이 도착했다는 사실과 작업이 성공했다는 판정을 분리해야 합니다. 프로세스 종료, 최종 산출물의 형식, 실제 테스트 결과를 각각 확인하는 작은 실행기를 만드는 편이 좋습니다.

공식 문서를 참고한 비공식 한국어 가이드입니다. 아래 명령은 합성 예시이며 AI 실행·인증·과금은 수행하지 않았습니다. 승인된 저장소와 출력 디렉터리를 사용하고 저장소 코드가 인증값을 읽을 수 있는 환경인지 검토합니다.

기본은 읽기 전용 실행

codex exec "<task>"는 비대화형 경로이며 기본 sandbox는 read-only입니다. 수정이 필요한 경우 공식 문서는 --sandbox workspace-write를 안내합니다. 오래된 예제의 --full-auto는 더 이상 지원되지 않습니다. 자동 승인 검토를 사용하는 다른 옵션을 무검수 대체품으로 복사하지 마세요.

codex exec "저장소의 테스트 실행 방법을 조사하고 수정 없이 근거 파일을 보고해 줘"

읽기 전용도 저장소 데이터가 모델에 전달되지 않는다는 뜻은 아닙니다. 외부 전송 허용 범위와 사용 계정을 먼저 확인합니다. Git 신뢰 검사나 샌드박스 오류를 해결하려고 안전장치를 생략하지 않습니다.

일반 출력과 JSONL

일반 모드의 진행 상황은 stderr, 최종 메시지는 stdout으로 나옵니다. --json을 사용하면 stdout은 JSONL 이벤트 스트림이 됩니다. 이벤트 하나를 최종 완료로 오인하지 말고 실제 종료와 필요한 최종 이벤트를 확인합니다.

-o <path>는 최종 메시지를 파일로 남기지만 stdout을 없애는 옵션이 아닙니다. 파이프라인이 두 경로를 중복 처리하거나 로그에 민감 내용을 남기지 않는지 확인합니다. prompt 인자와 pipe를 함께 쓰면 pipe는 추가 문맥이며, codex exec -는 stdin 전체를 prompt로 받습니다.

최종 응답에 Schema 적용

가상의 review-schema.json을 사람이 먼저 작성하고 검토했다는 가정입니다. 다음 구조는 출력 형식의 예시이지 테스트 성공을 증명하는 계약은 아닙니다.

{
  "type": "object",
  "properties": {
    "summary": { "type": "string" },
    "unverified": { "type": "array", "items": { "type": "string" } }
  },
  "required": ["summary", "unverified"],
  "additionalProperties": false
}

codex exec --output-schema review-schema.json -o review-result.json \
  "변경을 조사하고 요약과 미검증 범위를 작성해 줘. 파일은 수정하지 마."

Schema에 맞는 JSON이 만들어져도 내용은 틀릴 수 있습니다. 소비자는 파일 존재, JSON 파싱/Schema, 필수 증거, 실제 검증 결과를 따로 확인합니다. 답변의 summary를 셸 명령이나 게시 본문으로 즉시 실행하지 않습니다.

재개와 실행 환경

codex exec resume <SESSION_ID> 또는 --last로 이전 세션을 이어갈 수 있습니다. 저장된 대화의 디렉터리·기준 커밋·설정이 현재 작업과 맞는지 확인합니다. --ephemeral은 session rollout을 저장하지 않는 선택이지 모든 로그나 인증 흔적이 사라진다는 보장이 아닙니다.

CI에서는 API key를 저장소 코드와 같은 job 전체에 노출하지 않도록 설계합니다. 종료 실패, 출력 누락, timeout은 재시도 전에 원인을 기록하고 외부 쓰기의 중복 여부를 확인합니다. 라이브러리 제어가 필요하면 SDK, 연결/승인 UI가 필요하면 App Server로 이어집니다.

공식 한국어 도움말: ChatGPT 플랜과 Codex에서 계정별 이용 안내를 확인할 수 있습니다. 이 글은 해당 도움말의 공식 번역이 아니며 계정 조건과 요금은 공식 안내를 우선합니다.