Codex Cloud 异步任务

Codex Cloud 的核心价值是“委派”。你不用在本机守着它跑命令，而是把一个远程仓库任务交给云端环境，让 Codex 自己克隆仓库、执行任务、生成结果，再由你回收。

官方开发者文档把 Codex Cloud 定位为云端委派入口。本站更关心实战问题：什么任务适合交给 Cloud，任务说明怎么写，结果怎么验收。

Cloud 和 CLI 的差别

维度	CLI	Cloud
工作位置	本机项目目录	云端仓库环境
交互方式	你可以随时打断和补充	更偏异步委派
上下文来源	本地文件、命令、当前工作区	远程仓库、环境配置、任务描述
适合任务	快速修复、调试、验证	issue、PR、文档、测试、CI
风险点	本机权限和工作区污染	环境缺失、任务描述不够具体

Cloud 不是“更强的 CLI”，而是另一个工作场景。

适合交给 Cloud 的任务

• 明确的 GitHub issue。
• 文档链接检查和修复。
• 补一组边界测试。
• 修一个可复现的 CI 失败。
• 做一次代码审查。
• 按规则更新 README、Changelog、迁移说明。
• 独立模块的小型重构。

不适合：

• 需要本机私有文件。
• 依赖你本机特殊环境。
• 需要频繁产品判断。
• 需要登录态网页或本机 GUI。
• 涉及生产数据、支付、权限、删除。

Cloud 任务要写得更详细

Cloud 里你不能像 CLI 一样随时纠偏，所以任务说明要比本地更完整。

目标：
【一句话说明要完成什么】

背景：
【相关 issue、报错、用户反馈、现有行为】

范围：
【允许修改哪些目录或模块】

限制：
【不要改什么，不要引入什么依赖，不要改变什么接口】

验证：
【希望运行哪些测试、构建、lint 或人工检查】

交付：
【希望输出 PR、diff、说明还是问题清单】

停止条件：
【遇到环境缺失、信息不足、范围变大时应该停下说明】

环境配置要前置

Cloud 环境不是你的电脑。你本机有的东西，云端不一定有。

任务开始前要确认：

• 依赖安装命令。
• 构建命令。
• 测试命令。
• 需要的环境变量。
• 是否需要网络访问。
• 是否有 setup 脚本。
• 仓库里是否有 AGENTS.md。

建议把这些写进 AGENTS.md：

## Cloud 环境
- 安装依赖：
- 构建：
- 测试：
- 需要的环境变量：
- 如果缺少外部服务，请跳过集成测试并说明原因。

网络和 Secrets

Cloud 任务如果需要访问外部网络或密钥，要更谨慎。

原则：

• 默认不把秘密信息写进 Prompt。
• 能用测试替身就不要连真实服务。
• 需要网络时说明访问目的。
• 需要 secret 时说明变量名和使用场景，不输出值。
• 任务完成后检查是否误写日志或文档。

回收 Cloud 结果

Cloud 任务完成后，不要直接合并。先做四步：

1. 看任务总结是否和原目标一致。
2. 看 diff 是否超出范围。
3. 在本地拉取或应用结果后重新跑关键验证。
4. 用 交付审查 检查风险。

回收提示：

请审查这个 Cloud 任务结果：
1. 是否完成原始目标；
2. 是否超出修改范围；
3. 是否引入新依赖或配置；
4. 本地需要重新运行哪些验证；
5. 是否建议合并，还是需要返工。

常见失败

现象	常见原因	处理
任务一直 pending	队列、权限或环境问题	检查仓库连接和任务状态
安装依赖失败	setup 不完整	把安装步骤写进 AGENTS.md
测试跑不起来	云端缺少本机服务	区分环境失败和代码失败
改错方向	任务描述太短	补背景、文件路径、验收标准
PR 过大	范围没有限制	要求拆分或重新提交更小 diff

Cloud 任务模板

请在云端处理这个仓库任务。

目标：
修复 docs/codex 下的内部链接问题。

范围：
只允许修改 docs/codex 和 docs/.vitepress/config.ts。

限制：
不要改 ChatGPT、Claude、Vibe Coding 模块。
不要重构导航结构。

验证：
运行 npm run build。
如果构建失败，请说明失败原因，不要继续扩大修改范围。

交付：
输出修改文件、修复的链接类型、验证结果和剩余风险。

最重要的习惯

Cloud 的任务描述要比 CLI 多写 2 到 3 倍。你少写的上下文，最后都会变成回收阶段的返工。

参考：OpenAI Codex Cloud 文档。