配置权限

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

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

ℹ️ 本页面涵盖权限模式和规则。要构建交互式批准流程，其中用户在运行时批准或拒绝工具请求，请参阅处理批准和用户输入。

权限如何被评估

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

1. Hooks：首先运行 hooks。一个 hook 可以直接拒绝调用或将其传递下去。返回 allow 的 hook 不会跳过下面的拒绝和询问规则；无论 hook 结果如何，这些规则都会被评估。
2. 拒绝规则：检查 deny 规则（来自 disallowed_tools 和 settings.json）。如果拒绝规则匹配，工具被阻止，即使在 bypassPermissions 模式下也是如此。
3. 权限模式：应用活跃的权限模式。bypassPermissions 批准到达此步骤的所有内容。acceptEdits 批准文件操作。其他模式会继续进行。
4. 允许规则：检查 allow 规则（来自 allowed_tools 和 settings.json）。如果规则匹配，工具被批准。
5. canUseTool 回调：如果上述任何步骤都未解决，调用您的 canUseTool 回调以获得决定。在 dontAsk 模式下，此步骤被跳过，工具被拒绝。

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

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

允许和拒绝规则

allowed_tools 和 disallowed_tools（TypeScript：allowedTools / disallowedTools）向上面评估流程中的允许和拒绝规则列表添加条目。它们控制工具调用是否被批准，而不是工具是否对 Claude 可用。

选项	效果
allowed_tools=["Read", "Grep"]	Read 和 Grep 被自动批准。此处未列出的工具仍然存在并继续进行权限模式和 canUseTool。
disallowed_tools=["Bash"]	Bash 始终被拒绝。拒绝规则首先被检查，并在每个权限模式中都有效，包括 bypassPermissions。

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

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" 以使其应用。请参阅权限设置了解规则语法。

权限模式

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

可用模式

SDK 支持这些权限模式：

模式	描述	工具行为
default	标准权限行为	无自动批准；不匹配的工具触发您的 canUseTool 回调
dontAsk	拒绝而不是提示	任何未被 allowed_tools 或规则预批准的内容都被拒绝；canUseTool 永远不会被调用
acceptEdits	自动接受文件编辑	文件编辑和文件系统操作（mkdir、rm、mv 等）被自动批准
bypassPermissions	绕过所有权限检查	所有工具运行而无需权限提示（谨慎使用）
plan	规划模式	只读工具运行；Claude 分析和规划而不编辑您的源文件
auto（仅 TypeScript）	模型分类批准	模型分类器批准或拒绝每个工具调用。

⚠️ 子代理继承： 当父代理使用 bypassPermissions、acceptEdits 或 auto 时，所有子代理继承该模式，并且不能按子代理覆盖。子代理可能有不同的系统提示和行为约束较少，比您的主代理，所以继承 bypassPermissions 授予它们完整的、自主的系统访问权限，无需任何批准提示。

设置权限模式

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

在查询时，传递 permission_mode（Python）或 permissionMode（TypeScript）。此模式应用于整个会话，除非动态更改。

Python：

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：

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

在流式传输期间，调用 set_permission_mode()（Python）或 setPermissionMode()（TypeScript）以在会话中期更改模式。

Python：

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：

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

模式详情

接受编辑模式（acceptEdits）

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

自动批准的操作：

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

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

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

不询问模式（dontAsk）

将任何权限提示转换为拒绝。由 allowed_tools、settings.json 允许规则或作为 hook 运行的工具正常运行。其他所有内容都被拒绝，无需调用 canUseTool。

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

绕过权限模式（bypassPermissions）

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

⚠️ 谨慎使用。Claude 在此模式下具有完整的系统访问权限。仅在您信任所有可能操作的受控环境中使用。

allowed_tools 不约束此模式。每个工具都被批准，而不仅仅是您列出的工具。拒绝规则（disallowed_tools）、显式 ask 规则和 hooks 在模式检查之前被评估，仍然可以阻止工具。

规划模式（plan）

将 Claude 限制为只读工具。Claude 可以读取文件并运行只读 shell 命令来探索代码库，但不编辑您的源文件。Claude 可能使用 AskUserQuestion 在最终确定计划之前澄清需求。请参阅处理批准和用户输入以处理这些提示。

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

相关资源

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

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

---

本文翻译自 Anthropic Claude Code 官方文档，最近一次同步：2025-05-01。