SpyBara
Go Premium

prompt-caching.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 158 additions and 50 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Mon 14 22:58 Fri 18 23:58 Tue 22 23:59 Wed 23 23:57 Fri 25 23:58

Come Claude Code utilizza il prompt caching

Claude Code gestisce il prompt caching automaticamente. Scopri perché un cambio di modello attiva un turno lento senza cache, quanto costa /compact, perché le modifiche a CLAUDE.md non si applicano a metà sessione e come controllare il tasso di cache hit.

Il prompt caching rende Claude Code più veloce e più efficiente dal punto di vista dei costi. Senza caching, l'API rielaborerebbe la vostra cronologia completa ad ogni turno. Con il caching, riutilizza ciò che ha già elaborato, fattura la rilettura al tasso di token memorizzati nella cache e elabora completamente solo ciò che è cambiato.

Claude Code gestisce il prompt caching per voi, a meno che non lo disabiliti. È comunque utile sapere come funziona il prompt caching, perché alcune azioni invalidano la cache e rendono la risposta successiva più lenta e più costosa mentre la ricostruisce. Questa pagina copre quali azioni sono quelle, perché alcune impostazioni attendono un riavvio per applicarsi e come controllare le prestazioni della cache quando l'utilizzo sembra elevato.

Come è organizzata la cache

Ogni volta che invii un messaggio in Claude Code, effettua una nuova richiesta API. Il modello non ricorda nulla tra le richieste, quindi Claude Code rinvia il contesto completo: il prompt di sistema, il contesto del tuo progetto, ogni messaggio precedente e risultato dello strumento, e il tuo nuovo messaggio. Il nuovo contenuto viene aggiunto alla fine, il che significa che la maggior parte di ogni richiesta è identica a quella precedente. Il prompt caching è il modo in cui l'API evita di rielaborare la parte che non è cambiata.

L'API memorizza nella cache abbinando l'inizio di ogni richiesta, chiamato prefisso, al contenuto che ha elaborato di recente. Su un turno normale, il prefisso è l'intera richiesta precedente e solo lo scambio più recente è nuovo. La corrispondenza è esatta, quindi una modifica in qualsiasi punto del prefisso ricalcola tutto ciò che viene dopo. Non esiste caching per file o per segmento. Vedi come funziona il prompt caching nel riferimento API per il meccanismo sottostante.

Quattro turni mostrati come barre orizzontali crescenti. La richiesta di ogni turno contiene tutto dal turno precedente più lo scambio più recente aggiunto alla fine. Nei turni due e tre, il prefisso invariato viene letto dalla cache e solo il nuovo scambio viene elaborato. Nel turno quattro, il prompt di sistema è cambiato, quindi il prefisso non corrisponde più e l'intera richiesta viene rielaborata e scritta. Quattro turni mostrati come barre orizzontali crescenti. La richiesta di ogni turno contiene tutto dal turno precedente più lo scambio più recente aggiunto alla fine. Nei turni due e tre, il prefisso invariato viene letto dalla cache e solo il nuovo scambio viene elaborato. Nel turno quattro, il prompt di sistema è cambiato, quindi il prefisso non corrisponde più e l'intera richiesta viene rielaborata e scritta.

Per ottenere il massimo dall'abbinamento dei prefissi, Claude Code ordina ogni richiesta in modo che il contenuto che cambia raramente tra i turni venga per primo:

Layer Contenuto Cambia quando
System prompt Istruzioni principali, definizioni degli strumenti, stile di output Il set di definizioni degli strumenti caricati cambia, cambi lo stile di output, o Claude Code viene aggiornato
Project context CLAUDE.md, memoria automatica, regole non scoped La sessione inizia, o dopo /clear o /compact
Conversation I tuoi messaggi, le risposte di Claude, i risultati degli strumenti Ogni turno

Una modifica al layer della conversazione lascia il prompt di sistema e il contesto del progetto memorizzati nella cache. Una modifica al prompt di sistema invalida tutto, perché tutto il contenuto successivo ora si trova dietro un prefisso diverso. La terza colonna fornisce trigger comuni piuttosto che un elenco esaustivo, e le sezioni seguenti coprono l'insieme completo.

La regola di abbinamento dei prefissi spiega la maggior parte dei comportamenti in questa pagina. Plan mode e skill loading, ad esempio, aggiungono le loro istruzioni come messaggi di conversazione, quindi il prefisso memorizzato nella cache rimane intatto.

Due impostazioni non compaiono nella tabella dei layer ma comunque influenzano ciò che rimane memorizzato nella cache:

  • Model: ogni modello ha la sua cache. Cambiare modelli ricalcola l'intera richiesta anche quando il contenuto è identico. Vedi Switching models di seguito.
  • Effort level: sulla maggior parte dei modelli, ogni livello di sforzo ha la sua cache, quindi cambiare lo sforzo a metà sessione ricalcola l'intera richiesta. Su Fable 5.1 con una chiave API o un abbonamento Claude, la cache rimane intatta per impostazione predefinita. Vedi Changing effort level di seguito.

Dove vive la cache

Il caching avviene lato server, nell'infrastruttura che serve il tuo modello. Dove si trova dipende da come ti autentichi:

  • API key, Claude subscription, o Claude Platform on AWS: la cache vive nell'infrastruttura di Anthropic, accessibile tramite Claude API
  • Amazon Bedrock o Google Cloud's Agent Platform: la cache vive nell'infrastruttura di servizio del tuo provider cloud
  • Microsoft Foundry: dipende dall'opzione di hosting della distribuzione. Le distribuzioni ospitate su Azure vengono servite sull'infrastruttura Azure; le distribuzioni ospitate su Anthropic vengono servite sull'infrastruttura di Anthropic
  • Custom ANTHROPIC_BASE_URL o LLM gateway: la cache vive dove vengono inoltrate le tue richieste, e se il caching funziona dipende dal gateway

Claude Code inoltre aggiunge il contesto di sistema a metà conversazione, come notifiche di cambio file, e contrassegna quel blocco per il caching su ogni provider e connessione.

All'endpoint proprio del provider, Amazon Bedrock e il suo endpoint Mantle, Google Cloud's Agent Platform, e Microsoft Foundry memorizzano nella cache il blocco nello stesso modo in cui lo fa Claude API.

Quando le tue richieste passano attraverso un LLM gateway, un ANTHROPIC_BASE_URL personalizzato, o un override di URL di base del provider cloud come ANTHROPIC_BEDROCK_BASE_URL, ciò che rimane memorizzato nella cache dipende da come il gateway gestisce i marcatori cache_control che Claude Code invia:

  • Li inoltra invariati: il blocco e la tua conversazione vengono memorizzati nella cache nello stesso modo dell'endpoint proprio del provider.
  • Rifiuta la richiesta contrassegnata con un errore 400 che nomina cache_control: Claude Code rinvia la richiesta con il marcatore spostato dal blocco al tuo ultimo messaggio di conversazione, e lo mantiene lì per il resto della conversazione. Il blocco viene fatturato come input non memorizzato nella cache; la tua conversazione rimane memorizzata nella cache.
  • Rimuove i marcatori mentre restituisce successo: l'intera cronologia della conversazione viene fatturata come input non memorizzato nella cache ad ogni turno. Un gateway che converte il contenuto del sistema in forma di blocco in una stringa semplice rilascia il marcatore nello stesso modo.

Per ciò che ogni provider memorizza ed elabora, vedi data usage. Ovunque viva la cache, le voci scadono dopo un periodo di inattività, e Cache lifetime di seguito copre il TTL e come estenderlo.

Azioni che invalidano la cache

Queste azioni causano la mancanza di parte o tutta la cache nella richiesta successiva. Vedi un turno più lento e più costoso una sola volta, dopo il quale il nuovo prefisso viene memorizzato nella cache. La maggior parte di essi sono evitabili a metà compito una volta che sai che hanno un costo. Un cambio di modello può sembrare gratuito finché non noti il turno più lento che segue.

Switching models

Ogni modello ha la sua cache. Cambiare con /model significa che la richiesta successiva legge l'intera cronologia della conversazione senza cache hit, anche se il contenuto è identico.

Quando esegui /model al terminale, Claude Code ti chiede di confermare il cambio solo mentre la cache è ancora calda. La cache rimane calda per un cache TTL dopo che Claude Code ha inviato l'ultima richiesta in questa conversazione o Claude ha risposto. Una volta che quel tempo passa, la cache è scaduta, quindi Claude Code cambia senza chiedere.

Prima della v2.1.238, Claude Code non controllava il cache TTL e chiedeva anche dopo che la cache era scaduta.

Puoi anche richiedere questa conferma o saltarla con un hook PreModelSwitch.

L'impostazione opusplan model si risolve in Opus durante la modalità piano e Sonnet durante l'esecuzione, quindi ogni toggle della modalità piano è un cambio di modello e avvia una cache fresca.

Il fallback automatico del modello su modelli Fable e Opus 5 è anche un cambio di modello. Quando un classificatore di sicurezza contrassegna una richiesta in una categoria che ha un modello di fallback, Claude Code riesegue la richiesta su quel modello e la sessione continua lì.

Quando una skill o il frontmatter di un comando nomina un model diverso dal modello corrente della sessione, quel turno è anche un cambio di modello: la richiesta successiva legge l'intera cronologia della conversazione senza cache hit. Il modello della sessione riprende al tuo prossimo prompt. Una skill context: fork imposta il modello del subagent con fork invece.

Changing effort level

Sulla maggior parte dei modelli, cambiare il livello di effort a metà sessione significa che la richiesta successiva legge l'intera cronologia della conversazione senza cache hit. Mentre la cache è ancora calda, Claude Code ti chiede di confermare il cambio per primo.

Su Fable 5.1 con una chiave API o un abbonamento Claude, cambiare effort mantiene la cache, e Claude Code applica il nuovo livello senza chiedere. Questo non si applica su Amazon Bedrock, su Google Cloud's Agent Platform, o su un gateway di app Claude, o quando imposti CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS o la tua organizzazione ha una configurazione HIPAA.

Prima della v2.1.260, cambiare effort su Fable 5.1 con una chiave API o un abbonamento Claude invalidava anche la cache.

Turning on fast mode

L'abilitazione della fast mode aggiunge un'intestazione di richiesta che fa parte della chiave della cache, quindi la prima richiesta che Claude Code invia con la fast mode attiva legge l'intera cronologia della conversazione senza cache hit. Claude Code imposta quell'intestazione una volta quando un turno inizia e la mantiene per l'intero turno, quindi quando attivi la fast mode mentre Claude sta lavorando, la cache miss dall'intestazione accade sulla prima richiesta del tuo turno successivo. Quei token di input non memorizzati nella cache vengono fatturati alle tariffe della fast mode, motivo per cui attivarla all'inizio di una sessione costa meno che attivarla in profondità in una sessione lunga. Se il tuo modello corrente non supporta la fast mode, l'abilitazione della fast mode cambia anche il tuo modello, e quel cambio avvia una cache fresca di per sé dalla richiesta successiva nel turno in esecuzione.

Il costo si applica una volta per conversazione. Dopo il primo turno della fast mode, Claude Code continua a inviare l'intestazione e varia solo l'impostazione di velocità della richiesta, che non fa parte della chiave della cache. Disattivare la fast mode, il fallback automatico alla velocità standard dopo un limite di velocità, e riattivarla in seguito mantengono tutti la cache. Se esaurisci i crediti di utilizzo a metà sessione, Claude Code ritenta ogni richiesta fast mode rifiutata alla velocità standard allo stesso modo, quindi questo fallback mantiene anche la cache. /clear e /compact ripristinano questo, poiché ricostruiscono la cache in quei punti comunque.

Connecting or disconnecting an MCP server

Le definizioni degli strumenti si trovano nel layer del prompt di sistema, quindi la cache si invalida quando l'insieme delle definizioni degli strumenti nella richiesta cambia tra i turni. Attivare lo strumento advisor è un'eccezione: la sua definizione si trova dopo il punto di interruzione della cache, quindi abilitare o disabilitare /advisor mantiene il prefisso memorizzato nella cache intatto. Se un cambio di MCP server fa questo dipende dal fatto che i suoi strumenti siano rimandati dalla tool search o caricati nel prefisso:

  • Strumenti rimandati, il valore predefinito sui modelli supportati: un server che si connette, disconnette, o cambia il suo elenco di strumenti aggiunge solo nuovo contenuto e non disturba nulla che sia già memorizzato nella cache.
  • Strumenti caricati nel prefisso: qualsiasi cambio ad essi invalida la cache. Questo accade quando tool search non è disponibile o disabilitato, come su modelli di Google Cloud's Agent Platform precedenti alla generazione Claude 4.5, con un gateway ANTHROPIC_BASE_URL personalizzato, o su una distribuzione di Microsoft Foundry ospitata su Azure una volta che Claude Code rileva che la distribuzione rifiuta la tool search. Accade anche per un server o uno strumento contrassegnato alwaysLoad, e per le definizioni mantenute in primo piano dal caricamento basato su soglia.

Quando gli strumenti si caricano nel prefisso, la causa più comune di un'invalidazione è un server che si connette o disconnette a metà sessione, il che può accadere senza alcuna azione da parte tua: il processo di un server stdio esce, una sessione HTTP scade, o un server si riconnette automaticamente dopo un errore transitorio. Un server connesso può anche inviare un dynamic tool update che cambia il suo elenco di strumenti.

Modificare la tua configurazione MCP non cambia la cache di per sé. La nuova configurazione ha effetto solo dopo un riavvio, che è quando il server si connette o disconnette.

Enabling or disabling a plugin

Quando abiliti o disabiliti un plugin, il costo del cambio dipende da quali tipi di componenti il plugin fornisce. I casi seguenti coprono ogni tipo di componente, quando Claude Code applica il cambio, e cosa accade quando disabiliti un plugin di nuovo nella stessa sessione.

Plugin components that keep the cache

Claude Code non invalida mai la cache per le skill, i comandi, gli agenti, gli hook, i monitor o i temi di un plugin. Aggiunge il loro contenuto dopo la conversazione esistente, quindi la richiesta successiva paga per quel contenuto e legge comunque tutto ciò che lo precede dalla cache.

Plugins that provide MCP servers

Quando abiliti o disabiliti un plugin che fornisce MCP server, Claude Code segue le stesse regole di quando connetti o disconnetti un MCP server:

  • Se Claude Code rimanda gli strumenti del server, mantiene la cache.
  • Se Claude Code li carica nel prefisso, la richiesta successiva rilegge l'intera conversazione.

Code intelligence plugins

Quando abiliti un plugin di code intelligence, Claude ottiene lo strumento LSP.

When plugin changes apply

Claude Code applica un cambio di plugin quando esegui /reload-plugins o avvii una nuova sessione. Paghi il costo, sia annunci aggiunti che una rilettura completa, al primo turno dopo che il cambio si applica, non quando esegui /plugin enable o /plugin disable. Claude Code può anche applicare un cambio di per sé in tre casi:

  • Per un plugin con una sorgente command, Claude Code può ricaricare il plugin stesso.
  • Quando installi un plugin dall'interfaccia /plugin, Claude Code può attivarlo durante l'installazione. Claude Code ti dice nel riepilogo dell'installazione se l'ha fatto o se eseguire /reload-plugins.
  • Quando sposti la sessione con /cd su v2.1.246 o successivo, Claude Code applica i plugin che le impostazioni della nuova directory abilitano come parte dello spostamento, senza l'avviso di rilettura completa che trattiene un /reload-plugins.

Quando esegui /reload-plugins e il ricaricamento attiverebbe una rilettura completa, Claude Code mostra un avviso e non applica il ricaricamento. Rieseguilo con --force per applicare il ricaricamento comunque.

/reload-plugins viene eseguito anche in sessioni senza un terminale interattivo, come l'app desktop, l'Agent SDK, e modalità non interattiva con -p, quando lo digiti direttamente nella sessione. Richiede Claude Code v2.1.260 o successivo.

In quelle sessioni il ricaricamento applica tutto tranne i cambiamenti dei server MCP del plugin, che hanno effetto nella tua sessione successiva e quindi non costano mai una rilettura completa a metà sessione.

Plugins you enable and then disable in one session

Quando disabiliti un plugin che hai abilitato in precedenza nella sessione, Claude Code ripristina la forma di richiesta precedente. Se quel prefisso è ancora entro la sua durata della cache, la richiesta successiva legge la voce di cache più vecchia invece di ricostruirla.

Denying an entire tool

Aggiungere un nome di strumento semplice come Bash o WebFetch come deny rule rimuove completamente quello strumento dal contesto di Claude. Claude Code carica le definizioni degli strumenti incorporati nel layer del prompt di sistema, quindi aggiungere o rimuovere una di queste regole a metà sessione invalida la cache. Claude Code applica il cambio alla richiesta successiva, sia che tu aggiunga la regola tramite /permissions o modificando direttamente un file di impostazioni. Questo include una regola che aggiungi tramite /permissions nel mezzo di un turno.

Solo una deny rule che corrisponde nella posizione del nome dello strumento ha questo effetto: un nome di strumento semplice, la forma equivalente Bash(*), o un tool-name glob come "*". Un glob che corrisponde solo agli strumenti MCP, come "mcp__*", rimuove quegli strumenti allo stesso modo ma lascia la cache intatta quando gli strumenti corrispondenti sono rimandati, il valore predefinito, poiché le definizioni rimandate non erano mai nel prefisso memorizzato nella cache. Le deny rule con ambito come Bash(rm *), e tutte le regole di consentimento e richiesta, non cambiano quali strumenti Claude vede. Claude Code le controlla quando Claude tenta una chiamata, lasciando il prefisso intatto.

Changing output style

Lo stile di output fa parte del prompt di sistema. Quando cambi stili a metà sessione con /config o l'impostazione outputStyle, Claude usa il nuovo stile a partire dal tuo prossimo messaggio, e quella richiesta legge l'intera cronologia della conversazione senza cache hit. Per mantenere quel costo piccolo, cambia stili prima del tuo primo messaggio in una sessione o subito dopo /clear o /compact, quando c'è poca o nessuna cronologia della conversazione da rileggere.

Prima della v2.1.251, un cambio di stile a metà sessione manteneva la cache ma non si applicava finché non eseguivi /clear o non avviavi una nuova sessione.

Compacting the conversation

La compaction sostituisce la tua cronologia dei messaggi con un riepilogo. Per progettazione, questo invalida il layer della conversazione, poiché la richiesta successiva ha una cronologia nuova e più breve che non condivide un prefisso con quella vecchia. Claude Code riutilizza il layer del prompt di sistema e ricarica il contesto del progetto dal disco, che ha cache hit solo se CLAUDE.md e la memoria sono invariati dall'inizio della sessione.

Per produrre il riepilogo, Claude Code invia una richiesta separata con lo stesso prompt di sistema, strumenti e cronologia della tua conversazione, più un'istruzione di riepilogo aggiunta come messaggio utente finale. Mentre la cache è calda, quella richiesta legge il tuo prefisso dalla cache, quindi una /compact a metà sessione costa una frazione di quello che la dimensione del contesto suggerisce e spende la maggior parte del suo tempo generando il riepilogo.

Dopo una pausa più lunga della durata della cache, non c'è cache rimasta da leggere, quindi la richiesta di riepilogo rielabora la cronologia completa come input non memorizzato nella cache. Questo è il motivo per cui /compact costa di più quando riprendi una sessione vecchia. In entrambi i casi caldi e freddi, il turno dopo la compaction ricostruisce la cache della conversazione solo per il riepilogo molto più breve, quindi quel turno non è la parte lenta.

Accumulating many images

L'API limita quante immagini e PDF ogni richiesta può contenere. Per i numeri attuali, vedi Request limits nella documentazione dell'API. Claude Code limita anche la dimensione totale delle immagini e dei PDF in una richiesta, quindi gli screenshot grandi raggiungono il limite con meno immagini di quelli piccoli.

Quando la richiesta successiva passerebbe uno dei due limiti, Claude Code rimuove un batch delle immagini e dei PDF più vecchi da quello che invia, il che lascia spazio per altri prima di dover rimuovere di nuovo. Claude non può più vedere le immagini rimosse. Se Claude ne ha bisogno di nuovo, condividila di nuovo.

Rimuovere immagini cambia i messaggi che le contenevano, quindi la richiesta successiva rielabora la conversazione dal primo di quei messaggi in poi. Poiché Claude Code rimuove un batch alla volta, vedi un turno più lento per batch piuttosto che uno con ogni nuovo screenshot.

Upgrading Claude Code

Una nuova versione di Claude Code in genere aggiorna il prompt di sistema o le definizioni degli strumenti, quindi la prima richiesta dopo un aggiornamento ricostruisce la cache dall'inizio. L'auto-update scarica le nuove versioni in background ma le applica al prossimo avvio, mai a metà sessione, quindi lo vedi come un primo turno senza cache dopo il riavvio piuttosto che una sorpresa durante una sessione. Imposta DISABLE_AUTOUPDATER=1 per controllare quando gli aggiornamenti si applicano.

Azioni che mantengono la cache

Queste azioni aggiungono alla fine della conversazione o non toccano affatto la richiesta. Alcune di esse, come modificare CLAUDE.md, mantengono la cache per lo stesso motivo per cui la modifica non raggiunge la sessione in esecuzione fino a /clear, /compact o un riavvio.

Modifica dei file nel tuo repository

I contenuti dei file entrano nel contesto solo quando Claude li legge, e le letture si aggiungono alla conversazione. Modificare un file che Claude ha letto in precedenza non cambia retroattivamente la lettura precedente nella cronologia. Invece, Claude Code aggiunge un <system-reminder> notando che il file è cambiato, e Claude lo rilegge se necessario.

Modifica di CLAUDE.md durante la sessione

I tuoi file CLAUDE.md a livello di radice del progetto e a livello utente vengono letti una sola volta all'inizio della sessione e mantenuti in memoria. Modificarli durante la sessione non invalida la cache, ma la modifica non si applica nemmeno. Claude continua a lavorare con la versione che è stata caricata all'inizio della sessione. Il nuovo contenuto viene caricato al prossimo /clear, /compact o riavvio.

I file CLAUDE.md annidati nelle sottodirectory e le regole con frontmatter paths: vengono caricati in seguito, quando Claude legge per la prima volta un file corrispondente. Modificarne uno prima che venga caricato ha effetto. Dopo che viene caricato, il contenuto fa parte della cronologia della conversazione, quindi una modifica durante la sessione non lo cambia retroattivamente.

Cambio della modalità di autorizzazione

Passare tra modalità di autorizzazione, come da manuale ad accettare modifiche, non cambia il prompt di sistema o le definizioni degli strumenti, quindi i cambi di modalità sono sicuri per la cache. L'eccezione è la modalità piano con l'impostazione opusplan del modello, che cambia il modello tra Opus e Sonnet quando entri o esci dalla modalità piano. Questo rende il toggle della modalità un cambio di modello.

Invocazione di skills e comandi

Skills e comandi iniettano le loro istruzioni come messaggi utente nel punto di invocazione. Nulla prima nella conversazione cambia. Una skill o un comando il cui frontmatter nomina un model può essere un cambio di modello per quel turno.

Esecuzione di `/recap`

/recap genera un riepilogo per la visualizzazione nel tuo terminale. A differenza di /compact, aggiunge il riepilogo come output del comando piuttosto che sostituire la tua cronologia dei messaggi, quindi il prefisso memorizzato nella cache rimane intatto.

Riavvolgimento della conversazione

/rewind tronca la tua conversazione a un turno precedente. La cronologia rimanente è lo stesso contenuto da cui la cache è stata costruita in quel momento, e i layer del prompt di sistema e del contesto del progetto sono invariati, quindi la richiesta successiva colpisce la voce della cache precedente. Ogni turno da allora ha letto attraverso quel prefisso, che ha mantenuto la voce calda anche se il turno originale era più tempo fa del TTL.

Il ripristino dei checkpoint dei file insieme alla conversazione non ha alcun effetto separato sulla cache. I contenuti dei file entrano nel contesto solo quando Claude li legge, lo stesso di modifica dei file nel tuo repository.

Cache lifetime

I prefissi memorizzati nella cache scadono dopo un periodo di inattività. Ogni richiesta che colpisce la cache ripristina il timer, quindi la cache rimane calda finché continui a lavorare. Dopo un intervallo abbastanza lungo, la richiesta successiva ricalcola l'input completo e ristabilisce la cache, il che è il motivo per cui il primo turno di ritorno dopo essersi allontanato può essere notevolmente più lento.

Su un piano Pro o Max, quando riprendi una sessione di grandi dimensioni dopo una lunga pausa, Claude Code offre di riprendere da un riepilogo in modo che le richieste successive non portino la cronologia completa.

Il time to live (TTL) controlla per quanto tempo un intervallo la cache sopravvive. L'API offre due: un TTL di cinque minuti e un TTL di un'ora che mantiene la cache calda attraverso pause più lunghe ma fattura le scritture della cache a una velocità più elevata. Il TTL più lungo aiuta quando lasci una sessione inattiva e torni ad essa, perché salti la rielaborazione che un prefisso scaduto comporta. Costa di più su brevi raffiche di lavoro che non rimangono mai inattive oltre cinque minuti, dove si applica la velocità di scrittura più elevata e la durata della cache più lunga rimane inutilizzata.

Which TTL each request gets

Claude Code decide il TTL per richiesta, e ogni richiesta rientra in uno di due bucket fissi:

  • Main conversation: i tuoi turni interattivi, le esecuzioni non interattive -p e i turni Agent SDK, più gli helper che Claude Code esegue inline con essi
  • Everything else: le richieste che Claude Code effettua al di fuori di quella conversazione, come subagents, workflows, teammates in-process, fork, compaction e titoli di sessione

A meno che tu non scelga un TTL tu stesso, Claude Code richiede il TTL di un'ora solo su una Claude subscription entro l'utilizzo incluso nel tuo piano. Lì richiede l'ora per la conversazione principale, più un piccolo insieme di richieste helper che Anthropic controlla lato server. Questa tabella fornisce il TTL predefinito di ogni bucket in entrambi i tipi di fatturazione.

Request bucket Claude subscription, within plan usage Usage credits, API key, or cloud provider
Main conversation One hour Five minutes
Everything else Five minutes, except the server-controlled helper requests, which get one hour Five minutes

Una volta superato il limite di utilizzo del tuo piano e Claude Code attinge ai usage credits, ti viene fatturato quell'utilizzo, quindi Claude Code abbassa la conversazione principale al TTL di cinque minuti più economico. Per mantenere il TTL di un'ora lì, scegli il TTL tu stesso.

Choose the TTL yourself

Puoi impostare un TTL per uno dei due bucket. Ogni controllo accetta 5m o 1h, e Claude Code ignora qualsiasi altro valore.

Entrambe le impostazioni e entrambe le variabili di ambiente richiedono Claude Code v2.1.242 o successivo. Se accedi con una API key o utilizzi un cloud provider, imposta promptCacheTtl su 1h per dare alla conversazione principale una cache di un'ora. Le richieste al di fuori di essa mantengono il default di cinque minuti fino a quando non scegli un TTL per quel bucket anche.

Quando si applica più di un controllo, Claude Code prende la prima corrispondenza in questo ordine:

  1. FORCE_PROMPT_CACHING_5M=1, che forza cinque minuti per entrambi i bucket
  2. La variabile di ambiente del bucket
  3. L'impostazione del bucket
  4. Per le richieste di un subagent, il valore cacheTtl nel campo frontmatter experimental del subagent, che richiede Claude Code v2.1.248 o successivo. Claude Code ignora un 1h lì mentre la tua Claude subscription sta utilizzando usage credits
  5. ENABLE_PROMPT_CACHING_1H=1, che richiede un'ora per entrambi i bucket
  6. Il default per il bucket della richiesta

Imposta FORCE_PROMPT_CACHING_5M=1 quando stai eseguendo il debug del comportamento della cache, confrontando i due TTL, o sovrascrivendo un TTL più lungo impostato in managed settings.

Per confermare quale TTL le scritture della cache della tua conversazione principale hanno utilizzato, esegui claude -p "hello" --output-format json e leggi usage.cache_creation nel risultato. Claude Code segnala le scritture della cache di un'ora sotto ephemeral_1h_input_tokens e le scritture della cache di cinque minuti sotto ephemeral_5m_input_tokens.

Attraverso un gateway LLM che imposti con ANTHROPIC_BASE_URL, parte della richiesta di un'ora viaggia nell'intestazione anthropic-beta, quindi configura il gateway per inoltrare quell'intestazione invariata. Il TTL di un'ora non è disponibile attraverso il Claude apps gateway. Su Amazon Bedrock, il supporto del prompt caching, la lunghezza minima del prefisso memorizzabile nella cache e la disponibilità del TTL di un'ora variano a seconda del modello. Se i conteggi dei token della cache rimangono a zero, controlla supported models, regions, and limits nella documentazione di Amazon Bedrock.

Cache scope

In Claude Code, la cache è effettivamente scoped a una macchina e una directory. Il prompt di sistema incorpora la directory di lavoro, la piattaforma, la shell, la versione del sistema operativo e i percorsi della memoria automatica, quindi due sessioni in directory diverse costruiscono prefissi diversi e si perdono la cache l'una dell'altra. Questo include i worktrees dello stesso repository, poiché ogni worktree ha la sua directory di lavoro.

Le sessioni che esegui in parallelo nella stessa directory costruiscono prefissi corrispondenti e leggono la cache l'una dell'altra. Le sessioni sequenziali condividono il prefisso solo quando lo snapshot dello stato git all'avvio corrisponde, poiché il prompt di sistema cattura anche il ramo e i commit recenti.

La cache API sottostante è più ampia. Le cache sono isolate tra le organizzazioni e, su alcuni provider, tra i workspace all'interno di un'organizzazione. All'interno di questi confini, qualsiasi due richieste con lo stesso modello e prefisso leggono la stessa cache. Per i chiamanti dell'Agent SDK che eseguono flotte di processi automatizzati, vedi improve prompt caching across users and machines per sopprimere le sezioni per macchina del prompt di sistema e condividere la cache tra le macchine.

Verificare le prestazioni della cache

Le prestazioni della cache si mostrano come due conteggi di token che l'API segnala su ogni risposta. Il modo più diretto per guardarli dal vivo è uno statusline script che legge l'oggetto current_usage:

Field Meaning
cache_creation_input_tokens Token scritti nella cache su questo turno, fatturati alla velocità di scrittura della cache
cache_read_input_tokens Token serviti dalla cache su questo turno, fatturati a circa il 10% della velocità di input standard

Un alto rapporto lettura-creazione significa che il caching funziona bene. Se la creazione rimane alta turno dopo turno, qualcosa sta cambiando nel tuo prefisso. La sezione actions that invalidate the cache elenca le cause usuali.

Per un riepilogo per sessione, esegui /usage. Dopo la prima risposta della conversazione principale, Claude Code aggiunge una Prompt cache (main) line al blocco Session, mostrando il rapporto di hit della sessione, il conteggio dei miss e se la cache è calda in questo momento. Uno script statusline può leggere gli stessi numeri dall'oggetto prompt_cache. Entrambi richiedono Claude Code v2.1.251 o successivo.

La riga Prompt cache (main) nomina anche la probabile causa dell'ultimo miss quando Claude Code riesce a identificarne una, ad esempio likely cause: tool definitions changed. Il testo della probabile causa richiede Claude Code v2.1.260 o successivo.

Per la visibilità in un'organizzazione, l'esportatore OpenTelemetry segnala i token di lettura e creazione della cache per utente e sessione. Vedi Monitor usage per il riferimento degli attributi di metrica e evento.

Subagent e la cache

Un subagent avvia la sua propria conversazione con il suo prompt di sistema e set di strumenti, separato da quello del genitore. La sua prima richiesta non legge la cache del genitore, perché i due prefissi differiscono, e riscalda una cache propria attraverso i suoi turni. I subagent rimangono al di fuori del bucket TTL della conversazione principale, quindi ottengono cinque minuti anche su una subscription fino a quando non scegli uno più lungo.

La cache del genitore non è interessata. Dal lato del genitore, la chiamata e il risultato del subagent si aggiungono alla conversazione, lasciando il prefisso del genitore intatto.

Un fork, al contrario, eredita il prompt di sistema, gli strumenti e la cronologia della conversazione del genitore esattamente, quindi la sua prima richiesta legge la cache del genitore.

Altre richieste possono anche leggere un prefisso che una richiesta precedente ha memorizzato nella cache:

  • Session copies: una sessione che copi con /fork riceve la sua istruzione di isolamento come messaggio alla fine della conversazione copiata, quindi la cache che la conversazione originale ha costruito rimane intatta.
  • Compaction: la chiamata di riepilogo descritta in Compacting the conversation utilizza lo stesso approccio di condivisione dei prefissi.
  • Workflow fan-outs: in un workflow fan-out di agenti con lo stesso prefisso, Claude Code tiene tutti tranne il primo per un massimo di 5 secondi per impostazione predefinita, quindi le loro prime richieste possono leggere il prefisso che il primo agente ha memorizzato nella cache.

Disabilita prompt caching

Disabilitare il caching è occasionalmente utile quando si esegue il debug del comportamento della cache con un modello o provider specifico. Per disattivarlo, imposta una di queste variabili di ambiente su 1:

Variable Effect
DISABLE_PROMPT_CACHING Disabilita per tutti i modelli
DISABLE_PROMPT_CACHING_HAIKU Disabilita per Haiku solo
DISABLE_PROMPT_CACHING_SONNET Disabilita per Sonnet solo
DISABLE_PROMPT_CACHING_OPUS Disabilita per Opus solo
DISABLE_PROMPT_CACHING_FABLE Disabilita per Fable solo

Per impostare la politica di caching in un'organizzazione, metti una di queste o le TTL variables nel blocco env di managed settings. Per l'uso normale, lascia il caching abilitato.