用途
codex-delegate 用于把一项边界清晰的编码任务交给独立的实现者,即 OpenAI Codex CLI,然后由编排方自行审查其产物并落地提交。它仅在用户明确要求委派给该实现者时使用。编排方负责写任务简报并做判断,Codex 在自己的沙箱中完成代码编写,编排方负责验证并提交。
该循环不依赖特定编排智能体,只需能运行 shell 命令和读取文件,因此在 Claude Code、OpenCode 或其他同类智能体中原理一致。文档说明其设计与运行基于 Claude Code,其他编排方属于“设计上支持、尚未验证”。
主要能力
- 五步循环:1) 编写简报;2) 派发;3) 等待完成;4) 审查(不轻信自述);5) 落地提交。其中步骤 1、4、5 依赖编排方判断,2、3 为机械操作。
- 简报要求:Codex 只能看到发送的文本,没有仓库记忆、聊天历史或共享上下文,因此简报需包含目标、当前状态、要改什么、不要动什么、项目实际的检查(gate)命令(从 CLAUDE.md/AGENTS.md/Makefile 中发现,不可假设)以及报告约定,并告知 Codex 不会提交。每个简报只放一个任务。
- 派发辅助:通过捆绑的 relay.mjs 封装 codex exec,捕获运行并写出结构化 result.json。支持 --read-only(只读审查/诊断)、--session <threadId>(继续同一 Codex 会话)、--resume-last(无线程 ID 时的回退)、--timeout(看门狗硬超时,默认关闭)。
- 等待完成:辅助脚本会阻塞直到 Codex 结束;在 Claude Code 中可用 run_in_background,在普通 shell 中可前台运行或后台轮询 result.json。运行完成的判断是 result.json 已写出且进程已退出。
- 审查:需自行重跑项目的测试/代码检查/构建命令,不采信“检查通过”的自述;对照简报阅读 diff,检查是否多改(范围蔓延)或少改;可用 guard 类技能审查 diff;模式/迁移变更需往返验证,删除项需 grep 悬空引用。
- 落地:由于 Codex 沙箱无法可靠写入 .git,由编排方提交;仅在检查通过且 diff 符合要求后提交。需要修改时,用上一轮 result.json 中的 --session <threadId> 发送增量简报并再次审查。
- 只读第二意见:以 --read-only 派发,让 Codex 对争议点逐条辩护或让步,产物在其最终消息中,不触碰文件。Codex 的沙箱会强制执行只读;其他实现者的只读保证强弱不同,需自行检查 touchedFiles 是否为空。
使用方式
前置检查:codex --version 成功,否则安装 npm i -g @openai/codex 并执行 codex login;确认 PATH 上是哪个 codex(多次安装常见);处于或指向目标 git 仓库;Node 18+ 与 git 为前置条件。
派发命令(<skill-dir> 为该技能安装目录):
node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
只读:add --read-only
继续会话:add --session <threadId>
回退:add --resume-last
超时:add --timeout 2h
帮助:node .../relay.mjs --help
辅助脚本默认使用可写(workspace-write)沙箱,并将产物写入临时目录,使被审查仓库保持干净;它从不提交。
适用场景
- 需要把一项边界明确的编码任务交给 Codex 实现,并由编排方审查 diff 与检查后提交。
- 对争议点获取无写入风险的对抗性第二意见。
- 顺序处理任务队列,并逐项审查与落地。
限制
- 任务足够小、直接内联完成更划算时不应使用,委派开销不值得。
- codex CLI 未安装或未登录时不可用。
- 若想自己写代码或只需要评审,应使用 Codex 自带的 review 命令。
- 本条目为文档导入,未包含可执行脚本 scripts/relay.mjs,完整运行时需参考上游。
- relay 从不提交,只返回结构化结果 JSON,提交由编排方完成。
- 改编自 amElnagdy/delegate-skills(MIT),仅为文档,未捆绑运行时。
授权模型
委派需人类主动选择。一旦用户确认(如“运行这个队列”“继续”),提交已验证且检查通过的工作即为约定的契约。两项限制:如实上报而非默默吸收(报告 Codex 的设计决策、有道理但未被要求的改动、非阻塞的小问题),以及在范围变更时停下询问,不要自行扩大授权。
与 openai-codex 插件的关系
官方 openai-codex Claude Code 插件与 codex-delegate 互补:插件的 codex:codex-rescue 代理是单向转发器,不轮询、不审查、不提交;插件的 review 命令与 stop-review 检查是反向的(Codex 审查你的工作)。codex-delegate 是另一方向的编排循环:你驱动 Codex 实现一个任务或队列,由你审查并落地每个结果。若已安装该插件,其配套 CLI 可作为可选的派发后端;默认仍是捆绑的 relay.mjs,因为它除 codex 二进制外无需额外安装。