Leitfäden

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.

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, überprüft das SDK die Berechtigungen in dieser Reihenfolge:

Hooks
Führen Sie Hooks zuerst aus, die zulassen, ablehnen oder zum nächsten Schritt übergehen können
Berechtigungsregeln
Überprüfen Sie Regeln, die in settings.json in dieser Reihenfolge definiert sind: deny Regeln zuerst (blockieren unabhängig von anderen Regeln), dann allow Regeln (zulassen, wenn übereinstimmend), dann ask Regeln (zur Genehmigung auffordern). Diese deklarativen Regeln ermöglichen es Ihnen, bestimmte Tools vorab zu genehmigen, zu blockieren oder eine Genehmigung zu verlangen, ohne Code zu schreiben.
Berechtigungsmodus
Wenden Sie den aktiven Berechtigungsmodus (bypassPermissions, acceptEdits, dontAsk, usw.) an
canUseTool Callback
Falls nicht durch Regeln oder Modi gelöst, rufen Sie Ihren canUseTool Callback für eine Entscheidung auf

Diese Seite konzentriert sich auf Berechtigungsmodi (Schritt 3), die statische Konfiguration, die das Standardverhalten steuert. Für die anderen Schritte:

Hooks: Führen Sie benutzerdefinierten Code aus, um Tool-Anfragen zuzulassen, abzulehnen oder zu ändern. Siehe Ausführung mit Hooks steuern.
Berechtigungsregeln: Konfigurieren Sie deklarative Allow/Deny-Regeln in settings.json. Siehe Berechtigungseinstellungen.
canUseTool Callback: Fordern Sie Benutzer zur Laufzeit zur Genehmigung auf. Siehe Genehmigungen und Benutzereingaben handhaben.

Berechtigungsmodi

Berechtigungsmodi bieten globale Kontrolle über die Tool-Nutzung durch Claude. Sie können den Berechtigungsmodus beim Aufrufen von query() festlegen oder ihn während Streaming-Sitzungen dynamisch ä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
`acceptEdits`	Dateibearbeitungen automatisch akzeptieren	Dateibearbeitungen und Dateisystemoperationen (`mkdir`, `rm`, `mv`, usw.) werden automatisch genehmigt
`bypassPermissions`	Alle Berechtigungsprüfungen umgehen	Alle Tools werden ohne Berechtigungsaufforderungen ausgeführt (mit Vorsicht verwenden)
`plan`	Planungsmodus	Keine Tool-Ausführung; Claude plant, ohne Änderungen vorzunehmen

Subagent-Vererbung: Bei Verwendung von bypassPermissions erben alle Subagents diesen Modus und er kann nicht überschrieben werden. Subagents können unterschiedliche Systemaufforderungen und weniger eingeschränktes Verhalten als Ihr Hauptagent haben. Das Aktivieren von bypassPermissions gewährt ihnen vollständigen, autonomen Systemzugriff ohne Genehmigungsaufforderungen.

Berechtigungsmodus festlegen

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

Modusdetails

Bearbeitungsmodus akzeptieren (`acceptEdits`)

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

Automatisch genehmigte Operationen:

Dateibearbeitungen (Edit-, Write-Tools)
Dateisystembefehle: mkdir, touch, rm, mv, cp

Verwenden Sie, wenn: Sie Claudes Bearbeitungen vertrauen und schnellere Iterationen wünschen, z. B. während der Prototypenerstellung oder beim Arbeiten in einem isolierten Verzeichnis.

Berechtigungen umgehen Modus (`bypassPermissions`)

Genehmigt alle Tool-Verwendungen automatisch ohne Aufforderungen. Hooks werden weiterhin ausgeführt und können Operationen 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 Operationen vertrauen.

Planungsmodus (`plan`)

Verhindert die Tool-Ausführung vollständig. Claude kann Code analysieren und Pläne erstellen, kann aber keine Änderungen vornehmen. 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 einer Code-Überprüfung oder wenn Sie Änderungen genehmigen müssen, bevor sie vorgenommen werden.

Berechtigungen konfigurieren

Kontrollieren Sie, wie Ihr Agent Tools mit Berechtigungsmodi, Hooks und deklarativen Allow/Deny-Regeln verwendet.

Wie Berechtigungen ausgewertet werden

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

Hooks
Führen Sie Hooks zuerst aus, die zulassen, ablehnen oder zum nächsten Schritt übergehen können
Berechtigungsregeln
Überprüfen Sie Regeln, die in settings.json in dieser Reihenfolge definiert sind: deny Regeln zuerst (blockieren unabhängig von anderen Regeln), dann allow Regeln (zulassen, wenn übereinstimmend), dann ask Regeln (zur Genehmigung auffordern). Diese deklarativen Regeln ermöglichen es Ihnen, bestimmte Tools vorab zu genehmigen, zu blockieren oder eine Genehmigung zu verlangen, ohne Code zu schreiben.
Berechtigungsmodus
Wenden Sie den aktiven Berechtigungsmodus (bypassPermissions, acceptEdits, dontAsk, usw.) an
canUseTool Callback
Falls nicht durch Regeln oder Modi gelöst, rufen Sie Ihren canUseTool Callback für eine Entscheidung auf

Diese Seite konzentriert sich auf Berechtigungsmodi (Schritt 3), die statische Konfiguration, die das Standardverhalten steuert. Für die anderen Schritte:

Hooks: Führen Sie benutzerdefinierten Code aus, um Tool-Anfragen zuzulassen, abzulehnen oder zu ändern. Siehe Ausführung mit Hooks steuern.
Berechtigungsregeln: Konfigurieren Sie deklarative Allow/Deny-Regeln in settings.json. Siehe Berechtigungseinstellungen.
canUseTool Callback: Fordern Sie Benutzer zur Laufzeit zur Genehmigung auf. Siehe Genehmigungen und Benutzereingaben handhaben.

Berechtigungsmodi

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
`acceptEdits`	Dateibearbeitungen automatisch akzeptieren	Dateibearbeitungen und Dateisystemoperationen (`mkdir`, `rm`, `mv`, usw.) werden automatisch genehmigt
`bypassPermissions`	Alle Berechtigungsprüfungen umgehen	Alle Tools werden ohne Berechtigungsaufforderungen ausgeführt (mit Vorsicht verwenden)
`plan`	Planungsmodus	Keine Tool-Ausführung; Claude plant, ohne Änderungen vorzunehmen

Berechtigungsmodus festlegen

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

Modusdetails

Bearbeitungsmodus akzeptieren (`acceptEdits`)

Automatisch genehmigte Operationen:

Dateibearbeitungen (Edit-, Write-Tools)
Dateisystembefehle: mkdir, touch, rm, mv, cp

Verwenden Sie, wenn: Sie Claudes Bearbeitungen vertrauen und schnellere Iterationen wünschen, z. B. während der Prototypenerstellung oder beim Arbeiten in einem isolierten Verzeichnis.

Berechtigungen umgehen Modus (`bypassPermissions`)

Genehmigt alle Tool-Verwendungen automatisch ohne Aufforderungen. Hooks werden weiterhin ausgeführt und können Operationen 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 Operationen vertrauen.

Berechtigungen konfigurieren

Wie Berechtigungen ausgewertet werden

Berechtigungsmodi

Verfügbare Modi

Berechtigungsmodus festlegen

Modusdetails

Bearbeitungsmodus akzeptieren (`acceptEdits`)

Berechtigungen umgehen Modus (`bypassPermissions`)

Planungsmodus (`plan`)

Verwandte Ressourcen

Berechtigungen konfigurieren

Wie Berechtigungen ausgewertet werden

Berechtigungsmodi

Verfügbare Modi

Berechtigungsmodus festlegen

Modusdetails

Bearbeitungsmodus akzeptieren (`acceptEdits`)

Berechtigungen umgehen Modus (`bypassPermissions`)

Planungsmodus (`plan`)

Verwandte Ressourcen

Wie Berechtigungen ausgewertet werden

Berechtigungsmodi

Verfügbare Modi

Berechtigungsmodus festlegen

Modusdetails

Bearbeitungsmodus akzeptieren (acceptEdits)

Berechtigungen umgehen Modus (bypassPermissions)

Planungsmodus (plan)

Verwandte Ressourcen

Wie Berechtigungen ausgewertet werden

Berechtigungsmodi

Verfügbare Modi

Berechtigungsmodus festlegen

Modusdetails

Bearbeitungsmodus akzeptieren (acceptEdits)

Berechtigungen umgehen Modus (bypassPermissions)

Planungsmodus (plan)

Verwandte Ressourcen

Bearbeitungsmodus akzeptieren (`acceptEdits`)

Berechtigungen umgehen Modus (`bypassPermissions`)

Planungsmodus (`plan`)

Bearbeitungsmodus akzeptieren (`acceptEdits`)

Berechtigungen umgehen Modus (`bypassPermissions`)

Planungsmodus (`plan`)