Claude Code 设置：作用域与最小配置

Claude Code 的设置分四层作用域，最上面是组织部署的托管设置，往下依次是 --settings 命令行 JSON、项目本地、共享项目，最低是用户设置。仓库里的 .claude/settings.json 归团队共享，.claude/settings.local.json 只对你、只在这一个项目，~/.claude/settings.json 管你在这台机器上的每一个项目。想马上动手，一份最小配置只要 $schema 和 permissions 两段。

Claude Code 的设置放在哪些文件里，各自管多大范围？

写在哪一层，取决于这个偏好只服务你一个人，还是全组要统一。四类文件就是按这个分的，路径与用途见下表。

用户设置管的是这台机器上的所有项目，但它不会跟着仓库到队友那边，云端会话也读不到。托管设置由组织部署，你不需要去创建或编辑它。

共享项目设置要提交进版本控制之后才对团队有效，在那之前它不过是你磁盘上的一个普通文件。项目本地文件是你一个人的，Claude Code 第一次往里写内容时会顺手把它加进你的全局 git 排除，不会混进提交；文件要是你手工建的，这一步得自己补上。主题和默认模型只在自己机器上调好，提交代码后队友却没有，那就是这份文件的范围问题。

这些文件分别在什么时候被建出来

用户文件一般是 Claude Code 自己写出来的：你第一次在 /config 菜单里改动存进用户设置的选项（主题这类），它就写进 ~/.claude/settings.json；你第一次在权限提示上选“Yes, and don’t ask again”，这条批准会作为 allow 规则落到 .claude/settings.local.json。也有少数 /config 选项不走用户文件，包括 Show tips，保存的是本地文件。共享项目文件不需要谁去触发，已经在用 Claude Code 的项目可能早就提交过；没有的话，在项目文件夹里建一个。

本地文件有两个容易踩的例外

• 位置：不在 git 仓库里、仓库根目录正好是你的主目录、在 Windows 上，或者仓库根目录及其 .git、.claude 条目不归你的用户所有，这几种情况下文件会和 .claude/settings.json 放在一起。
• 路径锚点：以 / 开头的权限规则和相对沙箱路径，锚点是会话的主工作目录，不是仓库根目录。

同一个键写在多个文件里，最后听谁的？

查起来就两步：先确认这个键有没有特殊规则，没有就按优先级从高往低找。

同一个 model 最终由谁定

项目文件 .claude/settings.json 里写了 model，你又在会话里用 /model 换了一个：你的选择看着更近，可每次启动项目里的值都会重新压上来。你的选择确实存下来了，优先级比它低；启动标题会告诉你模型来自哪个文件。托管层的 model 属于起始默认值，不是锁，把模型真正锁住的是 availableModels 和 deniedModels。在项目文件里钉死了某个模型，结果每次启动都被换回去，原因就在这里。

同一项内容也可能由标志或环境变量来设：

• --model 对应 model；
• --effort 对应 effortLevel 与 modelSettings；
• ANTHROPIC_MODEL 对应 model。

也有的键只在特定层生效。权限默认模式的 auto 和 bypassPermissions 就不能写在项目或本地设置里，得放用户或托管设置，或者给单个会话传 --permission-mode；v2.1.257 之前，bypassPermissions 从任何文件都能生效。

列表键为什么不合并

数组通常会合并，下面这几个键是例外。

• fallbackModel 本身是一条有序链，顺序有意义，所以值整个取自定义它的最高优先级文件，不会把几份链接起来。
• modelPicker 存的是有序行列表和替换标志，取值只认托管设置、--settings 和用户设置，项目与本地文件里的同名键一律忽略，需要 Claude Code v2.1.242 或更高版本。
• availableModels 只要由托管设置定义，就按原样应用，你在用户、项目或本地补的条目不算数，不同托管来源之间的列表也不合并；只有在非托管作用域之间，数组才像平常一样合并。
• modelSettings 一次只解析一个模型，它和 effortLevel 一起决定这个模型最后用哪个值。

还有一类键方向相反，取的是更严格的那一侧：disableClaudeAiConnectors 只要在任何作用域里出现 true 就算数，托管来源写 false 也压不住它。

最小可用的一份配置该写什么？

用户设置够用就行，两段足够：$schema 负责让编辑器能校验，permissions 决定哪些命令免问、哪些文件不能碰。

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

把它放进 ~/.claude/settings.json，它就是你的个人偏好；一字不改搬进仓库的 .claude/settings.json，它就变成团队规则，差别只在影响范围和生效条件。不想改文件、只想临时试一段配置，可以在启动时把 JSON 传进去：claude --settings '{"model": "claude-opus-5-5"}'。这种写法只对当前会话有效，同名键会盖住项目和用户文件里的值，没提到的键还是原值。

把环境变量写进 env 块

要长期生效的变量写进设置文件的 env 块，比如超时时间：

{ "env": { "API_TIMEOUT_MS": "1200000", "BASH_DEFAULT_TIMEOUT_MS": "300000" } }

不动文件也行，直接在 shell 里导出：macOS、Linux、WSL 用 export，PowerShell 用 $env:，CMD 用 set。遥测和日志类的变量只从 shell、用户设置或托管设置读取，写进项目和本地设置会被忽略，只有少数关闭值例外。把这类开关塞进团队共享文件，队友那边看到的照样是没生效。

怎么确认改完的设置真的生效了？

核对最快靠 /status，它显示当前模型和账户信息。会话中途要改，model 用 /model 马上切，effortLevel 和 modelSettings 用 /effort 马上调。

每个模型各有一份提示缓存，换过去之后的第一个请求要把整个对话重新读一遍，用不上缓存，所以那一轮通常更慢。刚换完模型觉得第一轮特别慢，不是配置没生效，是缓存正在重建。

无效 JSON 和单个条目被拒是两件事

设置错误说的是用户、项目或本地文件里的 JSON 无效，或者某个值被架构拒掉。这种情况交互式会话启动会弹对话框，你可以让 Claude 帮忙修文件、直接退出，或者不加载这些坏掉的设置继续用。设置警告轻得多，只是单个条目没通过，比如一条格式错的权限规则、一个不认识的 hook 事件名，Claude Code 跳过这一条，文件里其余部分照样生效。托管设置里的无效条目另有说法：剩下的内容继续强制执行，某些键回退到更严格的值，直到你修好为止。

配置错误是另一条单独的路径：~/.claude.json 解析不了时，Claude Code 先把坏文件复制到 ~/.claude/backups/.claude.json.corrupted.<timestamp>，然后问你是退出手动修，还是重置成默认配置；用 -p 跑则直接打印错误并退出。想回到之前的状态，从备份目录里最近五个 .claude.json.backup.<timestamp> 挑一个复制回去，这些备份都是写入前存下的。

设置没问题了，下一步是拿它去跑真实项目：在真实项目里用 Claude Code 写代码的完整做法。

模型、API key 和环境变量分别设在哪一层？

模型既能长期固定，也能临时覆盖；凭据和端点走环境变量，这两样的影响范围常常不在项目文件里。

要让新会话固定用某个模型，写设置文件的 model 字段。临时切换的办法有几种：

• 会话里用 /model，启动时用 claude --model；
• 环境变量用 ANTHROPIC_MODEL；
• 新会话的默认值用 ANTHROPIC_DEFAULT_MODEL，需要 Claude Code v2.1.236 或更高版本。

在 /model 选择器里按 Enter，模型会存成默认值；按 s 只对当前会话有效。用 --resume 或 --continue 恢复的旧会话，通常还是用它当初那个模型，不会跟着你现在的默认值走。

订阅和 API key 谁生效

ANTHROPIC_API_KEY 是当 X-Api-Key 头送出去的。设了它之后，即使你已经登录，用的也是这个密钥，不是 Claude Pro、Max、Team 或 Enterprise 订阅；非交互模式（-p）只要它存在就一直用它，交互模式会先让你批准一次，然后才盖过订阅。想回订阅，运行 unset ANTHROPIC_API_KEY。ANTHROPIC_AUTH_TOKEN 走的是 Authorization 头，你填的值前面会被加上 Bearer 前缀。

端点类的变量是 ANTHROPIC_BASE_URL，它覆盖 API 端点，把请求转向代理或网关。改它的连带影响不止一处：主机不是第一方时，MCP 工具搜索默认关闭，如果你的代理能转发 tool_reference 块，把 ENABLE_TOOL_SEARCH 设成 true 可以打开；从 v2.1.196 起，指向 api.anthropic.com 以外主机时 Remote Control 会被禁用，这和它在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 上的表现一样。

别名解析与 [1m] 后缀

opus、sonnet、haiku、fable 分别落到哪个模型，看 ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_HAIKU_MODEL 和 ANTHROPIC_DEFAULT_FABLE_MODEL。但这几个变量不能把允许的别名重定向到允许列表以外的模型。

ID 发出去之前，Claude Code 会把 [1m] 后缀删掉，只有底层模型确实支持 1M 上下文时才该加上它。后缀看的是变量，不是模型：在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，同一个变量里没带 [1m] 的 Opus 4.6 或 Sonnet 4.6 ID 走 200K 上下文，哪怕另一个变量用了同样的模型和同样的后缀；反过来说，opus 已经解析到原生 1M 窗口的 Opus 4.7 或更高版本时，加这个后缀也没用了。

选择器里没有的模型

网关模型或非标准模型 ID，可以用 ANTHROPIC_CUSTOM_MODEL_OPTION 当成自定义条目加进 /model 选择器，配套的 _NAME、_DESCRIPTION、_SUPPORTED_CAPABILITIES 分别管显示名、描述和它支持的能力（比如 effort,thinking）。加进去只是多一个可选条目，内置别名怎么解析还是怎么解析，组织的允许列表也不会因此变宽。

团队共享设置怎么写才不覆盖个人文件？

共享项目文件里只放团队真的要统一的键，个人口味放在本地文件。还有些键即使提交了，也要等队友信任这个文件夹才开始生效。

permissions.allow 规则、permissions.additionalDirectories、extraKnownMarketplaces 和大多数 env 值，都得等工作区信任之后才应用。在那之前，队友照样看到提示，也拿不到文件声明市场里的插件。deny 和 ask 规则不等，马上生效。

你在权限提示上选过“Yes, and don’t ask again”，同一个工具却又被问一次。你的选择存成本地文件里的 allow 规则，而本地 allow 压不过项目或托管文件里的 ask。组织的允许规则会和你的规则一起应用，除非组织设了 allowManagedPermissionRulesOnly。

在 VS Code 扩展里批准操作，批准卡会问规则写进哪个文件，项目共享文件也在选项里；命令行里 Claude Code 只写你的本地文件。团队规则放共享文件、个人口味放本地文件，两边就不会互相压掉。

提交了也到不了队友的键

有些键的适用范围写的是 User, local, or managed、User or managed、Managed 或 Global config，这些永远不会从共享文件应用，少数在仓库文件里仍可关闭的除外；Global config 键只认 ~/.claude.json。env 块里的遥测导出变量同属这一类，项目和本地设置里写的值不算数，只有少数关闭类取值例外。

本地文件和 git 的关系是自动处理的：第一次写入 .claude/settings.local.json 时，Claude Code 会把 **/.claude/settings.local.json 加进你的全局 git 排除，写在 core.excludesFile 指定的文件里，没设置时就是 $XDG_CONFIG_HOME/git/ignore 或 ~/.config/git/ignore。文件还没被 git 跟踪时，里面的 allow 规则不用先过工作区信任。

把 Claude Code 接到别的网关或中转站，哪些值只属于那家服务？

地址、令牌、模型名这三项随服务走，换一家就得全换，别当成 Claude Code 的通用默认照抄。

拿接入 DeepSeek V4 Pro 举例：env 块里，网关地址写进 ANTHROPIC_BASE_URL，网关签发的 API Key 写进 ANTHROPIC_AUTH_TOKEN，模型名 deepseek-v4-pro 写进 ANTHROPIC_MODEL。为了让 Opus、Sonnet、Haiku 三个档位和子任务都落到同一个模型，示例里三个别名变量和 CLAUDE_CODE_SUBAGENT_MODEL 也一起指过去，省掉跨模型调用的兼容问题。

这些值只对这家服务成立，换服务就得换地址、令牌和模型名。改完 env 块，重启一次会话，再到 /status 的 Status 标签页看 Anthropic base URL 一行和模型名是不是指向你准备接入的那家；这一行不出现，说明变量没到会话里。用网关或中转站时，模型名要从对方那里拿，别照抄文档示例。

请求最后都要落到计费上。MixRoute 的现行首页与定价页写的是 ONE API、250+ 模型与 0% platform fee，四个语种的页面价格一律用美元显示。决定这次请求交给谁之前，先看当前充值门槛和可用模型范围。