实战教程
Codex 基础版教程:四种形态与 30 分钟快速入门
面向新手的 Codex 基础教程,先讲清 Codex 是什么、四种使用形态的差异,再带你用 App、CLI、IDE、Cloud 跑通第一条可执行工作流。
这篇给第一次系统使用 Codex 的开发者准备,目标只有一个:
用最短路径跑通一条可执行工作流,而不是只会提问。
建议阅读顺序:
- 先看这篇基础版(30 分钟)
- 再看进阶版(60 分钟)
- 最后进入 CLI 实战与自动化
1. Codex 到底是什么?
一句话版本:
Codex 不是“代码补全工具”,而是能在真实项目上下文里做推理、执行和验证的开发代理。
你会明显感觉到它和普通工具的区别:
- 复杂任务前会先思考,不会马上吐一段拼凑代码
- 能围绕仓库结构给出整体方案
- 更容易一次输出可落地结果,而不是连续打补丁
2. 四种形态怎么选?
| 形态 | 适合谁 | 一句话建议 |
|---|---|---|
| Codex App | 需要并行处理多个任务的人 | 默认选它,尤其是 Worktree 模式 |
| CLI | 终端重度用户、要做自动化的人 | 最灵活,最适合脚本化和 CI |
| IDE 扩展 | 长时间在编辑器里写代码的人 | 不切窗口,交互成本最低 |
| Cloud | 任务长、机器资源紧张的人 | 放后台跑,完成后再审 diff |
新手默认路径:
- macOS 用户优先 App
- 非 macOS 或偏脚本化优先 CLI
- 长任务交给 Cloud
如果你还不能确定,先按任务选择:需要查看和审查多个改动选 App,需要批量执行命令选 CLI,需要边写代码边提问选 IDE,需要长时间运行且不想占用本机选 Cloud。第一次不要同时配置四种形态,先跑通一种再迁移配置。
3. 先跑通第一条工作流(建议照抄)
第一步:定义边界
请先输出分步计划,不要直接改代码。
每一步必须包含:目标、影响文件、风险、验证、回滚。
第二步:让 Codex理解仓库
请总结这个仓库的模块结构,并标记本次改动不应该触碰的目录。
第三步:执行最小改动
请先给最小可行改动,不要一次性大改。
改完后给我验证命令和回滚命令。
第四步:验证
至少执行:
- 功能验证
- 回归验证
- 测试/静态检查
一个合格的最小任务应该能在十分钟内完成验证,例如让 Codex 为一个已有函数补充边界测试。验证时记录三项结果:实际修改的文件、测试命令及退出码、仍需人工确认的风险。如果结果不符合预期,先停止继续改动,回到上一版 diff 分析原因。
4. Worktree 为什么值得默认开启?
你可以理解为“每个任务都有独立沙盒分支”:
- 不会污染当前主线开发
- 支持并行做多个任务
- 失败后清理成本低
如果你在 Codex App 里工作,建议新线程优先选 Worktree 模式。
5. 新手最容易踩的 5 个坑
- 提示词只写“帮我改一下”,没有边界
- 一次要求太多目标,结果失焦
- 不限制改动目录,导致误改
- 跳过验证,直接提交
- 把 Codex 当最终审核人,而不是执行助手
6. 常见问题与排查
- Codex 找不到项目文件:先运行
pwd和目录列表,确认启动目录是仓库根目录,并检查是否被忽略规则排除。 - 改动范围过大:要求它先输出计划,并限定“只允许修改某个目录”;完成后立刻查看
git diff --stat。 - 命令执行失败:保留完整报错、运行目录和版本信息,再让 Codex 解释原因,不要只复制最后一行。
- 结果看似正确但无法发布:先运行项目现有构建和测试,再检查生成文件、环境变量和部署脚本。
7. 下一步怎么进阶?
看完这篇后,按这个顺序继续:
常见问题
Codex 新手应该先用 App 还是 CLI?
需要图形界面、并行处理任务时先用 App;习惯终端、需要脚本化或 CI 时先用 CLI。两者使用同一项目时,先确认工作目录和配置文件来源。
第一次让 Codex 改代码前要做什么?
先提交或备份当前改动,明确允许修改的目录,再让 Codex 先输出计划和验证命令。完成后检查 diff、运行项目测试,并确认没有生成密钥或临时文件。