Amazon Bedrock、Claude Platform on AWS、Google Cloud 和 Microsoft Foundry 的 Claude 应用网关

• 为什么使用 Claude 应用网关，它相比自己运行的优势，以及何时其他解决方案更合适
• 一个快速入门，包含前置条件，可将网关从零配置到已登录的开发人员
• 连接开发人员，包括通过托管设置设置网关 URL
• 可用性和限制，涵盖哪些 Claude Code 功能可通过网关工作以及服务器支持什么

​

为什么使用 Claude apps gateway

• 凭证：上游 API 密钥或云凭证仅存在于您的基础设施中。开发人员使用公司 SSO 进行身份验证并接收短期的持有者令牌，因此离职发生在您的 IdP 中。取消配置用户，其网关访问权限在会话生命周期内过期，默认为一小时。
• 访问控制：您的 IdP 组映射到模型允许列表和托管设置策略。网关在服务器端强制执行模型访问，拒绝非授予模型的请求，并选择每个组的托管设置策略，CLI 在托管设置层应用该策略。不同的团队获得不同的模型、工具和权限，开发人员无法覆盖其策略锁定的内容。
• 设置交付：网关本身将托管设置交付给已登录的客户端，取代来自 claude.ai 管理员控制台的服务器管理设置。
• 遥测：每个配置的目标接收OpenTelemetry Protocol (OTLP) 指标，默认包含令牌计数、模型、用户身份和延迟，日志和跟踪作为按目标的选择加入。
• 上游路由：客户端向网关发送 Anthropic Messages API，网关为每个上游进行转换，无论是 Amazon Bedrock、AWS 上的 Claude Platform、Google Cloud 的 Agent Platform、Microsoft Foundry 还是 Anthropic API，并在它们之间进行故障转移。您可以更改区域、提供商或故障转移顺序，而开发人员无需注意或重新配置。

​

其他网关实现

​

快速入门

​

前置条件

​

步骤

listen:
  host: 0.0.0.0
  port: 8080
  # 除非主机是环回地址，否则必需。用于 IdP
  # redirect_uri 和发现文档。
  public_url: https://claude-gateway.internal.example.com

oidc:
  issuer: https://login.example.com        # 必须提供 /.well-known/openid-configuration
  client_id: 0oa1example2
  client_secret: ${OIDC_CLIENT_SECRET}
  allowed_email_domains: [example.com]        # 拒绝组织外的 id_tokens
  userinfo_fallback: true                  # 对于 id_token 省略 email/groups 的 IdP；否则无害

session:
  jwt_secret: ${GATEWAY_JWT_SECRET}        # openssl rand -base64 32
  ttl_hours: 1                             # 也限制 IdP 取消配置时的撤销延迟

store:
  postgres_url: ${GATEWAY_POSTGRES_URL}    # 为托管 Postgres 添加 ?sslmode=require

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {} # 空：AWS 默认凭证链
# (IRSA, EC2/ECS task role, env vars, ~/.aws)

# 模型会自动按上游转换。内置目录
# 将 claude-opus-4-8 映射到 us.anthropic.claude-opus-4-8 等，
# 对于每个 Bedrock 支持的 Claude 模型。设置为 false 并添加 `models:` 列表以
# 仅公开特定模型。
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
      # AWS 凭证：在生产中，省略这些并使用实例
      # 角色。对于本地 Compose 测试，传递您自己的：
      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
}

​

连接开发人员

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

​

设置网关 URL

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

​

在您拥有的公共地址空间上允许网关

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

• 每个条目是一个 IPv4 块，写成其第一个地址和从 /8 到 /32 的前缀。
• 列表最多包含四个块，没有两个重叠。
• 没有块与私有地址空间重叠：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 和 100.64.0.0/10。/login 已经在没有此密钥的情况下接受那里的网关。
• 没有块与从不是组织网络的空间重叠：198.18.0.0/15 和 192.0.0.0/24，VPN 和 NAT64 客户端将其作为本地地址；文档范围 192.0.2.0/24、198.51.100.0/24 和 203.0.113.0/24；以及保留范围 0.0.0.0/8、192.88.99.0/24 和多播 224.0.0.0/4。您可以声明 240.0.0.0/4 内的块，某些大型网络将其用作内部单播空间。

• 网关主机名解析到的每个地址都在该块内。Claude Code 拒绝也在块外有记录的名称，包括私有和 IPv6 地址。
• 开发人员的机器从同一块内连接。Claude Code 拒绝 NAT 后面、容器或 WSL2 内或 VPN 上的机器，其地址池位于块外，并命名机器连接的地址。
• 连接是直接的。如果 HTTPS_PROXY 适用于网关主机，/login 拒绝并命名要添加的 NO_PROXY 条目。

​

将策略传递给 Claude Desktop 会话

​

哪些机器需要选择加入

​

设置选择加入

​

限制父设置

• deny 条目：仅使用其 path 或 name 和模式转发。
• 具有 mode: mask 的文件条目：转发为仅哨兵，作为整个文件掩码，其 injectHosts 是空列表，因此代理从不在任何平台上用真实值替换父提供的条目。所有结构化掩码字段也被删除，因此父提供的提取模式无法替代另一个源为同一路径设置的更严格掩码。
• 具有 mode: mask 的 envVars 条目：不转发。deny 是父通道可以通过 envVars 条目表达的唯一限制。
• awsPairs 和 sigv4：仅转发限制。从 sigv4，仅保留 deny 值，定义 sigv4 块的父将所有三种请求形式 streaming、presigned 和 sigv4a 固定到 deny。awsPairs 对从不以可以重新签名的形式转发；命名常规 AWS 变量之一的对被替换为保持 AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY 和 AWS_SESSION_TOKEN 自动配对被抑制的惯性条目。

​

部署锁

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

​

跨源的锁行为

• 网络域：使用空托管域列表锁定会阻止所有沙箱出站流量。
• MCP 服务器：使用任何管理员源或父提供的设置中都没有 allowedMcpServers 的锁会加载 deniedMcpServers 不阻止的每个服务器。
• 读取路径：allowRead 条目仅重新允许 denyRead 区域内的路径，因此将它们与托管 denyRead 配对。

​

锁不涵盖的设置

• forceLoginOrgUUID：当最高优先级管理员源未设置组织 UUID 时，Claude Code 尊重父提供的值。网关登录不检查此密钥。最高优先级管理员源中的组织 UUID 阻止父的值，是 Claude Code 强制执行的值。
• allowedMcpServers：当最高优先级管理员源未设置允许列表时，Claude Code 尊重父提供的允许列表，allowManagedMcpServersOnly 不阻止它，因为锁强制执行任何赢家列表作为托管值，包括当最高优先级管理员源未设置时的父提供列表。最高优先级管理员源中的列表阻止父的并是 Claude Code 强制执行的列表，因此在那里设置 allowedMcpServers，在锁旁边。在 v2.1.223 之前，任何管理员源中任一密钥的值都阻止父的。
• availableModels：当赢家托管源未设置模型列表时，Claude Code 尊重父提供的模型列表。如果您的舰队限制模型，在赢家源中设置 availableModels。
• strictKnownMarketplaces：当赢家托管源未设置一个时，Claude Code 尊重父提供的插件市场允许列表。如果您的舰队限制市场，在赢家源中设置 strictKnownMarketplaces。需要 Claude Code v2.1.282 或更高版本。
• blockedMarketplaces：父提供的市场阻止列表通过并添加到任何托管源设置的阻止列表，因为阻止列表只能进一步限制。需要 Claude Code v2.1.282 或更高版本。
• strictPluginOnlyCustomization：此密钥无论任何锁都通过过滤器，它使 Claude Code 忽略开发人员的自己定制，包括保护性 hooks。没有锁阻止它。

​

连接 Claude Desktop

​

CI 管道和远程机器

​

对开发人员强制执行的内容

• 模型访问：对策略未授予的模型的请求返回 400，/model 选择器被过滤到策略的 availableModels 允许列表。在策略中设置 enforceAvailableModels: true，以便 Default 选项解析为 availableModels 内的模型，而不是 Claude Code 的内置默认值；没有它，Default 保持可选，如果该模型未被授予，则在请求时被拒绝。
• 遥测目标：在通过 /login 登录的会话中，CLI 将其 OTLP/HTTP 导出发送到网关，而不是任何本地设置的 OTEL_EXPORTER_OTLP_ENDPOINT，除非策略将您的收集器命名为端点。网关将它接收的导出中继到 telemetry.forward_to 中的目标。
  • 在Claude Desktop 启动的嵌入式会话中，CLI 将其导出发送到配置的 OTEL_EXPORTER_OTLP_ENDPOINT。CLI 仅当该端点指向网关本身时才将网关会话令牌附加到这些导出。
  • 没有为信号配置目标时，网关接受并丢弃它。
  • 如果您已直接收集 Claude Code 遥测，将您的收集器添加为 forward_to 目标，或在策略中命名它以跳过中继。
• 凭证：网关令牌是会话的唯一凭证。Anthropic 配置文件和任何早期的 claude.ai 登录在登录时被忽略，因此开发人员不需要首先从 claude.ai 注销。对于配置的 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 或 apiKeyHelper 凭证，或早期 Claude Console 登录保存的 API 密钥，请参阅管理员策略需要 Cloud 网关登录。
• 托管设置：锁定的密钥无法在本地覆盖。CLI 在启动时应用策略，并在每个小时轮询时应用更改，除了仅在下一次启动时应用的更改。
• 启动时网关无法访问：已登录的会话在启动时约 10 秒后以错误退出，而不是在没有其设置的情况下启动。
• 启动后网关结束会话：请参阅强制执行故障关闭启动，了解哪些启动从网关登出打开，哪些在网关以 401 应答时退出。
• 取消配置：用户在 IdP 中被禁用的会话在下一次刷新失败时在 ttl_hours 内过期。
• 登出：/logout 从开发人员的机器删除网关凭证。
  • 当网关的发现文档在网关 URL 自己的方案、主机和端口上宣传 revocation_endpoint 时，/logout 也将存储的令牌发送到该端点，以便网关可以在其端结束会话。请求是尽力而为的，因此登出在开发人员的机器上完成，无论端点是否应答。撤销需要开发人员机器上的 Claude Code v2.1.275 或更高版本。
  • claude 二进制文件中的网关服务器不宣传任何，因此从它登出仅在开发人员的机器上结束会话。要强制会话从服务器端退出，请参阅 JWT 密钥轮换。

​

组织可以看到什么

​

可用性和限制

​

后续步骤

• 扩展 gateway.yaml 超越最小配置，例如添加按组 RBAC、多上游故障转移或遥测目标。配置参考涵盖每个选项。
• 从 Compose 迁移到 Kubernetes 或 Cloud Run 上的生产部署，正确设置您的 IdP，并审查安全模型。部署和操作指南涵盖每个 IdP 的设置、容器镜像要求、健康探针和故障排除。
• 对个别开发人员或组设置支出上限，以便失控的工作负载无法消耗您的整个承诺。支出限制涵盖管理 API 以及强制执行如何工作。
• 有关 AWS 上的完整工作示例，包括 ECS Fargate 或 EKS、Amazon RDS 和 Secrets Manager，请参阅在 AWS 上部署。
• 有关 Google Cloud 的完整工作示例，包括 Cloud Run、Cloud SQL 和 Secret Manager，请参阅在 Google Cloud 上部署。