当编程代理从云端走向本地终端，架构设计的重心发生了根本性转移。传统云端代理可以依赖远程沙箱、托管执行环境与集中式状态管理，但本地终端代理必须在资源受限的环境中完成模型推理、工具执行与安全隔离的协同工作。OpenAI 于 2024 年 4 月推出的 Codex CLI 代表了这一范式转变的典型实现 —— 它以 Rust 为核心构建语言，通过精细化的代理循环设计、选择性沙箱机制与高效的上下文管理策略，在保证执行安全性的同时实现了接近本地原生应用的响应速度。截至 2026 年 1 月，该项目已在 GitHub 获得超过 57,000 颗星标，成为终端编程代理领域的标杆参考实现。
代理循环的核心机制
Codex CLI 的架构核心是所谓的「代理循环」（Agent Loop），这一机制负责协调用户输入、模型推理与工具调用之间的完整交互流程。从宏观视角来看，代理循环遵循「输入 - 推理 - 工具执行 - 观察 - 更新」的迭代模式，每一次迭代都可能产生新的工具调用，直到模型决定输出面向用户的终结响应为止。这一设计使得 Codex 能够处理需要多步骤协作的复杂编程任务，例如「分析当前代码库结构、识别性能瓶颈、实现优化方案并运行测试验证」这类跨多个阶段的指令序列。
在具体实现层面，代理循环将用户查询转换为符合 OpenAI Responses API 规范的请求负载。该负载包含三个关键组成部分：instructions 字段承载系统级指令，定义代理的行为边界与可用工具集合；tools 字段列出模型可以调用的所有工具定义，每个工具包含名称、参数模式与用途描述；input 字段则包含用户提供的具体指令内容。值得注意的是，Codex 并非简单地将这些组件拼接成静态提示词，而是根据上下文动态调整提示结构，以优化模型推理效果并充分利用提示缓存机制带来的性能收益。
模型推理阶段通过 HTTP POST 请求触发，Codex 根据认证方式选择不同的 API 端点：使用 ChatGPT 账户登录时请求发往 https://chatgpt.com/backend-api/codex/responses，而 API 密钥认证则指向 https://api.openai.com/v1/responses。对于希望完全本地运行的用户，Codex 支持通过 --oss 标志配合 Ollama 0.13.4+ 或 LM Studio 0.3.39+ 实现自托管模型推理，默认端点为本地 http://localhost:11434/v1/responses。这种多层次的部署灵活性使得 Codex 能够适应从个人开发者到企业级环境的不同使用场景。
Responses API 以 Server-Sent Events 形式返回流式响应，Codex 消费这些事件并将其转换为内部事件对象。部分事件如 response.output_text.delta 用于驱动终端界面的实时流式输出，另一些事件如 response.output_item.added 则被转换为后续 API 调用所需的输入元素。这种事件驱动的架构确保了用户能够即时看到模型生成过程，同时代理系统能够完整记录每一次工具调用的输入输出，为后续推理提供必要的上下文信息。
工具调用与沙箱隔离策略
工具调用是代理系统执行有意义软件工作的关键能力。Codex 将工具划分为两类：系统提供的核心工具与通过 Model Context Protocol 接入的外部工具。这一分类直接决定了安全边界的划定方式 ——Codex 仅对自身提供的 shell 工具实施沙箱隔离，而外部 MCP 工具的安全策略由其各自的服务器负责实现。这种设计反映了本地代理系统的务实考量：强制隔离所有外部工具会导致显著的性能开销与兼容性问题，而将隔离责任下放给工具提供方则允许更灵活的集成方案。
Codex 的沙箱实现针对 shell 工具进行了精细化配置。在提示构建阶段，系统会在 tools 字段之前插入一条 role=developer 的特殊消息，专门描述适用于该 shell 工具的沙箱规则。这些规则涵盖文件系统访问边界、进程执行权限、网络连接限制等多个维度，具体参数可在用户配置文件 config.toml 中进行调整。这种将安全策略编码于提示而非硬编码于执行层的设计，使得沙箱行为可以根据项目需求动态调整，同时保持了提示层与执行层的清晰分离。
工具调用的执行流程遵循严格的状态转换模式。当模型在推理过程中决定调用工具时，Codex 会拦截这一请求并执行相应的本地操作，操作结果随后被格式化为结构化输出并附加到对话上下文中。关键的设计决策在于：工具执行的输出是追加到已有上下文的末尾，而非替换之前的对话内容。这一选择确保了对话历史的完整性，使得模型在后续推理中能够回溯之前的操作过程，同时也使得上下文管理成为必须持续优化的技术挑战。
MCP 工具的集成增加了动态性复杂度。MCP 服务器可以在会话期间通过 notifications/tools/list_changed 通知动态修改其提供的工具列表，这在技术上可能导致提示缓存失效 —— 因为工具列表的变更意味着提示前缀不再完全一致。Codex 团队曾在此处遭遇性能问题：早期的 MCP 工具集成实现未能保证工具枚举顺序的一致性，相同功能的 MCP 服务器在不同请求中返回的工具顺序可能不同，从而触发意外的缓存失效。后续修复通过强制排序解决了这一问题，但 MCP 工具的动态特性仍然要求系统在缓存策略上保持足够的容错能力。
上下文管理与性能优化
代理系统的上下文管理面临一个根本性的张力：对话历史的完整保留对于模型理解任务上下文至关重要，但上下文长度的线性增长会导致推理成本呈二次方扩展，同时很快触及模型的上下文窗口限制。Codex 通过多层次的优化策略应对这一挑战，核心思路是在保证任务连贯性的前提下尽可能压缩上下文体积并提高缓存命中率。
提示缓存是 Codex 性能优化的第一道防线。当后续请求的提示与之前请求的提示存在精确前缀匹配时，Responses API 可以复用之前的计算结果，将采样成本从全量计算降级为增量计算。Codex 团队将静态内容（系统指令、工具定义、示例代码）放置在提示的开头，而将可变内容（用户特定信息、动态生成的代码片段）放置在末尾，最大化前缀匹配的概率。然而，多种操作可能导致缓存失效：对话中动态添加或删除工具、切换目标模型、修改沙箱配置或工作目录等。Codex 的工程实践表明，每次引入新功能时都必须评估其对缓存策略的潜在影响，MCP 工具的动态性在这方面尤为棘手。
当上下文长度超过配置阈值时，Codex 会触发自动压缩机制。早期的实现要求用户手动调用 /compact 命令，压缩后的摘要作为新的对话上下文继续后续推理。这一方案的问题在于打断了用户的交互流程，且压缩时机的选择高度依赖用户的主观判断。后续版本引入了 /responses/compact 端点的自动支持，该端点不仅生成对话摘要，还返回一个特殊的 type=compaction 元素，其中包含加密的上下文表示，能够保留模型对原始对话的潜在理解。Codex 根据 auto_compact_limit 配置自动触发压缩，对用户完全透明，同时显著延长了单个会话能够处理的对话轮次上限。
值得深入分析的是 Codex 对状态性的处理方式。Responses API 提供了 previous_response_id 参数来支持有状态的对话延续，这一机制可以避免每次请求重复发送完整的对话历史。然而，Codex 出于两个关键原因选择不使用这一参数：首先是完全_stateless_的设计简化了服务端实现并提高了系统可靠性；其次是 Zero Data Retention 配置对数据持久化的严格要求与有状态机制存在根本冲突。对于选择 ZDR 的用户，Codex 确保每次请求都是完全独立的，同时通过上述压缩机制在客户端侧管理对话状态的延续。这种设计选择体现了安全合规与系统复杂度之间的权衡决策。
架构设计的工程启示
Codex CLI 的架构为本地代理系统的工程实现提供了多维度的参考价值。从技术选型角度看，Rust 作为核心实现语言带来了显著的性能收益与内存安全保证。97% 的代码库由 Rust 构成，这一比例在同类代理项目中属于较高水平，反映了 OpenAI 团队对执行效率与安全性的双重重视。Rust 的零成本抽象特性使得高性能的异步 I/O、精确的资源管理与低开销的命令执行成为可能，这些特性对于需要频繁调用系统命令的编程代理尤为关键。
文件系统结构的设计同样值得借鉴。Codex 将核心功能划分为多个子项目：codex-cli 负责终端交互与用户界面，codex-rs 包含代理循环与模型交互的核心逻辑，shell-tool-mcp 实现沙箱化的 shell 执行能力，sdk/typescript 提供外部集成接口。这种模块化架构使得各组件可以独立演进，同时保持了清晰的依赖边界。对于计划构建类似系统的团队，从一开始就明确组件边界并建立稳定的接口契约，远比后期重构更为经济。
安全模型的设计哲学体现了防御深度与实用主义的平衡。Codex 并未追求「绝对安全」的目标 —— 那在本地代理场景中既不现实也无必要 —— 而是聚焦于最危险的操作路径（shell 命令执行）实施强隔离，同时接受外部工具的自主安全策略。这一选择使得系统能够在安全性与功能性之间取得合理平衡：用户获得了执行复杂多步骤编程任务的能力，同时核心系统调用的风险被限制在可控范围内。
上下文管理策略的演进过程则展示了数据驱动设计的力量。从手动压缩到自动压缩的转变并非凭空产生，而是源于用户行为数据的分析 —— 大多数用户在遇到上下文限制时的第一反应是困惑而非主动寻求解决方案。自动压缩机制将复杂性隐藏在系统内部，将简洁性呈现给用户，这种设计思路在工具类产品中具有普遍适用性。
对于希望在本地代理领域进一步探索的开发者，Codex 提供了几个值得关注的技术方向：Responses API 的流式事件处理模型为实时反馈界面提供了标准化参考；MCP 集成模式展示了如何将动态工具发现能力融入代理系统；ZDR 兼容的架构设计则代表了隐私合规要求日益严格背景下的工程实践范式。这些技术遗产超越了具体的产品功能，为整个代理系统领域贡献了可复用的架构智慧。
参考资料
- OpenAI Codex CLI GitHub 仓库：https://github.com/openai/codex
- OpenAI 官方博客：《Unrolling the Codex agent loop》：https://openai.com/index/unrolling-the-codex-agent-loop/
- OpenAI Codex CLI 开发者文档：https://developers.openai.com/codex/cli/