Token di Claude: come funziona il conteggio in Claude Code

Cosa sono i token in Claude?

Un token è l'unità di testo che Claude legge e genera: un frammento di parola. Il glossario ufficiale di Anthropic indica circa 3.5 caratteri inglesi per i modelli precedenti a Claude Opus 4.7. Con il tokenizer attuale il valore è più vicino a 2.5, perché Anthropic considera 1M token equivalenti a circa 2.5M caratteri. In ogni caso, includendo spazi e punteggiatura, si supera ampiamente un token per parola. Un testo di mille parole supera quindi agevolmente 1,300 token. Il codice ha una densità maggiore per riga: parentesi graffe, operatori, caratteri di sottolineatura e indentazione vengono suddivisi in più token per carattere rispetto all'inglese. Un file sorgente di alcune centinaia di righe pesa in genere diverse migliaia di token. Un file di 2,000 righe che l'agente decide di leggere comporta un consumo di token a cinque cifre prima ancora di scrivere una sola riga di nuovo codice.

Due aspetti dei tokenizer causano spesso confusione. Primo, sono specifici del modello. A ottobre 2026, Claude Opus 4.7 e tutti i modelli successivi, inclusi gli attuali Fable 5.1, Opus 5.5, Sonnet 5.5 e Haiku 5.5, usano un tokenizer più recente che produce circa il 30% di token in più per lo stesso testo rispetto ai modelli Claude precedenti, come Haiku 4.5. L'aumento esatto varia in base al contenuto. Questo modifica qualsiasi stima basata sui token, anche se i prezzi per token non sono aumentati di conseguenza. Secondo, tiktoken, la libreria utilizzata nella maggior parte degli articoli, è il tokenizer di OpenAI, non quello di Claude. I relativi conteggi non corrispondono quindi a quelli fatturati da Anthropic. L'unico conteggio affidabile proviene dall'endpoint count_tokens, descritto di seguito.

Perché la sessione di programmazione ha questo costo

Ogni addebito Claude, che si tratti di una fattura API o di un limite dell'abbonamento, dipende principalmente da un unico contatore: token in ingresso e token in uscita. Alcuni strumenti API aggiungono una voce separata; la ricerca web, ad esempio, costa $10 per 1.000 ricerche a ottobre 2026, oltre ai token generati dai relativi risultati. In una sessione di programmazione, però, è il contatore dei token a incrementare il costo. La pagina dei prezzi sembra semplice: un certo numero di dollari per milione di token di input e un certo numero per milione di token di output. Non chiarisce che, in una sessione di programmazione agentica, il contatore dell'input aumenta molto più rapidamente di quanto suggerisca l'intuizione, perché l'intera conversazione viene inviata nuovamente a ogni singolo turno. Vendo infrastrutture a consumo da quindici anni e i token sono il primo contatore che abbia incontrato per il quale la maggior parte dei clienti non sa davvero cosa lo faccia aumentare. Questa è la lezione su come leggere il contatore: che cosa viene considerato input e output in una sessione agentica, perché il ciclo di reinvio è così costoso, perché il prompt caching cambia completamente i calcoli e quali leve modificano davvero il valore.

Tutto è input: che cosa conta realmente il contatore

Si presume di pagare il codice scritto da Claude. In una sessione agentica, questa è la voce di costo minore. I token di input, che hanno una tariffa più bassa ma un volume molto maggiore, includono:

• Il prompt di sistema. Le istruzioni del framework di Claude Code, oltre ai file CLAUDE.md e di memoria, caricati all'avvio della sessione e presenti in ogni richiesta successiva.
• Le definizioni degli strumenti. Ogni schema degli strumenti che l'agente può chiamare. Ogni server MCP a cui ci si connette aumenta questo overhead fisso, anche se ora Claude Code rinvia per impostazione predefinita le definizioni complete degli strumenti MCP. Nel contesto restano quindi solo i nomi degli strumenti finché uno di essi non viene usato. Questo riduce il costo, ma non lo elimina.
• Ogni file letto dall'agente. Una Read di un file sorgente inserisce l'intero file nel contesto, dove rimane.
• Ogni risultato degli strumenti. Esecuzioni dei test, output di grep, output del terminale, log delle build: tutto torna come token di input. Una suite di test che stampa 8,000 righe equivale a un breve libro. A ottobre 2026, Claude Code inserisce inline per impostazione predefinita circa 30,000 caratteri di output dei comandi. Qualsiasi output più lungo arriva invece come file salvato, con un'anteprima di massimo 2,000 caratteri. Tuttavia, ogni output entro questo limite e ogni lettura successiva del file salvato viene conteggiato integralmente.
• L'intera conversazione fino a quel momento, reinviata a ogni turno. Questo aspetto merita una sezione dedicata.

Il reinvio non è gratuito

L’API di Claude è stateless. Non conserva la sessione tra una richiesta e l’altra: non lo fa nessun componente. Al turno 2, quindi, il client invia il turno 1, la relativa risposta e il nuovo messaggio. Al turno 50 reinvia tutto ciò che è ancora nel contesto dai turni da 1 a 49, ogni file letto, risultato degli strumenti e diff che non è stato eliminato tramite compaction, oltre al turno 50. (La compaction sostituisce la cronologia meno recente con un riepilogo; le letture dei file eseguite da un subagent restano nel relativo contesto e viene restituito soltanto il risultato.) Il modello rilegge ogni volta l’intera trascrizione conservata e ogni token riletto viene addebitato come input.

La conseguenza è che il costo per turno cresce all’incirca in modo lineare con la durata della sessione, mentre il costo totale della sessione cresce in modo approssimativamente quadratico. Un messaggio che al turno 3 costava mezzo centesimo può costare venti volte tanto al turno 60, pur contenendo la stessa domanda di una riga, perché si porta dietro sessanta turni di contesto. Questo è il singolo fatto che spiega la maggior parte delle richieste relative a fatture insolitamente elevate. Non è una peculiarità di Claude: ogni prodotto LLM che sembra stateful usa sotto il cofano un’API stateless con un ciclo di reinvio.

Output: ciò che viene visualizzato e ciò che resta nel ragionamento

I token di output sono la voce più costosa: hanno una tariffa cinque volte superiore a quella degli input nell'attuale gamma ($10/$50 su Fable 5.1, $4/$20 su Opus 5.5, $2/$10 su Sonnet 5.5, $0.10/$0.50 su Haiku 5.5 per prompt fino a 100,000 token, a ottobre 2026). L'output comprende il testo e il codice generati da Claude, oltre ai thinking token: il ragionamento interno che il modello esegue prima di rispondere. Qui contano due aspetti. Il thinking viene fatturato alle tariffe dell'output e incide su max_tokens; una risposta API che termina con stop_reason: "max_tokens" e una risposta troncata spesso indicano che il thinking ha esaurito il budget prima della risposta. Inoltre, sui modelli attuali il riepilogo del ragionamento potrebbe non essere visualizzato: l'API lo omette per impostazione predefinita su Fable 5.1, Opus 5.5, Sonnet 5.5, Haiku 5.5 e sui modelli precedenti fino a Opus 4.7, ma il thinking è comunque avvenuto e viene comunque fatturato. Invisibile non significa gratuito.

Claude Code abilita il thinking esteso per impostazione predefinita perché migliora in modo misurabile le attività in più passaggi; il budget predefinito può arrivare a decine di migliaia di token per richiesta. Per le attività più semplici puoi ridurlo: abbassa il livello di effort con /effort o in /model, oppure disattiva il thinking in /config sui modelli che lo consentono. A ottobre 2026, Claude Code non può disattivare il thinking su Opus 5.5, Sonnet 5.5, Haiku 5.5 o sui modelli Fable; in questi casi il livello di effort è il parametro da usare. L'API offre più possibilità su due di questi modelli. Haiku 5.5 accetta thinking: {"type": "disabled"} con effort alto o inferiore, così come il precedente Opus 5, mentre il precedente Sonnet 5 lo accetta a ogni livello di effort, inclusi xhigh e max. Sonnet 5.5 rifiuta "disabled" e usa invece thinking: {"type": "between_tools"}, che riduce il thinking iniziale con effort basso, medio o alto; una richiesta senza strumenti riceve quindi la risposta senza thinking preliminare. Solo Opus 5.5 e i modelli Fable mantengono il thinking indipendentemente da ciò che invii. Si tratta di un parametro che incide realmente sui costi, non di una supposizione.

Il caching dei prompt riscrive i calcoli

Il caching dei prompt è il motivo per cui il ciclo di reinvio non porta tutti alla bancarotta. L'API può memorizzare in cache un prefisso stabile del prompt, il prompt di sistema, le definizioni degli strumenti e la cronologia della conversazione, quindi servirlo alla richiesta successiva a una frazione del prezzo. A ottobre 2026 i moltiplicatori sono i seguenti: una scrittura nella cache costa 1.25× della tariffa di base per gli input (2× per la variante da 1 ora), mentre una lettura dalla cache costa 0.1× sulla maggior parte dei modelli, 0.05× su Claude Opus 5.5 e Claude Sonnet 5.5 e 0.025× su Claude Fable 5.1. Le scritture hanno un sovrapprezzo; le letture applicano uno sconto del 90% sulla maggior parte dei modelli, del 95% su Opus 5.5 e Sonnet 5.5 e del 97.5% su Fable 5.1. (La tariffa di lettura di Sonnet 5.5 è stata ridotta da 0.1× a 0.05× il 7 ottobre 2026.) Una sola lettura ripaga già ampiamente il sovrapprezzo della scrittura con durata di 5 minuti.

Claude Code gestisce il caching per te e, in una sessione in condizioni normali, quasi tutto quel grande reinvio viene servito dalla cache. La cache però scade dopo un periodo di inattività. A ottobre 2026, Claude Code assegna alla conversazione principale una cache di un'ora per un abbonamento, nell'ambito dell'utilizzo incluso nel piano, e di cinque minuti dall'ultimo utilizzo quando usi una chiave API, un provider cloud o i crediti di utilizzo (l'impostazione promptCacheTtl può richiedere in quel caso la durata di un'ora, con una tariffa di scrittura pari a 2×). Con una cache di cinque minuti, se ti allontani per un caffè che si prolunga, torni, invii un messaggio e la cache è scaduta, l'intero prefisso accumulato viene riscritto a 1.25× invece di essere letto alla tariffa della cache. In una sessione da 150K token, quel singolo turno a cache fredda scrive tutti i 150K token a 1.25×, mentre un turno a cache calda li avrebbe letti a 0.1×: sul prefisso la differenza è di 12.5 volte (25 volte su Opus 5.5 e Sonnet 5.5, 50 volte su Fable 5.1). Questo è il risultato controintuitivo da tenere presente: un ritmo fatto di inattività e ripresa può costare più del lavoro continuo, perché ogni intervallo di inattività oltre il TTL trasforma il turno successivo da una lettura economica in una costosa nuova scrittura. Lavora per sessioni concentrate; con una cache di cinque minuti, non alimentare a intervalli un'enorme sessione inviando un messaggio ogni dieci minuti.

Se chiami l'API dalla tua applicazione su un VPS, nulla di tutto questo avviene automaticamente: devi attivare esplicitamente la funzione con cache_control. Il tipico errore causato dall'utente consiste nell'interpolare un timestamp o un ID della richiesta nel prompt di sistema, modificando i byte del prefisso a ogni richiesta e disattivando silenziosamente il caching. Il segnale è usage.cache_read_input_tokens fermo a zero in chiamate dall'aspetto identico.

La formula, con un esempio pratico

Ignorate chi indica un costo fisso del tipo «una sessione costa $X». Il costo delle sessioni può variare di due ordini di grandezza. La formula valida è:

turn cost = (uncached input        x base input price)
          + (cache writes          x 1.25 x base input price)
          + (cache reads           x read multiplier x base input price)
          + (output incl. thinking x output price)

read multiplier = 0.10 on most models, 0.05 on Opus 5.5 and Sonnet 5.5, 0.025 on Fable 5.1
session cost = sum over all turns

Ecco un esempio pratico con Claude Opus 4.8, oggi un modello legacy ma ancora disponibile e, a ottobre 2026, ancora prezzato a $5 per milione di token di input e $25 per milione di token di output. Consideriamo un turno a metà sessione con 80,000 token di contesto accumulato: 75,000 letti dalla cache, 3,000 scritti per la prima volta, 2,000 token di input nuovi non memorizzati nella cache e 1,500 token di output, incluso il ragionamento.

• Letture dalla cache: 75,000 × $0.50/M = $0.0375
• Scritture nella cache: 3,000 × $6.25/M = $0.019
• Input non memorizzato nella cache: 2,000 × $5/M = $0.010
• Output: 1,500 × $25/M = $0.0375

Circa $0.10 per il turno; cinquanta turni di questo tipo costano circa $5. Consideriamo ora lo stesso turno dopo la scadenza della cache: i 78,000 token memorizzabili nella cache vengono riscritti a $6.25/M. Sommando gli stessi 2,000 token non memorizzati nella cache a $5/M, si ottengono circa $0.50 prima dell'output. È circa cinque volte il costo dell'intero turno con cache attiva, a parità di lavoro. Questa differenza riassume in un solo numero l'impatto della cache. Con l'attuale Claude Opus 5.5 ($4/$20, con letture dalla cache a 0.05×), lo stesso turno con cache attiva costa circa $0.07 (letture $0.015, scritture $0.015, input non memorizzato nella cache $0.008, output $0.030), mentre la versione senza cache costa $0.40 prima dell'output, quindi quasi sei volte il turno con cache attiva. Queste stesse quattro righe sono anche l'unico metodo corretto per confrontare i fornitori, perché i prezzi pubblicizzati ignorano completamente le letture dalla cache e il ragionamento. Applicandole a tre attività reali si vede dove il costo di Claude risulta superiore o inferiore a quello di OpenAI.

Se volete comprendere l'unità di fatturazione in sé, anziché il costo di un singolo turno, quanto corrisponde un milione di token in pagine, file e dollari esegue gli stessi calcoli a un livello superiore. Si tratta di un riferimento, non di una previsione: secondo i dati pubblicati da Anthropic per le implementazioni aziendali di Claude Code, a ottobre 2026 la media è di circa $13 per sviluppatore per giorno di attività e di $150-$250 al mese; il 90% degli utenti rimane sotto $30 al giorno. Il costo effettivo dipende dal modello scelto, dalla gestione delle sessioni e dalle dimensioni del codice. È proprio per questo che le leve descritte di seguito sono importanti.

Visualizzare il proprio utilizzo

In Claude Code, il comando è /usage (/cost continua a funzionare, perché è un alias). Il blocco Session nella parte superiore mostra le statistiche sui token e una stima del costo calcolata localmente per la sessione corrente; nei piani in abbonamento, la stessa schermata mostra le barre dei limiti del piano e una suddivisione che attribuisce l'utilizzo recente a skill, subagent, plugin e singoli server MCP. Nelle versioni recenti, il blocco Session contiene anche una riga Prompt cache (main) che mostra la percentuale di input servita dalla cache, i miss e l'indicazione che specifica se la cache è attualmente valorizzata. Per la fatturazione ufficiale degli account API, fa fede la pagina di utilizzo nella Claude Console; il valore riportato dalla CLI è una stima. /context visualizza una griglia colorata di ciò che occupa la finestra di contesto, inclusi system prompt, strumenti, definizioni MCP, file e cronologia, ed è il modo più rapido per individuare un CLAUDE.md sovradimensionato o un server MCP troppo verboso; in modalità fullscreen comprime la suddivisione per elemento, mentre passando all la espande.

Dall'API, ogni risposta indica esattamente ciò che è avvenuto:

response = client.messages.create(model="claude-sonnet-5-5", max_tokens=2048,
                                  messages=messages)
u = response.usage
total_prompt = u.input_tokens + u.cache_creation_input_tokens + u.cache_read_input_tokens
print(f"uncached={u.input_tokens} written={u.cache_creation_input_tokens} "
      f"read={u.cache_read_input_tokens} output={u.output_tokens}")

Tieni presente che input_tokens rappresenta soltanto la parte non servita dalla cache; la dimensione effettiva del prompt è la somma dei tre campi di input. Un agent che ha funzionato per un'ora e mostra input_tokens: 4000 non è economico: gli altri 200,000 token sono stati serviti dalla cache. Per fare una stima prima dell'invio, usa l'endpoint per il conteggio dei token: la chiamata è gratuita, utilizza un rate limit dedicato e conta i token con il tokenizer del modello indicato (considera il risultato una stima vicina; la fatturazione riflette la richiesta effettiva):

count = client.messages.count_tokens(model="claude-sonnet-5-5",
                                     messages=[{"role": "user", "content": big_file}])
print(count.input_tokens)

Non tiktoken mai, per il motivo indicato sopra.

Piani in abbonamento e pagamento a consumo

La procedura descritta in questa guida è identica in ogni caso; cambia soltanto la modalità di addebito. Con una chiave API, Anthropic applica il pagamento a consumo, per token, alle tariffe pubblicate: ogni cifra riportata sopra corrisponde a un costo reale. Il conteggio inizia prima di quanto molti si aspettino, perché non esiste un livello gratuito su cui fare affidamento, ma solo un piccolo credito iniziale e alcuni endpoint senza addebito. È ciò che un nuovo account API riceve realmente prima di registrare una carta. L'eccezione, dal 7 ottobre 2026, è costituita dagli abbonamenti Max o Team: questi piani includono ora crediti API mensili per le proprie applicazioni e i propri agenti sulla Claude Platform, pari a $100 al mese per Max 5x e $200 per Max 20x; per Team ammontano a $20 per ogni postazione Standard e $100 per ogni postazione Premium, con un plafond condiviso e un limite massimo di $500. Per utilizzarli è necessario collegare un'organizzazione Console. I crediti non utilizzati scadono al termine di ogni ciclo di fatturazione e non coprono Claude Code interattivo. Con un abbonamento Claude (Pro, Max, Team e i piani Enterprise legacy basati sulle postazioni), l'utilizzo di Claude Code viene invece scalato dalla quota inclusa nel piano: a ottobre 2026 si tratta di una finestra mobile di cinque ore e di una finestra settimanale, condivise tra i modelli e con la chat di claude.ai; il valore in dollari /usage è informativo e non rappresenta un addebito. A ottobre 2026 esistono due eccezioni: le postazioni Enterprise attuali basate sull'utilizzo non includono alcuna quota, quindi ogni token viene fatturato alle tariffe API standard; inoltre, i modelli Fable non rientrano nella quota di Pro, delle postazioni Team Standard o delle postazioni Enterprise Standard legacy, dove vengono eseguiti utilizzando crediti a consumo. Quando esaurisci una finestra, visualizzi "Hai raggiunto il limite della sessione" oppure "Hai raggiunto il limite settimanale", con l'orario di ripristino. Cambiare modello con /model non ripristina l'accesso, perché le finestre sono condivise tra i modelli. Queste finestre dipendono dall'account, non dal client in uso. Questo è importante se stai ancora verificando cosa funziona nativamente su Linux e quale piano copre ogni superficie. La finestra effettivamente esaurita determina la durata dell'attesa e le attività utili da svolgere nel frattempo. Conviene quindi conoscere le opzioni disponibili quando raggiungi un limite durante un'attività. I piani possono abilitare facoltativamente i crediti a consumo, gestiti con /usage-credits, per acquistare utilizzo oltre il limite. Non riporto intenzionalmente le quote dei piani: sono i valori più soggetti a variazioni nell'intero argomento. Consulta invece claude.com/pricing e le tue barre /usage. La gestione dei token resta importante anche con un abbonamento: una sessione inefficiente consuma la finestra esattamente come consumerebbe denaro. Per la parte relativa agli abbonamenti, consulta quale piano Claude è adatto al tuo utilizzo.

Le leve che funzionano davvero

• Limita ciò che l'agente legge. "Correggi il bug di validazione in auth.py" richiede la lettura di un file; "migliora questa codebase" ne richiede quaranta. Mantieni CLAUDE.md essenziale: viene caricato in ogni sessione. Sposta invece le istruzioni specifiche del flusso di lavoro nelle skill, che vengono caricate solo quando servono.
• Mantieni il contesto chiaro e compatto. /clear tra attività non correlate viene reinviato e fatturato di nuovo a ogni messaggio successivo. In un'attività lunga, /compact Focus on the failing tests and the diff riepiloga progressivamente la cronologia e impedisce di entrare nella curva quadratica.
• Scegli un modello adeguato al compito. Sonnet gestisce la maggior parte delle attività di sviluppo a $2/$10 per milione di token a ottobre 2026, ormai un prezzo standard e non più promozionale: Sonnet 5.5 costa $2/$10 e Sonnet 5 è rimasto a $2/$10 dopo l'annullamento dell'aumento previsto per il 1 settembre, che avrebbe portato il prezzo a $3/$15. Il confronto è con Opus 5.5 a $4/$20. Haiku 5.5 costa $0.10/$0.50 (per prompt fino a 100,000 token; oltre questa soglia, $0.50/$2.50) ed è la scelta corretta per il lavoro meccanico dei subagenti, come il triage dei log. Fable 5.1 si colloca all'estremo opposto, a $10/$50, lo stesso prezzo di Fable 5 e due volte e mezza quello di Opus 5.5 in entrambe le fasce di fatturazione. Conviene quindi sapere quali attività giustificano davvero questo prezzo prima di lasciarlo selezionato per il lavoro ordinario. /model consente di cambiare modello durante la sessione.
• Pre-filtra l'output dettagliato. Un hook che estrae con grep soltanto gli errori da un'esecuzione dei test prima che Claude la riceva riduce il risultato dello strumento da 20,000 token a 300. Lo fa anche a ogni nuovo invio di quel turno.
• Raggruppa le attività non interattive. Per le pipeline API, la classificazione, le revisioni massive e i job notturni, l'API Batches esegue gli stessi modelli con uno sconto del 50% in cambio della consegna asincrona.
• Considera la durata della cache. Lavora in sessioni continue. Una sessione Claude Code scollegata in tmux su un VPS non costa nulla mentre è inattiva: i token vengono utilizzati solo quando viene eseguito un turno. Tuttavia, il tempo di inattività oltre il TTL della cache fa perdere la cache calda e il turno successivo deve riscrivere il contesto.

FAQ

Quanti token utilizza una sessione di programmazione in Claude Code?

Non esiste un numero fisso. Un singolo turno a metà sessione contiene comunemente decine di migliaia di token di prompt, quando file e cronologia si sono accumulati, mentre una sessione di lavoro arriva a milioni di token. La maggior parte viene servita dalla cache a un decimo della tariffa di base o meno, a seconda del modello. Come riferimento, secondo i dati enterprise pubblicati da Anthropic, a ottobre 2026 la media è di circa $13 per sviluppatore per giorno attivo, con il 90% degli utenti sotto $30. Esegui /usage nella tua sessione: osservarlo per cinque minuti è più utile di qualsiasi media pubblicata.

I token di ragionamento hanno un costo anche quando non posso visualizzarli?

Sì. I token di ragionamento vengono addebitati come token di output, alla tariffa più elevata, e concorrono a max_tokens. I modelli attuali li addebitano anche quando l'interfaccia non mostra il riepilogo del ragionamento. Se una risposta si interrompe con stop_reason: "max_tokens" prima del completamento della risposta visibile, è probabile che il ragionamento abbia consumato il budget. In Claude Code, riduci il livello di impegno con /effort per le attività che non richiedono un ragionamento approfondito.

Perché una sessione lunga di Claude Code diventa più costosa a ogni messaggio?

Perché l'API è stateless: a ogni turno reinvia la conversazione ancora presente nel contesto, ogni file letto, ogni risultato degli strumenti e ogni scambio precedente che non è stato rimosso dalla compattazione. Tutto questo viene addebitato come input. Di conseguenza, il turno 50 include i turni da 1 a 49. La cache dei prompt serve il prefisso ripetuto a un decimo del prezzo di base dell'input nella maggior parte dei modelli, al 5% su Opus 5.5 e Sonnet 5.5 e al 2.5% su Fable 5.1. Tuttavia, il prefisso continua a crescere e qualsiasi intervallo di inattività oltre il TTL della cache converte il turno successivo in una riscrittura a prezzo pieno. /compact riduce la cronologia; /clear la reimposta.

Come posso controllare l'utilizzo dei token e i costi di Claude?

In Claude Code, /usage mostra le statistiche sui token della sessione, una stima locale dei costi e le barre dei limiti del piano per gli abbonamenti; /cost è un alias. /context mostra quali contenuti occupano la finestra di contesto. Per la fatturazione API ufficiale, usa la pagina dei consumi nella Claude Console. Nel tuo codice, leggi response.usage: la somma di input_tokens, cache_creation_input_tokens e cache_read_input_tokens restituisce la dimensione effettiva del prompt. Per una stima preventiva, usa l'endpoint count_tokens, mai tiktoken.