Erros ANTHROPIC_AUTH_TOKEN no Claude Code: correções completas de configuração

Quando Erros ANTHROPIC_AUTH_TOKEN no Claude Code: correções completas de configuração é a consulta, a correção normalmente começa com uma pergunta: o Claude Code está enviando a credencial no cabeçalho que o seu gateway realmente lê?

Para o roteamento de gateway do Claude Code, ANTHROPIC_AUTH_TOKEN envia Authorization: Bearer .... ANTHROPIC_API_KEY envia x-api-key: .... Um token na variável errada pode parecer uma chave inválida, um login expirado ou um gateway quebrado, mesmo quando o valor em si é válido.

Use este runbook quando o Claude Code falhar depois que você definir ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL, um arquivo de configurações do Claude Code, a extensão do VS Code ou um fluxo de trabalho de CI.

A correção rápida

Comece com o diagnóstico mais simples possível antes de editar todos os arquivos de configuração no seu computador.

1. Escolha uma única variável de credencial.
2. Exporte a URL base do gateway e essa credencial no mesmo shell.
3. Execute uma requisição curl de um único token para $ANTHROPIC_BASE_URL/v1/messages.
4. Inicie o Claude Code a partir desse mesmo shell.
5. Execute /status e confirme se Anthropic base URL e a origem esperada da credencial aparecem.
6. Se o curl funcionar, mas o Claude Code ainda pedir para você fazer login, mova a credencial para um local que o Claude Code leia antes da configuração inicial, como ~/.claude/settings.json, uma exportação no shell ou configurações gerenciadas.

Para um gateway com token bearer:

export ANTHROPIC_BASE_URL="https://llm-gateway.example.com"
export ANTHROPIC_AUTH_TOKEN="REPLACE_WITH_GATEWAY_TOKEN"

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "replace-with-a-gateway-supported-claude-model",
    "max_tokens": 1,
    "messages": [{"role": "user", "content": "."}]
  }'

Para um gateway x-api-key:

export ANTHROPIC_BASE_URL="https://llm-gateway.example.com"
export ANTHROPIC_API_KEY="REPLACE_WITH_GATEWAY_KEY"

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "replace-with-a-gateway-supported-claude-model",
    "max_tokens": 1,
    "messages": [{"role": "user", "content": "."}]
  }'

Uma resposta JSON com um id de mensagem e content significa que a URL e a credencial funcionam. Um 401 significa que o gateway rejeitou a credencial ou a recebeu em um cabeçalho que ele não lê.

Lista de verificação de Erros ANTHROPIC_AUTH_TOKEN no Claude Code: correções completas de configuração

Use esta tabela como o diagnóstico de trabalho. Não faça rotação de chaves até que a variável ativa, o cabeçalho e a precedência das configurações sejam conhecidos.

Escolha ANTHROPIC_AUTH_TOKEN ou ANTHROPIC_API_KEY

ANTHROPIC_AUTH_TOKEN é para um token bearer. O Claude Code o envia como:

Authorization: Bearer <token>

ANTHROPIC_API_KEY é para uma chave de API. O Claude Code a envia como:

x-api-key: <key>

Se a equipe do seu gateway só disser "token" ou "Authorization header", comece com ANTHROPIC_AUTH_TOKEN. Se disserem "API key" ou "x-api-key", use ANTHROPIC_API_KEY. Se você adivinhou e recebeu 401, troque as variáveis antes de rotacionar a chave.

Não configure ambas durante a solução de problemas. É assim que Erros ANTHROPIC_AUTH_TOKEN no Claude Code: correções completas de configuração deixa de ser um problema de autenticação e passa a ser um problema de precedência de autenticação.

Coloque as variáveis onde o Claude Code realmente as lê

Exports do shell são bons para o primeiro teste porque são fáceis de remover:

export ANTHROPIC_BASE_URL="https://llm-gateway.example.com"
export ANTHROPIC_AUTH_TOKEN="REPLACE_WITH_GATEWAY_TOKEN"
claude

Eles se aplicam apenas àquela sessão de terminal e aos programas iniciados a partir dela. Se você abrir o VS Code, um aplicativo de desktop ou um agente em segundo plano de outro lugar, o export pode não estar visível.

Para uma configuração persistente no nível do usuário para a CLI, use ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
    "ANTHROPIC_AUTH_TOKEN": "REPLACE_WITH_GATEWAY_TOKEN"
  }
}

Para um único projeto, use .claude/settings.local.json e certifique-se de que ele esteja no gitignore antes de adicionar uma credencial. Não coloque uma credencial em .claude/settings.json, porque esse arquivo foi feito para ser compartilhado com o repositório.

Quando um export do shell e um bloco env de um arquivo de configuração definem a mesma variável, o Claude Code usa o valor do arquivo de configuração. É por isso que /status é uma fonte de verdade melhor do que echo $ANTHROPIC_AUTH_TOKEN.

Corrija a extensão do VS Code

A extensão do Claude Code para VS Code tem suas próprias verificações de inicialização. Configure as variáveis do gateway nas configurações do usuário do VS Code em claudeCode.environmentVariables:

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://llm-gateway.example.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "REPLACE_WITH_GATEWAY_TOKEN" }
  ]
}

Use o comando do VS Code Preferences: Open User Settings (JSON). Em seguida, reinicie a sessão da extensão e execute /status. Se a extensão ainda solicitar login, ela não está vendo a credencial na própria verificação de login.

Corrija o GitHub Actions

O Claude Code GitHub Actions lê ANTHROPIC_BASE_URL do bloco env do workflow. Para um gateway com x-api-key, passe a chave do gateway como input da action:

env:
  ANTHROPIC_BASE_URL: https://llm-gateway.example.com

steps:
  - uses: anthropics/claude-code-action@v1
    with:
      anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}

Para um gateway com bearer token, a action ainda precisa de anthropic_api_key para satisfazer sua verificação de inicialização, enquanto ANTHROPIC_AUTH_TOKEN é o valor que o Claude Code envia como Authorization: Bearer:

env:
  ANTHROPIC_BASE_URL: https://llm-gateway.example.com
  ANTHROPIC_AUTH_TOKEN: ${{ secrets.GATEWAY_API_KEY }}

steps:
  - uses: anthropics/claude-code-action@v1
    with:
      anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}

Mantenha esses valores nos GitHub Secrets. Não cole credenciais do gateway em logs de workflow, comentários de issues ou arquivos comitados.

Use /status como verificação da verdade

Após qualquer alteração de configuração, execute:

/status

Para um gateway no formato Anthropic, a aba Status deve mostrar:

Anthropic base URL: https://llm-gateway.example.com
Auth token: ANTHROPIC_AUTH_TOKEN

ou:

Anthropic base URL: https://llm-gateway.example.com
API key: ANTHROPIC_API_KEY

Se a linha da base URL estiver ausente, ANTHROPIC_BASE_URL não chegou à sessão. Se a origem da credencial for um login salvo, o Claude Code não está usando a credencial do gateway. Se ambos parecerem corretos e a mensagem ainda falhar, o problema provavelmente está agora no roteamento do gateway, na compatibilidade com o upstream, no comportamento do proxy ou na confiança do certificado.

Observação sobre Flatkey para o roteamento do gateway do Claude Code

O Flatkey é útil em dois fluxos diferentes do Claude Code, e essa distinção importa.

Para chamadas de modelo compatíveis com OpenAI a partir de um projeto ou skill de agente, a base URL do Flatkey é:

https://router.flatkey.ai/v1

Para o próprio caminho de gateway do Claude Code, siga a configuração de gateway no formato Anthropic Messages e não adicione /v1 ao ANTHROPIC_BASE_URL, a menos que as instruções do próprio gateway para Claude Code digam explicitamente para fazer isso. Um padrão típico do provedor é:

export ANTHROPIC_BASE_URL="https://router.flatkey.ai"
export ANTHROPIC_API_KEY="$FLATKEY_API_KEY"

Depois execute /status, envie um prompt curto e verifique o ledger ou os logs do gateway. Mantenha a configuração do Claude Code SKILL.md separada desse caminho: uma skill ensina o Claude Code a chamar modelos e ferramentas compatíveis com Flatkey a partir do seu repositório; o roteamento do gateway controla para onde o Claude Code envia seu próprio tráfego da família Claude.

Se você estiver padronizando o tráfego de agentes entre provedores, combine este artigo com os guias Claude API proxy vs multi-model router e Flatkey API quickstart.

Verificações do operador do gateway quando o token não é o problema real

Algumas pesquisas por Erros ANTHROPIC_AUTH_TOKEN no Claude Code: correções completas de configuração começam como um problema de configuração local e terminam no gateway. Se o curl de um único token autenticar e /status parecer correto, inspecione estas condições do lado do gateway:

Se o seu gateway estiver na frente de um provedor que não aceita a forma completa da requisição Anthropic Messages, use as variáveis específicas do provedor em vez de ANTHROPIC_BASE_URL, ou faça uma ponte do esquema dentro do gateway. Não remova campos às cegas; isso troca um erro visível por uma falha de capacidade posterior.

Registro de depuração copiável

Use este registro ao repassar o problema para um colega ou operador do gateway:

claude_code_auth_debug:
  date_checked: 2026-09-22
  surface: cli # cli | vscode | github_actions | agent_sdk | desktop
  claude_code_version: ""
  expected_gateway_base_url: "https://llm-gateway.example.com"
  variable_used: "ANTHROPIC_AUTH_TOKEN"
  expected_header: "Authorization: Bearer"
  status_tab_base_url_seen: false
  status_tab_credential_source: ""
  curl_status_code: ""
  curl_response_shape: "json_message | 401 | html_200 | dns_error | tls_error | other"
  settings_files_checked:
    - "~/.claude/settings.json"
    - ".claude/settings.local.json"
    - ".claude/settings.json"
  shell_started_claude: false
  saved_login_present: unknown
  gateway_logs_received_request: unknown
  suspected_fix: ""

Esse registro força a investigação a separar três coisas: de onde o Claude Code leu a configuração, qual cabeçalho ele enviou e o que o gateway retornou.

Perguntas frequentes

Devo usar ANTHROPIC_AUTH_TOKEN ou ANTHROPIC_API_KEY?

Use ANTHROPIC_AUTH_TOKEN quando o gateway espera um token bearer ou o cabeçalho Authorization. Use ANTHROPIC_API_KEY quando o gateway espera x-api-key. Se você não souber, comece com ANTHROPIC_AUTH_TOKEN, verifique com a requisição curl e troque se receber 401.

Por que /status não mostra minha base URL?

ANTHROPIC_BASE_URL não chegou ao processo do Claude Code. Inicie claude a partir do mesmo shell, mova o valor para o arquivo de configurações correto ou configure a superfície que você está usando, como as configurações do VS Code ou o env do GitHub Actions.

Por que o curl funciona, mas o Claude Code ainda pede para eu fazer login?

A URL base está acessível, mas o Claude Code não tem uma credencial disponível no ponto em que precisa dela. Coloque ANTHROPIC_AUTH_TOKEN ou a variável de credencial correta em uma exportação de shell, nas configurações do usuário ou em configurações gerenciadas que o Claude Code lê antes da configuração inicial.

Posso colocar o token em .claude/settings.json?

Não coloque segredos em .claude/settings.json porque ele é um arquivo de projeto compartilhado. Use ~/.claude/settings.json, .claude/settings.local.json, configurações gerenciadas, um gerenciador de segredos ou segredos de CI.

ANTHROPIC_AUTH_TOKEN direciona o Claude Code para modelos que não são da Claude?

Não. Ele apenas altera como o Claude Code se autentica no gateway no formato Anthropic configurado. O gateway pode rotear ou intermediar solicitações de acordo com sua própria implementação, mas o Claude Code ainda espera a estrutura da API da Claude no caminho ANTHROPIC_BASE_URL.

Qual é a verificação final mais segura?

Execute a solicitação curl de um token, inicie o Claude Code a partir da superfície configurada, execute /status, envie um prompt curto e confirme que o livro-razão ou os logs do gateway mostram a solicitação. Essa verificação em quatro etapas é a correção duradoura por trás de Erros ANTHROPIC_AUTH_TOKEN no Claude Code: correções completas de configuração.

Fontes verificadas

• Documentação do Anthropic Claude Code: Conectar o Claude Code a um gateway LLM, acessado em 2026-09-22.
• Documentação do Anthropic Claude Code: Arquivos de configuração e precedência, acessado em 2026-09-22.
• Documentação do Anthropic Claude Code: Guia de compatibilidade do gateway do Claude Code, acessado em 2026-09-22.
• Central de Ajuda da Claude: Gerenciar variáveis de ambiente da chave de API no Claude Code, acessado em 2026-09-22.
• SKILL.md público da Flatkey, acessado em 2026-09-22.
• Base de conhecimento da Flatkey: Visão geral do produto, estratégia de marketing, voz da marca.