Claude Code Headless: Deployment über das Terminal prüfen

Der Headless-Modus von Claude Code führt einen Prompt aus Ihrem Terminal mit claude -p aus und beendet sich, sobald die Aufgabe abgeschlossen ist. Sie können Daten übergeben, die Antwort speichern und ihn aus einem Skript aufrufen. Dieser Leitfaden nutzt dies, um Deployment-Checks zu erklären: einen Status-Endpoint, eine Preisberechnung und einen Bericht, den Ihr Skript verifizieren kann.

Das Beispiel fängt einen häufigen Fehler ab: /healthz gibt HTTP 200 zurück, während eine tatsächliche Anwendungsroute 503 zurückgibt. Sie erhalten eine reproduzierbare Demo, einen JSON-Bericht und einen Exit-Code ungleich Null, falls der Anwendungs-Check fehlschlägt.

Mit einem nicht-interaktiven Befehl starten

Sobald Claude Code installiert und angemeldet ist, führen Sie Folgendes aus:

claude -p "Explain what an HTTP 503 response tells me in two sentences." \
  --tools ""

-p gibt das Ergebnis aus und beendet das Programm. --tools "" deaktiviert die integrierten Tools für diese Anfrage. Claude kann anhand des Prompts antworten, ohne Ihr Repository zu lesen oder Shell-Befehle auszuführen. Die Claude Code CLI-Referenz listet die verfügbaren Flags auf.

Übergeben Sie dem Modell für einen Deployment-Check die Daten, die Ihr Skript bereits gesammelt hat. Dadurch werden HTTP-Requests und Erfolgsbedingungen leicht überprüfbar. Zudem bleiben Deployment-Anmeldedaten von der Modelleingabe getrennt.

Voraussetzungen

Verwenden Sie Python 3.10 oder neuer, eine aktuelle Installation von Claude Code und ein authentifiziertes Konto. Die Demo nutzt die Standardbibliothek von Python, es müssen also keine Python-Pakete installiert werden. Führen Sie die Shell-Beispiele in Bash oder Zsh unter macOS oder Linux aus.

Prüfen Sie die installierte CLI und ihren Authentifizierungsstatus:

claude --version
claude auth status

Falls ein Request fehlschlägt, weil die gespeicherte Sitzung abgelaufen ist, führen Sie claude auth login aus und versuchen es erneut. Ein gespeicherter Login kann weiterhin bestehen, auch wenn der nächste API-Request ihn nicht aktualisieren kann.

Installieren Sie für die optionalen gehosteten Checks die Lizard CLI und melden Sie sich bei Ihrem eigenen Projekt an. Falls Sie Ihre Anwendung noch deployen müssen, folgen Sie zunächst Deploy from Claude Code.

Beispiel herunterladen und Demo starten

Erstellen Sie einen neuen Ordner und laden Sie die sechs Dateien herunter. Lesen Sie diese, bevor Sie sie ausführen. Die Demo akzeptiert GET-Requests und speichert keine Kundendaten.

mkdir claude-deployment-check
cd claude-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
python3 demo.py --port 8787

Lassen Sie dieses Terminal geöffnet. Wechseln Sie in einem zweiten Terminal in denselben Ordner. Die Demo stellt /healthz und /api/quote?quantity=3 bereit. Jeder Artikel kostet 1.200 Cent; eine Preisberechnung für drei Artikel muss currency: USD und total_cents: 3600 zurückgeben.

Dies sind Demo-Routen. Bearbeiten Sie für Ihre eigene Anwendung die Pfade und erwarteten Felder in collect.py und gate.py. Wählen Sie eine kleine Operation, die ein Benutzer tatsächlich benötigt: das Lesen eines Seed-Datensatzes, die Berechnung eines Preises oder das Abrufen eines gespeicherten Dokuments. Eine Route, die nur „OK“ zurückgibt, kann diese Operationen nicht verifizieren.

Prüfdaten sammeln, bevor Sie Claude aufrufen

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

Der Collector führt zwei Requests mit einem Timeout von jeweils fünf Sekunden aus. Er lehnt Redirects, ungültiges JSON und Antworten ab, die größer als 64 KiB sind. Er prüft sowohl den HTTP-Status als auch die erwarteten JSON-Felder. Er protokolliert die Zeit, die erwarteten Werte und die Check-Ergebnisse; er kopiert keinen beliebigen Antworttext in den Prompt.

Diese letzte Entscheidung ist wichtig, wenn ein Endpoint Benutzertext enthält. Eine Support-Nachricht oder eine Datenbankzeile kann Anweisungen enthalten, die an einen Agenten gerichtet sind. Dieses Beispiel übergibt Claude eine kleine Menge gemessener Felder zur Auswertung.

Der Collector wird erfolgreich beendet, wenn er Prüfdaten schreibt, einschließlich Prüfdaten für einen fehlgeschlagenen Check. Das finale Check-Skript bestimmt, ob der Job erfolgreich ist. Halten Sie diese beiden Bedeutungen in Ihrer Automatisierung getrennt.

Einen strukturierten Bericht anfordern

Führen Sie dies aus dem Ordner aus, der die heruntergeladenen Dateien enthält:

claude --safe-mode -p \
  "Explain the evidence on stdin. Use no tools. Copy its verdict. List the names of failed checks in failed_checks. Give a short summary and one next_step. Do not infer a root cause from HTTP status alone." \
  --tools "" \
  --no-session-persistence \
  --output-format json \
  --json-schema "$(cat report.schema.json)" \
  < evidence.json > claude-result.json

Das Beispiel verwendet --safe-mode, um Anpassungen wie Hooks, Plugins und MCP-Server während dieser Berichtsaufgabe zu deaktivieren. Es nutzt den bestehenden Konto-Login. Prüfen Sie die Hilfe Ihrer installierten Version, falls sie das Flag nicht erkennt.

Die Antwort von Claude hat ein äußeres Ergebnisobjekt. Wenn Sie das Schema bereitstellen, befindet sich der Bericht in structured_output. Das äußere Objekt enthält auch Ausführungs-Metadaten und ein is_error-Feld. Eine einfache JSON-Antwort und eine durch ein Schema eingeschränkte Antwort dienen unterschiedlichen Zwecken; parsen Sie das Feld, das Ihr Befehl angefordert hat.

Das Schema verlangt vier Felder:

Die Dokumentation zur programmatischen Ausführung beschreibt diese Ausgabeformate. Eine gültige JSON-Struktur belegt nicht, ob die Erklärung korrekt ist, daher prüft der Wrapper den Bericht anhand der gemessenen Ergebnisse.

Den kompletten Check ausführen

run.py sammelt aktuelle Prüfdaten, ruft Claude mit einem Prozess-Timeout von 180 Sekunden auf, extrahiert den Bericht und prüft ihn. Geben Sie jedem Durchlauf ein neues Ausgabeverzeichnis:

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

Das Verzeichnis enthält evidence.json, claude-result.json, report.json und stderr.log. Behalten Sie das Rohergebnis bei der Fehlersuche; ein Authentifizierungsfehler kann im Ergebnis auf stdout erscheinen.

Der Wrapper verwendet drei Exit-Codes:

Code 0 vom Claude-Prozess bedeutet, dass der Agenten-Durchlauf abgeschlossen wurde. Der Wrapper trifft die separate Entscheidung über die Anwendung. Ein ungültiger Bericht kann einen fehlgeschlagenen HTTP-Check nicht in einen erfolgreichen Job verwandeln.

Einen Fehler reproduzieren, den ein Status-Check übersieht

Starten Sie eine zweite Demo in einem anderen Terminal:

python3 demo.py --port 8788 --broken

Führen Sie dann aus:

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

Die zweite Demo beantwortet /healthz weiterhin mit HTTP 200. Ihre Route zur Preisberechnung gibt HTTP 503 zurück. Die Prüfdaten protokollieren daher fail, mit quote als fehlgeschlagenem Check. Mit einer gültigen Claude-Antwort beendet sich der Wrapper mit 1.

Sie können die HTTP-Checks und die Validierungslogik auch testen, ohne ein Modell aufzurufen:

python3 verify.py

Dies prüft die funktionierenden und defekten Demos und verifiziert dann, dass das Prüfskript einen falschen Erfolgsbericht und unvollständige Prüfdaten ablehnt. Es verbraucht keine Claude-Credits.

Den Check auf eine Anwendung in Lizard anwenden

Wählen Sie die Anwendungs-URL aus Ihrem Projekt. Inspizieren Sie den aktuellen Projektkontext und den Service-Status mit der Lizard CLI:

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 status zeigt, mit welchem Projekt der lokale Ordner verknüpft ist. lizard ps liest den Service-Status für das ausgewählte Projekt. JSON-Logs geben einen begrenzten Snapshot zurück und werden beendet; sie folgen dem Service nicht weiter.

Verwenden Sie die öffentliche URL des Services mit demselben Checker, nachdem Sie die beiden Routen-Zusicherungen an Ihre Anwendung angepasst haben. Wenn Sie die mitgelieferte Demo selbst hosten, binden Sie sie an 0.0.0.0 und konfigurieren Sie den Port des Services entsprechend. Die lokalen Beispiele binden an 127.0.0.1.

Lesen Sie die Logs rund um die aufgezeichnete Check-Zeit, wenn eine Route fehlschlägt. Ein HTTP 503 allein kann Ihnen nicht sagen, ob die Ursache eine Datenbankverbindung, eine Abhängigkeit oder Anwendungscode war. Überprüfen und schwärzen Sie alle Logs, bevor Sie sie zu einem Modell-Prompt hinzufügen.

Fügen Sie für Anwendungen, die von gespeicherten Daten abhängen, einen Test mit einem bekannten Datensatz hinzu. Der Postgres MCP-Leitfaden erklärt den eingeschränkten Datenbankzugriff, und der Redis MCP-Leitfaden behandelt eingeschränkte Redis-Lesezugriffe. Verwenden Sie Testdaten und Anmeldedaten, die für den Check geeignet sind.

Headless-Modus, Authentifizierung und unbeaufsichtigte Jobs

Der Headless-Modus beschreibt, wie Sie den Befehl ausführen. Er erstellt keinen unbeaufsichtigten Login und entfernt keine Tool-Berechtigungen. Bereiten Sie für einen geplanten Job die Authentifizierung auf dem Runner vor und verwenden Sie einen expliziten Timeout.

Claude bietet auch --bare, was einen Großteil des normalen Startkontexts überspringt. Sein Anthropic-Authentifizierungspfad verwendet ANTHROPIC_API_KEY oder einen konfigurierten API-Schlüssel-Helfer; er liest keine Abonnement-OAuth-Anmeldedaten. Unser Konto-Login-Beispiel verwendet daher --safe-mode. Überprüfen Sie die aktuelle Dokumentation, bevor Sie den Job in die CI verschieben, wo das Authentifizierungs-Setup abweichen kann.

Für Live-Fortschritt unterstützt Claude --output-format stream-json --verbose. Jede Zeile ist ein Event. Verwenden Sie einfaches json, wenn Sie nur ein einziges Endergebnis benötigen, wie es in diesem Beispiel der Fall ist. Vermeiden Sie es, eine alte Unterhaltung für einen unabhängigen Deployment-Check fortzusetzen; jeder Durchlauf sollte aktuelle Daten verwenden.

Fehlerbehebung

Testumfang und nächster Schritt

Am 28. September 2026 führten wir die lokalen HTTP-Tests und die Berichtsprüfung mit Python 3.12.10 aus. Sie prüften korrekte Antworten, einen Fehler bei der Preisberechnung, einen falschen Erfolgsbericht und fehlende Prüfdaten. Die Befehlsoptionen glichen wir mit Claude Code 2.1.259, Lizard CLI 4.0.8 und der offiziellen Dokumentation ab. Die Antwort des Claude-Modells gehörte nicht zu den abgeschlossenen Tests; das oben beschriebene Berichtsverhalten folgt dem dokumentierten Ausgabeformat. Diese Beispieltests belegen nicht den Zustand einer Produktionsanwendung.

Für dasselbe Muster mit JSONL-Events und einer separaten finalen Berichtsdatei siehe Codex Exec Deployment-Checks. Um Ihre eigene App online zu stellen, folgen Sie dem Claude Code Deployment-Leitfaden und fügen Sie dann einen Check für die Operation hinzu, die Ihre Benutzer am meisten benötigen.