codex-delegate

Codex Delegate

你是编排者。此技能可让你将范围明确的编码任务交给独立的实现者——OpenAI Codex CLI，然后审查其产出并由你亲自提交。你撰写任务说明并负责判断；Codex 在自己的沙盒中编写代码；你负责验证并提交。

这里的内容并不专属于某一种编排 Agent。此流程只需要能够运行 shell 命令并读取文件，因此无论你使用 Claude Code、搭配所选模型的 OpenCode，还是任何类似的 Agent，流程都相同。（此技能专为 Claude Code 设计并在其上运行；其他编排者可视为设计适用，但尚未验证。）

以下情况请勿使用

• 任务足够小，可以直接完成——委派的开销不值得。
• 尚未安装或登录 codex CLI（运行 codex login）。
• 你想自己编写代码，或者只需要审查（使用 Codex 自带的 review 命令）。

先决条件（检查一次即可）

1. codex --version 能正常运行。如果不能，请安装（npm i -g @openai/codex）并运行 codex login。
2. 确认 PATH 中的 codex 是哪个版本。 多个安装版本很常见（例如，当前的 npm/nvm 版本和过时的 Homebrew 版本）。command -v codex 会显示当前使用的版本，codex --version 会显示其版本号——较旧的二进制文件不支持此技能依赖的标志（codex exec --json、-o、exec resume）。中继程序也会将运行时的版本记录到 result.json，因此事后可以发现使用了过时的二进制文件。
3. 你当前位于目标 Git 仓库中，或会将 --cd 指向该仓库。

流程

每项任务都按以下五个步骤执行。其中第 1、4、5 步需要你作出判断；第 2、3 步是机械操作。

1. 撰写任务说明

Codex 只能看到你发送的文本——没有仓库记忆、聊天记录或共享上下文。任务所需的一切都要写进任务说明：目标、当前状态、需要修改的内容、需要保持不变的内容、项目实际使用的门禁命令（从仓库的 CLAUDE.md/AGENTS.md/Makefile 中查找——不要假设），以及报告要求。告诉 Codex 它不会提交（由你提交）。每份任务说明只包含一项任务。完整指南和模板见：references/writing-the-brief.md。

此技能将 Codex 选为实现者。Codex 作为编排者是另一种角色：后台等待需要 codex-background 及其配置的 MCP 服务。安装 codex-delegate 不会自动安装或配置该支持工具。请参阅 codex-background 设置指南。

2. 派发

对于 Codex 编排的后台工作，请先安装并配置独立的 codex-background 支持工具。如果缺少它的 MCP 工具或注册表，请停止并报告设置要求；不要悄悄回退到由模型驱动的轮询。然后调用其已注册的 delegate_run MCP 工具一次，以代替下面的 shell 示例。 遵循该技能，使用结构化的通用参数、不变的提供方标志，并通过 runId 重新连接。保持请求待处理，直到任务完成，然后继续执行本技能中的审查和合并步骤。其他编排器继续使用下面的 shell 工作流。

使用随附的辅助工具将任务说明发送给 Codex。它会包装 codex exec、捕获运行信息并写入结构化的 result.json，因此你只需“运行命令、读取文件”。（下文的 <skill-dir> 是此技能的安装目录，即包含此 SKILL.md 的文件夹，也就是你加载此技能的目录。Claude Code 在技能加载时会将其显示为“此技能的基本目录”；在其他编排器中使用同一目录即可。如果不确定它位于何处，请运行 find ~ -name relay.mjs -path '*codex-delegate*'，并将其上级目录填入。）

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
# read-only (review/diagnosis, no edits):   add --read-only
# isolated review (skip ambient MCP/user config): add --ignore-user-config
# subagent defaults:                        add --subagent-model <name> --subagent-effort <level>  (again on every resume)
# web search mode (disabled|cached|indexed|live): add --web-search live  (again on every resume)
# network inside the sandbox (gh, curl, installs): add --network-access  (on resume: --sandbox workspace-write --network-access)
# continue the exact Codex session:         add --session <threadId>  (from result.json; send only the delta brief)
# fallback when no thread id is available:  add --resume-last
# hard time limit (watchdog):               add --timeout 2h  (default: off; implementation runs routinely need 1-2h)
# see all options:                          node .../relay.mjs --help

辅助工具默认使用可写入的（workspace-write）沙盒，并将其产物写入临时目录，因此受审查的仓库会保持干净。它绝不会提交更改——请参阅第 5 步。有关运行机制、标志和 result.json 的结构，请参阅：references/dispatch-and-poll.md。

3. 等待完成

使用 codex-background 的 Codex 会让原始 MCP 请求保持待处理状态：不由模型驱动休眠、状态或日志轮询。只有在请求中断后需要重新连接时，才使用 delegate_wait。

辅助工具会阻塞，直到 Codex 完成，因此请使用编排器提供的任意方式来运行它，并在返回时继续：

• Claude Code： 使用 run_in_background: true 运行 Bash 调用；完成后你会收到通知。
• 普通 shell / 其他 Agent： 对于短任务，在前台运行；也可以将其放到后台并轮询结果文件——在 bash/zsh（包括 Git Bash/WSL）中使用 … &，或使用 shell 对应的命令（PowerShell 中使用 Start-Job，cmd 中使用 start /b）。当 result.json 存在且包含 status 时，说明运行已完成。（运行前的用法错误——参数错误或任务说明为空——会以代码 2 退出，并输出 stderr 消息，且不会写入结果文件，因此也要检查退出代码。缺少 codex 二进制文件时会以代码 127 退出，但仍会写入状态为 codex_unavailable 的 result.json。）

不要只看进度跟踪器，要以实际情况为准：只有在写入 result.json 且进程已退出后，运行才算完成。读取工作树，而不是状态行。实施者的完整报告位于 result.json 的 finalMessage 字段中（也会在标准输出中报告标记之间完整打印）。

4. 审查——不要轻信自我报告

Codex 的 result.json 包含其自己的摘要和门禁结果声明。请重新验证，不要直接采信：

• 自行重新运行项目的门禁（第 1 步中的测试、lint 和构建命令）。切勿轻信“门禁已通过”。
• 根据任务说明阅读差异： Codex 是否按要求完成了工作，没有多做（范围蔓延），也没有少做？以结果中的 touchedFiles 为起点。
• 如果已安装相关守护技能，请在差异上运行它们（例如 guard-skills 中的 clean-code-guard、test-guard 等）——本技能负责产出工作，这些技能负责评判工作。
• 对于架构或迁移更改，执行往返验证；对于删除操作，使用 grep 检查是否存在悬空引用。

完整清单：references/review-and-land.md。

5. 落地

由于 Codex 的沙箱无法可靠地写入 .git（具体情况因版本、操作系统和路径而异），提交由编排器完成。 只有在各项门槛通过且差异内容确认无误后，才执行以下操作：

• 自行提交已验证的工作，并使用清晰的提交说明。
• 如果需要修改，请使用先前 result.json 中的 threadId 通过 --session <threadId> 发送差异说明（只有在没有可用的 thread ID 时才使用 --resume-last），然后再次审查。

只读的第二意见

Relay 也可以用作获取对抗性第二意见的简便方式，且没有写入风险：使用 --read-only 分派任务，并在说明中列出已达成一致的要点，再逐一列出有争议的要点及双方观点，要求 Codex 为每个要点辩护或让步；最终答复中会包含交付内容，且不会触碰任何文件。任何实现者提供只读模式的委派技能都支持同样的用法，但请先检查该模式的保证有多可靠：Codex 的沙箱会强制执行只读，而 Grok 只会尽力遵守，并且只有事后才会标记违规（readOnlyViolation）——使用这些实现者时，请确认返回的 touchedFiles 为空，不要想当然地认为没有编辑。

授权模型

委派需要由用户主动选择。一旦用户同意（“运行此队列”“继续”），提交已验证且通过门槛的工作就是双方约定的流程——这正是整个流程的目的。该授权有两个限制：呈现，不要擅自吸收（报告 Codex 做出的设计决策、有理有据但未经请求的改动，以及不影响流程的细枝末节，而不是默默保留它们）；以及遇到范围变更时停止（如果要正确完成任务就必须超出说明范围，请先询问，不要自行扩大授权范围）。完整说明见 references/review-and-land.md。

如果你安装了 openai-codex 插件

官方的 openai-codex Claude Code 插件非常出色，而且可以互补使用——codex-delegate 基于同一个 codex CLI 构建，并不会取代该插件。它们的方向不同：

• 插件的 codex:codex-rescue Agent 是一个转发器：它将单个任务交给 Codex，然后返回输出。它有意不轮询、不审查，也不提交。
• 插件的审查命令和停止审查门槛则运行在相反方向：由 Codex 审查你的工作。
• codex-delegate 是另一个方向上的编排循环：由你驱动 Codex 在单个任务或任务队列中执行实现，然后由你审查并落地每项结果。这个循环——说明 → 分派 → 轮询 → 审查 → 提交，由编排器负责提交——是插件留给你处理的部分，也是此技能所编码的流程。

如果你安装了该插件，其配套 CLI 可作为可选的分派后端；默认使用捆绑的 relay.mjs，因为除了 codex 二进制文件之外，它无需额外安装（Node 和 git 也是 relay 所需的依赖，且是此处所有技能的先决条件）。

参考资料

• references/writing-the-brief.md — 如何编写 Codex 能够直接执行的说明：结构、XML 块、报告约定，以及如何嵌入实际的门槛命令。
• references/dispatch-and-poll.md — relay.mjs 标志、result.json 约定、各编排器的后台运行方式，以及运行异常时的恢复方法。
• references/review-and-land.md — 审查清单、提交边界，以及针对特定会话的返工周期。
• references/multi-task-queues.md — 如何运行顺序任务队列：延续约束、跟踪进度，以及运行结束时的一致性检查。