Prompt-Caching

Prompt-Caching bedeutet, dass der Modell-Provider unveraenderte Prompt-Praefixe (typischerweise System-/Developer-Anweisungen und anderer stabiler Kontext) ueber Turns hinweg wiederverwenden kann, anstatt sie jedes Mal neu zu verarbeiten. Die erste passende Anfrage schreibt Cache-Tokens (cacheWrite), und spaetere passende Anfragen koennen sie zuruecklesen (cacheRead).

Warum das wichtig ist: niedrigere Token-Kosten, schnellere Antworten und vorhersagbarere Performance fuer lang laufende Sessions.

Primaere Einstellungen

`cacheRetention` (Modell und per Agent)

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

Per-Agent-Override: agents.list[].params.cacheRetention

Config-Merge-Reihenfolge: 1. agents.defaults.models["provider/model"].params 2. agents.list[].params

Legacy `cacheControlTtl`

Legacy-Werte werden akzeptiert: 5m -> short, 1h -> long. Bevorzuge cacheRetention fuer neue Config.

`contextPruning.mode: "cache-ttl"`

Pruent alten Tool-Result-Kontext nach Cache-TTL-Fenstern.

Heartbeat Keep-Warm

Heartbeat kann Cache-Fenster warm halten und wiederholte Cache-Writes nach Idle-Luecken reduzieren.

Provider-Verhalten

Anthropic (direkte API): cacheRetention unterstuetzt. OpenClaw setzt cacheRetention: "short" fuer Anthropic-Model-Refs als Seed.
Amazon Bedrock: Anthropic-Claude-Model-Refs unterstuetzen explizites cacheRetention-Passthrough. Nicht-Anthropic-Bedrock-Modelle werden auf cacheRetention: "none" erzwungen.
OpenRouter Anthropic-Modelle: OpenClaw injiziert Anthropic cache_control auf System-/Developer-Prompt-Bloecke.
Andere Provider: Wenn der Provider diesen Cache-Modus nicht unterstuetzt, hat cacheRetention keinen Effekt.

Cache-Diagnose

OpenClaw stellt dedizierte Cache-Trace-Diagnose fuer eingebettete Agent-Runs bereit. Konfigurierbar via diagnostics.cacheTrace oder Umgebungsvariablen (OPENCLAW_CACHE_TRACE=1).

Schnelle Fehlerbehebung

Hoher cacheWrite bei den meisten Turns: volatile System-Prompt-Eingaben pruefen.
Kein Effekt von cacheRetention: Modell-Key ueberpruefen ob er agents.defaults.models["provider/model"] entspricht.
Bedrock Nova/Mistral-Requests mit Cache-Einstellungen: erwartete Runtime-Erzwingung auf none.