OpenAI Codex 使用指南：从安装到项目实战的完整教程
更新日期：2026 年 8 月 4 日。 本文面向第一次接触 AI 编程代理的开发者，也适合已经会使用 ChatGPT、希望进一步自动化开发流程的用户。
过去的 AI 编程工具主要负责“补全下一行代码”，而 OpenAI Codex 更像一位能够进入项目、阅读文件、执行命令、修改代码并验证结果的协作开发者。你可以让它解释陌生仓库、修复 Bug、添加功能、补充测试、审查改动，甚至处理一套由多个步骤组成的开发任务。
不过，Codex 并不是“一句话生成整个项目”的魔法按钮。真正高效的使用方式，是给它清晰的目标、足够的上下文、明确的验收标准，并在关键操作上保留人工判断。本文将从安装开始，逐步讲清楚 Codex 的工作方式和实战技巧。
一、Codex 是什么？
Codex 是 OpenAI 推出的 AI 编程代理。它不仅能回答代码问题，还能围绕一个真实代码仓库执行完整工作流：
- 浏览目录并理解项目结构；
- 搜索相关代码和配置；
- 制定修改方案；
- 编辑一个或多个文件；
- 运行测试、构建或静态检查；
- 根据执行结果继续修正；
- 总结完成内容和剩余风险。
这与普通聊天机器人的最大区别在于：普通聊天通常只“告诉你怎么做”，Codex 可以在授权范围内“直接帮你做”。
Codex 适合完成哪些任务？
- 阅读并解释陌生项目；
- 定位错误日志对应的代码；
- 修复 Bug、补充边界条件；
- 创建页面、接口或组件；
- 编写单元测试和集成测试；
- 重构重复代码；
- 执行代码审查；
- 更新 README、接口文档和变更说明；
- 批量处理规则明确的机械修改。
哪些任务不应完全交给 Codex？
- 没有人工复核的生产数据库操作；
- 涉及密钥、支付和敏感用户数据的高风险操作；
- 需求本身尚未确定的重大架构改造；
- 没有测试或验收标准的全项目重写；
- 需要承担法律、医疗或财务责任的最终判断。
二、选择适合自己的 Codex 使用方式
Codex 可以通过不同界面参与开发。它们的底层思路相似，但使用场景不同。
| 使用方式 | 适合人群 | 典型场景 |
|---|---|---|
| Codex CLI | 熟悉终端的开发者 | 在本地仓库中分析、修改、测试和自动化 |
| IDE 扩展 | 日常使用编辑器的开发者 | 结合当前文件和选中代码快速协作 |
| Codex 桌面端 | 希望集中管理任务的用户 | 多任务协作、查看改动、运行开发工作流 |
| 云端任务 | 需要异步或并行处理的人 | 将相对独立的开发任务交给云端环境 |
新手可以从 IDE 或桌面端开始；如果你经常使用终端、需要脚本化处理或希望精确控制工作目录，Codex CLI 通常最灵活。
三、安装和登录 Codex CLI
3.1 安装前准备
使用 npm 安装时，需要先准备较新的 Node.js 和 npm。可以在终端检查：
node -v
npm -v然后安装 Codex CLI：
npm install -g @openai/codex安装完成后验证：
codex --versionCodex 更新较快，建议以 OpenAI Codex 官方文档 中的最新安装说明为准。如果已经安装，也可以查看当前版本支持的功能：
codex --help3.2 登录
执行：
codex login然后按照终端提示完成认证。登录后可以检查状态：
codex login status不同账号、组织和部署环境的可用模型、额度及功能可能不同，不建议在教程中写死套餐限制。以登录后界面和官方说明为准。
3.3 在项目中启动
先进入 Git 项目根目录，再启动 Codex：
cd /path/to/your-project
codex也可以直接指定工作目录：
codex -C /path/to/your-project第一次使用时，建议从只读分析开始：
请先阅读这个项目，不要修改文件。告诉我：
1. 使用了哪些技术栈；
2. 应用从哪里启动；
3. 核心模块如何协作；
4. 本地开发和测试命令是什么；
5. 目前最值得关注的三个风险。这一步能帮助你判断 Codex 是否正确理解了仓库，也能避免在上下文不足时过早修改代码。
四、Codex 的一次标准工作流
一个可靠的 Codex 任务，通常包含“理解—计划—修改—验证—总结”五个阶段。
第一步：描述目标，而不只是描述动作
不够理想的提示词：
改一下登录页面。更有效的提示词：
修复登录页面在手机端按钮超出屏幕的问题。
要求：
- 保持桌面端布局不变；
- 兼容 375px 宽度；
- 不引入新的 UI 依赖；
- 修改后运行现有前端测试和构建；
- 最后说明改了哪些文件。后一个提示词同时给出了目标、边界和验收方式，Codex 更容易一次完成。
第二步：让 Codex 先找证据
遇到 Bug 时，不要急着让它“直接修复”，可以先要求定位原因：
这是报错信息：[粘贴错误日志]
请先定位根因并指出相关文件，不要修改代码。
列出你排除过的可能原因，以及建议的最小修复方案。确认分析合理后，再继续：
按最小修复方案实施，并补充一个能复现该问题的测试。第三步：控制修改范围
Codex 能修改多个文件，但修改范围越大，审查成本越高。建议明确写出：
- 可以修改哪些目录；
- 哪些公共接口必须保持兼容；
- 是否允许增加依赖；
- 是否允许修改数据库结构；
- 是否需要保留旧行为。
示例：
仅修改 src/auth 和 tests/auth，不要改数据库 schema，不要新增依赖。
现有公开函数签名必须保持兼容。第四步：要求验证，而不是只看代码
代码“看起来正确”不等于真的可用。应要求 Codex 执行项目已有的检查：
完成修改后，请依次运行：
1. 单元测试；
2. 类型检查；
3. lint；
4. 生产构建。
如果某一步失败，请先判断是否由本次改动导致，再继续修复。如果项目测试非常慢，可以指定最小验证集，最后再运行完整检查。
第五步：审查最终差异
任务完成后，重点检查：
- 是否只改了需要修改的文件；
- 是否出现无关格式化；
- 是否意外删除原有逻辑；
- 测试是否真正覆盖问题；
- 是否引入新依赖或配置；
- 是否存在未验证的假设。
你还可以开启一个新的上下文，让 Codex 以审查者身份重新检查：
codex review独立审查通常比让同一轮对话“检查自己”更容易发现问题。
五、6 个常用实战场景
场景 1：快速读懂陌生项目
请分析这个仓库，输出一份新成员上手指南，包括：
- 目录结构；
- 核心数据流；
- 主要模块及依赖关系；
- 本地启动步骤；
- 测试策略；
- 新增一个 API 通常需要修改哪些文件。
只读取文件，不要修改。场景 2：根据错误日志修复 Bug
运行与这个报错相关的最小测试，定位根因后实施最小修复。
不要通过删除测试、捕获并忽略异常或写死返回值来绕过问题。
修复后添加回归测试，并汇报验证结果。场景 3：实现一个新功能
为用户列表增加按邮箱搜索功能。
验收标准：
- 支持部分匹配；
- 搜索不区分大小写；
- 空关键词返回默认列表；
- 保持现有分页行为；
- 添加接口测试；
- 不新增第三方依赖。
先给出简短计划，再开始修改。场景 4：补测试
检查 src/payment/calculate.ts 的现有测试覆盖。
重点补充边界条件、异常输入和金额精度测试。
不要为了让测试通过而修改业务逻辑；如果发现业务 Bug，先说明再处理。场景 5：安全重构
重构重复的权限判断逻辑，目标是减少重复代码，但保持外部行为不变。
先找出现有调用点和测试，再提出最小重构方案。
每完成一个阶段都运行相关测试，避免一次性大改。场景 6：生成结构化结果
Codex CLI 的非交互模式适合脚本和 CI：
codex exec "检查当前仓库中可能泄露密钥的代码，并给出按风险排序的报告，不要修改文件"如果后续程序需要消费结果，可结合 --json 或 --output-schema 输出机器可读内容。使用前先运行 codex exec --help，确认当前版本的参数。
六、用 AGENTS.md 固化项目规则
如果每次都要重复告诉 Codex“测试命令是什么”“禁止修改什么”，可以在仓库中添加 AGENTS.md。它适合记录长期有效的协作约定，例如：
# AGENTS.md
## 项目约定
- 使用 TypeScript，禁止新增 JavaScript 文件。
- 新功能必须补充测试。
- 不要修改 generated/ 目录中的生成文件。
## 常用命令
- 安装依赖：npm ci
- 单元测试：npm test
- 类型检查：npm run typecheck
- 生产构建：npm run build
## 提交前检查
- 保持公开 API 向后兼容。
- 不提交密钥、构建产物和本地配置。
- 汇报未运行的检查及原因。好的 AGENTS.md 应该简短、具体、可执行。不要把整份架构文档全部塞进去；更适合写命令、约束、目录规则和验收要求。
七、权限、沙箱与安全
Codex 可以执行终端命令和编辑文件，因此权限设置非常重要。常见沙箱模式包括：
read-only：只读，适合代码分析和审查；workspace-write：可修改当前工作区，适合大多数开发任务；danger-full-access：访问范围很大，风险最高，不应作为日常默认值。
启动时可以指定沙箱模式：
codex --sandbox read-only
codex --sandbox workspace-write审批策略决定 Codex 何时需要请求确认。日常使用中，建议保留审批和沙箱，不要为了少点一次确认就使用绕过安全限制的危险参数。
安全使用原则
- 先读后写：陌生仓库先分析，再授权修改；
- 最小权限：只开放任务需要的目录和命令；
- 保护密钥：不要在提示词中粘贴 API Key、密码或生产凭证；
- 谨慎联网：安装依赖和访问外部服务前确认来源；
- 警惕破坏性命令：删除、重置、覆盖和数据库迁移必须人工确认；
- 始终查看 diff：不要未经审查直接提交或发布；
- 重要任务要测试：构建成功不能代替业务测试。
八、如何写出高质量 Codex 提示词？
一个实用的 Codex 提示词，可以使用下面的五段式结构：
【目标】要解决什么问题
【上下文】相关页面、模块、错误日志或业务背景
【范围】允许和禁止修改什么
【验收】什么结果才算完成
【验证】需要运行哪些测试或检查完整示例：
【目标】修复商品详情页重复请求库存接口的问题。
【上下文】用户切换规格时偶尔会发送两次相同请求，怀疑与组件重复渲染有关。
【范围】仅修改商品详情页及相关 hooks，不更改后端接口，不新增依赖。
【验收】同一规格在状态未变化时只请求一次；快速切换规格时展示最后一次请求的结果。
【验证】补充回归测试，运行前端单测、类型检查和构建。最后说明根因、改动和测试结果。此外，还有三条非常有效的原则：
- 告诉 Codex 为什么 要改，避免它只处理表面现象；
- 提供可验证的完成条件，避免“优化一下”这类模糊要求；
- 让它主动报告不确定性，不要默默猜测业务规则。
九、常见问题与解决方法
1. Codex 一上来就修改了太多文件
在提示词中加入“先分析，不要修改”“优先最小改动”“限制到指定目录”，并使用只读沙箱完成第一轮分析。
2. Codex 修改后测试仍然失败
让它区分：失败是否由本次改动引起、失败是否在修改前就存在、运行环境是否缺少依赖。不要允许它通过删除测试或降低断言标准来制造“通过”。
3. Codex 总是误解业务需求
补充真实输入输出示例、异常情况和验收标准。业务规则越隐含，模型越容易做出看似合理但错误的假设。
4. 上下文太长，任务开始跑偏
把大任务拆成可独立验证的小阶段。一个阶段完成后总结状态，再开启新任务处理下一阶段。需要继续之前的会话时，可使用：
codex resume5. 如何判断 Codex 的代码能不能上线？
至少满足四个条件：人工审查通过、自动化测试通过、关键业务场景手动验证通过、发布和回滚方案明确。Codex 可以提高实现速度，但不能替代工程责任。
十、结语：把 Codex 当作协作开发者
使用 Codex 的关键，不是寻找一句“万能提示词”，而是建立一套稳定的协作流程：先让它理解项目，再给出边界清晰的任务；让它用测试证明结果；最后由人审查差异并承担决策责任。
对于简单任务，Codex 可以直接节省大量机械劳动；对于复杂任务，它更适合作为调查员、实现者和审查助手。只要目标明确、权限合理、验证充分，Codex 就能从“代码生成工具”升级为真正融入开发流程的 AI 编程伙伴。