codex-delegate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Codex Delegate

Codex 委托工具

You are the orchestrator. This skill lets you hand a bounded coding task to a separate implementer — the OpenAI Codex CLI — then review what it produced and land it yourself. You write the brief and own the judgment; Codex does the typing in its own sandbox; you verify and commit.

Nothing here is specific to one orchestrating agent. The loop needs only the ability to run a shell command and read a file, so it works the same whether you are Claude Code, OpenCode with a selected model, or any comparable agent. (It is designed for and run on Claude Code; treat other orchestrators as designed-for, not yet proven.)

你作为协调者。此技能可让你将一个边界清晰的编码任务交给独立的实现工具——OpenAI Codex CLI，之后审核其产出内容并自行完成提交。你撰写任务说明并负责判断；Codex在专属沙箱中完成代码编写；你负责验证并提交。

此流程不依赖特定的协调Agent。该循环仅需具备执行shell命令和读取文件的能力，因此无论你使用Claude Code、选定模型的OpenCode还是其他同类Agent，其工作方式都一致。（此工具为Claude Code设计并运行；其他协调工具虽适配设计，但尚未经过验证。）

When NOT to use this

请勿使用此工具的场景

The task is small enough to just do inline — delegation overhead is not worth it.
The
```
codex
```
CLI is not installed or not authenticated (run
```
codex login
```
).
You want to write the code yourself, or you only need a review (use Codex's own
```
review
```
command).

任务小到可直接完成——委托的开销得不偿失。
```
codex
```
CLI未安装或未完成认证（执行
```
codex login
```
完成认证）。
你希望自行编写代码，或仅需要审核（使用Codex自带的
```
review
```
命令）。

Prerequisites (check once)

前提条件（检查一次）

codex --version

succeeds. If not, install (

npm i -g @openai/codex

) and

codex login

Confirm which
codex
is on PATH. Multiple installs are common (e.g. a current npm/nvm copy and a stale Homebrew one).
```
command -v codex
```
shows the active one and
```
codex --version
```
its version — an old binary predates flags this skill relies on (
```
codex exec --json
```
,
```
-o
```
,
```
exec resume
```
). The relay also records the version it ran into
```
result.json
```
, so a stale binary is visible after the fact.
You are in (or will point
```
--cd
```
at) the target git repository.

```
codex --version
```
执行成功。若失败，请安装（
```
npm i -g @openai/codex
```
）并执行
```
codex login
```
。
确认PATH中的
codex
版本。多版本安装很常见（例如当前npm/nvm版本和旧版Homebrew版本）。
```
command -v codex
```
显示当前活跃版本，
```
codex --version
```
显示其版本号——旧版二进制文件不具备此技能依赖的参数（
```
codex exec --json
```
、
```
-o
```
、
```
exec resume
```
）。中继工具会将运行版本记录到
```
result.json
```
中，因此事后可发现旧版二进制文件问题。
你处于（或通过
```
--cd
```
指向）目标git仓库中。

The loop

工作流程

Run these five steps per task. Steps 1, 4, and 5 are your judgment; 2 and 3 are mechanical.

每个任务执行以下五个步骤。步骤1、4、5需要你判断；步骤2、3为机械操作。

1. Write the brief

1. 撰写任务说明

Codex sees only the text you send — no repo memory, no chat history, no shared context. Everything the task needs goes in the brief: the goal, the current state, what to change, what to leave untouched, the project's actual gate commands (discover them from the repo's CLAUDE.md/AGENTS.md/Makefile — do not assume), and a report contract. Tell Codex it will not commit (you will). Keep one task per brief. Full guidance and a template: references/writing-the-brief.md.

Codex仅能看到你发送的文本——无仓库记忆、无聊天历史、无共享上下文。任务所需的所有信息都需包含在任务说明中：目标、当前状态、需修改内容、需保留内容、项目的实际验证命令（从仓库的CLAUDE.md/AGENTS.md/Makefile中查找——请勿假设），以及报告约定。告知Codex它不会提交代码（由你完成）。每个任务说明对应一个任务。完整指南和模板：references/writing-the-brief.md。

2. Dispatch

2. 派发任务

Send the brief to Codex with the bundled helper. It wraps

codex exec

, captures the run, and writes a structured

result.json

— so your only job is "run a command, read a file." (

<skill-dir>

below is this skill's installed directory — the folder containing this

SKILL.md

, i.e. the directory you loaded the skill from. Claude Code prints it as "Base directory for this skill" when the skill loads; on other orchestrators use that same directory — if unsure where it landed, run

find ~ -name relay.mjs -path '*codex-delegate*'

and substitute the directory above it.)

bash

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo

通过捆绑的辅助工具将任务说明发送给Codex。它封装了

codex exec

，捕获运行过程，并生成结构化的

result.json

——因此你只需“执行命令、读取文件”即可。（下方的

<skill-dir>

是此技能的安装目录——包含本

SKILL.md

的文件夹，即你加载此技能的目录。Claude Code在加载技能时会打印“Base directory for this skill”；其他协调工具使用相同目录——若不确定位置，执行

find ~ -name relay.mjs -path '*codex-delegate*'

并替换为其上一级目录。）

bash

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo

read-only (review/diagnosis, no edits): add --read-only

只读模式（审核/诊断，不编辑）：添加 --read-only

continue the exact Codex session: add --session <threadId> (from result.json; send only the delta brief)

继续当前Codex会话：添加 --session <threadId> （来自result.json；仅发送增量任务说明）

fallback when no thread id is available: add --resume-last

无线程ID时的回退方案：添加 --resume-last

hard time limit (watchdog): add --timeout 2h (default: off; implementation runs routinely need 1-2h)

硬超时限制（监控）：添加 --timeout 2h （默认：关闭；实现任务通常需要1-2小时）

so you can attach a watcher later: add --out-dir .codex-runs/<task-slug> (see step 3)

以便后续附加监控：添加 --out-dir .codex-runs/<task-slug> （见步骤3）

see all options: node .../relay.mjs --help

查看所有选项： node .../relay.mjs --help


The helper defaults to a write-capable (`workspace-write`) sandbox and writes its artifacts to a temp
dir, so the repo under review stays clean. It **never commits** — see step 5. Mechanics, flags, and the
`result.json` shape: [references/dispatch-and-poll.md](references/dispatch-and-poll.md).


辅助工具默认使用可写入的（`workspace-write`）沙箱，并将产物写入临时目录，因此待审核的仓库保持干净。它**绝不会提交代码**——见步骤5。机制、参数和`result.json`结构：[references/dispatch-and-poll.md](references/dispatch-and-poll.md)。

3. Watch it work, and wait for completion

3. 监控进度，等待完成

A delegated run is not a black box. The relay renders one readable line per Codex event to stderr as it happens — messages, each command with its exit code, every file edit — so progress shows up wherever your orchestrator surfaces command output. Nothing to enable;

--no-stream

turns it off.

[    6s] ▸ I'll update `math.js` in place, then run the exact verification command.
[    9s] $ sed -n '1,200p' math.js && git status --short -- math.js
[    9s]   ✓ exit 0 · return a + b; }
[   12s] ✎ update math.js
[   16s] $ node -e "import('./math.js').then(m=>console.log(m.multiply(3,4)))"
[   16s]   ✓ exit 0 · result 12
[   18s] turn complete in 60558 · out 378 · cached 50176

Progress goes to stderr and the run summary to stdout, so a script parsing stdout is unaffected. Add

--stream-reasoning

for the model's reasoning summaries (verbose).

When the run is backgrounded, its stderr is somewhere you are not looking. Attach to it instead —

scripts/watch.mjs

renders the same view from the run's

events.jsonl

, live, and exits when

result.json

lands:

bash

node "<skill-dir>/scripts/watch.mjs" --dir <out-dir> --root /path/to/repo

This needs a known

--out-dir

on the dispatch — the default is a random temp directory that nothing can find afterwards. Pass one whenever you intend to watch (

--latest

then finds the newest run under

--runs-root

, default

./.codex-runs

Put the watcher on a screen, not in your context. A human watches it in a second pane; an orchestrator should not pipe it into the conversation. Platform recipes are in references/dispatch-and-poll.md —

tmux

works everywhere including headless boxes over SSH.

Then wait, using whatever your orchestrator offers:

Claude Code: run the Bash call with
```
run_in_background: true
```
; you are notified on completion, and the relay's stream is captured in the task's output file to read on demand. Do not point a
```
Monitor
```
at the watcher: Monitor turns every stdout line into a conversation message, and a normal run emits a line per command, so it floods the session. Monitor is for signals you would act on — if you want one, filter to those:
```
node .../watch.mjs --dir <d> | grep --line-buffered -E '✗|error|turn failed'
```
.
Plain shell / other agents: run it in the foreground for short tasks (you will see the stream directly), or background it and poll the result file —
```
… &
```
in bash/zsh (including Git Bash/WSL), or your shell's equivalent (
```
Start-Job
```
in PowerShell,
```
start /b
```
in cmd). The run is done when
```
result.json
```
exists with a
```
status
```
. (A pre-run usage error — bad args or an empty brief — instead exits with code 2 and a stderr message and writes no result file, so check the exit code too. A missing
```
codex
```
binary exits 127 but does write a
```
result.json
```
with status
```
codex_unavailable
```
.)

Watching is for visibility, not verification: the stream shows what Codex did, and step 4 still decides whether it was right.

Do not trust progress trackers over reality: a run is finished when

result.json

is written and the process has exited. Read the working tree, not a status line. The implementer's full report is the

finalMessage

field in

result.json

(also printed in full on stdout between the report markers).

委托任务的运行并非黑箱。中继工具会在每个Codex事件发生时，向stderr输出一行可读内容——消息、每个命令及其退出码、每一次文件编辑——因此进度会显示在协调工具输出命令结果的位置。无需额外启用；

--no-stream

可关闭此功能。

[    6s] ▸ I'll update `math.js` in place, then run the exact verification command.
[    9s] $ sed -n '1,200p' math.js && git status --short -- math.js
[    9s]   ✓ exit 0 · return a + b; }
[   12s] ✎ update math.js
[   16s] $ node -e "import('./math.js').then(m=>console.log(m.multiply(3,4)))"
[   16s]   ✓ exit 0 · result 12
[   18s] turn complete in 60558 · out 378 · cached 50176

进度输出到stderr，运行摘要输出到stdout，因此解析stdout的脚本不受影响。添加

--stream-reasoning

可查看模型的推理摘要（详细模式）。

当任务在后台运行时，其stderr输出在你无法查看的位置。可附加监控工具——

scripts/watch.mjs

从运行的

events.jsonl

中实时渲染相同视图，并在

result.json

生成后退出：

bash

node "<skill-dir>/scripts/watch.mjs" --dir <out-dir> --root /path/to/repo

这需要在派发任务时指定已知的

--out-dir

——默认是随机临时目录，事后无法找到。只要你打算监控，就需指定该参数（

--latest

可在

--runs-root

下找到最新运行任务，默认

./.codex-runs

）。

**将监控工具放在独立窗口，而非你的对话上下文里。**人类可在第二个面板中监控；协调工具不应将其输出导入对话。平台方案见references/dispatch-and-poll.md——

tmux

适用于所有场景，包括通过SSH连接的无头服务器。

然后等待，使用协调工具提供的方式：

Claude Code： 使用
```
run_in_background: true
```
执行Bash调用；任务完成时你会收到通知，中继工具的流输出会捕获到任务的输出文件中，可按需查看。请勿将
```
Monitor
```
指向监控工具：Monitor会将每一行stdout转为对话消息，而正常运行会为每个命令输出一行，导致会话消息泛滥。Monitor仅用于你需要响应的信号——若需使用，可过滤：
```
node .../watch.mjs --dir <d> | grep --line-buffered -E '✗|error|turn failed'
```
。
纯shell / 其他Agent： 短任务可在前台运行（你会直接看到流输出），或后台运行并轮询结果文件——在bash/zsh中使用
```
… &
```
（包括Git Bash/WSL），或使用shell的等效命令（PowerShell中的
```
Start-Job
```
，cmd中的
```
start /b
```
）。当
```
result.json
```
存在且包含
```
status
```
字段时，任务完成。（运行前的使用错误——参数错误或任务说明为空——会以代码2退出并输出stderr消息，且不生成结果文件，因此需同时检查退出码。缺失
```
codex
```
二进制文件会以127退出，但会生成
```
result.json
```
，其中
```
status
```
为
```
codex_unavailable
```
。）

监控仅用于查看进度，而非验证：流输出显示Codex做了什么，步骤4仍需判断其是否正确。

不要依赖进度跟踪器，要以实际情况为准：当

result.json

生成且进程退出时，任务才完成。查看工作目录，而非状态行。实现工具的完整报告是

result.json

中的

finalMessage

字段（也会在stdout的报告标记之间完整打印）。

4. Review — do not trust the self-report

4. 审核——不要相信自我报告

Codex's

result.json

includes its own summary and gate claims. Re-verify, don't accept:

Re-run the project's gates yourself (the test/lint/build commands from step 1). Never take "gates passed" on faith.
Read the diff against the brief: did Codex do what was asked, nothing more (scope creep) and nothing less?
```
touchedFiles
```
in the result is your starting point.
Run the relevant guard skills on the diff if you have them installed (clean-code-guard, test-guard, etc. from
```
guard-skills
```
) — this skill produces the work; those skills judge it.
For schema/migration changes, round-trip them; for removals, grep for dangling references.

Full checklist: references/review-and-land.md.

Codex的

result.json

包含其自身的摘要和验证声明。重新验证，不要轻信：

自行重新运行项目的验证命令（步骤1中的测试/ lint/构建命令）。永远不要轻信“验证通过”的说法。
对照任务说明查看代码差异：Codex是否完成了要求的内容，不多做（范围蔓延）也不少做？结果中的
```
touchedFiles
```
是你的起始点。
若已安装相关守卫技能，对代码差异运行这些技能（
```
guard-skills
```
中的clean-code-guard、test-guard等）——此技能负责生成代码；那些技能负责判断代码质量。
对于架构/迁移变更，进行往返测试；对于删除操作，检查是否存在悬空引用。

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

5. Land it

5. 提交代码

Because Codex's sandbox cannot reliably write

.git

(it varies by version, OS, and path), the orchestrator commits. Only after the gates pass and the diff holds:

Commit the verified work yourself, with a clear message.
If it needs changes, send a delta brief with
```
--session <threadId>
```
from the prior
```
result.json
```
(use
```
--resume-last
```
only when no thread id is available), and review again.

由于Codex的沙箱无法可靠写入

.git

（因版本、操作系统和路径而异），由协调者完成提交。仅当验证通过且代码差异符合要求后：

自行提交已验证的代码，使用清晰的提交信息。
若需要修改，使用之前
```
result.json
```
中的
```
--session <threadId>
```
发送增量任务说明（仅当无线程ID时使用
```
--resume-last
```
），并再次审核。

Read-only second opinions

只读模式的第二意见

The relay doubles as a clean way to get an adversarial second opinion with no write risk: dispatch

--read-only

with a brief that lists the agreed points, then each contested point with both positions, and ask Codex to defend or concede each — deliverable in its final message, touching no files. Any delegation skill whose implementer offers a read-only mode supports the same use, but check how hard that mode's guarantee is first: Codex's sandbox enforces it, while Grok's is best-effort and only flagged after the fact (

readOnlyViolation

) — for those implementers, verify

touchedFiles

came back empty instead of assuming no edits.

中继工具还可作为一种安全方式获取反向第二意见，无写入风险：使用

--read-only

派发任务，任务说明中列出已达成一致的要点，然后列出每个有争议的要点及双方立场，要求Codex为每个要点辩护或让步——最终消息中会给出结果，且不会修改任何文件。任何实现工具支持只读模式的委托技能都可用于此场景，但需先确认该模式的保障力度：Codex的沙箱会强制执行只读，而Grok的沙箱仅为尽力而为，且仅在事后标记（

readOnlyViolation

）——对于这些实现工具，需验证

touchedFiles

为空，而非假设未进行编辑。

Authorization model

授权模型

Delegation is something the human opts into. Once they have ("run this queue", "proceed"), committing verified, gate-passing work is the agreed contract — that is the whole point. Two limits on that mandate: surface, don't absorb (report Codex's design decisions, defensible-but-unasked turns, and non-blocking nitpicks rather than silently keeping them) and stop for scope changes (if correct completion needs going beyond the brief, ask — don't expand the mandate yourself). The full treatment is in references/review-and-land.md.

委托是用户主动选择的操作。一旦用户确认（“运行此队列”、“继续”），提交已验证且通过验证的代码就是约定的内容——这正是核心目的。此授权有两个限制：透明化，不隐瞒（报告Codex的设计决策、合理但未要求的变更，以及非阻塞性的小问题，而非默默保留）和范围变更时停止（若正确完成任务需要超出任务说明的范围，需询问用户——不要自行扩大授权）。完整说明见references/review-and-land.md。

If you have the openai-codex plugin

若你已安装openai-codex插件

The official openai-codex Claude Code plugin is excellent and complementary —

codex-delegate

builds on the same

codex

CLI, it doesn't replace the plugin. They point in different directions:

The plugin's
```
codex:codex-rescue
```
agent is a forwarder: it hands one task to Codex and returns the output. It deliberately does not poll, review, or commit.
The plugin's review command and stop-review gate run the inverse direction: Codex reviews your work.
```
codex-delegate
```
is the orchestration loop in the other direction: you drive Codex to implement across one task or a queue, and you review and land each result. That loop — brief → dispatch → poll → review → commit, with the orchestrator owning the commit — is what the plugin leaves to you, and what this skill encodes.

If you have the plugin installed, its companion CLI is an optional alternative dispatch backend; the bundled

relay.mjs

is the default because it adds no install of its own beyond the

codex

binary (Node and

git

, which the relay also needs, are prerequisites for every skill here).

官方openai-codex Claude Code插件非常出色且互补——

codex-delegate

基于相同的

codex

CLI构建，并非替代插件。它们的定位不同：

插件的
```
codex:codex-rescue
```
agent是转发工具：将一个任务交给Codex并返回输出。它特意不进行轮询、审核或提交。
插件的review命令和stop-review验证工具运行方向相反：Codex审核你的代码。
```
codex-delegate
```
是反向编排循环：你驱动Codex完成单个任务或一系列任务的实现，你审核并提交每个结果。这个循环——任务说明→派发→轮询→审核→提交，由协调者负责提交——是插件留给你完成的部分，也是此技能所封装的内容。

若你已安装插件，其配套CLI是可选的替代派发后端；捆绑的

relay.mjs

是默认选项，因为除

codex

二进制文件外无需额外安装（中继工具还需要的Node和

git

是所有技能的前提条件）。

References

参考资料

references/writing-the-brief.md — how to write a brief Codex can execute blind: structure, XML blocks, the report contract, embedding the real gate commands.
references/dispatch-and-poll.md —
```
relay.mjs
```
flags, the
```
result.json
```
contract, the live progress stream and
```
watch.mjs
```
, backgrounding per orchestrator, and recovery when a run misbehaves.
references/review-and-land.md — the review checklist, the commit boundary, and the exact-session rework cycle.
references/multi-task-queues.md — running a sequential queue: carrying constraints forward, progress tracking, and the end-of-run coherence check.

references/writing-the-brief.md —— 如何撰写Codex可盲执行的任务说明：结构、XML块、报告约定、嵌入真实验证命令。
references/dispatch-and-poll.md ——
```
relay.mjs
```
参数、
```
result.json
```
约定、实时进度流和
```
watch.mjs
```
、各协调工具的后台运行方式，以及运行异常时的恢复方法。
references/review-and-land.md —— 审核检查清单、提交边界，以及精确会话的返工循环。
references/multi-task-queues.md —— 运行顺序队列：传递约束、进度跟踪，以及运行结束时的一致性检查。

codex-delegate

Original

Translation

Codex Delegate

Codex 委托工具

When NOT to use this

请勿使用此工具的场景

Prerequisites (check once)

前提条件（检查一次）

The loop

工作流程

1. Write the brief

1. 撰写任务说明

2. Dispatch

2. 派发任务

read-only (review/diagnosis, no edits): add --read-only

只读模式（审核/诊断，不编辑）： 添加 --read-only

continue the exact Codex session: add --session <threadId> (from result.json; send only the delta brief)

继续当前Codex会话： 添加 --session <threadId> （来自result.json；仅发送增量任务说明）

fallback when no thread id is available: add --resume-last

无线程ID时的回退方案： 添加 --resume-last

hard time limit (watchdog): add --timeout 2h (default: off; implementation runs routinely need 1-2h)

硬超时限制（监控）： 添加 --timeout 2h （默认：关闭；实现任务通常需要1-2小时）

so you can attach a watcher later: add --out-dir .codex-runs/<task-slug> (see step 3)

以便后续附加监控： 添加 --out-dir .codex-runs/<task-slug> （见步骤3）

see all options: node .../relay.mjs --help

查看所有选项： node .../relay.mjs --help

3. Watch it work, and wait for completion

3. 监控进度，等待完成

4. Review — do not trust the self-report

4. 审核——不要相信自我报告

5. Land it

5. 提交代码

Read-only second opinions

只读模式的第二意见

Authorization model

授权模型

If you have the openai-codex plugin

若你已安装openai-codex插件

References

参考资料

只读模式（审核/诊断，不编辑）：添加 --read-only

继续当前Codex会话：添加 --session <threadId> （来自result.json；仅发送增量任务说明）

无线程ID时的回退方案：添加 --resume-last

硬超时限制（监控）：添加 --timeout 2h （默认：关闭；实现任务通常需要1-2小时）

以便后续附加监控：添加 --out-dir .codex-runs/<task-slug> （见步骤3）