Codex Exec: Deployment-Checks im Terminal automatisieren

codex exec führt Codex ohne die interaktive Terminal-Schnittstelle aus. Übergeben Sie einen Prompt oder leiten Sie Daten ein, und speichern Sie die Antwort für Ihren nächsten Skript-Schritt. Diese Anleitung erstellt einen Deployment-Bericht mit JSONL-Events, einem Schema-beschränkten Ergebnis und einem Exit-Code basierend auf echten HTTP-Checks.

Sie testen zwei Versionen einer kleinen Preisberechnungs-API: Eine funktioniert, und eine gibt HTTP 200 von ihrem Zustands-Endpoint zurück, während die Preisberechnungs-Route fehlschlägt. Das vollständige Beispiel enthält den Collector, das Berichtsschema und das Validierungsskript.

Codex ohne interaktive Schnittstelle ausführen

Führen Sie in einem vertrauenswürdigen Git-Repository Folgendes aus:

codex exec --sandbox read-only \
  "Summarize this repository in three sentences. Do not change files."

Codex schreibt den Fortschritt nach stderr und seine endgültige Antwort nach stdout. Sie können diese Antwort in eine Datei umleiten. Der offizielle nicht-interaktive Leitfaden behandelt dieses Verhalten und die unterstützten Automatisierungsmuster.

Für einen Deployment-Bericht stellen wir die Beobachtungen über stdin bereit. Ein kleiner Python-Collector führt die Netzwerkanfragen durch. Codex erklärt die Prüfdaten, und eine separate Funktion prüft den Bericht anhand dieser Beobachtungen.

Die drei Ausgabedateien verstehen

Diese Dateien haben unterschiedliche Rollen:

--json verwandelt stdout in einen Event-Stream. Es macht nicht den gesamten Stream zu einem einzigen Berichtsobjekt. --output-schema beschreibt die endgültige Antwort, und -o speichert diese Antwort separat. Diese Unterscheidung verhindert einen häufigen Automatisierungsfehler: den Versuch, das gesamte Event-Protokoll mit einem einzigen JSON-Lesevorgang zu parsen.

Das Beispiel vorbereiten

Verwenden Sie Python 3.10 oder neuer und eine authentifizierte Codex CLI. Die Python-Dateien benötigen keine Drittanbieter-Pakete. Die folgenden Shell-Befehle richten sich an Bash oder Zsh unter macOS oder Linux.

codex --version
codex login status
mkdir codex-deployment-check
cd codex-deployment-check
for file in demo.py collect.py gate.py run.py report.schema.json verify.py; do
  curl --fail --silent --show-error \
    "https://lizard.build/blog-examples/agent-deployment-checks/$file" \
    --output "$file"
done

Lesen Sie die heruntergeladenen Dateien, bevor Sie sie ausführen. Starten Sie die Demo und lassen Sie sie laufen:

python3 demo.py --port 8787

Die Anwendung hat zwei GET-Routen. /healthz gibt status: ok zurück. /api/quote?quantity=3 führt eine Preisberechnung für drei Artikel zu je 1.200 Cent durch. Das erwartete Ergebnis ist 36,00 $ (3.600 Cent). Das Beispiel verwendet ganzzahlige Cent-Beträge, um Rundungsfehler in der Assertion zu vermeiden.

Öffnen Sie ein weiteres Terminal im selben Ordner für die restlichen Befehle.

Die HTTP-Prüfdaten sammeln und prüfen

python3 collect.py http://127.0.0.1:8787 > evidence.json

Der Collector zeichnet die URL, die Prüfzeit, den HTTP-Status und die Übereinstimmung jeder Antwort mit den erwarteten Feldern auf. Er führt zwei begrenzte Anfragen durch, lehnt Weiterleitungen ab und begrenzt jede Antwort auf 64 KiB. Er sendet erwartete Werte und Booleans an das Modell, ohne beliebigen Antworttext zu kopieren.

Ersetzen Sie für Ihre Anwendung die Demo-Pfade und erwarteten Werte in collect.py und gate.py. Wählen Sie eine Route, die nützliches Verhalten ausführt: einen Preis berechnen, einen vorbereiteten Datenbankeintrag lesen oder ein vorhandenes Dokument abrufen. Gleichen Sie sowohl den Antwortinhalt als auch den Statuscode ab.

Der Exit-Code des Collectors gibt an, ob er Prüfdaten gesammelt hat. Ein fehlgeschlagener Anwendungs-Check erzeugt dennoch eine Prüfdatendatei, damit Codex den Fehler erklären kann. Das finale Prüfskript bestimmt das Ergebnis des Jobs.

Einen strukturierten Bericht anfordern

Führen Sie in einem vertrauenswürdigen Git-Repository, das die Dateien enthält, Folgendes aus:

codex exec --ignore-user-config --ephemeral \
  --sandbox read-only \
  --json \
  --output-schema report.schema.json \
  -o report.json \
  "Explain the evidence on stdin. Use no tools. Copy its verdict, list failed check names in failed_checks, and give a summary and next_step. Do not infer a root cause from HTTP status alone." \
  < evidence.json > events.jsonl 2> stderr.log

Wenn Sie nur den neuen Download-Ordner verwenden, fügen Sie --skip-git-repo-check hinzu. Der vollständige Wrapper tut dies in einem temporären Verzeichnis, das für den Bericht erstellt wurde. Verwenden Sie dieses Flag bewusst, wenn kein Repository benötigt wird.

--ignore-user-config überspringt die Hauptkonfigurationsdatei des Benutzers für Codex, behält aber die normale Authentifizierung bei. --ephemeral verhindert das Speichern des Session-Rollouts. Die Shell speichert weiterhin die drei oben genannten expliziten Ausgabedateien. --sandbox read-only begrenzt vom Modell generierte Befehle; die Umleitungen der Shell schreiben die Artefakte.

Das Schema erfordert verdict, failed_checks, summary und next_step und verbietet zusätzliche Felder. Der Bericht sollte erklären, was die gelieferten Checks bestätigen. Eine Antwort kann vorschlagen, nach einem 503 die Anwendungsprotokolle zu prüfen, aber der Statuscode allein ist kein Beleg für einen Datenbankfehler.

Den Stream und die endgültige Antwort separat parsen

In unserem Live-Test gab Codex diese Event-Typen in folgender Reihenfolge aus:

thread.started
turn.started
item.completed
turn.completed

Das abgeschlossene Element war eine Agenten-Nachricht. Diese speziellen Durchläufe machten keine Tool-Aufrufe. Andere Aufgaben können mehr Events erzeugen, einschließlich Befehlsausführungen, Tool-Aufrufen und Fehlern; setzen Sie nicht voraus, dass jeder erfolgreiche Durchlauf genau vier Zeilen hat.

Der Wrapper liest jedes Event und lehnt turn.failed oder error ab. Er erfordert außerdem turn.completed, einen erfolgreichen Prozessabschluss und einen finalen Bericht, der sich parsen lässt. Dann vergleicht er das Urteil des Berichts und die Namen der fehlgeschlagenen Checks mit den HTTP-Prüfdaten.

Ein Stream, der vorzeitig endet, ist ein unvollständiger Job. Eine Berichtsdatei, die von einem vorherigen Durchlauf übrig geblieben ist, ist ebenfalls unsicher für die Wiederverwendung. Der Wrapper erstellt ein neues Ausgabeverzeichnis und weigert sich, einen bestehenden Durchlauf zu überschreiben.

Den vollständigen Workflow ausführen

python3 run.py codex http://127.0.0.1:8787 runs/healthy

Dieser Befehl sammelt frische Prüfdaten, startet Codex mit einem Prozess-Timeout von 180 Sekunden, speichert dessen Ausgabe und validiert den Bericht. Der Wrapper beendet sich nur mit 0, wenn beide Anwendungs-Checks erfolgreich sind und der Bericht zustimmt.

Um den Fehler zu reproduzieren, starten Sie eine zweite Demo in einem anderen Terminal:

python3 demo.py --port 8788 --broken

Führen Sie dann denselben Workflow gegen diese Instanz aus:

python3 run.py codex http://127.0.0.1:8788 runs/broken

Die Zustands-Route gibt 200 zurück und die Preisberechnungs-Route gibt 503 zurück. Codex empfängt diese Beobachtungen und gibt einen Fehlerbericht zurück. Der Wrapper beendet sich mit 1. Der Berichtsprozess kann erfolgreich abgeschlossen werden, während der Anwendungs-Check fehlschlägt; Ihre Automatisierung muss den Exit-Code des Wrappers für die Anwendungsentscheidung verwenden.

Ergebnisse aus dem funktionierenden Beispiel

Wir haben beide Szenarien mit Codex CLI 0.156.1 und Python 3.12.10 am 28. September 2026 ausgeführt. Wir haben auch die Lizard CLI-Befehle gegen Version 4.0.8 geprüft.

Beide Modellaufrufe wurden abgeschlossen und erzeugten einen Bericht, der mit den gesammelten Prüfdaten übereinstimmte. Der Bericht des fehlerhaften Durchlaufs schlug vor, die Protokolle zur aufgezeichneten Zeit zu überprüfen. Er behauptete nicht, dass der Zustands-Endpoint belegt, dass die gesamte Anwendung funktioniert.

Die lokalen Validierungstests lehnen auch einen falschen Erfolgsbericht und unvollständige Prüfdaten ab. Führen Sie sie ohne Modellaufruf aus:

python3 verify.py

Dies ist ein synthetischer HTTP-Test auf einer lokalen Maschine. Er deckt keinen Produktionsverkehr, öffentliches DNS, TLS, Datenbankmigrationen oder jede Route ab. Fügen Sie Checks für die Teile Ihres eigenen Deployments hinzu, die wichtig sind.

Lizard status und Protokolle hinzufügen

Bestätigen Sie bei einer Anwendung auf Lizard das Ziel, bevor Sie Fehler interpretieren:

lizard skills get core --json
lizard status --json
lizard ps --project YOUR_PROJECT --json
lizard logs --project YOUR_PROJECT --service YOUR_SERVICE --tail 100 --json

Lizard CLI liefert Ihnen maschinenlesbare Service-Informationen und einen begrenzten Protokoll-Snapshot. Der Kernleitfaden entspricht der installierten CLI-Version. Verwenden Sie ihn, wenn Sie mehr Befehle oder Flags benötigen, und nutzen Sie explizite Projekt- und Service-Selektoren in der Automatisierung.

Führen Sie den angepassten HTTP-Collector gegen die öffentliche URL des Services aus. Ein als laufend markierter Container ist kein Beleg dafür, dass eine Preisabfrage oder ein Datenbank-Lesevorgang funktioniert. Vergleichen Sie die Zeit des HTTP-Fehlers mit den Service-Protokollen, um die nächste Untersuchung einzugrenzen. Überprüfen und schwärzen Sie Protokollinhalte, bevor Sie sie an ein Modell senden.

Wenn Sie zuerst deployen müssen, beginnen Sie mit dem Deployment-Leitfaden für Coding-Agenten. Für Apps mit Datenabhängigkeiten erklären das Postgres MCP-Tutorial und das Redis MCP-Tutorial den eingeschränkten Zugriff zur Überprüfung von Testdaten.

Das Ergebnis in der Automatisierung nutzen

Halten Sie drei Ergebnisse explizit: Anwendung bestanden, Anwendung fehlgeschlagen und Berichtsjob fehlgeschlagen. Dieser Wrapper verwendet entsprechend 0, 1 und 2. Ein Timeout, ein CLI-Authentifizierungsproblem, ein ungültiger Bericht oder ein Widerspruch in der Ausgabe erzeugt Code 2.

Speichern Sie die Prüfdaten zusammen mit dem Bericht. So kann ein Teammitglied das Ergebnis überprüfen, ohne einer Prosa-Zusammenfassung vertrauen zu müssen. Geben Sie geplanten Durchläufen eindeutige Ausgabepfade, legen Sie eine Aufbewahrungsfrist fest und vermeiden Sie es, Anmeldeinformationen in Artefakten zu speichern.

Auf Ihrer eigenen vertrauenswürdigen Maschine kann codex exec den gespeicherten CLI-Login wiederverwenden. Für GitHub Actions folgen Sie dem offiziellen Codex-Action-Leitfaden für die Einrichtung von Authentifizierung und Berechtigungen. Halten Sie API-Anmeldeinformationen aus Repository-Dateien fern und vermeiden Sie es, sie nicht vertrauenswürdigen Build-Schritten auszusetzen. Überprüfen Sie diese Runner-spezifischen Anforderungen, bevor Sie einen lokalen Befehl in die CI übertragen.

Verwenden Sie für jeden unabhängigen Check frische Prüfdaten. codex exec resume kann eine Konversation fortsetzen, wird aber für diesen einmaligen Bericht nicht benötigt. Der flüchtige Modus des Beispiels macht jeden Durchlauf unabhängig.

Fehlerbehebung

Wie es weitergeht

Verwenden Sie dieses Muster für einen fokussierten Deployment-Check und fügen Sie dann Assertions für die echten Abhängigkeiten Ihrer Anwendung hinzu. Halten Sie die Checks klein genug, damit ein fehlgeschlagenes Ergebnis auf einen nützlichen nächsten Schritt hinweist.

Wenn Ihr Team Claude Code verwendet, zeigt der Claude Code Headless-Leitfaden dieselben HTTP-Checks mit seiner Ergebnis-Hülle. Um die Anwendung selbst auszuführen, verwenden Sie Lizard CLI und fügen Sie den Bericht nach Ihrem Deployment-Schritt hinzu.