用 ccr 命令掌控 Claude Code RouterNode.js CLI 的安装、后台服务与 Agent 配置启动全指南【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-routermusistudio/claude-code-router是 Claude Code Router 项目的 Node.js 发行版将「浏览器管理界面 本地模型网关 Agent 配置启动」全部收敛进一个ccr命令无需 Electron 即可在开发机与无桌面服务器上运行。读完本文你将掌握如何全局安装与升级 CLI、用ccr start / ui / serve / stop管理后台服务、按名称或 ID 启动预置的 Agent 配置并正确理解 CCR 的配置文件布局、凭据体系与安全边界。本文以 packages/cli/README_zh.md 为骨架并结合仓库中 CLI 主程序、配置常量定义 与 路径解析实现 等源码补充底层细节。该包的英文说明可参见 packages/cli/README.md。CLI 与桌面应用的分工在动手安装前先明确两条产品线的差异避免装错包ccrCLI本文主角通过 npm 安装的 Node.js 发行版由ccr二进制提供管理服务、模型网关和 Agent 启动能力。它适合开发机与无桌面的服务器但没有系统托盘、桌面通知、应用自动更新和桌面端专属的浏览器集成。桌面应用如果你需要托盘图标、桌面通知、自动更新等体验应安装桌面应用。桌面应用会额外提供一个相关命令ccr-app从桌面 Agent 配置档案卡片复制出来的命令使用的是ccr-app而 npm 包安装的是ccr。从源码结构看两者的入口环境相互隔离CLI 会清理ELECTRON_RUN_AS_NODE变量见 cli.ts。从 packages/cli/package.json 可以看到该包通过bin: { ccr: dist/main/cli.js }暴露ccr命令并声明engines: { node: 22 }。环境要求与安装环境前提Node.js 22 或更高版本这是包在engines字段中声明的硬性要求版本过低将无法运行。一个可用的上游模型供应商或CCR 支持导入的本机 Agent 登录态如 Claude Code、Codex 等作为本地 Agent 供应商导入。使用「配置启动」类命令时本机需要已经安装对应的 Agent下文会展开说明。全局安装npm install -g musistudio/claude-code-router ccr --help安装后立刻运行ccr --help校验命令可用其帮助文本会列出start / ui / serve / stop与profile-name-or-id的用法集成测试也验证了这一行为见 cli-help.test.mjs。升级与卸载npm install -g musistudio/claude-code-routerlatest npm uninstall -g musistudio/claude-code-router需要特别提醒卸载 npm 包不会删除 CCR 的本地配置和数据库。这些数据存放在独立的配置目录见下文「配置与运行文件」因此重装或切换版本不会丢失供应商密钥、用量记录等数据。快速开始一句话启动全部能力ccr ui该命令会按需启动后台服务并打开浏览器管理界面。随后按顺序完成如下配置添加供应商在上游供应商配置中至少添加一个供应商与一个模型。创建客户端密钥在API 密钥页面创建 CCR 客户端 API Key。配置路由若默认供应商 / 模型不够用再配置路由规则可在管理界面中设置模型与路由策略。确认网关运行在服务页面确认模型网关已经运行。指向网关地址把 Claude Code 等客户端指向界面显示的网关地址。两个默认地址要牢记模型网关默认是http://127.0.0.1:3456管理界面默认是http://127.0.0.1:3458。从源码可以交叉验证这两个端口网关端口3456出现在 default-config.ts 的gateway.port中管理界面首选端口3458则由 management-server.ts 中的defaultWebPort常量定义。理解两类凭据这是新手最容易混淆的地方务必分清管理 Token用于保护浏览器 UI 和 RPC 接口例如服务状态查询、启动网关等内部调用。CCR 客户端 API Key用于验证发送到模型网关的请求客户端需要把它作为密钥访问3456端口的网关。从 CLI 源码可以看到管理服务认证通过 HTTP 头x-ccr-web-auth传递认证后的管理 URL 会把令牌放在查询参数ccr_web_token中见 cli.ts 与 management-server.ts 中对应的常量定义。服务命令一览CLI 围绕「服务」提供以下命令命令行为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只启动管理服务不启动模型网关适合仅做配置、暂不转发请求的场景。start的实现值得留意它会以detached: true方式派生一个serve --daemon-child子进程见 cli.ts随后把服务状态写入service.json。因此start返回后管理服务依然存活于后台。ccr ui后台服务 打开界面ccr ui [--host host] [--port port] [--open|--no-open] [--gateway|--no-gateway]ui默认会打开浏览器。在 SSH 或无桌面环境中使用--no-open此时命令只打印管理 URL便于你手动访问或转发。从实现看ui本质上就是调用startService并默认设置open true见 cli.ts所以它会复用已运行的实例。ccr serve前台运行交给进程管理器ccr serve [--host host] [--port port] [--open|--no-open] [--gateway|--no-gateway]serveweb是其别名会留在当前终端并监听SIGINT/SIGTERM信号优雅退出非常适合交给 pm2、systemd 等进程管理器托管。请注意边界ccr stop只管理由start/ui启动的后台服务对serve这类前台服务需要回到原终端或在进程管理器中停止它。实现上serve模式下进程会注册SIGINT/SIGTERM处理器并调用运行时关闭逻辑见 cli.ts。端口占用与参数生效规则如果首选管理端口3458已被占用CCR 会继续尝试后续端口并打印实际 URL因此你看到的管理地址可能不是默认端口——不要困惑使用打印出来的 URL 即可。另一个容易踩坑的点start或ui复用已运行服务时新传入的 Host、Port 和--no-gateway不会重配该进程。也就是说后台服务一经启动监听参数即已固定。要修改这些选项请先执行ccr stop停掉旧服务再重新ccr start。Agent 配置启动CCR 支持把某个 Agent 场景固化为一个「配置档案」Profile然后一条命令拉起。前提是在管理界面的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是入口类型Surface的位置写法之外的等价替代源码在 cli.ts 中同时识别--cli/--app与位置参数cli/app。Agent 自己的参数建议统一放到--后例如上面的-- --model sonnet。解析器遇到--后会把它之后的所有参数原样透传给子进程避免被误判为 CCR 参数见 cli.ts。省略入口类型时Claude Code、Codex、Grok CLI、Kimi CLI、Pi 默认使用 CLIZCode 默认使用 App每个 Agent 的默认入口在 launch-core.ts 的defaultProfileOpenSurface相关逻辑中定义。能力边界需要记牢Grok CLI、Kimi CLI 和 Pi 只支持 CLI 入口ZCode 只支持 App 入口Claude App 与 ZCode App 不接受额外 Agent 参数后者超参会直接报错见 cli.ts。启动桌面 App如 Codex App、Claude App、ZCode App时本机必须已安装对应应用且当前环境必须有图形会话——无显示器的服务器上无法拉起桌面 App。大多数配置需要先启动 CCR 服务依赖它提供网关与密钥但Grok CLI、Kimi CLI 和 Pi 配置可以自动启动一个临时的共享服务并在最后一个受管会话退出后自动停止。这一「按需拉起、空闲回收」的机制由 profile gateway lease 实现CLI 会为每个受管会话写入租约文件后台服务轮询发现没有活跃租约时自动退出见 cli.ts 与profile-gateway-leases相关逻辑。解析与匹配规则从解析器与匹配逻辑看配置引用遵循以下规则名称匹配不区分大小写也接受清理后的名称去掉特殊字符等如果多个配置名称产生歧义则必须使用配置 ID。只有已启用的配置才能被启动。CLI 会把配置编译为隔离的启动包装器存放在profiles/与bin/目录若启动器缺失会提示重新保存配置见 cli.ts 的「Profile launcher was not found」分支。配置与运行文件配置目录位置平台配置目录macOS / Linux~/.claude-code-routerWindows%APPDATA%\claude-code-router路径解析逻辑集中在 app-paths.ts非 Windows 平台取home/.claude-code-routerWindows 取appData即APPDATA下的claude-code-router。目录内的关键文件config.sqlite当前应用配置供应商、模型、路由规则、Agent 档案等路径在 constants.ts 中定义为CONFIGDIR/config.sqlite。app-data/API Key、用量、请求日志、证书等运行数据库与文件对应源码中的DATADIR存放用量、请求日志、CA 证书等数据见 constants.ts。需要注意在 Windows 上DATADIR与配置目录同目录在 macOS/Linux 上是配置目录下的app-data子目录。service.json后台 CLI 服务的状态与私有 Token权限设为0600用于start/ui/stop校验与 RPC 调用见 cli.ts。gateway.config.json生成的网关运行配置编译后的产物配合网关启动使用。profiles/和bin/隔离的 Agent 配置与启动包装器实现「按档案独立环境」拉起 Agent。备份的注意事项CCR 在运行时会持续写入 SQLite配置、用量、日志都落在这些数据库里。因此不要直接编辑或复制活跃的数据库文件否则可能损坏数据或产生不一致。需要导出数据时优先使用 UI 的导出功能。要做文件级备份请先停止 CCRccr stop再复制整个配置目录。环境变量与安全可配置的环境变量变量说明CCR_WEB_HOST省略--host时使用的管理服务监听地址。CCR_WEB_PORT省略--port时使用的管理服务端口。CCR_WEB_AUTH_TOKEN固定管理 UI / RPC 的认证 Token不设置时每个进程会生成随机 Token。这三个变量与--host/--port的优先级在帮助文本中写得很清楚命令行参数优先未传时回退到环境变量再回退到默认值127.0.0.1/3458见 cli.ts 的printStartHelp。安全注意事项把管理 URL 当作密码认证后的 URL 会在查询参数中包含ccr_web_token任何人拿到它都能控制你的管理界面与 RPC。不要把这个 URL 复制进日志、工单或公开的 Shell 历史。监听地址保持127.0.0.1除非确实需要远程访问否则不要改成0.0.0.0。远程访问时应同时使用防火墙或私网隔离并在可信反向代理上启用 TLS。不要在没有创建 CCR 客户端 API Key 的情况下暴露网关网关端口3456如果对公网开放却没有密钥校验等于把转发能力裸露出去。保护本地数据目录上游供应商凭据保存在 CCR 本地数据目录中app-data/内因此该目录及其备份都要妥善保护。常见问题排查找不到ccr命令确认 Node.js 不低于 22并检查 npm 全局可执行目录是否在PATHnode --version npm prefix -g如果 Shell 缓存了命令路径安装完成后请打开一个新终端再执行。管理 URL 的端口发生变化首选端口3458已被占用。CCR 会自动尝试后续端口并打印实际 URL——使用 CCR 打印的那个 URL或者停止占用端口的进程后重启 CCR。UI 能打开但网关不可用管理服务可以在没有可用网关时单独运行例如使用--no-gateway启动。此时请添加供应商和模型创建 CCR 客户端 API Key从服务页面启动或重启网关。排查启动错误时推荐改用ccr serve前台运行直接观察终端输出。找不到 Agent 配置只有已启用的配置才能启动。名称匹配不区分大小写也接受清理后的名称若多个名称产生歧义必须改用配置 ID。若提示生成的启动器缺失请回到管理界面重新保存该配置让profiles/与bin/下的包装器重新生成。后台服务仍使用旧参数说明正在运行的后台服务仍带着旧的 Host / Port 参数复用机制不会重配进程。停止并重新创建服务ccr stop ccr start --host 127.0.0.1 --port 3458Docker 部署说明仓库还提供面向模型网关与浏览器 UI的 Docker 镜像。需要注意的是运行时镜像不会安装 npm 的ccr命令也就是说容器里没有上文所述的 CLI 命令形态。详细的镜像使用、端口映射与 compose 配置请参阅仓库内的 Docker 部署文档 及根目录的 docker-compose.yml。延伸阅读CLI 完整命令行实现packages/cli/src/cli.tsCLI 命令解析与帮助集成测试packages/cli/test/integration/cli-help.test.mjs配置目录与运行数据路径常量packages/core/src/config/constants.ts跨平台配置/数据目录解析packages/core/src/runtime/app-paths.ts管理服务与默认端口3458packages/core/src/web/management-server.ts网关默认端口3456与默认配置packages/core/src/config/default-config.ts【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-router创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
用 ccr 命令掌控 Claude Code Router：Node.js CLI 的安装、后台服务与 Agent 配置启动全指南
用 ccr 命令掌控 Claude Code RouterNode.js CLI 的安装、后台服务与 Agent 配置启动全指南【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-routermusistudio/claude-code-router是 Claude Code Router 项目的 Node.js 发行版将「浏览器管理界面 本地模型网关 Agent 配置启动」全部收敛进一个ccr命令无需 Electron 即可在开发机与无桌面服务器上运行。读完本文你将掌握如何全局安装与升级 CLI、用ccr start / ui / serve / stop管理后台服务、按名称或 ID 启动预置的 Agent 配置并正确理解 CCR 的配置文件布局、凭据体系与安全边界。本文以 packages/cli/README_zh.md 为骨架并结合仓库中 CLI 主程序、配置常量定义 与 路径解析实现 等源码补充底层细节。该包的英文说明可参见 packages/cli/README.md。CLI 与桌面应用的分工在动手安装前先明确两条产品线的差异避免装错包ccrCLI本文主角通过 npm 安装的 Node.js 发行版由ccr二进制提供管理服务、模型网关和 Agent 启动能力。它适合开发机与无桌面的服务器但没有系统托盘、桌面通知、应用自动更新和桌面端专属的浏览器集成。桌面应用如果你需要托盘图标、桌面通知、自动更新等体验应安装桌面应用。桌面应用会额外提供一个相关命令ccr-app从桌面 Agent 配置档案卡片复制出来的命令使用的是ccr-app而 npm 包安装的是ccr。从源码结构看两者的入口环境相互隔离CLI 会清理ELECTRON_RUN_AS_NODE变量见 cli.ts。从 packages/cli/package.json 可以看到该包通过bin: { ccr: dist/main/cli.js }暴露ccr命令并声明engines: { node: 22 }。环境要求与安装环境前提Node.js 22 或更高版本这是包在engines字段中声明的硬性要求版本过低将无法运行。一个可用的上游模型供应商或CCR 支持导入的本机 Agent 登录态如 Claude Code、Codex 等作为本地 Agent 供应商导入。使用「配置启动」类命令时本机需要已经安装对应的 Agent下文会展开说明。全局安装npm install -g musistudio/claude-code-router ccr --help安装后立刻运行ccr --help校验命令可用其帮助文本会列出start / ui / serve / stop与profile-name-or-id的用法集成测试也验证了这一行为见 cli-help.test.mjs。升级与卸载npm install -g musistudio/claude-code-routerlatest npm uninstall -g musistudio/claude-code-router需要特别提醒卸载 npm 包不会删除 CCR 的本地配置和数据库。这些数据存放在独立的配置目录见下文「配置与运行文件」因此重装或切换版本不会丢失供应商密钥、用量记录等数据。快速开始一句话启动全部能力ccr ui该命令会按需启动后台服务并打开浏览器管理界面。随后按顺序完成如下配置添加供应商在上游供应商配置中至少添加一个供应商与一个模型。创建客户端密钥在API 密钥页面创建 CCR 客户端 API Key。配置路由若默认供应商 / 模型不够用再配置路由规则可在管理界面中设置模型与路由策略。确认网关运行在服务页面确认模型网关已经运行。指向网关地址把 Claude Code 等客户端指向界面显示的网关地址。两个默认地址要牢记模型网关默认是http://127.0.0.1:3456管理界面默认是http://127.0.0.1:3458。从源码可以交叉验证这两个端口网关端口3456出现在 default-config.ts 的gateway.port中管理界面首选端口3458则由 management-server.ts 中的defaultWebPort常量定义。理解两类凭据这是新手最容易混淆的地方务必分清管理 Token用于保护浏览器 UI 和 RPC 接口例如服务状态查询、启动网关等内部调用。CCR 客户端 API Key用于验证发送到模型网关的请求客户端需要把它作为密钥访问3456端口的网关。从 CLI 源码可以看到管理服务认证通过 HTTP 头x-ccr-web-auth传递认证后的管理 URL 会把令牌放在查询参数ccr_web_token中见 cli.ts 与 management-server.ts 中对应的常量定义。服务命令一览CLI 围绕「服务」提供以下命令命令行为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只启动管理服务不启动模型网关适合仅做配置、暂不转发请求的场景。start的实现值得留意它会以detached: true方式派生一个serve --daemon-child子进程见 cli.ts随后把服务状态写入service.json。因此start返回后管理服务依然存活于后台。ccr ui后台服务 打开界面ccr ui [--host host] [--port port] [--open|--no-open] [--gateway|--no-gateway]ui默认会打开浏览器。在 SSH 或无桌面环境中使用--no-open此时命令只打印管理 URL便于你手动访问或转发。从实现看ui本质上就是调用startService并默认设置open true见 cli.ts所以它会复用已运行的实例。ccr serve前台运行交给进程管理器ccr serve [--host host] [--port port] [--open|--no-open] [--gateway|--no-gateway]serveweb是其别名会留在当前终端并监听SIGINT/SIGTERM信号优雅退出非常适合交给 pm2、systemd 等进程管理器托管。请注意边界ccr stop只管理由start/ui启动的后台服务对serve这类前台服务需要回到原终端或在进程管理器中停止它。实现上serve模式下进程会注册SIGINT/SIGTERM处理器并调用运行时关闭逻辑见 cli.ts。端口占用与参数生效规则如果首选管理端口3458已被占用CCR 会继续尝试后续端口并打印实际 URL因此你看到的管理地址可能不是默认端口——不要困惑使用打印出来的 URL 即可。另一个容易踩坑的点start或ui复用已运行服务时新传入的 Host、Port 和--no-gateway不会重配该进程。也就是说后台服务一经启动监听参数即已固定。要修改这些选项请先执行ccr stop停掉旧服务再重新ccr start。Agent 配置启动CCR 支持把某个 Agent 场景固化为一个「配置档案」Profile然后一条命令拉起。前提是在管理界面的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是入口类型Surface的位置写法之外的等价替代源码在 cli.ts 中同时识别--cli/--app与位置参数cli/app。Agent 自己的参数建议统一放到--后例如上面的-- --model sonnet。解析器遇到--后会把它之后的所有参数原样透传给子进程避免被误判为 CCR 参数见 cli.ts。省略入口类型时Claude Code、Codex、Grok CLI、Kimi CLI、Pi 默认使用 CLIZCode 默认使用 App每个 Agent 的默认入口在 launch-core.ts 的defaultProfileOpenSurface相关逻辑中定义。能力边界需要记牢Grok CLI、Kimi CLI 和 Pi 只支持 CLI 入口ZCode 只支持 App 入口Claude App 与 ZCode App 不接受额外 Agent 参数后者超参会直接报错见 cli.ts。启动桌面 App如 Codex App、Claude App、ZCode App时本机必须已安装对应应用且当前环境必须有图形会话——无显示器的服务器上无法拉起桌面 App。大多数配置需要先启动 CCR 服务依赖它提供网关与密钥但Grok CLI、Kimi CLI 和 Pi 配置可以自动启动一个临时的共享服务并在最后一个受管会话退出后自动停止。这一「按需拉起、空闲回收」的机制由 profile gateway lease 实现CLI 会为每个受管会话写入租约文件后台服务轮询发现没有活跃租约时自动退出见 cli.ts 与profile-gateway-leases相关逻辑。解析与匹配规则从解析器与匹配逻辑看配置引用遵循以下规则名称匹配不区分大小写也接受清理后的名称去掉特殊字符等如果多个配置名称产生歧义则必须使用配置 ID。只有已启用的配置才能被启动。CLI 会把配置编译为隔离的启动包装器存放在profiles/与bin/目录若启动器缺失会提示重新保存配置见 cli.ts 的「Profile launcher was not found」分支。配置与运行文件配置目录位置平台配置目录macOS / Linux~/.claude-code-routerWindows%APPDATA%\claude-code-router路径解析逻辑集中在 app-paths.ts非 Windows 平台取home/.claude-code-routerWindows 取appData即APPDATA下的claude-code-router。目录内的关键文件config.sqlite当前应用配置供应商、模型、路由规则、Agent 档案等路径在 constants.ts 中定义为CONFIGDIR/config.sqlite。app-data/API Key、用量、请求日志、证书等运行数据库与文件对应源码中的DATADIR存放用量、请求日志、CA 证书等数据见 constants.ts。需要注意在 Windows 上DATADIR与配置目录同目录在 macOS/Linux 上是配置目录下的app-data子目录。service.json后台 CLI 服务的状态与私有 Token权限设为0600用于start/ui/stop校验与 RPC 调用见 cli.ts。gateway.config.json生成的网关运行配置编译后的产物配合网关启动使用。profiles/和bin/隔离的 Agent 配置与启动包装器实现「按档案独立环境」拉起 Agent。备份的注意事项CCR 在运行时会持续写入 SQLite配置、用量、日志都落在这些数据库里。因此不要直接编辑或复制活跃的数据库文件否则可能损坏数据或产生不一致。需要导出数据时优先使用 UI 的导出功能。要做文件级备份请先停止 CCRccr stop再复制整个配置目录。环境变量与安全可配置的环境变量变量说明CCR_WEB_HOST省略--host时使用的管理服务监听地址。CCR_WEB_PORT省略--port时使用的管理服务端口。CCR_WEB_AUTH_TOKEN固定管理 UI / RPC 的认证 Token不设置时每个进程会生成随机 Token。这三个变量与--host/--port的优先级在帮助文本中写得很清楚命令行参数优先未传时回退到环境变量再回退到默认值127.0.0.1/3458见 cli.ts 的printStartHelp。安全注意事项把管理 URL 当作密码认证后的 URL 会在查询参数中包含ccr_web_token任何人拿到它都能控制你的管理界面与 RPC。不要把这个 URL 复制进日志、工单或公开的 Shell 历史。监听地址保持127.0.0.1除非确实需要远程访问否则不要改成0.0.0.0。远程访问时应同时使用防火墙或私网隔离并在可信反向代理上启用 TLS。不要在没有创建 CCR 客户端 API Key 的情况下暴露网关网关端口3456如果对公网开放却没有密钥校验等于把转发能力裸露出去。保护本地数据目录上游供应商凭据保存在 CCR 本地数据目录中app-data/内因此该目录及其备份都要妥善保护。常见问题排查找不到ccr命令确认 Node.js 不低于 22并检查 npm 全局可执行目录是否在PATHnode --version npm prefix -g如果 Shell 缓存了命令路径安装完成后请打开一个新终端再执行。管理 URL 的端口发生变化首选端口3458已被占用。CCR 会自动尝试后续端口并打印实际 URL——使用 CCR 打印的那个 URL或者停止占用端口的进程后重启 CCR。UI 能打开但网关不可用管理服务可以在没有可用网关时单独运行例如使用--no-gateway启动。此时请添加供应商和模型创建 CCR 客户端 API Key从服务页面启动或重启网关。排查启动错误时推荐改用ccr serve前台运行直接观察终端输出。找不到 Agent 配置只有已启用的配置才能启动。名称匹配不区分大小写也接受清理后的名称若多个名称产生歧义必须改用配置 ID。若提示生成的启动器缺失请回到管理界面重新保存该配置让profiles/与bin/下的包装器重新生成。后台服务仍使用旧参数说明正在运行的后台服务仍带着旧的 Host / Port 参数复用机制不会重配进程。停止并重新创建服务ccr stop ccr start --host 127.0.0.1 --port 3458Docker 部署说明仓库还提供面向模型网关与浏览器 UI的 Docker 镜像。需要注意的是运行时镜像不会安装 npm 的ccr命令也就是说容器里没有上文所述的 CLI 命令形态。详细的镜像使用、端口映射与 compose 配置请参阅仓库内的 Docker 部署文档 及根目录的 docker-compose.yml。延伸阅读CLI 完整命令行实现packages/cli/src/cli.tsCLI 命令解析与帮助集成测试packages/cli/test/integration/cli-help.test.mjs配置目录与运行数据路径常量packages/core/src/config/constants.ts跨平台配置/数据目录解析packages/core/src/runtime/app-paths.ts管理服务与默认端口3458packages/core/src/web/management-server.ts网关默认端口3456与默认配置packages/core/src/config/default-config.ts【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-router创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
