Codex 有 Chorus 官方集成，提供工具、工作流技能和钩子。它也是受支持的 Chorus 后台服务后端。

安装前，请按照[为智能体创建访问权限](/zh/guides/administrator-setup/)创建智能体密钥。

## 安装集成

如果尚未安装 Codex，先安装它：

```bash
npm install --global @openai/codex
```

然后用 `chorus` 命令行工具安装 Chorus 集成：

```bash
npm install --global @chorus-aidlc/chorus
chorus agents add --agents codex
```

在提示时输入 Chorus 地址和智能体密钥。`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 从环境变量读取密钥，配置文件中从不包含密钥。完成后重新启动 Codex。

### 让已有 App Server 使用新配置

从 Chorus 0.21.1 起，凭据和 MCP 配置成功写入后，交互式配置可提示你用已保存的环境重启正在运行的 **Codex App Server**。它不是 Chorus 后台服务。所有 Codex 路径都遵循 `CODEX_HOME`，默认 `~/.codex`。

- 重启可能中断其他 Codex 会话及正在进行的工作。提示默认选择**否**，只有明确输入 `y` 或 `yes` 才会重启。
- 非交互、`--yes` 或 `CHORUS_DAEMON_HEADLESS=1` 会延后重启。通用 `--yes` 不代表授权中断会话。
- 没有运行中的 App Server 时不会自动启动；命令不支持、状态未知、配置失败或拒绝覆盖身份时，会安全延后。仅更新插件的流程跳过此步骤。
- 重启失败仍保留已写入的配置；成功只代表重启命令完成，不代表新增的凭据、MCP 工具或模型调用验证。

若暂缓重启，请先保存受影响会话的工作，待安全时在交互终端重新运行 `chorus agents add --agents codex`，不要加 `--yes`。受支持且正在运行的服务会再次给出专门确认，并使用已保存的环境。只重开终端界面可能仍连接旧服务。之后按下文验证连接。安装器不会为获取重启能力而自动升级 Codex。

## 启用远程启动

如果只在交互式 Codex 会话中使用 Chorus，可以跳过这一节。否则，请按照
[连接智能体运行环境](/zh/guides/operator-onboarding/)选择 `codex` 作为运行后端。
先在前台确认连接无误，再按照[管理后台服务](/zh/guides/daemon-operations/)让它保持在线。

## 0.20.0 的 daemon 行为

后台服务唤醒现在每一轮使用一个独立的 `codex app-server --listen stdio://` 进程。最低已验证基线为 **codex-cli 0.157.1**；更早版本未经验证，缺少协议支持会导致唤醒失败。没有回退到 `codex exec` 的机制或后端切换选项。使用自定义 `CODEX_HOME` 时，也要在其中安装 Chorus 集成。更新 Chorus 插件不会升级 Codex CLI 本身。

### 模型参数与会话连续性

后台服务的 `args` 支持模型选择（`--model` / `-m`）和允许的 `-c` / `--config` 设置，例如 `model_reasoning_effort`。其他选项，包括 `--oss`、图片输入和未知参数，会在启动前报错。传输、工作目录、权限和托管 MCP 控制项受保护。请使用支持的配置项，或通过 [CLI](/zh/reference/cli/) 显式运行前台命令；`chorus agents run --type codex -- exec ...` 和 `... -- resume ...` 保持原有行为。

后台服务会以当前工作目录和权限策略恢复已保存的线程，包括旧 `exec` 后端创建的线程。

- **替代线程**：只有明确返回“no rollout found”时，才会新建一次替代线程，并在对话中提示上下文连续性的变化。其他恢复错误会终止本次唤醒，并保留 Chorus 会话与 Codex 线程之间已保存的关联。
- **已保存的会话记录**：如果后台服务读不到已保存的会话记录，会发出警告并重新开始；如果无法保存，会警告后续的连续性可能受影响。
- **新消息**会排队等待后续回合，不会插入正在运行的回合。
- **Token 用量**只报告当前这一轮。如果恢复的线程没有可靠的起始计数，会省略该轮用量，而不是把线程的历史计入。

### 受限模式与工具授权

`--chorus-only` 让 Codex 保持只读，禁用交互审批，并关闭该回合的网络访问。原生审批或用户输入请求会被拒绝；无法安全拒绝的请求会使唤醒失败。需要提问时，请通过 Chorus 评论或需求细化。在已验证的 Codex 版本中，需要审批的 Chorus MCP 工具也可能被拒绝，包括 `chorus_checkin`。回合完成不代表其中的 MCP 调用成功。

如果你决定允许签到，可在 `~/.codex/config.toml`（或该智能体的 `CODEX_HOME/config.toml`）中明确添加：

```toml
[mcp_servers.chorus.tools.chorus_checkin]
approval_mode = "approve"
```

该配置已在 0.157.1 的新建和恢复线程中验证，验证时只读模式和禁用交互审批仍然生效。它只允许签到；评论和任务更新需要各自明确授权并验证。规则应写在 Codex 配置中，不要放进后台服务的 `args`。后台服务不会代替你批准请求。

### 中断与排障

获授权的中断会发送 `turn/interrupt`；启动阶段的取消会关闭传输。随后后台服务会在限定时间内清理进程树。在 Windows 上，这需要 Windows PowerShell（`Get-CimInstance`）和 `taskkill`。

启动或协议失败时，检查 `codex --version`、登录状态、模型与配置，以及本地会话存储权限。初始化限时 30 秒，启动阶段 RPC 响应限时 60 秒，清理限时 10 秒。运行中的回合没有空闲或总运行时长限制，卡住时请用**打断**。`CLOSED` 仅供参考。失败、被中断或从未报告结果的回合都不算成功，即使进程退出码为 0。恢复流程见[中断与恢复会话](/zh/guides/session-recovery/)。

## 验证连接

打开 Codex，让它执行 `check in to chorus`，确认响应显示预期的智能体身份和权限。你也可以用
`/plugins` 和 `/hooks` 确认 Chorus 插件和钩子已启用。

使用后台服务模式时，在 Chorus 中打开**设置 → 智能体**，确认预期的主机和工作目录处于在线状态。

## 能力与限制

- 该集成提供 Chorus MCP 工具、工作流技能和 Codex 钩子。
- 后台服务模式支持远程启动、追加指令、中断和恢复。
- Codex 没有在生成子智能体之前触发的钩子，因此由 Chorus 工作流技能显式管理子智能体会话。
- 远程工作继承本地用户的访问权限。只注册你信任的工作目录。

通用的操作流程见[从 Chorus 发起远程工作](/zh/guides/remote-control/)和[中断与恢复会话](/zh/guides/session-recovery/)。

## 从终端恢复会话

要在自己的终端里接管正在进行的对话，先在对话界面复制它的会话 ID（对话记录顶部的**复制 session ID**），然后在该对话的工作目录下运行：

```bash
codex exec resume <thread_id>
```

Codex 会自行生成线程 ID，因此复制到的是这个线程 ID，而不是 Chorus 分配的会话 ID；Chorus 恢复运行时传回 Codex 的正是这个值。完整流程见[中断与恢复会话](/zh/guides/session-recovery/#从终端接管会话)。

## 常见问题

- **找不到 `codex`**：全局安装 `@openai/codex`，然后重新运行 `chorus agents add`。
- **配置后仍用旧凭据或缺少 `CHORUS_API_KEY`**：检查实际 `CODEX_HOME` 下的 `.env`，重新运行 `chorus agents add --agents codex`，并按上文安全重启 App Server。只有密钥无效或已撤销时才需更换。
- **插件或钩子未启用**：在 `/plugins` 和 `/hooks` 中启用它们，然后重新启动 Codex。
- **后台服务离线**：运行 `chorus daemon status`，然后参阅[排查智能体连接故障](/zh/guides/troubleshooting/)。