Codex

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

安装前，请按照为智能体创建访问权限创建智能体密钥。

安装集成

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

npm install --global @openai/codex

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

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，可以跳过这一节。否则，请按照 连接智能体运行环境选择 codex 作为运行后端。 先在前台确认连接无误，再按照管理后台服务让它保持在线。

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 显式运行前台命令；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）中明确添加：

[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。恢复流程见中断与恢复会话。

验证连接

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

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

能力与限制

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

通用的操作流程见从 Chorus 发起远程工作和中断与恢复会话。

从终端恢复会话

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

codex exec resume <thread_id>

Codex 会自行生成线程 ID，因此复制到的是这个线程 ID，而不是 Chorus 分配的会话 ID；Chorus 恢复运行时传回 Codex 的正是这个值。完整流程见中断与恢复会话。

常见问题

• 找不到 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，然后参阅排查智能体连接故障。