Logo Vincent
返回文章列表

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

Claude
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 脚本，实现更深层的自动化控制。

更多同类文章

© 2026 vincentqiao.com . 保留所有权利。