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 默认行为。

Permission Check Flow

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

{
  "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 会拼接在一起，而不是互相覆盖。

规则来源与可编辑性

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

Rule Sources & Priority

来源是否可编辑说明
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 脚本，实现更深层的自动化控制。

相关推荐

AI-first 创业公司，为什么只需要一种编程语言？

技术架构越简单 = AI Coding 效率越高。从 Java 的"防人"设计到 TypeScript 全栈通吃，聊聊 AI 时代创业公司的编程语言选择。

cc-ping：一行命令 Ping 所有 Claude Code 配置

用多个 Claude Code API Key 或中继？cc-ping 帮你管理配置、一键切换，还能并行 Ping 所有节点比速度。

震惊！程序员用这个工具，4分钟干完95分钟的活！效率暴涨24倍

躺床上发3条消息，4分钟搞定3个项目。传统方式需要95分钟，这就是冷兵器和热兵器的差距。

CCBot - 研发提效 24 倍

通过 IM 机器人控制 Claude Code，3 个项目 4 分钟全部搞定。传统编程需要 95 分钟，效率提升 24 倍。

Claude Code /add-dir：被低估的 Monorepo 神器

Claude Code 默认只能看到当前目录。/add-dir 打破这个限制——分享我每天跨 5 个仓库使用的经验。

Claude Code 省 Token 小技巧：感叹号的妙用

一个简单却容易被忽略的技巧——用感叹号直接执行命令，省 token、提速度、更可控。

我做了个机器人，让团队在飞书里用 Claude Code

CCBot 让你的团队在飞书群聊里直接用 Claude Code——不需要终端、不需要 SSH。开源、自部署、五分钟搞定。

Claude Code /btw 命令详解：不打扰主线的快问快答

详细介绍 Claude Code 的 /btw 命令——它是什么、怎么用、什么时候该用，以及它和子代理、/compact 的区别。

Claude Code /compact：释放上下文，不丢进度

任务做到一半上下文满了？/compact 帮你压缩对话继续干活——和 /clear、/rewind 的区别一次讲清。

Claude Code /config：一文搞懂所有可调设置

用 Claude Code 却从没打开过 /config？这篇带你逐项拆解——从权限模式到自动压缩，从主题切换到通知配置，帮你打造最顺手的 AI 编程环境。

Claude Code /context：你的上下文都被什么吃了？

对话到一半 Claude Code 说上下文不够了？/context 用一张可视化网格告诉你：上下文被什么占了、占了多少、怎么优化。

Claude Code /diff：这次对话改了什么，一目了然

Claude Code 帮你改了一堆文件，但你不确定到底改了什么？/diff 用交互式界面展示所有改动——既有 git 视角的全量 diff，也有按对话轮次拆分的逐步 diff。

Claude Code /fast：同样的 Opus，两倍速——值不值？

/fast 不会降级模型，还是 Opus，只是更快。什么时候该开、什么时候该关，以及实际体验差异。

Claude Code 引用外部知识的最佳实践：GitHub MCP + Context7

用 GitHub MCP 和 Context7 MCP 两个工具组合，解决 Claude Code 知识过时导致的代码错误问题。

Claude Code /hooks：让 AI 按你的规矩办事

想在 Claude Code 执行命令前自动检查？想在任务完成后自动通知？/hooks 让你用脚本、AI 甚至 HTTP 请求，在关键节点插入自定义逻辑。

Claude Code /init：10 秒自动生成 CLAUDE.md

别再手写 CLAUDE.md 了。看看 /init 自动生成的效果、怎么自定义输出，以及一个让 Claude Code 效率翻倍的小技巧。

Claude Code MCP：让 AI 连接 GitHub、数据库等一切工具

MCP 把 Claude Code 从代码阅读器升级为全栈 Agent。哪些 MCP 服务器值得装、配置怎么写，实测分享。

Claude Code /memory 详解：让 AI 真正记住你的项目

详细介绍 Claude Code 的 /memory 命令和记忆系统——CLAUDE.md 手动指令、Auto Memory 自动记忆、模块化规则，让 Claude 跨会话记住项目规范和个人偏好。

Claude Code /model：Opus、Sonnet、Haiku 怎么选？

不是每个任务都需要 Opus。怎么切换模型、哪个场景用哪个、怎么省 token 又不掉质量。

Claude Code /permissions：谁能干什么，你说了算

每次 Claude Code 要跑命令都弹窗问你？嫌烦又不敢全放开？/permissions 帮你精细控制每个工具的权限——该放的放，该拦的拦。

Claude Code /plan 详解：先想清楚再动手

详细介绍 Claude Code 的 /plan 命令和 Plan Mode——只读规划模式，让 Claude 先分析代码、制定方案，确认后再动手，避免复杂任务翻车。

Claude Code + Playwright MCP：AI 终于能"看见"页面了

一个 Modal 溢出的 bug，Claude Code 反复修了 5 次都没搞定。直到接入 Playwright MCP 让它真正看到页面，一次定位，一次修复。

Claude Code /resume 命令详解：别让对话白聊

详细介绍 Claude Code 的 /resume 命令——恢复历史对话、管理会话、实用技巧，让你的每一轮对话都不浪费。

Claude Code /review：让 AI 帮你做 Code Review

提了 PR 没人看？想在合并前多一道把关？/review 让 Claude Code 像一个资深开发者一样审查你的代码——还有 /ultrareview 和 /security-review 两个进阶选择。

Claude Code Skills 详解：打造你的专属命令库

详细介绍 Claude Code 的 Skills 功能——创建自定义斜杠命令、复用提示词模板、共享团队最佳实践，让 AI 编程更高效更一致。

Claude Code /stats：看看 AI 到底帮你写了多少代码

好奇 Claude Code 到底写了多少行代码？/stats 给你完整数据——token、编辑次数、工具调用，教你怎么看。

Claude Code /status 命令详解：一眼看清会话全貌

详细介绍 Claude Code 的 /status 命令——它是什么、怎么用、能看到哪些信息，以及它在日常工作流中的实际价值。

Claude Code /tasks 命令详解：后台任务尽在掌控

详细介绍 Claude Code 的 /tasks 命令——查看后台任务、管理并行 Agent、掌控长时间运行的进程，让多任务开发井井有条。

Claude Code /usage 命令详解：你的额度还剩多少

详细介绍 Claude Code 的 /usage 命令——查看用量、了解限额、避免突然被限速，让你对自己的额度心中有数。

Claude Code /vim：在 AI 编程助手里用 Vim 键位

习惯了 Vim 的操作方式？/vim 让你在 Claude Code 的输入框里用 hjkl 移动、dd 删行、ciw 替换单词——不用改变肌肉记忆。

Claude Code 使用指南：从安装到实战，一篇就够（2026）

用了半年 Claude Code 的经验总结——5 分钟安装配置、最常用的命令、CLAUDE.md 编写技巧，以及没人告诉你的实战心得。

Claude 全家桶：从聊天到写代码到自动办公，一文讲清楚

一篇文章带你了解 Anthropic 的 Claude 全家桶——Claude.ai、Claude Code、Claude Cowork，以及 Opus、Sonnet、Haiku 三大模型家族。

Claude Code /agents 详解：自定义 AI 子代理，各司其职

详细介绍 Claude Code 的 /agents 命令——查看、管理和创建自定义 Agent，让不同任务由专门的 AI 角色来执行，从代码探索到架构规划各司其职。

Claude Code /doctor 详解：一键诊断你的开发环境

详细介绍 Claude Code 的 /doctor 命令——自动检测安装状态、API 连接、MCP 配置、上下文用量等问题，帮你快速定位和修复环境故障。

Claude Code /effort 详解：控制 AI 思考的深度

详细介绍 Claude Code 的 /effort 命令——调节 Claude 的推理努力程度，在速度和质量之间找到最佳平衡点，让每一次对话都恰到好处。

Claude Code /cost 详解：你的 AI 编程到底花了多少钱

详细介绍 Claude Code 的 /cost 命令——实时查看会话 API 成本，了解各模型定价和 Token 消耗明细，让每一分钱都花得明明白白。

Claude Code /export 详解：把 AI 对话带走

详细介绍 Claude Code 的 /export 命令——将对话导出为文件或复制到剪贴板，方便分享、存档和复盘，让每一次有价值的对话都不浪费。

Claude Code /rewind 详解：AI 改错了？一键回退

详细介绍 Claude Code 的 /rewind 命令——将代码和对话回退到任意历史节点，支持只回退代码、只回退对话、或两者同时回退，是你和 AI 协作时的后悔药。

Claude Code /plugin 详解：给你的 AI 编程助手装插件

详细介绍 Claude Code 的 /plugin 命令——管理插件的安装、启用、禁用和更新，通过插件扩展 Claude Code 的命令、技能、Agent 和 Hook，打造你专属的 AI 编程工具链。

Claude Code /theme 详解：给你的终端换个好看的皮肤

详细介绍 Claude Code 的 /theme 命令——6 种预设主题 + 自动模式，支持深色/浅色、色盲友好、ANSI 兼容，60+ 色值覆盖终端全部 UI 元素。

Claude Code /insights 详解：用 AI 分析你自己用 AI 的方式

详细介绍 Claude Code 的 /insights 命令——五阶段数据分析流水线、七大洞察章节、多维度会话统计，用 Claude Opus 生成专属 HTML 使用报告。

Claude Code /rename 详解：给你的会话取个有意义的名字

详细介绍 Claude Code 的 /rename 命令——手动命名、AI 自动生成（Haiku 模型）、启动参数命名、Plan 模式自动命名，以及双标题系统与 Bridge 同步机制。

Claude Code settings.json 配置详解：5 层优先级、3 种文件路径，一篇搞懂

Claude Code 的 settings.json 到底放哪里？用户级、项目级、本地级有什么区别？什么是 managed-settings.json？一篇讲清 5 层配置的优先级规则、合并逻辑和实际使用场景。

Claude Code settings.json 详解（三）：hooks 钩子全解析

深入解析 Claude Code 的 hooks 配置——四种钩子类型、核心事件（PreToolUse/PostToolUse/Stop/Notification）、stdin/stdout 协议、exit code 语义，以及实用配置示例。

Claude Code settings.json 配置模板：env、模型、认证等实用字段速查

Claude Code settings.json 常用字段速查表：env 环境变量、模型切换、apiKeyHelper 动态认证、Git 署名、思考深度、语言与界面、自动更新等，附可直接复制的配置示例。

Claude Code Agent Loop：拆解 AI 编程助手的心脏

Claude Code 是怎么一步步理解你的需求、调用工具、自我修复的？从源码角度拆解 Agent Loop 的核心架构——流式响应、并行工具执行、自动压缩、错误恢复，一次讲透。

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