Codex 源码解读
逐层拆读 OpenAI 开源的终端编码 Agent Codex CLI 的 Rust 源码（rust-v0.158.0）——从 app-server 架构、agent 内核、工具与沙箱，到扩展机制与终端界面，一边讲怎么用，一边讲怎么实现。
Codex 源码解读
Codex CLI（命令行叫 codex）是 OpenAI 开源的终端编码 Agent：在你本机的终端里阅读代码、修改文件、执行命令、调用 MCP 工具，也能用 codex exec 嵌进脚本和 CI。它的主体是 codex-rs/ 下的一个 Rust Cargo workspace，显式列出的成员有 153 个、约 190 万行代码（去掉测试约 82 万行，口径见下文“源码基准”）。
这个专栏把它逐层拆开读。
这个专栏怎么读
每一章尽量走两条线：
- 怎么用——这个功能在
codex里长什么样。详细用法站里已经有一本 《Codex 中文手册》，这里只点到为止，并链接到手册的对应页面； - 怎么实现——翻到对应 crate 的源码，看它在底层到底怎么做。
侧重结构与数据流：讲清“一件事经过哪些 crate、哪些类型、数据怎么流、边界契约是什么”，而不是逐行贴代码——关键处才引一小段源码点睛。每段摘录都原样取自源码，并在下方注明 路径:行号。
和《从 LLM 到 Coding Agent》配对
站里的 《从 LLM 到 Coding Agent》 讲“一个 Coding Agent 在裸 LLM API 之上该做哪些事”，配了一个从零手搓的教学实现。这本则是同一件事的生产实现：agent 循环、工具、上下文、权限、扩展……教学实现让你看清骨架，生产实现让你看清骨架周围要长出多少东西。不少章节末尾有“和《从 LLM 到 Coding Agent》对照”一节，两边对照着读，收获最大。
同一组里还有 《Grok Build 源码解读》、《OpenCode 源码解读》 等几本同类专栏，最后一部分会把它们放在一起比较。
读者预设：默认你懂一点 Rust（读得下 async、trait、Arc、workspace 分层），知道 tokio 是什么。不熟的语言点会在关键处就地补一句，但不系统教 Rust。读过《Codex 中文手册》会更顺，但不是硬前提。
源码基准
本专栏所有引用以下述快照为准：
| 项 | 值 |
|---|---|
| 仓库 | github.com/openai/codex |
| 版本 | Codex CLI 0.158.0（tag rust-v0.158.0，2026-09-28 发布） |
| commit | 064c6b8c737f5b41d171fdda80bd9ef10ad06eb3（提交日期 2026-09-27） |
| 许可 | Apache-2.0 |
| workspace | codex-rs/Cargo.toml 的 members 显式列出 153 个；另有 5 个 crate（windows-sandbox-rs、chatgpt、message-history 与两个测试支撑 crate）作为路径依赖被 Cargo 自动纳入。crate 名是目录名加 codex- 前缀（如 core 即 codex-core） |
| 代码量 | 153 个显式成员共 4,770 个 .rs 文件、约 190 万物理行；去掉测试（tests.rs、*_tests.rs、tests/ 目录与 #[cfg(test)] 块）约 82 万行。自动纳入的 5 个另有约 3.1 万行非测试代码，其中 windows-sandbox-rs 约 1.9 万行 |
| 最大的几个 crate | tui 约 20.6 万行、core 约 11.4 万行、app-server 约 4.4 万行（均为去掉测试后） |
所有路径都相对仓库根，例如 codex-rs/core/src/session/turn.rs；文中指向 GitHub 的源码链接都固定在 rust-v0.158.0 标签上。《Codex 中文手册》也以同一版本为基准。
路线图
- 第 0 部分 · 导论与全景——Codex CLI 开源的是哪一部分、怎么从源码构建、153 个 workspace 成员怎么分层、读源码前要知道的工程约定，以及贯穿全书的主线：一条消息从按下回车到看到回复的全过程。
- 第 1 部分 · app-server 与线程——终端界面、
codex exec、IDE 与桌面客户端共用的 app-server、它的 v2 协议、守护进程与各种传输，线程的生命周期与会话持久化。 - 第 2 部分 · Agent 内核——Session 与每轮配置、
run_turn主循环、模型客户端、只追加的上下文历史、压缩、指令组装、模型目录与提供方、任务类型与 Plan 模式。 - 第 3 部分 · 工具系统——工具的暴露、注册、路由与并行，命令执行与 unified exec、命令解析与安全判断、
apply_patch、MCP 工具调用、其它内置工具与 Code mode。 - 第 4 部分 · 安全：权限、审批与沙箱——权限模型、审批流程，macOS、Linux、Windows 三套沙箱，网络代理、执行策略与自动审查。
- 第 5 部分 · 扩展机制——配置系统、Skills、Hooks、插件、MCP 客户端、多 agent、扩展 API、记忆，以及从别的 agent 迁移过来。
- 第 6 部分 · 终端 UI——TUI 架构、输入框、历史记录单元与流式渲染、全屏对话记录与其它界面。
- 第 7 部分 · 运行形态与工程——exec-server、登录认证、实时语音、遥测、Codex Cloud 与代码审查，以及测试、构建与发布。
- 第 8 部分 · 收尾——对照《从 LLM 到 Coding Agent》复盘，与 Grok Build、OpenCode 横向比较，读完之后怎么继续。
准备好了，就从 Codex CLI 是什么 开始。