Codex 源码导读：第一部分——工程分层
英文标题：Codex 源码导读：第一部分——工程分层
Codex 源码导读：第一部分——工程分层 本文基于 OpenAI Codex 开源仓库当前检出的源码，而不是根据产品界面推测。这里的“层”是便于理解职责和运行路径的概念分层：Rust crate 之
3.2 KB
589 B
5.0 KB
中文
Codex 源码导读：第一部分——工程分层
本文基于 OpenAI Codex 开源仓库当前检出的源码，而不是根据产品界面推测。这里的“层”是便于理解职责和运行路径的概念分层 ：Rust crate 之间可以跨层依赖，不能把它误解成严格的六层网络协议。
先给结论：Codex 不是单一的 CLI，也不是单一的视图
Codex 是一个本地运行的 coding agent 系统。codex CLI 是最常见的产品入口；codex-rs/tui 是运行在终端里的交互视图；IDE、桌面 App 这类富客户端则可以通过 codex-rs/app-server 接入。它们共享核心的 agent 业务逻辑：codex-rs/core。
因此更准确的结构是：多个交互入口 → 一套 agent runtime → 模型、上下文、工具与安全能力 。
仓库的物理结构
仓库根目录并非所有代码都直接放在一起。
| 目录 | 作用 | 是否是主要运行时 |
|---|---|---|
codex-rs/ |
Rust workspace；包含 CLI、TUI、核心 agent、模型通信、工具执行、沙箱、MCP 等 | 是，主要实现所在地 |
codex-cli/ |
npm 分发/启动包装层 | 不是核心 agent runtime |
sdk/ |
TypeScript、Python SDK | 对外编程接入 |
docs/、scripts/、bazel/ |
文档、构建/测试/开发辅助 | 支撑工程 |
接下来分析的重点是 codex-rs/。其 Cargo.toml 把大量 crate 组织为一个 Rust workspace，这也是 Codex 不应被看作“一个 CLI 二进制”的直接证据。
六个运行层
1. 交互入口与适配层
这一层接收用户输入，展示过程和结果，并把不同界面的调用统一转入 agent runtime。
| 组件 | 职责 |
|---|---|
codex-rs/cli |
命令行入口、参数解析和子命令调度。 |
codex-rs/tui |
基于终端的交互界面；负责把用户看到的流式消息、工具进度和审批交互呈现出来。 |
codex-rs/app-server |
面向 IDE/桌面等富客户端的服务适配层；通过双向 JSON-RPC 2.0 通知与请求传递 Thread、Turn、Item。它不是视图本身。 |
codex-rs/app-server-protocol、protocol |
交互边界两侧使用的数据类型与协议定义。 |
sdk/ |
让 TypeScript/Python 代码以编程方式使用 Codex 的对外入口。 |
这里最容易混淆的地方是：TUI 是视图层，App Server 是接入协议层，CLI 是产品入口；三者都不是 agent 推理和工具编排本体。
2. Agent 编排层（系统中枢）
以 codex-rs/core 为中心。它承载“收到一次用户任务后，如何形成一次 agent 执行”的业务逻辑，并被不同 Rust UI 复用。
相邻的 rollout、state、thread-store、thread-manager-sample 等 crate 为一次执行及其生命周期提供编排、状态和持久化能力。第二部分分析 loop 时，重点会落在这一层：它决定何时请求模型、何时执行工具、何时继续下一步，以及何时完成一个 Turn。
3. 会话、上下文与持久化层
这一层解决两个问题：当前模型应看到什么 ，以及这次交互如何在之后被找回 。
| 组件 | 主要职责 |
|---|---|
prompts |
系统提示词和提示词资产的组织。 |
context-fragments |
可组合的上下文片段。 |
history、message-history |
历史消息与会话记录处理。 |
thread-store |
Thread 存储边界；源码说明它保存 canonical history 与可查询的 metadata。 |
state、config |
本地状态与配置。 |
memories/read、memories/write |
记忆的读取和写入能力。 |
在 App Server 的语义中，最小交互层级是：Thread（一个会话）→ Turn（一次用户发起的执行）→ Item（消息、工具调用、文件编辑等过程项） 。这组模型同时服务于 UI 展示、上下文重建和持久化。
4. 模型与后端接入层
这层负责身份认证、模型选择、请求发送与不同后端的适配；它不决定用户界面，也不直接承担本地命令执行。
主要模块包括 codex-api、codex-client、backend-client、model-provider、model-provider-info、models-manager、login、chatgpt、responses-api-proxy，以及 ollama、lmstudio 等本地/兼容后端接入。
从上层看，它提供的语义是“向选定模型发起一次流式 agent 请求并接收事件”；具体 HTTP、认证、模型格式差异被尽量封装在这里。模型返回的文本或工具调用意图会回到编排层，由编排层决定后续动作。
5. 工具执行与安全边界层
这一层把模型生成的动作请求变成实际副作用，同时确保副作用处于用户配置的权限和沙箱边界内。
| 类别 | 代表模块 |
|---|---|
| 命令与进程 | exec、exec-server、shell-command、shell-escalation |
| 文件与代码操作 | file-system、file-search、file-watcher、apply-patch、git-utils、worktree |
| 审批与策略 | execpolicy、sandboxing、linux-sandbox、bwrap、process-hardening |
execpolicy 的源码文档表明，它可以将命令按规则判为 allow、prompt 或 forbidden；所以“模型建议执行一个 shell 命令”与“命令已经在机器上执行”之间，存在明确的策略/审批/沙箱关口。
6. 扩展、协作与外部能力层
Codex 不把所有能力硬编码进 core。这一层把可插拔的能力接到 agent runtime：
| 能力 | 代表模块 |
|---|---|
| MCP | codex-mcp、rmcp-client、mcp-server、ext/mcp |
| Skills / 插件 / Hooks | skills、plugin、hooks、core-plugins、ext/skills |
| 外部连接器 | connectors、ext/connectors |
| 云端、代码模式与协作 | cloud-tasks*、code-mode*、collaboration-mode-templates、agent-roles、agent-identity |
它们的共同点是：为 agent 增加可调用的上下文、工具或运行方式；它们本身仍受上面的编排层和安全边界约束。
横切基础设施
除六层之外，还有一组不属于单一业务阶段、但几乎所有层都会使用的能力：http-client、network-proxy、otel、analytics、diagnostics、secrets、keyring-store、utils/*。可以把它们理解为网络、可观测性、凭证与通用基础设施，而不是第七个独立的 agent 业务阶段。
全局关系图
flowchart TB
User[用户或宿主程序]
Entry[交互入口与适配层<br/>CLI · TUI · App Server · SDK]
Runtime[Agent 编排层<br/>core · rollout · state]
Context[会话、上下文与持久化层<br/>prompts · context-fragments · history · thread-store · memories]
Model[模型与后端接入层<br/>model-provider · codex-client · codex-api · login]
Action[工具执行与安全边界层<br/>exec · file/git/apply-patch · execpolicy · sandboxing]
Extend[扩展、协作与外部能力层<br/>MCP · Skills · Plugins · Hooks · Connectors · Cloud]
Infra[横切基础设施<br/>protocol · HTTP · telemetry · diagnostics · secrets]
User --> Entry
Entry --> Runtime
Runtime <--> Context
Runtime <--> Model
Runtime --> Action
Runtime <--> Extend
Entry -.数据类型与事件.-> Infra
Runtime -.网络、日志、凭证.-> Infra
Model -.网络、日志、凭证.-> Infra
Action -.策略、审计.-> Infra
图中的箭头描述的是职责上的主要数据/控制路径：入口把一个用户任务交给 runtime；runtime 读取和写回会话上下文、请求模型、调度工具；扩展能力以可插拔方式参与。真实 crate 依赖会比图更细，且部分模块跨越多个概念层。
读源码时的推荐入口
如果目标是理解“它如何工作”，不建议从几千个 crate 平铺地读。先按下面顺序建立主干：
codex-rs/app-server/README.md：先掌握 Thread / Turn / Item 与外部交互生命周期。codex-rs/core/：理解 agent runtime 的业务中枢。codex-rs/thread-store/、history/、context-fragments/、prompts/：理解上下文和会话如何被组织。codex-rs/codex-client/、model-provider/、codex-api/：理解模型请求如何离开本地进程。codex-rs/exec/、execpolicy/、sandboxing/：理解模型意图如何变成受控动作。codex-rs/codex-mcp/、skills/、plugin/：最后理解外部能力怎样挂入主链路。
本目录导航（全部完成，2026-09-26）
主线即上文预告的那一条：从 Turn 进入 core，追踪一次用户输入如何驱动「模型 → 工具 → 模型」的循环、在哪些状态下终止，以及被批准的命令最终在什么笼子里跑起来。全程只读，基线 d58d0e5841。
源码证据
源码基线：OpenAI Codex
d58d0e5841e0de08e251673db2d5af8cf3a1ad51。文中的流程图用于标出本篇所处的运行阶段。
English / 原文
Codex 源码导读：第一部分——工程分层
本文基于 OpenAI Codex 开源仓库当前检出的源码，而不是根据产品界面推测。这里的“层”是便于理解职责和运行路径的概念分层 ：Rust crate 之间可以跨层依赖，不能把它误解成严格的六层网络协议。
先给结论：Codex 不是单一的 CLI，也不是单一的视图
Codex 是一个本地运行的 coding agent 系统。codex CLI 是最常见的产品入口；codex-rs/tui 是运行在终端里的交互视图；IDE、桌面 App 这类富客户端则可以通过 codex-rs/app-server 接入。它们共享核心的 agent 业务逻辑：codex-rs/core。
因此更准确的结构是：多个交互入口 → 一套 agent runtime → 模型、上下文、工具与安全能力 。
仓库的物理结构
仓库根目录并非所有代码都直接放在一起。
| 目录 | 作用 | 是否是主要运行时 |
|---|---|---|
codex-rs/ |
Rust workspace；包含 CLI、TUI、核心 agent、模型通信、工具执行、沙箱、MCP 等 | 是，主要实现所在地 |
codex-cli/ |
npm 分发/启动包装层 | 不是核心 agent runtime |
sdk/ |
TypeScript、Python SDK | 对外编程接入 |
docs/、scripts/、bazel/ |
文档、构建/测试/开发辅助 | 支撑工程 |
接下来分析的重点是 codex-rs/。其 Cargo.toml 把大量 crate 组织为一个 Rust workspace，这也是 Codex 不应被看作“一个 CLI 二进制”的直接证据。
六个运行层
1. 交互入口与适配层
这一层接收用户输入，展示过程和结果，并把不同界面的调用统一转入 agent runtime。
| 组件 | 职责 |
|---|---|
codex-rs/cli |
命令行入口、参数解析和子命令调度。 |
codex-rs/tui |
基于终端的交互界面；负责把用户看到的流式消息、工具进度和审批交互呈现出来。 |
codex-rs/app-server |
面向 IDE/桌面等富客户端的服务适配层；通过双向 JSON-RPC 2.0 通知与请求传递 Thread、Turn、Item。它不是视图本身。 |
codex-rs/app-server-protocol、protocol |
交互边界两侧使用的数据类型与协议定义。 |
sdk/ |
让 TypeScript/Python 代码以编程方式使用 Codex 的对外入口。 |
这里最容易混淆的地方是：TUI 是视图层，App Server 是接入协议层，CLI 是产品入口；三者都不是 agent 推理和工具编排本体。
2. Agent 编排层（系统中枢）
以 codex-rs/core 为中心。它承载“收到一次用户任务后，如何形成一次 agent 执行”的业务逻辑，并被不同 Rust UI 复用。
相邻的 rollout、state、thread-store、thread-manager-sample 等 crate 为一次执行及其生命周期提供编排、状态和持久化能力。第二部分分析 loop 时，重点会落在这一层：它决定何时请求模型、何时执行工具、何时继续下一步，以及何时完成一个 Turn。
3. 会话、上下文与持久化层
这一层解决两个问题：当前模型应看到什么 ，以及这次交互如何在之后被找回 。
| 组件 | 主要职责 |
|---|---|
prompts |
系统提示词和提示词资产的组织。 |
context-fragments |
可组合的上下文片段。 |
history、message-history |
历史消息与会话记录处理。 |
thread-store |
Thread 存储边界；源码说明它保存 canonical history 与可查询的 metadata。 |
state、config |
本地状态与配置。 |
memories/read、memories/write |
记忆的读取和写入能力。 |
在 App Server 的语义中，最小交互层级是：Thread（一个会话）→ Turn（一次用户发起的执行）→ Item（消息、工具调用、文件编辑等过程项） 。这组模型同时服务于 UI 展示、上下文重建和持久化。
4. 模型与后端接入层
这层负责身份认证、模型选择、请求发送与不同后端的适配；它不决定用户界面，也不直接承担本地命令执行。
主要模块包括 codex-api、codex-client、backend-client、model-provider、model-provider-info、models-manager、login、chatgpt、responses-api-proxy，以及 ollama、lmstudio 等本地/兼容后端接入。
从上层看，它提供的语义是“向选定模型发起一次流式 agent 请求并接收事件”；具体 HTTP、认证、模型格式差异被尽量封装在这里。模型返回的文本或工具调用意图会回到编排层，由编排层决定后续动作。
5. 工具执行与安全边界层
这一层把模型生成的动作请求变成实际副作用，同时确保副作用处于用户配置的权限和沙箱边界内。
| 类别 | 代表模块 |
|---|---|
| 命令与进程 | exec、exec-server、shell-command、shell-escalation |
| 文件与代码操作 | file-system、file-search、file-watcher、apply-patch、git-utils、worktree |
| 审批与策略 | execpolicy、sandboxing、linux-sandbox、bwrap、process-hardening |
execpolicy 的源码文档表明，它可以将命令按规则判为 allow、prompt 或 forbidden；所以“模型建议执行一个 shell 命令”与“命令已经在机器上执行”之间，存在明确的策略/审批/沙箱关口。
6. 扩展、协作与外部能力层
Codex 不把所有能力硬编码进 core。这一层把可插拔的能力接到 agent runtime：
| 能力 | 代表模块 |
|---|---|
| MCP | codex-mcp、rmcp-client、mcp-server、ext/mcp |
| Skills / 插件 / Hooks | skills、plugin、hooks、core-plugins、ext/skills |
| 外部连接器 | connectors、ext/connectors |
| 云端、代码模式与协作 | cloud-tasks*、code-mode*、collaboration-mode-templates、agent-roles、agent-identity |
它们的共同点是：为 agent 增加可调用的上下文、工具或运行方式；它们本身仍受上面的编排层和安全边界约束。
横切基础设施
除六层之外，还有一组不属于单一业务阶段、但几乎所有层都会使用的能力：http-client、network-proxy、otel、analytics、diagnostics、secrets、keyring-store、utils/*。可以把它们理解为网络、可观测性、凭证与通用基础设施，而不是第七个独立的 agent 业务阶段。
全局关系图
flowchart TB
User[用户或宿主程序]
Entry[交互入口与适配层<br/>CLI · TUI · App Server · SDK]
Runtime[Agent 编排层<br/>core · rollout · state]
Context[会话、上下文与持久化层<br/>prompts · context-fragments · history · thread-store · memories]
Model[模型与后端接入层<br/>model-provider · codex-client · codex-api · login]
Action[工具执行与安全边界层<br/>exec · file/git/apply-patch · execpolicy · sandboxing]
Extend[扩展、协作与外部能力层<br/>MCP · Skills · Plugins · Hooks · Connectors · Cloud]
Infra[横切基础设施<br/>protocol · HTTP · telemetry · diagnostics · secrets]
User --> Entry
Entry --> Runtime
Runtime <--> Context
Runtime <--> Model
Runtime --> Action
Runtime <--> Extend
Entry -.数据类型与事件.-> Infra
Runtime -.网络、日志、凭证.-> Infra
Model -.网络、日志、凭证.-> Infra
Action -.策略、审计.-> Infra
图中的箭头描述的是职责上的主要数据/控制路径：入口把一个用户任务交给 runtime；runtime 读取和写回会话上下文、请求模型、调度工具；扩展能力以可插拔方式参与。真实 crate 依赖会比图更细，且部分模块跨越多个概念层。
读源码时的推荐入口
如果目标是理解“它如何工作”，不建议从几千个 crate 平铺地读。先按下面顺序建立主干：
codex-rs/app-server/README.md：先掌握 Thread / Turn / Item 与外部交互生命周期。codex-rs/core/：理解 agent runtime 的业务中枢。codex-rs/thread-store/、history/、context-fragments/、prompts/：理解上下文和会话如何被组织。codex-rs/codex-client/、model-provider/、codex-api/：理解模型请求如何离开本地进程。codex-rs/exec/、execpolicy/、sandboxing/：理解模型意图如何变成受控动作。codex-rs/codex-mcp/、skills/、plugin/：最后理解外部能力怎样挂入主链路。
本目录导航（全部完成，2026-09-26）
主线即上文预告的那一条：从 Turn 进入 core，追踪一次用户输入如何驱动「模型 → 工具 → 模型」的循环、在哪些状态下终止，以及被批准的命令最终在什么笼子里跑起来。全程只读，基线 d58d0e5841。
源码证据
源码基线：OpenAI Codex
d58d0e5841e0de08e251673db2d5af8cf3a1ad51。文中的流程图用于标出本篇所处的运行阶段。