Dicas para Economizar Tokens no Claude Code e o Que Acontece ao Atingir o Limite

Uma das primeiras coisas que as pessoas percebem ao começar a usar o Claude Code é a velocidade com que ele consome tokens. Você já pensou: "Eu só editei um arquivo -- como já atingi o limite?"

Este artigo explica por que o Claude Code usa tantos tokens, apresenta 10 técnicas práticas de economia e detalha o que acontece ao atingir o limite e como funcionam os custos extras.

Se você quer usar modelos como DeepSeek, GLM e Kimi no lugar do Claude dentro do Claude Code para reduzir custos, reunimos em Como usar DeepSeek, GLM e Kimi no Claude Code o passo a passo, junto com os cuidados a tomar (cache, cobrança das buscas e para onde o código é enviado).

1. Por Que o Claude Code Consome Tantos Tokens

Diferente de um chat comum, o Claude Code é um sistema agêntico. Uma única instrução do usuário dispara múltiplas chamadas internas à API para completar a tarefa.

Razões Específicas para o Alto Consumo de Tokens

• O prompt do sistema + histórico da conversa são incluídos a cada turno: Cada mensagem reenvia todo o histórico da conversa, então quanto mais longa a conversa, mais rápido o consumo de tokens acelera
• O conteúdo dos arquivos é carregado no contexto: Ao editar código, o conteúdo do arquivo-alvo é puxado para o contexto. Arquivos maiores consomem mais tokens
• As chamadas de ferramentas se encadeiam: Uma única instrução pode disparar etapas internas de busca, leitura, edição e verificação de arquivos. Segundo a documentação da Anthropic, o Claude Code envia a conversa completa a cada requisição e, cada vez que o Claude usa ferramentas, envia outra requisição com esses resultados (Manage costs effectively)
• Tokens de raciocínio contam como saída: O processo interno de "raciocínio" do Claude Code também consome tokens

O processamento desse modelo acontece nos servidores da Anthropic, então trocar seu PC por um mais potente não muda o consumo de tokens nem o tempo que a IA leva para pensar. O que o PC altera é o tempo dos comandos executados localmente e se a memória é suficiente (veja Especificações de PC necessárias para o Claude Code e o Codex).

Para saber mais sobre as diferenças entre os modos do Claude, veja nosso artigo sobre as diferenças entre Claude Chat, Cowork e Code.

2. Limites de Uso e Preços por Plano

O Claude Code é usado fazendo login com um plano pago do Claude (Pro, Max, Team ou Enterprise) ou com uma chave de API do Claude Console. Segundo a página de preços do Claude, o limite de todos os planos é contado em uma janela de sessão que se renova a cada cinco horas, e os planos pagos acrescentam um limite semanal. Não há um número fixo de mensagens: o quanto você pode fazer depende do tamanho das conversas, do modelo escolhido e dos recursos que você usa (página de preços do Claude, consultada em 26 de setembro de 2026).

Fontes: página de preços do Claude, Central de Ajuda da Anthropic "What is the Pro plan?" e "What is the Max plan?", documentação do Claude Code "Manage costs effectively" (todas consultadas em 26 de setembro de 2026). O Ultra é o plano que passou a ter esse nome em 31 de outubro de 2026 (antes, Max 20x). Segundo "What is the Ultra plan?" (Central de Ajuda da Anthropic), o limite semanal é 10 vezes o do Pro, e contas verificadas não têm limite de 5 horas (consultado em 31 de outubro). A verificação é feita automaticamente com base no histórico da conta e de pagamentos; se a barra "Current session" não aparece na página de uso das configurações, sua conta está verificada.

O Fable, o modelo mais alto da linha, tem regras próprias. Na tabela comparativa da página de preços, o Pro só pode usá-lo com créditos de uso, enquanto o Max e o Ultra podem usá-lo até 50% do limite semanal. No Claude Code, dependendo do plano, o uso do Fable pode ser cobrado nos créditos de uso em vez da cota do plano; nesse caso, a linha do Fable em /model mostra "Requires usage credits" e o Claude Code pede confirmação antes de cobrar (Model configuration).

Para uma comparação detalhada de preços, veja nosso artigo sobre comparação de preços entre Claude e ChatGPT.

3. 10 Técnicas para Economizar Tokens

Ao aplicar as técnicas a seguir, você pode reduzir significativamente o consumo de tokens.

Ainda assim, antes de começar a cortar vale medir o que está ocupando o contexto. Veja o detalhamento com o /context, confirme o consumo real com o /usage e obtenha o custo por Skill com o /skill-doctor. Tratamos disso em detalhe em o que está consumindo o seu contexto no Claude Code.

Dica 1: Resete o Contexto Frequentemente com /clear

Ao mudar para uma tarefa diferente, execute /clear para resetar a conversa. O histórico de conversa acumulado significa que tokens desnecessários são reenviados a cada mensagem.

# Após terminar o trabalho na autenticação
/clear

# Iniciar a próxima tarefa
"Adicionar recurso de pagamento"

Dica 2: Comprima Conversas com /compact

Você pode comprimir uma conversa longa durante a sessão. Adicione instruções personalizadas para manter apenas o que importa.

# Compressão básica
/compact

# Compressão com instruções personalizadas
/compact Manter apenas as alterações de código e specs da API

Dito isso, você não ganha mais quanto mais vezes aperta. O custo de uma compactação oscila conforme o cache de prompt esteja quente ou não, e apertar logo depois de uma pausa é o caso mais caro de todos. Onde apertar é tratado em detalhe em quando apertar o /compact.

Dica 3: Diga Exatamente o que Ler

Quando o pedido é vago, o Claude Code procura amplamente arquivos que possam ser relevantes e os lê, e o contexto cresce na mesma medida. A documentação da Anthropic diz o mesmo: um pedido vago como "melhore esta base de código" provoca uma varredura ampla, enquanto um específico como "adicione validação de entrada à função login em auth.ts" permite trabalhar com o mínimo de leituras (Manage costs effectively). Se você já sabe qual arquivo importa, mencione-o com @ e o Claude o traz para a conversa sem precisar procurá-lo (Common workflows). Um arquivo mencionado com @ entra com todo o conteúdo, e um diretório mostra a lista de arquivos em vez do conteúdo, então mencione só os arquivos de que precisa.

❌ "Melhore esta base de código"
→ O Claude busca amplamente e lê o que parecer relevante (mais tokens de entrada)

✅ "Adicione validação de entrada à função login em @src/auth.ts"
→ O trabalho fica no arquivo que importa

Dica 4: Troque de Modelo Conforme a Tarefa

Você não precisa de um modelo de nível alto para todas as tarefas. Em 26 de setembro de 2026, o modelo padrão do Claude Code é o Opus 5.5 no Pro, no Max, no Team, no Enterprise e na API (Model configuration). Por token, porém, o Sonnet, de nível intermediário, custa cerca de metade do Opus, e o leve Haiku é ainda mais barato: em 12 de outubro de 2026, o Haiku 5.5 custa 40 vezes menos que o Opus em prompts de até 100 mil tokens (veja a tabela da seção 5). A documentação da Anthropic também diz que o Sonnet dá conta da maioria das tarefas de programação e custa menos que o Opus, recomenda reservar o Opus para decisões de arquitetura complexas e raciocínio em várias etapas, e sugere especificar o Haiku para tarefas simples de subagentes (Manage costs effectively). Também nos planos de assinatura, o quanto você pode fazer depende do modelo escolhido. Mesmo que as proporções mudem com uma nova versão, o critério continua o mesmo: escolha o nível de acordo com a dificuldade da tarefa.

# Usar Sonnet para codificação do dia a dia
/model sonnet

# Usar Opus para decisões de arquitetura ou refatorações complexas
/model opus

Dica 5: Peça Respostas Mais Curtas

Respostas mais longas da IA significam mais tokens de saída. Instruções como "apenas código" ou "responda em uma linha" reduzem a saída desnecessária.

❌ "Corrija esta função"
→ A IA gera uma explicação longa + código + notas (muitos tokens de saída)

✅ "Corrija esta função. Sem explicação, apenas o código"
→ Apenas código (muito menos tokens de saída)

Dica 6: Limite os Tokens de Raciocínio

No Claude Code, o pensamento estendido (extended thinking) vem ativado por padrão, e os tokens de pensamento são cobrados como tokens de saída. Dependendo do modelo, o orçamento padrão pode chegar a dezenas de milhares de tokens por requisição. Para trabalhos que não exigem raciocínio profundo, baixar o nível de esforço com /effort (ou em /model) reduz o custo. O Opus 5.5 e os modelos Fable sempre pensam, então neles você ajusta o esforço (Manage costs effectively). O esforço padrão do Opus 5.5 é medium; o da maioria dos outros modelos, high (Model configuration).

# Esforço reduzido para tarefas simples
/effort low

Dica 7: Mantenha o CLAUDE.md Conciso

O CLAUDE.md (o arquivo de instruções do projeto) é carregado no contexto quando a sessão começa e depois segue em todas as requisições seguintes. Se ele traz instruções passo a passo para fluxos específicos, como revisões de PR ou migrações de banco de dados, você paga esses tokens mesmo fazendo outra coisa. A recomendação oficial é mover essas instruções para skills, que só são carregadas quando invocadas (Manage costs effectively).

Dica 8: Aproveite os Sub-Agentes

Delegue a um subagente o trabalho que gera muita saída, como rodar testes, buscar documentação ou processar arquivos de log. A saída extensa fica no contexto do subagente e só um resumo volta para a conversa principal. Mesmo assim, as requisições do próprio subagente contam para o seu uso; para gastar menos com elas, dê ao subagente um modelo menor, como o Haiku (Manage costs effectively).

Dica 9: Forneça Especificações desde o Início para Evitar Retrabalho

Um vai e volta como "construa isso, depois corrija, depois mude" desperdiça tokens. Fornecer especificações claras desde o início evita retrabalho e mantém o consumo de tokens linear.

❌ Padrão de conversa (crescimento exponencial de tokens):
"Crie um recurso de login" → "Adicione validação"
→ "Na verdade, mude para autenticação por e-mail" → "Mude a interface também"

✅ Padrão com especificações (crescimento linear de tokens):
"Crie um recurso de login com estas especificações:
- Autenticação por e-mail + senha
- Validação de e-mail (verificação de formato + duplicidade)
- Requisitos de senha: 8+ caracteres, alfanuméricos
- Interface do formulário de login: centralizada, layout em card"

Para mais dicas sobre como escrever prompts eficazes, veja nosso artigo sobre dicas de prompt para desenvolvimento com IA.

Dica 10: Atente-se aos Formatos de Arquivo

Na API do Claude, cada página de um PDF custa os tokens do texto extraído (em geral de 1.500 a 3.000 tokens por página) mais os da página convertida em imagem (documentação da API do Claude, "PDF support"). O Claude Code lê PDFs curtos inteiros e, os de mais de 10 páginas, em trechos de até 20 páginas (Tools reference). Indique só as páginas de que precisa ou converta o arquivo em texto antes de passá-lo.

4. O que acontece ao atingir o limite: a janela de 5 horas, o limite semanal e os créditos de uso

Primeiro, o ponto principal: os planos de assinatura podem, sim, gerar cobranças extras, mas nunca sozinhos. Para continuar trabalhando além do limite, você mesmo precisa ativar os créditos de uso (usage credits) e colocar um saldo pré-pago. Se não fizer isso, o Claude Code simplesmente para no limite, você espera a janela se renovar e sua fatura não muda (Central de Ajuda da Anthropic, "Manage usage credits for paid Claude plans").

Duas camadas de limite: a janela de 5 horas e o limite semanal

• Janela de 5 horas (limite de sessão): uma cota que se renova a cada cinco horas. Pro, Max e Team têm
• Limite semanal: um teto semanal comum a todos os modelos. Ele se renova no dia e horário fixos atribuídos à sua conta, que não mudam conforme o dia em que você começa a usar o Claude ou em que assinou. Você vê a próxima renovação em Settings > Usage no claude.ai (Central de Ajuda, "What is the Pro plan?" e "What is the Max plan?")
• Limites por modelo: alguns limites valem só para o Opus ou só para o Sonnet

O uso é descontado ao mesmo tempo da janela de 5 horas e do limite semanal. Um pico de atividade intensa, como disparar muitos subagentes de uma vez, pode esgotar o limite semanal antes de a janela de 5 horas se renovar. Perto de um limite aparece um aviso como You've used 85% of your session limit · resets 3:45pm, e ao atingi-lo o Claude Code para com mensagens como estas (documentação do Claude Code, "Error reference"):

You've hit your session limit · resets 3:45pm
You've hit your weekly limit · resets Mon 12:00am
You've hit your Opus limit · resets 3:45pm

Suas opções ao atingir o limite no Pro ou no Max

Fontes: documentação do Claude Code "Error reference" e "Wait for a usage limit to reset", Central de Ajuda da Anthropic "Use Claude Code with your Pro or Max plan" e as perguntas frequentes da página de preços do Claude (consultadas em 26 de setembro de 2026). O que fazer diante de cada mensagem está em You've hit your session limit no Claude Code: o que significa e o que fazer.

Como funcionam os créditos de uso (Pro e Max)

• Onde ativar: na seção "Usage credits" de Settings > Usage no claude.ai. No Claude Code, /usage-credits abre essa página no navegador (só quando você está logado com uma assinatura do claude.ai; não funciona com chave de API)
• Pagamento: pré-pago. Você compra saldo em "Add funds" e pode ativar a recarga automática (auto-reload) para completá-lo quando ficar baixo
• Freio: dá para definir um limite de gastos mensal (ou escolher "Set to unlimited"). Se você o atingir ainda com créditos, o Claude Code pergunta se quer aumentar ou remover o limite
• Tarifa: as tarifas padrão da API (a tabela da seção 5), que aparecem como cobrança separada da assinatura. A janela de 5 horas continua se renovando normalmente
• Confirmação: você recebe avisos ao se aproximar do limite e ao atingi-lo, e precisa confirmar antes de continuar com créditos
• Desativar: dá para desligar a qualquer momento em Settings > Usage; a partir daí você usa só a cota do plano

Dois detalhes passam despercebidos com facilidade. O primeiro é a duração do cache. Dentro da cota do plano, o cache da conversa principal do Claude Code dura uma hora, mas cai para cinco minutos enquanto você consome créditos de uso. Se parar por mais de cinco minutos, a mensagem seguinte relê a conversa inteira e os créditos acabam mais rápido (Manage costs effectively). O segundo é a validade. Na maioria dos lugares os créditos comprados não expiram, mas em algumas jurisdições, como o Japão, eles expiram seis meses após a compra a partir de 10 de setembro de 2026, com um aviso por e-mail sete dias antes.

Se você não quer pagar nada a mais

• Não ative os créditos de uso (se já estiverem ativos, desative-os em Settings > Usage)
• Não deixe a variável de ambiente ANTHROPIC_API_KEY definida. Se ela estiver, o Claude Code se autentica com essa chave de API em vez da sua assinatura, e o seu uso é cobrado como uso da API (Central de Ajuda, "Use Claude Code with your Pro or Max plan"). /status mostra com qual conta você está trabalhando
• Faça login só com a sua conta Pro ou Max, sem adicionar credenciais do Claude Console (API) (mesmo artigo)

Team e Enterprise

• Team e Enterprise por assento: o uso de cada membro sai de uma cota por assento que se renova em uma janela de cinco horas e em outra semanal. A cota é compartilhada com o chat e o Cowork, e o tamanho depende do tipo de assento (padrão ou premium). Só é possível continuar além dela se um administrador ativar os créditos de uso, com limites de gastos por organização, grupo ou membro (Manage costs effectively). No Team os créditos são pré-pagos; no Enterprise por assento, o uso real é faturado no fim de cada mês (Central de Ajuda, "Manage usage credits for Team and seat-based Enterprise plans")
• Se um membro sem permissão de faturamento rodar /usage-credits, o Claude Code pede confirmação e envia uma solicitação aos administradores
• Enterprise por consumo (planos novos e self-service): não há cota por assento; todo o uso é cobrado pelas tarifas da API desde o primeiro token. O uso para quando o limite de gastos da organização ou do membro é atingido (Central de Ajuda, "How am I billed for my Enterprise plan?")

Chave de API (pague pelo uso)

• Não há janela de 5 horas nem limite semanal; você paga tudo o que usar
• Se passar de um limite de taxa por minuto (requisições, tokens de entrada ou tokens de saída por minuto), recebe um erro 429, com um cabeçalho retry-after indicando quanto esperar
• Cada nível de uso, que depende do seu histórico, tem um teto de gastos mensal (Start $500, Build $1.000, Scale $200.000). Ao atingi-lo, o uso fica pausado até 00:00 UTC do dia 1º do mês seguinte. Você também pode definir um limite próprio, mais baixo (documentação da API do Claude, "Rate limits")
• Em uma organização, também é possível pôr limites de gastos nos workspaces do Claude Console (Manage costs effectively)
• Os planos Max e Team incluem todo mês créditos para usar na API ($100 no Max e $200 no Ultra). Você os recebe vinculando uma organização do Claude Console, e eles valem também para o claude -p executado com chave de API, mas não para o Claude Code interativo ("Os créditos de API mensais dos planos Max e Team do Claude")

Como conferir o que resta e o que você gastou

• /usage: barras de uso do plano, o gasto do mês com créditos de uso e um detalhamento do que consumiu sua cota (skills, subagentes, servidores MCP etc.). /cost e /stats são apelidos. O detalhamento é calculado com o histórico de sessões desta máquina, então não inclui o uso em outros dispositivos nem no claude.ai
• Settings > Usage no claude.ai: o andamento da janela de 5 horas e do limite semanal, e quando cada um se renova
• Linha de status: adicione os campos rate_limits para manter o que resta sempre à vista
• /status: com qual conta você está trabalhando
• Com chave de API: a página Usage do Claude Console (platform.claude.com/usage)

Fontes: Manage costs effectively, Error reference, Commands (consultadas em 26 de setembro de 2026).

5. Como Funciona a Cobrança por Uso da API

Na API, o preço por token é definido pelo nível do modelo (topo, alto, intermediário, leve). Os preços individuais mudam a cada versão, mas as relações — quanto mais alto o nível, mais caro; a saída custa cinco vezes a entrada; e o que é lido do cache custa muito menos que a entrada — se mantiveram entre as gerações até agora. Preços em 12 de outubro de 2026:

* MTok = 1 milhão de tokens. Fonte: Claude Platform Docs, "Pricing" (consultado em 12 de outubro de 2026). Os preços do Haiku 5.5 valem para prompts de até 100 mil tokens; acima disso, passam a $0.50 de entrada, $2.50 de saída e $0.05 de leitura de cache. A leitura de cache do Sonnet 5.5 caiu de 10% para 5% da entrada em 7 de outubro de 2026. O Haiku 4.5 anterior ($1 de entrada, $5 de saída) passou a ser um modelo legado (legacy) e continua disponível. Para os preços atuais e a comparação entre modelos, veja a comparação de preços de Opus, Sonnet e Haiku; para os modelos atuais de cada empresa, a lista de modelos atuais e datas de corte.

O Que É o Cache de Prompt?

A Anthropic oferece um recurso de cache de prompt: quando o mesmo contexto (prompt do sistema e conversa recente) é reutilizado, o que é lido do cache custa 10% do preço base de entrada (e ainda menos no Opus 5.5 e no Sonnet 5.5, com 5%, e no Fable 5.1, com 2,5%, como na tabela acima). Em troca, gravar no cache custa 1,25 vez a entrada com validade de 5 minutos e 2 vezes com validade de uma hora.

Quanto o cache dura depende de como você é cobrado. Dentro da cota de um plano de assinatura, o Claude Code dá à conversa principal um cache de uma hora; com créditos de uso, chave de API ou provedor de nuvem, o padrão é de cinco minutos (documentação do Claude Code, "Prompt caching"). Com a duração de cinco minutos, uma pausa de mais de cinco minutos faz o cache expirar, e a mensagem seguinte grava todo o contexto no cache de novo. Definir promptCacheTtl como 1h estende a conversa principal para uma hora (com preço de escrita mais alto).

6. Resumo

FAQ

Fontes

Fontes primárias consultadas (obtidas em 26 de setembro de 2026): documentação do Claude Code Manage costs effectively / Error reference / Interactive mode / Prompt caching / Model configuration / Commands / Tools reference; documentação da API do Claude Pricing / Rate limits / PDF support; a página de preços do Claude; Central de Ajuda da Anthropic créditos de uso (Pro e Max) / créditos de uso (Team e Enterprise) / Claude Code com Pro ou Max / plano Pro / plano Max / faturamento do Enterprise. Preços, limites e disponibilidade podem mudar, então confira as páginas oficiais antes de assinar.