提示缓存

• Anthropic 提示缓存
• OpenAI 提示缓存。

​

主要控制项

​

cacheRetention

agents:
  defaults:
    params:
      cacheRetention: "long" # none | short | long
    models:
      "anthropic/claude-opus-4-6":
        params:
          cacheRetention: "short" # 覆盖此模型的全局默认值
  list:
    - id: "alerts"
      params:
        cacheRetention: "none" # 覆盖此代理的两个默认值

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

​

contextPruning.mode: "cache-ttl"

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

​

心跳保温

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

​

提供方行为

​

Anthropic（直接 API 和 Vertex AI）

• cacheRetention 支持 anthropic 和 anthropic-vertex 提供方，以及在 cacheRetention 明确设置时，支持 amazon-bedrock 上的 Claude 模型和自定义 anthropic-messages 兼容端点。
• 当未设置时，OpenClaw 会为直接 Anthropic（仅 anthropic 和 anthropic-vertex 提供方）默认填充 cacheRetention: "short"；其他 Anthropic 系路由需要显式指定值。
• 原生 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 分钟缓存。

​

OpenAI（直接 API）

• 支持的较新模型会自动启用提示缓存；OpenClaw 不会注入块级缓存标记。
• OpenClaw 会发送 prompt_cache_key 以保持跨轮次的缓存路由稳定。直接的 api.openai.com 主机会自动获得该设置。OpenAI 兼容代理（oMLX、llama.cpp、自定义端点）需要在模型配置中设置 compat.supportsPromptCacheKey: true 才会启用——对代理来说这不会被自动检测。
• 仅当选择 cacheRetention: "long"，且解析后的端点同时支持缓存键和长保留（compat.supportsLongCacheRetention，默认 true；Together AI 和 Cloudflare 兼容配置文件会禁用它）时，才会添加 prompt_cache_retention: "24h"。cacheRetention: "none" 会抑制这两个字段。
• 缓存命中会通过 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 风格代理。
• 实际上，OpenAI 更像是一个初始前缀缓存，而不是 Anthropic 那种会随完整历史记录移动复用的缓存——参见下方的 OpenAI 实时预期。

​

Amazon Bedrock

• Anthropic Claude 模型引用（amazon-bedrock/*anthropic.claude*，以及 AWS 系统推理配置文件前缀 us.／eu.／global.anthropic.claude*）支持显式 cacheRetention 透传。
• 非 Anthropic 的 Bedrock 模型（例如 amazon.nova-*）在运行时会解析为不保留缓存，无论配置了什么 cacheRetention 值。
• 模糊的 Bedrock 应用推理配置文件 ARN（不包含 claude 的配置文件 ID）也会在未显式设置 cacheRetention 时解析为不保留缓存，因为仅凭 ARN 无法推断模型家族。

​

OpenRouter

​

Google Gemini（直接 API）

• 直接 Gemini 传输（api: "google-generative-ai"）通过上游 cachedContentTokenCount 报告缓存命中，并映射为 cacheRead。
• 适用的模型家族：gemini-2.5* 和 gemini-3*（不包括该前缀匹配之外的 Live／preview 变体，例如 gemini-live-2.5-flash-preview）。
• 当在适用模型上设置了 cacheRetention 时，OpenClaw 会自动为 system prompt 创建、复用并刷新一个 cachedContents 资源——无需手动提供 cached-content 句柄。TTL 在 cacheRetention: "short" 时为 300s，在 "long" 时为 3600s。
• 你仍然可以通过 params.cachedContent（或旧版 params.cached_content）传入一个已存在的 Gemini cached-content 句柄；显式句柄会完全跳过自动缓存管理路径。
• 这与 Anthropic／OpenAI 的提示前缀缓存不同：OpenClaw 为 Gemini 管理的是提供方原生的 cachedContents 资源，而不是注入内联缓存标记。

​

CLI-harness 提供方（Claude Code、Gemini CLI）

​

其他提供方

​

系统提示缓存边界

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

​

OpenClaw 缓存稳定性防护

• 打包的 MCP 工具目录在工具注册之前会按确定性顺序排序（先按服务器名称，再按工具名称），因此 listTools() 顺序变化不会导致 tools 区块频繁变动并破坏提示缓存前缀。
• 具有持久化图片块的旧会话会保留最近 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"。
• 仅对能从预热缓存中受益的代理，将 heartbeat 保持在你的 TTL 以下。

​

实时回归测试

• 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

​

Anthropic 实时预期

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

​

OpenAI 实时预期

• 预期仅有 cacheRead；在 Chat Completions 上 cacheWrite 保持为 0。
• 将重复轮次的缓存复用视为提供方特定的平台期，而不是 Anthropic 风格的完整历史复用。
• 下限仅作监控（未达标会记录为警告，不会导致测试失败），这些数值依据 gpt-5.4-mini 的实时观测行为得出：

​

diagnostics.cacheTrace 配置

diagnostics:
  cacheTrace:
    enabled: true

​

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

​

需要检查什么

• 缓存跟踪事件采用 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 很高：检查是否存在易变的 system prompt 输入；确认模型/提供商支持你的缓存设置。
• Anthropic 中 cacheWrite 很高：通常表示缓存断点落在每次请求都会变化的内容上。
• OpenAI cacheRead 很低：确认稳定前缀位于最前面，重复前缀至少有 1024 个 token，并且在应共享缓存的轮次中复用了相同的 prompt_cache_key。
• cacheRetention 没有效果：确认模型键与 agents.defaults.models["provider/model"] 匹配。
• 带有缓存设置的 Bedrock Nova 请求：这是预期行为——它们在运行时会解析为无缓存保留。

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

​

相关

• Token 使用与成本
• API 使用与成本