Codex Web/Cloud：云端异步任务与环境配置

Codex 的云端模式让你可以把任务异步委派给远程环境，自己继续做其他事情。无论是长时间运行的重构任务、批量并行的代码生成，还是需要特定依赖的构建验证，云端模式都能胜任。

本篇将全面解析 Codex Web 界面、Cloud Environment 配置、互联网访问控制、任务生命周期，以及如何从 CLI 和 App 操控云端任务。

一、Codex Web 与 Codex Cloud 的关系

这两个词经常交替出现，先理清它们的关系：

二、GitHub 仓库连接与配置

云端模式的第一步是连接 GitHub 账号。

2.1 设置步骤

1. 访问 codex.openai.com
2. 点击 Connect GitHub → 授权 Codex 访问你的仓库
3. 选择要授权的仓库（可以是全部或指定仓库）
4. 授权后 Codex 即可：
   • 读取仓库代码
   • 创建分支和 Pull Request
   • 响应 @codex 提及

2.2 从 GitHub 触发任务

连接后，你可以在 GitHub Issues 或 Pull Requests 中用 @codex 标记，Codex 会自动拾取并在云端执行任务。

三、Cloud Environment 设置

环境配置是云端模式的核心——它决定了 Codex 在哪个容器中运行、安装什么依赖、能访问哪些秘密。

3.1 默认容器镜像：universal

Codex Cloud 使用一个名为 universal 的默认容器镜像，预装了常见语言和工具：

• Python、Node.js、Go、Rust、Java 等常见运行时
• 常用包管理器（npm、pip、cargo 等）
• Git、curl 等基础工具

你可以在环境设置中通过 Set package versions 固定 Python、Node.js 等运行时的版本。详细的预装内容参见 openai/codex-universal Dockerfile。

3.2 Setup Script（启动脚本）

用于安装项目特定的依赖和工具。在环境创建后第一时间执行。

自动设置：对于使用 npm、yarn、pnpm、pip、pipenv、poetry 的项目，Codex 可以自动检测并安装依赖。

手动设置：复杂项目可以自定义 setup script：

# 安装类型检查器
pip install pyright
​
# 安装依赖
poetry install --with test
pnpm install

3.3 Maintenance Script（维护脚本）

当缓存容器被复用时执行的可选脚本，用于更新依赖：

# 缓存容器可能基于旧提交，更新依赖
pnpm install

3.4 环境变量与 Secrets

设计思路：Secrets 仅对 setup script 可见，这是有意为之的安全设计——防止 agent 在执行任意代码时泄露敏感信息。如果 agent 需要访问某个 API Key，建议在 setup script 中将其写入配置文件，而非直接暴露为环境变量。

3.5 容器缓存

Codex 会缓存容器状态以加速后续任务：

四、互联网访问控制

这是云端模式中最重要的安全配置之一。

4.1 两个阶段的网络策略

4.2 Agent 阶段网络配置

Agent 阶段的互联网访问按环境单独配置：

开关状态：

• Off（默认）— 完全封锁网络
• On — 开启网络，可通过以下手段限制

域名白名单预设：

HTTP 方法限制：

可以仅允许 GET、HEAD、OPTIONS，屏蔽 POST、PUT、DELETE 等写入操作，进一步降低数据泄露风险。

4.3 互联网访问的安全风险

4.4 网络代理

所有云端环境的出站流量都通过 HTTP/HTTPS 网络代理，这是 OpenAI 的安全和滥用防护层。

五、云端任务生命周期

理解一个云端任务从提交到完成的完整流程：

5.1 完整流程

5.2 各阶段详解

5.3 从不同客户端提交的差异

六、从 CLI 操控云端任务

CLI 提供了一套完整的云端任务管理命令。

6.1 查看云端任务

# 打开云端任务列表（浏览器）
codex cloud
​
# 列出近期任务
codex cloud list

6.2 提交云端任务

# 基本提交
codex cloud exec "Add input validation to the signup form"
​
# 指定环境
codex cloud exec --env my-project-env "Fix the failing CI tests"
​
# 多次尝试（Best-of-N）
codex cloud exec --attempts 3 "Refactor the auth module to use JWT"

6.3 应用云端结果

# 将云端任务的 diff 应用到本地
codex apply

6.4 命令参考

七、Best-of-N 多次尝试（--attempts）

--attempts 是云端模式的杀手级功能——让 Codex 并行运行多次尝试，然后你从中选择最佳结果。

7.1 工作原理

codex cloud exec --attempts 3 "Optimize the database query performance"

1. Codex 并行启动 3 个独立容器
2. 每个容器独立执行相同的任务
3. 由于 LLM 的随机性，每次尝试可能产生不同的解决方案
4. 你可以比较所有结果，选择最佳的一个

7.2 适用场景

八、适用场景与最佳实践

8.1 云端模式的理想场景

8.2 不适合云端的场景

• 需要实时交互 — 需要反复对话微调的任务，本地模式更合适
• 调试前端 UI — 需要看到界面效果，本地/Worktree 更方便
• 涉及本地硬件/服务 — 云端无法访问你的本地数据库或设备

8.3 云端任务最佳实践

1. 写好 AGENTS.md — 云端 agent 会读取它来了解项目规范和 lint/test 命令
2. 配置完善的环境 — 确保 setup script 能正确安装所有依赖
3. 最小化网络访问 — 默认关闭，仅在必要时开启并限制域名
4. 善用容器缓存 — 避免频繁修改 setup script 导致缓存失效
5. 先本地测试，再云端批量 — 小任务先本地验证效果，确认后再批量提交
6. 审查每个 PR — 云端生成的 diff 仍需人工审查确认

九、实战：批量重构工作流

以下是一个利用云端模式批量处理任务的实战示例。

场景：将项目中所有 REST API 迁移为 GraphQL

Step 1 — 配置环境

1. 在 Codex Web 中创建/检查环境配置
2. 确保 setup script 包含必要的 GraphQL 工具链：

npm install
npm install -g graphql-cli

Step 2 — 批量提交任务

使用 CLI 脚本批量提交：

# 为每个 API 模块提交独立的迁移任务
for module in users orders products payments; do
  codex cloud exec --env my-project \
    "Migrate the $module REST API endpoints to GraphQL. \
     Follow the patterns in src/graphql/schema.ts. \
     Update tests and ensure they pass."
done

Step 3 — 监控进度

# 查看所有任务状态
codex cloud list

或在 Web 界面中查看每个任务的进度。

Step 4 — 审查结果

每个任务完成后：

1. 查看 diff 和 agent 的工作日志
2. 如需修改，追加 follow-up 要求
3. 满意后为每个模块创建独立的 PR

Step 5 — 本地验证

# 将所有 PR 合并到测试分支后运行完整测试
codex apply
npm test

十、云端模式速查