50 50
51### `listen`51### `listen`
52 52
53O bloco `listen` controla onde o gateway serve: o endereço de vinculação e porta, a origem visível externamente e terminação TLS opcional.53O bloco `listen` controla onde o gateway atende: o endereço e a porta de bind, a origem visível externamente e a terminação TLS opcional.
54 54
55| Campo | Obrigatório | Descrição |55| Campo | Obrigatório | Descrição |
56| - | - | - |56| - | - | - |
57| `host` | Não | Endereço de vinculação. Padrão `0.0.0.0`. |57| `host` | Não | Endereço de bind. Padrão `0.0.0.0`. |
58| `port` | Não | Porta de vinculação. Padrão `8080`. |58| `port` | Não | Porta de bind. Padrão `8080`. |
59| `public_url` | A menos que `host` seja loopback | A origem `https://` visível externamente, usada para construir o `redirect_uri` do IdP e metadados de descoberta. Obrigatório sempre que `host` não for um endereço de loopback, seja TLS terminado em um proxy como um ALB, Ingress ou Cloud Run ou no próprio gateway através de `tls`, porque o gateway nunca deriva sua própria origem de cabeçalhos `X-Forwarded-*`; eles são falsificáveis pelo cliente. Falha na inicialização sem ele. `trusted_proxies` abaixo governa apenas a resolução de IP do cliente. Também obrigatório para habilitar [telemetria](#telemetry), porque o gateway constrói o endpoint OTLP que envia para clientes a partir desta URL. |59| `public_url` | A menos que `host` seja loopback | A origem `https://` visível externamente, usada para montar o `redirect_uri` do IdP e os metadados de descoberta. Obrigatório sempre que `host` não for um endereço de loopback, seja o TLS terminado em um proxy como um ALB, Ingress ou Cloud Run, seja no próprio gateway por meio de `tls`, porque o gateway nunca deriva sua própria origem dos cabeçalhos `X-Forwarded-*`; eles podem ser falsificados pelo cliente. A inicialização falha sem ele. `trusted_proxies`, abaixo, rege apenas a resolução do IP do cliente. Também é obrigatório para ativar a [telemetria](#telemetry), porque o gateway monta a partir desta URL o endpoint OTLP que envia aos clientes. |
60| `tls.cert` / `tls.key` | Não | Caminhos PEM se o gateway termina TLS por si mesmo |60| `tls.cert` / `tls.key` | Não | Caminhos PEM, caso o próprio gateway termine o TLS |
61| `trusted_proxies` | Não | CIDRs ou IPs de balanceadores de carga na frente do gateway. Quando definido, o gateway confia em `X-Forwarded-For` apenas desses pares e registra o IP do cliente real para rate limiting por IP e auditoria. Equivalente ao nginx `set_real_ip_from`. Entradas `X-Forwarded-For` escritas como `ipv4:port` ou `[ipv6]:port`, como alguns balanceadores de carga fazem, são lidas com a porta descartada. Um endereço IPv6 com uma porta anexada e sem colchetes pode ser lido como um endereço diferente ou não ser lido, portanto desative a opção de porta em qualquer proxy que escreva esse formulário. |61| `trusted_proxies` | Não | CIDRs ou IPs dos balanceadores de carga à frente do gateway. Quando definido, o gateway confia em `X-Forwarded-For` somente vindo desses pares e registra o IP real do cliente para rate limiting por IP e auditoria. Equivalente ao `set_real_ip_from` do nginx. Entradas de `X-Forwarded-For` escritas como `ipv4:port` ou `[ipv6]:port`, como alguns balanceadores de carga fazem, são lidas descartando a porta. Um endereço IPv6 com uma porta anexada e sem colchetes pode ser lido como um endereço diferente ou nem ser lido, então desative a opção de porta em qualquer proxy que escreva nesse formato. |
62 62
63### `oidc`63### `oidc`
64 64
65O bloco `oidc` conecta o gateway ao seu provedor de identidade e decide quem pode fazer login. Ele nomeia o emissor e cliente OAuth, mapeia as declarações que carregam email e grupos e restringe o login por domínio de email ou grupo.65O bloco `oidc` conecta o gateway ao seu provedor de identidade e decide quem pode fazer login. Ele nomeia o emissor e o cliente OAuth, mapeia as claims que carregam e-mail e grupos e restringe o login por domínio de e-mail ou grupo.
66 66
67OpenID Connect (OIDC) é o protocolo SSO que o gateway usa com seu provedor de identidade; consulte [Configuração do provedor de identidade](https://code.claude.com/docs/pt/claude-apps-gateway-deploy.md#identity-provider-setup) para saber o que registrar no lado do IdP.67OpenID Connect (OIDC) é o protocolo de SSO que o gateway usa com seu provedor de identidade; consulte [Configuração do provedor de identidade](https://code.claude.com/docs/pt/claude-apps-gateway-deploy.md#identity-provider-setup) para saber o que registrar no lado do IdP.
68 68
69| Campo | Obrigatório | Descrição |69| Campo | Obrigatório | Descrição |
70| - | - | - |70| - | - | - |
71| `issuer` | Sim | Base de descoberta OIDC. Deve servir descoberta em `/.well-known/openid-configuration`. Use HTTPS em produção; o gateway aceita um emissor `http://`. Um emissor de loopback como `http://localhost:8081` é rejeitado pela [proteção SSRF](https://code.claude.com/docs/pt/claude-apps-gateway-deploy.md#threat-model-summary) a menos que `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1` esteja definido no ambiente do gateway. |71| `issuer` | Sim | Base de descoberta OIDC. Deve servir a descoberta em `/.well-known/openid-configuration`. Use HTTPS em produção; o gateway aceita um emissor `http://`. Um emissor de loopback como `http://localhost:8081` é rejeitado pela [proteção contra SSRF](https://code.claude.com/docs/pt/claude-apps-gateway-deploy.md#threat-model-summary), a menos que `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1` esteja definido no ambiente do gateway. |
72| `client_id` | Sim | Do seu registro de cliente OAuth |72| `client_id` | Sim | Do registro do seu cliente OAuth |
73| `client_secret` | A menos que `token_endpoint_auth_method` seja `private_key_jwt` | Do seu registro de cliente OAuth. Omita-o quando você usar [autenticação de cliente por certificado](#certificate-client-authentication). |73| `client_secret` | A menos que `token_endpoint_auth_method` seja `private_key_jwt` | Do registro do seu cliente OAuth. Omita-o ao usar [autenticação de cliente por certificado](#certificate-client-authentication). |
74| `allowed_email_domains` | Não | Rejeite id\_tokens cuja declaração `email` não esteja em um desses domínios, insensível a maiúsculas/minúsculas. Defesa em profundidade contra configuração incorreta de IdP multi-tenant. Independentemente dessa configuração, um id\_token cuja declaração `email_verified` é explicitamente `false` é sempre rejeitado. |74| `allowed_email_domains` | Não | Rejeita id\_tokens cuja claim `email` não esteja em um desses domínios, sem diferenciar maiúsculas de minúsculas. Defesa em profundidade contra configuração incorreta de IdP multi-tenant. Independentemente desta configuração, um id\_token cuja claim `email_verified` seja explicitamente `false` é sempre rejeitado. |
75| `allowed_groups` | Não | Restrinja o login a membros desses grupos IdP, comparados com `groups_claim`. Um usuário em um domínio de email permitido mas em nenhum desses grupos é rejeitado. Requer que o IdP emita a declaração de grupos. A correspondência é uma comparação de string exata e sensível a maiúsculas/minúsculas contra os valores nessa declaração, e o gateway não expande grupos aninhados: para admitir membros de um subgrupo, liste o subgrupo aqui ou configure o IdP para emitir associação achatada. |75| `allowed_groups` | Não | Restringe o login a membros destes grupos do IdP, comparados com `groups_claim`. Um usuário em um domínio de e-mail permitido, mas em nenhum desses grupos, é rejeitado. Requer que o IdP emita a claim de grupos. A correspondência é uma comparação exata de strings, diferenciando maiúsculas de minúsculas, com os valores dessa claim, e o gateway não expande grupos aninhados: para admitir membros de um subgrupo, liste o subgrupo aqui ou configure o IdP para emitir a associação achatada. |
76| `groups_claim` | Não | Qual declaração id\_token carrega associação de grupo. Padrão `groups`. Microsoft Entra emite funções de aplicativo sob `roles`. Aceita uma chave simples ou um JSON Pointer RFC 6901 como `/resource_access/gateway/roles` para declarações aninhadas. |76| `groups_claim` | Não | Qual claim do id\_token carrega a associação a grupos. Padrão `groups`. O Microsoft Entra emite app roles sob `roles`. Aceita uma chave simples ou um JSON Pointer RFC 6901 como `/resource_access/gateway/roles` para claims aninhadas. |
77| `google_groups` | Não | Procure os grupos do usuário conectado através da API do Diretório do Google Workspace Admin SDK, porque o id\_token do Google não carrega nenhuma declaração de grupos. Defina `service_account_json_path` para um arquivo de chave de conta de serviço com delegação em todo o domínio no escopo `https://www.googleapis.com/auth/admin.directory.group.readonly` e `admin_email` para um administrador do Workspace que a conta de serviço representa; a API do Diretório requer um assunto de administrador real. Os endereços de email do grupo de cada usuário se tornam sua declaração de grupos, portanto `allowed_groups` e `managed.policies.match.groups` correspondem aos emails do grupo. |77| `google_groups` | Não | Consulta os grupos do usuário conectado por meio da Directory API do Google Workspace Admin SDK, porque o id\_token do Google não carrega claim de grupos. Defina `service_account_json_path` como um arquivo de chave de conta de serviço com delegação em todo o domínio no escopo `https://www.googleapis.com/auth/admin.directory.group.readonly`, e `admin_email` como um administrador do Workspace que a conta de serviço personifica; a Directory API exige um sujeito administrador real. Os endereços de e-mail dos grupos de cada usuário se tornam sua claim de grupos, então `allowed_groups` e `managed.policies.match.groups` fazem a correspondência por e-mails de grupo. |
78| `email_claim` | Não | Qual declaração id\_token carrega o email do usuário. Padrão `email`. Alguns IdPs, como ADFS e Entra B2C, emitem `upn` ou `preferred_username`. Aceita uma chave simples, um JSON Pointer ou uma lista de chaves de fallback onde a primeira chave presente é usada. |78| `email_claim` | Não | Qual claim do id\_token carrega o e-mail do usuário. Padrão `email`. Alguns IdPs, como ADFS e Entra B2C, emitem `upn` ou `preferred_username` em vez disso. Aceita uma chave simples, um JSON Pointer ou uma lista de chaves de fallback em que a primeira chave presente é usada. |
79| `scopes` | Não | Substituição completa dos escopos OIDC que o gateway solicita. Padrão `[openid, profile, email, offline_access]`. Defina quando seu IdP rejeita escopos que não reconhece ou requer um escopo personalizado para emitir grupos ou email. Deve incluir `openid`. Descartar `offline_access` desabilita tokens de atualização, portanto os desenvolvedores executam novamente o login do navegador a cada `session.ttl_hours`. Consulte [Configuração do provedor de identidade](https://code.claude.com/docs/pt/claude-apps-gateway-deploy.md#identity-provider-setup) para receitas de escopo por IdP, como o fluxo de token de atualização do Google. |79| `scopes` | Não | Sobrescrita completa dos escopos OIDC que o gateway solicita. Padrão `[openid, profile, email, offline_access]`. Defina quando seu IdP rejeitar escopos que não reconhece ou exigir um escopo personalizado para emitir grupos ou e-mail. Deve incluir `openid`. Remover `offline_access` desativa os refresh tokens, de modo que os desenvolvedores refazem o login no navegador a cada `session.ttl_hours`. Consulte [Configuração do provedor de identidade](https://code.claude.com/docs/pt/claude-apps-gateway-deploy.md#identity-provider-setup) para receitas de escopo por IdP, como o fluxo de refresh token do Google. |
80| `scope_on_refresh` | Não | Também envie `scope`, com a mesma lista que a solicitação de login, quando o gateway troca um token de atualização. Padrão `false`: a solicitação de atualização omite `scope`. A maioria dos IdPs retorna um id\_token em cada atualização e não precisa disso. Defina `true` quando seu IdP retorna um id\_token na atualização apenas se solicitado `openid` novamente, que Okta documenta para sua concessão de atualização. Sem um id\_token, cada atualização depende do endpoint userinfo do IdP aceitar o token de acesso atualizado. Se você controlar o login ou corresponder políticas em grupos e o id\_token de atualização do seu IdP os omitir, também defina `userinfo_fallback: true` para que o gateway os preencha a partir do endpoint userinfo. Um IdP que concedeu menos escopos do que solicitado pode rejeitar a atualização com `invalid_scope`, incluindo para sessões existentes se você adicionar entradas a `scopes` enquanto isso estiver ativado. Desdefina a chave se as atualizações começarem a falhar em `token_endpoint` depois que você a definir. Requer Claude Code v2.1.260 ou posterior no servidor gateway. |80| `scope_on_refresh` | Não | Também envia `scope`, com a mesma lista da requisição de login, quando o gateway troca um refresh token. Padrão `false`: a requisição de refresh omite `scope`. A maioria dos IdPs retorna um id\_token em todo refresh e não precisa disso. Defina `true` quando seu IdP retornar um id\_token no refresh somente se `openid` for solicitado novamente, o que a Okta documenta para seu grant de refresh. Sem um id\_token, todo refresh depende de o endpoint userinfo do IdP aceitar o access token renovado. Se você condiciona o login ou a correspondência de políticas a grupos e o id\_token do refresh do seu IdP os omite, defina também `userinfo_fallback: true` para que o gateway os preencha a partir do endpoint userinfo. Um IdP que concedeu menos escopos do que os solicitados pode rejeitar o refresh com `invalid_scope`, inclusive para sessões existentes, se você adicionar entradas a `scopes` enquanto isto estiver ativado. Remova a chave se os refreshes começarem a falhar em `token_endpoint` depois que você a definir. Requer Claude Code v2.1.260 ou posterior no servidor do gateway. |
81| `extra_auth_params` | Não | Parâmetros de consulta extras anexados à solicitação de autorização do IdP, literalmente. Este é o mecanismo de substituição para comportamento específico do IdP, como `access_type: offline` para tokens de atualização do Google, `domain_hint` para alguns locatários Entra ou `acr_values` para fluxos de step-up. Não pode substituir os parâmetros de protocolo gerenciados pelo gateway: `state`, `nonce`, `redirect_uri`, PKCE, `scope`, `response_type`, `response_mode` e `client_id`. |81| `extra_auth_params` | Não | Parâmetros de query extras anexados à requisição de autorização do IdP, literalmente. Este é o mecanismo de sobrescrita para comportamentos específicos de IdP, como `access_type: offline` para refresh tokens do Google, `domain_hint` para alguns tenants do Entra ou `acr_values` para fluxos de step-up. Não pode sobrescrever os parâmetros de protocolo gerenciados pelo gateway: `state`, `nonce`, `redirect_uri`, PKCE, `scope`, `response_type`, `response_mode` e `client_id`. |
82| `userinfo_fallback` | Não | Quando o id\_token omite email ou grupos, busque-os em `/userinfo`. Necessário para tokens de acesso leve do Keycloak, o servidor org do Okta e tokens mínimos do ADFS. O id\_token permanece autoritário; userinfo apenas preenche lacunas. Padrão `false`. |82| `userinfo_fallback` | Não | Quando o id\_token omite e-mail ou grupos, busca-os em `/userinfo`. Necessário para access tokens leves do Keycloak, o org server da Okta e tokens mínimos do ADFS. O id\_token permanece autoritativo; o userinfo apenas preenche lacunas. Padrão `false`. |
83| `use_pkce` | Não | Envie um desafio PKCE (S256) na solicitação de autorização. Padrão `true`. Defina `false` apenas se seu IdP rejeitar PKCE para este cliente confidencial. |83| `use_pkce` | Não | Envia um desafio PKCE (S256) na requisição de autorização. Padrão `true`. Defina `false` somente se seu IdP rejeitar PKCE para este cliente confidencial. |
84| `clock_skew_seconds` | Não | Tolere desvio de relógio ao validar declarações de tempo id\_token. Padrão `0`, que é rigoroso. Aumente se você vir erros "token expirado / ainda não válido" logo após o login devido a desvio de relógio host/IdP. |84| `clock_skew_seconds` | Não | Tolera desvio de relógio ao validar as claims de tempo do id\_token. Padrão `0`, que é estrito. Aumente se você vir erros de "token expirado / ainda não válido" logo após o login devido a desvio de relógio entre o host e o IdP. |
85| `token_endpoint_auth_method` | Não | Como o gateway se autentica no endpoint de token do IdP: `client_secret_basic`, `client_secret_post` ou `private_key_jwt` para [autenticação de cliente por certificado](#certificate-client-authentication). Por padrão, o gateway escolhe um dos dois métodos `client_secret` com base no que o IdP anuncia. |85| `token_endpoint_auth_method` | Não | Como o gateway se autentica no endpoint de token do IdP: `client_secret_basic`, `client_secret_post` ou `private_key_jwt` para [autenticação de cliente por certificado](#certificate-client-authentication). Por padrão, o gateway escolhe um dos dois métodos `client_secret` com base no que o IdP anuncia. |
86| `client_assertion` | Com `private_key_jwt` | Um bloco com `private_key_pem` e `certificate_pem`: a chave privada e o certificado para [autenticação de cliente por certificado](#certificate-client-authentication). Requer v2.1.284 ou posterior. |86| `client_assertion` | Com `private_key_jwt` | Um bloco com `private_key_pem` e `certificate_pem`: a chave privada e o certificado para [autenticação de cliente por certificado](#certificate-client-authentication). Requer v2.1.284 ou posterior. |
87| `id_token_signed_response_alg` | Não | Algoritmo de assinatura id\_token esperado. Padrão `RS256`. Defina para IdPs que assinam com ES256, PS256 ou EdDSA. |87| `id_token_signed_response_alg` | Não | Algoritmo de assinatura esperado do id\_token. Padrão `RS256`. Defina para IdPs que assinam com ES256, PS256 ou EdDSA. |
88| `additional_authorized_parties` | Não | Valores `azp` extras para aceitar além de `client_id`, para fluxos de broker e troca de token do Keycloak |88| `additional_authorized_parties` | Não | Valores `azp` extras a aceitar além de `client_id`, para fluxos de broker e token-exchange do Keycloak |
89| `discovery_url` | Não | Busque o documento de descoberta desta URL em vez de derivá-lo de `issuer`, para IdPs atrás de um proxy que reescreve o host do emissor. O caminho deve conter `/.well-known/`. |89| `discovery_url` | Não | Busca o documento de descoberta nesta URL em vez de derivá-lo de `issuer`, para IdPs atrás de um proxy que reescreve o host do emissor. O caminho deve conter `/.well-known/`. |
90| `use_proxy` | Não | Envie as próprias solicitações do IdP do gateway através do proxy de encaminhamento em `HTTPS_PROXY` ou `HTTP_PROXY`, honrando `NO_PROXY`. `false` mantém essas solicitações diretas. Requer v2.1.227 ou posterior; consulte [Solicitações do IdP através de um proxy de encaminhamento](#idp-requests-through-a-forward-proxy) abaixo. |90| `use_proxy` | Não | Envia as próprias requisições do gateway ao IdP pelo proxy de encaminhamento em `HTTPS_PROXY` ou `HTTP_PROXY`, respeitando `NO_PROXY`. `false` mantém essas requisições diretas. Requer v2.1.227 ou posterior; consulte [Requisições ao IdP por um proxy de encaminhamento](#idp-requests-through-a-forward-proxy) abaixo. |
91| `form_action_origins` | Não | Origens adicionais para a diretiva `Content-Security-Policy: form-action` da página `/device`. O gateway já permite `'self'` e a origem `authorization_endpoint` descoberta, mas o Chrome impõe `form-action` contra toda a cadeia de redirecionamento. Se seu IdP redireciona através de um segundo host, como Azure AD federado para ADFS, Okta hub-spoke ou um interceptador SSO corporativo, liste cada origem pela qual a solicitação de autorização pode redirecionar. |91| `form_action_origins` | Não | Origens adicionais para a diretiva `Content-Security-Policy: form-action` da página `/device`. O gateway já permite `'self'` e a origem do `authorization_endpoint` descoberto, mas o Chrome aplica `form-action` a toda a cadeia de redirecionamento. Se seu IdP redireciona por um segundo host, como Azure AD federado ao ADFS, Okta hub-spoke ou um interceptador de SSO corporativo, liste todas as origens pelas quais a requisição de autorização pode ser redirecionada. |
92| `ca_cert_pem` | Não | O certificado CA codificado em PEM em si, não um caminho para um arquivo. Ele substitui o armazenamento de confiança do sistema apenas para solicitações do IdP. Para carregar um arquivo montado, escreva `${file:/etc/gateway/idp-ca.pem}`. Use para Keycloak ou Dex atrás de PKI corporativa. |92| `ca_cert_pem` | Não | O próprio certificado de CA codificado em PEM, não um caminho para um arquivo. Ele substitui o repositório de confiança do sistema apenas para requisições ao IdP. Para carregar um arquivo montado, escreva `${file:/etc/gateway/idp-ca.pem}`. Use para Keycloak ou Dex atrás de PKI corporativa. |
93 93
94#### Autenticação de cliente por certificado94#### Autenticação de cliente por certificado
95 95
96Se o seu provedor de identidade autentica clientes OAuth com um certificado em vez de um segredo de cliente, como o Microsoft Entra faz com credenciais de certificado, defina `token_endpoint_auth_method: private_key_jwt`. Requer Claude Code v2.1.284 ou posterior no servidor gateway.96Se o seu provedor de identidade autentica clientes OAuth com um certificado em vez de um client secret, como o Microsoft Entra faz com credenciais de certificado, defina `token_endpoint_auth_method: private_key_jwt`. Requer Claude Code v2.1.284 ou posterior no servidor do gateway.
97 97
98Com essa configuração, o gateway não envia nenhum segredo. Ele se autentica no endpoint de token do IdP com um JWT de curta duração assinado com a chave privada do certificado quando um desenvolvedor faz login e cada vez que o gateway atualiza a sessão dele. O JWT é assinado com RS256 e identifica o certificado pelos cabeçalhos de thumbprint `x5t` e `x5t#S256` em vez de um `kid`. Seu IdP deve ser capaz de encontrar o certificado registrado pelo thumbprint.98Com essa configuração, o gateway não envia nenhum segredo. Ele se autentica no endpoint de token do IdP com um JWT de curta duração assinado com a chave privada do certificado quando um desenvolvedor faz login e sempre que o gateway renova a sessão dele. O JWT é assinado com RS256 e identifica o certificado pelos cabeçalhos de thumbprint `x5t` e `x5t#S256`, em vez de um `kid`. Seu IdP deve ser capaz de encontrar o certificado registrado pelo thumbprint.
99 99
100**1. Crie a chave e o certificado**100**1. Crie a chave e o certificado**
101 101
102Crie uma chave privada RSA não criptografada de pelo menos 2048 bits, em formato PEM PKCS#8 ou PKCS#1, e um certificado para ela. O gateway se recusa a iniciar com qualquer chave que não atenda a essas condições. Este comando `openssl` cria uma chave desse tipo com um certificado autoassinado válido por um ano:102Crie uma chave privada RSA não criptografada de pelo menos 2048 bits, no formato PEM PKCS#8 ou PKCS#1, e um certificado para ela. O gateway se recusa a iniciar com qualquer chave que não atenda a essas condições. Este comando `openssl` cria uma chave assim com um certificado autoassinado válido por um ano:
103 103
104```bash theme={null}104```bash theme={null}
105openssl req -x509 -newkey rsa:2048 -nodes -keyout idp-client.key -out idp-client.crt -days 365 -subj "/CN=claude-gateway"105openssl req -x509 -newkey rsa:2048 -nodes -keyout idp-client.key -out idp-client.crt -days 365 -subj "/CN=claude-gateway"
106```106```
107 107
108Ele grava `idp-client.key` e `idp-client.crt` no diretório atual. Copie ou monte ambos os arquivos onde o gateway possa lê-los. O exemplo na etapa 3 usa `/etc/gateway/`.108Ele grava `idp-client.key` e `idp-client.crt` no diretório atual. Copie ou monte os dois arquivos em um local onde o gateway possa lê-los. O exemplo da etapa 3 usa `/etc/gateway/`.
109 109
110**2. Envie o certificado para o IdP**110**2. Envie o certificado ao IdP**
111 111
112Envie o certificado, não a chave privada, para o registro de aplicativo do gateway no IdP.112Envie o certificado, não a chave privada, para o registro de aplicativo do gateway no IdP.
113 113
114**3. Adicione a chave e o certificado ao gateway.yaml**114**3. Adicione a chave e o certificado ao gateway.yaml**
115 115
116Forneça ao gateway a chave privada e o certificado em um bloco `client_assertion`. Omita `client_secret`, porque o gateway se recusa a iniciar quando ele está definido junto com `private_key_jwt`. Este bloco `oidc` autentica o gateway em um tenant do Microsoft Entra com um certificado:116Forneça ao gateway a chave privada e o certificado em um bloco `client_assertion`. Omita `client_secret`, porque o gateway se recusa a iniciar quando ele é definido junto com `private_key_jwt`. Este bloco `oidc` autentica o gateway em um tenant do Microsoft Entra com um certificado:
117 117
118```yaml theme={null}118```yaml theme={null}
119oidc:119oidc:
125 certificate_pem: ${file:/etc/gateway/idp-client.crt}125 certificate_pem: ${file:/etc/gateway/idp-client.crt}
126```126```
127 127
128Ambos os valores são o conteúdo PEM, não caminhos de arquivo, portanto carregue arquivos montados com `${file:/path}` como o exemplo faz. O gateway se recusa a iniciar a menos que `certificate_pem` seja um único certificado PEM, sem o restante de sua cadeia, cuja chave pública corresponda a `private_key_pem`.128Ambos os valores são o conteúdo PEM, não caminhos de arquivo, então carregue os arquivos montados com `${file:/path}`, como o exemplo faz. O gateway se recusa a iniciar a menos que `certificate_pem` seja um único certificado PEM, sem o restante de sua cadeia, cuja chave pública corresponda a `private_key_pem`.
129 129
130**4. Reinicie o gateway e verifique o log de inicialização**130**4. Reinicie o gateway e verifique o log de inicialização**
131 131
135[gateway] 2026-10-01T23:07:40.512Z info oidc: client authentication private_key_jwt; certificate CN=claude-gateway, SHA-1 thumbprint DE92821854EE8BAA1D98C758FAA04AABE80B9F57, expires Oct 1 23:07:31 2027 GMT135[gateway] 2026-10-01T23:07:40.512Z info oidc: client authentication private_key_jwt; certificate CN=claude-gateway, SHA-1 thumbprint DE92821854EE8BAA1D98C758FAA04AABE80B9F57, expires Oct 1 23:07:31 2027 GMT
136```136```
137 137
138Compare o thumbprint SHA-1 com o que o IdP mostra para o certificado que você enviou. Se o certificado tiver expirado ou ainda não for válido, o gateway ainda inicia, mas registra um aviso de que logins e atualizações falharão até que você o substitua. Para confirmar que o IdP aceita o certificado, peça a um desenvolvedor que faça login através do gateway.138Compare o thumbprint SHA-1 com o que o IdP mostra para o certificado que você enviou. Se o certificado tiver expirado ou ainda não for válido, o gateway ainda inicia, mas registra um aviso de que logins e refreshes falharão até que você o substitua. Para confirmar que o IdP aceita o certificado, peça a um desenvolvedor que faça login pelo gateway.
139 139
140#### Rotacionar o certificado do cliente140#### Rotacionar o certificado do cliente
141 141
142O 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:142O gateway lê a chave e o certificado uma vez na inicialização, então um arquivo alterado só entra em vigor 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:
143 143
1441. Envie o novo certificado para o IdP junto com o antigo.1441. Envie o novo certificado ao IdP junto com o antigo.
1452. 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](https://code.claude.com/docs/pt/claude-apps-gateway-deploy.md#upgrades) funciona, porque o IdP tem ambos os certificados até que você remova o antigo.1452. Substitua os arquivos de chave e certificado que o `gateway.yaml` carrega e reinicie o gateway. Se você executa várias réplicas, uma [reinicialização gradual](https://code.claude.com/docs/pt/claude-apps-gateway-deploy.md#upgrades) funciona, porque o IdP tem os dois certificados até que você remova o antigo.
1463. Depois que todas as réplicas tiverem reiniciado, remova o certificado antigo do IdP.1463. Depois que todas as réplicas tiverem reiniciado, remova o certificado antigo do IdP.
147 147
148#### Solicitações do IdP através de um proxy de encaminhamento148#### Requisições ao IdP por um proxy de encaminhamento
149 149
150Os upstreams de inferência honram `HTTPS_PROXY` e `HTTP_PROXY` em cada versão. As próprias solicitações do gateway para o IdP, descoberta, JWKS, token e userinfo, vão diretas a menos que você defina `oidc.use_proxy: true`, que requer v2.1.227 ou posterior. Quando uma variável de proxy está definida, `use_proxy` está indefinido e o emissor não é coberto por `NO_PROXY`, o gateway mantém essas solicitações diretas e registra um aviso na inicialização pedindo que você escolha; `use_proxy: false` as mantém diretas e silencia o aviso.150Os upstreams de inferência respeitam `HTTPS_PROXY` e `HTTP_PROXY` em todas as versões. As próprias requisições do gateway ao IdP, de descoberta, JWKS, token e userinfo, vão diretamente, a menos que você defina `oidc.use_proxy: true`, o que requer v2.1.227 ou posterior. Quando uma variável de proxy está definida, `use_proxy` não está definido e o emissor não está coberto por `NO_PROXY`, o gateway mantém essas requisições diretas e registra um aviso na inicialização pedindo que você escolha; `use_proxy: false` as mantém diretas e silencia o aviso.
151 151
152Com `use_proxy: true`, o pod resolve o nome do host de cada endpoint do IdP e pede ao proxy para `CONNECT` ao endereço IP resolvido, portanto o proxy deve aceitar `CONNECT` ao endereço IP de cada host que o documento de descoberta nomeia, não apenas o emissor. Use uma URL de proxy `http://`. `ca_cert_pem` e a [proteção SSRF](https://code.claude.com/docs/pt/claude-apps-gateway-deploy.md#threat-model-summary) se aplicam no caminho proxied também.152Com `use_proxy: true`, o pod resolve ele mesmo o hostname de cada endpoint do IdP e pede ao proxy que faça `CONNECT` ao endereço IP resolvido, então o proxy deve aceitar `CONNECT` ao endereço IP de todos os hosts que o documento de descoberta nomeia, não apenas ao do emissor. Use uma URL de proxy `http://`. `ca_cert_pem` e a [proteção contra SSRF](https://code.claude.com/docs/pt/claude-apps-gateway-deploy.md#threat-model-summary) também se aplicam ao caminho via proxy.
153 153
154[Egresso apenas proxy](#proxy-only-egress) muda ambos: enquanto estiver ativo, solicitações do IdP seguem o proxy a menos que você defina `use_proxy: false`, e o gateway entrega ao proxy cada nome do host do IdP sem resolvê-lo primeiro.154A [saída somente por proxy](#proxy-only-egress) muda ambos os pontos: enquanto ela está ativa, as requisições ao IdP seguem o proxy, a menos que você defina `use_proxy: false`, e o gateway entrega ao proxy cada hostname do IdP sem resolvê-lo antes.
155 155
156#### Egresso apenas proxy156#### Saída somente por proxy
157 157
158Defina `CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1` no ambiente do gateway, ao lado de `HTTPS_PROXY`, quando o pod alcança outros hosts apenas através desse proxy de encaminhamento e não pode resolver nomes DNS públicos por si mesmo, ou quando o proxy recusa `CONNECT` a um endereço IP. Requer v2.1.277 ou posterior. É uma variável de ambiente em vez de uma chave `gateway.yaml` para que nada no arquivo de configuração possa relaxar a verificação de endereço do gateway.158Defina `CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1` no ambiente do gateway, ao lado de `HTTPS_PROXY`, quando o pod alcança outros hosts somente por esse proxy de encaminhamento e não consegue resolver nomes DNS públicos por conta própria, ou quando o proxy recusa `CONNECT` a um endereço IP. Requer v2.1.277 ou posterior. É uma variável de ambiente em vez de uma chave do `gateway.yaml` para que nada no arquivo de configuração possa relaxar a verificação de endereços do gateway.
159 159
160```bash theme={null}160```bash theme={null}
161export HTTPS_PROXY=http://proxy.corp.example.com:3128161export HTTPS_PROXY=http://proxy.corp.example.com:3128
164export CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1164export CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1
165```165```
166 166
167O gateway registra uma linha `network:` na inicialização enquanto o egresso apenas proxy está ativo.167O gateway registra uma linha `network:` na inicialização enquanto a saída somente por proxy está ativa.
168 168
169Cada linha abaixo é uma classe de solicitação de saída em um gateway com `HTTPS_PROXY` definido, por padrão e enquanto o egresso apenas proxy está ativo.169Cada linha abaixo é uma classe de requisição de saída em um gateway com `HTTPS_PROXY` definido, por padrão e enquanto a saída somente por proxy está ativa.
170 170
171| Solicitação de saída | Padrão | Egresso apenas proxy ativo |171| Requisição de saída | Padrão | Saída somente por proxy ativa |
172| - | - | - |172| - | - | - |
173| Upstreams `provider: anthropic`, troca de token de Workload Identity Federation, exportações `telemetry.forward_to` | Resolvido e verificado localmente, depois `CONNECT` ao endereço IP verificado através do proxy. Um coletor de telemetria listado em `NO_PROXY` é alcançado diretamente em vez disso | Nome do host entregue ao proxy |173| Upstreams `provider: anthropic`, troca de token do Workload Identity Federation, exportações de `telemetry.forward_to` | Resolvido e verificado localmente, depois `CONNECT` ao endereço IP verificado pelo proxy. Um coletor de telemetria listado em `NO_PROXY` é alcançado diretamente | Hostname entregue ao proxy |
174| Descoberta do IdP, JWKS, token e userinfo | Direto a menos que [`oidc.use_proxy: true`](#idp-requests-through-a-forward-proxy), depois `CONNECT` ao endereço IP verificado | Nome do host entregue ao proxy, a menos que `oidc.use_proxy: false` mantenha um IdP interno direto |174| Descoberta, JWKS, token e userinfo do IdP | Direto, a menos que [`oidc.use_proxy: true`](#idp-requests-through-a-forward-proxy), quando então `CONNECT` ao endereço IP verificado | Hostname entregue ao proxy, a menos que `oidc.use_proxy: false` mantenha um IdP interno direto |
175| Amazon Bedrock, Claude Platform on AWS, Agent Platform do Google Cloud e upstreams Microsoft Foundry; procuras de grupo do Google | Nome do host entregue ao proxy | Inalterado |175| Upstreams Amazon Bedrock, Claude Platform on AWS, Agent Platform do Google Cloud e Microsoft Foundry; consultas de grupos do Google | Hostname entregue ao proxy | Inalterado |
176 176
177O egresso apenas proxy permanece desativado a menos que o ambiente do gateway atenda a todas as três dessas condições:177A saída somente por proxy permanece desativada, a menos que o ambiente do gateway atenda a todas estas três condições:
178 178
179* `HTTPS_PROXY` ou `HTTP_PROXY` está definido.179* `HTTPS_PROXY` ou `HTTP_PROXY` está definido.
180* `NO_PROXY` e `no_proxy` estão vazios. Se sua plataforma injeta um deles em pods, defina ambos para um valor vazio no contêiner do gateway. Listar um coletor de telemetria em `NO_PROXY` mantém o egresso apenas proxy desativado.180* `NO_PROXY` e `no_proxy` estão vazios. Se sua plataforma injeta qualquer um deles nos pods, defina ambos com um valor vazio no contêiner do gateway. Listar um coletor de telemetria em `NO_PROXY` mantém a saída somente por proxy desativada.
181* `CLAUDE_GATEWAY_ALLOW_LOOPBACK` não está ativado. Um coletor ou IdP no próprio loopback do pod não pode ser combinado com egresso apenas proxy, porque um endereço de loopback entregue ao proxy seria o próprio do host proxy, portanto dê a esses serviços um endereço que o proxy possa alcançar em vez disso. Pela mesma razão, o gateway recusa nomes de estilo `localhost` completamente enquanto o egresso apenas proxy está ativo.181* `CLAUDE_GATEWAY_ALLOW_LOOPBACK` não está ativado. Um coletor ou IdP no próprio loopback do pod não pode ser combinado com a saída somente por proxy, porque um endereço de loopback entregue ao proxy seria o do próprio host do proxy; então dê a esses serviços um endereço que o proxy consiga alcançar. Pelo mesmo motivo, o gateway recusa de imediato nomes no estilo `localhost` enquanto a saída somente por proxy está ativa.
182 182
183Quando uma dessas condições não é atendida, o gateway registra um aviso na inicialização nomeando a variável que a impediu e mantém o comportamento padrão.183Quando uma dessas condições não é atendida, o gateway registra um aviso na inicialização nomeando a variável que a impediu e mantém o comportamento padrão.
184 184
185Uma vez que o egresso apenas proxy está ativo, permita cada destino no proxy, incluindo um coletor interno e qualquer host configurado por endereço IP. Você ainda pode manter um IdP interno direto com [`oidc.use_proxy: false`](#idp-requests-through-a-forward-proxy).185Depois que a saída somente por proxy estiver ativa, permita no proxy todos os destinos, incluindo um coletor interno e qualquer host configurado por endereço IP. Você ainda pode manter um IdP interno direto com [`oidc.use_proxy: false`](#idp-requests-through-a-forward-proxy).
186 186
187> [!WARNING]187> [!WARNING]
188>188>
189> Ative isso apenas quando a allowlist do proxy for pelo menos tão rigorosa quanto a verificação do próprio gateway. O proxy deve recusar endpoints de metadados de nuvem como `169.254.169.254` e `metadata.google.internal`, endereços link-local e o próprio loopback do host proxy, e deve recusá-los pelo endereço que um nome resolve, não apenas pelo nome, porque o gateway não captura mais um nome do host que resolve para um deles. Um proxy que se conecta em qualquer lugar que é solicitado remove a [proteção SSRF](https://code.claude.com/docs/pt/claude-apps-gateway-deploy.md#threat-model-summary) do gateway para essas solicitações.189> Ative isto somente quando a allowlist do proxy for pelo menos tão estrita quanto a própria verificação do gateway. O proxy deve recusar endpoints de metadados de nuvem como `169.254.169.254` e `metadata.google.internal`, endereços link-local e o próprio loopback do host do proxy, e deve recusá-los pelo endereço para o qual um nome é resolvido, não apenas pelo nome, porque o gateway não detecta mais um hostname que resolve para um deles. Um proxy que se conecta a qualquer lugar solicitado remove a [proteção contra SSRF](https://code.claude.com/docs/pt/claude-apps-gateway-deploy.md#threat-model-summary) do gateway para essas requisições.
190 190
191### `session`191### `session`
192 192
193O bloco `session` molda os tokens de portador que o gateway emite após o login: o segredo que os assina e quanto tempo eles vivem.193O bloco `session` define os bearer tokens que o gateway emite após o login: o segredo que os assina e por quanto tempo eles duram.
194 194
195| Campo | Obrigatório | Descrição |195| Campo | Obrigatório | Descrição |
196| - | - | - |196| - | - | - |
197| `jwt_secret` | Sim | Pelo menos 32 bytes de entropia, por exemplo de `openssl rand -base64 32`. Assina os tokens de portador HS256 do gateway. Aceita uma única string ou um array para rotação: o índice 0 assina e todas as entradas verificam. Para girar, coloque um novo segredo na frente, aguarde `ttl_hours` e depois remova o antigo. |197| `jwt_secret` | Sim | Pelo menos 32 bytes de entropia, por exemplo de `openssl rand -base64 32`. Assina os bearer tokens HS256 do gateway. Aceita uma única string ou um array para rotação: o índice 0 assina e todas as entradas verificam. Para rotacionar, adicione um novo segredo no início, aguarde `ttl_hours` e depois remova o antigo. |
198| `ttl_hours` | Não | Tempo de vida do token de portador do gateway. Padrão `1`. O CLI atualiza silenciosamente antes da expiração quando o IdP emite tokens de atualização. Um tempo de vida mais curto desprovisiona mais rápido; um mais longo faz menos viagens de ida e volta do IdP. Se seu IdP não puder emitir tokens de atualização porque `offline_access` não está disponível, não há atualização silenciosa, portanto aumente para `8` ou `12` para evitar enviar desenvolvedores de volta ao login do navegador a cada hora. |198| `ttl_hours` | Não | Tempo de vida do bearer token do gateway. Padrão `1`. A CLI renova silenciosamente antes da expiração quando o IdP emite refresh tokens. Um tempo de vida menor revoga o acesso mais rápido; um maior faz menos idas e voltas ao IdP. Se seu IdP não pode emitir refresh tokens porque `offline_access` não está disponível, não há renovação silenciosa, então aumente para `8` ou `12` para evitar mandar os desenvolvedores de volta ao login no navegador a cada hora. |
199 199
200### `store`200### `store`
201 201
202O bloco `store` aponta o gateway para seu banco de dados PostgreSQL, que contém concessões de dispositivo e contadores de rate limit.202O bloco `store` aponta o gateway para seu banco de dados PostgreSQL, que armazena os device grants e os contadores de rate limit.
203 203
204| Campo | Obrigatório | Descrição |204| Campo | Obrigatório | Descrição |
205| - | - | - |205| - | - | - |
206| `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](https://code.claude.com/docs/pt/claude-apps-gateway-deploy.md#upgrades) e [Postgres](https://code.claude.com/docs/pt/claude-apps-gateway-deploy.md#postgres). |206| `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, então a role precisa de direitos para criar e alterar tabelas no esquema de destino. Consulte [Atualizações](https://code.claude.com/docs/pt/claude-apps-gateway-deploy.md#upgrades) e [Postgres](https://code.claude.com/docs/pt/claude-apps-gateway-deploy.md#postgres). |
207| `username` | Não | Substitui o usuário em `postgres_url` |207| `username` | Não | Sobrescreve o usuário em `postgres_url` |
208| `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. |208| `password` | Não | Credencial do banco de dados. Defina-a aqui em vez de em `postgres_url` para que a credencial fique fora da URL. Aceita quaisquer caracteres e tem precedência sobre as credenciais da URL. |
209| `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 gateway faz algumas operações de banco de dados por requisição de inferência, portanto aumente-o para um banco de dados dedicado sob carga, dentro do que [Dimensionar o pool de conexões](https://code.claude.com/docs/pt/claude-apps-gateway-deploy.md#size-the-connection-pool) permite. |209| `max_connections` | Não | Tamanho do pool de conexões do Postgres por réplica. Padrão `5`, que é conservador e adequado a bancos de dados compartilhados. Com [limites de gasto](#admin) ativados, o gateway faz algumas operações de banco de dados por requisição de inferência, então aumente-o para um banco de dados dedicado sob carga, dentro do que [Dimensionar o pool de conexões](https://code.claude.com/docs/pt/claude-apps-gateway-deploy.md#size-the-connection-pool) permite. |
210| `connect_timeout_seconds` | Não | Segundos que o gateway aguarda quando abre uma conexão Postgres. Um número inteiro de `1` a `60`, padrão `5`. Aumente se as tentativas de conexão expirem quando uma nova instância do gateway inicia. Requer Claude Code v2.1.274 ou posterior no servidor gateway. Versões anteriores recusam iniciar quando a chave está definida. |210| `connect_timeout_seconds` | Não | Segundos que o gateway aguarda ao abrir uma conexão com o Postgres. Um número inteiro de `1` a `60`, padrão `5`. Aumente-o se as tentativas de conexão atingirem o timeout quando uma nova instância do gateway inicia. Requer Claude Code v2.1.274 ou posterior no servidor do gateway. Versões anteriores se recusam a iniciar quando a chave está definida. |
211| `readiness_grace_seconds` | Não | Quantos segundos `/readyz` continua relatando pronto depois que o Postgres para de responder. Um número inteiro de `0` a `3600`, padrão `0`. Consulte [Comportamento durante interrupções](https://code.claude.com/docs/pt/claude-apps-gateway-deploy.md#outage-behavior) para saber como escolher um valor. Requer Claude Code v2.1.282 ou posterior no servidor gateway. Versões anteriores recusam iniciar quando a chave está definida. |211| `readiness_grace_seconds` | Não | Por quantos segundos `/readyz` continua informando estar pronto depois que o Postgres para de responder. Um número inteiro de `0` a `3600`, padrão `0`. Consulte [Comportamento durante interrupções](https://code.claude.com/docs/pt/claude-apps-gateway-deploy.md#outage-behavior) para saber como escolher um valor. Requer Claude Code v2.1.282 ou posterior no servidor do gateway. Versões anteriores se recusam a iniciar quando a chave está definida. |
212 212
213Para desenvolvimento local, aponte `postgres_url` para um contêiner Postgres descartável, por exemplo `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`.213Para desenvolvimento local, aponte `postgres_url` para um contêiner Postgres descartável, por exemplo `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`.
214 214
215### `upstreams`215### `upstreams`
216 216
217`upstreams` é uma lista ordenada. O gateway encaminha inferência para o primeiro upstream que resolve o modelo solicitado.217`upstreams` é uma lista ordenada. O gateway encaminha a inferência para o primeiro upstream que resolve o modelo solicitado, ignorando qualquer upstream cuja [lista `groups`](#send-each-team-to-its-own-upstream) deixe o desenvolvedor de fora.
218 218
219Em `5xx`, `429`, `401`, `403`, `404` ou timeout, o gateway falha para o próximo upstream; outro `4xx` não, porque esses erros são atribuíveis à solicitação em vez do upstream. Um `401` ou `403` significa que o upstream rejeitou a credencial que o gateway usou ou negou acesso a ela, por exemplo, ao modelo solicitado. Um `404` significa que esse upstream não serve o modelo solicitado, portanto um upstream posterior na lista ainda pode.219Em `5xx`, `429`, `401`, `403`, `404` ou timeout, o gateway faz failover para o próximo upstream; outros `4xx` não, porque esses erros são atribuíveis à requisição e não ao upstream. Um `401` ou `403` significa que o upstream rejeitou a credencial que o gateway usou ou negou acesso a ela, por exemplo ao modelo solicitado. Um `404` significa que esse upstream não serve o modelo solicitado, então um upstream posterior na lista ainda pode servi-lo.
220 220
221Se você definir `forward_user_identity: true` em um upstream, um `429` que ele retorna para uma solicitação que carregava o email do desenvolvedor não falha. Consulte [como uma negação de limite por usuário chega ao desenvolvedor](#per-user-identity-headers-for-a-proxy-you-run).221Se você definir `forward_user_identity: true` em um upstream, um `429` que ele retorna para uma requisição que carregava o e-mail do desenvolvedor não faz failover. Consulte [como uma negação de limite por usuário chega ao desenvolvedor](#per-user-identity-headers-for-a-proxy-you-run).
222 222
223Failover em `404` requer gateway v2.1.198 ou posterior. Versões anteriores retornavam o primeiro `404` ao cliente mesmo quando um upstream posterior na lista servia o modelo.223O failover em `404` requer gateway v2.1.198 ou posterior. Versões anteriores retornavam o primeiro `404` ao cliente mesmo quando um upstream posterior na lista servia o modelo.
224 224
225Múltiplos upstreams do mesmo provedor devem definir um `name:` distinto.225Vários upstreams do mesmo provedor devem definir um `name:` distinto.
226 226
227Clientes Amazon Bedrock, Claude Platform on AWS, Agent Platform do Google Cloud e Microsoft Foundry são construídos uma vez na inicialização, e seus SDKs atualizam credenciais internamente, portanto girar credenciais de nuvem não requer reinicialização. Chaves de API Anthropic estáticas e portadores são lidos na inicialização; consulte [Anthropic API](#anthropic-api).227Os clientes de Amazon Bedrock, Claude Platform on AWS, Agent Platform do Google Cloud e Microsoft Foundry são criados uma vez na inicialização, e seus SDKs renovam as credenciais internamente, então rotacionar credenciais de nuvem não exige reinicialização. Chaves de API e bearers estáticos da Anthropic são lidos na inicialização; consulte [Anthropic API](#anthropic-api).
228 228
229#### Mensagens de erro do upstream229#### Mensagens de erro do upstream
230 230
231O gateway retorna a resposta de erro de um upstream ou seu próprio `502`, dependendo de como os upstreams responderam:231O gateway retorna a resposta de erro de um upstream, ou seu próprio `502`, dependendo de como os upstreams responderam:
232 232
233* **Um upstream retornou um status no qual o gateway não [falha](#multiple-upstreams)**: essa resposta do upstream. O gateway não tenta mais upstreams.233* **Um upstream retornou um status no qual o gateway não [faz failover](#multiple-upstreams)**: a resposta desse upstream. O gateway não tenta mais nenhum upstream.
234* **Cada upstream que o gateway tentou falhou de uma forma na qual [falha](#multiple-upstreams)**: o último `429`. Quando nenhum retornou um `429`, o gateway prefere, em ordem, o último `401` ou `403`, o último `404` e o último `501`. Quando nenhum retornou nenhum desses, o próprio `502` do gateway, `all upstreams failed (N attempted)`, onde N conta cada entrada em [`upstreams`](#upstreams), incluindo entradas que o gateway pulou porque não servem o modelo solicitado.234* **Todos os upstreams que o gateway tentou falharam de uma forma em que ele [faz failover](#multiple-upstreams)**: o último `429`. Quando nenhum retornou um `429`, o gateway prefere, nesta ordem, o último `401` ou `403`, o último `404` e o último `501`. Quando nenhum retornou nenhum desses, o próprio `502` do gateway, `all upstreams failed (N attempted)`. N conta suas entradas de [`upstreams`](#upstreams), incluindo as ignoradas, menos aquelas cuja lista [`groups`](#send-each-team-to-its-own-upstream) deixa o desenvolvedor de fora.
235 235
236Quando o gateway retorna a resposta de um upstream, ele mantém o código de status do upstream. Se ele mantém a mensagem do upstream depende do provedor. O corpo de erro de um upstream da API Anthropic chega ao desenvolvedor inalterado.236Quando o gateway retorna a resposta de um upstream, ele mantém o código de status do upstream. Se ele mantém a mensagem do upstream depende do provedor. O corpo de erro de um upstream da Anthropic API chega ao desenvolvedor inalterado.
237 237
238Os upstreams Amazon Bedrock, Claude Platform on AWS, Agent Platform do Google Cloud e Microsoft Foundry podem nomear seus IDs de conta, ARNs de função e IDs de projeto no texto de erro. O gateway registra esse texto completo no [log operacional](https://code.claude.com/docs/pt/claude-apps-gateway-deploy.md#logs). O que o desenvolvedor vê desses upstreams depende da rejeição:238Os upstreams Amazon Bedrock, Claude Platform on AWS, Agent Platform do Google Cloud e Microsoft Foundry podem citar seus IDs de conta, ARNs de role e IDs de projeto no texto de erro. O gateway registra esse texto completo no [log operacional](https://code.claude.com/docs/pt/claude-apps-gateway-deploy.md#logs). O que o desenvolvedor vê desses upstreams depende da rejeição:
239 239
240* `400` ou `413` no envelope de erro padrão da Anthropic: a mensagem do próprio upstream, como `prompt is too long`. Claude Platform on AWS, Agent Platform e Microsoft Foundry retornam esse envelope para rejeições de API de modelo.240* `400` ou `413` no envelope de erro padrão da Anthropic: a própria mensagem do upstream, como `prompt is too long`. Claude Platform on AWS, Agent Platform e Microsoft Foundry retornam esse envelope para rejeições da API do modelo.
241* `400` ou `413` na forma própria do provedor: um token `capability_rejected:`. Quando o gateway não pode classificar a rejeição, `upstream rejected the request` em um `400` ou `request too large for this upstream` em um `413`.241* `400` ou `413` no formato próprio do provedor: um token `capability_rejected:`. Quando o gateway não consegue classificar a rejeição, `upstream rejected the request` em um `400` ou `request too large for this upstream` em um `413`.
242* Qualquer outro status: cópia genérica por status, como `upstream rate limit exceeded` em um `429`.242* Qualquer outro status: texto genérico por status, como `upstream rate limit exceeded` em um `429`.
243 243
244Por exemplo, o gateway substitui `Input is too long for requested model.` do Amazon Bedrock por `capability_rejected: prompt_too_long`. Claude Code [compacta automaticamente](https://code.claude.com/docs/pt/errors.md#prompt-is-too-long) nesse token, como faz em `prompt is too long`.244Por exemplo, o gateway substitui `Input is too long for requested model.` do Amazon Bedrock por `capability_rejected: prompt_too_long`. O Claude Code [compacta automaticamente](https://code.claude.com/docs/pt/errors.md#prompt-is-too-long) com esse token, como faz com `prompt is too long`.
245 245
246Manter a mensagem `400` ou `413` de um upstream de nuvem ou substituí-la por um token `capability_rejected:` requer gateway v2.1.233 ou posterior.246Manter a mensagem `400` ou `413` de um upstream de nuvem, ou substituí-la por um token `capability_rejected:`, requer gateway v2.1.233 ou posterior.
247 247
248#### Anthropic API248#### Anthropic API
249 249
250O upstream Anthropic mínimo é uma chave de API do [Claude Console](https://platform.claude.com):250O upstream mínimo da Anthropic é uma chave de API do [Claude Console](https://platform.claude.com):
251 251
252```yaml theme={null}252```yaml theme={null}
253upstreams:253upstreams:
254 - provider: anthropic254 - provider: anthropic
255 auth:255 auth:
256 api_key: ${ANTHROPIC_API_KEY}256 api_key: ${ANTHROPIC_API_KEY}
257 # OU um portador OAuth (por exemplo, um token trocado por Workload-Identity-Federation):257 # OR an OAuth bearer (e.g. a Workload-Identity-Federation-exchanged token):
258 # oauth_token: ${file:/var/run/secrets/anthropic-oauth-token}258 # oauth_token: ${file:/var/run/secrets/anthropic-oauth-token}
259 # base_url: https://api.anthropic.com # padrão; substitua por um proxy de encaminhamento259 # base_url: https://api.anthropic.com # default; override for a forward proxy
260```260```
261 261
262As duas formas de credencial diferem no cabeçalho que enviam:262As duas formas de credencial diferem no cabeçalho que enviam:
263 263
264* **`api_key`**: envia `x-api-key`. Gire-a no Claude Console e atualize a variável env.264* **`api_key`**: envia `x-api-key`. Rotacione-a no Claude Console e atualize a variável de ambiente.
265* **`oauth_token`**: envia `Authorization: Bearer`. Use a forma de portador quando sua organização emite tokens de curta duração em vez de chaves de API de longa duração. O portador é lido uma vez na inicialização, portanto atualize remontando o segredo e reiniciando.265* **`oauth_token`**: envia `Authorization: Bearer`. Use a forma bearer quando sua organização emite tokens de curta duração em vez de chaves de API de longa duração. O bearer é lido uma vez na inicialização, então renove-o remontando o segredo e reiniciando.
266 266
267Em vez de uma chave estática ou portador, você pode usar Workload Identity Federation. Crie uma regra de federação seguindo o [guia de Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation), depois monte o JWT OIDC da sua carga de trabalho como um arquivo, como um token de conta de serviço projetado do Kubernetes ou um id-token de plataforma CI. O gateway troca o JWT por um portador de curta duração e o atualiza automaticamente. O arquivo de token é relido em cada troca, portanto tokens projetados girados são coletados sem reinicialização.267Em vez de uma chave ou bearer estático, você pode usar o Workload Identity Federation. Crie uma regra de federação seguindo o [guia do Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) e depois monte o JWT OIDC da sua carga de trabalho como um arquivo, como um token projetado de conta de serviço do Kubernetes ou o id-token de uma plataforma de CI. O gateway troca o JWT por um bearer de curta duração e o renova automaticamente. O arquivo de token é relido a cada troca, então tokens projetados rotacionados são captados sem reinicialização.
268 268
269```yaml theme={null}269```yaml theme={null}
270upstreams:270upstreams:
273 federation_rule_id: ${ANTHROPIC_FEDERATION_RULE_ID}273 federation_rule_id: ${ANTHROPIC_FEDERATION_RULE_ID}
274 organization_id: ${ANTHROPIC_ORGANIZATION_ID}274 organization_id: ${ANTHROPIC_ORGANIZATION_ID}
275 identity_token_file: /var/run/secrets/anthropic/id-token275 identity_token_file: /var/run/secrets/anthropic/id-token
276 # workspace_id: wrkspc_... # obrigatório se a regra cobre >1 workspace276 # workspace_id: wrkspc_... # required if the rule covers >1 workspace
277 # service_account_id: svac_... # verificação de alvo esperado opcional277 # service_account_id: svac_... # optional expected-target check
278```278```
279 279
280##### Cabeçalhos de identidade por usuário para um proxy que você executa280##### Cabeçalhos de identidade por usuário para um proxy que você executa
281 281
282Você pode apontar o `base_url` de um upstream `provider: anthropic` para um proxy que você executa em vez de para a API Anthropic. Para dizer a esse proxy qual desenvolvedor enviou cada solicitação, defina `forward_user_identity: true` nesse upstream. O proxy pode então atribuir gastos por desenvolvedor. Requer um gateway executando Claude Code v2.1.233 ou posterior.282Você pode apontar o `base_url` de um upstream `provider: anthropic` para um proxy que você executa em vez da Anthropic API. Para informar a esse proxy qual desenvolvedor enviou cada requisição, defina `forward_user_identity: true` nesse upstream. O proxy pode então atribuir o gasto por desenvolvedor. Requer um gateway executando Claude Code v2.1.233 ou posterior.
283 283
284Por exemplo, para um proxy em `upstream-gateway.internal.example.com`:284Por exemplo, para um proxy em `upstream-gateway.internal.example.com`:
285 285
289 base_url: https://upstream-gateway.internal.example.com289 base_url: https://upstream-gateway.internal.example.com
290 auth:290 auth:
291 api_key: ${PROXY_KEY}291 api_key: ${PROXY_KEY}
292 forward_user_identity: true # padrão false292 forward_user_identity: true # default false
293```293```
294 294
295O gateway adiciona esses cabeçalhos a cada solicitação que encaminha para esse upstream.295O gateway adiciona estes cabeçalhos a toda requisição que encaminha a esse upstream.
296 296
297| Cabeçalho | Valor |297| Cabeçalho | Valor |
298| - | - |298| - | - |
299| `x-litellm-end-user-id` | O email do desenvolvedor, quando o IdP forneceu um. |299| `x-litellm-end-user-id` | O e-mail do desenvolvedor, quando o IdP fornece um. |
300| `x-claude-gateway-user-id` | O assunto do IdP do desenvolvedor, da declaração `sub` do token. |300| `x-claude-gateway-user-id` | O sujeito do desenvolvedor no IdP, da claim `sub` do token. |
301| `x-claude-gateway-user-email` | O email do desenvolvedor, quando o IdP forneceu um. |301| `x-claude-gateway-user-email` | O e-mail do desenvolvedor, quando o IdP fornece um. |
302 302
303Quando o token do IdP não carrega email, o gateway envia apenas `x-claude-gateway-user-id` e omite os dois cabeçalhos de email. Se seu IdP coloca o email em uma declaração diferente, defina [`oidc.email_claim`](#oidc) para essa declaração.303Quando o token do IdP não carrega e-mail, o gateway envia apenas `x-claude-gateway-user-id` e omite os dois cabeçalhos de e-mail. Se seu IdP coloca o e-mail em uma claim diferente, defina [`oidc.email_claim`](#oidc) como essa claim.
304 304
305Seu proxy não recebe os [cabeçalhos `x-claude-code-*`](https://code.claude.com/docs/pt/llm-gateway-protocol#request-headers) que o Claude Code envia, como `x-claude-code-session-id`. O gateway não os repassa a nenhum upstream, portanto agrupe as requisições por desenvolvedor com os cabeçalhos da tabela acima.305Seu proxy não recebe os [cabeçalhos `x-claude-code-*`](https://code.claude.com/docs/pt/llm-gateway-protocol#request-headers) que o Claude Code envia, como `x-claude-code-session-id`. O gateway não os repassa a nenhum upstream, então agrupe as requisições por desenvolvedor com os cabeçalhos da tabela acima.
306 306
307Quando seu proxy responde `429` para uma solicitação que carregava o email do desenvolvedor, o gateway retorna essa resposta ao desenvolvedor como está em vez de falhar para o próximo upstream, portanto seu orçamento por usuário ou rate limit do proxy se mantém. As outras respostas do proxy seguem as [regras de failover](#upstreams) ordinárias. Se o token do IdP de um desenvolvedor não carrega email, o gateway encaminha suas solicitações sem os cabeçalhos de email, portanto um `429` para uma dessas solicitações conta como capacidade de upstream e falha. Antes da v2.1.267 no servidor gateway, cada `429` falhava.307Quando seu proxy responde `429` a uma requisição que carregava o e-mail do desenvolvedor, o gateway retorna essa resposta ao desenvolvedor como está, em vez de fazer failover para o próximo upstream, para que o orçamento ou rate limit por usuário do seu proxy seja mantido. As outras respostas do proxy seguem as [regras de failover](#upstreams) comuns. Se o token do IdP de um desenvolvedor não carrega e-mail, o gateway encaminha as requisições dele sem os cabeçalhos de e-mail, então um `429` para uma dessas requisições conta como capacidade do upstream e faz failover. Antes da v2.1.267 no servidor do gateway, todo `429` fazia failover.
308 308
309Defina `forward_user_identity` apenas em um upstream cujo `base_url` é um proxy que você opera. O gateway envia emails de desenvolvedor para qualquer servidor que esse `base_url` nomeia. Se o `base_url` for a API Anthropic, que é o padrão, o gateway se recusa a iniciar.309Defina `forward_user_identity` somente em um upstream cujo `base_url` seja um proxy que você opera. O gateway envia os e-mails dos desenvolvedores para qualquer servidor que esse `base_url` nomeie. Se o `base_url` for a Anthropic API, que é o padrão, o gateway se recusa a iniciar.
310 310
311> [!NOTE]311> [!NOTE]
312>312>
313> Se você definir `forward_user_identity` em um upstream Amazon Bedrock, o gateway encerra na inicialização com `Unrecognized key(s) in object: 'forward_user_identity'`. Se o seu proxy fica na frente do Bedrock, liste-o como um upstream `provider: anthropic` em vez disso. O gateway envia a esse upstream o formato Anthropic Messages, portanto seu proxy precisa [traduzir requisições para o Bedrock](https://code.claude.com/docs/pt/llm-gateway-protocol.md#format-mismatch-with-the-upstream). Para identificar cada desenvolvedor para a AWS em vez disso, consulte [Atribuição de custos AWS por desenvolvedor](#per-developer-aws-cost-attribution).313> Se você definir `forward_user_identity` em um upstream Amazon Bedrock, o gateway encerra na inicialização com `Unrecognized key(s) in object: 'forward_user_identity'`. Se seu proxy fica à frente do Bedrock, liste-o como um upstream `provider: anthropic`. O gateway envia a esse upstream o formato Anthropic Messages, então seu proxy precisa [traduzir as requisições para o Bedrock](https://code.claude.com/docs/pt/llm-gateway-protocol.md#format-mismatch-with-the-upstream). Para identificar cada desenvolvedor para a AWS, consulte [Atribuição de custos da AWS por desenvolvedor](#per-developer-aws-cost-attribution).
314 314
315#### Amazon Bedrock315#### Amazon Bedrock
316 316
317Para a implantação Amazon Bedrock do lado do cliente que o gateway substitui ou está na frente, consulte [Claude Code on Amazon Bedrock](https://code.claude.com/docs/pt/amazon-bedrock.md). O upstream do lado do gateway:317Para a implantação do Amazon Bedrock do lado do cliente que o gateway substitui ou intermedeia, consulte [Claude Code no Amazon Bedrock](https://code.claude.com/docs/pt/amazon-bedrock.md). O upstream do lado do gateway:
318 318
319```yaml theme={null}319```yaml theme={null}
320upstreams:320upstreams:
321 - provider: bedrock321 - provider: bedrock
322 region: us-east-1322 region: us-east-1
323 auth: {} # preferido: cadeia de credencial padrão AWS323 auth: {} # preferred: AWS default credential chain
324 # OU credenciais explícitas:324 # OR explicit credentials:
325 # auth:325 # auth:
326 # aws_access_key_id: ${AWS_AKID}326 # aws_access_key_id: ${AWS_AKID}
327 # aws_secret_access_key: ${AWS_SK}327 # aws_secret_access_key: ${AWS_SK}
328 # aws_session_token: ${AWS_ST}328 # aws_session_token: ${AWS_ST}
329 # OU um token de portador da API Bedrock:329 # OR a Bedrock API bearer token:
330 # auth:330 # auth:
331 # aws_bearer_token: ${AWS_BEARER_TOKEN}331 # aws_bearer_token: ${AWS_BEARER_TOKEN}
332 # Substitua o endpoint bedrock-runtime para implantações FIPS ou VPC-endpoint:332 # Override the bedrock-runtime endpoint for FIPS or VPC-endpoint deployments:
333 # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com333 # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com
334```334```
335 335
336Um bloco `auth` vazio usa a cadeia de credencial padrão do AWS SDK: variáveis env, `~/.aws/credentials`, função de tarefa ECS, metadados de instância EC2 ou IRSA no EKS. Em produção, dê ao pod do gateway uma função IAM em vez de incorporar chaves estáticas em uma imagem de contêiner.336Um bloco `auth` vazio usa a cadeia de credenciais padrão do AWS SDK: variáveis de ambiente, `~/.aws/credentials`, task role do ECS, metadados de instância do EC2 ou IRSA no EKS. Em produção, dê ao pod do gateway uma role do IAM em vez de embutir chaves estáticas em uma imagem de contêiner.
337 337
338Credenciais explícitas devem ser completas: o gateway falha na inicialização quando `aws_access_key_id` e `aws_secret_access_key` não estão definidos juntos, ou quando `aws_session_token` está definido sem eles. Antes da v2.1.207, um bloco `auth:` parcial passou na validação.338Credenciais explícitas devem estar completas: o gateway falha na inicialização quando `aws_access_key_id` e `aws_secret_access_key` não são definidos juntos, ou quando `aws_session_token` é definido sem eles. Antes da v2.1.207, um bloco `auth:` parcial passava na validação.
339 339
340| Configuração | Como |340| Configuração | Como |
341| - | - |341| - | - |
342| Permissões IAM | Conceda ao principal do gateway `bedrock:InvokeModel` e `bedrock:InvokeModelWithResponseStream` nos ARNs do perfil de inferência e nos ARNs do modelo de fundação subjacente. Para o catálogo integrado em regiões dos EUA: `arn:aws:bedrock:<region>:<account>:inference-profile/us.anthropic.*` e `arn:aws:bedrock:*::foundation-model/anthropic.*`. Também conceda `bedrock:CountTokens` nos ARNs do modelo de fundação. O gateway o usa, sem custo, para contar os tokens de entrada de uma solicitação que o cliente abandonou, portanto [limites de gastos](#admin) permanecem precisos. Sem ele, o gateway recorre a uma solicitação Bedrock de um token para essa contagem. |342| Permissões do IAM | Conceda ao principal do gateway `bedrock:InvokeModel` e `bedrock:InvokeModelWithResponseStream` tanto nos ARNs de inference-profile quanto nos ARNs de foundation-model subjacentes. Para o catálogo integrado em regiões dos EUA: `arn:aws:bedrock:<region>:<account>:inference-profile/us.anthropic.*` e `arn:aws:bedrock:*::foundation-model/anthropic.*`. Conceda também `bedrock:CountTokens` nos ARNs de foundation-model. O gateway o usa, sem custo, para contar os tokens de entrada de uma requisição que o cliente abandonou, para que os [limites de gasto](#admin) permaneçam precisos. Sem ele, o gateway recorre a uma requisição de um token ao Bedrock para essa contagem. |
343| Acesso ao modelo | Amazon Bedrock habilita acesso ao modelo por padrão em regiões comerciais. O portão de nível de conta restante é o formulário de caso de uso único da Anthropic: se ninguém em sua conta AWS o enviou, abra o console Amazon Bedrock, selecione um modelo Anthropic do catálogo de modelos e complete o formulário. Consulte [Enviar detalhes de caso de uso](https://code.claude.com/docs/pt/amazon-bedrock.md#1-submit-use-case-details) para o formulário AWS Organizations e as permissões que o remetente precisa. |343| Acesso a modelos | O Amazon Bedrock ativa o acesso a modelos por padrão em regiões comerciais. A barreira restante no nível da conta é o formulário de caso de uso único da Anthropic: se ninguém na sua conta da AWS o enviou, abra o console do Amazon Bedrock, selecione um modelo da Anthropic no Model catalog e preencha o formulário. Consulte [Enviar detalhes do caso de uso](https://code.claude.com/docs/pt/amazon-bedrock.md#1-submit-use-case-details) para o formulário do AWS Organizations e as permissões de que quem o envia precisa. |
344| EKS (IRSA) | Crie uma função IAM com a política acima e uma política de confiança para o provedor OIDC do seu cluster com escopo para a conta de serviço do gateway. Anote a conta de serviço com `eks.amazonaws.com/role-arn: arn:aws:iam::<acct>:role/claude-gateway`. `auth: {}` a coleta. |344| EKS (IRSA) | Crie uma role do IAM com a política acima e uma política de confiança para o provedor OIDC do seu cluster restrita à conta de serviço do gateway. Anote a conta de serviço com `eks.amazonaws.com/role-arn: arn:aws:iam::<acct>:role/claude-gateway`. `auth: {}` a detecta. |
345| ECS / EC2 | Anexe a função IAM à definição de tarefa ou perfil de instância. `auth: {}` a coleta. |345| ECS / EC2 | Anexe a role do IAM à definição de tarefa ou ao perfil de instância. `auth: {}` a detecta. |
346| Em qualquer outro lugar | Passe credenciais através das variáveis env `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` e `AWS_SESSION_TOKEN`, ou defina-as explicitamente em `auth:` com expansão `${VAR}` |346| Qualquer outro lugar | Passe as credenciais pelas variáveis de ambiente `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` e `AWS_SESSION_TOKEN`, ou defina-as explicitamente em `auth:` com expansão `${VAR}` |
347| Região | `region:` é a região do endpoint da API. Perfis de inferência entre regiões roteiam através da geo (US, EU, APAC) independentemente de qual você escolher. Para regiões fora dos EUA ou ARNs de throughput provisionado, adicione um bloco [`models:`](#models) com os IDs corretos por upstream. |347| Região | `region:` é a região do endpoint da API. Os perfis de inferência entre regiões roteiam pela geografia (EUA, UE, APAC) independentemente de qual você escolher. Para regiões fora dos EUA ou ARNs de provisioned throughput, adicione um bloco [`models:`](#models) com os IDs corretos por upstream. |
348 348
349##### Aplicar um guardrail do Amazon Bedrock349##### Aplicar um guardrail do Amazon Bedrock
350 350
351Para aplicar um guardrail do Amazon Bedrock a cada requisição de inferência que o gateway envia através de um upstream Bedrock, adicione um bloco `guardrail` a esse upstream. Requer Claude Code v2.1.281 ou posterior no servidor gateway.351Para aplicar um guardrail do Amazon Bedrock a toda requisição de inferência que o gateway envia por um upstream Bedrock, adicione um bloco `guardrail` a esse upstream. Requer Claude Code v2.1.281 ou posterior no servidor do gateway.
352 352
353```yaml theme={null}353```yaml theme={null}
354upstreams:354upstreams:
356 region: us-east-1356 region: us-east-1
357 auth: {}357 auth: {}
358 guardrail:358 guardrail:
359 id: gr-abc123 # ID do guardrail ou ARN completo359 id: gr-abc123 # guardrail ID or full ARN
360 version: "1" # um número de versão publicado, ou DRAFT360 version: "1" # a published version number, or DRAFT
361 # mantenha as aspas: um 1 sem aspas falha na inicialização361 # keep the quotes: a bare 1 fails at boot
362```362```
363 363
364Conceda também `bedrock:ApplyGuardrail` no guardrail ao principal que assina as requisições desse upstream: o principal da AWS do gateway ou, com [`assume_role`](#bedrock-in-another-aws-account), a role nomeada em `role_arn`.
365
366Defina `guardrail` em todos os upstreams `bedrock` ou em nenhum. O gateway se recusa a iniciar com uma mistura, porque o [failover](#multiple-upstreams) poderia, de outra forma, enviar uma requisição a um upstream Bedrock sem guardrail.
367
368O guardrail cobre apenas upstreams Bedrock. Se você listar outro provedor em `upstreams`, o gateway envia requisições a esse provedor sem o guardrail, ou se recusa a iniciar se esse provedor for [`mantle`](#amazon-bedrock-mantle-endpoint).
369
370Quando uma requisição `/v1/messages` cujo corpo carrega um campo `amazon-bedrock-*`, como `amazon-bedrock-guardrailConfig`, chega a um upstream Bedrock com `guardrail` definido, o gateway responde 400 em vez de encaminhá-la.
371
364> [!WARNING]372> [!WARNING]
365>373>
366> O gateway não suporta input tags de guardrail. Ele não adiciona tags de conteúdo de guarda aos prompts, portanto um filtro de guardrail que o Amazon Bedrock aplica apenas a entradas com tags não é executado no tráfego através do gateway. Para saber quais filtros dependem de input tags, consulte [input tags](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-tagging.html) na documentação do Amazon Bedrock.374> Por padrão, o gateway não adiciona tags de entrada aos prompts, então um filtro de guardrail que o Amazon Bedrock aplica apenas a entradas com tags não é executado no tráfego que passa pelo gateway. Para adicionar as tags, defina [`input_tagging`](#add-guardrail-input-tags). Para saber quais filtros dependem de tags de entrada, consulte [tags de entrada](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-tagging.html) na documentação do Amazon Bedrock.
367 375
368Também conceda `bedrock:ApplyGuardrail` no guardrail ao principal que assina as requisições desse upstream: o principal AWS do gateway ou, com [`assume_role`](#bedrock-in-another-aws-account), a função nomeada em `role_arn`.376##### Adicionar tags de entrada do guardrail
369 377
370Defina `guardrail` em todos os upstreams `bedrock` ou em nenhum. O gateway se recusa a iniciar com uma mistura, porque o [failover](#multiple-upstreams) poderia, de outra forma, enviar uma requisição a um upstream Bedrock que não tem guardrail.378Para que o gateway adicione as tags de entrada de que o [filtro de ataques de prompt](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-prompt-attack.html) de um guardrail do Amazon Bedrock precisa, defina `input_tagging` no bloco `guardrail` e reinicie o gateway. Defina o mesmo valor em todos os upstreams `bedrock`, ou o gateway se recusa a iniciar. Requer Claude Code v2.1.316 ou posterior no servidor do gateway. Um gateway em uma versão que não tem a chave encerra na inicialização com `Unrecognized key(s) in object: 'input_tagging'`.
371 379
372O guardrail cobre apenas upstreams Bedrock. Se você listar outro provedor em `upstreams`, o gateway envia requisições a esse provedor sem o guardrail, ou se recusa a iniciar se esse provedor for [`mantle`](#amazon-bedrock-mantle-endpoint).380> [!WARNING]
381>
382> De acordo com a [documentação do Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-tagging.html), todos os filtros do guardrail param de avaliar conteúdo sem tags quando uma requisição carrega tags de entrada. Teste `input_tagging` em um gateway de teste antes de defini-lo em um que os desenvolvedores usam.
383
384`input_tagging` aceita um destes valores:
373 385
374Quando uma requisição `/v1/messages` cujo corpo carrega um campo `amazon-bedrock-*`, como `amazon-bedrock-guardrailConfig`, chega a um upstream Bedrock que tem `guardrail` definido, o gateway responde 400 em vez de encaminhá-la.386| `input_tagging` | Onde o gateway marca o texto | Depois que o guardrail bloqueia um prompt |
387| :- | :- | :- |
388| `last_message` | As mensagens `user` desde a última resposta do Claude | No Claude Code, o próximo prompt pode passar, e o Claude então recebe o prompt bloqueado como parte da conversa |
389| `user_messages` | Mensagens `user` | Prompts posteriores na sessão também podem ser bloqueados, até que o desenvolvedor remova o prompt bloqueado |
390| `all_messages` | Mensagens `user` e `assistant` | Igual a `user_messages` |
391| `all_messages_and_system` | O system prompt e todas as mensagens, incluindo [mensagens de sistema no meio da conversa](https://code.claude.com/docs/pt/llm-gateway-protocol.md#feature-pass-through) | Igual a `user_messages` |
375 392
376##### Bedrock em outra conta AWS393Com `last_message`, se as mensagens `user` desde a última resposta do Claude não contiverem texto a marcar, o gateway marca as mensagens de sistema no meio da conversa desde essa resposta. Uma chamada de ferramenta conta como resposta.
377 394
378Defina `assume_role` em um upstream Bedrock e o gateway usa sua própria identidade AWS apenas para chamar `sts:AssumeRole` em uma função que você nomeia, que pode estar em uma conta AWS diferente da do gateway. Cada requisição Bedrock desse upstream é assinada com as credenciais de uma hora que o STS retorna, portanto nenhuma chave de acesso de longa duração cruza contas.395A orientação do Amazon Bedrock para o filtro de ataques de prompt é [marcar a entrada do usuário de modo que o system prompt fique excluído](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-prompt-attack.html). Se você definir `all_messages_and_system`, um filtro que sinalize o próprio system prompt do Claude Code pode bloquear requisições.
396
397O exemplo abaixo marca o texto em todas as mensagens `user`:
398
399```yaml theme={null}
400upstreams:
401 - provider: bedrock
402 region: us-east-1
403 auth: {}
404 guardrail:
405 id: gr-abc123
406 version: "1"
407 input_tagging: user_messages
408```
409
410Mensagens `user` também podem conter texto que o Claude Code adiciona, como [lembretes do sistema](https://code.claude.com/docs/pt/glossary.md#system-reminder), então verifique no gateway de teste se requisições comuns não são bloqueadas.
411
412Nos testes da Anthropic, uma sessão com tags manteve suas leituras do [cache de prompt](https://code.claude.com/docs/pt/prompt-caching.md) de um prompt para o seguinte, e as tags não adicionaram tokens de entrada.
413
414##### O que as tags de entrada não cobrem
415
416Nenhum valor de `input_tagging` impede um desenvolvedor que deliberadamente coloca texto onde nenhuma tag vai. Não conte com o guardrail para avaliar estas partes de uma requisição:
417
418* **Conteúdo que o gateway não marca**: mensagens que seu valor de `input_tagging` deixa de fora, definições de ferramentas, entradas de chamadas de ferramenta, imagens e PDFs, entre outros. A menos que você defina `all_messages_and_system`, o system prompt também fica sem tags.
419* **Resultados de ferramentas**: contêm o que as ferramentas do Claude retornam, como conteúdo de arquivos e páginas da web. Nos testes da Anthropic, um filtro de palavras não os avaliou, com ou sem tags.
420
421Se sua conta ou organização da AWS impõe um guardrail, consulte a [documentação do Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-enforcements.html) para saber como esse guardrail trata tags de entrada.
422
423##### Registrar qual filtro do guardrail foi acionado
424
425Para descobrir qual filtro do guardrail do Amazon Bedrock bloqueou a requisição de um desenvolvedor, defina `guardrail_trace: true` no upstream Bedrock, reinicie o gateway e peça ao desenvolvedor que envie a requisição novamente. Em seguida, encontre o evento `guardrail.trace` da requisição no [log de auditoria](https://code.claude.com/docs/pt/claude-apps-gateway-deploy.md#logs). Requer Claude Code v2.1.314 ou posterior no servidor do gateway. Um gateway anterior se recusa a iniciar quando encontra `guardrail_trace`.
426
427```yaml theme={null}
428upstreams:
429 - provider: bedrock
430 region: us-east-1
431 auth: {}
432 guardrail:
433 id: gr-abc123
434 version: "1"
435 guardrail_trace: true # default false; beside guardrail, not inside it
436```
437
438O gateway grava um evento `guardrail.trace`, sem o texto correspondente, quando um filtro é acionado ou a ação do guardrail é `INTERVENED`. Encontre os eventos do desenvolvedor por `email` ou `sub`. Uma requisição com streaming pode produzir vários eventos, e um deles pode ter uma lista `filters` vazia, então leia todos os eventos que têm o mesmo `request_id`:
439
440| Campo | O que contém |
441| - | - |
442| `request_id` | O ID da requisição |
443| `sub`, `email` | O ID de usuário e o email do desenvolvedor |
444| `upstream` | O upstream de onde veio a resposta |
445| `action` | A ação do guardrail, como `INTERVENED` |
446| `filters` | Os filtros que foram acionados. A lista fica vazia quando a AWS não envia detalhes do filtro |
447| `filters[].side` | `input` ou `output` |
448| `filters[].guardrail` | O ID do guardrail |
449| `filters[].policy` | A política e a lista do Bedrock, como `contentPolicy.filters` ou `sensitiveInformationPolicy.piiEntities` |
450| Outros campos de `filters[]` | Uma entrada também pode carregar campos como `action`, `name`, `type`, `confidence`, `filterStrength`, `score` e `threshold` |
451
452O evento omite o texto que um filtro encontrou, incluindo o campo `match` do trace do Bedrock. Os desenvolvedores não recebem os dados de trace do Bedrock, porque o gateway os remove de cada resposta, com ou sem streaming.
453
454Se um cliente enviar um campo `amazon-bedrock-*` no corpo de uma requisição `/v1/messages`, o gateway responde 400 em um upstream que define `guardrail_trace`.
455
456##### Bedrock em outra conta da AWS
457
458Defina `assume_role` em um upstream Bedrock e o gateway usa sua própria identidade da AWS apenas para chamar `sts:AssumeRole` em uma role que você nomeia, que pode estar em uma conta da AWS diferente da do gateway. Toda requisição ao Bedrock desse upstream é assinada com as credenciais de uma hora que o STS retorna, então nenhuma chave de acesso de longa duração atravessa contas.
379 459
380Requer um gateway executando Claude Code v2.1.281 ou posterior. Um gateway anterior se recusa a iniciar quando encontra a chave.460Requer um gateway executando Claude Code v2.1.281 ou posterior. Um gateway anterior se recusa a iniciar quando encontra a chave.
381 461
384 - name: bedrock-isolated464 - name: bedrock-isolated
385 provider: bedrock465 provider: bedrock
386 region: us-east-1466 region: us-east-1
387 auth: {} # a própria função do gateway: ela apenas chama o STS467 auth: {} # the gateway's own role: it only calls STS
388 assume_role:468 assume_role:
389 role_arn: arn:aws:iam::222222222222:role/claude-gateway-bedrock469 role_arn: arn:aws:iam::222222222222:role/claude-gateway-bedrock
390 # external_id: ${BEDROCK_ROLE_EXTERNAL_ID} # quando a política de confiança da função exige um470 # external_id: ${BEDROCK_ROLE_EXTERNAL_ID} # when the role's trust policy requires one
391```471```
392 472
393O bloco `assume_role` aceita três chaves:473O bloco `assume_role` aceita três chaves:
394 474
395| Chave | Significado |475| Chave | Significado |
396| - | - |476| - | - |
397| `role_arn` | A função IAM que o gateway assume, como um ARN `arn:aws:iam::` ou `arn:aws-us-gov:iam::`. Conceda a ela as [permissões do Bedrock](#amazon-bedrock) de que esse upstream precisa, incluindo `bedrock:CountTokens`, além de `bedrock:ApplyGuardrail` quando o upstream define `guardrail`. |477| `role_arn` | A role do IAM que o gateway assume, como um ARN `arn:aws:iam::` ou `arn:aws-us-gov:iam::`. Dê a ela as [permissões do Bedrock](#amazon-bedrock) de que este upstream precisa, incluindo `bedrock:CountTokens`, além de `bedrock:ApplyGuardrail` quando o upstream define `guardrail`. |
398| `external_id` | Opcional. Enviado como o external ID em cada chamada `sts:AssumeRole`. Defina-o quando a política de confiança da função exigir um, e coloque-o entre aspas se for composto apenas de dígitos. |478| `external_id` | Opcional. Enviado como external ID em toda chamada `sts:AssumeRole`. Defina-o quando a política de confiança da role exigir um, e coloque-o entre aspas se for composto só de dígitos. |
399| `session_name` | Opcional. `email` ou `sub` dá a cada desenvolvedor sua própria sessão: consulte [Atribuição de custos AWS por desenvolvedor](#per-developer-aws-cost-attribution). Se não definido, cada requisição usa uma única sessão chamada `claude-apps-gateway`. |479| `session_name` | Opcional. `email` ou `sub` dá a cada desenvolvedor sua própria sessão: consulte [Atribuição de custos da AWS por desenvolvedor](#per-developer-aws-cost-attribution). Se não definido, toda requisição usa uma única sessão chamada `claude-apps-gateway`. |
400 480
401A política de confiança da função nomeia o próprio principal do gateway, como sua função IRSA ou de tarefa ECS. Esse principal precisa de `sts:AssumeRole` na função e de nenhuma permissão Bedrock própria. Remova o `Condition` se você não definir `external_id`.481A política de confiança da role nomeia o próprio principal do gateway, como sua role IRSA ou task role do ECS. Esse principal precisa de `sts:AssumeRole` na role e de nenhuma permissão própria do Bedrock. Remova a `Condition` se você não definir `external_id`.
402 482
403```json theme={null}483```json theme={null}
404{484{
412}492}
413```493```
414 494
415* Se o STS recusar ou estiver inacessível, o gateway não envia a requisição com as credenciais próprias do upstream. Ele registra o erro do STS com o que verificar e então tenta o próximo upstream que você listou. [Mensagens de erro do upstream](#upstream-error-messages) descreve o que o cliente recebe quando nenhum upstream tem sucesso. Um upstream posterior sem `assume_role` serviria a requisição com suas próprias credenciais, portanto liste um apenas se for isso que você deseja.495* Se o STS recusar ou estiver inacessível, o gateway não envia a requisição com as credenciais próprias do upstream. Ele registra o erro do STS com o que verificar e então tenta o próximo upstream que você listou. [Mensagens de erro do upstream](#upstream-error-messages) explica o que o cliente recebe quando nenhum upstream tem sucesso. Um upstream posterior sem `assume_role` serviria a requisição com suas próprias credenciais, então liste um somente se for isso o que você deseja.
416* O gateway chama o endpoint regional do STS `sts.<region>.amazonaws.com`, que sua rede deve alcançar. Para o endpoint FIPS, defina `AWS_USE_FIPS_ENDPOINT=true` no ambiente do gateway em vez de `use_fips_endpoint` em um arquivo de configuração AWS.496* O gateway chama o endpoint regional do STS `sts.<region>.amazonaws.com`, que sua rede deve alcançar. Para o endpoint FIPS, defina `AWS_USE_FIPS_ENDPOINT=true` no ambiente do gateway, em vez de `use_fips_endpoint` em um arquivo de configuração da AWS.
417* `assume_role` se aplica apenas a `provider: bedrock` e precisa de credenciais de origem SigV4: o gateway se recusa a iniciar quando ele está definido junto com `aws_bearer_token`.497* `assume_role` se aplica apenas a `provider: bedrock` e precisa de credenciais de origem SigV4: o gateway se recusa a iniciar quando ele é definido ao lado de `aws_bearer_token`.
418* Cada desenvolvedor que o gateway admite pode usar esse upstream; [`managed`](#managed) governa quais desenvolvedores podem usar quais modelos. Para impedir que um modelo servido através da função também seja servido a partir de outra conta, dê a ele um id personalizado cujo mapa `upstream_model` tenha apenas o nome desse upstream. Para esse id, o gateway pula todos os outros upstreams, portanto nem a requisição nem a contagem de tokens de uma requisição abortada podem fazer failover para outra conta. Uma requisição para um nome de modelo integrado ainda pode [alcançar esse upstream](#multiple-upstreams), e o gateway a assina com a mesma função. Liste esse upstream por último, a menos que sua conta também deva servir esses modelos.498* Sem uma [lista `groups`](#send-each-team-to-its-own-upstream), todo desenvolvedor que o gateway admite pode usar este upstream. Para limitar quais modelos um desenvolvedor pode usar, defina `availableModels` em uma política [`managed`](#managed).
499* Para evitar que um modelo servido pelo papel também seja servido por outra conta, dê a ele um id personalizado cujo mapa `upstream_model` tenha apenas o nome deste upstream. Para esse id, o gateway ignora todos os outros upstreams, então nem a requisição nem a contagem de tokens de uma requisição abortada podem fazer failover para outra conta.
500* Uma requisição para um nome de modelo integrado ainda pode [chegar a este upstream](#multiple-upstreams), e o gateway a assina com o mesmo papel. Liste este upstream por último, a menos que a conta dele também deva servir esses modelos.
419 501
420Este exemplo dá a um modelo um id personalizado que apenas o upstream isolado serve:502Este exemplo dá a um modelo um id personalizado que somente o upstream isolado serve:
421 503
422```yaml theme={null}504```yaml theme={null}
423models:505models:
424 - id: restricted-claude-opus-4-8 # um id personalizado, não um nome de modelo integrado506 - id: restricted-claude-opus-4-8 # a custom id, not a built-in model name
425 upstream_model:507 upstream_model:
426 bedrock-isolated: us.anthropic.claude-opus-4-8 # o único upstream que o serve508 bedrock-isolated: us.anthropic.claude-opus-4-8 # the only upstream that serves it
427```509```
428 510
429##### Atribuição de custos AWS por desenvolvedor511##### Atribuição de custos da AWS por desenvolvedor
430 512
431Por padrão, o gateway assina cada requisição Bedrock com uma única credencial, portanto a AWS vê as requisições de todos os desenvolvedores sob um único principal IAM. Adicione `session_name: email` a [`assume_role`](#bedrock-in-another-aws-account) e o gateway chama `sts:AssumeRole` uma vez por desenvolvedor por hora, com o nome da sessão definido como o email desse desenvolvedor, e assina as requisições dele com as credenciais retornadas, portanto as requisições de cada desenvolvedor chegam à AWS sob sua própria sessão de função assumida. A função pode estar na própria conta do gateway.513Por padrão, o gateway assina toda requisição ao Bedrock com uma única credencial, então a AWS vê as requisições de todos os desenvolvedores sob um único principal do IAM. Adicione `session_name: email` a [`assume_role`](#bedrock-in-another-aws-account) e o gateway chama `sts:AssumeRole` uma vez por desenvolvedor por hora, com o nome da sessão definido como o e-mail desse desenvolvedor, e assina as requisições dele com as credenciais retornadas, de modo que as requisições de cada desenvolvedor chegam à AWS sob sua própria sessão de role assumida. A role pode estar na própria conta do gateway.
432 514
433Requer um gateway executando Claude Code v2.1.281 ou posterior. [Atribuição de custos na AWS](https://code.claude.com/docs/pt/claude-apps-gateway-on-aws.md#cost-attribution) descreve a função IAM e onde o faturamento da AWS mostra as sessões.515Requer um gateway executando Claude Code v2.1.281 ou posterior. [Atribuição de custos na AWS](https://code.claude.com/docs/pt/claude-apps-gateway-on-aws.md#cost-attribution) aborda a role do IAM e onde o faturamento da AWS mostra as sessões.
434 516
435```yaml theme={null}517```yaml theme={null}
436upstreams:518upstreams:
437 - provider: bedrock519 - provider: bedrock
438 region: us-east-1520 region: us-east-1
439 auth: {} # a própria função do gateway: ela apenas chama o STS521 auth: {} # the gateway's own role: it only calls STS
440 assume_role:522 assume_role:
441 role_arn: arn:aws:iam::123456789012:role/claude-gateway-bedrock-user523 role_arn: arn:aws:iam::123456789012:role/claude-gateway-bedrock-user
442 session_name: email # ou sub524 session_name: email # or sub
443```525```
444 526
445`session_name` seleciona qual declaração verificada se torna o `RoleSessionName` da AWS: `email` ou `sub`. O gateway escreve qualquer caractere diferente de letras ASCII, dígitos e `_+,.@-` como hex `=XX` por byte UTF-8, e encurta um resultado com mais de 64 caracteres para um prefixo mais um hash, portanto o nome de sessão de cada desenvolvedor permanece válido e único. Uma requisição de um desenvolvedor cujo token não tem a declaração não é enviada através desse upstream, e o log do operador indica para mudar para `sub` ou definir [`oidc.email_claim`](#oidc).527`session_name` seleciona qual claim verificada se torna o `RoleSessionName` da AWS: `email` ou `sub`. O gateway escreve qualquer caractere que não seja letra ASCII, dígito ou `_+,.@-` como `=XX` em hexadecimal por byte UTF-8, e encurta um resultado com mais de 64 caracteres para um prefixo mais um hash, de modo que o nome de sessão de cada desenvolvedor permaneça válido e único. Uma requisição de um desenvolvedor cujo token não tem a claim não é enviada por este upstream, e o log do operador diz para mudar para `sub` ou definir [`oidc.email_claim`](#oidc).
446 528
447Um desenvolvedor ativo custa uma chamada STS por hora por réplica do gateway, e primeiras requisições concorrentes compartilham uma chamada.529Um desenvolvedor ativo custa uma chamada ao STS por hora por réplica do gateway, e primeiras requisições simultâneas compartilham uma chamada.
448 530
449O gateway também faz uma chamada própria nessa função: a contagem de tokens de uma requisição que o cliente abandonou, para que os [limites de gastos](https://code.claude.com/docs/pt/claude-apps-gateway-spend-limits.md) permaneçam precisos. Essa contagem e sua [requisição de fallback de um token](#amazon-bedrock) são assinadas pela sessão compartilhada `claude-apps-gateway`, portanto a AWS atribui o fallback a `claude-apps-gateway` em vez de ao desenvolvedor.531O gateway também faz uma chamada própria nesta role: a contagem de tokens de uma requisição que o cliente abandonou, para que os [limites de gasto](https://code.claude.com/docs/pt/claude-apps-gateway-spend-limits.md) permaneçam precisos. Essa contagem e sua [requisição de fallback de um token](#amazon-bedrock) são assinadas pela sessão compartilhada `claude-apps-gateway`, então a AWS atribui o fallback a `claude-apps-gateway` em vez de ao desenvolvedor.
450 532
451Para uma atribuição estrita por desenvolvedor, defina `assume_role` com `session_name` em cada upstream Bedrock que você listar. Um upstream sem ele assina as requisições que serve com suas próprias credenciais.533Para uma atribuição estrita por desenvolvedor, defina `assume_role` com `session_name` em todos os upstreams Bedrock que você listar. Um upstream sem isso assina as requisições que serve com suas próprias credenciais.
452 534
453#### Endpoint Mantle do Amazon Bedrock535#### Endpoint Mantle do Amazon Bedrock
454 536
455O provedor `mantle` envia inferência para o [endpoint Mantle](https://code.claude.com/docs/pt/amazon-bedrock.md#use-the-mantle-endpoint) do Amazon Bedrock. Ele requer Claude Code v2.1.283 ou posterior no servidor gateway. Versões anteriores do gateway o rejeitam na inicialização, portanto atualize cada réplica antes de adicioná-lo.537O provedor `mantle` envia a inferência ao [endpoint Mantle](https://code.claude.com/docs/pt/amazon-bedrock.md#use-the-mantle-endpoint) do Amazon Bedrock. Ele requer Claude Code v2.1.283 ou posterior no servidor do gateway. Versões anteriores do gateway o rejeitam na inicialização, então atualize todas as réplicas antes de adicioná-lo.
456 538
457O exemplo abaixo coloca o Mantle primeiro, com um upstream Amazon Bedrock atrás dele para servir cada modelo que o campo `models` deixa de fora:539O exemplo abaixo coloca o Mantle primeiro, com um upstream Amazon Bedrock atrás dele para servir todos os modelos que o campo `models` deixa de fora:
458 540
459```yaml theme={null}541```yaml theme={null}
460upstreams:542upstreams:
461 - provider: mantle543 - provider: mantle
462 region: us-east-1544 region: us-east-1
463 models: [claude-opus-4-7, claude-haiku-4-5] # obrigatório545 models: [claude-opus-4-7, claude-haiku-4-5] # required
464 auth: {} # cadeia de credencial padrão AWS546 auth: {} # AWS default credential chain
465 - provider: bedrock547 - provider: bedrock
466 region: us-east-1548 region: us-east-1
467 auth: {}549 auth: {}
471 553
472| Campo | Obrigatório | Descrição |554| Campo | Obrigatório | Descrição |
473| - | - | - |555| - | - | - |
474| `region` | Sim | Região AWS. O gateway deriva o endpoint a partir dela como `https://bedrock-mantle.<region>.api.aws/anthropic`. |556| `region` | Sim | Região da AWS. O gateway deriva o endpoint dela como `https://bedrock-mantle.<region>.api.aws/anthropic`. |
475| `models` | Sim | Os modelos aos quais sua conta AWS recebeu acesso no Mantle, nomeados como os clientes os enviam, como `claude-haiku-4-5`. Apenas esses vão para este upstream, e todos os outros modelos pulam para o próximo. |557| `models` | Sim | Os modelos aos quais sua conta da AWS recebeu acesso no Mantle, nomeados como os clientes os enviam, como `claude-haiku-4-5`. Apenas estes vão para este upstream, e todos os outros modelos passam para o próximo. |
476| `auth` | Não | Aceita as mesmas chaves que o bloco `auth` do upstream [Amazon Bedrock](#amazon-bedrock), sob as mesmas regras. |558| `auth` | Não | Aceita as mesmas chaves do bloco `auth` do upstream [Amazon Bedrock](#amazon-bedrock), sob as mesmas regras. |
477| `base_url` | Não | Substitua o endpoint derivado. Mantenha o caminho `/anthropic` no final. |559| `base_url` | Não | Sobrescreve o endpoint derivado. Mantenha o caminho `/anthropic` no final. |
478 560
479Conceda à identidade AWS do upstream as ações IAM próprias do Mantle para inferência e contagem de tokens, que [Usar o endpoint Mantle](https://code.claude.com/docs/pt/amazon-bedrock.md#use-the-mantle-endpoint) lista.561Conceda à identidade da AWS do upstream as próprias ações do IAM do Mantle para inferência e contagem de tokens, listadas em [Usar o endpoint Mantle](https://code.claude.com/docs/pt/amazon-bedrock.md#use-the-mantle-endpoint).
480 562
481Para um ID de modelo do Mantle que o gateway não conhece, adicione uma entrada ao bloco [`models:`](#models) de nível superior cujo `upstream_model` mapeie o nome deste upstream para esse ID. Em seguida, coloque o `id` dessa entrada também no campo `models` deste upstream.563Para um ID de modelo do Mantle que o gateway não conhece, adicione uma entrada ao bloco [`models:`](#models) de nível superior cujo `upstream_model` mapeie o nome deste upstream para esse ID. Depois, coloque o `id` dessa entrada também no campo `models` deste upstream.
482 564
483As configurações `guardrail` e `assume_role` de um upstream `bedrock` não se estendem às requisições que o Mantle serve:565As configurações `guardrail` e `assume_role` de um upstream `bedrock` não se estendem às requisições que o Mantle serve:
484 566
485* **`guardrail`**: o gateway não aplica nenhum [guardrail do Bedrock](#apply-an-amazon-bedrock-guardrail) às requisições que envia ao Mantle, portanto ele se recusa a iniciar quando um upstream `mantle` está listado enquanto qualquer upstream `bedrock` define `guardrail`.567* **`guardrail`**: o gateway não aplica nenhum [guardrail do Bedrock](#apply-an-amazon-bedrock-guardrail) às requisições que envia ao Mantle, então se recusa a iniciar quando um upstream `mantle` está listado enquanto algum upstream `bedrock` define `guardrail`.
486* **`assume_role`**: um upstream `mantle` não aceita [`assume_role`](#bedrock-in-another-aws-account). As requisições que o Mantle serve são enviadas com as credenciais `auth` próprias do upstream `mantle` e não são [atribuídas por desenvolvedor](#per-developer-aws-cost-attribution).568* **`assume_role`**: um upstream `mantle` não aceita [`assume_role`](#bedrock-in-another-aws-account). As requisições que o Mantle serve são enviadas com as próprias credenciais `auth` do upstream `mantle` e não são [atribuídas por desenvolvedor](#per-developer-aws-cost-attribution).
487 569
488Para saber o que significam as respostas de erro próprias do Mantle, consulte [Erros do endpoint Mantle](https://code.claude.com/docs/pt/amazon-bedrock.md#mantle-endpoint-errors).570Para saber o que significam as próprias respostas de erro do Mantle, consulte [Erros do endpoint Mantle](https://code.claude.com/docs/pt/amazon-bedrock.md#mantle-endpoint-errors).
489 571
490#### Claude Platform on AWS572#### Claude Platform on AWS
491 573
492Claude Platform on AWS serve a API Anthropic de primeira parte em infraestrutura AWS em `aws-external-anthropic.<region>.api.aws`. Usa IDs de modelo de primeira parte, honra cabeçalhos `anthropic-beta` conforme enviados e serve `count_tokens`, portanto nenhuma tradução específica do Bedrock se aplica. O provedor `anthropicAws` requer Claude Code v2.1.198 ou posterior; versões anteriores do gateway o rejeitam na inicialização.574O Claude Platform on AWS serve a Anthropic API first-party na infraestrutura da AWS em `aws-external-anthropic.<region>.api.aws`. Ele usa IDs de modelo first-party, respeita os cabeçalhos `anthropic-beta` como enviados e serve `count_tokens`, então nenhuma das traduções específicas do Bedrock se aplica. O provedor `anthropicAws` requer Claude Code v2.1.198 ou posterior; versões anteriores do gateway o rejeitam na inicialização.
493 575
494Para a implantação do lado do cliente da mesma plataforma, consulte [Claude Code on Claude Platform on AWS](https://code.claude.com/docs/pt/claude-platform-on-aws.md). O upstream do lado do gateway:576Para a implantação do lado do cliente da mesma plataforma, consulte [Claude Code no Claude Platform on AWS](https://code.claude.com/docs/pt/claude-platform-on-aws.md). O upstream do lado do gateway:
495 577
496```yaml theme={null}578```yaml theme={null}
497upstreams:579upstreams:
499 region: us-east-1581 region: us-east-1
500 workspace_id: wrkspc_...582 workspace_id: wrkspc_...
501 auth:583 auth:
502 api_key: ${ANTHROPIC_AWS_API_KEY} # enviado como x-api-key584 api_key: ${ANTHROPIC_AWS_API_KEY} # sent as x-api-key
503 # OU SigV4 através da cadeia de credencial padrão AWS:585 # OR SigV4 via the AWS default credential chain:
504 # auth: {}586 # auth: {}
505 # OU credenciais SigV4 explícitas:587 # OR explicit SigV4 credentials:
506 # auth:588 # auth:
507 # aws_access_key_id: ${AWS_ACCESS_KEY_ID}589 # aws_access_key_id: ${AWS_ACCESS_KEY_ID}
508 # aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}590 # aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}
509 # Substitua o endpoint derivado:591 # Override the derived endpoint:
510 # base_url: https://aws-external-anthropic.us-east-1.api.aws592 # base_url: https://aws-external-anthropic.us-east-1.api.aws
511```593```
512 594
513A plataforma é executada em uma conta AWS separada do Amazon Bedrock e assina solicitações SigV4 para seu próprio nome de serviço, `aws-external-anthropic`, portanto uma função IAM com escopo Bedrock não a autoriza. Uma chave de API em `auth.api_key` tem precedência quando credenciais SigV4 também estão definidas. Um bloco `auth` vazio usa a cadeia de credencial padrão do AWS SDK, a mesma cadeia que o upstream [Amazon Bedrock](#amazon-bedrock) usa.595A plataforma é executada em uma conta da AWS separada do Amazon Bedrock e assina requisições SigV4 para seu próprio nome de serviço, `aws-external-anthropic`, então uma role do IAM com escopo do Bedrock não a autoriza. Uma chave de API em `auth.api_key` tem precedência quando credenciais SigV4 também estão definidas. Um bloco `auth` vazio usa a cadeia de credenciais padrão do AWS SDK, a mesma cadeia que o upstream [Amazon Bedrock](#amazon-bedrock) usa.
514 596
515| Campo | Obrigatório | Descrição |597| Campo | Obrigatório | Descrição |
516| - | - | - |598| - | - | - |
517| `region` | Sim | Região AWS, letras minúsculas, dígitos e hífens. O gateway deriva o endpoint a partir dela como `https://aws-external-anthropic.<region>.api.aws`. |599| `region` | Sim | Região da AWS, com letras minúsculas, dígitos e hifens. O gateway deriva o endpoint dela como `https://aws-external-anthropic.<region>.api.aws`. |
518| `workspace_id` | Sim | Enviado como um cabeçalho em cada solicitação; a plataforma o requer |600| `workspace_id` | Sim | Enviado como cabeçalho em toda requisição; a plataforma o exige |
519| `auth.api_key` | Não | Chave de API para a plataforma, enviada como `x-api-key`. Não é um token de portador: os dois modos de autenticação são uma chave de API ou SigV4. |601| `auth.api_key` | Não | Chave de API da plataforma, enviada como `x-api-key`. Não é um bearer token: os dois modos de autenticação são chave de API ou SigV4. |
520| `auth.aws_access_key_id` / `auth.aws_secret_access_key` | Não | Credenciais SigV4 explícitas. Definir um sem o outro falha na inicialização. `auth.aws_session_token` é aceito junto com eles. |602| `auth.aws_access_key_id` / `auth.aws_secret_access_key` | Não | Credenciais SigV4 explícitas. Definir uma sem a outra falha na inicialização. `auth.aws_session_token` é aceito junto com elas. |
521| `base_url` | Não | Substitua o endpoint derivado |603| `base_url` | Não | Sobrescreve o endpoint derivado |
522 604
523Como a plataforma resolve IDs de modelo de primeira parte, o catálogo integrado roteia para ela sem um bloco [`models:`](#models). Quando você cura uma lista `models:`, chave a entrada `anthropicAws:` com o ID de primeira parte.605Como a plataforma resolve IDs de modelo first-party, o catálogo integrado roteia para ela sem nenhum bloco [`models:`](#models). Ao montar uma lista `models:` própria, use a chave `anthropicAws:` na entrada com o ID first-party.
524 606
525#### Google Cloud Agent Platform607#### Google Cloud Agent Platform
526 608
527Para a configuração equivalente do lado do cliente, consulte [Claude Code on Google Cloud](https://code.claude.com/docs/pt/google-vertex-ai.md). O upstream do lado do gateway:609Para a configuração equivalente do lado do cliente, consulte [Claude Code no Google Cloud](https://code.claude.com/docs/pt/google-vertex-ai.md). O upstream do lado do gateway:
528 610
529```yaml theme={null}611```yaml theme={null}
530upstreams:612upstreams:
531 - provider: vertex613 - provider: vertex
532 region: us-east5614 region: us-east5
533 project_id: example-prod615 project_id: example-prod
534 auth: {} # preferido: Credenciais Padrão de Aplicativo616 auth: {} # preferred: Application Default Credentials
535 # OU um arquivo de chave de conta de serviço:617 # OR a service account key file:
536 # auth: { service_account_json: /secrets/sa.json }618 # auth: { service_account_json: /secrets/sa.json }
537 # Substitua o endpoint aiplatform para Private Service Connect:619 # Override the aiplatform endpoint for Private Service Connect:
538 # base_url: https://us-east5-aiplatform.p.googleapis.com620 # base_url: https://us-east5-aiplatform.p.googleapis.com
539```621```
540 622
541Um bloco `auth` vazio usa Credenciais Padrão de Aplicativo: `GOOGLE_APPLICATION_CREDENTIALS`, metadados GCE ou Workload Identity do GKE. Arquivos de chave JSON de conta de serviço são suportados mas desencorajados; use Workload Identity ou anexe uma conta de serviço à instância GCE ou Cloud Run.623Um bloco `auth` vazio usa o Application Default Credentials: `GOOGLE_APPLICATION_CREDENTIALS`, metadados do GCE ou GKE Workload Identity. Arquivos de chave JSON de conta de serviço são compatíveis, mas desaconselhados; use o Workload Identity ou anexe uma conta de serviço à instância do GCE ou do Cloud Run.
542 624
543Defina `region: global` para usar o [endpoint global do Agent Platform do Google Cloud](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations) em vez de um regional. O Google então roteia cada solicitação para uma região disponível, portanto você não rastreia disponibilidade de modelo por região. Definir uma região específica fixa cada solicitação a ela.625Defina `region: global` para usar o [endpoint global da Agent Platform do Google Cloud](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations) em vez de um regional. O Google então roteia cada requisição para uma região disponível, então você não precisa acompanhar a disponibilidade de modelos por região. Definir uma região específica fixa todas as requisições nela.
544 626
545| Configuração | Como |627| Configuração | Como |
546| - | - |628| - | - |
547| Permissões IAM | Conceda à conta de serviço do gateway `roles/aiplatform.user` no projeto, ou uma função personalizada com `aiplatform.endpoints.predict`. Habilite a API do Agent Platform do Google Cloud (`aiplatform.googleapis.com`). |629| Permissões do IAM | Conceda à conta de serviço do gateway `roles/aiplatform.user` no projeto, ou uma role personalizada com `aiplatform.endpoints.predict`. Ative a API da Agent Platform do Google Cloud (`aiplatform.googleapis.com`). |
548| Acesso ao modelo | No Model Garden, habilite os modelos Claude para seu projeto. Eles publicam em regiões específicas; verifique o cartão do modelo para regiões suportadas. |630| Acesso a modelos | No Model Garden, ative os modelos Claude para seu projeto. Eles são publicados em regiões específicas; verifique o card do modelo para ver as regiões compatíveis. |
549| GKE (Workload Identity) | Vincule uma conta de serviço GCP à conta de serviço Kubernetes do gateway e anote a KSA com `iam.gke.io/gcp-service-account: claude-gateway@<proj>.iam.gserviceaccount.com`. `auth: {}` a coleta. |631| GKE (Workload Identity) | Vincule uma conta de serviço do GCP à conta de serviço do Kubernetes do gateway e anote a KSA com `iam.gke.io/gcp-service-account: claude-gateway@<proj>.iam.gserviceaccount.com`. `auth: {}` a detecta. |
550| Cloud Run / GCE | Defina a conta de serviço do serviço para uma com `roles/aiplatform.user`. `auth: {}` a coleta. |632| Cloud Run / GCE | Defina a conta de serviço do serviço como uma que tenha `roles/aiplatform.user`. `auth: {}` a detecta. |
551| Em qualquer outro lugar | `auth: { service_account_json: /secrets/sa.json }`, o caminho para um arquivo de chave JSON montado como um segredo. O campo leva um caminho de arquivo, não o conteúdo da chave, portanto nenhuma expansão `${file:…}` está envolvida. |633| Qualquer outro lugar | `auth: { service_account_json: /secrets/sa.json }`, o caminho para um arquivo de chave JSON montado como segredo. O campo recebe um caminho de arquivo, não o conteúdo da chave, então nenhuma expansão `${file:…}` está envolvida. |
552 634
553#### Microsoft Foundry635#### Microsoft Foundry
554 636
555Para a implantação Microsoft Foundry do lado do cliente, consulte [Claude Code on Microsoft Foundry](https://code.claude.com/docs/pt/microsoft-foundry.md). O upstream do lado do gateway:637Para a implantação do Microsoft Foundry do lado do cliente, consulte [Claude Code no Microsoft Foundry](https://code.claude.com/docs/pt/microsoft-foundry.md). O upstream do lado do gateway:
556 638
557```yaml theme={null}639```yaml theme={null}
558upstreams:640upstreams:
559 - provider: foundry641 - provider: foundry
560 resource: example-foundry # https://example-foundry.services.ai.azure.com642 resource: example-foundry # https://example-foundry.services.ai.azure.com
561 auth: { use_azure_ad: true } # preferido: DefaultAzureCredential / Managed Identity643 auth: { use_azure_ad: true } # preferred: DefaultAzureCredential / Managed Identity
562 # OU uma chave de API:644 # OR an API key:
563 # auth:645 # auth:
564 # api_key: ${FOUNDRY_API_KEY}646 # api_key: ${FOUNDRY_API_KEY}
565```647```
566 648
567`use_azure_ad: true` resolve através de `DefaultAzureCredential`: Managed Identity no AKS, ACI ou App Service; a CLI do Azure; ou credenciais de ambiente. Chaves de API funcionam mas são em todo o projeto e não giram automaticamente. O endpoint do Microsoft Foundry é derivado de `resource:`; defina o `base_url` opcional para substituí-lo para nuvens soberanas como Azure Government.649`use_azure_ad: true` resolve por meio de `DefaultAzureCredential`: Managed Identity no AKS, ACI ou App Service; a Azure CLI; ou credenciais de ambiente. Chaves de API funcionam, mas valem para o projeto inteiro e não são rotacionadas automaticamente. O endpoint do Microsoft Foundry é derivado de `resource:`; defina o `base_url` opcional para sobrescrevê-lo em nuvens soberanas como o Azure Government.
568 650
569| Configuração | Como |651| Configuração | Como |
570| - | - |652| - | - |
571| RBAC | Conceda à identidade do gateway `Azure AI User` ou `Cognitive Services User` no recurso Microsoft Foundry |653| RBAC | Conceda à identidade do gateway `Azure AI User` ou `Cognitive Services User` no recurso do Microsoft Foundry |
572| Implantações | Microsoft Foundry usa nomes de implantação escolhidos pelo administrador, não IDs de modelo canônicos. Adicione um bloco [`models:`](#models) mapeando cada ID canônico para seu nome de implantação. |654| Implantações | O Microsoft Foundry usa nomes de implantação escolhidos pelo administrador, não IDs de modelo canônicos. Adicione um bloco [`models:`](#models) mapeando cada ID canônico para o nome da sua implantação. |
573| AKS (workload identity) | Federe uma Managed Identity Atribuída pelo Usuário com o emissor OIDC do cluster e vincule-a à conta de serviço do gateway. `use_azure_ad: true` a coleta via `WorkloadIdentityCredential`. |655| AKS (workload identity) | Federe uma User-Assigned Managed Identity com o emissor OIDC do cluster e vincule-a à conta de serviço do gateway. `use_azure_ad: true` a detecta via `WorkloadIdentityCredential`. |
574| ACI / App Service | Habilite identidade gerenciada atribuída pelo sistema ou pelo usuário no recurso. `use_azure_ad: true` a coleta. |656| ACI / App Service | Ative a managed identity atribuída pelo sistema ou pelo usuário no recurso. `use_azure_ad: true` a detecta. |
575| Em qualquer outro lugar | `auth: { api_key: "${FOUNDRY_API_KEY}" }`. Cite `${…}` dentro de `{ }`. |657| Qualquer outro lugar | `auth: { api_key: "${FOUNDRY_API_KEY}" }`. Coloque `${…}` entre aspas dentro de `{ }`. |
576 658
577#### Cabeçalhos estáticos em solicitações de upstream659#### Cabeçalhos estáticos nas requisições ao upstream
578 660
579Para adicionar cabeçalhos fixos às solicitações que o gateway envia para um upstream, defina `headers:` nesse upstream. Use-o quando um proxy que você executa na frente do provedor roteia ou atribui tráfego por um cabeçalho.661Para adicionar cabeçalhos fixos às requisições que o gateway envia a um upstream, defina `headers:` nesse upstream. Use isso quando um proxy que você executa à frente do provedor roteia ou atribui tráfego por um cabeçalho.
580 662
581`headers:` requer Claude Code v2.1.277 ou posterior no servidor gateway. Um gateway anterior se recusa a iniciar quando encontra a chave. Atualize cada réplica antes de adicionar a chave e remova a chave antes de reverter para uma versão anterior.663`headers:` requer Claude Code v2.1.277 ou posterior no servidor do gateway. Um gateway anterior se recusa a iniciar quando encontra a chave. Atualize todas as réplicas antes de adicionar a chave e remova a chave antes de reverter para uma versão anterior.
582 664
583Os cabeçalhos vão para o servidor que `base_url` nomeia, ou para o endpoint do próprio provedor quando `base_url` não está definido. O provedor os recebe também a menos que seu proxy os remova.665Os cabeçalhos vão para o servidor que `base_url` nomeia, ou para o próprio endpoint do provedor quando `base_url` não está definido. O provedor também os recebe, a menos que seu proxy os remova.
584 666
585Este exemplo alcança um upstream `provider: vertex` através de um proxy em `upstream-proxy.internal.example.com`. Ele define o cabeçalho `x-source` que o proxy lê e envia um token da variável de ambiente `PROXY_TOKEN` como `x-proxy-token`:667Este exemplo alcança um upstream `provider: vertex` por meio de um proxy em `upstream-proxy.internal.example.com`. Ele define o cabeçalho `x-source` que o proxy lê e envia um token da variável de ambiente `PROXY_TOKEN` como `x-proxy-token`:
586 668
587```yaml theme={null}669```yaml theme={null}
588upstreams:670upstreams:
596 x-proxy-token: ${PROXY_TOKEN}678 x-proxy-token: ${PROXY_TOKEN}
597```679```
598 680
599Os valores são texto ASCII imprimível sem espaço em nenhuma extremidade. Cite um número, `true` ou `false` para que YAML o leia como texto.681Os valores são texto ASCII imprimível sem espaço em nenhuma das extremidades. Coloque entre aspas um número, `true` ou `false` para que o YAML o leia como texto.
600 682
601Para manter um segredo fora do arquivo de configuração, use [expansão de segredo](#secret-expansion) para carregar o valor de uma variável de ambiente com `${VAR}` ou de um arquivo com `${file:/path}`. Um `${VAR}` que resolve para um valor vazio impede o gateway de iniciar.683Para manter um segredo fora do arquivo de configuração, use a [expansão de segredos](#secret-expansion) para carregar o valor de uma variável de ambiente com `${VAR}` ou de um arquivo com `${file:/path}`. Um `${VAR}` que resolve para um valor vazio impede o gateway de iniciar.
602 684
603`headers:` funciona em cada provedor, e cada upstream envia apenas o seu.685`headers:` funciona em todos os provedores, e cada upstream envia apenas os seus.
604 686
605Nem toda solicitação que o gateway envia para um upstream carrega eles:687Nem toda requisição que o gateway envia a um upstream os carrega:
606 688
607| Solicitação que o gateway envia para este upstream | Carrega `headers:` |689| Requisição que o gateway envia a este upstream | Carrega `headers:` |
608| - | - |690| - | - |
609| `/v1/messages`, streaming ou não, e `/v1/messages/count_tokens` | Sim |691| `/v1/messages`, com ou sem streaming, e `/v1/messages/count_tokens` | Sim |
610| Uma solicitação que falhou de outro upstream | Sim, apenas `headers:` deste upstream |692| Uma requisição que fez failover de outro upstream | Sim, apenas os `headers:` deste upstream |
611| Chamada `CountTokens` do Amazon Bedrock para uma solicitação que o cliente abandonou | Não |693| A chamada `CountTokens` do Amazon Bedrock para uma requisição que o cliente abandonou | Não |
612| A troca de token de Workload Identity Federation | Não |694| A troca de token do Workload Identity Federation | Não |
613 695
614Em um upstream Amazon Bedrock ou Claude Platform on AWS que assina solicitações com AWS SigV4, esses cabeçalhos fazem parte da assinatura, portanto seu proxy deve passá-los inalterados.696Em um upstream Amazon Bedrock ou Claude Platform on AWS que assina requisições com AWS SigV4, esses cabeçalhos fazem parte da assinatura, então seu proxy deve repassá-los inalterados.
615 697
616Se você usar um nome que o gateway reserva, ele se recusa a iniciar, e o erro de inicialização nomeia o cabeçalho. Os nomes reservados incluem:698Se você usar um nome que o gateway reserva, ele se recusa a iniciar, e o erro de inicialização nomeia o cabeçalho. Os nomes reservados incluem:
617 699
618* `authorization` e `x-api-key`700* `authorization` e `x-api-key`
619* `host`, `content-type` e `user-agent`701* `host`, `content-type` e `user-agent`
620* Qualquer nome começando com `anthropic-`, `x-goog-`, `x-amz-` ou `x-amzn-`702* Qualquer nome que comece com `anthropic-`, `x-goog-`, `x-amz-` ou `x-amzn-`
703
704#### Vários upstreams
621 705
622#### Múltiplos upstreams706O mesmo provedor pode aparecer mais de uma vez com um `name:` distinto. Isso cobre regiões diferentes, contas diferentes por meio de cadeias de credenciais diferentes, provisioned throughput versus sob demanda e fallback entre provedores.
623 707
624O mesmo provedor pode aparecer mais de uma vez com um `name:` distinto. Isso cobre diferentes regiões, diferentes contas através de diferentes cadeias de credencial, throughput provisionado versus sob demanda e fallback entre provedores.708O gateway tenta os upstreams em ordem. `5xx`, `429`, `401`, `403`, `404`, timeouts e endpoint ausente (`501`) fazem failover; outros `4xx` não.
625 709
626O gateway tenta upstreams em ordem. `5xx`, `429`, `401`, `403`, `404`, timeouts e endpoint ausente (`501`) falham; outro `4xx` não.710`429` é capacidade por upstream, então o esgotamento do provisioned throughput (PT) faz failover para o sob demanda. Se você definir [`forward_user_identity: true`](#per-user-identity-headers-for-a-proxy-you-run) em um upstream, um `429` para uma requisição que carregava o e-mail do desenvolvedor é, em vez disso, uma negação por usuário e não faz failover.
627 711
628`429` é capacidade por upstream, portanto esgotamento de throughput provisionado (PT) falha para sob demanda. Se você definir [`forward_user_identity: true`](#per-user-identity-headers-for-a-proxy-you-run) em um upstream, um `429` para uma solicitação que carregava o email do desenvolvedor é uma negação por usuário em vez disso e não falha.712Uma requisição passa de um upstream para o próximo apenas nestes casos:
629 713
630Cada solicitação começa no primeiro upstream. Uma solicitação alcança um upstream posterior apenas quando cada upstream à sua frente falhou ou não serve o modelo solicitado.714* O upstream falhou
715* O upstream não atende o modelo solicitado
716* O upstream tem uma [lista `groups`](#send-each-team-to-its-own-upstream) que deixa o desenvolvedor de fora
631 717
632O gateway não mantém registro de upstreams falhados, portanto enquanto um upstream está inativo, cada solicitação que o alcança ainda o tenta e aguarda sua falha antes de prosseguir.718O gateway não mantém registro de upstreams com falha, então, enquanto um upstream está fora do ar, toda requisição que chega a ele ainda o tenta e espera que ele falhe antes de seguir adiante.
633 719
634O gateway aguarda este tempo para que uma resposta comece:720O gateway espera este tempo para que uma resposta comece:
635 721
636* **Upstreams `provider: anthropic`**: [`timeouts.upstream_ttfb_ms`](#http-tuning), 120 segundos por padrão722* **Upstreams `provider: anthropic`**: [`timeouts.upstream_ttfb_ms`](#http-tuning), 120 segundos por padrão
637* **Outros provedores**: até uma hora. Para encurtar essa espera em requisições de streaming, defina `timeouts.upstream_ttfb_ms` no gateway v2.1.295 ou posterior. Requisições de modelo sem streaming aguardam até uma hora de qualquer forma723* **Outros provedores**: até uma hora. Para encurtar essa espera em requisições com streaming, defina `timeouts.upstream_ttfb_ms` no gateway v2.1.295 ou posterior. Requisições de modelo sem streaming esperam até uma hora de qualquer forma
638 724
639`404` é disponibilidade de modelo por upstream, portanto um upstream que não habilitou um modelo não bloqueia um upstream posterior que o serve. Um upstream que não pode resolver o modelo solicitado é pulado sem uma viagem de rede.725`404` é disponibilidade de modelo por upstream, então um upstream que não ativou um modelo não bloqueia um upstream posterior que o serve. Um upstream que não consegue resolver o modelo solicitado é pulado sem uma ida e volta pela rede.
640 726
641Este exemplo roteia uma alocação de throughput provisionado Amazon Bedrock primeiro, transborda para sob demanda e uma segunda conta, e recorre à API Anthropic por último:727Este exemplo roteia primeiro uma cota de provisioned throughput do Amazon Bedrock, transborda para o sob demanda e para uma segunda conta e recorre à Anthropic API por último:
642 728
643```yaml theme={null}729```yaml theme={null}
644upstreams:730upstreams:
645 # Primário: throughput provisionado em sua região inicial.731 # Primary: provisioned throughput in your home region.
646 - name: bedrock-pt732 - name: bedrock-pt
647 provider: bedrock733 provider: bedrock
648 region: us-east-1734 region: us-east-1
649 auth: {}735 auth: {}
650 # Transbordamento: sob demanda entre regiões.736 # Overflow: on-demand cross-region.
651 - name: bedrock-od737 - name: bedrock-od
652 provider: bedrock738 provider: bedrock
653 region: us-west-2739 region: us-west-2
654 auth: {}740 auth: {}
655 # Conta diferente: uma alocação Bedrock separada através de chaves estáticas.741 # Different account: a separate Bedrock allotment via static keys.
656 - name: bedrock-acct2742 - name: bedrock-acct2
657 provider: bedrock743 provider: bedrock
658 region: us-east-1744 region: us-east-1
659 auth:745 auth:
660 aws_access_key_id: ${ACCT2_AKID}746 aws_access_key_id: ${ACCT2_AKID}
661 aws_secret_access_key: ${ACCT2_SK}747 aws_secret_access_key: ${ACCT2_SK}
662 # Último recurso: API Anthropic direta.748 # Last resort: direct Anthropic API.
663 - name: anthropic-fallback749 - name: anthropic-fallback
664 provider: anthropic750 provider: anthropic
665 auth:751 auth:
666 api_key: ${ANTHROPIC_API_KEY}752 api_key: ${ANTHROPIC_API_KEY}
667 753
668# IDs de modelo por upstream são codificados no `name:` do upstream.754# Per-upstream model IDs are keyed on the upstream's `name:`.
669models:755models:
670 - id: claude-opus-4-8756 - id: claude-opus-4-8
671 label: Claude Opus 4.8757 label: Claude Opus 4.8
678 764
679| Alavanca | Como |765| Alavanca | Como |
680| - | - |766| - | - |
681| Diferentes regiões | Um upstream Amazon Bedrock por região, cada um com sua própria `region:`. Com [`auto_include_builtin_models: true`](#models) os perfis de inferência entre regiões roteiam automaticamente; para implantações fixadas por região use um bloco `models:`. |767| Regiões diferentes | Um upstream Amazon Bedrock por região, cada um com seu próprio `region:`. Com [`auto_include_builtin_models: true`](#models), os perfis de inferência entre regiões roteiam automaticamente; para implantações fixadas em uma região, use um bloco `models:`. |
682| Diferentes contas | Um upstream Amazon Bedrock por conta. A cadeia padrão (`auth: {}`) usa a identidade do pod; para uma segunda conta, adicione [`assume_role`](#bedrock-in-another-aws-account) para alcançá-la com credenciais de curta duração, ou defina credenciais explícitas ou um token de portador em `auth:`. |768| Contas diferentes | Um upstream Amazon Bedrock por conta. A cadeia padrão (`auth: {}`) usa a identidade do pod; para uma segunda conta, adicione [`assume_role`](#bedrock-in-another-aws-account) para alcançá-la com credenciais de curta duração, ou defina credenciais explícitas ou um bearer token em `auth:`. |
683| Throughput provisionado | Mapeie o modelo para o ARN de throughput provisionado em `models:` para o nome desse upstream. Outros upstreams mantêm o ID sob demanda, portanto a capacidade PT é esgotada antes de falhar. |769| Equipes diferentes | Dê ao upstream de cada equipe uma lista `groups`, para que apenas desenvolvedores nesses grupos do IdP o alcancem. Consulte [Enviar cada equipe para seu próprio upstream](#send-each-team-to-its-own-upstream). |
684| Endpoints VPC / FIPS | Defina `base_url:` no upstream para sua URL de endpoint VPC ou FIPS |770| Provisioned throughput | Mapeie o modelo para o ARN de provisioned throughput em `models:` para o nome desse upstream. Os outros upstreams mantêm o ID sob demanda, então a capacidade de PT se esgota antes do failover. |
685| Roteamento com escopo de modelo | Apenas um modelo `id` personalizado, que não é um modelo Claude integrado, pula os upstreams ausentes de seu mapa `upstream_model:`. Um upstream `mantle` é tentado apenas para os modelos listados em seu [campo `models`](#amazon-bedrock-mantle-endpoint). Em todos os outros upstreams, o gateway tenta modelos integrados em ordem e usa o ID padrão do provedor onde o mapa não tem entrada, portanto para modelos integrados o mapa muda qual ID um upstream recebe em vez de se é tentado; um upstream que rejeita o ID segue as mesmas [regras de failover](#upstreams) que qualquer outro erro de upstream. |771| Endpoints de VPC / FIPS | Defina `base_url:` no upstream como a URL do seu endpoint de VPC ou endpoint FIPS |
772| Roteamento por modelo | Um `id` de modelo personalizado, que não seja um modelo Claude integrado, ignora os upstreams ausentes do seu mapa `upstream_model:`. Um upstream com uma lista `models`, que um [upstream `mantle`](#amazon-bedrock-mantle-endpoint) precisa ter, só é tentado para esses modelos. |
773| Roteamento de modelos integrados | Em um upstream sem lista `models` ou `groups`, o gateway tenta os modelos integrados em ordem e usa o ID padrão do provedor quando o mapa `upstream_model:` não tem entrada. Para um modelo integrado para o qual o provedor tem um ID padrão, o mapa altera qual ID um upstream recebe, e não se ele é tentado. Um upstream que rejeita o ID segue as mesmas [regras de failover](#upstreams) que qualquer outro erro de upstream. |
774
775Fazer failover entre provedores de nuvem, ou para a API direta da Anthropic, altera qual contrato, geografia e outros termos regem a requisição.
776
777A CLI aplica o mesmo controle de recursos aos gateways independentemente de qual upstream atende a uma determinada requisição, portanto, por padrão, o failover não envia um campo do corpo que um upstream rejeitaria. Se você definir o [TTL de cache de uma hora](#one-hour-prompt-cache) em uma política, ele será enviado para todos os upstreams da lista, então defina-o somente se todos eles o aceitarem.
686 778
687Falhar entre provedores de nuvem ou para a API Anthropic direta muda qual acordo, geografia e outros termos governam a solicitação.779#### Enviar cada equipe para seu próprio upstream
688 780
689O CLI aplica o mesmo feature gating a gateways independentemente de qual upstream serve uma determinada solicitação, portanto, por padrão, o failover não envia um campo de corpo que um upstream rejeitaria. Se você definir o [TTL de cache de uma hora](#one-hour-prompt-cache) em uma política, ele vai para cada upstream da lista, portanto defina-o apenas se todos eles o aceitarem.781Para enviar as requisições de cada equipe para sua própria conta AWS ou projeto do Google Cloud, liste um upstream por equipe e dê a cada um uma lista `groups`. Apenas desenvolvedores em um grupo do IdP listado alcançam esse upstream, na primeira tentativa e no [failover](#multiple-upstreams). Todo provedor aceita `groups`. Requer Claude Code v2.1.314 ou posterior no servidor do gateway.
782
783Este exemplo dá aos grupos `payments-eng` e `search-eng` uma conta AWS cada, e adiciona um upstream sem lista `groups` que todo desenvolvedor pode usar:
784
785```yaml theme={null}
786upstreams:
787 - name: bedrock-payments
788 provider: bedrock
789 region: us-east-1
790 auth: {}
791 assume_role:
792 role_arn: arn:aws:iam::111111111111:role/claude-gateway-bedrock
793 groups: [payments-eng]
794 - name: bedrock-search
795 provider: bedrock
796 region: us-east-1
797 auth: {}
798 assume_role:
799 role_arn: arn:aws:iam::222222222222:role/claude-gateway-bedrock
800 groups: [search-eng]
801 - name: bedrock-shared # no groups: open to everyone, so listed last
802 provider: bedrock
803 region: us-east-1
804 auth: {}
805```
806
807Com a configuração de exemplo, as requisições de cada desenvolvedor começam no primeiro upstream de sua linha e passam para o próximo no failover:
808
809| Grupos do desenvolvedor | Upstreams, em ordem |
810| - | - |
811| `payments-eng` | `bedrock-payments`, depois `bedrock-shared` |
812| `search-eng` | `bedrock-search`, depois `bedrock-shared` |
813| `payments-eng` e `search-eng` | `bedrock-payments`, depois `bedrock-search`, depois `bedrock-shared` |
814| Nenhum | `bedrock-shared` |
815
816Quando o upstream de uma equipe nega o modelo solicitado com um `403`, o gateway tenta o próximo upstream na linha dessa equipe que atende o modelo. Para manter a equipe em um único upstream, dê a todos os upstreams uma lista `groups` e certifique-se de que nenhum outro upstream liste um grupo em que os desenvolvedores da equipe estejam. Essa equipe então não tem failover, e requisições de desenvolvedores que não estão em nenhum grupo listado [falham com um `400`](#what-happens-when-a-developer-is-in-no-listed-group).
817
818Para levar cada desenvolvedor ao upstream que você pretende, escreva entradas que correspondam exatamente e coloque os upstreams abertos por último:
819
820* **Entradas**: escreva cada grupo exatamente como seu IdP o envia na [claim de grupos](#oidc), que [`match.groups`](#managed) também lê. O gateway se recusa a iniciar quando encontra uma lista vazia ou uma entrada vazia. Ele não verifica uma entrada em relação ao seu IdP, então uma entrada que não corresponde a ninguém não gera nenhum aviso.
821* **Ordem**: coloque um upstream que não tenha lista `groups` por último. Ele atende a todos, então, se listado antes, ele captura as requisições de uma equipe antes do próprio upstream dessa equipe.
822
823> [!WARNING]
824>
825> Um gateway anterior à v2.1.314 se recusa a iniciar quando encontra `groups`, então atualize todas as réplicas antes de adicioná-lo.
826>
827> Antes de reverter, remova cada upstream que tenha uma lista `groups` e toda chave `upstream_model` ou substituição de preços que o nomeie, e mantenha pelo menos um upstream. Com apenas a chave `groups` removida, esse upstream fica aberto a todos os desenvolvedores. Uma chave ou substituição que ainda nomeie um upstream removido impede o gateway de iniciar, com `references unknown upstream`.
828
829##### O que acontece quando um desenvolvedor não está em nenhum grupo listado
830
831Se todos os upstreams tiverem uma lista `groups`, um desenvolvedor que não esteja em nenhum desses grupos vê este erro, e o gateway não contata nenhum provedor:
832
833```text theme={null}
834API Error: 400 you aren't in a group that can use this gateway. Ask your administrator to add you to one
835```
836
837Adicione o desenvolvedor a um grupo listado no seu IdP, ou adicione um upstream sem lista `groups`.
838
839O gateway lê novamente os grupos de um desenvolvedor a cada atualização de token. Se o seu IdP deixar os grupos de fora de uma atualização, o desenvolvedor passa a não ter nenhum:
840
841* **[`oidc.allowed_groups`](#oidc) está definido**: o gateway recusa a atualização, e a sessão termina
842* **Caso contrário, um upstream não tem lista `groups`**: as requisições do desenvolvedor passam para ele
843* **Caso contrário, todos os upstreams têm uma lista `groups`**: as requisições do desenvolvedor falham com esse erro
844
845Se o endpoint userinfo do seu IdP retornar a claim de grupos e `oidc.google_groups` não estiver definido, defina [`oidc.userinfo_fallback`](#oidc) como `true` para preencher os grupos a partir dele.
690 846
691## Seções opcionais847## Seções opcionais
692 848
782 938
783#### Enviar as tarifas para clientes conectados939#### Enviar as tarifas para clientes conectados
784 940
785Com a v2.1.268 ou posterior no servidor do gateway, o gateway também coloca as tarifas de `pricing` nas políticas [`managed`](#managed) que serve, como a configuração gerenciada [`modelPricing`](https://code.claude.com/docs/pt/settings-reference#modelpricing). Os desenvolvedores correspondidos por uma política passam então a ver as tarifas de `pricing` do primeiro upstream que atende cada ID de modelo em `/usage`, na linha de status e no OpenTelemetry. Um desenvolvedor que não corresponde a nenhuma política não recebe configurações gerenciadas, então seus valores permanecem no preço de tabela. Os clientes aplicam a configuração no Claude Code v2.1.242 ou posterior.941Com a v2.1.268 ou posterior no servidor do gateway, o gateway também coloca as tarifas de `pricing` nas políticas [`managed`](#managed) que ele serve, como a configuração gerenciada [`modelPricing`](https://code.claude.com/docs/pt/settings-reference#modelpricing).
942
943Os desenvolvedores correspondidos por uma política passam a ver as tarifas de `pricing` em `/usage`, na linha de status e no OpenTelemetry. Um desenvolvedor que não corresponde a nenhuma política não recebe configurações gerenciadas, então seus números permanecem no preço de tabela. Os clientes aplicam a configuração no Claude Code v2.1.242 ou posterior.
786 944
787* O que o gateway adiciona: a menos que o bloco `cli` de uma política já defina `modelPricing`, o gateway adiciona o `multiplier` e, para cada ID de modelo que um cliente pode solicitar, a linha de override do primeiro upstream que atende esse ID. Uma tarifa que apenas um upstream de failover cobra permanece no gateway.945* O que o gateway adiciona: a menos que o bloco `cli` de uma política já defina `modelPricing`, o gateway adiciona o `multiplier` e, para cada ID de modelo que um cliente pode solicitar, a linha de override do primeiro upstream que atende esse ID. Uma tarifa que apenas um upstream de failover cobra permanece no gateway.
946* Upstreams com uma [lista `groups`](#send-each-team-to-its-own-upstream): quando um deles é o primeiro upstream que atende um ID de modelo, o gateway não adiciona nenhuma linha para esse ID. Os desenvolvedores então veem a tarifa do próprio Claude Code para esse ID, que é a tarifa padrão do modelo quando o Claude Code reconhece o ID, vezes o `multiplier`.
788* Excluir uma política: defina `modelPricing` como `{}` no bloco `cli` dessa política, e seus desenvolvedores permanecem no preço de tabela.947* Excluir uma política: defina `modelPricing` como `{}` no bloco `cli` dessa política, e seus desenvolvedores permanecem no preço de tabela.
789* Manter as tarifas próprias de uma política: uma política cujo bloco `cli` define `modelPricing` com seu próprio `multiplier` ou `overrides` mantém esse `modelPricing` inteiro, e o gateway não adiciona nenhuma tarifa própria a ele.948* Manter as tarifas próprias de uma política: uma política cujo bloco `cli` define `modelPricing` com seu próprio `multiplier` ou `overrides` mantém esse `modelPricing` inteiro, e o gateway não adiciona nenhuma tarifa própria a ele.
790 949
808 967
809### `managed`968### `managed`
810 969
811O bloco `managed` define políticas de acesso baseadas em funções, indexadas por grupos do IdP ou domínio de e-mail. As políticas são avaliadas em ordem; a primeira correspondência é selecionada e depois mesclada sobre a base catch-all `match: {}`. Elas são servidas por usuário em `GET /managed/settings` com cache ETag/304.970O bloco `managed` define políticas de acesso baseadas em funções, indexadas por grupos do IdP ou domínio de email. As políticas são avaliadas em ordem; por padrão, a primeira correspondência é selecionada e depois mesclada sobre a base genérica `match: {}`. Um usuário que corresponde a duas políticas de função recebe apenas a primeira, então as regras de negação da segunda política não se aplicam, a menos que você [aplique todas as políticas correspondentes](#apply-every-matching-policy). As políticas são servidas por usuário em `GET /managed/settings` com cache ETag/304.
812 971
813```yaml theme={null}972```yaml theme={null}
814managed:973managed:
849 1008
850Um usuário autenticado que não corresponde a nenhuma política recebe os padrões do gateway, o que significa todos os modelos do catálogo e nenhuma configuração gerenciada. Adicione um catch-all `match: {}` por último se quiser uma política padrão garantida.1009Um usuário autenticado que não corresponde a nenhuma política recebe os padrões do gateway, o que significa todos os modelos do catálogo e nenhuma configuração gerenciada. Adicione um catch-all `match: {}` por último se quiser uma política padrão garantida.
851 1010
1011Coloque as regras de negação de toda a organização na política `match: {}`, porque as regras de uma política de grupo só se aplicam enquanto o token do usuário contiver esse grupo.
1012
852> [!NOTE]1013> [!NOTE]
853>1014>
854> O gateway não mantém um diretório de usuários próprio. Ele autoriza cada requisição a partir do token do IdP do usuário, lendo a associação a grupos da claim `groups` do token e avaliando as políticas com base nela. Não há lista de usuários para enumerar nem contas para pré-criar e, portanto, não há endpoint SCIM, porque não há nada para o SCIM sincronizar.1015> O gateway não mantém um diretório de usuários próprio. Ele autoriza cada requisição a partir do token do IdP do usuário, lendo a associação a grupos da claim `groups` do token e avaliando as políticas com base nela. Não há lista de usuários para enumerar nem contas para pré-criar e, portanto, não há endpoint SCIM, porque não há nada para o SCIM sincronizar.
862>1023>
863> O Claude Desktop segue [seu próprio cronograma](#when-a-policy-change-reaches-claude-desktop).1024> O Claude Desktop segue [seu próprio cronograma](#when-a-policy-change-reaches-claude-desktop).
864 1025
1026#### Aplicar todas as políticas correspondentes
1027
1028Um usuário que corresponde a várias políticas de função recebe apenas a primeira, a menos que você defina `policy_mode: layered` ao lado de `policies`. Com `layered`, todas as políticas que correspondem ao usuário se aplicam, até a primeira política `match: {}`.
1029
1030`policy_mode` requer o Claude Code v2.1.316 ou posterior no servidor do gateway. Um gateway em uma versão que não o suporta se recusa a iniciar quando encontra a chave. Atualize todas as réplicas antes de adicionar a chave e remova a chave antes de reverter para uma versão anterior. Este exemplo tem um grupo que perde `WebFetch` e um que ganha o Opus:
1031
1032```yaml theme={null}
1033managed:
1034 policy_mode: layered
1035 policies:
1036 - match: { groups: [no-web] }
1037 cli:
1038 permissions: { deny: ["WebFetch"] }
1039 - match: { groups: [opus-users] }
1040 cli:
1041 availableModels: [opus, sonnet]
1042 - match: {}
1043 cli:
1044 availableModels: [sonnet]
1045 enforceAvailableModels: true
1046```
1047
1048A tabela mostra o que um usuário em `no-web` e `opus-users` recebe com o padrão, `first_match`, e com `layered`.
1049
1050| Configuração | `first_match` | `layered` |
1051| - | - | - |
1052| `availableModels` | `sonnet` | `opus`, `sonnet` |
1053| `enforceAvailableModels` | `true` | `true` |
1054| `permissions.deny` | `WebFetch` | `WebFetch` |
1055
1056O gateway mescla cada política correspondente sobre as listadas abaixo dela, pelas mesmas [regras de mesclagem](#managed) da camada base:
1057
1058* **Allowlists, valores únicos e blocos como `sandbox`**: cada um vem inteiro da primeira política correspondente listada que o define, então as listas `availableModels` de dois grupos não se somam.
1059* **Listas de negação e arrays de hooks**: estes se somam entre todas as políticas correspondentes, então um usuário em dois grupos recebe as regras de negação de ambos os grupos.
1060* **`env`, `modelOverrides` e `skillOverrides`**: as entradas são mescladas por nome, e a primeira política correspondente listada que define um nome fornece seu valor.
1061* **Chaves de `desktop`**: estas são mescladas pelas [regras do bloco `desktop` base](#how-a-role-policy-inherits-the-base-desktop-block).
1062
1063> [!WARNING]
1064>
1065> As políticas podem se somar em regras mais permissivas do que qualquer uma delas sozinha. Por exemplo, a política `match: {}` define `sandbox.enabled: true`, a política de um grupo define `permissions.allow: ["Bash"]` e a de outro grupo define `sandbox.enabled: false`. Um usuário em ambos os grupos recebe `Bash` permitido com o sandbox desativado. Nesse caso, liste primeiro a política que permite `Bash` e copie para ela o bloco `sandbox` inteiro da política `match: {}`.
1066
1067Com `layered`, o gateway se recusa a iniciar com algumas configurações, incluindo estas:
1068
1069* **Um padrão `!`**: uma [negação `!`](https://code.claude.com/docs/pt/permissions#special-characters-and-negation) em uma regra `Read` ou `Edit` na lista `permissions.deny` ou `permissions.ask` de qualquer política, incluindo a da política `match: {}`
1070* **Um limite sobre hooks fora da genérica**: `disableAllHooks`, `allowedHttpHookUrls` ou `httpHookAllowedEnvVars` em qualquer política que não seja `match: {}`
1071
865#### Iniciar sessões em um modelo que a política permite1072#### Iniciar sessões em um modelo que a política permite
866 1073
867Se `availableModels` deixar de fora o modelo padrão do Claude Code, as sessões recebem respostas `400` até que o desenvolvedor escolha um modelo listado, por exemplo com `/model`. Em sessões do gateway, o padrão é o modelo Opus para o qual o alias `opus` é resolvido, e `availableModels` sozinho não o altera.1074Se `availableModels` deixar de fora o modelo padrão do Claude Code, as sessões recebem respostas `400` até que o desenvolvedor escolha um modelo listado, por exemplo com `/model`. Em sessões do gateway, o padrão é o modelo Opus para o qual o alias `opus` é resolvido, e `availableModels` sozinho não o altera.
