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) 指标，默认包含 token 计数、模型、用户身份和延迟，日志和跟踪作为按目标的选择加入。
• 上游路由：客户端向网关发送 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"
}

​

在用户设置中设置网关 URL

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

• 仅限用户设置：Claude Code 从 ~/.claude/settings.json 读取这两个键，而不会从项目的 .claude/settings.json 或 .claude/settings.local.json 读取。
• 托管设置会使其失效：一旦管理员的设置通过托管设置文件、macOS plist 或 Windows HKLM 策略，或策略帮助程序到达该机器，Claude Code 就会忽略用户设置中指定的网关。

​

允许位于您自有公网地址空间的网关

{
  "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 无需此键即可接受位于这些范围内的网关。
• 任何地址块都不得与绝不可能是组织网络的空间重叠：VPN 和 NAT64 客户端用作本地地址的 198.18.0.0/15 和 192.0.0.0/24；文档专用范围 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 内的地址块，一些大型网络将其用作内部单播空间。

• 网关主机名解析到的每个地址都位于同一个地址块内。如果某个名称还有位于该地址块之外的记录（包括私有地址和 IPv6 地址），Claude Code 会拒绝它。
• 开发人员的机器从同一地址块内进行连接。如果机器位于 NAT 之后、位于容器或 WSL2 内，或者使用地址池位于该地址块之外的 VPN，Claude Code 会拒绝，并指出该机器用于连接的地址。
• 连接是直接的。如果 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：当 Claude Code 应用的托管设置未设置组织 UUID 时，Claude Code 会采用父进程提供的值。网关登录不检查此键。Claude Code 应用的托管设置中的组织 UUID 会阻止父进程的值，并成为 Claude Code 强制执行的组织 UUID。如果您的机器群固定了某个 Anthropic 组织，请参阅哪个托管来源提供登录键，了解应在何处设置 forceLoginOrgUUID。
• allowedMcpServers：当没有生效的管理员列表时，Claude Code 会采用父进程提供的允许列表。allowManagedMcpServersOnly 不会阻止它，因为该锁定会将胜出的列表作为托管值强制执行，在没有管理员来源提供列表时，这也包括父进程提供的列表。最高优先级管理员来源中的列表会阻止父进程的列表，并成为 Claude Code 强制执行的列表，因此请在那里、在锁定旁边设置 allowedMcpServers。在 v2.1.223 之前，任何管理员来源中这两个键之一的值都会阻止父进程的值。
• availableModels：当胜出的托管来源未设置模型列表时，Claude Code 会采用父进程提供的模型列表。如果您的机器群限制模型，请在胜出来源中设置 availableModels。
• allowedProviders：当胜出的托管来源未设置 API 提供商允许列表时，Claude Code 会采用父进程提供的该列表。如果您的机器群限制开发人员可以使用的 API 提供商，请在胜出来源中设置 allowedProviders。需要 Claude Code v2.1.285 或更高版本。
• strictKnownMarketplaces：当胜出的托管来源未设置插件市场允许列表时，Claude Code 会采用父进程提供的该列表。当 Claude Desktop 2.16120.0 或更高版本的托管配置关闭用户添加的插件市场时，它会发送该列表。如果您的机器群限制市场，请在胜出来源中设置 strictKnownMarketplaces。需要 Claude Code v2.1.282 或更高版本。
• blockedMarketplaces：父进程提供的市场拒绝列表会通过，并添加到托管来源设置的任何拒绝列表中，因为拒绝列表只会进一步增加限制。需要 Claude Code v2.1.282 或更高版本。
• strictPluginOnlyCustomization：无论设置了何种锁定，此键都会通过过滤器，并且它会让 Claude Code 忽略开发人员自己的自定义内容，包括保护性 hook。没有任何锁定能阻止它。

​

父设置中的 hook 和 skill 键如何生效

• 停止：用户、项目和本地 hook，以及在 Agent frontmatter 或 SDK 的 settings 选项中声明的 hook。
• 继续运行：您的应用程序的 SDK hook 回调以及来自托管设置的管理员 hook。您的应用程序无法关闭管理员的 hook。

​

连接 Claude Desktop

​

CI 流水线和远程机器

​

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

• 模型访问：针对策略未授予的模型的请求会返回 400，/model 选择器会被筛选为策略的 availableModels 允许列表。这也包括开发人员选择模型之前会话所使用的起始模型；请参阅让会话以策略允许的模型启动。
• 遥测目标：在通过 /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 gateway 登录。
• 托管设置：已锁定的键无法在本地覆盖。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 上部署。