Codex 架构与 Rust Core 入口解析

util6大约 3 分钟

Codex 架构与 Rust Core 入口解析

1. 整体架构设计：Node/JS CLI 与 Rust Core 的双层协作

Codex 采用了区别于 OpenCode (纯 TypeScript) 和 Claude Code (TypeScript + 深度混淆打包) 的双层架构设计：

CLI / UI 前端层 (codex-cli)：负责命令行终端交互、终端渲染 (TUI)、提示词预处理、用户输入补全以及向后台 Core 发起 RPC / IPC 通信。
Rust Core 核心层 (codex-rs)：采用 Rust 编写，承载了完整的 Agent Loop、模型请求调度、上下文压缩、受控沙箱隔离、MCP 客户端适配以及全量会话持久化。

┌─────────────────────────────────────────────────────────┐
│                    codex-cli (Node.js)                  │
│   • TUI / CLI 交互    • IPC 通信      • 用户环境适配       │
└────────────────────────────┬────────────────────────────┘
                             │ Stdio / IPC / AppServer Protocol
┌────────────────────────────▼────────────────────────────┐
│                    codex-rs (Rust Core)                 │
│                                                         │
│  ┌──────────────────┐   ┌────────────────────────────┐  │
│  │  ThreadManager   │───▶│ CodexThread (Turn Loop)    │  │
│  └─────────┬────────┘   └──────────────┬─────────────┘  │
│            │                           │                │
│  ┌─────────▼────────┐   ┌──────────────▼─────────────┐  │
│  │ Sandboxing/Exec  │   │  rmcp-client (MCP Host)    │  │
│  └──────────────────┘   └────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

与 OpenCode 和 Claude Code 相比，Codex 将计算密集型、多线程并发管理以及系统级的安全沙箱全盘交由 Rust Core 实现，保障了高响应速率与跨平台的硬隔离安全性。

2. Rust Core 核心模块与入口点

位于 ~/fork-code/codex/codex-rs 的核心代码结构清晰地划分为多个专用 crate 与子系统：

Crate / 模块	源码路径	核心职责
`codex-rs/core`	[`codex-rs/core/src/lib.rs`](file:///Users/util6/fork-code/codex/codex-rs/core/src/lib.rs)	Agent 核心逻辑，包含 Session, Thread, Turn 管理
`client`	[`codex-rs/core/src/client.rs`](file:///Users/util6/fork-code/codex/codex-rs/core/src/client.rs)	OpenAI / Codex Backend API 通信引擎
`thread_manager`	[`codex-rs/core/src/thread_manager.rs`](file:///Users/util6/fork-code/codex/codex-rs/core/src/thread_manager.rs)	会话线程生命周期与多 Thread 调度控制器
`codex_thread`	[`codex-rs/core/src/codex_thread.rs`](file:///Users/util6/fork-code/codex/codex-rs/core/src/codex_thread.rs)	单会话 Turn 循环、状态轮转与 Steer 控制
`sandboxing`	[`codex-rs/sandboxing`](file:///Users/util6/fork-code/codex/codex-rs/sandboxing)	跨平台系统级沙箱（Linux Bubblewrap / macOS Landlock / Windows Restricted Token）
`rmcp-client`	[`codex-rs/rmcp-client`](file:///Users/util6/fork-code/codex/codex-rs/rmcp-client)	高性能 MCP 协议客户端实现

3. ThreadManager 与 CodexThread 事件主循环

Codex 的 Agent 主循环基于 Rust Tokio 异步运行时，采用基于通道 (mpsc channel) 和状态机 (AgentStatus) 驱动的事件响应架构。

3.1 会话线程管理 (`ThreadManager`)

在 [codex-rs/core/src/thread_manager.rs](file:///Users/util6/fork-code/codex/codex-rs/core/src/thread_manager.rs) 中，ThreadManager 负责管理所有活跃的 CodexThread。它提供会话分支创建 (Forking)、会话切换、历史恢复以及线程间的内存隔离。

3.2 单线程 Turn 事件循环 (`CodexThread`)

在 [codex-rs/core/src/codex_thread.rs](file:///Users/util6/fork-code/codex/codex-rs/core/src/codex_thread.rs) 中，每个 CodexThread 维护了一个 ThreadConfigSnapshot 和一个异步任务处理队列：

// codex-rs/core/src/codex_thread.rs
pub struct ThreadConfigSnapshot {
    pub model: String,
    pub model_provider_id: String,
    pub approval_policy: AskForApproval,
    pub approvals_reviewer: ApprovalsReviewer,
    pub permission_profile: PermissionProfile,
    pub workspace_roots: Vec&lt;AbsolutePathBuf&gt;,
    pub reasoning_effort: Option&lt;ReasoningEffort&gt;,
    pub collaboration_mode: CollaborationMode,
    // ...
}

Turn 推进流程：

输入接收 (Submission)：用户输入或系统 Trigger 通过 submit_user_input 投递到消息通道。
状态评估与抢占：try_start_turn_if_idle 检查当前 AgentStatus。若处于可启动状态，锁定 Idle 信号并分配新的 Turn ID。
Prompt 组装与模型调用：从 ThreadStore 拉取上文上下文，经过 compact.rs 压缩后向 Backend Client 发起流式 Token 响应请求。
工具提取与审批分派：当模型返回 tool_calls 时，核心捕获工具并推送到 exec_policy.rs 进行规则判定。若符合审批策略则向 CLI / TUI 发送 AskForApproval 事件。
异步工具执行与结果回传：在沙箱内完成命令执行或 MCP 调用，将结果封装为 ResponseItem 塞回上下文，开启下一次蒸馏循环。

4. 架构优势总结

类型安全与零成本抽象：基于 Rust 的所有权与类型系统，绝无 Node.js 中常见的异步竞争条件与内存泄漏风险。
严格的沙箱控制前置：在进入工具执行前，由 Rust Core 原生注入沙箱和安全规则，无需依赖宿主 JS 进程补全权限。
极致的响应效能：内存占用小，序列化与 JSON 文本流处理比 JavaScript 快数倍。