处理权限

在 Claude Agent SDK 中控制工具使用和权限

​

SDK 权限

Claude Agent SDK 提供强大的权限控制功能，允许您管理 Claude 在应用程序中如何使用工具。

本指南涵盖如何使用 canUseTool 回调、钩子和 settings.json 权限规则来实现权限系统。有关完整的 API 文档，请参阅 TypeScript SDK 参考。

​

概述

Claude Agent SDK 提供四种互补的方式来控制工具使用：

1. 权限模式 - 影响所有工具的全局权限行为设置
2. canUseTool 回调 - 用于其他规则未涵盖情况的运行时权限处理程序
3. 钩子 - 通过自定义逻辑对每个工具执行进行细粒度控制
4. 权限规则 (settings.json) - 具有集成 bash 命令解析的声明式允许/拒绝规则

每种方法的用例：

• 权限模式 - 设置整体权限行为（规划、自动接受编辑、绕过检查）
• canUseTool - 对未涵盖情况的动态批准，提示用户获取权限
• 钩子 - 对所有工具执行的程序化控制
• 权限规则 - 具有智能 bash 命令解析的静态策略

​

权限流程图

处理顺序： PreToolUse 钩子 → 拒绝规则 → 允许规则 → 询问规则 → 权限模式检查 → canUseTool 回调 → PostToolUse 钩子

​

权限模式

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

​

可用模式

SDK 支持四种权限模式，每种都有不同的行为：

模式	描述	工具行为
default	标准权限行为	应用正常权限检查
plan	规划模式 - 无执行	Claude 只能使用只读工具；在执行前呈现计划 （SDK 中当前不支持）
acceptEdits	自动接受文件编辑	文件编辑和文件系统操作自动获得批准
bypassPermissions	绕过所有权限检查	所有工具无需权限提示即可运行（谨慎使用）

​

设置权限模式

您可以通过两种方式设置权限模式：

​

1. 初始配置

在创建查询时设置模式：

TypeScript

import { query } from "@anthropic-ai/claude-agent-sdk";

const result = await query({
  prompt: "帮我重构这段代码",
  options: {
    permissionMode: 'default'  // 标准权限模式
  }
});

​

2. 动态模式更改（仅流式）

在流式会话期间更改模式：

TypeScript

import { query } from "@anthropic-ai/claude-agent-sdk";

// 为流式输入创建异步生成器
async function* streamInput() {
  yield { 
    type: 'user',
    message: { 
      role: 'user', 
      content: "让我们从默认权限开始" 
    }
  };
  
  // 稍后在对话中...
  yield {
    type: 'user',
    message: {
      role: 'user',
      content: "现在让我们加快开发速度"
    }
  };
}

const q = query({
  prompt: streamInput(),
  options: {
    permissionMode: 'default'  // 以默认模式开始
  }
});

// 动态更改模式
await q.setPermissionMode('acceptEdits');

// 处理消息
for await (const message of q) {
  console.log(message);
}

​

特定模式行为

​

接受编辑模式 (acceptEdits)

在接受编辑模式下：

• 所有文件编辑自动获得批准
• 文件系统操作（mkdir、touch、rm 等）自动批准
• 其他工具仍需要正常权限
• 当您信任 Claude 的编辑时加快开发速度
• 适用于快速原型制作和迭代

自动批准的操作：

• 文件编辑（Edit、Write 工具）
• Bash 文件系统命令（mkdir、touch、rm、mv、cp）
• 文件创建和删除

​

绕过权限模式 (bypassPermissions)

在绕过权限模式下：

• 所有工具使用都自动获得批准
• 不出现权限提示
• 钩子仍然执行（仍可阻止操作）
• 极其谨慎使用 - Claude 拥有完整系统访问权限
• 仅建议在受控环境中使用

​

权限流程中的模式优先级

权限模式在权限流程的特定点进行评估：

1. 钩子首先执行 - 可以允许、拒绝、询问或继续
2. 检查拒绝规则 - 无论模式如何都阻止工具
3. 检查允许规则 - 如果匹配则允许工具
4. 检查询问规则 - 如果匹配则提示权限
5. 评估权限模式：
   • bypassPermissions 模式 - 如果激活，允许所有剩余工具
   • 其他模式 - 延迟到 canUseTool 回调
6. canUseTool 回调 - 处理剩余情况

这意味着：

• 钩子始终可以控制工具使用，即使在 bypassPermissions 模式下
• 显式拒绝规则覆盖所有权限模式
• 询问规则在权限模式之前评估
• bypassPermissions 模式覆盖未匹配工具的 canUseTool 回调

​

最佳实践

1. 使用默认模式 进行受控执行和正常权限检查
2. 使用 acceptEdits 模式 处理隔离文件或目录时
3. 避免 bypassPermissions 在生产环境或有敏感数据的系统上
4. 结合模式与钩子 进行细粒度控制
5. 根据任务进度和信心动态切换模式

模式进展示例：

// 以默认模式开始进行受控执行
permissionMode: 'default'

// 切换到 acceptEdits 进行快速迭代
await q.setPermissionMode('acceptEdits')

​

canUseTool

canUseTool 回调在调用 query 函数时作为选项传递。它接收工具名称和输入参数，必须返回一个决定 - 允许或拒绝。

canUseTool 在 Claude Code 向用户显示权限提示时触发，例如钩子和权限规则不涵盖它且不在 acceptEdits 模式下。

以下是一个完整示例，展示如何实现交互式工具批准：

TypeScript

import { query } from "@anthropic-ai/claude-agent-sdk";

async function promptForToolApproval(toolName: string, input: any) {
  console.log("\n🔧 工具请求:");
  console.log(`   工具: ${toolName}`);
  
  // 显示工具参数
  if (input && Object.keys(input).length > 0) {
    console.log("   参数:");
    for (const [key, value] of Object.entries(input)) {
      let displayValue = value;
      if (typeof value === 'string' && value.length > 100) {
        displayValue = value.substring(0, 100) + "...";
      } else if (typeof value === 'object') {
        displayValue = JSON.stringify(value, null, 2);
      }
      console.log(`     ${key}: ${displayValue}`);
    }
  }
  
  // 获取用户批准（用您的 UI 逻辑替换）
  const approved = await getUserApproval();
  
  if (approved) {
    console.log("   ✅ 已批准\n");
    return {
      behavior: "allow",
      updatedInput: input
    };
  } else {
    console.log("   ❌ 已拒绝\n");
    return {
      behavior: "deny",
      message: "用户拒绝了此工具的权限"
    };
  }
}

// 使用权限回调
const result = await query({
  prompt: "帮我分析这个代码库",
  options: {
    canUseTool: async (toolName, input) => {
      return promptForToolApproval(toolName, input);
    }
  }
});

​

相关资源

• 钩子指南 - 了解如何实现钩子以对工具执行进行细粒度控制
• 设置：权限规则 - 配置具有 bash 命令解析的声明式允许/拒绝规则