2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.3> Use this file to discover all available pages before exploring further.
4 4
5# Configuração do gateway LLM5# Gateways LLM
6 6
7> 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.7> Rotear Claude Code através de um gateway LLM para autenticação centralizada, rastreamento de uso e controles de custo. Abrange conectar Claude Code a um gateway, implantar um para sua organização, o que Claude Code envia a um gateway e como gateways interagem com assinaturas claude.ai.
8 8
9Gateways LLM fornecem uma camada proxy centralizada entre Claude Code e provedores de modelos, frequentemente fornecendo:9Um gateway LLM é um proxy que sua organização executa entre Claude Code e um provedor de modelo. Claude Code envia tráfego de API para o gateway, e o gateway o encaminha para o provedor usando uma credencial que sua organização controla.
10 10
11* **Autenticação centralizada** - Ponto único para gerenciamento de chaves de API11Esta página aborda:
12* **Rastreamento de uso** - Monitore o uso em equipes e projetos
13* **Controles de custo** - Implemente orçamentos e limites de taxa
14* **Registro de auditoria** - Rastreie todas as interações de modelo para conformidade
15* **Roteamento de modelo** - Alterne entre provedores sem alterações de código
16 12
17Esta 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](https://support.claude.com/pt/articles/12622667-enterprise-configuration). O aplicativo Claude Desktop também pode ser executado em um gateway auto-hospedado através da [visualização de pesquisa Cowork on 3P](https://claude.com/docs/cowork/3p/gateway), que usa suas próprias chaves de configuração.13* [O que um gateway fornece](#what-a-gateway-provides)
18 14* [Como roteamento e credenciais funcionam](#how-a-gateway-works)
19<h2 id="gateway-requirements">15* [Os passos para implantar um](#roll-out-a-gateway)
20 Requisitos do gateway16* [Como gateways interagem com assinaturas claude.ai](#subscriptions-and-gateways)
21</h2>17* [O que é configurado separadamente do gateway](#configure-separately-from-the-gateway)
22
23Para que um gateway LLM funcione com Claude Code, ele deve atender aos seguintes requisitos:
24
25**Formato de API**
26
27O gateway deve expor aos clientes pelo menos um dos seguintes formatos de API:
28
291. **Anthropic Messages**: `/v1/messages`, `/v1/messages/count_tokens`
30 * Deve encaminhar cabeçalhos de solicitação: `anthropic-beta`, `anthropic-version`
31
322. **Bedrock InvokeModel**: `/invoke`, `/invoke-with-response-stream`
33 * Deve preservar campos do corpo da solicitação: `anthropic_beta`, `anthropic_version`
34
353. **Vertex rawPredict**: `:rawPredict`, `:streamRawPredict`, `/count-tokens:rawPredict`
36 * Deve encaminhar cabeçalhos de solicitação: `anthropic-beta`, `anthropic-version`
37
38A falha ao encaminhar cabeçalhos ou preservar campos do corpo pode resultar em funcionalidade reduzida ou incapacidade de usar recursos do Claude Code.
39 18
40<Note>19<Note>
41 Claude Code determina quais recursos ativar com base no formato da API. Ao usar o formato Anthropic Messages com Bedrock ou Vertex, você pode precisar definir a variável de ambiente `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`.20 - Se você é um desenvolvedor conectando a um gateway existente: [conectar Claude Code ao seu gateway](/pt/llm-gateway-connect)
21 - Se você é um administrador implantando um gateway para sua organização: [implantar e distribuir um gateway](/pt/llm-gateway-rollout)
22 - Se você está configurando um produto gateway: a [referência de protocolo de gateway](/pt/llm-gateway-protocol)
42</Note>23</Note>
43 24
44**Cabeçalhos de solicitação**25<h2 id="what-a-gateway-provides">
45 26 O que um gateway fornece
46Claude Code inclui os seguintes cabeçalhos em solicitações de API:
47
48| Cabeçalho | Descrição |
49| :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
50| `X-Claude-Code-Session-Id` | Um identificador único para a sessão atual do Claude Code. Proxies podem usar isso para agregar todas as solicitações de API de uma única sessão sem analisar o corpo da solicitação. |
51| `X-Claude-Code-Agent-Id` | Identificador do subagente ou colega de trabalho que emitiu a solicitação. Seu proxy pode usar isso para atribuir o custo da API a subagentes paralelos individuais dentro de uma sessão, sem analisar o corpo da solicitação. Presente apenas para solicitações feitas por um subagente ou colega de trabalho em processo. |
52| `X-Claude-Code-Parent-Agent-Id` | Identificador do agente que gerou o agente que faz a solicitação. Use isso com `X-Claude-Code-Agent-Id` para atribuir custos de API entre agentes aninhados em seu proxy. Presente apenas quando o agente solicitante foi ele próprio gerado por outro agente. |
53
54Ambos os cabeçalhos de ID de agente são identificadores efêmeros por geração, não IDs de usuário ou dispositivo persistentes.
55
56Claude 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`](/pt/env-vars) para omiti-lo.
57
58<h2 id="configuration">
59 Configuração
60</h2>27</h2>
61 28
62<h3 id="model-selection">29Um gateway oferece à sua organização um único lugar para gerenciar:
63 Seleção de modelo
64</h3>
65
66Por padrão, Claude Code usa nomes de modelo padrão para o formato de API selecionado.
67 30
68Quando `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.31* **Credenciais**: a chave do provedor fica no lado do servidor; desenvolvedores mantêm credenciais de gateway em vez disso
32* **Rastreamento de uso**: atribua uso por desenvolvedor ou equipe, independentemente de qual provedor atende a solicitação
33* **Controles de custo**: aplique orçamentos e limites de taxa em um único lugar
34* **Registro de auditoria**: registre cada solicitação de modelo para conformidade
35* **Alternância de provedor**: altere o provedor na configuração do gateway, sem tocar nas máquinas dos desenvolvedores
69 36
70A 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`.37Todos esses, exceto alternância de provedor, se aplicam se o upstream é a API da Anthropic ou um [provedor de nuvem](/pt/third-party-integrations).
71 38
72A 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.39O tradeoff é que o gateway se torna infraestrutura que sua organização opera. Claude Code adiciona capacidades com cada lançamento, e um gateway que não as encaminha quebra os recursos correspondentes, então o produto gateway precisa ser mantido atualizado conforme Claude Code evolui. A [referência de protocolo de gateway](/pt/llm-gateway-protocol) aborda o que encaminhar.
73 40
74Se 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](/pt/model-config) para adicioná-los manualmente.41<h2 id="how-a-gateway-works">
75 42 Como um gateway funciona
76<h2 id="litellm-configuration">
77 Configuração do LiteLLM
78</h2>43</h2>
79 44
80<Warning>45Por padrão, Claude Code envia solicitações diretamente para a API da Anthropic em `api.anthropic.com`. Para rotear através de um gateway, defina `ANTHROPIC_BASE_URL` para o endereço do gateway; Claude Code envia as mesmas solicitações lá em vez disso. O gateway autentica o desenvolvedor, anexa a credencial do provedor de sua organização e encaminha cada solicitação para qualquer provedor para o qual esteja configurado.
81 As versões PyPI do LiteLLM 1.82.7 e 1.82.8 foram comprometidas com malware que rouba credenciais. Não instale essas versões. Se você já as instalou:
82
83 * Remova o pacote
84 * Rotacione todas as credenciais nos sistemas afetados
85 * Siga as etapas de remediação em [BerriAI/litellm#24518](https://github.com/BerriAI/litellm/issues/24518)
86
87 LiteLLM é um serviço proxy de terceiros. Anthropic não endossa, mantém ou audita a segurança ou funcionalidade do LiteLLM. Este guia é fornecido para fins informativos e pode ficar desatualizado. Use por sua conta e risco.
88</Warning>
89
90<h3 id="prerequisites">
91 Pré-requisitos
92</h3>
93
94* Claude Code atualizado para a versão mais recente
95* LiteLLM Proxy Server implantado e acessível
96* Acesso aos modelos Claude através do seu provedor escolhido
97
98<h3 id="basic-litellm-setup">
99 Configuração básica do LiteLLM
100</h3>
101
102**Configure Claude Code**:
103
104<h4 id="authentication-methods">
105 Métodos de autenticação
106</h4>
107 46
108<h5 id="static-api-key">47`ANTHROPIC_BASE_URL` é a variável de endereço para a maioria dos gateways. Um gateway que fronts um provedor de nuvem específico, como Bedrock, Vertex, Foundry ou Claude Platform on AWS, usa a variável de URL base desse provedor em vez disso; [Formatos de API](/pt/llm-gateway-protocol#api-formats) lista qual variável vai com cada configuração.
109 Chave de API estática
110</h5>
111 48
112Método mais simples usando uma chave de API fixa:49<Frame>
50 <img src="https://mintcdn.com/claude-code/zIcIE_SQv4Z0Zbhc/images/llm-gateway-flow.svg?fit=max&auto=format&n=zIcIE_SQv4Z0Zbhc&q=85&s=490607d033d235694efb49a73a5b9e4b" alt="Diagrama mostrando Claude Code roteando através de um gateway LLM. Em uma zona de máquinas de desenvolvedor, o CLI Claude Code, extensão VS Code e clientes SDK de CI ou Agent enviam solicitações para o gateway, com a variável de URL base para o formato de API do gateway apontando para ele e cada desenvolvedor mantendo uma credencial por desenvolvedor, e o aplicativo desktop alcança o mesmo gateway através de configuração distribuída pela organização. Em uma zona rotulada sua infraestrutura, o gateway LLM lida com autenticação, rastreamento de uso, orçamentos e roteamento, e encaminha solicitações com a credencial de sua organização. Em uma zona de provedores de modelo, uma seta sólida leva ao provedor que você configura, mostrado como a API Anthropic, e setas tracejadas levam a outras opções de provedor, ilustradas com Amazon Bedrock, Google Vertex AI e Microsoft Foundry como exemplos." width="780" height="322" data-path="images/llm-gateway-flow.svg" />
51</Frame>
113 52
114```bash theme={null}53Dois tipos de credencial estão envolvidos:
115# Defina no ambiente
116export ANTHROPIC_AUTH_TOKEN=sk-litellm-static-key
117 54
118# Ou nas configurações do Claude Code55* **Credenciais de desenvolvedor**: cada desenvolvedor mantém a sua própria, emitida pelo gateway. Ela os autentica no gateway e os identifica no rastreamento de uso
119{56* **Credencial do provedor**: o gateway mantém uma credencial para sua conta de provedor, compartilhada por todo o tráfego encaminhado. Você não provisiona chaves de provedor por desenvolvedor
120 "env": {
121 "ANTHROPIC_AUTH_TOKEN": "sk-litellm-static-key"
122 }
123}
124```
125 57
126Este valor será enviado como o cabeçalho `Authorization`.58O gateway encaminha cada solicitação para o provedor que você configura, como a API Anthropic, [Amazon Bedrock](/pt/amazon-bedrock), [Google Vertex AI](/pt/google-vertex-ai), [Microsoft Foundry](/pt/microsoft-foundry) ou [Claude Platform on AWS](/pt/claude-platform-on-aws). Como Claude Code fala apenas com o gateway, a escolha do provedor é a configuração do gateway, não a do cliente.
127 59
128<h5 id="dynamic-api-key-with-helper">60<h2 id="roll-out-a-gateway">
129 Chave de API dinâmica com auxiliar61 Implantar um gateway
130</h5>62</h2>
131
132Para chaves rotativas ou autenticação por usuário:
133
1341. Crie um script auxiliar de chave de API:
135
136```bash theme={null}
137#!/bin/bash
138# ~/bin/get-litellm-key.sh
139
140# Exemplo: Buscar chave do cofre
141vault kv get -field=api_key secret/litellm/claude-code
142
143# Exemplo: Gerar token JWT
144jwt encode \
145 --secret="${JWT_SECRET}" \
146 --exp="+1h" \
147 '{"user":"'${USER}'","team":"engineering"}'
148```
149
1502. Configure as configurações do Claude Code para usar o auxiliar:
151
152```json theme={null}
153{
154 "apiKeyHelper": "~/bin/get-litellm-key.sh"
155}
156```
157
1583. Defina o intervalo de atualização de token:
159
160```bash theme={null}
161# Atualizar a cada hora (3600000 ms)
162export CLAUDE_CODE_API_KEY_HELPER_TTL_MS=3600000
163```
164
165Este 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`.
166
167<h4 id="unified-endpoint-recommended">
168 Endpoint unificado (recomendado)
169</h4>
170
171Usando o [endpoint de formato Anthropic](https://docs.litellm.ai/docs/anthropic_unified) do LiteLLM:
172
173```bash theme={null}
174export ANTHROPIC_BASE_URL=https://litellm-server:4000
175```
176
177**Benefícios do endpoint unificado sobre endpoints pass-through:**
178
179* Balanceamento de carga
180* Fallbacks
181* Suporte consistente para rastreamento de custo e rastreamento de usuário final
182
183<h4 id="provider-specific-pass-through-endpoints-alternative">
184 Endpoints pass-through específicos do provedor (alternativa)
185</h4>
186
187<h5 id="claude-api-through-litellm">
188 Claude API através do LiteLLM
189</h5>
190
191Usando [endpoint pass-through](https://docs.litellm.ai/docs/pass_through/anthropic_completion):
192 63
193```bash theme={null}64Quando você estiver pronto para implantar um gateway LLM para sua organização, a sequência é a mesma qualquer que seja o produto gateway que você escolha:
194export ANTHROPIC_BASE_URL=https://litellm-server:4000/anthropic
195```
196 65
197<h5 id="amazon-bedrock-through-litellm">661. Implante o gateway e dê a ele sua credencial de provedor, para que ele possa autenticar as solicitações que encaminha.
198 Amazon Bedrock através do LiteLLM672. Emita a cada desenvolvedor uma credencial de gateway, para que o uso seja atribuído ao desenvolvedor e o offboarding revogue uma credencial.
199</h5>683. Distribua a configuração através de um [arquivo de configurações gerenciadas](/pt/settings#settings-files) e sua ferramenta de segredos, para que cada máquina receba a URL base e uma credencial. Quando ambos forem distribuídos, os desenvolvedores não configuram nada. Se você não tiver distribuição de configurações em vigor, os desenvolvedores seguem a [página de conexão](/pt/llm-gateway-connect) para definir as variáveis eles mesmos.
694. Faça cada desenvolvedor [verificar a configuração no Claude Code](/pt/llm-gateway-connect#check-for-an-existing-configuration), para que problemas de distribuição apareçam antes de dependerem do gateway.
200 70
201Usando [endpoint pass-through](https://docs.litellm.ai/docs/pass_through/bedrock):71[Implantar um gateway LLM para sua organização](/pt/llm-gateway-rollout) percorre cada passo e mostra os arquivos de configuração para distribuir em cada um. O gateway é uma parte da configuração da organização; para aplicação de política, visibilidade de uso e decisões de tratamento de dados, veja [Configurar Claude Code para sua organização](/pt/admin-setup).
202 72
203```bash theme={null}73<h2 id="third-party-gateways">
204export ANTHROPIC_BEDROCK_BASE_URL=https://litellm-server:4000/bedrock74 Gateways de terceiros
205export CLAUDE_CODE_SKIP_BEDROCK_AUTH=175</h2>
206export CLAUDE_CODE_USE_BEDROCK=1
207```
208 76
209<h5 id="google-vertex-ai-through-litellm">77Qualquer gateway que exponha um [formato de API suportado](/pt/llm-gateway-protocol#api-formats) funciona. Anthropic não endossa, mantém ou audita produtos gateway de terceiros. Implante-os seguindo sua própria documentação, então complete o lado Claude Code do rollout com os [passos de rollout](/pt/llm-gateway-rollout).
210 Google Vertex AI através do LiteLLM
211</h5>
212 78
213Usando [endpoint pass-through](https://docs.litellm.ai/docs/pass_through/vertex_ai):79<h2 id="subscriptions-and-gateways">
80 Assinaturas e gateways
81</h2>
214 82
215```bash theme={null}83Enquanto uma [variável de credencial de gateway](/pt/llm-gateway-connect#set-the-credential-variable) ou `apiKeyHelper` está ativa, a assinatura claude.ai de um desenvolvedor não é usada: a credencial substitui o login da assinatura para essa sessão, e os limites de uso da assinatura não se aplicam. Esse tráfego é cobrado por token para quem quer que possua a credencial que o gateway encaminha, como sua conta Anthropic Console da organização, ou sua conta Bedrock, Vertex ou Foundry quando o gateway roteia para lá.
216export ANTHROPIC_VERTEX_BASE_URL=https://litellm-server:4000/vertex_ai/v1
217export ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
218export CLAUDE_CODE_SKIP_VERTEX_AUTH=1
219export CLAUDE_CODE_USE_VERTEX=1
220export CLOUD_ML_REGION=us-east5
221```
222 84
223<h5 id="claude-platform-on-aws-through-a-gateway">85Definir apenas `ANTHROPIC_BASE_URL`, sem uma credencial de gateway, não substitui a assinatura. As solicitações ainda roteiam através do gateway, mas um login claude.ai salvo permanece como a credencial ativa, então seus limites de uso e cobrança se aplicam. Gateways que passam esse tráfego para Anthropic devem encaminhar a capacidade OAuth em `anthropic-beta`; veja a [referência de cabeçalhos de solicitação](/pt/llm-gateway-protocol#request-headers).
224 Claude Platform on AWS através de um gateway
225</h5>
226 86
227Rotear para um gateway que encaminha para o endpoint [Claude Platform on AWS](/pt/claude-platform-on-aws):87<h2 id="configure-separately-from-the-gateway">
88 Configurar separadamente do gateway
89</h2>
228 90
229```bash theme={null}91Um gateway determina para onde as solicitações de API de modelo são enviadas. Seleção de modelo, o resto do tráfego de rede do Claude Code e proxies corporativos são configurados separadamente:
230export ANTHROPIC_AWS_BASE_URL=https://litellm-server:4000/anthropic-aws
231export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
232export CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1
233export CLAUDE_CODE_USE_ANTHROPIC_AWS=1
234```
235 92
236Para informações mais detalhadas, consulte a [documentação do LiteLLM](https://docs.litellm.ai/).93* **Seleção de modelo**: a URL base decide para onde as solicitações vão, não qual modelo as responde. Escolha o modelo com o comando `/model` ou as variáveis de ambiente de modelo; veja [como definir seu modelo](/pt/model-config#setting-your-model)
94* **Tráfego do lado do cliente**: verificações de versão e telemetria de cliente opcional, ambas desabilitadas com [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/pt/env-vars), e tráfego de login quando um login claude.ai ou Console está em uso, vão para os endpoints de atualização e autenticação da Anthropic em vez do gateway. Veja [requisitos de acesso à rede](/pt/network-config#network-access-requirements) para os domínios
95* **Proxies corporativos**: um proxy definido com `HTTPS_PROXY` fica entre Claude Code e cada servidor com o qual ele fala, incluindo o gateway. Se sua rede requer um proxy, configure ambos; veja [configuração de proxy](/pt/network-config#proxy-configuration)
237 96
238<h2 id="additional-resources">97<h2 id="related-pages">
239 Recursos adicionais98 Páginas relacionadas
240</h2>99</h2>
241 100
242* [Documentação do LiteLLM](https://docs.litellm.ai/)101* [Conectar Claude Code a um gateway LLM](/pt/llm-gateway-connect): defina a URL base e credencial em sua própria máquina, com configuração por superfície e uma tabela de solução de problemas
243* [Configurações do Claude Code](/pt/settings)102* [Implantar um gateway LLM para sua organização](/pt/llm-gateway-rollout): a lista de verificação do administrador para implantar um gateway, emitir credenciais de desenvolvedor e distribuir configurações gerenciadas
244* [Configuração de rede corporativa](/pt/network-config)103* [Referência de protocolo de gateway](/pt/llm-gateway-protocol): o que Claude Code envia a um gateway, para operadores configurando um, abrangendo endpoints, cabeçalhos para encaminhar e passagem de recursos
245* [Visão geral de integrações de terceiros](/pt/third-party-integrations)104* [Configurar Claude Code para sua organização](/pt/admin-setup): as decisões de rollout mais amplas das quais um gateway é uma parte, incluindo aplicação de política e visibilidade de uso
