❝

本文将带你深入了解 OpenAI Codex 的内部架构、设计思路和实现原理。无论你是初学者还是有经验的开发者，都能从中获得对 AI 编程助手的深刻理解。

什么是 Codex？

想象一下，你有一个超级聪明的编程助手，它不仅能理解你的需求，还能直接帮你写代码、运行命令、修改文件。这就是 Codex —— OpenAI 推出的本地 AI 编程代理。

用大白话解释

如果把编程比作做菜：

• 普通的 AI 助手（如 ChatGPT）就像一本菜谱，告诉你怎么做，但你需要自己动手
• Codex 就像一个真正的厨师，不仅告诉你怎么做，还能直接帮你把菜做出来

核心能力

• Codex 能做什么？
• 理解代码：阅读和分析你的项目代码
• 编写代码：自动编写新功能或修复 bug
• 执行命令：运行测试、构建项目、git 操作等
• 修改文件：直接编辑、创建、删除文件
• 搜索信息：在代码库中搜索，甚至进行网络搜索
• 调用外部工具：通过 MCP 协议连接各种外部服务

整体架构概览

Codex 采用了 Monorepo（单一代码仓库） 的组织方式，主要由 Rust 和 TypeScript 两种语言构建。

为什么选择 Rust？

项目结构图

codex/├── codex-rs/           # Rust 核心代码（45+ 个模块）│   ├── core/           # 🧠 核心引擎 - AI 的"大脑"│   ├── tui/            # 💻 终端界面 - 用户交互│   ├── cli/            # ⌨️ 命令行入口│   ├── exec/           # 🤖 非交互式执行│   ├── mcp-server/     # 🔌 MCP 服务器│   └── ...             # 其他支持模块│├── sdk/typescript/     # TypeScript SDK（给开发者用的库）├── shell-tool-mcp/     # Shell 工具 MCP 实现└── docs/               # 文档

架构分层图

Codex 的架构可以分为四层：

1. 用户接口层：你与 Codex 交互的入口（CLI、TUI、SDK）
2. 核心引擎层：处理 AI 推理、工具调用、上下文管理
3. 执行层：实际执行命令、修改文件、调用外部服务
4. 安全层：沙箱隔离、权限控制、执行策略

核心特性详解

1. 多模式交互

Codex 支持三种使用模式：

2. 会话管理

每次与 Codex 的对话都是一个”会话”（Session）。Codex 会：

• 记住你们的对话历史
• 保存执行过的命令和结果
• 支持暂停和恢复对话

3. 智能审批

Codex 不会盲目执行所有命令。对于危险操作，它会执行 rm -rf ./logs/*，这会删除所有日志。[允许执行] [拒绝] [白名单此命令]

底层协议与通信机制

提交队列/事件队列（SQ/EQ）模式

Codex 内部使用了一种高效的异步通信模式：

用大白话解释：

想象一家餐厅：

• 提交队列（SQ） 就像顾客下单的窗口
• Codex 核心引擎 就像厨房
• 事件队列（EQ） 就像出餐窗口

顾客下单后不需要等在窗口，可以去座位上等。厨房做好菜后，通过出餐窗口通知顾客取餐。

核心代码结构

// 简化版的 Codex 核心结构pubstructCodex {// 提交队列：接收用户输入    tx_sub: Sender<Submission>,// 事件队列：发送处理结果    rx_event: Receiver<Event>,}

事件类型

Codex 定义了丰富的事件类型来描述各种操作：

记忆系统：如何记住对话

问题：AI 的”健忘症”

大语言模型本身是”无状态”的，每次调用都是全新的开始。就像一个失忆的人，每天早上醒来都不记得昨天发生了什么。

解决方案：持久化历史

Codex 通过多层记忆系统解决这个问题：

三层记忆架构

1. 短期记忆：上下文管理器（ContextManager）

pubstructContextManager {// 当前对话的所有项目（从旧到新排序）    items: Vec<ResponseItem>,// Token 使用信息    token_info: Option<TokenUsageInfo>,}

作用：管理当前对话中的所有消息、工具调用和结果。

2. 中期记忆：消息历史（Message History）

存储位置：~/.codex/history.jsonl

{"session_id": "abc123", "ts": 1699123456, "text": "帮我写一个排序函数"}{"session_id": "abc123", "ts": 1699123460, "text": "好的，这是冒泡排序的实现..."}

特点：

• 使用 JSONL 格式（每行一个 JSON）
• 原子写入（不会出现写一半的情况）
• 自动管理大小（超过限制会清理旧记录）

3. 长期记忆：会话持久化

存储位置：~/.codex/sessions/

每个会话保存为独立的 JSON 文件，包含完整的对话状态，支持随时恢复。

项目文档记忆：AGENTS.md

Codex 还会读取项目中的 AGENTS.md 文件，了解项目的特殊规则：

# AGENTS.md## 项目规范- 使用 TypeScript 编写- 所有函数必须有注释- 测试覆盖率要求 80% 以上## 禁止操作- 不要修改 .env 文件- 不要删除 migrations 文件夹

上下文工程：智能管理有限的”脑容量”

问题：上下文窗口的限制

大语言模型有一个”上下文窗口”限制，就像人的工作记忆一样有限。如果对话太长，模型就会”记不住”前面的内容。

解决方案：智能上下文管理

Codex 采用多种策略来最大化利用有限的上下文：

策略 1：Token 估算

不使用精确的 tokenizer（太慢），而是用简单的启发式算法：

const APPROX_BYTES_PER_TOKEN: usize = 4;// 估算 token 数量：每 4 个字节约等于 1 个 tokenfnapprox_token_count(text: &str) -> usize {    (text.len() + 3) / 4// 向上取整}

策略 2：智能截断

对于过长的输出，保留头尾，删除中间：

原始输出（10000 字符）：┌───────────────────────────────────────────────────────┐│ [头部 1000 字符] [...中间内容...] [尾部 1000 字符]        │└───────────────────────────────────────────────────────┘截断后（2500 字符）：┌───────────────────────────────────────────────────────┐│ [头部 1000 字符] ... [省略 7500 字符] ...[尾部 1000 字符] │└───────────────────────────────────────────────────────┘

策略 3：对话压缩（Compaction）

当上下文接近满时，Codex 会请求 AI 对之前的对话进行”摘要”：

压缩前：用户: 帮我看看为什么测试失败AI: 好的，让我运行测试... 测试结果是... 问题在于...用户: 修复它AI: 我修改了文件... 现在测试通过了用户: 还有其他问题吗？...（很多轮对话）压缩后：[摘要] 用户请求修复测试失败问题，经过分析发现是类型错误，已修改 src/utils.ts 第 42 行，测试现已通过。

策略 4：环境上下文差异

只发送变化的部分，而不是每次都发送完整的环境信息：

<!-- 首次发送完整上下文 --><environment_context><cwd>/path/to/project</cwd><sandbox_mode>workspace-write</sandbox_mode><shell>bash</shell></environment_context><!-- 之后只发送变化 --><environment_context_diff><cwd>/path/to/project/src</cwd><!-- 只有工作目录变了 --></environment_context_diff>

工具系统：让 AI 能够”动手”

为什么需要工具？

大语言模型本身只能”说”，不能”做”。工具系统就是给 AI 装上”手”，让它能够：

• 执行 shell 命令
• 读写文件
• 搜索代码
• 调用外部服务

工具架构

内置工具列表

工具调用流程

1. AI 决定使用工具   └── "我需要运行测试来验证修复"2. 生成工具调用   └── { tool: "shell", command: "npm test" }3. 权限检查   └── 检查执行策略和沙箱规则4. 执行工具   └── 在沙箱中运行命令5. 返回结果   └── 将输出返回给 AI6. AI 继续推理   └── "测试通过了，修复成功！"

工具注册机制

Codex 使用统一的工具注册表来管理所有工具：

pubstructToolRegistry {    handlers: HashMap<ToolType, Box<dyn ToolHandler>>,}pubtraitToolHandler: Send + Sync {asyncfnhandle(        &self,        invocation: ToolInvocation    ) -> Result<ToolOutput, ToolError>;}

安全沙箱：给 AI 一个安全的”游乐场”

为什么需要沙箱？

让 AI 执行命令是危险的。想象一下：

用户: 帮我清理项目AI: 好的，我来执行 rm -rf /  # 危险！会删除整个系统！

沙箱就是为了防止这种灾难性的操作。

沙箱原理

三种沙箱策略

跨平台沙箱实现

Codex 针对不同操作系统使用不同的沙箱技术：

macOS: Seatbelt

// 生成 SBPL（Seatbelt Profile Language）策略let profile = format!(r#"    (version 1)    (deny default)    (allow file-read* (subpath "{writable_root}"))    (allow file-write* (subpath "{writable_root}"))    (deny network*)"#);

Linux: Landlock + Seccomp

// Landlock：限制文件系统访问let ruleset = Ruleset::new()    .handle_access(AccessFs::ReadFile)?    .create()?;// Seccomp：阻止危险的系统调用seccomp_rule_add(ctx, SCMP_ACT_ERRNO(EPERM),    SCMP_SYS(connect), 0)?;  // 禁止网络连接

Windows: RestrictedToken

使用 Windows 的受限令牌和 ACL（访问控制列表）来限制权限。

沙箱绕过机制

有时候确实需要执行受限的操作，Codex 提供了安全的升级路径：

1. AI 请求执行需要额外权限的命令2. 向用户显示权限提升请求3. 用户确认后，在沙箱外执行4. 记录操作日志

MCP 协议：连接外部世界的桥梁

什么是 MCP？

MCP（Model Context Protocol） 是一个开放协议，让 AI 助手能够与外部工具和服务交互。可以把它想象成 AI 世界的”USB 接口”。

MCP 的角色

Codex 可以同时作为：

• MCP 客户端：调用其他 MCP 服务器提供的工具
• MCP 服务器：让其他应用调用 Codex 的能力

连接外部服务示例

# ~/.codex/config.toml[mcp_servers.github]enabled = true[mcp_servers.github.transport]type = "stdio"command = "npx"args = ["@modelcontextprotocol/server-github"]

配置后，Codex 就能使用 GitHub 的功能：

用户: 帮我创建一个 issue 报告这个 bugCodex: 好的，我来调用 GitHub MCP 服务器创建 issue...       [调用 mcp__github__create_issue 工具]       Issue 已创建：https://github.com/xxx/xxx/issues/123

MCP 通信流程

┌─────────────┐     JSON-RPC      ┌─────────────┐│   Codex     │ ◄──────────────► │  MCP 服务器  ││  (客户端)   │    over stdio    │  (GitHub)   │└─────────────┘                   └─────────────┘1. 初始化握手：交换能力声明2. 工具列表：获取可用工具3. 工具调用：执行具体操作4. 返回结果：获取执行结果

支持的传输方式

执行策略：智能的权限管理

问题：如何判断命令是否安全？

不是所有命令都同样危险：

• ls 完全安全
• npm test 通常安全
• rm -rf / 绝对危险
• git push 需要确认

解决方案：执行策略引擎

Codex 使用基于规则的执行策略系统：

策略文件格式

策略文件使用类 Python 的 Starlark 语言：

# ~/.codex/policy/default.codexpolicy# 允许常见的安全命令prefix_rule(    pattern = ["ls"],    decision = "allow",)prefix_rule(    pattern = ["cat"],    decision = "allow",)# 需要确认的命令prefix_rule(    pattern = ["git", ["push", "pull", "fetch"]],    decision = "prompt",)# 禁止危险命令prefix_rule(    pattern = ["rm", "-rf"],    decision = "forbidden",)

决策优先级

当多个规则匹配时，采用最严格的决策：

forbidden（禁止） > prompt（提示） > allow（允许）

内置安全检测

除了显式规则，Codex 还有内置的启发式安全检测：

// 已知的安全命令（27个）const SAFE_COMMANDS: &[&str] = &["cat", "echo", "ls", "pwd", "grep", "head", "tail","wc", "sort", "uniq", "diff", "file", "which", "date","env", "printenv", "hostname", "uname", "whoami",// ...];// 危险命令检测fnis_dangerous_command(cmd: &[String]) -> bool {    matches!(cmd,        ["rm", "-rf", ..] |        ["git", "reset", "--hard", ..] |        ["sudo", ..] |// ...    )}

动态白名单

当你批准一个命令后，可以选择”白名单此命令”，Codex 会自动更新策略文件：

# 自动添加的规则prefix_rule(pattern=["npm", "test"], decision="allow")

如何使用 Codex

安装方式

# 方式 1：通过 npm 安装npm install -g @openai/codex# 方式 2：通过 Homebrew 安装（macOS）brew install --cask codex

登录认证

# 使用 ChatGPT 账户登录（推荐）codex login# 或者使用 API Keyexport CODEX_API_KEY=sk-xxx

基本使用

# 启动交互式界面codex# 直接执行任务（非交互式）codex exec"帮我写一个快速排序函数"# 在特定目录工作codex --cd /path/to/project

TypeScript SDK 使用

import { Codex } from"@openai/codex-sdk";const codex = new Codex();const thread = codex.startThread({    model: "gpt-4",    sandboxMode: "workspace-write",    workingDirectory: "./my-project"});// 同步模式：等待完成const turn = await thread.run("帮我修复所有的 TypeScript 错误");console.log(turn.finalResponse);// 流式模式：实时获取事件const { events } = await thread.runStreamed("运行测试");forawait (const event of events) {if (event.type === "item.completed") {console.log("完成:", event.item);    }}

配置文件

# ~/.codex/config.toml# 默认模型model = "gpt-4-turbo"# 沙箱策略sandbox_policy = "workspace-write"# 审批策略approval_policy = "on-request"# MCP 服务器配置[mcp_servers.github]enabled = true[mcp_servers.github.transport]type = "stdio"command = "npx"args = ["@modelcontextprotocol/server-github"]

总结

Codex 的设计哲学

1. 安全第一：多层沙箱、执行策略、用户审批
2. 可扩展性：工具系统、MCP 协议、插件架构
3. 智能管理：上下文压缩、记忆持久化、Token 优化
4. 用户体验：交互式界面、流式输出、断点续传

技术亮点

未来展望

Codex 代表了 AI 编程助手的一个重要方向：从”建议”走向”执行”，从”对话”走向”协作”。随着 AI 能力的提升和工具生态的完善，我们可以期待更加智能、安全、高效的编程助手。

附录：关键文件路径速查

• 作者【前端领秀】一个喜欢探索前端领域AI赋能的开发者，喜欢我的可以关注我，私信我邀请进入技术群，我会时刻分享最新前沿AI技术；