Prompt Caching

Prompt Caching 指模型提供商可以在多个轮次之间复用未变化的提示前缀（通常是系统/开发者指令和其他稳定的上下文），而无需每次都重新处理。第一个匹配的请求会写入缓存 token（cacheWrite），后续匹配的请求可以读回它们（cacheRead）。

这样做的意义：更低的 token 成本、更快的响应速度，以及长期运行会话中更稳定的性能表现。如果不启用缓存，即使大部分输入没有变化，每一轮都需要支付完整的提示费用。

本页涵盖所有影响提示复用和 token 成本的缓存相关配置项。

关于 Anthropic 的定价详情，请参见： https://docs.anthropic.com/docs/build-with-claude/prompt-caching

主要配置项

cacheRetention（模型级别与 per-agent）

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

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

Per-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"

完整行为参见 Session Pruning。

心跳保温

心跳机制可以保持缓存窗口温热，减少空闲后重复写入缓存。

让你的龙虾保持活跃——配置心跳，缓存就不会轻易失效。

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

agents.list[].heartbeat 也支持 per-agent 心跳配置。

各提供商行为

Anthropic（直接 API）

• 支持 cacheRetention。
• 使用 Anthropic API Key auth profiles 时，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，属于正常行为。

相关文档：

• Anthropic
• Token 用量与费用
• Session Pruning
• Gateway 配置参考