OpenAI Codex CLI 代理循环技术概述

OpenAI 详细阐述了 Codex CLI 代理循环的内部架构，这是一套核心编排逻辑，用于管理用户、语言模型（LLM）以及本地软件工具之间的交互。该系统通过迭代执行工具调用并管理不断增长的对话上下文，以实现可靠的软件更改并保持性能和稳定性。

代理循环架构

代理循环是协调用户与模型之间信息流的核心机制。对话中的一次“回合”包括多次推理和工具执行的迭代，直至达到最终状态。

迭代过程

输入与提示：代理接收用户输入并为模型准备文本提示。
推理：提示被分词后发送给模型，以生成响应。
决策点：模型要么生成最终的助手消息（结束本回合），要么请求一次 工具调用（例如执行类似 ls 的 shell 命令）。
执行与反馈：如果调用了工具，代理执行该命令，将输出追加到提示中，并重新查询模型。

该循环会重复进行，直至模型发出助手消息，表明工作已完成，控制权应返回给用户。

模型推理与提示构建

Codex CLI 使用 Responses API 来驱动其代理循环。根据配置，它可以连接到多种端点，包括 ChatGPT 登录、通过 API 密钥访问的 OpenAI 托管模型，或使用 gpt-oss 与 Ollama 或 LM Studio 的本地实例。

构建初始提示

Codex 并非直接发送原始提示，而是发送包含特定输入类型的 JSON 负载。Responses API 服务器随后根据角色将其组织成提示，优先级（从高到低）为：system、developer、user 和 assistant。

初始提示的关键组成部分包括：

指令：系统或开发者消息插入到上下文中。
工具：基于模式定义的工具列表，包含 Codex 提供的 shell 工具、Responses API 工具以及通过 MCP（模型上下文协议）服务器提供的用户自定义工具。
输入：聚合的文本、图像或文件。这包括来自 config.toml 的开发者指令，以及从项目根目录或 $CODEX_HOME 中的 AGENTS.md 或 AGENTS.override.md 文件获取的用户指令。

处理对话回合

每个回合都作为 Server-Sent Events（SSE）流进行处理。当模型产生推理或函数调用时，这些内容会追加到后续请求的 input 字段中。为优化性能，Codex 确保旧提示是新提示的精确前缀，这对于实现提示缓存至关重要。

性能与上下文管理

随着对话的增长，提示长度会增加，可能耗尽模型的上下文窗口并导致延迟上升。Codex 采用两种主要策略来缓解此问题：提示缓存和对话压缩。

提示缓存

为避免发送不断增大的 JSON 负载所带来的二次成本，Codex 依赖提示缓存。只有在完全匹配前缀时才会命中缓存。为保持命中，Codex 不会修改对话中早期的消息，而是通过追加新消息来反映更改：

配置更改：对沙箱配置或批准模式的更改会作为新的 role=developer 消息添加。
环境更改：对当前工作目录的更改会作为新的 role=user 消息添加。

如果未能保持工具顺序的一致性（如早期 MCP 工具实现中），可能导致缓存未命中，从而性能下降。

上下文窗口压缩

当令牌数量超过 auto_compact_limit 时，Codex 会使用 Responses API 的 /responses/compact 端点。此过程用更小的、具代表性的项目列表替换大量的对话历史。其中包括一个特殊的 type=compaction 项，包含 encrypted_content，在不需要完整令牌历史的情况下保留模型对对话的潜在理解。