Codex 零基础入门教程

本版定位

这一版只保留新手最需要的主线：认识 Codex、完成安装、学会基础任务、学会表达需求、学会项目文档。

本版的边界很明确：读完后，读者应该能完成基础安装、看懂常见界面、把简单任务交给 Codex、用项目文档控制任务范围；但还不能算掌握复杂工程协作、长期上下文管理、CI 集成、多人规范冲突、token 成本优化等进阶主题。

适合读者：

• 完全没接触过 Codex 的新手。
• 想先做出结果，而不是先研究所有配置的人。
• 想学会 README、PRD、DESIGN、PLAN、AGENTS.md 基础协作法的人。

不包含内容：

• MCP、Skill、飞书、Office 自动化等进阶能力。
• 小程序、iOS、ESP32 等复杂项目。
• 长篇附录和资料包说明。

本版目录

• 第一部分：先认识 Codex
• 第1章 Codex 到底是什么
• 第2章 Codex 能帮我们做什么
• 第3章 Codex 的三种形态
• 第4章 安装 Codex 的基本流程
• 第5章 Codex APP 的操作界面
• 第6章 Codex 的安装目录详解
• 第二部分：小白先学会"怎么用"
• 第7章 从一句话到完整页面
• 第8章 CSV 数据分析与 HTML 图表报告
• 第9章 怎么和 Codex 说清楚你的需求
• 第10章 学会让 Codex 修改、补充和重构内容
• 第11章 常见报错和解决报错的思路
• 第三部分：从会用到用顺手
• 第12章 Codex 的常用快捷指令
• 第13章 项目目录的 AGENTS.md 是什么
• 第14章 PLAN.md：把大任务拆成可执行步骤
• 第15章 四文档法则构建项目框架
• 第16章 产品文档与四文档法则的协同
• 附录A 常用命令速查
• 附录B 常见术语解释
• 附录C 推荐学习路径与练习建议

第一部分：先认识 Codex

这一部分是整篇教程的起点。先不要急着研究配置、模型、MCP、Skill 这些看起来很玄乎的词。

对新手来说，第一步永远不是“全都懂”，而是先建立正确认识：Codex 到底是什么，它能帮你做什么，以及你应该从哪个版本开始上手。只有把这些最基础的概念捋顺了，后面的安装、使用和实战才不会越学越乱。

第1章 Codex 到底是什么

1.0 本章你会学到什么

学完这一章，你不需要马上懂所有专业概念，只需要先搞明白三件事：

• 知道 Codex 和普通聊天式 AI 的关键区别。
• 明白为什么它不只是“写代码”，而是能参与真实任务。
• 建立一个适合新手的理解方式，后面学起来不容易乱。

对新手来说，第一章最重要的不是记住定义，而是建立一个正确的理解方式。只要这一点想明白了，后面再学安装、配置、提示词、项目协作，就不会那么容易乱。

1.1 一句话解释 Codex

如果只用一句最简单的话来解释，Codex 可以理解为：一个不仅会回答问题，还能直接进入项目、读取文件、执行任务、帮你持续推进工作的智能助手——数字员工。

很多人第一次听到 Codex，会下意识把它理解成“一个更强的 AI 对话框”或者“一个会写代码的机器人”。

这种理解不能说完全错，但太窄了。因为当你真正开始使用它时，你会发现它并不是只会输出一段文字给你看，而是能够围绕真实任务展开工作。

比如，你可以让它查看项目文件、整理资料、分析 CSV、生成网页、修改文档、检查问题、补充说明，甚至帮你把一个模糊需求逐步拆成可以执行的步骤。也就是说，Codex 的价值不只是“回答”，更重要的是“协助你把事情做下去”。

Codex 并不仅仅是一个写代码的工具。

• 可以处理文件。
• 可以清洗和整理数据。
• 可以做知识问答和信息梳理。
• 可以撰写报告、整理思路、补全文案。
• 可以参与真实项目中的执行过程。

你可以把 Codex 看成一个工作在本地项目环境中的通用智能助手。

1.2 和普通聊天式 AI 有什么区别

如果把普通聊天式 AI 比作“你问一句，它答一句”的顾问，那么 Codex 更像是“能进场干活”的助手。

普通聊天式 AI 的强项，往往是解释概念、回答问题、给建议、生成文字。

而 Codex 更进一步，它通常会围绕当前工作环境来行动。对新手来说，这个区别非常重要，因为它决定了你使用 Codex 的方式，不应该只是“问答案”，而应该是“交任务”。

你可以把两者的区别简单理解成下面这样：

• 普通聊天式 AI 更像顾问，擅长聊天、解释和出主意。
• Codex 更像协作助手，擅长围绕文件、项目和任务持续推进。
• 普通聊天式 AI 常常停在“告诉你怎么做”。
• Codex 更强调“帮你一起把它做出来”。

这也是为什么很多人第一次真正用上 Codex 后，会觉得它和自己以前接触的 AI 工具完全不是一个层级的体验。

1.3 为什么更适合做真实任务

因为真实工作很少是“一个问题，一个答案”就结束的。

真实任务通常包含很多连续动作，比如先看资料，再整理内容，再修改文件，再检查结果，最后继续补充。很多工具只能帮你完成其中一小步，而 Codex 的强项，是把这些动作串起来。

比如你要做一个教程文档，通常不是只写一段话就完事，而是要经历很多步骤：

• 先确定目录。
• 再整理已有素材。
• 然后补正文。
• 接着加案例。
• 再配截图。
• 最后检查顺序、标题和表达是否统一。

再比如你要做一个网页，也不是一句“帮我写网页”就彻底完成，而是要不断调整：

• 页面主题是什么？
• 给谁看？
• 需要几个模块？
• 用什么风格？
• 图片放哪里？
• 文字怎么写？
• 页面有没有报错？
• 手机端看起来怎么样？

Codex 的价值就在这里：它可以跟着任务一步步走，而不是只给你一个孤立答案。

它可以先帮你拆任务，再生成初版，再根据你的反馈继续改。你不满意，它还能继续调整。你发现有问题，它还能帮你排查。这个过程更像是“协作”，而不是单纯“问答”。

1.4 小白第一次应该怎么理解Codex

对零基础大家来说，最好的理解方式不是去背定义，而是先记住一个类比：

把 Codex 看成一个会看文件、会听要求、会动手做事、还能持续陪你修改的数字助手。

你给它的要求越清楚，它越容易做出好结果。

你给它的资料越完整，它越容易理解上下文。

你越愿意让它一步步改，它越容易帮你把任务推进到能用的程度。

所以，小白使用 Codex 的第一原则不是“我必须懂技术”，而是：

我先学会把事情说清楚。

比如，不要只说：

帮我做个网页。

更好的说法是：

帮我做一个适合新手学习 Codex 的网页，页面要有标题、简介、三个功能介绍模块和一个开始学习按钮，风格简洁，适合电脑和手机浏览。

这就是使用 Codex 的核心思路：把模糊需求说清楚，把大任务拆小，把反馈说具体。

1.5 新手常见误区

#### 误区一：把 Codex 当成高级搜索框

有些新手会像用搜索引擎一样使用 Codex，只问一些零散问题。

比如：

Codex 是什么？

HTML 是什么？

怎么写网页？

这些问题当然可以问，但如果只停留在这里，就浪费了 Codex 的能力。

更好的方式是把它当成任务助手：

我是零基础，想做一个 HTML 小页面，请你先解释思路，再生成代码，最后告诉我怎么运行。

这样 Codex 才能真正帮你完成一件事。

#### 误区二：以为不会编程就不能用 Codex

这是很多小白最容易卡住的地方。

实际上，Codex 的很多能力都不要求你先会编程。你可以先从这些任务开始：

• 整理文章。
• 改写文案。
• 生成教程。
• 分析表格。
• 做网页草稿。
• 拆解项目步骤。
• 总结文件内容。

等你用得多了，再慢慢接触代码和配置，就不会那么害怕。

#### 误区三：一上来就研究所有配置

新手最容易被配置文件吓住。

看到 config.toml、auth.json、provider、model、sandbox 这些词，马上就觉得自己学不会。

其实不用一上来全懂。

正确顺序应该是：

• 先知道 Codex 能干什么。
• 再完成第一次简单任务。
• 再学习怎么提需求。
• 然后再理解模型、配置和工具扩展。

先会用，再理解原理，这样最轻松。

1.6 本章小结

这一章你只需要记住三件事：

• Codex 不只是一个问答工具，更是一个能参与实际工作的智能助手。
• 它和普通聊天式 AI 的关键区别，在于它更强调任务执行和持续协作。
• 对新手来说，先学会把它当成“能一起做事的助手”，比死记硬背定义更重要。

接下来，下一章我们会继续解决另一个关键问题：Codex 到底能帮我们做什么。 只有把应用场景看明白，你才知道它为什么值得学。

第2章 Codex 能帮我们做什么

2.0 本章你会学到什么

学完这一章，你会先建立一个非常重要的认知：

• Codex 不是只能“写代码”。
• 它能处理很多真实工作里的常见任务。
• 你应该先从哪些场景开始上手。
• 哪些任务适合交给 Codex，哪些任务需要你自己把关。

很多新手第一次接触 Codex 时，最大的问题不是不会操作，而是不知道“自己到底可以拿它做什么,如何切入实际的业务场景”。

所以这一章的重点，不是讲技术，而是帮你打开使用思路。

2.1 先问“能帮我省什么事”

很多人接触新工具时，第一反应是：

它厉不厉害？

它能不能代替人？

它是不是比别的 AI 更强？

这些问题当然重要，但对新手来说，真正更有价值的问题其实是：

它能帮我省掉哪些麻烦？

因为大多数人使用 Codex，不是为了研究模型，也不是为了做技术评测，而是为了把事情做得更快、更顺、更清楚。

比如你平时可能会遇到这些麻烦：

• 文档太乱，不知道从哪里整理。
• 文件太多，不知道重点看哪个。
• 数据拿到了，但不会分析。
• 想做个网页，不知道怎么开始。
• 有了一个想法，但不会拆步骤。
• 写了一堆内容，语言不够清楚。
• 看到项目目录就头大，不知道先看什么。

这些地方，正是 Codex 最容易发挥价值的地方。

所以新手不要一上来就神化它，也不要低估它。最好的理解方式是：

把 Codex 看成一个能帮你节省时间、减少混乱、提高执行效率的助手。

2.2 整理文档和资料

这是最适合新手上手的能力之一。

很多人以为 Codex 只能处理技术内容，其实它在整理文字材料这件事上也非常好用。尤其当你手里已经有一份文档、一些截图、一些零散笔记时，它特别适合帮你做这些事：

• 重组目录。
• 补充前言。
• 改写语气。
• 把专业表达变成小白能懂的话。
• 提炼重点。
• 把零散内容整理成结构化说明。
• 根据现有素材继续扩写。

比如：你已经有了一份word、PPT或飞书文档，也有不少截图和素材，但它现在更像课件，而不是适合阅读的教程。这时候 Codex 的作用就不是“重新发明内容”，而是帮你把已有材料整理成更易读、更有顺序的版本。

对很多新手来说，这类任务会比“写程序”更容易上手，因为你更容易判断结果好不好。读起来顺不顺、能不能看懂、逻辑清不清楚，这些你马上就能感受到。

2.3 处理文件和理解项目

如果你打开一个陌生目录就头疼，那么 Codex 在这一类任务上会特别有帮助。

很多真实工作都不是从零开始的，而是从一个现成项目、一个现成资料夹、一个现成代码仓库开始。问题在于，新手最怕的就是“看不懂”。

这时候，你可以让 Codex 帮你做这些事：

• 查看目录结构。
• 解释每个文件大概是干什么的。
• 找出关键入口文件。
• 总结当前项目的组成。
• 帮你判断哪些文件先看，哪些可以先不看。
• 把复杂结构用更容易理解的话说出来。

这对新手非常重要，因为很多人并不是不会学，而是一上来就被复杂结构吓住了。Codex 在这里的价值，就是帮你先把陌生环境变成熟悉环境。

你可以把它理解成：你走进一个很乱的房间，它先帮你把东西分类，再告诉你哪几样最重要。

2.4 分析数据和生成结果

这也是一个特别适合初学者的场景。

很多人手上都会碰到表格、CSV、销售数据、名单、统计表，但拿到数据以后常常不知道怎么下手。尤其是不会代码的人，看到数据文件就容易发懵。

这时候，Codex 可以帮你：

• 读取数据文件。
• 看看有哪些字段。
• 帮你找出异常值、重点值、趋势变化。
• 根据需求生成分析结论。
• 把结果做成更容易读懂的页面或报告。

比如你给它一个 CSV 文件，你可以不只是说“帮我分析一下”，而是说得更清楚一点：

• 帮我找出销量最高的产品。
• 帮我比较不同月份的变化。
• 帮我生成一个适合汇报的 HTML 图表页面。
• 帮我总结这份数据里最值得关注的三个发现。

对新手来说，这类任务很有成就感，因为结果通常比较直观。你不是只得到一段抽象解释，而是能得到图表、页面、总结、结论这些看得见的成果。

2.5 生成网页、原型和小工具

这是很多人第一次对 Codex 产生“真有用”感觉的场景。

因为网页、小游戏、工具页这些东西，一旦做出来，结果是能直接看见的。你不是只得到一个概念，而是得到一个实际页面。

你可以让 Codex 帮你做很多入门级任务

• 生成一个介绍页。
• 生成一个静态 HTML 页面。
• 做一个简单的小游戏。
• 做一个小工具页面。
• 做一个数据展示页面。
• 根据你的想法先做出一个初版原型。

这个场景特别适合新手，因为它有两个优点：

• 反馈快，做出来马上就能看。
• 容易迭代，不满意就继续让它改。

这类任务的关键不是一遍做完，而是“先做出来，再继续改”。这正好符合 Codex 的工作方式。

2.6 代码开发

Codex 的核心使用场景：代码开发。

• 写代码、改代码
• 查问题、做重构
• 补注释、解释报错
• 检查逻辑、优化结构

但对新手来说，这一块不要一上来就当成唯一入口。因为如果你完全没有基础，直接扑到最复杂的代码任务上，容易被打击。

更适合的顺序是：

• 先拿它整理文档、分析数据、生成页面。
• 再逐步接触简单代码任务。
• 再学习怎么让它协作完成更完整的开发任务。

这样会轻松很多。

也就是说，代码开发是 Codex 的核心能力之一，但对新手来说，它不一定是最先开始的能力。

2.7 把任务“往前推进”

如果要用一句话总结这一章，那就是：

Codex 最有价值的地方，不是它能不能回答一个问题，而是它能不能把一个任务一步步往前推进。

给一个模糊目标，它可以帮你拆步骤。

给一份素材，它可以帮你整理结构。

给一个页面需求，它可以先做初版。

给一个数据文件，它可以先读、再分析、再输出结果。

给一个项目，它可以先帮你理解，再继续协作。

所以，学习 Codex 的关键不是背它有哪些功能，而是慢慢形成一种工作习惯：

• 先明确目标
• 再提供材料
• 然后让它先给初版
• 再根据结果继续调整

这才是最接近真实工作的用法。

2.8 本章小结

这一章你只需要记住四件事：

• Codex 的能力范围很广，不只是写代码。
• 对新手最友好的入口，通常是文档整理、文件理解、数据分析和页面生成。
• 它最有价值的地方，不是回答一个问题，而是持续推进一个任务。
• 学会把“问问题”变成“交任务”，你才会真正感受到 Codex 的威力。

下一章，我们继续往下看：Codex 到底有哪几种形态，以及新手应该从哪一种开始上手。

第3章 Codex 的三种形态

3.0 本章你会学到什么

学完这一章，你会知道 Codex 常见的三种使用形态：

• 桌面版 APP
• 命令行 CLI
• IDE 插件

你还会明白它们各自适合什么人、有什么优缺点，以及新手应该先从哪一种开始。

这一章不追求把所有细节讲完，而是先帮你建立一个清楚判断：同样是 Codex，不同入口的使用体验差别很大。选对入口，学习会轻松很多。

3.1 为什么 Codex 会有不同形态

桌面版 APP、终端 CLI、IDE 插件，本质上是同一类 Codex 能力的不同入口。

很多新手会问一个问题：

既然都是 Codex，为什么还要分桌面版、命令行版、插件版？

原因很简单：不同用户的工作习惯不一样。

有的人喜欢图形界面，希望打开软件就能点点点；有的人经常用终端，希望直接在命令行里操作；还有的人每天都在编程软件里工作，希望 AI 能直接嵌到 IDE 里。

所以，Codex 并不是只提供一种入口，而是根据不同使用场景，提供了不同形态。

你可以把它们理解成同一个能力的三种入口：

• 桌面版 APP：像一个完整软件。
• 命令行 CLI：像一个终端工具。
• IDE 插件：像嵌在开发工具里的助手。

它们背后的目标都差不多，都是为了让 AI 帮你完成任务。但因为入口不同，使用体验会有明显差异。

对新手来说，最重要的不是马上研究所有版本，而是先选一个最适合自己上手的入口。

3.2 桌面版 APP：最适合新手的入口

桌面版 APP 是最适合新手开始的形态。

它最大的优点是：界面直观，操作成本低。

你不用一上来就记命令，也不用理解太多终端概念。打开软件以后，你通常可以直接看到项目、会话、设置、模型、工具等入口。很多配置也能通过界面完成，对小白更友好。

桌面版 APP 适合下面这些人：

• 第一次接触 Codex 的新手。
• 不熟悉命令行的人。
• 想用 Codex 做文档、数据、网页、案例整理的人。
• 希望一边看界面一边学习的人。
• 不想一开始就被配置文件和终端命令吓住的人。

它适合处理很多入门任务，比如：

• 让 Codex 整理一份文档。
• 让 Codex 生成一个 HTML 页面。
• 让 Codex 分析 CSV 数据。
• 让 Codex 帮你拆解项目步骤。
• 在多个项目之间切换工作。

对新手来说，桌面版 APP 的优势不是“功能一定最多”，而是“学习阻力最小”。你先用它跑通几个真实任务，再回头理解 CLI 和配置，会轻松很多。

3.3 命令行 CLI：更适合进阶用户和自动化场景

CLI 是 Command Line Interface 的缩写，也就是命令行界面。

简单说，命令行版 Codex 是通过终端、PowerShell、命令提示符等方式来运行的。它看起来没有桌面版那么直观，但灵活性更强。

CLI 适合下面这些人：

• 熟悉终端操作的人。
• 经常做开发的人。
• 需要在项目目录里快速启动 Codex 的人。
• 想把 Codex 和脚本、自动化流程结合的人。
• 不介意用命令来控制工具的人。

它的优势是：

• 启动快。
• 更贴近开发环境。
• 适合放进自动化流程。
• 适合在服务器、远程环境或纯终端环境使用。
• 对高级用户来说，操作效率很高。

但对小白来说，CLI 最大的问题也很明显：门槛稍高。

你需要知道什么是终端，什么是目录，什么是命令，甚至可能还要处理环境变量、权限、路径这些问题。不是不能学，而是不建议完全零基础的人一上来就从 CLI 开始。

如果你已经会用 PowerShell、终端、cd 进入目录，那么 CLI 会很好用。

如果你看到黑窗口就发怵，那就先用桌面版 APP，别跟自己较劲。

CLI 的安装方式会随版本调整，最稳的做法是打开官方文档确认当前命令。常见方式包括 npm 和 Homebrew，其中 npm 方式通常最通用（详细安装见第 4 章）：

# npm 方式（需要先安装 Node.js）
npm install -g @openai/codex

如果你使用 macOS，也可以查看官方文档是否提供 Homebrew 安装命令。教程里凡是涉及安装命令，都建议以官方页面的最新说明为准。

3.4 IDE 插件：适合已经在写代码的人

IDE 插件是指把 Codex 嵌入到开发工具里使用。

IDE 可以简单理解成“写代码的软件”，比如 VS Code、JetBrains 系列工具等。插件版的优势是：你写代码的时候可以直接调用 AI，不需要频繁切换窗口。

IDE 插件适合下面这些人：

• 已经会写代码的人。
• 长时间待在开发工具里的程序员。
• 想让 AI 辅助补代码、改代码、解释代码的人。
• 想在编辑器里直接完成代码协作的人。

它适合的任务包括：

• 解释当前代码。
• 补全函数。
• 修改一段逻辑。
• 根据报错定位问题。

IDE 插件最大的价值在于"上下文跟手"——你光标停在哪一段代码上，AI 就围绕那段工作。但它不替代桌面版 APP 和 CLI：在 IDE 里更适合做"局部"修改，整体项目理解、跨文件改写、复杂任务推进，仍然是桌面版 APP 或 CLI 更顺手。

如果你完全没写过代码，IDE 插件可以放到最后再考虑，不用着急。

3.5 新手怎么选

如果你还没决定从哪个入口开始，按下面三句话挑：

• 没编程基础 → 先用桌面版 APP。学习阻力最小，跑通几个真实任务再说。
• 有终端基础或想做自动化 → 直接上 CLI。命令几行就能装好。
• 每天都在写代码 → 装 IDE 插件配合现有工作流。

三种形态不是互斥的，熟练之后通常会同时用：APP 推进项目、CLI 做脚本、IDE 写代码时随手补全。但起步阶段只挑一个，别一上来就全装，否则容易在配置上耗光耐心。

3.6 本章小结

这一章你只需要记住三件事：

• Codex 有桌面版 APP、命令行 CLI、IDE 插件三种形态，背后能力一致，入口不同。
• 形态决定使用门槛：APP 最低、CLI 中等、IDE 插件需要先有代码基础。
• 新手起步选一个就够，跑通真实任务比"全部装上"重要得多。

下一章我们就开始动手装 Codex，先把"能用起来"这件事彻底搞定。

第4章 安装 Codex 的基本流程

4.0 本章你会学到什么

学完这一章，你会完成两件事：

• 在自己的电脑上把 Codex 装好。
• 完成第一次登录和第一次对话。

不需要先看懂所有原理，按步骤走一遍，遇到坑了再回头看说明就够了。

4.1 装之前先确认三件事

正式装之前，花两分钟确认这几样，能避免 80% 的坑：

• 操作系统：Codex 桌面版 APP 当前主要支持 macOS 和 Windows；CLI 在 macOS、Windows、Linux 上都能跑。
• 网络环境：Codex 需要访问 OpenAI 的服务，网络问题不在本教程讨论范围，请自行解决到能稳定访问的程度。
• OpenAI 账号：需要一个能登录 ChatGPT 的账号，或可用的 OpenAI API Key。不同套餐、额度和可用功能会调整，实际以 Codex 客户端提示和官方文档为准。

确认好这三样，再往下走。

4.2 桌面版 APP 安装（推荐新手）

新手优先选这条路。

macOS：

1. 打开 Codex 官网下载页（在 ChatGPT 桌面版的设置里也能找到入口）。
2. 下载 .dmg 安装包，双击打开，把图标拖到"应用程序"。
3. 第一次打开时如果提示"无法验证开发者"，到"系统设置 → 隐私与安全性"里点"仍要打开"。

Windows：

1. 下载 .exe 安装包。
2. 双击运行，按向导一路下一步即可。
3. 如果 Defender 弹窗，选"仍要运行"。

装完后桌面或开始菜单会有 Codex 图标，双击启动。

4.3 CLI 安装

如果你愿意用命令行，CLI 装起来其实更快。

npm（通用方式）：

# 需要先安装 Node.js LTS 版本
npm install -g @openai/codex

Homebrew（macOS，可选）：

# 如果官方 CLI 文档当前提供 Homebrew 命令，按官方页面执行
# 不同版本命令可能变化，这里不要死记

装好后打开终端，输入：

codex --version

能看到版本号，就说明装成功了。

4.4 第一次登录

不管你装的是 APP 还是 CLI，第一次都需要登录。

APP：启动后点"Sign in"，会跳浏览器完成 OAuth 登录，回到 APP 就能看到主界面。

CLI：在终端输入 codex 进入交互界面，按提示选择 ChatGPT 登录或 API Key 登录。ChatGPT 登录会跳浏览器完成授权；API Key 登录则需要你粘贴自己的 key。

新手优先用 ChatGPT 登录，路径更直观；如果你本来就在用 OpenAI API，也可以选择 API Key。具体入口名称可能随版本变化，跟着客户端提示走就好。

4.5 跑第一句话

装完、登录完，先做一个最小验证，确认整条链路通了。

打开 APP 或在终端输入 codex，进入对话框输入：

你好，请用一句话介绍你自己。

只要 Codex 回了一段中文自我介绍，就说明：网络通了、登录有效、模型能用。这一刻起，你就可以开始正式学了。

4.6 常见安装报错

记住三类最常见的卡点，遇到的时候不用慌：

• 下载/打开提示安全警告：macOS 在"系统设置 → 隐私与安全性"里放行；Windows 在 Defender 弹窗里选"仍要运行"。
• codex 命令找不到：通常是 npm 全局路径没加进 PATH。重启终端，或者改用 Homebrew 安装。
• 登录后无响应 / 一直转圈：99% 是网络问题，换网络环境再试。

更复杂的报错排查会在第 11 章统一处理，这里不展开。

4.7 本章小结

• 装 Codex 前，先确认操作系统、网络、账号三件事。
• 新手优先桌面版 APP；愿意用命令行的直接 CLI。
• 装完一定要跑一句"你好"做最小验证。
• 报错绝大多数是网络或权限，别一上来就怀疑工具本身。

下一章带你认识桌面版 APP 的操作界面，把每个常用按钮先过一遍。

第5章 Codex APP 的操作界面

5.0 本章你会学到什么

学完这一章，你能：

• 认识 Codex APP 主界面的每个区域。
• 知道项目、会话、模型、设置都在哪。
• 学会切换会话、切换模型、关联本地项目这三个最常用的操作。

界面会随着版本迭代略有变化，下面以教程截稿时的版本为准，但主要分区基本稳定。

5.1 主界面分区

打开 APP 后，界面大致分成三块：

• 左侧：项目与会话列表。上半部分是你关联过的本地项目，下半部分是这些项目下的历史会话。
• 中间：对话主区域。你输入提示词、Codex 回复内容、显示工具调用与文件改动的地方。
• 右上：模型与设置入口。可以切换模型、调整工作模式、打开偏好设置。

新手第一次打开容易被信息量吓到，记住一个原则：所有操作都从左到右看，先选项目、再选会话、最后在中间区域开干。

5.2 关联第一个项目

Codex 不像聊天 AI 一样"零上下文"，它的强项是结合本地文件夹来工作。所以第一步先把项目关联进来：

1. 点左上角"+"或"New Project"。
2. 选择本地一个文件夹（一个普通的、用来放教程练习的目录就行）。
3. 关联完成后，Codex 会读取目录结构，作为之后所有对话的上下文。

第一次练习建议新建一个空文件夹，比如 ~/codex-练习/，避免直接拿工作项目试手。

5.3 新建与切换会话

每个项目下可以有多个会话，建议一个任务一个会话，不要全部塞在同一个会话里：

• 会话内的上下文会一直累积，太长容易让 AI 跑偏。
• 不同任务分开，回头查找历史时也清楚。

切换会话时，左侧列表点一下就行；新建会话点项目名右边的"+"。

5.4 切换模型

右上角能选模型。常见的几档：

• 高能力模型：适合复杂任务、大段代码、长文档处理。
• 通用模型：日常使用，速度和质量相对平衡。
• 轻量模型：速度快、成本低，适合简单整理、批量小任务。

具体模型名称会随 Codex 版本和账号权限变化，新手不必纠结，先用默认模型跑通；等到感觉某个任务"明显不够聪明"或"明显太慢"时再切。

5.5 工作模式开关

界面里通常还有几个常用开关：

• 联网 / 浏览器：开启后 Codex 可以访问网页查资料。
• 写文件 / 执行命令：决定 Codex 能不能直接改你的本地文件、跑命令。
• Plan 模式：先让它给计划，确认后再执行，适合复杂任务。

新手默认建议：保持"写文件"为允许、"执行命令"先关或设为"每次询问"，等熟悉之后再放开。

5.6 本章小结

• 主界面三块：左侧项目/会话、中间对话、右上模型与设置。
• 一个任务一个会话，避免上下文混乱。
• 关联本地项目是 Codex 真正发挥能力的前提。
• 模型和权限别一上来就拉满，跑通再优化。

下一章我们看一下 Codex 在你电脑里"住"在哪，了解一下安装目录和配置文件，为第三部分的 AGENTS.md / 配置进阶做铺垫。

第6章 Codex 的安装目录详解

6.0 本章你会学到什么

学完这一章，你会大致知道：

• Codex 在你电脑上把文件放在哪。
• 哪些文件你可以放心动，哪些最好别碰。
• 配置文件 config.toml、凭证 auth.json 大概是什么角色。

这一章不要求你去动配置，只要先知道它们存在、知道在哪就够了。

版本说明：本章按 2026-05-21 复查到的 OpenAI Codex 官方配置文档整理。Codex CLI、桌面 App、IDE 扩展和插件生态都可能继续变化，发布前需要用当前版本在真机上复核目录清单。

6.1 配置目录在哪

Codex 把用户级配置放在一个统一目录，路径和系统有关：

• macOS / Linux：~/.codex/
• Windows：%USERPROFILE%\.codex\（通常是 C:\Users\你的用户名\.codex\）

打开看一眼，里面常见这些文件和子目录：

• config.toml：用户级配置（模型、权限、MCP、日志等）。
• auth.json：登录凭证（账号 token / API Key），绝对不要外发或截图。
• sessions/：本地保存的会话记录。
• logs/：运行日志，排查问题时会用到。
• skills/：可能出现的 Skills 目录，是否存在取决于当前 Codex 版本、安装方式、插件和个人配置。

具体文件名可能随版本略有差异，不要把本章列表当成永久固定清单。发布前最好记录实际 Codex 版本号和目录截图。

6.2 哪些可以动，哪些别动

按"风险从低到高"排：

• 可以放心看、可以动：config.toml（改之前先备份）、logs/（可以删旧日志）。
• 可以看，建议不动：sessions/（删了会丢历史）、skills/（如果存在，优先用 Codex 当前支持的 Skill 管理方式处理，别手动删）。
• 绝对不要碰：auth.json。这文件等于你的登录凭证，泄露相当于把账号交出去。

如果你不知道该不该改某个文件，默认就别改。Codex 的大部分配置都能在 APP 设置里完成，不需要直接编辑文件。

6.3 项目级配置：AGENTS.md

除了用户级 ~/.codex/，每个项目目录里还可以放项目级配置：

• AGENTS.md：告诉 Codex 这个项目的背景、规范、注意事项。
• PLAN.md：把当前任务拆成步骤，配合 Plan 模式使用。

这里要先区分清楚：AGENTS.md 是 Codex 官方文档明确说明会读取的项目说明文件；PLAN.md 是本教程采用的任务拆解约定，本身不是 Codex 自动识别的官方配置文件。要让 Codex 按 PLAN.md 工作，需要在提示词里显式引用它，比如 请阅读 @PLAN.md 后执行步骤 1。

这两个文件是第三部分（第 13、14 章）的重点，这里先知道它们放在你的项目目录里，跟随项目走，不在 ~/.codex/ 里。

6.4 配置文件长什么样

这里给一个最小 config.toml 示例，不要求你看懂，只要先有印象：

# 默认模型
model = "gpt-5.5"

# 运行命令前是否需要确认
approval_policy = "on-request"

# 本地命令的沙盒权限
sandbox_mode = "workspace-write"

具体可用字段会随版本变化。看到不熟悉的字段，先查官方配置文档或本书资料包附录 G，不要凭感觉改。

6.5 备份与迁移

换电脑或重装系统时，下面三样最值得备份：

• ~/.codex/config.toml：你调过的配置。
• ~/.codex/skills/：如果你的环境实际存在这个目录，再备份你确认可迁移的个人 Skill。
• 你电脑上各个项目目录里的 AGENTS.md / PLAN.md（这些通常已经在 git 里了）。

auth.json 不要跨设备复制，新设备重新登录即可。

6.6 本章小结

• Codex 的用户级配置在 ~/.codex/，按系统略有不同。
• config.toml 可改、auth.json 千万别外泄、logs/ 排查时翻一下。
• AGENTS.md 是项目说明文件，PLAN.md 是任务计划约定；两者跟着项目走，不在 ~/.codex/。
• 不知道该不该动的文件，默认就别动。

第一部分到这里就完整了：你已经知道 Codex 是什么、能做什么、有哪些形态、怎么装、界面长什么样、文件放在哪。下一部分我们正式动手，从一句话开始做出第一个完整页面。

第二部分：小白先学会"怎么用"

第一部分让你知道了 Codex 是什么、怎么装。这一部分换个节奏：别再读概念，开始动手。

我们会通过 5 个章节，把你从"打开 Codex 不知道说什么"带到"能把一个完整任务交给它做完"。每一章都围绕一个具体场景：写页面、分析数据、提需求、改重构、处理报错。看到代码不要慌，跟着抄一遍就行。

第7章 从一句话到完整页面

7.0 本章你会学到什么

学完这一章，你会：

• 用一句话生成一个能在浏览器里打开的 HTML 页面。
• 学会"先粗后细"的迭代方式，不指望一次说清所有需求。
• 知道遇到不满意结果时，怎么继续让它改。

整章会跟着一个完整案例走：做一个个人介绍页。

7.1 准备：建一个练习目录

打开 Codex APP，关联（或新建）一个空目录，比如：

~/codex-练习/01-介绍页/

养成"一个任务一个目录"的习惯。混在一起以后找东西要命。

7.2 第一版：先让它跑出来

新建一个会话，输入下面这段提示词。别加修饰，先看它做出什么：

帮我做一个个人介绍页面，用单文件 HTML，放在当前目录里，
名字叫 index.html。要有：标题、一句简介、三个特长、一个联系方式。
风格简洁，不用引入外部框架。

按回车，Codex 会做几件事：

• 说明它打算怎么做。
• 写出 index.html 文件。
• 告诉你文件放在哪。

这时双击 index.html 用浏览器打开，你会看到一个朴素但完整的页面。这就是第一版基线。

7.3 第二版：把不满意的地方说具体

第一版多半"能用但难看"。新手最容易犯的错是说："不好看，重做。"——AI 听不懂"不好看"。

正确的做法：指出具体问题 + 给方向。比如：

当前页面有几个问题，请改：
1. 标题字号太小，加大一倍，并居中。
2. 三个特长改成卡片样式，三列横排，鼠标悬停时背景变浅灰。
3. 整页加最大宽度 720px、左右居中，背景换成淡米色。
4. 手机上访问时，三个卡片自动变成一列。

Codex 会直接改 index.html，不会重新生成一个新文件。刷新浏览器就能看到新效果。

7.4 第三版：加内容、加交互

页面骨架满意了，再往里加东西：

继续改 index.html：
1. 在联系方式上方加一个"作品展示"区，放 3 张占位图（用 picsum.photos 生成）。
2. 页面顶部加一个深色导航条，包含"关于我 / 特长 / 作品 / 联系"四个锚点。
3. 点击锚点要平滑滚动到对应区块。

到这一步，你已经有一个像样的个人主页了。整个过程你没写一行代码，全靠和 Codex 对话推进。

7.5 三个新手最常踩的坑

坑一：一次性堆需求 第一句就要求"做一个有动画、有暗色模式、能切换语言、带视差滚动的高级页面"，结果生成出来哪哪都对不上预期。 对策：先让它做最小版本，再分轮迭代。

坑二：用感受代替指令 "再好看一点""再现代一点""再有质感一点"——这些 AI 接不住。 对策：换成具体描述，比如"主色换成 #1f2937""卡片加 8px 圆角和淡阴影""字体改成 system-ui"。

坑三：忘了让它打开看效果 有些需求 Codex 改完自己也不知道效果对不对，比如响应式。 对策：直接告诉它"改完用 Codex 自带浏览器打开 index.html，截一张手机宽度的图给我看"，让它闭环验证。

7.6 本章小结

• 做页面别一次说完，第一版求"出来"，后续求"对"。
• 反馈用具体描述代替主观感受。
• 一句话能起步、十句话能细化、几十句话能做完——这就是 Codex 的工作方式。

下一章换个场景：拿到一份 CSV，怎么让 Codex 帮你分析并生成图表报告。

第8章 CSV 数据分析与 HTML 图表报告

8.0 本章你会学到什么

学完这一章你会：

• 把一份 CSV 交给 Codex，让它读懂、清洗、分析。
• 生成一个带图表的 HTML 报告，能直接发给同事或老板。
• 学会"提供数据 + 提供问题"的标准提需求方式。

8.1 准备一份 CSV

如果你手头没有数据，让 Codex 自己造一份练手用的：

帮我在当前目录生成一个 sales.csv，模拟某店铺 2025 年 1-12 月的
销售数据。字段包括：月份、品类（3 种）、销售额、订单数。
数据要有合理波动，比如夏天饮料品类高、冬天保暖品类高。

跑完会有一个 sales.csv，36 行左右。这就是后面所有分析的输入。

8.2 第一步：让它先"读懂"

新手最容易做的事是上来就喊"分析一下"。Codex 会做，但你不知道它分析的对不对。正确的第一步是先让它告诉你看到了什么：

读取 sales.csv，告诉我：
1. 共有多少行、多少列。
2. 每列的字段名和数据类型。
3. 数值列的最小值、最大值、平均值。
4. 有没有空值或异常值。

Codex 会输出一份"数据体检报告"。你确认数据没问题，再往下走。

8.3 第二步：提具体业务问题

不要说"分析一下销售情况"，要说你到底想知道什么：

基于 sales.csv 回答以下问题：
1. 全年销售额最高的是哪个品类？高出第二名多少？
2. 每个品类的销售额峰值出现在哪个月？
3. 总订单数和总销售额按月的趋势分别是怎样的？
4. 客单价（销售额/订单数）哪个月最高？

Codex 会逐条回答，并解释计算过程。这一步不要急着做图表，先确认结论是对的。

8.4 第三步：生成图表报告

确认结论无误，再让它做成可视化报告：

基于上一步的分析结论，生成 report.html，要求：
1. 单文件 HTML，图表用 Chart.js 的 CDN 引入。
2. 顶部一句话总结全年最重要的发现。
3. 四张图：
   - 月度销售额趋势（折线图）。
   - 各品类全年销售额对比（柱状图）。
   - 各品类月度销售额堆叠（堆叠柱状图）。
   - 客单价月度变化（折线图）。
4. 每张图下方配一句解读，不超过 30 字。
5. 整体配色用低饱和度商务风。

跑完打开 report.html，你会得到一个能直接发给老板的报告。需要 PDF？再说一句"把它转成 PDF"即可。

8.5 把这套流程沉淀成模板

如果以后还要做类似分析，把上面三步存成一个模板提示词：

我会给你一份 CSV，请按以下流程处理：
第一步：读取并输出"数据体检报告"（行列数、字段类型、空值、极值）。
第二步：等我给具体业务问题后再做计算，每条结论都说明计算逻辑。
第三步：等我确认结论后再生成 report.html，要求：单文件、Chart.js CDN、
        顶部摘要、每图配解读、低饱和度配色。

下次直接 paste 这段 + 一个 CSV，10 分钟一份图表报告。这就是把经验变成可复用资产。

8.6 三个新手最容易卡住的点

• CSV 编码问题：中文 CSV 用 GBK 保存的，Codex 读出来全是乱码。让它读之前先转 UTF-8，或直接告诉它"以 GBK 编码读取"。
• 数据量过大：百万行级别 CSV 让 Codex 直接读容易超时。先让它写个脚本采样或聚合，再分析。
• 图表显示不出：常见原因是 CDN 拉不下来。换 jsDelivr 或本地 chart.umd.js 都行。

8.7 本章小结

• 分析数据三步走：先体检 → 再问问题 → 最后做报告。
• 每一步都先让 Codex 输出可验证的中间结果，别一步到位。
• 把成功流程沉淀为模板提示词，下次直接复用。

下一章我们专门讲一件事：怎么和 Codex 说清楚你的需求——这是新手最值得反复练的能力。

第9章 怎么和 Codex 说清楚你的需求

9.0 本章你会学到什么

学完这一章，你能：

• 用一个简单结构组织任何提需求的句子。
• 看出"模糊需求"和"清楚需求"的差别在哪里。
• 存下一组随时能复用的提示词模板。

提需求是 Codex 使用里最值得练的元能力。工具会迭代，模型会换代，但"把事情说清楚"这件事一辈子都用得上。

9.1 一个能套到任何任务上的五要素

任何提需求的句子，都可以套这五个要素，缺一个就容易跑偏：

1. 身份：你希望 Codex 扮演什么角色？（前端工程师 / 数据分析师 / 文档编辑）
2. 目标：要做出什么？最终交付物是什么？
3. 输入：手头有哪些素材、文件、约束条件？
4. 输出：要什么格式？文件名？字数？放在哪个目录？
5. 约束：什么不能做、什么必须做？风格偏好？

新手不必每次写得很长，但心里要过一遍。漏哪个就在哪个上栽跟头。

9.2 模糊 vs 清楚：同一个需求两种说法

模糊版（差）：

帮我写一个登录页。

清楚版（好）：

你是前端工程师。请在当前目录生成 login.html，单文件，
不引入框架，用原生 HTML/CSS/JS。包含：邮箱、密码、登录按钮、
"忘记密码"链接。点击登录时做前端校验：邮箱格式、密码至少 8 位，
失败时在输入框下方显示红色提示。整体风格简洁，主色 #2563eb，
最大宽度 360px 居中。

第二段长，但 Codex 一遍就能做对，省掉来回改三轮的时间。长不是啰嗦，长是省时间。

9.3 用"先粗后细"代替"一次到位"

不是每次都得写一大段。复杂任务反而要分轮：

• 第 1 轮：身份 + 目标 + 最少必要信息，先看雏形。
• 第 2 轮：基于雏形指出具体问题，给改的方向。
• 第 3 轮：细节打磨，比如配色、文案、边界情况。

第 7 章的页面案例就是这个套路。新手最常见的错误，是把所有细节塞进第一轮——结果 Codex 抓不住重点。

9.4 三个万能补充句

不知道在末尾加什么时，加这三句，效果立竿见影：

• "先列你打算怎么做的步骤，得到我确认后再动手。"
• "做完后告诉我改了哪些文件、为什么这么改。"
• "如果有不确定的地方，先问我，不要猜。"

这三句一加，AI 从"埋头乱做"变成"按计划做事"。

9.5 一组能直接拿走的模板

写文档：

你是文档编辑。请基于 [素材文件] 生成 [输出文件名]，目标读者是 [人群]，
风格 [口语/正式]，长度约 [字数]。结构包括 [章节]。
不要 [禁止项]，必须 [硬性要求]。

改代码：

你是 [语言] 工程师。请修改 [文件名] 的 [函数/区块]，目标是 [业务效果]。
当前问题是 [现象]。修改时只动 [范围]，其他保持不动。改完跑一下 [测试命令]。

做分析：

你是数据分析师。基于 [数据文件] 回答 [问题列表]，每条结论说明计算逻辑。
最后输出 [报告格式]，附 [图表类型] 可视化。

把这三个模板存起来，覆盖 80% 日常需求。

9.6 本章小结

• 提需求五要素：身份、目标、输入、输出、约束。
• 清楚的指令一次顶三轮模糊指令。
• 复杂任务分轮做，简单任务用模板套。
• 不会写收尾时，记得加"先列计划""说明改动""有问题先问"三件套。

下一章讲一个紧接着的话题：当你想改、想补、想重构现有内容时，怎么让 Codex 精准动刀。

第10章 学会让 Codex 修改、补充和重构内容

10.0 本章你会学到什么

学完这一章，你能区分三种动作并用不同方式表达：

• 补：在现有内容上加东西。
• 改：替换或修正某一部分。
• 重构：保持结果不变，重组结构。

这三种动作走错路，最容易出现"我只想改一行，它把整个文件重写了"的灾难。

10.1 三个动作的核心差别

新手常犯的错：心里想"补"，嘴上说成"重写一下"。Codex 真的就给你重写了。

10.2 "定位 + 范围"是关键

无论补、改还是重构，都要把"动哪里"说清楚：

请修改 index.html：
- 定位：导航条里的"作品"链接。
- 动作：把它的链接地址从 #works 改成 /works.html。
- 范围：只动这一处，其他不要碰。

句子里"定位""动作""范围"三件套写齐，就基本不会改飞。

10.3 补内容：在哪插，插什么

补充内容时，告诉它"插在哪个标记之后"，比"在文档里加一段"清楚十倍：

在 README.md 的"## 安装"小节末尾追加一段：
- 内容：补充 Windows 用户的额外步骤，包含三条要点（管理员权限、关闭杀毒、PATH）。
- 风格：跟现有段落保持一致，使用同样的 -   列表前缀。

10.4 改内容：先看，再改

改之前，先让它把要改的部分念给你听，确认对了再动手：

我要改 user.py 里 register 函数的密码校验逻辑。
请先把当前实现贴给我看，并说明你打算怎么改、为什么这么改。
我确认后再动手。

这是 Codex 用得最爽的方式之一。让 AI 先打草稿，再写正式版。

10.5 重构：只能改结构，不能改行为

重构的关键约束是"对外效果不变"。这一句必须写进提示词：

请重构 utils.js：
- 目标：把里面的工具函数按"日期/字符串/数组"分到三个文件。
- 约束：所有对外暴露的函数名、参数、返回值不变。
- 验证：改完后告诉我每个函数现在在哪个文件，方便我更新引用。

如果项目里有测试，再加一句"改完跑一遍测试，全部通过再提交"，闭环就关上了。

10.6 出错了怎么回滚

Codex 改坏了不要慌。如果项目用 git，第一时间用 git 回滚：

# 看看刚才改了哪些文件
git status
git diff

# 想全部回到改之前的状态
git checkout .

# 只回滚某一个文件
git checkout -- path/to/file

不会用 git 也行。让 Codex 帮你：

我对刚才的改动不满意，请把 index.html 恢复到我们这次会话开始前的样子。

它会从会话历史里找回原版。所以重要项目一定要先 git init——这是后悔药。

10.7 本章小结

• 动手前先分清是补、改、还是重构。
• 提示词写齐"定位、动作、范围"三件套。
• 改之前让 Codex 先念一遍、再动手。
• 重构必须强调"行为不变"，并加验证环节。
• 重要项目先 git init，比后悔强。

下一章我们处理学 Codex 路上必遇的问题：报错。

第11章 常见报错和解决报错的思路

11.0 本章你会学到什么

学完这一章，你能：

• 分清三层报错（环境层 / 代码层 / AI 误解层），各自该怎么处理。
• 学会一套通用的排查动作，遇到陌生报错也能下手。
• 认识几个新手最常踩的具体报错。

报错不是失败，是 Codex 在告诉你"哪里不对"。看懂报错的人，进步速度比别人快好几倍。

11.1 三层报错，处理思路完全不同

先判断在哪一层，再决定怎么处理。新手最常见的错是"环境问题让 AI 改代码""AI 误解了需求却怪它代码烂"。

11.2 通用排查四步法

不管什么报错，按这个顺序做基本不会错：

1. 完整复制报错信息，包括上下几行。
2. 告诉 Codex 你刚才做了什么，别只贴报错。
3. 让 Codex 先解释报错的含义，再给修复方案。
4. 修完跑一遍最小验证，确认真的修好了。

对应的提示词长这样：

我刚才在执行 [命令/操作]，目的是 [目标]，结果出现下面的报错：

[完整报错粘贴]

请：
1. 解释这个报错是什么意思、为什么会出现。
2. 给出修复步骤。
3. 修复后告诉我怎么验证已经修好。

11.3 几个新手最容易撞上的具体报错

command not found: codex 环境层。99% 是 PATH 没配好。重启终端、换安装方式（Homebrew / npm）通常能解。

Permission denied（写文件 / 跑命令时） 环境层。两种可能：操作系统权限，或 Codex 配置里没允许写文件 / 执行命令。先去 APP 设置里把权限打开。

Module not found / Cannot find module 代码层但偏环境。多半是依赖没装。把报错完整贴给 Codex，让它告诉你装哪个包，再 npm install 或 pip install。

SyntaxError / IndentationError 代码层。Codex 自己改的代码偶尔会出这种问题，直接发给它："上一步生成的代码报了这个错，请定位行号并修复。"

API 报 401 / 429 环境层。401 是凭证问题，重新登录；429 是被限流，等一会儿或换模型。

"做出来了但不是我要的" AI 误解层。别让它一直改——回头读自己最初的提示词，多半是需求没说清。补一句"目标其实是 X，请按这个目标重新调整"。

11.4 让 Codex 自己看日志

Codex 会运行命令，遇到失败时，让它自己读日志比你眼睛去找快得多：

刚才那条命令失败了。请：
1. 读 logs/latest.log 的最后 100 行。
2. 找出第一个 ERROR 或 Exception。
3. 解释原因并给出修复方案。

这套用法在第三部分（Plan 模式、AGENTS.md）会再次出现。让 AI 自己闭环排查，是从"会用"到"用顺手"的分水岭。

11.5 什么时候该停下问人

碰到下面这些情况，别让 Codex 一直试，会越改越糟：

• 同一个报错改了 3 轮还在原地。
• 修着修着把不相关的代码也动了。
• 它开始绕圈子，给的方案前后矛盾。

这时候停下，把当前状态截图或导出，去社区问真人，或者起一个新会话重新开始。Codex 会跟着上下文走，长会话里的错误判断会一直延续。

11.6 本章小结

• 报错先分层：环境 / 代码 / AI 误解，三种处理思路完全不同。
• 通用四步法：贴完整报错 → 说清上下文 → 让它先解释再修 → 跑最小验证。
• 遇到僵局别硬刚，新建会话或问真人比死磕高效。

到这里第二部分就完整了。你已经能用 Codex 做页面、做数据分析、清楚地提需求、稳健地改重构、从容地处理报错。第三部分开始往"项目协作"走，你会学到 AGENTS.md、PLAN.md、四文档法则——这些是把 Codex 从"会用"提到"用顺手"的关键。

第三部分：从会用到用顺手

第二部分让你"能跑"。但只跑过几个小任务的人，遇到稍微大一点的项目就会发现：

• 每开一个新会话，要重新解释一遍项目背景。
• 任务做着做着跑偏，回头才发现是中间某一步走错了。
• 同一个项目里，不同会话之间互相不知道发生了什么。

第三部分解决的就是这些问题。我们会引入两类东西：

1. 快捷指令：让你在会话里更快下达常用动作。
2. 项目级文档：让 Codex 在不同会话之间也能"记住事"。

学完这部分，你的 Codex 用法会从"一次性对话"升级到"长期协作"。

第12章 Codex 的常用快捷指令

12.0 本章你会学到什么

学完这一章，你会熟练使用：

• 斜杠命令（/clear、/model、/help…）
• 文件引用（@文件名）
• 模式切换（Plan / Edit / Auto）
• 中断与回滚

这些指令省下来的不是几秒钟，是让你不必离开输入框就能控制全局。

12.1 斜杠命令：在输入框直接控制 Codex

输入框里第一个字符打 /，会弹出可用命令列表。常用的几条：

不同版本命令略有差异，忘了就打 /help，永远不会错。

12.2 用 `@` 引用文件，让 AI 看你想看的

直接说"看一下我的代码"，Codex 不知道指哪个文件。用 @ 显式引用：

帮我看 @src/utils.js 里 formatDate 函数有没有问题。

@ 后跟相对路径，Codex 会精确读那个文件，而不是"扫描整个项目找一找"。项目大的时候差别巨大——你点名了它就只看一处，没点名它会读一大堆，速度慢还容易跑偏。

引用多个文件：

对比 @src/api/v1.js 和 @src/api/v2.js，告诉我接口差异。

12.3 三种工作模式

Codex 通常有三种模式，按"自动度"递增：

• Plan 模式：只列计划、不动文件。适合复杂任务、不想被惊吓的时候。
• Edit / Approve 模式：每次改文件前问你一下，你点确认才执行。适合改正式项目。
• Auto / Agent 模式：自由读写、自由跑命令、自由迭代。适合练习项目或一次性脚本。

新手默认建议：

• 学习练习用 Auto，让它放开手脚。
• 碰真实项目用 Edit，避免被改飞。
• 规划阶段用 Plan，先看路线图再动手。

输入框附近通常有一个模式切换按钮，或者用 /plan、/auto 这类命令切换。

12.4 中断、撤销、回滚

Codex 跑歪了不要等它跑完。记住这三招：

• 中断：键盘 Esc（APP）或 Ctrl+C（CLI），立即停。
• 撤销当次回复：APP 里通常有"重试"或"删除最后一条"，删掉再重新提问。
• 文件回滚：项目用 git 时，git checkout -- 文件名 一键回滚（参考第 10.6 节）。

最稳的姿势：每次开新任务前 git commit 一下。Codex 跑得再野，git 都能拉回来。

12.5 一些值得养成的小习惯

• 会话开始第一句先说目标，别上来就堆细节。
• 长会话上下文跑偏时，直接 /clear 重开，比挣扎着拉回来快。
• 重要会话导出存档（APP 里通常有导出功能），方便回头复盘。
• 不要在同一个会话里频繁切换不相关的任务，会话越短越聚焦越准。

12.6 本章小结

• / 命令、@ 引用、三种模式、中断回滚，是控制 Codex 的"键盘快捷键"。
• @文件名 是让大项目里 AI 不跑偏的核心动作。
• 动手前 git commit，跑歪时不慌。

下一章开始进入"项目级文档"——AGENTS.md，让你的项目背景一次写好，长期生效。

第13章 项目目录的 AGENTS.md 是什么

13.0 本章你会学到什么

学完这一章，你会知道：

• AGENTS.md 是给 Codex 看的项目说明书。
• 它应该放在哪里。
• 里面应该写什么，不应该写什么。
• 怎么用一个最小模板，让 Codex 每次进入项目都少问很多背景问题。

从这一章开始，你会真正进入"项目级协作"。前面我们更多是在和 Codex 做一次性对话；有了 AGENTS.md，你就开始给项目建立长期规则。

13.1 为什么需要 AGENTS.md

很多新手第一次用 Codex 做项目时，会遇到一个很烦的问题：

每次开新会话，都要重新解释一遍项目背景。

比如你要做一个课程网站，你可能反复告诉它：

• 这是给小白看的教程。
• 文风要口语化，不要太技术。
• 文件放在 docs/ 目录。
• 不要随便改图片资源。
• 改完要先告诉我改了哪里。

说一两次还行，说十次就很累。更麻烦的是，你漏说一次，Codex 就可能按自己的理解乱改。

AGENTS.md 解决的就是这个问题：把项目里长期不变的背景、规则、偏好写下来，让 Codex 进入项目时先读它。

你可以把它理解成：

给 AI 同事看的项目入职手册。

人进项目要看 README，Codex 进项目也要看自己的说明书。AGENTS.md 就是这份说明书。

13.2 AGENTS.md 和 README.md 有什么区别

很多人会问：项目里不是已经有 README.md 了吗，为什么还要多一个 AGENTS.md？

区别很简单：

README.md 更像项目介绍。

AGENTS.md 更像协作说明。

举个例子，README.md 可以写：

# 小白记账工具

这是一个帮助新手记录日常收支的网页小工具。

而 AGENTS.md 可以写：

# AGENTS.md

## 项目背景

这是一个面向非程序员的小白记账工具，界面要简单，文案要直接。

## 协作规则

- 修改前先说明准备改哪些文件。
- 不要改动 `data/` 里的原始 CSV。
- 前端文案保持中文，避免技术术语。
- 改完后运行 `npm test`。

你看，后者明显是在告诉 Codex："你在这个项目里应该怎么干活。"

13.3 AGENTS.md 应该放在哪里

最常见的放法：放在项目根目录。

比如：

my-project/
├── AGENTS.md
├── README.md
├── src/
├── docs/
└── package.json

什么叫项目根目录？

简单理解，就是你平时打开 Codex 时关联的那个文件夹，也是项目最外层的文件夹。

如果项目很大，里面有多个子项目，也可以在子目录里放更细的 AGENTS.md 或覆盖说明。新手阶段先别复杂化，一个项目根目录放一个就够了。

还有一种全局写法：在 ~/.codex/AGENTS.md 里放你个人长期偏好，比如"默认用中文回复""解释时照顾新手"。但全局规则会影响很多项目，初学者更建议先从项目级 AGENTS.md 开始。

13.4 一个最小可用模板

新手别一开始写太长。AGENTS.md 的目标不是写得像公司制度，而是让 Codex 少猜。

可以先用这个模板：

# AGENTS.md

## 项目背景

这个项目是：

- 面向谁：
- 解决什么问题：
- 当前阶段：

## 目录说明

- `src/`：主要代码
- `docs/`：说明文档
- `data/`：原始数据，不要直接修改
- `output/`：生成结果，可以覆盖

## 工作规则

- 修改文件前，先简要说明准备改哪里。
- 不确定需求时，先提问，不要自行扩大范围。
- 不要删除用户已有内容，除非明确要求。
- 改完后说明改了什么、怎么验证。

## 常用命令

- 安装依赖：`npm install`
- 本地运行：`npm run dev`
- 运行测试：`npm test`

## 文风和输出偏好

- 默认使用中文。
- 面向新手解释时，少用术语。
- 输出结论先行，再补充细节。

这个模板不用一次填满。不会写的地方先删掉，比硬凑强。

最重要的是三类信息：

• 项目背景：这东西是给谁用的。
• 目录说明：哪些能改，哪些别动。
• 常用命令：改完怎么验证。

这三类写清楚，Codex 的稳定性会明显提升。

13.5 怎么让 Codex 用起来

最简单的方式：

1. 在项目根目录新建 AGENTS.md。
2. 把上面的模板复制进去，按项目情况改几句。
3. 重新打开这个项目，或者在新会话里让 Codex 先读一下。

你可以直接对 Codex 说：

请先阅读 @AGENTS.md，再帮我理解这个项目。

或者：

请根据 @AGENTS.md 的规则，帮我修改第 3 章内容。

如果你的 Codex 版本支持自动发现项目说明，它通常会在项目范围内加载这些说明；但新手不要依赖"它应该会自动读"。最稳的方式，是在关键任务开始时用 @AGENTS.md 点名引用。

记住：显式引用，永远比含糊地说"按项目规则来"更稳。

13.6 三个常见误区

误区一：把 AGENTS.md 写成超长说明书

很多人一上来写几千字，把公司介绍、产品愿景、历史决策全塞进去。这样反而会稀释重点。

新手阶段先控制在一屏到两屏内。只写会影响 Codex 行为的内容。

误区二：只写目标，不写禁区

比如只写"做一个好看的页面"，但没写"不要动数据文件""不要改登录逻辑"。真实项目里，禁区往往比目标更重要。

建议一定加一段：

## 不要做

- 不要修改生产环境配置。
- 不要删除历史数据。
- 不要引入新依赖，除非先确认。

误区三：写完就再也不更新

AGENTS.md 不是一次性文件。项目阶段变了、目录变了、测试命令变了，都应该更新。

一个好习惯是：每次项目踩坑后，问一句：

这个坑是否应该补充到 AGENTS.md，避免下次再犯？

这样你的项目说明会越来越像真正的团队经验库。

13.7 本章小结

• AGENTS.md 是给 Codex 看的项目协作说明。
• 新手先把它放在项目根目录，不要一开始搞复杂。
• 重点写项目背景、目录说明、工作规则、常用命令和禁区。
• 关键任务开始时，用 @AGENTS.md 显式引用会更稳。

下一章我们讲 PLAN.md：当任务变大以后，怎么把"帮我做一个东西"拆成一步一步能执行的路线图。

第14章 PLAN.md：把大任务拆成可执行步骤

14.0 本章你会学到什么

学完这一章，你会知道：

• 为什么大任务不能只靠一句提示词。
• PLAN.md 适合解决什么问题。
• 一个好计划应该拆到多细。
• 怎么让 Codex 按计划推进，而不是想到哪改到哪。

这一章的核心很简单：大任务先写计划，再动手。

先澄清一句：PLAN.md 不是 Codex 自动识别的官方配置文件，它只是本书采用的一种任务拆解约定。要让 Codex 真正按它工作，你必须在提示词里主动引用它，或者在 AGENTS.md 里写明“执行复杂任务前先读取并维护 PLAN.md”。

14.1 为什么需要 PLAN.md

小任务可以一句话解决：

帮我把这段文案润色得更适合小白。

但大任务不行。

比如：

帮我做一个会员管理系统。

这句话太大了。里面至少包含：

• 用户登录
• 会员列表
• 会员详情
• 充值记录
• 权限控制
• 数据存储
• 页面样式
• 测试和部署

如果你直接把这种任务丢给 Codex，它可能一边想一边做，做到后面才发现前面结构不合适。

PLAN.md 的作用，就是先把大任务拆开：

先决定怎么走，再开始跑。

它不是神奇配置文件，而是一份项目里的执行路线图。你可以让 Codex 读它、改它、按它执行，也可以自己看着它确认项目有没有跑偏。关键动作是“显式引用”：不要只假设 Codex 已经知道计划，而要在任务开始时写清楚 请先阅读 @PLAN.md。

14.2 PLAN.md 和普通待办有什么区别

普通待办经常长这样：

- 做登录
- 做页面
- 做数据
- 做测试

这太粗了。Codex 看到以后，还是要猜。

一个更好的 PLAN.md 应该写清楚：

• 每一步改哪些文件。
• 这一步完成后应该看到什么结果。
• 怎么验证这一步没有问题。
• 哪些事情暂时不做。

它更像施工清单，而不是愿望清单。

比如：

## 任务 1：整理首页结构

- 修改文件：`index.html`
- 目标：把页面拆成顶部导航、主内容、底部说明三块
- 验证：浏览器打开后，三块内容顺序正确，移动端不横向滚动
- 暂不做：不增加登录功能

这就比"做页面"清楚很多。

14.3 一个最小 PLAN.md 模板

你可以直接用下面这个模板：

# PLAN.md

## 目标

本次任务要完成：

## 范围

本次会做：

- （填写具体条目）

本次不做：

- （填写具体条目）

## 当前状态

- 已有：
- 缺少：
- 风险：

## 执行步骤

### 步骤 1：

- 修改文件：
- 要做什么：
- 验证方式：
- 完成状态：未开始

### 步骤 2：

- 修改文件：
- 要做什么：
- 验证方式：
- 完成状态：未开始

## 完成标准

- （填写具体条目）

填的时候注意一个原则：每一步最好小到 10 到 30 分钟能完成。

如果一步要做半天，那就继续拆。

14.4 怎么让 Codex 帮你写计划

你不需要自己从零写 PLAN.md。更好的方式是先让 Codex 帮你生成第一版。

可以这样说：

我要做一个小白记账网页。请先不要写代码，先帮我生成 PLAN.md。
要求：
1. 任务拆成 5 到 8 步。
2. 每一步写清楚要改哪些文件。
3. 每一步都要有验证方式。
4. 明确写出本次不做的内容。

拿到计划后，不要马上执行。先看三点：

• 有没有把任务拆得太大。
• 有没有偷偷加入你没要求的功能。
• 验证方式是不是可执行。

如果不满意，就让它改计划：

这个计划太大了。请保留目标，但把每一步拆小，并去掉登录、支付和数据库功能。

计划满意之后，再说：

请按 @PLAN.md 从步骤 1 开始执行。每完成一步，先暂停并汇报。

这句话很关键：让 Codex 一步一步走，而不是一口气改完所有东西。

14.5 执行中怎么更新计划

计划不是写完就锁死。

真实任务里经常出现三种情况：

• 做到一半发现原计划不合理。
• 某一步比预期复杂。
• 用户临时改需求。

这时候不要硬做。应该让 Codex 先更新计划：

步骤 2 遇到问题，请先更新 @PLAN.md，说明为什么要调整，再继续执行。

或者：

我决定暂时不做导出 PDF。请更新 @PLAN.md，把相关步骤移到后续规划。

一个好 PLAN.md 应该反映当前真实状态，而不是停留在最初想象。

你也可以用状态标记：

- [x] 步骤 1：整理目录结构
- [ ] 步骤 2：实现数据读取
- [ ] 步骤 3：生成图表页面

这类复选框非常适合长任务复盘。

14.6 三个常见误区

误区一：计划写得像作文

计划不是写给人感动的，是写给人和 AI 执行的。少写形容词，多写动作、文件和验证。

误区二：没有完成标准

"做完页面"不算标准。

更好的标准是：

- 本地浏览器能打开 `index.html`
- 页面在 390px 手机宽度下没有横向滚动
- 点击筛选按钮后，列表内容会更新

误区三：计划里混进太多愿望

一份计划只服务当前任务。登录、支付、后台、数据看板都想做，可以放到"后续规划"，不要塞进本次范围。

14.7 本章小结

• PLAN.md 是大任务的执行路线图，不是 Codex 自动读取的官方配置文件。
• 好计划要写清楚目标、范围、步骤、验证方式和完成标准。
• 大任务先让 Codex 写计划，用户确认后再执行。
• 执行中计划可以更新，但要说明为什么调整。

下一章我们把 AGENTS.md、PLAN.md 放进更完整的项目框架里，讲一个非常适合小白的"四文档法则"。

第15章 四文档法则构建项目框架

15.0 本章你会学到什么

学完这一章，你会知道：

• 一个项目最少需要哪几类文档。
• 为什么不是所有信息都塞进一个文件。
• README.md、PRD.md、DESIGN.md、PLAN.md 分别负责什么。
• AGENTS.md 如何配合这四份文档，让 Codex 更稳定地协作。

这一章的目标，是帮你摆脱"文件夹里一堆东西但不知道从哪看"的混乱感。

说明：四文档法则是本书作者为了降低新手协作难度总结出来的方法论，不是 Codex 官方推荐规范。它的价值在于把需求、方案、执行和说明拆开，让 Codex 更容易按边界工作。

15.1 什么是四文档法则

对小白来说，一个项目刚开始不需要复杂的企业级流程。

但至少要把四件事分开：

1. 这个项目是什么。
2. 用户到底要什么。
3. 技术上准备怎么做。
4. 接下来一步一步怎么执行。

对应到文件，就是：

这就是本书所说的四文档法则。

再加上第 13 章的 AGENTS.md，项目就有了第五个辅助文件：

注意：AGENTS.md 不是替代四文档，而是让 Codex 更好地使用四文档。

15.2 README.md：项目门牌

README.md 是项目门牌。

它不需要讲完所有细节，只要让别人 3 分钟内知道：

• 这是什么项目。
• 解决什么问题。
• 怎么运行。
• 重要文件在哪里。

一个小白友好的模板：

# 项目名称

一句话说明这个项目是做什么的。

## 使用对象

这个项目主要给谁用。

## 当前功能

- 功能 1
- 功能 2
- 功能 3

## 如何运行

npm install npm run dev

## 目录说明

- `src/`：源码
- `docs/`：文档
- `data/`：数据
- `output/`：生成结果

写 README 的关键是：别把它写成产品说明书，也别写成技术论文。

它只负责让人快速进门。

15.3 PRD.md：需求边界

PRD.md 是产品需求文档。

小白不需要写很复杂，先把这几个问题说清楚就够：

• 用户是谁。
• 用户遇到什么问题。
• 这次要解决哪些问题。
• 哪些事情本次不做。
• 判断成功的标准是什么。

模板：

# PRD.md

## 背景

为什么要做这个项目。

## 用户

主要用户是谁，他们有什么特点。

## 核心场景

用户会在什么情况下使用它。

## 功能范围

本次要做：

- （填写具体条目）

本次不做：

- （填写具体条目）

## 成功标准

- （填写具体条目）

PRD.md 最重要的不是写得漂亮，而是写清边界。

边界越清楚，Codex 越不容易自己加戏。

15.4 DESIGN.md：技术和结构说明

DESIGN.md 是设计方案。

它回答的问题不是"用户想要什么"，而是"我们准备怎么做"。

可以写：

• 页面结构。
• 数据从哪里来。
• 主要模块怎么分。
• 为什么选择这种实现方式。
• 有哪些风险。

模板：

# DESIGN.md

## 总体方案

用几句话说明实现思路。

## 页面或模块结构

- 模块 1：
- 模块 2：
- 模块 3：

## 数据流

数据从哪里来，经过哪里，最后展示到哪里。

## 关键决策

- 决策 1：
- 决策 2：

## 风险和取舍

- 风险：
- 暂不处理：

很多新手会跳过设计，直接让 Codex 写代码。小项目可以，稍微大一点就容易乱。

DESIGN.md 的价值，是让你和 Codex 在动手前先对齐路线。

15.5 PLAN.md：执行清单

PLAN.md 是四文档里最接近行动的一份。

前面三份文档分别回答：

• 项目是什么。
• 要解决什么需求。
• 准备怎么实现。

PLAN.md 回答：

今天到底先做哪一步。

它可以只服务当前阶段，不必覆盖整个项目。

比如你今天只做首页，就让 PLAN.md 聚焦首页：

# PLAN.md

## 本次目标

完成首页静态页面。

## 本次不做

- 登录
- 后台管理
- 数据库

## 步骤

- [ ] 创建页面基础结构
- [ ] 补充示例内容
- [ ] 添加基础样式
- [ ] 检查移动端显示

等首页完成，再开下一份计划做数据、交互或部署。

计划越小，越容易闭环。

15.6 AGENTS.md 怎么配合四文档

四文档是项目材料，AGENTS.md 是协作规则。

你可以在 AGENTS.md 里告诉 Codex：

## 项目文档

- 先读 `README.md` 理解项目背景。
- 涉及功能范围时，先参考 `PRD.md`。
- 涉及结构调整时，先参考 `DESIGN.md`。
- 执行具体任务时，先显式读取 `PLAN.md`，再按其中步骤推进。

这样 Codex 就更容易知道：

• 不懂项目，看 README。
• 不懂需求，看 PRD。
• 不懂结构，看 DESIGN。
• 不懂下一步，看 PLAN。

这比你每次都说"你先看一下项目文档"清楚得多。

15.7 一个最小项目目录

新项目可以这样起步：

my-project/
├── AGENTS.md
├── README.md
├── PRD.md
├── DESIGN.md
├── PLAN.md
├── src/
├── data/
└── output/

如果项目还很小，也可以先不建 src/、data/、output/，但四份文档的思路可以先有。

对小白来说，这套结构最大的好处不是"专业"，而是降低混乱：

• 想了解项目，看 README.md。
• 想确认需求，看 PRD.md。
• 想理解方案，看 DESIGN.md。
• 想知道下一步，看 PLAN.md。
• 想让 Codex 守规矩，看 AGENTS.md。

15.8 本章小结

• 四文档法则包括 README.md、PRD.md、DESIGN.md、PLAN.md。
• 四份文档分别负责总览、需求、方案和执行。
• AGENTS.md 不是四文档之一，而是 Codex 的协作规则入口。
• 文档分工清楚，项目越大越不容易乱。

下一章我们继续往前走：如果你已经有一份产品文档，应该怎么把它拆进四文档，并让 Codex 按这套框架推进。

第16章 产品文档与四文档法则的协同

16.0 本章你会学到什么

学完这一章，你会知道：

• 一份产品想法，怎么拆成四文档。
• 为什么不要把所有内容都塞进 PRD。
• 怎么让 Codex 根据产品文档生成项目框架。
• 怎么用四文档持续推进项目，而不是写完就丢。

这一章适合你在真正做项目之前反复看。很多项目失败，不是因为 Codex 不会做，而是因为一开始的材料太乱。

16.1 产品文档不是越长越好

很多人一想到产品文档，就觉得要写很多页：

• 行业背景
• 用户画像
• 竞品分析
• 功能列表
• 页面原型
• 技术方案
• 排期计划

这些当然有用，但对新手来说，很容易写着写着变成一锅粥。

真正适合和 Codex 协作的产品文档，应该先分清：

• 哪些是需求。
• 哪些是设计。
• 哪些是执行计划。
• 哪些只是背景资料。

四文档法则的价值就在这里：把一份混在一起的产品想法，拆成 Codex 更容易理解和执行的结构。

16.2 从一句产品想法开始

假设你只有一句话：

我想做一个给自由职业者用的收入支出记录工具。

不要急着让 Codex 写代码。先让它帮你拆文档：

请根据下面这个想法，帮我生成 README.md、PRD.md、DESIGN.md、PLAN.md 四份文档的初稿。

想法：我想做一个给自由职业者用的收入支出记录工具。

要求：
1. 面向零基础用户，语言简单。
2. 先做本地网页版本，不做账号登录。
3. 每份文档只写当前阶段需要的信息。
4. PLAN.md 拆成 5 到 8 个可执行步骤。

这时候 Codex 不需要马上动文件。你先看四份初稿有没有跑偏。

如果它加入了登录、云同步、支付、团队协作，而你第一阶段并不想做，就直接让它删掉：

第一阶段不要登录、云同步和多人协作。请更新 PRD.md 和 PLAN.md，把这些内容放到后续规划。

16.3 四文档之间怎么流动

四文档不是孤立的。

它们之间有一个很自然的顺序：

产品想法 → PRD.md → DESIGN.md → PLAN.md → 实现结果 → README.md 更新

更具体一点：

• PRD.md 先定义用户、场景、范围。
• DESIGN.md 根据需求决定结构和方案。
• PLAN.md 根据方案拆执行步骤。
• 实现完成后，README.md 更新成真实使用说明。
• AGENTS.md 记录长期协作规则和项目禁区。

不要反过来。

如果需求没定，设计就容易飘。

如果设计没定，计划就容易乱。

如果计划没定，Codex 就容易边做边猜。

16.4 让 Codex 做文档拆分的提示词

你可以把下面这段当成通用模板：

我会给你一段产品想法。请先不要写代码。

请你做四件事：
1. 把它整理成 PRD.md，明确用户、场景、功能范围和不做什么。
2. 根据 PRD.md 生成 DESIGN.md，说明页面结构、数据流和技术取舍。
3. 根据 DESIGN.md 生成 PLAN.md，把任务拆成可执行步骤，每步都要有验证方式。
4. 生成 README.md 的初稿，让新加入的人能快速理解项目。

要求：
- 面向新手，语言直接。
- 不要自行增加超出当前阶段的功能。
- 不确定的地方列为“待确认”，不要假设。
- 每份文档都保持精简。

产品想法如下：
……

这段提示词的关键不是"生成四份文档"，而是第一句：

请先不要写代码。

很多项目一开始最需要的不是代码，而是把问题说清楚。

16.5 用四文档推进一次真实任务

假设四份文档已经有了，你要让 Codex 开始执行，可以这样说：

请先阅读 @AGENTS.md、@PRD.md、@DESIGN.md 和 @PLAN.md。

本次只执行 PLAN.md 的步骤 1。
要求：
1. 修改前先说明准备改哪些文件。
2. 只做步骤 1，不提前做后续步骤。
3. 完成后说明怎么验证。

如果步骤 1 做完没问题，再继续：

步骤 1 已确认。请更新 @PLAN.md 的完成状态，然后继续步骤 2。

这个节奏会慢一点，但稳定很多。

你是在训练 Codex 按项目方法工作，而不是靠一次提示词赌运气。

16.6 文档更新的时机

四文档不是写完就结束。建议在这些时刻更新：

• 需求变了：更新 PRD.md。
• 实现方案变了：更新 DESIGN.md。
• 任务顺序变了：更新 PLAN.md。
• 功能真的做完了：更新 README.md。
• 协作规则踩坑了：更新 AGENTS.md。

你可以让 Codex 帮你判断：

根据刚才的修改，请判断 README.md、PRD.md、DESIGN.md、PLAN.md、AGENTS.md 中哪些需要同步更新。先列清单，不要直接改。

这句话很实用。它能避免代码改了，文档还停留在旧版本。

16.7 一个简单案例：教程项目

就拿这篇 Codex 教程来说，也可以套四文档：

• README.md：说明这是一本面向小白的 Codex 入门教程。
• PRD.md：定义读者是谁、学完能做什么、哪些高级内容后面再讲。
• DESIGN.md：设计章节结构、每章固定格式、配图规则和更新节奏。
• PLAN.md：列出下一次更新要补哪几章、先修哪些格式问题。
• AGENTS.md：告诉 Codex 文风要口语化、解释要照顾新手、不要随便删原文。

这样一来，后续继续写第 17 章、第 18 章时，就不需要每次重新解释这本教程的风格。

项目越长，文档越能省力。

16.8 本章小结

• 产品文档不要一锅端，先拆成需求、设计、计划和说明。
• 四文档的顺序是：PRD.md 定范围，DESIGN.md 定方案，PLAN.md 定步骤，README.md 定对外说明。
• AGENTS.md 负责让 Codex 按项目规则协作。
• 真正稳定的 AI 协作，不是一次提示词写得多神，而是项目材料清楚、执行边界清楚、每一步都能验证。

到这里，第三部分就完整了。你已经学会了快捷指令、项目说明、执行计划和基础项目文档框架。

进阶能力放在《Codex 入门与实战指南：进阶能力手册》中继续讲。零基础主线到这里收束，避免新手在第一本里被 MCP、Skill、浏览器控制、办公自动化、多模态内容生产同时淹没。

附录A 常用命令速查

这一附录不是完整命令手册，只收录新手最常用、最容易忘的命令和提示方式。

具体命令会随 Codex 版本变化，遇到不一致时，以当前客户端的 /help 和官方文档为准。

A.1 Codex 常用输入框命令

不同版本命令名称可能略有差异。

最稳的习惯是：不确定就输入 /help。

A.2 文件引用

引用单个文件：

请阅读 @README.md，告诉我这个项目怎么运行。

引用多个文件：

请对比 @PRD.md、@DESIGN.md 和 @PLAN.md，检查它们是否一致。

引用具体任务：

请根据 @PLAN.md，只执行步骤 1。完成后先停下来汇报。

文件引用是防止 Codex 乱猜的核心动作。

A.3 项目启动常用命令

Node.js 项目常见：

npm install
npm run dev
npm test
npm run build

Python 项目常见：

python --version
pip install -r requirements.txt
python main.py
pytest

Git 常见：

git status
git diff
git add .
git commit -m "说明这次改动"
git log --oneline -5

不要死记所有命令。

更好的方式是让 Codex 读项目文件后告诉你：

请阅读这个项目，告诉我安装、启动、测试、构建分别应该运行什么命令。

A.4 常用提示词句式

先看再动

请先阅读相关文件，告诉我你的理解和修改计划。先不要改文件。

限制范围

本次只修改文案，不调整结构和样式。

分步执行

请按步骤执行，每完成一步先汇报，再继续下一步。

先写计划

这是一个大任务。请先生成 PLAN.md，把任务拆成可执行步骤，不要直接实现。

遇到报错

请先阅读完整报错并定位根因，不要直接猜测修改。

完成前验证

请说明你如何验证这次修改已经完成，并给出验证结果。

A.5 常用文档文件

新项目如果不知道从哪里开始，就先让 Codex 帮你生成这几份文档的初稿。

附录B 常见术语解释

这一附录用尽量口语化的方式解释教程中出现的常见术语。

B.1 Codex

OpenAI 的编程与任务协作工具。

它不只是聊天，也可以读写文件、运行命令、理解项目、帮你推进任务。

B.2 CLI

Command Line Interface，命令行界面。

你在终端、PowerShell、命令提示符里输入命令来操作工具。

B.3 IDE

Integrated Development Environment，集成开发环境。

简单说就是写代码的软件，比如 VS Code、JetBrains 系列工具、Xcode。

B.4 API

Application Programming Interface，应用程序接口。

可以理解成一个系统对外提供的"功能入口"，程序可以通过它调用某个服务。

B.5 API Key

调用 API 时使用的密钥。

它像账号密码一样敏感，不能发到公开聊天、截图、仓库或文档里。

B.6 MCP

Model Context Protocol。

一套让 AI 连接外部工具、资料和上下文的通用协议。

你可以把它理解成给 Codex 接工具的标准插座。

B.7 Skill

可复用的 AI 工作流程说明。

它告诉 Codex：遇到某类任务时，应该按什么步骤做、输出什么格式、注意哪些边界。

B.8 Agent

智能体。

比普通问答更进一步，Agent 通常会围绕一个目标进行多步推理、调用工具、执行任务。

B.9 Worktree

Git 的多工作区能力。

它允许同一个仓库在多个目录里同时打开不同分支，适合并行开发。

B.10 TTS

Text To Speech，文本转语音。

把文字稿转换成音频，常用于课程配音、短视频口播、语音播报。

B.11 Prompt

提示词。

你给 AI 的任务说明。好的提示词应该包含目标、背景、范围、格式和限制。

B.12 PRD

Product Requirements Document，产品需求文档。

用来说明用户是谁、要解决什么问题、本次做什么、不做什么。

B.13 DESIGN

设计文档。

在项目里通常指技术方案或结构设计，说明准备怎么实现。

B.14 PLAN

计划文档。

把任务拆成具体步骤，每一步最好有修改范围和验证方式。

B.15 README

项目说明文件。

通常放在项目根目录，用来说明项目是什么、怎么安装、怎么运行。

附录C 推荐学习路径与练习建议

这一附录给你一条更实际的学习路线。

不用按 47 章从头背到尾。你可以按自己的目标选路线。

C.1 完全零基础路线

适合：刚接触 Codex，不会编程，想先做出东西。

建议顺序：

1. 第 1-6 章：认识 Codex、安装、界面、目录。
2. 第 7 章：从一句话做页面。
3. 第 9 章：怎么说清楚需求。
4. 第 10 章：让 Codex 修改和补充内容。
5. 第 11 章：报错怎么处理。
6. 第 12-16 章：学会项目文档。

练习：

• 建一个空文件夹。
• 让 Codex 生成一个个人介绍网页。
• 让它改三轮。
• 让它写 README。
• 最后让它检查页面问题。

目标：能完成一个本地小页面。

C.2 内容创作者路线

适合：写教程、做自媒体、做课程、整理知识库。

建议顺序：

1. 第 9-10 章：需求表达和内容修改。
2. 第 18-20 章：Skill 和元能力。
3. 第 23-24 章：视觉素材和 TTS。
4. 第 26 章：文本处理。
5. 第 30 章：教程改写与知识库。
6. 第 32 章：自媒体运营。
7. 第 43 章：多 Agent 写作。

练习：

• 找一段自己的长文。
• 让 Codex 改成教程章节。
• 再拆成 5 个小红书选题。
• 再生成一版 60 秒口播稿。

目标：把一份内容变成多种交付形态。

C.3 数据分析路线

适合：运营、销售、财务、研究、数据工作者。

建议顺序：

1. 第 8 章：CSV 数据分析。
2. 第 9 章：提具体业务问题。
3. 第 25 章：Office 自动化。
4. 第 26 章：文本和结构化。
5. 第 31 章：数据分析与图表报告。
6. 第 35 章：行业研究报告。

练习：

• 准备一份 CSV。
• 先让 Codex 解释字段和数据质量。
• 再提出 5 个业务问题。
• 选 3 个问题做图表报告。
• 最后让它检查结论是否有数据支持。

目标：从文件得到可信分析结论。

C.4 小白开发者路线

适合：想做网页、小工具、APP、小程序的人。

建议顺序：

1. 第 7 章：做第一个页面。
2. 第 13-16 章：项目文档。
3. 第 20-21 章：元能力和浏览器验证。
4. 第 36 章：从零搭建项目。
5. 第 37 章：文件数据清洗工具。
6. 第 38 章：智能体对话平台。
7. 第 40-41 章：小程序和 iOS APP。

练习：

• 做一个本地记账网页。
• 写 PRD、DESIGN、PLAN、AGENTS.md。
• 先跑通一条核心流程。
• 用浏览器检查页面。
• 让 Codex 写 README 和使用说明。

目标：从想法推进到能运行的小项目。

C.5 办公自动化路线

适合：经常处理会议、文档、表格、飞书、任务的人。

建议顺序：

1. 第 22 章：飞书 CLI。
2. 第 25 章：Office 自动化。
3. 第 26 章：文本处理。
4. 第 29 章：会议纪要。
5. 第 33 章：客户跟进。
6. 第 34 章：飞书办公协同。

练习：

• 找一份会议记录。
• 整理成会议纪要。
• 提取待办事项。
• 生成周报草稿。
• 起草群消息，但不直接发送。

目标：把重复办公流程变成可复用 Skill。

C.6 一个月练习计划

第 1 周：基础使用

• 安装 Codex。
• 跑第一句话。
• 生成一个 HTML 页面。
• 学会 @文件名。
• 学会让 Codex 修改文件。

第 2 周：项目文档

• 学会 README、PRD、DESIGN、PLAN、AGENTS.md。
• 给一个小项目补齐四文档。
• 让 Codex 按 PLAN 执行一个小任务。

第 3 周：Skill 和业务场景

• 了解 MCP 和 Skill。
• 练习会议纪要、文本处理、数据分析。
• 试着把一个重复任务写成 Skill 草稿。

第 4 周：小项目实战

• 做一个文件清洗工具或本地网页工具。
• 跑测试。
• 写 README。
• 完成前做验证。
• 总结踩坑并更新 AGENTS.md。

一个月后，你不一定精通 Codex。

但你会拥有一种更重要的能力：知道如何把一个真实任务拆给 AI 做，并把结果检查到能用。

C.7 最后一个练习

请打开 Codex，新建一个空文件夹，然后输入：

我想做一个 1 小时内能完成的小项目。
请先问我 3 个问题，帮我把目标缩小到最小可用版本。
然后生成 README.md、PRD.md、DESIGN.md、PLAN.md 和 AGENTS.md。
先不要写代码。

这就是你真正开始的地方。

入门版收尾建议

读完这一版后，不建议马上去啃 MCP、Skill 和多 Agent。更好的下一步是做一个 1 小时内能完成的小项目。

推荐顺序：

1. 用第 7 章做一个个人介绍页。
2. 用第 8 章分析一份 CSV。
3. 用第 13-16 章给一个小项目补齐 README、PRD、DESIGN、PLAN 和 AGENTS.md。
4. 遇到卡点时，再去阅读进阶能力手册。

配套练习文件可以在 ../codex-tutorial-kit/ 中找到。