第十四课：整体架构概览
2.0K字·6分钟·
Rust codex-rs架构60+ crateNode.js包装层
学习目标
- 理解 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
- 性能：Rust 编译为原生代码，启动速度快，内存占用低
- 安全性：Rust 的所有权系统防止内存泄漏和数据竞争
- 跨平台：Rust 可以编译到 macOS、Linux、Windows
- 系统级访问：沙盒机制需要直接调用操作系统 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 分发，因为：
- npm 是最流行的包管理器，用户熟悉
- Node.js 生态提供了便利的安装脚本
- 可以处理平台特定的安装逻辑
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 如何处理用户请求。