Configuração do gateway LLM

Saiba como configurar Claude Code para trabalhar com soluções de gateway LLM. Abrange requisitos de gateway, configuração de autenticação, seleção de modelo e configuração de endpoint específica do provedor.

Gateways LLM fornecem uma camada proxy centralizada entre Claude Code e provedores de modelos, frequentemente fornecendo:

• Autenticação centralizada - Ponto único para gerenciamento de chaves de API
• Rastreamento de uso - Monitore o uso em equipes e projetos
• Controles de custo - Implemente orçamentos e limites de taxa
• Registro de auditoria - Rastreie todas as interações de modelo para conformidade
• Roteamento de modelo - Alterne entre provedores sem alterações de código

Esta página aborda os requisitos de gateway e a configuração para o Claude Code CLI. As implantações do Enterprise Desktop podem configurar provedores de gateway por meio de configurações gerenciadas. O aplicativo Claude Desktop também pode ser executado em um gateway auto-hospedado através da visualização de pesquisa Cowork on 3P, que usa suas próprias chaves de configuração.

Requisitos do gateway

Para que um gateway LLM funcione com Claude Code, ele deve atender aos seguintes requisitos:

Formato de API

O gateway deve expor aos clientes pelo menos um dos seguintes formatos de API:

1. Anthropic Messages: /v1/messages, /v1/messages/count_tokens

   • Deve encaminhar cabeçalhos de solicitação: anthropic-beta, anthropic-version

2. Bedrock InvokeModel: /invoke, /invoke-with-response-stream

   • Deve preservar campos do corpo da solicitação: anthropic_beta, anthropic_version

3. Vertex rawPredict: :rawPredict, :streamRawPredict, /count-tokens:rawPredict

   • Deve encaminhar cabeçalhos de solicitação: anthropic-beta, anthropic-version

A falha ao encaminhar cabeçalhos ou preservar campos do corpo pode resultar em funcionalidade reduzida ou incapacidade de usar recursos do Claude Code.

Cabeçalhos de solicitação

Claude Code inclui os seguintes cabeçalhos em solicitações de API:

Ambos os cabeçalhos de ID de agente são identificadores efêmeros por geração, não IDs de usuário ou dispositivo persistentes.

Claude Code também adiciona um bloco de atribuição curto ao prompt do sistema contendo a versão do cliente e uma impressão digital derivada da conversa. A API Anthropic remove este bloco antes do processamento, portanto não afeta o cache de prompt de primeira parte. Se seu gateway implementa seu próprio cache de prompt com chave no corpo completo da solicitação, defina CLAUDE_CODE_ATTRIBUTION_HEADER=0 para omiti-lo.

Configuração

Seleção de modelo

Por padrão, Claude Code usa nomes de modelo padrão para o formato de API selecionado.

Quando ANTHROPIC_BASE_URL aponta para um gateway que expõe o formato Anthropic Messages, Claude Code consulta o endpoint /v1/models do gateway na inicialização e adiciona os modelos retornados ao seletor /model. Defina CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 para ativar isso. A descoberta está desativada por padrão para que gateways apoiados por uma chave de API compartilhada não exponham todos os modelos que a chave pode acessar para cada usuário. Cada entrada descoberta é rotulada como "From gateway" e usa o campo display_name da resposta quando um é fornecido. Isso requer Claude Code v2.1.129 ou posterior.

A descoberta se aplica apenas ao formato Anthropic Messages. Ela não é executada para endpoints de passagem Bedrock ou Vertex, e não é executada quando ANTHROPIC_BASE_URL não está definido ou aponta para api.anthropic.com.

A solicitação de descoberta autentica da mesma forma que as solicitações de inferência: ela envia ANTHROPIC_AUTH_TOKEN como um token de portador, ou ANTHROPIC_API_KEY como o cabeçalho x-api-key quando nenhum token de autenticação está definido, junto com quaisquer cabeçalhos de ANTHROPIC_CUSTOM_HEADERS. Apenas modelos cujo ID começa com claude ou anthropic são adicionados ao seletor. Os resultados são armazenados em cache em ~/.claude/cache/gateway-models.json e atualizados a cada inicialização. Se a solicitação falhar ou o gateway não implementar /v1/models, o seletor volta para a lista em cache da inicialização anterior ou para a lista de modelos integrada.

Se seu gateway usa nomes de modelo que não correspondem ao filtro de descoberta, use as variáveis de ambiente documentadas em Configuração de modelo para adicioná-los manualmente.

Configuração do LiteLLM

Pré-requisitos

• Claude Code atualizado para a versão mais recente
• LiteLLM Proxy Server implantado e acessível
• Acesso aos modelos Claude através do seu provedor escolhido

Configuração básica do LiteLLM

Configure Claude Code:

Métodos de autenticação

Chave de API estática

Método mais simples usando uma chave de API fixa:

# Defina no ambiente
export ANTHROPIC_AUTH_TOKEN=sk-litellm-static-key

# Ou nas configurações do Claude Code
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-litellm-static-key"
  }
}

Este valor será enviado como o cabeçalho Authorization.

Chave de API dinâmica com auxiliar

Para chaves rotativas ou autenticação por usuário:

1. Crie um script auxiliar de chave de API:

#!/bin/bash
# ~/bin/get-litellm-key.sh

# Exemplo: Buscar chave do cofre
vault kv get -field=api_key secret/litellm/claude-code

# Exemplo: Gerar token JWT
jwt encode \
  --secret="${JWT_SECRET}" \
  --exp="+1h" \
  '{"user":"'${USER}'","team":"engineering"}'

2. Configure as configurações do Claude Code para usar o auxiliar:

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

3. Defina o intervalo de atualização de token:

# Atualizar a cada hora (3600000 ms)
export CLAUDE_CODE_API_KEY_HELPER_TTL_MS=3600000

Este valor será enviado como cabeçalhos Authorization e X-Api-Key. O apiKeyHelper tem precedência menor que ANTHROPIC_AUTH_TOKEN ou ANTHROPIC_API_KEY.

Endpoint unificado (recomendado)

Usando o endpoint de formato Anthropic do LiteLLM:

export ANTHROPIC_BASE_URL=https://litellm-server:4000

Benefícios do endpoint unificado sobre endpoints pass-through:

• Balanceamento de carga
• Fallbacks
• Suporte consistente para rastreamento de custo e rastreamento de usuário final

Endpoints pass-through específicos do provedor (alternativa)

Claude API através do LiteLLM

Usando endpoint pass-through:

export ANTHROPIC_BASE_URL=https://litellm-server:4000/anthropic

Amazon Bedrock através do LiteLLM

Usando endpoint pass-through:

export ANTHROPIC_BEDROCK_BASE_URL=https://litellm-server:4000/bedrock
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
export CLAUDE_CODE_USE_BEDROCK=1

Google Vertex AI através do LiteLLM

Usando endpoint pass-through:

export ANTHROPIC_VERTEX_BASE_URL=https://litellm-server:4000/vertex_ai/v1
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

Claude Platform on AWS através de um gateway

Rotear para um gateway que encaminha para o endpoint Claude Platform on AWS:

export ANTHROPIC_AWS_BASE_URL=https://litellm-server:4000/anthropic-aws
export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
export CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1
export CLAUDE_CODE_USE_ANTHROPIC_AWS=1

Para informações mais detalhadas, consulte a documentação do LiteLLM.

Recursos adicionais

• Documentação do LiteLLM
• Configurações do Claude Code
• Configuração de rede corporativa
• Visão geral de integrações de terceiros