Codex 源码导读：第一部分——工程分层

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

流程图 1

图中的箭头描述的是职责上的主要数据/控制路径：入口把一个用户任务交给 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/：最后理解外部能力怎样挂入主链路。

本系列文章导航

本文是系列第 1 篇。后续篇目分别展开 Turn 生命周期、沙箱执行、上下文压缩、事件出口、模型网络、Skill/Agent、Agent Loop、工具路由以及 Session/Thread/Memory。每篇文章均独立成文，源码锚点直接指向公开仓库，不依赖本地目录或本地 Markdown 文件。

主线即上文预告的那一条：从 Turn 进入 core，追踪一次用户输入如何驱动「模型 → 工具 → 模型」的循环、在哪些状态下终止，以及被批准的命令最终在什么笼子里跑起来。全程只读，基线 d58d0e5841。

源码证据

仓库根 README：明确列出 CLI、IDE、桌面 App、Web 等使用入口。
Rust workspace 清单：列出各主要 crate。
core README：说明 codex-core 是供多种 Rust UI 复用的业务逻辑。
App Server README：说明 JSON-RPC、Thread / Turn / Item 及生命周期。
Thread Store README：说明持久化边界。
Exec Policy README：说明命令策略的 allow / prompt / forbidden 判定。

源码基线：OpenAI Codex d58d0e5841e0de08e251673db2d5af8cf3a1ad51。文中的流程图用于标出本篇所处的运行阶段。