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 一覽 ​

每層一句話 ​

設計動機 ​

常見誤讀 ​

推薦閱讀順序 ​