心 智 七 篇 · Seven Mental Models
中 EN
← Knowledge Atlas · 源头

Unrolling the Codex Agent Loop

Codex agent loop 内部机制：prompt 构建、推理流程、prompt caching、compaction
源
源头 · CODEX AGENT LOOP · OpenAI · 循环机制 + Prompt 层级

拆解 Codex Agent Loop

循环由模型 tool call 驱动——以 assistant message 结束 turn

PROMPT构建MODELResponses APITOOLcall 执行ASSISTANT MSGturn 结束信号loop until final
PROMPT 构建 · 优先级递减
1System messageserver 控制
2Instructionsgpt-5.2-codex_prompt.md
3ToolsCodex 内建 + Responses API + MCP
4Developer messagesandbox 权限 · 审批模式
5User instructionsAGENTS.md 层级聚合 · skills
6Env contextcwd · shell
7User message本轮输入
Prompt Caching后续请求是前序的精确前缀——O(n²) 采样成本 → O(n)。破坏 cache：改 tools · 切模型 · 改 sandbox。MCP tools/list_changed 尤其棘手。
→ implicit-loop-architecture · codex · context-management · prompt-cachingopenai.com/index

Unrolling the Codex Agent Loop

概述

本文详细拆解 Codex 的 agent loop 内部机制——prompt 构建、推理流程、工具调用循环、性能优化和上下文管理。是理解 隐式循环架构 工程实现的核心参考。

Agent Loop 详解

循环机制

  1. 用户输入 → 构建 prompt → 发送到 Responses API
  2. 模型返回：final response（结束 turn）或 tool call（继续循环）
  3. Tool call → 执行 → 输出追加到 prompt → 重新查询模型
  4. 重复直到模型产出 assistant message（turn 结束信号）

Prompt 构建

按优先级递减排列：

  1. System message（由 server 控制）
  2. Instructions（model-specific，如 gpt-5.2-codex_prompt.md）
  3. Tools（Codex 内建 + Responses API + MCP 工具）
  4. Developer message（sandbox 权限、审批模式）
  5. User instructions（AGENTS.md 层级聚合 + skills 元数据）
  6. Environment context（cwd、shell）
  7. User message

Prompt Caching

关键性能优化：后续请求的 prompt 是前序请求的精确前缀，使得 prompt caching 可以将采样成本从二次方降为线性。破坏 cache 的操作：改 tools 列表、切换模型、改 sandbox 配置。MCP 工具尤其棘手——notifications/tools/list_changed 会导致中间 cache miss。

Compaction

演进过程：

  1. 手动 /compact → 用 LLM 总结对话 → 替换 input
  2. Responses API /responses/compact 端点 → 更高效，包含 type=compaction + encrypted_content 保留模型对原始对话的潜在理解
  3. 自动触发：超过 auto_compact_limit 时自动调用

与 Anthropic SDK 的对比

两者都采用 隐式循环架构，但实现细节不同：

  • Codex：Responses API + SSE 流 + stateless（支持 ZDR）
  • Claude Agent SDK：Messages API + compaction 内建
  • 共同点：循环由模型 tool call 驱动，以 assistant message 结束

References

  • sources/openai_official/unrolling-codex-agent-loop.md