Amazon Bedrock、Claude Platform on AWS、Google Cloud 和 Microsoft Foundry 的 Claude 應用程式閘道

• 為什麼使用 Claude 應用程式閘道、它相比自行執行增加了什麼，以及何時其他解決方案更合適
• 一個快速入門，包含先決條件，可將閘道從零開始設定為已登入的開發人員
• 連接開發人員，包括透過受管設定設定閘道 URL
• 可用性和限制，涵蓋哪些 Claude Code 功能可透過閘道運作，以及伺服器支援什麼

​

為什麼使用 Claude 應用程式閘道

• 認證：上游 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 省略電子郵件/群組的 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 任務角色、環境變數、~/.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，以便預設選項解析為 availableModels 內的模型，而不是 Claude Code 的內建預設值；沒有它，預設保持可選擇，如果該模型未被授予，則在請求時被拒絕。
• 遙測目的地：在透過 /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 認證，請參閱管理員原則要求雲端閘道登入。
• 受管設定：鎖定的金鑰無法在本地覆蓋。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 上部署。