先别把它当成“会聊天的 IDE”
普通代码补全解决的是下一段代码写什么；聊天式助手解决的是应该怎么做；Coding Agent 还要负责在真实仓库里把事情做完，并拿出可检查的证据。
对 Codex 来说，一次任务不是“一问一答”，而是一段受控执行：
- 接收目标与当前环境；
- 搜索仓库、读取文件、理解约束；
- 向模型发起一次推理；
- 根据模型产生的工具调用执行命令或修改文件；
- 把结果放回上下文，继续推理；
- 运行测试或其他验证；
- 通过事件流向界面报告过程和最终结果。
源码可证实 官方仓库中的 run_turn 明确区分两种模型输出：工具调用会执行并触发下一次采样；普通 assistant 消息则结束本轮。
把一个自然语言目标，可靠地转化为仓库中的可验证结果。
模型负责选择下一步，Runtime 提供上下文、工具、执行环境、状态和事件。
软件任务通常需要多轮观察与纠错，不可能靠一次补全稳定完成。
核心循环位于 codex-rs/core；CLI、TUI、App Server 是不同交互表面。
它仍会误解需求、遗漏约束或做出错误修改；验证和人工控制不能省略。
五个构件，而不是一个模型
flowchart LR G["目标<br/>Goal"] --> R["Runtime<br/>编排与状态"] E["环境<br/>仓库 / OS / Git"] --> R R --> M["Model<br/>选择下一步"] M --> T["Tools<br/>读 / 搜 / Shell / Patch"] T --> E T --> V["Validation<br/>测试 / 构建 / Diff"] V --> R H["Human control<br/>Approval / 指令"] -.约束.-> R
这里最容易混淆的是 Codex 这个名字。公开产品里它可以指多个相连但不同的表面：
| 表面 | 你看见什么 | 主要职责 |
|---|---|---|
| Codex CLI | 终端中的交互与非交互命令 | 把本地仓库、Shell 和 Agent Loop 接起来 |
| Codex App / IDE 集成 | 图形界面、线程、diff、任务状态 | 展示事件、组织任务与人工确认 |
| Codex Cloud | 隔离环境中的远程任务 | 在托管环境中异步执行 |
| Codex SDK / App Server | 可编程接口与协议 | 把同一能力嵌入产品或自动化 |
本教材的源码主线是官方 openai/codex 仓库中的 Rust CLI 与 runtime。产品服务端如何实现不在公开仓库中；遇到这条边界，我们会明确停在可证据化的位置。
与三类常见工具的差别
代码补全：局部概率
补全器通常围绕光标和附近代码预测后续 token。它快、低摩擦，适合重复性实现，但不会天然承担“检查整个仓库—修改多处—运行测试—解释结果”的责任。
聊天助手：建议与生成
聊天助手可以给出高质量方案和代码块，但如果它不能观察真实环境、执行工具并消费结果，那么最后一公里仍由人完成。
Coding Agent：带控制边界的行动循环
Codex 把模型放入一个 runtime：模型的输出可能是消息，也可能是结构化工具调用。工具执行成功、失败、被沙箱拒绝或等待批准，都会变成下一步可观察的信息。
什么任务适合
最适合的是目标可描述、环境可访问、结果可验证的工作，例如：
- 定位并修复一个有复现步骤的 bug；
- 在现有模式下添加一个小功能并补测试；
- 理解陌生模块，产出带路径证据的说明；
- 机械但跨文件的迁移、重命名和配置更新；
- 执行 lint、测试、构建，修复明确失败。
不适合直接全权交付的任务包括：需求本身未决、涉及不可逆生产操作、验证标准缺失、需要未授权凭据，或必须依赖未公开业务背景的决策。
Codex 的交付契约
一个可信的结果至少包含四层：
| 层 | 问题 | 典型证据 |
|---|---|---|
| 理解 | 目标和约束是否正确 | 任务复述、相关文件、假设 |
| 修改 | 实际改变了什么 | patch、文件路径、diff |
| 验证 | 为什么认为它能工作 | 测试、构建、静态检查 |
| 边界 | 什么还没有被证明 | 未运行的环境、缺失凭据、推论 |
读完这套教材的路线
先掌握下一章的 Agent Loop，再沿着一次真实修改理解 Context、Tool、Session 和安全控制。到最后，你会用同一套概念读源码，并实现一个最小的 Coding Agent。