配置权限

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

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

权限如何被评估

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

如果您在 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 使用，对其的调用如果需要批准，则会进入权限模式。拒绝规则的行为取决于它们是命名工具还是在工具内限定模式。

允许规则仅在字面 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 支持以下权限模式：

设置权限模式

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

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

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 允许规则或钩子预先批准的工具会正常运行，default 模式下不需要批准的调用也会运行，例如在您的工作目录内的文件读取和对 Agent 的调用。连接器工具您的组织设置为 ask、需要用户交互的工具，以及 rm 和 rmdir 针对关键路径的删除即使允许规则匹配也会被拒绝。PreToolUse 钩子允许也不会清除关键路径删除。

使用场景： 您希望为无头代理提供固定的、明确的工具表面，并且更喜欢硬拒绝而不是依赖 canUseTool 不存在的无声依赖。

绕过权限模式（`bypassPermissions`）

自动批准工具使用而无需提示，除了下面警告中列出的情况。钩子仍会执行，如果需要可以阻止操作。在 Linux 和 macOS 上，Claude Code 拒绝在此模式下以 root 身份或在已识别的沙箱外的 sudo 下启动，查询在第一轮之前失败。

规划模式（`plan`）

Claude 探索代码库并生成计划，而不编辑您的源文件。只读工具的运行方式与 default 权限模式相同。

在规划模式下，文件编辑永远不会自动批准，即使允许规则匹配。它们会通过您的 canUseTool 回调提示。 在 Claude Code v2.1.212 或更高版本上，修改文件的 shell 命令（如 touch 和 rm）会以相同方式到达您的 canUseTool 回调。

如果您在 permissionMode: 'plan' 旁边设置 allowDangerouslySkipPermissions: true，文件编辑和修改文件的 shell 命令仍然会到达您的 canUseTool 回调。该选项让您稍后可以使用 setPermissionMode() 切换到 bypassPermissions。

Claude 可能会使用 AskUserQuestion 在最终确定计划之前澄清需求。有关处理这些提示的信息，请参阅处理批准和用户输入。

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

相关资源

有关权限评估流程中的其他步骤：

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