OpenClaw Prompt Caching 設定指南：降低成本與提升回應速度

每次跟 AI 對話都要重複傳送一大堆 System Prompt 或背景資料，看著 Token 消耗飛快，心真的很痛。而且每次重新處理一樣的內容，回應速度也會變慢。這就是為什麼你需要 Prompt caching。

Prompt caching 代表模型供應商可以重複使用沒變過的 Prompt 前綴（通常是系統/開發者指令或其他穩定的上下文），而不需要每次都重新處理。第一個匹配的請求會寫入快取 Token (cacheWrite)，後續匹配的請求則可以直接讀取它們 (cacheRead)。

為什麼這很重要：這能顯著降低 Token 成本，並讓反應速度變得更快。如果沒有快取，即使大部分輸入內容沒變，重複的 Prompt 每次都要支付完整的費用。

這篇文章會介紹所有影響 Prompt 重複使用與 Token 成本的快取設定。

關於 Anthropic 的計費細節，請參考： https://docs.anthropic.com/docs/build-with-claude/prompt-caching

主要控制參數

cacheRetention (全域預設、模型與單一 Agent)

你可以為所有模型設定全域預設的快取保留時間：

agents:
  defaults:
    params:
      cacheRetention: "long" # none | short | long

針對特定模型進行覆蓋：

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.params (全域預設 — 套用到所有模型)
2. agents.defaults.models["provider/model"].params (特定模型覆蓋)
3. agents.list[].params (匹配的 Agent ID；依 Key 覆蓋)

舊版 cacheControlTtl

目前仍接受舊版數值並會自動對應：

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

新的設定建議優先使用 cacheRetention。

contextPruning.mode: "cache-ttl"

在快取 TTL 窗口過期後，會修剪舊的 Tool-result 上下文，這樣閒置後的請求就不會重新快取過大的歷史紀錄。

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

完整行為請參考 Session Pruning。

Heartbeat 保持熱度

Heartbeat 可以讓

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

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"

diagnostics:
  cacheTrace:
    enabled: true
    filePath: "~/.openclaw/logs/cache-trace.jsonl" # optional
    includeMessages: false # default true
    includePrompt: false # default true
    includeSystem: false # default true