用 Codex 桌面应用完成从计划到提交 PR 的编码任务

Codex 桌面应用可以理解为把 Codex CLI 包进了一个 IDE 外壳：左侧是项目与线程列表，中间是对话，旁边有内置终端和代码审查面板。它解决的核心问题是让编码代理的上下文活下来——关掉窗口再打开，之前积累的线程、上下文和缓存都还在，而不是像终端里那样一关就没了。它适合希望用图形界面管理多个并行任务、并且愿意把「先计划、再执行、最后验证」当成固定流程的开发者。站内也有对应的工具条目，可以先看 Codex 的说明再往下读。

需要先说明一点：Codex 一共有四种使用形态——桌面应用、VS Code 扩展、CLI，以及跑在 OpenAI 基础设施上的 Codex Cloud。本文只讲桌面应用这一种，其他形态的细节不在本文范围内。

准备工作

开始之前，先把下面几件事确认好，否则后面很多功能会卡住。

账号与套餐：Codex 的部分模型与功能受套餐限制，例如素材中提到的 Spark 模型只在 Max 套餐下可用。具体哪些模型、哪些功能在哪个套餐里，以及价格与配额，请以官网当前信息为准，本文不给出具体数字。
安装桌面应用：Codex 桌面应用是一个 Electron 应用，安装后以独立窗口运行，不依赖终端。
Git 与 GitHub：本地模式需要你的项目本身是一个 Git 仓库；云端模式需要连接 GitHub 账号，因为它的执行发生在 OpenAI 的服务器上，工作流围绕推送到 GitHub 展开。
项目目录：准备一个你愿意让代理读写的代码库。第一次使用时建议选一个不太关键的小项目，先把权限和沙箱配置摸清楚。
了解三种执行位置：本地、云端、工作树（worktree）。这三者的差别决定了任务在哪里跑、能不能关掉电脑，后面会分别说明。

操作步骤

第一步：建立项目与线程

打开应用后，左侧边栏的每一个顶层条目就是一个项目。在项目内部创建线程，每个线程对应一个代理实例。如果你用过终端里的 Codex，可以把每次执行的命令理解为一个线程，区别在于桌面应用里的线程是持久化的：硬关闭应用再重新打开，所有线程和上下文都还在，缓存也还在等待你继续。

侧边栏会同时标出每个线程是本地执行、云端执行还是工作树，这在同时推进多条任务线时很有用。建议的组织习惯是一个线程只做一件事，范围收窄，产出才干净。

第二步：选择执行模式

三种模式各有适用场景：

本地模式：任务直接在你的机器上、你的项目里运行。最简单，适合日常改动。
云端模式：执行被送到 OpenAI 的服务器。你可以发起一个任务，合上笔记本，过一段时间回来接着看结果。前提是已经连接 GitHub。
工作树模式：Codex 把当前分支克隆到一个独立的 Git worktree 里，于是你有了两个并行的本地环境。这样可以在同一份代码库上跑两个代理而互不覆盖文件。应用原生支持这种模式：侧边栏里能看到不同的工作树，在每个工作树里创建线程，并以可视化的方式管理。

一个常见的错误是让两个线程在同一个分支上改同一批文件。需要并行编辑时，用工作树把两边隔开。

第三步：选模型与推理档位

在对话里输入 /models 可以查看当前可用的全部模型。素材中提到的选项包括 GPT 5.4、Mini、Codex 模型，以及仅限 Max 套餐的 Spark（速度极快）。模型清单会随版本变化，请以应用内实际显示和官网当前信息为准。

选模型时通常看两个变量：成本与速度。Codex 还多了一个维度——推理档位。任何模型都可以把推理设为 low、medium 或 high，默认是 medium，能覆盖大多数任务。

面对大型代码库里一个棘手的 bug，把推理调到 high。
简单的文件操作或样板代码，low 就够。
所有任务都用 high，就像在高速公路上一直挂一挡：技术上能走，但既慢又浪费。

另外还有一个 /fast 模式，会把 GPT 5.4 推到更快的输出模式，代价是更高的 token 消耗。赶截止日期时值得，随手探索时不值得。

做调研的子代理可以用 Mini，主规划线程用完整模型。把算力匹配到任务复杂度上。

第四步：按四要素写提示

提示词建议围绕四个要素组织：

目标（Goal）：你要达成什么，写具体。
上下文（Context）：相关文件、目录、文档。可以用 @ 引用文件，也可以直接用自然语言描述需求，让模型自己去建立上下文。
约束（Constraints）：框架、架构、约定，以及任何无法从代码本身看出来的规则。
完成标准（Done When）：告诉代理怎样才算成功，例如「所有测试通过时完成」「迁移脚本无报错跑通时完成」。没有这一条，你就是唯一的验证层；有了它，代理可以自我修正。

无论任务大小，先进入计划模式（Shift+Tab），先计划再执行。

第五步：配置 agents.md、技能与 MCP

agents.md 是存放项目常识的地方：构建命令、PR 约定、架构决策，以及你反复对 AI 说的那些规则。判断标准很简单——如果你在重复提示同一条规则，它就该写进这个文件。

技能（Skills）是可复用的工作流。Codex 内置了技能创建器，描述你想要什么，它会生成技能。应用里还有市场，提供第三方技能与插件，例如 Sora、图像生成、文档处理、Playwright 等。技能与插件的区别在于：插件打包的不只是提示词，通常还包含 MCP 和更深的集成。

MCP（Model Context Protocol）用来让代理访问外部工具与服务，例如 Figma、数据库、Slack、基于 Playwright 的浏览器自动化。如果你在别的编码工具里用过 MCP，这里的用法一致。可以从市场安装，也可以直接让 Codex 帮你配好。

第六步：用子代理并行与隔离上下文

子代理有两个用途。一是并行处理，同时跑多个任务。二是保护上下文：如果某个任务很嘈杂、会污染主线程，就把它交给子代理，让子代理去做脏活，只把结果汇报回来。这种污染常被称为「上下文腐坏」。

这也是模型选择真正落地的地方：主线程可能需要 GPT 5.4 配 high 推理，而一个调查配色方案的子代理用 Mini 配 low 推理即可。

第七步：设置沙箱与权限

沙箱按环境配置，可选只读、默认权限、完全访问三档。设置可以按项目生效，也可以全局生效。细粒度权限规则允许你预先批准常见命令（例如 GitHub CLI、某些 bash 命令），这样代理遇到明显安全的操作时不会停下来等审批。代理能自主运行的时间越长，你获得的杠杆越大。

钩子（Hooks）在生命周期事件上触发：会话开始、工具调用前、工具调用后、提交提示词、代理停止。你可以直接让 Codex 帮你写钩子，例如「写一个工具调用后的钩子，每次代码改动后跑 lint」，让代理管理它自己的环境。

第八步：用代码审查面板与内置 Git 收尾

代码审查面板用 Cmd+Option+B 切换。它提供行内 diff、选择性暂存、回退按钮，以及让代理继续迭代的修改请求。你可以点中某一行说「这行不对，改掉」，然后看它迭代。

Git 操作是一等公民：用自动生成的信息提交、创建 PR、暂存改动、审查 diff，全部在应用内完成，不必在终端、浏览器和编辑器之间反复切换。

第九步：把重复工作交给自动化

自动化相当于给代理设定时任务：选一个项目、设一个时间表、让它跑。模板包括每周代码审查摘要、仓库维护等。在 Codex 内部跑自动化的好处是，它能复用你为这个项目积累的技能和上下文。

有一个前提要注意：本地自动化需要你的电脑保持运行。如果需要设定后完全不用管，就用云端自动化。

一个完整示例

下面把上面的步骤串成一个最小可跑通的流程：给一个已有 Git 仓库的项目加一个功能，从计划走到 PR。

1. 打开项目并新建线程。在侧边栏选中项目，新建一个线程，执行模式选本地。

2. 进入计划模式。按 Shift+Tab 切到计划模式，然后按四要素写提示：

目标：为设置页增加「导出配置为 JSON」按钮，点击后下载当前配置。
上下文：@src/pages/Settings.tsx，@src/lib/config.ts，参考 @src/lib/download.ts 里已有的下载工具函数。
约束：沿用现有 React + TypeScript 结构，不引入新依赖，样式复用现有按钮组件。
完成标准：类型检查通过、现有测试全部通过、新增一个覆盖导出内容的单元测试。
先给出计划，不要直接改代码。

3. 审阅计划。看代理列出的改动点是否合理，需要调整就直接在对话里说明，让它改计划。

4. 退出计划模式执行。确认计划后切回执行模式，让它动手。如果任务涉及大量文件读写，可以在权限设置里预先批准常用的构建与测试命令，减少中途停顿。

5. 用审查面板检查 diff。按 Cmd+Option+B 打开审查面板，逐行看改动。发现某一行不合适，点中它并说明问题，让代理迭代修改。

6. 提交并创建 PR。用内置 Git 暂存改动，让应用生成提交信息并提交，然后创建 PR。

7. 需要并行时改用工作树。如果同时还要做另一个改动，不要在同一分支上再开一个线程，而是新建工作树，在工作树里开线程，两边互不干扰。

8. 沉淀规则。如果这次你反复强调了某条约定（比如 PR 标题格式），把它写进 agents.md，下次就不用再说。

注意事项

线程会变长，上下文会退化。线程过长时用 /compact 压缩，保持上下文紧凑。
想探索分支思路时用 /fork，避免把主线程带偏。
不要跳过计划模式。大多数值得做的任务都需要事先规划。
不要在同一分支上用两个线程改同一批文件。并行编辑请用工作树。
先打磨技能，再上自动化。把技能调对了，再放进时间表。
本地自动化依赖你的电脑开机。需要完全无人值守时选云端自动化，而云端模式需要连接 GitHub。
模型、套餐、价格与配额会变化。本文提到的模型名称与套餐限制仅反映素材描述，实际可用性请以官网当前信息为准。