Codex 101｜00｜Reading Guide

Codex 101 的阅读路线图：从本地 Agent Runtime、工具执行、安全沙箱，到 app-server、状态存储与 SDK。

Codex 101 不是“如何使用 Codex CLI”的教程，也不是按文件顺序展开的实现笔记。它把 Codex 当作一个完整的本地 Agent Runtime 来读：一个命令行入口背后，如何组织用户输入、模型流、工具调用、审批、沙箱、会话状态、TUI、SDK 和云端任务。

如果你想学习的是“一个生产级 coding agent 应该怎样拆层”，这组文章的读法是：先看运行时边界，再看模型闭环，再看工具与安全，最后看产品层和持久化。

本篇目标：这组文章解决什么问题

Codex 为什么不只是一个 CLI，而是本地 Agent Runtime
Codex 代码库里的关键抽象：Thread、Turn、Item、Op、Event、ToolRuntime
读完系列后，能把这些机制迁移到自己的 agent 系统中

顺序	文章	你会学到什么
01–04	Runtime、Protocol、Loop、Streaming	Codex 如何把用户输入推进成模型事件流和工具闭环
05–08	Tool、Sandbox、MCP、Skills/Hooks	模型提出行动后，本地运行时如何执行、审批、隔离和扩展
09–12	App Server、TUI/CLI、State、SDK/Cloud	同一个 agent core 如何被包装成产品、服务和状态系统

系列写法

这组文章会引用 repo-relative 文件作为机制锚点，但不会把文章写成按文件顺序展开的实现笔记。每篇都按同一条线展开：先说明工程问题，再解释 Codex 的边界设计，然后给出可迁移伪实现，最后总结能迁移到其他 agent 系统的原则。

运行示例

为了保持系列连续性，后续文章会反复使用同一个任务作为心智模型：用户让 Codex 修复一个失败测试。这个任务看似简单，却会触发几乎所有关键机制：读取上下文、构造模型请求、流式返回、调用 shell、申请审批、沙箱执行、应用 patch、记录 rollout、更新 TUI、持久化 thread。

如何判断自己读懂了

读完这组文章，不应该只记住 Codex 里有哪些 crate，而应该能回答四个问题：第一，用户输入如何变成 runtime 可处理的操作；第二，模型输出如何变成事件和工具调用；第三，本地执行如何被审批、沙箱和 hooks 包住；第四，会话为什么既需要可回放日志，也需要查询索引。

本系列不做什么

这不是安装教程，不覆盖每一个命令参数，也不会把文章组织成文件树讲解。文件路径只作为机制锚点出现：当一个概念需要落到实现边界时，读者可以顺着 repo-relative 路径继续深挖。

贯穿示例

贯穿示例是“修复一个失败测试”。后续每篇都会从不同角度解释这个任务：01 看它如何穿过本地 runtime，03 看它如何形成多次模型采样，05 看测试命令如何变成工具执行，06 看命令为什么需要审批和沙箱，11 看这段过程如何被写入 rollout 和 state。这样读，系列就不是十三篇分散文章，而是一条完整路径。

关键源代码入口

文件	用途
`README.md`	机制锚点
`codex-rs/README.md`	机制锚点
`codex-rs/Cargo.toml`	机制锚点

小结

建议先读 01–04，建立“用户输入如何变成模型与工具闭环”的主线；再读 05–08，理解工具、安全和扩展生态；最后读 09–12，理解 Codex 如何把同一个 core 包装成 TUI、app-server、SDK、状态系统和 Cloud Tasks。