bozhouDev/codex-orange-book

0. 使用说明

0.1 重要声明

• 本资料为非官方指南，不代表 OpenAI 官方文档。
• 所有功能以 OpenAI 官方文档和 Codex 实际版本为准。
• 本 PDF 会随着 Codex 更新持续维护。
• 建议读者优先查看 GitHub 仓库中的最新版 Markdown 原稿。

0.2 这份 PDF 适合谁

• 完全没用过 Codex，但想系统上手的人。
• 会写代码，但不知道怎么把 Codex 接入真实项目的人。
• 已经用过 Cursor、Claude Code、ChatGPT，想比较 Codex 工作流的人。
• 独立开发者、AI 工具博主、技术团队负责人。
• 想搭建 AI 编程工作流、知识库和自动化流程的人。

0.3 阅读路线

• 快速上手路线：0. 使用说明 → 第一篇：先搞懂 Codex 是什么 → 第二篇：安装、配置与环境准备 → 第四篇：标准工作流 → 第五篇：实战案例库
• 开发者核心路线：第一篇：先搞懂 Codex 是什么 → 第二篇：安装、配置与环境准备 → 第三篇：核心功能详解 → 第四篇：标准工作流
• 进阶扩展路线：第三篇：核心功能详解 → 第四篇：标准工作流 → 附录：第三方模型接入

第一篇：先搞懂 Codex 是什么

Codex 基础认知

Codex 到底是什么

很多人第一次听到 Codex，会下意识把它理解成'又一个 AI 写代码工具'。

但如果只把 Codex 当成'帮我写代码的 ChatGPT'，你很容易低估它。

Codex 真正重要的地方，不是它能不能写一个函数、补一段代码、解释一个报错，而是它代表了 AI 编程工具的一次角色变化：

以前，AI 是坐在你旁边帮你补代码的人。

后来，AI 是在编辑器里和你一起改代码的人。

现在，Codex 更像是一个可以被交代任务的工程执行者。

它不只是回答你'这段代码怎么写'，而是可以进入一个项目，读取文件，理解上下文，制定计划，修改代码，运行命令，检查结果，最后把改动整理成可以 review 的结果。

这就是 Codex 和普通 AI 聊天工具最大的区别。

五年变了四次

AI 编程工具的四次进化

过去几年，AI 编程工具大致经历了四个阶段。

2021 年：Copilot 补全时代。 Codex 这个名字第一次被大量开发者听到，是因为 GitHub Copilot。那时 AI 主要负责代码补全：你写开头，它补后面；你写函数名，它补函数体。它像一个更聪明的输入法，能让你写得更快，但项目怎么拆、文件怎么找、测试怎么跑，仍然主要靠人完成。

2022 年：ChatGPT 对话时代。 ChatGPT 出现后，AI 编程从'补全'进入'对话'。你可以直接问它报错原因、代码优化、接口写法、项目结构解释。AI 从输入法变成了问答伙伴。但它通常不在真实项目里，你需要复制代码、粘贴报错、手动补上下文，再把答案搬回项目。

2023—2024 年：Cursor 项目协作时代。 Cursor 这类 AI 编辑器让 AI 真正进入编辑器，能看到文件、修改函数、跨文件重构、根据项目上下文完成一部分开发任务。AI 开始从'回答问题'变成'协助修改项目'。但它大多数时候仍依附在 IDE 里，你还需要盯着它改、判断下一步、跑测试、整理提交。

2025 年：Codex 工程 Agent 时代。 Codex 重新出现后，已经不只是当年负责代码补全的模型，而是面向真实软件工程任务的 coding agent。它能读项目、解释代码、修 bug、加功能、补测试、重构模块、运行命令、检查 diff、整理 PR 说明，甚至并行处理多个工程任务。

这意味着，AI 编程工具的重点正在从'帮你写代码'转向'帮你交付任务'。

一句话总结：

Copilot 帮你补代码，ChatGPT 帮你想代码，Cursor 陪你改项目，而 Codex 开始帮你执行工程任务。

Codex 能做什么

What Codex Can Do

很多人第一次用 Codex，会直接问：

• '帮我写一个登录页面。'
• '帮我修一下这个 bug。'
• '帮我做一个项目。'

这些当然可以，但还不够准确。

Codex 真正擅长的，不是凭空生成一段代码，而是在真实项目里完成一组工程任务。

它可以读项目、找文件、理解上下文、制定计划、修改代码、运行命令、检查结果、整理 diff，最后把任务推进到可以 review 的状态。

所以，不要把 Codex 当成一个'代码生成按钮'。

更准确地说：

Codex 是一个可以进入项目现场的 AI 工程助手。

它能做的事，大致可以分成以下几类。

读懂一个陌生项目

使用 Codex 的第一步，不应该是让它直接写代码，而是让它先读项目。

它可以帮你快速搞清楚：

• 项目用什么技术栈。
• 入口文件在哪里。
• 核心模块在哪里。
• 测试和构建命令是什么。
• 哪些文件不能随便动。

很多 Codex 任务失败，不是因为它不会写代码，而是因为它还没理解项目，就被要求直接动手。

解释代码和梳理逻辑

Codex 可以帮你解释看不懂的代码。

比如：

• 这个函数是做什么的。
• 这个组件为什么这样写。
• 接口调用链路是什么。
• 状态从哪里来。
• 这个 bug 可能和哪些文件有关。

它不只是解释单个函数，还可以结合上下文，梳理模块关系、数据流和潜在风险。

这对接手旧项目尤其有用。

修 bug 和加功能

Codex 很适合处理边界清楚的开发任务。

比如：

• 修复一个可复现 bug。
• 新增一个设置页。
• 新增一个表单校验。
• 新增一个接口。
• 新增一个导出按钮。
• 优化一个前端页面。

但不要直接把一个大项目丢给它。

更好的方式是把任务拆小：

1. 先读项目。
2. 再出方案。
3. 只改一个模块。
4. 跑测试。
5. 看 diff。
6. 确认没问题后再继续。

Codex 更适合连续完成小任务，而不是一次吞下大项目。

写测试、做重构

Codex 可以帮你补测试，也可以帮你重构代码。

它可以做：

• 补单元测试。
• 补边界条件。
• 补异常场景。
• 提取重复逻辑。
• 拆分过长函数。
• 整理组件结构。
• 封装 API 请求。

但这类任务必须加边界：

• 不改业务逻辑。
• 不改公共 API。
• 不引入无关依赖。
• 不大范围重构。
• 修改后必须跑测试。

Codex 能重构，但你必须控制范围。

写文档和整理 PR

Codex 很适合写工程文档。

比如：

• README。
• 安装说明。
• 启动说明。
• 接口文档。
• 环境变量说明。
• 项目结构说明。
• PR 描述。
• commit message。
• 更新日志。

文档不是附属品。

在 Codex 工作流里，文档本身就是上下文基础设施。

文档越清楚，后续人和 AI 接手项目都会更轻松。

但要提醒 Codex：

不要编造不存在的命令，不确定的信息要明确标注。

跑命令、看 diff、做 review

Codex 和普通聊天工具最大的区别之一，是它可以在项目环境里运行命令。

它可以：

• 运行测试。
• 运行 lint。
• 运行 typecheck。
• 运行 build。
• 查看 git status。
• 查看 git diff。
• 搜索代码。
• 检查修改结果。

这让 Codex 不只是'猜答案'，而是可以验证结果。

但命令执行也有风险。

能验证的，可以让它验证。

有风险的，必须由你批准。

涉及生产环境、数据库、真实用户数据的操作，不要交给它自动执行。

什么时候适合用 Codex

适合 Codex 的任务，一般有几个特点：

• 目标明确。
• 范围可控。
• 上下文清楚。
• 结果能验证。
• 失败能回滚。
• 风险可接受。

比如：

• 读项目。
• 修 bug。
• 加小功能。
• 补测试。
• 写文档。
• 优化前端页面。
• 整理 PR。
• 审查 diff。
• 处理重复任务。

什么时候不适合直接用 Codex

不建议直接让 Codex 处理：

• 生产数据库。
• 真实用户数据。
• 支付核心逻辑。
• 权限和安全核心模块。
• 大规模架构迁移。
• 没有备份的重要项目。
• 没有测试的核心业务。
• 你自己也无法验收的任务。

如果你判断不了结果对不对，就不要让 Codex 独立完成。

Codex 可以提高效率，但不能替你做判断。

一句话总结

Codex 能做的事情，不只是写代码。

它真正重要的能力是：

把一个明确的软件工程任务，从需求推进到可 review 的结果。

你不是让它随便写点代码。

你是在让它按照你的项目规则、上下文和验收标准，完成一项可控的工程任务。

Codex 与 ChatGPT 的区别

很多人会问：

既然 ChatGPT 也能写代码，为什么还要用 Codex？

核心区别在于：

ChatGPT 更像一个顾问，有问题问GPT，从它那里得到答案，然后自己去执行。那么现在Codex更像是一个实习生，我们能够真正的让它帮我们干活，交代任务能够完成这种。

ChatGPT 适合帮你想问题。

Codex 适合帮你推进任务。

更合理的用法是：

先用 ChatGPT 想清楚，再用 Codex 进项目执行。

Codex 与 Cursor 的区别

很多人会把 Codex 和 Cursor 放在一起比较，因为它们都能帮你写代码、改代码、理解项目。

但它们的定位并不一样。

Cursor 更像一个 AI 编辑器，Codex 更像一个工程 Agent。

合理的用法是组合使用：

用 Cursor 做日常编码和局部修改，用 Codex 做任务推进和工程交付。

Cursor 负责陪你写。

Codex 负责帮你跑完整任务。

一个偏 IDE 协作，一个偏 Agent 执行。

这就是它们最大的区别。

Codex 与 Claude Code 的区别

Codex 和 Claude Code 很像。

都是 **agentic coding 工具，**但两者的侧重点不一样。

Claude Code 更偏终端里的长期协作

Claude Code 的体验更像是：

你打开终端，把它放进项目里，然后和它围绕一个开发任务持续协作。

它适合：

• 长时间读项目。
• 持续追踪一个复杂任务。
• 在终端里边讨论边修改。
• 处理多步骤工程问题。
• 通过 hooks、subagents、MCP 等机制扩展工作流。

所以，Claude Code 更像一个长期待在你终端里的 AI 工程搭档。

它的优势在于命令行工作流、深度上下文协作和工程任务连续推进。

Codex 更偏 OpenAI 生态里的多端任务执行

Codex 的优势，不只在 CLI，而在 OpenAI 生态里的多端联动。

它可以通过不同入口使用：

Codex CLI。

Codex App。

Codex IDE Extension。

Codex Web。

ChatGPT 账号体系。

GitHub / PR 工作流。

Skills 和项目规则。

OpenAI 官方文档中，Codex CLI 是本地终端里的 coding agent；Codex App 则提供桌面端多线程、worktree、自动化和 Git 功能；Codex Skills 也可以在 CLI、IDE extension 和 Codex app 中复用。

所以，Codex 更像一个接入 OpenAI 生态的工程任务平台。

它不只是'在终端里写代码'，而是可以在 App、CLI、IDE、Web 等多个入口之间流转，让你用不同方式管理、执行和审查工程任务。

怎么选

如果你更喜欢终端工作流，希望 AI 长时间待在项目里，和你围绕复杂任务持续协作，Claude Code 很适合。

如果你已经在使用 ChatGPT 和 OpenAI 生态，希望在 CLI、桌面 App、IDE、Web 之间切换，并把任务、diff、PR、Skills、GitHub 工作流串起来，Codex 会更顺手。

但两者没有绝对谁替代谁。

最终选择要看：

• 模型能力。
• 上下文处理。
• 工具链。
• 价格。
• 团队习惯。
• 你自己的开发流程。

一句话总结：

Claude Code 更像终端里的长期工程搭档，Codex 更像 OpenAI 生态里的多端工程 Agent。

一句话总结 Codex

• 初级用法：让它帮你写代码。
• 中级用法：让它帮你读项目、改功能、跑测试。
• 高级用法：让它成为你的项目执行代理，配合规则、上下文、自动化和团队流程工作。

Codex 的使用入口

如果你主要做本地项目、网页练习和日常开发，优先从 Codex App 开始通常就够用；等你熟悉 Git、终端和团队协作后，再逐步补 CLI、IDE Extension 和 Web / Cloud。

第二篇：安装、配置与环境准备

安装前准备

账号准备

如果你是普通个人用户，建议准备：

• ChatGPT 账号
• 能正常访问 ChatGPT / OpenAI 服务的网络
• 选择当前包含 Codex 的 ChatGPT 套餐；套餐名称、额度和功能范围会变化，请以官方页面和你账号实际显示为准。

系统准备

Codex 四大形态：

Codex App 支持 macOS 和 Windows；Codex CLI 支持 macOS、Windows 和 Linux。

软件工具准备

安装 Codex 之前，建议先准备这些基础工具：

项目目录准备

Codex 不是单纯聊天工具，它需要进入一个具体项目目录工作。官方入门流程也是：登录 Codex 后，选择电脑上的文件夹或 Git 仓库，再开始第一个任务。

建议你提前建一个专门练习目录，比如：

D:\AI-Codex-Projects

里面可以放：

hello-web
ai-tools-page
xiaohongshu-cover-tool
landing-page-demo

不要一开始就让 Codex 操作你最重要的真实项目。先用练习项目熟悉它怎么改文件、跑命令、生成结果。

权限与安全准备

Codex 可以读取、修改文件，还能在你的项目目录里运行命令。官方对 CLI 的描述就是：它可以在你选择的目录中读取、修改代码，并运行命令。

所以安装前要注意：

推荐每个项目先初始化 Git：

git init
git add .
git commit -m "initial commit"

这样 Codex 改坏了也可以回退。

Codex App 安装与上手 （新手最为推荐，也是功能最强的）

下载与安装

macOS 安装

如果你使用的是 Mac，先确认自己的芯片类型。

点击电脑左上角的 Apple 图标，选择「关于本机」。

如果显示的是：

• Apple M1 / M2 / M3 / M4：选择 Apple Silicon 版本
• Intel：选择 Intel 版本

进入 Codex App 官方页面后，根据自己的芯片下载对应版本。下载完成后，打开安装包，把 Codex 拖进「应用程序」文件夹。

安装完成后，在「应用程序」里打开 Codex。

第一次打开时，系统可能会提示：

「这是从互联网下载的应用，是否确认打开？」

选择「打开」即可。

Intel Mac 与 Apple Silicon 的区别

Mac 主要分两种芯片：

最简单的判断方法：

打开「关于本机」，看芯片信息。

如果写的是 Apple M 系列，就是 Apple Silicon。

如果写的是 Intel Core i5、Intel Core i7、Intel Core i9，就是 Intel Mac。

这个地方不要选错。选错版本可能会导致无法安装、打不开，或者运行不稳定。

Windows 安装

如果你使用的是 Windows，进入 Codex App 官方页面，选择 Windows 版本。

Windows 版一般会跳转到 Microsoft Store 安装。

安装步骤：

1. 打开 Codex App 官方页面
2. 点击 Windows 下载入口

3. 跳转到 Microsoft Store

4. 点击「获取」或「安装」（这里我已经安装过了所以显示的是打开）
5. 打开 Codex App
6. 到这里Codex App已经安装完成

第一次打开 Codex App

选择项目目录

第一次打开 Codex App 后，登录完成，系统会让你选择一个项目目录。

这里的「项目目录」，可以理解成：

Codex 要进入哪个文件夹工作。

比如你想让 Codex 帮你做一个网页，就可以提前新建一个文件夹：

hello-codex

然后在 Codex App 里选择这个文件夹。

新手建议第一次选择一个干净的练习目录，不要直接 C 盘，也不要一上来就选择重要工作项目。

推荐目录结构：

AI-Codex-Projects
└── hello-codex
    └── index.html

选择项目目录后，Codex 才知道自己应该读哪些文件、改哪些文件、在哪个地方运行命令。

理解项目列表

进入 Codex App 后，左侧通常会看到项目列表。

你可以把项目列表理解成：

你交给 Codex 的不同代码文件夹。

比如：

hello-codex
ai-first-page

每一个项目，都对应你电脑上的一个本地文件夹，或者一个 Git 仓库。

如果你之前在 Codex App、Codex CLI、Codex IDE Extension 里打开过项目，这些项目也可能会出现在列表里。

小白要记住一点：

项目列表不是聊天记录列表，而是「代码项目列表」。

你点进不同项目，Codex 看到的文件范围也不一样。

理解 thread（对话）

Thread 可以理解成：

同一个项目里的一个任务对话。

比如你在 hello-Codex 这个项目里，可以开多个 thread：

Thread 1：做一个首页
Thread 2：修复按钮点击无反应的问题
Thread 3：优化移动端样式
Thread 4：帮我写 README

每个 thread 都有自己的上下文。

也就是说，你在 Thread 1 里让 Codex 做首页，它会围绕这个任务持续理解和修改。

你在 Thread 2 里让它修 bug，它就围绕另一个任务工作。

小白可以简单理解：

• 项目 = 一个公司
• thread = 公司里面的员工

不要把所有事情都塞进同一个 thread。

更好的做法是：

一个清楚的任务，开一个 thread。

比如：

请帮我做一个个人主页

这是一个 thread。

请检查为什么移动端布局错位

这是另一个 thread。

这样项目不会乱，Codex 也更容易理解任务边界。

理解任务窗口

任务窗口就是你和 Codex 对话、安排工作的地方。

你可以在这里输入任务，比如：

请帮我做一个简单网页，黑色背景，中间显示 Hello, Codex。

也可以继续追问：

请把这个页面改得更像科技产品首页。

任务窗口里通常会出现这些内容：

第一次使用时，不要写太复杂的任务。

不推荐：

帮我做一个完整的 AI 工具平台，要有登录、支付、数据库、后台管理。

推荐：

请帮我做一个简单的产品介绍页，只用 HTML 和 CSS。

任务越清楚，Codex 越容易做好。

理解 review pane

Review pane 可以理解成：

检查 Codex 改了什么的地方。

Codex 改完文件后，你不要只看它的文字总结，而是要打开 review pane 看实际改动。

它会告诉你：

• 哪些文件被修改了
• 哪些地方新增了代码
• 哪些地方删除了代码
• 哪些改动可以接受
• 哪些改动可以退回

小白可以把 review pane 理解成：

Codex 的「作业检查区」。

你不是让 Codex 写完就直接相信，而是要在这里检查它到底交了什么作业。

如果你看到某一行代码不满意，可以在对应位置留下评论，让 Codex 按照你的评论继续修改。

比如你可以评论：

这里的按钮颜色太亮了，改成更克制的深蓝色。

或者：

这段代码太复杂，请改成新手更容易理解的写法。

理解 diff

Diff 是代码改动对比。

小白可以这样理解：

绿色 = 新增内容
红色 = 删除内容

比如 Codex 原来没有写标题，后来加了一行：

<h1>Hello, Codex</h1>

这行就会显示为新增。

如果 Codex 删除了一段旧代码，那段就会显示为删除。

Diff 的作用是让你看清楚：

Codex 到底改了什么。

不要只看最终页面，也不要只看 Codex 的总结。

真正重要的是看 diff。

因为 Codex 有时候可能会：

• 顺手改了你没要求改的地方
• 删除了某些你还需要的代码
• 把简单代码改复杂
• 修改了多个文件但没有说清楚

所以第一次上手就要养成习惯：

每次 Codex 完成任务后，先看 diff，再决定要不要接受。

第一次打开后的推荐操作流程

第一次打开 Codex App，可以按这个顺序操作：

1. 登录 ChatGPT
2. 选择一个练习项目目录
3. 新建或选择一个 thread
4. 在任务窗口输入一个简单任务
5. 等 Codex 修改文件
6. 打开 review pane
7. 查看 diff
8. 确认没有问题后再继续修改

推荐第一个任务：

请帮我做一个简单网页，要求：
1. 黑色背景
2. 页面中间显示大字 Hello, Codex
3. 字体白色
4. 页面整体水平和垂直居中
5. 只使用 HTML 和 CSS

这个任务足够简单，适合用来熟悉 Codex App 的基本流程。

小白需要记住的几个概念

Codex App 的基础使用

基础布局

可以看到 Codex App 是经典的三栏布局

左侧是任务列表

中间是对话窗口

右侧是多功能区域

新对话

使用项目

我们可以开启一个新对话来执行一个新的任务

开启新对话后需要选择新对话属于哪个项目

当然我们也可以直接在项目右侧的小按钮那里点击，直接开启对应项目的一个新对话。

不使用项目

点击不使用项目，对应的会话会显示在对话里面，可以作为想问和项目无关的问题

搜索

后期任务对话太多了，但是只记得一些关键次找不到对应的任务对话了，可以直接在搜索这里，搜关键词，就会查找到对应的任务对话了

插件

功能较多，后续再讲

自动化

功能较多，后续再讲

项目

创建项目

可以在Codex中直接创建一个新项目，也可以使用现有的项目

创建或选择好的项目会出现在项目栏里面，方便后续的管理

thread

thread 是一个项目里的「单独任务对话」

比如你有一个项目叫：

hello-codex

你可以在这个项目里开多个 thread：

你可以这样理解：

Project 项目 = 一个代码文件夹
Thread = 这个项目里的一个具体任务

比如：

项目：小红书封面生成器
Thread 1：做首页
Thread 2：修复上传图片失败
Thread 3：优化手机端布局
Thread 4：写项目说明文档

为什么要有 thread？

因为不同任务最好分开做。

如果你把'做首页、修 bug、改样式、写文档'全塞进一个对话里，Codex 容易上下文混乱，你也不好检查它到底改了什么。

更好的用法是：

一个明确任务 = 一个 thread

比如你要做页面：

请帮我做一个 AI 工具介绍页。

这是一个 thread。

后面你发现按钮有问题，再新开一个 thread：

请检查为什么首页按钮点击后没有反应。

一句话总结：

Thread 就是 Codex App 里的任务对话，一个 thread 专门处理一个具体任务。

等待批准

在我们 Codex 执行任务的时候，很多时候都会需要用户进行权限的批准

并且会在对应的对话处提示等待批准的标签

点击对应的对话后，再点击允许，Codex 就会继续进行接下来的工作了

归档

归档 Archive，可以理解成把一个已经完成、暂时不用继续处理的 thread 收起来。

它的作用不是删除代码，也不是合并代码，而是让你的任务列表更干净。

比如你做完了这些任务：

Thread 1：优化移动端样式
Thread 2：做一个首页
Thread 3：做一个首页

其中 Thread 2、Thread 3 已经完成了，Thread 1 你也不打算用了，就可以把它们归档。

归档后，它们不会继续占据当前任务列表的位置，你的项目界面会更清爽。

取消归档，当然你也可以在设置里面找到已归档对话，将其还原回来

设置

剩余额度

在这里可以看到当前账号的额度、速率限制或使用情况。

不同套餐、工作区、模型和版本显示的限制可能不一样；具体能用多久、什么时候恢复、是否能购买额外额度，都以 Codex 当前界面和官方说明为准。

对话窗口

权限控制

沙盒（Sandbox）

要知道权限控制必须先知道一个沙盒（Sandbox）的概念

你可以把它理解成：

Codex 可以在围栏里面干活，但不能随便跑到围栏外面乱动你的电脑。

因为 Codex App 不是普通聊天工具，它可以读文件、改文件、运行命令，所以必须有一个'围栏'限制它能碰哪里、能不能联网、能不能改项目外的文件。官方文档里，Codex 的 sandbox 模式包括 read-only、workspace-write、danger-full-access 这几类，用来控制文件系统和网络访问边界。

简单来说

假设你的项目文件夹是：

D:\AI-Codex-Projects\hello-codex

如果开启沙盒，Codex 正常只能在这个项目文件夹范围内工作，比如：

可以看 index.html
可以改 style.css
可以运行 npm run dev

但如果它想做这些事，就可能需要你批准：

访问桌面文件
读取下载文件夹
修改项目外的文件
联网下载东西
运行高风险命令

所以：

Sandbox = 给 Codex 设置工作边界

三大权限

请求批准
替我审批
完全访问权限

可以这样对应理解：

新手建议开启：

请求批准或自动审批类选项。如果你是新手，优先选择不会放开项目边界的模式：让 Codex 可以在当前项目内工作，但遇到越界、联网或高风险命令时仍然停下来让你确认。不同版本里权限选项名称可能不同，核心原则是：不要一开始就开完全访问权限。

一句话总结

Sandbox 沙盒就是 Codex 的安全围栏。

它决定 Codex 能不能：

看文件
改文件
访问项目外目录
联网
运行命令

Model 模型选择

推理强度

可以看到推理强度分为了4档，强度越高对应的推理能力越强所花的时间和token消耗也越大

模型选择

这里可以选择不同的模型。模型能力、可用范围和消耗会随账号套餐、地区、版本和模型目录变化。普通任务用默认推荐模型即可；复杂任务再考虑切换更强模型或提高推理强度。

速度

有些模型或版本会提供标准 / 快速之类的服务档位。

快速模式的速度提升、额度消耗和是否可用，都以当前界面显示为准。任务很急、额度充足时可以考虑开启；日常任务不需要默认开启。

引导

可中途插入对话

当我们在AI执行的过程中，发现AI理解错了我们的意思，就不应该让它继续执行了，这时候就应该及时进行人工引导

如果不选择引导则会排队执行，只有执行完上一个任务过后，AI才会执行你发送的下一个任务

计划模式

开启计划模式后，Codex 就不会立即上手干活，而是会先整理出一份工作计划，跟我们确认了过后再开始干活

对于所有复杂任务，建议都先开启计划模式，可以查漏补缺。

多功能区

注释

在多功能的右上角区域的注释

当我们用 Codex 内置的浏览器打开了页面过后，会发现有个注释功能

可以让AI帮我们只修改页面的具体部分

Codex CLI 安装与上手

Codex CLI 是 Codex 的命令行版本。

它适合愿意打开终端的人使用，比如 PowerShell、Terminal、iTerm、Windows Terminal。

macOS / Linux 安装

macOS 有两种常见安装方式。

方式一：使用 npm 安装

先确认电脑已经安装 Node.js。

打开 Terminal，输入：

node -v
npm -v

能看到版本号，说明 Node.js 和 npm 已经可用。

然后安装 Codex CLI：

npm install -g @openai/codex

安装完成后，检查是否安装成功：

codex --version

或者直接运行：

codex

方式二：使用 Homebrew 安装

Mac 用户也可以用 Homebrew：

brew install --cask codex

安装后运行：

codex

小白建议：

• 已经装过 Node.js，就用 npm。
• 已经习惯 Homebrew，就用 brew。

Windows 安装

Windows 用户建议使用 PowerShell 或 Windows Terminal。

第一步，安装 Node.js。

安装完成后，打开 PowerShell，输入：

node -v
npm -v

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

第二步，安装 Codex CLI：

npm install -g @openai/codex

第三步，检查是否安装成功：

codex --version

或者直接运行：

codex

Windows 用户第一次使用时，建议不要在系统目录里运行 Codex。

不要在这些位置直接操作：

C:\
系统目录
桌面
下载文件夹
重要资料文件夹

建议新建一个练习目录：

D:\AI-Codex-Projects\hello-codex

第一次运行

安装完成后，在终端输入：

codex

第一次运行时，Codex 会提示你登录。

Codex CLI 常见有两种登录方式：

1. 使用 ChatGPT 账号登录
2. 使用 OpenAI API Key 登录

新手优先推荐第一种：ChatGPT 账号登录。

方式一：使用 ChatGPT 账号登录

这是最适合普通用户和小白的方式。

在终端输入：

codex

或者：

codex login

然后选择：

Sign in with ChatGPT

登录流程大概是：

1. 终端输入 codex 或 codex login
2. 选择 Sign in with ChatGPT
3. 浏览器会自动打开登录页面
4. 输入你的 ChatGPT 账号
5. 登录成功后，浏览器会把登录结果传回终端
6. 回到终端，Codex CLI 就可以使用了

方式二：使用 API Key 登录

Codex CLI 也支持使用 OpenAI API Key 登录。

API Key 登录更适合开发者、自动化脚本、CI/CD、服务器任务等场景。

小白可以这样理解：

ChatGPT 登录 = 走 ChatGPT 账号和套餐额度
API Key 登录 = 走 OpenAI Platform API 计费

如果你要用 API Key 登录，先去 OpenAI Platform 创建 API Key。

然后在终端里设置环境变量。

macOS / Linux 可以这样写：

export OPENAI_API_KEY="你的_API_Key"
printenv OPENAI_API_KEY | codex login --with-api-key

Windows PowerShell 可以这样写：

$env:OPENAI_API_KEY="你的_API_Key"
$env:OPENAI_API_KEY | codex login --with-api-key

登录成功后，Codex CLI 会保存登录信息，后面再次运行：

codex

就可以继续使用。

ChatGPT 登录和 API Key 登录有什么区别？

API Key 登录注意事项

API Key 很敏感，不能随便泄露。

不要把 API Key：

写进代码里
发给别人
截图公开
上传到 GitHub
放进 README
放进前端网页
提交到 Git 仓库

如果不小心泄露了 API Key，要立刻去 OpenAI Platform 删除或重新生成。

API Key 登录虽然方便做自动化，但它会按 API 使用量计费，所以新手不要不清楚费用规则就长时间运行任务。

查看当前登录状态

你可以用下面命令查看当前是否已经登录：

codex login status

如果需要退出登录，可以运行：

codex logout

退出后，下次再运行 Codex CLI，需要重新登录。

CLI 基础命令

Codex CLI 的命令可以分成两类：

CLI 终端命令

CLI 终端命令，是在 PowerShell / Terminal / Windows Terminal 里输入的命令。

小白最常用终端命令

进入项目相关命令

新手推荐最简单的方式：

cd 项目目录
codex

不要在这些地方直接运行 Codex：

C:\
桌面
下载文件夹
系统目录
重要资料文件夹

登录相关命令

Windows PowerShell 使用 API Key 登录：

$env:OPENAI_API_KEY | codex login --with-api-key

启动时直接发任务

适合：

简单解释项目
分析报错截图
根据 UI 截图提修改建议
查新版本文档

新手更推荐先运行：

codex

进入后再输入任务，更容易观察执行过程。

模型、权限、沙盒相关命令

新手推荐组合：

codex --sandbox workspace-write --ask-for-approval on-request

意思是：

Codex 可以在当前项目里工作，但敏感操作要先问我。

不要把这个当成省事模式：

codex --sandbox danger-full-access

非交互式任务命令

示例：

codex exec "请检查当前项目有没有明显问题"

小白阶段优先用：

codex

熟悉后再用 codex exec。

会话管理命令

简单来说：

resume = 接着做
archive = 收起来
unarchive = 找回来
fork = 复制一份去试新方案

诊断、更新和维护命令

小白最常用：

codex doctor
codex update

其他先不用记。

Cloud、MCP、插件相关命令

小白阶段先不用管这些。

等你开始用：

Codex Cloud
外部工具
数据库
Figma
项目管理工具
MCP
插件

再学习这一类命令。

沙盒测试命令

小白阶段不用学。

只要记住：

默认用 workspace-write + on-request。
不要随便 full access。

危险命令和危险参数

看到这些内容，先问 Codex：

请解释这条命令的作用、风险，以及有没有更安全的替代方案。

新手最推荐记住的命令

推荐新手工作流

CLI 斜杠命令

它不是在外面的 PowerShell / Terminal 里输入，而是在进入 Codex 后，在 Codex 输入框里输入 / 使用。

小白最常用命令

模型与速度相关

新手建议：

普通任务：默认模型 + 中推理
复杂 bug：高推理
简单改文案：低推理
不要所有任务都开最高推理

权限与安全相关

新手建议：

默认用 /permissions 保持请求批准。
不要随便放开完全访问权限。
看不懂的操作，不要用 /approve。

代码检查与 Review 相关

推荐流程：

Codex 修改完成
→ /diff 查看改动
→ /review 检查问题
→ 没问题再 git commit

会话管理相关

小白区别：

/new = 开新任务
/clear = 清理并重新开始
/archive = 收起当前任务
/fork = 复制当前任务去试新方案
/side = 临时问个小问题

上下文与长对话相关

新手建议：

对话长了用 /compact。
想让 Codex 看特定文件，用 /mention。
不想让它乱扫整个项目，就明确指定文件。

项目规则与能力相关

新手优先掌握：

/init
/skills

其他命令可以后面再学。

终端和后台任务相关

常见场景：

Codex 跑了 npm run dev
你想看它还在不在跑
→ 用 /ps

命令卡住了
→ 用 /stop

界面与快捷键相关

小白阶段可以先不用这些。

开发者和高级功能

这些不是入门必学内容。

新手知道有就行，不需要一开始掌握。

新手最推荐记住的 8 个

推荐新手使用流程

一句话总结

Slash Commands 是 Codex CLI 里的快捷控制命令。

新手不用全部背，先记住这几个就够了：

/diff       看改动
/plan       先规划
/permissions 控权限
/model      换模型
/status     看状态
/init       建规则
/compact    压缩长对话
/quit       退出

CLI 工作方式

Codex CLI 的工作方式，可以理解成一条完整流程：

读取项目
→ 理解任务
→ 提出计划
→ 修改文件
→ 运行命令
→ 等待批准
→ 展示 diff
→ 处理失败

小白不用一开始理解所有技术细节，只要先知道：

Codex CLI 不是只会聊天，它会真的进入当前项目目录，读文件、改文件、跑命令，然后把结果展示给你检查。

Codex 如何读取项目

当你在项目目录里运行：

codex

Codex 会把当前目录当成工作区。

比如你在这个目录里启动：

D:\AI-Codex-Projects\hello-codex

Codex 就会围绕这个文件夹里的内容工作。

它可能会读取：

简单来说：

你在哪个文件夹启动 Codex，
Codex 就默认把哪个文件夹当成当前项目。

所以不要在这些地方乱启动：

C:\
桌面
下载文件夹
系统目录
重要资料文件夹

推荐做法：

cd 项目目录
codex

Codex 如何理解任务

你输入任务后，Codex 会先判断你想让它做什么。

比如你输入：

请帮我做一个简单网页，黑色背景，中间显示 Hello Codex。

Codex 会判断：

如果你输入：

请检查为什么 npm run build 失败。

Codex 会判断：

小白提示：

任务越清楚，Codex 越稳定。

推荐写法：

请帮我完成【具体任务】。

要求：
1.
2.
3.

限制：
1. 不要修改无关文件
2. 不要删除已有功能
3. 完成后告诉我改了哪些文件

Codex 如何提出计划

复杂任务开始前，Codex 通常会先分析问题，再提出计划。

你也可以主动要求它先计划：

请先给我计划，不要直接修改文件。

或者使用：

/plan

计划通常会包含：

比如：

计划：
1. 先查看 package.json，确认启动命令
2. 运行 npm run build 复现报错
3. 根据报错定位相关文件
4. 最小范围修复问题
5. 再次运行 build 验证

小白建议：

简单任务可以直接让它做。
复杂任务先让它 /plan。

尤其是这些任务，建议先计划：

修复复杂 bug
多文件修改
项目重构
新增功能
构建失败
涉及依赖升级

Codex 如何修改文件

当 Codex 确认要修改文件后，它会在当前项目里进行编辑。

它可能会：

新手要注意：

Codex 可能会改对，也可能会改多。

所以你要养成习惯：

它改完之后，不要直接相信。
一定要看 diff。

你可以提前加限制：

请只修改 index.html 和 style.css，不要修改其他文件。

或者：

请用最小改动修复问题，不要重构整个项目。

这样可以减少 Codex 改动范围过大的问题。

Codex 如何运行命令

Codex 不只会改文件，也可以运行终端命令。

常见命令包括：

比如你让它修构建失败，它可能会运行：

npm run build

然后根据报错继续修改。

小白不要害怕命令，但要看懂再允许。

如果你不懂，可以让它先解释：

请先解释你准备运行的命令，每条命令是干什么的，不要直接执行。

尤其看到这些命令，要谨慎：

rm -rf
sudo
curl xxx | sh
git reset --hard
git clean -fd

这些命令可能删除文件、修改系统、重置代码或执行远程脚本。

Codex 如何等待用户批准

Codex CLI 有权限控制，不是所有操作都能直接执行。

如果 Codex 想做敏感操作，可能会停下来问你。

比如：

简单来说：

批准 = 你允许 Codex 继续做这一步。
拒绝 = 这一步不要做。

如果你看不懂它要做什么，不要直接点允许。

可以先问：

请解释这个操作的作用、风险，以及有没有更安全的替代方案。

新手建议权限：

保持请求批准。
不要随便开启完全访问权限。

Codex 如何展示 diff

Diff 是 Codex 修改前后的代码对比。

你可以在 Codex CLI 里输入：

/diff

它会展示当前改动。

简单来说：

绿色 = 新增内容
红色 = 删除内容

diff 可以帮你确认：

推荐流程：

Codex 完成修改
→ 输入 /diff
→ 查看改动
→ 不满意就让它继续改或撤回
→ 满意后再 git commit

不要只看 Codex 的总结。

真正重要的是：

它实际改了什么。

Codex 如何处理失败

Codex 执行任务失败很正常。

常见失败包括：

Codex 通常会根据失败结果继续分析。

比如：

运行 npm run build 失败
→ 读取报错信息
→ 定位相关文件
→ 修改代码
→ 再次运行 build

但你要注意：

不要让它无限乱试。

如果它连续失败，可以暂停它，让它重新分析：

先停一下。请总结目前失败原因，不要继续修改文件。

或者：

请列出你已经尝试过的方法、失败原因，以及下一步最小改动方案。

如果它改乱了，可以说：

请撤回刚才的修改，恢复到修改前状态。

或者自己用 Git 查看：

git status
git diff

再决定是否保留。

推荐新手工作流

一句话总结

Codex CLI 的工作方式不是'问一句答一句'，而是一个完整的编程流程：

读项目
→ 想方案
→ 改文件
→ 跑命令
→ 等批准
→ 看 diff
→ 修失败
→ 交结果

CLI 常见问题

Codex CLI 常见问题，大多数不是 Codex 本身坏了，而是出在这几个地方：

小白最常见问题

安装类问题

排查命令：

codex --version
node -v
npm -v
codex doctor

小白建议：

安装后第一件事，不是直接用，而是先运行 codex --version。
能看到版本号，说明基础安装正常。

登录类问题

常用命令：

codex login
codex login status
codex logout
codex login --device-auth

新手建议：

本地学习优先用 ChatGPT 账号登录。
API Key 登录更适合开发者、自动化和服务器场景。

项目目录类问题

推荐方式：

cd D:\AI-Codex-Projects\hello-codex
codex

不推荐：

在 C 盘根目录运行
在桌面运行
在下载文件夹运行
在重要资料文件夹运行

一句话：

你在哪个目录运行 codex，它就默认把哪个目录当成项目。

权限和沙盒类问题

推荐设置：

sandbox：workspace-write
approval：on-request

简单来说：

workspace-write = 允许在当前项目里工作
on-request = 敏感操作先问你

不要随便使用：

danger-full-access
--yolo
--dangerously-bypass-approvals-and-sandbox

看到不懂的权限请求，可以问：

请解释这个操作为什么需要权限，会影响哪些文件，有没有更安全的替代方案。

命令运行类问题

常见命令含义：

不懂命令时，先让 Codex 解释：

请先解释你准备运行的命令，每条命令是干什么的，不要直接执行。

Diff 和改动类问题

推荐检查流程：

Codex 完成任务
→ 输入 /diff
→ 看改了哪些文件
→ 看红色删除部分
→ 看是否改了无关文件
→ 满意后再 git commit

提示词可以这样写：

请只修改当前任务相关文件。
不要重构整个项目。
完成后列出修改了哪些文件。

Git 相关问题

推荐新手第一次项目先做：

git init
git add .
git commit -m "initial commit"

之后 Codex 每次改完：

git status
git diff

简单来说：

git status = 看哪些文件变了
git diff = 看具体变了什么
commit = 保存一个版本

模型和额度类问题

省额度建议：

小任务不要开最高推理。
不要一次让 Codex 扫整个项目。
不要反复让它大范围重构。
能指定文件就指定文件。
复杂任务先 /plan，再修改。

推荐配置：

普通任务：默认模型 + 中推理
复杂 bug：高推理
小改动：低推理

Codex 卡住或结果不对

可以这样叫停：

先停一下，不要继续修改文件。
请总结目前做了什么、失败在哪里、下一步最小修改方案是什么。

如果它改偏了，可以说：

这次方向不对。请撤回刚才的无关修改，只保留和首页样式相关的改动。

Windows 常见问题

推荐 Windows 项目路径：

D:\AI-Codex-Projects\hello-codex

不推荐：

C:\Users\你的名字\桌面\新建文件夹

原因：

中文路径、空格、桌面目录，有时更容易出问题。

macOS 常见问题

推荐项目路径：

~/AI-Codex-Projects/hello-codex

常用检查命令：

pwd
ls
codex --version
codex doctor

运行 codex doctor 排查

如果你不知道问题出在哪里，可以先运行：

codex doctor

它适合排查：

安装异常
登录异常
配置异常
终端环境异常
权限问题
系统环境问题

简单来说：

codex doctor = Codex 的体检命令。

遇到复杂问题时，可以把 doctor 结果发给 Codex，让它帮你分析：

请根据 codex doctor 的输出，帮我判断 CLI 哪里有问题。

新手通用排查流程

Codex IDE Extension

把 Codex 直接装进你的代码编辑器里。

你不用单独打开 Codex App，也不用一直切到终端，而是可以在 VS Code、Cursor、Windsurf 这类编辑器侧边栏里直接使用 Codex。

怎么理解 Codex IDE Extension

简单说：

Codex IDE = 在写代码软件里直接叫 Codex 帮你干活

Codex IDE Extension 适合谁

Codex IDE Extension 支持哪些编辑器

新手优先推荐：

VS Code 或 Cursor

Codex IDE Extension 怎么安装

如果你在 Cursor 里找不到 Codex 图标，可能是侧边栏图标被折叠了。可以先检查左侧或右侧活动栏，把 Codex 固定出来。

第一次登录

安装完成后，Codex IDE Extension 会提示你登录。

常见登录方式有两种：

小白优先选择：

Sign in with ChatGPT

也就是用你的 ChatGPT 账号登录。

API Key 登录更适合懂 API 计费和环境变量的开发者。

Codex IDE Extension 在哪里打开

安装成功后，Codex 通常会出现在编辑器侧边栏。

常见位置：

如果找不到，可以尝试：

1. 重启编辑器
2. 打开 Extensions，确认 Codex 已安装
3. 查看左侧活动栏是否有 Codex 图标
4. 查看右侧边栏是否有 Codex 面板
5. 在命令面板里搜索 Codex

Codex IDE Extension 能做什么

Codex Web

在网页里使用的云端 Codex。

它不需要你一直开着本地电脑，也不一定要在终端里操作，而是可以连接 GitHub 仓库，让 Codex 在云端环境里读取代码、执行任务、修改文件，并生成可 review 的结果。

怎么理解 Codex Web

一句话：

Codex Web = 让 Codex 在云端帮你处理 GitHub 项目。

Codex Web 适合谁

小白建议：

刚开始做本地练习，用 Codex App。
项目已经放到 GitHub 后，再学 Codex Web。

Codex Web 入口在哪里

Codex Web 的入口是：

chatgpt.com/codex

打开后，你需要：

Codex Web 和本地 Codex 有什么区别

简单理解：

本地 Codex = 在你电脑上干活
Codex Web = 在云端帮 GitHub 仓库干活

第一次使用 Codex Web 的流程

连接 GitHub 是什么意思

连接 GitHub 的意思是：

让 Codex Web 有权限访问你指定的 GitHub 仓库。

它需要读取仓库代码，才能完成任务。

比如你让 Codex Web 做：

请帮我修复首页按钮点击无反应的问题。

它需要先读取你的项目代码，再判断按钮逻辑在哪里，然后修改相关文件。

简单来说：

GitHub = 放代码的云盘
Codex Web = 进入这个代码云盘帮你改项目

注意：

不要随便授权不信任的账号或组织。
不要一上来让 Codex 访问所有仓库。
能只授权某几个仓库，就只授权需要的仓库。

Repository 仓库是什么

Repository 简称 repo，可以理解成：

一个完整代码项目。

比如：

my-landing-page
ai-tools-site
xiaohongshu-cover-generator
my-react-app

这些都可以是 GitHub 上的仓库。

Codex Web 通常围绕一个仓库创建任务。

简单来说：

仓库 = 一个放在 GitHub 上的项目文件夹

Branch 分支是什么

Branch 可以理解成：

代码的一个独立版本。

比如：

main = 正式版本
feature/homepage = 首页修改版本
fix/button-bug = 修复按钮 bug 的版本

Codex Web 通常不会直接乱改正式分支，而是基于某个分支去做任务，最后生成可检查的修改。

简单来说：

main = 原稿
新分支 = 复制一份出来修改
PR = 把修改后的版本提交给你检查

Pull Request 是什么

Pull Request，简称 PR。

小白可以理解成：

Codex 改完代码后，不是直接把代码合进正式项目，而是先提交一份'修改申请'。

你可以在 PR 里看到：

改了哪些文件
新增了哪些代码
删除了哪些代码
有没有测试通过
Codex 的总结说明
是否可以合并

PR 的好处是：

先检查，再合并。

所以 Codex Web 很适合真实项目和团队项目。

Codex Web 怎么创建任务

创建任务时，最好写清楚：

目标：让 Codex 做什么
范围：只改哪些地方
限制：哪些地方不能动
验证：完成后怎么检查

示例：

请修复首页按钮点击无反应的问题。

要求：
1. 先分析按钮点击逻辑在哪里
2. 只修改和按钮相关的文件
3. 不要重构整个项目
4. 不要删除现有功能
5. 修复后运行构建或测试命令验证
6. 完成后说明修改了哪些文件

不推荐写：

帮我优化一下项目。

太模糊，Codex 容易不知道从哪里下手。

Codex Web 如何运行项目

Codex Web 会在云端创建一个运行环境。

它通常会：

1. 拉取 GitHub 仓库代码
2. 切到指定分支或提交
3. 执行 setup script 安装依赖
4. 根据你的任务读取文件
5. 修改代码
6. 运行测试或构建命令
7. 生成 diff 和总结

如果项目需要安装依赖，就要配置好 setup script。

比如前端项目可能需要：

npm install

或者：

pnpm install

如果没有正确配置环境，Codex 可能会因为缺依赖而运行失败。

Environment 环境是什么

Environment 可以理解成：

Codex Web 在云端运行项目的电脑配置。

它需要知道：

用什么语言
怎么安装依赖
怎么启动项目
怎么运行测试
需要哪些环境变量
是否需要特殊工具

比如一个前端项目可能需要：

Node.js
npm / pnpm
package.json
npm run build

一个 Python 项目可能需要：

Python
pip
requirements.txt
pytest

简单来说：

Environment = Codex 在云端跑项目时需要的工具箱。

Setup Script 是什么

Setup Script 可以理解成：

Codex Web 每次准备云端环境时，先执行的一段安装命令。

比如：

npm install

或者：

pip install -r requirements.txt

它的作用是：

把项目需要的依赖先装好。

如果 setup script 写错了，Codex 可能会跑不起来项目。

小白建议：

先用最简单的安装命令。
不要在 setup script 里写危险命令。
不要把密码和 API Key 写进去。

Codex Web 的网络访问

Codex Web 的云端环境不等于完全自由联网。

通常：

安装依赖阶段可能允许联网
真正执行 agent 任务阶段可能默认限制联网

简单来说：

安装依赖可以联网，干活时不一定能随便联网。

这样做是为了安全，避免任务过程中随意访问外部网络。

如果你的任务必须联网，要看工作区和环境设置是否允许。

Codex Web 的权限要注意什么

Codex Web 主要涉及这些权限：

新手安全建议：

只授权需要的仓库。
不要授权全部仓库。
不要把 .env、API Key、密码、token 写进任务。
不要让 Codex 自动合并 PR。
先 review，再合并。

Codex Web 适合做什么

特别适合：

GitHub 项目
团队项目
需要 PR 流程的项目
不想本地一直开着电脑的任务

Codex Web 不适合什么

新手不建议一开始用 Codex Web 做：

没有 GitHub 的本地小练习
完全不会 Git 的项目
真实生产环境部署
数据库迁移
支付系统修改
自动合并 PR
删除大量文件
处理敏感密钥

这些不是不能做，而是风险更高。

小白建议：

先用 Codex App 做本地练习。
会 GitHub 后，再用 Codex Web 处理仓库任务。

Codex Web 和 Codex Cloud 是一回事吗

可以这样理解：

Codex Web = 你在网页上操作的界面
Codex Cloud = 背后帮你跑任务的云端能力

也就是说：

你在 Codex Web 上输入任务，
Codex Cloud 在云端环境里帮你执行。

小白可以不纠结这两个词。

日常理解成：

Codex Web = 网页入口
Cloud task = 云端任务

第一个 Codex Web 任务建议

新手第一次不要选复杂项目。

建议选择一个简单 GitHub 仓库，比如：

简单 HTML 页面
React 小项目
个人主页
README 项目
小工具页面

任务可以写：

请帮我检查这个项目的 README 是否清楚。

要求：
1. 阅读当前项目结构
2. 说明 README 缺少哪些内容
3. 补充安装步骤、启动命令和项目结构说明
4. 不要修改代码逻辑
5. 完成后创建一个 PR

这个任务风险低，适合熟悉 Codex Web 的流程。

常见问题

新手安全规则

1. 不要一上来授权所有 GitHub 仓库。
2. 不要让 Codex 自动合并 PR。
3. 不要把 API Key、密码、token 写进任务。
4. 不要把 .env 文件提交到仓库。
5. 复杂任务先让 Codex 给计划。
6. PR 里一定要看 diff。
7. 看不懂的改动不要合并。
8. 生产项目不要直接让 Codex 自动部署。
9. 先用简单仓库练习。
10. 满意后再 merge。

第三篇：核心功能详解

自动化

什么是自动化

Codex 自动化 = 让 Codex 不只是'听你指挥'，而是能按规则定期帮你巡查项目、发现问题、处理问题。

就像你给项目请了一个'AI 值班工程师'：

平时它不打扰你， 有问题它来提醒你， 简单问题它先尝试修， 最后让你审核决定。

如何使用自动化

可以用'每周 Codex 会话自动复盘'举例，让 Codex 越来越好用。

你可以让 Codex 定期检查最近一段时间的会话记录、任务结果和常见问题，沉淀成一份可复用的工作流档案。

示例提示词可以这样写：

请检索并复盘最近一周的 Codex 会话记录与执行日志，维护一份'Codex 会话复盘与个人风格档案'。

要求：
1. 优先使用可用的会话历史检索能力；如果需要读取日志，只做搜索、元数据提取和相关片段抽取，不要整文件载入大型 session 文件。
2. 不要复现原始日志、隐私内容、密钥、内部 reasoning 或长对话原文。
3. 总结执行经验：哪些做法导致了问题，最终正确做法是什么，适合什么场景复用。
4. 总结我的偏好：UI 设计偏好、产品理念、交互原则、内容系统偏好和工作流偏好。
5. 整理可复用规则清单：把复盘结论改写成后续 Codex 会话可以遵循的简洁规则。
6. 更新文档时去重、合并相近规则，保留日期范围或任务类型作为来源线索。
7. 如有适合长期复用的规则，请建议是否加入项目级或用户级 AGENTS.md。

插件

给 Codex 额外安装的'能力包'

什么是插件

Codex 本身已经能读代码、改代码、运行命令；插件是在这个基础上，让它连接更多工具、使用固定流程，或者获得某些专项能力。

比如：

插件、Skill、MCP 三者关系（先看这一张表）

插件、Skill、MCP 是本篇最容易混淆的三个概念。它们不是互相替代，而是各管一层，下面这张总表请先记住，后面各节不再重复对比。

一句话记住：插件可以把 Skill 和 MCP 打包成更容易安装的能力包；Skill 管「怎么做」，MCP 管「连什么工具」。

在 Codex App 里怎么安装插件

打开 Codex App

搜索或浏览插件

也可以搜索对应的插件

点开插件详情

点击 Add to Codex 或添加按钮

安装完成后，新开一个 thread 使用

在 Codex CLI 里怎么安装插件

进入项目目录后，先启动 Codex：

codex

然后在 Codex CLI 里输入：

/plugins

打开插件列表后，可以：

常见插件和能力方向

插件目录会随着 Codex 版本、工作区和账号权限变化。下面不是固定排名，而是常见能力方向，实际可安装内容以你当前 Codex 插件页显示为准。

Skill

给 Codex 准备的一套「固定工作方法」。

Codex 本身会读代码、改代码、运行命令。

但如果你经常让它做同一类任务，比如写 README、做代码 Review、生成网页、整理文档，就可以把这套流程做成 Skill。

什么是 Skill

比如你每次都想让 Codex 写 README，并且 README 必须包含：

项目介绍
安装步骤
启动命令
文件结构
常见问题

那就可以做一个 README Skill。

以后你不用每次重新解释规则，只要调用这个 Skill，Codex 就会按这套流程写。

Skill 还是 MCP？什么时候用哪个

插件、Skill、MCP 的整体区别，见前面「插件、Skill、MCP 三者关系」总表。这里只解决最常见的纠结：一个需求到底该用 Skill 还是 MCP。

记住一句话：「怎么做」的问题用 Skill，「连接什么工具」的问题用 MCP。

Skill 和普通提示词有什么区别

只做一次的任务 = 直接写提示词 经常重复做的任务 = 适合做 Skill

Skill 适合什么时候用

Skill 通常包含什么

Skill 的基本结构

一个简单 Skill 可以这样写：

# Skill 名称

## 适用场景
这个 Skill 适合用来做什么。

## 工作目标
Codex 最终要交付什么结果。

## 工作流程
1. 先分析输入内容
2. 再确认任务类型
3. 然后按固定步骤处理
4. 最后输出结果和检查清单

## 输出格式
规定 Codex 最后应该怎么输出。

## 注意事项
哪些事情不能做，哪些风险要提醒。

比如 README Skill：

# README 生成 Skill

## 适用场景
用于根据当前项目生成 README 文档。

## 工作目标
输出一份结构清晰、适合新手阅读的 README。

## 工作流程
1. 阅读项目结构
2. 查看 package.json 或主要入口文件
3. 判断项目类型
4. 生成项目介绍
5. 补充安装步骤和启动命令
6. 说明文件结构
7. 输出常见问题

## 输出格式
使用 Markdown 格式。

## 注意事项
不要编造不存在的功能。
不确定的地方要明确标注。

在 Codex App 里怎么添加 Skill

在 Codex App 里添加 Skill，可以分成两种情况：

1. 使用已有 Skill
2. 创建自己的 Skill

使用已有 Skill

在插件里面的技能可以看到系统推荐的一些Skill

创建自己的 Skill

如果你想自己创建一个 Skill，可以在 Codex App 的 thread 里使用：

$skill-creator

它相当于一个 Skill 创建助手，会帮你把一套重复流程整理成 Skill。

操作步骤：

示例提示词：

$skill-creator

请帮我创建一个 README Skill。

这个 Skill 的作用：
根据当前项目自动生成适合小白阅读的 README。

触发场景：
当我说'生成 README''写项目说明''整理项目文档'时使用。

工作流程：
1. 先阅读项目结构
2. 查看 package.json、README、入口文件
3. 判断项目类型
4. 生成项目简介
5. 写安装步骤
6. 写启动命令
7. 说明主要文件夹作用
8. 补充常见问题
9. 不确定的地方不要编造

输出格式：
使用 Markdown。

必须包含：
- 项目简介
- 功能特点
- 安装步骤
- 启动命令
- 文件结构
- 常见问题
- 后续优化方向

推荐安装的 Skill

在 Codex CLI 里怎么添加 Skill

在 Codex CLI 里添加 Skill，主要有 3 种方式：

1. 使用已有 Skill
2. 用 $skill-creator 创建 Skill
3. 手动创建 SKILL.md 文件

添加 Skill 的 3 种方式

方式一：使用已有 Skill

进入项目目录后，先启动 Codex CLI：

cd 项目目录
codex

进入 Codex CLI 后，可以输入：

/skills

或者直接输入：

$

Codex 会显示当前可用的 Skill。

如果你已经知道 Skill 名称，也可以直接在任务里点名使用：

请使用 $readme-skill，根据当前项目生成 README。

或者：

$ui-review-skill 请检查当前首页的视觉问题，并给出修改建议。

已有 Skill 的使用方式

方式二：用 $skill-creator 创建 Skill

如果你想把一套重复流程保存成 Skill，可以用：

$skill-creator

它相当于一个 Skill 创建助手，会问你：

$skill-creator 使用流程

$skill-creator 示例提示词

$skill-creator

请帮我创建一个 README Skill。

这个 Skill 的作用：
根据当前项目自动生成一份适合小白阅读的 README。

触发场景：
当我说'生成 README''写项目说明''整理项目文档''写安装教程'时使用。

工作流程：
1. 先阅读项目结构
2. 查看 package.json、README、入口文件
3. 判断项目类型
4. 生成项目简介
5. 写安装步骤
6. 写启动命令
7. 说明主要文件夹作用
8. 补充常见问题
9. 不确定的地方不要编造

输出格式：
使用 Markdown。

必须包含：
- 项目简介
- 功能特点
- 安装步骤
- 启动命令
- 文件结构
- 常见问题
- 后续优化方向

注意事项：
不要编造不存在的功能。
不要读取或输出 API Key、密码、token、私钥。

方式三：手动创建 Skill 文件

Skill 本质上是一个文件夹，里面必须有一个：

SKILL.md

最简单的结构是：

.agents
└── skills
    └── readme-skill
        └── SKILL.md

也可以放脚本、参考资料和资源文件：

.agents
└── skills
    └── readme-skill
        ├── SKILL.md
        ├── scripts
        ├── references
        └── assets

Skill 文件结构说明

一个最简单的 SKILL.md 示例

---
name: readme-skill
description: 当用户需要生成 README、项目说明、安装教程、启动步骤时使用。
---

你是一个 README 文档生成助手。

任务：
根据当前项目生成一份适合新手阅读的 README。

工作流程：
1. 阅读项目结构
2. 查看 package.json、README、入口文件
3. 判断项目类型
4. 生成项目介绍
5. 写安装步骤
6. 写启动命令
7. 说明文件结构
8. 补充常见问题
9. 不确定的地方不要编造

输出格式：
使用 Markdown。

必须包含：
- 项目简介
- 功能特点
- 安装步骤
- 启动命令
- 文件结构
- 常见问题
- 后续优化方向

添加 Skill 后怎么使用

添加 Skill 后，有两种常见用法：

如果 Skill 的 description 写得清楚，Codex 会更容易自动判断什么时候该用它。

比如：

description: 当用户需要生成 README、项目说明、安装教程、启动步骤时使用。

这个描述就很清楚。

不建议写得太模糊：

description: 帮我写东西。

这样 Codex 不知道什么时候该调用它。

Skill 放在哪里更合适

MCP

只有进阶AI编程才需要了解，普通人可以直接跳过

让 Codex 连接外部工具的接口。

Codex 本身可以读代码、改代码、运行命令。

MCP 的作用是让 Codex 连接更多外部工具、数据源或服务。

什么是 MCP

生活化理解：

Codex = 一个会干活的人
MCP = 给他接上不同工具的插座
MCP Server = 插在插座上的工具箱
Tool = 工具箱里的具体工具

比如一个文档 MCP，可以让 Codex 读取文档。

一个数据库 MCP，可以让 Codex 查询数据库。

一个设计工具 MCP，可以让 Codex 获取设计稿信息。

MCP 适合做什么

小白可以这样判断：

普通写代码，不一定需要 MCP。
需要 Codex 访问外部工具或外部数据时，才考虑 MCP。

MCP Server 是什么

MCP Server 可以理解成：

给 Codex 提供工具能力的服务。

比如：

简单来说：

MCP Server = Codex 可以调用的外部工具服务。

在 Codex App 里怎么使用 MCP

Codex App 使用 MCP 的基本流程

添加 MCP 时通常需要填什么

添加 MCP 后怎么使用

添加完成后，回到 Codex App 的 thread，直接描述任务即可。

示例提示词：

请使用可用的 MCP 文档工具，
查询 Next.js App Router 的最新用法，
然后告诉我当前项目应该怎么修改。

或者：

请用 Figma MCP 读取这个设计稿，
分析页面结构，并给我生成前端实现计划。

在 Codex CLI 里怎么使用 MCP

在 Codex CLI 里使用 MCP，可以理解成：

给终端版 Codex 接入外部工具。

比如：

文档 MCP：让 Codex 查询开发文档
GitHub MCP：让 Codex 读取 issue、PR、仓库信息
Figma MCP：让 Codex 读取设计稿
数据库 MCP：让 Codex 查询数据库结构

小白可以这样理解：

Codex CLI = 终端里的 AI 编程助手
MCP = 给 Codex CLI 接外部工具的接口

CLI 使用 MCP 的基本流程

常用 MCP 终端命令

添加 MCP 的基本格式

添加 MCP 的基本命令通常是：

codex mcp add 名称 -- 启动命令

简单来说：

名称 = 你给这个 MCP 起的名字
启动命令 = 这个 MCP 怎么启动

示例：

codex mcp add context7 -- npx -y @upstash/context7-mcp

这条命令可以理解成：

给 Codex 添加一个叫 context7 的 MCP。
它通过 npx 启动 @upstash/context7-mcp 这个工具。

查看已经添加的 MCP

添加后可以运行：

codex mcp list

作用：

查看当前 Codex CLI 已经配置了哪些 MCP server。

如果能看到你刚添加的名称，说明配置已经写入。

进入 Codex 后查看 MCP

先进入项目目录：

cd 项目目录

然后启动 Codex：

codex

进入 Codex CLI 后，输入：

/mcp

作用：

查看当前会话里可用的 MCP 工具。

如果 MCP 没显示，可能是：

在任务里调用 MCP

配置好 MCP 后，不一定要记复杂命令。

你可以直接在 Codex CLI 里说：

请使用可用的 MCP 工具，查询 Next.js App Router 的最新文档。

也可以指定某个 MCP：

请用 context7 查询 Next.js App Router 的最新用法，
然后告诉我当前项目应该怎么修改。

如果是 Figma 类 MCP，可以这样说：

请用 Figma MCP 读取这个设计稿，
分析页面结构，并给我生成前端实现计划。

如果是 GitHub 类 MCP，可以这样说：

请用 GitHub MCP 查看这个仓库最近的 open issue，
帮我整理出优先级最高的 3 个问题。

MCP 配置文件在哪里

Codex 的 MCP 配置会写进配置文件里。

常见位置是：

~/.codex/config.toml

简单来说：

config.toml = Codex 的配置文件

里面可能会有类似这样的配置：

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

这表示：

有一个 MCP server 叫 context7。
启动命令是 npx -y @upstash/context7-mcp。

如果你不熟悉配置文件，前期不要手动乱改。

优先使用：

codex mcp add
codex mcp list
codex mcp remove

添加远程 MCP

有些 MCP 不是本地命令启动，而是通过网址连接。

这类一般叫远程 MCP / HTTP MCP。

可能会需要：

如果需要登录，可以使用：

codex mcp login MCP名称

不用了可以：

codex mcp logout MCP名称

新手建议：

先用不需要复杂授权的文档类 MCP。
后面再尝试需要登录的远程 MCP。

删除不用的 MCP

如果某个 MCP 不用了，可以删除：

codex mcp remove 名称

比如：

codex mcp remove context7

删除后再检查：

codex mcp list

确认它已经不在列表里。

代码管理 （Git 与 GitHub 工作流）

用 Codex 做真实项目时，一定要懂一点 Git 和 GitHub。

小白可以先这样理解：

Git = 本地代码版本管理工具
GitHub = 把代码放到网上协作的平台
Codex = 帮你读代码、改代码、跑命令的 AI 编程助手

一句话：

Git 负责记录代码变化。
GitHub 负责远程保存和协作。
Codex 负责帮你完成具体编程任务。

Git 和 GitHub 有什么区别

小白必须先懂的 Git 概念

小白必须先懂的 GitHub 概念

为什么用 Codex 更需要 Git

一句话：

没有 Git，Codex 改错了你很难回退。
有了 Git，Codex 可以放心试，你可以随时检查和恢复。

如何在 Codex 中使用 Git

在 Codex 对话框中输入：把项目初始化成一个 Git 工程，并排除不需要的文件

Codex 会帮我们直接写好 .gitignore 文件

如何在 Codex 中使用 GitHub

使用前需要准备什么

标准上传流程

创建 GitHub 仓库

复制仓库地址

将地址复制给 Codex

推送到 GitHub

代码回滚

修改代码

先让 AI 修改一下代码

提交到 Git，保存好当前版本

继续修改代码

打开 IDE 查看代码并且回退代码

先打开 IDE 查看代码

复制版本号

复制给 Codex，让它回退代码到指定版本

Git Worktree

给同一个 Git 项目，额外开一个独立工作副本。

相当于一个草稿本，效果满意后再合并回正式项目。

为什么需要 Worktree

普通 Git 分支虽然可以切换，但每次只能在一个文件夹里操作一个分支。

Worktree 的好处是：

创建 Worktree

使用分支进行任务

合并回主干

检查效果满意后，就可以合并回主干，并把这个分支删除。

云端运行

Codex 的云端任务适合在你不方便一直开着本地电脑时继续处理工作；如果你的账号和客户端支持移动端入口，也可以在外出时查看或推进部分任务。

把代码任务交给 Codex，让它在云端环境里自己跑。

小白可以这样理解：

Codex 云端运行是什么

Codex 云端运行，本质上是：

云端运行和本地运行的区别

云端运行操作步骤

推送代码到GitHub上面

打开Codex Web

选择我们要修改的仓库

选择好过后直接让Codex给我们工作就行了

修改完成后上传到 GitHub 仓库

本地修改前先同步 GitHub 仓库里的最新代码

如果云端任务已经把修改推回 GitHub，本地继续开发前要先同步最新代码，避免在旧版本上继续修改导致冲突。具体是 Codex 自动帮你应用变更，还是你手动 git pull / codex apply，取决于当前入口和任务类型。

记忆系统

让 Codex 记住一些长期有用的信息，方便以后继续工作。

项目级AGENTS.md

写给 Codex 看的项目规则说明书。

小白可以这样理解：

AGENTS.md 放在哪里

如何写 AGENTS.md

可以直接交给AI来写，让AI总结这个项目的核心内容制作成 AGENTS.md

前端项目 AGENTS.md 模板

# AGENTS.md

## 项目说明

这是一个前端网页项目，用于构建产品页面、工具页面或个人作品展示页面。

## 技术栈

- React
- Vite
- Tailwind CSS
- JavaScript / TypeScript

## 常用命令

- 安装依赖：`npm install`
- 启动项目：`npm run dev`
- 构建项目：`npm run build`

## 项目结构

- `src/`：主要源代码
- `src/components/`：通用组件
- `src/pages/`：页面文件
- `src/assets/`：图片、图标等静态资源
- `public/`：公开静态文件

## 代码规范

- 优先使用 React 函数组件
- 优先使用 Tailwind CSS 写样式
- 不要引入 Bootstrap
- 不要大范围重构无关代码
- 修改时保持文件结构清晰
- 中文文案要自然、简洁、适合普通用户阅读

## UI 规则

- 页面要有清晰的信息层级
- 按钮、卡片、标题、留白要统一
- 移动端要基本可用
- 不要过度渐变、阴影和 AI 模板感
- 优先做真实产品感，而不是 Demo 感

## 禁止事项

- 不要修改 `.env`、`.env.local`
- 不要输出 API Key、token、密码
- 不要删除已有核心功能
- 不要随意新增大型依赖
- 不要直接改动和当前任务无关的文件

## 完成任务后

每次修改完成后，请输出：

1. 修改了哪些文件
2. 每个文件改了什么
3. 为什么这样改
4. 是否需要运行 `npm run build`
5. 提醒我检查 diff

好的 AGENTS.md 有什么特点

全局级AGENTS.md

打开Codex的设置，找到个性化

输入指令，这里的指令会作为你的个人通用偏好影响后续 Codex 会话

使用AI编程的时候最怕AI乱删东西，可以用以下指令

禁止批量删除文件或目录。

不要使用：

• del /s
• rd /s
• rmdir /s
• Remove-Item -Recurse
• rm -rf

需要删除文件时，只能一次删除一个明确路径的文件。

正确示例：

Remove-Item "C:\path\to\file.txt"

如果需要批量删除文件，应停止操作，并向用户请求，让用户手动删除。

第四篇：标准工作流

从需求到交付的完整链路

很多人刚开始用 Codex，会直接一句话丢给它：

帮我做一个网站。 帮我改这个功能。 帮我优化这个项目。

这样不是不行，但很容易出现一个问题： AI 改得很快，但你不知道它到底改了什么，也不知道能不能放心交付。

所以真正稳定的方式，不是让 Codex 一口气乱改，而是按照一套固定工作流来推进。

你可以把它理解成：

需求不是直接变成交付物，中间必须经过'理解、计划、修改、验证、检查、验收'这几步。

标准六步法

第一步：需求拆解

在让 Codex 修改项目之前，第一件事不是写代码，而是先拆需求。

很多人用 Codex 容易翻车，不是因为 Codex 不会写代码，而是因为一开始需求没说清楚。

比如你只说：

帮我优化首页。

Codex 可能会理解成：

• 改 UI
• 改文案
• 改布局
• 改组件结构
• 改路由
• 甚至顺手删掉一些它觉得'没用'的代码

所以在正式动手前，应该先把需求拆成几个关键问题。

背景是什么

先说明这个任务为什么要做。

要解决什么问题

需求要尽量具体，不要只写'优化''美化''改好一点'。

好的需求应该能回答：

这次到底要解决哪一个具体问题？

示例：

这次主要解决三个问题：
1. 首屏标题表达不清楚
2. CTA 按钮不明显
3. 移动端首屏内容太拥挤

哪些文件可能相关

如果你知道大概文件位置，最好提前告诉 Codex。

这样可以减少它全项目乱找、乱改的概率。

哪些功能不能动

这一点非常重要。

Codex 很容易为了完成当前任务，顺手改掉其他地方。

所以要提前告诉它：

这一步的核心是给 Codex 画边界。

什么结果算完成

不要只说'做完就行'，要告诉 Codex 什么叫完成。

示例：

完成标准：
1. 首页首屏能清楚表达产品用途
2. CTA 按钮更明显
3. 移动端显示正常
4. 不影响其他页面
5. 项目可以正常运行和构建

需要哪些测试

改完之后不能只看 Codex 说'完成了'，还要提前说明需要怎么验证。

有哪些风险

需求拆解时，还要提前让 Codex 判断风险。

这样它不会一边改一边乱试。

需求拆解提示词模板

实际使用 Codex 时，可以直接复制这段：

请先帮我做需求拆解，不要立刻修改代码。

需求：
【这里写你的需求】

请按下面结构分析：

1. 背景是什么
- 当前项目大概是什么
- 为什么要做这个需求
- 这个需求属于新功能、Bug 修复、UI 优化，还是重构

2. 要解决什么问题
- 当前具体问题是什么
- 本次要解决到什么程度
- 哪些内容不是本次范围

3. 哪些文件可能相关
- 请根据项目结构判断可能涉及哪些文件
- 先列出来，不要直接修改

4. 哪些功能不能动
- 不要改哪些逻辑
- 不要动哪些接口
- 不要影响哪些页面或组件

5. 什么结果算完成
- 功能完成标准
- 页面完成标准
- 代码完成标准

6. 需要哪些测试
- 需要运行什么命令
- 需要手动检查哪些页面
- 需要重点验证哪些流程

7. 有哪些风险
- 可能影响哪些功能
- 是否有样式污染风险
- 是否有重构过度风险
- 是否有新增依赖风险

最后，请给我一个简短的执行建议：
- 建议先做哪一步
- 是否需要我确认后再修改

第二步：让 Codex 制定计划

需求拆解完成后，不要马上让 Codex 写代码。

这一步要让 Codex 先制定计划。

你可以把它理解成：

先让 AI 说清楚它准备怎么做，再决定要不要让它动手。

很多项目翻车，不是因为 Codex 不会改，而是因为它一上来就开始改。

等你发现方向不对时，它可能已经改了很多文件，回头检查和回滚都很麻烦。

所以第二步的核心是：

先计划，后执行。 先确认，后修改。

先不要写代码

这一点要写在提示词最前面。

因为 Codex 的默认倾向是：看到需求后直接开始解决问题。

但在真实项目里，直接改代码风险很高。

示例提示词：

先不要写代码，也不要修改任何文件。
请先根据当前需求和项目结构，制定一个修改计划。
等我确认后，再开始执行。

开启计划模式

可以参考前文 Codex App 基础使用里的「计划模式」小节。实际使用时，也可以直接在 Codex CLI 或 App 输入 /plan，先让 Codex 输出计划，再决定是否执行。

第三步：小步实现

计划确认后，才进入真正的代码修改阶段。

但这里有一个非常重要的原则：

不要让 Codex 一次性把所有东西都改完。

很多人用 Codex 翻车，就是因为一上来就让它'全部实现'。

结果它可能会同时改页面、改组件、改样式、改接口、改配置，最后项目虽然看起来变了，但你很难判断到底哪里出了问题。

所以更稳定的方式是：

一次只改一个功能点。 改完一小步，就检查一小步。

一次只改一个功能点

小步实现的核心是控制修改范围。

比如你要优化首页，不要一次性说：

请帮我优化整个首页。

更推荐拆成这样：

这样每一步都很清楚，出问题也容易定位。

不要让 Codex 顺手重构无关代码

Codex 有时候会觉得某些代码'不够优雅'，然后顺手帮你重构。

但真实项目里，顺手重构是很危险的。

所以在小步实现时，要明确限制：

本次只实现当前功能点。
不要顺手重构无关代码。
不要修改命名、目录结构、依赖版本和全局配置。
如果你发现代码可以优化，请先记录为建议，不要直接修改。

这句话很重要。

Codex 可以提建议，但不能私自扩大改动范围。

不要接受大面积无解释修改

如果 Codex 一次性改了很多文件，而且没有解释清楚原因，就要暂停。

尤其是看到这些情况时，要提高警惕：

遇到不确定先停下来问

小步实现不是让 Codex 什么都问，而是遇到关键不确定时必须停下来。

比如：

可以提前给 Codex 加这条规则：

如果你遇到以下情况，请先停下来问我，不要自行决定：

1. 不确定该改哪个文件
2. 不确定是否要删除旧代码
3. 不确定是否要新增依赖
4. 不确定业务逻辑应该怎么处理
5. 不确定测试失败原因
6. 发现需要超出原计划的修改

小步实现提示词模板

实际使用时，可以直接复制下面这段：

请开始小步实现。

当前只执行第【1】步：
【这里写本次只做的一个功能点】

要求：
1. 一次只改这个功能点
2. 只修改和当前功能直接相关的文件
3. 不要顺手重构无关代码
4. 不要修改目录结构
5. 不要新增不必要依赖
6. 不要删除已有功能
7. 不要改计划外的文件

修改完成后请停止，并输出：

1. 本次修改了哪些文件
2. 每个文件改了什么
3. 为什么这些修改是必要的
4. 有没有改到计划外内容
5. 有没有潜在风险
6. 下一步建议做什么

注意：
如果遇到不确定的地方，请先停下来问我，不要自行决定。

第四步：测试

Codex 完成小步修改后，不能马上进入下一步，必须先测试。

很多人用 Codex 最大的问题是：

AI 说完成了，但项目其实没跑通。 页面看起来正常，但某些功能已经坏了。 当前功能修好了，旧功能却被影响了。

所以测试的核心是：不是相信 Codex 说「完成」，而是用结果证明它真的完成。

下面这张表覆盖了一次完整测试要做的事，按从快到慢的顺序执行即可：

两个提醒：很多老项目本身就有 lint 或类型问题，不要让 Codex 把历史问题都顺手重构；回归测试是最容易被小白忽略的一步——改了首页按钮，也可能影响复用同一组件的其他页面。

手动测试时，可以让 Codex 把验证步骤列成「操作—预期结果」表格，例如：

测试阶段提示词模板

实际使用时，可以直接复制这段：

请对本次修改进行测试，不要继续新增功能。

请按下面顺序执行或说明：

1. 单元测试
- 项目是否有单元测试
- 如果有，请运行测试命令
- 如果失败，请说明失败原因

2. 类型检查
- 项目是否有 typecheck 命令
- 如果有，请运行
- 如果没有，请说明

3. lint
- 运行 lint 检查
- 区分本次新增问题和项目原有问题

4. 构建
- 运行 build 命令
- 如果失败，请说明报错原因和影响范围

5. 手动测试
- 列出需要手动测试的页面
- 列出用户操作步骤
- 列出每一步预期结果

6. 浏览器测试
- 检查页面显示
- 检查控制台报错
- 检查移动端布局
- 检查关键按钮和交互

7. 回归测试
- 检查本次修改是否影响旧功能
- 列出可能受影响的页面、组件和流程

最后请输出测试总结：
- 哪些测试通过了
- 哪些测试失败了
- 失败原因是什么
- 是否可以进入下一步
- 是否需要先修复问题

第五步：代码审查

测试通过后，不代表这次修改就可以直接交付。

还需要做代码审查。

代码审查可以理解成：

不只是看代码能不能跑，还要看代码改得对不对、稳不稳、有没有风险。

Codex 写代码很快，但它也可能出现这些问题：

所以代码审查不是可选项，而是 Codex 工作流里的关键一步。

两轮审查：Codex 自审 + 人工审查

第一轮先让 Codex 自查刚才的修改（目的不是完全相信它，而是让它先暴露明显问题），最好让它输出成表格：

第二轮人工审查。最终交付的人是你，不是 Codex。不要求每行都看懂，但要重点看 diff 的这几处：