Claude Code 权限系统（官方文档）
Claude Code Permissions System
Anthropic official docs — the core security mechanism that precisely controls what the agent can and cannot do
Three tool tiers × three rule types × six modes × five-level scope form Claude Code’s full permission model. Core semantics: deny-first — evaluation runs deny → ask → allow, the first match wins, deny always takes priority. A deny at any layer cannot be overridden by an allow elsewhere.
cat inside Bash — sandbox enforces isolation at the OS levelClaude Code 权限系统（官方文档）
基本信息
- 来源:
sources/anthropic_official/claude-code-permissions.md - 原文 URL: https://code.claude.com/docs/en/permissions
- 作者: Anthropic
- 采集日期: 2026-04-08
摘要
本文档是 Anthropic 官方的 Claude Code 权限系统完整参考。Claude Code 是一款 AI 编码 agent，权限系统是其核心安全机制——精确控制 agent 被允许做什么、不能做什么。
核心主题
1. 分层权限系统（Tiered Permission System）
Claude Code 将工具分为三类，审批要求不同：
| 工具类型 | 示例 | 需要审批 | ”不再询问”行为 |
|---|---|---|---|
| 只读工具 | 文件读取、Grep | 否 | N/A |
| Bash 命令 | Shell 执行 | 是 | 永久记录（按项目目录+命令） |
| 文件修改 | 编辑/写入文件 | 是 | 会话结束前有效 |
这个三级结构体现了风险分层：只读操作无需确认，文件修改需要一次会话级授权，Bash 命令风险最高因而需要永久级审批（保存到 settings）。
2. Allow/Ask/Deny 规则层次
Claude Code 使用三类规则管理权限：
- Allow：无需手动确认，直接允许使用指定工具
- Ask：每次使用前提示确认
- Deny：阻止使用
评估顺序：deny → ask → allow。第一个匹配的规则生效，因此 deny 规则总是优先。这是”拒绝优先”（deny-first）语义——只有没有 deny 规则匹配时，才考虑 ask，再才考虑 allow。
3. 六种权限模式
通过 defaultMode 配置：
| 模式 | 描述 |
|---|---|
default | 标准行为：每个工具首次使用时提示 |
acceptEdits | 自动接受文件编辑权限（受保护目录除外） |
plan | 计划模式：只能分析，不能修改文件或执行命令 |
auto | 自动审批，后台安全检查验证操作是否符合请求意图 |
dontAsk | 自动拒绝，除非通过 /permissions 或 allow 规则预先授权 |
bypassPermissions | 跳过权限提示（受保护目录仍提示） |
bypassPermissions 最危险，仅应用于容器/VM 等隔离环境。管理员可在托管设置中禁用此模式。
4. 规则指定符（Specifiers）
规则格式：Tool 或 Tool(specifier)
工具级（匹配所有使用）：
Bash、Read、WebFetch
精细匹配：
Bash(npm run build)— 精确匹配命令Read(./.env)— 精确匹配文件路径WebFetch(domain:example.com)— 按域名匹配
通配符：Bash(npm run *) 匹配所有以 npm run 开头的命令。空格前的 * 强制单词边界：Bash(ls *) 匹配 ls -la 但不匹配 lsof。
MCP 工具：mcp__puppeteer、mcp__puppeteer__puppeteer_navigate
子 Agent：Agent(Explore)、Agent(my-custom-agent)
5. 作用域层次（Settings Precedence）
优先级从高到低：
- 托管设置（Managed）：不可被任何其他层覆盖
- 命令行参数：临时会话覆盖
- 本地项目设置（
.claude/settings.local.json） - 共享项目设置（
.claude/settings.json） - 用户设置（
~/.claude/settings.json）
关键语义：任意层级的 deny 都不可被其他层的 allow 覆盖。例如，托管 deny 无法通过 --allowedTools 绕过。
6. 权限与沙箱：两层互补安全
- 权限：控制 Claude Code 可以使用哪些工具、访问哪些文件/域名（适用于所有工具）
- 沙箱：OS 级强制隔离，限制 Bash 工具的文件系统和网络访问（仅适用于 Bash 命令及其子进程）
纵深防御逻辑：权限规则阻止 Claude 发起受限访问请求，沙箱在 prompt injection 绕过模型决策时作为最后防线。
7. Hooks 扩展权限
PreToolUse hooks 在权限提示前运行，可动态：
- 拒绝工具调用（exit 2）
- 强制提示
- 跳过提示（但不绕过 deny 规则）
8. Auto 模式分类器
Auto 模式使用分类器模型判断每个操作是否安全。分类器读取 autoMode 配置：
environment：描述可信基础设施allow：例外规则soft_deny：阻止规则
设置 allow 或 soft_deny 会替换全部默认值，需先运行 claude auto-mode defaults 获取内置规则。
9. 托管设置（Managed Settings）
组织管理员可通过 MDM/OS 级策略部署不可覆盖的设置。托管专属设置包括：
allowManagedPermissionRulesOnly：阻止用户和项目定义权限规则allowManagedHooksOnly：阻止加载用户/项目/插件钩子allowManagedMcpServersOnly：仅允许托管 MCP 服务器
关键洞察
- 规则层次是 deny-first，不是 allow-first：匹配优先级 deny > ask > allow 的”第一匹配”语义意味着阻止比允许更容易实现和更难绕过
- 权限与沙箱是互补而非替代：Read 规则阻止读工具，但不阻止
cat file的 Bash 命令——需要沙箱补足 - Auto 模式分类器是可配置的：内置规则不够时可通过 environment/allow/soft_deny 调整
- Bash 权限规则不可靠用于参数约束：通配符模式对变量、空格、重定向等变体无效——应使用 WebFetch+域名规则或 PreToolUse hooks
与其他来源的关联
- 与 Agent Sandboxing 的 OS 级沙箱研究形成互补——本文档提供了沙箱之上的应用层权限控制
- 与 Guardrails 的分层防御模式一致——Claude Code 的权限系统是专门化的 guardrails 实现
bypassPermissions模式印证了 Agent OS 讨论中的容器/VM 隔离部署模式- 托管设置机制对应 Harness Engineering 中”组织级约束编码进 harness”的思路
References
sources/anthropic_official/claude-code-permissions.md