Claude Code settings.json 配置详解

这篇适合谁，读完能做到什么

如果你想知道 Claude Code 的 settings.json 应该写在哪里、哪些设置会覆盖哪些设置，或者改了配置却不生效，这篇适合你。读完你能分清四个设置文件各自管到哪些人，会按优先级排查同一个键的冲突，并知道怎样确认配置已经加载。^[1]

settings.json 管什么

设置（settings）就是一组 JSON 键，用来改变 Claude Code 的行为，比如它启动时用哪个模型、哪些操作无需询问就能执行、哪些文件不能读，以及组织要强制执行哪些规则。^[1]

Claude Code 从 ~/.claude/settings.json 这类 JSON 文件里读取设置。设置写在哪个文件里，就决定了它作用于谁。^[1]

四个设置文件和它们的作用范围

用户级的 ~/.claude/settings.json 对你在这台机器上的所有项目生效，适合放主题、编辑器模式、默认模型和你自己的权限规则这类个人偏好。^[1]

共享的项目级 .claude/settings.json 对文件夹里的所有人生效。在 git 仓库里应该把它提交进版本库，队友拉下代码后就能拿到同样的设置，适合放团队的权限、hook、插件和项目需要的环境变量。^[1]

项目本地的 .claude/settings.local.json 只对你自己在这个项目中生效。Claude Code 在创建这个文件时会把它排除在 git 之外。^[1]

托管设置（managed settings）由组织部署，覆盖所有被部署到的人，用于安全策略和合规要求。^[1]

安装 Claude Code 本身不会生成任何设置文件。设置文件要么来自组织下发，要么由你自己创建，或者由 Claude Code 在你第一次做相应操作时自动生成。在 /config 菜单里修改一个存入用户设置的选项时，Claude Code 会写入 ~/.claude/settings.json；在权限提示中第一次选择「不再询问」时，它会写入 .claude/settings.local.json。^[1]

在 Windows 上，~/.claude 指的是 %USERPROFILE%\.claude。如果想把主目录下的文件放到别处，可以设置 CLAUDE_CONFIG_DIR。^[1]

只想为自己改一个项目的设置

如果你想在一个项目里只为自己改某个设置，又不影响队友，就把它写进 .claude/settings.local.json。Claude Code 会把这个文件叠加在已提交的 .claude/settings.json 之上。^[1]

用 /config 还是直接改文件

/config 菜单只列出一小部分个人选项，比如主题、编辑器模式和详细输出，而不是所有键。选中一个选项修改，Claude Code 会替你保存。想不打开菜单直接改，可以输入 /config verbose=true 这种「键=值」的形式。^[1]

如果你要直接编辑文件，要记住设置文件是严格的 JSON。// 注释和多余的逗号都会导致语法错误，Claude Code 会在下一次启动时把它报告为设置错误。下面是一个示例，允许运行 lint 和测试命令而不询问，并禁止读取 .env 文件：^[1]

``json { "$schema": "https://json.schemastore.org/claude-code-settings.json", "permissions": { "allow": [ "Bash(npm run lint)", "Bash(npm run test *)" ], "deny": [ "Read(./.env)", "Read(./.env.*)" ] } } ``^[1]

保存之后，在 Claude Code 里运行 /status，看一下 Setting sources 一行，它列出了本次会话加载的每个设置文件。^[1]

只对一次会话生效

想试一个值又不想保存，可以在启动时指定。--settings 参数接收一段 JSON，它的优先级高于用户、项目和本地文件，但低于托管设置，而且无法设置托管或全局配置类的键。^[1]

有些键自己有对应的命令行参数，比如 --model 对应 model，--effort 对应 effortLevel。环境变量 ANTHROPIC_MODEL 也能设置 model。^[1]

如果只想用一次 Opus 而不改默认值，可以这样启动：^[1]

``bash claude --settings '{"model": "claude-opus-5-5"}' ``^[1]

在 /model 的选择器里按 s，可以切换模型但不把它保存为用户默认值。^[1]

改完什么时候生效

Claude Code 会监视设置文件并自动重新加载，所以大多数修改不用重启就能作用于正在运行的会话，包括 permissions、hooks 和 apiKeyHelper 的修改。但有些键只在会话启动时读取一次，改了也不会影响正在运行的会话，需要重新启动。^[1]

同一个键在多处设置时以谁为准

托管设置位于最顶层，你自己的设置文件或 --settings 都无法覆盖其中的键。用户设置位于最底层，任何更高层级设置了同一个键，它都会被覆盖。排查时可以先找出这个键在哪几层出现，再从高到低看谁先生效。^[1]

优先级从高到低依次是：托管设置、命令行参数、项目本地设置、共享项目设置、用户设置。同一个键在较高的层级设置了，就会覆盖较低层级的值。^[1]

环境变量不在这个层级结构里。对于每一对「环境变量与设置键」，优先级是单独判定的。^[1]

列表类的键比较特殊。如果 permissions.allow 在多个文件里都设置了，Claude Code 会把这些列表合并，而不是只取一个。这样每个文件都能添加自己的条目，而不会删掉别人的。^[1]

有少数与安全相关的键，即使托管设置写的是 false，任何作用域里写的 true 也会生效，比如 disableClaudeAiConnectors。^[1]

配置没有生效怎么办

排查通常先问两个问题：这个键是不是被更高层级设置了？这个文件本身有没有被加载？第一个问题看优先级，第二个问题看 /status。然后再对照下面的症状排查。^[1]

设置错误（Settings Error）：用户、项目或本地文件中的 JSON 无效，或者某个值被拒绝。交互式会话开始时会弹出对话框，让你修复、退出，或者跳过损坏的设置继续。^[1]
设置警告（Settings Warning）：只有个别条目出错，比如权限规则格式不对。Claude Code 会跳过这些值，文件其余部分仍然生效。^[1]
-p 模式不会弹对话框。它会跳过损坏的用户、项目或本地文件，或其中有问题的值，然后继续执行。^[1]
permissions.defaultMode 的值 auto 和 bypassPermissions 不会从项目或本地设置中生效。应该写进用户设置或托管设置。^[1]
在权限提示中选择「不再询问」保存的是本地文件里的 allow 规则。这条规则不会压过项目或托管文件里的 ask 规则。^[1]