OpenAI Codex Agent 提示词缓存策略：让长期编码任务成本降低九成 · 干货攻略

  • 链接:https://x.com/cwolferesearch/status/2054202312436953270
  • 分类:x-tips
  • 来源:X @cwolferesearch
  • 作者:Jay
  • 更新:2026-10-11

这是什么

OpenAI Codex 是一个以 LLM 为核心的编码 Agent（通过 Codex CLI 本地运行，或云端沙盒运行），每次任务会发送一系列 API 请求来驱动"Agent Loop"——即让模型推理、调用工具、读取结果、再推理的循环。Codex 的 prompt 构造并非用户直接写死，而是由 harness（即 Codex 的执行框架）将多条信息分层组装后发给 Responses API。

提示词缓存（Prompt Caching）是 OpenAI 在 2026 年主推的推理优化手段：当多个请求拥有相同的前缀（prefix）时，已计算过的 Key-Value（KV）状态会被复用，无需重新 prefill，从而同时降低延迟和成本。OpenAI 官方文档明确写出：缓存的 KV 张量存储在服务端，cache hit 时采样变成线性而非二次复杂度。

核心机制：OpenAI 对前缀约前 256 个 token 做哈希，与已缓存的 KV 张量匹配池比对——有命中则跳过 prefill，直接处理后续变长部分。

为什么值得关注

cwolferesearch（Cameron R. Wolfe, Ph.D.）指出：Codex 的 prompt 在用户消息之前就已包含大量稳定内容——System message、Tool specs、Model/Developer instructions、Permissions info、Agent files、环境信息。这使得单个请求的 token 量极易达到数千甚至上万。

典型编码任务往往是长会话：用户让 Agent 改一个 bug，它要先读文件、再推理、再改、再验证——一个任务可能消耗掉整个上下文窗口甚至多次。在这样的场景下，一次 cache miss 的代价就是整段 prefill 的重复计算。

OpenAI 官方数据显示：GPT-6 系列上缓存的输入 token 折扣最高达 90%（up to 90% 折扣）；通用文档写明折扣最高 95%（up to 95% 折扣，两文口径略有差异，以下方官方核验说明为准）。这意味着对于一个 token 消耗密集的编码 Agent，优化缓存策略可直接将输入成本腰斩甚至更多。

核验过程

官方来源：

  1. OpenAI Blog · "Better prompt caching for GPT-6"（2026-09-22） - 原文：「GPT‑6 enables persistent agents to work for hours on complex tasks… cached input tokens… discounts of up to 90%」「cache discounts for eligible shared prefixes reused within a 30‑minute window」「Prompt Caching Dashboard」「append new developer messages to the end of the context to override older ones」（append-only 更新原则） - 此文是 GPT-6 系列的缓存策略说明，同时适用于 Codex 等 Agent 场景。

  2. OpenAI Blog · "Unrolling the Codex agent loop"（2026-01-23） - 原文：「When we get cache hits, sampling the model is linear rather than quadratic」（此句与 cwolferesearch 引用的 Codex 官方博客一致，原文出自 Codex 技术文档而非 Responses API 通用文档） - 详述 Codex prompt 构造方式：instructions（system/developer 消息）、tools（工具定义列表）、input（用户输入）三大字段，input 中再分层插入 sandbox description、agent files、环境信息等。 - 确认：model、tools、工具顺序改变均会破坏缓存。

  3. OpenAI Developers · Prompt Caching 官方文档 - 原文：「Pay the model's reduced cached‑input rate for reused tokens, discounted up to 95%」「Prompt caching is enabled by default for supported OpenAI models」「Cache reuse requires the entire rendered prefix to match」 - 明确哪些设置影响缓存：model、tools（含名称/描述/schema/顺序）、parallel_tool_calls、reasoning.effort（可通过 configuration_update 局部修改以避免破坏缓存）。 - 提供 prewarm（预热）机制：提前在 startup 阶段写入已知上下文，减少用户等待时间。

交叉验证：

  • Zentrik Blog · "How Codex prompt caching behaves across model and reasoning changes"（Aug 2026）：实测验证模型切换和 reasoning effort 变化对缓存的影响，提供 6 阶段缓存模型图。确认官方描述准确：工具变更 → 立即 miss；模型切换 → 冷切换。
  • ZenML · "Building Production‑Ready AI Agents: OpenAI Codex CLI Architecture"：引用官方文档说明 prompt 缓存优化实现线性而非二次性能，并详述 stateless request handling 与 Zero Data Retention 合规。
  • Technspire · "Prompt Caching in 2026: Anthropic, OpenAI, Azure Compared"（May 2026）：提供第三方实测对比，确认 OpenAI 缓存折扣 30–50% 在 Agent 循环中是常态，与官方文档口径一致。

关于 GPT-6 90% vs 通用 95% 折扣的说明：官方文档明确 GPT-6 系列（2026-09 发布）专属折扣上限为 90%；Responses API 通用文档描述的是更广泛模型的折扣上限 95%。两者均为官方口径，实际折扣取决于模型和使用场景。

上手步骤

1. 理解 Codex prompt 的分层结构

根据 OpenAI 官方博客，Codex 在发送第一次请求时，input 字段中按以下顺序插入（从稳定到多变）：

1. role=developer: sandbox 描述（仅针对 Codex 提供的 shell tool）
2. Agent files 内容
3. 当前环境信息
4. 用户请求 ← 唯一真正多变的内容

instructions 字段包含 system message 和 developer instructions，tools 字段包含工具定义（含 Codex 内置工具、Responses API 工具、用户通过 MCP 注册的工具）。

2. 遵循 append-only 更新原则

官方文档明确指出：不要直接修改已发送的 prompt 内容（如工具定义），而应在末尾追加新的 developer message 来覆盖旧指令。这样做的好处是不破坏已缓存的 prefix，后续请求仍能命中缓存。

错误做法：

# 直接修改 tool schema → cache miss
tools = [{ "name": "bash", "description": "run commands" }]

正确做法：

# 在末尾追加覆盖指令 → 保持 cache hit
{
  "role": "developer",
  "content": "Note: bash tool should now timeout after 30s not 60s."
}

3. 工具变更时保持 schema 稳定

cwolferesearch 强调：工具是 prompt 中体量最大、最影响缓存命中率的组件之一。官方文档补充：

  • 工具名称、描述、schema、顺序改变 → 立即 cache miss
  • 不要删除工具定义，用 allowed_tools 限制可用工具，或 tool_choice: none 替代
  • 尽量保持工具顺序不变

4. 利用 prewarm 预热缓存

官方文档建议：在用户发起第一个请求之前，预先发送包含共享指令、工具定义或参考材料的请求来写缓存。例如在 startup 阶段：

# 预热请求示例
response = client.responses.create(
    model="gpt-5.6-codex",
    instructions="You are a code review assistant.",  # 稳定系统消息
    tools=[...],  # 完整工具列表
    input="Warmup ping"  # 最简 input
)
# 预热后，第一个真实用户请求直接命中缓存

5. 调整 reasoning effort 而不破坏缓存（GPT-6 系列）

官方新增功能：无需重建整个缓存，即可通过 configuration_update 调整 reasoning.effort：

{
  "configuration_update": {
    "reasoning": {
      "effort": "high"  # 切到复杂推理，缓存仍有效
    }
  }
}

6. 监控与诊断

  • Prompt Caching Dashboard：platform.openai.com/usage?usage_section=prompt-caching 查看 hit rate 趋势和 input 组成。
  • Diagnostics API：返回 cache miss 原因（tools_changed、model_changed 等）和受影响 token 数量，用于精准定位问题。

坑与适用边界

坑 说明
cache boundary 以下的内容不受保护 只有前缀能命中缓存；用户消息及之后的内容每次都要重新计算。将稳定内容放在上面。
工具增删改均破坏缓存 哪怕只改一个工具的描述，prefix 就不匹配。生产环境应将工具定义视为「发布物」，不可随意修改。
模型切换代价高 model 改变会丢弃缓存。如果需要切换模型，应评估重新 prefill 的成本是否可接受。
不同模型折扣率不同 GPT-6 系列最高 90%，其他模型最高 95%。见 platform.openai.com/docs/pricing。
默认缓存窗口 30 分钟 1 小时缓存需要双倍写入费用，适合 human‑in‑the‑loop 或慢节奏交互。连续 Agent 循环建议保持请求间隔 < 30 分钟。
Agent 循环内的 compaction 会重置前缀 Codex 在上下文即将耗尽时会做 compaction（压缩历史），这会改变 prefix 导致 cache miss。这是预期行为，无法绕过。

适用场景：多轮交互的编码任务（Codex CLI/Cloud）、长上下文 RAG 流程、需要反复调用相同 system prompt 的评测任务。

不适用：单次请求、无共享前缀的一次性任务、工具定义频繁变更的开发调试阶段。

一句话结论

Codex Agent 的 prompt 由稳定前缀（system message + 工具定义 + 环境信息）和可变后缀（用户请求）构成，遵循 append-only 更新 + 工具 schema 稳定 + prewarm 预热 三大原则可将缓存命中率推到最高，实现输入 token 成本降低 70–90%；善用 OpenAI 的 Prompt Caching Dashboard 和 Diagnostics API 是持续优化的关键。