1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# Configuração do gateway de aplicativos Claude
6
7> Referência para cada opção de gateway.yaml: listener e TLS, OIDC, sessão, armazenamento Postgres, upstreams Bedrock/Agent Platform/Foundry, roteamento de modelos, políticas gerenciadas e telemetria.
8
9Uma implantação de gateway de aplicativos Claude é configurada por um arquivo YAML, convencionalmente `gateway.yaml`. O arquivo define tudo o que o gateway faz: onde ele escuta, como os desenvolvedores fazem login, para onde a inferência vai e quais políticas e telemetria se aplicam. Esta página é a referência para cada opção nesse arquivo. Para escrever o seu primeiro, comece pelo [quickstart](/pt/claude-apps-gateway#quickstart), que constrói uma configuração mínima funcional e a executa; uma vez que você tenha uma configuração com a qual esteja satisfeito, o [guia de implantação](/pt/claude-apps-gateway-deploy) cobre a containerização e hospedagem no Kubernetes, Cloud Run ou sua própria plataforma.
10
11O gateway lê o arquivo uma vez, na inicialização, com `claude gateway --config /path/to/gateway.yaml`. Cada opção é validada contra um esquema na inicialização, portanto uma configuração malformada falha no início com um erro no nível do campo em vez de no primeiro uso.
12
13O [exemplo completo](#complete-example) no final desta página exercita cada seção.
14
15<h2 id="file-structure">
16 Estrutura do arquivo
17</h2>
18
19Cinco seções são [obrigatórias](#required-sections). Todas as outras seções são [opcionais](#optional-sections), e uma seção omitida assume seus padrões. Chaves desconhecidas falham na inicialização, portanto um erro de digitação aparece como um erro nomeado em vez de uma configuração silenciosamente ignorada.
20
21**Seções obrigatórias:**
22
23* [`listen`](#listen): endereço de vinculação, URL pública, terminação TLS
24* [`oidc`](#oidc): seu provedor de identidade (IdP), incluindo emissor, cliente, mapeamento de declarações e quem pode fazer login
25* [`session`](#session): os tokens de portador que o gateway emite, com segredo e tempo de vida
26* [`store`](#store): PostgreSQL, para concessões de dispositivo e contadores de limite de taxa
27* [`upstreams`](#upstreams): para onde a inferência vai, seja Anthropic, Bedrock, Agent Platform ou Foundry
28
29**Seções opcionais:**
30
31* [`admin`](#admin): autenticação da API de administração e retenção para limites de gastos
32* [`enforcement`](#enforcement): comportamento de falha aberta ou fechada do limite de gastos
33* [`models`](#models) e `auto_include_builtin_models`: lista de modelos curada pelo administrador e IDs por upstream
34* [`managed`](#managed): políticas de configurações gerenciadas por grupo IdP
35* [`telemetry`](#telemetry): encaminhamento OTLP para sua pilha de observabilidade
36* [`access_control`, `limits`, `timeouts`, `rate_limits`](#http-tuning): permitir/negar IP, limites de tamanho de solicitação, tempo até o primeiro byte upstream e limites de login por IP
37
38<h2 id="secret-expansion">
39 Expansão de segredos
40</h2>
41
42Não escreva segredos como `client_secret`, `jwt_secret` ou `postgres_url` diretamente em `gateway.yaml`. Faça referência a eles com um dos formulários abaixo, e o gateway resolve o valor na inicialização a partir de uma variável de ambiente ou um arquivo:
43
44| Formulário | Resolve para | Use para |
45| --------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
46| `${VAR}` | A variável de ambiente `VAR`. A inicialização falha se não estiver definida. | Variáveis de ambiente de contêiner, AWS Secrets Manager via injeção de env |
47| `${file:/path}` | Conteúdo do arquivo, aparado | Montagens de volume do Kubernetes Secret, Vault Agent, SOPS |
48
49<h2 id="required-sections">
50 Seções obrigatórias
51</h2>
52
53<h3 id="listen">
54 `listen`
55</h3>
56
57O 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.
58
59| Campo | Obrigatório | Descrição |
60| ---------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
61| `host` | Não | Endereço de vinculação. Padrão `0.0.0.0`. |
62| `port` | Não | Porta de vinculação. Padrão `8080`. |
63| `public_url` | Atrás de um proxy | A origem `https://` visível externamente, usada para construir o `redirect_uri` do IdP e metadados de descoberta. Obrigatório atrás de qualquer proxy que termine TLS, como um ALB, Ingress ou Cloud Run, porque o gateway não confia em cabeçalhos `X-Forwarded-*` ao construir sua própria origem; eles são falsificáveis pelo cliente. `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. |
64| `tls.cert` / `tls.key` | Não | Caminhos PEM se o gateway termina TLS por si mesmo |
65| `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 limitação de taxa por IP e auditoria. Equivalente ao nginx `set_real_ip_from`. |
66
67<h3 id="oidc">
68 `oidc`
69</h3>
70
71OpenID Connect (OIDC) é o protocolo SSO que o gateway usa com seu provedor de identidade; consulte [Configuração do provedor de identidade](/pt/claude-apps-gateway-deploy#identity-provider-setup) para saber o que registrar no lado do IdP. O 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.
72
73| Campo | Obrigatório | Descrição |
74| ------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
75| `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](/pt/claude-apps-gateway-deploy#threat-model-summary) a menos que `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1` esteja definido no ambiente do gateway. |
76| `client_id` / `client_secret` | Sim | Do seu registro de cliente OAuth |
77| `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. |
78| `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. |
79| `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. |
80| `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. |
81| `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. |
82| `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](/pt/claude-apps-gateway-deploy#identity-provider-setup) para receitas de escopo por IdP, como o fluxo de token de atualização do Google. |
83| `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`. |
84| `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`. |
85| `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. |
86| `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. |
87| `token_endpoint_auth_method` | Não | Substitua o método de autenticação do endpoint de token. Aceita `client_secret_basic` ou `client_secret_post`. Negociado automaticamente por padrão. |
88| `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. |
89| `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 |
90| `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/`. |
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. |
92| `ca_cert_pem` | Não | Certificado CA PEM que substitui o armazenamento de confiança do sistema apenas para solicitações do IdP. Use para Keycloak ou Dex atrás de PKI corporativa. |
93
94<h3 id="session">
95 `session`
96</h3>
97
98O 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.
99
100| Campo | Obrigatório | Descrição |
101| ------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
102| `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. |
103| `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. |
104
105<h3 id="store">
106 `store`
107</h3>
108
109O bloco `store` aponta o gateway para seu banco de dados PostgreSQL, que contém concessões de dispositivo e contadores de limite de taxa.
110
111| Campo | Obrigatório | Descrição |
112| ----------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
113| `postgres_url` | Sim | URL `postgres://` ou `postgresql://`. Obrigatório: o encontro de concessão de dispositivo, onde o callback do navegador escreve e o CLI de sondagem lê, precisa de estado entre réplicas. O gateway executa suas próprias migrações de esquema na inicialização, portanto a função precisa de `CREATE TABLE` no esquema de destino. Se sua política de segurança proíbe DDL da função de aplicativo, execute as migrações com uma função de administrador, inicialmente e novamente sempre que uma nova versão envie migrações, e conceda à função de aplicativo `SELECT, INSERT, UPDATE, DELETE` nas tabelas do gateway. Consulte [Atualizações](/pt/claude-apps-gateway-deploy#upgrades) e [Postgres](/pt/claude-apps-gateway-deploy#postgres). |
114| `username` | Não | Substitui o usuário em `postgres_url` |
115| `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. |
116| `max_connections` | Não | Tamanho do pool de conexão Postgres por réplica. Padrão `5`, que é conservador e amigável para bancos de dados compartilhados. Com [limites de gastos](#admin) habilitados, o caminho quente faz algumas operações por solicitação de inferência, portanto aumente para um banco de dados dedicado sob carga e mantenha réplicas × isto abaixo do `max_connections` do banco de dados. |
117
118Para 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`.
119
120<h3 id="upstreams">
121 `upstreams`
122</h3>
123
124`upstreams` é uma lista ordenada. O gateway encaminha inferência para o primeiro upstream que resolve o modelo solicitado. Em `5xx`, `429` ou timeout, ele falha para o próximo; outro `4xx` não, porque esses erros são atribuíveis à solicitação em vez do upstream. Múltiplos upstreams do mesmo provedor devem definir um `name:` distinto.
125
126Clientes Bedrock, Agent Platform e 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).
127
128<h4 id="anthropic-api">
129 Anthropic API
130</h4>
131
132O upstream Anthropic mínimo é uma chave de API do [Claude Console](https://platform.claude.com):
133
134```yaml theme={null}
135upstreams:
136 - provider: anthropic
137 auth:
138 api_key: ${ANTHROPIC_API_KEY}
139 # OU um portador OAuth (por exemplo, um token trocado por Workload-Identity-Federation):
140 # oauth_token: ${file:/var/run/secrets/anthropic-oauth-token}
141 # base_url: https://api.anthropic.com # padrão; substitua por um proxy de encaminhamento
142```
143
144As duas formas de credencial diferem no cabeçalho que enviam:
145
146* **`api_key`**: envia `x-api-key`. Gire-a no Claude Console e atualize a variável env.
147* **`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.
148
149Em 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.
150
151```yaml theme={null}
152upstreams:
153 - provider: anthropic
154 auth:
155 federation_rule_id: ${ANTHROPIC_FEDERATION_RULE_ID}
156 organization_id: ${ANTHROPIC_ORGANIZATION_ID}
157 identity_token_file: /var/run/secrets/anthropic/id-token
158 # workspace_id: wrkspc_... # obrigatório se a regra cobre >1 workspace
159 # service_account_id: svac_... # verificação de alvo esperado opcional
160```
161
162<h4 id="amazon-bedrock">
163 Amazon Bedrock
164</h4>
165
166Para a implantação Bedrock do lado do cliente que o gateway substitui ou está na frente, consulte [Claude Code on Amazon Bedrock](/pt/amazon-bedrock). O upstream do lado do gateway:
167
168```yaml theme={null}
169upstreams:
170 - provider: bedrock
171 region: us-east-1
172 auth: {} # preferido: cadeia de credencial padrão AWS
173 # OU credenciais explícitas:
174 # auth:
175 # aws_access_key_id: ${AWS_AKID}
176 # aws_secret_access_key: ${AWS_SK}
177 # aws_session_token: ${AWS_ST}
178 # OU um token de portador da API Bedrock:
179 # auth:
180 # aws_bearer_token: ${AWS_BEARER_TOKEN}
181 # Substitua o endpoint bedrock-runtime para implantações FIPS ou VPC-endpoint:
182 # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com
183```
184
185Um 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.
186
187| Configuração | Como |
188| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
189| 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.*`. |
190| Acesso ao modelo | No console Bedrock, por região, solicite e habilite acesso ao modelo para os modelos Claude que você deseja. Perfis de inferência entre regiões (`us.anthropic.*`) requerem acesso ao modelo em cada região que o perfil abrange. |
191| 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. |
192| ECS / EC2 | Anexe a função IAM à definição de tarefa ou perfil de instância. `auth: {}` a coleta. |
193| 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}` |
194| 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. |
195
196<h4 id="google-cloud-agent-platform">
197 Google Cloud Agent Platform
198</h4>
199
200Para a configuração equivalente do lado do cliente, consulte [Claude Code on Google Cloud](/pt/google-vertex-ai). O upstream do lado do gateway:
201
202```yaml theme={null}
203upstreams:
204 - provider: vertex
205 region: us-east5
206 project_id: example-prod
207 auth: {} # preferido: Credenciais Padrão de Aplicativo
208 # OU um arquivo de chave de conta de serviço:
209 # auth: { service_account_json: /secrets/sa.json }
210 # Substitua o endpoint aiplatform para Private Service Connect:
211 # base_url: https://us-east5-aiplatform.p.googleapis.com
212```
213
214Um 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.
215
216Defina `region: global` para usar o [endpoint global do Agent Platform](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.
217
218| Configuração | Como |
219| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
220| 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 (`aiplatform.googleapis.com`). |
221| 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. |
222| 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. |
223| Cloud Run / GCE | Defina a conta de serviço do serviço para uma com `roles/aiplatform.user`. `auth: {}` a coleta. |
224| 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. |
225
226<h4 id="microsoft-foundry">
227 Microsoft Foundry
228</h4>
229
230Para a implantação Foundry do lado do cliente, consulte [Claude Code on Microsoft Foundry](/pt/microsoft-foundry). O upstream do lado do gateway:
231
232```yaml theme={null}
233upstreams:
234 - provider: foundry
235 resource: example-foundry # https://example-foundry.services.ai.azure.com
236 auth: { use_azure_ad: true } # preferido: DefaultAzureCredential / Managed Identity
237 # OU uma chave de API:
238 # auth:
239 # api_key: ${FOUNDRY_API_KEY}
240```
241
242`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 Foundry é derivado de `resource:`; defina o `base_url` opcional para substituí-lo para nuvens soberanas como Azure Government.
243
244| Configuração | Como |
245| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
246| RBAC | Conceda à identidade do gateway `Azure AI User` ou `Cognitive Services User` no recurso Foundry |
247| Implantações | 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. |
248| 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`. |
249| ACI / App Service | Habilite identidade gerenciada atribuída pelo sistema ou pelo usuário no recurso. `use_azure_ad: true` a coleta. |
250| Em qualquer outro lugar | `auth: { api_key: "${FOUNDRY_API_KEY}" }`. Cite `${…}` dentro de `{ }`. |
251
252<h4 id="multiple-upstreams">
253 Múltiplos upstreams
254</h4>
255
256O 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.
257
258O gateway tenta upstreams em ordem. `5xx`, `429`, timeouts e endpoint ausente (`501`) falham; outro `4xx` não. `429` é capacidade por upstream, portanto esgotamento de throughput provisionado (PT) falha para sob demanda. Um upstream que não pode resolver o modelo solicitado é pulado sem uma viagem de rede.
259
260Este exemplo roteia uma alocação de throughput provisionado Bedrock primeiro, transborda para sob demanda e uma segunda conta, e volta para a API Anthropic por último:
261
262```yaml theme={null}
263upstreams:
264 # Primário: throughput provisionado em sua região inicial.
265 - name: bedrock-pt
266 provider: bedrock
267 region: us-east-1
268 auth: {}
269 # Transbordamento: sob demanda entre regiões.
270 - name: bedrock-od
271 provider: bedrock
272 region: us-west-2
273 auth: {}
274 # Conta diferente: uma alocação Bedrock separada através de credenciais de função assumida.
275 - name: bedrock-acct2
276 provider: bedrock
277 region: us-east-1
278 auth:
279 aws_access_key_id: ${ACCT2_AKID}
280 aws_secret_access_key: ${ACCT2_SK}
281 # Último recurso: API Anthropic direta.
282 - name: anthropic-fallback
283 provider: anthropic
284 auth:
285 api_key: ${ANTHROPIC_API_KEY}
286
287# IDs de modelo por upstream são codificados no `name:` do upstream; um upstream
288# sem um `name:` assume como padrão sua string de provedor (por exemplo, `bedrock`). Qualquer
289# upstream não listado para um modelo é pulado, que é como você roteia um modelo
290# para throughput provisionado enquanto tudo mais fica sob demanda.
291models:
292 - id: claude-opus-4-8
293 label: Claude Opus 4.8
294 upstream_model:
295 bedrock-pt: arn:aws:bedrock:us-east-1:111111111111:provisioned-model/abcdef
296 bedrock-od: us.anthropic.claude-opus-4-8
297 bedrock-acct2: us.anthropic.claude-opus-4-8
298 anthropic-fallback: claude-opus-4-8
299```
300
301| Alavanca | Como |
302| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
303| Diferentes regiões | Um upstream 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:`. |
304| Diferentes contas | Um upstream Bedrock por conta, cada um com suas próprias credenciais em `auth:`. A cadeia padrão (`auth: {}`) usa a identidade do pod; para uma segunda conta, defina credenciais explícitas ou um token de portador. |
305| 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. |
306| Endpoints VPC / FIPS | Defina `base_url:` no upstream para sua URL de endpoint VPC ou FIPS |
307| Roteamento com escopo de modelo | Omita um upstream do mapa `upstream_model:` de um modelo e esse upstream é pulado para esse modelo. Por exemplo, rotear Opus para throughput provisionado e Sonnet e Haiku para sob demanda. |
308
309Falhar entre provedores de nuvem ou para a API Anthropic direta muda qual acordo, geografia e outros termos governam a solicitação.
310
311O CLI aplica o mesmo feature gating a gateways independentemente de qual upstream serve uma determinada solicitação, portanto o failover não envia um campo de corpo que um upstream rejeitaria.
312
313<h2 id="optional-sections">
314 Seções opcionais
315</h2>
316
317<h3 id="admin">
318 `admin`
319</h3>
320
321Opcional. Habilita `/v1/organizations/spend_limits`, que espelha a API de Administração Pública da Anthropic, e aplicação de gastos por desenvolvedor em `/v1/messages`. Consulte [Limites de gastos](/pt/claude-apps-gateway-spend-limits) para saber como os limites são definidos e aplicados; esta seção cobre as chaves `gateway.yaml` que ativam o recurso e o ajustam.
322
323```yaml theme={null}
324admin:
325 # Chaves de API estáticas nomeadas para os endpoints de administração, enviadas como x-api-key.
326 # O id aparece no log de auditoria como admin-key:<id> portanto cada chave é
327 # atribuível. Array para rotação: adicione a nova chave, role clientes,
328 # remova a antiga.
329 write_keys:
330 - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
331 - { id: ci, key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }
332 read_keys:
333 - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
334 # Grupos IdP concedidos acesso total de administrador através do JWT normal do gateway (sem chave de API).
335 admin_groups: [platform-finops]
336 blocked_message: request an increase at https://go.example.com/claude-limits
337```
338
339| Campo | Obrigatório | Descrição |
340| ------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
341| `write_keys` | Não | Array de `{id, key}`. Um `x-api-key` correspondente a um desses pode listar, definir e deletar limites de gastos. Os valores das chaves devem ter pelo menos 32 caracteres; `id`s devem ser únicos em `read_keys` e `write_keys`. |
342| `read_keys` | Não | Array de `{id, key}`. Somente leitura: cada endpoint `GET`, incluindo listagem de limites, busca de um por ID e leitura de [`/effective`](/pt/claude-apps-gateway-spend-limits#%2Feffective) e [`/audit`](/pt/claude-apps-gateway-spend-limits#%2Faudit). |
343| `admin_groups` | Não | Nomes de grupos IdP. Um JWT do gateway cuja declaração `groups` inclui um desses tem acesso total de administrador, leitura e escrita, e audita como `oidc:<sub>`. Use isso para administradores humanos; use chaves de API para máquinas. |
344| `blocked_message` | Não | Anexado literalmente ao `429 billing_error` que um desenvolvedor bloqueado vê. Escreva a instrução completa, como uma URL ou canal Slack. Não definido, o erro é `spend limit reached`. |
345| `audit_retention_days` | Não | Padrão `365`. Linhas `admin_audit` mais antigas são varridas. |
346| `spend_retention_months` | Não | Padrão `13`. Linhas do contador `spend` mais antigas que isso são varridas. O padrão mantém um ano completo mais o mês parcial atual para relatórios ano a ano. |
347| `identity_retention_days` | Não | Padrão `90`. TTL de última visualização para linhas `principal_emails`, que contêm email, nome de exibição e grupos de cada desenvolvedor (PII). Deliberadamente mais curto que retenção de gastos para que uma identidade desprovisionada envelheça enquanto seus contadores de gastos anônimos permanecem. |
348| `group_limit_mode` | Não | `min` (padrão) ou `max`. Quando um desenvolvedor está em vários grupos com limites, `min` aplica o mais restritivo e `max` o menos. Usado tanto por aplicação quanto por `/effective`. |
349
350<h3 id="enforcement">
351 `enforcement`
352</h3>
353
354O bloco `enforcement` controla como as verificações de limite de gastos se comportam quando o armazenamento está indisponível.
355
356| Campo | Obrigatório | Descrição |
357| ---------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
358| `fail_closed_on_error` | Não | Padrão `false`. A aplicação de gastos falha aberta em uma interrupção do Postgres, portanto a inferência fica ativa. Defina `true` para falhar fechado: desenvolvedores acima do limite são bloqueados, mas também todos se o armazenamento estiver inacessível. Não tem efeito sem um bloco [`admin:`](#admin). |
359
360<h3 id="models">
361 `models`
362</h3>
363
364O bloco `models` é uma lista de modelos curada pelo administrador opcional, servida em `/v1/models` e usada para traduzir IDs de modelo por upstream. É obrigatório para regiões Bedrock fora dos EUA, ARNs de throughput provisionado Bedrock e nomes de implantação Foundry.
365
366```yaml theme={null}
367auto_include_builtin_models: true # false: expor apenas a lista abaixo
368models:
369 - id: claude-opus-4-8
370 label: Claude Opus 4.8
371 # description: texto opcional mostrado em clientes que o exibem
372 upstream_model:
373 anthropic: claude-opus-4-8
374 bedrock: us.anthropic.claude-opus-4-8 # ou um ARN de perfil de inferência
375 foundry: your-opus-deployment-name
376```
377
378<h3 id="managed">
379 `managed`
380</h3>
381
382O bloco `managed` define políticas de acesso baseadas em função codificadas em grupos IdP ou domínio de email. As políticas são avaliadas em ordem; a primeira correspondência é selecionada, depois mesclada na base `match: {}` catch-all descrita abaixo. Elas são servidas por usuário em `GET /managed/settings` com cache ETag/304.
383
384```yaml theme={null}
385managed:
386 policies:
387 # Grupos específicos primeiro.
388 - match: { groups: [eng-contractors] }
389 cli:
390 availableModels: [claude-sonnet-4-6]
391 permissions: { deny: ["WebFetch", "WebSearch"] }
392 # Catch-all padrão por último: corresponde a todos que se autenticaram.
393 - match: {}
394 cli:
395 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
396```
397
398Um catch-all `match: {}`, convencionalmente listado por último, é tratado como uma camada base. Cada outra política herda qualquer chave que não defina do catch-all, portanto entradas por função apenas precisam listar o que difere do padrão da organização. As regras de mesclagem dependem do tipo de chave:
399
400* **Listas de permissão**: `availableModels` e `permissions.allow`. A lista de uma política específica substitui completamente a da base.
401* **Listas de negação e arrays de hook**: `permissions.deny`, `permissions.ask`, `disabledMcpjsonServers`, `deniedMcpServers`, `blockedMarketplaces` e cada array de tipo de evento `hooks`. Estes tomam a união de base e política, portanto uma negação em toda a organização ou hook de auditoria não pode ser acidentalmente descartada por uma substituição por função.
402* **Chaves do tipo registro**: `env`, `modelOverrides` e `skillOverrides`. Estes mesclam superficialmente, portanto um bloco `env` por função substitui as chaves que define e herda o resto da base.
403
404`availableModels` também é aplicado no servidor em `/v1/messages`, portanto um modelo negado retorna `400` independentemente do que o cliente envia.
405
406| Correspondente | Comportamento |
407| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
408| `match: {}` | Corresponde a cada usuário autenticado. Comece com um desses e adicione políticas com escopo de grupo acima mais tarde. |
409| `match: { groups: [a, b] }` | Corresponde se a declaração `groups` do JWT contiver qualquer um dos grupos listados. Sensível a maiúsculas/minúsculas: grupos devem corresponder ao invólucro exato do IdP. |
410| `match: { email_domain: example.com }` | Corresponde à parte após o último `@` na declaração `email` do JWT, insensível a maiúsculas/minúsculas. Aceita um domínio por política. |
411| `match: { groups: [a], email_domain: example.com }` | Ambas as condições devem corresponder |
412
413Um usuário autenticado que não corresponde a nenhuma política obtém os padrões do gateway, o que significa cada modelo no catálogo e nenhuma configuração gerenciada. Adicione um catch-all `match: {}` por último se quiser uma política padrão garantida.
414
415<Note>
416 O gateway não mantém seu próprio diretório de usuários. Ele autoriza cada solicitação do token IdP do usuário, lendo associação de grupo da declaração `groups` do token e avaliando políticas contra ela. Não há lista para enumerar e nenhuma conta para pré-criar, e portanto nenhum endpoint SCIM, porque não há nada para SCIM sincronizar.
417
418 Execute gerenciamento de ciclo de vida de usuário e grupo na fonte de verdade, que é o provisionamento SCIM nativo do seu IdP ou uma plataforma dedicada de governança de identidade. Associação e desprovisionamento governados lá fluem para o gateway automaticamente através do token. Se você quiser provisionamento SCIM de contas Claude em si, essa é uma capacidade [Claude for Enterprise](/pt/admin-setup).
419
420 Dois relógios de propagação se aplicam:
421
422 * **Conteúdo da política**: editar uma política e reimplantar alcança clientes conectados em sua próxima sondagem de configurações gerenciadas, dentro de uma hora
423 * **Associação de grupo**: mudar a associação de grupo de um usuário muda qual política os corresponde. Isso entra em vigor na próxima re-cunhagem de sessão, significando a próxima atualização silenciosa, limitada por `session.ttl_hours`.
424</Note>
425
426<h4 id="what-goes-in-cli">
427 O que vai em `cli`
428</h4>
429
430Cada valor `cli` é um documento `managed-settings.json` completo do Claude Code, o mesmo esquema que você implantaria via MDM ou `/etc/claude-code/managed-settings.json`, expresso aqui como YAML. O CLI aplica o documento entregue na camada gerenciada, acima das configurações de usuário e projeto.
431
432O gateway valida cada documento contra o esquema de configurações do CLI na inicialização, portanto uma chave de nível superior não reconhecida ou uma chave reconhecida com um valor malformado falha na inicialização com um erro nomeando cada chave ofensiva. Partes deliberadamente abertas do esquema ainda aceitam valores arbitrários, porque clientes mais novos podem reconhecer entradas que o esquema do gateway não reconhece. Essas chaves abertas são `env`, `pluginConfigs` e chaves aninhadas sob `permissions`.
433
434Como a validação usa o esquema agrupado com a versão instalada do gateway, colocar uma chave de configurações de nível superior introduzida por uma versão mais nova do Claude Code na configuração gerenciada requer atualizar o gateway primeiro. Teste uma nova política em um cliente antes de implantá-la.
435
436A referência de chave completa está em [Configurações do Claude Code](/pt/settings#available-settings). As chaves que os operadores mais procuram primeiro:
437
438```yaml theme={null}
439managed:
440 policies:
441 - match: {}
442 cli:
443 # Acesso ao modelo (também aplicado no servidor em /v1/messages)
444 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
445
446 # Política de permissão
447 permissions:
448 deny:
449 - "WebFetch"
450 - "Read(./.env)"
451 - "Read(./secrets/**)"
452 disableBypassPermissionsMode: disable # bloqueia --dangerously-skip-permissions
453 allowManagedPermissionRulesOnly: true # ignora regras de permissão de usuário/projeto
454
455 # Ambiente empurrado para o processo CLI. DISABLE_UPDATES bloqueia
456 # atualizações de fundo e manuais; DISABLE_AUTOUPDATER para apenas
457 # atualizações de fundo.
458 env:
459 DISABLE_UPDATES: "1" # fixe versões através de sua própria distribuição
460
461 # Hooks em toda a organização. Comandos de hook executam em máquinas de desenvolvedor, não no
462 # gateway, portanto o caminho deve existir em cada SO do cliente na política.
463 hooks:
464 PostToolUse:
465 - matcher: "Edit|Write"
466 hooks:
467 - { type: command, command: /usr/local/bin/audit-edit.sh }
468```
469
470| Chave | Aplicada por | Efeito |
471| ------------------------------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
472| `availableModels` | Gateway + CLI | Lista de permissão de modelo. Também verificada em `/v1/messages`, portanto um cliente corrigido não pode contorná-la. |
473| `permissions.allow` / `.deny` | CLI | Regras de ferramenta e comando. Consulte [Permissões](/pt/permissions). |
474| `permissions.disableBypassPermissionsMode` | CLI | Defina como `disable` para bloquear [`bypassPermissions`](/pt/permission-modes#skip-all-checks-with-bypasspermissions-mode), o modo que aprova automaticamente cada chamada de ferramenta, e a flag `--dangerously-skip-permissions` |
475| `allowManagedPermissionRulesOnly` | CLI | Quando `true`, regras de permissão de usuário e projeto são ignoradas; apenas regras deste documento se aplicam |
476| `env` | CLI | Variáveis de ambiente mescladas no processo CLI. Use para telemetria, atualização automática e substituições de nome de modelo. |
477| `hooks` | CLI | [Hooks](/pt/hooks) em toda a organização |
478
479Como essas configurações chegam pela rede, o CLI mostra a cada desenvolvedor um diálogo de aprovação de segurança única antes de aplicar qualquer coisa que possa executar um comando shell ou alterar para onde o tráfego vai. O diálogo cobre:
480
481* `hooks`
482* Variáveis `env` que não estão na lista segura integrada do CLI
483* Configurações de execução de shell como `apiKeyHelper` e `statusLine`
484* Conteúdo CLAUDE.md gerenciado
485
486A lista segura determina quais variáveis `env` se aplicam sem aprovação:
487
488* **Na lista segura**: variáveis de atualização automática e nome de modelo
489* **Não na lista segura**: variáveis de proxy, variáveis de URL base e `OTEL_EXPORTER_OTLP_ENDPOINT`
490
491A configuração de [telemetria](#telemetry) do gateway empurra `OTEL_EXPORTER_OTLP_ENDPOINT`, portanto definir `telemetry.forward_to` dispara o diálogo em cada cliente interativo. Execuções não interativas com a flag `-p` pulam o diálogo e aplicam configurações sem aprovação. O diálogo protege a máquina do desenvolvedor de um gateway comprometido ou hostil, não a organização do desenvolvedor, portanto o skip `-p` é intencional em vez de uma lacuna.
492
493Se um desenvolvedor recusar, Claude Code sai em vez de aplicar a política. Empurrar um novo hook ou variável env não segura para uma política ampla portanto significa um prompt de aprovação em cada inicialização do desenvolvedor correspondente.
494
495A chave `cli` foi nomeada `settings` em versões anteriores. Essa ortografia ainda é aceita como um alias, mas novas implantações devem usar `cli`.
496
497<h4 id="precedence-with-other-managed-sources">
498 Precedência com outras fontes gerenciadas
499</h4>
500
501Se um dispositivo também tiver um `managed-settings.json` local ou política entregue por MDM, as fontes gerenciadas não mesclam. A fonte de maior prioridade fornece todas as configurações de política, classificadas nesta ordem com maior prioridade primeiro:
502
5031. O [auxiliar de política](/pt/settings#compute-managed-settings-with-a-policy-helper)
5042. Configurações entregues pelo gateway
5053. MDM, via registro HKLM no Windows ou plist no macOS
5064. O arquivo `managed-settings.json`
5075. O registro HKCU, apenas no Windows
508
509Hosts de incorporação podem fornecer política através da opção SDK `managedSettings`. É ignorado por padrão e se aplica apenas quando uma fonte gerenciada opta por [`parentSettingsBehavior: "merge"`](/pt/settings#available-settings), filtrado para que possa apertar a política mas não afrouxá-la.
510
511A exceção é um pequeno conjunto de chaves entre fontes, honradas quando qualquer fonte de administrador as define; a camada HKCU gravável pelo usuário é excluída:
512
513* `sandbox.network.allowManagedDomainsOnly` e `sandbox.filesystem.allowManagedReadPathsOnly`: quando bloqueadas, as listas de permissão correspondentes são unidas entre fontes
514* [`allowAllClaudeAiMcps`](/pt/settings#available-settings): substituição de permissão apenas para a lista de permissão do servidor MCP claude.ai
515* `sandbox.bwrapPath` e `sandbox.socatPath`: caminhos do sistema de arquivos para os binários auxiliares [sandbox](/pt/sandboxing)
516
517`allowManagedPermissionRulesOnly` e `disableBypassPermissionsMode` não são entre fontes, portanto apenas o valor da fonte vencedora se aplica.
518
519As políticas do gateway se aplicam a cada invocação do Claude Code na máquina, incluindo execuções não interativas `claude -p` e sessões geradas pelo Agent SDK. Se o gateway estiver inacessível na inicialização, sessões assinadas saem com um erro em vez de executar sem sua política.
520
521<Warning>
522 `mcpServers` dentro de um bloco `cli` de política é rejeitado na inicialização do gateway. Distribuição de MCP por grupo não está disponível; implante servidores MCP via `managed-mcp.json` baseado em arquivo em cada dispositivo ou deixe desenvolvedores adicioná-los localmente.
523</Warning>
524
525<h3 id="telemetry">
526 `telemetry`
527</h3>
528
529O CLI envia métricas, logs e, quando habilitado, rastreamentos do OpenTelemetry Protocol (OTLP) sobre HTTP para o gateway, que os retransmite literalmente para cada destino configurado. Consulte [Monitoramento de uso](/pt/monitoring-usage) para as métricas e eventos que o CLI emite.
530
531O CLI carimba cada exportação com a identidade do usuário autenticado, lida do JWT emitido pelo gateway: os atributos `user.id`, `user.email` e `user.groups`. A atribuição de custo e uso por desenvolvedor portanto funciona sem nenhuma configuração do lado do desenvolvedor.
532
533```yaml theme={null}
534telemetry:
535 forward_to:
536 - url: https://otel-collector.internal.example.com
537 headers:
538 Authorization: ${OTLP_TOKEN}
539 # Opt-in por sinal. Padrão: apenas métricas.
540 metrics: true
541 logs: false
542 traces: false
543 - url: https://api.datadoghq.com/api/v2/otlp
544 headers:
545 DD-API-KEY: ${DD_API_KEY}
546```
547
548<Warning>
549 Cada destino opta por `metrics`, `logs` e `traces` independentemente, e o padrão é apenas métricas. Os sinais diferem em sensibilidade:
550
551 * **Métricas**: contadores agregados como contagens de token, contagens de solicitação e latência
552 * **Logs e rastreamentos**: podem carregar comandos bash completos, entradas de ferramenta e caminhos de arquivo, cobrindo qualquer coisa que Claude Code faz na máquina de um desenvolvedor
553
554 Habilite logs e rastreamentos apenas em destinos com os controles de acesso e política de retenção que os dados justificam.
555</Warning>
556
557A telemetria está desativada no CLI por padrão. Configurar `telemetry.forward_to` junto com `listen.public_url` a ativa. O gateway empurra cinco variáveis env para cada cliente conectado através de `/managed/settings`:
558
559* `CLAUDE_CODE_ENABLE_TELEMETRY=1`
560* `OTEL_METRICS_EXPORTER=otlp`
561* `OTEL_LOGS_EXPORTER=otlp`
562* `OTEL_TRACES_EXPORTER=otlp`
563* `OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>`
564
565O endpoint empurrado é construído a partir da URL pública, portanto métricas e logs não precisam de nenhuma configuração OTEL de desenvolvedores ou políticas. A configuração empurrada é aplicada na camada gerenciada, substituindo variáveis `OTEL_*` que um desenvolvedor define localmente.
566
567[Rastreamentos](/pt/monitoring-usage#traces-beta) adicionalmente requerem `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` em cada cliente. O gateway não empurra essa variável, portanto defina-a através do bloco `env` de uma política gerenciada. Não está na lista segura do CLI, portanto entregá-la através de uma política é coberta pelo mesmo [diálogo de aprovação de segurança](#managed) que o endpoint OTLP empurrado já dispara.
568
569Ambas as codificações OTLP protobuf e JSON são retransmitidas, e qualquer backend compatível com OpenTelemetry funciona como destino.
570
571<h3 id="http-tuning">
572 Ajuste HTTP
573</h3>
574
575Quatro blocos opcionais de nível superior, `access_control`, `limits`, `timeouts` e `rate_limits`, ajustam a superfície HTTP. Os padrões se adequam à maioria das implantações.
576
577| Bloco | Chave | Padrão | Descrição |
578| ---------------- | ---------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
579| `access_control` | `allow_cidrs` / `deny_cidrs` | vazio | Permitir/negar IP de entrada por endereço do cliente, após resolução `trusted_proxies`. `deny_cidrs` é verificado primeiro; um cliente que corresponde é rejeitado mesmo se `allow_cidrs` também corresponder. Se `allow_cidrs` não estiver vazio o gateway é padrão-negar. `/healthz` e `/readyz` estão isentos de `allow_cidrs`. |
580| `limits` | `max_request_bytes` | 32 MiB | Corpo de solicitação de entrada máximo; solicitações de tamanho excessivo obtêm `413` antes do corpo ser armazenado em buffer. Aumente para solicitações de arquivo ou imagem grandes. |
581| `limits` | `max_request_header_bytes` | não definido | Quando definido, cabeçalhos de tamanho excessivo retornam `431` |
582| `limits` | `max_url_length` | não definido | Quando definido, uma URL muito longa retorna `414` |
583| `timeouts` | `upstream_ttfb_ms` | 120000 | Espera máxima pelos cabeçalhos de resposta do upstream (tempo até o primeiro byte). O corpo da resposta então flui sem limite de relógio de parede. Aplica-se ao caminho upstream Anthropic direto; Bedrock, Agent Platform e Foundry são limitados pelo próprio timeout do SDK do provedor. |
584| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | Limite de taxa por IP no endpoint de autorização de dispositivo não autenticado. Aumente para uma grande organização atrás de um IP de saída compartilhado ou NAT. Esses limites se aplicam apenas ao fluxo de concessão de dispositivo de login, não a `/v1/messages` inferência. Consulte [Resistência de força bruta de código de usuário](/pt/claude-apps-gateway-deploy#user-code-brute-force-resistance). |
585| `rate_limits` | `device_verify.max` / `.window_seconds` | 10 / 600 | Limite de taxa por IP em envios `user_code` em `/device` |
586
587<h2 id="complete-example">
588 Exemplo completo
589</h2>
590
591Esta configuração de referência completa exercita cada seção principal; os blocos [ajuste HTTP](#http-tuning) mantêm seus padrões. Copie-a, delete o que você não precisa e preencha seus valores. A configuração no [Quickstart](/pt/claude-apps-gateway#quickstart) é uma versão mínima disso.
592
593```yaml gateway.yaml theme={null}
594# Execute com:
595# claude gateway --config gateway.yaml
596#
597# A verbosidade do log operacional é controlada pela variável de ambiente
598# CLAUDE_GATEWAY_LOG_LEVEL (info | warn | error; padrão info). Não afeta
599# eventos de auditoria, que são sempre emitidos.
600
601listen:
602 host: 0.0.0.0
603 port: 8080
604 public_url: https://claude-gateway.internal.example.com
605 # Omita o bloco tls ao executar atrás de um ingress que termina TLS.
606 # tls:
607 # cert: /certs/gateway.crt
608 # key: /certs/gateway.key
609 # trusted_proxies:
610 # - 10.0.0.0/8
611
612oidc:
613 issuer: https://example.okta.com
614 client_id: 0oa1example2
615 client_secret: ${OIDC_CLIENT_SECRET}
616 allowed_email_domains:
617 - example.com
618 # Obrigatório quando o emissor é o servidor org Okta, cujos id_tokens
619 # podem omitir email e grupos; o gateway os preenche de /userinfo.
620 userinfo_fallback: true
621 # allowed_groups: [claude-code-users]
622 # Okta emite grupos apenas quando o escopo `groups` é solicitado e o
623 # filtro de declaração de grupos do aplicativo os permite. A política de contratados abaixo
624 # corresponde em grupos, portanto o escopo é solicitado aqui.
625 scopes: [openid, profile, email, offline_access, groups]
626 # extra_auth_params: { access_type: offline, prompt: consent } # Google
627 # groups_claim: groups # Funções de aplicativo Entra: use `roles`
628 # email_claim: email
629
630session:
631 jwt_secret: ${GATEWAY_JWT_SECRET} # openssl rand -base64 32
632 # ttl_hours: 1
633
634store:
635 postgres_url: ${GATEWAY_POSTGRES_URL}
636 # max_connections: 5
637
638# Habilita /v1/organizations/spend_limits (espelha a API de Administração Anthropic)
639# e aplicação de gastos por desenvolvedor em /v1/messages. Omita para desabilitar.
640# Os limites em si são definidos via API de administração, não aqui.
641# admin:
642# write_keys:
643# - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
644# read_keys:
645# - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
646# admin_groups: [platform-finops]
647# blocked_message: request an increase at https://go.example.com/claude-limits
648# # audit_retention_days: 365
649# # spend_retention_months: 13
650# # identity_retention_days: 90
651# # group_limit_mode: min
652
653# enforcement:
654# fail_closed_on_error: false
655
656upstreams:
657 - provider: anthropic
658 auth:
659 api_key: ${ANTHROPIC_API_KEY}
660
661 # - provider: bedrock
662 # region: us-east-1
663 # auth: {}
664
665 # - provider: vertex
666 # region: us-east5
667 # project_id: example-prod
668 # auth: {}
669
670 # - provider: foundry
671 # resource: example-foundry
672 # auth: { use_azure_ad: true }
673
674auto_include_builtin_models: true
675models:
676 - id: claude-opus-4-8
677 label: Claude Opus 4.8
678 upstream_model:
679 anthropic: claude-opus-4-8
680 # bedrock: us.anthropic.claude-opus-4-8
681 # vertex: claude-opus-4-8
682 # foundry: <your-opus-deployment-name>
683 - id: claude-sonnet-4-6
684 label: Claude Sonnet 4.6
685 upstream_model:
686 anthropic: claude-sonnet-4-6
687 - id: claude-haiku-4-5
688 label: Claude Haiku 4.5
689 upstream_model:
690 anthropic: claude-haiku-4-5
691
692managed:
693 policies:
694 - match: { groups: [contractors] }
695 cli:
696 availableModels: [claude-haiku-4-5]
697 # Restrinja o seletor Padrão à opção availableModels em vez de
698 # o padrão de camada, portanto contratados não obtêm um 400 no padrão.
699 enforceAvailableModels: true
700 # allow aprova automaticamente essas ferramentas; não bloqueia o resto.
701 # Adicione regras deny para restringir ferramentas.
702 permissions: { allow: [Read, Grep] }
703 - match: {}
704 cli:
705 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
706 permissions:
707 allow: [Read, Grep, Bash, Edit]
708 deny: ["WebFetch"]
709 env: { HTTP_PROXY: http://proxy.example.com:8080 }
710
711telemetry:
712 forward_to:
713 - url: https://otel.internal.example.com:4318
714 headers:
715 Authorization: Bearer ${OTEL_TOKEN}
716```
717
718<h2 id="client-side-managed-settings">
719 Configurações gerenciadas do lado do cliente
720</h2>
721
722Tudo acima configura o servidor gateway. Apontar máquinas de desenvolvedor para ele é configurado separadamente, em cada dispositivo, através das [configurações gerenciadas](/pt/settings#settings-files) do Claude Code. O gateway não pode empurrar essas chaves em si, porque são o que dizem ao cliente onde o gateway está.
723
724Para o CLI, defina ambas as chaves no `managed-settings.json` por SO:
725
726```json theme={null}
727{
728 "forceLoginMethod": "gateway",
729 "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com"
730}
731```
732
733Implante esse arquivo em cada dispositivo, tipicamente via sua plataforma MDM. O caminho do arquivo difere por plataforma:
734
735| Plataforma | Caminho |
736| ----------- | ------------------------------------------------------------------------------------------------------------------------------------ |
737| macOS | `/Library/Application Support/ClaudeCode/managed-settings.json`, ou o domínio de preferências gerenciadas `com.anthropic.claudecode` |
738| Linux e WSL | `/etc/claude-code/managed-settings.json` |
739| Windows | `C:\Program Files\ClaudeCode\managed-settings.json`, ou Group Policy via registro HKLM |
740
741`forceLoginGatewayUrl` e o valor `"gateway"` de `forceLoginMethod` são honrados apenas da camada gerenciada controlada pelo administrador. Um desenvolvedor definindo-os em seu próprio `~/.claude/settings.json` não tem efeito.
742
743<h2 id="related">
744 Relacionado
745</h2>
746
747* [Visão geral do gateway de aplicativos Claude](/pt/claude-apps-gateway): quickstart e conexão de desenvolvedor
748* [Guia de implantação](/pt/claude-apps-gateway-deploy): configuração de IdP, imagem de contêiner, Kubernetes e Cloud Run e operações
749* [Limites de gastos](/pt/claude-apps-gateway-spend-limits): limites por desenvolvedor e a API de Administração
