Source: https://aiprimetech.io/zh/blog/claude-code-router/ 2026 年九月 17 日 · 8 分钟 · 开源 # Claude Code Router：让 Claude Code 使用其他模型（以及何时使用网关更简单） A 作者 [AI Prime Tech](https://aiprimetech.io/zh/) · AI 辅助撰写 Claude Code Router 通过本地网关，让你将 Claude Code 连接到其他模型；该网关负责提供商选择、协议适配和路由。本指南涵盖安装、智能体配置档案、回退机制，以及截至 2026 年 17 月在 v3.1.1 中可用的 OpenCode Go 集成。你还将了解在什么情况下，托管网关可以减少本地设置步骤。 ## Claude Code Router 的作用 musistudio 的 Claude Code Router 通常简称为 CCR，自称是“面向编程智能体的本地模型网关和控制平面”。它为 Claude Code 和其他客户端提供稳定的本地端点，并提供提供商凭据、路由规则、重试、有序回退和请求日志功能。 该 [v3.1.1 README](https://raw.githubusercontent.com/musistudio/claude-code-router/v3.1.1/README.md) 列出了对 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 指南](https://raw.githubusercontent.com/musistudio/claude-code-router/v3.1.1/docs/src/content/docs/en/guides/cli.md) 记录了以下命令： ``` npm install -g @musistudio/claude-code-router ccr --help ccr ui ``` 要在不打开浏览器的情况下启动： ``` ccr ui --no-open ``` 管理界面和模型网关各有独立的默认地址： | 组件 | 默认地址 | 用途 | 管理界面 | http://127.0.0.1:3458 | 配置提供商、配置档案和路由 | 模型网关 | http://127.0.0.1:3456 | 接收来自客户端的模型请求 明确区分这些角色，有助于排查连接在何处失败。管理页面正常工作，本身并不能证明模型网关已接受其配置。 ### 添加提供商和客户端密钥 打开 提供商 → 添加提供商，选择预设或 其他 / 自定义 API 端点，然后输入端点和 API 密钥。CCR 会检测协议和模型； 高级设置 允许你手动选择协议。 使用 检查连接 以测试提供商。这会发送真实请求，因此可能消耗 token 或提供商的部分请求额度。 创建一个 CCR 客户端密钥 在 API 密钥 用于模型请求。该密钥与管理界面/RPC 令牌相互独立：请将客户端访问和管理访问视为不同的配置项。 ### 创建 Claude Code 配置档案 在 智能体配置中，为以下对象创建并启用配置档案： Claude Code，选择一个模型，例如 Provider/model，然后保存。对于名为“Claude Code - Work”的配置档案，使用以下命令启动： ``` ccr "Claude Code - Work" ``` 桌面端生成的启动命令使用 ccr-app。 [Claude Code 配置档案指南](https://raw.githubusercontent.com/musistudio/claude-code-router/v3.1.1/docs/src/content/docs/en/configuration/agents/claude-code.md) 区分了两种作用范围： - 仅从 CCR 打开 会将配置应用于从 CCR 启动的实例。 - 系统默认 也会影响直接启动的 Claude Code。 配置档案支持覆盖 Fable、Opus、Sonnet 和 Haiku 的设置。使用以下命令验证当前选择： /model，然后查看 CCR 的 请求日志 ，以查看经过网关的请求。规划这些选择时，请将 [Claude Code 模型指南](/zh/claude-code/models/) 放在手边以供参考。 ## 配置路由、重试和回退 CCR 路由规则可以检查 request.header 和 request.body，并可以重写 request.body.model。这让你能够根据传入请求控制模型选择，而不局限于智能体配置档案中选择的模型。 回退配置使用 mode, models，以及 retryCount。三种模式分别是 off, retry，以及 model-chain. | 行为 | 相关响应 | 运行效果 | 重试 | 408、409、429 和 5xx | 在符合条件的失败后重试请求 | 回退目标 | 任何 4xx 或 5xx | 可将请求转移到另一个已配置的模型 | 延迟处理 | 正值 Retry-After（如有） | 使用提供的重试延迟 | 默认退避 | 没有正值 Retry-After 适用时 | 从一秒开始，每次尝试的上限为 30 秒 区分重试条件和回退条件十分重要。不符合重试条件的响应，仍可能符合转向回退目标的条件。 ### 检查实际处理请求的模型 模型链可能改变最终处理请求的模型。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://github.com/musistudio/claude-code-router/pull/1786) 记录了发送到 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 参考文档](/zh/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 日公告](https://openrouter.ai/blog/announcements/ori-harness/) 记录了以下连接设置： ``` ANTHROPIC_BASE_URL=https://openrouter.ai/api ANTHROPIC_AUTH_TOKEN= ANTHROPIC_API_KEY= ``` 该公告还说明了其他模型和功能设置。这三个变量是连接设置，并非适用于每个模型的完整配置。OpenRouter 提醒，大多数开放模型不支持工具搜索，因此设置因模型而异。 其 Ori CLI 可通过以下方式自动完成设置： ``` ori login ori claude ``` 同样的工作流也可以通过 AI Prime Tech 等 API 网关运行。AI Prime Tech 是一家独立服务，与 Anthropic 或 OpenAI 无关联；请参阅以下指南： [使用 API 密钥运行 Claude Code](/zh/learn/claude-code-api-key-setup/). 请根据所需的控制能力进行选择。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 端点注入该请求头。 [Claude](/zh/blog/tag/claude/)[编程](/zh/blog/tag/coding/)[开源](/zh/blog/tag/open-source/) A [AI Prime Tech](https://aiprimetech.io/zh/) 本博客由 AI Prime Tech 发布。文章借助 AI 辅助起草；在据此采取行动前，请对照官方文档核实模型 ID、价格和限额等特定版本的细节。 以更低价格接入 Claude API 一个 API 密钥即可使用 Claude Opus 5.5、Sonnet 5、Haiku 4.5 和 Fable 5.1，以及 GPT-6 个模型。按量付费，无需订阅。 [获取 API 密钥 →](/register) AI Prime Tech 是独立的第三方 API 网关。Claude™ 和 Anthropic® 是 Anthropic, PBC 的商标。此处不暗示任何关联或背书。