Codex Harness 深度教程

Codex Harness 深度教程

15 章拆解 OpenAI Codex CLI 的架构设计与实现 —— 一个 102 个 crate、147 万行 Rust 的生产级 agent（智能体）运行外壳

本教程的定位（2026-08-24） 同目录下已有两份 harness 拆解：Pi-Agent 教程拆的是减法哲学（4 个包，刻意不做 MCP / 子 Agent / 权限弹窗），DeepSeek Harness 教程拆的是全插件化（185 个包，连 agent loop 都是配置里的一行）。

Codex 是这道题的第三种答案：不追求最小，也不追求最大可替换性，而是把一个每天被几百万开发者使用的产品该有的东西全部做出来并塞进一个静态二进制里。它的关键词是工程化——协议先行、平台全覆盖、14168 个测试、四套沙箱实现、一个用模型守模型的安全层。

三者不是优劣关系。第 15 章有完整对照。

关于"OpenAI 最近开源了 Codex"这个说法的更正 Codex CLI 的仓库 openai/codex 初始提交是 2025-04-16，从第一天起就是 Apache-2.0 开源，不是最近才开放。本教程核实的时间线：

事件	时间	依据
仓库初始提交	2025-04-16	git log --reverse 首条
codex-rs/core（Rust 重写核心）落地	2025-04-24	该目录首次出现的提交
Guardian 安全层进入仓库	2026-03-15	core/src/guardian/ 首次出现
ext/ 内部扩展平面	2026-05-11	codex-rs/ext/ 首次出现

所以真实情况不是"某天开源了"，而是持续在公开仓库里开发——包括生产系统提示词、Guardian 风险策略、四套沙箱实现这些通常会被藏起来的东西。本教程认为这才是它值得读的原因。

版本与写作方法 本教程基于 openai/codex main 分支 09609ba4（2026-08-24），对照本机安装的 codex-cli 0.146.0。仓库当时的最新 tag 是 rust-v0.149.1 与 rust-v0.150.0-alpha.7。

与 Pi 教程（转载）不同、与 dsh 教程（读打包产物）也不同：本教程读的是原始 Rust 源码——注释、测试、TODO 全在。凡是标注 [源码] 的结论都给了 文件:行号，你可以 clone 仓库当场核对。

一、这套教程解决什么问题

如果你读过前两份 harness 教程，会带着这些问题来看 Codex：

1. 一个 agent harness 做到"产品级"要多少东西？ —— Pi 说 4 个包够了，dsh 说拆成 185 个位置，Codex 的答案是 102 个 crate、147 万行、14168 个测试
2. core 和 UI 怎么解耦才能同时喂饱终端、IDE 插件、桌面 App、MCP 客户端和云端任务？ —— Codex 的答案是一份提交/事件队列协议，前端全是它的消费者
3. 沙箱这种"每个操作系统都不一样"的脏活，认真做是什么样子？ —— macOS Seatbelt、Linux Landlock+seccomp+bwrap、Windows AppContainer，三套独立实现加一层统一抽象
4. 当静态规则拦不住提示词注入时怎么办？ —— Codex 的答案是 Guardian：再上一个模型当判官，风险分类学写成 8KB 的策略提示词放在仓库里

如果你没读过前两份教程，本教程也是自洽的：从第 2 章的工程骨架讲起，不预设你了解任何一个具体 harness，也不要求你会写 Rust（所有代码片段都有中文解读）。

二、章节结构

第一部分 · 骨架
ch01 开篇总览  →  ch02 工程骨架  →  ch03 协议先行
                                        ↓
第二部分 · 主干
ch04 Agent Loop  →  ch05 模型调用  →  ch06 上下文工程  →  ch07 上下文压缩
                                        ↓
ch08 工具系统  →  ch09 命令执行与终端
                                        ↓
第三部分 · 边界
ch10 沙箱  →  ch11 审批与策略（含 Guardian）  →  ch12 会话持久化
                                        ↓
第四部分 · 扩展与总结
ch13 扩展面  →  ch14 多 Agent 委派  →  ch15 设计精华

阅读建议：第 1–4 章是骨架，建议顺序通读——不理解第 3 章的提交/事件队列，后面每一章都会卡住。第 5 章起可按需跳读。第 11 章（Guardian）和第 15 章即使不读源码也值得单独看。

每一章回答三个层次的问题：是什么（概念）、怎么做（源码取证）、为什么这样做（设计取舍）。

三、素材基线：本教程的每个数字从哪来

本教程的所有事实都可以在一台 clone 了仓库的机器上复核。写作时使用的取证路径：

自己动手复核 每章末尾都有「动手复核」小节，给出可直接运行的命令。教程正文里凡标注 [源码] 的结论都出自这些命令能定位到的位置。

起手式：

bash

git clone --filter=blob:none https://github.com/openai/codex.git
cd codex/codex-rs && ls

原始资料索引见 00-资料索引，研究背景与结论摘要见 Codex Harness 研究摘要。

四、和另外两份 harness 教程的关系

第 15 章会把这张表展开成完整的哲学对照，并汇总全书 26 条可迁移的设计判断（其中 10 条标星为优先采纳项），最后给出对本仓的具体启示。

Related Documents

• Pi-Agent 深度教程 —— 减法哲学的对照组
• DeepSeek Harness 深度教程 —— 全插件化的对照组
• Harness Engineering 研究报告 —— harness 工程的行业方法论背景
• Codex Harness 研究摘要 —— 本教程的调研过程与核心结论
• 00-资料索引 —— 官方与第三方原始资料清单