CX-02 Codex App 桌面工作流完整指南：把 App 当主控台

定位说明：本篇是整个 Codex 系列的主轴。后续 Commands、MCP、Skills、Plugins、Automations、Review、Cloud 都围绕这里展开。

⠀

主要来源：OpenAI Codex App Features、App Commands、Settings、Review、Automations、MCP、Skills、Plugins、CLI Slash Commands 官方文档。

---

课程信息

⠀

• 作者：老金

• GitHub：https://github.com/KimYx0207

• 公众号：老金带你玩AI

• X（Twitter）：老金带你玩AI

• 个人博客：https://aiking.dev

• 预计学时：3-4小时

• 难度等级：⭐ 零基础入门

• 更新日期：2026年10月3日

• 信息来源：OpenAI Codex App Features、Settings、Review、Automations、MCP、Skills、Plugins 官方文档

• 前置要求：已完成 CX-01 Codex App 安装与认证

---

先用 App 修一个小 Bug

⠀

先做一次能看见结果的任务，再认识整套工作台。本例要修复项目看板的进度计算：空列表显示 NaN%，应改为 0%。两条编程课程共用同一份原创材料，便于你比较操作习惯。

⠀

把练习目录交给 App

⠀

1. 在教程仓库和现有工作项目之外，新建 course-progress-lab 目录，将 进度计算练习 中的 progress.cjs 和 progress.test.cjs 复制进去。只阅读在线课程时，也可以从 Claude Code 02 的两份文件 复制代码保存；后续操作在 Codex App 中完成。

2. 在 App 的项目入口添加这个目录，核对显示的路径，创建一个 Local 任务。本例只用本地文件和 Git，不需要远程仓库或 GitHub 登录。

3. 让 Codex 分别运行 node --version 和 git --version，确认工具可用。若命令不可用，先让它解释这两份文件，准备好环境再继续。

⠀

先保存一个本地起点。官方 Review 说明要求项目位于 Git 仓库中。确认当前目录只有这两份练习文件、尚未初始化 Git 后，可以让 App 在该目录执行：

⠀

git init
git add progress.cjs progress.test.cjs
git -c user.name="Course Learner" -c user.email="[email protected]" commit -m "Start progress exercise"
git status --short

⠀

这里用的是虚构的练习提交身份，-c 只对这条命令生效，不改全局配置。提交成功后，git status --short 应没有改动列表；这份初始提交让你稍后只看到修复差异。若初始化或提交失败，先处理这个错误，再进入修改步骤。

⠀

第一轮：让它证明问题存在

⠀

发送：

⠀

先不要改文件。阅读 progress.cjs 和 progress.test.cjs，
运行 node progress.test.cjs，告诉我哪条检查失败、实际值是什么、期望值是什么。
这个样例的输入都是非负整数，已完成数不超过总数。

⠀

你应该看到空列表对应的检查失败：实际值 NaN，期望值 0。如果只是找不到文件或命令，先修正目录或运行环境，不能把这种错误当成已复现业务 Bug。

⠀

第二轮：修改，并在 Review 里对照

⠀

接着发送：

⠀

现在只修改 progress.cjs，让空列表返回 0。
保留其他百分比计算和四舍五入规则，测试文件保持原样，不加依赖。
运行 node progress.test.cjs，报告实际输出，并解释改了哪里。

⠀

在 App 的 Review / diff 面板选择 Unstaged，找到 progress.cjs。检查这次改动是否处理了空列表，并确认测试文件没有被删改。若面板没有内容，先核对项目路径和本地初始提交，再看 git status --short；不要把看不到 diff 当成没有改动。最后看任务中的执行记录：同一条测试命令应正常结束，输出 progress checks passed。

⠀

要确认的行为

正确结果

完成 2 项、共 4 项

50

没有任何任务

0

完成 4 项、共 4 项

100

完成 1 项、共 3 项

33

⠀

如果 Codex 把所有结果都改成 0，就在这次任务中指出“2 项 / 4 项应为 50”，让它继续修复；如果它修改了测试，先要求按原始材料恢复测试，再检查源码。这里练的是给出具体反馈，不必为了同一个问题另开任务。

⠀

第三轮：换一个数字，自己提任务

⠀

不复制前面的提示词，要求增加“完成 3 项、共 8 项”的检查，自己先算出结果 38。观察新增测试、运行结果和 diff 是否一致。

⠀

这次先把结果保存在练习目录。之后用真实项目练习时，沿用“给出复现条件 → 说明正确行为 → 查看改动和运行结果”的顺序；涉及合并或发布，再进入 CX-10 Review / GitHub / PR。

⠀

这一节的方法参考 OpenAI 官方最佳实践。后面的功能全景可以按需查，第一次不用把所有设置都配完。

---

📚 本课学习目标

⠀

完成本课学习后，你将能够：

⠀

2026-09-13 当前基线（App 26.908）：本章主线（Thread、Worktree、Review、Terminal、Settings）没变，26.908 加的是几处入口：悬浮 Pets 控件上可以直接快速对话，@ 带上下文、$ 选 skill；Windows 上同时按下两个 Alt 键截 Appshot；会话的 Sources 面板里能直接打开文件，预览不了的可以下载；Codex Micro 可以绑一个键把常用文本插进当前提示而不发送；宠物能在设置里恢复默认尺寸，听写会遵循已保存的主语言偏好；关闭浏览器标签时标签宽度和滚动位置也更稳了。都是加法，先学完本章主线再按需打开。

⠀

2026-06-18 App 口径：本章按 Codex App 26.609 更新。新增重点补强主控台能力：Developer mode / CDP 浏览器调试、composer /init、Migrate to Codex、使用量重置 UI、Windows Computer Use per-app controls，以及 Automations 继承所选 approval mode。读者仍然先学 Thread、Workspace、Review、Settings，再按需打开这些能力。

⠀

1. 理解App的核心模型：掌握Thread、Worktree、Review、Terminal、Settings等核心概念

2. 区分三种工作方式：清楚Local thread、Worktree thread、Cloud handoff各自的适用场景

3. 写好任务描述：用目标-范围-约束-验证-交付五要素模板描述任务

4. 掌握Review工作流：在App中查看diff、审批命令、合并改动

5. 理解Settings配置：知道模型、审批、沙盒、插件、MCP在App中的配置入口

6. 建立App全局视角：知道Commands、MCP、Skills、Plugins、Automations在App中各自的位置和关系

7. 避免常见翻车场景：不盲目给写权限、不跳过Review、不用Cloud替代本地App

8. 跑通完整的App改动流程：从任务描述到diff检查到合并提交的全流程

---

🗺️ 学习路径导航（先看这里！）

⠀

💡 根据你的情况选择学习路径：这是一篇长教程，不用全看！

⠀

路径A：快速上手（⏱️ 20分钟）

⠀

适合人群：装好了App，想快速知道怎么用

⠀

只看这些章节（其他跳过）：

⠀

✅ 先用 App 修一个小 Bug：复现、修改、在 Review 中看结果
✅ 第3部分：任务描述模板，换成你自己的项目任务
✅ 第4部分：需要更细的审阅操作时再查

⠀

这次练完能带走：一个修好的进度计算样例，以及在 App 中复现、检查和纠错的完整过程。时间按已安装、已登录且 Node.js / Git 可用估计。

---

路径B：完整学习（⏱️ 3-4小时）

⠀

适合人群：想系统掌握Codex App的全部工作流

⠀

学习顺序：从头到尾所有章节

---

路径C：问题排查（⏱️ 5分钟）

⠀

适合人群：使用App时遇到问题

⠀

直接跳到：

⠀

🔧 常见问题
🔧 第14部分：从零到 PR 的完整 App 实战

---

0. App 的核心模型

⠀

我在这篇里把 App 当主控台讲，因为 Codex 新手最需要先看见线程、终端、Review 和权限在哪里。

⠀

Codex App 可以理解为一个桌面开发主控台。它把这些能力放到同一个工作流里：

⠀

能力

App 中的意义

Thread

一条任务线。每个线程都有上下文、历史和状态

Local workspace

直接围绕当前本地目录工作

Worktree

给任务创建隔离分支/目录，降低互相覆盖风险

Review

查看 diff、文件变更、行内反馈、stage / unstage

Terminal

让 Codex 在受控环境中运行命令

Settings

模型、审批、沙盒、插件、MCP、外观、Git 等配置

Automations

周期性或后台检查任务

Plugins / Connectors

连接 GitHub、Gmail、Drive、Slack 等外部上下文

Appshots

把截图、页面状态或视觉反馈带入线程，用于 UI 复核和问题定位

Developer mode

通过受控 Chrome / Browser 通道检查性能、网络、console、DOM 和样式问题

⠀

本系列后续功能都要回到这个模型里解释。

⠀

术语表（小白必读）

⠀

第一次学 Codex App，最容易混乱的不是"按钮在哪里"，而是这些词到底在工作流里承担什么角色。先把它们分清楚，后面所有章节都会变顺。

⠀

术语

一句话解释

新手容易误解的地方

Thread

一条任务线，保存这次任务的上下文、消息、工具调用和结果

不是普通聊天记录；它会影响后续任务理解

Local workspace

当前本机项目目录

Codex 能看到什么，取决于你打开了哪个目录和权限

Worktree

Git 提供的隔离工作目录

不是备份；它仍然会产生真实代码改动

Review pane

查看 Git diff、行内反馈、stage / revert 的关口

不是装饰面板；合并前一定要看

Terminal

Codex 运行命令和展示输出的位置

命令失败不等于任务失败，但必须解释

Settings

模型、审批、沙盒、连接器、插件等配置入口

不是一次设置永远适用；不同项目风险不同

Connector / App

GitHub、Drive、Slack 等外部账号连接

授权范围要单独看，不等于本地文件权限

MCP

外部工具协议

它给 Codex 工具，不是让 Codex “更懂一切”

Skill

可复用工作流

适合固化 SOP，不适合连接实时外部系统

Automation

后台或周期任务

适合重复检查，不适合模糊大改

Cloud handoff

把任务交给云端环境继续做

Cloud 看不到你未同步的本机私有状态

⠀

把 App 想成一个“开发控制台”会更准确：Thread 管上下文，Workspace 管文件，Terminal 管命令，Review 管结果，Settings 管边界，Connectors / MCP / Skills / Automations 管扩展能力。

⠀

1. App 工作流的底层逻辑

⠀

Codex App 的核心不是"让 AI 帮你写代码"，而是把一次软件改动拆成六个可控环节：

⠀

目标输入
  -> 上下文收集
  -> 权限和工具选择
  -> 文件或命令执行
  -> Review / diff 检查
  -> 人工决定提交、继续或撤销

⠀

你每次使用 App，都在这条链路上做选择。提示词写得再漂亮，如果没有范围、权限和 Review，任务仍然容易失控；模型再强，如果它没有读到项目命令、测试方式和安全边界，也会把通用经验误当成本项目事实。

⠀

0.1 五个控制点

⠀

控制点

你要问的问题

推荐动作

目标

这次到底要解决什么问题？

用“目标-范围-约束-验证-交付”写任务

上下文

Codex 该读哪些文件？

陌生项目先只读建模

权限

是否允许写文件、跑命令、联网、调外部工具？

先保守，必要时再放开

结果

改动是否真的在预期范围内？

看 Review 面板和命令输出

收口

是继续修、撤销、提交，还是交给 Cloud？

人工做最后决定

⠀

这就是 Codex App 比普通聊天更适合开发的原因：它把“看文件、跑命令、改代码、审 diff、连接外部系统”放在同一个界面里。但这也意味着你不能只学提示词，还要学会流程控制。

⠀

0.2 一条线程的生命周期

⠀

一条健康的开发线程通常长这样：

⠀

1. 开场只读：先让 Codex 读项目，确认技术栈、命令、目录和风险。

2. 明确任务：告诉它目标、范围、不能做什么、怎么验证。

3. 允许执行：小任务可直接改，大任务先 /plan 或用 worktree。

4. 检查结果：Review 面板看文件、diff、命令输出和风险。

5. 定点反馈：用行内评论或具体文件行号让它修。

6. 收尾决策：草拟 commit / PR 描述，由人决定是否提交。

⠀

如果同一线程里开始混入无关目标，比如刚修登录又让它设计首页、再顺手接一个数据库迁移，线程会变得难以 Review。更稳的做法是：一个线程承载一个目标；新目标开新线程或新 worktree。

⠀

1.1 App 主控台不是“聊天窗口”

⠀

Codex App 的学习难点不在提示词，而在你是否把每个动作放到正确位置：

⠀

你看到的东西

你真正要判断的事

错误用法

Thread 列表

哪条任务线承载当前上下文

同一个线程里混多个目标

Prompt 输入框

任务是否有目标、范围、验证和交付

只写“帮我优化一下”

Terminal / 命令输出

命令是否按预期运行、有没有失败

只看 Codex 总结，不看输出

Review 面板

文件差异是否可接受

跳过 diff 直接提交

Settings

当前模型、审批、沙盒、工具是否匹配任务风险

所有项目都用同一套高权限配置

Apps / Connectors

外部上下文是否真的需要

为了方便授权过多服务

⠀

一句话：App 负责把“任务、文件、命令、权限、审查、外部上下文”放在同一个桌面流程里。你要学的是流程控制，不是只学几个命令。

⠀

1.2 新手每天都该用的三条安全线

⠀

1. 第一次进陌生项目，先发只读任务，不让 Codex 写文件。

2. 第一次允许写文件，只改低风险文档或单个小范围文件。

3. 每次写完都进 Review 面板看 diff，不把“Codex 说完成了”当成最终结果。

⠀

这三条比任何高级插件都重要。只要你守住它们，App 工作流会比纯 CLI 更容易控制。

⠀

2. 三种工作方式

⠀

2.1 Local thread

⠀

适合小任务和只读任务：

⠀

阅读这个项目并总结启动命令、测试命令、主要目录。不要修改文件。

⠀

优点：快，直接使用当前工作区。

⠀

风险：如果让 Codex 写文件，改动会进入当前工作区。学习阶段要盯住 Review 面板。

⠀

2.2 Worktree thread

⠀

适合功能开发、重构、风险较高的改动：

⠀

在新的 worktree 里实现登录页移动端布局修复。改完运行相关测试，最后给我 diff 摘要。

⠀

优点：隔离改动，多个任务可以并行。

⠀

注意：worktree 仍然是真实 Git 工作区。合并前要 Review。

⠀

实际创建时，先确认项目在 Git 仓库中。在新聊天输入框下选择 Worktree，选择基础分支，再发送任务。默认创建的是 detached HEAD，不会自动生成一个新分支；要长期保留或提交这项工作，使用聊天顶部的 Create branch here。需要回到本地 checkout 时用 Hand off，不要把同一分支同时 checkout 到两个 worktree。

托管 worktree 默认位于 $CODEX_HOME/worktrees，可在 Settings → Worktrees → Worktree root 调整。默认保留最近 15 个托管 worktree，永久 worktree 的生命周期另行管理；删除前会保存快照，并可从相关聊天恢复。若新目录缺少被 Git 忽略的本地配置，可在仓库根目录的 .worktreeinclude 明确列出需要复制的忽略路径；这只适用于本地 App 托管 worktree，不适用于自己用 Git 创建的目录或远程 worktree。复制前确认这些配置应当进入该任务。详见 官方 Worktrees 指南。

2.3 Cloud / Web handoff

⠀

适合云端仓库任务、长时间后台任务和 PR 工作流。App 是本地主控台，Cloud 是远程执行环境。不要把 Cloud 当成本地 App 的替代品。

⠀

2.4 三种方式怎么选

⠀

任务

推荐方式

为什么

读项目、找启动命令、解释报错

Local thread 只读

快，风险低

改一个文件或少量文档

Local thread + Review

改动小，容易检查

新功能、重构、修多个文件

Worktree thread

隔离改动，便于撤回

盯 PR、修 CI、长时间后台任务

Cloud / Web handoff

不占用本地环境

依赖本机浏览器、私有服务、桌面 App

Local thread

云端通常拿不到本机状态

⠀

判断标准不是"哪个功能更酷"，而是：执行环境能不能看到需要的文件、命令和服务；失败时你能不能快速撤销。

⠀

3. App 任务描述模板

⠀

好任务要包含五件事：

⠀

目标：修复用户资料页加载失败。
范围：只改 src/pages/profile.tsx 和 src/api/user.ts。
约束：不要改数据库 schema，不要引入新依赖。
验证：运行 npm test -- profile。
交付：展示 diff 摘要和测试结果，不要自动提交。

⠀

不要只写：

⠀

帮我修一下。

⠀

因为 Codex 不知道范围、验证方式和停止条件。

⠀

3.1 三类高质量任务模板

⠀

只读理解任务

⠀

阅读这个仓库。只总结：技术栈、启动命令、测试命令、主要目录、当前风险。不要修改文件，不要安装依赖。

⠀

小范围修复任务

⠀

目标：修复 docs/install.md 中 Windows 安装命令不一致的问题。
范围：只改 docs/install.md。
约束：不要改 README，不要新增图片，不要提交。
验证：检查文内命令前后一致。
交付：给出 diff 摘要和你检查过的命令列表。

⠀

UI / 页面反馈任务

⠀

目标：修复设置页按钮在 375px 宽度下文字溢出。
范围：只改 SettingsPage 相关组件和样式。
验证：启动本地页面，分别检查桌面和移动宽度；如能使用 App 内浏览器或截图，请把观察结果写清楚。
交付：展示 diff、截图观察结论和未覆盖风险。

⠀

3.2 不要写进任务里的东西

⠀

• 不要写 API key、cookie、token、私有账号。

• 不要让 Codex “顺手优化所有代码”。

• 不要把“自动提交、自动推送、自动发 PR”设成默认动作。

• 不要让它在没说明原因时安装新依赖。

• 不要把不确定的命令当成事实；让它先从项目文件里找证据。

⠀

4. App Review 工作流

⠀

每次 Codex 修改文件后，你都应该看 Review：

⠀

1. 看文件列表：确认只改了目标范围。

2. 看 diff：确认行为变化合理。

3. 看测试输出：确认验证真的跑过。

4. 行内指出问题：让 Codex 继续修。

5. 需要提交时再 stage / commit。

⠀

典型提示：

⠀

Review 这次 diff。重点检查是否改了范围外文件、是否缺测试、是否引入兼容性风险。

⠀

4.1 Review 面板逐项检查法

⠀

检查项

看什么

不通过时怎么处理

文件列表

是否只改了任务范围内文件

让 Codex 解释范围外改动，必要时撤掉

单文件 diff

是否有无关格式化、删除、重命名

行内指出具体片段重改

命令记录

是否真的运行验证命令

要求运行相关命令，或说明不能运行原因

生成文件

是否出现 lockfile、build output、缓存

确认是否必要，不必要就删除

安全项

是否碰到 .env、token、权限配置

立即停止并人工审查

Git 操作

是否 stage / commit / push 到正确目标

学习阶段让 Codex 只草拟，不自动执行

⠀

4.2 App 里继续修的正确说法

⠀

不要开新线程说“你刚才改错了”。在同一线程里引用具体 diff：

⠀

Review 面板里 src/pages/login.tsx 第 42 行的条件判断不对。请只改这一处，并说明为什么不会影响桌面端。

⠀

这样 Codex 能保留上下文，改动也更容易收敛。

⠀

5. App 中的 Commands

⠀

Commands 是 App 里最快的工作流入口。你可以在输入框里输入 / 查看当前可用命令。

⠀

常见类型：

⠀

类型

例子

用途

状态

/status

查看模型、工作区、审批、上下文状态

工作流

/plan、/review

计划、审查

工具

/mcp、Apps / Plugins 入口

外部能力入口

反馈

/feedback

向产品反馈问题

⠀

不同版本、实验开关和插件会改变命令列表。App 用户先输入 / 看当前列表；当前官方 App Commands 主线包括 /feedback、/goal、/mcp、/plan、/review、/status。CLI 里的 /new、/resume、/compact、/permissions 等命令可以帮助理解概念，但不能反推 App 一定有同名入口。完整讲解见 CX-03 和 CX-12。

⠀

5.1 App 命令的正确学习方式

⠀

App 命令会随版本、账号、实验开关、插件和连接器变化。本教程只把 /status、/plan、/review、/mcp 这类稳定工作流当作教学主线；其他命令必须以当前 App 输入 / 后的列表为准。

⠀

如果你想核对一个命令是否可用，按这个顺序：

⠀

1. 在 App 输入 / 看当前列表。

2. 看命令弹出的说明文字。

3. 再查官方 App Commands 文档。

4. CLI 里的命令只能辅助理解，不能反向证明 App 一定有同名入口。

⠀

6. App 中的项目指令

⠀

AGENTS.md 是 Codex 理解项目规则的核心文件。它应该写：

⠀

• 项目是什么。

• 常用命令是什么。

• 代码风格和测试要求。

• 哪些文件不要动。

• 修改后如何验证。

⠀

不要把临时任务、密钥、个人路径写进去。详见 CX-04。

⠀

7. App 中的 MCP

⠀

MCP 是外部工具协议。App 通过 MCP 使用浏览器、数据库、文档源、内部系统等工具。

⠀

App 用户应该先理解：

⠀

• MCP 不是 prompt。

• MCP server 可能带权限和数据风险。

• 连接后要在 App 或 /mcp 中确认工具是否可用。

• CLI 管理 MCP 只是辅助，不是主线。

⠀

详见 CX-05。

⠀

8. App 中的 Skills

⠀

Skills 是可复用工作流。适合把“每次都要重复说的步骤”固定下来。

⠀

例如：

⠀

• 代码审查流程。

• 发布前检查。

• 文档核对流程。

• 特定团队的写作规范。

⠀

App 中可以通过自然语言或 $skill-name 点名触发。详见 CX-06。

⠀

9. App 中的 Plugins / Connectors

⠀

Plugins 是能力包，可能包含 Skills、MCP、Apps、配置等。Connectors 是连接外部服务的入口，例如 GitHub、Google Drive、Slack、Gmail 等。

⠀

App 用户要记住：

⠀

• 安装插件不等于自动授权所有外部数据。

• 连接器需要单独登录和授权。

• 外部服务权限要按最小范围配置。

⠀

详见 CX-07。

⠀

10. App 中的 Subagents

⠀

Subagents 适合并行分析、分工改代码、独立审查。不要滥用。

⠀

适合：

⠀

• 一个 agent 查 API 文档，一个 agent 看代码实现。

• 一个 agent 改前端，一个 agent 改测试。

• 一个 agent 做实现，一个 agent 做 review。

⠀

不适合：

⠀

• 单个错别字。

• 线性的一步任务。

• 你还没定义清楚范围的大任务。

⠀

详见 CX-08。

⠀

11. App 中的 Automations

⠀

Automations 用来让 Codex 周期性或后台执行任务：

⠀

• 每天检查测试是否失败。

• 每周总结依赖更新。

• 定期检查文档是否和代码漂移。

• 监控某个 PR 或部署状态。

⠀

创建自动化前要明确：

⠀

• 运行频率。

• 工作目录。

• 是否允许写文件。

• 找到问题后通知还是自动修。

⠀

详见 CX-09。

⠀

12. App 与 GitHub / PR

⠀

App 的 Git 工作流通常是：

⠀

1. Codex 修改本地文件。

2. 你在 Review 面板检查。

3. 运行测试。

4. stage / commit。

5. 推送分支。

6. 创建 PR。

7. 必要时交给 Cloud / Web 继续处理。

⠀

GitHub / PR 详见 CX-10。

⠀

13. App 用户什么时候看 CLI / Web

⠀

你要做什么

看哪里

只用桌面 App 开发

CX-01 到 CX-10

排查 slash / MCP / config

CX-12 CLI

CI 或无头任务

CX-12 CLI

云端仓库任务 / 长跑 PR

CX-11 Web / Cloud

内部平台接 Codex

SDK / App Server 官方文档

⠀

13.1 App 能力地图：什么时候用哪一层

⠀

很多新手的问题不是"不会用某个功能"，而是把所有功能都当成同一种按钮。下面这张图可以当作整套 Codex 课程的地图：

⠀

一次性当前任务
  -> 先用自然语言或 slash command

重复出现的工作流
  -> 做成 Skill

需要外部工具或服务
  -> 用 MCP / Connector / Plugin

需要后台或周期运行
  -> 用 Automation

需要隔离并行开发
  -> 用 Worktree / Subagents

需要远程仓库长任务
  -> 用 Cloud / Web handoff

合并前判断
  -> 回到 Review / Git / PR

⠀

这样选功能，学习成本会低很多。你不需要一开始掌握所有高级能力，只要每次问一句：这件事是“当前动作、固定流程、外部工具、后台重复、并行分工、远程执行、合并审查”中的哪一种。

⠀

13.2 App 工作流反模式

⠀

反模式

看起来方便

真正风险

更稳做法

一个线程混多个目标

少开线程

上下文混乱，Review 难收口

一个目标一条线程

任务只写“优化一下”

省字

Codex 不知道边界

写目标、范围、约束、验证、交付

陌生仓库直接写

快

误读架构和命令

先只读建模

允许自动提交推送

省操作

错误进入远端

先草拟，由人确认

不看 Review

省时间

范围外改动混入

每次改完看 diff

所有项目同一权限

管理简单

高风险项目权限过大

按项目风险选 Settings

⠀

13.3 团队训练顺序

⠀

如果你要教团队使用 Codex App，不建议从 MCP、插件、Subagents 开始。更好的顺序是：

⠀

1. 第 1 天：只读线程和任务五要素。让每个人都能让 Codex 总结项目而不改文件。

2. 第 2 天：小范围写入和 Review。只改 README 或单个测试文件，练习看 diff。

3. 第 3 天：AGENTS.md 和权限基线。把项目命令、安全边界和验证方式写清楚。

4. 第 4 天：MCP / Connector 只读试跑。先读 GitHub issue 或文档，不做写操作。

5. 第 5 天：Worktree / Automations / Cloud。再进入并行、后台和远程执行。

⠀

这条路径符合新手心理：先建立控制感，再逐步放开能力。反过来，一上来讲插件、云端、自动化，容易让人觉得强大但危险，最后不敢真正用。

⠀

13.4 用内置浏览器验证一个页面

桌面 App 的内置 Browser 和你的常用浏览器使用不同的 profile，不会自动共享已登录会话。验证本地页面前，先从项目脚本确认并启动开发服务器，再在 App 的 New tab 中打开准确的 localhost 地址。你也可以在任务中提及 @Browser。

例如：“用 @Browser 打开 http://localhost:3000/settings，先复现窄屏下按钮溢出，只修改对应布局。修改后再次打开同一页面，说明是否仍能复现。”检查渲染结果时可在页面元素上添加浏览器评论，然后让 Codex 处理这些评论，并回到 Review 对照代码 diff。

需要检查网络请求、console、DOM 或性能时，到 Settings → Browser → Developer mode 启用 Enable full CDP access，再按任务授权。组织可以禁止该能力；普通页面预览不要求先开全量 CDP。CLI 和 IDE 没有这个内置 Browser，仍可使用已配置的浏览器 MCP；ChatGPT Work 网页端的托管 Browser 也不共享你本地的登录会话；它不同于 CX-11 的 Codex Cloud VM 环境，后者目前不支持 Browser / Computer Use。详见 Browser。

13.5 需要操作真实桌面应用时

在支持的地区，macOS / Windows 桌面 App 的 Work 或 Codex 可通过 Plugins → Computer Use 安装并启用插件、server 和 skill，再到 Settings → Computer use 查看允许的应用。macOS 还要按系统提示授予 Screen Recording 和 Accessibility。用 @Computer 或 @AppName 指定目标，并写清要检查的窗口与流程。

Windows Computer Use 在当前活动桌面前台运行，任务会控制鼠标和键盘；保持目标应用可见，不要同时操作同一会话。系统授权、App 内应用授权和项目的文件/命令权限是不同边界。仅验证本地 Web 页面时优先用上一节的内置浏览器；Linux App preview 不意味着同样支持整个桌面的 Computer Use。详见 Computer Use。

13.6 从手机继续主机上的任务

Remote 控制的是连接的 Mac 或 Windows 主机，代码和命令仍在主机上运行。先在主机 App 的 Settings → Connections → Control this Mac or PC 选择 Set up / Add，完成验证，再用手机扫描 QR code，确认同一个 ChatGPT 账号和 workspace。iOS 当前从 Codex 进入；仍显示 Remote 的客户端就使用该入口。Android 和跨桌面设备控制按实际 rollout 与 workspace 设置核对。

连接后可以从手机选项目、发任务、补充指令、查看 diff 和处理审批。主机必须保持开机、联网、App 运行；睡眠或关闭 App 会中断访问。任务使用主机的文件、工具、连接和权限，不会因为从手机发起就变成 Codex Cloud。Windows Computer Use 还需要主机会话解锁，并为任务保留前台桌面。

项目已在 SSH 主机时，先确认普通 SSH 能连上、远程登录 shell 的 PATH 中有已安装并认证的 Codex，再从 App Settings → Connections 添加主机和项目。跨主机 Hand off 要求目标保存同一个 Git 仓库项目；该操作不能把聊天直接 Hand off 到 Codex Cloud 环境。详见 Remote connections。

Remote 的 iPad 查看方式与连接排障

2026 年 9 月 23 日的 iOS 1.2026.258 公告加入了 iPad 横屏分栏：从 Codex 打开已连接主机上的任务时，任务列表可留在旁边，便于切换和查看当前任务。该版还支持浏览嵌套 Git 仓库中的改动。打开任务的更改文件和 diff 后，先确认文件属于父仓库还是嵌套仓库，再决定提交范围；查看支持不代表两层仓库会自动合成一次提交。

配对失败时，先更新手机与主机 App，核对两端账号和 workspace，并检查设备的日期、时间与时区是否准确；设备时钟错误是该公告明确修复的一类原因。SSH 项目连不上时，先在运行 App 的主机确认普通 SSH 可以连接，再检查远程用户的登录 shell 是否能找到已安装并认证的 codex；Mac / Linux 的 SSH 连接问题也是该版修复范围。回到 Settings → Connections 重新连接并查看错误，仍失败时按具体错误排障，不通过关闭认证或公开 app-server 端口绕过。依据：9 月 23 日移动端发布记录、Remote connections。

13.7 需要使用日常浏览器的登录状态时

内置 Browser 使用独立 profile。若任务需要你日常浏览器里已经登录的网站，在桌面 App 的 Settings → Computer Use 选择浏览器，按提示安装插件和扩展，再确认显示 Manage。当前支持 Chrome、Edge、Brave、Opera、Vivaldi；Opera 没有 side chat，其任务从桌面 App 发起。

使用安装扩展的那个浏览器 profile，在 Work 或 Codex 聊天里用 @Chrome / @Edge 等选中浏览器，也可提及已打开标签页。第一次使用新站点时按当前任务选择一次允许或站点允许；在浏览器旁的 Manage 查看允许/禁止域名。浏览器扩展安装权限和每次任务的网站许可不同，不要把安装扩展当作所有网站均已允许。详见 Browser extension。

14. 从零到 PR 的完整 App 实战

⠀

这一节是把前面的概念串起来。建议你拿一个非生产仓库练一遍。

⠀

14.1 第一步：只读建模

⠀

阅读这个项目，只输出：技术栈、启动命令、测试命令、主要目录、可能需要写进 AGENTS.md 的规则。不要修改文件。

⠀

你应该看到：

⠀

• Codex 没有写文件。

• 输出里能指出命令来自哪个文件，例如 package.json、README、Makefile。

• 没有把不存在的命令编出来。

⠀

14.2 第二步：小范围修改

⠀

目标：修正 README 中一处过时命令。
范围：只改 README.md。
约束：不要改版本号，不要重排整篇文档，不要提交。
验证：确认 README 中同类命令写法一致。
交付：展示 diff 摘要。

⠀

你应该看到：

⠀

• Review 里只有 README。

• 没有格式化整篇文件。

• Codex 能说明为什么改这一行。

⠀

14.3 第三步：让 Codex 自审一次

⠀

/review 重点检查这次改动是否超出范围、是否引入错误命令、是否需要更新其他文档。

⠀

如果当前 App 没有 /review，就用自然语言：

⠀

请审查当前 diff。只报告问题和风险，不要继续修改。

⠀

14.4 第四步：人工决定 Git 操作

⠀

学习阶段建议你让 Codex 只草拟：

⠀

根据当前 diff 写一个 commit message 和 PR 描述。不要执行 git commit，不要 push。

⠀

你确认无误后再决定是否提交。这样可以保留人的最后控制权。

⠀

15. 团队落地 Playbook：从一个人会用到一组人会协作

⠀

Codex App 真正进入团队，不是每个人都能打开 App 就结束了。团队要统一的是工作方式：什么时候只读、什么时候写、什么时候用 worktree、什么时候交给 Cloud、什么时候必须回到 Review。

⠀

15.1 第一周训练计划

⠀

天数

训练主题

练习任务

重点观察

Day 1

只读建模

让 Codex 总结项目技术栈、命令、主要目录

是否编造命令，是否改文件

Day 2

小范围写入

只改 README 一行过时命令

Review 面板是否只出现目标文件

Day 3

任务五要素

把“优化登录页”改写成目标、范围、约束、验证、交付

任务是否能独立执行

Day 4

AGENTS.md

给仓库写最小项目规则

新线程是否能复述规则

Day 5

Review 收口

对一个真实小 diff 做 /review 和人工 Review

是否能区分 P0/P1/P2

⠀

这一周不要急着教 MCP、Plugins、Automations。先让团队形成基本肌肉记忆：先读、再写、看 diff、跑验证、再决定提交。

⠀

15.2 团队任务模板库

⠀

把常用任务模板放进团队文档或 AGENTS.md 引用文件里，会比每个人临时发挥更稳。

⠀

只读理解模板

⠀

阅读这个项目，只输出：
1. 项目用途
2. 技术栈
3. 安装、测试、lint、build 命令及来源
4. 主要目录
5. 不应随意修改的文件或目录
不要修改文件，不要安装依赖。

⠀

小修模板

⠀

目标：[具体问题]
范围：只改 [文件/目录]
约束：不要改 [排除项]，不要新增依赖，不要提交。
验证：运行 [命令]；如果不能运行，说明原因。
交付：展示 diff 摘要、验证结果、剩余风险。

⠀

大改计划模板

⠀

/plan

目标：[大目标]
范围：[允许读写的模块]
约束：[不改什么，不做什么外部动作]
请先只读分析，输出：
1. 需要读的文件
2. 两种可选方案
3. 风险和回滚方式
4. 建议验证命令
5. 下一步是否建议使用 worktree
不要修改文件。

⠀

PR 收口模板

⠀

基于当前 diff 草拟 PR 描述，包含 Summary、Verification、Risk。
Verification 只写真实运行过的命令；未运行的命令要说明原因。
不要创建 PR，不要 push。

⠀

15.3 团队默认边界

⠀

动作

默认策略

什么时候放开

读项目文件

允许

敏感目录例外

修改普通源码

允许在明确范围内

大改用 worktree

修改依赖 / lockfile

先计划

任务明确且有验证

读取 .env*

默认拒绝

极少数人工确认场景

删除文件

先列清单

人工确认后小范围执行

提交 / push

学习阶段只草拟

团队成熟后按规则放开

外部服务写操作

默认拒绝

connector scope 明确且 PR/评论目标清楚

⠀

团队边界不需要一开始完美，但要写下来。写下来之后，Codex、导师、新成员才有共同参照。

⠀

15.4 经理和 Tech Lead 怎么看 Codex 产出

⠀

管理者不用盯每一行代码，但要盯四个信号：

⠀

1. 任务是否被拆小：一个 Codex 线程不应该承载半个月的模糊大目标。

2. Review 是否真实发生：有没有看 diff、测试、风险，而不是只看总结。

3. 验证是否对应改动：跑了相关测试，还是只跑了无关命令。

4. 权限是否按项目区分：陌生仓库、生产相关任务、高风险外部服务不能和普通文档小修同权限。

⠀

如果团队发现 Codex 经常“越修越大”，通常不是模型突然变差，而是任务边界、项目规则和 Review 纪律没有建立。

⠀

常见问题

⠀

Q1：App 是不是只能聊天？

⠀

不是。App 是本地开发主控台，核心是线程、文件改动、Review、终端、插件、自动化。

⠀

Q2：所有功能都要学吗？

⠀

不需要。先掌握 Thread、Review、Commands、AGENTS.md，再按需要学 MCP、Skills、Plugins、Automations。

⠀

Q3：App 中看到的命令和 CLI 一样吗？

⠀

不一定。先在当前 App 输入 /，查看命令补全和每项说明，再对照官方文档。CLI 能辅助核对，但两种界面的命令列表不保证相同。

---

16. App 桌面工作流的完整操作系统

⠀

Codex App 不是一个聊天框，而是一套围绕项目、线程、终端、Review、权限和外部连接组织起来的桌面工作台。你可以把它理解为 6 个区域：

⠀

区域

作用

新手常见错误

Project

选定工作边界

打开太大的目录

Thread

保留任务上下文

一个线程塞太多目标

Composer

写任务和权限选择

prompt 太泛

Terminal

运行和观察命令

忽略终端输出

Review

看 Git diff 和评论

不分 diff 来源

Sidebar / panes

看任务、自动化、产物

只盯最终回答

⠀

成熟的 App 工作流不是"发一句话等结果"，而是不断在这 6 个区域之间切换：描述目标、看执行、读终端、看 diff、给反馈、再收窄。

⠀

16.1 一次 App 任务的推荐节奏

⠀

任务前：
  说明目标、范围、不能做什么

执行中：
  看计划、看终端、必要时补充上下文

执行后：
  看 last turn changes
  看 uncommitted changes
  跑必要命令
  留 inline comments
  决定保留、继续修或丢弃

⠀

16.2 App 用户的三个基本动作

⠀

动作

例子

目的

收窄

“只改 README”

控制 diff

追证据

“你运行了什么命令？”

避免只看结论

反向解释

“根据 diff 解释你做了什么”

检查是否偏题

⠀

这三个动作比记住很多功能更重要。

⠀

17. 线程设计：不要把一个线程用成杂物间

⠀

线程是 App 的核心单位。线程越清楚，Codex 越容易保持方向。

⠀

17.1 适合放在同一线程的内容

⠀

- 同一个 bug 的定位、修复和 review
- 同一个 PR 评论回合
- 同一个文档页面的修改
- 同一次发布检查
- 同一条 automation 的设计和调试

⠀

17.2 应该新开线程的内容

⠀

- 从 bug 修复跳到新功能设计
- 从代码修改跳到企业治理讨论
- 从本地任务跳到 Cloud 环境配置
- 从一个 PR 跳到另一个 PR
- 从只读研究跳到写入执行，且范围变大

⠀

17.3 线程命名习惯

⠀

如果 App 支持显示或编辑线程标题，建议用结果导向命名：

⠀

Fix checkout retry timeout
Review PR #128 auth redirect
Draft AGENTS.md for mobile app
Investigate docs drift in onboarding guide

⠀

不要命名成：

⠀

Codex test
Help me
看看这个
今天的任务

⠀

线程标题是未来你找回上下文的入口。

⠀

18. App 与集成终端：让 Codex 看见真实反馈

⠀

集成终端的价值不只是方便。它让你在同一个工作台里运行命令，再让 Codex 基于真实输出继续工作。

⠀

18.1 终端协作模式

⠀

我会先运行测试。
请等我把终端输出留在这里后，再帮我分析。
不要猜测失败原因。

⠀

然后你运行：

⠀

npm test

⠀

再问：

⠀

请读取当前终端输出。
先总结失败测试，再判断最可能的根因。
不要修改文件。

⠀

这比让 Codex 直接猜“测试为什么失败”可靠得多。

⠀

18.2 终端输出太长怎么办

⠀

终端输出很长。
请只关注：
1. 第一个失败的测试
2. 最靠近 root cause 的错误
3. 和当前 diff 有关的文件
4. 下一步最小排查命令

⠀

18.3 命令运行权交给谁

⠀

情况

建议

安装依赖

人先看命令，必要时批准

运行测试

可让 Codex 执行，也可人执行

Git commit / push

人决定

删除文件

人先确认

项目外目录写入

尽量避免

⠀

App 的好工作流不是所有命令都让 Codex 代跑，而是让命令和解释形成闭环。

⠀

19. App 任务库：从小到大的 20 个练习

⠀

这组任务可以作为课程练习。它们从只读到写入，从单文件到跨模块。

⠀

19.1 只读任务

⠀

请只读总结这个项目的目录结构。
不要修改文件。
输出适合新同事阅读的项目地图。

⠀

请只读分析 package.json。
告诉我开发、测试、构建相关命令分别是什么。
不要运行命令。

⠀

请只读找出项目里最可能需要 AGENTS.md 说明的规则。

⠀

请只读比较 README 和 package.json 是否有不一致的命令说明。

⠀

请只读解释当前 Git 状态，告诉我哪些改动可能不是本轮产生的。

⠀

19.2 小写入任务

⠀

请只修改 README 的快速开始部分，使它和 package.json 脚本一致。
不要改代码。
完成后说明 Review 面板应该看哪里。

⠀

请给 docs/setup.md 增加 Windows PowerShell 注意事项。
不要添加空白素材提示。

⠀

请把 CONTRIBUTING.md 中过期的测试命令更新为当前 package.json 里的脚本。

⠀

请在 AGENTS.md 中增加项目常用命令草稿。
先根据仓库文件推断，不确定的地方标注。

⠀

请修复一个明显的 Markdown 链接错误。
只改相关文档文件。

⠀

19.3 中等任务

⠀

请根据当前失败测试定位最小修复。
先解释根因，再修改文件。
不要重构无关代码。

⠀

请把这个 UI 文案错误修掉。
只改显示文案和对应测试。

⠀

请根据 PR 评论修复第一条明确 bug。
不要处理其它评论。

⠀

请补一个 regression test 覆盖刚才发现的错误分支。
先写测试，再做最小实现。

⠀

请把一个重复的小 helper 抽出来。
只在两个调用点使用，不扩大重构。

⠀

19.4 进阶任务

⠀

请先用只读方式评估这个任务是否适合 worktree。
如果适合，说明 worktree 的价值和回流方式。

⠀

请把这个模糊需求拆成 3 个小任务。
每个任务都要有可编辑文件范围和风险说明。

⠀

请做一次定向 review：
只看安全、边界条件和缺失测试。
不要评价纯风格问题。

⠀

请把这个本地问题整理成 Cloud handoff 包。
不要修改文件。

⠀

请设计一个 Automation prompt，用于每周检查 docs 漂移。
默认只读。

⠀

20. App 反模式详解

⠀

20.1 “全都帮我优化一下”

⠀

问题：

⠀

帮我把这个项目优化一下。

⠀

这个任务没有目标、范围、优先级和停止条件。更好的写法：

⠀

请只读分析当前项目的 README 和 package.json。
找出新手安装流程里最容易失败的 3 个点。
不要修改文件。

⠀

20.2 “先改了再说”

⠀

问题：

⠀

你看着改，改好就行。

⠀

这会让 Codex 猜你的偏好。更好的写法：

⠀

请先给我一个最小修改计划。
计划里列出会改哪些文件、为什么改。
我确认后再执行。

⠀

20.3 “把所有评论一次修完”

⠀

问题：

⠀

把 PR 评论都处理掉。

⠀

更好的写法：

⠀

请先把 PR 评论分组。
只处理可以直接修复且风险低的一组。
需要产品判断或兼容性判断的评论先列出来。

⠀

20.4 “测试失败就大改”

⠀

问题是把一个失败当成重构理由。更好的写法：

⠀

请定位第一个失败测试的根因。
优先做最小修复。
如果你认为需要重构，请先说明为什么小修不够。

⠀

21. 跨岗位协作：让 App 输出能被别人接住

⠀

Codex App 的一个优势是：它能把代码改动、终端输出、Review diff 和任务摘要放在同一个工作台里。工程师不必把所有上下文重新口头解释一遍，可以让 Codex 把同一份 diff 改写成不同人能接住的材料。

⠀

21.1 给产品同事看的解释

⠀

请根据当前 diff，用产品语言解释用户会感知到什么变化。
不要讨论代码实现细节。
如果用户无感，也请说明为什么。

⠀

21.2 给测试同事看的手测路径

⠀

请根据当前改动列出最该手测的 5 条路径。
按风险排序。
不要写自动化测试，先给手测清单。

⠀

21.3 给工程负责人看的拆分建议

⠀

请评估这个改动是否适合拆成多个 PR。
给出拆分建议、每个 PR 的风险和依赖关系。
不要修改文件。

⠀

21.4 给文档或运营同事看的变更摘要

⠀

请根据当前 diff 判断是否需要更新 README、用户文档、发布说明或内部 FAQ。
只输出建议和对应原因，不要修改文件。

⠀

22. App 工作流复盘模板

⠀

每次完成一个任务后，用 3 分钟复盘，会让团队进步很快。

⠀

# Codex App Task Review

## Task

本次任务是什么？

## Scope

实际改了哪些文件？

## Evidence

运行了哪些命令？看了哪些输出？

## Review

Review 面板里发现了什么？

## Next

下次同类任务要怎样写 prompt 更清楚？

⠀

这个模板不是给外部评审看的，而是帮助学习者把一次 App 使用转化成下一次更好的任务描述。

⠀

23. 大型综合工坊：用 App 完成一个小型 PR 回合

⠀

这个工坊把 App 的核心能力串起来：线程、终端、Review、inline comments、GitHub PR context、任务收窄。

⠀

23.1 工坊任务背景

⠀

假设项目里 README 的启动命令过期，PR reviewer 也指出文档和脚本不一致。你要用 Codex App 完成一次小修。

⠀

23.2 第一步：建立线程边界

⠀

本线程只处理 README 启动命令和 package.json 脚本不一致的问题。
不要改代码。
不要改 lockfile。
不要处理其它文档问题。
请先只读分析 README 和 package.json，告诉我计划。

⠀

23.3 第二步：确认计划

⠀

Codex 给出计划后，不要直接说“继续”。更好的确认：

⠀

按你的计划执行，但只改 README。
如果你发现还需要改其它文件，先停下来告诉我原因。

⠀

23.4 第三步：看 Review

⠀

Prompt：

⠀

请根据 last turn changes 解释刚才的 diff。
只解释事实，不要继续修改。

⠀

人工检查：

⠀

- README 是否只改了目标段落。
- 命令是否和 package.json 一致。
- 有没有顺手改格式。
- 有没有新增无关内容。

⠀

23.5 第四步：用 inline comment 精修

⠀

你可以在具体行留言：

⠀

这条命令缺少 Windows PowerShell 说明，请补一句但不要扩展成新章节。

⠀

然后在线程里说：

⠀

请处理我在 Review 面板里的 inline comment。
保持 README 改动范围不变。

⠀

23.6 第五步：准备 PR 摘要

⠀

请根据当前 diff 草拟 PR 描述。
包括 Summary、Verification、Risk。
不要提交，不要推送。

⠀

示例输出：

⠀

## Summary

- Update README quickstart command to match package scripts.
- Add a short PowerShell note for Windows users.

## Verification

- Compared README commands with package.json scripts.
- No code files changed.

## Risk

- Low. Documentation-only update.

⠀

24. App 里的“人机分工”实战

⠀

24.1 人负责意图

⠀

我要解决什么问题？
哪些文件可以改？
哪些文件不能改？
什么情况下需要停下来问我？

⠀

24.2 Codex 负责推进

⠀

读取上下文。
提出计划。
执行小范围修改。
解释 diff。
根据反馈修正。

⠀

24.3 人负责最后判断

⠀

是否保留 diff。
是否提交。
是否推送。
是否回复外部评论。
是否扩大范围。

⠀

24.4 分工 prompt

⠀

这次任务中，你负责分析和执行小范围修改。
我负责决定是否提交和是否扩大范围。
如果你遇到需要产品判断、权限扩大、外部写操作或大重构的情况，请停下来问我。

⠀

25. App 工作流中的上下文管理

⠀

线程越长，越需要管理上下文。

⠀

25.1 什么时候总结

⠀

- 任务进入第二天。
- 线程已经处理多个阶段。
- 你准备开新线程继续。
- 要把任务交给 Cloud。
- 要让 Automation 后续跟进。

⠀

25.2 线程总结 prompt

⠀

请总结当前线程，方便我开新线程继续。
包括：
1. 原始目标
2. 已经做的事
3. 修改过的文件
4. 运行过的命令
5. 剩余问题
6. 下一步建议

⠀

25.3 新线程接续 prompt

⠀

下面是上一个 Codex App 线程的总结。
请先复述你理解的目标和剩余问题。
不要立即修改文件。

⠀

这能防止新线程丢失意图。

⠀

26. App 与非代码产物

⠀

Codex App 可以帮助处理文档、表格、演示文稿和 PDF 等产物。课程里要提醒：非代码产物也需要清楚输入和检查方式。

⠀

26.1 文档任务 prompt

⠀

请把这份 Markdown 文档整理成更适合新人阅读的结构。
保持事实不变。
不要新增图片提示。
输出前说明你改了哪些标题和段落。

⠀

26.2 表格任务 prompt

⠀

请根据这个 CSV 生成一个汇总表。
列出：
- 总数
- 按状态分组
- 异常项
请保存为新的 Markdown 表格，不要覆盖原始 CSV。

⠀

26.3 演示任务 prompt

⠀

请根据这份课程大纲生成 10 页幻灯片内容草稿。
每页包含标题、要点和演示备注。
不要生成空白图片提示。

⠀

27. App 进阶 FAQ

⠀

Q1：一个线程能不能长期用下去？

⠀

可以，但不建议一个线程承载所有项目事务。长期线程适合一个持续目标；主题变化明显时，新开线程并带上总结更清楚。

⠀

Q2：Codex 执行中我能打断吗？

⠀

可以。如果你发现方向错了，直接发新指令收窄。比如“先停，不要继续修改。请汇报已经改了什么。”越早打断，越容易控制 diff。

⠀

Q3：App 里的终端输出 Codex 都能看到吗？

⠀

它可以读取当前线程相关终端输出，但你仍然要明确让它看哪段输出、关注什么错误。不要假设它会自动理解所有终端历史。

⠀

Q4：App 和 IDE Extension 同时使用会不会混乱？

⠀

它们可以同步上下文，但学习阶段建议先在 App 里完成完整闭环。等你理解线程、Review 和终端后，再使用 IDE context 提升效率。

⠀

Q5：什么时候应该改用 Cloud？

⠀

当任务可复现、依赖明确、适合远端容器执行，或者你想把明确 issue 交给 Cloud 做分支修复时。需要本地登录态、桌面 GUI 或未提交草稿时，优先 App。

⠀

28. App 工作台案例库：从一天工作流看 Codex 怎么嵌进去

⠀

28.1 上午：只读进入状态

⠀

请只读总结当前项目今天最值得关注的状态。
读取：
- git status
- 最近提交
- README 或 AGENTS.md 中的项目命令
- 当前终端输出如果有

输出：
- 当前工作区状态
- 可能需要先处理的问题
- 今天适合 Codex 参与的 3 个小任务

⠀

这个任务适合每天开始工作时使用。它不要求 Codex 改任何东西，只让它帮助你恢复上下文。

⠀

28.2 上午中段：处理一个小 bug

⠀

我想处理一个小 bug：保存设置后按钮没有恢复可点击状态。
请先只读定位可能文件。
不要修改文件。
输出：
- 相关文件候选
- 需要确认的状态流
- 建议最小修复步骤

⠀

确认后：

⠀

请只做最小修复。
不要重构设置页面。
如果需要改测试，先说明应该补哪条。

⠀

28.3 午后：Review 和整理

⠀

请根据当前 diff 写一个 review-oriented summary。
包括：
1. 改动意图
2. 主要文件
3. 用户可见变化
4. 已经运行或应该运行的命令
5. 还需要人工看的风险

⠀

这比让 Codex 写“工作总结”更有用，因为它直接服务 PR 和 Review。

⠀

28.4 下班前：收束线程

⠀

请总结这个线程，方便我明天继续。
包括：
- 已完成
- 未完成
- 当前 diff 状态
- 不要忘记的风险
- 明天第一步建议

⠀

App 工作流的核心是“收束”。不收束的线程第二天会变成上下文负担。

⠀

29. App 工作流成熟度：从会用到用稳

⠀

29.1 初级阶段

⠀

表现：

⠀

- 能打开项目。
- 能问问题。
- 能做小改。
- 会看 Review。

⠀

常见问题：

⠀

- prompt 太大。
- 不知道何时停。
- 不看终端输出。
- 不区分 last turn 和全部 diff。

⠀

29.2 中级阶段

⠀

表现：

⠀

- 会先 plan。
- 会写边界。
- 会用 inline comments。
- 会让 Codex 反向解释 diff。
- 会把 Cloud、Automation、Skills 放到合适位置。

⠀

29.3 高级阶段

⠀

表现：

⠀

- 会给团队写 AGENTS.md。
- 会设计可复用 Skill。
- 会判断什么时候开 subagents。
- 会把 App Review 嵌入 PR 流程。
- 会把失败经验写进团队模板。

⠀

29.4 团队阶段

⠀

表现：

⠀

- 团队有统一第一条 prompt。
- 每个仓库有项目基线。
- Review 和 Git 操作边界清楚。
- 自动化有 owner。
- 外部能力有登记。

⠀

30. App 工作流练习：把同一个 diff 讲清楚

⠀

同一个 diff 可以有多种解释方式。练习的重点不是给每种岗位固定模板，而是学会根据接收者的下一步行动改写信息。

⠀

30.1 用户影响版

⠀

请根据当前 diff，用产品语言解释这个改动。
只回答：
1. 用户会看到什么
2. 用户不会看到什么
3. 是否需要更新 release note
4. 是否需要产品确认

⠀

30.2 手测清单版

⠀

请根据当前 diff 生成手测建议。
按风险排序。
每条包括前置条件、操作步骤和预期结果。
不要写自动化代码。

⠀

30.3 拆 PR 版

⠀

请评估当前任务是否已经超出原始范围。
把 diff 分成：
- 原目标内
- 相关但可拆分
- 不应该在本次提交里

⠀

30.4 文档同步版

⠀

请检查当前代码改动是否需要同步 README、docs 或示例。
只给建议，不修改文件。

⠀

这些练习能让非工程角色也参与 Codex App 工作流，而不是把它当成只有程序员能用的工具。

⠀

31. App 长案例：一天里三次使用 Codex，但每次目的不同

⠀

成熟的 App 工作流不是“一整天都让 Codex 写代码”。更真实的一天通常包含三类使用：早上梳理、下午执行、傍晚收口。

⠀

31.1 早上：把模糊任务变成可做任务

⠀

原始任务：

⠀

今天把登录体验优化一下。

⠀

不要直接执行。先让 Codex 帮你收窄：

⠀

我今天想改登录体验，但任务还很模糊。

请先只读分析项目里登录相关的入口、组件、测试和文档。
输出：
1. 可以在 1 天内完成的小任务候选。
2. 每个候选的风险。
3. 哪个最适合先做。
4. 需要我确认的问题。

不要修改文件。

⠀

Codex 可能给出：

⠀

候选 A：优化错误提示文案。
候选 B：保留登录前目标页面 redirect。
候选 C：重构 auth form 组件。

⠀

这时你选择 B，因为它有明确行为和测试。第二轮 prompt：

⠀

选择候选 B：保留登录前目标页面 redirect。

请制定最小修复计划。
要求：
1. 列出要读的文件。
2. 列出可能要改的文件。
3. 说明测试策略。
4. 不要开始修改。

⠀

31.2 下午：只改最小闭环

⠀

确认计划后再写：

⠀

按刚才计划执行最小修复。

边界：
1. 只处理登录前目标页面 redirect。
2. 不重构 auth form。
3. 不改 toast 样式。
4. 如果需要新增文件，先说明原因。
5. 修改后运行相关测试。

⠀

执行过程中，如果 Codex 想扩大范围，可以这样拉回来：

⠀

请暂停扩展。
重新对照任务目标：
只处理 redirect 保留。
把当前 diff 分成“目标内”和“目标外”。
不要继续写代码。

⠀

31.3 傍晚：把结果变成 PR 材料

⠀

不要只问“总结一下”。让 App 输出可进入 PR 的材料：

⠀

请基于当前 diff 写 PR 材料。

输出：
1. Summary：3 条以内。
2. User Impact：用户行为变化。
3. Verification：只写实际运行过的命令。
4. Risk：需要人工确认的地方。
5. Follow-up：不在本 PR 处理的事项。

⠀

再用 Review 面板读一次 diff：

⠀

请只读审查当前 diff。
重点看：
1. 是否只处理 redirect。
2. 是否有无关 UI 或样式改动。
3. 测试是否覆盖失败路径。
4. PR 描述是否有夸大。

⠀

这个一天案例的重点是节奏：早上不急着写，下午不扩大范围，傍晚不跳过 Review。Codex App 的优势不只是“能改代码”，而是能把任务从模糊、执行、审查到交付都放在一个可回看的线程里。

⠀

32. App 失控恢复：线程变乱以后怎么救回来

⠀

线程用久了会变乱：目标变了、文件多了、测试失败混进来、用户又插入新想法。不要在同一条混乱线程里继续加要求。先让 Codex 总结现场。

⠀

请暂停实现，整理当前线程状态。

输出：
1. 原始目标是什么。
2. 当前已经做了什么。
3. 哪些新需求后来加入。
4. 当前 diff 涉及哪些文件。
5. 哪些问题应该另开线程或另开 PR。

不要修改文件。

⠀

如果目标已经变成两个任务：

⠀

请把当前线程拆成两个后续任务：
任务 A：完成 auth redirect 修复。
任务 B：处理 toast 样式整理。

对每个任务输出：
1. 目标。
2. 文件范围。
3. 验证方式。
4. 是否可以从当前 diff 中保留部分改动。

⠀

然后选择一个继续：

⠀

本线程只继续任务 A。
请忽略任务 B，除非它影响任务 A。
先只读确认任务 A 的剩余步骤。

⠀

这种恢复能力很重要。App 线程不是越长越好，长线程如果没有阶段性收口，会让 Codex 记住太多过期意图。会暂停、整理、拆分，才是真正会用 App。

⠀

📝 总结与检查清单

⠀

完成本课后，请确认以下所有项：

⠀

⠀

全部勾选后即掌握 Codex App 核心工作流。

---

附录

⠀

A. App核心概念速查

⠀

概念

一句话解释

Thread

一条任务线，包含上下文、历史和状态

Local thread

直接在当前工作区执行的任务线

Worktree thread

在隔离Git分支/目录中执行的任务线

Cloud handoff

将任务交给云端执行的接力模式

Review面板

查看diff、文件变更、行内反馈的关口

Settings

模型、审批、沙盒、插件、MCP等配置入口

⠀

B. 任务描述模板

⠀

目标：[你要达到什么效果]
范围：[只改哪些文件/目录]
约束：[不能做什么]
验证：[怎么确认改对了]
交付：[期望的输出形式]

⠀

C. 推荐学习资源

⠀

• Codex App 官方文档：https://developers.openai.com/codex

• Codex App Review 官方文档：https://developers.openai.com/codex/app/review

• Codex App Automations 官方文档：https://developers.openai.com/codex/app/automations

• 本系列上一篇：CX-01 Codex App 安装与认证

• 本系列下一篇：CX-03 Commands 工作流入口

---

课程制作：老金
最后更新：2026年9月14日
许可：本课程采用 MIT License；转载、复制或二次分发时必须保留版权声明与许可声明

---

下一步

⠀

下一篇：CX-03 Commands：App 里的 slash commands 与工作流入口。