---
title: "Claude Code settings.json 层级、优先级与 env 配置"
description: "讲清 Claude Code 用户级、项目级、本地级和托管策略四类 settings.json 的位置与覆盖顺序，env 里接口地址和代理变量的作用范围，以及用 /status 确认生效值的步骤。"
url: https://cdnping.org/blog/claude-code-settings-json-guide
language: zh-CN
published: 2026-10-22
category: "开发工具"
tags: ["Claude Code","配置文件","环境变量","开发工具","团队协作"]
source: cdnping.org
license: Free to quote and summarize with a link to the url above.
---
# Claude Code settings.json 层级、优先级与 env 配置

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

下面按“文件在哪、谁覆盖谁、写什么、怎么验证”的顺序展开。字段名和路径以 [Anthropic 官方 settings 文档](https://docs.anthropic.com/en/docs/claude-code/settings) 为准，Claude Code 更新频繁，遇到出入请以文档当前版本为准。

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

| 层级 | 路径 | 谁会用到 | 是否提交到仓库 |
|---|---|---|---|
| 托管策略（managed） | macOS：`/Library/Application Support/ClaudeCode/managed-settings.json`；Linux / WSL：`/etc/claude-code/managed-settings.json`；Windows：见官方文档 | 公司 IT 或管理员统一下发 | 不在仓库里 |
| 用户级 | `~/.claude/settings.json` | 你本人，所有项目 | 否 |
| 项目共享 | `<项目>/.claude/settings.json` | 团队所有成员 | 是 |
| 项目本地 | `<项目>/.claude/settings.local.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，用户在任何一层都改不掉。

## 常用字段一张表

| 字段 | 作用 | 示例 | 建议放在哪一层 |
|---|---|---|---|
| `env` | 每次会话自动设置的环境变量 | `{"HTTPS_PROXY": "http://127.0.0.1:7890"}` | 看变量性质，见下一节 |
| `permissions.allow` / `deny` / `ask` | 工具调用的放行、禁止、需确认规则 | `"Bash(npm run test:*)"`、`"Read(./.env)"` | 团队约定放项目共享，个人习惯放本地 |
| `permissions.defaultMode` | 默认权限模式 | `"acceptEdits"` | 用户级或本地 |
| `permissions.additionalDirectories` | 允许访问的工作目录之外的路径 | `["../shared-lib"]` | 本地 |
| `model` | 默认模型 | 写模型别名或 ID | 用户级或本地 |
| `apiKeyHelper` | 用脚本生成认证值，避免把密钥写进文件 | `"~/bin/get-key.sh"` | 用户级 |
| `hooks` | 在工具调用前后执行命令，例如自动格式化 | 见官方 hooks 文档 | 团队规范放项目共享 |
| `includeCoAuthoredBy` | git 提交里是否带 Claude 署名 | `false` | 项目共享 |
| `cleanupPeriodDays` | 本地会话记录保留天数 | `30` | 用户级 |
| `statusLine` | 自定义底部状态栏 | 命令配置 | 用户级 |

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

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

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

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

| 类别 | 变量 | 放哪里 | 原因 |
|---|---|---|---|
| 接口地址与认证 | `ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_API_KEY` | 用户级或 `settings.local.json` | 含密钥，绝不能进仓库 |
| 网络代理 | `HTTPS_PROXY`、`HTTP_PROXY`、`NO_PROXY` | 用户级或本地 | 每个人的网络环境不同 |
| 行为开关 | `DISABLE_TELEMETRY`、`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`、`API_TIMEOUT_MS`、`BASH_DEFAULT_TIMEOUT_MS` | 团队统一的可以放项目共享 | 不含个人信息 |

几个实际会踩到的点：

**代理变量会被子命令继承。** 你在 `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 接口地址配置](/blog/configure-custom-api-endpoint-claude-code-codex)，这里不重复。

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

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

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

下面的检查按顺序做：

1. 校验 JSON 语法。一个多余的逗号就会让整个文件被忽略：
   ```bash
   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 连接超时和报错怎么排查：四层网络检查清单](/blog/claude-code-connection-troubleshooting) 逐层看；也可以先打开 [Claude Code 挂了吗](/down/claude-code) 和 [Anthropic API 状态](/status/anthropic) 确认服务端当前有没有故障，排除对方的问题再查自己。代理是否真正生效、出口 IP 在哪，可以用 [IP 与环境检测](/ip) 看一眼。

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

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

项目共享 `.claude/settings.json`（提交到仓库）示例：

```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`（不提交）示例：

```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` 里加上：

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

提交前可以再确认一次：

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

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

## 几个常见问题

### 改了 settings.json 没反应？

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

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

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

### 配置都对，就是慢？

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

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