企业官网建设流程全解析

Claude Code Router 完整指南：用一个本地网关管好所有 AI 编码 Agent

【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-router

Claude Code Router（下文简称 CCR）是一个跑在本机的模型网关与控制台：它在127.0.0.1:3456上提供一个固定地址，把 Claude Code、Codex、Kimi CLI、OpenCode 等编码 Agent 的请求统一收进来，再由你决定每个请求发给哪个供应商、哪个模型、用哪把 API Key，失败时还能自动重试或切换到备用模型。如果你同时维护多个 Agent 的配置文件，或者手里有 Gemini、OpenAI、DeepSeek 等多家供应商的 Key，用它可以把"换模型"这件重复劳动集中到一个地方完成。

接入之后你能得到什么

先说结论：接入 CCR 后，Agent 侧只需要记住一个本地地址，其余变化都发生在 CCR 内部。三个最直观的变化是——

• 换模型不再改 Agent 配置：供应商、模型、Key 都在 CCR 里维护，Agent 配置文件里的指向始终不变。
• 请求失败有兜底：重试、凭据池轮换、有序回退模型，可以在路由层统一配置。
• 每次请求可追溯：日志里能看到最终命中的供应商与模型、状态码、延迟、token 数和估算成本。

它的能力范围如下表：

三种启动方式：桌面应用、CLI 与 Docker

根据使用习惯选一条路径即可，三者启动的是同一套网关，管理界面不同而已。

桌面应用（推荐）：从项目的 release 页下载对应平台的安装包并运行，全程图形化操作，适合首次接触的用户。

npm CLI：需要 Node.js 22 或更高版本，装好后用ccr ui起一个浏览器版管理界面：

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

浏览器打开http://127.0.0.1:3458即可管理，模型网关地址仍为http://127.0.0.1:3456。

Docker：适合服务器或容器化环境，一条命令起服务，管理与网关路由默认暴露在http://127.0.0.1:3458：

docker compose up -d --build

如果想从源码跑起来做开发或二次研究，克隆仓库后用 pnpm 工作区脚本即可：

git clone https://gitcode.com/GitHub_Trending/cl/claude-code-router cd claude-code-router npm ci && npm run dev:cli

首次接入：添加 Gemini 供应商并启动网关

CCR 的运行配置存在本地 SQLite 数据库里（桌面版默认~/.claude-code-router/config.sqlite），官方建议通过界面修改配置、用 Settings 里的导出做备份，不要在服务运行时手改数据库文件。旧版config.json只会在没有 SQLite 配置时作为迁移来源读取一次。

以接入 Gemini 为例，完整流程是"添加供应商 → 启动服务 → 应用 Agent 配置 → 看日志"四步：

1. 打开Providers → Add Provider，选择内置的 Google Gemini 预设。预设已带好上游地址https://generativelanguage.googleapis.com和generate_content、interactions两种协议，你只需填入在 Google AI Studio 申请的 API Key，并勾选要启用的模型。
2. 点击"检测连通性"发一次真实测试请求，确认 Key、协议、模型名三件事都没问题。注意检测是按模型逐个请求的，会产生少量 token 消耗，建议只勾选需要确认的模型。
3. 打开Server页点击Start，网关开始监听默认的http://127.0.0.1:3456。
4. 打开Agent Config，选择你的 Agent（如 Claude Code），选一个默认模型并应用 profile——这一步会改写该 Agent 的配置文件，让它的请求指向 CCR。
5. 从 CCR 启动 Agent 发一条消息，在Logs页核对 resolved provider、模型、状态、延迟和 token 数。

供应商表单里几个容易忽略的字段，实际含义如下（完整字段说明见供应商配置文档）：

路由是怎么决定模型的

CCR 的路由分三层，请求从上到下依次经过：

1. 内置路由：识别 Claude Code 和 Codex 发来的请求。当客户端没有显式选择可识别的模型时，回落到 Agent profile 里设置的默认模型。
2. 自定义规则：按列表顺序逐条匹配，第一条命中的启用规则负责改写请求。条件可以匹配请求头或请求体的任意字段；一个条件不够用时，可以把规则类型切换为 Node.js 脚本，读取完整请求后动态决定目标模型、改写内容和回退策略。
3. 失败处理：请求失败后按策略重试，或切换到有序的备用模型列表。默认配置里回退是关闭的（mode: "off"，retryCount: 1），需要手动启用。

整体路径可以用这张图概括：

脚本规则适合表达多条件判断，比如"默认请求走轻量模型，估算 token 超过 5 万时换成强推理模型"。脚本是一个异步函数体，环境已注入input（包含input.body、input.model、input.tokenCount、input.summary.lastUserText等字段）：

// 返回 null 表示不命中，继续检查下一条规则 if (input.model !== "gemini/gemini-2.0-flash") { return null; } if (input.tokenCount > 50000) { return { model: "gemini/gemini-2.5-pro" }; } return { model: "gemini/gemini-2.5-flash" };

脚本执行异常、超时或返回值无效时采用 fail-open：记录诊断后继续下一条规则，不会把请求卡死。

三个实战场景

场景一：主供应商故障时自动切换。日常请求走 Gemini 的轻量模型，一旦上游失败，回退到另一家供应商的同档模型，Agent 端无感知。操作：在路由页把"默认失败处理"的模式从 off 改为启用，填入备用模型列表（写全"供应商/模型"格式）和重试次数；如果只想给某条规则单独兜底，在该规则的"失败时"字段里覆盖即可。

场景二：给没有视觉能力的模型补上眼睛。CCR 的 Fusion 内置图像能力会把一个视觉模型接在基础文本模型前面，组合后的模型可以像普通模型一样被路由。例如某文本模型本身不支持图片，选择ccr-fusion-builtins / vision_understand并为 Vision model 指定一个 Gemini 视觉模型后，它就能处理截图、图表和 OCR 内容；视觉层失败时先重试视觉模型、再试备用视觉模型，基础文本模型保持不变。

场景三：多把 Key 分摊速率限制。单把 Key 容易触发上游的分钟级限流，CCR 的凭据池可以展开多把 Key，每把 Key 独立设置优先级（数字越小越优先）、权重和本地限额。限额用一段 JSON 表达，达到上限后 CCR 自动跳过这把 Key 换下一把：

{ "rpm": 60, "tpm": 100000 }

rpm/tpm分别是每分钟最多请求数和 token 数，也支持按小时（rph/tph）和按天（rpd/tpd）的窗口。

常见问题处理与成本控制

遇到大多数问题时，第一步都是打开请求日志对比request model、resolved provider和resolved model三个字段，确认请求实际去了哪里，再对症下药（更完整的清单见常见问题文档）：

• Agent 没走 CCR：依次确认服务在运行、Agent 是从 CCR 启动的（而不是直接打开）、Agent 配置已应用且作用范围覆盖当前项目，三项缺一不可。
• 401 / 403：这是凭据问题不是路由问题。核对 Key 是否正确、Base URL 与协议是否匹配，改完用供应商页的"检测连通性"验证。
• model not found：模型名出现在供应商模型列表、路由选中项、Agent 配置三个地方，逐一对比，把不一致的改过来。
• 命中了错误模型：规则是按顺序匹配的，顺序或条件写错就会串。在路由页调整规则顺序，或给条件加上更精确的字段约束。
• 成本突然变高：不要猜，按模型、供应商或凭据筛选日志，看 token 组成和请求体大小，找出贡献增量的请求类型。
• 请求超时：先看日志里的耗时分布，判断慢在上游还是工具调用，再对应调大 timeout（默认API_TIMEOUT_MS为 600000 毫秒）。

成本上有一条实用建议：把日常对话、简单修改路由给轻量模型，把复杂推理和大规模重构留给强模型；连通性检测会消耗真实 token，按需要逐个确认，不要每次全量检测。

最后给三条落地建议：先用一个供应商、一个 Agent 跑通"添加 → 启动 → 应用 → 看日志"四步，再逐步加规则；每次改动路由规则前开启请求日志，改完拿一条真实请求验证命中路径；备份用 Settings 页的导出功能完成。另外提醒一句：不要在 CCR 运行时直接编辑config.sqlite，如果你要把 Docker 部署的 CCR 暴露到局域网或远程访问，请先读一下仓库里的 Docker 部署文档再动手。

【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-router