网关与路由 · gate · 验证于 2026-08-28 ✓ 实测验证

claude-code-router

已验证 2026-08-28安装与基本路由配置实测通过；本地 Agent 控制面，跨模型路由与供应商管理。

本地 Agent 控制面：Claude Code 等跨模型路由与供应商管理，适合同时用多家模型、想集中切换 API 的开发者

详细版 → 所属问题域：网关与路由 遇到问题？去问题空间 →

你会遇到什么

Claude Code 只能锁死一个模型，你想按场景切模型（写代码用一个、问问题用一个），或者你有多个供应商要统一管理——这就是 claude-code-router（CCR）的活儿：本地 Agent 控制面，跨模型路由 + 供应商管理，按 profile 启动不同 Agent（如 ccr default-codex -- --model gpt-5-codex）。但它不是无脑装的：装完会往 ~/.claude/settings.json 注入 env 段（ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN 等），卸载要手动清理；首次运行会提示 No available models（别慌，配个 provider 就好）。 什么时候用：

  • 你要在多个模型/供应商间路由，而不是锁定单一模型；
  • 你要用 profile 管理不同场景的启动参数；
  • 你要一个本地管理界面（ccr ui / ccr start 起的网关）。

什么时候别用：单模型单供应商、不需要路由层时——控制面本身会注入 ~/.claude/settings.json env 并可能起后台进程。

本文路径：快速修复（30 秒一段命令）→ 一步步来（可跳读）→ 怎么确认修好了（成功判据）。赶时间直接跳到「快速修复」。

为什么会这样

npm 全局 CLI ccr。子命令：start（启动网关 + 管理界面，起后台进程）、ui、serve、stop、<profile> [cli|app]（按 profile 启动指定 Agent）。它的路由原理：注入 env 把 Claude Code 的 API 指向本地网关，网关再按 profile 转发到目标模型/供应商。所以注入段是核心机制，也是卸载时要手动清的残留源。 关键概念：

  • profile：一组启动参数/模型路由配置；
  • 注入段：安装时写入 ~/.claude/settings.json 的 env（ANTHROPIC_*）；
  • 网关：ccr start 起的本地进程（管理界面地址）。

装完它动哪里：~/.claude-code-router/（专属配置）+ ~/.claude/settings.json（注入 env 段，卸载手动清理）。

快速修复（不想看讲解，直接跑）

note: 本环境实测路径；国内用 npmmirror 前缀
npm_config_registry=https://registry.npmmirror.com npm install -g @musistudio/claude-code-router --no-audit --no-fund
ccr --help

预期输出: ccr 用法（start/ui/serve/stop/profile 路由）

一步步来

第 1 步：装 CLI

讲解：全局 npm 包，安装即用。国内 npm 直连慢，用 npmmirror registry 前缀。装完 ccr --help 应显示 start/ui/serve/stop/profile 路由。

npm_config_registry=https://registry.npmmirror.com npm install -g @musistudio/claude-code-router --no-audit --no-fund
ccr --help

预期输出: ccr 用法（start/ui/serve/stop/profile 路由）

装好确认：

  • ccr --help 有完整子命令列表；
  • 首次运行提示 No available models 属正常（需先配 provider）。

卡住怎么办：

  • npm 慢/超时 → 确认命令带 npm_config_registry=https://registry.npmmirror.com 前缀；
  • No available models → 正常现象，配置至少一个 provider 后再用。

第 2 步：配 provider + 启动网关

讲解：先配 provider（CLI/管理界面），再 ccr start --no-open 启动网关（会起后台进程；--no-open 不开浏览器）。管理界面地址会输出在启动日志。

ccr start --no-open

预期输出: 网关启动状态；浏览器管理界面地址（--no-open 不开浏览器）

装好确认：

  • 启动日志有管理界面地址；
  • ccr stop 能正常停掉网关。

卡住怎么办：

  • 启动失败 → 确认 provider 已配置；看 ~/.claude-code-router/ 下日志；
  • 端口被占 → 先 stop 再 start，或检查占用进程。

第 3 步：按 Profile 启动指定 Agent

讲解：profile 是启动参数集合——ccr default-codex -- --model gpt-5-codex 以指定 profile 启动 Codex（需先配置该 profile）。这是跨模型路由的核心用法。

ccr default-codex -- --model gpt-5-codex

预期输出: 以指定 profile 启动 Codex（需先配置该 profile）

装好确认：

  • 目标 Agent 以 profile 指定模型启动。

卡住怎么办：

  • profile 不存在 → 先配置 profile（管理界面或配置文件）。

怎么确认修好了

一条命令确认装好，一条命令确认网关可用：

ccr --help

预期输出: ccr start / ccr ui / ccr serve / ccr stop / ccr <profile> [cli|app]（子命令齐全）

ccr stop

预期输出: 网关已停止（能正常停止 = 网关进程可管理）

  • 启动网关后：ccr start 日志里有管理界面地址；
  • 配置 provider 后：按 profile 启动 Agent 不再提示 No available models。

其它环境的表现（常见变体）

  • 桌面端：官方 release 提供 AppImage/dmg/exe（本环境未实测，无显示环境）。
  • Node 版本：>= 22（实测要求）；低版本 npm 安装可能报 engine 警告。
  • 与其它改 env 工具共装：ruflo → 判定 possible-compatible（2026-08-30 部分实测：ruflo 工作区 settings.json env 仅 CLAUDE_FLOW_*/CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS，无 ANTHROPIC_*；本工具注入 HOME settings.json env ANTHROPIC_* 需 provider 配置后触发；ccr 网关启停与 ruflo doctor 并存正常；注入链未全验证，不转 verified）。
  • 与 oh-my-claudecode / agent-governance-toolkit / deepcode：判定 possible-compatible（写面不重叠）。

常用场景（按用户目标）

场景按「你要做什么」组织，不是按命令面；命令均与上文一步步/冒烟同源。

场景 1：启动网关 + 管理界面

多模型路由的底座：先起网关（后台进程），管理界面看路由状态：

ccr start --no-open

预期输出: 网关启动状态；浏览器管理界面地址（--no-open 不开浏览器）

场景 2：按 Profile 启动指定 Agent（多模型路由）

想用指定模型/供应商跑 Codex 或 Claude Code（需先配置该 profile）：

ccr default-codex -- --model gpt-5-codex

预期输出: 以指定 profile 启动 Codex（需先配置该 profile）

场景 3：停止网关 / 查看命令面

ccr stop

预期输出: 网关已停止

ccr --help

预期输出: ccr start / ccr ui / ccr serve / ccr stop / ccr <profile> [cli|app]

数据与目录

  • 专属配置：~/.claude-code-router/；
  • 注入段：~/.claude/settings.json（env：ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN 等）。

卸载与清理

note: npm 包自动卸载 + 专属配置目录自动删；settings.json 注入段手动清理
npm rm -g @musistudio/claude-code-router || true
rm -rf ~/.claude-code-router
command -v ccr >/dev/null 2>&1 && echo "残留: ccr 仍存在" || echo "claude-code-router removed: OK"

预期输出: claude-code-router removed: OK

手动确认清单（通用文件，不自动删）：

  • ~/.claude/settings.json：删除 CCR 注入的 env 段（ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN 等）——保留文件其余内容
  • 桌面端安装的：系统卸载（AppImage/dmg/exe）

依赖警告

  • 版本：[3.0.22, 3.0.22] 锁定（收录实测版本）。
  • 环境：Node >= 22（实测要求）；桌面端 release 二进制需显示环境（本环境未实测）。
  • 网络：npm 用 npmmirror 前缀（国内实测路径）。
  • 写面：~/.claude-code-router/ + ~/.claude/settings.json（env 注入段，卸载手动清理）。
  • 后台进程：ccr start 会起网关进程（ccr stop 停止）。
  • 共装：与 oh-my-claudecode / agent-governance-toolkit / deepcode 判定 possible-compatible；与 ruflo 判定 possible-compatible（2026-08-30 部分实测：env 字段/层级不重叠——ruflo 工作区 CLAUDE_FLOW_* vs 本工具 HOME ANTHROPIC_*；注入链未全验证）。

FAQ（常见问题）

  • 问：ccr --version 没有输出版本号？答：ccr 首次运行提示「No available models」，配置 provider 后正常；版本信息见 ccr --help 或 npm ls -g。
  • 问：和 ruflo 一起装会不会冲突？答：判定 possible-compatible（2026-08-30 部分实测）——ruflo 工作区 settings.json env 仅 CLAUDE_FLOW_*（无 ANTHROPIC_*），本工具注入 HOME settings.json env ANTHROPIC_*（需 provider 配置触发）；ccr 网关启停与 ruflo doctor 并存正常。注入链未全验证：配好 provider 后确认注入段与工作区配置并存。
  • 问：卸载后 ~/.claude/settings.json 的配置还在怎么办？答：CCR 的注入段需手动删除（卸载段清单）；不影响其他配置。
  • 问：网关进程怎么停？答：ccr stop；也可 kill 对应进程。
  • 问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口（usage-report 模板）；项目自身问题请向作者仓库反馈。
验证证据
  • 实测：实测记录（本地留存）（2026-08-28，npm 安装 + ccr --help 冒烟）；实测复现日志（2026-08-30）（教程镜像参数可行：npmmirror 安装 @musistudio/claude-code-router 31 包成功，教程前置条件 node v22 成立）。
  • 未实测：provider 配置与网关启动（首次运行需配置 provider）；桌面端 release 二进制（无显示环境）。

引用：claude-code-router · 验证于 2026-08-28 · v3.0.22~3.0.22

相关问题（问题域）

出问题了？排障方案

排障手册：claude-code-router（L34 批次 1）

症状 → 原因 → 解法 → 验证证据 四段结构。
素材来源：L33 分源记录（CSDN）+ 上游 Issue 检索（#239）+ 项目 docker 文档 + 本市场实测（2026-08-28 隔离 HOME 安装/卸载闭环）。
采集纪律：零账号匿名检索；不破解反爬；未碰 GitHub。check-words HARD 0。

基本信息

  • 条目名称：claude-code-router（musistudio/claude-code-router，MIT，v3.0.22 收录）
  • L33 分源信号：CSDN=8 / 掘金=0 / 知乎=0 / B站=0（强）
  • §14 角色：core；分类：gate
  • 定位：本地 Agent 控制面——跨模型/供应商路由、Profile 切换、网关服务、浏览器管理界面
  • 本市场安装路径：npm CLI（ccr）+ 配置目录 ~/.claude-code-router/；桌面端（release 二进制）另有安装方式
  • 主要安装形态：npm 全局 / npx（免全局）/ 桌面应用（Electron release）

症状 → 原因 → 解法 → 验证证据

1. EBADENGINE：Node 版本不满足 engines

症状

npm install -g @musistudio/claude-code-router 报 EBADENGINE，提示 engine node 不满足要求。

原因

包 engines 要求 Node 20 || >=22；系统 Node 过旧（18/19/21 均不满足）。

解法

  1. 用 nvm 装新版并切换：nvm install 22 && nvm use 22（或 nvm install 20）。
  2. 多 Node 环境（nvm/Windows/WSL 混用）先确认生效版本：node --version、which node。
  3. 满足版本后重试安装。

验证证据

  • 网页案例：CSDN（2026-03，EBADENGINE 场景）。
  • 本市场实测：本环境 Node v22.22.1，安装成功（首行 node: v22.22.1）。

2. WSL 里 node: not found（npm 来自 Windows 侧）

症状

WSL 里执行 ccr 或 npm 全局命令报 node: not found；同一命令在 Windows 侧正常。

原因

npm 包是 Windows 版安装的（脚本 shebang 指向 Windows node），或 PATH 中 Windows 路径优先于 WSL 原生路径。

解法

  1. WSL 内装原生 Node（nvm 或 apt），确保 /usr/bin 在 PATH 中优先。
  2. 重开 shell 验证：which node、node --version。
  3. 不要混用两侧 npm 全局目录（重装到 WSL 侧全局即可）。

验证证据

  • 网页案例：CSDN（2026-03，WSL node: not found 场景）。
  • 本市场实测：WSL 原生 Node v22.22.1 + npm 全局安装链路可用。

3. 首次运行 No available models / 网关起不来

症状

ccr start / ccr serve 提示 No available models. Configure at least one provider...；管理界面没有可用模型。

原因

尚未配置任何 provider（~/.claude-code-router/ 下 provider 配置为空）——首次运行正常现象，不是故障。

解法

  1. ccr start 后浏览器打开管理界面，添加 provider + 模型。
  2. 或直接编辑配置文件（~/.claude-code-router/，本版为 config.sqlite；见 guide.md 配置节）。
  3. 添加后重启网关（ccr stop → ccr start）。

验证证据

  • 本市场实测：ccr --version 输出 No available models. Configure at least one provider with a model before starting CCR Gateway（+ 闭环日志 step 2），符合预期；配置步骤见 站内文档。

4. 本地模型 api_base_url 配置错误（Ollama 等）

症状

配置本地模型（Ollama 等）后请求失败：找不到模型 / 连接拒绝 / 路由报错。

原因

api_base_url 必须写完整 URL（含 /v1/chat/completions 路径）；只写 base（如 http://localhost:11434）或漏 /v1 都会失败（上游 Issue #239 场景）。

解法

  1. 写完整 URL：http://localhost:11434/v1/chat/completions（Ollama 例）。
  2. 模型名与 ollama list 输出一致。
  3. 保存后重启网关再测。

验证证据

  • 上游 Issue #239 + 项目本地模型配置文档。

5. Docker 部署：端口 / volume / 权限

症状

容器能起但浏览器打不开；重启后配置丢失；或 volume 权限报错。

原因

  1. 只暴露 Nginx 8080：3456/3457/3459 是容器内部端口，不需要映射到宿主机。
  2. 未用 named volume：数据随容器重建丢失。
  3. 容器用户与 volume 属主不匹配（镜像文档建议 -u 1000:1000）。

解法

  1. 按项目 docker/README.md 的参数启动：-p 8080:8080 + named volume + -u 1000:1000。
  2. 端口冲突先 docker ps 查占用，换宿主端口（-p 8081:8080）即可。
  3. 数据恢复：volume 挂载到对应数据目录后重启。

验证证据

  • 项目 docker/README.md；网页案例：CSDN（Docker 端口冲突/权限场景）。
  • 本市场未实测 Docker 形态（本地容器环境限制），如实标注。

6. JSON / API 配置错误导致服务启动失败

症状

修改配置后 ccr start 报错或崩溃；管理界面 API 返回 500。

原因

provider/profile 配置 JSON 语法错误或字段名不符（如 api_base_url、type 拼写/结构错误）。

解法

  1. 改前备份配置文件（~/.claude-code-router/）。
  2. 改后用 JSON 校验工具检查语法。
  3. 对照项目配置文档核对字段；改错恢复备份后重启。

验证证据

  • 网页案例：CSDN 汇总篇（服务启动失败 / API / JSON 配置场景）。
  • 本市场实测：写面 = ~/.claude-code-router/config.sqlite，配置修改前先备份该目录。

7. 卸载 / 重装残留（npm 全局 + 配置目录）

症状

重装后配置还是旧的；或卸载后 ccr 命令仍然存在。

原因

npm rm 只删包，~/.claude-code-router/ 配置目录会保留；shell hash 缓存会让已卸载的命令继续命中。

解法

  1. 完整卸载：npm rm -g @musistudio/claude-code-router + rm -rf ~/.claude-code-router。
  2. ~/.claude/settings.json 里的路由 env 注入段（ANTHROPIC_* 等）按 guide.md 卸载段手动确认清理（通用文件，不代删）。
  3. 新 shell 验证：command -v ccr 应为空。
  4. 桌面端（release 二进制）用系统卸载方式，不在 npm 管理范围。

验证证据

  • 本市场实测闭环 2026-08-28：install exit=0 → uninstall（102 包移除 + 配置目录清除）→ verify 零残留（claude-code-router removed: OK + 目录已清，verify exit=0）。

本市场实测安装 / 卸载（2026-08-28）

安装（manifest install.cmd，隔离 HOME=/tmp/l34-ccr/home）：

# 来源: Trove 排障手册 · 验证于 2026-08-28
[install] 执行: npm_config_registry=https://registry.npmmirror.com npm install -g @musistudio/claude-code-router --no-audit --no-fund && ccr --help
changed 102 packages in 54s
Usage: ccr start ... / ccr ui ... / ccr serve ... / ccr stop / ccr <profile-name-or-id> [cli|app] ...
[install] exit=0

卸载（manifest uninstall.cmd + 修正后的 verify）：

# 来源: Trove 排障手册 · 验证于 2026-08-28
[uninstall] 执行: npm rm -g @musistudio/claude-code-router; rm -rf ~/.claude-code-router
removed 102 packages in 139ms
[uninstall] 验证: claude-code-router removed: OK；~/.claude-code-router 已清；verify exit=0
  • 完整日志：实测记录（本地留存）。
  • CLI 冒烟：实测记录（本地留存）（ccr --help/--version；写面 config.sqlite；源码审计 ~/.claude/settings.json env 注入）。
  • 连通性：实测记录（本地留存）（npmmirror 0.26s；codeload 1.73s）。
  • 未能实测：真实路由到模型端点（需 provider 配置）、桌面端 release 二进制、Docker 形态。

冲突标注

  • possible-compatible：oh-my-claudecode / agent-governance-toolkit / deepcode（CLI 面隔离，manifest 对子，见 站内文档）。
  • possible-conflict：ruflo（推断态，manifest 对子）。
  • 专属写面：~/.claude-code-router/（config.sqlite）；~/.claude/settings.json 为通用文件（env 注入段需人工确认）。

名称混淆

  • 命令名 ccr 与包名 @musistudio/claude-code-router：安装/卸载用包名，日常用命令名。
  • 与 claude-mem（记忆插件）区分：ccr 是路由/网关，claude-mem 是记忆存储；两者 npm 包名不同。
  • 与 Claude Code 内置命令/其它同名 "claude code router" 项目区分：本项目检索特征 = musistudio 出品 + v3.x + ccr 命令。

判据（验证状态）

  • 症状清单：
  • [x] Node>=18 / EBADENGINE / EACCES 权限（CSDN 汇总篇；本环境 Node v22.22.1 通过）
  • [x] WSL node: not found（CSDN 2026-03）
  • [x] 服务启动失败 / API / JSON 配置（CSDN 汇总篇）
  • [x] Docker 端口 / volume 配置（项目 docker/README.md + CSDN）
  • [x] 本地模型 api_base_url / 离线安装（上游 Issue #239）
  • 实测步骤：

本站实测记录

  • [x] 卸载验证（manifest uninstall.cmd：npm rm + 配置目录清除 → verify 零残留 exit 0）
  • [x] 网络/镜像场景（npmmirror 0.26s；codeload 1.73s，见）
  • [x] 未能实测项：真实路由到模型端点（需 provider）、桌面端 release 二进制、Docker 形态

验收

  • [x] 症状 → 原因 → 解法 → 验证证据 四段齐全（7 症状）
  • [x] 名称混淆已点名（ccr 命令 vs 包名；与 claude-mem 区分）
  • [x] check-words HARD 0
  • [x] validate 通过
  • [x] 未碰 GitHub / 未用任何账号

所属组合包 （1）

矩阵暂无该工具对子。

← 返回工具货架 ｜ 遇到其它问题？去 问题空间 提交求助卡 ｜ 预检与证据记录由维护流程本地留存，仅公开结论与来源