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

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

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

• 憑證：上游 API 金鑰或雲端憑證僅存在於您的基礎設施中。開發人員使用公司 SSO 進行身分驗證並接收短期的持有人 token，因此離職處理在您的 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
  # Required unless host is a loopback address. Used for the IdP
  # redirect_uri and the discovery document.
  public_url: https://claude-gateway.internal.example.com

oidc:
  issuer: https://login.example.com        # must serve /.well-known/openid-configuration
  client_id: 0oa1example2
  client_secret: ${OIDC_CLIENT_SECRET}
  allowed_email_domains: [example.com]        # reject id_tokens outside your org
  userinfo_fallback: true                  # for IdPs whose id_token omits email/groups; harmless otherwise

session:
  jwt_secret: ${GATEWAY_JWT_SECRET}        # openssl rand -base64 32
  ttl_hours: 1                             # also bounds revocation latency on IdP deprovision

store:
  postgres_url: ${GATEWAY_POSTGRES_URL}    # add ?sslmode=require for managed Postgres

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {} # empty: AWS default credential chain
# (IRSA, EC2/ECS task role, env vars, ~/.aws)

# Models are translated per upstream automatically. The built-in catalog
# maps claude-opus-4-8 to us.anthropic.claude-opus-4-8 and so on for every
# Bedrock-supported Claude model. Set false and add a `models:` list to
# expose only specific 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 credentials: in production, omit these and use an instance
      # role. For local Compose testing, pass through your own:
      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 會拒絕該名稱。
• 開發人員的電腦從同一區塊內連線。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：當 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：當勝出的受管來源未設定時，Claude Code 會採用父程序提供的 API 供應商允許清單。如果您的機群限制開發人員可使用的 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 才會將閘道工作階段 token 附加到這些匯出資料上。
  • 若某個訊號沒有設定目的地，閘道會接受並捨棄它。
  • 如果您已直接收集 Claude Code 遙測，請將您的收集器新增為 forward_to 目的地，或在原則中指定它以略過轉送。
• 憑證：閘道 token 是工作階段唯一的憑證。登入期間會忽略 Anthropic 設定檔和任何先前的 claude.ai 登入，因此開發人員不需要先登出 claude.ai。關於已設定的 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 或 apiKeyHelper 憑證，或先前 Claude Console 登入所儲存的 API 金鑰，請參閱 Administrator policy requires a Cloud gateway sign-in。
• 受管設定：鎖定的鍵無法在本機覆寫。CLI 會在啟動時套用原則，並在每小時輪詢時套用變更，但僅在下次啟動時套用的變更除外。
• 閘道無法連線時的啟動：已登入的工作階段會在約 10 秒後以錯誤結束啟動，而不會在沒有其設定的情況下啟動。
• 閘道結束工作階段後的啟動：請參閱強制執行失敗即關閉的啟動，了解哪些啟動會以登出閘道的狀態開啟，以及哪些啟動會在閘道以 401 回應時結束。
• 取消佈建：使用者在 IdP 中被停用的工作階段，會在下次更新失敗時於 ttl_hours 內到期。
• 登出：/logout 會從開發人員的電腦刪除閘道憑證。
  • 當閘道的探索文件在與閘道 URL 本身相同的 scheme、主機和連接埠上公告 revocation_endpoint 時，/logout 也會將儲存的 token 傳送到該端點，讓閘道能在其端結束工作階段。此請求為盡力而為，因此無論端點是否回應，開發人員電腦上的登出都會完成。撤銷需要開發人員電腦上的 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 上部署。