文档索引

在此获取完整文档索引：https://code.claude.com/docs/llms.txt 使用此文件发现所有可用页面，然后再进一步探索。

配置权限

使用权限模式、钩子和声明式允许/拒绝规则控制智能体如何使用工具。

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

权限评估方式

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

1. 钩子

   首先运行钩子。钩子可以完全拒绝调用或传递它。返回 allow 的钩子不会跳过下面的拒绝和询问规则；无论钩子结果如何都会评估这些规则。

2. 拒绝规则

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

3. 权限模式

   应用活动的权限模式。bypassPermissions 批准到达此步骤的所有内容。acceptEdits 批准文件操作。其他模式继续传递。

4. 允许规则

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

5. canUseTool 回调

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

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

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

允许和拒绝规则

allowed_tools 和 disallowed_tools（TypeScript：allowedTools / disallowedTools）向上面评估流程中的允许和拒绝规则列表添加条目。允许规则仅影响审批：未列在 allowed_tools 中的工具仍然可用，并传递到权限模式。拒绝规则根据它们是命名工具还是限定工具内的模式而表现不同。

对于锁定的智能体，将 allowedTools 与 permissionMode: "dontAsk" 配对使用。列出的工具被批准；其他任何内容都被完全拒绝而不是提示：

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

您还可以在 .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",  # 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();

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 内的路径。超出该范围的路径和对受保护路径的写入仍会提示。

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

不询问模式（dontAsk）

将任何权限提示转换为拒绝。由 allowed_tools、settings.json 允许规则或钩子运行预批准的工具正常运行。其他一切都被拒绝，不调用 canUseTool。

适用场景： 您想要为无头智能体提供固定的、显式的工具表面，并倾向于硬拒绝而不是静默依赖 canUseTool 不存在。

绕过权限模式（bypassPermissions）

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

计划模式（plan）

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

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

相关资源

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

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