Claude Code settings.json配置教程：权限、Hooks、MCP与团队共享

从用户、项目和本机三层拆解 Claude Code 配置，讲清权限规则、敏感文件保护、Windows Hooks、MCP 作用域与团队渐进发布。附可解析的 JSON 示例、只读检查清单和保护脚本。

配置的目标不是“少弹几个确认框”，而是把边界写清楚。共享规则只放团队都认可的底线，本机偏好留在 local 文件；敏感路径先 deny，高风险动作保留 ask；Hook 负责确定性的检查，MCP 只接经过审查的系统。

先看全局：Claude Code 配置不止一个文件

很多配置事故不是 JSON 写错，而是写到了错误作用域。根据当前官方设置文档，用户设置、共享项目设置和本机项目设置分别解决不同问题。先决定“谁需要这条规则”，再决定写在哪个文件。

位置	适合放什么	是否进 Git
~/.claude/settings.json	自己所有项目通用的偏好与个人工具	否
.claude/settings.json	团队共享的权限底线、Hook 和项目插件配置	是，需审核
.claude/settings.local.json	当前机器的个人允许项、试验配置	否，应忽略
.mcp.json	项目级 MCP 服务定义	可共享，但不能含密钥
托管设置	组织强制策略	由管理员控制

权限的优先级还要单独理解：官方规则按 deny → ask → allow 评估，任何作用域命中的 deny 都不能被更具体的 allow 覆盖。换句话说，团队底线应该写成 deny；个人便利项才适合放 allow。

最小起步：先写共享底线，不要先放开全部命令

第一版共享设置只需要做两件事：拦住敏感文件，把提交、推送和发布保留为人工确认。不要因为经常运行测试，就顺手允许全部 Bash；工具级宽泛 allow 会把以后新增的危险命令也一起放开。

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "defaultMode": "default",
    "ask": [
      "Bash(git commit *)",
      "Bash(git push *)",
      "Bash(npm publish *)"
    ],
    "deny": [
      "Read(./.env)",
      "Edit(./.env)",
      "Read(./secrets/**)",
      "Edit(./secrets/**)",
      "Bash(git push --force *)"
    ]
  }
}

$schema 能让支持 JSON Schema 的编辑器提示字段和结构问题；它不是安全扫描器。保存后先运行 claude doctor，再用 /permissions 查看每条规则来自哪个文件，不能只看磁盘上的 JSON 猜测是否已加载。

权限规则怎么写：用 deny 守底线，用 ask 留确认

官方权限文档区分三种行为：allow 直接允许匹配动作，ask 每次要求确认，deny 阻止动作。规则可以匹配整个工具，也可以带参数范围。这里有三个容易踩的坑：

1. 不要裸写 Bash 到 deny：这会让整个工具从上下文中消失。若只想拦危险命令，应写带范围的规则。
2. 不要指望“更具体的 allow”覆盖 deny：规则不是按精确度优先，deny 始终先评估。
3. 不要把提示词当权限：CLAUDE.md 可以说明“不要读取 .env”，但真正的访问控制必须落在 permissions 或 Hook。

实用做法是从操作结果反推：读取普通源码可保持默认；提交和推送会改变协作状态，放 ask；强制推送、发布、读写凭据路径直接 deny。项目稳定后再逐条增加精确 allow，并由团队审核 diff。

敏感文件保护：Read 和 Edit 要同时考虑

只禁止读取 .env 还不够，工具仍可能创建或覆盖同名文件。共享模板应同时覆盖 Read 与 Edit，并根据仓库实际补上 secrets/、凭据 JSON、私钥、生产配置和备份目录。

"deny": [
  "Read(./.env)",
  "Read(./.env.*)",
  "Edit(./.env)",
  "Edit(./.env.*)",
  "Read(./secrets/**)",
  "Edit(./secrets/**)",
  "Read(./**/*.pem)",
  "Edit(./**/*.pem)"
]

这仍然不是完整的数据防泄漏方案：权限控制 Claude Code 工具的访问，操作系统沙箱控制 Bash 子进程的文件和网络边界。官方沙箱说明建议把两层结合使用。对客户数据、生产凭据和合规项目，应继续使用独立测试账号、最小权限凭据和系统级隔离。

Hooks 适合做什么：把确定性检查放到生命周期里

Hook 会在指定事件发生时执行命令。它适合格式化、通知、保护路径和审计等确定性动作；不适合把模糊业务判断塞进一段难维护的正则。官方Hooks 指南明确区分命令 Hook、提示词 Hook和 Agent Hook，复杂度应从最低的一层开始。

需求	优先方案	原因
编辑后格式化	PostToolUse 命令 Hook	输入和结果确定
禁止改凭据文件	permissions deny + PreToolUse Hook	权限守底线，Hook 补动态检查
等待确认时通知	Notification Hook	不改变工具结果
判断测试是否真的通过	测试命令或 Agent Hook	需要读取实际状态
是否应该上线	人工验收	涉及业务风险与责任

Hook 命令来自配置文件，也会执行本机程序，所以从陌生仓库拉下来的 Hook 必须像构建脚本一样审查。不要因为它位于 .claude/ 就默认可信。

Windows 示例：在写入前拦住受保护路径

资源包中的 PowerShell 脚本从标准输入读取 Hook JSON，检查 tool_input.file_path，命中 .env、secrets/、私钥或 .git/ 时向标准错误写原因并返回退出码 2。脚本不修改文件，也不记录完整输入。

"hooks": {
  "PreToolUse": [
    {
      "matcher": "Edit|Write",
      "hooks": [
        {
          "type": "command",
          "command": "powershell.exe -NoProfile -ExecutionPolicy Bypass -File .claude/hooks/protect-sensitive-files.ps1"
        }
      ]
    }
  ]
}

matcher 应是字符串，多个工具用 Edit|Write。数组会造成结构错误；拼错工具名则可能静默匹配不到。保存后运行 /hooks，确认事件、matcher、来源和命令都出现，再用一个测试文件验证。完整输入输出字段应以Hooks 参考为准。

MCP 怎么分作用域：先接一个只读测试系统

MCP 能把 Claude Code 连接到 Issue、监控、数据库和设计工具，但每增加一个服务，都增加新的凭据、网络和提示注入边界。官方MCP 文档提供 local、project 和 user 三种作用域；团队共享通常放项目级 .mcp.json，个人或实验服务留在本机。

1. 先确认服务发布者、传输地址和需要的权限，不从随机文章复制未知命令。
2. 优先连接测试组织、只读数据库或低权限账号，不直接给生产写权限。
3. 项目配置不写 Token、Cookie、密码或数据库连接串；凭据走服务支持的 OAuth 或本机环境。
4. 添加后用 claude mcp list 和 /mcp 检查状态、审批与工具数量。
5. 先完成一个最小读取任务，再评估是否允许写操作。

项目级服务需要一次性信任确认；“已连接但工具数为 0”不等于可用。相对命令路径还会按启动 Claude Code 的目录解析，不一定按 .mcp.json 所在位置解析。排错时先取证，不要不断重装。

团队共享流程：从一台测试机逐步推广

配置是代码，也应走小步发布。一个稳妥顺序是：

1. 建立基线：备份文件，记录 /status、/permissions、/hooks 和 /mcp。
2. 只加 deny：在测试仓库确认敏感读取和写入被拦截。
3. 再加 ask：确认提交、推送、发布仍需要人工决定。
4. 启用一个 Hook：验证正常文件放行、受保护文件阻断、异常输入默认安全失败。
5. 接一个 MCP：只用测试账号完成最小任务。
6. 审查 diff：团队确认规则范围、Hook 命令和回滚步骤后，再提交共享文件。

不要把所有人的个人 allow 合并进共享设置。共享文件越宽松，后来维护者越难判断一条命令为什么无需确认；本机偏好留在 settings.local.json，既能提高效率，也不改变其他人的安全边界。

怎么验证：语法、加载、行为三层都要过

只做 JSON 校验远远不够。完整验收分三层：

层级	检查	通过标准
语法	ConvertFrom-Json、claude doctor	文件可解析，无设置结构报错
加载	/status、/permissions、/hooks、/mcp	来源、规则、Hook 和服务都符合预期
行为	测试允许、询问、拒绝、Hook 与 MCP 最小任务	每条规则都产生预期结果

资源包的清单把这三层拆成可勾选步骤。请在无真实密钥、无客户数据的测试仓库执行；测试通过后也要保留人工确认的发布和生产变更门槛。

常见故障：先用安全模式判断是不是配置引起

官方配置排错文档给出一条很实用的分界线：运行 claude --safe-mode，临时禁用用户和项目中的自定义设置、Hooks、MCP、插件等。如果安全模式正常，问题大概率在自定义层；如果仍异常，再转向安装、账号、网络或托管策略。

• 整个文件被拒绝：先跑 JSON 解析和 claude doctor，不要删掉全部配置重来。
• Hook 不出现：检查是否放在 settings 的 hooks 键下，以及 matcher 是否为字符串。
• Hook 出现但不触发：用 claude --debug hooks 看实际事件和工具名。
• MCP 启动失败：用 claude mcp get <name> 和 claude --debug mcp 查看命令、路径和标准错误。
• MCP 连接但无工具：在 /mcp 重连；仍为 0 时检查服务是否真正返回工具列表。

这套配置和完整工作流怎么配合

配置解决“能做什么、何时检查、连接哪些系统”；任务流程解决“先理解什么、如何计划、怎么验证”。第一次使用建议先完成Claude Code Windows 安装排错，再按Claude Code 完整工作流教程建立项目记忆、Plan Mode、最小改动和测试闭环，最后用本文模板固定权限与自动检查。

三者顺序不能倒：程序还没稳定时不要堆 Hooks；工作流没跑通时不要一次接多个 MCP；团队边界没讨论清楚时不要共享宽泛 allow。每次只改变一个变量，出现问题才有可回退的证据。

资源包包含什么

• 共享 settings 示例：敏感路径 deny、高风险动作 ask、Windows PreToolUse Hook。
• 本机 settings 示例：仅包含 git status、diff、log 等精确只读允许项。
• 项目 MCP 结构：不含密钥的 HTTP 服务占位模板，要求先替换并审查。
• PowerShell 保护脚本：只读取 Hook 输入，拦截敏感路径，不记录完整请求。
• 渐进发布清单：覆盖基线、语法、行为、安全和回滚。
• 故障对照 CSV：从现象映射到验证命令和处理方向。

下载说明：正文可以直接阅读；ZIP 模板包免费注册后下载，登录后会回到本资源。示例遵循最小权限起步，但必须按你的仓库、操作系统和组织策略复核，不能直接替代安全评审。

参考资料

本文于 2026 年 7 月按 Anthropic Claude Code 当前官方设置、权限、Hooks、MCP 与排错文档核对。Claude Code 更新较快，字段、作用域和命令行为可能变化；落地前请以官方最新页面和本机 claude doctor 结果为准。

• Claude Code 设置文件与作用域
• Claude Code 权限规则
• Claude Code Hooks 实操指南
• Claude Code Hooks 参考
• Claude Code MCP 配置
• Claude Code 配置排错
• Claude Code 沙箱说明
• Claude Code settings.json JSON Schema