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

# 四种入口

> 本篇梳理 Codex 的 App、CLI、IDE 和 Cloud 四种使用入口。

# 四种入口

同一个 Codex 可以从桌面 App、CLI、IDE 扩展和 Cloud 四种入口使用。它们不是四个完全不同的 AI，而是**同一类代理能力在不同工作环境中的入口**。

读完后，你应该能够：

* 分清本地入口和云端入口；
* 根据任务是否需要本机文件、终端、编辑器或后台并行来选入口；
* 理解 Local、Worktree 和 Cloud 的基本区别；
* 知道四种入口之间哪些设置可以复用。

> 本篇参考了 `参考/codex/01-what-is-codex.md`、`参考/codex/07-desktop-app.md`、`参考/codex/08-cli.md`、`参考/codex/09-ide.md` 和 `参考/codex/10-cloud.md`。不同版本的按钮、扩展名称和功能范围可能变化，请以官方文档和本地界面为准。

## 四种入口总览

| 入口         | 代码在哪里         | 主要特点                              | 适合场景                          |
| ---------- | ------------- | --------------------------------- | ----------------------------- |
| **桌面 App** | 本机            | 图形界面、线程列表、可视化 diff、Worktree 和并行任务 | 不想频繁使用命令行，或需要同时管理多个任务         |
| **CLI**    | 本机            | 终端交互、脚本化、`exec`、SSH 和 CI 友好       | 习惯终端、需要自动化或服务器环境              |
| **IDE 扩展** | 本机            | 直接使用当前文件、选中代码和编辑器上下文              | 日常主要在 VS Code、Cursor 等编辑器中写代码 |
| **Cloud**  | OpenAI 云端隔离环境 | 连接 GitHub、后台运行、完成后交 diff 或 PR     | 长任务、并行任务、电脑不方便持续运行的任务         |

前三种入口通常读取和修改你本机上的工作区；Cloud 则使用你授权的 GitHub 仓库，在云端容器中工作。这个区别决定了它能否访问你本机的未提交文件、本地工具、私有配置和本地 MCP。

## 入口一：桌面 App

桌面 App 是一个面向并行工作的图形化工作台。参考材料把它概括为“左边栏选项目和线程，中间下指令，右边看结果”：

* **项目和线程**：管理不同代码仓库及其任务对话；
* **对话区**：查看 Codex 读取了什么、执行了什么、准备怎么做；
* **结果面板**：查看 Git diff、终端输出和预览；
* **运行模式**：通常可以在 Local、Worktree 和 Cloud 之间选择。

### Local、Worktree 和 Cloud

| 模式           | 改动位置             | 适合什么               |
| ------------ | ---------------- | ------------------ |
| **Local**    | 当前本机工作目录         | 小范围日常修改，想立刻在本机继续工作 |
| **Worktree** | 独立的 Git worktree | 同一项目开启多个任务，避免互相覆盖  |
| **Cloud**    | 云端隔离容器           | 长任务、后台任务或不想占用本机的任务 |

Worktree 的关键价值是隔离：多个任务各自在独立副本中修改，完成后你再通过 diff、合并或交接决定如何落地。它依赖 Git，并且不会自动带上 `.gitignore` 中的依赖目录或本地文件。

桌面 App 特别适合：一边修复 Bug、一边让另一个线程补测试；修改量较大时逐文件查看 diff；把常用命令保存成 Action；设置定时任务生成代码库简报。

## 入口二：CLI

CLI 是最灵活、最容易接入工程流程的入口。直接运行 `codex` 会进入交互式终端界面；需要脚本或 CI 时，可以使用非交互式的 `codex exec`。

```bash theme={null}
# 在当前目录启动交互式会话
codex

# 进入指定目录并直接给出任务
codex --cd ./my-project "先解释这个项目的结构"

# 非交互式执行,适合脚本和 CI
codex exec "审查当前改动并列出潜在问题"
```

CLI 的优势主要在于：

* 可以在没有图形界面的服务器和 SSH 环境中运行；
* 可以用 shell、脚本和 CI 组合；
* 可以精确指定工作目录、模型、沙箱和审批策略；
* 可以用结构化输出把结果交给其他程序处理。

## 入口三：IDE 扩展

IDE 扩展把 Codex 放进你正在写代码的编辑器中。参考材料特别提醒：安装时应确认发布者和扩展 ID；例如 VS Code 生态中常见的官方扩展 ID 是 `openai.chatgpt`，具体以扩展市场当前信息为准。

IDE 扩展的最大优势是直接拿到编辑器上下文：选中代码后提问、用 `@file` 引用文件、让 Auto Context 带入最近打开的文件，并在编辑器中查看和应用 diff。

```text theme={null}
请参考 @example.tsx 和 @resources.ts,给当前页面增加 Resources 区域。
先说明准备修改哪些位置,不要修改其他文件。
```

如果你大部分时间都在编辑器中读代码、选代码和审 diff，那么扩展通常是最顺手的入口。

## 入口四：Cloud

Cloud 把任务放到 OpenAI 的云端隔离环境中执行。你通常需要连接 GitHub 仓库，云端任务会拉取指定分支或提交，准备环境，运行 Codex，最后返回结果、diff 或 Pull Request。

参考材料将云端任务拆成了一个清楚的流程：

1. 连接并选择 GitHub 仓库；
2. 创建云端容器并拉取代码；
3. 运行设置脚本，安装依赖和工具；
4. 在默认受限的网络环境中执行任务；
5. 返回说明和 diff，由你决定是否提 PR、审查和合并。

Cloud 的优势是并行和脱离本机：电脑关掉后任务仍可继续，多个任务可以使用独立容器运行。但它看不到你本机没有提交到 GitHub 的文件、全局配置、本地工具和本地 MCP。云端任务通常不会像本地会话一样每一步都等待你批准，所以描述必须具体到可以验收。

```text theme={null}
在仓库根目录新建 HELLO.md,只写一行 Hello from Codex cloud.
不要修改其他文件。完成后返回改动文件列表和验证结果。
```

## 怎么选入口

| 你的需求                | 推荐入口                                    |
| ------------------- | --------------------------------------- |
| 不想碰终端，想看图形化 diff    | 桌面 App                                  |
| 要跑脚本、批量处理、SSH 或 CI  | CLI                                     |
| 正在编辑器里写代码，想直接引用选中内容 | IDE 扩展                                  |
| 电脑可以关、任务要后台运行或并行    | Cloud                                   |
| 同一个项目需要多个任务互不覆盖     | 桌面 App 的 Worktree，或 CLI 配合 Git worktree |

新手推荐顺序是：先用桌面 App 或 IDE 扩展建立体感，再学习 CLI；等需要后台并行或跨机器执行时，再使用 Cloud。

## 四种入口能否共用配置

项目级的 `AGENTS.md` 是最适合跨入口复用的规则文件。CLI、桌面 App 和 IDE 扩展也通常共享登录状态、项目规则以及部分用户配置，但具体功能取决于版本和登录方式。

要特别区分：

* **项目规则可以随仓库共享**：例如测试命令、代码约定和禁止修改的目录；
* **本机工具不会自动出现在 Cloud**：需要在云端环境中重新配置；
* **未提交的本地改动不会自动出现在 Cloud**：要显式选择带本地改动运行，或先提交并推送；
* **入口相同不代表运行位置相同**：IDE 的本地模式和 Cloud 是两种不同的执行边界。

## 小结

* 桌面 App 适合图形化审查、并行线程和 Worktree；
* CLI 适合终端、服务器、脚本和 CI；
* IDE 扩展适合直接利用编辑器上下文；
* Cloud 适合隔离、并行和后台任务，但只看得到授权的远程仓库；
* 选择入口时先看任务需要访问哪里、是否需要人在场、是否要并行。

下一篇将解释这些入口背后共同的工作模型：[代理、上下文、工具与模型](/01-认识-Codex/03-代理上下文工具与模型)。