codex-agents 把 Codex CLI 定位为与 Claude 平级的“同伴”，而不是格式化工具、关卡或权威。它运行在 Codex CLI 提供的最新模型上，每轮都采用最高推理强度（xhigh，也是封装器的默认值）。
用途与定位
- 早期介入：在构思和框架阶段就引入 Codex，而不是只当作发布前检查。最省成本的收益出现在开头，比如选择角度、命名承重论点、决定砍掉什么。
- 压力测试：对关键主张、结构或钩子先做压力测试，再进行投入。
- 协商分歧：当卡在两种合理框架之间，或准备让人在两个选项中选择时，先让两个智能体互相辩论。
- 构建委派：可以把一个构建阶段交给 Codex，包括目标、约束性决策和将要触碰的文件，然后阅读返回的 diff。但委派回来的 diff 属于未评审代码。
主要能力
- 编写代码，并能直接生成图像（多模态输出），不必假设交付物一定是 HTML 或代码。
- 以对话式、同伴式的方式连续迭代，默认自动续接上一次会话。
- 提供会话标记，记录活动会话的目录、模型和 id，默认行为是“继续”，直到执行 --reset 或 --new。
- 支持长开场简报：把简报写入临时文件，再用 --read 读取。
- 通过参数控制模型、推理强度、沙箱级别和工作目录。
使用方式
脚本位于技能自身的 <skill dir>/scripts/codex.py，建议使用绝对路径，并通过 --cwd 限定仓库。常用命令：
- codex.py "<msg>"：发送消息，存在会话则自动续接，否则新建。
- codex.py --new "<msg>"：强制新会话。
- codex.py --session ID "<msg>"：续接指定 id 的会话。
- codex.py --read FILE：从文件读取消息正文（- 表示 stdin）。
- codex.py --status：显示是否有活动会话以及距上次调用的时间。
- codex.py --reset：清除会话标记。
主要标志：--new、--session ID、--read FILE、--model MODEL（默认取 codex 配置的模型）、--effort LEVEL（low、medium、high、xhigh，默认每轮 xhigh）、--sandbox MODE（read-only、workspace-write、danger-full-access，仅对新会话生效）、--cwd DIR、--raw。
开场时给 Codex 四样东西：TARGET（产出或决定什么）、RESEARCH（已知事实）、DRAFT（当前版本及备选，直接贴出成品本身）、REASONING（卡在哪里、已否决什么及原因）。后续轮次保持对话式、简短、同伴对同伴，不要重新包装成结构化提示词。
会话管理
- 同一阶段内续接；新阶段或新领域用 --new 重新开始。项目已知信息应写进文档和阶段简报，而不是依赖旧线程。
- 并行构建需要各自的工作树、会话和标记，通过 CODEX_AGENTS_STATE 为每个构建指定独立标记文件。
- 可用 --session <id> 续接更早的会话；会话存放在 ~/.codex/sessions/<yyyy>/<mm>/<dd>/。续接不会保留原会话的模型，需用 --model 指定。
- 会话按工作目录隔离；标记只保存一个目录，目录不匹配时会新建线程。
适用场景
需要与另一个模型对等讨论、对重要交付物引入不同盲点、在提交前检验关键论点，以及把边界清晰的构建阶段委派出去并另行评审时。
限制与注意事项
- 涉及真实系统的操作（任何数据库、服务器、设置）、判断阶段是否完成、接受或拒绝评审结论，仍由会话智能体负责。
- 即使使用 workspace-write，构建也无法提交，且不能在另一个检出中运行 git：沙箱保持 .git 只读，git add 会因创建 .git/index.lock 失败；在 Windows 上沙箱以另一本地用户运行命令，git 会以“dubious ownership”拒绝其他仓库（资料记录为 Codex CLI 0.159、Windows 11、2026-10-25 复现，其他平台未测试）。因此简报应要求工作保持未提交并附提交信息，由会话智能体阅读 diff 后提交。
- 默认沙箱为只读，且该标志只对新会话生效。如果预期的续接没有发生，会话会静默落入只读，返回一份有论证但没有任何改动的报告；判断依据是磁盘：检查 git status 和文件修改时间。
- 用法限额会使构建者不可用，表现与 CLI 缺失相同。临近重置时可等待，否则由会话智能体自行构建阶段，独立评审仍然适用。
- 独立评审不由此技能完成；撰写代码的会话从不清除自己的代码，需要独立评审（例如 grok-agents 技能或项目自选方式）。
- 不适合例行起草、格式化或会话内能自信处理的机械任务。
- 委派的标准是规模而非时间：若简报长度接近 diff，直接写 diff；小改动若一轮没有写入（查 git status），应停止并转为会话内编写。
- 开场简报中不要写编号式具体请求和子条目，也不要规定路径、文件名、字体、尺寸、库或框架，除非是硬性约束。
- 不要停在第一轮就把草稿当成品；正常迭代约 3 到 8 轮，先收敛再向人呈现单一结果。