文章深入剖析了 OpenAI Codex CLI（本地跨平台软件代理）的工作原理，特别是其核心机制 Agent Loop（代理循环），并针对 Java/Python 工程化实践提供了具体的建议。
核心要点
Agent Loop 的运作流程
Agent Loop 是一个"反复问、反复干、反复追加"的流水线，包含以下步骤：
- 输入：将用户输入塞入 Prompt（消息列表）
- 推理：模型进行推理并输出
- 分支：输出可能是"最终回复"（回合结束）或"工具调用"（如执行
ls、读文件等） - 执行与追加：执行工具并将结果追加回 Prompt，供下一轮推理使用
- 循环：直到模型不再调用工具并输出最终回复
Prompt 的组装方式
Codex 使用 Responses API，将 Prompt 视为一串分角色的 Item 列表：
instructions：系统指令（权限、沙箱说明）tools：工具定义列表（shell、plan、web_search 等）input：包含消息、文件、图片、推理结果及工具调用记录的数组
流式推理与工具回填
利用 SSE（Server-Sent Events）流式返回推理事件，这些事件会被转化为结构化对象（如 reasoning、function_call、function_call_output）追加回 input 中，作为下一轮请求的历史记录。
性能优化与缓存策略
- 缓存命中的关键：为了实现 Zero Data Retention (ZDR)，Codex 每次都会发送完整的历史记录，极度依赖 Prompt Caching，要求新旧 Prompt 必须是"精确的前缀匹配"
- 保持前缀稳定：中途配置变更采用"追加新消息"而非"修改旧消息"的方式，以防止缓存失效
上下文窗口管理（压缩 Compaction）
随着对话变长，会触发上下文窗口溢出。Codex 使用 Compaction 机制，将冗长的历史 input 替换为一个更短的、包含加密内容的列表，以保留模型的潜在理解并释放空间。
工程化建议
- Prompt 设计：将其视为"不可变日志"，只追加不修改
- 工具管理：工具列表必须稳定排序，版本可控，否则会导致缓存失效
- 权限控制：将沙箱和权限约束明确写入 Prompt
- 流式事件：落地成结构化记录，以便回放和审计
- 自动化机制：必须具备自动化的上下文压缩机制
总结
一个靠谱的 Agent Loop 能够让 AI 写代码变得像可控的流水线一样，具备可追溯、可审计、可缓存、可压缩和可扩展的特性。