Codex 架构原理详解：从代理到执行的完整旅程

最近心血来潮上手试了试 Codex（用 #Rust 开发的），本来只是想 “摸个新鲜工具” 图一乐，结果玩着玩着就收不住了 —— 不管是补完我写了一半的逻辑代码，还是帮我把一段绕得头晕的业务逻辑注释理得清清楚楚，它给的反馈都比我预想的要机灵，实际用起来的效果，更是给了我好大的惊喜。

Codex 是 OpenAI 开发的一个本地运行的编码智能体，它能够理解用户的自然语言请求，自动生成、测试、执行代码，甚至修复错误。

与传统的代码补全工具不同，Codex 是一个完整的 AI 代理系统，拥有复杂的对话管理、沙箱执行、权限控制等能力。

本文从架构的角度，深入浅出地解释 Codex 如何从一个用户请求出发，最终执行代码并反馈结果的整个过程。

核心概念

在深入架构细节之前，我们需要理解几个关键概念：

1. 会话（Conversation）

• 会话是 Codex 与用户交互的基本单位
• 一个会话包含完整的对话历史、执行记录、审批状态等
• 会话可以被保存、恢复、分享
• 每个会话都有唯一的 ID，并在磁盘上以"Rollout"文件保存

2. 轮次（Turn）

• 一个轮次是用户请求到 AI 响应的完整周期
• 每轮可能包含多个步骤：理解请求 → 生成方案 → 执行命令 → 验证结果 → 迭代

3. 事件流（Event Stream）

• Codex 内部通过异步事件流进行通信
• 从 AI 模型的流式响应，到命令执行的完成，都转换为事件
• UI 层通过订阅事件流来实时更新用户界面

4. 沙箱与权限控制

• 沙箱策略（Sandbox Policy）：控制代码能访问的资源范围
• 批准策略（Approval Policy）：决定哪些命令需要用户手动批准
• 平台特定：macOS 使用 Seatbelt，Linux 使用 Landlock，Windows 使用受限令牌

5. 工具调用（Tool Call）

• AI 模型通过调用工具来执行具体任务
• 工具包括：local_shell（执行命令）、view_image（查看图片）等
• 工具调用遵循 OpenAI 的函数调用 API 规范

整体架构

首先，来看看 Codex 三层架构图：

核心组件详解

1. ConversationManager（会话管理器）

职责：创建和管理会话的生命周期

关键方法：

• new_conversation(config) - 创建新会话
• resume_conversation_from_rollout(path) - 从文件恢复会话
• get_conversation(id) - 获取活跃会话

核心设计：

• 使用 Arc<RwLock<HashMap>> 存储活跃会话，支持并发访问
• 每个会话对应一个 CodexConversation 实例
• 通过 Rollout 文件系统化保存会话历史

2. Codex Engine（核心引擎）

职责：执行整个对话逻辑的核心引擎，是 Codex 的"大脑"

核心流程：

Codex {
    // 初始化阶段
    auth_manager        // 身份验证
    models_manager      // 模型管理
    config              // 配置

    // 会话状态
    session_state       // 当前会话状态
    turn_context        // 当前轮次上下文

    // 事件处理
    event_sender        // 发送事件到客户端
    event_receiver      // 接收用户输入
}

关键方法：

• spawn() - 创建并初始化新的 Codex 实例
• submit(Op) - 提交用户操作（发送消息、批准命令等）
• next_event() - 获取下一个事件
• process_turn() - 处理一个完整轮次

3. TurnContext（轮次上下文）

职责：保存单个轮次的所有上下文信息

包含内容：

TurnContext {
    client              // 与 AI 模型的连接
    cwd                 // 工作目录
    approval_policy     // 批准策略
    sandbox_policy      // 沙箱策略
    tools_config        // 工具配置
    message_history     // 消息历史
    // ... 等等
}

为什么重要：

• 隔离轮次间的状态，避免交叉污染
• 支持轮次级别的可撤销操作
• 便于并行处理多轮请求

4. ToolRouter & Tools（工具系统）

职责：管理和执行 AI 模型调用的各种工具

工具类型：

执行流程：

5. Rollout System（回滚系统）

职责：持久化和检索会话历史

数据结构：

~/.codex/sessions/
├── {conversation_id}.jsonl
│   ├── RolloutItem (事件1)
│   ├── RolloutItem (事件2)
│   └── ... 所有事件的 JSONL 记录
└── metadata.json

JSONL 格式优势：

• 支持流式写入和读取
• 事件原子性和持久性
• 支持快速搜索（索引）

6. ModelClient（模型客户端）

职责：与 OpenAI API 通信，处理流式响应

核心能力：

ModelClient {
    // 支持多种模型
    model: "gpt-5.1-codex-max" / "gpt-4" / ...

    // 支持自定义提供商
    model_provider: OpenAI / LMStudio / Ollama / ...

    // 处理流式 SSE 响应
    ResponseStream {
        delta          // 增量内容
        tool_calls     // 工具调用
        reasoning      // 推理过程
    }
}

两种 Wire API：

1. Chat Completions API（标准）

   • 所有提供商都支持
   • 最稳定、最可靠

2. Responses API（优化）

   • OpenAI 专有，性能更好
   • 支持增量工具调用、推理流

7. Auth System（身份验证）

职责：管理用户身份和 API 密钥

支持的方式：

工作流程

1. 初始化阶段（Session Initialization）

2. 轮次处理（Turn Processing）

这是 Codex 最核心的流程，包含以下步骤：

步骤 1：接收用户输入

步骤 2：构建上下文（Context Building）

关键概念 - 自动压缩（Auto-Compaction）：

• 如果消息历史太长，Codex 会自动总结早期的轮次
• 保留最后 N 轮完整对话，更早的轮次压缩为摘要
• 确保模型始终能看到最相关的上下文

步骤 3：流式处理 AI 响应

步骤 4：工具调用处理

步骤 5：继续推理

步骤 6：轮次完成

3. 完整例子：修复 Lint 错误

关键机制

1. Ghost Snapshot（幽灵快照）

目的：支持"撤销"功能

工作原理：

• 每轮开始前，Codex 捕获文件系统的快照（元数据级别，不复制文件）
• 如果用户对这一轮的结果不满意，可以快速恢复到轮次开始的状态
• 通过 Git 或文件系统级别的快速回滚实现

优势：

• 鼓励用户尝试，降低风险
• 支持自然的试错流程

2. Message History（消息历史管理）

结构：

MessageHistory {
    system_message      // 系统提示词
    base_instructions   // 基础指示
    user_instructions   // 用户自定义指示（AGENTS.md）

    turns: [
        {
            user_messages: [...]     // 用户在这一轮说的话
            assistant_message: ...   // AI 的完整响应
            tool_calls: [...]        // 工具调用记录
            tool_results: [...]      // 工具结果
        }
    ]
}

优化策略：

1. 滑动窗口（Sliding Window）

   • 始终保留最后 N 轮完整对话
   • 更早的轮次被压缩

2. 自动压缩（Auto-Compaction）

   • 定期检查 token 使用量
   • 超过阈值时，调用模型自动总结早期对话
   • 用简洁的总结替换冗长的详细记录

3. 远程压缩（Remote Compaction）

   • 在后台调用 API 进行压缩
   • 不阻塞主对话流

3. Execution Policy（执行策略）

两层检查：

1. 批准策略（Approval Policy）

   AskForApproval {
      Never,           // 完全信任，自动执行
      OnRequest,       // 大多数命令需批准
      OnFailure,       // 只在失败时询问
      Untrusted,       // 所有 shell 命令都需批准
   }

2. 沙箱策略（Sandbox Policy）

   SandboxPolicy {
      ReadOnly,           // 文件系统只读
      WorkspaceWrite,     // 只能写当前工作区
      DangerFullAccess,   // 无限制（危险！）
   }

执行流程：

4. Model Context Protocol (MCP)

新功能：允许 Codex 连接外部工具和数据源

Codex ← MCP Client → MCP Server (Git, Database, APIs)
                   → MCP Server (Web Search)
                   → MCP Server (Custom Tools)

使用场景：

• 集成公司内部工具
• 访问外部 API（GitHub、Jira）
• 使用专业领域知识库

配置示例：

[mcp_servers]
git = { command = "python", args = ["git_mcp_server.py"] }
web_search = { command = "npx", args = ["@example/web-search-mcp"] }

5. Reasoning（推理过程）

支持高级推理模型（如 o1、o3）

三个推理级别：

• Low - 快速、轻量级推理
• Medium - 平衡速度和质量
• High - 深度思考，性能最优

总结

Codex 的架构哲学

1. 事件驱动

   • 所有状态变化都转换为事件
   • 支持多客户端、实时更新

2. 分层隔离

   • 表现层、业务逻辑层、执行层分离
   • 便于扩展和测试

3. 安全第一

   • 沙箱、批准、策略三层防护
   • 用户始终有最终控制权

4. 持久化和恢复

   • 完整的会话记录
   • 支持断点续行

5. 可扩展性

   • 工具系统支持任意扩展
   • MCP 支持第三方集成

核心优势

下一步学习

如果你想深入研究 Codex，推荐按以下顺序：

1. 快速开始：docs/getting-started.md
2. 配置理解：docs/config.md
3. 源码阅读：
   • core/src/codex.rs - 核心引擎
   • core/src/tools/ - 工具系统
   • core/src/sandboxing/ - 沙箱实现
4. 协议：protocol/src/protocol.rs - 事件和消息定义

附录：关键文件映射

codex-rs/
├── core/                      # 核心业务逻辑
│   ├── src/
│   │   ├── codex.rs          # Codex 引擎主体
│   │   ├── conversation_manager.rs  # 会话管理
│   │   ├── tools/            # 工具系统
│   │   ├── sandboxing/       # 沙箱实现
│   │   ├── exec_policy.rs    # 执行策略
│   │   └── rollout/          # 持久化系统
│   └── tests/                # 集成测试
│
├── cli/                       # CLI 入口
│   └── src/main.rs
│
├── tui/                       # 终端 UI（Ratatui）
│   └── src/
│       ├── app.rs            # TUI 主体
│       └── event_handler.rs  # 事件处理
│
├── protocol/                  # 协议定义
│   └── src/
│       └── protocol.rs       # 事件、消息定义
│
├── app-server/               # HTTP API 服务器
│   └── src/
│       └── codex_message_processor.rs  # 消息处理
│
└── mcp-server/               # MCP 服务器实现
    └── src/

最后的话：Codex 的架构体现了现代 AI 系统的设计智慧——在保证安全和可靠的前提下，通过巧妙的分层和事件驱动，实现了一个高度可扩展和易维护的系统。希望本文能帮助你理解 Codex 的核心原理！