Configuração do gateway de aplicativos Claude

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

Uma implantação de gateway de aplicativos Claude é configurada por um arquivo YAML, convencionalmente gateway.yaml. O arquivo define tudo o que o gateway faz: onde ele escuta, como os desenvolvedores fazem login, para onde a inferência vai e quais políticas e telemetria se aplicam. Esta página é a referência para cada opção nesse arquivo.

Para escrever o seu primeiro, comece pelo quickstart, que constrói uma configuração mínima funcional e a executa. Uma vez que você tenha uma configuração com a qual esteja satisfeito, o guia de implantação cobre a containerização e hospedagem no Kubernetes, Cloud Run ou sua própria plataforma.

O gateway lê o arquivo uma vez, na inicialização, com claude gateway --config /path/to/gateway.yaml. Cada opção é validada contra um esquema na inicialização, portanto uma configuração malformada falha no início com um erro no nível do campo em vez de no primeiro uso.

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

Estrutura do arquivo

Cinco seções são obrigatórias. Todas as outras seções são opcionais, e uma seção omitida assume seus padrões. Chaves desconhecidas falham na inicialização, portanto um erro de digitação aparece como um erro nomeado em vez de uma configuração silenciosamente ignorada.

Seções obrigatórias:

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

Seções opcionais:

• admin: autenticação da API de administração e retenção para limites de gastos
• enforcement: comportamento de falha aberta ou fechada do limite de gastos
• pricing: taxas contratadas e um multiplicador de desconto 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

Expansão de segredos

Não escreva segredos como client_secret, jwt_secret ou postgres_url diretamente em gateway.yaml. Faça referência a eles com um dos formulários abaixo, e o gateway resolve o valor na inicialização a partir de uma variável de ambiente ou um arquivo:

Seções obrigatórias

`listen`

O bloco listen controla onde o gateway serve: o endereço de vinculação e porta, a origem visível externamente e terminação TLS opcional.

`oidc`

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

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

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

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

Com use_proxy: true, o pod resolve o nome do host de cada endpoint do IdP e pede ao proxy para CONNECT ao endereço IP resolvido, portanto o proxy deve aceitar CONNECT ao endereço IP de cada host que o documento de descoberta nomeia, não apenas o emissor. Use uma URL de proxy http://. ca_cert_pem e a proteção SSRF se aplicam no caminho proxied também.

`session`

O bloco session molda os tokens de portador que o gateway emite após o login: o segredo que os assina e quanto tempo eles vivem.

`store`

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

Para desenvolvimento local, aponte postgres_url para um contêiner Postgres descartável, por exemplo docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres.

`upstreams`

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

Em 5xx, 429, 401, 403, 404 ou timeout, o gateway falha para o próximo upstream; outro 4xx não, porque esses erros são atribuíveis à solicitação em vez do upstream. Um 401 ou 403 significa que a credencial do próprio gateway falhou contra esse upstream. Um 404 significa que esse upstream não serve o modelo solicitado, portanto um upstream posterior na lista ainda pode.

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

Failover em 404 requer gateway v2.1.198 ou posterior. Versões anteriores retornavam o primeiro 404 ao cliente mesmo quando um upstream posterior na lista servia o modelo.

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

Clientes Amazon Bedrock, Claude Platform on AWS, Agent Platform do Google Cloud e Microsoft Foundry são construídos uma vez na inicialização, e seus SDKs atualizam credenciais internamente, portanto girar credenciais de nuvem não requer reinicialização. Chaves de API Anthropic estáticas e portadores são lidos na inicialização; consulte Anthropic API.

Mensagens de erro do upstream

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

• Um upstream retornou um status no qual o gateway não falha: essa resposta do upstream. O gateway não tenta mais upstreams.
• Cada upstream que o gateway tentou falhou de uma forma na qual falha: o último 429. Quando nenhum retornou um 429, o gateway prefere, em ordem, o último 401 ou 403, o último 404 e o último 501. Quando nenhum retornou nenhum desses, o próprio 502 do gateway, all upstreams failed (N attempted), onde N conta cada entrada em upstreams, incluindo entradas que o gateway pulou porque não servem o modelo solicitado.

Quando o gateway retorna a resposta de um upstream, ele mantém o código de status do upstream. Se ele mantém a mensagem do upstream depende do provedor. O corpo de erro de um upstream da API Anthropic chega ao desenvolvedor inalterado.

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

• 400 ou 413 no envelope de erro padrão da Anthropic: a mensagem do próprio upstream, como prompt is too long. Claude Platform on AWS, Agent Platform e Microsoft Foundry retornam esse envelope para rejeições de API de modelo.
• 400 ou 413 na forma própria do provedor: um token capability_rejected:. Quando o gateway não pode classificar a rejeição, upstream rejected the request em um 400 ou request too large for this upstream em um 413.
• Qualquer outro status: cópia genérica por status, como upstream rate limit exceeded em um 429.

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

Manter a mensagem 400 ou 413 de um upstream de nuvem ou substituí-la por um token capability_rejected: requer gateway v2.1.233 ou posterior.

Anthropic API

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

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

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

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

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

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

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

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

Quando seu proxy responde 429 para uma solicitação que carregava o email do desenvolvedor, o gateway retorna essa resposta ao desenvolvedor como está em vez de falhar para o próximo upstream, portanto seu orçamento por usuário ou limite de taxa do proxy se mantém. As outras respostas do proxy seguem as regras de failover ordinárias. Se o token do IdP de um desenvolvedor não carrega email, o gateway encaminha suas solicitações sem os cabeçalhos de email, portanto um 429 para uma dessas solicitações conta como capacidade de upstream e falha. Antes da v2.1.267 no servidor gateway, cada 429 falhava.

Defina forward_user_identity apenas em um upstream cujo base_url é um proxy que você opera. O gateway envia emails de desenvolvedor para qualquer servidor que esse base_url nomeia. Se o base_url for a API Anthropic, que é o padrão, o gateway se recusa a iniciar.

Amazon Bedrock

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

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

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

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

Claude Platform on AWS

Claude Platform on AWS serve a primeira API Anthropic em infraestrutura AWS em aws-external-anthropic.<region>.api.aws. Usa IDs de modelo de primeira parte, honra cabeçalhos anthropic-beta conforme enviados e serve count_tokens, portanto nenhuma tradução específica do Bedrock se aplica. O provedor anthropicAws requer Claude Code v2.1.198 ou posterior; versões anteriores do gateway o rejeitam na inicialização.

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

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

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

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

Google Cloud Agent Platform

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

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

Um bloco auth vazio usa Credenciais Padrão de Aplicativo: GOOGLE_APPLICATION_CREDENTIALS, metadados GCE ou Workload Identity do GKE. Arquivos de chave JSON de conta de serviço são suportados mas desencorajados; use Workload Identity ou anexe uma conta de serviço à instância GCE ou Cloud Run.

Defina region: global para usar o endpoint global do Agent Platform do Google Cloud em vez de um regional. O Google então roteia cada solicitação para uma região disponível, portanto você não rastreia disponibilidade de modelo por região. Definir uma região específica fixa cada solicitação a ela.

Microsoft Foundry

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

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

use_azure_ad: true resolve através de DefaultAzureCredential: Managed Identity no AKS, ACI ou App Service; a CLI do Azure; ou credenciais de ambiente. Chaves de API funcionam mas são em todo o projeto e não giram automaticamente. O endpoint do Foundry é derivado de resource:; defina o base_url opcional para substituí-lo para nuvens soberanas como Azure Government.

Múltiplos upstreams

O mesmo provedor pode aparecer mais de uma vez com um name: distinto. Isso cobre diferentes regiões, diferentes contas através de diferentes cadeias de credencial, throughput provisionado versus sob demanda e fallback entre provedores.

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

429 é capacidade por upstream, portanto esgotamento de throughput provisionado (PT) falha para sob demanda. Se você definir forward_user_identity: true em um upstream, um 429 para uma solicitação que carregava o email do desenvolvedor é uma negação por usuário em vez disso e não falha.

404 é disponibilidade de modelo por upstream, portanto um upstream que não habilitou um modelo não bloqueia um upstream posterior que o serve. Um upstream que não pode resolver o modelo solicitado é pulado sem uma viagem de rede.

Este exemplo roteia uma alocação de throughput provisionado Bedrock primeiro, transborda para sob demanda e uma segunda conta, e volta para a API Anthropic por último:

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

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

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

O CLI aplica o mesmo feature gating a gateways independentemente de qual upstream serve uma determinada solicitação, portanto o failover não envia um campo de corpo que um upstream rejeitaria.

Seções opcionais

`admin`

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

admin:
  # Chaves de API estáticas nomeadas para os endpoints de administração, enviadas como x-api-key.
  # O id aparece no log de auditoria como admin-key:<id> portanto cada chave é
  # atribuível. Array para rotação: adicione a nova chave, role clientes,
  # remova a antiga.
  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}" }
  # Grupos IdP concedidos acesso total de administrador através do JWT normal do gateway (sem chave de API).
  admin_groups: [platform-finops]
  blocked_message: request an increase at https://go.example.com/claude-limits

`enforcement`

O bloco enforcement controla como as verificações de limite de gastos se comportam quando o armazenamento está indisponível.

`pricing`

O bloco pricing diz ao medidor de gastos o que cobrar em vez do preço de lista em USD, portanto os limites e /effective refletem suas taxas contratadas. Os valores permanecem em USD e permanecem 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, em v2.1.268 ou posterior, um bloco managed: com pelo menos uma política. O gateway recusa iniciar com pricing definido e nenhum bloco, 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 substituição:

• Uma linha substitui o preço de lista para solicitações que upstream, um upstreams[].name, serve para model. Isso inclui a taxa de modo rápido mais alta, portanto solicitações de modo rápido e padrão medem as mesmas quatro taxas.
• Um ID integrado como claude-sonnet-4-6, correspondido como models[].id, cobre cada forma datada, forma regional Amazon Bedrock, ou forma da Plataforma de Agentes 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 a string enviada upstream, insensível a maiúsculas/minúsculas.
• Onde as linhas se sobrepõem, o medidor escolhe a linha mais específica em vez da primeira linha: uma linha cujo model é a string de modelo exata enviada upstream, depois uma linha correspondendo ao ID exato que o cliente enviou, depois uma linha nomeando o modelo integrado.
• Um nome de upstream desconhecido falha na inicialização, assim como duas linhas para um upstream que nomeiam o mesmo modelo, incluindo duas grafias de um modelo integrado. O gateway avisa na inicialização sobre uma linha que nenhum modelo solicitável pode usar.
• Solicitações de busca na web permanecem no preço de lista de $0.01; o multiplicador ainda se aplica a elas.

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

Enviar as taxas para clientes conectados

Com v2.1.268 ou posterior no servidor do gateway, o gateway também coloca as taxas de pricing nas políticas managed que serve, como a configuração gerenciada modelPricing. Desenvolvedores correspondidos por uma política então veem as taxas de pricing para o primeiro upstream que serve cada ID de modelo em /usage, a linha de status e OpenTelemetry. Um desenvolvedor que não corresponde a nenhuma política recebe nenhuma configuração gerenciada, portanto suas figuras permanecem no preço de lista. Clientes aplicam a configuração em 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 substituição do primeiro upstream que serve esse ID. Uma taxa que apenas um upstream de failover cobra permanece no gateway.
• Optar uma política para fora: defina modelPricing para {} no bloco cli dessa política, e seus desenvolvedores permanecem no preço de lista.
• Manter as próprias taxas 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 taxa de sua própria a ele.

`models`

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

auto_include_builtin_models: true   # false: expor apenas a lista abaixo
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    # description: texto opcional mostrado em clientes que o exibem
    upstream_model:
      anthropic: claude-opus-4-8
      bedrock: us.anthropic.claude-opus-4-8   # ou um ARN de perfil de inferência
      foundry: your-opus-deployment-name

Cada chave sob upstream_model deve corresponder ao name de um upstream configurado, que padrão é o nome do provedor. Uma chave que não corresponde a nenhum upstream falha na inicialização, portanto omita as linhas para provedores que você não usa.

`managed`

O bloco managed define políticas de acesso baseadas em função codificadas em grupos IdP ou domínio de email. As políticas são avaliadas em ordem; a primeira correspondência é selecionada, depois mesclada na base match: {} catch-all descrita abaixo. Elas são servidas por usuário em GET /managed/settings com cache ETag/304.

managed:
  policies:
    # Grupos específicos primeiro.
    - match: { groups: [eng-contractors] }
      cli:
        availableModels: [claude-sonnet-4-6]
        permissions: { deny: ["WebFetch", "WebSearch"] }
    # Catch-all padrão por último: corresponde a todos que se autenticaram.
    - match: {}
      cli:
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

Um catch-all match: {}, convencionalmente listado por último, é tratado como uma camada base. Cada outra política herda qualquer chave que não defina do catch-all, portanto entradas por função apenas precisam listar o que difere do padrão da organização. As regras de mesclagem dependem do tipo de chave:

• Listas de permissão: availableModels e permissions.allow. A lista de uma política específica substitui completamente a da base.
• Listas de negação e arrays de hook: permissions.deny, permissions.ask, disabledMcpjsonServers, deniedMcpServers, blockedMarketplaces e cada array de tipo de evento hooks. Estes tomam a união de base e política, portanto uma negação em toda a organização ou hook de auditoria não pode ser acidentalmente descartada por uma substituição por função.
• Chaves do tipo registro: env, modelOverrides e skillOverrides. Estes mesclam superficialmente, portanto um bloco env por função substitui as chaves que define e herda o resto da base.

availableModels também é aplicado no servidor em /v1/messages, portanto um modelo negado retorna 400 independentemente do que o cliente envia.

O gateway valida o valor model em si antes de retransmitir uma solicitação, portanto um valor malformado nunca atinge um upstream. Ele rejeita a solicitação com um 400 em dois casos:

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

Um usuário autenticado que não corresponde a nenhuma política obtém os padrões do gateway, o que significa cada modelo no catálogo e nenhuma configuração gerenciada. Adicione um catch-all match: {} por último se quiser uma política padrão garantida.

Valores de correspondência que param o gateway na inicialização

Na inicialização, o gateway verifica o bloco match de cada política e a lista admin_groups. Qualquer um desses valores para 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 uma vírgula. O gateway aparenta o valor e remove um @ inicial antes dessa verificação. Escreva um domínio simples, como example.com.

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

• Um email_domain vazio: o gateway pulava a verificação de domínio, portanto uma política com um email_domain vazio e nenhuma lista groups correspondia a cada usuário autenticado
• Uma lista groups vazia: a política não correspondia a ninguém
• Um email_domain contendo @, espaço em branco ou uma 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 apenas quando a declaração 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 continha uma entrada vazia, ninguém ganhava acesso de administrador dessa forma.

O que vai em `cli`

Cada valor cli é um documento managed-settings.json completo do Claude Code, o mesmo esquema que você implantaria via MDM ou /etc/claude-code/managed-settings.json, expresso aqui como YAML. O CLI aplica o documento entregue na camada gerenciada, acima das configurações de usuário e projeto, no lugar das configurações gerenciadas pelo servidor. Portanto, ele ignora as configurações restritas a fontes de política de nível do SO, como policyHelper e wslInheritsWindowsSettings.

O gateway valida cada documento contra o esquema de configurações do CLI na inicialização, portanto uma chave de nível superior não reconhecida falha na inicialização com um erro nomeando cada chave ofensiva. Partes deliberadamente abertas do esquema ainda aceitam valores arbitrários, porque clientes mais novos podem reconhecer entradas que o esquema do gateway não reconhece. Essas chaves abertas são env, pluginConfigs e chaves aninhadas sob permissions.

Como a validação usa o esquema agrupado com a versão instalada do gateway, colocar uma chave de configurações de nível superior introduzida por uma versão mais nova do Claude Code na configuração gerenciada requer atualizar o gateway primeiro. Teste uma nova política em um cliente antes de implantá-la.

A referência de chave completa está em Configurações do Claude Code. As chaves que os operadores mais procuram primeiro:

managed:
  policies:
    - match: {}
      cli:
        # Acesso ao modelo (também aplicado no servidor em /v1/messages)
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

        # Política de permissão
        permissions:
          deny:
            - "WebFetch"
            - "Read(./.env)"
            - "Read(./secrets/**)"
          disableBypassPermissionsMode: disable   # bloqueia --dangerously-skip-permissions
        allowManagedPermissionRulesOnly: true     # ignora regras de permissão de usuário/projeto

        # Ambiente empurrado para o processo CLI. DISABLE_UPDATES bloqueia
        # atualizações de fundo e manuais; DISABLE_AUTOUPDATER para apenas
        # atualizações de fundo.
        env:
          DISABLE_UPDATES: "1"                    # fixe versões através de sua própria distribuição

        # Hooks em toda a organização. Comandos de hook executam em máquinas de desenvolvedor, não no
        # gateway, portanto o caminho deve existir em cada SO do cliente na política.
        hooks:
          PostToolUse:
            - matcher: "Edit|Write"
              hooks:
                - { type: command, command: /usr/local/bin/audit-edit.sh }

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

• hooks
• Variáveis env que requerem aprovação do desenvolvedor, como variáveis de proxy e URL base
• Configurações de execução de shell como apiKeyHelper e statusLine
• As configurações de binário sandbox sandbox.bwrapPath, sandbox.socatPath e sandbox.ripgrep
• Configurações de Sandbox que interceptam tráfego, injetam credenciais ou enfraquecem isolamento, como sandbox.network.tlsTerminate e as configurações de porta de proxy. Diálogos de aprovação de segurança lista todos eles.

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

Claude Code aplica algumas variáveis env entregues sem mostrar ao desenvolvedor o diálogo de aprovação, como configurações de seleção de modelo e limites numéricos. Outras variáveis entregues podem exigir aprovação do desenvolvedor antes de entrarem em vigor; um valor de proxy, URL base ou OTEL_EXPORTER_OTLP_ENDPOINT não vazio sempre faz. Quando uma variável entregue precisa de aprovação, o diálogo a nomeia.

Variáveis de ambiente e o diálogo de aprovação tem os detalhes, incluindo quatro alternâncias de privacidade cujo valor entregue decide se precisam de aprovação. Antes da v2.1.218, Claude Code aplicava menos variáveis sem perguntar ao desenvolvedor, portanto mais variáveis entregues disparavam o diálogo.

A configuração de telemetria do gateway empurra OTEL_EXPORTER_OTLP_ENDPOINT, portanto definir telemetry.forward_to dispara o diálogo em cada cliente interativo. O diálogo protege a máquina do desenvolvedor de um gateway comprometido ou hostil, não a organização do desenvolvedor.

Uma execução não interativa com a flag -p não pode mostrar o diálogo. Ela aplica as configurações empurradas apenas para essa execução e não as registra como aprovadas, portanto a próxima sessão interativa do desenvolvedor ainda mostra o diálogo. Antes da v2.1.207, uma execução não interativa salvava as configurações como aprovadas e nenhuma sessão interativa posterior mostrava o diálogo para elas.

Se um desenvolvedor recusar, Claude Code sai dessa sessão em vez de aplicar a política. Quando você empurra um novo hook, ou qualquer variável env que dispara o diálogo, para uma política ampla, Claude Code portanto mostra o diálogo a cada desenvolvedor correspondente. Ele mostra o diálogo em uma sessão em execução na próxima sondagem horária, e caso contrário no próximo início do desenvolvedor.

A chave cli foi nomeada settings em versões anteriores. Essa ortografia ainda é aceita como um alias, mas novas implantações devem usar cli.

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 de 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 Claude Code aplica no cliente, e se uma entrada falhar uma verificação, o gateway recusa iniciar e nomeia a entrada.

Se você escrever uma referência ${VAR} em gateway.yaml, o gateway a resolve de seu ambiente na inicialização através de expansão de segredo antes de executar as verificações de entrada, portanto cada cliente correspondente recebe o valor literal e pode lê-lo. A orientação de cabeçalho para servidores fornecidos se aplica ao valor expandido.

O gateway rejeita a ortografia .mcp.json mcpServers em um bloco cli, e seu erro de inicialização nomeia managedMcpServers como a chave a usar. 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 Claude Desktop, o mesmo gateway serve ambos os clientes. Aponte bootstrapUrl, na configuração gerenciada do Claude Desktop, para <listen.public_url>/user/bootstrap. Claude Desktop deriva o emissor OAuth dessa URL, executa o mesmo login de código de dispositivo contra este gateway e busca sua configuração da resposta.

O gateway deriva muito da resposta do bloco cli da política correspondente e da configuração do gateway de nível superior:

• A lista de modelos, de availableModels

• Ferramentas desabilitadas, de entradas permissions.deny de nome de ferramenta simples. Se você definir disabledBuiltinTools no bloco desktop da política, o gateway serve a união de seu valor e a lista derivada, portanto você pode desabilitar mais ferramentas dessa forma mas não pode reabilitar uma que você desabilitou através de permissions.deny

• A lista de permissão 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

• Um endpoint OTLP que aponta para o gateway em si, e os atributos de identidade do usuário conectado. O gateway retransmite 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.

  Claude Desktop exporta cada sinal com uma codificação: http/protobuf, ou http/json quando você define OTEL_EXPORTER_OTLP_PROTOCOL ou uma de suas variantes por sinal para http/json no env da política. Antes de Claude Code v2.1.261 no servidor do gateway, a resposta definiu http/json independentemente, portanto um coletor que aceita apenas protobuf rejeitou as exportações do Claude Desktop

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

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

Adicione o bloco desktop opcional ao lado de cli para definir configurações do Claude Desktop diretamente. Escreva configurações da referência de configuração gerenciada do Claude Desktop como nomes de chave simples. Deixe de fora chaves que Claude Desktop lê apenas de MDM ou arquivos locais, como bootstrapUrl; o gateway as rejeita na inicialização. Antes da v2.1.232, o gateway aceitava uma lista fixa de 11 chaves de portão de recurso, como chatTabEnabled e disableAutoUpdates, e rejeitava cada outra chave na inicialização. Antes da v2.1.227, o gateway também rejeitava chatTabEnabled e chatAdvancedFileAnalysisEnabled na inicialização.

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

Cada chave é opcional; Claude Desktop aplica seu próprio padrão para qualquer chave que você omita. O gateway valida cada bloco desktop na inicialização contra o esquema de configuração que o próprio Claude Desktop usa, portanto um erro aparece no início do gateway como um erro nomeando a chave em vez de alcançar cada desktop conectado. O gateway falha na inicialização quando um bloco contém:

• Uma chave desconhecida
• Uma chave reconhecida cujo valor Claude Desktop rejeitaria ou descartaria silenciosamente, como um valor vazio ou uma sub-chave digitada incorretamente dentro de uma entrada aninhada. Antes da v2.1.260, o gateway descartava silenciosamente um campo digitado incorretamente dentro de um objeto aninhado de uma entrada managedMcpServers ou orgPluginSettings em vez de falhar na inicialização.
• Uma chave que o gateway computa em si: a conexão de inferência, a lista de modelos e a retransmissão OTLP. Configure aqueles através de upstreams, models e a seção telemetry forward_to.
• Um alias legado de uma chave atual. No erro de inicialização, o gateway nomeia a chave canônica a escrever.

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

O gateway valida um bloco desktop contra o esquema agrupado com sua versão instalada, como faz 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 de Claude Code v2.1.260 ou posterior no servidor do gateway e Claude Desktop 1.37937.0 ou posterior nas máquinas dos membros.

Se você definir orgPluginSettings em um bloco desktop de uma política, o gateway o serve na forma de array que Claude Desktop 1.15200.0 e posterior lê. Desktops mais antigos ignoram o array e não aplicam nenhuma política de ferramenta de plugin, portanto atualize membros para 1.15200.0 ou posterior antes de confiar nisso.

O gateway preenche chaves que um bloco desktop de uma política não define a partir do bloco desktop do catch-all match: {}, da mesma forma que preenche um 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 e da lista da política
• builtinToolPolicy: se você definir uma ferramenta para um valor diferente de allow na base, o gateway mantém esse valor mesmo se você definir allow para a mesma ferramenta em uma política de função

Para cada outra chave, 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 inteiro, portanto se você definir banner.text em uma política de função, o gateway descarta o banner.backgroundColor da base.

Se você não implantar Claude Desktop, deixe desktop completamente fora de suas políticas; o gateway então retorna 404 de /user/bootstrap para cada usuário.

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 classificação primeiro. Precedência dentro da camada gerenciada na página de configurações gerenciadas diz quando as fontes locais se aplicam, e tem as chaves que Claude Code lê de cada fonte de administrador independentemente de qual fonte selecionou, como as chaves de bloqueio de sandbox, forceRemoteSettingsRefresh e a mesclagem env por variável. Um policyHelper configurado em um perfil MDM ou arquivo de configurações gerenciadas é executado apenas quando o gateway não entrega configurações; a entrada diz o que sua saída substitui.

Hosts de incorporação como Claude Desktop podem fornecer política através da opção SDK managedSettings. Configurações pai de hosts de incorporação diz quando Claude Code a aplica, e Restringir configurações pai lista quais configurações de direção de permissão ainda se aplicam sem os bloqueios allowManaged*Only.

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

`telemetry`

O CLI envia métricas, logs e, quando habilitado, rastreamentos para o gateway, que os retransmite literalmente para cada destino configurado. As exportações usam OpenTelemetry Protocol (OTLP) sobre HTTP. Para pular a retransmissão e ter sessões exportarem diretamente para seu coletor, nomeie o coletor em uma política. Consulte Monitoramento de uso para as métricas e eventos que o CLI emite.

O CLI carimba cada exportação com a identidade do usuário autenticado, lida do JWT emitido pelo gateway: os atributos user.id, user.email e user.groups. A atribuição de custo e uso por desenvolvedor portanto funciona sem nenhuma configuração do lado do desenvolvedor.

Claude Desktop e sessões Cowork conectadas através do gateway carimbam sua telemetria com user.email e user.groups ao lado de enduser.id, portanto você pode cobrir uso de terminal, Desktop e Cowork com uma consulta em user.email ou user.groups. user.groups é a lista de grupos IdP separada por vírgula.

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

Se a lista de grupos de um usuário for maior que 255 caracteres uma vez codificada em percentual, ou um nome de grupo contiver uma vírgula ou sinal de igual, o gateway deixa user.groups fora da telemetria Desktop e Cowork desse usuário em vez de truncá-la. As sessões de terminal desse usuário ainda carregam a lista completa.

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

telemetry:
  forward_to:
    - url: https://otel-collector.internal.example.com
      headers:
        Authorization: ${OTLP_TOKEN}
      # Opt-in por sinal. Padrão: apenas métricas.
      metrics: true
      logs: false
      traces: false
    - url: https://api.datadoghq.com/api/v2/otlp
      headers:
        DD-API-KEY: ${DD_API_KEY}

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

• http://localhost:<port> passa validação de configuração, mas a proteção SSRF bloqueia cada exportação 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> falha na inicialização a menos que essa variável seja definida

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

A telemetria está desativada no CLI por padrão. Quando você define tanto telemetry.forward_to quanto listen.public_url, o gateway a ativa para clientes conectados empurrando seis variáveis de ambiente através de /managed/settings:

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

Antes de Claude Code v2.1.265 no servidor do gateway, o gateway empurrava todos os três seletores de exportador como otlp, incluindo para sinais que nenhum destino optou.

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

Desenvolvedores conectados através de /login não podem redirecionar exportações com sua própria configuração OTEL:

• Variáveis definidas localmente: Claude Code aplica as variáveis empurradas na camada gerenciada, portanto cada uma substitui o valor que um desenvolvedor define para ela localmente.
• Endpoints configurados localmente: com exportação OTLP/HTTP habilitada, o CLI ignora qualquer endpoint configurado localmente, independentemente de o gateway ter empurrado 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 aceita e descarta. Se desenvolvedores já exportam telemetria do Claude Code para um de seus coletores, adicione-o como um destino forward_to, com logs ou rastreamentos habilitados se exportarem aqueles, portanto continua recebendo seus dados depois que eles se conectam. Para pular a retransmissão em vez disso, nomeie o coletor em uma política.

Rastreamentos também requerem CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 em cada cliente. Defina-o no bloco env de uma política gerenciada, já que o gateway não o empurra. Desenvolvedores o aprovam no mesmo diálogo de aprovação de segurança que o endpoint empurrado já dispara.

Defina-o para 1 apenas nas políticas cujos grupos você quer rastreados. Uma política que não o define herda o valor de sua política match: {} catch-all se essa política define um, por regras de mesclagem. Para manter os clientes de um grupo de enviar rastreamentos mesmo quando um desenvolvedor define a variável localmente, defina-a para 0 na política desse grupo.

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

Exportar diretamente para seu coletor

Para ter sessões conectadas através de /login enviar telemetria diretamente para seu coletor em vez de através da retransmissão, defina OTEL_EXPORTER_OTLP_ENDPOINT para a URL base https:// do coletor no bloco env de uma política gerenciada. Claude Code anexa /v1/metrics, /v1/logs ou /v1/traces à URL que você define, como https://otel-collector.example.com:4318, e exporta cada sinal lá sobre OTLP/HTTP. Requer Claude Code v2.1.265 ou posterior em cada máquina do desenvolvedor. Clientes anteriores exportam através da retransmissão.

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

Quando você adiciona ou muda esse endpoint em uma política, Claude Code pede a cada desenvolvedor para aprová-lo no diálogo de aprovação de segurança antes de aplicá-lo em uma sessão interativa.

Claude Code verifica o endpoint antes de exportar um sinal diretamente, e mantém esse sinal na retransmissão 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 um managed-settings.json local, exportações permanecem na retransmissão.
• A URL usa https://, ou http:// para um endereço de loopback
• A URL resolve para um caminho terminando em /v1/<signal>, sem consulta ou fragmento. Claude Code constrói esse caminho em si a partir da variável genérica. Ele usa uma variável por sinal como OTEL_EXPORTER_OTLP_METRICS_ENDPOINT conforme escrito, portanto inclua o caminho completo lá.
• A URL não é o próprio host do gateway. Um endpoint endereçado ao gateway mantém o caminho de retransmissão e seu token de sessão.
• Nem você nem o desenvolvedor configurou otelHeadersHelper em nenhuma fonte de configurações. Com um helper configurado, cada sinal permanece na retransmissão.

O endpoint que você nomeia muda apenas para onde as exportações vão. Você ainda escolhe quais sinais exportam em tudo com os seletores OTEL_*_EXPORTER.

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

• Se o gateway já empurra as variáveis de telemetria, elas cobrem habilitação, seletores e protocolo, e seu endpoint explícito substitui o valor <public_url> empurrado. Defina um seletor OTEL_*_EXPORTER para otlp você mesmo apenas para um sinal que nenhum destino forward_to habilita.
• Se não, também defina CLAUDE_CODE_ENABLE_TELEMETRY=1, os seletores OTEL_*_EXPORTER e OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf.

Quando o desenvolvedor se desconecta, ou se conecta a um gateway diferente, exportações para o coletor param e Claude Code descarta cada lote restante em vez de enviá-lo.

Quando um destino falha

O gateway não armazena em buffer, tenta novamente ou armazena telemetria, portanto descarta uma exportação que não atinge um destino em vez de entregá-la tarde. Cada destino sucede ou falha por conta própria, e o cliente exportador recebe uma resposta de sucesso de qualquer forma, portanto uma entrega falhada aparece apenas no log do gateway.

Após cinco falhas consecutivas de entrega para um destino, o gateway pausa o encaminhamento para ele em trechos de 30 segundos, registrando cada pausa, até que uma entrega suceda. Qualquer resposta de erro, timeout ou erro de conexão conta como uma entrega falhada, exceto 400, 413, 415, 422 e 431, que significam que o coletor recusou a carga dessa exportação como malformada ou muito grande.

Uma carga recusada nem avança nem reseta a contagem de falhas: o gateway continua encaminhando para o destino e registra um aviso nomeando-o e o status, na primeira recusa do destino e a cada centésima depois.

Ajuste HTTP

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

Exemplo completo

Esta configuração de referência completa exercita cada seção principal; os blocos 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 disso.

# 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 declarações em cada id_token, para diagnóstico de groups_claim.
# Não afeta eventos de auditoria, que são sempre emitidos.

listen:
  host: 0.0.0.0
  port: 8080
  public_url: https://claude-gateway.internal.example.com
  # Omita o bloco tls ao executar atrás de um ingress que termina 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 org Okta, cujos id_tokens
  # podem omitir email e grupos; o gateway os preenche de /userinfo.
  userinfo_fallback: true
  # allowed_groups: [claude-code-users]
  # Okta emite grupos apenas quando o escopo `groups` é solicitado e o
  # filtro de declaração de grupos do aplicativo os permite. A política de contratados abaixo
  # corresponde em grupos, portanto 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

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

# enforcement:
#   fail_closed_on_error: false

# Medir em taxas contratadas em vez de preço de lista USD. Requer admin:.
# Com managed:, as mesmas taxas também vão para clientes conectados.
# As taxas abaixo são espaços reservados, 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: 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
      # 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]
        # Restrinja o seletor Padrão à opção availableModels em vez de
        # o padrão de camada, portanto contratados não obtêm um 400 no padrão.
        enforceAvailableModels: true
        # 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]
        permissions:
          allow: [Read, Grep, Bash, 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 do lado do cliente

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

Para o CLI, defina essas chaves no managed-settings.json por SO:

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

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

Implante o arquivo managed-settings.json em cada dispositivo, tipicamente via 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 em vez disso.

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

forceLoginGatewayUrl e o valor "gateway" de forceLoginMethod são honrados apenas 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. Um desenvolvedor definindo-os em seu próprio ~/.claude/settings.json não tem efeito, e nem define-os na carga útil do gateway.

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