codex-goal-loop

name	codex-goal-loop
description	解释并编写 OpenAI Codex `/goal` 功能的有效指令——持久的自检代理循环（计划 → 执行 → 测试 → 复查 → 迭代）。当用户提到 Codex `/goal`、“goal loop”、“Ralph loop”，想启动一次长期运行的自主 Codex 任务，询问如何编写 goal 提示，或想草拟一段 goal 指令时使用。

Codex /goal 循环

什么是 /goal

/goal 是 Codex v0.128.0+（2026 年 4 月 30 日）中的一个斜杠命令，它会把一条 Codex 提示转化为一个持久代理，持续循环执行 计划 → 执行 → 测试 → 复查 → 迭代，直到满足停止条件、用户暂停，或 token 预算耗尽。内部称为 “Ralph loop”。

它与普通提示的关键区别：当一个回合结束但目标尚未达成时，Codex 会自动继续，而不是等待用户输入。

生命周期状态： pursuing、paused、achieved、unmet、budget-limited。

监控正在运行的 /goal 时，每次检查都应向 M4n5ter 提供一行更新：Codex 正在做什么，以及是否按计划推进。保持极其简洁。

它不是： 预算命令、安全边界、“永远运行”，也不是 /plan 的替代品。它是带验证循环的契约执行器。

要求

• Codex CLI/app/extension v0.128.0+
• 在 ~/.codex/config.toml 中设置 goals = true（或运行 codex features enable goals）
• ChatGPT 身份验证（Plus/Pro/Business/Edu/Enterprise）——API key 身份验证不可用。对于长时间运行，Pro 是现实中的最低配置。

什么时候使用它

仅当以下四项全部满足时使用：

1. 任务是超过 30 分钟的机械性工作。
2. 有一个可验证的停止条件（测试通过、覆盖率达到目标、评测 ≥ X、构建变绿）。
3. 仓库已适合代理执行（构建可用、测试较完善、存在 AGENTS.md）。
4. 产品契约、架构方向和范围边界已经确定；剩余工作主要是实现与验证。

适合：迁移、提升覆盖率、TDD 功能构建、带契约测试的重构、提示词/评测优化、部署重试循环、复现 bug 后修复。

不适合：探索性工作、架构与接口仍未确定的功能、模糊的“改进这个”、任何没有“完成”定义的任务、生产凭证、破坏性的共享基础设施操作。先用讨论或 grilling 关闭关键设计分支，再启动 goal。

7 字段契约（每个 goal 都需要）

1. 目标 —— 一句话，一个具体结果。
2. 首先阅读 —— 权威规格、约束和代码入口。
3. 约束 —— 什么绝不能改变，以及范围信封、预期触及的职责边界与明确非目标。
4. 验证命令 —— 能证明进展的确切 shell 命令（pytest -q、pnpm test 等）。
5. 文档判断 —— 只记录持久的公共契约、架构、运维或用户可见行为变化；没有这类变化时明确无需新增文档。
6. 检查点 —— 进度、范围与复杂度复核时机；临时进度日志放在仓库外或已忽略目录。
7. 停止条件 —— 可验证：“当 X 通过时停止”或“当进一步变更需要人工/产品输入、范围扩张或架构重置时停止”。

编写 goal（核心交付物）

当用户想要一条快速的 /goal 指令时，生成一个结构化 markdown 块，每个契约项一行（使用正确换行，不要写成连续散文）。不要在输出前加 /goal —— M4n5ter 会自己在输入框中添加斜杠命令。只输出契约正文。模板：

**Objective:** <一句话目标>
**Read first:** <文件/PLAN.md/issue>
**Constraints:** <不要改变什么、库、约定、明确非目标和预期触及的职责边界与模块>
**Validate:** 每次变更后运行 `<确切命令>`
**Document:** <只更新持久契约、架构、运维或用户可见行为所需的文档；否则明确无需新增文档>
**Checkpoints:** 按检查点推进，记录进度，并在实现规模或概念数量明显偏离预期时重新审视设计
**Stop when:** <可验证条件>，或当进一步变更需要人工/产品输入、范围扩张或架构重置时停止

示例（迁移）

**Objective:** 将此项目从 Pydantic v1 迁移到 v2。
**Read first:** pyproject.toml, src/, tests/
**Constraints:** 不改变公共 API；如有需要，通过 shim 保持导入向后兼容；不添加新依赖；范围限于 Pydantic model、validation 和相应测试，不削弱或跳过测试
**Validate:** 每次变更后运行 `pytest -q`
**Document:** 更新已有迁移文档中的持久兼容要求；不为实施进度创建文档，不创建 ADR
**Checkpoints:** 按检查点推进；简短记录进度
**Stop when:** 完整测试套件通过且无任何弃用警告，或当某项变更需要架构决策时停止

示例（提升覆盖率）

**Objective:** 将 src/auth/ 的覆盖率从约 38% 提高到 ≥75%。
**Read first:** src/auth/, tests/auth/, AGENTS.md
**Constraints:** 不添加新依赖；范围限于 src/auth/ 与 tests/auth/；除非严格出于可测试性需要，否则不要修改生产代码；不得排除文件、降低阈值或削弱测试
**Validate:** `pytest --cov=src/auth --cov-report=term-missing`
**Document:** 仅当测试入口或用户可见契约改变时更新现有文档；不要为覆盖率进度创建文档，不创建 ADR
**Checkpoints:** 按检查点推进；每个检查点记录覆盖率变化
**Stop when:** 覆盖率 ≥75% 且所有测试通过，或当未覆盖代码需要设计变更时停止

编写规则

• 一个目标，一个停止条件。 不要写成待办清单。
• 文档判断是强制要求，新增文档不是。 每条 /goal 提示都必须说明哪些持久契约需要记录，或明确本目标无需新增文档。不要把实现过程、检查点流水或临时结论写成仓库文档。
• 绝不要指示代理创建新的 ADR —— ADR 需要 M4n5ter 明确批准，因此 goal 提示不得预先批准或鼓励创建 ADR。
• 明确禁止 reward hacking： “不要为了让目标通过而删除、跳过、削弱或缩小测试范围。” 否则 Codex 可能会钻停止条件的空子。
• 目标长度限制为 4,000 个字符。如果更长，把细节放入文件（该文件通常应当位于git仓库之外，例如临时目录，或从 .gitignore 中挑选合适的目录），并让 goal 指向该文件——goal 本身保持紧凑。
• 对路径、命令、issue 编号使用字面字符串——必须精确。
• 明确禁止范围蔓延：“不要重构无关代码。不要添加依赖。”
• 告诉 Codex 何时暂停：“如果 <条件>，暂停并在继续前询问。”
• 简短、模糊的 goal 相比普通提示不会带来额外价值，只会消耗 token。

范围与复杂度闸门

goal 的停止条件不能只有“测试通过”。在契约或它引用的设计文件中建立一个范围信封：预期触及的职责边界与模块、明确非目标，以及实现规模的大致量级。量级是用于发现偏移的警戒线，不是按行数裁决设计的死亡线。

在第一个有意义的实现切片后，以及每轮深度 review 前，检查：

• 修改文件数、实现代码与测试代码的增减；
• 新触及的模块、公共接口、外部依赖和数据格式；
• 新增的概念、状态、控制流分支、协调机制和恢复行为；
• 每份新增复杂度与测试对应的受支持场景或明确系统不变量。

出现以下任一信号时，先冻结写入并重新表述问题，而不是继续补丁式推进：实际范围显著超过范围信封；意外跨入新的模块或接口；连续审查都在同一设计边界发现同类问题；每次修复都继续增加概念、分支和成组测试。实现代码或触及文件达到预期约两倍，是必须重新审视的常见警戒信号，但不是自动否决设计的硬阈值。先判断能否通过调整接口、类型或职责划分让非法状态不可表达；若会改变已确认契约或范围，再暂停并询问用户。

审查发现是需要验证的假设，不是自动进入实现的需求。只有当它能通过受支持路径到达、对应明确契约，或涉及安全与数据损坏边界时，才默认要求修复。对仅由违反明确契约的调用或无法到达的输入产生的问题，优先收紧边界、记录残余风险或拒绝扩展，而不是增加新的处理机制。

声明完成前做一次减法审计：从空白视角重读 diff，把每个状态、分支、恢复路径和测试映射回目标能力；删除没有真实场景、重复表达同一行为或只复述实现的内容。验证全绿是必要条件，不是最小且正确的充分条件。

元提示技巧（最高杠杆）

手写 goal 往往规格不足。让另一个 AI 会话（加载了代码库的 Claude、连接了项目的 ChatGPT，或同一目录下的另一个 Codex 线程）执行以下操作：

1. 检查代码库；
2. 找出隐藏假设、约束和边界情况，并区分受支持路径与纯推测性加固；
3. 使用 7 字段契约输出一个结构化的 /goal markdown 块。

然后把它粘贴进 Codex。运行质量会提升一个数量级。

Claude Code cmux 备注：Claude 完成后，可能会预填一条预测的下一条用户消息；那个草稿是 Claude 写的，不代表 M4n5ter 发言。

自我设定 goal

Codex 现在可以原生编写并设置自己的 goal（create_goal 工具）。你无需自己编写契约，而是给它你的高层意图，并让它设置 goal：“检查这个仓库，然后为自己编写一个带有可验证停止条件的 /goal 并执行。” 这相当于把元提示技巧内联完成——代理会把你的意图转化为契约。仍然要给它相同的原始材料（要阅读的文件、约束、验证命令），这样它写出的 goal 才有依据。补充一句：“如果意图规格不足，在提交前先提出澄清问题”——这能提前捕捉歧义，防止自设 goal 偏移。

启动

1. cd <repo>（goal 的运行范围限定在当前工作目录）。
2. 运行 codex（不带参数——打开 TUI）。不要运行 codex exec "/goal ..." —— /goal 只是 TUI 中的斜杠命令。
3. 使用 ChatGPT 登录（不是 API key）。
4. 在输入框中输入 /goal <你的契约>，然后回车。
5. 离开去做别的事。

控制正在运行的 goal

命令	效果
/goal（单独输入）	查看状态：当前检查点、已验证内容、剩余事项、阻塞项
/goal pause	冻结
/goal resume	解除冻结（v0.129+ 中必需；暂停的 goal 永远不会自动恢复）
/goal clear	终止 goal
/goal <new>	替换当前 goal
Ctrl+C / 任何输入的消息	自动暂停；用户输入始终拥有优先级

跨会话恢复：goal 状态会在服务端持久化。重新 cd 进入仓库，运行 codex，输入 /goal 查看状态，再输入 /goal resume。

预算受限状态：Codex 不会突然停止——它会总结、说明剩余事项，并保存状态。预算刷新或升级后，/goal resume 可继续使用。

当 goal 发生偏移时

• 轻微偏移： 直接在输入框中输入修正（会自动暂停、合并修正，然后恢复）。
• 目标过松： /goal pause，阅读状态，然后输入 /goal <更严格的版本>——这会替换契约。不要在模糊 goal 上不断堆叠指令。
• 严重混乱： /goal clear，执行 git status 或 git stash，用元提示技巧重写，然后重新开始。

不要让一个已经偏移的 goal 继续运行，只是“看看它会怎样”。这会消耗 token，并让 diff 不断叠加。

操作建议

• 定期用单独的 /goal 检查状态。
• 合并前始终审查 diff 与复杂度账单 —— 长时间自主运行意味着需要验证和删减的代码更多，而不是更少。人工监督会变得更关键，而不是可选。
• 保持审批和沙箱设置严格；默认权限是正确的。
• 第一次运行：选择一个约 30 分钟范围的任务，先了解 /goal 实际如何停止，再考虑让它隔夜运行。
• 把经常重复的策略写入 AGENTS.md，这样每个 goal 都能继承它们，而不必重复说明：声明完成前进行对抗性自检、即使测试通过也额外做一次 QA、标准验证命令。这样可以减少每次 goal 段落中的重复内容。

故障排查

症状	修复
斜杠弹窗中没有 /goal	codex update（需要 ≥0.128.0）
功能标志已开启但命令缺失	完全退出并重启 codex
输入了 /goals	它是单数：/goal
无法激活	退出登录，再使用 ChatGPT 订阅账号重新登录（不是 API key）
带进度总结停止	预算受限——刷新后运行 /goal resume，或收紧范围
/goal resume 提示没有活动 goal	已进入终态或已清除——用 /goal <new> 重新开始
goal 看起来处于活动状态但不会自动继续	卡在 Plan 模式——仅计划工作不会触发继续。先起草计划，然后切换到 Goal 执行

心智模型

/goal 是一个带验证循环的契约执行器，不是“永远运行”按钮。关键转变是：停止写提示，开始写带停止条件的规格说明。把时间花在前期定义“完成”上；后续运行会自行推进。