OpenAI Codex 全面教学指南

从零基础到精通 —— 系统掌握 OpenAI Codex 的完整学习路径

教程目录

推荐学习路径

【新手起步】
 01 → 02 → 03 → 04
 ↓
【独立开发】
 05 → 06 → 07
 ↓
【团队 & 复杂项目】
 08 → 09 → 10

使用前须知

• 系统要求：macOS（优先支持），Windows 支持正在推进中
• 账号要求：ChatGPT Plus / Pro / Team / Enterprise 订阅，或 OpenAI API Key
• Node.js 版本：建议 v22 或更高版本

本教程系列持续更新，建议按顺序阅读以获得最佳学习效果。

第 01 课：什么是 Codex？初识与安装

难度：入门 ｜ 预计阅读时间：10 分钟

Codex 是什么？

简单来说，Codex 是一个能帮你写代码的 AI 助手，但它远比普通的代码补全工具强大得多。

你可以把它想象成：

一个高级程序员助理，你只需要用自然语言告诉他你想要什么，他就能帮你完成从写代码、修 Bug、跑测试到管理文件的一切工作。

Codex 和普通 AI 聊天有什么区别？

安装 Codex

第一步：安装 Node.js

Codex 依赖 Node.js 运行，推荐安装 v22 或更高版本。

1. 打开浏览器，访问 https://nodejs.org
2. 下载并安装 LTS（长期支持）版本
3. 安装完成后，打开终端验证安装：

node --version
# 应输出类似：v22.x.x

第二步：安装 Codex CLI

打开终端，输入以下命令：

npm install -g @openai/codex

-g 是什么意思？ 这表示"全局安装"，安装后在任何地方都能使用 codex 命令。

安装完成后验证：

codex --version

第三步：登录账号

在终端输入：

codex

首次运行时，Codex 会引导你完成登录。你有两种方式：

方式 A：用 ChatGPT 账号登录（推荐新手）

• 按照提示，用浏览器扫码或点击链接登录
• 需要 ChatGPT Plus / Pro / Team / Enterprise 订阅

方式 B：用 API Key 登录（适合开发者）

• 前往 platform.openai.com 获取 API Key
• 在终端设置环境变量：

# macOS / Linux
export OPENAI_API_KEY="你的API Key"

# Windows PowerShell
$env:OPENAI_API_KEY="你的API Key"

桌面版 vs 命令行版

Codex 有两种使用方式：

命令行版（CLI）

• 在终端中使用，功能完整
• 输入 codex 启动

桌面版（Desktop App）

• 图形界面，更直观
• 支持多个 Agent 同时并行工作
• 在终端输入 codex app 启动，或直接安装桌面应用程序

本教程系列主要围绕桌面版展开，但 CLI 相关技巧同样适用。

安装成功检查清单

• Node.js v22+ 安装完成
• npm install -g @openai/codex 执行成功
• codex --version 能正常输出版本号
• 已完成账号登录

下一步

恭喜你完成安装！前往 第 02 课：界面介绍与第一次对话 开始你的第一次 AI 编程体验。

第 02 课：界面介绍与第一次对话

难度：入门 ｜ 预计阅读时间：15 分钟

启动 Codex 桌面版

打开终端，进入你想工作的项目文件夹，然后启动桌面版：

# 进入你的项目目录（示例）
cd ~/Documents/my-project

# 启动桌面版
codex app

为什么要先进入项目目录？ Codex 会自动扫描当前目录下的所有文件，理解你的项目结构。在正确的目录下启动，它才能"读懂"你的项目。

界面总览

Codex 桌面版界面分为以下几个区域：

┌─────────────────────────────────────────────┐
│ 顶部工具栏：项目名称 / Agent 状态 / 设置 │
├──────────────┬──────────────────────────────┤
│ │ │
│ 左侧面板 │ 主工作区（对话窗口） │
│ - 项目文件树 │ │
│ - 对话历史 │ │
│ - Agent 列表 │ │
│ │ │
├──────────────┴──────────────────────────────┤
│ 底部输入框：在这里输入你的指令 │
└─────────────────────────────────────────────┘

各区域说明

第一次对话：Hello, Codex!

让我们从最简单的任务开始，感受一下 Codex 的能力。

实验 1：问一个问题

在底部输入框中输入：

这个项目的目录结构是什么？帮我解释一下每个文件的作用。

Codex 会：

1. 自动扫描项目目录
2. 列出所有文件和文件夹
3. 用中文解释每个部分的作用

实验 2：创建第一个文件

输入：

创建一个名为 hello.py 的文件，里面打印 "你好，Codex！"

你会看到 Codex：

1. 提出一个文件创建计划
2. 展示将要写入的代码
3. 等待你确认（在默认 Suggest 模式下）

点击 "确认" 按钮后，文件就会被创建！

常用内置命令

在对话框中输入 / 可以看到所有内置命令，以下是最常用的：

示例：查看状态

在输入框输入：

/status

你会看到：

• 当前使用的模型版本
• 本次会话消耗的 Token 数
• 当前权限模式

恢复上次的会话

如果你关闭了 Codex 又重新打开，想继续上次的工作：

在 CLI 模式下：

codex resume --last

在桌面版中： 点击左侧"对话历史"，找到上次的会话点击即可恢复。

新手常见问题

Q：我不会英文，可以用中文和 Codex 说话吗？ A：完全可以！Codex 支持中文指令，你看到的所有回复也可以要求它用中文输出。

Q：Codex 能理解我的整个项目吗？ A：是的，只要你在项目根目录启动 Codex，它会自动读取相关文件来理解上下文。

Q：如果 Codex 做错了怎么办？ A：在默认 Suggest 模式下，所有操作都需要你确认才会执行，你可以随时拒绝。此外，建议配合 Git 使用（见第 10 课）。

本课要点

• 了解 Codex 桌面版界面布局
• 学会启动 Codex 并进行第一次对话
• 掌握内置命令 /status /permissions 的使用
• 知道如何恢复上次会话

下一步

前往 第 03 课：基础代码生成——写你的第一个程序，开始真正的 AI 编程之旅！

第 03 课：基础代码生成——写你的第一个程序

难度：基础 ｜ 预计阅读时间：20 分钟

本课目标

通过三个由简到难的实战练习，掌握 Codex 最核心的能力——用自然语言生成可运行的代码。

实战练习一：生成一个简单脚本

任务：创建一个数字猜谜游戏

在 Codex 输入框中输入：

用 Python 写一个猜数字游戏：
- 程序随机生成 1 到 100 之间的整数
- 用户输入猜测，程序告诉用户"猜大了"或"猜小了"
- 猜对后显示"恭喜！你用了 X 次猜中了"
- 将文件保存为 guess_game.py

Codex 生成的代码示例：

import random

def play_game():
 secret = random.randint(1, 100)
 attempts = 0

 print("欢迎来到猜数字游戏！我已经想好了一个 1-100 之间的数字。")

 while True:
 try:
 guess = int(input("请输入你的猜测："))
 attempts += 1

 if guess < secret:
 print("猜小了！再试试。")
 elif guess > secret:
 print("猜大了！再试试。")
 else:
 print(f" 恭喜！你用了 {attempts} 次猜中了！答案是 {secret}。")
 break
 except ValueError:
 print("请输入一个有效的数字！")

if __name__ == "__main__":
 play_game()

运行验证

生成后，让 Codex 帮你运行它：

帮我运行 guess_game.py，验证它能正常工作

实战练习二：为代码添加功能

在已有代码的基础上，让 Codex 扩展功能：

在 guess_game.py 基础上增加以下功能：
1. 增加难度选择：简单（1-50次机会），中等（10次机会），困难（5次机会）
2. 游戏结束后询问是否再来一局
3. 记录并显示历史最佳成绩

关键技巧：描述你想要的结果，而不是如何实现它。 不好的方式："在第 15 行添加一个 if 语句判断次数" 好的方式："当用户用完所有机会后，显示游戏失败并揭示答案"

实战练习三：生成不同类型的代码

Codex 不只会写 Python，试试这些：

生成网页

创建一个简单的 HTML 页面，显示一个漂亮的个人名片：
- 包含姓名、职业、联系方式
- 使用现代简洁的 CSS 样式
- 保存为 profile.html

生成配置文件

为一个 Node.js 项目创建 package.json，
项目名称叫 my-app，版本 1.0.0，
包含 express 和 dotenv 依赖

生成 SQL 查询

写一条 SQL 语句，查询用户表中
过去 30 天内注册的、年龄在 18-35 岁之间的活跃用户，
按注册时间降序排列，只取前 20 条

理解 Codex 的工作方式

Codex 在生成代码时会经历以下步骤：

1. 理解需求：解析你的自然语言描述
2. 分析上下文：读取项目中的相关文件
3. 生成方案：制定实现计划
4. 展示变更：以 diff 形式展示将要做的修改
5. 等待确认：在你批准前不做任何改动

新手常见误区

本课要点

• 用自然语言描述需求，让 Codex 生成完整代码
• 在已有代码上迭代添加功能
• Codex 支持多种编程语言和文件类型
• 描述"想要什么结果"比描述"怎么实现"更有效

下一步

前往 第 04 课：权限模式详解，了解如何安全地让 Codex 自主完成更多任务。

第 04 课：权限模式详解——Suggest / Auto Edit / Full Auto

难度：基础 ｜ 预计阅读时间：15 分钟

为什么需要权限模式？

Codex 是一个能直接操作你电脑文件的 AI。为了安全，它设计了三种权限级别，让你决定"AI 可以自主做多少事"。

类比理解：想象你雇了一个新员工（Codex）：

• Suggest 模式：他只给建议，每一步都等你签字
• Auto Edit 模式：他可以自己修改文档，但跑外勤要先汇报
• Full Auto 模式：你给他一个大任务，他全权处理，完成后报告结果

模式一：Suggest（默认）

适合场景

• 刚开始使用 Codex 的新手
• 对陌生代码库进行修改
• 不确定 Codex 会做什么时

工作方式

每次 Codex 想要：

• 创建/修改/删除文件 → 需要你确认
• 运行终端命令 → 需要你确认

操作体验

你：帮我创建一个 config.json 文件

Codex：我计划创建以下文件：
 config.json
{
 "version": "1.0",
 "debug": false
}

[确认] [拒绝] [修改后再确认]

模式二：Auto Edit

适合场景

• 你信任 Codex 对文件的操作
• 需要让 Codex 修改多个文件但想控制命令执行
• 日常编码工作中最推荐的模式

工作方式

• 读取文件 → 自动执行
• 创建/修改文件 → 自动执行
• 运行 shell 命令 → 需要你确认

如何切换

在对话框输入：

/permissions

选择 Auto Edit 选项。

或者启动时直接指定：

codex --approval-mode auto-edit

模式三：Full Auto

适合场景

• 熟悉 Codex 并完全信任它
• 处理独立、封闭的任务（不影响核心代码）
• 在沙箱环境中进行大规模重构

工作方式

• 读取文件 → 自动执行
• 创建/修改文件 → 自动执行
• 运行 shell 命令 → 自动执行（在沙箱中）

安全须知

Full Auto 模式中，Codex 会在沙箱（Sandbox）中运行命令，意味着：

• 网络访问受限
• 无法影响沙箱外的系统文件
• 但仍可以修改你项目内的文件

 强烈建议：在使用 Full Auto 之前，先用 Git 提交一次！
 这样即使出现问题，可以一键回滚。

启动方式：

codex --approval-mode full-auto

随时切换模式

你可以在任何时候改变权限模式，不需要重启：

/permissions

会弹出选项：

当前模式：Suggest
请选择新模式：
 1. Suggest（每步确认）
 2. Auto Edit（文件自动，命令确认）
 3. Full Auto（完全自动，沙箱内运行）

模式对比一览

实用建议

1. 新手从 Suggest 开始，观察 Codex 的操作习惯后再升级
2. 日常使用推荐 Auto Edit，效率和安全之间的最佳平衡
3. Full Auto 配合 Git 使用，出错可以随时回滚
4. 遇到重要项目，临时降回 Suggest 模式再操作

本课要点

• 理解三种权限模式的区别和适用场景
• 掌握如何随时切换权限模式
• 知道 Full Auto 模式的安全机制（沙箱）
• 建立"权限模式 + Git"的安全习惯

下一步

前往 第 05 课：在真实项目中使用 Codex，把 Codex 融入你的实际开发流程。

第 05 课：在真实项目中使用 Codex

难度：进阶 ｜ 预计阅读时间：25 分钟

从玩具到生产——真实项目的挑战

前几课你已经能让 Codex 生成代码片段了。但在真实项目中，情况更复杂：

• 项目有几十甚至几百个文件
• 代码之间有复杂的依赖关系
• 需要遵守特定的代码风格
• 改动一个地方可能影响其他地方

本课教你如何在这种环境下高效使用 Codex。

第一步：正确初始化工作环境

永远在项目根目录启动 Codex！

# 正确做法：进入项目根目录再启动
cd /path/to/your-project
codex app

# 错误做法：在桌面或其他目录启动
cd ~/Desktop
codex app

为什么这很重要？

Codex 启动时会扫描当前目录，建立对项目的"认知"。在根目录启动，它能：

• 了解项目的整体结构
• 读取 package.json、requirements.txt 等配置文件
• 找到相关的工具链配置

第二步：让 Codex 先理解你的项目

在开始任何修改前，先让 Codex 做一个项目分析：

帮我分析这个项目：
1. 这是什么类型的项目？技术栈是什么？
2. 主要有哪些模块？各自负责什么功能？
3. 代码风格和约定是什么？
4. 目前有没有明显的问题或可以改进的地方？

Codex 会给出详细的项目分析报告。这一步非常重要，让你和 Codex 对项目有共同的认知基础。

第三步：常见开发任务的标准指令

添加新功能

在用户模块（src/user/）中添加"用户头像上传"功能：
- 支持 JPG、PNG 格式，文件大小不超过 2MB
- 保存到 /uploads/avatars/ 目录
- 更新用户表的 avatar_url 字段
- 需要编写对应的单元测试

重构现有代码

重构 src/utils/dataProcessor.js 文件：
- 将超过 50 行的函数拆分成更小的函数
- 添加 JSDoc 注释
- 保持原有的功能不变，不要修改接口

修复 Bug

用户反映登录后刷新页面会退出登录。
相关代码在 src/auth/ 目录。
请帮我找到原因并修复，不要影响其他认证功能。

优化性能

src/api/products.js 中的 getProductList 接口响应很慢。
请分析原因（可能是 N+1 查询、缺少索引等），
并提出优化方案，在我确认后再执行。

第四步：任务拆解技巧

对于大型任务，不要一次提交，要拆成小步骤：

不好的方式（一次要太多）

帮我做一个完整的电商系统，包含用户管理、商品管理、
购物车、订单系统、支付集成、物流追踪...

好的方式（循序渐进）

第一步：帮我设计用户系统的数据库表结构，
先不要写代码，给我看方案后我确认再继续。

（确认后）第二步：按照刚才的表结构，
创建用户注册和登录的 API 接口。

（确认后）第三步：为这两个接口写单元测试。

处理跨文件修改

当一个功能需要修改多个文件时，明确告诉 Codex 影响范围：

我需要在订单系统中增加"优惠券"功能，
这会涉及以下文件的修改：
- 数据库：需要新建 coupons 表
- 后端：src/api/orders.js 和 src/models/Order.js
- 前端：src/components/Checkout.vue

请先给我展示完整的修改方案，我确认后再执行。

保护关键代码

对于不想被 Codex 触碰的文件，明确说明：

帮我优化 src/utils/ 目录下的代码，
但不要修改以下文件：
- src/utils/crypto.js（安全相关，已经过审计）
- src/utils/config.js（配置文件，由运维管理）

本课要点

• 始终在项目根目录启动 Codex
• 先做项目分析，建立共同认知
• 用具体的指令描述任务（包含文件路径、约束条件）
• 大任务拆成小步骤，逐步推进
• 明确保护不希望被修改的文件

下一步

前往 第 06 课：AGENTS.md——让 Codex 记住你的项目规范，解锁持久化项目记忆。

第 06 课：AGENTS.md——让 Codex 记住你的项目规范

难度：进阶 ｜ 预计阅读时间：20 分钟

问题：Codex 不记得你的偏好

每次重新启动 Codex，它都是"全新的"——不记得你上次告诉它的代码规范、技术偏好或项目约定。

这意味着你可能每次都要重复告诉它：

• "我们用 TypeScript，不用 JavaScript"
• "缩进用 2 个空格"
• "注释要用中文"
• "测试框架用 Jest"

解决方案：AGENTS.md 文件

什么是 AGENTS.md？

AGENTS.md 是放在项目根目录的一个特殊文件。Codex 每次启动时会自动读取它，就像给新来的员工的入职手册一样。

your-project/
├── AGENTS.md ← Codex 自动读取这个文件
├── src/
├── tests/
└── package.json

如何创建 AGENTS.md

方法一：让 Codex 帮你生成

根据这个项目的现有代码和结构，
帮我生成一个 AGENTS.md 文件，
包含项目规范、技术栈、代码风格等信息。

方法二：手动创建

在项目根目录创建 AGENTS.md，以下是一个完整模板：

AGENTS.md 完整模板

# 项目 Agent 规范手册

## 项目概述
这是一个 [项目类型] 项目，主要功能是 [简短描述]。

## 技术栈
- 语言：TypeScript 5.x
- 前端框架：React 18 + Next.js 14
- 后端：Node.js + Express
- 数据库：PostgreSQL（使用 Prisma ORM）
- 测试：Jest + React Testing Library
- 代码检查：ESLint + Prettier

## 代码风格
- 缩进：2 个空格
- 引号：单引号
- 分号：不使用
- 行宽：最大 100 字符
- 变量命名：camelCase（变量/函数），PascalCase（类/组件）

## 注释规范
- 所有注释使用中文
- 函数必须有 JSDoc 注释，说明参数和返回值
- 复杂逻辑必须有行内注释

## 文件结构约定
- 组件放在 src/components/
- API 路由放在 src/api/
- 工具函数放在 src/utils/
- 类型定义放在 src/types/
- 测试文件放在对应文件的 __tests__ 目录

## 测试规范
- 所有新功能必须配套单元测试
- 测试覆盖率不低于 80%
- 使用 describe / it 结构组织测试

## 禁止事项
- 不要使用 any 类型（TypeScript）
- 不要提交 console.log 到生产代码
- 不要修改 src/core/ 目录下的文件（核心模块，需团队审查）

## Git 约定
- 提交信息格式：[类型] 简短描述（如：[feat] 添加用户头像上传功能）
- 类型：feat（功能）/ fix（修复）/ refactor（重构）/ docs（文档）/ test（测试）

## 其他说明
- 所有 API 接口返回统一格式：{ success: boolean, data: T, message: string }
- 错误处理统一使用 src/utils/errorHandler.ts

AGENTS.md 的威力

有了 AGENTS.md，你可以简化很多指令：

没有 AGENTS.md 时

用 TypeScript 写一个用户服务类，用单引号，不用分号，
2空格缩进，添加中文 JSDoc 注释，
方法放在 src/services/ 目录，
同时在 __tests__/services/ 目录写 Jest 测试...

有了 AGENTS.md 后

按照项目规范，写一个用户服务类

多级 AGENTS.md

你可以在子目录中放额外的 AGENTS.md，用于覆盖或补充特定目录的规范：

your-project/
├── AGENTS.md ← 全局规范
├── src/
│ ├── api/
│ │ └── AGENTS.md ← API 模块专属规范（可覆盖全局设置）
│ └── components/
│ └── AGENTS.md ← 组件模块专属规范

让 AGENTS.md 保持更新

随着项目演进，记得更新 AGENTS.md：

我们最近决定把测试框架从 Jest 改为 Vitest，
请更新 AGENTS.md 中的相关说明，
并列出哪些现有测试文件需要调整。

本课要点

• 理解 AGENTS.md 的作用：项目规范的"入职手册"
• 掌握 AGENTS.md 的完整结构和写法
• 学会用多级 AGENTS.md 管理不同模块的规范
• 养成让 Codex 生成并维护 AGENTS.md 的习惯

下一步

前往 第 07 课：高级提示词技巧——精准指挥 AI，把你的指令效率提升 10 倍。

第 07 课：高级提示词技巧——精准指挥 AI

难度：高级 ｜ 预计阅读时间：30 分钟

什么决定了 Codex 的输出质量？

你给 Codex 的指令质量，直接决定它输出的代码质量。

这一课我们系统学习提示词工程（Prompt Engineering）在 Codex 中的实际应用。

技巧一：角色设定（Role Setting）

在开始任务前，先告诉 Codex 以什么角色思考：

你现在是一位专注于安全性的后端高级工程师，
有 10 年防御 SQL 注入、XSS 攻击的经验。
请以这个视角审查我们的用户输入处理模块（src/utils/inputSanitizer.js），
找出所有潜在的安全漏洞。

对比没有角色设定的效果：

# 模糊指令
检查一下 inputSanitizer.js 有没有问题

# 带角色的指令
（上面的例子）→ 会得到更专业、更深入的安全分析

技巧二：给出约束条件（Constraints）

明确说明边界条件，避免 Codex 走弯路：

优化 searchProducts 函数，要求：
 必须保持原有的函数签名不变（其他地方有调用）
 响应时间要降到 200ms 以内
 只能使用现有的 PostgreSQL，不能引入 Elasticsearch
 不能破坏现有的 10 个测试用例
 不要修改数据库表结构
 不要引入新的 npm 依赖

技巧三：给出示例（Few-shot Prompting）

用例子告诉 Codex 你想要的格式：

帮我为所有 API 接口添加错误处理，格式参考以下示例：

// 现在的代码（没有错误处理）：
async function getUser(id) {
 const user = await db.users.findById(id)
 return user
}

// 期望的格式（带错误处理）：
async function getUser(id) {
 try {
 const user = await db.users.findById(id)
 if (!user) {
 throw new NotFoundError(`用户 ${id} 不存在`)
 }
 return { success: true, data: user }
 } catch (error) {
 logger.error('获取用户失败', { id, error })
 throw error
 }
}

请按照这个格式，处理 src/api/ 目录下所有没有错误处理的函数。

技巧四：分步推理（Chain of Thought）

让 Codex 在执行前先思考，避免盲目行动：

我需要把用户认证从 Session 改为 JWT，
这是一个高风险的改动。

请先不要写代码，而是：
1. 列出所有会受影响的文件和模块
2. 分析可能的风险点
3. 给出迁移方案（按步骤列出）
4. 预估每个步骤的工作量

等我确认方案后，再开始实施第一步。

技巧五：上下文锚定（Context Anchoring）

在修改时，明确告诉 Codex 需要保持一致的地方：

我要在 OrderService 中添加"退款"功能。

参考以下已有的实现作为风格标准：
- 支付功能在 src/services/OrderService.js 的 processPayment 方法
- 错误处理方式参考 refundPayment 方法（虽然还没完整实现）
- 日志格式参考 src/utils/logger.js 的 logTransaction 方法

新的退款功能要和这些保持风格一致。

技巧六：迭代优化（Iterative Refinement）

不要期望一次就完美，要学会迭代：

# 第一轮：生成基础版本
写一个发送邮件的函数

# 第二轮：添加具体需求
好的，现在改进这个函数：
- 支持 HTML 格式邮件
- 添加重试机制（失败后最多重试 3 次）
- 每次重试间隔指数级增长（1s, 2s, 4s）

# 第三轮：添加测试
现在为这个函数写测试，
要 mock 掉实际的邮件发送，覆盖以下场景：
- 发送成功
- 第一次失败、第二次成功
- 三次都失败

技巧七：调试导向提示（Debug-oriented Prompting）

遇到问题时，提供足够的调试上下文：

我的应用出现了以下错误：

错误信息：
TypeError: Cannot read property 'user' of undefined
 at AuthMiddleware.verify (src/middleware/auth.js:23)
 at Layer.handle (node_modules/express/lib/router/layer.js:95)

复现步骤：
1. 用户登录后获取 token
2. 用 token 请求 GET /api/profile
3. 必现此错误

我已经检查过：
- token 格式是正确的（已验证）
- 数据库连接正常
- 其他接口正常工作

请分析 src/middleware/auth.js 找出根本原因。

提示词质量自查清单

在发送指令前，检查以下要素：

本课要点

• 用角色设定获得更专业的分析
• 用约束条件控制修改范围
• 用示例告诉 Codex 期望的格式
• 用分步推理避免盲目行动
• 迭代优化比一次求全更有效

下一步

前往 第 08 课：多 Agent 并行工作流，解锁 Codex 最强大的功能之一。

第 08 课：多 Agent 并行工作流

难度：高级 ｜ 预计阅读时间：25 分钟

什么是多 Agent 并行工作？

Codex 桌面版的核心功能之一：同时运行多个 AI Agent，并行处理不同任务。

想象一个软件团队：

• 前端工程师：同时在写 UI 组件
• 后端工程师：同时在写 API 接口
• 测试工程师：同时在写测试用例
• 文档工程师：同时在写 API 文档

Codex 的多 Agent 功能，让你一个人也能获得"整个团队同时工作"的效率。

实战场景：开发一个用户管理模块

传统（单线程）工作方式

步骤1：设计数据库表（10分钟）
步骤2：写后端 API（20分钟）
步骤3：写前端界面（20分钟）
步骤4：写测试（15分钟）
步骤5：写文档（10分钟）
总计：75分钟，串行完成

多 Agent 并行方式

Agent A：写后端 API（20分钟） ┐
Agent B：写前端界面（20分钟） ├─ 同时进行
Agent C：写测试用例（15分钟） │
Agent D：写 API 文档（10分钟） ┘
总计：~20分钟，并行完成（效率提升 3-4 倍）

如何启动多个 Agent

在桌面版中

1. 点击界面左上角的 "新建 Agent" 按钮
2. 为每个 Agent 指定不同的任务
3. 在左侧 Agent 列表中切换查看各 Agent 的进度

方法二：在 CLI 中开多个终端窗口

# 终端窗口 1 - 后端 Agent
cd /your-project
codex "专注于 src/api/ 目录，实现用户 CRUD 接口"

# 终端窗口 2 - 前端 Agent
cd /your-project
codex "专注于 src/components/User/ 目录，实现用户管理界面"

# 终端窗口 3 - 测试 Agent
cd /your-project
codex "专注于 tests/ 目录，为用户模块编写测试"

多 Agent 的注意事项

防止文件冲突

多个 Agent 同时修改同一个文件会产生冲突。避免方法：

# Agent A 的指令（明确范围）
你只能修改以下文件：
- src/api/users.js
- src/models/User.js
不要触碰其他任何文件。

# Agent B 的指令（明确范围）
你只能修改以下文件：
- src/components/UserList.vue
- src/components/UserForm.vue
- src/store/userStore.js
不要触碰其他任何文件。

定义清晰的接口约定

并行工作前，先定义好各模块的接口：

在启动并行工作前，先帮我定义以下接口约定：
- 后端 API 返回格式
- 前端调用 API 的方式
- 共享的类型定义（TypeScript interfaces）

把这些约定写入 src/types/api.ts，
然后我们才开始并行开发。

最佳多 Agent 任务分配策略

策略一：按模块分配

Agent 1 → 用户模块 (src/user/)
Agent 2 → 商品模块 (src/product/)
Agent 3 → 订单模块 (src/order/)

策略二：按职能分配

Agent 1 → 后端开发 (功能实现)
Agent 2 → 测试编写 (质量保证)
Agent 3 → 文档生成 (文档维护)

策略三：主从协作

主 Agent → 开发核心功能
从 Agent 1 → 实时为主 Agent 的代码编写测试
从 Agent 2 → 实时更新文档

Agent 间的协调

各 Agent 之间通过文件系统"通信"：

# 在 Agent A 的指令中
完成每个功能后，在 .agent-status/backend.md 文件中
更新你的进度，格式如下：
- 已完成：用户列表 API
- 进行中：用户创建 API
- 待开始：用户删除 API

# 在 Agent B 的指令中
检查 .agent-status/backend.md 查看后端进度，
优先为已完成的后端接口写对应的前端组件。

实用技巧：用 Agent 做代码审查

在你写完代码后，启动一个专门做审查的 Agent：

你是一位严格的代码审查员，请审查最近的代码变更：

审查重点：
1. 安全漏洞（SQL 注入、XSS、认证绕过等）
2. 性能问题（N+1 查询、内存泄漏等）
3. 代码质量（可读性、可维护性）
4. 测试覆盖（是否有遗漏的边界情况）

以 Markdown 格式输出审查报告，将问题按严重程度分类：
 严重 / 警告 / 建议

本课要点

• 理解多 Agent 并行工作的优势
• 掌握如何在桌面版启动多个 Agent
• 学会为每个 Agent 划定清晰的工作边界
• 了解 Agent 间通过文件系统协调的方式

下一步

前往 第 09 课：调试与修复 Bug 的最佳实践。

第 09 课：调试与修复 Bug 的最佳实践

难度：高级 ｜ 预计阅读时间：25 分钟

让 Codex 成为你最强的调试伙伴

调试是开发中最耗时的工作之一。Codex 不仅能帮你写代码，更能帮你快速定位和修复 Bug。本课教你如何最大化利用 Codex 的调试能力。

调试工作流：五步法

第一步：提供完整的错误上下文

给 Codex 的信息越完整，诊断越准确。

我的应用出现了一个 Bug，以下是完整信息：

【错误信息】
Error: connect ECONNREFUSED 127.0.0.1:5432
 at TCPConnectWrap.afterConnect [as oncomplete] (net.js:1141:16)

【发生时间】
启动应用时立即出现，不是偶发性的

【环境信息】
- Node.js: v18.17.0
- 系统：macOS 14
- 数据库：PostgreSQL 15

【最近的变更】
昨天把数据库连接配置从硬编码改成了环境变量

【已尝试过的方法】
- 重启应用：无效
- 检查数据库是否运行：postgres 服务正常运行（端口 5432 可 telnet 通）

请分析可能的原因。

第二步：让 Codex 系统性地排查

请按以下顺序系统排查这个连接错误：
1. 检查 src/config/database.js 的配置读取逻辑
2. 检查 .env 文件的格式是否正确
3. 检查连接字符串的拼接方式
4. 检查是否有连接池配置问题
每个检查点给出结论，找到问题后再提修复方案。

第三步：理解根本原因，不只是症状

你找到了问题（DB_PORT 环境变量没有被转换成数字类型），
但我想理解：
1. 为什么 JavaScript 在这里需要明确的数字类型？
2. 这类问题还可能出现在哪些地方？
3. 有没有一劳永逸的解决方案？

第四步：修复并验证

好的，请修复这个问题：
1. 在配置读取处添加类型转换
2. 添加配置验证（如果关键配置缺失，启动时立即报错并给出清晰提示）
3. 修复后，帮我运行相关测试验证没有破坏其他功能

第五步：预防类似问题

这个 Bug 暴露了我们的配置管理存在问题。
请帮我：
1. 在整个项目中扫描类似的配置读取问题
2. 创建一个统一的配置验证模块
3. 更新 AGENTS.md，加入"配置读取必须进行类型验证"的规范

常见 Bug 类型的调试指令模板

类型一：性能问题

接口 GET /api/products/search 响应时间超过 3 秒。

请帮我：
1. 在 src/api/products.js 中添加计时日志，定位耗时的具体步骤
2. 分析数据库查询（可以打印出执行的 SQL 语句）
3. 检查是否有 N+1 查询问题
4. 提出优化方案（优先不改变数据结构的方案）

类型二：并发/竞态条件

我们的订单系统偶发出现重复订单，特别是在高并发时。

请分析：
1. src/services/OrderService.js 中的 createOrder 方法
2. 查找可能的竞态条件（race condition）
3. 检查数据库事务的使用是否正确
4. 提出加锁或幂等性的解决方案

类型三：内存泄漏

应用运行一段时间后内存会持续增长，最终崩溃。

请帮我：
1. 在代码中查找常见的内存泄漏模式：
 - 未清理的事件监听器
 - 未关闭的数据库连接
 - 无限增长的缓存
 - 闭包持有大对象的引用
2. 特别检查 src/services/ 和 src/middleware/ 目录
3. 给出修复方案和验证内存使用的方法

类型四：第三方 API 问题

调用支付宝 API 时偶发失败，错误码是 40004。

请帮我：
1. 查一下错误码 40004 的含义（可以查看 src/docs/ 或告诉我去哪里查）
2. 检查 src/services/AlipayService.js 的请求参数构造
3. 添加详细的请求/响应日志，方便下次排查
4. 增加重试机制（只对可重试的错误类型重试）

预防性调试：主动发现问题

不要等 Bug 出现才去处理，让 Codex 帮你提前发现：

帮我对整个项目做一次"预防性代码审查"，重点检查：

1. 【未处理的 Promise 拒绝】
 找出所有没有 catch 的 async/await 调用

2. 【空值引用风险】
 找出所有直接访问可能为 null 的属性，没有做空值检查的地方

3. 【错误吞噬】
 找出 catch 块里只有 console.log 没有重新抛出或处理的地方

4. 【敏感信息泄露】
 找出可能把密码、token、密钥打印到日志的地方

输出为一个报告，按严重程度排序。

调试效率对比

本课要点

• 调试时给 Codex 提供完整上下文（错误信息 + 环境 + 已尝试的方法）
• 要求 Codex 系统性排查，而不是直接猜测
• 理解根本原因，不只是修复症状
• 修复后验证，并预防类似问题
• 用预防性代码审查主动发现潜在 Bug

下一步

前往 第 10 课：Git 集成与安全回滚策略，建立完整的代码安全保障体系。

第 10 课：Git 集成与安全回滚策略

难度：专家 ｜ 预计阅读时间：20 分钟

为什么 Git + Codex 是黄金组合？

Codex 很强大，但 AI 也会犯错。当 Codex 做出了不符合预期的改动时，你需要一个安全网——Git 就是这个安全网。

核心原则：

在让 Codex 做任何大规模修改前，先提交一个 Git 检查点（Checkpoint）。

标准工作流：Codex + Git

每次工作前的仪式

# 1. 确认当前状态干净
git status

# 2. 如果有未提交的改动，先提交
git add -A
git commit -m "[checkpoint] 开始使用 Codex 前的存档"

# 3. 启动 Codex
codex app

让 Codex 帮你管理 Git

Codex 可以直接帮你执行 Git 操作：

帮我做一个 Git 提交，提交信息要符合 Conventional Commits 规范，
自动总结本次修改的内容。

查看 git diff，总结我做了哪些改动，
然后帮我写一个清晰的提交信息并提交。

出问题时的回滚策略

情况一：刚刚操作出错，还没提交

# 撤销所有未提交的修改（谨慎！不可恢复）
git restore .

# 或者只撤销某个文件
git restore src/api/users.js

或者告诉 Codex：

刚才的修改出问题了，请撤销所有未提交的变更，
恢复到最近一次 git commit 的状态。

情况二：刚提交但发现有问题

# 撤销最近一次提交，但保留文件改动（可以重新修改后再提交）
git reset --soft HEAD~1

# 完全撤销最近一次提交（包括文件改动）
git reset --hard HEAD~1

情况三：改动已经很多，想回到某个历史版本

# 查看提交历史，找到你想回到的版本
git log --oneline -10

# 回到指定版本（替换 abc1234 为目标 commit 的哈希值）
git reset --hard abc1234

分支策略：用分支隔离风险

对于大型修改，建议用独立分支：

# 在开始大型重构前，创建新分支
git checkout -b feature/codex-refactor-auth

# 让 Codex 在这个分支上工作
# ... Codex 做各种修改 ...

# 如果满意，合并回主分支
git checkout main
git merge feature/codex-refactor-auth

# 如果不满意，直接删除这个分支（干净回滚）
git checkout main
git branch -D feature/codex-refactor-auth

让 Codex 帮你管理分支：

我要做一个大规模重构，帮我：
1. 创建一个新分支叫 refactor/database-layer
2. 在这个分支上进行所有数据库层的重构
3. 重构完成后，帮我生成一个 PR 描述

推荐的 Git 提交习惯

Conventional Commits 格式

<类型>(<范围>): <描述>

类型：
feat - 新功能
fix - Bug 修复
refactor - 重构（不影响功能）
test - 添加/修改测试
docs - 文档更新
chore - 构建/工具相关
perf - 性能优化

让 Codex 自动生成提交信息

分析我的代码改动，按照 Conventional Commits 规范
生成一个准确的提交信息，然后执行 git commit。

打 Tag：重要里程碑的快照

在重要版本发布前打 Tag，方便随时回到里程碑状态：

# 打一个带注释的 Tag
git tag -a v1.2.0 -m "用户管理模块完成"

# 查看所有 Tag
git tag

# 回到某个 Tag 的状态
git checkout v1.2.0

# 让 Codex 帮你管理版本号
帮我更新项目版本号到 1.2.0，
更新 package.json 和 CHANGELOG.md，
然后打一个 git tag v1.2.0

用 Git 追踪 Codex 的所有操作

养成好习惯：每次 Codex 完成一个任务就提交，形成详细的历史记录：

任务完成后帮我做以下操作：
1. 运行 git diff 展示所有改动
2. 如果改动符合预期，执行 git add -A 和 git commit
3. 提交信息格式：[codex] feat: 实现用户头像上传功能
4. 显示最终的 git log 确认提交成功

紧急情况处理手册

本课要点

• 每次让 Codex 大规模修改前，先做 Git Checkpoint
• 大型修改用独立分支，不满意直接删分支
• 让 Codex 帮你生成规范的提交信息
• 重要里程碑打 Tag，方便随时回溯
• 出问题时知道用哪个 Git 命令回滚