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:

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.

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"
};

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:

Berechtigungsmodus setzen

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

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

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

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.

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