Prompt 缓存

Prompt 缓存允许模型提供商在多个轮次之间复用未更改的 prompt 前缀（system/developer 指令、工具定义、其他稳定上下文），而不是在每次请求时重新处理它。这可以降低具有重复上下文的长时间运行会话的 Token 成本和延迟。

OpenClaw 会在上游 API 暴露这些计数器的地方，将提供商用量归一化为 cacheRead 和 cacheWrite。当实时会话快照缺少缓存计数器时，用量摘要（/status 及类似命令）会回退到最后一个 transcript 用量条目；非零的实时值始终优先于回退值。

提供商参考：

• Anthropic Prompt 缓存
• OpenAI Prompt 缓存

保持模型设置稳定¶

Prompt 缓存复用取决于提供商请求配置以及 prompt 文本。更改模型总会开启不同的缓存谱系。更改 thinking 或 reasoning 级别也可能使复用失效，即使 prompt 和模型保持不变。受支持的 native OpenAI Responses 请求会保留原始 effort，并附加轮次范围的配置控制；即使传输过期或 Gateway 重启，只要已保存的 replay 元数据和历史仍然匹配，也会如此。参见 OpenAI 推理变更。其他 OpenAI 模型或不兼容模式仍可能重新处理完整前缀。Anthropic 同样记录了当其 thinking 预算、effort 或模式变更时缓存失效的情况。

如果缓存连续性很重要，请在创建会话时选择模型和 thinking 级别，并保持两者稳定。对于计划中的变更，请开启新会话。使复用失效意味着下一次请求会未命中该缓存状态；这并不一定会在提供商的旧缓存条目正常过期前删除它。

主要配置项¶

Worker 轮次¶

通过 Gateway 代理的 worker 推理使用与本地轮次相同的 OpenAI 缓存键派生方式：显式 Gateway 键优先；否则，键会将 session ID 与权威 transcript 的 reset 和 compaction 边界计数组合起来。Gateway 会将这些事实与已接受的轮次一起保留，而不是接受 worker 提供的缓存键，或从裁剪后的 replay 历史中派生一个键。

交付的 worker 技能使用稳定的会话范围、内容寻址路径以及确定性的目录顺序。因此，未更改的技能会在轮次之间保持 system prompt 前缀稳定。技能刷新仍会交付当前已验证的字节；内容变更会故意更改该技能的路径。Worker 和本地 prompt 在范围上仍然不同：worker 会加载有界工作区 AGENTS.md 以及 Gateway 提供的指令，并附带其受限工具集。在运行时或工作区之间移动会话仍可能使其缓存前缀失效。

cacheRetention¶

取值："none" | "short" | "long"。可配置为全局默认值、按模型配置以及按 agent 配置。 "standard" 不是别名；请使用 "short" 表示提供商的默认缓存窗口。无效值会被忽略并给出警告。

agents:
  defaults:
    params:
      cacheRetention: "long" # none | short | long
    models:
      "anthropic/claude-opus-4-6":
        params:
          cacheRetention: "short" # overrides the global default for this model
  list:
    - id: "alerts"
      params:
        cacheRetention: "none" # overrides both defaults for this agent

合并顺序（后者优先）：

1. agents.defaults.params - 所有模型的全局默认值
2. agents.defaults.models["provider/model"].params - 按模型覆盖
3. agents.entries.*.models["provider/model"].params - agent 特定的按模型覆盖
4. agents.entries.*.params - agent 全局覆盖，按 agent id 匹配

来源：src/agents/embedded-agent-runner/extra-params.ts（resolveExtraParams）。

contextPruning.mode: "cache-ttl"¶

在缓存 TTL 窗口过期后，修剪旧的 tool-result 上下文，因此空闲后的请求不会重新缓存过大的历史。

agents:
  defaults:
    contextPruning:
      mode: "cache-ttl"
      ttl: "1h"

有关完整行为，参见 会话修剪。

Heartbeat 保活¶

Heartbeat 可以保持缓存窗口处于热状态，并减少空闲间隔后重复的缓存写入。可全局配置（agents.defaults.heartbeat）或按 agent 配置（agents.entries.*.heartbeat）。

agents:
  defaults:
    heartbeat:
      every: "55m"

提供商行为¶

Anthropic（直接 API 和 Vertex AI）¶

• 当缓存已启用且路由支持工具缓存控制时，工具前缀会与 system prompt 分开设置检查点。
• cacheRetention 受 anthropic 和 anthropic-vertex 提供商支持，并且当 cacheRetention 被显式设置时，也受 amazon-bedrock 上的 Claude 模型以及自定义 anthropic-messages 兼容端点支持。
• 当未设置时，OpenClaw 会为直接 Anthropic（仅限 anthropic 和 anthropic-vertex 提供商；其他 Anthropic 系路由需要显式值）设置 cacheRetention: "short"。
• 原生 Anthropic Messages 响应会暴露 cache_read_input_tokens 和 cache_creation_input_tokens，并映射到 cacheRead 和 cacheWrite。
• cacheRetention: "short" 映射到默认的 5 分钟临时缓存。显式设置 cacheRetention: "long" 时，会请求 1 小时 TTL（cache_control: { type: "ephemeral", ttl: "1h" }）。隐式/环境变量驱动的长保留（OPENCLAW_CACHE_RETENTION=long 且没有显式 cacheRetention）仅在 api.anthropic.com 或 Vertex AI（aiplatform.googleapis.com / *-aiplatform.googleapis.com）主机上升级到 1 小时 TTL；其他主机保持 5 分钟缓存。

来源：packages/ai/src/transports/anthropic-payload-policy.ts（resolveAnthropicEphemeralCacheControl、isLongTtlEligibleEndpoint）。

DeepInfra¶

对于 anthropic/* 模型，托管和 SDK Chat Completions 路径使用 共享标记布局。cacheRetention: "none" 会禁用这些标记。默认情况下，"short" 和 "long" 都使用没有 TTL 覆盖的临时标记；OpenClaw 不会假设该路由支持一小时。

Model Studio / DashScope（Qwen）¶

两个 Chat Completions 构建器会通过 compat.cacheControlFormat: "anthropic" 在原生或默认的 Model Studio / DashScope 路由上启用共享标记布局。显式的模型兼容设置优先于检测到的默认值。自定义代理端点不会获得自动格式默认值；仅当代理支持这些标记时，才显式设置 compat.cacheControlFormat: "anthropic"。

Model Studio 会将工具定义包含在系统缓存中，并忽略工具本身的标记，因此 OpenClaw 在检测到的原生路由上会省略该标记。Qwen3.5 及后续版本仅支持消息级检查点：将稳定与易变的系统内容拆分为块，并不能保证稳定块被独立复用。参见 Model Studio 显式缓存指南。

显式的 cacheRetention 值会到达此传输层，而无需启用 compat.supportsPromptCacheKey；请保持该标志未设置，因为此路由不需要 OpenAI 的 prompt_cache_key 或 prompt_cache_retention 字段。如果没有显式保留设置，传输层会保持其 "short" 默认值。Model Studio 使用五分钟显式缓存窗口，因此 "long" 会保留临时标记，而不会请求一小时 TTL。

要禁用 OpenClaw 的显式标记，请设置 cacheRetention: "none"。当前 compat.cacheControlFormat 模式仅接受 "anthropic"，不接受禁用值；省略它时会使用检测到的默认值。Alibaba 的自动隐式缓存是独立的，无法禁用。支持的模型、最小 Prompt 长度和缓存计费在 Model Studio 上下文缓存 中有说明。

OpenAI（直接 API）¶

• 在受支持的近期模型上，Prompt 缓存是自动的；OpenClaw 不会注入块级缓存标记。
• OpenClaw 会发送 prompt_cache_key，以跨轮次保持缓存路由稳定。当存在会话或显式缓存键时，发往直接 api.openai.com 主机的 Responses 和 Chat Completions 请求会自动获得该键；compat.supportsPromptCacheKey: false 会禁用它。OpenAI 兼容代理（oMLX、llama.cpp、自定义端点）需要在模型配置中设置 compat.supportsPromptCacheKey: true 才能选择加入——对于代理，这永远不会被自动检测。
• cacheRetention: "long" 会为两个 API 上的 GPT-5.6 及后续版本请求 prompt_cache_options: { ttl: "30m" }。更早的原生模型仅在 OpenAI 文档中记录的延长保留模型上接收 prompt_cache_retention: "24h"：GPT-5.5 / GPT-5.5 Pro、GPT-5.4、GPT-5.2、GPT-5.1 / Codex / Codex Max / Codex Mini / Chat Latest、GPT-5 / Codex 以及 GPT-4.1（包括带日期的快照）。其他更早的原生模型不会接收生命周期字段。参见 OpenAI 缓存生命周期。
• 生命周期字段需要同时支持缓存键和 compat.supportsLongCacheRetention（默认为 true；Together AI 和 Cloudflare 配置会禁用它）。选择加入的代理使用相同的 GPT-5.6+ TTL 映射，否则接收 "24h"；如果代理拒绝生命周期字段，请禁用长保留支持。
• cacheRetention: "short" 会发送键但不发送生命周期字段，使提供商的默认生命周期保持生效。cacheRetention: "none" 会抑制该键和两个生命周期字段；它不会禁用 OpenAI 的自动 Prompt 缓存。
• 原生 ChatGPT 支持的 Responses 路由会保留会话缓存键，遵循 none，并省略两个 OpenAI 生命周期字段。
• 缓存命中通过 usage.prompt_tokens_details.cached_tokens（Chat Completions）或 input_tokens_details.cached_tokens（Responses API）体现，并映射到 cacheRead。
• Responses API 负载还可以暴露 input_tokens_details.cache_write_tokens，映射到 cacheWrite，并按模型的缓存写入费率计费；省略该字段的 Responses 负载会将 cacheWrite 保持为 0。OpenAI 的 Chat Completions API 未记录或输出 cache_write_tokens 计数器，但 OpenClaw 仍会在那里读取 prompt_tokens_details.cache_write_tokens，以兼容报告单独写入计数的 OpenRouter 兼容代理和 DeepSeek 风格代理。
• 捕获的连续 Responses 请求体保留了逐字节相同的历史前缀，因此历史重写无法解释观察到的缺口。提供商断点位置可能影响报告的 cacheRead：OpenAI 在 Platform API 上为 GPT-5.6 及后续版本记录了消息末尾断点，而观察到 ChatGPT 支持的 Responses 路由以 1,024 个 Token 为步长报告命中。参见下文 OpenAI 实时预期。
• 在 Responses 路由上，整个系统 Prompt（包括缓存边界下方的易变后缀）都会作为 instructions 发送。后缀变更（日期切换、时区、提升级别、受监视会话、模型身份、Project Memory 事实）会在下一次请求时从变更点开始重新缓存；稳定前缀和工具不会像 Anthropic 检查点那样被拆分为单独的缓存块。缓存观察会将其报告为 systemPromptSuffix 变更。

Amazon Bedrock¶

• Anthropic Claude 模型引用（amazon-bedrock/*anthropic.claude*，以及 AWS 系统推理配置前缀 us./eu./global.anthropic.claude*）支持显式 cacheRetention 透传。
• 稳定系统前缀会与动态运行时添加内容分开设置检查点。会话检查点会随保留的历史推进，包括工具结果；临时运行时上下文载体仍位于缓存前缀之外。Bedrock Mantle 的 Anthropic Messages 传输也会保留单独的稳定系统边界。
• Nova Micro、Lite、Pro、Premier（amazon.nova-{micro,lite,pro,premier}-v1:0）以及 Nova 2 Lite（amazon.nova-2-lite-v1:0）支持在 system 和 messages 中设置显式检查点，包括其 AWS 地理推理配置和基础模型 ARN。short 和 long 均使用 Nova 的五分钟 TTL；none 会禁用显式检查点。OpenClaw 不会为 Nova 添加工具检查点。
• 其他非 Claude Bedrock 模型保持为 cacheRetention: "none"。
• Nova 显式缓存为选择加入：需将 cacheRetention 显式设置为 short 或 long。如果未设置保留，Nova 请求会保持现有负载布局且不包含检查点；默认 short 窗口和 OPENCLAW_CACHE_RETENTION 均不会启用 Nova 检查点。
• 不透明的 Bedrock 应用推理配置 ARN（不包含 claude 的配置 ID）同样会解析为无缓存保留，除非显式设置 cacheRetention，因为仅凭 ARN 无法推断模型系列。

AWS 的Prompt 缓存指南 以及 Micro、 Lite、 Pro、 Premier 和 Nova 2 Lite 的模型卡片列出了这些限制：最低 1K Token、四个检查点，以及 Nova 最多 20K 缓存 Token。提供商的 Token 限制仍然决定某个检查点是否会被缓存。

Nova 显式缓存尚未由 OpenClaw 维护者针对 AWS 进行实时验证。 在拥有 Bedrock 访问权限的维护者运行之前，AWS 实时验收证明仍是一个缺口。

OpenRouter¶

对于 openrouter/anthropic/* 模型引用，两个 Chat Completions 构建器都会应用共享标记布局，但仅当请求仍然指向已验证的 OpenRouter 路由（openrouter 在其默认端点上，或任何解析到 openrouter.ai 的提供商/基础 URL）时。将模型重新指向任意 OpenAI 兼容代理 URL 会停止自动标记注入。cacheRetention: "long" 在这些已验证路由上请求 ttl: "1h"；"none" 会禁用标记。参见 OpenRouter Prompt 缓存。

contextPruning.mode: "cache-ttl" 允许用于 openrouter/anthropic/*、openrouter/deepseek/*、openrouter/moonshot/*、openrouter/moonshotai/* 和 openrouter/zai/* 模型引用，因为这些路由处理提供商侧的 Prompt 缓存，而不需要 OpenClaw 注入的标记。

来源：extensions/openrouter/index.ts（OPENROUTER_CACHE_TTL_MODEL_PREFIXES）。

OpenRouter 上的 DeepSeek 缓存构建是尽力而为的，可能需要几秒钟；立即发出的后续请求可能仍显示 cached_tokens: 0。请在短暂延迟后使用重复的相同前缀请求进行验证，并以 usage.prompt_tokens_details.cached_tokens 作为缓存命中信号。

Google Gemini（直接 API）¶

• 直接 Gemini 传输（api: "google-generative-ai"）通过上游 cachedContentTokenCount 报告缓存命中，并映射到 cacheRead。
• 符合条件的模型系列：gemini-2.5* 和 gemini-3*（排除该前缀匹配之外的 Live/预览变体，例如 gemini-live-2.5-flash-preview）。
• 当在符合条件的模型上设置 cacheRetention 时，OpenClaw 会自动创建、复用并刷新一个 cachedContents 资源，其中包含缓存边界之上的稳定系统前缀，以及工具和工具配置——无需手动缓存内容句柄。cacheRetention: "short" 的 TTL 为 300s，"long" 为 3600s。
• 易变的系统后缀会先于其他运行时事实，位于当前轮次的隐藏运行时上下文载体内部。该载体是瞬时的，因此后缀变化会复用同一资源，而不会累积历史。稳定前缀或工具变化会创建新资源。如果创建失败或 Prompt 没有缓存边界，则完整系统 Prompt 保持内联。
• 你仍然可以将现有的 Gemini 缓存内容句柄作为 params.cachedContent（或旧版 params.cached_content）传入；显式句柄会完全跳过自动缓存管理路径。
• 这与 Anthropic/OpenAI 的 Prompt 前缀缓存不同：OpenClaw 为 Gemini 管理提供商原生的 cachedContents 资源，而不是注入内联缓存标记。

来源：src/agents/embedded-agent-runner/google-prompt-cache.ts。

CLI 框架提供商（Claude Code、Gemini CLI）¶

发出 JSONL 使用事件的 CLI 后端（jsonlDialect: "claude-stream-json" 或 "gemini-stream-json"）会经过一个共享的使用解析器，该解析器识别若干字段名变体，包括映射到 cacheRead 的普通 cached 计数器。当 CLI 的 JSON 负载省略直接的输入 Token 字段时，OpenClaw 会将其推导为 input_tokens - cached。这只是使用量规范化——它不会为这些 CLI 驱动的模型创建 Anthropic/OpenAI 风格的 Prompt 缓存标记。

Claude Code 在 --append-system-prompt-file 上没有由 OpenClaw 控制的 cache_control 断点，因此 OpenClaw 会在该传输中保留其完整系统 Prompt。当有界版本探测发现 Claude Code 2.1.98 或更新版本时，捆绑的 claude-cli 还会传递 --exclude-dynamic-system-prompt-sections。第一次 CLI 执行或直接 Anthropic OAuth 请求会启动共享探测；并发执行会复用它，而 API 目录发现不会启动它。该 Claude Code 标志只会将 Claude 自身的每台机器 cwd、环境、内存路径和 Git 状态部分移出其原生系统 Prompt；较旧、未知或失败的探测会保留已建立的 argv。cacheRetention 在此路径上仍然没有效果。

通过 CLI 后端分发的一次性辅助运行（例如 claude-cli 上的 Active Memory 召回）每次运行都会获得新的会话键。这些运行会在其唯一的用户轮次中携带 Runtime 事实行（agent、session、model、channel），而不是放在系统 Prompt 中，因此对同一 agent 的重复召回会发送字节相同的系统 Prompt，并可以复用 Claude 的 Prompt 缓存。普通 CLI 轮次会将 Runtime 行保留在系统 Prompt 中。

来源：src/agents/cli-output.ts（toCliUsage）。

其他提供商¶

如果提供商不支持上述任何缓存模式，cacheRetention 没有效果。

Chat Completions 缓存标记¶

具有 compat.cacheControlFormat: "anthropic" 的 OpenAI 兼容路由在受管传输、SDK 构建器和提供商包装器之间共享同一标记策略：

• 当路由支持工具标记时，最后一个工具定义会被标记；工具仍按名称排序。
• 稳定的系统/开发者块会被标记，易变后缀位于单独的未标记块中。
• 最新的符合条件的用户文本或工具结果会被标记，在工具循环和新轮次中推进，同时跳过瞬时的运行时上下文载体。

布局通常使用三个标记，并保持在四个断点预算内。cacheRetention: "none" 不发出任何标记。会话检查点覆盖所有先前的工具、系统内容和消息，因此更改易变 system 后缀仍会使该后续检查点失效；较早的稳定 system 检查点在后端支持块级缓存时仍可复用。后端 Token 最低要求和缓存生命周期仍然适用。

在 compat.requiresStringContent: true 下，托管请求将消息内容保留为字符串，并省略消息块标记，包括通过提供商包装器时。在支持的地方，工具定义标记仍会保留。

检测到的默认值仅在已验证的 OpenRouter 路由上请求 ttl: "1h"。对于支持一小时 Anthropic 缓存的自定义端点，请显式设置 compat.cacheControlFormat: "anthropic"、compat.supportsLongCacheRetention: true 和 cacheRetention: "long" 以发送该 TTL。省略该能力覆盖项会保留自定义端点标记但不带 TTL；将其设置为 false 即使在 OpenRouter 上也会禁用一小时 TTL。

系统 Prompt 缓存边界¶

OpenClaw 在内部缓存前缀边界处将系统 Prompt 拆分为 稳定前缀 和 易变后缀。边界之上的内容（工具定义、skills 元数据、工作区文件）会按顺序保持跨轮字节一致。边界之下的内容（例如运行时时间戳和其他每轮元数据）可以变化，而不会使缓存的前缀失效。

关键设计选择：

• 稳定的工作区项目上下文文件被排在易变的每轮元数据之前，因此常规变化不会破坏稳定前缀。
• 该边界适用于 Anthropic 系、OpenAI 系、Google 和 CLI 传输整形，因此所有受支持的提供商都能受益于相同的前缀稳定性。
• Codex Responses 和 Anthropic Vertex 请求通过边界感知的缓存整形进行路由，因此缓存复用与提供商实际接收的内容保持一致。
• 系统 Prompt 指纹会经过规范化处理（空白、换行符、hook 添加的上下文、运行时能力顺序），因此语义上未变化的 Prompt 可以在各轮之间共享缓存。

如果在配置或工作区更改后看到意外的 cacheWrite 峰值，请检查更改落在缓存边界之上还是之下。将易变内容移到边界之下（或使其稳定）通常可以解决问题。

没有显式消息缓存断点的 Chat Completions 路由会将有界的 Runtime facts 行移动到第一个发出的用户消息中。这会在兼容的本地服务器上保持会话标识符位于 system-and-tools 前缀之后。在后续消息中，该行仍保留在该第一条消息中。行为说明（包括 hook 添加、权限通知和 Git coauthor 指导）保留其 system/developer 角色。具有显式消息断点的路由保持其现有 system 布局。当前轮 Runtime Context 快照仍使用其独立的临时载体；它们不会成为永久首条消息上下文。

OpenClaw 缓存稳定性保护¶

• 活动 exec 会话、子代理状态和媒体生成进度通过当前用户消息之后的紧凑 Runtime Context 载体传递，因此更改不会在对话历史之前重写系统 Prompt。Project Memory 事实、特定于频道的 ACP 提示、委派/编排模式以及当前提升级别保持在系统 Prompt 缓存边界之下；静态召回、安全和能力指导保持在边界之上。
• 交付说明位于系统 Prompt 缓存边界之后。原生 Codex 在后期轮次上下文中携带当前交付和目标策略，因此在可用能力保持不变时，交替交付模式不会重建其静态 Prompt 或消息工具目录。实际能力变化仍会更新目录。
• 捆绑的 MCP 工具目录在工具注册前按确定性顺序排序（先按服务器名称，再按工具名称），因此 listTools() 顺序变化不会扰动工具块并破坏 Prompt 缓存前缀。
• 消息工具操作枚举在策略过滤后排序，使相同能力在频道发现顺序变化时保持稳定。
• 原生 Ollama 请求按名称对工具排序，因此发现顺序变化不会扰动工具前缀。
• 具有持久化图像块的旧版会话会保持 最近 3 个已完成轮次 完整（计算所有已完成轮次，而不仅仅是包含图像的轮次）。较早的已处理图像块会被文本标记替换，因此图像较多的后续消息不会持续重新发送大型过期负载。

调优模式¶

混合流量（推荐默认）¶

在主代理上保持长期基线，并在突发通知代理上禁用缓存：

agents:
  defaults:
    model:
      primary: "anthropic/claude-opus-4-6"
    models:
      "anthropic/claude-opus-4-6":
        params:
          cacheRetention: "long"
  list:
    - id: "research"
      default: true
      heartbeat:
        every: "55m"
    - id: "alerts"
      params:
        cacheRetention: "none"

成本优先基线¶

• 设置基线 cacheRetention: "short"。
• 启用 contextPruning.mode: "cache-ttl"。
• 仅对受益于热缓存的代理，将心跳保持在 TTL 以下。

实时回归测试¶

OpenClaw 运行一个合并的实时缓存回归门禁，覆盖重复前缀、工具轮次、图像轮次、MCP 风格工具转录以及 Anthropic 无缓存对照。

• src/agents/live-cache-regression.live.test.ts
• src/agents/test-helpers/live-cache-regression-runner.ts
• src/agents/live-cache-regression-baseline.ts

使用以下命令运行：

OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache

基线文件存储最近观察到的实时数值，以及测试所对照的特定提供商回归下限。每次运行都使用全新的每次运行会话 ID 和 Prompt 命名空间，因此之前的缓存状态不会污染当前样本。Anthropic 和 OpenAI 使用不同的执行方式：Anthropic 下限未达标是硬性回归（测试失败），而 OpenAI 下限未达标仅观察（记录为警告，不会导致运行失败）。它们不共享单一的跨提供商阈值。

Claude CLI 提示词复用拥有独立的 Docker 通道，因为它验证的是 Claude Code 的原生会话传输，而不是直接的 Anthropic API。在一次全新的回合和带有工具的预热恢复之后，它允许一次无工具的稳定恢复以热或冷方式运行，弄脏工作区，并要求在后续恢复中至少达到 90% 的复用，同时不轮换已稳定的实时会话代际。它还验证 thinking-level 变更会轮换代际，并且下一次稳定恢复能恢复至少 90% 的复用：

pnpm test:docker:live-cli-backend:claude:cache

Anthropic 实时预期¶

• 预期通过 cacheWrite 进行显式预热写入。
• 预期在重复回合中几乎完整复用历史，因为 Anthropic 的缓存控制会随对话推进缓存断点。
• 稳定、工具、图像和 MCP 风格通道的基线下限是硬性回归门槛。

OpenAI 实时预期¶

• 预期仅有 cacheRead；在 Chat Completions 中 cacheWrite 保持为 0。
• cacheRead 可能滞后于完整提示词，并以提供商大小的步长推进。下文观察到的区间并非未缓存输入的保证边界；路由、缓存可用性和提示词内容变化也可能降低复用。
• 下限仅用于观察（未达标会记录为警告，而不是测试失败），它们源自在 gpt-5.4-mini 上观察到的实时行为，自 2026.4.5 以来未变化：

最近观察到的基线数字（来自 live-cache-regression-baseline.ts，记录于 2026-04-04）为：稳定前缀 cacheRead=4864，命中率 0.966；工具转录 cacheRead=4608，命中率 0.896；图像转录 cacheRead=4864，命中率 0.954；MCP 风格转录 cacheRead=4608，命中率 0.891。

断言不同的原因：Anthropic 暴露显式缓存断点，而 OpenAI 报告的复用取决于可用的匹配缓存前缀。下文带日期的测量显示的是阶梯式增长，而非通用的命中率保证。将两家提供商对照单一的跨提供商百分比阈值进行比较会产生虚假回归。

在 2026-09-16 使用 openai/gpt-5.6-luna 通过由 ChatGPT 支持的 Responses 路由（transport: auto，默认 cacheRetention）观察到，同时使用 openclaw agent --local 和隔离的 Gateway：

• 每个报告的 cacheRead 对 1,024 取模均同余于 512（32256、33280、34304、35328），与本次样本中 1,024 token 的复用增量一致，但这并非固定提供商级断点策略的证明。一个提示词在四个回合中从 32658 增长到 33098 token 的会话，在提示词越过下一个区间之前一直报告 32256；回合之间暂停 60 秒也不会改变这一点。
• 连续请求体在新增追加项之前逐字节相同，包括重放的运行时上下文载体，这排除了这些捕获中的历史重写，但并未说明为何并非每个 token 都被复用。
• 在会话中途更改主机时区（这会重写 instructions 内的 ## Temporal Context 行）使一个回合在 32974 token 的提示词上从 32256 个缓存 token 降至 22016；下一个回合又回到 32256。
• 新会话有时会在首次请求时复用共享的指令与工具前缀，有时则冷启动，无论是否带有共享的 prompt_cache_key；路由看起来是会话粘性的，而不是由密钥驱动，这与 OpenAI 的说明一致：在 GPT-5.6 及后续版本上优化缓存不需要该密钥。

diagnostics.cacheTrace 配置¶

diagnostics:
  cacheTrace:
    enabled: true

enabled 默认为 false。缓存跟踪默认写入 $OPENCLAW_STATE_DIR/logs/cache-trace.jsonl，并默认包含消息、提示词文本和系统提示词。输出路径和载荷包含项的覆盖项是仅限环境变量的控制项，用于一次性调试。

环境变量开关（一次性调试）¶

检查内容¶

提示词缓存观察会为每个已完成的前台模型请求记录 input、cacheRead 和 cacheWrite，并同时记录其稳定系统前缀、易变后缀和工具指纹，并标记相对于上一请求的缓存读取下降，包括报告的零读取；计费总额仍单独计算。被标记的下降会列出自上一请求以来跟踪到的变更（model、cacheRetention、transport、streamStrategy、systemPrompt、systemPromptSuffix、tools、aggregateToolResultTruncation）。观察和警告需要启用缓存跟踪（diagnostics.cacheTrace.enabled 或 OPENCLAW_CACHE_TRACE=1）或调试日志，并且跟踪结果会在其尝试内标识每个请求。

• 缓存跟踪事件是 JSONL，包含诸如 session:loaded、prompt:before、stream:context 和 session:after 的分阶段快照。
• 每个回合的缓存 token 影响可在常规用量界面中看到：cacheRead 和 cacheWrite 会显示在 /usage tokens、/status、会话用量摘要以及自定义 messages.usageTemplate 布局中。
• 对于 Anthropic，当缓存激活时，预期同时出现 cacheRead 和 cacheWrite。
• 对于 OpenAI，缓存命中时预期出现 cacheRead；cacheWrite 仅在包含它的 Responses API 载荷中填充（见上文 OpenAI）。
• OpenAI 还会返回跟踪和速率限制头，例如 x-request-id、openai-processing-ms 和 x-ratelimit-*；请使用它们进行请求跟踪，但缓存命中统计仍应来自 usage 载荷，而不是来自头。

快速故障排查¶

• 大多数轮次中 cacheWrite 较高：检查易变的系统提示输入；验证模型/提供商是否支持您的缓存设置。
• Anthropic 上 cacheWrite 较高：通常意味着缓存断点落在每次请求都会变化的内容上。易变的系统后缀更改可能会保留稳定的系统前缀检查点，同时使后续对话检查点失效；缓存观察报告会将该更改报告为 systemPromptSuffix。
• OpenAI cacheRead 较低：验证稳定前缀位于开头，重复前缀至少为 1024 个 token，并且对于应共享缓存的轮次复用了相同的 prompt_cache_key。易变的系统后缀更改可能导致一轮下降，并在下一次请求时恢复；启用缓存跟踪，并在 [prompt-cache] 警告中查找 systemPromptSuffix。小幅或阶梯式不足可能反映提供商粒度，但不能排除提示更改或缓存可用性问题。
• cacheRetention 没有效果：确认模型键与 agents.defaults.models["provider/model"] 匹配。
• Bedrock Nova 请求没有缓存命中：将 cacheRetention 显式设置为 short 或 long，验证模型是上述受支持的变体之一，并检查前缀是否满足 AWS 的 token 限制；long 仍使用五分钟 TTL。

相关¶

• Token 使用与成本
• API 使用与成本
• 使用跟踪
• Anthropic
• 会话修剪
• 网关配置参考