Como Reduzir Custos de Tokens de Agentes via CLI (Guia 2026)

Um agente de codificação CLI parece barato até a fatura chegar. Você aponta Claude Code ou Codex para um repositório, pede para refatorar um módulo e, dez minutos depois, ele já leu dezenas de arquivos, executou testes várias vezes e consumiu milhares de tokens em contexto que não precisava existir. Em uma equipe com vários engenheiros usando agentes o dia todo, esse desperdício deixa de ser detalhe. A boa notícia: dá para reduzir muito o custo diretamente pela linha de comando, sem trocar de modelo nem aceitar respostas piores.

Experimente o Apidog hoje

TL;DR

Para reduzir custos de tokens em agentes CLI:

• delimite o conjunto de arquivos antes de iniciar a tarefa;
• mantenha arquivos como CLAUDE.md curtos;
• use /compact ou /clear entre tarefas;
• ative cache de prompts para prefixos estáveis;
• roteie subtarefas simples para modelos menores;
• filtre logs e saídas de ferramentas;
• meça o custo por execução.

O objetivo é simples: cortar contexto antes que ele chegue ao modelo.

Introdução

O custo aparece de duas formas. Você pode bater em um limite semanal no meio de uma tarefa, ou receber uma fatura mensal alta o suficiente para alguém perguntar por que um “assistente de IA” custa mais do que deveria.

A causa costuma ser a mesma: agentes CLI são famintos por tokens por padrão. Eles:

• leem arquivos inteiros quando precisam de poucas linhas;
• reenviam o histórico completo a cada turno;
• colocam logs brutos no contexto;
• repetem o mesmo prompt do sistema e mapa do repositório várias vezes por dia.

Uma refatoração que exige raciocinar sobre 2.000 tokens de código não precisa carregar 180.000 tokens de contexto. A diferença entre esses números é onde está a economia.

Este guia mostra como cortar esse desperdício com práticas implementáveis hoje: higiene de contexto, cache de prompts, roteamento de modelos, limitação de saída de ferramentas e medição de custo por execução. Os exemplos usam Claude Code e Codex, mas a lógica se aplica a qualquer agente cobrado por tokens.

Um custo adjacente importante é depuração. Quando um agente chama uma API interna instável, ele pode tentar novamente, ler erros, reler docs e entrar em loop. Cada iteração custa tokens.

💡 Se seus agentes acessam APIs, projetar, mockar e testar essas APIs no Apidog antes de apontar um agente para elas reduz uma categoria inteira de tentativa e erro caro. O agente trabalha contra um contrato previsível, não contra um endpoint ativo que muda ou falha inesperadamente.

Para onde os tokens vão em uma execução de agente CLI

Cada turno do agente envia uma entrada ao modelo e recebe uma saída. Você paga por ambos. Em geral, tokens de saída custam mais do que tokens de entrada, enquanto o volume de entrada é o que mais infla a conta.

Em uma execução típica, a entrada inclui:

• Prompt do sistema e definições de ferramentas
  
  Instruções do agente e schemas JSON das ferramentas. Isso é reenviado a cada turno.

• Arquivos de memória e projeto
  
  Arquivos como CLAUDE.md, convenções do repositório e instruções persistentes. Eles entram no contexto mesmo quando não são relevantes.

• Histórico da conversa
  
  Mensagens anteriores, respostas do modelo, chamadas de ferramenta e resultados. Em sessões longas, costuma ser o maior custo.

• Conteúdo de arquivos lidos
  
  Uma leitura de arquivo grande pode adicionar milhares de tokens ao contexto.

• Saída de ferramentas
  
  Logs de testes, npm install, git diff, stack traces e mensagens verbosas entram no contexto e são reenviados depois.

A saída inclui explicações, raciocínio, comandos e edições de código. Ela costuma ser menor do que a entrada, mas é mais cara por token.

O ponto crítico: o histórico é reenviado a cada turno. Uma sessão de 30 turnos não custa apenas 30 vezes um turno pequeno. Os turnos finais carregam tudo o que veio antes.

Se quiser entender melhor como sessões e limites funcionam, veja como a janela de tokens do Claude Code é reiniciada.

Higiene de contexto e arquivos de memória

O token mais barato é o que você nunca envia. Comece reduzindo a entrada antes que o agente tenha chance de desperdiçá-la.

1. Defina o conjunto de trabalho

Evite abrir o agente na raiz do repositório com um pedido amplo como “refatore a lógica de faturamento”. Isso incentiva exploração excessiva.

Use prompts com escopo explícito:

claude "refatore a lógica de retry para usar exponential backoff,
apenas em src/payments/retry.ts e no arquivo de teste correspondente"

Se o agente precisa explorar, limite a busca a um diretório:

claude "encontre a implementação de retry em src/payments e proponha a menor alteração possível"

Nomear arquivos reduz leituras desnecessárias.

2. Mantenha CLAUDE.md curto

Arquivos de memória são carregados a cada turno. Se o seu CLAUDE.md virou uma wiki interna, você está pagando por essa wiki repetidamente.

Meça o tamanho aproximado:

wc -c CLAUDE.md | awk '{print "≈", int($1/4), "tokens por turno"}'

Um bom arquivo de memória deve conter:

• comandos de build e teste;
• convenções obrigatórias;
• padrões de estilo realmente usados;
• links para documentos maiores, não os documentos inteiros.

Exemplo de estrutura enxuta:

# Regras do projeto

## Testes
- Unit tests: npm test -- --runInBand
- Lint: npm run lint

## Convenções
- Não usar default exports em src/services.
- Preferir funções puras em src/core.
- Validar payloads com Zod antes de chamar APIs externas.

## Docs sob demanda
- Arquitetura de pagamentos: docs/payments.md
- Contratos internos de API: docs/api-contracts.md

Se uma seção só importa uma vez por mês, remova do arquivo sempre carregado.

3. Compacte ou limpe sessões longas

Quando terminar uma tarefa lógica, não continue usando o mesmo contexto para outra tarefa. Use compactação ou limpeza.

# No Claude Code:
/compact

Use quando quiser preservar um resumo curto do que aconteceu.

# Para começar uma tarefa não relacionada:
/clear

Regra prática:

• uma tarefa lógica por sessão;
• /compact antes de continuar em uma tarefa relacionada;
• /clear antes de mudar de assunto.

Os padrões em Fluxos de trabalho do Claude Code dependem bastante desse controle de escopo.

4. Use arquivos de ignore

Mantenha fora do alcance do agente:

• node_modules/;
• dist/;
• build/;
• arquivos lock gerados;
• logs;
• snapshots grandes;
• artefatos de cobertura.

Exemplo:

node_modules/
dist/
build/
coverage/
*.log
package-lock.json
pnpm-lock.yaml
yarn.lock

Se o agente não vê esses arquivos, ele não gasta tokens lendo ou comparando esses conteúdos.

Cache de prompts: pare de pagar pelo mesmo prefixo

Cache de prompts permite que o provedor armazene partes estáveis da solicitação, como prompt do sistema, ferramentas e convenções do repositório. Nas chamadas seguintes, esse prefixo pode ser reutilizado com desconto.

A regra estrutural é:

ferramentas → sistema → mensagens

Coloque o conteúdo estável primeiro e o conteúdo volátil depois.

Conteúdo estável:

• prompt do sistema;
• definições de ferramentas;
• convenções do repositório;
• instruções fixas.

Conteúdo volátil:

• tarefa do usuário;
• timestamps;
• arquivos recém-lidos;
• logs;
• resultados de ferramentas.

Se você usa um wrapper próprio, defina o cache explicitamente:

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    system=[
        {
            "type": "text",
            "text": SYSTEM_PROMPT + REPO_CONVENTIONS,
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[
        {
            "role": "user",
            "content": user_task,
        }
    ],
)

u = response.usage

print("cache write:", u.cache_creation_input_tokens)
print("cache read :", u.cache_read_input_tokens)
print("fresh input:", u.input_tokens)

Pontos operacionais:

• mantenha o prefixo byte-estável;
• não interpole timestamps no prompt do sistema;
• não altere convenções a cada execução;
• agrupe execuções relacionadas para manter o cache quente.

Um caso comum: um bloco estável de 8.000 tokens usado em 60 invocações por dia. Sem cache, você paga entrada cheia 60 vezes. Com cache, paga a gravação e depois leituras com desconto significativo.

A API da OpenAI também aplica desconto de entrada em cache em modelos suportados, embora os controles sejam diferentes. Para complementar cache com roteamento e limites, veja executando GPT-5.5 gratuitamente através do Codex.

Roteamento de modelos: modelo barato para trabalho barato

Nem toda tarefa precisa do modelo mais caro.

Use modelos menores para:

• mensagens de commit;
• resumos de diff;
• changelog;
• renomeações simples;
• geração de boilerplate;
• explicações curtas de lint;
• revisão superficial.

Reserve modelos fortes para:

• mudanças arquiteturais;
• debugging complexo;
• refatorações com múltiplos módulos;
• raciocínio sobre trade-offs;
• análise de falhas difíceis.

Exemplo na CLI:

# Tarefa simples
claude --model haiku "escreva uma mensagem de commit convencional para o diff staged"

# Tarefa complexa
claude --model sonnet "redesenhe a camada de cache do serviço de pagamentos"

Uma política simples para equipe:

Modelo padrão: barato
Escalar para modelo forte: somente quando a tarefa exigir raciocínio complexo

Muitas equipes fazem o inverso: usam o modelo premium para tudo “por segurança” e acabam pagando caro por mensagens de commit.

Use subagentes com contexto pequeno

Se sua estrutura suporta subagentes, delegue tarefas estreitas para um modelo barato.

Exemplo de padrão:

Agente pai:
- modelo forte
- contexto principal
- decide a estratégia

Subagente:
- modelo barato
- contexto mínimo
- resume logs, procura símbolos, gera rascunhos

O subagente retorna um resultado curto. O modelo caro não precisa ler tudo.

Os padrões em o comando de objetivo entre Codex e Claude Code mostram como estruturar esse tipo de delegação.

Roteamento também ajuda em planos com limite de uso. O aumento do limite semanal do Claude Code ajuda, mas ainda é desperdício gastar modelo premium em tarefas mecânicas.

Aparando saída de ferramentas e recuperação

Saída de ferramenta é um dos maiores desperdícios porque parece invisível. Cada comando executado pelo agente retorna texto. Esse texto entra no contexto e é reenviado depois.

Um único comando pode gerar milhares de linhas:

• npm install;
• testes verbosos;
• git diff com lockfile;
• logs de build;
• stack traces completos.

O agente normalmente precisa apenas de:

• sucesso ou falha;
• mensagem relevante;
• arquivo e linha;
• resumo do diff.

1. Torne comandos silenciosos

# Barulhento
npm test

# Mais econômico
npm test --silent -- --reporter=dot

# Barulhento
npm install

# Mais econômico
npm install --silent --no-audit --no-fund

2. Filtre antes de retornar ao agente

# Retorna apenas o final do erro
pytest -q 2>&1 | tail -n 30

# Estatísticas em vez de diff completo
git diff --stat

# Apenas linhas relevantes
npm test 2>&1 | grep -E "(FAIL|✗|Error)" | head -n 20

3. Evite leitura de arquivo inteiro

Em vez de pedir:

Leia src/payments/retry.ts e corrija a lógica.

Prefira:

Encontre a função que trata retry em src/payments/retry.ts.
Leia apenas essa função e as funções auxiliares diretamente chamadas por ela.
Depois proponha a menor alteração possível.

Em arquivos grandes, isso pode reduzir dezenas de milhares de tokens para algumas centenas.

4. Restrinja recuperação em RAG ou busca de código

Se o agente usa busca sobre docs ou código, limite:

• número de trechos;
• tamanho dos trechos;
• diretórios pesquisados;
• tipos de arquivo;
• profundidade de recuperação.

Melhor:

Retorne no máximo 5 trechos de até 200 tokens cada.
Priorize src/payments e docs/payments.md.

Pior:

Procure em todo o repositório e traga tudo que parecer relacionado.

Medindo e atribuindo custo por execução

Você não consegue otimizar o que não mede. Acompanhe custo por tarefa, não apenas a fatura mensal.

Se você usa API diretamente, capture usage:

u = response.usage

INPUT_RATE  = 3.00 / 1_000_000
OUTPUT_RATE = 15.00 / 1_000_000
CACHE_READ  = 0.30 / 1_000_000
CACHE_WRITE = 3.75 / 1_000_000

cost = (
    u.input_tokens * INPUT_RATE +
    u.output_tokens * OUTPUT_RATE +
    u.cache_read_input_tokens * CACHE_READ +
    u.cache_creation_input_tokens * CACHE_WRITE
)

print(
    f"run cost ≈ ${cost:.4f} "
    f"(in={u.input_tokens} "
    f"out={u.output_tokens} "
    f"cache_read={u.cache_read_input_tokens})"
)

Use taxas atuais do seu provedor. Os valores acima são ilustrativos.

Se você usa CLI, três abordagens funcionam.

1. Use comando de custo da sessão

claude /cost

Rode depois de uma tarefa representativa e registre o número.

2. Separe chaves de API por projeto

Crie uma chave por:

• agente;
• projeto;
• time;
• ambiente.

Assim, o gasto fica atribuível em vez de cair em um total agregado.

3. Envolva a CLI em um script

Exemplo simples:

#!/usr/bin/env bash

TASK_LABEL="$1"
shift

START=$(date -Iseconds)

claude "$@"

END=$(date -Iseconds)

echo "$START,$END,$TASK_LABEL" >> agent-runs.csv

Depois, complemente com contagens de tokens do provedor ou do comando de custo.

Meça tarefas recorrentes:

• custo por refatoração diária;
• custo por revisão de PR;
• custo por geração de teste;
• custo por debugging de API;
• custo por resumo de diff.

Quando você ativa cache, reduz contexto ou roteia modelo, esse número deve cair. Se não cair, a otimização não está atuando onde você pensava.

Comparativo de táticas

Tática	Economia típica de tokens	Esforço
Delimitar o conjunto de trabalho	30–60% na entrada por execução	Baixo
Arquivo de memória curto e estável	5–15% por turno	Baixo
/compact ou /clear entre tarefas	40–80% em sessões longas	Baixo
Cache de prompts em prefixo estável	~90% no prefixo em cache	Médio
Roteamento de modelos	50–80% nas subtarefas roteadas	Médio
Saída de ferramenta silenciosa ou filtrada	20–50% em execuções com muitas ferramentas	Baixo
Leituras direcionadas	70–95% em edições de arquivos grandes	Baixo
Escopo de recuperação restrito	30–60% em agentes com muito RAG	Médio
Medição de custo por execução	0% diretamente; habilita as demais	Baixo

Os intervalos são ilustrativos. Os ganhos se acumulam de forma multiplicativa e dependem do desperdício inicial.

Checklist prático

Use este checklist antes de iniciar uma execução grande:

[ ] Nomeei os arquivos ou diretórios relevantes?
[ ] Removi escopo desnecessário do prompt?
[ ] O CLAUDE.md está curto?
[ ] Estou em uma sessão limpa ou compactada?
[ ] O modelo escolhido é adequado à dificuldade?
[ ] Comandos de teste/build estão silenciosos?
[ ] Logs serão filtrados antes de entrar no contexto?
[ ] Arquivos gerados estão ignorados?
[ ] Vou medir o custo da execução?

Para tarefas recorrentes, transforme isso em política de time.

Conclusão

Custos de tokens em agentes CLI são, em grande parte, custos de contexto mal controlado. O desperdício vem de arquivos demais, histórico demais, logs demais e modelos caros usados para tarefas simples.

Comece pelas ações de baixo esforço:

1. delimite arquivos;
2. reduza CLAUDE.md;
3. use /compact e /clear;
4. silencie comandos;
5. meça custo por execução.

Depois adicione cache de prompts e roteamento de modelos. A qualidade do trabalho não precisa cair. O que precisa cair é o volume de tokens que nunca deveria ter sido enviado.