Berechtigungen konfigurieren - Claude Code Docs

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:

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.

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.

Berechtigungsmodus

Wenden Sie den aktiven Berechtigungsmodus an. bypassPermissions genehmigt alles, das diesen Schritt erreicht. acceptEdits genehmigt Dateivorgänge. Andere Modi fallen durch.

Allow-Regeln

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

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 Berechtigungsauswertungsflusses

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. 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. 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.

Option	Auswirkung
`allowed_tools=["Read", "Grep"]`	`Read` und `Grep` werden automatisch genehmigt. Tools, die hier nicht aufgelistet sind, existieren immer noch und 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, werden in jedem Berechtigungsmodus abgelehnt, einschließlich `bypassPermissions`. Andere `Bash`-Aufrufe fallen durch zum Berechtigungsmodus.

Für einen gesperrten Agent kombinieren Sie allowedTools mit permissionMode: "dontAsk". Aufgelistete Tools werden genehmigt; alles andere wird direkt abgelehnt, anstatt zu fragen:

const options = {
  allowedTools: ["Read", "Glob", "Grep"],
  permissionMode: "dontAsk"
};

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:

Modus	Beschreibung	Tool-Verhalten
`default`	Standardberechtigungsverhalten	Keine automatischen Genehmigungen; nicht übereinstimmende Tools lösen Ihren `canUseTool`-Callback aus
`dontAsk`	Ablehnung statt Nachfrage	Alles, das nicht von `allowed_tools` oder Regeln vorab genehmigt ist, wird abgelehnt; `canUseTool` wird nie aufgerufen
`acceptEdits`	Dateibearbeitungen automatisch akzeptieren	Dateibearbeitungen und Dateisystemvorgänge (`mkdir`, `rm`, `mv` usw.) werden automatisch genehmigt
`bypassPermissions`	Alle Berechtigungsprüfungen umgehen	Alle Tools werden ohne Berechtigungsaufforderungen ausgeführt (mit Vorsicht verwenden)
`plan`	Planungsmodus	Schreibgeschützte Tools werden ausgeführt; Claude analysiert und plant, ohne Ihre Quelldateien zu bearbeiten
`auto` (nur TypeScript)	Modellklassifizierte Genehmigungen	Ein Modellklassifizierer genehmigt oder lehnt jeden Tool-Aufruf ab. Siehe Auto-Modus für Verfügbarkeit

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 ohne Genehmigungsaufforderungen.

Berechtigungsmodus setzen

Sie können den Berechtigungsmodus einmal beim Starten einer Abfrage setzen oder ihn dynamisch ändern, während die Sitzung aktiv ist.

Zur Abfragezeit
Während des Streaming

Ü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())

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())

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. 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.

Plan-Modus (`plan`)

Beschränkt Claude auf schreibgeschützte Tools. Claude kann Dateien lesen und schreibgeschützte Shell-Befehle ausführen, um die Codebasis zu erkunden, bearbeitet aber nicht Ihre Quelldateien. 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.

​Wie Berechtigungen ausgewertet werden

​Allow- und Deny-Regeln

​Berechtigungsmodi

​Verfügbare Modi

​Berechtigungsmodus setzen

​Modusdetails

​Accept Edits-Modus (acceptEdits)

​Don’t Ask-Modus (dontAsk)

​Bypass Permissions-Modus (bypassPermissions)

​Plan-Modus (plan)

​Verwandte Ressourcen

Wie Berechtigungen ausgewertet werden

Allow- und Deny-Regeln

Berechtigungsmodi

Verfügbare Modi

Berechtigungsmodus setzen

Modusdetails

Accept Edits-Modus (`acceptEdits`)

Don’t Ask-Modus (`dontAsk`)

Bypass Permissions-Modus (`bypassPermissions`)

Plan-Modus (`plan`)

Verwandte Ressourcen