博客 / 开发工具

Claude Code settings.json 层级、优先级与 env 配置

2026-10-22cdnping 编辑部约 6 分钟读完

Claude Code settings.json 一共有四个位置：用户级 ~/.claude/settings.json、项目共享的 .claude/settings.json、项目本地的 .claude/settings.local.json，以及管理员下发的托管策略文件。同一个字段在多处出现时，越靠近“当前这台机器、这个项目”的越优先，托管策略最高。接口地址、代理这类变量写在 env 字段里，写完以后用 /status 看实际生效值，不要靠猜。

下面按“文件在哪、谁覆盖谁、写什么、怎么验证”的顺序展开。字段名和路径以 Anthropic 官方 settings 文档 为准，Claude Code 更新频繁，遇到出入请以文档当前版本为准。

#settings.json 有几个，分别放在哪？

几点容易混淆的地方：

• ~/.claude.json（注意没有子目录）是 Claude Code 自己维护的状态文件，里面有登录状态、项目历史、MCP 服务器等内容，它不是 settings.json，一般不需要手改。
• CLAUDE.md 是给模型读的项目说明，属于“记忆”，不是配置。权限、环境变量不要写进 CLAUDE.md，写了也不会被当作设置执行。
• settings.local.json 由 Claude Code 创建时，会自动配置 git 忽略它；如果你是手动建的，最好自己检查一下 .gitignore。

#多个文件冲突时，谁说了算？

官方文档给出的优先级从高到低是：

1. 托管策略（managed-settings.json）
2. 命令行参数（例如 --model、--settings <文件>、--permission-mode）
3. 项目本地 .claude/settings.local.json
4. 项目共享 .claude/settings.json
5. 用户级 ~/.claude/settings.json

也就是常说的“5 层优先级”。只看顺序容易误判，还要记住两条规则：

标量字段按优先级覆盖。 比如 model 在用户级写了一个值、项目本地又写了一个，生效的是项目本地那个。env 里的同名变量也一样，高优先级的那一层赢。

权限规则是合并的，不是覆盖。 permissions.allow、permissions.deny 这类数组会把各层的规则合起来一起判断，而 deny 优先于 allow。所以如果团队在项目共享配置里 deny 了 Bash(curl:*)，你在本地 allow 它也没用。托管策略里的 deny，用户在任何一层都改不掉。

#常用字段一张表

写之前可以在文件顶部加一行 "$schema": "https://json.schemastore.org/claude-code-settings.json"，VS Code 等编辑器会据此做字段补全和校验，拼错字段名能当场看出来。

#env 里放接口地址和代理，作用范围是什么？

env 的效果相当于在启动 Claude Code 之前替你 export 了这些变量，作用于 Claude Code 进程本身；Claude Code 通过 Bash 工具执行的命令一般也能读到这些变量。它不会改你的系统环境，也不会影响你在另一个终端里手动运行的程序。

常见的变量可以分成三类，放的位置不同：

几个实际会踩到的点：

代理变量会被子命令继承。 你在 env 里设了 HTTPS_PROXY，Claude Code 帮你跑 npm install、git fetch 时也会走这个代理。如果内网仓库或国内镜像不该走代理，就要在 NO_PROXY 里列出来，例如 "NO_PROXY": "localhost,127.0.0.1,.internal.example.com"。

接口地址只在一个项目里改，就写进本地文件。 假设你平时用官方接口，只有某个项目要走公司网关，把 ANTHROPIC_BASE_URL 写进那个项目的 .claude/settings.local.json 即可，其他项目不受影响。接口地址具体怎么填、Codex 和 OpenCode 对应写在哪，见 Claude Code 自定义 API 与 Codex、OpenCode 接口地址配置，这里不重复。

shell 里也设了同名变量时，以 /status 为准。 按官方说法，settings 里的 env 会应用到每个会话；但不同版本对“shell 已有变量”和“settings 变量”同名时的处理细节可能变化。遇到“我明明改了却不生效”，第一步是看下面的验证步骤，而不是反复改文件。

进程启动时就要读的变量放 shell。 像 NODE_EXTRA_CA_CERTS（公司自签证书）这种 Node.js 启动阶段读取的变量，写在 settings 的 env 里可能来不及生效，稳妥做法是在 shell 配置里 export。

#改完之后，怎么确认是哪一层生效？

下面的检查按顺序做：

1. 校验 JSON 语法。一个多余的逗号就会让整个文件被忽略：

   for f in ~/.claude/settings.json .claude/settings.json .claude/settings.local.json; do
     [ -f "$f" ] && (python3 -m json.tool "$f" >/dev/null && echo "OK  $f" || echo "BAD $f")
   done
   

2. 重启会话。settings 在启动时读取，已经打开的会话不一定会重新加载 env。退出后重新运行 claude。
3. 在会话里运行 /status。它会显示当前的认证方式、模型、接口地址等信息，部分版本还会列出读取到了哪些设置来源。看这里的接口地址和代理是不是你期望的值。
4. 运行 /permissions，列出当前生效的 allow / deny 规则。某条规则不起作用时，看看是不是被另一层的 deny 盖住了。
5. 运行 /config，打开设置界面，查看和修改用户级常用选项。注意它改的是哪一层文件，不确定时回到第 3 步核对。
6. 让 Claude 打印环境变量。直接让它执行 env | grep -iE 'proxy|anthropic'，看 Bash 工具拿到的值。输出里可能有密钥，只在自己机器上看，不要贴到群里或 issue 里。
7. 出问题时运行 /doctor。它会检查安装状态和配置问题，部分版本会提示设置文件里的无效字段。

如果 /status 显示配置都对，但请求还是超时或报错，问题多半不在配置文件，而在网络或服务端。这时按 Claude Code 连接超时和报错怎么排查：四层网络检查清单 逐层看；也可以先打开 Claude Code 挂了吗 和 Anthropic API 状态 确认服务端当前有没有故障，排除对方的问题再查自己。代理是否真正生效、出口 IP 在哪，可以用 IP 与环境检测 看一眼。

#团队共享配置和个人配置怎么分开放？

一个比较稳的分法：仓库里只放“所有人都该一样”的东西，凡是跟人、跟机器、跟密钥有关的都留在本地。

项目共享 .claude/settings.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.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "DISABLE_TELEMETRY": "1"
  },
  "includeCoAuthoredBy": false
}

项目本地 .claude/settings.local.json（不提交）示例：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.example.com",
    "ANTHROPIC_AUTH_TOKEN": "替换为你自己的密钥",
    "HTTPS_PROXY": "http://127.0.0.1:7890",
    "NO_PROXY": "localhost,127.0.0.1"
  },
  "permissions": {
    "additionalDirectories": ["../my-scratch"]
  }
}

上面的地址、端口和目录都是示例，请换成你自己的值。

.gitignore 里加上：

# Claude Code 个人配置，不进仓库
.claude/settings.local.json
# 如果有人习惯在项目里放 CLAUDE.local.md，也一起忽略
CLAUDE.local.md

提交前可以再确认一次：

git check-ignore -v .claude/settings.local.json   # 应输出命中的忽略规则
git ls-files .claude/                              # 不应出现 settings.local.json

如果密钥已经被提交过，光加 .gitignore 不够，需要到服务商后台把这把密钥作废重建。把代码和配置交给第三方接口之前，先看一下对方的数据政策，可以参考 用第三方 AI API 时，代码和对话会被看到吗。

#几个常见问题

#改了 settings.json 没反应？

按顺序排查：JSON 是否合法 → 是否重启了会话 → 是否有更高一层的同名字段覆盖 → shell 里是否有同名变量 → /status 显示的值是什么。大部分情况停在前三步。

#能不能只在某次启动时临时换一套配置？

可以用 claude --settings ./某个文件.json 加载额外的设置文件，它的优先级在命令行参数这一层，高于项目和用户配置，适合临时测试另一个接口地址或模型，不用改动常用文件。

#配置都对，就是慢？

那就不是配置问题了。延迟通常来自网络路径、代理节点或服务端排队，可以看 Claude Code 响应很慢：延迟来自哪里，怎么判断和优化。需要放行哪些域名和端口，见 Claude Code 与 Codex 的网络要求。在浏览器里也可以用 cdnping 在线测速 看一下到各家 API 的首次连接和往返时间，作为参考。

最后提醒一句：通过代理或第三方接口使用 Claude Code 时，请遵守 Anthropic 的服务条款和所在地的法规，地区可用性以官方说明为准。