Codex 源码电子书（41 章）
读者优先，不是代码优先。按产品误区和工程分层拆 openai/codex，不按 crate 名排目录。
源码仓库：openai/codex。真正干活的代码在 codex-rs/。官方产品文档在 developers.openai.com/codex；仓库里 docs/ 大量只是跳转，以官网为准。
本书对齐 codex-rs @ 944d6fd1 (2026-09-12)。 行号会随重构漂移；对不上时按文件名和符号名重新定位，别信本书里的具体行号胜过当前源码。
这本电子书教的是：2025+ 这个 Agent harness 为什么这样拆，以及你自己做时该抄哪几层。 不是 API 手册，也不是提 PR 指南——上游仓库不接受外部代码 PR。
适合谁 / 不适合谁
- 适合：已经懂「模型调用工具」，想对着 OpenAI Codex 源码建立 coding agent harness 的工程分层（主循环、工具、沙箱、上下文、扩展），并带走可抄切片。
- 不适合：只想用 TypeScript 跟练最小闭环——请先 实践篇；OpenCode 主书概念入口见 什么是 AI Agent。
跨线入口
- 概念校准对照：什么是 AI Agent
- 工具协议对照：OpenCode 工具系统
- Runtime 对照：Hermes Agent 拆解
- Harness 对照：DeepSeek Harness 拆解
- 判断力专栏：Claude Code 架构思维
- 动手：P1 / P10 ReAct
- 源码仓库：openai/codex
怎么读
新读者或者第一次接触 agent harness 概念的人，先扫一眼 术语表 混个脸熟——不用记，读到生词回来查就行。这本书本身写给已经懂"模型调用工具"这类通用概念的工程师，术语表是补那道台阶，不是替你从零讲 agent 是什么。
| 你的目的 | 读法 |
|---|---|
| 自己做一个 coding agent | A0–A2 站稳，B1–B7 必抄，G1 G2 补推理与落盘，附录 F 钉一枪，F2–F3 收束 |
| 搞清产品家族和账号能力 | A1，再按需翻 E |
| 读仓库为什么代码在、默认看不见 | G4 |
| 给项目写说明书 / 配扩展 | C1，然后 D1–D4 |
| 对照 TUI / CI / IDE | E1，协议和 daemon 看 G3，细节回 B1 |
| 第一周最小切片 | 直接看 F3 |
目录按阅读职责排，不是字母序：G（抄 harness 绕不开的层）在 F（收束）前面。
一次只消化一章。正文引用写成 path:line，对着仓库打开，不在这里贴完整函数。行号会随重构漂移，对不上时按文件名和符号名重新定位。
目录
A. 地图
| 章 | 文件 | 读完应带走的判断 |
|---|---|---|
| A0 | A0-这份拆解怎么读.md | 同名不同物；开源的是客户端 harness，不是整个 Codex 产品 |
| A1 | A1-产品家族.md | 六个入口不是六套 Agent；API Key / 本地 provider 能跑循环，没有 Codex 后端 |
| A2 | A2-一次任务的生命周期.md | Thread 活着，Turn 干活，Step 采样；/side 不是协议 fork |
B. 内核（做 Agent 必抄）
| 章 | 文件 | 读完应带走的判断 |
|---|---|---|
| B1 | B1-主循环与事件总线.md | 智能在 Session 的 SQ/EQ 上；EventMsg 按职分流；oneshot 不是 Event |
| B2 | B2-工具系统.md | 模型看见的和机器执行的必须拆开；产品能力挂 Extension，不往 core 焊 Handler；默认 exec 是可恢复 PTY |
| B3 | B3-沙箱审批与ExecPolicy.md | 能力是 permission profile；三档只是内置档案；--yolo 只给外层已隔离的环境 |
| B4 | B4-上下文装配与压缩.md | 模型看见的必须能从 fragment 和 rollout 重建；compact 是替换起点，不是改过去 |
| B5 | B5-配置鉴权与持久化.md | 身份在 CODEX_HOME；几条登录路进同一只 AuthManager；JSONL 是会话真相 |
| B6 | B6-执行环境与exec-server.md | 执行后端可以是另一台机器；审批和 profile 仍在本机 Orchestrator |
| B7 | B7-一枪采样与指令栈.md | 一枪是 Prompt 三块；指令栈谁常驻谁点名；失败不是一种 retry |
C. 行为、记忆与个性化
| 章 | 文件 | 读完应带走的判断 |
|---|---|---|
| C1 | C1-AGENTS项目说明书.md | 说明书是短而可执行的项目政策；正本是 AGENTS.md，fallback 才去读 CLAUDE.md |
| C2 | C2-Memories跨会话记忆.md | 默关的本机笔记；读/写两套开关；不替代 AGENTS.md |
| C3 | C3-Chronicle与Computer-History.md | 采集器写扩展文件，不是第二条 Turn；截屏预览已被交互事件替换 |
| C4 | C4-Personality语气.md | 只改指令里的语气段；Friendly/Pragmatic 已不再换模板，None 才剥掉那一节 |
| C5 | C5-Plan与Goal.md | /plan 是先调查再改；/goal 是 thread 上的完成条件；并行 Goal 配 worktree |
D. 扩展层
| 章 | 文件 | 读完应带走的判断 |
|---|---|---|
| D1 | D1-Skills.md | Skill 是说明书包：先目录后正文；目录变了推 skills/changed，当前枪仍冻住 |
| D2 | D2-Plugins.md | Plugin 是安装单元，不是进程内 Extension；一份 plugin.json 打包四件套，MCP 可单独关 |
| D3 | D3-MCP与Apps.md | Codex 是 MCP client；stdio 启动即执行；嵌 Codex 走 app-server |
| D4 | D4-Hooks.md | 同步 hook 用 exit 2 或 JSON 拦截；项目 hook 过未信任闸，脚本还要过哈希 |
| D5 | D5-Subagents.md | 默认不主动拆；角色只能减权；V2 是另一套协议，不是 V1 换皮 |
E. 产品表面
| 章 | 文件 | 读完应带走的判断 |
|---|---|---|
| E1 | E1-多前端.md | 同一只 app-server 插座；TUI overlay、exec 守 stdout、SDK 只适配 |
| E2 | E2-Worktrees与Local-environments.md | 隔离单位是第二份 checkout；一条 worktree 绑一条 thread |
| E3 | E3-Cloud与Remote.md | 云端不在这棵树里跑；Remote 是看本机 app-server；缝是 git apply |
| E4 | E4-Computer-Use.md | 看点打是桌面插件；OS 辅助功能 ≠ 应用白名单 ≠ Seatbelt |
| E5 | E5-感知通道.md | 搜、看、听、贴图都是进 fragment 的通道；看见不等于能写 |
| E6 | E6-Review与Git.md | /review 是减权只读会话；Guardian 拦工具；/diff 只给人看 |
| E7 | E7-Automations.md | 时刻表叫醒 harness；默认后台 worktree；调度器不在 core |
| E8 | E8-Pets宠物.md | 四态只投影 Session；Kitty/Sixel 才画得出；不准进 ToolRouter |
| E9 | E9-IDE与桌面特有UX.md | 选区和行内 diff 是投影；/import 迁 Claude/Cursor 配置 |
| E10 | E10-TUI-slash命令总表.md | slash 只是菜单；无 /personality；/pet 是 /pets 别名 |
| E11 | E11-Codex-Security.md | 找洞产品 ≠ /review ≠ Guardian；/codex/security 不是沙箱文档 |
G. 抄 harness 绕不开的层
| 章 | 文件 | 读完应带走的判断 |
|---|---|---|
| G1 | G1-推理栈与Responses客户端.md | Prompt 是合同；打出去是 turn-scoped 的 Responses 客户端，不是一个 URL |
| G2 | G2-会话持久化与Thread-Store.md | JSONL 重建上下文；Thread Store 做列表、分页、持久队列 |
| G3 | G3-App-server与Daemon.md | 多前端共用 v2 插座；TUI 只探测已有 socket，不默默 Start |
| G4 | G4-Feature-Flags.md | 有效开关来自注册表和合并链，不是一份 [features] |
| G5 | G5-协作模式.md | 模式是 developer 说明书预设；不是子代理，不是 /side |
| G6 | G6-Network-Proxy.md | 双门闩 + allowlist；limited 只许 GET/HEAD/OPTIONS；升出沙箱就绕过代理 |
F. 收束
| 章 | 文件 | 读完应带走的判断 |
|---|---|---|
| F1 | F1-分层对照表.md | 十层各答一个问题；进 git 的是政策，不是账号和记忆 |
| F2 | F2-可抄清单与反模式.md | 先抄总线、Prompt、PTY、三套旋钮；--yolo、项目 MCP 自启、记忆当政策是反模式 |
| F3 | F3-周末最小切片.md | P0 交出可审批的 patch + 可恢复 exec + Event 流；宠物和插件市场不进第一周 |
| F4 | F4-源码与官方入口.md | 源码 > 官网 > docs/ 跳转；sandbox.md 链的是 Security 产品页 |
附录
| 章 | 文件 | 读完应带走的判断 |
|---|---|---|
| A | 附录A-Guardian评审员Session.md | 隔离的同步评审员；替代的是部分「人点 Allow」，不是沙箱 |
| B | 附录B-unified_exec长进程.md | 管的是可恢复 PTY；启动冻沙箱，stdin 再审；Unix zsh-fork 用 socket 升权，不拆终端 |
| C | 附录C-远程compact-v2.md | 压缩是 provider 能力；流最多 2 次重试；64k 保留窗，图片整块留 |
| D | 附录D-code-mode.md | 模型写 JS 编排工具；V8 无 I/O；嵌套 call 仍过 Orchestrator |
| E | 附录E-apply-patch文法.md | Lark freeform：三种 hunk；按内容匹配；shell 拦截走同一解析器 |
| F | 附录F-一枪采样解剖.md | 一枪是 Prompt 三块；流才重试；用 test_codex 钉文件和 Event |
写作约定
- 先判断，再给文件行号。
- 每个关键设计都写「如果没有这一层会怎样」。
- 章末只带走一句判断，不列提纲式总结。
- 产品能力以当时源码和官网为准；E7 触发器、模型名等会变，正文会标明「以当时产品为准」。
读完这一章，下一步做什么
- Hermes Agent 拆解
OpenCode 拆解 · 想通过真实 Agent 源码建立运行时工程直觉的开发者
- DeepSeek Harness 拆解
OpenCode 拆解 · 想通过真实 Harness 源码看清可替换能力边界的开发者
- Claude Code 架构思维
OpenCode 拆解 · 想系统建立 Agent 工程判断力的开发者
- /practice/
继续沿学习路径进入下一章或对应入口。