Claude Code SDK
Erfahren Sie, wie Sie Claude Code programmatisch in Ihre Anwendungen mit dem Claude Code SDK integrieren.
Das Claude Code SDK ermöglicht es, Claude Code als Unterprozess auszuführen und bietet eine Möglichkeit, KI-gestützte Coding-Assistenten und Tools zu erstellen, die Claudes Fähigkeiten nutzen.
Das SDK ist für die Verwendung über die Kommandozeile, TypeScript und Python verfügbar.
Authentifizierung
Das Claude Code SDK unterstützt mehrere Authentifizierungsmethoden:
Anthropic API-Schlüssel
Um das Claude Code SDK direkt mit Anthropics API zu verwenden, empfehlen wir die Erstellung eines dedizierten API-Schlüssels:
- Erstellen Sie einen Anthropic API-Schlüssel in der Anthropic Console
- Setzen Sie dann die Umgebungsvariable
ANTHROPIC_API_KEY
. Wir empfehlen, diesen Schlüssel sicher zu speichern (z.B. mit einem Github Secret)
Drittanbieter-API-Anmeldedaten
Das SDK unterstützt auch Drittanbieter-API-Provider:
- Amazon Bedrock: Setzen Sie die Umgebungsvariable
CLAUDE_CODE_USE_BEDROCK=1
und konfigurieren Sie AWS-Anmeldedaten - Google Vertex AI: Setzen Sie die Umgebungsvariable
CLAUDE_CODE_USE_VERTEX=1
und konfigurieren Sie Google Cloud-Anmeldedaten
Für detaillierte Konfigurationsanweisungen für Drittanbieter-Provider siehe die Dokumentation zu Amazon Bedrock und Google Vertex AI.
Grundlegende SDK-Verwendung
Das Claude Code SDK ermöglicht es Ihnen, Claude Code im nicht-interaktiven Modus aus Ihren Anwendungen zu verwenden.
Kommandozeile
Hier sind einige grundlegende Beispiele für das Kommandozeilen-SDK:
TypeScript
Das TypeScript SDK ist im Hauptpaket @anthropic-ai/claude-code
auf NPM enthalten:
Das TypeScript SDK akzeptiert alle Argumente, die vom Kommandozeilen-SDK unterstützt werden, sowie:
Argument | Beschreibung | Standard |
---|---|---|
abortController | Abort-Controller | new AbortController() |
cwd | Aktuelles Arbeitsverzeichnis | process.cwd() |
executable | Welche JavaScript-Laufzeit zu verwenden | node bei Ausführung mit Node.js, bun bei Ausführung mit Bun |
executableArgs | Argumente, die an die ausführbare Datei übergeben werden | [] |
pathToClaudeCodeExecutable | Pfad zur Claude Code-Ausführungsdatei | Ausführbare Datei, die mit @anthropic-ai/claude-code geliefert wird |
Python
Das Python SDK ist als claude-code-sdk
auf PyPI verfügbar:
Voraussetzungen:
- Python 3.10+
- Node.js
- Claude Code CLI:
npm install -g @anthropic-ai/claude-code
Grundlegende Verwendung:
Das Python SDK akzeptiert alle Argumente, die vom Kommandozeilen-SDK unterstützt werden, über die ClaudeCodeOptions
-Klasse:
Erweiterte Verwendung
Die nachfolgende Dokumentation verwendet das Kommandozeilen-SDK als Beispiel, kann aber auch mit den TypeScript- und Python-SDKs verwendet werden.
Multi-Turn-Gespräche
Für Multi-Turn-Gespräche können Sie Gespräche fortsetzen oder von der neuesten Sitzung aus weitermachen:
Benutzerdefinierte System-Prompts
Sie können benutzerdefinierte System-Prompts bereitstellen, um Claudes Verhalten zu steuern:
Sie können auch Anweisungen an den Standard-System-Prompt anhängen:
MCP-Konfiguration
Das Model Context Protocol (MCP) ermöglicht es Ihnen, Claude Code mit zusätzlichen Tools und Ressourcen von externen Servern zu erweitern. Mit dem --mcp-config
-Flag können Sie MCP-Server laden, die spezialisierte Fähigkeiten wie Datenbankzugriff, API-Integrationen oder benutzerdefinierte Tools bereitstellen.
Erstellen Sie eine JSON-Konfigurationsdatei mit Ihren MCP-Servern:
Verwenden Sie es dann mit Claude Code:
Bei der Verwendung von MCP-Tools müssen Sie diese explizit mit dem --allowedTools
-Flag erlauben. MCP-Tool-Namen folgen dem Muster mcp__<serverName>__<toolName>
, wobei:
serverName
der Schlüssel aus Ihrer MCP-Konfigurationsdatei isttoolName
das spezifische Tool ist, das von diesem Server bereitgestellt wird
Diese Sicherheitsmaßnahme stellt sicher, dass MCP-Tools nur verwendet werden, wenn sie explizit erlaubt sind.
Wenn Sie nur den Servernamen angeben (d.h. mcp__<serverName>
), werden alle Tools von diesem Server erlaubt.
Glob-Muster (z.B. mcp__go*
) werden nicht unterstützt.
Benutzerdefiniertes Berechtigungsaufforderungs-Tool
Verwenden Sie optional --permission-prompt-tool
, um ein MCP-Tool zu übergeben, das wir verwenden werden, um zu überprüfen, ob der Benutzer dem Modell die Berechtigung erteilt, ein bestimmtes Tool aufzurufen. Wenn das Modell ein Tool aufruft, passiert Folgendes:
- Wir überprüfen zuerst die Berechtigungseinstellungen: alle settings.json-Dateien sowie
--allowedTools
und--disallowedTools
, die an das SDK übergeben wurden; wenn eine davon den Tool-Aufruf erlaubt oder verweigert, fahren wir mit dem Tool-Aufruf fort - Andernfalls rufen wir das MCP-Tool auf, das Sie in
--permission-prompt-tool
bereitgestellt haben
Das --permission-prompt-tool
MCP-Tool erhält den Tool-Namen und die Eingabe und muss eine JSON-stringifizierte Nutzlast mit dem Ergebnis zurückgeben. Die Nutzlast muss eine der folgenden sein:
Zum Beispiel könnte eine TypeScript MCP-Berechtigungsaufforderungs-Tool-Implementierung so aussehen:
Um dieses Tool zu verwenden, fügen Sie Ihren MCP-Server hinzu (z.B. mit --mcp-config
) und rufen Sie dann das SDK so auf:
Verwendungshinweise:
- Verwenden Sie
updatedInput
, um dem Modell mitzuteilen, dass die Berechtigungsaufforderung seine Eingabe verändert hat; setzen Sie andernfallsupdatedInput
auf die ursprüngliche Eingabe, wie im obigen Beispiel. Wenn das Tool beispielsweise einem Benutzer ein Datei-Edit-Diff zeigt und ihm erlaubt, das Diff manuell zu bearbeiten, sollte das Berechtigungsaufforderungs-Tool diese aktualisierte Bearbeitung zurückgeben. - Die Nutzlast muss JSON-stringifiziert sein
Verfügbare CLI-Optionen
Das SDK nutzt alle CLI-Optionen, die in Claude Code verfügbar sind. Hier sind die wichtigsten für die SDK-Verwendung:
Flag | Beschreibung | Beispiel |
---|---|---|
--print , -p | Im nicht-interaktiven Modus ausführen | claude -p "Abfrage" |
--output-format | Ausgabeformat angeben (text , json , stream-json ) | claude -p --output-format json |
--resume , -r | Ein Gespräch anhand der Sitzungs-ID fortsetzen | claude --resume abc123 |
--continue , -c | Das neueste Gespräch fortsetzen | claude --continue |
--verbose | Ausführliche Protokollierung aktivieren | claude --verbose |
--max-turns | Agentische Wendungen im nicht-interaktiven Modus begrenzen | claude --max-turns 3 |
--system-prompt | System-Prompt überschreiben (nur mit --print ) | claude --system-prompt "Benutzerdefinierte Anweisung" |
--append-system-prompt | An System-Prompt anhängen (nur mit --print ) | claude --append-system-prompt "Benutzerdefinierte Anweisung" |
--allowedTools | Leerzeichengetrennte Liste erlaubter Tools, oder Zeichenkette mit kommagetrennte Liste erlaubter Tools | claude --allowedTools mcp__slack mcp__filesystem claude --allowedTools "Bash(npm install),mcp__filesystem" |
--disallowedTools | Leerzeichengetrennte Liste verweigerter Tools, oder Zeichenkette mit kommagetrennte Liste verweigerter Tools | claude --disallowedTools mcp__splunk mcp__github claude --disallowedTools "Bash(git commit),mcp__github" |
--mcp-config | MCP-Server aus einer JSON-Datei laden | claude --mcp-config servers.json |
--permission-prompt-tool | MCP-Tool für die Behandlung von Berechtigungsaufforderungen (nur mit --print ) | claude --permission-prompt-tool mcp__auth__prompt |
Für eine vollständige Liste der CLI-Optionen und -Funktionen siehe die Dokumentation zur CLI-Referenz.
Ausgabeformate
Das SDK unterstützt mehrere Ausgabeformate:
Textausgabe (Standard)
Gibt nur den Antworttext zurück:
JSON-Ausgabe
Gibt strukturierte Daten einschließlich Metadaten zurück:
Antwortformat:
Streaming-JSON-Ausgabe
Streamt jede Nachricht, während sie empfangen wird:
Jedes Gespräch beginnt mit einer anfänglichen init
-Systemnachricht, gefolgt von einer Liste von Benutzer- und Assistentennachrichten, gefolgt von einer abschließenden result
-Systemnachricht mit Statistiken. Jede Nachricht wird als separates JSON-Objekt ausgegeben.
Nachrichtenschema
Nachrichten, die von der JSON-API zurückgegeben werden, sind streng typisiert gemäß dem folgenden Schema:
Wir werden diese Typen bald in einem JSONSchema-kompatiblen Format veröffentlichen. Wir verwenden semantische Versionierung für das Haupt-Claude-Code-Paket, um Breaking Changes an diesem Format zu kommunizieren.
Message
- und MessageParam
-Typen sind in Anthropic SDKs verfügbar. Siehe zum Beispiel die Anthropic TypeScript- und Python-SDKs.
Eingabeformate
Das SDK unterstützt mehrere Eingabeformate:
Texteingabe (Standard)
Eingabetext kann als Argument bereitgestellt werden:
Oder Eingabetext kann über stdin weitergeleitet werden:
Streaming-JSON-Eingabe
Ein Stream von Nachrichten, die über stdin
bereitgestellt werden, wobei jede Nachricht eine Benutzerwendung darstellt. Dies ermöglicht mehrere Wendungen eines Gesprächs, ohne die claude
-Binärdatei neu zu starten, und ermöglicht es, dem Modell Anleitung zu geben, während es eine Anfrage verarbeitet.
Jede Nachricht ist ein JSON-‘Benutzernachricht’-Objekt, das dem gleichen Format wie das Ausgabenachrichtenschema folgt. Nachrichten werden mit dem jsonl-Format formatiert, wobei jede Eingabezeile ein vollständiges JSON-Objekt ist. Streaming-JSON-Eingabe erfordert -p
und --output-format stream-json
.
Derzeit ist dies auf reine Textnachrichten von Benutzern beschränkt.
Beispiele
Einfache Skriptintegration
Dateien mit Claude verarbeiten
Sitzungsverwaltung
Best Practices
-
Verwenden Sie das JSON-Ausgabeformat für programmatisches Parsen von Antworten:
-
Behandeln Sie Fehler elegant - überprüfen Sie Exit-Codes und stderr:
-
Verwenden Sie Sitzungsverwaltung für die Aufrechterhaltung des Kontexts in Multi-Turn-Gesprächen
-
Berücksichtigen Sie Timeouts für langwierige Operationen:
-
Respektieren Sie Rate-Limits bei mehreren Anfragen, indem Sie Verzögerungen zwischen Aufrufen hinzufügen
Reale Anwendungen
Das Claude Code SDK ermöglicht leistungsstarke Integrationen in Ihren Entwicklungsworkflow. Ein bemerkenswertes Beispiel sind die Claude Code GitHub Actions, die das SDK verwenden, um automatisierte Code-Review-, PR-Erstellungs- und Issue-Triage-Funktionen direkt in Ihrem GitHub-Workflow bereitzustellen.
Verwandte Ressourcen
- CLI-Verwendung und -Steuerung - Vollständige CLI-Dokumentation
- GitHub Actions-Integration - Automatisieren Sie Ihren GitHub-Workflow mit Claude
- Häufige Workflows - Schritt-für-Schritt-Anleitungen für häufige Anwendungsfälle