Zum Hauptinhalt springen
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. Um Claude Code im nicht-interaktiven Modus auszuführen, übergeben Sie -p mit Ihrer Eingabeaufforderung und allen CLI-Optionen, die Sie benötigen:
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. Nicht jede CLI-Option kombiniert mit -p. Claude Code lehnt --bg ab und lehnt --cloud mit einer Aufgabenbeschreibung mit einem Fehler ab, der den Konflikt benennt; --cloud mit einer Sitzungs-ID und -p reiht stattdessen eine Nachricht in diese Cloud-Sitzung ein und beendet sich. Optionen, die Sie häufig mit -p kombinieren, sind: Dieses Beispiel stellt Claude eine Frage zu Ihrer Codebasis und gibt die Antwort aus:
Claude Code beendet sich mit Code 0 bei Erfolg und mit einem Code ungleich Null, wenn die Ausführung fehlschlägt, sodass Ihre Skripte basierend auf dem Exit-Status verzweigen können. Wenn Sie ein ungültiges Flag übergeben, meldet Claude Code den Fehler an stderr, bevor die Ausführung beginnt. Wenn ein Fehler während der Ausführung auftritt, z. B. fehlende Authentifizierung, gibt Claude Code den Fehler als Ergebnis auf stdout aus.

Schneller starten mit Bare-Modus

Fügen Sie --bare hinzu, um die Startzeit zu verkürzen, indem Sie die automatische Erkennung von Hooks, Skills, benutzerdefinierten Befehlen, Subagenten, installierten Plugins, MCP-Servern, Auto-Memory und CLAUDE.md überspringen. Ohne diese Option erkennt und lädt claude -p diese wie eine interaktive Sitzung, einschließlich aller im Arbeitsverzeichnis oder in ~/.claude konfigurierten Inhalte. 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 wird nicht ausgeführt, da der Bare-Modus diese nie liest. Ein Verzeichnis, das Sie mit --add-dir benennen, ist eine teilweise Ausnahme: Der Bare-Modus lädt Skills aus seinem .claude/skills/-Ordner, überspringt aber immer noch seine .claude/commands/- und .claude/agents/-Ordner. Skills aus zusätzlichen Verzeichnissen behandelt, was geladen wird und was nicht. Ohne --bare führt eine -p-Sitzung die Hooks in der .claude/settings.json eines Projekts aus und verbindet die Server in seiner .mcp.json, auch in einem Ordner, dem Sie nie vertraut haben. Eine -p-Sitzung zeigt keinen Workspace-Trust-Dialog und keine Berechtigungsabfrage pro Server an. Was vor dem Vertrauen in einen Ordner ausgeführt wird behandelt jede Art von Repository-Inhalt unter -p und wie Sie ihn fernhalten. Dieses Beispiel führt eine einmalige Zusammenfassungsaufgabe im Bare-Modus aus und genehmigt das Read-Tool im Voraus, sodass der Aufruf ohne Berechtigungsabfrage abgeschlossen wird. Setzen Sie ANTHROPIC_API_KEY vor der Ausführung, da der Bare-Modus Ihren Abonnement-Login nicht verwendet:
Im Bare-Modus liest Claude Code niemals OAuth-Anmeldedaten oder den System-Schlüsselbund. Für die Anthropic API setzen Sie ANTHROPIC_API_KEY in der Umgebung mit einem Schlüssel, der in der Claude Console erstellt wurde, oder geben Sie einen apiKeyHelper in der --settings-JSON an. Amazon Bedrock, Google Clouds Agent Platform und Microsoft Foundry lesen weiterhin ihre eigenen Provider-Anmeldedaten wie gewohnt. Im Bare-Modus hat Claude Zugriff auf die Tools Bash, Datei lesen und Datei bearbeiten. Übergeben Sie den benötigten Kontext mit einem Flag: Hooks werden im Bare-Modus weiterhin nicht ausgeführt, wenn Sie sie mit --settings übergeben oder wenn sie in der hooks/hooks.json oder unter dem Manifest-Schlüssel hooks eines Plugins stehen, das Sie mit einem Flag laden. Verwenden Sie den Bare-Modus nicht für eine Ausführung, die sie benötigt. Der Bare-Modus schränkt außerdem ein, was während der Sitzung geschieht:
  • MCP-Server: Es werden nur Server verbunden, die über die Befehlszeile übergeben werden, z. B. mit --mcp-config. In einer interaktiven Sitzung überspringt Claude Code außerdem die automatische IDE-Verbindung, sofern Sie nicht --ide übergeben.
  • System-Erinnerungen: Claude erhält Ihre Prompts und die Tool-Ergebnisse ohne die System-Erinnerungen, die Claude Code ihnen sonst beifügen würde. Beispielsweise wird Claude nicht darüber informiert, wenn sich eine zuvor gelesene Datei auf der Festplatte ändert, und erhält nicht die Liste der verfügbaren Skills, einschließlich Skills aus einem --add-dir-Ordner.
  • Hintergrundaufgaben: Claude kann keine Hintergrundbefehle oder Hintergrund-Subagenten ausführen, und die anderen Funktionen, die CLAUDE_CODE_DISABLE_BACKGROUND_TASKS ausschaltet, sind ebenfalls ausgeschaltet. Ein Befehl, der sein Timeout erreicht, wird gestoppt, statt in den Hintergrund verschoben zu werden.
Vor v2.1.286 galten diese Einschränkungen nur teilweise: Eine interaktive --bare-Sitzung verband die MCP-Server, die auch eine normale Sitzung verbinden würde, jede --bare-Sitzung sendete System-Erinnerungen, und Hintergrundaufgaben blieben verfügbar.
--bare ist der empfohlene Modus für skriptgesteuerte und SDK-Aufrufe und wird in einer zukünftigen Version zum Standard für -p.

Hintergrundaufgaben beim Beenden

Nachdem Claude seinen Turn beendet hat und stdin geschlossen wurde, kann eine claude -p-Ausführung offen bleiben, um auf Hintergrundarbeit zu warten, die Claude gestartet hat. Sofern nicht noch ein Hintergrundbefehl läuft, den die Hauptkonversation gestartet hat, stoppt Claude Code standardmäßig nach 10 Minuten kontinuierlichen Wartens im Leerlauf alles, was noch läuft, und verwirft sein Teilergebnis. Um die Obergrenze von 10 Minuten zu ändern, setzen Sie CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS, oder setzen Sie es auf 0, um ohne Obergrenze zu warten. Die Ausführung wartet auf Hintergrundarbeit wie Hintergrundbefehle, Subagenten und Workflows, Monitor-Watches und ausstehende /loop-Wakeups:
  • Hintergrundbefehle: Bei einem Befehl, den die Hauptkonversation gestartet hat, z. B. einem Dev-Server oder einem Watch-Build, wartet die Ausführung, bis der Befehl beendet wird oder sein Zeitlimit erreicht. Claude führt dann einen weiteren Turn mit dem Ergebnis aus. Solange der Befehl läuft, beendet die Obergrenze von 10 Minuten das Warten nicht.
  • Hintergrund-Subagenten und Workflows: Die Ausführung bleibt offen, bis jeder davon abgeschlossen ist oder die Obergrenze von 10 Minuten das Warten beendet.
  • Monitor-Watches: Die Ausführung wartet, bis die Watch abläuft oder die Obergrenze von 10 Minuten das Warten beendet, je nachdem, was zuerst eintritt. Während des Wartens antwortet Claude weiterhin auf das, was die Watch meldet. Standardmäßig läuft eine Watch fünf Minuten nach dem Start durch Claude ab.
  • Ausstehende Wakeups: Wenn Claude in einer Ausführung, deren Prompt Sie als Text statt mit --input-format stream-json übergeben haben, einen selbstgetakteten /loop-Wakeup geplant hat, wartet die Ausführung auf das Auslösen jedes Wakeups und führt dessen Iteration aus, bis die Schleife endet, auch über die Obergrenze von 10 Minuten hinaus.
Wenn stderr ein Terminal ist und die Ausführung fünf Sekunden gewartet hat, gibt Claude Code eine Zeile an stderr aus, die mit Waiting for background work to finish beginnt und die betreffende Arbeit benennt. Bei json- oder stream-json-Ausgabe wird die Zeile nur ausgegeben, wenn stdout kein Terminal ist, sodass das JSON, das Ihr Skript liest, sie nie enthält. Wenn die Ausführung ihre --max-budget-usd-Obergrenze erreicht, stoppt Claude Code die verbleibende Hintergrundarbeit, statt zu warten. Wenn Hintergrundarbeit einen weiteren Turn startet, gibt die Ausführung mit der Standardausgabe text das Ergebnis jedes Turns aus und mit der Ausgabe json das Ergebnis des letzten Turns. Vor v2.1.295 gab die Ausführung auch mit der Ausgabe text nur das Ergebnis des letzten Turns aus.

Einem langen Subagenten-Befehl mehr Zeit geben

Wenn der lange Befehl eines Subagenten bei seinem Timeout in den Hintergrund verschoben wird, läuft er weiter, aber eine claude -p-Ausführung kann sich mit Code 0 beenden, bevor der Befehl abgeschlossen ist. Um das Standard-Timeout über die Laufzeit des Befehls anzuheben, setzen Sie BASH_DEFAULT_TIMEOUT_MS, z. B. BASH_DEFAULT_TIMEOUT_MS=300000 claude -p "<prompt>" für fünf Minuten. Für den Befehl eines Hintergrund-Subagenten, der länger als 10 Minuten dauert, heben Sie außerdem die Obergrenze von 10 Minuten an.

MCP-Arbeit beim Ende einer nicht-interaktiven Ausführung

Eine claude -p-Ausführung wartet nicht auf MCP-Arbeit im Hintergrund:

Beenden Sie eine Ausführung mit SIGTERM

Wenn Sie eine claude -p-Ausführung mit SIGTERM beenden, z. B. mit kill oder von einem Prozessüberwacher, beendet sich Claude Code mit Code 143. Claude Code lässt den laufenden Turn unvollständig und zeichnet kein Ergebnis dafür auf. Um den Turn stattdessen zu beenden, senden Sie SIGINT oder rufen Sie die interrupt()-Methode des Agent SDK auf, bevor Sie den Prozess stoppen. Bei SIGTERM beendet Claude Code die Prozessstruktur aller noch laufenden Bash-Befehle. Claude Code führt dann SessionEnd-Hooks aus und beendet sich. Beim Beenden startet Claude Code keinen neuen Tool-Aufruf, sendet keine neue Modellanfrage und führt keinen Hook außer SessionEnd aus. Wenn die Ausführung in der Mitte eines Befehls oder beim Warten auf eine Berechtigungsabfrage war, als das Signal ankam, behandelt Claude Code diesen Schritt wie folgt:
  • Ausführung eines Befehls: Claude Code zeichnet den Befehl als beendet in der Sitzung auf.
  • Warten auf eine Antwort auf eine Berechtigungsabfrage: Wenn Sie SIGTERM an den Prozess senden, lässt Claude Code die Abfrage unbeantwortet. Wenn Ihr Programm die Sitzung über das Agent SDK schließt, beendet das SDK Claude Codes Eingabe vor dem Senden eines Signals, und Claude Code bricht die Abfrage ab, sobald die Eingabe endet.
Wenn Sie die Sitzung fortsetzen, lässt Claude Code den unterbrochenen Turn unverändert, und Ihr nächster Prompt bestimmt den weiteren Verlauf der Konversation. Damit Claude Code stattdessen den unterbrochenen Turn beim Fortsetzen weiterführt, setzen Sie CLAUDE_CODE_RESUME_INTERRUPTED_TURN=1.

Wenn das Arbeitsverzeichnis gelöscht wird

Wenn das Arbeitsverzeichnis einer claude -p- oder Agent SDK-Sitzung während der Sitzung gelöscht wird, läuft die Sitzung weiter. Wenn ein Turn beginnt, während das Verzeichnis fehlt, gibt Claude Code eine Warnmeldung in der stream-json-Ausgabe aus, und Shell-Befehle schlagen fehl, bis das Verzeichnis wieder vorhanden ist.

Beispiele

Diese Beispiele zeigen häufige CLI-Muster. Wenn ein Befehl eine Datei wie auth.py oder build-error.txt benennt, ersetzen Sie diese durch eine Datei aus Ihrem eigenen Projekt. Fügen Sie in CI oder anderen skriptgesteuerten Umgebungen --bare hinzu, damit Claude Code startet, ohne die Hooks, Plugins, das Auto-Memory oder die CLAUDE.md des Hosts zu laden.

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-Log in Claude ein und schreibt die Erklärung in eine Datei:
Mit --output-format json enthält die Antwort-Payload total_cost_usd und eine Kostenaufschlüsselung pro Modell, sodass skriptgesteuerte Aufrufer die Ausgaben verfolgen können, ohne das Nutzungs-Dashboard zu konsultieren. Wenn Sie eine frühere Konversation mit --continue oder --resume fortsetzen, meldet der Lauf die Gesamtsumme der Konversation, einschließlich der Ausgaben früherer Läufe. Beide Zahlen sind clientseitige Schätzungen und können sich von Ihrer tatsächlichen Rechnung unterscheiden.
Eingeleitetes stdin ist 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 in Ihrem Prompt auf den Dateipfad, anstatt ihn einzuleiten.
Wenn Claude Code stdin nicht lesen kann, beispielsweise weil der Prozess, der es gestartet hat, sein Ende getrennt hat, gibt Claude Code eine Warnung auf stderr aus und fährt mit dem Prompt aus der Befehlszeile fort.

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 Claude auf, Tippfehler zu melden. Durch das Einleiten des Diffs benötigt Claude keine Bash-Berechtigung zum Lesen, und die maskierten doppelten Anführungszeichen halten das Skript unter Windows portabel:
Führen Sie es mit npm run lint:claude aus.

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: zeilengetrenntes JSON für Echtzeit-Streaming
Dieses Beispiel gibt eine Projektzusammenfassung als JSON mit Sitzungsmetadaten zurück, wobei sich das Textergebnis im Feld result befindet:
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:
Wenn der Wert kein gültiges JSON Schema ist, beendet sich claude mit Error: --json-schema is not a valid JSON Schema gefolgt von der Diagnose des Validators. Claude Code akzeptiert Schemas, die das Schlüsselwort format verwenden, wie "format": "email", behandelt format aber als Anmerkung und erzwingt es nicht. Wenn ein Lauf ohne gültige strukturierte Ausgabe endet, beispielsweise weil Claude die Anfrage abgelehnt hat, enthält die Antwort kein Feld structured_output. Prüfen Sie, ob das Feld vorhanden ist, bevor Ihr Skript structured_output verwendet.
Verwenden Sie ein Tool wie jq zum Analysieren der Antwort und zum Extrahieren bestimmter Felder:

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:
Die letzte Zeile des Streams ist eine result-Nachricht mit dem endgültigen Antworttext, den Kosten und den Sitzungsmetadaten. Wenn Ihr Consumer den Stream langsam liest, wartet Claude Code vor dem Beenden darauf, dass die in der Warteschlange befindliche Ausgabe abfließt, und skaliert die Wartezeit mit der Menge, die sich noch in der Warteschlange befindet, begrenzt auf 30 Sekunden. Das folgende Beispiel verwendet jq zum Filtern nach Text-Deltas und zum Anzeigen nur des Streaming-Texts. Das Flag -r gibt Rohzeichenketten aus (keine Anführungszeichen) und -j verbindet ohne Zeilenumbrüche, sodass Token kontinuierlich gestreamt werden:
Für programmgesteuertes Streaming mit Callbacks und Nachrichtenobjekten siehe Antworten in Echtzeit streamen in der Agent SDK-Dokumentation.

Subagenten-Nachrichten folgen

Nachrichten von Subagenten und von Skills, die in einem Subagenten laufen, erscheinen im Stream als assistant- und user-Nachrichten. Ihr Feld parent_tool_use_id gibt an, zu welchem Lauf jede Nachricht gehört. Nachrichten aus der Hauptkonversation tragen null in diesem Feld. Die erste Nachricht eines geforkten Skills oder eines Subagenten, der im Vordergrund läuft, ist eine user-Nachricht mit dem Prompt oder Skill-Inhalt, der ihn steuert. Nach dieser ersten Nachricht gibt Claude Code Folgendes aus: Wenn Sie eine der beiden Optionen aktivieren, leitet Claude Code Nachrichten von Subagenten auf jeder Verschachtelungstiefe weiter, unabhängig davon, ob jeder mit dem Agent-Tool erzeugt oder als geforkter Skill gestartet wurde. In parent_tool_use_id tragen die Nachrichten des verschachtelten Subagenten die ID des Agent- oder Skill-Tool-Aufrufs, der ihn gestartet hat, sodass Sie den vollständigen Verschachtelungsbaum rekonstruieren können, indem Sie diesen IDs folgen. Ein Lauf, den Claude mit einem Tool-Aufruf startet, trägt die ID dieses Tool-Aufrufs. Ein geforkter Skill, den Sie starten, indem Sie /<skill-name> als Prompt übergeben, hat keinen Tool-Aufruf, daher tragen seine Nachrichten stattdessen einen forked-command--Wert und treffen erst ein, nachdem er abgeschlossen ist. Suchen Sie in der ersten Spalte, wie der Lauf gestartet wurde: Gleichen Sie bei einem aus dem Prompt gestarteten geforkten Skill parent_tool_use_id anhand des Präfixes forked-command- ab, da der darauf folgende Name von dem abweichen kann, den Sie eingegeben haben. Wenn einige dieser Nachrichten in Ihrem Stream fehlen, prüfen Sie Ihre Claude Code-Version anhand dieser Mindestversionen:
  • Ein geforkter Skill, den Claude mit dem Skill-Tool aus der Hauptkonversation startet: v2.1.86 oder später für seine tool_use- und tool_result-Blöcke und v2.1.265 oder später für seine erste user-Nachricht sowie seine Text- und Thinking-Blöcke
  • Nachrichten von Subagenten, die ein geforkter Skill startet, und von geforkten Skills, die in einem Subagenten oder einem anderen geforkten Skill gestartet werden: v2.1.275 oder später
  • Nachrichten eines geforkten Skills, den Sie starten, indem Sie /<skill-name> als Prompt übergeben: v2.1.287 oder später

API-Wiederholungsversuche verarbeiten

Wenn eine API-Anfrage mit einem Fehler fehlschlägt, bei dem ein erneuter Versuch möglich ist, gibt Claude Code vor dem erneuten Versuch ein system/api_retry-Ereignis aus. Wenn bei v2.1.246 oder später ein 401 oder 403 über apiKeyHelper bereitgestellte Anmeldedaten ablehnt, führt Claude Code die ersten beiden Wiederholungsversuche stillschweigend ohne Ereignis durch und gibt das Ereignis dann ab dem dritten aufeinanderfolgenden Wiederholungsversuch wie gewohnt aus. Die stillen Wiederholungsversuche zählen trotzdem zu attempt. Sie können das Ereignis verwenden, um den Fortschritt der Wiederholungsversuche in Ihrer eigenen Benutzeroberfläche anzuzeigen.

Sitzungsmetadaten lesen

Das system/init-Ereignis meldet Sitzungsmetadaten einschließlich des Modells, der Tools, der MCP-Server und der geladenen Plugins. Es ist das erste Ereignis im Stream, es sei denn, Startereignisse gehen ihm voraus: Das Ereignis enthält außerdem ein optionales Array capabilities von Zeichenketten, das die Protokollverhalten benennt, die diese Claude Code-Version implementiert, wie interrupt_receipt_v1 oder interrupt_cancel_queued_v1. Prüfen Sie es, um Funktionen zu erkennen, anstatt Versionszeichenketten zu vergleichen, und ignorieren Sie Werte, die Sie nicht kennen. Siehe SDKSystemMessage für die Liste der Fähigkeiten.

CI fehlschlagen lassen, wenn ein Plugin oder MCP-Server nicht geladen wird

Verwenden Sie die Plugin-Felder im system/init-Ereignis, um ein Plugin zu erkennen, das nicht geladen wurde: Wenn ein --plugin-dir-Verzeichnis oder -Archiv selbst nicht geladen werden kann, enthält sein plugin_errors-Eintrag den aufgelösten absoluten Pfad als path. Verwenden Sie ihn, um zu erkennen, welcher von mehreren --plugin-dir-Werten fehlgeschlagen ist. Das Feld path erfordert Claude Code v2.1.283 oder später. Verwenden Sie die MCP-Server-Felder auf die gleiche Weise. Wenn Sie --mcp-config mit -p übergeben, wartet Claude Code auf noch ausstehende Server, bevor der erste Turn ausgeführt wird, höchstens bis zum Start-Timeout MCP_TIMEOUT, standardmäßig 30 Sekunden. Ein Remote-Server mit einer zwischengespeicherten Tool-Liste überspringt das Warten, zeigt pending in system/init an und verbindet sich beim ersten Tool-Aufruf. In einer selbst gehosteten Umgebung gilt stattdessen eine kürzere Wartezeit. Das Warten erfordert Claude Code v2.1.221 oder später. Claude Code validiert jeden --mcp-config-Eintrag beim Start und überspringt Einträge, die die Validierung nicht bestehen, beispielsweise einen url-Eintrag ohne type. Der Lauf wird fortgesetzt und beendet sich sauber, prüfen Sie also diese Felder, um einen Server zu erkennen, der nie geladen wurde: Wenn Sie den Befehl selbst in einem Terminal ausführen, gibt Claude Code außerdem eine Startwarnung auf stderr aus, wie Warning: 1 MCP server skipped due to invalid config:, gefolgt vom Grund für jeden übersprungenen Eintrag. Wenn Sie stderr umleiten oder wenn ein Programm wie ein CI-Runner oder ein SDK-Host es erfasst, gibt Claude Code keine Warnung aus. Es meldet die übersprungenen Einträge nur im Feld mcp_server_errors.

Plugin-Installationen verfolgen

Wenn CLAUDE_CODE_SYNC_PLUGIN_INSTALL gesetzt ist, gibt Claude Code system/plugin_install-Ereignisse aus, während Marketplace-Plugins vor dem ersten Turn installiert werden. Verwenden Sie diese, um den Installationsfortschritt in Ihrer eigenen Benutzeroberfläche anzuzeigen.

Tools automatisch genehmigen

Verwenden Sie --allowedTools, damit Claude bestimmte Tools ohne Nachfrage verwenden kann. Wenn Sie Read und Edit auflisten, kann Claude Dateien lesen und bearbeiten, ohne um Erlaubnis zu fragen, ausgenommen Lesevorgänge von Netzwerkpfaden. Das Auflisten von Bash bewirkt dasselbe für Shell-Befehle, außer in einem Lauf, der im Auto-Modus startet: Dort verwirft Claude Code einen bloßen Bash-Eintrag als zu breite allow-Regel, und der Auto-Modus bewertet stattdessen jeden Befehl. Dieses Beispiel führt eine Test-Suite aus und behebt Fehler, wobei diese drei Tools aufgelistet sind:
Aufrufe von Tools, die Sie nicht aufgelistet haben, werden ausgeführt, wenn sie keine Genehmigung benötigen. In einem claude -p-Lauf im Manual-Modus wird ein Aufruf, der eine Genehmigung benötigt, verweigert, sofern ihn nicht etwas genehmigt, etwa ein PermissionRequest-Hook oder ein --permission-prompt-tool. Ab Claude Code v2.1.302 starten claude -p-Läufe im Manual-Modus, wenn nichts einen Berechtigungsmodus setzt. Um eine Baseline für die gesamte Sitzung festzulegen, anstatt einzelne Tools aufzulisten, übergeben Sie mit --permission-mode einen Berechtigungsmodus, etwa auto, dontAsk oder acceptEdits:
  • auto: Übergeben Sie --permission-mode auto, damit ein Klassifikator anstelle von Ihnen die meisten Aktionen überprüft
  • dontAsk: Claude Code verweigert jeden Aufruf, bei dem sonst nachgefragt würde, was für abgeschottete CI-Läufe nützlich ist, wobei ein von Ihnen installierter Mod einige dieser Aufrufe dennoch genehmigen kann. Welche Aufrufe ein Mod genehmigen kann, erfahren Sie unter Berechtigungen mit Hooks erweitern. Aktionen, die im Manual-Modus keine Genehmigung benötigen, werden weiterhin ausgeführt, etwa Dateilesevorgänge in Ihren Arbeitsverzeichnissen und die nur lesenden Befehle. Aktionen, die Ihre --allowedTools-Einträge oder permissions.allow-Regeln abdecken, werden ebenfalls ausgeführt. AskUserQuestion, Konnektor-Tools, die Ihre Organisation auf ask gesetzt hat, MCP-Tools, die mit requiresUserInteraction gekennzeichnet sind, und Lesevorgänge von Netzwerkpfaden werden verweigert, auch wenn eine allow-Regel passt
  • acceptEdits: Claude schreibt Dateien ohne Nachfrage, und Claude Code genehmigt automatisch häufige Dateisystembefehle wie mkdir, touch, mv und cp. Die Aktionen, die kein Modus automatisch genehmigt, gelten weiterhin. Abgesehen von den nur lesenden Befehlen benötigen andere Shell-Befehle und Netzwerkanfragen weiterhin einen --allowedTools-Eintrag oder eine permissions.allow-Regel. Siehe was acceptEdits automatisch genehmigt für die vollständige Liste
Dieses Beispiel wendet Lint-Korrekturen mit acceptEdits als Baseline an:

Berechtigungsabfragen in unbeaufsichtigten Läufen ausschalten

Übergeben Sie --permission-prompts none, wenn niemand verfügbar ist, um Berechtigungsabfragen zu beantworten, beispielsweise in einem geplanten Job. Das Flag ist vor allem dann relevant, wenn Ihr Lauf einen Berechtigungshost hat: eine Agent SDK-App mit einem canUseTool-Callback oder ein MCP-Tool, das Sie mit --permission-prompt-tool übergeben. Ohne das Flag wartet Ihr Lauf darauf, dass dieser Host jede Berechtigungsanfrage beantwortet. Mit dem Flag konsultiert Ihr Lauf den Host nicht und wartet nicht auf ihn. Alles, wofür nachgefragt würde, wird verweigert, es sei denn, ein PermissionRequest-Hook erlaubt es. Claude wird mitgeteilt, dass niemand die Anfrage genehmigen kann und dass Claude sie nicht erneut versuchen soll, und der Lauf wird fortgesetzt. In einem -p-Lauf ohne Host werden diese Anfragen ohnehin verweigert, und das Flag teilt Claude zusätzlich mit, sie nicht erneut zu versuchen. Berechtigungsregeln, PermissionRequest-Hooks und der von Ihnen festgelegte Berechtigungsmodus entscheiden weiterhin zuerst über jeden Aufruf; Claude Code verweigert nur die Anfragen, die durch nichts anderes aufgelöst werden. Dieses Beispiel führt eine unbeaufsichtigte Aufgabe im Auto-Modus aus. Der Klassifikator überprüft jede Aktion wie gewohnt, und Claude Code verweigert alles, was auf eine Berechtigungsabfrage zurückgefallen wäre:
Mit --permission-prompts none entfernt Claude Code die Tools, die eine Antwort von einer Person benötigen, wie AskUserQuestion, sodass Claude sie nicht aufrufen kann. Jede MCP-Elicitation-Anfrage, die kein Elicitation-Hook beantwortet, wird abgebrochen. Mit --output-format stream-json erscheinen Ablehnungen als permission_denied-Systemnachrichten, und die abschließende Ergebnisnachricht listet sie in permission_denials auf.
Das Flag --permission-prompts erfordert Claude Code v2.1.259 oder später. Frühere Versionen lehnen es mit einem Fehler für unbekannte Optionen ab.

Einen Commit erstellen

Dieses Beispiel überprüft bereitgestellte Änderungen und erstellt einen Commit mit einer passenden Nachricht:
Das Flag --allowedTools verwendet die Syntax für Berechtigungsregeln. Das nachgestellte * 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 auf git diff-index passen.
Die Unterstützung von Befehlen unterscheidet sich im -p-Modus:
  • Vom Benutzer aufgerufene Skills und benutzerdefinierte Befehle funktionieren. Fügen Sie /skill-name in die Prompt-Zeichenkette ein, und Claude Code erweitert ihn vor der Ausführung.
  • Integrierte Befehle, die nur in der Terminal-Oberfläche ausgeführt werden, wie /login, sind nicht verfügbar.
  • /model, /effort, /fast, /color und /rename akzeptieren den Wert als Argument, zum Beispiel /model sonnet, und /mcp ohne Argument gibt eine Textzusammenfassung des Serverstatus aus. Diese Formen folgen den Verfügbarkeitshinweisen des jeweiligen Befehls.
  • Um eine Einstellung zu ändern, übergeben Sie key=value an /config, zum Beispiel /config verbose=true.
  • /output-style <style> wechselt Ausgabestile, und /output-style allein listet sie auf. Erfordert Claude Code v2.1.269 oder später.

System-Prompt 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 Claude an, ihn auf Sicherheitslücken zu überprüfen. Speichern Sie es als Shell-Skript, zum Beispiel review.sh:
Im Skript steht "$1" für das erste Argument, das Sie in der Befehlszeile übergeben. Führen Sie bash review.sh 123 aus, und die Shell ersetzt "$1" durch 123, sodass das Skript den Diff für PR 123 abruft. Claude Code gibt die Überprüfung als JSON aus, wobei sich der Text im Feld result befindet. Siehe System-Prompt-Flags für weitere Optionen, einschließlich --system-prompt, um den Standard-Prompt vollständig zu ersetzen. Wenn Sie ihn ersetzen, startet der Lauf außerdem ohne den Git-Status-Snapshot.

Konversationen fortsetzen

Verwenden Sie --continue, um die neueste Konversation fortzusetzen, oder --resume mit einer Sitzungs-ID, um eine bestimmte Konversation fortzusetzen. Wenn Sie bei Claude Code v2.1.257 oder später --continue übergeben, öffnet Claude Code eine Hintergrundsitzung, die beendet ist, aber keine, die noch läuft. Dieses Beispiel führt eine Überprüfung durch und sendet dann Folge-Prompts:
Wenn Sie mehrere Konversationen führen, erfassen Sie die Sitzungs-ID, um eine bestimmte fortzusetzen:
Sie können die beiden Befehle aus verschiedenen Verzeichnissen ausführen: Claude Code findet die Sitzung anhand ihrer ID in jedem Projekt auf diesem Computer. Anstelle der Sitzungs-ID können Sie --resume den absoluten Pfad zur .jsonl-Transkriptdatei einer Sitzung übergeben, und Claude Code setzt die in dieser Datei gespeicherte Konversation fort.

Nächste Schritte