SpyBara
Go Premium

claude-apps-gateway-config.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 296 additions and 95 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Fri 18 23:58 Wed 23 23:57 Fri 25 23:58

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

Formulário Resolve para Use para
${VAR} A variável de ambiente VAR. A inicialização falha se não estiver definida. Variáveis de ambiente de contêiner, AWS Secrets Manager via injeção de env
${file:/path} Conteúdo do arquivo nesse caminho absoluto, aparado. A referência deve ser o valor inteiro do campo: diferentemente de ${VAR}, não é expandida dentro de uma string mais longa, então para uma senha de banco de dados defina store.password em vez de incorporá-la em postgres_url. Montagens de volume do Kubernetes Secret, Vault Agent, SOPS

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.

Campo Obrigatório Descrição
host Não Endereço de vinculação. Padrão 0.0.0.0.
port Não Porta de vinculação. Padrão 8080.
public_url A menos que host seja loopback A origem https:// visível externamente, usada para construir o redirect_uri do IdP e metadados de descoberta. Obrigatório sempre que host não for um endereço de loopback, seja TLS terminado em um proxy como um ALB, Ingress ou Cloud Run ou no próprio gateway através de tls, porque o gateway nunca deriva sua própria origem de cabeçalhos X-Forwarded-*; eles são falsificáveis pelo cliente. Falha na inicialização sem ele. trusted_proxies abaixo governa apenas a resolução de IP do cliente. Também obrigatório para habilitar telemetria, porque o gateway constrói o endpoint OTLP que envia para clientes a partir desta URL.
tls.cert / tls.key Não Caminhos PEM se o gateway termina TLS por si mesmo
trusted_proxies Não CIDRs ou IPs de balanceadores de carga na frente do gateway. Quando definido, o gateway confia em X-Forwarded-For apenas desses pares e registra o IP do cliente real para limitação de taxa por IP e auditoria. Equivalente ao nginx set_real_ip_from. Entradas X-Forwarded-For escritas como ipv4:port ou [ipv6]:port, como alguns balanceadores de carga fazem, são lidas com a porta descartada. Um endereço IPv6 com uma porta anexada e sem colchetes pode ser lido como um endereço diferente ou não ser lido, portanto desative a opção de porta em qualquer proxy que escreva esse formulário.

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

Campo Obrigatório Descrição
issuer Sim Base de descoberta OIDC. Deve servir descoberta em /.well-known/openid-configuration. Use HTTPS em produção; o gateway aceita um emissor http://. Um emissor de loopback como http://localhost:8081 é rejeitado pela proteção SSRF a menos que CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 esteja definido no ambiente do gateway.
client_id / client_secret Sim Do seu registro de cliente OAuth
allowed_email_domains Não Rejeite id_tokens cuja declaração email não esteja em um desses domínios, insensível a maiúsculas/minúsculas. Defesa em profundidade contra configuração incorreta de IdP multi-tenant. Independentemente dessa configuração, um id_token cuja declaração email_verified é explicitamente false é sempre rejeitado.
allowed_groups Não Restrinja o login a membros desses grupos IdP, comparados com groups_claim. Um usuário em um domínio de email permitido mas em nenhum desses grupos é rejeitado. Requer que o IdP emita a declaração de grupos. A correspondência é uma comparação de string exata e sensível a maiúsculas/minúsculas contra os valores nessa declaração, e o gateway não expande grupos aninhados: para admitir membros de um subgrupo, liste o subgrupo aqui ou configure o IdP para emitir associação achatada.
groups_claim Não Qual declaração id_token carrega associação de grupo. Padrão groups. Microsoft Entra emite funções de aplicativo sob roles. Aceita uma chave simples ou um JSON Pointer RFC 6901 como /resource_access/gateway/roles para declarações aninhadas.
google_groups Não Procure os grupos do usuário conectado através da API do Diretório do Google Workspace Admin SDK, porque o id_token do Google não carrega nenhuma declaração de grupos. Defina service_account_json_path para um arquivo de chave de conta de serviço com delegação em todo o domínio no escopo https://www.googleapis.com/auth/admin.directory.group.readonly e admin_email para um administrador do Workspace que a conta de serviço representa; a API do Diretório requer um assunto de administrador real. Os endereços de email do grupo de cada usuário se tornam sua declaração de grupos, portanto allowed_groups e managed.policies.match.groups correspondem aos emails do grupo.
email_claim Não Qual declaração id_token carrega o email do usuário. Padrão email. Alguns IdPs, como ADFS e Entra B2C, emitem upn ou preferred_username. Aceita uma chave simples, um JSON Pointer ou uma lista de chaves de fallback onde a primeira chave presente é usada.
scopes Não Substituição completa dos escopos OIDC que o gateway solicita. Padrão [openid, profile, email, offline_access]. Defina quando seu IdP rejeita escopos que não reconhece ou requer um escopo personalizado para emitir grupos ou email. Deve incluir openid. Descartar offline_access desabilita tokens de atualização, portanto os desenvolvedores executam novamente o login do navegador a cada session.ttl_hours. Consulte Configuração do provedor de identidade para receitas de escopo por IdP, como o fluxo de token de atualização do Google.
scope_on_refresh Não Também envie scope, com a mesma lista que a solicitação de login, quando o gateway troca um token de atualização. Padrão false: a solicitação de atualização omite scope. A maioria dos IdPs retorna um id_token em cada atualização e não precisa disso. Defina true quando seu IdP retorna um id_token na atualização apenas se solicitado openid novamente, que Okta documenta para sua concessão de atualização. Sem um id_token, cada atualização depende do endpoint userinfo do IdP aceitar o token de acesso atualizado. Se você controlar o login ou corresponder políticas em grupos e o id_token de atualização do seu IdP os omitir, também defina userinfo_fallback: true para que o gateway os preencha a partir do endpoint userinfo. Um IdP que concedeu menos escopos do que solicitado pode rejeitar a atualização com invalid_scope, incluindo para sessões existentes se você adicionar entradas a scopes enquanto isso estiver ativado. Desdefina a chave se as atualizações começarem a falhar em token_endpoint depois que você a definir. Requer Claude Code v2.1.260 ou posterior no servidor gateway.
extra_auth_params Não Parâmetros de consulta extras anexados à solicitação de autorização do IdP, literalmente. Este é o mecanismo de substituição para comportamento específico do IdP, como access_type: offline para tokens de atualização do Google, domain_hint para alguns locatários Entra ou acr_values para fluxos de step-up. Não pode substituir os parâmetros de protocolo gerenciados pelo gateway: state, nonce, redirect_uri, PKCE, scope, response_type, response_mode e client_id.
userinfo_fallback Não Quando o id_token omite email ou grupos, busque-os em /userinfo. Necessário para tokens de acesso leve do Keycloak, o servidor org do Okta e tokens mínimos do ADFS. O id_token permanece autoritário; userinfo apenas preenche lacunas. Padrão false.
use_pkce Não Envie um desafio PKCE (S256) na solicitação de autorização. Padrão true. Defina false apenas se seu IdP rejeitar PKCE para este cliente confidencial.
clock_skew_seconds Não Tolere desvio de relógio ao validar declarações de tempo id_token. Padrão 0, que é rigoroso. Aumente se você vir erros "token expirado / ainda não válido" logo após o login devido a desvio de relógio host/IdP.
token_endpoint_auth_method Não Substitua o método de autenticação do endpoint de token. Aceita client_secret_basic ou client_secret_post. Negociado automaticamente por padrão.
id_token_signed_response_alg Não Algoritmo de assinatura id_token esperado. Padrão RS256. Defina para IdPs que assinam com ES256, PS256 ou EdDSA.
additional_authorized_parties Não Valores azp extras para aceitar além de client_id, para fluxos de broker e troca de token do Keycloak
discovery_url Não Busque o documento de descoberta desta URL em vez de derivá-lo de issuer, para IdPs atrás de um proxy que reescreve o host do emissor. O caminho deve conter /.well-known/.
use_proxy Não Envie as próprias solicitações do IdP do gateway através do proxy de encaminhamento em HTTPS_PROXY ou HTTP_PROXY, honrando NO_PROXY. Indefinido ou false, essas solicitações vão diretas. Requer v2.1.227 ou posterior; consulte Solicitações do IdP através de um proxy de encaminhamento abaixo.
form_action_origins Não Origens adicionais para a diretiva Content-Security-Policy: form-action da página /device. O gateway já permite 'self' e a origem authorization_endpoint descoberta, mas o Chrome impõe form-action contra toda a cadeia de redirecionamento. Se seu IdP redireciona através de um segundo host, como Azure AD federado para ADFS, Okta hub-spoke ou um interceptador SSO corporativo, liste cada origem pela qual a solicitação de autorização pode redirecionar.
ca_cert_pem Não O certificado CA codificado em PEM em si, não um caminho para um arquivo. Ele substitui o armazenamento de confiança do sistema apenas para solicitações do IdP. Para carregar um arquivo montado, escreva ${file:/etc/gateway/idp-ca.pem}. Use para Keycloak ou Dex atrás de PKI corporativa.

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.

Campo Obrigatório Descrição
jwt_secret Sim Pelo menos 32 bytes de entropia, por exemplo de openssl rand -base64 32. Assina os tokens de portador HS256 do gateway. Aceita uma única string ou um array para rotação: o índice 0 assina e todas as entradas verificam. Para girar, coloque um novo segredo na frente, aguarde ttl_hours e depois remova o antigo.
ttl_hours Não Tempo de vida do token de portador do gateway. Padrão 1. O CLI atualiza silenciosamente antes da expiração quando o IdP emite tokens de atualização. Um tempo de vida mais curto desprovisiona mais rápido; um mais longo faz menos viagens de ida e volta do IdP. Se seu IdP não puder emitir tokens de atualização porque offline_access não está disponível, não há atualização silenciosa, portanto aumente para 8 ou 12 para evitar enviar desenvolvedores de volta ao login do navegador a cada hora.

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

Campo Obrigatório Descrição
postgres_url Sim URL postgres:// ou postgresql://. Obrigatório: o encontro de concessão de dispositivo, onde o callback do navegador escreve e o CLI de sondagem lê, precisa de estado entre réplicas. O gateway executa suas próprias migrações de esquema na inicialização e na atualização, portanto a função precisa de direitos para criar e alterar tabelas no esquema de destino. Consulte Atualizações e Postgres.
username Não Substitui o usuário em postgres_url
password Não Credencial do banco de dados. Defina aqui em vez de em postgres_url para que a credencial fique fora da URL. Aceita qualquer caractere e tem precedência sobre credenciais de URL.
max_connections Não Tamanho do pool de conexão Postgres por réplica. Padrão 5, que é conservador e amigável para bancos de dados compartilhados. Com limites de gastos habilitados, o caminho quente faz algumas operações por solicitação de inferência, portanto aumente para um banco de dados dedicado sob carga e mantenha réplicas × isto abaixo do max_connections do banco de dados.

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, ele falha para o próximo; 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, e um 404 significa que esse upstream não serve o modelo solicitado, portanto um upstream posterior na lista ainda pode.

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

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

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

Mensagens de erro do upstream

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

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

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

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

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

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

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

Anthropic API

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

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

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

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

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

upstreams:
  - provider: anthropic
    auth:
      federation_rule_id: ${ANTHROPIC_FEDERATION_RULE_ID}
      organization_id: ${ANTHROPIC_ORGANIZATION_ID}
      identity_token_file: /var/run/secrets/anthropic/id-token
      # workspace_id: wrkspc_...       # obrigatório se a regra cobre >1 workspace
      # service_account_id: svac_...   # verificação de alvo esperado opcional
Cabeçalhos de identidade por usuário para um proxy que você executa

Você pode apontar o base_url de um upstream provider: anthropic para um proxy que você executa em vez de para a API Anthropic. Para dizer a esse proxy qual desenvolvedor enviou cada solicitação, defina forward_user_identity: true nesse upstream. O proxy pode então atribuir gastos por desenvolvedor. Requer um gateway executando Claude Code v2.1.233 ou posterior.

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

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

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

Cabeçalho Valor
x-litellm-end-user-id O email do desenvolvedor, quando o IdP forneceu um.
x-claude-gateway-user-id O assunto do IdP do desenvolvedor, da declaração sub do token.
x-claude-gateway-user-email O email do desenvolvedor, quando o IdP forneceu um.

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.

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.

Configuração Como
Permissões IAM Conceda ao principal do gateway bedrock:InvokeModel e bedrock:InvokeModelWithResponseStream nos ARNs do perfil de inferência e nos ARNs do modelo de fundação subjacente. Para o catálogo integrado em regiões dos EUA: arn:aws:bedrock:<region>:<account>:inference-profile/us.anthropic.* e arn:aws:bedrock:*::foundation-model/anthropic.*. Também conceda bedrock:CountTokens nos ARNs do modelo de fundação. O gateway o usa, sem custo, para contar os tokens de entrada de uma solicitação que o cliente abandonou, portanto limites de gastos permanecem precisos. Sem ele, o gateway volta para uma solicitação Bedrock de um token para essa contagem.
Acesso ao modelo Amazon Bedrock habilita acesso ao modelo por padrão em regiões comerciais. O portão de nível de conta restante é o formulário de caso de uso único da Anthropic: se ninguém em sua conta AWS o enviou, abra o console Amazon Bedrock, selecione um modelo Anthropic do catálogo de modelos e complete o formulário. Consulte Enviar detalhes de caso de uso para o formulário AWS Organizations e as permissões que o remetente precisa.
EKS (IRSA) Crie uma função IAM com a política acima e uma política de confiança para o provedor OIDC do seu cluster com escopo para a conta de serviço do gateway. Anote a conta de serviço com eks.amazonaws.com/role-arn: arn:aws:iam::<acct>:role/claude-gateway. auth: {} a coleta.
ECS / EC2 Anexe a função IAM à definição de tarefa ou perfil de instância. auth: {} a coleta.
Em qualquer outro lugar Passe credenciais através das variáveis env AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY e AWS_SESSION_TOKEN, ou defina-as explicitamente em auth: com expansão ${VAR}
Região region: é a região do endpoint da API. Perfis de inferência entre regiões roteiam através da geo (US, EU, APAC) independentemente de qual você escolher. Para regiões fora dos EUA ou ARNs de throughput provisionado, adicione um bloco models: com os IDs corretos por upstream.

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.

Campo Obrigatório Descrição
region Sim Região AWS, letras minúsculas, dígitos e hífens. O gateway deriva o endpoint a partir dela como https://aws-external-anthropic.<region>.api.aws.
workspace_id Sim Enviado como um cabeçalho em cada solicitação; a plataforma o requer
auth.api_key Não Chave de API para a plataforma, enviada como x-api-key. Não é um token de portador: os dois modos de autenticação são uma chave de API ou SigV4.
auth.aws_access_key_id / auth.aws_secret_access_key Não Credenciais SigV4 explícitas. Definir um sem o outro falha na inicialização. auth.aws_session_token é aceito junto com eles.
base_url Não Substitua o endpoint derivado

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.

Configuração Como
Permissões IAM Conceda à conta de serviço do gateway roles/aiplatform.user no projeto, ou uma função personalizada com aiplatform.endpoints.predict. Habilite a API do Agent Platform do Google Cloud (aiplatform.googleapis.com).
Acesso ao modelo No Model Garden, habilite os modelos Claude para seu projeto. Eles publicam em regiões específicas; verifique o cartão do modelo para regiões suportadas.
GKE (Workload Identity) Vincule uma conta de serviço GCP à conta de serviço Kubernetes do gateway e anote a KSA com iam.gke.io/gcp-service-account: claude-gateway@<proj>.iam.gserviceaccount.com. auth: {} a coleta.
Cloud Run / GCE Defina a conta de serviço do serviço para uma com roles/aiplatform.user. auth: {} a coleta.
Em qualquer outro lugar auth: { service_account_json: /secrets/sa.json }, o caminho para um arquivo de chave JSON montado como um segredo. O campo leva um caminho de arquivo, não o conteúdo da chave, portanto nenhuma expansão ${file:…} está envolvida.

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.

Configuração Como
RBAC Conceda à identidade do gateway Azure AI User ou Cognitive Services User no recurso Foundry
Implantações Microsoft Foundry usa nomes de implantação escolhidos pelo administrador, não IDs de modelo canônicos. Adicione um bloco models: mapeando cada ID canônico para seu nome de implantação.
AKS (workload identity) Federe uma Managed Identity Atribuída pelo Usuário com o emissor OIDC do cluster e vincule-a à conta de serviço do gateway. use_azure_ad: true a coleta via WorkloadIdentityCredential.
ACI / App Service Habilite identidade gerenciada atribuída pelo sistema ou pelo usuário no recurso. use_azure_ad: true a coleta.
Em qualquer outro lugar auth: { api_key: "${FOUNDRY_API_KEY}" }. Cite ${…} dentro de { }.

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. 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
Alavanca Como
Diferentes regiões Um upstream Bedrock por região, cada um com sua própria region:. Com auto_include_builtin_models: true os perfis de inferência entre regiões roteiam automaticamente; para implantações fixadas por região use um bloco models:.
Diferentes contas Um upstream Bedrock por conta, cada um com suas próprias credenciais em auth:. A cadeia padrão (auth: {}) usa a identidade do pod; para uma segunda conta, defina credenciais explícitas ou um token de portador.
Throughput provisionado Mapeie o modelo para o ARN de throughput provisionado em models: para o nome desse upstream. Outros upstreams mantêm o ID sob demanda, portanto a capacidade PT é esgotada antes de falhar.
Endpoints VPC / FIPS Defina base_url: no upstream para sua URL de endpoint VPC ou FIPS
Roteamento com escopo de modelo Apenas um modelo id personalizado, que não é um modelo Claude integrado, pula os upstreams ausentes de seu mapa upstream_model:. O gateway tenta modelos integrados em cada upstream em ordem e usa o ID padrão do provedor onde o mapa não tem entrada, portanto para modelos integrados o mapa muda qual ID um upstream recebe em vez de se é tentado; um upstream que rejeita o ID segue as mesmas regras de failover que qualquer outro erro de upstream.

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
Campo Obrigatório Descrição
write_keys Não Array de {id, key}. Um x-api-key correspondente a um desses pode listar, definir e deletar limites de gastos. Os valores das chaves devem ter pelo menos 32 caracteres; ids devem ser únicos em read_keys e write_keys.
read_keys Não Array de {id, key}. Somente leitura: cada endpoint GET, incluindo listagem de limites, busca de um por ID e leitura de /effective e /audit.
admin_groups Não Nomes de grupos IdP. Um JWT do gateway cuja declaração groups inclui um desses tem acesso total de administrador, leitura e escrita, e audita como oidc:<sub>. Use isso para administradores humanos; use chaves de API para máquinas. Uma entrada vazia nesta lista para o gateway na inicialização. Consulte Valores de correspondência que param o gateway na inicialização.
blocked_message Não Anexado literalmente ao 429 billing_error que um desenvolvedor bloqueado vê. Escreva a instrução completa, como uma URL ou canal Slack. Quando não definido, o gateway envia apenas a mensagem padrão. Consulte Como a aplicação funciona.
audit_retention_days Não Padrão 365. Linhas admin_audit mais antigas são varridas.
spend_retention_months Não Padrão 13. Linhas do contador spend mais antigas que isso são varridas. O padrão mantém um ano completo mais o mês parcial atual para relatórios ano a ano.
identity_retention_days Não Padrão 90. TTL de última visualização para linhas principal_emails, que contêm email, nome de exibição e grupos de cada desenvolvedor (PII). Deliberadamente mais curto que retenção de gastos para que uma identidade desprovisionada envelheça enquanto seus contadores de gastos anônimos permanecem.
group_limit_mode Não min (padrão) ou max. Quando um desenvolvedor está em vários grupos com limites, min aplica o mais restritivo e max o menos. Usado tanto por aplicação quanto por /effective.

`enforcement`

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

Campo Obrigatório Descrição
fail_closed_on_error Não Padrão false. A aplicação de gastos falha aberta em uma interrupção do Postgres, portanto a inferência fica ativa. Defina true para falhar fechado: desenvolvedores acima do limite são bloqueados, mas também todos se o armazenamento estiver inacessível. Requer um bloco admin:: a aplicação de gastos só é executada quando admin é configurado, e o gateway recusa iniciar se você definir isso como true sem um.

`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:, porque apenas o medidor de gastos lê pricing. O gateway recusa iniciar com pricing definido e sem admin.
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
Campo Obrigatório Descrição
multiplier Não Padrão 1. O medidor multiplica cada valor medido por isso, seja com preço de lista ou substituído, portanto 0.85 cobra 85% do preço. Deve ser maior que 0 e no máximo 1.
overrides Não Linhas de {upstream, model, input, output, cache_read, cache_write} em USD por milhão de tokens. Todas as quatro taxas são obrigatórias e devem ser positivas.

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.

`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.
Correspondente Comportamento
match: {} Corresponde a cada usuário autenticado. Comece com um desses e adicione políticas com escopo de grupo acima mais tarde.
match: { groups: [a, b] } Corresponde se a declaração groups do JWT contiver qualquer um dos grupos listados. Sensível a maiúsculas/minúsculas: grupos devem corresponder ao invólucro exato do IdP.
match: { email_domain: example.com } Corresponde à parte após o último @ na declaração email do JWT, insensível a maiúsculas/minúsculas. Aceita um domínio por política.
match: { groups: [a], email_domain: example.com } Ambas as condições devem corresponder

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 }
Chave Aplicada por Efeito
availableModels Gateway + CLI Lista de permissão de modelo. Também verificada em /v1/messages, portanto um cliente corrigido não pode contorná-la.
permissions.allow / .deny CLI Regras de ferramenta e comando. Consulte Permissões.
permissions.disableBypassPermissionsMode CLI Defina como disable para bloquear bypassPermissions, o modo que aprova automaticamente cada chamada de ferramenta, e a flag --dangerously-skip-permissions
allowManagedPermissionRulesOnly CLI Quando true, configurações gerenciadas se tornam a única fonte de configurações de regras de permissão. A entrada allowManagedPermissionRulesOnly lista cada fonte que Claude Code então ignora.
env CLI Variáveis de ambiente mescladas no processo CLI. Use para telemetria, atualização automática e substituições de nome de modelo.
hooks CLI Hooks em toda a organização
managedMcpServers CLI Servidores MCP remotos fornecidos a cada desenvolvedor correspondente junto com os servidores que eles adicionam a si mesmos, http e sse apenas. Consulte Servidores MCP em uma política. Requer Claude Code v2.1.259 ou posterior no servidor do gateway e nos clientes. Clientes anteriores ignoram a chave.

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, que distribui para seus destinos, incluído quando a retransmissão de telemetry é configurada.

    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 do OpenTelemetry Protocol (OTLP) sobre HTTP para o gateway, que os retransmite literalmente para cada destino configurado. 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.

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. Configurar telemetry.forward_to junto com listen.public_url a ativa. O gateway empurra seis variáveis env para cada cliente conectado através de /managed/settings:

  • CLAUDE_CODE_ENABLE_TELEMETRY=1
  • OTEL_METRICS_EXPORTER=otlp
  • OTEL_LOGS_EXPORTER=otlp
  • OTEL_TRACES_EXPORTER=otlp
  • OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>
  • OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

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. A configuração empurrada é aplicada na camada gerenciada, substituindo variáveis OTEL_* que um desenvolvedor define localmente. Independentemente de o gateway empurrar essas variáveis, um CLI assinado através de /login que tem exportação OTLP/HTTP habilitada envia suas exportações para o gateway em vez de para um endpoint configurado localmente, e sem um destino forward_to para um sinal o gateway aceita e descarta; se você já coleta telemetria do Claude Code diretamente, adicione seu coletor como um destino forward_to.

Rastreamentos adicionalmente requerem CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 em cada cliente. O gateway não empurra essa variável, portanto defina-a através do bloco env de uma política gerenciada. Não está entre as variáveis que Claude Code aplica sem aprovação do desenvolvedor, portanto entregá-la através de uma política é coberta pelo mesmo diálogo de aprovação de segurança que o endpoint OTLP empurrado já dispara.

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

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.

Bloco Chave Padrão Descrição
access_control allow_cidrs / deny_cidrs vazio Permitir/negar IP de entrada por endereço do cliente, após resolução trusted_proxies. deny_cidrs é verificado primeiro; um cliente que corresponde é rejeitado mesmo se allow_cidrs também corresponder. Se allow_cidrs não estiver vazio o gateway é padrão-negar. /healthz e /readyz estão isentos de allow_cidrs. Quando um proxy confiável envia uma entrada X-Forwarded-For que não é um endereço IP, o cliente real é desconhecido e o gateway registra um aviso uma vez nomeando o que verificar. Onde qualquer lista se aplica à solicitação, ela a recusa com 403 e motivo de auditoria xff_unparseable. Onde nenhuma se aplica, ela serve a solicitação e usa o endereço do próprio proxy como IP do cliente para limites de taxa por IP e auditoria.
limits max_request_bytes 32 MiB Corpo de solicitação de entrada máximo; solicitações de tamanho excessivo obtêm 413 antes do corpo ser armazenado em buffer. Aumente para solicitações de arquivo ou imagem grandes.
limits max_request_header_bytes não definido Quando definido, cabeçalhos de tamanho excessivo retornam 431
limits max_url_length não definido Quando definido, uma URL muito longa retorna 414
timeouts upstream_ttfb_ms 120000 Espera máxima pelos cabeçalhos de resposta do upstream (tempo até o primeiro byte). O corpo da resposta então flui sem limite de relógio de parede. Aplica-se ao caminho upstream Anthropic direto; cada outro provedor é limitado pelo próprio timeout do SDK do provedor.
rate_limits device_authorization.max / .window_seconds 30 / 600 Limite de taxa por IP no endpoint de autorização de dispositivo não autenticado. Aumente para uma grande organização atrás de um IP de saída compartilhado ou NAT. Esses limites se aplicam apenas ao fluxo de concessão de dispositivo de login, não a /v1/messages inferência. Consulte Resistência de força bruta de código de usuário.
rate_limits device_verify.max / .window_seconds 10 / 600 Limite de taxa por IP em envios user_code em /device

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:.
# 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:

Plataforma Caminho
macOS /Library/Application Support/ClaudeCode/managed-settings.json, ou o domínio de preferências gerenciadas com.anthropic.claudecode
Linux e WSL /etc/claude-code/managed-settings.json
Windows C:\Program Files\ClaudeCode\managed-settings.json, ou Group Policy via registro HKLM

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.