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# Konfigurasi gateway aplikasi Claude
6
7> Referensi untuk setiap opsi gateway.yaml: listener dan TLS, OIDC, session, Postgres store, Bedrock/Agent Platform/Foundry upstreams, model routing, managed policies, dan telemetry.
8
9Deployment gateway aplikasi Claude dikonfigurasi oleh satu file YAML, secara konvensional `gateway.yaml`. File ini mendefinisikan semua yang dilakukan gateway: di mana ia mendengarkan, bagaimana pengembang masuk, ke mana inference pergi, dan kebijakan serta telemetry mana yang berlaku. Halaman ini adalah referensi untuk setiap opsi dalam file tersebut. Untuk menulis yang pertama, mulai dari [quickstart](/id/claude-apps-gateway#quickstart), yang membangun config minimal yang berfungsi dan menjalankannya; setelah Anda memiliki config yang Anda sukai, [deployment guide](/id/claude-apps-gateway-deploy) mencakup containerizing dan hosting di Kubernetes, Cloud Run, atau platform Anda sendiri.
10
11Gateway membaca file sekali, saat startup, dengan `claude gateway --config /path/to/gateway.yaml`. Setiap opsi divalidasi terhadap schema saat boot, jadi config yang salah format gagal saat start dengan error tingkat field daripada saat penggunaan pertama.
12
13[Complete example](#complete-example) di akhir halaman ini menggunakan setiap bagian.
14
15<h2 id="file-structure">
16 Struktur file
17</h2>
18
19Lima bagian [diperlukan](#required-sections). Setiap bagian lainnya [opsional](#optional-sections), dan bagian yang dihilangkan mengambil default-nya. Kunci yang tidak dikenal gagal boot, jadi typo muncul sebagai error bernama daripada setting yang diabaikan secara diam-diam.
20
21**Bagian yang diperlukan:**
22
23* [`listen`](#listen): bind address, public URL, TLS termination
24* [`oidc`](#oidc): identity provider Anda (IdP), termasuk issuer, client, claim mapping, dan siapa yang boleh masuk
25* [`session`](#session): bearer tokens yang dimint gateway, dengan secret dan lifetime
26* [`store`](#store): PostgreSQL, untuk device grants dan rate-limit counters
27* [`upstreams`](#upstreams): ke mana inference pergi, apakah Anthropic, Bedrock, Agent Platform, atau Foundry
28
29**Bagian opsional:**
30
31* [`admin`](#admin): Admin API auth dan retention untuk spend limits
32* [`enforcement`](#enforcement): perilaku spend-limit fail-open atau fail-closed
33* [`models`](#models) dan `auto_include_builtin_models`: daftar model yang dikurasi admin dan per-upstream IDs
34* [`managed`](#managed): managed settings policies berdasarkan IdP group
35* [`telemetry`](#telemetry): OTLP forwarding ke observability stack Anda
36* [`access_control`, `limits`, `timeouts`, `rate_limits`](#http-tuning): IP allow/deny, request size caps, upstream time-to-first-byte, dan per-IP sign-in limits
37
38<h2 id="secret-expansion">
39 Ekspansi secret
40</h2>
41
42Jangan tulis secrets seperti `client_secret`, `jwt_secret`, atau `postgres_url` langsung di `gateway.yaml`. Referensikan mereka dengan salah satu bentuk di bawah, dan gateway menyelesaikan nilai saat boot dari environment variable atau file:
43
44| Bentuk | Diselesaikan ke | Gunakan untuk |
45| --------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------- |
46| `${VAR}` | Environment variable `VAR`. Boot gagal jika tidak terdefinisi. | Container environment variables, AWS Secrets Manager via env injection |
47| `${file:/path}` | Isi file, dipangkas | Kubernetes Secret volume mounts, Vault Agent, SOPS |
48
49<h2 id="required-sections">
50 Bagian yang diperlukan
51</h2>
52
53<h3 id="listen">
54 `listen`
55</h3>
56
57Blok `listen` mengontrol di mana gateway melayani: bind address dan port, origin yang terlihat secara eksternal, dan optional TLS termination.
58
59| Field | Diperlukan | Deskripsi |
60| ---------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
61| `host` | Tidak | Bind address. Default `0.0.0.0`. |
62| `port` | Tidak | Bind port. Default `8080`. |
63| `public_url` | Di belakang proxy | Origin `https://` yang terlihat secara eksternal, digunakan untuk membangun IdP `redirect_uri` dan discovery metadata. Diperlukan di belakang proxy apa pun yang menghentikan TLS seperti ALB, Ingress, atau Cloud Run, karena gateway tidak mempercayai header `X-Forwarded-*` saat membangun origin-nya sendiri; mereka dapat dipalsukan oleh client. `trusted_proxies` di bawah mengatur resolusi client-IP saja. Juga diperlukan untuk mengaktifkan [telemetry](#telemetry), karena gateway membangun endpoint OTLP yang didorong ke client dari URL ini. |
64| `tls.cert` / `tls.key` | Tidak | Path PEM jika gateway menghentikan TLS sendiri |
65| `trusted_proxies` | Tidak | CIDR atau IP dari load balancer di depan gateway. Ketika diatur, gateway mempercayai `X-Forwarded-For` hanya dari peer ini dan mencatat IP client yang sebenarnya untuk per-IP rate limiting dan audit. Setara dengan nginx `set_real_ip_from`. |
66
67<h3 id="oidc">
68 `oidc`
69</h3>
70
71OpenID Connect (OIDC) adalah protokol SSO yang digunakan gateway dengan identity provider Anda; lihat [Identity provider setup](/id/claude-apps-gateway-deploy#identity-provider-setup) untuk apa yang harus didaftarkan di sisi IdP. Blok `oidc` menghubungkan gateway ke identity provider Anda dan memutuskan siapa yang dapat masuk. Ini menamai issuer dan OAuth client, memetakan claims yang membawa email dan groups, dan membatasi sign-in berdasarkan email domain atau group.
72
73| Field | Diperlukan | Deskripsi |
74| ------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
75| `issuer` | Ya | OIDC discovery base. Harus melayani discovery di `/.well-known/openid-configuration`. Gunakan HTTPS dalam production; gateway menerima issuer `http://`. Issuer loopback seperti `http://localhost:8081` ditolak oleh [SSRF guard](/id/claude-apps-gateway-deploy#threat-model-summary) kecuali `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1` diatur di environment gateway. |
76| `client_id` / `client_secret` | Ya | Dari registrasi OAuth client Anda |
77| `allowed_email_domains` | Tidak | Tolak id\_tokens yang claim `email`-nya tidak ada di salah satu domain ini, case-insensitive. Defense-in-depth terhadap misconfiguration IdP multi-tenant. Independen dari setting ini, id\_token yang claim `email_verified`-nya secara eksplisit `false` selalu ditolak. |
78| `allowed_groups` | Tidak | Batasi sign-in ke anggota IdP groups ini, dicocokkan terhadap `groups_claim`. User dalam email domain yang diizinkan tetapi tidak ada di salah satu groups ini ditolak. Memerlukan IdP untuk memancarkan groups claim. |
79| `groups_claim` | Tidak | Claim id\_token mana yang membawa group membership. Default `groups`. Microsoft Entra memancarkan app roles di bawah `roles`. Menerima flat key atau RFC 6901 JSON Pointer seperti `/resource_access/gateway/roles` untuk nested claims. |
80| `google_groups` | Tidak | Cari groups user yang masuk melalui Google Workspace Admin SDK Directory API, karena id\_token Google tidak membawa groups claim. Atur `service_account_json_path` ke file service-account key dengan domain-wide delegation pada scope `https://www.googleapis.com/auth/admin.directory.group.readonly`, dan `admin_email` ke administrator Workspace yang disamar oleh service account; Directory API memerlukan subject admin yang sebenarnya. Email address group setiap user menjadi groups claim mereka, jadi `allowed_groups` dan `managed.policies.match.groups` cocok pada group emails. |
81| `email_claim` | Tidak | Claim id\_token mana yang membawa email user. Default `email`. Beberapa IdP, seperti ADFS dan Entra B2C, memancarkan `upn` atau `preferred_username` sebagai gantinya. Menerima flat key, JSON Pointer, atau daftar fallback keys di mana key pertama yang ada digunakan. |
82| `scopes` | Tidak | Override lengkap dari scopes OIDC yang diminta gateway. Default `[openid, profile, email, offline_access]`. Atur ketika IdP Anda menolak scopes yang tidak dikenalinya, atau memerlukan custom scope untuk memancarkan groups atau email. Harus menyertakan `openid`. Menghilangkan `offline_access` menonaktifkan refresh tokens, jadi developer menjalankan kembali browser login setiap `session.ttl_hours`. Lihat [Identity provider setup](/id/claude-apps-gateway-deploy#identity-provider-setup) untuk per-IdP scope recipes seperti Google's refresh-token flow. |
83| `extra_auth_params` | Tidak | Extra query parameters ditambahkan ke IdP authorization request, verbatim. Ini adalah mekanisme override untuk perilaku spesifik IdP, seperti `access_type: offline` untuk Google refresh tokens, `domain_hint` untuk beberapa Entra tenants, atau `acr_values` untuk step-up flows. Tidak dapat override protocol params yang dikelola gateway: `state`, `nonce`, `redirect_uri`, PKCE, `scope`, `response_type`, `response_mode`, dan `client_id`. |
84| `userinfo_fallback` | Tidak | Ketika id\_token menghilangkan email atau groups, ambil dari `/userinfo`. Diperlukan untuk Keycloak lightweight access tokens, Okta org server, dan ADFS minimal tokens. Id\_token tetap authoritative; userinfo hanya mengisi gaps. Default `false`. |
85| `use_pkce` | Tidak | Kirim PKCE (S256) challenge pada authorization request. Default `true`. Atur `false` hanya jika IdP Anda menolak PKCE untuk confidential client ini. |
86| `clock_skew_seconds` | Tidak | Toleransi clock drift saat memvalidasi id\_token time claims. Default `0`, yang ketat. Naikkan jika Anda melihat error "token expired / not yet valid" tepat setelah sign-in karena host/IdP clock skew. |
87| `token_endpoint_auth_method` | Tidak | Override token-endpoint auth method. Menerima `client_secret_basic` atau `client_secret_post`. Auto-negotiated secara default. |
88| `id_token_signed_response_alg` | Tidak | Expected id\_token signing algorithm. Default `RS256`. Atur untuk IdP yang menandatangani dengan ES256, PS256, atau EdDSA. |
89| `additional_authorized_parties` | Tidak | Extra `azp` values untuk diterima di luar `client_id`, untuk Keycloak broker dan token-exchange flows |
90| `discovery_url` | Tidak | Ambil discovery document dari URL ini daripada menurunkannya dari `issuer`, untuk IdP di belakang proxy yang menulis ulang issuer host. Path harus berisi `/.well-known/`. |
91| `form_action_origins` | Tidak | Origins tambahan untuk direktif `Content-Security-Policy: form-action` halaman `/device`. Gateway sudah mengizinkan `'self'` dan origin `authorization_endpoint` yang ditemukan, tetapi Chrome memberlakukan `form-action` terhadap seluruh redirect chain. Jika IdP Anda mengalihkan melalui host kedua, seperti Azure AD federated ke ADFS, hub-spoke Okta, atau SSO interceptor korporat, daftar setiap origin yang mungkin dialihkan oleh authorization request. |
92| `ca_cert_pem` | Tidak | PEM CA cert yang menggantikan system trust store untuk IdP requests saja. Gunakan untuk Keycloak atau Dex di belakang corporate PKI. |
93
94<h3 id="session">
95 `session`
96</h3>
97
98Blok `session` membentuk bearer tokens yang dimint gateway setelah sign-in: secret yang menandatanganinya dan berapa lama mereka hidup.
99
100| Field | Diperlukan | Deskripsi |
101| ------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
102| `jwt_secret` | Ya | Minimal 32 bytes entropy, misalnya dari `openssl rand -base64 32`. Menandatangani gateway's HS256 bearer tokens. Menerima single string atau array untuk rotation: index 0 menandatangani dan semua entries memverifikasi. Untuk rotate, prepend secret baru, tunggu `ttl_hours`, kemudian drop yang lama. |
103| `ttl_hours` | Tidak | Gateway bearer token lifetime. Default `1`. CLI secara diam-diam refresh sebelum expiry ketika IdP mengeluarkan refresh tokens. Lifetime yang lebih pendek menghapus provisioning lebih cepat; yang lebih panjang membuat lebih sedikit IdP round-trips. Jika IdP Anda tidak dapat mengeluarkan refresh tokens karena `offline_access` tidak tersedia, tidak ada silent refresh, jadi naikkan ini ke `8` atau `12` untuk menghindari mengirim developer kembali ke browser login setiap jam. |
104
105<h3 id="store">
106 `store`
107</h3>
108
109Blok `store` menunjukkan gateway ke database PostgreSQL-nya, yang menyimpan device grants dan rate-limit counters.
110
111| Field | Diperlukan | Deskripsi |
112| ----------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
113| `postgres_url` | Ya | `postgres://` atau `postgresql://` URL. Diperlukan: device-grant rendezvous, di mana browser callback menulis dan polling CLI membaca, memerlukan cross-replica state. Gateway menjalankan schema migrations-nya sendiri saat boot, jadi role memerlukan `CREATE TABLE` pada target schema. Jika kebijakan keamanan Anda melarang DDL dari application role, jalankan migrations dengan admin role, awalnya dan lagi setiap kali release baru mengirim migrations, dan berikan app role `SELECT, INSERT, UPDATE, DELETE` pada gateway's tables. Lihat [Upgrades](/id/claude-apps-gateway-deploy#upgrades) dan [Postgres](/id/claude-apps-gateway-deploy#postgres). |
114| `username` | Tidak | Overrides user di `postgres_url` |
115| `password` | Tidak | Database credential. Atur di sini daripada di `postgres_url` jadi credential tetap keluar dari URL. Menerima karakter apa pun dan mengambil precedence atas URL credentials. |
116| `max_connections` | Tidak | Postgres connection-pool size per replica. Default `5`, yang konservatif dan ramah ke shared databases. Dengan [spend limits](#admin) diaktifkan, hot path melakukan beberapa operasi per inference request, jadi naikkan untuk dedicated database di bawah load, dan simpan replicas × ini di bawah database's `max_connections`. |
117
118Untuk local development, arahkan `postgres_url` ke throwaway Postgres container, misalnya `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` adalah ordered list. Gateway meneruskan inference ke upstream pertama yang menyelesaikan model yang diminta. Pada `5xx`, `429`, atau timeout ia failover ke next; `4xx` lainnya tidak, karena error tersebut dapat diatribusikan ke request daripada upstream. Multiple upstreams dari provider yang sama harus menetapkan distinct `name:`.
125
126Bedrock, Agent Platform, dan Foundry clients dibangun sekali saat startup, dan SDK mereka refresh credentials secara internal, jadi rotating cloud credentials tidak memerlukan restart. Static Anthropic API keys dan bearers dibaca saat startup; lihat [Anthropic API](#anthropic-api).
127
128<h4 id="anthropic-api">
129 Anthropic API
130</h4>
131
132Minimal Anthropic upstream adalah API key dari [Claude Console](https://platform.claude.com):
133
134```yaml theme={null}
135upstreams:
136 - provider: anthropic
137 auth:
138 api_key: ${ANTHROPIC_API_KEY}
139 # OR an OAuth bearer (e.g. a Workload-Identity-Federation-exchanged token):
140 # oauth_token: ${file:/var/run/secrets/anthropic-oauth-token}
141 # base_url: https://api.anthropic.com # default; override for a forward proxy
142```
143
144Dua bentuk credential berbeda dalam header yang mereka kirim:
145
146* **`api_key`**: mengirim `x-api-key`. Rotate di Claude Console dan update env var.
147* **`oauth_token`**: mengirim `Authorization: Bearer`. Gunakan bentuk bearer ketika org Anda mengeluarkan short-lived tokens daripada long-lived API keys. Bearer dibaca sekali saat startup, jadi refresh dengan remount secret dan restart.
148
149Daripada static key atau bearer, Anda dapat menggunakan Workload Identity Federation. Buat federation rule dengan mengikuti [Workload Identity Federation guide](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation), kemudian mount workload's OIDC JWT Anda sebagai file, seperti Kubernetes projected service-account token atau CI platform's id-token. Gateway menukar JWT untuk short-lived bearer dan refresh secara otomatis. Token file dibaca ulang pada setiap exchange, jadi rotated projected tokens diambil tanpa restart.
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_... # required if the rule covers >1 workspace
159 # service_account_id: svac_... # optional expected-target check
160```
161
162<h4 id="amazon-bedrock">
163 Amazon Bedrock
164</h4>
165
166Untuk client-side Bedrock deployment yang digantikan atau di-front oleh gateway, lihat [Claude Code on Amazon Bedrock](/id/amazon-bedrock). Gateway-side upstream:
167
168```yaml theme={null}
169upstreams:
170 - provider: bedrock
171 region: us-east-1
172 auth: {} # preferred: AWS default credential chain
173 # OR explicit credentials:
174 # auth:
175 # aws_access_key_id: ${AWS_AKID}
176 # aws_secret_access_key: ${AWS_SK}
177 # aws_session_token: ${AWS_ST}
178 # OR a Bedrock API bearer token:
179 # auth:
180 # aws_bearer_token: ${AWS_BEARER_TOKEN}
181 # Override the bedrock-runtime endpoint for FIPS or VPC-endpoint deployments:
182 # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com
183```
184
185Empty `auth` block menggunakan AWS SDK's default credential chain: env vars, `~/.aws/credentials`, ECS task role, EC2 instance metadata, atau IRSA pada EKS. Dalam production, berikan gateway pod IAM role daripada embedding static keys dalam container image.
186
187| Setup | Bagaimana |
188| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
189| IAM permissions | Berikan gateway's principal `bedrock:InvokeModel` dan `bedrock:InvokeModelWithResponseStream` pada inference-profile ARNs dan underlying foundation-model ARNs. Untuk built-in catalog di US regions: `arn:aws:bedrock:<region>:<account>:inference-profile/us.anthropic.*` dan `arn:aws:bedrock:*::foundation-model/anthropic.*`. |
190| Model access | Di Bedrock console, per region, request dan enable model access untuk Claude models yang Anda inginkan. Cross-region inference profiles (`us.anthropic.*`) memerlukan model access di setiap region yang dicakup profile. |
191| EKS (IRSA) | Buat IAM role dengan policy di atas dan trust policy untuk cluster's OIDC provider yang scoped ke gateway's service account. Annotate service account dengan `eks.amazonaws.com/role-arn: arn:aws:iam::<acct>:role/claude-gateway`. `auth: {}` mengambilnya. |
192| ECS / EC2 | Attach IAM role ke task definition atau instance profile. `auth: {}` mengambilnya. |
193| Tempat lain | Lewatkan credentials via `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, dan `AWS_SESSION_TOKEN` env vars, atau atur secara eksplisit di `auth:` dengan `${VAR}` expansion |
194| Region | `region:` adalah API endpoint region. Cross-region inference profiles route across geo (US, EU, APAC) terlepas dari mana Anda memilih. Untuk non-US regions atau provisioned-throughput ARNs, tambahkan [`models:`](#models) block dengan per-upstream IDs yang benar. |
195
196<h4 id="google-cloud-agent-platform">
197 Google Cloud Agent Platform
198</h4>
199
200Untuk equivalent client-side setup, lihat [Claude Code on Google Cloud](/id/google-vertex-ai). Gateway-side upstream:
201
202```yaml theme={null}
203upstreams:
204 - provider: vertex
205 region: us-east5
206 project_id: example-prod
207 auth: {} # preferred: Application Default Credentials
208 # OR a service account key file:
209 # auth: { service_account_json: /secrets/sa.json }
210 # Override the aiplatform endpoint for Private Service Connect:
211 # base_url: https://us-east5-aiplatform.p.googleapis.com
212```
213
214Empty `auth` block menggunakan Application Default Credentials: `GOOGLE_APPLICATION_CREDENTIALS`, GCE metadata, atau GKE Workload Identity. Service-account JSON key files didukung tetapi tidak disarankan; gunakan Workload Identity atau attach service account ke GCE atau Cloud Run instance.
215
216Atur `region: global` untuk menggunakan [Agent Platform's global endpoint](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations) daripada regional. Google kemudian route setiap request ke available region, jadi Anda tidak track per-region model availability. Menetapkan region spesifik pin setiap request ke sana.
217
218| Setup | Bagaimana |
219| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
220| IAM permissions | Berikan gateway's service account `roles/aiplatform.user` pada project, atau custom role dengan `aiplatform.endpoints.predict`. Enable Agent Platform API (`aiplatform.googleapis.com`). |
221| Model access | Di Model Garden, enable Claude models untuk project Anda. Mereka publish ke specific regions; check model card untuk supported regions. |
222| GKE (Workload Identity) | Bind GCP service account ke gateway's Kubernetes service account dan annotate KSA dengan `iam.gke.io/gcp-service-account: claude-gateway@<proj>.iam.gserviceaccount.com`. `auth: {}` mengambilnya. |
223| Cloud Run / GCE | Atur service's service account ke satu dengan `roles/aiplatform.user`. `auth: {}` mengambilnya. |
224| Tempat lain | `auth: { service_account_json: /secrets/sa.json }`, path ke JSON key file yang di-mount sebagai secret. Field mengambil file path, bukan key contents, jadi tidak ada `${file:…}` expansion yang terlibat. |
225
226<h4 id="microsoft-foundry">
227 Microsoft Foundry
228</h4>
229
230Untuk client-side Foundry deployment, lihat [Claude Code on Microsoft Foundry](/id/microsoft-foundry). Gateway-side upstream:
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 } # preferred: DefaultAzureCredential / Managed Identity
237 # OR an API key:
238 # auth:
239 # api_key: ${FOUNDRY_API_KEY}
240```
241
242`use_azure_ad: true` resolves melalui `DefaultAzureCredential`: Managed Identity pada AKS, ACI, atau App Service; Azure CLI; atau environment credentials. API keys bekerja tetapi project-wide dan tidak rotate secara otomatis. Foundry's endpoint diturunkan dari `resource:`; atur optional `base_url` untuk override untuk sovereign clouds seperti Azure Government.
243
244| Setup | Bagaimana |
245| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
246| RBAC | Berikan gateway's identity `Azure AI User` atau `Cognitive Services User` pada Foundry resource |
247| Deployments | Foundry menggunakan admin-chosen deployment names, bukan canonical model IDs. Tambahkan [`models:`](#models) block memetakan setiap canonical ID ke deployment name Anda. |
248| AKS (workload identity) | Federate User-Assigned Managed Identity dengan cluster's OIDC issuer dan bind ke gateway's service account. `use_azure_ad: true` mengambilnya via `WorkloadIdentityCredential`. |
249| ACI / App Service | Enable system-assigned atau user-assigned managed identity pada resource. `use_azure_ad: true` mengambilnya. |
250| Tempat lain | `auth: { api_key: "${FOUNDRY_API_KEY}" }`. Quote `${…}` di dalam `{ }`. |
251
252<h4 id="multiple-upstreams">
253 Multiple upstreams
254</h4>
255
256Provider yang sama dapat muncul lebih dari sekali dengan distinct `name:`. Ini mencakup different regions, different accounts via different credential chains, provisioned throughput versus on-demand, dan cross-provider fallback.
257
258Gateway mencoba upstreams secara berurutan. `5xx`, `429`, timeouts, dan missing-endpoint (`501`) failover; `4xx` lainnya tidak. `429` adalah per-upstream capacity, jadi provisioned-throughput (PT) exhaustion failover ke on-demand. Upstream yang tidak dapat menyelesaikan model yang diminta dilewati tanpa network round-trip.
259
260Contoh ini route provisioned-throughput Bedrock allotment pertama, overflow ke on-demand dan second account, dan fallback ke Anthropic API terakhir:
261
262```yaml theme={null}
263upstreams:
264 # Primary: provisioned throughput in your home region.
265 - name: bedrock-pt
266 provider: bedrock
267 region: us-east-1
268 auth: {}
269 # Overflow: on-demand cross-region.
270 - name: bedrock-od
271 provider: bedrock
272 region: us-west-2
273 auth: {}
274 # Different account: a separate Bedrock allotment via assumed-role creds.
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 # Last resort: direct Anthropic API.
282 - name: anthropic-fallback
283 provider: anthropic
284 auth:
285 api_key: ${ANTHROPIC_API_KEY}
286
287# Per-upstream model IDs are keyed on the upstream's `name:`; an upstream
288# without a `name:` defaults to its provider string (e.g. `bedrock`). Any
289# upstream not listed for a model is skipped, which is how you route a model
290# to provisioned throughput while everything else stays on-demand.
291models:
292 - id: claude-opus-4-8
293 label: Claude Opus 4.8
294 upstream_model:
295 bedrock-pt: arn:aws:bedrock:us-east-1:111111111111:provisioned-model/abcdef
296 bedrock-od: us.anthropic.claude-opus-4-8
297 bedrock-acct2: us.anthropic.claude-opus-4-8
298 anthropic-fallback: claude-opus-4-8
299```
300
301| Lever | Bagaimana |
302| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
303| Different regions | Satu Bedrock upstream per region, masing-masing dengan `region:` sendiri. Dengan [`auto_include_builtin_models: true`](#models) cross-region inference profiles route secara otomatis; untuk region-pinned deployments gunakan `models:` block. |
304| Different accounts | Satu Bedrock upstream per account, masing-masing dengan credentials sendiri di `auth:`. Default chain (`auth: {}`) menggunakan pod's identity; untuk second account, atur explicit credentials atau bearer token. |
305| Provisioned throughput | Map model ke provisioned-throughput ARN di `models:` untuk upstream's name itu. Upstreams lainnya simpan on-demand ID, jadi PT capacity exhausted sebelum failover. |
306| VPC / FIPS endpoints | Atur `base_url:` pada upstream ke VPC endpoint atau FIPS endpoint URL Anda |
307| Model-scoped routing | Omit upstream dari model's `upstream_model:` map dan upstream itu dilewati untuk model itu. Misalnya, route Opus ke provisioned throughput dan Sonnet dan Haiku ke on-demand. |
308
309Failover antara cloud providers, atau ke direct Anthropic API, mengubah agreement, geography, dan terms lainnya yang mengatur request.
310
311CLI menerapkan feature gating yang sama ke gateways terlepas dari upstream mana yang melayani request tertentu, jadi failover tidak mengirim body field yang upstream akan tolak.
312
313<h2 id="optional-sections">
314 Bagian opsional
315</h2>
316
317<h3 id="admin">
318 `admin`
319</h3>
320
321Opsional. Mengaktifkan `/v1/organizations/spend_limits`, yang mencerminkan Anthropic's public Admin API, dan per-developer spend enforcement pada `/v1/messages`. Lihat [Spend limits](/id/claude-apps-gateway-spend-limits) untuk bagaimana caps ditetapkan dan ditegakkan; bagian ini mencakup `gateway.yaml` keys yang mengaktifkan fitur dan menyetelnya.
322
323```yaml theme={null}
324admin:
325 # Named static API keys for the admin endpoints, sent as x-api-key.
326 # The id appears in the audit log as admin-key:<id> so each key is
327 # attributable. Array for rotation: add the new key, roll clients,
328 # remove the old.
329 write_keys:
330 - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
331 - { id: ci, key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }
332 read_keys:
333 - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
334 # IdP groups granted full admin via the normal gateway JWT (no API key).
335 admin_groups: [platform-finops]
336 blocked_message: request an increase at https://go.example.com/claude-limits
337```
338
339| Field | Diperlukan | Deskripsi |
340| ------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
341| `write_keys` | Tidak | Array dari `{id, key}`. `x-api-key` yang cocok dengan salah satu ini dapat list, set, dan delete spend limits. Nilai key harus minimal 32 karakter; `id`s harus unik di seluruh `read_keys` dan `write_keys`. |
342| `read_keys` | Tidak | Array dari `{id, key}`. Read-only: setiap endpoint `GET`, termasuk listing caps, mengambil satu berdasarkan ID, dan membaca [`/effective`](/id/claude-apps-gateway-spend-limits#%2Feffective) dan [`/audit`](/id/claude-apps-gateway-spend-limits#%2Faudit). |
343| `admin_groups` | Tidak | Nama grup IdP. JWT gateway yang klaim `groups`-nya mencakup salah satu ini memiliki akses admin penuh, read dan write, dan audit sebagai `oidc:<sub>`. Gunakan ini untuk admin manusia; gunakan API keys untuk mesin. |
344| `blocked_message` | Tidak | Ditambahkan verbatim ke `429 billing_error` yang dilihat developer yang diblokir. Tulis seluruh instruksi, seperti URL atau saluran Slack. Jika tidak diatur, error adalah `spend limit reached`. |
345| `audit_retention_days` | Tidak | Default `365`. Baris `admin_audit` yang lebih lama disapu. |
346| `spend_retention_months` | Tidak | Default `13`. Baris counter `spend` yang lebih tua dari ini disapu. Default menyimpan tahun penuh ditambah bulan parsial saat ini untuk pelaporan year-over-year. |
347| `identity_retention_days` | Tidak | Default `90`. Last-seen TTL untuk baris `principal_emails`, yang menyimpan email, nama tampilan, dan grup setiap developer (PII). Sengaja lebih pendek dari spend retention sehingga identitas yang dihapus provisioning-nya berusia keluar sementara counter spend anonimnya tetap ada. |
348| `group_limit_mode` | Tidak | `min` (default) atau `max`. Ketika developer ada di beberapa grup dengan caps, `min` memberlakukan yang paling ketat dan `max` yang paling longgar. Digunakan oleh enforcement dan `/effective`. |
349
350<h3 id="enforcement">
351 `enforcement`
352</h3>
353
354Blok `enforcement` mengontrol bagaimana pemeriksaan spend-limit berperilaku ketika store tidak tersedia.
355
356| Field | Diperlukan | Deskripsi |
357| ---------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
358| `fail_closed_on_error` | Tidak | Default `false`. Enforcement spend gagal terbuka pada pemadaman Postgres, jadi inference tetap aktif. Atur `true` untuk gagal tertutup: developer yang over-cap diblokir, tetapi begitu juga semua orang jika store tidak dapat dijangkau. Tidak ada efek tanpa blok [`admin:`](#admin). |
359
360<h3 id="models">
361 `models`
362</h3>
363
364Blok `models` adalah daftar model yang dikurasi admin opsional, disajikan di `/v1/models` dan digunakan untuk menerjemahkan ID model per upstream. Ini diperlukan untuk wilayah Bedrock non-AS, ARN throughput provisioned Bedrock, dan nama deployment Foundry.
365
366```yaml theme={null}
367auto_include_builtin_models: true # false: expose only the list below
368models:
369 - id: claude-opus-4-8
370 label: Claude Opus 4.8
371 # description: optional text shown in clients that surface it
372 upstream_model:
373 anthropic: claude-opus-4-8
374 bedrock: us.anthropic.claude-opus-4-8 # or an inference-profile ARN
375 foundry: your-opus-deployment-name
376```
377
378<h3 id="managed">
379 `managed`
380</h3>
381
382Blok `managed` mendefinisikan kebijakan akses berbasis peran yang dikunci pada grup IdP atau domain email. Kebijakan dievaluasi secara berurutan; kecocokan pertama dipilih, kemudian digabungkan ke basis catch-all `match: {}` yang dijelaskan di bawah. Mereka disajikan per-user di `GET /managed/settings` dengan caching ETag/304.
383
384```yaml theme={null}
385managed:
386 policies:
387 # Specific groups first.
388 - match: { groups: [eng-contractors] }
389 cli:
390 availableModels: [claude-sonnet-4-6]
391 permissions: { deny: ["WebFetch", "WebSearch"] }
392 # Default catch-all last: matches everyone who authenticated.
393 - match: {}
394 cli:
395 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
396```
397
398Catch-all `match: {}`, secara konvensional terdaftar terakhir, diperlakukan sebagai lapisan dasar. Setiap kebijakan lainnya mewarisi kunci apa pun yang tidak ditetapkan dari catch-all, jadi entri per-peran hanya perlu mencantumkan apa yang berbeda dari default org. Aturan penggabungan tergantung pada jenis kunci:
399
400* **Allow-lists**: `availableModels` dan `permissions.allow`. Daftar kebijakan spesifik sepenuhnya menggantikan daftar dasar.
401* **Deny-lists dan hook arrays**: `permissions.deny`, `permissions.ask`, `disabledMcpjsonServers`, `deniedMcpServers`, `blockedMarketplaces`, dan setiap array jenis event `hooks`. Ini mengambil union dari dasar dan kebijakan, jadi deny org-wide atau audit hook tidak dapat secara tidak sengaja dijatuhkan oleh override per-peran.
402* **Record-typed keys**: `env`, `modelOverrides`, dan `skillOverrides`. Ini shallow-merge, jadi blok `env` per-peran menimpa kunci yang ditetapkan dan mewarisi sisanya dari dasar.
403
404`availableModels` juga ditegakkan server-side di `/v1/messages`, jadi model yang ditolak mengembalikan `400` terlepas dari apa yang dikirim klien.
405
406| Matcher | Perilaku |
407| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
408| `match: {}` | Cocok dengan setiap pengguna yang terautentikasi. Mulai dengan satu ini dan tambahkan kebijakan yang dibatasi grup di atasnya nanti. |
409| `match: { groups: [a, b] }` | Cocok jika klaim `groups` JWT berisi salah satu grup yang terdaftar. Case-sensitive: grup harus cocok dengan casing yang tepat dari IdP. |
410| `match: { email_domain: example.com }` | Cocok dengan bagian setelah `@` terakhir dalam klaim `email` JWT, case-insensitive. Menerima satu domain per kebijakan. |
411| `match: { groups: [a], email_domain: example.com }` | Kedua kondisi harus cocok |
412
413Pengguna yang terautentikasi yang tidak cocok dengan kebijakan apa pun mendapat default gateway, yang berarti setiap model dalam katalog dan tidak ada pengaturan terkelola. Tambahkan catch-all `match: {}` terakhir jika Anda menginginkan kebijakan default yang dijamin.
414
415<Note>
416 Gateway tidak menyimpan direktori pengguna sendiri. Ini mengotorisasi setiap permintaan dari token IdP pengguna, membaca keanggotaan grup dari klaim `groups` token dan mengevaluasi kebijakan terhadapnya. Tidak ada roster untuk dihitung dan tidak ada akun untuk dibuat sebelumnya, dan oleh karena itu tidak ada endpoint SCIM, karena tidak ada apa pun untuk SCIM sinkronkan ke.
417
418 Jalankan manajemen siklus hidup pengguna dan grup di sumber kebenaran, yang merupakan penyediaan SCIM asli IdP atau platform tata kelola identitas khusus. Keanggotaan dan deprovisioning yang diatur di sana mengalir ke gateway secara otomatis melalui token. Jika Anda menginginkan penyediaan SCIM dari akun Claude itu sendiri, itu adalah kemampuan [Claude for Enterprise](/id/admin-setup).
419
420 Dua jam propagasi berlaku:
421
422 * **Konten kebijakan**: mengedit kebijakan dan redeploy mencapai klien yang terhubung pada polling managed-settings berikutnya mereka, dalam satu jam
423 * **Keanggotaan grup**: mengubah keanggotaan grup pengguna mengubah kebijakan mana yang cocok dengan mereka. Ini berlaku pada re-mint sesi berikutnya, berarti refresh senyap berikutnya, dibatasi oleh `session.ttl_hours`.
424</Note>
425
426<h4 id="what-goes-in-cli">
427 Apa yang masuk di `cli`
428</h4>
429
430Setiap nilai `cli` adalah dokumen `managed-settings.json` Claude Code yang lengkap, skema yang sama yang akan Anda deploy melalui MDM atau `/etc/claude-code/managed-settings.json`, diekspresikan di sini sebagai YAML. CLI menerapkan dokumen yang dikirimkan pada tingkat terkelola, di atas pengaturan pengguna dan proyek.
431
432Gateway memvalidasi setiap dokumen terhadap skema pengaturan CLI saat boot, jadi kunci tingkat atas yang tidak dikenali atau kunci yang dikenali dengan nilai yang salah bentuk gagal boot dengan error yang menamai setiap kunci yang bermasalah. Bagian skema yang sengaja terbuka masih menerima nilai arbitrer, karena klien yang lebih baru mungkin mengenali entri yang skema gateway tidak. Kunci terbuka ini adalah `env`, `pluginConfigs`, dan kunci yang bersarang di bawah `permissions`.
433
434Karena validasi menggunakan skema yang disertakan dengan versi gateway yang terinstal, menempatkan kunci pengaturan tingkat atas yang diperkenalkan oleh rilis Claude Code yang lebih baru ke konfigurasi terkelola memerlukan upgrade gateway terlebih dahulu. Smoke-test kebijakan baru pada satu klien sebelum meluncurkannya.
435
436Referensi kunci lengkap ada di [Claude Code settings](/id/settings#available-settings). Kunci yang paling sering dicari operator:
437
438```yaml theme={null}
439managed:
440 policies:
441 - match: {}
442 cli:
443 # Model access (also enforced server-side at /v1/messages)
444 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
445
446 # Permission policy
447 permissions:
448 deny:
449 - "WebFetch"
450 - "Read(./.env)"
451 - "Read(./secrets/**)"
452 disableBypassPermissionsMode: disable # blocks --dangerously-skip-permissions
453 allowManagedPermissionRulesOnly: true # ignore user/project permission rules
454
455 # Environment pushed into the CLI process. DISABLE_UPDATES blocks
456 # background and manual updates; DISABLE_AUTOUPDATER stops only
457 # background updates.
458 env:
459 DISABLE_UPDATES: "1" # pin versions via your own distribution
460
461 # Org-wide hooks. Hook commands run on developer machines, not the
462 # gateway, so the path must exist on every client OS in the policy.
463 hooks:
464 PostToolUse:
465 - matcher: "Edit|Write"
466 hooks:
467 - { type: command, command: /usr/local/bin/audit-edit.sh }
468```
469
470| Key | Ditegakkan oleh | Efek |
471| ------------------------------------------ | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
472| `availableModels` | Gateway + CLI | Allowlist model. Juga diperiksa di `/v1/messages`, jadi klien yang dipatch tidak dapat membypassnya. |
473| `permissions.allow` / `.deny` | CLI | Aturan tool dan command. Lihat [Permissions](/id/permissions). |
474| `permissions.disableBypassPermissionsMode` | CLI | Atur ke `disable` untuk memblokir [`bypassPermissions`](/id/permission-modes#skip-all-checks-with-bypasspermissions-mode), mode yang auto-approves setiap tool call, dan flag `--dangerously-skip-permissions` |
475| `allowManagedPermissionRulesOnly` | CLI | Ketika `true`, aturan permission pengguna dan proyek diabaikan; hanya aturan dari dokumen ini yang berlaku |
476| `env` | CLI | Variabel lingkungan yang digabungkan ke proses CLI. Gunakan untuk telemetry, auto-update, dan model-name overrides. |
477| `hooks` | CLI | Org-wide [hooks](/id/hooks) |
478
479Karena pengaturan ini tiba melalui jaringan, CLI menunjukkan setiap developer dialog persetujuan keamanan satu kali sebelum menerapkan apa pun yang dapat menjalankan perintah shell atau mengubah ke mana traffic pergi. Dialog mencakup:
480
481* `hooks`
482* Variabel `env` yang tidak ada di daftar aman bawaan CLI
483* pengaturan eksekusi shell seperti `apiKeyHelper` dan `statusLine`
484* konten CLAUDE.md yang terkelola
485
486Daftar aman menentukan variabel `env` mana yang berlaku tanpa persetujuan:
487
488* **Pada daftar aman**: auto-update dan model-name vars
489* **Tidak pada daftar aman**: proxy vars, base-URL vars, dan `OTEL_EXPORTER_OTLP_ENDPOINT`
490
491Konfigurasi [telemetry](#telemetry) gateway mendorong `OTEL_EXPORTER_OTLP_ENDPOINT`, jadi pengaturan `telemetry.forward_to` memicu dialog pada setiap klien interaktif. Run non-interaktif dengan flag `-p` melewati dialog dan menerapkan pengaturan tanpa persetujuan. Dialog melindungi mesin developer dari gateway yang dikompromikan atau bermusuhan, bukan organisasi dari developer, jadi skip `-p` adalah disengaja daripada celah.
492
493Jika developer menolak, Claude Code keluar daripada menerapkan kebijakan. Mendorong hook baru atau variabel env non-aman ke kebijakan yang luas oleh karena itu berarti prompt persetujuan pada startup berikutnya setiap developer yang cocok.
494
495Kunci `cli` dinamai `settings` dalam rilis sebelumnya. Ejaan itu masih diterima sebagai alias, tetapi deployment baru harus menggunakan `cli`.
496
497<h4 id="precedence-with-other-managed-sources">
498 Precedence dengan sumber terkelola lainnya
499</h4>
500
501Jika perangkat juga memiliki `managed-settings.json` lokal atau kebijakan yang dikirimkan MDM, sumber terkelola tidak bergabung. Sumber prioritas tertinggi menyediakan semua pengaturan kebijakan, diurutkan dalam urutan ini dengan prioritas tertinggi terlebih dahulu:
502
5031. [Policy helper](/id/settings#compute-managed-settings-with-a-policy-helper)
5042. Pengaturan yang dikirimkan gateway
5053. MDM, melalui registri HKLM di Windows atau plist di macOS
5064. File `managed-settings.json`
5075. Registri HKCU, hanya di Windows
508
509Host embedding dapat menyediakan kebijakan melalui opsi SDK `managedSettings`. Ini diabaikan secara default dan berlaku hanya ketika sumber terkelola opt in dengan [`parentSettingsBehavior: "merge"`](/id/settings#available-settings), disaring sehingga dapat mengencangkan kebijakan tetapi tidak melonggarkannya.
510
511Satu-satunya pengecualian adalah kunci berikut, yang dihormati ketika sumber admin apa pun di atas tingkat HKCU yang dapat ditulis pengguna menetapkannya, terlepas dari sumber mana yang menyediakan sisa kebijakan:
512
513* `sandbox.network.allowManagedDomainsOnly` dan `sandbox.filesystem.allowManagedReadPathsOnly`: ketika terkunci, allowlist yang sesuai adalah union di seluruh sumber
514* [`allowAllClaudeAiMcps`](/id/settings#available-settings): override allow-only untuk allowlist server MCP claude.ai
515* `sandbox.bwrapPath` dan `sandbox.socatPath`: jalur filesystem ke binary helper [sandbox](/id/sandboxing)
516
517Setiap kunci lainnya, termasuk `allowManagedPermissionRulesOnly` dan `disableBypassPermissionsMode`, berasal dari sumber prioritas tertinggi saja. Lihat [Settings precedence](/id/settings#settings-precedence) untuk aturan yang sama di halaman pengaturan.
518
519Kebijakan gateway berlaku untuk setiap invokasi Claude Code pada mesin, termasuk run non-interaktif `claude -p` dan sesi yang dihasilkan oleh Agent SDK. Jika gateway tidak dapat dijangkau saat startup, sesi yang masuk keluar dengan error daripada menjalankan tanpa kebijakan mereka.
520
521<Warning>
522 `mcpServers` di dalam blok `cli` kebijakan ditolak saat boot gateway. Distribusi MCP per-grup tidak tersedia; deploy server MCP melalui `managed-mcp.json` berbasis file pada setiap perangkat atau biarkan developer menambahkannya secara lokal.
523</Warning>
524
525<h3 id="telemetry">
526 `telemetry`
527</h3>
528
529CLI mengirim metrik, log, dan, ketika diaktifkan, trace OpenTelemetry Protocol (OTLP) melalui HTTP ke gateway, yang meneruskan mereka verbatim ke setiap tujuan yang dikonfigurasi. Lihat [Monitoring usage](/id/monitoring-usage) untuk metrik dan event yang CLI emit.
530
531CLI memberi stempel setiap export dengan identitas pengguna yang terautentikasi, dibaca dari JWT yang diterbitkan gateway: atribut `user.id`, `user.email`, dan `user.groups`. Atribusi biaya dan penggunaan per-developer oleh karena itu bekerja tanpa konfigurasi sisi developer.
532
533```yaml theme={null}
534telemetry:
535 forward_to:
536 - url: https://otel-collector.internal.example.com
537 headers:
538 Authorization: ${OTLP_TOKEN}
539 # Per-signal opt-in. Default: metrics only.
540 metrics: true
541 logs: false
542 traces: false
543 - url: https://api.datadoghq.com/api/v2/otlp
544 headers:
545 DD-API-KEY: ${DD_API_KEY}
546```
547
548<Warning>
549 Setiap tujuan opt into `metrics`, `logs`, dan `traces` secara independen, dan default adalah metrics saja. Signal berbeda dalam sensitivitas:
550
551 * **Metrics**: counter agregat seperti token counts, request counts, dan latency
552 * **Logs dan traces**: dapat membawa perintah bash lengkap, tool inputs, dan jalur file, mencakup apa pun yang Claude Code lakukan pada mesin developer
553
554 Aktifkan logs dan traces hanya pada tujuan dengan kontrol akses dan kebijakan retensi yang data jamin.
555</Warning>
556
557Telemetry off dalam CLI secara default. Mengonfigurasi `telemetry.forward_to` bersama dengan `listen.public_url` mengaktifkannya. Gateway mendorong lima variabel env ke setiap klien yang terhubung melalui `/managed/settings`:
558
559* `CLAUDE_CODE_ENABLE_TELEMETRY=1`
560* `OTEL_METRICS_EXPORTER=otlp`
561* `OTEL_LOGS_EXPORTER=otlp`
562* `OTEL_TRACES_EXPORTER=otlp`
563* `OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>`
564
565Endpoint yang didorong dibangun dari URL publik, jadi metrik dan log tidak memerlukan konfigurasi OTEL dari developer atau kebijakan. Konfigurasi yang didorong diterapkan pada tingkat terkelola, menimpa variabel `OTEL_*` yang developer atur secara lokal.
566
567[Traces](/id/monitoring-usage#traces-beta) selain itu memerlukan `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` pada setiap klien. Gateway tidak mendorong variabel itu, jadi atur melalui blok `env` kebijakan terkelola. Ini tidak pada daftar aman CLI, jadi mengirimkannya melalui kebijakan dicakup oleh dialog [security approval](#managed) yang sama yang endpoint OTLP yang didorong sudah trigger.
568
569Kedua encoding OTLP protobuf dan JSON direlai, dan backend apa pun yang kompatibel dengan OpenTelemetry bekerja sebagai tujuan.
570
571<h3 id="http-tuning">
572 HTTP tuning
573</h3>
574
575Empat blok tingkat atas opsional, `access_control`, `limits`, `timeouts`, dan `rate_limits`, menyetel permukaan HTTP. Default cocok untuk sebagian besar deployment.
576
577| Block | Key | Default | Deskripsi |
578| ---------------- | ---------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
579| `access_control` | `allow_cidrs` / `deny_cidrs` | empty | Inbound IP allow/deny berdasarkan alamat klien, setelah resolusi `trusted_proxies`. `deny_cidrs` diperiksa terlebih dahulu; klien yang cocok ditolak bahkan jika `allow_cidrs` juga cocok. Jika `allow_cidrs` non-empty gateway adalah default-deny. `/healthz` dan `/readyz` dikecualikan dari `allow_cidrs`. |
580| `limits` | `max_request_bytes` | 32 MiB | Max inbound request body; permintaan yang terlalu besar mendapat `413` sebelum body dibuffer. Naikkan untuk permintaan file atau gambar besar. |
581| `limits` | `max_request_header_bytes` | unset | Ketika diatur, header yang terlalu besar mengembalikan `431` |
582| `limits` | `max_url_length` | unset | Ketika diatur, URL yang terlalu panjang mengembalikan `414` |
583| `timeouts` | `upstream_ttfb_ms` | 120000 | Max wait untuk header respons upstream (time to first byte). Response body kemudian stream tanpa wall-clock cap. Berlaku ke jalur upstream Anthropic langsung; Bedrock, Agent Platform, dan Foundry dibatasi oleh timeout SDK penyedia mereka sendiri. |
584| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | Per-IP rate limit pada endpoint device-authorization yang tidak terautentikasi. Naikkan untuk org besar di belakang IP egress bersama atau NAT. Limit ini berlaku hanya ke alur sign-in device-grant, bukan ke inference `/v1/messages`. Lihat [User-code brute-force resistance](/id/claude-apps-gateway-deploy#user-code-brute-force-resistance). |
585| `rate_limits` | `device_verify.max` / `.window_seconds` | 10 / 600 | Per-IP rate limit pada pengajuan `user_code` di `/device` |
586
587<h2 id="complete-example">
588 Contoh lengkap
589</h2>
590
591Config reference penuh ini menggunakan setiap core section; [HTTP tuning blocks](#http-tuning) menyimpan defaults mereka. Salin, hapus apa yang Anda tidak butuhkan, dan isi values Anda. Config dalam [Quickstart](/id/claude-apps-gateway#quickstart) adalah minimal version dari ini.
592
593```yaml gateway.yaml theme={null}
594# Run with:
595# claude gateway --config gateway.yaml
596#
597# Operational log verbosity is controlled by the CLAUDE_GATEWAY_LOG_LEVEL
598# environment variable (info | warn | error; default info). It does not
599# affect audit events, which are always emitted.
600
601listen:
602 host: 0.0.0.0
603 port: 8080
604 public_url: https://claude-gateway.internal.example.com
605 # Omit the tls block when running behind a TLS-terminating ingress.
606 # tls:
607 # cert: /certs/gateway.crt
608 # key: /certs/gateway.key
609 # trusted_proxies:
610 # - 10.0.0.0/8
611
612oidc:
613 issuer: https://example.okta.com
614 client_id: 0oa1example2
615 client_secret: ${OIDC_CLIENT_SECRET}
616 allowed_email_domains:
617 - example.com
618 # Required when the issuer is the Okta org server, whose id_tokens
619 # can omit email and groups; the gateway fills them from /userinfo.
620 userinfo_fallback: true
621 # allowed_groups: [claude-code-users]
622 # Okta emits groups only when the `groups` scope is requested and the
623 # app's groups claim filter allows them. The contractors policy below
624 # matches on groups, so the scope is requested here.
625 scopes: [openid, profile, email, offline_access, groups]
626 # extra_auth_params: { access_type: offline, prompt: consent } # Google
627 # groups_claim: groups # Entra app roles: use `roles`
628 # email_claim: email
629
630session:
631 jwt_secret: ${GATEWAY_JWT_SECRET} # openssl rand -base64 32
632 # ttl_hours: 1
633
634store:
635 postgres_url: ${GATEWAY_POSTGRES_URL}
636 # max_connections: 5
637
638# Enables /v1/organizations/spend_limits (mirrors the Anthropic Admin API)
639# and per-developer spend enforcement on /v1/messages. Omit to disable.
640# Caps themselves are set via the admin API, not here.
641# admin:
642# write_keys:
643# - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
644# read_keys:
645# - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
646# admin_groups: [platform-finops]
647# blocked_message: request an increase at https://go.example.com/claude-limits
648# # audit_retention_days: 365
649# # spend_retention_months: 13
650# # identity_retention_days: 90
651# # group_limit_mode: min
652
653# enforcement:
654# fail_closed_on_error: false
655
656upstreams:
657 - provider: anthropic
658 auth:
659 api_key: ${ANTHROPIC_API_KEY}
660
661 # - provider: bedrock
662 # region: us-east-1
663 # auth: {}
664
665 # - provider: vertex
666 # region: us-east5
667 # project_id: example-prod
668 # auth: {}
669
670 # - provider: foundry
671 # resource: example-foundry
672 # auth: { use_azure_ad: true }
673
674auto_include_builtin_models: true
675models:
676 - id: claude-opus-4-8
677 label: Claude Opus 4.8
678 upstream_model:
679 anthropic: claude-opus-4-8
680 # bedrock: us.anthropic.claude-opus-4-8
681 # vertex: claude-opus-4-8
682 # foundry: <your-opus-deployment-name>
683 - id: claude-sonnet-4-6
684 label: Claude Sonnet 4.6
685 upstream_model:
686 anthropic: claude-sonnet-4-6
687 - id: claude-haiku-4-5
688 label: Claude Haiku 4.5
689 upstream_model:
690 anthropic: claude-haiku-4-5
691
692managed:
693 policies:
694 - match: { groups: [contractors] }
695 cli:
696 availableModels: [claude-haiku-4-5]
697 # Constrain the Default picker option to availableModels instead of
698 # the tier default, so contractors don't get a 400 on the default.
699 enforceAvailableModels: true
700 # allow auto-approves these tools; it does not block the rest.
701 # Add deny rules to restrict tools.
702 permissions: { allow: [Read, Grep] }
703 - match: {}
704 cli:
705 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
706 permissions:
707 allow: [Read, Grep, Bash, Edit]
708 deny: ["WebFetch"]
709 env: { HTTP_PROXY: http://proxy.example.com:8080 }
710
711telemetry:
712 forward_to:
713 - url: https://otel.internal.example.com:4318
714 headers:
715 Authorization: Bearer ${OTEL_TOKEN}
716```
717
718<h2 id="client-side-managed-settings">
719 Managed settings sisi client
720</h2>
721
722Semua di atas mengonfigurasi gateway server. Menunjukkan developer machines ke sana dikonfigurasi secara terpisah, pada setiap device, melalui Claude Code's [managed settings](/id/settings#settings-files). Gateway tidak dapat mendorong keys ini sendiri, karena mereka adalah apa yang memberitahu client di mana gateway berada.
723
724Untuk CLI, atur kedua keys dalam per-OS `managed-settings.json`:
725
726```json theme={null}
727{
728 "forceLoginMethod": "gateway",
729 "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com"
730}
731```
732
733Deploy file itu ke setiap device, typically via MDM platform Anda. File path berbeda by platform:
734
735| Platform | Path |
736| ------------- | --------------------------------------------------------------------------------------------------------------------------- |
737| macOS | `/Library/Application Support/ClaudeCode/managed-settings.json`, atau `com.anthropic.claudecode` managed preferences domain |
738| Linux dan WSL | `/etc/claude-code/managed-settings.json` |
739| Windows | `C:\Program Files\ClaudeCode\managed-settings.json`, atau Group Policy via HKLM registry |
740
741`forceLoginGatewayUrl`, dan `"gateway"` value dari `forceLoginMethod`, dihormati hanya dari admin-controlled managed tier. Developer menetapkan mereka dalam `~/.claude/settings.json` mereka sendiri tidak memiliki efek.
742
743<h2 id="related">
744 Terkait
745</h2>
746
747* [Claude apps gateway overview](/id/claude-apps-gateway): quickstart dan developer connection
748* [Deployment guide](/id/claude-apps-gateway-deploy): IdP setup, container image, Kubernetes dan Cloud Run, dan operations
749* [Spend limits](/id/claude-apps-gateway-spend-limits): per-developer caps dan Admin API
