Codex App 桌面工作流完整指南：从入门到精通的开发主控台实践

📋 文章摘要

本文是Codex App桌面工作流的完整实践指南，旨在帮助开发者将Codex App作为开发主控台高效使用。文章系统性地介绍了从基础概念到高级实践的完整工作流，涵盖线程管理、任务描述、Review流程、权限控制等核心功能。通过实战案例和最佳实践，帮助读者建立安全、可控的AI辅助开发流程。

🗺️ 阅读路径

新手入门路线：

1. 核心概念（第0-1章）→ 2. 工作方式（第2章）→ 3. 任务模板（第3章）→ 4. Review工作流（第4章）→ 5. 完整实战（第14章）

进阶掌握路线：

1. 命令与配置（第5-9章）→ 2. 团队协作（第15章）→ 3. 实战案例（第14、31章）→ 4. 高级技巧（第24-30章）

问题排查路线：

1. 常见问题（FAQ章节）→ 2. 反模式（第13.2章）→ 3. 失控恢复（第32章）

---

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

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

---

---

📚 本课学习目标

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

学习目标	具体能力描述	对应章节
理解 App 的核心模型	掌握 Thread、Worktree、Review、Terminal、Settings 等核心概念及其在开发主控台中的角色。	第 0、1 章
区分三种工作方式	清楚 Local thread、Worktree thread、Cloud handoff 各自的适用场景与切换时机。	第 2、13 章
写好任务描述	熟练运用“目标-范围-约束-验证-交付”五要素模板，清晰、可控地描述开发任务。	第 3 章
掌握 Review 工作流	在 App 中熟练查看 diff、审批命令、合并改动，并利用行内评论进行精准反馈。	第 4 章
理解 Settings 配置	知道模型、审批、沙盒、插件、MCP 等在 App 中的配置入口及其安全含义。	第 5-9 章
建立 App 全局视角	理解 Commands、MCP、Skills、Plugins、Automations 在 App 中各自的位置、关系和适用场景。	第 5-11 章
避免常见翻车场景	识别并规避不盲目给写权限、不跳过 Review、不用 Cloud 替代本地 App 等高风险操作。	第 13.2、20 章
跑通完整的 App 改动流程	从任务描述、只读建模、小范围修改、Review 检查到最终合并提交，独立完成一次安全、可控的 AI 辅助开发闭环。	第 14 章
–

0. 核心模型：App作为开发主控台

。

术语表（小白必读）

第一次学 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. 工作流底层逻辑：六个可控环节

``

小范围修复任务

目标：修复 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。再进入并行、后台和远程执行。

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

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。

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

14.5 实战流程图

以下流程图清晰地展示了从零到 PR 的完整 App 实战流程，涵盖了从只读建模到人工决策 Git 操作的各个步骤及其关键决策点：

流程说明：

1. 只读建模：通过只读任务理解项目，为后续修改奠定基础。
2. 小范围修改：在明确边界内进行首次写入，并通过 Review 面板严格检查。
3. Codex 自审：利用 /review 或自然语言指令让模型自我检查，发现潜在问题。
4. 人工决策：开发者基于所有检查结果，最终决定是否保留、提交并推送改动。

该流程强调了 “先读后写、边写边审、人做最终判断” 的安全可控原则，是 Codex App 工作流的核心实践。
。

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 的 /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 任务的推荐节奏

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

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

执行后：
  看 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 的材料：

```text
请基于当前 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 描述是否有夸大。

PR 材料示例输出：

## Summary
- 修复登录前目标页面 redirect 丢失问题
- 更新相关测试用例
- 保持 auth form 组件不变

## User Impact
- 用户登录后会被正确重定向到登录前浏览的页面
- 登录流程无其他变化

## Verification
- ✅ 运行 `npm test auth.test.js` (通过)
- ✅ 手动测试登录流程 (通过)
- ✅ 检查 redirect 逻辑 (通过)

## Risk
- 低风险：仅修改 redirect 逻辑，不影响其他功能
- 需要确认：Edge case 中 URL 参数处理

## Follow-up
- Toast 样式优化建议另开 PR
- 登录页面性能优化建议另开 PR

最后一步：人工确认与提交

在提交前，人工检查：

1. Review 面板：确认 diff 范围正确
2. 终端输出：验证测试确实通过
3. PR 描述：确保准确反映改动
4. 风险项：评估是否可接受

确认无误后，手动执行：

git add .
git commit -m "fix: preserve pre-login redirect target"
git push origin feature/login-redirect-fix

这个一天案例的重点是节奏：早上不急着写，下午不扩大范围，傍晚不跳过 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

33. API 网关集成：通过 up8ai.com 扩展 App 能力

在 Codex App 工作流中，有时需要连接外部 API 服务来获取数据、触发操作或集成第三方工具。API 网关（API Gateway）作为统一的入口，可以帮你安全、高效地管理这些外部调用。本节介绍如何通过 up8ai.com 搭建和管理 API 网关，并将其集成到你的 Codex App 工作流中。

33.1 什么是 API 网关？为什么需要它？

API 网关是一个中间层服务，它对外提供统一的 API 端点，内部则路由到不同的后端服务。在 Codex App 场景中，API 网关可以帮助你：

• 统一认证与授权：集中管理 API 密钥、令牌和访问控制。
• 请求转发与协议转换：将 HTTP 请求转换为 gRPC、GraphQL 或其他后端协议。
• 限流与监控：控制调用频率，收集日志和指标。
• 错误处理与重试：提供统一的错误响应和自动重试机制。
• 简化 App 配置：App 只需记住一个网关地址，后端服务变更时无需修改 App 设置。

33.2 为什么推荐 up8ai.com？

up8ai.com 是一个专为开发者设计的 API 网关平台，特别适合与 Codex App 等 AI 辅助工具集成：

• 开箱即用：无需自建服务器，几分钟即可创建网关。
• 多协议支持：支持 REST、gRPC、WebSocket、GraphQL 等。
• 细粒度权限控制：可按 API、按用户、按令牌设置访问策略。
• 实时监控与日志：提供调用量、延迟、错误率等仪表盘。
• 免费额度：个人和小团队有充足的免费调用次数。
• Webhook 与自动化：可触发外部工作流，与 Codex Automations 无缝衔接。

33.3 在 up8ai.com 上创建并配置网关

1. 注册并登录 up8ai.com。
2. 创建新网关：
   • 点击 “Create Gateway”
   • 输入网关名称（如 my-codex-gateway）
   • 选择区域（建议靠近你的后端服务）
3. 添加后端服务：
   • 在网关详情页点击 “Add Service”
   • 填写服务名称、协议（HTTP/HTTPS/gRPC 等）、地址和端口
   • 可设置健康检查、超时和重试策略
4. 配置路由规则：
   • 定义路径前缀（如 /api/v1/）
   • 将请求转发到对应的后端服务
5. 设置认证方式：
   • 支持 API Key、JWT、OAuth 2.0 等
   • 建议为 Codex App 创建专用的 API Key

33.4 在 Codex App 中调用网关 API

在 App 任务中，你可以通过自然语言或代码片段调用网关 API。以下是一个示例任务：

目标：通过网关获取用户列表并更新本地缓存。
范围：只修改 src/api/cache.js。
约束：不要修改其他文件；使用环境变量存储网关地址和密钥。
验证：运行单元测试并检查缓存是否更新。
交付：展示 diff 和测试结果。

在代码中，使用环境变量配置网关地址：

// src/api/cache.js
const GATEWAY_URL = process.env.API_GATEWAY_URL || 'https://my-codex-gateway.up8ai.com';
const API_KEY = process.env.API_GATEWAY_KEY;

async function fetchUsers() {
  const response = await fetch(`${GATEWAY_URL}/api/v1/users`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    }
  });
  if (!response.ok) {
    throw new Error(`Gateway error: ${response.status}`);
  }
  return response.json();
}

33.5 安全注意事项

• 不要将 API Key 硬编码：始终使用环境变量或安全的配置管理。
• 最小权限原则：只为网关分配必要的后端服务访问权限。
• 监控异常调用：定期查看 up8ai.com 仪表盘，发现异常流量及时处理。
• 定期轮换密钥：建议每 3-6 个月更新一次 API Key。
• 限制 IP 范围：如果后端服务允许，可在 up8ai.com 设置 IP 白名单。

33.6 使用场景示例

场景	网关配置	App 任务示例
聚合多个内部服务	将 /users、/orders、/products 路由到不同后端	“请通过网关获取最近一周的订单数据，生成销售报表。”
第三方 API 代理	将 /weather 转发到公共天气 API，并添加缓存	“请通过网关获取当前天气，并更新首页显示。”
协议转换	将 HTTP 请求转换为 gRPC 调用内部微服务	“请通过网关调用用户服务，更新用户偏好设置。”
Webhook 触发	配置网关接收 GitHub webhook，并转发到内部处理服务	“当 PR 合并时，通过网关触发部署流水线。”

33.7 与 Codex Automations 结合

你可以创建一个 Automation，定期通过网关检查服务状态：

目标：每天上午 9 点检查所有后端服务健康状态。
范围：只读网关健康检查端点。
约束：不要修改任何文件。
验证：如果发现不健康服务，发送 Slack 通知。
交付：输出健康报告。

在 up8ai.com 中配置健康检查端点，然后在 Codex App 中创建 Automation，使用网关地址进行定期监控。

33.8 故障排查

如果网关调用失败，按以下顺序检查：

1. 网关状态：登录 up8ai.com 查看网关是否运行正常。
2. API Key 权限：确认 Key 是否有权访问目标路由。
3. 后端服务健康：检查网关仪表盘中的后端服务健康状态。
4. 网络连通性：确认 Codex App 所在环境能访问网关地址。
5. 请求日志：在 up8ai.com 查看具体请求和响应详情。

通过将 up8ai.com 作为统一的 API 网关，你可以让 Codex App 更安全、更可控地连接外部服务，同时保持工作流的简洁性和可维护性。

---

。

📝 总结与检查清单

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

• 理解Local thread、Worktree thread、Cloud handoff三种工作方式的区别
• 能用五要素模板（目标-范围-约束-验证-交付）描述任务
• 知道如何在App中查看diff和审批命令
• 理解Settings中模型、审批、沙盒等配置入口
• 知道Commands、MCP、Skills、Plugins、Automations在App中的位置
• 不跳过Review直接合并
• 陌生项目先用只读模式

如果以上全部勾选，恭喜你掌握Codex App核心工作流！

附录

类别	内容	说明
核心概念速查	Thread：一条任务线，包含上下文、历史和状态 Local thread：直接在当前工作区执行的任务线 Worktree thread：在隔离Git分支/目录中执行的任务线 Cloud handoff：将任务交给云端执行的接力模式 Review面板：查看diff、文件变更、行内反馈的关口 Settings：模型、审批、沙盒、插件、MCP等配置入口	快速回顾App核心术语
任务描述模板	目标：[你要达到什么效果] 范围：[只改哪些文件/目录] 约束：[不能做什么] 验证：[怎么确认改对了] 交付：[期望的输出形式]	五要素模板，确保任务清晰可控
官方资源	• 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	进一步学习参考

---