Zum Hauptinhalt springen

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Das Agent SDK bietet Ihnen die gleichen Tools, die Agent-Schleife und das Kontextmanagement, die Claude Code antreiben. Es ist als CLI für Skripte und CI/CD verfügbar oder als Python- und TypeScript-Pakete für vollständige programmgesteuerte Kontrolle.
Die CLI hieß früher „Headless-Modus”. Das Flag -p und alle CLI-Optionen funktionieren auf die gleiche Weise.
Um Claude Code programmgesteuert über die CLI auszuführen, übergeben Sie -p mit Ihrer Eingabeaufforderung und allen CLI-Optionen: 
claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"
Diese Seite behandelt die Verwendung des Agent SDK über die CLI (claude -p). Für die Python- und TypeScript-SDK-Pakete mit strukturierten Ausgaben, Tool-Genehmigungsrückrufen und nativen Nachrichtenobjekten siehe die vollständige Agent SDK-Dokumentation.

​
Grundlegende Verwendung

Fügen Sie das Flag -p (oder --print) zu jedem claude-Befehl hinzu, um ihn nicht interaktiv auszuführen. Alle CLI-Optionen funktionieren mit -p, einschließlich: Dieses Beispiel stellt Claude eine Frage zu Ihrer Codebasis und gibt die Antwort aus: 
claude -p "What does the auth module do?"

​
Schneller starten mit Bare-Modus

Fügen Sie --bare hinzu, um die Startzeit zu verkürzen, indem Sie die automatische Erkennung von hooks, skills, plugins, MCP-Servern, automatischem Speicher und CLAUDE.md überspringen. Ohne diese Option lädt claude -p den gleichen Kontext, den eine interaktive Sitzung hätte, einschließlich alles, was im Arbeitsverzeichnis oder in ~/.claude konfiguriert ist. Der Bare-Modus ist nützlich für CI und Skripte, bei denen Sie auf jedem Computer das gleiche Ergebnis benötigen. Ein hook in der ~/.claude eines Teamkollegen oder ein MCP-Server in der .mcp.json des Projekts werden nicht ausgeführt, da der Bare-Modus diese nie liest. Nur Flags, die Sie explizit übergeben, haben Auswirkungen. Dieses Beispiel führt eine einmalige Zusammenfassungsaufgabe im Bare-Modus aus und genehmigt das Read-Tool vorab, damit der Aufruf ohne Berechtigungsaufforderung abgeschlossen wird: 
claude --bare -p "Summarize this file" --allowedTools "Read"
Im Bare-Modus hat Claude Zugriff auf die Bash-, Dateilesungs- und Dateibearbeitungstools. Übergeben Sie jeden Kontext, den Sie benötigen, mit einem Flag:
Zum LadenVerwenden Sie
Systemanfrage-Ergänzungen--append-system-prompt, --append-system-prompt-file
Einstellungen--settings <file-or-json>
MCP-Server--mcp-config <file-or-json>
Benutzerdefinierte Agenten--agents <json>
Ein Plugin--plugin-dir <path>, --plugin-url <url>
Der Bare-Modus überspringt OAuth und Keychain-Lesevorgänge. Die Anthropic-Authentifizierung muss von ANTHROPIC_API_KEY oder einem apiKeyHelper in der an --settings übergebenen JSON stammen. Bedrock, Vertex und Foundry verwenden ihre üblichen Anmeldedaten des Anbieters.
--bare ist der empfohlene Modus für skriptgesteuerte und SDK-Aufrufe und wird in einer zukünftigen Version zum Standard für -p.

​
Beispiele

Diese Beispiele zeigen häufige CLI-Muster. Für CI und andere skriptgesteuerte Aufrufe fügen Sie --bare hinzu, damit sie nicht abhängig von lokalen Konfigurationen sind.

​
Daten durch Claude leiten

Der nicht-interaktive Modus liest stdin, sodass Sie Daten wie bei jedem anderen Befehlszeilentool einleiten und die Antwort umleiten können. Dieses Beispiel leitet ein Build-Protokoll in Claude ein und schreibt die Erklärung in eine Datei: 
cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt
Mit --output-format json enthält die Antwort-Payload total_cost_usd und eine Kostenaufschlüsselung pro Modell, sodass skriptgesteuerte Aufrufer die Ausgaben pro Aufruf verfolgen können, ohne das Nutzungs-Dashboard zu konsultieren.
Ab Claude Code v2.1.128 ist eingeleiter stdin auf 10 MB begrenzt. Wenn Sie die Grenze überschreiten, beendet sich Claude Code mit einer klaren Fehlermeldung und einem Nicht-Null-Status. Um mit größeren Eingaben zu arbeiten, schreiben Sie den Inhalt in eine Datei und verweisen Sie auf den Dateipfad in Ihrer Eingabeaufforderung, anstatt ihn einzuleiten.

​
Claude zu einem Build-Skript hinzufügen

Sie können einen nicht-interaktiven Aufruf in einem Skript einbinden, um Claude als projektspezifischen Linter oder Reviewer zu verwenden. Dieses package.json-Skript leitet den Diff gegen main in Claude ein und fordert ihn auf, Tippfehler zu melden. Das Einleiten des Diff bedeutet, dass Claude keine Bash-Berechtigung zum Lesen benötigt, und die maskierten doppelten Anführungszeichen halten das Skript portabel zu Windows: 
{
  "scripts": {
    "lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""
  }
}

​
Strukturierte Ausgabe abrufen

Verwenden Sie --output-format, um zu steuern, wie Antworten zurückgegeben werden:
  • text (Standard): einfache Textausgabe
  • json: strukturiertes JSON mit Ergebnis, Sitzungs-ID und Metadaten
  • stream-json: zeilengetrennte JSON für Echtzeit-Streaming
Dieses Beispiel gibt eine Projektzusammenfassung als JSON mit Sitzungsmetadaten zurück, wobei sich das Textergebnis im Feld result befindet: 
claude -p "Summarize this project" --output-format json
Um eine Ausgabe zu erhalten, die einem bestimmten Schema entspricht, verwenden Sie --output-format json mit --json-schema und einer JSON Schema-Definition. Die Antwort enthält Metadaten über die Anfrage (Sitzungs-ID, Nutzung usw.) mit der strukturierten Ausgabe im Feld structured_output. Dieses Beispiel extrahiert Funktionsnamen und gibt sie als Array von Zeichenketten zurück: 
claude -p "Extract the main function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'
Verwenden Sie ein Tool wie jq, um die Antwort zu analysieren und bestimmte Felder zu extrahieren:
# Extract the text result
claude -p "Summarize this project" --output-format json | jq -r '.result'

# Extract structured output
claude -p "Extract function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'

​
Antworten streamen

Verwenden Sie --output-format stream-json mit --verbose und --include-partial-messages, um Token zu empfangen, während sie generiert werden. Jede Zeile ist ein JSON-Objekt, das ein Ereignis darstellt: 
claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages
Das folgende Beispiel verwendet jq, um nach Text-Deltas zu filtern und nur den Streaming-Text anzuzeigen. Das Flag -r gibt Rohzeichenketten aus (keine Anführungszeichen) und -j verbindet ohne Zeilenumbrüche, sodass Token kontinuierlich gestreamt werden: 
claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | \
  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'
Wenn eine API-Anfrage mit einem wiederholbaren Fehler fehlschlägt, gibt Claude Code ein system/api_retry-Ereignis vor dem erneuten Versuch aus. Sie können dies verwenden, um Wiederholungsfortschritt anzuzeigen oder benutzerdefinierte Backoff-Logik zu implementieren.
FeldTypBeschreibung
type"system"Nachrichtentyp
subtype"api_retry"identifiziert dies als Wiederholungsereignis
attemptGanzzahlaktuelle Versuchsnummer, beginnend bei 1
max_retriesGanzzahlinsgesamt zulässige Wiederholungen
retry_delay_msGanzzahlMillisekunden bis zum nächsten Versuch
error_statusGanzzahl oder nullHTTP-Statuscode oder null für Verbindungsfehler ohne HTTP-Antwort
errorZeichenketteFehlerkategorie: authentication_failed, oauth_org_not_allowed, billing_error, rate_limit, invalid_request, server_error, max_output_tokens oder unknown
uuidZeichenketteeindeutige Ereigniskennung
session_idZeichenketteSitzung, zu der das Ereignis gehört
Das system/init-Ereignis meldet Sitzungsmetadaten einschließlich des Modells, Tools, MCP-Server und geladener Plugins. Es ist das erste Ereignis im Stream, es sei denn, CLAUDE_CODE_SYNC_PLUGIN_INSTALL ist gesetzt. In diesem Fall gehen plugin_install-Ereignisse voraus. Verwenden Sie die Plugin-Felder, um CI fehlschlagen zu lassen, wenn ein Plugin nicht geladen wurde:
FeldTypBeschreibung
pluginsArrayPlugins, die erfolgreich geladen wurden, jeweils mit name und path
plugin_errorsArrayPlugin-Ladefehler, jeweils mit plugin, type und message. Umfasst nicht erfüllte Abhängigkeitsversionen und --plugin-dir-Ladefehler wie einen fehlenden Pfad oder ein ungültiges Archiv. Betroffene Plugins werden herabgestuft und fehlen in plugins. Der Schlüssel wird weggelassen, wenn es keine Fehler gibt
Wenn CLAUDE_CODE_SYNC_PLUGIN_INSTALL gesetzt ist, gibt Claude Code system/plugin_install-Ereignisse aus, während Marketplace-Plugins vor dem ersten Zug installiert werden. Verwenden Sie diese, um Installationsfortschritt in Ihrer eigenen Benutzeroberfläche anzuzeigen.
FeldTypBeschreibung
type"system"Nachrichtentyp
subtype"plugin_install"identifiziert dies als Plugin-Installationsereignis
status"started", "installed", "failed" oder "completed"started und completed rahmen die Gesamtinstallation ein; installed und failed melden einzelne Marketplaces
nameZeichenkette, optionalMarketplace-Name, vorhanden bei installed und failed
errorZeichenkette, optionalFehlermeldung, vorhanden bei failed
uuidZeichenketteeindeutige Ereigniskennung
session_idZeichenketteSitzung, zu der das Ereignis gehört
Für programmgesteuertes Streaming mit Rückrufen und Nachrichtenobjekten siehe Antworten in Echtzeit streamen in der Agent SDK-Dokumentation.

​
Tools automatisch genehmigen

Verwenden Sie --allowedTools, um Claude die Verwendung bestimmter Tools ohne Aufforderung zu ermöglichen. Dieses Beispiel führt eine Test-Suite aus und behebt Fehler, wobei Claude Bash-Befehle ausführen und Dateien lesen/bearbeiten kann, ohne um Genehmigung zu fragen: 
claude -p "Run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit"
Um einen Baseline für die gesamte Sitzung festzulegen, anstatt einzelne Tools aufzulisten, übergeben Sie einen Berechtigungsmodus. dontAsk verweigert alles, das nicht in Ihren permissions.allow-Regeln oder dem schreibgeschützten Befehlssatz enthalten ist, was für gesperrte CI-Läufe nützlich ist. acceptEdits ermöglicht Claude, Dateien ohne Aufforderung zu schreiben, und genehmigt auch automatisch häufige Dateisystembefehle wie mkdir, touch, mv und cp. Andere Shell-Befehle und Netzwerkanfragen benötigen immer noch einen --allowedTools-Eintrag oder eine permissions.allow-Regel, andernfalls wird der Lauf abgebrochen, wenn einer versucht wird: 
claude -p "Apply the lint fixes" --permission-mode acceptEdits

​
Einen Commit erstellen

Dieses Beispiel überprüft bereitgestellte Änderungen und erstellt einen Commit mit einer angemessenen Nachricht: 
claude -p "Look at my staged changes and create an appropriate commit" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"
Das Flag --allowedTools verwendet Berechtigungsregelsyntax. Das nachfolgende * ermöglicht Präfix-Matching, sodass Bash(git diff *) jeden Befehl erlaubt, der mit git diff beginnt. Das Leerzeichen vor * ist wichtig: ohne es würde Bash(git diff*) auch git diff-index entsprechen.
Benutzer-aufgerufene skills wie /commit und integrierte Befehle sind nur im interaktiven Modus verfügbar. Im -p-Modus beschreiben Sie stattdessen die Aufgabe, die Sie ausführen möchten.

​
System-Eingabeaufforderung anpassen

Verwenden Sie --append-system-prompt, um Anweisungen hinzuzufügen und dabei das Standardverhalten von Claude Code beizubehalten. Dieses Beispiel leitet einen PR-Diff an Claude weiter und weist ihn an, auf Sicherheitslücken zu überprüfen: 
gh pr diff "$1" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json
Siehe System-Eingabeaufforderungs-Flags für weitere Optionen, einschließlich --system-prompt, um die Standardeingabeaufforderung vollständig zu ersetzen.

​
Gespräche fortsetzen

Verwenden Sie --continue, um das neueste Gespräch fortzusetzen, oder --resume mit einer Sitzungs-ID, um ein bestimmtes Gespräch fortzusetzen. Dieses Beispiel führt eine Überprüfung durch und sendet dann Folgeeingabeaufforderungen: 
# First request
claude -p "Review this codebase for performance issues"

# Continue the most recent conversation
claude -p "Now focus on the database queries" --continue
claude -p "Generate a summary of all issues found" --continue
Wenn Sie mehrere Gespräche führen, erfassen Sie die Sitzungs-ID, um ein bestimmtes Gespräch fortzusetzen: 
session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

​
Nächste Schritte