Codex 总架构精读

调研时间：2026-06-22

源码 commit：98845e4（2026-06-22）

本地 CLI：codex-cli 0.125.0

仓库：openai/codex（Apache-2.0）

一句话定位

Codex 是 OpenAI 的生产级开源 Coding Agent 运行时——用 Rust 实现一套统一的 Agent 核心（Codex Core），通过 App Server（JSON-RPC 2.0）对外暴露，让 CLI、IDE 扩展、Web 等多个 Surface 共享同一份 agent loop、工具编排、沙箱隔离和记忆管线。

日常类比

把 Codex 想象成一家全国性银行的 IT 系统：

• Core（核心业务系统）：所有交易逻辑只写一次——转账、风控、审批，不管客户从哪个渠道来
• App Server（统一接口层）：柜台、ATM、手机 App、网银都通过同一套接口与核心对话
• Surfaces（渠道 UI）：柜台是 CLI/TUI，手机 App 是 VS Code 扩展，网银是 Codex Web

类比边界：银行系统是事务制（一次转账完成即止），而 Codex Core 是 turn loop——一轮对话中模型可以反复调用工具、等待审批、再调用，直到 agent 自行判断任务完成。

架构总览

flowchart TB
  subgraph surfaces["Surfaces（UI 渠道）"]
    CLI["TUI / CLI<br/><small>codex-rs/tui</small>"]
    IDE["VS Code Extension<br/><small>codex app-server 客户端</small>"]
    Web["Codex Web<br/><small>chatgpt.com/codex</small>"]
    App["Codex App (Desktop)<br/><small>codex app</small>"]
  end

  subgraph app_server["App Server（协议层）"]
    RPC["JSON-RPC 2.0<br/>stdio / unix socket / ws"]
    TM["Thread Manager<br/>多会话生命周期"]
  end

  subgraph core["Codex Core（agent 引擎）"]
    Session["Session<br/>配置 + 历史 + 状态"]
    Turn["run_turn()<br/>agent 主循环"]
    TO["ToolOrchestrator<br/>审批→沙箱→执行→重试"]
    Compact["Compact<br/>上下文压缩"]
  end

  subgraph sandbox["安全层"]
    SB["SandboxManager"]
    Seatbelt["macOS Seatbelt"]
    BWrap["Linux bubblewrap"]
    Landlock["Linux Landlock"]
    WinSB["Windows Sandbox"]
  end

  subgraph state["持久化"]
    DB[("SQLite State DB<br/><small>codex-rs/state</small>")]
    Mem["~/.codex/memories/<br/><small>git-baseline 文件系统</small>"]
  end

  subgraph extensions["扩展面"]
    MCP["MCP Servers"]
    Skills["Skills + Plugins"]
    Hooks["Hooks<br/>SessionStart / TurnStop / PermissionRequest"]
    MultiAgent["MultiAgentV2<br/>spawn / wait / send"]
  end

  CLI --> RPC
  IDE --> RPC
  Web --> RPC
  App --> RPC
  RPC --> TM
  TM --> Session
  Session --> Turn
  Turn --> TO
  TO --> SB
  SB --> Seatbelt
  SB --> BWrap
  SB --> Landlock
  SB --> WinSB
  Turn --> Compact
  Turn -.-> DB
  Mem -.-> Session
  Turn --> MCP
  Turn --> Skills
  Turn --> Hooks
  Turn --> MultiAgent

核心 Crate 依赖表

Codex Rust workspace 共 120+ crate，下面只列最关键的 7 个层，按依赖方向从上到下：

辅助 crate 速览（不展开精读）：

• tui — 终端 UI 渲染（未来计划全走 App Server）
• cli — 命令行参数解析、codex / codex app-server 入口
• config — 分层配置（内置 → 用户 → 项目），TOML + rules 文件
• hooks — Hook 运行时（JS via V8 PoC、外部进程）
• core-skills — Skills 加载/注入/渲染引擎
• core-plugins — 插件管理（MCP server 贡献者）
• codex-mcp — MCP 协议客户端实现
• exec / exec-server — 进程执行、PTY 管理
• git-utils — memory baseline 的 git 操作

数据流：一次完整的 Turn

从用户输入到 agent 回复，完整经过以下阶段：

┌─────────────────────────────────────────────────────────────┐
│ Surface (VS Code / CLI / Web)                              │
│   用户输入 "帮我重构这个函数"                                │
└──────────────────────────────┬──────────────────────────────┘
                               │ JSON-RPC: turn/start
                               ▼
┌─────────────────────────────────────────────────────────────┐
│ App Server                                                  │
│   validate → find/create Thread → dispatch to Core          │
└──────────────────────────────┬──────────────────────────────┘
                               │ Submission::TurnInput
                               ▼
┌─────────────────────────────────────────────────────────────┐
│ Codex Core: run_turn()                                      │
│                                                             │
│  ┌─── loop ───────────────────────────────────────────┐    │
│  │ 1. 构建 prompt（AGENTS.md + skills + history）       │    │
│  │ 2. stream → model API（responses endpoint）          │    │
│  │ 3. 收到 tool_call?                                   │    │
│  │    ├── YES → ToolOrchestrator                        │    │
│  │    │   ├── ExecPolicy 决策                           │    │
│  │    │   ├── Approval（hook → guardian → user）        │    │
│  │    │   ├── SandboxManager 选择沙箱                   │    │
│  │    │   ├── 执行 tool → 结果回写 history              │    │
│  │    │   └── sandbox 拒绝? escalation 重试             │    │
│  │    └── needs_follow_up = true → continue             │    │
│  │ 4. 收到 end_turn / assistant message                 │    │
│  │    └── needs_follow_up = false → break               │    │
│  │ 5. token limit? → auto compact → continue            │    │
│  └────────────────────────────────────────────────────┘    │
│                                                             │
│  → return last_agent_message                                │
└──────────────────────────────┬──────────────────────────────┘
                               │ Event stream (notifications)
                               ▼
┌─────────────────────────────────────────────────────────────┐
│ App Server → Surface                                        │
│   item/started, item/agentMessage/delta, turn/completed     │
└─────────────────────────────────────────────────────────────┘

关键代码：Agent 主循环

文件：codex-rs/core/src/session/turn.rs

// run_turn 的核心 loop（简化）
loop {
    // 1. 检查是否需要 compact
    if should_compact { run_inline_auto_compact_task(...).await; }

    // 2. 构建 sampling input（含完整 history + system prompt）
    let input = build_sampling_request_input(&sess, &turn_context).await;

    // 3. 流式调用模型 + 处理 tool calls
    let (result, _items) = run_sampling_request(
        &sess, &turn_context, &mut client_session, input, &cancel,
    ).await?;

    // 4. 决定是否继续循环
    if result.needs_follow_up {
        continue; // model 请求了 tool call，循环继续
    } else {
        run_stop_hooks(...).await;
        break;    // 任务完成
    }
}

[源码] try_run_sampling_request 内部使用 FuturesOrdered 并发执行多个 tool call，而非顺序等待——这是 Codex 的 turn 内并行 能力。

核心设计决策

1. Harness 统一，Surface 分离

Codex 的核心洞察：Agent loop 只写一份，所有 UI 通过 App Server 说话 [源码][文档]。

这意味着：

• VS Code 扩展、TUI、Desktop App 不各自实现 agent 逻辑
• App Server 通过 JSON-RPC 提供统一的 Thread/Turn/Item 抽象
• 新增一个 Surface（如 JetBrains 插件）只需实现 JSON-RPC 客户端

对比：Claude Code 各 surface 也共享 core，但 core 是 TS/Bun 实现；Codex 选择 Rust + 显式 IPC 协议层。

2. Turn Loop + 工具级并行

Codex 的编排模型是 turn-by-turn loop（不是有向图）[源码]：

• 每个 turn 内，模型可以请求多个 tool calls，它们并发执行
• 多 agent 通过 MultiAgentV2 工具实现（spawn/wait/send），不是 graph node

这比 LangGraph 的有向图编排更简单，但也意味着编排逻辑完全依赖模型的 tool call 决策。

3. 安全在 OS 层

bubblewrap / Seatbelt / Landlock 是 OS 内核级隔离 [源码]：

• exec policy 做第一道过滤（白名单/黑名单）
• SandboxManager 做第二道执行隔离
• 即使模型”越狱”生成恶意命令，sandbox 仍然拦截文件系统/网络访问

与 Claude Code 的差异（待 Agent A 核对）

具体差异点（公开层面推断）：

• Codex App Server 是一个独立进程/服务，Surface 通过 IPC 连接；Claude Code 的各 surface 更倾向于内嵌 core 库
• Codex exec policy 使用 .rules 文件做声明式白名单；Claude Code 使用 permission classifier 做动态分类
• Codex 的 memory 是 AI pipeline（Phase1 提取 + Phase2 合并）产出文件系统工件；Claude Code 使用 memdir 目录结构
• Codex 多 agent 走 MultiAgentV2 tool（spawn/wait/send 三个工具）；Claude Code 走 Swarm / Dynamic Workflow
• Codex AGENTS.md 从项目根到 cwd 逐层叠加；Claude Code 的 CLAUDE.md 叠加逻辑类似但还有 .claude/rules/ 目录

局限性

• CLI 版本 vs 源码：本地 codex-cli 0.125.0 可能滞后于 HEAD（commit 98845e4），部分实验性功能（如 codex app、realtime-webrtc）可能 CLI 未暴露 [待验证]
• Windows sandbox：windows-sandbox-rs 需要 Windows 10 2004+ 且开启 Windows Sandbox 特性，覆盖率不如 Linux/macOS [源码]
• App Server 稳定性：WebSocket transport 标注为 “experimental and unsupported”，unix socket 是推荐路径 [文档]
• Memory pipeline 异步性：Phase1/Phase2 在后台运行，用户无法同步等待 memory 写入完成；新 session 可能看不到刚结束的 session 的 memory [源码]
• MultiAgentV2 实验性：多 agent 模式依赖 experimentalApi opt-in，API 可能变动 [源码]

证据等级汇总