1. 引言：为什么你需要一份 Codex 实战教程

2025 年，OpenAI 正式发布了 Codex，一个专为代码任务打造的智能体。它不再只是一个「自动补全代码」的助手，而是一个能理解项目上下文、自主规划任务、调用工具、执行命令并完成端到端开发任务的 AI 工程师。

很多开发者已经听说过 Codex，但真正把它用起来、用好的并不多。原因很简单：网上碎片化的介绍很多，但缺少一份从零到一、覆盖真实开发场景的系统教程。

这份教程会带你从安装配置开始，逐步深入到项目实战、工具调用、工作流定制和团队协作。无论你是刚接触 AI 编程的新手，还是已经在用其他 AI 编程工具的老手，都能在这里找到适合自己的内容。

2. Codex 是什么

2.1 从代码补全到 AI 工程师

传统 AI 编程工具的核心能力是「补全」：你写一半，它帮你补另一半。而 Codex 的核心能力是「执行」：你给它一个任务，它自己规划步骤、读写文件、运行命令、查看结果，直到任务完成。

2.2 Codex 的核心能力

• 代码理解：读取整个代码仓库，理解项目结构和业务逻辑，而不只是看当前文件。
• 任务规划：把一个复杂需求拆解成多个可执行的子任务，并合理安排执行顺序。
• 工具调用：可以调用命令行工具、读写文件、运行测试、执行 Git 操作等。
• 自主迭代：运行代码后查看结果，发现问题自动修复，直到通过验证。

2.3 Codex 与 ChatGPT、Claude Code 的区别

对比维度	Codex	ChatGPT	Claude Code
定位	代码智能体	通用对话助手	代码智能体
代码仓库理解	深度集成	较弱	深度集成
工具调用	丰富	有限	丰富
自主执行任务	强	弱	强
适用场景	开发任务	问答/写作	开发任务

3. 环境准备与安装

3.1 前置要求

在开始之前，请确保你的开发环境满足以下条件：

• 操作系统：macOS、Linux 或 Windows（WSL 推荐）
• 已安装 Node.js 18+ 或 Python 3.9+
• 已安装 Git
• 拥有 OpenAI API 账号或 ChatGPT 订阅

3.2 安装 Codex CLI

Codex CLI 是官方提供的命令行工具，安装非常简单：

npm install -g @openai/codex

安装完成后，验证是否成功：

codex --version

3.3 配置认证

首次运行 Codex 时，需要配置 API 密钥：

codex login

按照提示完成认证流程。如果你使用的是 API Key，也可以直接设置环境变量：

export OPENAI_API_KEY="sk-你的密钥"

3.4 验证安装

创建一个测试目录，运行 Codex 试试：

mkdir codex-test && cd codex-test
codex "创建一个 Python 的 Hello World 程序并运行它"

如果一切正常，你会看到 Codex 自动创建文件、运行程序并输出结果。

4. Codex 基础用法

4.1 交互式对话模式

在项目目录下直接运行 codex，进入交互式对话模式：

codex

此时你可以像和同事聊天一样描述需求：

> 帮我写一个函数，计算斐波那契数列的第 n 项

Codex 会分析你的项目结构，编写代码，并询问你是否要应用修改。

4.2 单次任务模式

如果你只想执行一次任务，可以直接在命令行中传入任务描述：

codex "给项目添加一个 README.md 文件，介绍项目用途和运行方式"

4.3 指定文件范围

当项目较大时，可以限制 Codex 只关注某些文件：

codex "修复 src/utils/date.ts 中的时区问题" --files src/utils/date.ts

4.4 常用参数

参数	说明	示例
--model	指定模型	--model gpt-5-codex
--files	限定文件范围	--files src/**/*.ts
--sandbox	沙箱模式	--sandbox danger-full-access
--json	JSON 输出	--json
--verbose	详细日志	--verbose

5. 实战案例一：从零搭建一个 Web 应用

5.1 任务描述

假设我们要用 Codex 从零搭建一个「待办事项」Web 应用，技术栈选择 Node.js + Express + SQLite。

5.2 初始化项目

mkdir todo-app && cd todo-app
codex "初始化一个 Node.js 项目，使用 Express 框架，数据库用 SQLite，创建 package.json 和基础目录结构"

Codex 会自动完成以下工作：

• 创建 package.json 并安装依赖
• 创建 src/ 目录结构
• 生成入口文件 src/index.js
• 初始化 Git 仓库

5.3 实现核心功能

codex "实现待办事项的增删改查 API：支持创建、查询、更新、删除待办事项，数据存储使用 SQLite，提供 RESTful 接口"

Codex 会创建数据库模型、路由文件和控制器，并自动安装 better-sqlite3 等依赖。

5.4 添加前端页面

codex "创建一个简单的前端页面，使用原生 HTML/CSS/JavaScript，实现待办事项的展示和添加功能，通过 fetch 调用后端 API"

5.5 运行与测试

codex "启动应用并测试所有 API 接口，确保功能正常，如果有问题请修复"

Codex 会启动服务、调用接口、检查返回结果，并自动修复发现的问题。

5.6 完整项目结构

todo-app/
├── package.json
├── src/
│   ├── index.js          # 入口文件
│   ├── db.js             # 数据库连接
│   ├── routes/
│   │   └── todos.js      # 待办事项路由
│   └── public/
│       ├── index.html    # 前端页面
│       ├── style.css     # 样式
│       └── app.js        # 前端逻辑
└── data/
    └── todos.db          # SQLite 数据库

6. 实战案例二：重构遗留项目

6.1 场景描述

接手一个老项目，代码混乱、没有测试、技术栈过时。用 Codex 帮你完成重构。

6.2 分析项目现状

codex "分析当前项目的代码结构，找出存在的问题：包括代码重复、过时 API、潜在 Bug，输出一份分析报告"

6.3 制定重构计划

codex "根据分析结果，制定一个分阶段的重构计划，每个阶段都要有明确的目标和验证方式"

6.4 执行重构

codex "执行第一阶段重构：将项目中所有回调函数改写为 async/await 风格，确保功能不变"

6.5 补充测试

codex "为项目核心模块编写单元测试，使用 Jest 框架，覆盖率达到 80% 以上"

6.6 重构注意事项

• 小步提交：让 Codex 每次只改一个模块，改完立即运行测试验证。
• 保留行为：重构的目标是改善代码质量，而不是改变功能行为。
• 善用 Git：每次重构前创建分支，方便随时回退。

7. 实战案例三：编写自动化测试

7.1 为什么让 Codex 写测试

测试代码往往重复性高、模板化强，非常适合 Codex 自动生成。但要注意：AI 生成的测试需要人工审核，确保测试断言合理、覆盖了关键路径。

7.2 生成单元测试

codex "为 src/utils/string.ts 中的每个函数编写单元测试，覆盖正常输入、边界情况和异常输入"

7.3 生成集成测试

codex "为用户注册接口编写集成测试，覆盖注册成功、邮箱已存在、参数不合法三种场景"

7.4 测试驱动开发（TDD）

Codex 也支持 TDD 工作流：

codex "先为 calculateDiscount 函数编写测试用例，然后实现函数让测试通过"

7.5 测试代码审核要点

• 断言是否真正验证了预期行为，而不是「为了测试而测试」
• 是否覆盖了边界条件和异常路径
• 测试之间是否相互独立、可重复执行
• 是否有不必要的 Mock，导致测试失真

8. 高级技巧与最佳实践

8.1 编写高质量的任务描述

Codex 的输出质量很大程度上取决于你的输入质量。好的任务描述应该包含：

• 明确的目标：要做什么，达到什么效果
• 技术约束：使用什么技术栈、遵循什么规范
• 验收标准：怎样算完成，如何验证
• 上下文信息：相关文件、模块、历史决策

反面示例：

帮我优化一下代码

正面示例：

优化 src/utils/date.ts 中的 formatDate 函数：
1. 当前实现存在时区问题，使用 UTC 时间导致本地时间偏移
2. 请改用 dayjs 库处理时区
3. 保持函数签名不变，确保现有调用方不受影响
4. 补充单元测试验证不同时区下的输出

8.2 善用 AGENTS.md 项目说明文件

在项目根目录创建 AGENTS.md 文件，告诉 Codex 项目的关键信息：

# 项目说明

## 技术栈
- 前端：React 18 + TypeScript
- 后端：Node.js + Express
- 数据库：PostgreSQL

## 代码规范
- 使用 ESLint + Prettier
- 组件使用函数式写法 + Hooks
- 禁止使用 any 类型

## 常用命令
- 开发：npm run dev
- 测试：npm test
- 构建：npm run build

8.3 迭代式开发

不要期望一次对话就完成所有工作。推荐的工作流是：

8.4 善用沙箱模式

Codex 支持沙箱模式，限制其对系统的访问权限：

# 只读模式，不允许修改文件
codex "分析项目结构" --sandbox read-only

# 工作区模式，只允许修改当前目录
codex "重构代码" --sandbox workspace-write

# 完全访问模式，谨慎使用
codex "部署到服务器" --sandbox danger-full-access

8.5 常见陷阱与规避

陷阱	表现	规避方法
任务描述模糊	输出偏离预期	写清楚目标和约束
上下文不足	修改了错误的文件	用 --files 限定范围
过度自信	声称完成但实际有 Bug	要求运行测试验证
无限循环	反复修改同一问题	设置明确的完成标准

9. Codex 与团队协作

9.1 代码审查

Codex 可以作为代码审查助手：

codex "审查 src/auth/login.ts 的代码，关注安全性问题：SQL 注入、XSS、敏感信息泄露"

9.2 生成提交信息

codex "根据当前 Git 暂存区的改动，生成一个符合 Conventional Commits 规范的提交信息"

9.3 编写技术文档

codex "为 src/api/ 目录下的所有接口编写 API 文档，包含请求参数、响应格式、错误码说明"

9.4 新人 onboarding

codex "为项目编写一份新人上手文档，包含环境搭建、项目结构说明、常用命令和开发流程"

10. 常见问题与排查

10.1 Codex 运行缓慢

• 检查网络连接是否稳定
• 减少 --files 范围，缩小上下文
• 使用更快的模型

10.2 Codex 修改了不该改的文件

• 使用 --files 明确限定范围
• 在 AGENTS.md 中声明哪些目录不允许修改
• 修改前先让 Codex 输出计划，确认后再执行

10.3 Codex 生成的代码有 Bug

• 要求 Codex 运行测试并修复
• 提供具体的错误信息作为上下文
• 缩小任务范围，分步执行

10.4 认证失败

• 检查 API Key 是否有效
• 确认账号是否有 Codex 访问权限
• 重新执行 codex login

11. 总结与下一步

11.1 核心要点回顾

• Codex 是一个能自主规划、执行、验证的 AI 代码智能体
• 高质量的任务描述是获得高质量输出的关键
• 善用 AGENTS.md、沙箱模式和 --files 参数控制行为
• 人工审查和测试验证永远不可替代
• 迭代式开发是使用 Codex 的最佳实践

11.2 学习资源

• OpenAI 官方 Codex 文档
• GitHub 上的 Codex 示例项目
• 社区分享的 Codex 工作流

11.3 下一步行动

1. 安装 Codex CLI 并完成认证
2. 在一个练习项目上跑通第一个任务
3. 为你的主力项目编写 AGENTS.md
4. 尝试用 Codex 完成一次完整的开发任务

AI 编程的时代已经到来，Codex 是这场变革的前沿工具。掌握它，你就能把更多精力放在架构设计、业务理解和创新思考上，把重复性工作交给 AI。现在就打开终端，开始你的第一个 Codex 任务吧！