Configuração do gateway de aplicativos Claude

​

Estrutura do arquivo

• 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

• 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

​

Seções obrigatórias

​

listen

​

oidc

​

Autenticação de cliente por certificado

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

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}

[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

​

Rotacionar o certificado do cliente

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

​

Saída somente por proxy

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

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

​

session

​

store

​

upstreams

​

Mensagens de erro do upstream

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

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

​

Anthropic API

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

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

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

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

​

Amazon Bedrock

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

Aplicar um guardrail do Amazon Bedrock

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

Adicionar tags de entrada do guardrail

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

O que as tags de entrada não cobrem

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

Registrar qual filtro do guardrail foi acionado

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

Bedrock em outra conta da AWS

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

{
  "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.

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

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

​

Endpoint Mantle do Amazon Bedrock

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: {}

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

​

Claude Platform on AWS

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

​

Google Cloud Agent Platform

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

​

Microsoft Foundry

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}

​

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

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}

• 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 upstream falhou
• O upstream não atende o modelo solicitado
• O upstream tem uma lista groups que deixa o desenvolvedor de fora

• 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

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

​

Enviar cada equipe para seu próprio upstream

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: {}

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

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

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

• 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ções opcionais

​

login_notice

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

​

admin

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

• 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

​

enforcement

​

pricing

• 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

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

​

Aplicar acréscimo aos preços

pricing:
  multiplier: 1.2

​

Enviar as tarifas para clientes conectados

• 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

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

​

managed

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

• 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: estes recebem a união da base e da política:
  • permissions.deny e permissions.ask
  • disabledMcpjsonServers e deniedMcpServers
  • blockedMarketplaces e deniedModels
  • Os arrays de tipos de evento de hooks
• 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.

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

​

Aplicar todas as políticas correspondentes

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

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

• 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

• 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

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

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

• 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

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

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

• 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

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 }

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

​

Testar uma política antes da implantação

​

Janela de contexto em sessões de terminal

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

​

Cache de prompt de uma hora

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

​

Servidores MCP em uma política

​

Sobreposição do Claude Desktop

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

• 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

Aplicar configurações code na aba Code

• 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

• 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

Definir configurações do Claude Desktop diretamente

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" }

O que o gateway rejeita na inicialização

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

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

Como uma política de função herda o bloco desktop 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

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

• 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

​

Contexto estendido no Claude Desktop

• 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

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

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

​

Precedência com outras fontes gerenciadas

​

telemetry

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}

• 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

• 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

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

​

Enviar métricas cumulativas

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

​

Adicionar seus próprios rótulos

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

• 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

​

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

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

​

Exportar diretamente para o seu coletor

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

• 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 um destino falha

​

Ajuste de HTTP

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

​

load_test_mode

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

​

Exemplo completo

# 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

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

​

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