跳转到内容
Chorus Chorus

chorus 命令行工具

chorus 命令（发布为 @chorus-aidlc/chorus）承担三项工作：运行 Chorus 服务器、配置本机上的 编码智能体，以及从 shell 调用 Chorus MCP 端点。全局安装它：

Terminal window
npm install --global @chorus-aidlc/chorus
chorus --version

运行 chorus --help 或 chorus <command> --help 查看完整的参数列表。

命令一览

Section titled “命令一览”
命令作用
chorus启动 Chorus 服务器（不带子命令时的默认行为）。参见使用 Docker 部署。
chorus upgrade / chorus update升级 npm 全局安装的 CLI；加 --plugins 刷新已配置的 Chorus 插件。
chorus agents配置本机的智能体：list（默认）、add、remove，以及 run（启动一个）。
chorus mcp原生 MCP 客户端：call 调用工具、打印你的 UUID（whoami），或 list 列出可调用的工具。
chorus login以智能体身份认证，并把连接保存到 ~/.chorus/daemon.json。
chorus daemon让运行环境保持在线，以便 Chorus 唤醒它。参见管理后台服务。

升级 CLI 与插件

Section titled “升级 CLI 与插件”

从 Chorus 0.20.0 起，可以运行：

Terminal window
chorus upgrade             # 仅升级 CLI
chorus upgrade --plugins   # 先升级 CLI，再刷新已配置的 Chorus 插件
chorus update --plugins    # upgrade 的别名

该命令仅支持 @chorus-aidlc/chorus 的 npm 全局安装。它查询 npm 最新稳定版，在同一个 npm prefix 下更新当前安装，并核验安装后的版本。若已安装的版本已是最新或更高，则既不重装也不降级，但仍会执行 --plugins。源码检出、链接安装和其他包管理器的安装方式不受支持。旧 CLI 尚无此命令时，先用 npm install --global @chorus-aidlc/chorus@latest 安装新版。

--plugins 的刷新范围

Section titled “--plugins 的刷新范围”

它读取 ~/.chorus/daemon.json，处理明确标注为 Claude Code、Codex、Kiro 或 Pi 的记录，包括未启用后台服务唤醒的记录。每条记录的 env、PATH 和自定义配置目录决定更新目标；共享目录只更新一次，不同目录分别处理。该命令目前只读取默认文件，不使用 CHORUS_DAEMON_CONFIG_PATH。

  • Claude Code 与 Codex：通过宿主的插件机制刷新 Chorus 插件。
  • Kiro：从记录所配置的 Chorus 实例刷新模板。需先升级该服务端，才能获取新版模板。同一目标目录对应多个冲突的实例地址时，会报告未完成。
  • Pi：稳定版 >=0.99.0 <2.0.0 使用原生 MCP，仅更新符合条件的 @chorus-aidlc/chorus-pi 安装；0.84.4–0.98.x 保留已验证的 pi-mcp-adapter@5.0.0 固定版本。其他适配器约束及 Chorus 固定版本、范围或标签会保留，可能导致配置或最新版本刷新未完成。不更新所有扩展或 Pi 本身，也不自动卸载旧适配器。详见 Pi 配置与迁移。

若宿主 CLI 已安装但缺少 Chorus 插件，命令会补装插件。它保留注册信息与凭据，不会安装或升级宿主 CLI。修改配置文件前，它会把原文件备份为 <file>.chorus-upgrade.bak（下次升级时覆盖）。offline 或未知类型记录（包括默认的 OpenCode、OpenClaw 和 dsh 记录），以及在各自 PATH 中找不到宿主的记录，会跳过并标为 INCOMPLETE。这些宿主请使用对应平台的配置或升级流程。

完成状态与生效方式

Section titled “完成状态与生效方式”

命令无需交互确认。退出码 0 表示请求的工作全部完成，1 表示失败或某个目标未完成。没有后台服务配置文件或智能体列表为空时，视为成功，无需刷新任何内容；文件不可读或格式错误则视为失败。CLI 升级失败时不执行插件更新；单个插件失败不会中止后续目标，已完成的更新会保留（不会自动回滚）。

npm 安装会持续输出进度，没有安装超时限制。失败时按输出的 npm 错误排查；遇到 EACCES 或 EPERM，可改用当前用户拥有的 Node 安装，或请管理员更新系统 npm prefix。Chorus 不会自动提权。更新后，请启动新的智能体会话，并在方便时运行 chorus daemon restart；活跃会话和后台服务都不会被自动重启。

配置智能体：chorus agents

Section titled “配置智能体：chorus agents”

只需 chorus agents add 这一条命令，即可把本机编码智能体连接到 Chorus。它会检测你已安装的智能体， 通过各智能体自己的插件机制为其安装 Chorus 插件，并把 Chorus 网址和智能体密钥一次性写入 ~/.chorus/daemon.json。对 Claude Code、Codex、Hermes 和 DeepSeek Harness，它还会把凭据写入该智能体 自己的配置，因此交互式会话无需手动设置环境变量即可完成认证（见凭据写往何处）。

Terminal window
chorus agents add                     # interactive: detect, pick, configure
chorus agents add --all --yes         # configure every detected agent, no prompts
chorus agents add --agents claude,codex \
  --url https://chorus.example.com --api-key cho_xxx

可重新运行配置以添加智能体或刷新凭据。支持 Claude Code、Codex、Kiro、Pi、OpenCode、OpenClaw、Hermes 和 DeepSeek Harness（dsh）。Pi 稳定版 >=0.99.0 <2.0.0 使用原生 MCP，0.84.4–0.98.x 使用 pi-mcp-adapter@5.0.0，并安装 chorus-pi。Pi 未安装、不受支持或版本不确定时会给出指引，不会一律报告 MCP 配置完成。详见 Pi。

常用参数（chorus agents add --help 会列出全部）：

  • --agents <a,b> / --all：要配置哪些智能体。
  • --url / --api-key：以非交互方式提供凭据（环境变量：CHORUS_URL / CHORUS_API_KEY）。
  • --update-installed：刷新已有的安装。对 Pi，这会运行 pi update --extensions；仅重复 pi install 不会升级已安装的包。
  • --dsh-profile <name>：把 bundle 安装进哪个 DeepSeek Harness profile。
  • --daemon-wake <a,b> / --daemon-wake-all：把指定的（或全部可唤醒的）智能体选入后台服务唤醒范围。可唤醒的智能体（Claude Code、Codex、Kiro、Pi）默认以「停靠」状态添加：chorus mcp 可以访问它们，但在你通过此参数（或 TTY 下逐个智能体的提示）选入之前，后台服务不会唤醒它们。
  • --daemon-autostart：同时安装并启用后台服务的开机自启（Linux systemd / macOS launchd）。
  • --no-linger：跳过 Linux systemd 用户驻留的配置或修复，不关闭已有设置。详见后台服务运维。
  • -y, --yes：跳过确认（非 TTY 环境下自动生效，此时必须传入 --agents 或 --all）。

列出并移除已配置的智能体：

Terminal window
chorus agents                     # list configured agents (name, UUID, backend)
chorus agents remove <name|uuid>  # remove one (match by name or UUID)

chorus agents 绝不会打印 API 密钥。列出的名称或 UUID 都是 chorus mcp --agent 或 CHORUS_AGENT_PROFILE 环境变量的有效取值。

对 Codex，--yes 不会授权重启 App Server。凭据和 MCP 配置成功后，仅交互终端会提供单独的中断警告和确认。详见 Codex。

配置 Hermes（0.22.0）

Section titled “配置 Hermes（0.22.0）”

chorus agents add --agents hermes --hermes-cwd /path/to/repo 从 CLI 对应发布标签安装 chorus 和 chorus-mcp，写入 $HERMES_HOME/.env，配置仓库及未设置的审批默认值。--hermes-cwd <path> 覆盖目录；否则保留现有目录或使用当前 Git 仓库。标签缺失时安装失败。

Hermes 在 Chorus 后台服务中登记为 offline。chorus upgrade --plugins 和 chorus agents run --type hermes 均不支持它。更新 CLI 后，用 chorus agents add --agents hermes 重装两个插件，再运行 hermes gateway restart。发布标签安装、远端 MCP、技能和所有者审批详见 Hermes Agent。

启动智能体：chorus agents run

Section titled “启动智能体：chorus agents run”

chorus agents run 在你的终端里启动一个已配置的智能体，并自动接好它的 Chorus 连接，相当于后台服务 唤醒的前台版本。由于子进程无法改动父 shell 的环境，该命令会把连接直接注入被启动的智能体进程， 因此你无需手动 export 任何变量。

Terminal window
chorus agents run --name work -- --model opus        # 启动名为 "work" 的智能体；把 --model opus 传给它
chorus agents run                                    # 启动唯一一个已配置的智能体
chorus agents run --name work --type codex -- resume # 覆盖后端，再把 `resume` 透传过去
  • 选哪个智能体：--name <name|uuid> 从 ~/.chorus/daemon.json 的 agents[] 中选取。只有一个智能体时可省略； 有多个时请传 --name（或设置 CHORUS_AGENT_PROFILE），否则命令会报错而不擅自猜测。
  • 注入了什么（只注入被启动的进程，绝不进入你的 shell，也绝不打印）：CHORUS_URL、 CHORUS_API_KEY 和 CHORUS_AGENT_PROFILE。
  • 启动哪个二进制：默认取该智能体存储的后端，--type 可覆盖。类型分别映射到 claude、codex、 kiro-cli、pi、opencode、openclaw 和 dsh。以 OpenCode / OpenClaw / DeepSeek Harness 添加的智能体会被存储为 offline（后台服务不会自动唤醒它们），启动它们时需显式传 --type。
  • 透传：-- 之后的一切都会原样交给智能体，因此智能体自身的全部参数都可使用。智能体继承你的终端， chorus agents run 以它的退出码退出。

持久化 args/env 与一次性覆盖

Section titled “持久化 args/env 与一次性覆盖”

选中的 agents[] 条目可设置 args（字符串数组，默认 []）和 env（字符串到字符串的对象，默认 {}），后台服务唤醒与前台启动都会使用。agents[] 非空时，条目不继承顶层的 args / env，在顶层设置它们会报错。可复制的模型/思考/env 示例、扁平文件迁移、校验和密钥保护注意事项，参见后台服务指南。

值按字面传递：不做 shell 展开、不加载 dotenv、不查询密钥服务。env 只影响被启动的智能体。CHORUS_* 以及 Claude Code 嵌套变量 CLAUDECODE / CLAUDE_CODE_ENTRYPOINT 为保留名称（不区分大小写），配置它们会报错，而不是被静默丢弃。持久化参数不能覆盖由 Chorus 管理的选项（会话、提示词、协议、工作目录、MCP 或权限控制），也不能包含 -- / - 分隔符，或只打印帮助、版本信息就退出的选项。启动时显式传入的参数会原样转发，包括原生恢复命令。这些检查只防范已知冲突，并不是沙箱。

每次运行 chorus agents run 都会重读文件；后台服务要在 chorus daemon restart 之后才会读取更改。两者都不影响已在运行的智能体。--type 选定的后端用于校验以及匹配覆盖项，不会转换后端参数。

仅限下表中的选项：在所选命令作用域中显式传入其中一个，就会替换配置中的同名选项及其值：

实际后端可识别的覆盖项
claude-code / claude--model、--effort
codex--model / -m / 配置键 model；配置键 model_reasoning_effort
kiro--model、--effort
pi--model、--thinking、--provider
opencode--model / -m
openclawagent 的 --model、--thinking（-m 是消息，不是模型）
dsh无；改用 DSH_PROVIDER / DSH_MODEL 环境变量

匹配支持 --option value、--option=value，以及表中列有 -m 时的 -mVALUE / -m=VALUE。Codex 支持 -c key=value、-ckey=value、-c=key=value、--config key=value 和 --config=key=value；仅表中的两个键参与优先级处理，其他配置条目保留。后端自身也必须支持该写法：Pi 0.85.1 的 --model、--thinking、--provider 请将值分开传递，不要用等号形式。

Terminal window
chorus agents run --name pi-worker -- --model anthropic/claude-sonnet-4-6 --thinking medium
chorus agents run --name codex-worker -- exec --model gpt-5.4 -c model_reasoning_effort=high

子命令：持久化参数插入最深的已识别命令之后：Codex 的 exec、exec resume 或 resume，Kiro 的 chat，OpenClaw 的 agent。显式覆盖也应放在同一作用域，如 exec --model chosen，而非 --model chosen exec。放在子命令之前的模型选项不会替换子命令中配置的模型；Codex 的 -c/--config 键跨作用域生效。未识别到命令时，配置参数放在最前面。其他命令路径不做推断；对这些路径，请去掉不兼容的持久化参数，改用原生透传。

未知选项：

  • 持久化 args 允许普通的未知选项，但无法判断下一项是值还是提示词。后端支持时请写成 ["--future=value"]，而不是 ["--future", "value"]。已知选项必须提供其要求的值。
  • 未知或可重复的选项在所选作用域内保持先配置、后显式的顺序；不保证后出现者生效。
  • 遇到有歧义的显式选项（未知且没有内联值）后，Chorus 不再查找覆盖项；请把已知覆盖项放在它之前，或使用受支持的内联值。移除外层 Chorus 分隔符后，分析也会在智能体参数中第一个单独的 -- 处停止。
  • 命令识别遇到位置提示词、未知命令或有歧义的选项时停止，并跳过已知选项的值。
  • 所有显式参数仍会原样转发；后端参数及版本兼容性需由你自行确认。Windows .cmd/.bat 的限制见后台服务指南。

Codex 后台服务进一步将持久化参数限制为模型选项和允许的 -c / --config 覆盖。其他参数即使在前台会话中可用，也会在后台服务唤醒智能体之前报错。参见 Codex 后台服务配置。

从 shell 调用 MCP 工具：chorus mcp

Section titled “从 shell 调用 MCP 工具：chorus mcp”

chorus mcp 是一个原生 MCP 客户端，可从脚本或终端调用任意 Chorus 工具，且无需消耗模型 token。它取代了 早先的 chorus-api.sh / chorus-mcp-call.sh 封装脚本。

Terminal window
chorus mcp call <tool> '<json>'                  # call a tool with a JSON argument object
chorus mcp call <tool> --arg key=value           # set one string argument
chorus mcp call <tool> --arg-file content=<path> # stream a file's raw bytes into an argument
chorus mcp whoami                                 # print this agent's own UUID
chorus mcp list                                   # list the tools this agent may call

--arg-file 让大段内容（如文档正文、OpenSpec 文件）无需经模型重新输入即可送达工具。 成功时，chorus mcp call 会把工具结果原样打印到 stdout；工具或传输错误会输出到 stderr，并以 非零退出码结束。

身份按以下顺序解析：--agent <name|uuid> → 显式的 --url + --api-key 参数 → CHORUS_AGENT_PROFILE → CHORUS_URL + CHORUS_API_KEY → 唯一的已配置智能体（仅当只有一个时）。

连接环境变量

Section titled “连接环境变量”
变量含义
CHORUS_URLChorus 实例的 URL。
CHORUS_API_KEY智能体 API 密钥（cho_…）。
CHORUS_AGENT_PROFILE可选，要充当的已配置智能体的名称或 UUID。设置后，chorus mcp 会从 ~/.chorus/daemon.json 读取该智能体的密钥，因此你无需导出 CHORUS_API_KEY。

后台服务唤醒的会话会自动获得 CHORUS_AGENT_PROFILE；只有当交互式 shell 需要充当某个特定的 已配置智能体时，你才需要手动设置它。

凭据写往何处

Section titled “凭据写往何处”

chorus agents add 总是把校验后的凭据写入 ~/.chorus/daemon.json（权限 0600；密钥绝不会 回显）。对其中四种智能体，它还会把凭据写入该智能体自己的配置，让交互式会话无需任何手动导出 即可完成认证：

智能体额外的凭据落地位置
Claude Code~/.claude/settings.json 的 env 块（遵循 CLAUDE_CONFIG_DIR）。
Codex~/.codex/.env（遵循 CODEX_HOME）；Codex 通过一个不内置密钥的 config.toml 条目从环境变量读取密钥。
DeepSeek Harness$DSH_HOME/.env。
Hermes$HERMES_HOME/.env（默认 ~/.hermes/.env，权限 0600）；远端 MCP 配置保存密钥占位符。

Kiro、OpenCode 和 OpenClaw 从各自已安装的配置读取凭据；对于后台服务唤醒的 Kiro，则从后台服务 每次唤醒时导出的环境变量读取。

面向智能体

Section titled “面向智能体”
  • 触发条件。 你来到本页，是为了安装或升级命令行工具、配置某个智能体（chorus agents add）， 或从 shell 调用某个 Chorus 工具（chorus mcp call）。
  • 约束。 对文档镜像等大段内容的调用，优先使用 chorus mcp call <tool> '<json>' --arg-file content=<file>；仅当 chorus 不在 PATH 中时， 才回退到 chorus-api.sh / chorus-mcp-call.sh。绝不要把 API 密钥粘贴到命令行或终端历史里， 交由 chorus agents add / chorus login 接收密钥。
  • 引用来源。 运行 chorus --help 和 chorus <command> --help 查看权威的参数说明；它始终与 已安装的版本一致。

相关阅读

Section titled “相关阅读”