Claude Code 权限和工具 Allowlist

配置 Claude Code permission modes、allowed tools、deny rules、MCP tools、Shell 命令模式和更安全的自动化流程。

Claude Code 权限决定哪些工具可以运行，以及 Claude 在行动前什么时候需要请求确认。把 allowlist 当成工作流边界，而不是单纯的效率开关。目标是让 Claude Code 足够高效，同时让风险动作可见、可审查、可回退。

快速结论

permission mode 控制整体工作流，tool rules 控制具体可用工具。敏感任务建议用 plan 模式加只读工具；无人值守自动化建议使用明确 allowlist，并为绝不应运行的操作添加 deny 规则。

需求	推荐配置
理解代码库	`plan` 模式加读取和搜索工具。
小功能开发	允许读取、编辑、测试、`git status` 和 `git diff`。
CI 或 PR 摘要	print mode 加窄 allowlist。
认证、计费、迁移、部署	先用 `plan`，再逐步批准实现。
MCP 访问	尽量授权精确的 `mcp__server__tool` 名称。
高风险操作	添加 deny 或 disallowed 规则，而不是只依赖未加入 allowlist。

Permission Modes 和 Tool Rules 的区别

控制项	作用
Permission mode	控制整个会话的审批行为。
Allowed tools	预批准特定工具或命令模式。
Deny 或 disallowed tools	阻止工具或模式，通常在 mode 审批前生效。
Sandbox settings	为 shell 命令和子进程增加操作系统级限制。
Managed settings	让组织统一管控多台机器的策略。

官方文档里的关键点是：allow rules 主要是预批准匹配工具，真正阻止工具要靠 deny 或 disallowed rules。不要以为某个工具没写进 allowlist，就一定不可用。

Settings 优先级

Claude Code 会从多个位置读取 settings。permissions.defaultMode 这类标量配置按下面优先级覆盖：

优先级	来源	含义
1	Managed settings	组织策略，不能被其他层级覆盖。
2	命令行参数	当前会话的临时覆盖。
3	Local project settings	`.claude/settings.local.json`，当前仓库个人配置。
4	Shared project settings	`.claude/settings.json`，提交给团队共享。
5	User settings	`~/.claude/settings.json`，个人全局默认配置。

数组配置不一样。permissions.allow、permissions.ask、permissions.deny 这类权限数组会跨 scope 合并并去重，而不是互相替换。很多 sandbox filesystem 数组也遵循合并规则。可以用 /status 查看当前会话加载了哪些 settings 来源。

权限规则本身也有匹配顺序：先检查 deny，再检查 ask，最后检查 allow。第一个命中的规则生效。

常见 Permission Modes

模式	适合场景	注意点
`default`	日常交互开发	敏感动作仍可能要求确认。
`plan`	研究、架构、代码审查、高风险改动	只做只读规划，不做实现。
`acceptEdits`	可信工作目录里的快速编码	不会自动批准所有 MCP 工具。
`dontAsk`	固定工具面的自动化	未预批准的内容会被拒绝。
`auto`	环境支持时的模型分类审批	行为取决于当前环境。
`bypassPermissions`	一次性隔离沙箱	不要用于普通工作站或生产仓库。

Sandbox 和 Permissions 的边界

permissions 决定工具调用能不能运行、是否需要 Claude Code 先询问。sandbox 则是在 Bash 命令启动之后，限制这个命令和子进程能访问哪些文件和网络。

控制项	覆盖范围	单独使用时不覆盖什么
Permission rules	工具审批、`Read`、`Edit`、`Bash`、`WebFetch`、MCP tool 名称。	子进程的操作系统级隔离。
Bash sandbox	Bash 命令和子进程，以及文件系统和网络边界。	内置文件工具、MCP servers、hooks、computer use。
Sandbox runtime / VM	按这种方式配置时，可以覆盖整个 Claude Code 进程。	审批策略本身，仍需要 permission modes 配合。

在 auto-allow sandbox 模式下，符合 sandbox 边界的 Bash 命令可以不逐条提示就运行，但显式 deny rules 仍会生效。无法在 sandbox 内运行的命令会回到常规 permission flow，除非 strict sandbox 设置禁用了这个逃生口。

实用 Allowlist 示例

只读探索

用于让 Claude Code 梳理仓库，不修改代码：

{
  "permissions": {
    "defaultMode": "plan",
    "allow": ["Read", "Glob", "Grep", "LS"]
  }
}

小功能开发

允许项目读取、编辑、测试和安全 Git 检查：

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "LS",
      "Edit",
      "Bash(npm test)",
      "Bash(npm run build)",
      "Bash(git status)",
      "Bash(git diff)"
    ],
    "deny": ["Bash(sudo *)", "Bash(rm -rf *)"]
  }
}

PR 摘要自动化

print mode 搭配窄工具面：

claude -p "Summarize this pull request and list test risks" \
  --allowedTools "Read,Glob,Grep,LS,Bash(git diff:*)" \
  --permission-mode plan

中文团队起步配置

下面是一份适合普通产品仓库的团队默认配置：默认先进入 plan 模式，允许读取、搜索、编辑、测试和安全 Git 检查，同时明确禁止提权、危险删除、发包和部署命令。

{
  "permissions": {
    "defaultMode": "plan",
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "LS",
      "Edit",
      "Bash(npm test)",
      "Bash(npm run build)",
      "Bash(git status)",
      "Bash(git diff)"
    ],
    "deny": [
      "Bash(sudo *)",
      "Bash(rm -rf *)",
      "Bash(npm publish *)",
      "Bash(wrangler deploy *)"
    ]
  }
}

这类配置适合放进 .claude/settings.json 作为团队共享规则。个人临时放宽权限时，优先写进 .claude/settings.local.json，不要把个人实验权限提交给团队。对认证、支付、数据库、部署这类任务，即使已有 allowlist，也建议先用 plan 模式确认影响范围。

MCP 工具 Allowlist

MCP tools 通常使用这样的名称：

mcp__github__list_issues
mcp__context7__resolve_library_id

对于可写服务，优先使用精确工具名：

{
  "permissions": {
    "allow": [
      "mcp__github__list_issues",
      "mcp__github__get_pull_request",
      "mcp__context7__*"
    ]
  }
}

只有当整个 server 都适合当前会话时，才使用通配符。文档查询 server 和 GitHub、Slack、数据库、部署 server 的风险等级完全不同。

Shell 命令规则

Shell 模式应该尽量具体：

过宽写法	更安全写法
`Bash(*)`	`Bash(npm test)`
`Bash(git *)`	`Bash(git status)`, `Bash(git diff)`
`Bash(npm *)`	`Bash(npm run build)`, `Bash(npm test)`
`Bash(rm *)`	通常 deny，需要时单次手动批准。

如果命令会删除文件、改凭证、发布包、部署或修改基础设施，就不要放进默认 allowlist。

团队策略清单

共享权限默认保持收敛。
对绝不应无人值守运行的操作添加 deny 规则。
认证、支付、数据库、部署和跨模块重构优先使用 plan。
提交 .claude/settings.json 或项目设置前先审查。
记录允许的 MCP server 和 token scope。
一次性任务优先临时批准。
组织级强管控使用 managed settings。

常见错误

把 allow rules 或 --allowedTools 当成完整安全边界。
bypassPermissions 搭配小 allowlist，还以为 allowlist 会限制它。
为了省事开放宽泛 shell 模式。
只读任务却给了可写 MCP 工具。
把个人实验权限提交成团队默认配置。

官方来源

下一步：GitHub CLI 集成 - 在不扩大权限面的前提下接入 GitHub 工作流。