架构概览 — 概念

Cargo Workspace 组织

Codex 使用 Cargo workspace 管理 119 个 crate，按职责划分为以下层次：

各 crate 在 workspace 中的核心职责：

层次	Crate	核心类型	职责
界面	`cli`	`MultitoolCli`	参数解析，子命令分发（exec/review/login/mcp 等 25+ 子命令）
界面	`tui`	`App`, `ChatWidget`	基于 [[glossary/ratatui
界面	`exec`	`Cli`, `EventProcessor`	非交互执行，JSON/文本输出，自动拒绝交互请求
协议	`app-server-protocol`	`ClientRequest`(60+ 变体)	JSON-RPC 请求/通知定义，序列化作用域
协议	`app-server`	`MessageProcessor`	请求处理，线程状态管理，传输层
核心	`core`	`Codex`, `CodexThread`	会话状态机，代理循环，上下文管理
核心	`protocol`	`EventMsg`(60+ 变体)	跨 crate 共享的类型定义
核心	`config`	`CloudConfigBundle`	TOML + 云端 + CLI 分层配置
沙箱	`sandboxing`	`SandboxManager`	跨平台沙箱抽象与命令变换
工具	`codex-mcp`	`McpConnectionManager`	[[glossary/mcp
工具	`apply-patch`	`StreamingPatchParser`	`*** Begin Patch` 格式解析与原子应用

分层架构

Codex 的架构遵循严格的分层隔离原则，所有二进制通过 app-server protocol（App Server Protocol）与代理运行时通信：

关键设计决策：

所有界面共享同一协议：无论是 TUI、Exec 还是 SDK，都通过 App Server Protocol 与核心通信，确保行为一致性
Codex struct 是队列对：tx_sub: Sender<Submission> 提交操作，rx_event: Receiver<Event> 接收事件，实现了完全异步的事件驱动架构
CodexThread 是外部接口：包装 Codex 提供更高级的 submit()/next_event() API，管理会话配置快照（ThreadConfigSnapshot）
平台沙箱透明切换：SandboxManager::transform() 根据平台自动选择 Seatbelt（macOS）、Landlock+Bwrap（Linux）或 Restricted Token（Windows）

数据流

从用户输入到最终执行的完整数据流：

数据流中的关键节点：

节点	处理逻辑	源码位置
CLI 入口	`MultitoolCli` 解析参数，选择子命令	`codex-rs/cli/src/main.rs`
模式分发	无子命令 → TUI，`exec` → Exec，`app-server` → 后台服务	`codex-rs/cli/src/main.rs`
协议传输	JSON-RPC over stdio（嵌入式）或 Unix socket（守护进程）	`app-server-protocol/`
会话启动	`Codex::spawn(CodexSpawnArgs)` 创建队列对和事件循环	`core/src/session/mod.rs`
上下文构建	`build_initial_context()` 拼装 system prompt + 历史 + 工具	`core/src/session/mod.rs`
模型调用	`ModelClientSession::stream()` 通过 WebSocket/SSE 流式请求	`core/src/client.rs`
沙箱执行	`SandboxManager::transform()` 包装命令后在隔离环境执行	`sandboxing/src/manager.rs`

相关概念

Cargo Workspace — 119 个 crate 的 workspace 组织方式
Agent Loop — 核心代理循环的迭代机制
Sandbox — 跨平台沙箱系统
Backend Client — LLM 后端连接管理
App Server Protocol — 界面与核心的通信协议

出链