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设计并运行；其他协调Agent也适配，但尚未经过充分验证。）

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
```
路径，
```
codex --version
```
可查看其版本——过时的二进制版本不具备此技能依赖的参数（
```
codex exec --json
```
,
```
-o
```
,
```
exec resume
```
）。relay助手也会将运行的版本记录到
```
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会将其显示为“此技能的基础目录”；其他协调Agent也使用相同的目录——若不确定位置，可运行

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 previous Codex session: add --resume-last (send only the delta brief)

继续上一次Codex会话：添加 --resume-last （仅发送增量需求说明）

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. Wait for completion

3. 等待完成

The helper blocks until Codex finishes, so back it with whatever your orchestrator offers and resume when it returns:

Claude Code: run the Bash call with
```
run_in_background: true
```
; you are notified on completion.
Plain shell / other agents: run it in the foreground for short tasks, 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
```
.)

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.

助手会阻塞直到Codex完成任务，因此你可以使用协调Agent提供的后台运行功能，完成后再恢复操作：

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退出，但会生成
```
result.json
```
文件并标记
```
status
```
为
```
codex_unavailable
```
。）

不要依赖进度跟踪器，而要以实际状态为准：当

result.json

文件生成且进程退出时，任务才完成。查看工作目录的实际状态，而非状态行。

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
```
--resume-last
```
(don't restate the whole task) and review again.

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

.git

目录（因版本、操作系统和路径不同而异），由协调者负责提交代码。只有在验证通过且代码差异符合要求后：

自行提交已验证的工作，并附上清晰的提交信息。
若需要修改，使用
```
--resume-last
```
发送增量需求说明（无需重述整个任务），然后再次审核。

Non-negotiables

不可协商的规则

Re-run the gates yourself. The self-report is a claim, not evidence.
The orchestrator commits, never Codex. Don't assume Codex committed; it didn't.
One task = one brief = one commit. Split unrelated work into separate runs.
Trust the working tree and process state over any progress tracker.

自行重新运行验证命令。自我报告只是声明，而非证据。
由协调者提交代码，绝不由Codex提交。不要假设Codex已提交代码——它没有。
一个任务 = 一份需求说明 = 一次提交。将无关工作拆分为单独的运行任务。
信任工作目录和进程状态，而非任何进度跟踪器。

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。

Trust and safety

信任与安全

scripts/relay.mjs

itself makes no network calls, reads or writes no credentials, and sends no telemetry; it has no dependencies (Node built-ins only) and shells out only to

codex

and

git

. The

codex

process it launches does authenticate — exactly as you do at the terminal. Read the script before you run it. It is the one executable in this package; everything else is Markdown.

scripts/relay.mjs

本身不进行网络调用，不读取或写入凭据，也不发送遥测数据；它没有依赖项（仅使用Node内置模块），仅调用

codex

和

git

命令。它启动的

codex

进程会进行认证——与你在终端中的认证方式完全相同。运行前请阅读该脚本。它是此包中唯一的可执行文件；其余内容均为Markdown文档。

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, backgrounding per orchestrator, and recovery when a run misbehaves.
references/review-and-land.md — the review checklist, the commit boundary, and the rework cycle via
```
--resume-last
```
.
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
```
的格式、不同协调者的后台运行方式，以及运行异常时的恢复方法。
references/review-and-land.md —— 审核清单、提交边界，以及通过
```
--resume-last
```
进行返工的流程。
references/multi-task-queues.md —— 运行顺序任务队列：传递约束条件、进度跟踪，以及运行结束时的一致性检查。

What this skill does NOT do

此技能不具备的功能

It does not commit for you — that is deliberate (step 5).
It does not review the code's quality itself — pair it with guard skills.
It does not run your tests — you re-run the project's own gates in step 4.
It is not the inverse direction (Codex reviewing your work). For that, use the openai-codex plugin's review command or stop-review gate.

它不会替你提交代码——这是有意设计的（步骤5）。
它本身不会审核代码质量——需搭配守卫技能使用。
它不会运行你的测试——你需在步骤4中重新运行项目自身的验证命令。
它不支持反向操作（Codex审核你的工作）。若需要此功能，请使用openai-codex插件的review命令或stop-review验证环节。