Codex Cloud 实战：把一个需求交给云端 Agent 后怎么验收

一个 GitHub issue 写着：“CI 里的 webhook 测试失败，但我现在不方便在本机跑完整环境。”你想让 Codex Cloud 在云端仓库里修复，最后只把 diff、测试记录和 PR 交给你验收。

这个场景的关键不是“云端更自动”，而是 Cloud task 有一个干净、可复现、离开本机也能跑的仓库环境。它不会读到你电脑上的未提交文件、浏览器登录态或本地 .env；这既是边界，也是好处。

下面按一次真实任务的顺序走：先判断是否该放 Cloud，再配 environment，写 prompt，看结果，最后决定是开 PR、接回本地，还是用 @codex review 做第二道检查。

先判断：这个需求该放 Cloud，还是留在本地

Local、Worktree、Cloud 和 SSH host 的边界

Codex 的几个入口解决的是不同问题，不是简单的强弱关系。

场景	适合入口	原因	主要验收物
本地小修、依赖未提交文件或 localhost	CLI / IDE / Local	能直接访问本机工作区、浏览器和本地服务	本地 diff、测试输出
两三个独立方案并行	Codex app Worktree	隔离 Git 状态和依赖目录	worktree diff、review queue
GitHub issue、CI failure、文档更新、可复现仓库任务	Codex Cloud	远程 checkout，离开本机也能跑	Cloud summary、diff、PR
PR 第二道审查	GitHub @codex review	基于 PR diff 发布标准 review	GitHub review comments
项目在 devbox 或内网机器	Remote connection / SSH host	使用远程 host 的文件、shell、凭据和工具	remote diff、terminal output

Cloud 不是“更强的 Worktree”。Worktree 仍在本机运行，只是把 Git 目录隔开；Cloud 是 configured cloud environment，会从 GitHub checkout 仓库，在远程容器里执行任务。

适合 Cloud 的任务通常有四个特征：目标明确、仓库状态可复现、环境能脚本化、Done when 可以用命令或 diff 验收。比如修一个 CI failure、补一段文档、跟进 PR review、给一个局部模块加测试。

不该交给 Cloud 的任务

有些任务看起来能交给 AI，但不适合离开本机。

• 依赖本地未提交文件：Cloud 只会看到远程仓库 checkout 的状态。
• 依赖浏览器登录态或本机 dev server：Cloud 容器不会自动访问你的 Chrome、localhost 或桌面应用。
• 需要生产密钥进入 agent phase：secrets 不应该暴露给 agent 循环。
• 范围模糊的大重构：没有验收命令时，Cloud 只会把不确定性搬到远端。
• 需要产品判断或团队取舍：这些可以让 Codex 辅助分析，但不该让它直接改完整个方向。

我的习惯是：第一次 Cloud task 只选小任务。如果一个任务没法写出“跑什么命令算完成”，它还没准备好交给 Cloud。

Cloud task 开始前，先把 environment 配到能复现仓库

Cloud task 的运行顺序

一个 Cloud task 大致会按这个顺序跑：

1. 创建远程 container。
2. checkout 你选择的 branch 或 commit SHA。
3. 运行 setup script；如果恢复 cached container，可运行 maintenance script。
4. 应用网络策略。
5. agent 在 terminal command loop 中读文件、改代码、运行检查并尝试验证。
6. 结束后给出 answer、summary 和 diff，可继续追问或创建 PR。

很多 Cloud 任务失败，不是 agent 不会改代码，而是 environment 没复现仓库：依赖装不上、测试数据库缺配置、lockfile 与运行时不一致，或者 setup script 假设了本机才有的文件。

setup script、maintenance script 和 cache

setup script 要让容器从“刚 checkout 仓库”走到“能执行验收命令”。最小示例可以很短：

pnpm install
pnpm run typecheck
pnpm test -- --runInBand

它不是所有项目通用模板，而是提醒你：Cloud environment 至少要知道如何安装依赖、准备测试环境、跑一个能暴露问题的检查。

常见 setup 内容包括：

• 安装依赖、linter、formatter、typechecker 和 test tools。
• 初始化测试数据库，或生成安全的本地配置替代品。
• 为私有包安装准备一次性认证。
• 把必须持久的非敏感环境写入 environment settings，而不是只在 script 里临时 export。

cache 能减少重复安装依赖的时间，但也会让排障多一层判断。setup script、maintenance script、env vars 或 secrets 变化后，cache 会失效并重新跑；依赖突然不一致时，也可以主动 reset cache。

Secret、环境变量和网络：最容易误判的三件事

secrets 和 environment variables 的生命周期

secrets 和 environment variables 最大的区别不是名字，而是可见阶段。

配置项	什么时候用	不应该放什么	验收问题
environment variable	非敏感 runtime 配置	token、私钥、生产连接串	agent 是否真的需要读到
secret	setup 阶段拉依赖或安装工具	需要 agent 直接读取的值	setup 后是否已移除
setup internet	安装依赖、拉私有包	任意执行不可信脚本	lockfile 是否稳定
agent internet access	任务必须访问公开 API 或文档	unrestricted 全网	allowlist 和 methods 是否最小

secrets 适合 setup 阶段，例如安装私有依赖或拉取内部包。进入 agent phase 前，secrets 应被移除。也就是说，不要设计一个需要 agent 在修改代码时直接读取生产 token 的 Cloud task。

environment variables 会持续整个 task，适合 NODE_ENV=test、公开 API base URL、feature flag 这类非敏感配置。

agent internet access 只在需要时打开

setup script 可联网安装依赖，但 agent phase 默认无网络。这个默认值很重要，因为 agent 读外部网页或 API 时，风险也会变大。

必须打开 agent internet access 时，优先这样做：

1. allowlist 具体域名，而不是开放全网。
2. 尽量限制 HTTP methods，例如只允许 GET、HEAD、OPTIONS。
3. 不让 agent 读取、拼接或上传敏感文件。
4. 把需要联网核查的事实写清楚，别让 agent 自己漫游。

常见风险包括 prompt injection、代码或 secret 外传、下载恶意依赖、引入许可证不合规的包。为了“省一步”打开 unrestricted 网络，通常不划算。

给 Cloud 的 prompt 要像一个 issue

一个可直接改的 prompt 模板

Cloud prompt 不应该是一句愿望。它最好像一个小型 GitHub issue：目标、上下文、范围、环境、验收和停止条件都写清楚。

Goal: 修复 GitHub Actions 中 webhook.test.ts 的 failing test。
Context: 失败日志如下；相关代码大概率在 src/webhooks/ 和 tests/webhooks/。
Scope: 只修复 Stripe webhook signature 校验相关逻辑，不改 payment public API，不重构测试框架。
Environment: Cloud environment 已安装 pnpm 依赖；请优先运行 pnpm test tests/webhooks/webhook.test.ts。
Done when: 指定测试通过；列出改动文件、运行过的命令、未运行的检查和需要我人工确认的风险。
Stop if: 需要新增 secret、改数据库 schema、修改 shared/http-client.ts 或无法复现失败。

这个模板的重点不是格式，而是让 Codex 有边界可遵守。Cloud task 越像 issue，越容易交付一个可 review 的 diff。

Stop if 比“尽量小心”更有用

“尽量小心”太抽象，agent 很难知道什么算越界。Stop if 则能把风险转成明确条件。

可以写成：

• Stop if 需要新增 secret。
• Stop if 要改数据库 schema。
• Stop if 必须碰 shared auth middleware。
• Stop if 目标测试无法复现。
• Stop if 需要大面积重命名或迁移文件。

这样 Cloud task 遇到高风险点时，会更倾向于停下来解释，而不是继续扩大 diff。

Cloud 任务跑完后，看 summary、diff 和命令记录

什么时候追问，什么时候开 PR

Cloud 完成后，不要只看“完成了”三个字。先看四样东西：

1. summary 是否准确复述了目标和改动。
2. diff 是否只在 scope 内。
3. 命令记录是否包含你要求的测试、lint 或 typecheck。
4. 未运行的检查和人工风险是否被明确列出。

如果 diff 触碰了 scope 外文件，先追问：

The diff touches shared/http-client.ts, which was outside scope. Explain why it was necessary. If not necessary, revert that part and keep the webhook fix minimal.

如果没有跑目标测试，也先追问：

You did not run the target test. Run pnpm test tests/webhooks/webhook.test.ts and summarize the result before opening a PR.

只有改动范围清楚、验收命令可信、风险已经写明时，才适合进入 PR。

本地接回时检查什么

两条路径都可以：

• 小改动：Create PR，交给 GitHub review、CI 和团队流程。
• 高风险改动：check out locally，先用本机工具、Codex app review pane 或 IDE 验证。

本地接回时至少看这些：

• git status 是否干净，或是否在独立 branch / worktree。
• diff 是否只包含 Cloud task 的目标。
• 目标测试、lint、typecheck 是否本地也通过。
• 是否修改 .env*、secret、CI config、lockfile 或 generated files。
• 是否需要把这次踩坑沉淀进 AGENTS.md。

Cloud diff 不是 merge 按钮。它只是把“远端完成的一次尝试”交还给你。

GitHub 里的 @codex review：第二道关，不是合并许可

手动触发和 automatic reviews

在已经配置 Codex Cloud 和 Code review 的 GitHub PR 里，可以用一行评论触发 review：

@codex review

也可以更聚焦：

@codex review for security regressions

Codex review 会读取 PR diff，遵循仓库里最接近 changed file 的 AGENTS.md 指导，并默认聚焦高优先级问题。团队也可以开启 automatic reviews，让 PR opened for review 时自动触发。

但 automatic review 不等于 automatic merge。它可以帮你更快发现 P0/P1 类问题，不能替代业务 owner、CI 和最终人工判断。

Codex review 适合做什么	仍要人工决定什么
找明显回归、遗漏校验、危险权限变化	需求是否正确、取舍是否合理
按 AGENTS.md review guidelines 查 PR diff	架构方向、产品语义、发布时机
对 P0/P1 问题给出高信号评论	是否接受风险、是否合并

如果 review 发现问题，可以继续让 Codex 基于 PR context 修复，例如评论 @codex fix the P1 issue。这会进入 Cloud task 流程，仍然需要你验收 diff。

@codex 没反应时先按顺序排查

不要在 PR 里反复重发同一句评论。先按顺序查：

1. 这个 repository 是否已经设置 Codex Cloud。
2. Code review 是否在 Codex settings 中为该 repository 打开。
3. 评论是否精确包含 @codex review。
4. automatic review 是否打开，触发事件是否匹配。
5. GitHub app / repository 权限是否允许读取 PR diff、评论和 push branch。
6. workspace/admin policy、GitHub Enterprise 或 private repo 访问是否有限制。
7. usage limit 是否已经到达，尤其 code review limit 和普通聊天额度可能不同。

如果 Cloud task、review、非 review 的 @codex comment 表现不同，记录 task、comment、repository 和时间，再查官方支持或团队管理员。

Remote devbox / SSH host 不是 Cloud

什么时候改用 remote connection

还有一类需求，既不适合本机 Local，也不适合 Cloud：项目本来就在 devbox、GPU 机器、内网环境或企业 remote development host 上。

这时要区分：

• Codex Cloud：OpenAI managed / configured cloud environment，checkout GitHub repo，适合离开本机的仓库任务和 PR。
• Remote connection / SSH host：Codex app 连接到你的远程 host，使用那台机器的 files、credentials、permissions、plugins、browser setup 和 local tools。

如果任务需要内网服务、GPU、远程数据库或 devbox 上已经配置好的工具，remote connection 更接近真实环境。它的安全边界也不同：远程 host 上 Codex 能用的权限、凭据和工具，就是你给它的边界。

保守做法是使用 trusted SSH keys、least-privilege accounts，不把 app-server transport 暴露到公网；跨网络访问优先 VPN 或 mesh networking。

一套保守的 Codex Cloud SOP

第一次接 Codex Cloud，可以按这个顺序走：

1. 选一个仓库状态可复现的小任务，不选大重构。
2. 在 repository 上配置 Cloud environment。
3. 写 setup script，让依赖安装和目标检查可重复。
4. 只把 setup 阶段需要的敏感值放进 secrets；非敏感配置才放 env vars。
5. 默认保持 agent internet access 关闭；必须开启时只 allowlist 必要域名和 methods。
6. 把 task prompt 写成 issue：Goal、Context、Scope、Environment、Done when、Stop if。
7. 任务运行时看 plan、命令和异常。
8. 完成后读取 summary、diff、测试结果和未完成检查。
9. 小改动可 Create PR；高风险改动先 check out locally。
10. PR 上用 @codex review 做第二道检查。
11. 最终合并仍看人、CI 和团队流程。
12. 把反复出现的 review 规则沉淀到 AGENTS.md。

真正让 Cloud 稳定的不是“自动化程度更高”，而是每个环节都有清楚边界：环境能复现，prompt 能执行，diff 能验收，review 能追责。这样你才是在把一个明确需求交给云端 Agent，而不是把不确定性扔到更远的地方。