用途:当 Codex 需要跨多个智能体进行实时协调时使用 Agent Relay,弥补 Codex 子智能体工作流中点对点通信的缺口。它让 Codex 能够连接 Agent Relay 工作区、生成具备 relay 能力的 worker、发送直接消息、频道更新与线程回复,并通过 ACK、STATUS、BLOCKED、DONE 信号保持 lead 与 worker 状态同步。
主要能力:工作区创建与密钥设置;智能体注册;收件箱检查;直接消息、频道与线程消息;relay-spawned worker 的生成与释放;观察者链接生成,输出带作用域、只读、24 小时有效的令牌(ot_live_...),排除 agent 私信,可通过 --channels、--include-dms、--expires 调整,并用 agent-relay observer revoke <id> 撤销。
使用方式:首次激活时技能运行 scripts/setup.sh 自动配置 Codex,将 Agent Relay MCP 服务器加入 .codex/config.toml,启用 hooks、安装 hooks.json 并复制 relay-worker.toml 智能体定义。启动需按序完成:设置工作区(用 RELAY_WORKSPACE_KEY 调用 set_workspace_key,或调用 create_workspace);调用 register_agent 注册,类型为 "agent";检查收件箱 check_inbox;对任务分配发送 ACK,否则发送 BLOCKED;完成后发送 DONE。生成 worker 可用 add_agent(name, cli, task),可选 channel、persona、model;已有进程用 register_agent。
限制与注意:不得假设当前 MCP 会话已有活动工作区,注册前必须先设置或创建工作区;不要打印工作区密钥或据此构造观察者 URL,该密钥为管理凭证;relay 身份需全程稳定;非 lead 明确要求不得生成额外 worker;worker 30 秒未确认需排查并重试,第二次仍无 ACK 则向用户报告失败步骤。若工作区创建或注册失败,重试一次后如实报告,不要在没有 relay 连接的情况下继续。