第一次会话：在示例项目中完成一项小改动

安装与登录完成后，本节带你在一个示例项目里跑通 Codex CLI 的第一次完整会话：先只读探索，再进入计划模式确认方案，最后放行一处小改动并由你审查、验证、决定去留。Codex 采用"代理循环（agent loop）"的工作方式：它会反复地读取项目、形成计划、尝试执行、根据结果调整，直到任务完成。理解这个循环，并在每个审批节点把好关，是后续使用 Codex 的基础。本节命令以 OpenAI 官方 CLI 为准。

一、选择练习项目并做开工检查

和任何终端编程代理一样，第一次使用 Codex 也要选一个安全、可回滚的练习项目。开始前完成三项检查：

1. 确认项目在 Git 管理之下。执行 git status，保证工作区干净，改动可以随时回退。
2. 选择体量小、技术栈清楚的示例仓库。项目内最好能看到依赖清单、入口文件与测试命令，便于对照 Codex 的汇报逐项核实。
3. 从只读任务开始。第一轮消息只要求浏览与说明，明确"不要修改代码"，等理解一致后再谈改动。

二、启动会话并下达只读探索指令

进入项目目录后启动交互式会话：

cd ~/projects/your-project
codex

会话启动后，先发送一条只读探索任务，让 Codex 摸清项目全貌：

先浏览这个项目，不要修改任何文件。请告诉我：
1. 项目用途与主要技术栈；
2. 目录结构和各目录职责；
3. 安装、构建、运行与测试命令分别是什么；
4. 主要入口文件位置；
5. 你阅读时发现的明显约定或潜在问题。
回答时请标注对应的文件路径。

在代理循环中，Codex 会先调用工具列出目录、读取配置与源码，再汇总成回答。你重点观察：它读取的路径是否覆盖了项目主干，技术栈判断是否与依赖清单一致，给出的命令能否在真实配置里找到依据。

三、核对第一份项目分析

拿到分析后，用三个动作快速判断它是否真的理解了项目：

核对项	具体做法	判断标准
路径真实性	随机打开分析中引用的一两个文件	文件存在，内容与描述吻合
命令准确性	对照 package.json、脚本配置等清单	构建与测试命令真实存在，而非凭语言类型猜测
结论依据	检查它对代码风格、缺测试等判断的来源	结论来自实际阅读，不是空泛评价

若分析与实际不符，直接在会话中指出并要求它重新核对。只读阶段纠正偏差，比改动之后再返工成本低得多。

四、进入计划模式：先出方案，再动手

对小改动任务，推荐先让 Codex 在计划模式中给出方案，而不是直接允许它写代码。计划模式下，Codex 专注于调研与设计修改步骤，不立即改动磁盘文件。你可以这样表达：

接下来我希望做一处小改动，请先进入计划模式，不要写代码。
任务：为 src/ 目录下的某个工具函数补充参数与返回值的类型注释，保持现有行为不变。
请先给出：你准备修改哪些文件、每处改动的思路、如何验证行为没有变化。我确认方案后，你再开始修改。

审阅计划时重点看三点：改动文件清单是否必要且克制、实现思路是否符合项目现有风格、验证方式是否可执行。方案超出你设想的范围，就在会话中收窄边界后再让它继续。计划模式与审批策略的完整档位，会在下一章结合会话界面系统讲解。

五、下达范围明确的小改动任务

计划确认后，再让 Codex 执行改动。新手第一个任务务必满足"小、独立、可验证"：补充注释、统一文案、修复一处格式问题、为工具函数补类型说明等。指令里写清背景、目标、约束与验收标准：

请按刚才确认的方案执行，只修改指定的那个文件：
背景：该工具函数缺少类型注释与说明文档。
目标：补充参数、返回值类型注释与简要说明，不改变函数逻辑。
约束：不重命名、不调整其他函数、不新增依赖、不改动其他文件。
验收：项目测试命令执行通过；最终 diff 只包含注释与类型说明相关内容。

六、理解代理循环与审批节点

放行改动后，Codex 会在代理循环中连续执行：读取相关文件 → 编辑代码 → 尝试运行构建或测试 → 根据报错继续调整。每当它需要执行写入、安装依赖或运行命令时，会话会向你请求审批。你在每个节点核对：

• 文件路径：准备修改的文件是否在约定清单内；
• 命令内容：执行的是不是构建、测试、读取类低风险操作；安装新包、删除文件、访问网络等动作要单独判断；
• 改动目标：当前动作是否仍服务于已确认的计划，有没有在循环中偏离任务。

七、审查 diff 并运行验证

任务完成后，进入人工审查环节，这一步不能省略：

1. 执行 git status，确认改动文件数量符合预期，没有多出意外文件；
2. 执行 git diff，逐段核对每处修改都服务于原任务，没有夹带重构、改命名或逻辑调整；
3. 阅读 Codex 给出的改动说明，与实际差异比对是否一致；
4. 运行项目测试命令；有启动命令的项目，启动后人工确认相关功能正常。测试不通过，就把报错贴回会话让它继续修正。

八、接受、回滚与提交

验证通过后，由你本人决定是否保留改动：

# 查看改动范围与差异
git status
git diff

# 确认无误后按项目规范提交
git add .
git commit -m "docs: 补充工具函数类型注释与文档说明"

# 不满意时整体回退到改动前状态
git restore .

提交始终由你来完成，Codex 负责在授权范围内执行与修改。第一次练习即使选择全部回滚，也不影响后续继续使用。

九、第一次会话的标准节奏对照

阶段	你的动作	Codex 的动作	审查重点
只读探索	下达只读指令	浏览目录、读取配置与源码并汇总分析	路径真实、命令准确、理解无偏差
计划确认	要求先出方案并收窄范围	调研后输出修改计划，暂不写文件	文件清单克制、思路符合项目风格
执行改动	逐节点审批写文件与命令	代理循环中编辑、运行、根据反馈调整	动作不越界，命令内容可解释
审查验证	看 diff、跑测试、提出问题	根据反馈继续修正	差异干净、测试通过
收尾决策	提交保留或整体回滚	结束本次会话	最终状态与任务目标一致

十、新手常见误区

• 跳过计划直接改代码：没有方案基线，后面很难判断代理是否越界。
• 任务范围写得太宽："把代码优化一下"这类指令容易触发大面积改动，必须限定到文件与函数。
• 习惯性批量放行审批：审批节点是控制边界的闸门，每条命令都应看清内容。
• 不运行测试就接受：即使是注释类改动，涉及逻辑时验证步骤不能省。
• 一个会话塞入多个不相关任务：任务越聚焦，代理循环越稳定，审查也越容易。