Zum Hauptinhalt springen
Das Claude Agent SDK bietet Berechtigungskontrollen zur Verwaltung der Tool-Nutzung durch Claude. Verwenden Sie Berechtigungsmodi und Regeln, um zu definieren, was automatisch zulässig ist, und den canUseTool-Callback, um alles andere zur Laufzeit zu handhaben.
Diese Seite behandelt Berechtigungsmodi und Regeln. Um interaktive Genehmigungsabläufe zu erstellen, bei denen Benutzer Tool-Anfragen zur Laufzeit genehmigen oder ablehnen, siehe Genehmigungen und Benutzereingaben handhaben.

Wie Berechtigungen ausgewertet werden

Wenn Claude ein Tool anfordert, prüft das SDK die Berechtigungen in dieser Reihenfolge:
1

Hooks

Führen Sie Hooks zuerst aus. Ein Hook kann den Aufruf direkt ablehnen oder ihn weitergeben. Ein Hook, der allow zurückgibt, überspringt nicht die Deny- und Ask-Regeln unten; diese werden unabhängig vom Hook-Ergebnis ausgewertet.
2

Deny-Regeln

Prüfen Sie deny-Regeln (aus disallowed_tools und settings.json). Wenn eine Deny-Regel zutrifft, wird das Tool blockiert, auch im bypassPermissions-Modus. Bare-Name-Deny-Regeln wie Bash entfernen das Tool aus Claudes Kontext, bevor diese Auswertung beginnt, daher werden nur scoped-Regeln wie Bash(rm *) in diesem Schritt geprüft.
3

Ask-Regeln

Prüfen Sie ask-Regeln aus settings.json. Wenn eine Ask-Regel zutrifft, fällt der Aufruf zu Ihrem canUseTool-Callback zur Bestätigung durch, auch im bypassPermissions-Modus.Tools, die Benutzerinteraktion erfordern, verhalten sich auf die gleiche Weise: AskUserQuestion und MCP-Tools, deren Server _meta["anthropic/requiresUserInteraction"] setzt, fallen immer zum Callback durch, auch wenn eine Allow-Regel zutrifft. Im dontAsk-Modus werden beide Fälle stattdessen abgelehnt, da dieser Modus niemals eine Aufforderung anzeigt. Die MCP-Anmerkung erfordert Claude Code v2.1.199 oder später.claude.ai-Connector-Tools, die Ihre Organisation auf ask gesetzt hat, verlassen den Fluss auch in diesem Schritt. Jeder Aufruf fällt zum Callback durch, auch im bypassPermissions-Modus und auch wenn eine Allow-Regel zutrifft. Der Callback erhält den Grund Your organization requires approval for this tool. Im dontAsk-Modus wird der Aufruf stattdessen abgelehnt, da dieser Modus niemals eine Aufforderung anzeigt.
4

Berechtigungsmodus

Wenden Sie den aktiven Berechtigungsmodus an. bypassPermissions genehmigt alles, das diesen Schritt erreicht. acceptEdits genehmigt Dateivorgänge. plan leitet Datei-Edit- und Shell-Write-Tools zu Ihrem canUseTool-Callback weiter, unabhängig von Allow-Regeln, sodass Schreibvorgänge während der Planung nicht automatisch genehmigt werden können. Andere Modi fallen durch.
5

Allow-Regeln

Prüfen Sie allow-Regeln (aus allowed_tools und settings.json). Wenn eine Regel zutrifft, wird das Tool genehmigt.
6

canUseTool-Callback

Wenn nicht durch eines der oben genannten Verfahren gelöst, rufen Sie Ihren canUseTool-Callback für eine Entscheidung auf. Im dontAsk-Modus wird dieser Schritt übersprungen und das Tool wird abgelehnt.
Diagramm des sechsstufigen Berechtigungsauswertungsflusses, das den obigen Schritten entspricht: Eine Tool-Anfrage durchläuft Hooks, Deny-Regeln, Ask-Regeln, Berechtigungsmodus, Allow-Regeln und canUseTool. Hooks, Deny-Regeln und canUseTool können zu Blockiert weiterleiten; Berechtigungsmodus-Bypass, Allow-Regeln und canUseTool können zu Ausführen weiterleiten; Ask-Regeln leiten zu canUseTool weiter. Ab v2.1.198 gibt das TypeScript SDK eine Node.js-Prozesswarnung aus, wenn Sie einen canUseTool-Callback übergeben, den diese Auswertungsreihenfolge niemals erreichen kann. Der Warnungscode ist CLAUDE_SDK_CAN_USE_TOOL_SHADOWED. Zwei Konfigurationen lösen ihn aus:
  • permissionMode: 'bypassPermissions', das jeden Aufruf, der den Berechtigungsmodus-Schritt erreicht, automatisch genehmigt
  • Jeder bare allowedTools-Eintrag wie "Read", der dieses gesamte Tool automatisch genehmigt, bevor der Callback konsultiert wird
Einträge mit einem Spezifizierer wie Bash(ls *) und der acceptEdits-Modus lösen ihn nicht aus, und Allow-Regeln aus Einstellungsdateien sind für die Prüfung nicht sichtbar. Hören Sie mit process.on('warning', ...) zu und gleichen Sie den Code ab, um ihn zu protokollieren oder zu unterdrücken. Um jeden Tool-Aufruf unabhängig von Modus und Regeln zu steuern, verwenden Sie stattdessen einen PreToolUse-Hook. Diese Seite konzentriert sich auf Allow- und Deny-Regeln sowie Berechtigungsmodi. Für die anderen Schritte:

Allow- und Deny-Regeln

allowed_tools und disallowed_tools (TypeScript: allowedTools / disallowedTools) fügen Einträge zu den Allow- und Deny-Regellisten im obigen Auswertungsfluss hinzu. Allow-Regeln beeinflussen nur die Genehmigung: Ein Tool, das nicht in allowed_tools aufgelistet ist, ist immer noch für Claude verfügbar und fällt durch zum Berechtigungsmodus. Deny-Regeln verhalten sich unterschiedlich, je nachdem, ob sie ein Tool benennen oder ein Muster innerhalb eines Tools eingrenzen. Allow-Regeln akzeptieren Tool-Name-Globs nur nach einem literalen mcp__<server>__-Präfix. Das Server-Segment muss glob-frei sein, damit die Regel einen bestimmten Server benennt, den Sie konfiguriert haben: mcp__puppeteer__* entspricht jedem Tool vom puppeteer-Server, und mcp__github__get_* entspricht seinen get_-Tools. Ein unverankter Eintrag wie allowed_tools=["*"] oder allowed_tools=["mcp__*"] wird mit einer Startwarnmeldung ignoriert und genehmigt nichts automatisch. Begrenzte Regeln für Read und Edit verwenden ein Pfadmuster. Edit(path)-Regeln regeln alle integrierten Tools, die Dateien schreiben, einschließlich Write und NotebookEdit; eine Write(path)-Regel wird nie von den Dateiberechtigungsprüfungen erfasst. Verwenden Sie //path für einen absoluten Dateisystempfad: Eine Deny-Regel von Edit(//secrets/**) blockiert Schreibvorgänge überall unter /secrets auf der Festplatte. Mit einem einzelnen führenden Schrägstrich verankert Edit(/secrets/**) stattdessen an der Quelle der Regel. Für Regeln, die durch allowed_tools oder disallowed_tools übergeben werden, bedeutet das das Arbeitsverzeichnis der Sitzung, sodass die Regel /secrets auf der Festplatte nicht blockiert. Siehe Read- und Edit-Regeln für die vier Ankerformen und wie Regeln aus Einstellungsdateien aufgelöst werden.
Auto-genehmigte Tools erreichen canUseTool nie. Ein Tool-Aufruf, der in einem früheren Schritt genehmigt wurde, durch acceptEdits oder bypassPermissions, oder durch eine Allow-Regel, überspringt Ihren canUseTool-Callback, sodass Berechtigungsprüfungen, die Sie dort durchführen, für dieses Tool stillschweigend umgangen werden. AskUserQuestion, MCP-Tools, die mit _meta["anthropic/requiresUserInteraction"] gekennzeichnet sind, und Connector-Tools, die Ihre Organisation auf ask gesetzt hat, erreichen den Callback immer noch, auch wenn eine Allow-Regel passt.Die Abdeckung hängt von der Form des Eintrags ab: Ein einfacher Name wie Read oder mcp__github__get_issue genehmigt jeden Aufruf dieses Tools automatisch, während eine begrenzte Regel wie Bash(ls *) nur übereinstimmende Aufrufe automatisch genehmigt und andere Bash-Aufrufe immer noch zum Callback fallen. Für Prüfungen, die bei jedem Tool-Aufruf ausgeführt werden müssen, verwenden Sie einen PreToolUse-Hook: Hooks werden vor jedem anderen Schritt ausgeführt, und eine Hook-Ablehnung gilt auch im bypassPermissions-Modus.
Für einen gesperrten Agent kombinieren Sie allowedTools mit permissionMode: "dontAsk". Aufgelistete Tools werden genehmigt, abgesehen von den immer-Prompt-Tools in der obigen Warnung; alles andere wird direkt abgelehnt, anstatt zu fragen:
allowed_tools beschränkt bypassPermissions nicht. allowed_tools genehmigt nur die Tools, die Sie aufgelistet haben. Nicht aufgelistete Tools werden von keiner Allow-Regel erfasst und fallen durch zum Berechtigungsmodus, wo bypassPermissions sie genehmigt. Das Setzen von allowed_tools=["Read"] zusammen mit permission_mode="bypassPermissions" genehmigt immer noch jedes Tool, einschließlich Bash, Write und Edit. Wenn Sie bypassPermissions benötigen, aber bestimmte Tools blockieren möchten, verwenden Sie disallowed_tools.
Sie können Allow-, Deny- und Ask-Regeln auch deklarativ in .claude/settings.json konfigurieren. Diese Regeln werden gelesen, wenn die project-Einstellungsquelle aktiviert ist, was sie für Standard-query()-Optionen ist. Wenn Sie setting_sources (TypeScript: settingSources) explizit setzen, fügen Sie "project" ein, damit sie angewendet werden. Siehe Berechtigungseinstellungen für die Regelsyntax.

Berechtigungsmodi

Berechtigungsmodi bieten globale Kontrolle über die Tool-Nutzung durch Claude. Sie können den Berechtigungsmodus beim Aufrufen von query() setzen oder ihn dynamisch während Streaming-Sitzungen ändern.

Verfügbare Modi

Das SDK unterstützt diese Berechtigungsmodi:
Subagent-Vererbung: Wenn der übergeordnete Agent bypassPermissions, acceptEdits oder auto verwendet, erben alle Subagents diesen Modus und er kann nicht pro Subagent überschrieben werden. Subagents können unterschiedliche Systemaufforderungen und weniger eingeschränktes Verhalten als Ihr Hauptagent haben, daher erbt bypassPermissions ihnen vollständigen, autonomen Systemzugriff. Explizite ask-Regeln, Connector-Tools die Ihre Organisation auf ask gesetzt hat und Tools, die Benutzerinteraktion erfordern, erzwingen weiterhin eine Aufforderung.

Berechtigungsmodus setzen

Sie können den Berechtigungsmodus einmal beim Starten einer Abfrage setzen oder ihn dynamisch ändern, während die Sitzung aktiv ist.
Übergeben Sie permission_mode (Python) oder permissionMode (TypeScript) beim Erstellen einer Abfrage. Dieser Modus gilt für die gesamte Sitzung, es sei denn, er wird dynamisch geändert.

Modusdetails

Accept Edits-Modus (acceptEdits)

Genehmigt automatisch Dateivorgänge, damit Claude Code ohne Aufforderung bearbeiten kann. Andere Tools (wie Bash-Befehle, die keine Dateisystemvorgänge sind) erfordern weiterhin normale Berechtigungen. Automatisch genehmigte Vorgänge:
  • Dateibearbeitungen (Edit-, Write-Tools)
  • Dateisystembefehle: mkdir, touch, rm, rmdir, mv, cp, sed
Beide gelten nur für Pfade innerhalb des Arbeitsverzeichnisses oder additionalDirectories. Pfade außerhalb dieses Bereichs und Schreibvorgänge auf geschützte Pfade werden weiterhin angefordert. Verwenden Sie, wenn: Sie Claudes Bearbeitungen vertrauen und schnellere Iteration wünschen, z. B. während der Prototypenerstellung oder beim Arbeiten in einem isolierten Verzeichnis.

Don’t Ask-Modus (dontAsk)

Konvertiert jede Berechtigungsaufforderung in eine Ablehnung. Tools, die von allowed_tools, settings.json-Allow-Regeln oder einem Hook vorab genehmigt sind, werden normal ausgeführt. Connector-Tools die Ihre Organisation auf ask gesetzt hat und Tools, die Benutzerinteraktion erfordern, werden abgelehnt, auch wenn eine Allow-Regel stimmt. Alles andere wird abgelehnt, ohne canUseTool aufzurufen. Verwenden Sie, wenn: Sie eine feste, explizite Tool-Oberfläche für einen Headless-Agent wünschen und eine harte Ablehnung gegenüber stiller Abhängigkeit von fehlender canUseTool bevorzugen.

Bypass Permissions-Modus (bypassPermissions)

Genehmigt automatisch alle Tool-Nutzungen ohne Aufforderungen. Hooks werden weiterhin ausgeführt und können Vorgänge bei Bedarf blockieren.
Mit äußerster Vorsicht verwenden. Claude hat in diesem Modus vollständigen Systemzugriff. Verwenden Sie nur in kontrollierten Umgebungen, in denen Sie allen möglichen Vorgängen vertrauen.allowed_tools beschränkt diesen Modus nicht. Jedes Tool wird genehmigt, nicht nur die, die Sie aufgelistet haben. Deny-Regeln (disallowed_tools), explizite ask-Regeln und Hooks werden vor der Modusüberprüfung ausgewertet und können ein Tool immer noch blockieren. Connector-Tools die Ihre Organisation auf ask gesetzt hat und Tools, die Benutzerinteraktion erfordern, fallen weiterhin in Ihren canUseTool-Callback.

Plan-Modus (plan)

Claude erkundet die Codebasis und erstellt einen Plan, ohne Ihre Quelldateien zu bearbeiten. Schreibgeschützte Tools werden wie im Standard-Modus ausgeführt. Dateibearbeitungen werden im Plan-Modus nie automatisch genehmigt, auch wenn eine Allow-Regel stimmt. Sie werden stattdessen durch Ihren canUseTool-Callback angefordert. Claude kann AskUserQuestion verwenden, um Anforderungen zu klären, bevor der Plan abgeschlossen wird. Siehe Genehmigungen und Benutzereingaben handhaben für die Behandlung dieser Aufforderungen. Verwenden Sie, wenn: Sie möchten, dass Claude Änderungen vorschlägt, ohne sie auszuführen, z. B. während der Code-Überprüfung oder wenn Sie Änderungen genehmigen müssen, bevor sie vorgenommen werden. Für die anderen Schritte im Berechtigungsauswertungsfluss: