跳到主要内容

settings.json：配置系统

进阶

settings.json 是 Claude Code 配置的所在之处——权限、钩子、环境变量、模型默认值等等。理解层级是关键。

层级（优先级从高到低）​

当同一个键在多个位置被设置时，Claude Code 使用设置了它的最高层级的值:

  1. 受管 / 企业 — managed-settings.json、MDM 策略，或来自 claude.ai 控制台的服务器托管设置。除少数安全敏感的例外情况外，你设置的任何内容都无法覆盖它们。
  2. 命令行 — claude --settings '<json-or-path>'，仅对单次会话生效。位于除受管之外的所有文件之上，且不写入任何文件。
  3. 项目（个人） — .claude/settings.local.json，被 git 忽略。你对这个仓库的覆盖设置。
  4. 项目（共享） — .claude/settings.json，提交到仓库。面向整个团队。
  5. 用户 — ~/.claude/settings.json。你在所有项目中的默认值。
环境变量不是一个层级

它们位于这个栈之外，按键逐个解析。例如 ANTHROPIC_MODEL 优先于任何文件中的 model 键，而 ANTHROPIC_DEFAULT_MODEL 仅在没有任何文件设置 model 时才生效。

提交共享文件，忽略本地文件

把团队约定放进 .claude/settings.json（提交）。把个人微调和机器特定路径放进 .claude/settings.local.json（被 git 忽略）。这样既能保持团队一致，又不会把你的偏好强加于人。

你通常会设置什么​

  • permissions——allow/ask/deny 规则。见权限。
  • hooks——在生命周期事件运行的命令。见钩子。
  • env——会话的环境变量。
  • 模型 / 行为默认值——例如首选模型。

安全地编辑​

  • 保持有效的 JSON（一个多余的逗号就会破坏它）。
  • 优先使用窄范围的权限规则，而非宽泛的。
  • 绝不要把密钥放进已提交的文件——改用 env 引用或密钥管理器。

可直接复制的起始文件见钩子与 settings.json 配方。

下一步​