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

• 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 para o IdP junto com o antigo.
2. Substitua os arquivos de chave e certificado que o gateway.yaml carrega e, em seguida, reinicie o gateway. Se você executa várias réplicas, uma reinicialização gradual funciona, porque o IdP tem ambos os certificados até que você remova o antigo.
3. Depois que todas as réplicas tiverem reiniciado, remova o certificado antigo do IdP.

​

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

​

Egresso apenas 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 um deles em pods, defina ambos para um valor vazio no contêiner do gateway. Listar um coletor de telemetria em NO_PROXY mantém o egresso apenas proxy desativado.
• CLAUDE_GATEWAY_ALLOW_LOOPBACK não está ativado. Um coletor ou IdP no próprio loopback do pod não pode ser combinado com egresso apenas proxy, porque um endereço de loopback entregue ao proxy seria o próprio do host proxy, portanto dê a esses serviços um endereço que o proxy possa alcançar em vez disso. Pela mesma razão, o gateway recusa nomes de estilo localhost completamente enquanto o egresso apenas proxy está ativo.

​

session

​

store

​

upstreams

​

Mensagens de erro do upstream

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

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

​

Anthropic API

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

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

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

​

Amazon Bedrock

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

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

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

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

• Se o STS recusar ou estiver inacessível, o gateway não envia a requisição com as credenciais próprias do upstream. Ele registra o erro do STS com o que verificar e então tenta o próximo upstream que você listou. Mensagens de erro do upstream descreve o que o cliente recebe quando nenhum upstream tem sucesso. Um upstream posterior sem assume_role serviria a requisição com suas próprias credenciais, portanto liste um apenas se for isso que você deseja.
• O gateway chama o endpoint regional do STS sts.<region>.amazonaws.com, que sua rede deve alcançar. Para o endpoint FIPS, defina AWS_USE_FIPS_ENDPOINT=true no ambiente do gateway em vez de use_fips_endpoint em um arquivo de configuração AWS.
• assume_role se aplica apenas a provider: bedrock e precisa de credenciais de origem SigV4: o gateway se recusa a iniciar quando ele está definido junto com aws_bearer_token.
• Cada desenvolvedor que o gateway admite pode usar esse upstream; managed governa quais desenvolvedores podem usar quais modelos. Para impedir que um modelo servido através da função também seja servido a partir de outra conta, dê a ele um id personalizado cujo mapa upstream_model tenha apenas o nome desse upstream. Para esse id, o gateway pula todos os outros upstreams, portanto nem a requisição nem a contagem de tokens de uma requisição abortada podem fazer failover para outra conta. Uma requisição para um nome de modelo integrado ainda pode alcançar esse upstream, e o gateway a assina com a mesma função. Liste esse upstream por último, a menos que sua conta também deva servir esses modelos.

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

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

​

Endpoint Mantle do Amazon Bedrock

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

• guardrail: o gateway não aplica nenhum guardrail do Bedrock às requisições que envia ao Mantle, portanto ele se recusa a iniciar quando um upstream mantle está listado enquanto qualquer upstream bedrock define guardrail.
• assume_role: um upstream mantle não aceita assume_role. As requisições que o Mantle serve são enviadas com as credenciais auth próprias do upstream mantle e não são atribuídas por desenvolvedor.

​

Claude Platform on AWS

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

​

Google Cloud Agent Platform

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

​

Microsoft Foundry

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}

​

Cabeçalhos estáticos em solicitações de 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 começando com anthropic-, x-goog-, x-amz- ou x-amzn-

​

Múltiplos upstreams

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

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

​

Seções opcionais

​

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

​

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, em 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 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

• Uma linha substitui o preço de lista para requisições que upstream, um upstreams[].name, serve para model. Isto inclui a taxa de modo rápido mais alta, então requisiçõ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 do 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 à string enviada upstream, sem distinção de maiúsculas e 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.
• Requisições de busca na web permanecem no preço de lista de $0,01; o multiplicador ainda se aplica a elas.

​

Marcar preços para cima

pricing:
  multiplier: 1.2

​

Enviar as taxas 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 substituição do primeiro upstream que serve esse ID. Uma taxa que apenas um upstream de failover cobra permanece no gateway.
• Excluir uma política: defina modelPricing como {} no bloco cli dessa política, e seus desenvolvedores permanecem no preço de 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

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 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, então um hook de negação ou auditoria em toda a organização não pode ser acidentalmente descartado por uma substituição por função.
• Chaves de tipo registro: env, modelOverrides e skillOverrides. Estas mesclam superficialmente, então um bloco env por função sobrescreve as chaves que define e herda o resto da base.

• Quando o valor está faltando ou vazio, o gateway rejeita a requisiçã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 requisição com a mensagem model must be a string. Requer um gateway executando Claude Code v2.1.221 ou posterior.

​

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 começam em um desses modelos, e a opção Default em /model resolve para ele
• Nenhum alias ou ID integrado na lista: as sessões podem continuar começando no padrão integrado, então também defina model como um dos IDs listados no bloco cli dessa política

managed:
  policies:
    - match: { groups: [restricted-projects] }
      cli:
        availableModels: [claude-opus-restricted]
        enforceAvailableModels: true
        model: claude-opus-restricted

​

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 uma vírgula. O gateway remove espaço em branco do valor e remove um @ inicial antes desta verificação. Escreva um domínio simples, como example.com.

• Um email_domain vazio: o gateway pulava a verificação de domínio, então 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 administrativo. Se sua lista admin_groups nunca continha uma entrada vazia, ninguém ganhava acesso administrativo desta forma.

​

Escolher cli ou code

• cli: o terminal, as extensões do VS Code e do JetBrains e o Agent SDK. Com 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: {}

​

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 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. Security approval dialogs lista todas elas.

​

Janela de contexto em sessões de terminal

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

​

MCP servers in a policy

​

Claude Desktop overlay

• A lista de modelos, de availableModels. Contexto estendido no Claude Desktop cobre a opção de contexto de 1M de cada modelo
• 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, então você pode desabilitar mais ferramentas desta forma mas não pode reabilitar uma que você desabilitou através de permissions.deny
• A allowlist de egresso, 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 próprio gateway, 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 definia http/json independentemente, então um coletor que aceita apenas protobuf rejeitava as exportações do Claude Desktop

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

• Via HTTPS, quando 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
• Via HTTPS, quando o Claude Desktop inclui uma versão anterior: a aba Code inicia sem suas configurações de code, e nada na sessão indica isso
• Via HTTP simples: a aba Code inicia sem suas configurações de code, qualquer que seja a versão incluída no Claude Desktop

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

• 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 de 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 a si mesmo: a conexão de inferência, a lista de modelos e o relé 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.

• 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

• Fechado: Claude Desktop busca a resposta de bootstrap quando inicia, então a mudança se aplica a partir da próxima inicialização
• Aberto: 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, Claude Desktop mostra um 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 nenhum de seus valores upstream_model nomeia um modelo Claude, como um alias personalizado roteado para um ARN de perfil de inferência de aplicação

• Iniciar 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 isto se seu servidor do gateway executa uma versão anterior a v2.1.284, ou se uma entrada não nomeia nenhum modelo Claude. Liste o modelo duas vezes em models, uma vez com seu ID simples e uma vez com [1m] anexado, ambas com o mesmo mapa upstream_model. Claude Desktop mostra o par como um modelo com uma opção de 1M. O gateway serve uma entrada [1m] sem verificá-la, então adicione uma apenas 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

​

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 validação de configuração, mas a SSRF guard 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 esteja definida

• 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

• Variáveis definidas localmente: Claude Code aplica as variáveis empurradas na camada gerenciada, então cada uma sobrescreve 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.

​

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

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

​

Group changes during an open session

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

​

Exportar diretamente para seu coletor

• 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 no relé.
• 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 a si mesmo a partir da variável genérica. Ele usa uma variável por sinal como OTEL_EXPORTER_OTLP_METRICS_ENDPOINT conforme escrito, então 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 relé 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 no relé.

• Se o gateway já empurra as variáveis de telemetria, elas cobrem habilitação, seletores e protocolo, e seu endpoint explícito sobrescreve 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 um destino falha

​

HTTP tuning

• 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, mais qualquer outro intervalo interno de onde 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 em desenvolvimento local, o aviso não aparece.
• Em tempo de execução: a primeira vez que uma requisição chega de um endereço fora desses intervalos privados, o gateway registra um aviso e emite um access.public_client audit event carregando o IP do cliente. Ambos disparam 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 /healthz e /readyz antes desta verificação ser executada, então sondas de saúde 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.

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

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

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

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

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

# enforcement:
#   fail_closed_on_error: false

# Teste de carga desta implantação sem chamar um provedor de modelo. Nunca em um
# gateway que desenvolvedores usam: cada solicitaçã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, 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 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