Claude Code settings.json 详解（一）：配置文件在哪里、谁说了算

为什么要了解配置文件体系

用 Claude Code 久了，你会想做各种自定义：给某个项目配置特定的权限规则，在团队里共享一套 hooks，或者在自己的机器上覆盖某些默认值，却不想把它提交到 git 里。

这些需求背后，是 Claude Code 完整的多层配置体系。搞清楚”有哪些配置文件”和”谁覆盖谁”，是正确配置 Claude Code 的前提。

五个配置来源

Claude Code 的配置来自五个不同的来源，按优先级从低到高排列：

层级	名称	文件路径
1（最低）	用户设置	`~/.claude/settings.json`
2	项目设置	`.claude/settings.json`
3	本地设置	`.claude/settings.local.json`
4	CLI 参数	`--settings <路径或JSON>`
5（最高）	管理员策略	`managed-settings.json`（见下文）

高优先级的来源会覆盖低优先级的来源。

各配置文件详解

1. 用户设置 `~/.claude/settings.json`

适用场景：个人偏好设置，对这台机器上所有项目生效。

这是最常用的配置文件。比如你希望所有项目都默认使用某个模型，或者始终关闭某些提示，就放在这里。

{
  "model": "claude-sonnet-4-6",
  "cleanupPeriodDays": 60
}

这个文件不会被提交到任何 git 仓库，完全是个人配置。

2. 项目设置 `.claude/settings.json`

适用场景：项目级共享配置，团队成员共同使用。

放在项目根目录的 .claude/ 文件夹下，可以提交到 git，让整个团队使用同一套配置。比如约定这个项目允许哪些 bash 命令，或者强制使用某个语言响应。

{
  "permissions": {
    "allow": ["Bash(npm run:*)"]
  },
  "language": "english"
}

3. 本地设置 `.claude/settings.local.json`

适用场景：个人在项目里的本地覆盖，不提交到 git。

和项目设置在同一目录，但不应该提交到 git。Claude Code 在写入这个文件时会自动把它加到项目的 .gitignore 里。

适合存放个人偏好覆盖，比如你希望在这个项目里用不同的模型，但不想影响其他团队成员。

{
  "model": "claude-opus-4-6"
}

4. CLI 参数 `--settings`

适用场景：临时覆盖、脚本化调用、CI/CD 场景。

通过命令行直接指定，优先级高于所有文件配置：

# 指定一个配置文件
claude --settings ./my-override.json

# 直接传 JSON 字符串（SDK 调用场景）
claude --settings '{"model":"claude-haiku-4-5-20251001"}'

还可以通过 --setting-sources 限制只加载哪些来源：

# 只加载用户设置，忽略项目设置和本地设置
claude --setting-sources user

注意：无论如何设置，管理员策略（policySettings）和 CLI 参数（flagSettings）永远加载，无法被排除。

5. 管理员策略（最高优先级）

适用场景：企业统一管控，不允许用户覆盖。

管理员策略有多种下发方式，按 Claude Code 内部的优先级从高到低：

① 远程策略（最高）

通过 Claude.ai 平台远程下发，Claude Code 会定期轮询更新，无需手动操作。

② MDM / 注册表（管理员专属）

平台	路径
macOS（设备级）	`/Library/Managed Preferences/com.anthropic.claudecode.plist`
macOS（用户级）	`/Library/Managed Preferences/<username>/com.anthropic.claudecode.plist`
Windows（管理员）	`HKLM\SOFTWARE\Policies\ClaudeCode`（注册表键 `Settings`）

macOS 通过 MDM Profile 管理，Windows 通过组策略管理。

③ 文件配置

平台	路径
macOS	`/Library/Application Support/ClaudeCode/managed-settings.json`
Linux	`/etc/claude-code/managed-settings.json`
Windows	`C:\Program Files\ClaudeCode\managed-settings.json`

④ Drop-in 目录

在上述路径同级的 managed-settings.d/ 目录下，可以放多个 .json 文件，按文件名字母序合并，后面的文件覆盖前面的。

例如 Linux 下：

/etc/claude-code/
├── managed-settings.json          # 基础配置
└── managed-settings.d/
    ├── 10-security.json           # 安全团队的策略
    ├── 20-mcp-allowlist.json      # 平台团队的 MCP 策略
    └── 30-model-restrictions.json # 成本控制团队的模型限制

这种设计参考了 systemd/sudoers 的 drop-in 约定，让不同团队可以维护独立的策略片段，不用协调编辑同一个文件。

⑤ HKCU（Windows 用户注册表，最低管理员优先级）

HKCU\SOFTWARE\Policies\ClaudeCode，用户可写，优先级最低。

管理员策略内部采用首个有效来源获胜的规则：只要优先级更高的来源有内容，后面的来源就会被完全忽略，不会合并。

优先级规则：覆盖 vs 合并

了解优先级之后，还需要明白一个关键区别：不是所有字段都是直接覆盖的。

单值字段：高优先级直接覆盖

大多数普通字段（字符串、布尔值、数字、对象）遵循”高优先级覆盖低优先级”的规则：

// 用户设置（优先级低）
{ "model": "claude-sonnet-4-6" }

// 项目设置（优先级高）
{ "model": "claude-opus-4-6" }

// 最终生效
{ "model": "claude-opus-4-6" }

数组字段：跨来源合并去重

数组类型的字段（如 permissions.allow[]、hooks、enabledMcpjsonServers 等）不是覆盖，而是拼接并去重：

// 用户设置
{ "permissions": { "allow": ["Bash(git:*)"] } }

// 项目设置
{ "permissions": { "allow": ["Bash(npm run:*)"] } }

// 最终生效（两个来源的规则都保留）
{ "permissions": { "allow": ["Bash(git:*)", "Bash(npm run:*)"] } }

这个设计使得用户全局设置的权限规则和项目设置的规则可以共存，不会互相覆盖。

哪些配置可以写入

只有三个来源支持写入操作：

用户设置（~/.claude/settings.json）
项目设置（.claude/settings.json）
本地设置（.claude/settings.local.json）

--settings 参数和管理员策略是只读的，Claude Code 不会向这两个来源写入任何内容。

/config 命令修改配置时，会让你选择写入哪个来源（用户 / 项目 / 本地）。

配置验证

Claude Code 使用 Zod v4 对所有配置文件进行严格校验。有几个值得注意的细节：

无效权限规则不会导致整个文件失效：在验证前，会先过滤掉格式不合法的权限规则，其余配置正常生效。这避免了”一条规则写错了，整个配置文件都不生效”的情况。

文件读取有缓存：设置在会话期间缓存，文件变更后或执行写入操作后自动重置缓存。

JSON Schema 支持：Claude Code 提供了标准 JSON Schema，可以在编辑器中获得自动补全和校验提示：

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-opus-4-6"
}

快速决策指南

需求	用哪个文件
个人偏好，所有项目生效	`~/.claude/settings.json`
团队共享配置，提交 git	`.claude/settings.json`
个人覆盖，不提交 git	`.claude/settings.local.json`
临时测试某个配置	`--settings '{...}'`
企业统一管控	`managed-settings.json` 或 MDM

写在最后

Claude Code 的配置体系设计得很清晰：个人的归个人，项目的归项目，团队的归团队，管控的归管控。

五个层级各司其职，数组合并的设计让多个来源的规则可以共存。理解了这套体系，你就能在正确的地方放置正确的配置，而不是靠试错来猜测”为什么我的配置没有生效”。

后续几篇将深入介绍各个具体配置项的用法。