提示缓存

提示缓存意味着模型提供商可以跨轮次重用未更改的提示前缀（通常是系?开发者指令和其他稳定上下文），而不是每次都重新处理它们。第一个匹配请求写入缓?token（cacheWrite），后续匹配请求可以读回它们（cacheRead）?

为什么这很重要：降低 token 成本、更快的响应，以及更可预测的长会话性能。没有缓存，即使大多数输入未更改，重复提示也会在每轮支付完整提示成本?

此页面涵盖影响提示重用和 token 成本的所有缓存相关旋钮?

有关 Anthropic 定价详情，请参阅? https://docs.anthropic.com/docs/build-with-claude/prompt-caching

主要旋钮

cacheRetention（模型和每个 agent?

在模型参数上设置缓存保留?

agents:
  defaults:
    models:
      "anthropic/claude-opus-4-6":
        params:
          cacheRetention: "short" # none | short | long

每个 agent 覆盖?

agents:
  list:
    - id: "alerts"
      params:
        cacheRetention: "none"

配置合并顺序?

  1. agents.defaults.models["provider/model"].params
  2. agents.list[].params（匹?agent id；按键覆盖）

旧版 cacheControlTtl

仍接受旧值并映射?

  • 5m -> short
  • 1h -> long

新配置首?cacheRetention?

contextPruning.mode: "cache-ttl"

在缓?TTL 窗口后剪枝旧工具结果上下文，以便空闲后的请求不会重新缓存过大的历史?

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

请参阅会话剪枝了解完整行为?

心跳保持温暖

心跳可以保持缓存窗口温暖，并减少空闲间隔后重复缓存写入?

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

每个 agent 心跳?agents.list[].heartbeat 支持?

提供商行?

Anthropic（直?API?

  • 支持 cacheRetention?
  • 使用 Anthropic API 密钥认证配置文件，OpenClaw 在未设置时为 Anthropic 模型引用植入 cacheRetention: "short"?

Amazon Bedrock

  • Anthropic Claude 模型引用（amazon-bedrock/*anthropic.claude*）支持显?cacheRetention 直通?
  • ?Anthropic Bedrock 模型在运行时强制?cacheRetention: "none"?

OpenRouter Anthropic 模型

对于 openrouter/anthropic/* 模型引用，OpenClaw 在系?开发者提示块上注?Anthropic cache_control 以改善提示缓存重用?

其他提供?

如果提供商不支持此缓存模式，cacheRetention 无效果?

调优模式

混合流量（推荐的默认?

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

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"?
  • 仅对受益于温暖缓存的 agent 将心跳保持在 TTL 以下?

缓存诊断

OpenClaw 为嵌入式 agent 运行公开专用缓存跟踪诊断?

diagnostics.cacheTrace 配置

diagnostics:
  cacheTrace:
    enabled: true
    filePath: "~/.openclaw/logs/cache-trace.jsonl" # 可?
    includeMessages: false # 默认 true
    includePrompt: false # 默认 true
    includeSystem: false # 默认 true

默认值：

  • filePath：$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl
  • includeMessages：true
  • includePrompt：true
  • includeSystem：true

环境切换（一次性调试）

  • OPENCLAW_CACHE_TRACE=1 启用缓存跟踪?
  • OPENCLAW_CACHE_TRACE_FILE=/path/to/cache-trace.jsonl 覆盖输出路径?
  • OPENCLAW_CACHE_TRACE_MESSAGES=0|1 切换完整消息负载捕获?
  • OPENCLAW_CACHE_TRACE_PROMPT=0|1 切换提示文本捕获?
  • OPENCLAW_CACHE_TRACE_SYSTEM=0|1 切换系统提示捕获?

检查什?

  • 缓存跟踪事件?JSONL，包含分阶段快照，如 session:loaded、prompt:before、stream:context ?session:after?
  • 每轮缓存 token 影响在正常使用界面可见，通过 cacheRead ?cacheWrite（例?/usage full 和会话使用摘要）?

快速故障排?

  • 大多数轮次上 cacheWrite 很高：检查易失性系统提示输入并验证模型/提供商支持你的缓存设置?
  • cacheRetention 无效果：确认模型键匹?agents.defaults.models["provider/model"]?
  • Bedrock Nova/Mistral 请求带缓存设置：预期的运行时强制?none?

相关文档?