第十四课：整体架构概览

学习目标

• 理解 Codex 的四层架构设计
• 了解 codex-rs 的 Rust 实现细节
• 掌握 Node.js 包装层的作用
• 理解各层之间的交互方式

一、架构总览

OpenAI Codex 采用四层架构设计，从上到下分别是：用户界面层、代理核心层、安全层、模型层。这种分层设计使得各层可以独立演进，同时保持整体的稳定性。

1.1 用户界面层

用户界面层是用户与 Codex 交互的入口，包括：

• CLI（命令行界面）：终端用户的主要交互方式
• TUI（终端用户界面）：提供更丰富的终端交互体验
• IDE 扩展：VS Code、Cursor、Windsurf 等编辑器集成
• 桌面应用：macOS/Windows 原生应用
• Web 界面：chatgpt.com/codex 云端访问

1.2 代理核心层

代理核心层是 Codex 的大脑，负责：

• Agent Loop（代理循环）：处理用户请求的核心引擎
• 工具系统：管理和执行工具调用
• 上下文管理：维护对话历史和项目上下文
• 配置管理：处理多层级配置

1.3 安全层

安全层确保 Codex 在受控环境中运行：

• macOS：使用 Seatbelt (sandbox-exec) 沙盒
• Linux：使用 Landlock + seccomp + bubblewrap
• Windows：使用原生沙盒机制

1.4 模型层

模型层负责与 AI 模型通信：

• OpenAI 模型：GPT-5 Codex、codex-mini、o3、o4-mini
• 本地模型：通过 Ollama 运行开源模型

二、codex-rs：Rust 核心

Codex 的核心是用 Rust 编写的，项目名为 codex-rs。

2.1 为什么选择 Rust

1. 性能：Rust 编译为原生代码，启动速度快，内存占用低
2. 安全性：Rust 的所有权系统防止内存泄漏和数据竞争
3. 跨平台：Rust 可以编译到 macOS、Linux、Windows
4. 系统级访问：沙盒机制需要直接调用操作系统 API

2.2 crate 结构

codex-rs 包含 60+ 个 crate，主要包括：

• codex-core：核心逻辑，Agent Loop 实现
• codex-cli：CLI 入口，参数解析
• codex-tui：终端 UI 渲染
• codex-sandbox：沙盒执行引擎
• codex-tools：工具注册与调用
• codex-config：配置管理
• codex-protocol：通信协议

2.3 编译与分发

Rust 代码编译为平台特定的二进制文件：

• macOS Apple Silicon：codex-aarch64-apple-darwin
• macOS x86_64：codex-x86_64-apple-darwin
• Linux x86_64：codex-x86_64-unknown-linux-musl
• Linux arm64：codex-aarch64-unknown-linux-musl

三、Node.js 包装层

虽然核心是 Rust，但 Codex 通过 npm 分发，因为：

1. npm 是最流行的包管理器，用户熟悉
2. Node.js 生态提供了便利的安装脚本
3. 可以处理平台特定的安装逻辑

npm 包 @openai/codex 包含：

• 预编译的 Rust 二进制文件
• Node.js 启动脚本
• 平台检测和安装逻辑

四、Responses API

Codex 使用 OpenAI 的 Responses API 而非 Chat Completions API，因为：

• 支持 function calling（工具调用）
• 支持流式响应
• 支持 reasoning（推理链）
• 支持多轮对话

五、本课小结

要点	说明
四层架构	UI → Agent Core → Security → Model
codex-rs	Rust 实现，60+ crate
npm 包装	通过 npm 分发预编译二进制
Responses API	使用 OpenAI Responses API

下一步

下一课我们将深入 Agent Loop，了解 Codex 如何处理用户请求。