7.1 KiB
Claude Code Router CLI
@musistudio/claude-code-router 是 Claude Code Router 的 Node.js 发行版。它通过 ccr 命令提供浏览器管理界面、本地模型网关和 Agent 配置启动能力，不需要安装 Electron。
CLI 适合开发机和无桌面的服务器。如果你需要系统托盘、桌面通知、应用自动更新或桌面端专属的浏览器集成，请安装桌面应用。
环境要求与安装
- Node.js 22 或更高版本
- 一个可用的上游模型供应商，或 CCR 支持导入的本机 Agent 登录态
- 使用配置启动命令时，本机需要已经安装对应 Agent
全局安装：
npm install -g @musistudio/claude-code-router
ccr --help
升级或卸载：
npm install -g @musistudio/claude-code-router@latest
npm uninstall -g @musistudio/claude-code-router
卸载 npm 包不会删除 CCR 的本地配置和数据库。
快速开始
启动后台服务并打开管理界面：
ccr ui
然后按以下顺序配置：
- 添加上游供应商和至少一个模型。
- 在 API 密钥 页面创建 CCR 客户端密钥。
- 如果默认供应商 / 模型不够用，再配置路由规则。
- 在 服务 页面确认网关已经运行。
- 把客户端指向界面显示的网关地址。网关默认是
http://127.0.0.1:3456，管理界面默认是http://127.0.0.1:3458。
管理 Token 和 CCR 客户端 API Key 是两种不同凭据。管理 Token 保护浏览器 UI 和 RPC 接口，CCR 客户端 Key 用于验证发送到模型网关的请求。
服务命令
| 命令 | 行为 |
|---|---|
ccr start |
在后台启动管理服务和网关，并打印带认证信息的管理 URL。 |
ccr ui |
复用或启动后台服务，然后打开管理界面。 |
ccr stop |
停止由 ccr start 或 ccr ui 启动的后台服务。 |
ccr serve |
在前台运行管理服务和网关；ccr web 是别名。 |
ccr <配置> |
按名称或 ID 打开一个已启用的 Agent 配置。 |
ccr start
ccr start [--host <host>] [--port <port>] [--open|--no-open] [--gateway|--no-gateway]
--host <host>：管理服务监听地址，默认127.0.0.1。--port <port>：管理服务首选端口，默认3458。--open/--no-open：是否打开浏览器。--gateway：明确要求启动模型网关；这是默认行为。--no-gateway：只启动管理服务，不启动模型网关。
ccr ui
ccr ui [--host <host>] [--port <port>] [--open|--no-open] [--gateway|--no-gateway]
ui 默认会打开浏览器。在 SSH 或其他无桌面环境中使用 --no-open。
ccr serve
ccr serve [--host <host>] [--port <port>] [--open|--no-open] [--gateway|--no-gateway]
serve 会留在当前终端并处理 SIGINT / SIGTERM，适合交给进程管理器托管。ccr stop 只管理后台服务；前台服务需要在终端或进程管理器中停止。
如果首选管理端口已被占用，CCR 会继续尝试后续端口并打印实际 URL。start 或 ui 复用已运行服务时，新传入的 Host、Port 和 --no-gateway 不会重配该进程；要修改这些选项，请先运行 ccr stop。
Agent 配置启动
先在 Agent 配置档案 中创建并启用配置，然后按名称或 ID 启动：
ccr "Codex - Work"
ccr "Codex - Work" app
ccr "Claude - Review" cli -- --model sonnet
ccr profile-id -- --help
完整语法：
ccr <配置名称或 ID> [cli|app] [-- <Agent 参数>]
--cli和--app也可以代替位置形式的入口类型。- Agent 自己的参数建议统一放到
--后，避免被识别为 CCR 参数。 - 省略入口类型时，Claude Code、Codex、Grok CLI、Kimi CLI、Pi 默认使用 CLI，ZCode 默认使用 App。
- Grok CLI、Kimi CLI 和 Pi 只支持 CLI，ZCode 只支持 App。Claude App 和 ZCode App 不接受额外 Agent 参数。
- 启动桌面 App 时，本机必须已安装对应应用，并且当前环境必须有图形会话。
- 大多数配置需要先启动 CCR 服务。Grok CLI、Kimi CLI 和 Pi 配置可以自动启动一个临时共享服务，并在最后一个受管会话退出后停止。
桌面应用会安装一个相关命令 ccr-app。桌面 Agent 配置档案卡片复制出来的命令使用 ccr-app；本文介绍的 npm 包安装的是 ccr。
配置与运行文件
| 平台 | 配置目录 |
|---|---|
| macOS / Linux | ~/.claude-code-router |
| Windows | %APPDATA%\claude-code-router |
重要文件包括：
config.sqlite：当前应用配置。app-data/：API Key、用量、请求日志、证书等运行数据库和文件。service.json：后台 CLI 服务的状态和私有 Token。gateway.config.json：生成的网关运行配置。profiles/和bin/：隔离的 Agent 配置和启动包装器。
CCR 写入 SQLite 时不要直接编辑或复制活跃数据库。优先使用 UI 导出；要做文件级备份，请先停止 CCR。
环境变量与安全
| 变量 | 说明 |
|---|---|
CCR_WEB_HOST |
省略 --host 时使用的管理服务监听地址。 |
CCR_WEB_PORT |
省略 --port 时使用的管理服务端口。 |
CCR_WEB_AUTH_TOKEN |
固定管理 UI / RPC 的认证 Token；不设置时每个进程会生成随机 Token。 |
认证后的管理 URL 会在查询参数中包含 ccr_web_token。请把这个 URL 当作密码，不要复制到日志、工单或公开的 Shell 历史中。除非确实需要远程访问，否则监听地址应保持 127.0.0.1。远程访问时，应同时使用防火墙或私网，并在可信反向代理上启用 TLS。
不要在未创建 CCR 客户端 API Key 的情况下暴露网关。上游供应商凭据保存在 CCR 本地数据目录中，因此也要保护该目录及其备份。
常见问题
找不到 ccr 命令
确认 Node.js 不低于 22，并检查 npm 全局可执行目录是否在 PATH：
node --version
npm prefix -g
如果 Shell 缓存了命令路径，安装后请打开一个新终端。
管理 URL 的端口发生变化
首选端口已被占用。请使用 CCR 打印的实际 URL，或停止占用端口的进程后重启 CCR。
UI 能打开，但网关不可用
管理服务可以在没有可用网关时单独运行。请添加供应商和模型、创建客户端 API Key，然后从 服务 页面启动或重启网关。排查启动错误时，可以使用 ccr serve 查看前台输出。
找不到 Agent 配置
只有已启用的配置才能启动。名称匹配不区分大小写，也接受清理后的名称；如果多个名称产生歧义，必须使用配置 ID。生成的启动器缺失时，请重新保存配置。
后台服务仍使用旧参数
停止并重新创建服务：
ccr stop
ccr start --host 127.0.0.1 --port 3458
Docker
仓库还提供面向模型网关和浏览器 UI 的 Docker 镜像。运行时镜像不会安装 npm 的 ccr 命令。请参阅 Docker 部署文档。