Permissions¶

重要性：⭐⭐⭐ 目标读者：所有用户（必读）关联：topics/permission-system.md、topics/deep-dive-bash-permissions.md

1. 概览¶

Claude Code 工具调用必须先通过权限检查——决定 allow / deny / ask。

5 mode： - default —— 正常 - acceptEdits —— 自动接受 Edit - bypassPermissions —— 全部允许（危险） - plan —— 只读 - auto —— AI 决策

2. 5 mode 详解¶

2.1 `default`¶

// settings.json
{ "permissions": { "defaultMode": "default" } }

正常 —— 按规则。

2.2 `acceptEdits`¶

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

自动接受 Edit/Write —— 其他 ask。

2.3 `bypassPermissions`¶

{ "permissions": { "defaultMode": "bypassPermissions" } }

⚠️ 危险 —— 全部允许。

2.4 `plan`¶

{ "permissions": { "defaultMode": "plan" } }

只读 —— Edit/Write/Bash 都 ask。

2.5 `auto`¶

{ "permissions": { "defaultMode": "auto" } }

AI 决策 —— LLM classifier。

3. CLI flag¶

# 启动时指定
claude --permission-mode default
claude --permission-mode acceptEdits
claude --permission-mode bypassPermissions
claude --permission-mode plan
claude --permission-mode auto

# 临时切换（推测）
> /mode default
> /mode plan

2 种切 mode。

4. 3 种规则¶

4.1 allow 规则¶

{ "allow": ["Bash(git:*)", "Read", "WebFetch(domain:github.com)"] }

白名单 —— 总是允许。

4.2 deny 规则¶

{ "deny": ["Bash(rm -rf:*)", "WebFetch", "Read(./.env)"] }

黑名单 —— 总是拒绝。

4.3 ask 规则¶

{ "ask": ["Bash(sudo:*)", "Bash(curl:*)"] }

总是问 —— 即便白名单。

5. 5 种工具特定权限¶

5.1 Bash 权限¶

{
  "allow": [
    "Bash(git:*)",          // 前缀匹配
    "Bash(npm run:*)",     // 命令 + 第一个参数
    "Bash(grep:*)"         // 命令
  ],
  "deny": [
    "Bash(rm -rf:*)",
    "Bash(sudo:*)"
  ]
}

Bash 规则——命令 + 子命令。

5.2 Edit/Write 权限¶

{
  "allow": ["Edit", "Write"],
  "deny": ["Edit(./.env)", "Write(./secrets/**)"]
}

文件路径 匹配。

5.3 Read 权限¶

{
  "allow": ["Read(./src/**)"],
  "deny": ["Read(./.env)", "Read(~/.ssh/**)"]
}

读权限。

5.4 WebFetch 权限¶

{
  "allow": ["WebFetch(domain:github.com)"],
  "deny": ["WebFetch(domain:malicious.com)"]
}

域名匹配。

5.5 Agent 权限¶

{
  "allow": ["Agent(reviewer)"],
  "deny": ["Agent(*)"]  // 拒所有 agent
}

Agent 限制。

6. 规则匹配¶

6.1 优先级¶

deny > ask > allow

3 优先级。

6.2 通配符¶

Bash(git:*)   匹配 git status / git commit
Bash(rm *)    匹配 rm -rf /
Bash(*:*)     匹配任何

3 种。

6.3 路径¶

Read(./src/**)   匹配 src/ 下所有
Edit(./.env)     精确匹配
Write(/tmp/*)    绝对路径

3 种。

6.4 规则顺序¶

// 后面的覆盖前面
{
  "deny": ["Bash(*)"],
  "allow": ["Bash(git:*)"]  // 这个 win
}

后面覆盖。

7. 5 个实战¶

7.1 个人默认¶

// ~/.claude/settings.json
{
  "permissions": {
    "allow": ["Bash(git:*)", "Bash(npm:*)", "Read", "Edit", "Write"],
    "deny": ["Bash(rm -rf:*)", "Bash(sudo:*)", "Bash(curl:*)"]
  }
}

个人。

7.2 项目级¶

// .claude/settings.json
{
  "permissions": {
    "defaultMode": "default",
    "allow": ["Bash(docker:*)", "Read(./src/**)"],
    "deny": ["Bash(rm -rf:*)"]
  }
}

项目。

7.3 Enterprise Policy¶

// /etc/claude-code/policy.json
{
  "permissions": {
    "defaultMode": "default",
    "deny": ["Bash(*)", "WebFetch", "Read(/etc/**)"]
  }
}

企业。

7.4 临时 grant¶

# 一次性
> /allow Bash(npm:install)
# 或
> yes

临时。

7.5 撤销¶

{ "deny": ["Bash(*)", "Read", "Edit", "Write"] }

全拒。

8. UI 流程¶

8.1 默认 ask¶

> Edit src/auth.ts

Allow Edit on src/auth.ts?
  1. Yes (allow this time)
  2. Yes, and don't ask again for Edit on this file
  3. Yes, and don't ask again for Edit on this session
  4. No

Choice: 1

4 选项。

8.2 deny¶

> rm -rf /

Denied: rm -rf matches deny rule
Reason: Bash(rm -rf:*) is in deny list

deny 反馈。

8.3 bypass¶

> /permission-mode bypassPermissions

⚠️ Warning: bypassPermissions enables all tools without confirmation
Use only in trusted environments

警告。

9. 6 层决策流程¶

1. mode 检查 (bypass / plan)
  ↓
2. exact match 检查
  ↓
3. wildcard 检查
  ↓
4. sandbox auto-allow
  ↓
5. early deny
  ↓
6. semantic deny / classifier
  ↓
return allow / deny / ask

6 步。

10. Bash 特定规则¶

10.1 6 层决策¶

详见 deep-dive-bash-permissions.md。

10.2 25+ validator¶

详见 deep-dive-bash-security.md。

10.3 stripSafeWrappers¶

// time / nohup / sudo -n / env -i 等无害 wrapper

剥离。

11. 5 个最佳实践¶

deny 默认 —— 明确允许
白名单具体 —— Bash(git:*) 而非 Bash(*)
路径白名单 —— Read(./src/**)
deny 危险 —— rm -rf / sudo / curl
定期 review —— 检查 .claude/settings.json

5 条。

12. 5 个常见错误¶

12.1 太宽 allow¶

{ "allow": ["Bash(*)"] }  // ❌ 等同 bypassPermissions

太宽。

12.2 路径用绝对¶

{ "allow": ["Read(/Users/me/projects/**)"] }  // ❌ 不通用

绝对路径。

12.3 忽略 order¶

{ "allow": ["Bash(*)"], "deny": ["Bash(rm -rf:*)"] }
// deny 在 allow 之后 → win

顺序重要。

12.4 没 deny 危险¶

// ❌ 缺 deny
{ "allow": ["Bash(*)"] }

缺 deny。

12.5 mode 误用¶

{ "defaultMode": "bypassPermissions" }  // ❌ 危险

mode 误用。

13. 5 个企业级建议¶

13.1 Policy 强制¶

// /etc/claude-code/policy.json
{ "deny": ["Bash(rm -rf:*)"] }  // 不能覆盖

强制。

13.2 settings 模板¶

# 团队共享
.claude/settings.template.json

模板。

13.3 审计¶

# 定期 review
claude --debug permissions

审计。

13.4 培训¶

# 教用户模式
> /help permissions

培训。

13.5 监控¶

# logEvent 监控 deny
logEvent('tengu_permission_denied', { ... })

监控。

14. 5 个调试命令¶

14.1 debug¶

claude --debug permissions

debug。

14.2 explain¶

# 推测
> /permissions explain Bash(rm -rf /)

explain。

14.3 list¶

> /permissions list

list。

14.4 test¶

> /permissions test Bash(git status)

test。

14.5 reset¶

> /permissions reset

reset。

15. 5 个迁移步骤¶

15.1 评估¶

# 看现有规则
cat .claude/settings.json | jq '.permissions'

评估。

15.2 deny 优先¶

{ "deny": ["Bash(rm -rf:*)", "WebFetch"] }

deny。

15.3 allow 具体¶

{ "allow": ["Bash(git:*)", "Read(./src/**)"] }

allow。

15.4 mode¶

{ "defaultMode": "default" }  // 不要 bypassPermissions

mode。

15.5 测试¶

# 实际跑命令
> git status   # 允许
> rm -rf /    # 拒绝

测试。

16. 总结¶

Permissions = 多层规则 + 工具特定。

核心： - 5 mode - 3 规则（allow/deny/ask） - 6 层决策 - 5 工具特定 - deny > ask > allow 优先级

下一步： - 看 permission-system.md - 配置项目级 - 团队培训