Codex exec 사용법: CI 결과를 JSONL·스키마 출력으로 자동화하기 | DAKER 커뮤니티

Codex exec 사용법의 핵심은 Codex를 터미널 대화창이 아니라 CI, 스크립트, 로그 분석 파이프라인에서 실행하는 것이다. `codex exec`란 Codex CLI를 비대화형으로 실행해 최종 답변, JSONL 이벤트, 스키마 기반 JSON 결과를 자동화 단계에 넘기는 방식을 의미한다. 2026년 6월 30일 기준 OpenAI Developers의 Codex 비대화형 모드 문서는 `--json`, `--output-schema`, 샌드박스 권한을 함께 설계하라고 안내한다.

대표 이미지 alt: DAKER 코덱스 Codex exec 사용법 JSONL 스키마 출력 CI 자동화 카드

대표 이미지 caption: Codex exec를 CI 로그, JSONL 이벤트, schema.json, 최소 권한 실행으로 연결하는 실무 흐름

워크플로 이미지 alt: DAKER 코덱스 Codex exec JSONL output-schema 자동화 워크플로

워크플로 이미지 caption: 로그 입력에서 codex exec 실행, 구조화 출력, PR·슬랙·릴리스 노트 전달까지의 4단계 흐름

## 문제 상황: 왜 Codex exec가 CI 자동화에서 필요할까?

Codex exec는 사람이 터미널 UI를 열지 않아도 Codex에게 저장소, 로그, 테스트 결과를 분석하게 만드는 실행 방식이다. CI 실패 요약, 릴리스 노트 초안, 위험 변경점 리포트처럼 반복되는 작업은 사람이 매번 프롬프트를 붙여넣는 방식보다 비대화형 실행이 안정적이다. 단, 자동화에서는 출력 형식과 권한 경계를 먼저 정하지 않으면 후속 스크립트가 깨지거나 과한 권한으로 실행될 수 있다.

핵심 포인트는 세 가지다.

1. 최종 요약만 필요하면 기본 `stdout` 또는 `-o` 파일 출력을 쓴다.

2. 실행 중 이벤트까지 추적하려면 `--json`으로 JSONL 스트림을 받는다.

3. 후속 단계가 필드 단위로 읽어야 하면 `--output-schema`로 최종 JSON 형태를 고정한다.

비슷한 실행 검증 관점은 https://daker.ai/community/codex-tool-03-safe-execution-validation-loop 글에서 함께 확인하면 좋다. 웹 검색과 근거 확인이 필요한 작업은 https://daker.ai/community/codex-tool-guide-21-web-search-evidence-surface 흐름과 같이 묶어 설계할 수 있다.

## 핵심 개념: Codex exec는 어떤 출력 모드를 제공할까?

Codex exec 출력 설계는 “사람이 읽는 요약”과 “기계가 읽는 이벤트”를 분리하는 일이다. OpenAI Developers 문서는 비대화형 실행에서 진행 상황은 `stderr`로 흐르고, 최종 에이전트 메시지는 `stdout`으로 출력된다고 설명한다. `--json`을 켜면 `stdout`은 JSON Lines 스트림이 되어 실행 이벤트를 줄 단위 객체로 캡처할 수 있다.

비교표로 보면 선택이 빨라진다.

| 목적 | 추천 옵션 | 후속 사용처 | 주의점 |

| --- | --- | --- | --- |

권한 설계는 별도 축이다. OpenAI Developers 문서 기준으로 `codex exec`는 기본적으로 읽기 전용 샌드박스에서 실행된다. 편집이 필요한 자동화만 `--sandbox workspace-write`를 쓰고, `danger-full-access`는 격리된 CI runner나 컨테이너처럼 통제된 환경에서만 검토해야 한다.

권한과 승인 정책은 https://daker.ai/community/codex-tool-usage-25-secure-workspace-permission-pr 글의 체크포인트와 함께 보면 실수 가능성이 줄어든다.

## 단계별 사용법: Codex exec 자동화는 어떻게 설계할까?

Codex exec 자동화는 실행 명령보다 입출력 계약을 먼저 정해야 한다. 아래 순서대로 잡으면 사람이 읽는 결과와 스크립트가 읽는 결과를 분리할 수 있다.

1. 자동화 목표를 한 문장으로 쓴다.

예: “최근 테스트 로그에서 실패 원인을 요약하고 PR 댓글 초안을 만든다.”

2. 입력 위치를 정한다.

예: `npm test 2>&1`, `gh run view --log`, `git diff --stat`, `CHANGELOG.md`.

3. 출력 소비자를 정한다.

사람이 읽으면 Markdown, 스크립트가 읽으면 JSONL 또는 JSON Schema를 선택한다.

4. 권한을 최소화한다.

요약만 하면 기본 읽기 전용으로 충분하다. 파일 수정을 맡길 때만 `--sandbox workspace-write`를 붙인다.

5. 실패 조건을 명시한다.

JSONL에서는 `turn.failed`나 `error` 이벤트를 감지하고, 스키마 출력에서는 필수 필드 누락을 실패로 처리한다.

짧은 예시는 다음과 같다. `npm test 2>&1 | codex exec "실패한 테스트의 원인과 가장 작은 수정 후보를 요약해줘" -o test-summary.md`

기계가 읽는 이벤트가 필요하면 다음처럼 JSONL로 남긴다.

예: `codex exec --json "저장소 구조를 요약하고 위험 영역 5개를 알려줘" > codex-events.jsonl`

후속 스크립트가 필드를 읽어야 한다면 `schema.json`을 만들고 `--output-schema schema.json -o result.json` 흐름을 쓴다. 예를 들어 `summary`, `risk_level`, `recommended_next_step` 같은 필드를 고정하면 PR 댓글, 슬랙 알림, 릴리스 노트 생성기가 결과를 안정적으로 소비할 수 있다.

GitHub Actions 안에서 Codex를 쓰는 팀은 https://daker.ai/community/codex-github-action-safe-pr-review-automation 글의 안전한 PR 리뷰 흐름도 함께 비교해보자.

## 실수 방지 체크리스트: 자동화에서 무엇을 확인해야 할까?

Codex exec 자동화는 프롬프트보다 운영 경계가 더 자주 문제를 만든다. 아래 항목을 게시 전 CI 설정처럼 점검하자.

- `OPENAI_API_KEY` 또는 `CODEX_API_KEY`를 job-level 환경 변수로 두지 않았는가?

- 저장소 코드, 테스트, 의존성 hook이 같은 환경에서 비밀 값을 읽을 수 없는가?

- 요약만 필요한 작업인데 `workspace-write`나 `danger-full-access`를 쓰고 있지 않은가?

- `--json` 결과를 일반 JSON 배열처럼 파싱하고 있지 않은가? JSONL은 한 줄에 객체 하나다.

- 스키마 출력의 필수 필드가 후속 스크립트와 정확히 맞는가?

- 프롬프트 지시문과 stdin으로 들어오는 로그·파일 내용을 구분했는가?

- CI 실패 시 `turn.failed`, `error`, 빈 출력, 스키마 검증 실패를 모두 실패로 처리하는가?

확인 기준일은 2026년 6월 30일이다. OpenAI Developers 문서에는 새 버전이 계속 반영될 수 있으므로, 팀의 공용 스크립트는 분기별로 옵션 이름과 보안 안내를 다시 확인하는 편이 안전하다.

## 공식 출처: 오늘 내용은 어디를 기준으로 확인했을까?

이 글은 2026년 6월 30일 기준 OpenAI Developers의 `Non-interactive mode - Codex`와 `CLI - Codex` 문서를 확인해 작성했다. 핵심 근거는 `codex exec`의 비대화형 실행 목적, `--json` JSONL 이벤트, `--output-schema` 구조화 출력, 기본 읽기 전용 샌드박스, CI 인증 주의사항이다. DAKER 정책에 따라 공개 본문에는 외부 URL을 직접 싣지 않고, 공식 문서명과 확인일만 남겼다.

## 자주 묻는 질문

### Codex exec와 일반 Codex CLI 실행은 무엇이 다른가?

일반 `codex` 실행은 터미널 UI에서 사람이 상호작용하는 흐름이다. `codex exec`는 CI나 스크립트에서 한 번 실행하고 결과를 파일, 파이프, JSONL, 스키마 JSON으로 넘기는 비대화형 흐름이다.

### Codex JSONL 출력은 언제 써야 하나?

실행 중 이벤트를 감시하거나, 명령 실행·파일 변경·MCP 호출·웹 검색·완료 상태를 로그 시스템에 남겨야 할 때 쓴다. 최종 요약만 필요하면 JSONL보다 `-o` 파일 출력이 단순하다.

### output-schema는 모든 Codex exec 작업에 필요한가?

아니다. 후속 스크립트가 특정 필드를 읽어야 할 때만 유용하다. 사람이 읽는 설명문이 목적이면 Markdown 출력이 더 유지보수하기 쉽다.

### CI에서 Codex API 키는 어떻게 다뤄야 하나?

공식 문서 기준으로 job-level 환경 변수에 API 키를 두는 방식은 피해야 한다. 저장소 코드나 의존성 hook이 같은 환경을 읽을 수 있으므로, 필요할 때 단일 `codex exec` 호출에만 제한적으로 전달하는 방식이 안전하다.

### Codex exec에 쓰기 권한을 줘도 괜찮을까?

요약과 분석만 맡기는 작업은 기본 읽기 전용으로 충분하다. 실제 파일 수정을 자동화할 때만 `--sandbox workspace-write`를 검토하고, 더 넓은 권한은 격리된 실행 환경에서만 사용해야 한다.

Codex 자동화를 처음 붙인다면 오늘은 `-o`, `--json`, `--output-schema` 중 하나만 골라 작은 CI 로그 요약부터 만들어보자.