{/* TRANSLATED — 已翻译为中文 */} > ## 文档索引 > 在此获取完整文档索引：https://code.claude.com/docs/llms.txt > 使用此文件发现所有可用页面，然后再进一步探索。 # 配置权限 > 使用权限模式、钩子和声明式允许/拒绝规则控制智能体如何使用工具。 Claude Agent SDK 提供权限控制来管理 Claude 如何使用工具。使用权限模式和规则定义自动允许的内容，使用 [`canUseTool` 回调](/en/agent-sdk/user-input)在运行时处理其他所有内容。 本页介绍权限模式和规则。要构建用户在运行时批准或拒绝工具请求的交互式审批流程，请参阅[处理审批和用户输入](/en/agent-sdk/user-input)。 ## 权限评估方式 当 Claude 请求工具时，SDK 按以下顺序检查权限： 首先运行[钩子](/en/agent-sdk/hooks)。钩子可以完全拒绝调用或传递它。返回 `allow` 的钩子不会跳过下面的拒绝和询问规则；无论钩子结果如何都会评估这些规则。 检查 `deny` 规则（来自 `disallowed_tools` 和 [settings.json](/en/settings#permission-settings)）。如果拒绝规则匹配，即使在 `bypassPermissions` 模式下工具也会被阻止。裸名称拒绝规则（如 `Bash`）会在此评估开始之前从 Claude 的上下文中移除工具，因此只有范围规则（如 `Bash(rm *)`）在此步骤检查。 应用活动的[权限模式](#permission-modes)。`bypassPermissions` 批准到达此步骤的所有内容。`acceptEdits` 批准文件操作。其他模式继续传递。 检查 `allow` 规则（来自 `allowed_tools` 和 settings.json）。如果规则匹配，工具被批准。 如果上述任何步骤都未解决，则调用您的 [`canUseTool` 回调](/en/agent-sdk/user-input)进行决策。在 `dontAsk` 模式下，此步骤被跳过，工具被拒绝。 权限评估流程图 本页重点介绍**允许和拒绝规则**以及**权限模式**。对于其他步骤： * **钩子：** 运行自定义代码以允许、拒绝或修改工具请求。请参阅[使用钩子控制执行](/en/agent-sdk/hooks)。 * **canUseTool 回调：** 在运行时提示用户进行审批。请参阅[处理审批和用户输入](/en/agent-sdk/user-input)。 ## 允许和拒绝规则 `allowed_tools` 和 `disallowed_tools`（TypeScript：`allowedTools` / `disallowedTools`）向上面评估流程中的允许和拒绝规则列表添加条目。允许规则仅影响审批：未列在 `allowed_tools` 中的工具仍然可用，并传递到权限模式。拒绝规则根据它们是命名工具还是限定工具内的模式而表现不同。 | 选项 | 效果 | | :---------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `allowed_tools=["Read", "Grep"]` | `Read` 和 `Grep` 被自动批准。未列出的工具仍然存在，传递到权限模式和 `canUseTool`。 | | `disallowed_tools=["Bash"]` | `Bash` 工具定义从请求中移除。Claude 看不到该工具且无法尝试。 | | `disallowed_tools=["Bash(rm *)"]` | `Bash` 仍然可用。匹配 `rm *` 的调用在每种权限模式下都被拒绝，包括 `bypassPermissions`。其他 `Bash` 调用传递到权限模式。 | 对于锁定的智能体，将 `allowedTools` 与 `permissionMode: "dontAsk"` 配对使用。列出的工具被批准；其他任何内容都被完全拒绝而不是提示： ```typescript theme={null} const options = { allowedTools: ["Read", "Glob", "Grep"], permissionMode: "dontAsk" }; ``` **`allowed_tools` 不约束 `bypassPermissions`。** `allowed_tools` 仅预批准您列出的工具。未列出的工具不被任何允许规则匹配，传递到权限模式，`bypassPermissions` 在那里批准它们。将 `allowed_tools=["Read"]` 与 `permission_mode="bypassPermissions"` 一起设置仍然批准每个工具，包括 `Bash`、`Write` 和 `Edit`。如果您需要 `bypassPermissions` 但想要阻止特定工具，请使用 `disallowed_tools`。 您还可以在 `.claude/settings.json` 中以声明方式配置允许、拒绝和询问规则。这些规则在启用 `project` 设置来源时读取，这是默认 `query()` 选项的行为。如果您显式设置 `setting_sources`（TypeScript：`settingSources`），请包含 `"project"` 以使其生效。有关规则语法，请参阅[权限设置](/en/settings#permission-settings)。 ## 权限模式 权限模式提供对 Claude 如何使用工具的全局控制。您可以在调用 `query()` 时设置权限模式，或在流式会话期间动态更改它。 ### 可用模式 SDK 支持以下权限模式： | 模式 | 描述 | 工具行为 | | :------------------------- | :-------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | | `default` | 标准权限行为 | 无自动批准；不匹配的工具触发您的 `canUseTool` 回调 | | `dontAsk` | 拒绝而不是提示 | 未被 `allowed_tools` 或规则预批准的任何内容都被拒绝；`canUseTool` 永远不会被调用 | | `acceptEdits` | 自动接受文件编辑 | 文件编辑和[文件系统操作](#accept-edits-mode-acceptEdits)（`mkdir`、`rm`、`mv` 等）自动批准 | | `bypassPermissions` | 绕过所有权限检查 | 所有工具无需权限提示即可运行（请谨慎使用） | | `plan` | 规划模式 | 只读工具运行；Claude 分析和规划而不编辑您的源文件 | | `auto`（仅 TypeScript） | 模型分类审批 | 模型分类器批准或拒绝每个工具调用。有关可用性，请参阅[自动模式](/en/permission-modes#eliminate-prompts-with-auto-mode) | **子智能体继承：** 当父级使用 `bypassPermissions`、`acceptEdits` 或 `auto` 时，所有子智能体继承该模式且无法按子智能体覆盖。子智能体可能具有不同的系统提示和比主智能体更少约束的行为，因此继承 `bypassPermissions` 会授予它们完全的自主系统访问权限，无需任何审批提示。 ### 设置权限模式 您可以在启动查询时设置一次权限模式，或在会话活动期间动态更改它。 创建查询时传递 `permission_mode`（Python）或 `permissionMode`（TypeScript）。此模式在会话期间适用，除非动态更改。 ```python Python theme={null} 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()) ``` ```typescript TypeScript theme={null} 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(); ``` 调用 `set_permission_mode()`（Python）或 `setPermissionMode()`（TypeScript）以在会话中途更改模式。新模式对所有后续工具请求立即生效。这让您可以从限制性开始，随着信任建立而放宽权限，例如在审查 Claude 的初始方法后切换到 `acceptEdits`。 ```python Python theme={null} 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()) ``` ```typescript TypeScript theme={null} 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(); ``` ### 模式详情 #### 接受编辑模式（`acceptEdits`） 自动批准文件操作，以便 Claude 可以无需提示即可编辑代码。其他工具（如非文件系统操作的 Bash 命令）仍需要正常权限。 **自动批准的操作：** * 文件编辑（Edit、Write 工具） * 文件系统命令：`mkdir`、`touch`、`rm`、`rmdir`、`mv`、`cp`、`sed` 两者都仅适用于工作目录或 `additionalDirectories` 内的路径。超出该范围的路径和对受保护路径的写入仍会提示。 **适用场景：** 您信任 Claude 的编辑并希望更快的迭代，例如在原型开发期间或在隔离目录中工作时。 #### 不询问模式（`dontAsk`） 将任何权限提示转换为拒绝。由 `allowed_tools`、`settings.json` 允许规则或钩子运行预批准的工具正常运行。其他一切都被拒绝，不调用 `canUseTool`。 **适用场景：** 您想要为无头智能体提供固定的、显式的工具表面，并倾向于硬拒绝而不是静默依赖 `canUseTool` 不存在。 #### 绕过权限模式（`bypassPermissions`） 自动批准所有工具使用，无需提示。钩子仍然执行，如果需要可以阻止操作。 请极其谨慎地使用。在此模式下 Claude 具有完全的系统访问权限。仅在您信任所有可能操作的受控环境中使用。 `allowed_tools` 不约束此模式。每个工具都被批准，不仅仅是您列出的那些。拒绝规则（`disallowed_tools`）、显式 `ask` 规则和钩子在模式检查之前评估，仍然可以阻止工具。 #### 计划模式（`plan`） 将 Claude 限制为只读工具。Claude 可以读取文件和运行只读 shell 命令来探索代码库，但不编辑您的源文件。Claude 可能使用 `AskUserQuestion` 在最终确定计划前澄清需求。有关处理这些提示，请参阅[处理审批和用户输入](/en/agent-sdk/user-input#handle-clarifying-questions)。 **适用场景：** 您希望 Claude 提出更改建议而不执行它们，例如在代码审查期间或需要在更改执行前进行审批时。 ## 相关资源 有关权限评估流程中的其他步骤： * [处理审批和用户输入](/en/agent-sdk/user-input)：交互式审批提示和澄清性问题 * [钩子指南](/en/agent-sdk/hooks)：在智能体生命周期的关键点运行自定义代码 * [权限规则](/en/settings#permission-settings)：`settings.json` 中的声明式允许/拒绝规则