对于想理解一个生产级 coding agent 如何搭建的开发者来说，OpenAI Codex 开源仓库提供了一个少见的观察样本。掘金近日发布的一篇源码导读文章，以当前检出的 Codex 源码为基础，梳理了仓库中 codex-rs/ 目录的整体工程结构。文章强调，这里的“层”并不是严格依赖关系，而是一种帮助理解职责与运行路径的概念分层：Rust crate 之间可以跨层依赖，不能将其等同于网络协议式的六层模型。
从产品形态看，Codex 是一个本地运行的 coding agent 系统。常见入口包括 codex CLI、运行在终端里的 codex-rs/tui，以及通过 codex-rs/app-server 接入的 IDE、桌面 App 等富客户端。这些入口并不各自实现核心推理逻辑，而是共享同一个 agent 业务核心：codex-rs/core。因此，文章给出的更准确结构是：多个交互入口、一套 agent runtime，再往下连接模型、上下文、工具与安全能力。
交互入口与编排核心被明确分开
在导读作者看来，仓库根目录并不是把所有代码简单堆在一起。真正值得关注的部分集中在 codex-rs/ 目录。该目录下的 Cargo.toml 将大量 crate 组织为一个 Rust workspace，这也说明 Codex 并不是“一个 CLI 二进制”那么简单，而是一个由多个模块组成的工程系统。
第一层是交互入口与适配层，负责接收用户输入、展示过程和结果，并把不同界面的调用统一转入 agent runtime。文章特别提醒，这一层中最容易混淆的地方在于：TUI 是视图层，App Server 是接入协议层，CLI 是产品入口，但它们都不是 agent 推理和工具编排本体。
真正的中心是 codex-rs/core。它承载的业务逻辑是：当收到一次用户任务后，如何形成一次 agent 执行。围绕这一核心，rollout、state、thread-store、thread-manager-sample 等相邻 crate 提供编排、状态和持久化能力。该层决定何时请求模型、何时执行工具、何时继续下一步，以及何时完成一个 Turn。对于理解 Agent 系统而言，这也是后续分析 loop 机制时的关键位置。
会话、模型接入与工具执行各有边界
在编排层之下，Codex 还划分出会话、上下文与持久化层。它主要解决两个问题：当前模型应看到什么，以及这次交互如何在之后被找回。在 App Server 的语义中，最小交互层级被定义为 Thread、Turn、Item。其中，Thread 表示一个会话，Turn 表示一次用户发起的执行，Item 则包括消息、工具调用、文件编辑等过程项。这组模型同时服务于 UI 展示、上下文重建和持久化。
再往下是模型与后端接入层。该层负责身份认证、模型选择、请求发送，以及不同后端适配。主要模块包括 codex-api、codex-client、backend-client、model-provider、model-provider-info、models-manager、login、chatgpt、responses-api-proxy，以及 ollama、lmstudio 等本地或兼容后端接入。从上层视角看，它提供的语义是“向选定模型发起一次流式 agent 请求并接收事件”，具体的 HTTP、认证和模型格式差异则被尽量封装在这一层内部。模型返回的文本或工具调用意图会回到编排层，由编排层决定后续动作。
工具执行与安全边界层则负责把模型生成的动作请求转化为实际副作用，同时确保这些副作用处于用户配置的权限和沙箱边界内。文章提到，execpolicy 的源码文档显示，它可以按规则将命令判为 allow、prompt 或 forbidden。这意味着，“模型建议执行一个 shell 命令”与“命令已经在机器上执行”之间，存在明确的策略、审批和沙箱关口。
扩展能力与横切设施构成外围支撑
除了主线层次，Codex 还设置了一层扩展、协作与外部能力模块。文章指出，Codex 并没有把所有能力硬编码进 core，而是通过可插拔方式接入 MCP、Skills、Plugins、Hooks、Connectors、Cloud 等能力。这些模块的共同点是为 agent 增加可调用的上下文、工具或运行方式，但它们仍然受编排层和安全边界约束。
此外，还有一组不属于单一业务阶段、但几乎各层都会使用的基础能力，包括 http-client、network-proxy、otel、analytics、diagnostics、secrets、keyring-store 以及 utils/* 等。文章将其归为网络、可观测性、凭证与通用基础设施，而不是第七个独立的 agent 业务阶段。
在整体运行路径上，这篇导读给出的结构相当清晰：用户或宿主程序从 CLI、TUI、App Server 等入口进入，任务被交给 runtime；runtime 读写会话上下文、请求模型、调度工具，扩展能力则以可插拔方式参与。与此同时，协议、HTTP、遥测、诊断、凭证等横切设施为各层提供支撑。文章也说明，图中的箭头表示职责上的主要数据和控制路径，真实 crate 依赖关系会更细，部分模块也会跨越多个概念层。
对于希望入门的读者，文章给出的建议是，不要一开始就平铺阅读几千个 crate，而应先建立主干：从入口进入，再到 core 的 Turn 生命周期，随后追踪模型调用、工具执行和安全边界。该系列后续还将展开 Turn 生命周期、沙箱执行、上下文压缩、事件出口、模型网络、Skill/Agent、Agent Loop、工具路由以及 Session/Thread/Memory 等主题。本系列以 OpenAI Codex 源码基线 d58d0e5841e0de08e251673db2d5af8cf3a1ad51 为准，强调源码锚点直接指向公开仓库。
从行业角度看，这类源码导读的价值不只是解释一个项目怎么读代码，更在于展示了 Agent 工程化的一个基本方向：入口可以多样，但执行核心必须集中；模型调用、上下文管理、工具执行和安全策略需要被拆开；扩展能力要能接入，但不能绕过边界。对于正在搭建本地 Agent、IDE 助手或自动化编程工具的团队来说，这种分层方式提供了一个相对清晰的参考框架。
原创文章，作者：点点，如若转载，请注明出处：https://www.dian8dian.com/du-dong-openai-codex-kai-yuan-cang-ku-cong-gong-cheng-fen
