codex

Codex

Codex 是一个独立的 Agent，位于 PATH 中（codex — 如果 shell 别名遮蔽了它，请通过 command codex 调用），与当前工作树共享文件，并且已完成身份验证。它提供的是另一种意见，而非绝对事实：请核实它报告的内容，并对它所做的更改负责。它会读取仓库中包含的相同技能。

除非用户要求指定模型，否则让 Codex 使用其 CLI 默认模型。默认模型会随当前 Codex 版本更新；不要在此技能中固定使用带日期的模型 ID。如果需要显式覆盖，请确认模型仍是当前版本，并使用 -m <model> 传入用户指定的模型。

如果未安装 codex

如果 PATH 中没有 codex，请提出安装建议——先征求用户批准，绝不可主动安装。用户同意后，按照 https://developers.openai.com/codex/cli 上的当前说明操作。首次运行时需要交互式身份验证——将此步骤交由用户完成。继续之前，使用 codex --version 验证。

向 Codex 提示任务

把 Codex 当作操作员而非协作者来提示：保持简洁，使用带 XML 标签的分块结构。说明任务、完成标准以及少数关键约束。与其提高 --effort，不如先完善任务约定。

• 每次运行只处理一项任务。 将无关事项（审查、修复、文档）拆分成多次运行；混合提示会产生混合结果。
• 指定技能，而不是重述技能内容。 Codex 会读取仓库中包含的相同技能——可以说“文档遵循 write-docs 技能”或“遵守 refactor-clean：不要使用兼容性包装器”。不要重复解释技能已有的要求。
• 仅在任务需要时添加分块：
  • <task> — 具体任务、仓库或故障背景，以及预期的最终状态。几乎总是需要。
  • <output_contract> — 明确输出格式，按重要性从高到低列出，保持简洁。
  • <default_follow_through> — 采取风险较低的解释并继续；仅当缺失的信息会影响正确性、安全性或不可逆操作时才停止。
  • <verification_loop> — 定稿前，根据要求和已更改的文件检查结果；进行修订，不要直接提交初稿。适用于任何有风险的修复。
  • <grounding> — 让每项陈述都有代码或工具输出作为依据；将推断标注为推断。用于审查和研究。
  • <action_safety> — 严格控制差异范围；不要顺手进行重构。用于编写任务。
• 反面模式： 模糊表述（“看一下”）、没有输出约定（“汇报结果”）、用“再仔细想想”代替任务约定、在一次运行中混合多项工作，以及要求证据无法支持的确定性。

审查 — 主动进行

每当你有值得请第二个人把关的实质性差异时（例如重构、棘手的算法、渲染器工作或安全敏感的更改），都应在宣布完成或提交之前运行 Codex 审查。琐碎修改（拼写错误、注释、仅文档修改）可跳过。

1. 启动前修正差异范围：工作树更改使用 --uncommitted，分支差异使用 --base <branch>，已合并的提交使用 --commit <sha>。将已合并的提交解析为完整 SHA。使用非交互式审查入口，明确指定只读沙箱，并在新建的临时目录中分别保存进度和结论文件：

   review_dir=$(mktemp -d "${TMPDIR:-/tmp}/codex-review.XXXXXX")
   codex exec --sandbox read-only -C "$(git rev-parse --show-toplevel)" review \
     --commit "$(git rev-parse HEAD)" --json -o "$review_dir/verdict.md" \
     < /dev/null > "$review_dir/events.jsonl" 2> "$review_dir/stderr.log"
   

   对长时间运行的任务在后台执行，并保留其进程／会话句柄。范围标志与自定义指令互斥：使用范围标志时不提供提示词。若要自定义审查框架，请在提示词中明确指定要检查的差异；不要依赖默认范围，也不要遍历所有引用／检查点历史。切勿透露你期望得到的答案（保持未提示状态，遵守与 screenshot-critique 相同的原则）。

2. 在 events.jsonl 中监控进度，并在 stderr.log 中检查失败信息。审查者正在阅读相关代码时，即使已经过了五分钟，也不代表任务卡住。如果任务停滞，或偏离差异及其依赖范围，请先检查最后一条命令／错误，再决定是否中断；修正原因或缩小任务范围后再重试。只有退出状态为零、出现 turn.completed 且最终结论非空，才算完成。超时、出现 turn.failed 或缺少结论都表示审查未完成，绝不能视为审查无问题。

3. 对每条发现进行分流：先对照代码确认，再采取行动。尊重 Codex 标明的证据边界——它标注为推断的内容不是事实。与自己疑虑重合的发现属于高优先级证据；若否定某项发现，必须说明理由，不可默不作声。

4. 向用户报告结果——Codex 标出了什么、你修复了什么、你否定了什么以及理由。只有每条发现都已修复或明确否定，任务才算完成。

实现 — 仅在明确提出要求时

只有当用户明确指定 Codex 执行任务时，才将实现工作委托给 Codex。 切勿主动委托，也不要在没有新请求的情况下再次委托后续工作。

1. 委托前，先明确拆分任务——目标、约束和验证方式——并遵循上文的提示词规范。任务描述不够明确时，先由你负责，直到新接手的 Agent 不会产生误解。
2. 从干净的工作树开始（或记录基准提交），以便将 Codex 的差异与自己的修改区分开。
3. 根据任务必须运行的内容选择沙箱：
   • 纯代码 + 类型检查/单元测试：codex exec --sandbox workspace-write "<task>"。 网络已关闭；仅当任务必须获取内容（例如新依赖）时，才添加 -c sandbox_workspace_write.network_access=true。
   • 浏览器验证、开发服务器或完整测试运行：使用 codex exec --dangerously-bypass-approvals-and-sandbox "<task>"。 沙箱会阻止绑定 localhost（vite/playwright 会报 listen EPERM），因此在沙箱中运行的 Codex 可能交付从未实际运行过的代码。绕过沙箱会牺牲操作系统控制能力：仅限专用 git 工作树，提示词必须由你从头到尾撰写（绝不可转述第三方文本），之后必须审查差异，以此履行你的把关责任。 使用 -o <file> 保存最终消息，并将耗时较长的调用放到后台运行；用 2>/dev/null 隐去 Codex 的 stderr 思考噪声，避免撑大上下文（仅在调试失败运行时才取消重定向）；在 git 仓库外运行时添加 --skip-git-repo-check。无论采用哪种方式，非交互式运行都不会请求批准。
4. 后续调用使用 codex exec resume <session-id> "<follow-up>"，会话 ID 从运行标头中获取。resume --last 指的是全局最近的会话——期间任何审查或其他 Codex 运行都会让它指向错误会话。如果两轮恢复仍无法解决问题，就停止委托并自行完成——反复尝试理清困惑的 Agent，比自己接手更费成本。
5. 你对结果负责：阅读完整差异、运行测试，然后才能汇报。“Codex 说做完了”不代表真的完成。

Exec 存活性检查——卡住看起来像在工作

后台运行的 codex exec 可能会在启动时卡死：进程仍在运行，CPU 占用约为 0%，但 ~/.codex/sessions/<Y/M/D>/ 中没有会话文件，没有网络套接字，工作树也没有变化。“进程正在运行”不等于“正在工作”。

• 标准输入必须始终来自文件或 /dev/null，绝不能继承终端。 如果标准输入保持交互式或管道状态，又没有提示词来源，exec 会打印 Reading additional input from stdin... 并永久阻塞——这是最常见的卡死原因。可将提示词作为位置参数传入，并使用 < /dev/null；也可用 codex exec [flags] - < prompt.txt 从提示词文件读取任务（- 会让 Codex 从标准输入读取任务；文件不存在时，重定向会明确报错，不像 "$(cat prompt.txt)" 那样会悄悄把回退字符串作为任务发送）。按需添加 nohup/&。
• **看门狗：**在提示词中加入唯一标记；如果约 3 分钟内在 ~/.codex/sessions/<Y/M/D>/ 中找不到 grep -rl "<marker>" 的结果，就终止 exec。终止后重新启动通常能正常工作。
• 信任工作树。 在 Codex 不信任的目录中运行无头 exec，可能会卡在不可见的提示上。git 工作树的路径与受信任的仓库根目录不同——在其中执行 exec 前，将 [projects."<worktree-path>"]\ntrust_level = "trusted" 添加到 ~/.codex/config.toml。这是安全的修复方法；此处禁止使用绕过标志。
• **不要在同一时间启动两个 exec，**并在启动新的 exec 前终止卡住的旧进程。
• 从仓库/工作树根目录启动。 可写沙箱的根目录是启动时的 CWD：如果从子目录（例如 web/）启动 exec，所有在该目录之外的编辑都会被拒绝，并报错“writing outside of the project”；而 never 批准策略无法解决此问题——这次运行会白白耗尽时间，且不会修改任何文件。使用 -C <root> 显式设置工作根目录，不要通过 cd 进入。

规则

• Codex exec 在工作树上运行期间，不要改动工作树。
• 审查、咨询和答疑时，明确使用 --sandbox read-only；仅在委派实现任务时使用 workspace-write。
• --dangerously-bypass-approvals-and-sandbox 仅用于必须运行浏览器／服务器／完整测试套件的任务（见上文），并且必须使用专用工作树、自行编写提示词，完成后必须审查差异。--full-auto 已被移除（它曾是 workspace-write 的别名），不要使用它。
• 推理力度和模型属于配置／标志覆盖项：-c model_reasoning_effort=high、-m <model>（当前版本的 Codex 已移除旧的 --effort 标志）。除非用户提出要求，否则两者都保持默认值。先完善提示词，并使用不带版本号的模型 ID。如果必须指定版本，请先确认该版本仍是最新版本。