# Claude Code 进阶配置：settings.json、环境变量、中转切换与 MCP

> 装好 Claude Code 之后怎么配才顺手？settings.json 放哪、ANTHROPIC_BASE_URL/AUTH_TOKEN 怎么走中转、多个供应商怎么一键切换、MCP 怎么加、常见报错怎么解？进阶配置一篇讲全。
> 更新于 2026-08-09 · 难度 初级 · 来源 https://aicdks.com/guides/claude-code-config-deep

安装和登录看[国内安装教程](/guides/install-claude-code-china)就够了，这篇讲装好之后的进阶配置：配置文件体系、走中转的环境变量、多供应商切换、MCP 扩展和高频报错。看完这篇，Claude Code 才算真正配顺手了。

## 配置文件体系：settings.json 放哪

Claude Code 的配置是 JSON 文件，按优先级从低到高分三层：

| 文件位置 | 作用范围 | 用途 |
| --- | --- | --- |
| `~/.claude/settings.json` | 你机器上的所有项目 | 个人全局配置（中转地址、默认模型等放这） |
| `项目/.claude/settings.json` | 单个项目，随 git 提交 | 团队共享的项目配置 |
| `项目/.claude/settings.local.json` | 单个项目，不提交 | 你个人的项目级配置 |

**高优先级覆盖低优先级**。个人用户 90% 的配置放 `~/.claude/settings.json` 就行。一个实用的起手模板：

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://你的中转地址",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的中转key"
  },
  "permissions": {
    "allow": ["Bash(npm run test:*)", "Read(~/.zshrc)"],
    "deny": ["Bash(rm -rf:*)"]
  }
}
```

`env` 键里的变量 Claude Code 会直接读取，**不管你从哪个终端、哪个 IDE 启动都生效**——比写进 `.bashrc` 更可靠，推荐用这种方式而不是 export。

## 走中转的核心环境变量

国内没有订阅、用 [API 中转额度](/category/api-中转与额度-claude-额度)跑 Claude Code，靠的就是这几个变量：

| 变量 | 作用 |
| --- | --- |
| `ANTHROPIC_BASE_URL` | 把 API 请求指到中转地址（替代官方 api.anthropic.com） |
| `ANTHROPIC_AUTH_TOKEN` | 中转的凭据，会加上 `Bearer ` 前缀放进 Authorization 头。**拿不准用哪个就用这个** |
| `ANTHROPIC_API_KEY` | 另一种凭据格式，走 `X-Api-Key` 头。中转站要求「API key/x-api-key」时用 |
| `ANTHROPIC_MODEL` | 指定默认模型名（部分中转要求特定模型名） |

两个高频坑：

1. **只设 BASE_URL 不设凭据 = 没配好**。请求会指向中转，但没有认证信息，必然 401。BASE_URL 和 TOKEN/KEY 要成对配置。
2. **设了 `ANTHROPIC_API_KEY` 会覆盖你已登录的订阅**。如果你有 Pro/Max 订阅还发现额度没走订阅，多半是环境里残留了这个变量，`unset ANTHROPIC_API_KEY` 即可。

配置完验证：进 Claude Code 输 `/status`，看 `Anthropic base URL` 一行是不是你的中转地址、凭据一行显示的是 AUTH_TOKEN 还是 API_KEY，再随便发一句话确认能正常回复。

## 多供应商切换：CC Switch 等工具

手里有官方订阅 + 两三家中转 key 时，手工改 settings.json 太痛苦。推荐用切换工具：

- **CC Switch**：开源桌面工具，把每家中转存成一个「供应商」配置，点一下就切换 Claude Code / Codex 的接入点，详细用法见 [CC Switch 使用教程](/guides/cc-switch-tutorial)。
- **Claude Code Router** 等代理类工具：本地起一个代理，按规则把请求分发给不同后端，还能接非 Claude 模型。
- 各家工具的横向对比见[API 切换工具对比](/guides/api-switching-tools-compared)。

一个纪律：**同一时间只用一种方式管配置**。CC Switch 管着 settings.json 的同时你又手工改环境变量，出问题会很难排查。

## MCP：给 Claude Code 加外部工具

MCP（Model Context Protocol）让 Claude Code 能连数据库、浏览器、各种 SaaS。加 MCP 服务器用命令行最简单：

```bash
# 本地 stdio 方式（以 filesystem 为例）
claude mcp add my-fs -- npx -y @modelcontextprotocol/server-filesystem ~/projects

# 远程 HTTP 方式
claude mcp add --transport http my-server https://example.com/mcp

claude mcp list   # 查看已配置的服务器
```

配置存在哪也分层级：默认存到你个人的配置（仅本机），加 `--scope project` 会写到项目的 `.mcp.json`（随 git 共享给团队）。会话里输 `/mcp` 可以查看连接状态和授权。MCP 是什么、有哪些好用的服务器，见 [MCP 入门](/guides/mcp-getting-started)。

注意：MCP 工具调用也消耗你的额度，挂一堆用不上的 MCP 服务器会白白吃掉上下文，**按需添加**。

## 常见报错处理

| 现象 | 原因与解决 |
| --- | --- |
| `401 Unauthorized` | 凭据不对：中转 key 填错/过期，或该用 AUTH_TOKEN 却设了 API_KEY（换一个变量试试） |
| `403 Forbidden` | 中转站不支持你请求的模型，或账号地区受限；换模型名或问中转客服 |
| `429 rate_limit` | 触发限额。订阅用户看 `/status` 的恢复时间等刷新；中转用户是额度用完或并发超限 |
| 明明登录了订阅却提示按量计费 | 环境里残留 `ANTHROPIC_API_KEY`，unset 掉 |
| 连接超时 / fetch failed | 网络到不了 api.anthropic.com：终端挂代理，或直接走国内可达的中转 |
| 改了 settings.json 不生效 | 检查 JSON 语法（少个逗号都会整个文件失效）；部分配置要重启 claude 才生效 |
| `/status` 里没有 base URL 那一行 | 说明中转配置根本没被读到，检查文件路径和 `env` 键的拼写 |

更完整的 401/403/429 排错思路（含 Codex）见[排错指南](/guides/codex-claude-code-troubleshooting)。

## 推荐的配置顺序

1. 先用最简单的方式跑通（订阅登录，或 settings.json 里配一家中转）；
2. `/status` 验证接入点和凭据无误；
3. 稳定用一两周、确定有多供应商需求了，再上 CC Switch；
4. 最后按需加 MCP。

配置项官方迭代很快，本文列的是最常用的子集，完整列表以 [Claude Code 官方文档](https://code.claude.com/docs) 为准。