Claude Code Router 完整指南用一个本地网关管好所有 AI 编码 Agent【免费下载链接】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 Router下文简称 CCR是一个跑在本机的模型网关与控制台它在127.0.0.1:3456上提供一个固定地址把 Claude Code、Codex、Kimi CLI、OpenCode 等编码 Agent 的请求统一收进来再由你决定每个请求发给哪个供应商、哪个模型、用哪把 API Key失败时还能自动重试或切换到备用模型。如果你同时维护多个 Agent 的配置文件或者手里有 Gemini、OpenAI、DeepSeek 等多家供应商的 Key用它可以把换模型这件重复劳动集中到一个地方完成。接入之后你能得到什么先说结论接入 CCR 后Agent 侧只需要记住一个本地地址其余变化都发生在 CCR 内部。三个最直观的变化是——换模型不再改 Agent 配置供应商、模型、Key 都在 CCR 里维护Agent 配置文件里的指向始终不变。请求失败有兜底重试、凭据池轮换、有序回退模型可以在路由层统一配置。每次请求可追溯日志里能看到最终命中的供应商与模型、状态码、延迟、token 数和估算成本。它的能力范围如下表维度说明支持的 AgentClaude Code、Claude Design、Codex、Grok CLI、Kimi CLI、Kilo Code、OpenCode、Pi、ZCode、WorkBuddy 及兼容 API 的客户端支持的供应商OpenAI、Anthropic、Gemini、OpenRouter、DeepSeek、SiliconFlow、Moonshot、Mistral、Z.AI、Bailian 等预设以及任意自定义兼容端点凭据管理单把 Key 或凭据池多 Key 轮换、优先级、本地限额扩展能力Fusion 视觉/联网搜索、MCP 工具、ToolHub可观测性请求日志、Agent 执行链路、用量与成本估算运行形态桌面应用Windows / macOS / Linux、npm CLI、Docker三种启动方式桌面应用、CLI 与 Docker根据使用习惯选一条路径即可三者启动的是同一套网关管理界面不同而已。桌面应用推荐从项目的 release 页下载对应平台的安装包并运行全程图形化操作适合首次接触的用户。npm CLI需要 Node.js 22 或更高版本装好后用ccr ui起一个浏览器版管理界面npm install -g musistudio/claude-code-router ccr ui浏览器打开http://127.0.0.1:3458即可管理模型网关地址仍为http://127.0.0.1:3456。Docker适合服务器或容器化环境一条命令起服务管理与网关路由默认暴露在http://127.0.0.1:3458docker compose up -d --build如果想从源码跑起来做开发或二次研究克隆仓库后用 pnpm 工作区脚本即可git clone https://gitcode.com/GitHub_Trending/cl/claude-code-router cd claude-code-router npm ci npm run dev:cli首次接入添加 Gemini 供应商并启动网关CCR 的运行配置存在本地 SQLite 数据库里桌面版默认~/.claude-code-router/config.sqlite官方建议通过界面修改配置、用 Settings 里的导出做备份不要在服务运行时手改数据库文件。旧版config.json只会在没有 SQLite 配置时作为迁移来源读取一次。以接入 Gemini 为例完整流程是添加供应商 → 启动服务 → 应用 Agent 配置 → 看日志四步打开Providers → Add Provider选择内置的 Google Gemini 预设。预设已带好上游地址https://generativelanguage.googleapis.com和generate_content、interactions两种协议你只需填入在 Google AI Studio 申请的 API Key并勾选要启用的模型。点击检测连通性发一次真实测试请求确认 Key、协议、模型名三件事都没问题。注意检测是按模型逐个请求的会产生少量 token 消耗建议只勾选需要确认的模型。打开Server页点击Start网关开始监听默认的http://127.0.0.1:3456。打开Agent Config选择你的 Agent如 Claude Code选一个默认模型并应用 profile——这一步会改写该 Agent 的配置文件让它的请求指向 CCR。从 CCR 启动 Agent 发一条消息在Logs页核对 resolved provider、模型、状态、延迟和 token 数。供应商表单里几个容易忽略的字段实际含义如下完整字段说明见供应商配置文档字段作用预设 / 自定义预设套用内置模板地址、协议、默认模型选自定义可接入任意兼容 OpenAI、Anthropic 或 Gemini 协议的服务名称CCR 内部唯一标识路由规则、日志、模型选择都引用这个名字建议短且稳定API 地址上游 Base URL决定请求实际发往哪里也用于协议探测与安全校验API 密钥默认凭据未配置凭据池时所有请求都用这把 Key探测和用量读取同样用它模型暴露给 CCR 的模型 ID 列表路由、Agent 配置、客户端/models响应都基于它路由是怎么决定模型的CCR 的路由分三层请求从上到下依次经过内置路由识别 Claude Code 和 Codex 发来的请求。当客户端没有显式选择可识别的模型时回落到 Agent profile 里设置的默认模型。自定义规则按列表顺序逐条匹配第一条命中的启用规则负责改写请求。条件可以匹配请求头或请求体的任意字段一个条件不够用时可以把规则类型切换为 Node.js 脚本读取完整请求后动态决定目标模型、改写内容和回退策略。失败处理请求失败后按策略重试或切换到有序的备用模型列表。默认配置里回退是关闭的mode: offretryCount: 1需要手动启用。整体路径可以用这张图概括脚本规则适合表达多条件判断比如默认请求走轻量模型估算 token 超过 5 万时换成强推理模型。脚本是一个异步函数体环境已注入input包含input.body、input.model、input.tokenCount、input.summary.lastUserText等字段// 返回 null 表示不命中继续检查下一条规则 if (input.model ! gemini/gemini-2.0-flash) { return null; } if (input.tokenCount 50000) { return { model: gemini/gemini-2.5-pro }; } return { model: gemini/gemini-2.5-flash };脚本执行异常、超时或返回值无效时采用 fail-open记录诊断后继续下一条规则不会把请求卡死。三个实战场景场景一主供应商故障时自动切换。日常请求走 Gemini 的轻量模型一旦上游失败回退到另一家供应商的同档模型Agent 端无感知。操作在路由页把默认失败处理的模式从 off 改为启用填入备用模型列表写全供应商/模型格式和重试次数如果只想给某条规则单独兜底在该规则的失败时字段里覆盖即可。场景二给没有视觉能力的模型补上眼睛。CCR 的 Fusion 内置图像能力会把一个视觉模型接在基础文本模型前面组合后的模型可以像普通模型一样被路由。例如某文本模型本身不支持图片选择ccr-fusion-builtins / vision_understand并为 Vision model 指定一个 Gemini 视觉模型后它就能处理截图、图表和 OCR 内容视觉层失败时先重试视觉模型、再试备用视觉模型基础文本模型保持不变。场景三多把 Key 分摊速率限制。单把 Key 容易触发上游的分钟级限流CCR 的凭据池可以展开多把 Key每把 Key 独立设置优先级数字越小越优先、权重和本地限额。限额用一段 JSON 表达达到上限后 CCR 自动跳过这把 Key 换下一把{ rpm: 60, tpm: 100000 }rpm/tpm分别是每分钟最多请求数和 token 数也支持按小时rph/tph和按天rpd/tpd的窗口。常见问题处理与成本控制遇到大多数问题时第一步都是打开请求日志对比request model、resolved provider和resolved model三个字段确认请求实际去了哪里再对症下药更完整的清单见常见问题文档Agent 没走 CCR依次确认服务在运行、Agent 是从 CCR 启动的而不是直接打开、Agent 配置已应用且作用范围覆盖当前项目三项缺一不可。401 / 403这是凭据问题不是路由问题。核对 Key 是否正确、Base URL 与协议是否匹配改完用供应商页的检测连通性验证。model not found模型名出现在供应商模型列表、路由选中项、Agent 配置三个地方逐一对比把不一致的改过来。命中了错误模型规则是按顺序匹配的顺序或条件写错就会串。在路由页调整规则顺序或给条件加上更精确的字段约束。成本突然变高不要猜按模型、供应商或凭据筛选日志看 token 组成和请求体大小找出贡献增量的请求类型。请求超时先看日志里的耗时分布判断慢在上游还是工具调用再对应调大 timeout默认API_TIMEOUT_MS为 600000 毫秒。成本上有一条实用建议把日常对话、简单修改路由给轻量模型把复杂推理和大规模重构留给强模型连通性检测会消耗真实 token按需要逐个确认不要每次全量检测。最后给三条落地建议先用一个供应商、一个 Agent 跑通添加 → 启动 → 应用 → 看日志四步再逐步加规则每次改动路由规则前开启请求日志改完拿一条真实请求验证命中路径备份用 Settings 页的导出功能完成。另外提醒一句不要在 CCR 运行时直接编辑config.sqlite如果你要把 Docker 部署的 CCR 暴露到局域网或远程访问请先读一下仓库里的 Docker 部署文档再动手。【免费下载链接】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），仅供参考 Claude Code Router 完整指南：用一个本地网关管好所有 AI 编码 Agent
Claude Code Router 完整指南用一个本地网关管好所有 AI 编码 Agent【免费下载链接】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 Router下文简称 CCR是一个跑在本机的模型网关与控制台它在127.0.0.1:3456上提供一个固定地址把 Claude Code、Codex、Kimi CLI、OpenCode 等编码 Agent 的请求统一收进来再由你决定每个请求发给哪个供应商、哪个模型、用哪把 API Key失败时还能自动重试或切换到备用模型。如果你同时维护多个 Agent 的配置文件或者手里有 Gemini、OpenAI、DeepSeek 等多家供应商的 Key用它可以把换模型这件重复劳动集中到一个地方完成。接入之后你能得到什么先说结论接入 CCR 后Agent 侧只需要记住一个本地地址其余变化都发生在 CCR 内部。三个最直观的变化是——换模型不再改 Agent 配置供应商、模型、Key 都在 CCR 里维护Agent 配置文件里的指向始终不变。请求失败有兜底重试、凭据池轮换、有序回退模型可以在路由层统一配置。每次请求可追溯日志里能看到最终命中的供应商与模型、状态码、延迟、token 数和估算成本。它的能力范围如下表维度说明支持的 AgentClaude Code、Claude Design、Codex、Grok CLI、Kimi CLI、Kilo Code、OpenCode、Pi、ZCode、WorkBuddy 及兼容 API 的客户端支持的供应商OpenAI、Anthropic、Gemini、OpenRouter、DeepSeek、SiliconFlow、Moonshot、Mistral、Z.AI、Bailian 等预设以及任意自定义兼容端点凭据管理单把 Key 或凭据池多 Key 轮换、优先级、本地限额扩展能力Fusion 视觉/联网搜索、MCP 工具、ToolHub可观测性请求日志、Agent 执行链路、用量与成本估算运行形态桌面应用Windows / macOS / Linux、npm CLI、Docker三种启动方式桌面应用、CLI 与 Docker根据使用习惯选一条路径即可三者启动的是同一套网关管理界面不同而已。桌面应用推荐从项目的 release 页下载对应平台的安装包并运行全程图形化操作适合首次接触的用户。npm CLI需要 Node.js 22 或更高版本装好后用ccr ui起一个浏览器版管理界面npm install -g musistudio/claude-code-router ccr ui浏览器打开http://127.0.0.1:3458即可管理模型网关地址仍为http://127.0.0.1:3456。Docker适合服务器或容器化环境一条命令起服务管理与网关路由默认暴露在http://127.0.0.1:3458docker compose up -d --build如果想从源码跑起来做开发或二次研究克隆仓库后用 pnpm 工作区脚本即可git clone https://gitcode.com/GitHub_Trending/cl/claude-code-router cd claude-code-router npm ci npm run dev:cli首次接入添加 Gemini 供应商并启动网关CCR 的运行配置存在本地 SQLite 数据库里桌面版默认~/.claude-code-router/config.sqlite官方建议通过界面修改配置、用 Settings 里的导出做备份不要在服务运行时手改数据库文件。旧版config.json只会在没有 SQLite 配置时作为迁移来源读取一次。以接入 Gemini 为例完整流程是添加供应商 → 启动服务 → 应用 Agent 配置 → 看日志四步打开Providers → Add Provider选择内置的 Google Gemini 预设。预设已带好上游地址https://generativelanguage.googleapis.com和generate_content、interactions两种协议你只需填入在 Google AI Studio 申请的 API Key并勾选要启用的模型。点击检测连通性发一次真实测试请求确认 Key、协议、模型名三件事都没问题。注意检测是按模型逐个请求的会产生少量 token 消耗建议只勾选需要确认的模型。打开Server页点击Start网关开始监听默认的http://127.0.0.1:3456。打开Agent Config选择你的 Agent如 Claude Code选一个默认模型并应用 profile——这一步会改写该 Agent 的配置文件让它的请求指向 CCR。从 CCR 启动 Agent 发一条消息在Logs页核对 resolved provider、模型、状态、延迟和 token 数。供应商表单里几个容易忽略的字段实际含义如下完整字段说明见供应商配置文档字段作用预设 / 自定义预设套用内置模板地址、协议、默认模型选自定义可接入任意兼容 OpenAI、Anthropic 或 Gemini 协议的服务名称CCR 内部唯一标识路由规则、日志、模型选择都引用这个名字建议短且稳定API 地址上游 Base URL决定请求实际发往哪里也用于协议探测与安全校验API 密钥默认凭据未配置凭据池时所有请求都用这把 Key探测和用量读取同样用它模型暴露给 CCR 的模型 ID 列表路由、Agent 配置、客户端/models响应都基于它路由是怎么决定模型的CCR 的路由分三层请求从上到下依次经过内置路由识别 Claude Code 和 Codex 发来的请求。当客户端没有显式选择可识别的模型时回落到 Agent profile 里设置的默认模型。自定义规则按列表顺序逐条匹配第一条命中的启用规则负责改写请求。条件可以匹配请求头或请求体的任意字段一个条件不够用时可以把规则类型切换为 Node.js 脚本读取完整请求后动态决定目标模型、改写内容和回退策略。失败处理请求失败后按策略重试或切换到有序的备用模型列表。默认配置里回退是关闭的mode: offretryCount: 1需要手动启用。整体路径可以用这张图概括脚本规则适合表达多条件判断比如默认请求走轻量模型估算 token 超过 5 万时换成强推理模型。脚本是一个异步函数体环境已注入input包含input.body、input.model、input.tokenCount、input.summary.lastUserText等字段// 返回 null 表示不命中继续检查下一条规则 if (input.model ! gemini/gemini-2.0-flash) { return null; } if (input.tokenCount 50000) { return { model: gemini/gemini-2.5-pro }; } return { model: gemini/gemini-2.5-flash };脚本执行异常、超时或返回值无效时采用 fail-open记录诊断后继续下一条规则不会把请求卡死。三个实战场景场景一主供应商故障时自动切换。日常请求走 Gemini 的轻量模型一旦上游失败回退到另一家供应商的同档模型Agent 端无感知。操作在路由页把默认失败处理的模式从 off 改为启用填入备用模型列表写全供应商/模型格式和重试次数如果只想给某条规则单独兜底在该规则的失败时字段里覆盖即可。场景二给没有视觉能力的模型补上眼睛。CCR 的 Fusion 内置图像能力会把一个视觉模型接在基础文本模型前面组合后的模型可以像普通模型一样被路由。例如某文本模型本身不支持图片选择ccr-fusion-builtins / vision_understand并为 Vision model 指定一个 Gemini 视觉模型后它就能处理截图、图表和 OCR 内容视觉层失败时先重试视觉模型、再试备用视觉模型基础文本模型保持不变。场景三多把 Key 分摊速率限制。单把 Key 容易触发上游的分钟级限流CCR 的凭据池可以展开多把 Key每把 Key 独立设置优先级数字越小越优先、权重和本地限额。限额用一段 JSON 表达达到上限后 CCR 自动跳过这把 Key 换下一把{ rpm: 60, tpm: 100000 }rpm/tpm分别是每分钟最多请求数和 token 数也支持按小时rph/tph和按天rpd/tpd的窗口。常见问题处理与成本控制遇到大多数问题时第一步都是打开请求日志对比request model、resolved provider和resolved model三个字段确认请求实际去了哪里再对症下药更完整的清单见常见问题文档Agent 没走 CCR依次确认服务在运行、Agent 是从 CCR 启动的而不是直接打开、Agent 配置已应用且作用范围覆盖当前项目三项缺一不可。401 / 403这是凭据问题不是路由问题。核对 Key 是否正确、Base URL 与协议是否匹配改完用供应商页的检测连通性验证。model not found模型名出现在供应商模型列表、路由选中项、Agent 配置三个地方逐一对比把不一致的改过来。命中了错误模型规则是按顺序匹配的顺序或条件写错就会串。在路由页调整规则顺序或给条件加上更精确的字段约束。成本突然变高不要猜按模型、供应商或凭据筛选日志看 token 组成和请求体大小找出贡献增量的请求类型。请求超时先看日志里的耗时分布判断慢在上游还是工具调用再对应调大 timeout默认API_TIMEOUT_MS为 600000 毫秒。成本上有一条实用建议把日常对话、简单修改路由给轻量模型把复杂推理和大规模重构留给强模型连通性检测会消耗真实 token按需要逐个确认不要每次全量检测。最后给三条落地建议先用一个供应商、一个 Agent 跑通添加 → 启动 → 应用 → 看日志四步再逐步加规则每次改动路由规则前开启请求日志改完拿一条真实请求验证命中路径备份用 Settings 页的导出功能完成。另外提醒一句不要在 CCR 运行时直接编辑config.sqlite如果你要把 Docker 部署的 CCR 暴露到局域网或远程访问请先读一下仓库里的 Docker 部署文档再动手。【免费下载链接】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），仅供参考