mirror of
https://github.com/musistudio/claude-code-router.git
synced 2026-08-18 21:13:23 +00:00
184 lines
7.1 KiB
Markdown
184 lines
7.1 KiB
Markdown
# Claude Code Router CLI
|
||
|
||
[English](README.md) · [完整文档](https://ccrdesk.top/) · [GitHub](https://github.com/musistudio/claude-code-router)
|
||
|
||
`@musistudio/claude-code-router` 是 Claude Code Router 的 Node.js 发行版。它通过 `ccr` 命令提供浏览器管理界面、本地模型网关和 Agent 配置启动能力，不需要安装 Electron。
|
||
|
||
CLI 适合开发机和无桌面的服务器。如果你需要系统托盘、桌面通知、应用自动更新或桌面端专属的浏览器集成，请安装桌面应用。
|
||
|
||
## 环境要求与安装
|
||
|
||
- Node.js 22 或更高版本
|
||
- 一个可用的上游模型供应商，或 CCR 支持导入的本机 Agent 登录态
|
||
- 使用配置启动命令时，本机需要已经安装对应 Agent
|
||
|
||
全局安装：
|
||
|
||
```sh
|
||
npm install -g @musistudio/claude-code-router
|
||
ccr --help
|
||
```
|
||
|
||
升级或卸载：
|
||
|
||
```sh
|
||
npm install -g @musistudio/claude-code-router@latest
|
||
npm uninstall -g @musistudio/claude-code-router
|
||
```
|
||
|
||
卸载 npm 包不会删除 CCR 的本地配置和数据库。
|
||
|
||
## 快速开始
|
||
|
||
启动后台服务并打开管理界面：
|
||
|
||
```sh
|
||
ccr ui
|
||
```
|
||
|
||
然后按以下顺序配置：
|
||
|
||
1. 添加上游供应商和至少一个模型。
|
||
2. 在 **API 密钥** 页面创建 CCR 客户端密钥。
|
||
3. 如果默认供应商 / 模型不够用，再配置路由规则。
|
||
4. 在 **服务** 页面确认网关已经运行。
|
||
5. 把客户端指向界面显示的网关地址。网关默认是 `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`
|
||
|
||
```text
|
||
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`
|
||
|
||
```text
|
||
ccr ui [--host <host>] [--port <port>] [--open|--no-open] [--gateway|--no-gateway]
|
||
```
|
||
|
||
`ui` 默认会打开浏览器。在 SSH 或其他无桌面环境中使用 `--no-open`。
|
||
|
||
### `ccr serve`
|
||
|
||
```text
|
||
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 启动：
|
||
|
||
```sh
|
||
ccr "Codex - Work"
|
||
ccr "Codex - Work" app
|
||
ccr "Claude - Review" cli -- --model sonnet
|
||
ccr profile-id -- --help
|
||
```
|
||
|
||
完整语法：
|
||
|
||
```text
|
||
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`：
|
||
|
||
```sh
|
||
node --version
|
||
npm prefix -g
|
||
```
|
||
|
||
如果 Shell 缓存了命令路径，安装后请打开一个新终端。
|
||
|
||
### 管理 URL 的端口发生变化
|
||
|
||
首选端口已被占用。请使用 CCR 打印的实际 URL，或停止占用端口的进程后重启 CCR。
|
||
|
||
### UI 能打开，但网关不可用
|
||
|
||
管理服务可以在没有可用网关时单独运行。请添加供应商和模型、创建客户端 API Key，然后从 **服务** 页面启动或重启网关。排查启动错误时，可以使用 `ccr serve` 查看前台输出。
|
||
|
||
### 找不到 Agent 配置
|
||
|
||
只有已启用的配置才能启动。名称匹配不区分大小写，也接受清理后的名称；如果多个名称产生歧义，必须使用配置 ID。生成的启动器缺失时，请重新保存配置。
|
||
|
||
### 后台服务仍使用旧参数
|
||
|
||
停止并重新创建服务：
|
||
|
||
```sh
|
||
ccr stop
|
||
ccr start --host 127.0.0.1 --port 3458
|
||
```
|
||
|
||
## Docker
|
||
|
||
仓库还提供面向模型网关和浏览器 UI 的 Docker 镜像。运行时镜像不会安装 npm 的 `ccr` 命令。请参阅 [Docker 部署文档](https://github.com/musistudio/claude-code-router/blob/main/docker/README.md)。
|
||
|
||
## 许可证
|
||
|
||
[MIT](LICENSE)
|