OpenClaw Prompt Caching: Kosten senken & Latenz optimieren

Kennst du das Problem? Deine App schickt bei jedem API-Call riesige System-Prompts und Kontext-Daten mit, nur damit das Modell jedes Mal von vorne anfängt zu rechnen. Das treibt die Kosten hoch und macht die Latenz unnötig lang.

Prompt Caching ist hier die Lösung. Es bedeutet, dass der Model Provider unveränderte Prompt-Präfixe (meist System-Anweisungen oder stabiler Kontext) zwischen den Turns wiederverwendet. Der erste passende Request schreibt Cache-Tokens (cacheWrite), und spätere passende Requests lesen diese einfach wieder aus (cacheRead).

Warum das wichtig ist: Du profitierst von niedrigeren Token-Kosten, schnelleren Antworten, einer besseren Performance und einer höheren Vorhersehbarkeit bei langen Sessions. Ohne Caching zahlst du bei jedem Turn den vollen Preis für den Prompt, selbst wenn sich der Großteil des Inputs gar nicht geändert hat.

Diese Seite zeigt dir alle Cache-Einstellungen, die die Wiederverwendung von Prompts und die Token-Kosten beeinflussen.

Details zu den Anthropic-Preisen findest du hier: https://docs.anthropic.com/docs/build-with-claude/prompt-caching

Zentrale Stellschrauben

cacheRetention (globaler Standard, pro Modell, pro Provider oder pro Agent)

Setze die Cache-Retention als globalen Standard für alle Modelle:

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

Überschreibe die Einstellung pro Modell:

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

Überschreibung pro Agent:

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

Reihenfolge beim Zusammenführen der Konfiguration:

1. agents.defaults.params (globaler Standard — gilt für alle Modelle)
2. agents.defaults.models["provider/model"].params (Überschreibung pro Modell)
3. agents.list[].params (passende Agent-ID; überschreibt nach Key)
4. Runtime-Overrides über die API oder CLI.

Veraltetes cacheControlTtl

Legacy-Werte werden weiterhin akzeptiert und wie folgt zugeordnet:

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

Verwende für neue Konfigurationen lieber cacheRetention.

contextPruning.mode: "cache-ttl"

Entfernt alten Tool-Result-Kontext nach Ablauf der Cache-TTL-Fenster, damit Requests nach einer Ruhephase nicht unnöt

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

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