Documentation 2026-10-06 23:59 UTC to 2026-10-07 02:00 UTC

75| - | - |75| - | - |

76| Claude Code v2.1.195 ou posterior | O subcomando `claude gateway` e o fluxo de sign-in do gateway são enviados na v2.1.195. Compilações públicas anteriores não as incluem. Tanto a máquina executando o servidor gateway quanto a máquina de cada desenvolvedor devem estar na v2.1.195 ou posterior; execute `claude update` para obter a versão mais recente. O [upstream Claude Platform on AWS](/docs/pt/claude-apps-gateway-config#claude-platform-on-aws) requer Claude Code v2.1.198 ou posterior no servidor gateway. |76| Claude Code v2.1.195 ou posterior | O subcomando `claude gateway` e o fluxo de sign-in do gateway são enviados na v2.1.195. Compilações públicas anteriores não as incluem. Tanto a máquina executando o servidor gateway quanto a máquina de cada desenvolvedor devem estar na v2.1.195 ou posterior; execute `claude update` para obter a versão mais recente. O [upstream Claude Platform on AWS](/docs/pt/claude-apps-gateway-config#claude-platform-on-aws) requer Claude Code v2.1.198 ou posterior no servidor gateway. |

77| Provedor de identidade OpenID Connect (OIDC) | Okta, Microsoft Entra ID, Google Workspace, Keycloak ou Dex, ou qualquer outro IdP compatível com OIDC, como PingFederate. O gateway executa descoberta OIDC padrão e o fluxo de código de autorização contra ele. SAML e LDAP não são suportados. |77| Provedor de identidade OpenID Connect (OIDC) | Okta, Microsoft Entra ID, Google Workspace, Keycloak ou Dex, ou qualquer outro IdP compatível com OIDC, como PingFederate. O gateway executa descoberta OIDC padrão e o fluxo de código de autorização contra ele. SAML e LDAP não são suportados. |

78| PostgreSQL 14 ou posterior | Faz backup do fluxo de sign-in do dispositivo, onde o callback do navegador escreve e a CLI de polling lê, além de contadores de limite de taxa. Qualquer Postgres gerenciado funciona, incluindo o menor nível. Sem limites de gastos configurados, o gateway armazena alguns KB de estado de autenticação de curta duração; com [limites de gastos](/docs/pt/claude-apps-gateway-spend-limits), também mantém tabelas de gastos, auditoria e identidade duráveis que devem ser feitas backup. TLS via `?sslmode=require` é recomendado. |78| PostgreSQL 11 ou posterior | Dá suporte ao fluxo de sign-in do dispositivo e aos contadores de rate limit. Um serviço PostgreSQL gerenciado funciona, incluindo o menor nível; consulte [quais bancos de dados são suportados](/docs/pt/claude-apps-gateway-deploy#postgres). Com [limites de gastos](/docs/pt/claude-apps-gateway-spend-limits), também mantém tabelas de gastos, auditoria e identidade duráveis que devem ter backup. TLS via `?sslmode=require` é recomendado. PostgreSQL 11, 12 e 13 requerem Claude Code v2.1.290 ou posterior no servidor gateway. O projeto PostgreSQL não mantém mais essas versões, então use uma mais recente sempre que possível. |

79| Upstream de modelo | Credenciais do Amazon Bedrock, credenciais do Claude Platform on AWS, credenciais do Google Cloud, um recurso Microsoft Foundry ou uma chave de API Anthropic. Múltiplos upstreams são suportados com failover. |79| Upstream de modelo | Credenciais do Amazon Bedrock, credenciais do Claude Platform on AWS, credenciais do Google Cloud, um recurso Microsoft Foundry ou uma chave de API Anthropic. Múltiplos upstreams são suportados com failover. |

80| HTTPS | O gateway deve ser acessível via `https://` de laptops de desenvolvedores e de qualquer navegador usado para sign-in; o gateway serve a página de verificação do dispositivo no mesmo listener. Forneça um certificado TLS via `listen.tls` ou execute atrás de um ingress que termina TLS e defina `listen.public_url` para a origem externa em ambos os casos. Uma origem `http://` simples é aceita apenas quando o host do gateway é loopback: `localhost`, `127.0.0.1` ou `::1`. |80| HTTPS | O gateway deve ser acessível via `https://` de laptops de desenvolvedores e de qualquer navegador usado para sign-in; o gateway serve a página de verificação do dispositivo no mesmo listener. Forneça um certificado TLS via `listen.tls` ou execute atrás de um ingress que termina TLS e defina `listen.public_url` para a origem externa em ambos os casos. Em `/login`, Claude Code aceita uma origem `http://` simples apenas quando o host do gateway é loopback: `localhost`, `127.0.0.1` ou `::1`. |

81| Endereço de rede privada | Em `/login`, Claude Code requer que o nome de host ou endereço IP do gateway resolva apenas para endereços privados: RFC 1918, link-local, CGNAT `100.64.0.0/10`, ULA IPv6 `fc00::/7` ou loopback. Para um gateway que você hospeda, qualquer endereço público fora de um bloco que você declara é rejeitado; consulte o [modelo de ameaça](/docs/pt/claude-apps-gateway-deploy#threat-model-summary) no guia de implantação. Se máquinas de desenvolvedores rotear HTTPS através de um proxy corporativo, o sign-in também requer que o host proxy resolva para endereços privados; se não resolver, adicione o host do gateway a `NO_PROXY` para que a CLI se conecte diretamente. Se sua rede interna for numerada a partir do espaço IPv4 público que sua organização possui, [declare esses blocos](#allow-a-gateway-on-public-address-space-you-own) para que `/login` aceite um gateway lá. |81| Endereço de rede privada | Em `/login`, Claude Code requer que o nome de host ou endereço IP do gateway resolva apenas para endereços privados: RFC 1918, link-local, CGNAT `100.64.0.0/10`, ULA IPv6 `fc00::/7` ou loopback. Para um gateway que você hospeda, qualquer endereço público fora de um bloco que você declara é rejeitado; consulte o [modelo de ameaça](/docs/pt/claude-apps-gateway-deploy#threat-model-summary) no guia de implantação. Se máquinas de desenvolvedores rotear HTTPS através de um proxy corporativo, o sign-in também requer que o host proxy resolva para endereços privados; se não resolver, adicione o host do gateway a `NO_PROXY` para que a CLI se conecte diretamente. Se sua rede interna for numerada a partir do espaço IPv4 público que sua organização possui, [declare esses blocos](#allow-a-gateway-on-public-address-space-you-own) para que `/login` aceite um gateway lá. |

82| Runtime Linux | O servidor gateway é executado apenas no binário Linux nativo. macOS funciona para desenvolvimento local. Windows não é suportado como plataforma de servidor. |82| Runtime Linux | O servidor gateway é executado apenas no binário Linux nativo. macOS funciona para desenvolvimento local. Windows não é suportado como plataforma de servidor. |

83 83 

91 </Step>91 </Step>

92 92 

93 <Step title="Provisione um banco de dados PostgreSQL">93 <Step title="Provisione um banco de dados PostgreSQL">

94 Qualquer Postgres 14 ou posterior funciona, incluindo o menor nível gerenciado. O gateway executa suas próprias migrações de esquema na inicialização, então o usuário do banco de dados precisa de direitos para criar e alterar tabelas; consulte [`store`](/docs/pt/claude-apps-gateway-config#store).94 Use PostgreSQL 11 ou posterior. O menor nível gerenciado é suficiente. O gateway executa suas próprias migrações de esquema na inicialização, então a função do banco de dados precisa de direitos para criar e alterar tabelas; consulte [`store`](/docs/pt/claude-apps-gateway-config#store).

95 </Step>95 </Step>

96 96 

97 <Step title="Escreva gateway.yaml">97 <Step title="Escreva gateway.yaml">

132 auto_include_builtin_models: true132 auto_include_builtin_models: true

133 ```133 ```

134 134 

135 Esta configuração é suficiente para um loop de sign-in funcionando com o catálogo de modelos Bedrock padrão. Uma vez em execução, adicione RBAC por grupo e configurações gerenciadas via [`managed.policies`](/docs/pt/claude-apps-gateway-config#managed), fan-out de telemetria via [`telemetry`](/docs/pt/claude-apps-gateway-config#telemetry), e failover multi-upstream, ARNs de throughput provisionado ou regiões não-US via [`models`](/docs/pt/claude-apps-gateway-config#models).135 Esta configuração é suficiente para um loop de sign-in funcionando com o catálogo de modelos Amazon Bedrock padrão. Uma vez em execução, adicione RBAC por grupo e configurações gerenciadas via [`managed.policies`](/docs/pt/claude-apps-gateway-config#managed), fan-out de telemetria via [`telemetry`](/docs/pt/claude-apps-gateway-config#telemetry), e failover multi-upstream, ARNs de throughput provisionado ou regiões não-US via [`models`](/docs/pt/claude-apps-gateway-config#models).

136 136 

137 <Note>137 <Note>

138 O upstream Amazon Bedrock precisa de um principal AWS com `bedrock:InvokeModel` e `bedrock:InvokeModelWithResponseStream` nos ARNs `inference-profile/us.anthropic.*` e nos ARNs `foundation-model/anthropic.*` subjacentes. Ele também precisa do formulário de caso de uso único da Anthropic enviado para a conta a partir do catálogo de modelos do console Bedrock.138 O upstream Amazon Bedrock precisa de um principal AWS com `bedrock:InvokeModel` e `bedrock:InvokeModelWithResponseStream` nos ARNs `inference-profile/us.anthropic.*` e nos ARNs `foundation-model/anthropic.*` subjacentes. Ele também precisa do formulário de caso de uso único da Anthropic enviado para a conta a partir do catálogo de modelos do console Bedrock.

172 volumes: { pgdata: }172 volumes: { pgdata: }

173 ```173 ```

174 174 

175 O gateway é um único binário Linux que lê a configuração, se conecta ao Postgres e aplica suas migrações de esquema, executa descoberta OIDC contra seu IdP, constrói clientes upstream e começa a escutar. A inicialização é fail-closed para a configuração, a conexão Postgres, descoberta OIDC e construção de cliente upstream. Se qualquer um desses for inacessível ou mal configurado, o gateway sai com um erro em vez de servir tráfego em um estado degradado.175 O gateway é um único binário Linux que lê a configuração, se conecta ao Postgres e aplica suas migrações de esquema, executa descoberta OIDC contra seu IdP, constrói clientes upstream e começa a escutar.

176 176 

177 Uma inicialização bem-sucedida não valida o caminho de inferência, porque credenciais de instância Bedrock e Agent Platform resolvem na primeira solicitação, não na inicialização.177 A inicialização é fail-closed para a configuração, a conexão Postgres, descoberta OIDC e construção de cliente upstream. Se qualquer um desses for inacessível ou mal configurado, o gateway sai com um erro em vez de servir tráfego em um estado degradado.

178 

179 Uma inicialização bem-sucedida não valida o caminho de inferência, porque credenciais de instância do Amazon Bedrock e da Agent Platform do Google Cloud resolvem na primeira requisição, não na inicialização.

178 180 

179 Observe stderr para a sequência de inicialização. As linhas de log usam o formato `[gateway] <timestamp> <level> <message>`, eventos de auditoria são JSON de linha única com um campo `evt`, e um banner de inicialização, omitido abaixo, é impresso entre as linhas de migração e escuta. Um banco de dados novo imprime uma linha `migration N applied` por migração de esquema; um banco de dados já migrado não imprime nenhuma. Você deve ver, em ordem:181 Observe stderr para a sequência de inicialização. As linhas de log usam o formato `[gateway] <timestamp> <level> <message>`, eventos de auditoria são JSON de linha única com um campo `evt`, e um banner de inicialização, omitido abaixo, é impresso entre as linhas de migração e escuta. Um banco de dados novo imprime uma linha `migration N applied` por migração de esquema; um banco de dados já migrado não imprime nenhuma. Você deve ver, em ordem:

180 182 

206 208 

207 Os exemplos usam a URL pública do gateway; para a configuração local do Compose sem um ingress, substitua `http://localhost:8080` nas duas primeiras verificações. A terceira verificação abre `verification_uri_complete`, que é construída a partir de `public_url`, então para Compose local defina `public_url: http://localhost:8080` em `gateway.yaml` e adicione `http://localhost:8080/oauth/callback` como um segundo URI de redirecionamento no cliente OAuth da etapa 1, porque o gateway constrói o `redirect_uri` do IdP a partir de `public_url`. O link de verificação então abre em seu navegador local.209 Os exemplos usam a URL pública do gateway; para a configuração local do Compose sem um ingress, substitua `http://localhost:8080` nas duas primeiras verificações. A terceira verificação abre `verification_uri_complete`, que é construída a partir de `public_url`, então para Compose local defina `public_url: http://localhost:8080` em `gateway.yaml` e adicione `http://localhost:8080/oauth/callback` como um segundo URI de redirecionamento no cliente OAuth da etapa 1, porque o gateway constrói o `redirect_uri` do IdP a partir de `public_url`. O link de verificação então abre em seu navegador local.

208 210 

209 No Windows PowerShell, execute `curl.exe`; o `curl` simples é um alias para `Invoke-WebRequest` e rejeita esses sinalizadores.211 No Windows PowerShell, execute `curl.exe`; o `curl` simples é um alias para `Invoke-WebRequest` e rejeita essas flags.

210 212 

211 Primeiro, busque o documento de descoberta, que confirma que o gateway está ativo, a configuração é válida e todas as verificações de inicialização passaram:213 Primeiro, busque o documento de descoberta, que confirma que o gateway está ativo, a configuração é válida e todas as verificações de inicialização passaram:

212 214 

158O gateway lê a chave e o certificado uma vez na inicialização, portanto um arquivo alterado só tem efeito após uma reinicialização. Faça a rotação nesta ordem para que nenhuma requisição de token apresente um certificado que o IdP não tenha:158O gateway lê a chave e o certificado uma vez na inicialização, portanto um arquivo alterado só tem efeito após uma reinicialização. Faça a rotação nesta ordem para que nenhuma requisição de token apresente um certificado que o IdP não tenha:

159 159 

1601. Envie o novo certificado para o IdP junto com o antigo.1601. Envie o novo certificado para o IdP junto com o antigo.

1612. Substitua os arquivos de chave e certificado que o `gateway.yaml` carrega e, em seguida, reinicie o gateway.1612. Substitua os arquivos de chave e certificado que o `gateway.yaml` carrega e, em seguida, reinicie o gateway. Se você executa várias réplicas, uma [reinicialização gradual](/docs/pt/claude-apps-gateway-deploy#upgrades) funciona, porque o IdP tem ambos os certificados até que você remova o antigo.

1623. Remova o certificado antigo do IdP.1623. Depois que todas as réplicas tiverem reiniciado, remova o certificado antigo do IdP.

163 163 

164<h4 id="idp-requests-through-a-forward-proxy">164<h4 id="idp-requests-through-a-forward-proxy">

165 Solicitações do IdP através de um proxy de encaminhamento165 Solicitações do IdP através de um proxy de encaminhamento

227 227 

228| Campo | Obrigatório | Descrição |228| Campo | Obrigatório | Descrição |

229| - | - | - |229| - | - | - |

230| `postgres_url` | Sim | URL `postgres://` ou `postgresql://`. Obrigatório: o encontro de concessão de dispositivo, onde o callback do navegador escreve e o CLI de sondagem lê, precisa de estado entre réplicas. O gateway executa suas próprias migrações de esquema na inicialização e na atualização, portanto a função precisa de direitos para criar e alterar tabelas no esquema de destino. Consulte [Atualizações](/docs/pt/claude-apps-gateway-deploy#upgrades) e [Postgres](/docs/pt/claude-apps-gateway-deploy#postgres). |230| `postgres_url` | Sim | URL `postgres://` ou `postgresql://` com um único host, não uma lista separada por vírgulas. O gateway executa suas próprias migrações de esquema na inicialização e na atualização, portanto a função precisa de direitos para criar e alterar tabelas no esquema de destino. Consulte [Atualizações](/docs/pt/claude-apps-gateway-deploy#upgrades) e [Postgres](/docs/pt/claude-apps-gateway-deploy#postgres). |

231| `username` | Não | Substitui o usuário em `postgres_url` |231| `username` | Não | Substitui o usuário em `postgres_url` |

232| `password` | Não | Credencial do banco de dados. Defina aqui em vez de em `postgres_url` para que a credencial fique fora da URL. Aceita qualquer caractere e tem precedência sobre credenciais de URL. |232| `password` | Não | Credencial do banco de dados. Defina aqui em vez de em `postgres_url` para que a credencial fique fora da URL. Aceita qualquer caractere e tem precedência sobre credenciais de URL. |

233| `max_connections` | Não | Tamanho do pool de conexão Postgres por réplica. Padrão `5`, que é conservador e amigável para bancos de dados compartilhados. Com [limites de gastos](#admin) habilitados, o caminho quente faz algumas operações por solicitação de inferência, portanto aumente para um banco de dados dedicado sob carga e mantenha réplicas × isto abaixo do `max_connections` do banco de dados. |233| `max_connections` | Não | Tamanho do pool de conexão Postgres por réplica. Padrão `5`, que é conservador e amigável para bancos de dados compartilhados. Com [limites de gastos](#admin) habilitados, o caminho quente faz algumas operações por solicitação de inferência, portanto aumente para um banco de dados dedicado sob carga e mantenha réplicas × isto abaixo do `max_connections` do banco de dados. |

249 Postgres249 Postgres

250</h3>250</h3>

251 251 

252O gateway armazena seu estado em um banco de dados PostgreSQL:

253 

254* **Banco de dados**: o próprio PostgreSQL, auto-hospedado ou gerenciado, na [versão mínima](/docs/pt/claude-apps-gateway#prerequisites) ou posterior. Bancos de dados que apenas implementam o protocolo Postgres, como bancos de dados SQL distribuídos, não são suportados.

255* **Endereço**: `store.postgres_url` aceita um único host. Se o banco de dados tiver vários nós, use o endereço que fica na frente deles, como o endpoint do seu serviço gerenciado, um balanceador de carga ou um IP virtual. Defina um [período de carência de prontidão](#readiness-grace-period) mais longo do que um failover leva.

256 

252O gateway mantém cinco tabelas de dados mais uma tabela `_migrations`, todas criadas por suas migrações de tempo de inicialização:257O gateway mantém cinco tabelas de dados mais uma tabela `_migrations`, todas criadas por suas migrações de tempo de inicialização:

253 258 

254| Tabela | Conteúdo | Retenção |259| Tabela | Conteúdo | Retenção |

396| CLI `/login`: `Could not resolve the configured HTTP proxy` | O nome do host em `HTTPS_PROXY` ou `HTTP_PROXY` não resolve da máquina do desenvolvedor, tipicamente porque não está conectado à rede corporativa | Peça ao desenvolvedor para conectar à sua rede ou VPN e tentar novamente, ou corrija a URL do proxy |401| CLI `/login`: `Could not resolve the configured HTTP proxy` | O nome do host em `HTTPS_PROXY` ou `HTTP_PROXY` não resolve da máquina do desenvolvedor, tipicamente porque não está conectado à rede corporativa | Peça ao desenvolvedor para conectar à sua rede ou VPN e tentar novamente, ou corrija a URL do proxy |

397| 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 |402| 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 |

398| A inicialização sai com um erro de validação de configuração que nomeia `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`. |403| A inicialização sai com um erro de validação de configuração que nomeia `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`. |

404| A inicialização sai: `store.postgres_url in <path> is not a URL the gateway can read`, ou, antes da v2.1.290, um simples `Invalid URL` ou `URI error` | A URL não pode ser analisada, por exemplo porque lista mais de um host ou sua senha tem um `/`, `?`, `#` ou `%` não codificado | Nomeie [um host](#postgres), e mova a senha para [`store.password`](/docs/pt/claude-apps-gateway-config#store) |

399| A inicialização sai: `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) |405| A inicialização sai: `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) |

400| A inicialização sai com um erro de descoberta OIDC após `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 forward proxy, 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. |406| A inicialização sai com um erro de descoberta OIDC após `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 forward proxy, 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. |

401| A inicialização sai com um erro de permissão do Postgres | O papel do banco de dados carece de direitos DDL em seu esquema | Conceda ao papel `CREATE` no esquema do gateway para que possa criar e alterar suas tabelas na inicialização |407| A inicialização sai com um erro de permissão do Postgres | O papel do banco de dados carece de direitos DDL em seu esquema | Conceda ao papel `CREATE` no esquema do gateway para que possa criar e alterar suas tabelas na inicialização |

402| 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 atingirem o timeout em vez de serem recusadas, aumente [`store.connect_timeout_seconds`](/docs/pt/claude-apps-gateway-config#store) para dar a cada uma mais tempo. |408| 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`, incluindo se ela nomeia um único host, e o caminho de rede para o banco de dados. Se as tentativas atingirem o timeout em vez de serem recusadas, aumente [`store.connect_timeout_seconds`](/docs/pt/claude-apps-gateway-config#store) para dar a cada uma mais tempo. |

403| `/oauth/callback` mostra "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 possibilidade de sobrescrever | 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`. |409| `/oauth/callback` mostra "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 possibilidade de sobrescrever | 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`. |

404| 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 o incluirá no id\_token, como o servidor de autorização da organização Okta, defina `oidc.userinfo_fallback: true`. |410| 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 o incluirá no id\_token, como o servidor de autorização da organização Okta, defina `oidc.userinfo_fallback: true`. |

405| 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 requisiçã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. |411| 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 requisiçã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. |

169 </Step>169 </Step>

170 170 

171 <Step title="Provisione Amazon RDS para PostgreSQL">171 <Step title="Provisione Amazon RDS para PostgreSQL">

172 A instância é executada nas subnets privadas sem endereço público e com criptografia de armazenamento ativada. A versão do mecanismo é fixada em Postgres 16, que satisfaz o piso suportado do gateway de PostgreSQL 14 e garante que a família do grupo de parâmetros abaixo corresponda à instância.172 A instância executa o Postgres 16 nas subnets privadas, sem endereço público e com criptografia de armazenamento ativada.

173 173 

174 Primeiro, crie o grupo de subnets que coloca o banco de dados nas subnets privadas e um grupo de parâmetros com `rds.force_ssl=1` para que o servidor rejeite conexões em texto simples. A versão do mecanismo é fixada uma vez porque a família do grupo de parâmetros deve corresponder à versão principal do mecanismo que a instância executa:174 Primeiro, crie o grupo de subnets que coloca o banco de dados nas subnets privadas e um grupo de parâmetros com `rds.force_ssl=1` para que o servidor rejeite conexões em texto simples. A versão do mecanismo é fixada uma vez porque a família do grupo de parâmetros deve corresponder à versão principal do mecanismo que a instância executa:

175 175 

83* Terminal: `claude --continue`, `claude --resume <session-id>` ou `claude --resume <name>` quando o nome corresponde a uma sessão, sem `-p`. Claude Code restaura o modo de permissão em que a sessão estava, exceto nos casos da tabela. Passe `--permission-mode` ou `--dangerously-skip-permissions` para substituir o modo restaurado.83* Terminal: `claude --continue`, `claude --resume <session-id>` ou `claude --resume <name>` quando o nome corresponde a uma sessão, sem `-p`. Claude Code restaura o modo de permissão em que a sessão estava, exceto nos casos da tabela. Passe `--permission-mode` ou `--dangerously-skip-permissions` para substituir o modo restaurado.

84* Não interativo: `claude -p --resume` ou `claude -p --continue`. Claude Code inicia a execução no modo de permissão em que uma nova execução `claude -p` iniciaria, exceto que uma sessão que terminou em modo de plano retoma em modo de plano sob as [condições abaixo](#resume-in-plan-mode-with-p).84* Não interativo: `claude -p --resume` ou `claude -p --continue`. Claude Code inicia a execução no modo de permissão em que uma nova execução `claude -p` iniciaria, exceto que uma sessão que terminou em modo de plano retoma em modo de plano sob as [condições abaixo](#resume-in-plan-mode-with-p).

85* VS Code: o painel de conversa da extensão. A tabela cobre apenas uma conversa que terminou em modo de plano; para o resto, veja [retomar conversas passadas](/docs/pt/vs-code#resume-past-conversations).85* VS Code: o painel de conversa da extensão. A tabela cobre apenas uma conversa que terminou em modo de plano; para o resto, veja [retomar conversas passadas](/docs/pt/vs-code#resume-past-conversations).

86* Seletor de sessão no lançamento: uma sessão que você seleciona do [seletor de sessão](#use-the-session-picker), se você o abriu com `claude --resume` sozinho, `claude --from-pr` ou um nome que corresponde a mais de uma sessão. Claude Code não restaura o modo de permissão armazenado. Ele inicia a sessão no modo de permissão em que iniciaria uma nova sessão a partir da mesma linha de comando.86* Seletor de sessão no lançamento: uma sessão que você seleciona do [seletor de sessão](#use-the-session-picker), se você o abriu com `claude --resume` sozinho, `claude --from-pr` ou um nome que corresponde a mais de uma sessão. Claude Code inicia a sessão no modo de permissão em que iniciaria uma nova sessão a partir da mesma linha de comando, exceto que uma sessão que terminou em modo de planejamento retoma em modo de planejamento, a menos que você passe `--permission-mode`, `--dangerously-skip-permissions` ou `--fork-session`. Nenhum outro modo de permissão armazenado é restaurado.

87* `/resume` dentro de uma sessão, com ou sem um argumento: Claude Code não restaura o modo de permissão armazenado. A conversa para a qual você alterna continua no modo de permissão em que sua sessão atual está.87* `/resume` dentro de uma sessão, com ou sem um argumento: a conversa para a qual você alterna continua no modo de permissão em que sua sessão atual está, exceto que uma conversa que terminou em modo de planejamento retoma em modo de planejamento, mesmo que você tenha iniciado Claude Code com `--permission-mode` ou `--dangerously-skip-permissions`. Se essa conversa já estava aberta anteriormente nesta execução de Claude Code, como a conversa em que você começou ou uma que você deixou com `/clear` ou `/resume`, ela continua no seu modo de permissão atual em vez disso.

88 88 

89Restaurar modo de plano nos caminhos não interativo e VS Code requer Claude Code v2.1.246 ou posterior. Cada linha nomeia o modo de permissão em que a sessão terminou, qual dos caminhos terminal, não interativo e VS Code você a retoma, e o modo de permissão em que Claude Code inicia a sessão retomada.89Restaurar modo de plano nos caminhos não interativo e VS Code requer Claude Code v2.1.246 ou posterior. Cada linha nomeia o modo de permissão em que a sessão terminou, qual dos caminhos terminal, não interativo e VS Code você a retoma, e o modo de permissão em que Claude Code inicia a sessão retomada.

90 90 

91| Sessão terminou em | Como você retoma | Modo de permissão após você retomar |91| Sessão terminou em | Como você retoma | Modo de permissão após você retomar |

92| :- | :- | :- |92| :- | :- | :- |

93| `bypassPermissions` | Terminal | O modo de permissão em que uma nova sessão iniciaria. Para [ignorar permissões](/docs/pt/permission-modes#skip-all-checks-with-bypasspermissions-mode) novamente, ative-o no lançamento com uma de suas flags de lançamento ou `permissions.defaultMode: "bypassPermissions"` em [configurações de usuário, `--settings` ou gerenciadas](/docs/pt/settings-reference#permissions-defaultmode) |93| `bypassPermissions` | Terminal | O modo de permissão em que uma nova sessão iniciaria. Para [ignorar permissões](/docs/pt/permission-modes#skip-all-checks-with-bypasspermissions-mode) novamente, ative-o no lançamento com uma de suas flags de lançamento ou `permissions.defaultMode: "bypassPermissions"` em [configurações de usuário, `--settings` ou gerenciadas](/docs/pt/settings-reference#permissions-defaultmode) |

94| `plan` | Terminal | O modo de permissão em que uma nova sessão iniciaria |94| `plan` | Terminal | Modo de planejamento. Com `--fork-session`, o modo de permissão em que uma nova sessão iniciaria |

95| `auto` | Terminal | `auto`, apenas quando sua conta ainda atende aos [requisitos do modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) |95| `auto` | Terminal | `auto`, apenas quando sua conta ainda atende aos [requisitos do modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) |

96| Manual | Terminal | Manual quando uma nova sessão iniciaria em modo auto a partir do [padrão integrado](/docs/pt/permission-modes#which-mode-a-session-starts-in). Quando um `defaultMode` de um arquivo de configurações [entra em vigor](/docs/pt/permission-modes#which-mode-a-session-starts-in), Claude Code inicia a sessão retomada nesse modo |96| Manual | Terminal | Manual quando uma nova sessão iniciaria em modo auto a partir do [padrão integrado](/docs/pt/permission-modes#which-mode-a-session-starts-in). Quando um `defaultMode` de um arquivo de configurações [entra em vigor](/docs/pt/permission-modes#which-mode-a-session-starts-in), Claude Code inicia a sessão retomada nesse modo |

97| `plan` | Não interativo, sob as [condições abaixo](#resume-in-plan-mode-with-p) | Modo de plano |97| `plan` | Não interativo, sob as [condições abaixo](#resume-in-plan-mode-with-p) | Modo de plano |