Compreendendo a prioridade de autenticação no Claude Code
Ao usar Claude Code, é importante entender como os métodos de autenticação são priorizados para evitar cobranças inesperadas de API e garantir que você esteja usando sua conta pretendida.
Importante: Se você tiver uma variável de ambiente ANTHROPIC_API_KEY definida em seu sistema, Claude Code usará essa chave de API para autenticação em vez de sua assinatura Claude.ai (Pro, Max, Team ou Enterprise), resultando em cobranças de uso de API em vez de usar o uso incluído em sua assinatura.
Como a Autenticação Funciona
Claude Code prioriza chaves de API de variáveis de ambiente sobre assinaturas autenticadas.
Este é um comportamento intencional projetado para lhe dar flexibilidade na escolha do seu método de autenticação.
Quando uma chave de API é definida como uma variável de ambiente, você será cobrado via taxas de pagamento conforme o uso da API usando a conta de API associada a essa chave.
Isso acontece mesmo se você estiver conectado ao Claude Code com uma assinatura claude.ai ou uma conta Console diferente.
Melhores Práticas
Para usar Claude Code com sua assinatura Claude: Mantenha a variável de ambiente ANTHROPIC_API_KEY não definida.
Isso evita cobranças inesperadas de API e garante que você esteja usando o uso incluído em sua assinatura.
Se você precisar usar uma chave de API específica ocasionalmente, defina-a temporariamente apenas quando necessário.
Execute /status no Claude Code periodicamente para verificar seu método de autenticação atual.
Avisos de Conflito de Autenticação
Claude Code o notificará quando houver um conflito entre sua assinatura autenticada e uma chave de API de variável de ambiente:
Durante a configuração inicial, se uma chave de API for detectada em suas variáveis de ambiente, Claude Code pedirá que você confirme qual método de autenticação deseja usar
Após o login bem-sucedido, você verá uma notificação se ambas as credenciais estiverem ativas, alertando-o sobre o potencial de cobranças inesperadas de API
Verificando Sua Configuração Atual
Para verificar se uma chave de API está definida como uma variável de ambiente, execute /status no Claude Code. Isso mostrará qual método de autenticação está ativo no momento.
Para verificar sua variável de ambiente diretamente, execute um destes comandos em um terminal (fora do Claude Code):
macOS/Linux:
echo $ANTHROPIC_API_KEY
Windows CMD:
echo %ANTHROPIC_API_KEY%
Windows PowerShell:
echo $env:ANTHROPIC_API_KEY
Definindo uma Chave de API Temporariamente
Se você precisar usar uma chave de API apenas para a sessão de terminal atual:
macOS/Linux:
export ANTHROPIC_API_KEY='your-api-key-here'
Windows CMD:
set ANTHROPIC_API_KEY=your-api-key-here
Windows PowerShell:
$env:ANTHROPIC_API_KEY="your-api-key-here"
Definindo uma Variável de Ambiente de Chave de API Permanentemente
macOS/Linux:
Para zsh (padrão no macOS):
bash
# Adicionar ao arquivo de configuração do shell
echo 'export ANTHROPIC_API_KEY="your-api-key-here"' >> ~/.zshrc
# Aplicar alterações
source ~/.zshrc
Para bash:
bash
# Adicionar ao arquivo de configuração do shell
echo 'export ANTHROPIC_API_KEY="your-api-key-here"' >> ~/.bash_profile
# Aplicar alterações
source ~/.bash_profile
Windows:
Abra Propriedades do Sistema → Avançado → Variáveis de Ambiente
Em "Variáveis do usuário", clique em "Novo"
Nome da variável: ANTHROPIC_API_KEY
Valor da variável: your-api-key-here
Clique em OK e reinicie seu terminal
Removendo uma Variável de Ambiente de Chave de API
macOS/Linux (temporário):
unset ANTHROPIC_API_KEY
macOS (permanente):
# Remover do arquivo de configuração
sed -i '' '/ANTHROPIC_API_KEY/d' ~/.zshrc
source ~/.zshrc
Linux (permanente)
sed -i '/ANTHROPIC_API_KEY/d' ~/.zshrc
Windows CMD:
set ANTHROPIC_API_KEY=
Windows PowerShell:
Remove-Item Env:ANTHROPIC_API_KEY
Windows (permanente): Delete a variável das configurações de Variáveis de Ambiente do Sistema.
Problemas Comuns a Evitar
Definir variáveis de ambiente em arquivos de configuração do shell e esquecer delas.
Não reiniciar seu terminal após alterar variáveis de ambiente.
Assumir que você está usando sua assinatura quando uma chave de API está configurada em seu ambiente.
Se você tiver alguma dúvida, entre em contato com nossa equipe de Suporte ao Produto.