展开目录（6 节）
先弄清 Claude Code 是怎么找到网关的
Claude Code 本质上是一个会读环境变量的 Anthropic API 客户端。它不关心对面是不是官方服务，只要对面能按 /v1/messages 的格式收发请求就行。接第三方网关要改三样东西：请求发到哪里（base URL）、拿什么认证（密钥）、请求里写什么模型名（模型映射）。
读完这篇，你应该能在 15 分钟内跑通第一次对话，并且知道出问题时先查哪一层。
背景补充：网关一般分两类。一类是原生兼容 Anthropic Messages 协议的，Claude Code 可以直接接；另一类只提供 OpenAI 格式的 /v1/chat/completions，Claude Code 接不上，除非你自己在中间加一层协议转换。买之前先问清楚网关是否支持 /v1/messages。
环境变量：最小可用配置
先装好 Claude Code（需要 Node.js 18 以上）：
npm install -g @anthropic-ai/claude-code
claude --version然后用下面几个变量对接网关：
| 变量 | 作用 | 示例值 |
|---|---|---|
ANTHROPIC_BASE_URL |
网关地址，客户端会自己拼 /v1/messages |
https://your-gateway.example.com |
ANTHROPIC_AUTH_TOKEN |
以 Authorization: Bearer 方式发送密钥 |
sk-xxxx |
ANTHROPIC_API_KEY |
以 x-api-key 头发送密钥 |
sk-xxxx |
ANTHROPIC_MODEL |
默认主模型 | claude-sonnet-4-5 |
HTTPS_PROXY |
本机需要走代理访问网关时才设置 | http://127.0.0.1:7890 |
临时试用，直接在当前终端 export：
export ANTHROPIC_BASE_URL="https://your-gateway.example.com"
export ANTHROPIC_AUTH_TOKEN="sk-xxxx"
claude长期使用，写进 ~/.claude/settings.json 的 env 字段，这样不依赖 shell 配置：
{
"env": {
"ANTHROPIC_BASE_URL": "https://your-gateway.example.com",
"ANTHROPIC_AUTH_TOKEN": "sk-xxxx"
}
}最常见的坑：base URL 不要带 /v1。Claude Code 会自己补路径，你写成 https://xxx/v1，实际请求就变成 /v1/v1/messages，返回 404。个别网关文档要求带前缀，以网关给出的 Anthropic 协议地址为准，但默认先按不带 /v1 试。
认证头用哪个，取决于网关。多数网关两种都认；如果一种报 401，换另一种再试。别同时设两个，否则出了问题你分不清是哪个头在起作用。
模型映射：Claude Code 会悄悄调用不止一个模型
很多人只设了 ANTHROPIC_MODEL，结果对话能通，日志里却出现别的模型的报错。原因是 Claude Code 内部还会用小模型处理标题生成、简单判断等轻量任务，这些请求默认写的是官方模型名。如果网关没有这个名字，就会返回 model not found 一类错误，有时表现为“主对话正常，但偶尔卡一下”。
稳妥做法是把三档模型都显式映射成网关里存在的名字：
{
"env": {
"ANTHROPIC_BASE_URL": "https://your-gateway.example.com",
"ANTHROPIC_AUTH_TOKEN": "sk-xxxx",
"ANTHROPIC_MODEL": "claude-sonnet-4-5",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-5",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-5",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
}
}网关的模型名可能带日期后缀、前缀或自定义别名，以网关控制台的模型列表为准，不要照抄上面的示例。旧文章里常见的 ANTHROPIC_SMALL_FAST_MODEL 已经被 ANTHROPIC_DEFAULT_HAIKU_MODEL 取代，新配置用后者。
成本上的取舍
三档模型的单价差距很大。按官方公开价量级，Haiku 档输出约每百万 token 几美元，Sonnet 档约十几美元，Opus 档约二三十美元，网关通常在此基础上有倍率。把日常编码默认设为 Sonnet 档，只在复杂重构时用 /model 临时切到 Opus，账单通常比全程 Opus 低一半以上。不建议一上来把三档全映射到最贵的模型。
只设 ANTHROPIC_MODEL
- 配置短，适合快速试通
- 小模型请求仍写官方名，网关不认时会报错
- 不建议长期使用
三档全部显式映射
- 多写 3 行，行为可预期
- 可以把 Haiku 档指到更便宜的模型控成本
- 推荐作为默认方案
验证代理是否真的生效
“能聊天”不等于“走的是网关”。如果你之前用 /login 登录过官方账号，Claude Code 可能还在用旧凭证。按下面的顺序验证：
- 先用 curl 单独测网关。绕开 Claude Code，确认地址、密钥、模型名本身没问题。
- 清掉旧登录态。在 Claude Code 里执行
/logout，避免官方凭证优先于环境变量。 - 重启 claude。环境变量只在进程启动时读取，改完配置必须重开。
- 执行 /status。检查显示的 base URL 和认证方式是否是你配置的值。
- 发一句简单提问并查网关后台。确认后台出现这次请求和对应的 token 计费，这才算真正生效。
第 1 步的 curl 示例：
curl -sS "$ANTHROPIC_BASE_URL/v1/messages" \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"claude-sonnet-4-5","max_tokens":32,
"messages":[{"role":"user","content":"ping"}]}'返回里有 "type":"message" 和 content 字段，说明网关链路通了。如果 curl 通而 Claude Code 不通，问题一定在本地配置，不在网关。
提示：密钥不想明文写进 settings.json，可以只把 BASE_URL 等非敏感项写进去，密钥放在 shell 的 profile 或系统密钥管理里。这个文件很容易被误提交到仓库。
常见报错对照表
| 现象 / 报错 | 最可能原因 | 处理 |
|---|---|---|
401 / Invalid API key · Please run /login |
密钥错误，或认证头类型不对 | 换 AUTH_TOKEN 与 API_KEY 另一种；检查密钥首尾空格 |
404 / not_found_error |
base URL 多了 /v1，或模型名不存在 |
去掉 /v1；对照网关模型列表 |
403 |
密钥无该模型权限，或 IP 被限制 | 查网关分组与白名单 |
429 / rate_limit_error |
并发或额度触顶 | 降低并发；确认余额；稍后重试 |
529 / overloaded_error |
上游过载 | 重试，或在网关侧切换通道 |
ECONNREFUSED / ETIMEDOUT |
网络不通，或代理没生效 | 检查 HTTPS_PROXY，用 curl -v 看连接 |
unable to verify the first certificate |
公司代理做了 HTTPS 中间人，证书不受信 | 设置 NODE_EXTRA_CA_CERTS 指向公司根证书 |
不要这样做：遇到证书报错就设置 NODE_TLS_REJECT_UNAUTHORIZED=0。这等于关掉 TLS 校验，你的 API 密钥和源码都可能被中间人读走。正确做法是导入根证书。
排错顺序建议固定：网络通不通 → 认证对不对 → 路径对不对 → 模型名在不在。按这个顺序，大部分问题 5 分钟内能定位。另外在 Claude Code 里跑一下 /doctor，可以顺手发现安装和版本层面的问题。
回滚：改坏了怎么快速退回
改配置之前先备份，这一步成本几乎为零：
cp ~/.claude/settings.json ~/.claude/settings.json.bak需要回滚时，按范围从小到大处理：
- 只想临时回官方：在当前终端
unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_API_KEY，再启动 claude 并/login。 - 配置写在 settings.json：删掉
env里对应的键，或直接恢复.bak文件。 - 多套环境来回切：写两个 shell 函数，比反复改文件更不容易出错。
