> ## Documentation Index
> Fetch the complete documentation index at: https://aicoding.cscitech.top/llms.txt
> Use this file to discover all available pages before exploring further.

# 04-Cloud云端使用

> 从仓库授权、云端环境和任务委派，到网络、密钥、结果审查及任务清理，完整掌握 Codex Cloud 的安全使用流程。

## 用途

Codex Cloud 适合把一个基于 GitHub 仓库、可以在隔离环境中完成的开发任务委派到云端运行。你在网页中选择仓库、分支和任务，云端创建临时环境，读取代码、执行检查、生成修改，最后返回结果和 diff。电脑关机不会中断已经提交的云端任务。

本页专门讲以下完整链路：

* 连接 GitHub 并只授权需要的仓库；
* 准备运行时、依赖、环境变量和 Secrets；
* 选择网络权限并理解 Agent 阶段的外发风险；
* 写清任务边界，提交一个可审查的云端任务；
* 审查 diff、测试证据和权限影响，再决定是否提 PR；
* 比较 Cloud、Local 和 Git worktree 的适用范围；
* 停止、归档、删除任务及清理相关分支；
* 按个人、团队和企业治理边界排查故障。

网页按钮、套餐能力和具体字段会随版本变化。操作时以当前 `chatgpt.com/codex` 页面、工作区策略和 OpenAI 官方文档为准；本页提供的是稳定的判断方法和验收证据。

## 先理解边界

Cloud 不是把你的电脑远程控制一遍，而是在 OpenAI 管理的隔离云端容器中处理已授权的仓库内容。典型流程如下：

```text theme={null}
浏览器登录
  -> 连接 GitHub 并选择仓库
  -> 选择分支或提交，准备云端环境
  -> 执行设置脚本安装依赖
  -> 按网络策略启动 Agent
  -> 修改代码并运行检查
  -> 返回摘要、日志和 diff
  -> 人工审查后提 PR、合并或放弃
```

设置脚本和 Agent 是两个不同阶段。设置脚本通常需要网络来安装依赖；Agent 阶段默认断网，是否联网由环境设置决定。不要因为设置脚本能下载依赖，就推断 Agent 也能访问任意网站。

Cloud 也不是自动合并器。它可以生成修改和 PR，但合并、发布、修改生产系统、发送外部消息等动作仍应由有权限的人按团队流程确认。云端任务完成只代表“产生了一个待审结果”，不代表代码正确、合规或已经上线。

## 适合与不适合的任务

适合委派到 Cloud 的任务通常满足四个条件：输入在 GitHub 仓库中，环境可以脚本化，验收标准可以运行命令验证，结果可以通过 diff 审查。例如：

* 修复一个有明确复现步骤的测试失败；
* 为某个模块补单元测试或类型标注；
* 批量更新已知格式，但限定文件范围；
* 运行较慢、无需本地设备的测试或静态分析；
* 并行处理多个相互独立的 issue；
* 在隔离分支上准备一个待审的重构草稿。

下列任务优先留在 Local，或先得到安全负责人批准：

* 必须读取未提交的本地文件、私有目录或本地数据库；
* 依赖本机设备、USB、浏览器登录态、内网服务或本地 MCP；
* 涉及生产凭据、客户原始数据、个人信息或受合同限制的代码；
* 需要在本地 worktree 中与未完成修改精确配合；
* 需要人工逐步审批每个外部命令；
* 目标是直接部署、删库、改生产配置或发送不可撤回消息。

一个简单判断是：如果任务的关键输入不在 GitHub 仓库，或最终副作用不应发生在隔离容器中，就不要直接委派到 Cloud。

## 一、连接仓库并检查授权

### 1. 确认账号与工作区

1. 在浏览器打开 `https://chatgpt.com/codex`。
2. 确认登录的是正确的个人账号或企业工作区。
3. 查看当前工作区是否允许使用 Codex Cloud，以及账号套餐是否包含该能力。
4. 如果页面提示没有权限，先联系工作区管理员，不要通过共享账号或他人令牌绕过控制。

\*\*预期结果：\*\*页面显示可创建云端任务的入口，并能看到当前工作区允许使用的仓库连接器或项目列表。

企业环境中，管理员可能分别控制 Codex Local 和 Codex Cloud。能使用本地 CLI 不等于能使用 Cloud；Cloud 还可能要求 GitHub 连接器、组织审批或指定成员组。

### 2. 连接 GitHub

首次使用通常需要授权 Codex 访问 GitHub。授权页面可能提供“全部仓库”或“仅选择仓库”等范围选项。

推荐步骤：

1. 选择仅授权本次工作所需的组织和仓库。
2. 核对授权的 GitHub 组织、安装位置和仓库清单。
3. 确认仓库没有把生产配置、密钥或不应外发的数据提交进去。
4. 完成回跳后，在 Codex 的仓库选择器中搜索目标仓库。
5. 用测试仓库先创建一个只读或极小修改任务，确认连接确实指向正确仓库。

\*\*预期结果：\*\*目标仓库可以被选中，并能看到可用分支或提交。仓库列表为空时，优先检查 GitHub App 的安装范围、组织审批、仓库可见性和当前登录账号。

### 3. 复核 GitHub 权限

仓库授权至少涉及三层权限，不能混为一谈：

| 权限            | 解决的问题           | 使用前检查        |
| ------------- | --------------- | ------------ |
| 读取仓库          | Cloud 能否拉取代码和历史 | 仓库是否在授权范围    |
| 创建分支或 PR      | 是否能提交云端结果       | 账号是否有对应写权限   |
| 管理设置或 Secrets | 是否能改仓库治理配置      | 是否由仓库管理员单独负责 |

给 Codex Cloud 的仓库写权限，并不等于给它生产环境权限。反过来，仓库写权限也足以造成依赖文件、工作流或代码变更，因此仍须审查每个 PR。

不需要创建 PR 时，可以只让任务返回 diff，由人工在本地应用或按团队流程提交。不要为了省一步操作而扩大 GitHub 授权范围。

## 二、准备云端环境

### 1. 认识环境初始化顺序

一次任务通常按以下顺序初始化：

1. 创建隔离容器；
2. 按指定分支或提交拉取仓库；
3. 使用默认镜像准备常见工具；
4. 执行设置脚本，安装依赖和项目工具；
5. 应用 Agent 阶段的网络设置；
6. 让 Agent 读取项目规则、执行任务和验证命令。

仓库中的 `AGENTS.md`、README、构建脚本和测试配置应明确写出安装、检查和禁止事项。不要把只存在于个人电脑的全局配置当作云端配置；Cloud 看不到本机的 `~/.codex`、本地插件、本地 MCP 或未提交文件。

### 2. 选择镜像和运行时版本

默认的 `universal` 镜像通常包含常用语言和工具。项目如果要求特定版本，应在环境设置中固定 Node.js、Python 或其他运行时版本，并在设置脚本中验证：

```bash theme={null}
node --version
python --version
npm --version
```

\*\*预期结果：\*\*设置脚本输出的版本与项目声明一致，依赖安装和基础检查能够完成。版本不一致时，先修正环境配置，不要让 Agent 在任务中临时升级系统工具。

### 3. 编写设置脚本

设置脚本只负责可重复的初始化，例如安装依赖、安装 lint 工具和准备测试数据。示例：

```bash theme={null}
set -eu
npm ci
npm run build
```

或：

```bash theme={null}
set -eu
python -m pip install -r requirements.txt
python -m pytest --collect-only
```

脚本要满足以下要求：

* 可重复执行，失败时返回非零状态；
* 不删除仓库外文件，不修改生产系统；
* 不把密钥打印到标准输出；
* 不依赖交互式输入；
* 尽量固定依赖版本，并使用锁文件；
* 明确区分安装、构建和测试阶段。

设置脚本与 Agent 可能运行在不同的 Bash 会话中。在设置脚本中执行 `export TEMP_VALUE=...`，不应假定 Agent 阶段仍能读取它。需要贯穿任务的普通配置放在环境变量设置中，或写入受控的 `~/.bashrc`；不要用这种方式传递敏感值。

### 4. 区分环境变量与 Secrets

| 类型      | 可见阶段           | 适合内容                  | 主要风险                 |
| ------- | -------------- | --------------------- | -------------------- |
| 普通环境变量  | 设置脚本和 Agent    | `NODE_ENV`、非敏感路径、功能开关 | 可能出现在日志或 Agent 读取结果中 |
| Secrets | 通常只在初始化需要的阶段可用 | 私有包仓库令牌、临时安装凭据        | 脚本、依赖钩子可能读取并外发       |
| 仓库文件    | 任务全过程可读        | 非敏感规则和锁文件             | 会随 Git/PR 永久留下       |

把 API key、密码、SSH 私钥、云厂商令牌、客户数据放进仓库是错误做法。Secrets 也不是“可以放心交给任意脚本”的保险箱：设置脚本及其依赖可能读取它们。因此，能不用秘密就不用；必须使用时，使用短期、最小范围、只读的凭据，并确认初始化脚本来源可信。

如果 Agent 阶段需要调用外部服务，Secrets 在初始化阶段被移除可能导致任务失败。这时不要把 Secret 改成普通环境变量来“解决”问题，而应先确认是否真的需要联网和凭据，再让安全负责人评估专用代理、短期令牌或改用 Local 的方案。

### 5. 了解缓存影响

Cloud 可能缓存环境状态以减少重复安装时间。缓存会让任务更快，但也可能保留旧依赖或旧构建产物。修改设置脚本、环境变量、Secrets 或依赖锁文件后，应检查缓存是否自动失效；结果异常时使用环境页面提供的重置缓存操作。

团队或企业共享环境时，重置缓存可能影响其他成员的任务。重置前记录原因、当前环境版本和正在运行的任务，避免把别人的任务变成难以解释的初始化失败。

## 三、配置网络并控制数据外发

### 1. 默认保持 Agent 断网

Agent 阶段默认断网是重要的安全边界。许多任务只需在设置脚本阶段下载依赖，Agent 不需要访问网络。先用网络关闭的环境跑通本地检查，再判断是否有明确需求。

只有以下情况才考虑开放 Agent 网络：

* 必须读取指定的实时 API 数据；
* 测试必须访问一个外部测试服务；
* 任务必须获取未能在初始化阶段准备的公开资料。

“方便 Agent 搜索”不是足够理由。网页、Issue、PR 描述、依赖 README 和生成文件都可能包含提示注入，诱导 Agent 把代码、环境变量或命令结果发送出去。

### 2. 使用最小白名单

如果确实需要网络，按以下顺序收紧：

1. 打开 Agent 网络访问；
2. 选择 `None` 或 `Common dependencies` 等最小预设；
3. 只添加任务确实需要的完整域名；
4. 优先只允许 `GET`、`HEAD`、`OPTIONS`；
5. 任务结束后关闭不再需要的网络配置。

避免使用 `All` 或 unrestricted。域名白名单限制的是访问目的地，不代表返回内容可信；只读 HTTP 方法可以减少 POST、PUT、PATCH、DELETE 形式的数据外发，但不能替代 diff 审查和凭据隔离。

| 设置                  | 适用场景           | 风险判断         |
| ------------------- | -------------- | ------------ |
| 网络 Off              | 代码修改、静态分析、已有测试 | 推荐默认值        |
| Common dependencies | 需要常见包源或源码站     | 仍应限制方法       |
| 指定域名                | 访问单一测试 API     | 记录用途和期限      |
| unrestricted        | 极少数受控实验        | 不用于敏感仓库或常规任务 |

云端容器的网络路径与本地浏览器不同。你本地能访问某网站，不代表容器能访问；你本地无法访问，也不一定是容器失败。网页登录和 GitHub 授权是本地浏览器链路，容器安装依赖和 Agent 出站则受云端环境、代理和白名单控制。

### 3. 识别外发风险

提交任务前检查：

* prompt 是否要求读取完整 `.env`、凭据目录或客户数据；
* 仓库 Issue、PR 和测试夹具是否含有不可信指令；
* 依赖安装是否会执行生命周期脚本；
* 测试是否会向真实服务写入数据；
* 网络方法是否允许写请求；
* 输出摘要、日志和 PR 是否可能包含秘密。

安全的任务描述应明确：不得读取哪些路径，不得访问哪些域名，不得发送请求，不得修改哪些文件。禁止事项不是绝对防护，但能减少误解并提供审查依据。

## 四、委派一个可审查的任务

### 1. 先写任务卡

在网页提交前准备一份短任务卡，至少包括：

```text theme={null}
目标：修复 packages/api/src/timeout.ts 中的超时计算错误。
范围：只修改该文件及其对应测试。
输入：以当前分支代码为准，不读取 .env、密钥或生产数据。
约束：不要升级依赖，不改 CI，不执行部署，不提交或合并。
验证：运行 npm test -- timeout，并说明失败测试和未运行的测试。
交付：先给出摘要、文件列表、diff 和验证命令结果。
```

任务越具体，结果越容易比较。避免“全面优化一下”“把项目整理好”这类没有边界的指令，尤其不要把多个不相关目标塞进同一任务。

### 2. 选择分支和基准

选择任务使用的仓库、分支或固定 commit。对于重要修复，优先以明确 commit 作为基准，避免任务运行期间上游分支变化导致结果无法复现。

\*\*预期结果：\*\*任务详情显示正确的仓库、基准分支或提交。若仓库有未合并的依赖变更，应在任务描述中明确是否包含它们。

### 3. 提交并观察状态

提交后，云端一般会显示排队、初始化、运行中、完成或失败等状态。记录任务链接、创建时间、仓库、基准和环境名称。

Cloud Agent 通常会在云端连续执行，不像 Local 那样在每个越权操作前都依赖你实时批准。因此提交前的范围设计和提交后的结果审查尤其重要。任务卡里写了“不要提交”并不能代替 GitHub 权限控制；真正的权限要在连接器、工作区策略和仓库设置中收紧。

多个独立任务可以并行委派，但每个任务应使用独立上下文和清晰目标。不要让两个任务同时修改同一批文件，再把两个结果盲目合并。

### 4. 追问和继续任务

任务完成后可以在同一上下文中要求修正，但每次追问都要重新说明新增范围。例如：

```text theme={null}
只修复上一条测试反馈涉及的断言，不扩大到其他模块。
先说明将改哪些文件，再执行测试；不要提 PR。
```

如果第一次任务已经产生过宽的 diff，优先停止并重新创建一个边界更清晰的任务，不要连续追问让云端在混乱状态上继续堆修改。

## 五、审查结果并决定是否提 PR

### 1. 不要只看摘要

完成状态不是验收证据。按以下顺序审查：

1. 核对仓库、基准分支和任务描述；
2. 阅读完整 diff 和文件列表；
3. 检查是否有未请求的依赖、配置、锁文件或工作流变化；
4. 阅读 Agent 执行的命令和测试输出；
5. 在可信的 Local 或 CI 环境重新运行关键检查；
6. 检查是否出现密钥、令牌、路径或客户数据；
7. 检查边界条件、错误处理、日志和性能影响。

\*\*预期结果：\*\*diff 只包含任务范围内的文件，关键测试有明确命令和通过证据，未验证项目被明确列出。任何“测试通过”都应说明测试范围，不应理解为整个系统没有风险。

### 2. 用清单审查 diff

| 检查项  | 通过标准               |
| ---- | ------------------ |
| 文件范围 | 只修改任务允许的路径         |
| 行为   | 与验收标准一致，有测试或可复现证据  |
| 依赖   | 没有无理由的升级和新增脚本      |
| 安全   | 没有硬编码秘密、放宽权限或绕过校验  |
| 网络   | 没有把测试指向生产或新增外发请求   |
| Git  | 没有隐藏生成物、异常大文件或误删历史 |
| 文档   | 修改了必要说明，没有篡改治理规则   |

如果发现额外修改，先暂停提 PR。要求云端解释每个额外文件，或丢弃任务重新开始。不要因为“改动看起来合理”就跳过范围审查。

### 3. 提 PR 前后的责任

只有在 diff、测试和数据检查通过后，才执行“创建 Pull Request”。PR 描述应包含任务目标、变更范围、验证命令、未验证假设、网络设置和潜在风险。

创建 PR 不等于批准合并。评审人仍需按普通代码评审检查安全、依赖、迁移和回滚。涉及生产配置、权限策略、数据迁移或外部 API 的 PR，应由相应负责人批准。合并和部署遵循仓库保护分支、CI 门禁和变更管理制度。

如果结果不符合预期，不提 PR，直接关闭或删除任务分支。若 PR 已创建，先关闭 PR，再按仓库权限删除分支或恢复提交；不要用强制推送掩盖审查痕迹。

## 六、Cloud、Local 与 Worktree 的差异

| 维度       | Cloud        | Local 主检出    | Local Git worktree |
| -------- | ------------ | ------------ | ------------------ |
| 执行位置     | 托管云端容器       | 你的电脑         | 你的电脑上的独立工作树        |
| 输入       | 已授权的远程仓库     | 本机全部可见文件     | 该 worktree 可见文件    |
| 电脑关机     | 已提交任务通常继续    | 通常停止         | 通常停止               |
| GitHub   | 通常是必要连接      | 可选           | 可选                 |
| 本地工具/MCP | 不可直接使用       | 可使用          | 可使用                |
| 隔离方式     | 每个任务独立云端环境   | 依赖本地沙箱和审批    | 与主检出隔离             |
| 交付       | diff、任务结果、PR | 直接修改本地文件     | 独立分支或工作树中的修改       |
| 适合       | 并行、后台、可脚本化任务 | 需要本机上下文和逐步审批 | 并行本地任务、避免互相覆盖      |

选择原则：

* 需要本地未提交内容、内网、设备或本机凭据，使用 Local；
* 需要多个独立任务并行，且仓库已在 GitHub，使用 Cloud；
* 想在本机并行工作、又不想污染当前分支，使用 Local worktree；
* 任务包含敏感数据时，先看组织数据政策，不要仅凭“容器隔离”做决定。

Cloud 的隔离容器减少了对你电脑的直接影响，但不会自动解决代码授权、数据驻留、日志保留、第三方依赖和 PR 供应链风险。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、删除临时分支、撤销无用连接、清理测试数据。不要删除仍被其他任务或评审引用的分支。

## 九、故障排查

### 仓库找不到或授权失败

1. 确认当前 ChatGPT 和 GitHub 是同一预期账号；
2. 检查 GitHub App 是否安装在目标组织；
3. 检查仓库是否被限制为“仅选定仓库”；
4. 确认组织管理员没有阻止第三方应用；
5. 重新授权后刷新仓库列表；
6. 仍失败时记录错误码、组织策略和仓库可见性，交给管理员处理。

不要把仓库改成公开或把个人账号加入组织来绕过授权问题。

### 设置脚本失败

检查运行时版本、锁文件、包源域名、脚本退出码和是否依赖交互输入。确认失败发生在初始化阶段还是 Agent 阶段；两者网络策略不同。必要时在本地用相同版本复现，再缩小设置脚本。

如果只是缓存状态错误，先确认没有其他成员正在使用共享环境，再重置缓存。不要把安装失败直接归因于 Agent 能力不足。

### Agent 报网络错误

先确认任务是否真的需要 Agent 网络。需要时检查网络开关、域名白名单、HTTP 方法和云端 DNS/代理限制。白名单只填实际请求的域名，不要直接切换到 unrestricted。依赖安装成功但 Agent 请求失败，通常说明两个阶段的设置不同。

### 结果过宽或改错文件

停止追问，保存当前 diff，检查任务描述是否缺少文件范围和禁止事项。若未创建 PR，丢弃结果并重新派一个更小的任务；若已创建 PR，关闭 PR 或标记为不合并，避免在同一错误基线上继续累积修改。

### 任务卡住、超时或状态不更新

检查任务日志、初始化步骤和服务状态；确认本地浏览器只是查看端没有断开误导，云端任务不一定依赖本地浏览器持续打开。若任务重复失败，减少任务范围、关闭不必要网络、固定依赖并重新运行。不要连续点击重复提交，避免产生多个并行分支。

### 找不到预期的密钥或配置

确认变量名、作用阶段和工作区环境。不要为了让任务通过，把 Secret 改成普通变量、写进仓库或打印到日志。若 Agent 必须使用该凭据，先重新评估任务是否应移到 Local 或由专用 CI 流程执行。

## 十、最小实战与验收

使用一个没有敏感数据的练习仓库完成以下流程：

1. 连接 GitHub，只选择练习仓库；
2. 保持 Agent 网络 Off，使用默认镜像；
3. 确认仓库有锁文件和最小测试命令；
4. 委派“只新增一个测试文件，不改其他文件”的任务；
5. 等待初始化和 Agent 完成；
6. 阅读任务摘要、命令输出和完整 diff；
7. 在本地重新运行对应测试；
8. 不提 PR，先停止或归档任务；
9. 检查 GitHub 没有多余分支、提交或工作流变更。

验收标准：

* 仓库和基准正确；
* 任务只修改约定文件；
* 关键测试有可复现命令；
* 网络权限符合最小需求；
* 输出中没有密钥和个人数据；
* 没有误创建或误修改生产资源；
* 不需要的任务、缓存、分支和令牌已按规则清理。

## 小结

Codex Cloud 的核心价值是：把可脚本化、可隔离、可审查的仓库任务放到云端并行运行，电脑关机也不影响已提交任务。核心风险则集中在授权范围、初始化脚本、网络外发、密钥暴露和未经审查的 PR。

记住这条工作顺序：

```text theme={null}
最小授权
  -> 固定仓库与基准
  -> 准备可重复环境
  -> 默认关闭 Agent 网络
  -> 写清范围和禁止事项
  -> 审查完整 diff 与测试证据
  -> 再提 PR、合并或部署
  -> 停止、归档并清理不再需要的资源
```

需要本机文件、内网、设备或逐步审批时选择 Local；需要本地隔离并行时选择 worktree；需要远程仓库、后台执行和多个独立任务时选择 Cloud。入口不同，责任不变：人负责授权、审查、合规和最终副作用。

参考资料：参考/codex/10-cloud.md、参考/codex/27-automation.md、参考/codex/39-enterprise.md。动态信息以 Cloud 页面、工作区管理员策略和 OpenAI 官方文档为准。