Configuração do gateway de aplicativos Claude

Referência para cada opção de gateway.yaml: listener e TLS, OIDC, sessão, armazenamento Postgres, Amazon Bedrock, Claude Platform on AWS, Agent Platform do Google Cloud e upstreams Microsoft Foundry, roteamento de modelos, políticas gerenciadas e telemetria.

Uma 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, 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 cobre a containerização e hospedagem no Kubernetes, Cloud Run ou sua própria plataforma.

O 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.

O exemplo completo no final desta página exercita cada seção.

Estrutura do arquivo

Cinco seções são obrigatórias. Todas as outras seções são opcionais, 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.

Seções obrigatórias:

• listen: endereço de vinculação, URL pública, terminação TLS
• oidc: seu provedor de identidade (IdP), incluindo emissor, cliente, mapeamento de declarações e quem pode fazer login
• session: os tokens de portador que o gateway emite, com segredo e tempo de vida
• store: PostgreSQL, para concessões de dispositivo e contadores de limite de taxa
• upstreams: para onde a inferência vai, seja Anthropic, Amazon Bedrock, Claude Platform na AWS, Agent Platform do Google Cloud ou Microsoft Foundry

Seções opcionais:

• admin: autenticação da API de administração e retenção para limites de gastos
• enforcement: comportamento de falha aberta ou fechada do limite de gastos
• pricing: taxas contratadas e um multiplicador para o medidor de gastos e para os valores de custo que os desenvolvedores veem
• models e auto_include_builtin_models: lista de modelos curada pelo administrador e IDs por upstream
• managed: políticas de configurações gerenciadas por grupo IdP
• telemetry: encaminhamento OTLP para sua pilha de observabilidade
• access_control, limits, timeouts, rate_limits: permitir/negar IP, limites de tamanho de solicitação, tempo até o primeiro byte upstream e limites de login por IP
• load_test_mode: teste de carga do gateway sem chamar um provedor de modelo

Expansão de segredos

Nã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:

Seções obrigatórias

listen

O 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.

oidc

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.

OpenID Connect (OIDC) é o protocolo SSO que o gateway usa com seu provedor de identidade; consulte Configuração do provedor de identidade para saber o que registrar no lado do IdP.

Autenticação de cliente por certificado

Se 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.

Com 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.

1. Crie a chave e o certificado

Crie 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:

openssl req -x509 -newkey rsa:2048 -nodes -keyout idp-client.key -out idp-client.crt -days 365 -subj "/CN=claude-gateway"

Ele 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/.

2. Envie o certificado para o IdP

Envie o certificado, não a chave privada, para o registro de aplicativo do gateway no IdP.

3. Adicione a chave e o certificado ao gateway.yaml

Forneç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:

oidc:
  issuer: https://login.microsoftonline.com/<tenant-id>/v2.0
  client_id: <application-id>
  token_endpoint_auth_method: private_key_jwt
  client_assertion:
    private_key_pem: ${file:/etc/gateway/idp-client.key}
    certificate_pem: ${file:/etc/gateway/idp-client.crt}

Ambos 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.

4. Reinicie o gateway e verifique o log de inicialização

Reinicie o gateway e encontre esta linha no log de inicialização:

[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

Compare 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.

Rotacionar o certificado do cliente

O 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:

1. Envie o novo certificado para o IdP junto com o antigo.
2. 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 funciona, porque o IdP tem ambos os certificados até que você remova o antigo.
3. Depois que todas as réplicas tiverem reiniciado, remova o certificado antigo do IdP.

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

Os 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.

Com 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 se aplicam no caminho proxied também.

Egresso apenas proxy 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.

Egresso apenas proxy

Defina 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.

export HTTPS_PROXY=http://proxy.corp.example.com:3128
export NO_PROXY=
export no_proxy=
export CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1

O gateway registra uma linha network: na inicialização enquanto o egresso apenas proxy está ativo.

Cada 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.

O egresso apenas proxy permanece desativado a menos que o ambiente do gateway atenda a todas as três dessas condições:

• HTTPS_PROXY ou HTTP_PROXY está definido.
• 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.
• 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.

Quando 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.

Uma 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.

[!WARNING]

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 do gateway para essas solicitações.

session

O 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.

store

O bloco store aponta o gateway para seu banco de dados PostgreSQL, que contém concessões de dispositivo e contadores de rate limit.

Para 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.

upstreams

upstreams é uma lista ordenada. O gateway encaminha inferência para o primeiro upstream que resolve o modelo solicitado.

Em 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.

Se 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.

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.

Múltiplos upstreams do mesmo provedor devem definir um name: distinto.

Clientes 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.

Mensagens de erro do upstream

O gateway retorna a resposta de erro de um upstream ou seu próprio 502, dependendo de como os upstreams responderam:

• Um upstream retornou um status no qual o gateway não falha: essa resposta do upstream. O gateway não tenta mais upstreams.
• Cada upstream que o gateway tentou falhou de uma forma na qual falha: 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, incluindo entradas que o gateway pulou porque não servem o modelo solicitado.

Quando 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.

Os 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. O que o desenvolvedor vê desses upstreams depende da rejeição:

• 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.
• 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.
• Qualquer outro status: cópia genérica por status, como upstream rate limit exceeded em um 429.

Por exemplo, o gateway substitui Input is too long for requested model. do Amazon Bedrock por capability_rejected: prompt_too_long. Claude Code compacta automaticamente nesse token, como faz em prompt is too long.

Manter 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.

Anthropic API

O upstream Anthropic mínimo é uma chave de API do Claude Console:

upstreams:
  - provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}
    # OU um portador OAuth (por exemplo, um token trocado por Workload-Identity-Federation):
    #   oauth_token: ${file:/var/run/secrets/anthropic-oauth-token}
    # base_url: https://api.anthropic.com   # padrão; substitua por um proxy de encaminhamento

As duas formas de credencial diferem no cabeçalho que enviam:

• api_key: envia x-api-key. Gire-a no Claude Console e atualize a variável env.
• 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.

Em 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, 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.

upstreams:
  - provider: anthropic
    auth:
      federation_rule_id: ${ANTHROPIC_FEDERATION_RULE_ID}
      organization_id: ${ANTHROPIC_ORGANIZATION_ID}
      identity_token_file: /var/run/secrets/anthropic/id-token
      # workspace_id: wrkspc_...       # obrigatório se a regra cobre >1 workspace
      # service_account_id: svac_...   # verificação de alvo esperado opcional

Cabeçalhos de identidade por usuário para um proxy que você executa

Você 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.

Por exemplo, para um proxy em upstream-gateway.internal.example.com:

upstreams:
  - provider: anthropic
    base_url: https://upstream-gateway.internal.example.com
    auth:
      api_key: ${PROXY_KEY}
    forward_user_identity: true        # padrão false

O gateway adiciona esses cabeçalhos a cada solicitação que encaminha para esse upstream.

Quando 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 para essa declaração.

Seu proxy não recebe os cabeçalhos x-claude-code-* 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.

Quando 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 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.

Defina 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.

[!NOTE]

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. Para identificar cada desenvolvedor para a AWS em vez disso, consulte Atribuição de custos AWS por desenvolvedor.

Amazon Bedrock

Para a implantação Amazon Bedrock do lado do cliente que o gateway substitui ou está na frente, consulte Claude Code on Amazon Bedrock. O upstream do lado do gateway:

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}                           # preferido: cadeia de credencial padrão AWS
    # OU credenciais explícitas:
    # auth:
    #   aws_access_key_id: ${AWS_AKID}
    #   aws_secret_access_key: ${AWS_SK}
    #   aws_session_token: ${AWS_ST}
    # OU um token de portador da API Bedrock:
    # auth:
    #   aws_bearer_token: ${AWS_BEARER_TOKEN}
    # Substitua o endpoint bedrock-runtime para implantações FIPS ou VPC-endpoint:
    # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com

Um 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.

Credenciais 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.

Aplicar um guardrail do Amazon Bedrock

Para 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.

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}
    guardrail:
      id: gr-abc123                    # ID do guardrail ou ARN completo
      version: "1"                     # um número de versão publicado, ou DRAFT
 # mantenha as aspas: um 1 sem aspas falha na inicialização

[!WARNING]

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 na documentação do Amazon Bedrock.

Também conceda bedrock:ApplyGuardrail no guardrail ao principal que assina as requisições desse upstream: o principal AWS do gateway ou, com assume_role, a função nomeada em role_arn.

Defina guardrail em todos os upstreams bedrock ou em nenhum. O gateway se recusa a iniciar com uma mistura, porque o failover poderia, de outra forma, enviar uma requisição a um upstream Bedrock que não tem guardrail.

O 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.

Quando 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.

Bedrock em outra conta AWS

Defina 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.

Requer um gateway executando Claude Code v2.1.281 ou posterior. Um gateway anterior se recusa a iniciar quando encontra a chave.

upstreams:
  - name: bedrock-isolated
    provider: bedrock
    region: us-east-1
    auth: {}                           # a própria função do gateway: ela apenas chama o STS
    assume_role:
      role_arn: arn:aws:iam::222222222222:role/claude-gateway-bedrock
      # external_id: ${BEDROCK_ROLE_EXTERNAL_ID}   # quando a política de confiança da função exige um

O bloco assume_role aceita três chaves:

A 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.

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "AWS": "arn:aws:iam::111111111111:role/claude-gateway" },
    "Action": "sts:AssumeRole",
    "Condition": { "StringEquals": { "sts:ExternalId": "your-external-id" } }
  }]
}

• 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 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.
• 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.
• 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.
• Cada desenvolvedor que o gateway admite pode usar esse upstream; 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, 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.

Este exemplo dá a um modelo um id personalizado que apenas o upstream isolado serve:

models:
  - id: restricted-claude-opus-4-8      # um id personalizado, não um nome de modelo integrado
    upstream_model:
      bedrock-isolated: us.anthropic.claude-opus-4-8   # o único upstream que o serve

Atribuição de custos AWS por desenvolvedor

Por 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 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.

Requer um gateway executando Claude Code v2.1.281 ou posterior. Atribuição de custos na AWS descreve a função IAM e onde o faturamento da AWS mostra as sessões.

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}                           # a própria função do gateway: ela apenas chama o STS
    assume_role:
      role_arn: arn:aws:iam::123456789012:role/claude-gateway-bedrock-user
      session_name: email              # ou sub

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.

Um desenvolvedor ativo custa uma chamada STS por hora por réplica do gateway, e primeiras requisições concorrentes compartilham uma chamada.

O 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 permaneçam precisos. Essa contagem e sua requisição de fallback de um token 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.

Para 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.

Endpoint Mantle do Amazon Bedrock

O provedor mantle envia inferência para o endpoint Mantle 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.

O 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:

upstreams:
  - provider: mantle
    region: us-east-1
    models: [claude-opus-4-7, claude-haiku-4-5]   # obrigatório
    auth: {}                           # cadeia de credencial padrão AWS
  - provider: bedrock
    region: us-east-1
    auth: {}

A tabela abaixo lista os campos específicos de um upstream mantle.

Conceda à identidade AWS do upstream as ações IAM próprias do Mantle para inferência e contagem de tokens, que Usar o endpoint Mantle lista.

Para um ID de modelo do Mantle que o gateway não conhece, adicione uma entrada ao bloco 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.

As configurações guardrail e assume_role de um upstream bedrock não se estendem às requisições que o Mantle serve:

• guardrail: o gateway não aplica nenhum guardrail do Bedrock à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.
• assume_role: um upstream mantle não aceita assume_role. 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.

Para saber o que significam as respostas de erro próprias do Mantle, consulte Erros do endpoint Mantle.

Claude Platform on AWS

Claude 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.

Para a implantação do lado do cliente da mesma plataforma, consulte Claude Code on Claude Platform on AWS. O upstream do lado do gateway:

upstreams:
  - provider: anthropicAws
    region: us-east-1
    workspace_id: wrkspc_...
    auth:
      api_key: ${ANTHROPIC_AWS_API_KEY}   # enviado como x-api-key
    # OU SigV4 através da cadeia de credencial padrão AWS:
    # auth: {}
    # OU credenciais SigV4 explícitas:
    # auth:
    #   aws_access_key_id: ${AWS_ACCESS_KEY_ID}
    #   aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}
    # Substitua o endpoint derivado:
    # base_url: https://aws-external-anthropic.us-east-1.api.aws

A 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 usa.

Como a plataforma resolve IDs de modelo de primeira parte, o catálogo integrado roteia para ela sem um bloco models:. Quando você cura uma lista models:, chave a entrada anthropicAws: com o ID de primeira parte.

Google Cloud Agent Platform

Para a configuração equivalente do lado do cliente, consulte Claude Code on Google Cloud. O upstream do lado do gateway:

upstreams:
  - provider: vertex
    region: us-east5
    project_id: example-prod
    auth: {}                           # preferido: Credenciais Padrão de Aplicativo
    # OU um arquivo de chave de conta de serviço:
    # auth: { service_account_json: /secrets/sa.json }
    # Substitua o endpoint aiplatform para Private Service Connect:
    # base_url: https://us-east5-aiplatform.p.googleapis.com

Um 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.

Defina region: global para usar o endpoint global do Agent Platform do Google Cloud 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.

Microsoft Foundry

Para a implantação Microsoft Foundry do lado do cliente, consulte Claude Code on Microsoft Foundry. O upstream do lado do gateway:

upstreams:
  - provider: foundry
    resource: example-foundry              # https://example-foundry.services.ai.azure.com
    auth: { use_azure_ad: true }        # preferido: DefaultAzureCredential / Managed Identity
    # OU uma chave de API:
    # auth:
    #   api_key: ${FOUNDRY_API_KEY}

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.

Cabeçalhos estáticos em solicitações de upstream

Para 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.

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.

Os 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.

Este 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:

upstreams:
  - provider: vertex
    region: us-east5
    project_id: example-prod
    base_url: https://upstream-proxy.internal.example.com
    auth: {}
    headers:
      x-source: claude-apps-gateway
      x-proxy-token: ${PROXY_TOKEN}

Os 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.

Para manter um segredo fora do arquivo de configuração, use expansão de segredo 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.

headers: funciona em cada provedor, e cada upstream envia apenas o seu.

Nem toda solicitação que o gateway envia para um upstream carrega eles:

Em 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.

Se 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:

• authorization e x-api-key
• host, content-type e user-agent
• Qualquer nome começando com anthropic-, x-goog-, x-amz- ou x-amzn-

Múltiplos upstreams

O 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.

O gateway tenta upstreams em ordem. 5xx, 429, 401, 403, 404, timeouts e endpoint ausente (501) falham; outro 4xx não.

429 é capacidade por upstream, portanto esgotamento de throughput provisionado (PT) falha para sob demanda. Se você definir forward_user_identity: true 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.

Cada 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.

O 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.

O gateway aguarda este tempo para que uma resposta comece:

• Upstreams provider: anthropic: timeouts.upstream_ttfb_ms, 120 segundos por padrão
• 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 forma

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.

Este 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:

upstreams:
  # Primário: throughput provisionado em sua região inicial.
  - name: bedrock-pt
    provider: bedrock
    region: us-east-1
    auth: {}
  # Transbordamento: sob demanda entre regiões.
  - name: bedrock-od
    provider: bedrock
    region: us-west-2
    auth: {}
  # Conta diferente: uma alocação Bedrock separada através de chaves estáticas.
  - name: bedrock-acct2
    provider: bedrock
    region: us-east-1
    auth:
      aws_access_key_id: ${ACCT2_AKID}
      aws_secret_access_key: ${ACCT2_SK}
  # Último recurso: API Anthropic direta.
  - name: anthropic-fallback
    provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}

# IDs de modelo por upstream são codificados no `name:` do upstream.
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    upstream_model:
      bedrock-pt: arn:aws:bedrock:us-east-1:111111111111:provisioned-model/abcdef
      bedrock-od: us.anthropic.claude-opus-4-8
      bedrock-acct2: us.anthropic.claude-opus-4-8
      anthropic-fallback: claude-opus-4-8

Falhar entre provedores de nuvem ou para a API Anthropic direta muda qual acordo, geografia e outros termos governam a solicitação.

O 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 em uma política, ele vai para cada upstream da lista, portanto defina-o apenas se todos eles o aceitarem.

Seções opcionais

admin

Opcional. Habilita /v1/organizations/spend_limits, que espelha a Admin API pública da Anthropic, e a aplicação de limites de gastos por desenvolvedor em /v1/messages. Consulte Limites de gastos para saber como os limites são definidos e aplicados; esta seção aborda as chaves do gateway.yaml que ativam o recurso e o ajustam.

admin:
  # Named static API keys for the admin endpoints, sent as x-api-key.
  # The id appears in the audit log as admin-key:<id> so each key is
  # attributable. Array for rotation: add the new key, roll clients,
  # remove the old.
  write_keys:
    - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
    - { id: ci,        key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }
  read_keys:
    - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
  # IdP groups granted full admin via the normal gateway JWT (no API key).
  admin_groups: [platform-finops]
  blocked_message: request an increase at https://go.example.com/claude-limits

enforcement

O bloco enforcement controla como as verificações de limites de gastos se comportam quando o armazenamento não está disponível.

pricing

O bloco pricing informa ao medidor de gastos o que cobrar em vez do preço de tabela em USD, para que os limites e /effective reflitam suas tarifas contratadas. Os valores permanecem em USD e continuam sendo uma estimativa, não uma fatura. Dois pré-requisitos:

• Claude Code v2.1.227 ou posterior no servidor do gateway. Versões anteriores rejeitam a chave desconhecida na inicialização.
• Um bloco admin: ou, na v2.1.268 ou posterior, um bloco managed: com pelo menos uma política. O gateway se recusa a iniciar com pricing definido e nenhum dos dois blocos, porque nada o leria.

pricing:
  multiplier: 0.85
  overrides:
    - upstream: bedrock-eu
      model: claude-sonnet-4-6
      input: 3.30
      output: 16.50
      cache_read: 0.33
      cache_write: 4.125

Como o medidor corresponde a uma linha de override:

• Uma linha substitui o preço de tabela para requisições que upstream, um upstreams[].name, atende para model. Isso inclui a tarifa mais alta do modo rápido, de modo que requisições rápidas e padrão são medidas com as mesmas quatro tarifas.
• Um ID integrado como claude-sonnet-4-6, correspondido como models[].id, cobre toda forma datada, forma regional do Amazon Bedrock ou forma do Agent Platform do Google Cloud que o medidor precifica como esse modelo. Qualquer outra string, como um alias ou um ARN de perfil de inferência, corresponde ao ID que o cliente enviou ou à string enviada ao upstream, sem diferenciar maiúsculas de minúsculas.
• Onde as linhas se sobrepõem, o medidor escolhe a linha mais específica, e não a primeira: uma linha cujo model é a string exata do modelo enviada ao upstream, depois uma linha que corresponde ao ID exato que o cliente enviou e, em seguida, uma linha que nomeia o modelo integrado.
• Um nome de upstream desconhecido faz a inicialização falhar, assim como duas linhas para um mesmo upstream que nomeiam o mesmo modelo, incluindo duas grafias de um mesmo modelo integrado. O gateway emite um aviso na inicialização sobre uma linha que nenhum modelo solicitável pode usar.
• Requisições de pesquisa na web permanecem no preço de tabela de $0.01; o multiplicador ainda se aplica a elas.

Para tarifas por região, dê a cada região seu próprio upstream nomeado e uma linha por upstream.

Aplicar acréscimo aos preços

Com a v2.1.271 ou posterior no servidor do gateway, você pode definir multiplier acima de 1, até 10, para medir mais do que o provedor cobra, por exemplo, uma tarifa interna de chargeback. Este exemplo mede cada requisição a 120% do preço:

pricing:
  multiplier: 1.2

Com um bloco admin:, o acréscimo também se aplica aos limites de gastos. O medidor conta 120% do preço, então os desenvolvedores atingem seus limites mais cedo. O gateway registra um aviso na inicialização informando isso.

O multiplicador não altera o que o provedor upstream cobra pelas requisições.

Se o gateway também enviar as tarifas para clientes conectados, os desenvolvedores precisam do Claude Code v2.1.271 ou posterior para ver o acréscimo. Clientes anteriores ignoram um multiplier acima de 1 e mostram os custos sem ele.

Um servidor do gateway anterior à v2.1.271 se recusa a iniciar se você definir um multiplier acima de 1.

Enviar as tarifas para clientes conectados

Com a v2.1.268 ou posterior no servidor do gateway, o gateway também coloca as tarifas de pricing nas políticas managed que serve, como a configuração gerenciada 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.

• 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.
• Excluir uma política: defina modelPricing como {} no bloco cli dessa política, e seus desenvolvedores permanecem no preço de tabela.
• 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.

models

O bloco models é uma lista opcional de modelos selecionada pelo administrador, servida em /v1/models e usada para traduzir IDs de modelo por upstream. Ele é obrigatório para regiões do Amazon Bedrock fora dos EUA, ARNs de throughput provisionado do Amazon Bedrock e nomes de implantação do Microsoft Foundry.

auto_include_builtin_models: true   # false: expose only the list below
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    # description: optional text shown in clients that surface it
    upstream_model:
      anthropic: claude-opus-4-8
      bedrock: us.anthropic.claude-opus-4-8   # or an inference-profile ARN
      foundry: your-opus-deployment-name

Cada chave em upstream_model deve corresponder ao name de um upstream configurado, que por padrão é o nome do provedor. Uma chave que não corresponde a nenhum upstream faz a inicialização falhar, então omita as linhas dos provedores que você não usa.

managed

O 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.

managed:
  policies:
    # Specific groups first.
    - match: { groups: [eng-contractors] }
      cli:
        availableModels: [claude-sonnet-4-6]
        permissions: { deny: ["WebFetch", "WebSearch"] }
    # Default catch-all last: matches everyone who authenticated.
    - match: {}
      cli:
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
        # Make the Default option in /model resolve inside each policy's
        # list. The eng-contractors policy inherits enforceAvailableModels.
        enforceAvailableModels: true

Um catch-all match: {}, por convenção listado por último, é tratado como uma camada base. Todas as outras políticas herdam do catch-all qualquer chave que não definam, então as entradas por função só precisam listar o que difere do padrão da organização. As regras de mesclagem dependem do tipo de chave:

• Allowlists: availableModels e permissions.allow. A lista de uma política específica substitui totalmente a da base.
• Listas de negação e arrays de hooks: permissions.deny, permissions.ask, disabledMcpjsonServers, deniedMcpServers, blockedMarketplaces, deniedModels e todos os arrays de tipo de evento de hooks. Estes usam a união da base e da política, para que uma negação ou um hook de auditoria de toda a organização não possa ser removido acidentalmente por uma sobrescrita por função.
• Chaves do tipo registro: env, modelOverrides e skillOverrides. Estas são mescladas superficialmente, então um bloco env por função sobrescreve as chaves que define e herda o restante da base.

availableModels também é aplicado no lado do servidor em /v1/messages, então um modelo negado retorna 400 independentemente do que o cliente envia. Uma lista vazia nega todos os modelos. A verificação também cobre o modelo com que uma sessão inicia antes de o desenvolvedor escolher um, então inicie as sessões em um modelo que a política permite.

O próprio gateway valida o valor de model antes de repassar uma requisição, para que um valor malformado nunca chegue a um upstream. Ele rejeita a requisição com um 400 em dois casos:

• Quando o valor está ausente ou vazio, o gateway rejeita a requisição com a mensagem model is required. Essa verificação requer um gateway executando o Claude Code v2.1.228 ou posterior.
• Quando o valor está presente, mas não é uma string, o gateway rejeita a requisição com a mensagem model must be a string. Requer um gateway executando o Claude Code v2.1.221 ou posterior.

Um 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.

[!NOTE]

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.

Execute o gerenciamento do ciclo de vida de usuários e grupos na fonte da verdade, que é o provisionamento SCIM nativo do seu IdP ou uma plataforma dedicada de governança de identidade. A associação e o desprovisionamento governados ali chegam ao gateway automaticamente por meio do token. Se você quiser provisionamento SCIM das próprias contas do Claude, esse é um recurso do Claude for Enterprise.

Dois relógios de propagação se aplicam:

• Conteúdo das políticas: editar uma política e reimplantar chega aos clientes Claude Code conectados na próxima consulta de configurações gerenciadas, em até uma hora, exceto pelas alterações que se aplicam apenas na próxima inicialização
• Associação a grupos: alterar a associação de um usuário a grupos muda qual política corresponde a ele. Isso entra em vigor na próxima reemissão da sessão, ou seja, na próxima atualização silenciosa, limitada por session.ttl_hours.

O Claude Desktop segue seu próprio cronograma.

Iniciar sessões em um modelo que a política permite

Se 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.

Para corrigir isso, defina enforceAvailableModels: true no mesmo bloco cli e, em seguida, verifique que tipo de entrada a lista tem:

• Um alias como sonnet, ou um ID integrado como claude-sonnet-4-6: as sessões iniciam em um desses modelos, e a opção Default em /model é resolvida para ele
• Nenhum alias ou ID integrado na lista: as sessões podem continuar iniciando no padrão integrado, então defina também model como um dos IDs listados no bloco cli dessa política

Esta política lista um ID personalizado que models define e inicia as sessões nesse ID:

managed:
  policies:
    - match: { groups: [restricted-projects] }
      cli:
        availableModels: [restricted-claude-opus-4-8]
        enforceAvailableModels: true
        model: restricted-claude-opus-4-8
        env:
          ANTHROPIC_DEFAULT_OPUS_MODEL: restricted-claude-opus-4-8   # opus and Default resolve to the ID too

Valores de matcher que interrompem o gateway na inicialização

Na inicialização, o gateway verifica o bloco match de todas as políticas e a lista admin_groups. Qualquer um destes valores interrompe o gateway com um erro que nomeia o campo:

• Uma lista groups vazia
• Uma entrada vazia em groups ou em admin_groups
• Um email_domain vazio
• Um email_domain que contém @, espaço em branco ou vírgula. O gateway apara o valor e remove um @ inicial antes desta verificação. Escreva um único domínio simples, como example.com.

Antes da v2.1.232, o gateway iniciava com esses valores. Cada valor tinha este efeito:

• Um email_domain vazio: o gateway ignorava a verificação de domínio, então uma política com um email_domain vazio e sem lista groups correspondia a todos os usuários autenticados
• Uma lista groups vazia: a política não correspondia a ninguém
• Um email_domain contendo @, espaço em branco ou vírgula: a política não correspondia a ninguém
• Uma entrada vazia em groups ou em admin_groups: a entrada correspondia a um usuário somente quando a claim groups do IdP desse usuário também continha uma entrada vazia. Em admin_groups, essa correspondência concedia acesso de administrador. Se sua lista admin_groups nunca conteve uma entrada vazia, ninguém obteve acesso de administrador dessa forma.

Escolher cli ou code

[!WARNING]

Quando uma política usa a chave code, cada um destes impede o gateway de iniciar:

• Versão do gateway: code requer o Claude Code v2.1.296 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 troque code de volta para cli antes de reverter para uma versão anterior.
• Chaves misturadas: um arquivo que tenha tanto code quanto cli, ou sua grafia anterior settings, interrompe o gateway na inicialização. Coloque todos os blocos sob uma única chave, em uma única edição.

As configurações do Claude Code de uma política, como uma regra que nega a leitura de arquivos .env, ficam em um bloco sob a chave cli ou code. code é a chave recomendada, e cli é a chave legada. Ambas as chaves aceitam o mesmo conteúdo. A chave decide onde as configurações são aplicadas:

• cli: o terminal, as extensões do VS Code e do JetBrains e o Agent SDK. Sob cli, a aba Code do Claude Desktop recebe as configurações derivadas, então uma regra com escopo como Read(./.env) não impede um usuário ali.
• code: os mesmos lugares, e a aba Code do Claude Desktop também pode ser coberta.

Um arquivo que usa cli funciona como antes, e um gateway que encontra cli em uma política com uma chave desktop emite um aviso na inicialização e inicia mesmo assim. Mude para code para que as configurações também possam cobrir a aba Code.

Antes de mudar, leia Aplicar configurações code na aba Code. A política precisa de uma chave desktop e as máquinas dos usuários precisam de configuração antes que as configurações se apliquem ali, e a pesquisa na web é desativada no Claude Desktop.

Esta política coloca a regra de negação sob code, com uma chave desktop vazia:

managed:
  policies:
    - match: {}
      code:
        permissions: { deny: ["Read(./.env)"] }
      desktop: {}

Ao mudar, exclua qualquer linha serve_to_desktop na mesma edição que renomeia os blocos. Onde uma instrução mencionar o bloco cli, use seu bloco code.

serve_to_desktop: true é uma forma legada de oferecer as configurações cli de uma política à guia Code. Não tem efeito quando o Claude Desktop se conecta por meio de bootstrapUrl. Enquanto suas políticas usarem cli, um aviso de inicialização que nomeia essa chave significa que essas configurações não estão chegando à guia Code:

• Para cobrir a guia Code: mude para code, assim que as máquinas dos usuários atenderem às condições em Aplicar configurações de code na guia Code
• Para permanecer em cli: defina serve_to_desktop: false ao lado de cli em uma política para silenciar o aviso

O que vai em cli

Cada valor de code ou 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. A CLI aplica o documento entregue no nível gerenciado, acima das configurações de usuário e de projeto, no lugar das configurações gerenciadas pelo servidor. Portanto, ela ignora as configurações restritas a fontes de política no nível do sistema operacional, como policyHelper e wslInheritsWindowsSettings.

O gateway valida cada documento em relação ao esquema de configurações da CLI na inicialização, então uma chave de nível superior não reconhecida faz a inicialização falhar com um erro que nomeia cada chave problemática. 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 incluem env, pluginConfigs e chaves aninhadas em permissions.

Como a validação usa o esquema empacotado com a versão instalada do gateway, colocar na configuração gerenciada uma chave de configuração de nível superior introduzida por uma versão mais nova do Claude Code exige atualizar o gateway primeiro. Faça um teste rápido de uma nova política em um cliente antes de distribuí-la.

A referência completa de chaves está em Configurações do Claude Code. As chaves que a maioria dos operadores usa primeiro:

managed:
  policies:
    - match: {}
      cli:
        # Model access (also enforced server-side at /v1/messages)
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
        enforceAvailableModels: true              # Default resolves inside the list

        # Permission policy
        permissions:
          deny:
            - "WebFetch"
            - "Read(./.env)"
            - "Read(./secrets/**)"
          disableBypassPermissionsMode: disable   # blocks --dangerously-skip-permissions
        allowManagedPermissionRulesOnly: true     # ignore user/project permission rules

        # Environment pushed into the CLI process. DISABLE_UPDATES blocks
        # background and manual updates; DISABLE_AUTOUPDATER stops only
        # background updates.
        env:
          DISABLE_UPDATES: "1"                    # pin versions via your own distribution

        # Org-wide hooks. Hook commands run on developer machines, not the
        # gateway, so the path must exist on every client OS in the policy.
        hooks:
          PostToolUse:
            - matcher: "Edit|Write"
              hooks:
                - { type: command, command: /usr/local/bin/audit-edit.sh }

Como essas configurações chegam pela rede, a CLI mostra a cada desenvolvedor uma caixa de diálogo de aprovação de segurança antes de aplicar as configurações listadas abaixo:

• hooks
• variáveis de env que exigem a aprovação do desenvolvedor, como variáveis de proxy e de URL base
• configurações de execução de shell, como apiKeyHelper e statusLine
• as configurações de binários do sandbox sandbox.bwrapPath, sandbox.socatPath e sandbox.ripgrep
• Configurações do sandbox que interceptam tráfego, injetam credenciais ou enfraquecem o isolamento, como sandbox.network.tlsTerminate e as configurações de porta do proxy. Caixas de diálogo de aprovação de segurança lista todas elas.

Memória de aprovação explica quanto tempo uma aprovação dura e quando a caixa de diálogo aparece novamente.

O Claude Code aplica algumas variáveis env entregues sem mostrar ao desenvolvedor a caixa de diálogo de aprovação, como configurações de seleção de modelo e limites numéricos. Outras variáveis entregues podem exigir a aprovação do desenvolvedor; um valor não vazio de proxy, URL base ou OTEL_EXPORTER_OTLP_ENDPOINT sempre exige. Quando uma variável entregue precisa de aprovação, a caixa de diálogo a nomeia. Variáveis de ambiente e a caixa de diálogo de aprovação tem os detalhes, incluindo quatro opções de privacidade cujo valor entregue decide se precisam de aprovação.

A configuração de telemetria do gateway envia OTEL_EXPORTER_OTLP_ENDPOINT, então definir telemetry.forward_to aciona a caixa de diálogo em cada cliente interativo. A caixa de diálogo protege a máquina do desenvolvedor contra um gateway comprometido ou hostil, não a organização contra o desenvolvedor.

Uma execução não interativa, como claude -p, uma sessão do Agent SDK ou uma sessão na aba Code do Claude Desktop, não pode mostrar a caixa de diálogo. Ela aplica as configurações enviadas somente para essa execução e não as registra como aprovadas, então a próxima sessão interativa do desenvolvedor ainda mostra a caixa de diálogo.

Se um desenvolvedor recusar, o Claude Code encerra essa sessão em vez de aplicar a política. Quando você envia um novo hook, ou qualquer variável de ambiente que aciona a caixa de diálogo, para uma política ampla, todos os desenvolvedores correspondentes veem, portanto, a caixa de diálogo em suas sessões interativas. Uma sessão interativa em execução a mostra na próxima consulta horária; caso contrário, ela aparece na próxima inicialização interativa do desenvolvedor.

A chave cli se chamava settings em versões anteriores, e o gateway ainda aceita essa grafia como alias. Para novas implantações, use code.

Testar uma política antes da implantação

Para testar uma alteração de política, inicie o gateway com um banco de dados Postgres descartável. O gateway se conecta ao Postgres e aplica suas migrações de esquema antes de verificar o conteúdo dos blocos cli, code e desktop. Quando não consegue acessar o banco de dados, a inicialização para em could not connect to Postgres e não informa nada sobre o conteúdo deles.

Janela de contexto em sessões de terminal

Sessões de terminal conectadas por meio de /login usam a janela de contexto de 1M para Opus 4.7 e posteriores, Sonnet 5 e posteriores e os modelos Fable. O ID do modelo não precisa do sufixo [1m], e as sessões compactam em cerca de 967K tokens. Antes do Claude Code v2.1.287 na máquina do desenvolvedor, o Claude Code tratava os modelos Opus e Fable como tendo uma janela de 200K, a menos que o ID do modelo terminasse em [1m].

Para que as sessões de terminal compactem no limite de 200K, defina a janela de compactação automática no env da política:

managed:
  policies:
    - match: {}
      cli:
        env:
          CLAUDE_CODE_AUTO_COMPACT_WINDOW: "200000"

O Claude Code aplica esta variável sem mostrar ao desenvolvedor a caixa de diálogo de aprovação. A variável se aplica a todos os modelos, incluindo IDs de modelo que terminam em [1m].

Para desativar o contexto de 1M, defina CLAUDE_CODE_DISABLE_1M_CONTEXT: "1" no mesmo bloco env. O Claude Code então trata todos os modelos como tendo uma janela de 200K. Em sessões interativas, cada desenvolvedor aprova esta variável na caixa de diálogo de aprovação antes que ela entre em vigor.

Cache de prompt de uma hora

Para solicitar o TTL do cache de prompt de uma hora em vez dos cinco minutos padrão, adicione estas chaves ao bloco code, cli ou settings existente de uma política e reinicie o gateway. As chaves precisam do Claude Code v2.1.242 ou posterior no servidor do gateway e nos clientes.

promptCacheTtl cobre a conversa principal. subagentPromptCacheTtl é opcional e cobre subagentes, fluxos de trabalho e requisições em segundo plano. Este exemplo adiciona ambas a uma política match: {} com a chave cli:

managed:
  policies:
    - match: {}
      cli:
        promptCacheTtl: 1h
        subagentPromptCacheTtl: 1h

[!WARNING]

Defina as chaves somente se seus upstreams oferecerem o TTL de uma hora para todos os modelos que o gateway serve. Se um upstream rejeitar o TTL, a requisição falha, e nem o gateway nem o Claude Code tentam novamente com o TTL de cinco minutos. Para o Amazon Bedrock, verifique os modelos, regiões e limites suportados.

Para confirmar promptCacheTtl, conecte-se ao gateway como um usuário que a política corresponde e verifique qual TTL suas gravações em cache usaram. Passe --model para repetir a verificação para cada modelo que o gateway serve.

Gravações em cache de uma hora custam mais do que gravações de cinco minutos. Para que os limites de gastos contabilizem essa tarifa mais alta, você precisa da v2.1.286 ou posterior no servidor do gateway.

Servidores MCP em uma política

Para fornecer servidores MCP aos clientes Claude Code que uma política corresponde, defina managedMcpServers no bloco cli dessa política. Você precisa do Claude Code v2.1.259 ou posterior no servidor do gateway e nos clientes.

O gateway verifica cada entrada na inicialização com as mesmas regras que o Claude Code aplica no cliente e, se uma entrada falhar em uma verificação, o gateway se recusa a iniciar e nomeia a entrada.

Se você escrever uma referência ${VAR} no gateway.yaml, o gateway a resolve a partir de seu ambiente na inicialização por meio da expansão de segredos antes de executar as verificações das entradas, então todo cliente correspondente recebe o valor literal e pode lê-lo. As orientações sobre cabeçalhos para servidores fornecidos se aplicam ao valor expandido.

O gateway rejeita a grafia mcpServers do .mcp.json em um bloco cli, e seu erro de inicialização indica managedMcpServers como a chave a ser usada. Antes da v2.1.259, o gateway rejeitava qualquer definição de servidor MCP em um bloco cli.

Sobreposição do Claude Desktop

Se sua organização também implanta o Claude Desktop, o mesmo gateway serve ambos os clientes. Aponte bootstrapUrl, na configuração gerenciada do Claude Desktop, para <listen.public_url>/user/bootstrap. O Claude Desktop deriva o emissor OAuth dessa URL, executa o mesmo login por código de dispositivo contra este gateway e busca sua configuração na resposta.

[!NOTE]

Requer o Claude Code v2.1.203 ou posterior no servidor do gateway e uma adesão explícita: /user/bootstrap retorna 404, a menos que a política correspondente ao usuário tenha uma chave desktop. Um desktop: {} vazio faz uma política aderir, e uma chave desktop na camada base match: {} faz aderir todas as políticas que a herdam. O log de auditoria registra cada requisição como desktop_bootstrap.serve ou desktop_bootstrap.denied.

Se você não implanta o Claude Desktop, deixe desktop totalmente fora de suas políticas; o gateway então retorna 404 de /user/bootstrap para todos os usuários.

Configurações que o gateway deriva para o Claude Desktop

O gateway deriva grande parte da resposta de bootstrap do bloco cli ou code da política correspondida e da configuração de nível superior do gateway:

• A lista de modelos, de availableModels. A lista deixa de fora os modelos que a política bloqueia com deniedModels ou availableModelsMatch: exact. Este filtro requer o Claude Code v2.1.299 ou posterior no servidor do gateway. Contexto estendido no Claude Desktop aborda a opção de contexto de 1M de cada modelo

• Ferramentas desativadas, de entradas permissions.deny com apenas o nome da ferramenta. Se você definir disabledBuiltinTools no bloco desktop da política, o gateway serve a união do seu valor com a lista derivada, então você pode desativar mais ferramentas dessa forma, mas não pode reativar uma que desativou por meio de permissions.deny

• A allowlist de saída, de sandbox.network.allowedDomains. Se você definir coworkEgressAllowedHosts no bloco desktop da política, o gateway usa esse valor em vez da lista derivada. Se a allowlist que o gateway serve incluir * e o gateway não servir também o allowedWorkspaceFolders do Claude Desktop, o Claude Desktop não ativa o sandbox do Bash na aba Code

• Um endpoint OTLP que aponta para o próprio gateway e os atributos de identidade do usuário conectado. O gateway repassa as exportações que recebe nesse endpoint para seus destinos forward_to. Ele inclui o endpoint e os atributos quando você define tanto telemetry.forward_to quanto listen.public_url.

  O Claude Desktop exporta todos os sinais com uma única codificação: http/protobuf, ou http/json quando você define OTEL_EXPORTER_OTLP_PROTOCOL ou uma de suas variantes por sinal como http/json no env da política. Antes do Claude Code v2.1.261 no servidor do gateway, a resposta definia http/json de qualquer forma, então um coletor que aceita apenas protobuf rejeitava as exportações do Claude Desktop

Para definir disabledBuiltinTools, coworkEgressAllowedHosts ou a própria configuração managedMcpServers do Claude Desktop no bloco desktop de uma política, você precisa do Claude Code v2.1.232 ou posterior no servidor do gateway. O managedMcpServers do Claude Desktop aceita um valor de array em vez de um objeto.

O gateway omite da resposta de bootstrap as chaves sem equivalente no Claude Desktop, como hooks e regras de permissão com escopo como Bash(npm *).

Aplicar configurações code na aba Code

As configurações do Claude Code que uma política mantém sob sua chave code se aplicam na aba Code do Claude Desktop quando todas estas condições são atendidas:

• A política também tem uma chave desktop, e um desktop: {} vazio conta
• O Claude Desktop é a versão 2.9939.2 ou posterior
• As configurações gerenciadas do Claude Code na máquina nomeiam este gateway
• Essa máquina acessa o gateway por HTTPS em uma rede privada

As duas últimas condições se aplicam à máquina que executa o Claude Code para a sessão. Para uma sessão local, é o próprio computador do usuário. Para uma sessão da aba Code via SSH, é o host remoto.

Implante as configurações gerenciadas do lado do cliente nessas máquinas antes de renomear cli para code. Quando as duas primeiras condições são atendidas e qualquer uma das duas últimas falha, um usuário que a política corresponde obtém um destes resultados:

• Por HTTPS, onde o Claude Desktop inclui o Claude Code v2.1.296 ou posterior: a aba Code não inicia, e a resposta ao prompt do usuário explica o motivo
• Por HTTPS, onde o Claude Desktop inclui uma versão anterior: a aba Code inicia sem suas configurações code, e nada na sessão informa isso
• Por HTTP simples: a aba Code inicia sem suas configurações code, qualquer que seja a versão que o Claude Desktop inclui

Quando um proxy na frente do gateway responde a /managed/settings com seu próprio 404, a aba Code também inicia sem suas configurações code, inclusive em uma máquina que atende às quatro condições.

Em uma política que tem uma chave desktop, um bloco code que contém configurações desativa a ferramenta WebSearch no Cowork, no Chat e na aba Code. Para servidores MCP, consulte Onde managedMcpServers se aplica.

Definir configurações do Claude Desktop diretamente

Adicione o bloco opcional desktop junto com cli para definir configurações do Claude Desktop diretamente. Escreva as configurações da referência de configuração gerenciada do Claude Desktop como nomes de chave simples. Deixe de fora as chaves que o Claude Desktop lê apenas de MDM ou de arquivos locais, como bootstrapUrl; o gateway as rejeita na inicialização.

Este exemplo define três chaves do Claude Desktop para o grupo eng-contractors junto com suas configurações cli:

managed:
  policies:
    - match: { groups: [eng-contractors] }
      cli:
        availableModels: [claude-sonnet-4-6]
        enforceAvailableModels: true
      desktop:
        isLocalDevMcpEnabled: false
        disableAutoUpdates: true
        banner: { text: "Contractor build: internal use only" }

Todas as chaves são opcionais; o Claude Desktop aplica seu próprio padrão para qualquer chave que você omitir.

O que o gateway rejeita na inicialização

O gateway valida cada bloco desktop na inicialização em relação ao esquema de configuração que o próprio Claude Desktop usa, para que um erro apareça na inicialização do gateway como uma mensagem que nomeia a chave, em vez de chegar a todos os desktops conectados. O gateway falha na inicialização quando um bloco contém:

• Uma chave desconhecida
• Uma chave reconhecida cujo valor o Claude Desktop rejeitaria ou descartaria silenciosamente, como um valor vazio ou uma subchave com erro de digitação dentro de uma entrada aninhada. Antes da v2.1.260, o gateway descartava silenciosamente um campo com erro de digitação dentro de um objeto aninhado de uma entrada de managedMcpServers ou orgPluginSettings, em vez de falhar na inicialização.
• Uma chave que o próprio gateway calcula: a conexão de inferência, a lista de modelos e o relay OTLP. Configure-as por meio de upstreams, models e do forward_to da seção telemetry.
• Um alias legado de uma chave atual. No erro de inicialização, o gateway nomeia a chave canônica a ser escrita.

Se você usar um valor ou formato de entrada descontinuado, como uma entrada de managedMcpServers sem transport, o gateway inicia e registra um aviso que nomeia a substituição.

Antes da v2.1.232, o gateway aceitava uma lista fixa de 11 chaves de controle de recursos, como chatTabEnabled e disableAutoUpdates, e rejeitava todas as outras chaves na inicialização. Antes da v2.1.227, o gateway também rejeitava chatTabEnabled e chatAdvancedFileAnalysisEnabled na inicialização.

Chaves que precisam de uma versão mais recente do gateway ou do Claude Desktop

O gateway valida um bloco desktop em relação ao esquema empacotado com sua versão instalada, assim como faz com o bloco cli. Para entregar uma configuração introduzida por uma versão mais nova do Claude Desktop, atualize o gateway primeiro. Por exemplo, userPluginMarketplacesEnabled e userPluginUploadsEnabled precisam do Claude Code v2.1.260 ou posterior no servidor do gateway e do Claude Desktop 1.37937.0 ou posterior nas máquinas dos membros.

blockReadsOutsideWorkingDirectories, disableBypassPermissionsMode, configRecheckIntervalMinutes e sshClientPath precisam do Claude Code v2.1.281 ou posterior no servidor do gateway. O mesmo vale para o valor required de microsoftAuthBroker e o campo continuousAccessEvaluation de uma entrada managedMcpServers do Microsoft 365. Versões do Claude Desktop anteriores ao valor required o leem como disabled, então defina required somente depois que o Claude Desktop de todos os membros o suportar. A referência de configuração gerenciada do Claude Desktop lista a versão que primeiro lê cada chave.

[!NOTE]

sshTransport precisa do Claude Code v2.1.293 ou posterior no servidor do gateway.

Se você definir orgPluginSettings no bloco desktop de uma política, o gateway o serve na forma de array que o Claude Desktop 1.15200.0 e posteriores leem. Desktops mais antigos ignoram o array e não aplicam nenhuma política de ferramentas de plugin, então atualize os membros para 1.15200.0 ou posterior antes de depender disso.

Como uma política de função herda o bloco desktop base

O gateway preenche as chaves que o bloco desktop de uma política não define a partir do bloco desktop do catch-all match: {}, da mesma forma que preenche o bloco cli de uma política a partir da base. Se você definir disabledBuiltinTools ou builtinToolPolicy tanto na base quanto em uma política de função, o gateway mantém a restrição da base:

• disabledBuiltinTools: o gateway usa a união da lista da base com a lista da política
• builtinToolPolicy: se você definir uma ferramenta com um valor diferente de allow na base, o gateway mantém esse valor mesmo que você defina allow para a mesma ferramenta em uma política de função

Para todas as outras chaves, se você a definir na política de função, o gateway usa o valor da política de função. O gateway substitui um array ou um objeto aninhado como banner por inteiro, então, se você definir banner.text em uma política de função, o gateway descarta o banner.backgroundColor da base.

Quando uma alteração de política chega ao Claude Desktop

Depois que você reimplanta o gateway com uma política alterada, o Claude Desktop aplica a maioria das configurações somente na próxima vez que inicia:

• Fechado: o Claude Desktop busca a resposta de bootstrap ao iniciar, então a alteração se aplica a partir da próxima inicialização
• Aberto: o Claude Desktop verifica se há uma resposta alterada a cada 10 minutos por padrão e aplica algumas configurações sem reiniciar. Para as demais, como skillCreationEnabled, o usuário vê um cartão Relaunch Claude Desktop na barra lateral e mantém a configuração anterior até reiniciar o aplicativo. Após 24 horas por padrão, o Claude Desktop mostra uma caixa de diálogo de reinicialização e reinicia sozinho após 2 minutos de inatividade

Para encurtar as 24 horas, defina relaunchEnforcementHours no bloco desktop da política. Você precisa do Claude Code v2.1.260 ou posterior no servidor do gateway e do Claude Desktop 1.40609.0 ou posterior nas máquinas dos membros. Com 0, a caixa de diálogo aparece assim que o Claude Desktop encontra a alteração.

Contexto estendido no Claude Desktop

Se você serve o Claude Desktop a partir do gateway, seu seletor de modelos oferece uma opção de contexto de 1M para cada modelo listado que pode ser executado com uma janela de contexto de 1M. Isso inclui o Claude Opus 4.6 e posteriores, o Claude Sonnet 4.6 e posteriores e os modelos Fable. A opção é a variante [1m] do modelo, descrita em Contexto estendido. Você precisa do Claude Code v2.1.284 ou posterior no servidor do gateway.

Uma entrada de models não recebe a opção de 1M quando:

• Um upstream que pode servir a entrada a mapeia para um modelo sem suporte a 1M, incluindo um upstream que o gateway alcança apenas em failover
• Nem seu id nem qualquer um de seus valores de upstream_model nomeia um modelo Claude, como um alias personalizado roteado para um ARN de perfil de inferência de aplicação

Para alterar o que o seletor oferece, use uma destas opções:

• Iniciar os usuários na opção de 1M: defina modelPrefer1mContext: true no bloco desktop da política. Usuários que ainda não escolheram um modelo começam na opção de 1M quando o primeiro modelo listado tem uma. Usuários que já escolheram um modelo mantêm sua escolha.
• Oferecer a opção manualmente: faça isso se o servidor do seu gateway executa uma versão anterior à v2.1.284 ou se uma entrada não nomeia nenhum modelo Claude. Liste o modelo duas vezes em models, uma com seu ID simples e outra com [1m] anexado, ambas com o mesmo mapa upstream_model. O Claude Desktop mostra o par como um único modelo com uma opção de 1M. O gateway serve uma entrada [1m] sem verificá-la, então adicione uma somente para um modelo que seus upstreams servem com 1M.

Este exemplo oferece a opção manualmente para um alias personalizado roteado para um perfil de inferência de aplicação e inicia os novos usuários nela:

models:
  - id: corp-sonnet
    upstream_model:
      bedrock: arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-5-prod
  - id: corp-sonnet[1m]
    upstream_model:
      bedrock: arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-5-prod

managed:
  policies:
    - match: {}
      desktop:
        modelPrefer1mContext: true

Remover a opção de 1M

Para remover a opção do seletor, defina CLAUDE_CODE_DISABLE_1M_CONTEXT: "1" no bloco env sob a chave cli da política. Se você também listou uma entrada cujo id termina em [1m], o gateway ainda a serve, então exclua essa entrada também.

A variável também chega às sessões de terminal dos desenvolvedores que a política corresponde. Para saber o que ela altera ali, consulte Contexto estendido.

Precedência com outras fontes gerenciadas

Se um dispositivo também tiver uma política entregue por MDM ou um managed-settings.json local, as configurações entregues pelo gateway têm a maior prioridade. Precedência dentro do nível gerenciado, na página de configurações gerenciadas, explica quando as fontes locais se aplicam e traz as chaves que o Claude Code lê de todas as fontes de administrador, independentemente da fonte selecionada, como as chaves de bloqueio do sandbox, forceRemoteSettingsRefresh e a mesclagem de env por variável. Um policyHelper configurado em um perfil MDM ou no arquivo de configurações gerenciadas só é executado quando o gateway não entrega nenhuma configuração; a entrada informa o que sua saída substitui.

Hosts incorporadores como o Claude Desktop podem fornecer políticas por meio da opção managedSettings do SDK. Configurações pai de hosts incorporadores explica quando o Claude Code as aplica, e Restringir configurações pai lista quais configurações na direção de permissão ainda se aplicam sem os bloqueios allowManaged*Only.

As políticas do gateway se aplicam a toda invocação do Claude Code na máquina, incluindo execuções não interativas de claude -p e sessões geradas pelo Agent SDK. Se o gateway estiver inacessível na inicialização, as sessões conectadas são encerradas com um erro em vez de serem executadas sem sua política.

telemetry

A CLI envia métricas, logs e, quando habilitados, traces para o gateway, que os repassa literalmente para cada destino configurado. As exportações usam o OpenTelemetry Protocol (OTLP) sobre HTTP. Para ignorar o relay e fazer as sessões exportarem diretamente para seu coletor, nomeie o coletor em uma política. Consulte Monitorar o uso para ver as métricas e os eventos que a CLI emite.

Em sessões conectadas por meio de /login, a CLI marca 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 por parte do desenvolvedor. Os eventos que o Claude Code registra antes de o desenvolvedor se conectar não carregam essa identidade. Para ver qual atributo acompanha uma alteração nos grupos de um desenvolvedor, consulte Alterações de grupo durante uma sessão aberta.

Sessões do Claude Desktop e do Cowork conectadas por meio do gateway marcam sua telemetria com user.email e user.groups junto com enduser.id, então você pode cobrir o uso do terminal, do Desktop e do Cowork com uma única consulta em user.email ou user.groups. user.groups é a lista de grupos do IdP separada por vírgulas.

A telemetria do Desktop e do Cowork também carrega enduser.sub, a claim sub que seu provedor de identidade emite para o usuário, que permanece a mesma quando o e-mail de um usuário muda. As sessões de terminal marcam o mesmo valor em user.id, então uma consulta que compara enduser.sub com o user.id do terminal cobre juntos o uso de um usuário no terminal, no Desktop e no Cowork. Nas exportações do Desktop e do Cowork, user.id é um identificador anônimo, não o sujeito.

Como todos os dados do OpenTelemetry do Claude Code, esses atributos vão apenas para destinos que sua organização configura, nunca para a Anthropic.

Se a lista de grupos de um usuário tiver mais de 255 caracteres após a codificação percentual, ou se um nome de grupo contiver uma vírgula ou um sinal de igual, o gateway deixa user.groups de fora da telemetria do Desktop e do Cowork desse usuário em vez de truncá-la. As sessões de terminal desse usuário ainda carregam a lista completa.

O gateway deixa enduser.sub de fora quando o sujeito tem mais de 255 caracteres após a codificação percentual, ou contém um espaço, um caractere fora do ASCII imprimível ou um destes: , ; = \ " %. A telemetria do Desktop e do Cowork desse usuário mantém seus outros atributos.

Você precisa do Claude Code v2.1.265 ou posterior no servidor do gateway para user.email e user.groups na telemetria do Desktop e do Cowork, e do Claude Desktop 1.24012 ou posterior na máquina de cada desenvolvedor para user.groups.

Você precisa do Claude Code v2.1.274 ou posterior no servidor do gateway para enduser.sub.

telemetry:
  forward_to:
    - url: https://otel-collector.internal.example.com
      headers:
        Authorization: ${OTLP_TOKEN}
      # Per-signal opt-in. Default: metrics only.
      metrics: true
      logs: false
      traces: false
    - url: https://api.datadoghq.com/api/v2/otlp
      headers:
        DD-API-KEY: ${DD_API_KEY}

[!WARNING]

Cada destino adere a metrics, logs e traces de forma independente, e o padrão é somente métricas. Os sinais diferem em sensibilidade:

• Métricas: contadores agregados, como contagens de tokens, contagens de requisições e latência
• Logs e traces: podem carregar comandos Bash completos, entradas de ferramentas e caminhos de arquivos, cobrindo tudo o que o Claude Code faz na máquina de um desenvolvedor

Habilite logs e traces somente em destinos com os controles de acesso e a política de retenção que esses dados exigem.

Cada URL de forward_to deve usar https://, com uma exceção para um coletor na própria interface de loopback do gateway:

• http://localhost:<port> passa na validação da configuração, mas a proteção contra SSRF bloqueia todas as exportações com ECONNREFUSED_SSRF, a menos que você defina CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 no ambiente do gateway
• http://127.0.0.1:<port> ou http://[::1]:<port> faz a inicialização falhar, a menos que essa variável esteja definida

Para um coletor dentro do cluster, exponha-o por HTTPS em seu próprio endereço interno ou execute-o como sidecar com a variável definida.

Quando HTTPS_PROXY está definido, o gateway envia as exportações por meio desse proxy.

Para acessar um coletor interno diretamente, adicione-o a NO_PROXY pelo nome de host ou por um domínio com ponto inicial, como .internal.example.com, o que requer o Claude Code v2.1.277 ou posterior no servidor do gateway. Certifique-se de que o gateway consegue acessar o coletor sem o proxy. Uma entrada sem ponto inicial corresponde apenas a esse nome exato, não a nomes abaixo dele. Intervalos CIDR não correspondem.

Com a saída somente por proxy ativada, permita o coletor no proxy, já que qualquer entrada em NO_PROXY mantém a saída somente por proxy desativada.

A telemetria fica desativada na CLI por padrão. Quando você define tanto telemetry.forward_to quanto listen.public_url, o gateway a ativa para os clientes conectados enviando seis variáveis de ambiente por meio de /managed/settings:

• CLAUDE_CODE_ENABLE_TELEMETRY=1
• OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTER e OTEL_TRACES_EXPORTER, cada uma definida como otlp se pelo menos um destino forward_to habilitar esse sinal, e como none caso contrário
• OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>
• OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

Quando você adiciona seus próprios rótulos, o gateway também envia OTEL_RESOURCE_ATTRIBUTES.

Antes do Claude Code v2.1.265 no servidor do gateway, o gateway enviava os três seletores de exportador como otlp, inclusive para sinais aos quais nenhum destino havia aderido.

O endpoint enviado é construído a partir da URL pública, então métricas e logs não precisam de nenhuma configuração OTEL por parte dos desenvolvedores ou das políticas.

Desenvolvedores conectados por meio de /login não podem redirecionar as exportações com sua própria configuração OTEL:

• Variáveis definidas localmente: o Claude Code aplica as variáveis enviadas no nível gerenciado, então cada uma sobrescreve o valor que um desenvolvedor define para ela localmente.
• Endpoints configurados localmente: com a exportação OTLP/HTTP habilitada, a CLI ignora qualquer endpoint configurado localmente, independentemente de o gateway ter enviado as variáveis de telemetria. Suas exportações vão para o gateway, a menos que uma política nomeie seu coletor como o endpoint.

Sem um destino forward_to para um sinal, o gateway o aceita e o descarta. Se os desenvolvedores já exportam a telemetria do Claude Code para um de seus coletores, adicione-o como destino forward_to, com logs ou traces habilitados se eles os exportarem, para que ele continue recebendo os dados depois que se conectarem. Para ignorar o relay, nomeie o coletor em uma política.

Os traces também exigem CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 em cada cliente. Defina-a no bloco env de uma política gerenciada, já que o gateway não a envia. Os desenvolvedores a aprovam na mesma caixa de diálogo de aprovação de segurança que o endpoint enviado já aciona.

Defina-a como 1 somente nas políticas cujos grupos você deseja rastrear. Uma política que não a define herda o valor da sua política catch-all match: {}, se essa política definir um, conforme as regras de mesclagem. Para impedir que os clientes de um grupo enviem traces mesmo quando um desenvolvedor define a variável localmente, defina-a como 0 na política desse grupo.

As codificações OTLP protobuf e JSON são repassadas, e qualquer backend compatível com OpenTelemetry funciona como destino.

Enviar métricas cumulativas

Se seu coletor aceita apenas métricas cumulativas, defina OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE como cumulative. O Claude Code envia métricas delta por padrão, e o gateway as repassa sem convertê-las. Defina a variável onde cada tipo de sessão a lê:

• Sessões de terminal: no bloco env sob a chave cli ou code de uma política
• Sessões do Cowork que são executadas na máquina do usuário: no bloco env das configurações gerenciadas do lado do cliente nessa máquina
• Sessões da aba Code sob uma política code: no bloco env da política, depois que você atender às condições para que as configurações code se apliquem
• Sessões da aba Code sob uma política cli: no bloco env das configurações gerenciadas do lado do cliente na máquina que executa a sessão. Via SSH, esse é o host remoto.

Se você adicionar a variável às configurações gerenciadas de uma máquina, defina também parentSettingsBehavior: "merge" na fonte de maior prioridade nessa máquina. Sem isso, as sessões do Cowork e as sessões da aba Code sob uma política cli são executadas sem a allowlist de saída e as demais políticas que o Claude Desktop lhes passa como configurações pai.

Adicionar seus próprios rótulos

Para colocar rótulos fixos, como service.namespace ou deployment.environment.name, na telemetria das sessões conectadas por meio do gateway, defina telemetry.resource_attributes. Cada rótulo é um atributo de recurso do OpenTelemetry, e todos os destinos recebem os mesmos rótulos.

As sessões recebem os rótulos somente quando você também define telemetry.forward_to e listen.public_url. Este exemplo adiciona dois rótulos:

telemetry:
  forward_to:
    - url: https://otel-collector.internal.example.com
  resource_attributes:
    service.namespace: claude
    deployment.environment.name: prod

O gateway se recusa a iniciar quando um rótulo viola uma destas regras, e o erro de inicialização nomeia o rótulo:

• Os nomes usam apenas letras, dígitos, ., _ e -
• Os nomes não são reservados. Comparados em qualquer combinação de maiúsculas e minúsculas, os nomes reservados são tudo o que começa com user., enduser. ou identity., além de service.name, service.version, claude.deployment_mode, host.arch, os.type, os.version e wsl.version
• Os valores são ASCII imprimível não vazio, sem espaço e sem nenhum destes: , ; = \ " %
• Os valores têm no máximo 255 caracteres conforme o gateway os conta após a codificação percentual, então /, : e @ contam como três cada
• Os valores são texto, então coloque entre aspas um número, true ou false

Você precisa do Claude Code v2.1.281 ou posterior no servidor do gateway para definir telemetry.resource_attributes. 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.

Sessões de terminal conectadas por meio de /login recebem os rótulos como OTEL_RESOURCE_ATTRIBUTES, enviados com as outras variáveis de telemetria. Se você definir OTEL_RESOURCE_ATTRIBUTES no bloco env de uma política, as sessões de terminal que essa política corresponde recebem esse valor em vez dos rótulos. O Claude Desktop recebe os rótulos do gateway junto com user.email e os outros atributos de identidade.

O Claude Code também copia cada rótulo para cada ponto de dados de métrica, para que você possa filtrar as métricas por ele em um backend que não indexa atributos de recurso. Para desativar essa cópia, consulte Controle de cardinalidade de métricas.

Alterações de grupo durante uma sessão aberta

As sessões de terminal colocam user.groups no recurso OTLP e novamente em cada ponto de dados de métrica e evento. Se os grupos de um desenvolvedor mudarem enquanto uma sessão está aberta, os pontos de dados e eventos do uso posterior à próxima atualização silenciosa carregam os novos grupos. O recurso mantém os grupos antigos até que o desenvolvedor reinicie o Claude Code, então agrupe pelo atributo no ponto de dados ou no evento.

Se você ativar resource_to_telemetry_conversion no exportador Prometheus remote write do OpenTelemetry Collector, o exportador substitui o user.groups de cada ponto de dados pelo do recurso, então todos os pontos de dados mostram os grupos antigos. Para manter o valor do ponto de dados, exclua user.groups do recurso antes desse exportador.

Este processador resource do OpenTelemetry Collector exclui o atributo nos pipelines que o listam:

processors:
  resource/drop-user-groups:
    attributes:
      - key: user.groups
        action: delete

Depois de adicionar resource/drop-user-groups aos processors do pipeline de métricas, cada série carrega o rótulo user_groups de seu próprio ponto de dados.

Exportar diretamente para o seu coletor

Para que as sessões conectadas por meio de /login enviem telemetria diretamente para o seu coletor em vez de passar pelo relay, defina OTEL_EXPORTER_OTLP_ENDPOINT como a URL base https:// do coletor no bloco env de uma política gerenciada. O Claude Code acrescenta /v1/metrics, /v1/logs ou /v1/traces à URL que você definir, como https://otel-collector.example.com:4318, e exporta cada sinal para lá via OTLP/HTTP. Requer o Claude Code v2.1.265 ou posterior na máquina de cada desenvolvedor. Clientes anteriores exportam por meio do relay.

Para autenticar no coletor, defina OTEL_EXPORTER_OTLP_HEADERS no mesmo bloco env. As sessões nunca enviam o token de sessão do gateway do desenvolvedor para um coletor especificado dessa forma.

Quando você adiciona ou altera esse endpoint em uma política, o Claude Code pede a cada desenvolvedor que o aprove na caixa de diálogo de aprovação de segurança antes de aplicá-lo em uma sessão interativa.

O Claude Code verifica o endpoint antes de exportar um sinal diretamente e mantém esse sinal no relay quando uma verificação falha. As verificações incluem:

• O endpoint vem do próprio gateway. Se você definir a mesma variável em um perfil MDM ou em um managed-settings.json local, as exportações permanecem no relay.
• A URL usa https://, ou http:// para um endereço de loopback
• A URL resolve para um caminho que termina em /v1/<signal>, sem query nem fragmento. O Claude Code constrói esse caminho por conta própria a partir da variável genérica. Ele usa uma variável por sinal, como OTEL_EXPORTER_OTLP_METRICS_ENDPOINT, exatamente como escrita, portanto inclua o caminho completo nela.
• A URL não é o próprio host do gateway. Um endpoint endereçado ao gateway mantém o caminho do relay e seu token de sessão.
• Nem você nem o desenvolvedor configuraram otelHeadersHelper em nenhuma fonte de configurações. Com um helper configurado, todos os sinais permanecem no relay.

O endpoint que você especifica altera apenas para onde as exportações vão. Você ainda escolhe quais sinais são exportados com os seletores OTEL_*_EXPORTER.

O endpoint sozinho não ativa a exportação, então defina também as variáveis que fazem isso, a menos que o gateway já as envie:

• Se o gateway já envia as variáveis de telemetria, elas cobrem a ativação, os seletores e o protocolo, e o seu endpoint explícito sobrescreve o valor <public_url> enviado. Defina você mesmo um seletor OTEL_*_EXPORTER como otlp somente para um sinal que nenhum destino forward_to ativa.
• Caso contrário, defina também CLAUDE_CODE_ENABLE_TELEMETRY=1, os seletores OTEL_*_EXPORTER e OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf.

Quando o desenvolvedor sai da conta, ou faz login em um gateway diferente, as exportações para o coletor param e o Claude Code descarta cada lote restante em vez de enviá-lo.

Quando um destino falha

O gateway não armazena em buffer, não tenta novamente nem armazena telemetria, portanto descarta uma exportação que não chega a um destino em vez de entregá-la com atraso. Cada destino tem sucesso ou falha de forma independente, e o cliente que exporta recebe uma resposta de sucesso em qualquer caso, então uma entrega com falha aparece apenas no log do gateway.

Após cinco entregas consecutivas com falha para um destino, o gateway pausa o encaminhamento para ele em intervalos de 30 segundos, registrando cada pausa em log, até que uma entrega seja bem-sucedida. Qualquer resposta de erro, timeout ou erro de conexão conta como uma entrega com falha, exceto 400, 413, 415, 422 e 431, que significam que o coletor recusou o payload dessa exportação por estar malformado ou grande demais.

Um payload recusado não avança nem redefine a contagem de falhas: o gateway continua encaminhando para o destino e registra em log um aviso indicando o destino e o status, na primeira recusa do destino e a cada centésima depois disso.

Ajuste de HTTP

Quatro blocos opcionais de nível superior, access_control, limits, timeouts e rate_limits, ajustam a superfície HTTP. Os padrões atendem à maioria das implantações.

Se você deixar ambas as listas de access_control vazias, que é o padrão, o gateway atende qualquer endereço de cliente, então apenas a sua rede restringe quem pode alcançá-lo. Isso importa porque um gateway pode enviar configurações gerenciadas que executam comandos nas máquinas dos desenvolvedores.

Enquanto allow_cidrs estiver vazio, o gateway emite avisos em dois lugares, sem alterar a forma como responde a qualquer requisição:

• Na inicialização: um aviso no log operacional recomenda permitir apenas os intervalos privados 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 100.64.0.0/10, 127.0.0.0/8, ::1/128 e fc00::/7, além de quaisquer outros intervalos internos a partir dos quais seus desenvolvedores se conectam. Se você vincular o gateway a um endereço de loopback e não definir nem trusted_proxies nem public_url, como no desenvolvimento local, o aviso não aparece.
• Em tempo de execução: na primeira vez que uma requisição chega de um endereço fora desses intervalos privados, o gateway registra um aviso em log e emite um evento de auditoria access.public_client contendo o IP do cliente. Ambos ocorrem uma vez por processo. Endereços link-local, 169.254.0.0/16 e fe80::/10, não contam como públicos. O gateway responde a /healthz e /readyz antes que essa verificação seja executada, então sondagens de integridade de intervalos públicos não a acionam.

Ambos os sinais usam o endereço do cliente conforme resolvido pelo gateway. Se um balanceador de carga, port-forward ou túnel retransmite o tráfego e não está listado em listen.trusted_proxies, o gateway vê o endereço do intermediário, que geralmente é privado, então nem o aviso em tempo de execução nem uma lista de permissões privada capturam o tráfego retransmitido por ele.

Por trás de um front end desse tipo, defina primeiro listen.trusted_proxies para que o gateway veja os endereços reais dos clientes e, de qualquer forma, mantenha o gateway e tudo o que está à frente dele inacessíveis a partir da internet pública.

load_test_mode

O bloco load_test_mode permite fazer teste de carga em um gateway sem chamar um provedor de modelo. Enquanto está ativado, o gateway monta e assina cada requisição ao provedor normalmente, descarta-a em vez de enviá-la e transmite uma resposta pré-definida de volta pelo seu caminho normal de resposta. A resposta é um texto de preenchimento que começa com uma frase informando que ela é pré-definida.

Requer o Claude Code v2.1.282 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 o bloco e remova o bloco antes de reverter a versão.

O exemplo abaixo ativa o modo com os padrões, uma resposta de aproximadamente 750 tokens de texto transmitida ao longo de cerca de 10 segundos:

load_test_mode:
  enabled: true
  reply_tokens: 750     # roughly how many tokens of text each canned reply carries
  reply_seconds: 9.5    # how long a streamed reply takes

Um teste de carga nesse modo abrange o gateway, o seu Postgres e tudo o que está à frente do gateway. Ele não abrange os limites, a velocidade nem o caminho de rede do provedor.

Nenhuma requisição de modelo é enviada ao provedor, portanto a CPU por requisição de uma réplica é uma estimativa e aparece menor do que em produção, que também criptografa seu tráfego para o provedor. Confirme a quantidade de réplicas com um pequeno piloto contra o provedor real. Antes da v2.1.283, a estimativa aparece muito menor.

Enquanto o modo está ativado, uma requisição pode carregar um cabeçalho x-load-test-user contendo um número inteiro de até sete dígitos. O gateway conta cada número como um desenvolvedor separado, com o e-mail e os grupos do desenvolvedor cujo token acompanhou a requisição.

Dê à implantação de teste de carga seu próprio banco de dados vazio, pois o gateway se recusa a iniciar com o modo ativado em um banco de dados no qual qualquer desenvolvedor já tenha gasto algo.

[!WARNING]

Nunca ative isso em um gateway que os desenvolvedores usam. Toda requisição recebe a resposta pré-definida e nenhum modelo é chamado. O gateway registra em log um aviso load_test_mode is on na inicialização e marca cada evento de auditoria inference com load_test: true enquanto o modo está ativado.

Exemplo completo

Esta configuração de referência completa exercita cada seção principal; os blocos de ajuste HTTP mantêm seus padrões. Copie-a, delete o que você não precisa e preencha seus valores. A configuração no Quickstart é uma versão mínima desta.

# Execute com:
#   claude gateway --config gateway.yaml
#
# A verbosidade do log operacional é controlada pela variável de ambiente
# CLAUDE_GATEWAY_LOG_LEVEL (debug | info | warn | error; padrão info). debug
# também registra os nomes de claims em cada id_token, para diagnóstico de groups_claim.
# Isso não afeta eventos de auditoria, que são sempre emitidos.

listen:
  host: 0.0.0.0
  port: 8080
  public_url: https://claude-gateway.internal.example.com
  # Omita o bloco tls ao executar atrás de um ingress que encerra TLS.
  # tls:
  #   cert: /certs/gateway.crt
  #   key: /certs/gateway.key
  # trusted_proxies:
  #   - 10.0.0.0/8

oidc:
  issuer: https://example.okta.com
  client_id: 0oa1example2
  client_secret: ${OIDC_CLIENT_SECRET}
  allowed_email_domains:
    - example.com
  # Obrigatório quando o emissor é o servidor da organização Okta, cujos id_tokens
  # podem omitir email e groups; o gateway os preenche a partir de /userinfo.
  userinfo_fallback: true
  # allowed_groups: [claude-code-users]
  # Okta emite groups apenas quando o escopo `groups` é solicitado e o
  # filtro de claim de grupos do aplicativo os permite. A política de contractors abaixo
  # corresponde a groups, então o escopo é solicitado aqui.
  scopes: [openid, profile, email, offline_access, groups]
  # extra_auth_params: { access_type: offline, prompt: consent }  # Google
  # groups_claim: groups          # Funções de aplicativo Entra: use `roles`
  # email_claim: email

session:
  jwt_secret: ${GATEWAY_JWT_SECRET}   # openssl rand -base64 32
  # ttl_hours: 1

store:
  postgres_url: ${GATEWAY_POSTGRES_URL}
  # max_connections: 5
  # connect_timeout_seconds: 5
  # readiness_grace_seconds: 300   # continua passando na verificação de prontidão durante um failover do banco de dados

# Habilita /v1/organizations/spend_limits (espelha a API Admin do Anthropic)
# e aplicação de gastos por desenvolvedor em /v1/messages. Omita para desabilitar.
# Os limites em si são definidos via API admin, não aqui.
# admin:
#   write_keys:
#     - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
#   read_keys:
#     - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
#   admin_groups: [platform-finops]
#   blocked_message: request an increase at https://go.example.com/claude-limits
#   # audit_retention_days: 365
#   # spend_retention_months: 13
#   # identity_retention_days: 90
#   # group_limit_mode: min

# enforcement:
#   fail_closed_on_error: false

# Teste de carga desta implantação sem chamar um provedor de modelo. Nunca em um
# gateway que desenvolvedores usam: cada requisição recebe uma resposta enlatada.
# load_test_mode:
#   enabled: true
#   # reply_tokens: 750
#   # reply_seconds: 9.5

# Meça em taxas contratadas em vez de preço de lista USD. Requer admin: ou uma
# política managed:. Com managed:, as mesmas taxas também vão para clientes conectados.
# As taxas abaixo são placeholders, não preços de contrato reais.
# pricing:
#   multiplier: 0.85
#   overrides:
#     - { upstream: anthropic, model: claude-sonnet-4-6, input: 3.30, output: 16.50, cache_read: 0.33, cache_write: 4.125 }

upstreams:
  - provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}

  # - provider: bedrock
  #   region: us-east-1
  #   auth: {}

  # - provider: mantle
  #   region: us-east-1
  #   models: [claude-opus-4-8, claude-opus-4-7, claude-haiku-4-5]
  #   auth: {}

  # - provider: anthropicAws
  #   region: us-east-1
  #   workspace_id: wrkspc_...
  #   auth:
  #     api_key: ${ANTHROPIC_AWS_API_KEY}

  # - provider: vertex
  #   region: us-east5
  #   project_id: example-prod
  #   auth: {}

  # - provider: foundry
  #   resource: example-foundry
  #   auth: { use_azure_ad: true }

auto_include_builtin_models: true
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    upstream_model:
      anthropic: claude-opus-4-8
      # bedrock: us.anthropic.claude-opus-4-8
      # mantle: anthropic.claude-opus-4-8
      # anthropicAws: claude-opus-4-8
      # vertex: claude-opus-4-8
      # foundry: <your-opus-deployment-name>
  - id: claude-sonnet-4-6
    label: Claude Sonnet 4.6
    upstream_model:
      anthropic: claude-sonnet-4-6
  - id: claude-haiku-4-5
    label: Claude Haiku 4.5
    upstream_model:
      anthropic: claude-haiku-4-5

managed:
  policies:
    - match: { groups: [contractors] }
      cli:
        availableModels: [claude-haiku-4-5]
        # allow aprova automaticamente essas ferramentas; não bloqueia o resto.
        # Adicione regras deny para restringir ferramentas.
        permissions: { allow: [Read, Grep] }
    - match: {}
      cli:
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
        # Restrinja a opção Padrão do seletor aos availableModels de cada política
        # em vez do padrão integrado, para que nenhuma função receba um 400 no Padrão.
        # A política de contractors herda esta chave.
        enforceAvailableModels: true
        permissions:
          allow: [Read, Grep, Edit]
          deny: ["WebFetch"]
        env: { HTTP_PROXY: http://proxy.example.com:8080 }

telemetry:
  forward_to:
    - url: https://otel.internal.example.com:4318
      headers:
        Authorization: Bearer ${OTEL_TOKEN}

Configurações gerenciadas no lado do cliente

Tudo acima configura o servidor gateway. Você aponta máquinas de desenvolvedores para o gateway separadamente, em cada dispositivo, através das configurações gerenciadas do Claude Code. O gateway não pode enviar as chaves de login por si só, porque são elas que dizem ao cliente onde o gateway está.

Para a CLI, defina essas chaves no managed-settings.json por SO. As duas chaves de login encaminham cada /login do desenvolvedor para seu gateway:

{
  "forceLoginMethod": "gateway",
  "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com",
  "parentSettingsBehavior": "merge"
}

parentSettingsBehavior: "merge" mantém a entrega da allowlist de saída do Claude Desktop para suas sessões incorporadas do Claude Code funcionando; Entregar política para sessões Claude Desktop explica o mecanismo e onde a aceitação deve estar.

Para impedir que os desenvolvedores contornem o gateway com uma variável de provedor de nuvem ou um ANTHROPIC_BASE_URL próprio, adicione "allowedProviders": ["gateway"] ao mesmo arquivo. O Claude Code então recusa toda sessão na máquina que não esteja configurada para um Cloud gateway, e admite um gateway apenas quando ele é aquele que forceLoginGatewayUrl nomeia ou um cuja URL o bloco env do arquivo define como ANTHROPIC_BASE_URL. claude gateway se recusa a ser executado em uma máquina que define a lista, portanto mantenha a chave fora do host do gateway. Veja a entrada allowedProviders na referência de configurações. Requer Claude Code v2.1.285 ou posterior.

Implante o arquivo managed-settings.json em cada dispositivo, normalmente através de sua plataforma MDM. O caminho do arquivo difere por plataforma. Veja onde cada mecanismo armazena a política.

Por padrão, uma política de registro no Windows ou um plist de preferências gerenciadas no macOS substitui o arquivo managed-settings.json em vez de mesclar com ele, exceto pelas chaves de exceção e verificações entre fontes acima. Todas as três chaves neste trecho seguem a regra de fonte de prioridade mais alta, portanto frotas que entregam política através de Group Policy ou perfis de configuração devem colocar todas as três nesse mecanismo.

Para Claude Desktop, defina a chave bootstrapUrl na própria configuração gerenciada do Claude Desktop como <listen.public_url>/user/bootstrap. O fluxo de entrada e a política por grupo correspondem aos da CLI uma vez que uma política aceita no servidor com uma chave desktop; sem a aceitação, /user/bootstrap retorna 404. Veja Claude Desktop overlay para a metade do servidor.

Claude Code honra forceLoginGatewayUrl, gatewayInternalNetworks e o valor "gateway" de forceLoginMethod de uma fonte gerenciada na máquina: managed-settings.json, o plist do macOS ou registro HKLM do Windows, ou um auxiliar de política. Defini-los no payload do gateway não configura o login no gateway. Para o próprio ~/.claude/settings.json de um desenvolvedor, veja Definir a URL do gateway nas configurações do usuário.

Deixe forceLoginMethod e forceLoginOrgUUID fora do payload. O Claude Code ainda lê ambas as chaves do payload para sua verificação de credenciais na inicialização, portanto um desenvolvedor que mantém uma credencial emitida pela Anthropic na máquina recebe a saída na inicialização descrita em Administrator policy requires a Cloud gateway sign-in mesmo depois de fazer login.

Relacionado

• Visão geral do gateway de aplicativos Claude: quickstart e conexão de desenvolvedor
• Guia de implantação: configuração de IdP, imagem de contêiner, Kubernetes e Cloud Run e operações
• Limites de gastos: limites por desenvolvedor e a API de Administração