Prompt 快取

Prompt 快取是指模型供應商可以在回合之間重用未改變的 prompt 前綴（通常是系統/開發者指示和其他穩定上下文），而不需每次重新處理。首次匹配的請求寫入快取 token（cacheWrite），後續匹配的請求可讀回（cacheRead）。

重要性在於：降低 token 成本、加快回應速度，以及長期 session 的效能更可預測。沒有快取的話，重複的 prompt 即使大部分輸入未改變，每回合仍需支付完整的 prompt 費用。

本頁面涵蓋所有影響 prompt 重用和 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"

設定合併順序：

agents.defaults.models["provider/model"].params
agents.list[].params（匹配的代理 id；依鍵覆寫）

舊有 `cacheControlTtl`

舊有值仍被接受並對應：

5m -> short
1h -> long

新設定偏好使用 cacheRetention。

`contextPruning.mode: "cache-ttl"`

在快取 TTL 視窗後裁剪舊的工具結果上下文，避免閒置後的請求重新快取過大的歷史。

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

完整行為參見 Session 裁剪。

心跳保溫

心跳可保持快取視窗溫暖，減少閒置間隙後重複的快取寫入。

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

逐代理心跳支援 agents.list[].heartbeat。

供應商行為

Anthropic（直接 API）

支援 cacheRetention。
使用 Anthropic API 金鑰 auth profiles 時，OpenClaw 在未設定時為 Anthropic 模型 ref 預設填入 cacheRetention: "short"。

Amazon Bedrock

Anthropic Claude 模型 ref（amazon-bedrock/*anthropic.claude*）支援明確的 cacheRetention 傳遞。
非 Anthropic Bedrock 模型在執行時強制為 cacheRetention: "none"。

OpenRouter Anthropic 模型

對 openrouter/anthropic/* 模型 ref，OpenClaw 在系統/開發者 prompt 區塊上注入 Anthropic cache_control 以改善 prompt 快取重用。

其他供應商

若供應商不支援此快取模式，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 切換完整訊息 payload 擷取。
OPENCLAW_CACHE_TRACE_PROMPT=0|1 切換 prompt 文字擷取。
OPENCLAW_CACHE_TRACE_SYSTEM=0|1 切換系統 prompt 擷取。

檢查要點

快取追蹤事件為 JSONL，包含 session:loaded、prompt:before、stream:context 和 session:after 等階段快照。
逐回合的快取 token 影響可透過正常的使用量介面中的 cacheRead 和 cacheWrite 查看（例如 /usage full 和 session 使用量摘要）。

快速故障排除

大部分回合都有高 cacheWrite：檢查系統 prompt 中的易變輸入，並確認模型/供應商支援你的快取設定。
cacheRetention 無效果：確認模型鍵匹配 agents.defaults.models["provider/model"]。
Bedrock Nova/Mistral 請求帶快取設定：預期的執行時強制為 none。

相關文件：