Claude Code settings.json 配置教程详解

同一个 spinnerTipsEnabled，写进用户级文件后所有项目都会生效，写进项目级文件后却可能被本机的 local 配置覆盖。配置 Claude Code 时，先决定作用域，再写 JSON，能避开“文件格式正确但实际没有采用”的常见误判。

完成后，你应当拥有一份位置明确、语法有效、权限边界清楚的 settings.json，并能在 Claude Code 的 /status 页面看到对应的 Setting sources。示例适用于 Windows、macOS 和 Linux，不要求把个人路径、密钥或机器专属命令提交到项目仓库。

先定作用域，再动文件。

先决定配置是个人使用还是团队共享

1. 为当前设置选择 User、Project 或 Local 作用域。

   入口位置：Claude Code 官方 Settings 页的 Configuration scopes 与 Available scopes 区域。

   主要动作：个人在所有项目共用的偏好选 User；需要随仓库提交并给团队共用的规则选 Project；只在当前仓库、本机生效的试验配置选 Local。组织统一下发且不能被个人覆盖的策略属于 Managed，不要把它当作普通个人配置修改。

   成功标志：能用一句话说明谁会受该设置影响、是否应提交到版本控制，以及它是否只属于当前机器。

   失败处理：无法判断时先用 Local 做小范围验证。涉及团队权限、Hooks 或共同工具链时，再由团队确认后迁移到 Project。

看图中的 Scope、Location、Who it affects 和 Shared with team 四列。选中的行应同时符合影响范围和共享要求；若两项互相矛盾，说明作用域选错了。

把 settings.json 放到正确目录

2. 创建目标作用域对应的配置文件。

   入口位置：个人配置目录或项目根目录。macOS 与 Linux 的用户级路径是 ~/.claude/settings.json；Windows 对应 %USERPROFILE%.claudesettings.json。项目共享文件是仓库根目录下的 .claude/settings.json，本机项目文件是 .claude/settings.local.json。

   主要动作：先备份已有文件，再创建缺失的 .claude 目录和目标 JSON 文件。手动创建 settings.local.json 时，把它加入 .gitignore；由 Claude Code 创建时，程序会配置忽略规则。

   成功标志：文件名、扩展名和目录层级完全正确；Project 文件可按团队要求进入版本控制，Local 文件不会出现在待提交列表。

   失败处理：Windows 若误建成 settings.json.txt，先显示文件扩展名再重命名。项目文件没有生效时，确认当前目录处于仓库内，并从仓库根目录检查 .claude。

图中 Settings files 区域把三个常用路径并排列出。看到 User settings、Project settings 与 settings.local.json 的说明，说明当前查的是正式配置位置；若文件放在其他目录，先移动到对应作用域。

先写一份容易验证的最小配置

3. 写入权限边界和两个可观察偏好。

   入口位置：刚创建的目标 settings.json 文件。

   主要动作：用下面的最小示例开始。allow 放可直接执行的低风险命令，ask 放每次需要确认的动作，deny 阻止读取敏感文件。示例还开启自动压缩，并关闭终端中的提示语。

   成功标志：编辑器把内容识别为 JSON；对象括号配对，末尾数组项和末尾键值后没有多余逗号。

   失败处理：不要在 JSON 中写注释。复制后若出现红色波浪线，先检查全角引号、漏逗号、尾随逗号和错误的反斜杠转义。

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "autoCompactEnabled": true,
  "spinnerTipsEnabled": false
}

deny 的判断顺序高于 ask 和 allow。规则写成 Tool 或 Tool(specifier)；不要用一个宽泛的 allow 抵消敏感文件的 deny。

保存前先做 JSON 语法检查

4. 用系统现有工具解析配置文件。

   入口位置：终端或 PowerShell，当前路径指向配置文件所在目录。

   主要动作：macOS 与 Linux 可运行 python3 -m json.tool settings.json；Windows PowerShell 可运行 Get-Content .settings.json -Raw | ConvertFrom-Json | Out-Null。项目文件应把命令中的文件名换成实际相对路径。

   成功标志：Python 输出格式化后的 JSON，或 PowerShell 安静返回且没有异常。

   失败处理：按错误中的行号定位。解析错误通常来自缺少逗号、引号不配对或把路径反斜杠写成单个转义字符；修复后重新运行，直到解析器通过。

分清热重载与下次启动生效

5. 保存后按设置类型决定是否重启会话。

   入口位置：Claude Code 正在运行的会话，以及官方 Settings 页的 When edits take effect 区域。

   主要动作：大多数键会在文件变化后重新加载，权限、Hooks 和凭据辅助程序也在此范围内。model 与 outputStyle 等少数键需要切换命令、清空会话或重新启动后才完整应用。

   成功标志：普通偏好保存后在当前会话出现预期变化；属于启动期的键在重启或按官方说明切换后生效。

   失败处理：不要连续修改多个作用域来碰运气。先保持 JSON 语法有效，再重启一次；仍无变化时进入下一步查看实际加载来源。

图中第一段说明大多数设置会自动重新加载，下面单独列出需要下次启动处理的例外。当前会话出现变化就是成功信号；若例外键没有变化，先按页面提示切换或重启。

6. 排查同名键被更高优先级覆盖。

   入口位置：官方 Settings 页的 Settings precedence 区域，以及本机各层配置文件。

   主要动作：按 Managed、命令行参数、Local、Project、User 的顺序检查同名键。普通标量由高优先级覆盖低优先级；权限规则会跨作用域合并，不能只看单个文件。

   成功标志：能指出最终值来自哪一层，并确认没有更高层的 Managed 或临时命令行参数改变结果。

   失败处理：临时把重复键从低优先级文件移除，保留一个来源再验证。组织策略无法在个人文件中覆盖，应联系策略维护者确认允许范围。

图中的 Settings precedence 从最高优先级开始列出。Managed settings 不能被其他层覆盖；若个人文件内容正确但行为不同，先沿此顺序查找，而不是反复重写 JSON。

用 /status 确认文件真的被加载

7. 查看当前会话的 Setting sources。

   入口位置：Claude Code 交互会话输入 /status，打开 Status 标签。

   主要动作：找到 Setting sources 行，核对是否出现 User settings、Project settings 或 Project local settings。该区域证明哪些来源已加载，但不会逐键显示每个值来自哪一层。

   成功标志：目标配置来源出现在列表中，并且刚设置的可观察偏好或权限行为符合预期。

   失败处理：来源未出现时，优先检查 JSON 语法、文件路径和文件是否至少包含一个有效键。Config 标签只编辑部分开关，不等于查看原始 settings.json 内容。

图中 Verify active settings 明确指向 /status、Status 标签和 Setting sources 行。目标来源出现且行为一致才算完成；列表为空时，配置文件可能未找到、没有有效键或 JSON 已损坏。

settings.json 配置完成检查

• 已根据个人、团队或本机项目需求选择 User、Project 或 Local 作用域。
• Windows、macOS 或 Linux 的配置文件路径与当前作用域一致。
• Local 文件没有进入版本控制，Project 文件不包含个人密钥或机器专属路径。
• JSON 已通过系统解析器检查，没有注释、尾随逗号或错误转义。
• deny 覆盖敏感文件，ask 保留高风险动作确认，allow 只放明确的低风险范围。
• 已区分热重载设置与需要切换、清空或重启的设置。
• /status 的 Setting sources 能看到目标来源，实际行为与期望一致。
• 五张官方截图均可打开，分别对应作用域、文件位置、生效时机、优先级和加载核验。