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 automatisch zu definieren, was zulässig ist, und den canUseTool-Callback, um alles andere zur Laufzeit zu handhaben.

Wie Berechtigungen ausgewertet werden

[!NOTE]

Wenn Sie ein Plugin laden, das einen Mod enthält, erfahren Sie unter wo sich die Entscheidungen eines Mods zwischen Regeln und Hooks einordnen mehr.

Wenn Claude ein Tool anfordert, prüft Claude Code den Aufruf in diesen Schritten. Jeder Schritt kann über den Aufruf entscheiden, ihn an Ihren canUseTool Callback senden oder ihn weitergeben:

1. Hooks

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

Ein PreToolUse-Hook, der allow zurückgibt, kann außerdem keinen rm- oder rmdir-Befehl genehmigen, dessen Ziel Claude Code als kritischen Pfad erkennt, etwa rm -rf ~. Was dieses allow im Plan-Modus bewirkt, erfahren Sie unter Hook-Genehmigungen im Plan-Modus.

2. Deny-Regeln

Wenn eine Deny-Regel aus disallowed_tools oder aus einer Einstellungsdatei, die das SDK lädt, zutrifft, wird der Aufruf abgelehnt und canUseTool wird nicht aufgerufen. Der Aufruf wird auf diese Weise selbst im bypassPermissions Modus abgelehnt und auch dann, wenn ein Hook allow zurückgegeben hat.

Wenn Sie im TypeScript SDK die permission_policy eines benutzerdefinierten Tools auf always_deny setzen, wird ein Aufruf dieses Tools in diesem Schritt abgelehnt.

3. Ask-Regeln

Prüfen Sie ask Regeln aus settings.json. Wenn eine Ask-Regel zutrifft, fällt der Aufruf in Ihren canUseTool Callback zur Bestätigung, 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 in den Callback, auch wenn eine Allow-Regel zutrifft. Im dontAsk Modus werden beide Fälle stattdessen abgelehnt, da dieser Modus jede Berechtigungsabfrage in eine Ablehnung umwandelt. 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 in den Callback, 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 auffordert.

Wenn Sie im TypeScript SDK die permission_policy eines benutzerdefinierten Tools auf always_ask setzen, genehmigt keine Allow-Regel dessen Aufrufe, nicht einmal ein allowedTools-Eintrag. Im dontAsk Modus lehnt Claude Code diese Aufrufe ab, und im auto, plan oder bypassPermissions Modus kann es sie genehmigen, bevor Ihr Callback ausgeführt wird.

4. Berechtigungsmodus

Wenden Sie den aktiven Berechtigungsmodus an:

• Im bypassPermissions Modus genehmigt Claude Code jeden Aufruf, der diesen Schritt erreicht, es sei denn, es handelt sich um eine der Aktionen, die kein Modus automatisch genehmigt. Welche dieser Aktionen an Ihren canUseTool Callback gehen, erfahren Sie unter Bypass permissions mode.
• Im acceptEdits Modus genehmigt Claude Code die unter Accept edits mode aufgelisteten Dateivorgänge.
• Im plan Modus erreichen einige Aufrufe Ihren Callback, und wenn der Auto-Modus verfügbar ist, gehen andere stattdessen an dessen Klassifikator. Weitere Informationen finden Sie unter Plan mode.
• Im default und dontAsk Modus geht der Aufruf weiter zu den Allow-Regeln.
• Zum auto Modus siehe Auto mode.

5. 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 aufgelöst, ohne dass eine Regel erforderlich ist: zum Beispiel ein Dateilesezugriff in Ihren Arbeitsverzeichnissen oder ein nur lesender Bash-Befehl.

Erkannte Entfernungen kritischer Pfade werden nicht durch eine Allow-Regel genehmigt, und mit Dangerous rm operation not ruled out markierte Befehle werden nicht durch eine Bash- oder Bash(*)-Regel genehmigt. Ob sie dann Ihren Callback erreichen, hängt vom Berechtigungsmodus ab: in einer Agent SDK Sitzung im auto Modus lehnt Claude Code sie beispielsweise standardmäßig ab, ohne ihn aufzurufen. Die Modustabelle für kritische Pfade listet auf, was jeder Modus mit ihnen tut.

Eine Allow-Regel genehmigt keinen Lesezugriff auf einen Netzwerkpfad.

6. canUseTool Callback

Wenn kein vorheriger Schritt die Anfrage auflöst, rufen Sie Ihren canUseTool Callback zur Entscheidung auf. Im dontAsk Modus wird dieser Schritt übersprungen und das Tool wird abgelehnt, wobei ein von Ihnen installierter Mod einige solcher Aufrufe dennoch genehmigen kann.

Im TypeScript SDK, wenn Sie permissionPrompts: 'none' setzen, wird Ihr Callback in diesem Schritt nicht aufgerufen. 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, wenn die Abfrage konstruiert wird. Der Code der Warnung ist CLAUDE_SDK_CAN_USE_TOOL_SHADOWED. Zwei Konfigurationen lösen sie aus:

• permissionMode: 'bypassPermissions': Der Warnungstext beginnt mit canUseTool will not be invoked: permissionMode 'bypassPermissions'. Tool-Aufrufe werden genehmigt, bevor canUseTool konsultiert wird, sodass Ihr Callback nur für wenige Aufrufe ausgeführt wird, etwa für die unter Bypass permissions mode aufgeführten Aufrufe. Um auch die genehmigten Aufrufe zu prüfen, verlagern Sie die Prüfungen Ihres Callbacks in einen PreToolUse Hook
• Ein allowedTools-Eintrag, der nur aus einem Tool-Namen besteht, etwa "Read": Die Warnung listet jeden solchen Eintrag nach canUseTool will not be invoked for: auf. Aufrufe eines aufgeführten Tools werden genehmigt, bevor canUseTool konsultiert wird, abgesehen von den Aufrufen, die eine Allow-Regel nie genehmigt. Damit Ihr Callback für Aufrufe eines aufgeführten Tools ausgeführt wird, die eine Genehmigung benötigen, entfernen Sie den Eintrag dieses Tools aus allowedTools

Einträge mit einem Spezifizierer wie Bash(ls *) und der acceptEdits Modus lösen es nicht aus, und Allow-Regeln aus Einstellungsdateien sind für die Prüfung nicht sichtbar.

Die Warnung blockiert keinen Aufruf und ändert keine Option. Wenn Ihr Callback bereits jeden Aufruf erhält, den Sie prüfen möchten, lassen Sie Ihre Konfiguration unverändert. Um die Warnung zu protokollieren, hören Sie mit process.on('warning', ...) zu und gleichen Sie den Code CLAUDE_SDK_CAN_USE_TOOL_SHADOWED ab.

Diese Seite konzentriert sich auf Allow- und Deny-Regeln und Berechtigungsmodi. Für die anderen Schritte:

• Hooks: Führen Sie benutzerdefinierten Code aus, um Tool-Anfragen zu erlauben, zu verweigern 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 auflöst. Siehe Genehmigungen und Benutzereingaben verarbeiten.

Allow- und Deny-Regeln

Wenn Sie allowedTools und disallowedTools (TypeScript) oder allowed_tools und disallowed_tools (Python) setzen, fügt Claude Code deren Einträge zu den Allow- und Deny-Regellisten im Ablauf der Berechtigungsauswertung hinzu. Jedes andere Tool, das nicht in allowed_tools aufgelistet ist, ist weiterhin für Claude verfügbar, und ein Aufruf, der Genehmigung benötigt, fällt durch zum Berechtigungsmodus.

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 unverankerter Eintrag wie allowed_tools=["*"] oder allowed_tools=["mcp__*"] wird ignoriert und genehmigt nichts automatisch.

[!WARNING]

Automatisch genehmigte Tools erreichen canUseTool niemals. Ein Tool-Aufruf, der in einem früheren Schritt genehmigt wird, durch acceptEdits oder bypassPermissions oder durch eine Allow-Regel, überspringt Ihren canUseTool-Callback, daher werden Berechtigungsprüfungen, die Sie dort durchführen, für dieses Tool stillschweigend umgangen.

Wenn Aufrufe eines Tools in allowed_tools dennoch Ihren canUseTool-Callback erreichen oder im dontAsk-Modus abgelehnt werden, prüfen Sie, ob es sich um Lesezugriffe auf Netzwerkpfade oder um einen der folgenden Aufrufe handelt. Keine Allow-Regel genehmigt diese Aufrufe. Im dontAsk-Modus, der nie nachfragt, lehnt Claude Code sie ab, ohne canUseTool aufzurufen, und in den anderen Berechtigungsmodi behandeln Sie sie so, wie es der jeweilige Punkt beschreibt:

• AskUserQuestion, MCP-Tools, die mit _meta["anthropic/requiresUserInteraction"] gekennzeichnet sind, und Konnektor-Tools, die Ihre Organisation auf ask gesetzt hat: Beantworten Sie sie im Callback. Rückfragen behandeln zeigt, wie Sie AskUserQuestion beantworten, und ein Konnektor-Aufruf kommt mit dem Grund Your organization requires approval for this tool an

• Benutzerdefinierte Tools, die Ihre Anwendung mit always_ask kennzeichnet: Entscheiden Sie über den Aufruf im Callback. Damit diese Aufrufe nicht mehr ankommen, ändern Sie die Richtlinie während der Sitzung. In den Modi auto, plan und bypassPermissions kann der Aufruf stattdessen vor dem Callback genehmigt werden, und zwar in den Fällen, die unter Berechtigungsmodi, die einen always_ask-Aufruf genehmigen können aufgeführt sind

• Erkannte rm- und rmdir-Entfernungen kritischer Pfade: Im Modus default, acceptEdits und bypassPermissions erlauben oder verweigern Sie die Entfernung im Callback, wobei decisionReason mit Dangerous rm beginnt. Für die Modi auto und plan siehe Entfernungen kritischer Pfade in jedem Berechtigungsmodus

• Bloßer Name: Ein Eintrag wie Read oder mcp__github__get_issue genehmigt automatisch jeden Aufruf dieses Tools, abgesehen von den Aktionen, die kein Modus automatisch genehmigt, und Lesezugriffen auf Netzwerkpfade.

• Begrenzte Regel: Ein Eintrag wie Bash(npm test *) genehmigt übereinstimmende Aufrufe automatisch, und andere Bash-Aufrufe, die Genehmigung benötigen, fallen durch zum Berechtigungsmodus.

Um Aufrufe zu prüfen, die eine Allow-Regel, acceptEdits oder bypassPermissions genehmigt, verwenden Sie einen PreToolUse-Hook, der auch für diese Aufrufe ausgeführt wird. Eine Hook-Ablehnung gilt auch im bypassPermissions-Modus.

Für einen abgesperrten Agent kombinieren Sie allowedTools mit permissionMode: "dontAsk":

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

Die aufgelisteten Read-, Glob- und Grep-Aufrufe werden genehmigt, außer den Aktionen, die kein Modus automatisch genehmigt, und Lesezugriffen auf Netzwerkpfade. Jeder andere Aufruf, der sonst eine Berechtigungsabfrage auslösen würde, wird stattdessen abgelehnt, wobei ein von Ihnen installierter Mod einige dieser Aufrufe dennoch genehmigen kann.

Aufrufe, die im default-Modus keine Genehmigung benötigen, werden ausgeführt, unabhängig davon, ob Sie sie aufgelistet haben oder nicht. Dazu gehören nur lesende Bash-Befehle, Tools wie Agent, die vor dem Ausführen nicht fragen, und Dateilesevorgänge in Ihren Arbeitsverzeichnissen. Um ein integriertes Tool vollständig vor Claude zu verbergen, statt seine Aufrufe abzulehnen, fügen Sie seinen bloßen Namen zu disallowedTools hinzu.

[!WARNING]

allowed_tools schränkt bypassPermissions nicht ein. allowed_tools genehmigt die Tools, die Sie aufgelistet haben, im Voraus. Im bypassPermissions-Modus genehmigt Claude Code einen Aufruf eines nicht aufgelisteten Tools, es sei denn, es handelt sich um eine der Aktionen, die kein Modus automatisch genehmigt.

Wenn Sie allowed_tools=["Read"] zusammen mit permission_mode="bypassPermissions" setzen, genehmigt Claude Code dennoch Aufrufe von Tools wie Bash, Write und Edit. Wenn Sie bypassPermissions benötigen, aber bestimmte Tools blockiert haben möchten, verwenden Sie disallowed_tools. Für die Aufrufe, die in diesem Modus dennoch Ihren canUseTool-Callback erreichen, siehe Modus zum Umgehen von Berechtigungen.

Sie können auch Allow-, Deny- und Ask-Regeln 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, schließen Sie "project" ein, damit sie angewendet werden. Siehe Berechtigungseinstellungen für die Regelsyntax.

Wann Allow-Regeln in der .claude/settings.json eines Projekts gelten, erfahren Sie unter Projekt-Allow-Regeln und Workspace-Vertrauen.

Pfadmuster in Regeln

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. Schreiben Sie eine Pfadregel für jedes dieser Tools daher als Edit(path). Wenn Sie eine Pfadregel als Write(path) oder NotebookEdit(path) schreiben, entspricht sie keinem Aufruf und hat keine Wirkung.

Beginnen Sie in allowed_tools und disallowed_tools ein Pfadmuster mit // für einen absoluten Pfad oder mit einem einzelnen / für einen Pfad innerhalb des Arbeitsverzeichnisses der Sitzung:

• //path: Mit einer Deny-Regel von Edit(//secrets/**) blockiert Claude Code Schreibvorgänge unter /secrets auf der Festplatte durch Claudes Datei-Tools und durch Bash-Befehle wie tee und > file-Umleitung. Ein Skript, das Claude ausführt und das selbst Dateien öffnet, kann weiterhin unter /secrets schreiben. Für eine Durchsetzung durch das Betriebssystem siehe Das Bash-Tool in der Sandbox konfigurieren.
• /path: Edit(/secrets/**) entspricht dem Verzeichnis secrets innerhalb des Arbeitsverzeichnisses.

Weitere Möglichkeiten, ein Pfadmuster zu beginnen, finden Sie unter Read- und Edit-Regeln.

Berechtigungsmodi

Berechtigungsmodi bieten globale Kontrolle darüber, wie Claude Tools nutzt. Sie können den Berechtigungsmodus beim Aufrufen von query() festlegen oder ihn während Streaming-Sitzungen dynamisch ändern.

Ab Claude Code v2.1.302 startet Ihre App im default-Modus, sofern Sie keinen Berechtigungsmodus festlegen und sie keinen aus permissions.defaultMode in ihren Einstellungsdateien erhält. Im default-Modus lehnt Claude Code jeden Tool-Aufruf ab, der eine Genehmigung benötigt, es sei denn, Sie genehmigen ihn über eine Allow-Regel, einen Hook, einen canUseTool-Callback oder ein Berechtigungsabfrage-Tool. Wenn Tool-Aufrufe abgelehnt werden, siehe Tool-Aufrufe in claude -p- und Agent SDK-Ausführungen abgelehnt.

Verfügbare Modi

Das SDK unterstützt diese Berechtigungsmodi:

[!WARNING]

Subagent-Vererbung: Wenn sich Ihre Hauptsitzung im Plan-Modus befindet, wird ein Subagent, dessen AgentDefinition permissionMode: "acceptEdits" festlegt, dennoch im Plan-Modus ausgeführt. Die Edit- und Write-Aufrufe dieses Subagenten auf Ihre Quelldateien gehen weiterhin an Ihren canUseTool-Callback. Der Plan-Modus gilt auch für die von Ihnen definierten Subagenten, sodass das Übergeben von Arbeit an einen Subagenten die vorherige Überprüfung des Plans nicht umgeht.

Der Subagent erbt plan, acceptEdits, auto oder bypassPermissions von der Hauptsitzung, und unter einer Hauptsitzung im default- oder dontAsk-Modus wird er in dem von Ihnen festgelegten Modus ausgeführt. Auch dann wendet Claude Code nie einen "bypassPermissions"-Wert an und wendet einen "auto"-Wert nur dann an, wenn der Auto-Modus für diesen Subagenten verfügbar ist. Die bypassPermissions-Ausnahme erfordert Claude Code v2.1.267 oder später.

Subagents können unterschiedliche Systemaufforderungen und weniger eingeschränktes Verhalten als Ihr Hauptagent haben, daher gewährt die Vererbung von bypassPermissions ihnen vollständigen, autonomen Systemzugriff. Die Aktionen, die kein Modus automatisch genehmigt, gelten weiterhin.

Berechtigungsmodus festlegen

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

[tab] Zum Abfragezeitpunkt

Übergeben Sie permission_mode (Python) oder permissionMode (TypeScript) beim Erstellen einer Abfrage.

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

[tab] Während des Streaming

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 die Berechtigungen zu lockern, wenn Vertrauen aufgebaut wird, z. B. durch 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

Bearbeitungsmodus akzeptieren (acceptEdits)

Genehmigt Dateivorgänge automatisch, damit Claude Code bearbeiten kann, ohne zu fragen. Andere Tools (wie Bash-Befehle, die keine Dateisystemvorgänge sind) erfordern weiterhin normale Berechtigungen.

Automatisch genehmigte Vorgänge:

• Dateibearbeitungen mit den Tools Edit, Write und NotebookEdit
• Dateisystembefehle: mkdir, touch, rm, rmdir, mv, cp, sed

Beide gelten für Pfade innerhalb des Arbeitsverzeichnisses oder eines von Ihnen hinzugefügten Verzeichnisses. In Python fügen Sie eines mit add_dirs hinzu, in TypeScript mit 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 Pfad, den Claude Code als kritischen Pfad erkennt, mit rm oder rmdir löscht
• touch beispielsweise mit einer Option, einem Glob oder einem Präfix wie timeout 5 oder LANG=C ausführt

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.

Nicht-Fragen-Modus (dontAsk)

Konvertiert jede Berechtigungsabfrage in eine Ablehnung, ohne canUseTool aufzurufen, wobei ein von Ihnen installierter Mod einige dieser Aufrufe dennoch genehmigen kann. Tools, die von allowed_tools, settings.json-Allow-Regeln oder einem Hook vorab genehmigt wurden, werden normal ausgeführt. Aufrufe, die im default-Modus keine Genehmigung benötigen, werden ebenfalls ausgeführt, wie Dateilesevorgänge in Ihren Arbeitsverzeichnissen und Aufrufe an Agent.

Diese Aufrufe werden abgelehnt, auch wenn eine Allow-Regel übereinstimmt:

• Konnektor-Tools, die Ihre Organisation auf ask gesetzt hat
• Tools, die Benutzerinteraktion erfordern, wie AskUserQuestion und MCP-Tools, deren Server _meta["anthropic/requiresUserInteraction"] setzt
• Benutzerdefinierte Tools, deren permission_policy Ihre Anwendung auf always_ask setzt
• Lesezugriffe auf Netzwerkpfade
• Erkannte Löschungen kritischer Pfade

Wenn Ihr PreToolUse-Hook allow für eine erkannte Löschung eines kritischen Pfads, einen Lesezugriff auf einen Netzwerkpfad oder einen Aufruf eines als always_ask gekennzeichneten Tools zurückgibt, wird der Aufruf dennoch abgelehnt. Die Prüfung, die diese Löschungen erkennt, kann einige Befehle übersehen.

Verwenden Sie, wenn: Sie einen Headless-Agenten ausführen und für jeden Aufruf, der sonst eine Nachfrage auslösen würde, eine harte Ablehnung wünschen.

Berechtigungen umgehen-Modus (bypassPermissions)

Genehmigt Tool-Nutzungen automatisch ohne Nachfrage, außer bei den Aktionen, die kein Modus automatisch genehmigt. Hooks werden weiterhin ausgeführt und können Vorgänge bei Bedarf blockieren. Auf Linux und macOS weigert sich Claude Code, in diesem Modus als Root oder unter sudo außerhalb einer erkannten Sandbox zu starten, und die Abfrage schlägt vor dem ersten Turn fehl.

[!WARNING]

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, und auch Aufrufe von Tools, die Sie nicht aufgelistet haben, werden genehmigt. Diese Kontrollen gelten weiterhin:

• Deny-Regeln, explizite ask-Regeln und Hooks werden vor der Modusüberprüfung ausgewertet und können ein Tool weiterhin blockieren.
• Konnektor-Tools, die Ihre Organisation auf ask gesetzt hat, Tools, die Benutzerinteraktion erfordern, erkannte Löschungen kritischer Pfade und Bash-Befehle, die mit Dangerous rm operation not ruled out markiert sind, fallen weiterhin in Ihren canUseTool-Callback. Die Prüfung, die Löschungen kritischer Pfade erkennt, kann einige Befehle übersehen, und Sie können die Abfrage bei Löschungen kritischer Pfade ausschalten. Außerhalb einer Cloud-Sitzung fallen auch Aufrufe benutzerdefinierter Tools, die Ihre Anwendung als always_ask kennzeichnet, in den Callback.
• Die Sitzungsübergreifenden Messaging-Schutzmaßnahmen gelten weiterhin.

Planungsmodus (plan)

Claude erkundet die Codebasis und erstellt einen Plan. Während der Planung erreichen Bearbeitungen mit Claudes Datei-Tools außerhalb geschützter Pfade Ihren canUseTool-Callback, auch wenn eine Allow-Regel übereinstimmt oder ein PreToolUse-Hook allow zurückgibt. AskUserQuestion-Aufrufe erreichen ebenfalls Ihren Callback, auch wenn eine Allow-Regel das Tool nennt.

Wenn der Auto-Modus verfügbar ist, sendet Claude Code diese Aufrufe während der Planung zur Überprüfung an den Klassifikator des Auto-Modus statt an Ihren Callback, sofern keine Allow-Regel sie genehmigt:

• Shell-Befehle
• Web-Abrufe
• Websuchen
• Aufrufe von MCP-Tools, die ihr Server als nur lesend kennzeichnet

Diese Überprüfung ist standardmäßig aktiviert. Um sie auszuschalten, setzen Sie useAutoModeDuringPlan in der settings-Option, die Sie an query() übergeben, oder in Ihren Benutzereinstellungen auf false. Solange die Überprüfung ausgeschaltet ist, erreichen Websuchen und Aufrufe von als nur lesend gekennzeichneten MCP-Tools Ihren Callback.

Für Shell-Befehle und Web-Abrufe zeigt die Tabelle, ob der jeweilige Aufruf Ihren Callback erreicht:

Was passiert, nachdem der Klassifikator mehrere Aufrufe hintereinander abgelehnt hat, erfahren Sie unter Schwellenwerte für wiederholte Blockierungen.

[!NOTE]

Wenn Sie im TypeScript SDK allowDangerouslySkipPermissions: true zusammen mit permissionMode: 'plan' festlegen, erreichen Dateibearbeitungen weiterhin Ihren canUseTool-Callback. Um eine Sitzung, die im Plan-Modus startet, später mit setPermissionMode() auf bypassPermissions umzustellen, muss allowDangerouslySkipPermissions von Anfang an gesetzt sein.

Verwenden Sie, wenn: Claude zuerst einen Plan erstellen soll, z. B. während eines Code-Reviews oder vor einer großen Änderung.

Auto-Modus (auto)

Ein Klassifikatormodell überprüft Aktionen wie Shell-Befehle und Netzwerkanfragen, bevor sie ausgeführt werden, und erlaubt oder blockiert jede überprüfte Aktion. Welche Modelle und Anbieter der Auto-Modus voraussetzt und in welcher Reihenfolge er Aktionen bewertet, erfahren Sie unter Berechtigungsabfragen mit dem Auto-Modus vermeiden.

Wenn Sie eine Sitzung im Auto-Modus mit set_model(), setModel() oder applyFlagSettings() auf ein Modell umstellen, das der Auto-Modus nicht unterstützt, wechselt die Sitzung in den default-Modus:

• Was Sie sehen: eine system-Nachricht mit dem Subtyp status und permissionMode auf "default" gesetzt, die das TypeScript SDK als SDKStatusMessage typisiert. Ab diesem Zeitpunkt erreichen Aufrufe, die eine Genehmigung benötigen und keine Allow-Regel erfüllen, Ihren canUseTool-Callback.
• Zurück zum Auto-Modus: Wechseln Sie zu einem unterstützten Modell und rufen Sie dann set_permission_mode("auto") oder setPermissionMode("auto") auf. Wenn Sie das Modell zurückwechseln, ohne diesen Aufruf auszuführen, bleibt die Sitzung im default-Modus. Solange das nicht unterstützte Modell aktiv ist, schlägt der Aufruf mit Cannot set permission mode to auto: auto mode unavailable for this model fehl.

Der Wechsel in den default-Modus nach einem Aufruf von set_model(), setModel() oder applyFlagSettings() erfordert Claude Code v2.1.299 oder später.

Verwandte Ressourcen

Für die anderen Schritte im Genehmigungsbewertungsfluss:

• Genehmigungen und Benutzereingaben verarbeiten: interaktive Genehmigungsaufforderungen und Klärungsfragen
• Hooks-Anleitung: Ausführung von benutzerdefiniertem Code an wichtigen Punkten im Agent-Lebenszyklus
• Berechtigungsregeln: deklarative Allow/Deny-Regeln in settings.json