​

Prompt-Caching

• Anthropic Prompt-Caching: https://platform.claude.com/docs/en/build-with-claude/prompt-caching
• OpenAI Prompt-Caching: https://developers.openai.com/api/docs/guides/prompt-caching
• OpenAI-API-Header und Request-IDs: https://developers.openai.com/api/reference/overview
• Anthropic-Request-IDs und Fehler: https://platform.claude.com/docs/en/api/errors

​

Primäre Schalter

​

cacheRetention (globaler Standard, Modell und pro Agent)

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

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

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

1. agents.defaults.params (globaler Standard — gilt für alle Modelle)
2. agents.defaults.models["provider/model"].params (modellspezifische Überschreibung)
3. agents.list[].params (passende Agent-ID; überschreibt nach Schlüssel)

​

contextPruning.mode: "cache-ttl"

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

​

Heartbeat zum Warmhalten

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

​

Provider-Verhalten

​

Anthropic (direkte API)

• cacheRetention wird unterstützt.
• Bei Anthropic-Auth-Profilen mit API-Schlüssel setzt OpenClaw cacheRetention: "short" für Anthropic-Modellreferenzen, wenn kein Wert gesetzt ist.
• Native Anthropic-Messages-Antworten geben sowohl cache_read_input_tokens als auch cache_creation_input_tokens aus, sodass OpenClaw sowohl cacheRead als auch cacheWrite anzeigen kann.
• Für native Anthropic-Anfragen entspricht cacheRetention: "short" dem standardmäßigen kurzlebigen 5-Minuten-Cache, und cacheRetention: "long" erweitert nur auf direkten Hosts unter api.anthropic.com auf die 1-Stunden-TTL.

​

OpenAI (direkte API)

• Prompt-Caching erfolgt auf unterstützten aktuellen Modellen automatisch. OpenClaw muss keine Cache-Marker auf Blockebene einfügen.
• OpenClaw verwendet prompt_cache_key, um das Cache-Routing über mehrere Turns stabil zu halten, und verwendet prompt_cache_retention: "24h" nur dann, wenn cacheRetention: "long" auf direkten OpenAI-Hosts ausgewählt ist.
• OpenAI-Antworten geben gecachte Prompt-Token über usage.prompt_tokens_details.cached_tokens aus (oder input_tokens_details.cached_tokens bei Responses-API-Ereignissen). OpenClaw ordnet dies cacheRead zu.
• OpenAI gibt keinen separaten Zähler für Cache-Schreib-Token aus, daher bleibt cacheWrite auf OpenAI-Pfaden auch dann 0, wenn der Provider einen Cache aufwärmt.
• OpenAI gibt nützliche Tracing- und Rate-Limit-Header wie x-request-id, openai-processing-ms und x-ratelimit-* zurück, aber die Berechnung von Cache-Treffern sollte aus dem Usage-Payload kommen, nicht aus Headern.
• In der Praxis verhält sich OpenAI oft eher wie ein Anfangs-Präfix-Cache als wie eine Anthropic-artige Wiederverwendung des vollständigen beweglichen Verlaufs. Stabile Text-Turns mit langem Präfix landen in aktuellen Live-Probes oft nahe einem Plateau von 4864 gecachten Tokens, während tool-lastige oder MCP-artige Transkripte selbst bei exakten Wiederholungen oft eher bei 4608 gecachten Tokens plateauieren.

​

Anthropic Vertex

• Anthropic-Modelle auf Vertex AI (anthropic-vertex/*) unterstützen cacheRetention genauso wie direktes Anthropic.
• cacheRetention: "long" entspricht auf Vertex-AI-Endpunkten der echten 1-Stunden-TTL für Prompt-Caches.
• Die Standard-Cache-Aufbewahrung für anthropic-vertex entspricht den direkten Anthropic-Standards.
• Vertex-Anfragen werden durch boundary-bewusstes Cache-Shaping geleitet, sodass die Cache-Wiederverwendung mit dem übereinstimmt, was Provider tatsächlich erhalten.

​

Amazon Bedrock

• Anthropic-Claude-Modellreferenzen (amazon-bedrock/*anthropic.claude*) unterstützen die explizite Durchreichung von cacheRetention.
• Nicht-Anthropic-Bedrock-Modelle werden zur Laufzeit auf cacheRetention: "none" erzwungen.

​

OpenRouter-Anthropic-Modelle

​

Andere Provider

​

Google-Gemini-Direkt-API

• Der direkte Gemini-Transport (api: "google-generative-ai") meldet Cache-Treffer über das Upstream-Feld cachedContentTokenCount; OpenClaw ordnet dies cacheRead zu.
• Wenn cacheRetention für ein direktes Gemini-Modell gesetzt ist, erstellt, verwendet und aktualisiert OpenClaw automatisch cachedContents-Ressourcen für System-Prompts bei Google-AI-Studio-Läufen. Sie müssen also keinen Handle für gecachte Inhalte mehr manuell vorab erstellen.
• Sie können weiterhin einen bereits vorhandenen Gemini-Handle für gecachte Inhalte als params.cachedContent (oder legacy params.cached_content) für das konfigurierte Modell durchreichen.
• Das ist getrennt vom Anthropic-/OpenAI-Prompt-Präfix-Caching. Bei Gemini verwaltet OpenClaw eine providereigene cachedContents-Ressource, statt Cache-Marker in die Anfrage einzufügen.

​

Gemini-CLI-JSON-Nutzung

• Die Gemini-CLI-JSON-Ausgabe kann Cache-Treffer auch über stats.cached anzeigen; OpenClaw ordnet dies cacheRead zu.
• Wenn die CLI keinen direkten Wert für stats.input ausgibt, leitet OpenClaw die Eingabe-Tokens aus stats.input_tokens - stats.cached ab.
• Dies ist nur eine Nutzungsnormalisierung. Es bedeutet nicht, dass OpenClaw Anthropic-/OpenAI-artige Prompt-Cache-Marker für Gemini CLI erstellt.

​

Cache-Grenze für System-Prompts

• Stabile Workspace-Dateien des Projektkontexts werden vor HEARTBEAT.md angeordnet, damit Heartbeat-Änderungen das stabile Präfix nicht zerstören.
• Die Grenze wird über Anthropic-Familie, OpenAI-Familie, Google und CLI-Transport-Shaping hinweg angewendet, sodass alle unterstützten Provider von derselben Präfix-Stabilität profitieren.
• Codex-Responses- und Anthropic-Vertex-Anfragen werden durch boundary-bewusstes Cache-Shaping geleitet, damit die Cache-Wiederverwendung mit dem übereinstimmt, was Provider tatsächlich erhalten.
• Fingerprints von System-Prompts werden normalisiert (Whitespace, Zeilenenden, durch Hooks hinzugefügter Kontext, Reihenfolge von Runtime-Fähigkeiten), sodass semantisch unveränderte Prompts KV-/Cache über mehrere Turns hinweg gemeinsam nutzen.

​

OpenClaw-Schutzmechanismen für Cache-Stabilität

• Gebündelte MCP-Tool-Kataloge werden vor der Tool-Registrierung deterministisch sortiert, sodass Änderungen in der Reihenfolge von listTools() den Tool-Block nicht verändern und Prompt-Cache-Präfixe nicht zerstören.
• Legacy-Sitzungen mit persistenten Image-Blöcken behalten die 3 neuesten abgeschlossenen Turns unverändert bei; ältere, bereits verarbeitete Image-Blöcke können durch einen Marker ersetzt werden, damit bildlastige Folgeanfragen nicht weiterhin große veraltete Payloads erneut senden.

​

Tuning-Muster

​

Gemischter Verkehr (empfohlener Standard)

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"

​

Kostenorientierte Basis

• Setzen Sie als Basis cacheRetention: "short".
• Aktivieren Sie contextPruning.mode: "cache-ttl".
• Halten Sie den Heartbeat nur bei den Agenten unter Ihrer TTL, die von warmen Caches profitieren.

​

Cache-Diagnose

​

Live-Regressionstests

• src/agents/live-cache-regression.live.test.ts
• src/agents/live-cache-regression-baseline.ts

OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache

​

Anthropic-Live-Erwartungen

• Erwarten Sie explizite Aufwärm-Schreibvorgänge über cacheWrite.
• Erwarten Sie bei wiederholten Turns eine Wiederverwendung nahezu des gesamten Verlaufs, da Anthropic-Cache-Control den Cache-Breakpoint durch die Konversation verschiebt.
• Aktuelle Live-Assertions verwenden weiterhin hohe Trefferquoten-Schwellenwerte für stabile, Tool- und Image-Pfade.

​

OpenAI-Live-Erwartungen

• Erwarten Sie nur cacheRead. cacheWrite bleibt 0.
• Behandeln Sie die Cache-Wiederverwendung bei wiederholten Turns als providerspezifisches Plateau, nicht als Anthropic-artige Wiederverwendung des vollständigen beweglichen Verlaufs.
• Aktuelle Live-Assertions verwenden konservative Untergrenzen, die aus beobachtetem Live-Verhalten auf gpt-5.4-mini abgeleitet sind:
  • stabiles Präfix: cacheRead >= 4608, Trefferquote >= 0.90
  • Tool-Transkript: cacheRead >= 4096, Trefferquote >= 0.85
  • Image-Transkript: cacheRead >= 3840, Trefferquote >= 0.82
  • MCP-artiges Transkript: cacheRead >= 4096, Trefferquote >= 0.85

• stabiles Präfix: cacheRead=4864, Trefferquote 0.966
• Tool-Transkript: cacheRead=4608, Trefferquote 0.896
• Image-Transkript: cacheRead=4864, Trefferquote 0.954
• MCP-artiges Transkript: cacheRead=4608, Trefferquote 0.891

• Anthropic stellt explizite Cache-Breakpoints und eine bewegliche Wiederverwendung des Konversationsverlaufs bereit.
• OpenAI-Prompt-Caching bleibt weiterhin sensitiv gegenüber exakten Präfixen, aber das effektiv wiederverwendbare Präfix in Live-Responses-Datenverkehr kann früher plateauieren als der vollständige Prompt.
• Deshalb erzeugt ein Vergleich von Anthropic und OpenAI mit einem einzigen providerübergreifenden Prozent-Schwellenwert falsche Regressionen.

​

Konfiguration diagnostics.cacheTrace

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

• filePath: $OPENCLAW_STATE_DIR/logs/cache-trace.jsonl
• includeMessages: true
• includePrompt: true
• includeSystem: true

​

Env-Schalter (einmaliges Debugging)

• OPENCLAW_CACHE_TRACE=1 aktiviert Cache-Trace.
• OPENCLAW_CACHE_TRACE_FILE=/path/to/cache-trace.jsonl überschreibt den Ausgabepfad.
• OPENCLAW_CACHE_TRACE_MESSAGES=0|1 schaltet die Erfassung vollständiger Nachrichten-Payloads um.
• OPENCLAW_CACHE_TRACE_PROMPT=0|1 schaltet die Erfassung von Prompt-Text um.
• OPENCLAW_CACHE_TRACE_SYSTEM=0|1 schaltet die Erfassung von System-Prompts um.

​

Was Sie prüfen sollten

• Cache-Trace-Ereignisse sind JSONL und enthalten gestufte Snapshots wie session:loaded, prompt:before, stream:context und session:after.
• Die Cache-Token-Auswirkung pro Turn ist in normalen Nutzungsoberflächen über cacheRead und cacheWrite sichtbar (zum Beispiel /usage full und Sitzungsnutzungszusammenfassungen).
• Für Anthropic erwarten Sie sowohl cacheRead als auch cacheWrite, wenn Caching aktiv ist.
• Für OpenAI erwarten Sie cacheRead bei Cache-Treffern und cacheWrite bleibt 0; OpenAI veröffentlicht kein separates Feld für Cache-Schreib-Tokens.
• Wenn Sie Request-Tracing benötigen, protokollieren Sie Request-IDs und Rate-Limit-Header getrennt von Cache-Metriken. Die aktuelle Cache-Trace-Ausgabe von OpenClaw konzentriert sich auf Prompt-/Sitzungsform und normalisierte Token-Nutzung statt auf rohe Provider-Antwort-Header.

​

Schnelle Fehlerbehebung

• Hohes cacheWrite in den meisten Turns: prüfen Sie auf volatile Eingaben im System-Prompt und verifizieren Sie, dass Modell/Provider Ihre Cache-Einstellungen unterstützt.
• Hohes cacheWrite bei Anthropic: bedeutet oft, dass der Cache-Breakpoint auf Inhalt landet, der sich bei jeder Anfrage ändert.
• Niedriges cacheRead bei OpenAI: prüfen Sie, ob das stabile Präfix am Anfang steht, das wiederholte Präfix mindestens 1024 Tokens lang ist und derselbe prompt_cache_key für Turns wiederverwendet wird, die sich einen Cache teilen sollen.
• Keine Wirkung von cacheRetention: bestätigen Sie, dass der Modellschlüssel mit agents.defaults.models["provider/model"] übereinstimmt.
• Bedrock-Nova-/Mistral-Anfragen mit Cache-Einstellungen: erwartete Erzwingung zur Laufzeit auf none.

• Anthropic
• Token-Nutzung und Kosten
• Sitzungs-Pruning
• Referenz der Gateway-Konfiguration