配置权限

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

权限如何被评估

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

Hooks

首先运行 hooks。Hook 可以直接拒绝调用或将其传递下去。返回 allow 的 hook 不会跳过下面的拒绝和询问规则；无论 hook 结果如何，这些规则都会被评估。返回 allow 的 PreToolUse hook 也不能批准针对关键路径的 rm 或 rmdir 删除。关于该 allow 在计划模式下的作用，请参阅计划模式下的 hook 批准。

拒绝规则

检查 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 或更高版本。您的组织设置为 ask 的 claude.ai connector 工具也在此步骤离开流程。每个调用都传递到回调，即使在 bypassPermissions 模式下，即使当允许规则匹配时也是如此。回调接收原因 Your organization requires approval for this tool。在 dontAsk 模式下，调用被拒绝，因为该模式从不提示。

权限模式

应用活跃的权限模式：

在 bypassPermissions 模式下，Claude Code 批准到达此步骤的所有内容，除了针对关键路径的 rm 和 rmdir 删除，这些会传递下去。
在 acceptEdits 模式下，Claude Code 批准接受编辑模式下列出的文件操作。
在 plan 模式下，Claude Code 将文件编辑和 shell 写入工具发送到您的 canUseTool 回调，无论允许规则如何，因此在规划时写入操作无法自动批准。
在其他模式下，请求传递下去。

允许规则

检查 allow 规则（来自 allowed_tools 和 settings.json）。如果规则匹配，工具被批准。工具自己批准的调用也在此步骤被解决，无需规则：例如在您的工作目录内的文件读取或只读 Bash 命令。针对关键路径的 rm 和 rmdir 删除永远不会被允许规则批准。它们是否随后到达您的回调取决于权限模式：例如在 auto 模式的 Agent SDK 会话中，Claude Code 默认拒绝它们而不调用它。关键路径模式表列出了每种模式对它们的处理方式。允许规则不会批准从网络路径进行的读取。

canUseTool 回调

如果上述任何步骤都未解决，调用您的 canUseTool 回调以获得决定。在 dontAsk 模式下，此步骤被跳过，工具被拒绝。在 TypeScript SDK 中，如果您设置了 permissionPrompts: 'none'，您的回调在此步骤不会被调用。PermissionRequest hook 仍然有机会决定，如果它不决定，Claude Code 拒绝调用。该选项需要 Claude Code v2.1.259 或更高版本。

六步权限评估流程的图表，与上述步骤匹配：工具请求通过 hooks、拒绝规则、询问规则、权限模式、允许规则和 canUseTool。Hooks、拒绝规则和 canUseTool 可以路由到被阻止；权限模式绕过、允许规则和 canUseTool 可以路由到执行；询问规则路由到 canUseTool。

如果您在 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 规则了解四种锚定形式以及来自设置文件的规则如何解析。

自动批准的工具永远不会到达 canUseTool。 在任何早期步骤中被批准的工具调用，通过 acceptEdits 或 bypassPermissions，或通过允许规则，会跳过你的 canUseTool 回调，因此你在那里放置的权限检查会被该工具无声地绕过。允许规则永远不会自动批准 AskUserQuestion、标记为 _meta["anthropic/requiresUserInteraction"] 的 MCP 工具、连接器工具你的组织设置为 ask，或针对关键路径的 rm 和 rmdir 移除。在 dontAsk 模式中，Claude Code 拒绝这些调用而不调用回调。在其他模式中，前三个会到达回调。根据权限模式，关键路径移除要么到达回调，要么 Claude Code 拒绝它而不调用它，就像它在 auto 模式中对 Agent SDK 会话默认做的那样。覆盖范围取决于条目的形式：像 Read 或 mcp__github__get_issue 这样的裸名称会自动批准对该工具的每个调用，上述例外和从网络路径读取除外，而像 Bash(npm test *) 这样的限定规则仅自动批准匹配的调用，其他需要批准的 Bash 调用仍然会进入回调。对于必须在每个工具调用上运行的检查，使用 PreToolUse hook：hook 在每个其他步骤之前运行，hook 拒绝即使在 bypassPermissions 模式中也适用。

对于锁定的代理，将 allowedTools 与 permissionMode: "dontAsk" 配对：

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

列出的工具被批准，任何模式都不自动批准的操作和从网络路径读取除外，而每个其他会提示的调用都会被拒绝。在 default 模式中不需要批准的调用会运行，无论您是否列出它们，例如只读 Bash 命令、不在运行前询问的 Agent 等工具，以及工作目录内的文件读取。要将工具从请求中完全移除，请将其裸名称添加到 disallowedTools。

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() 时设置权限模式，或在流式会话期间动态更改它。如果您没有设置权限模式，Claude Code 会根据会话启动时的模式中的规则选择起始权限模式：

当适用时，来自会话的设置文件中的 permissions.defaultMode
否则使用内置默认值，可以是自动模式

在自动模式下启动的会话会放弃广泛的允许规则，例如裸 Bash 条目，如自动模式如何评估操作所述。如果您的应用程序依赖于 default 模式或此类规则，请显式传递 default。在 TypeScript Agent SDK v0.3.286 之前，省略 permissionMode 与传递 default 相同。

可用模式

SDK 支持以下权限模式：

模式	描述	工具行为
`default`	标准权限行为	无基于模式的自动批准；需要批准且不匹配任何允许规则的调用会触发您的 `canUseTool` 回调
`dontAsk`	拒绝而不是提示	任何会提示的调用都被拒绝。由 `allowed_tools` 或规则批准的调用会运行，`default` 模式下不需要批准的调用也会运行；连接器工具您的组织设置为 `ask`和需要用户交互的工具即使您已预先批准也会被拒绝，来自网络路径的读取以及 `rm` 和 `rmdir` 针对关键路径的删除也会被拒绝。`canUseTool` 永远不会被调用
`acceptEdits`	自动接受文件编辑	文件编辑和文件系统操作（`mkdir`、`rm`、`mv` 等）会自动批准
`bypassPermissions`	绕过权限检查	工具运行时无需权限提示，除了任何模式都不自动批准的操作。请谨慎使用
`plan`	规划模式	Claude 在不编辑您的源文件的情况下探索和规划；文件编辑永远不会自动批准，而是通过您的 `canUseTool` 回调提示
`auto`	模型分类批准	模型分类器审查 shell 命令和网络请求等操作，允许或阻止它审查的每一个操作。有关可用性和决策顺序，请参阅自动模式

子代理继承： 子代理在父会话的权限模式下运行，除非您在其AgentDefinition上设置 permissionMode，且父会话处于 default、dontAsk 或 plan 模式。即使这样，Claude Code 也永远不会应用 "bypassPermissions" 值，并且仅当该子代理可以使用自动模式时才会应用 "auto" 值。子代理仅在父会话本身处于 bypassPermissions 模式时才在该模式下运行。 bypassPermissions 异常需要 Claude Code v2.1.267 或更高版本。子代理可能具有不同的系统提示和比主代理更少受限的行为，因此继承 bypassPermissions 会授予它们完整的自主系统访问权限。任何模式都不自动批准的操作仍然适用。

设置权限模式

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

在查询时
在流式传输期间

在创建查询时传递 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",  # Set the mode here
        ),
    ):
        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" // Set the mode here
    }
  })) {
    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",  # 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())

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 内的路径。在 acceptEdits 模式下，当 Claude 执行以下操作时，Claude Code 不会自动批准请求：

在该范围之外的路径上工作
写入受保护的路径
使用 rm 或 rmdir 删除关键路径

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

不要询问模式（`dontAsk`）

将任何权限提示转换为拒绝，而不调用 canUseTool。由 allowed_tools、settings.json 允许规则或 hook 预先批准的工具会正常运行，default 模式下不需要批准的调用也会运行，例如在您的工作目录内的文件读取和对 Agent 的调用。连接器工具您的组织设置为 ask、需要用户交互的工具、来自网络路径的读取，以及 rm 和 rmdir 针对关键路径的删除即使允许规则匹配也会被拒绝。PreToolUse hook 允许也不会放行关键路径删除或来自网络路径的读取。 使用场景： 您希望为无头代理提供固定的、明确的工具表面，并且更喜欢硬拒绝而不是依赖 canUseTool 不存在的无声依赖。

绕过权限模式（`bypassPermissions`）

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

请极其谨慎使用。Claude 在此模式下具有完整的系统访问权限。仅在您信任所有可能操作的受控环境中使用。allowed_tools 不会限制此模式。每个工具都被批准，而不仅仅是您列出的工具。这些控制仍然适用：

拒绝规则、显式 ask 规则和钩子在模式检查之前被评估，仍然可以阻止工具。
连接器工具您的组织设置为 ask、需要用户交互的工具，以及 rm 和 rmdir 针对关键路径的删除仍然会转到您的 canUseTool 回调。
跨会话消息保护措施仍然适用。

规划模式（`plan`）

Claude 探索代码库并生成计划，而不编辑您的源文件。只读工具的运行方式与 default 权限模式相同。在计划模式下，文件编辑永远不会自动批准，即使允许规则匹配或 PreToolUse hook 返回 allow。它们会通过您的 canUseTool 回调提示。在 Claude Code v2.1.212 或更高版本上，修改文件的 shell 命令（如 touch 和 rm）会以相同方式到达您的 canUseTool 回调。在 TypeScript SDK 中，如果您在 permissionMode: 'plan' 旁边设置 allowDangerouslySkipPermissions: true，文件编辑和修改文件的 shell 命令仍然会到达您的 canUseTool 回调。该选项让您稍后可以使用 setPermissionMode() 切换到 bypassPermissions。 Claude 可能会使用 AskUserQuestion 在最终确定计划之前澄清需求。有关处理这些提示的信息，请参阅处理批准和用户输入。 使用场景： 您希望 Claude 提议更改而不执行它们，例如在代码审查期间或当您需要在进行更改之前批准更改时。

自动模式（`auto`）

分类器模型会在 shell 命令和网络请求等操作运行之前对其进行审查，并允许或阻止它审查的每一个操作。有关自动模式所需的模型和提供商以及它评估操作的顺序，请参阅使用自动模式消除权限提示。如果您使用 set_model()、setModel() 或 applyFlagSettings() 将处于自动模式的会话切换到自动模式不支持的模型，会话将更改为 default 模式：

您会看到的内容：一条子类型为 status、permissionMode 设置为 "default" 的 system 消息，TypeScript SDK 将其类型定义为 SDKStatusMessage。此后，需要批准且不匹配任何允许规则的调用会到达您的 canUseTool 回调。
返回自动模式：切换到受支持的模型，然后调用 set_permission_mode("auto") 或 setPermissionMode("auto")。如果您切换回原模型但未进行该调用，会话将保持在 default 模式。当不受支持的模型处于活动状态时，该调用会失败并显示 Cannot set permission mode to auto: auto mode unavailable for this model。

在调用 set_model()、setModel() 或 applyFlagSettings() 之后更改为 default 模式需要 Claude Code v2.1.299 或更高版本。有关权限评估流程中的其他步骤：

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

Agent SDK

构建 Agent

核心概念

输入和输出

使用工具扩展

自定义行为

控制与可观测性

部署

SDK 参考

权限如何被评估

允许和拒绝规则

权限模式

可用模式

设置权限模式

模式详情

接受编辑模式（`acceptEdits`）

不要询问模式（`dontAsk`）

绕过权限模式（`bypassPermissions`）

规划模式（`plan`）

自动模式（`auto`）

​权限如何被评估

​允许和拒绝规则

​权限模式

​可用模式

​设置权限模式

​模式详情

​接受编辑模式（acceptEdits）

​不要询问模式（dontAsk）

​绕过权限模式（bypassPermissions）

​规划模式（plan）

​自动模式（auto）

​相关资源

权限如何被评估

允许和拒绝规则

权限模式

可用模式

设置权限模式

模式详情

接受编辑模式（`acceptEdits`）

不要询问模式（`dontAsk`）

绕过权限模式（`bypassPermissions`）

规划模式（`plan`）

自动模式（`auto`）

相关资源