OpenAI 在 2025 年 12 月开源的 Codex CLI 代表了终端编码代理的新范式。这个由 97% Rust 代码构建的项目在发布当天就获得了超过 1100 颗 GitHub 星标，目前已达到 57,200 星，成为终端 AI 代理领域最受关注的开源实现之一。与传统的基于 Python 或 JavaScript 的编码助手不同，Codex 选择了系统编程语言 Rust 作为核心实现语言，这一架构决策直接决定了其性能特征和安全边界。
Codex 的系统架构遵循清晰的分层设计原则，将用户界面、代理核心逻辑和工具执行层进行了彻底解耦。最核心的设计是 Op/Event 协议系统：用户界面通过提交 Operation（操作）到异步通道与代理核心通信，代理核心则通过 Event（事件）流将状态变化和结果返回给前端。这种基于通道的解耦模式使得同一个代理核心可以同时支撑三种完全不同的交互模式 —— 交互式终端界面（TUI）、非交互式 headless 执行模式（codex exec），以及用于 IDE 集成的 JSON-RPC 服务器。TUI 层使用 Ratatui 框架构建，提供会话管理、命令审批和流式文本显示功能；headless 模式则通过 EventProcessor 抽象支持人类可读和 JSONL 两种输出格式；App Server 则实现了完整的 Thread/Turn/Item 协议原语用于 IDE 扩展通信。
配置系统是 Codex 架构中另一个值得深入分析的子系统。它采用了六层优先级机制，从最低到最高依次为：内置默认值、MDM 配置（macOS 企业管理）、系统级配置、用户级配置、项目级配置，最后是 CLI 参数覆盖。这种分层设计使得企业可以在系统层面锁定安全策略，同时保留用户在个人配置和项目层面的灵活性。CLI 覆盖的优先级最高（值为 30），这意味着开发者可以在命令行中临时覆盖任何配置而无需修改配置文件。在实际使用中，开发者可以通过 -c key=value 格式的标志进行配置覆盖，也可以通过 --enable 和 --disable 标志动态调整功能开关。
工具系统和沙箱机制是保障 Codex 安全执行的关键组件。内置工具集包括文件读取、grep 搜索、目录列表和补丁应用等核心功能，而 shell 命令执行则通过 UnifiedExec 组件统一管理。沙箱实现针对不同操作系统采用了差异化的底层机制：Linux 平台使用 Landlock 机制进行文件系统权限限制，macOS 借助 Seatbelt 沙箱配置文件，Windows 则使用 Restricted Tokens。这种多平台适配确保了代理在执行任意命令时都能受到预先定义的安全策略约束。此外，Codex 还支持通过 MCP（Model Context Protocol）扩展工具集，外部 MCP 服务器可以通过 stdio 或 HTTP 传输协议接入，工具命名遵循 mcp__{server}__{tool} 的聚合模式，便于代理发现和调用。
从工程实践角度来看，Codex 的 Cargo 工作空间包含超过 50 个 crate，核心组件包括 codex-core（代理逻辑）、codex-tui（终端界面）、codex-exec（headless 执行）、codex-app-server（IDE 集成服务器）和 codex-cli（CLI 入口点）。构建配置启用了完整的 LTO 链接时优化和单 codegen 单元优化，发布版本的二进制文件会剥离符号以减小体积。发行渠道覆盖了 npm（TypeScript 包装器嵌入原生二进制）、Homebrew（macOS 直接安装）和 GitHub Releases（多平台压缩包），并针对各平台提供了代码签名保障。这种成熟的工程化组织方式为开源项目的长期维护和社区贡献奠定了坚实基础。
资料来源：Codex GitHub 仓库（https://github.com/openai/codex，Apache-2.0 许可证）；架构文档 DeepWiki（https://deepwiki.com/openai/codex/architecture-overview）。