English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisहिन्दीالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiРусскийفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Technical reference

Memorizzazione nella cache dei prompt

La memorizzazione nella cache dei prompt significa che il provider del modello può riutilizzare prefissi di prompt invariati (di solito istruzioni di sistema/sviluppatore e altro contesto stabile) tra i turni invece di rielaborarli ogni volta. OpenClaw normalizza l'utilizzo del provider in cacheRead e cacheWrite quando l'API upstream espone direttamente quei contatori.

Le superfici di stato possono anche recuperare i contatori della cache dal log di utilizzo della trascrizione più recente quando mancano dallo snapshot della sessione live, così /status può continuare a mostrare una riga della cache dopo una perdita parziale dei metadati di sessione. I valori live non nulli esistenti della cache hanno comunque precedenza sui valori di fallback della trascrizione.

Perché è importante: costi dei token inferiori, risposte più rapide e prestazioni più prevedibili per sessioni di lunga durata. Senza cache, i prompt ripetuti pagano il costo completo del prompt a ogni turno anche quando la maggior parte dell'input non è cambiata.

Le sezioni seguenti coprono ogni opzione relativa alla cache che influisce sul riutilizzo dei prompt e sul costo dei token.

Riferimenti dei provider:

Opzioni principali

cacheRetention (predefinito globale, modello e per agente)

Imposta la conservazione della cache come predefinito globale per tutti i modelli:

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

Sovrascrittura per modello:

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

Sovrascrittura per agente:

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

Ordine di merge della configurazione:

  1. agents.defaults.params (predefinito globale — si applica a tutti i modelli)
  2. agents.defaults.models["provider/model"].params (sovrascrittura per modello)
  3. agents.list[].params (ID agente corrispondente; sovrascrive per chiave)

contextPruning.mode: "cache-ttl"

Elimina il vecchio contesto dei risultati degli strumenti dopo le finestre TTL della cache, così le richieste post-inattività non rimettono in cache una cronologia sovradimensionata.

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

Consulta Potatura della sessione per il comportamento completo.

Heartbeat keep-warm

Heartbeat può mantenere calde le finestre della cache e ridurre le scritture ripetute in cache dopo intervalli di inattività.

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

Heartbeat per agente è supportato in agents.list[].heartbeat.

Comportamento dei provider

Anthropic (API diretta)

  • cacheRetention è supportato.
  • Con i profili di autenticazione tramite chiave API Anthropic, OpenClaw imposta cacheRetention: "short" per i riferimenti ai modelli Anthropic quando non è impostato.
  • Le risposte native Messages di Anthropic espongono sia cache_read_input_tokens sia cache_creation_input_tokens, quindi OpenClaw può mostrare sia cacheRead sia cacheWrite.
  • Per le richieste native Anthropic, cacheRetention: "short" corrisponde alla cache effimera predefinita di 5 minuti, e cacheRetention: "long" passa al TTL di 1 ora solo sugli host diretti api.anthropic.com.

OpenAI (API diretta)

  • La cache dei prompt è automatica sui modelli recenti supportati. OpenClaw non deve iniettare marker di cache a livello di blocco.
  • OpenClaw usa prompt_cache_key per mantenere stabile il routing della cache tra i turni. Gli host diretti OpenAI usano prompt_cache_retention: "24h" quando viene selezionato cacheRetention: "long".
  • I provider Completions compatibili con OpenAI ricevono prompt_cache_key solo quando la loro configurazione del modello imposta esplicitamente compat.supportsPromptCacheKey: true. L'inoltro della conservazione lunga è una capacità separata: cacheRetention: "long" esplicito invia prompt_cache_retention: "24h" solo quando quella voce compat supporta anche la conservazione lunga della cache. Provider come Mistral possono abilitare le chiavi di cache impostando al tempo stesso compat.supportsLongCacheRetention: false per sopprimere il campo di conservazione lunga. cacheRetention: "none" sopprime entrambi i campi.
  • Le risposte OpenAI espongono i token di prompt memorizzati in cache tramite usage.prompt_tokens_details.cached_tokens (o input_tokens_details.cached_tokens sugli eventi dell'API Responses). OpenClaw lo mappa a cacheRead.
  • L'utilizzo di GPT-5.6 Responses può anche esporre input_tokens_details.cache_write_tokens. OpenClaw lo mappa a cacheWrite e lo prezza alla tariffa di scrittura in cache del modello; le risposte che omettono il campo mantengono cacheWrite a 0.
  • OpenAI restituisce header utili per tracciamento e limiti di frequenza, come x-request-id, openai-processing-ms e x-ratelimit-*, ma la contabilizzazione degli hit della cache deve provenire dal payload di utilizzo, non dagli header.
  • In pratica, OpenAI spesso si comporta come una cache del prefisso iniziale invece che come un riutilizzo mobile della cronologia completa in stile Anthropic. I turni di testo con prefisso lungo stabile possono arrivare vicino a un plateau di 4864 token in cache nelle sonde live attuali, mentre le trascrizioni ricche di strumenti o in stile MCP spesso si stabilizzano vicino a 4608 token in cache anche su ripetizioni esatte.

Anthropic Vertex

  • I modelli Anthropic su Vertex AI (anthropic-vertex/*) supportano cacheRetention nello stesso modo dell'Anthropic diretto.
  • cacheRetention: "long" corrisponde al vero TTL di 1 ora della cache dei prompt sugli endpoint Vertex AI.
  • La conservazione predefinita della cache per anthropic-vertex corrisponde ai predefiniti Anthropic diretti.
  • Le richieste Vertex vengono instradate attraverso una modellazione della cache consapevole dei confini, così il riutilizzo della cache resta allineato a ciò che i provider ricevono effettivamente.

Amazon Bedrock

  • I riferimenti ai modelli Anthropic Claude (amazon-bedrock/*anthropic.claude*) supportano il pass-through esplicito di cacheRetention.
  • I modelli Bedrock non Anthropic vengono forzati a cacheRetention: "none" in runtime.

Modelli OpenRouter

Per i riferimenti ai modelli openrouter/anthropic/*, OpenClaw inietta cache_control sui blocchi di prompt di sistema/sviluppatore per migliorare il riutilizzo della cache dei prompt solo quando la richiesta sta ancora puntando a una route OpenRouter verificata (openrouter sul suo endpoint predefinito, o qualsiasi provider/URL base che si risolva in openrouter.ai).

Per i riferimenti ai modelli openrouter/deepseek/*, openrouter/moonshot*/* e openrouter/zai/*, contextPruning.mode: "cache-ttl" è consentito perché OpenRouter gestisce automaticamente la cache dei prompt lato provider. OpenClaw non inietta marker Anthropic cache_control in quelle richieste.

La costruzione della cache DeepSeek è best-effort e può richiedere alcuni secondi. Un follow-up immediato può ancora mostrare cached_tokens: 0; verifica con una richiesta ripetuta con lo stesso prefisso dopo una breve attesa e usa usage.prompt_tokens_details.cached_tokens come segnale di hit della cache.

Se ripunti il modello a un URL proxy arbitrario compatibile con OpenAI, OpenClaw smette di iniettare quei marker di cache Anthropic specifici di OpenRouter.

Altri provider

Se il provider non supporta questa modalità di cache, cacheRetention non ha effetto.

API diretta Google Gemini

  • Il trasporto diretto Gemini (api: "google-generative-ai") segnala gli hit della cache tramite cachedContentTokenCount upstream; OpenClaw lo mappa a cacheRead.
  • Quando cacheRetention è impostato su un modello Gemini diretto, OpenClaw crea, riutilizza e aggiorna automaticamente risorse cachedContents per i prompt di sistema nelle esecuzioni Google AI Studio. Questo significa che non devi più precreare manualmente un handle di contenuto in cache.
  • Puoi comunque passare un handle di contenuto in cache Gemini preesistente come params.cachedContent (o legacy params.cached_content) sul modello configurato.
  • Questo è separato dalla cache dei prefissi di prompt Anthropic/OpenAI. Per Gemini, OpenClaw gestisce una risorsa cachedContents nativa del provider invece di iniettare marker di cache nella richiesta.

Utilizzo di Gemini CLI

  • L'output stream-json di Gemini CLI può esporre gli hit della cache tramite stats.cached; OpenClaw lo mappa a cacheRead. Le sovrascritture legacy --output-format json usano la stessa normalizzazione dell'utilizzo.
  • Se la CLI omette un valore diretto stats.input, OpenClaw deriva i token di input da stats.input_tokens - stats.cached.
  • Questa è solo normalizzazione dell'utilizzo. Non significa che OpenClaw stia creando marker di cache dei prompt in stile Anthropic/OpenAI per Gemini CLI.

Confine della cache del prompt di sistema

OpenClaw divide il prompt di sistema in un prefisso stabile e un suffisso volatile separati da un confine interno del prefisso di cache. Il contenuto sopra il confine (definizioni degli strumenti, metadati Skills, file dell'area di lavoro e altro contesto relativamente statico) è ordinato in modo da restare identico byte per byte tra i turni. Il contenuto sotto il confine (per esempio HEARTBEAT.md, timestamp di runtime e altri metadati per turno) può cambiare senza invalidare il prefisso in cache.

Scelte progettuali principali:

  • I file stabili di contesto del progetto nell'area di lavoro sono ordinati prima di HEARTBEAT.md, così il churn di Heartbeat non invalida il prefisso stabile.
  • Il confine viene applicato alla modellazione dei trasporti delle famiglie Anthropic, OpenAI, Google e CLI, così tutti i provider supportati beneficiano della stessa stabilità del prefisso.
  • Le richieste Codex Responses e Anthropic Vertex vengono instradate attraverso una modellazione della cache consapevole dei confini, così il riutilizzo della cache resta allineato a ciò che i provider ricevono effettivamente.
  • Le impronte dei prompt di sistema sono normalizzate (spazi, terminazioni di riga, contesto aggiunto da hook, ordinamento delle capacità di runtime) così i prompt semanticamente invariati condividono KV/cache tra i turni.

Se vedi picchi inattesi di cacheWrite dopo una modifica di configurazione o dell'area di lavoro, controlla se la modifica finisce sopra o sotto il confine della cache. Spostare contenuto volatile sotto il confine (o stabilizzarlo) spesso risolve il problema.

Guardie di stabilità della cache di OpenClaw

OpenClaw mantiene anche deterministiche diverse forme di payload sensibili alla cache prima che la richiesta raggiunga il provider:

  • I cataloghi degli strumenti MCP del bundle vengono ordinati deterministicamente prima della registrazione degli strumenti, così le modifiche all'ordine di listTools() non agitano il blocco strumenti e non invalidano i prefissi della cache dei prompt.
  • Le sessioni legacy con blocchi immagine persistiti mantengono intatti i 3 turni completati più recenti; i blocchi immagine più vecchi già elaborati possono essere sostituiti con un marker, così i follow-up ricchi di immagini non continuano a reinviare payload obsoleti di grandi dimensioni.

Pattern di ottimizzazione

Traffico misto (predefinito consigliato)

Mantieni una baseline di lunga durata sul tuo agente principale, disabilita la cache sugli agenti notificatori a raffica:

yaml
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"

Baseline orientata ai costi

  • Imposta la baseline cacheRetention: "short".
  • Abilita contextPruning.mode: "cache-ttl".
  • Mantieni Heartbeat sotto il tuo TTL solo per gli agenti che beneficiano di cache calde.

Diagnostica della cache

OpenClaw espone diagnostiche dedicate di traccia della cache per le esecuzioni degli agenti incorporati.

Per la normale diagnostica rivolta all'utente, /status e altri riepiloghi di utilizzo possono usare la voce di utilizzo della trascrizione più recente come fonte di fallback per cacheRead / cacheWrite quando la voce della sessione live non ha quei contatori.

Test di regressione live

OpenClaw mantiene un unico gate combinato di regressione live della cache per 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-baseline.ts

Esegui il gate live ristretto con:

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

Il file di baseline memorizza i numeri live osservati più di recente più i limiti minimi di regressione specifici del provider usati dal test. Il runner usa anche ID sessione e namespace dei prompt freschi per ogni esecuzione, così lo stato della cache precedente non contamina il campione di regressione corrente.

Questi test intenzionalmente non usano criteri di successo identici tra provider.

Aspettative live di Anthropic

  • Aspettati scritture di warmup esplicite tramite cacheWrite.
  • Aspettati un riuso quasi completo della cronologia nei turni ripetuti perché il controllo della cache di Anthropic fa avanzare il punto di interruzione della cache lungo la conversazione.
  • Le asserzioni live correnti usano ancora soglie di hit rate elevate per i percorsi stabile, tool e immagine.

Aspettative live di OpenAI

  • Aspettati solo cacheRead. cacheWrite resta 0.
  • Considera il riuso della cache su turni ripetuti come un plateau specifico del provider, non come un riuso mobile dell'intera cronologia in stile Anthropic.
  • Le asserzioni live correnti usano controlli di soglia minimi conservativi derivati dal comportamento live osservato su gpt-5.4-mini:
    • prefisso stabile: cacheRead >= 4608, hit rate >= 0.90
    • trascrizione tool: cacheRead >= 4096, hit rate >= 0.85
    • trascrizione immagine: cacheRead >= 3840, hit rate >= 0.82
    • trascrizione in stile MCP: cacheRead >= 4096, hit rate >= 0.85

La nuova verifica live combinata del 2026-04-04 ha prodotto:

  • prefisso stabile: cacheRead=4864, hit rate 0.966
  • trascrizione tool: cacheRead=4608, hit rate 0.896
  • trascrizione immagine: cacheRead=4864, hit rate 0.954
  • trascrizione in stile MCP: cacheRead=4608, hit rate 0.891

Il tempo wall-clock locale recente per il gate combinato era di circa 88s.

Perché le asserzioni differiscono:

  • Anthropic espone punti di interruzione della cache espliciti e il riuso mobile della cronologia della conversazione.
  • Il prompt caching di OpenAI è ancora sensibile al prefisso esatto, ma il prefisso effettivamente riutilizzabile nel traffico live Responses può raggiungere un plateau prima del prompt completo.
  • Per questo, confrontare Anthropic e OpenAI con una singola soglia percentuale cross-provider crea false regressioni.

Configurazione diagnostics.cacheTrace

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

Valori predefiniti:

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

Toggle env (debug una tantum)

  • OPENCLAW_CACHE_TRACE=1 abilita il tracciamento della cache.
  • OPENCLAW_CACHE_TRACE_FILE=/path/to/cache-trace.jsonl sovrascrive il percorso di output.
  • OPENCLAW_CACHE_TRACE_MESSAGES=0|1 attiva o disattiva la cattura completa del payload dei messaggi.
  • OPENCLAW_CACHE_TRACE_PROMPT=0|1 attiva o disattiva la cattura del testo del prompt.
  • OPENCLAW_CACHE_TRACE_SYSTEM=0|1 attiva o disattiva la cattura del prompt di sistema.

Cosa ispezionare

  • Gli eventi di tracciamento della cache sono JSONL e includono snapshot a stadi come session:loaded, prompt:before, stream:context e session:after.
  • L'impatto dei token di cache per turno è visibile nelle normali superfici d'uso tramite cacheRead e cacheWrite (per esempio /usage tokens, /status, riepiloghi d'uso della sessione e layout personalizzati messages.usageTemplate).
  • Per Anthropic, aspettati sia cacheRead sia cacheWrite quando la cache è attiva.
  • Per OpenAI, aspettati cacheRead sui cache hit. GPT-5.6 Responses può anche riportare cacheWrite mentre vengono scritti segmenti del prompt; altri payload Responses che omettono il contatore di scrittura lo mantengono a 0.
  • Se ti serve il tracciamento delle richieste, registra separatamente gli ID richiesta e gli header di rate limit rispetto alle metriche della cache. L'output attuale di cache-trace di OpenClaw è focalizzato sulla forma di prompt/sessione e sull'uso normalizzato dei token, più che sugli header grezzi delle risposte dei provider.

Risoluzione rapida dei problemi

  • cacheWrite alto nella maggior parte dei turni: controlla input volatili del prompt di sistema e verifica che il modello/provider supporti le tue impostazioni della cache.
  • cacheWrite alto su Anthropic: spesso significa che il punto di interruzione della cache sta finendo su contenuto che cambia a ogni richiesta.
  • cacheRead basso su OpenAI: verifica che il prefisso stabile sia all'inizio, che il prefisso ripetuto sia di almeno 1024 token e che lo stesso prompt_cache_key venga riutilizzato per i turni che dovrebbero condividere una cache.
  • Nessun effetto da cacheRetention: conferma che la chiave del modello corrisponda a agents.defaults.models["provider/model"].
  • Richieste Bedrock Nova/Mistral con impostazioni di cache: forza runtime previsto a none.

Documenti correlati:

Correlati

Was this useful?
On this page

On this page