配置权限

使用权限模式、hooks 和声明式允许/拒绝规则来控制您的代理如何使用工具。

Claude Agent SDK 提供权限控制来管理 Claude 如何使用工具。使用权限模式和规则来定义自动允许的内容，以及使用 canUseTool 回调 在运行时处理其他所有情况。

权限如何被评估

当 Claude 请求一个工具时，SDK 按以下顺序检查权限：

1. Hooks

   首先运行 hooks。一个 hook 可以直接拒绝调用或将其传递下去。返回 allow 的 hook 不会跳过下面的拒绝和询问规则；无论 hook 结果如何，这些规则都会被评估。

2. 拒绝规则

   检查 deny 规则（来自 disallowed_tools 和 settings.json）。如果拒绝规则匹配，工具被阻止，即使在 bypassPermissions 模式下也是如此。裸名称拒绝规则（如 Bash）在此评估开始之前将工具从 Claude 的上下文中移除，因此只有作用域规则（如 Bash(rm *)）在此步骤中被检查。

3. 询问规则

   检查来自 settings.json 的 ask 规则。如果询问规则匹配，调用会传递到您的 canUseTool 回调 以获得确认，即使在 bypassPermissions 模式下也是如此。

   需要用户交互的工具行为相同：`AskUserQuestion` 和 MCP 工具，其服务器设置 [`_meta["anthropic/requiresUserInteraction"]`](/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 总是传递到回调，即使当允许规则匹配时。在 `dontAsk` 模式下，两种情况都被拒绝，因为该模式从不提示。MCP 注解需要 Claude Code v2.1.199 或更高版本。
   
   [claude.ai connector](/docs/zh-CN/mcp#organization-controls-on-connector-tools) 工具，您的组织已设置为 `ask` 也会在此步骤离开流程。每个调用都会传递到回调，即使在 `bypassPermissions` 模式下，即使当允许规则匹配时。回调接收原因 `Your organization requires approval for this tool`。在 `dontAsk` 模式下，调用被拒绝，因为该模式从不提示。
   

4. 权限模式

   应用活跃的 权限模式。bypassPermissions 批准到达此步骤的所有内容。acceptEdits 批准文件操作。plan 将文件编辑和 shell 写入工具路由到您的 canUseTool 回调，无论允许规则如何，因此在规划时写入操作无法自动批准。其他模式会继续进行。

5. 允许规则

   检查 allow 规则（来自 allowed_tools 和 settings.json）。如果规则匹配，工具被批准。

6. canUseTool 回调

   如果上述任何步骤都未解决，调用您的 canUseTool 回调 以获得决定。在 dontAsk 模式下，此步骤被跳过，工具被拒绝。

从 v2.1.198 开始，如果您传递一个 canUseTool 回调，该评估顺序永远无法到达，TypeScript SDK 在构造查询时会发出一次 Node.js 进程警告。警告的代码是 CLAUDE_SDK_CAN_USE_TOOL_SHADOWED。两种配置会触发它：

• permissionMode: 'bypassPermissions'，它自动批准到达权限模式步骤的每个调用
• 每个裸 allowedTools 条目，如 "Read"，它在咨询回调之前自动批准整个工具

带有说明符的条目（如 Bash(ls *)）和 acceptEdits 模式不会触发它，来自设置文件的允许规则对检查不可见。

使用 process.on('warning', ...) 监听并匹配代码以记录或抑制它。要无论模式和规则如何都控制每个工具调用，请改用 PreToolUse hook。

本页面重点关注 允许和拒绝规则 以及 权限模式。对于其他步骤：

• Hooks： 运行自定义代码以允许、拒绝或修改工具请求。请参阅 使用 hooks 控制执行。
• canUseTool 回调： 在运行时提示用户批准，当没有更早的步骤解决调用时。请参阅 处理批准和用户输入。

允许和拒绝规则

allowed_tools 和 disallowed_tools（TypeScript：allowedTools / disallowedTools）向上面评估流程中的允许和拒绝规则列表添加条目。允许规则仅影响批准：未在 allowed_tools 中列出的工具仍然可供 Claude 使用，并继续进行权限模式。拒绝规则的行为取决于它们是命名工具还是在工具内范围化模式。

允许规则仅在字面 mcp__<server>__ 前缀之后接受工具名称通配符。服务器段必须无通配符，以便规则命名您配置的特定服务器：mcp__puppeteer__* 匹配来自 puppeteer 服务器的每个工具，mcp__github__get_* 匹配其 get_ 工具。未锚定的条目如 allowed_tools=["*"] 或 allowed_tools=["mcp__*"] 被忽略并显示启动警告，不会自动批准任何内容。

范围化规则用于 Read 和 Edit 采用路径模式。Edit(path) 规则管理所有写入文件的内置工具，包括 Write 和 NotebookEdit；Write(path) 规则永远不会被文件权限检查匹配。

使用 //path 表示绝对文件系统路径：Edit(//secrets/**) 的拒绝规则阻止在磁盘上 /secrets 下任何位置的写入。使用单个前导斜杠，Edit(/secrets/**) 在规则的源处锚定。对于通过 allowed_tools 或 disallowed_tools 传递的规则，这意味着会话的工作目录，因此规则不会阻止磁盘上的 /secrets。请参阅 Read 和 Edit 规则 了解四种锚定形式以及来自设置文件的规则如何解析。

对于锁定的代理，将 allowedTools 与 permissionMode: "dontAsk" 配对。列出的工具被批准，除了上面警告中的始终提示工具；其他任何内容都被直接拒绝，而不是提示：

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

您也可以在 .claude/settings.json 中声明式地配置允许、拒绝和询问规则。当启用 project 设置源时，这些规则被读取，默认 query() 选项就是这样。如果您显式设置 setting_sources（TypeScript：settingSources），请包含 "project" 以使其应用。请参阅 权限设置 了解规则语法。

权限模式

权限模式提供对 Claude 如何使用工具的全局控制。您可以在调用 query() 时设置权限模式，或在流式会话期间动态更改它。

可用模式

SDK 支持这些权限模式：

设置权限模式

您可以在启动查询时设置权限模式一次，或在会话活跃时动态更改它。

<CodeGroup>
  ```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",  # 在此处设置模式
          ),
      ):
          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" // 在此处设置模式
      }
    })) {
      if ("result" in message) {
        console.log(message.result);
      }
    }
  }

  main();
  ```
</CodeGroup>

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

  async def main():
      async with ClaudeSDKClient(
          options=ClaudeAgentOptions(
              permission_mode="default",  # 以默认模式开始
          )
      ) as client:
          await client.query("Help me refactor this code")

          # 在会话中期动态更改模式
          await client.set_permission_mode("acceptEdits")

          # 使用新权限模式处理消息
          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" // 以默认模式开始
      }
    });

    // 在会话中期动态更改模式
    await q.setPermissionMode("acceptEdits");

    // 使用新权限模式处理消息
    for await (const message of q) {
      if ("result" in message) {
        console.log(message.result);
      }
    }
  }

  main();
  ```
</CodeGroup>

模式详情

接受编辑模式（acceptEdits）

自动批准文件操作，以便 Claude 可以编辑代码而无需提示。其他工具（如不是文件系统操作的 Bash 命令）仍然需要正常权限。

自动批准的操作：

• 文件编辑（Edit、Write 工具）
• 文件系统命令：mkdir、touch、rm、rmdir、mv、cp、sed

两者都仅适用于工作目录或 additionalDirectories 内的路径。该范围外的路径和对受保护路径的写入仍然会提示。

使用时机： 您信任 Claude 的编辑并希望更快的迭代，例如在原型设计期间或在隔离目录中工作时。

不询问模式（dontAsk） {#don’t-ask-mode-dontask}

将任何权限提示转换为拒绝。由 allowed_tools、settings.json 允许规则或作为 hook 运行的工具正常运行。连接器工具您的组织设置为 ask和需要用户交互的工具即使允许规则匹配也被拒绝。其他所有内容都被拒绝，无需调用 canUseTool。

使用时机： 您想要为无头代理提供固定的、明确的工具表面，并且更喜欢硬拒绝而不是默默依赖 canUseTool 不存在。

绕过权限模式（bypassPermissions）

自动批准所有工具使用而无需提示。Hooks 仍然执行，如果需要可以阻止操作。

规划模式（plan）

Claude 探索代码库并生成计划而不编辑您的源文件。只读工具在默认模式下运行。文件编辑在规划模式下永远不会自动批准，即使允许规则匹配。它们通过您的 canUseTool 回调提示。Claude 可能使用 AskUserQuestion 在最终确定计划之前澄清需求。请参阅 处理批准和用户输入 以处理这些提示。

使用时机： 您想要 Claude 提议更改而不执行它们，例如在代码审查期间或当您需要在进行更改之前批准更改时。

相关资源

对于权限评估流程中的其他步骤：

• 处理批准和用户输入：交互式批准提示和澄清问题
• Hooks 指南：在代理生命周期中的关键点运行自定义代码
• 权限规则：settings.json 中的声明式允许/拒绝规则