codex-subagent

将 Codex CLI 用作子 Agent

Codex CLI 是 OpenAI 的终端编码 Agent。codex exec 会以非交互方式运行： 它会在沙箱中自主工作，将进度流式输出到 stderr，并仅将最终消息输出到 stdout。身份验证沿用用户的 ChatGPT 订阅，绝不使用 API 密钥。

适合委派的任务

• 成功标准明确且自成一体的编码任务（修复、功能开发、重构、审查）。
• 并行工作：同时处理多项互不相关的任务（参见“并行运行”）。
• 征求第二意见／独立验证你自己的更改。

不要委派需要对话上下文、且无法完整写入提示词的任务。

启动前检查

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

未登录 → 停止并告知用户运行 codex login（一次性浏览器 OAuth）。 绝不要读取、打印或复制凭据（~/.codex/auth.json）。

启动

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

• 始终使用 GPT 5.6 Sol（gpt-5.6-sol）。默认推理力度设为 high。 每次启动新的 Codex 运行时，都要明确传入这两个标志。
• 不要使用 Codex 快速模式。
• 当 stdin 不是实际终端时（后台 shell、脚本），必须使用 </dev/null：Codex 会将未关闭的 stdin 视为额外上下文，并一直等待 EOF。
• Codex 无法看到你的任何对话内容。请在提示词中提供所有上下文： 目标、相关路径、约束，以及验证任务完成的方法。
• 提示词较长？改为通过 stdin 管道传入：codex exec [flags] - < /tmp/task.md。
• 如果宿主 Agent 提供了后台/Bash 子 Agent，请将命令封装其中运行（Cursor：使用带 shell 子 Agent 的 Task 工具），避免 Codex 的冗长输出进入父上下文。否则可使用普通后台终端。
• 运行需要几分钟，且没有内置超时机制——请在后台运行并监控。
• 可选：使用 --json 获取 JSONL 事件流。

收集结果

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

在同一会话中继续操作（从相同的 cwd 运行——恢复会按 cwd 筛选）：

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

并行运行

仅并行处理真正互不相关的任务，并预先分配文件的所有权，确保结果能够顺利合并。每次 Codex 运行使用一个 git worktree，同一工作树中绝不能同时运行两个任务：

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

故障模式

• 永久挂起且没有输出 → stdin 未关闭。终止运行，并使用 </dev/null 重新启动。
• codex login status 返回非零 → 用户必须运行 codex login。不要绕过此要求。
• 达到 ChatGPT 套餐速率限制 → 告知用户；绝不要循环重试。
• 出现 “Not a git repo” 错误 → 添加 --skip-git-repo-check，或先初始化仓库。
• 默认情况下，工作区写入沙箱内的网络访问受阻。如果任务需要网络（安装、API 调用），请使用：-c sandbox_workspace_write.network_access=true。
• 绝不要使用 --dangerously-bypass-approvals-and-sandbox。

规则

• 每次启动只处理一项任务。将大型任务拆分为多次启动。
• 宣布任务完成前，亲自审查 Codex 的差异。

Cursor 原生封装（可选）

要在 Cursor 中启用自动路由和 /codex 调用，请添加 ~/.cursor/agents/codex.md — 一个自定义子 Agent，其描述为“将编码任务委派给 Codex CLI”，并在正文中指向此技能。