1> ## Documentation Index
2> 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.
4
5# Conectar Claude Code a um gateway LLM
6
7> 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 para o CLI, VS Code, GitHub Actions e o Agent SDK, depois verifique a conexão e corrija erros do gateway.
8
9Um [gateway LLM](/pt/llm-gateway) é 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.
10
11Esta 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ê](#check-for-an-existing-configuration) e [configurá-lo você mesmo](#configure-claude-code-yourself) quando não tiverem.
12
13<Note>
14 * Para implantar um gateway para sua organização, consulte [Implementar um gateway LLM](/pt/llm-gateway-rollout)
15 * Para saber o que Claude Code envia para um gateway, consulte a [referência do protocolo do gateway](/pt/llm-gateway-protocol)
16</Note>
17
18<h2 id="check-for-an-existing-configuration">
19 Verificar uma configuração existente
20</h2>
21
22Os administradores podem distribuir o endereço do gateway e a credencial através de [configurações gerenciadas](/pt/settings#settings-files), gerenciamento de dispositivos ou um [`apiKeyHelper`](#rotate-credentials-with-apikeyhelper), para que Claude Code os pegue na inicialização sem nada para você configurar. Para verificar se sua organização já fez isso:
23
24<Steps>
25 <Step title="Iniciar Claude Code">
26 Execute `claude`. Se ele abrir para a tela de login em vez de uma sessão, nenhuma credencial de gateway foi distribuída; [configure-a você mesmo](#configure-claude-code-yourself) abaixo.
27 </Step>
28
29 <Step title="Verificar a aba Status">
30 Se Claude Code iniciou uma sessão sem mostrar a tela de login, execute `/status`, abra a aba **Status** e verifique duas linhas:
31
32 * `Anthropic base URL`: esta linha aparece apenas quando um endereço de gateway está definido. Se não estiver lá, Claude Code não está apontado para o gateway; [configure-o você mesmo](#configure-claude-code-yourself) abaixo.
33 * `Auth token` ou `API key`: uma linha nomeando `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_API_KEY` ou um `apiKeyHelper` confirma que uma credencial de gateway está ativa. Uma linha `Login method` nomeando uma conta claude.ai em vez disso significa que a credencial não foi distribuída; [defina-a você mesmo](#set-the-credential-variable).
34 </Step>
35
36 <Step title="Enviar uma mensagem de teste">
37 Feche o menu `/status` e envie qualquer prompt em Claude Code. Uma resposta normal de Claude, sem erro, confirma que a conexão do gateway funciona.
38 </Step>
39</Steps>
40
41Se ambas as linhas no menu `/status` parecerem corretas, mas a mensagem para Claude falhar, consulte a [tabela de solução de problemas](#troubleshoot-gateway-errors).
42
43<h2 id="configure-claude-code-yourself">
44 Configurar Claude Code você mesmo
45</h2>
46
47Para configurar Claude Code para o gateway você mesmo, você precisa de sua equipe de gateway:
48
49* A URL base do gateway
50* Uma credencial: uma string de chave ou token, ou um comando que busca uma
51 * Se sua equipe de gateway não disse qual tipo de credencial é, a seção [variável de credencial](#set-the-credential-variable) abaixo cobre o que tentar
52
53As seções abaixo cobrem a configuração em ordem:
54
55* [Definir a variável de credencial](#set-the-credential-variable) e [definir a URL base](#set-the-base-url-and-credential): as duas variáveis que toda conexão de gateway precisa
56* [Verificar a conexão](#verify-the-connection): confirme que funciona antes de persistir qualquer coisa
57* [Configurar cada superfície](#configure-each-surface): 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
58* [Configuração adicional](#additional-configuration): 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 ou uma URL base em formato de provedor. Defina estas apenas se seu administrador as nomeou
59
60<h3 id="set-the-credential-variable">
61 Definir a variável de credencial
62</h3>
63
64Para 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:
65
66| Definir a credencial em | Use quando |
67| :------------------------------------------------------ | :------------------------------------------------------------------- |
68| `ANTHROPIC_AUTH_TOKEN` | Sua equipe de gateway disse "bearer token" ou "Authorization header" |
69| `ANTHROPIC_API_KEY` | Sua equipe de gateway disse "API key" ou "x-api-key" |
70| [`apiKeyHelper`](#rotate-credentials-with-apikeyhelper) | A credencial rotaciona ou vem de um vault |
71
72Se você não foi informado qual tipo, use `ANTHROPIC_AUTH_TOKEN`; a [solicitação de verificação](#verify-the-connection) abaixo mostra como saber se você precisa mudar.
73
74<h3 id="set-the-base-url-and-credential">
75 Definir a URL base e a credencial
76</h3>
77
78Defina 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](#set-the-credential-variable). Você pode defini-los [em seu shell](#set-as-shell-environment-variables), que dura uma sessão de terminal, ou [em um arquivo de configurações Claude Code](#set-in-a-settings-file), que persiste em todos os lugares onde Claude Code é executado.
79
80Para sua primeira conexão, comece com exportações de shell e execute a [solicitação de verificação](#verify-the-connection) antes de mover os valores para um arquivo de configurações.
81
82<h4 id="set-as-shell-environment-variables">
83 Definir como variáveis de ambiente do shell
84</h4>
85
86Substitua os valores pelos que sua equipe de gateway forneceu:
87
88<Tabs>
89 <Tab title="Bash ou Zsh">
90 ```bash theme={null}
91 export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
92 export ANTHROPIC_AUTH_TOKEN=sk-gateway-key
93 ```
94 </Tab>
95
96 <Tab title="PowerShell">
97 ```powershell theme={null}
98 $env:ANTHROPIC_BASE_URL = "https://llm-gateway.example.com"
99 $env:ANTHROPIC_AUTH_TOKEN = "sk-gateway-key"
100 ```
101 </Tab>
102</Tabs>
103
104As 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, ou use um arquivo de configurações em vez disso.
105
106<h4 id="set-in-a-settings-file">
107 Definir em um arquivo de configurações
108</h4>
109
110Para fazer a configuração se aplicar em todos os lugares onde Claude Code é executado sem depender do seu shell, defina as variáveis no bloco `env` de um [arquivo de configurações](/pt/settings). Os arquivos de configurações têm escopos diferentes:
111
112* `~/.claude/settings.json` se aplica a todos os seus projetos. No Windows, o caminho é `%USERPROFILE%\.claude\settings.json`
113* `.claude/settings.local.json` se aplica a um projeto. Claude Code o adiciona ao seu gitignore quando cria o arquivo; se você o criar você mesmo, adicione-o ao seu gitignore manualmente primeiro para não cometer acidentalmente sua credencial
114
115<Warning>
116 Não coloque a credencial no `.claude/settings.json` de um projeto. Esse arquivo é confirmado e compartilhado com todos que clonam o repositório.
117</Warning>
118
119O bloco `env` se parece igual em qualquer arquivo:
120
121```json theme={null}
122{
123 "env": {
124 "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
125 "ANTHROPIC_AUTH_TOKEN": "sk-gateway-key"
126 }
127}
128```
129
130Quando 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.
131
132<h3 id="verify-the-connection">
133 Verificar a conexão
134</h3>
135
136Com 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](#set-as-shell-environment-variables) mesmo se você também colocar os valores em um arquivo de configurações.
137
138<Tabs>
139 <Tab title="Bash ou Zsh">
140 ```bash theme={null}
141 curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
142 -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
143 -H "anthropic-version: 2023-06-01" \
144 -H "content-type: application/json" \
145 -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'
146 ```
147 </Tab>
148
149 <Tab title="PowerShell">
150 ```powershell theme={null}
151 Invoke-RestMethod -Method Post -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `
152 -Headers @{ "Authorization" = "Bearer $env:ANTHROPIC_AUTH_TOKEN"; "anthropic-version" = "2023-06-01" } `
153 -ContentType "application/json" `
154 -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'
155 ```
156 </Tab>
157</Tabs>
158
159Se 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.
160
161Uma 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.
162
163<h4 id="confirm-in-claude-code">
164 Confirmar em Claude Code
165</h4>
166
167Inicie `claude` do mesmo shell para que ele herde as exportações, envie uma mensagem e execute `/status`.
168
169Na 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.
170
171Se a mensagem falhar ou `/status` não mostrar a URL do gateway, consulte a [tabela de solução de problemas](#troubleshoot-gateway-errors) abaixo.
172
173<h3 id="how-the-credential-variable-maps-to-a-header">
174 Como a variável de credencial mapeia para um cabeçalho
175</h3>
176
177Cada 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.
178
179<h3 id="conflicts-with-an-existing-login">
180 Conflitos com um login existente
181</h3>
182
183Uma 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.
184
185Execute `/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](#troubleshoot-gateway-errors) para saber qual descartar. Para limpar um login salvo para que apenas a credencial de gateway permaneça, execute `/logout`.
186
187<h2 id="configure-each-surface">
188 Configurar cada superfície
189</h2>
190
191O 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.
192
193<h3 id="vs-code-extension">
194 Extensão VS Code
195</h3>
196
197Defina as variáveis de gateway para a [extensão VS Code](/pt/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.
198
199```json theme={null}
200{
201 "claudeCode.environmentVariables": [
202 { "name": "ANTHROPIC_BASE_URL", "value": "https://llm-gateway.example.com" },
203 { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-gateway-key" }
204 ]
205}
206```
207
208<h3 id="desktop-app">
209 Aplicativo desktop
210</h3>
211
212O aplicativo desktop lê o roteamento de gateway de uma [configuração distribuída pelo administrador](https://claude.com/docs/cowork/3p/gateway), não de `ANTHROPIC_BASE_URL` ou `settings.json`. Se sua organização a distribuiu, o aplicativo desktop roteia através do gateway sem nenhuma configuração de sua parte; se não, use o CLI de terminal ou a extensão VS Code para sessões de gateway. Os administradores distribuem a configuração conforme descrito na [implementação da organização](/pt/llm-gateway-rollout#distribute-through-managed-settings).
213
214Se 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](#verify-the-connection).
215
216<h3 id="github-actions">
217 GitHub Actions
218</h3>
219
220[Claude Code GitHub Actions](/pt/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`.
221
222Para um gateway `x-api-key`, defina a URL base em `env` e passe a chave de gateway como a entrada:
223
224```yaml theme={null}
225env:
226 ANTHROPIC_BASE_URL: https://llm-gateway.example.com
227
228steps:
229 - uses: anthropics/claude-code-action@v1
230 with:
231 anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}
232```
233
234Para um gateway de bearer token, passe o mesmo segredo como a entrada `anthropic_api_key` e `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 satisfaz essa verificação de inicialização enquanto a variável de env coloca a chave no cabeçalho `Authorization` que o gateway lê. A cópia em `x-api-key` é ignorada:
235
236```yaml theme={null}
237env:
238 ANTHROPIC_BASE_URL: https://llm-gateway.example.com
239 ANTHROPIC_AUTH_TOKEN: ${{ secrets.GATEWAY_API_KEY }}
240
241steps:
242 - uses: anthropics/claude-code-action@v1
243 with:
244 anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}
245```
246
247Para 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](/pt/github-actions) e o [README](https://github.com/anthropics/claude-code-action#readme) da ação.
248
249<h3 id="agent-sdk">
250 Agent SDK
251</h3>
252
253O [Agent SDK](/pt/agent-sdk/overview) 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:
254
255* 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.
256* Python: `ClaudeAgentOptions(env=...)` mescla no topo do ambiente herdado, para que variáveis de gateway definidas no processo pai passem sem espalhar.
257
258<CodeGroup>
259 ```ts TypeScript theme={null}
260 const result = query({
261 prompt: "...",
262 options: {
263 env: {
264 ...process.env,
265 ANTHROPIC_BASE_URL: "https://llm-gateway.example.com",
266 ANTHROPIC_AUTH_TOKEN: process.env.GATEWAY_KEY,
267 },
268 },
269 })
270 ```
271
272 ```python Python theme={null}
273 options = ClaudeAgentOptions(
274 env={
275 "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
276 "ANTHROPIC_AUTH_TOKEN": os.environ["GATEWAY_KEY"],
277 }
278 )
279 ```
280</CodeGroup>
281
282<h3 id="slack-web-and-remote-control">
283 Slack, web e Remote Control
284</h3>
285
286[Claude Code no Slack](/pt/slack) e [Claude Code na web](/pt/claude-code-on-the-web) são produtos hospedados pela Anthropic que 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.
287
288[Remote Control](/pt/remote-control) e [ditado por voz](/pt/voice-dictation) 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. Para usar qualquer um, desdefina a credencial de gateway e faça login com claude.ai em vez disso; `/doctor` nomeia a variável a desdefir.
289
290<h2 id="additional-configuration">
291 Configuração adicional
292</h2>
293
294Essas configurações cobrem casos além da URL base e credencial. Defina-as apenas se as instruções do seu administrador ou a [tabela de solução de problemas](#troubleshoot-gateway-errors) chamarem por uma.
295
296<h3 id="send-additional-headers">
297 Enviar cabeçalhos adicionais
298</h3>
299
300Alguns 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`](/pt/env-vars) com um par `Name: Value` por linha. O exemplo abaixo adiciona um cabeçalho de roteamento nomeado `X-Org-Route`:
301
302<Tabs>
303 <Tab title="Bash ou Zsh">
304 ```bash theme={null}
305 export ANTHROPIC_CUSTOM_HEADERS="X-Org-Route: prod"
306 ```
307 </Tab>
308
309 <Tab title="PowerShell">
310 ```powershell theme={null}
311 $env:ANTHROPIC_CUSTOM_HEADERS = "X-Org-Route: prod"
312 ```
313 </Tab>
314</Tabs>
315
316Você 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:
317
318```json theme={null}
319{
320 "env": {
321 "ANTHROPIC_CUSTOM_HEADERS": "X-Org-Route: prod\nX-Tenant: acme"
322 }
323}
324```
325
326<h3 id="add-gateway-models-to-the-model-picker">
327 Adicionar modelos de gateway ao seletor de modelo
328</h3>
329
330A descoberta de modelo consulta o gateway para sua lista de modelos na inicialização e adiciona esses nomes ao seletor `/model` junto com as entradas integradas.
331
332Ative-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.
333
334Para ativá-la, defina `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` em seu shell ou no bloco `env` de `~/.claude/settings.json`. A descoberta requer Claude Code v2.1.129 ou posterior. {/* min-version: 2.1.129 */}
335
336Os modelos descobertos aparecem como entradas `/model` adicionais rotuladas `From gateway`. Para confirmar que a descoberta foi executada, inicie `claude --debug` e procure pelas linhas `[gatewayDiscovery]`: um sucesso registra quantos modelos foram armazenados em cache, e um `404`, timeout ou redirecionamento é registrado 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](/pt/llm-gateway-protocol#model-discovery).
337
338<h3 id="rotate-credentials-with-apikeyhelper">
339 Rotacionar credenciais com apiKeyHelper
340</h3>
341
342Um `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.
343
344Use 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](#set-the-credential-variable) é tudo que você precisa e você pode pular esta seção.
345
346O 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. Escreva o script, torne-o executável e referencie-o de `apiKeyHelper` em seu [arquivo de configurações](/pt/settings):
347
348<Tabs>
349 <Tab title="Bash ou Zsh">
350 Por exemplo, um script que lê de um vault:
351
352 ```bash theme={null}
353 #!/bin/bash
354 vault kv get -field=api_key secret/llm-gateway/claude-code
355 ```
356
357 Referencie seu caminho em `~/.claude/settings.json`:
358
359 ```json theme={null}
360 {
361 "apiKeyHelper": "~/bin/get-gateway-key.sh"
362 }
363 ```
364 </Tab>
365
366 <Tab title="PowerShell">
367 Por exemplo, um script que lê de um vault:
368
369 ```powershell theme={null}
370 vault kv get -field=api_key secret/llm-gateway/claude-code
371 ```
372
373 Referencie a invocação do PowerShell em `%USERPROFILE%\.claude\settings.json`, escapando as barras invertidas na string JSON:
374
375 ```json theme={null}
376 {
377 "apiKeyHelper": "powershell -NoProfile -File C:\\scripts\\get-gateway-key.ps1"
378 }
379 ```
380 </Tab>
381</Tabs>
382
383Claude Code armazena em cache a saída do auxiliar por cinco minutos por padrão e o re-executa quando uma solicitação retorna HTTP 401. Para alterar o tempo de vida do cache, defina `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` em milissegundos, por exemplo `CLAUDE_CODE_API_KEY_HELPER_TTL_MS=900000` para 15 minutos.
384
385O 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.
386
387<h3 id="route-to-a-cloud-provider-through-a-gateway">
388 Rotear para um provedor em nuvem através de um gateway
389</h3>
390
391Essas 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 Bedrock e Vertex aceitam formatos de solicitação nativos desses provedores; gateways Foundry e Claude Platform on AWS aceitam o formato Anthropic Messages e diferem apenas em qual variável de URL base os alcança.
392
393Use uma apenas se sua equipe de gateway nomeou especificamente Bedrock, Vertex, Foundry ou Claude Platform on AWS. Se a [solicitação de verificação](#verify-the-connection) acima retornou JSON, você pode pular esta seção.
394
395Defina o bloco para o provedor que sua equipe de gateway nomeou. As variáveis skip-auth dizem a Claude Code para não assinar solicitações com credenciais de provedor, já que o gateway as mantém. Se o gateway precisa de seu próprio token, adicione `ANTHROPIC_AUTH_TOKEN` após o bloco, exceto para Foundry, que usa `ANTHROPIC_FOUNDRY_API_KEY` conforme mostrado.
396
397<h4 id="amazon-bedrock">
398 Amazon Bedrock
399</h4>
400
401<Tabs>
402 <Tab title="Bash ou Zsh">
403 ```bash theme={null}
404 export ANTHROPIC_BEDROCK_BASE_URL=https://llm-gateway.example.com/bedrock
405 export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
406 export CLAUDE_CODE_USE_BEDROCK=1
407 ```
408 </Tab>
409
410 <Tab title="PowerShell">
411 ```powershell theme={null}
412 $env:ANTHROPIC_BEDROCK_BASE_URL = "https://llm-gateway.example.com/bedrock"
413 $env:CLAUDE_CODE_SKIP_BEDROCK_AUTH = "1"
414 $env:CLAUDE_CODE_USE_BEDROCK = "1"
415 ```
416 </Tab>
417</Tabs>
418
419<h4 id="google-vertex-ai">
420 Google Vertex AI
421</h4>
422
423<Tabs>
424 <Tab title="Bash ou Zsh">
425 ```bash theme={null}
426 export ANTHROPIC_VERTEX_BASE_URL=https://llm-gateway.example.com/vertex
427 export ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
428 export CLAUDE_CODE_SKIP_VERTEX_AUTH=1
429 export CLAUDE_CODE_USE_VERTEX=1
430 export CLOUD_ML_REGION=us-east5
431 ```
432 </Tab>
433
434 <Tab title="PowerShell">
435 ```powershell theme={null}
436 $env:ANTHROPIC_VERTEX_BASE_URL = "https://llm-gateway.example.com/vertex"
437 $env:ANTHROPIC_VERTEX_PROJECT_ID = "your-gcp-project-id"
438 $env:CLAUDE_CODE_SKIP_VERTEX_AUTH = "1"
439 $env:CLAUDE_CODE_USE_VERTEX = "1"
440 $env:CLOUD_ML_REGION = "us-east5"
441 ```
442 </Tab>
443</Tabs>
444
445<h4 id="microsoft-foundry">
446 Microsoft Foundry
447</h4>
448
449Coloque a credencial do gateway em `ANTHROPIC_FOUNDRY_API_KEY`; ela é enviada para o gateway como o cabeçalho `x-api-key`. `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` não se aplica aqui: sem uma chave de API, o cliente Foundry falha em cada solicitação antes de sair da máquina.
450
451<Tabs>
452 <Tab title="Bash ou Zsh">
453 ```bash theme={null}
454 export ANTHROPIC_FOUNDRY_BASE_URL=https://llm-gateway.example.com/foundry
455 export ANTHROPIC_FOUNDRY_API_KEY=sk-gateway-key
456 export CLAUDE_CODE_USE_FOUNDRY=1
457 ```
458 </Tab>
459
460 <Tab title="PowerShell">
461 ```powershell theme={null}
462 $env:ANTHROPIC_FOUNDRY_BASE_URL = "https://llm-gateway.example.com/foundry"
463 $env:ANTHROPIC_FOUNDRY_API_KEY = "sk-gateway-key"
464 $env:CLAUDE_CODE_USE_FOUNDRY = "1"
465 ```
466 </Tab>
467</Tabs>
468
469<h4 id="claude-platform-on-aws">
470 Claude Platform on AWS
471</h4>
472
473Consulte [Claude Platform on AWS](/pt/claude-platform-on-aws) para o ID do workspace.
474
475<Tabs>
476 <Tab title="Bash ou Zsh">
477 ```bash theme={null}
478 export ANTHROPIC_AWS_BASE_URL=https://llm-gateway.example.com/anthropic-aws
479 export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
480 export CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1
481 export CLAUDE_CODE_USE_ANTHROPIC_AWS=1
482 ```
483 </Tab>
484
485 <Tab title="PowerShell">
486 ```powershell theme={null}
487 $env:ANTHROPIC_AWS_BASE_URL = "https://llm-gateway.example.com/anthropic-aws"
488 $env:ANTHROPIC_AWS_WORKSPACE_ID = "wrkspc_01ABCDEFGHIJKLMN"
489 $env:CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH = "1"
490 $env:CLAUDE_CODE_USE_ANTHROPIC_AWS = "1"
491 ```
492 </Tab>
493</Tabs>
494
495<h2 id="troubleshoot-gateway-errors">
496 Solucionar erros de gateway
497</h2>
498
499Estes 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:
500
501| Erro | Causa | Correção |
502| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
503| Um aviso de inicialização nomeando duas fontes de credencial e terminando em `auth may not work as expected`. Versões mais antigas mostram `Auth conflict: Both a token (SOURCE) and an API key (SOURCE) are set` em vez disso. | Uma credencial de gateway e um login salvo estão ambos ativos; a variável é usada para solicitações, mas o login obsoleto pode causar comportamento de autenticação inesperado | Desdefina a variável para usar o login salvo, ou execute `/logout` para usar a credencial de gateway |
504| Erros `401` nomeando um token inválido ou não reconhecido | A credencial não é uma que o gateway emitiu, ou está em um cabeçalho que o gateway não lê | Confirme que a variável corresponde ao seu tipo de credencial na [tabela de credencial](#set-the-credential-variable) e regenere a chave no gateway se ela foi revogada |
505| `Unable to connect to API (ConnectionRefused)` ou `(ECONNREFUSED)` de instalações npm, frequentemente após uma pausa silenciosa enquanto Claude Code [tenta novamente com backoff](/pt/errors#automatic-retries) | Nada respondeu na URL base: o endereço está errado ou uma VPN ou firewall bloqueia o caminho para o gateway | Execute o [teste curl acima](#verify-the-connection), que falha imediatamente com a mesma causa, e confirme a URL e o caminho de rede com sua equipe de gateway |
506| `API returned an empty or malformed response (HTTP 200)` | O gateway ou um proxy intermediário retornou uma resposta não-API, frequentemente uma página de erro HTML ou login | Teste com a [solicitação curl acima](#verify-the-connection); corrija a rota do gateway que retorna não-JSON |
507| Erros `400` nomeando `context_management`, `Extra inputs are not permitted` ou outros campos não reconhecidos | O gateway encaminha solicitações para um upstream que rejeita campos que Claude Code envia para endpoints em formato Anthropic | Defina `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`, que suprime a maioria dos campos de pré-lançamento; consulte [passagem de recurso](/pt/llm-gateway-protocol#feature-pass-through). Alguns betas não são controlados por este sinalizador; para esses, defina a variável de provedor `CLAUDE_CODE_USE_*` correspondente para que Claude Code envie apenas o que esse provedor aceita |
508| Erros `400` nomeando `thinking` ou `adaptive`, como `Input tag 'adaptive' found` | A compilação do modelo upstream não aceita raciocínio adaptativo, que Claude Code solicita para modelos Claude 4.6 e posteriores | Atualize o upstream do gateway. Em Opus 4.6 e Sonnet 4.6, `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` funciona em vez disso. As variáveis de capacidade de [configuração de modelo](/pt/model-config) se aplicam apenas às configurações de provedor, como `CLAUDE_CODE_USE_BEDROCK` e `CLAUDE_CODE_USE_VERTEX`, não atrás de um gateway `ANTHROPIC_BASE_URL` |
509| Erros `400` indicando um contexto ou limite de token nas próprias palavras do gateway, como `ContextWindowExceededError` ou `prompt token count of N exceeds the limit of M` | O gateway impõe um contexto menor que a janela nativa do modelo e reescreve o erro upstream, para que a compactação automática e repetição, que corresponde à redação `prompt is too long` da Anthropic, não dispare | Execute `/compact` para recuperar a sessão. Para evitar, defina `CLAUDE_CODE_AUTO_COMPACT_WINDOW` para o limite do gateway; o valor é fixado em pelo menos 100.000 tokens e no máximo a janela de contexto do modelo, para que um limite de gateway abaixo de 100.000 não possa ser correspondido e `/compact` permaneça a recuperação lá. Também defina `CLAUDE_CODE_MAX_OUTPUT_TOKENS` abaixo do limite de saída do modelo de gateway |
510| Modelos faltando do seletor `/model` | Nomes de modelo de gateway não estão na lista integrada de Claude Code | Ative [descoberta de modelo de gateway](#add-gateway-models-to-the-model-picker) ou adicione nomes com as variáveis de [configuração de modelo](/pt/model-config) |
511| Claude Code pede para você fazer login mesmo que o [teste curl](#verify-the-connection) tenha sucesso | O CLI não tem credencial própria: uma URL base alcançável não é uma, e um bloco `env` no `.claude/settings.json` ou `.claude/settings.local.json` de um projeto se aplica apenas após o assistente de primeira execução e prompt de confiança | Defina `ANTHROPIC_AUTH_TOKEN` em algum lugar que Claude Code leia antes da configuração de primeira execução: uma exportação de shell, o bloco `env` em `~/.claude/settings.json` ou configurações gerenciadas |
512| `ANTHROPIC_API_KEY` está definido mas ignorado, sem prompt | A chave precisa de uma aprovação única em sessões interativas, e uma chave previamente recusada é ignorada sem perguntar novamente | Ative-a em `/config` com a opção `Use custom API key` |
513| `This machine's managed settings require a first-party login` | Configurações gerenciadas incluem `forceLoginMethod` ou `forceLoginOrgUUID`, que em Claude Code v2.1.146 e posterior não podem coexistir com `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` ou `apiKeyHelper` | Seu administrador deve remover `forceLoginMethod` e `forceLoginOrgUUID` das configurações gerenciadas para usar credenciais de gateway, ou remover a credencial de gateway para usar login de primeira parte. Os dois não podem ser combinados |
514| `403` com um corpo HTML como `403 Forbidden`, quando os próprios logs do gateway não mostram nenhuma solicitação recebida | Um firewall de aplicativo web ou proxy reverso na frente do gateway bloqueou o corpo da solicitação antes de chegar ao gateway. Os prompts de Claude Code incluem tags de estilo XML e código-fonte que correspondem a regras de corpo de cross-site-scripting, para que um teste curl curto passe enquanto uma sessão real não | Isente o caminho `/v1/messages` do gateway da inspeção de corpo de solicitação. No AWS WAF esta é a regra gerenciada `CrossSiteScripting_Body`; no nginx com ModSecurity é a regra de corpo OWASP CRS equivalente |
515| Erros de certificado ou TLS como `SSL certificate verification failed` ou `Self-signed certificate detected`, quando o [teste curl](#verify-the-connection) tem sucesso | O runtime de Claude Code não está confiando na mesma autoridade de certificação que `curl` usa. Comum atrás de proxies de inspeção TLS corporativa | Defina `NODE_EXTRA_CA_CERTS` para o caminho do pacote CA; consulte [armazenamento de certificado CA](/pt/network-config#ca-certificate-store) |
516
517Se 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](/pt/errors#authentication-errors).
518
519<h2 id="related-resources">
520 Recursos relacionados
521</h2>
522
523* [Visão geral de gateways LLM](/pt/llm-gateway): o que é um gateway e como ele interage com assinaturas claude.ai
524* [Implementar um gateway LLM para sua organização](/pt/llm-gateway-rollout): a lista de verificação voltada para o administrador para implantar e distribuir configuração de gateway
525* [Referência do protocolo de gateway](/pt/llm-gateway-protocol): o que Claude Code envia para um gateway, incluindo os cabeçalhos e campos que o gateway deve encaminhar
526* [Configurações](/pt/settings): onde os arquivos de configurações vivem e como o bloco `env` é lido
527* [Autenticação](/pt/authentication): como variáveis de credencial, `apiKeyHelper` e login OAuth interagem
