View a markdown version of this page

Configure o Claude Code com o gateway de aplicativos Claude - Amazon CloudWatch
Capacidades geraisPré-requisitosImplantar o gatewayConecte os desenvolvedores ao gatewayEncaminhe a telemetria para o Amazon CloudWatchDisponibilidade e limitaçõesPróximas etapas

Configure o Claude Code com o gateway de aplicativos Claude

O gateway de aplicativos Claude é um serviço auto-hospedado que fica entre os clientes Claude Code de seus desenvolvedores e o provedor do modelo. Os desenvolvedores fazem login com seu provedor de identidades (IdP) corporativas em vez de manter as chaves da API ou as credenciais da nuvem. O gateway contém a credencial upstream, impõe o acesso ao modelo e as configurações gerenciadas pelo grupo de IdP e retransmite a telemetria de uso para sua pilha de observabilidade, incluindo o Amazon CloudWatch.

O gateway está incluído no binário claude. O mesmo executável que roda o Claude Code executa o gateway quando você passa o subcomando gateway com um arquivo de configuração.

Capacidades gerais

O gateway de aplicativos Claude fornece controle centralizado em várias dimensões.

  • Credenciais — A chave da API upstream reside somente na sua infraestrutura. Os desenvolvedores se autenticam por meio de SSO com tokens de curta duração.

  • Controle de acesso — Os grupos de IdP são mapeados para listas de permissões de modelos e políticas de configurações gerenciadas.

  • Entrega de configurações — O gateway fornece configurações gerenciadas para clientes conectados.

  • Telemetria — Encaminha métricas OTLP (contagem de tokens, modelo, identidade do usuário, latência) para seu coletor. Você pode distribuir para vários destinos, incluindo CloudWatch, Datadog, Splunk e ClickHouse.

  • Roteamento upstream — Os clientes utilizam a API Anthropic Messages. O gateway traduz para cada upstream com failover. Os upstreams compatíveis incluem Amazon Bedrock, Claude Platform on AWS, Agent Platform do Google Cloud, Microsoft Foundry e a API Anthropic.

Pré-requisitos

Antes de implantar o gateway, confirme se os seguintes requisitos foram atendidos.

Requisito Detalhes
Versão do Claude Code v2.1.195 ou posterior
Provedor de identidades Provedor do OpenID Connect (OIDC), como Okta, Microsoft Entra ID, Google Workspace, Keycloak ou Dex
Banco de dados PostgreSQL 14 ou mais recente
Modelo upstream Credenciais Amazon Bedrock, Claude Platform on AWS, Google Cloud, Microsoft Foundry ou chave de API Anthropic
TLS Certificado HTTPS ou ingress com terminação TLS
Rede Endereço de rede privada (RFC 1918, link-local, CGNAT, IPv6 ULA ou loopback)
Runtime Linux para produção (macOS somente para desenvolvimento local)

Implantar o gateway

O procedimento a seguir resume as etapas de início rápido. Para obter instruções detalhadas, consulte a Documentação do gateway de aplicativos Claude.

Para implantar o gateway de aplicativos Claude

  1. Registre um cliente OAuth em seu IdP. Defina o URI de redirecionamento como https://claude-gateway.your-domain/oauth/callback.

  2. Provisione um banco de dados PostgreSQL (qualquer instância do PostgreSQL 14 ou posterior). O gateway executa migrações de esquema na inicialização.

  3. Gravar um arquivo de configuração gateway.yaml. O exemplo mostrado a seguir mostra uma configuração mínima que utiliza o Amazon Bedrock como upstream.

    listen:
  host: 0.0.0.0
  port: 8080
  public_url: https://claude-gateway.internal.example.com

oidc:
  issuer: https://login.example.com
  client_id: 0oa1example2
  client_secret: ${OIDC_CLIENT_SECRET}
  allowed_email_domains: [example.com]
  userinfo_fallback: true

session:
  jwt_secret: ${GATEWAY_JWT_SECRET}
  ttl_hours: 1

store:
  postgres_url: ${GATEWAY_POSTGRES_URL}

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}

auto_include_builtin_models: true

  4. Execute o gateway. Você pode utilizar o Docker Compose ou executar o binário diretamente.

    claude gateway --config gateway.yaml

  5. Verifique a superfície de autenticação. Obtenha o documento de descoberta, solicite a autorização do dispositivo e teste o login do navegador no URL do gateway.

  6. Faça login como desenvolvedor para confirmar a conectividade de ponta a ponta.

Conecte os desenvolvedores ao gateway

Para direcionar as máquinas dos desenvolvedores para seu gateway, distribua as seguintes chaves de configurações gerenciadas por meio do gerenciamento de dispositivos móveis (MDM) ou de sua ferramenta de gerenciamento de configurações.

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

Depois de distribuir as configurações, cada desenvolvedor conclui as etapas seguintes.

Para fazer login pelo gateway

  1. Execute o comando /login no Claude Code.

  2. Pressione Enter na tela do gateway do Cloud.

  3. Conclua o login no navegador com seu IdP corporativo.

Após o login, o Claude Code roteia a inferência pelo gateway e o gateway exporta a telemetria para os destinos configurados.

Encaminhe a telemetria para o Amazon CloudWatch

O gateway oferece suporte à distribuição de OTLP/HTTP para vários coletores, com exportações com carimbo de identidade. Configure destinos de telemetria no arquivo gateway.yaml. Cada destino pode receber métricas, logs ou rastreamentos.

Quando você configura o CloudWatch como um destino de telemetria, o gateway marca cada exportação com a identidade do desenvolvedor do IdP. As métricas chegam com atributos de usuário, equipe e organização, assim, os mesmos painéis do Coding Agent Insights são preenchidos.

Para ver as opções completas de configuração de telemetria, veja a referência de configuração.

Disponibilidade e limitações

A tabela mostrada a seguir resume o que o gateway suporta e as limitações atuais.

Item Status
Upstreams compatíveis Amazon Bedrock, Claude Platform on AWS, Agent Platform do Google Cloud, Microsoft Foundry, API Anthropic
IdPs compatíveis Okta, Microsoft Entra ID, Google Workspace, Keycloak, Dex e outros provedores compatíveis com OIDC
Protocolo de telemetria OTLP/HTTP com distribuição para vários destinos
Runtime Linux para implantações de produção. O macOS é compatível somente com desenvolvimento local.
Versão mínima do Claude Code v2.1.195

Próximas etapas

Utilize os recursos mostrados a seguir para obter instruções detalhadas de implantação, opções de configuração e orientação operacional.

Depois que o gateway estiver enviando métricas para o CloudWatch, visualize os painéis conforme descrito em Visualize os painéis.