一文读懂 OpenAI Codex 源码的原理、架构与未来

📰 来源: 博客园

如果你第一次打开 codex-main 这个源码目录，很容易被它的规模吓住：顶层有 npm 包、Rust workspace、SDK、app-server、MCP、插件、技能、沙箱、TUI、云任务、线程存储、模型提供商、登录认证等大量模块。它不像一个传统命令行工具，也不像一个简单的 ChatGPT 包装器。更准确地说，Codex CLI 是一个“本地运行的智能软件工程代理”：它能理解用户目标，读取项目上下文，调用模型推理，决定是否执行命令或修改文件，把工具结果回传给模型，再持续推进任务直到给出最终结果。

本文基于当前工作区的 codex-main 源码目录进行分析，目标是让初学者也能看懂 Codex 的基本原理，同时给有工程背景的读者足够的架构细节。文章会围绕四个问题展开：

第一，Codex 到底是什么？它和普通命令行工具、普通聊天机器人有什么区别？

第二，Codex 的源码是如何组织的？哪些 crate 或目录承担核心职责？

第三，Codex 的核心执行原理是什么？从用户输入一条需求，到模型调用 shell、修改文件、读取 MCP 资源、输出最终答案，中间经过了哪些关键步骤？

第四，从工程实践角度看，我们可以怎样使用 Codex、扩展 Codex，或者从它的架构中学习如何设计自己的 AI Agent？

先给出一句通俗但准确的定义：

Codex 是一个以 Rust 为核心实现的本地软件工程 Agent 运行时，它通过协议层连接 UI、CLI、App Server 和无交互执行入口，通过 core 会话循环连接模型和工具，通过沙箱、审批、配置、MCP、技能、插件等机制把“模型会想”变成“系统能安全地做事”。

从源码看，Codex 并不是把用户问题直接发给模型，然后打印模型回答这么简单。它更像一个小型操作系统，里面有输入队列、事件队列、会话状态、权限系统、工具注册表、上下文管理器、模型客户端、执行沙箱、插件系统和持久化存储。模型只是决策核心之一，真正把 Agent 做成产品的是围绕模型的一整套工程系统。

为了帮助初学者建立直觉，我们先用一个简化流程表示 Codex 的工作方式：

这个循环是理解 Codex 的关键。传统 CLI 往往是“一条命令 -> 一个结果”，聊天机器人往往是“一段上下文 -> 一段文本”。Codex 则是“一段目标 -> 多轮推理 -> 多次工具调用 -> 状态更新 -> 最终交付”。它的源码复杂度主要来自三个方面：

接下来进入源码层面的系统拆解。

简要介绍：codex-main 是一个多语言单仓库，外层 npm 包负责分发和启动，核心能力集中在 codex-rs Rust workspace。最重要的主线是：codex-cli/bin/codex.js 找到对应平台的原生二进制，Rust cli 解析命令，tui 或 exec 或 app-server 建立会话，core 运行 Agent 主循环，protocol 定义客户端与 Agent 之间的操作和事件，tools 负责把模型输出映射成真实工具调用，sandboxing 和权限系统负责限制风险。

2.1 Codex 不是“聊天壳”，而是 Agent Runtime

很多初学者第一次理解 AI 编程工具时，会把它想成：

这只是最早期的代码助手形态。Codex 源码展示的是更成熟的 Agent 形态：

这个过程中，模型需要不断“看见”外部世界。它不能只凭训练记忆回答，因为当前项目的代码、测试失败、用户本地环境、未提交变更、配置文件和工具输出都在实时变化。Codex 的核心价值就在于把这些外部信息纳入一个受控循环。

在 codex-rs/core/src/session/turn.rs 中，源码对 run_turn 的注释已经把核心机制讲得很清楚：每一次 sampling request，模型可能返回函数调用，也可能返回助手消息。如果返回工具调用，Codex 执行工具并把工具输出作为下一次请求的输入；如果返回普通助手消息，就记录进历史并认为当前 turn 完成。

也就是说，Codex 的“智能”不只是模型能力，还包括它周围的运行时能力：

如果我们把 Codex 当成一个系统来观察，可以把它拆成五层：

其中最重要的源码目录如下：

codex-main/

├── README.md                         # 项目入口说明，介绍安装方式和产品形态

├── codex-cli/

│   └── bin/codex.js                  # npm 包入口，定位并启动平台原生二进制

├── codex-rs/

│   ├── Cargo.toml                    # Rust workspace，列出大量内部 crate

│   ├── cli/                          # 顶层命令行解析与子命令分发

│   ├── tui/                          # 交互式终端 UI

│   ├── exec/                         # 非交互执行入口，适合脚本和 CI

│   ├── core/                         # Agent 核心：会话、turn、工具、上下文、模型调用

│   ├── protocol/                     # 核心协议类型：Op、Event、SandboxPolicy 等

│   ├── app-server/                   # App/IDE 等宿主形态可复用的服务端

│   ├── app-server-protocol/          # App Server v1/v2 JSON-RPC 协议

│   ├── codex-api/                    # OpenAI API / Responses API 访问层

│   ├── codex-client/                 # HTTP/SSE/WebSocket 客户端基础能力

│   ├── model-provider/               # 模型提供商抽象

│   ├── mcp-server/、codex-mcp/       # MCP 相关能力

│   ├── core-skills/、skills/         # 技能加载与注入

│   ├── core-plugins/、plugin/        # 插件 manifest、市场和本地插件

│   ├── sandboxing/                   # 跨平台沙箱抽象

│   ├── linux-sandbox/                # Linux Landlock / bubblewrap 支持

│   ├── windows-sandbox-rs/           # Windows 受限 token、ACL、WFP 等

│   ├── thread-store/                 # 线程持久化抽象

│   ├── rollout/、rollout-trace/      # 会话记录、回放和调试

│   └── tools/                        # 工具规范和共享工具定义

└── sdk/

    ├── python/                 


🔗 原文链接: 点击阅读原文