实战教程

Codex 基础版教程:四种形态与 30 分钟快速入门

发布时间: 2026-02-24 · 更新于: 2026-11-01

面向新手的 Codex 基础教程,先讲清 Codex 是什么、四种使用形态的差异,再带你用 App、CLI、IDE、Cloud 跑通第一条可执行工作流。

这篇给第一次系统使用 Codex 的开发者准备,目标只有一个:

用最短路径跑通一条可执行工作流,而不是只会提问。

建议阅读顺序:

  1. 先看这篇基础版(30 分钟)
  2. 再看进阶版(60 分钟)
  3. 最后进入 CLI 实战与自动化

1. Codex 到底是什么?

一句话版本:

Codex 不是“代码补全工具”,而是能在真实项目上下文里做推理、执行和验证的开发代理。

你会明显感觉到它和普通工具的区别:

  • 复杂任务前会先思考,不会马上吐一段拼凑代码
  • 能围绕仓库结构给出整体方案
  • 更容易一次输出可落地结果,而不是连续打补丁

2. 四种形态怎么选?

形态 适合谁 一句话建议
Codex App 需要并行处理多个任务的人 默认选它,尤其是 Worktree 模式
CLI 终端重度用户、要做自动化的人 最灵活,最适合脚本化和 CI
IDE 扩展 长时间在编辑器里写代码的人 不切窗口,交互成本最低
Cloud 任务长、机器资源紧张的人 放后台跑,完成后再审 diff

新手默认路径:

  • macOS 用户优先 App
  • 非 macOS 或偏脚本化优先 CLI
  • 长任务交给 Cloud

如果你还不能确定,先按任务选择:需要查看和审查多个改动选 App,需要批量执行命令选 CLI,需要边写代码边提问选 IDE,需要长时间运行且不想占用本机选 Cloud。第一次不要同时配置四种形态,先跑通一种再迁移配置。

3. 先跑通第一条工作流(建议照抄)

第一步:定义边界

请先输出分步计划,不要直接改代码。
每一步必须包含:目标、影响文件、风险、验证、回滚。

第二步:让 Codex理解仓库

请总结这个仓库的模块结构,并标记本次改动不应该触碰的目录。

第三步:执行最小改动

请先给最小可行改动,不要一次性大改。
改完后给我验证命令和回滚命令。

第四步:验证

至少执行:

  1. 功能验证
  2. 回归验证
  3. 测试/静态检查

一个合格的最小任务应该能在十分钟内完成验证,例如让 Codex 为一个已有函数补充边界测试。验证时记录三项结果:实际修改的文件、测试命令及退出码、仍需人工确认的风险。如果结果不符合预期,先停止继续改动,回到上一版 diff 分析原因。

4. Worktree 为什么值得默认开启?

你可以理解为“每个任务都有独立沙盒分支”:

  • 不会污染当前主线开发
  • 支持并行做多个任务
  • 失败后清理成本低

如果你在 Codex App 里工作,建议新线程优先选 Worktree 模式。

5. 新手最容易踩的 5 个坑

  1. 提示词只写“帮我改一下”,没有边界
  2. 一次要求太多目标,结果失焦
  3. 不限制改动目录,导致误改
  4. 跳过验证,直接提交
  5. 把 Codex 当最终审核人,而不是执行助手

6. 常见问题与排查

  • Codex 找不到项目文件:先运行 pwd 和目录列表,确认启动目录是仓库根目录,并检查是否被忽略规则排除。
  • 改动范围过大:要求它先输出计划,并限定“只允许修改某个目录”;完成后立刻查看 git diff --stat。
  • 命令执行失败:保留完整报错、运行目录和版本信息,再让 Codex 解释原因,不要只复制最后一行。
  • 结果看似正确但无法发布:先运行项目现有构建和测试,再检查生成文件、环境变量和部署脚本。

7. 下一步怎么进阶?

看完这篇后,按这个顺序继续:

  1. Codex 进阶教程:配置系统、提示词工程与生产级实战
  2. Codex CLI 实战教程:从需求到落地的完整工作流
  3. Codex CLI 自动化实战:批量任务与可回滚脚本

常见问题

Codex 新手应该先用 App 还是 CLI?

需要图形界面、并行处理任务时先用 App;习惯终端、需要脚本化或 CI 时先用 CLI。两者使用同一项目时,先确认工作目录和配置文件来源。

第一次让 Codex 改代码前要做什么?

先提交或备份当前改动,明确允许修改的目录,再让 Codex 先输出计划和验证命令。完成后检查 diff、运行项目测试,并确认没有生成密钥或临时文件。