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, der eine minimale funktionierende Konfiguration erstellt und ausführt. Sobald Sie eine Konfiguration haben, mit der Sie zufrieden sind, behandelt der Bereitstellungsleitfaden die Containerisierung und das Hosting auf Kubernetes, Cloud Run oder Ihrer eigenen Plattform.
Das 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.
Das vollständige Beispiel am Ende dieser Seite behandelt jeden Abschnitt.
Dateistruktur
Fünf Abschnitte sind erforderlich. Jeder andere Abschnitt ist optional, 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. Erforderliche Abschnitte:listen: Bindungsadresse, öffentliche URL, TLS-Beendigungoidc: Ihr Identitätsanbieter (IdP), einschließlich Aussteller, Client, Anspruchszuordnung und wer sich anmelden darfsession: die Bearer-Token, die das Gateway ausstellt, mit Geheimnis und Lebensdauerstore: PostgreSQL, für Gerätezuschüsse und Rate-Limit-Zählerupstreams: wohin Inferenz geht, ob Anthropic, Bedrock, Agent Platform oder Foundry
admin: Admin-API-Authentifizierung und Aufbewahrung für Ausgabenlimitsenforcement: Ausgabenlimit-Verhalten bei Fehler-offen oder Fehler-geschlossenmodelsundauto_include_builtin_models: von Admin kuratierte Modellliste und Pro-Upstream-IDsmanaged: verwaltete Einstellungsrichtlinien nach IdP-Gruppetelemetry: OTLP-Weiterleitung an Ihren Observability-Stackaccess_control,limits,timeouts,rate_limits: IP-Zulassung/Ablehnung, Anfragegrößenbeschränkungen, Upstream-Zeit-bis-erstes-Byte und Pro-IP-Anmeldungslimits
Geheimniserweiterung
Schreiben Sie Geheimnisse wieclient_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:
| Formular | Wird aufgelöst zu | Verwenden für |
|---|---|---|
${VAR} | Die Umgebungsvariable VAR. Der Start schlägt fehl, wenn nicht definiert. | Container-Umgebungsvariablen, AWS Secrets Manager über Env-Injektion |
${file:/path} | Dateiinhalt, gekürzt | Kubernetes Secret-Volume-Mounts, Vault Agent, SOPS |
Erforderliche Abschnitte
listen
Der listen-Block steuert, wo das Gateway bereitgestellt wird: die Bindungsadresse und der Port, der extern sichtbare Ursprung und optionale TLS-Beendigung.
| Feld | Erforderlich | Beschreibung |
|---|---|---|
host | Nein | Bindungsadresse. Standard 0.0.0.0. |
port | Nein | Bindungsport. Standard 8080. |
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 zu aktivieren, da das Gateway den OTLP-Endpunkt, den es an Clients pusht, aus dieser URL erstellt. |
tls.cert / tls.key | Nein | PEM-Pfade, wenn das Gateway selbst TLS beendet |
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. |
oidc
OpenID Connect (OIDC) ist das SSO-Protokoll, das das Gateway mit Ihrem Identitätsanbieter verwendet; siehe Identitätsanbieter-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.
| Feld | Erforderlich | Beschreibung |
|---|---|---|
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 abgelehnt, es sei denn, CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 ist in der Gateway-Umgebung gesetzt. |
client_id / client_secret | Ja | Aus Ihrer OAuth-Client-Registrierung |
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. |
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. |
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. |
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. |
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. |
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 für Pro-IdP-Bereich-Rezepte wie Googles Aktualisierungstoken-Fluss. |
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. |
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. |
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. |
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. |
token_endpoint_auth_method | Nein | Überschreiben Sie die Token-Endpunkt-Authentifizierungsmethode. Akzeptiert client_secret_basic oder client_secret_post. Standardmäßig automatisch ausgehandelt. |
id_token_signed_response_alg | Nein | Erwarteter id_token-Signaturalgorithmus. Standard RS256. Setzen Sie für IdPs, die mit ES256, PS256 oder EdDSA signieren. |
additional_authorized_parties | Nein | Zusätzliche azp-Werte, die neben client_id akzeptiert werden, für Keycloak-Broker und Token-Exchange-Flüsse |
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. |
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. |
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. |
session
Der session-Block formt die Bearer-Token, die das Gateway nach der Anmeldung ausstellt: das Geheimnis, das sie signiert, und wie lange sie leben.
| Feld | Erforderlich | Beschreibung |
|---|---|---|
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. |
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. |
store
Der store-Block zeigt das Gateway auf seine PostgreSQL-Datenbank, die Gerätezuschüsse und Rate-Limit-Zähler enthält.
| Feld | Erforderlich | Beschreibung |
|---|---|---|
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 und Postgres. |
username | Nein | Überschreibt den Benutzer in postgres_url |
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. |
max_connections | Nein | Postgres-Verbindungspool-Größe pro Replik. Standard 5, was konservativ und freundlich zu gemeinsamen Datenbanken ist. Mit Ausgabenlimits 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. |
postgres_url auf einen Wegwerf-Postgres-Container, zum Beispiel docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres.
upstreams
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.
Bedrock-, 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
Der minimale Anthropic-Upstream ist ein API-Schlüssel aus der Claude Console:api_key: sendetx-api-key. Rotieren Sie ihn in der Claude Console und aktualisieren Sie die Env-Variable.oauth_token: sendetAuthorization: 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.
Amazon Bedrock
Für die Client-seitige Bedrock-Bereitstellung, die das Gateway ersetzt oder frontet, siehe Claude Code on Amazon Bedrock. Der Gateway-seitige Upstream: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.
| Setup | Wie |
|---|---|
| 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.*. |
| 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. |
| 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. |
| ECS / EC2 | Hängen Sie die IAM-Rolle an die Task-Definition oder das Instance-Profil an. auth: {} nimmt es auf. |
| Ü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 |
| 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:-Block mit den richtigen Pro-Upstream-IDs hinzu. |
Google Cloud Agent Platform
Für das äquivalente Client-seitige Setup siehe Claude Code on Google Cloud. Der Gateway-seitige Upstream: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.
Setzen Sie region: global, um Agent Platforms globalen Endpunkt 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.
| Setup | Wie |
|---|---|
| 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). |
| 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. |
| 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. |
| Cloud Run / GCE | Setzen Sie das Service-Account des Service auf eines mit roles/aiplatform.user. auth: {} nimmt es auf. |
| Ü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. |
Microsoft Foundry
Für die Client-seitige Foundry-Bereitstellung siehe Claude Code on Microsoft Foundry. Der Gateway-seitige Upstream: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.
| Setup | Wie |
|---|---|
| RBAC | Gewähren Sie dem Gateway-Identity Azure AI User oder Cognitive Services User auf der Foundry-Ressource |
| Bereitstellungen | Foundry verwendet von Admin gewählte Bereitstellungsnamen, nicht kanonische Modell-IDs. Fügen Sie einen models:-Block hinzu, der jede kanonische ID Ihrem Bereitstellungsnamen zuordnet. |
| 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. |
| ACI / App Service | Aktivieren Sie system-zugewiesene oder user-zugewiesene Managed Identity auf der Ressource. use_azure_ad: true nimmt es auf. |
| Überall sonst | auth: { api_key: "${FOUNDRY_API_KEY}" }. Zitieren Sie ${…} innerhalb von { }. |
Mehrere Upstreams
Derselbe Anbieter kann mehr als einmal mit einem unterschiedlichenname: erscheinen. Dies deckt verschiedene Regionen, verschiedene Konten über verschiedene Berechtigungsketten, bereitgestellter Durchsatz versus On-Demand und Cross-Provider-Fallback ab.
Das 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.
Dieses 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:
| Hebel | Wie |
|---|---|
| Verschiedene Regionen | Ein Bedrock-Upstream pro Region, jeder mit seiner eigenen region:. Mit auto_include_builtin_models: true routen die Cross-Region-Inferenz-Profile automatisch; für Region-gepinnte Bereitstellungen verwenden Sie einen models:-Block. |
| 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. |
| 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. |
| VPC / FIPS-Endpunkte | Setzen Sie base_url: auf dem Upstream auf Ihren VPC-Endpunkt oder FIPS-Endpunkt-URL |
| 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. |
Optionale Abschnitte
admin
Optional. Aktiviert /v1/organizations/spend_limits, das Anthropics öffentliche Admin API spiegelt, und Pro-Entwickler-Ausgabendurchsetzung auf /v1/messages. Siehe Ausgabenlimits für wie Caps gesetzt und durchgesetzt werden; dieser Abschnitt behandelt die gateway.yaml-Schlüssel, die die Funktion aktivieren und sie abstimmen.
| Feld | Erforderlich | Beschreibung |
|---|---|---|
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; ids müssen über read_keys und write_keys eindeutig sein. |
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 und /audit. |
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. |
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. |
audit_retention_days | Nein | Standard 365. Ältere admin_audit-Zeilen werden gefegt. |
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. |
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. |
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. |
enforcement
Der enforcement-Block steuert, wie Ausgabenlimit-Prüfungen sich verhalten, wenn der Store nicht verfügbar ist.
| Feld | Erforderlich | Beschreibung |
|---|---|---|
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:-Block. |
models
Der 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.
managed
Der 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.
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:
- Zulassungslisten:
availableModelsundpermissions.allow. Die Liste einer spezifischen Richtlinie ersetzt die Basis vollständig. - Ablehnungslisten und Hook-Arrays:
permissions.deny,permissions.ask,disabledMcpjsonServers,deniedMcpServers,blockedMarketplacesund jedeshooks-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. - Record-typisierte Schlüssel:
env,modelOverridesundskillOverrides. Diese flach-zusammenführen, sodass ein Pro-Rollen-env-Block Schlüssel überschreibt, die er setzt, und den Rest von der Basis erbt.
availableModels wird auch Server-seitig unter /v1/messages durchgesetzt, sodass ein abgelehntes Modell 400 zurückgibt, unabhängig davon, was der Client sendet.
| Matcher | Verhalten |
|---|---|
match: {} | Passt zu jedem authentifizierten Benutzer. Beginnen Sie mit einem davon und fügen Sie später Gruppen-gesteuerter Richtlinien darüber hinzu. |
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. |
match: { email_domain: example.com } | Passt den Teil nach dem letzten @ im JWT-email-Anspruch, Groß-/Kleinschreibung ignoriert. Akzeptiert eine Domäne pro Richtlinie. |
match: { groups: [a], email_domain: example.com } | Beide Bedingungen müssen passen |
match: {}-Catch-All zuletzt hinzu, wenn Sie eine garantierte Standard-Richtlinie möchten.
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.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-Fähigkeit.Zwei Ausbreitungsuhren gelten:- Richtlinieninhalt: Das Bearbeiten einer Richtlinie und das erneute Bereitstellen erreichen verbundene Clients bei ihrer nächsten verwalteten Einstellungsabfrage, innerhalb einer Stunde
- 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.
Was geht in cli
Jeder 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.
Das 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.
Da 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.
Die vollständige Schlüsselreferenz ist in Claude Code-Einstellungen. Die Schlüssel, die Operatoren zuerst erreichen:
| Schlüssel | Durchgesetzt von | Effekt |
|---|---|---|
availableModels | Gateway + CLI | Modell-Zulassungsliste. Auch unter /v1/messages überprüft, sodass ein gepatchter Client ihn nicht umgehen kann. |
permissions.allow / .deny | CLI | Tool- und Befehlsregeln. Siehe Berechtigungen. |
permissions.disableBypassPermissionsMode | CLI | Setzen Sie auf disable, um bypassPermissions, den Modus, der jeden Tool-Aufruf auto-genehmigt, und das --dangerously-skip-permissions-Flag zu blockieren |
allowManagedPermissionRulesOnly | CLI | Wenn true, werden Benutzer- und Projektberechtigungsregeln ignoriert; nur Regeln aus diesem Dokument gelten |
env | CLI | Umgebungsvariablen, die in den CLI-Prozess zusammengeführt werden. Verwenden Sie für Telemetrie, Auto-Update und Modellnamen-Überschreibungen. |
hooks | CLI | Org-weite Hooks |
hooksenv-Variablen, die nicht auf der sicheren Liste der CLI sind- Shell-Ausführungseinstellungen wie
apiKeyHelperundstatusLine - verwalteter CLAUDE.md-Inhalt
env-Variablen ohne Genehmigung gelten:
- Auf der sicheren Liste: Auto-Update und Modellnamen-Variablen
- Nicht auf der sicheren Liste: Proxy-Variablen, Base-URL-Variablen und
OTEL_EXPORTER_OTLP_ENDPOINT
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.
Wenn 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.
Der cli-Schlüssel wurde in früheren Releases settings genannt. Diese Schreibweise wird immer noch als Alias akzeptiert, aber neue Bereitstellungen sollten cli verwenden.
Vorrang mit anderen verwalteten Quellen
Wenn ein Gerät auch eine lokalemanaged-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:
- Der Richtlinien-Helper
- Gateway-bereitgestellte Einstellungen
- MDM, über die HKLM-Registrierung unter Windows oder eine plist unter macOS
- Die
managed-settings.json-Datei - Die HKCU-Registrierung, nur unter Windows
managedSettings-Option bereitstellen. Sie wird standardmäßig ignoriert und gilt nur, wenn eine verwaltete Quelle sich mit parentSettingsBehavior: "merge" anmeldet, gefiltert, sodass sie Richtlinie straffen, aber nicht lockern kann.
Die 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:
sandbox.network.allowManagedDomainsOnlyundsandbox.filesystem.allowManagedReadPathsOnly: wenn gesperrt, werden die entsprechenden Zulassungslisten über Quellen vereinigtallowAllClaudeAiMcps: Zulassung-nur-Überschreibung für die claude.ai MCP-Server-Zulassungslistesandbox.bwrapPathundsandbox.socatPath: Dateisystempfade zu den Sandbox-Helper-Binärdateien
allowManagedPermissionRulesOnly und disableBypassPermissionsMode sind nicht Cross-Source, sodass nur der Wert der gewinnenden Quelle gilt.
Gateway-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.
telemetry
Die 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 für die Metriken und Ereignisse, die die CLI ausgibt.
Die 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.
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:
CLAUDE_CODE_ENABLE_TELEMETRY=1OTEL_METRICS_EXPORTER=otlpOTEL_LOGS_EXPORTER=otlpOTEL_TRACES_EXPORTER=otlpOTEL_EXPORTER_OTLP_ENDPOINT=<public_url>
OTEL_*-Variablen, die ein Entwickler lokal setzt.
Traces 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 abgedeckt ist, den der gepushte OTLP-Endpunkt bereits auslöst.
Sowohl Protobuf- als auch JSON-OTLP-Codierungen werden weitergeleitet, und jedes OpenTelemetry-kompatible Backend funktioniert als Ziel.
HTTP-Abstimmung
Vier 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.
| Block | Schlüssel | Standard | Beschreibung |
|---|---|---|---|
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. |
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. |
limits | max_request_header_bytes | nicht gesetzt | Wenn gesetzt, geben übergroße Header 431 zurück |
limits | max_url_length | nicht gesetzt | Wenn gesetzt, gibt eine zu lange URL 414 zurück |
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. |
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. |
rate_limits | device_verify.max / .window_seconds | 10 / 600 | Pro-IP-Rate-Limit auf user_code-Einreichungen unter /device |
Vollständiges Beispiel
Diese vollständige Referenzkonfiguration behandelt jeden Kernabschnitt; die HTTP-Abstimmungsblöcke behalten ihre Standardwerte. Kopieren Sie sie, löschen Sie, was Sie nicht brauchen, und füllen Sie Ihre Werte aus. Die Konfiguration im Schnellstart ist eine minimale Version davon.gateway.yaml
Client-seitige verwaltete Einstellungen
Alles oben konfiguriert den Gateway-Server. Das Zeigen von Entwicklermaschinen darauf wird separat auf jedem Gerät durch Claude Code’s verwaltete Einstellungen konfiguriert. Das Gateway kann diese Schlüssel nicht selbst pushen, da sie dem Client sagen, wo das Gateway ist. Für die CLI setzen Sie beide Schlüssel in die Pro-OSmanaged-settings.json:
| Plattform | Pfad |
|---|---|
| macOS | /Library/Application Support/ClaudeCode/managed-settings.json, oder die com.anthropic.claudecode verwaltete Präferenzen-Domäne |
| Linux und WSL | /etc/claude-code/managed-settings.json |
| Windows | C:\Program Files\ClaudeCode\managed-settings.json, oder Gruppenrichtlinie über die HKLM-Registrierung |
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.
Verwandt
- Claude Apps Gateway-Übersicht: Schnellstart und Entwickler-Verbindung
- Bereitstellungsleitfaden: IdP-Setup, Container-Image, Kubernetes und Cloud Run sowie Operationen
- Ausgabenlimits: Pro-Entwickler-Caps und die Admin API