Berechtigungen konfigurieren
Kontrollieren Sie, wie Ihr Agent Tools mit Berechtigungsmodi, Hooks und deklarativen Allow/Deny-Regeln verwendet.
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.
Wie Berechtigungen ausgewertet werden
Wenn Claude ein Tool anfordert, prüft das SDK die Berechtigungen in dieser Reihenfolge:
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. Ein PreToolUse-Hook-Allow kann auch keine rm- oder rmdir-Entfernung genehmigen, die auf einen kritischen Pfad abzielt.
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.
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.
Berechtigungsmodus
Wenden Sie den aktiven Berechtigungsmodus an:
- Im
bypassPermissions-Modus genehmigt Claude Code alles, das diesen Schritt erreicht, außerrm- undrmdir-Entfernungen, die auf einen kritischen Pfad abzielen, die stattdessen durchfallen. - Im
acceptEdits-Modus genehmigt Claude Code die unter Accept edits mode aufgelisteten Dateivorgänge. - Im
plan-Modus leitet Claude Code Datei-Edit- und Shell-Write-Tools zu IhremcanUseTool-Callback weiter, unabhängig von Allow-Regeln, sodass Schreibvorgänge während der Planung nicht automatisch genehmigt werden können. - In anderen Modi fällt die Anfrage durch.
Allow-Regeln
Prüfen Sie allow-Regeln (aus allowed_tools und settings.json). Wenn eine Regel zutrifft, wird das Tool genehmigt. Ein Aufruf, den das Tool selbst genehmigt, wird auch in diesem Schritt gelöst, ohne dass eine Regel erforderlich ist: zum Beispiel ein Dateilesezugriff in Ihren Arbeitsverzeichnissen oder ein schreibgeschützter Bash-Befehl. rm- und rmdir-Entfernungen, die auf einen kritischen Pfad abzielen, werden niemals durch eine Allow-Regel genehmigt: Sie erreichen Ihren Callback in den Modi, die Aufforderungen anzeigen, gehen zum Klassifizierer im auto-Modus auf Claude Code v2.1.218 oder später, und werden im dontAsk-Modus abgelehnt.
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.
Im TypeScript SDK wird Ihr Callback in diesem Schritt nicht aufgerufen, wenn Sie permissionPrompts: 'none' setzen. Ein PermissionRequest-Hook erhält immer noch eine Chance zu entscheiden, und wenn nicht, lehnt Claude Code den Aufruf ab. Die Option erfordert Claude Code v2.1.259 oder später.
Wenn Sie einen canUseTool-Callback in einer Konfiguration übergeben, in der das TypeScript SDK erwartet, dass die Auswertungsreihenfolge Aufrufe automatisch genehmigt, bevor der Callback konsultiert wird, gibt das SDK eine Node.js-Prozesswarnung aus, sobald die Abfrage konstruiert wird. 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, außer den Aktionen, die kein Modus automatisch genehmigt- Jeder bare
allowedTools-Eintrag wie"Read", der dieses gesamte Tool automatisch genehmigt, bevor der Callback konsultiert wird, außer den Aktionen, die kein Modus automatisch genehmigt
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:
- Hooks: Führen Sie benutzerdefinierten Code aus, um Tool-Anfragen zu genehmigen, abzulehnen oder zu ändern. Siehe Ausführung mit Hooks steuern.
- canUseTool-Callback: Fordern Sie Benutzer zur Laufzeit zur Genehmigung auf, wenn kein früherer Schritt den Aufruf löst. Siehe Genehmigungen und Benutzereingaben handhaben.
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. Wenn Sie eines der Task-Tracking-Tools in allowed_tools benennen, aktiviert Claude Code auch die Sitzung. Jedes andere Tool, das nicht in allowed_tools aufgelistet ist, ist immer noch für Claude verfügbar, und ein Aufruf dazu, der eine Genehmigung benötigt, fällt durch zum Berechtigungsmodus. Deny-Regeln verhalten sich unterschiedlich, je nachdem, ob sie ein Tool benennen oder ein Muster innerhalb eines Tools eingrenzen.
| Option | Auswirkung |
|---|---|
allowed_tools=["Read", "Grep"] |
Read und Grep werden automatisch genehmigt. Andere Tools, die hier nicht aufgelistet sind, existieren immer noch, und Aufrufe dazu, die eine Genehmigung benötigen, fallen durch zum Berechtigungsmodus und canUseTool. |
disallowed_tools=["Bash"] |
Die Bash-Tool-Definition wird aus der Anfrage entfernt. Claude sieht das Tool nicht und kann es nicht versuchen. |
disallowed_tools=["Bash(rm *)"] |
Bash bleibt verfügbar. Aufrufe, die rm * entsprechen, wie geschrieben, werden in jedem Berechtigungsmodus abgelehnt, einschließlich bypassPermissions. Andere Bash-Aufrufe, einschließlich /bin/rm, fallen durch zum Berechtigungsmodus. |
disallowed_tools=["*"] |
Jede Tool-Definition wird aus der Anfrage entfernt. Tool-Name-Globs werden in Deny-Regeln unterstützt: "*" entspricht jedem Tool und "mcp__*" entspricht jedem MCP-Tool über alle Server hinweg. |
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.
Für einen gesperrten Agent kombinieren Sie allowedTools mit permissionMode: "dontAsk":
const options = {
allowedTools: ["Read", "Glob", "Grep"],
permissionMode: "dontAsk"
};
Aufgelistete Tools werden genehmigt, abgesehen von den Aktionen, die kein Modus automatisch genehmigt, und jeder andere Aufruf, der eine Aufforderung auslösen würde, wird stattdessen abgelehnt. Aufrufe, die im default-Modus keine Genehmigung benötigen, werden ausgeführt, unabhängig davon, ob Sie sie aufgelistet haben, wie z. B. schreibgeschützte Bash-Befehle, Tools wie Agent, die vor dem Ausführen nicht fragen, und Dateileseoperationen in Ihren Arbeitsverzeichnissen. Um ein Tool vollständig außerhalb von Claudes Reichweite zu platzieren, fügen Sie seinen einfachen Namen zu disallowedTools hinzu.
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:
| Modus | Beschreibung | Tool-Verhalten |
|---|---|---|
default |
Standardberechtigungsverhalten | Keine modusgestützten automatischen Genehmigungen; Aufrufe, die Genehmigung benötigen und keine Allow-Regel erfüllen, lösen Ihren canUseTool-Callback aus |
dontAsk |
Ablehnung statt Nachfrage | Jeder Aufruf, der sonst eine Nachfrage auslösen würde, wird abgelehnt. Aufrufe, die von allowed_tools oder Regeln genehmigt sind, werden ausgeführt, ebenso wie Aufrufe, die im default-Modus keine Genehmigung benötigen; Connector-Tools die Ihre Organisation auf ask gesetzt hat und Tools, die Benutzerinteraktion erfordern, werden abgelehnt, auch wenn Sie sie vorab genehmigt haben, ebenso wie rm und rmdir Löschungen, die auf einen kritischen Pfad abzielen. canUseTool wird nie aufgerufen |
acceptEdits |
Dateibearbeitungen automatisch akzeptieren | Dateibearbeitungen und Dateisystemvorgänge (mkdir, rm, mv usw.) werden automatisch genehmigt |
bypassPermissions |
Berechtigungsprüfungen umgehen | Tools werden ohne Berechtigungsaufforderungen ausgeführt, mit Ausnahme von Aktionen, die kein Modus automatisch genehmigt. Mit Vorsicht verwenden |
plan |
Planungsmodus | Claude erkundet und plant, ohne Ihre Quelldateien zu bearbeiten; Dateibearbeitungen werden nie automatisch genehmigt und werden durch Ihren canUseTool-Callback angefordert |
auto |
Modellklassifizierte Genehmigungen | Ein Modellklassifizierer genehmigt oder lehnt Berechtigungsaufforderungen ab. Siehe Auto-Modus für Verfügbarkeit |
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.
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="Help me refactor this code",
options=ClaudeAgentOptions(
permission_mode="default", # Set the mode here
),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())
import { query } from "@anthropic-ai/claude-agent-sdk";
async function main() {
for await (const message of query({
prompt: "Help me refactor this code",
options: {
permissionMode: "default" // Set the mode here
}
})) {
if ("result" in message) {
console.log(message.result);
}
}
}
main();
Rufen Sie set_permission_mode() (Python) oder setPermissionMode() (TypeScript) auf, um den Modus während der Sitzung zu ändern. Der neue Modus wird sofort für alle nachfolgenden Tool-Anfragen wirksam. Dies ermöglicht es Ihnen, restriktiv zu beginnen und Berechtigungen zu lockern, wenn Vertrauen aufgebaut wird, z. B. zum Wechsel zu acceptEdits nach Überprüfung von Claudes anfänglichem Ansatz.
import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
async def main():
async with ClaudeSDKClient(
options=ClaudeAgentOptions(
permission_mode="default", # Start in default mode
)
) as client:
await client.query("Help me refactor this code")
# Change mode dynamically mid-session
await client.set_permission_mode("acceptEdits")
# Process messages with the new permission mode
async for message in client.receive_response():
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())
import { query } from "@anthropic-ai/claude-agent-sdk";
async function main() {
const q = query({
prompt: "Help me refactor this code",
options: {
permissionMode: "default" // Start in default mode
}
});
// Change mode dynamically mid-session
await q.setPermissionMode("acceptEdits");
// Process messages with the new permission mode
for await (const message of q) {
if ("result" in message) {
console.log(message.result);
}
}
}
main();
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. Im acceptEdits-Modus genehmigt Claude Code die Anfrage nicht automatisch, wenn Claude:
- An einem Pfad außerhalb dieses Bereichs arbeitet
- In einen geschützten Pfad schreibt
- Einen kritischen Pfad mit
rmoderrmdirlöscht
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, ohne canUseTool aufzurufen. Tools, die von allowed_tools, settings.json-Allow-Regeln oder einem Hook vorab genehmigt sind, werden normal ausgeführt, ebenso wie Aufrufe, die im default-Modus keine Genehmigung benötigen, wie Dateilesevorgänge in Ihren Arbeitsverzeichnissen und Aufrufe an Agent. Connector-Tools die Ihre Organisation auf ask gesetzt hat, Tools, die Benutzerinteraktion erfordern, und rm und rmdir Löschungen, die auf einen kritischen Pfad abzielen, werden abgelehnt, auch wenn eine Allow-Regel stimmt. Ein PreToolUse Hook Allow hebt eine kritische Pfad-Löschung auch nicht auf.
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 Tool-Nutzungen ohne Aufforderungen, mit Ausnahme der in der Warnung unten aufgelisteten Fälle. Hooks werden weiterhin ausgeführt und können Vorgänge bei Bedarf blockieren.
Plan-Modus (`plan`)
Claude erkundet die Codebasis und erstellt einen Plan, ohne Ihre Quelldateien zu bearbeiten. Schreibgeschützte Tools werden wie im default-Berechtigungsmodus ausgeführt.
Dateibearbeitungen werden im Plan-Modus nie automatisch genehmigt, auch wenn eine Allow-Regel stimmt. Sie werden stattdessen durch Ihren canUseTool-Callback angefordert. Auf Claude Code v2.1.212 oder später erreichen Shell-Befehle, die Dateien ändern, wie touch und rm, Ihren canUseTool-Callback auf die gleiche Weise.
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.
Verwandte Ressourcen
Für die anderen Schritte im Berechtigungsauswertungsfluss:
- Genehmigungen und Benutzereingaben handhaben: interaktive Genehmigungsaufforderungen und Klärungsfragen
- Hooks-Anleitung: Führen Sie benutzerdefinierten Code an Schlüsselpunkten im Agent-Lebenszyklus aus
- Berechtigungsregeln: deklarative Allow/Deny-Regeln in
settings.json