Claude Code Router 接入 OpenRouter，管住模型成本与故障

Claude Code Router 接入 OpenRouter，管住模型成本与故障

【免费下载链接】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 等客户端提供统一的本机端点，按你的规则把请求调度到 OpenRouter、DeepSeek 等上游供应商的具体模型上，并负责重试、降级与请求观测。本文覆盖从安装、接入 OpenRouter、配路由规则，到降级、凭据池与日常排障运维的完整闭环，全部操作在本地终端与管理界面内完成。

CCR 把三件事收进一个本地服务：客户端只认http://127.0.0.1:3456这一个地址，供应商、模型、路由规则、降级策略全部在管理界面里维护，请求结果进日志可查。满足以下任意一条，就值得花 20 分钟接入：

• 你有两个以上模型供应商，或同一供应商的多条 Key 需要轮换；
• 你希望简单任务走便宜模型、关键任务走强模型，而不是每次手动切换；
• 你需要知道每个请求最终打到哪个供应商、哪个模型、消耗了多少 token。

用 ccr ui 启动网关并跑通第一条 OpenRouter 请求

检查 Node.js 环境并安装 CLI

npm CLI 要求 Node.js 22 或更高版本，先确认版本：

node -v

输出v22.x及以上即可继续；低于 22 先升级 Node。

全局安装 CLI 包并启动后台服务：

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

服务拉起后自动打开浏览器管理界面（无桌面环境用ccr ui --no-open，常驻托管用ccr serve --no-open）；浏览器访问http://127.0.0.1:3458出现管理页面即成功。注意区分两个端口：3458是管理界面端口，3456才是模型网关端口，客户端要配的是后者。

添加 OpenRouter 供应商并检测连通性

在供应商页面点击添加，预设列表中选择 OpenRouter，填写以sk-or-v1-开头的 API 密钥，勾选要暴露的模型并保存（目录里没有的模型 ID 可手动添加）。预设供应商无需手填 API 地址，协议与默认模型自动带出。

点检测连通性并对个别模型发一次真实请求，验证地址、密钥、协议和模型名都能用。检测请求会计费，只勾选需要确认的模型，不要一次全量检查；结果中每个模型显示“可用”即成功。

创建客户端 Key 并用 curl 验证网关

在API 密钥页面创建一个 CCR 客户端 Key，把客户端的 base URL 指向http://127.0.0.1:3456。客户端 Key 与发给上游的供应商 Key 是两套东西，别混淆。

验证网关是否在运行：

curl http://127.0.0.1:3456/health

返回200说明网关可用；尚未配置任何供应商时返回502属预期行为。

带 CCR Key 发一个最小模型请求：

curl http://127.0.0.1:3456/v1/chat/completions \ -H "Authorization: Bearer <CCR客户端Key>" \ -d '{"model":"OpenRouter/claude-3.5-sonnet","messages":[{"role":"user","content":"ping"}]}'

拿到正常补全响应即成功；再到日志页面确认request model、resolved provider、resolved model、状态码与耗时都如实记录。安装细节见 安装与启动指南。

为路由规则按场景改写模型，用脚本做动态分流

理解内置路由的默认行为

CCR 的路由分两层。内置路由负责识别 Claude Code 与 Codex 的请求：客户端没有选择可识别模型时，主请求落到 Agent 配置里的默认模型；Codex 访问非 GPT 模型时，apply_patch工具会自动桥接为 function tool，让三方模型也能改文件。这一层无需配置，装完即生效。

在路由页添加自定义规则

自定义规则在路由页面维护，按列表顺序匹配，第一条命中的启用规则生效。一条规则由三部分组成：

条件：来源选request.header或request.body，配合==、starts with、contains deep等操作符；

改写：最常用的一行是把request.body.model设置为供应商/模型选择器，也可以改 temperature 等任意 body 字段；

失败时：这条规则自己的降级策略，覆盖页面顶部的全局默认设置。

常用规则写法对照：

用 Node.js 脚本规则做灰度分流

普通条件不够用时，把规则类型切换为Node.js 脚本：脚本在独立 Worker 沙箱里读取完整请求，可走api.fetch查询外部策略、api.fs读本地文件，返回模型、改写与回退策略；脚本异常时 fail-open，继续检查下一条规则。脚本文件默认超时 2000 毫秒，保存前可在编辑器里用测试请求 JSON 试跑。

if (!input.body.model.startsWith("OpenRouter/claude-")) { return null; } return { model: "OpenRouter/claude-haiku" };

规则编辑器显示脚本验证通过即成功。完整的input/api字段与返回值约定见 路由配置文档。

给模型写 Description 让子代理自动选模

在模型页面为每个模型填写 Description（适合什么任务、速度与成本如何），保存后 CCR 会把说明注入 Claude Code 的 Agent/Task/Workflow 工具描述，派生子代理时客户端自行选模并携带模型标签，CCR 据此把派生请求路由到对应模型。效果是主对话走强推理模型，后台搜索、摘要类子任务自动落到便宜快模型，无需人工干预。

配置模型降级链、凭据池与本地限额

生产环境要防三类故障：上游偶发抖动、主模型限流、单把 Key 打满。对应四个配置项：

降级等待默认从 1 秒开始指数退避，单次最长 30 秒；上游给了正的Retry-After头时优先遵守。全局默认失败处理覆盖所有未单独配置降级的请求，规则级失败时配置覆盖全局设置。发生降级后，响应头会带x-ccr-fallback-attempts等标记，日志详情里也能看到关联的重试尝试列表，方便复盘。

按排障表定位故障，用日志与账号面板做周度运维

运维节奏很固定：每周花 10 分钟翻一次日志页，找出实际高频命中的模型组合，把稳定走旗舰模型但任务并不需要的请求加条件规则改写到性价比更高的模型；看一眼账号面板里 OpenRouter 等供应商的余额与用量趋势；用检测连通性抽查一次备用模型，避免降级时才发现备胎不可用。请求日志只保留本地当天数据，需要长期留存就定期导出。

上线验收清单：

✅ 网关http://127.0.0.1:3456/health返回200，服务页状态为运行中

• 日志页能查到resolved provider/resolved model，与预期路由一致
• 关键工作流配了model-chain降级链，且备用模型通过连通性检测
• 客户端 Key 已分发，供应商 Key 未直接暴露给客户端
• 脚本类规则（如有）已用测试请求验证，超时时间已设置

更细的字段说明见 供应商配置文档。

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