OpenAI Codex 源码深度研究

这份研究覆盖 OpenAI Codex CLI / Rust 主体 / TS+Python SDK 全貌：2 篇总纲 + 25 章正文 + 3 个附录，约 51 万中文字 / 1.5 MB Markdown 与 149 张 Mermaid 架构图。

系列研究

本研究是 AI Agent / Coding Harness 源码深度研究系列的一部分，姊妹篇：

• Claude Code 源码解析 — Anthropic Claude Code v2.1.88 完整 Agent Harness 拆解（30 篇 / 23 个子系统 / 179 张架构图）
• Hermes Agent 深度研究 — Hermes Agent + 4 个同源/对比项目（OpenClaw / EvoMap / OpenHarness / JiuwenClaw），含抄袭分析（38 篇 / 32 章 / 97 张架构图）
• OpenClaw 源码深度研究 — 358k Stars OpenClaw v2026.4.15 源码 + 23k commits + 生态调研

引言

OpenAI Codex 在 2025–2026 年从一个早期 TS 原型重写为以 Rust 为主体的多入口 harness：

• codex-cli（npm）— 跨平台启动器，把请求转交给原生二进制
• codex-rs（Rust workspace，~120 个 crate）— 真正的核心：CLI、TUI、Agent 循环、App-Server JSON-RPC、沙箱、Plugin 市场、MCP、Cloud Tasks
• sdk/typescript 与 sdk/python — 通过 spawn CLI 或 App-Server JSON-RPC 暴露给外部应用

本研究分三部分对其进行系统性源码层面解析：
Part I 使用方法与原理（8 章）
Part II 源码解析（13 章）
Part III 对比与延展（4 章）

生成流程采用三阶段写作：

• 第一稿：GPT-5.3 Codex High（章节 01-15 + 总纲 + 全网调研）/ Claude Opus 4.7 Thinking High（章节 16-25）
• review 与优化升级：Claude Opus 4.7 Thinking High 对 17 篇做源码引用核验 + 七维框架补全 + Mermaid 加固
• 最终质量检测：GPT-5.5 High 对全 27 篇做 Mermaid 合规、跨章一致性、措辞审慎度收束

研究结构

总纲

文档	内容
总纲 — Codex 技术主线分析	核心机制、设计哲学、火爆原因、整体架构
全网调研 — 社区认知地图	中英文社区技术分析索引、观点争议、认知盲区

Part I 使用方法与原理（8 章）

序号	章节	关键源码
01	项目全景与设计哲学	codex-rs/Cargo.toml、AGENTS.md
02	多入口与启动分发	codex-cli/bin/codex.js、codex-rs/cli/src/main.rs、arg0/
03	配置系统与企业要求	core/src/config/mod.rs、cloud-requirements/
04	初级使用方法	docs/getting-started.md、login/
05	高级使用方法	cloud-tasks/、cli/src/mcp_cmd.rs、debug_sandbox.rs
06	Agent 核心循环	core/src/session/mod.rs、turn.rs
07	Prompt 组装与 Skill 注入	core/gpt_5_codex_prompt.md、core-skills/
08	Provider 与 Responses/Realtime API	model-provider/、codex-api/、realtime-webrtc/

Part II 源码解析（13 章）

序号	章节	关键源码
09	工具系统总览	tools/、core/src/tools/handlers/
10	命令执行与 unified_exec	core/src/exec.rs、shell-command/parse_command.rs
11	apply_patch 工具	apply-patch/
12	macOS Seatbelt 与 Linux Bwrap 沙箱	sandboxing/、linux-sandbox/、bwrap/
13	Windows 沙箱与 WFP 防火墙	windows-sandbox-rs/
14	执行策略 Starlark execpolicy	execpolicy/、execpolicy-legacy/
15	网络代理与策略	network-proxy/
16	Hook 与生命周期事件	hooks/
17	Plugin 市场系统	core-plugins/
18	MCP 双向集成	codex-mcp/、rmcp-client/、mcp-server/
19	会话与轨迹持久化	rollout/、rollout-trace/、thread-store/、state/
20	记忆系统	memories/{read,write,mcp}/、state/runtime/memories.rs
21	App-Server JSON-RPC 协议层	protocol/、app-server/、app-server-protocol/v2/

Part III 对比与延展（4 章）

序号	章节	关键源码
22	TUI 渲染管线与 Code Mode V8	tui/、code-mode/
23	Cloud Tasks 与外部 Agent 迁移	cloud-tasks/、external-agent-migration/、agent-graph-store/
24	Codex vs Claude Code / Opencode 架构对比	横向对比
25	Codex 沙箱与权限模型 vs 同类	沙箱与权限模型横评

附录

文档	内容
附录 A	章节配置元数据
附录 B	核心 struct/enum/trait 速查表
附录 C	参考文献与引用来源

---

源码基线

项目	规模	语言
codex-rs	~120 crate	Rust
codex-cli	npm 启动器	TypeScript / Node
sdk/typescript	App-Server / spawn 客户端	TypeScript
sdk/python	App-Server / spawn 客户端 (含 generated 模型)	Python
docs	16 篇官方文档	Markdown

三大量级集群（行数）

Crate	LOC
codex-rs/tui	193,863
codex-rs/core	151,372
codex-rs/app-server	39,229
codex-rs/core-plugins	21,197
codex-rs/windows-sandbox-rs	15,902
codex-rs/state	15,480

研究规模

维度	数量
总文档数	30 (README + 2 总纲 + 25 章 + 3 附录)
总字节数	~1.54 MB
中文字数（估计）	~51 万字
Mermaid 图表	149 张
平均每章字数	~17,000 字

怎么读

• 15 分钟掌握全貌：先读 总纲
• 快速上手：Part I 第 4-5 章
• 理解架构：Part I 第 6-8 章 + Part II 第 21 章（App-Server 协议层）
• 沙箱与权限专题：Part II 第 12-15 章 + Part III 第 25 章
• 协议演进：Part II 第 18 章 (MCP) + 第 21 章 (App-Server) + Part III 第 22 章 (Code Mode V8)
• 横向研究：Part III 第 24-25 章

工程化

# 校验所有 Mermaid 图表语法
npm install
npm run validate:mermaid

当前所有 mermaid 块（149 张架构 / 流程 / 时序 / 状态 / ER 图）均通过 mermaid@11.x 解析。

写作方法论

本研究遵循 source-deep-research 7 阶段工作流：

阶段 1  通读源码，建立 25 章骨架（chapters.yaml）
阶段 2  全网调研，建立外部认知基线（全网调研.md）
阶段 3  设计七维结构化 Prompt 集
阶段 4  cursor-agent 串行批量生成（GPT-5.3 Codex / Opus 4.7）
阶段 5  Opus 4.7 review + 改进；GPT-5.5 最终质量检测
阶段 6  系统化整理（README / 章节编号 / 文风 / 图表）
阶段 7  开源发布

每章遵循"七维分析框架"：本质 → 核心痛点 → 解决思路 → 实现细节 → 易错点 → 竞品对比 → 仍存缺陷。

许可

本研究内容采用 CC BY-SA 4.0 许可证。所分析的源码版权归 OpenAI 所有。