1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# Claude 應用程式閘道設定
6
7> 每個 gateway.yaml 選項的參考資料：監聽器和 TLS、OIDC、工作階段、Postgres 存放區、Bedrock/Agent Platform/Foundry 上游、模型路由、受管原則和遙測。
8
9Claude 應用程式閘道部署由一個 YAML 檔案設定，按慣例稱為 `gateway.yaml`。該檔案定義閘道執行的所有操作：它在哪裡監聽、開發人員如何登入、推論去往何處，以及哪些原則和遙測適用。本頁是該檔案中每個選項的參考資料。若要撰寫您的第一個，請從[快速入門](/zh-TW/claude-apps-gateway#quickstart)開始，它會建立最小的工作設定並執行它；一旦您有了滿意的設定，[部署指南](/zh-TW/claude-apps-gateway-deploy)涵蓋將其容器化並在 Kubernetes、Cloud Run 或您自己的平台上託管。
10
11閘道在啟動時使用 `claude gateway --config /path/to/gateway.yaml` 讀取該檔案一次。每個選項都在啟動時根據架構進行驗證，因此格式不正確的設定會在啟動時失敗，並出現欄位級錯誤，而不是在首次使用時失敗。
12
13本頁末尾的[完整範例](#complete-example)涵蓋每個部分。
14
15<h2 id="file-structure">
16 檔案結構
17</h2>
18
19五個部分是[必需的](#required-sections)。所有其他部分都是[選用的](#optional-sections)，省略的部分採用其預設值。未知的鍵會導致啟動失敗，因此打字錯誤會顯示為命名錯誤，而不是被無聲地忽略的設定。
20
21**必需部分：**
22
23* [`listen`](#listen)：繫結位址、公開 URL、TLS 終止
24* [`oidc`](#oidc)：您的身分識別提供者 (IdP)，包括簽發者、用戶端、宣告對應和誰可以登入
25* [`session`](#session)：閘道鑄造的持有人令牌，包括祕密和生命週期
26* [`store`](#store)：PostgreSQL，用於裝置授權和速率限制計數器
27* [`upstreams`](#upstreams)：推論去往何處，無論是 Anthropic、Bedrock、Agent Platform 還是 Foundry
28
29**選用部分：**
30
31* [`admin`](#admin)：Admin API 驗證和支出限制的保留
32* [`enforcement`](#enforcement)：支出限制失敗開放或失敗關閉行為
33* [`models`](#models) 和 `auto_include_builtin_models`：管理員策劃的模型清單和每個上游 ID
34* [`managed`](#managed)：按 IdP 群組的受管設定原則
35* [`telemetry`](#telemetry)：OTLP 轉發到您的可觀測性堆疊
36* [`access_control`、`limits`、`timeouts`、`rate_limits`](#http-tuning)：IP 允許/拒絕、請求大小上限、上游首位元組時間和每 IP 登入限制
37
38<h2 id="secret-expansion">
39 祕密擴展
40</h2>
41
42不要直接在 `gateway.yaml` 中寫入祕密，例如 `client_secret`、`jwt_secret` 或 `postgres_url`。使用下列其中一種形式參考它們，閘道會在啟動時從環境變數或檔案解析該值：
43
44| 形式 | 解析為 | 用於 |
45| --------------- | ---------------------- | -------------------------------------- |
46| `${VAR}` | 環境變數 `VAR`。如果未定義，啟動失敗。 | 容器環境變數、透過環境注入的 AWS Secrets Manager |
47| `${file:/path}` | 檔案內容，已修剪 | Kubernetes Secret 卷掛載、Vault Agent、SOPS |
48
49<h2 id="required-sections">
50 必需部分
51</h2>
52
53<h3 id="listen">
54 `listen`
55</h3>
56
57`listen` 區塊控制閘道服務的位置：繫結位址和連接埠、外部可見的來源，以及選用的 TLS 終止。
58
59| 欄位 | 必需 | 說明 |
60| ---------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
61| `host` | 否 | 繫結位址。預設 `0.0.0.0`。 |
62| `port` | 否 | 繫結連接埠。預設 `8080`。 |
63| `public_url` | 在代理後面 | 外部可見的 `https://` 來源，用於建立 IdP `redirect_uri` 和發現中繼資料。在任何 TLS 終止代理（例如 ALB、Ingress 或 Cloud Run）後面時為必需，因為閘道在建立自己的來源時不信任 `X-Forwarded-*` 標頭；它們是用戶端可欺騙的。下面的 `trusted_proxies` 僅控制用戶端 IP 解析。啟用[遙測](#telemetry)時也是必需的，因為閘道從此 URL 建立它推送給用戶端的 OTLP 端點。 |
64| `tls.cert` / `tls.key` | 否 | 如果閘道自己終止 TLS，則為 PEM 路徑 |
65| `trusted_proxies` | 否 | 閘道前面的負載平衡器的 CIDR 或 IP。設定時，閘道僅信任來自這些對等方的 `X-Forwarded-For`，並記錄真實用戶端 IP 以進行每 IP 速率限制和稽核。等同於 nginx `set_real_ip_from`。 |
66
67<h3 id="oidc">
68 `oidc`
69</h3>
70
71OpenID Connect (OIDC) 是閘道與您的身分識別提供者一起使用的 SSO 協定；請參閱[身分識別提供者設定](/zh-TW/claude-apps-gateway-deploy#identity-provider-setup)以了解在 IdP 端註冊的內容。`oidc` 區塊將閘道連接到您的身分識別提供者，並決定誰可以登入。它命名簽發者和 OAuth 用戶端、對應攜帶電子郵件和群組的宣告，並按電子郵件網域或群組限制登入。
72
73| 欄位 | 必需 | 說明 |
74| ------------------------------- | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
75| `issuer` | 是 | OIDC 發現基礎。必須在 `/.well-known/openid-configuration` 提供發現。在生產環境中使用 HTTPS；閘道接受 `http://` 簽發者。環回簽發者（例如 `http://localhost:8081`）會被[SSRF 防護](/zh-TW/claude-apps-gateway-deploy#threat-model-summary)拒絕，除非在閘道的環境中設定了 `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`。 |
76| `client_id` / `client_secret` | 是 | 來自您的 OAuth 用戶端註冊 |
77| `allowed_email_domains` | 否 | 拒絕 `email` 宣告不在這些網域之一中的 id\_token，不區分大小寫。針對多租戶 IdP 誤設定的深度防禦。獨立於此設定，`email_verified` 宣告明確為 `false` 的 id\_token 始終被拒絕。 |
78| `allowed_groups` | 否 | 限制登入為這些 IdP 群組的成員，與 `groups_claim` 相符。允許電子郵件網域中但不在這些群組中的使用者被拒絕。需要 IdP 發出群組宣告。 |
79| `groups_claim` | 否 | 哪個 id\_token 宣告攜帶群組成員資格。預設 `groups`。Microsoft Entra 在 `roles` 下發出應用程式角色。接受平面鍵或 RFC 6901 JSON 指標，例如 `/resource_access/gateway/roles` 用於嵌套宣告。 |
80| `google_groups` | 否 | 透過 Google Workspace Admin SDK Directory API 查詢已登入使用者的群組，因為 Google 的 id\_token 不攜帶群組宣告。將 `service_account_json_path` 設定為具有 `https://www.googleapis.com/auth/admin.directory.group.readonly` 範圍的網域範圍委派的服務帳戶金鑰檔案，並將 `admin_email` 設定為服務帳戶模擬的 Workspace 管理員；Directory API 需要真實的管理員主體。每個使用者的群組電子郵件地址成為其群組宣告，因此 `allowed_groups` 和 `managed.policies.match.groups` 與群組電子郵件相符。 |
81| `email_claim` | 否 | 哪個 id\_token 宣告攜帶使用者的電子郵件。預設 `email`。某些 IdP（例如 ADFS 和 Entra B2C）改為發出 `upn` 或 `preferred_username`。接受平面鍵、JSON 指標或後備鍵清單，其中使用第一個存在的鍵。 |
82| `scopes` | 否 | 閘道請求的 OIDC 範圍的完整覆蓋。預設 `[openid, profile, email, offline_access]`。當您的 IdP 拒絕它不識別的範圍或需要自訂範圍來發出群組或電子郵件時設定。必須包含 `openid`。刪除 `offline_access` 會停用重新整理令牌，因此開發人員每 `session.ttl_hours` 重新執行瀏覽器登入。請參閱[身分識別提供者設定](/zh-TW/claude-apps-gateway-deploy#identity-provider-setup)以了解每個 IdP 範圍配方，例如 Google 的重新整理令牌流程。 |
83| `extra_auth_params` | 否 | 附加到 IdP 授權請求的額外查詢參數，逐字。這是 IdP 特定行為的覆蓋機制，例如 Google 重新整理令牌的 `access_type: offline`、某些 Entra 租戶的 `domain_hint` 或逐步提升流程的 `acr_values`。無法覆蓋閘道管理的協定參數：`state`、`nonce`、`redirect_uri`、PKCE、`scope`、`response_type`、`response_mode` 和 `client_id`。 |
84| `userinfo_fallback` | 否 | 當 id\_token 省略電子郵件或群組時，從 `/userinfo` 擷取它們。Keycloak 輕量級存取令牌、Okta 組織伺服器和 ADFS 最小令牌需要。id\_token 保持權威；userinfo 僅填補空白。預設 `false`。 |
85| `use_pkce` | 否 | 在授權請求上傳送 PKCE (S256) 挑戰。預設 `true`。僅當您的 IdP 為此機密用戶端拒絕 PKCE 時設定 `false`。 |
86| `clock_skew_seconds` | 否 | 驗證 id\_token 時間宣告時容許時鐘漂移。預設 `0`，這是嚴格的。如果您在登入後立即看到「令牌已過期/尚未有效」錯誤，請提高以應對主機/IdP 時鐘偏差。 |
87| `token_endpoint_auth_method` | 否 | 覆蓋令牌端點驗證方法。接受 `client_secret_basic` 或 `client_secret_post`。預設自動協商。 |
88| `id_token_signed_response_alg` | 否 | 預期的 id\_token 簽署演算法。預設 `RS256`。為使用 ES256、PS256 或 EdDSA 簽署的 IdP 設定。 |
89| `additional_authorized_parties` | 否 | 除了 `client_id` 之外要接受的額外 `azp` 值，用於 Keycloak 代理和令牌交換流程 |
90| `discovery_url` | 否 | 從此 URL 擷取發現文件，而不是從 `issuer` 衍生，用於代理後面重寫簽發者主機的 IdP。路徑必須包含 `/.well-known/`。 |
91| `form_action_origins` | 否 | `/device` 頁面的 `Content-Security-Policy: form-action` 指令的其他來源。閘道已允許 `'self'` 和發現的 `authorization_endpoint` 來源，但 Chrome 對整個重新導向鏈強制執行 `form-action`。如果您的 IdP 透過第二個主機重新導向，例如 Azure AD 聯合到 ADFS、中樞輪輻 Okta 或公司 SSO 攔截器，列出授權請求可能重新導向的每個來源。 |
92| `ca_cert_pem` | 否 | PEM CA 憑證，用於替換 IdP 請求的系統信任存放區。用於公司 PKI 後面的 Keycloak 或 Dex。 |
93
94<h3 id="session">
95 `session`
96</h3>
97
98`session` 區塊塑造閘道在登入後鑄造的持有人令牌：簽署它們的祕密和它們的生命週期。
99
100| 欄位 | 必需 | 說明 |
101| ------------ | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
102| `jwt_secret` | 是 | 至少 32 位元組的熵，例如來自 `openssl rand -base64 32`。簽署閘道的 HS256 持有人令牌。接受單一字串或用於輪換的陣列：索引 0 簽署，所有項目驗證。若要輪換，前置新祕密，等待 `ttl_hours`，然後刪除舊祕密。 |
103| `ttl_hours` | 否 | 閘道持有人令牌生命週期。預設 `1`。當 IdP 發出重新整理令牌時，CLI 在過期前無聲地重新整理。較短的生命週期會更快地取消佈建；較長的生命週期會減少 IdP 往返次數。如果您的 IdP 因為 `offline_access` 不可用而無法發出重新整理令牌，則沒有無聲重新整理，因此將其提高到 `8` 或 `12` 以避免每小時將開發人員送回瀏覽器登入。 |
104
105<h3 id="store">
106 `store`
107</h3>
108
109`store` 區塊將閘道指向其 PostgreSQL 資料庫，該資料庫保存裝置授權和速率限制計數器。
110
111| 欄位 | 必需 | 說明 |
112| ----------------- | -- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
113| `postgres_url` | 是 | `postgres://` 或 `postgresql://` URL。必需：裝置授權會合點，瀏覽器回呼寫入且輪詢 CLI 讀取，需要跨副本狀態。閘道在啟動時執行自己的架構遷移，因此角色需要在目標架構上 `CREATE TABLE`。如果您的安全原則禁止應用程式角色的 DDL，請使用管理員角色執行遷移，最初和每當新版本發出遷移時，並授予應用程式角色對閘道表的 `SELECT, INSERT, UPDATE, DELETE`。請參閱[升級](/zh-TW/claude-apps-gateway-deploy#upgrades)和 [Postgres](/zh-TW/claude-apps-gateway-deploy#postgres)。 |
114| `username` | 否 | 覆蓋 `postgres_url` 中的使用者 |
115| `password` | 否 | 資料庫認證。在此設定它而不是在 `postgres_url` 中，以便認證保持在 URL 之外。接受任何字元並優先於 URL 認證。 |
116| `max_connections` | 否 | 每個副本的 Postgres 連線池大小。預設 `5`，這是保守的且對共享資料庫友善。啟用[支出限制](#admin)後，熱路徑每個推論請求執行幾個操作，因此在負載下為專用資料庫提高它，並保持副本 × 此值低於資料庫的 `max_connections`。 |
117
118對於本地開發，將 `postgres_url` 指向一次性 Postgres 容器，例如 `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`。
119
120<h3 id="upstreams">
121 `upstreams`
122</h3>
123
124`upstreams` 是一個有序清單。閘道將推論轉發到解析所請求模型的第一個上游。在 `5xx`、`429` 或逾時時，它會故障轉移到下一個；其他 `4xx` 不會，因為這些錯誤可歸因於請求而不是上游。相同提供者的多個上游必須設定不同的 `name:`。
125
126Bedrock、Agent Platform 和 Foundry 用戶端在啟動時建立一次，其 SDK 在內部重新整理認證，因此輪換雲認證不需要重新啟動。靜態 Anthropic API 金鑰和持有人在啟動時讀取；請參閱 [Anthropic API](#anthropic-api)。
127
128<h4 id="anthropic-api">
129 Anthropic API
130</h4>
131
132最小的 Anthropic 上游是來自 [Claude Console](https://platform.claude.com) 的 API 金鑰：
133
134```yaml theme={null}
135upstreams:
136 - provider: anthropic
137 auth:
138 api_key: ${ANTHROPIC_API_KEY}
139 # 或 OAuth 持有人（例如工作負載身分識別聯合交換的令牌）：
140 # oauth_token: ${file:/var/run/secrets/anthropic-oauth-token}
141 # base_url: https://api.anthropic.com # 預設；覆蓋以使用轉發代理
142```
143
144兩種認證形式在它們傳送的標頭中有所不同：
145
146* **`api_key`**：傳送 `x-api-key`。在 Claude Console 中輪換它並更新環境變數。
147* **`oauth_token`**：傳送 `Authorization: Bearer`。當您的組織發出短期令牌而不是長期 API 金鑰時使用持有人形式。持有人在啟動時讀取一次，因此透過重新掛載祕密和重新啟動來重新整理。
148
149除了靜態金鑰或持有人，您可以使用工作負載身分識別聯合。按照[工作負載身分識別聯合指南](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation)建立聯合規則，然後將您的工作負載的 OIDC JWT 掛載為檔案，例如 Kubernetes 投影服務帳戶令牌或 CI 平台的 id-token。閘道將 JWT 交換為短期持有人並自動重新整理它。令牌檔案在每次交換時重新讀取，因此輪換的投影令牌無需重新啟動即可被拾取。
150
151```yaml theme={null}
152upstreams:
153 - provider: anthropic
154 auth:
155 federation_rule_id: ${ANTHROPIC_FEDERATION_RULE_ID}
156 organization_id: ${ANTHROPIC_ORGANIZATION_ID}
157 identity_token_file: /var/run/secrets/anthropic/id-token
158 # workspace_id: wrkspc_... # 如果規則涵蓋 >1 個工作區，則為必需
159 # service_account_id: svac_... # 選用的預期目標檢查
160```
161
162<h4 id="amazon-bedrock">
163 Amazon Bedrock
164</h4>
165
166對於閘道替換或前置的用戶端 Bedrock 部署，請參閱 [Claude Code on Amazon Bedrock](/zh-TW/amazon-bedrock)。閘道端上游：
167
168```yaml theme={null}
169upstreams:
170 - provider: bedrock
171 region: us-east-1
172 auth: {} # 首選：AWS 預設認證鏈
173 # 或明確認證：
174 # auth:
175 # aws_access_key_id: ${AWS_AKID}
176 # aws_secret_access_key: ${AWS_SK}
177 # aws_session_token: ${AWS_ST}
178 # 或 Bedrock API 持有人令牌：
179 # auth:
180 # aws_bearer_token: ${AWS_BEARER_TOKEN}
181 # 覆蓋 bedrock-runtime 端點以進行 FIPS 或 VPC 端點部署：
182 # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com
183```
184
185空的 `auth` 區塊使用 AWS SDK 的預設認證鏈：環境變數、`~/.aws/credentials`、ECS 任務角色、EC2 執行個體中繼資料或 EKS 上的 IRSA。在生產環境中，給予閘道 Pod 一個 IAM 角色，而不是在容器映像中嵌入靜態金鑰。
186
187| 設定 | 方式 |
188| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
189| IAM 權限 | 授予閘道的主體 `bedrock:InvokeModel` 和 `bedrock:InvokeModelWithResponseStream` 在推論設定檔 ARN 和基礎基礎模型 ARN 上。對於美國地區的內建目錄：`arn:aws:bedrock:<region>:<account>:inference-profile/us.anthropic.*` 和 `arn:aws:bedrock:*::foundation-model/anthropic.*`。 |
190| 模型存取 | 在 Bedrock 主控台中，按地區，請求並啟用您想要的 Claude 模型的模型存取。跨地區推論設定檔 (`us.anthropic.*`) 需要在設定檔跨越的每個地區中進行模型存取。 |
191| EKS (IRSA) | 建立具有上述原則和針對您叢集的 OIDC 提供者的信任原則的 IAM 角色，範圍限於閘道的服務帳戶。使用 `eks.amazonaws.com/role-arn: arn:aws:iam::<acct>:role/claude-gateway` 註釋服務帳戶。`auth: {}` 會拾取它。 |
192| ECS / EC2 | 將 IAM 角色附加到任務定義或執行個體設定檔。`auth: {}` 會拾取它。 |
193| 其他任何地方 | 透過 `AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY` 和 `AWS_SESSION_TOKEN` 環境變數傳遞認證，或在 `auth:` 中使用 `${VAR}` 擴展明確設定它們 |
194| 地區 | `region:` 是 API 端點地區。跨地區推論設定檔無論您選擇哪一個，都會跨地理位置 (US、EU、APAC) 路由。對於非美國地區或佈建輸送量 ARN，新增具有正確每上游 ID 的 [`models:`](#models) 區塊。 |
195
196<h4 id="google-cloud-agent-platform">
197 Google Cloud Agent Platform
198</h4>
199
200對於等效的用戶端設定，請參閱 [Claude Code on Google Cloud](/zh-TW/google-vertex-ai)。閘道端上游：
201
202```yaml theme={null}
203upstreams:
204 - provider: vertex
205 region: us-east5
206 project_id: example-prod
207 auth: {} # 首選：應用程式預設認證
208 # 或服務帳戶金鑰檔案：
209 # auth: { service_account_json: /secrets/sa.json }
210 # 覆蓋 aiplatform 端點以進行私人服務連線：
211 # base_url: https://us-east5-aiplatform.p.googleapis.com
212```
213
214空的 `auth` 區塊使用應用程式預設認證：`GOOGLE_APPLICATION_CREDENTIALS`、GCE 中繼資料或 GKE 工作負載身分識別。支援服務帳戶 JSON 金鑰檔案但不建議；使用工作負載身分識別或將服務帳戶附加到 GCE 或 Cloud Run 執行個體。
215
216設定 `region: global` 以使用 [Agent Platform 的全域端點](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations)而不是區域端點。Google 然後將每個請求路由到可用的地區，因此您不追蹤每個地區的模型可用性。設定特定地區會將每個請求固定到它。
217
218| 設定 | 方式 |
219| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
220| IAM 權限 | 授予閘道的服務帳戶在專案上的 `roles/aiplatform.user`，或具有 `aiplatform.endpoints.predict` 的自訂角色。啟用 Agent Platform API (`aiplatform.googleapis.com`)。 |
221| 模型存取 | 在 Model Garden 中，為您的專案啟用 Claude 模型。它們發佈到特定地區；檢查模型卡以了解支援的地區。 |
222| GKE (工作負載身分識別) | 將 GCP 服務帳戶繫結到閘道的 Kubernetes 服務帳戶，並使用 `iam.gke.io/gcp-service-account: claude-gateway@<proj>.iam.gserviceaccount.com` 註釋 KSA。`auth: {}` 會拾取它。 |
223| Cloud Run / GCE | 將服務的服務帳戶設定為具有 `roles/aiplatform.user` 的帳戶。`auth: {}` 會拾取它。 |
224| 其他任何地方 | `auth: { service_account_json: /secrets/sa.json }`，JSON 金鑰檔案的路徑，掛載為祕密。該欄位採用檔案路徑，而不是金鑰內容，因此不涉及 `${file:…}` 擴展。 |
225
226<h4 id="microsoft-foundry">
227 Microsoft Foundry
228</h4>
229
230對於用戶端 Foundry 部署，請參閱 [Claude Code on Microsoft Foundry](/zh-TW/microsoft-foundry)。閘道端上游：
231
232```yaml theme={null}
233upstreams:
234 - provider: foundry
235 resource: example-foundry # https://example-foundry.services.ai.azure.com
236 auth: { use_azure_ad: true } # 首選：DefaultAzureCredential / 受管身分識別
237 # 或 API 金鑰：
238 # auth:
239 # api_key: ${FOUNDRY_API_KEY}
240```
241
242`use_azure_ad: true` 透過 `DefaultAzureCredential` 解析：AKS、ACI 或 App Service 上的受管身分識別；Azure CLI；或環境認證。API 金鑰有效但是專案範圍的，不會自動輪換。Foundry 的端點衍生自 `resource:`；設定選用的 `base_url` 以覆蓋它以進行主權雲，例如 Azure Government。
243
244| 設定 | 方式 |
245| ----------------- | ---------------------------------------------------------------------------------------------------- |
246| RBAC | 授予閘道的身分識別在 Foundry 資源上的 `Azure AI User` 或 `Cognitive Services User` |
247| 部署 | Foundry 使用管理員選擇的部署名稱，而不是規範模型 ID。新增 [`models:`](#models) 區塊，將每個規範 ID 對應到您的部署名稱。 |
248| AKS (工作負載身分識別) | 將使用者指派的受管身分識別與叢集的 OIDC 簽發者聯合，並將其繫結到閘道的服務帳戶。`use_azure_ad: true` 透過 `WorkloadIdentityCredential` 拾取它。 |
249| ACI / App Service | 在資源上啟用系統指派或使用者指派的受管身分識別。`use_azure_ad: true` 會拾取它。 |
250| 其他任何地方 | `auth: { api_key: "${FOUNDRY_API_KEY}" }`。在 `{ }` 內引用 `${…}`。 |
251
252<h4 id="multiple-upstreams">
253 多個上游
254</h4>
255
256相同的提供者可以出現多次，具有不同的 `name:`。這涵蓋不同的地區、透過不同認證鏈的不同帳戶、佈建輸送量與隨需，以及跨提供者故障轉移。
257
258閘道按順序嘗試上游。`5xx`、`429`、逾時和遺漏端點 (`501`) 故障轉移；其他 `4xx` 不會。`429` 是每個上游容量，因此佈建輸送量 (PT) 耗盡會故障轉移到隨需。無法解析所請求模型的上游會被跳過，無需網路往返。
259
260此範例首先路由佈建輸送量 Bedrock 配額，溢出到隨需和第二個帳戶，最後故障轉移到 Anthropic API：
261
262```yaml theme={null}
263upstreams:
264 # 主要：您主區域中的佈建輸送量。
265 - name: bedrock-pt
266 provider: bedrock
267 region: us-east-1
268 auth: {}
269 # 溢出：隨需跨地區。
270 - name: bedrock-od
271 provider: bedrock
272 region: us-west-2
273 auth: {}
274 # 不同帳戶：透過假設角色認證的單獨 Bedrock 配額。
275 - name: bedrock-acct2
276 provider: bedrock
277 region: us-east-1
278 auth:
279 aws_access_key_id: ${ACCT2_AKID}
280 aws_secret_access_key: ${ACCT2_SK}
281 # 最後手段：直接 Anthropic API。
282 - name: anthropic-fallback
283 provider: anthropic
284 auth:
285 api_key: ${ANTHROPIC_API_KEY}
286
287# 每個上游模型 ID 以上游的 `name:` 為鍵；沒有 `name:` 的上游預設為其提供者字串（例如 `bedrock`）。任何未為模型列出的上游都會被跳過，這是您將模型路由到佈建輸送量的方式，而所有其他模型保持隨需。
288models:
289 - id: claude-opus-4-8
290 label: Claude Opus 4.8
291 upstream_model:
292 bedrock-pt: arn:aws:bedrock:us-east-1:111111111111:provisioned-model/abcdef
293 bedrock-od: us.anthropic.claude-opus-4-8
294 bedrock-acct2: us.anthropic.claude-opus-4-8
295 anthropic-fallback: claude-opus-4-8
296```
297
298| 槓桿 | 方式 |
299| ------------- | ----------------------------------------------------------------------------------------------------------------------------- |
300| 不同地區 | 每個地區一個 Bedrock 上游，每個都有自己的 `region:`。使用 [`auto_include_builtin_models: true`](#models)，跨地區推論設定檔會自動路由；對於地區固定部署，使用 `models:` 區塊。 |
301| 不同帳戶 | 每個帳戶一個 Bedrock 上游，每個在 `auth:` 中都有自己的認證。預設鏈 (`auth: {}`) 使用 Pod 的身分識別；對於第二個帳戶，設定明確認證或持有人令牌。 |
302| 佈建輸送量 | 將模型對應到該上游名稱的 `models:` 中的佈建輸送量 ARN。其他上游保持隨需 ID，因此 PT 容量在故障轉移前耗盡。 |
303| VPC / FIPS 端點 | 在上游上設定 `base_url:` 為您的 VPC 端點或 FIPS 端點 URL |
304| 模型範圍路由 | 從模型的 `upstream_model:` 對應中省略上游，該上游會被跳過以進行該模型。例如，將 Opus 路由到佈建輸送量，將 Sonnet 和 Haiku 路由到隨需。 |
305
306在雲提供者之間或直接 Anthropic API 之間故障轉移會改變哪些協議、地理位置和其他條款管理請求。
307
308CLI 對閘道應用相同的功能閘控，無論哪個上游服務給定請求，因此故障轉移不會傳送上游會拒絕的正文欄位。
309
310<h2 id="optional-sections">
311 選用部分
312</h2>
313
314<h3 id="admin">
315 `admin`
316</h3>
317
318選用。啟用 `/v1/organizations/spend_limits`，它鏡像 Anthropic 的公開 Admin API，以及 `/v1/messages` 上的每個開發人員支出強制執行。請參閱[支出限制](/zh-TW/claude-apps-gateway-spend-limits)以了解如何設定和強制執行上限；本部分涵蓋打開功能和調整它的 `gateway.yaml` 鍵。
319
320```yaml theme={null}
321admin:
322 # 管理員端點的命名靜態 API 金鑰，作為 x-api-key 傳送。
323 # id 在稽核日誌中顯示為 admin-key:<id>，因此每個金鑰都是
324 # 可歸因的。用於輪換的陣列：新增新金鑰、滾動用戶端、
325 # 移除舊金鑰。
326 write_keys:
327 - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
328 - { id: ci, key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }
329 read_keys:
330 - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
331 # 透過正常閘道 JWT（無 API 金鑰）授予完整管理員的 IdP 群組。
332 admin_groups: [platform-finops]
333 blocked_message: request an increase at https://go.example.com/claude-limits
334```
335
336| 欄位 | 必需 | 說明 |
337| ------------------------- | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
338| `write_keys` | 否 | `{id, key}` 的陣列。與其中一個相符的 `x-api-key` 可以列出、設定和刪除支出限制。金鑰值必須至少 32 個字元；`id` 必須在 `read_keys` 和 `write_keys` 中唯一。 |
339| `read_keys` | 否 | `{id, key}` 的陣列。唯讀：每個 `GET` 端點，包括列出上限、按 ID 擷取一個，以及讀取 [`/effective`](/zh-TW/claude-apps-gateway-spend-limits#%2Feffective) 和 [`/audit`](/zh-TW/claude-apps-gateway-spend-limits#%2Faudit)。 |
340| `admin_groups` | 否 | IdP 群組名稱。其 `groups` 宣告包含其中一個的閘道 JWT 具有完整管理員存取權，讀取和寫入，並稽核為 `oidc:<sub>`。將此用於人類管理員；將 API 金鑰用於機器。 |
341| `blocked_message` | 否 | 逐字附加到被阻止的開發人員看到的 `429 billing_error`。寫入整個指令，例如 URL 或 Slack 頻道。未設定，錯誤是 `spend limit reached`。 |
342| `audit_retention_days` | 否 | 預設 `365`。較舊的 `admin_audit` 列會被掃除。 |
343| `spend_retention_months` | 否 | 預設 `13`。早於此的 `spend` 計數器列會被掃除。預設值保留完整年份加當前部分月份以進行年度比較報告。 |
344| `identity_retention_days` | 否 | 預設 `90`。`principal_emails` 列的最後一次看到 TTL，其中保存每個開發人員的電子郵件、顯示名稱和群組 (PII)。故意比支出保留更短，因此已取消佈建的身分識別會在其匿名支出計數器保留時老化。 |
345| `group_limit_mode` | 否 | `min`（預設）或 `max`。當開發人員在具有上限的多個群組中時，`min` 強制執行最限制的，`max` 強制執行最寬鬆的。由強制執行和 `/effective` 使用。 |
346
347<h3 id="enforcement">
348 `enforcement`
349</h3>
350
351`enforcement` 區塊控制當存放區不可用時支出限制檢查的行為。
352
353| 欄位 | 必需 | 說明 |
354| ---------------------- | -- | ------------------------------------------------------------------------------------------------------------------------- |
355| `fail_closed_on_error` | 否 | 預設 `false`。支出強制執行在 Postgres 中斷時失敗開放，因此推論保持運行。設定 `true` 以失敗關閉：超過上限的開發人員被阻止，但如果存放區無法到達，每個人都被阻止。沒有 [`admin:`](#admin) 區塊時無效。 |
356
357<h3 id="models">
358 `models`
359</h3>
360
361`models` 區塊是選用的管理員策劃模型清單，在 `/v1/models` 提供並用於轉換每個上游的模型 ID。對於非美國 Bedrock 地區、Bedrock 佈建輸送量 ARN 和 Foundry 部署名稱是必需的。
362
363```yaml theme={null}
364auto_include_builtin_models: true # false：僅公開下面的清單
365models:
366 - id: claude-opus-4-8
367 label: Claude Opus 4.8
368 # description: 在表面它的用戶端中顯示的選用文字
369 upstream_model:
370 anthropic: claude-opus-4-8
371 bedrock: us.anthropic.claude-opus-4-8 # 或推論設定檔 ARN
372 foundry: your-opus-deployment-name
373```
374
375<h3 id="managed">
376 `managed`
377</h3>
378
379`managed` 區塊定義基於 IdP 群組或電子郵件網域的角色型存取原則。原則按順序評估；選擇第一個相符項，然後合併到下面描述的 `match: {}` 全部捕捉基礎上。它們按使用者在 `GET /managed/settings` 提供，具有 ETag/304 快取。
380
381```yaml theme={null}
382managed:
383 policies:
384 # 特定群組優先。
385 - match: { groups: [eng-contractors] }
386 cli:
387 availableModels: [claude-sonnet-4-6]
388 permissions: { deny: ["WebFetch", "WebSearch"] }
389 # 預設全部捕捉最後：符合每個已驗證的人。
390 - match: {}
391 cli:
392 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
393```
394
395`match: {}` 全部捕捉，按慣例列在最後，被視為基礎層。每個其他原則從全部捕捉繼承它不設定的任何鍵，因此每個角色項目只需要列出與組織預設不同的內容。合併規則取決於鍵類型：
396
397* **允許清單**：`availableModels` 和 `permissions.allow`。特定原則的清單完全替換基礎的。
398* **拒絕清單和掛鉤陣列**：`permissions.deny`、`permissions.ask`、`disabledMcpjsonServers`、`deniedMcpServers`、`blockedMarketplaces` 和每個 `hooks` 事件類型陣列。這些採用基礎和原則的聯合，因此組織範圍的拒絕或稽核掛鉤無法被每個角色覆蓋意外刪除。
399* **記錄類型鍵**：`env`、`modelOverrides` 和 `skillOverrides`。這些淺合併，因此每個角色 `env` 區塊覆蓋它設定的鍵並從基礎繼承其餘的。
400
401`availableModels` 也在 `/v1/messages` 伺服器端強制執行，因此被拒絕的模型返回 `400`，無論用戶端傳送什麼。
402
403| 匹配器 | 行為 |
404| --------------------------------------------------- | ---------------------------------------------------------- |
405| `match: {}` | 符合每個已驗證的使用者。從其中一個開始，稍後新增群組範圍的原則。 |
406| `match: { groups: [a, b] }` | 如果 JWT 的 `groups` 宣告包含任何列出的群組，則符合。區分大小寫：群組必須符合 IdP 的確切大小寫。 |
407| `match: { email_domain: example.com }` | 符合 JWT 的 `email` 宣告中最後一個 `@` 之後的部分，不區分大小寫。每個原則接受一個網域。 |
408| `match: { groups: [a], email_domain: example.com }` | 兩個條件都必須符合 |
409
410未符合任何原則的已驗證使用者獲得閘道的預設值，這意味著目錄中的每個模型和沒有受管設定。如果您想要保證的預設原則，請在最後新增 `match: {}` 全部捕捉。
411
412<Note>
413 閘道保持沒有自己的使用者目錄。它從使用者的 IdP 令牌授權每個請求，從令牌的 `groups` 宣告讀取群組成員資格，並根據它評估原則。沒有要列舉的名冊，沒有要預先建立的帳戶，因此沒有 SCIM 端點，因為沒有什麼可供 SCIM 同步到。
414
415 在真實來源（您的 IdP 的原生 SCIM 佈建或專用身分識別治理平台）執行使用者和群組生命週期管理。那裡管理的成員資格和取消佈建透過令牌自動流入閘道。如果您想要 Claude 帳戶本身的 SCIM 佈建，那是 [Claude for Enterprise](/zh-TW/admin-setup) 功能。
416
417 兩個傳播時鐘適用：
418
419 * **原則內容**：編輯原則並重新部署在連接的用戶端的下一個受管設定輪詢時到達，在一小時內
420 * **群組成員資格**：變更使用者的群組成員資格會變更哪個原則符合他們。這在下一個工作階段重新鑄造時生效，意味著下一個無聲重新整理，受 `session.ttl_hours` 限制。
421</Note>
422
423<h4 id="what-goes-in-cli">
424 `cli` 中的內容
425</h4>
426
427每個 `cli` 值是完整的 Claude Code `managed-settings.json` 文件，與您透過 MDM 或 `/etc/claude-code/managed-settings.json` 部署的相同架構，在此表示為 YAML。CLI 在受管層應用傳遞的文件，在使用者和專案設定之上。
428
429閘道在啟動時根據 CLI 的設定架構驗證每個文件，因此無法識別的頂層鍵或具有格式不正確值的識別鍵會在啟動時失敗，並出現命名每個違規鍵的錯誤。架構的故意開放部分仍然接受任意值，因為較新的用戶端可能識別閘道的架構不識別的項目。這些開放鍵是 `env`、`pluginConfigs` 和 `permissions` 下嵌套的鍵。
430
431因為驗證使用與閘道的已安裝版本捆綁的架構，將較新 Claude Code 版本引入的頂層設定鍵放入受管設定需要首先升級閘道。在將新原則推出到一個用戶端之前進行煙霧測試。
432
433完整的鍵參考在 [Claude Code 設定](/zh-TW/settings#available-settings) 中。操作員首先尋求的鍵：
434
435```yaml theme={null}
436managed:
437 policies:
438 - match: {}
439 cli:
440 # 模型存取（也在 /v1/messages 伺服器端強制執行）
441 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
442
443 # 權限原則
444 permissions:
445 deny:
446 - "WebFetch"
447 - "Read(./.env)"
448 - "Read(./secrets/**)"
449 disableBypassPermissionsMode: disable # 阻止 --dangerously-skip-permissions
450 allowManagedPermissionRulesOnly: true # 忽略使用者/專案權限規則
451
452 # 推送到 CLI 程序的環境。DISABLE_UPDATES 阻止
453 # 背景和手動更新；DISABLE_AUTOUPDATER 僅停止
454 # 背景更新。
455 env:
456 DISABLE_UPDATES: "1" # 透過您自己的發佈固定版本
457
458 # 組織範圍的掛鉤。掛鉤命令在開發人員機器上執行，而不是
459 # 閘道，因此路徑必須存在於原則中的每個用戶端 OS 上。
460 hooks:
461 PostToolUse:
462 - matcher: "Edit|Write"
463 hooks:
464 - { type: command, command: /usr/local/bin/audit-edit.sh }
465```
466
467| 鍵 | 由以下強制執行 | 效果 |
468| ------------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
469| `availableModels` | 閘道 + CLI | 模型允許清單。也在 `/v1/messages` 檢查，因此修補的用戶端無法繞過它。 |
470| `permissions.allow` / `.deny` | CLI | 工具和命令規則。請參閱[權限](/zh-TW/permissions)。 |
471| `permissions.disableBypassPermissionsMode` | CLI | 設定為 `disable` 以阻止 [`bypassPermissions`](/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode)，自動批准每個工具呼叫的模式，以及 `--dangerously-skip-permissions` 旗標 |
472| `allowManagedPermissionRulesOnly` | CLI | 當 `true` 時，使用者和專案權限規則被忽略；僅此文件中的規則適用 |
473| `env` | CLI | 合併到 CLI 程序的環境變數。用於遙測、自動更新和模型名稱覆蓋。 |
474| `hooks` | CLI | 組織範圍的[掛鉤](/zh-TW/hooks) |
475
476因為這些設定透過網路到達，CLI 在應用任何可以執行 shell 命令或改變流量去往何處的內容之前，向每個開發人員顯示一次性安全批准對話。對話涵蓋：
477
478* `hooks`
479* `env` 變數不在 CLI 的內建安全清單上
480* shell 執行設定，例如 `apiKeyHelper` 和 `statusLine`
481* 受管 CLAUDE.md 內容
482
483安全清單決定哪些 `env` 變數無需批准即可應用：
484
485* **在安全清單上**：自動更新和模型名稱變數
486* **不在安全清單上**：代理變數、基礎 URL 變數和 `OTEL_EXPORTER_OTLP_ENDPOINT`
487
488閘道的[遙測](#telemetry)設定推送 `OTEL_EXPORTER_OTLP_ENDPOINT`，因此設定 `telemetry.forward_to` 在每個互動式用戶端上觸發對話。使用 `-p` 旗標的非互動式執行跳過對話並無需批准應用設定。對話保護開發人員的機器免受受損或敵對閘道的影響，而不是保護組織免受開發人員的影響，因此 `-p` 跳過是故意的而不是差距。
489
490如果開發人員拒絕，Claude Code 退出而不是應用原則。將新掛鉤或非安全環境變數推送到廣泛原則因此意味著每個符合開發人員下一次啟動時的批准提示。
491
492`cli` 鍵在較早版本中被命名為 `settings`。該拼寫仍然被接受為別名，但新部署應使用 `cli`。
493
494<h4 id="precedence-with-other-managed-sources">
495 與其他受管來源的優先順序
496</h4>
497
498如果裝置也有本地 `managed-settings.json` 或 MDM 傳遞的原則，受管來源不合併。最高優先順序來源提供所有原則設定，按此順序排列，最高優先順序優先：
499
5001. [原則幫助程式](/zh-TW/settings#compute-managed-settings-with-a-policy-helper)
5012. 閘道傳遞的設定
5023. MDM，透過 Windows 上的 HKLM 登錄或 macOS 上的 plist
5034. `managed-settings.json` 檔案
5045. HKCU 登錄，僅在 Windows 上
505
506嵌入主機可以透過 SDK `managedSettings` 選項提供原則。預設情況下它被忽略，僅當受管來源使用 [`parentSettingsBehavior: "merge"`](/zh-TW/settings#available-settings) 選擇加入時適用，經過篩選以便它可以收緊原則但不能放鬆它。
507
508例外是一小組跨來源鍵，在任何管理來源設定它們時被尊重；使用者可寫 HKCU 層被排除：
509
510* `sandbox.network.allowManagedDomainsOnly` 和 `sandbox.filesystem.allowManagedReadPathsOnly`：當鎖定時，對應的允許清單跨來源聯合
511* [`allowAllClaudeAiMcps`](/zh-TW/settings#available-settings)：claude.ai MCP 伺服器允許清單的僅允許覆蓋
512* `sandbox.bwrapPath` 和 `sandbox.socatPath`：[沙箱](/zh-TW/sandboxing)幫助程式二進位檔的檔案系統路徑
513
514`allowManagedPermissionRulesOnly` 和 `disableBypassPermissionsMode` 不是跨來源的，因此僅獲勝來源的值適用。
515
516閘道原則適用於機器上的每個 Claude Code 呼叫，包括非互動式 `claude -p` 執行和由 Agent SDK 生成的工作階段。如果閘道在啟動時無法到達，已登入的工作階段退出並出現錯誤，而不是在沒有其原則的情況下執行。
517
518<Warning>
519 原則的 `cli` 區塊內的 `mcpServers` 在閘道啟動時被拒絕。不提供每個群組 MCP 發佈；透過每個裝置上的檔案型 `managed-mcp.json` 部署 MCP 伺服器或讓開發人員在本地新增它們。
520</Warning>
521
522<h3 id="telemetry">
523 `telemetry`
524</h3>
525
526CLI 透過 HTTP 指標、日誌和（啟用時）追蹤傳送 OpenTelemetry Protocol (OTLP) 到閘道，閘道逐字將它們轉發到每個設定的目的地。請參閱[監控使用](/zh-TW/monitoring-usage)以了解 CLI 發出的指標和事件。
527
528CLI 使用從閘道簽發的 JWT 讀取的已驗證使用者的身分識別戳記每個匯出：`user.id`、`user.email` 和 `user.groups` 屬性。每個開發人員的成本和使用歸因因此無需開發人員端設定即可運作。
529
530```yaml theme={null}
531telemetry:
532 forward_to:
533 - url: https://otel-collector.internal.example.com
534 headers:
535 Authorization: ${OTLP_TOKEN}
536 # 每個信號選擇加入。預設：僅指標。
537 metrics: true
538 logs: false
539 traces: false
540 - url: https://api.datadoghq.com/api/v2/otlp
541 headers:
542 DD-API-KEY: ${DD_API_KEY}
543```
544
545<Warning>
546 每個目的地獨立選擇加入 `metrics`、`logs` 和 `traces`，預設僅指標。信號在敏感性上有所不同：
547
548 * **指標**：聚合計數器，例如令牌計數、請求計數和延遲
549 * **日誌和追蹤**：可以攜帶完整的 bash 命令、工具輸入和檔案路徑，涵蓋 Claude Code 在開發人員機器上執行的任何操作
550
551 僅在具有該資料保證的存取控制和保留原則的目的地上啟用日誌和追蹤。
552</Warning>
553
554遙測在 CLI 中預設關閉。將 `telemetry.forward_to` 與 `listen.public_url` 一起設定會打開它。閘道透過 `/managed/settings` 推送五個環境變數到每個連接的用戶端：
555
556* `CLAUDE_CODE_ENABLE_TELEMETRY=1`
557* `OTEL_METRICS_EXPORTER=otlp`
558* `OTEL_LOGS_EXPORTER=otlp`
559* `OTEL_TRACES_EXPORTER=otlp`
560* `OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>`
561
562推送的端點是從公開 URL 建立的，因此指標和日誌不需要開發人員或原則的 OTEL 設定。推送的設定在受管層應用，覆蓋開發人員在本地設定的 `OTEL_*` 變數。
563
564[追蹤](/zh-TW/monitoring-usage#traces-beta)另外需要每個用戶端上的 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`。閘道不推送該變數，因此透過受管原則的 `env` 區塊設定它。它不在 CLI 的安全清單上，因此透過原則傳遞它由推送的 OTLP 端點已經觸發的相同[安全批准對話](#managed)涵蓋。
565
566protobuf 和 JSON OTLP 編碼都被轉發，任何 OpenTelemetry 相容後端都可作為目的地。
567
568<h3 id="http-tuning">
569 HTTP 調整
570</h3>
571
572四個選用的頂層區塊 `access_control`、`limits`、`timeouts` 和 `rate_limits` 調整 HTTP 表面。預設值適合大多數部署。
573
574| 區塊 | 鍵 | 預設 | 說明 |
575| ---------------- | ---------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
576| `access_control` | `allow_cidrs` / `deny_cidrs` | 空 | 按用戶端位址的入站 IP 允許/拒絕，在 `trusted_proxies` 解析後。`deny_cidrs` 首先檢查；符合它的用戶端即使 `allow_cidrs` 也相符也被拒絕。如果 `allow_cidrs` 非空，閘道是預設拒絕。`/healthz` 和 `/readyz` 豁免於 `allow_cidrs`。 |
577| `limits` | `max_request_bytes` | 32 MiB | 最大入站請求正文；超大小請求在正文被緩衝前獲得 `413`。為大型檔案或影像請求提高。 |
578| `limits` | `max_request_header_bytes` | 未設定 | 設定時，超大小標頭返回 `431` |
579| `limits` | `max_url_length` | 未設定 | 設定時，過長 URL 返回 `414` |
580| `timeouts` | `upstream_ttfb_ms` | 120000 | 等待上游回應標頭（首位元組時間）的最大時間。回應正文然後以無牆鐘上限流。適用於直接 Anthropic 上游路徑；Bedrock、Agent Platform 和 Foundry 受其提供者 SDK 自己的逾時限制。 |
581| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | 未驗證裝置授權端點上的每 IP 速率限制。為在共享出口 IP 或 NAT 後面的大型組織提高。這些限制僅適用於裝置授權登入流程，不適用於 `/v1/messages` 推論。請參閱[使用者程式碼暴力破解抵抗](/zh-TW/claude-apps-gateway-deploy#user-code-brute-force-resistance)。 |
582| `rate_limits` | `device_verify.max` / `.window_seconds` | 10 / 600 | 在 `/device` 上 `user_code` 提交的每 IP 速率限制 |
583
584<h2 id="complete-example">
585 完整範例
586</h2>
587
588此完整參考設定涵蓋每個核心部分；[HTTP 調整區塊](#http-tuning)保持其預設值。複製它，刪除您不需要的內容，並填入您的值。[快速入門](/zh-TW/claude-apps-gateway#quickstart)中的設定是此的最小版本。
589
590```yaml gateway.yaml theme={null}
591# 執行方式：
592# claude gateway --config gateway.yaml
593#
594# 操作日誌詳細程度由 CLAUDE_GATEWAY_LOG_LEVEL
595# 環境變數控制（info | warn | error；預設 info）。它不
596# 影響稽核事件，始終發出。
597
598listen:
599 host: 0.0.0.0
600 port: 8080
601 public_url: https://claude-gateway.internal.example.com
602 # 在 TLS 終止入口後面執行時省略 tls 區塊。
603 # tls:
604 # cert: /certs/gateway.crt
605 # key: /certs/gateway.key
606 # trusted_proxies:
607 # - 10.0.0.0/8
608
609oidc:
610 issuer: https://example.okta.com
611 client_id: 0oa1example2
612 client_secret: ${OIDC_CLIENT_SECRET}
613 allowed_email_domains:
614 - example.com
615 # 當簽發者是 Okta 組織伺服器時需要，其 id_token
616 # 可以省略電子郵件和群組；閘道從 /userinfo 填充它們。
617 userinfo_fallback: true
618 # allowed_groups: [claude-code-users]
619 # Okta 僅在請求 `groups` 範圍且
620 # 應用程式的群組宣告篩選允許它們時發出群組。下面的承包商原則
621 # 符合群組，因此此處請求範圍。
622 scopes: [openid, profile, email, offline_access, groups]
623 # extra_auth_params: { access_type: offline, prompt: consent } # Google
624 # groups_claim: groups # Entra 應用程式角色：使用 `roles`
625 # email_claim: email
626
627session:
628 jwt_secret: ${GATEWAY_JWT_SECRET} # openssl rand -base64 32
629 # ttl_hours: 1
630
631store:
632 postgres_url: ${GATEWAY_POSTGRES_URL}
633 # max_connections: 5
634
635# 啟用 /v1/organizations/spend_limits（鏡像 Anthropic Admin API）
636# 和 /v1/messages 上的每個開發人員支出強制執行。省略以停用。
637# 上限本身透過 admin API 設定，而不是此處。
638# admin:
639# write_keys:
640# - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
641# read_keys:
642# - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
643# admin_groups: [platform-finops]
644# blocked_message: request an increase at https://go.example.com/claude-limits
645# # audit_retention_days: 365
646# # spend_retention_months: 13
647# # identity_retention_days: 90
648# # group_limit_mode: min
649
650# enforcement:
651# fail_closed_on_error: false
652
653upstreams:
654 - provider: anthropic
655 auth:
656 api_key: ${ANTHROPIC_API_KEY}
657
658 # - provider: bedrock
659 # region: us-east-1
660 # auth: {}
661
662 # - provider: vertex
663 # region: us-east5
664 # project_id: example-prod
665 # auth: {}
666
667 # - provider: foundry
668 # resource: example-foundry
669 # auth: { use_azure_ad: true }
670
671auto_include_builtin_models: true
672models:
673 - id: claude-opus-4-8
674 label: Claude Opus 4.8
675 upstream_model:
676 anthropic: claude-opus-4-8
677 # bedrock: us.anthropic.claude-opus-4-8
678 # vertex: claude-opus-4-8
679 # foundry: <your-opus-deployment-name>
680 - id: claude-sonnet-4-6
681 label: Claude Sonnet 4.6
682 upstream_model:
683 anthropic: claude-sonnet-4-6
684 - id: claude-haiku-4-5
685 label: Claude Haiku 4.5
686 upstream_model:
687 anthropic: claude-haiku-4-5
688
689managed:
690 policies:
691 - match: { groups: [contractors] }
692 cli:
693 availableModels: [claude-haiku-4-5]
694 # 將預設選擇器選項限制為 availableModels 而不是
695 # 層級預設，因此承包商不會在預設上獲得 400。
696 enforceAvailableModels: true
697 # allow 自動批准這些工具；它不阻止其餘的。
698 # 新增 deny 規則以限制工具。
699 permissions: { allow: [Read, Grep] }
700 - match: {}
701 cli:
702 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
703 permissions:
704 allow: [Read, Grep, Bash, Edit]
705 deny: ["WebFetch"]
706 env: { HTTP_PROXY: http://proxy.example.com:8080 }
707
708telemetry:
709 forward_to:
710 - url: https://otel.internal.example.com:4318
711 headers:
712 Authorization: Bearer ${OTEL_TOKEN}
713```
714
715<h2 id="client-side-managed-settings">
716 用戶端受管設定
717</h2>
718
719上面的所有內容設定閘道伺服器。將開發人員機器指向它在每個裝置上單獨設定，透過 Claude Code 的[受管設定](/zh-TW/settings#settings-files)。閘道無法自己推送這些鍵，因為它們是告訴用戶端閘道在哪裡的內容。
720
721對於 CLI，在每個 OS `managed-settings.json` 中設定兩個鍵：
722
723```json theme={null}
724{
725 "forceLoginMethod": "gateway",
726 "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com"
727}
728```
729
730將該檔案部署到每個裝置，通常透過您的 MDM 平台。檔案路徑因平台而異：
731
732| 平台 | 路徑 |
733| ----------- | ----------------------------------------------------------------------------------------------------- |
734| macOS | `/Library/Application Support/ClaudeCode/managed-settings.json`，或 `com.anthropic.claudecode` 受管偏好設定網域 |
735| Linux 和 WSL | `/etc/claude-code/managed-settings.json` |
736| Windows | `C:\Program Files\ClaudeCode\managed-settings.json`，或透過 HKLM 登錄的群組原則 |
737
738`forceLoginGatewayUrl` 和 `forceLoginMethod` 的 `"gateway"` 值僅從管理員控制的受管層被尊重。開發人員在自己的 `~/.claude/settings.json` 中設定它們無效。
739
740<h2 id="related">
741 相關
742</h2>
743
744* [Claude 應用程式閘道概述](/zh-TW/claude-apps-gateway)：快速入門和開發人員連接
745* [部署指南](/zh-TW/claude-apps-gateway-deploy)：IdP 設定、容器映像、Kubernetes 和 Cloud Run，以及操作
746* [支出限制](/zh-TW/claude-apps-gateway-spend-limits)：每個開發人員上限和 Admin API
