SpyBara
Go Premium

claude-apps-gateway.md 2026-10-03 23:57 UTC to 2026-10-04 17:00 UTC

This page contains 90 additions and 87 deletions.

2026
Sun 4 18:02

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

透過自託管閘道在 Amazon Bedrock、Claude Platform on AWS、Google Cloud 或 Microsoft Foundry 上執行 Claude Code，具備 SSO 登入、按群組模型存取和 OTLP 遙測功能。

Claude 應用程式閘道是一個自託管服務，位於開發人員的 Claude Code 用戶端和模型提供商之間。開發人員使用您的企業身份提供商 (IdP) 登入，而不是持有 API 金鑰或雲端認證。閘道持有上游認證，按 IdP 群組強制執行模型存取和受管設定，並將使用情況遙測轉發到您自己的可觀測性堆疊。

它包含在 claude 二進位檔中，因此在筆記型電腦上執行 Claude Code 的相同可執行檔可以使用 claude gateway --config gateway.yaml 執行閘道伺服器。

本頁涵蓋：

相關頁面會更深入地介紹。配置參考涵蓋快速入門寫入的 YAML 檔案中的每個選項，部署指南涵蓋每個 IdP 的設定、Kubernetes 和 Cloud Run 部署，以及操作。

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

閘道概述涵蓋閘道的功能以及為什麼要執行一個。Claude 應用程式閘道是 Anthropic 自己的閘道，內建於 claude 二進位檔中，並與每個 Claude Code 版本一起測試，因此它轉發 Claude Code 發送的標頭和請求欄位，無需操作員維護單獨的允許清單。部署後，它為您提供：

  • 認證：上游 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，並在它們之間進行故障轉移。您可以更改區域、提供商或故障轉移順序，而開發人員無需注意或重新配置。
圖表顯示 Claude Code 用戶端和 Claude Desktop 的 Chat、Cowork 和 Code 標籤透過 HTTPS 和持有人令牌連接到您基礎設施內的自託管 Claude 應用程式閘道，該閘道針對您的 IdP 簽署使用者，在 PostgreSQL 中儲存身份驗證狀態，將遙測轉發到您的 OTLP 收集器，並將推理轉發到 Amazon Bedrock、AWS 上的 Claude Platform、Google Cloud、Microsoft Foundry 或 Anthropic API

有關哪些 Claude Code 功能可透過閘道運作以及伺服器本身支援什麼，請參閱下面的可用性和限制。有關成本、繞過、執行多個閘道和無伺服器平台等決策，請參閱部署指南。

其他閘道實現

如果您已經執行滿足您需求的 LLM 閘道或 API 閘道，請繼續使用它；其他 LLM 閘道涵蓋針對它配置 Claude Code。

閘道相容性指南記錄了 Claude Code 期望從任何閘道的內容：它呼叫的端點、要轉發的標頭和正文欄位，以及當它們被剝離時停止運作的內容。執行中的 Claude 應用程式閘道也在 GET /protocol 提供其自己的協議參考，其中描述了它向 Claude Code 用戶端公開的端點：SSO 登入、推理、受管設定傳遞、模型探索和遙測。使用 curl https://claude-gateway.internal.example.com/protocol 從任何部署的閘道（例如下面快速入門產生的閘道）獲取它。協議的重大變更會提前宣佈，但不保證無限期的向後相容性。

快速入門

此快速入門走最小路徑：在您的 IdP 中註冊 OAuth 用戶端，寫入 gateway.yaml，使用 Docker Compose 與 Postgres 一起執行閘道，並驗證端到端登入。它使用 Amazon Bedrock 上游；Claude Platform on AWS、Google Cloud 的 Agent Platform、Microsoft Foundry 和 Anthropic API 同樣受支援，只需如配置參考所示交換 upstreams 區塊。最後，您有一個開發人員可以 /login 的閘道。

先決條件

在開始之前，請準備好以下內容：

您需要 詳細資訊
Claude Code v2.1.195 或更新版本 claude gateway 子命令和閘道登入流程在 v2.1.195 中發布。較早的公開版本不包含它們。執行閘道伺服器的機器和每個開發人員的機器都必須是 v2.1.195 或更新版本；執行 claude update 以取得最新版本。Claude Platform on AWS 上游在閘道伺服器上需要 Claude Code v2.1.198 或更新版本。
OpenID Connect (OIDC) 身份提供商 Okta、Microsoft Entra ID、Google Workspace、Keycloak 或 Dex，或任何其他符合 OIDC 的 IdP，例如 PingFederate。閘道針對它執行標準 OIDC 發現和授權碼流程。不支援 SAML 和 LDAP。
PostgreSQL 14 或更新版本 支援裝置登入流程，其中瀏覽器回呼寫入，輪詢 CLI 讀取，加上速率限制計數器。任何受管 Postgres 都可以，包括最小層級。在未配置支出限制的情況下，閘道儲存幾 KB 的短期身份驗證狀態；使用支出限制，它還持有應備份的耐久支出、稽核和身份表。建議透過 ?sslmode=require 使用 TLS。
模型上游 Amazon Bedrock 認證、Claude Platform on AWS 認證、Google Cloud 認證、Microsoft Foundry 資源或 Anthropic API 金鑰。支援多個上游和故障轉移。
HTTPS 閘道必須可從開發人員筆記型電腦和用於登入的任何瀏覽器透過 https:// 到達；閘道在同一監聽器上提供裝置驗證頁面。透過 listen.tls 提供 TLS 憑證，或在 TLS 終止入口後執行並設定 listen.public_url 為外部來源（兩種情況下都是如此）。純 http:// 來源僅在閘道主機為環回時接受：localhost、127.0.0.1 或 ::1。
私有網路地址 在 /login 處，Claude Code 要求閘道的主機名或 IP 地址僅解析為私有地址：RFC 1918、連結本地、CGNAT 100.64.0.0/10、IPv6 ULA fc00::/7 或環回。對於您託管的閘道，任何公開地址都會被拒絕；請參閱部署指南中的威脅模型。如果開發人員機器透過公司代理路由 HTTPS，登入還要求代理主機解析為私有地址；如果不是，將閘道主機新增到 NO_PROXY，以便 CLI 直接連接。如果您的內部網路是從您的組織擁有的公開 IPv4 空間編號的，宣告這些區塊，以便 /login 接受那裡的閘道。
Linux 執行時 閘道伺服器僅在原生 Linux 二進位檔上執行。macOS 適用於本地開發。Windows 不支援作為伺服器平台。

步驟

1

在您的 IdP 中註冊 OAuth 用戶端

首先決定閘道的主機名，因為重定向 URI 必須與其匹配。建立新的 OIDC Web 應用程式，並將重定向 URI 設定為 https://claude-gateway.<your-domain>/oauth/callback，其中主機是您在步驟 3 中設定為 listen.public_url 的相同值。記下 client_id 和 client_secret。每個 IdP 的說明在身份提供商設定中。

2

佈建 PostgreSQL 資料庫

任何 Postgres 14 或更新版本都可以，包括最小受管層級。閘道在啟動時執行自己的架構遷移，因此資料庫角色需要建立和更改表的權限；請參閱 store。

3

寫入 gateway.yaml

機密透過 ${ENV_VAR} 擴展讀取，因此檔案本身可以存在於版本控制中。使用在您的網路上解析為私有 IP 的 public_url 主機名，因為 /login 拒絕公開地址。最小配置有五個部分，其他每個欄位都有預設值：

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

此配置足以使用預設 Amazon Bedrock 模型目錄進行有效的登入迴圈。執行後，透過 managed.policies 新增按群組 RBAC 和受管設定、透過 telemetry 的遙測扇出，以及多上游故障轉移、佈建輸送量 ARN 或非美國區域，透過 models。

4

執行它

圍繞滿足映像要求的 claude 二進位檔建立容器映像，然後與 Postgres 一起執行它。Compose 檔案將映像參考為 registry.example.com/claude-gateway:2.1.198；替換您自己的登錄和映像標籤：

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: }

閘道是一個單一 Linux 二進位檔，讀取配置，連接到 Postgres 並應用其架構遷移，針對您的 IdP 執行 OIDC 發現，建立上游用戶端，並開始監聽。啟動對配置、Postgres 連接、OIDC 發現和上游用戶端構造是失敗關閉的。如果其中任何一個無法到達或配置錯誤，閘道會以錯誤退出，而不是以降級狀態提供流量。

成功啟動不驗證推理路徑，因為 Amazon Bedrock 和 Google Cloud 的 Agent Platform 執行個體認證在第一個請求時解析，而不是在啟動時。

監視 stderr 以了解啟動序列。日誌行使用格式 [gateway] <timestamp> <level> <message>，稽核事件是帶有 evt 欄位的單行 JSON，啟動橫幅（下面省略）在遷移和監聽行之間列印。新資料庫為每個架構遷移列印一個 migration N applied 行；已遷移的資料庫不列印任何行。您應該按順序看到：

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

閘道也會記錄一個警告，access_control.allow_cidrs 為空。這在這裡是預期的，因為在您設定允許清單之前，沒有任何東西限制閘道提供的用戶端地址。access_control 參考具有建議的範圍。

如果啟動在 claude gateway listening on 行之前退出，stderr 的最後一行命名問題：

  • 無法到達的 Postgres
  • 沒有 DDL 權限的 Postgres 角色
  • 無法到達或無效的 OIDC 發現文件
  • 配置架構違規，帶有違規欄位路徑

修復它並重新啟動。

如果您已經有 TLS 終止入口，請跳過 Compose 並直接使用 claude gateway --config gateway.yaml 執行二進位檔。將 public_url 設定為入口來源，並將 listen 綁定到環回或叢集內部地址。

5

驗證身份驗證表面

三個檢查確認閘道可以在將其交給開發人員之前驗證真實使用者。

示例使用閘道的公開 URL；對於沒有入口的本地 Compose 設定，在前兩個檢查中替換 http://localhost:8080。第三個檢查開啟 verification_uri_complete，它從 public_url 建立，因此對於本地 Compose，在 gateway.yaml 中設定 public_url: http://localhost:8080，並在步驟 1 的 OAuth 用戶端上新增 http://localhost:8080/oauth/callback 作為第二個重定向 URI，因為閘道從 public_url 建立 IdP redirect_uri。驗證連結然後在您的本地瀏覽器中開啟。

在 Windows PowerShell 中，執行 curl.exe；裸 curl 是 Invoke-WebRequest 的別名，拒絕這些標誌。

首先，獲取發現文件，確認閘道已啟動、配置有效且所有啟動檢查已通過：

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

回應包括其他欄位，例如 response_types_supported 和 scopes_supported。

其次，請求裝置授權，確認裝置登入流程有效且 Postgres 可到達且可寫：

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
}

第三，透過在瀏覽器中開啟 verification_uri_complete 並確認代碼來測試瀏覽器部分。您應該被重定向到您的 IdP 的登入頁面，登入後，返回閘道並顯示已登入確認。

使用第一個失敗的檢查來定位問題：

  • 第一個檢查失敗：啟動未完成；檢查 stderr
  • 第二個檢查失敗：Postgres 無法從閘道到達或角色無法寫入；檢查連接字串和授予
  • 第三個檢查無法到達 IdP：檢查 IdP 的重定向 URI 是否完全符合 https://<gateway>/oauth/callback
  • 第三個檢查到達 IdP 但以錯誤反彈：讀取閘道的稽核日誌，它記錄每個身份驗證拒絕及其原因，例如 email domain not allowed
6

登入開發人員

最後一步發生在開發人員機器上，而不是伺服器上。在該機器的受管設定檔中將 forceLoginMethod 設定為 "gateway" 並將 forceLoginGatewayUrl 設定為您的閘道的 public_url，然後執行 /login，在雲端閘道螢幕上按 Enter，並完成瀏覽器登入。下面的設定閘道 URL 涵蓋大規模分發兩個金鑰。

連接開發人員

開發人員從自己的筆記型電腦使用一次瀏覽器登入進行連接，使用他們的公司工作帳戶。他們不需要 claude.ai 帳戶、API 金鑰或訂閱，因為對模型的請求透過使用組織上游憑證的閘道進行。連接由您透過 MDM 推送的用戶端側受管設定驅動，因此開發人員端沒有手動設定；本節涵蓋管理員設定的內容。

CLI 在首次連接時對閘道的 TLS 葉憑證進行指紋識別，並按主機名固定它。它在登入期間、無聲工作階段重新整理期間和受管設定擷取期間再次檢查該固定，而推論請求使用標準 TLS 驗證而不使用固定。透過 HTTPS 代理伺服器路由的請求會跳過固定檢查，因此將閘道主機新增至 NO_PROXY 以保持它們直接連線。

發佈預期的 SHA-256 指紋以及閘道 URL，以便開發人員有可比較的內容。/login 提示顯示指紋的前 16 個字元作為小寫十六進位，無冒號。若要從憑證檔案以該形式列印完整指紋，請執行：

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

當憑證輪換時，每個開發人員都會再次看到信任提示，因此將輪換視為計劃事件並重新發佈指紋。如果您的閘道原則包含需要核准的設定，開發人員在接受新憑證後也會再次看到該核准對話框，因為 Claude Code 會將核准記憶綁定至固定的憑證。

閘道可以在其 token 回應中返回可選的 email 欄位，以命名登入使用的帳戶。當它這樣做時，開發人員在 Claude Code 儲存憑證之前確認帳戶。確認登入後，/status 顯示帳戶。

確認需要開發人員機器上的 Claude Code v2.1.275 或更新版本；低於該版本的用戶端會忽略該欄位。claude 二進位檔中的閘道伺服器不返回該欄位，因此其登入完成時沒有確認。

開發人員登入後，模型選擇器顯示其 availableModels 允許清單中的模型。受管設定在啟動時套用並每小時重新整理一次，遙測路由到您的收集器。

工作階段在 ttl_hours 過期前無聲重新整理。當 IdP 取消佈建後重新整理失敗時，Claude Code 會提示開發人員再次登入。

設定閘道 URL

三個設定鍵放入您透過 MDM 或直接在磁碟上部署的各 OS 受管設定檔。forceLoginMethod 和 forceLoginGatewayUrl 在雲端閘道畫面上直接開啟 /login，URL 已填入，而 parentSettingsBehavior: "merge" 讓 Claude Desktop 將閘道的出口允許清單傳遞給它啟動的 Claude Code 工作階段，詳見將原則傳遞給 Claude Desktop 工作階段：

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

開發人員按 Enter 進行連接。首次連接 TLS 指紋提示仍然出現。一旦檔案在機器上，未完成閘道登入的開發人員會看到管理員原則要求雲端閘道登入下所述的其中一則訊息。透過環境變數（例如 CLAUDE_CODE_USE_BEDROCK）選擇雲端提供商的開發人員不需要閘道登入。

開發人員無法手動設定此項。登入選擇器中沒有閘道選項，forceLoginGatewayUrl 在開發人員自己的設定檔中被忽略。單獨使用 forceLoginMethod 而沒有 URL，會讓開發人員停留在「聯絡您的 IT 管理員」訊息處。登入設定鍵應該在您推送到機器的檔案中，而不是在閘道的 managed.policies[].cli 區塊中，該區塊僅到達已連接的用戶端。

允許您擁有的公開位址空間上的閘道

某些組織從他們擁有的公開 IPv4 區塊（例如電信業者自己的位址空間或舊版 /8）對其內部網路進行編號，因此他們的閘道無法擁有私人位址。在 gatewayInternalNetworks 受管設定中列出這些區塊。/login 然後在開發人員的機器從同一區塊內的位址連接到它時，接受位於列出區塊內的閘道。這需要開發人員機器上的 Claude Code v2.1.268 或更新版本；較早的版本忽略該設定鍵並套用私人位址規則。

將設定鍵新增至與登入設定鍵相同的受管設定來源：受管設定檔、MDM 設定檔或登錄原則。Claude Code 在使用者、專案和伺服器受管設定中忽略它。

此範例宣告一個區塊。將 203.0.113.0/24 替換為您自己的區塊。它是文件範圍，Claude Code 拒絕這些。

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

Claude Code 在 /login 驗證清單，然後才聯絡任何閘道：

  • 每個項目是一個 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 內宣告區塊，某些大型網路將其用作內部單播空間。

來自 managed-settings.json 及其 managed-settings.d/ 插入檔案的區塊合併為一個清單，這些限制適用於合併後的清單。若要縮小區塊，請替換其項目，而不是在插入檔案中新增第二個重疊的項目；/login 會拒絕重疊。

如果項目違反規則，或值不是字串清單，Claude Code 會在該機器上拒絕每個新的閘道登入，並在訊息中指出問題。登入到私人位址上的閘道也會失敗，現有登入保持有效。在部署前先在一台機器上嘗試該值。Claude Code 也會在它報告的無效受管設定中列出類型錯誤的值。

使用有效清單時，/login 對位址位於列出區塊內的閘道套用三項檢查：

  • 閘道主機名解析到的每個位址都位於該同一區塊內。Claude Code 拒絕在區塊外也有記錄的名稱，包括私人和 IPv6 位址。
  • 開發人員的機器從同一區塊內連接。Claude Code 拒絕位於 NAT 後面、容器或 WSL2 內，或位址池位於區塊外的 VPN 上的機器，並指出機器連接所使用的位址。
  • 連接是直接的。如果 HTTPS_PROXY 適用於閘道主機，/login 會拒絕並指出要新增的 NO_PROXY 項目。

當三項都通過時，信任提示會新增一行，指出機器的位址、閘道的位址，以及同時包含兩者的宣告區塊。

該設定鍵對其他閘道不改變任何內容：登入到私人位址上的閘道像以前一樣有效，登入到所有列出區塊外的公開位址上的閘道像以前一樣被拒絕。

宣告的區塊縮小了誰可以登入，但無法證明機器的所在位置，因此僅宣告您的組織控制的位址空間。與其他租戶共享的區塊（例如雲端提供商的公開範圍）會讓其中的任何人通過相同的檢查。

將原則傳遞給 Claude Desktop 工作階段

Claude Desktop 在嵌入式 Claude Code 工作階段上執行其 Cowork 和 Code 標籤，以及您啟用時的 Chat 標籤，並透過閘道傳送其模型請求。它將原則傳遞給每個工作階段，原則由閘道在 /user/bootstrap 提供的設定建立：模型允許清單、停用的工具，以及從相符原則的 cli 區塊衍生的出口允許清單，加上 desktop 覆蓋。

其他 cli 設定鍵，例如 hook、env 和範圍權限規則（如 Bash(npm *)），僅到達透過 /login 登入的用戶端。Claude Desktop 從其自己的受管設定讀取閘道 URL，並使用其自己的流程登入，與設定閘道 URL 中的 forceLoginMethod 和 forceLoginGatewayUrl 設定鍵分開。

由啟動程序傳遞的設定是父設定。Claude Code 在任何具有管理員部署之受管來源的機器上忽略父設定，除非傳遞原則的來源設定了 parentSettingsBehavior: "merge"。

哪些機器需要選擇加入

僅執行 Claude Desktop 的機器需要它。Claude Desktop 會自行將模型清單和停用工具清單套用於嵌入式工作階段，但出口允許清單僅作為父設定到達它們，形式為 WebFetch 網域規則和沙箱網路規則。沒有選擇加入時，這些工作階段執行時沒有出口限制，且不會有任何警告。閘道仍然拒絕原則未授予之模型的推論請求。

外掛市集允許清單也僅作為父設定到達嵌入式工作階段。當您在 Claude Desktop 的受管設定中關閉使用者新增的外掛市集時，Claude Desktop 2.16120.0 或更新版本會隱藏您的組織未佈建的市集，並拒絕從它們安裝。為了阻止嵌入式工作階段載入已從這些市集安裝的外掛，它會將 strictKnownMarketplaces 清單作為父設定傳送給它們。沒有選擇加入時，Claude Code 會忽略該清單，這些外掛會繼續載入。

開發人員透過 /login 登入的機器不需要它；每個 Claude Code 工作階段從閘道擷取其原則。

由 policyHelper 提供受管設定的機隊無法使用它：Claude Code 在這些機隊上永遠不會合併父設定，因為它僅從 helper 的輸出讀取受管設定。

設定選擇加入

部署設定閘道 URL 中的受管設定片段，將其鏡像到任何優先於該檔案的用戶端側來源，然後驗證。

1

在受管設定檔中部署選擇加入

上面的片段已經包含 parentSettingsBehavior: "merge"，因此您推送到機器的檔案會攜帶它。

2

將片段鏡像到任何優先於該檔案的來源

Claude Code 僅從選定的來源讀取 parentSettingsBehavior。將任何原則設定鍵新增至某個來源可能會使該來源成為選定的來源，因此在用戶端側來源中，請鏡像整個片段，而不僅僅是 parentSettingsBehavior。用戶端側受管設定涵蓋透過群組原則或組態設定檔傳遞原則的機隊。macOS 上的受管偏好設定 plist 或 Windows 上的 HKLM 原則優先於 managed-settings.json 檔案，而閘道自己的遠端受管設定優先於兩者，因此在登入閘道的機器上，也要在閘道原則的 cli 區塊中設定 parentSettingsBehavior。

3

檢查選定的來源

在僅執行 Claude Desktop 的機器上，呼叫 Agent SDK 的 resolveSettings()，並讀取其 sources 清單中 managed 項目上的 policyOrigin。該值指出選定的用戶端側來源：plist、hklm 或 file，這就是必須攜帶片段的來源。Claude Desktop 的嵌入式工作階段不擷取閘道原則，因此閘道的 cli 區塊永遠不會被視為它們的選定來源。

限制父設定

一旦您部署 parentSettingsBehavior: "merge"，任何啟動 Claude Code 的主機程序都可以提供父設定，不僅是 Claude Desktop，還有 Agent SDK 應用程式或 IDE 擴充功能。

Claude Code 根據限制性設定鍵的允許清單篩選父設定，但某些允許的設定鍵可能會授予存取權而非加以限制。除非您設定 allowManaged*Only 鎖定，否則主機提供的權限允許規則和沙箱允許清單仍然適用。無論如何，您的原則的拒絕和詢問規則都保持有效；它們在任何允許規則之前進行評估。

Claude Code 以剝離形式轉發父提供的 sandbox.credentials 項目：

  • 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 的自動配對保持被抑制。

部署鎖定

為了讓父設定盡可能接近篩選器所支援的僅限制形式，請將全部五個 allowManaged*Only 鎖定及其管理的允許清單，新增至與合併選擇加入相同的來源：

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

OS 原則（例如 HKLM 登錄原則或受管偏好設定 plist）優先於此檔案，因此請透過它而不是檔案傳遞整個片段。閘道的遠端受管設定優先於 OS 原則和檔案來源，但僅到達已連接的用戶端。將鎖定、允許清單和合併選擇加入鏡像到原則的 cli 區塊中，並保持此檔案的部署，因為永遠不連接的機器（包括僅執行 Claude Desktop 的機器）僅從該檔案取得其原則。

跨來源的鎖定行為

設定一個鎖定不會限制其他鎖定；每個設定鍵都記錄在設定參考中。

來自低於獲勝來源的管理員來源時，兩個沙箱鎖定仍然適用，且 allowManagedPermissionRulesOnly 仍然阻擋父提供的允許規則和 additionalDirectories。在 Claude Code v2.1.273 或更新版本上，MCP 伺服器鎖定也會從低於獲勝來源的來源套用，且在其開啟時，受管 allowedMcpServers 清單來自有設定該清單的最高優先級管理員來源。

hook 鎖定以及 allowManagedPermissionRulesOnly 對開發人員自己規則的影響，預設需要來自獲勝的來源；在 Claude Code 如何合併受管來源中的 managedSourcesBehavior 合併選擇加入下，Claude Code 會對每個鎖定套用任何來源設定的最嚴格值。在 policyHelper 機隊上，Claude Code 僅從 helper 的輸出讀取鎖定。

每個鎖定都會使 Claude Code 忽略開發人員自己針對該設定的項目，因此請在鎖定旁邊包含您組織的允許清單：

  • 網路網域：以空的受管網域清單鎖定會阻擋所有沙箱出站流量。
  • 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。
  • allowedProviders：當獲勝的受管來源未設定 API 提供商允許清單時，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。沒有鎖定能阻擋它。

在預設的首次獲勝設定下，只有當管理員值位於最高優先級管理員來源時，才會阻擋父項的值，但 MCP 伺服器鎖定開啟時的 allowedMcpServers 除外。在 managedSourcesBehavior 合併選擇加入下，Claude Code 如何合併受管來源說明改為套用哪個來源的值。

連接 Claude Desktop

Claude Desktop 透過不同的 MDM 設定鍵連接到相同的閘道：在 Claude Desktop 的受管設定中將 bootstrapUrl 設定為 <listen.public_url>/user/bootstrap，並使用 desktop 設定鍵讓使用者的原則選擇加入。Claude Desktop 覆蓋涵蓋這兩個部分。需要閘道伺服器上的 Claude Code v2.1.203 或更新版本。

Claude Desktop 透過閘道的身分提供者，以相同的瀏覽器 SSO 步驟讓開發人員登入，然後從閘道而不是從 Anthropic 擷取其設定。模型存取和原則遵循與 CLI 相同的各群組規則。同時使用 CLI 和 Claude Desktop 的開發人員需分別登入兩者；閘道工作階段不會在它們之間共享。

連接後，Claude Desktop 會透過閘道傳送每個已啟用標籤的模型請求。它預設顯示 Cowork 和 Code 標籤。若要同時啟用 Chat 標籤，請在 Claude Desktop 的受管設定中將 chatTabEnabled 設定為 true，或在執行 Claude Code v2.1.227 或更新版本的閘道上，於原則的 desktop 區塊中設定。

CI 管道和遠端機器

無人值守的管道沒有服務 token 流程。閘道登入始終執行瀏覽器裝置流程，因此沒有開發人員核准登入的 CI 作業無法進行身分驗證；請直接針對您的提供商設定這些作業。

開發人員登入後，該機器上的每個 Claude Code 工作階段都會使用閘道工作階段，包括非互動式 claude -p 執行和由 Agent SDK 啟動的工作階段。Claude Code 將閘道原則套用於每個工作階段。

裝置流程將輪詢的 CLI 與核准的瀏覽器分開，因此沒有顯示器的遠端開發機器仍然可以運作：開發人員透過 SSH 在遠端機器上執行 /login，並在其筆記型電腦上的瀏覽器中開啟驗證連結。

對開發人員強制執行的內容

這些保證適用於每個透過 /login 登入的工作階段。Claude Desktop 啟動的嵌入式工作階段按照將原則傳遞給 Claude Desktop 工作階段中所述取得其原則，遙測項目則說明其匯出的去向。

  • 模型存取：對原則未授予之模型的請求會返回 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 金鑰，請參閱管理員原則要求雲端閘道登入。
  • 受管設定：鎖定的設定鍵無法在本機覆蓋。CLI 在啟動時套用原則，並在每小時輪詢時套用變更，但僅在下次啟動時套用的變更除外。
  • 閘道無法到達時啟動：已登入的工作階段會在啟動時約 10 秒後以錯誤結束，而不是在沒有其設定的情況下啟動。
  • 閘道結束工作階段後啟動：請參閱強制執行故障關閉啟動，了解哪些啟動會在登出閘道的狀態下開啟，哪些會在閘道以 401 回應時結束。
  • 取消佈建：使用者在 IdP 中被停用的工作階段，會在下一次重新整理失敗時於 ttl_hours 內過期。
  • 登出：/logout 會刪除開發人員機器上的閘道憑證。
    • 當閘道的探索文件在與閘道 URL 相同的配置、主機和連接埠上公告 revocation_endpoint 時，/logout 也會將儲存的 token 傳送到該端點，以便閘道可以在其端結束工作階段。此請求為盡力而為，因此無論端點是否回應，登出都會在開發人員的機器上完成。撤銷需要開發人員機器上的 Claude Code v2.1.275 或更新版本。
    • claude 二進位檔中的閘道伺服器不公告任何撤銷端點，因此從它登出僅會在開發人員的機器上結束工作階段。若要在伺服器端強制結束工作階段，請參閱 JWT 祕密輪換。

組織可以看到什麼

使用情況遙測會將開發人員的身分、token 計數、模型和延遲傳送到組織的收集器。閘道不會記錄或儲存提示詞或完成內容。是否收集更豐富的遙測（例如日誌和追蹤，可能包括命令和檔案路徑），是組織的按目的地選擇。

可用性和限制

該表涵蓋當開發人員透過閘道連接時哪些 Claude Code 功能有效，以及閘道伺服器本身支援什麼。如果不支援某些內容，「備註」欄提供替代方案。

閘道傳遞 CLI 發送到每個上游的 anthropic-beta 值，因此操作員不維護測試版允許清單。對於 Amazon Bedrock（忽略標頭），閘道將值移到請求正文的 anthropic_beta 欄位；其他上游接收按發送方式發送的標頭。

功能 狀態 備註
推理轉發 (Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform、Microsoft Foundry、Anthropic) 可用 具有按上游模型轉換和故障轉移。Amazon Bedrock 上游使用 bedrock-runtime 端點和 AWS 預設憑證鏈。Amazon Bedrock Mantle 上游需要閘道伺服器上的 Claude Code v2.1.283 或更新版本，而 Claude Platform on AWS 上游需要 v2.1.198 或更新版本。
按 IdP 群組的模型存取和受管設定 可用 模型存取在伺服器端強制執行；受管設定按 IdP 群組傳遞，由 CLI 在受管設定層級應用
Claude Desktop 可用（需要選擇加入） 閘道在 /user/bootstrap 提供 Claude Desktop 的設定，一旦原則使用 desktop 金鑰選擇加入，Claude Desktop 從其 Cowork 和 Code 標籤以及從 Chat 標籤（當您啟用它時）發送模型請求透過閘道。若要開啟 Chat 標籤，請參閱連接 Claude Desktop。需要閘道伺服器上的 Claude Code v2.1.203 或更新版本。
遙測扇出 (OTLP/HTTP) 可用 按匯出標識戳記；protobuf 和 JSON 編碼
OIDC 身份提供者 可用 任何符合 OIDC 的 IdP；閘道執行標準 OIDC 探索和授權碼流程。請參閱身份提供者設定以了解各 IdP 的設定
按使用者和按群組支出限制 可用 請參閱支出限制
伺服器端網路搜尋 不可用 CLI 無法看到閘道路由到的上游提供商，因此無法驗證網路搜尋支援並在閘道工作階段上禁用 WebSearch
Remote Control 不可用 CLI 顯示命名閘道的錯誤
/design-sync 和 /design-login 不可用 兩者都需要 claude.ai，CLI 在閘道工作階段上不聯絡，因此兩個命令都不會出現
需要功能旗標擷取的功能，例如 /import 和 claude import 不可用 CLI 在閘道工作階段上跳過旗標擷取。需要功能旗標擷取的功能列出關閉的內容
標準提示快取 可用 閘道將 cache_control 斷點轉發到每個上游。快取位置涵蓋 CLI 標記的區塊，包括它在對話中途附加的系統內容
1 小時快取 TTL 不可用 CLI 在閘道工作階段上省略擴展快取 TTL 測試版，因為並非閘道可以路由到的每個上游都支援 1 小時 TTL，因此透過閘道的提示快取使用 5 分鐘 TTL；請參閱上面的測試版標頭備註
自動模式 可用 遵循第三方提供商規則：只有第三方提供商上符合條件的模型可以使用它。在 v2.1.207 之前，閘道工作階段上的自動模式需要設定 CLAUDE_CODE_ENABLE_AUTO_MODE=1，可透過受管原則 env 區塊傳遞
僅限第一方的最佳化，例如全域快取範圍和令牌高效工具 不可用 CLI 在閘道工作階段上不啟用它們；請參閱上面的測試版標頭備註
OTLP/gRPC 不支援 僅 OTLP over HTTP
SAML、LDAP 和其他非 OIDC 身份驗證 不支援 僅 OIDC。如果需要，使用 OIDC 橋接
多租戶（多個 OIDC 發行者） 不支援 每個閘道一個發行者。執行單獨的執行個體
Windows 伺服器 不支援 在 Linux 上部署。僅本地開發的 macOS
Helm chart 不可用 閘道作為標準無狀態 Deployment 執行；請參閱部署指南
管理員 UI 不可用 設定是 YAML 檔案；重新部署以更改它

後續步驟

快速入門讓您在 Docker Compose 下執行最小配置。要進一步進行：

  • 擴展 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 上部署。