Chave de API do Claude Code — onde obtê-la, onde colocá-la e por que a variável errada falha silenciosamente

O Claude Code pode autenticar-se de duas maneiras diferentes, e a opção necessária determina todo o restante. Um login de assinatura do claude.ai cobre o uso dentro do seu plano Pro ou Max. Uma chave de API cobra por token, sem limites do plano. Este guia explica onde obter uma chave, exatamente onde colocá-la, as duas variáveis de credenciais e por que escolher a errada causa uma falha silenciosa, além de como manter os custos sob controle depois que tudo funcionar.

Você precisa mesmo de uma chave?

Vale saber antes de começar: definir uma chave pausa sua assinatura. Enquanto uma variável de credencial estiver ativa, o Claude Code a usará no lugar de um login salvo do claude.ai, os limites do plano deixarão de se aplicar e o uso será cobrado do proprietário da chave. Remova a variável e o Claude Code voltará à assinatura.

Opção 1 — uma chave Anthropic própria

1. Faça login em console.anthropic.com (uma conta separada da do claude.ai).
2. Adicione crédito em Billing. A API é pré-paga e separada de qualquer assinatura — um plano Pro não a financia.
3. Crie uma chave em API Keys. Ela começa com sk-ant- e é exibida uma única vez.

export ANTHROPIC_API_KEY=sk-ant-...
# Then approve it once, interactively:
#   /config  ->  Use custom API key
claude

Observe a segunda etapa nesse trecho. ANTHROPIC_API_KEY é enviado no cabeçalho x-api-key e exige uma aprovação interativa única antes que o Claude Code possa usá-lo. Se esse aviso tiver sido recusado alguma vez, a chave será ignorada depois sem nenhum aviso — exatamente como se a variável não estivesse sendo lida. Reative-a em /config → Use custom API key.

Opção 2 — uma chave que custa menos por token

O Claude Code lê ANTHROPIC_BASE_URL nativamente, portanto funciona com qualquer endpoint que ofereça a Anthropic Messages API — sem plugin, proxy ou binário modificado. Esse é o caminho compatível para gateways e permite executar os mesmos modelos Claude por uma tarifa menor:

export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

ANTHROPIC_BASE_URL é apenas a origem — o Claude Code acrescenta /v1/messages por conta própria. Mantenha as linhas de modelo: o padrão integrado ao Claude Code e seu alias opus apontam para o Opus mais recente e, se a Kunavo ainda não oferecer esse modelo, a primeira solicitação retornará 404. A linha opus o fixa em Claude Opus 5.5, que exige o Claude Code v2.1.280 ou posterior (execute claude update em uma versão mais antiga). O alias sonnet solicita o Sonnet 5.5, que a Kunavo não oferece; portanto, sem ANTHROPIC_DEFAULT_SONNET_MODEL, /model sonnet, a fase de execução de opusplan e os subagentes definidos como sonnet retornarão 404. Crie a chave sk-kn- no painel depois de se cadastrar e recarregar US$ 10. Não há mensalidade e o saldo não expira.

Isso representa cerca de 30% abaixo do preço de tabela no modelo principal. As tarifas completas estão no guia de preços da Claude API, e os preços do Claude Code comparam este caminho às tarifas dos planos Pro e Max; a configuração completa, incluindo o roteamento de modelos por tarefa e o que muda atrás de um gateway, está no guia do roteador do Claude Code. Se a CLI ainda não estiver instalada, comece por instalar o Claude Code.

Para onde a chave realmente vai

Duas variáveis, dois cabeçalhos HTTP diferentes. Uma chave no cabeçalho que o servidor não lê falha com 401:

Se você não souber qual tipo possui, comece com ANTHROPIC_AUTH_TOKEN, que não exige uma etapa de aprovação. No Kunavo, qualquer uma das variáveis também permite que o Claude Code descubra a lista de modelos, pois /v1/models lê a chave de qualquer um dos dois cabeçalhos.

Exportação do shell versus arquivo de configurações

Uma exportação do shell aplica-se somente a esse terminal e aos seus processos filhos. Um editor iniciado pelo dock não a verá, nem os agentes em segundo plano. Para algo permanente, use o bloco env de ~/.claude/settings.json — as mesmas chaves, aplicadas onde quer que o Claude Code seja executado. Não coloque uma chave no .claude/settings.json de um projeto; esse arquivo é versionado e compartilhado com todos que clonarem o repositório.

Execute /status para confirmar qual credencial está ativa. Uma linha Auth token ou API key que nomeie sua variável significa que a chave está ativa; uma linha Login method que nomeie uma conta do claude.ai significa que ela não está.

Rotacionando chaves sem editar arquivos

Se a credencial expirar conforme uma programação ou vier de um cofre, aponte apiKeyHelper para um comando que imprima a atual:

#!/bin/bash
# Any command that prints the current key to stdout works.
vault kv get -field=api_key secret/claude-code

Faça referência a ela como "apiKeyHelper": "~/bin/get-key.sh" no arquivo de configurações. O Claude Code armazena a saída em cache por cinco minutos e a executa novamente em um 401; ajuste com CLAUDE_CODE_API_KEY_HELPER_TTL_MS. O valor é enviado nos dois cabeçalhos, portanto funciona de qualquer maneira.

Mantendo a cobrança previsível

A programação agêntica consome muitos tokens — cada etapa reenvia o prompt do sistema, o histórico da tarefa e o contexto atualizado dos arquivos. Quatro coisas importam mais do que qualquer outra:

1. Mantenha a linha do Haiku. Sem ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5, o alias haiku do Claude Code solicita um ID de modelo que a Kunavo não oferece (Haiku 5.5 a partir da v2.1.293), então /model haiku e os subagentes configurados com haiku retornam 404. Essa mesma linha direciona para fora do modelo principal os resumos e títulos que o Claude Code gera automaticamente, gerando uma economia que aumenta quando o trabalho se distribui entre vários processos, conforme os preços detalhados em quanto custa um fluxo de trabalho do Claude Code.
2. As mesmas duas variáveis roteiam o Agent SDK. Ele não tem uma opção de URL base própria — inicia esta CLI e repassa diretamente seu ambiente, portanto um programa do Agent SDK é roteado exatamente pela configuração acima.
3. Comece novas tarefas em vez de prolongar uma indefinidamente. O contexto é reenviado a cada etapa, portanto uma sessão longa tem custo quadrático. A escolha da camada para o modelo principal é analisada em Opus vs Sonnet vs Haiku, considerando o custo por tarefa concluída, e não o custo por token.
4. Deixe o armazenamento em cache de prompts funcionar. A entrada em cache é cobrada a 10% da tarifa de entrada, e a rota nativa da Messages API repassa cache_control sem tradução (detalhes).
5. Dê ao editor sua própria chave com um limite de gastos no painel e verifique o uso depois de uma semana. Limites por chave transformam um loop descontrolado em um loop limitado.

Solução de problemas

Perguntas frequentes