用途
Codex Cloud 适合把一个基于 GitHub 仓库、可以在隔离环境中完成的开发任务委派到云端运行。你在网页中选择仓库、分支和任务，云端创建临时环境，读取代码、执行检查、生成修改，最后返回结果和 diff。电脑关机不会中断已经提交的云端任务。 本页专门讲以下完整链路：- 连接 GitHub 并只授权需要的仓库；
- 准备运行时、依赖、环境变量和 Secrets；
- 选择网络权限并理解 Agent 阶段的外发风险；
- 写清任务边界，提交一个可审查的云端任务；
- 审查 diff、测试证据和权限影响，再决定是否提 PR；
- 比较 Cloud、Local 和 Git worktree 的适用范围；
- 停止、归档、删除任务及清理相关分支；
- 按个人、团队和企业治理边界排查故障。
chatgpt.com/codex 页面、工作区策略和 OpenAI 官方文档为准；本页提供的是稳定的判断方法和验收证据。
先理解边界
Cloud 不是把你的电脑远程控制一遍，而是在 OpenAI 管理的隔离云端容器中处理已授权的仓库内容。典型流程如下：适合与不适合的任务
适合委派到 Cloud 的任务通常满足四个条件：输入在 GitHub 仓库中，环境可以脚本化，验收标准可以运行命令验证，结果可以通过 diff 审查。例如：- 修复一个有明确复现步骤的测试失败；
- 为某个模块补单元测试或类型标注；
- 批量更新已知格式，但限定文件范围；
- 运行较慢、无需本地设备的测试或静态分析；
- 并行处理多个相互独立的 issue；
- 在隔离分支上准备一个待审的重构草稿。
- 必须读取未提交的本地文件、私有目录或本地数据库；
- 依赖本机设备、USB、浏览器登录态、内网服务或本地 MCP；
- 涉及生产凭据、客户原始数据、个人信息或受合同限制的代码；
- 需要在本地 worktree 中与未完成修改精确配合；
- 需要人工逐步审批每个外部命令；
- 目标是直接部署、删库、改生产配置或发送不可撤回消息。
一、连接仓库并检查授权
1. 确认账号与工作区
- 在浏览器打开
https://chatgpt.com/codex。 - 确认登录的是正确的个人账号或企业工作区。
- 查看当前工作区是否允许使用 Codex Cloud，以及账号套餐是否包含该能力。
- 如果页面提示没有权限，先联系工作区管理员，不要通过共享账号或他人令牌绕过控制。
2. 连接 GitHub
首次使用通常需要授权 Codex 访问 GitHub。授权页面可能提供“全部仓库”或“仅选择仓库”等范围选项。 推荐步骤：- 选择仅授权本次工作所需的组织和仓库。
- 核对授权的 GitHub 组织、安装位置和仓库清单。
- 确认仓库没有把生产配置、密钥或不应外发的数据提交进去。
- 完成回跳后，在 Codex 的仓库选择器中搜索目标仓库。
- 用测试仓库先创建一个只读或极小修改任务，确认连接确实指向正确仓库。
3. 复核 GitHub 权限
仓库授权至少涉及三层权限，不能混为一谈：
给 Codex Cloud 的仓库写权限，并不等于给它生产环境权限。反过来，仓库写权限也足以造成依赖文件、工作流或代码变更，因此仍须审查每个 PR。
不需要创建 PR 时，可以只让任务返回 diff，由人工在本地应用或按团队流程提交。不要为了省一步操作而扩大 GitHub 授权范围。
二、准备云端环境
1. 认识环境初始化顺序
一次任务通常按以下顺序初始化：- 创建隔离容器；
- 按指定分支或提交拉取仓库；
- 使用默认镜像准备常见工具；
- 执行设置脚本，安装依赖和项目工具；
- 应用 Agent 阶段的网络设置；
- 让 Agent 读取项目规则、执行任务和验证命令。
AGENTS.md、README、构建脚本和测试配置应明确写出安装、检查和禁止事项。不要把只存在于个人电脑的全局配置当作云端配置；Cloud 看不到本机的 ~/.codex、本地插件、本地 MCP 或未提交文件。
2. 选择镜像和运行时版本
默认的universal 镜像通常包含常用语言和工具。项目如果要求特定版本，应在环境设置中固定 Node.js、Python 或其他运行时版本，并在设置脚本中验证：
3. 编写设置脚本
设置脚本只负责可重复的初始化，例如安装依赖、安装 lint 工具和准备测试数据。示例：- 可重复执行，失败时返回非零状态；
- 不删除仓库外文件，不修改生产系统；
- 不把密钥打印到标准输出；
- 不依赖交互式输入；
- 尽量固定依赖版本，并使用锁文件；
- 明确区分安装、构建和测试阶段。
export TEMP_VALUE=...，不应假定 Agent 阶段仍能读取它。需要贯穿任务的普通配置放在环境变量设置中，或写入受控的 ~/.bashrc；不要用这种方式传递敏感值。
4. 区分环境变量与 Secrets
把 API key、密码、SSH 私钥、云厂商令牌、客户数据放进仓库是错误做法。Secrets 也不是“可以放心交给任意脚本”的保险箱：设置脚本及其依赖可能读取它们。因此，能不用秘密就不用；必须使用时，使用短期、最小范围、只读的凭据，并确认初始化脚本来源可信。
如果 Agent 阶段需要调用外部服务，Secrets 在初始化阶段被移除可能导致任务失败。这时不要把 Secret 改成普通环境变量来“解决”问题，而应先确认是否真的需要联网和凭据，再让安全负责人评估专用代理、短期令牌或改用 Local 的方案。
5. 了解缓存影响
Cloud 可能缓存环境状态以减少重复安装时间。缓存会让任务更快，但也可能保留旧依赖或旧构建产物。修改设置脚本、环境变量、Secrets 或依赖锁文件后，应检查缓存是否自动失效；结果异常时使用环境页面提供的重置缓存操作。 团队或企业共享环境时，重置缓存可能影响其他成员的任务。重置前记录原因、当前环境版本和正在运行的任务，避免把别人的任务变成难以解释的初始化失败。三、配置网络并控制数据外发
1. 默认保持 Agent 断网
Agent 阶段默认断网是重要的安全边界。许多任务只需在设置脚本阶段下载依赖，Agent 不需要访问网络。先用网络关闭的环境跑通本地检查，再判断是否有明确需求。 只有以下情况才考虑开放 Agent 网络：- 必须读取指定的实时 API 数据；
- 测试必须访问一个外部测试服务；
- 任务必须获取未能在初始化阶段准备的公开资料。
2. 使用最小白名单
如果确实需要网络，按以下顺序收紧：- 打开 Agent 网络访问；
- 选择
None或Common dependencies等最小预设； - 只添加任务确实需要的完整域名；
- 优先只允许
GET、HEAD、OPTIONS； - 任务结束后关闭不再需要的网络配置。
All 或 unrestricted。域名白名单限制的是访问目的地，不代表返回内容可信；只读 HTTP 方法可以减少 POST、PUT、PATCH、DELETE 形式的数据外发，但不能替代 diff 审查和凭据隔离。
云端容器的网络路径与本地浏览器不同。你本地能访问某网站，不代表容器能访问；你本地无法访问，也不一定是容器失败。网页登录和 GitHub 授权是本地浏览器链路，容器安装依赖和 Agent 出站则受云端环境、代理和白名单控制。
3. 识别外发风险
提交任务前检查：- prompt 是否要求读取完整
.env、凭据目录或客户数据； - 仓库 Issue、PR 和测试夹具是否含有不可信指令；
- 依赖安装是否会执行生命周期脚本；
- 测试是否会向真实服务写入数据；
- 网络方法是否允许写请求；
- 输出摘要、日志和 PR 是否可能包含秘密。
四、委派一个可审查的任务
1. 先写任务卡
在网页提交前准备一份短任务卡，至少包括：2. 选择分支和基准
选择任务使用的仓库、分支或固定 commit。对于重要修复，优先以明确 commit 作为基准，避免任务运行期间上游分支变化导致结果无法复现。 **预期结果：**任务详情显示正确的仓库、基准分支或提交。若仓库有未合并的依赖变更，应在任务描述中明确是否包含它们。3. 提交并观察状态
提交后，云端一般会显示排队、初始化、运行中、完成或失败等状态。记录任务链接、创建时间、仓库、基准和环境名称。 Cloud Agent 通常会在云端连续执行，不像 Local 那样在每个越权操作前都依赖你实时批准。因此提交前的范围设计和提交后的结果审查尤其重要。任务卡里写了“不要提交”并不能代替 GitHub 权限控制；真正的权限要在连接器、工作区策略和仓库设置中收紧。 多个独立任务可以并行委派，但每个任务应使用独立上下文和清晰目标。不要让两个任务同时修改同一批文件，再把两个结果盲目合并。4. 追问和继续任务
任务完成后可以在同一上下文中要求修正，但每次追问都要重新说明新增范围。例如：五、审查结果并决定是否提 PR
1. 不要只看摘要
完成状态不是验收证据。按以下顺序审查：- 核对仓库、基准分支和任务描述；
- 阅读完整 diff 和文件列表；
- 检查是否有未请求的依赖、配置、锁文件或工作流变化；
- 阅读 Agent 执行的命令和测试输出；
- 在可信的 Local 或 CI 环境重新运行关键检查；
- 检查是否出现密钥、令牌、路径或客户数据；
- 检查边界条件、错误处理、日志和性能影响。
2. 用清单审查 diff
如果发现额外修改，先暂停提 PR。要求云端解释每个额外文件，或丢弃任务重新开始。不要因为“改动看起来合理”就跳过范围审查。
3. 提 PR 前后的责任
只有在 diff、测试和数据检查通过后，才执行“创建 Pull Request”。PR 描述应包含任务目标、变更范围、验证命令、未验证假设、网络设置和潜在风险。 创建 PR 不等于批准合并。评审人仍需按普通代码评审检查安全、依赖、迁移和回滚。涉及生产配置、权限策略、数据迁移或外部 API 的 PR，应由相应负责人批准。合并和部署遵循仓库保护分支、CI 门禁和变更管理制度。 如果结果不符合预期，不提 PR，直接关闭或删除任务分支。若 PR 已创建，先关闭 PR，再按仓库权限删除分支或恢复提交；不要用强制推送掩盖审查痕迹。六、Cloud、Local 与 Worktree 的差异
选择原则：
- 需要本地未提交内容、内网、设备或本机凭据，使用 Local；
- 需要多个独立任务并行，且仓库已在 GitHub，使用 Cloud；
- 想在本机并行工作、又不想污染当前分支，使用 Local worktree；
- 任务包含敏感数据时，先看组织数据政策，不要仅凭“容器隔离”做决定。
七、密钥与数据治理边界
个人使用
个人用户至少应做到：不上传真实.env、私钥、生产数据库导出和客户原始数据；仓库使用最小授权；环境中的 Secrets 只放短期、只读凭据；任务完成后删除不再使用的连接、分支和令牌。
团队使用
团队应在启用前约定：哪些仓库允许 Cloud、哪些数据类别禁止上传、谁批准网络白名单、谁审查 PR、如何保留任务记录、如何撤销 GitHub 连接和令牌。把这些规则写进仓库的AGENTS.md 只能帮助 Agent 遵守，不替代 GitHub、身份提供商和网络层面的强制控制。
企业使用
企业管理员应分别评估 Codex Local 和 Cloud 的数据流向与合同承诺。重点确认：- 工作区是否启用了 Cloud，成员是否按组授权；
- GitHub 连接器是按组织还是按仓库授权；
- SSO、MFA、SCIM 和离职回收是否已生效；
- 企业数据不用于训练的承诺是否适用于当前套餐和合同；
- 云端代码处理的数据驻留、留存和删除策略；
- 审计日志保存期限，以及是否需要定期导出；
- 哪些任务必须禁止 Cloud，哪些域名可以加入白名单；
- 谁拥有管理员、仓库管理员、数据合规和成本分析权限。
八、停止、归档和删除任务
1. 运行中停止
发现仓库、权限、网络或任务范围错误时，立即在任务页面使用停止、取消或终止操作。停止后确认状态变为已取消或已停止，并记录停止时间和原因。 停止任务不一定撤销已经发出的网络请求，也不一定删除所有任务记录。若任务接触过凭据，应立即撤销或轮换相关令牌，并检查服务端访问日志。2. 完成后归档
对已审查但暂时保留的任务，使用归档功能减少任务列表和后台资源。归档通常是隐藏或整理记录，不等于删除仓库分支、PR、日志或缓存。需要长期保存的审查证据应按团队规则导出到受控位置。3. 删除任务结果
如果页面支持删除任务或运行记录，先确认它会删除哪些对象：任务记录、云端容器、缓存、生成分支、PR，还是只从界面移除。删除前保存必要的任务链接、审查结论和合规记录，避免误删调查证据。 删除云端任务不会自动删除 GitHub 上已经创建的 PR、分支或提交。应分别检查并按权限处理：关闭 PR、删除临时分支、撤销无用连接、清理测试数据。不要删除仍被其他任务或评审引用的分支。九、故障排查
仓库找不到或授权失败
- 确认当前 ChatGPT 和 GitHub 是同一预期账号；
- 检查 GitHub App 是否安装在目标组织；
- 检查仓库是否被限制为“仅选定仓库”；
- 确认组织管理员没有阻止第三方应用；
- 重新授权后刷新仓库列表；
- 仍失败时记录错误码、组织策略和仓库可见性，交给管理员处理。
设置脚本失败
检查运行时版本、锁文件、包源域名、脚本退出码和是否依赖交互输入。确认失败发生在初始化阶段还是 Agent 阶段；两者网络策略不同。必要时在本地用相同版本复现，再缩小设置脚本。 如果只是缓存状态错误，先确认没有其他成员正在使用共享环境，再重置缓存。不要把安装失败直接归因于 Agent 能力不足。Agent 报网络错误
先确认任务是否真的需要 Agent 网络。需要时检查网络开关、域名白名单、HTTP 方法和云端 DNS/代理限制。白名单只填实际请求的域名，不要直接切换到 unrestricted。依赖安装成功但 Agent 请求失败，通常说明两个阶段的设置不同。结果过宽或改错文件
停止追问，保存当前 diff，检查任务描述是否缺少文件范围和禁止事项。若未创建 PR，丢弃结果并重新派一个更小的任务；若已创建 PR，关闭 PR 或标记为不合并，避免在同一错误基线上继续累积修改。任务卡住、超时或状态不更新
检查任务日志、初始化步骤和服务状态；确认本地浏览器只是查看端没有断开误导，云端任务不一定依赖本地浏览器持续打开。若任务重复失败，减少任务范围、关闭不必要网络、固定依赖并重新运行。不要连续点击重复提交，避免产生多个并行分支。找不到预期的密钥或配置
确认变量名、作用阶段和工作区环境。不要为了让任务通过，把 Secret 改成普通变量、写进仓库或打印到日志。若 Agent 必须使用该凭据，先重新评估任务是否应移到 Local 或由专用 CI 流程执行。十、最小实战与验收
使用一个没有敏感数据的练习仓库完成以下流程：- 连接 GitHub，只选择练习仓库；
- 保持 Agent 网络 Off，使用默认镜像；
- 确认仓库有锁文件和最小测试命令；
- 委派“只新增一个测试文件，不改其他文件”的任务；
- 等待初始化和 Agent 完成；
- 阅读任务摘要、命令输出和完整 diff；
- 在本地重新运行对应测试；
- 不提 PR，先停止或归档任务；
- 检查 GitHub 没有多余分支、提交或工作流变更。
- 仓库和基准正确；
- 任务只修改约定文件；
- 关键测试有可复现命令；
- 网络权限符合最小需求；
- 输出中没有密钥和个人数据；
- 没有误创建或误修改生产资源；
- 不需要的任务、缓存、分支和令牌已按规则清理。