Gateway de aplicativos Claude para Amazon Bedrock, Claude Platform on AWS, Google Cloud e Microsoft Foundry

Execute Claude Code através do Amazon Bedrock, Claude Platform on AWS, Google Cloud ou Microsoft Foundry atrás de um gateway auto-hospedado com sign-in SSO, acesso a modelos por grupo e telemetria OTLP.

Claude apps gateway é um serviço auto-hospedado que fica entre os clientes Claude Code dos seus desenvolvedores e seu provedor de modelo. Os desenvolvedores fazem login com seu provedor de identidade corporativo (IdP) em vez de manter chaves de API ou credenciais de nuvem. O gateway mantém a credencial upstream, aplica acesso a modelos e configurações gerenciadas por grupo IdP, e retransmite telemetria de uso para sua própria pilha de observabilidade.

Está incluído no binário claude, então o mesmo executável que executa Claude Code em um laptop executa o servidor gateway com claude gateway --config gateway.yaml.

Esta página cobre:

• Por que Claude apps gateway, o que adiciona em relação a executar o seu próprio, e quando algo mais se encaixa melhor
• Um guia de início rápido com pré-requisitos que leva um gateway de zero a um desenvolvedor conectado
• Conectando desenvolvedores, incluindo definir a URL do gateway através de configurações gerenciadas
• Disponibilidade e limitações cobrindo quais recursos do Claude Code funcionam através do gateway e o que o servidor suporta

As páginas complementares vão mais fundo. A referência de configuração cobre todas as opções no arquivo YAML que o guia de início rápido escreve, e o guia de implantação cobre configuração por IdP, implantação em Kubernetes e Cloud Run, e operações.

Por que Claude apps gateway

A visão geral do gateway cobre o que um gateway faz e por que você executaria um. Claude apps gateway é o próprio gateway da Anthropic, integrado ao binário claude e testado junto com cada lançamento do Claude Code, então encaminha os cabeçalhos e campos de solicitação que Claude Code envia sem operadores mantendo uma lista de permissões separada. Uma vez implantado, ele oferece:

• Credenciais: a chave de API upstream ou credencial de nuvem vive apenas em sua infraestrutura. Os desenvolvedores se autenticam com SSO corporativo e recebem tokens de portador de curta duração, então o offboarding acontece em seu IdP. Desprovisione um usuário e seu acesso ao gateway expira dentro do tempo de vida da sessão, uma hora por padrão.
• Controle de acesso: seus grupos IdP mapeiam para listas de permissões de modelos e políticas de configurações gerenciadas. O gateway aplica acesso a modelos no lado do servidor, rejeitando solicitações para modelos não concedidos, e seleciona a política de configurações gerenciadas de cada grupo, que a CLI aplica no nível de configurações gerenciadas. Diferentes equipes obtêm diferentes modelos, ferramentas e permissões, e um desenvolvedor não pode substituir o que sua política bloqueia.
• Entrega de configurações: o gateway entrega configurações gerenciadas para clientes conectados, assumindo o lugar das configurações gerenciadas pelo servidor do console administrativo claude.ai.
• Telemetria: cada destino configurado recebe métricas do OpenTelemetry Protocol (OTLP) com contagens de tokens, modelo, identidade do usuário e latência por padrão, com logs e rastreamentos como opt-ins por destino.
• Roteamento upstream: os clientes falam a API de Mensagens Anthropic para o gateway, e o gateway traduz para cada upstream, seja Amazon Bedrock, Claude Platform on AWS, Agent Platform do Google Cloud, Microsoft Foundry ou a API Anthropic, com failover entre eles. Você pode alterar regiões, provedores ou ordem de failover sem que os desenvolvedores notem ou reconfiguram.

Para quais recursos do Claude Code funcionam através do gateway e o que o próprio servidor suporta, consulte Disponibilidade e limitações abaixo. Para decisões como custo, bypass, executar múltiplos gateways e plataformas sem servidor, consulte o guia de implantação.

Outras implementações de gateway

Se você já executa um gateway LLM ou gateway de API que atende às suas necessidades, continue usando-o; Outros gateways LLM cobre a configuração do Claude Code contra ele.

O guia de compatibilidade de gateway documenta o que Claude Code espera de qualquer gateway: os endpoints que chama, os cabeçalhos e campos de corpo para encaminhar, e o que para de funcionar quando são removidos. Um gateway de aplicativos Claude em execução também serve sua própria referência de protocolo em GET /protocol, que descreve os endpoints que expõe para clientes Claude Code: sign-in SSO, inferência, entrega de configurações gerenciadas, descoberta de modelos e telemetria. Busque-o com curl https://claude-gateway.internal.example.com/protocol de qualquer gateway implantado, como o que o guia de início rápido abaixo produz.

Mudanças significativas no protocolo são anunciadas com antecedência, mas compatibilidade retroativa indefinida não é garantida.

Guia de início rápido

Este guia de início rápido percorre o caminho mínimo: registre um cliente OAuth em seu IdP, escreva um gateway.yaml, execute o gateway junto com Postgres usando Docker Compose, e verifique o sign-in de ponta a ponta. Usa um upstream Amazon Bedrock; Claude Platform on AWS, Agent Platform do Google Cloud, Microsoft Foundry e a API Anthropic são igualmente suportados trocando o bloco upstreams conforme mostrado na referência de configuração. No final você tem um gateway que um desenvolvedor pode fazer /login.

Pré-requisitos

Tenha estes em vigor antes de começar:

Etapas

listen:
host: 0.0.0.0
port: 8080
# Obrigatório a menos que o host seja um endereço loopback. Usado para o IdP
# redirect_uri e o documento de descoberta.
public_url: https://claude-gateway.internal.example.com

oidc:
issuer: https://login.example.com        # deve servir /.well-known/openid-configuration
client_id: 0oa1example2
client_secret: ${OIDC_CLIENT_SECRET}
allowed_email_domains: [example.com]        # rejeitar id_tokens fora de sua organização
userinfo_fallback: true                  # para IdPs cujo id_token omite email/grupos; inofensivo caso contrário

session:
jwt_secret: ${GATEWAY_JWT_SECRET}        # openssl rand -base64 32
ttl_hours: 1                             # também limita a latência de revogação no desprovisionamento de IdP

store:
postgres_url: ${GATEWAY_POSTGRES_URL}    # adicione ?sslmode=require para Postgres gerenciado

upstreams:
- provider: bedrock
region: us-east-1
auth: {} # vazio: cadeia de credencial padrão da AWS
# (IRSA, função de tarefa EC2/ECS, variáveis de ambiente, ~/.aws)

# Os modelos são traduzidos por upstream automaticamente. O catálogo integrado
# mapeia claude-opus-4-8 para us.anthropic.claude-opus-4-8 e assim por diante para cada
# modelo Claude suportado pelo Bedrock. Defina como false e adicione uma lista `models:` para
# expor apenas modelos específicos.
auto_include_builtin_models: true

services:
gateway:
image: registry.example.com/claude-gateway:2.1.198
ports: ["8080:8080"]
volumes: ["./gateway.yaml:/etc/claude/gateway.yaml:ro"]
environment:
OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}
GATEWAY_JWT_SECRET: ${GATEWAY_JWT_SECRET}
GATEWAY_POSTGRES_URL: postgres://gw:pw@postgres/gateway
# Credenciais AWS: em produção, omita estas e use uma função de instância.
# Para teste local do Compose, passe as suas próprias:
AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}
AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}
AWS_SESSION_TOKEN: ${AWS_SESSION_TOKEN}
depends_on:
postgres:
condition: service_healthy
postgres:
image: postgres:16-alpine
environment: { POSTGRES_USER: gw, POSTGRES_PASSWORD: pw, POSTGRES_DB: gateway }
healthcheck:
test: ["CMD-SHELL", "pg_isready -U gw"]
interval: 5s
volumes: ["pgdata:/var/lib/postgresql/data"]
volumes: { pgdata: }

{"ts":"2026-06-10T17:03:21.114Z","evt":"config.load","path":"/etc/claude/gateway.yaml","sha256":"…"}
[gateway] 2026-06-10T17:03:21.395Z info waiting for migration lock (another replica may be migrating; check pg_locks for key 6775156 if this persists)
[gateway] 2026-06-10T17:03:21.408Z info migration 1 applied
…
[gateway] 2026-06-10T17:03:21.431Z info migration 6 applied
[gateway] 2026-06-10T17:03:21.512Z info claude gateway listening on http://0.0.0.0:8080

curl -s https://claude-gateway.internal.example.com/.well-known/oauth-authorization-server | jq

{
"issuer": "https://claude-gateway.internal.example.com",
"device_authorization_endpoint": "…/oauth/device_authorization",
"token_endpoint": "…/oauth/token",
"grant_types_supported": ["urn:ietf:params:oauth:grant-type:device_code", "refresh_token"]
}

curl -s -X POST https://claude-gateway.internal.example.com/oauth/device_authorization | jq

{
"device_code": "…",
"user_code": "WDJB-MJHT",
"verification_uri": "https://claude-gateway.internal.example.com/device",
"verification_uri_complete": "https://claude-gateway.internal.example.com/device?user_code=WDJB-MJHT",
"expires_in": 600,
"interval": 5
}

Conectar desenvolvedores

Os desenvolvedores se conectam de seus próprios laptops com um sign-in de navegador, usando sua conta de trabalho corporativa. Eles não precisam de uma conta claude.ai, uma chave de API ou uma assinatura, porque as solicitações para o modelo passam pelo gateway usando a credencial upstream da organização. A conexão é orientada pelas configurações gerenciadas no lado do cliente que você envia via MDM, então não há configuração manual no lado do desenvolvedor; esta seção cobre o que o administrador configura.

A CLI coloca a impressão digital do certificado TLS folha do gateway na primeira conexão e a fixa por nome de host. Ela verifica esse pino novamente durante o sign-in, em atualizações de sessão silenciosas e em buscas de configurações gerenciadas, enquanto solicitações de inferência usam validação TLS padrão sem o pino. Solicitações roteadas através de um proxy HTTPS pulam a verificação de pino, então adicione o host do gateway a NO_PROXY para mantê-las diretas.

Publique a impressão digital SHA-256 esperada junto com a URL do gateway para que os desenvolvedores tenham algo para comparar. O prompt /login mostra os primeiros 16 caracteres da impressão digital como hexadecimal minúsculo sem dois-pontos. Para imprimir a impressão digital completa nesse formato a partir do arquivo de certificado, execute:

openssl x509 -noout -fingerprint -sha256 -in cert.pem | cut -d= -f2 | tr -d : | tr 'A-F' 'a-f'

Quando o certificado é rotacionado, cada desenvolvedor vê o prompt de confiança novamente, então trate rotações como um evento planejado e republique a impressão digital. Se sua política de gateway incluir configurações que precisam de aprovação, o desenvolvedor também vê esse diálogo de aprovação novamente após aceitar o novo certificado, porque Claude Code vincula memória de aprovação ao certificado fixado.

Um gateway pode retornar o campo email opcional em sua resposta de token para nomear a conta que um sign-in usou. Quando faz isso, o desenvolvedor confirma a conta antes de Claude Code salvar a credencial. Após um sign-in confirmado, /status mostra a conta.

A confirmação requer Claude Code v2.1.275 ou posterior na máquina do desenvolvedor; um cliente abaixo dessa versão ignora o campo. O servidor do gateway no binário claude não retorna o campo, então seus sign-ins são concluídos sem a confirmação.

Uma vez que o desenvolvedor faz login, o seletor de modelo mostra os modelos na lista de permissões availableModels do desenvolvedor. As configurações gerenciadas se aplicam na inicialização e atualizam a cada hora, e a telemetria é roteada para seu coletor.

As sessões são atualizadas silenciosamente antes da expiração de ttl_hours. Quando uma atualização falha após desprovisionamento de IdP, Claude Code solicita que o desenvolvedor faça login novamente.

Defina a URL do gateway

Três chaves vão no arquivo de configurações gerenciadas por SO que você implanta via MDM ou diretamente no disco. forceLoginMethod e forceLoginGatewayUrl abrem /login diretamente na tela Cloud gateway com a URL preenchida, e parentSettingsBehavior: "merge" permite que Claude Desktop entregue a lista de permissões de egresso do gateway para as sessões Claude Code que ele inicia, explicado em Entregar política para sessões Claude Desktop:

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

O desenvolvedor pressiona Enter para se conectar. O prompt de impressão digital TLS de primeira conexão ainda aparece. Uma vez que o arquivo está em uma máquina, um desenvolvedor que não completou o sign-in do gateway vê uma das mensagens descritas em A política do administrador requer um sign-in Cloud gateway. Desenvolvedores que selecionam um provedor de nuvem através de uma variável de ambiente como CLAUDE_CODE_USE_BEDROCK não precisam do sign-in do gateway.

Um desenvolvedor não pode configurar isso manualmente. O seletor de login não tem opção de gateway, e forceLoginGatewayUrl é ignorado nos arquivos de configurações próprias de um desenvolvedor. forceLoginMethod sozinho, sem uma URL, deixa o desenvolvedor em uma mensagem "Entre em contato com seu administrador de TI". As chaves de login pertencem ao arquivo que você envia para máquinas, não ao bloco managed.policies[].cli do gateway, que só alcança clientes que já estão conectados.

Permitir um gateway em espaço de endereço público que você possui

Algumas organizações numerem sua rede interna a partir de um bloco IPv4 público que possuem, como o espaço de endereço próprio de uma operadora ou um /8 legado, então seu gateway não pode ter um endereço privado. Liste esses blocos na configuração gerenciada gatewayInternalNetworks. /login então aceita um gateway dentro de um bloco listado quando a máquina do desenvolvedor se conecta a ele a partir de um endereço dentro do mesmo bloco. Isso requer Claude Code v2.1.268 ou posterior na máquina do desenvolvedor; versões anteriores ignoram a chave e aplicam a regra de endereço privado.

Adicione a chave à mesma fonte de configurações gerenciadas que as chaves de login: o arquivo de configurações gerenciadas, perfil MDM ou política de registro. Claude Code a ignora em configurações de usuário, projeto e gerenciadas pelo servidor.

Este exemplo declara um bloco. Substitua 203.0.113.0/24 pelo seu próprio bloco. É um intervalo de documentação, e Claude Code recusa aqueles.

{
  "gatewayInternalNetworks": ["203.0.113.0/24"]
}

Claude Code valida a lista em /login antes de contatar qualquer gateway:

• Cada entrada é um bloco IPv4 escrito como seu primeiro endereço e um prefixo de /8 a /32.
• A lista contém no máximo quatro blocos, e nenhum dois se sobrepõem.
• Nenhum bloco se sobrepõe ao espaço de endereço privado: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8, 169.254.0.0/16 e 100.64.0.0/10. /login já aceita um gateway lá sem essa chave.
• Nenhum bloco se sobrepõe ao espaço que nunca é a rede de uma organização: 198.18.0.0/15 e 192.0.0.0/24, que clientes VPN e NAT64 mantêm como endereços locais; os intervalos de documentação 192.0.2.0/24, 198.51.100.0/24 e 203.0.113.0/24; e os intervalos reservados 0.0.0.0/8, 192.88.99.0/24 e multicast 224.0.0.0/4. Você pode declarar blocos dentro de 240.0.0.0/4, que algumas redes grandes usam como espaço unicast interno.

Blocos de managed-settings.json e seus arquivos drop-in managed-settings.d/ se combinam em uma lista, e esses limites se aplicam à lista combinada. Para estreitar um bloco, substitua sua entrada em vez de adicionar uma segunda, sobreposta em um drop-in; /login recusa a sobreposição.

Se uma entrada quebra uma regra, ou o valor não é uma lista de strings, Claude Code recusa cada novo sign-in de gateway nessa máquina e nomeia o problema na mensagem. O sign-in para um gateway em um endereço privado também falha, e sign-ins existentes continuam funcionando. Tente o valor em uma máquina antes de implantá-lo. Claude Code também lista um valor digitado incorretamente entre as configurações gerenciadas inválidas que relata.

Com uma lista válida, /login aplica três verificações a um gateway cujo endereço está dentro de um bloco listado:

• Cada endereço para o qual o nome de host do gateway é resolvido está dentro daquele bloco. Claude Code recusa um nome que também tem registros fora dele, endereços privados e IPv6 incluídos.
• A máquina do desenvolvedor se conecta de dentro do mesmo bloco. Claude Code recusa uma máquina atrás de NAT, dentro de um container ou WSL2, ou em uma VPN cujo pool de endereços fica fora do bloco, e nomeia o endereço a partir do qual a máquina se conectou.
• A conexão é direta. Se HTTPS_PROXY se aplica ao host do gateway, /login recusa e nomeia a entrada NO_PROXY a adicionar.

Quando todos os três passam, o prompt de confiança adiciona uma linha nomeando o endereço da máquina, o endereço do gateway e o bloco declarado que contém ambos.

A chave não muda nada para outros gateways: o sign-in para um em um endereço privado funciona como antes, e o sign-in para um em um endereço público fora de cada bloco listado é recusado como antes.

Um bloco declarado estreita quem pode fazer sign-in mas não prova onde uma máquina está, então declare apenas espaço de endereço que sua organização controla. Um bloco compartilhado com outros tenants, como um intervalo público de um provedor de nuvem, deixa qualquer um nele passar na mesma verificação.

Entregar política para sessões Claude Desktop

Claude Desktop executa suas abas Cowork e Code, mais a aba Chat quando você a habilita, em sessões Claude Code incorporadas e envia suas solicitações de modelo através do gateway. Ele passa política para cada uma dessas sessões, construída a partir da configuração que o gateway serve em /user/bootstrap: a lista de permissões de modelo, ferramentas desabilitadas e lista de permissões de egresso derivada do bloco cli da política correspondente, mais a sobreposição desktop.

Outras chaves cli, como hooks, env e regras de permissão com escopo como Bash(npm *), alcançam apenas clientes que fazem login através de /login. Claude Desktop lê a URL do gateway de sua própria configuração gerenciada e faz login com seu próprio fluxo, separado das chaves forceLoginMethod e forceLoginGatewayUrl em Defina a URL do gateway.

As configurações passadas por um processo de inicialização são configurações pai. Claude Code ignora configurações pai em qualquer máquina que tenha uma fonte gerenciada implantada por administrador, a menos que a fonte que entrega a política defina parentSettingsBehavior: "merge".

Quais máquinas precisam da aceitação

Máquinas que executam apenas Claude Desktop precisam dela. Claude Desktop aplica a lista de modelos e a lista de ferramentas desabilitadas às sessões incorporadas em si, mas a lista de permissões de egresso as alcança apenas como configurações pai, na forma de regras de domínio WebFetch e regras de rede sandbox. Sem a aceitação, essas sessões são executadas sem a restrição de egresso, e nada o avisa. O gateway ainda rejeita solicitações de inferência para modelos que a política não concede.

Máquinas onde desenvolvedores fazem login através de /login não precisam dela; cada sessão Claude Code busca sua política do gateway.

Frotas cujo policyHelper fornece configurações gerenciadas não podem usá-la: Claude Code nunca mescla configurações pai nessas frotas, porque lê configurações gerenciadas apenas da saída do helper.

Defina a aceitação

Implante o trecho de configurações gerenciadas de Defina a URL do gateway, espelhe-o para qualquer fonte no lado do cliente que supere o arquivo, então verifique.

Restringir configurações pai

Uma vez que você implante parentSettingsBehavior: "merge", qualquer processo host que inicie Claude Code pode fornecer configurações pai, não apenas Claude Desktop mas também um aplicativo Agent SDK ou uma extensão IDE.

Claude Code filtra configurações pai contra uma lista de permissões de chaves restritivas, mas algumas chaves permitidas podem conceder acesso em vez de restringir. A menos que você defina os bloqueios allowManaged*Only, regras de permissão de acesso e listas de permissões de sandbox fornecidas pelo host ainda se aplicam. As regras de negação e pergunta da sua política permanecem em vigor de qualquer forma; elas são avaliadas antes de qualquer regra de acesso.

Claude Code encaminha entradas sandbox.credentials fornecidas pelo pai em forma reduzida:

• Entradas deny: encaminhadas apenas com seu path ou name e o modo.
• Entradas de arquivo com mode: mask: encaminhadas apenas com sentinela, como uma máscara de arquivo inteiro cujo injectHosts é a lista vazia, então o proxy nunca substitui o valor real por uma entrada fornecida pelo pai em qualquer plataforma. Todos os campos de mascaramento estruturado também são descartados, então um padrão de extração fornecido pelo pai não pode deslocar uma máscara mais rigorosa que outra fonte define para o mesmo caminho.
• Entradas envVars com mode: mask: não encaminhadas. deny é a única restrição que o canal pai pode expressar através de entradas envVars.
• awsPairs e sigv4: encaminhadas apenas restrição. De sigv4, apenas valores deny são mantidos, e um pai que define um bloco sigv4 em tudo fixa todas as três formas de solicitação, streaming, presigned e sigv4a, para deny. Um par awsPairs nunca é encaminhado em uma forma que possa re-assinar; um par que nomeia uma das variáveis AWS convencionais é substituído por uma entrada inerte que mantém o emparelhamento automático de AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY e AWS_SESSION_TOKEN suprimido.

Implante os bloqueios

Para manter configurações pai tão próximas de apenas restrição quanto o filtro suporta, adicione todos os cinco bloqueios allowManaged*Only e as listas de permissões que eles governam às mesmas fontes que a aceitação de mesclagem:

{
  "forceLoginMethod": "gateway",
  "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com",
  "parentSettingsBehavior": "merge",
  "allowManagedPermissionRulesOnly": true,
  "allowManagedMcpServersOnly": true,
  "allowManagedHooksOnly": true,
  "allowedMcpServers": [{ "serverUrl": "https://mcp.internal.example.com/*" }],
  "sandbox": {
    "network": {
      "allowManagedDomainsOnly": true,
      "allowedDomains": ["github.com", "*.npmjs.org"]
    },
    "filesystem": {
      "allowManagedReadPathsOnly": true,
      "denyRead": ["~/"],
      "allowRead": ["~/projects"]
    }
  }
}

Uma política do SO, como uma política de registro HKLM ou um plist de preferências gerenciadas, supera esse arquivo, então entregue o trecho inteiro através dela em vez do arquivo. As configurações gerenciadas remotas do gateway superam as fontes de política do SO e arquivo mas alcançam apenas clientes conectados. Espelhe os bloqueios, as listas de permissões e a aceitação de mesclagem no bloco cli da política e mantenha esse arquivo implantado, porque máquinas que nunca se conectam, incluindo aquelas que executam apenas Claude Desktop, obtêm sua política apenas do arquivo.

Comportamento de bloqueio entre fontes

Definir um bloqueio não restringe os outros; cada chave é documentada na referência de configurações. De uma fonte de administrador abaixo do vencedor, os dois bloqueios de sandbox ainda se aplicam, e allowManagedPermissionRulesOnly ainda bloqueia regras de acesso fornecidas pelo pai e additionalDirectories. No Claude Code v2.1.273 ou posterior, o bloqueio de servidor MCP também se aplica de uma fonte abaixo do vencedor, e enquanto estiver ativado, a lista gerenciada allowedMcpServers vem da fonte de administrador de prioridade mais alta que define uma.

O bloqueio de hooks e o efeito de allowManagedPermissionRulesOnly nas regras próprias do desenvolvedor precisam da fonte vencedora por padrão; sob a aceitação de mesclagem managedSourcesBehavior em como Claude Code combina fontes gerenciadas, Claude Code aplica o valor mais rigoroso que qualquer fonte define para cada bloqueio. Em frotas policyHelper, Claude Code lê os bloqueios apenas da saída do helper.

Cada bloqueio faz Claude Code ignorar as entradas próprias do desenvolvedor para essa configuração, então inclua as listas de permissões da sua organização ao lado dos bloqueios:

• Domínios de rede: bloquear com uma lista de domínios gerenciados vazia bloqueia todo o tráfego de saída em sandbox.
• Servidores MCP: bloquear sem allowedMcpServers em qualquer fonte de administrador ou nas configurações fornecidas pelo pai carrega cada servidor que deniedMcpServers não bloqueia.
• Caminhos de leitura: entradas allowRead apenas re-permitem caminhos dentro de regiões denyRead, então emparelhe-as com um denyRead gerenciado.

Configurações que os bloqueios não cobrem

Quatro configurações fornecidas pelo pai passam pelo filtro mesmo com todos os cinco bloqueios definidos. Sob a configuração padrão de primeiro vencedor, o valor de administrador que bloqueia o do pai é aquele na fonte de administrador de prioridade mais alta, exceto para allowedMcpServers enquanto o bloqueio de servidor MCP está ativado. Sob a aceitação de mesclagem managedSourcesBehavior, como Claude Code combina fontes gerenciadas diz qual valor da fonte se aplica em vez disso.

• forceLoginOrgUUID: Claude Code honra um valor fornecido pelo pai quando a fonte de administrador de prioridade mais alta não define um UUID de organização. O sign-in do gateway não verifica essa chave, então importa apenas para frotas que também usam logins Anthropic de primeira parte. Um UUID de organização na fonte de administrador de prioridade mais alta bloqueia o valor do pai e é aquele que Claude Code aplica, então defina forceLoginOrgUUID lá.
• allowedMcpServers: Claude Code honra uma lista de permissões fornecida pelo pai quando nenhuma lista de administrador está em vigor. allowManagedMcpServersOnly não a bloqueia, porque o bloqueio aplica qualquer lista que vença como o valor gerenciado, incluindo uma lista fornecida pelo pai quando nenhuma fonte de administrador fornece uma lista. Uma lista na fonte de administrador de prioridade mais alta bloqueia a do pai e é a lista que Claude Code aplica, então defina allowedMcpServers lá, ao lado do bloqueio. Antes da v2.1.223, um valor para qualquer chave em qualquer fonte de administrador bloqueava a do pai.
• availableModels: Claude Code honra uma lista de modelos fornecida pelo pai quando a fonte gerenciada vencedora não define uma. Se sua frota restringe modelos, defina availableModels na fonte vencedora.
• strictPluginOnlyCustomization: essa chave passa pelo filtro independentemente de qualquer bloqueio, e faz Claude Code ignorar a customização própria do desenvolvedor, incluindo hooks protetores. Nenhum bloqueio a bloqueia.

Conectar Claude Desktop

Claude Desktop se conecta ao mesmo gateway através de uma chave MDM diferente: defina bootstrapUrl na configuração gerenciada do Claude Desktop para <listen.public_url>/user/bootstrap, e opte pela política do usuário com uma chave desktop. Sobreposição Claude Desktop cobre ambas as metades. Requer Claude Code v2.1.203 ou posterior no servidor do gateway.

Claude Desktop faz o desenvolvedor fazer login através do provedor de identidade do gateway com o mesmo passo de SSO do navegador, então busca sua configuração do gateway em vez de da Anthropic. O acesso a modelos e a política seguem as mesmas regras por grupo que a CLI. Um desenvolvedor que usa tanto a CLI quanto Claude Desktop faz login em cada um separadamente; a sessão do gateway não é compartilhada entre eles.

Uma vez conectado, Claude Desktop envia solicitações de modelo de cada aba habilitada através do gateway. Ele mostra as abas Cowork e Code por padrão. Para ativar também a aba Chat, defina chatTabEnabled para true na configuração gerenciada do Claude Desktop, ou no bloco desktop da política em um gateway executando Claude Code v2.1.227 ou posterior.

Pipelines de CI e máquinas remotas

Não há fluxo de token de serviço para pipelines não supervisionados. O sign-in do gateway sempre executa o fluxo de dispositivo do navegador, então um trabalho de CI sem um desenvolvedor para aprovar o sign-in não pode se autenticar; configure aqueles contra seu provedor diretamente.

Uma vez que um desenvolvedor tenha feito login, cada sessão Claude Code nessa máquina usa a sessão do gateway, incluindo execuções não interativas claude -p e sessões iniciadas pelo Agent SDK. Claude Code aplica a política do gateway a cada uma delas.

O fluxo de dispositivo separa a CLI de polling do navegador aprovador, então uma caixa de desenvolvimento remota sem exibição ainda funciona: o desenvolvedor executa /login via SSH na máquina remota e abre o link de verificação no navegador em seu laptop.

O que é aplicado aos desenvolvedores

Estas garantias se aplicam a cada sessão conectada através de /login. As sessões incorporadas que Claude Desktop inicia obtêm sua política conforme descrito em Entregar política para sessões Claude Desktop, e o ponto de telemetria diz para onde suas exportações vão.

• Acesso a modelos: solicitações para modelos que a política não concede retornam 400, e o seletor /model é filtrado para a lista de permissões availableModels da política. Defina enforceAvailableModels: true na política para que a opção Padrão resolva para um modelo dentro de availableModels em vez de para o padrão integrado do Claude Code; sem isso, Padrão permanece selecionável e é rejeitado no tempo de solicitação se esse modelo não for concedido.
• Destino de telemetria: em sessões conectadas através de /login, a CLI envia suas exportações OTLP/HTTP para o gateway em vez de para um OTEL_EXPORTER_OTLP_ENDPOINT definido localmente, a menos que uma política nomeie seu coletor como o endpoint. O gateway retransmite as exportações que recebe para os destinos em telemetry.forward_to.
  • Nas sessões incorporadas que Claude Desktop inicia, a CLI envia suas exportações para o OTEL_EXPORTER_OTLP_ENDPOINT configurado. A CLI anexa o token de sessão do gateway àquelas exportações apenas quando esse endpoint aponta para o próprio gateway.
  • Sem destino configurado para um sinal, o gateway o aceita e descarta.
  • Se você já coleta telemetria Claude Code diretamente, adicione seu coletor como um destino forward_to, ou nomeie-o em uma política para pular a retransmissão.
• Credenciais: o token do gateway é a única credencial da sessão. Perfis Anthropic e qualquer login anterior de claude.ai são ignorados enquanto conectado, então os desenvolvedores não precisam fazer logout de claude.ai primeiro. Para uma credencial ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN ou apiKeyHelper configurada, veja A política do administrador requer um sign-in Cloud gateway.
• Configurações gerenciadas: chaves bloqueadas não podem ser substituídas localmente. A CLI aplica a política na inicialização e aplica mudanças em cada sondagem horária, além das mudanças que se aplicam apenas no próximo lançamento.
• Inicialização com o gateway inacessível: sessões conectadas saem na inicialização com um erro após cerca de 10 segundos em vez de iniciar sem suas configurações.
• Inicialização após o gateway encerrar a sessão: veja Aplicar falha fechada na inicialização para quais lançamentos abrem desconectados do gateway e quais saem quando o gateway responde com um 401.
• Desprovisionamento: uma sessão cujo usuário é desabilitado no IdP expira dentro de ttl_hours quando a próxima atualização falha.
• Sign-out: /logout deleta a credencial do gateway da máquina do desenvolvedor.
  • Quando o documento de descoberta do gateway anuncia um revocation_endpoint no esquema, host e porta próprios da URL do gateway, /logout também envia os tokens armazenados para esse endpoint para que o gateway possa encerrar a sessão em seu lado. A solicitação é melhor esforço, então o sign-out é concluído na máquina do desenvolvedor independentemente de o endpoint responder. A revogação requer Claude Code v2.1.275 ou posterior na máquina do desenvolvedor.
  • O servidor do gateway no binário claude não anuncia nenhum, então um sign-out dele encerra a sessão na máquina do desenvolvedor apenas. Para forçar sessões para fora no lado do servidor, veja Rotação de segredo JWT.

O que a organização pode ver

A telemetria de uso carrega a identidade do desenvolvedor, contagens de tokens, modelo e latência para o coletor da organização. O gateway não registra ou armazena conteúdo de prompt ou conclusão. Se telemetria mais rica, como logs e rastreamentos, é coletada, que pode incluir comandos e caminhos de arquivo, é a escolha por destino da organização.

Disponibilidade e limitações

A tabela cobre quais recursos do Claude Code funcionam quando os desenvolvedores se conectam através do gateway e o que o próprio servidor gateway suporta. Onde algo não é suportado, a coluna Notas fornece a alternativa.

O gateway entrega os valores anthropic-beta que a CLI envia para cada upstream, então operadores não mantêm uma lista de permissões beta. Para Amazon Bedrock, que ignora o cabeçalho, o gateway move os valores para o campo anthropic_beta do corpo da solicitação; os outros upstreams recebem o cabeçalho conforme enviado.

Próximas etapas

O guia de início rápido deixa você com uma configuração mínima em execução sob Docker Compose. Para ir além:

• Expanda gateway.yaml além da configuração mínima, por exemplo para adicionar RBAC por grupo, failover multi-upstream ou destinos de telemetria. A referência de configuração cobre todas as opções.
• Mude do Compose para uma implantação de produção em Kubernetes ou Cloud Run, configure seu IdP adequadamente e revise o modelo de segurança. O guia de implantação e operações cobre configuração por IdP, requisitos de imagem de contêiner, sondas de saúde e solução de problemas.
• Coloque limites de gastos em desenvolvedores individuais ou grupos para que uma carga de trabalho descontrolada não possa consumir todo o seu compromisso. Limites de gastos cobre a API de administração e como a aplicação funciona.
• Para um exemplo completo trabalhado no AWS, com ECS Fargate ou EKS, Amazon RDS e Secrets Manager, consulte Implante no AWS.
• Para um exemplo completo trabalhado no Google Cloud, com Cloud Run, Cloud SQL e Secret Manager, consulte Implante no Google Cloud.