Claude Code Router 如何用 ccr 命令按 Agent 配置启动实例并向 Agent 透传参数-二趣网

Claude Code Router 如何用 ccr 命令按 Agent 配置启动实例并向 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-router

如果你使用 npm 安装 Claude Code Router（CCR）而不是桌面应用，就需要用ccr命令完成两件事：按Agent 配置中已保存的配置启动一个独立的 Agent 实例，并把 Agent 自己的命令行参数原样透传给它。ccr <配置名称或 ID> [cli|app] [-- <Agent 参数>]是这条路径的完整形态，本文基于 CLI 安装与命令参考和 Agent 配置说明从准备到验证的全过程。

区分`ccr`与`ccr-app`

CCR 有两个相关命令，名字不能混用：

命令	来源	主要用途
`ccr`	npm 包`@musistudio/claude-code-router`	不依赖 Electron，提供浏览器管理界面和模型网关，并按配置启动 Agent
`ccr-app`	CCR 桌面应用	桌面版生成的配置启动器；Agent 配置卡片复制的命令使用这个名称

两个发行版读取同一套本机配置目录：macOS / Linux 在~/.claude-code-router，Windows 在%APPDATA%\claude-code-router。本文的命令都以 npm CLI 为准，即ccr ...；如果配置卡片复制出的是ccr-app "配置名称"，在 CLI 发行版里对应写成ccr "配置名称"，配置名称和可选的cli/app后缀保持一致。

准备：安装 CLI 并确保网关可用

CLI 要求 Node.js 22 或更高版本：

node --version npm install -g @musistudio/claude-code-router ccr --help

安装成功但找不到命令时，执行npm prefix -g，确认 npm 全局可执行目录已加入PATH，然后打开新终端。

接着在后台启动 CCR 并打开管理界面（SSH 或无桌面环境用ccr ui --no-open）：

ccr ui

管理界面默认使用http://127.0.0.1:3458，模型网关默认使用http://127.0.0.1:3456。在界面里按顺序完成：添加供应商和至少一个模型，在API 密钥页面创建 CCR 客户端 Key，然后在服务页面确认网关已运行。大多数 Agent 配置要求 CCR 网关已经运行（例外见下文）；管理 Token 与 CCR 客户端 Key 是两种独立凭据，前者保护 UI / RPC，后者验证模型请求。

创建并启用 Agent 配置

按接入 Agent 配置的流程操作：

在Agent 配置页面点击添加配置，选择 Agent 类型，填写配置名称（名称可以有空格，复制命令时 CCR 会自动加引号）。
选择作用范围与入口模式。试用阶段建议选仅从 CCR 打开时生效（默认），配置只影响从 CCR 启动的实例，不会改动你系统里直接打开的 Agent。
选择模型，模型值通常是供应商名称/模型名称，也可以选 Fusion 模型。
保存。只有已启用的配置可以被ccr命令启动；启用开关关闭后，配置不会出现在启动入口中。

用 ccr 命令启动实例

启动命令的完整形态：

ccr <配置名称或 ID> [cli|app] [-- <Agent 参数>]

文档给出的示例：

ccr "Codex - Work" ccr "Codex - Work" app ccr "Claude - Review" cli -- --model sonnet ccr profile-id -- --help

逐条规则如下：

cli/app是入口位置参数，--cli和--app可以替代它。
Agent 自己的参数放到--之后，避免与 CCR 选项或入口名冲突。例如ccr "Claude - Review" cli -- --model sonnet中的--model sonnet会被透传给 Claude Code CLI，而不是被 CCR 解析。
省略入口时，Claude Code、Codex、Grok CLI 默认使用 CLI，ZCode 默认使用 App。
Grok CLI、Kimi CLI、Pi 和 Kilo 只支持 CLI；ZCode 和 Claude Design 只支持 App。
Claude App 和 ZCode App 不支持额外 Agent 参数，所以透传参数只对 CLI 入口的 Agent 有意义。
启动 App 需要本机安装对应桌面应用，并且当前环境有图形会话。
名称产生歧义时使用配置 ID。CCR 会按 ID、名称、忽略大小写的名称和清理后的名称匹配；多个结果匹配时必须使用 ID。

关于网关依赖：大多数配置要求 CCR 网关已经运行。Grok CLI、Kimi CLI 和 Pi 是例外——如果服务不存在，它们可以自动启动一个受管的临时共享服务，并在最后一个会话退出后关闭。

验证启动结果

按 Claude Code 接入与配置的验证方法，链路是否打通可以这样核对：

运行ccr "配置名称"后，在 Agent 中发送一条消息，确认能正常回复。
打开 CCR 的请求日志，确认请求经过了 CCR 网关，并核对最终命中的供应商 / 模型。查看前先到设置 → 日志与观测打开请求日志开关，详见开启日志与观测。注意普通请求日志只保留本地当天的数据，进入第二天后下一次读取或写入时会清理前一天的记录。
对 Claude Code CLI，进入后输入/model，确认 CCR 暴露的模型列表出现，并确认透传的 Agent 参数（如--model）已生效。

常见问题排查

以下均出自 CLI 文档的常见问题一节：

找不到 Agent 配置：确认配置已启用，并检查名称是否重复；多个结果匹配时必须使用配置 ID。
提示启动器不存在：先打开一次 CCR 或重新保存该 Agent 配置，让 CCR 重新生成bin/下的启动包装器。
UI 能打开，但模型请求失败：管理服务可以在没有可用模型网关时运行。添加供应商和模型、创建 CCR 客户端 Key，然后从服务页面启动或重启网关；用ccr serve查看启动错误，因为前台运行的错误会直接输出到当前终端。
Agent 没有走 CCR：按常见问题的顺序检查——确认 CCR 服务正在运行、Agent 是从 CCR 启动的而不是直接打开的、Agent 配置已应用且作用范围覆盖当前场景。

企业官网建设流程全解析