Claude Agent SDK: consumo do limite de cinco horas
Compare o consumo do limite de cinco horas em aplicativos do Claude Agent SDK, no claude -p e no Claude Code interativo. Confira os identificadores de cliente e os eventos de uso, avalie as limitações das alternativas da comunidade e migre automações para cobrança pela API ou créditos elegíveis dos planos Max e Team.
Conteúdo
Se aplicativos do Claude Agent SDK ou claude -p esgotam sua cota de cinco horas cedo, compare a mesma tarefa no Claude Code interativo. Testes da comunidade indicam consumo aproximadamente 1.6×–2.97× mais rápido, sem estabelecer um multiplicador universal. Para automações recorrentes, a cobrança documentada pela API oferece um saldo separado e custos mensuráveis por token.
Em 2026-10-27, a issue #97074 da Anthropic continua aberta. Os relatos apresentam evidências de diferenças no consumo entre os entrypoints dos clientes. Eles não esclarecem se a Anthropic pretende aplicar essa diferença ou a considera um defeito.
O que os testes controlados mediram
Vários autores relataram um aumento maior no consumo da cota de cinco horas para trabalho comparável com claude -p ou aplicativos do Agent SDK. São experimentos separados, com versões, modelos, combinações de tokens e clientes de comparação diferentes.
| Relato | Condições do teste | Resultado relatado |
|---|---|---|
| qvarker, 25 de setembro | Max; Claude Code 2.1.282; claude-opus-5; esforço alto | Consumo da cota cerca de 1.8× mais rápido no modo sem interação, ou headless, que no terminal interativo |
| kler, 17 de outubro | Team; Claude Code 2.1.300; claude-opus-5-5; esforço alto | sdk-ts: 2.97×; sdk-cli: 2.83×, em comparação com um programa de teste que usava o identificador claude-vscode |
| Relato de Theo sobre o T3 Code, 25 de outubro | Uma conta Max; carga de trabalho equivalente; terminal interativo, T3 Code e claude -p | Consumo pelos caminhos SDK/headless equivalente a aproximadamente 1.6×–1.7× o do terminal interativo, após a comparação de cache apresentada no relato |
| frostfire575, 26 de outubro | Windows 11; Claude Code 2.1.310; claude-opus-5-5; esforço baixo | Consumo de aproximadamente 2.4× a cota por token ponderado com claude -p, em comparação com o terminal interativo |
O maior resultado exige uma ressalva: o programa de teste de kler emulou o identificador da extensão do VS Code. Ele não operou a interface da extensão real. O resultado isola uma diferença associada ao identificador naquele experimento.
Os valores em dólares do relato de qvarker são estimativas equivalentes ao custo da API, usadas para normalizar o trabalho. Eles não representam cobranças adicionais na assinatura. Um valor menor de “dólares de trabalho por 1%” indica que a cota acabou mais rápido.
A cota semanal precisa de uma análise separada. Theo registrou o mesmo aumento semanal de dois pontos percentuais em cada execução. O medidor semanal de frostfire575 passou apenas de 0% para 1%, uma resolução insuficiente para concluir algo. As evidências sustentam consumo semanal igual no experimento de Theo, sem garantir esse comportamento para todas as contas.
O que sdk-cli e sdk-ts realmente demonstram
O entrypoint identifica o cliente que faz a chamada; sua presença não revela a fórmula de contabilização nos servidores da Anthropic.
O pacote publicado @anthropic-ai/claude-agent-sdk 0.3.311 contém este valor padrão em sdk.mjs:
if(!c.CLAUDE_CODE_ENTRYPOINT)c.CLAUDE_CODE_ENTRYPOINT="sdk-ts"Portanto, o SDK define sdk-ts quando essa variável de ambiente não tem valor. Registros de sessão compartilhados pela comunidade mostram sdk-cli para execuções comuns de claude -p e cli para o terminal interativo.
Na comparação de tráfego de qvarker, as requisições diferiam em cc_entrypoint dentro do bloco de sistema x-anthropic-billing-header. O autor também observou diferenças no User-Agent e em uma flag beta.
Essa é uma observação da comunidade sobre o conteúdo das requisições. Ela não estabelece uma interface de cabeçalho de cobrança oficialmente documentada, nem prova que um campo explica todas as diferenças.
O changelog do Claude Code 2.1.311 não anuncia uma correção para essa discrepância no consumo. Essa ausência não permite concluir se o comportamento nos servidores mudou.
Como verificar seu próprio fluxo de trabalho
Meça o cliente real, a forma de autenticação e a carga de trabalho antes de mudar a configuração.
Confirme a autenticação e as condições de comparação
Confira o ambiente usado pelo processo do Claude iniciado pelo aplicativo. Uma chave de API pode ter precedência sobre a autenticação da assinatura no modo -p, conforme a referência de autenticação.
Registre o executável, as versões da CLI e do pacote SDK, o plano da conta, o ID exato do modelo e o nível de esforço. Uma interface pode iniciar um binário diferente daquele disponível no seu terminal.
Para comparar:
- Use a mesma conta, a mesma cópia do projeto, a mesma lista de prompts, as mesmas ferramentas e configurações de cache.
- Pause outras atividades nessa conta.
- Inicie sessões novas e mantenha as duas execuções dentro da mesma janela de cinco horas.
- Interrompa a comparação se a janela reiniciar ou o consumo passar para uso extra pago.
Use uma tarefa representativa, como resumir os mesmos arquivos de código. Mantenha separados os totais de entrada, saída, leitura de cache e gravação de cache. Saídas do mesmo tamanho, por si só, não demonstram trabalho equivalente.
Capture o medidor e o entrypoint registrado
Preserve o conteúdo completo dos dados de limite de uso, pois os campos disponíveis variam entre versões.
O teste abaixo usa Bash, exige jq e pressupõe uma sessão autenticada pela assinatura. Ele consome a cota. O teste verifica telemetria e autenticação; a resposta de uma palavra não mede um multiplicador.
set -o pipefail
claude --version
claude auth status | jq '{authMethod}'
claude -p "Reply with exactly OK." \
--model claude-sonnet-5-5 \
--max-turns 1 \
--disallowedTools "*" \
--output-format stream-json --verbose |
jq -c '
if .type == "rate_limit_event" then
{type, session_id, rate_limit_info}
elif .type == "result" then
{type, subtype, is_error, session_id,
usage, modelUsage, total_cost_usd, result}
else empty end
'A referência da CLI documenta essas flags e o comando de status da autenticação. Uma resposta bem-sucedida deve incluir um registro result com subtype: "success" e is_error: false.
As versões instrumentadas usadas na issue acessavam este caminho:
rate_limit_event.rate_limit_info.unifiedWindows.five_hour.utilization
Porém, unifiedWindows não aparece no tipo público de evento do SDK 0.3.311. Esse tipo declara campos como rateLimitType e utilization. Não interprete a ausência de um campo ou evento como consumo zero. Consulte a página Usage da conta quando o fluxo não fornecer uma leitura utilizável.
Use medições da mesma interface e na mesma escala. A utilização informada pelos eventos e a resposta separada de controle de uso do SDK seguem esquemas diferentes. Seus números não são intercambiáveis.
Use o session_id retornado para localizar o registro da sessão. A documentação de sessões indica o caminho ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl. Uma configuração personalizada de CLAUDE_CONFIG_DIR altera esse diretório raiz.
Confira apenas o entrypoint registrado com Bash:
read -r -p "Transcript path: " CLAUDE_TRANSCRIPT
jq -r 'select(.entrypoint? | type == "string") | .entrypoint' \
"$CLAUDE_TRANSCRIPT" | sort -uUm resultado vazio significa que o campo não estava disponível. Isso não identifica a sessão como interativa.
Para a comparação pelo terminal, inicie o Claude Code interativo real em um shell limpo. qvarker relatou que um servidor tmux herdou CLAUDE_CODE_ENTRYPOINT e o repassou para sessões posteriores do terminal. Confira o registro resultante, sem presumir que a interface determina o identificador.
Compare o consumo por unidade de trabalho
Compare pontos percentuais por unidade equivalente de trabalho, em vez de minutos gastos ou quantidade de prompts.
Frostfire575 relatou 1.43 milhão de tokens ponderados para um aumento de cinco pontos no terminal. A execução headless usou 1.32 milhão de tokens ponderados para um aumento de onze pontos. Com os valores relatados:
Headless / terminal = (11 / 1.32) / (5 / 1.43) = 2.38
Esse cálculo explica o resultado de 2.4×. Ele usa a medida de tokens ponderados definida pelo autor e vale apenas para aquela comparação.
Variações de um ponto têm resolução insuficiente para uma comparação útil entre execuções pequenas. Se necessário, repita o trabalho normal na ordem inversa. Evite reinícios da janela e outras atividades simultâneas na conta.
Use os resultados finais de sessões novas para estimar custos. Não some registros cumulativos de resultado de sessões retomadas. A documentação de acompanhamento de custos distingue a contabilização de tokens da cobrança real. Nem total_cost_usd nem modelUsage medem a cota da assinatura.
Se a diferença desaparecer ao igualar o comportamento do cache ou eliminar atividades simultâneas, investigue essas causas primeiro.
Vale a pena mudar CLAUDE_CODE_ENTRYPOINT?
Trate a troca do identificador do cliente como um experimento sem suporte oficial.
Em 26 de outubro, qvarker e oviano relataram consumo menor ao usar os nomes das próprias ferramentas. Nessas comparações, o consumo com o identificador padrão sdk-cli correspondeu a aproximadamente 1.9×–2.4× o consumo com um identificador próprio.
Esses relatos não estabelecem uma forma aprovada de obter uma cota diferente. Um identificador personalizado altera a atribuição do cliente, que parece ser relevante para a contabilização. Seu tratamento pode mudar, e sua situação perante as políticas continua indefinida.
Não identifique seu aplicativo como cli ou claude-vscode para receber o tratamento de outro cliente. Esses nomes identificam clientes diferentes.
O pull request #25597 do T3 Code, associado a essa alternativa, estava aberto e sem merge na verificação de 2026-10-27. Sua existência não demonstra que o T3 Code lançou uma correção nem que a Anthropic aprovou a mudança.
Para trabalho interativo, teste o cliente real do terminal. Para automações que precisam manter entrada e saída estruturadas, avalie a cobrança pela API.
Qual saldo paga pela automação com o Agent SDK?
A autenticação determina se uma tarefa consome a cota da assinatura ou créditos de API.
A atualização de cobrança de 7 de outubro da Anthropic mantém o uso da assinatura para Agent SDK, claude -p e aplicativos de terceiros. Ela também permite usar créditos de API elegíveis dos planos Max e Team em tarefas do SDK e de claude -p executadas diretamente por você. Essas tarefas precisam se autenticar com uma chave de API da organização vinculada no Console.
Mantenha estes saldos separados:
| Forma de cobrança | O que a tarefa consome |
|---|---|
| Login pela assinatura Claude | Cotas da assinatura, incluindo a janela de cinco horas |
| Uso extra ativado, também chamado de usage credits | Continuação paga separadamente após o fim da cota incluída |
| Chave de API da Anthropic | Créditos de API elegíveis ou saldo pago de API da organização no Console |
| Gateway de API independente | Saldo e regras de cobrança desse provedor |
A cobrança pela API elimina a dependência da cota de cinco horas da assinatura para essa tarefa. Os limites de taxa e de gastos da API e o saldo disponível continuam valendo.
Em 2026-10-27, o programa mensal de créditos de API informa:
| Plano elegível | Crédito mensal de API |
|---|---|
| Max 5x | $100 USD |
| Max 20x | $200 USD |
| Team Standard | $20 USD por licença |
| Team Premium | $100 USD por licença |
Os créditos do Team formam um saldo compartilhado com teto de $500 USD. O Pro não é elegível. Novos assinantes precisam permanecer sete dias em um plano elegível.
Para ativar os créditos, abra Settings > Billing no Max ou Organization settings > Billing no Team. Selecione Link organization na seção de créditos de API. Você precisa da função exigida de assinante ou proprietário e das permissões de cobrança no Console. Crie a chave de API nessa organização vinculada.
O programa exclui o Claude Code interativo, o uso extra e as execuções iniciadas pelo Claude Code GitHub Action, por extensões de IDE ou pelo aplicativo Claude para desktop. Adicionar -p não elimina essas exclusões.
A documentação de créditos da Platform explica que os créditos não usados expiram, sem transferência para o período seguinte. Os créditos incluídos são consumidos antes dos créditos comprados. Após o esgotamento, o saldo comprado ou o faturamento aplicável podem manter o serviço; caso contrário, as requisições param. Elas não passam automaticamente a consumir a cota da assinatura.
Faça um teste com cobrança pela API antes de migrar tarefas recorrentes
Verifique uma execução direta com chave de API e seu registro de uso no Console antes de migrar uma fila de tarefas.
Use um terminal Bash configurado para acessar diretamente a Anthropic. Confira primeiro ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN e as configurações de provedores de nuvem existentes. Elas podem selecionar outro endpoint ou outra fonte de credenciais.
Crie uma chave de API na organização desejada do Console. Digite-a sem exibi-la no terminal:
read -rs ANTHROPIC_API_KEY && export ANTHROPIC_API_KEY
claude --bare -p \
--model claude-sonnet-5-5 \
--tools "" \
--max-turns 1 \
--max-budget-usd 1.00 \
--output-format json \
"Reply with exactly OK."A documentação de uso programático informa que --bare ignora as credenciais OAuth da assinatura e as personalizações descobertas automaticamente. Por isso, ele serve para esse teste da API. Em uma comparação de consumo da assinatura, esse modo alteraria a forma de autenticação.
O resultado esperado é um JSON bem-sucedido contendo a resposta. Em seguida, confira o uso e o saldo da organização correta no Console. A estimativa de custo da CLI, sozinha, não prova que créditos promocionais pagaram pela requisição.
Se a autenticação falhar, confira a chave e o provedor ativo. Se o saldo acabar, consulte a cobrança no Console. Erros de limite de taxa ou de gastos da API exigem verificar esses limites, mesmo quando resta cota na assinatura.
O orçamento de $1.00 da CLI é um limite estimado para interromper a execução. Uma requisição pode ultrapassá-lo. Portanto, configure também um limite de gastos adequado no Console.
Como exemplo de orçamento, a tabela atual de preços da Anthropic lista claude-sonnet-5-5 a $2 por milhão de tokens de entrada sem cache e $10 por milhão de tokens de saída. Em 2026-10-27, um milhão de tokens de entrada mais 100,000 tokens de saída resulta nesta estimativa de cobrança por tokens:
(1 × $2) + (0.1 × $10) = $3
A estimativa pressupõe roteamento global síncrono padrão, sem uso de cache e sem ferramentas de servidor cobradas separadamente. Ela não inclui impostos aplicáveis. Para contextos repetidos, calcule gravações e leituras de cache com suas tarifas específicas.
Um gateway independente oferece outro caminho. O catálogo atual da BetterToken listava claude-sonnet-5-5 e claude-opus-5-5 em 2026-10-27. Seu guia para Claude Code usa sua própria chave BetterToken e a URL base https://bettertoken.ai, sem /v1. Compare os preços atuais e a compatibilidade necessária com as ferramentas considerando sua carga de trabalho. Os créditos de API incluídos pela Anthropic não são transferidos para essa forma de cobrança separada.
