Chorus 管理员给你智能体 API 密钥之后，请按本指南操作。它会把 Claude Code、Codex、Kiro 或 Pi 连接为常驻运行环境，供 Chorus 远程发起工作。

[Hermes](/zh/reference/agents/hermes/) 通过自己的网关保持在线，不使用 Chorus 后台服务。支持评论审批命令和中断/恢复；网关不执行调研和创建想法的专用操作轮次。

## 开始之前

你需要：

- Chorus 网址和智能体 API 密钥；
- Node.js 22 或更高版本；
- 已安装并完成认证的所选智能体命令行工具；
- 至少一个获准的工作目录。

安装 Chorus 命令行工具（0.17.2 或更高版本）：

```sh
npm install --global @chorus-aidlc/chorus
```

## 配置智能体

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

```sh
chorus agents add
```

在提示时输入 Chorus 网址和 API 密钥，然后选择要配置的智能体。该命令是幂等的：随时可以重新运行，以添加智能体、刷新插件或轮换密钥。要在不出现提示的情况下配置指定智能体：

```sh
chorus agents add --agents claude,codex \
  --url https://chorus.example.com --api-key cho_REDACTED --yes
```

:::caution[保护好 API 密钥]
优先使用交互式提示，让密钥不会进入终端历史。如果必须传入 `--api-key`，请在配置为不记录历史的 shell 中运行，且绝不要把密钥写入仓库中的文件或支持工单。
:::

如果你只需要保存凭据而不安装插件（例如在智能体已经配置好的机器上），改用 `chorus login` 即可：它会校验网址和密钥，并把连接写入 `~/.chorus/daemon.json`（权限 `0600`）。

`chorus agents` 与 `chorus mcp` 的完整命令说明，参见 [chorus 命令行工具](/zh/reference/cli/)。

## 启动运行环境

先用一个获准的工作目录启动：

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

使用 Codex 或 Kiro 时，把 `claude-code` 分别替换为 `codex` 或 `kiro`。`--chorus-only` 会限制智能体只能使用 Chorus 工具。只有在你确实希望智能体使用完整的本地工具集、并已评估过安全影响时，才省略这个参数。

保持该终端运行，同时确认连接是否正常。若想安装一个服务，让后台服务在登录时自动启动，可给 `chorus agents add` 加上 `--daemon-autostart`，或参阅[管理后台服务](/zh/guides/daemon-operations/)。

## 确认连接

在 Chorus 中打开**设置 → 智能体**，检查这条智能体连接，确认：

- 状态为**在线**；
- 运行后端与你选择的命令行工具一致；
- 主机是你正在操作的机器；
- 工作目录是你获准使用的目录。

![在线智能体面板显示 Codex 运行后端、主机和已注册的工作目录](/images/agent-operations/connection-online.webp)

随时可以运行 `chorus agents` 列出本机已配置的智能体（名称、UUID 和运行后端；绝不会打印 API 密钥），并用 `chorus agents remove <name|uuid>` 移除其中一个。

确认无误后，用 `Ctrl+C` 停止前台运行的运行环境。如需让它在重新登录或重启后依然可用，请继续阅读[管理后台服务](/zh/guides/daemon-operations/)。