OpenAI详解Codex代理循环，完整呈现提示构建与性能优化

核心概览

Codex CLI 作为跨平台本地软件代理，围绕 agent loop 实现用户指令、模型推理、工具调用的闭环。文章首先定义了 agent loop：

1. 接收用户输入并组装成 Prompt；
2. 调用 Responses API 进行模型推理；
3. 根据模型返回的 assistant message 或 tool call 执行相应工具；
4. 将工具输出写回 Prompt，进入下一轮推理，直至模型给出最终 assistant 消息。

Prompt 生成细节

• 角色顺序：系统（system）→开发者（developer）→用户（user）→助理（assistant），权重依次递减。
• 指令来源：model_instructions_file 或默认的模型指令文件（如 gpt-5.2-codex_prompt.md）。
• 工具清单：通过 JSON schema 向模型公开可调用的工具，包括本地 shell、计划更新、Web 搜索以及用户自定义的 MCP 服务。
• 环境描述：额外插入开发者角色的 sandbox 描述与用户角色的工作目录信息，以约束工具的权限。

交互流程示例

{
  "type": "message",
  "role": "user",
  "content": [{ "type": "input_text", "text": "在 README.md 中添加架构图" }]
}

模型可能返回 function_call（如 shell），Codex 执行后把输出包装为 function_call_output，再将其拼回 Prompt，继续推理直至得到 assistant 消息 "已在 README.md 中加入架构图"。

性能与上下文管理

1. 缓存机制：Prompt 前缀保持不变可命中模型缓存，使后续推理从线性成本降至常数成本。静态指令放在开头，动态用户信息放在末尾。
2. 上下文窗口：随着对话轮次增长，Prompt 长度逼近模型上下文上限。Codex 通过 compact 接口将历史对话压缩为加密摘要，保留模型的潜在理解，同时释放 token 空间。
3. 避免 Quadratic 增长：不使用 previous_response_id，保持每次请求完全无状态，兼容 Zero Data Retention（ZDR）配置。
4. 工具变更的缓存失效：中途增删工具、切换模型或更改 sandbox 配置都会导致缓存失效，Codex 会通过插入新 developer 或 user 消息的方式记录变更，而非修改已有条目。

实践建议

• 将固定指令、示例放在 Prompt 开头，以提高缓存命中率。
• 当工具列表可能频繁变动时，考虑在对话开始前一次性声明全部工具，避免中途更改。
• 监控 token 使用率，超过阈值时主动调用 /responses/compact 接口进行压缩。
• 对于长对话，可定期手动触发 /compact 命令，以获得更细粒度的摘要。

展望

本文仅覆盖 Codex 代理循环的基本框架与性能要点，后续系列将进一步剖析 CLI 的内部架构、计划生成与沙箱安全模型，帮助社区在构建自定义 LLM 代理时遵循最佳实践。

“零数据保留（ZDR）让每一次请求都保持纯粹的 stateless，既是对用户隐私的尊重，也是对系统可扩展性的保障。” — Michael Bolin, OpenAI 技术团队