Codex 实战教程：从安装配置到让 AI 协作完成项目
面向开发者的 Codex 入门与实战教程，覆盖安装、项目初始化、有效提示词、测试验证和安全协作流程。
Codex 是面向软件开发任务的 AI 编程助手。它可以阅读项目结构、修改代码、运行测试，并把执行结果反馈给你。更有效的使用方式不是把它当成一次性代码生成器，而是把它放进现有的开发流程中：你定义目标与边界，Codex 协助分析、实现和验证，最终决策仍由开发者负责。
一、开始前的准备
使用 Codex 前，先准备一个可以独立构建和测试的项目。建议完成以下检查：
- 保证 Git 状态可读，重要改动先提交或暂存；
- 在项目根目录确认构建、测试和格式化命令；
- 不要把 .env、API Key、生产数据库连接串或客户数据交给工具；
- 把要完成的任务写成可验证的结果，而不是一句模糊的“优化一下”。
例如，“为订单列表增加按状态筛选，并补充接口和组件测试”就比“改一下订单页”更容易得到可靠结果。
二、安装与登录
在已安装 Node.js 的终端中执行：
npm install -g @openai/codex
codex --version
然后进入目标仓库并启动 Codex：
cd your-project
codex
首次使用时按终端提示完成账户登录或配置。安装方式和可用模型会随版本变化，遇到问题时优先查看官方文档和 codex --help 输出。不要从不明来源复制登录令牌，也不要将令牌写进仓库。
三、先让 Codex 理解项目
不要一开始就要求直接改文件。先给它一个阅读和汇报任务：
请先阅读项目结构、README、package.json 和与订单列表相关的模块。
不要修改任何文件。说明现有数据流、测试入口，以及实现状态筛选可能涉及的文件。
这一步能让你确认它理解了仓库，也能尽早发现依赖、目录约定或测试方式。对于较大的项目，可进一步限定范围，例如只分析 src/features/orders 和相关 API。
四、把任务拆成可验收的小步骤
一次完成需求看起来省事，但很难定位错误。推荐按以下顺序协作：
- 先要求提出实现方案，列出要改的文件和风险；
- 确认方案后，只实现第一部分，例如接口参数与服务层；
- 运行相关测试，检查 diff；
- 再实现页面交互和边界状态；
- 最后执行完整测试、格式化和人工验收。
一个清晰的实现提示词可以这样写：
在不改变现有接口响应结构的前提下，为订单列表增加 status 查询参数。
先说明计划；确认后修改服务层、页面筛选控件和测试。
复用仓库已有的请求与组件模式。完成后运行相关测试，并总结改动、测试结果和仍需人工确认的事项。
提示词里最重要的是约束：目标、影响范围、不能改动的内容、完成标准和验证命令。
五、常见工作流示例
排查 Bug
先提供复现步骤、实际结果、预期结果和日志片段。要求 Codex 从最可能的调用链开始排查，并在修改前说明根因假设。修复后必须补一个能复现问题的测试，避免只修表象。
新增功能
先让它列出数据模型、接口、前端状态、错误处理和测试点。对于跨模块需求，分多轮提交。每一轮结束都查看 git diff，确认没有顺手改动无关文件。
代码审查
可以要求它重点检查空值、权限、并发、异常处理、N+1 查询和兼容性。审查任务要明确“只报告问题，不改代码”，这样能把诊断和实现分开。
六、让结果可验证
Codex 给出的代码不应直接进入生产。至少完成以下检查：
- 阅读变更内容，确认实现与需求一致；
- 运行项目的单元测试、类型检查、构建和格式化命令；
- 检查错误分支、空数据、权限边界和加载状态；
- 对数据库迁移、支付、权限与删除操作进行人工复核；
- 提交前确认没有把密钥、调试日志或无关文件带入 diff。
可直接要求：
请运行与本次改动相关的测试和静态检查。若无法运行，请说明原因和可执行的命令；不要把未执行的命令描述为已通过。
七、用项目说明减少重复沟通
把稳定的协作规则写进仓库说明文件，例如 AGENTS.md 或团队约定文档。内容可以包括：目录职责、常用命令、代码风格、测试要求、禁止修改的模块和提交规范。每次开始新任务时，先让 Codex 阅读这些规则。
不过说明文件不是越长越好。它应该记录不会频繁变化的事实；具体需求、上线时间和业务判断仍应放在本次任务的提示词里。
八、安全与成本意识
始终在最小必要权限下工作。涉及删除、批量更新、迁移、发布或外部调用时，要求先展示计划和受影响范围，再由人确认执行。使用真实环境前，优先在测试环境验证。
对于调用量较大的任务，可以先让 Codex 做只读分析和小范围验证，确认方向正确后再扩展。这样既节省时间，也能避免大面积返工。
结语
Codex 的价值不在于替代工程判断，而在于缩短理解代码、编写重复工作和验证改动的时间。把任务讲清楚、把边界写清楚、把验证做扎实，你就能把它稳定地融入日常开发流程。