# 拆开一看才明白：Codex 这种本地AI写代码到底怎么跑起来的

> 深入剖析 OpenAI Codex CLI 的 Agent Loop 核心机制，以及工程化实践建议

- 原文链接: https://laojin.blog/repost/20260213_codex_agent_loop
- 作者: Dcs（老金转载）
- 原始出处: https://juejin.cn/post/7605516501752250377
- 发布日期: 2026-02-13
- 标签: Codex, Agent Loop, OpenAI, 转载

---

[原文链接](https://juejin.cn/post/7605516501752250377)

文章深入剖析了 OpenAI Codex CLI（本地跨平台软件代理）的工作原理，特别是其核心机制 **Agent Loop（代理循环）**，并针对 Java/Python 工程化实践提供了具体的建议。

---

## 核心要点

### Agent Loop 的运作流程

Agent Loop 是一个"反复问、反复干、反复追加"的流水线，包含以下步骤：

1. **输入**：将用户输入塞入 Prompt（消息列表）
2. **推理**：模型进行推理并输出
3. **分支**：输出可能是"最终回复"（回合结束）或"工具调用"（如执行 `ls`、读文件等）
4. **执行与追加**：执行工具并将结果追加回 Prompt，供下一轮推理使用
5. **循环**：直到模型不再调用工具并输出最终回复

### 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 写代码变得像可控的流水线一样，具备可追溯、可审计、可缓存、可压缩和可扩展的特性。

---