62| - | - | - |62| - | - | - |
63| `host` | 否 | 繫結位址。預設 `0.0.0.0`。 |63| `host` | 否 | 繫結位址。預設 `0.0.0.0`。 |
64| `port` | 否 | 繫結連接埠。預設 `8080`。 |64| `port` | 否 | 繫結連接埠。預設 `8080`。 |
65| `public_url` | 除非 `host` 是環回 | 外部可見的 `https://` 來源，用於建立 IdP `redirect_uri` 和發現中繼資料。在 `host` 不是環回位址時為必需，無論 TLS 是在代理（例如 ALB、Ingress 或 Cloud Run）還是在閘道本身透過 `tls` 終止，因為閘道永遠不會從 `X-Forwarded-*` 標頭衍生自己的來源；它們是用戶端可欺騙的。沒有它啟動會失敗。下面的 `trusted_proxies` 僅控制用戶端 IP 解析。啟用[遙測](#telemetry)時也是必需的，因為閘道從此 URL 建立它推送給用戶端的 OTLP 端點。 |65| `public_url` | 除非 `host` 是環回 | 外部可見的 `https://` 來源，用於建立 IdP `redirect_uri` 和發現中繼資料。在 `host` 不是環回位址時為必需，無論 TLS 是在代理（例如 ALB、Ingress 或 Cloud Run）還是在閘道本身透過 `tls` 終止，因為閘道永遠不會從 `X-Forwarded-*` 標頭衍生自己的來源；它們是使用者端可欺騙的。沒有它啟動會失敗。下面的 `trusted_proxies` 僅控制使用者端 IP 解析。啟用[遙測](#telemetry)時也是必需的，因為閘道從此 URL 建立它推送給使用者端的 OTLP 端點。 |
66| `tls.cert` / `tls.key` | 否 | 如果閘道自己終止 TLS，則為 PEM 路徑 |66| `tls.cert` / `tls.key` | 否 | 如果閘道自己終止 TLS，則為 PEM 路徑 |
67| `trusted_proxies` | 否 | 閘道前面的負載平衡器的 CIDR 或 IP。設定時，閘道僅信任來自這些對等方的 `X-Forwarded-For`，並記錄真實用戶端 IP 以進行每 IP 速率限制和稽核。等同於 nginx `set_real_ip_from`。`X-Forwarded-For` 項目寫成 `ipv4:port` 或 `[ipv6]:port`（如某些負載平衡器所做），會以連接埠被刪除的方式讀取。附加連接埠且沒有括號的 IPv6 位址可能被讀取為不同位址或根本不被讀取，因此在任何寫入該形式的代理上關閉連接埠選項。 |67| `trusted_proxies` | 否 | 閘道前面的負載平衡器的 CIDR 或 IP。設定時，閘道僅信任來自這些對等方的 `X-Forwarded-For`，並記錄真實使用者端 IP 以進行每 IP 速率限制和稽核。等同於 nginx `set_real_ip_from`。`X-Forwarded-For` 項目寫成 `ipv4:port` 或 `[ipv6]:port`（如某些負載平衡器所做），會以連接埠被刪除的方式讀取。附加連接埠且沒有括號的 IPv6 位址可能被讀取為不同位址或根本不被讀取，因此在任何寫入該形式的代理上關閉連接埠選項。 |
68 68
69<h3 id="oidc">69<h3 id="oidc">
70 `oidc`70 `oidc`
168| `password` | 否 | 資料庫認證。在此設定它而不是在 `postgres_url` 中，以便認證保持在 URL 之外。接受任何字元並優先於 URL 認證。 |168| `password` | 否 | 資料庫認證。在此設定它而不是在 `postgres_url` 中，以便認證保持在 URL 之外。接受任何字元並優先於 URL 認證。 |
169| `max_connections` | 否 | 每個副本的 Postgres 連線池大小。預設 `5`，這是保守的且對共享資料庫友善。啟用[支出限制](#admin)後，熱路徑每個推論請求執行幾個操作，因此在負載下為專用資料庫提高它，並保持副本 × 此值低於資料庫的 `max_connections`。 |169| `max_connections` | 否 | 每個副本的 Postgres 連線池大小。預設 `5`，這是保守的且對共享資料庫友善。啟用[支出限制](#admin)後，熱路徑每個推論請求執行幾個操作，因此在負載下為專用資料庫提高它，並保持副本 × 此值低於資料庫的 `max_connections`。 |
170| `connect_timeout_seconds` | 否 | 閘道開啟 Postgres 連線時等待的秒數。從 `1` 到 `60` 的整數，預設 `5`。如果新閘道執行個體啟動時連線嘗試逾時，請提高它。需要閘道伺服器上的 Claude Code v2.1.274 或更新版本。較早的版本在設定金鑰時拒絕啟動。 |170| `connect_timeout_seconds` | 否 | 閘道開啟 Postgres 連線時等待的秒數。從 `1` 到 `60` 的整數，預設 `5`。如果新閘道執行個體啟動時連線嘗試逾時，請提高它。需要閘道伺服器上的 Claude Code v2.1.274 或更新版本。較早的版本在設定金鑰時拒絕啟動。 |
171| `readiness_grace_seconds` | 否 | Postgres 停止回答後 `/readyz` 保持報告就緒的秒數。從 `0` 到 `3600` 的整數，預設 `0`。請參閱[中斷行為](/docs/zh-TW/claude-apps-gateway-deploy#outage-behavior)以了解如何選擇值。需要閘道伺服器上的 Claude Code v2.1.282 或更新版本。較早的版本在設定金鑰時拒絕啟動。 |
171 172
172對於本地開發，將 `postgres_url` 指向一次性 Postgres 容器，例如 `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`。173對於本地開發，將 `postgres_url` 指向一次性 Postgres 容器，例如 `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`。
173 174
181 182
182如果您在上游上設定 `forward_user_identity: true`，它返回給攜帶開發人員電子郵件的請求的 `429` 不會故障轉移。請參閱[每個使用者限制拒絕如何到達開發人員](#per-user-identity-headers-for-a-proxy-you-run)。183如果您在上游上設定 `forward_user_identity: true`，它返回給攜帶開發人員電子郵件的請求的 `429` 不會故障轉移。請參閱[每個使用者限制拒絕如何到達開發人員](#per-user-identity-headers-for-a-proxy-you-run)。
183 184
184故障轉移於 `404` 需要閘道 v2.1.198 或更新版本。較早的版本即使清單中稍後的上游服務該模型，也會將第一個 `404` 返回給用戶端。185故障轉移於 `404` 需要閘道 v2.1.198 或更新版本。較早的版本即使清單中稍後的上游服務該模型，也會將第一個 `404` 返回給使用者端。
185 186
186相同提供者的多個上游必須設定不同的 `name:`。187相同提供者的多個上游必須設定不同的 `name:`。
187 188
311| 其他任何地方 | 透過 `AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY` 和 `AWS_SESSION_TOKEN` 環境變數傳遞認證，或在 `auth:` 中使用 `${VAR}` 擴展明確設定它們 |312| 其他任何地方 | 透過 `AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY` 和 `AWS_SESSION_TOKEN` 環境變數傳遞認證，或在 `auth:` 中使用 `${VAR}` 擴展明確設定它們 |
312| 地區 | `region:` 是 API 端點地區。跨地區推論設定檔無論您選擇哪一個，都會跨地理位置 (US、EU、APAC) 路由。對於非美國地區或佈建輸送量 ARN，新增具有正確每上游 ID 的 [`models:`](#models) 區塊。 |313| 地區 | `region:` 是 API 端點地區。跨地區推論設定檔無論您選擇哪一個，都會跨地理位置 (US、EU、APAC) 路由。對於非美國地區或佈建輸送量 ARN，新增具有正確每上游 ID 的 [`models:`](#models) 區塊。 |
313 314
315<h5 id="apply-an-amazon-bedrock-guardrail">
316 應用 Amazon Bedrock 防護欄
317</h5>
318
319若要將 Amazon Bedrock 防護欄應用於閘道透過 Bedrock 上游傳送的每個推論請求，請將 `guardrail` 區塊新增到該上游。需要閘道伺服器上的 Claude Code v2.1.281 或更新版本。
320
321```yaml theme={null}
322upstreams:
323 - provider: bedrock
324 region: us-east-1
325 auth: {}
326 guardrail:
327 id: gr-abc123 # 防護欄 ID 或完整 ARN
328 version: "1" # 已發佈的版本號，或 DRAFT
329 # 保留引號：裸露的 1 在啟動時失敗
330```
331
332<Warning>
333 閘道不支援防護欄輸入標籤。它不向提示新增防護內容標籤，因此 Amazon Bedrock 僅應用於標籤輸入的防護欄篩選器不會在透過閘道的流量上執行。對於哪些篩選器取決於輸入標籤，請參閱 Amazon Bedrock 文件中的[輸入標籤](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-tagging.html)。
334</Warning>
335
336也授予簽署此上游請求的主體的防護欄上的 `bedrock:ApplyGuardrail`：閘道的 AWS 主體，或使用 [`assume_role`](#bedrock-in-another-aws-account) 的 `role_arn` 中命名的角色。
337
338在每個 `bedrock` 上游或沒有上游上設定 `guardrail`。閘道拒絕在混合上啟動，因為[故障轉移](#multiple-upstreams)可能會將請求傳送到沒有防護欄的 Bedrock 上游。
339
340防護欄僅涵蓋 Bedrock 上游。如果您在 `upstreams` 中列出另一個提供者，閘道將請求傳送到該提供者而不帶防護欄。
341
342當 `/v1/messages` 請求的正文攜帶 `amazon-bedrock-*` 欄位（例如 `amazon-bedrock-guardrailConfig`）到達設定了 `guardrail` 的 Bedrock 上游時，閘道答覆 400 而不是轉發它。
343
344<a id="bedrock-in-another-aws-account" />
345
346<h5 id="bedrock-in-another-aws-account">
347 另一個 AWS 帳戶中的 Bedrock
348</h5>
349
350在 Bedrock 上游上設定 `assume_role`，閘道僅使用其自己的 AWS 身分識別來呼叫您命名的角色上的 `sts:AssumeRole`，該角色可以在與閘道不同的 AWS 帳戶中。該上游的每個 Bedrock 請求都使用 STS 返回的一小時認證簽署，因此沒有長期存取金鑰跨帳戶。
351
352需要執行 Claude Code v2.1.281 或更新版本的閘道。較早的閘道在找到金鑰時拒絕啟動。
353
354```yaml theme={null}
355upstreams:
356 - name: bedrock-isolated
357 provider: bedrock
358 region: us-east-1
359 auth: {} # 閘道自己的角色：它僅呼叫 STS
360 assume_role:
361 role_arn: arn:aws:iam::222222222222:role/claude-gateway-bedrock
362 # external_id: ${BEDROCK_ROLE_EXTERNAL_ID} # 當角色的信任原則需要時
363```
364
365`assume_role` 區塊採用三個金鑰：
366
367| 金鑰 | 意義 |
368| - | - |
369| `role_arn` | 閘道假設的 IAM 角色，作為 `arn:aws:iam::` 或 `arn:aws-us-gov:iam::` ARN。給予它此上游需要的 [Bedrock 權限](#amazon-bedrock)，包括 `bedrock:CountTokens`，以及當上游設定 `guardrail` 時的 `bedrock:ApplyGuardrail`。 |
370| `external_id` | 選用。在每個 `sts:AssumeRole` 呼叫上傳送為外部 ID。當角色的信任原則需要時設定它，如果它全是數字則引用它。 |
371| `session_name` | 選用。`email` 或 `sub` 給每個開發人員自己的工作階段：請參閱[每個開發人員 AWS 成本歸因](#per-developer-aws-cost-attribution)。未設定，每個請求使用一個名為 `claude-apps-gateway` 的工作階段。 |
372
373角色的信任原則命名閘道自己的主體，例如其 IRSA 或 ECS 任務角色。該主體需要角色上的 `sts:AssumeRole` 和沒有 Bedrock 權限。如果您設定沒有 `external_id`，請刪除 `Condition`。
374
375```json theme={null}
376{
377 "Version": "2012-10-17",
378 "Statement": [{
379 "Effect": "Allow",
380 "Principal": { "AWS": "arn:aws:iam::111111111111:role/claude-gateway" },
381 "Action": "sts:AssumeRole",
382 "Condition": { "StringEquals": { "sts:ExternalId": "your-external-id" } }
383 }]
384}
385```
386
387* 如果 STS 拒絕或無法到達，閘道不會使用上游自己的認證傳送請求。它記錄 STS 錯誤以及要檢查的內容，然後嘗試您列出的下一個上游。[上游錯誤訊息](#upstream-error-messages)涵蓋當沒有上游成功時用戶端接收的內容。沒有 `assume_role` 的稍後上游會使用其自己的認證服務請求，因此僅在這是您想要的情況下列出一個。
388* 閘道呼叫區域 STS 端點 `sts.<region>.amazonaws.com`，其網路必須到達。對於 FIPS 端點，在閘道的環境中設定 `AWS_USE_FIPS_ENDPOINT=true` 而不是在 AWS 設定檔中設定 `use_fips_endpoint`。
389* `assume_role` 僅適用於 `provider: bedrock` 並需要 SigV4 來源認證：當它在 `aws_bearer_token` 旁邊設定時，閘道拒絕啟動。
390* 閘道允許的每個開發人員都可以使用此上游；[`managed`](#managed)控制哪些開發人員可能使用哪些模型。若要保持透過角色服務的模型也不從另一個帳戶服務，請給它一個自訂 id，其 `upstream_model` 對應僅具有此上游的名稱。對於這樣的 id，閘道跳過每個其他上游，因此請求和已放棄請求的令牌計數都無法故障轉移到另一個帳戶。內建模型名稱仍在每個上游上按順序嘗試，包括這個，到達它的請求使用相同角色簽署，因此除非其帳戶也應該服務它們，否則最後列出此上游。
391
392此範例給一個模型一個自訂 id，只有隔離上游服務：
393
394```yaml theme={null}
395models:
396 - id: claude-opus-restricted # 自訂 id，不是內建模型名稱
397 upstream_model:
398 bedrock-isolated: us.anthropic.claude-opus-4-8 # 唯一服務它的上游
399```
400
401<a id="per-developer-aws-cost-attribution" />
402
403<h5 id="per-developer-aws-cost-attribution">
404 每個開發人員 AWS 成本歸因
405</h5>
406
407預設情況下，閘道使用一個認證簽署每個 Bedrock 請求，因此 AWS 在單個 IAM 主體下看到所有開發人員的請求。將 `session_name: email` 新增到 [`assume_role`](#bedrock-in-another-aws-account)，閘道每個開發人員每小時呼叫一次 `sts:AssumeRole`，工作階段名稱設定為該開發人員的電子郵件，並使用返回的認證簽署其請求，因此每個開發人員的請求在 AWS 下以其自己的假設角色工作階段到達。角色可以在閘道自己的帳戶中。
408
409需要執行 Claude Code v2.1.281 或更新版本的閘道。[AWS 上的成本歸因](/docs/zh-TW/claude-apps-gateway-on-aws#cost-attribution)涵蓋 IAM 角色以及 AWS 帳單顯示工作階段的位置。
410
411```yaml theme={null}
412upstreams:
413 - provider: bedrock
414 region: us-east-1
415 auth: {} # 閘道自己的角色：它僅呼叫 STS
416 assume_role:
417 role_arn: arn:aws:iam::123456789012:role/claude-gateway-bedrock-user
418 session_name: email # 或 sub
419```
420
421`session_name` 選擇哪個已驗證宣告成為 AWS `RoleSessionName`：`email` 或 `sub`。閘道將 ASCII 字母、數字和 `_+,.@-` 以外的任何字元寫成 `=XX` 十六進位（每 UTF-8 位元組），並將長於 64 字元的結果縮短為前置詞加雜湊，因此每個開發人員的工作階段名稱保持有效且唯一。來自其令牌缺少宣告的開發人員的請求不會透過此上游傳送，操作員日誌說要切換到 `sub` 或設定 [`oidc.email_claim`](#oidc)。
422
423活躍開發人員每小時每個閘道副本成本一個 STS 呼叫，並且並行首次請求共享一個呼叫。
424
425閘道也在此角色上進行一個呼叫：用戶端放棄的請求的令牌計數，因此[支出限制](/docs/zh-TW/claude-apps-gateway-spend-limits)保持準確。該計數及其[一令牌後備請求](#amazon-bedrock)由共享 `claude-apps-gateway` 工作階段簽署，因此 AWS 將後備歸因於 `claude-apps-gateway` 而不是開發人員。
426
427對於嚴格的每個開發人員歸因，在您列出的每個 Bedrock 上游上設定 `assume_role` 與 `session_name`。沒有它的上游使用其自己的認證簽署它服務的請求。
428
314<h4 id="claude-platform-on-aws">429<h4 id="claude-platform-on-aws">
315 Claude Platform on AWS430 Claude Platform on AWS
316</h4>431</h4>
440| - | - |555| - | - |
441| `/v1/messages`、串流或不串流，以及 `/v1/messages/count_tokens` | 是 |556| `/v1/messages`、串流或不串流，以及 `/v1/messages/count_tokens` | 是 |
442| 從另一個上游故障轉移的請求 | 是，僅此上游的 `headers:` |557| 從另一個上游故障轉移的請求 | 是，僅此上游的 `headers:` |
443| Amazon Bedrock 的 `CountTokens` 呼叫用於用戶端放棄的請求 | 否 |558| Amazon Bedrock 的 `CountTokens` 呼叫用於使用者端放棄的請求 | 否 |
444| Workload Identity Federation 令牌交換 | 否 |559| Workload Identity Federation 令牌交換 | 否 |
445 560
446在使用 AWS SigV4 簽署請求的 Amazon Bedrock 或 Claude Platform on AWS 上游上，這些標頭是簽名的一部分，因此您的代理必須原樣傳遞它們。561在使用 AWS SigV4 簽署請求的 Amazon Bedrock 或 Claude Platform on AWS 上游上，這些標頭是簽名的一部分，因此您的代理必須原樣傳遞它們。
483 provider: bedrock598 provider: bedrock
484 region: us-west-2599 region: us-west-2
485 auth: {}600 auth: {}
486 # 不同帳戶：透過假設角色認證的單獨 Bedrock 配額。601 # 不同帳戶：透過靜態金鑰的單獨 Bedrock 配額。
487 - name: bedrock-acct2602 - name: bedrock-acct2
488 provider: bedrock603 provider: bedrock
489 region: us-east-1604 region: us-east-1
510| 槓桿 | 方式 |625| 槓桿 | 方式 |
511| - | - |626| - | - |
512| 不同地區 | 每個地區一個 Bedrock 上游，每個都有自己的 `region:`。使用 [`auto_include_builtin_models: true`](#models)，跨地區推論設定檔會自動路由；對於地區固定部署，使用 `models:` 區塊。 |627| 不同地區 | 每個地區一個 Bedrock 上游，每個都有自己的 `region:`。使用 [`auto_include_builtin_models: true`](#models)，跨地區推論設定檔會自動路由；對於地區固定部署，使用 `models:` 區塊。 |
513| 不同帳戶 | 每個帳戶一個 Bedrock 上游，每個在 `auth:` 中都有自己的認證。預設鏈 (`auth: {}`) 使用 Pod 的身分識別；對於第二個帳戶，設定明確認證或持有人令牌。 |628| 不同帳戶 | 每個帳戶一個 Bedrock 上游。預設鏈 (`auth: {}`) 使用 Pod 的身分識別；對於第二個帳戶，新增 [`assume_role`](#bedrock-in-another-aws-account) 以透過短期認證到達它，或在 `auth:` 中設定明確認證或持有人令牌。 |
514| 佈建輸送量 | 將模型對應到該上游名稱的 `models:` 中的佈建輸送量 ARN。其他上游保持隨需 ID，因此 PT 容量在故障轉移前耗盡。 |629| 佈建輸送量 | 將模型對應到該上游名稱的 `models:` 中的佈建輸送量 ARN。其他上游保持隨需 ID，因此 PT 容量在故障轉移前耗盡。 |
515| VPC / FIPS 端點 | 在上游上設定 `base_url:` 為您的 VPC 端點或 FIPS 端點 URL |630| VPC / FIPS 端點 | 在上游上設定 `base_url:` 為您的 VPC 端點或 FIPS 端點 URL |
516| 模型範圍路由 | 只有自訂模型 `id`（不是內建 Claude 模型）會跳過其 `upstream_model:` 對應中不存在的上游。閘道按順序嘗試每個上游上的內建模型，並在對應中沒有項目時使用提供者的預設 ID，因此對於內建模型，對應改變上游接收的 ID 而不是是否嘗試它；拒絕 ID 的上游遵循與任何其他上游錯誤相同的[故障轉移規則](#upstreams)。 |631| 模型範圍路由 | 只有自訂模型 `id`（不是內建 Claude 模型）會跳過其 `upstream_model:` 對應中不存在的上游。閘道按順序嘗試每個上游上的內建模型，並在對應中沒有項目時使用提供者的預設 ID，因此對於內建模型，對應改變上游接收的 ID 而不是是否嘗試它；拒絕 ID 的上游遵循與任何其他上游錯誤相同的[故障轉移規則](#upstreams)。 |
527 `admin`642 `admin`
528</h3>643</h3>
529 644
530選用。啟用 `/v1/organizations/spend_limits`，其鏡像 Anthropic 的公開 Admin API，以及在 `/v1/messages` 上的每位開發者支出強制執行。請參閱[支出限制](/docs/zh-TW/claude-apps-gateway-spend-limits)以了解上限如何設定和強制執行；本區段涵蓋啟用該功能並調整它的 `gateway.yaml` 金鑰。645選用。啟用 `/v1/organizations/spend_limits`，其鏡像 Anthropic 的公開 Admin API，以及在 `/v1/messages` 上的每位開發者支出強制執行。請參閱[支出限制](/docs/zh-TW/claude-apps-gateway-spend-limits)以了解如何設定和強制執行上限；本節涵蓋啟用該功能並調整它的 `gateway.yaml` 金鑰。
531 646
532```yaml theme={null}647```yaml theme={null}
533admin:648admin:
540 - { id: ci, key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }655 - { id: ci, key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }
541 read_keys:656 read_keys:
542 - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }657 - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
543 # IdP 群組透過一般 gateway JWT（無 API 金鑰）授予完整 admin 存取權。658 # 透過一般 gateway JWT（無 API 金鑰）授予完整 admin 的 IdP 群組。
544 admin_groups: [platform-finops]659 admin_groups: [platform-finops]
545 blocked_message: request an increase at https://go.example.com/claude-limits660 blocked_message: request an increase at https://go.example.com/claude-limits
546```661```
547 662
548| 欄位 | 必要 | 說明 |663| 欄位 | 必需 | 說明 |
549| - | - | - |664| - | - | - |
550| `write_keys` | 否 | `{id, key}` 的陣列。符合其中一個的 `x-api-key` 可以列出、設定和刪除支出限制。金鑰值必須至少 32 個字元；`id` 在 `read_keys` 和 `write_keys` 中必須唯一。 |665| `write_keys` | 否 | `{id, key}` 的陣列。符合其中一個的 `x-api-key` 可以列出、設定和刪除支出限制。金鑰值必須至少 32 個字元；`id` 在 `read_keys` 和 `write_keys` 中必須唯一。 |
551| `read_keys` | 否 | `{id, key}` 的陣列。唯讀：每個 `GET` 端點，包括列出上限、按 ID 擷取一個，以及讀取 [`/effective`](/docs/zh-TW/claude-apps-gateway-spend-limits#%2Feffective) 和 [`/audit`](/docs/zh-TW/claude-apps-gateway-spend-limits#%2Faudit)。 |666| `read_keys` | 否 | `{id, key}` 的陣列。唯讀：每個 `GET` 端點，包括列出上限、按 ID 擷取一個，以及讀取 [`/effective`](/docs/zh-TW/claude-apps-gateway-spend-limits#%2Feffective) 和 [`/audit`](/docs/zh-TW/claude-apps-gateway-spend-limits#%2Faudit)。 |
552| `admin_groups` | 否 | IdP 群組名稱。gateway JWT 的 `groups` 宣告包含其中一個的具有完整 admin 存取權（讀取和寫入），並稽核為 `oidc:<sub>`。將此用於人類 admin；將 API 金鑰用於機器。此清單中的空項目會在啟動時停止 gateway。請參閱[在啟動時停止 gateway 的匹配器值](#matcher-values-that-stop-the-gateway-at-boot)。 |667| `admin_groups` | 否 | IdP 群組名稱。gateway JWT 的 `groups` 聲明包含其中一個的具有完整 admin 存取權（讀取和寫入），並稽核為 `oidc:<sub>`。將此用於人類 admin；將 API 金鑰用於機器。此清單中的空項目會在啟動時停止 gateway。請參閱[在啟動時停止 gateway 的匹配器值](#matcher-values-that-stop-the-gateway-at-boot)。 |
553| `blocked_message` | 否 | 逐字附加到被阻止的開發者看到的 `429 billing_error`。寫入完整指示，例如 URL 或 Slack 頻道。未設定時，gateway 只傳送預設訊息。請參閱[強制執行如何運作](/docs/zh-TW/claude-apps-gateway-spend-limits#how-enforcement-works)。 |668| `blocked_message` | 否 | 逐字附加到被阻止的開發者看到的 `429 billing_error`。寫入完整指示，例如 URL 或 Slack 頻道。未設定時，gateway 只傳送預設訊息。請參閱[強制執行如何運作](/docs/zh-TW/claude-apps-gateway-spend-limits#how-enforcement-works)。 |
554| `audit_retention_days` | 否 | 預設 `365`。較舊的 `admin_audit` 列會被清除。 |669| `audit_retention_days` | 否 | 預設 `365`。較舊的 `admin_audit` 列會被清除。 |
555| `spend_retention_months` | 否 | 預設 `13`。超過此時間的 `spend` 計數器列會被清除。預設值保留整整一年加上當月的部分月份，用於年度比較報告。 |670| `spend_retention_months` | 否 | 預設 `13`。早於此時間的 `spend` 計數器列會被清除。預設值保留完整年份加上當月部分月份，用於年度比較報告。 |
556| `identity_retention_days` | 否 | 預設 `90`。`principal_emails` 列的最後一次看到 TTL，其中保存每位開發者的電子郵件、顯示名稱和群組（PII）。刻意比支出保留期短，因此已取消佈建的身分會在其匿名支出計數器保留時過期。 |671| `identity_retention_days` | 否 | 預設 `90`。`principal_emails` 列的最後一次看到 TTL，其中保存每位開發者的電子郵件、顯示名稱和群組（PII）。刻意比支出保留期短，因此已取消佈建的身分會在其匿名支出計數器保留時過期。 |
557| `group_limit_mode` | 否 | `min`（預設）或 `max`。當開發者在多個具有上限的群組中時，`min` 強制執行最嚴格的，`max` 強制執行最寬鬆的。由強制執行和 `/effective` 使用。 |672| `group_limit_mode` | 否 | `min`（預設）或 `max`。當開發者在多個具有上限的群組中時，`min` 強制執行最嚴格的，`max` 強制執行最寬鬆的。由強制執行和 `/effective` 使用。 |
558 673
562 677
563`enforcement` 區塊控制當存放區不可用時支出限制檢查的行為。678`enforcement` 區塊控制當存放區不可用時支出限制檢查的行為。
564 679
565| 欄位 | 必要 | 說明 |680| 欄位 | 必需 | 說明 |
566| - | - | - |681| - | - | - |
567| `fail_closed_on_error` | 否 | 預設 `false`。支出強制執行在 Postgres 中斷時失敗開放，因此推論保持運作。設定為 `true` 以失敗關閉：超過上限的開發者被阻止，但如果存放區無法到達，所有人也都被阻止。需要 [`admin:`](#admin) 區塊：支出強制執行只在設定 `admin` 時執行，如果您在沒有 `admin` 的情況下設定此 `true`，gateway 會拒絕啟動。 |682| `fail_closed_on_error` | 否 | 預設 `false`。支出強制執行在 Postgres 中斷時失敗開放，因此推論保持運作。設定 `true` 以失敗關閉：超過上限的開發者被阻止，但如果存放區無法到達，所有人都被阻止。需要 [`admin:`](#admin) 區塊：支出強制執行只在設定 `admin` 時執行，如果您在沒有 `admin` 的情況下設定此 `true`，gateway 會拒絕啟動。 |
568 683
569<h3 id="pricing">684<h3 id="pricing">
570 `pricing`685 `pricing`
571</h3>686</h3>
572 687
573`pricing` 區塊告訴支出計量器要收費的金額而不是 USD 清單價格，因此上限和 [`/effective`](/docs/zh-TW/claude-apps-gateway-spend-limits#%2Feffective) 反映您的合約費率。金額保持為 USD，並保持為估計值，而非發票。兩個先決條件：688`pricing` 區塊告訴支出計量器要收費的金額而不是美元清單價格，因此上限和 [`/effective`](/docs/zh-TW/claude-apps-gateway-spend-limits#%2Feffective) 反映您的合約費率。金額保持為美元，並保持為估計值，而非發票。兩個先決條件：
574 689
575* gateway 伺服器上的 Claude Code v2.1.227 或更新版本。較早版本在啟動時拒絕未知金鑰。690* gateway 伺服器上的 Claude Code v2.1.227 或更新版本。較早版本在啟動時拒絕未知金鑰。
576* [`admin:`](#admin) 區塊或在 v2.1.268 或更新版本中，具有至少一個原則的 [`managed:`](#managed) 區塊。gateway 會拒絕在設定 `pricing` 且沒有任何區塊的情況下啟動，因為沒有任何東西會讀取它。691* [`admin:`](#admin) 區塊或在 v2.1.268 或更新版本中，至少有一個原則的 [`managed:`](#managed) 區塊。gateway 會拒絕在設定 `pricing` 且沒有任何區塊的情況下啟動，因為沒有任何東西會讀取它。
577 692
578```yaml theme={null}693```yaml theme={null}
579pricing:694pricing:
587 cache_write: 4.125702 cache_write: 4.125
588```703```
589 704
590| 欄位 | 必要 | 說明 |705| 欄位 | 必需 | 說明 |
591| - | - | - |706| - | - | - |
592| `multiplier` | 否 | 預設 `1`。計量器將每個計量金額乘以此值，無論是清單定價還是覆蓋，因此 `0.85` 計費 85% 的價格。必須大於 0 且最多 10，值大於 1 是[標記價格上升](#mark-prices-up)。 |707| `multiplier` | 否 | 預設 `1`。計量器將每個計量金額乘以此值，無論是清單價格還是覆蓋，因此 `0.85` 計費 85% 的價格。必須大於 0 且最多 10，大於 1 的值是[標記價格上升](#mark-prices-up)。 |
593| `overrides` | 否 | `{upstream, model, input, output, cache_read, cache_write}` 的列，單位為 USD 每百萬個 token。所有四個費率都是必要的。每個必須大於 0 且最多 10000。 |708| `overrides` | 否 | `{upstream, model, input, output, cache_read, cache_write}` 的列，單位為美元每百萬個 token。所有四個費率都是必需的。每個必須大於 0 且最多 10000。 |
594 709
595計量器如何匹配覆蓋列：710計量器如何匹配覆蓋列：
596 711
597* 列替換 `upstream`（[`upstreams[].name`](#upstreams)）為 `model` 提供的請求的清單價格。這包括更高的[快速模式](/docs/zh-TW/fast-mode#understand-the-cost-tradeoff)費率，因此快速和標準請求以相同的四個費率計量。712* 列替換 `upstream`（[`upstreams[].name`](#upstreams)）為 `model` 提供的請求的清單價格。這包括更高的[快速模式](/docs/zh-TW/fast-mode#understand-the-cost-tradeoff)費率，因此快速和標準請求以相同的四個費率計量。
598* 內建 ID（例如 `claude-sonnet-4-6`）匹配方式類似 [`models[].id`](#models)，涵蓋計量器定價為該模型的每個日期形式、區域 Amazon Bedrock 形式或 Google Cloud 的 Agent Platform 形式。任何其他字串（例如別名或推論設定檔 ARN）匹配用戶端傳送的 ID 或上游傳送的字串，不區分大小寫。713* 內建 ID（例如 `claude-sonnet-4-6`）匹配方式類似 [`models[].id`](#models)，涵蓋計量器定價為該模型的每個日期形式、區域 Amazon Bedrock 形式或 Google Cloud 的 Agent Platform 形式。任何其他字串（例如別名或推論設定檔 ARN）匹配用戶端傳送的 ID 或上游傳送的字串，不區分大小寫。
599* 列重疊時，計量器選擇最具體的列而不是第一列：其 `model` 是上游傳送的確切模型字串的列，然後是匹配用戶端傳送的確切 ID 的列，然後是命名內建模型的列。714* 當列重疊時，計量器選擇最具體的列而不是第一列：其 `model` 是上游傳送的確切模型字串的列，然後是匹配用戶端傳送的確切 ID 的列，然後是命名內建模型的列。
600* 未知的上游名稱會導致啟動失敗，兩個列針對一個上游命名相同模型也會導致啟動失敗，包括一個內建模型的兩個拼寫。gateway 在啟動時警告沒有可請求模型可以使用的列。715* 未知的上游名稱會導致啟動失敗，一個上游的兩列命名相同模型也會導致啟動失敗，包括一個內建模型的兩個拼寫。gateway 在啟動時警告沒有可請求模型可以使用的列。
601* Web 搜尋請求保持在 \$0.01 清單價格；乘數仍適用於它們。716* Web 搜尋請求保持在 \$0.01 清單價格；乘數仍適用於它們。
602 717
603對於每個區域費率，為每個區域提供自己的具名上游和每個上游一列。718對於每個區域費率，為每個區域提供自己的具名上游和每個上游一列。
613 multiplier: 1.2728 multiplier: 1.2
614```729```
615 730
616使用 [`admin:`](#admin) 區塊，標記也適用於支出限制。計量器計數 120% 的價格，因此開發者更快達到其上限。gateway 在啟動時記錄警告，說明這一點。731使用 [`admin:`](#admin) 區塊，標記也適用於支出限制。計量器計算 120% 的價格，因此開發者更快達到其上限。gateway 在啟動時記錄警告，說明這一點。
617 732
618乘數不會改變上游提供者對請求的收費。733乘數不會改變上游提供者對請求的收費。
619 734
620如果 gateway 也[將費率傳送給已登入的用戶端](#send-the-rates-to-signed-in-clients)，開發者需要 Claude Code v2.1.271 或更新版本才能看到標記。較早的用戶端忽略大於 1 的 `multiplier` 並顯示不含標記的成本。735如果 gateway 也[將費率傳送給已登入的用戶端](#send-the-rates-to-signed-in-clients)，開發者需要 Claude Code v2.1.271 或更新版本才能看到標記。較早的用戶端忽略大於 1 的 `multiplier` 並顯示不含標記的成本。
621 736
622早於 v2.1.271 的 gateway 伺服器會在您設定大於 1 的 `multiplier` 時拒絕啟動。737早於 v2.1.271 的 gateway 伺服器會拒絕在您設定大於 1 的 `multiplier` 時啟動。
623 738
624<h4 id="send-the-rates-to-signed-in-clients">739<h4 id="send-the-rates-to-signed-in-clients">
625 將費率傳送給已登入的用戶端740 將費率傳送給已登入的用戶端
626</h4>741</h4>
627 742
628使用 gateway 伺服器上的 v2.1.268 或更新版本，gateway 也將 `pricing` 中的費率放入它提供的 [`managed`](#managed) 原則中，作為 [`modelPricing`](/docs/zh-TW/settings-reference#modelpricing) 受管設定。由原則匹配的開發者隨後在 `/usage`、狀態列和 OpenTelemetry 中看到為提供每個模型 ID 的第一個上游的 `pricing` 費率。不符合任何原則的開發者不會收到受管設定，因此其數字保持在清單價格。用戶端在 Claude Code v2.1.242 或更新版本中應用設定。743使用 gateway 伺服器上的 v2.1.268 或更新版本，gateway 也將 `pricing` 中的費率放入它提供的 [`managed`](#managed) 原則中，作為 [`modelPricing`](/docs/zh-TW/settings-reference#modelpricing) 受管設定。由原則匹配的開發者隨後在 `/usage`、狀態列和 OpenTelemetry 中看到每個模型 ID 的第一個上游的 `pricing` 費率。與任何原則不匹配的開發者不會收到受管設定，因此其數字保持在清單價格。用戶端在 Claude Code v2.1.242 或更新版本中應用設定。
629 744
630* gateway 新增的內容：除非原則的 `cli` 區塊已設定 `modelPricing`，gateway 新增 `multiplier` 和用戶端可以請求的每個模型 ID 的第一個提供該 ID 的上游的覆蓋列。只有容錯移轉上游收費的費率保持在 gateway 上。745* gateway 新增的內容：除非原則的 `cli` 區塊已設定 `modelPricing`，gateway 新增 `multiplier` 和，對於用戶端可以請求的每個模型 ID，提供該 ID 的第一個上游的覆蓋列。只有故障轉移上游收費的費率保持在 gateway 上。
631* 選擇一個原則退出：在該原則的 `cli` 區塊中將 `modelPricing` 設定為 `{}`，其開發者保持在清單價格。746* 選擇一個原則退出：在該原則的 `cli` 區塊中將 `modelPricing` 設定為 `{}`，其開發者保持在清單價格。
632* 保留原則自己的費率：其 `cli` 區塊使用自己的 `multiplier` 或 `overrides` 設定 `modelPricing` 的原則保留該 `modelPricing` 完整，gateway 不新增自己的費率到它。747* 保留原則自己的費率：其 `cli` 區塊使用自己的 `multiplier` 或 `overrides` 設定 `modelPricing` 的原則保留該 `modelPricing` 完整，gateway 不向其新增自己的費率。
633 748
634<h3 id="models">749<h3 id="models">
635 `models`750 `models`
636</h3>751</h3>
637 752
638`models` 區塊是選用的 admin 策劃模型清單，在 `/v1/models` 提供並用於按上游轉譯模型 ID。對於非美國 Amazon Bedrock 區域、Amazon Bedrock 佈建輸送量 ARN 和 Microsoft Foundry 部署名稱是必要的。753`models` 區塊是選用的 admin 策劃模型清單，在 `/v1/models` 提供，用於按上游轉譯模型 ID。對於非美國 Amazon Bedrock 區域、Amazon Bedrock 佈建輸送量 ARN 和 Microsoft Foundry 部署名稱是必需的。
639 754
640```yaml theme={null}755```yaml theme={null}
641auto_include_builtin_models: true # false: expose only the list below756auto_include_builtin_models: true # false: 只公開下面的清單
642models:757models:
643 - id: claude-opus-4-8758 - id: claude-opus-4-8
644 label: Claude Opus 4.8759 label: Claude Opus 4.8
645 # description: optional text shown in clients that surface it760 # description: 在顯示它的用戶端中顯示的選用文字
646 upstream_model:761 upstream_model:
647 anthropic: claude-opus-4-8762 anthropic: claude-opus-4-8
648 bedrock: us.anthropic.claude-opus-4-8 # or an inference-profile ARN763 bedrock: us.anthropic.claude-opus-4-8 # 或推論設定檔 ARN
649 foundry: your-opus-deployment-name764 foundry: your-opus-deployment-name
650```765```
651 766
655 `managed`770 `managed`
656</h3>771</h3>
657 772
658`managed` 區塊定義基於 IdP 群組或電子郵件網域的角色型存取原則。原則按順序評估；選擇第一個匹配，然後合併到 `match: {}` 全部捕捉基礎。它們按使用者在 `GET /managed/settings` 提供，具有 ETag/304 快取。773`managed` 區塊定義基於 IdP 群組或電子郵件網域的角色型存取原則。原則按順序評估；選擇第一個匹配項，然後合併到 `match: {}` 全部捕捉基礎。它們在 `GET /managed/settings` 按使用者提供，具有 ETag/304 快取。
659 774
660```yaml theme={null}775```yaml theme={null}
661managed:776managed:
662 policies:777 policies:
663 # Specific groups first.778 # 特定群組優先。
664 - match: { groups: [eng-contractors] }779 - match: { groups: [eng-contractors] }
665 cli:780 cli:
666 availableModels: [claude-sonnet-4-6]781 availableModels: [claude-sonnet-4-6]
667 permissions: { deny: ["WebFetch", "WebSearch"] }782 permissions: { deny: ["WebFetch", "WebSearch"] }
668 # Default catch-all last: matches everyone who authenticated.783 # 預設全部捕捉最後：匹配每個已驗證的使用者。
669 - match: {}784 - match: {}
670 cli:785 cli:
671 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]786 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
672```787```
673 788
674`match: {}` 全部捕捉，按慣例列在最後，被視為基礎層。每個其他原則從全部捕捉繼承它未設定的任何金鑰，因此每個角色項目只需列出與組織預設不同的內容。合併規則取決於金鑰類型：789`match: {}` 全部捕捉（按慣例列在最後）被視為基礎層。每個其他原則從全部捕捉繼承它未設定的任何金鑰，因此每個角色項目只需列出與組織預設不同的內容。合併規則取決於金鑰類型：
675 790
676* **允許清單**：`availableModels` 和 `permissions.allow`。特定原則的清單完全替換基礎的。791* **允許清單**：`availableModels` 和 `permissions.allow`。特定原則的清單完全替換基礎的。
677* **拒絕清單和 hook 陣列**：`permissions.deny`、`permissions.ask`、`disabledMcpjsonServers`、`deniedMcpServers`、`blockedMarketplaces` 和每個 `hooks` 事件類型陣列。這些取基礎和原則的聯集，因此組織範圍的拒絕或稽核 hook 不會被每個角色覆蓋意外丟棄。792* **拒絕清單和 hook 陣列**：`permissions.deny`、`permissions.ask`、`disabledMcpjsonServers`、`deniedMcpServers`、`blockedMarketplaces` 和每個 `hooks` 事件類型陣列。這些取基礎和原則的聯集，因此組織範圍的拒絕或稽核 hook 不會被每個角色覆蓋意外丟棄。
681 796
682gateway 在轉發請求之前驗證 `model` 值本身，因此格式不正確的值永遠不會到達上游。它在兩種情況下以 `400` 拒絕請求：797gateway 在轉發請求之前驗證 `model` 值本身，因此格式不正確的值永遠不會到達上游。它在兩種情況下以 `400` 拒絕請求：
683 798
684* 當值缺失或為空時，gateway 以訊息 `model is required` 拒絕請求。該檢查需要執行 Claude Code v2.1.228 或更新版本的 gateway。799*
685* 當值存在但不是字串時，gateway 以訊息 `model must be a string` 拒絕請求。需要執行 Claude Code v2.1.221 或更新版本的 gateway。800
801當值缺失或為空時，gateway 以訊息 `model is required` 拒絕請求。該檢查需要執行 Claude Code v2.1.228 或更新版本的 gateway。
802
803*
804
805當值存在但不是字串時，gateway 以訊息 `model must be a string` 拒絕請求。需要執行 Claude Code v2.1.221 或更新版本的 gateway。
686 806
687| 匹配器 | 行為 |807| 匹配器 | 行為 |
688| - | - |808| - | - |
689| `match: {}` | 匹配每個已驗證的使用者。從其中一個開始，稍後在其上方新增群組範圍的原則。 |809| `match: {}` | 匹配每個已驗證的使用者。從其中一個開始，稍後在其上方新增群組範圍的原則。 |
690| `match: { groups: [a, b] }` | 如果 JWT 的 `groups` 宣告包含任何列出的群組，則匹配。區分大小寫：群組必須符合 IdP 的確切大小寫。 |810| `match: { groups: [a, b] }` | 如果 JWT 的 `groups` 聲明包含任何列出的群組，則匹配。區分大小寫：群組必須符合 IdP 的確切大小寫。 |
691| `match: { email_domain: example.com }` | 匹配 JWT 的 `email` 宣告中最後一個 `@` 之後的部分，不區分大小寫。每個原則接受一個網域。 |811| `match: { email_domain: example.com }` | 匹配 JWT 的 `email` 聲明中最後一個 `@` 之後的部分，不區分大小寫。每個原則接受一個網域。 |
692| `match: { groups: [a], email_domain: example.com }` | 兩個條件都必須匹配 |812| `match: { groups: [a], email_domain: example.com }` | 兩個條件都必須匹配 |
693 813
694不符合任何原則的已驗證使用者獲得 gateway 的預設值，這意味著目錄中的每個模型和沒有受管設定。如果您想要保證的預設原則，請在最後新增 `match: {}` 全部捕捉。814與任何原則不匹配的已驗證使用者獲得 gateway 的預設值，這意味著目錄中的每個模型和沒有受管設定。如果您想要保證的預設原則，請在最後新增 `match: {}` 全部捕捉。
695 815
696<Note>816<Note>
697 gateway 保留沒有自己的使用者目錄。它從使用者的 IdP 令牌授權每個請求，從令牌的 `groups` 宣告讀取群組成員資格並針對它評估原則。沒有名冊可列舉，沒有帳戶可預先建立，因此沒有 SCIM 端點，因為沒有東西可供 SCIM 同步到。817 gateway 不保留自己的使用者目錄。它從使用者的 IdP 令牌授權每個請求，從令牌的 `groups` 聲明讀取群組成員資格，並根據它評估原則。沒有名冊可列舉，沒有帳戶可預先建立，因此沒有 SCIM 端點，因為沒有任何東西可供 SCIM 同步到。
698 818
699 在真實來源（您的 IdP 的原生 SCIM 佈建或專用身分治理平台）執行使用者和群組生命週期管理。那裡管理的成員資格和取消佈建透過令牌自動流入 gateway。如果您想要 Claude 帳戶本身的 SCIM 佈建，那是[Claude for Enterprise](/docs/zh-TW/admin-setup) 功能。819 在真實來源（即您的 IdP 的原生 SCIM 佈建或專用身分治理平台）執行使用者和群組生命週期管理。那裡管理的成員資格和取消佈建透過令牌自動流入 gateway。如果您想要 Claude 帳戶本身的 SCIM 佈建，那是[適用於企業的 Claude](/docs/zh-TW/admin-setup) 功能。
700 820
701 兩個傳播時鐘適用：821 兩個傳播時鐘適用：
702 822
703 * **原則內容**：編輯原則並重新部署在連接的用戶端的下一個受管設定輪詢時到達，在一小時內，除了[只在下一次啟動時適用的變更](/docs/zh-TW/server-managed-settings#fetch-and-caching-behavior)823 * **原則內容**：編輯原則並重新部署在連接的用戶端的下一個受管設定輪詢時到達，在一小時內，除了[只在下一次啟動時適用的變更](/docs/zh-TW/server-managed-settings#fetch-and-caching-behavior)
704 * **群組成員資格**：變更使用者的群組成員資格變更哪個原則匹配他們。這在下一個工作階段重新鑄造時生效，意味著下一個無聲重新整理，受 `session.ttl_hours` 限制。824 * **群組成員資格**：變更使用者的群組成員資格會變更哪個原則匹配他們。這在下一個工作階段重新鑄造時生效，意味著下一個無聲重新整理，受 `session.ttl_hours` 限制。
705</Note>825</Note>
706 826
707<h4 id="matcher-values-that-stop-the-gateway-at-boot">827<h4 id="matcher-values-that-stop-the-gateway-at-boot">
713* 空的 `groups` 清單833* 空的 `groups` 清單
714* `groups` 或 `admin_groups` 中的空項目834* `groups` 或 `admin_groups` 中的空項目
715* 空的 `email_domain`835* 空的 `email_domain`
716* 包含 `@`、空白或逗號的 `email_domain`。gateway 修剪值並在此檢查之前移除一個前導 `@`。寫入一個裸網域，例如 `example.com`。836* 包含 `@`、空格或逗號的 `email_domain`。gateway 修剪值並在此檢查之前移除一個前導 `@`。寫入一個裸網域，例如 `example.com`。
717 837
718在 v2.1.232 之前，gateway 以這些值啟動。每個值有此效果：838在 v2.1.232 之前，gateway 以這些值啟動。每個值有此效果：
719 839
720* 空的 `email_domain`：gateway 跳過網域檢查，因此具有空 `email_domain` 和沒有 `groups` 清單的原則匹配每個已驗證的使用者840* 空的 `email_domain`：gateway 跳過網域檢查，因此具有空 `email_domain` 和沒有 `groups` 清單的原則匹配每個已驗證的使用者
721* 空的 `groups` 清單：原則不匹配任何人841* 空的 `groups` 清單：原則不匹配任何人
722* 包含 `@`、空白或逗號的 `email_domain`：原則不匹配任何人842* 包含 `@`、空格或逗號的 `email_domain`：原則不匹配任何人
723* `groups` 或 `admin_groups` 中的空項目：項目只在該使用者的 IdP `groups` 宣告也包含空項目時匹配使用者。在 `admin_groups` 中，該匹配授予 admin 存取權。如果您的 `admin_groups` 清單從未包含空項目，沒有人以此方式獲得 admin 存取權。843* `groups` 或 `admin_groups` 中的空項目：項目只在該使用者的 IdP `groups` 聲明也包含空項目時匹配使用者。在 `admin_groups` 中，該匹配授予 admin 存取權。如果您的 `admin_groups` 清單從未包含空項目，沒有人以此方式獲得 admin 存取權。
724 844
725<h4 id="what-goes-in-cli">845<h4 id="what-goes-in-cli">
726 `cli` 中的內容846 `cli` 中的內容
728 848
729每個 `cli` 值是完整的 Claude Code `managed-settings.json` 文件，與您透過 MDM 或 `/etc/claude-code/managed-settings.json` 部署的相同架構，在此表示為 YAML。CLI 在受管層級應用傳遞的文件，在使用者和專案設定之上，代替伺服器受管設定。因此它忽略[限制於 OS 層級原則來源](/docs/zh-TW/server-managed-settings#current-limitations)的設定，例如 `policyHelper` 和 `wslInheritsWindowsSettings`。849每個 `cli` 值是完整的 Claude Code `managed-settings.json` 文件，與您透過 MDM 或 `/etc/claude-code/managed-settings.json` 部署的相同架構，在此表示為 YAML。CLI 在受管層級應用傳遞的文件，在使用者和專案設定之上，代替伺服器受管設定。因此它忽略[限制於 OS 層級原則來源](/docs/zh-TW/server-managed-settings#current-limitations)的設定，例如 `policyHelper` 和 `wslInheritsWindowsSettings`。
730 850
731gateway 在啟動時針對 CLI 的設定架構驗證每個文件，因此無法識別的頂層金鑰會導致啟動失敗，並出現命名每個違規金鑰的錯誤。架構的刻意開放部分仍接受任意值，因為較新的用戶端可能識別 gateway 的架構不識別的項目。這些開放金鑰包括 `env`、`pluginConfigs` 和 `permissions` 下的巢狀金鑰。851gateway 在啟動時根據 CLI 的設定架構驗證每個文件，因此無法識別的頂層金鑰會導致啟動失敗，並出現命名每個違規金鑰的錯誤。架構的刻意開放部分仍接受任意值，因為較新的用戶端可能識別 gateway 架構不識別的項目。這些開放金鑰包括 `env`、`pluginConfigs` 和 `permissions` 下的巢狀金鑰。
732 852
733因為驗證使用與 gateway 已安裝版本捆綁的架構，將較新 Claude Code 版本引入的頂層設定金鑰放入受管設定需要先升級 gateway。在將新原則推出給所有用戶端之前，先在一個用戶端上進行煙霧測試。853因為驗證使用與 gateway 已安裝版本捆綁的架構，將較新 Claude Code 版本引入的頂層設定金鑰放入受管設定需要先升級 gateway。在一個用戶端上煙霧測試新原則，然後再推出。
734 854
735完整金鑰參考在[Claude Code 設定](/docs/zh-TW/settings-reference#all-settings)中。運營者首先尋求的金鑰：855完整金鑰參考在[Claude Code 設定](/docs/zh-TW/settings-reference#all-settings)中。運營者首先尋求的金鑰：
736 856
739 policies:859 policies:
740 - match: {}860 - match: {}
741 cli:861 cli:
742 # Model access (also enforced server-side at /v1/messages)862 # 模型存取（也在 /v1/messages 伺服器端強制執行）
743 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]863 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
744 864
745 # Permission policy865 # 權限原則
746 permissions:866 permissions:
747 deny:867 deny:
748 - "WebFetch"868 - "WebFetch"
749 - "Read(./.env)"869 - "Read(./.env)"
750 - "Read(./secrets/**)"870 - "Read(./secrets/**)"
751 disableBypassPermissionsMode: disable # blocks --dangerously-skip-permissions871 disableBypassPermissionsMode: disable # 阻止 --dangerously-skip-permissions
752 allowManagedPermissionRulesOnly: true # ignore user/project permission rules872 allowManagedPermissionRulesOnly: true # 忽略使用者/專案權限規則
753 873
754 # Environment pushed into the CLI process. DISABLE_UPDATES blocks874 # 推送到 CLI 程序的環境。DISABLE_UPDATES 阻止
755 # background and manual updates; DISABLE_AUTOUPDATER stops only875 # 背景和手動更新；DISABLE_AUTOUPDATER 只停止
756 # background updates.876 # 背景更新。
757 env:877 env:
758 DISABLE_UPDATES: "1" # pin versions via your own distribution878 DISABLE_UPDATES: "1" # 透過您自己的發佈固定版本
759 879
760 # Org-wide hooks. Hook commands run on developer machines, not the880 # 組織範圍的 hook。Hook 命令在開發者機器上執行，不是
761 # gateway, so the path must exist on every client OS in the policy.881 # gateway，因此路徑必須存在於原則中每個用戶端 OS 上。
762 hooks:882 hooks:
763 PostToolUse:883 PostToolUse:
764 - matcher: "Edit|Write"884 - matcher: "Edit|Write"
776| `hooks` | CLI | 組織範圍的 [hooks](/docs/zh-TW/hooks) |896| `hooks` | CLI | 組織範圍的 [hooks](/docs/zh-TW/hooks) |
777| `managedMcpServers` | CLI | 遠端 MCP 伺服器[提供給每個匹配的開發者](/docs/zh-TW/managed-mcp#provide-servers-through-managed-settings)以及他們自己新增的伺服器，`http` 和 `sse` 只。請參閱[原則中的 MCP 伺服器](#mcp-servers-in-a-policy)。需要 gateway 伺服器和用戶端上的 Claude Code v2.1.259 或更新版本。較早的用戶端忽略金鑰。 |897| `managedMcpServers` | CLI | 遠端 MCP 伺服器[提供給每個匹配的開發者](/docs/zh-TW/managed-mcp#provide-servers-through-managed-settings)以及他們自己新增的伺服器，`http` 和 `sse` 只。請參閱[原則中的 MCP 伺服器](#mcp-servers-in-a-policy)。需要 gateway 伺服器和用戶端上的 Claude Code v2.1.259 或更新版本。較早的用戶端忽略金鑰。 |
778 898
779因為這些設定透過網路到達，CLI 在應用下列列出的設定之前向每位開發者顯示安全核准對話框：899因為這些設定透過網路到達，CLI 在應用下面列出的設定之前向每位開發者顯示安全核准對話框：
780 900
781* `hooks`901* `hooks`
782* 需要開發者核准的 `env` 變數，例如代理和基礎 URL 變數902* 需要開發者核准的 `env` 變數，例如代理和基礎 URL 變數
783* 殼層執行設定，例如 `apiKeyHelper` 和 `statusLine`903* shell 執行設定，例如 `apiKeyHelper` 和 `statusLine`
784* 沙箱二進位設定 `sandbox.bwrapPath`、`sandbox.socatPath` 和 `sandbox.ripgrep`904* 沙箱二進位設定 `sandbox.bwrapPath`、`sandbox.socatPath` 和 `sandbox.ripgrep`
785* 攔截流量、注入認證或削弱隔離的沙箱設定，例如 `sandbox.network.tlsTerminate` 和代理連接埠設定。[安全核准對話框](/docs/zh-TW/server-managed-settings#security-approval-dialogs)列出所有。905* 攔截流量、注入認證或削弱隔離的沙箱設定，例如 `sandbox.network.tlsTerminate` 和代理連接埠設定。[安全核准對話框](/docs/zh-TW/server-managed-settings#security-approval-dialogs)列出所有。
786 906
787[核准記憶](/docs/zh-TW/server-managed-settings#approval-memory)涵蓋核准持續多長時間以及何時再次出現對話框。907[核准記憶](/docs/zh-TW/server-managed-settings#approval-memory)涵蓋核准持續多長時間以及何時再次出現對話框。
788 908
789Claude Code 應用某些傳遞的 `env` 變數而不向開發者顯示核准對話框，例如模型選擇設定和數值限制。其他傳遞的變數可能需要開發者的核准才能生效；非空代理、基礎 URL 或 `OTEL_EXPORTER_OTLP_ENDPOINT` 值總是如此。當傳遞的變數需要核准時，對話框命名它。909Claude Code 應用某些傳遞的 `env` 變數而不向開發者顯示核准對話框，例如模型選擇設定和數值限制。其他傳遞的變數可能需要開發者的核准才能生效；非空代理、基礎 URL 或 `OTEL_EXPORTER_OTLP_ENDPOINT` 值總是這樣。當傳遞的變數需要核准時，對話框會命名它。
790 910
791[環境變數和核准對話框](/docs/zh-TW/server-managed-settings#environment-variables-and-the-approval-dialog)有詳細資訊，包括四個隱私切換，其傳遞值決定它們是否需要核准。在 v2.1.218 之前，Claude Code 應用較少的變數而不詢問開發者，因此更多傳遞的變數觸發對話框。911[環境變數和核准對話框](/docs/zh-TW/server-managed-settings#environment-variables-and-the-approval-dialog)有詳細資訊，包括四個隱私切換，其傳遞值決定它們是否需要核准。
912在 v2.1.218 之前，Claude Code 應用較少的變數而不詢問開發者，因此更多傳遞的變數觸發對話框。
792 913
793gateway 的[遙測](#telemetry)設定推送 `OTEL_EXPORTER_OTLP_ENDPOINT`，因此設定 `telemetry.forward_to` 在每個互動式用戶端上觸發對話框。對話框保護開發者的機器免受受損或敵對 gateway 的影響，而不是保護組織免受開發者的影響。914gateway 的[遙測](#telemetry)設定推送 `OTEL_EXPORTER_OTLP_ENDPOINT`，因此設定 `telemetry.forward_to` 在每個互動式用戶端上觸發對話框。對話框保護開發者的機器免受受損或敵對 gateway 的影響，而不是保護組織免受開發者的影響。
794 915
795具有 `-p` 旗標的非互動式執行無法顯示對話框。它僅針對該執行應用推送的設定，不將其記錄為已核准，因此開發者的下一個互動式工作階段仍會顯示它們的對話框。在 v2.1.207 之前，非互動式執行將設定儲存為已核准，沒有後來的互動式工作階段顯示它們的對話框。916[非互動式執行](/docs/zh-TW/server-managed-settings#security-approval-dialogs)（例如 `claude -p` 或 Agent SDK 工作階段）無法顯示對話框。它只為該執行應用推送的設定，不將其記錄為已核准，因此開發者的下一個互動式工作階段仍會顯示對話框。在 v2.1.207 之前，非互動式執行將設定儲存為已核准，沒有後來的互動式工作階段顯示對話框。
796 917
797如果開發者拒絕，Claude Code 會退出該工作階段而不是應用原則。當您推送新 hook 或任何觸發對話框的 env 變數到廣泛原則時，Claude Code 因此向每個匹配的開發者顯示對話框。它在執行中的工作階段上在下一個每小時輪詢時顯示對話框，否則在開發者的下一次啟動時顯示。918如果開發者拒絕，Claude Code 會退出該工作階段，而不是應用原則。當您推送新 hook 或任何觸發對話框的 env 變數到廣泛原則時，每個匹配的開發者因此在其互動式工作階段中看到對話框。執行中的互動式工作階段在下一個每小時輪詢時顯示它，否則它在開發者的下一個互動式啟動時出現。
798 919
799`cli` 金鑰在較早版本中命名為 `settings`。該拼寫仍被接受為別名，但新部署應使用 `cli`。920`cli` 金鑰在較早版本中命名為 `settings`。該拼寫仍被接受為別名，但新部署應使用 `cli`。
800 921
802 原則中的 MCP 伺服器923 原則中的 MCP 伺服器
803</h4>924</h4>
804 925
805要向原則匹配的 Claude Code 用戶端提供 MCP 伺服器，在該原則的 `cli` 區塊中設定 [`managedMcpServers`](/docs/zh-TW/managed-mcp#provide-servers-through-managed-settings)。您需要 gateway 伺服器和用戶端上的 Claude Code v2.1.259 或更新版本。926要將 MCP 伺服器提供給原則匹配的 Claude Code 用戶端，在該原則的 `cli` 區塊中設定 [`managedMcpServers`](/docs/zh-TW/managed-mcp#provide-servers-through-managed-settings)。您需要 gateway 伺服器和用戶端上的 Claude Code v2.1.259 或更新版本。
806 927
807gateway 在啟動時使用[Claude Code 在用戶端應用的相同規則](/docs/zh-TW/managed-mcp#what-an-entry-can-contain)檢查每個項目，如果項目未通過檢查，gateway 會拒絕啟動並命名項目。928gateway 在啟動時使用 [Claude Code 在用戶端應用的相同規則](/docs/zh-TW/managed-mcp#what-an-entry-can-contain)檢查每個項目，如果項目未通過檢查，gateway 會拒絕啟動並命名項目。
808 929
809如果您在 `gateway.yaml` 中寫入 `${VAR}` 參考，gateway 在啟動時透過[秘密擴展](#secret-expansion)從其環境解析它，然後執行項目檢查，因此每個匹配的用戶端接收字面值並可以讀取它。[提供伺服器的標頭指導](/docs/zh-TW/managed-mcp#provide-servers-through-managed-settings)適用於擴展值。930如果您在 `gateway.yaml` 中寫入 `${VAR}` 參考，gateway 在啟動時透過[秘密擴展](#secret-expansion)從其環境解析它，然後執行項目檢查，因此每個匹配的用戶端接收字面值並可以讀取它。[提供伺服器的標頭指導](/docs/zh-TW/managed-mcp#provide-servers-through-managed-settings)適用於擴展值。
810 931
814 Claude Desktop 覆蓋935 Claude Desktop 覆蓋
815</h4>936</h4>
816 937
817如果您的組織也部署[Claude Desktop](/docs/zh-TW/desktop)，相同的 gateway 為兩個用戶端提供服務。在 Claude Desktop 的[受管設定](https://claude.com/docs/third-party/claude-desktop/configuration)中指向 `bootstrapUrl` 到 `<listen.public_url>/user/bootstrap`。Claude Desktop 從該 URL 衍生 OAuth 簽發者，針對此 gateway 執行相同的裝置代碼登入，並從回應擷取其設定。938如果您的組織也部署[Claude Desktop](/docs/zh-TW/desktop)，相同的 gateway 為兩個用戶端提供服務。在 Claude Desktop 的[受管設定](https://claude.com/docs/third-party/claude-desktop/configuration)中指向 `bootstrapUrl` 到 `<listen.public_url>/user/bootstrap`。Claude Desktop 從該 URL 衍生 OAuth 發行者，針對此 gateway 執行相同的裝置代碼登入，並從回應擷取其設定。
818 939
819<Note>940<Note>
820 需要 gateway 伺服器上的 Claude Code v2.1.203 或更新版本，以及明確的選擇加入：除非匹配使用者的原則帶有 `desktop` 金鑰，否則 `/user/bootstrap` 返回 404。空的 `desktop: {}` 選擇加入原則，`match: {}` 基礎層上的 `desktop` 金鑰選擇加入繼承它的每個原則。稽核日誌將每個請求記錄為 `desktop_bootstrap.serve` 或 `desktop_bootstrap.denied`。941 需要 gateway 伺服器上的 Claude Code v2.1.203 或更新版本，以及明確的選擇加入：除非匹配使用者的原則攜帶 `desktop` 金鑰，否則 `/user/bootstrap` 返回 404。空的 `desktop: {}` 選擇加入原則，`match: {}` 基礎層上的 `desktop` 金鑰選擇加入每個繼承它的原則。稽核日誌將每個請求記錄為 `desktop_bootstrap.serve` 或 `desktop_bootstrap.denied`。
821</Note>942</Note>
822 943
823gateway 從匹配原則的 `cli` 區塊和頂層 gateway 設定衍生大部分回應：944gateway 從匹配原則的 `cli` 區塊和頂層 gateway 設定衍生大部分回應：
824 945
825* 模型清單，來自 `availableModels`946* 模型清單，來自 `availableModels`
826* 已停用的工具，來自裸工具名稱 `permissions.deny` 項目。如果您在原則的 `desktop` 區塊中設定 `disabledBuiltinTools`，gateway 提供您的值和衍生清單的聯集，因此您可以透過此方式停用更多工具，但無法重新啟用您透過 `permissions.deny` 停用的工具947* 禁用的工具，來自裸工具名稱 `permissions.deny` 項目。如果您在原則的 `desktop` 區塊中設定 `disabledBuiltinTools`，gateway 提供您的值和衍生清單的聯集，因此您可以透過此方式禁用更多工具，但無法重新啟用您透過 `permissions.deny` 禁用的工具
827* 出口允許清單，來自 `sandbox.network.allowedDomains`。如果您在原則的 `desktop` 區塊中設定 `coworkEgressAllowedHosts`，gateway 使用該值而不是衍生清單948* 出口允許清單，來自 `sandbox.network.allowedDomains`。如果您在原則的 `desktop` 區塊中設定 `coworkEgressAllowedHosts`，gateway 使用該值而不是衍生清單
828* 指向 gateway 本身的 OTLP 端點，以及已登入使用者的身分屬性。gateway 轉發它在該端點接收的匯出到您的 `forward_to` 目的地。當您同時設定 [`telemetry.forward_to`](#telemetry) 和 `listen.public_url` 時，它包括端點和屬性。949* 指向 gateway 本身的 OTLP 端點，以及已登入使用者的身分屬性。gateway 轉發它在該端點接收的匯出到您的 `forward_to` 目的地。當您同時設定 [`telemetry.forward_to`](#telemetry) 和 `listen.public_url` 時，它包括端點和屬性。
829 950
830 Claude Desktop 以一種編碼匯出每個信號：`http/protobuf`，或當您在原則的 `env` 中設定 `OTEL_EXPORTER_OTLP_PROTOCOL` 或其每個信號變體為 `http/json` 時為 `http/json`。在 gateway 伺服器上的 Claude Code v2.1.261 之前，回應設定 `http/json` 無論如何，因此只接受 protobuf 的收集器拒絕 Claude Desktop 的匯出951 Claude Desktop 以一種編碼匯出每個信號：`http/protobuf`，或當您在原則的 `env` 中設定 `OTEL_EXPORTER_OTLP_PROTOCOL` 或其每個信號變體為 `http/json` 時為 `http/json`。
952 在 gateway 伺服器上的 Claude Code v2.1.261 之前，回應設定 `http/json` 無論如何，因此只接受 protobuf 的收集器拒絕 Claude Desktop 的匯出
831 953
832要在原則的 `desktop` 區塊中設定 `disabledBuiltinTools`、`coworkEgressAllowedHosts` 或 Claude Desktop 自己的 `managedMcpServers` 設定，您需要 gateway 伺服器上的 Claude Code v2.1.232 或更新版本。Claude Desktop 的 `managedMcpServers` 採用陣列值而不是物件。954要在原則的 `desktop` 區塊中設定 `disabledBuiltinTools`、`coworkEgressAllowedHosts` 或 Claude Desktop 自己的 `managedMcpServers` 設定，您需要 gateway 伺服器上的 Claude Code v2.1.232 或更新版本。Claude Desktop 的 `managedMcpServers` 採用陣列值而不是物件。
833 955
834gateway 省略沒有 Claude Desktop 等效項的金鑰，例如 `hooks` 和範圍權限規則（如 `Bash(npm *)`），來自啟動回應。956gateway 省略沒有 Claude Desktop 等效項的金鑰，例如 `hooks` 和範圍權限規則（如 `Bash(npm *)`），來自啟動回應。
835 957
836在 `cli` 旁邊新增選用的 `desktop` 區塊以直接設定 Claude Desktop 設定。從 Claude Desktop 的[受管設定參考](https://claude.com/docs/third-party/claude-desktop/configuration)寫入設定為平面金鑰名稱。省略 Claude Desktop 只從 MDM 或本機檔案讀取的金鑰，例如 `bootstrapUrl`；gateway 在啟動時拒絕它們。在 v2.1.232 之前，gateway 接受固定的 11 個功能閘道金鑰清單，例如 `chatTabEnabled` 和 `disableAutoUpdates`，並在啟動時拒絕每個其他金鑰。在 v2.1.227 之前，gateway 也在啟動時拒絕 `chatTabEnabled` 和 `chatAdvancedFileAnalysisEnabled`。958在 `cli` 旁邊新增選用的 `desktop` 區塊以直接設定 Claude Desktop 設定。
959從 Claude Desktop 的[受管設定參考](https://claude.com/docs/third-party/claude-desktop/configuration)寫入設定為平面金鑰名稱。省略 Claude Desktop 只從 MDM 或本機檔案讀取的金鑰，例如 `bootstrapUrl`；gateway 在啟動時拒絕它們。在 v2.1.232 之前，gateway 接受固定的 11 個功能閘道金鑰清單，例如 `chatTabEnabled` 和 `disableAutoUpdates`，並在啟動時拒絕每個其他金鑰。
960在 v2.1.227 之前，gateway 也在啟動時拒絕 `chatTabEnabled` 和 `chatAdvancedFileAnalysisEnabled`。
837 961
838```yaml theme={null}962```yaml theme={null}
839managed:963managed:
847 banner: { text: "Contractor build: internal use only" }971 banner: { text: "Contractor build: internal use only" }
848```972```
849 973
850每個金鑰都是選用的；Claude Desktop 為您省略的任何金鑰應用自己的預設值。gateway 在啟動時針對 Claude Desktop 本身使用的設定架構驗證每個 `desktop` 區塊，因此錯誤會在 gateway 啟動時作為命名金鑰的錯誤出現，而不是到達每個連接的桌面。當區塊包含以下內容時，gateway 在啟動時失敗：974每個金鑰都是選用的；Claude Desktop 為您省略的任何金鑰應用自己的預設值。gateway 在啟動時根據 Claude Desktop 本身使用的設定架構驗證每個 `desktop` 區塊，因此錯誤會在 gateway 啟動時顯示為命名金鑰的錯誤，而不是到達每個連接的桌面。當區塊包含以下內容時，gateway 在啟動時失敗：
851 975
852* 未知金鑰976* 未知金鑰
853* 已識別的金鑰，其值 Claude Desktop 會拒絕或無聲丟棄，例如空值或巢狀項目內的拼寫錯誤的子金鑰。在 v2.1.260 之前，gateway 無聲丟棄 `managedMcpServers` 或 `orgPluginSettings` 項目的巢狀物件內的拼寫錯誤欄位，而不是在啟動時失敗。977* 已識別的金鑰，其值 Claude Desktop 會拒絕或無聲丟棄，例如空值或巢狀項目內的拼寫錯誤的子金鑰。
978 在 v2.1.260 之前，gateway 無聲丟棄 `managedMcpServers` 或 `orgPluginSettings` 項目的巢狀物件內的拼寫錯誤欄位，而不是在啟動時失敗。
854* gateway 自己計算的金鑰：推論連接、模型清單和 OTLP 轉發。透過 [`upstreams`](#upstreams)、[`models`](#models) 和 [`telemetry`](#telemetry) 區塊的 `forward_to` 設定這些。979* gateway 自己計算的金鑰：推論連接、模型清單和 OTLP 轉發。透過 [`upstreams`](#upstreams)、[`models`](#models) 和 [`telemetry`](#telemetry) 區塊的 `forward_to` 設定這些。
855* 目前金鑰的舊版別名。在啟動錯誤中，gateway 命名規範金鑰以寫入。980* 目前金鑰的舊版別名。在啟動錯誤中，gateway 命名規範金鑰以寫入。
856 981
857如果您使用已棄用的值或項目形狀，例如沒有 `transport` 的 `managedMcpServers` 項目，gateway 啟動並記錄命名替換的警告。982如果您使用已棄用的值或項目形狀，例如沒有 `transport` 的 `managedMcpServers` 項目，gateway 啟動並記錄命名替換的警告。
858 983
859gateway 針對與 `cli` 區塊相同的已安裝版本捆綁的架構驗證 `desktop` 區塊。要傳遞由較新 Claude Desktop 版本引入的設定，請先升級 gateway。例如，`userPluginMarketplacesEnabled` 和 `userPluginUploadsEnabled` 需要 gateway 伺服器上的 Claude Code v2.1.260 或更新版本以及成員機器上的 Claude Desktop 1.37937.0 或更新版本。984gateway 根據與其安裝版本捆綁的架構驗證 `desktop` 區塊，如同 `cli` 區塊。要傳遞較新 Claude Desktop 版本引入的設定，請先升級 gateway。
985例如，`userPluginMarketplacesEnabled` 和 `userPluginUploadsEnabled` 需要 gateway 伺服器上的 Claude Code v2.1.260 或更新版本以及成員機器上的 Claude Desktop 1.37937.0 或更新版本。
986
987`blockReadsOutsideWorkingDirectories`、`disableBypassPermissionsMode`、`configRecheckIntervalMinutes` 和 `sshClientPath` 需要 gateway 伺服器上的 Claude Code v2.1.281 或更新版本。Microsoft 365 `managedMcpServers` 項目的 `microsoftAuthBroker` 的 `required` 值和 `continuousAccessEvaluation` 欄位也是如此。早於 `required` 值的 Claude Desktop 版本將其讀取為 `disabled`，因此只在每個成員的 Claude Desktop 支援它之後設定 `required`。Claude Desktop 的[受管設定參考](https://claude.com/docs/third-party/claude-desktop/configuration)列出首次讀取每個金鑰的版本。
860 988
861如果您在原則的 `desktop` 區塊中設定 `orgPluginSettings`，gateway 以 Claude Desktop 1.15200.0 及更新版本讀取的陣列形式提供它。較舊的桌面忽略陣列並強制執行沒有外掛工具原則，因此在依賴它之前將成員更新到 1.15200.0 或更新版本。989如果您在原則的 `desktop` 區塊中設定 `orgPluginSettings`，gateway 以 Claude Desktop 1.15200.0 及更新版本讀取的陣列形式提供它。較舊的桌面忽略陣列並強制執行沒有外掛工具原則，因此在依賴它之前將成員更新到 1.15200.0 或更新版本。
862 990
863gateway 從原則的 `desktop` 區塊未設定的金鑰填入 `match: {}` 全部捕捉的 `desktop` 區塊，與它填入原則的 `cli` 區塊的方式相同。如果您在基礎和角色原則中都設定 `disabledBuiltinTools` 或 `builtinToolPolicy`，gateway 保留基礎的限制：991gateway 從原則的 `desktop` 區塊未設定的金鑰填充 `match: {}` 全部捕捉的 `desktop` 區塊，與它填充原則的 `cli` 區塊的方式相同。如果您在基礎和角色原則中都設定 `disabledBuiltinTools` 或 `builtinToolPolicy`，gateway 保留基礎的限制：
864 992
865* `disabledBuiltinTools`：gateway 使用基礎清單和原則清單的聯集993* `disabledBuiltinTools`：gateway 使用基礎清單和原則清單的聯集
866* `builtinToolPolicy`：如果您在基礎中將工具設定為 `allow` 以外的值，gateway 保留該值，即使您在角色原則中為相同工具設定 `allow`994* `builtinToolPolicy`：如果您在基礎中將工具設定為 `allow` 以外的值，gateway 保留該值，即使您在角色原則中為相同工具設定 `allow`
867 995
868對於每個其他金鑰，如果您在角色原則中設定它，gateway 使用角色原則的值。gateway 完整替換陣列或巢狀物件（例如 `banner`），因此如果您在角色原則中設定 `banner.text`，gateway 丟棄基礎的 `banner.backgroundColor`。996對於每個其他金鑰，如果您在角色原則中設定它，gateway 使用角色原則的值。gateway 整體替換陣列或巢狀物件（例如 `banner`），因此如果您在角色原則中設定 `banner.text`，gateway 丟棄基礎的 `banner.backgroundColor`。
869 997
870如果您不部署 Claude Desktop，請完全從您的原則中省略 `desktop`；gateway 隨後從 `/user/bootstrap` 為每個使用者返回 404。998如果您不部署 Claude Desktop，完全從您的原則中省略 `desktop`；gateway 隨後為每個使用者從 `/user/bootstrap` 返回 404。
871 999
872<h4 id="precedence-with-other-managed-sources">1000<h4 id="precedence-with-other-managed-sources">
873 與其他受管來源的優先順序1001 與其他受管來源的優先順序
874</h4>1002</h4>
875 1003
876如果裝置也有 MDM 傳遞的原則或本機 `managed-settings.json`，gateway 傳遞的設定排名第一。[受管層級內的優先順序](/docs/zh-TW/managed-settings#precedence-within-the-managed-tier)在受管設定頁面上說明本機來源何時適用，並有[Claude Code 從每個 admin 來源讀取的金鑰](/docs/zh-TW/managed-settings#keys-read-from-every-admin-source)，無論它選擇哪個來源，例如沙箱鎖定金鑰、`forceRemoteSettingsRefresh` 和每個變數 `env` 合併。在 MDM 設定檔或受管設定檔案中設定的 [`policyHelper`](/docs/zh-TW/settings-reference#policyhelper) 只在 gateway 不傳遞設定時執行；項目說明其輸出替換什麼。1004如果裝置也有 MDM 傳遞的原則或本機 `managed-settings.json`，gateway 傳遞的設定排名第一。[受管層級內的優先順序](/docs/zh-TW/managed-settings#precedence-within-the-managed-tier)在受管設定頁面上說明本機來源何時適用，並有[Claude Code 從每個 admin 來源讀取的金鑰](/docs/zh-TW/managed-settings#keys-read-from-every-admin-source)，無論它選擇哪個來源，例如沙箱鎖定金鑰、`forceRemoteSettingsRefresh` 和每個變數 `env` 合併。在 MDM 設定檔或受管設定檔案中設定的 [`policyHelper`](/docs/zh-TW/settings-reference#policyhelper) 只在 gateway 傳遞沒有設定時執行；項目說明其輸出替換什麼。
877 1005
878嵌入主機（例如[Claude Desktop](/docs/zh-TW/desktop)）可以透過 SDK `managedSettings` 選項提供原則。[來自嵌入主機的父設定](/docs/zh-TW/managed-settings#parent-settings-from-embedding-hosts)說明 Claude Code 何時應用它，以及[限制父設定](/docs/zh-TW/claude-apps-gateway#restrict-parent-settings)列出哪些允許方向設定仍在沒有 `allowManaged*Only` 鎖定的情況下適用。1006嵌入主機（例如 [Claude Desktop](/docs/zh-TW/desktop)）可以透過 SDK `managedSettings` 選項提供原則。[來自嵌入主機的父設定](/docs/zh-TW/managed-settings#parent-settings-from-embedding-hosts)說明 Claude Code 何時應用它，以及[限制父設定](/docs/zh-TW/claude-apps-gateway#restrict-parent-settings)列出哪些允許方向設定仍在沒有 `allowManaged*Only` 鎖的情況下適用。
879 1007
880gateway 原則適用於機器上的每個 Claude Code 呼叫，包括非互動式 `claude -p` 執行和由 Agent SDK 衍生的工作階段。如果 gateway 在啟動時無法到達，已登入的工作階段會以錯誤退出，而不是在沒有其原則的情況下執行。1008gateway 原則適用於機器上的每個 Claude Code 呼叫，包括非互動式 `claude -p` 執行和 Agent SDK 衍生的工作階段。如果 gateway 在啟動時無法到達，已登入的工作階段會以錯誤退出，而不是在沒有其原則的情況下執行。
881 1009
882<h3 id="telemetry">1010<h3 id="telemetry">
883 `telemetry`1011 `telemetry`
884</h3>1012</h3>
885 1013
886CLI 將指標、日誌和（啟用時）追蹤傳送到 gateway，gateway 逐字轉發它們到每個已設定的目的地。匯出使用 OpenTelemetry Protocol (OTLP) over HTTP。要跳過轉發並讓工作階段直接匯出到您的收集器，[在原則中命名收集器](#export-directly-to-your-collector)。請參閱[監控使用](/docs/zh-TW/monitoring-usage)以了解 CLI 發出的指標和事件。1014CLI 將指標、日誌和（啟用時）追蹤傳送到 gateway，gateway 逐字轉發到每個已設定的目的地。匯出使用 OpenTelemetry Protocol (OTLP) over HTTP。要跳過轉發並讓工作階段直接匯出到您的收集器，[在原則中命名收集器](#export-directly-to-your-collector)。請參閱[監控使用](/docs/zh-TW/monitoring-usage)以了解 CLI 發出的指標和事件。
887 1015
888CLI 使用已驗證使用者的身分（從 gateway 簽發的 JWT 讀取）為每個匯出加上時間戳：`user.id`、`user.email` 和 `user.groups` 屬性。每位開發者的成本和使用歸因因此無需開發者端設定即可運作。1016在透過 `/login` 登入的工作階段中，CLI 使用從 gateway 發行的 JWT 讀取的已驗證使用者的身分戳記每個匯出：`user.id`、`user.email` 和 `user.groups` 屬性。每位開發者成本和使用歸因因此無需開發者端設定即可運作。
889 1017
890[Claude Desktop](#claude-desktop-overlay) 和透過 gateway 登入的 Cowork 工作階段使用 `user.email` 和 `user.groups` 以及 `enduser.id` 為其遙測加上時間戳，因此您可以使用一個 `user.email` 或 `user.groups` 查詢涵蓋終端、Desktop 和 Cowork 使用。`user.groups` 是逗號分隔的 IdP 群組清單。1018[Claude Desktop](#claude-desktop-overlay) 和透過 gateway 登入的 Cowork 工作階段使用 `user.email` 和 `user.groups` 以及 `enduser.id` 戳記其遙測，因此您可以使用一個 `user.email` 或 `user.groups` 查詢涵蓋終端、Desktop 和 Cowork 使用。`user.groups` 是逗號分隔的 IdP 群組清單。
891 1019
892Desktop 和 Cowork 遙測也帶有 `enduser.sub`，您的身分提供者為使用者簽發的 `sub` 宣告，當使用者的電子郵件變更時保持相同。終端工作階段在 `user.id` 下加上相同值，因此匹配 `enduser.sub` 對終端 `user.id` 的查詢涵蓋一位使用者的終端、Desktop 和 Cowork 使用。在 Desktop 和 Cowork 匯出上，`user.id` 是匿名識別碼，不是主體。1020Desktop 和 Cowork 遙測也攜帶 `enduser.sub`，您的身分提供者為使用者發行的 `sub` 聲明，當使用者的電子郵件變更時保持相同。終端工作階段在 `user.id` 下戳記相同值，因此匹配 `enduser.sub` 對終端 `user.id` 的查詢涵蓋一個使用者的終端、Desktop 和 Cowork 使用。在 Desktop 和 Cowork 匯出上，`user.id` 是匿名識別碼，而不是主體。
893 1021
894與來自 Claude Code 的所有 OpenTelemetry 資料一樣，這些屬性只進入您的組織設定的目的地，永遠不進入 Anthropic。1022像來自 Claude Code 的所有 OpenTelemetry 資料一樣，這些屬性只進入您的組織設定的目的地，永遠不進入 Anthropic。
895 1023
896如果使用者的群組清單在百分比編碼後超過 255 個字元，或群組名稱包含逗號或等號，gateway 會從該使用者的 Desktop 和 Cowork 遙測中省略 `user.groups`，而不是截斷它。該使用者的終端工作階段仍帶有完整清單。1024如果使用者的群組清單在百分比編碼後超過 255 個字元，或群組名稱包含逗號或等號，gateway 從該使用者的 Desktop 和 Cowork 遙測中省略 `user.groups`，而不是截斷它。該使用者的終端工作階段仍攜帶完整清單。
897 1025
898當主體在百分比編碼後超過 255 個字元，或包含空格、可列印 ASCII 外的字元，或 `,` `;` `=` `\` `"` `%` 之一時，gateway 會省略 `enduser.sub`。該使用者的 Desktop 和 Cowork 遙測保留其他屬性。1026當主體在百分比編碼後超過 255 個字元，或包含空格、可列印 ASCII 外的字元或 `,` `;` `=` `\` `"` `%` 之一時，gateway 從 Desktop 和 Cowork 遙測中省略 `enduser.sub`。該使用者的 Desktop 和 Cowork 遙測保留其他屬性。
899 1027
900您需要 gateway 伺服器上的 Claude Code v2.1.265 或更新版本，以在 Desktop 和 Cowork 遙測上使用 `user.email` 和 `user.groups`，以及每位開發者機器上的 Claude Desktop 1.24012 或更新版本，以使用 `user.groups`。1028您需要 gateway 伺服器上的 Claude Code v2.1.265 或更新版本才能在 Desktop 和 Cowork 遙測上使用 `user.email` 和 `user.groups`，以及每位開發者機器上的 Claude Desktop 1.24012 或更新版本才能使用 `user.groups`。
901 1029
902您需要 gateway 伺服器上的 Claude Code v2.1.274 或更新版本，以使用 `enduser.sub`。1030您需要 gateway 伺服器上的 Claude Code v2.1.274 或更新版本才能使用 `enduser.sub`。
903 1031
904```yaml theme={null}1032```yaml theme={null}
905telemetry:1033telemetry:
907 - url: https://otel-collector.internal.example.com1035 - url: https://otel-collector.internal.example.com
908 headers:1036 headers:
909 Authorization: ${OTLP_TOKEN}1037 Authorization: ${OTLP_TOKEN}
910 # Per-signal opt-in. Default: metrics only.1038 # 每個信號選擇加入。預設：僅指標。
911 metrics: true1039 metrics: true
912 logs: false1040 logs: false
913 traces: false1041 traces: false
919<Warning>1047<Warning>
920 每個目的地獨立選擇加入 `metrics`、`logs` 和 `traces`，預設為僅指標。信號在敏感性上有所不同：1048 每個目的地獨立選擇加入 `metrics`、`logs` 和 `traces`，預設為僅指標。信號在敏感性上有所不同：
921 1049
922 * **指標**：彙總計數器，例如 token 計數、請求計數和延遲1050 * **指標**：聚合計數器，例如 token 計數、請求計數和延遲
923 * **日誌和追蹤**：可以帶有完整 Bash 命令、工具輸入和檔案路徑，涵蓋 Claude Code 在開發者機器上執行的任何操作1051 * **日誌和追蹤**：可以攜帶完整 Bash 命令、工具輸入和檔案路徑，涵蓋 Claude Code 在開發者機器上執行的任何操作
924 1052
925 僅在具有該資料保證的存取控制和保留原則的目的地啟用日誌和追蹤。1053 只在具有該資料保證的存取控制和保留原則的目的地啟用日誌和追蹤。
926</Warning>1054</Warning>
927 1055
928每個 `forward_to` URL 必須使用 `https://`，但有一個例外，適用於 gateway 自己的迴路介面上的收集器：1056每個 `forward_to` URL 必須使用 `https://`，有一個例外，用於 gateway 自己的環回介面上的收集器：
929 1057
930* `http://localhost:<port>` 通過設定驗證，但[SSRF 防護](/docs/zh-TW/claude-apps-gateway-deploy#threat-model-summary)使用 `ECONNREFUSED_SSRF` 阻止每個匯出，除非您在 gateway 的環境中設定 `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`1058* `http://localhost:<port>` 通過設定驗證，但[SSRF 防護](/docs/zh-TW/claude-apps-gateway-deploy#threat-model-summary)除非您在 gateway 的環境中設定 `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`，否則會阻止每個匯出，出現 `ECONNREFUSED_SSRF`
931* `http://127.0.0.1:<port>` 或 `http://[::1]:<port>` 在未設定該變數的情況下啟動失敗1059* `http://127.0.0.1:<port>` 或 `http://[::1]:<port>` 除非設定該變數，否則啟動失敗
932 1060
933對於叢集內收集器，在其自己的內部位址上公開 HTTPS，或以設定變數的方式將其作為邊車執行。1061對於叢集內收集器，在其自己的內部位址上公開 HTTPS，或將其作為邊車執行，並設定變數。
934 1062
935當 `HTTPS_PROXY` 被設定時，gateway 透過該代理傳送匯出。1063當設定 `HTTPS_PROXY` 時，gateway 透過該代理傳送匯出。
936 1064
937要直接到達內部收集器，透過主機名稱或具有前導點的網域（例如 `.internal.example.com`）將其新增到 `NO_PROXY`，這需要 gateway 伺服器上的 Claude Code v2.1.277 或更新版本。確保 gateway 可以在沒有代理的情況下到達收集器。沒有前導點的項目只匹配該確切名稱，不匹配其下的名稱。CIDR 範圍不匹配。1065要直接到達內部收集器，透過主機名稱或具有前導點的網域（例如 `.internal.example.com`）將其新增到 `NO_PROXY`，這需要 gateway 伺服器上的 Claude Code v2.1.277 或更新版本。確保 gateway 可以在沒有代理的情況下到達收集器。沒有前導點的項目只匹配該確切名稱，不匹配其下的名稱。CIDR 範圍不匹配。
938 1066
939啟用[僅代理出口](#proxy-only-egress)時，改為在代理中允許收集器，因為任何 `NO_PROXY` 項目會關閉僅代理出口。1067啟用[僅代理出口](#proxy-only-egress)後，改為在代理中允許收集器，因為任何 `NO_PROXY` 項目會關閉僅代理出口。
940 1068
941遙測在 CLI 中預設關閉。當您同時設定 `telemetry.forward_to` 和 `listen.public_url` 時，gateway 透過 `/managed/settings` 推送六個環境變數來為連接的用戶端開啟它：1069遙測在 CLI 中預設關閉。當您同時設定 `telemetry.forward_to` 和 `listen.public_url` 時，gateway 透過 `/managed/settings` 推送六個環境變數來為連接的用戶端啟用它：
942 1070
943* `CLAUDE_CODE_ENABLE_TELEMETRY=1`1071* `CLAUDE_CODE_ENABLE_TELEMETRY=1`
944* `OTEL_METRICS_EXPORTER`、`OTEL_LOGS_EXPORTER` 和 `OTEL_TRACES_EXPORTER`，如果至少一個 `forward_to` 目的地啟用該信號，則每個設定為 `otlp`，否則設定為 `none`1072* `OTEL_METRICS_EXPORTER`、`OTEL_LOGS_EXPORTER` 和 `OTEL_TRACES_EXPORTER`，如果至少一個 `forward_to` 目的地啟用該信號，則每個設定為 `otlp`，否則設定為 `none`
945* `OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>`1073* `OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>`
946* `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`1074* `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`
947 1075
948當您[新增您自己的標籤](#add-your-own-labels)時，gateway 也推送 `OTEL_RESOURCE_ATTRIBUTES`。1076當您[新增自己的標籤](#add-your-own-labels)時，gateway 也推送 `OTEL_RESOURCE_ATTRIBUTES`。
949 1077
950在 gateway 伺服器上的 Claude Code v2.1.265 之前，gateway 將所有三個匯出器選擇器推送為 `otlp`，包括沒有目的地選擇加入的信號。1078在 gateway 伺服器上的 Claude Code v2.1.265 之前，gateway 推送所有三個匯出器選擇器為 `otlp`，包括沒有目的地選擇加入的信號。
951 1079
952推送的端點是從公開 URL 建立的，因此指標和日誌不需要開發者或原則的 OTEL 設定。1080推送的端點是從公開 URL 建立的，因此指標和日誌不需要開發者或原則的 OTEL 設定。
953 1081
954透過 `/login` 登入的開發者無法使用自己的 OTEL 設定重新導向匯出：1082透過 `/login` 登入的開發者無法使用自己的 OTEL 設定重新導向匯出：
955 1083
956* **本機設定的變數**：Claude Code 在受管層級應用推送的變數，因此每個變數覆蓋開發者為其本機設定的值。1084* **本機設定的變數**：Claude Code 在受管層級應用推送的變數，因此每個變數覆蓋開發者本機設定的值。
957* **本機設定的端點**：啟用 OTLP/HTTP 匯出時，CLI 忽略任何本機設定的端點，無論 gateway 是否推送了遙測變數。其匯出進入 gateway，除非原則[將您的收集器命名為端點](#export-directly-to-your-collector)。1085* **本機設定的端點**：啟用 OTLP/HTTP 匯出後，CLI 忽略任何本機設定的端點，無論 gateway 是否推送遙測變數。其匯出進入 gateway，除非原則[將您的收集器命名為端點](#export-directly-to-your-collector)。
958 1086
959沒有信號的 `forward_to` 目的地，gateway 接受並丟棄它。如果開發者已經將 Claude Code 遙測匯出到您的其中一個收集器，將其新增為 `forward_to` 目的地，如果他們匯出這些，則啟用日誌或追蹤，以便在他們登入後繼續接收其資料。要改為跳過轉發，[在原則中命名收集器](#export-directly-to-your-collector)。1087沒有信號的 `forward_to` 目的地，gateway 接受並丟棄它。如果開發者已經將 Claude Code 遙測匯出到您的其中一個收集器，將其新增為 `forward_to` 目的地，如果他們匯出那些，則啟用日誌或追蹤，因此在他們登入後它繼續接收其資料。要改為跳過轉發，[在原則中命名收集器](#export-directly-to-your-collector)。
960 1088
961[追蹤](/docs/zh-TW/monitoring-usage#traces-beta)也需要每個用戶端上的 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`。在受管原則的 `env` 區塊中設定它，因為 gateway 不推送它。開發者在已推送端點觸發的相同[安全核准對話框](#managed)中核准它。1089[追蹤](/docs/zh-TW/monitoring-usage#traces-beta)也需要每個用戶端上的 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`。在受管原則的 `env` 區塊中設定它，因為 gateway 不推送它。開發者在已經觸發推送端點的相同[安全核准對話框](#managed)中核准它。
962 1090
963僅在您想要追蹤的群組的原則中將其設定為 `1`。不設定它的原則從您的 `match: {}` 全部捕捉原則繼承值（如果該原則設定一個），根據[合併規則](#managed)。要防止群組的用戶端傳送追蹤，即使開發者在本機設定變數，請在該群組的原則中將其設定為 `0`。1091只在您想要追蹤的群組的原則中將其設定為 `1`。不設定它的原則從您的 `match: {}` 全部捕捉原則繼承值（如果該原則設定一個），根據[合併規則](#managed)。要防止群組的用戶端傳送追蹤，即使開發者本機設定變數，在該群組的原則中將其設定為 `0`。
964 1092
965protobuf 和 JSON OTLP 編碼都被轉發，任何 OpenTelemetry 相容後端都可作為目的地。1093protobuf 和 JSON OTLP 編碼都被轉發，任何 OpenTelemetry 相容後端都可作為目的地。
966 1094
967<h4 id="add-your-own-labels">1095<h4 id="add-your-own-labels">
968 新增您自己的標籤1096 新增自己的標籤
969</h4>1097</h4>
970 1098
971要在透過 gateway 登入的工作階段的遙測上放置固定標籤（例如 `service.namespace` 或 `deployment.environment.name`），設定 `telemetry.resource_attributes`。每個標籤是 OpenTelemetry 資源屬性，每個目的地接收相同的標籤。1099要在透過 gateway 登入的工作階段的遙測上放置固定標籤（例如 `service.namespace` 或 `deployment.environment.name`），設定 `telemetry.resource_attributes`。每個標籤是 OpenTelemetry 資源屬性，每個目的地接收相同的標籤。
981 deployment.environment.name: prod1109 deployment.environment.name: prod
982```1110```
983 1111
984當標籤違反這些規則之一時，gateway 會拒絕啟動，啟動錯誤命名標籤：1112當標籤違反這些規則之一時，gateway 會拒絕啟動，啟動錯誤會命名標籤：
985 1113
986* 名稱僅使用字母、數字、`.`、`_` 和 `-`1114* 名稱只使用字母、數字、`.`、`_` 和 `-`
987* 名稱不是保留的。以任何字母大小寫比較，保留名稱是以 `user.`、`enduser.` 或 `identity.` 開頭的所有內容，加上 `service.name`、`service.version`、`claude.deployment_mode`、`host.arch`、`os.type`、`os.version` 和 `wsl.version`1115* 名稱不是保留的。以任何字母大小寫比較，保留名稱是以 `user.`、`enduser.` 或 `identity.` 開頭的所有內容，加上 `service.name`、`service.version`、`claude.deployment_mode`、`host.arch`、`os.type`、`os.version` 和 `wsl.version`
988* 值是非空可列印 ASCII，沒有空格和 `, ; = \ " %` 中的任何一個1116* 值是非空可列印 ASCII，沒有空格和 `, ; = \ " %` 中的任何一個
989* 值最多 255 個字元，因為 gateway 在百分比編碼後計算它們，所以 `/`、`:` 和 `@` 各計為三個1117* 值在 gateway 在百分比編碼後計算時最多 255 個字元，因此 `/`、`:` 和 `@` 各計為三個
990* 值是文字，因此引用數字、`true` 或 `false`1118* 值是文字，因此引用數字、`true` 或 `false`
991 1119
992您需要 gateway 伺服器上的 Claude Code v2.1.281 或更新版本才能設定 `telemetry.resource_attributes`。較早的 gateway 在找到金鑰時拒絕啟動。在新增金鑰之前升級每個複本，並在回滾到較早版本之前移除金鑰。1120您需要 gateway 伺服器上的 Claude Code v2.1.281 或更新版本才能設定 `telemetry.resource_attributes`。較早的 gateway 在找到金鑰時會拒絕啟動。在新增金鑰之前升級每個複本，並在回滾到較早版本之前移除金鑰。
993 1121
994透過 `/login` 登入的終端工作階段接收標籤作為 `OTEL_RESOURCE_ATTRIBUTES`，與其他[遙測變數](#telemetry)一起推送。如果您在原則的 `env` 區塊中設定 `OTEL_RESOURCE_ATTRIBUTES`，該原則匹配的終端工作階段獲得該值而不是標籤。Claude Desktop 從 gateway 接收標籤以及 `user.email` 和其他身分屬性。1122透過 `/login` 登入的終端工作階段接收標籤作為 `OTEL_RESOURCE_ATTRIBUTES`，與其他[遙測變數](#telemetry)一起推送。如果您在原則的 `env` 區塊中設定 `OTEL_RESOURCE_ATTRIBUTES`，該原則匹配的終端工作階段獲得該值而不是標籤。Claude Desktop 從 gateway 接收標籤以及 `user.email` 和其他身分屬性。
995 1123
999 直接匯出到您的收集器1127 直接匯出到您的收集器
1000</h4>1128</h4>
1001 1129
1002要讓透過 `/login` 登入的工作階段直接將遙測傳送到您的收集器而不是透過轉發，在[受管原則](#managed)的 `env` 區塊中將 `OTEL_EXPORTER_OTLP_ENDPOINT` 設定為收集器的 `https://` 基礎 URL。Claude Code 將 `/v1/metrics`、`/v1/logs` 或 `/v1/traces` 附加到您設定的 URL，例如 `https://otel-collector.example.com:4318`，並透過 OTLP/HTTP 在那裡匯出每個信號。需要每位開發者機器上的 Claude Code v2.1.265 或更新版本。較早的用戶端透過轉發匯出。1130要讓透過 `/login` 登入的工作階段直接將遙測傳送到您的收集器而不是透過轉發，在[受管原則](#managed)的 `env` 區塊中將 `OTEL_EXPORTER_OTLP_ENDPOINT` 設定為收集器的 `https://` 基礎 URL。Claude Code 將 `/v1/metrics`、`/v1/logs` 或 `/v1/traces` 附加到您設定的 URL，例如 `https://otel-collector.example.com:4318`，並在那裡透過 OTLP/HTTP 匯出每個信號。需要每位開發者機器上的 Claude Code v2.1.265 或更新版本。較早的用戶端透過轉發匯出。
1003 1131
1004要向收集器驗證，在相同的 `env` 區塊中設定 `OTEL_EXPORTER_OTLP_HEADERS`。工作階段永遠不會將開發者的 gateway 工作階段令牌傳送到以此方式命名的收集器。1132要驗證到收集器，在相同的 `env` 區塊中設定 `OTEL_EXPORTER_OTLP_HEADERS`。工作階段永遠不會將開發者的 gateway 工作階段令牌傳送到以此方式命名的收集器。
1005 1133
1006當您在原則中新增或變更此端點時，Claude Code 在[安全核准對話框](#managed)中要求每位開發者核准它，然後才在互動式工作階段中應用它。1134當您在原則中新增或變更此端點時，Claude Code 在[安全核准對話框](#managed)中要求每位開發者核准它，然後在互動式工作階段中應用它。
1007 1135
1008Claude Code 在匯出信號之前檢查端點，並在檢查失敗時將該信號保留在轉發上。檢查包括：1136Claude Code 在直接匯出信號之前檢查端點，並在檢查失敗時將該信號保留在轉發上。檢查包括：
1009 1137
1010* 端點來自 gateway 本身。如果您在 MDM 設定檔或本機 `managed-settings.json` 中設定相同變數，匯出保留在轉發上。1138* 端點來自 gateway 本身。如果您在 MDM 設定檔或本機 `managed-settings.json` 中設定相同變數，匯出保留在轉發上。
1011* URL 使用 `https://`，或 `http://` 到迴路位址1139* URL 使用 `https://`，或 `http://` 到環回位址
1012* URL 解析為以 `/v1/<signal>` 結尾的路徑，沒有查詢或片段。Claude Code 從通用變數自己建立該路徑。它使用每個信號變數（例如 `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`）如寫入，因此在那裡包括完整路徑。1140* URL 解析為以 `/v1/<signal>` 結尾的路徑，沒有查詢或片段。Claude Code 從通用變數自己建立該路徑。它使用每個信號變數（例如 `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`）如寫入，因此在那裡包括完整路徑。
1013* URL 不是 gateway 自己的主機。指向 gateway 的端點保留轉發路徑及其工作階段令牌。1141* URL 不是 gateway 自己的主機。尋址到 gateway 的端點保留轉發路徑和其工作階段令牌。
1014* 您和開發者都未在任何設定來源中設定 [`otelHeadersHelper`](/docs/zh-TW/settings-reference#otelheadershelper)。設定了助手，每個信號保留在轉發上。1142* 您和開發者都未在任何設定來源中設定 [`otelHeadersHelper`](/docs/zh-TW/settings-reference#otelheadershelper)。設定了助手，每個信號保留在轉發上。
1015 1143
1016您命名的端點只改變匯出的去向。您仍然使用 `OTEL_*_EXPORTER` 選擇器選擇哪些信號匯出。1144您命名的端點只改變匯出的去向。您仍然使用 `OTEL_*_EXPORTER` 選擇器選擇哪些信號匯出。
1017 1145
1018端點本身不開啟匯出，因此也設定執行此操作的變數，除非 gateway 已推送它們：1146端點本身不啟用匯出，因此也設定執行此操作的變數，除非 gateway 已推送它們：
1019 1147
1020* 如果 gateway 已[推送遙測變數](#telemetry)，它們涵蓋啟用、選擇器和協定，您的明確端點覆蓋推送的 `<public_url>` 值。僅針對沒有 `forward_to` 目的地啟用的信號自己設定 `OTEL_*_EXPORTER` 選擇器為 `otlp`。1148* 如果 gateway 已[推送遙測變數](#telemetry)，它們涵蓋啟用、選擇器和協議，您的明確端點覆蓋推送的 `<public_url>` 值。只為沒有 `forward_to` 目的地啟用的信號自己設定 `OTEL_*_EXPORTER` 選擇器為 `otlp`。
1021* 如果它沒有，也設定 `CLAUDE_CODE_ENABLE_TELEMETRY=1`、`OTEL_*_EXPORTER` 選擇器和 `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`。1149* 如果它沒有，也設定 `CLAUDE_CODE_ENABLE_TELEMETRY=1`、`OTEL_*_EXPORTER` 選擇器和 `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`。
1022 1150
1023當開發者登出或登入不同的 gateway 時，對收集器的匯出停止，Claude Code 丟棄每個剩餘批次，而不是晚期傳送它。1151當開發者登出或登入不同的 gateway 時，對收集器的匯出停止，Claude Code 丟棄每個剩餘批次，而不是傳送它。
1024 1152
1025<h4 id="when-a-destination-fails">1153<h4 id="when-a-destination-fails">
1026 當目的地失敗時1154 當目的地失敗時
1027</h4>1155</h4>
1028 1156
1029gateway 不緩衝、重試或儲存遙測，因此未到達目的地的匯出被丟棄，而不是晚期傳遞。每個目的地獨立成功或失敗，匯出用戶端無論如何都收到成功回應，因此失敗的傳遞只出現在 gateway 的日誌中。1157gateway 不緩衝、重試或儲存遙測，因此未到達目的地的匯出被丟棄，而不是晚期傳遞。每個目的地獨立成功或失敗，匯出用戶端無論如何都接收成功回應，因此失敗的傳遞只出現在 gateway 的日誌中。
1030 1158
1031在五次連續失敗傳遞到目的地後，gateway 在 30 秒的拉伸中暫停轉發到它，記錄每次暫停，直到傳遞成功。任何錯誤回應、逾時或連接錯誤都計為失敗傳遞，除了 `400`、`413`、`415`、`422` 和 `431`，這意味著收集器拒絕該匯出的承載為格式不正確或太大。1159在連續 5 次失敗傳遞到目的地後，gateway 在 30 秒的拉伸中暫停轉發到它，記錄每個暫停，直到傳遞成功。任何錯誤回應、逾時或連接錯誤計為失敗傳遞，除了 `400`、`413`、`415`、`422` 和 `431`，這意味著收集器拒絕該匯出的有效負載為格式不正確或太大。
1032 1160
1033被拒絕的承載既不推進也不重設失敗計數：gateway 繼續轉發到目的地並記錄警告，命名它和狀態，在目的地的第一次拒絕和之後每一百次。1161被拒絕的有效負載既不推進也不重設失敗計數：gateway 繼續轉發到目的地並記錄警告，命名它和狀態，在目的地的第一次拒絕和之後每一百次。
1034 1162
1035<h3 id="http-tuning">1163<h3 id="http-tuning">
1036 HTTP 調整1164 HTTP 調整
1040 1168
1041| 區塊 | 金鑰 | 預設 | 說明 |1169| 區塊 | 金鑰 | 預設 | 說明 |
1042| - | - | - | - |1170| - | - | - | - |
1043| `access_control` | `allow_cidrs` / `deny_cidrs` | 空 | 按用戶端位址的入站 IP 允許/拒絕，在 `trusted_proxies` 解析後。`deny_cidrs` 首先檢查；符合它的用戶端被拒絕，即使 `allow_cidrs` 也匹配。如果 `allow_cidrs` 非空，gateway 是預設拒絕。`/healthz` 和 `/readyz` 豁免於 `allow_cidrs`。當受信任代理傳送不是 IP 位址的 `X-Forwarded-For` 項目時，真實用戶端未知，gateway 記錄一次警告，命名要檢查的內容。列表適用於請求的地方，它以 `403` 和稽核原因 `xff_unparseable` 拒絕它。列表都不適用的地方，它提供請求並使用代理自己的位址作為用戶端 IP，用於每 IP 速率限制和稽核。 |1171| `access_control` | `allow_cidrs` / `deny_cidrs` | 空 | 按用戶端位址的入站 IP 允許/拒絕，在 `trusted_proxies` 解析後。`deny_cidrs` 首先檢查；符合它的用戶端被拒絕，即使 `allow_cidrs` 也匹配。如果 `allow_cidrs` 非空，gateway 是預設拒絕。`/healthz` 和 `/readyz` 豁免於 `allow_cidrs`。當受信任代理傳送不是 IP 位址的 `X-Forwarded-For` 項目時，真實用戶端未知，gateway 記錄一次警告，命名要檢查的內容。其中任一清單適用於請求，它以 `403` 和稽核原因 `xff_unparseable` 拒絕它。其中都不適用，它提供請求並使用代理自己的位址作為用戶端 IP，用於每 IP 速率限制和稽核。 |
1044| `limits` | `max_request_bytes` | 32 MiB | 最大入站請求本體；超大小請求在本體被緩衝之前獲得 `413`。為大型檔案或影像請求提高。 |1172| `limits` | `max_request_bytes` | 32 MiB | 最大入站請求本體；超大小請求在本體被緩衝之前獲得 `413`。為大型檔案或影像請求提高。 |
1045| `limits` | `max_request_header_bytes` | 未設定 | 設定時，超大小標頭返回 `431` |1173| `limits` | `max_request_header_bytes` | 未設定 | 設定時，超大小標頭返回 `431` |
1046| `limits` | `max_url_length` | 未設定 | 設定時，過長 URL 返回 `414` |1174| `limits` | `max_url_length` | 未設定 | 設定時，過長 URL 返回 `414` |
1047| `timeouts` | `upstream_ttfb_ms` | 120000 | 等待上游回應標頭（首位元組時間）的最大時間。回應本體隨後以無牆鐘上限流式傳輸。適用於直接 Anthropic 上游路徑；每個其他提供者 gateway 等待最多一小時以供回應開始。 |1175| `timeouts` | `upstream_ttfb_ms` | 120000 | 等待上游回應標頭（首位元組時間）的最大時間。回應本體隨後以無牆鐘上限流式傳輸。適用於直接 Anthropic 上游路徑；在每個其他提供者上，gateway 等待最多一小時以開始回應。 |
1048| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | 未驗證裝置授權端點上的每 IP 速率限制。為共享出口 IP 或 NAT 後面的大型組織提高。[大型推出](/docs/zh-TW/claude-apps-gateway-deploy#large-rollouts)顯示如何調整大小。這些限制僅適用於裝置授予登入流程，不適用於 `/v1/messages` 推論。請參閱[使用者代碼暴力破解抵抗](/docs/zh-TW/claude-apps-gateway-deploy#user-code-brute-force-resistance)。 |1176| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | 未驗證裝置授權端點上的每 IP 速率限制。為共享出口 IP 或 NAT 後的大型組織提高。[大型推出](/docs/zh-TW/claude-apps-gateway-deploy#large-rollouts)顯示如何調整大小。這些限制只適用於裝置授予登入流程，不適用於 `/v1/messages` 推論。請參閱[使用者代碼暴力破解抵抗](/docs/zh-TW/claude-apps-gateway-deploy#user-code-brute-force-resistance)。 |
1049| `rate_limits` | `device_verify.max` / `.window_seconds` | 10 / 600 | 在 `/device` 上 `user_code` 提交的每 IP 速率限制。這是阻止某人猜測另一位開發者代碼的原因。[大型推出](/docs/zh-TW/claude-apps-gateway-deploy#large-rollouts)顯示提高多遠。 |1177| `rate_limits` | `device_verify.max` / `.window_seconds` | 10 / 600 | 在 `/device` 上 `user_code` 提交的每 IP 速率限制。這是阻止某人猜測另一位開發者代碼的原因。[大型推出](/docs/zh-TW/claude-apps-gateway-deploy#large-rollouts)顯示提高多遠。 |
1050 1178
1051如果您將兩個 `access_control` 清單都留空（這是預設值），gateway 為任何用戶端位址提供服務，因此只有您的網路限制誰可以到達它。這很重要，因為 gateway 可以推送[受管設定](#managed)，在開發者機器上執行命令。1179如果您將兩個 `access_control` 清單都留空（預設值），gateway 為任何用戶端位址提供服務，因此只有您的網路限制誰可以到達它。這很重要，因為 gateway 可以推送[受管設定](#managed)，在開發者機器上執行命令。
1052 1180
1053當 `allow_cidrs` 為空時，gateway 在兩個地方警告，不改變它如何回答任何請求：1181當 `allow_cidrs` 為空時，gateway 在兩個地方警告，不改變它如何回答任何請求：
1054 1182
1055* **在啟動時**：操作日誌中的警告建議僅允許私有範圍 `10.0.0.0/8`、`172.16.0.0/12`、`192.168.0.0/16`、`100.64.0.0/10`、`127.0.0.0/8`、`::1/128` 和 `fc00::/7`，加上開發者連接的任何其他內部範圍。如果您將 gateway 綁定到迴路位址並設定 `trusted_proxies` 和 `public_url` 都不設定，如本機開發，警告不出現。1183* **在啟動時**：操作日誌中的警告建議只允許私有範圍 `10.0.0.0/8`、`172.16.0.0/12`、`192.168.0.0/16`、`100.64.0.0/10`、`127.0.0.0/8`、`::1/128` 和 `fc00::/7`，加上開發者連接的任何其他內部範圍。如果您將 gateway 綁定到環回位址並設定 `trusted_proxies` 和 `public_url` 都不設定，如本機開發，警告不出現。
1056* **在執行時**：第一次請求從位址外的範圍到達時，gateway 記錄警告並發出 [`access.public_client` 稽核事件](/docs/zh-TW/claude-apps-gateway-deploy#logs)，帶有用戶端 IP。兩者每個程序發生一次。連結本機位址 `169.254.0.0/16` 和 `fe80::/10` 不計為公開。gateway 在此檢查執行之前回答 `/healthz` 和 `/readyz`，因此來自公開範圍的健康探測不觸發它。1184* **在執行時**：第一次請求從私有範圍外的位址到達時，gateway 記錄警告並發出 [`access.public_client` 稽核事件](/docs/zh-TW/claude-apps-gateway-deploy#logs)，攜帶用戶端 IP。兩者每個程序執行一次。連結本機位址 `169.254.0.0/16` 和 `fe80::/10` 不計為公開。gateway 在此檢查執行之前回答 `/healthz` 和 `/readyz`，因此來自公開範圍的健康探測不觸發它。
1057 1185
1058兩個信號都使用用戶端位址，因為 gateway 解析它。如果負載平衡器、連接埠轉發或隧道轉發流量且未列在 `listen.trusted_proxies` 中，gateway 看到轉發的位址，通常是私有的，因此既不是執行時警告也不是私有允許清單捕捉透過它轉發的流量。1186兩個信號都使用 gateway 解析的用戶端位址。如果負載平衡器、連接埠轉發或隧道轉發流量且未列在 `listen.trusted_proxies` 中，gateway 看到轉發位址，通常是私有的，因此執行時警告和私有允許清單都不捕捉透過它轉發的流量。
1059 1187
1060在這樣的前端後面，首先設定 [`listen.trusted_proxies`](#listen)，以便 gateway 看到真實用戶端位址，並無論如何保持 gateway 和其前面的所有東西無法從公開網際網路到達。1188在這樣的前端後面，首先設定 [`listen.trusted_proxies`](#listen)，以便 gateway 看到真實用戶端位址，並無論如何保持 gateway 和其前面的所有東西無法從公開網際網路到達。
1061 1189
1063 `load_test_mode`1191 `load_test_mode`
1064</h3>1192</h3>
1065 1193
1066`load_test_mode` 區塊讓您負載測試 gateway，而不呼叫模型提供者。啟用時，gateway 建立和簽署每個提供者請求如常，丟棄它而不是傳送它，並透過其正常回應路徑流式傳輸罐裝回覆。回覆是填充文字，開始於說它是罐裝的句子。1194`load_test_mode` 區塊讓您負載測試 gateway，而不呼叫模型提供者。啟用時，gateway 建立和簽署每個提供者請求如常，丟棄它而不是傳送它，並透過其一般回應路徑流式傳輸罐裝回覆。回覆是填充文字，以說明它是罐裝的句子開始。
1067 1195
1068需要 gateway 伺服器上的 Claude Code v2.1.282 或更新版本。較早版本在找到金鑰時拒絕啟動。在新增區塊之前升級每個複本，並在回滾之前移除區塊。1196需要 gateway 伺服器上的 Claude Code v2.1.282 或更新版本。較早的 gateway 在找到金鑰時會拒絕啟動。在新增區塊之前升級每個複本，並在回滾之前移除區塊。
1069 1197
1070下面的範例以預設值開啟模式，回覆為大約 750 個 token 的文字，在大約 10 秒內流式傳輸：1198下面的範例以預設值啟用模式，大約 750 個 token 的文字回覆，在大約 10 秒內流式傳輸：
1071 1199
1072```yaml theme={null}1200```yaml theme={null}
1073load_test_mode:1201load_test_mode:
1074 enabled: true1202 enabled: true
1075 reply_tokens: 750 # roughly how many tokens of text each canned reply carries1203 reply_tokens: 750 # 大約每個罐裝回覆攜帶多少 token 的文字
1076 reply_seconds: 9.5 # how long a streamed reply takes1204 reply_seconds: 9.5 # 流式回覆需要多長時間
1077```1205```
1078 1206
1079| 欄位 | 必要 | 說明 |1207| 欄位 | 必需 | 說明 |
1080| - | - | - |1208| - | - | - |
1081| `enabled` | 是 | `true` 開啟模式。`false` 保留您的數字在檔案中，模式關閉。如果區塊存在而沒有它，gateway 拒絕啟動。 |1209| `enabled` | 是 | `true` 啟用模式。`false` 在模式關閉的情況下將您的數字保留在檔案中。如果區塊存在而沒有它，gateway 會拒絕啟動。 |
1082| `reply_tokens` | 否 | 預設 `750`。大約每個罐裝回覆帶有多少個文字 token，從 1 到 100000 的整數。 |1210| `reply_tokens` | 否 | 預設 `750`。大約每個罐裝回覆攜帶多少 token 的文字，1 到 100000 的整數。 |
1083| `reply_seconds` | 否 | 預設 `9.5`。流式回覆需要多長時間，從 0 到 600。`0` 一次傳送整個回覆。對非流式請求的回覆總是一次回來。 |1211| `reply_seconds` | 否 | 預設 `9.5`。流式回覆需要多長時間，從 0 到 600。`0` 一次傳送整個回覆。對非流式請求的回覆總是一次回來。 |
1084 1212
1085此模式中的負載測試涵蓋 gateway、您的 Postgres 和 gateway 前面的所有東西。它不涵蓋提供者的限制、速度或網路路徑。1213此模式中的負載測試涵蓋 gateway、您的 Postgres 和 gateway 前面的所有東西。它不涵蓋提供者的限制、速度或網路路徑。
1086 1214
1087沒有模型請求傳送到提供者，因此複本的每個請求 CPU 是估計值，讀取低於生產，生產也加密其對提供者的流量。使用小試點對真實提供者確認複本計數。在 v2.1.283 之前，估計讀取低得多。1215沒有模型請求傳送到提供者，因此複本的每個請求 CPU 是估計值，讀取低於生產，生產也加密其到提供者的流量。使用小型試驗對真實提供者確認複本計數。在 v2.1.283 之前，估計值讀取低得多。
1088 1216
1089啟用模式時，請求可以帶有 `x-load-test-user` 標頭，保存最多七位數的整數。gateway 將每個數字計為具有請求附帶的令牌的開發者的電子郵件和群組的單獨開發者。1217啟用模式時，請求可以攜帶 `x-load-test-user` 標頭，保存最多七位數的整數。gateway 將每個數字計為單獨的開發者，具有請求附帶的令牌的開發者的電子郵件和群組。
1090 1218
1091為負載測試部署提供自己的空資料庫，因為如果任何開發者已經花費任何東西，gateway 拒絕以模式啟動。1219為負載測試部署提供自己的空資料庫，因為 gateway 會拒絕在任何開發者已經花費任何東西的資料庫上啟動模式。
1092 1220
1093<Warning>1221<Warning>
1094 永遠不要為開發者使用的 gateway 開啟此。每個請求獲得罐裝回覆，沒有模型被呼叫。gateway 在啟動時記錄 `load_test_mode is on` 警告，並在模式啟用時使用 `load_test: true` 標記每個 `inference` [稽核事件](/docs/zh-TW/claude-apps-gateway-deploy#logs)。1222 永遠不要為開發者使用的 gateway 啟用此功能。每個請求獲得罐裝回覆，沒有模型被呼叫。gateway 在啟動時記錄 `load_test_mode is on` 警告，並在模式啟用時使用 `load_test: true` 標記每個 `inference` [稽核事件](/docs/zh-TW/claude-apps-gateway-deploy#logs)。
1095</Warning>1223</Warning>
1096 1224
1097<h2 id="complete-example">1225<h2 id="complete-example">
1146 postgres_url: ${GATEWAY_POSTGRES_URL}1274 postgres_url: ${GATEWAY_POSTGRES_URL}
1147 # max_connections: 51275 # max_connections: 5
1148 # connect_timeout_seconds: 51276 # connect_timeout_seconds: 5
1277 # readiness_grace_seconds: 300 # 在資料庫容錯移轉期間保持通過整備檢查
1149 1278
1150# 啟用 /v1/organizations/spend_limits（鏡像 Anthropic Admin API）1279# 啟用 /v1/organizations/spend_limits（鏡像 Anthropic Admin API）
1151# 和 /v1/messages 上的每個開發人員支出強制執行。省略以停用。1280# 和 /v1/messages 上的每個開發人員支出強制執行。省略以停用。
1165# enforcement:1294# enforcement:
1166# fail_closed_on_error: false1295# fail_closed_on_error: false
1167 1296
1297# 在不呼叫模型提供者的情況下負載測試此部署。絕不在開發人員使用的
1298# 閘道上執行：每個請求都會獲得預先錄製的回覆。
1299# load_test_mode:
1300# enabled: true
1301# # reply_tokens: 750
1302# # reply_seconds: 9.5
1303
1168# 以合約費率而非美元標價計費。需要 admin: 或1304# 以合約費率而非美元標價計費。需要 admin: 或
1169# managed: 原則。使用 managed:，相同費率也會傳送給已登入的用戶端。1305# managed: 原則。使用 managed:，相同費率也會傳送給已登入的用戶端。
1170# 下面的費率是佔位符，不是真實合約價格。1306# 下面的費率是佔位符，不是真實合約價格。
1266 1402
1267對於 Claude Desktop，在 Claude Desktop 自己的[受管設定](https://claude.com/docs/third-party/claude-desktop/configuration)中設定 `bootstrapUrl` 鍵為 `<listen.public_url>/user/bootstrap`。登入流程和每個群組原則在原則透過 `desktop` 鍵在伺服器端選擇加入後，與 CLI 的相符；沒有選擇加入，`/user/bootstrap` 會傳回 404。請參閱[Claude Desktop 覆蓋層](#claude-desktop-overlay)以了解伺服器端部分。1403對於 Claude Desktop，在 Claude Desktop 自己的[受管設定](https://claude.com/docs/third-party/claude-desktop/configuration)中設定 `bootstrapUrl` 鍵為 `<listen.public_url>/user/bootstrap`。登入流程和每個群組原則在原則透過 `desktop` 鍵在伺服器端選擇加入後，與 CLI 的相符；沒有選擇加入，`/user/bootstrap` 會傳回 404。請參閱[Claude Desktop 覆蓋層](#claude-desktop-overlay)以了解伺服器端部分。
1268 1404
1269Claude Code 僅從機器上的受管來源尊重 [`forceLoginGatewayUrl`](/docs/zh-TW/settings-reference#forcelogingatewayurl)、[`gatewayInternalNetworks`](/docs/zh-TW/settings-reference#gatewayinternalnetworks) 和 [`forceLoginMethod`](/docs/zh-TW/settings-reference#forceloginmethod) 的 `"gateway"` 值：`managed-settings.json`、macOS plist 或 Windows HKLM 登錄，或原則協助程式。開發人員在自己的 `~/.claude/settings.json` 中設定它們無效，在閘道承載中設定它們也無效。1405Claude Code 僅從機器上的受管來源尊重 [`forceLoginGatewayUrl`](/docs/zh-TW/settings-reference#forcelogingatewayurl)、[`gatewayInternalNetworks`](/docs/zh-TW/settings-reference#gatewayinternalnetworks) 和 [`forceLoginMethod`](/docs/zh-TW/settings-reference#forceloginmethod) 的 `"gateway"` 值：`managed-settings.json`、macOS plist 或 Windows HKLM 登錄，或原則協助程式。在開發人員自己的 `~/.claude/settings.json` 中設定它們無法設定閘道登入，在閘道承載中設定它們也無法。
1406
1407保留 `forceLoginMethod` 和 `forceLoginOrgUUID` 不在承載中。Claude Code 仍然從承載中讀取兩個鍵以進行其啟動認證檢查，因此在機器上保留 Anthropic 發行認證的開發人員在登入後仍會獲得[管理員原則需要 Cloud 閘道登入](/docs/zh-TW/errors#administrator-policy-requires-a-cloud-gateway-sign-in)下所述的啟動退出。
1270 1408
1271<h2 id="related">1409<h2 id="related">
1272 相關1410 相關
