Implante um gateway LLM para sua organização

Implante um produto de gateway para Claude Code: configure-o para encaminhar o que Claude Code envia, emita credenciais de desenvolvedor, distribua a configuração através de configurações gerenciadas e verifique a implantação.

Esta página orienta um administrador através da implantação de um gateway LLM para Claude Code. Ela assume que você tem um produto de gateway implantado que atende aos requisitos do gateway. A implantação ou operação de qualquer produto específico não é abordada aqui; implante o seu seguindo a documentação do seu fornecedor.

Pré-requisitos

Para concluir a implantação, você precisará de:

• Um gateway implantado em sua infraestrutura, servindo HTTPS no endereço exato que você distribuirá aos desenvolvedores, não em um endereço que redireciona para ele, e configurado para rotear nomes de modelos Claude para seu provedor
• Uma credencial de provedor para o gateway encaminhar com:
  • Para a API Anthropic: uma chave de API do Claude Console
  • Para um provedor de nuvem: credenciais de nuvem com acesso ao modelo. Consulte os pré-requisitos na página Amazon Bedrock, Google Cloud's Agent Platform ou Microsoft Foundry
• Uma maneira de entregar arquivos de configurações para máquinas de desenvolvedores, como MDM ou gerenciamento de configuração
  • Se você ainda não tiver uma, como as configurações chegam aos dispositivos compara as opções

Requisitos do gateway

Qualquer que seja o produto que fornece o gateway, ele deve:

• Aceitar um formato de API suportado: um dos formatos na tabela de formatos de API. As etapas de implantação abaixo assumem a API de Mensagens Anthropic em POST /v1/messages, que a maioria dos gateways serve
• Transmitir respostas: passar eventos enviados pelo servidor conforme chegam, incluindo pings de keep-alive, em vez de armazenar em buffer a resposta inteira; streaming cobre o que o buffering ou pings removidos quebram
• Rotear nomes de modelos Claude: mapear cada nome que os desenvolvedores usam para um modelo upstream. Claude Code envia um nome de modelo como claude-sonnet-4-6 em cada solicitação; na maioria dos produtos de gateway o mapeamento é uma lista de modelos ou tabela de roteamento na própria configuração do gateway
• Encaminhar cabeçalhos e corpo sem alterações: passar anthropic-beta, anthropic-version e o corpo da solicitação em ambas as direções; a tabela de passagem de recursos mapeia cada um para o recurso que quebra sem ele
• Retornar erros upstream não modificados: a recuperação automática do Claude Code corresponde à redação do erro, portanto envolver erros no próprio envelope do gateway quebra isso, a menos que a mensagem do envelope carregue um dos tokens capability_rejected: que um gateway de aplicativos Claude substitui pela redação de erro dos provedores de nuvem
• Isentar o caminho da inspeção WAF do corpo da solicitação: os prompts do Claude Code carregam código-fonte e tags de estilo XML que correspondem às regras do corpo de cross-site-scripting; um WAF na frente do gateway retorna 403 em sessões reais enquanto solicitações de teste curtas passam

Opcionalmente, sirva GET /v1/models para que Claude Code possa preencher o seletor de modelo do seu gateway com descoberta de modelo.

Etapas de implantação

A implantação leva cinco etapas, cada uma com um ponto de verificação:

1. Confirme que o gateway roteia seus modelos
2. Emita uma credencial para cada desenvolvedor
3. Teste Claude Code contra o gateway
4. Distribua a URL base e as credenciais
5. Verifique a partir de uma máquina de desenvolvedor

As etapas envolvem três credenciais diferentes, e os pontos de verificação as nomeiam por espaço reservado para que você possa dizer qual é a culpada quando algo falha:

Confirme que o gateway roteia seus modelos

Seu gateway já deve estar configurado com sua credencial de provedor, ouvindo em sua URL base e encaminhando solicitações para a API do seu provedor. Teste que o caminho funciona de ponta a ponta com uma solicitação mínima, substituindo dois valores de sua implantação:

• <gateway-key> é qualquer credencial que permite chamar o gateway agora: uma chave administrativa, uma chave de teste ou sua própria chave de desenvolvedor se você já tiver emitido uma. Nem todo produto de gateway tem uma credencial de administrador separada; se o seu não tiver, emita uma chave de desenvolvedor para você em Emita credenciais de desenvolvedor primeiro
• model é um nome de modelo Claude que seu gateway está configurado para rotear. O exemplo usa claude-sonnet-4-6; substitua um nome que você configurou

curl -X POST "https://llm-gateway.example.com/v1/messages" \
-H "Authorization: Bearer <gateway-key>" \
-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 "https://llm-gateway.example.com/v1/messages" `
-Headers @{ "Authorization" = "Bearer <gateway-key>"; "anthropic-version" = "2023-06-01" } `
-ContentType "application/json" `
-Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

Ponto de verificação: um 200 com um campo content significa que o gateway alcançou o provedor com esse nome de modelo. Um 404 significa que esse nome não é roteado no gateway; um 401 do provedor significa que a credencial do provedor do gateway está errada.

Repita a solicitação uma vez por nome de modelo Claude na configuração de roteamento do seu gateway. Um nome que o gateway não roteia retorna 404 para qualquer desenvolvedor que o selecione, portanto teste cada nome antes da implantação.

Emita credenciais de desenvolvedor

Cada desenvolvedor precisa de sua própria chave de gateway para autenticar. Crie uma credencial por desenvolvedor no gateway, seguindo a documentação de gerenciamento de credenciais do seu produto.

Confirme que uma chave recém-emitida funciona contra o gateway com a mesma solicitação que Confirme que o gateway roteia seus modelos, substituindo <gateway-key> pela nova <developer-key>:

curl -X POST "https://llm-gateway.example.com/v1/messages" \
-H "Authorization: Bearer <developer-key>" \
-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 "https://llm-gateway.example.com/v1/messages" `
-Headers @{ "Authorization" = "Bearer <developer-key>"; "anthropic-version" = "2023-06-01" } `
-ContentType "application/json" `
-Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

Ponto de verificação: um 200 com um campo content significa que a chave do desenvolvedor alcança o gateway e o gateway a encaminha. Um 401 aqui, quando a etapa anterior foi bem-sucedida, significa que a chave do desenvolvedor está errada ou ainda não entrou em vigor no gateway.

Emitir uma chave por desenvolvedor em vez de uma chave compartilhada é o que torna a atribuição de uso por desenvolvedor e o offboarding individual funcionarem. A variável de ambiente que contém a chave depende de qual cabeçalho o gateway lê. Para um gateway que verifica credenciais no cabeçalho Authorization: Bearer, os desenvolvedores definem sua chave em ANTHROPIC_AUTH_TOKEN. Para um gateway que lê chaves do cabeçalho x-api-key, os desenvolvedores definem ANTHROPIC_API_KEY em vez disso; a tabela de credenciais cobre o mapeamento.

Teste Claude Code contra o gateway

Execute Claude Code através do gateway você mesmo antes de distribuir qualquer coisa, usando a mesma configuração que a implantação entregará em toda a frota. Digite-os diretamente em um terminal, não em um arquivo .env ou arquivo de configurações; eles duram apenas para esta sessão de terminal, portanto fechá-la retorna sua máquina à sua configuração normal. Use ANTHROPIC_API_KEY em vez de ANTHROPIC_AUTH_TOKEN se seu gateway lê o cabeçalho x-api-key:

export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
export ANTHROPIC_AUTH_TOKEN="<developer-key>"

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

Em seguida, envie um prompt único através do gateway:

claude -p "Reply with one word: connected"

Ponto de verificação: o prompt retorna uma resposta e a solicitação aparece no log do gateway como um POST para o caminho /v1/messages com status 200. Claude Code anexa uma string de consulta como ?beta=true, portanto corresponda no caminho, não na URL completa. Duas mensagens de falha apontam em direções diferentes:

• Not logged in: verifique o log do gateway para distinguir as duas causas. Se estiver vazio, nenhuma credencial alcançou a sessão e nenhuma solicitação saiu da máquina; re-execute as exportações no shell que você está testando. Se mostrar uma solicitação rejeitada com x-api-key no corpo 401, o gateway espera chaves nesse cabeçalho em vez disso; mude para ANTHROPIC_API_KEY
• Failed to authenticate. API Error: 401 significa que uma credencial foi enviada e rejeitada, e o log do gateway diz onde: um 401 nomeando api.anthropic.com ou o endpoint do seu provedor significa que o gateway alcançou o upstream mas sua credencial de provedor foi rejeitada, portanto a chave do desenvolvedor funcionou e a credencial do provedor que o gateway detém está errada ou é um espaço reservado

Uma URL base errada ou inacessível produz um sintoma diferente: Claude Code tenta novamente a conexão com backoff e pode ficar sem saída por vários minutos antes de relatar um erro. Se o comando parecer travar, verifique o log do gateway em vez de esperar; nenhuma solicitação chegando significa que ANTHROPIC_BASE_URL não aponta para o gateway.

Distribua a configuração

Cada máquina de desenvolvedor precisa do endereço do gateway e de uma credencial. Você pode distribuí-los centralmente através de configurações gerenciadas, para que os desenvolvedores não configurem nada, ou entregue aos desenvolvedores os valores para definir eles mesmos.

O que distribuir

O mesmo conjunto de variáveis se aplica qualquer que seja o caminho que você escolha. A maioria das implantações só precisa de ANTHROPIC_BASE_URL e uma credencial; inclua as linhas condicionais quando sua configuração de gateway as exigir.

Distribua através de configurações gerenciadas

Entregue as variáveis através do bloco env de um arquivo de configurações gerenciadas, enviado por MDM, política de registro ou gerenciamento de configuração:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com"
  },
  "apiKeyHelper": "/usr/local/bin/get-gateway-key"
}

Adicione as variáveis condicionais da tabela ao mesmo bloco env. Um ANTHROPIC_BASE_URL gerenciado é imposto e não pode ser substituído pela exportação de shell de um desenvolvedor, já que Claude Code o aplica sobre o ambiente do processo e configurações de precedência inferior.

Não inclua forceLoginMethod ou forceLoginOrgUUID em configurações gerenciadas junto com uma credencial de gateway. Qualquer chave bloqueia ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN e apiKeyHelper na inicialização, e os desenvolvedores não podem prosseguir. Eles veem This machine's managed settings require a first-party login, ou Administrator policy requires a Cloud gateway sign-in sob um valor "gateway".

A entrega de configurações gerenciadas pelo servidor requer uma conexão direta com api.anthropic.com, portanto não alcança sessões roteadas por gateway. As implantações de gateway usam este caminho de configurações gerenciadas baseado em arquivo, que impõe as mesmas chaves.

Para a credencial, distribua um comando apiKeyHelper no arquivo de configurações gerenciadas conforme mostrado acima; o comando autentica seu armazenamento de segredos como o desenvolvedor local, portanto cada máquina recebe sua própria chave. Alternativamente, entregue a cada desenvolvedor sua chave através do seu processo de segredos existente e peça-lhes para definir ANTHROPIC_AUTH_TOKEN eles mesmos.

Alguns ambientes precisam de entrega separada:

• O aplicativo de desktop lê o roteamento do gateway apenas de sua configuração de inferência de terceiros, não de configurações gerenciadas; implante esse arquivo através de MDM junto com configurações gerenciadas para que as sessões de desktop também roteiem através do gateway. Consulte a documentação de configuração de terceiros do desktop e a documentação de gateway do desktop
• Os executores de CI precisam de ANTHROPIC_BASE_URL e a credencial definida no ambiente do executor
• WSL em máquinas Windows gerenciadas lê as configurações gerenciadas do Windows apenas quando wslInheritsWindowsSettings é true

Entregue aos desenvolvedores os valores para definir eles mesmos

Se você não tiver distribuição de configurações gerenciadas em vigor, envie a cada desenvolvedor o que ele precisa para seguir a página de conexão:

• A URL do gateway
• Sua credencial pessoal
• Qual variável colocar a credencial em: ANTHROPIC_AUTH_TOKEN para um gateway de token portador, ou ANTHROPIC_API_KEY para um gateway x-api-key. Dizer aos desenvolvedores qual economiza o trial-and-error descrito na página de conexão
• Quaisquer variáveis condicionais da tabela O que distribuir, com seus valores

A página de conexão orienta os desenvolvedores através da definição de cada uma.

Ponto de verificação: em uma máquina de desenvolvedor, claude inicia uma sessão sem mostrar a tela de login, já que a credencial distribuída satisfaz a autenticação. Em seguida, execute /status e abra a aba Status: a linha Anthropic base URL mostra o endereço do gateway, e para distribuição gerenciada a linha Setting sources inclui configurações gerenciadas. Uma tela de login, ou uma linha Anthropic base URL ausente, significa que a configuração não alcançou a máquina.

Verifique a implantação

Confirme que tudo funciona a partir de uma máquina de desenvolvedor, não do host do gateway, para que o teste cubra o caminho de rede que os desenvolvedores usam. Envie uma solicitação de streaming, que verifica o endpoint, passagem de streaming e roteamento de modelo de uma vez:

curl -N -X POST "https://llm-gateway.example.com/v1/messages" \
-H "Authorization: Bearer <developer-key>" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model": "claude-sonnet-4-6", "max_tokens": 16, "stream": true, "messages": [{"role": "user", "content": "count to 3"}]}'

$body = '{"model": "claude-sonnet-4-6", "max_tokens": 16, "stream": true, "messages": [{"role": "user", "content": "count to 3"}]}'
$body | curl.exe -N -X POST "https://llm-gateway.example.com/v1/messages" `
-H "Authorization: Bearer <developer-key>" `
-H "anthropic-version: 2023-06-01" `
-H "content-type: application/json" `
--data-binary '@-'

Você deve ver linhas data: chegarem incrementalmente. A resposta inteira chegando de uma vez após uma pausa significa que o gateway está armazenando em buffer, o que paralisa Claude Code; um 404 significa que o nome do modelo não é roteado. Repita por nome de modelo.

Em seguida, inicie claude e envie uma mensagem. Cada sintoma nesta etapa tem uma causa:

• Um prompt de login significa uma lacuna de credencial. Execute /status e abra a aba Status: quando a linha Setting sources não inclui configurações gerenciadas, a distribuição não alcançou a máquina; quando inclui, a credencial do desenvolvedor não foi entregue, portanto defina ANTHROPIC_AUTH_TOKEN ou o apiKeyHelper
• Erros Failed to authenticate significam que o gateway está rejeitando solicitações; seu log diz qual credencial falhou. Uma rejeição que o gateway registra em si nomeia a chave do desenvolvedor, enquanto um 401 de api.anthropic.com ou do endpoint do seu provedor significa que a credencial do provedor que o gateway detém foi rejeitada
• Um prompt de aprovação única para a chave é esperado no primeiro uso quando o gateway espera chaves no cabeçalho x-api-key, definido como ANTHROPIC_API_KEY. Com ANTHROPIC_AUTH_TOKEN, nenhum prompt aparece e a variável assume silenciosamente; um login claude.ai previamente salvo está inativo para essa sessão

Se sua organização usa fast mode, execute /fast aqui também: a verificação de disponibilidade chama api.anthropic.com diretamente em vez de seguir a URL base do gateway, portanto uma sessão roteada por gateway pode relatar fast mode como indisponível ou desabilitado mesmo que a inferência funcione. Use fast mode atrás de proxies e gateways LLM mapeia cada mensagem para a variável que a restaura, distribuída com o resto da configuração.

Finalmente, verifique os logs do gateway para a mensagem que você enviou: a credencial identifica o desenvolvedor, e o cabeçalho x-claude-code-session-id agrupa solicitações por sessão. Se os recursos falharem com os sintomas de solução de problemas, o gateway está removendo cabeçalhos ou reescrevendo erros; consulte os requisitos do gateway acima.

Mantenha o gateway

Após a implantação, três tipos de mudança alcançam o gateway ao longo do tempo. Cada um tem um sintoma a observar e uma ação a tomar.

Ao dimensionar limites de taxa por chave, leve em conta o cliente tentando novamente falhas transitórias, incluindo respostas 429, até 10 vezes com backoff, honrando Retry-After. Mantenha a guia de compatibilidade como a referência para o que cada lançamento do Claude Code envia.

Planejar atualizações de versão do Claude Code

Alguns comportamentos do Claude Code são incorporados à versão instalada em vez de serem definidos no seu gateway, portanto, mover desenvolvedores para um novo lançamento pode alterar o comportamento em toda a sua implantação mesmo quando a configuração do gateway não foi alterada. Para controlar quando isso acontece, fixe os desenvolvedores a uma versão testada com requiredMaximumVersion, ou com DISABLE_UPDATES se você distribuir Claude Code através do seu próprio canal. Antes de aumentar a fixação, leia a entrada do changelog do novo lançamento e teste-o contra o gateway.

Quando você testa um lançamento, novos cabeçalhos ou campos de solicitação que o gateway rejeita aparecem como os erros 400 descritos em Mantenha o gateway. A tabela abaixo cobre mudanças dependentes de versão que não produzem um erro, com a configuração que mantém cada uma constante entre atualizações.

Recursos relacionados

• Conectar Claude Code a um gateway LLM: as etapas de configuração voltadas para o desenvolvedor, com configuração por superfície e uma tabela de solução de problemas que você pode entregar aos desenvolvedores
• Guia de compatibilidade do gateway: a referência para operadores de gateway, cobrindo endpoints, cabeçalhos para encaminhar e a tabela de passagem de recursos
• Qual valor Claude Code usa: como configurações gerenciadas, de projeto e de usuário se combinam
• Mecanismos de entrega: onde o arquivo gerenciado vai em cada plataforma
• Configure Claude Code para sua organização: a implantação mais ampla da qual este gateway é uma parte, incluindo imposição de política, visibilidade de uso e tratamento de dados