Codex 实战指南

AI 编程工具这几年很多，但 Codex 和普通“代码补全工具”不太一样。它更像一个可以进入项目、阅读代码、修改文件、运行命令、解释报错、补测试、修 Bug、做代码审查的编程代理。

简单来说，传统代码助手更像是“帮你补几行代码”；而 Codex 更像是“帮你完成一个开发任务”。

本文会从日常开发视角介绍 Codex 的基本用法，包括安装、初始化、CLI 使用、IDE 使用、Prompt 写法、项目规则配置、权限控制，以及几个真实开发中的常见场景。

---

1. Codex 适合做什么？

Codex 最适合处理那些需要理解项目上下文的任务，比如：

• 阅读陌生代码库；
• 解释某个模块的调用链；
• 修复一个明确的 Bug；
• 为已有函数补充测试；
• 根据需求实现一个小功能；
• 检查当前 git diff；
• 总结 CI 失败原因；
• 生成 release notes；
• 重构局部代码；
• 审查 PR 中的潜在风险。

它不是只能“回答怎么写”，而是可以直接参与开发过程：读文件、改代码、跑测试、根据测试结果继续修复。

这也是 Codex 和普通聊天式代码问答最大的区别。

---

2. 选择哪种使用方式？

Codex 常见的使用方式有几种：

使用方式	适合场景
IDE 插件	日常写代码、改文件、看 diff
CLI	终端工作流、脚本化任务、自动化开发
云端任务	较大的开发任务、并行任务、PR 级别修改
GitHub 集成	PR Review、根据 issue 或评论触发任务

如果你是第一次使用，我建议优先从 IDE 插件 或 CLI 开始。

IDE 插件最适合日常开发，因为它离代码最近，可以结合你当前打开的文件和选中的代码来理解上下文。

CLI 更适合喜欢终端的人，也适合做一些半自动化任务，比如分析测试失败、生成变更总结、批量检查代码。

云端任务更适合比较完整的需求，比如“修复一个 CI 失败”“实现一个筛选功能”“重构某个模块并补测试”。

---

3. 安装 Codex CLI

如果你是 macOS 用户，可以使用 Homebrew：

brew install --cask codex

安装完成后，进入你的项目目录：

cd your-project
codex

第一次运行时，一般会提示你登录。登录完成后，就可以在当前项目中直接和 Codex 交互。

进入交互界面后，不建议一开始就让它大改代码。可以先让它做一次只读分析：

请阅读这个项目，概括它的目录结构、主要模块、启动方式和测试方式。不要修改任何文件。

这个请求很适合作为第一次接触项目时的“项目导览”。

---

4. 登录方式

Codex 通常支持两种登录方式：

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

如果你只是日常开发使用，直接用账号登录会更方便。

如果你想把 Codex 放进脚本、CI 或自动化流程里，可以考虑使用 API Key。不过这种方式更适合有工程化需求的场景，普通个人开发者一开始没必要优先折腾。

登录后可以检查状态：

codex login status

如果需要重新登录：

codex login

注意，不要把本地认证文件、API Key 或任何凭据提交到代码仓库里。尤其是团队项目里，最好把这些内容加入 .gitignore，避免误传。

---

5. 第一次可以让 Codex 做什么？

刚开始使用 Codex 时，建议从低风险任务开始。

例如，让它解释项目结构：

请阅读当前项目，输出：
1. 项目技术栈；
2. 主要目录职责；
3. 启动命令；
4. 测试命令；
5. 最核心的 5 个模块；
6. 新人上手时最应该先读哪些文件。

不要修改任何代码。

再进一步，可以让它分析某个模块：

请解释 src/auth 目录的职责，列出核心文件、调用链路和潜在风险点。不要修改代码。

等你确认它对项目理解基本正确后，再让它做小范围修改：

请为 login 函数补充单元测试。要求：
1. 不改变生产代码行为；
2. 覆盖成功登录、密码错误、用户不存在三个场景；
3. 修改后运行相关测试；
4. 最后说明改了哪些文件。

这种任务范围明确、验证方式清楚，非常适合交给 Codex。

---

6. 写好 Prompt 的关键

Codex 的效果很大程度上取决于你怎么描述任务。

6.1 不要只说“优化一下”

不推荐这样写：

帮我优化一下这个项目。

这个请求太宽泛，Codex 很难判断什么叫“优化完成”。

更好的写法是：

请优化首页首屏加载性能。完成标准：
1. 不改变现有 UI；
2. 尽量减少首屏 JS 体积；
3. 保留现有测试全部通过；
4. 最后输出修改文件、优化点和风险点。

好的 Prompt 一般要包含四个信息：

1. 要解决什么问题；
2. 修改范围在哪里；
3. 有哪些限制；
4. 如何验证结果。

---

6.2 复杂任务先让它写计划

如果任务比较复杂，不要直接让它开改。可以先让 Codex 分析：

先不要改代码。请先分析这个需求，列出实现方案、涉及文件、风险点和测试计划。等我确认后再开始修改。

这个方式特别适合下面几类任务：

• 涉及多个模块；
• 可能影响数据库结构；
• 可能影响权限逻辑；
• 可能影响支付、订单、登录等核心流程；
• 你自己也不确定最佳实现方式。

先让它写计划，你可以提前发现方向是否跑偏。

---

6.3 给它足够的上下文

不推荐这样写：

修一下支付问题。

更好的写法是：

用户反馈：订单支付后偶尔会重复扣款。请重点查看：
- src/services/payment.ts
- src/controllers/order.ts
- tests/payment.test.ts

目标：
1. 找到可能导致重复扣款的原因；
2. 写一个能复现问题的测试；
3. 做最小代码修改；
4. 运行相关测试；
5. 总结根因、修改内容和剩余风险。

你给的上下文越清楚，Codex 越容易给出可用结果。

---

6.4 要求它验证自己的修改

让 Codex 改代码时，最好明确告诉它需要运行哪些验证命令：

修改完成后，请运行：
npm test -- payment
npm run lint

如果测试失败，请继续修复，直到相关测试通过；如果无法通过，请说明失败原因和下一步建议。

这一步非常重要。

如果只是让它“写完代码”，结果可能看起来能用，但没有验证。让它跑测试、看报错、继续修复，质量会明显更稳定。

---

7. 用 AGENTS.md 固化项目规则

如果你的项目有固定规范，不要每次都写在 Prompt 里。可以在仓库根目录创建一个 AGENTS.md 文件，把团队规则写进去。

示例：

# AGENTS.md

## 项目规则

- 使用 pnpm 管理依赖，不要使用 npm 或 yarn。
- 修改 TypeScript 代码后必须运行 pnpm typecheck。
- 提交 PR 前必须运行 pnpm lint 和 pnpm test。
- 不要引入新的生产依赖，除非先解释原因并等待确认。
- 修改公共 API 时，需要同步更新 docs/ 目录下的文档。
- 不要大范围重构无关代码。
- 优先做最小可验证修改。

这个文件可以理解成给 Codex 的“项目协作手册”。

它特别适合多人项目，因为团队可以把开发规范、测试命令、依赖策略、提交要求、安全要求统一写进去。这样每次 Codex 进入项目时，就能更稳定地遵守这些规则。

我个人非常建议每个长期项目都加一个 AGENTS.md。

---

8. 权限和安全边界

Codex 可以读文件、改文件、运行命令，所以权限控制很重要。

常见权限模式可以简单理解为：

模式	适合场景
read-only	只读分析、解释项目、审查代码
workspace-write	日常开发、修改项目内文件、运行测试
full access	高风险操作，只适合隔离环境

第一次使用时，建议尽量从只读模式开始：

codex --sandbox read-only

日常开发可以使用工作区写入模式：

codex --sandbox workspace-write

不建议在自己的主力开发环境里随便给完全访问权限。尤其是当项目里有部署脚本、数据库脚本、云服务配置、密钥文件时，更要小心。

一个比较稳妥的原则是：

能只读就只读，能限制在项目目录内就不要给全局权限，能在临时分支里做就不要直接改主分支。

---

9. 常见开发场景

9.1 解释陌生代码库

请阅读当前项目，输出：
1. 项目技术栈；
2. 主要目录职责；
3. 启动命令；
4. 测试命令；
5. 核心业务流程；
6. 新人上手建议。

不要修改任何代码。

这个场景非常适合刚接手一个项目时使用。

---

9.2 修复 Bug

用户反馈：登录后偶尔被重定向到 /login。请：
1. 查找可能原因；
2. 写一个能复现问题的测试；
3. 做最小代码修改；
4. 运行相关测试；
5. 总结根因、修改内容和剩余风险。

这里的重点是“先复现，再修复”。

不要一上来就让它直接改。能复现的问题，才更容易验证是否真的修好了。

---

9.3 实现新功能

请为订单列表增加“按订单状态筛选”的功能。要求：
1. 支持 pending、paid、cancelled 三种状态；
2. URL query 参数使用 status；
3. 保持现有分页逻辑不变；
4. 增加单元测试和必要的 UI 测试；
5. 不引入新的第三方依赖。

实现功能时，Prompt 里最好写清楚边界，比如：

• 是否允许改接口；
• 是否允许改数据库；
• 是否允许加依赖；
• 是否需要兼容旧逻辑；
• 是否需要补测试；
• 是否需要更新文档。

这些信息如果不写，Codex 可能会默认选择一个它认为合理、但不一定适合你项目的方案。

---

9.4 补充测试

请为 src/utils/date.ts 补充测试。要求：
1. 覆盖时区边界；
2. 覆盖非法输入；
3. 覆盖闰年；
4. 不修改生产代码，除非发现明显 bug，并先说明原因。

补测试是 Codex 非常适合做的任务。

很多项目里，开发者不是不会写测试，而是觉得写测试很琐碎。这类重复性强、规则明确的工作，很适合交给 AI 处理。

---

9.5 做代码审查

请审查当前 git diff，重点关注：
1. 安全漏洞；
2. 竞态条件；
3. 错误处理；
4. 类型边界；
5. 是否缺少测试。

只输出高优先级问题，不要纠结格式和命名。

这个 Prompt 的关键是指定审查重点。

如果你不指定重点，它可能会指出很多风格类问题，反而影响效率。对于真实项目，建议优先让它关注安全、数据一致性、权限、边界条件和测试缺失。

---

10. 用 codex exec 做自动化

除了交互式使用，Codex CLI 还可以用非交互方式执行任务。

例如，生成最近提交的 release notes：

codex exec "generate release notes for the last 10 commits" | tee release-notes.md

分析测试失败原因：

npm test 2>&1 \
  | codex exec "summarize the failing tests and propose the smallest likely fix" \
  | tee test-summary.md

让它总结项目结构：

codex exec "summarize the repo structure"

这种方式适合放进脚本里，比如：

• 每次发版前生成变更说明；
• 测试失败后自动总结原因；
• CI 失败后输出可能的修复方向；
• 定期扫描项目中的 TODO；
• 批量检查某类代码风险。

不过要注意，自动化场景里权限要给得更谨慎。尤其是在 CI 环境中，不要随便把密钥暴露给任务执行过程，也不要让不可信代码轻易接触敏感环境变量。

---

11. 云端任务适合什么场景？

如果任务比较大，或者你不想一直盯着本地终端，可以考虑把任务交给云端环境处理。

比较适合的任务包括：

• 修复 CI 失败；
• 实现一个独立小功能；
• 补充测试覆盖；
• 重构某个模块；
• 分析大型仓库结构；
• 根据 issue 生成一个初版 PR；
• 检查某次改动是否引入风险。

一个适合云端执行的 Prompt：

请分析当前仓库中导致 CI 失败的原因，做最小修复，并确保相关测试通过。完成后输出：
1. 根因；
2. 修改文件；
3. 验证命令；
4. 潜在风险。

云端任务的好处是可以并行处理，也不会占用你本地开发环境。

但它不适合完全无脑托管。最后的 diff 还是要自己 review，尤其是涉及权限、支付、订单、数据迁移、登录态、缓存策略这些关键逻辑时。

---

12. 推荐工作流

我更推荐把 Codex 当成“会干活但必须 review 的队友”，而不是完全自动驾驶。

比较稳的流程是：

理解项目 → 制定计划 → 小步修改 → 运行测试 → 查看 diff → 人工 review → 提交

对应到实际使用中，可以这样操作：

第一步，只读分析：

请解释这个模块，不要修改代码。

第二步，制定计划：

请制定修复方案，列出涉及文件和测试计划，先不要动手。

第三步，执行修改：

按方案实现，做最小修改，并运行相关测试。

第四步，复核结果：

请审查你刚才的修改，重点找潜在 bug、遗漏测试和安全问题。

这个流程看起来比“一句话让它全部改完”慢一点，但稳定性会高很多，尤其适合真实生产项目。

---

13. 常见坑

13.1 任务太大

不要这样写：

帮我重构整个项目。

更好的方式是拆小：

请先重构 payment service，保持对外 API 不变，并补充相关测试。

Codex 更适合处理边界清楚的小任务。任务越大，越容易偏离你的预期。

---

13.2 没有明确验证方式

不推荐：

帮我修一下测试。

更推荐：

请运行 npm test，找到失败原因，做最小修复，并确保相关测试通过。

有验证命令，Codex 就能根据真实反馈迭代。

---

13.3 盲目信任结果

Codex 改完代码后，一定要看 diff。

重点关注：

• 删除了什么逻辑；
• 是否绕过了权限判断；
• 是否改变了公共 API；
• 是否引入了新依赖；
• 是否破坏了边界条件；
• 是否只是让测试“看起来通过”；
• 是否修改了和任务无关的大量文件。

Codex 可以提高效率，但最终责任仍然在开发者自己。

---

13.4 没有项目规则

如果没有 AGENTS.md，每次都要在 Prompt 里重复项目规范，很麻烦，也容易漏。

建议把这些内容固化下来：

• 包管理器；
• 测试命令；
• lint 命令；
• 类型检查命令；
• 是否允许新增依赖；
• 是否允许大范围重构；
• 文档更新要求；
• 提交前检查项。

---

13.5 权限给得太大

不要一开始就给最高权限。

普通开发任务大多数只需要项目目录内的读写权限。涉及系统目录、全局配置、密钥、部署环境的操作，都应该谨慎处理。

---

14. 总结

Codex 最适合的定位不是“替代程序员”，而是一个可以参与工程流程的 AI 编程搭档。

它擅长处理这些事情：

• 快速理解项目；
• 分析代码调用链；
• 补充测试；
• 修复小 Bug；
• 总结报错；
• 检查 diff；
• 生成文档；
• 处理重复性开发任务。

真正用好 Codex 的关键有三个：

1. 给清楚上下文和完成标准。
2. 让它小步执行，并要求验证。
3. 始终 review 它的修改，不要盲目信任。

当你把 Codex 接入 IDE、CLI、GitHub 和自动化脚本之后，它就不只是一个聊天工具，而是可以融入日常开发流程的编程代理。

对于个人开发者，它能减少查代码、写样板代码和补测试的时间。对于团队项目，它可以帮助新人理解项目、辅助代码审查、提高重复任务处理效率。

我的建议是：不要一上来就让 Codex 接管整个项目，而是先从小任务开始，比如解释模块、补测试、修一个明确 Bug。等你熟悉它的能力边界之后，再逐步把它接入更完整的开发流程。