codex 架构总览

源码版本rust-v0.145.0

codex 是 OpenAI 的开源编码 Agent,这一版是 Rust 重写(早期 TypeScript 版已退居 codex-cli/ 仅作 npm 安装壳)。源码主体在 codex-rs/,是一个 Cargo workspace,下挂 90+ 独立 crate,按职责切分极细。本站按 crate 分层拆解,每个关键文件都带 SrcLink 直链到 GitHub 对应行。

整体分层

主要 crate 一览

分层	crate	职责
CLI 入口	`cli`	子命令分发、doctor、login、mcp_cmd
Agent 核心	`core`	Agent 主循环、LLM 客户端、压缩、会话线程、工具
补丁协议	`apply-patch`	apply_patch 文本补丁格式
沙箱	`sandboxing` / `linux-sandbox` / `bwrap` / `windows-sandbox-rs`	跨平台命令隔离
执行策略	`execpolicy`	命令分类与放行策略
执行	`exec` / `exec-server`	命令执行与 exec-server 协议
TUI	`tui`	终端 UI、chatwidget、diff_model
App-server	`app-server` / `app-server-protocol` / `app-server-transport`	编排服务与协议
MCP	`mcp-server` / `rmcp-client` / `codex-mcp` / `connectors`	Model Context Protocol 集成
Provider	`model-provider` / `model-provider-info` / `backend-client`	模型 provider 抽象
Cloud	`cloud-tasks` / `cloud-config`	云端任务执行
配置	`config` / `codex-home`	配置系统与 home 目录
周边	`prompts` / `skills` / `memories` / `hooks` / `plugin` / `rollout`	提示词、技能、记忆、钩子、插件、trace

每层一句话

CLI 入口:codex 命令的子命令分发,main.rs 用 clap 解析后路由到各子命令。
Agent 核心:Agent 主循环消费 Op,驱动 LLM 调用与工具执行,CodexThread 是会话编排的入口。
Sandbox 执行:命令在沙箱里跑,execpolicy 先分类命令决定放行/拦截/审批,再交给平台沙箱隔离。
TUI/App-server:TUI 是终端前端,App-server 把 Agent 能力以协议暴露给 IDE/外部客户端。
Provider/Cloud:model-provider 抽象不同后端,cloud-tasks 把任务丢到云端跑。

设计动机

codex 选 Rust 重写,核心动机是沙箱与性能。编码 Agent 要跑用户机器上的任意 shell 命令,没有可靠的进程隔离就没有安全可言;Rust 的类型系统和零成本抽象让 90+ crate 的细粒度切分不会带来运行时开销。workspace 按职责切 crate,而不是一个大 crate,是为了编译增量和边界清晰——改 TUI 不会重编 core。

常见误读

「codex 是个 CLI 工具」——对一半。CLI 只是入口,真正能跑的是 core + sandbox + tui/app-server 三层组合。
「Rust 重写是为了快」——Rust 带来的是沙箱隔离和进程级安全,性能是副产品。
「apply_patch 是 codex 的私有格式」——是 codex 用的文本补丁协议,模型生成、apply-patch crate 解析应用。

codex 架构总览 ​

整体分层 ​

主要 crate 一览 ​

每层一句话 ​

设计动机 ​

常见误读 ​

推荐阅读顺序 ​