Nicht interaktiver Modus

Im nicht interaktiven Modus können Sie Codex aus Skripten heraus ausführen (beispielsweise in Continuous-Integration-Aufträgen (CI)), ohne die interaktive TUI zu öffnen. Sie rufen ihn mit codex exec auf.

Details zu den einzelnen Flags finden Sie unter codex exec.

Wann Sie codex exec verwenden sollten

Verwenden Sie codex exec, wenn Codex Folgendes tun soll:

• Als Teil einer Pipeline ausgeführt werden (CI, Prüfungen vor dem Zusammenführen, geplante Aufträge).
• Ausgaben erzeugen, die Sie an andere Tools weiterleiten können (beispielsweise zum Erstellen von Versionshinweisen oder Zusammenfassungen).
• Sich nahtlos in CLI-Workflows einfügen, die Befehlsausgaben an Codex und die Codex-Ausgabe an andere Tools weiterleiten.
• Mit expliziten, vorab festgelegten Sandbox- und Genehmigungseinstellungen ausgeführt werden.

Grundlegende Verwendung

Übergeben Sie eine Aufgabenanweisung als einzelnes Argument:

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

Während codex exec ausgeführt wird, schreibt Codex den Fortschritt fortlaufend nach stderr und gibt nur die abschließende Agentennachricht auf stdout aus. Dadurch lässt sich das Endergebnis einfach umleiten oder weiterleiten:

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

Verwenden Sie --ephemeral, wenn Sie die Sitzungs-Rollout-Dateien nicht dauerhaft auf dem Datenträger speichern möchten:

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

Wenn stdin weitergeleitet wird und Sie zusätzlich ein Prompt-Argument angeben, behandelt Codex den Prompt als Anweisung und den weitergeleiteten Inhalt als zusätzlichen Kontext.

So können Sie die Eingabe einfach mit einem Befehl erzeugen und direkt an Codex übergeben:

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

Weitere fortgeschrittene Muster für die Weiterleitung über stdin finden Sie unter Fortgeschrittene stdin-Weiterleitung.

Berechtigungen und Sicherheit

Standardmäßig wird codex exec in einer schreibgeschützten Sandbox ausgeführt. Legen Sie für Automatisierungen nur die mindestens für den Workflow erforderlichen Berechtigungen fest:

• Bearbeitungen zulassen: codex exec --sandbox workspace-write "<task>"
• Umfassenderen Zugriff zulassen: codex exec --sandbox danger-full-access "<task>"

Verwenden Sie danger-full-access nur in einer kontrollierten Umgebung (beispielsweise in einem isolierten CI-Runner oder Container).

Codex behält codex exec --full-auto als veraltetes Kompatibilitäts-Flag bei und gibt eine Warnung aus. Verwenden Sie in neuen Skripten vorzugsweise das explizite Flag --sandbox workspace-write.

Verwenden Sie --ignore-user-config, wenn bei einer Ausführung $CODEX_HOME/config.toml nicht geladen werden soll, und --ignore-rules, wenn Sie in einer kontrollierten Automatisierungsumgebung die benutzer- und projektspezifischen Execpolicy-Dateien .rules überspringen müssen.

Wenn Sie einen aktivierten MCP-Server mit required = true konfigurieren und seine Initialisierung fehlschlägt, wird codex exec mit einem Fehler beendet, anstatt ohne diesen Server fortzufahren.

Maschinenlesbare Ausgabe erzeugen

Verwenden Sie die Ausgabe im JSON-Lines-Format, um Codex-Ausgaben in Skripten zu verarbeiten:

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

Wenn Sie --json aktivieren, wird stdout zu einem JSON-Lines-Datenstrom (JSONL), sodass Sie jedes Ereignis erfassen können, das Codex während der Ausführung ausgibt. Zu den Ereignistypen gehören thread.started, turn.started, turn.completed, turn.failed, item.* und error.

Zu den Elementtypen gehören Agentennachrichten, Schlussfolgerungen, Befehlsausführungen, Dateiänderungen, MCP-Tool-Aufrufe, Websuchen und Planaktualisierungen.

Beispiel für einen JSON-Datenstrom (jede Zeile ist ein JSON-Objekt):

{"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}}

Wenn Sie nur die abschließende Nachricht benötigen, schreiben Sie sie mit -o <path>/--output-last-message <path> in eine Datei. Dadurch wird die abschließende Nachricht in die Datei geschrieben und weiterhin auf stdout ausgegeben (Details finden Sie unter codex exec).

Strukturierte Ausgaben mit einem Schema erstellen

Wenn Sie strukturierte Daten für nachgelagerte Schritte benötigen, verwenden Sie --output-schema, um eine abschließende Antwort anzufordern, die einem JSON Schema entspricht. Dies ist für automatisierte Workflows nützlich, die stabile Felder benötigen (beispielsweise Auftragszusammenfassungen, Risikoberichte oder Veröffentlichungsmetadaten).

schema.json

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

Führen Sie Codex mit dem Schema aus und schreiben Sie die abschließende JSON-Antwort auf den Datenträger:

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

Beispiel für die abschließende Ausgabe (stdout):

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

In Automatisierungen authentifizieren

codex exec verwendet standardmäßig die gespeicherte CLI-Authentifizierung erneut. In CI ist es üblich, Anmeldedaten explizit bereitzustellen:

Authentifizierung mit API key verwenden

Verwenden Sie für GitHub Actions die Codex GitHub Action, anstatt die CLI selbst zu installieren und zu authentifizieren. Die Action wurde entwickelt, um die Offenlegung des API key zu verringern, indem sie Codex installiert, einen Responses API-Proxy startet und Codex mit einer konfigurierbaren Sicherheitsstrategie ausführt.

Legen Sie OPENAI_API_KEY oder CODEX_API_KEY nicht als Umgebungsvariable auf Auftragsebene in Workflows fest, die vom Repository kontrollierten Code auschecken oder ausführen. Build-Skripte, Tests, Lebenszyklus-Hooks von Abhängigkeiten oder eine kompromittierte Action im selben Auftrag können diese Umgebungsvariablen auslesen.

Legen Sie für andere Automatisierungsumgebungen CODEX_API_KEY nur für den einzelnen Aufruf von codex exec fest und stellen Sie sicher, dass in derselben Prozessumgebung kein nicht vertrauenswürdiger Code ausgeführt wird.

Um für eine einzelne Ausführung einen anderen API key zu verwenden, legen Sie CODEX_API_KEY inline fest:

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

CODEX_API_KEY wird nur in codex exec unterstützt.

Eine nicht interaktive Sitzung fortsetzen

Wenn Sie eine vorherige Ausführung fortsetzen müssen (beispielsweise in einer zweistufigen Pipeline), verwenden Sie den Unterbefehl resume:

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

Sie können mit codex exec resume <SESSION_ID> auch eine bestimmte Sitzungs-ID angeben.

Git-Repository erforderlich

Codex setzt voraus, dass Befehle innerhalb eines Git-Repositorys ausgeführt werden, um destruktive Änderungen zu verhindern. Umgehen Sie diese Prüfung mit codex exec --skip-git-repo-check, wenn Sie sicher sind, dass die Umgebung sicher ist.

Gängige Automatisierungsmuster

Beispiel: CI-Fehler in GitHub Actions automatisch beheben

Verwenden Sie für GitHub-Actions-Workflows openai/codex-action, anstatt Codex zu installieren und den API key an einen Shell-Schritt zu übergeben. Die Action startet einen sicheren Proxy für den OpenAI API key.

Sie können Codex verwenden, um automatisch Korrekturen vorzuschlagen, wenn ein CI-Workflow fehlschlägt. Das Muster sieht wie folgt aus:

1. Lösen Sie einen nachgelagerten Workflow aus, wenn Ihr Haupt-CI-Workflow mit einem Fehler abgeschlossen wird.
2. Checken Sie den fehlgeschlagenen Commit ausschließlich mit Leseberechtigungen für das Repository aus.
3. Führen Sie Einrichtungsbefehle vor Codex aus, ohne diesen Schritten Ihren OpenAI API key offenzulegen.
4. Führen Sie die Codex GitHub Action aus.
5. Speichern Sie die lokalen Änderungen von Codex als Patch-Artefakt.
6. Wenden Sie den Patch in einem separaten Auftrag an und öffnen Sie einen Pull Request.

Der nachfolgende Codex-Auftrag verfügt nur über contents: read. Nachdem Codex ausgeführt wurde, serialisiert er lediglich den Diff als Artefakt. Der Auftrag open_pr erhält Schreibberechtigungen für das Repository, aber nicht OPENAI_API_KEY.

Das Beispiel setzt ein Node.js-Projekt voraus. Passen Sie die Einrichtungs- und Testbefehle an Ihren Technologie-Stack an.

Eine ausführlichere Sicherheitscheckliste finden Sie in den Sicherheitshinweisen zur 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

Fortgeschrittene stdin-Weiterleitung

Wenn ein anderer Befehl Eingaben für Codex erzeugt, wählen Sie das stdin-Muster danach aus, woher die Anweisung stammen soll. Verwenden Sie Prompt-plus-stdin, wenn die Anweisung bereits feststeht und Sie die weitergeleitete Ausgabe als Kontext übergeben möchten. Verwenden Sie codex exec -, wenn stdin zum vollständigen Prompt werden soll.

Prompt-plus-stdin verwenden

Prompt-plus-stdin ist nützlich, wenn ein anderer Befehl bereits die Daten erzeugt, die Codex untersuchen soll. In diesem Modus schreiben Sie die Anweisung selbst und leiten die Ausgabe als Kontext weiter. Damit eignet er sich ideal für CLI-Workflows, die auf Befehlsausgaben, Protokollen und generierten Daten basieren.

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 -

codex exec - verwenden, wenn stdin der Prompt ist

Wenn Sie das Prompt-Argument weglassen, liest Codex den Prompt aus stdin. Verwenden Sie codex exec -, wenn Sie dieses Verhalten ausdrücklich erzwingen möchten.

Der Sentinel - ist nützlich, wenn ein anderer Befehl oder ein anderes Skript den gesamten Prompt dynamisch erzeugt. Dies eignet sich gut, wenn Sie Prompts in Dateien speichern, Prompts mit Shell-Skripten zusammensetzen oder aktuelle Befehlsausgaben mit Anweisungen kombinieren, bevor Sie den gesamten Prompt an Codex übergeben.

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