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

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

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

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

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

高优先级覆盖低优先级。个人用户 90% 的配置放 ~/.claude/settings.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 中转额度跑 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 使用教程。
• Claude Code Router 等代理类工具：本地起一个代理，按规则把请求分发给不同后端，还能接非 Claude 模型。
• 各家工具的横向对比见API 切换工具对比。

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

MCP：给 Claude Code 加外部工具

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

# 本地 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 入门。

注意：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）见排错指南。

推荐的配置顺序

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

配置项官方迭代很快，本文列的是最常用的子集，完整列表以 Claude Code 官方文档 为准。