Conectar Claude Code a um gateway LLM

Um gateway LLM é um proxy que sua organização executa entre Claude Code e o provedor de modelo. Quando sua organização usa um, Claude Code se autentica no gateway com uma credencial que sua organização emite em vez de seu login pessoal claude.ai. Esta página é para desenvolvedores que executam Claude Code através de um gateway que sua organização opera. Ela cobre dois caminhos: verificar se seu administrador já o configurou para você e configurá-lo você mesmo quando não tiverem.

Para implantar um gateway para sua organização, consulte Implementar um gateway LLM
Para saber o que Claude Code envia para um gateway, consulte a referência do protocolo do gateway

Verificar uma configuração existente

Os administradores podem distribuir o endereço do gateway e a credencial através de configurações gerenciadas, gerenciamento de dispositivos ou um apiKeyHelper, para que Claude Code os pegue na inicialização sem nada para você configurar. Para verificar se sua organização já fez isso:

Iniciar Claude Code

Execute claude. Se ele abrir para a tela de login em vez de uma sessão, nenhuma credencial de gateway foi distribuída; configure-a você mesmo abaixo.

Verificar a aba Status

Se Claude Code iniciou uma sessão sem mostrar a tela de login, execute /status, abra a aba Status e verifique duas linhas:

Anthropic base URL: esta linha aparece apenas quando um endereço de gateway está definido. Se não estiver lá, Claude Code não está apontado para o gateway; configure-o você mesmo abaixo.
Auth token ou API key: uma linha nomeando ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY ou um apiKeyHelper confirma que uma credencial de gateway está ativa. Uma linha Login method nomeando uma conta claude.ai em vez disso significa que a credencial não foi distribuída; defina-a você mesmo.

Enviar uma mensagem de teste

Feche o menu /status e envie qualquer prompt em Claude Code. Uma resposta normal de Claude, sem erro, confirma que a conexão do gateway funciona.

Se ambas as linhas no menu /status parecerem corretas, mas a mensagem para Claude falhar, consulte a tabela de solução de problemas.

Configurar Claude Code você mesmo

Para configurar Claude Code para o gateway você mesmo, você precisa de sua equipe de gateway:

A URL base do gateway
Uma credencial: uma string de chave ou token, ou um comando que busca uma
- Se sua equipe de gateway não disse qual tipo de credencial é, a seção variável de credencial abaixo cobre o que tentar

As seções abaixo cobrem a configuração em ordem:

Definir a variável de credencial e definir a URL base: as duas variáveis que toda conexão de gateway precisa
Verificar a conexão: confirme que funciona antes de persistir qualquer coisa
Configurar cada superfície: se você está usando uma superfície além do CLI Claude Code, como VS Code, veja como configurá-la com suas credenciais de gateway
Configuração adicional: variáveis que alguns gateways precisam além da URL base e credencial, como um cabeçalho personalizado, um auxiliar de credencial, descoberta de modelo, uma URL base em formato de provedor, ou desativar o tráfego fora do caminho do gateway. Defina estas apenas se seu administrador as nomeou ou sua rede restringe saída

Definir a variável de credencial

Para autenticar Claude Code no gateway, defina sua credencial em uma variável de ambiente. Qual variável depende do que sua equipe de gateway disse:

Definir a credencial em	Use quando
`ANTHROPIC_AUTH_TOKEN`	Sua equipe de gateway disse “bearer token” ou “Authorization header”
`ANTHROPIC_API_KEY`	Sua equipe de gateway disse “API key” ou “x-api-key”
`apiKeyHelper`	A credencial rotaciona ou vem de um vault

Se você não foi informado qual tipo, use ANTHROPIC_AUTH_TOKEN; a solicitação de verificação abaixo mostra como saber se você precisa mudar.

Definir a URL base e a credencial

Defina a URL base do gateway e a variável de credencial que você escolheu acima como variáveis de ambiente. Os exemplos usam ANTHROPIC_AUTH_TOKEN; troque-o por ANTHROPIC_API_KEY se essa for a variável que você escolheu. Você pode defini-los em seu shell, que dura uma sessão de terminal, ou em um arquivo de configurações Claude Code, que persiste em todos os lugares onde Claude Code é executado. Para sua primeira conexão, comece com exportações de shell e execute a solicitação de verificação antes de mover os valores para um arquivo de configurações.

Definir como variáveis de ambiente do shell

Substitua os valores pelos que sua equipe de gateway forneceu:

Bash ou Zsh
PowerShell

export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
export ANTHROPIC_AUTH_TOKEN=sk-gateway-key

$env:ANTHROPIC_BASE_URL = "https://llm-gateway.example.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-gateway-key"

As exportações de shell se aplicam apenas a essa sessão de terminal e aos programas iniciados a partir dela; um editor iniciado do dock ou menu Iniciar não as verá. Para torná-las persistentes em novos terminais, adicione as mesmas linhas ao seu perfil de shell, como ~/.zshrc, ~/.bashrc ou seu $PROFILE do PowerShell, ou use um arquivo de configurações em vez disso.

Definir em um arquivo de configurações

Para fazer a configuração se aplicar em todos os lugares onde Claude Code é executado sem depender do seu shell, defina as variáveis no bloco env de um arquivo de configurações. Os arquivos de configurações têm escopos diferentes:

~/.claude/settings.json se aplica a todos os seus projetos. No Windows, o caminho é %USERPROFILE%\.claude\settings.json
.claude/settings.local.json se aplica a um projeto. Claude Code o adiciona ao seu gitignore quando cria o arquivo; se você o criar você mesmo, adicione-o ao seu gitignore manualmente primeiro para não cometer acidentalmente sua credencial

Não coloque a credencial no .claude/settings.json de um projeto. Esse arquivo é confirmado e compartilhado com todos que clonam o repositório.

O bloco env se parece igual em qualquer arquivo:

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

Quando uma exportação de shell e um bloco env de arquivo de configurações definem a mesma variável, o valor do arquivo de configurações se aplica. Execute /status para ver qual URL base e fonte de credencial Claude Code está usando.

Verificar a conexão

Com as variáveis exportadas em seu shell, envie uma solicitação de um token para o gateway diretamente. Isso confirma que a URL e a credencial funcionam antes de você abrir Claude Code, para que uma falha aponte para o gateway em vez de sua configuração. Os comandos abaixo leem as variáveis do shell, então eles precisam das exportações de shell mesmo se você também colocar os valores em um arquivo de configurações.

Bash ou Zsh
PowerShell

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": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

Invoke-RestMethod -Method Post -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `
  -Headers @{ "Authorization" = "Bearer $env:ANTHROPIC_AUTH_TOKEN"; "anthropic-version" = "2023-06-01" } `
  -ContentType "application/json" `
  -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

Se seu gateway espera chaves no cabeçalho x-api-key, substitua o cabeçalho Authorization por x-api-key: $ANTHROPIC_API_KEY no comando Bash, ou a entrada da tabela hash "Authorization" por "x-api-key" = "$env:ANTHROPIC_API_KEY" no comando PowerShell. Uma resposta JSON que começa com {"id":"msg_ e inclui um campo "content":[...] significa que o gateway é alcançável e a credencial funciona. Um erro nomeando um modelo desconhecido ainda prova que a URL e a credencial funcionam, já que o gateway autenticou a solicitação antes de rejeitar o nome do modelo; você não precisa encontrar um modelo que seu gateway serve para este teste. Um 401 significa que a credencial foi rejeitada: se você adivinhou a variável, mude para a outra e re-exporte.

Confirmar em Claude Code

Inicie claude do mesmo shell para que ele herde as exportações, envie uma mensagem e execute /status. Na aba Status, a linha Anthropic base URL deve mostrar seu endereço de gateway, o que confirma que as solicitações estão sendo roteadas para lá; se a linha não estiver lá, a variável não chegou à sessão. Uma linha Auth token ou API key nomeando a variável que você definiu confirma que a credencial de gateway está ativa em vez de um login claude.ai salvo. Se a mensagem falhar ou /status não mostrar a URL do gateway, consulte a tabela de solução de problemas abaixo.

Como a variável de credencial mapeia para um cabeçalho

Cada variável envia a credencial em um cabeçalho HTTP diferente: ANTHROPIC_AUTH_TOKEN em Authorization: Bearer, ANTHROPIC_API_KEY em x-api-key e apiKeyHelper em ambos. Uma credencial na variável errada chega ao gateway em um cabeçalho que ele não lê, e a solicitação falha com 401. Se a solicitação de verificação retornou 401, mude para a outra variável e tente novamente. Uma variável de credencial de gateway tem precedência sobre um login claude.ai salvo ou uma chave Console. Seu login claude.ai permanece salvo e não utilizado enquanto a variável está definida; desdefina a variável e Claude Code volta para ela. Com ANTHROPIC_AUTH_TOKEN, a variável tem precedência imediatamente. Com ANTHROPIC_API_KEY, você é solicitado uma vez em modo interativo para aprovar a chave antes que ela assuma o controle. Execute /status para confirmar qual fonte de credencial está ativa. Se a inicialização mostrar um aviso de conflito de autenticação nomeando duas fontes, consulte a primeira linha da tabela de solução de problemas para saber qual descartar. Para limpar um login salvo para que apenas a credencial de gateway permaneça, execute /logout.

Configurar cada superfície

O CLI lê as variáveis de ambiente e arquivos de configurações acima. As outras superfícies são a extensão VS Code, o aplicativo desktop, GitHub Actions, o Agent SDK e as superfícies em nuvem, como Slack e a web; as seções abaixo cobrem se essas configurações chegam a cada uma.

Extensão VS Code

Defina as variáveis de gateway para a extensão VS Code em claudeCode.environmentVariables, nas próprias configurações do usuário do VS Code abertas com o comando Preferences: Open User Settings (JSON). A extensão verifica credenciais dessa configuração antes de iniciar, então é o lugar confiável para a credencial de gateway; valores em ~/.claude/settings.json chegam ao processo gerado, mas não à verificação de login da própria extensão.

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

Aplicativo desktop

O aplicativo desktop lê o roteamento de gateway de sua configuração de inferência de terceiros, não de ANTHROPIC_BASE_URL ou settings.json. Essa configuração pode vir de sua organização ou de um formulário no próprio aplicativo:

Distribuído por um administrador: se sua organização implantou a configuração, o aplicativo desktop roteia através do gateway sem nenhuma configuração de sua parte
Configurado localmente: para dispositivos sem uma configuração distribuída por administrador, abra Help → Troubleshooting → Enable Developer Mode, que reinicia o aplicativo com um menu Developer. Em seguida, abra Developer → Configure Third-Party Inference e insira a URL base do seu gateway. Uma configuração distribuída por administrador tem precedência e torna esse formulário somente leitura

Com a configuração de gateway ativa, o aplicativo desktop executa sessões apenas em sua máquina local: o seletor de ambiente não oferece sessões SSH ou ambientes em nuvem hospedados pela Anthropic, e Remote Control não está disponível. Para usar Claude Code em um host remoto através do gateway, execute o CLI nesse host com ANTHROPIC_BASE_URL e a credencial de gateway definidos lá. Se o aplicativo desktop mostrar Gateway was unreachable, o aplicativo não conseguiu alcançar a URL base configurada na inicialização; verifique a URL e o caminho de rede com o teste curl acima.

GitHub Actions

Claude Code GitHub Actions lê ANTHROPIC_BASE_URL e ANTHROPIC_CUSTOM_HEADERS do bloco env do workflow. Passe a credencial como a entrada anthropic_api_key da ação; a ação a define como ANTHROPIC_API_KEY, para que chegue ao gateway no cabeçalho x-api-key. Para um gateway x-api-key, defina a URL base em env e passe a chave de gateway como a entrada:

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 de bearer token, passe o mesmo segredo duas vezes: como a entrada anthropic_api_key e como ANTHROPIC_AUTH_TOKEN no bloco env do workflow. A ação requer anthropic_api_key, CLAUDE_CODE_OAUTH_TOKEN ou federação de identidade de carga de trabalho antes de iniciar Claude Code, e não lê ANTHROPIC_AUTH_TOKEN, então a entrada está lá apenas para satisfazer essa verificação de inicialização. A variável de env é o que coloca a chave no cabeçalho Authorization que o gateway lê; a cópia em x-api-key é ignorada:

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 }}

Para as outras opções de autenticação da ação, incluindo CLAUDE_CODE_OAUTH_TOKEN e federação de identidade de carga de trabalho, consulte Claude Code GitHub Actions e o README da ação.

Agent SDK

O Agent SDK não tem opções específicas de gateway; ele passa variáveis de ambiente para o processo Claude Code que gera. Cada SDK aceita uma opção env que define o ambiente do processo gerado, e os SDKs TypeScript e Python o tratam de forma diferente:

TypeScript: o processo gerado herda o ambiente pai por padrão, mas definir options.env substitui o ambiente inteiramente. Espalhe process.env nele para manter suas variáveis de gateway.
Python: ClaudeAgentOptions(env=...) mescla no topo do ambiente herdado, para que variáveis de gateway definidas no processo pai passem sem espalhar.

const result = query({
  prompt: "...",
  options: {
    env: {
      ...process.env,
      ANTHROPIC_BASE_URL: "https://llm-gateway.example.com",
      ANTHROPIC_AUTH_TOKEN: process.env.GATEWAY_KEY,
    },
  },
})

options = ClaudeAgentOptions(
    env={
        "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
        "ANTHROPIC_AUTH_TOKEN": os.environ["GATEWAY_KEY"],
    }
)

Slack, web e Remote Control

Claude Code no Slack e Claude Code na web são produtos hospedados pela Anthropic que sempre usam a API da Anthropic; eles não fazem parte de uma implantação de gateway. Variáveis de gateway definidas na configuração de ambiente de uma sessão em nuvem não são aplicadas. Se seu tráfego deve permanecer no gateway, não ative essas superfícies para esses usuários. Remote Control e ditado por voz ambos dependem de uma identidade claude.ai: Remote Control para emparelhar uma sessão ao vivo com sua conta e ditado por voz para alcançar o endpoint de transcrição claude.ai. Eles não estão disponíveis enquanto ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN ou um apiKeyHelper está ativo. A partir da v2.1.196, Remote Control também está desabilitado enquanto ANTHROPIC_BASE_URL aponta para um host não-Anthropic, então fazer login com claude.ai não é suficiente por si só. Para restaurar qualquer um dos recursos, faça login com claude.ai e desdefina as variáveis de gateway que ele verifica. A seção Remote Control de claude doctor nomeia a variável de credencial a desdefir.

Ditado por voz: desdefina a credencial de gateway
Remote Control: desdefina a credencial de gateway e ANTHROPIC_BASE_URL

Configuração adicional

Essas configurações cobrem casos além da URL base e credencial. Defina-as apenas se as instruções do seu administrador, as regras de saída da sua rede ou a tabela de solução de problemas chamarem por uma.

Enviar cabeçalhos adicionais

Alguns gateways roteiam ou marcam solicitações usando um cabeçalho personalizado além da credencial, por exemplo um identificador de locatário ou uma chave de roteamento. Para enviar um, defina ANTHROPIC_CUSTOM_HEADERS com um par Name: Value por linha. O exemplo abaixo adiciona um cabeçalho de roteamento nomeado X-Org-Route:

Bash ou Zsh
PowerShell

export ANTHROPIC_CUSTOM_HEADERS="X-Org-Route: prod"

$env:ANTHROPIC_CUSTOM_HEADERS = "X-Org-Route: prod"

Você também pode definir ANTHROPIC_CUSTOM_HEADERS no bloco env de um arquivo de configurações. Use \n entre pares lá, já que strings JSON não podem abranger várias linhas:

{
  "env": {
    "ANTHROPIC_CUSTOM_HEADERS": "X-Org-Route: prod\nX-Tenant: example"
  }
}

Adicionar modelos de gateway ao seletor de modelo

A descoberta de modelo consulta o gateway para sua lista de modelos na inicialização e adiciona esses nomes ao seletor /model junto com as entradas integradas. Ative-a se seu gateway serve nomes de modelo que não estão na lista integrada de Claude Code e você quer selecioná-los do seletor. Se os modelos integrados são o que você usa, você não precisa de descoberta; seu administrador também pode já ter ativado através de configurações gerenciadas. Para ativá-la, defina CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 em seu shell ou no bloco env de ~/.claude/settings.json. A descoberta requer Claude Code v2.1.129 ou posterior. Os modelos descobertos aparecem como entradas /model adicionais rotuladas From gateway. Para confirmar que a descoberta foi executada, inicie claude --debug e procure pelas linhas [gatewayDiscovery]: um sucesso registra quantos modelos foram armazenados em cache, e um 404, timeout ou redirecionamento é registrado lá também. Para quando a descoberta é executada, o que ela filtra e o formato de resposta que os gateways servem, consulte a referência de descoberta de modelo.

Rotacionar credenciais com apiKeyHelper

Um apiKeyHelper é um comando que Claude Code executa para buscar sua credencial de gateway, em vez de lê-la de uma variável de ambiente estática. Use um auxiliar quando a credencial expira em um cronograma, vem de um vault ou comando SSO, ou seu administrador disse para você configurar um. Se sua credencial é uma string fixa que você define uma vez, a variável de credencial é tudo que você precisa e você pode pular esta seção. O auxiliar é qualquer comando de shell que imprime a credencial atual para stdout. Claude Code o executa através do seu shell do sistema, então no Windows pode ser um executável ou uma invocação do PowerShell. Escreva o script, torne-o executável e referencie-o de apiKeyHelper em seu arquivo de configurações:

Bash ou Zsh
PowerShell

Por exemplo, um script que lê de um vault:

#!/bin/bash
vault kv get -field=api_key secret/llm-gateway/claude-code

Referencie seu caminho em ~/.claude/settings.json:

{
  "apiKeyHelper": "~/bin/get-gateway-key.sh"
}

Por exemplo, um script que lê de um vault:

vault kv get -field=api_key secret/llm-gateway/claude-code

Referencie a invocação do PowerShell em %USERPROFILE%\.claude\settings.json, escapando as barras invertidas na string JSON:

{
  "apiKeyHelper": "powershell -NoProfile -File C:\\scripts\\get-gateway-key.ps1"
}

Claude Code armazena em cache a saída do auxiliar por cinco minutos por padrão e o re-executa quando uma solicitação retorna HTTP 401. Para alterar o tempo de vida do cache, defina CLAUDE_CODE_API_KEY_HELPER_TTL_MS em milissegundos, por exemplo CLAUDE_CODE_API_KEY_HELPER_TTL_MS=900000 para 15 minutos. O valor do auxiliar é enviado nos cabeçalhos Authorization e x-api-key, então funciona qualquer que seja o cabeçalho que seu gateway leia.

Desativar tráfego fora do caminho do gateway

O gateway carrega solicitações de modelo, mas Claude Code também envia tráfego de fundo não essencial fora do caminho do gateway, para Anthropic e para serviços de terceiros como GitHub: verificações de versão, telemetria, relatórios de erro, notas de lançamento e solicitações similares. Em uma rede que permite apenas saída para o gateway, essas solicitações falham e podem aparecer como conexões bloqueadas em seu monitoramento de saída. Para desativar esse tráfego, defina CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 junto com as variáveis de gateway, no mesmo bloco de exportações de shell ou env do arquivo de configurações:

Bash ou Zsh
PowerShell

export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

$env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1"

Definir a variável tem esses efeitos e limitações:

Desativa atualizações automáticas, então planeje outro caminho de atualização, como seu gerenciador de pacotes ou distribuição gerenciada.
Suprime a verificação de disponibilidade do modo rápido. A menos que uma verificação anterior já tenha ativado o modo rápido na máquina, /fast relata que o modo rápido está indisponível.
Desativa a descoberta de modelo de gateway, mesmo que a descoberta consulte o próprio gateway. Os modelos descobertos anteriormente permanecem disponíveis do cache local, mas a lista não é atualizada.
A verificação de segurança de domínio da ferramenta WebFetch](/pt/data-usage#webfetch-domain-safety-check) não é afetada e ainda chama api.anthropic.com. Desative-a separadamente com skipWebFetchPreflight: true em configurações se sua rede bloquear esse host.
Para cada fluxo de telemetria e a variável que a controla, consulte serviços de telemetria.

Rotear para um provedor em nuvem através de um gateway

Essas configurações apontam Claude Code para um gateway através de uma variável de URL base específica do provedor no lugar de ANTHROPIC_BASE_URL. Gateways Amazon Bedrock e Google Cloud’s Agent Platform aceitam formatos de solicitação nativos desses provedores; gateways Microsoft Foundry e Claude Platform on AWS aceitam o formato Anthropic Messages e diferem apenas em qual variável de URL base os alcança. Use uma apenas se sua equipe de gateway nomeou especificamente Amazon Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry ou Claude Platform on AWS. Se a solicitação de verificação acima retornou JSON, você pode pular esta seção. Defina o bloco para o provedor que sua equipe de gateway nomeou. As variáveis skip-auth dizem a Claude Code para não assinar solicitações com credenciais de provedor, já que o gateway as mantém. Se o gateway precisa de seu próprio token, adicione ANTHROPIC_AUTH_TOKEN após o bloco, exceto para Microsoft Foundry, que usa ANTHROPIC_FOUNDRY_API_KEY conforme mostrado. Um gateway Microsoft Foundry que espera um token bearer pode usar ANTHROPIC_FOUNDRY_AUTH_TOKEN em vez disso; ele tem precedência sobre ANTHROPIC_FOUNDRY_API_KEY quando ambos estão definidos. ANTHROPIC_FOUNDRY_AUTH_TOKEN requer Claude Code v2.1.203 ou posterior.

Amazon Bedrock

Bash ou Zsh
PowerShell

export ANTHROPIC_BEDROCK_BASE_URL=https://llm-gateway.example.com/bedrock
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
export CLAUDE_CODE_USE_BEDROCK=1

$env:ANTHROPIC_BEDROCK_BASE_URL = "https://llm-gateway.example.com/bedrock"
$env:CLAUDE_CODE_SKIP_BEDROCK_AUTH = "1"
$env:CLAUDE_CODE_USE_BEDROCK = "1"

Google Cloud’s Agent Platform

Bash ou Zsh
PowerShell

export ANTHROPIC_VERTEX_BASE_URL=https://llm-gateway.example.com/vertex
export ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
export CLAUDE_CODE_SKIP_VERTEX_AUTH=1
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5

$env:ANTHROPIC_VERTEX_BASE_URL = "https://llm-gateway.example.com/vertex"
$env:ANTHROPIC_VERTEX_PROJECT_ID = "your-gcp-project-id"
$env:CLAUDE_CODE_SKIP_VERTEX_AUTH = "1"
$env:CLAUDE_CODE_USE_VERTEX = "1"
$env:CLOUD_ML_REGION = "us-east5"

Microsoft Foundry

Coloque a credencial do gateway em ANTHROPIC_FOUNDRY_API_KEY; ela é enviada para o gateway como o cabeçalho x-api-key. Um gateway que espera um token bearer pode usar ANTHROPIC_FOUNDRY_AUTH_TOKEN em vez disso. Claude Code envia esse valor como o cabeçalho Authorization: Bearer, e ele tem precedência sobre ANTHROPIC_FOUNDRY_API_KEY quando ambos estão definidos. Requer Claude Code v2.1.203 ou posterior. Para um gateway que injeta seu próprio cabeçalho Authorization, defina CLAUDE_CODE_SKIP_FOUNDRY_AUTH=1 e deixe ambas as variáveis de credencial indefinidas. Claude Code então envia solicitações sem uma credencial do Azure e preserva o cabeçalho Authorization que você fornece, por exemplo através de ANTHROPIC_CUSTOM_HEADERS. Antes de v2.1.203, CLAUDE_CODE_SKIP_FOUNDRY_AUTH sem uma chave de API deixava o cliente Microsoft Foundry incapaz de enviar solicitações.

Bash ou Zsh
PowerShell

export ANTHROPIC_FOUNDRY_BASE_URL=https://llm-gateway.example.com/foundry
export ANTHROPIC_FOUNDRY_API_KEY=sk-gateway-key
export CLAUDE_CODE_USE_FOUNDRY=1

$env:ANTHROPIC_FOUNDRY_BASE_URL = "https://llm-gateway.example.com/foundry"
$env:ANTHROPIC_FOUNDRY_API_KEY = "sk-gateway-key"
$env:CLAUDE_CODE_USE_FOUNDRY = "1"

Claude Platform on AWS

Consulte Claude Platform on AWS para o ID do workspace.

Bash ou Zsh
PowerShell

export ANTHROPIC_AWS_BASE_URL=https://llm-gateway.example.com/anthropic-aws
export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
export CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1
export CLAUDE_CODE_USE_ANTHROPIC_AWS=1

$env:ANTHROPIC_AWS_BASE_URL = "https://llm-gateway.example.com/anthropic-aws"
$env:ANTHROPIC_AWS_WORKSPACE_ID = "wrkspc_01ABCDEFGHIJKLMN"
$env:CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH = "1"
$env:CLAUDE_CODE_USE_ANTHROPIC_AWS = "1"

Solucionar erros de gateway

Estes são os erros mais comuns ao executar Claude Code através de um gateway, com a causa do lado do gateway e a correção:

Erro	Causa	Correção
Um aviso de inicialização nomeando duas fontes de credencial e terminando em `auth may not work as expected`. Versões mais antigas mostram `Auth conflict: Both a token (SOURCE) and an API key (SOURCE) are set` em vez disso.	Uma credencial de gateway e um login salvo estão ambos ativos; a variável é usada para solicitações, mas o login obsoleto pode causar comportamento de autenticação inesperado	Desdefina a variável para usar o login salvo, ou execute `/logout` para usar a credencial de gateway
Erros `401` nomeando um token inválido ou não reconhecido	A credencial não é uma que o gateway emitiu, ou está em um cabeçalho que o gateway não lê	Confirme que a variável corresponde ao seu tipo de credencial na tabela de credencial e regenere a chave no gateway se ela foi revogada
`Your apiKeyHelper script is failing`	O comando na configuração `apiKeyHelper` saiu com um erro, expirou ou não imprimiu nada, portanto as solicitações carregam uma chave de espaço reservado	Execute o comando diretamente para ver por que falha e autentique-se novamente com seu provedor de credencial se ele relatar uma sessão expirada; consulte a referência de erro
`Unable to connect to API (ConnectionRefused)` ou `(ECONNREFUSED)` de instalações npm, frequentemente após uma pausa silenciosa enquanto Claude Code tenta novamente com backoff	Nada respondeu na URL base: o endereço está errado ou uma VPN ou firewall bloqueia o caminho para o gateway	Execute o teste curl acima, que falha imediatamente com a mesma causa, e confirme a URL e o caminho de rede com sua equipe de gateway
`API returned an empty or malformed response (HTTP 200)`	O gateway ou um proxy intermediário retornou uma resposta não-API, frequentemente uma página de erro HTML ou login	Teste com a solicitação curl acima; corrija a rota do gateway que retorna não-JSON
Erros `400` nomeando `context_management`, `Extra inputs are not permitted` ou outros campos não reconhecidos	O gateway encaminha solicitações para um upstream que rejeita campos que Claude Code envia para endpoints em formato Anthropic	Defina `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`, que suprime a maioria dos campos de pré-lançamento; consulte passagem de recurso. Alguns betas não são controlados por este sinalizador; para esses, defina a variável de provedor `CLAUDE_CODE_USE_*` correspondente para que Claude Code envie apenas o que esse provedor aceita
Erros `400` nomeando `thinking` ou `adaptive`, como `Input tag 'adaptive' found`	A compilação do modelo upstream não aceita raciocínio adaptativo, que Claude Code solicita para modelos Claude 4.6 e posteriores	Atualize o upstream do gateway. Em Opus 4.6 e Sonnet 4.6, `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` funciona em vez disso. As variáveis de capacidade de configuração de modelo se aplicam apenas às configurações de provedor, como `CLAUDE_CODE_USE_BEDROCK` e `CLAUDE_CODE_USE_VERTEX`, não atrás de um gateway `ANTHROPIC_BASE_URL`
Erros `400` indicando um contexto ou limite de token nas próprias palavras do gateway, como `ContextWindowExceededError` ou `prompt token count of N exceeds the limit of M`	O gateway impõe um contexto menor que a janela nativa do modelo e reescreve o erro upstream, para que a compactação automática e repetição, que corresponde à redação `prompt is too long` da Anthropic, não dispare	Execute `/compact` para recuperar a sessão. Para evitar, defina `CLAUDE_CODE_AUTO_COMPACT_WINDOW` para o limite do gateway; o valor é fixado em pelo menos 100.000 tokens e no máximo a janela de contexto do modelo, para que um limite de gateway abaixo de 100.000 não possa ser correspondido e `/compact` permaneça a recuperação lá. Também defina `CLAUDE_CODE_MAX_OUTPUT_TOKENS` abaixo do limite de saída do modelo de gateway
Modelos faltando do seletor `/model`	Nomes de modelo de gateway não estão na lista integrada de Claude Code	Ative descoberta de modelo de gateway ou adicione nomes com as variáveis de configuração de modelo
Claude Code pede para você fazer login mesmo que o teste curl tenha sucesso	O CLI não tem credencial própria: uma URL base alcançável não é uma, e um bloco `env` no `.claude/settings.json` ou `.claude/settings.local.json` de um projeto se aplica apenas após o assistente de primeira execução e prompt de confiança	Defina `ANTHROPIC_AUTH_TOKEN` em algum lugar que Claude Code leia antes da configuração de primeira execução: uma exportação de shell, o bloco `env` em `~/.claude/settings.json` ou configurações gerenciadas
`ANTHROPIC_API_KEY` está definido mas ignorado, sem prompt	A chave precisa de uma aprovação única em sessões interativas, e uma chave previamente recusada é ignorada sem perguntar novamente	Ative-a em `/config` com a opção `Use custom API key`
`This machine's managed settings require a first-party login`	Configurações gerenciadas incluem `forceLoginMethod` ou `forceLoginOrgUUID`, que em Claude Code v2.1.146 e posterior não podem coexistir com `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` ou `apiKeyHelper`	Seu administrador deve remover `forceLoginMethod` e `forceLoginOrgUUID` das configurações gerenciadas para usar credenciais de gateway, ou remover a credencial de gateway para usar login de primeira parte. Os dois não podem ser combinados
`403` com um corpo HTML como `403 Forbidden`, quando os próprios logs do gateway não mostram nenhuma solicitação recebida	Um firewall de aplicativo web ou proxy reverso na frente do gateway bloqueou o corpo da solicitação antes de chegar ao gateway. Os prompts de Claude Code incluem tags de estilo XML e código-fonte que correspondem a regras de corpo de cross-site-scripting, para que um teste curl curto passe enquanto uma sessão real não	Isente o caminho `/v1/messages` do gateway da inspeção de corpo de solicitação. No AWS WAF esta é a regra gerenciada `CrossSiteScripting_Body`; no nginx com ModSecurity é a regra de corpo OWASP CRS equivalente
Erros de certificado ou TLS como `SSL certificate verification failed` ou `Self-signed certificate detected`, quando o teste curl tem sucesso	O runtime de Claude Code não está confiando na mesma autoridade de certificação que `curl` usa. Comum atrás de proxies de inspeção TLS corporativa	Defina `NODE_EXTRA_CA_CERTS` para o caminho do pacote CA; consulte armazenamento de certificado CA

Se Claude Code solicitar que você faça login repetidamente após remover a configuração de gateway, a causa é geralmente armazenamento de credencial em vez do gateway; consulte erros de autenticação.

Visão geral de gateways LLM: o que é um gateway e como ele interage com assinaturas claude.ai
Implementar um gateway LLM para sua organização: a lista de verificação voltada para o administrador para implantar e distribuir configuração de gateway
Referência do protocolo de gateway: o que Claude Code envia para um gateway, incluindo os cabeçalhos e campos que o gateway deve encaminhar
Configurações: onde os arquivos de configurações vivem e como o bloco env é lido
Autenticação: como variáveis de credencial, apiKeyHelper e login OAuth interagem

Configuração e acesso

Implantação

Gateways

Uso e custos

Distribuição de plugins

Segurança e dados

Adoção

Conectar Claude Code a um gateway LLM

Verificar uma configuração existente

Configurar Claude Code você mesmo

Definir a variável de credencial

Definir a URL base e a credencial

Definir como variáveis de ambiente do shell

Definir em um arquivo de configurações

Verificar a conexão

Confirmar em Claude Code

Como a variável de credencial mapeia para um cabeçalho

Configurar cada superfície

Extensão VS Code

Aplicativo desktop

GitHub Actions

Agent SDK

Slack, web e Remote Control

Configuração adicional

Enviar cabeçalhos adicionais

Adicionar modelos de gateway ao seletor de modelo

Rotacionar credenciais com apiKeyHelper

Desativar tráfego fora do caminho do gateway

Rotear para um provedor em nuvem através de um gateway

Amazon Bedrock

Google Cloud’s Agent Platform

Microsoft Foundry

Claude Platform on AWS

Solucionar erros de gateway

​Verificar uma configuração existente

​Configurar Claude Code você mesmo

​Definir a variável de credencial

​Definir a URL base e a credencial

​Definir como variáveis de ambiente do shell

​Definir em um arquivo de configurações

​Verificar a conexão

​Confirmar em Claude Code

​Como a variável de credencial mapeia para um cabeçalho

​Conflitos com um login existente

​Configurar cada superfície

​Extensão VS Code

​Aplicativo desktop

​GitHub Actions

​Agent SDK

​Slack, web e Remote Control

​Configuração adicional

​Enviar cabeçalhos adicionais

​Adicionar modelos de gateway ao seletor de modelo

​Rotacionar credenciais com apiKeyHelper

​Desativar tráfego fora do caminho do gateway

​Rotear para um provedor em nuvem através de um gateway

​Amazon Bedrock

​Google Cloud’s Agent Platform

​Microsoft Foundry

​Claude Platform on AWS

​Solucionar erros de gateway

​Recursos relacionados

Verificar uma configuração existente

Configurar Claude Code você mesmo

Definir a variável de credencial

Definir a URL base e a credencial

Definir como variáveis de ambiente do shell

Definir em um arquivo de configurações

Verificar a conexão

Confirmar em Claude Code

Como a variável de credencial mapeia para um cabeçalho

Conflitos com um login existente

Configurar cada superfície

Extensão VS Code

Aplicativo desktop

GitHub Actions

Agent SDK

Slack, web e Remote Control

Configuração adicional

Enviar cabeçalhos adicionais

Adicionar modelos de gateway ao seletor de modelo

Rotacionar credenciais com apiKeyHelper

Desativar tráfego fora do caminho do gateway

Rotear para um provedor em nuvem através de um gateway

Amazon Bedrock

Google Cloud’s Agent Platform

Microsoft Foundry

Claude Platform on AWS

Solucionar erros de gateway

Recursos relacionados