权限模型与内置工具概览

Claude Code 之所以被称为"代理"，是因为它能真正动手：读文件、改代码、跑命令、联网检索。能力越大，控制边界越重要。本节系统讲解两件事：权限模式决定"哪些动作免确认、哪些必须先问你"，内置工具决定"它手里有哪些动作能力"。读完你应能为不同场景选择合适的模式，并读懂确认提示里的工具与参数。

一、为什么必须理解权限模型

代理的动作分两类风险等级：读取类动作（查看文件、搜索内容）通常低风险；写入与执行类动作（修改文件、运行命令、联网请求）可能改变你的代码和系统状态，需要明确授权。权限模型就是在"全自动提效"与"人工可控安全"之间选择平衡点：

• 权限模式设定基础门槛（基线）。
• 权限规则（allow / ask / deny）在模式之上对具体工具、命令或路径做精细化追加。
• 两者叠加：模式决定默认是否询问，规则决定特定动作的固定放行或固定拦截。

二、六种权限模式对照（以官方定义为准）

模式配置值	界面/CLI 叫法	免确认即可执行的范围	最适合的场景	状态栏提示
default	Manual（手动模式）	仅读取类动作；写入、命令、联网等逐条询问	敏感工作、不熟悉的代码库、逐条审阅每一步	⏸ manual mode on
acceptEdits	自动接受编辑	读取、文件编辑，以及常见文件系统命令（如 mkdir、touch、mv、cp 等），不再为文件改动反复确认	正在逐轮审阅的本地代码迭代，减少确认打扰	⏵⏵ accept edits on
plan	计划模式	读取与探索；auto 可用时由分类器批准的探索类命令；在你批准方案前阻止源码编辑	动手前先调研代码库、产出修改方案	⏸ plan mode on
auto	自动模式	在后台安全检查覆盖下执行大部分动作，减少提示疲劳（需受支持模型，且组织未关闭）	长任务、批量任务，兼顾效率与安全检查	⏵⏵ auto mode on
dontAsk	不询问（锁定）	只放行工作目录内读取与已预批准工具；凡是本应询问的动作直接拒绝，适合脚本化 CI	CI、自动化脚本，用精确白名单限定能力	⏵⏵ don't ask on
bypassPermissions	绕过全部权限确认	全部动作不再询问；仅限隔离容器、虚拟机等受控环境使用	沙箱化的隔离执行，不用于本机日常开发	⏵⏵ bypass permissions on

三、切换模式：会话内、启动时、规则层

1. 会话内循环切换。在交互式会话中按 Shift+Tab 循环切换权限模式：若从 auto 开始，第一次按下切到 default，之后沿 default → acceptEdits → plan 循环；可选模式（如 bypassPermissions）在启用后插入到循环中。当前模式直接显示在状态栏。

2. 启动时指定初始模式。在终端启动会话时通过参数指定：

# 以计划模式启动：只调研、先出方案
claude --permission-mode plan

3. 非交互（脚本）白名单模式。一次性执行任务时，可用 dontAsk 配合精确工具白名单，把能力锁死在允许范围内：

# 非交互运行：只允许读取与运行 npm test，其余需确认动作直接拒绝
claude -p "run the test suite" --permission-mode dontAsk --allowedTools "Bash(npm test)" "Read"

4. 规则层精细管理。运行 /permissions 打开交互界面管理 allow / ask / deny 规则；deny（拒绝）规则在所有模式下都生效，包括 bypassPermissions；而 allow（放行）规则在 bypassPermissions 下不再额外起作用。

四、核心内置工具一览

下表列出入门到进阶阶段最常接触的内置工具；"需确认"指在 Manual 默认模式下、工作目录内是否会弹出审批。工具的精确名称同时用于权限规则书写。

工具名	职责	Manual 模式下是否需确认
Read	读取指定文件内容；工作目录内直接进行，访问目录外路径会询问	否（工作区内）
Grep	按模式在文件内容中检索匹配项	否（只读检索）
Glob	按文件名模式查找匹配文件	否（只读检索）
Edit	对指定文件做定向、局部修改	是
Write	新建文件或整体覆盖写入	是
Bash	在当前环境执行 shell 命令；内置的一组只读命令可不提示直接运行，其余命令需批准	是（只读子命令除外）
PowerShell	Windows 环境下原生执行 PowerShell 命令	是
WebFetch	抓取指定 URL，把页面转为 Markdown 后按提示提取要点；拒绝无点主机（如 localhost）、HTTP 自动升级为 HTTPS、单次读取有内容上限	是
WebSearch	发起联网检索，返回标题与链接；要读详情需再配合 WebFetch	是
Agent	派出拥有独立上下文窗口的子代理处理子任务，结果汇总回来	否
EnterPlanMode / ExitPlanMode	进入计划模式；提交方案并退出、等待你批准后才动手	进入否 / 退出（含方案）是
AskUserQuestion	以选择题形式向你澄清需求或消除歧义，问题默认保持开放直到作答	否
TaskCreate / TaskList / TaskUpdate	维护会话内任务清单的创建、查看与状态更新	否
Monitor	后台运行命令并把每行输出回喂给代理，便于根据日志变化动态响应	是

五、权限规则怎么写（allow / deny 示例）

在 /permissions、设置文件的 permissions.allow / permissions.deny，或启动参数 --allowedTools 中，规则格式为 工具名(限定符)：

规则示例	作用对象与含义
Bash(npm run *)	匹配 npm run 开头的命令（Bash、Monitor 适用命令模式匹配）
Edit(/src/**)	放行对 /src 目录下文件的编辑；Edit 的放行同时授予同路径读取权
Read(~/secrets/**)	对指定敏感目录的读取做明确规则控制（Read / Grep / Glob / LSP 适用路径匹配）
WebFetch(domain:example.com)	限定 WebFetch 可访问的域名
Agent(Explore)	按子代理类型限定可派出的子代理

六、不同阶段的推荐姿势

• 第一次接触陌生项目：从 Manual（default）开始，先用计划模式调研，逐条确认写入与命令。
• 熟悉代码后的迭代修改：可切到 acceptEdits 减少文件编辑确认，命令类动作仍按需审查。
• 改大方案前：用 /plan 或 Shift+Tab 进入计划模式，先拿到方案清单再决定如何执行。
• 自动化 / CI：用 dontAsk 加精确白名单，不依赖交互确认。
• 隔离环境验证：仅在容器、虚拟机等受控环境才考虑 bypassPermissions；Linux/macOS 下不应以 root/sudo 身份运行该模式。