企业官网建设流程全解析

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-router

Claude Code Router（CCR）是一个本地模型网关：把 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 ui

ccr 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，客户端接错哪个都会失败：

然后到供应商页添加 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 轮换

失败处理提供三种模式，全局默认和单条规则上都能配：

两种兜底的触发条件不一样：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 反复撞限流被上游盯上。

链路出问题时，按这个顺序查 🔍

多数故障都能靠一次判断定位，照顺序过一遍：

1. 管理界面能开、客户端请求失败→ 两个端口是分开的：3458可用不代表3456网关在跑，确认服务页状态为运行中；
2. /health返回502→ 还没有配置任何供应商或模型，属预期行为，补全后重试；
3. 上游返回认证错误→ 十有八九是两套 Key 填反：客户端手里该是 CCR 客户端 Key，供应商 Key 只在 CCR 内部用于上游；
4. 路由规则不生效→ 按序查三处：开关是否启用？规则顺序对不对（先命中先生效）？改写目标是不是已配置的供应商/模型？
5. 某把 Key 频繁被跳过→ 凭据池限额 JSON 是否过紧，或该 Key 在上游已被限流；
6. 疑似请求超时→ 默认 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