비대화형 모드
스크립트와 CI에서 Codex를 실행하려면 codex exec을 사용하세요
비대화형 모드를 사용하면 대화형 TUI를 열지 않고도 스크립트(예: 지속적 통합(CI) 작업)에서 Codex를 실행할 수 있습니다.
codex exec으로 호출합니다.
플래그별 자세한 내용은 codex exec을 참조하세요.
codex exec을 사용해야 하는 경우
다음과 같은 작업을 Codex로 수행하려면 codex exec을 사용하세요.
- 파이프라인(CI, 병합 전 검사, 예약 작업)의 일부로 실행합니다.
- 다른 도구로 파이프할 수 있는 출력을 생성합니다(예: 릴리스 노트 또는 요약 생성).
- 명령 출력을 Codex에 연결하고 Codex 출력을 다른 도구에 전달하는 CLI 워크플로에 자연스럽게 통합합니다.
- 명시적으로 사전 설정한 샌드박스 및 승인 설정으로 실행합니다.
기본 사용법
작업 프롬프트를 단일 인수로 전달합니다.
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 러너 또는 컨테이너)에서만 사용하세요.
Codex는 codex exec --full-auto을 더 이상 권장되지 않는 호환성 플래그로 유지하며 경고를 출력합니다. 새 스크립트에서는 명시적인 --sandbox workspace-write 플래그를 사용하는 것이 좋습니다.
$CODEX_HOME/config.toml을 로드하지 않는 실행이 필요할 때는 --ignore-user-config을 사용하고, 통제된 자동화 환경에서 사용자 및 프로젝트 execpolicy .rules 파일을 건너뛰어야 할 때는 --ignore-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를 준수하는 최종 응답을 요청하세요.
이는 안정적인 필드가 필요한 자동화 워크플로(예: 작업 요약, 위험 보고서 또는 릴리스 메타데이터)에 유용합니다.
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 key 인증 사용
GitHub Actions에서는 CLI를 직접 설치하고 인증하는 대신 Codex GitHub Action을 사용하세요. 이 액션은 Codex를 설치하고 Responses API 프록시를 시작한 다음 구성 가능한 안전 전략으로 Codex를 실행하여 API key 노출을 줄이도록 설계되었습니다.
저장소에서 관리하는 코드를 체크아웃하거나 실행하는 워크플로에서는 OPENAI_API_KEY 또는 CODEX_API_KEY을 작업 수준 환경 변수로 설정하지 마세요. 같은 작업의 빌드 스크립트, 테스트, 종속성 수명 주기 훅 또는 침해된 액션이 해당 환경 변수를 읽을 수 있습니다.
다른 자동화 환경에서는 단일 codex exec 호출에만 CODEX_API_KEY을 설정하고, 같은 프로세스 환경에서 신뢰할 수 없는 코드가 실행되지 않도록 하세요.
단일 실행에 다른 API key를 사용하려면 CODEX_API_KEY을 인라인으로 설정하세요.
CODEX_API_KEY=<api-key> codex exec --json "triage open bug reports"CODEX_API_KEY은 codex exec에서만 지원됩니다.
API key는 프로비저닝과 교체가 더 간단하므로 자동화에 적합한 기본 옵션입니다. Codex 계정으로 실행해야 하는 명확한 필요가 있을 때만 이 방법을 사용하세요.
공개 또는 오픈 소스 저장소에는 이 워크플로를 사용하지 마세요. 러너에서 codex login을
사용할 수 없다면 보안 저장소를 통해 auth.json을 제공하고, 러너에서 Codex를 실행하여
Codex가 해당 파일을 제자리에서 갱신하도록 한 다음 실행 간에 업데이트된 파일을 보존하세요.
CI/CD에서 Codex 계정 인증 유지 관리(고급)를 참조하세요.
비대화형 세션 재개
이전 실행을 계속해야 하는 경우(예: 2단계 파이프라인) 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 key를 셸 단계에 전달하는 대신 openai/codex-action을 사용하세요. 이 액션은 OpenAI API key를 위한 보안 프록시를 시작합니다.
CI 워크플로가 실패할 때 Codex를 사용하여 자동으로 수정안을 제안할 수 있습니다. 패턴은 다음과 같습니다.
- 기본 CI 워크플로가 오류와 함께 완료되면 후속 워크플로를 트리거합니다.
- 저장소 읽기 권한만으로 실패한 커밋을 체크아웃합니다.
- Codex를 실행하기 전에 OpenAI API key를 해당 단계에 노출하지 않고 설정 명령을 실행합니다.
- Codex GitHub Action을 실행합니다.
- Codex의 로컬 변경 사항을 패치 아티팩트로 저장합니다.
- 별도의 작업에서 패치를 적용하고 풀 리퀘스트를 엽니다.
아래 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 함께 사용하기
프롬프트와 stdin을 함께 사용하는 방식은 다른 명령이 Codex에서 검사할 데이터를 이미 생성하는 경우에 유용합니다. 이 모드에서는 지침을 직접 작성하고 출력을 컨텍스트로 파이프하므로 명령 출력, 로그, 생성된 데이터를 중심으로 구성된 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.mdTLS 또는 HTTP 문제 검사하기
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.mdSlack에 바로 게시할 수 있는 업데이트 준비하기
gh run view 123456 --log \
| codex exec "write a concise Slack-ready update on the CI failure, including the likely cause and next step" \
| pbcopyCI 로그를 바탕으로 풀 리퀘스트 댓글 초안 작성하기
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 -을 사용하세요.
- 센티널은 다른 명령이나 스크립트가 전체 프롬프트를 동적으로 생성할 때 유용합니다. 프롬프트를 파일에 저장하거나, 셸 스크립트로 프롬프트를 조합하거나, 실시간 명령 출력과 지침을 결합한 후 전체 프롬프트를 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