Claude Code settings.json 详解（二）：permissions 权限系统全解析

为什么 permissions 很重要

在上一篇里，我们介绍了 Claude Code 的五层配置体系，知道了配置文件在哪里、谁说了算。这一篇聚焦 permissions 字段——它决定了 Claude 能做什么、不能做什么、以及哪些操作需要你点头。

配置对了，Claude 可以在你圈定的范围里自由发挥；配置错了，要么频繁打扰你确认，要么给了 Claude 不该有的权限。

permissions 对象的完整结构

{
  "permissions": {
    "allow": [],
    "deny": [],
    "ask": [],
    "defaultMode": "default",
    "additionalDirectories": []
  }
}

五个字段，分两类：

• 规则数组：allow / deny / ask，每个元素是一条权限规则
• 全局设置：defaultMode（默认模式）、additionalDirectories（额外目录）

规则格式：两种写法

每条权限规则都是一个字符串，格式如下：

ToolName
ToolName(content)

• ToolName：工具名称，大写开头，如 Bash、Write、Read
• (content)：可选的内容匹配部分，括号内填命令或路径模式

示例：

"allow": [
  "Bash",
  "Bash(npm install)",
  "Bash(npm run:*)",
  "Write(src/**)",
  "mcp__github__create-pull-request"
]

第一条 "Bash" 允许所有 Bash 命令，不加任何限制。第二条只允许完整匹配 npm install 这一条命令。第三条用通配符匹配所有 npm run 开头的命令。

三种规则行为

数组	效果
allow	始终允许，不弹确认框
deny	始终拒绝，Claude 直接收到拒绝响应
ask	每次执行前弹出确认框，无论 defaultMode

优先级：deny > allow > ask > defaultMode 默认行为。

常见用法——精确放行某类命令，其余均拒绝：

{
  "permissions": {
    "allow": ["Bash(npm:*)", "Bash(git:*)"],
    "deny": ["Bash"]
  }
}

先写 allow 放行 npm 和 git 相关命令，再写 deny 兜底拒绝所有其他 Bash 命令。注意顺序在逻辑上是”先匹配具体规则，再匹配宽泛规则”，而不是数组的物理顺序。

通配符语法详解

旧式：前缀匹配 prefix:*

Bash(npm:*)
Bash(git:*)
Bash(docker:*)

格式为 ToolName(prefix:*)，匹配 prefix 或 prefix <任意内容>，并且强制词边界——不会匹配 npmx 这种情况。

这是最早的通配符语法，目前仍然有效，主要用于命令行工具的主命令前缀匹配。

新式：通配符模式 *

Bash(npm * --save)
Bash(git * main)
Bash(* install)
Write(src/**/*.ts)

* 匹配任意字符序列（包括空格）。这种写法更灵活，可以匹配中间某段、结尾某段、或路径中的多级目录。

特殊行为：如果规则以 * 结尾且只有一个通配符，则这个尾部通配符是可选的。也就是说 Bash(git *) 同时匹配 git add、git checkout 和裸命令 git。

转义字符

如果命令或路径里本身包含括号或星号，需要转义：

字符	转义写法	说明
(	\(	字面左括号
)	\)	字面右括号
\	\\	字面反斜杠
*	\*	字面星号

示例：

"allow": ["Bash(python -c \"print\\(1\\)\")"]

这条规则匹配字面命令 python -c "print(1)"。

MCP 工具权限规则

MCP 工具用双下划线分隔，格式如下：

mcp__serverName
mcp__serverName__toolName

• mcp__github：允许 GitHub MCP 服务器的所有工具
• mcp__github__create-pull-request：只允许该服务器的某个具体工具
• mcp__github__*：等同于 mcp__github，明确用通配符表示”全部工具”

注意：MCP 规则不支持括号内容，写法 mcp__server(pattern) 是无效的。

defaultMode：全局默认模式

当一个操作没有命中任何 allow / deny / ask 规则时，由 defaultMode 决定默认行为：

值	行为
default	弹确认框（默认值）
acceptEdits	文件编辑类操作自动批准，命令执行仍弹框
bypassPermissions	跳过所有权限检查，完全自动化（需要满足特定条件才能开启）
dontAsk	自动批准所有操作，不弹任何确认框
plan	仅规划模式，不执行任何写操作

推荐搭配：

开发阶段可以用 acceptEdits，让 Claude 自由读写文件，但执行 shell 命令前还是要确认；如果是在 CI/自动化环境中运行，可以搭配精细的 allow 规则 + dontAsk，实现全自动。

additionalDirectories：扩展可访问目录

默认情况下，Claude Code 只能访问当前工作目录及其子目录。additionalDirectories 可以额外授权其他路径：

{
  "permissions": {
    "additionalDirectories": ["/Users/yourname/shared-libs", "/var/log/myapp"]
  }
}

常见用途：monorepo 中跨子包访问、读取项目外的共享配置文件、查看系统日志等。

路径数组遵循上一篇介绍的合并规则：多层配置的 additionalDirectories 会拼接在一起，而不是互相覆盖。

规则来源与可编辑性

权限规则可以来自不同的配置来源（见第一篇），但并非所有来源都允许修改：

来源	是否可编辑	说明
userSettings	是	~/.claude/settings.json
projectSettings	是	.claude/settings.json
localSettings	是	.claude/settings.local.json
policySettings	否（只读）	企业管理员下发的策略，不可覆盖
flagSettings	否（只读）	CLI 启动参数或环境变量，只读

企业场景下，管理员可以通过 policySettings 强制锁定某些权限规则，员工的个人配置无法绕过。

几个实用配置示例

只允许 npm 和 git，拒绝其他 Bash：

{
  "permissions": {
    "allow": ["Bash(npm:*)", "Bash(git:*)"],
    "deny": ["Bash"],
    "defaultMode": "default"
  }
}

允许在 src 目录内自由写文件，但写 src 之外需确认：

{
  "permissions": {
    "allow": ["Write(src/**)"],
    "defaultMode": "default"
  }
}

CI 环境全自动运行：

{
  "permissions": {
    "allow": ["Bash", "Write", "Read"],
    "defaultMode": "dontAsk"
  }
}

保护特定命令，强制每次确认：

{
  "permissions": {
    "ask": ["Bash(sudo *)"],
    "allow": ["Bash(npm:*)", "Bash(git:*)"]
  }
}

小结

permissions 是 Claude Code 配置里最值得花时间搞清楚的字段。核心逻辑很简单：

• 用 allow / deny / ask 三个数组圈定规则
• 规则支持精确匹配、前缀通配（prefix:*）、模式通配（*）
• MCP 工具用双下划线格式，不支持括号内容
• defaultMode 处理没有命中规则的情况
• additionalDirectories 扩展可访问目录

下一篇会介绍 hooks——如何在 Claude 执行工具前后自动触发你的 shell 脚本，实现更深层的自动化控制。