Claude Code 接入中转站：完整配置与排错

为什么 Claude Code 的配置容易出问题

Claude Code 走的是 Anthropic 原生协议，和 OpenAI 那套不一样。两个后果：

1. 不是所有中转站都支持 —— 只实现了 OpenAI 协议的站，配了也不通
2. 配置层级比一般工具多 —— 环境变量、配置文件、启动参数三处都可能生效，容易互相覆盖

前置条件：先确认站点支持

在配置之前，先验证站点是否实现了 /v1/messages：

curl -s -o /dev/null -w "%{http_code}\n" -X POST https://站点域名/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: 你的key" \
  -d '{"model":"claude-sonnet-4-5","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

• 返回 200 或 400 → 端点存在，可以继续
• 返回 404 / 405 → 该站不支持，换站

这一步能省掉后面大量的无谓调试。

配置步骤

第一步：设置环境变量

# macOS / Linux
export ANTHROPIC_BASE_URL="https://站点域名"
export ANTHROPIC_AUTH_TOKEN="你的key"

# Windows PowerShell
$env:ANTHROPIC_BASE_URL="https://站点域名"
$env:ANTHROPIC_AUTH_TOKEN="你的key"

要持久化的话，写到 shell 配置文件（~/.zshrc、~/.bashrc）或 Windows 的用户环境变量。

第二步：让配置对命令行可见

如果你是在已有终端里改的环境变量，需要新开一个终端 —— 否则当前会话看不到。

这一步经常被忽略：明明改了配置，运行时却没生效。

第三步：验证

claude --version
claude

在交互界面里让它做点简单的事（比如读一个文件），确认能正常响应。

五类常见报错

报错一：Status 403 或鉴权失败

最容易被误判的一类。 表现是启动就报 403，看起来像 Key 错了。

实际上常见原因是：环境变量没有真正生效。Claude Code 的启动过程有预检，如果它在读取配置文件之前就发起请求，而你只把配置写在了配置文件里，就会 403。

解决：把 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 都写成用户级环境变量（不是只在配置文件里），然后新开终端。

报错二：404 Not Found

原因：站点不支持 /v1/messages。

验证：用上面那条 curl 测一下。404 就是没实现。

报错三：模型不存在

报错信息里带模型名，说明请求发出去了但模型名不对。

各站点对 Claude 模型的别名不统一。解决：请求 /v1/models 看它实际提供的模型 id，用那个名字。

报错四：长上下文时才开始失败

前几个任务正常，跑到项目中期开始报错。

原因：上下文变长后超出该站的实际限制。宣传的上下文窗口不等于实际可用的。

解决：换站，或主动裁剪上下文。

报错五：响应正常但很慢

原因可能是缓存未生效、或站点做了缓冲（先收完整响应再返回）。

验证：让它写一段较长的代码，观察第一个字符出现的时间。如果是「等很久然后一次性全出来」，说明没有流式透传。这种情况在交互式编程里体感很差。

一份排查顺序

1. curl 测 /v1/messages 是否存在     ← 排除协议不支持
2. 确认环境变量在新终端里可见          ← 排除配置未生效
3. 确认模型名与 /v1/models 一致       ← 排除别名问题
4. 用短请求测试                       ← 排除上下文超限
5. 观察首字延迟                       ← 排除无流式

两个实践建议

一、把配置写进项目而不是全局。 如果不同项目要用不同的站，用项目的本地配置覆盖全局，避免互相干扰。

二、保留一份官方渠道的配置。 中转站出问题时能立刻切回去，不至于停摆。

相关阅读

• Claude Code 国内接入的三种方案对比
• 中转站突然报错或变慢，怎么判断是谁的问题
• 常见报错对照表：401/403/404/429/500 分别意味着什么