Codex 实战使用教程：从安装到独立完成一个真实项目开发

本文面向前端、Java 后端、Python 后端以及 AI Agent 开发者。不讲太多概念，直接从安装开始，通过一个真实项目完整演示 Codex 的使用方式。

核心目标：学完这篇文章，你至少应该能够做到：安装 Codex、在真实项目中启动 Codex、让 Codex 理解现有代码、让 Codex 分析项目问题、让 Codex 修改代码、让 Codex 自动运行测试、让 Codex 排查 Bug、让 Codex 做代码 Review、使用 MCP 扩展 Codex 能力、使用项目级规则约束 Codex，并形成一套真正适合日常开发的 Codex 工作流。

一、先理解：Codex 到底是什么？

如果以前你使用 ChatGPT 的方式是：复制代码 → 粘贴到 ChatGPT → 描述问题 → 复制修改后的代码 → 粘贴回项目 → 运行 → 报错 → 再复制错误 → 重新问。那么 Codex 最大的变化就是：AI 不再只是“看代码告诉你怎么改”，而是直接进入你的开发环境，理解项目、修改文件、执行命令、运行测试，然后根据结果继续修复。

所以真正高效的使用方式不是“帮我写一个函数”，而是：“理解这个项目 → 分析问题 → 制定方案 → 修改代码 → 运行测试 → 根据测试结果继续修复”。这才是 Agent Coding 的核心工作方式。

二、Codex 可以做什么？

日常开发中，可以把 Codex 理解成一个能够进入项目工作的 AI 开发助手：理解项目 → 分析代码 → 定位问题 → 修改代码 → 运行命令 → 运行测试 → 查看错误 → 继续修改 → 最终验证。

实际开发中，可以让 Codex 帮你完成：

1. 新功能开发

例如：给 FastAPI 项目增加一个用户注册接口。要求：

1. 使用 Pydantic 校验参数

2. 使用 PostgreSQL

3. 密码不能明文保存

4. 增加单元测试

5. 不影响现有接口

2. Bug 排查

例如：这个接口偶尔返回 500。请你先不要修改代码：

1. 分析调用链

2. 找出可能的问题

3. 给出你的判断

4. 告诉我需要修改哪些文件 确认后再修改。

3. 重构

例如：分析这个项目的 service 层。找出：

1. 重复代码

2. 不合理的依赖

3. 可以抽取的公共逻辑

4. 潜在的异常处理问题 先给我重构方案，不要修改代码。

4. 测试

例如：检查这个项目目前有哪些测试。运行测试。如果失败：

1. 分析失败原因

2. 修复代码

3. 重新运行测试

4. 直到测试通过

5. Code Review

例如：Review 当前分支相对于 main 的所有代码变化。重点检查：

1. Bug

2. 类型问题

3. 异常处理

4. 安全问题

5. 性能问题

6. 是否存在破坏现有行为的修改 不要直接修改代码，只输出 Review 结果。

三、安装 Codex

3.1 使用 Codex CLI

Codex CLI 可以直接在终端中运行。 官方文档：OpenAI Codex 官方文档

如果你的环境支持 npm，可以使用：

npm install -g @openai/codex

安装完成以后输入：

codex

如果能够进入 Codex 交互界面，说明安装成功。

四、第一次启动 Codex

进入你的项目目录，例如：

cd ~/Desktop/my-project

然后输入：

codex

第一次使用时，根据终端提示完成登录。

五、先不要急着让 Codex 写代码

这是很多人第一次使用 Codex 最容易犯的错误。一进项目就“帮我增加一个登录功能”，这样虽然也能工作，但效率通常不高。正确方式是先让 Codex 理解项目。

第一句话可以这样说：

请先完整分析当前项目，不要修改任何代码。

重点分析：

1. 项目的技术栈

2. 项目目录结构

3. 前后端架构

4. 核心业务模块

5. 数据库

6. API

7. 测试体系

8. 启动方式

9. 构建方式

10. 当前项目可能存在的问题

最后给我输出一份项目架构说明。

这一步非常重要。

六、为什么第一步一定要“理解项目”？

因为 Codex 面对的不是一个孤立代码文件。真实项目一般包含 frontend、backend、database、config、scripts、tests、Dockerfile、CI/CD，甚至还有 MCP、Agent、RAG、Redis、PostgreSQL、Vector DB、第三方 API。

如果你直接让 AI 修改代码，它可能只关注你提到的那个文件。但是先理解项目之后，它才能知道：这个文件 → 被谁调用 → 调用了什么 Service → Service 调用了什么 Repository → Repository 操作什么数据库 → 最后有哪些测试。这才是工程开发。

七、第一次实战：让 Codex 分析项目

假设我们现在有一个 Python + FastAPI 项目：

启动 Codex：

cd ai-agent-demo codex输入：

请先阅读当前项目，不要修改任何文件。

请分析：

1. 项目的整体架构

2. FastAPI 的启动入口

3. API 路由

4. Service 层

5. Agent 层

6. 数据库相关代码

7. 测试代码

8. Docker 配置

9. 项目启动方式

最后用“项目架构图 + 目录说明 + 核心调用链”的方式告诉我。

八、第二次实战：让 Codex 开发一个功能

假设现在我们要增加：订单查询 Agent。不要直接说“帮我写一个订单 Agent。”推荐这样写：

我需要给当前项目增加一个“订单查询 Agent”。

业务要求：

1. 用户可以查询订单状态

2. 用户可以查询物流信息

3. 用户可以查询订单详情

4. Agent 需要根据用户问题决定调用哪个工具

5. 不要破坏现有 API

6. 增加对应测试

请先：

1. 分析现有代码

2. 找到最适合扩展的位置

3. 给出实现方案

4. 列出需要修改的文件

5. 说明每个文件修改什么

暂时不要修改代码。

这一步让 Codex 先进入 Plan，而不是直接 Coding。

九、确认方案以后，再让 Codex 开始修改

如果方案没有问题，可以继续：

按照刚才的方案开始实现。

要求：

1. 尽量复用现有代码

2. 不要大范围重构

3. 保持现有代码风格

4. 增加必要的类型定义

5. 增加测试

6. 修改完成后运行测试

完成以后告诉我：

1. 修改了哪些文件

2. 每个文件做了什么

3. 测试结果

4. 还有没有风险

这时候 Codex 才开始真正修改项目。

十、Codex 最重要的能力：执行命令

传统 AI 最大的问题之一是：AI 觉得代码应该这样修改，但是它不知道修改以后能不能运行？

Codex 可以进入项目环境执行命令（例如 npm install、npm test、pytest、pnpm build 甚至 docker compose up -d）。

因此完整开发链路变成：需求 → Codex 分析 → 修改代码 → 执行命令 → 发现错误 → 分析错误 → 修改代码 → 再次执行 → 测试通过。这就是 Agent Coding。

十一、实战：让 Codex 自动修复 Bug

假设运行 pytest 出现：

FAILED tests/test_order.pyAssertionError:expected "shipped"but got "pending"

不要自己分析半天，可以直接告诉 Codex：

刚才测试失败了。请你排查这个问题。

要求：

1. 找到失败测试对应的业务调用链

2. 分析为什么返回 pending

3. 判断是测试错误还是业务代码错误

4. 如果是业务代码错误，修复它

5. 重新运行相关测试

6. 如果相关测试通过，再运行完整测试

不要为了让测试通过而修改测试断言。

“不要为了让测试通过而修改测试断言”这句话非常重要，否则 AI 很容易出现代码错了 → 修改测试 → 测试通过 → 看起来没问题的假修复。

十二、一个非常实用的 Debug Prompt

以后遇到 Bug，可以直接复制：

请帮我排查这个 Bug。

要求严格按照下面步骤执行： 第一步：先定位错误入口。 第二步：分析完整调用链。 第三步：找到真正的根因。 第四步：解释为什么会产生这个问题。 第五步：给出最小修改方案。 第六步：修改代码。 第七步：运行相关测试。 第八步：运行完整测试。

要求：

• 不要为了通过测试而修改测试逻辑

• 不要进行无关重构

• 不要修改无关文件

• 保持现有代码风格

• 最终告诉我根因、修改内容和测试结果

这个 Prompt 非常适合日常开发。

十三、让 Codex 帮你写测试

例如：

请检查 app/services/order_service.py。为这个 Service 补充单元测试。

要求：

1. 覆盖正常情况

2. 覆盖订单不存在

3. 覆盖数据库异常

4. 覆盖非法参数

5. 不要修改业务代码

6. 使用当前项目已有的测试框架

7. 写完以后运行测试

如果发现当前代码不方便测试，先告诉我原因。

这比“帮我写几个测试”效果好很多。

十四、让 Codex 做代码 Review

假设你刚刚开发完一个功能，可以让 Codex：

请 Review 我当前工作区的代码变化。

重点检查：

1. Bug

2. 潜在异常

3. 类型错误

4. 边界条件

5. 性能问题

6. 安全问题

7. 并发问题

8. 数据一致性

9. 是否存在重复代码

10. 是否可能破坏现有功能

请按照严重程度输出：P0、P1、P2、P3。只报告真实问题，不要为了提出问题而提出问题，不要修改代码。

这样可以把 Codex 当成一个 AI Code Reviewer。

十五、让 Codex 帮你做重构

重构的时候不要直接说“把这个项目重构一下”，范围太大。推荐：

请分析 app/services 目录。

目标：

1. 降低重复代码

2. 降低 Service 与数据库层的耦合

3. 保持现有 API 不变

4. 不改变业务行为

第一阶段：只分析问题，不修改代码。 告诉我：

1. 哪些文件存在问题

2. 为什么存在问题

3. 推荐怎么重构

4. 重构风险是什么

5. 哪些地方应该保持不动

确认以后再输入：

按照方案开始重构。要求每完成一个模块就运行对应测试。如果测试失败，立即停止并分析原因。

十六、Codex 非常适合做“渐进式开发”

真实项目开发不要一次性让 AI 从 0 做完整个系统。更推荐按阶段推进：第一阶段：项目分析 → 第二阶段：数据库设计 → 第三阶段：后端 API → 第四阶段：Service → 第五阶段：Agent → 第六阶段：前端页面 → 第七阶段：测试 → 第八阶段：Docker → 第九阶段：Code Review。

例如做一个企业知识库 Agent（用户 → 前端 → FastAPI → Query Understanding → Retriever → Rerank → LLM → Answer），不要一次性全部生成，可以逐步开发。

十七、实战：让 Codex 开发一个 RAG 功能

例如：

给当前项目增加企业知识库 RAG。

技术要求：

1. 支持 PDF 上传

2. 文档解析

3. Chunk 切分

4. Embedding

5. 向量存储

6. Similarity Search

7. TopK

8. Rerank

9. LLM 生成答案

10. 返回引用来源

但是现在不要开始编码。先分析当前项目是否已经存在：文件上传、数据库、向量数据库、LLM Provider、用户系统。然后告诉我哪些可以复用，哪些需要新增。

这样 Codex 会先判断 Existing Capability，而不是重新造轮子。

十八、Codex + MCP

Codex 还可以通过 MCP 扩展能力。例如 OpenAI 官方提供了开发者文档 MCP：https://developers.openai.com/mcp。

可以使用命令添加：

codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp

然后查看：

codex mcp list

官方文档说明，这个 MCP 提供的是 OpenAI 开发文档的只读搜索和读取能力。这样以后你在 Codex 中开发 OpenAI API 时，就可以让它参考最新官方文档。

例如：

请根据 OpenAI 官方最新文档，检查当前项目的 Responses API 使用方式。

重点检查：

1. API 调用方式

2. 参数是否已经过时

3. Model 参数

4. Tool Calling

5. Streaming

如果发现问题，告诉我具体位置。

十九、为什么 MCP 对 Codex 很重要？

可以把 Codex 理解成：大脑 + 代码执行能力 + 项目文件 + 工具。而 MCP 可以不断给它增加数据库、GitHub、浏览器、企业内部系统、API、知识库、官方文档。

最终形成的结构为： Codex 关联项目代码、Terminal、Git、AI Model，同时通过 MCP 扩展连接 GitHub、Docs、Database 及其他工具。这时候它已经不是简单的“AI 写代码”，而是“AI Agent 开发环境”。

二十、项目级 Codex 配置

Codex 支持项目级配置。 用户级配置：~/.codex/config.toml项目级配置：项目目录/.codex/config.toml

官方文档说明，CLI 与 IDE 扩展可以共享这些配置，用来配置模型、审批策略、沙盒以及 MCP 等。

例如目录结构：

my-project/├── .codex/│   └── config.toml├── app/├── tests/└── README.md

二十一、为什么要配置项目级规则？

因为真实团队开发一定有自己的规范（例如：Python 使用 3.13、FastAPI 使用 async、所有 API 必须增加类型定义、Service 不允许直接操作 HTTP Request、数据库访问统一放 Repository、测试使用 pytest、所有新功能必须增加测试、禁止修改已有 API 行为）。这些规则如果每次都告诉 AI 提醒“请注意……”，非常浪费时间，更好的方式是把它们变成项目规则。

二十二、推荐建立自己的 AI 开发规范

例如在项目中建立 AGENTS.md，内容可以写：

# Project Development Rules## Project这是一个 Python + FastAPI 项目。## PythonPython 3.13。## Code Style- 使用类型注解- 优先 async/await- 避免不必要的全局变量- 保持函数职责单一## API- 所有 API 使用 Pydantic Schema- API Router 不直接访问数据库- Service 负责业务逻辑## Database- Repository 负责数据库访问- 不允许在 Router 中直接操作数据库## Testing所有新功能必须增加测试。使用 pytest。修改代码以后必须运行相关测试。## Modification Rules- 优先最小修改- 不进行无关重构- 不修改已有 API 行为- 不删除已有测试

这样以后每次 Codex 工作，都有一份统一的项目开发规范可以遵循。

二十三、Codex + Git 是非常重要的组合

建议遵循流程：开始任务 → git status → 创建分支 → Codex 修改 → 运行测试 → git diff → Codex Review → 提交。

例如：

git checkout -b feature/order-agentcodex

开发完成后执行 git diff，让 Codex 检查：

请检查当前 git diff。

确认：

1. 是否包含无关修改

2. 是否存在明显 Bug

3. 是否存在调试代码

4. 是否存在敏感信息

5. 是否存在测试遗漏

6. 是否符合当前项目规范

不要修改代码。

二十四、让 Codex 帮你生成 Commit Message

检查完成以后：

根据当前 git diff，帮我生成一个符合 Conventional Commits 的 commit message。

要求：

1. 简洁

2. 准确描述实际修改

3. 不要夸大

4. 不要包含不存在的功能

例如可能得到：feat(agent): add order status query agent

二十五、最推荐的 Codex 工作流

如果你是开发者，我比较推荐把日常工作固定成下面这个流程：

用户需求 → Codex 理解需求 → 分析现有项目 → 制定实现方案 → 人确认方案 → Codex 修改代码 → 自动运行测试。如果测试失败，则分析错误 → 修复代码 → 再次测试，直到通过；测试通过后进行 Code Review → git diff → Commit / PR。

这个流程比“一句话让 AI 写完整项目”可靠得多。

二十六、实战案例：让 Codex 从 0 开发一个 AI Agent

下面给一个可以直接复制使用的 Prompt：

我准备在当前项目开发一个企业智能工单 Agent。

技术栈：Python、FastAPI、LangChain、LangGraph、PostgreSQL、Redis、向量数据库、LLM。

核心功能：

1. 用户提交工单

2. Agent 判断用户意图

3. 查询历史工单

4. 查询企业知识库

5. 查询订单信息

6. 查询物流信息

7. 判断是否需要人工介入

8. 生成最终回复

9. 保存会话记录

10. 支持流式输出

现在不要开始写代码。第一阶段请完成项目分析：

1. 阅读当前项目

2. 分析目录结构

3. 分析已有模块

4. 找出可以复用的代码

5. 分析数据库结构

6. 分析 LLM Provider

7. 分析现有 Agent

8. 分析 API

9. 分析测试

然后设计这个 Agent 的完整架构。 输出：一、项目现状 二、Agent 架构 三、核心调用链 四、State 设计 五、Tools 设计 六、LangGraph 节点设计 七、数据库设计 八、API 设计 九、需要修改的文件 十、开发步骤。 不要修改任何文件。

等 Codex 输出方案以后：

方案确认。现在开始按照刚才的方案实现。

要求：

1. 分阶段修改

2. 每完成一个模块进行验证

3. 不要进行无关重构

4. 不要修改已有 API 行为

5. 增加必要测试

6. 每次修改以后运行相关测试

7. 遇到测试失败先分析根因

8. 不要通过修改测试断言来掩盖业务 Bug

最终完成以后告诉我：

1. 修改文件

2. 核心实现

3. 测试结果

4. 启动方式

5. API 调用方式

6. 当前已知问题

二十七、不要这样使用 Codex

• 错误方式一：一句话生成整个项目（例如“帮我开发一个企业级 AI Agent”）。问题：需求不明确、架构不明确、边界不明确、测试不明确，容易产生大量不可控代码。

• 错误方式二：不看 diff。 Codex 修改完以后直接“可以了”，这是非常危险的。至少要用 git diff 检查：修改了哪些文件？为什么修改？有没有无关代码？有没有删除东西？有没有修改配置？有没有敏感信息？

• 错误方式三：不运行测试。 代码看起来没问题 ≠ 代码真的能运行。一定要：修改 → 测试 → 失败 → 修复 → 测试。

• 错误方式四：让 AI 修改测试来“通过测试”。 例如测试失败 → AI 修改 assert → 测试通过，这种方式没有意义。正确的是：测试失败 → 找到业务根因 → 修复业务代码 → 测试通过。

二十八、一个非常重要的技巧：告诉 Codex“不要做什么”

很多时候光告诉 AI 做什么还不够，还应该告诉它不要做什么。例如：

要求：

• 不要修改数据库结构

• 不要修改现有 API

• 不要新增依赖

• 不要进行大规模重构

• 不要删除测试

• 不要修改环境变量

• 不要修改 Docker 配置

• 不要修改前端

这样可以明显减少 AI 的“自由发挥”。

二十九、从“代码生成”升级到“工程协作”

真正使用 Codex 一段时间以后，你会发现 Codex 最有价值的地方并不是“帮我写一个函数”，而是：理解大型项目 + 分析问题 + 修改多个文件 + 执行命令 + 运行测试 + 根据反馈继续修改 + Review。

也就是说，传统 AI 编程（人 → AI → 代码 → 人执行 → 人发现问题 → AI）变成了 Agent Coding（人 → Codex → 分析 → 修改 → 执行 → 测试 → 发现问题 → 继续修改 → 验证 → 最终结果）。这才是 Codex 真正值得学习的地方。

三十、给开发者的一套 Codex Prompt 模板

• 模板 1：项目分析

  请分析当前项目，不要修改代码。重点分析：1. 技术栈 2. 目录结构 3. 核心模块 4. 数据流 5. API 6. 数据库 7. 测试 8. 启动方式 9. 构建方式 10. 潜在问题。最后输出项目架构说明。

• 模板 2：开发功能

  请实现这个功能：【功能描述】。要求：1. 先分析现有代码 2. 给出实现方案 3. 列出需要修改的文件 4. 确认方案后再修改 5. 保持现有代码风格 6. 不进行无关重构 7. 增加测试 8. 运行测试 9. 最后总结修改内容。

• 模板 3：Bug 排查

  请排查这个 Bug：【错误信息】。要求：1. 定位错误入口 2. 分析调用链 3. 找出根因 4. 给出最小修改方案 5. 修改代码 6. 运行相关测试 7. 运行完整测试。不要修改测试来掩盖业务问题。

• 模板 4：Code Review

  请 Review 当前 git diff。重点检查：1. Bug 2. 安全 3. 性能 4. 类型 5. 异常处理 6. 边界条件 7. 并发 8. 数据一致性 9. 测试覆盖 10. 是否存在无关修改。不要修改代码，按照严重程度输出问题。

• 模板 5：重构

  请分析：【文件 / 模块】。第一阶段不要修改代码，告诉我：1. 当前问题 2. 重复代码 3. 耦合问题 4. 可优化点 5. 重构方案 6. 风险。等我确认以后再开始重构。

三十一、最终形成自己的 AI Coding 工作流

如果你是前端、Java、Python 或 AI Agent 开发者，可以逐步形成流程：

需求 → Codex 分析 → 技术方案 → 人工确认 → Codex Coding → 自动执行命令 → 自动测试。若 PASS 则进行 Code Review → Git Diff → Commit → PR；若 FAIL 则进行 Debug → Fix 并重新测试。

这套流程真正建立起来以后，Codex 就不只是一个“AI 写代码工具”，而更接近“AI 软件工程师”。

三十二、学习 Codex 最重要的三个阶段

• 第一阶段：会用（掌握安装、启动、项目分析、修改代码、运行测试、Debug）。

• 第二阶段：会协作（掌握 Plan、Task Decomposition、Git、Code Review、测试、项目规范、MCP）。

• 第三阶段：会构建自己的 AI Coding Workflow（最终形成：需求分析 + 项目上下文 + AGENTS.md + MCP + Git + 自动测试 + Code Review）。

这时候你真正掌握的就不是某一个 AI 工具，而是如何让 AI 参与真实的软件工程。

三十三、建议你今天直接做一次完整实战

不要只看教程，找一个自己已经有的项目（例如 FastAPI 项目、React 项目或 Vue3 项目），然后按照下面顺序操作：

• Step 1：cd your-project

• Step 2：codex

• Step 3：让 Codex 分析项目（“请先分析当前项目，不要修改代码。”）

• Step 4：挑一个真实 Bug（“请帮我定位这个 Bug。”）

• Step 5：让它修复（“找到根因以后进行最小修改。”）

• Step 6：让它测试（“运行相关测试。”）

• Step 7：让它 Review（“请 Review 当前 git diff。”）

• Step 8：最后自己用 git diff 再看一遍。

三十四、最后总结

如果只记住一句话：不要把 Codex 当成“代码生成器”，而要把它当成一个可以进入项目、执行任务、运行代码、根据反馈继续工作的 AI 开发协作者。

真正高效的 Codex 使用方式不是“帮我写代码”，而是：理解项目 → 分析需求 → 制定方案 → 修改代码 → 执行命令 → 运行测试 → 分析错误 → 继续修复 → Code Review → Git 提交。

对于现在的前端、Java、Python 以及 AI Agent 开发来说，这套工作方式比单纯学习几个 Prompt 更重要。最终目标不是让 AI 替你写更多代码，而是让你一个人能够完成过去需要多人协作才能完成的一整套开发流程。

官方资料

• Codex 官方学习中心：OpenAI Codex

• Codex / OpenAI Developers Plugin：OpenAI Developers Plugin

• Codex 配置说明：Codex 配置文件

• OpenAI Docs MCP：Docs MCP