Claude Code Router 指南4 个问题理清模型网关、路由规则与失败兜底【免费下载链接】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-routerClaude Code RouterCCR是一个本地模型网关把 Claude Code、Codex 等 AI 客户端统一指向http://127.0.0.1:3456这一个地址由它负责挑选上游、执行路由规则、失败降级和多 Key 轮换。适合同时管理多个模型或多把 Key 的开发者。下面围绕四个问题展开装起来、配规则、加兜底、出问题怎么查。请求到底打给了谁先把本地网关跑起来想象一下这个局面白天用 Claude Code 写代码夜里让 Codex 跑批量任务手里有一把 OpenRouter Key 还剩 10 美元、另一把剩 5 美元外加一把便宜的 DeepSeek Key。没有中间层时每个客户端各配各的地址和密钥某把 Key 被限流了整条流程就得停下来改配置。CCR 把这个中间层收成一台本地服务所有客户端只认一个地址请求最终走哪家、走哪个模型由 CCR 集中决定。npm CLI 要求 Node.js 22 或更高版本node -v npm install -g musistudio/claude-code-router ccr uiccr ui会拉起后台服务并打开浏览器管理页无图形界面环境用ccr ui --no-open需要前台常驻用ccr serve --no-open。想容器化部署到服务器则克隆源码后用 Compose 启动git clone https://gitcode.com/GitHub_Trending/cl/claude-code-router cd claude-code-router docker compose up -d --build⚠️先澄清两件最容易搞混的事两个端口、两套 Key客户端接错哪个都会失败易混点容易混淆的说法客户端该配什么端口3458是管理端口浏览器界面3456才是网关端口模型请求base URL 指向http://127.0.0.1:3456Key供应商 API Key 是 CCR 发给上游用的CCR 客户端 Key是客户端访问 CCR 出示的在API 密钥页创建 CCR 客户端 Key别把上游 Key 填进客户端然后到供应商页添加 OpenRouter它是内置预设填以sk-or-v1-开头的 API Key勾选要暴露的模型即可。用「检测连通性」会对所选模型发一次真实请求确认地址、Key 和模型名可用——检测是真实计费的建议只勾选少数需要确认的模型。最后做两个验证curl http://127.0.0.1:3456/health返回 200 说明网关在运行再发一个最小的模型请求到日志页核对请求模型、最终命中的供应商/模型、状态码、耗时都应有记录。链路到此全部打通。请求该用哪个模型写路由规则CCR 的路由分两层。内置路由负责识别客户端类型比如 Claude Code 的请求没有显式选择可识别模型时落到该客户端 Agent 配置里的默认模型。自定义规则由你在路由页维护按列表从上到下匹配第一条命中的启用规则生效。一条规则由三部分组成条件检查request.header或request.body配合、starts with、contains deep可递归搜索嵌套数组等操作符改写最常用的写法是把request.body.model设成供应商/模型选择器也可以顺手改 temperature 等任意 body 字段失败处理这条规则专属的降级策略命中时覆盖页面顶部的全局默认。由此可以做成本分层带x-client-name: batch头的批量请求改写到低价模型交互编码保留旗舰模型。条件表达不够用时把规则类型切换为Node.js 脚本它在沙箱里读取完整请求可做灰度分桶、查外部策略还能用测试请求 JSON 干跑一遍而不用真实上游请求。更多字段说明见 路由文档。子代理该选哪个模型让 Description 替你选Claude Code 的 Agent / Task / Workflow 会派生子请求不必为它们逐条写规则在模型页给每个模型填一段Description适合什么任务、速度如何、成本多少。CCR 会把这些说明注入 Agent / Task / Workflow 的工具描述客户端派生子代理时自行选模并在请求里带上供应商/模型标签CCR 提取标签后把该请求路由过去。效果是主对话留在强推理模型上后台搜索、摘要类子任务自动流向便宜快速的模型全程无人工干预。注意一点——没有任何模型填写 Description 时CCR 不会注入提示词所以这套机制填了才生效不是装完就有。主模型被限流了怎么办降级与 Key 轮换失败处理提供三种模式全局默认和单条规则上都能配模式行为适用场景off只请求当前模型失败即报错低价值任务不需要保证成功retry同一模型重试retryCount次上游偶发抖动、超时、限流model-chain失败后按备用列表顺序逐个尝试不能中断的生产链路两种兜底的触发条件不一样retry只在408/409/429/5xx时触发model-chain对任意4xx/5xx都会切换因为模型不存在、鉴权失败这类错误可能只影响当前目标。切换前会先等待——上游给了正数Retry-After就遵守否则从 1 秒起步、单次最长 30 秒的指数退避。瓶颈不在模型而在 Key 时比如 OpenRouter 余额分散在两个账号展开供应商高级设置里的凭据池每条 Key 有名称、启用开关、优先级数字越小越优先、权重以及本地限额 JSON{rpm: 60, tpm: 100000}某把 Key 达到窗口上限会被自动跳过CCR 转而同供应商的其他 Key 继续不用手动换 Key也避免一把 Key 反复撞限流被上游盯上。链路出问题时按这个顺序查 多数故障都能靠一次判断定位照顺序过一遍管理界面能开、客户端请求失败→ 两个端口是分开的3458可用不代表3456网关在跑确认服务页状态为运行中/health返回502→ 还没有配置任何供应商或模型属预期行为补全后重试上游返回认证错误→ 十有八九是两套 Key 填反客户端手里该是 CCR 客户端 Key供应商 Key 只在 CCR 内部用于上游路由规则不生效→ 按序查三处开关是否启用规则顺序对不对先命中先生效改写目标是不是已配置的供应商/模型某把 Key 频繁被跳过→ 凭据池限额 JSON 是否过紧或该 Key 在上游已被限流疑似请求超时→ 默认 API 超时为600000毫秒足够长先查网络与代理配置。网关的日志页记录每个请求的解析路由、耗时、token 用量与成本估算总览页汇总各供应商的余额与用量。调优节奏可以很简单每周翻一次日志找出实际高频命中的模型组合发现某类低复杂度任务一直落在旗舰模型上就给它加一条条件规则挪到更便宜的模型备用模型链则定期跑连通性检测保证降级真触发时备胎是满的。现在回到路由页把全局默认失败处理设成model-chain、加一个备用模型然后发一次真实请求在日志页确认resolved provider和resolved model两个字段——看到它们这套网关就正式上工了。✅【免费下载链接】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），仅供参考