Im nicht interaktiven Modus kannst du Codex aus Skripten aufrufen, etwa in Jobs für die kontinuierliche Integration (CI), ohne die interaktive Terminaloberfläche (TUI) zu öffnen.
Dazu verwendest du codex exec.
Details zu den einzelnen Optionen findest du in der Referenz zu codex exec.
Wann du codex exec verwendest
Verwende codex exec, wenn du Folgendes tun möchtest:
- Codex in einer Pipeline ausführen, etwa in der CI, bei Prüfungen vor dem Merge oder in zeitgesteuerten Jobs.
- Ausgaben per Pipe an andere Tools weitergeben, etwa um Versionshinweise oder Zusammenfassungen zu erstellen.
- Codex in CLI-Workflows einbinden, die Befehlsausgaben an Codex übergeben und die Ausgabe von Codex an andere Tools weiterleiten.
- Codex mit Einstellungen für die Sandbox und für Genehmigungen ausführen, die du vorab ausdrücklich festgelegt hast.
Grundlagen
Übergib den Prompt für die Aufgabe als einzelnes Argument:
codex exec "summarize the repository structure and list the top 5 risky areas"
Während codex exec läuft, meldet Codex den Fortschritt fortlaufend über stderr. Auf stdout gibt Codex nur die abschließende Nachricht des Agenten aus. So kannst du das Ergebnis direkt umleiten oder per Pipe weitergeben:
codex exec "generate release notes for the last 10 commits" | tee release-notes.md
Verwende --ephemeral, wenn du die Rollout-Dateien der Sitzung nicht dauerhaft auf dem Datenträger speichern möchtest:
codex exec --ephemeral "triage this repository and suggest next steps"
Wenn die Home-Verzeichnisse deiner Worker über das Netzwerk eingebunden sind, erfährst du hier, wie du den Jobzustand lokal speicherst und die Rollout-Dateien der Sitzung aufbewahrst.
Wenn du Daten per Pipe an stdin übergibst und zusätzlich einen Prompt als Argument angibst, verwendet Codex den Prompt als Anweisung und die Daten aus der Pipe als zusätzlichen Kontext.
So kannst du mit einem Befehl Eingabedaten erzeugen und sie direkt an Codex weitergeben:
curl -s https://jsonplaceholder.typicode.com/comments \
| codex exec "format the top 20 items into a markdown table" \
> table.md
Weitere Möglichkeiten beschreibt der Abschnitt Eingaben über stdin weiterleiten.
Berechtigungen und Sicherheit
Standardmäßig läuft codex exec in einer Sandbox ohne Schreibzugriff. Erteile bei der Automatisierung nur die Berechtigungen, die der Workflow benötigt:
- Änderungen erlauben:
codex exec --sandbox workspace-write "<task>" - Weitergehenden Zugriff erlauben:
codex exec --sandbox danger-full-access "<task>"
Verwende danger-full-access nur in einer kontrollierten Umgebung, etwa auf einem isolierten CI-Runner oder in einem isolierten Container.
--full-auto wird nicht mehr unterstützt. Stelle deine Skripte auf --sandbox workspace-write um. Alternativ kannst du mit --approve-for-me die workspace-write-Sandbox verwenden und Genehmigungsanfragen automatisch überprüfen lassen.
Wenn du codex exec oder codex review lokal ausführst, lädt Codex die Projektkonfiguration und die im Projekt definierten MCP-Server nur bei vertrauenswürdigen Projekten. Das gilt auch in einer Sandbox mit Schreibzugriff. Mit --trust kennzeichnest du das Projekt für diesen und künftige Chats als vertrauenswürdig. Im Projekt definierte MCP-Server können Befehle außerhalb der Sandbox ausführen.
Die Vertrauenseinstellung bleibt auch mit --ephemeral erhalten. Wenn du das Projekt als nicht vertrauenswürdig gekennzeichnet hast, ändere zuerst diese Einstellung. Du kannst --trust und --ignore-user-config nicht kombinieren.
Verwende --ignore-user-config, wenn Codex bei einem Lauf $CODEX_HOME/config.toml nicht laden soll. Mit --ignore-rules kannst du in einer kontrollierten Automatisierungsumgebung die benutzer- und projektspezifischen .rules-Dateien für execpolicy überspringen.
Wenn du für einen aktivierten MCP-Server required = true festlegst und der Server sich nicht initialisieren lässt, beendet sich codex exec mit einem Fehler, statt ohne diesen Server weiterzulaufen.
Maschinenlesbare Ausgabe erzeugen
Wenn du die Ausgabe von Codex in Skripten verarbeiten möchtest, verwende das Format JSON Lines:
codex exec --json "summarize the repo structure" | jq
Wenn du --json aktivierst, liefert stdout einen Datenstrom im Format JSON Lines (JSONL). Damit kannst du jedes Ereignis erfassen, das Codex während des Laufs ausgibt. Zu den Ereignistypen gehören thread.started, turn.started, turn.completed, turn.failed, item.* und error.
Zu den Eintragstypen gehören Nachrichten des Agenten, Reasoning, Befehlsausführungen, Dateiänderungen, Aufrufe von MCP-Tools, Websuchen und Aktualisierungen des Plans.
Beispiel für einen JSON-Datenstrom, in dem jede Zeile ein JSON-Objekt enthält:
{"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 du nur die abschließende Nachricht brauchst, schreibe sie mit -o <path> oder --output-last-message <path> in eine Datei. Codex speichert die Nachricht in der Datei und gibt sie weiterhin auf stdout aus. Details findest du in der Referenz zu codex exec.
Strukturierte Ausgaben mit einem Schema erstellen
Wenn du strukturierte Daten für nachfolgende Schritte brauchst, fordere mit --output-schema eine abschließende Antwort an, die einem JSON-Schema entspricht.
Das eignet sich für automatisierte Workflows, die auf gleichbleibende Felder angewiesen sind, etwa für Jobzusammenfassungen, Risikoberichte oder Release-Metadaten.
schema.json
{
"type": "object",
"properties": {
"project_name": { "type": "string" },
"programming_languages": {
"type": "array",
"items": { "type": "string" }
}
},
"required": ["project_name", "programming_languages"],
"additionalProperties": false
}
Führe Codex mit dem Schema aus und speichere die abschließende JSON-Antwort in einer Datei:
codex exec "Extract project metadata" \
--output-schema ./schema.json \
-o ./project-metadata.json
Beispiel für die abschließende Ausgabe auf stdout:
{
"project_name": "Codex CLI",
"programming_languages": ["Rust", "TypeScript", "Shell"]
}
Authentifizierung bei der Automatisierung
codex exec verwendet standardmäßig die gespeicherten Anmeldedaten der CLI. In CI-Jobs ist es üblich, die Zugangsdaten ausdrücklich anzugeben.
Mit einem API-Schlüssel authentifizieren
Verwende für GitHub Actions die Codex GitHub Action, statt die CLI selbst zu installieren und dich darüber anzumelden. Die Action soll das Risiko verringern, dass der API-Schlüssel offengelegt wird. Dazu installiert sie Codex, startet einen Proxy für die Responses API und führt Codex mit einer konfigurierbaren Sicherheitsstrategie aus.
Setze weder OPENAI_API_KEY noch CODEX_API_KEY als Umgebungsvariable für den gesamten Job, wenn der Workflow Code aus dem Repository auscheckt oder ausführt. Build-Skripte, Tests, Lifecycle-Hooks von Abhängigkeiten oder eine kompromittierte Action im selben Job können diese Umgebungsvariablen lesen.
Setze CODEX_API_KEY in anderen Automatisierungsumgebungen nur für den Codex-Aufruf, der den Schlüssel benötigt. Stelle sicher, dass in derselben Prozessumgebung ausschließlich vertrauenswürdiger Code läuft.
Wenn du für einen einzelnen Lauf einen anderen API-Schlüssel verwenden möchtest, setze CODEX_API_KEY direkt beim Aufruf:
CODEX_API_KEY=<api-key> codex exec --json "triage open bug reports"
Du kannst CODEX_API_KEY mit codex exec, codex review, dem TypeScript-SDK und codex exec-server --remote verwenden.
Von ChatGPT verwaltete Authentifizierung in CI/CD verwenden (für Fortgeschrittene)
Lies diesen Abschnitt, wenn du CI/CD-Jobs mit einem Codex-Konto statt mit einem API-Schlüssel ausführen musst. Das gilt etwa für Teams in Unternehmen, die auf vertrauenswürdigen Runnern einen von ChatGPT verwalteten Codex-Zugriff verwenden. Es gilt auch, wenn du die Ratenlimits von ChatGPT/Codex benötigst, statt Codex über einen API-Schlüssel zu nutzen.
Für die Automatisierung sind API-Schlüssel die erste Wahl, weil sie sich einfacher bereitstellen und regelmäßig austauschen lassen. Verwende die hier beschriebene Methode nur, wenn Codex ausdrücklich unter deinem Konto laufen muss.
Behandle ~/.codex/auth.json wie ein Passwort. Die Datei enthält Zugriffstoken. Nimm sie nicht in einen Commit auf, kopiere ihren Inhalt nicht in Tickets und teile sie nicht im Chat.
Verwende diesen Workflow nicht für öffentliche oder Open-Source-Repositorys. Wenn du codex login auf dem Runner nicht verwenden kannst, stelle auth.json für den ersten Lauf aus einem sicheren Speicher bereit. Führe Codex auf dem Runner aus, damit Codex die Datei dort aktualisiert. Bewahre die aktualisierte Datei zwischen den Läufen auf.
Weitere Informationen findest du im Abschnitt Authentifizierung mit einem Codex-Konto in CI/CD aufrechterhalten (für Fortgeschrittene).
Eine nicht interaktive Sitzung fortsetzen
Wenn du einen früheren Lauf fortsetzen möchtest, etwa in einer zweistufigen Pipeline, verwende den Unterbefehl resume:
codex exec "review the change for race conditions"
codex exec resume --last "fix the race conditions you found"
Mit codex exec resume <SESSION_ID> kannst du auch gezielt eine Sitzung anhand ihrer ID fortsetzen.
Git-Repository erforderlich
Codex setzt voraus, dass Befehle innerhalb eines Git-Repositorys laufen, um destruktive Änderungen zu verhindern. Wenn du dich von der Sicherheit der Umgebung überzeugt hast, kannst du diese Prüfung mit codex exec --skip-git-repo-check überspringen.
Typische Abläufe bei der Automatisierung
Beispiel für GitHub Actions: CI-Fehler automatisch beheben
Verwende für Workflows in GitHub Actions openai/codex-action, statt Codex selbst zu installieren und den API-Schlüssel an einen Shell-Schritt zu übergeben. Die Action startet einen sicheren Proxy für den OpenAI-API-Schlüssel.
Wenn ein CI-Workflow fehlschlägt, kannst du Codex automatisch eine Korrektur vorschlagen lassen. Gehe dazu so vor:
- Starte einen Folgeworkflow, wenn dein Haupt-CI-Workflow mit einem Fehler endet.
- Checke den Commit, bei dem der Fehler aufgetreten ist, nur mit Leserechten für das Repository aus.
- Führe die Setup-Befehle vor Codex aus, ohne diesen Schritten Zugriff auf deinen OpenAI-API-Schlüssel zu geben.
- Führe die Codex GitHub Action aus.
- Speichere die lokalen Änderungen von Codex als Patch-Artefakt.
- Wende den Patch in einem separaten Job an und öffne einen Pull Request.
Der Codex-Job im folgenden Beispiel hat nur die Berechtigung contents: read. Nach dem Codex-Lauf speichert er lediglich den Diff als Artefakt. Der Job open_pr erhält Schreibrechte für das Repository, aber keinen Zugriff auf OPENAI_API_KEY.
Das Beispiel geht von einem Node.js-Projekt aus. Passe die Setup- und Testbefehle an deinen Stack an.
Eine ausführlichere Sicherheitscheckliste findest du 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
Eingaben über stdin weiterleiten
Wenn ein anderer Befehl die Eingabe für Codex erzeugt, hängt die Verwendung von stdin davon ab, woher die Anweisung kommt. Kennst du die Anweisung bereits, übergib sie als Prompt und leite die Befehlsausgabe per Pipe als Kontext weiter. Verwende codex exec -, wenn stdin den vollständigen Prompt liefern soll.
Einen Prompt mit Daten aus stdin kombinieren
Die Kombination eignet sich, wenn ein anderer Befehl bereits die Daten liefert, die Codex untersuchen soll. Du formulierst die Anweisung selbst und übergibst die Befehlsausgabe per Pipe als Kontext. Das ist besonders praktisch für CLI-Workflows, in denen du mit Befehlsausgaben, Logs oder generierten Daten arbeitest.
npm test 2>&1 \
| codex exec "summarize the failing tests and propose the smallest likely fix" \
| tee test-summary.md
Weitere Beispiele für Prompts mit Daten aus stdin
Logs zusammenfassen
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- oder HTTP-Probleme untersuchen
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.mdEine Statusmeldung für Slack vorbereiten
gh run view 123456 --log \
| codex exec "write a concise Slack-ready update on the CI failure, including the likely cause and next step" \
| pbcopyAus CI-Logs einen Kommentar für einen Pull Request formulieren
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 den Prompt liefert
Wenn du keinen Prompt als Argument angibst, liest Codex den Prompt aus stdin. Mit codex exec - kannst du dieses Verhalten ausdrücklich erzwingen.
Das Sonderargument - ist praktisch, wenn ein anderer Befehl oder ein Skript den gesamten Prompt dynamisch erzeugt. Das bietet sich an, wenn du Prompts in Dateien speicherst, mit Shell-Skripten zusammensetzt oder aktuelle Befehlsausgaben mit Anweisungen kombinierst, bevor du den vollständigen Prompt an Codex übergibst.
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