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:

• login_notice: um aviso que os desenvolvedores veem ao fazer login
• 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 atende: o endereço e a porta de bind, a origem visível externamente e a terminação TLS opcional.

Liste um frontend em trusted_proxies somente se a última entrada de X-Forwarded-For que ele repassa for uma que nenhum desenvolvedor escreveu. Não liste nenhum endereço ou intervalo a partir do qual os desenvolvedores se conectam. Um frontend que acrescenta o endereço de cada conexão que recebe se qualifica. Um que repassa o cabeçalho como os desenvolvedores o enviam não se qualifica.

Entradas de X-Forwarded-For escritas como ipv4:port ou [ipv6]:port, como alguns balanceadores de carga fazem, são lidas com a porta descartada. Um endereço IPv6 com uma porta acrescentada e sem colchetes pode ser lido como um endereço diferente ou não ser lido. Desative a opção de porta em qualquer proxy que escreva essa forma.

oidc

O bloco oidc conecta o gateway ao seu provedor de identidade e decide quem pode fazer login. Ele nomeia o emissor e o cliente OAuth, mapeia as claims que carregam e-mail e grupos e restringe o login por domínio de e-mail ou grupo.

OpenID Connect (OIDC) é o protocolo de 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 client secret, como o Microsoft Entra faz com credenciais de certificado, defina token_endpoint_auth_method: private_key_jwt. Requer Claude Code v2.1.284 ou posterior no servidor do gateway.

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 sempre que o gateway renova a sessão dele. O JWT é assinado com RS256 e identifica o certificado pelos cabeçalhos de thumbprint x5t e x5t#S256, em vez de um kid. Seu IdP deve ser capaz de encontrar o certificado registrado pelo thumbprint.

1. Crie a chave e o certificado

Crie uma chave privada RSA não criptografada de pelo menos 2048 bits, no formato PEM PKCS#8 ou PKCS#1, e um certificado para ela. O gateway se recusa a iniciar com qualquer chave que não atenda a essas condições. Este comando openssl cria uma chave assim com um certificado autoassinado válido por um ano:

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 os dois arquivos em um local onde o gateway possa lê-los. O exemplo da etapa 3 usa /etc/gateway/.

2. Envie o certificado ao 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 é 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, então carregue os arquivos montados com ${file:/path}, como o exemplo faz. O gateway se recusa a iniciar a menos que certificate_pem seja um único certificado PEM, sem o restante de sua cadeia, cuja chave pública corresponda a private_key_pem.

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 refreshes falharão até que você o substitua. Para confirmar que o IdP aceita o certificado, peça a um desenvolvedor que faça login pelo gateway.

Rotacionar o certificado do cliente

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

1. Envie o novo certificado ao IdP junto com o antigo.
2. Substitua os arquivos de chave e certificado que o gateway.yaml carrega e reinicie o gateway. Se você executa várias réplicas, uma reinicialização gradual funciona, porque o IdP tem os dois certificados até que você remova o antigo.
3. Depois que todas as réplicas tiverem reiniciado, remova o certificado antigo do IdP.

Requisições ao IdP por um proxy de encaminhamento

Os upstreams de inferência respeitam HTTPS_PROXY e HTTP_PROXY em todas as versões. As próprias requisições do gateway ao IdP, de descoberta, JWKS, token e userinfo, vão diretamente, a menos que você defina oidc.use_proxy: true, o que requer v2.1.227 ou posterior. Quando uma variável de proxy está definida, use_proxy não está definido e o emissor não está coberto por NO_PROXY, o gateway mantém essas requisições diretas e registra um aviso na inicialização pedindo que você escolha; use_proxy: false as mantém diretas e silencia o aviso.

Com use_proxy: true, o pod resolve ele mesmo o hostname de cada endpoint do IdP e pede ao proxy que faça CONNECT ao endereço IP resolvido, então o proxy deve aceitar CONNECT ao endereço IP de todos os hosts que o documento de descoberta nomeia, não apenas ao do emissor. Use uma URL de proxy http://. ca_cert_pem e a proteção contra SSRF também se aplicam ao caminho via proxy.

A saída somente por proxy muda ambos os pontos: enquanto ela está ativa, as requisições ao IdP seguem o proxy, a menos que você defina use_proxy: false, e o gateway entrega ao proxy cada hostname do IdP sem resolvê-lo antes.

Saída somente por 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 somente por esse proxy de encaminhamento e não consegue resolver nomes DNS públicos por conta própria, ou quando o proxy recusa CONNECT a um endereço IP. Requer v2.1.277 ou posterior. É uma variável de ambiente em vez de uma chave do gateway.yaml para que nada no arquivo de configuração possa relaxar a verificação de endereços do gateway.

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 a saída somente por proxy está ativa.

Cada linha abaixo é uma classe de requisição de saída em um gateway com HTTPS_PROXY definido, por padrão e enquanto a saída somente por proxy está ativa.

A saída somente por proxy permanece desativada, a menos que o ambiente do gateway atenda a todas estas três condições:

• HTTPS_PROXY ou HTTP_PROXY está definido.
• NO_PROXY e no_proxy estão vazios. Se sua plataforma injeta qualquer um deles nos pods, defina ambos com um valor vazio no contêiner do gateway. Listar um coletor de telemetria em NO_PROXY mantém a saída somente por proxy desativada.
• CLAUDE_GATEWAY_ALLOW_LOOPBACK não está ativado. Um coletor ou IdP no próprio loopback do pod não pode ser combinado com a saída somente por proxy, porque um endereço de loopback entregue ao proxy seria o do próprio host do proxy; então dê a esses serviços um endereço que o proxy consiga alcançar. Pelo mesmo motivo, o gateway recusa de imediato nomes no estilo localhost enquanto a saída somente por proxy está ativa.

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.

Depois que a saída somente por proxy estiver ativa, permita no proxy todos os destinos, incluindo um coletor interno e qualquer host configurado por endereço IP. Você ainda pode manter um IdP interno direto com oidc.use_proxy: false.

[!WARNING]

Ative isto somente quando a allowlist do proxy for pelo menos tão estrita quanto a própria verificação do gateway. O proxy deve recusar endpoints de metadados de nuvem como 169.254.169.254 e metadata.google.internal, endereços link-local e o próprio loopback do host do proxy, e deve recusá-los pelo endereço para o qual um nome é resolvido, não apenas pelo nome, porque o gateway não detecta mais um hostname que resolve para um deles. Um proxy que se conecta a qualquer lugar solicitado remove a proteção contra SSRF do gateway para essas requisições.

session

O bloco session define os bearer tokens que o gateway emite após o login: o segredo que os assina e por quanto tempo eles duram.

store

O bloco store aponta o gateway para seu banco de dados PostgreSQL, que armazena os device grants e os 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 a inferência para o primeiro upstream que resolve o modelo solicitado, ignorando qualquer upstream cuja lista groups deixe o desenvolvedor de fora.

Em 5xx, 429, 401, 403, 404 ou timeout, o gateway faz failover para o próximo upstream; outros 4xx não, porque esses erros são atribuíveis à requisição e não ao upstream. Um 401 ou 403 significa que o upstream rejeitou a credencial que o gateway usou ou negou acesso a ela, por exemplo ao modelo solicitado. Um 404 significa que esse upstream não serve o modelo solicitado, então um upstream posterior na lista ainda pode servi-lo.

Se você definir forward_user_identity: true em um upstream, um 429 que ele retorna para uma requisição que carregava o e-mail do desenvolvedor não faz failover. Consulte como uma negação de limite por usuário chega ao desenvolvedor.

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

Vários upstreams do mesmo provedor devem definir um name: distinto.

Os clientes de Amazon Bedrock, Claude Platform on AWS, Agent Platform do Google Cloud e Microsoft Foundry são criados uma vez na inicialização, e seus SDKs renovam as credenciais internamente, então rotacionar credenciais de nuvem não exige reinicialização. Chaves de API e bearers estáticos da Anthropic são lidos na inicialização; consulte Anthropic API.

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 faz failover: a resposta desse upstream. O gateway não tenta mais nenhum upstream.
• Todos os upstreams que o gateway tentou falharam de uma forma em que ele faz failover: o último 429. Quando nenhum retornou um 429, o gateway prefere, nesta ordem, o último 401 ou 403, o último 404 e o último 501. Quando nenhum retornou nenhum desses, o próprio 502 do gateway, all upstreams failed (N attempted). N conta suas entradas de upstreams, incluindo as ignoradas, menos aquelas cuja lista groups deixa o desenvolvedor de fora.

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 Anthropic API chega ao desenvolvedor inalterado.

Os upstreams Amazon Bedrock, Claude Platform on AWS, Agent Platform do Google Cloud e Microsoft Foundry podem citar seus IDs de conta, ARNs de role e IDs de projeto no texto de erro. O gateway registra esse texto completo no log operacional. O que o desenvolvedor vê desses upstreams depende da rejeição:

• 400 ou 413 no envelope de erro padrão da Anthropic: a própria mensagem do upstream, como prompt is too long. Claude Platform on AWS, Agent Platform e Microsoft Foundry retornam esse envelope para rejeições da API do modelo.
• 400 ou 413 no formato próprio do provedor: um token capability_rejected:. Quando o gateway não consegue classificar a rejeição, upstream rejected the request em um 400 ou request too large for this upstream em um 413.
• Qualquer outro status: texto genérico 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. O Claude Code compacta automaticamente com esse token, como faz com 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 mínimo da Anthropic é uma chave de API do Claude Console:

upstreams:
  - provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}
    # OR an OAuth bearer (e.g. a Workload-Identity-Federation-exchanged token):
    #   oauth_token: ${file:/var/run/secrets/anthropic-oauth-token}
    # base_url: https://api.anthropic.com   # default; override for a forward proxy

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

• api_key: envia x-api-key. Rotacione-a no Claude Console e atualize a variável de ambiente.
• oauth_token: envia Authorization: Bearer. Use a forma bearer quando sua organização emite tokens de curta duração em vez de chaves de API de longa duração. O bearer é lido uma vez na inicialização, então renove-o remontando o segredo e reiniciando.

Em vez de uma chave ou bearer estático, você pode usar o Workload Identity Federation. Crie uma regra de federação seguindo o guia do Workload Identity Federation e depois monte o JWT OIDC da sua carga de trabalho como um arquivo, como um token projetado de conta de serviço do Kubernetes ou o id-token de uma plataforma de CI. O gateway troca o JWT por um bearer de curta duração e o renova automaticamente. O arquivo de token é relido a cada troca, então tokens projetados rotacionados são captados sem reinicialização.

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_...       # required if the rule covers >1 workspace
      # service_account_id: svac_...   # optional expected-target check

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 da Anthropic API. Para informar a esse proxy qual desenvolvedor enviou cada requisição, defina forward_user_identity: true nesse upstream. O proxy pode então atribuir o gasto por desenvolvedor. Requer um gateway executando Claude Code v2.1.233 ou posterior.

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        # default false

O gateway adiciona estes cabeçalhos a toda requisição que encaminha a esse upstream.

Quando o token do IdP não carrega e-mail, o gateway envia apenas x-claude-gateway-user-id e omite os dois cabeçalhos de e-mail. Se seu IdP coloca o e-mail em uma claim diferente, defina oidc.email_claim como essa claim.

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, então agrupe as requisições por desenvolvedor com os cabeçalhos da tabela acima.

Quando seu proxy responde 429 a uma requisição que carregava o e-mail do desenvolvedor, o gateway retorna essa resposta ao desenvolvedor como está, em vez de fazer failover para o próximo upstream, para que o orçamento ou rate limit por usuário do seu proxy seja mantido. As outras respostas do proxy seguem as regras de failover comuns. Se o token do IdP de um desenvolvedor não carrega e-mail, o gateway encaminha as requisições dele sem os cabeçalhos de e-mail, então um 429 para uma dessas requisições conta como capacidade do upstream e faz failover. Antes da v2.1.267 no servidor do gateway, todo 429 fazia failover.

Defina forward_user_identity somente em um upstream cujo base_url seja um proxy que você opera. O gateway envia os e-mails dos desenvolvedores para qualquer servidor que esse base_url nomeie. Se o base_url for a Anthropic API, que é o padrão, o gateway se recusa a iniciar.

[!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 seu proxy fica à frente do Bedrock, liste-o como um upstream provider: anthropic. O gateway envia a esse upstream o formato Anthropic Messages, então seu proxy precisa traduzir as requisições para o Bedrock. Para identificar cada desenvolvedor para a AWS, consulte Atribuição de custos da AWS por desenvolvedor.

Amazon Bedrock

Para a implantação do Amazon Bedrock do lado do cliente que o gateway substitui ou intermedeia, consulte Claude Code no Amazon Bedrock. O upstream do lado do gateway:

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}                           # preferred: AWS default credential chain
    # OR explicit credentials:
    # auth:
    #   aws_access_key_id: ${AWS_AKID}
    #   aws_secret_access_key: ${AWS_SK}
    #   aws_session_token: ${AWS_ST}
    # OR a Bedrock API bearer token:
    # auth:
    #   aws_bearer_token: ${AWS_BEARER_TOKEN}
    # Override the bedrock-runtime endpoint for FIPS or VPC-endpoint deployments:
    # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com

Um bloco auth vazio usa a cadeia de credenciais padrão do AWS SDK: variáveis de ambiente, ~/.aws/credentials, task role do ECS, metadados de instância do EC2 ou IRSA no EKS. Em produção, dê ao pod do gateway uma role do IAM em vez de embutir chaves estáticas em uma imagem de contêiner.

Credenciais explícitas devem estar completas: o gateway falha na inicialização quando aws_access_key_id e aws_secret_access_key não são definidos juntos, ou quando aws_session_token é definido sem eles. Antes da v2.1.207, um bloco auth: parcial passava na validação.

Aplicar um guardrail do Amazon Bedrock

Para aplicar um guardrail do Amazon Bedrock a toda requisição de inferência que o gateway envia por um upstream Bedrock, adicione um bloco guardrail a esse upstream. Requer Claude Code v2.1.281 ou posterior no servidor do gateway.

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}
    guardrail:
      id: gr-abc123                    # guardrail ID or full ARN
      version: "1"                     # a published version number, or DRAFT
 # keep the quotes: a bare 1 fails at boot

Conceda também bedrock:ApplyGuardrail no guardrail ao principal que assina as requisições desse upstream: o principal da AWS do gateway ou, com assume_role, a role 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 sem 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 com guardrail definido, o gateway responde 400 em vez de encaminhá-la.

[!WARNING]

Por padrão, o gateway não adiciona tags de entrada aos prompts, então um filtro de guardrail que o Amazon Bedrock aplica apenas a entradas com tags não é executado no tráfego que passa pelo gateway. Para adicionar as tags, defina input_tagging. Para saber quais filtros dependem de tags de entrada, consulte tags de entrada na documentação do Amazon Bedrock.

Adicionar tags de entrada do guardrail

Para que o gateway adicione as tags de entrada de que o filtro de ataques de prompt de um guardrail do Amazon Bedrock precisa, defina input_tagging no bloco guardrail e reinicie o gateway. Defina o mesmo valor em todos os upstreams bedrock, ou o gateway se recusa a iniciar. Requer Claude Code v2.1.316 ou posterior no servidor do gateway. Um gateway em uma versão que não tem a chave encerra na inicialização com Unrecognized key(s) in object: 'input_tagging'.

[!WARNING]

De acordo com a documentação do Amazon Bedrock, todos os filtros do guardrail param de avaliar conteúdo sem tags quando uma requisição carrega tags de entrada. Teste input_tagging em um gateway de teste antes de defini-lo em um que os desenvolvedores usam.

input_tagging aceita um destes valores:

Com last_message, se as mensagens user desde a última resposta do Claude não contiverem texto a marcar, o gateway marca as mensagens de sistema no meio da conversa desde essa resposta. Uma chamada de ferramenta conta como resposta.

A orientação do Amazon Bedrock para o filtro de ataques de prompt é marcar a entrada do usuário de modo que o system prompt fique excluído. Se você definir all_messages_and_system, um filtro que sinalize o próprio system prompt do Claude Code pode bloquear requisições.

O exemplo abaixo marca o texto em todas as mensagens user:

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}
    guardrail:
      id: gr-abc123
      version: "1"
      input_tagging: user_messages

Mensagens user também podem conter texto que o Claude Code adiciona, como lembretes do sistema, então verifique no gateway de teste se requisições comuns não são bloqueadas.

Nos testes da Anthropic, uma sessão com tags manteve suas leituras do cache de prompt de um prompt para o seguinte, e as tags não adicionaram tokens de entrada.

O que as tags de entrada não cobrem

Nenhum valor de input_tagging impede um desenvolvedor que deliberadamente coloca texto onde nenhuma tag vai. Não conte com o guardrail para avaliar estas partes de uma requisição:

• Conteúdo que o gateway não marca: mensagens que seu valor de input_tagging deixa de fora, definições de ferramentas, entradas de chamadas de ferramenta, imagens e PDFs, entre outros. A menos que você defina all_messages_and_system, o system prompt também fica sem tags.
• Resultados de ferramentas: contêm o que as ferramentas do Claude retornam, como conteúdo de arquivos e páginas da web. Nos testes da Anthropic, um filtro de palavras não os avaliou, com ou sem tags.

Se sua conta ou organização da AWS impõe um guardrail, consulte a documentação do Amazon Bedrock para saber como esse guardrail trata tags de entrada.

Registrar qual filtro do guardrail foi acionado

Para descobrir qual filtro do guardrail do Amazon Bedrock bloqueou a requisição de um desenvolvedor, defina guardrail_trace: true no upstream Bedrock, reinicie o gateway e peça ao desenvolvedor que envie a requisição novamente. Em seguida, encontre o evento guardrail.trace da requisição no log de auditoria. Requer Claude Code v2.1.314 ou posterior no servidor do gateway. Um gateway anterior se recusa a iniciar quando encontra guardrail_trace.

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}
    guardrail:
      id: gr-abc123
      version: "1"
    guardrail_trace: true              # default false; beside guardrail, not inside it

O gateway grava um evento guardrail.trace, sem o texto correspondente, quando um filtro é acionado ou a ação do guardrail é INTERVENED. Encontre os eventos do desenvolvedor por email ou sub. Uma requisição com streaming pode produzir vários eventos, e um deles pode ter uma lista filters vazia, então leia todos os eventos que têm o mesmo request_id:

O evento omite o texto que um filtro encontrou, incluindo o campo match do trace do Bedrock. Os desenvolvedores não recebem os dados de trace do Bedrock, porque o gateway os remove de cada resposta, com ou sem streaming.

Se um cliente enviar um campo amazon-bedrock-* no corpo de uma requisição /v1/messages, o gateway responde 400 em um upstream que define guardrail_trace.

Bedrock em outra conta da AWS

Defina assume_role em um upstream Bedrock e o gateway usa sua própria identidade da AWS apenas para chamar sts:AssumeRole em uma role que você nomeia, que pode estar em uma conta da AWS diferente da do gateway. Toda requisição ao Bedrock desse upstream é assinada com as credenciais de uma hora que o STS retorna, então nenhuma chave de acesso de longa duração atravessa contas.

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: {}                           # the gateway's own role: it only calls STS
    assume_role:
      role_arn: arn:aws:iam::222222222222:role/claude-gateway-bedrock
      # external_id: ${BEDROCK_ROLE_EXTERNAL_ID}   # when the role's trust policy requires one

O bloco assume_role aceita três chaves:

A política de confiança da role nomeia o próprio principal do gateway, como sua role IRSA ou task role do ECS. Esse principal precisa de sts:AssumeRole na role e de nenhuma permissão própria do Bedrock. Remova a Condition se você não definir external_id.

{
  "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 explica o que o cliente recebe quando nenhum upstream tem sucesso. Um upstream posterior sem assume_role serviria a requisição com suas próprias credenciais, então liste um somente se for isso o que você deseja.
• O gateway chama o endpoint regional do STS sts.<region>.amazonaws.com, que sua rede deve alcançar. Para o endpoint FIPS, defina AWS_USE_FIPS_ENDPOINT=true no ambiente do gateway, em vez de use_fips_endpoint em um arquivo de configuração da AWS.
• assume_role precisa de credenciais de origem SigV4: o gateway se recusa a iniciar quando ele é definido junto com aws_bearer_token.
• Sem uma lista groups, todo desenvolvedor que o gateway admite pode usar este upstream. Para limitar quais modelos um desenvolvedor pode usar, defina availableModels em uma política managed.
• Para evitar que um modelo servido pelo papel também seja servido por outra conta, dê a ele um id personalizado cujo mapa upstream_model tenha apenas o nome deste upstream. Para esse id, o gateway ignora todos os outros upstreams, então nem a requisição nem a contagem de tokens de uma requisição abortada podem fazer failover para outra conta.
• Uma requisição para um nome de modelo integrado ainda pode chegar a este upstream, e o gateway a assina com o mesmo papel. Liste este upstream por último, a menos que a conta dele também deva servir esses modelos.

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

models:
  - id: restricted-claude-opus-4-8      # a custom id, not a built-in model name
    upstream_model:
      bedrock-isolated: us.anthropic.claude-opus-4-8   # the only upstream that serves it

Atribuição de custos da AWS por desenvolvedor

Por padrão, o gateway assina toda requisição ao Bedrock com uma única credencial, então a AWS vê as requisições de todos os desenvolvedores sob um único principal do IAM. Adicione session_name: email a assume_role e o gateway chama sts:AssumeRole uma vez por desenvolvedor por hora, com o nome da sessão definido como o e-mail desse desenvolvedor, e assina as requisições dele com as credenciais retornadas, de modo que as requisições de cada desenvolvedor chegam à AWS sob sua própria sessão de role assumida. A role pode estar na própria conta do gateway.

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

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}                           # the gateway's own role: it only calls STS
    assume_role:
      role_arn: arn:aws:iam::123456789012:role/claude-gateway-bedrock-user
      session_name: email              # or sub

session_name seleciona qual claim verificada se torna o RoleSessionName da AWS: email ou sub. O gateway escreve qualquer caractere que não seja letra ASCII, dígito ou _+,.@- como =XX em hexadecimal por byte UTF-8, e encurta um resultado com mais de 64 caracteres para um prefixo mais um hash, de modo que o nome de sessão de cada desenvolvedor permaneça válido e único. Uma requisição de um desenvolvedor cujo token não tem a claim não é enviada por este upstream, e o log do operador diz para mudar para sub ou definir oidc.email_claim.

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

O gateway também faz uma chamada própria nesta role: a contagem de tokens de uma requisição que o cliente abandonou, para que os limites de gasto permaneçam precisos. Essa contagem e sua requisição de fallback de um token são assinadas pela sessão compartilhada claude-apps-gateway, então a AWS atribui o fallback a claude-apps-gateway em vez de ao desenvolvedor.

Para uma atribuição estrita por desenvolvedor, defina assume_role com session_name em todos os upstreams Bedrock que você listar. Um upstream sem isso assina as requisições que serve com suas próprias credenciais.

Endpoint Mantle do Amazon Bedrock

O provedor mantle envia a inferência ao endpoint Mantle do Amazon Bedrock. Ele requer Claude Code v2.1.283 ou posterior no servidor do gateway. Versões anteriores do gateway o rejeitam na inicialização, então atualize todas as réplicas antes de adicioná-lo.

O exemplo abaixo coloca o Mantle primeiro, com um upstream Amazon Bedrock atrás dele para servir todos os modelos que o campo models deixa de fora:

upstreams:
  - provider: mantle
    region: us-east-1
    models: [claude-opus-4-7, claude-haiku-4-5]   # required
    auth: {}                           # AWS default credential chain
  - provider: bedrock
    region: us-east-1
    auth: {}

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

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

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. Depois, 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, então se recusa a iniciar quando um upstream mantle está listado enquanto algum upstream bedrock define guardrail.
• assume_role: defina-o no próprio upstream mantle. Sem ele, as requisições que o Mantle serve são enviadas com as credenciais auth próprias do upstream mantle.

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

Claude Platform on AWS

O Claude Platform on AWS serve a Anthropic API first-party na infraestrutura da AWS em aws-external-anthropic.<region>.api.aws. Ele usa IDs de modelo first-party, respeita os cabeçalhos anthropic-beta como enviados e serve count_tokens, então nenhuma das traduções específicas do Bedrock se aplica. O provedor anthropicAws requer Claude Code v2.1.198 ou posterior; versões anteriores do gateway o rejeitam na inicialização.

Para a implantação do lado do cliente da mesma plataforma, consulte Claude Code no 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}   # sent as x-api-key
    # OR SigV4 via the AWS default credential chain:
    # auth: {}
    # OR explicit SigV4 credentials:
    # auth:
    #   aws_access_key_id: ${AWS_ACCESS_KEY_ID}
    #   aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}
    # Override the derived endpoint:
    # base_url: https://aws-external-anthropic.us-east-1.api.aws

A plataforma é executada em uma conta da AWS separada do Amazon Bedrock e assina requisições SigV4 para seu próprio nome de serviço, aws-external-anthropic, então uma role do IAM com escopo do Bedrock não a autoriza. Uma chave de API em auth.api_key tem precedência quando credenciais SigV4 também estão definidas. Um bloco auth vazio usa a cadeia de credenciais padrão do AWS SDK, a mesma cadeia que o upstream Amazon Bedrock usa.

Como a plataforma resolve IDs de modelo first-party, o catálogo integrado roteia para ela sem nenhum bloco models:. Ao montar uma lista models: própria, use a chave anthropicAws: na entrada com o ID first-party.

Google Cloud Agent Platform

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

upstreams:
  - provider: vertex
    region: us-east5
    project_id: example-prod
    auth: {}                           # preferred: Application Default Credentials
    # OR a service account key file:
    # auth: { service_account_json: /secrets/sa.json }
    # Override the aiplatform endpoint for Private Service Connect:
    # base_url: https://us-east5-aiplatform.p.googleapis.com

Um bloco auth vazio usa o Application Default Credentials: GOOGLE_APPLICATION_CREDENTIALS, metadados do GCE ou GKE Workload Identity. Arquivos de chave JSON de conta de serviço são compatíveis, mas desaconselhados; use o Workload Identity ou anexe uma conta de serviço à instância do GCE ou do Cloud Run.

Defina region: global para usar o endpoint global da Agent Platform do Google Cloud em vez de um regional. O Google então roteia cada requisição para uma região disponível, então você não precisa acompanhar a disponibilidade de modelos por região. Definir uma região específica fixa todas as requisições nela.

Microsoft Foundry

Para a implantação do Microsoft Foundry do lado do cliente, consulte Claude Code no 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 }        # preferred: DefaultAzureCredential / Managed Identity
    # OR an API key:
    # auth:
    #   api_key: ${FOUNDRY_API_KEY}

use_azure_ad: true resolve por meio de DefaultAzureCredential: Managed Identity no AKS, ACI ou App Service; a Azure CLI; ou credenciais de ambiente. Chaves de API funcionam, mas valem para o projeto inteiro e não são rotacionadas automaticamente. O endpoint do Microsoft Foundry é derivado de resource:; defina o base_url opcional para sobrescrevê-lo em nuvens soberanas como o Azure Government.

Cabeçalhos estáticos nas requisições ao upstream

Para adicionar cabeçalhos fixos às requisições que o gateway envia a um upstream, defina headers: nesse upstream. Use isso quando um proxy que você executa à frente do provedor roteia ou atribui tráfego por um cabeçalho.

headers: requer Claude Code v2.1.277 ou posterior no servidor do gateway. Um gateway anterior se recusa a iniciar quando encontra a chave. Atualize todas as réplicas antes de adicionar a chave e remova a chave antes de reverter para uma versão anterior.

Os cabeçalhos vão para o servidor que base_url nomeia, ou para o próprio endpoint do provedor quando base_url não está definido. O provedor também os recebe, a menos que seu proxy os remova.

Este exemplo alcança um upstream provider: vertex por meio de um proxy em upstream-proxy.internal.example.com. Ele define o cabeçalho x-source que o proxy lê e envia um token da variável de ambiente PROXY_TOKEN como x-proxy-token:

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 das extremidades. Coloque entre aspas um número, true ou false para que o YAML o leia como texto.

Para manter um segredo fora do arquivo de configuração, use a expansão de segredos 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 todos os provedores, e cada upstream envia apenas os seus.

Nem toda requisição que o gateway envia a um upstream os carrega:

Em um upstream Amazon Bedrock ou Claude Platform on AWS que assina requisições com AWS SigV4, esses cabeçalhos fazem parte da assinatura, então seu proxy deve repassá-los inalterados.

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 que comece com anthropic-, x-goog-, x-amz- ou x-amzn-

Vários upstreams

O mesmo provedor pode aparecer mais de uma vez com um name: distinto. Isso cobre regiões diferentes, contas diferentes por meio de cadeias de credenciais diferentes, provisioned throughput versus sob demanda e fallback entre provedores.

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

429 é capacidade por upstream, então o esgotamento do provisioned throughput (PT) faz failover para o sob demanda. Se você definir forward_user_identity: true em um upstream, um 429 para uma requisição que carregava o e-mail do desenvolvedor é, em vez disso, uma negação por usuário e não faz failover.

Uma requisição passa de um upstream para o próximo apenas nestes casos:

• O upstream falhou
• O upstream não atende o modelo solicitado
• O upstream tem uma lista groups que deixa o desenvolvedor de fora

O gateway não mantém registro de upstreams com falha, então, enquanto um upstream está fora do ar, toda requisição que chega a ele ainda o tenta e espera que ele falhe antes de seguir adiante.

O gateway espera 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 com streaming, defina timeouts.upstream_ttfb_ms no gateway v2.1.295 ou posterior. Requisições de modelo sem streaming esperam até uma hora de qualquer forma

404 é disponibilidade de modelo por upstream, então um upstream que não ativou um modelo não bloqueia um upstream posterior que o serve. Um upstream que não consegue resolver o modelo solicitado é pulado sem uma ida e volta pela rede.

Este exemplo roteia primeiro uma cota de provisioned throughput do Amazon Bedrock, transborda para o sob demanda e para uma segunda conta e recorre à Anthropic API por último:

upstreams:
  # Primary: provisioned throughput in your home region.
  - name: bedrock-pt
    provider: bedrock
    region: us-east-1
    auth: {}
  # Overflow: on-demand cross-region.
  - name: bedrock-od
    provider: bedrock
    region: us-west-2
    auth: {}
  # Different account: a separate Bedrock allotment via static keys.
  - name: bedrock-acct2
    provider: bedrock
    region: us-east-1
    auth:
      aws_access_key_id: ${ACCT2_AKID}
      aws_secret_access_key: ${ACCT2_SK}
  # Last resort: direct Anthropic API.
  - name: anthropic-fallback
    provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}

# Per-upstream model IDs are keyed on the upstream's `name:`.
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

Fazer failover entre provedores de nuvem, ou para a API direta da Anthropic, altera qual contrato, geografia e outros termos regem a requisição.

A CLI aplica o mesmo controle de recursos aos gateways independentemente de qual upstream atende a uma determinada requisição, portanto, por padrão, o failover não envia um campo do corpo que um upstream rejeitaria. Se você definir o TTL de cache de uma hora em uma política, ele será enviado para todos os upstreams da lista, então defina-o somente se todos eles o aceitarem.

Enviar cada equipe para seu próprio upstream

Para enviar as requisições de cada equipe para sua própria conta AWS ou projeto do Google Cloud, liste um upstream por equipe e dê a cada um uma lista groups. Apenas desenvolvedores em um grupo do IdP listado alcançam esse upstream, na primeira tentativa e no failover. Todo provedor aceita groups. Requer Claude Code v2.1.314 ou posterior no servidor do gateway.

Este exemplo dá aos grupos payments-eng e search-eng uma conta AWS cada, e adiciona um upstream sem lista groups que todo desenvolvedor pode usar:

upstreams:
  - name: bedrock-payments
    provider: bedrock
    region: us-east-1
    auth: {}
    assume_role:
      role_arn: arn:aws:iam::111111111111:role/claude-gateway-bedrock
    groups: [payments-eng]
  - name: bedrock-search
    provider: bedrock
    region: us-east-1
    auth: {}
    assume_role:
      role_arn: arn:aws:iam::222222222222:role/claude-gateway-bedrock
    groups: [search-eng]
  - name: bedrock-shared               # no groups: open to everyone, so listed last
    provider: bedrock
    region: us-east-1
    auth: {}

Com a configuração de exemplo, as requisições de cada desenvolvedor começam no primeiro upstream de sua linha e passam para o próximo no failover:

Quando o upstream de uma equipe nega o modelo solicitado com um 403, o gateway tenta o próximo upstream na linha dessa equipe que atende o modelo. Para manter a equipe em um único upstream, dê a todos os upstreams uma lista groups e certifique-se de que nenhum outro upstream liste um grupo em que os desenvolvedores da equipe estejam. Essa equipe então não tem failover, e requisições de desenvolvedores que não estão em nenhum grupo listado falham com um 400.

Para levar cada desenvolvedor ao upstream que você pretende, escreva entradas que correspondam exatamente e coloque os upstreams abertos por último:

• Entradas: escreva cada grupo exatamente como seu IdP o envia na claim de grupos, que match.groups também lê. O gateway se recusa a iniciar quando encontra uma lista vazia ou uma entrada vazia. Ele não verifica uma entrada em relação ao seu IdP, então uma entrada que não corresponde a ninguém não gera nenhum aviso.
• Ordem: coloque um upstream que não tenha lista groups por último. Ele atende a todos, então, se listado antes, ele captura as requisições de uma equipe antes do próprio upstream dessa equipe.

[!WARNING]

Um gateway anterior à v2.1.314 se recusa a iniciar quando encontra groups, então atualize todas as réplicas antes de adicioná-lo.

Antes de reverter, remova cada upstream que tenha uma lista groups e toda chave upstream_model ou substituição de preços que o nomeie, e mantenha pelo menos um upstream. Com apenas a chave groups removida, esse upstream fica aberto a todos os desenvolvedores. Uma chave ou substituição que ainda nomeie um upstream removido impede o gateway de iniciar, com references unknown upstream.

O que acontece quando um desenvolvedor não está em nenhum grupo listado

Se todos os upstreams tiverem uma lista groups, um desenvolvedor que não esteja em nenhum desses grupos vê este erro, e o gateway não contata nenhum provedor:

API Error: 400 you aren't in a group that can use this gateway. Ask your administrator to add you to one

Adicione o desenvolvedor a um grupo listado no seu IdP, ou adicione um upstream sem lista groups.

O gateway lê novamente os grupos de um desenvolvedor a cada atualização de token. Se o seu IdP deixar os grupos de fora de uma atualização, o desenvolvedor passa a não ter nenhum:

• oidc.allowed_groups está definido: o gateway recusa a atualização, e a sessão termina
• Caso contrário, um upstream não tem lista groups: as requisições do desenvolvedor passam para ele
• Caso contrário, todos os upstreams têm uma lista groups: as requisições do desenvolvedor falham com esse erro

Se o endpoint userinfo do seu IdP retornar a claim de grupos e oidc.google_groups não estiver definido, defina oidc.userinfo_fallback como true para preencher os grupos a partir dele.

Seções opcionais

login_notice

Para mostrar aos desenvolvedores um aviso quando eles fizerem login, defina a chave de nível superior login_notice com o texto do aviso, de até 500 caracteres. Este exemplo informa a quem o gateway se destina e onde solicitar acesso:

login_notice: This gateway is for Example Corp staff. For access questions, email it-help@example.com.

Os desenvolvedores veem o texto abaixo de Notice from <gateway hostname> na página de verificação do gateway no navegador e na tela interativa de login no terminal. Quebras de linha no texto se tornam espaços. O aviso aparece antes do login, então qualquer pessoa que consiga acessar o gateway pode lê-lo.

Requer Claude Code v2.1.319 ou posterior no servidor do gateway e também na máquina do desenvolvedor para a tela do terminal. 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.

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
  # Try eng-platform's pooled budget first, then eng-all's, then any other group's.
  pooled_conflict_rule: priority_list
  pooled_priority_order: [eng-platform, eng-all]

Ordem dos orçamentos compartilhados

Um orçamento compartilhado é um limite mensal contra o qual um grupo inteiro gasta. Para definir um, adicione pooled_budget à requisição que define o limite mensal do grupo, como em "pooled_budget": {"amount": "500000"} para $5.000. A requisição também recebe o scope do grupo, "period": "monthly" e amount, que continua sendo o limite individual de cada membro.

Para um desenvolvedor em vários desses grupos, cada requisição é contabilizada no primeiro orçamento cujo gasto esteja abaixo do limite, e é recusada quando todos os orçamentos estão esgotados. pooled_conflict_rule define a ordem em que o gateway tenta os orçamentos:

• default_order: o maior limite primeiro, e limites iguais em ordem crescente de nome de grupo
• priority_list: os orçamentos dos grupos em pooled_priority_order, na ordem da lista, depois os orçamentos dos outros grupos por nome de grupo

Se você listar grupos sem pooled_conflict_rule: priority_list, o gateway ignora a lista e registra um aviso em log na inicialização.

Um servidor do gateway anterior à v2.1.319 se recusa a iniciar quando encontra pooled_conflict_rule ou pooled_priority_order. Atualize todas as réplicas antes de adicionar qualquer uma das chaves e remova ambas as chaves antes de reverter para uma versão anterior.

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 ele serve, como a configuração gerenciada modelPricing.

Os desenvolvedores correspondidos por uma política passam a ver as tarifas de pricing em /usage, na linha de status e no OpenTelemetry. Um desenvolvedor que não corresponde a nenhuma política não recebe configurações gerenciadas, então seus números permanecem no preço de tabela. Os clientes aplicam a configuração no Claude Code v2.1.242 ou posterior.

• 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.
• Upstreams com uma lista groups: quando um deles é o primeiro upstream que atende um ID de modelo, o gateway não adiciona nenhuma linha para esse ID. Os desenvolvedores então veem a tarifa do próprio Claude Code para esse ID, que é a tarifa padrão do modelo quando o Claude Code reconhece o ID, vezes o multiplier.
• 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 email. As políticas são avaliadas em ordem; por padrão, a primeira correspondência é selecionada e depois mesclada sobre a base genérica match: {}. Um usuário que corresponde a duas políticas de função recebe apenas a primeira, então as regras de negação da segunda política não se aplicam, a menos que você aplique todas as políticas correspondentes. As políticas 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.

Coloque as regras de negação de toda a organização na política match: {}, porque as regras de uma política de grupo só se aplicam enquanto o token do usuário contiver esse grupo.

[!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.

Aplicar todas as políticas correspondentes

Um usuário que corresponde a várias políticas de função recebe apenas a primeira, a menos que você defina policy_mode: layered ao lado de policies. Com layered, todas as políticas que correspondem ao usuário se aplicam, até a primeira política match: {}.

policy_mode requer o Claude Code v2.1.316 ou posterior no servidor do gateway. Um gateway em uma versão que não o suporta se recusa a iniciar quando encontra a chave. Atualize todas as réplicas antes de adicionar a chave e remova a chave antes de reverter para uma versão anterior. Este exemplo tem um grupo que perde WebFetch e um que ganha o Opus:

managed:
  policy_mode: layered
  policies:
    - match: { groups: [no-web] }
      cli:
        permissions: { deny: ["WebFetch"] }
    - match: { groups: [opus-users] }
      cli:
        availableModels: [opus, sonnet]
    - match: {}
      cli:
        availableModels: [sonnet]
        enforceAvailableModels: true

A tabela mostra o que um usuário em no-web e opus-users recebe com o padrão, first_match, e com layered.

O gateway mescla cada política correspondente sobre as listadas abaixo dela, pelas mesmas regras de mesclagem da camada base:

• Allowlists, valores únicos e blocos como sandbox: cada um vem inteiro da primeira política correspondente listada que o define, então as listas availableModels de dois grupos não se somam.
• Listas de negação e arrays de hooks: estes se somam entre todas as políticas correspondentes, então um usuário em dois grupos recebe as regras de negação de ambos os grupos.
• env, modelOverrides e skillOverrides: as entradas são mescladas por nome, e a primeira política correspondente listada que define um nome fornece seu valor.
• Chaves de desktop: estas são mescladas pelas regras do bloco desktop base.

[!WARNING]

As políticas podem se somar em regras mais permissivas do que qualquer uma delas sozinha. Por exemplo, a política match: {} define sandbox.enabled: true, a política de um grupo define permissions.allow: ["Bash"] e a de outro grupo define sandbox.enabled: false. Um usuário em ambos os grupos recebe Bash permitido com o sandbox desativado. Nesse caso, liste primeiro a política que permite Bash e copie para ela o bloco sandbox inteiro da política match: {}.

Com layered, o gateway se recusa a iniciar com algumas configurações, incluindo estas:

• Um padrão !: uma negação ! em uma regra Read ou Edit na lista permissions.deny ou permissions.ask de qualquer política, incluindo a da política match: {}
• Um limite sobre hooks fora da genérica: disableAllHooks, allowedHttpHookUrls ou httpHookAllowedEnvVars em qualquer política que não seja match: {}

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.

Se o intermediário pertence a listen.trusted_proxies, liste-o ali. De qualquer forma, mantenha o gateway e tudo o que está à frente dele inacessíveis pela 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 neste modo abrange o gateway, seu Postgres e tudo o que estiver na frente do gateway. Ele não abrange os limites, a velocidade e o caminho de rede do provedor, nem a espera no limite de requisições upstream simultâneas de cada réplica. Uma réplica ainda registra em log o aviso client requests are open quando há mais requisições abertas do que esse limite, o ponto em que as requisições de produção começam a esperar.

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.
# Defina CLAUDE_GATEWAY_LOG_FORMAT=json para gravar as linhas do log operacional como
# objetos JSON com severity, time e message.

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

# Aviso exibido no login. Qualquer pessoa que consiga acessar o gateway pode lê-lo.
# login_notice: This gateway is for Example Corp staff. For access questions, email it-help@example.com.

# 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
#   # pooled_conflict_rule: priority_list
#   # pooled_priority_order: [eng-platform, eng-all]

# 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