ANTHROPIC_AUTH_TOKEN vs ANTHROPIC_API_KEY — qual deles o Claude Code realmente lê

Elas não são aliases. Uma se torna `x-api-key`, e a outra se torna `Authorization: Bearer` — quando ambas estão definidas, aquela que você não pretendia usar pode vencer. A maioria dos relatos de “minha chave está correta, mas a autenticação falha” contra uma URL base personalizada se resume a isso.

O erro

as duas variáveis

# Sent as:  x-api-key: <value>
export ANTHROPIC_API_KEY="sk-ant-..."

# Sent as:  Authorization: Bearer <value>
export ANTHROPIC_AUTH_TOKEN="sk-kn-..."

# Where those headers go:
export ANTHROPIC_BASE_URL="https://api.kunavo.com"

Causas e soluções em resumo

Causa	Solução
O gateway espera um token bearer; você definiu a variável da chave de API	A maioria dos gateways compatíveis com OpenAI autentica usando `Authorization: Bearer`. Coloque a chave do gateway em ANTHROPIC_AUTH_TOKEN.
As duas variáveis definidas, de provedores diferentes	Um ANTHROPIC_API_KEY antigo no perfil do shell pode ser enviado junto com o token. Remova a variável que você não está usando.
URL base definida, credenciais não alteradas	Apontar para um novo host não torna válida nesse local a chave de um provedor antigo. A credencial precisa mudar junto com o host.
Variável definida em um shell diferente daquele que executa a ferramenta	Uma exportação em um shell interativo não chega a um processo iniciado pela interface gráfica. Verifique dentro do mesmo ambiente.

Veja o que seu ambiente realmente contém

Verifique as duas, no shell que inicia a ferramenta, antes de alterar qualquer coisa. Uma parcela surpreendente dessas sessões tem ambas definidas — geralmente uma delas vem de uma edição do perfil feita meses atrás e esquecida por todos.

inspect-env.sh

for v in ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN ANTHROPIC_BASE_URL; do
  printf '%-22s %s\n' "$v" "$(printenv "$v" | cut -c1-12)"
done

# Prefixes tell you the provider at a glance:
#   sk-ant-  Anthropic direct
#   sk-kn-   Kunavo

Defina o par correspondente ao seu host e remova o outro

Trate host e credencial como uma única unidade. Contra uma URL base de terceiros, isso normalmente significa o token bearer junto com a URL base, com a chave de API direta explicitamente removida para que não seja selecionada.

third-party.sh

unset ANTHROPIC_API_KEY

export ANTHROPIC_AUTH_TOKEN="sk-kn-..."
export ANTHROPIC_BASE_URL="https://api.kunavo.com"

# On Kunavo, pin served models too: Claude Code's default and its opus and
# sonnet aliases follow Anthropic's newest models, and the sonnet alias asks
# for Sonnet 5.5, which Kunavo does not serve — unpinned, that request 404s.
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"

claude

Confirme na transmissão, não apenas mentalmente

Se a autenticação ainda falhar, elimine o ambiente da equação: faça a solicitação manualmente com o cabeçalho que você acredita estar sendo enviado. Um 200 aqui, acompanhado de uma falha na ferramenta, significa que a ferramenta não está lendo a variável definida — geralmente por estar em outro shell ou por um arquivo de configuração estar sobrescrevendo-a.

verify.sh

curl -s -o /dev/null -w '%{http_code}\n' \
  "$ANTHROPIC_BASE_URL/v1/models" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"

Se você estiver chamando pela Kunavo

A Kunavo lê a chave tanto de `Authorization: Bearer` quanto de `x-api-key`, portanto o cabeçalho não é o fator decisivo. Com o Claude Code, o par que funciona ainda é ANTHROPIC_AUTH_TOKEN mais ANTHROPIC_BASE_URL — o token entra em vigor sem a aprovação única exigida por ANTHROPIC_API_KEY — e ANTHROPIC_API_KEY deve ser removida, em vez de deixada para trás, porque um valor antigo nela é a causa mais comum de uma sessão que parece configurada, mas continua recusando. A mesma chave `sk-kn-` funciona sem alterações como token bearer no estilo OpenAI contra /v1/chat/completions, portanto uma credencial cobre os dois formatos. A configuração completa, incluindo os nomes dos modelos a usar, está em nosso guia de erro 401 do Claude Code.

Perguntas frequentes

Se ambas estiverem definidas, qual vence?

Não confie na resposta — trata-se de uma regra de precedência que mudou entre versões e varia entre SDKs. Defina exatamente uma e remova a outra; essa é a única configuração que se comporta da mesma forma em todos os lugares.

Posso usar ANTHROPIC_AUTH_TOKEN diretamente com a Anthropic?

A própria API da Anthropic autentica usando x-api-key, portanto uma chave direta da Anthropic deve ficar em ANTHROPIC_API_KEY. A variável de token existe para hosts que esperam uma credencial bearer.

O SDK usa as mesmas variáveis?

Os SDKs de Python e TypeScript leem ANTHROPIC_API_KEY e enviam x-api-key. Se você apontar um SDK para um gateway com autenticação bearer, passe a credencial explicitamente em vez de depender do ambiente.

Guias relacionados

Mais detalhes sobre o significado dos erros estão em referência de erros; obter uma chave leva um minuto por meio de cadastro e da guia de autenticação.