O que são tokens no Claude Code? Veja a conta

O que são tokens no Claude?

Um token é a unidade de texto que o Claude lê e escreve: um fragmento de uma palavra. O glossário da Anthropic estima aproximadamente 3.5 caracteres em inglês nos modelos anteriores ao Claude Opus 4.7. No tokenizer atual, o valor está mais próximo de 2.5, porque a Anthropic considera que 1M de tokens correspondem a cerca de 2.5M de caracteres. De qualquer forma, o resultado é bem superior a um token por palavra quando se contam espaços e pontuação. Assim, mil palavras de prosa ultrapassam confortavelmente 1,300 tokens. O código consome mais tokens por linha: chavetas, operadores, underscores e indentação são divididos em mais tokens por caractere do que o inglês. Um ficheiro de código com algumas centenas de linhas normalmente pesa vários milhares de tokens. Um ficheiro com 2,000 linhas que o agente decide ler representa uma utilização de cinco algarismos de tokens antes de qualquer linha de código nova ser escrita.

Há duas características dos tokenizers que causam confusão. Primeiro, são específicos de cada modelo. Em outubro de 2026, o Claude Opus 4.7 e todos os modelos posteriores, incluindo os atuais Fable 5.1, Opus 5.5, Sonnet 5.5 e Haiku 5.5, usam um tokenizer mais recente que produz aproximadamente 30% mais tokens para o mesmo texto do que os modelos Claude anteriores, como o Haiku 4.5. O aumento exato varia conforme o conteúdo. Isto altera qualquer estimativa feita em tokens, mesmo que os preços por token não tenham aumentado com essa mudança. Segundo, tiktoken, a biblioteca usada pela maioria dos artigos, é o tokenizer da OpenAI, não o do Claude. Por isso, as contagens não coincidem com o que a Anthropic fatura. A única contagem fiável é a do endpoint count_tokens, descrito abaixo.

Por que a sua sessão de programação custa o que custa

Cada cobrança do Claude, seja uma fatura da API ou um limite de subscrição, depende principalmente de um único contador: tokens de entrada e de saída. Algumas ferramentas da API acrescentam uma cobrança própria. A pesquisa na Web, por exemplo, custa $10 por 1,000 pesquisas desde outubro de 2026, além dos tokens adicionados pelos respetivos resultados. Numa sessão de programação, porém, é o contador de tokens que mais varia. A página de preços faz o cálculo parecer simples: determinado valor por milhão de tokens de entrada e determinado valor por milhão de tokens de saída. O que ela não explica é que, numa sessão de programação com agentes, o contador de entrada avança muito mais depressa do que a intuição sugere, porque a conversa completa é reenviada a cada turno. Vendo infraestrutura com tarifação por utilização há quinze anos, este é o primeiro contador que encontrei em que a maioria dos clientes realmente não consegue dizer o que o faz avançar. Esta é a lição sobre a leitura do contador: o que conta como entrada e saída numa sessão com agentes, por que o ciclo de reenvio é tão dispendioso, como o armazenamento em cache de prompts altera o cálculo e quais as variáveis que efetivamente mudam o valor.

Tudo é entrada: o que o medidor realmente contabiliza

As pessoas assumem que pagam pelo código que o Claude escreve. Numa sessão agêntica, essa é a parcela menor. Os tokens de entrada, com uma tarifa mais baixa mas um volume muito maior, incluem:

• O prompt do sistema. As instruções do próprio harness do Claude Code, além dos seus ficheiros CLAUDE.md e de memória, carregados no início da sessão e presentes em todos os pedidos seguintes.
• As definições das ferramentas. O esquema de cada ferramenta que o agente pode chamar. Cada servidor MCP que ligar aumenta esta sobrecarga fixa, embora o Claude Code agora adie por predefinição as definições completas das ferramentas MCP. Assim, apenas os nomes das ferramentas ficam no contexto até uma ferramenta ser usada pela primeira vez. Isto reduz o custo, mas não o elimina.
• Cada ficheiro que o agente lê. Um Read de um ficheiro de código-fonte coloca o ficheiro completo no contexto, onde permanece.
• Cada resultado de uma ferramenta. Execuções de testes, saída do grep, saída do terminal, logs de compilação: tudo regressa como tokens de entrada. Uma suite de testes com falhas que imprime 8,000 linhas equivale a um pequeno livro. Desde October 2026, o Claude Code passa inline, por predefinição, aproximadamente 30,000 caracteres da saída dos comandos. Qualquer saída mais longa chega como um ficheiro guardado, acompanhada de uma pré-visualização com até 2,000 caracteres. No entanto, cada saída abaixo desse limite e cada leitura posterior do ficheiro guardado são faturadas na totalidade.
• Toda a conversa até ao momento, reenviada em cada turno. Este ponto merece uma secção própria.

O reenvio que ninguém contabiliza

A API do Claude não mantém estado. Ela não se lembra da sua sessão entre pedidos; nada se lembra. Por isso, no turno 2, o cliente envia o turno 1, a resposta correspondente e a sua nova mensagem. No turno 50, reenvia tudo o que ainda estiver no contexto dos turnos 1 a 49, todos os ficheiros lidos, resultados de ferramentas e diffs que não tenham sido removidos pela compactação, além do turno 50. (A compactação troca o histórico antigo por um resumo, e as leituras de ficheiros de um subagente permanecem no próprio contexto; apenas o resultado volta.) O modelo relê toda a transcrição retida em cada pedido, e cada um desses tokens relidos é faturado como entrada.

A consequência é que o custo por turno cresce aproximadamente de forma linear com a duração da sessão, e o custo total da sessão cresce aproximadamente de forma quadrática. Uma mensagem que custou meio cêntimo no turno 3 pode custar vinte vezes mais no turno 60, para a mesma pergunta de uma linha, porque transporta sessenta turnos de histórico. Este é o único facto que explica a maioria dos pedidos de suporte do tipo "porque é que a minha fatura foi tão alta", e não é uma particularidade do Claude: todos os produtos LLM que parecem manter estado são, por baixo, APIs sem estado com um ciclo de reenvio.

Saída: o que vê, mais o raciocínio que não vê

Os tokens de saída são caros, com uma tarifa cinco vezes superior à da entrada em toda a linha atual ($10/$50 no Fable 5.1, $4/$20 no Opus 5.5, $2/$10 no Sonnet 5.5, $0.10/$0.50 no Haiku 5.5 para prompts até 100,000 tokens, em outubro de 2026). A saída inclui o texto e o código que o Claude gera, além dos tokens de raciocínio: o raciocínio interno que o modelo executa antes de responder. Há dois factos importantes. O raciocínio é cobrado às tarifas de saída e conta para max_tokens. Uma resposta da API que termina com stop_reason: "max_tokens" e uma resposta truncada significam muitas vezes que o raciocínio consumiu o orçamento antes da resposta. Nos modelos atuais, o resumo do raciocínio pode nem ser apresentado. A API omite-o por predefinição no Fable 5.1, Opus 5.5, Sonnet 5.5, Haiku 5.5 e nos modelos anteriores até ao Opus 4.7, mas o raciocínio ainda ocorreu e continua a ser cobrado. Invisível não significa gratuito.

O Claude Code ativa o raciocínio alargado por predefinição porque melhora de forma mensurável o trabalho com várias etapas. O orçamento predefinido pode chegar a dezenas de milhares de tokens por pedido. Em tarefas simples, pode reduzi-lo: diminua o nível de esforço com /effort ou em /model, ou desative o raciocínio em /config nos modelos que o permitem. Em outubro de 2026, o Claude Code não consegue desativar o raciocínio no Opus 5.5, Sonnet 5.5, Haiku 5.5 nem nos modelos Fable. Nesses modelos, o nível de esforço é o mecanismo de controlo. A API oferece mais opções em dois deles. O Haiku 5.5 aceita thinking: {"type": "disabled"} com esforço alto ou inferior, tal como o Opus 5 mais antigo. O Sonnet 5 mais antigo aceita-o em todos os níveis de esforço, incluindo xhigh e max. O Sonnet 5.5 rejeita "disabled" e aceita thinking: {"type": "between_tools"}, que reduz o raciocínio inicial com esforço baixo, médio ou alto. Assim, um pedido sem ferramentas recebe a resposta sem raciocínio inicial. Apenas o Opus 5.5 e os modelos Fable mantêm o raciocínio independentemente do que enviar. Este é um mecanismo real de controlo de custos, não uma suposição.

O cache de prompts altera os cálculos

O cache de prompts é o motivo pelo qual o ciclo de reenvio não leva todos à falência. A API pode colocar em cache um prefixo estável do seu prompt, do prompt do sistema, das definições das ferramentas e do histórico da conversa. No pedido seguinte, pode fornecê-lo por uma fração do preço. Em outubro de 2026, os multiplicadores são os seguintes: uma gravação no cache custa 1.25× a tarifa base de entrada (2× para a variante de 1 hora), e uma leitura do cache custa 0.1× na maioria dos modelos, 0.05× no Claude Opus 5.5 e no Claude Sonnet 5.5, e 0.025× no Claude Fable 5.1. As gravações têm um custo adicional; as leituras representam um desconto de 90% na maioria dos modelos, de 95% no Opus 5.5 e no Sonnet 5.5, e de 97.5% no Fable 5.1. (A tarifa de leitura do Sonnet 5.5 foi reduzida de 0.1× para 0.05× em 7 de outubro de 2026.) Uma única leitura já compensa mais do que o custo adicional de 5 minutos da gravação.

O Claude Code gere o cache por si e, numa sessão saudável, quase todo esse reenvio volumoso é servido a partir do cache. No entanto, o cache expira após um período de inatividade. Em outubro de 2026, o Claude Code atribui à conversa principal um cache de uma hora numa subscrição, dentro da utilização incluída no seu plano, e de cinco minutos desde a última utilização quando usa uma chave de API, um fornecedor cloud ou créditos de utilização (a definição promptCacheTtl pode solicitar a duração de uma hora nesses casos, à tarifa de gravação de 2×). Com um cache de cinco minutos, pode afastar-se para tomar um café, demorar-se, voltar e enviar uma mensagem. O cache terá expirado e todo o prefixo acumulado será gravado novamente a 1.25×, em vez de ser lido à tarifa do cache. Numa sessão de 150K tokens, essa interação sem cache grava todos os 150K tokens a 1.25×, enquanto uma interação com cache os teria lido a 0.1×. Isso representa uma diferença de 12.5 vezes no prefixo (25 vezes no Opus 5.5 e no Sonnet 5.5, e 50 vezes no Fable 5.1). Este é o resultado contraintuitivo que vale a pena memorizar: um ritmo de parar e retomar pode custar mais do que trabalhar continuamente, porque cada intervalo de inatividade superior ao TTL transforma a interação seguinte de uma leitura barata numa gravação cara. Trabalhe por períodos concentrados. Com um cache de cinco minutos, não alimente uma sessão enorme com uma mensagem a cada dez minutos.

Se chamar a API a partir de a sua própria aplicação num VPS, nada disto acontece automaticamente: tem de ativar a funcionalidade com cache_control. O erro clássico causado pelo próprio utilizador é interpolar um timestamp ou um ID do pedido no prompt do sistema. Isso altera os bytes do prefixo em cada pedido e desativa o cache silenciosamente. O sinal é usage.cache_read_input_tokens permanecer a zero em chamadas que parecem idênticas.

A fórmula, com um exemplo prático

Ignore quem afirma que “uma sessão custa $X”. O custo das sessões pode variar por duas ordens de grandeza. O que se mantém é a fórmula:

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

Exemplo prático com o Claude Opus 4.8, atualmente um modelo legado, mas ainda disponível e, em outubro de 2026, ainda com um custo de $5 por milhão de tokens de entrada e $25 por milhão de tokens de saída. Um turno a meio da sessão com 80,000 tokens de contexto acumulado: 75,000 lidos da cache, 3,000 escritos de novo, 2,000 tokens de entrada novos não colocados em cache e 1,500 tokens de saída, incluindo o raciocínio.

• Leituras da cache: 75,000 × $0.50/M = $0.0375
• Escritas na cache: 3,000 × $6.25/M = $0.019
• Entrada não colocada em cache: 2,000 × $5/M = $0.010
• Saída: 1,500 × $25/M = $0.0375

Cerca de $0.10 pelo turno; cinquenta turnos deste tipo custam cerca de $5. Agora considere o mesmo turno depois de a cache expirar: os 78,000 tokens colocados em cache são novamente escritos a $6.25/M. Somados aos mesmos 2,000 tokens não colocados em cache a $5/M, custam cerca de $0.50 antes da saída. Isso corresponde a aproximadamente cinco vezes o custo de todo o turno com a cache quente, para trabalho idêntico. Essa diferença resume toda a questão da cache num único número. No Claude Opus 5.5 atual ($4/$20, com leituras da cache a 0.05×), o mesmo turno com a cache quente custa cerca de $0.07 (leituras $0.015, escritas $0.015, entrada não colocada em cache $0.008, saída $0.030). A versão com a cache fria custa $0.40 antes da saída, perto de seis vezes o custo do turno com a cache quente. Estas mesmas quatro linhas são também a única forma honesta de comparar fornecedores, porque as tarifas anunciadas ignoram completamente as leituras da cache e o raciocínio. Além disso, executá-las em três trabalhos reais mostra onde o custo do Claude fica acima ou abaixo do do OpenAI.

Se pretende perceber a própria unidade de faturação, em vez de analisar um único turno, quanto correspondem um milhão de tokens em páginas, ficheiros e dólares aplica o mesmo cálculo a um nível superior. Para fins de calibração, e não de previsão: os valores publicados pela Anthropic para implementações empresariais do Claude Code, em outubro de 2026, indicam uma média de cerca de $13 por programador por dia ativo e de $150 a $250 por mês, com 90% dos utilizadores a permanecerem abaixo de $30 por dia. O custo real depende do modelo escolhido, da organização das sessões e do tamanho da base de código. É precisamente por isso que as opções abaixo são importantes.

Consultar o seu próprio consumo

No Claude Code, o comando é /usage (/cost continua a funcionar, como alias). O bloco Session, no topo, mostra as estatísticas de tokens e uma estimativa de custo calculada localmente para a sessão atual. Nos planos de subscrição, o mesmo ecrã mostra as barras dos limites do plano e uma discriminação que atribui o consumo recente a skills, subagentes, plugins e servidores MCP individuais. Nas versões recentes, o bloco Session também inclui uma linha Prompt cache (main) que mostra a parte da entrada servida a partir da cache, os misses e se a cache está atualmente ativa. Para obter dados de faturação oficiais em contas da API, a página de consumo na Claude Console é a fonte de referência. O valor da CLI é uma estimativa. /context apresenta uma grelha colorida de elementos que ocupam a janela de contexto, incluindo o system prompt, as ferramentas, as definições MCP, os ficheiros e o histórico. É a forma mais rápida de detetar um CLAUDE.md demasiado grande ou um servidor MCP demasiado comunicativo. No modo de ecrã inteiro, oculta a discriminação por item. Passar all expande-a.

Na API, cada resposta indica exatamente o que aconteceu:

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}")

Tenha em atenção que input_tokens corresponde apenas ao restante não colocado em cache. O tamanho real do prompt é a soma dos três campos de entrada. Um agente que funcionou durante uma hora e mostra input_tokens: 4000 não é barato. Os outros 200,000 tokens foram servidos a partir da cache. Para fazer uma estimativa antes de enviar o pedido, use o endpoint de contagem de tokens. A chamada é gratuita, usa um limite de taxa próprio e conta com o tokenizador do modelo que indicar. Trate o resultado como uma estimativa aproximada. A faturação baseia-se no pedido real:

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

Nunca tiktoken, pelo motivo indicado acima.

Planos de subscrição versus pagamento conforme o uso

Os mecanismos neste guia são idênticos em toda a parte; apenas a liquidação difere. Com uma API key, a Anthropic fatura conforme o uso, por token, às taxas publicadas; cada número acima representa dinheiro real. Esse contador começa mais cedo do que a maioria das pessoas espera, porque não existe um nível gratuito para recorrer, apenas um pequeno crédito no registo e um punhado de endpoints que não cobram nada, que é o que uma nova conta de API recebe efetivamente antes de adicionar um cartão ao ficheiro. A exceção, desde 7 de outubro de 2026, é uma subscrição Max ou Team: esses planos incluem agora créditos mensais de API para as suas próprias aplicações e agentes na Claude Platform, 100 dólares por mês no Max 5x e 200 dólares no Max 20x, e na Team 20 dólares por licença Standard e 100 dólares por licença Premium, agrupados e limitados a 500 dólares. Pode reclamá-los associando uma organização na Console, os créditos não utilizados expiram no final de cada ciclo de faturação e não cobrem o Claude Code interativo. Numa subscrição Claude (Pro, Max, Team e planos Enterprise legados baseados em licenças), a utilização do Claude Code é descontada da franquia incluída no seu plano: a partir de outubro de 2026, trata-se de uma janela de sessão contínua de cinco horas mais uma janela semanal, partilhada entre modelos e com o chat claude.ai, e o valor em dólares /usage é informativo em vez de uma fatura. Duas exceções a partir de outubro de 2026: as licenças Enterprise atuais baseadas em utilização não incluem qualquer utilização, pelo que cada token é faturado às taxas padrão da API, e os modelos Fable não estão na franquia do Pro, licenças Team padrão ou licenças Enterprise legadas padrão, onde funcionam com créditos de utilização pós-pagos. Esgote uma janela e verá "You've hit your session limit" ou "You've hit your weekly limit" com um tempo de reposição, e mudar de modelo com /model não restaurará o acesso, porque as janelas são partilhadas entre modelos. Essas janelas seguem a conta em vez do cliente em que se encontra, o que é útil saber se ainda está a determinar o que corre nativamente em Linux e que plano cobre cada interface. Qual das duas janelas esgotou efetivamente decide quanto tempo terá de esperar e o que vale a pena fazer entretanto, por isso compensa conhecer as suas opções quando atinge um limite a meio de uma tarefa. Os planos podem opcionalmente ativar créditos de utilização, geridos com /usage-credits, para comprar utilização para além do limite. Deliberadamente não vou imprimir as quotas dos planos: são os números mais voláteis em todo este tópico, por isso verifique claude.com/pricing e as suas próprias barras /usage. Os mecanismos de tokens continuam a ser importantes numa subscrição; uma sessão desperdiçada consome a sua janela exatamente da mesma forma que consumiria dólares. Para o lado da subscrição, veja que plano Claude se adequa à sua utilização.

As medidas que realmente funcionam

• Limite o que o agente lê. "Corrija o erro de validação em auth.py" lê um ficheiro; "melhore esta base de código" lê quarenta. Mantenha CLAUDE.md conciso: é carregado em todas as sessões, por isso deve conter apenas o essencial. Mova as instruções específicas do fluxo de trabalho para skills carregadas quando necessário.
• Seja claro e conciso. /clear entre tarefas não relacionadas faz com que o contexto obsoleto seja reenviado e cobrado novamente em cada mensagem seguinte. Numa tarefa longa, /compact Focus on the failing tests and the diff resume o histórico progressivamente e evita a curva quadrática.
• Escolha um modelo adequado. O Sonnet trata da maioria das tarefas de programação a $2/$10 por milhão de tokens desde outubro de 2026. Esse é agora o preço padrão, não um preço promocional: o Sonnet 5.5 custa $2/$10, e o Sonnet 5 manteve $2/$10 quando o aumento previsto para $3/$15 em setembro de 1 foi cancelado. Em comparação, o Opus 5.5 custa $4/$20. O Haiku 5.5 custa $0.10/$0.50 para prompts até 100,000 tokens e $0.50/$2.50 acima desse limite, sendo adequado para tarefas mecânicas de subagentes, como a triagem de logs. O Fable 5.1 está no extremo oposto, a $10/$50, a mesma tarifa do Fable 5 e duas vezes e meia a do Opus 5.5 em ambos os sentidos da cobrança. Por isso, convém saber que tarefas justificam realmente essa tarifa antes de o deixar selecionado para tarefas rotineiras. /model permite mudar de modelo durante a sessão.
• Filtre previamente a saída extensa. Um hook que reduz uma execução de testes às falhas com grep antes de Claude a receber transforma 20,000 tokens de resultado de ferramenta em 300. Isso acontece em cada reenvio futuro dessa mensagem.
• Agrupe o que não é interativo. Nas suas próprias pipelines da API, para classificação, revisões em massa e tarefas noturnas, a Batches API executa os mesmos modelos com 50% de desconto em troca de entrega assíncrona.
• Tenha em conta o tempo de vida da cache. Trabalhe em períodos contínuos. Uma sessão do Claude Code num tmux num VPS desligada não tem custo enquanto está inativa; os tokens só são consumidos quando uma interação é executada. No entanto, o tempo de inatividade além do TTL da cache faz perder a cache aquecida, e a interação seguinte paga novamente a reescrita.

FAQ

Quantos tokens uma sessão de programação no Claude Code utiliza?

Não existe um número fixo. Uma única interação a meio da sessão normalmente já inclui dezenas de milhares de tokens de prompt, depois de os ficheiros e o histórico se acumularem. Uma sessão de trabalho chega aos milhões, sendo a maior parte servida a partir da cache por um décimo da tarifa base ou menos, dependendo do modelo. Para referência, os valores empresariais publicados pela Anthropic em outubro de 2026 indicam uma média de cerca de $13 por programador e por dia ativo, com 90% dos utilizadores abaixo de $30. Execute /usage na sua própria sessão. Cinco minutos a monitorizar o resultado são mais úteis do que qualquer média publicada.

Os tokens de raciocínio têm custos mesmo quando não consigo vê-los?

Sim. Os tokens de raciocínio são cobrados como tokens de saída, à tarifa mais elevada, e contam para max_tokens. Os modelos atuais também os cobram quando a interface omite do ecrã o resumo do raciocínio. Se uma resposta for truncada por stop_reason: "max_tokens" antes de terminar a resposta visível, é provável que o raciocínio tenha consumido o orçamento. No Claude Code, reduza o nível de esforço com /effort para tarefas que não precisam de raciocínio profundo.

Por que motivo uma sessão longa do Claude Code fica mais cara por mensagem?

Porque a API não mantém estado. Em cada interação, a conversa que ainda está no contexto é enviada novamente, incluindo todos os ficheiros lidos, resultados de ferramentas e interações anteriores que não tenham sido removidos pela compactação. Tudo isto é cobrado como entrada. Por isso, a interação 50 transporta as interações 1 a 49. A cache de prompts serve o prefixo repetido a um décimo do preço base de entrada na maioria dos modelos (5% no Opus 5.5 e no Sonnet 5.5, 2.5% no Fable 5.1), mas o próprio prefixo continua a crescer. Além disso, qualquer intervalo de inatividade superior ao TTL da cache transforma a interação seguinte numa reescrita cobrada à tarifa total. /compact reduz o histórico; /clear repõe o contexto.

Como verifico a utilização de tokens e os custos do Claude?

No Claude Code, /usage mostra as estatísticas de tokens da sessão, uma estimativa de custos local e barras dos limites do plano nas subscrições (/cost é um alias); /context mostra o que está a ocupar a janela. Para consultar a faturação autorizada da API, utilize a página de utilização na Claude Console. No seu próprio código, leia response.usage. A soma de input_tokens, cache_creation_input_tokens e cache_read_input_tokens fornece o tamanho real do prompt. Para fazer uma estimativa antecipada, utilize o endpoint count_tokens, nunca tiktoken.