codex-subagent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Codex CLI as a Subagent

Codex CLI 作为子Agent

Codex CLI is OpenAI's terminal coding agent.

codex exec

runs it non-interactively: it works autonomously in a sandbox, streams progress to stderr, and prints only the final message to stdout. Auth reuses the user's ChatGPT subscription — never an API key.

Codex CLI 是OpenAI推出的终端编码Agent。

codex exec

命令以非交互模式运行它：它在沙箱中自主工作，将进度流输出到stderr，仅将最终消息打印到stdout。授权复用用户的ChatGPT订阅——无需使用API密钥。

When to delegate

何时委派任务

Self-contained coding task with clear success criteria (fix, feature, refactor, review).
Parallel work: several independent tasks at once (see Parallel runs).
Second opinion / independent verification of your own changes.

Do NOT delegate tasks that need conversation context you can't fully write into the prompt.

具备明确成功标准的独立编码任务（修复、功能开发、重构、代码审查）。
并行工作：同时处理多个独立任务（参见并行运行章节）。
对自身修改获取二次意见/进行独立验证。

请勿委派那些无法将对话上下文完整写入提示词的任务。

Preflight

预检查

bash

codex --version       # missing? npm i -g @openai/codex  (or: brew install --cask codex)
codex login status    # exit 0 + "Logged in using ChatGPT" = ready

Not logged in → stop and tell the user to run

codex login

(one-time browser OAuth). Never read, print, or copy credentials (

~/.codex/auth.json

bash

codex --version       # 未安装？执行 npm i -g @openai/codex （或：brew install --cask codex）
codex login status    # 退出码为0且显示“Logged in using ChatGPT”即为就绪

未登录 → 停止操作并告知用户运行

codex login

（一次性浏览器OAuth授权）。切勿读取、打印或复制凭据文件（

~/.codex/auth.json

）。

Launch

启动命令

bash

OUT=$(mktemp /tmp/codex-out.XXXXXX)
codex exec \
  --cd /path/to/repo \
  --model gpt-5.6-sol \
  --config model_reasoning_effort=high \
  --sandbox workspace-write \
  --output-last-message "$OUT" \
  "Full task prompt: goal, constraints, files to touch, definition of done." \
  </dev/null

Always use GPT 5.6 Sol (
```
gpt-5.6-sol
```
). Default reasoning effort to
```
high
```
. Pass both flags explicitly on every new Codex run.
Do NOT use Codex fast mode.
```
</dev/null
```
is MANDATORY when stdin is not a real terminal (background shells, scripts): codex treats open stdin as extra context and waits forever for EOF.
Codex sees NOTHING of your conversation. Put all context in the prompt: goal, relevant paths, constraints, and how to verify it's done.
Long prompt? Pipe it via stdin instead:
```
codex exec [flags] - < /tmp/task.md
```
.
Wrap the command in a background/Bash subagent if your host agent has one (Cursor: Task tool with a shell subagent) so Codex's verbose stream stays out of the parent context. Fallback: a plain background terminal.
Runs take minutes and have no built-in timeout — background it and monitor.
Optional:
```
--json
```
for JSONL event stream.

bash

OUT=$(mktemp /tmp/codex-out.XXXXXX)
codex exec \
  --cd /path/to/repo \
  --model gpt-5.6-sol \
  --config model_reasoning_effort=high \
  --sandbox workspace-write \
  --output-last-message "$OUT" \
  "完整任务提示词：目标、约束条件、需修改的文件、完成定义。" \
  </dev/null

始终使用GPT 5.6 Sol（
```
gpt-5.6-sol
```
）。默认推理强度设为
```
high
```
。每次启动新的Codex运行时都要显式传递这两个参数。
请勿使用Codex快速模式。
当标准输入不是真实终端（后台shell、脚本）时，
```
</dev/null
```
是必填项：Codex会将打开的标准输入视为额外上下文，并无限等待EOF。
Codex无法获取你的对话内容。请将所有上下文写入提示词：目标、相关路径、约束条件以及验证完成的方式。
提示词过长？改为通过标准输入管道传递：
```
codex exec [参数] - < /tmp/task.md
```
。
如果宿主Agent支持（如Cursor：带shell子Agent的Task工具），请将命令包装在后台/Bash子Agent中，这样Codex的详细输出流就不会干扰父上下文。备选方案：使用普通后台终端。
任务运行需要数分钟，且无内置超时机制——请将其置于后台并监控进度。
可选：添加
```
--json
```
参数以获取JSONL事件流。

Collect results

收集结果

bash

cat "$OUT"                            # final message = the deliverable
git -C /path/to/repo status --short   # see what Codex actually changed

Follow-up in the same session (run from the same cwd — resume filters by cwd):

bash

codex exec resume --last "follow-up instruction" </dev/null

bash

cat "$OUT"                            # 最终消息即为交付成果
git -C /path/to/repo status --short   # 查看Codex实际修改的内容

在同一会话中进行后续操作（从同一工作目录运行——恢复操作会按工作目录过滤）：

bash

codex exec resume --last "后续指令" </dev/null

Parallel runs

并行运行

Parallelize only genuinely independent tasks, and assign file ownership upfront so results merge cleanly. One git worktree per Codex run — never two in the same tree:

bash

git worktree add /tmp/wt-taskA -b codex/task-a
codex exec --cd /tmp/wt-taskA --model gpt-5.6-sol \
  --config model_reasoning_effort=high --sandbox workspace-write \
  -o /tmp/outA.md "task A" </dev/null

仅对真正独立的任务进行并行处理，并预先分配文件归属权，以便结果能够顺利合并。每个Codex运行使用一个git工作区——切勿在同一工作区运行两个任务：

bash

git worktree add /tmp/wt-taskA -b codex/task-a
codex exec --cd /tmp/wt-taskA --model gpt-5.6-sol \
  --config model_reasoning_effort=high --sandbox workspace-write \
  -o /tmp/outA.md "任务A" </dev/null

Failure modes

故障模式

Hangs forever with no output → stdin was left open. Kill it, relaunch with
```
</dev/null
```
.
```
codex login status
```
non-zero → the user must run
```
codex login
```
. Don't work around it.
ChatGPT plan rate limit hit → report to the user; never retry in a loop.
"Not a git repo" error → add
```
--skip-git-repo-check
```
, or init a repo first.
Network is blocked inside the workspace-write sandbox by default. If the task needs it (installs, API calls):
```
-c sandbox_workspace_write.network_access=true
```
.

NEVER use

--dangerously-bypass-approvals-and-sandbox

无限挂起且无输出 → 标准输入未关闭。终止进程，添加
```
</dev/null
```
后重新启动。
```
codex login status
```
返回非零值 → 用户必须运行
```
codex login
```
。请勿尝试绕过此步骤。
触发ChatGPT计划速率限制 → 告知用户；切勿循环重试。
出现“Not a git repo”错误 → 添加
```
--skip-git-repo-check
```
参数，或先初始化仓库。
默认情况下，workspace-write沙箱内的网络是被阻止的。如果任务需要网络（安装依赖、API调用）：添加
```
-c sandbox_workspace_write.network_access=true
```
参数。

切勿使用

--dangerously-bypass-approvals-and-sandbox

参数。

Rules

规则

One task per launch. Split big jobs into multiple launches.
Review Codex's diff yourself before declaring the task done.

每次启动处理一个任务。将大型任务拆分为多次启动。
在宣布任务完成前，请自行检查Codex的差异内容。

Cursor-native wrapper (optional)

Cursor原生包装器（可选）

For auto-routing and

/codex

invocation inside Cursor, add

~/.cursor/agents/codex.md

— a custom subagent whose description is "delegates coding tasks to Codex CLI" and whose body points at this skill.

如需在Cursor内实现自动路由和

/codex

调用，请添加

~/.cursor/agents/codex.md

—— 这是一个自定义子Agent，其描述为“将编码任务委派给Codex CLI”，内容指向本技能文档。