OpenClaw 🦞

提示缓存

提示缓存

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

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

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

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

主要旋钮

cacheRetention（模型和每代理）

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

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

每代理覆盖：

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

配置合并顺序：

  1. agents.defaults.models["provider/model"].params
  2. agents.list[].params（匹配的代理 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"

每代理心跳在 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 无效。

调优模式

混合流量（推荐默认）

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

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 为嵌入式代理运行公开专用的缓存跟踪诊断。

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，包括 staged snapshots 如 session:loaded、prompt:before、stream:context 和 session:after。
  • 每轮缓存 token 影响通过 cacheRead 和 cacheWrite 在正常使用表面可见（例如 /usage full 和会话使用量摘要）。

快速故障排除

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

相关文档：