Claude Code settings.json e variáveis de ambiente: URL base, token de autenticação e modelo

O Claude Code obtém sua configuração de arquivos JSON de configurações e de variáveis de ambiente. Para executá-lo por meio de um gateway, em vez da API da Anthropic, você precisa de duas variáveis, ANTHROPIC_BASE_URL e um token, e geralmente de um modelo. As variáveis são simples. O que costuma confundir é onde defini-las, pois a mesma variável pode estar no perfil do shell, em vários arquivos settings.json e nas configurações do VS Code.

Este guia começa com uma configuração funcional e, em seguida, explica onde ficam os arquivos, qual valor prevalece e quais erros você provavelmente verá. O conteúdo foi verificado com base na documentação da Anthropic e testado com o AIHubMix no Claude Code 2.1.304, em 20 de outubro de 2026. Os exemplos usam o AIHubMix como gateway; qualquer endpoint compatível com a Anthropic é configurado da mesma forma.

Resumo

• Seu arquivo pessoal de configurações é ~/.claude/settings.json, ou %USERPROFILE%\.claude\settings.json no Windows.
• Para usar um gateway, inclua ANTHROPIC_BASE_URL (sem /v1) e ANTHROPIC_AUTH_TOKEN no bloco env desse arquivo.
• Um valor no bloco env de um arquivo de configurações substitui o valor da mesma variável exportada no shell.
• Depois que um token é definido, as solicitações deixam de usar sua assinatura Claude e passam a ser cobradas pelo gateway.
• A extensão do VS Code precisa das mesmas variáveis na própria configuração claudeCode.environmentVariables.

Uma configuração funcional do AIHubMix

1. Crie uma chave no console do AIHubMix.
2. Coloque isto em ~/.claude/settings.json. Crie o arquivo se ele ainda não existir.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "env": {
    "ANTHROPIC_BASE_URL": "https://aihubmix.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-aihubmix-key"
  },
  "model": "claude-sonnet-5-5"
}

3. Faça um teste rápido:

claude -p "1+1, output only the answer"

4. Inicie claude em um projeto. O cabeçalho sob o logotipo deve exibir algo como Sonnet 5.5 · API Usage Billing, e /status mostra seu gateway na linha Anthropic base URL.

Dois detalhes são importantes. A URL base é o endereço raiz: o Claude Code acrescenta /v1/messages por conta própria, então uma URL que termina em /v1 interrompe todas as solicitações. Além disso, o AIHubMix usa os próprios IDs de modelo da Anthropic, como claude-sonnet-5-5, então os atalhos sonnet, opus e haiku funcionam sem configuração adicional.

A linha $schema é opcional. Ela permite que o VS Code, o Cursor e outros editores sinalizem erros no arquivo enquanto você digita.

Você também pode exportar as mesmas duas variáveis no shell, mas é melhor defini-las no arquivo de configurações: todos os terminais, as extensões de IDE e os agentes em segundo plano o leem.

Onde ficam os arquivos de configurações

Nunca coloque um token em .claude/settings.json do projeto, pois esse arquivo é enviado ao git. Use seu arquivo de usuário ou .claude/settings.local.json.

Os arquivos de configurações precisam ser JSON válido. Um comentário // ou uma vírgula final faz o Claude Code ignorar o arquivo inteiro, inclusive o token, e você verá a tela de login em vez do gateway.

Não confunda esses arquivos com ~/.claude.json, um arquivo único na sua pasta pessoal. Esse arquivo armazena o estado do próprio Claude Code, como seu login e os servidores MCP, e raramente é necessário editá-lo.

Qual valor prevalece

Quando vários arquivos definem a mesma configuração, aplica-se a precedência das configurações da Anthropic, da maior para a menor:

1. Configurações gerenciadas pela sua organização
2. --settings na linha de comando, somente para a sessão atual
3. .claude/settings.local.json
4. .claude/settings.json
5. ~/.claude/settings.json

Para variáveis de ambiente, há mais uma regra: uma variável no bloco env de um arquivo de configurações substitui a mesma variável definida no shell. Portanto, um export ANTHROPIC_BASE_URL=... em ~/.zshrc não tem efeito enquanto um arquivo de configurações também definir essa variável. As ferramentas para alternar provedores geralmente gravam em ~/.claude/settings.json, e por isso prevalecem sobre o shell.

No Claude Code, /status lista os arquivos carregados na linha Setting sources.

ANTHROPIC_AUTH_TOKEN ou ANTHROPIC_API_KEY

Use a variável que seu gateway lê. O AIHubMix aceita ambas, e o guia do AIHubMix para Claude Code usa ANTHROPIC_AUTH_TOKEN, que também é a opção mais simples. Não deixe ambas definidas. Nesse caso, o Claude Code envia os dois cabeçalhos, e o AIHubMix verifica x-api-key primeiro: em nosso teste, um token correto em settings.json ainda recebeu um erro 401 porque uma variável ANTHROPIC_API_KEY antiga estava exportada no shell. O bloco env só substitui as variáveis que define, então remova a chave antiga do perfil do shell ao trocar.

E quanto à sua assinatura Claude? De acordo com o guia de gateways da Anthropic, quando uma variável de token ou chave de API é definida, as solicitações a usam em vez do seu login no claude.ai, e o gateway cobra por token. Seu login continua salvo e volta a ser usado quando você remove a variável. Definir apenas ANTHROPIC_BASE_URL, sem token, mantém o uso da sua assinatura.

Escolha do modelo

A página de configuração de modelos da Anthropic apresenta esta ordem, da maior para a menor prioridade:

1. /model <name> durante uma sessão
2. claude --model <name> na inicialização
3. A variável ANTHROPIC_MODEL
4. A chave model em um arquivo de configurações

/model salva sua escolha como o novo padrão. Porém, se ANTHROPIC_MODEL estiver definida, todas as novas sessões serão iniciadas novamente com esse modelo. Se você alterna modelos com frequência, defina a chave model e não inclua ANTHROPIC_MODEL. Se nenhum modelo estiver definido, o Claude Code usa Opus 5.5.

ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL e ANTHROPIC_DEFAULT_HAIKU_MODEL alteram o modelo usado por cada atalho. Você só precisa delas se quiser apontar um atalho para outro modelo, por exemplo, para manter sonnet em uma versão mais antiga.

O AIHubMix também disponibiliza modelos de outros fornecedores no mesmo endereço, mas a Anthropic não oferece suporte ao Claude Code com modelos que não sejam Claude, então alguns recursos podem não funcionar com eles.

Quando as alterações entram em vigor

O Claude Code monitora seus arquivos de configurações, e a maioria das alterações salvas, inclusive no bloco env, aplica-se à sessão em andamento. A chave model, as variáveis removidas e as exportações do shell exigem uma reinicialização. Na dúvida, reinicie o Claude Code.

A extensão do VS Code

A extensão lê os mesmos arquivos de configurações, mas verifica se há um login antes de iniciar, usando sua própria configuração claudeCode.environmentVariables. Por isso, o VS Code pode pedir que você entre na conta enquanto a CLI funciona. Abra Preferences: Open User Settings (JSON) na Paleta de Comandos e adicione:

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://aihubmix.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-your-aihubmix-key" }
  ]
}

Em seguida, execute Developer: Reload Window. Há mais opções na documentação do VS Code da Anthropic. O aplicativo Claude Desktop é separado: ele não lê nem settings.json nem essas variáveis.

Outras variáveis úteis

Todas podem ser incluídas no bloco env. A lista completa está na referência de variáveis de ambiente da Anthropic.

Erros comuns e o que significam

Not logged in · Please run /login, ou a tela de login na primeira inicialização
O Claude Code não encontrou nenhum token. Verifique três coisas: um erro no JSON que fez com que o arquivo fosse ignorado, a ausência de ANTHROPIC_AUTH_TOKEN ou um token definido apenas em um arquivo do projeto. A etapa de login ocorre antes do carregamento das configurações do projeto, então mova o token para ~/.claude/settings.json.

Invalid or malformed JSON
O arquivo indicado na mensagem contém um comentário, uma vírgula final ou outro erro de sintaxe, e nenhuma das configurações dele foi aplicada.

There's an issue with the selected model (...)
O ID do modelo está incorreto, ou a URL base termina em /v1 e a solicitação foi enviada para /v1/v1/messages. Se o ID do modelo parecer correto, verifique primeiro a URL.

API Error: 400 com This model ID is incorrect
O AIHubMix não tem um modelo com esse ID, e a mensagem repete o ID que recebeu. Geralmente, é um erro de digitação. Copie novamente o ID da lista de modelos do AIHubMix.

Failed to authenticate. API Error: 401 invalid key: ...
O AIHubMix não aceita a chave. A mensagem termina com os últimos seis caracteres da chave recebida, então compare-os com o final do seu token. PI_KEY significa que o espaço reservado AIHUBMIX_API_KEY foi colado no lugar de uma chave verdadeira. Qualquer outra coisa geralmente indica que uma variável ANTHROPIC_API_KEY antiga do shell foi enviada. Se, em vez disso, a mensagem disser this key is not enabled, verifique no console do AIHubMix se a chave está ativada e tem crédito.

auth may not work as expected
Uma variável de token e um login salvo no claude.ai estão ativos ao mesmo tempo. Execute /logout para continuar usando o gateway ou remova a variável para voltar à sua assinatura.

Claude Code doesn't recognize the model ...
É um aviso, não um erro: a solicitação ainda é enviada, mas o Claude Code presume uma janela de contexto de 200K tokens. Se o ID corresponder a um modelo Claude mais recente, claude update resolve o problema.

Parece travar quando a chave é inválida
O Claude Code tenta novamente solicitações com falha até 10 vezes. Em um teste com uma chave que sempre falhava, claude -p continuou tentando por cerca de três minutos. Reduza CLAUDE_CODE_MAX_RETRIES para ver o erro mais cedo.

Se você quiser usar uma única chave para o Claude no Claude Code e para OpenAI, Google e outros fornecedores nas demais ferramentas, o AIHubMix disponibiliza a API da Anthropic em https://aihubmix.com. O arquivo de configurações acima é tudo de que o Claude Code precisa.

Perguntas frequentes

Onde fica o settings.json do Claude Code?
Seu arquivo pessoal é ~/.claude/settings.json, ou %USERPROFILE%.claude\settings.json no Windows. Um projeto também pode ter .claude/settings.json, compartilhado via git, e .claude/settings.local.json, que é só seu. O Claude Code não cria esses arquivos durante a instalação.

settings.json substitui as variáveis de ambiente?
Sim. Um valor no bloco env de um arquivo de configurações substitui a mesma variável exportada no shell. Variáveis que o arquivo não define, como uma ANTHROPIC_API_KEY antiga, continuam vindo do shell.

Devo usar ANTHROPIC_AUTH_TOKEN ou ANTHROPIC_API_KEY?
Use a variável que seu gateway lê. ANTHROPIC_AUTH_TOKEN envia um token Bearer e não precisa de aprovação. Para o AIHubMix, ANTHROPIC_AUTH_TOKEN é a opção documentada. Não defina as duas: o AIHubMix lê x-api-key primeiro, então uma ANTHROPIC_API_KEY antiga causa um erro 401.

ANTHROPIC_BASE_URL deve terminar com /v1?
Não. O Claude Code adiciona /v1/messages por conta própria. Para o AIHubMix, use https://aihubmix.com.

Preciso reiniciar o Claude Code depois de editar settings.json?
A maioria das alterações, incluindo as de env, é aplicada ao salvar. A chave do modelo e as exportações do shell exigem uma reinicialização. Reiniciar é a opção mais segura.

Por que o VS Code pede para eu entrar na conta quando a CLI funciona?
Antes de iniciar, a extensão verifica se há um login usando a configuração claudeCode.environmentVariables, e os valores em ~/.claude/settings.json não são acessados por essa verificação. Adicione a URL base e o token lá e recarregue a janela.

Definir ANTHROPIC_BASE_URL usa minha assinatura do Claude?
Somente se nenhum token estiver definido. Com ANTHROPIC_AUTH_TOKEN ou ANTHROPIC_API_KEY definido, as solicitações usam essa chave, e o gateway cobra por token.

Fontes

• Arquivos de configurações e precedência, Anthropic
• Variáveis de ambiente, Anthropic
• Conectar o Claude Code a um gateway de LLM, Anthropic
• Configuração do modelo, Anthropic
• Guia de integração do Claude Code, AIHubMix