Claude Code im Headless-Modus betreiben in 2026: Ein praktischer Automatisierungs-Leitfaden

Der Headless-Modus von Claude Code führt den Agenten nicht-interaktiv aus: Sie übergeben das Flag -p (oder --print) zusammen mit einem Prompt, Claude läuft bis zum Abschluss durch, gibt das Ergebnis aus und beendet sich – kein REPL, keine Tastatur, niemand, der am Terminal wartet. Dieses eine Flag verwandelt einen interaktiven Coding-Assistenten in ein Unix-freundliches Kommandozeilenwerkzeug, in das Sie hineinpipen, das Sie in ein Skript einbetten, mit cron planen oder in eine CI/CD-Pipeline einbauen können. Dieser Leitfaden erklärt, wie der Headless-Modus in 2026 funktioniert, welche Flags wirklich zählen, wie Sie parsebares JSON herausbekommen, welche Berechtigungs- und Auth-Fallen unbeaufsichtigte Läufe klammheimlich sabotieren und welche Lehren sich aus dem Betrieb einer Headless-Claude-Code-Pipeline in Produktion ziehen lassen.

Was ist der Headless-Modus von Claude Code?

Der Headless-Modus ist Claude Code ohne seine interaktive Terminal-Oberfläche. Fügen Sie -p (kurz für --print) zu einem beliebigen claude-Befehl hinzu, und statt das REPL zu öffnen, liest Claude den Prompt, durchläuft die vollständige Agenten-Schleife (Dateien lesen, Tools ausführen, Code bearbeiten), gibt dann das finale Ergebnis aus und beendet sich mit einem Statuscode. Es ist derselbe Agent, der das interaktive Claude Code antreibt, nur von einem Skript statt von einem Menschen gesteuert. Ab 2026 lebt die Funktion unter dem Agent SDK, das auch als Python- und TypeScript-Paket ausgeliefert wird, falls Sie Callbacks und native Message-Objekte statt eines Shell-Aufrufs wünschen.

claude -p "What does the auth module do?"

Da der nicht-interaktive Modus von stdin liest, lässt er sich wie jedes andere CLI-Tool kombinieren. Sie können ein Build-Log direkt hineinpipen und die Antwort herausleiten:

cat build-error.txt | claude -p "concisely explain the root cause of this build error" > cause.txt

Genau diese Kombinierbarkeit (stdin rein, Text oder JSON raus, ein Exit-Code, auf den Sie verzweigen können) ist der ganze Grund, warum es den Headless-Modus gibt.

So erhalten Sie strukturierte Ausgaben, die Sie parsen können

Reiner Text reicht für einen Menschen, der ein Log liest, aber Automatisierung braucht Struktur. Das Flag --output-format akzeptiert genau drei Werte: text (die Voreinstellung), json und stream-json. Das Format json ist das Arbeitspferd: Es liefert die Antwort plus Session-Metadaten in einem einzigen Objekt.

claude -p "Summarize this project" --output-format json | jq -r '.result'

Die JSON-Nutzlast enthält result (den Text), session_id, num_turns, is_error, duration_ms und – entscheidend für alle, die das im großen Maßstab betreiben – total_cost_usd, eine Kostenangabe pro Aufruf, sodass Sie Ausgaben verfolgen können, ohne das Dashboard zu öffnen. Für maschinenlesbare Antworten, die einer von Ihnen definierten Form entsprechen, kombinieren Sie --output-format json mit --json-schema '{...}'; das validierte Objekt kommt in einem Feld structured_output zurück. Verwenden Sie stream-json mit --verbose, wenn Sie Tokens rendern möchten, während sie eintreffen. Parsen Sie alles davon mit jq, und Sie haben eine verlässliche programmatische Schnittstelle.

Berechtigungen: der Teil, über den alle stolpern

Eine interaktive Sitzung fragt nach, bevor sie einen Shell-Befehl ausführt oder eine Datei bearbeitet. Ein Headless-Lauf hat niemanden zum Fragen, also wird er die Aktion standardmäßig verweigern und kann Ihre Pipeline blockieren. Sie müssen die Berechtigung vorab erteilen. Das sauberste Werkzeug ist --allowedTools, eine kommagetrennte Erlaubnisliste:

claude -p "Run the test suite and fix any failures" --allowedTools "Bash,Read,Edit"

Für feinere Kontrolle nutzt das Flag die Syntax für Berechtigungsregeln, sodass --allowedTools "Bash(git diff *)" nur Befehle erlaubt, die mit git diff beginnen. Um für den gesamten Lauf eine Grundlinie festzulegen, statt Tools aufzuzählen, übergeben Sie einen --permission-mode: acceptEdits lässt Claude Dateien schreiben und gängige Dateisystembefehle ausführen, ohne nachzufragen, während dontAsk alles ablehnt, was nicht ausdrücklich erlaubt ist – die richtige Wahl für einen abgeschotteten CI-Job. Das grobe Werkzeug --dangerously-skip-permissions genehmigt alles und sollte nur eine Wegwerf-Sandbox oder einen Container berühren, niemals eine Maschine mit Zugangsdaten oder Produktionszugriff.

Authentifizierung: API-Schlüssel vs. OAuth-Token

Headless-Läufe brauchen Zugangsdaten, die keine Browser-Anmeldung erfordern, und dafür gibt es zwei ehrliche Wege. Der erste ist ANTHROPIC_API_KEY, ein Schlüssel aus der Anthropic Console, der pro Token abgerechnet wird – die natürliche Wahl für CI-Runner und Pay-as-you-go-Automatisierung. Der zweite lässt Sie ein bestehendes Abonnement wiederverwenden: Führen Sie einmal claude setup-token aus, durchlaufen Sie den OAuth-Flow im Browser, und es wird ein einjähriges Token ausgegeben, das Sie als CLAUDE_CODE_OAUTH_TOKEN exportieren. Dieses Token ist an einen Pro-, Max-, Team- oder Enterprise-Plan gebunden und auf reine Inferenz beschränkt. Wählen Sie nach Abrechnungsmodell: gemessene API-Nutzung für schubweise CI-Lasten, das Abo-Token für einen stetigen, dauerhaft laufenden Agenten. Ein Vorbehalt für skriptgesteuerte Aufrufe: Der --bare-Modus (der die automatische Erkennung von Hooks, Skills und MCP-Servern für reproduzierbare Läufe überspringt) überspringt auch OAuth, sodass Sie unter --bare ANTHROPIC_API_KEY bereitstellen müssen.

Claude Code in CI/CD und per cron betreiben

Sobald ein einzelner Befehl nicht-interaktiv funktioniert, ist seine Planung ganz gewöhnliches DevOps. Ein cron-Eintrag, der claude -p auf einem VPS ausführt, macht aus dem Agenten eine Aufgabe, die von selbst anläuft: Logs um 2 Uhr nachts sichten, ein Changelog entwerfen oder nach Zeitplan Lint-Fehler beheben. In einer Pipeline packen Sie den Aufruf in ein Skript, das ein Diff hineinpipet und je nach Exit-Code verzweigt; Anthropic liefert hauseigene GitHub Actions- und GitLab-CI/CD-Integrationen genau dafür. Zwei Flags sind für unbeaufsichtigte Zuverlässigkeit entscheidend. Fügen Sie --bare hinzu, damit Läufe nicht stillschweigend beliebige Hooks oder MCP-Server erben, die zufällig im ~/.claude eines Teamkollegen liegen – so erhalten Sie auf jeder Maschine dasselbe Ergebnis. Und verwenden Sie --continue oder --resume <session_id>, wenn ein Job mehrere aufeinander aufbauende Schritte benötigt, wobei Sie die Session-ID aus der JSON-Ausgabe des ersten Aufrufs erfassen. Wenn Sie die Maschine selbst aufsetzen, deckt unser Leitfaden zum Self-Hosting von Apps auf einem VPS die cron- und Härtungsgrundlagen ab, die einen geplanten Agenten gesund halten.

Flag	Was es tut	Wann Sie es brauchen
-p / --print	Nicht-interaktiv laufen, Ergebnis ausgeben, beenden	Jeder Headless-Lauf
--output-format json	Strukturiertes Ergebnis mit Kosten + Session-Metadaten	Jeder skriptgesteuerte Aufrufer
--json-schema	Ausgabe in ein Schema erzwingen (structured_output)	Maschinenlesbare Extraktion
--allowedTools	Bestimmte Tools vorab genehmigen	Blockieren des Laufs bei Nachfragen verhindern
--permission-mode	Session-weite Grundlinie (acceptEdits, dontAsk)	Abgeschottetes CI
--bare	Automatische Erkennung für reproduzierbare Läufe überspringen	CI- und SDK-Aufrufe
--continue / --resume	Mehrschrittige Konversationen über Aufrufe hinweg	Zustandsbehaftete Jobs

Was wir beim Betrieb einer Headless-Content-Engine gelernt haben

Wir nutzen Claude Code im Headless-Modus selbst in Produktion: Die Pipeline, die Artikel hier bei TechRiseUps recherchiert, schreibt und veröffentlicht, läuft als geplanter claude -p-Job auf unserer eigenen WaseerHost-Infrastruktur, gesteuert von einem eigenen Skill statt von einer Person an der Tastatur. Ein paar Lehren haben sich bewährt, die die Dokumentation nur andeutet.

Berechtigungen sind die häufigste Ursache für einen „hängenden“ Lauf: Ein Job, der festzustecken scheint, ist fast immer Claude, das auf eine Genehmigung wartet, die nie kommt – genehmigen Sie also vorab jedes Tool, das die Aufgabe wirklich braucht, und nichts darüber hinaus. Lesen Sie bei jedem Aufruf total_cost_usd aus dem JSON und protokollieren Sie es; unbeaufsichtigte Agenten haben keine natürliche Kostenobergrenze, und die Angabe pro Lauf ist die einzige günstige Möglichkeit, eine Aufgabe abzufangen, die außer Kontrolle geraten ist. Machen Sie jeden Lauf idempotent, denn ein cron-Job wird irgendwann zweimal feuern oder mittendrin fortsetzen, und ein Agent, der blind anhängt, richtet ein Chaos an. Und für langlaufende Jobs, die sich mit Hintergrund-Subagenten auffächern, erhöhen Sie das Limit für Datei-Deskriptoren des Prozesses, denn ein Headless-Agent, der viele Dateien und Sockets öffnet, kann stillschweigend an das voreingestellte ulimit stoßen und ohne offensichtlichen Fehler steckenbleiben. Nichts davon ist exotisch; es ist die langweilige betriebliche Hygiene, die eine Demo von einer Pipeline unterscheidet, der Sie vertrauen, dass sie läuft, während Sie schlafen.

Häufig gestellte Fragen

Was ist der Headless-Modus in Claude Code?

Es ist Claude Code, das nicht-interaktiv über das Flag -p / --print läuft. Claude liest einen Prompt, durchläuft die vollständige Agenten-Schleife, gibt das finale Ergebnis aus und beendet sich, ohne interaktives Terminal. Er ist für Skripte, Pipes, cron-Jobs und CI/CD gedacht, nicht für händisches Coden.

Wie betreibe ich Claude Code im Headless-Modus, ohne für API-Schlüssel zu bezahlen?

Erzeugen Sie ein abonnementgestütztes Token mit claude setup-token und exportieren Sie es dann als CLAUDE_CODE_OAUTH_TOKEN. Es authentifiziert sich gegen einen Pro-, Max-, Team- oder Enterprise-Plan statt gegen gemessene API-Abrechnung. Beachten Sie, dass der --bare-Modus OAuth umgeht und weiterhin ANTHROPIC_API_KEY erfordert.

Wie verhindere ich, dass Claude Code im Headless-Modus nach Berechtigungen fragt?

Genehmigen Sie Tools vorab mit --allowedTools "Bash,Read,Edit", oder legen Sie eine Session-Grundlinie mit --permission-mode acceptEdits (oder dontAsk für abgeschottetes CI) fest. Verwenden Sie --dangerously-skip-permissions nur innerhalb einer verwerfbaren Sandbox, niemals auf einer Maschine mit echten Zugangsdaten.

Kann ich Claude Code im Headless-Modus aus Python heraus betreiben?

Ja. Der Headless-Modus ist Teil des Agent SDK, das zusätzlich zur CLI claude -p als Python- und TypeScript-Paket ausgeliefert wird. Verwenden Sie die SDK-Pakete, wenn Sie Callbacks für Tool-Genehmigungen, native Message-Objekte und strukturierte Ausgaben ohne Parsen von stdout wünschen.

Ist der Headless-Modus dasselbe wie das Claude Agent SDK?

Sie sind zwei Eingangstüren zu derselben Engine. claude -p ist die CLI-Form des Agent SDK – dieselben Tools, dieselbe Agenten-Schleife und dasselbe Kontext-Management. Die Python- und TypeScript-SDK-Pakete geben Ihnen umfassendere programmatische Kontrolle, um Agenten in Anwendungen einzubauen.

Quellen

• Claude Code Docs — Claude Code programmatisch ausführen (headless): das Flag -p/--print, --output-format, --bare, Berechtigungen, --continue/--resume und die JSON-Ergebnisfelder.
• Claude Code Docs — Authentifizierung: claude setup-token, CLAUDE_CODE_OAUTH_TOKEN und wie sich Abo-Tokens von ANTHROPIC_API_KEY unterscheiden.
• Claude Code Docs — GitHub Actions: hauseigene CI-Integration zum Ausführen des Agenten in Pipelines.