> ## 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.

# 05-入口选择与协同

> 用决策树和协同工作流选择 CLI、IDE、桌面 App 或 Cloud，并在上下文、权限、网络、审查、并行和成本之间做出可验证的取舍。

## 用途

四种入口不是四套互相割裂的产品，而是同一个 Codex 代理的不同工作面：IDE 适合贴着代码探索和定位，CLI 适合可重复的命令与自动化，桌面 App 适合并行线程和可视化审查，Cloud 适合隔离、长时间运行和不占本机的任务。本页解决的不是“哪个入口最强”，而是“当前这件事应该在哪里开始、在哪里交接、由谁验收”。

看完本页，你应当能够：

* 用一棵决策树在几分钟内选定入口；
* 比较四种入口的上下文、权限、网络、审查、并行和成本；
* 按“IDE 探索 -> CLI `exec` 验证 -> Desktop/Cloud 协同”的方式组织一项真实任务；
* 为每次交接留下分支、diff、命令和验收证据；
* 在权限、密钥、网络和并行冲突出现时及时停下并恢复。

> 本页讨论的是工作方法，不把模型名称、套餐额度或界面按钮写死。命令和功能可能随版本变化，执行前以本地 `codex --help`、对应子命令的 `--help`、入口中的实际选项和官方文档为准。

## 先记住三个边界

### 入口改变的是工作面

IDE、CLI、桌面 App 的本地任务通常读取本机项目、使用本机工具链，并遵循项目中的 `AGENTS.md` 与本地配置。它们的主要差别是操作界面和任务编排方式：IDE 把编辑器上下文放在手边，CLI 把命令和脚本放在手边，桌面 App 把线程、Worktree 和 Review 放在手边。

Cloud 则是在 OpenAI 的隔离环境里拉取 GitHub 仓库执行。它不自动拥有你本机的未提交文件、本机 MCP、本机缓存或本机环境变量；需要通过仓库、云端环境设置和明确的任务描述提供上下文。

### 入口不等于权限

“在 IDE 里”不代表一定只读，“在 Cloud 里”也不代表一定安全。能否修改文件、能否执行命令、能否联网，取决于当前的审批、沙箱和环境设置。任何入口都要先确认：

```text theme={null}
当前目录/仓库是什么？
当前分支和已有改动是什么？
Codex 能读写哪些路径？
命令是否需要批准？网络是否开放？
这次任务允许提交、推送或创建 PR 吗？
```

### 入口不等于验收

Codex 的总结不是验收证据。验收至少包括目标文件、实际 diff、测试或构建退出码，以及没有越过授权边界。选择更方便的入口，不应减少人工审查；相反，任务越长、并行越多、权限越高，越要把交付证据写清楚。

## 入口选择决策树

按下面的顺序回答问题。遇到“是”就沿箭头继续；没有特别理由时，从最靠近代码的入口开始。

```text theme={null}
开始
  |
  | 任务必须读取或修改本机文件、本地服务、未提交改动或本地工具？
  |-- 是 --> 需要在编辑器中逐段理解、选中代码或看实时预览？
  |             |-- 是 --> IDE 扩展
  |             |-- 否 --> 需要脚本化、SSH、批量执行或机器可读输出？
  |                         |-- 是 --> CLI；一次性任务优先 codex exec
  |                         |-- 否 --> 需要同时管理多个线程、隔离 worktree 或可视化审查？
  |                                     |-- 是 --> Desktop App
  |                                     |-- 否 --> CLI 交互式或 IDE，按当前工作面选择
  |
  |-- 否 --> 仓库是否已在 GitHub，且允许在云端隔离环境中运行？
                |-- 否 --> 先在本地 CLI/IDE 准备仓库、分支和环境
                |-- 是 --> 任务是否适合离开本机并可用一句话验收？
                            |-- 否 --> 本地入口，保留本机上下文
                            |-- 是 --> 是否需要电脑关闭后继续或多个任务并行？
                                        |-- 是 --> Cloud
                                        |-- 否 --> Cloud 或本地，按数据和成本边界选择
```

### 决策树的快速解释

| 关键问题               | 优先入口                           | 原因                          |
| ------------------ | ------------------------------ | --------------------------- |
| “这段代码为什么这样写？”      | IDE                            | 打开文件、选中代码和 `@file` 能提供精确上下文 |
| “请解释整个仓库，但不要修改”    | IDE 或 CLI                      | 需要只读权限；CLI 便于保留命令记录         |
| “在 CI 中审查每次提交”     | CLI `exec`                     | 可用退出码、`--json` 或输出文件接入脚本    |
| “两个不相干任务同时做”       | Desktop App + Worktree，或 Cloud | 需要线程可见性和工作区隔离               |
| “跑一小时测试，电脑可以关”     | Cloud                          | 任务脱离本机，结束后交付 diff 或 PR      |
| “必须调用本机数据库或本地服务”   | IDE、CLI 或 Desktop Local        | Cloud 看不到本机服务，且不应暴露内部数据     |
| “只改 GitHub 上的练习仓库” | Cloud                          | 不必先在本机安装完整工具链               |

## 六个维度的比较

### 总表

| 维度    | IDE 扩展                   | CLI                        | Desktop App                       | Cloud                                |
| ----- | ------------------------ | -------------------------- | --------------------------------- | ------------------------------------ |
| 运行位置  | 本机                       | 本机、也可 SSH                  | 本机                                | OpenAI 云端隔离环境                        |
| 主要上下文 | 当前文件、选中代码、`@file`、编辑器上下文 | 当前目录、命令输出、明确引用的文件          | 项目、线程、Worktree、内置终端               | GitHub 仓库、分支/commit、云端环境、`AGENTS.md` |
| 适合的权限 | `Chat`、`Agent` 等入口内审批模式  | 沙箱与审批可用命令行参数或会话命令控制        | Local、Worktree、Cloud 模式并配合 Review | 任务通常提交后自主执行，中途不按本地节奏逐次确认             |
| 网络边界  | 本机网络策略和审批                | 本机网络策略、沙箱和审批               | 本机环境或 Cloud 模式的云端设置               | 设置脚本可联网；Agent 阶段默认断网，按环境白名单放开        |
| 审查方式  | 编辑器 diff、选中代码复核          | `/diff`、`/review`、Git diff | 可视化 Review、行级批注、按 hunk 接受或回滚      | 任务结果 diff、分支和 PR                     |
| 并行方式  | 多面板，但共享本地工作区时要小心         | 多终端或多个 Worktree            | 多线程和 Worktree 是核心能力               | 多个容器、分支天然隔离                          |
| 成本结构  | 本机资源加 Codex 用量           | 本机资源加 Codex 用量；脚本可能扩大调用次数  | 本机资源加 Codex 用量；并行会增加总用量           | Codex 用量、云端运行时间和套餐限制；失败重跑也消耗用量       |
| 最佳任务  | 探索、局部修改、前端预览             | 自动化、CI、批量检查、SSH            | 并行开发、审查、任务编排                      | 长任务、并行任务、无需本机环境的仓库任务                 |
| 主要风险  | 把过多编辑器上下文带入任务            | 脚本无人值守、路径和权限写错             | 并行线程误用 Local 互相覆盖                 | 数据出境、提示注入、云端环境不完整                    |

### 上下文：相关比更多重要

IDE 的优势是“我指给你看”：选中函数、引用 `@file`、打开相关文件，适合从症状定位到实现。CLI 的优势是“命令就是记录”：可以先运行 `git status`、测试和搜索，把输出作为后续证据。Desktop App 的上下文以线程和项目为中心，适合保存多个任务的来回讨论。Cloud 只有它实际拉取到的仓库和配置，不能假定它知道本机聊天记录或未提交改动。

建议采用“上下文最小充分集”：目标文件、接口定义、相关测试、报错输出和约束都要给；无关目录、密钥、整库历史和大段日志不要一股脑塞进去。任务很长时使用 `/compact`，任务换题时新开线程。

### 权限：先收紧，再逐步放开

| 工作阶段    | 推荐入口状态                                                   | 目的          |
| ------- | -------------------------------------------------------- | ----------- |
| 了解陌生仓库  | CLI `read-only` 或 IDE `Chat`                             | 只读、先建立模型    |
| 小范围本地修改 | IDE `Agent`、CLI `workspace-write`、Desktop Local/Worktree | 只允许项目范围内工作  |
| 多任务并行   | Desktop Worktree 或 Cloud                                 | 避免共享工作区互相覆盖 |
| 无人值守检查  | CLI `exec` 配合明确沙箱和最小目录                                   | 机器可读、限制写入范围 |
| 需要联网    | 逐项批准，Cloud 使用最小域名白名单                                     | 防止提示注入和数据外发 |

不要把 `--yolo` 或 Full Access 当作“速度开关”。它们会削弱重要的防线，只能在外部隔离、数据可丢失且任务边界明确的环境中临时使用。任务结束后恢复默认权限，并再次检查 diff。

### 网络：本地和 Cloud 是两套网络

本地入口访问的是你的网络，可能需要代理、VPN、内网权限或本地服务。Cloud 任务访问的是云端网络；浏览器能打开页面，不代表云端容器就能访问某个域名。

Cloud 的常见边界是：设置脚本阶段为安装依赖联网，Agent 阶段默认断网。确实需要访问外部服务时，从最小域名集合开始，并优先限制为 `GET`、`HEAD`、`OPTIONS`。不要因为安装依赖失败就直接选择 unrestricted；先确认缺少的域名、脚本和版本。

把 API key、密码和内部令牌放进 Secrets，而不是普通环境变量或仓库文件。即使任务看似只读，也要把 Issue、网页、README、日志和依赖输出视为可能包含提示注入的非可信内容。

### 审查：入口越自动，交付越要可见

IDE 适合边看边应用；CLI 适合用 `/diff` 和 `/review` 复核；Desktop App 适合在文件、hunk 和行级批注之间做选择；Cloud 适合先看任务 diff，再决定是否提 PR。四种入口都应保留以下证据：

```text theme={null}
目标分支或 commit
改动文件清单
关键 diff
实际执行的验证命令及退出码
未验证的假设
是否提交、推送或创建 PR
```

### 并行：隔离比“同时打开几个窗口”重要

同一目录下同时让两个代理写文件，可能出现覆盖、测试结果错位和难以解释的 diff。需要并行时：

* Desktop App 使用 Worktree，让每个线程拥有独立副本；
* CLI 用多个 Git Worktree 和多个终端；
* Cloud 让每个任务使用独立容器和分支；
* 不要让两个任务同时负责同一批文件；
* 合并前分别跑验证，合并后再跑一次集成验证。

Worktree 不会自动带上 `.gitignore` 中的 `node_modules`、`.env` 等内容。新 Worktree 需要设置脚本、依赖安装和非敏感配置；敏感配置应通过安全的本地或云端环境提供。

### 成本：算总任务成本，不只看单次响应

一次响应便宜，不代表整个任务便宜。返工、重复读库、失败重跑、并行重复安装和过高推理强度都会增加总成本。可以按以下顺序控制：

1. 先写清目标、范围、约束和验收，减少返工；
2. 用 `@file`、选中代码和测试输出缩小上下文；
3. 简单任务用较低推理强度，复杂任务再提高；
4. 长任务分成可独立验收的阶段；
5. 只有值得后台运行的任务才放 Cloud；
6. 并行前确认任务确实互不冲突；
7. 用 `/status` 或入口中的用量信息观察消耗，不把快速模式默认打开。

## 推荐协同工作流

下面是一条适合中等规模功能、缺陷修复和前端改动的默认流程：先在 IDE 探索，转到 CLI `exec` 做可重复验证，再按任务性质交给 Desktop App 或 Cloud 管理并行和长任务。它不是强制顺序；关键是每次交接都带着可验证的状态。

### 阶段一：IDE 探索与范围确认

在 IDE 中打开仓库，先不要修改。确认当前分支和工作区状态，在 Codex 中使用 `Chat` 或只读模式，提供四段信息：

```text theme={null}
目标：修复登录成功后偶发跳转空白页。
上下文：请重点查看 @src/auth/login.ts、@src/router/index.ts 和相关测试。
约束：不要改变权限校验和公开 API；先只分析，不改文件。
验收：给出根因、最小修改范围和应补的测试用例。
```

检查 Codex 是否引用了正确的文件，是否把猜测和事实区分开。若它扩大了范围，先要求列出证据，不要立即进入写入模式。

**阶段一验收：** 已确认仓库、分支、已有改动；得到根因假设和涉及文件；没有产生未审查的文件修改。

### 阶段二：IDE 小范围实现

确认方案后切换到日常 Agent 模式，只把必要文件加入上下文。让 Codex 先修改测试或实现，再说明“不要动哪些文件”。例如：

```text theme={null}
按刚才确认的最小方案实现。
只允许修改 @src/auth/login.ts 和 @tests/auth/login.test.ts。
先运行单个相关测试，失败时保留错误并说明原因；不要提交或推送。
```

在编辑器中查看并排 diff，检查错误处理、边界条件和接口兼容性。不要因为改动很小就跳过 diff。

### 阶段三：CLI `exec` 做可重复验证

实现后切到仓库根目录，用 CLI 执行不需要持续对话的检查。先观察当前状态：

```bash theme={null}
git status --short
git diff --check
```

再用只读 `exec` 复核改动：

```bash theme={null}
codex exec --sandbox read-only "审查当前未提交改动。只读取文件，按严重度列出回归风险、遗漏测试和与目标无关的改动，不要修改文件。"
```

运行项目自己的测试、类型检查、格式化或构建命令。若要把结果接入脚本，可根据本机帮助使用 `--json`；不要假定不同版本的事件字段完全一致。验证完成后记录命令和退出码。

**阶段三验收：** `git diff --check` 通过；目标测试和必要检查通过；只读审查没有高严重度问题；输出已保存或可复现。

### 阶段四：交给 Desktop App 管理并行和审阅

当任务需要多个独立方向，打开 Desktop App，为每条线建立 Worktree。例如：

| 线程 | 目标       | 允许修改              |
| -- | -------- | ----------------- |
| A  | 补登录回归测试  | `tests/auth/**`   |
| B  | 检查路由错误处理 | `src/router/**`   |
| C  | 更新测试说明   | `docs/testing/**` |

不要使用三个 Local 线程共享同一工作目录。每个线程启动时说明基线、非目标和验证命令。完成后在 Review 面板中按文件和 hunk 审查，必要时添加行级批注，让原线程小范围修正。

Desktop App 适合把“等待、切换、审查、交接”集中管理，但它不会替你解决合并冲突。每个 Worktree 独立通过测试后，才允许按顺序合并或 Handoff 回主工作目录。

### 阶段五：把长任务交给 Cloud

以下任务满足条件时，才适合 Cloud：

* 仓库已经在 GitHub，权限和可见范围已确认；
* 任务不依赖本机未提交文件、内网服务或私有本地工具；
* 任务可以用明确的 diff 和测试结果验收；
* 允许在云端拉取代码，并接受云端运行时间与用量成本。

提交前在 Cloud 环境中确认运行时、设置脚本、环境变量、Secrets 和网络策略。优先关闭 Agent 网络；确需联网时使用最小域名白名单和只读 HTTP 方法。任务描述写成“一句话能验收”的粒度：

```text theme={null}
从 main 创建独立分支。
只修改 tests/auth/test_redirect.py，为登录后空白页补一个失败复现和一个成功断言。
运行项目约定的测试命令；不要修改生产代码，不要提交包含密钥的文件。
完成后返回根因、测试命令、退出码和完整 diff，先不要自动合并。
```

云端任务完成后先看 diff，再看测试日志，最后决定是否创建 PR。不要把“任务已完成”当作“可以合并”。

## 三个实际案例

### 案例一：陌生前端项目的空白页

**问题：** 接手一个没有文档的 React 项目，点击登录后偶发白屏。

**选择：** 先用 IDE。原因是需要打开组件、选中调用链并观察路由文件；此时上下文相关性比并行更重要。

**步骤：**

1. IDE `Chat` 模式读取入口组件、登录请求、路由和错误边界；
2. 要求输出调用链、复现条件和最小修改计划；
3. 切到 Agent，只修改相关组件和回归测试；
4. 在 IDE Review 中确认没有顺手重构状态管理；
5. 用 CLI `exec` 以只读方式审查 diff，并运行前端测试和构建；
6. 若需要另一条线补测试，可在 Desktop App 的 Worktree 中单独完成。

**验收：** 正确账号进入首页，异常响应显示错误状态，原有权限校验不变，相关测试和构建退出码为 0。

**风险：** Auto Context 带入过多无关文件；本地开发服务器连接了真实后端；并行线程修改同一个路由文件。处理方式是关闭无关上下文、使用测试服务，并把同一文件归给一个线程。

### 案例二：每天审查提交并生成报告

**问题：** 每天早上审查前一天的提交，输出潜在 bug 和测试缺口。

**选择：** CLI `exec`。原因是任务输入和输出稳定、需要脚本化、可以用退出码判断失败，不需要持续的图形交互。

**示例：**

```bash theme={null}
codex exec --sandbox read-only --json \
  "审查 HEAD~1..HEAD 的改动。只读仓库，按严重度输出问题、文件位置和建议测试；不要修改、提交或推送。"
```

把 JSON 事件和最终报告写入受控目录，再由人工查看。若使用 Desktop App Automations，也要保留同样的只读边界和报告审查，不能因为定时运行就跳过检查。

**验收：** 脚本在正确仓库和分支运行；退出码可被 CI 或任务计划识别；报告包含提交范围、文件位置和证据；没有写入代码或泄露日志中的令牌。

**风险：** 无人值守脚本误用可写权限；输入的提交信息包含提示注入；报告把敏感代码复制到外部系统。处理方式是只读沙箱、固定提交范围、限制输出目录，并对外发报告做脱敏。

### 案例三：大仓库的依赖升级和长时间测试

**问题：** 升级一个 GitHub 仓库的依赖，安装、全量测试和修复可能需要很久，本机还要继续工作。

**选择：** 先在 IDE 或 CLI 确认升级范围和本地差异，再用 Cloud 执行隔离任务；若需要同时尝试两个版本，则为每个版本建立独立 Cloud 任务或 Desktop Worktree。

**步骤：**

1. 本地检查 `AGENTS.md`、包管理器、锁文件和测试命令；
2. 在 IDE `Chat` 中要求列出直接依赖、间接影响和回滚方式；
3. 把明确的分支、版本范围、禁止修改项写进 Cloud 任务；
4. 云端设置脚本只负责安装依赖，Agent 网络保持关闭，除非明确需要访问白名单域名；
5. 云端结束后审查锁文件、生产配置和测试日志；
6. 通过 PR 交给人工 Review，合并前在 CI 再跑一次。

**验收：** 依赖版本符合约束，锁文件变化可解释，全量测试和构建通过，PR 只有目标文件，回滚命令可执行。

**风险：** 云端环境与生产环境不同；设置脚本的 `export` 不会自动跨到 Agent 阶段；缓存导致旧依赖被误判为新结果。处理方式是固定运行时、把变量配置到正确的环境设置、必要时重置缓存，并在 CI 复验。

## 交接协议：换入口前写清四件事

入口之间切换时，不要只复制一句“继续做”。至少交接下面四项：

| 交接项 | 需要写什么                | 例子                       |
| --- | -------------------- | ------------------------ |
| 状态  | 当前分支、commit、是否有未提交改动 | `feature/login`，2 个文件未提交 |
| 决策  | 已确认的根因、方案和不可改变的约束    | 不改权限校验，只修错误跳转            |
| 证据  | 已运行的命令、输出和失败原因       | `npm test -- login` 通过   |
| 下一步 | 新入口要做的一个明确动作         | 审查 diff 并补边界测试           |

推荐交接模板：

```text theme={null}
项目与基线：<仓库路径或 GitHub 仓库>，基于 <分支/commit>
当前状态：<已修改文件>，<是否有未提交改动>
已确认：<根因、方案、约束>
已验证：<命令> -> <退出码/结果>
下一步：<一个明确动作>
禁止：<不允许修改、联网、提交、推送或读取的内容>
```

如果交接到 Cloud，还要补充云端环境、Secrets 是否需要、网络白名单和预期 PR 分支。若交接回本地，还要确认本机依赖、服务和未跟踪文件是否齐全。

## 验收清单

### 选择是否合理

* [ ] 入口选择由任务的上下文和运行位置决定，而不是由个人偏好决定；
* [ ] 需要本机文件或服务的任务没有误交给 Cloud；
* [ ] 需要脚本、SSH、CI 或机器可读输出的任务使用 CLI；
* [ ] 需要编辑器上下文的探索任务先在 IDE 完成；
* [ ] 需要并行时使用 Worktree 或独立云端容器；
* [ ] 成本、运行时间和用量边界已确认。

### 任务是否可交付

* [ ] 分支、commit、仓库路径和账号正确；
* [ ] diff 只包含目标文件和必要的测试/配置；
* [ ] `git diff --check` 通过；
* [ ] 格式化、类型检查、测试或构建命令有实际结果；
* [ ] 失败检查没有被忽略或用“应该没问题”替代；
* [ ] 未提交、未推送、未创建 PR 的约束得到遵守；
* [ ] 关键边界、错误路径、权限拒绝和回滚方式已检查。

### Cloud 额外验收

* [ ] GitHub 仓库和授权范围正确；
* [ ] 云端运行时、设置脚本和锁文件一致；
* [ ] Secrets 没有写入仓库、日志或普通环境变量；
* [ ] Agent 网络保持关闭，或白名单和 HTTP 方法足够具体；
* [ ] 云端 diff、测试日志和 PR 分支可追溯；
* [ ] 合并前仍在 CI 或本地干净环境复验。

## 风险处理与回滚

### 发现改错了

停止继续派发任务，保存当前 diff、错误输出和线程 ID。先判断改动里是否混入人工工作；若没有混入，可对明确的单个文件使用 `git restore -- <文件>`，否则从补丁或独立 Worktree 恢复。不要用破坏性命令覆盖同事的未提交改动。

### 发现并行冲突

暂停相关线程，分别导出两个 Worktree 的 diff，确定哪条线拥有某个文件。不要让 Codex 在冲突未解释前自动合并。解决后先在合并结果上运行针对性测试，再运行完整检查。

### 发现权限或网络过宽

立即停止任务，撤销不必要的批准，关闭 Full Access 或 unrestricted 网络。检查命令历史、输出、日志和生成文件中是否出现密钥或客户数据；必要时轮换已暴露凭据。后续任务改用只读、最小写入目录和明确白名单。

### Cloud 结果不可复现

保留任务 ID、仓库 commit、环境版本、设置脚本和测试日志。不要直接重跑很多次碰运气；先比较缓存、依赖锁文件、环境变量和网络白名单。确认差异后，再新建独立任务或重置缓存，并把原因写入 PR 说明。

## 最小可执行流程

不确定从哪里开始时，照这个顺序走：

```text theme={null}
1. 在正确仓库运行 git status --short，确认分支和已有改动。
2. IDE 只读探索，使用 @file 或选中代码，得到范围和方案。
3. IDE 小范围实现，立即查看 diff。
4. CLI 运行 git diff --check、测试和只读 codex exec 审查。
5. 需要并行则 Desktop App 使用 Worktree；需要后台运行则 Cloud 使用隔离分支。
6. 交接时写状态、决策、证据、下一步和禁止事项。
7. 人工审查最终 diff，验证通过后再决定 commit、push 或 PR。
```

> 最重要的判断不是“我喜欢哪个入口”，而是“这个入口能否提供任务所需的上下文，同时把权限、并行和验收保持在可控范围内”。先用 IDE 把问题说清楚，再用 CLI 把验证变成可重复证据，最后按运行时间和并行需要选择 Desktop App 或 Cloud，通常能得到稳定且可恢复的协作结果。

参考资料：参考/codex/01-what-is-codex.md、07-desktop-app.md、08-cli.md、09-ide.md、10-cloud.md、31-speed.md。