Conectar Claude Code a um gateway LLM

Aponte Claude Code para o gateway LLM da sua organização. Verifique se seu administrador já o configurou ou defina a URL base e a credencial você mesmo, depois verifique a conexão e corrija erros do gateway.

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.

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:

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:

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:

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.

Se você exportar o gateway apenas em seu shell, ele não chega de forma confiável aos agentes de fundo hospedados pelo supervisor; veja como cada sessão de fundo obtém seu gateway. Use um arquivo de configurações para qualquer gateway que agentes de fundo devem sempre rotear através.

Definir em um arquivo de configurações

Para fazer a configuração se aplicar em todos os lugares onde Claude Code é executado, incluindo agentes de fundo, defina as variáveis no bloco env de um arquivo de configurações em vez de depender do seu shell. 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 global quando salva uma configuração lá; se você o criar manualmente ou tiver Claude escrevê-lo, adicione-o ao seu gitignore você mesmo primeiro para não cometer acidentalmente sua credencial

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.

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.

Conflitos com um login existente

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, sessões em nuvem e Remote Control

Claude Code no Slack e sessões em nuvem 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. 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ó. Antes da v2.1.196, uma URL base não-Anthropic não bloqueava Remote Control.

Para restaurar qualquer um dos recursos, faça login com claude.ai e desdefina as variáveis de gateway que o recurso verifica. A seção Remote Control de claude doctor nomeia o que está bloqueando Remote Control no momento.

• 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:

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

Nomes de cabeçalho de roteamento e locatário como esses contam como cabeçalhos que precisam de aprovação. Quando os cabeçalhos vêm de um arquivo de configurações de projeto, Claude Code os aplica sob as regras para quando aplica valores env.

Adicionar modelos de gateway ao seletor de modelo

Com a descoberta de modelo ativada, Claude Code consulta o gateway para sua lista de modelos na inicialização e adiciona esses nomes ao seletor /model junto com as entradas integradas. Se você ou seu administrador definirem replaceBuiltInOptions em um modelPicker, Claude Code também oculta os nomes descobertos. Ele mantém uma linha para o modelo que a sessão já está usando.

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.

Os modelos descobertos aparecem como entradas /model adicionais. Cada entrada mostra a descrição que seu gateway fornece para o modelo, ou From gateway quando não fornece uma.

Para confirmar que a descoberta foi executada, inicie claude --debug e procure pelas linhas [gatewayDiscovery] no log de depuração em ~/.claude/debug/<session-id>.txt. A primeira vez que a descoberta é bem-sucedida, Claude Code registra quantos modelos foram armazenados em cache, e registra novamente apenas quando a lista do gateway muda. Um 404, timeout ou redirecionamento aparece 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. Faça o comando imprimir nada além da credencial. No Claude Code v2.1.227 ou posterior, um banner ou uma linha de log impressa junto com a chave faz o auxiliar falhar. Escreva o script, torne-o executável e referencie-o de apiKeyHelper em seu arquivo de configurações:

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

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

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

{
"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 re-executa o auxiliar após o tempo de vida do cache expirar. Para alterar o tempo de vida, defina CLAUDE_CODE_API_KEY_HELPER_TTL_MS em milissegundos, por exemplo CLAUDE_CODE_API_KEY_HELPER_TTL_MS=900000 para 15 minutos.

Consulte apiKeyHelper para os outros casos em que Claude Code re-executa o auxiliar.

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, 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.

Claude Code anexa uma credencial a uma solicitação de telemetria ou métricas de uso apenas quando a solicitação vai para o host ao qual a credencial pertence. Enquanto ANTHROPIC_BASE_URL aponta para o gateway, Claude Code envia seus eventos de telemetria para Anthropic sem sua credencial de gateway. Com uma variável de credencial ou apiKeyHelper também ativa, Claude Code não relata métricas de uso para o painel analytics do Console. Antes de v2.1.246, Claude Code poderia anexar a credencial do gateway a solicitações de telemetria e métricas de uso destinadas a hosts Anthropic; solicitações de modelo sempre iam para o gateway com a credencial que o gateway espera.

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:

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.
• Não afeta a descoberta de modelo de gateway, que consulta apenas seu gateway. Antes de v2.1.257, a variável também parava a descoberta de atualizar, então o seletor mantinha a lista previamente armazenada em cache.
• 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. Na rota Amazon Bedrock e Google Cloud's Agent Platform, Claude Code também limita os cabeçalhos beta e campos de solicitação que envia ao conjunto que o provedor aceita. Para o que seu gateway recebe em cada rota, consulte o guia de compatibilidade de gateway.

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 nos blocos Amazon Bedrock, Google Cloud's Agent Platform e Claude Platform on AWS dizem a Claude Code para não assinar solicitações com credenciais do provedor em nuvem, já que o gateway as mantém. Se o gateway também precisa de seu próprio token, onde você o coloca depende do provedor:

• Amazon Bedrock, Google Cloud's Agent Platform ou Claude Platform on AWS: adicione ANTHROPIC_AUTH_TOKEN após o bloco. Claude Code o envia para o gateway como um cabeçalho Authorization: Bearer. Para uma credencial em um esquema ou cabeçalho diferente, use ANTHROPIC_CUSTOM_HEADERS em vez disso. Mantenha a variável skip-auth definida de qualquer forma, já que sem ela Claude Code remove qualquer cabeçalho Authorization que ANTHROPIC_AUTH_TOKEN, um apiKeyHelper ou ANTHROPIC_CUSTOM_HEADERS adicionaria.
• Microsoft Foundry: use ANTHROPIC_FOUNDRY_API_KEY conforme seu bloco mostra

Amazon Bedrock

Deixe AWS_BEARER_TOKEN_BEDROCK indefinido quando o gateway emite sua própria credencial. Se você o definir, Claude Code envia essa chave de API Amazon Bedrock como o cabeçalho Authorization em vez de seu token de gateway, mesmo com CLAUDE_CODE_SKIP_BEDROCK_AUTH definido.

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

Substitua o ID do projeto e a região pelos seus próprios valores. Claude Code inclui ambos no caminho de cada solicitação que envia para o gateway:

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"

O bloco cobre roteamento e autenticação. As substituições de região e pins de modelo da configuração do Agent Platform se aplicam através de um gateway também:

• Regiões por modelo: se seu gateway serve alguns modelos de uma região diferente de CLOUD_ML_REGION, defina a variável VERTEX_REGION_CLAUDE_* correspondente para cada um, por exemplo VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1. A referência de variáveis de ambiente lista os nomes exatos.
• Versões de modelo: pin ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL e ANTHROPIC_DEFAULT_HAIKU_MODEL conforme em Pin model versions. Definir ANTHROPIC_DEFAULT_HAIKU_MODEL também move tarefas de fundo como títulos de sessão para esse modelo, e essa seção explica qual modelo as executa de outra forma.
• Capacidades de modelo: se você pin um ID de modelo que sua versão de Claude Code não reconhece, recursos como níveis de esforço ou pensamento estendido podem permanecer desativados nele. Declare o que o modelo suporta com ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES e seus equivalentes Sonnet e Haiku.

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.

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.

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"

Confirmar a rota do provedor

Inicie claude a partir do shell onde você definiu o bloco e execute /status. Com o bloco Amazon Bedrock, a aba Status mostra linhas como estas:

API provider: Amazon Bedrock
Bedrock base URL: https://llm-gateway.example.com/bedrock
AWS auth skipped

Os outros blocos produzem as mesmas linhas sob os nomes de seus provedores, por exemplo Vertex base URL e GCP auth skipped para Google Cloud's Agent Platform; o bloco Microsoft Foundry mostra uma linha de auth skipped apenas se você definir CLAUDE_CODE_SKIP_FOUNDRY_AUTH. Se você também rotear através de um proxy corporativo, uma linha Proxy mostra a URL do proxy. Se a linha de URL base está faltando, a variável não alcançou a sessão.

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:

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.

Recursos relacionados

• 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
• Guia de compatibilidade 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