原文：KimYx0207/AI-Coding-Guide-Zh · 2026-06-10
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年5月30日
- 信息来源：OpenAI Codex App Features、Settings、Review、Automations、MCP、Skills、Plugins 官方文档
- 前置要求：已完成 CX-01 Codex App 安装与认证
📚 本课学习目标
完成本课学习后，你将能够：
- 理解App的核心模型：掌握Thread、Worktree、Review、Terminal、Settings等核心概念
- 区分三种工作方式：清楚Local thread、Worktree thread、Cloud handoff各自的适用场景
- 写好任务描述：用目标-范围-约束-验证-交付五要素模板描述任务
- 掌握Review工作流：在App中查看diff、审批命令、合并改动
- 理解Settings配置：知道模型、审批、沙盒、插件、MCP在App中的配置入口
- 建立App全局视角：知道Commands、MCP、Skills、Plugins、Automations在App中各自的位置和关系
- 避免常见翻车场景：不盲目给写权限、不跳过Review、不用Cloud替代本地App
- 跑通完整的App改动流程：从任务描述到diff检查到合并提交的全流程
🗺️ 学习路径导航（先看这里！）
💡 根据你的情况选择学习路径：这是一篇长教程，不用全看！
路径A：快速上手（⏱️ 20分钟）
适合人群：装好了App，想快速知道怎么用
只看这些章节（其他跳过）：
✅ 第1部分：App的核心模型（5分钟）
✅ 第2部分：三种工作方式（5分钟）
✅ 第3部分：任务描述模板（5分钟）
✅ 第6部分：Review工作流（5分钟）20分钟后你能达到：能用App描述任务、看懂diff、做基本操作
路径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 复核和问题定位 |
本系列后续功能都要回到这个模型里解释。
术语表（小白必读）
第一次学 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 帮你写代码”，而是把一次软件改动拆成六个可控环节：
text
目标输入
-> 上下文收集
-> 权限和工具选择
-> 文件或命令执行
-> Review / diff 检查
-> 人工决定提交、继续或撤销你每次使用 App，都在这条链路上做选择。提示词写得再漂亮，如果没有范围、权限和 Review，任务仍然容易失控；模型再强，如果它没有读到项目命令、测试方式和安全边界，也会把通用经验误当成本项目事实。
0.1 五个控制点
| 控制点 | 你要问的问题 | 推荐动作 |
|---|---|---|
| 目标 | 这次到底要解决什么问题？ | 用“目标-范围-约束-验证-交付”写任务 |
| 上下文 | Codex 该读哪些文件？ | 陌生项目先只读建模 |
| 权限 | 是否允许写文件、跑命令、联网、调外部工具？ | 先保守，必要时再放开 |
| 结果 | 改动是否真的在预期范围内？ | 看 Review 面板和命令输出 |
| 收口 | 是继续修、撤销、提交，还是交给 Cloud？ | 人工做最后决定 |
这就是 Codex App 比普通聊天更适合开发的原因：它把“看文件、跑命令、改代码、审 diff、连接外部系统”放在同一个界面里。但这也意味着你不能只学提示词，还要学会流程控制。
0.2 一条线程的生命周期
一条健康的开发线程通常长这样：
- 开场只读：先让 Codex 读项目，确认技术栈、命令、目录和风险。
- 明确任务：告诉它目标、范围、不能做什么、怎么验证。
- 允许执行：小任务可直接改，大任务先
/plan或用 worktree。 - 检查结果：Review 面板看文件、diff、命令输出和风险。
- 定点反馈：用行内评论或具体文件行号让它修。
- 收尾决策：草拟 commit / PR 描述，由人决定是否提交。
如果同一线程里开始混入无关目标，比如刚修登录又让它设计首页、再顺手接一个数据库迁移，线程会变得难以 Review。更稳的做法是：一个线程承载一个目标；新目标开新线程或新 worktree。
1.1 App 主控台不是“聊天窗口”
Codex App 的学习难点不在提示词，而在你是否把每个动作放到正确位置：
| 你看到的东西 | 你真正要判断的事 | 错误用法 |
|---|---|---|
| Thread 列表 | 哪条任务线承载当前上下文 | 同一个线程里混多个目标 |
| Prompt 输入框 | 任务是否有目标、范围、验证和交付 | 只写“帮我优化一下” |
| Terminal / 命令输出 | 命令是否按预期运行、有没有失败 | 只看 Codex 总结，不看输出 |
| Review 面板 | 文件差异是否可接受 | 跳过 diff 直接提交 |
| Settings | 当前模型、审批、沙盒、工具是否匹配任务风险 | 所有项目都用同一套高权限配置 |
| Apps / Connectors | 外部上下文是否真的需要 | 为了方便授权过多服务 |
一句话：App 负责把“任务、文件、命令、权限、审查、外部上下文”放在同一个桌面流程里。你要学的是流程控制，不是只学几个命令。
1.2 新手每天都该用的三条安全线
- 第一次进陌生项目，先发只读任务，不让 Codex 写文件。
- 第一次允许写文件，只改低风险文档或单个小范围文件。
- 每次写完都进 Review 面板看 diff，不把“Codex 说完成了”当成最终结果。
这三条比任何高级插件都重要。只要你守住它们，App 工作流会比纯 CLI 更容易控制。
2. 三种工作方式
2.1 Local thread
适合小任务和只读任务：
text
阅读这个项目并总结启动命令、测试命令、主要目录。不要修改文件。优点：快，直接使用当前工作区。
风险：如果让 Codex 写文件，改动会进入当前工作区。学习阶段要盯住 Review 面板。
2.2 Worktree thread
适合功能开发、重构、风险较高的改动：
text
在新的 worktree 里实现登录页移动端布局修复。改完运行相关测试，最后给我 diff 摘要。优点：隔离改动，多个任务可以并行。
注意：worktree 仍然是真实 Git 工作区。合并前要 Review。
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 任务描述模板
好任务要包含五件事：
text
目标：修复用户资料页加载失败。
范围：只改 src/pages/profile.tsx 和 src/api/user.ts。
约束：不要改数据库 schema，不要引入新依赖。
验证：运行 npm test -- profile。
交付：展示 diff 摘要和测试结果，不要自动提交。不要只写：
text
帮我修一下。因为 Codex 不知道范围、验证方式和停止条件。
3.1 三类高质量任务模板
只读理解任务
text
阅读这个仓库。只总结：技术栈、启动命令、测试命令、主要目录、当前风险。不要修改文件，不要安装依赖。小范围修复任务
text
目标：修复 docs/install.md 中 Windows 安装命令不一致的问题。
范围：只改 docs/install.md。
约束：不要改 README，不要新增图片，不要提交。
验证：检查文内命令前后一致。
交付：给出 diff 摘要和你检查过的命令列表。UI / 页面反馈任务
text
目标：修复设置页按钮在 375px 宽度下文字溢出。
范围：只改 SettingsPage 相关组件和样式。
验证：启动本地页面，分别检查桌面和移动宽度；如能使用 App 内浏览器或截图，请把观察结果写清楚。
交付：展示 diff、截图观察结论和未覆盖风险。3.2 不要写进任务里的东西
- 不要写 API key、cookie、token、私有账号。
- 不要让 Codex “顺手优化所有代码”。
- 不要把“自动提交、自动推送、自动发 PR”设成默认动作。
- 不要让它在没说明原因时安装新依赖。
- 不要把不确定的命令当成事实；让它先从项目文件里找证据。
4. App Review 工作流
每次 Codex 修改文件后，你都应该看 Review：
- 看文件列表：确认只改了目标范围。
- 看 diff：确认行为变化合理。
- 看测试输出：确认验证真的跑过。
- 行内指出问题：让 Codex 继续修。
- 需要提交时再 stage / commit。
典型提示：
text
Review 这次 diff。重点检查是否改了范围外文件、是否缺测试、是否引入兼容性风险。4.1 Review 面板逐项检查法
| 检查项 | 看什么 | 不通过时怎么处理 |
|---|---|---|
| 文件列表 | 是否只改了任务范围内文件 | 让 Codex 解释范围外改动，必要时撤掉 |
| 单文件 diff | 是否有无关格式化、删除、重命名 | 行内指出具体片段重改 |
| 命令记录 | 是否真的运行验证命令 | 要求运行相关命令，或说明不能运行原因 |
| 生成文件 | 是否出现 lockfile、build output、缓存 | 确认是否必要，不必要就删除 |
| 安全项 | 是否碰到 .env、token、权限配置 | 立即停止并人工审查 |
| Git 操作 | 是否 stage / commit / push 到正确目标 | 学习阶段让 Codex 只草拟，不自动执行 |
4.2 App 里继续修的正确说法
不要开新线程说“你刚才改错了”。在同一线程里引用具体 diff：
text
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 输入 / 后的列表为准。
如果你想核对一个命令是否可用，按这个顺序：
- 在 App 输入
/看当前列表。 - 看命令弹出的说明文字。
- 再查官方 App Commands 文档。
- 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 工作流通常是：
- Codex 修改本地文件。
- 你在 Review 面板检查。
- 运行测试。
- stage / commit。
- 推送分支。
- 创建 PR。
- 必要时交给 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 课程的地图：
text
一次性当前任务
-> 先用自然语言或 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 天：只读线程和任务五要素。让每个人都能让 Codex 总结项目而不改文件。
- 第 2 天：小范围写入和 Review。只改 README 或单个测试文件，练习看 diff。
- 第 3 天：AGENTS.md 和权限基线。把项目命令、安全边界和验证方式写清楚。
- 第 4 天：MCP / Connector 只读试跑。先读 GitHub issue 或文档，不做写操作。
- 第 5 天：Worktree / Automations / Cloud。再进入并行、后台和远程执行。
这条路径符合新手心理：先建立控制感，再逐步放开能力。反过来，一上来讲插件、云端、自动化，容易让人觉得强大但危险，最后不敢真正用。
14. 从零到 PR 的完整 App 实战
这一节是把前面的概念串起来。建议你拿一个非生产仓库练一遍。
14.1 第一步：只读建模
text
阅读这个项目，只输出：技术栈、启动命令、测试命令、主要目录、可能需要写进 AGENTS.md 的规则。不要修改文件。你应该看到：
- Codex 没有写文件。
- 输出里能指出命令来自哪个文件，例如
package.json、README、Makefile。 - 没有把不存在的命令编出来。
14.2 第二步：小范围修改
text
目标：修正 README 中一处过时命令。
范围：只改 README.md。
约束：不要改版本号，不要重排整篇文档，不要提交。
验证：确认 README 中同类命令写法一致。
交付：展示 diff 摘要。你应该看到：
- Review 里只有 README。
- 没有格式化整篇文件。
- Codex 能说明为什么改这一行。
14.3 第三步：让 Codex 自审一次
text
/review 重点检查这次改动是否超出范围、是否引入错误命令、是否需要更新其他文档。如果当前 App 没有 /review，就用自然语言：
text
请审查当前 diff。只报告问题和风险，不要继续修改。14.4 第四步：人工决定 Git 操作
学习阶段建议你让 Codex 只草拟：
text
根据当前 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 引用文件里，会比每个人临时发挥更稳。
只读理解模板
text
阅读这个项目，只输出：
1. 项目用途
2. 技术栈
3. 安装、测试、lint、build 命令及来源
4. 主要目录
5. 不应随意修改的文件或目录
不要修改文件，不要安装依赖。小修模板
text
目标：[具体问题]
范围：只改 [文件/目录]
约束：不要改 [排除项]，不要新增依赖，不要提交。
验证：运行 [命令]；如果不能运行，说明原因。
交付：展示 diff 摘要、验证结果、剩余风险。大改计划模板
text
/plan
目标：[大目标]
范围：[允许读写的模块]
约束：[不改什么，不做什么外部动作]
请先只读分析，输出：
1. 需要读的文件
2. 两种可选方案
3. 风险和回滚方式
4. 建议验证命令
5. 下一步是否建议使用 worktree
不要修改文件。PR 收口模板
text
基于当前 diff 草拟 PR 描述，包含 Summary、Verification、Risk。
Verification 只写真实运行过的命令；未运行的命令要说明原因。
不要创建 PR，不要 push。15.3 团队默认边界
| 动作 | 默认策略 | 什么时候放开 |
|---|---|---|
| 读项目文件 | 允许 | 敏感目录例外 |
| 修改普通源码 | 允许在明确范围内 | 大改用 worktree |
| 修改依赖 / lockfile | 先计划 | 任务明确且有验证 |
读取 .env* | 默认拒绝 | 极少数人工确认场景 |
| 删除文件 | 先列清单 | 人工确认后小范围执行 |
| 提交 / push | 学习阶段只草拟 | 团队成熟后按规则放开 |
| 外部服务写操作 | 默认拒绝 | connector scope 明确且 PR/评论目标清楚 |
团队边界不需要一开始完美，但要写下来。写下来之后，Codex、导师、新成员才有共同参照。
15.4 经理和 Tech Lead 怎么看 Codex 产出
管理者不用盯每一行代码，但要盯四个信号：
- 任务是否被拆小：一个 Codex 线程不应该承载半个月的模糊大目标。
- Review 是否真实发生：有没有看 diff、测试、风险，而不是只看总结。
- 验证是否对应改动：跑了相关测试，还是只跑了无关命令。
- 权限是否按项目区分：陌生仓库、生产相关任务、高风险外部服务不能和普通文档小修同权限。
如果团队发现 Codex 经常“越修越大”，通常不是模型突然变差，而是任务边界、项目规则和 Review 纪律没有建立。
常见问题
Q1：App 是不是只能聊天？
不是。App 是本地开发主控台，核心是线程、文件改动、Review、终端、插件、自动化。
Q2：所有功能都要学吗？
不需要。先掌握 Thread、Review、Commands、AGENTS.md，再按需要学 MCP、Skills、Plugins、Automations。
Q3：App 中看到的命令和 CLI 一样吗？
不一定。以当前 App 的 /help、命令补全和官方文档为准。CLI 能帮助核对，但不是 App 的替代品。
16. App 桌面工作流的完整操作系统
Codex App 不是一个聊天框，而是一套围绕项目、线程、终端、Review、权限和外部连接组织起来的桌面工作台。你可以把它理解为 6 个区域：
| 区域 | 作用 | 新手常见错误 |
|---|---|---|
| Project | 选定工作边界 | 打开太大的目录 |
| Thread | 保留任务上下文 | 一个线程塞太多目标 |
| Composer | 写任务和权限选择 | prompt 太泛 |
| Terminal | 运行和观察命令 | 忽略终端输出 |
| Review | 看 Git diff 和评论 | 不分 diff 来源 |
| Sidebar / panes | 看任务、自动化、产物 | 只盯最终回答 |
成熟的 App 工作流不是“发一句话等结果”，而是不断在这 6 个区域之间切换：描述目标、看执行、读终端、看 diff、给反馈、再收窄。
16.1 一次 App 任务的推荐节奏
text
任务前：
说明目标、范围、不能做什么
执行中：
看计划、看终端、必要时补充上下文
执行后：
看 last turn changes
看 uncommitted changes
跑必要命令
留 inline comments
决定保留、继续修或丢弃16.2 App 用户的三个基本动作
| 动作 | 例子 | 目的 |
|---|---|---|
| 收窄 | “只改 README” | 控制 diff |
| 追证据 | “你运行了什么命令？” | 避免只看结论 |
| 反向解释 | “根据 diff 解释你做了什么” | 检查是否偏题 |
这三个动作比记住很多功能更重要。
17. 线程设计：不要把一个线程用成杂物间
线程是 App 的核心单位。线程越清楚，Codex 越容易保持方向。
17.1 适合放在同一线程的内容
text
- 同一个 bug 的定位、修复和 review
- 同一个 PR 评论回合
- 同一个文档页面的修改
- 同一次发布检查
- 同一条 automation 的设计和调试17.2 应该新开线程的内容
text
- 从 bug 修复跳到新功能设计
- 从代码修改跳到企业治理讨论
- 从本地任务跳到 Cloud 环境配置
- 从一个 PR 跳到另一个 PR
- 从只读研究跳到写入执行，且范围变大17.3 线程命名习惯
如果 App 支持显示或编辑线程标题，建议用结果导向命名：
text
Fix checkout retry timeout
Review PR #128 auth redirect
Draft AGENTS.md for mobile app
Investigate docs drift in onboarding guide不要命名成：
text
Codex test
Help me
看看这个
今天的任务线程标题是未来你找回上下文的入口。
18. App 与集成终端：让 Codex 看见真实反馈
集成终端的价值不只是方便。它让你在同一个工作台里运行命令，再让 Codex 基于真实输出继续工作。
18.1 终端协作模式
text
我会先运行测试。
请等我把终端输出留在这里后，再帮我分析。
不要猜测失败原因。然后你运行：
bash
npm test再问：
text
请读取当前终端输出。
先总结失败测试，再判断最可能的根因。
不要修改文件。这比让 Codex 直接猜“测试为什么失败”可靠得多。
18.2 终端输出太长怎么办
text
终端输出很长。
请只关注：
1. 第一个失败的测试
2. 最靠近 root cause 的错误
3. 和当前 diff 有关的文件
4. 下一步最小排查命令18.3 命令运行权交给谁
| 情况 | 建议 |
|---|---|
| 安装依赖 | 人先看命令，必要时批准 |
| 运行测试 | 可让 Codex 执行，也可人执行 |
| Git commit / push | 人决定 |
| 删除文件 | 人先确认 |
| 项目外目录写入 | 尽量避免 |
App 的好工作流不是所有命令都让 Codex 代跑，而是让命令和解释形成闭环。
19. App 任务库：从小到大的 20 个练习
这组任务可以作为课程练习。它们从只读到写入，从单文件到跨模块。
19.1 只读任务
text
请只读总结这个项目的目录结构。
不要修改文件。
输出适合新同事阅读的项目地图。text
请只读分析 package.json。
告诉我开发、测试、构建相关命令分别是什么。
不要运行命令。text
请只读找出项目里最可能需要 AGENTS.md 说明的规则。text
请只读比较 README 和 package.json 是否有不一致的命令说明。text
请只读解释当前 Git 状态，告诉我哪些改动可能不是本轮产生的。19.2 小写入任务
text
请只修改 README 的快速开始部分，使它和 package.json 脚本一致。
不要改代码。
完成后说明 Review 面板应该看哪里。text
请给 docs/setup.md 增加 Windows PowerShell 注意事项。
不要添加空白素材提示。text
请把 CONTRIBUTING.md 中过期的测试命令更新为当前 package.json 里的脚本。text
请在 AGENTS.md 中增加项目常用命令草稿。
先根据仓库文件推断，不确定的地方标注。text
请修复一个明显的 Markdown 链接错误。
只改相关文档文件。19.3 中等任务
text
请根据当前失败测试定位最小修复。
先解释根因，再修改文件。
不要重构无关代码。text
请把这个 UI 文案错误修掉。
只改显示文案和对应测试。text
请根据 PR 评论修复第一条明确 bug。
不要处理其它评论。text
请补一个 regression test 覆盖刚才发现的错误分支。
先写测试，再做最小实现。text
请把一个重复的小 helper 抽出来。
只在两个调用点使用，不扩大重构。19.4 进阶任务
text
请先用只读方式评估这个任务是否适合 worktree。
如果适合，说明 worktree 的价值和回流方式。text
请把这个模糊需求拆成 3 个小任务。
每个任务都要有可编辑文件范围和风险说明。text
请做一次定向 review：
只看安全、边界条件和缺失测试。
不要评价纯风格问题。text
请把这个本地问题整理成 Cloud handoff 包。
不要修改文件。text
请设计一个 Automation prompt，用于每周检查 docs 漂移。
默认只读。20. App 反模式详解
20.1 “全都帮我优化一下”
问题：
text
帮我把这个项目优化一下。这个任务没有目标、范围、优先级和停止条件。更好的写法：
text
请只读分析当前项目的 README 和 package.json。
找出新手安装流程里最容易失败的 3 个点。
不要修改文件。20.2 “先改了再说”
问题：
text
你看着改，改好就行。这会让 Codex 猜你的偏好。更好的写法：
text
请先给我一个最小修改计划。
计划里列出会改哪些文件、为什么改。
我确认后再执行。20.3 “把所有评论一次修完”
问题：
text
把 PR 评论都处理掉。更好的写法：
text
请先把 PR 评论分组。
只处理可以直接修复且风险低的一组。
需要产品判断或兼容性判断的评论先列出来。20.4 “测试失败就大改”
问题是把一个失败当成重构理由。更好的写法：
text
请定位第一个失败测试的根因。
优先做最小修复。
如果你认为需要重构，请先说明为什么小修不够。21. 跨岗位协作：让 App 输出能被别人接住
Codex App 的一个优势是：它能把代码改动、终端输出、Review diff 和任务摘要放在同一个工作台里。工程师不必把所有上下文重新口头解释一遍，可以让 Codex 把同一份 diff 改写成不同人能接住的材料。
21.1 给产品同事看的解释
text
请根据当前 diff，用产品语言解释用户会感知到什么变化。
不要讨论代码实现细节。
如果用户无感，也请说明为什么。21.2 给测试同事看的手测路径
text
请根据当前改动列出最该手测的 5 条路径。
按风险排序。
不要写自动化测试，先给手测清单。21.3 给工程负责人看的拆分建议
text
请评估这个改动是否适合拆成多个 PR。
给出拆分建议、每个 PR 的风险和依赖关系。
不要修改文件。21.4 给文档或运营同事看的变更摘要
text
请根据当前 diff 判断是否需要更新 README、用户文档、发布说明或内部 FAQ。
只输出建议和对应原因，不要修改文件。22. App 工作流复盘模板
每次完成一个任务后，用 3 分钟复盘，会让团队进步很快。
md
# 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 第一步：建立线程边界
text
本线程只处理 README 启动命令和 package.json 脚本不一致的问题。
不要改代码。
不要改 lockfile。
不要处理其它文档问题。
请先只读分析 README 和 package.json，告诉我计划。23.3 第二步：确认计划
Codex 给出计划后，不要直接说“继续”。更好的确认：
text
按你的计划执行，但只改 README。
如果你发现还需要改其它文件，先停下来告诉我原因。23.4 第三步：看 Review
Prompt：
text
请根据 last turn changes 解释刚才的 diff。
只解释事实，不要继续修改。人工检查：
text
- README 是否只改了目标段落。
- 命令是否和 package.json 一致。
- 有没有顺手改格式。
- 有没有新增无关内容。23.5 第四步：用 inline comment 精修
你可以在具体行留言：
text
这条命令缺少 Windows PowerShell 说明，请补一句但不要扩展成新章节。然后在线程里说：
text
请处理我在 Review 面板里的 inline comment。
保持 README 改动范围不变。23.6 第五步：准备 PR 摘要
text
请根据当前 diff 草拟 PR 描述。
包括 Summary、Verification、Risk。
不要提交，不要推送。示例输出：
md
## 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 人负责意图
text
我要解决什么问题？
哪些文件可以改？
哪些文件不能改？
什么情况下需要停下来问我？24.2 Codex 负责推进
text
读取上下文。
提出计划。
执行小范围修改。
解释 diff。
根据反馈修正。24.3 人负责最后判断
text
是否保留 diff。
是否提交。
是否推送。
是否回复外部评论。
是否扩大范围。24.4 分工 prompt
text
这次任务中，你负责分析和执行小范围修改。
我负责决定是否提交和是否扩大范围。
如果你遇到需要产品判断、权限扩大、外部写操作或大重构的情况，请停下来问我。25. App 工作流中的上下文管理
线程越长，越需要管理上下文。
25.1 什么时候总结
text
- 任务进入第二天。
- 线程已经处理多个阶段。
- 你准备开新线程继续。
- 要把任务交给 Cloud。
- 要让 Automation 后续跟进。25.2 线程总结 prompt
text
请总结当前线程，方便我开新线程继续。
包括：
1. 原始目标
2. 已经做的事
3. 修改过的文件
4. 运行过的命令
5. 剩余问题
6. 下一步建议25.3 新线程接续 prompt
text
下面是上一个 Codex App 线程的总结。
请先复述你理解的目标和剩余问题。
不要立即修改文件。这能防止新线程丢失意图。
26. App 与非代码产物
Codex App 可以帮助处理文档、表格、演示文稿和 PDF 等产物。课程里要提醒：非代码产物也需要清楚输入和检查方式。
26.1 文档任务 prompt
text
请把这份 Markdown 文档整理成更适合新人阅读的结构。
保持事实不变。
不要新增图片提示。
输出前说明你改了哪些标题和段落。26.2 表格任务 prompt
text
请根据这个 CSV 生成一个汇总表。
列出：
- 总数
- 按状态分组
- 异常项
请保存为新的 Markdown 表格，不要覆盖原始 CSV。26.3 演示任务 prompt
text
请根据这份课程大纲生成 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 上午：只读进入状态
text
请只读总结当前项目今天最值得关注的状态。
读取：
- git status
- 最近提交
- README 或 AGENTS.md 中的项目命令
- 当前终端输出如果有
输出：
- 当前工作区状态
- 可能需要先处理的问题
- 今天适合 Codex 参与的 3 个小任务这个任务适合每天开始工作时使用。它不要求 Codex 改任何东西，只让它帮助你恢复上下文。
28.2 上午中段：处理一个小 bug
text
我想处理一个小 bug：保存设置后按钮没有恢复可点击状态。
请先只读定位可能文件。
不要修改文件。
输出：
- 相关文件候选
- 需要确认的状态流
- 建议最小修复步骤确认后：
text
请只做最小修复。
不要重构设置页面。
如果需要改测试，先说明应该补哪条。28.3 午后：Review 和整理
text
请根据当前 diff 写一个 review-oriented summary。
包括：
1. 改动意图
2. 主要文件
3. 用户可见变化
4. 已经运行或应该运行的命令
5. 还需要人工看的风险这比让 Codex 写“工作总结”更有用，因为它直接服务 PR 和 Review。
28.4 下班前：收束线程
text
请总结这个线程，方便我明天继续。
包括：
- 已完成
- 未完成
- 当前 diff 状态
- 不要忘记的风险
- 明天第一步建议App 工作流的核心是“收束”。不收束的线程第二天会变成上下文负担。
29. App 工作流成熟度：从会用到用稳
29.1 初级阶段
表现：
text
- 能打开项目。
- 能问问题。
- 能做小改。
- 会看 Review。常见问题：
text
- prompt 太大。
- 不知道何时停。
- 不看终端输出。
- 不区分 last turn 和全部 diff。29.2 中级阶段
表现：
text
- 会先 plan。
- 会写边界。
- 会用 inline comments。
- 会让 Codex 反向解释 diff。
- 会把 Cloud、Automation、Skills 放到合适位置。29.3 高级阶段
表现：
text
- 会给团队写 AGENTS.md。
- 会设计可复用 Skill。
- 会判断什么时候开 subagents。
- 会把 App Review 嵌入 PR 流程。
- 会把失败经验沉淀进团队模板。29.4 团队阶段
表现：
text
- 团队有统一第一条 prompt。
- 每个仓库有项目基线。
- Review 和 Git 操作边界清楚。
- 自动化有 owner。
- 外部能力有登记。30. App 工作流练习：把同一个 diff 讲清楚
同一个 diff 可以有多种解释方式。练习的重点不是给每种岗位固定模板，而是学会根据接收者的下一步行动改写信息。
30.1 用户影响版
text
请根据当前 diff，用产品语言解释这个改动。
只回答：
1. 用户会看到什么
2. 用户不会看到什么
3. 是否需要更新 release note
4. 是否需要产品确认30.2 手测清单版
text
请根据当前 diff 生成手测建议。
按风险排序。
每条包括前置条件、操作步骤和预期结果。
不要写自动化代码。30.3 拆 PR 版
text
请评估当前任务是否已经超出原始范围。
把 diff 分成：
- 原目标内
- 相关但可拆分
- 不应该在本次提交里30.4 文档同步版
text
请检查当前代码改动是否需要同步 README、docs 或示例。
只给建议，不修改文件。这些练习能让非工程角色也参与 Codex App 工作流，而不是把它当成只有程序员能用的工具。
31. App 长案例：一天里三次使用 Codex，但每次目的不同
成熟的 App 工作流不是“一整天都让 Codex 写代码”。更真实的一天通常包含三类使用：早上梳理、下午执行、傍晚收口。
31.1 早上：把模糊任务变成可做任务
原始任务：
text
今天把登录体验优化一下。不要直接执行。先让 Codex 帮你收窄：
text
我今天想改登录体验，但任务还很模糊。
请先只读分析项目里登录相关的入口、组件、测试和文档。
输出：
1. 可以在 1 天内完成的小任务候选。
2. 每个候选的风险。
3. 哪个最适合先做。
4. 需要我确认的问题。
不要修改文件。Codex 可能给出：
text
候选 A：优化错误提示文案。
候选 B：保留登录前目标页面 redirect。
候选 C：重构 auth form 组件。这时你选择 B，因为它有明确行为和测试。第二轮 prompt：
text
选择候选 B：保留登录前目标页面 redirect。
请制定最小修复计划。
要求：
1. 列出要读的文件。
2. 列出可能要改的文件。
3. 说明测试策略。
4. 不要开始修改。31.2 下午：只改最小闭环
确认计划后再写：
text
按刚才计划执行最小修复。
边界：
1. 只处理登录前目标页面 redirect。
2. 不重构 auth form。
3. 不改 toast 样式。
4. 如果需要新增文件，先说明原因。
5. 修改后运行相关测试。执行过程中，如果 Codex 想扩大范围，可以这样拉回来：
text
请暂停扩展。
重新对照任务目标：
只处理 redirect 保留。
把当前 diff 分成“目标内”和“目标外”。
不要继续写代码。31.3 傍晚：把结果变成 PR 材料
不要只问“总结一下”。让 App 输出可进入 PR 的材料：
text
请基于当前 diff 写 PR 材料。
输出：
1. Summary：3 条以内。
2. User Impact：用户行为变化。
3. Verification：只写实际运行过的命令。
4. Risk：需要人工确认的地方。
5. Follow-up：不在本 PR 处理的事项。再用 Review 面板读一次 diff：
text
请只读审查当前 diff。
重点看：
1. 是否只处理 redirect。
2. 是否有无关 UI 或样式改动。
3. 测试是否覆盖失败路径。
4. PR 描述是否有夸大。这个一天案例的重点是节奏：早上不急着写，下午不扩大范围，傍晚不跳过 Review。Codex App 的优势不只是“能改代码”，而是能把任务从模糊、执行、审查到交付都放在一个可回看的线程里。
32. App 失控恢复：线程变乱以后怎么救回来
线程用久了会变乱：目标变了、文件多了、测试失败混进来、用户又插入新想法。不要在同一条混乱线程里继续加要求。先让 Codex 总结现场。
text
请暂停实现，整理当前线程状态。
输出：
1. 原始目标是什么。
2. 当前已经做了什么。
3. 哪些新需求后来加入。
4. 当前 diff 涉及哪些文件。
5. 哪些问题应该另开线程或另开 PR。
不要修改文件。如果目标已经变成两个任务：
text
请把当前线程拆成两个后续任务：
任务 A：完成 auth redirect 修复。
任务 B：处理 toast 样式整理。
对每个任务输出：
1. 目标。
2. 文件范围。
3. 验证方式。
4. 是否可以从当前 diff 中保留部分改动。然后选择一个继续：
text
本线程只继续任务 A。
请忽略任务 B，除非它影响任务 A。
先只读确认任务 A 的剩余步骤。这种恢复能力很重要。App 线程不是越长越好，长线程如果没有阶段性收口，会让 Codex 记住太多过期意图。会暂停、整理、拆分，才是真正会用 App。
📝 总结与检查清单
完成本课后，请确认以下所有项：
- [ ] 理解Local thread、Worktree thread、Cloud handoff三种工作方式的区别
- [ ] 能用五要素模板（目标-范围-约束-验证-交付）描述任务
- [ ] 知道如何在App中查看diff和审批命令
- [ ] 理解Settings中模型、审批、沙盒等配置入口
- [ ] 知道Commands、MCP、Skills、Plugins、Automations在App中的位置
- [ ] 不跳过Review直接合并
- [ ] 陌生项目先用只读模式
如果以上全部勾选，恭喜你掌握Codex App核心工作流！
附录
A. App核心概念速查
| 概念 | 一句话解释 |
|---|---|
| Thread | 一条任务线，包含上下文、历史和状态 |
| Local thread | 直接在当前工作区执行的任务线 |
| Worktree thread | 在隔离Git分支/目录中执行的任务线 |
| Cloud handoff | 将任务交给云端执行的接力模式 |
| Review面板 | 查看diff、文件变更、行内反馈的关口 |
| Settings | 模型、审批、沙盒、插件、MCP等配置入口 |
B. 任务描述模板
text
目标：[你要达到什么效果]
范围：[只改哪些文件/目录]
约束：[不能做什么]
验证：[怎么确认改对了]
交付：[期望的输出形式]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年5月30日 许可：本课程采用 MIT License；转载、复制或二次分发时必须保留版权声明与许可声明