Promptcaching

Promptcaching stelt een modelprovider in staat om een ongewijzigd promptprefix (systeem-/ontwikkelaarsinstructies, tooldefinities en andere stabiele context) over meerdere beurten te hergebruiken, in plaats van dit bij elke aanvraag opnieuw te verwerken. Dit verlaagt de tokenkosten en latentie voor langlopende sessies met herhaalde context.

OpenClaw normaliseert providergebruik naar cacheRead en cacheWrite wanneer de upstream-API deze tellers beschikbaar stelt. Gebruiksoverzichten (/status en vergelijkbare overzichten) vallen terug op de laatste gebruiksvermelding in het transcript wanneer de momentopname van de actieve sessie geen cachetellers bevat; een actieve waarde groter dan nul heeft altijd voorrang op de terugvalwaarde.

Providerreferenties:

• Anthropic-promptcaching
• OpenAI-promptcaching

Primaire instellingen

cacheRetention

Waarden: "none" | "short" | "long". Configureerbaar als globale standaardwaarde, per model en per agent.

agents:  defaults:    params:      cacheRetention: "long" # none | short | long    models:      "anthropic/claude-opus-4-6":        params:          cacheRetention: "short" # overschrijft de globale standaardwaarde voor dit model  list:    - id: "alerts"      params:        cacheRetention: "none" # overschrijft beide standaardwaarden voor deze agent

Samenvoegvolgorde (later heeft voorrang):

1. agents.defaults.params - globale standaardwaarde voor alle modellen
2. agents.defaults.models["provider/model"].params - overschrijving per model
3. agents.list[].params - overschrijving per agent, gekoppeld op agent-id

Bron: src/agents/embedded-agent-runner/extra-params.ts (resolveExtraParams).

contextPruning.mode: "cache-ttl"

Snoeit oude context met toolresultaten nadat het TTL-venster van de cache is verstreken, zodat een aanvraag na een periode van inactiviteit een te grote geschiedenis niet opnieuw in de cache opslaat.

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

Zie Sessies snoeien voor het volledige gedrag.

Cache warm houden met Heartbeat

Heartbeat kan cachevensters warm houden en herhaalde schrijfbewerkingen naar de cache na perioden van inactiviteit verminderen. Globaal configureerbaar (agents.defaults.heartbeat) of per agent (agents.list[].heartbeat).

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

Providergedrag

Anthropic (directe API en Vertex AI)

• cacheRetention wordt ondersteund voor de providers anthropic en anthropic-vertex, en voor Claude-modellen op amazon-bedrock en aangepaste eindpunten die compatibel zijn met anthropic-messages wanneer cacheRetention expliciet is ingesteld.
• Wanneer de waarde niet is ingesteld, initialiseert OpenClaw cacheRetention: "short" voor directe Anthropic-verbindingen (alleen de providers anthropic en anthropic-vertex; andere routes uit de Anthropic-familie vereisen een expliciete waarde).
• Native antwoorden van Anthropic Messages stellen cache_read_input_tokens en cache_creation_input_tokens beschikbaar, toegewezen aan cacheRead en cacheWrite.
• cacheRetention: "short" wordt toegewezen aan de standaard tijdelijke cache van 5 minuten. cacheRetention: "long" vraagt expliciet om de TTL van 1 uur (cache_control: { type: "ephemeral", ttl: "1h" }). Een impliciete of door de omgeving aangestuurde lange bewaartijd (OPENCLAW_CACHE_RETENTION=long zonder expliciete cacheRetention) wordt alleen opgewaardeerd naar de TTL van 1 uur op hosts van api.anthropic.com of Vertex AI (aiplatform.googleapis.com / *-aiplatform.googleapis.com); andere hosts behouden de cache van 5 minuten.

Bron: src/agents/anthropic-payload-policy.ts (resolveAnthropicEphemeralCacheControl, isLongTtlEligibleEndpoint).

OpenAI (directe API)

• Promptcaching verloopt automatisch op ondersteunde recente modellen; OpenClaw voegt geen cachemarkeringen op blokniveau toe.
• OpenClaw verzendt prompt_cache_key om de cacheroutering over meerdere beurten stabiel te houden. Directe hosts van api.openai.com krijgen dit automatisch. OpenAI-compatibele proxy's (oMLX, llama.cpp en aangepaste eindpunten) moeten zich hiervoor aanmelden met compat.supportsPromptCacheKey: true in de modelconfiguratie; dit wordt voor een proxy nooit automatisch gedetecteerd.
• prompt_cache_retention: "24h" wordt alleen toegevoegd wanneer cacheRetention: "long" is geselecteerd en het gevonden eindpunt zowel de cachesleutel als lange bewaring ondersteunt (compat.supportsLongCacheRetention, standaard true; compatibiliteitsprofielen van Together AI en Cloudflare schakelen dit uit). cacheRetention: "none" onderdrukt beide velden.
• Cachetreffers worden beschikbaar gesteld via usage.prompt_tokens_details.cached_tokens (Chat Completions) of input_tokens_details.cached_tokens (Responses API), toegewezen aan cacheRead.
• Payloads van de Responses API kunnen ook input_tokens_details.cache_write_tokens beschikbaar stellen, toegewezen aan cacheWrite en geprijsd volgens het tarief voor cacheschrijfbewerkingen van het model; bij Responses-payloads waarin het veld ontbreekt, blijft cacheWrite op 0. De Chat Completions API van OpenAI documenteert of retourneert geen teller cache_write_tokens, maar OpenClaw leest daar toch prompt_tokens_details.cache_write_tokens voor OpenRouter-compatibele en DeepSeek-achtige proxy's die een afzonderlijk aantal schrijfbewerkingen rapporteren.
• In de praktijk gedraagt OpenAI zich meer als een cache voor het initiële prefix dan als Anthropic met hergebruik van de verschuivende volledige geschiedenis; zie Verwachtingen voor livegebruik van OpenAI hieronder.

Amazon Bedrock

• Anthropic Claude-modelreferenties (amazon-bedrock/*anthropic.claude*, plus AWS-prefixen voor systeeminferentieprofielen us./eu./global.anthropic.claude*) ondersteunen expliciete doorgifte van cacheRetention.
• Niet-Anthropic-modellen van Bedrock (bijvoorbeeld amazon.nova-*) worden tijdens runtime omgezet naar geen cachebewaring, ongeacht een eventueel geconfigureerde waarde voor cacheRetention.
• Ondoorzichtige ARN's van Bedrock-toepassingsinferentieprofielen (profiel-id's die geen claude bevatten) worden eveneens omgezet naar geen cachebewaring, tenzij cacheRetention expliciet is ingesteld, omdat de modelfamilie niet uitsluitend uit de ARN kan worden afgeleid.

OpenRouter

Voor modelreferenties van openrouter/anthropic/* voegt OpenClaw Anthropic-markeringen voor cache_control toe aan systeem-/ontwikkelaarspromptblokken, maar alleen wanneer de aanvraag nog steeds naar een geverifieerde OpenRouter-route gaat (openrouter op het standaardeindpunt, of een provider/basis-URL die naar openrouter.ai wordt omgezet). Als het model naar een willekeurige OpenAI-compatibele proxy-URL wordt omgeleid, stopt deze toevoeging.

contextPruning.mode: "cache-ttl" is toegestaan voor modelreferenties van openrouter/anthropic/*, openrouter/deepseek/*, openrouter/moonshot/*, openrouter/moonshotai/* en openrouter/zai/*, omdat deze routes promptcaching aan de providerzijde afhandelen zonder dat door OpenClaw toegevoegde markeringen nodig zijn.

Bron: extensions/openrouter/index.ts (OPENROUTER_CACHE_TTL_MODEL_PREFIXES).

Het opbouwen van de DeepSeek-cache op OpenRouter gebeurt op basis van beste inspanning en kan enkele seconden duren; een onmiddellijke vervolgaanvraag kan nog steeds cached_tokens: 0 tonen. Verifieer dit na een korte vertraging met een herhaalde aanvraag met hetzelfde prefix en gebruik usage.prompt_tokens_details.cached_tokens als signaal voor een cachetreffer.

Google Gemini (directe API)

• Direct Gemini-transport (api: "google-generative-ai") rapporteert cachetreffers via upstream cachedContentTokenCount, toegewezen aan cacheRead.
• Geschikte modelfamilies: gemini-2.5* en gemini-3* (Live-/previewvarianten buiten deze prefixovereenkomst zijn uitgesloten, bijvoorbeeld gemini-live-2.5-flash-preview).
• Wanneer cacheRetention is ingesteld op een geschikt model, maakt, hergebruikt en vernieuwt OpenClaw automatisch een cachedContents-resource voor de systeemprompt; een handmatige verwijzing naar gecachte inhoud is niet nodig. De TTL is 300s voor cacheRetention: "short" en 3600s voor "long".
• U kunt nog steeds een bestaande Gemini-verwijzing naar gecachte inhoud doorgeven als params.cachedContent (of de verouderde vorm params.cached_content); een expliciete verwijzing slaat het automatische cachebeheer volledig over.
• Dit staat los van promptprefixcaching van Anthropic/OpenAI: OpenClaw beheert voor Gemini een providereigen cachedContents-resource in plaats van inline cachemarkeringen toe te voegen.

Bron: src/agents/embedded-agent-runner/google-prompt-cache.ts.

Providers met een CLI-harnas (Claude Code, Gemini CLI)

CLI-backends die JSONL-gebruiksgebeurtenissen produceren (jsonlDialect: "claude-stream-json" of "gemini-stream-json") gebruiken een gedeelde gebruiksparser die meerdere veldnaamvarianten herkent, waaronder een gewone teller cached die aan cacheRead wordt toegewezen. Wanneer de JSON-payload van de CLI geen rechtstreeks veld voor invoertokens bevat, leidt OpenClaw dit af als input_tokens - cached. Dit is alleen normalisatie van gebruik; het maakt geen promptcachemarkeringen in Anthropic-/OpenAI-stijl voor deze via de CLI aangestuurde modellen.

Bron: src/agents/cli-output.ts (toCliUsage).

Andere providers

Als een provider geen van de bovenstaande cachemodi ondersteunt, heeft cacheRetention geen effect.

Cachegrens van de systeemprompt

OpenClaw splitst de systeemprompt bij een interne cacheprefixgrens in een stabiel prefix en een vluchtig suffix. Inhoud boven de grens (tooldefinities, metagegevens van Skills en werkruimtebestanden) wordt geordend om over meerdere beurten byte-identiek te blijven. Inhoud onder de grens (bijvoorbeeld HEARTBEAT.md, runtime-tijdstempels en andere metagegevens per beurt) kan veranderen zonder het gecachte prefix ongeldig te maken.

Belangrijke ontwerpkeuzes:

• Stabiele projectcontextbestanden van de werkruimte worden vóór HEARTBEAT.md geordend, zodat veranderingen door Heartbeat het stabiele prefix niet verbreken.
• De grens wordt toegepast bij de transportvormgeving voor de Anthropic-familie, OpenAI-familie, Google en CLI, zodat alle ondersteunde providers profiteren van dezelfde prefixstabiliteit.
• Codex Responses- en Anthropic Vertex-aanvragen worden verwerkt via grensbewuste cachevormgeving, zodat cachehergebruik afgestemd blijft op wat providers daadwerkelijk ontvangen.
• Vingerafdrukken van systeemprompts worden genormaliseerd (witruimte, regeleinden, door hooks toegevoegde context en ordening van runtimecapaciteiten), zodat semantisch ongewijzigde prompts over meerdere beurten dezelfde cache delen.

Als u onverwachte pieken in cacheWrite ziet na een wijziging in de configuratie of werkruimte, controleert u of de wijziging boven of onder de cachegrens terechtkomt. Het probleem wordt meestal opgelost door vluchtige inhoud onder de grens te plaatsen (of deze te stabiliseren).

Beschermingsmechanismen voor cachestabiliteit van OpenClaw

• Meegeleverde MCP-toolcatalogi worden vóór toolregistratie deterministisch gesorteerd (eerst op servernaam, daarna op toolnaam), zodat wijzigingen in de volgorde van listTools() het toolblok niet voortdurend wijzigen en promptcacheprefixen niet verbreken.
• Bij verouderde sessies met opgeslagen afbeeldingsblokken blijven de 3 meest recente voltooide beurten intact (waarbij alle voltooide beurten worden geteld, niet alleen die met afbeeldingen). Oudere, al verwerkte afbeeldingsblokken worden vervangen door een tekstmarkering, zodat bij vervolgaanvragen met veel afbeeldingen niet voortdurend grote, verouderde payloads opnieuw worden verzonden.

Afstemmingspatronen

Gemengd verkeer (aanbevolen standaardwaarde)

Gebruik een langlevende basisconfiguratie voor uw primaire agent en schakel caching uit voor agents die meldingen in pieken versturen:

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"

Basisconfiguratie met kosten als prioriteit

• Stel de basiswaarde cacheRetention: "short" in.
• Schakel contextPruning.mode: "cache-ttl" in.
• Houd Heartbeat alleen onder uw TTL voor agents die voordeel hebben van warme caches.

Live-regressietests

OpenClaw voert één gecombineerde live-regressiecontrole voor caches uit, die herhaalde prefixen, toolbeurten, afbeeldingsbeurten, MCP-achtige tooltranscripten en een Anthropic-controle zonder cache omvat.

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

Voer deze als volgt uit:

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

Het basislijnbestand slaat de meest recent waargenomen livewaarden op, samen met de providerspecifieke regressieondergrenzen waaraan de test toetst. Elke uitvoering gebruikt nieuwe sessie-id's en promptnaamruimten per uitvoering, zodat eerdere cachestatus het huidige monster niet verstoort. Anthropic en OpenAI gebruiken verschillende handhaving: het niet halen van een Anthropic-ondergrens is een harde regressie (de test mislukt), terwijl het niet halen van een OpenAI-ondergrens alleen wordt bewaakt (vastgelegd als waarschuwing en de uitvoering mislukt niet). Ze delen niet één drempelwaarde voor alle providers.

Verwachtingen voor livegebruik van Anthropic

• Verwacht expliciete opwarmwrites via cacheWrite.
• Verwacht bij herhaalde beurten dat vrijwel de volledige geschiedenis wordt hergebruikt, omdat Anthropic's cachebeheer het cachebreekpunt tijdens het gesprek steeds verder verplaatst.
• Ondergrenzen voor stabiele, tool-, afbeeldings- en MCP-achtige paden zijn strikte regressiepoorten.

Verwachtingen voor livegebruik van OpenAI

• Verwacht alleen cacheRead; bij Chat Completions blijft cacheWrite 0.
• Beschouw cachehergebruik bij herhaalde beurten als een providerspecifiek plateau, niet als met Anthropic vergelijkbaar voortschrijdend hergebruik van de volledige geschiedenis.
• Ondergrenzen dienen alleen voor bewaking (een gemiste ondergrens wordt als waarschuwing vastgelegd en laat de test niet mislukken) en zijn afgeleid van waargenomen livegedrag op gpt-5.4-mini:

De laatst waargenomen basiswaarden (uit live-cache-regression-baseline.ts) waren: stabiel voorvoegsel cacheRead=4864, trefpercentage 0.966; tooltranscript cacheRead=4608, trefpercentage 0.896; afbeeldingstranscript cacheRead=4864, trefpercentage 0.954; MCP-achtig transcript cacheRead=4608, trefpercentage 0.891.

Waarom de controles verschillen: Anthropic biedt expliciete cachebreekpunten en voortschrijdend hergebruik van de gespreksgeschiedenis, terwijl het effectief herbruikbare voorvoegsel van OpenAI in liveverkeer eerder een plateau kan bereiken dan de volledige prompt. Vergelijking van beide providers met één providersoverschrijdende procentuele drempel leidt tot foutieve regressiemeldingen.

Configuratie van diagnostics.cacheTrace

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

Standaardwaarden:

Omgevingsschakelaars (eenmalige foutopsporing)

Wat te controleren

• Cachetraceringsgebeurtenissen zijn JSONL-records met gefaseerde momentopnamen zoals session:loaded, prompt:before, stream:context en session:after.
• De invloed van cachetokens per beurt is zichtbaar in de normale gebruiksoverzichten: cacheRead en cacheWrite verschijnen in /usage tokens, /status, gebruikssamenvattingen van sessies en aangepaste indelingen voor messages.usageTemplate.
• Verwacht bij Anthropic zowel cacheRead als cacheWrite wanneer caching actief is.
• Verwacht bij OpenAI cacheRead bij cachetreffers; cacheWrite wordt alleen ingevuld voor payloads van de Responses API waarin dit veld is opgenomen (zie OpenAI hierboven).
• OpenAI retourneert ook tracerings- en snelheidslimietheaders zoals x-request-id, openai-processing-ms en x-ratelimit-*; gebruik deze voor het traceren van aanvragen, maar baseer de registratie van cachetreffers nog steeds op de gebruikspayload en niet op headers.

Snelle probleemoplossing

• Hoge cacheWrite bij de meeste beurten: controleer op veranderlijke invoer voor de systeemprompt; verifieer dat het model/de provider uw cache-instellingen ondersteunt.
• Hoge cacheWrite bij Anthropic: betekent vaak dat het cachebreekpunt terechtkomt op inhoud die bij elke aanvraag verandert.
• Lage cacheRead bij OpenAI: verifieer dat het stabiele voorvoegsel vooraan staat, dat het herhaalde voorvoegsel minstens 1024 tokens bevat en dat dezelfde prompt_cache_key wordt hergebruikt voor beurten die een cache moeten delen.
• Geen effect van cacheRetention: controleer of de modelsleutel overeenkomt met agents.defaults.models["provider/model"].
• Bedrock Nova-aanvragen met cache-instellingen: verwacht gedrag — deze worden tijdens runtime omgezet naar geen cachebewaring.

Gerelateerde documentatie:

• Anthropic
• Tokengebruik en kosten
• Sessies opschonen
• Configuratiereferentie voor de Gateway

Gerelateerd

• Tokengebruik en kosten
• API-gebruik en kosten