什么是 Codex CLI
Codex CLI 是 OpenAI 推出的开源命令行 AI 编程智能体。它直接运行在你的终端里，能读取项目代码、理解需求、自动编写与修改文件、执行命令并验证结果。与网页版对话式 AI 不同，Codex 是"动手型"的：你描述目标，它负责实现。
它特别适合以下场景：
- 从零搭建项目脚手架（前端、Node.js、Python 均可）
- 在现有代码库中定位并修复 Bug
- 批量重构、补充测试、编写文档
- 嵌入式开发中生成外设驱动、解析协议、编写测试用例
安装与登录
前提：已安装 Node.js 18 及以上版本。
# 全局安装
npm install -g @openai/codex
# 查看版本，确认安装成功
codex --version
# 启动并登录 OpenAI 账号（ChatGPT Plus / Pro / Team 席位可直接使用）
codex
首次运行会引导你在浏览器完成 OAuth 登录。如果你习惯使用 API Key 认证，也可以设置环境变量（接入中转站的方式见本站另一篇教程）。
三种审批模式
Codex 的核心安全机制是审批模式，决定了它能自主做多少事：
| 模式 | 读文件 | 改文件 | 执行命令 |
|---|---|---|---|
| Suggest（默认） | ✅ | 需确认 | 需确认 |
| Auto Edit | ✅ | 自动 | 需确认 |
| Full Auto | ✅ | 自动 | 自动（沙箱内） |
建议新手从默认的 Suggest 模式开始，熟悉后再逐步放开权限。在沙箱机制保护下，Full Auto 适合大批量机械性修改，例如批量替换 API、统一代码风格。
日常使用：像带新人一样下需求
启动后直接用自然语言描述任务即可：
# 交互式进入当前项目
cd my-project && codex
# 也可以单次执行
codex "阅读 src/utils 目录，把所有回调风格的函数重写为 Promise 风格，保持导出不变"
高效使用 Codex 的几个要点：
- 目标明确：说清"做什么、在哪做、验收标准是什么"，而不是只丢一个报错
- 小步快跑：把大任务拆成多个小任务，每步验证后再继续
- 及时纠偏：发现方向不对立即按 Esc 中断，补充约束后重试
- 利用版本控制：让 Codex 工作前先 commit，出问题随时回滚
用 AGENTS.md 固化项目约定
在项目根目录创建 AGENTS.md，Codex 每次启动都会自动读取。相当于给智能体一份"入职手册"：
# 项目说明
- 技术栈：Vue 3 + Vite + Node.js/Express
- 组件使用 <script setup> 写法，样式使用 scoped
- 提交信息遵循 Conventional Commits
# 嵌入式子项目 firmware/
- 基于 STM32 HAL 库（F103C8T6）
- 所有中断服务函数中禁止调用 malloc 与 printf
- 修改外设配置后需同步更新 README 中的引脚分配表
有了这份文件，Codex 生成的代码会明显更贴合团队规范，返工率大幅下降。
在嵌入式场景中的使用建议
Codex 同样能胜任嵌入式工作，但要注意边界：
- 擅长：生成 UART/SPI/I2C 初始化模板、解析帧协议、写上位机脚本、解释寄存器手册
- 需人工确认：中断时序、硬件相关的延时与 volatile、电源与时钟树配置——这些依赖具体硬件，AI 给出的代码必须对照数据手册核验
小结
Codex CLI 把"对话式 AI"变成了"结对编程工程师"。记住三件事：装好后先用 Suggest 模式建立信任、用 AGENTS.md 沉淀项目约定、把大任务拆小逐步推进。下一篇实战教程中，我们会用它完整走一遍 STM32 嵌入式项目的开发流程。