管理权限

权限配置的目标不是让 Claude Code 少问，而是让它在低风险动作上少问，在高风险动作上必须停下。少弹窗只是结果，边界清楚才是目的。——翔宇

1. 权限管的是“工具调用”，不是 Claude 的想法

Claude Code 做事靠工具。

它读文件、改文件、运行命令、抓网页、调用 MCP、派 subagent，本质上都是一次 tool call。权限系统管的就是这些 tool call 能不能发生、要不要问你。

官方 Configure permissions 文档给了一个基础分层：

所以不要把权限理解成“信任 Claude 还是不信任 Claude”。更准确是：

2. 六种权限模式：先定整体姿态

权限模式决定一场会话里 Claude Code 多常停下来问你。

CLI 里可以启动时指定：

claude --permission-mode plan

也可以写默认模式：

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

Shift+Tab 默认循环 default → acceptEdits → plan。dontAsk 不在循环里；auto 和 bypassPermissions 需要满足条件或显式启用。

3. 三类规则：deny / ask / allow

模式是整体姿态，规则是具体边界。

官方规则顺序是：

deny -> ask -> allow

第一条匹配规则生效，所以 deny 永远优先：

flowchart TD
    Call[Claude 准备调用工具]
    Call --> CheckDeny{命中 deny?}
    CheckDeny -->|是| Block[直接阻止]
    CheckDeny -->|否| CheckAsk{命中 ask?}
    CheckAsk -->|是| Prompt[弹窗等你确认]
    CheckAsk -->|否| CheckAllow{命中 allow?}
    CheckAllow -->|是| Run[直接执行]
    CheckAllow -->|否| ModeFallback[按权限模式默认行为]

    style Block fill:#fee2e2,stroke:#dc2626,stroke-width:2px
    style Prompt fill:#fef3c7,stroke:#d97706,stroke-width:2px
    style Run fill:#dcfce7,stroke:#16a34a,stroke-width:2px
    style ModeFallback fill:#e0e7ff,stroke:#4f46e5,stroke-width:2px

一个项目级示例：

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(git diff *)",
      "WebFetch(domain:docs.anthropic.com)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(npm publish *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Bash(wget *)"
    ]
  }
}

这份配置表达：

• lint / test / diff 可以自动做。
• push / publish 必须问。
• secrets、危险删除、直接网络拉取默认拒绝。

4. 规则语法：Tool 或 Tool(specifier)

权限规则格式只有两类：

Tool
Tool(specifier)

例子：

常见规则写法：

• Bash：匹配所有 Bash。
• Bash(*)：等价于 Bash。
• Bash(npm run build)：精确匹配该命令。
• Read(./.env)：匹配当前目录 .env。
• WebFetch(domain:example.com)：匹配 example.com 的 WebFetch。
• Agent(Explore)：匹配 Explore subagent。

Bash wildcard 细节：

• Bash(ls *)：匹配 ls -la，不匹配 lsof。
• Bash(ls*)：既可能匹配 ls -la，也可能匹配 lsof。
• Bash(ls:*)：结尾 :* 等价于尾部 *。
• Bash(git * main)：一个 * 可以跨多个参数。

5. Bash 是最容易误配的工具

Bash 不是普通工具。它可以：

• 读文件。
• 改文件。
• 删除文件。
• 联网。
• 执行脚本。
• 调 docker、npx、devbox、mise 等二级执行器。

官方文档里有几个关键事实。

复合命令会拆开检查。

这些分隔符会拆成多个子命令：

&&  ||  ;  |  |&  &  newline

规则必须匹配每个子命令。也就是说，允许 safe-cmd 不等于允许：

safe-cmd && rm -rf .

Claude Code 会剥掉部分 process wrappers。

内置识别：

timeout, time, nice, nohup, stdbuf, bare xargs

所以 Bash(npm test *) 也可能匹配：

timeout 30 npm test

但这些不在可剥离列表里：

direnv exec, devbox run, mise exec, npx, docker exec

如果你写：

Bash(devbox run *)

它可能覆盖 devbox run rm -rf .。更好的写法是精确到内部命令：

Bash(devbox run npm test)

6. Read / Edit 路径规则怎么写

Read 和 Edit 路径规则遵循 gitignore 风格，并有四类路径。

四类路径写法：

• //path：文件系统绝对路径。
• ~/path：home 目录相对路径。
• /path：project root 相对路径。
• path 或 ./path：当前目录相对路径。

最容易错的是绝对路径。

Read(/Users/alice/file)

这不是文件系统绝对路径，而是项目根目录下的 Users/alice/file。

真正的绝对路径要写：

Read(//Users/alice/file)

Windows 会被规范化成 POSIX 风格，比如：

C:\Users\alice

会变成：

/c/Users/alice

所以跨盘匹配 .env 可以用：

Read(//**/.env)

还有 symlink 规则：

symlink 规则：

• allow：symlink 路径和目标都匹配才允许，否则提示。
• deny：symlink 路径或目标任一匹配就阻止。

7. WebFetch 不等于网络隔离

WebFetch(domain:example.com) 只控制 Claude Code 的 WebFetch 工具。

它不控制 Bash 里的：

curl
wget
python -c 'requests.get(...)'
node fetch(...)

官方文档也明确提醒：using WebFetch alone does not prevent network access。

可靠做法是组合：

• WebFetch：只允许可信域名。
• Bash deny：禁止 curl、wget 等网络工具。
• PreToolUse Hook：对 Bash 里的 URL 做更细检查。
• sandbox network：从 OS / proxy 层限制网络域名。

8. MCP 和 Subagents 也要写权限

MCP server 可能连接数据库、issue 系统、云服务、浏览器和内部 API。不要因为它不是 Bash，就默认安全。

MCP 规则示例：

• mcp__github：匹配 github server 的所有工具。
• mcp__github__*：同样匹配该 server 所有工具。
• mcp__github__create_issue：只匹配一个具体工具。

更稳的做法：

• 探索型只读工具可以 allow。
• 写远端状态的工具先 ask。
• 删除、发布、授权类工具尽量 deny 或 managed。
• 不要对整个 MCP server 粗暴 allow，除非你确认所有 tool 都低风险。

Subagent 用 Agent(AgentName) 控制：

{
  "permissions": {
    "deny": ["Agent(Explore)"]
  }
}

9. sandbox（沙盒）和 permissions（权限）怎么配合

Permissions 和 sandbox 是两层。

两层边界：

• Permissions：管理所有工具，包括 Bash、Read、Edit、WebFetch、MCP、Agent。
• sandbox：管理 Bash 及其子进程的文件系统和网络访问。

官方 sandbox 文档说，sandboxed bash tool 使用 OS-level primitives：

• macOS：Seatbelt。
• Linux / WSL2：bubblewrap。

它能限制 Bash 子进程能读写哪些路径、能访问哪些网络域名。

关键交互：

• deny rules 仍然生效。
• sandbox 文件系统限制使用 Read / Edit deny rules，不是完全独立的一套文件规则。
• 网络限制组合 WebFetch permission rules 和 sandbox allowedDomains / deniedDomains。
• autoAllowBashIfSandboxed: true 默认启用时，sandboxed Bash 命令会自动允许，即使 ask: Bash(*) 存在。
• rm / rmdir 指向 /、home 或关键系统路径时仍会触发提示。

10. additionalDirectories 只加文件访问，不加完整配置根

你可以扩展 Claude Code 的文件访问范围：

claude --add-dir ../shared

会话中：

/add-dir ../shared

持久配置：

{
  "additionalDirectories": ["../shared"]
}

但官方权限文档有一个重要边界：additional directories grant file access, not configuration。

这意味着：

--add-dir 的加载边界：

• .claude/skills/：会加载，支持 live reload。
• .claude/settings.json 里的 plugin settings：只加载 enabledPlugins 和 extraKnownMarketplaces。
• CLAUDE.md / .claude/rules/ / CLAUDE.local.md：需要 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1。
• subagents / commands / output styles / hooks / 其他 settings：不会加载。

11. Managed policy：团队安全底线

团队和企业不要只靠个人自觉。

managed settings 可以强制：

• 禁止 bypass。
• 禁止 auto。
• 只允许 managed permission rules。
• 限制 MCP servers。
• 限制 channel plugins。
• 限制 marketplace。
• 只允许 managed hooks。

示例：

{
  "permissions": {
    "deny": [
      "Bash(curl *)",
      "Bash(wget *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ],
    "disableBypassPermissionsMode": "disable"
  },
  "allowManagedPermissionRulesOnly": true
}

12. 本章自检

试着用自己的话回答：

1. 权限系统管的是 Claude 的想法，还是 tool call？对应 §1。
2. default、acceptEdits、plan、auto、dontAsk、bypassPermissions 各适合什么？对应 §2。
3. 为什么 Bash(devbox run *) 比 Bash(devbox run npm test) 风险更高？对应 §5。
4. Read(//Users/alice/file) 和 Read(/Users/alice/file) 有什么区别？对应 §6。
5. WebFetch、Bash 网络命令和 sandbox 网络规则分别管什么？对应 §7-§9。

官方来源

• Configure permissions
• Choose a permission mode
• Sandboxing
• Security
• Claude Code settings

接下来去哪

如果只记一个判断：权限不是为了少弹窗，而是为了把 Claude Code 的每一次工具行动放在可解释、可审查、可强制的边界里。