Claude Code Router 配置实践：一个入口接多家上游

为什么需要一层 Router

Claude Code 是原生 Anthropic 协议客户端：它请求 /v1/messages，带 x-api-key，用 tool_use / tool_result 语义。它不接受 OpenAI 格式的端点。

所以你面临一个选择：

• 直接指向一家支持 Anthropic 协议的中转站 —— 简单，但被单一供应商锁定；
• 在中间放一层 Router —— 多一层维护，但可以接任意上游、按规则分流。

Router 解决的核心问题有三个：

1. 协议转换：把 Anthropic 格式的请求转成 OpenAI 格式发给上游，再把响应转回来；
2. 多上游管理：一份配置里放多个上游，按规则选择；
3. 成本路由：简单任务走便宜模型，复杂任务走强模型。

最小可用配置骨架

以 claude-code-router 为例，配置文件的结构大致如下（字段名以你所选项目的文档为准，这里给出的是结构关系）：

{
  "Providers": [
    {
      "name": "upstream-a",
      "api_base_url": "https://<中转站域名>/v1/chat/completions",
      "api_key": "<KEY>",
      "models": ["claude-sonnet-4-6", "claude-opus-4-7"]
    },
    {
      "name": "upstream-b",
      "api_base_url": "https://<另一家>/v1/chat/completions",
      "api_key": "<KEY>",
      "models": ["gpt-5.1", "claude-sonnet-4-6"]
    }
  ],
  "Router": {
    "default":     "upstream-a,claude-sonnet-4-6",
    "background":  "upstream-b,gpt-5.1",
    "think":       "upstream-a,claude-opus-4-7",
    "longContext": "upstream-a,claude-sonnet-4-6"
  }
}

要点说明：

• api_base_url 通常要写到 /v1/chat/completions（OpenAI 兼容端点），而不是只写域名 —— 不同 Router 的要求不同，以文档为准；
• Router 里的值格式是 上游名,模型名，逗号不能省；
• background 走便宜模型是成本优化最明显的一处（后台任务量最大）；
• 配置改完后必须重启 Router 进程，多数实现不热加载。

三类最容易出现的故障

Router 本身是「请求改写层」，而改写就带来协议漂移的风险。按排查顺序：

一、工具调用漂移（最常见）

症状：Claude Code 能正常对话，但改文件、跑命令的行为异常 —— 文件编辑声称成功但内容不对、命令参数被改坏。

成因：Router 在 Anthropic 的 tool_use（input 是对象）与 OpenAI 的 tool_calls（arguments 是字符串）之间转换时出错。

排查：

1. 先绕过 Router，把 Claude Code 直接指向一家原生支持 Anthropic 协议的中转站；
2. 行为恢复正常 → 确认是 Router 的转换问题；
3. 仍然异常 → 问题在上游站点。

这个「二分法」能省掉大量时间。行业里反复被提到的一条经验是：优先选「最小改写、尽量透传」的 Router 实现，改写越少，漂移风险越低。

二、模型名映射错误

症状：Router 请求了一个上游不存在的模型名，返回 404 或 400。

Claude Code 会请求 claude-sonnet-4-5 这类它内置的模型名，而上游可能叫别的名字。Router 需要做映射，映射表由你配置。

排查：看 Router 日志里实际发出的 model 字段。日志是唯一的可靠依据 —— 不要靠猜。

只写系列名（claude-sonnet）通常风险更小，因为上游大多做前缀匹配；写完整版本号则可能出现上游没有该版本的错误。

三、流式分块异常

症状：Claude Code 的终端界面里出现重复 token、缺字，或响应卡住不结束。

成因：OpenAI 的 SSE 与 Anthropic 的 SSE 事件结构不同。转换层如果只做「格式套壳」而不理解事件语义，会出现分块错位。

排查：先用 curl -N 直接打上游的 OpenAI 端点，确认上游本身流式正常；再把 Router 加进来对比。分离出问题在哪一层。

成本路由的实际收益

Router 的分流规则如果配得好，省下来的钱相当可观。经验值：

• 后台任务（生成 commit message、总结文件、生成标题）占调用次数的大头，全部走便宜模型；
• 主对话走中档模型；
• 只在明确需要复杂推理时才用最强模型（think）。

多数人的 Claude Code 用量结构是「大量琐碎调用 + 少量复杂推理」，所以把 background 分流出去，通常能省掉一半以上的费用，而体验几乎无感。

什么时候不该用 Router

• 你只用一家上游，且它原生支持 Anthropic 协议 → 直接接，不需要 Router。少一层就少一类故障。
• 你不愿意维护额外配置 → Router 的配置会随上游变化而需要更新（模型名、endpoint）。
• 你的核心用途是文件编辑和命令执行 → 工具调用的稳定性是硬要求，多一层转换就多一分风险。这种情况优先选原生协议站点。

小结

Router 的价值是解耦：把「客户端」和「上游供应商」之间的绑定关系解开。代价是引入一层需要维护和排错的组件。

判断标准很简单：

• 你的上游可能换 → 值得上 Router；
• 你的上游很稳定 → 不值得。

配置完成后，务必先跑一遍本站《函数调用（tool use）兼容性》那篇里的四个用例 —— 那是最能暴露 Router 转换问题的测试。