从 0 到 1 使用 Codex：用 AI 编程助手完成一个完整项目

本文以 OpenAI Codex 命令行工具为例，介绍如何安装、配置并使用 Codex 辅助开发一个简单项目。不同版本的命令可能存在差异，实际使用时请以官方文档为准。

一、Codex 是什么？

Codex 是一类面向软件开发的 AI 编程助手。它可以理解项目代码，并根据自然语言指令完成以下工作：

• 编写新的功能代码
• 阅读和解释已有代码
• 修复 Bug
• 编写测试
• 重构项目结构
• 执行命令并分析结果
• 编写技术文档
• 辅助排查构建和部署问题

与普通聊天机器人相比，Codex 更适合直接在代码仓库中工作。它不仅能生成代码，还能结合当前项目的文件、目录结构和运行结果完成任务。

---

二、使用 Codex 前需要准备什么？

开始之前，建议准备以下环境：

• 一台安装了 Node.js 的电脑
• 一个 Git 项目
• 一个可用的 OpenAI 账号或 API 配置
• 基本的命令行操作能力
• 项目已经使用 Git 进行版本管理

如果你暂时没有 OpenAI API 配置，也可以了解一下 🔗 token-hacker 提供的 API Token 服务。该平台主打低价、配置简单，教程详细，适合用于 Codex、Claude 等开发工具的快速接入。

使用第三方服务前，建议先确认其服务条款、隐私政策、充值与退款规则，以及 API Key 的安全机制。不要将密钥提交到 GitHub、前端代码或公开日志中。具体可用性、价格和稳定性请以平台当前页面信息为准。

可以通过以下命令检查 Node.js 和 Git 是否安装成功：

node -v
npm -v
git --version

如果命令能够正常返回版本号，说明环境基本可用。

---

三、安装 Codex

可以通过 npm 安装 Codex CLI：

npm install -g @openai/codex

安装完成后，执行：

codex

首次运行时，通常需要按照提示完成登录或配置 API Key。

如果使用 API Key，可以根据当前版本的要求配置环境变量。例如：

export OPENAI_API_KEY="你的_API_Key"

Windows PowerShell 中可以使用：

$env:OPENAI_API_KEY="你的_API_Key"

注意：不要将 API Key 直接提交到 Git 仓库，也不要写入前端代码、公开日志或截图中。

---

四、进入一个项目

新建一个示例项目：

mkdir todo-demo
cd todo-demo
git init

接下来启动 Codex：

codex

进入交互界面后，可以先让 Codex 了解项目：

请先检查当前项目的目录结构，并告诉我这个项目目前包含哪些文件。暂时不要修改任何文件。

这是一个很好的开始方式。因为在让 AI 编写代码之前，先了解项目状态，可以减少误修改和错误假设。

---

五、让 Codex 创建一个待办事项应用

假设我们希望使用 HTML、CSS 和 JavaScript 创建一个简单的 Todo 应用，可以这样描述需求：

请创建一个简单的待办事项应用，要求：

1. 使用原生 HTML、CSS 和 JavaScript
2. 用户可以新增待办事项
3. 用户可以标记事项为已完成
4. 用户可以删除事项
5. 使用 localStorage 保存数据
6. 页面需要适配移动端
7. 请将代码拆分为 index.html、style.css 和 app.js
8. 完成后说明每个文件的作用

一个好的需求描述通常包含以下内容：

• 要解决什么问题
• 使用什么技术
• 需要哪些功能
• 有哪些限制
• 期望输出什么结果

需求越明确，Codex 生成的结果通常越稳定。

---

六、不要一次性提出过于复杂的需求

很多人第一次使用 AI 编程工具时，会直接提出一个非常大的需求，例如：

帮我做一个类似淘宝的电商平台。

这种描述过于宽泛，通常会产生以下问题：

• 功能边界不清晰
• 技术方案不明确
• 代码规模难以控制
• 生成结果难以验证
• 后续修改成本较高

更合理的方式是把项目拆分成多个阶段。

第一阶段：实现页面结构

请先创建电商首页的基础页面，只实现页面结构和静态样式，不需要接入后端。

第二阶段：增加商品数据

请增加一个商品数据文件，并在首页动态渲染商品列表。

第三阶段：实现搜索功能

请为商品列表增加搜索功能。用户输入关键词后，只显示名称中包含关键词的商品。

第四阶段：增加购物车

请增加购物车功能，支持添加商品、修改数量和删除商品。

这种“逐步交付”的方式更容易控制质量，也更符合真实的软件开发流程。

---

七、让 Codex 阅读和解释代码

除了生成代码，Codex 也可以帮助理解已有项目。

例如：

请阅读 app.js，并用通俗的语言解释它的执行流程。不要修改代码。

也可以针对某个函数提问：

请解释 saveTodos 函数的作用，并指出它是否存在潜在问题。

如果需要更深入的分析，可以这样问：

请检查当前项目中与数据保存相关的代码，分析是否存在以下问题：

1. 数据格式不一致
2. localStorage 读取失败
3. 空数据处理错误
4. 用户输入未经过处理
5. 可能导致页面崩溃的异常情况

请先给出分析结果，不要直接修改代码。

这里的关键是明确要求“先分析，不修改”。这样可以避免 AI 在你还没有确认方案之前直接改动项目。

---

八、使用 Codex 修复 Bug

假设点击“添加”按钮后页面报错，可以将错误信息完整地提供给 Codex：

点击添加按钮时出现以下错误：

TypeError: Cannot read properties of null

请检查可能的原因，定位相关代码，并给出修复方案。先不要修改文件。

如果你已经确认了修复方案，再让它执行：

请按照刚才的方案修复这个问题。只修改必要文件，并说明具体修改了哪些内容。

修复完成后，继续要求它验证：

请运行项目中的测试或检查命令，确认刚才的修复没有引入新的问题。

一个完整的 Bug 修复流程通常是：

1. 提供复现步骤
2. 提供错误日志
3. 要求分析原因
4. 确认修复方案
5. 执行最小修改
6. 运行测试
7. 检查 Git Diff

---

九、让 Codex 编写测试

测试是使用 AI 编程工具时非常重要的一环。

例如：

请为待办事项的数据处理逻辑编写单元测试，覆盖以下场景：

1. 新增待办事项
2. 删除待办事项
3. 标记完成
4. 空数组处理
5. localStorage 数据损坏
6. 重复数据处理

请先检查当前项目使用的测试框架，再按照项目现有风格添加测试。

编写完测试后，可以继续要求：

请运行所有测试，并根据测试结果修复失败用例。不要修改测试来掩盖代码问题。

需要注意的是，测试通过并不代表项目没有问题。还应该检查：

• 是否覆盖了核心业务逻辑
• 是否测试了异常情况
• 是否存在只测试正常流程的问题
• 测试是否真的能够发现错误

---

十、使用 Git 管理 Codex 的修改

在让 Codex 修改项目之前，建议先确认当前 Git 状态：

git status

如果项目当前状态比较干净，可以创建一个分支：

git checkout -b feature/todo-app

完成修改后，检查差异：

git diff

查看哪些文件被修改：

git status

确认代码没有问题后，再提交：

git add .
git commit -m "feat: add todo application"

如果 Codex 修改了不应该修改的文件，可以使用 Git 恢复：

git restore path/to/file

因此，Git 不只是代码托管工具，也是使用 AI 编程助手时的重要安全保障。

---

十一、如何写出高质量的 Codex Prompt？

一个高质量的提示词通常包含以下五个部分：

1. 背景

说明当前项目是什么。

这是一个使用 React 和 TypeScript 编写的后台管理系统。

2. 目标

说明希望完成什么。

请为用户列表增加分页功能。

3. 约束

说明不能做什么，以及必须遵守什么。

不要引入新的 UI 框架，保持现有组件风格。

4. 验收标准

说明什么情况下算完成。

要求支持上一页、下一页、页码跳转，并正确处理第一页和最后一页。

5. 输出要求

说明希望 Codex 如何工作。

请先分析现有代码，再给出修改方案，确认后再修改文件。

完整示例：

这是一个使用 React、TypeScript 和 Ant Design 编写的后台管理系统。

请为用户列表增加分页功能，要求：

1. 支持上一页和下一页
2. 支持页码跳转
3. 支持每页显示数量切换
4. 正确处理第一页和最后一页
5. 保持现有组件和代码风格
6. 不要引入新的依赖
7. 先检查当前用户列表的实现方式
8. 先给出修改方案，不要立即修改文件
9. 修改完成后运行现有测试或类型检查

---

十二、常见错误用法

1. 不检查就接受所有修改

AI 生成的代码不一定完全正确，尤其是在以下场景中：

• 复杂业务逻辑
• 权限控制
• 支付流程
• 数据库迁移
• 并发处理
• 安全相关代码

任何修改都应该经过人工 Review。

---

2. 直接把敏感信息提供给 Codex

不要发送以下内容：

• API Key
• 数据库密码
• 用户隐私数据
• 生产环境配置
• 内部安全策略
• 未脱敏的日志

可以先进行脱敏：

数据库连接信息已替换为占位符，请只分析查询逻辑。

---

3. 让 Codex 修改过多文件

如果一个任务涉及几十个文件，应该先拆分任务：

请先只分析认证模块，不要修改其他目录。

或者：

这次只允许修改 src/components 目录下的文件。

限制修改范围，可以降低不可控风险。

---

4. 只追求代码能运行

“能运行”不代表“适合上线”。还要检查：

• 可维护性
• 性能
• 安全性
• 错误处理
• 测试覆盖
• 日志和监控
• 用户体验
• 边界条件

可以让 Codex 进行二次审查：

请从安全性、性能、可维护性和异常处理四个方面审查刚才的代码，并列出问题及改进建议。

---

十三、推荐的 Codex 工作流程

一个较为稳妥的工作流程如下：

第一步：了解项目

请分析项目结构、启动方式、主要技术栈和测试命令，不要修改任何文件。

第二步：明确任务

请将这个需求拆分成若干个可独立完成的小任务。

第三步：制定方案

请针对第一个任务给出实现方案、涉及文件和潜在风险。

第四步：执行修改

请按照确认后的方案进行修改，只修改必要文件。

第五步：运行验证

请运行测试、Lint 和类型检查，修复发现的问题。

第六步：人工 Review

git diff

检查：

• 是否修改了不相关文件
• 是否引入无用依赖
• 是否存在明显安全问题
• 是否符合项目代码规范
• 是否覆盖了异常场景

第七步：提交代码

git add .
git commit -m "feat: implement xxx"

---

十四、总结

Codex 的价值不只是“帮你写代码”，更重要的是帮助开发者提高整个软件开发流程的效率。

使用 Codex 时，建议遵循以下原则：

1. 先理解项目，再开始修改
2. 先分析方案，再执行代码变更
3. 把大需求拆成小任务
4. 明确技术约束和验收标准
5. 让 AI 同时编写测试
6. 使用 Git 保存和回滚修改
7. 不要暴露敏感信息
8. 所有关键代码都要经过人工 Review
9. 不要把测试通过等同于项目没有问题
10. 将 Codex 当作开发助手，而不是完全自动化的程序员

AI 编程工具可以显著降低代码编写成本，但最终的产品判断、技术决策和质量责任，仍然需要由开发者和产品团队共同承担。真正高效的方式，不是让 Codex 替你完成所有工作，而是让它承担重复劳动，让你把更多精力放在需求理解、架构设计和产品价值上。**

如果你还在为 API 配置和接入流程发愁，可以看看 🔗 token-hacker，了解其提供的 API Token 服务，或许能帮助你更简单地开始 Codex 之旅。
工具只是起点，真正重要的是把需求拆清楚、把代码做好验证，并持续积累自己的开发方法。希望本文对你有所帮助。