120 Envie a URL do gateway para máquinas de desenvolvedores120 Envie a URL do gateway para máquinas de desenvolvedores
121</h3>121</h3>
122 122
123123Assim que o gateway estiver servindo, envie `forceLoginMethod`, `forceLoginGatewayUrl` e `parentSettingsBehavior: "merge"` para a máquina de cada desenvolvedor através de configurações gerenciadas, via MDM ou escrevendo o `managed-settings.json` por SO diretamente. Sem isso, `/login` mostra o seletor de conta padrão sem opção de gateway. Uma vez que você implanta as chaves, Claude Code para de usar uma chave de API restante ou login claude.ai na máquina, então planeje o envio junto com suas instruções de sign-in. [A política do administrador requer um sign-in de gateway Cloud](/docs/pt/errors#administrator-policy-requires-a-cloud-gateway-sign-in) descreve as mensagens que os desenvolvedores veem.Assim que o gateway estiver servindo, envie `forceLoginMethod`, `forceLoginGatewayUrl` e `parentSettingsBehavior: "merge"` para a máquina de cada desenvolvedor através de configurações gerenciadas, via MDM ou escrevendo o `managed-settings.json` por SO diretamente. Sem isso, `/login` mostra o seletor de conta padrão sem opção de gateway.
124
125Uma vez que você implanta as chaves, Claude Code para de usar uma chave de API restante ou login claude.ai na máquina, então planeje o envio junto com suas instruções de sign-in. [A política do administrador requer um sign-in de gateway Cloud](/docs/pt/errors#administrator-policy-requires-a-cloud-gateway-sign-in) descreve as mensagens que os desenvolvedores veem.
124 126
125Consulte [onde cada mecanismo armazena a política](/docs/pt/managed-settings#where-each-mechanism-stores-the-policy) para os caminhos de arquivo, e [Configurações gerenciadas do lado do cliente](/docs/pt/claude-apps-gateway-config#client-side-managed-settings) para o equivalente `bootstrapUrl` do Claude Desktop.127Consulte [onde cada mecanismo armazena a política](/docs/pt/managed-settings#where-each-mechanism-stores-the-policy) para os caminhos de arquivo, e [Configurações gerenciadas do lado do cliente](/docs/pt/claude-apps-gateway-config#client-side-managed-settings) para o equivalente `bootstrapUrl` do Claude Desktop.
126 128
129<h3 id="large-rollouts">
130 Grandes implantações
131</h3>
132
133O sign-in é limitado por taxa por endereço IP do cliente, e os padrões se adequam a uma pequena equipe. Cada endereço recebe 30 inícios de sign-in e 10 envios de código a cada 10 minutos. Uma implantação para milhares de desenvolvedores pode atingir esses limites na primeira manhã, por uma de duas razões:
134
135* **O gateway não consegue ver além do seu balanceador de carga.** Sem [`listen.trusted_proxies`](/docs/pt/claude-apps-gateway-config#listen), cada desenvolvedor parece vir do endereço do balanceador de carga e compartilha um limite. Defina-o antes de qualquer outra coisa. O gateway registra um aviso na primeira vez que ignora um cabeçalho `X-Forwarded-For`.
136* **Muitos desenvolvedores compartilham alguns endereços de saída NAT ou VPN.** Eles compartilham os limites desses endereços mesmo quando `trusted_proxies` está correto. Aumente [`rate_limits`](/docs/pt/claude-apps-gateway-config#http-tuning) para se adequar.
137
138Para dimensionar `max`, divida os desenvolvedores pelos endereços de saída que eles compartilham. Estime quantos desses fazem sign-in dentro de um período `window_seconds`, que é 10 minutos por padrão. Depois dobre para cobrir tentativas novamente e desenvolvedores que fazem sign-in tanto para Claude Code quanto para Claude Desktop.
139
140Por exemplo, 10.000 desenvolvedores atrás de 4 endereços de saída fazem sign-in uniformemente ao longo de uma hora. Isso é 2.500 desenvolvedores por endereço e cerca de 420 deles em cada 10 minutos, que você dobra e arredonda para 1.000. O exemplo abaixo define ambos os limites para 1.000:
141
142```yaml theme={null}
143rate_limits:
144 device_authorization: { max: 1000, window_seconds: 600 }
145 device_verify: { max: 1000, window_seconds: 600 }
146```
147
148`device_verify` é o que impede alguém de adivinhar o código de sign-in de outro desenvolvedor, então aumente-o apenas o quanto sua estimativa precisa. Mesmo nestes limites, um código tem 8 caracteres de um alfabeto de 20 caracteres e expira após 10 minutos, então adivinhar permanece impraticável; consulte [Resistência de força bruta de código de usuário](#user-code-brute-force-resistance).
149
150Quando seu IdP emite tokens de atualização, Claude Code renova sessões silenciosamente, então você pode colocar o limite de volta após a implantação. Sem tokens de atualização, desenvolvedores fazem sign-in novamente a cada [`session.ttl_hours`](/docs/pt/claude-apps-gateway-config#session). Dimensione ambos os limites para essa taxa constante também e deixe-os elevados.
151
152Quando um limite é atingido, Claude Code v2.1.274 ou posterior mostra `The gateway is limiting sign-in attempts right now`. Um gateway na v2.1.274 ou posterior mostra `Too many attempts came from your network address` na página de verificação, com as configurações a verificar. Também escreve uma linha de log `sign-in refused` que nomeia a configuração a alterar.
153
127<h2 id="operations">154<h2 id="operations">
128 Operações155 Operações
129</h2>156</h2>
158 185
159O documento de descoberta OAuth em `/.well-known/oauth-authorization-server` também retorna `200` apenas após carregamento de configuração, descoberta OIDC, construção de cliente upstream e migração do Postgres, então funciona como uma verificação de inicialização de ponta a ponta.186O documento de descoberta OAuth em `/.well-known/oauth-authorization-server` também retorna `200` apenas após carregamento de configuração, descoberta OIDC, construção de cliente upstream e migração do Postgres, então funciona como uma verificação de inicialização de ponta a ponta.
160 187
188<h3 id="concurrent-upstream-requests">
189 Solicitações upstream simultâneas
190</h3>
191
192Por padrão, cada réplica de gateway envia no máximo 256 solicitações upstream ao mesmo tempo. Uma resposta de streaming conta contra o limite até que o stream termine.
193
194Uma solicitação que chega enquanto uma réplica está no limite aguarda dentro do gateway por um slot livre. O desenvolvedor vê uma resposta que é lenta para começar ou parece travar. Em um upstream `provider: anthropic`, uma solicitação que aguarda mais tempo que [`timeouts.upstream_ttfb_ms`](/docs/pt/claude-apps-gateway-config#http-tuning) desiste desse upstream e falha com um 502 quando nenhum upstream posterior o serve.
195
196A linha de log de inicialização que contém `upstream requests:` mostra o limite em vigor. Enquanto uma réplica tem mais solicitações abertas que o limite, ela também registra um aviso que contém `client requests are open`, no máximo uma vez por minuto.
197
198Para servir mais solicitações ao mesmo tempo, você tem duas opções:
199
200* Adicione réplicas.
201* Aumente o limite em cada réplica. Defina a variável de ambiente `BUN_CONFIG_MAX_HTTP_REQUESTS` no contêiner do gateway para um número inteiro de 1 a 65535, depois reinicie o contêiner.
202
203Uma réplica preenche seu limite a uma taxa de solicitação de aproximadamente o limite dividido pelo número médio de segundos que uma solicitação permanece aberta. Por exemplo, se as solicitações permanecerem abertas por 10 segundos em média, uma réplica no limite padrão de 256 a preenche a cerca de 26 solicitações por segundo.
204
205Se você fizer autoscaling em CPU, uma réplica no limite enfileira solicitações sem disparar uma expansão, então defina o alvo abaixo do nível de CPU que suas réplicas mostram quando registram o aviso `client requests are open`.
206
207<Warning>
208 Cada solicitação aberta mantém memória no processo do gateway enquanto ele faz streaming e enquanto aguarda por um slot. Se você manter o limite em 256, a memória em uma réplica sobrecarregada ainda cresce, porque as solicitações em espera mantêm seus corpos de solicitação. Dimensione a memória do contêiner para o número de solicitações abertas no pico e observe a memória quando você alterar o limite. Uma réplica que fica sem memória é eliminada e descarta cada stream que mantém.
209</Warning>
210
161<h3 id="outage-behavior">211<h3 id="outage-behavior">
162 Comportamento de interrupção212 Comportamento de interrupção
163</h3>213</h3>
205 Atualizações255 Atualizações
206</h3>256</h3>
207 257
208258As réplicas são sem estado, então uma reinicialização contínua é segura a qualquer momento. O gateway executa migrações de esquema na inicialização, o que significa que implantar o novo binário auto-migra o banco de dados. Réplicas concorrentes serializam em um bloqueio consultivo do Postgres, então apenas uma aplica cada migração.As réplicas são sem estado, então uma reinicialização contínua não perde nenhum estado do gateway. O gateway executa migrações de esquema na inicialização, o que significa que implantar o novo binário auto-migra o banco de dados. Réplicas concorrentes serializam em um bloqueio consultivo do Postgres, então apenas uma aplica cada migração.
259
260Quando seu orquestrador para uma réplica com `SIGTERM`, como em uma reinicialização contínua ou uma redução de escala, o gateway para de aceitar novas conexões e deixa as solicitações e streams já em voo terminarem antes de sair. Ele aguarda até 25 segundos, chamado de janela de drenagem, depois fecha o que ainda está aberto. Um `SIGINT`, como Ctrl+C em um terminal, inicia a mesma drenagem, e um segundo sinal durante a drenagem fecha as solicitações abertas e sai imediatamente. A drenagem requer gateway v2.1.274 ou posterior.
261
262Gerações longas podem fazer streaming por minutos. No Kubernetes e Amazon ECS, aumente ambas juntas para dar a esses streams mais tempo:
263
264* **A janela de drenagem**: defina a variável de ambiente `CLAUDE_GATEWAY_DRAIN_TIMEOUT_MS` no contêiner do gateway para um número inteiro positivo de milissegundos, como `120000`. O gateway ignora um valor em qualquer outra forma, como `120s`, e mantém o padrão de 25 segundos
265* **O período de carência do seu orquestrador**: `terminationGracePeriodSeconds` no Kubernetes, ou `stopTimeout` no Amazon ECS
266
267O período de carência padrão é 30 segundos em ambas as plataformas. Mantenha-o pelo menos 5 segundos mais longo que a janela de drenagem, ou o orquestrador matará o gateway antes da drenagem terminar. No Kubernetes, adicione também a duração de qualquer hook `preStop`, porque o período de carência começa a contar antes do hook ser executado em vez de quando o gateway recebe `SIGTERM`.
268
269Sua plataforma também pode limitar quanto tempo a drenagem pode executar:
270
271* **Amazon ECS no Fargate**: `stopTimeout` permite no máximo 120 segundos
272* **Cloud Run**: para uma instância 10 segundos após `SIGTERM`, então streams abertos recebem no máximo 10 segundos lá, qualquer que seja a janela de drenagem
273
274Quando a janela de drenagem termina com solicitações ainda abertas, o gateway registra um aviso que contém `drain window over after`, conta as solicitações que cortou e nomeia ambas as configurações para aumentar.
209 275
210As migrações são apenas anexadas, então reverter para um binário anterior que conhece menos migrações é seguro; ele ignora as linhas extras. A reversão também re-valida o YAML contra o esquema do binário mais antigo, então uma configuração que adotou uma chave introduzida pela versão mais nova falha na inicialização no mais antigo. Remova a nova chave antes de reverter.276As migrações são apenas anexadas, então reverter para um binário anterior que conhece menos migrações é seguro; ele ignora as linhas extras. A reversão também re-valida o YAML contra o esquema do binário mais antigo, então uma configuração que adotou uma chave introduzida pela versão mais nova falha na inicialização no mais antigo. Remova a nova chave antes de reverter.
211 277
237 303
238* Os desenvolvedores mantêm JWTs de curta duração em vez de chaves upstream brutas. A perna CLI-para-gateway usa a concessão de dispositivo RFC 8628, e a troca de código de autorização do gateway com o IdP executa PKCE na configuração padrão, então um código de autorização IdP interceptado é inútil.304* Os desenvolvedores mantêm JWTs de curta duração em vez de chaves upstream brutas. A perna CLI-para-gateway usa a concessão de dispositivo RFC 8628, e a troca de código de autorização do gateway com o IdP executa PKCE na configuração padrão, então um código de autorização IdP interceptado é inútil.
239* A página de verificação de dispositivo impõe POST de mesma origem e um limite de taxa por IP por RFC 8628 §5.1. Consulte [Resistência de força bruta de código de usuário](#user-code-brute-force-resistance).305* A página de verificação de dispositivo impõe POST de mesma origem e um limite de taxa por IP por RFC 8628 §5.1. Consulte [Resistência de força bruta de código de usuário](#user-code-brute-force-resistance).
240306* Solicitações de saída passam por uma proteção de falsificação de solicitação do lado do servidor (SSRF) que resolve DNS, bloqueia endereços link-local e metadados de nuvem mais loopback por padrão e fixa a conexão ao IP resolvido, então URLs influenciadas pelo operador como o IdP e destinos OTLP não podem ser redirecionados para endpoints de metadados de nuvem. Intervalos privados RFC 1918 são deliberadamente permitidos, porque IdPs e coletores OTLP comumente vivem em IPs privados. Defina `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1` no ambiente do gateway apenas quando algo que o gateway deve alcançar legitimamente vive em loopback, como um IdP de desenvolvimento local ou um coletor OTLP sidecar em `localhost`. A variável relaxa o bloqueio de loopback para cada URL configurada pelo operador e também pula o aviso de tempo de inicialização que verifica se o pod pode alcançar o endpoint de metadados de nuvem, então prefira dar ao coletor seu próprio endereço interno.* As solicitações do gateway para seu IdP, seus coletores OTLP e upstreams `provider: anthropic` passam por uma proteção de falsificação de solicitação do lado do servidor (SSRF) que resolve DNS, bloqueia endereços link-local e metadados de nuvem mais loopback por padrão e fixa a conexão ao IP resolvido, então URLs influenciadas pelo operador não podem ser redirecionadas para endpoints de metadados de nuvem. Intervalos privados RFC 1918 são deliberadamente permitidos, porque IdPs e coletores OTLP comumente vivem em IPs privados. Para os outros provedores, o gateway recusa um `base_url` que nomeie um desses endereços ou um nome de host de metadados quando carrega a configuração, e o SDK do provedor então se conecta sem a verificação de DNS.
307
308 Se você ativar [egresso somente proxy](/docs/pt/claude-apps-gateway-config#proxy-only-egress), essa verificação de endereço se move para seu proxy direto: o gateway entrega nomes de host e a lista de permissões do proxy deve recusar esses destinos.
309
310 Defina `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1` no ambiente do gateway apenas quando algo que o gateway deve alcançar legitimamente vive em loopback, como um IdP de desenvolvimento local ou um coletor OTLP sidecar em `localhost`. A variável relaxa o bloqueio de loopback para cada URL configurada pelo operador e também pula o aviso de tempo de inicialização que verifica se o pod pode alcançar o endpoint de metadados de nuvem, então prefira dar ao coletor seu próprio endereço interno.
241 311
242Se você adicionar seus próprios controles de saída, o gateway deve alcançar o servidor de metadados sempre que usar credenciais de metadados de instância como identidade de carga de trabalho.312Se você adicionar seus próprios controles de saída, o gateway deve alcançar o servidor de metadados sempre que usar credenciais de metadados de instância como identidade de carga de trabalho.
243 313
252 322
253O `user_code` que um desenvolvedor digita na página de verificação `/device` tem 8 caracteres extraídos de um alfabeto de 20 caracteres, o que produz 20⁸ ou cerca de 2,56×10¹⁰ combinações, e expira após 10 minutos.323O `user_code` que um desenvolvedor digita na página de verificação `/device` tem 8 caracteres extraídos de um alfabeto de 20 caracteres, o que produz 20⁸ ou cerca de 2,56×10¹⁰ combinações, e expira após 10 minutos.
254 324
255325O gateway aplica limites de taxa por IP nos endpoints de concessão de dispositivo, configuráveis via [`rate_limits`](/docs/pt/claude-apps-gateway-config#http-tuning). Aumente os limites se muitos desenvolvedores entrarem de um único endereço NAT corporativo compartilhado. Os limites se aplicam apenas ao fluxo de entrada, não à inferência.O gateway aplica limites de taxa por IP nos endpoints de concessão de dispositivo, configuráveis via [`rate_limits`](/docs/pt/claude-apps-gateway-config#http-tuning). Aumente os limites se muitos desenvolvedores entrarem de um único endereço NAT corporativo compartilhado. [Grandes implantações](#large-rollouts) mostra como dimensioná-los. Os limites se aplicam apenas ao fluxo de entrada, não à inferência.
256 326
257<h3 id="compliance-posture">327<h3 id="compliance-posture">
258 Postura de conformidade328 Postura de conformidade
282O stderr do gateway inclui o fluxo de eventos de auditoria, o log de auditoria registra identidades de desenvolvedores, e o arquivo de debug registra saída de hook e servidor MCP da máquina do desenvolvedor. Revise e remova essas informações antes de postar em uma issue pública.352O stderr do gateway inclui o fluxo de eventos de auditoria, o log de auditoria registra identidades de desenvolvedores, e o arquivo de debug registra saída de hook e servidor MCP da máquina do desenvolvedor. Revise e remova essas informações antes de postar em uma issue pública.
283 353
284| Symptom | Cause | Fix |354| Symptom | Cause | Fix |
285355| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
286| A `/login` de um desenvolvedor mostra o seletor de conta padrão em vez da tela **Cloud gateway** | `forceLoginMethod` ou `forceLoginGatewayUrl` não está definido nas configurações gerenciadas nessa máquina | Implante o [arquivo de configurações gerenciadas](/docs/pt/claude-apps-gateway#set-the-gateway-url) no dispositivo; `/login` lê a URL do gateway de lá |356| A `/login` de um desenvolvedor mostra o seletor de conta padrão em vez da tela **Cloud gateway** | `forceLoginMethod` ou `forceLoginGatewayUrl` não está definido nas configurações gerenciadas nessa máquina | Implante o [arquivo de configurações gerenciadas](/docs/pt/claude-apps-gateway#set-the-gateway-url) no dispositivo; `/login` lê a URL do gateway de lá |
287| As solicitações de um desenvolvedor falham com `Not signed in to the Cloud gateway — run /login.` | As configurações gerenciadas da máquina definem `forceLoginMethod: "gateway"` ou `forceLoginGatewayUrl`, e a sessão não tem login no gateway. Um login claude.ai restante não satisfaz o requisito. | Peça ao desenvolvedor para executar `/login` e completar o login no gateway. Veja também [Administrator policy requires a Cloud gateway sign-in](/docs/pt/errors#administrator-policy-requires-a-cloud-gateway-sign-in). |357| As solicitações de um desenvolvedor falham com `Not signed in to the Cloud gateway — run /login.` | As configurações gerenciadas da máquina definem `forceLoginMethod: "gateway"` ou `forceLoginGatewayUrl`, e a sessão não tem login no gateway. Um login claude.ai restante não satisfaz o requisito. | Peça ao desenvolvedor para executar `/login` e completar o login no gateway. Veja também [Administrator policy requires a Cloud gateway sign-in](/docs/pt/errors#administrator-policy-requires-a-cloud-gateway-sign-in). |
288| Claude Desktop relata que sua configuração de bootstrap não pôde ser buscada | `/user/bootstrap` retornou 404: a política que corresponde ao usuário não carrega uma chave `desktop`, ou nenhuma política correspondeu. O log de auditoria do gateway registra cada rejeição como `desktop_bootstrap.denied` com o motivo. | Adicione um bloco `desktop` à política que corresponde ao usuário, ou à camada base `match: {}`; um `desktop: {}` vazio é suficiente. Veja [Claude Desktop overlay](/docs/pt/claude-apps-gateway-config#claude-desktop-overlay). |358| Claude Desktop relata que sua configuração de bootstrap não pôde ser buscada | `/user/bootstrap` retornou 404: a política que corresponde ao usuário não carrega uma chave `desktop`, ou nenhuma política correspondeu. O log de auditoria do gateway registra cada rejeição como `desktop_bootstrap.denied` com o motivo. | Adicione um bloco `desktop` à política que corresponde ao usuário, ou à camada base `match: {}`; um `desktop: {}` vazio é suficiente. Veja [Claude Desktop overlay](/docs/pt/claude-apps-gateway-config#claude-desktop-overlay). |
289| A inicialização mostra `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.` | A compilação Claude Code instalada é anterior ao suporte de gateway | Peça ao desenvolvedor para atualizar Claude Code para uma versão que inclua suporte de Cloud gateway |359| A inicialização mostra `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.` | A compilação Claude Code instalada é anterior ao suporte de gateway | Peça ao desenvolvedor para atualizar Claude Code para uma versão que inclua suporte de Cloud gateway |
290| A inicialização sai com `Administrator policy requires a Cloud gateway sign-in on this machine` | O ambiente do desenvolvedor define `ANTHROPIC_API_KEY` ou `ANTHROPIC_AUTH_TOKEN`, suas configurações configuram um [`apiKeyHelper`](/docs/pt/settings-reference#apikeyhelper), ou uma chave de API de um login anterior do Claude Console ainda está salva | Peça ao desenvolvedor para limpar cada um que se aplica: desdefina a variável, remova a entrada `apiKeyHelper`, ou execute `claude auth logout` para remover a chave salva. Depois peça para iniciar `claude` e fazer login com `/login`. Veja também [Administrator policy requires a Cloud gateway sign-in](/docs/pt/errors#administrator-policy-requires-a-cloud-gateway-sign-in). |360| A inicialização sai com `Administrator policy requires a Cloud gateway sign-in on this machine` | O ambiente do desenvolvedor define `ANTHROPIC_API_KEY` ou `ANTHROPIC_AUTH_TOKEN`, suas configurações configuram um [`apiKeyHelper`](/docs/pt/settings-reference#apikeyhelper), ou uma chave de API de um login anterior do Claude Console ainda está salva | Peça ao desenvolvedor para limpar cada um que se aplica: desdefina a variável, remova a entrada `apiKeyHelper`, ou execute `claude auth logout` para remover a chave salva. Depois peça para iniciar `claude` e fazer login com `/login`. Veja também [Administrator policy requires a Cloud gateway sign-in](/docs/pt/errors#administrator-policy-requires-a-cloud-gateway-sign-in). |
291| A inicialização ou `/login` relata `Claude Code may not be enabled for your organization` após um 403 no carregamento de configurações gerenciadas | O gateway, ou algo na frente dele, respondeu à solicitação `/managed/settings` com 403. A rota de configurações do próprio gateway nunca responde com 403. O status vem das verificações de IP [`access_control`](/docs/pt/claude-apps-gateway-config#http-tuning) ou de um proxy ou WAF na frente do gateway. O log de auditoria registra uma negação de verificação de IP como `access.denied` com o motivo. O desenvolvedor permanece conectado. | Verifique o log de auditoria para `access.denied` no momento da falha e corrija as listas `access_control` ou o front end, depois peça ao desenvolvedor para iniciar `claude` novamente |361| A inicialização ou `/login` relata `Claude Code may not be enabled for your organization` após um 403 no carregamento de configurações gerenciadas | O gateway, ou algo na frente dele, respondeu à solicitação `/managed/settings` com 403. A rota de configurações do próprio gateway nunca responde com 403. O status vem das verificações de IP [`access_control`](/docs/pt/claude-apps-gateway-config#http-tuning) ou de um proxy ou WAF na frente do gateway. O log de auditoria registra uma negação de verificação de IP como `access.denied` com o motivo. O desenvolvedor permanece conectado. | Verifique o log de auditoria para `access.denied` no momento da falha e corrija as listas `access_control` ou o front end, depois peça ao desenvolvedor para iniciar `claude` novamente |
362| CLI `/login`: `The gateway is limiting sign-in attempts right now`, ou `Request failed with status code 429` em versões mais antigas. A página `/device` pode mostrar `Too many attempts` para desenvolvedores que não tentaram antes | O limite de taxa de login por IP foi atingido. Ou `listen.trusted_proxies` não cobre o balanceador de carga, então cada desenvolvedor compartilha seu endereço, ou muitos desenvolvedores compartilham um endereço de saída NAT ou VPN. Eventos de auditoria com `result: rate_limited` mostram o mesmo um ou poucos valores `client_ip`. | Defina `listen.trusted_proxies` para os intervalos de origem do balanceador de carga primeiro, depois aumente `rate_limits` se desenvolvedores ainda compartilharem endereços. Veja [Large rollouts](#large-rollouts). |
292| CLI `/login`: `Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | O nome do host do gateway resolve para pelo menos um endereço IP público. Claude Code verifica cada endereço resolvido e requer que todos sejam privados. Uma causa comum é um nome dual-stack onde uma família resolve para um endereço público, incluindo balanceadores de carga dual-stack internos da AWS, que retornam endereços AAAA de intervalo público. | Faça com que o nome do gateway resolva apenas para endereços privados nas máquinas dos desenvolvedores. Para um nome dual-stack, remova o registro de intervalo público ou sirva um nome DNS separado apenas para interno. Veja o [pré-requisito de rede privada](/docs/pt/claude-apps-gateway#prerequisites). Se o endereço é espaço público que sua organização possui e usa internamente, [declare esse bloco](/docs/pt/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own) em vez disso. |363| CLI `/login`: `Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | O nome do host do gateway resolve para pelo menos um endereço IP público. Claude Code verifica cada endereço resolvido e requer que todos sejam privados. Uma causa comum é um nome dual-stack onde uma família resolve para um endereço público, incluindo balanceadores de carga dual-stack internos da AWS, que retornam endereços AAAA de intervalo público. | Faça com que o nome do gateway resolva apenas para endereços privados nas máquinas dos desenvolvedores. Para um nome dual-stack, remova o registro de intervalo público ou sirva um nome DNS separado apenas para interno. Veja o [pré-requisito de rede privada](/docs/pt/claude-apps-gateway#prerequisites). Se o endereço é espaço público que sua organização possui e usa internamente, [declare esse bloco](/docs/pt/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own) em vez disso. |
293| CLI `/login`: `Gateway login would go through proxy <proxy>, which is not on a private network` | Um `HTTPS_PROXY` ou `HTTP_PROXY` se aplica ao host do gateway e o nome do host do proxy resolve para um endereço público. Um proxy cujo host resolve apenas para endereços privados é permitido e não dispara esse erro | Adicione o host do gateway a `NO_PROXY` na máquina do desenvolvedor para que a conexão seja direta, ou use um proxy cujo nome do host resolve para endereços privados. A mensagem nomeia a entrada exata `NO_PROXY` a adicionar |364| CLI `/login`: `Gateway login would go through proxy <proxy>, which is not on a private network` | Um `HTTPS_PROXY` ou `HTTP_PROXY` se aplica ao host do gateway e o nome do host do proxy resolve para um endereço público. Um proxy cujo host resolve apenas para endereços privados é permitido e não dispara esse erro | Adicione o host do gateway a `NO_PROXY` na máquina do desenvolvedor para que a conexão seja direta, ou use um proxy cujo nome do host resolve para endereços privados. A mensagem nomeia a entrada exata `NO_PROXY` a adicionar |
294| CLI `/login`: `Claude Code only signs in to <host> from inside its declared network <block> (managed settings), and this machine is connecting from <ip>, outside it` | O gateway está em um bloco declarado em [`gatewayInternalNetworks`](/docs/pt/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own), e a máquina do desenvolvedor o alcançou de um endereço fora desse bloco: um pool de endereços VPN, um segmento NAT de container ou WSL2, ou uma rede que não é sua | Peça ao desenvolvedor para executar `/login` do SO host em sua rede. Se o endereço mostrado também é espaço público da sua organização, substitua a entrada do gateway por um bloco que cubra ambos, até `/8`; uma segunda entrada sobreposta é recusada |365| CLI `/login`: `Claude Code only signs in to <host> from inside its declared network <block> (managed settings), and this machine is connecting from <ip>, outside it` | O gateway está em um bloco declarado em [`gatewayInternalNetworks`](/docs/pt/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own), e a máquina do desenvolvedor o alcançou de um endereço fora desse bloco: um pool de endereços VPN, um segmento NAT de container ou WSL2, ou uma rede que não é sua | Peça ao desenvolvedor para executar `/login` do SO host em sua rede. Se o endereço mostrado também é espaço público da sua organização, substitua a entrada do gateway por um bloco que cubra ambos, até `/8`; uma segunda entrada sobreposta é recusada |
299| CLI `/login`: `Could not resolve gateway host <host>` | A máquina não consegue resolver o nome DNS interno do gateway, tipicamente porque não está na rede corporativa | Peça ao desenvolvedor para conectar à sua rede ou VPN, depois execute `/login` novamente |370| CLI `/login`: `Could not resolve gateway host <host>` | A máquina não consegue resolver o nome DNS interno do gateway, tipicamente porque não está na rede corporativa | Peça ao desenvolvedor para conectar à sua rede ou VPN, depois execute `/login` novamente |
300| Boot exits with a config validation error naming `store.postgres_url` | Nenhum Postgres configurado; o gateway requer Postgres | Defina `store.postgres_url`. Para desenvolvimento local, use um container descartável: `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`. |371| Boot exits with a config validation error naming `store.postgres_url` | Nenhum Postgres configurado; o gateway requer Postgres | Defina `store.postgres_url`. Para desenvolvimento local, use um container descartável: `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`. |
301| Boot exits: `requires the native binary` | Executando sob Node em vez do binário nativo | Instale Claude Code com um dos [métodos de instalação autônomos](/docs/pt/setup) |372| Boot exits: `requires the native binary` | Executando sob Node em vez do binário nativo | Instale Claude Code com um dos [métodos de instalação autônomos](/docs/pt/setup) |
302373| Boot exits with an OIDC discovery error after `config.load` | `oidc.issuer` inacessível, ou cadeia TLS não confiável | Verifique se o emissor é acessível do pod e serve `/.well-known/openid-configuration`. Defina `ca_cert_pem` para PKI privada. Se o pod alcança o IdP apenas através de um proxy direto, defina [`oidc.use_proxy: true`](/docs/pt/claude-apps-gateway-config#idp-requests-through-a-forward-proxy); em versões anteriores a v2.1.227, dê ao pod uma rota direta para cada um dos endpoints do IdP em vez disso. || Boot exits with an OIDC discovery error after `config.load` | `oidc.issuer` inacessível, ou cadeia TLS não confiável | Verifique se o emissor é acessível do pod e serve `/.well-known/openid-configuration`. Defina `ca_cert_pem` para PKI privada. Se o pod alcança o IdP apenas através de um proxy direto, defina [`oidc.use_proxy: true`](/docs/pt/claude-apps-gateway-config#idp-requests-through-a-forward-proxy); em versões anteriores a v2.1.227, dê ao pod uma rota direta para cada um dos endpoints do IdP em vez disso. Se o pod também não conseguir resolver o nome do host do IdP, ou o proxy recusar `CONNECT` para um endereço IP, veja [Proxy-only egress](/docs/pt/claude-apps-gateway-config#proxy-only-egress), que requer v2.1.277 ou posterior. |
303| Boot exits with a Postgres permission error | O papel do banco de dados carece de direitos DDL em seu schema | Conceda ao papel `CREATE` no schema do gateway para que possa criar e alterar suas tabelas na inicialização |374| Boot exits with a Postgres permission error | O papel do banco de dados carece de direitos DDL em seu schema | Conceda ao papel `CREATE` no schema do gateway para que possa criar e alterar suas tabelas na inicialização |
375| Log: `could not connect to Postgres at boot, attempt 1 of 3` | O banco de dados não estava acessível quando o gateway iniciou, por exemplo em uma instância fria cuja rede ainda está se iniciando | Se o gateway então terminar de inicializar, nenhuma ação é necessária. Quando o banco de dados não está acessível, o gateway tenta a conexão três vezes, dois segundos de intervalo, antes de sair. Se sair com `could not connect to Postgres`, verifique `store.postgres_url` e o caminho de rede para o banco de dados. Se as tentativas expirarem em vez de serem recusadas, aumente [`store.connect_timeout_seconds`](/docs/pt/claude-apps-gateway-config#store) para dar a cada uma mais tempo. |
304| `/oauth/callback` shows "Sign-in could not be completed" | Domínio de email rejeitado, validação de id\_token falhou, ou `email_verified` é explicitamente `false`, que o gateway sempre rejeita sem override | Verifique `allowed_email_domains` e que o IdP retorna uma reivindicação `email` verificada. Para `email_verified: false`, corrija a verificação do lado do IdP. Se seu IdP emite email sob um nome de reivindicação diferente, defina `oidc.email_claim`. |376| `/oauth/callback` shows "Sign-in could not be completed" | Domínio de email rejeitado, validação de id\_token falhou, ou `email_verified` é explicitamente `false`, que o gateway sempre rejeita sem override | Verifique `allowed_email_domains` e que o IdP retorna uma reivindicação `email` verificada. Para `email_verified: false`, corrija a verificação do lado do IdP. Se seu IdP emite email sob um nome de reivindicação diferente, defina `oidc.email_claim`. |
305| Log: `token exchange failed request_id=<id>: id_token missing email claim` | O IdP não está incluindo `email` no id\_token por padrão. Essa rejeição dispara apenas quando `allowed_email_domains` está definido; sem ele, um email ausente cria uma sessão sem email | Configure o IdP para emitir `email` no id\_token. Okta: adicione `email` às reivindicações de token de ID de um servidor de autorização personalizado. Entra: adicione `email` como uma reivindicação opcional no registro do aplicativo. PingFederate: ative uma Política OpenID Connect que emita `email`. Se o IdP serve `email` do endpoint userinfo mas não incluirá no id\_token, como o servidor de autorização da organização Okta, defina `oidc.userinfo_fallback: true`. |377| Log: `token exchange failed request_id=<id>: id_token missing email claim` | O IdP não está incluindo `email` no id\_token por padrão. Essa rejeição dispara apenas quando `allowed_email_domains` está definido; sem ele, um email ausente cria uma sessão sem email | Configure o IdP para emitir `email` no id\_token. Okta: adicione `email` às reivindicações de token de ID de um servidor de autorização personalizado. Entra: adicione `email` como uma reivindicação opcional no registro do aplicativo. PingFederate: ative uma Política OpenID Connect que emita `email`. Se o IdP serve `email` do endpoint userinfo mas não incluirá no id\_token, como o servidor de autorização da organização Okta, defina `oidc.userinfo_fallback: true`. |
306| Log: `refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`, e desenvolvedores veem `Cloud gateway session expired` a cada `session.ttl_hours` | O IdP aceitou o token de atualização mas não retornou id\_token com ele, então o gateway perguntou ao endpoint userinfo do IdP pelas reivindicações do usuário. O IdP rejeitou o token de acesso atualizado lá. O gateway responde `temporarily_unavailable`, então Claude Code mantém o token de atualização mas não consegue renovar a sessão. Versões do gateway anteriores a v2.1.260 registram a mesma linha sem o detalhe `(at …)`. | Defina [`oidc.scope_on_refresh: true`](/docs/pt/claude-apps-gateway-config#oidc), disponível no gateway v2.1.260 ou posterior, para que a solicitação de atualização peça por `openid` novamente. Alguns IdPs, como Okta, retornam um id\_token na atualização apenas quando solicitado. No PingFederate, ative **Return ID Token On Refresh Grant** sob **Applications > OAuth > OpenID Connect Policy Management** em vez disso. A chave não muda o comportamento do PingFederate. Para outros IdPs que ainda o omitem, verifique se o endpoint userinfo aceita tokens de acesso emitidos por uma atualização. Como uma solução temporária, aumente [`session.ttl_hours`](/docs/pt/claude-apps-gateway-config#session). Veja [Identity provider setup](#identity-provider-setup) para o tradeoff de desprovisionamento. |378| Log: `refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`, e desenvolvedores veem `Cloud gateway session expired` a cada `session.ttl_hours` | O IdP aceitou o token de atualização mas não retornou id\_token com ele, então o gateway perguntou ao endpoint userinfo do IdP pelas reivindicações do usuário. O IdP rejeitou o token de acesso atualizado lá. O gateway responde `temporarily_unavailable`, então Claude Code mantém o token de atualização mas não consegue renovar a sessão. Versões do gateway anteriores a v2.1.260 registram a mesma linha sem o detalhe `(at …)`. | Defina [`oidc.scope_on_refresh: true`](/docs/pt/claude-apps-gateway-config#oidc), disponível no gateway v2.1.260 ou posterior, para que a solicitação de atualização peça por `openid` novamente. Alguns IdPs, como Okta, retornam um id\_token na atualização apenas quando solicitado. No PingFederate, ative **Return ID Token On Refresh Grant** sob **Applications > OAuth > OpenID Connect Policy Management** em vez disso. A chave não muda o comportamento do PingFederate. Para outros IdPs que ainda o omitem, verifique se o endpoint userinfo aceita tokens de acesso emitidos por uma atualização. Como uma solução temporária, aumente [`session.ttl_hours`](/docs/pt/claude-apps-gateway-config#session). Veja [Identity provider setup](#identity-provider-setup) para o tradeoff de desprovisionamento. |
307| Every Amazon Bedrock request returns 502; log shows `Could not load credentials from any providers` | No EC2, o hop limit padrão do IMDSv2 de 1 bloqueia a solicitação de metadados de instância de dentro do container. Boot e `/readyz` passam mesmo assim porque o AWS SDK resolve credenciais de instância na primeira solicitação, não na construção do cliente | Aumente o hop limit com `aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2`, ou defina-o no modelo de lançamento. A mudança se aplica a cada container na instância. Prefira funções de tarefa ECS onde disponível, que leem credenciais do endpoint de credenciais do container ECS e evitam a mudança inteiramente, ou aplique a mudança em uma instância de gateway dedicada para limitar a exposição. |379| Every Amazon Bedrock request returns 502; log shows `Could not load credentials from any providers` | No EC2, o hop limit padrão do IMDSv2 de 1 bloqueia a solicitação de metadados de instância de dentro do container. Boot e `/readyz` passam mesmo assim porque o AWS SDK resolve credenciais de instância na primeira solicitação, não na construção do cliente | Aumente o hop limit com `aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2`, ou defina-o no modelo de lançamento. A mudança se aplica a cada container na instância. Prefira funções de tarefa ECS onde disponível, que leem credenciais do endpoint de credenciais do container ECS e evitam a mudança inteiramente, ou aplique a mudança em uma instância de gateway dedicada para limitar a exposição. |
380| At peak load, responses are slow to start or appear to hang, or fail with a 502 `all upstreams failed` while the upstream is healthy | Uma réplica tem mais solicitações abertas do que envia upstream de uma vez, então as solicitações extras esperam dentro do gateway. Em um upstream `provider: anthropic`, uma solicitação que espera mais tempo que `timeouts.upstream_ttfb_ms` desiste desse upstream, que produz o 502 quando nenhum upstream posterior a serve. O log mostra um aviso que contém `client requests are open`. | Adicione réplicas, ou aumente o limite em cada réplica. Veja [Concurrent upstream requests](#concurrent-upstream-requests). |
308| IdP error: unknown or unsupported scope | O IdP rejeita escopos que não reconhece | Defina `oidc.scopes` para exatamente a lista que seu IdP aceita; deve incluir `openid`. O padrão é `openid profile email offline_access`. |381| IdP error: unknown or unsupported scope | O IdP rejeita escopos que não reconhece | Defina `oidc.scopes` para exatamente a lista que seu IdP aceita; deve incluir `openid`. O padrão é `openid profile email offline_access`. |
309| Sessions don't silently renew after setting `oidc.scopes` | `offline_access` foi removido da substituição | Adicione `offline_access` de volta se seu IdP o suporta. Sem um token de atualização, desenvolvedores executam novamente o login do navegador a cada `session.ttl_hours`. |382| Sessions don't silently renew after setting `oidc.scopes` | `offline_access` foi removido da substituição | Adicione `offline_access` de volta se seu IdP o suporta. Sem um token de atualização, desenvolvedores executam novamente o login do navegador a cada `session.ttl_hours`. |
310| Browser shows "This request came from another site and was blocked" | POST de formulário entre sites, bloqueado como proteção CSRF. Esperado para páginas incorporadas ou proxied | Abra o link de verificação diretamente |383| Browser shows "This request came from another site and was blocked" | POST de formulário entre sites, bloqueado como proteção CSRF. Esperado para páginas incorporadas ou proxied | Abra o link de verificação diretamente |