Caching del prompt

La cache dei prompt consente a un provider di modelli di riutilizzare tra i turni un prefisso del prompt invariato (istruzioni di sistema/sviluppatore, definizioni degli strumenti, altro contesto stabile), anziché rielaborarlo a ogni richiesta. Questo riduce il costo in token e la latenza nelle sessioni di lunga durata con contesto ripetuto.

OpenClaw normalizza l'utilizzo dei provider in cacheRead e cacheWrite quando l'API upstream espone tali contatori. I riepiloghi dell'utilizzo (/status e simili) ricorrono all'ultima voce di utilizzo della trascrizione quando l'istantanea della sessione attiva non contiene i contatori della cache; un valore attivo diverso da zero ha sempre la precedenza sul valore di ripiego.

Riferimenti dei provider:

• Cache dei prompt di Anthropic
• Cache dei prompt di OpenAI

Impostazioni principali

cacheRetention

Valori: "none" | "short" | "long". Configurabile come valore predefinito globale, per modello e per agente.

agents:  defaults:    params:      cacheRetention: "long" # none | short | long    models:      "anthropic/claude-opus-4-6":        params:          cacheRetention: "short" # sostituisce il valore predefinito globale per questo modello  list:    - id: "alerts"      params:        cacheRetention: "none" # sostituisce entrambi i valori predefiniti per questo agente

Ordine di unione (l'ultimo ha la precedenza):

1. agents.defaults.params - valore predefinito globale per tutti i modelli
2. agents.defaults.models["provider/model"].params - sostituzione per modello
3. agents.list[].params - sostituzione per agente, associata tramite l'ID dell'agente

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

contextPruning.mode: "cache-ttl"

Elimina dal contesto i vecchi risultati degli strumenti dopo la scadenza della finestra TTL della cache, evitando che una richiesta successiva a un periodo di inattività rimetta in cache una cronologia sovradimensionata.

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

Per il comportamento completo, consulta Potatura delle sessioni.

Mantenimento della cache tramite Heartbeat

Heartbeat può mantenere attive le finestre della cache e ridurre le scritture ripetute nella cache dopo intervalli di inattività. È configurabile globalmente (agents.defaults.heartbeat) o per agente (agents.list[].heartbeat).

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

Comportamento dei provider

Anthropic (API diretta e Vertex AI)

• cacheRetention è supportato per i provider anthropic e anthropic-vertex e per i modelli Claude su amazon-bedrock e sugli endpoint personalizzati compatibili con anthropic-messages quando cacheRetention è impostato esplicitamente.
• Quando non è impostato, OpenClaw inizializza cacheRetention: "short" per Anthropic diretto (solo per i provider anthropic e anthropic-vertex; gli altri percorsi della famiglia Anthropic richiedono un valore esplicito).
• Le risposte native di Anthropic Messages espongono cache_read_input_tokens e cache_creation_input_tokens, associati rispettivamente a cacheRead e cacheWrite.
• cacheRetention: "short" corrisponde alla cache effimera predefinita di 5 minuti. cacheRetention: "long" richiede il TTL di 1 ora (cache_control: { type: "ephemeral", ttl: "1h" }) quando è impostato esplicitamente. Una conservazione lunga implicita o determinata dall'ambiente (OPENCLAW_CACHE_RETENTION=long senza un valore cacheRetention esplicito) passa al TTL di 1 ora solo sugli host api.anthropic.com o Vertex AI (aiplatform.googleapis.com / *-aiplatform.googleapis.com); gli altri host mantengono la cache di 5 minuti.

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

OpenAI (API diretta)

• La cache dei prompt è automatica sui modelli recenti supportati; OpenClaw non inserisce marcatori di cache a livello di blocco.
• OpenClaw invia prompt_cache_key per mantenere stabile l'instradamento della cache tra i turni. Gli host diretti api.openai.com lo ricevono automaticamente. I proxy compatibili con OpenAI (oMLX, llama.cpp, endpoint personalizzati) devono impostare compat.supportsPromptCacheKey: true nella configurazione del modello per abilitarlo: questa funzionalità non viene mai rilevata automaticamente per un proxy.
• prompt_cache_retention: "24h" viene aggiunto solo quando è selezionato cacheRetention: "long" e l'endpoint risolto supporta sia la chiave della cache sia la conservazione lunga (compat.supportsLongCacheRetention, true per impostazione predefinita; i profili di compatibilità Together AI e Cloudflare la disabilitano). cacheRetention: "none" elimina entrambi i campi.
• I riscontri positivi della cache vengono esposti tramite usage.prompt_tokens_details.cached_tokens (Chat Completions) o input_tokens_details.cached_tokens (Responses API), associati a cacheRead.
• I payload della Responses API possono anche esporre input_tokens_details.cache_write_tokens, associato a cacheWrite e tariffato secondo il costo di scrittura nella cache del modello; i payload di Responses che omettono il campo mantengono cacheWrite a 0. La Chat Completions API di OpenAI non documenta né emette un contatore cache_write_tokens, ma OpenClaw legge comunque prompt_tokens_details.cache_write_tokens in quel contesto per i proxy compatibili con OpenRouter e in stile DeepSeek che segnalano separatamente il numero di scritture.
• In pratica, OpenAI si comporta più come una cache del prefisso iniziale che come il riutilizzo progressivo dell'intera cronologia di Anthropic; consulta Aspettative operative di OpenAI più avanti.

Amazon Bedrock

• I riferimenti ai modelli Anthropic Claude (amazon-bedrock/*anthropic.claude*, inclusi i prefissi dei profili di inferenza di sistema AWS us./eu./global.anthropic.claude*) supportano il passaggio esplicito di cacheRetention.
• I modelli Bedrock non Anthropic (ad esempio amazon.nova-*) non applicano alcuna conservazione della cache in fase di esecuzione, indipendentemente dall'eventuale valore cacheRetention configurato.
• Anche gli ARN opachi dei profili di inferenza delle applicazioni Bedrock (ID dei profili che non contengono claude) non applicano alcuna conservazione della cache, a meno che cacheRetention non sia impostato esplicitamente, poiché la famiglia del modello non può essere dedotta dal solo ARN.

OpenRouter

Per i riferimenti ai modelli openrouter/anthropic/*, OpenClaw inserisce marcatori Anthropic cache_control nei blocchi del prompt di sistema/sviluppatore, ma solo quando la richiesta è ancora destinata a un percorso OpenRouter verificato (openrouter sul relativo endpoint predefinito oppure qualsiasi provider/URL di base che si risolva in openrouter.ai). Reindirizzando il modello a un URL proxy arbitrario compatibile con OpenAI, questo inserimento viene interrotto.

contextPruning.mode: "cache-ttl" è consentito per i riferimenti ai modelli openrouter/anthropic/*, openrouter/deepseek/*, openrouter/moonshot/*, openrouter/moonshotai/* e openrouter/zai/*, perché questi percorsi gestiscono la cache dei prompt sul lato del provider senza richiedere i marcatori inseriti da OpenClaw.

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

La costruzione della cache DeepSeek su OpenRouter avviene secondo il principio del massimo impegno e può richiedere alcuni secondi; una richiesta immediatamente successiva potrebbe ancora mostrare cached_tokens: 0. Verifica con una richiesta ripetuta con lo stesso prefisso dopo un breve intervallo, usando usage.prompt_tokens_details.cached_tokens come indicatore del riscontro positivo della cache.

Google Gemini (API diretta)

• Il trasporto diretto di Gemini (api: "google-generative-ai") segnala i riscontri positivi della cache tramite il valore upstream cachedContentTokenCount, associato a cacheRead.
• Famiglie di modelli idonee: gemini-2.5* e gemini-3* (sono escluse le varianti Live/anteprima che non corrispondono a tali prefissi, ad esempio gemini-live-2.5-flash-preview).
• Quando cacheRetention è impostato su un modello idoneo, OpenClaw crea, riutilizza e aggiorna automaticamente una risorsa cachedContents per il prompt di sistema; non è necessario alcun handle manuale per i contenuti memorizzati nella cache. Il TTL è 300s per cacheRetention: "short" e 3600s per "long".
• È comunque possibile passare un handle preesistente per i contenuti memorizzati nella cache di Gemini tramite params.cachedContent (o il precedente params.cached_content); un handle esplicito ignora completamente il percorso di gestione automatica della cache.
• Questa modalità è distinta dalla cache dei prefissi dei prompt di Anthropic/OpenAI: per Gemini, OpenClaw gestisce una risorsa cachedContents nativa del provider anziché inserire marcatori di cache inline.

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

Provider basati su harness CLI (Claude Code, Gemini CLI)

I backend CLI che emettono eventi di utilizzo JSONL (jsonlDialect: "claude-stream-json" o "gemini-stream-json") passano attraverso un parser di utilizzo condiviso che riconosce diverse varianti dei nomi dei campi, incluso un semplice contatore cached associato a cacheRead. Quando il payload JSON della CLI omette un campo diretto per i token di input, OpenClaw lo calcola come input_tokens - cached. Questa è solo una normalizzazione dell'utilizzo: non crea marcatori della cache dei prompt in stile Anthropic/OpenAI per questi modelli gestiti tramite CLI.

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

Altri provider

Se un provider non supporta nessuna delle modalità di cache descritte sopra, cacheRetention non produce alcun effetto.

Limite della cache del prompt di sistema

OpenClaw divide il prompt di sistema in un prefisso stabile e un suffisso variabile in corrispondenza di un limite interno del prefisso della cache. I contenuti sopra il limite (definizioni degli strumenti, metadati delle Skills, file dell'area di lavoro) vengono ordinati in modo da restare identici a livello di byte tra i turni. I contenuti sotto il limite (ad esempio HEARTBEAT.md, timestamp di esecuzione e altri metadati specifici del turno) possono cambiare senza invalidare il prefisso memorizzato nella cache.

Scelte progettuali principali:

• I file stabili del contesto di progetto dell'area di lavoro vengono ordinati prima di HEARTBEAT.md, così le variazioni di Heartbeat non invalidano il prefisso stabile.
• Il limite si applica alla strutturazione dei trasporti della famiglia Anthropic, della famiglia OpenAI, di Google e della CLI, così tutti i provider supportati beneficiano della stessa stabilità del prefisso.
• Le richieste Codex Responses e Anthropic Vertex vengono instradate attraverso una strutturazione della cache consapevole del limite, affinché il riutilizzo della cache rimanga allineato con ciò che i provider ricevono effettivamente.
• Le impronte digitali dei prompt di sistema vengono normalizzate (spaziatura, terminazioni di riga, contesto aggiunto dagli hook, ordinamento delle funzionalità di esecuzione), così i prompt semanticamente invariati condividono la cache tra i turni.

Se si osservano picchi imprevisti di cacheWrite dopo una modifica alla configurazione o all'area di lavoro, verificare se la modifica ricade sopra o sotto il limite della cache. Spostare i contenuti variabili sotto il limite, oppure stabilizzarli, in genere risolve il problema.

Protezioni di OpenClaw per la stabilità della cache

• I cataloghi degli strumenti MCP inclusi vengono ordinati in modo deterministico (prima per nome del server, poi per nome dello strumento) prima della registrazione degli strumenti, così le variazioni nell'ordine di listTools() non modificano continuamente il blocco degli strumenti né invalidano i prefissi della cache dei prompt.
• Le sessioni precedenti con blocchi immagine persistenti mantengono intatti i 3 turni completati più recenti (conteggiando tutti i turni completati, non solo quelli contenenti immagini). I blocchi immagine meno recenti e già elaborati vengono sostituiti con un marcatore testuale, così le richieste successive ricche di immagini non continuano a reinviare payload obsoleti di grandi dimensioni.

Modelli di configurazione

Traffico misto (impostazione predefinita consigliata)

Mantieni una base di lunga durata per l'agente principale e disabilita la cache per gli agenti di notifica con attività intermittente:

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"

Configurazione di base orientata ai costi

• Imposta il valore di base cacheRetention: "short".
• Abilita contextPruning.mode: "cache-ttl".
• Mantieni Heartbeat al di sotto del TTL solo per gli agenti che traggono vantaggio da cache già attive.

Test di regressione operativi

OpenClaw esegue un unico controllo di regressione operativo combinato della cache che copre prefissi ripetuti, turni con strumenti, turni con immagini, trascrizioni di strumenti in stile MCP e un controllo Anthropic senza cache.

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

Eseguilo con:

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

Il file di riferimento memorizza gli ultimi valori operativi osservati insieme alle soglie minime di regressione specifiche del provider verificate dal test. Ogni esecuzione usa ID di sessione e spazi dei nomi dei prompt nuovi e specifici dell'esecuzione, così lo stato della cache precedente non contamina il campione corrente. Anthropic e OpenAI applicano criteri diversi: il mancato raggiungimento di una soglia minima Anthropic costituisce una regressione bloccante (il test non riesce), mentre il mancato raggiungimento di una soglia minima OpenAI è solo oggetto di monitoraggio (viene registrato come avviso e non causa il fallimento dell'esecuzione). Non condividono un'unica soglia comune tra provider.

Aspettative operative di Anthropic

• Sono previste scritture esplicite di riscaldamento tramite cacheWrite.
• È previsto il riutilizzo di quasi tutta la cronologia nei turni ripetuti, perché il controllo della cache di Anthropic fa avanzare il punto di interruzione della cache nel corso della conversazione.
• Le soglie minime di riferimento per i percorsi stabili, degli strumenti, delle immagini e in stile MCP sono criteri rigidi di rilevamento delle regressioni.

Aspettative per OpenAI in produzione

• È previsto solo cacheRead; cacheWrite rimane 0 con Chat Completions.
• Il riutilizzo della cache nei turni ripetuti va considerato come un plateau specifico del provider, non come il riutilizzo mobile dell'intera cronologia in stile Anthropic.
• Le soglie minime sono solo di monitoraggio (un mancato raggiungimento viene registrato come avviso, non come errore del test) e derivano dal comportamento osservato in produzione su gpt-5.4-mini:

I valori di riferimento osservati più di recente (da live-cache-regression-baseline.ts) sono risultati: prefisso stabile cacheRead=4864, tasso di hit 0.966; trascrizione strumenti cacheRead=4608, tasso di hit 0.896; trascrizione immagini cacheRead=4864, tasso di hit 0.954; trascrizione in stile MCP cacheRead=4608, tasso di hit 0.891.

Motivo per cui le asserzioni differiscono: Anthropic espone punti di interruzione della cache espliciti e il riutilizzo mobile della cronologia della conversazione, mentre il prefisso effettivamente riutilizzabile da OpenAI nel traffico in produzione può raggiungere un plateau prima del prompt completo. Confrontare i due provider rispetto a un'unica soglia percentuale trasversale produce falsi rilevamenti di regressione.

Configurazione di diagnostics.cacheTrace

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

Valori predefiniti:

Variabili di ambiente (debug occasionale)

Cosa esaminare

• Gli eventi di tracciamento della cache sono in formato JSONL, con snapshot per fase come session:loaded, prompt:before, stream:context e session:after.
• L'impatto dei token della cache per turno è visibile nelle normali superfici di utilizzo: cacheRead e cacheWrite compaiono in /usage tokens, /status, nei riepiloghi di utilizzo delle sessioni e nei layout personalizzati di messages.usageTemplate.
• Per Anthropic, quando la memorizzazione nella cache è attiva, sono previsti sia cacheRead sia cacheWrite.
• Per OpenAI, è previsto cacheRead in caso di hit della cache; cacheWrite viene valorizzato solo nei payload della Responses API che lo includono (vedere OpenAI sopra).
• OpenAI restituisce inoltre intestazioni di tracciamento e di limite di frequenza, come x-request-id, openai-processing-ms e x-ratelimit-*; usarle per tracciare le richieste, ma la contabilizzazione degli hit della cache deve comunque provenire dal payload di utilizzo, non dalle intestazioni.

Risoluzione rapida dei problemi

• cacheWrite elevato nella maggior parte dei turni: verificare la presenza di input variabili nel prompt di sistema; verificare che il modello/provider supporti le impostazioni della cache.
• cacheWrite elevato su Anthropic: spesso significa che il punto di interruzione della cache si trova su contenuti che cambiano a ogni richiesta.
• cacheRead basso su OpenAI: verificare che il prefisso stabile sia all'inizio, che il prefisso ripetuto contenga almeno 1024 token e che lo stesso prompt_cache_key venga riutilizzato per i turni che devono condividere una cache.
• Nessun effetto da cacheRetention: verificare che la chiave del modello corrisponda a agents.defaults.models["provider/model"].
• Richieste Bedrock Nova con impostazioni della cache: comportamento previsto; in fase di esecuzione, per queste richieste non viene applicata alcuna conservazione della cache.

Documentazione correlata:

• Anthropic
• Utilizzo dei token e costi
• Potatura delle sessioni
• Riferimento per la configurazione del Gateway

Contenuti correlati

• Utilizzo dei token e costi
• Utilizzo delle API e costi