管理后台服务

选择运行方式

chorus daemon 会把本机的 Claude Code、Codex、Kiro 或 Pi 连接到 Chorus。首次接入时，建议先在前台运行，确认登录、运行后端和工作目录都正确：

chorus daemon --agent claude-code --cwd /home/demo/workspace --chorus-only

前台运行便于直接查看错误，也可以随时按 Ctrl+C 停止。确认正常后，再安装为 Linux 用户服务。

配置工作目录

每个 --cwd 参数都会注册一个可供 Chorus 选择的工作目录：

chorus daemon \
  --agent claude-code \
  --cwd /home/demo/workspace \
  --cwd /home/demo/workspace/service \
  --chorus-only

只添加智能体确实需要访问的目录。若希望用户能在某个目录树中选择尚未注册的子目录，可另外设置浏览根目录：

chorus daemon --browse-root /home/demo/workspace

浏览根目录不会自动把所有子目录注册为连接。项目中已经固定的主机和工作目录会继续用于后续任务与会话，除非用户明确更改。

为项目的智能体固定工作目录时，该路径必须是本 daemon 所服务的目录之一，请把它加入本 daemon 的 cwds 集合，固定的目录才能解析为在线连接。

配置 `daemon.json`

daemon 的设置都读自 ~/.chorus/daemon.json。常见的单智能体场景下，它是一个扁平的 JSON 对象，同时保存智能体凭据和运行选项；若要用一个 daemon 同时服务多个智能体，则改为在 agents 数组中逐一列出（见下文「在一个 daemon 中运行多个智能体」一节）。无论哪种形式，该文件都以 0600 权限（仅所有者可读写）写入，采用先写临时文件再原子重命名的方式，因此写入过程中崩溃也不会留下被截断的文件。默认路径为 ~/.chorus/daemon.json（从主目录解析而来），可用 CHORUS_DAEMON_CONFIG_PATH 指定其他文件。使用覆盖路径时，请为 CLI 与 daemon 服务一致地设置该变量；在 shell 中导出它不会改变已运行的服务。

字段

字段	类型	含义
`url`	string	Chorus 服务器 URL。
`apiKey`	string	智能体 API 密钥（`cho_…`）。
`agentUuid`	string	已认证的智能体 UUID（仅供参考）。
`agentName`	string	已认证的智能体名称（仅供参考）。
`cwds`	string[]	本 daemon 服务的工作目录。每个路径都是一个独立的在线连接。
`browseRoots`	string[]	向远程工作目录发现开放的根目录。浏览根目录不会创建连接。
`agent`	string	要唤起的本地运行后端：`"claude-code"`、`"codex"`、`"kiro"` 或 `"pi"`。
`sigintTimeoutMs`	number	收到 `SIGINT` 后强制终止已唤起智能体前的宽限时间（毫秒）。默认 `10000`。
`agents`	object[]	可选。用一个 daemon 服务多个独立智能体；每个条目可覆盖共享运行默认值，但不会继承 `args` 和 `env`。见下文「在一个 daemon 中运行多个智能体」。

执行 chorus login 加 chorus daemon install 后的最简文件：

{
  "url": "https://chorus.example.com",
  "apiKey": "cho_REDACTED",
  "agentUuid": "8a1c…",
  "agentName": "Build Agent",
  "cwds": ["/home/demo/work/project-a"],
  "browseRoots": ["/home/demo/work"],
  "agent": "claude-code",
  "sigintTimeoutMs": 10000
}

文件如何创建

chorus agents add 是该文件首次创建的常规方式：它会校验每个已配置智能体的凭据，并将其作为 agents 数组中的一个条目写入。参见连接智能体运行环境。
chorus login 校验 URL 和密钥后，写入 url、apiKey、agentUuid 和 agentName，对应一个扁平的单智能体。
chorus daemon install 会额外写入 cwds、browseRoots 和 agent（当这些项尚未设置时，会提示输入所服务的目录和运行后端）。
首次在终端运行 chorus daemon 时，会以交互方式补全缺失的凭据并写入。

文件如何更新

每个写入方都执行浅合并：新字段合并到磁盘上已有内容之上，无关字段予以保留。重新运行 chorus login 会刷新凭据，而不会清除你的 cwds、agent 或 sigintTimeoutMs；重新运行 chorus daemon install 会更新所服务的目录集合，而不会丢弃凭据。缺失或损坏的文件会被当作空对象处理，因此重新登录始终能生成有效文件，而不会失败。

字段、命令行参数与环境变量

下表中的运行选项可通过三种方式提供。优先级为命令行参数，其次是环境变量，最后是 daemon.json，因此一次性的参数或环境变量覆盖无需写入文件：

关注点	`daemon.json` 字段	命令行参数	环境变量
服务器 URL	`url`	`--url`	`CHORUS_URL`
API 密钥	`apiKey`	`--api-key`	`CHORUS_API_KEY`
工作目录	`cwds`	`--cwd`（可重复）	`CHORUS_DAEMON_CWDS`
浏览根目录	`browseRoots`	`--browse-root`（可重复）	`CHORUS_DAEMON_BROWSE_ROOTS`
运行后端	`agent`	`--agent`	`CHORUS_AGENT`
SIGINT 宽限	`sigintTimeoutMs`	`--sigint-timeout`	`CHORUS_DAEMON_SIGINT_TIMEOUT`
权限模式	（不持久化）	`--yolo` / `--chorus-only`	`CHORUS_YOLO` / `CHORUS_CHORUS_ONLY`

权限模式特意不保存到 daemon.json。请在启动时传入 --chorus-only（或设置 CHORUS_CHORUS_ONLY=1）；安装为服务时，--chorus-only 会被写入服务单元，而不是文件。

在一个 daemon 中运行多个智能体

一个 chorus daemon 进程可以同时服务多个完全独立的智能体（不同的人设、权限、账户，甚至不同的运行后端），而无需为每个智能体单独跑一个 daemon。把它们逐一列在 agents 数组中，每个条目就是一个智能体：

{
  "url": "https://chorus.example.com",
  "sigintTimeoutMs": 8000,
  "agents": [
    { "apiKey": "cho_alpha", "agentType": "claude-code", "cwds": ["/home/demo/project-a"] },
    { "apiKey": "cho_beta", "agentType": "kiro", "cwds": ["/home/demo/project-b"], "permissionMode": "chorus" }
  ]
}

url、sigintTimeoutMs 等共享运行设置提供默认值，智能体自己的设置可覆盖这些默认值。args 和 env 只属于单个智能体，不是共享默认值。每个智能体都有自己的身份（由其密钥决定）、自己的连接（每个 cwds 一个）、自己的唤起队列和自己的运行后端，因此它们各自独立地被唤起和运行，一个智能体出错不会影响其他智能体。在服务器端，每个智能体都以 agent、主机、目录为键，作为独立连接显示在设置 → 智能体（Settings → Agents）中。多个智能体甚至可以共享同一个工作目录；daemon 不会对它们串行化，因此请避免在同一个 git 工作树中并发地做互相冲突的工作（改用不同的分支或 worktree）。

每个智能体的字段

字段	含义
`apiKey`（必填）	该智能体的 `cho_` 密钥，决定其身份。
`url`	Chorus 服务器（可按智能体不同，如不同的服务器或公司）。
`agentType`	`claude-code`、`codex`、`kiro` 或 `pi`（后端可以混用）。
`cwds`	该智能体服务的工作目录（每个一个连接）。
`permissionMode`	`yolo` 或 `chorus`。
`maxConcurrency`	该智能体自己的唤起并发上限（默认 `4`）。
`sigintTimeoutMs`	中断升级的宽限时间（毫秒）。
`browseRoots`	目录发现的允许列表。
`args`	可选的字符串数组，作为后端 CLI 的额外参数，默认 `[]`。见下文「设置智能体的模型、思考级别和环境变量」。
`env`	可选的对象，将环境变量名映射到字符串值，默认 `{}`。

设置智能体的模型、思考级别和环境变量

在 ~/.chorus/daemon.json 中为目标智能体添加字段。下面的 Pi 示例使用占位凭据和非敏感环境变量值；请替换为适合你的 URL、密钥和模型，并合并到现有文件中，不要覆盖其他智能体：

{
  "url": "https://chorus.example.com",
  "agents": [
    {
      "agentName": "pi-worker",
      "apiKey": "cho_REDACTED",
      "agentType": "pi",
      "args": ["--model", "anthropic/claude-sonnet-4-6", "--thinking", "high"],
      "env": { "PROVIDER_REGION": "us-east-1" }
    }
  ]
}

模型仅为示例，不是 Chorus 默认值。请使用后端支持的参数和值；没有独立的 model 或 thinking 字段。daemon 唤起和 chorus agents run --name pi-worker 都会使用这个条目。offline 智能体仍不会被 daemon 唤起。

不继承全局设置：存在非空 agents 数组时，顶层 args 或 env 会报错。请移入每个需要它们的条目，不会影响其他智能体或你的 shell。
按字面传递：args 的每个元素是一个参数，不要额外加 shell 引号。$HOME、${TOKEN} 和 shell 命令不会展开。Chorus 不额外加载 dotenv、不插值、不查询密钥服务，也不对 env 值做特殊处理。env 覆盖子进程继承的环境，但 Chorus 管理的控制项仍优先。Windows 环境变量名不区分大小写，POSIX 区分。
校验：null、非字符串参数或值、NUL 字符，以及不符合 [A-Za-z_][A-Za-z0-9_]* 的变量名会在启动前被拒绝。允许空字符串值。请填写选项，而非位置提示词或子命令。未知选项在后端支持时用 "--future=value"；"--future", "value" 存在歧义，会被拒绝。
受保护的控制项：持久化参数不能更改已知的会话/恢复、提示词、传输/输出、工作目录、托管 MCP 或权限控制。帮助/版本、会导致程序直接退出的检查选项、单独的 -- 和标准输入标记 - 也被禁止。所有 CHORUS_* 环境变量名以及嵌套 Claude 上下文变量 CLAUDECODE / CLAUDE_CODE_ENTRYPOINT 均保留，不区分大小写；配置这些名称会报错，而不是被静默删除。请改用专用的 Chorus 设置或显式前台透传。
Windows 命令包装器：通过 .cmd/.bat 启动时，配置中的空参数，以及含空白、引号或命令元字符的参数会被拒绝。需要这些值时请用原生可执行文件；通过包装器的显式前台透传不保证 shell 安全。

Env 可包含明文提供方凭据。请保护文件（POSIX 上用 chmod 600 ~/.chorus/daemon.json），切勿提交密钥。Chorus 的校验和启动消息不显示配置值，但子程序或操作系统检查仍可能暴露它们；没有加密或密钥库支持。若设置 CODEX_HOME 或 PI_CODING_AGENT_DIR 等自定义目录，也需在其中配置 Chorus 集成。

应用更改：运行 chorus daemon restart。daemon 在启动时读取这些设置，而非每次唤起时；编辑文件不会改变运行中的子进程，重启前的后续唤起也仍使用旧设置。每次新的 chorus agents run 都会重读配置，但不影响已运行的子进程。删除 args/env 即可恢复未自定义的行为。

旧式扁平文件：没有非空 agents 数组时，顶层 args/env 用于唯一的 daemon 智能体。前台选择要求使用 agents[]。要共用设置，请将扁平的 URL、密钥、身份信息、args 和 env 移入一个条目，并将 agent 改名为 agentType。通过 chorus agents add 或 chorus login --add 添加智能体，也会将已有扁平凭据配置及其 args/env 移入 agents[0]，删除对应顶层键。缺少密钥的不完整扁平配置需要先补全或手动转换。

一次性覆盖和子命令的具体规则见 CLI 参考。

添加另一个智能体

chorus login --add 校验一个新密钥并把它追加为另一个智能体。在扁平文件上首次使用 --add 时，会把已有凭据迁移到 agents[0]，并把新密钥添加为 agents[1]；重复的密钥会被拒绝，已有的智能体绝不会被覆盖。
chorus daemon install --add 会循环运行安装向导，让你在一次运行中添加多个智能体（仅限终端）。
始终支持手动编辑 ~/.chorus/daemon.json。

编辑文件后请重启 daemon（chorus daemon restart），然后在设置 → 智能体（Settings → Agents）中确认每个智能体都已出现。

各后端如何拿到自己的密钥

每个智能体都用自己的密钥认证，但这个密钥如何到达被唤起的子进程，取决于后端：

Claude Code：自动。daemon 会为每次唤起写入一份携带该智能体 URL 和密钥的 MCP 配置。无需额外配置。
Kiro：自动，通过环境变量。已安装的 mcp.json 引用 ${CHORUS_URL} 和 ${env:CHORUS_API_KEY}，daemon 会在每次唤起时导出它们，因此每个 Kiro 智能体都用自己的密钥认证。
Codex：自动，通过环境变量。chorus agents add 会把 Codex 配置为不内置密钥：它把 CHORUS_URL / CHORUS_API_KEY / CHORUS_AGENT_PROFILE 写入 ~/.codex/.env（Codex 在启动时加载它），并在 config.toml 中设置 bearer_token_env_var = "CHORUS_API_KEY"，因此 Codex 从环境变量读取密钥，而不是从写死的字面量读取。daemon 会在每次唤起时注入各智能体自己的密钥，因此一个 daemon 中的多个 Codex 智能体各自以自己的身份认证。
Pi：自动，通过环境变量。daemon 会在每次唤起时把各智能体自己的 CHORUS_URL / CHORUS_API_KEY / CHORUS_AGENT_PROFILE 导出到被唤醒的 pi 会话中，由 chorus-pi 扩展读取，因此每个 pi 智能体都用自己的密钥认证。

安装 Linux 用户服务

在 Linux 上，可让 Chorus 自动创建并启动用户级 systemd 服务：

chorus daemon install --agent claude-code --cwd /home/demo/workspace --chorus-only
chorus daemon status

安装脚本会立即启动该服务，并将其配置为在用户登录时自动启动。请先运行 chorus agents add（或 chorus login），服务才能读取已保存的凭据；也可以给 chorus agents add 传入 --daemon-autostart，在同一步中安装这个开机服务。

常用管理命令：

chorus daemon logs
chorus daemon restart
chorus daemon uninstall

更改登录信息、运行后端或工作目录后，请重启服务。需要让服务在用户退出登录后继续运行时，请先确认系统策略允许，再由系统管理员配置用户驻留。

为被唤醒的智能体提供所需凭据

daemon 自动提供 Chorus 连接（CHORUS_URL、CHORUS_API_KEY 和 CHORUS_AGENT_PROFILE），不会自动提供模型提供方凭据。若后端从环境变量读取提供方凭据，可通过该智能体的 env 提供，也可通过 daemon 继承的环境提供。systemd --user 服务不会继承登录 shell 中导出的变量。如需通过服务提供，请用 drop-in 设置后重启：

[Service]
Environment=EXAMPLE_PROVIDER_API_KEY=…

systemctl --user daemon-reload && systemctl --user restart chorus-daemon

从文件读取提供方认证的后端（例如 Claude Code 和 Codex，位于 ~/.claude / ~/.codex）只需正确设置后台服务的 HOME，已安装的服务单元已经做到了这一点。

macOS 与 Windows

在 macOS 上，chorus daemon install 会像在 Linux 上一样安装真正的 launchd 开机服务。在 Windows 上，它会输出服务模板和手动配置步骤；测试连接时，请以前台方式运行 chorus daemon 作为基准。

服务在线后，可继续阅读从 Chorus 发起远程工作；运行异常时，请查看排查智能体连接故障。