精读：Codex 架构演进（TypeScript → Rust）

2025 年 4 月 OpenAI 以 TypeScript/Node.js 开源 Codex CLI；2025 年 6 月宣布 Rust 全面重写；2026 年 3 月代码库已 95.7% Rust。这是开源 AI Agent 领域最大规模的语言迁移之一。

演进总览

2025.4          2025.6          2025.12         2026.3          2026.6
  │               │               │               │               │
  ▼               ▼               ▼               ▼               ▼
TypeScript ──→ Rust 启动 ───→ 核心完成 ────→ 95.7% Rust ──→ 124 crates
(Node.js)     (codex-rs/)    (沙箱/TUI)     (主分支切换)    (v0.142.0)
  │               │               │               │               │
ink/React     Ratatui        Landlock       全平台沙箱      MCP+Multi-Agent
npm 分发       Cargo WS       seccomp BPF    原生二进制       Subagents GA

Phase 1：TypeScript 原型（2025.4 – 2025.6）

技术栈

初始架构

codex/
├── src/
│   ├── cli.ts          # 命令行入口
│   ├── agent.ts        # Agent Loop
│   ├── tools/          # 内置工具
│   ├── ui/             # Ink 组件
│   └── sandbox/        # 简单进程隔离
├── package.json
└── tsconfig.json

局限性

Phase 2：Rust 重写启动（2025.6 – 2025.9）

重写动机（官方声明）

1. 零依赖安装：用户不需要 Node.js、npm 或任何运行时
2. 原生安全绑定：直接调用 OS 内核 API（Seatbelt SBPL / Landlock / seccomp）
3. 无 GC 性能：确定性延迟，终端交互零卡顿
4. 单二进制分发：一个文件搞定，busybox 风格 argv[0] dispatch
5. 可扩展协议层：JSON-RPC 2.0 的高性能实现

初始 Crate 规划

codex-rs/
├── codex-core/         # Agent 核心库
├── codex-cli/          # 命令行入口
├── codex-tui/          # Ratatui 终端 UI
├── codex-sandbox/      # 统一沙箱编排
├── apply-patch/        # 文件补丁
└── shell-command-safety/ # 命令安全策略

迁移策略

渐进式迁移（非 Big Bang）：

1. 先重写安全关键路径（沙箱、命令安全）
2. 再重写核心 Agent Loop
3. 最后重写 UI 层
4. 保留 TypeScript 作为 npm shim 入口（兼容已有安装方式）

Phase 3：核心完成（2025.9 – 2025.12）

里程碑

沙箱实现（Rust 原生）

// 伪代码：Linux 沙箱组合
fn create_sandbox(policy: &ExecPolicy) -> Sandbox {
    let mut sb = Sandbox::new();
    
    // Layer 1: Landlock（文件系统隔离）
    sb.add_landlock_rules(policy.allowed_paths());
    
    // Layer 2: seccomp BPF（系统调用过滤）
    sb.add_seccomp_filter(policy.allowed_syscalls());
    
    // Layer 3: Bubblewrap（命名空间隔离）
    sb.wrap_with_bubblewrap(policy.namespace_config());
    
    sb
}

Rust 的优势在此体现：

• 直接操作 prctl() / seccomp() 系统调用
• 零开销抽象：沙箱策略在编译期部分确定
• 内存安全：沙箱逻辑不会因 buffer overflow 被绕过

Phase 4：主分支切换（2026.1 – 2026.3）

代码占比变化

Crate 爆发期

从初始 5 个 crate 扩展到 80-90 个：

codex-rs/                        (2026.3 状态)
├── codex-core/                  # 可复用 Agent 库
├── codex-cli/                   # CLI 入口 + busybox dispatch
├── codex-tui/                   # Ratatui 终端 UI
├── codex-sandbox/               # 统一沙箱编排层
├── codex-app-server/            # JSON-RPC 2.0 App Server
├── codex-mcp/                   # MCP Server 实现
├── codex-hooks/                 # 生命周期钩子
├── codex-analytics/             # 遥测分析
├── apply-patch/                 # 文件补丁应用
├── shell-command-safety/        # 命令安全策略
├── context-fragments/           # 上下文碎片管理
├── cloud-tasks/                 # 云端任务
├── thread-storage/              # 会话持久化
├── model-providers/             # 模型提供商抽象
├── auth/                        # 认证模块
├── config/                      # 配置管理
└── ... (70+ 其他 crate)

10-15 commits/天

2026 年 3 月的开发节奏：

• 每天 10-15 commits 合入主分支
• 多个团队并行开发不同 crate
• CI 全平台交叉编译（macOS/Linux/Windows × arm64/x86_64）

Phase 5：成熟期（2026.4 – 2026.6）

当前状态

新增关键 Crate

架构设计决策

决策 1：Cargo Workspace Monorepo

选择：单仓库 + Cargo Workspace（所有 crate 在一个 repo）

原因：

• 统一版本管理（workspace-level dependencies）
• 原子提交（跨 crate 改动一次 PR）
• 共享 CI 配置
• 社区贡献门槛低（clone 一次全部可用）

对比：Claude Code 也是单仓库，但无法分享（闭源）。

决策 2：Busybox 风格分发

# 单二进制，通过 argv[0] 决定行为
codex          # 主 CLI
codex-sandbox  # 沙箱工具
codex-mcp      # MCP 模式

原因：

• 安装极简（下载一个文件）
• 避免 PATH 污染
• 嵌入式部署友好

决策 3：保留 TypeScript npm shim

虽然核心全部 Rust，但仍保留 @openai/codex npm 包：

• npm shim 检测平台 → 下载对应原生二进制
• 兼容已有安装习惯（npm i -g @openai/codex）
• 渐进迁移用户（不 break 已有工作流）

决策 4：Ratatui 而非 Crossterm 原生

选择：用 Ratatui（Rust TUI 框架）而非直接操作终端。

原因：

• 声明式 UI（类似 React 模型，熟悉度高）
• 丰富组件库（表格、图表、滚动、布局）
• 社区活跃（bug 修复快）
• 跨平台终端兼容

决策 5：ExecPolicy 命令分类

enum ExecPolicy {
    /// 已知安全命令，自动执行
    Safe,
    /// 需要审批的命令
    NeedsApproval,
    /// 已知危险命令，拒绝执行
    Dangerous,
    /// 未知命令，根据沙箱策略决定
    Unknown(SandboxLevel),
}

在 Rust 类型系统中编码安全策略，编译器保证不会遗漏分支。

性能对比（TS vs Rust）

开源治理演进

对 AI Agent 生态的启示

1. “用 Rust 重写”不是噱头

Codex 的 Rust 重写带来了实质性的安全和性能提升。沙箱直接调用内核 API 是 TypeScript 无法实现的。这验证了”AI Agent 的基础设施层适合系统语言”的论断。

2. 开源 + 快速迭代可以共存

10-15 commits/天 + Apache-2.0 + 92K Stars 证明了高速闭源开发和开源社区参与并不矛盾。关键在于：清晰的贡献指南 + 快速的 PR review + 合理的 crate 边界。

3. Monorepo 适合 Agent 系统

Agent 系统天然涉及多层（核心/工具/UI/安全/扩展），Monorepo 保证：

• 接口一致性（共享 trait 定义）
• 原子变更（跨层重构不 break）
• 统一测试（集成测试覆盖全链路）

交叉引用

• Codex 总架构 — 四层架构 + run_turn
• Codex 沙箱与安全 — Seatbelt/Landlock 详解
• Codex 工具循环 — ExecPolicy 在 Rust 中的实现
• Claude Code 版本演进 — 对比演进路径
• Claude Code vs Codex 全维度对比 — 语言选择差异