Claude Code Router 实战手册：从零基础到本地云混合智能路由的完整路径

Claude Code Router 实战手册：从零基础到本地云混合智能路由的完整路径

【免费下载链接】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）就是中间那层本地模型网关（统一转发请求的代理服务）：它接管编程 Agent 的请求，按路由规则把每次请求派发到合适的供应商与模型。本指南用 CLI 方式，带你 15 分钟内跑通供应商接入、本地模型集成与本地云混合路由的完整流程。

一、项目速览与适用场景

CCR 是面向编程 Agent（如 Claude Code、Codex 这类 AI 编程助手）的本地模型网关与控制平面，由开源社区维护，MIT 协议发布。核心机制一句话概括：所有 Agent 请求统一打到本机127.0.0.1:3456的网关，网关再按供应商配置、路由规则和回退策略（请求失败后自动切换备用模型的机制）把请求送进真正的模型。

判断你是否需要它：

• 同时使用多个 Agent、多个模型供应商，想统一入口和切换
• 希望简单任务走本地模型（如 Ollama 拉起的本地大模型服务），压缩 Token（模型计费的计量单位）成本
• 想集中查看每次请求最终命中的模型、耗时与 Token 消耗
• 不需要：只用一个模型、无任何切换与路由需求
• 不需要：要给公网提供服务，CCR 默认只监听本机地址

二、准备工作与环境检查

最简路径是直接安装 npm 包，装完就有ccr命令：

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

若想从源码运行，先获取代码：

git clone https://gitcode.com/GitHub_Trending/cl/claude-code-router cd claude-code-router

源码方式需再执行npm ci安装依赖，细节参考项目 README 对应章节。

三、核心配置走通

① 接入本地模型

在管理界面供应商页添加 Ollama 供应商（协议选 OpenAI 兼容），表单填好后保存并点「检测连通性」验证 Key 与模型 ID 可真实调用：

{ "name": "ollama", "api_base_url": "http://localhost:11434/v1/chat/completions", "models": ["qwen2.5-coder:latest"] // ... 省略 }

再按同样流程添加一个云端供应商（选内置预设，填 API Key 并勾选模型）。

常见坑：API 地址必须带/v1前缀；连通性检测会发真实请求，建议只勾选要确认的模型。

② 定义路由策略

打开路由页点「添加」创建规则。规则按列表顺序匹配，第一条命中的启用规则改写请求。下面这条规则的意思是：请求消息里出现「架构」二字时，把目标模型改写为云端推理模型：

{ "name": "架构分析走云端", "enabled": true, "condition": { "left": "request.body.messages", "operator": "contains deep", "right": "架构" }, "rewrites": [{ "key": "request.body.model", "operation": "set", "value": "deepseek/deepseek-reasoner" }] // ... 省略 }

常见坑：改写目标必须是 CCR 里已配置的「供应商/模型」，否则规则会被诊断为不命中。

③ 绑定默认参数

在Agent 配置页添加配置，指定该 Agent 的默认模型；试用阶段作用范围选「仅从 CCR 打开时生效」，避免影响你系统里原本直接打开的 Agent：

{ "agent": "claude-code", "name": "本地优先", "model": "ollama/qwen2.5-coder:latest", "scope": "global" }

常见坑：默认模型留空时 CCR 保留 Agent 自身默认模型，不会走你配置的供应商。

四、端到端工作流演示

以「代码补全走本地、架构分析走云端」为任务走一遍完整链路。

先让 Ollama 就绪并拉取代码模型：

ollama serve ollama pull qwen2.5-coder:latest

启动 CCR 并打开管理界面：

ccr ui

浏览器会打开http://127.0.0.1:3458，模型网关在http://127.0.0.1:3456。接着在供应商页完成模块①的两家供应商配置，界面大致如下：

截图左侧是供应商列表，每张卡片展示 API 地址与可用模型标签；右侧路由区可以按场景看到默认模型、后台任务模型等配置。

然后保存模块②的路由规则，用模块③的配置从 CCR 启动 Agent：

ccr "本地优先"

进入会话后，日常补全请求按默认模型走本地 Ollama；当你输入包含「架构」的分析请求时，命中规则改走云端。最后用一条命令确认链路已通：

curl http://127.0.0.1:3456/health

返回正常即网关在跑；再到日志页对照request model（原始请求模型）与resolved model（最终命中模型），即可确认规则确实生效。

五、参数调优与成本对照

以下为单机粗估，耗时与费用请按你的供应商计费和本地硬件换算：

• 补全类任务把 temperature 压到 0.3 以下
• 本地模型响应慢，超时适当调大
• 偶发失败先「继续重试」，再配降级目标

六、故障排查速查

• Agent 连网关被拒 →curl http://127.0.0.1:3456/health→ 在服务页点「启动」或执行ccr stop后重启
• Ollama 模型无响应 →ollama ps看模型是否加载 → 缺模型就ollama pull对应名称
• 3458 打不开管理页 → 看终端打印的实际 URL → CCR 遇端口占用会自动顺延换端口
• 上游返回 401/403 → 核对供应商页的 API Key 与模型勾选 → 重新「检测连通性」
• 规则不命中、日志仍是原模型 → 查日志页resolved model→ 确认改写目标模型已配置且规则开关打开

七、扩展与生态

• Node.js 脚本规则：普通条件不够用时，把规则类型改为本地脚本，可以写租户分流、灰度分桶等动态路由，编辑器内置测试请求可离线试跑。
• 插件目录：packages/electron/bundled-plugins/下有 new-api-account 等内置插件（扩展 CCR 能力的可安装模块），写自定义插件时可直接参考其结构。
• 团队协作：API 密钥页可签发多把客户端 Key 并设置有效期与限额，配合不同 Agent 配置分发给成员即可。

桌面端还内置状态栏（Status Line）监控，显示当前目录、Git 分支、模型与 Token 消耗：

左侧组件面板勾选工作目录、Git 分支、模型、用量等显示项，中间是实时预览，右侧单独设置颜色与图标。

CCR 把多模型路由、回退与观测收敛到一个本地入口，配置、环境变量与第三方工具调用就够你跑通绝大多数场景。下一步可以试：给「架构分析走云端」规则补一条失败降级链，再用ccr stop和ccr start重启验证配置是否仍然生效。

【免费下载链接】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