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 Apps Gateway-Konfiguration
6
7> Referenz für jede gateway.yaml-Option: Listener und TLS, OIDC, Session, Postgres-Speicher, Bedrock/Agent Platform/Foundry-Upstreams, Modellrouting, verwaltete Richtlinien und Telemetrie.
8
9Eine Claude Apps Gateway-Bereitstellung wird durch eine YAML-Datei konfiguriert, üblicherweise `gateway.yaml`. Die Datei definiert alles, was das Gateway tut: wo es lauscht, wie sich Entwickler anmelden, wohin Inferenz geht und welche Richtlinien und Telemetrie gelten. Diese Seite ist die Referenz für jede Option in dieser Datei. Um Ihre erste zu schreiben, beginnen Sie mit dem [Schnellstart](/de/claude-apps-gateway#quickstart), der eine minimale funktionierende Konfiguration erstellt und ausführt. Sobald Sie eine Konfiguration haben, mit der Sie zufrieden sind, behandelt der [Bereitstellungsleitfaden](/de/claude-apps-gateway-deploy) die Containerisierung und das Hosting auf Kubernetes, Cloud Run oder Ihrer eigenen Plattform.
10
11Das Gateway liest die Datei einmal beim Start mit `claude gateway --config /path/to/gateway.yaml`. Jede Option wird beim Start gegen ein Schema validiert, sodass eine fehlerhafte Konfiguration beim Start mit einem Fehler auf Feldebene fehlschlägt, anstatt bei der ersten Verwendung.
12
13Das [vollständige Beispiel](#complete-example) am Ende dieser Seite behandelt jeden Abschnitt.
14
15<h2 id="file-structure">
16 Dateistruktur
17</h2>
18
19Fünf Abschnitte sind [erforderlich](#required-sections). Jeder andere Abschnitt ist [optional](#optional-sections), und ein fehlender Abschnitt nimmt seine Standardwerte an. Unbekannte Schlüssel führen zum Fehlschlag beim Start, sodass ein Tippfehler als benannter Fehler anstelle einer stillschweigend ignorierten Einstellung auftaucht.
20
21**Erforderliche Abschnitte:**
22
23* [`listen`](#listen): Bindungsadresse, öffentliche URL, TLS-Beendigung
24* [`oidc`](#oidc): Ihr Identitätsanbieter (IdP), einschließlich Aussteller, Client, Anspruchszuordnung und wer sich anmelden darf
25* [`session`](#session): die Bearer-Token, die das Gateway ausstellt, mit Geheimnis und Lebensdauer
26* [`store`](#store): PostgreSQL, für Gerätezuschüsse und Rate-Limit-Zähler
27* [`upstreams`](#upstreams): wohin Inferenz geht, ob Anthropic, Bedrock, Agent Platform oder Foundry
28
29**Optionale Abschnitte:**
30
31* [`admin`](#admin): Admin-API-Authentifizierung und Aufbewahrung für Ausgabenlimits
32* [`enforcement`](#enforcement): Ausgabenlimit-Verhalten bei Fehler-offen oder Fehler-geschlossen
33* [`models`](#models) und `auto_include_builtin_models`: von Admin kuratierte Modellliste und Pro-Upstream-IDs
34* [`managed`](#managed): verwaltete Einstellungsrichtlinien nach IdP-Gruppe
35* [`telemetry`](#telemetry): OTLP-Weiterleitung an Ihren Observability-Stack
36* [`access_control`, `limits`, `timeouts`, `rate_limits`](#http-tuning): IP-Zulassung/Ablehnung, Anfragegrößenbeschränkungen, Upstream-Zeit-bis-erstes-Byte und Pro-IP-Anmeldungslimits
37
38<h2 id="secret-expansion">
39 Geheimniserweiterung
40</h2>
41
42Schreiben Sie Geheimnisse wie `client_secret`, `jwt_secret` oder `postgres_url` nicht direkt in `gateway.yaml`. Referenzieren Sie sie mit einem der folgenden Formulare, und das Gateway löst den Wert beim Start aus einer Umgebungsvariablen oder einer Datei auf:
43
44| Formular | Wird aufgelöst zu | Verwenden für |
45| --------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------- |
46| `${VAR}` | Die Umgebungsvariable `VAR`. Der Start schlägt fehl, wenn nicht definiert. | Container-Umgebungsvariablen, AWS Secrets Manager über Env-Injektion |
47| `${file:/path}` | Dateiinhalt, gekürzt | Kubernetes Secret-Volume-Mounts, Vault Agent, SOPS |
48
49<h2 id="required-sections">
50 Erforderliche Abschnitte
51</h2>
52
53<h3 id="listen">
54 `listen`
55</h3>
56
57Der `listen`-Block steuert, wo das Gateway bereitgestellt wird: die Bindungsadresse und der Port, der extern sichtbare Ursprung und optionale TLS-Beendigung.
58
59| Feld | Erforderlich | Beschreibung |
60| ---------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
61| `host` | Nein | Bindungsadresse. Standard `0.0.0.0`. |
62| `port` | Nein | Bindungsport. Standard `8080`. |
63| `public_url` | Hinter einem Proxy | Der extern sichtbare `https://`-Ursprung, der zum Erstellen des IdP-`redirect_uri` und der Erkennungsmetadaten verwendet wird. Erforderlich hinter jedem TLS-beendenden Proxy wie ALB, Ingress oder Cloud Run, da das Gateway `X-Forwarded-*`-Header nicht vertraut, wenn es seinen eigenen Ursprung konstruiert; diese sind Client-spoofbar. `trusted_proxies` unten regelt nur die Client-IP-Auflösung. Auch erforderlich, um [Telemetrie](#telemetry) zu aktivieren, da das Gateway den OTLP-Endpunkt, den es an Clients pusht, aus dieser URL erstellt. |
64| `tls.cert` / `tls.key` | Nein | PEM-Pfade, wenn das Gateway selbst TLS beendet |
65| `trusted_proxies` | Nein | CIDRs oder IPs von Load Balancern vor dem Gateway. Wenn gesetzt, vertraut das Gateway `X-Forwarded-For` nur von diesen Peers und zeichnet die echte Client-IP für Pro-IP-Rate-Limiting und Audit auf. Äquivalent zu nginx `set_real_ip_from`. |
66
67<h3 id="oidc">
68 `oidc`
69</h3>
70
71OpenID Connect (OIDC) ist das SSO-Protokoll, das das Gateway mit Ihrem Identitätsanbieter verwendet; siehe [Identitätsanbieter-Setup](/de/claude-apps-gateway-deploy#identity-provider-setup) für das, was Sie auf der IdP-Seite registrieren müssen. Der `oidc`-Block verbindet das Gateway mit Ihrem Identitätsanbieter und entscheidet, wer sich anmelden kann. Er benennt den Aussteller und OAuth-Client, ordnet die Ansprüche zu, die E-Mail und Gruppen enthalten, und beschränkt die Anmeldung nach E-Mail-Domäne oder Gruppe.
72
73| Feld | Erforderlich | Beschreibung |
74| ------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
75| `issuer` | Ja | OIDC-Erkennungsbasis. Muss Erkennung unter `/.well-known/openid-configuration` bereitstellen. Verwenden Sie HTTPS in der Produktion; das Gateway akzeptiert einen `http://`-Aussteller. Ein Loopback-Aussteller wie `http://localhost:8081` wird vom [SSRF-Schutz](/de/claude-apps-gateway-deploy#threat-model-summary) abgelehnt, es sei denn, `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1` ist in der Gateway-Umgebung gesetzt. |
76| `client_id` / `client_secret` | Ja | Aus Ihrer OAuth-Client-Registrierung |
77| `allowed_email_domains` | Nein | Lehnen Sie id\_tokens ab, deren `email`-Anspruch nicht in einer dieser Domänen liegt, Groß-/Kleinschreibung ignoriert. Verteidigungstiefe gegen Multi-Tenant-IdP-Fehlkonfiguration. Unabhängig von dieser Einstellung wird ein id\_token, dessen `email_verified`-Anspruch explizit `false` ist, immer abgelehnt. |
78| `allowed_groups` | Nein | Beschränken Sie die Anmeldung auf Mitglieder dieser IdP-Gruppen, abgeglichen gegen `groups_claim`. Ein Benutzer in einer zulässigen E-Mail-Domäne, aber in keiner dieser Gruppen, wird abgelehnt. Erfordert, dass der IdP den Gruppenanspruch ausgibt. |
79| `groups_claim` | Nein | Welcher id\_token-Anspruch trägt die Gruppenmitgliedschaft. Standard `groups`. Microsoft Entra gibt App-Rollen unter `roles` aus. Akzeptiert einen flachen Schlüssel oder einen RFC 6901 JSON Pointer wie `/resource_access/gateway/roles` für verschachtelte Ansprüche. |
80| `google_groups` | Nein | Schlagen Sie die Gruppen des angemeldeten Benutzers über die Google Workspace Admin SDK Directory API nach, da Googles id\_token keinen Gruppenanspruch trägt. Setzen Sie `service_account_json_path` auf eine Service-Account-Schlüsseldatei mit Domain-weiter Delegation im Bereich `https://www.googleapis.com/auth/admin.directory.group.readonly` und `admin_email` auf einen Workspace-Administrator, den der Service Account annimmt; die Directory API erfordert ein echtes Admin-Subjekt. Die E-Mail-Adressen jeder Benutzergruppe werden zu ihrem Gruppenanspruch, sodass `allowed_groups` und `managed.policies.match.groups` auf Gruppen-E-Mails abgeglichen werden. |
81| `email_claim` | Nein | Welcher id\_token-Anspruch trägt die E-Mail des Benutzers. Standard `email`. Einige IdPs wie ADFS und Entra B2C geben stattdessen `upn` oder `preferred_username` aus. Akzeptiert einen flachen Schlüssel, einen JSON Pointer oder eine Liste von Fallback-Schlüsseln, wobei der erste vorhandene Schlüssel verwendet wird. |
82| `scopes` | Nein | Vollständige Überschreibung der OIDC-Bereiche, die das Gateway anfordert. Standard `[openid, profile, email, offline_access]`. Setzen Sie, wenn Ihr IdP Bereiche ablehnt, die er nicht erkennt, oder einen benutzerdefinierten Bereich erfordert, um Gruppen oder E-Mail auszugeben. Muss `openid` enthalten. Das Löschen von `offline_access` deaktiviert Aktualisierungstoken, sodass Entwickler die Browser-Anmeldung alle `session.ttl_hours` erneut ausführen. Siehe [Identitätsanbieter-Setup](/de/claude-apps-gateway-deploy#identity-provider-setup) für Pro-IdP-Bereich-Rezepte wie Googles Aktualisierungstoken-Fluss. |
83| `extra_auth_params` | Nein | Zusätzliche Abfrageparameter, die wörtlich an die IdP-Autorisierungsanfrage angehängt werden. Dies ist der Überschreibungsmechanismus für IdP-spezifisches Verhalten, wie `access_type: offline` für Google-Aktualisierungstoken, `domain_hint` für einige Entra-Mandanten oder `acr_values` für Step-up-Flüsse. Kann die vom Gateway verwalteten Protokollparameter nicht überschreiben: `state`, `nonce`, `redirect_uri`, PKCE, `scope`, `response_type`, `response_mode` und `client_id`. |
84| `userinfo_fallback` | Nein | Wenn der id\_token E-Mail oder Gruppen auslässt, rufen Sie sie von `/userinfo` ab. Erforderlich für Keycloak-Lightweight-Zugriffstokens, den Okta-Org-Server und ADFS-Minimal-Tokens. Der id\_token bleibt maßgeblich; userinfo füllt nur Lücken. Standard `false`. |
85| `use_pkce` | Nein | Senden Sie eine PKCE (S256)-Herausforderung bei der Autorisierungsanfrage. Standard `true`. Setzen Sie `false` nur, wenn Ihr IdP PKCE für diesen vertraulichen Client ablehnt. |
86| `clock_skew_seconds` | Nein | Tolerieren Sie Uhrenabweichungen beim Validieren von id\_token-Zeitansprüchen. Standard `0`, was streng ist. Erhöhen Sie, wenn Sie "Token abgelaufen / noch nicht gültig"-Fehler direkt nach der Anmeldung aufgrund von Host-/IdP-Uhrenabweichung sehen. |
87| `token_endpoint_auth_method` | Nein | Überschreiben Sie die Token-Endpunkt-Authentifizierungsmethode. Akzeptiert `client_secret_basic` oder `client_secret_post`. Standardmäßig automatisch ausgehandelt. |
88| `id_token_signed_response_alg` | Nein | Erwarteter id\_token-Signaturalgorithmus. Standard `RS256`. Setzen Sie für IdPs, die mit ES256, PS256 oder EdDSA signieren. |
89| `additional_authorized_parties` | Nein | Zusätzliche `azp`-Werte, die neben `client_id` akzeptiert werden, für Keycloak-Broker und Token-Exchange-Flüsse |
90| `discovery_url` | Nein | Rufen Sie das Erkennungsdokument von dieser URL ab, anstatt es vom `issuer` abzuleiten, für IdPs hinter einem Proxy, der den Aussteller-Host umschreibt. Der Pfad muss `/.well-known/` enthalten. |
91| `form_action_origins` | Nein | Zusätzliche Ursprünge für die `Content-Security-Policy: form-action`-Direktive der `/device`-Seite. Das Gateway erlaubt bereits `'self'` und den erkannten `authorization_endpoint`-Ursprung, aber Chrome erzwingt `form-action` gegen die gesamte Umleitungskette. Wenn Ihr IdP durch einen zweiten Host umleitet, wie Azure AD, das zu ADFS verbunden ist, Hub-Spoke-Okta oder ein unternehmensweiter SSO-Interceptor, listen Sie jeden Ursprung auf, durch den die Autorisierungsanfrage umgeleitet werden kann. |
92| `ca_cert_pem` | Nein | PEM-CA-Zertifikat, das den System-Trust-Store nur für IdP-Anfragen ersetzt. Verwenden Sie für Keycloak oder Dex hinter unternehmensweiter PKI. |
93
94<h3 id="session">
95 `session`
96</h3>
97
98Der `session`-Block formt die Bearer-Token, die das Gateway nach der Anmeldung ausstellt: das Geheimnis, das sie signiert, und wie lange sie leben.
99
100| Feld | Erforderlich | Beschreibung |
101| ------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
102| `jwt_secret` | Ja | Mindestens 32 Bytes Entropie, zum Beispiel von `openssl rand -base64 32`. Signiert die HS256-Bearer-Tokens des Gateways. Akzeptiert einen einzelnen String oder ein Array für Rotation: Index 0 signiert und alle Einträge verifizieren. Um zu rotieren, stellen Sie ein neues Geheimnis voran, warten Sie `ttl_hours`, dann löschen Sie das alte. |
103| `ttl_hours` | Nein | Gateway-Bearer-Token-Lebensdauer. Standard `1`. Die CLI aktualisiert sich stillschweigend vor Ablauf, wenn der IdP Aktualisierungstoken ausgibt. Eine kürzere Lebensdauer hebt die Bereitstellung schneller auf; eine längere macht weniger IdP-Rundfahrten. Wenn Ihr IdP keine Aktualisierungstoken ausstellen kann, weil `offline_access` nicht verfügbar ist, gibt es keine stille Aktualisierung, also erhöhen Sie dies auf `8` oder `12`, um zu vermeiden, dass Entwickler alle Stunde zur Browser-Anmeldung zurückgesendet werden. |
104
105<h3 id="store">
106 `store`
107</h3>
108
109Der `store`-Block zeigt das Gateway auf seine PostgreSQL-Datenbank, die Gerätezuschüsse und Rate-Limit-Zähler enthält.
110
111| Feld | Erforderlich | Beschreibung |
112| ----------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
113| `postgres_url` | Ja | `postgres://` oder `postgresql://` URL. Erforderlich: das Gerätezuschuss-Rendezvous, wo der Browser-Callback schreibt und die Polling-CLI liest, benötigt Cross-Replica-Status. Das Gateway führt seine eigenen Schema-Migrationen beim Start aus, sodass die Rolle `CREATE TABLE` im Zielschema benötigt. Wenn Ihre Sicherheitsrichtlinie DDL von der Anwendungsrolle verbietet, führen Sie die Migrationen mit einer Admin-Rolle aus, anfangs und jedes Mal, wenn ein neues Release Migrationen ausliefert, und gewähren Sie der App-Rolle `SELECT, INSERT, UPDATE, DELETE` auf den Gateway-Tabellen. Siehe [Upgrades](/de/claude-apps-gateway-deploy#upgrades) und [Postgres](/de/claude-apps-gateway-deploy#postgres). |
114| `username` | Nein | Überschreibt den Benutzer in `postgres_url` |
115| `password` | Nein | Datenbankberechtigungsnachweis. Setzen Sie ihn hier anstelle von `postgres_url`, damit die Berechtigung aus der URL bleibt. Akzeptiert beliebige Zeichen und hat Vorrang vor URL-Berechtigungsnachweisen. |
116| `max_connections` | Nein | Postgres-Verbindungspool-Größe pro Replik. Standard `5`, was konservativ und freundlich zu gemeinsamen Datenbanken ist. Mit [Ausgabenlimits](#admin) aktiviert, macht der Hot Path ein paar Operationen pro Inferenzanfrage, also erhöhen Sie es für eine dedizierte Datenbank unter Last und halten Sie Replikas × dies unter der `max_connections` der Datenbank. |
117
118Für die lokale Entwicklung zeigen Sie `postgres_url` auf einen Wegwerf-Postgres-Container, zum Beispiel `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` ist eine geordnete Liste. Das Gateway leitet Inferenz an den ersten Upstream weiter, der das angeforderte Modell auflöst. Bei `5xx`, `429` oder Timeout schlägt es zum nächsten fehl; andere `4xx` nicht, da diese Fehler der Anfrage statt dem Upstream zuzuordnen sind. Mehrere Upstreams desselben Anbieters müssen einen unterschiedlichen `name:` setzen.
125
126Bedrock-, Agent Platform- und Foundry-Clients werden einmal beim Start erstellt, und ihre SDKs aktualisieren Berechtigungsnachweise intern, sodass das Rotieren von Cloud-Berechtigungsnachweisen keinen Neustart erfordert. Statische Anthropic-API-Schlüssel und Bearer werden beim Start gelesen; siehe [Anthropic API](#anthropic-api).
127
128<h4 id="anthropic-api">
129 Anthropic API
130</h4>
131
132Der minimale Anthropic-Upstream ist ein API-Schlüssel aus der [Claude Console](https://platform.claude.com):
133
134```yaml theme={null}
135upstreams:
136 - provider: anthropic
137 auth:
138 api_key: ${ANTHROPIC_API_KEY}
139 # ODER ein OAuth-Bearer (z.B. ein Workload-Identity-Federation-ausgetauschter Token):
140 # oauth_token: ${file:/var/run/secrets/anthropic-oauth-token}
141 # base_url: https://api.anthropic.com # Standard; Überschreibung für einen Forward Proxy
142```
143
144Die zwei Berechtigungsnachweis-Formulare unterscheiden sich im Header, den sie senden:
145
146* **`api_key`**: sendet `x-api-key`. Rotieren Sie ihn in der Claude Console und aktualisieren Sie die Env-Variable.
147* **`oauth_token`**: sendet `Authorization: Bearer`. Verwenden Sie das Bearer-Formular, wenn Ihre Organisation kurzlebige Token statt langlebiger API-Schlüssel ausgibt. Der Bearer wird einmal beim Start gelesen, also aktualisieren Sie durch Remounten des Geheimnisses und Neustart.
148
149Anstelle eines statischen Schlüssels oder Bearers können Sie Workload Identity Federation verwenden. Erstellen Sie eine Verbindungsregel, indem Sie dem [Workload Identity Federation-Leitfaden](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) folgen, dann mounten Sie das OIDC-JWT Ihrer Workload als Datei, wie ein Kubernetes-projiziertes Service-Account-Token oder ein ID-Token einer CI-Plattform. Das Gateway tauscht das JWT gegen einen kurzlebigen Bearer aus und aktualisiert ihn automatisch. Die Token-Datei wird bei jedem Austausch erneut gelesen, sodass rotierte projizierte Tokens ohne Neustart aufgegriffen werden.
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_... # erforderlich, wenn die Regel >1 Workspace abdeckt
159 # service_account_id: svac_... # optionale erwartete Zielprüfung
160```
161
162<h4 id="amazon-bedrock">
163 Amazon Bedrock
164</h4>
165
166Für die Client-seitige Bedrock-Bereitstellung, die das Gateway ersetzt oder frontet, siehe [Claude Code on Amazon Bedrock](/de/amazon-bedrock). Der Gateway-seitige Upstream:
167
168```yaml theme={null}
169upstreams:
170 - provider: bedrock
171 region: us-east-1
172 auth: {} # bevorzugt: AWS-Standard-Berechtigungskette
173 # ODER explizite Berechtigungsnachweise:
174 # auth:
175 # aws_access_key_id: ${AWS_AKID}
176 # aws_secret_access_key: ${AWS_SK}
177 # aws_session_token: ${AWS_ST}
178 # ODER ein Bedrock-API-Bearer-Token:
179 # auth:
180 # aws_bearer_token: ${AWS_BEARER_TOKEN}
181 # Überschreiben Sie den bedrock-runtime-Endpunkt für FIPS oder VPC-Endpunkt-Bereitstellungen:
182 # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com
183```
184
185Ein leerer `auth`-Block verwendet die Standard-Berechtigungskette des AWS SDK: Env-Variablen, `~/.aws/credentials`, ECS-Task-Rolle, EC2-Instanzmetadaten oder IRSA auf EKS. In der Produktion geben Sie dem Gateway-Pod eine IAM-Rolle statt statische Schlüssel in ein Container-Image einzubetten.
186
187| Setup | Wie |
188| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
189| IAM-Berechtigungen | Gewähren Sie dem Gateway-Principal `bedrock:InvokeModel` und `bedrock:InvokeModelWithResponseStream` sowohl auf den Inferenz-Profil-ARNs als auch auf den zugrunde liegenden Foundation-Model-ARNs. Für den integrierten Katalog in US-Regionen: `arn:aws:bedrock:<region>:<account>:inference-profile/us.anthropic.*` und `arn:aws:bedrock:*::foundation-model/anthropic.*`. |
190| Modellzugriff | In der Bedrock-Konsole pro Region fordern Sie Modellzugriff für die Claude-Modelle an, die Sie möchten, und aktivieren Sie ihn. Cross-Region-Inferenz-Profile (`us.anthropic.*`) erfordern Modellzugriff in jeder Region, die das Profil umfasst. |
191| EKS (IRSA) | Erstellen Sie eine IAM-Rolle mit der obigen Richtlinie und einer Vertrauensrichtlinie für den OIDC-Provider Ihres Clusters, der auf das Service-Account des Gateways beschränkt ist. Kommentieren Sie das Service-Account mit `eks.amazonaws.com/role-arn: arn:aws:iam::<acct>:role/claude-gateway`. `auth: {}` nimmt es auf. |
192| ECS / EC2 | Hängen Sie die IAM-Rolle an die Task-Definition oder das Instance-Profil an. `auth: {}` nimmt es auf. |
193| Überall sonst | Übergeben Sie Berechtigungsnachweise über die Env-Variablen `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` und `AWS_SESSION_TOKEN`, oder setzen Sie sie explizit in `auth:` mit `${VAR}`-Erweiterung |
194| Region | `region:` ist die API-Endpunkt-Region. Cross-Region-Inferenz-Profile routen über die Geo (US, EU, APAC) unabhängig davon, welche Sie wählen. Für Nicht-US-Regionen oder bereitgestellte Durchsatz-ARNs fügen Sie einen [`models:`](#models)-Block mit den richtigen Pro-Upstream-IDs hinzu. |
195
196<h4 id="google-cloud-agent-platform">
197 Google Cloud Agent Platform
198</h4>
199
200Für das äquivalente Client-seitige Setup siehe [Claude Code on Google Cloud](/de/google-vertex-ai). Der Gateway-seitige Upstream:
201
202```yaml theme={null}
203upstreams:
204 - provider: vertex
205 region: us-east5
206 project_id: example-prod
207 auth: {} # bevorzugt: Application Default Credentials
208 # ODER eine Service-Account-Schlüsseldatei:
209 # auth: { service_account_json: /secrets/sa.json }
210 # Überschreiben Sie den aiplatform-Endpunkt für Private Service Connect:
211 # base_url: https://us-east5-aiplatform.p.googleapis.com
212```
213
214Ein leerer `auth`-Block verwendet Application Default Credentials: `GOOGLE_APPLICATION_CREDENTIALS`, GCE-Metadaten oder GKE Workload Identity. Service-Account-JSON-Schlüsseldateien werden unterstützt, aber nicht empfohlen; verwenden Sie Workload Identity oder hängen Sie ein Service-Account an die GCE- oder Cloud Run-Instanz an.
215
216Setzen Sie `region: global`, um [Agent Platforms globalen Endpunkt](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations) statt eines regionalen zu verwenden. Google leitet dann jede Anfrage an eine verfügbare Region weiter, sodass Sie die Pro-Region-Modellverfügbarkeit nicht verfolgen. Das Setzen einer bestimmten Region heftet jede Anfrage daran.
217
218| Setup | Wie |
219| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
220| IAM-Berechtigungen | Gewähren Sie dem Gateway-Service-Account `roles/aiplatform.user` auf dem Projekt oder eine benutzerdefinierte Rolle mit `aiplatform.endpoints.predict`. Aktivieren Sie die Agent Platform API (`aiplatform.googleapis.com`). |
221| Modellzugriff | Aktivieren Sie in Model Garden die Claude-Modelle für Ihr Projekt. Sie werden in bestimmten Regionen veröffentlicht; überprüfen Sie die Modellkarte auf unterstützte Regionen. |
222| GKE (Workload Identity) | Binden Sie ein GCP-Service-Account an das Kubernetes-Service-Account des Gateways und kommentieren Sie das KSA mit `iam.gke.io/gcp-service-account: claude-gateway@<proj>.iam.gserviceaccount.com`. `auth: {}` nimmt es auf. |
223| Cloud Run / GCE | Setzen Sie das Service-Account des Service auf eines mit `roles/aiplatform.user`. `auth: {}` nimmt es auf. |
224| Überall sonst | `auth: { service_account_json: /secrets/sa.json }`, der Pfad zu einer JSON-Schlüsseldatei, die als Geheimnis gemountet ist. Das Feld nimmt einen Dateipfad, nicht den Schlüsselinhalt, also ist keine `${file:…}`-Erweiterung beteiligt. |
225
226<h4 id="microsoft-foundry">
227 Microsoft Foundry
228</h4>
229
230Für die Client-seitige Foundry-Bereitstellung siehe [Claude Code on Microsoft Foundry](/de/microsoft-foundry). Der Gateway-seitige 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 } # bevorzugt: DefaultAzureCredential / Managed Identity
237 # ODER ein API-Schlüssel:
238 # auth:
239 # api_key: ${FOUNDRY_API_KEY}
240```
241
242`use_azure_ad: true` wird durch `DefaultAzureCredential` aufgelöst: Managed Identity auf AKS, ACI oder App Service; die Azure CLI; oder Umgebungsberechtigungsnachweise. API-Schlüssel funktionieren, sind aber projektumfassend und rotieren nicht automatisch. Der Foundry-Endpunkt wird von `resource:` abgeleitet; setzen Sie das optionale `base_url`, um es für souveräne Clouds wie Azure Government zu überschreiben.
243
244| Setup | Wie |
245| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
246| RBAC | Gewähren Sie dem Gateway-Identity `Azure AI User` oder `Cognitive Services User` auf der Foundry-Ressource |
247| Bereitstellungen | Foundry verwendet von Admin gewählte Bereitstellungsnamen, nicht kanonische Modell-IDs. Fügen Sie einen [`models:`](#models)-Block hinzu, der jede kanonische ID Ihrem Bereitstellungsnamen zuordnet. |
248| AKS (Workload-Identität) | Verbinden Sie eine User-Assigned Managed Identity mit dem OIDC-Issuer des Clusters und binden Sie sie an das Service-Account des Gateways. `use_azure_ad: true` nimmt es über `WorkloadIdentityCredential` auf. |
249| ACI / App Service | Aktivieren Sie system-zugewiesene oder user-zugewiesene Managed Identity auf der Ressource. `use_azure_ad: true` nimmt es auf. |
250| Überall sonst | `auth: { api_key: "${FOUNDRY_API_KEY}" }`. Zitieren Sie `${…}` innerhalb von `{ }`. |
251
252<h4 id="multiple-upstreams">
253 Mehrere Upstreams
254</h4>
255
256Derselbe Anbieter kann mehr als einmal mit einem unterschiedlichen `name:` erscheinen. Dies deckt verschiedene Regionen, verschiedene Konten über verschiedene Berechtigungsketten, bereitgestellter Durchsatz versus On-Demand und Cross-Provider-Fallback ab.
257
258Das Gateway versucht Upstreams in Reihenfolge. `5xx`, `429`, Timeouts und fehlender Endpunkt (`501`) schlagen fehl; andere `4xx` nicht. `429` ist Pro-Upstream-Kapazität, sodass bereitgestellter Durchsatz (PT)-Erschöpfung zu On-Demand fehlschlägt. Ein Upstream, der das angeforderte Modell nicht auflösen kann, wird ohne Netzwerk-Rundfahrt übersprungen.
259
260Dieses Beispiel leitet eine bereitgestellte Durchsatz-Bedrock-Zuteilung zuerst weiter, überläuft zu On-Demand und einem zweiten Konto und fällt zuletzt auf die Anthropic API zurück:
261
262```yaml theme={null}
263upstreams:
264 # Primär: bereitgestellter Durchsatz in Ihrer Heimatregion.
265 - name: bedrock-pt
266 provider: bedrock
267 region: us-east-1
268 auth: {}
269 # Überlauf: On-Demand Cross-Region.
270 - name: bedrock-od
271 provider: bedrock
272 region: us-west-2
273 auth: {}
274 # Anderes Konto: eine separate Bedrock-Zuteilung über angenommene Rollberechtigungsnachweise.
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 # Letzter Ausweg: direkte Anthropic API.
282 - name: anthropic-fallback
283 provider: anthropic
284 auth:
285 api_key: ${ANTHROPIC_API_KEY}
286
287# Pro-Upstream-Modell-IDs werden auf dem `name:` des Upstream geschlüsselt; ein Upstream
288# ohne `name:` nimmt standardmäßig seinen Provider-String (z.B. `bedrock`). Jeder
289# Upstream, der nicht für ein Modell aufgelistet ist, wird übersprungen, was ist, wie Sie ein Modell
290# zu bereitgestelltem Durchsatz routen, während alles andere On-Demand bleibt.
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| Hebel | Wie |
302| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
303| Verschiedene Regionen | Ein Bedrock-Upstream pro Region, jeder mit seiner eigenen `region:`. Mit [`auto_include_builtin_models: true`](#models) routen die Cross-Region-Inferenz-Profile automatisch; für Region-gepinnte Bereitstellungen verwenden Sie einen `models:`-Block. |
304| Verschiedene Konten | Ein Bedrock-Upstream pro Konto, jeder mit seinen eigenen Berechtigungsnachweisen in `auth:`. Die Standard-Kette (`auth: {}`) verwendet die Pod-Identität; für ein zweites Konto setzen Sie explizite Berechtigungsnachweise oder ein Bearer-Token. |
305| Bereitgestellter Durchsatz | Ordnen Sie das Modell der bereitgestellten Durchsatz-ARN in `models:` für den Namen dieses Upstream zu. Andere Upstreams behalten die On-Demand-ID, sodass PT-Kapazität vor dem Failover erschöpft ist. |
306| VPC / FIPS-Endpunkte | Setzen Sie `base_url:` auf dem Upstream auf Ihren VPC-Endpunkt oder FIPS-Endpunkt-URL |
307| Modell-gesteuertes Routing | Lassen Sie einen Upstream aus der `upstream_model:`-Karte eines Modells weg und dieser Upstream wird für dieses Modell übersprungen. Zum Beispiel routen Sie Opus zu bereitgestelltem Durchsatz und Sonnet und Haiku zu On-Demand. |
308
309Das Failover zwischen Cloud-Anbietern oder zur direkten Anthropic API ändert, welche Vereinbarung, Geographie und andere Bedingungen die Anfrage regeln.
310
311Die CLI wendet dasselbe Feature-Gating auf Gateways an, unabhängig davon, welcher Upstream eine bestimmte Anfrage bedient, sodass Failover kein Body-Feld sendet, das ein Upstream ablehnen würde.
312
313<h2 id="optional-sections">
314 Optionale Abschnitte
315</h2>
316
317<h3 id="admin">
318 `admin`
319</h3>
320
321Optional. Aktiviert `/v1/organizations/spend_limits`, das Anthropics öffentliche Admin API spiegelt, und Pro-Entwickler-Ausgabendurchsetzung auf `/v1/messages`. Siehe [Ausgabenlimits](/de/claude-apps-gateway-spend-limits) für wie Caps gesetzt und durchgesetzt werden; dieser Abschnitt behandelt die `gateway.yaml`-Schlüssel, die die Funktion aktivieren und sie abstimmen.
322
323```yaml theme={null}
324admin:
325 # Benannte statische API-Schlüssel für die Admin-Endpunkte, gesendet als x-api-key.
326 # Die ID erscheint im Audit-Log als admin-key:<id>, sodass jeder Schlüssel
327 # zurechenbar ist. Array für Rotation: fügen Sie den neuen Schlüssel hinzu, rollen Sie Clients,
328 # entfernen Sie den alten.
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-Gruppen, denen vollständiger Admin über das normale Gateway-JWT gewährt wird (kein API-Schlüssel).
335 admin_groups: [platform-finops]
336 blocked_message: request an increase at https://go.example.com/claude-limits
337```
338
339| Feld | Erforderlich | Beschreibung |
340| ------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
341| `write_keys` | Nein | Array von `{id, key}`. Ein `x-api-key`, das einem dieser entspricht, kann Ausgabenlimits auflisten, setzen und löschen. Schlüsselwerte müssen mindestens 32 Zeichen sein; `id`s müssen über `read_keys` und `write_keys` eindeutig sein. |
342| `read_keys` | Nein | Array von `{id, key}`. Schreibgeschützt: jeder `GET`-Endpunkt, einschließlich Auflistung von Caps, Abrufen eines nach ID und Lesen von [`/effective`](/de/claude-apps-gateway-spend-limits#%2Feffective) und [`/audit`](/de/claude-apps-gateway-spend-limits#%2Faudit). |
343| `admin_groups` | Nein | IdP-Gruppennamen. Ein Gateway-JWT, dessen `groups`-Anspruch einen dieser enthält, hat vollständigen Admin-Zugriff, Lesen und Schreiben, und Audits als `oidc:<sub>`. Verwenden Sie dies für menschliche Admins; verwenden Sie API-Schlüssel für Maschinen. |
344| `blocked_message` | Nein | Wörtlich an die `429 billing_error` angehängt, die ein blockierter Entwickler sieht. Schreiben Sie die ganze Anweisung, wie eine URL oder einen Slack-Kanal. Nicht gesetzt, der Fehler ist `spend limit reached`. |
345| `audit_retention_days` | Nein | Standard `365`. Ältere `admin_audit`-Zeilen werden gefegt. |
346| `spend_retention_months` | Nein | Standard `13`. `spend`-Zähler-Zeilen älter als dies werden gefegt. Der Standard behält ein volles Jahr plus den aktuellen Teilmonat für Jahr-über-Jahr-Berichterstattung. |
347| `identity_retention_days` | Nein | Standard `90`. Last-Seen-TTL für `principal_emails`-Zeilen, die die E-Mail, den Anzeigenamen und die Gruppen jedes Entwicklers enthalten (PII). Absichtlich kürzer als Ausgabenaufbewahrung, sodass eine bereitgestellte Identität altert, während ihre anonymen Ausgabenzähler bleiben. |
348| `group_limit_mode` | Nein | `min` (Standard) oder `max`. Wenn ein Entwickler in mehreren Gruppen mit Caps ist, erzwingt `min` die restriktivste und `max` die am wenigsten restriktive. Wird sowohl von Durchsetzung als auch von `/effective` verwendet. |
349
350<h3 id="enforcement">
351 `enforcement`
352</h3>
353
354Der `enforcement`-Block steuert, wie Ausgabenlimit-Prüfungen sich verhalten, wenn der Store nicht verfügbar ist.
355
356| Feld | Erforderlich | Beschreibung |
357| ---------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
358| `fail_closed_on_error` | Nein | Standard `false`. Ausgabendurchsetzung schlägt bei einem Postgres-Ausfall offen fehl, sodass Inferenz oben bleibt. Setzen Sie `true`, um geschlossen fehlzuschlagen: Über-Cap-Entwickler werden blockiert, aber so ist jeder, wenn der Store nicht erreichbar ist. Hat keine Auswirkung ohne einen [`admin:`](#admin)-Block. |
359
360<h3 id="models">
361 `models`
362</h3>
363
364Der `models`-Block ist eine optionale von Admin kuratierte Modellliste, die unter `/v1/models` bereitgestellt wird und zum Übersetzen von Modell-IDs pro Upstream verwendet wird. Es ist erforderlich für Nicht-US-Bedrock-Regionen, Bedrock-bereitgestellte Durchsatz-ARNs und Foundry-Bereitstellungsnamen.
365
366```yaml theme={null}
367auto_include_builtin_models: true # false: nur die Liste unten exponieren
368models:
369 - id: claude-opus-4-8
370 label: Claude Opus 4.8
371 # description: optionaler Text, der in Clients angezeigt wird, die ihn exponieren
372 upstream_model:
373 anthropic: claude-opus-4-8
374 bedrock: us.anthropic.claude-opus-4-8 # oder eine Inferenz-Profil-ARN
375 foundry: your-opus-deployment-name
376```
377
378<h3 id="managed">
379 `managed`
380</h3>
381
382Der `managed`-Block definiert rollenbasierte Zugriffrichtlinien, die auf IdP-Gruppen oder E-Mail-Domäne geschlüsselt sind. Richtlinien werden in Reihenfolge ausgewertet; die erste Übereinstimmung wird ausgewählt, dann auf die `match: {}`-Catch-All-Basis zusammengeführt, die unten beschrieben wird. Sie werden pro Benutzer unter `GET /managed/settings` mit ETag/304-Caching bereitgestellt.
383
384```yaml theme={null}
385managed:
386 policies:
387 # Spezifische Gruppen zuerst.
388 - match: { groups: [eng-contractors] }
389 cli:
390 availableModels: [claude-sonnet-4-6]
391 permissions: { deny: ["WebFetch", "WebSearch"] }
392 # Standard-Catch-All zuletzt: passt zu jedem, der sich authentifiziert hat.
393 - match: {}
394 cli:
395 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
396```
397
398Ein `match: {}`-Catch-All, üblicherweise zuletzt aufgelistet, wird als Basisschicht behandelt. Jede andere Richtlinie erbt jeden Schlüssel, den sie nicht von der Catch-All setzt, sodass Pro-Rollen-Einträge nur auflisten müssen, was sich vom Org-Standard unterscheidet. Die Zusammenführungsregeln hängen vom Schlüsseltyp ab:
399
400* **Zulassungslisten**: `availableModels` und `permissions.allow`. Die Liste einer spezifischen Richtlinie ersetzt die Basis vollständig.
401* **Ablehnungslisten und Hook-Arrays**: `permissions.deny`, `permissions.ask`, `disabledMcpjsonServers`, `deniedMcpServers`, `blockedMarketplaces` und jedes `hooks`-Event-Typ-Array. Diese nehmen die Vereinigung von Basis und Richtlinie, sodass ein Org-weiter Ablehnungs- oder Audit-Hook nicht versehentlich durch eine Pro-Rollen-Überschreibung gelöscht werden kann.
402* **Record-typisierte Schlüssel**: `env`, `modelOverrides` und `skillOverrides`. Diese flach-zusammenführen, sodass ein Pro-Rollen-`env`-Block Schlüssel überschreibt, die er setzt, und den Rest von der Basis erbt.
403
404`availableModels` wird auch Server-seitig unter `/v1/messages` durchgesetzt, sodass ein abgelehntes Modell `400` zurückgibt, unabhängig davon, was der Client sendet.
405
406| Matcher | Verhalten |
407| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
408| `match: {}` | Passt zu jedem authentifizierten Benutzer. Beginnen Sie mit einem davon und fügen Sie später Gruppen-gesteuerter Richtlinien darüber hinzu. |
409| `match: { groups: [a, b] }` | Passt, wenn der JWT-`groups`-Anspruch eine der aufgelisteten Gruppen enthält. Groß-/Kleinschreibung beachtet: Gruppen müssen die genaue Groß-/Kleinschreibung des IdP abgleichen. |
410| `match: { email_domain: example.com }` | Passt den Teil nach dem letzten `@` im JWT-`email`-Anspruch, Groß-/Kleinschreibung ignoriert. Akzeptiert eine Domäne pro Richtlinie. |
411| `match: { groups: [a], email_domain: example.com }` | Beide Bedingungen müssen passen |
412
413Ein authentifizierter Benutzer, der keine Richtlinie passt, erhält die Gateway-Standardwerte, was bedeutet, jedes Modell im Katalog und keine verwalteten Einstellungen. Fügen Sie einen `match: {}`-Catch-All zuletzt hinzu, wenn Sie eine garantierte Standard-Richtlinie möchten.
414
415<Note>
416 Das Gateway führt kein eigenes Benutzerverzeichnis. Es autorisiert jede Anfrage vom IdP-Token des Benutzers, liest die Gruppenmitgliedschaft vom `groups`-Anspruch des Tokens und wertet Richtlinien dagegen aus. Es gibt kein Roster zum Aufzählen und keine Konten zum Vorerstellen, und daher keinen SCIM-Endpunkt, da es nichts gibt, das SCIM hinein synchronisieren könnte.
417
418 Führen Sie Benutzer- und Gruppen-Lebenszyklusverwaltung an der Quelle der Wahrheit durch, die der native SCIM-Bereitstellung Ihres IdP oder eine dedizierte Identitäts-Governance-Plattform ist. Mitgliedschaft und Bereitstellung, die dort regiert werden, fließen automatisch durch den Token in das Gateway. Wenn Sie SCIM-Bereitstellung von Claude-Konten selbst möchten, das ist eine [Claude for Enterprise](/de/admin-setup)-Fähigkeit.
419
420 Zwei Ausbreitungsuhren gelten:
421
422 * **Richtlinieninhalt**: Das Bearbeiten einer Richtlinie und das erneute Bereitstellen erreichen verbundene Clients bei ihrer nächsten verwalteten Einstellungsabfrage, innerhalb einer Stunde
423 * **Gruppenmitgliedschaft**: Das Ändern der Gruppenmitgliedschaft eines Benutzers ändert, welche Richtlinie ihn passt. Dies tritt bei der nächsten Session-Neuerstellung in Kraft, was die nächste stille Aktualisierung bedeutet, begrenzt durch `session.ttl_hours`.
424</Note>
425
426<h4 id="what-goes-in-cli">
427 Was geht in `cli`
428</h4>
429
430Jeder `cli`-Wert ist ein vollständiges Claude Code `managed-settings.json`-Dokument, das gleiche Schema, das Sie über MDM oder `/etc/claude-code/managed-settings.json` bereitstellen würden, hier als YAML ausgedrückt. Die CLI wendet das bereitgestellte Dokument auf der verwalteten Ebene an, über Benutzer- und Projekteinstellungen.
431
432Das Gateway validiert jedes Dokument beim Start gegen das Einstellungsschema der CLI, sodass ein nicht erkannter Top-Level-Schlüssel oder ein erkannter Schlüssel mit einem fehlgeformten Wert beim Start mit einem Fehler fehlschlägt, der jeden fehlerhaften Schlüssel benennt. Absichtlich offene Teile des Schemas akzeptieren immer noch beliebige Werte, da neuere Clients Einträge erkennen können, die das Gateway-Schema nicht erkennt. Diese offenen Schlüssel sind `env`, `pluginConfigs` und Schlüssel, die unter `permissions` verschachtelt sind.
433
434Da die Validierung das Schema verwendet, das mit der installierten Version des Gateways gebündelt ist, erfordert das Einfügen eines Top-Level-Einstellungsschlüssels, der von einer neueren Claude Code-Version eingeführt wurde, in verwaltete Konfiguration, das Gateway zuerst zu aktualisieren. Rauchtesten Sie eine neue Richtlinie auf einem Client, bevor Sie sie ausrollen.
435
436Die vollständige Schlüsselreferenz ist in [Claude Code-Einstellungen](/de/settings#available-settings). Die Schlüssel, die Operatoren zuerst erreichen:
437
438```yaml theme={null}
439managed:
440 policies:
441 - match: {}
442 cli:
443 # Modellzugriff (auch Server-seitig unter /v1/messages durchgesetzt)
444 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
445
446 # Berechtigungsrichtlinie
447 permissions:
448 deny:
449 - "WebFetch"
450 - "Read(./.env)"
451 - "Read(./secrets/**)"
452 disableBypassPermissionsMode: disable # blockiert --dangerously-skip-permissions
453 allowManagedPermissionRulesOnly: true # ignoriert Benutzer-/Projektberechtigungsregeln
454
455 # Umgebung in den CLI-Prozess gepusht. DISABLE_UPDATES blockiert
456 # Hintergrund- und manuelle Updates; DISABLE_AUTOUPDATER stoppt nur
457 # Hintergrund-Updates.
458 env:
459 DISABLE_UPDATES: "1" # pin-Versionen über Ihre eigene Verteilung
460
461 # Org-weite Hooks. Hook-Befehle laufen auf Entwicklermaschinen, nicht dem
462 # Gateway, sodass der Pfad auf jedem Client-OS in der Richtlinie existieren muss.
463 hooks:
464 PostToolUse:
465 - matcher: "Edit|Write"
466 hooks:
467 - { type: command, command: /usr/local/bin/audit-edit.sh }
468```
469
470| Schlüssel | Durchgesetzt von | Effekt |
471| ------------------------------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
472| `availableModels` | Gateway + CLI | Modell-Zulassungsliste. Auch unter `/v1/messages` überprüft, sodass ein gepatchter Client ihn nicht umgehen kann. |
473| `permissions.allow` / `.deny` | CLI | Tool- und Befehlsregeln. Siehe [Berechtigungen](/de/permissions). |
474| `permissions.disableBypassPermissionsMode` | CLI | Setzen Sie auf `disable`, um [`bypassPermissions`](/de/permission-modes#skip-all-checks-with-bypasspermissions-mode), den Modus, der jeden Tool-Aufruf auto-genehmigt, und das `--dangerously-skip-permissions`-Flag zu blockieren |
475| `allowManagedPermissionRulesOnly` | CLI | Wenn `true`, werden Benutzer- und Projektberechtigungsregeln ignoriert; nur Regeln aus diesem Dokument gelten |
476| `env` | CLI | Umgebungsvariablen, die in den CLI-Prozess zusammengeführt werden. Verwenden Sie für Telemetrie, Auto-Update und Modellnamen-Überschreibungen. |
477| `hooks` | CLI | Org-weite [Hooks](/de/hooks) |
478
479Da diese Einstellungen über das Netzwerk ankommen, zeigt die CLI jedem Entwickler einen einmaligen Sicherheitsgenehmigungsdialog, bevor etwas angewendet wird, das einen Shell-Befehl ausführen oder ändern kann, wohin Traffic geht. Der Dialog behandelt:
480
481* `hooks`
482* `env`-Variablen, die nicht auf der sicheren Liste der CLI sind
483* Shell-Ausführungseinstellungen wie `apiKeyHelper` und `statusLine`
484* verwalteter CLAUDE.md-Inhalt
485
486Die sichere Liste bestimmt, welche `env`-Variablen ohne Genehmigung gelten:
487
488* **Auf der sicheren Liste**: Auto-Update und Modellnamen-Variablen
489* **Nicht auf der sicheren Liste**: Proxy-Variablen, Base-URL-Variablen und `OTEL_EXPORTER_OTLP_ENDPOINT`
490
491Die [Telemetrie](#telemetry)-Konfiguration des Gateways pusht `OTEL_EXPORTER_OTLP_ENDPOINT`, sodass das Setzen von `telemetry.forward_to` den Dialog bei jedem interaktiven Client auslöst. Nicht-interaktive Läufe mit dem `-p`-Flag überspringen den Dialog und wenden Einstellungen ohne Genehmigung an. Der Dialog schützt die Maschine des Entwicklers vor einem kompromittierten oder feindseligem Gateway, nicht die Organisation vor dem Entwickler, sodass der `-p`-Skip absichtlich statt eine Lücke ist.
492
493Wenn ein Entwickler ablehnt, beendet Claude Code statt die Richtlinie anzuwenden. Das Pushen eines neuen Hooks oder einer nicht-sicheren Env-Variable zu einer breiten Richtlinie bedeutet daher eine Genehmigungsaufforderung bei jedem passenden Entwickler beim nächsten Start.
494
495Der `cli`-Schlüssel wurde in früheren Releases `settings` genannt. Diese Schreibweise wird immer noch als Alias akzeptiert, aber neue Bereitstellungen sollten `cli` verwenden.
496
497<h4 id="precedence-with-other-managed-sources">
498 Vorrang mit anderen verwalteten Quellen
499</h4>
500
501Wenn ein Gerät auch eine lokale `managed-settings.json` oder MDM-bereitgestellte Richtlinie hat, werden die verwalteten Quellen nicht zusammengeführt. Die höchste Prioritätsquelle stellt alle Richtlinieneinstellungen bereit, in dieser Reihenfolge mit höchster Priorität zuerst:
502
5031. Der [Richtlinien-Helper](/de/settings#compute-managed-settings-with-a-policy-helper)
5042. Gateway-bereitgestellte Einstellungen
5053. MDM, über die HKLM-Registrierung unter Windows oder eine plist unter macOS
5064. Die `managed-settings.json`-Datei
5075. Die HKCU-Registrierung, nur unter Windows
508
509Einbettungs-Hosts können Richtlinie durch die SDK-`managedSettings`-Option bereitstellen. Sie wird standardmäßig ignoriert und gilt nur, wenn eine verwaltete Quelle sich mit [`parentSettingsBehavior: "merge"`](/de/settings#available-settings) anmeldet, gefiltert, sodass sie Richtlinie straffen, aber nicht lockern kann.
510
511Die Ausnahme ist eine kleine Menge von Cross-Source-Schlüsseln, die geehrt werden, wenn eine Admin-Quelle sie setzt; die Benutzer-schreibbare HKCU-Ebene ist ausgeschlossen:
512
513* `sandbox.network.allowManagedDomainsOnly` und `sandbox.filesystem.allowManagedReadPathsOnly`: wenn gesperrt, werden die entsprechenden Zulassungslisten über Quellen vereinigt
514* [`allowAllClaudeAiMcps`](/de/settings#available-settings): Zulassung-nur-Überschreibung für die claude.ai MCP-Server-Zulassungsliste
515* `sandbox.bwrapPath` und `sandbox.socatPath`: Dateisystempfade zu den [Sandbox](/de/sandboxing)-Helper-Binärdateien
516
517`allowManagedPermissionRulesOnly` und `disableBypassPermissionsMode` sind nicht Cross-Source, sodass nur der Wert der gewinnenden Quelle gilt.
518
519Gateway-Richtlinien gelten für jeden Claude Code-Aufruf auf der Maschine, einschließlich nicht-interaktiver `claude -p`-Läufe und Sessions, die vom Agent SDK erzeugt werden. Wenn das Gateway beim Start nicht erreichbar ist, beenden sich angemeldete Sessions mit einem Fehler, anstatt ohne ihre Richtlinie zu laufen.
520
521<Warning>
522 `mcpServers` innerhalb eines Richtlinien-`cli`-Blocks wird beim Gateway-Start abgelehnt. Pro-Gruppen-MCP-Verteilung ist nicht verfügbar; stellen Sie MCP-Server über die dateibasierte `managed-mcp.json` auf jedem Gerät bereit oder lassen Sie Entwickler sie lokal hinzufügen.
523</Warning>
524
525<h3 id="telemetry">
526 `telemetry`
527</h3>
528
529Die CLI sendet OpenTelemetry Protocol (OTLP) über HTTP-Metriken, Logs und, wenn aktiviert, Traces an das Gateway, das sie wörtlich an jedes konfigurierte Ziel weiterleitet. Siehe [Überwachung der Nutzung](/de/monitoring-usage) für die Metriken und Ereignisse, die die CLI ausgibt.
530
531Die CLI stempelt jeden Export mit der Identität des authentifizierten Benutzers, gelesen aus dem Gateway-ausgegebenen JWT: die `user.id`-, `user.email`- und `user.groups`-Attribute. Pro-Entwickler-Kosten- und Nutzungszuordnung funktioniert daher ohne Entwickler-seitige Konfiguration.
532
533```yaml theme={null}
534telemetry:
535 forward_to:
536 - url: https://otel-collector.internal.example.com
537 headers:
538 Authorization: ${OTLP_TOKEN}
539 # Pro-Signal-Opt-In. Standard: nur Metriken.
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 Jedes Ziel meldet sich unabhängig in `metrics`, `logs` und `traces` an, und der Standard ist nur Metriken. Die Signale unterscheiden sich in Empfindlichkeit:
550
551 * **Metriken**: Aggregatzähler wie Token-Zähler, Anfragezähler und Latenz
552 * **Logs und Traces**: können vollständige Bash-Befehle, Tool-Eingaben und Dateipfade tragen, die alles abdecken, was Claude Code auf einer Entwicklermaschine tut
553
554 Aktivieren Sie Logs und Traces nur auf Zielen mit den Zugriffskontrolle und Aufbewahrungsrichtlinie, die Daten rechtfertigen.
555</Warning>
556
557Telemetrie ist in der CLI standardmäßig aus. Das Konfigurieren von `telemetry.forward_to` zusammen mit `listen.public_url` schaltet es ein. Das Gateway pusht fünf Env-Variablen an jeden verbundenen Client durch `/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
565Der gepushte Endpunkt wird aus der öffentlichen URL erstellt, sodass Metriken und Logs keine OTEL-Konfiguration von Entwicklern oder Richtlinien benötigen. Die gepushte Konfiguration wird auf der verwalteten Ebene angewendet, überschreibt `OTEL_*`-Variablen, die ein Entwickler lokal setzt.
566
567[Traces](/de/monitoring-usage#traces-beta) erfordern zusätzlich `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` auf jedem Client. Das Gateway pusht diese Variable nicht, also setzen Sie sie durch einen verwalteten Richtlinien-`env`-Block. Sie ist nicht auf der sicheren Liste der CLI, sodass die Bereitstellung durch eine Richtlinie durch den gleichen [Sicherheitsgenehmigungsdialog](#managed) abgedeckt ist, den der gepushte OTLP-Endpunkt bereits auslöst.
568
569Sowohl Protobuf- als auch JSON-OTLP-Codierungen werden weitergeleitet, und jedes OpenTelemetry-kompatible Backend funktioniert als Ziel.
570
571<h3 id="http-tuning">
572 HTTP-Abstimmung
573</h3>
574
575Vier optionale Top-Level-Blöcke, `access_control`, `limits`, `timeouts` und `rate_limits`, stimmen die HTTP-Oberfläche ab. Die Standardwerte passen zu den meisten Bereitstellungen.
576
577| Block | Schlüssel | Standard | Beschreibung |
578| ---------------- | ---------------------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
579| `access_control` | `allow_cidrs` / `deny_cidrs` | leer | Eingehende IP-Zulassung/Ablehnung nach Client-Adresse, nach `trusted_proxies`-Auflösung. `deny_cidrs` wird zuerst überprüft; ein Client, den es passt, wird abgelehnt, auch wenn `allow_cidrs` auch passt. Wenn `allow_cidrs` nicht leer ist, ist das Gateway Standard-Ablehnung. `/healthz` und `/readyz` sind von `allow_cidrs` ausgenommen. |
580| `limits` | `max_request_bytes` | 32 MiB | Max eingehende Anfragebody; übergroße Anfragen erhalten `413`, bevor der Body gepuffert wird. Erhöhen Sie für große Datei- oder Bildanfragen. |
581| `limits` | `max_request_header_bytes` | nicht gesetzt | Wenn gesetzt, geben übergroße Header `431` zurück |
582| `limits` | `max_url_length` | nicht gesetzt | Wenn gesetzt, gibt eine zu lange URL `414` zurück |
583| `timeouts` | `upstream_ttfb_ms` | 120000 | Max Wartezeit für die Response-Header des Upstream (Zeit bis erstes Byte). Der Response-Body streamt dann ohne Wall-Clock-Cap. Gilt für den direkten Anthropic-Upstream-Pfad; Bedrock, Agent Platform und Foundry sind durch die eigenen Timeouts des Provider-SDK begrenzt. |
584| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | Pro-IP-Rate-Limit auf dem nicht authentifizierten Gerätegenehmigungsendpunkt. Erhöhen Sie für eine große Org hinter einer gemeinsamen Egress-IP oder NAT. Diese Limits gelten nur für den Gerätezuschuss-Anmeldungsfluss, nicht für `/v1/messages`-Inferenz. Siehe [Benutzercode-Brute-Force-Widerstand](/de/claude-apps-gateway-deploy#user-code-brute-force-resistance). |
585| `rate_limits` | `device_verify.max` / `.window_seconds` | 10 / 600 | Pro-IP-Rate-Limit auf `user_code`-Einreichungen unter `/device` |
586
587<h2 id="complete-example">
588 Vollständiges Beispiel
589</h2>
590
591Diese vollständige Referenzkonfiguration behandelt jeden Kernabschnitt; die [HTTP-Abstimmungsblöcke](#http-tuning) behalten ihre Standardwerte. Kopieren Sie sie, löschen Sie, was Sie nicht brauchen, und füllen Sie Ihre Werte aus. Die Konfiguration im [Schnellstart](/de/claude-apps-gateway#quickstart) ist eine minimale Version davon.
592
593```yaml gateway.yaml theme={null}
594# Laufen mit:
595# claude gateway --config gateway.yaml
596#
597# Operatives Log-Verbosity wird durch die Umgebungsvariable CLAUDE_GATEWAY_LOG_LEVEL
598# gesteuert (info | warn | error; Standard info). Sie beeinflusst nicht
599# Audit-Ereignisse, die immer ausgegeben werden.
600
601listen:
602 host: 0.0.0.0
603 port: 8080
604 public_url: https://claude-gateway.internal.example.com
605 # Lassen Sie den tls-Block weg, wenn Sie hinter einem TLS-beendenden Ingress laufen.
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 # Erforderlich, wenn der Aussteller der Okta-Org-Server ist, dessen id_tokens
619 # E-Mail und Gruppen auslassen können; das Gateway füllt sie von /userinfo.
620 userinfo_fallback: true
621 # allowed_groups: [claude-code-users]
622 # Okta gibt Gruppen nur aus, wenn der `groups`-Bereich angefordert wird und die
623 # App-Gruppenanspruchsfilter sie erlauben. Die Contractor-Richtlinie unten
624 # passt auf Gruppen, also wird der Bereich hier angefordert.
625 scopes: [openid, profile, email, offline_access, groups]
626 # extra_auth_params: { access_type: offline, prompt: consent } # Google
627 # groups_claim: groups # Entra-App-Rollen: verwenden Sie `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# Aktiviert /v1/organizations/spend_limits (spiegelt die Anthropic Admin API)
639# und Pro-Entwickler-Ausgabendurchsetzung auf /v1/messages. Lassen Sie weg, um zu deaktivieren.
640# Caps selbst werden über die Admin API gesetzt, nicht hier.
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 # Beschränken Sie die Standard-Picker-Option auf availableModels statt
698 # der Tier-Standard, sodass Contractors keinen 400 auf dem Standard erhalten.
699 enforceAvailableModels: true
700 # allow genehmigt diese Tools automatisch; es blockiert nicht den Rest.
701 # Fügen Sie deny-Regeln hinzu, um Tools zu beschränken.
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 Client-seitige verwaltete Einstellungen
720</h2>
721
722Alles oben konfiguriert den Gateway-Server. Das Zeigen von Entwicklermaschinen darauf wird separat auf jedem Gerät durch Claude Code's [verwaltete Einstellungen](/de/settings#settings-files) konfiguriert. Das Gateway kann diese Schlüssel nicht selbst pushen, da sie dem Client sagen, wo das Gateway ist.
723
724Für die CLI setzen Sie beide Schlüssel in die Pro-OS `managed-settings.json`:
725
726```json theme={null}
727{
728 "forceLoginMethod": "gateway",
729 "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com"
730}
731```
732
733Stellen Sie diese Datei auf jedem Gerät bereit, typischerweise über Ihre MDM-Plattform. Der Dateipfad unterscheidet sich je nach Plattform:
734
735| Plattform | Pfad |
736| ------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
737| macOS | `/Library/Application Support/ClaudeCode/managed-settings.json`, oder die `com.anthropic.claudecode` verwaltete Präferenzen-Domäne |
738| Linux und WSL | `/etc/claude-code/managed-settings.json` |
739| Windows | `C:\Program Files\ClaudeCode\managed-settings.json`, oder Gruppenrichtlinie über die HKLM-Registrierung |
740
741`forceLoginGatewayUrl` und der `"gateway"`-Wert von `forceLoginMethod` werden nur von der Admin-kontrollierten verwalteten Ebene geehrt. Ein Entwickler, der sie in seinen eigenen `~/.claude/settings.json` setzt, hat keine Auswirkung.
742
743<h2 id="related">
744 Verwandt
745</h2>
746
747* [Claude Apps Gateway-Übersicht](/de/claude-apps-gateway): Schnellstart und Entwickler-Verbindung
748* [Bereitstellungsleitfaden](/de/claude-apps-gateway-deploy): IdP-Setup, Container-Image, Kubernetes und Cloud Run sowie Operationen
749* [Ausgabenlimits](/de/claude-apps-gateway-spend-limits): Pro-Entwickler-Caps und die Admin API
