Claude Code Router：让 Claude Code 使用其他模型（以及何时使用网关更简单）

Claude Code Router 的作用

musistudio 的 Claude Code Router 通常简称为 CCR，自称是“面向编程智能体的本地模型网关和控制平面”。它为 Claude Code 和其他客户端提供稳定的本地端点，并提供提供商凭据、路由规则、重试、有序回退和请求日志功能。

该 v3.1.1 README 列出了对 OpenAI Chat 和 Responses、Anthropic Messages，以及 Gemini Generate Content 和 Interactions 格式的支持。协议适配使得通过 CCR 将 Claude Code 与其他模型配合使用成为可能。

CCR 采用 MIT 许可证，版权归 musistudio 所有，年份为 2025，并按“原样”提供。获准使用该软件并不意味着上游推理免费。提供商收费与额度仍单独计算；截至本文发布日期，尚未核实提供商的历史价格以及 OpenCode Go 以美元计的额度。

相关的 Claude Code Router 3.1 版本

版本 3.1.1 于 2026 年 16 月发布。该版本为 OpenCode Go 本地导入提供一等支持，展示每次失败的网关尝试，并修正了路由模型的用量计费。

该版本还接受 --daemon 在 start 和 serve上，修复了 Docker UI 的日志正文工作线程，并提供 macOS Apple Silicon 和 Intel 构建版本、Windows 安装程序以及 Linux AppImage。下文的设置使用 npm 发行包，以及固定为 v3.1.1 的文档。

安装 CCR 并连接 Claude Code

npm 发行包要求 Node.js 22 或更新版本。 固定版本的 CLI 指南 记录了以下命令：

npm install -g @musistudio/claude-code-router
ccr --help
ccr ui

要在不打开浏览器的情况下启动：

ccr ui --no-open

管理界面和模型网关各有独立的默认地址：

明确区分这些角色，有助于排查连接在何处失败。管理页面正常工作，本身并不能证明模型网关已接受其配置。

添加提供商和客户端密钥

打开 提供商 → 添加提供商，选择预设或 其他 / 自定义 API 端点，然后输入端点和 API 密钥。CCR 会检测协议和模型； 高级设置 允许你手动选择协议。

使用 检查连接 以测试提供商。这会发送真实请求，因此可能消耗 token 或提供商的部分请求额度。

创建一个 CCR 客户端密钥 在 API 密钥 用于模型请求。该密钥与管理界面/RPC 令牌相互独立：请将客户端访问和管理访问视为不同的配置项。

创建 Claude Code 配置档案

在 智能体配置中，为以下对象创建并启用配置档案： Claude Code，选择一个模型，例如 Provider/model，然后保存。对于名为“Claude Code - Work”的配置档案，使用以下命令启动：

ccr "Claude Code - Work"

桌面端生成的启动命令使用 ccr-app。 Claude Code 配置档案指南 区分了两种作用范围：

• 仅从 CCR 打开 会将配置应用于从 CCR 启动的实例。
• 系统默认 也会影响直接启动的 Claude Code。

配置档案支持覆盖 Fable、Opus、Sonnet 和 Haiku 的设置。使用以下命令验证当前选择： /model，然后查看 CCR 的 请求日志 ，以查看经过网关的请求。规划这些选择时，请将 Claude Code 模型指南 放在手边以供参考。

配置路由、重试和回退

CCR 路由规则可以检查 request.header 和 request.body，并可以重写 request.body.model。这让你能够根据传入请求控制模型选择，而不局限于智能体配置档案中选择的模型。

回退配置使用 mode, models，以及 retryCount。三种模式分别是 off, retry，以及 model-chain.

区分重试条件和回退条件十分重要。不符合重试条件的响应，仍可能符合转向回退目标的条件。

检查实际处理请求的模型

模型链可能改变最终处理请求的模型。CCR 日志会显示最终的提供商和模型，因此在排查意外行为或用量时，请使用这些日志。

先使用一个你能明确识别其提供商和模型的配置档案。有规划地添加路由规则和回退目标，然后在实际触发这些规则和目标后检查最终请求去向。这样更容易将响应或成本模式的变化与路由配置联系起来。

版本 3.1.1 还会展示每次失败的网关尝试。这些记录有助于区分最终的成功响应及其之前的各次尝试。

在 v3.1.1 中使用 OpenCode Go 导入

musistudio Claude Code Router v3.1.1 版本为 OpenCode Go 本地导入提供一等支持。该集成将 Zen（标识为 opencode）与 Go（标识为 opencode-go）区分开来，包括各自的凭据以及重叠的模型 ID。

导入工具会读取 OpenCode 配置、 auth.json，以及缓存的模型元数据。 OPENCODE_API_KEY 适用于这两项服务； OPENCODE_GO_API_KEY 提供针对 Go 的覆盖配置。模型发现会按协议筛选模型，并将缓存的元数据与实时 /models 结果进行核对。

为什么会话请求头很重要

该 OpenCode Go 集成 PR 记录了发送到 https://opencode.ai/zen/go/v1 的请求需要 x-opencode-session。如果缺少该请求头，端点会返回 400 MissingSessionID.

CCR 按以下顺序选择会话值：显式配置、显式客户端请求头、Claude 会话请求头、 metadata.user_id，最后是稳定的进程级回退值。请求头注入仅限于官方 Go 端点。

这解释了为什么仅输入端点和凭据可能不足以连接 Go。它的会话要求是提供商集成的一部分。

刷新模型发现并查看用量限额

如果无法导入 Go，请在 OpenCode 中连接 OpenCode Go ，刷新其本地模型缓存，然后在 CCR 中重新扫描。

CCR 从以下位置获取用量： GET https://opencode.ai/zen/go/v1/usage 并显示五小时、每周和每月时间窗口的剩余百分比。固定版本的文档未说明以美元计的额度。请将这些值理解为相应时间窗口的剩余百分比；它们并不代表货币余额。

分阶段排查连接问题

CCR 的故障排查资料涵盖路由被绕过、身份验证失败、模型缺失、模型选择不符合预期、费用激增、超时和智能体跟踪记录缺失等问题。一种有效的诊断顺序是沿着请求路径，从启动配置一直检查到最终提供商。

Claude Code 绕过 CCR

检查是否已启用预期的 Agent Config 配置档案，以及是否通过该档案启动。将配置档案设置为 仅从 CCR 打开 会使其配置仅适用于通过 CCR 启动的情况；选择 系统默认 时，直接启动也会受到影响。

使用 /model 并结合 CCR 请求日志来验证设置。 Claude Code CLI 参考文档 提供了使用该客户端的更全面参考。

身份验证错误或模型缺失

对于 401/403 错误，请检查各个相关层级的凭据：提供商 API 密钥、用于模型请求的 CCR 客户端密钥，以及单独的管理令牌。这些凭据各有不同用途。

对于 model not found，请检查检测到的模型、所选协议，以及配置档案中选择的提供商和模型。使用 OpenCode Go 时，如果无法导入，请刷新本地缓存并重新扫描。

启动失败和超时

版本 3.1.1 将网关接受配置的等待时间从五秒延长至 30 秒。这解决了主机负载较高时管理 UI 已启动但网关启动失败的情况，尤其是在 Windows 上。

CCR_GATEWAY_CONFIG_TIMEOUT_MS 可覆盖超时时间。无效值或低于 1,000 毫秒的值会回退为默认值。

配置存储位置为： ~/.claude-code-router （macOS/Linux）和 %APPDATA%\claude-code-router （Windows）。相关文件包括 config.sqlite、生成的 gateway.config.json，以及 service.json。服务命令包括 ccr start, ccr stop，以及前台运行的 ccr serve.

何时托管网关更简单

CCR 适合需要本地提供商管理、按请求路由、凭据池或显式回退链的工作流。如果您当前的目标是将 Claude Code 连接到上游服务，托管网关可以减少本地设置步骤。

OpenRouter 的 2026 年八月 4 日公告 记录了以下连接设置：

ANTHROPIC_BASE_URL=https://openrouter.ai/api
ANTHROPIC_AUTH_TOKEN=<openrouter-api-key>
ANTHROPIC_API_KEY=

该公告还说明了其他模型和功能设置。这三个变量是连接设置，并非适用于每个模型的完整配置。OpenRouter 提醒，大多数开放模型不支持工具搜索，因此设置因模型而异。

其 Ori CLI 可通过以下方式自动完成设置：

ori login
ori claude

同样的工作流也可以通过 AI Prime Tech 等 API 网关运行。AI Prime Tech 是一家独立服务，与 Anthropic 或 OpenAI 无关联；请参阅以下指南： 使用 API 密钥运行 Claude Code.

请根据所需的控制能力进行选择。CCR 提供一个本地管理环境，可用于管理路由、检查尝试记录和配置回退；文档所述的托管方案则无需在本地运行 CCR。

要点

• Claude Code Router 通过一个稳定的本地端点将 Claude Code 和其他客户端连接到提供商，并提供协议适配。
• npm 分发包要求 Node.js 22+，管理 UI 和模型网关使用不同的默认端口。
• Agent Config 的作用范围决定了配置档案仅适用于通过 CCR 启动的情况，还是也适用于直接启动。
• 回退可能改变实际提供服务的模型；请查看请求日志，确认最终使用的提供商和模型。
• v3.1.1 新增 OpenCode Go 导入功能，使用独立凭据，并处理必需的会话请求头。
• 如果您不需要 CCR 的本地路由控制，托管网关可以减少本地设置工作。

常见问题

Claude Code Router 是免费的吗？

Claude Code Router 采用 MIT 许可证，允许使用该软件。这并不意味着上游推理免费，且此处未核实提供商的历史价格或 OpenCode Go 的美元额度。

我可以通过 CCR 在 Claude Code 中使用其他模型吗？

可以。CCR 提供协议适配以及提供商和模型选择功能，其 Claude Code 配置档案允许您选择模型，例如 Provider/model。支持的上游格式包括 OpenAI Chat/Responses、Anthropic Messages 和 Gemini Generate Content/Interactions。

Claude Code Router 3.1.1 有哪些变化？

v3.1.1 于 2026 年九月 16 日发布，新增对 OpenCode Go 本地导入的原生支持，可查看每次失败尝试，并修正了路由模型的用量计费价格。它还将网关接受配置的等待时间延长至 30 秒，并支持 --daemon 在 start 和 serve.

为什么 OpenCode Go 会返回 MissingSessionID？

官方 OpenCode Go 端点要求提供 x-opencode-session 请求头，并会返回 400 MissingSessionID （当该请求头缺失时）。CCR 的 Go 集成按明确定义的优先顺序选择会话值，且仅为官方 Go 端点注入该请求头。