配置权限
使用权限模式、hooks 和声明式允许/拒绝规则来控制您的代理如何使用工具。
Claude Agent SDK 提供权限控制来管理 Claude 如何使用工具。使用权限模式和规则来定义自动允许的内容，以及使用 canUseTool 回调 在运行时处理其他所有情况。
权限如何被评估
当 Claude 请求一个工具时，SDK 按以下顺序检查权限：
拒绝规则
检查 deny 规则（来自 disallowed_tools 和 settings.json）。如果拒绝规则匹配，工具被阻止，即使在 bypassPermissions 模式下也是如此。裸名称拒绝规则（如 Bash）在此评估开始之前将工具从 Claude 的上下文中移除，因此只有作用域规则（如 Bash(rm *)）在此步骤中被检查。
询问规则
检查来自 settings.json 的 ask 规则。如果询问规则匹配，调用会传递到您的 canUseTool 回调 以获得确认，即使在 bypassPermissions 模式下也是如此。
需要用户交互的工具行为相同：AskUserQuestion 和 MCP 工具，其服务器设置 _meta["anthropic/requiresUserInteraction"] 总是传递到回调，即使当允许规则匹配时。在 dontAsk 模式下，两种情况都被拒绝，因为该模式从不提示。MCP 注解需要 Claude Code v2.1.199 或更高版本。
claude.ai connector 工具，您的组织已设置为 ask 也会在此步骤离开流程。每个调用都会传递到回调，即使在 bypassPermissions 模式下，即使当允许规则匹配时。回调接收原因 Your organization requires approval for this tool。在 dontAsk 模式下，调用被拒绝，因为该模式从不提示。
权限模式
应用活跃的 权限模式：
- 在
bypassPermissions模式下，Claude Code 批准到达此步骤的所有内容，除了针对 关键路径 的rm和rmdir删除，这些会传递下去。 - 在
acceptEdits模式下，Claude Code 批准 Accept edits mode 下列出的文件操作。 - 在
plan模式下，Claude Code 将文件编辑和 shell 写入工具发送到您的canUseTool回调，无论允许规则如何，因此在规划时写入操作无法自动批准。 - 在其他模式下，请求会传递下去。
允许规则
检查 allow 规则（来自 allowed_tools 和 settings.json）。如果规则匹配，工具被批准。调用工具自身批准的是在此步骤解决的，无需规则：例如在您的工作目录内的文件读取或 只读 Bash 命令。针对 关键路径 的 rm 和 rmdir 删除永远不会被允许规则批准：它们在提示的模式下到达您的回调，在 Claude Code v2.1.218 或更高版本的 auto 模式下进入 分类器，并在 dontAsk 模式下被拒绝。
canUseTool 回调
如果上述任何步骤都未解决，调用您的 canUseTool 回调 以获得决定。在 dontAsk 模式下，此步骤被跳过，工具被拒绝。
在 TypeScript SDK 中，如果您设置 permissionPrompts: 'none'，您的回调在此步骤不会被调用。一个 PermissionRequest hook 仍然有机会决定，如果它不决定，Claude Code 拒绝调用。该选项需要 Claude Code v2.1.259 或更高版本。
如果您在 TypeScript SDK 期望评估顺序在咨询回调之前自动批准调用的配置中传递 canUseTool 回调，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 Code 也会选择加入会话。任何其他未在 allowed_tools 中列出的工具仍然可供 Claude 使用，对其的调用如果需要批准，会继续进行权限模式。拒绝规则的行为取决于它们是命名工具还是在工具内范围化模式。
| 选项 | 效果 |
|---|---|
allowed_tools=["Read", "Grep"] |
Read 和 Grep 被自动批准。此处未列出的其他工具仍然存在，对其的调用如果需要批准，会继续进行权限模式和 canUseTool。 |
disallowed_tools=["Bash"] |
Bash 工具定义从请求中移除。Claude 看不到该工具，无法尝试它。 |
disallowed_tools=["Bash(rm *)"] |
Bash 保持可用。与 rm * 如所写 匹配的调用在每个权限模式中都被拒绝，包括 bypassPermissions。其他 Bash 调用，包括 /bin/rm，继续进行权限模式。 |
disallowed_tools=["*"] |
每个工具定义都从请求中移除。工具名称通配符在拒绝规则中受支持："*" 匹配每个工具，"mcp__*" 匹配所有服务器中的每个 MCP 工具。 |
允许规则仅在字面 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"
};
列出的工具被批准，除了任何模式都不自动批准的操作，以及每个其他会提示的调用都被拒绝。在 default 模式中不需要批准的调用无论您是否列出它们都会运行，例如只读 Bash 命令、不在运行前询问的工具如 Agent，以及您工作目录内的文件读取。要将工具完全置于 Claude 的范围之外，请将其裸名称添加到 disallowedTools。
您也可以在 .claude/settings.json 中声明式地配置允许、拒绝和询问规则。当启用 project 设置源时，这些规则被读取，默认 query() 选项就是这样。如果您显式设置 setting_sources（TypeScript：settingSources），请包含 "project" 以使其应用。请参阅 权限设置 了解规则语法。
权限模式
权限模式提供对 Claude 如何使用工具的全局控制。您可以在调用 query() 时设置权限模式，或在流式会话期间动态更改它。
可用模式
SDK 支持这些权限模式：
| 模式 | 描述 | 工具行为 |
|---|---|---|
default |
标准权限行为 | 无基于模式的自动批准；需要批准且不匹配任何允许规则的调用会触发您的 canUseTool 回调 |
dontAsk |
拒绝而不是提示 | 任何会提示的调用都被拒绝。由 allowed_tools 或规则批准的调用会运行，在 default 模式下不需要批准的调用也会运行；连接器工具您的组织设置为 ask和需要用户交互的工具即使您已预批准它们也被拒绝，rm 和 rmdir 移除针对关键路径也被拒绝。canUseTool 永远不会被调用 |
acceptEdits |
自动接受文件编辑 | 文件编辑和 文件系统操作（mkdir、rm、mv 等）被自动批准 |
bypassPermissions |
绕过权限检查 | 工具运行而无需权限提示，除了任何模式都不自动批准的操作。谨慎使用 |
plan |
规划模式 | Claude 在不编辑源文件的情况下探索和规划；文件编辑永远不会自动批准，并通过您的 canUseTool 回调提示 |
auto |
模型分类批准 | 模型分类器批准或拒绝权限提示。请参阅Auto 模式了解可用性 |
设置权限模式
您可以在启动查询时设置权限模式一次，或在会话活跃时动态更改它。
在创建查询时传递 permission_mode（Python）或 permissionMode（TypeScript）。此模式应用于整个会话，除非动态更改。
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())
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）以在会话中期更改模式。新模式立即对所有后续工具请求生效。这让您可以从限制性开始，随着信任建立而放松权限，例如在审查 Claude 的初始方法后切换到 acceptEdits。
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())
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 内的路径。在 acceptEdits 模式下，当 Claude 时，Claude Code 不会自动批准请求：
- 在该范围之外的路径上工作
- 写入受保护的路径
- 使用
rm或rmdir移除关键路径
使用时机： 您信任 Claude 的编辑并希望更快的迭代，例如在原型设计期间或在隔离目录中工作时。
不询问模式（`dontAsk`）
将任何权限提示转换为拒绝，无需调用 canUseTool。由 allowed_tools、settings.json 允许规则或 hook 预批准的工具正常运行，在 default 模式下不需要批准的调用也会运行，例如在您的工作目录内的文件读取和对 Agent 的调用。连接器工具您的组织设置为 ask、需要用户交互的工具，以及 rm 和 rmdir 移除针对关键路径即使允许规则匹配也被拒绝。PreToolUse hook 允许也不会清除关键路径移除。
使用时机： 您想要为无头代理提供固定的、明确的工具表面，并且更喜欢硬拒绝而不是默默依赖 canUseTool 不存在。
绕过权限模式（`bypassPermissions`）
自动批准工具使用而无需提示，除了下面警告中列出的情况。Hooks 仍然执行，如果需要可以阻止操作。
规划模式（`plan`）
Claude 探索代码库并生成计划而不编辑您的源文件。只读工具在 default 权限模式下运行。
文件编辑在规划模式下永远不会自动批准，即使允许规则匹配。它们通过您的 canUseTool 回调提示。在 Claude Code v2.1.212 或更高版本上，修改文件的 shell 命令，如 touch 和 rm，以相同方式到达您的 canUseTool 回调。
Claude 可能使用 AskUserQuestion 在最终确定计划之前澄清需求。请参阅处理批准和用户输入以处理这些提示。
使用时机： 您想要 Claude 提议更改而不执行它们，例如在代码审查期间或当您需要在进行更改之前批准更改时。
相关资源
对于权限评估流程中的其他步骤：