View a markdown version of this page

使用 Claude 应用程序网关设置 Claude Code - Amazon CloudWatch
关键功能先决条件部署网关将开发人员连接到网关将遥测路由到 Amazon CloudWatch可用性和限制后续步骤

使用 Claude 应用程序网关设置 Claude Code

Claude 应用程序网关是一项自托管服务，其位于开发人员的 Claude Code 客户端和模型提供商之间。开发人员使用公司身份提供者（IdP）登录，而不是持有 API 密钥或云凭证。网关持有上游凭证，按 IdP 组强制执行模型访问和托管设置，并将使用情况遥测数据中继到可观测性堆栈（包括 Amazon CloudWatch）。

网关包含在 claude 二进制文件中。当您使用配置文件传递 gateway 子命令时，运行 Claude Code 的同一个可执行文件会运行网关。

关键功能

Claude 应用程序网关跨多个维度提供集中控制。

  • 凭证：上游 API 密钥仅存在于基础设施中。开发人员通过 SSO 使用短期令牌进行身份验证。

  • 访问控制：IdP 组映射到模型允许列表和托管设置策略。

  • 设置传输：网关向登录的客户端传输托管设置。

  • 遥测：将 OTLP 指标（令牌计数、模型、用户身份、延迟）路由到收集器。您可以扇出到多个目标（包括 CloudWatch、Datadog、Splunk 和 ClickHouse）。

  • 上游路由：客户端使用 Anthropic 消息 API。网关通过失效转移针对每个上游进行转换。支持的上游包括 Amazon Bedrock、AWS 云端 Claude Platform、Google Cloud 的 Agent Platform、Microsoft Foundry 和 Anthropic API。

先决条件

在部署网关之前，请确认满足下面的要求。

要求 说明
Claude Code 版本 v2.1.195 或更高版本
身份提供者 OpenID Connect（OIDC）提供商，例如 Okta、Microsoft Entra ID、Google Workspace、Keycloak 或 Dex
数据库 PostgreSQL 14 或更高版本
模型上游 Amazon Bedrock 凭证、AWS 云端 Claude Platform、Google Cloud、Microsoft Foundry 或 Anthropic API 密钥
TLS HTTPS 证书或 TLS 终止入口
Network 专用网络地址（RFC 1918、链路本地、CGNAT、IPv6 ULA 或环回）
运行时 Linux 适用于生产环境（macOS 仅适用于本地开发）

部署网关

以下过程总结了快速入门步骤。有关详细说明，请参阅 Claude 应用程序网关文档。

部署 Claude 应用程序网关

  1. 在 IdP 中注册 OAuth 客户端。将重定向 URI 设置为 https://claude-gateway.your-domain/oauth/callback。

  2. 预置 PostgreSQL 数据库（任何 PostgreSQL 14 或更高版本的实例）。网关会在启动时运行架构迁移。

  3. 编写 gateway.yaml 配置文件。以下示例展示了使用 Amazon Bedrock 作为上游的最低配置。

    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. 运行网关。您可以使用 Docker Compose，也可以直接运行二进制文件。

    claude gateway --config gateway.yaml

  5. 验证身份验证界面。获取发现文档，请求设备授权，并在网关 URL 上测试浏览器登录。

  6. 让开发人员登录以确认端到端连接。

将开发人员连接到网关

要将开发人员计算机指向网关，请通过移动设备管理（MDM）或配置管理工具分发以下托管设置密钥。

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

分发设置后，每位开发人员都需要完成下面的步骤。

通过网关登录

  1. 在 Claude Code 中运行 /login 命令。

  2. 在云网关屏幕上按 Enter。

  3. 使用公司 IdP 完成浏览器登录。

登录后，Claude Code 会通过网关路由推理，网关会将遥测导出到配置的目标。

将遥测路由到 Amazon CloudWatch

网关支持 OTLP/HTTP 扇出到多个收集器，并采用带有身份戳记的导出。在 gateway.yaml 文件中配置遥测目标。每个目标都可以接收指标、日志或跟踪。

当您将 CloudWatch 配置为遥测目标时，网关会使用来自 IdP 的开发人员身份标记每次导出。指标随用户、团队和组织属性一起到达，因此会填充相同的编程代理洞察控制面板。

有关完整的遥测配置选项，请参阅配置参考。

可用性和限制

下表总结了网关支持的内容和当前限制。

Item Status
支持的上游 Amazon Bedrock、AWS 云端 Claude Platform、Google Cloud 的 Agent Platform、Microsoft Foundry、Anthropic API
支持的 IdP Okta、Microsoft Entra ID、Google Workspace、Keycloak、Dex 以及其他符合 OIDC 标准的提供商
遥测协议 OTLP/HTTP，可扇出到多个目标
运行时 Linux 用于生产部署。macOS 仅支持本地开发。
最低 Claude Code 版本 v2.1.195

后续步骤

请使用下面的资源获取详细的部署说明、配置选项和操作指导。

  • Claude 应用程序网关文档：完整的设置指南，包括 Docker Compose 模板和 IdP 注册演练。

  • 配置参考：所有 gateway.yaml 选项的完整参考，包括遥测目标、上游路由和访问策略。

  • 部署指南：生产部署模式、扩展和运营最佳实践。

在网关向 CloudWatch 发送指标后，请按照 查看控制面板 中所述查看控制面板。