SpyBara
Go Premium

claude-apps-gateway-deploy.md 2026-09-09 22:58 UTC to 2026-09-10 23:00 UTC

This page contains 58 additions and 51 deletions.

2026
Thu 10 23:00 Sat 12 03:02 Fri 18 23:58 Sat 19 23:57 Fri 25 23:58

Claude 應用程式閘道部署和運營

向您的身份提供者註冊閘道、建置容器、在 Kubernetes 或 Cloud Run 上部署，並運營它：健康檢查、祕密輪換、升級和安全性。

本頁涵蓋執行 Claude 應用程式閘道 的運營方面：在您的身份提供者 (IdP) 中註冊 OAuth 用戶端、將閘道部署為容器，以及日常運營。關於閘道在啟動時讀取的 gateway.yaml 檔案中的每個選項，請參閱 設定參考。

生產部署按順序遵循四個步驟，下面的章節與之相符。前兩個是您做出選擇的地方；後兩個是一旦運行時要查閱的參考資料。

  1. 設定您的身份提供者：註冊 OAuth 用戶端並檢查 Okta、Entra 和 Google 的各個 IdP 說明
  2. 部署閘道：建置固定版本的容器映像並在 Kubernetes、Cloud Run 或您自己的平台上執行。本章節也涵蓋成本、繞過、多閘道和無伺服器決策
  3. 設定運營：日誌、健康探針、中斷行為、祕密輪換和升級。當您連接監控和運行手冊時的參考資料
  4. 檢查安全態勢：資料流向何處、威脅模型和合規性答案。用於安全審查的參考資料

如果沿途簽入或啟動失敗，請直接前往 故障排除，該部分根據您看到的錯誤進行索引。

身份提供者設定

向任何 OIDC 相容的身份提供者註冊機密 OAuth/OpenID Connect (OIDC) 網路應用程式，使用單一重新導向 URI https://<gateway>/oauth/callback，並將其分配給應該有閘道存取權限的使用者或群組。

任何 OIDC 相容的 IdP 都可以使用：Okta、Microsoft Entra ID、Google Workspace、Keycloak、Dex、PingFederate 等。IdP 必須滿足三個要求：

  • 在生產環境中透過 HTTPS 提供 /.well-known/openid-configuration；閘道接受 http:// 發行者，環回發行者另外需要 CLAUDE_GATEWAY_ALLOW_LOOPBACK=1
  • 支援授權碼流程。PKCE（代碼交換的證明金鑰）預設開啟；對於不支援它的 IdP，使用 oidc.use_pkce: false 停用它
  • 在 id_token 中傳回 email 和可選的 groups，或使用 oidc.userinfo_fallback: true 從 userinfo 端點提供它們

對於私有 PKI，設定 oidc.ca_cert_pem。

一些提供者以不同方式處理電子郵件和群組聲明：

  • Okta：位於 https://example.okta.com 的組織授權伺服器傳回省略 email 和 groups 的簡化 id_token，因此當您將其用作 issuer 時設定 oidc.userinfo_fallback: true。包含 id_token 中 email 和可選 groups 的自訂授權伺服器（例如 https://example.okta.com/oauth2/default）直接發出它們，不需要回退。Okta 只在 oidc.scopes 中請求 groups 範圍且應用程式的群組聲明篩選器允許時才發出 groups；userinfo_fallback 無法填充 IdP 未被要求的聲明。
  • Microsoft Entra ID：issuer = https://login.microsoftonline.com/<tenant-id>/v2.0。Entra 發出群組物件 ID 而不是名稱，因此在 managed.policies.match.groups 中使用 GUID，或使用應用程式角色以獲得人類可讀的名稱。如果您的租戶在 roles 而不是 groups 下發出角色，設定 oidc.groups_claim: roles。
  • Google Workspace：issuer = https://accounts.google.com。Google 的 id_token 不包含群組。要將基於群組的 allowed_groups 或 managed.policies 與 Google 作為 IdP 一起使用，請配置 oidc.google_groups，它使用具有網域範圍委派的服務帳戶透過 Admin SDK Directory API 查詢每個使用者的群組。沒有它，使用 oidc.allowed_email_domains 進行成員資格閘道和 managed.policies.match.email_domain 進行原則分配。Google 也忽略標準 offline_access 範圍。對於重新整理令牌，設定 oidc.scopes: [openid, profile, email] 和 oidc.extra_auth_params: { access_type: offline, prompt: consent }。

部署

閘道是單一無狀態 Linux 二進位檔案，透過 Postgres 進行協調，因此以您在環境中部署任何其他無狀態服務的方式部署它。將其保持在您的網路內，您的開發人員和 IdP 可以透過 HTTPS 到達它，並將其視為任何持有生產認證的服務。

除了它執行的位置之外，還有一些決策塑造部署：

  • 成本：沒有單獨的許可證或按座位費用。閘道是 claude 二進位檔案的一部分，因此您透過現有的承諾為推理付費，加上它執行的計算。
  • 繞過：閘道不強制執行通往模型的唯一路由必須通過它。具有自己認證的開發人員仍然可以直接呼叫提供者，因此關閉該路徑是網路原則決策，例如阻止到 api.anthropic.com 的出口，除了來自閘道。阻止該出口也會破壞 WebFetch 網域安全檢查，它從每個開發人員的機器呼叫 api.anthropic.com。在受管原則中設定 skipWebFetchPreflight: true 以停用它。
  • 多個閘道：每個是一個單獨的部署，具有自己的設定，CLI 按閘道主機名儲存信任和認證，因此團隊可以使用不同的閘道而不會衝突。要提供多個 OIDC 發行者，請執行單獨的實例。
  • 無伺服器：Cloud Run 可以工作，如果您設定 min-instances: 1 以避免冷 OIDC 發現。Lambda 和 Cloud Functions 不行，因為閘道是長時間執行的 HTTP 伺服器。

此處的每個生產拓撲都在純 HTTP 副本前面放置 L7 代理，例如 Ingress、Cloud Run 的前端或 ALB。設定 listen.trusted_proxies 為代理的來源範圍，以便閘道從 X-Forwarded-For 讀取用戶端 IP。閘道只在 TCP 對等體受信任時才遵守標頭。Google Cloud 和 AWS 實際工作範例為每個拓撲提供具體值。沒有受信任的代理，每個請求似乎都來自代理的 IP，這會將按 IP 速率限制摺疊為一個共享桶，並在審計事件中記錄代理的 IP。

不要將請求重新導向到閘道的裝置授權和權杖端點。Claude Code 不會在這些請求上跟隨重新導向，因此重新導向它們的 Ingress 規則（例如 HTTP 到 HTTPS 或主機規範化重寫）會破壞登入和權杖重新整理。

給代理任何閒置逾時時間長於閘道的保活間隔，這取決於上游：

  • 在除了 provider: anthropic 之外的每個上游上，一旦串流沉默約 15 秒，閘道就會寫入 SSE ping。
  • 在 provider: anthropic 上，閘道將回應原封不動地傳遞，包括 Anthropic API 自己的 ping。

預設值（例如 ALB 的 60 秒）足以保持安靜的串流開啟。AWS 實際工作範例無論如何將其提高到一小時，其故障排除列涵蓋早於 v2.1.229 的閘道，它在現在獲得 ping 的上游上的安靜期間沒有發送任何內容。

容器映像

圍繞標準 Claude Code 版本中的原生 claude 二進位檔案建置您自己的映像：

  1. 從固定版本下載您的映像架構的 Linux 建置；請參閱 安裝特定版本 以取得下載 URL。
  2. 根據 二進位完整性和代碼簽名 中所述，根據版本的 GPG 簽名 manifest.json 驗證它。
  3. 將其複製到建置上下文中。

如果您的建置無法到達版本主機，請將版本鏡像到您的內部登錄中，並固定您的機隊執行的版本。

除了二進位檔案，映像還需要：

  • 基於 glibc 的映像：glibc 建置的唯一動態依賴項是 glibc 庫。基於 Musl 的映像需要 linux-x64-musl 或 linux-arm64-musl 建置加上額外套件；請參閱 Alpine Linux 設定。
  • 可寫入的狀態目錄：閘道以任何使用者身份執行，但最小映像沒有可寫入的主目錄。將 CLAUDE_CONFIG_DIR 設定為可寫入的路徑，例如 /tmp/.claude。
  • 容器命令：claude gateway --config /etc/claude/gateway.yaml，設定檔案以唯讀方式掛載，祕密作為環境變數提供；閘道在 listen.port 上監聽，預設為 8080。

Kubernetes

將閘道作為 Deployment 執行，就像任何無狀態服務一樣：

  • 從 ConfigMap 掛載設定，從 Secret 掛載祕密；透過 ${file:/path/to/secret} 或作為環境變數在 YAML 中參考祕密
  • 在 Ingress 處終止 TLS 並將 listen.public_url 設定為 Ingress 主機名
  • 將就緒探針指向 GET /readyz，將活躍探針指向 GET /healthz

如需 AWS 上的完整實際工作範例，涵蓋 ECS Fargate 或 EKS、Amazon RDS 和 AWS Secrets Manager，請參閱 在 AWS 上部署。

優先選擇平台的工作負載身份而不是靜態金鑰；upstreams 參考有各平台設定詳情。對於跨雲配對，例如 GKE 上的 Amazon Bedrock 上游，在上游的 auth 區塊中設定明確認證。

Cloud Run

按如下方式設定服務：

  • 將 listen.port 保留在預設值 8080，這與 Cloud Run 的預設 PORT 相符，或設定 port: ${PORT}
  • 將 public_url 設定為外部可到達的來源。對於生產，這通常是內部負載平衡器的主機名，因為 /login 拒絕公開地址，而 *.run.app URL 解析為一個，所以單獨的 Cloud Run URL 僅適用於 curl 或瀏覽器煙霧測試。例外是一個網路，其中 *.run.app 透過 Private Service Connect 和 Cloud DNS 私有區域私下解析；在該拓撲中，Cloud Run URL 是有效的 public_url。Google Cloud 實際工作範例涵蓋兩者。
  • 將設定掛載為祕密卷
  • 設定 min-instances: 1 以避免首次請求時的冷 OIDC 發現

如需 Google Cloud 上的完整實際工作範例，涵蓋 Cloud Run 或 GKE、Cloud SQL 和 Secret Manager，請參閱 在 Google Cloud 上部署。

將閘道 URL 推送到開發人員機器

一旦閘道開始提供服務，透過受管設定、MDM 或直接寫入各個 OS managed-settings.json 將 forceLoginMethod、forceLoginGatewayUrl 和 parentSettingsBehavior: "merge" 推送到每個開發人員的機器。沒有這個，/login 顯示標準帳戶選擇器，沒有閘道選項。請參閱 用戶端受管設定 以取得檔案路徑和 Claude Desktop bootstrapUrl 等效項。

運營

一旦閘道開始提供流量，日常運營就是讀取其日誌、探測其健康狀況，以及按您的時間表輪換其祕密。下面的小節涵蓋每一個，加上 Postgres 持有的內容以及升級和回滾的行為方式。

日誌

閘道向 stderr 寫入兩個流，都是 JSON 友好的：

  • 審計事件：每個安全相關事件的單行 JSON。將 stderr 管道傳輸到您的日誌聚合器。發出的事件包括 config.load、session.mint、session.refresh、device.authorize、device.verify、device.callback、auth.denied、access.denied、inference、managed.serve、desktop_bootstrap.serve、desktop_bootstrap.denied、spend.blocked、admin.denied、admin.limit.upsert 和 admin.limit.delete。欄位因事件而異：
    • 成功的 mint 和 refresh 事件攜帶 sub、email、client_ip 和結果
    • auth.denied 和 access.denied 攜帶原因和用戶端 IP，加上 auth.denied 的請求路徑，因為在這些拒絕時不存在使用者身份
    • inference 記錄哪個上游提供了請求以及回應狀態
    • desktop_bootstrap.denied 記錄被拒絕的 Claude Desktop bootstrap 擷取，包含原因（not_configured、policy_not_opted_in 或 no_policy_matched）和使用者的身份
    • admin.denied 記錄被拒絕的管理員 API 驗證嘗試，包括用戶端 IP、方法、路徑和原因，不包括呈現的金鑰材料：當呈現了 x-api-key 但與沒有配置的金鑰相符時為 invalid_key，當只呈現了 Authorization 標頭且它未驗證為 admin.admin_groups 中的閘道會話時為 bearer_rejected，或當兩個標頭都未呈現時為 no_credentials
  • 運營日誌：人類可讀的 [gateway] 前綴行，用於啟動、警告和上游錯誤。CLAUDE_GATEWAY_LOG_LEVEL 環境變數控制詳細程度，接受 debug、info、warn 或 error，預設為 info。在 debug 時，每次登入和重新整理也會記錄 id_token 中的宣告名稱（不是值），加上當 userinfo_fallback 提供任何時的 userinfo 宣告名稱，因此您可以診斷 email_claim 和 groups_claim 設定，而不記錄個人識別資訊。它不影響審計事件，這些事件始終被發出。

健康

閘道提供 GET /healthz 作為活躍探針，GET /readyz 作為就緒探針；/readyz 驗證存儲是否可到達。兩者都豁免於 access_control.allow_cidrs，因此探針在鎖定的監聽器上保持工作。

OAuth 發現文件位於 /.well-known/oauth-authorization-server 也只在配置載入、OIDC 發現、上游用戶端構造和 Postgres 遷移全部成功後才傳回 200，因此它也充當端到端啟動檢查。

中斷行為

如果 Postgres 宕機，閘道本身繼續為已簽入的開發人員提供服務，新的簽入失敗。開發人員是否實際保持工作取決於您的協調器如何處理就緒：

  • 現有會話：持有人令牌使用 JWT 祕密在本地驗證，會話重新整理不接觸存儲，閘道程序仍然可以提供推理
  • 新簽入：失敗直到 Postgres 恢復，因為設備流及其速率限制計數器存在於 Postgres 中
  • 支出限制執行：在中斷期間預設失敗開放，因此推理仍然流動；如果您寧願阻止也不願無計量執行，請將其翻轉為失敗關閉
  • 就緒：/readyz 在中斷期間報告未就緒，因此在就緒上閘門流量的協調器一次從輪換中移除每個副本。在該拓撲中，所有流量，包括閘道仍然可以提供的推理，在負載平衡器處失敗，直到 Postgres 恢復。/healthz 上的活躍探針保持通過，因此副本不會重新啟動。如果您寧願已簽入的開發人員在存儲中斷期間保持工作，請將就緒探針指向 /healthz；成本是新簽入失敗對仍然報告就緒的副本。

如果您的 IdP 宕機，現有會話工作直到 ttl_hours，新登入和重新整理失敗。如果您的 IdP 有頻繁的維護窗口，設定更長的 ttl_hours。

JWT 祕密輪換

分三個步驟輪換簽名祕密，以便現有會話保持有效：

  1. 生成新祕密。將其前置到 session.jwt_secret 陣列。
  2. 滾動部署。新令牌使用新祕密簽名；舊令牌仍然驗證。
  3. 在 ttl_hours 加上邊距後，移除舊祕密並再次滾動。

輪換也是在它們過期之前強制會話退出的唯一方法：持有人令牌根據 JWT 祕密在本地驗證，因此沒有按會話撤銷。直接替換祕密，不在陣列中保留舊祕密，一次使每個未完成的會話無效。對於個別離職，在您的 IdP 中取消配置使用者；他們的會話在 ttl_hours 內結束。

Postgres

閘道持有五個資料表加上一個 _migrations 表，全部由其啟動時遷移建立：

表 內容 保留
kv 設備授予（10 分鐘 TTL）和速率限制計數器 每行 TTL
spend 按主體期間至今支出計數器，以美分計 admin.spend_retention_months，預設 13
spend_limits 配置的支出上限 直到透過 API 刪除
admin_audit 管理員 API 變更軌跡 admin.audit_retention_days，預設 365
principal_emails 每個主體的最後看到的電子郵件、顯示名稱和 IdP 群組。包含個人識別資訊。 admin.identity_retention_days 自上次活動以來，預設 90

30 秒迴圈過期 kv 行超過其 TTL，每小時掃描在支出表上強制保留窗口，因此沒有任何東西無限增長。沒有 支出限制 配置，只有 kv 被寫入。閘道在啟動時應用其自己的架構遷移，以及在每次升級時，因此其資料庫角色需要建立和更改表的權限。將其指向專用於閘道的資料庫或架構，以保持該授予狹窄。

使用支出限制，丟失的資料庫意味著丟失支出追蹤和上限，不僅僅是開發人員重新登入，因此執行定期備份。要立即清除一個已離職的開發人員，而不是等待保留，直接執行 DELETE FROM principal_emails WHERE principal = '<sub>'；這移除唯一持有其電子郵件、名稱和群組的表。spend 和 admin_audit 行僅參考偽匿名 OIDC sub。

升級

副本是無狀態的，因此滾動重新啟動在任何時間都是安全的。閘道在啟動時執行架構遷移，這意味著部署新二進位檔案自我遷移資料庫。並行副本在 Postgres 諮詢鎖上序列化，因此只有一個應用每個遷移。

遷移是僅附加的，因此回滾到知道較少遷移的先前二進位檔案是安全的；它忽略額外的行。回滾也根據較舊二進位檔案的架構重新驗證 YAML，因此採用較新版本引入的金鑰的配置在較舊版本上啟動失敗。在回滾之前移除新金鑰。

因為您在自己的映像中固定閘道的版本，新 Claude Code 版本中的修復，包括安全修復，只有在您更新固定並重新部署時才會到達您的部署。將閘道包含在您用於持有生產認證的其他服務的相同修補週期中。

安全

本章節回答安全審查提出的問題：什麼資料流經閘道以及它流向何處、設計防禦的攻擊，以及哪些答案屬於合規性問卷。

資料流

資料 路徑 由閘道發送給 Anthropic
推理（提示、完成） CLI → 閘道 → 您的上游 只有在 Anthropic API 是配置的上游時
遙測（OTLP 指標，加上 選擇加入日誌和追蹤） CLI → 閘道 → 您的收集器 從不
身份（電子郵件、群組、sub） IdP → 閘道 → JWT → CLI；CLI 在 OTLP 匯出上標記它。如果您開啟 forward_user_identity，閘道也會將開發人員的電子郵件和 IdP 主體作為標頭發送到您的代理 從不
受管設定 您的閘道 YAML → CLI 從不
審計日誌 閘道 stderr → 您的聚合器 從不

威脅模型摘要

閘道位於您的網路周邊內，但個別開發人員筆記型電腦不被視為受信任。設計以三種方式考慮這一點：

  • 開發人員持有短期 JWT 而不是原始上游金鑰。CLI 到閘道的腿使用 RFC 8628 設備授予，閘道與 IdP 的授權碼交換在預設配置中執行 PKCE，因此攔截的 IdP 授權碼是無用的。
  • 設備驗證頁面強制執行同源 POST 和根據 RFC 8628 §5.1 的每 IP 速率限制。請參閱 使用者代碼暴力破解抵抗。
  • 出站請求通過伺服器端請求偽造 (SSRF) 防護，解析 DNS、阻止連結本地和雲端中繼資料地址加上預設環回，並將連接固定到解析的 IP，因此操作員影響的 URL（例如 IdP 和 OTLP 目的地）無法重新導向到雲端中繼資料端點。RFC 1918 私有範圍被刻意允許，因為 IdP 和 OTLP 收集器通常存在於私有 IP 上。只有當閘道必須到達的東西合法地存在於環回上時，才在閘道的環境中設定 CLAUDE_GATEWAY_ALLOW_LOOPBACK=1，例如本地開發 IdP 或 localhost 上的邊車 OTLP 收集器。該變數放寬每個操作員配置的 URL 的環回阻止，也跳過啟動時檢查 pod 是否可以到達雲端中繼資料端點的警告，因此偏好為收集器提供自己的內部地址。

如果您新增自己的出口控制，閘道必須在使用工作負載身份等實例中繼資料認證時到達中繼資料伺服器。

兩個威脅超出範圍，因為它們是您的基礎設施要保護的：

  • 受損的閘道主機：主機既持有上游認證，又向每個連接的開發人員分發 受管設定，因此對閘道配置的控制與對您的 MDM 的控制相當。CLI 的 批准對話框 用於殼層功能設定限制無聲變更，但不替代主機安全。
  • 惡意 OIDC 提供者：提供者簽署閘道信任的 id_token，因此它可以聲稱任何身份。審查和保護您的 IdP 是您的責任。

使用者代碼暴力破解抵抗

開發人員在 /device 驗證頁面中輸入的 user_code 是從 20 字元字母表中抽取的 8 個字元，產生 20⁸ 或約 2.56×10¹⁰ 個組合，並在 10 分鐘後過期。

閘道在設備授予端點上應用按 IP 速率限制，可透過 rate_limits 配置。如果許多開發人員從單一共享公司 NAT 地址簽入，請提高限制。限制僅適用於簽入流程，不適用於推理。

合規性態勢

  • 資料駐留：閘道自己的資料平面不向 Anthropic 發送任何東西，除非 Anthropic API 是配置的上游；當它是時，您現有的資料處理協議適用於推理路徑。遙測、審計、身份和設定只流向您配置的目的地。
  • 主機程序流量：主機程序是 Claude Code CLI。claude gateway 在與 Amazon Bedrock 和 Google Cloud 的 Agent Platform 部署相同的第三方規則下執行，不向 Anthropic 發送任何東西。在 v2.1.227 之前，主機程序發送啟動遙測，例如產品版本和平台，設定容器環境中的 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 會關閉。這些版本也在啟動時發送一個 HEAD 請求，沒有正文或認證，到 https://api.anthropic.com 上的 /api/hello，或在環境設定時到 ANTHROPIC_BASE_URL，除非環境也設定代理變數（例如 HTTPS_PROXY）或 mTLS 用戶端憑證。它們忽略回應，因此在出口防火牆阻止該請求不會影響閘道。
  • 用戶端分析：CLI 在簽入到閘道時停用自己的使用分析和錯誤報告。在第一次簽入之前，CLI 仍然向 Anthropic 發送啟動事件，包括在受管設定強制閘道簽入的機器上。要也關閉這些，在強制閘道簽入的相同 用戶端側受管設定 中傳遞 DISABLE_TELEMETRY。
  • 錯誤報告：每當 CLI 的模型請求流向 Anthropic 的第一方 API 以外的任何端點（例如 Amazon Bedrock 或自訂 ANTHROPIC_BASE_URL）時，CLI 會關閉錯誤報告。
  • 用戶端機器：開發人員的 CLI 仍然向 Anthropic 發送 WebFetch 主機名檢查和版本檢查，除非設定 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 和 skipWebFetchPreflight: true。請參閱 資料使用。
  • 調查評分：在簽入到閘道時，CLI 停用 Anthropic 綁定評分上傳以及分析串流，因此不向 Anthropic 發送評分。
  • 記錄單共享：在調查的記錄單共享提示上選擇「是」會在 ~/.claude/feedback-bundles/ 下寫入本地檔案，而不是上傳到 Anthropic。
  • 用戶端更新：更新檢查與閘道流量分開。透過您自己的分發固定版本，如果筆記型電腦不得提取版本，設定 DISABLE_UPDATES。DISABLE_AUTOUPDATER 只停止背景更新，而 claude update 仍然有效。
  • TLS：在生產中透過 HTTPS 提供 public_url，要麼從閘道自己的監聽器透過 listen.tls，要麼從 TLS 終止 ingress 在純 HTTP 副本前面，在兩種情況下都設定 listen.public_url。閘道不拒絕純 HTTP。IdP 必須在生產中提供 HTTPS，Postgres 支援 ?sslmode=require。在您的 ingress 設定 Strict-Transport-Security。
  • 漏洞披露：遵循 報告安全問題

故障排除

如有問題和反饋，請使用 Claude Code 支援，或在 Claude Code GitHub 儲存庫 上開啟問題。報告問題時，請包括：

  • 閘道問題：相關窗口的閘道 stderr、您的 gateway.yaml（祕密已編輯）、閘道版本（顯示在 / 的登陸頁面和 /managed/settings 上的 x-cc-gateway-version 回應標頭中），以及最近變更的內容
  • 登入問題：開發人員執行 claude --debug-file ./claude-debug.txt、重現，並發送該檔案加上相同窗口的閘道審計日誌
  • 推理問題：請求的模型、配置的上游，以及請求的閘道審計日誌，記錄哪個上游提供了它以及回應狀態

閘道的 stderr 包含審計事件串流，審計日誌記錄開發人員身分，除錯檔案記錄來自開發人員機器的 hook 和 MCP 伺服器輸出。在發佈到公開議題之前，請檢查並隱蔽這些資訊。

症狀 原因 修復
開發人員的 /login 顯示標準帳戶選擇器而不是 Cloud 閘道 螢幕 forceLoginMethod 或 forceLoginGatewayUrl 未在該機器上的受管設定中設定 將 受管設定檔案 部署到設備；/login 從那裡讀取閘道 URL
Claude Desktop 報告其啟動程序設定無法擷取 /user/bootstrap 傳回 404：符合使用者的原則不包含 desktop 金鑰，或沒有原則符合。閘道的審計日誌將每個拒絕記錄為 desktop_bootstrap.denied，並附上原因。 將 desktop 區塊新增到符合使用者的原則，或新增到 match: {} 基礎層；空的 desktop: {} 就足夠了。請參閱 Claude Desktop 覆蓋。
啟動顯示 Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support. 已安裝的 Claude Code 建置早於閘道支援 讓開發人員更新 Claude Code 到包含 Cloud 閘道支援的版本
CLI /login：Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip> 閘道主機名解析為至少一個公開 IP 地址。Claude Code 檢查每個解析的地址，並要求每個都是私有的。常見原因是雙堆棧名稱，其中一個系列解析為公開地址，包括 AWS 內部雙堆棧負載平衡器，它們傳回公開範圍 AAAA 地址。 讓閘道名稱在開發人員機器上只解析為私有地址。對於雙堆棧名稱，刪除公開範圍記錄或提供單獨的僅內部 DNS 名稱。請參閱 私有網路先決條件。
CLI /login：Gateway login would go through proxy <proxy>, which is not on a private network HTTPS_PROXY 或 HTTP_PROXY 適用於閘道主機，代理的主機名解析為公開地址。代理的主機解析為僅私有地址是允許的，不會觸發此錯誤 在開發人員的機器上將閘道主機新增到 NO_PROXY，以便連接是直接的，或使用主機名解析為私有地址的代理。訊息會命名要新增的確切 NO_PROXY 項目
CLI /login：Could not resolve the configured HTTP proxy HTTPS_PROXY 或 HTTP_PROXY 中的主機名無法從開發人員的機器解析，通常是因為它未連接到公司網路 讓開發人員連接到您的網路或 VPN 並重試，或修復代理 URL
CLI /login：Could not resolve gateway host <host> 機器無法解析閘道的內部 DNS 名稱，通常是因為它不在公司網路上 讓開發人員連接到您的網路或 VPN，然後重試 /login
啟動退出，配置驗證錯誤命名 store.postgres_url 未配置 Postgres；閘道需要 Postgres 設定 store.postgres_url。對於本地開發，使用一次性容器：docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres。
啟動退出：requires the native binary 在 Node 下執行而不是原生二進位檔案 使用其中一種 獨立安裝方法 安裝 Claude Code
啟動退出，OIDC 發現錯誤在 config.load 之後 oidc.issuer 無法到達，或 TLS 鏈不受信任 檢查發行者是否可從 Pod 到達並提供 /.well-known/openid-configuration。為私有 PKI 設定 ca_cert_pem。 如果 Pod 只能透過轉發代理到達 IdP，設定 oidc.use_proxy: true；在 v2.1.227 之前的版本上，改為給予 Pod 到 IdP 每個端點的直接路由。
啟動退出，Postgres 權限錯誤 資料庫角色缺少其架構上的 DDL 權限 授予角色在閘道的架構上的 CREATE 權限，以便它可以在啟動時建立和修改其表格
/oauth/callback 顯示「Sign-in could not be completed」 電子郵件網域被拒絕、id_token 驗證失敗，或 email_verified 明確為 false，閘道始終拒絕，沒有覆蓋 檢查 allowed_email_domains 以及 IdP 是否傳回驗證的 email 聲明。對於 email_verified: false，修復 IdP 端驗證。如果您的 IdP 在不同的聲明名稱下發出電子郵件，設定 oidc.email_claim。
日誌：token exchange failed request_id=<id>: id_token missing email claim IdP 預設不在 id_token 中包含 email。此拒絕僅在設定 allowed_email_domains 時觸發；沒有它，缺失的電子郵件鑄造沒有電子郵件的會話 配置 IdP 在 id_token 中發出 email。Okta：將 email 新增到自訂授權伺服器的 ID 令牌聲明。Entra：在應用程式註冊上新增 email 作為可選聲明。PingFederate：啟用發出 email 的 OpenID Connect 原則。如果 IdP 從 userinfo 端點提供 email 但不會在 id_token 中包含它，例如 Okta 組織授權伺服器，設定 oidc.userinfo_fallback: true。
每個 Amazon Bedrock 請求傳回 502；日誌顯示 Could not load credentials from any providers 在 EC2 上，IMDSv2 的預設躍點限制 1 阻止來自容器內的實例中繼資料請求。啟動和 /readyz 仍然通過，因為 AWS SDK 在第一個請求時解析實例認證，而不是在用戶端構造時 使用 aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2 提高躍點限制，或在啟動範本中設定它。變更適用於實例上的每個容器。優先選擇 ECS 任務角色（如果可用），它從 ECS 容器認證端點讀取認證，完全避免變更，或在專用閘道實例上應用變更以限制暴露。
IdP 錯誤：unknown or unsupported scope IdP 拒絕它不識別的範圍 將 oidc.scopes 設定為您的 IdP 接受的確切清單；它必須包含 openid。預設為 openid profile email offline_access。
設定 oidc.scopes 後會話不無聲更新 offline_access 從覆蓋中被刪除 如果您的 IdP 支援，新增 offline_access 回來。沒有重新整理令牌，開發人員每 session.ttl_hours 重新執行瀏覽器登入。
瀏覽器顯示「This request came from another site and was blocked」 跨網站表單 POST，被阻止作為 CSRF 保護。嵌入或代理頁面的預期 直接開啟驗證連結
Chrome 使用「Refused to send form data … violates … Content Security Policy directive: form-action」阻止「批准」按鈕，但相同頁面在 Safari 或 Firefox 中有效 Chrome 對整個重新導向鏈強制執行 form-action。您的 IdP 重新導向到不在允許清單中的第二個主機。 在 oidc.form_action_origins 中新增重新導向鏈中的每個額外來源。在「批准」頁面上開啟 Chrome DevTools → 主控台以查看哪個來源被阻止。
簽入在 IdP 完成但回調失敗，Chrome 中出現 CSP 錯誤或 Safari 中出現「this sign-in link has expired」 IdP 透過 response_mode=form_post 傳回代碼，它透過 POST 自動提交到 /oauth/callback。Chrome 在嚴格 CSP 下阻止它；Safari 允許提交但回調只讀取查詢字串。 確保您的 IdP 遵守 response_mode=query，閘道明確請求它，以便回調是純重新導向
登入在本地有效但在 ALB 後面失敗 public_url 仍然命名本地或內部 http:// 來源，所以 IdP 獲得錯誤的 redirect_uri 將 listen.public_url 設定為外部 https:// 來源，並向 IdP 註冊 <public_url>/oauth/callback
開發人員重複看到信任提示 TLS 憑證按副本或按請求輪換 在 ingress 使用穩定憑證，或終止 TLS 一次並在內部透過純 HTTP 執行副本
CLI /login：「Could not verify the gateway's TLS certificate」或 SELF_SIGNED_CERT_IN_CHAIN 閘道的 TLS 鏈由 CLI 主機的信任存儲中不存在的私有 CA 簽署 Claude Code 預設在原生二進位檔案上讀取 OS 信任存儲，在 Node 22.15 或更新版本上；CLAUDE_CODE_CERT_STORE 控制此行為。如果 CA 安裝在 OS 信任存儲中，確保開發人員在當前執行時上。否則在啟動前將 NODE_EXTRA_CA_CERTS 設定為 CA 憑證 PEM。首次連接指紋提示仍然適用。
CLI /login 完成瀏覽器簽入，然後會話以 Cloud gateway sign-in was not completed 和 TLS 憑證不匹配結束 在簽入後的第一個請求上，閘道提供了與 Claude Code 固定的指紋不符的憑證，所以 Claude Code 沒有保留任何閘道認證。常見原因是一個地址後面的副本提供不同的憑證，或網路路徑上的某些東西攔截 TLS。 為主機名提供一個憑證，例如在 ingress 終止 TLS 一次，然後讓開發人員再次執行 /login。如果該憑證與固定的不同，Claude Code 會在 信任提示 上顯示警告，指出憑證已變更。
CLI /login 停止，顯示 The gateway's TLS certificate changed during sign-in: it no longer matches the one you trusted 簽入請求到達一個伺服器，其憑證與開發人員在 /login 開始時接受的不符：一個地址後面的副本提供不同的憑證、路徑上的 TLS 攔截，或簽入進行中的憑證輪換。 為主機名提供一個憑證，然後讓開發人員再次開始簽入，並在 信任提示 上檢查新憑證。

Cloud gateway sign-in was not completed 訊息命名閘道主機名，以及當 Claude Code 有兩個指紋時，固定指紋的前 16 個字元和提供的指紋。

如果 Claude Code 在閘道簽入後報告 couldn't load your organization's managed settings，Claude Code 會命名原因、就地重新啟動並繼續對話。如果 Claude Code 無法重新啟動，例如在背景會話中，Claude Code 會結束會話並保留簽入。