🩺 摘要
📝 详情
Codex CLI入门教程：OpenAI的99K星代码代理，三分钟上手
省流版： Codex CLI是OpenAI开源的轻量级代码代理工具，GitHub 99,270星，14,856 forks——增速极快。它直接在终端运行，能理解整个代码仓库、自动执行命令、支持多文件编辑。安装只要npm install -g @openai/codex，三分钟就能跑起来。
99K星意味着什么？
2026年7月，Codex CLI的GitHub星数已经接近10万。从0到99K，只用了不到一年。
对比一下：Aider是47K，LangChain是100K（但LangChain做了很多年，而Codex CLI是个工具，不是框架）。这个增速说明终端AI代码代理的需求比想象中大得多。
但Codex CLI最特别的地方不是它的星数——是它的设计哲学。
Codex CLI的设计哲学：Sandbox First
用过其他AI编程工具的人都知道一个痛点：AI改完代码，你不敢直接上生产。
Codex CLI解决这个问题的方式很聪明——Sandbox沙箱模式。
默认情况下，Codex CLI会： 1. 在沙箱里执行代码修改 2. 所有文件改动都在沙箱内进行 3. 你review确认后，改动才同步到真实工作区 4. 测试也在沙箱里跑，不影响你的本地环境
这个机制是目前所有AI编程工具中最安全的。
安装
前置条件
- Node.js 18+
- npm
- OpenAI API密钥（或Codex OAuth）
安装步骤
npm install -g @openai/codex
验证：
codex --version
# 输出类似：0.3.1
身份验证
两种方式：
方式一：OpenAI API密钥
export OPENAI_API_KEY="sk-..."
方式二：Codex OAuth（推荐）
codex auth login
浏览器会打开OAuth页面，登录OpenAI账号即可。
三分钟快速上手
第一步：进入Git仓库
Codex CLI必须运行在Git仓库中（设计上要求版本控制）。
cd ~/my-project
如果是新项目，先初始化：
mkdir test-project && cd test-project
git init
第二步：用Codex写代码
codex exec "创建一个Python Flask应用，包含用户注册和登录功能"
Codex会：
- 分析项目现有结构
- 创建必要的文件（app.py、models.py、requirements.txt等）
- 在沙箱里运行测试
- 提示你确认改动
- 确认后写入文件
第三步：Review改动
git diff
可以看到Codex帮你改了哪些文件、加了哪些代码。每个commit都有清晰的描述。
核心工作模式
Codex CLI有三种运行模式：
1. 普通模式（默认）
codex exec "你的任务描述"
沙箱模式。代码先改在沙箱里，你会看到diff，确认后才写入。适合日常工作，推荐。
2. 全自动模式
codex exec --full-auto "你的任务描述"
依然是沙箱模式，但自动确认文件改动。适合你信任Codex执行简单任务。注意：--full-auto只自动确认文件写入，不会自动运行危险命令。
3. YOLO模式（慎用）
codex exec --yolo "你的任务描述"
没有沙箱，没有确认，直接改。最快但最危险。适合你100%确定Codex不会搞乱的情况——比如生成一个新的脚手架项目。
使用建议： 日常开发用普通模式，批量修改用--full-auto，生成新项目用YOLO。
实战场景
场景1：修bug
codex exec "登录接口在传空密码时报500，需要返回400，并加上密码校验"
Codex会找到对应的视图函数、修改逻辑、加校验、写测试。
场景2：重构
codex exec "把views.py里的用户相关逻辑拆分到users/目录下，保持原有路由不变"
涉及的文件：可能需要新建目录、拆分文件、修改import、更新路由。
场景3：加新功能
codex exec "给文章系统添加'草稿'状态：发布前先在草稿箱，管理员审核后才能发布"
这会涉及到模型字段、业务逻辑、视图函数、测试。
场景4：写测试
codex exec "用pytest给auth模块写单元测试，覆盖率90%以上"
Codex会分析现有模块，自动生成测试用例。
AGENTS.md：团队共享上下文
Codex CLI有一个非常实用的功能——AGENTS.md。
在项目根目录放一个AGENTS.md文件，告诉Codex你的项目习惯：
# 项目编码规范
## 技术栈
- Flask 3.x + PostgreSQL
- SQLAlchemy 2.0（异步模式）
- pytest + coverage
## 代码风格
- Python 3.12+类型注解
- Black格式化（100字符行宽）
- docstring用Google风格
## 测试要求
- 每个public函数都要有测试
- db操作使用fixture而不是mock
- 测试文件命名：test_{module}.py
## 部署相关
- Docker构建，多阶段构建
- Gunicorn启动，4 worker
- nginx反向代理
Codex CLI会在每次任务中自动读取这个文件。一个文件，团队所有人都能受益。
Codex CLI vs Codex IDE 插件
很多人分不清这两个：
| Codex CLI | Codex IDE插件 | |
|---|---|---|
| 运行环境 | 终端 | VS Code / Cursor / Windsurf |
| 安装 | npm install -g @openai/codex |
IDE扩展市场安装 |
| 能力 | 完整的代码代理 | 代码补全+内联修改 |
| 沙箱 | ✅ 内置 | ❌ |
| 自动Git | ✅ 自动commit | ❌ 手动操作 |
| 全库理解 | ✅ 扫描仓库 | ✅ 但受限于编辑器 |
| 适用 | 自动开发/重构/代码审查 | 日常编码辅助 |
简单说： CLI版是给你干活的，IDE版是给你辅助的。两个互补，不冲突。
Codex CLI的局限
没有工具是完美的，Codex CLI也一样。
1. 只支持OpenAI模型
这是最大的限制。你不能用Claude、DeepSeek或其他模型。这是设计上的选择（毕竟是OpenAI自家的），但也是用户吐槽最多的地方。
2. 只能跑在Git仓库里
如果代码不在Git，需要用git init建一个。额外一步。
3. 首次启动较慢
首次运行时，Codex需要下载模型配置和建立索引。大约需要30秒。
4. 大型项目上下文管理
100+文件的项目，Codex的上下文管理不如Aider成熟。建议分模块操作。
什么时候该用Codex CLI？
- ✅ 你已经是OpenAI的用户，API密钥在手
- ✅ 你习惯终端操作，不用IDE
- ✅ 你需要安全的沙箱模式
-
✅ 你想让AI自动完成代码审查
-
❌ 如果你想用Claude或其他模型
- ❌ 如果你不做Git版本控制
- ❌ 如果你需要编辑器里的实时补全
总结
Codex CLI以99K+星的社区热度证明了一个道理：开发者真正需要的是安全可控的AI编程助手，而不是一个黑盒。
它最强的三点：
- 沙箱模式——安全第一，AI改完你review后再落地
- AGENTS.md——团队规范一次配置，所有任务自动遵守
- 极简安装——一个npm命令，三分钟跑起来
如果你已经在用OpenAI的模型，Codex CLI是你终端里最顺手的AI编程搭档。
💡 建议收藏本文。 Codex CLI的更新很快，但核心操作——exec命令和AGENTS.md配置——学会了就不会变。
📤 转发给朋友，他肯定会感谢你。 99K星的工具，错过真的太可惜。
📚 AI编码工具系列 ← （一）Aider AI编程助手入门 · （二）Aider进阶配置 → （三）OpenCode vs Aider vs Claude Code：三款终端AI编程助手横评 → （四）AI代码文档自动生成指南 · （五）AI辅助代码迁移实战
💬 评论 (0)