Mode noninteraktif

Mode noninteraktif memungkinkan Anda menjalankan Codex dari skrip (misalnya, tugas integrasi berkelanjutan (CI)) tanpa membuka TUI interaktif. Anda memanggilnya dengan codex exec.

Untuk detail tingkat flag, lihat codex exec.

Kapan menggunakan codex exec

Gunakan codex exec saat Anda ingin Codex:

• Berjalan sebagai bagian dari pipeline (CI, pemeriksaan pra-penggabungan, tugas terjadwal).
• Menghasilkan output yang dapat Anda salurkan ke alat lain (misalnya, untuk membuat catatan rilis atau ringkasan).
• Menyatu secara alami dengan alur kerja CLI yang merangkai output perintah sebagai input Codex dan meneruskan output Codex ke alat lain.
• Berjalan dengan pengaturan sandbox dan persetujuan yang eksplisit dan telah ditetapkan sebelumnya.

Penggunaan dasar

Berikan prompt tugas sebagai satu argumen:

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

Saat codex exec berjalan, Codex mengalirkan progres ke stderr dan hanya mencetak pesan terakhir agen ke stdout. Hal ini memudahkan pengalihan atau penyaluran hasil akhir:

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

Gunakan --ephemeral jika Anda tidak ingin menyimpan file rollout sesi ke disk:

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

Jika stdin disalurkan dan Anda juga memberikan argumen prompt, Codex memperlakukan prompt sebagai instruksi dan konten yang disalurkan sebagai konteks tambahan.

Dengan demikian, Anda dapat dengan mudah menghasilkan input menggunakan satu perintah dan menyerahkannya langsung ke Codex:

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

Untuk pola penyaluran stdin yang lebih lanjut, lihat Penyaluran stdin lanjutan.

Izin dan keamanan

Secara default, codex exec berjalan dalam sandbox hanya-baca. Dalam otomatisasi, tetapkan izin minimum yang diperlukan alur kerja:

• Izinkan pengeditan: codex exec --sandbox workspace-write "<task>"
• Izinkan akses lebih luas: codex exec --sandbox danger-full-access "<task>"

Gunakan danger-full-access hanya dalam lingkungan terkendali (misalnya, runner CI atau kontainer yang terisolasi).

Codex mempertahankan codex exec --full-auto sebagai flag kompatibilitas yang tidak digunakan lagi dan mencetak peringatan. Utamakan flag --sandbox workspace-write yang eksplisit dalam skrip baru.

Gunakan --ignore-user-config saat Anda memerlukan eksekusi yang tidak memuat $CODEX_HOME/config.toml, dan --ignore-rules saat Anda perlu melewati file execpolicy .rules pengguna dan proyek untuk lingkungan otomatisasi terkendali.

Jika Anda mengonfigurasi server MCP aktif dengan required = true dan server tersebut gagal diinisialisasi, codex exec berhenti dengan kesalahan alih-alih melanjutkan tanpa server tersebut.

Membuat output yang dapat dibaca mesin

Untuk menggunakan output Codex dalam skrip, gunakan output JSON Lines:

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

Saat Anda mengaktifkan --json, stdout menjadi aliran JSON Lines (JSONL) sehingga Anda dapat merekam setiap peristiwa yang dikeluarkan Codex selama berjalan. Jenis peristiwa mencakup thread.started, turn.started, turn.completed, turn.failed, item.*, dan error.

Jenis item mencakup pesan agen, penalaran, eksekusi perintah, perubahan file, pemanggilan alat MCP, pencarian web, dan pembaruan rencana.

Contoh aliran JSON (setiap baris adalah objek 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}}

Jika Anda hanya memerlukan pesan terakhir, tulis pesan tersebut ke file dengan -o <path>/--output-last-message <path>. Perintah ini menulis pesan terakhir ke file dan tetap mencetaknya ke stdout (lihat codex exec untuk detail).

Membuat output terstruktur dengan skema

Jika Anda memerlukan data terstruktur untuk langkah berikutnya, gunakan --output-schema untuk meminta respons akhir yang mematuhi JSON Schema. Fitur ini berguna untuk alur kerja otomatis yang memerlukan kolom stabil (misalnya, ringkasan tugas, laporan risiko, atau metadata rilis).

schema.json

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

Jalankan Codex dengan skema tersebut dan tulis respons JSON akhir ke disk:

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

Contoh output akhir (stdout):

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

Melakukan autentikasi dalam otomatisasi

codex exec menggunakan kembali autentikasi CLI yang tersimpan secara default. Dalam CI, kredensial biasanya diberikan secara eksplisit:

Menggunakan autentikasi API key

Untuk GitHub Actions, gunakan Codex GitHub Action alih-alih menginstal dan mengautentikasi CLI sendiri. Tindakan ini dirancang untuk mengurangi paparan API key dengan menginstal Codex, memulai proksi Responses API, dan menjalankan Codex menggunakan strategi keamanan yang dapat dikonfigurasi.

Jangan tetapkan OPENAI_API_KEY atau CODEX_API_KEY sebagai variabel lingkungan tingkat tugas dalam alur kerja yang melakukan checkout atau menjalankan kode yang dikendalikan repositori. Skrip build, pengujian, hook siklus hidup dependensi, atau tindakan yang disusupi dalam tugas yang sama dapat membaca variabel lingkungan tersebut.

Untuk lingkungan otomatisasi lain, tetapkan CODEX_API_KEY hanya untuk satu pemanggilan codex exec dan pastikan tidak ada kode yang tidak tepercaya berjalan dalam lingkungan proses yang sama.

Untuk menggunakan API key lain pada satu eksekusi, tetapkan CODEX_API_KEY secara sebaris:

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

CODEX_API_KEY hanya didukung dalam codex exec.

Melanjutkan sesi noninteraktif

Jika Anda perlu melanjutkan eksekusi sebelumnya (misalnya, pipeline dua tahap), gunakan subperintah resume:

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

Anda juga dapat menargetkan ID sesi tertentu dengan codex exec resume <SESSION_ID>.

Repositori Git diperlukan

Codex mengharuskan perintah dijalankan di dalam repositori Git untuk mencegah perubahan destruktif. Lewati pemeriksaan ini dengan codex exec --skip-git-repo-check jika Anda yakin lingkungannya aman.

Pola otomatisasi umum

Contoh: Memperbaiki kegagalan CI secara otomatis di GitHub Actions

Untuk alur kerja GitHub Actions, gunakan openai/codex-action alih-alih menginstal Codex dan meneruskan API key ke langkah shell. Tindakan ini memulai proksi aman untuk API key OpenAI.

Anda dapat menggunakan Codex untuk mengusulkan perbaikan secara otomatis saat alur kerja CI gagal. Polanya adalah:

1. Picu alur kerja lanjutan saat alur kerja CI utama Anda selesai dengan kesalahan.
2. Lakukan checkout commit yang gagal hanya dengan izin baca repositori.
3. Jalankan perintah penyiapan sebelum Codex tanpa mengekspos API key OpenAI Anda ke langkah-langkah tersebut.
4. Jalankan Codex GitHub Action.
5. Simpan perubahan lokal Codex sebagai artefak patch.
6. Dalam tugas terpisah, terapkan patch dan buka pull request.

Tugas Codex di bawah ini hanya memiliki contents: read. Setelah Codex berjalan, tugas tersebut hanya menserialisasikan diff sebagai artefak. Tugas open_pr menerima izin tulis repositori, tetapi tidak menerima OPENAI_API_KEY.

Contoh ini mengasumsikan proyek Node.js. Sesuaikan perintah penyiapan dan pengujian dengan tumpukan teknologi Anda.

Untuk daftar periksa keamanan yang lebih mendalam, lihat panduan keamanan 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

Penyaluran stdin lanjutan

Saat perintah lain menghasilkan input untuk Codex, pilih pola stdin berdasarkan sumber instruksi. Gunakan prompt-plus-stdin jika Anda sudah mengetahui instruksinya dan ingin meneruskan output yang disalurkan sebagai konteks. Gunakan codex exec - saat stdin harus menjadi prompt lengkap.

Menggunakan prompt-plus-stdin

Prompt-plus-stdin berguna saat perintah lain telah menghasilkan data yang ingin Anda minta Codex periksa. Dalam mode ini, Anda menulis instruksi sendiri dan menyalurkan output sebagai konteks, sehingga pola ini sangat sesuai untuk alur kerja CLI yang dibangun berdasarkan output perintah, log, dan data yang dihasilkan.

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 -

Menggunakan codex exec - saat stdin adalah prompt

Jika Anda menghilangkan argumen prompt, Codex membaca prompt dari stdin. Gunakan codex exec - jika Anda ingin memaksakan perilaku tersebut secara eksplisit.

Sentinel - berguna saat perintah atau skrip lain menghasilkan seluruh prompt secara dinamis. Pola ini cocok ketika Anda menyimpan prompt dalam file, menyusun prompt dengan skrip shell, atau menggabungkan output perintah langsung dengan instruksi sebelum menyerahkan seluruh prompt ke 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