O que são tokens no Claude Code e quanto custam

O que são tokens no Claude?

Um token é a unidade de texto que o Claude lê e escreve: um fragmento de uma palavra, com aproximadamente 3.5 caracteres em inglês. Esse valor vem do glossário da Anthropic e corresponde a bem mais de um token por palavra quando se contam espaços e pontuação. Por isso, mil palavras de prosa representam confortavelmente mais de 1,300 tokens. O código consome mais tokens por linha: chavetas, operadores, underscores e indentação geram mais tokens por carácter do que o inglês. Um ficheiro de código-fonte com algumas centenas de linhas normalmente representa vários milhares de tokens. Um ficheiro com 2,000 linhas que o agente decida ler representa um consumo de cinco algarismos de tokens antes de ser escrita qualquer linha de código nova.

Há dois aspetos dos tokenizadores que causam confusão. Primeiro, são específicos de cada modelo. Em julho de 2026, Opus 4.7 e posteriores, Sonnet 5 e Fable 5 usam um tokenizador mais recente que produz aproximadamente 30% mais tokens para o mesmo texto do que os modelos Claude anteriores. O aumento exato varia conforme o conteúdo. Isto altera qualquer orçamento calculado em tokens, embora os preços por token não tenham aumentado com essa mudança. Segundo, tiktoken, a biblioteca usada na maioria dos artigos, é o tokenizador da OpenAI e subestima o número de tokens do Claude em aproximadamente 15–20% para texto comum, e ainda mais para código. A única contagem fiável é a do endpoint count_tokens, explicado 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, resulta de um único contador: tokens de entrada e tokens de saída. A página de preços faz isto parecer simples: determinado valor por milhão de tokens de entrada e outro por milhão de tokens de saída. O que ela não explica é que, numa sessão de programação agentic, o contador de entrada é utilizado muito mais do que a intuição sugere, porque a conversa completa é reenviada em cada interação. Vendo infraestrutura com tarifação por consumo há quinze anos, este é o primeiro contador que encontrei em que a maioria dos clientes não consegue realmente dizer o que o está a fazer avançar. Esta é a lição sobre como ler o contador: o que conta como entrada e saída numa sessão agentic, por que o ciclo de reenvio é tão dispendioso, como o prompt caching altera os cálculos e quais os controlos que realmente mudam o valor.

Tudo é entrada: o que o medidor realmente contabiliza

As pessoas presumem que pagam pelo código que o Claude escreve. Numa sessão agêntica, esse é o menor item da fatura. Os tokens de entrada, com uma tarifa mais baixa, mas em volume muito maior, incluem:

• O prompt do sistema. As próprias instruções do harness do Claude Code, além de CLAUDE.md e dos seus ficheiros 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 ao qual se liga 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 ferramenta. Execuções de testes, saída de 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 acabou de lhe faturar o equivalente a um pequeno livro.
• 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 é stateless. Ela não guarda a sua sessão entre pedidos; na realidade, nada o faz. No turno 2, o cliente envia o turno 1, a resposta do modelo e a sua nova mensagem. No turno 50, reenvia os turnos 1 a 49, todos os ficheiros lidos, todos os resultados das ferramentas, todas as diferenças e o turno 50. O modelo volta a ler toda a transcrição em cada pedido, e todos esses tokens relidos são cobrados como entrada.

A consequência é que o custo por turno aumenta aproximadamente de forma linear com a duração da sessão, enquanto 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, apesar de conter a mesma pergunta de uma linha, porque transporta sessenta turnos de contexto. Este é o único facto que explica a maioria dos pedidos relacionados com faturas inesperadamente elevadas. Não é uma particularidade do Claude: qualquer produto LLM que pareça manter estado é, por baixo, uma API stateless com um ciclo de reenvio.

Saída: o que vê, além do raciocínio que não vê

Os tokens de saída são o componente mais caro, cinco vezes a tarifa de entrada em toda a linha atual ($5/$25 no Opus 4.8, $3/$15 no Sonnet 5, $1/$5 no Haiku 4.5, em julho 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. Dois factos são importantes. O raciocínio é faturado à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. Além disso, nos modelos atuais o resumo do raciocínio pode nem ser apresentado. O Opus 4.8, o Sonnet 5 e o Fable 5 não o mostram por predefinição, mas o raciocínio continua a ocorrer e continua a ser faturado. Invisível não significa gratuito.

O Claude Code ativa o raciocínio prolongado por predefinição porque melhora de forma mensurável o trabalho em várias etapas, e o orçamento predefinido pode chegar a dezenas de milhares de tokens por pedido. Em tarefas mais simples, pode reduzi-lo: diminua o nível de esforço com /effort ou em /model, ou ajuste as definições de raciocínio em /config. Esta é uma forma real de controlar os custos, não uma superstição.

O cache de prompts muda 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 servi-lo por uma fração do preço. Em julho de 2026, os multiplicadores são: 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×. As gravações têm um custo adicional; as leituras têm um desconto de 90%. Uma única leitura já compensa mais do que o custo adicional da gravação de 5 minutos.

O Claude Code gere o cache por si. Numa sessão saudável, quase todo esse reenvio grande é servido a partir do cache. No entanto, o cache predefinido permanece válido durante cinco minutos desde a última utilização. Afaste-se para tomar um café que demora mais do que esperava, volte, envie uma mensagem, o cache expirou e todo o prefixo acumulado é gravado novamente a 1.25%, em vez de ser lido a 0.1%. Numa sessão com 150K tokens, esse único turno sem cache custa mais do que uma dúzia de turnos com cache. Este é o resultado contraintuitivo que deve reter: um ritmo de pausa e retoma pode custar mais do que o trabalho contínuo, porque cada intervalo de inatividade superior ao TTL transforma o turno seguinte de uma leitura barata numa gravação cara. Trabalhe em períodos concentrados. Não alimente uma sessão grande com uma mensagem a cada dez minutos.

Se chamar a API a partir da sua própria aplicação num VPS, não obtém nada disto gratuitamente. O erro clássico provocado pelo próprio utilizador é interpolar um timestamp ou um ID de pedido no prompt do sistema. Isso altera os bytes do prefixo em cada pedido e desativa o cache silenciosamente. O indicador é usage.cache_read_input_tokens permanecer a zero em chamadas visualmente idênticas.

A fórmula, com um exemplo prático

Ignore quem apresenta um valor fixo de “$X por sessão”. As sessões podem variar em 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 0.10 x base input price)
          + (output incl. thinking x output price)

session cost = sum over all turns

Exemplo prático com Claude Opus 4.8, que em julho de 2026 custa $5 por milhão de tokens de entrada e $25 por milhão de tokens de saída. Uma interação a meio da sessão, com 80,000 tokens de contexto acumulado: 75,000 lidos da cache, 3,000 escritos recentemente, 2,000 tokens de entrada novos não armazenados 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 armazenada em cache: 2,000 × $5/M = $0.010
• Saída: 1,500 × $25/M = $0.0375

Cerca de $0.10 por interação; cinquenta interações como esta custam cerca de $5. Agora considere a mesma interação depois de a cache expirar: reescrever os 80,000 tokens completos a $6.25/M custa $0.50 antes da saída, aproximadamente cinco vezes o custo total da interação com a cache ativa, para o mesmo trabalho. Essa diferença resume toda a questão da cache num único número. As mesmas quatro linhas são também a única forma rigorosa de comparar fornecedores, porque as tarifas anunciadas ignoram completamente as leituras da cache e o raciocínio, e executar estes cálculos em três trabalhos reais mostra onde o custo do Claude fica acima ou abaixo do custo do OpenAI.

Se pretende compreender a própria unidade de faturação, em vez de apenas uma interação, o que um milhão de tokens representa em páginas, ficheiros e dólares aplica os mesmos cálculos a um nível mais abrangente. Para referência, não para previsão: os valores publicados pela Anthropic para implementações empresariais do Claude Code indicam, em julho de 2026, uma média de cerca de $13 por programador por dia ativo e $150–250 por mês, com 90% dos utilizadores a permanecerem abaixo de $30 por dia. O seu consumo depende do modelo escolhido, da gestão das sessões e do tamanho da base de código, precisamente por isso os controlos abaixo são importantes.

Como consultar o seu próprio consumo

No Claude Code, o comando é /usage (/cost continua a funcionar, porque é um 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 por 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. Para obter dados oficiais de faturação em contas de API, a página de utilização na Claude Console é a fonte de referência; o valor apresentado pela CLI é uma estimativa. /context apresenta uma grelha colorida de o que ocupa a janela de contexto, incluindo o prompt do sistema, ferramentas, definições MCP, ficheiros e histórico. É a forma mais rápida de detetar um CLAUDE.md demasiado grande ou um servidor MCP demasiado comunicativo. Passe all para expandir a discriminação completa por item.

Na API, cada resposta indica exatamente o que aconteceu:

response = client.messages.create(model="claude-sonnet-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 representa apenas o restante não armazenado em cache. O tamanho real do prompt é a soma dos três campos de entrada. Um agente que tenha funcionado durante uma hora e apresente input_tokens: 4000 não é barato; os outros 200,000 tokens foram fornecidos a partir da cache. Para fazer uma estimativa antes do envio, use o endpoint de contagem de tokens. A chamada é gratuita, usa um limite de taxa próprio e faz a contagem com o tokenizer 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",
                                     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

A mecânica deste guia é idêntica em qualquer opção; apenas a cobrança é diferente. Com uma chave de API, a Anthropic cobra conforme o uso, por token, às tarifas publicadas. Todos os valores acima correspondem a dinheiro real. Esse contador começa mais cedo do que a maioria das pessoas espera, porque não existe um nível gratuito de reserva. Há apenas um pequeno crédito no registo e alguns endpoints que não são cobrados. Isto explica o que uma nova conta de API recebe antes de associar um cartão. Numa subscrição Claude (Pro, Max, Team, Enterprise), o uso do Claude Code é descontado da franquia incluída no plano. Em julho de 2026, essa franquia corresponde a uma janela contínua de sessão de cinco horas e a uma janela semanal, partilhadas entre os modelos e com as conversas em claude.ai. O valor em dólares /usage é apenas informativo, não uma cobrança. Quando esgotar uma janela, verá "You've hit your session limit" ou "You've hit your weekly limit", com a indicação da hora de reposição. Mudar de modelo com /model não repõe o acesso, porque as janelas são partilhadas entre os modelos. Essas janelas estão associadas à conta, não ao cliente que está a utilizar. Isto é importante se ainda estiver a determinar o que funciona nativamente no Linux e que plano cobre cada superfície. A janela que foi efetivamente esgotada determina a duração da espera e as medidas que fazem sentido entretanto. Por isso, é útil conhecer as opções quando atinge um limite durante uma tarefa. Os planos podem ativar créditos de uso opcionais, geridos com /usage-credits, para comprar uso além do limite. Não vou indicar as quotas dos planos. São os valores mais voláteis de todo este tema. Consulte claude.com/pricing e as suas próprias /usage barras. A mecânica dos tokens continua a ser relevante numa subscrição: uma sessão ineficiente consome a janela exatamente como consumiria dinheiro. Para a parte relativa às subscrições, consulte qual plano Claude é adequado para o seu uso.

Os mecanismos que realmente funcionam

• Defina o âmbito do 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. Limite-o ao essencial e mova as instruções específicas do fluxo de trabalho para skills carregadas a pedido.
• Seja claro e conciso. /clear entre tarefas não relacionadas, o contexto obsoleto é reenviado e cobrado novamente em cada mensagem seguinte. Numa tarefa longa, /compact Focus on the failing tests and the diff resume o histórico e evita que os custos sigam uma 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, segundo os preços introdutórios em julho de 2026 ($3/$15 ao preço normal, contra $5/$25 do Opus), e o Haiku, a $1/$5, é a escolha certa para tarefas mecânicas de subagentes, como a triagem de logs. O Fable 5 está no extremo oposto, a $10/$50, o dobro do Opus nos dois lados da métrica. Por isso, convém saber que tarefas justificam realmente esse preço antes de o deixar selecionado para trabalho rotineiro. /model permite mudar de modelo a meio da sessão.
• Pré-filtre a saída detalhada. Um hook que usa grep para reduzir a execução dos testes às falhas antes de o Claude a receber transforma 20,000 tokens de resultado de ferramenta em 300. Isto acontece em cada reenvio futuro dessa interação.
• Agrupe o que não é interativo. Nas suas pipelines de API, para classificação, revisão em massa e tarefas noturnas, a Batches API executa os mesmos modelos com 50% de desconto, em troca de uma entrega assíncrona.
• Tenha em conta o ciclo da cache. Trabalhe em períodos contínuos. Uma sessão do Claude Code num tmux num VPS desligada não custa nada enquanto está inativa: os tokens só são consumidos quando uma interação é executada. No entanto, o tempo de inatividade faz perder a cache aquecida, e a interação seguinte paga novamente o custo de reescrever o contexto.

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 costuma conter dezenas de milhares de tokens de prompt quando os ficheiros e o histórico se acumulam, e 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. Para referência, os valores empresariais publicados pela Anthropic em julho de 2026 indicam uma média de cerca de $13 por programador por dia ativo, com 90% dos utilizadores abaixo de $30. Execute /usage na sua própria sessão. Monitorizá-lo durante cinco minutos é mais útil do que qualquer média publicada.

Os tokens de raciocínio têm custo mesmo quando não os consigo ver?

Sim. Os tokens de raciocínio são faturados como tokens de saída, à tarifa mais elevada, e contam para max_tokens. Os modelos atuais também os faturam quando a interface não apresenta o resumo do raciocínio. Se uma resposta for truncada com 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 aprofundado.

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, reenvia toda a conversa, cada ficheiro lido, cada resultado de ferramenta e cada interação anterior como entrada faturada. Assim, a interação 50 transporta as interações 1 a 49. A cache de prompts serve o prefixo repetido por cerca de um décimo do preço base da entrada, mas o próprio prefixo continua a crescer. Qualquer intervalo de inatividade superior ao TTL da cache transforma a interação seguinte numa reescrita ao preço total. /compact reduz o histórico; /clear reinicia-o.

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

No Claude Code, /usage mostra as estatísticas de tokens da sessão, uma estimativa do custo local e as 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 oficial 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 dá o tamanho real do prompt. Para estimar antecipadamente, utilize o endpoint count_tokens, nunca tiktoken.