Claude Code Router 部署实践：本地统一编码智能体模型网关

一、项目介绍

Claude Code Router（下文简称 CCR）是一个运行在本机的模型网关与控制平面，作者把它定位成"在一个地方管理所有编码智能体与模型服务商"。它的核心思路是：不再让 Claude Code、Codex、Grok CLI、Kimi CLI、Kilo Code、OpenCode、Pi、ZCode、Claude Design、WorkBuddy 等客户端各自维护一套模型配置，而是让这些智能体全部指向同一个稳定的本地地址，再由 CCR 在背后统一完成服务商选择、模型切换、密钥轮换、失败回退与请求观测。

对个人开发者而言，CCR 解决的是一个很现实的痛点：当你同时在多个编码智能体里写代码，又想在 OpenRouter、DeepSeek、Moonshot、SiliconFlow、智谱百炼、Z.AI、Mistral 等不同服务商之间比价、试用和切换时，逐个修改客户端配置文件既繁琐又容易出错。CCR 在本机开一个固定端口，智能体只认这一个地址，之后换服务商、换模型、加备用线路，都在 CCR 的控制台里完成，智能体的工作流完全不用动。

CCR 支持的上游协议相当全，涵盖 OpenAI Chat 与 Responses、Anthropic Messages、Gemini Generate Content 与 Interactions，以及 OpenRouter、DeepSeek、SiliconFlow、Moonshot、Kimi Code、Mistral、Z.AI、百炼等内置预设，也支持任何自定义兼容端点。在能力上，它提供路由规则、按顺序排列的失败回退、密钥池与密钥轮换、请求日志、Fusion 视觉模型、联网搜索、MCP 工具与 ToolHub 扩展，还能通过 AgentClaw 把智能体中继到企业微信、飞书、钉钉、Slack、Discord、Telegram 等 IM 通道。

典型的使用场景是这样的：白天预算充足时，让日常编码走响应更快的旗舰模型；遇到需要长上下文阅读大型仓库时，自动切到长上下文模型；夜间或大批量重构时，切到价格更低的开源模型。这些策略全部在 CCR 里以规则的形式声明一次，所有接入的智能体同时受益，而不必在每个客户端里重复配置。对团队而言，集中的密钥池与用量统计也让成本可观测、可限额。

上图是桌面版总览面板，可以看到本地网关端点、各服务商的配额与余额、一段时间内的请求数、输入输出与缓存 token 用量，以及估算成本。所有经过网关的请求，最终解析到了哪个服务商、哪个模型、哪把密钥，状态、延迟、token 消耗如何，都能在日志里逐条回看。

二、项目结构

CCR 是一个多包仓库，围绕"网关运行时 + 管理界面 + 文档站"三块组织源码。理解它的目录结构，有助于在需要二次开发或排查插件行为时快速定位。

仓库根目录下，packages/ui 是基于 Electron 的桌面管理界面，内置了提供商管理、路由编排、智能体配置档案、可观测性与扩展等页面；blog/images 存放 README 与文档站使用的截图素材；docs 目录对应公开文档站 ccrdesk.top 的源码，里面包含各平台图标与提供商图标资源。网关运行时本身以插件化方式组织，CLI 启动时会加载具备插件能力的 ai-gateway 运行时，用户本地的插件通常落在 ~/.claude-code-router/plugins/ 目录下，例如改写请求头或限制温度的自定义 transformer。

对外发布物分成三条线：一条是 npm 包 @musistudio/claude-code-router，通过全局命令 ccr 启动同样的网关与浏览器管理界面；一条是 GitHub Releases 里的桌面安装包，分别提供 Windows 的 exe、Linux 的 AppImage 与 macOS 的 dmg；还有一条是 Docker 镜像，通过仓库脚本一键拉起。License 采用 MIT 协议，个人与团队都可自由使用与二次分发。

从职责上看，整个系统可以拆成三层：最上层是面向人的管理界面（桌面 UI 或 3458 控制台），负责登记服务商、编排路由、发放密钥与查看报表；中间层是常驻本机的网关进程，负责接收智能体请求、按规则解析上游、执行重试与回退、记录日志；最下层是你所购买或自建的各家模型服务，网关对它们保持透明，只在需要时注入凭证、改写请求或追加工具调用。理解这三层，后面排错时就能快速判断问题出在界面配置、网关规则还是上游服务商本身。

三、版本与环境要求

在动手之前，先确认本机环境满足要求。如果你选择 CLI 方式，官方明确要求 Node.js 22 或更高版本，因为 npm 包与网关运行时使用了较新的 Node API。建议通过 nvm、fnm 等版本管理器安装 Node 22 LTS，并在终端用 node -v 确认大版本号不低于 22。

如果你选择桌面版，则不需要预装 Node，直接在 Releases 页面下载对应平台的安装包即可。当前 README 提供的桌面版本为 3.1.3，包含 Windows 安装包 Claude-Code-Router_3.1.3.exe、Linux 的 .AppImage，以及 macOS 的两个 dmg——分别对应 Apple Silicon（arm64）与 Intel（x64）芯片，下载时注意按自己的芯片选择。

Docker 方式适合希望把网关跑在服务器或常驻容器里的用户，官方提供了 compose 脚本，但 README 特别提醒：在把 CCR 暴露到公网之前，务必先阅读 Docker 部署指南并配置好鉴权，因为网关一旦暴露，等于把你所有模型密钥的调用入口开放了出去。系统层面，macOS、Windows 与主流 Linux 发行版均可运行，网关默认监听本机回环地址，不会对外暴露端口。

四、本地部署步骤

本地部署最常见的方式是 CLI。打开终端，执行下面两行命令：第一行全局安装 npm 包，第二行启动管理界面。

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

启动后，浏览器管理界面运行在 http://127.0.0.1:3458，而模型网关本身监听在 http://127.0.0.1:3456。需要强调的是，这两个端口职责不同：3458 是给人用的控制台，3456 是给智能体和程序调用的 API 入口，不要混淆。

接下来按"提供商 → 服务器 → 智能体档案"的顺序配置。第一步，打开 Providers 页面，点击 Add Provider。你可以选择一个内置预设（例如 DeepSeek、Moonshot、OpenRouter），也可以填一个自定义端点；粘贴该服务商的 API Key，选择协议类型并勾选要用的模型，保存即可。CCR 会自动做协议探测与模型发现，部分支持本地登录导入的服务商还能直接同步登录态。如果你的同一服务商有多把密钥，可以把它们放进同一个凭证池，网关会在请求时轮换使用。

第二步，打开 Server 页面，点击 Start，让本地网关跑起来。启动成功后，Endpoint 处会显示 http://127.0.0.1:3456。第三步，打开 Agent Config，选择你正在用的智能体（Claude Code、Codex、Kimi CLI 等），为它选定一个默认模型并 Apply 这份档案。CCR 会自动把对应的环境变量写入，例如把 ANTHROPIC_BASE_URL 指向本地网关，让智能体发出的请求先经过 CCR。

第四步，回到你平时的智能体里正常对话，然后切回 CCR 的 Logs 页面确认：每一条请求是否解析到了预期的服务商与模型，状态码、延迟、token 数与错误信息是否正常。如果需要在默认模型之外加条件、重试、请求改写或备用模型，打开 Routing 页面配置即可。想用 Docker 的话，在仓库根目录执行 npm run docker:compose:up，默认同样通过 3458 提供管理界面、3456 提供网关路由。

五、浏览器端部署与桌面控制台

如果你不想碰命令行，官方更推荐直接使用桌面版。到 Releases 下载对应平台的安装包，按系统提示安装后启动，会看到与上文截图一致的深色控制台。它把 CLI 版的全部能力装进了一个原生应用：左侧导航依次是总览、Providers、Agent Config、Routing、Fusion、API Keys、Models、Observability、Logs、Server 与 Extensions。

上图是控制台里 Providers 与 Router 并排的配置视图。左侧列出了已添加的服务商及其端点与可用模型标签，例如 Kimi 指向 Moonshot 端点、OpenRouter 聚合了多个 Anthropic 与 Google 模型、Ollama 指向本地 localhost:11434；右侧 Router 区域则按场景分配模型：Default 是日常对话默认线路，Background 处理后台轻量请求，Think 分配给擅长推理的思考型模型，Long Context 在上下文超过阈值（示例中为 60000）时自动切换到长上下文模型，Web Search 则交给支持联网搜索的模型。这种按请求特征分流的方式，就是 CCR"路由"二字的实际含义。

在 Routing 规则里，你可以依据请求头与请求体设置条件，配置前缀匹配、请求改写、重试次数，以及按顺序排列的 fallback 列表——主模型失败后自动落到第一个备用模型，再失败继续向下，从而在某家服务商限流或抖动时保证编码智能体不中断。Custom Transformers 区域允许挂载本地脚本，对经过网关的请求做统一改写，例如强制限制最大温度或注入项目级工具说明。API Keys 页面可以为不同客户端单独发放带过期时间与请求、token、图像限额的密钥，便于在家人、同事或多台设备之间隔离用量。

除了基础路由，控制台还提供两类扩展能力。一类是 Fusion 与 ToolHub：Fusion 允许把不具备视觉能力的文本模型与一个视觉模型组合，让纯文本模型在遇到截图或图片时自动转交给视觉模型处理，从而补齐多模态短板；ToolHub 与内置浏览器自动化、Chrome 登录态导入，则让网关可以在请求过程中按需调用联网搜索或抓取网页内容。另一类是 Observability 与 Logs：每一次请求的响应体、解析到的服务商与密钥、状态码、延迟、输入输出与缓存 token、估算成本、工具调用记录乃至智能体的调用轨迹都被落盘，方便事后复盘一次复杂任务到底花了多少、慢在哪一步。

六、API 用法：以 OpenAI 兼容端点调用

CCR 的网关对程序而言就是一个标准的 OpenAI 兼容服务。本地启动后，任何支持自定义 base URL 的 OpenAI SDK 或 HTTP 客户端，都可以把地址指向 http://127.0.0.1:3456/v1 直接调用。下面是一个最小的 curl 示例，演示如何向网关发起一次对话补全：

curl http://127.0.0.1:3456/v1/chat/completions \
  -H "Authorization: Bearer $CCR_CLIENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openrouter/anthropic/claude-sonnet-4",
    "messages": [{"role": "user", "content": "用一句话解释什么是模型网关"}]
  }'

这里的 model 写法是"服务商预设名 / 模型名"，与你在 Providers 里注册的标签对应；Authorization 使用在 CCR 的 API Keys 页面签发的客户端密钥，而不是上游服务商的原始密钥。CCR 收到请求后，根据 Routing 规则决定实际走哪家上游、哪把密钥，再把响应以 OpenAI 兼容格式原样返回。除了 Chat Completions，网关同时暴露 Anthropic Messages 兼容入口，供 Claude Code 这类原生使用 Anthropic 协议的智能体接入；Gemini 协议的客户端也可按对应路径调用。

这张调试截图展示了理解 CCR 工作原理的关键：编码智能体内部的 Anthropic SDK 在构造客户端时会读取 ANTHROPIC_BASE_URL 环境变量。CCR 的 Agent Config 档案本质上就是把这个变量改写为本地网关地址，于是原本直连 api.anthropic.com 的请求被透明地截获到 127.0.0.1:3456，再由网关转发到你选定的任何上游。这种"协议透明、本地截获"的设计，让 CCR 无需修改智能体源码即可统一接入多家模型。

七、常见问题 FAQ

问一：启动时提示 3456 或 3458 端口被占用怎么办？ 这两个端口分别是网关与管理界面，如果本机已有其他程序占用，可以在启动参数或 Server 设置里更换端口，注意智能体配置档案里的 base URL 要同步改成新端口；CLI 方式的完整服务模式与鉴权参数可查阅 CLI 参考文档。

问二：配置好服务商后请求仍然失败？ 先在 Providers 页面用连通性检查确认端点可达、密钥有效；再到 Logs 页面看具体错误——常见原因是模型名拼写不一致、协议类型选错（Chat 与 Responses 不能混用），或上游账号余额不足。CCR 会把上游返回的错误透传出来，对照排查即可。

问三：怎样实现主模型挂了自动切换？ 在 Routing 规则里为对应场景配置 ordered fallback 列表，按优先级从高到低排列备用模型；同时为服务商开启重试，并把多把密钥加入凭证池做轮换。这样单次请求在主线路失败后会自动重试并落到备用线路，编码过程不会因为某家服务商抖动而中断。

问四：能不能把 CCR 部署到服务器上多设备共用？ 可以通过 Docker 部署，但官方明确建议：在远程暴露之前务必配置客户端密钥鉴权与访问控制，因为 3456 端口一旦对公网开放，就等于公开了一个能消耗你所有模型额度的代理。具体做法参见 Docker 部署指南。

问五：CLI 版和桌面版有什么区别，该选哪个？ 两者启动的是同一个网关，能力一致。区别在于桌面版基于 Electron，开箱即用、带原生窗口与托盘，适合日常以图形界面管理；CLI 版通过 npm 安装，启动后用浏览器访问 3458 控制台，适合服务器、自动化脚本或偏好命令行的用户。详细排错思路可参考官方故障排查文档。