Claude Code Router（musistudio 出品，MIT，约 3.7 万星）是一个本地控制面：把 Claude Code / Codex 等 Agent 的请求路由到不同模型和供应商，统一管理 API key、模型选择、请求日志。它有两种形态：桌面应用（图形界面）和 npm CLI（ccr，Node 22+ 即可，无需 Electron）。

一句话：多个模型/供应商之间"拨号上网"，一个控制面板管所有 Agent 的模型接入。

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 并可能起后台进程。

note: 本环境实测路径；国内用 npmmirror 前缀

# 来源: Trove 详细指南 · 验证于 2026-08-28
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 路由）

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

# 来源: Trove 详细指南 · 验证于 2026-08-28
ccr --help

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

# 来源: Trove 详细指南 · 验证于 2026-08-28
ccr stop

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

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

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 段，卸载手动清理）。

• ~/.claude-code-router/：自身配置（config.sqlite，实测生成）
• ~/.claude/settings.json：路由 env 注入段（源码审计确认：设置 ANTHROPIC_* 等环境变量实现路由）
• 运行时：ccr start/serve 起网关进程（端口绑定）

第 1 步：装 CLI

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

# 来源: Trove 详细指南 · 验证于 2026-08-28
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 不开浏览器）。管理界面地址会输出在启动日志。

# 来源: Trove 详细指南 · 验证于 2026-08-28
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）。这是跨模型路由的核心用法。

# 来源: Trove 详细指南 · 验证于 2026-08-28
ccr default-codex -- --model gpt-5-codex

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

装好确认：

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

卡住怎么办：

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

与工具页矩阵同源，共 19 对（2 实测兼容 / 15 推断可能兼容 / 2 推断可能冲突）；完整对子、状态与证据见 冲突对子（共装矩阵）。

• 症状：EBADENGINE：Node 版本不满足 engines
• 症状：WSL 里 node: not found（npm 来自 Windows 侧）
• 症状：首次运行 No available models / 网关起不来
• 症状：本地模型 api_base_url 配置错误（Ollama 等）
• 症状：Docker 部署：端口 / volume / 权限
• 症状：JSON / API 配置错误导致服务启动失败

四段式全文（症状→原因→解法→验证证据）：站内文档

# 来源: Trove 详细指南 · 验证于 2026-08-28
npm rm -g @musistudio/claude-code-router || true; rm -rf ~/.claude-code-router

note: npm 包自动卸载 + 专属配置目录自动删；settings.json 注入段手动清理

# 来源: Trove 详细指南 · 验证于 2026-08-28
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）

• 运行环境预检（需 Node >= 22）
• 官方 npm CLI 路径（本环境实测）；国内用 npmmirror 前缀
• 首次运行会提示 No available models——需先配置至少一个 provider；桌面端（release 二进制）本环境未实测（无显示环境）
• 每条操作 = 一个命令块 + 预期输出
• 控制面工具：会写 ~/.claude/settings.json（env 注入），卸载时需手动清理注入段（guide.md 卸载段有清单）

• 问：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 模板）；项目自身问题请向作者仓库反馈。

• 版本：[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_*；注入链未全验证）。

• 条目签名：musistudio/claude-code-router（MIT，原样收录 v3.0.22）

• 实测：实测记录（本地留存）（2026-08-28，npm 安装 + ccr --help 冒烟）。
• 未实测：provider 配置与网关启动（首次运行需配置 provider）；桌面端 release 二进制（无显示环境）。

第三方教学未逐条实测，仅供学习；有出入以本页与官方文档为准。

• 使用 claude code router + cc switch，在 claude code 中接入官方大模型以及第三方平台提供的聚合大模型 API ⚠ 与实测冲突，以 Trove 实测为准 [博客园 · 沄卿 · 2026-02-27]
  用 ccr 做本地代理，把聚合大模型 API（文中例：白山智算）接入 claude code；含 node 环境检查、安装、路由配置、与 cc-switch 配合切换
• Windows 中安装 claude-code + claude-code-router 接入英伟达模型（minimax-m2.5/glm4.7） [博客园 · 二月雪 · 2026-03-22]
  Windows 下 winget/npm 安装 ccr、配置 provider 接入英伟达模型；5 章节含安装方式对比与配置步骤