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 RouterCCR就是中间那层本地模型网关统一转发请求的代理服务它接管编程 Agent 的请求按路由规则把每次请求派发到合适的供应商与模型。本指南用 CLI 方式带你 15 分钟内跑通供应商接入、本地模型集成与本地云混合路由的完整流程。一、项目速览与适用场景CCR 是面向编程 Agent如 Claude Code、Codex 这类 AI 编程助手的本地模型网关与控制平面由开源社区维护MIT 协议发布。核心机制一句话概括所有 Agent 请求统一打到本机127.0.0.1:3456的网关网关再按供应商配置、路由规则和回退策略请求失败后自动切换备用模型的机制把请求送进真正的模型。判断你是否需要它同时使用多个 Agent、多个模型供应商想统一入口和切换希望简单任务走本地模型如 Ollama 拉起的本地大模型服务压缩 Token模型计费的计量单位成本想集中查看每次请求最终命中的模型、耗时与 Token 消耗不需要只用一个模型、无任何切换与路由需求不需要要给公网提供服务CCR 默认只监听本机地址二、准备工作与环境检查检查项确认命令预期结果Node.js 22 及以上node -v输出v22.x或更高模型网关端口 3456 空闲ss -ltn \| grep 3456无输出管理界面端口 3458 空闲ss -ltn \| grep 3458无输出Ollama 可用可选curl -s http://localhost:11434返回 HTTP 200最简路径是直接安装 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 启动 Agentccr 本地优先进入会话后日常补全请求按默认模型走本地 Ollama当你输入包含「架构」的分析请求时命中规则改走云端。最后用一条命令确认链路已通curl http://127.0.0.1:3456/health返回正常即网关在跑再到日志页对照request model原始请求模型与resolved model最终命中模型即可确认规则确实生效。五、参数调优与成本对照以下为单机粗估耗时与费用请按你的供应商计费和本地硬件换算任务类型全云端混合路由全本地短代码补全约 3s / $0.005约 8s / $0约 15s / $0简单问答约 5s / $0.01约 8s / $0约 25s / $0架构分析约 20s / $0.15约 20s / $0.15不建议长文档审查约 30s / $0.3约 35s / $0.05约 90s / $0补全类任务把 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考