Conectar Claude Code a um gateway LLM

​

Verificar uma configuração existente

​

Configurar Claude Code você mesmo

• 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

• 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

​

Definir a URL base e a credencial

​

Definir como variáveis de ambiente do shell

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"

​

Definir em um arquivo de configurações

• ~/.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

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

​

Verificar a conexão

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": "."}]}'

​

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

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

​

Aplicativo desktop

• 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

​

GitHub Actions

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

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

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

​

Agent SDK

• 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

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

​

Configuração adicional

​

Enviar cabeçalhos adicionais

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

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

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

​

Adicionar modelos de gateway ao seletor de modelo

​

Rotacionar credenciais com apiKeyHelper

#!/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"
}

​

Desativar tráfego fora do caminho do gateway

export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

$env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1"

• 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

• 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

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

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"

• 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

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

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

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

​

Solucionar erros de gateway

​

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