비대화형 모드

비대화형 모드를 사용하면 대화형 TUI를 열지 않고도 스크립트에서 Codex를 실행할 수 있습니다. 지속적 통합(CI) 작업이 대표적인 예입니다. codex exec로 이 모드를 실행합니다.

각 플래그에 대한 자세한 설명은 codex exec를 참고하세요.

codex exec를 사용하는 경우

다음과 같은 경우에 codex exec를 사용하세요.

• CI, 병합 전 검사, 예약 작업 등 파이프라인의 일부로 Codex를 실행할 때
• 릴리스 노트나 요약을 생성하기 위해 Codex의 출력을 파이프로 다른 도구에 전달할 때
• CLI 워크플로우에서 명령어의 출력을 Codex에 입력하고 그 결과를 다른 도구에 전달할 때
• 샌드박스 및 승인 설정을 미리 명시하고 Codex를 실행할 때

기본 사용법

작업 프롬프트를 하나의 인수로 전달하세요.

codex exec "summarize the repository structure and list the top 5 risky areas"

codex exec를 실행하면 Codex는 진행 상황을 stderr로 실시간 출력하고 에이전트의 최종 메시지만 stdout으로 출력합니다. 따라서 최종 결과만 파일로 리디렉션하거나 파이프로 전달할 수 있습니다.

codex exec "generate release notes for the last 10 commits" | tee release-notes.md

세션 실행 기록 파일을 디스크에 남기고 싶지 않다면 --ephemeral을 사용하세요.

codex exec --ephemeral "triage this repository and suggest next steps"

워커의 홈 디렉터리가 네트워크 파일 시스템에 마운트되어 있다면 작업 상태를 로컬에 저장하고 세션 실행 기록을 보존하는 방법을 참고하세요.

파이프로 stdin에 데이터를 전달하면서 프롬프트 인수도 지정하면 Codex는 프롬프트를 지시 사항으로, 파이프로 받은 내용을 추가 컨텍스트로 사용합니다.

이 방식으로 한 명령어에서 생성한 입력을 Codex에 바로 전달할 수 있습니다.

curl -s https://jsonplaceholder.typicode.com/comments \
  | codex exec "format the top 20 items into a markdown table" \
  > table.md

stdin에 파이프로 입력을 전달하는 다양한 방법은 stdin 파이프 고급 활용을 참고하세요.

권한과 안전

기본적으로 codex exec는 읽기 전용 샌드박스에서 실행됩니다. 자동화할 때는 워크플로우에 필요한 최소한의 권한만 부여하세요.

• 편집 허용: codex exec --sandbox workspace-write "<task>"
• 더 넓은 범위의 접근 허용: codex exec --sandbox danger-full-access "<task>"

danger-full-access는 격리된 CI 러너나 컨테이너처럼 통제된 환경에서만 사용하세요.

--full-auto는 더 이상 지원되지 않습니다. 스크립트를 수정해 --sandbox workspace-write를 사용하세요. 또는 --approve-for-me를 사용해 workspace-write 샌드박스에서 승인 요청을 자동 검토하도록 하세요.

--ignore-user-config를 사용하면 $CODEX_HOME/config.toml을 로드하지 않고 실행할 수 있습니다. 통제된 자동화 환경에서는 --ignore-rules를 사용해 사용자 및 프로젝트의 execpolicy .rules 파일을 건너뛸 수 있습니다.

활성화된 MCP 서버에 required = true를 설정한 경우, 해당 서버를 초기화하지 못하면 codex exec는 오류를 반환하고 종료됩니다.

기계가 읽을 수 있는 형식으로 출력하기

스크립트에서 Codex의 출력을 처리하려면 JSON Lines 형식을 사용하세요.

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

--json을 사용하면 stdout에 JSON Lines(JSONL) 스트림이 출력되므로 Codex가 실행 중에 내보내는 모든 이벤트를 수집할 수 있습니다. 이벤트 유형에는 thread.started, turn.started, turn.completed, turn.failed, item.*, error가 있습니다.

항목 유형에는 에이전트 메시지, 추론, 명령어 실행, 파일 변경, MCP 도구 호출, 웹 검색, 계획 업데이트가 있습니다.

다음은 JSON 스트림의 예시입니다. 각 줄이 하나의 JSON 객체입니다.

{"type":"thread.started","thread_id":"0199a213-81c0-7800-8aa1-bbab2a035a53"}
{"type":"turn.started"}
{"type":"item.started","item":{"id":"item_1","type":"command_execution","command":"bash -lc ls","status":"in_progress"}}
{"type":"item.completed","item":{"id":"item_3","type":"agent_message","text":"Repo contains docs, sdk, and examples directories."}}
{"type":"turn.completed","usage":{"input_tokens":24763,"cached_input_tokens":24448,"output_tokens":122,"reasoning_output_tokens":0}}

최종 메시지만 필요하다면 -o <path> 또는 --output-last-message <path>로 파일에 저장하세요. 최종 메시지는 파일에 저장되며 stdout에도 출력됩니다. 자세한 내용은 codex exec를 참고하세요.

스키마로 구조화된 출력값 생성하기

후속 단계에서 구조화된 데이터가 필요하면 --output-schema를 사용해 JSON 스키마에 맞는 최종 응답을 요청하세요. 작업 요약, 위험 보고서, 릴리스 메타데이터처럼 필드 구성이 일정해야 하는 자동화 워크플로우에 유용합니다.

schema.json

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

스키마를 지정해 Codex를 실행하고 최종 JSON 응답을 디스크에 저장하세요.

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

최종 출력 예시(stdout)

{
  "project_name": "Codex CLI",
  "programming_languages": ["Rust", "TypeScript", "Shell"]
}

자동화 환경에서 인증하기

codex exec는 기본적으로 저장된 CLI 인증 정보를 재사용합니다. CI에서는 일반적으로 인증 정보를 명시적으로 제공합니다.

API 키로 인증하기

GitHub Actions에서는 CLI를 직접 설치하고 인증하는 대신 Codex GitHub Action을 사용하세요. 이 액션은 API 키 노출을 줄이도록 설계되었습니다. Codex를 설치하고 Responses API 프록시를 시작한 뒤, 설정한 안전 전략에 따라 Codex를 실행합니다.

리포지터리에서 관리하는 코드를 체크아웃하거나 실행하는 워크플로우에서는 OPENAI_API_KEY나 CODEX_API_KEY를 작업 수준의 환경 변수로 설정하지 마세요. 같은 작업에서 실행되는 빌드 스크립트, 테스트, 종속성 수명 주기 훅 또는 공격자가 장악한 액션이 이 환경 변수를 읽을 수 있습니다.

그 밖의 자동화 환경에서는 CODEX_API_KEY를 해당 키가 필요한 Codex 호출에만 설정하고, 같은 프로세스 환경에서 신뢰할 수 없는 코드가 실행되지 않도록 하세요.

한 번의 실행에만 다른 API 키를 사용하려면 명령어 앞에 CODEX_API_KEY를 지정하세요.

CODEX_API_KEY=<api-key> codex exec --json "triage open bug reports"

CODEX_API_KEY는 codex exec, codex review, TypeScript SDK 및 codex exec-server --remote에서 사용할 수 있습니다.

비대화형 세션 재개하기

두 단계로 구성된 파이프라인처럼 이전 실행을 이어서 진행해야 할 때는 resume 하위 명령어를 사용하세요.

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

codex exec resume <SESSION_ID>로 재개할 세션의 ID를 지정할 수도 있습니다.

Git 리포지터리 요구 사항

Codex는 파괴적인 변경을 방지하기 위해 Git 리포지터리 안에서만 명령어를 실행하도록 합니다. 환경이 안전하다고 확신한다면 codex exec --skip-git-repo-check로 이 검사를 건너뛸 수 있습니다.

일반적인 자동화 패턴

예시: GitHub Actions에서 CI 실패 자동 수정하기

GitHub Actions 워크플로우에서는 Codex를 직접 설치하고 셸 단계에 API 키를 전달하는 대신 openai/codex-action을 사용하세요. 이 액션은 OpenAI API 키를 보호하는 프록시를 시작합니다.

CI 워크플로우가 실패하면 Codex가 자동으로 수정안을 제안하도록 구성할 수 있습니다. 절차는 다음과 같습니다.

1. 기본 CI 워크플로우가 오류로 종료되면 후속 워크플로우를 시작합니다.
2. 리포지터리 읽기 권한만 사용해 실패한 커밋을 체크아웃합니다.
3. Codex를 실행하기 전에 설정 명령어를 실행합니다. 이 단계에는 OpenAI API 키를 노출하지 않습니다.
4. Codex GitHub Action을 실행합니다.
5. Codex가 로컬에서 변경한 내용을 패치 아티팩트로 저장합니다.
6. 별도의 작업에서 패치를 적용하고 pull request를 엽니다.

아래 예시에서 Codex를 실행하는 작업에는 contents: read 권한만 있습니다. Codex가 실행된 뒤 이 작업은 diff만 아티팩트로 저장합니다. open_pr 작업에는 리포지터리 쓰기 권한을 부여하지만 OPENAI_API_KEY는 전달하지 않습니다.

이 예시는 Node.js 프로젝트를 기준으로 작성했습니다. 사용하는 기술 스택에 맞게 설정 및 테스트 명령어를 조정하세요.

자세한 보안 체크리스트는 Codex GitHub Action 보안 지침을 참고하세요.

name: Codex auto-fix on CI failure

on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]

jobs:
  generate_fix:
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    runs-on: ubuntu-latest
    permissions:
      contents: read
    outputs:
      has_patch: ${{ steps.diff.outputs.has_patch }}
    steps:
      - uses: actions/checkout@v5
        with:
          ref: ${{ github.event.workflow_run.head_sha }}
          fetch-depth: 0
          persist-credentials: false

      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install dependencies
        run: |
          if [ -f package-lock.json ]; then npm ci; fi

      - name: Run Codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt: |
            The CI workflow "${{ github.event.workflow_run.name }}" failed for commit
            ${{ github.event.workflow_run.head_sha }}.

            Run `npm test --silent` to reproduce the failure. Identify the minimal
            change needed to make the tests pass, implement only that change, and
            run `npm test --silent` again.

            Do not refactor unrelated files.

      - name: Create patch artifact
        id: diff
        run: |
          git add -N .
          git diff --binary HEAD > codex.patch
          if [ -s codex.patch ]; then
            echo "has_patch=true" >> "$GITHUB_OUTPUT"
          else
            echo "has_patch=false" >> "$GITHUB_OUTPUT"
          fi

      - name: Upload patch artifact
        if: steps.diff.outputs.has_patch == 'true'
        uses: actions/upload-artifact@v4
        with:
          name: codex-fix-patch
          path: codex.patch
          if-no-files-found: error

  open_pr:
    runs-on: ubuntu-latest
    needs: generate_fix
    if: needs.generate_fix.outputs.has_patch == 'true'
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v5
        with:
          ref: ${{ github.event.workflow_run.head_sha }}
          fetch-depth: 0

      - uses: actions/download-artifact@v4
        with:
          name: codex-fix-patch

      - name: Apply Codex patch
        run: git apply --index codex.patch

      - name: Open pull request
        env:
          GH_TOKEN: ${{ github.token }}
          FAILED_HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
          FAILED_HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
          RUN_ID: ${{ github.event.workflow_run.run_id }}
        run: |
          branch="codex/auto-fix-$RUN_ID"

          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git switch -c "$branch"
          git commit -m "Auto-fix failing CI via Codex"
          git push origin "$branch"

          {
            echo "Codex generated this patch after CI failed for \`$FAILED_HEAD_SHA\`."
            echo
            echo "Review the changes before merging."
          } > pr-body.md

          gh pr create \
            --base "$FAILED_HEAD_BRANCH" \
            --head "$branch" \
            --title "Auto-fix failing CI via Codex" \
            --body-file pr-body.md

stdin 파이프 고급 활용

다른 명령어에서 Codex에 전달할 입력을 생성할 때는 지시 사항을 어디에서 가져올지에 따라 stdin 사용 방식을 선택하세요. 지시 사항이 이미 정해져 있고 파이프로 받은 출력을 컨텍스트로 전달하려면 프롬프트와 stdin을 함께 사용하세요. stdin 전체를 프롬프트로 사용하려면 codex exec -를 사용하세요.

프롬프트와 stdin 함께 사용하기

다른 명령어가 이미 Codex로 검사할 데이터를 출력한다면 프롬프트와 stdin을 함께 사용하는 방식이 유용합니다. 지시 사항은 직접 작성하고 명령어의 출력은 파이프로 전달해 컨텍스트로 사용합니다. 명령어 출력, 로그, 자동으로 생성한 데이터를 다루는 CLI 워크플로우에 적합합니다.

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

tail -n 200 app.log \
  | codex exec "identify the likely root cause, cite the most important errors, and suggest the next three debugging steps" \
  > log-triage.md

curl -vv https://api.example.com/health 2>&1 \
  | codex exec "explain the TLS or HTTP failure and suggest the most likely fix" \
  > tls-debug.md

gh run view 123456 --log \
  | codex exec "write a concise Slack-ready update on the CI failure, including the likely cause and next step" \
  | pbcopy

gh run view 123456 --log \
  | codex exec "summarize the failure in 5 bullets for the pull request thread" \
  | gh pr comment 789 --body-file -

stdin이 프롬프트일 때 codex exec - 사용하기

프롬프트 인수를 생략하면 Codex는 stdin에서 프롬프트를 읽습니다. 이 동작을 명시적으로 지정하려면 codex exec -를 사용하세요.

-는 stdin에서 프롬프트를 읽도록 지정하는 인수로, 다른 명령어나 스크립트가 프롬프트 전체를 동적으로 생성할 때 유용합니다. 프롬프트를 파일에 저장해 두거나 셸 스크립트로 조합할 때, 또는 실시간 명령어 출력과 지시 사항을 결합해 하나의 프롬프트로 Codex에 전달할 때 이 방식을 사용하세요.

cat prompt.txt | codex exec -

printf "Summarize this error log in 3 bullets:\n\n%s\n" "$(tail -n 200 app.log)" \
  | codex exec -

generate_prompt.sh | codex exec - --json > result.jsonl