Bereitstellung und Betrieb des Claude-Apps-Gateways

Planen Sie zuerst das Netzwerk Ihres Gateways. Bei der Anmeldung lehnt Claude Code ein Claude-Apps-Gateway ab, dessen Hostname zu einer öffentlichen IP-Adresse aufgelöst wird, selbst wenn diese aus dem Internet nicht erreichbar ist.Ein Claude-Apps-Gateway kann Einstellungen auf die Rechner der Benutzer pushen, einschließlich Hooks, die Shell-Befehle ausführen. Die Prüfung hilft zu verhindern, dass sich Benutzer versehentlich bei einem bösartigen Gateway im öffentlichen Internet anmelden. Halten Sie auch Ihr eigenes Gateway vom Internet fern.Wählen Sie die Adresse des Gateways, bevor Sie entscheiden, wo es läuft. In der Regel ist das eine private Adresse, die Benutzer in Ihrem internen Netzwerk oder über ein VPN erreichen. Wenn Ihr internes Netzwerk öffentliche IPv4-Bereiche verwendet, können Sie einen Bereich angeben, der sowohl das Gateway als auch die Rechner Ihrer Benutzer umfasst. Claude Code wertet diese Übereinstimmung als Zeichen dafür, dass sich das Gateway in Ihrem internen Netzwerk befindet. Siehe Eine Adresse für das Gateway wählen. Wenn keine der beiden Möglichkeiten zu Ihrem Netzwerk passt, wenden Sie sich an Ihr Anthropic-Account-Team.

Diese Seite behandelt den operativen Aspekt des Betriebs des Claude-Apps-Gateways: Registrierung eines OAuth-Clients bei Ihrem Identitätsanbieter (IdP), Bereitstellung des Gateways als Container und täglicher Betrieb. Für jede Option in der Datei gateway.yaml, die das Gateway beim Start liest, siehe die Konfigurationsreferenz. Eine Produktionsbereitstellung folgt vier Schritten in der richtigen Reihenfolge, und die folgenden Abschnitte entsprechen ihnen. Die ersten beiden sind Stellen, an denen Sie Entscheidungen treffen; die zweiten beiden sind Referenzmaterial, das Sie konsultieren können, sobald es läuft.

Richten Sie Ihren Identitätsanbieter ein: Registrieren Sie den OAuth-Client und überprüfen Sie die IdP-spezifischen Hinweise für Okta, Entra und Google
Stellen Sie das Gateway bereit: Erstellen Sie ein gepinntes Container-Image und führen Sie es auf Kubernetes, Cloud Run oder Ihrer eigenen Plattform aus. Dieser Abschnitt behandelt auch Kosten-, Bypass-, Multi-Gateway- und Serverless-Entscheidungen
Richten Sie den Betrieb ein: Protokolle, Integritätsprüfungen, Ausfallverhalten, Geheimnisrotation und Upgrades. Referenzmaterial für die Einrichtung von Überwachung und Runbooks
Überprüfen Sie die Sicherheitslage: Welche Daten wohin fließen, das Bedrohungsmodell und Compliance-Antworten. Referenzmaterial für eine Sicherheitsüberprüfung

Wenn ein Anmelde- oder Startfehler auftritt, gehen Sie direkt zu Fehlerbehebung, das nach dem Fehler, den Sie sehen, indiziert ist.

Identitätsanbieter-Setup

Registrieren Sie eine vertrauliche OAuth/OpenID Connect (OIDC) Webanwendung mit einem einzelnen Redirect-URI, https://<gateway>/oauth/callback, und weisen Sie sie den Benutzern oder Gruppen zu, die Zugriff auf das Gateway haben sollten. Das Gateway authentifiziert sich beim IdP mit dem Client-Secret der Registrierung oder mit einem Zertifikat, das Sie in die Registrierung hochladen, falls Ihr IdP stattdessen Zertifikat-Anmeldedaten verwendet. Jeder OIDC-konforme IdP funktioniert: Okta, Microsoft Entra ID, Google Workspace, Keycloak, Dex, PingFederate und andere. Der IdP muss drei Anforderungen erfüllen:

Stellt /.well-known/openid-configuration über HTTPS in der Produktion bereit; das Gateway akzeptiert einen http:// Aussteller, und ein Loopback-Aussteller erfordert zusätzlich CLAUDE_GATEWAY_ALLOW_LOOPBACK=1
Unterstützt den Authorization-Code-Flow. PKCE (Proof Key for Code Exchange) ist standardmäßig aktiviert; deaktivieren Sie es mit oidc.use_pkce: false für IdPs, die es nicht unterstützen
Gibt email und optional groups im id_token zurück, oder stellt sie vom Userinfo-Endpoint mit oidc.userinfo_fallback: true bereit

Für private PKI setzen Sie oidc.ca_cert_pem. Einige Anbieter handhaben E-Mail- und Gruppen-Claims unterschiedlich:

Okta: Der Org-Autorisierungsserver unter https://example.okta.com gibt einen dünnen id_token zurück, der email und groups auslässt, daher setzen Sie oidc.userinfo_fallback: true, wenn Sie ihn als issuer verwenden. Ein benutzerdefinierter Autorisierungsserver wie https://example.okta.com/oauth2/default, der email und optional groups im id_token enthält, gibt sie direkt aus und benötigt keinen Fallback. Okta gibt groups nur aus, wenn der groups-Scope in oidc.scopes angefordert wird und der Gruppen-Claim-Filter der App dies zulässt; userinfo_fallback kann einen Claim nicht ausfüllen, nach dem der IdP nicht gefragt wurde.
Microsoft Entra ID: issuer = https://login.microsoftonline.com/<tenant-id>/v2.0. Entra gibt Gruppen-Object-IDs statt Namen aus, daher verwenden Sie die GUIDs in managed.policies.match.groups, oder verwenden Sie App-Rollen für lesbare Namen. Wenn Ihr Mandant Rollen unter roles statt groups ausgibt, setzen Sie oidc.groups_claim: roles.
Google Workspace: issuer = https://accounts.google.com. Googles id_token enthält keine Gruppen. Um gruppenbasierte allowed_groups oder managed.policies mit Google als IdP zu verwenden, konfigurieren Sie oidc.google_groups, das die Gruppen jedes Benutzers über die Admin SDK Directory API mit einem Service-Account mit Domain-Wide-Delegation nachschlägt. Ohne dies verwenden Sie oidc.allowed_email_domains für Mitgliedschafts-Gating und managed.policies.match.email_domain für Richtlinienzuweisung. Google ignoriert auch den Standard-Scope offline_access. Für Refresh-Tokens setzen Sie oidc.scopes: [openid, profile, email] und oidc.extra_auth_params: { access_type: offline, prompt: consent }.

Refresh-Tokens ermöglichen es dem Gateway, die Sitzung eines Entwicklers stillschweigend zu erneuern, ohne den Entwickler zum Browser zu senden. Sie treiben auch die Deprovisioning an, denn wenn der IdP einen Benutzer deaktiviert, schlägt die nächste Aktualisierung fehl und die Sitzung endet innerhalb von ttl_hours. Das Gateway fordert standardmäßig offline_access an, um einen Refresh-Token zu erhalten. Wenn Ihr IdP explizite Zustimmung für Offline-Zugriff erfordert, konfigurieren Sie den OAuth-Client, um dies zu ermöglichen.Wenn Ihr IdP überhaupt keine Refresh-Tokens ausstellen kann, funktioniert das Gateway immer noch, aber es gibt keine stille Erneuerung, daher führen Entwickler die Browser-Anmeldung erneut aus, wenn ihre Sitzung abläuft. Um zu verhindern, dass dies jede Stunde geschieht, erhöhen Sie session.ttl_hours auf 8 oder 12. Der Kompromiss ist die Deprovisioning-Latenz, denn ohne Refresh-Tokens behält ein deaktivierter Benutzer Zugriff, bis die längere TTL abläuft.

Bereitstellung

Das Gateway ist eine einzelne zustandslose Linux-Binärdatei, die sich über Postgres koordiniert. Stellen Sie es so bereit, wie Sie jeden anderen zustandslosen Dienst in Ihrer Umgebung bereitstellen. Halten Sie es in Ihrem Netzwerk, wo Ihre Entwickler es über HTTPS erreichen können und es Ihren IdP erreichen kann, und behandeln Sie es wie jeden anderen Dienst, der Produktionsanmeldedaten hält. Einige Entscheidungen prägen die Bereitstellung über den Ort hinaus, an dem sie läuft:

Kosten: Keine separate Lizenz oder Pro-Sitz-Gebühr. Das Gateway ist Teil der claude-Binärdatei, daher zahlen Sie für Inferenz über Ihr bestehendes Engagement, plus die Berechnung, auf der es läuft.
Bypass: Das Gateway erzwingt nicht, dass die einzige Route zu einem Modell durch es führt. Ein Entwickler mit seinen eigenen Anmeldedaten kann den Anbieter immer noch direkt aufrufen, daher ist das Schließen dieses Pfads eine Netzwerkrichtlinien-Entscheidung, z. B. das Blockieren von Egress zu api.anthropic.com außer vom Gateway. Das Blockieren dieses Egress bricht auch die WebFetch-Domain-Sicherheitsprüfung, die api.anthropic.com von jeder Entwicklermaschine aufruft. Setzen Sie skipWebFetchPreflight: true in der verwalteten Richtlinie, um sie zu deaktivieren.
Mehrere Gateways: Jedes ist eine separate Bereitstellung mit seiner eigenen Konfiguration, und die CLI speichert Vertrauen und Anmeldedaten pro Gateway-Hostname, daher können Teams verschiedene Gateways ohne Konflikte verwenden. Um mehrere OIDC-Aussteller zu bedienen, führen Sie separate Instanzen aus.
Serverless: Cloud Run funktioniert, wenn Sie min-instances: 1 setzen, um kalte OIDC-Erkennung zu vermeiden. Lambda und Cloud Functions funktionieren nicht, da das Gateway ein langlebiger HTTP-Server ist.

Jede Produktionstopologie hier platziert einen L7-Proxy, wie einen Ingress, Cloud Runs Front-End oder einen ALB, vor einfachen HTTP-Replikationen. Setzen Sie listen.trusted_proxies auf die Quellbereiche des Proxys, damit das Gateway Client-IPs aus X-Forwarded-For liest. Das Gateway ehrt den Header nur, wenn der TCP-Peer vertrauenswürdig ist. Die Google Cloud- und AWS-Beispiele haben konkrete Werte pro Topologie. Ohne vertrauenswürdige Proxys scheint jede Anfrage von der IP des Proxys zu kommen, was Pro-IP-Ratenlimits in einen gemeinsamen Bucket zusammenfasst und die IP des Proxys in Audit-Events aufzeichnet. Leiten Sie Anfragen nicht an die Device-Authorization- und Token-Endpunkte des Gateways um, z. B. mit einem HTTP-zu-HTTPS- oder Host-Kanonisierungs-Rewrite am Ingress. Claude Code folgt Umleitungen bei diesen Anfragen nicht, daher bricht eine Ingress-Regel, die sie umleitet, die Anmeldung und Token-Aktualisierung. Geben Sie dem Proxy ein Idle-Timeout, das länger ist als das Keepalive-Intervall des Gateways, das vom Upstream abhängt:

Bei jedem Upstream außer provider: anthropic schreibt das Gateway einen SSE-ping, sobald ein Stream etwa 15 Sekunden lang stumm war.
Bei provider: anthropic leitet das Gateway die Antwort unverändert weiter, einschließlich der eigenen Pings der Anthropic-API.

Ein Standard wie die 60 Sekunden des ALB reichen aus, um einen ruhigen Stream offen zu halten. Das AWS-Beispiel erhöht es ohnehin auf eine Stunde, und seine Troubleshooting-Zeile behandelt Gateways älter als v2.1.229, die während ruhiger Perioden auf den Upstreams, die jetzt Pings erhalten, nichts sendeten.

Adresse für das Gateway wählen

Claude Code akzeptiert die Adresse eines Gateways auf eine von zwei Arten:

Private Adresse: Platzieren Sie das Gateway hinter einem internen Load Balancer oder VPN, mit einem Hostnamen, der nur zu privaten Adressen aufgelöst wird, etwa RFC 1918 oder CGNAT 100.64.0.0/10. Die Rechner der Benutzer können eine beliebige Adresse haben. Die Voraussetzung eines privaten Netzwerks listet die akzeptierten Bereiche auf.
Deklarierter Block: Wenn Ihr internes Netzwerk öffentlichen IPv4-Adressraum verwendet, der Ihrer Organisation gehört, tragen Sie den Block in der verwalteten Einstellung gatewayInternalNetworks ein. Das Gateway und der Rechner des Benutzers müssen sich beide in diesem Block befinden. Siehe Ein Gateway in eigenem öffentlichem Adressraum zulassen.

Wenn kein einzelner Block beide enthält, geben Sie dem Gateway stattdessen eine private Adresse.

Container-Image

Erstellen Sie Ihr eigenes Image um die native claude-Binärdatei aus der Standard-Claude-Code-Version:

Laden Sie den Linux-Build für Ihre Image-Architektur aus einer gepinnten Version herunter; siehe Installieren Sie eine bestimmte Version für die Download-URL.
Überprüfen Sie es gegen die GPG-signierte manifest.json der Version, wie in Binäre Integrität und Code-Signierung beschrieben.
Kopieren Sie es in den Build-Kontext.

Spiegeln Sie die Version in Ihre interne Registry, wenn Ihre Builds den Release-Host nicht erreichen können, und pinnen Sie die Version, die Ihre Flotte ausführt. Über die Binärdatei hinaus benötigt das Image:

Ein glibc-basiertes Image: Die einzigen dynamischen Abhängigkeiten des glibc-Builds sind glibc-Bibliotheken. Musl-basierte Images benötigen den linux-x64-musl- oder linux-arm64-musl-Build, dessen einzige dynamische Abhängigkeit musl ist.
Ein beschreibbares Zustandsverzeichnis: Das Gateway läuft als jeder Benutzer, aber minimale Images haben kein beschreibbares Home. Setzen Sie CLAUDE_CONFIG_DIR auf einen beschreibbaren Pfad wie /tmp/.claude.
Der Container-Befehl: claude gateway --config /etc/claude/gateway.yaml, mit der Konfigurationsdatei schreibgeschützt eingebunden und Geheimnissen als Umgebungsvariablen bereitgestellt; das Gateway lauscht auf listen.port, Standard 8080.

Kubernetes

Führen Sie das Gateway als Deployment aus, wie jeden zustandslosen Dienst:

Binden Sie die Konfiguration von einer ConfigMap und Geheimnisse von einem Secret ein; referenzieren Sie Geheimnisse in der YAML über ${file:/path/to/secret} oder als Umgebungsvariablen
Beenden Sie TLS am Ingress und setzen Sie listen.public_url auf den Ingress-Hostnamen
Zeigen Sie die Readiness-Probe auf GET /readyz und die Liveness-Probe auf GET /healthz

Für ein vollständiges Beispiel auf AWS, das ECS Fargate oder EKS, Amazon RDS und AWS Secrets Manager abdeckt, siehe Bereitstellung auf AWS. Bevorzugen Sie die Workload-Identität der Plattform gegenüber statischen Schlüsseln; die upstreams-Referenz hat Setup-Details pro Plattform. Für eine Cloud-übergreifende Kopplung, wie z. B. einen Amazon-Bedrock-Upstream auf GKE, setzen Sie explizite Anmeldedaten im auth-Block des Upstream statt.

Cloud Run

Konfigurieren Sie den Dienst wie folgt:

Lassen Sie listen.port bei seinem Standard von 8080, das Cloud Runs Standard-PORT entspricht, oder setzen Sie port: ${PORT}
Setzen Sie public_url auf den extern erreichbaren Ursprung. Für die Produktion ist dies normalerweise der Hostname eines internen Load Balancers, da /login öffentliche Adressen ablehnt und die *.run.app-URL zu einer aufgelöst wird, daher funktioniert die Cloud-Run-URL allein nur für einen curl- oder Browser-Smoke-Test. Die Ausnahme ist ein Netzwerk, in dem *.run.app privat über Private Service Connect und eine Cloud-DNS-Private-Zone aufgelöst wird; in dieser Topologie ist die Cloud-Run-URL eine gültige public_url. Das Google-Cloud-Beispiel behandelt beide.
Binden Sie die Konfiguration als Secret-Volume ein
Setzen Sie min-instances: 1, um kalte OIDC-Erkennung bei der ersten Anfrage zu vermeiden

Für ein vollständiges Beispiel auf Google Cloud, das Cloud Run oder GKE, Cloud SQL und Secret Manager abdeckt, siehe Bereitstellung auf Google Cloud.

Pushen Sie die Gateway-URL zu Entwicklermaschinen

Sobald das Gateway bedient wird, pushen Sie forceLoginMethod, forceLoginGatewayUrl und parentSettingsBehavior: "merge" über verwaltete Einstellungen auf jede Entwicklermaschine, über MDM oder durch direktes Schreiben der pro-OS managed-settings.json. Sobald Sie die Schlüssel bereitstellen, stoppt Claude Code die Verwendung eines übrigen API-Schlüssels oder claude.ai-Anmeldung auf der Maschine, daher planen Sie den Push zusammen mit Ihren Anmeldeanweisungen. Administrator-Richtlinie erfordert eine Cloud-Gateway-Anmeldung beschreibt die Meldungen, die Entwickler sehen. Siehe wo jeder Mechanismus die Richtlinie speichert für die Dateipfade und Client-seitige verwaltete Einstellungen für das Claude-Desktop-bootstrapUrl-Äquivalent.

Große Rollouts

Die Anmeldung ist pro Client-IP-Adresse ratenbegrenzt, und die Standards eignen sich für ein kleines Team. Jede Adresse erhält 30 Anmeldestarts und 10 Code-Einreichungen alle 10 Minuten. Ein Rollout für Tausende von Entwicklern kann diese Limits am ersten Morgen aus einem von zwei Gründen erreichen:

Das Gateway kann nicht über Ihren Load Balancer hinaussehen. Ohne listen.trusted_proxies scheint jeder Entwickler von der Adresse des Load Balancers zu kommen und teilt sich ein Limit. Das Gateway protokolliert eine Warnung, wenn es zum ersten Mal einen X-Forwarded-For-Header ignoriert. Wenn der Load Balancer in listen.trusted_proxies gehört, tragen Sie ihn dort ein, bevor Sie irgendetwas anderes ändern. Wenn sich Entwickler danach immer noch eine Adresse teilen, erhöhen Sie rate_limits.
Viele Entwickler teilen sich wenige NAT- oder VPN-Egress-Adressen. Sie teilen sich die Limits dieser Adressen, auch wenn trusted_proxies richtig ist. Erhöhen Sie rate_limits, um zu passen.

Um max zu dimensionieren, teilen Sie die Entwickler durch die Egress-Adressen, die sie teilen. Schätzen Sie, wie viele dieser sich innerhalb einer window_seconds-Periode anmelden, die standardmäßig 10 Minuten beträgt. Verdoppeln Sie es dann, um Wiederholungen und Entwickler abzudecken, die sich sowohl bei Claude Code als auch bei Claude Desktop anmelden. Zum Beispiel melden sich 10.000 Entwickler hinter 4 Egress-Adressen gleichmäßig über eine Stunde an. Das sind 2.500 Entwickler pro Adresse und etwa 420 von ihnen in jeweils 10 Minuten, die Sie verdoppeln und auf 1.000 aufrunden. Das Beispiel unten setzt beide Limits auf 1.000:

rate_limits:
  device_authorization: { max: 1000, window_seconds: 600 }
  device_verify: { max: 1000, window_seconds: 600 }

device_verify ist das, was jemanden daran abhält, den Anmeldecode eines anderen Entwicklers zu erraten, daher erhöhen Sie ihn nur so weit, wie Ihre Schätzung es braucht. Selbst bei diesen Limits ist ein Code 8 Zeichen aus einem 20-Zeichen-Alphabet und läuft nach 10 Minuten ab, daher bleibt das Erraten unpraktisch; siehe Benutzercode-Brute-Force-Widerstand. Wenn Ihr IdP Refresh-Token ausstellt, erneuert Claude Code Sitzungen stillschweigend, daher können Sie das Limit nach dem Rollout zurücksetzen. Ohne Refresh-Token melden sich Entwickler alle session.ttl_hours erneut an. Dimensionieren Sie beide Limits auch für diese stetige Rate und lassen Sie sie erhöht. Wenn ein Limit erreicht wird, zeigt Claude Code v2.1.274 oder später The gateway is limiting sign-in attempts right now. Ein Gateway auf v2.1.274 oder später zeigt Too many attempts came from your network address auf der Verifizierungsseite mit den zu überprüfenden Einstellungen. Es schreibt auch eine sign-in refused-Protokollzeile, die die zu ändernde Einstellung benennt.

Betrieb

Sobald das Gateway Traffic bedient, besteht der tägliche Betrieb darin, seine Logs zu lesen, seinen Zustand zu prüfen und seine Secrets nach Ihrem Zeitplan zu rotieren. Die Unterabschnitte behandeln jeden dieser Punkte sowie, was Postgres speichert und wie sich Upgrades und Rollbacks verhalten.

Logs

Das Gateway schreibt zwei Streams nach stderr, beide JSON-freundlich:

Audit-Ereignisse: einzeiliges JSON pro sicherheitsrelevantem Ereignis. Leiten Sie stderr an Ihren Log-Aggregator weiter. Zu den ausgegebenen Ereignissen gehören config.load, session.mint, session.refresh, device.authorize, device.verify, device.callback, auth.denied, access.denied, access.public_client, inference, managed.serve, desktop_bootstrap.serve, desktop_bootstrap.denied, spend.blocked, admin.denied, admin.limit.upsert und admin.limit.delete. Die Felder variieren je nach Ereignis:
- Erfolgreiche Mint- und Refresh-Ereignisse enthalten sub, email, client_ip und das Ergebnis
- auth.denied und access.denied enthalten den Grund und die Client-IP, bei auth.denied zusätzlich den Anfragepfad, da bei diesen Ablehnungen keine Benutzeridentität existiert. Zwei access.denied-Gründe ändern, was das Ereignis enthält:
  - xff_unparseable: Das Ereignis enthält zusätzlich den X-Forwarded-For-Eintrag, der nicht gelesen werden konnte
  - client_ip_unknown: Das Ereignis enthält keine Client-IP, weil die Verbindung keine Peer-Adresse hatte, während eine access_control-Liste gesetzt war
- access.public_client enthält die Client-IP der ersten Anfrage pro Prozess, die von einer öffentlichen Adresse eintrifft, während access_control.allow_cidrs leer ist. Das Gateway bedient die Anfrage wie gewohnt; das Ereignis signalisiert, dass das Gateway möglicherweise aus dem öffentlichen Internet erreichbar ist. In der access_control-Referenz erfahren Sie, was als öffentlich gilt, und finden die empfohlene Allow-List.
- inference protokolliert, welcher Upstream die Anfrage bedient hat, sowie den Antwortstatus
- desktop_bootstrap.denied protokolliert einen abgelehnten Bootstrap-Abruf von Claude Desktop mit dem Grund (not_configured, policy_not_opted_in oder no_policy_matched) und der Identität des Benutzers
- guardrail.trace protokolliert, welcher Filter ausgelöst wurde, ohne den gefundenen Text
- admin.denied protokolliert einen abgelehnten Authentifizierungsversuch an der Admin-API mit Client-IP, Methode, Pfad und einem Grund, ohne das vorgelegte Schlüsselmaterial: invalid_key, wenn ein x-api-key vorgelegt wurde, der zu keinem konfigurierten Schlüssel passte, bearer_rejected, wenn nur ein Authorization-Header vorgelegt wurde und dieser nicht als Gateway-Sitzung in admin.admin_groups verifiziert werden konnte, oder no_credentials, wenn keiner der beiden Header vorgelegt wurde
Betriebs-Logs: menschenlesbare Zeilen mit dem Präfix [gateway] für Start, Warnungen und Upstream-Fehler. Die Umgebungsvariable CLAUDE_GATEWAY_LOG_LEVEL steuert die Ausführlichkeit und akzeptiert debug, info, warn oder error, wobei info der Standard ist. Bei debug protokolliert jede Anmeldung und jeder Refresh zusätzlich die Namen, nicht die Werte, der Claims im id_token sowie die Namen der Userinfo-Claims, wenn userinfo_fallback welche geliefert hat, sodass Sie die Einstellungen email_claim und groups_claim diagnostizieren können, ohne personenbezogene Daten zu protokollieren. Sie wirkt sich nicht auf Audit-Ereignisse aus, die immer ausgegeben werden.

Betriebs-Logs als JSON schreiben

Wenn Ihr Log-Collector die Stufe jeder Zeile aus einem JSON-Feld liest, setzen Sie CLAUDE_GATEWAY_LOG_FORMAT=json in der Umgebung des Gateways. Erfordert Claude Code v2.1.319 oder höher auf dem Gateway-Server. Jede Zeile der Betriebs-Logs ist dann ein Objekt mit severity, time und message:

{"severity":"INFO","time":"2026-11-04T17:03:21.512Z","message":"claude gateway listening on http://0.0.0.0:8080"}

severity ist die Log-Stufe in Großbuchstaben, wobei warn als WARNING geschrieben wird. Ein fehlgeschlagener Start ist eine ERROR-Zeile. Audit-Ereignisse, die ebenfalls nach stderr gehen, ändern sich nicht. Sie enthalten ts und evt, aber kein severity.

Zustand

Das Gateway stellt GET /healthz als Liveness-Probe und GET /readyz als Readiness-Probe bereit. /readyz prüft, ob der Store erreichbar ist. Wenn Sie store.readiness_grace_seconds setzen, meldet /readyz bis zu diese Anzahl an Sekunden weiterhin Bereitschaft, nachdem der Store nicht mehr antwortet. Beide Endpunkte sind von access_control.allow_cidrs ausgenommen, sodass Probes auch auf einem abgeschotteten Listener weiter funktionieren. Das OAuth-Discovery-Dokument unter /.well-known/oauth-authorization-server gibt ebenfalls erst dann 200 zurück, wenn das Laden der Konfiguration, die OIDC-Discovery, der Aufbau des Upstream-Clients und die Postgres-Migration alle erfolgreich waren, sodass es zugleich als End-to-End-Startprüfung dient.

Gleichzeitige Upstream-Anfragen

Standardmäßig sendet jedes Gateway-Replikat höchstens 256 Anfragen gleichzeitig an den Upstream. Eine Streaming-Antwort zählt gegen das Limit, bis der Stream endet. Eine Anfrage, die eintrifft, während ein Replikat am Limit ist, wartet innerhalb des Gateways auf einen freien Platz. Der Entwickler sieht eine Antwort, die langsam beginnt oder zu hängen scheint. Bei einem Upstream mit provider: anthropic gibt eine Anfrage, die länger als timeouts.upstream_ttfb_ms wartet, diesen Upstream auf und schlägt mit einem 502 fehl, wenn kein späterer Upstream sie bedient. Die Startup-Log-Zeile, die upstream requests: enthält, zeigt das wirksame Limit. Solange ein Replikat mehr offene Anfragen als das Limit hat, protokolliert es zusätzlich höchstens einmal pro Minute eine Warnung, die client requests are open enthält. Um mehr Anfragen gleichzeitig zu bedienen, haben Sie zwei Möglichkeiten:

Fügen Sie Replikate hinzu.
Erhöhen Sie das Limit auf jedem Replikat. Setzen Sie die Umgebungsvariable BUN_CONFIG_MAX_HTTP_REQUESTS auf dem Gateway-Container auf eine ganze Zahl von 1 bis 65535 und starten Sie den Container anschließend neu.

Ein Replikat erreicht sein Limit bei einer Anfragerate von etwa dem Limit geteilt durch die durchschnittliche Anzahl an Sekunden, die eine Anfrage offen bleibt. Wenn Anfragen beispielsweise durchschnittlich 10 Sekunden offen bleiben, erreicht ein Replikat mit dem Standardlimit von 256 dieses bei etwa 26 Anfragen pro Sekunde. Wenn Sie anhand der CPU automatisch skalieren, stellt ein Replikat am Limit Anfragen in die Warteschlange, ohne ein Hochskalieren auszulösen. Setzen Sie den Zielwert daher unter das CPU-Niveau, das Ihre Replikate zeigen, wenn sie die Warnung client requests are open protokollieren.

Jede offene Anfrage belegt Arbeitsspeicher im Gateway-Prozess, während sie streamt und während sie auf einen freien Platz wartet. Auch wenn Sie das Limit bei 256 belassen, wächst der Arbeitsspeicher auf einem überlasteten Replikat weiter, weil wartende Anfragen ihre Request-Bodys behalten. Dimensionieren Sie den Arbeitsspeicher des Containers für die Anzahl der Anfragen, die in Spitzenzeiten offen sind, und beobachten Sie den Arbeitsspeicher, wenn Sie das Limit ändern. Ein Replikat, dem der Arbeitsspeicher ausgeht, wird beendet und bricht alle Streams ab, die es hält.

Bei einem Lasttest mit load_test_mode warten Anfragen nicht an diesem Limit, ein Replikat protokolliert die Warnung client requests are open aber dennoch.

`API_TIMEOUT_MS` über der Zeit bis zum ersten Byte des Gateways halten

Wenn Sie API_TIMEOUT_MS senken, um eine unbeantwortete Anfrage früher erneut zu versuchen, halten Sie den Wert über der Zeit, die das Gateway benötigt, um die ersten Bytes einer Streaming-Antwort zu senden. Eine Anfrage, die länger wartet, läuft in einen Timeout, ebenso jeder Wiederholungsversuch, der genauso lange wartet, bis der Turn mit Request timed out endet, sofern ihn nicht die First-Byte-Frist beendet.

provider: anthropic: Setzen Sie API_TIMEOUT_MS über die längste Zeit, die Ihr Upstream benötigt, um sein erstes Ereignis zu senden.
Jeder andere Upstream: Setzen Sie den Wert mehr als 20 Sekunden über die längste Zeit, die Ihr Upstream benötigt, um Response-Header zurückzugeben. Das Gateway sendet seinen ersten Keepalive-ping etwa 15 Sekunden nach diesen Headern, sofern das erste Ereignis des Upstreams nicht früher eintrifft. Ein Gateway älter als v2.1.229 sendet keine Pings, verwenden Sie dort also die Regel für provider: anthropic.

Berücksichtigen Sie zusätzlich zu dieser Zeit jede Wartezeit auf einen freien Platz sowie die Wartezeit auf einen ausgefallenen Upstream vor dem Failover. Halten Sie den Wert außerdem über der längsten Nicht-Streaming-Anfrage.

Eine unbeantwortete Anfrage mit der First-Byte-Frist früher erneut versuchen

Damit Claude Code eine unbeantwortete Streaming-Anfrage früher erneut versucht, geben Sie ihm eine First-Byte-Frist, indem Sie CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS auf den Rechnern Ihrer Entwickler setzen. Die Frist begrenzt, wie lange der erste Versuch auf Response-Header wartet. Ohne sie kann dieser Versuch 5 bis 6 Minuten warten. Erfordert Claude Code v2.1.307 oder höher auf dem Rechner des Entwicklers. Setzen Sie die Variable auf eine positive ganze Zahl in Millisekunden, in einem env-Block einer Gateway-Richtlinie oder in der Shell eines Entwicklers. Halten Sie den Wert über der längsten Zeit bis zum ersten Byte Ihres Gateways, sonst kann Claude Code intakte Anfragen abbrechen und erneut senden, deren Header länger brauchen. Dieses Beispiel setzt 60 Sekunden in der Shell eines Entwicklers:

export CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS=60000

Eine unbeantwortete erneut gesendete Anfrage kann 5 bis 6 Minuten warten, bis der Body-Idle-Timeout sie beendet und Claude Code sie innerhalb des Wiederholungsbudgets erneut versucht. Wenn Sie API_TIMEOUT_MS nur gesenkt haben, um früher erneut zu versuchen, entfernen Sie diesen Wert, sonst kann eine einzige unbeantwortete erneut gesendete Anfrage den Turn mit No response from API beenden. Um zu bestätigen, dass die Frist ausgelöst wurde, lassen Sie einen Entwickler Claude Code mit Debug-Logging starten und durchsuchen Sie das Log anschließend nach [first-byte] no response headers.

Verhalten bei Ausfällen

Wenn Postgres ausfällt, bedient das Gateway selbst angemeldete Entwickler weiter, neue Anmeldungen schlagen jedoch fehl. Ob Entwickler tatsächlich weiterarbeiten können, hängt davon ab, wie Ihr Orchestrator mit Readiness umgeht:

Bestehende Sitzungen: Bearer-Token werden lokal mit dem JWT-Secret validiert, Sitzungs-Refreshes greifen nicht auf den Store zu, und der Gateway-Prozess kann weiterhin Inferenz bedienen
Neue Anmeldungen: schlagen fehl, bis sich Postgres erholt, weil der Device-Flow und seine Rate-Limit-Zähler in Postgres liegen
Durchsetzung von Ausgabenlimits: ist während des Ausfalls standardmäßig fail-open, sodass Inferenz weiter fließt; stellen Sie auf fail-closed um, wenn Sie lieber blockieren als ohne Messung laufen möchten
Readiness: Standardmäßig meldet /readyz „nicht bereit“, sobald Postgres nicht erreichbar ist, sodass jedes Replikat gleichzeitig seine Readiness-Prüfung nicht besteht. Wo Traffic nur Replikate erreicht, die die Prüfung bestehen, schlägt jeglicher Traffic fehl, einschließlich Inferenz, die das Gateway noch bedienen könnte, bis sich Postgres erholt. Die Liveness-Probe auf /healthz besteht währenddessen weiterhin.

Wenn Ihr IdP ausfällt, funktionieren bestehende Sitzungen bis ttl_hours, und neue Anmeldungen schlagen fehl. Ein Sitzungs-Refresh erhält die Antwort, es erneut zu versuchen, und ist erfolgreich, sobald der IdP wieder verfügbar ist. Setzen Sie ein längeres ttl_hours, wenn Ihr IdP häufige Wartungsfenster hat.

Readiness-Kulanzzeit

Damit angemeldete Entwickler einen kurzen Postgres-Ausfall wie ein Datenbank-Failover überstehen, setzen Sie store.readiness_grace_seconds auf einen Wert, der länger ist als das Failover dauert, zum Beispiel 300. Bei aktivierten Ausgabenlimits und dem standardmäßigen Fail-open-Verhalten laufen Anfragen über ein Replikat, das bereit bleibt, ohne Messung, bis sich Postgres erholt. Halten Sie den Wert daher so niedrig, wie es Ihr Failover zulässt. Wenn Sie enforcement.fail_closed_on_error: true setzen, lehnt das Gateway die Inferenz angemeldeter Entwickler mit der 429-Meldung spend limit unavailable ab, bis sich Postgres erholt, auch während Replikate ihre Readiness-Prüfung noch bestehen. Die Einstellung erfordert Claude Code v2.1.282 oder höher auf dem Gateway-Server. Ein älteres Gateway verweigert den Start, wenn es den Schlüssel findet. Aktualisieren Sie daher jedes Replikat, bevor Sie ihn hinzufügen. Upgrades behandelt Rollbacks. Wenn Sie die Readiness-Probe stattdessen auf /healthz richten, bestehen Replikate diese während eines Ausfalls ebenfalls weiterhin, aber /healthz meldet nie „nicht bereit“, sodass auch ein Replikat, dessen Postgres-Verbindung sich nicht erholt, die Prüfung weiter besteht.

Rotation des JWT-Secrets

Rotieren Sie das Signatur-Secret in Stufen, damit bestehende Sitzungen gültig bleiben:

Generieren Sie ein neues Secret. Stellen Sie es dem Array session.jwt_secret voran.
Rollen Sie das Deployment aus. Neue Token werden mit dem neuen Secret signiert; alte Token werden weiterhin verifiziert.
Entfernen Sie nach ttl_hours plus einer Sicherheitsmarge das alte Secret und rollen Sie erneut aus.

Die Rotation ist außerdem die einzige Möglichkeit, Sitzungen vor ihrem Ablauf zu beenden: Bearer-Token werden lokal gegen das JWT-Secret validiert, daher gibt es keinen Widerruf pro Sitzung. Wenn Sie das Secret vollständig ersetzen, ohne das alte im Array zu behalten, werden alle ausstehenden Sitzungen auf einmal ungültig. Für das Offboarding einzelner Personen deprovisionieren Sie den Benutzer in Ihrem IdP; seine Sitzung endet innerhalb von ttl_hours.

Postgres

Das Gateway speichert seinen Zustand in einer PostgreSQL-Datenbank:

Datenbank: PostgreSQL selbst, selbst gehostet oder verwaltet, in der Mindestversion oder höher. Datenbanken, die nur das Postgres-Protokoll implementieren, wie verteilte SQL-Datenbanken, werden nicht unterstützt.
Adresse: store.postgres_url akzeptiert einen Host. Wenn die Datenbank mehrere Knoten hat, verwenden Sie die vorgelagerte Adresse, etwa den Endpunkt Ihres verwalteten Dienstes, einen Load Balancer oder eine virtuelle IP. Setzen Sie eine Readiness-Kulanzzeit, die länger ist als ein Failover dauert.

Das Gateway verwaltet fünf Datentabellen sowie eine Tabelle _migrations, die alle durch seine Migrationen beim Start erstellt werden:

Tabelle	Inhalt	Aufbewahrung
`kv`	Device-Grants (10 Minuten TTL) und Rate-Limit-Zähler	TTL pro Zeile
`spend`	Ausgabenzähler pro Principal für den laufenden Zeitraum, in Cent	`admin.spend_retention_months`, Standard 13
`spend_limits`	Konfigurierte Ausgabenobergrenzen	Bis zur Löschung über die API
`admin_audit`	Änderungsverlauf der Admin-API	`admin.audit_retention_days`, Standard 365
`principal_emails`	Zuletzt gesehene E-Mail-Adresse, Anzeigename und IdP-Gruppen jedes Principals. Enthält personenbezogene Daten.	`admin.identity_retention_days` seit der letzten Aktivität, Standard 90

Eine 30-Sekunden-Schleife lässt kv-Zeilen nach Ablauf ihrer TTL verfallen, und ein stündlicher Durchlauf setzt die Aufbewahrungsfristen für die Ausgabentabellen durch, sodass nichts unbegrenzt wächst. Ohne konfigurierte Ausgabenlimits wird nur in kv geschrieben. Das Gateway wendet seine eigenen Schemamigrationen beim Start und bei jedem Upgrade an, daher benötigt seine Datenbankrolle Rechte zum Erstellen und Ändern von Tabellen. Richten Sie es auf eine Datenbank oder ein Schema, das ausschließlich dem Gateway dient, um diese Berechtigung eng zu halten. Bei Verwendung von Ausgabenlimits bedeutet eine verlorene Datenbank verlorene Ausgabenerfassung und Obergrenzen, nicht nur erneute Anmeldungen der Entwickler. Erstellen Sie daher regelmäßig Backups. Um einen ausgeschiedenen Entwickler sofort zu löschen, statt auf die Aufbewahrungsfrist zu warten, führen Sie DELETE FROM principal_emails WHERE principal = '<sub>' direkt aus; damit wird die einzige Tabelle bereinigt, die seine E-Mail-Adresse, seinen Namen und seine Gruppen enthält. Zeilen in spend und admin_audit verweisen nur auf das pseudonyme OIDC-sub.

Den Verbindungspool dimensionieren

Jedes Replikat öffnet bis zu store.max_connections Postgres-Verbindungen, standardmäßig fünf. Halten Sie Replikate × store.max_connections bei oder unter den Verbindungen, die die Datenbank für das Gateway übrig hat:

Replikate: Zählen Sie die Höchstzahl, die gleichzeitig läuft. Beginnen Sie mit Ihrem Autoscaling-Maximum oder Ihrer Replikatanzahl, wenn Sie nicht automatisch skalieren, und addieren Sie die zusätzlichen Replikate, die ein Rolling Update startet, bevor es alte stoppt. Auf Amazon ECS mit Standardeinstellungen und auf Cloud Run können das noch einmal so viele sein.
Verbleibende Verbindungen: Nehmen Sie den max_connections-Wert der Datenbank und ziehen Sie ab, was die Datenbank reserviert und was andere Clients belegen. PostgreSQL reserviert superuser_reserved_connections, standardmäßig drei. Ein verwalteter Dienst kann mehr reservieren, prüfen Sie daher dessen Dokumentation.

Nehmen Sie beispielsweise ein Autoscaling-Maximum von sechs, Rolling Updates, die höchstens zwei zusätzliche Replikate starten, und den Standardpool von fünf. Das erfordert (6 + 2) × 5 = 40 Verbindungen. Eine Datenbank mit einem max_connections von 50 und zwei von anderen Clients belegten Verbindungen hat 50 − 3 − 2 = 45 übrig, die Summe passt also. Wenn Ihre Summe nicht passt, ändern Sie einen der folgenden Punkte:

Die Datenbank: Erhöhen Sie ihren max_connections-Wert
Die Replikate: Betreiben Sie weniger, oder lassen Sie Ihren Orchestrator bei einem Rolling Update weniger zusätzliche Replikate starten
Der Pool: Senken Sie store.max_connections, halten Sie ihn aber bei aktivierten Ausgabenlimits groß genug für die Last jedes Replikats. Andernfalls können Ausgabenprüfungen beim Warten auf eine Verbindung in einen Timeout laufen, und das Gateway protokolliert spend check failed: spend precheck timed out.

Upgrades

Replikate sind zustandslos, daher geht bei einem Rolling Restart kein Gateway-Zustand verloren. Das Gateway führt Schemamigrationen beim Start aus, was bedeutet, dass das Deployment der neuen Binary die Datenbank selbst migriert. Gleichzeitige Replikate serialisieren sich über einen Postgres-Advisory-Lock, sodass nur eines jede Migration anwendet. Wenn Ihr Orchestrator ein Replikat mit SIGTERM stoppt, etwa bei einem Rolling Restart oder einem Herunterskalieren, nimmt das Gateway keine neuen Verbindungen mehr an und lässt bereits laufende Anfragen und Streams abschließen, bevor es sich beendet. Es wartet bis zu 25 Sekunden, das sogenannte Drain-Fenster, und schließt dann alles, was noch offen ist. Ein SIGINT, etwa Ctrl+C in einem Terminal, startet denselben Drain, und ein zweites Signal während des Drains schließt die offenen Anfragen und beendet sich sofort. Draining erfordert Gateway v2.1.274 oder höher. Lange Generierungen können minutenlang streamen. Erhöhen Sie auf Kubernetes und Amazon ECS beide der folgenden Werte zusammen, um diesen Streams mehr Zeit zu geben:

Das Drain-Fenster: Setzen Sie die Umgebungsvariable CLAUDE_GATEWAY_DRAIN_TIMEOUT_MS auf dem Gateway-Container auf eine positive ganze Zahl in Millisekunden, etwa 120000. Das Gateway ignoriert einen Wert in jeder anderen Form, etwa 120s, und behält den Standard von 25 Sekunden bei
Die Grace Period Ihres Orchestrators: terminationGracePeriodSeconds auf Kubernetes oder stopTimeout auf Amazon ECS

Die Grace Period beträgt auf beiden Plattformen standardmäßig 30 Sekunden. Halten Sie sie mindestens 5 Sekunden länger als das Drain-Fenster, sonst beendet der Orchestrator das Gateway, bevor der Drain abgeschlossen ist. Addieren Sie auf Kubernetes außerdem die Dauer eines etwaigen preStop-Hooks, da die Grace Period zu zählen beginnt, bevor der Hook läuft, und nicht erst, wenn das Gateway SIGTERM empfängt. Ihre Plattform kann außerdem begrenzen, wie lange der Drain laufen darf:

Amazon ECS auf Fargate: stopTimeout erlaubt höchstens 120 Sekunden
Cloud Run: stoppt eine Instanz 10 Sekunden nach SIGTERM, sodass offene Streams dort höchstens 10 Sekunden erhalten, unabhängig vom Drain-Fenster

Wenn das Drain-Fenster endet, während noch Anfragen offen sind, protokolliert das Gateway eine Warnung, die drain window over after enthält, zählt die abgebrochenen Anfragen und nennt beide Einstellungen, die erhöht werden sollten. Migrationen sind rein additiv, daher ist ein Rollback auf eine frühere Binary, die weniger Migrationen kennt, sicher; sie ignoriert die zusätzlichen Zeilen. Beim Rollback wird das YAML außerdem erneut gegen das Schema der älteren Binary validiert, sodass eine Konfiguration, die einen mit dem neueren Release eingeführten Schlüssel übernommen hat, beim Start der älteren Version fehlschlägt. Entfernen Sie den neuen Schlüssel vor dem Rollback.

Wenn Sie nur den Schlüssel groups aus einem Upstream entfernen, ist dieser anschließend für jeden Entwickler offen. Siehe was Sie vor dem Rollback entfernen sollten.

Da Sie die Version des Gateways in Ihrem eigenen Image festlegen, erreichen Korrekturen in neuen Claude Code-Releases, einschließlich Sicherheitskorrekturen, Ihr Deployment erst, wenn Sie die festgelegte Version aktualisieren und erneut deployen. Nehmen Sie das Gateway in denselben Patch-Rhythmus auf, den Sie für andere Dienste verwenden, die Produktions-Anmeldedaten enthalten.

Sicherheit

Dieser Abschnitt beantwortet die Fragen, die eine Sicherheitsüberprüfung stellt: Welche Daten fließen durch das Gateway und wohin sie gehen, welche Angriffe das Design abwehrt, und welche Antworten in einen Compliance-Fragebogen gehören.

Datenfluss

Daten	Pfad	Vom Gateway an Anthropic gesendet
Inferenz (Prompts, Completions)	CLI → Gateway → Ihr Upstream	Nur wenn die Anthropic-API ein konfigurierter Upstream ist
Telemetrie (OTLP-Metriken, plus Opt-in-Protokolle und Traces)	CLI → Gateway → Ihr Collector	Nie
Identität (E-Mail, Gruppen, Sub)	IdP → Gateway → CLI; die CLI stempelt sie auf OTLP-Exporte. Wenn Sie `forward_user_identity` aktivieren, sendet das Gateway auch die E-Mail des Entwicklers und den IdP-Subject als Header an Ihren Proxy	Nie
Verwaltete Einstellungen	Ihre Gateway-YAML → CLI	Nie
Audit-Protokoll	Gateway-Stderr → Ihr Aggregator	Nie

Bedrohungsmodell-Zusammenfassung

Das Gateway sitzt innerhalb Ihres Netzwerk-Perimeters, aber einzelne Entwickler-Laptops werden nicht als vertrauenswürdig behandelt. Das Design berücksichtigt dies auf drei Arten:

Entwickler halten kurzlebige JWTs statt roher Upstream-Schlüssel. Das CLI-zu-Gateway-Bein verwendet den RFC-8628-Device-Grant, und der Gateway-Autorisierungs-Code-Austausch mit dem IdP führt PKCE in der Standard-Konfiguration aus, daher ist ein abgefangener IdP-Autorisierungs-Code nutzlos.
Die Device-Verifikationsseite erzwingt Same-Origin-POST und ein Pro-IP-Rate-Limit pro RFC 8628 §5.1. Siehe User-Code-Brute-Force-Resistenz.
Die Anfragen des Gateways an Ihren IdP, Ihre OTLP-Collector und provider: anthropic-Upstreams gehen durch einen Server-Side-Request-Forgery (SSRF)-Guard, der DNS auflöst, Link-Local- und Cloud-Metadata-Adressen plus Loopback standardmäßig blockiert und die Verbindung zur aufgelösten IP pinnt, daher können Operator-beeinflusste URLs nicht zu Cloud-Metadata-Endpoints umgeleitet werden. RFC-1918-Private-Bereiche sind absichtlich erlaubt, da IdPs und OTLP-Collector häufig auf privaten IPs leben. Für die anderen Provider weigert sich das Gateway, eine base_url zu akzeptieren, die eine dieser Adressen oder einen Metadata-Hostnamen benennt, wenn es die Konfiguration lädt, und das SDK des Providers verbindet sich dann ohne die DNS-Prüfung. Wenn Sie Proxy-Only-Egress aktivieren, verschiebt sich diese Adressprüfung zu Ihrem Forward-Proxy: Das Gateway übergibt Hostnamen und die Allowlist des Proxys muss diese Ziele ablehnen. Setzen Sie CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 in der Gateway-Umgebung nur, wenn etwas, das das Gateway erreichen muss, legitim auf Loopback lebt, wie ein lokaler Entwicklungs-IdP oder ein Sidecar-OTLP-Collector auf localhost. Die Variable lockert die Loopback-Blockade für jede Operator-konfigurierte URL und überspringt auch die Boot-Zeit-Warnung, die prüft, ob der Pod den Cloud-Metadata-Endpoint erreichen kann, daher bevorzugen Sie es, dem Collector seine eigene interne Adresse zu geben.

Wenn Sie Ihre eigenen Egress-Kontrollen hinzufügen, muss das Gateway den Metadata-Server erreichen, wenn es Instanz-Metadata-Anmeldedaten wie Workload-Identität verwendet. Zwei Bedrohungen sind außerhalb des Geltungsbereichs, da sie Ihre Infrastruktur sind, um zu sichern:

Ein kompromittierter Gateway-Host: Der Host hält sowohl die Upstream-Anmeldedaten als auch verteilt verwaltete Einstellungen an jeden verbundenen Entwickler, daher ist die Kontrolle über die Gateway-Konfiguration vergleichbar mit der Kontrolle über Ihr MDM. Der Genehmigungsdialog der CLI für Shell-fähige Einstellungen begrenzt stille Änderungen, ersetzt aber nicht die Host-Sicherheit.
Ein böswilliger OIDC-Anbieter: Der Anbieter signiert die id_tokens, denen das Gateway vertraut, daher kann er jede Identität behaupten. Das Überprüfen und Sichern Ihres IdP ist Ihre Verantwortung.

User-Code-Brute-Force-Resistenz

Der user_code, den ein Entwickler auf der /device-Verifikationsseite eingibt, sind 8 Zeichen aus einem 20-Zeichen-Alphabet, was 20⁸ oder etwa 2,56×10¹⁰ Kombinationen ergibt, und er läuft nach 10 Minuten ab. Das Gateway wendet Pro-IP-Rate-Limits auf die Device-Grant-Endpoints an, konfigurierbar über rate_limits. Erhöhen Sie die Limits, wenn sich viele Entwickler von einer einzelnen gemeinsamen Unternehmens-NAT-Adresse anmelden. Große Rollouts zeigt, wie Sie sie dimensionieren. Die Limits gelten nur für den Anmeldungs-Flow, nicht für Inferenz.

Compliance-Haltung

Datenresidenz: Die Datenebene des Gateways selbst sendet nichts an Anthropic, es sei denn, die Anthropic-API ist ein konfigurierter Upstream; wenn sie es ist, gilt Ihre bestehende Datenbehandlungsvereinbarung für den Inferenz-Pfad. Telemetrie, Audit, Identität und Einstellungen gehen nur an die Ziele, die Sie konfigurieren.
Host-Prozess-Verkehr: Der Host-Prozess ist die Claude Code CLI. claude gateway läuft unter den gleichen Third-Party-Regeln wie Amazon Bedrock und Google Cloud’s Agent Platform-Bereitstellungen und sendet nichts an Anthropic. Vor v2.1.227 sendete der Host-Prozess Startup-Telemetrie wie Produktversion und Plattform, die das Setzen von CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 in der Container-Umgebung ausschaltete. Diese Releases sendeten auch eine HEAD-Anfrage beim Boot ohne Body oder Anmeldedaten an /api/hello auf https://api.anthropic.com oder auf ANTHROPIC_BASE_URL, wenn die Umgebung es setzte, es sei denn, die Umgebung setzte auch eine Proxy-Variable wie HTTPS_PROXY oder ein mTLS-Client-Zertifikat. Sie ignorierten die Antwort, daher blockierte das Blockieren dieser Anfrage an der Egress-Firewall das Gateway nicht.
Client-Analytik: Die CLI deaktiviert ihre eigene Nutzungsanalytik und Fehlerberichterstattung, während sie bei einem Gateway angemeldet ist. Vor der ersten Anmeldung sendet die CLI immer noch Startup-Events an Anthropic, auch auf Maschinen, deren verwaltete Einstellungen Gateway-Anmeldung erzwingen. Um diese auch auszuschalten, liefern Sie DISABLE_TELEMETRY in den gleichen Client-seitigen verwalteten Einstellungen, die Gateway-Anmeldung erzwingen.
Fehlerberichterstattung: Die CLI schaltet Fehlerberichterstattung aus, wenn ihre Modellanfragen zu einem anderen Endpoint als Anthropic’s First-Party-API gehen, wie Amazon Bedrock oder ein benutzerdefiniertes ANTHROPIC_BASE_URL.
Client-Maschinen: Entwickler-CLIs senden immer noch WebFetch-Hostname-Prüfungen und Versions-Prüfungen an Anthropic, es sei denn, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 und skipWebFetchPreflight: true sind gesetzt. Plugin-Marketplace-Anfragen haben eigene Schalter zum Ausschalten. Siehe Datennutzung.
Umfrage-Bewertungen: Während der Anmeldung bei einem Gateway deaktiviert die CLI den Anthropic-gebundenen Bewertungs-Upload zusammen mit den Analytik-Streams, daher sendet sie Bewertungen nicht an Anthropic.
Transkript-Freigabe: Das Wählen von Ja auf einer Umfrage-Transkript-Freigabe-Aufforderung schreibt eine lokale Datei unter ~/.claude/feedback-bundles/ statt zu Anthropic hochzuladen.
Client-Updates: Update-Prüfungen sind getrennt vom Gateway-Verkehr. Pinnen Sie Versionen durch Ihre eigene Verteilung und setzen Sie DISABLE_UPDATES, wenn Laptops keine Releases abrufen dürfen. DISABLE_AUTOUPDATER stoppt nur Hintergrund-Updates, während claude update immer noch funktioniert.
TLS: Bedienen Sie public_url über HTTPS in der Produktion, entweder vom Gateway-eigenen Listener über listen.tls oder von einem TLS-terminierenden Ingress vor einfachen HTTP-Replikationen mit listen.public_url gesetzt. Das Gateway weigert sich nicht, einfaches HTTP. Der IdP muss HTTPS in der Produktion bedienen, und Postgres unterstützt ?sslmode=require. Setzen Sie Strict-Transport-Security bei Ihrem Ingress.
Vulnerability-Offenlegung: Folgen Sie Sicherheitsprobleme melden

Plugin-Marketplace-Anfragen

Claude Code ruft Plugin-Marketplaces direkt vom Rechner jedes Entwicklers ab, nicht über das Gateway. Anforderungen an den Netzwerkzugriff listet die Hosts auf. Wenn ein Entwickler zum ersten Mal eine interaktive Terminal-Sitzung startet, registriert Claude Code den offiziellen Marketplace claude-plugins-official. Es lädt den Katalog von downloads.claude.ai herunter und klont ihn, falls das fehlschlägt, von github.com. Welche Marketplaces und Plugins automatisch aktualisiert werden behandelt spätere Aktualisierungen. CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 verhindert die erste Registrierung nicht. Jede dieser verwalteten Einstellungen verhindert sie:

Eine Marketplace-Liste: eine strictKnownMarketplaces-Allowlist, die den Marketplace auslässt, oder ein blockedMarketplaces-Eintrag, der ihn benennt
Eine Umgebungsvariable: CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL, im verwalteten env-Block auf "1" gesetzt

Die erste Registrierung kann ausgeführt werden, bevor sich der Entwickler beim Gateway anmeldet, wenn noch keine Gateway-Richtlinie angekommen ist. Um diesen ersten Start abzudecken, liefern Sie Ihre Wahl in Client-seitigen verwalteten Einstellungen sowie im cli- oder code-Block der Gateway-Richtlinie.

Fehlerbehebung

Für Fragen und Feedback nutzen Sie den Claude Code-Support oder erstellen Sie ein Issue im Claude Code GitHub-Repository. Sie können sich auch an Ihr Anthropic-Account-Team wenden. Geben Sie beim Melden eines Problems Folgendes an:

Gateway-Problem: die stderr-Ausgabe des Gateways für den betreffenden Zeitraum, Ihre gateway.yaml mit geschwärzten Secrets, die Gateway-Version, die auf der Startseite unter / und im Response-Header x-cc-gateway-version von /managed/settings angezeigt wird, sowie die jüngsten Änderungen
Anmeldeproblem: Der Entwickler führt claude --debug-file ./claude-debug.txt aus, reproduziert das Problem und sendet diese Datei zusammen mit dem Audit-Log des Gateways für denselben Zeitraum
Inferenzproblem: das angefragte Modell, die konfigurierten Upstreams und das Audit-Log des Gateways für die Anfrage, das festhält, welcher Upstream sie bedient hat und welchen Antwortstatus sie hatte

Die stderr-Ausgabe des Gateways enthält den Audit-Event-Stream, das Audit-Log enthält die Identitäten der Entwickler, und die Debug-Datei enthält die Ausgabe von Hooks und MCP-Servern vom Rechner des Entwicklers. Prüfen und schwärzen Sie diese Daten, bevor Sie sie in einem öffentlichen Issue veröffentlichen.

Symptom	Ursache	Lösung
Das `/login` eines Entwicklers zeigt die Standard-Kontoauswahl statt des Bildschirms Cloud gateway	`forceLoginMethod` oder `forceLoginGatewayUrl` ist in den verwalteten Einstellungen auf diesem Rechner nicht gesetzt	Stellen Sie die Datei mit den verwalteten Einstellungen auf dem Gerät bereit; `/login` liest die Gateway-URL von dort
Die Anfragen eines Entwicklers schlagen fehl mit `Not signed in to the Cloud gateway — run /login.`	Die verwalteten Einstellungen des Rechners setzen `forceLoginMethod: "gateway"` oder `forceLoginGatewayUrl`, und die Sitzung hat keine Gateway-Anmeldung. Eine verbliebene claude.ai-Anmeldung erfüllt diese Anforderung nicht.	Lassen Sie den Entwickler `/login` ausführen und die Gateway-Anmeldung abschließen. Siehe auch Administrator policy requires a Cloud gateway sign-in.
Claude Desktop meldet, dass seine Bootstrap-Konfiguration nicht abgerufen werden konnte	`/user/bootstrap` hat 404 zurückgegeben: Die zum Benutzer passende Richtlinie enthält keinen `desktop`-Schlüssel, oder keine Richtlinie hat gepasst. Das Audit-Log des Gateways protokolliert jede Ablehnung als `desktop_bootstrap.denied` mit dem Grund.	Fügen Sie der zum Benutzer passenden Richtlinie oder der Basisebene `match: {}` einen `desktop`-Block hinzu; ein leeres `desktop: {}` genügt. Siehe Claude Desktop-Overlay.
Das Audit-Log zeigt `auth.denied` mit `reason: invalid_token` für `/v1/logs` oder `/v1/metrics`	Sie haben `otelHeadersHelper` in den verwalteten Einstellungen eines Rechners gesetzt. In einer Claude Desktop-Sitzung auf diesem Rechner sendet Claude Code den `Authorization`-Header aus dem Helper anstelle des Sitzungs-Tokens an das Telemetrie-Relay des Gateways. Wenn Claude Desktop Claude Code in einer Version vor v2.1.307 mitliefert, erhalten Sie dieselbe Ablehnung, wenn Sie in diesen Einstellungen einen `Authorization`-Header in `OTEL_EXPORTER_OTLP_HEADERS` oder einer signalspezifischen Variante setzen.	Entfernen Sie den Helper aus diesen Einstellungen. Wenn Claude Desktop Claude Code in einer Version vor v2.1.307 mitliefert, entfernen Sie die Variable.
Beim Start erscheint `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.`	Der installierte Claude Code-Build ist älter als die Gateway-Unterstützung	Lassen Sie den Entwickler Claude Code auf ein Release aktualisieren, das Cloud gateway-Unterstützung enthält
Der Start bricht ab mit `Administrator policy requires a Cloud gateway sign-in on this machine`	Die Umgebung des Entwicklers setzt `ANTHROPIC_API_KEY` oder `ANTHROPIC_AUTH_TOKEN`, seine Einstellungen konfigurieren einen `apiKeyHelper`, oder ein API-Schlüssel aus einer früheren Claude Console-Anmeldung ist noch gespeichert	Lassen Sie den Entwickler jeden zutreffenden Punkt bereinigen: die Variable entfernen, den `apiKeyHelper`-Eintrag entfernen oder `claude auth logout` ausführen, um den gespeicherten Schlüssel zu entfernen. Eine Sitzung, die mit `CLAUDE_CODE_USE_*` einen Cloud-Anbieter auswählt, startet dann ohne Anmeldung; bei allen anderen Sitzungen lassen Sie den Entwickler `claude` starten und sich mit `/login` anmelden. Siehe auch Administrator policy requires a Cloud gateway sign-in.
Der Start oder `/login` meldet `Claude Code may not be enabled for your organization` nach einem 403 beim Laden der verwalteten Einstellungen	Das Gateway oder etwas davor hat die Anfrage an `/managed/settings` mit 403 beantwortet. Die eigene Einstellungsroute des Gateways antwortet nie mit 403. Der Status stammt aus den IP-Prüfungen von `access_control` oder von einem Proxy oder einer WAF vor dem Gateway. Das Audit-Log protokolliert eine Ablehnung durch die IP-Prüfung als `access.denied` mit dem Grund. Der Entwickler bleibt angemeldet.	Suchen Sie im Audit-Log zum Zeitpunkt des Fehlers nach `access.denied` und korrigieren Sie die `access_control`-Listen oder das Frontend; lassen Sie den Entwickler dann `claude` erneut starten
CLI-`/login`: `The gateway is limiting sign-in attempts right now`, oder `Request failed with status code 429` bei älteren Versionen. Die Seite `/device` kann Entwicklern, die es noch nicht versucht haben, `Too many attempts` anzeigen	Das Rate-Limit für Anmeldungen pro IP wurde erreicht. Entweder deckt `listen.trusted_proxies` den Load Balancer nicht ab, sodass sich alle Entwickler dessen Adresse teilen, oder viele Entwickler teilen sich eine NAT- oder VPN-Egress-Adresse. Audit-Events mit `result: rate_limited` zeigen denselben oder wenige `client_ip`-Werte.	Wenn der Load Balancer in `listen.trusted_proxies` gehört, tragen Sie ihn zuerst dort ein. Erhöhen Sie dann `rate_limits`, falls sich Entwickler weiterhin Adressen teilen. Siehe Große Rollouts.
CLI-`/login`: `Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>`	Der Hostname des Gateways wird zu mindestens einer öffentlichen IP-Adresse aufgelöst. Claude Code prüft jede aufgelöste Adresse und verlangt, dass alle privat sind. Eine häufige Ursache ist ein Dual-Stack-Name, bei dem eine Adressfamilie zu einer öffentlichen Adresse aufgelöst wird, darunter interne Dual-Stack-Load-Balancer von AWS, die AAAA-Adressen aus öffentlichen Bereichen zurückgeben.	Sorgen Sie dafür, dass der Gateway-Name auf den Rechnern der Entwickler nur zu privaten Adressen aufgelöst wird. Entfernen Sie bei einem Dual-Stack-Namen den Eintrag aus dem öffentlichen Bereich oder stellen Sie einen separaten, rein internen DNS-Namen bereit. Siehe die Voraussetzung zum privaten Netzwerk. Wenn die Adresse zu einem öffentlichen Adressraum gehört, der Ihrer Organisation gehört und intern genutzt wird, deklarieren Sie stattdessen diesen Block.
CLI-`/login`: `Gateway login would go through proxy <proxy>, which is not on a private network`	Ein `HTTPS_PROXY` oder `HTTP_PROXY` gilt für den Gateway-Host, und der Hostname des Proxys wird zu einer öffentlichen Adresse aufgelöst. Ein Proxy, dessen Host nur zu privaten Adressen aufgelöst wird, ist erlaubt und löst diesen Fehler nicht aus	Fügen Sie den Gateway-Host auf dem Rechner des Entwicklers zu `NO_PROXY` hinzu, damit die Verbindung direkt erfolgt, oder verwenden Sie einen Proxy, dessen Hostname zu privaten Adressen aufgelöst wird. Die Meldung nennt den genauen `NO_PROXY`-Eintrag, den Sie hinzufügen müssen
CLI-`/login`: `Claude Code only signs in to <host> from inside its declared network <block> (managed settings), and this machine is connecting from <ip>, outside it`	Das Gateway liegt in einem in `gatewayInternalNetworks` deklarierten Block, und der Rechner des Entwicklers hat es von einer Adresse außerhalb dieses Blocks erreicht: einem VPN-Adresspool, einem NAT-Segment eines Containers oder von WSL2 oder einem Netzwerk, das nicht Ihnen gehört	Lassen Sie den Entwickler `/login` vom Host-Betriebssystem in Ihrem Netzwerk ausführen. Wenn die angezeigte Adresse ebenfalls zum öffentlichen Adressraum Ihrer Organisation gehört, ersetzen Sie den Eintrag des Gateways durch einen Block, der beide abdeckt, bis zu `/8`; ein zweiter, überlappender Eintrag wird abgelehnt. Wenn kein Block beide abdeckt, siehe Eine Adresse für das Gateway wählen
CLI-`/login`: `Every address for gateway host <host> must be inside its declared network <block>, and it also resolves to <ip>`	Der Name des Gateways wird zu einer Adresse außerhalb des in `gatewayInternalNetworks` deklarierten Blocks aufgelöst: ein zweiter Standort oder ein IPv6-Eintrag bei einem Dual-Stack-Namen. Bei einem deklarierten Block muss jeder Eintrag innerhalb dieses einen IPv4-Blocks liegen, private und IPv6-Adressen eingeschlossen	Veröffentlichen Sie für den Gateway-Namen auf den Rechnern der Entwickler nur Einträge innerhalb des Blocks, oder stellen Sie einen separaten, rein internen Namen bereit
CLI-`/login`: `<host> is on the declared network <block>, which Claude Code checks over a direct connection, not through an HTTP proxy`	Ein `HTTPS_PROXY` oder `HTTP_PROXY` gilt für ein Gateway in einem deklarierten Block	Fügen Sie auf dem Rechner des Entwicklers den in der Meldung genannten `NO_PROXY`-Eintrag hinzu
CLI-`/login`: eine Meldung, die mit `gatewayInternalNetworks in managed settings` beginnt	Der Wert verstößt gegen eine der Validierungsregeln, und die Meldung nennt, gegen welche. Bis Sie das korrigieren, lehnt Claude Code jedes neue Gateway-`/login` auf dem Rechner ab, auch für Gateways mit privaten Adressen; bestehende Anmeldungen funktionieren weiterhin	Korrigieren Sie in der Quelle der verwalteten Einstellungen, die Sie bereitstellen, den in der Meldung genannten Eintrag und führen Sie `/login` dann erneut aus
CLI-`/login`: `Could not resolve the configured HTTP proxy`	Der Hostname in `HTTPS_PROXY` oder `HTTP_PROXY` lässt sich vom Rechner des Entwicklers aus nicht auflösen, meist weil dieser nicht mit dem Unternehmensnetzwerk verbunden ist	Lassen Sie den Entwickler eine Verbindung zu Ihrem Netzwerk oder VPN herstellen und es erneut versuchen, oder korrigieren Sie die Proxy-URL
CLI-`/login`: `Could not resolve gateway host <host>`	Der Rechner kann den internen DNS-Namen des Gateways nicht auflösen, meist weil er sich nicht im Unternehmensnetzwerk befindet	Lassen Sie den Entwickler eine Verbindung zu Ihrem Netzwerk oder VPN herstellen und `/login` dann erneut versuchen
Der Start bricht mit einem Konfigurationsvalidierungsfehler ab, der `store.postgres_url` nennt	Kein Postgres konfiguriert; das Gateway benötigt Postgres	Setzen Sie `store.postgres_url`. Verwenden Sie für die lokale Entwicklung einen Wegwerf-Container: `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`.
Der Start bricht ab: `store.postgres_url in <path> is not a URL the gateway can read`, oder vor v2.1.290 ein bloßes `Invalid URL` oder `URI error`	Die URL kann nicht geparst werden, zum Beispiel weil sie mehr als einen Host auflistet oder ihr Passwort ein nicht kodiertes `/`, `?`, `#` oder `%` enthält	Geben Sie einen Host an und verschieben Sie das Passwort nach `store.password`
Der Start bricht ab: `requires the native binary`	Ausführung unter Node statt mit der nativen Binärdatei	Installieren Sie Claude Code mit einer der eigenständigen Installationsmethoden
Der Start bricht nach `config.load` mit einem OIDC-Discovery-Fehler ab	`oidc.issuer` nicht erreichbar, oder die TLS-Kette ist nicht vertrauenswürdig	Prüfen Sie, ob der Issuer vom Pod aus erreichbar ist und `/.well-known/openid-configuration` bereitstellt. Setzen Sie `ca_cert_pem` für eine private PKI. Wenn der Pod den IdP nur über einen Forward-Proxy erreicht, setzen Sie `oidc.use_proxy: true`; geben Sie dem Pod bei Versionen vor v2.1.227 stattdessen eine direkte Route zu jedem Endpunkt des IdP. Wenn der Pod zusätzlich den Hostnamen des IdP nicht auflösen kann oder der Proxy `CONNECT` zu einer IP-Adresse ablehnt, siehe Egress nur über Proxy, was v2.1.277 oder neuer erfordert.
Der Start bricht mit einem Postgres-Berechtigungsfehler ab	Der Datenbankrolle fehlen DDL-Rechte für ihr Schema	Erteilen Sie der Rolle `CREATE` für das Schema des Gateways, damit es beim Start seine Tabellen erstellen und ändern kann
Log: `remaining connection slots are reserved` oder `sorry, too many clients already`, von PostgreSQL. Das erscheint in den Warnungen `postgres connection closed` laufender Replikate oder im Start-Log eines neuen Replikats. Dort kann `remaining connection slots are reserved` auf `attempt 1 of 3` folgen, und das Replikat startet möglicherweise trotzdem.	Die Replikate fordern mehr Verbindungen an, als die Datenbank für das Gateway noch frei hat, und PostgreSQL lehnt die zusätzlichen ab	Sorgen Sie dafür, dass die Gesamtzahl passt, wie unter Den Connection-Pool dimensionieren beschrieben: Betreiben Sie weniger Replikate, senken Sie `store.max_connections` oder erhöhen Sie `max_connections` der Datenbank. Wenn die Gesamtzahl außer während eines Rolling Updates passt, können Sie stattdessen Ihren Orchestrator ein altes Replikat stoppen lassen, bevor er ein neues startet, sofern er das unterstützt.
Log: `could not connect to Postgres at boot, attempt 1 of 3`, mit einem anderen Grund als `remaining connection slots are reserved`	Die Datenbank war beim Start des Gateways noch nicht erreichbar, zum Beispiel bei einer kalten Instanz, deren Netzwerk noch hochfährt	Wenn das Gateway den Start anschließend abschließt, ist nichts zu tun. Wenn die Datenbank nicht erreichbar ist, versucht das Gateway die Verbindung dreimal im Abstand von zwei Sekunden, bevor es sich beendet. Wenn es sich mit `could not connect to Postgres` beendet, prüfen Sie `store.postgres_url`, einschließlich dass genau ein Host angegeben ist, sowie den Netzwerkpfad zur Datenbank. Wenn die Versuche in einen Timeout laufen, statt abgelehnt zu werden, erhöhen Sie `store.connect_timeout_seconds`, um jedem Versuch mehr Zeit zu geben.
Log: `Postgres <version> is below the supported floor`	Die Datenbank läuft mit einer PostgreSQL-Version, die älter ist, als Ihre Gateway-Version unterstützt. Das Gateway läuft weiter.	Aktualisieren Sie die Datenbank. Bei PostgreSQL 11, 12 oder 13 können Sie stattdessen das Gateway aktualisieren, um die PostgreSQL-Anforderung zu erfüllen.
`/oauth/callback` zeigt „Sign-in could not be completed“	E-Mail-Domain abgelehnt, Validierung des id_token fehlgeschlagen oder `email_verified` explizit `false`, was das Gateway immer ohne Überschreibungsmöglichkeit ablehnt	Prüfen Sie `allowed_email_domains` und ob der IdP einen verifizierten `email`-Claim zurückgibt. Beheben Sie bei `email_verified: false` die Verifizierung auf IdP-Seite. Wenn Ihr IdP die E-Mail unter einem anderen Claim-Namen ausgibt, setzen Sie `oidc.email_claim`.
Log: `token exchange failed request_id=<id>: id_token missing email claim`	Der IdP nimmt `email` standardmäßig nicht in das id_token auf. Diese Ablehnung tritt nur auf, wenn `allowed_email_domains` gesetzt ist; ohne diese Einstellung erzeugt eine fehlende E-Mail eine Sitzung ohne E-Mail	Konfigurieren Sie den IdP so, dass er `email` im id_token ausgibt. Okta: Fügen Sie `email` zu den ID-Token-Claims eines benutzerdefinierten Autorisierungsservers hinzu. Entra: Fügen Sie `email` als optionalen Claim zur App-Registrierung hinzu. PingFederate: Aktivieren Sie eine OpenID Connect Policy, die `email` ausgibt. Wenn der IdP `email` über den Userinfo-Endpunkt bereitstellt, es aber nicht in das id_token aufnimmt, wie etwa der Okta-Org-Autorisierungsserver, setzen Sie `oidc.userinfo_fallback: true`.
Log: `refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`, und Entwickler sehen `Cloud gateway session expired` alle `session.ttl_hours`	Der IdP hat das Refresh-Token akzeptiert, aber kein id_token dazu zurückgegeben, daher hat das Gateway den Userinfo-Endpunkt des IdP nach den Claims des Benutzers gefragt. Der IdP hat dort das erneuerte Access-Token abgelehnt. Das Gateway antwortet mit `temporarily_unavailable`, sodass Claude Code das Refresh-Token behält, die Sitzung aber nicht erneuern kann. Gateway-Versionen vor v2.1.260 protokollieren dieselbe Zeile ohne das Detail `(at …)`.	Setzen Sie `oidc.scope_on_refresh: true`, verfügbar ab Gateway v2.1.260, damit die Refresh-Anfrage erneut `openid` anfordert. Manche IdPs wie Okta geben beim Refresh nur dann ein id_token zurück, wenn es angefordert wird. Aktivieren Sie bei PingFederate stattdessen Return ID Token On Refresh Grant unter Applications > OAuth > OpenID Connect Policy Management. Der Schlüssel ändert das Verhalten von PingFederate nicht. Prüfen Sie bei anderen IdPs, die es weiterhin weglassen, ob der Userinfo-Endpunkt Access-Tokens akzeptiert, die durch einen Refresh ausgestellt wurden. Erhöhen Sie als Übergangslösung `session.ttl_hours`. Siehe Einrichtung des Identitätsanbieters für den Zielkonflikt beim Deprovisioning.
Ein Entwickler meldet sich an, dann schlägt jede Anfrage aus dieser Sitzung mit einem `431`-Fehler fehl	Das Sitzungs-Token im `Authorization`-Header jeder Anfrage listet die IdP-Gruppen des Entwicklers auf, sodass die Header bei einem Entwickler in vielen Gruppen insgesamt mehr umfassen können, als das Gateway akzeptiert	Siehe Request-Header nach der Anmeldung zu groß, um zu erfahren, welches Limit gilt und was Sie ändern müssen
Jede Amazon Bedrock-Anfrage gibt 502 zurück; das Log zeigt `Could not load credentials from any providers`	Auf EC2 blockiert das standardmäßige Hop-Limit von 1 bei IMDSv2 die Instance-Metadata-Anfrage aus dem Container heraus. Start und `/readyz` sind trotzdem erfolgreich, weil das AWS SDK die Instanz-Anmeldedaten erst bei der ersten Anfrage auflöst, nicht beim Erstellen des Clients	Erhöhen Sie das Hop-Limit mit `aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2` oder setzen Sie es im Launch Template. Die Änderung gilt für jeden Container auf der Instanz. Bevorzugen Sie nach Möglichkeit ECS-Task-Rollen, die Anmeldedaten vom ECS-Container-Credentials-Endpunkt lesen und die Änderung ganz vermeiden, oder nehmen Sie die Änderung auf einer dedizierten Gateway-Instanz vor, um die Angriffsfläche zu begrenzen.
Log: eine Warnung, die `upstream <name>: Google issued an access token that expires in <N>s` enthält, bei einem Upstream, dessen Google-Anmeldedatendatei den Typ `external_account` hat	Anfragen sind erfolgreich, bis dieses Access-Token abläuft, und schlagen dann fehl, sofern das Token, auf das `credential_source` verweist, nicht vorher erneuert wurde.	Wenn ein Prozess dieses Token in eine Datei schreibt, lassen Sie ihn mehr als fünf Minuten vor Ablauf des alten Tokens ein neues schreiben
Bei Spitzenlast beginnen Antworten verzögert oder scheinen zu hängen, oder sie schlagen mit einem 502 `all upstreams failed` fehl, obwohl der Upstream fehlerfrei ist	Ein Replikat hat mehr Anfragen offen, als es gleichzeitig an den Upstream sendet, sodass die zusätzlichen Anfragen im Gateway warten. Bei einem `provider: anthropic`-Upstream gibt eine Anfrage, die länger als `timeouts.upstream_ttfb_ms` wartet, diesen Upstream auf, was den 502 erzeugt, wenn kein nachfolgender Upstream sie bedient. Das Log zeigt eine Warnung, die `client requests are open` enthält.	Fügen Sie Replikate hinzu oder erhöhen Sie das Limit für jedes Replikat. Siehe Gleichzeitige Upstream-Anfragen.
Bei einem anderen Upstream als `provider: anthropic` schlägt ein Turn mit einer langen Denkpause fehl. Der Proxy vor dem Gateway protokolliert eine Anfrage, die etwa 12,5 Minuten offen bleibt, dann eine Reihe von `504`-Fehlern	Claude Code hat einen Stream beendet, der sein erstes Antwort-Event geliefert und danach nur noch Keepalive-Pings übertragen hatte. Es hat die Anfrage ohne Streaming erneut gesendet, und jede Antwort dauert länger als der Timeout des Proxys.	Erhöhen Sie `CLAUDE_STREAM_IDLE_TIMEOUT_MS` für Ihre Entwickler. Siehe Langes Thinking endet in Proxy-Timeouts.
Bei `provider: anthropic` schlägt ein Turn mit einer langen Denkpause fehl. Der Proxy protokolliert eine Anfrage, die etwa 20 Minuten offen ist, dann `502`- oder `504`-Fehler	Claude Code hat einen Stream beendet, der sein erstes Antwort-Event geliefert und danach nur noch Keepalive-Pings übertragen hatte. Es hat die Anfrage ohne Streaming erneut gesendet, und jede Antwort dauert länger als die Wartezeit des Gateways auf den Upstream, `timeouts.upstream_ttfb_ms`, oder der Timeout des Proxys.	Erhöhen Sie `CLAUDE_STREAM_IDLE_TIMEOUT_MS` für Ihre Entwickler. Siehe Langes Thinking bei einem Anthropic API-Upstream.
Die Anfragen eines Entwicklers schlagen fehl mit `API Error: 400 you aren't in a group that can use this gateway. Ask your administrator to add you to one`	Jeder Upstream hat eine `groups`-Liste, und die Sitzung des Entwicklers enthält keine der aufgeführten Gruppen.	Fügen Sie den Entwickler in Ihrem IdP einer aufgeführten Gruppe hinzu, oder führen Sie als letzten Eintrag einen Upstream ohne `groups` auf, der alle anderen bedient. Das Gateway liest die Gruppen bei der nächsten Token-Aktualisierung des Entwicklers erneut. Wenn der IdP die Gruppen weggelassen hat und sein Userinfo-Endpunkt sie zurückgibt, setzen Sie `oidc.userinfo_fallback: true`.
IdP-Fehler: unbekannter oder nicht unterstützter Scope	Der IdP lehnt Scopes ab, die er nicht kennt	Setzen Sie `oidc.scopes` auf genau die Liste, die Ihr IdP akzeptiert; sie muss `openid` enthalten. Der Standardwert ist `openid profile email offline_access`.
Sitzungen werden nach dem Setzen von `oidc.scopes` nicht mehr unbemerkt erneuert	`offline_access` wurde aus der Überschreibung entfernt	Fügen Sie `offline_access` wieder hinzu, sofern Ihr IdP es unterstützt. Ohne Refresh-Token müssen Entwickler die Browser-Anmeldung alle `session.ttl_hours` erneut durchführen.
Der Browser zeigt „This request came from another site and was blocked“	Websiteübergreifender Formular-POST, als CSRF-Schutz blockiert. Bei eingebetteten oder über einen Proxy ausgelieferten Seiten zu erwarten	Öffnen Sie den Verifizierungslink direkt
Chrome blockiert die Schaltfläche „Approve“ mit „Refused to send form data … violates … Content Security Policy directive: form-action“, während dieselbe Seite in Safari oder Firefox funktioniert	Chrome wendet `form-action` auf die gesamte Weiterleitungskette an. Ihr IdP leitet weiter an einen zweiten Host, der nicht auf der Zulassungsliste steht.	Fügen Sie jeden zusätzlichen Origin in der Weiterleitungskette zu `oidc.form_action_origins` hinzu. Öffnen Sie auf der Approve-Seite Chrome DevTools → Console, um zu sehen, welcher Origin blockiert wurde.
Die Anmeldung wird beim IdP abgeschlossen, aber der Callback schlägt fehl, mit einem CSP-Fehler in Chrome oder „this sign-in link has expired“ in Safari	Der IdP hat den Code über `response_mode=form_post` zurückgegeben, wodurch er automatisch per POST Origin-übergreifend an `/oauth/callback` übermittelt wird. Chrome blockiert das unter einer strikten CSP; Safari lässt die Übermittlung zu, aber der Callback liest nur den Query-String.	Stellen Sie sicher, dass Ihr IdP `response_mode=query` berücksichtigt, was das Gateway explizit anfordert, damit der Callback eine einfache Weiterleitung ist
Die Anmeldung funktioniert lokal, schlägt aber hinter einem ALB fehl	`public_url` nennt noch den lokalen oder inneren `http://`-Origin, sodass der IdP die falsche `redirect_uri` erhält	Setzen Sie `listen.public_url` auf den externen `https://`-Origin und registrieren Sie `<public_url>/oauth/callback` beim IdP
Der Entwickler sieht die Vertrauensabfrage wiederholt	Das TLS-Zertifikat wechselt pro Replikat oder pro Anfrage	Verwenden Sie am Ingress ein stabiles Zertifikat, oder terminieren Sie TLS einmal und betreiben Sie die Replikate intern über reines HTTP
CLI-`/login`: „Could not verify the gateway’s TLS certificate“ oder `SELF_SIGNED_CERT_IN_CHAIN`	Die TLS-Kette des Gateways ist von einer privaten CA signiert, die nicht im Trust Store des CLI-Hosts enthalten ist	Claude Code liest bei der nativen Binärdatei und unter Node 22.15 oder neuer standardmäßig den Trust Store des Betriebssystems; `CLAUDE_CODE_CERT_STORE` steuert dieses Verhalten. Wenn die CA im Trust Store des Betriebssystems installiert ist, stellen Sie sicher, dass Entwickler eine aktuelle Runtime verwenden. Setzen Sie andernfalls vor dem Start `NODE_EXTRA_CA_CERTS` auf das PEM des CA-Zertifikats. Die Fingerprint-Abfrage bei der ersten Verbindung gilt weiterhin.
CLI-`/login` schließt die Browser-Anmeldung ab, dann endet die Sitzung mit `Cloud gateway sign-in was not completed` und einer TLS-Zertifikatsabweichung	Bei der ersten Anfrage nach der Anmeldung hat das Gateway ein Zertifikat präsentiert, das nicht dem von Claude Code gepinnten Fingerprint entspricht, sodass Claude Code keine Gateway-Anmeldedaten behalten hat. Die üblichen Ursachen sind Replikate hinter einer Adresse, die unterschiedliche Zertifikate ausliefern, oder etwas auf dem Netzwerkpfad, das TLS abfängt.	Liefern Sie für den Hostnamen ein einziges Zertifikat aus, zum Beispiel indem Sie TLS einmal am Ingress terminieren, und lassen Sie den Entwickler dann `/login` erneut ausführen. Wenn sich dieses Zertifikat vom gepinnten unterscheidet, zeigt Claude Code die Vertrauensabfrage erneut mit einem Hinweis an, dass sich das Zertifikat geändert hat.
CLI-`/login` stoppt mit `The gateway's TLS certificate changed during sign-in: it no longer matches the one you trusted`	Eine Anmeldeanfrage hat einen Server erreicht, dessen Zertifikat nicht dem entspricht, das der Entwickler beim Start von `/login` akzeptiert hat: Replikate hinter einer Adresse mit unterschiedlichen Zertifikaten, TLS-Interception auf dem Pfad oder eine Zertifikatsrotation während der laufenden Anmeldung.	Liefern Sie für den Hostnamen ein einziges Zertifikat aus, lassen Sie den Entwickler die Anmeldung dann erneut starten und das neue Zertifikat in der Vertrauensabfrage prüfen.

Die Meldung Cloud gateway sign-in was not completed nennt den Hostnamen des Gateways. Wenn Claude Code sowohl den gepinnten als auch den präsentierten Fingerprint hat, zeigt die Meldung außerdem jeweils die ersten 16 Zeichen. Wenn Claude Code nach einer Gateway-Anmeldung couldn't load your organization's managed settings meldet, nennt Claude Code den Grund, startet an Ort und Stelle neu und setzt die Konversation fort. Wenn Claude Code nicht neu starten kann, zum Beispiel in einer Hintergrundsitzung, beendet Claude Code die Sitzung und behält die Anmeldung bei. Die Anfragen eines Entwicklers können nach der Anmeldung mit einem 431-Fehler fehlschlagen, wenn der Entwickler vielen IdP-Gruppen angehört. Das Gateway antwortet mit 431, wenn die Header einer Anfrage insgesamt mehr als 256 KiB umfassen, oder mehr als limits.max_request_header_bytes, sofern Sie diesen Wert gesetzt haben. Für diese Anfragen schreibt es weder eine Log-Zeile noch ein Audit-Event. Gateway-Versionen vor v2.1.284 antworten oberhalb von 16 KiB mit 431. Beginnen Sie mit dem ersten der folgenden Punkte, der auf Ihr Gateway zutrifft:

Gateway älter als v2.1.284: Aktualisieren Sie das Gateway
limits.max_request_header_bytes gesetzt: Erhöhen Sie den Wert oder entfernen Sie den Schlüssel
Keines von beiden trifft zu, oder 431 tritt danach weiterhin auf: Lassen Sie Ihren IdP weniger Gruppen ausgeben. Einrichtung des Identitätsanbieters beschreibt, wie Okta, Microsoft Entra ID und Google Workspace Gruppen bereitstellen

Wenn Sie den Groups-Claim kürzen, behalten Sie die Gruppen bei, die Sie in diesen Einstellungen angegeben haben, da sie über Zugriff, Richtlinie, Upstreams und Ausgabenobergrenzen eines Entwicklers entscheiden:

oidc.allowed_groups: entscheidet, wer sich anmelden kann
admin.admin_groups: entscheidet, wer die Admin-API mit seiner Gateway-Sitzung aufrufen kann
match.groups in managed.policies: entscheidet, welche Richtlinie für einen Entwickler gilt
groups bei einem Upstream: entscheidet, welche Upstreams einen Entwickler bedienen
rbac_group-Ausgabenobergrenzen: entscheiden, welche Gruppenobergrenzen für einen Entwickler gelten

Langes Thinking endet in Proxy-Timeouts

Wenn Ihr Upstream provider: anthropic ist, verwenden Sie stattdessen Langes Thinking bei einem Anthropic API-Upstream: Auch dort erhöhen Sie CLAUDE_STREAM_IDLE_TIMEOUT_MS, aber die Zeiten und Fehler unterscheiden sich. Wenn Turns nach langem Thinking fehlschlagen und Ihr Proxy eine Anfrage protokolliert, die etwa 12,5 Minuten offen ist, gefolgt von einer Reihe von 504-Fehlern, erhöhen Sie CLAUDE_STREAM_IDLE_TIMEOUT_MS in einer Gateway-Richtlinie. Bei einem Leerlauf-Timeout von 240 Sekunden am Proxy besteht die Reihe beispielsweise aus 10 Anfragen, die jeweils nach 240 Sekunden abgebrochen werden.

Die erste Anfrage: ein Stream, der sein erstes Antwort-Event, message_start, liefert und danach nur noch Pings, während Claude nachdenkt. Mit den Standardeinstellungen beendet Claude Code diesen Stream nach etwa 12,5 Minuten.
Die anderen 10: dieselbe Anfrage, ohne Streaming gesendet und dann erneut versucht, standardmäßig insgesamt 10 Sendevorgänge. Sie erhalten keine Pings, sodass eine langsame Antwort den Timeout des Proxys erreicht.

Für diese Lösung benötigen Sie keinen längeren Proxy-Timeout. Wenn Sie nur den Timeout des Proxys erhöhen, schlagen Anfragen ohne Streaming weiterhin fehl, sobald eine Antwort länger dauert als die eigene Wartezeit von Claude Code, standardmäßig 300 Sekunden.

Die Ursache bestätigen

Lassen Sie einen Entwickler den Fehler mit claude --debug-file ./claude-debug.txt reproduzieren und durchsuchen Sie dann diese Datei nach folgender Zeile:

Error streaming, falling back to non-streaming mode: Stream idle timeout - no chunks received

Wenn Ihre Entwickler CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK bereits auf 1 setzen, sehen Sie keine Anfragen ohne Streaming, und der Turn endet mit API Error: Stream idle timeout - no chunks received. Es gilt dieselbe Lösung.

Einen Wert wählen

Wählen Sie einen Wert für CLAUDE_STREAM_IDLE_TIMEOUT_MS, dessen zweite Spalte Ihre längste Denkpause abdeckt, oder beginnen Sie mit 1800000, wenn Sie diese nicht kennen. Ein Stream kann etwa 7,5 Minuten länger als der Wert nur mit Pings bestehen bleiben:

`CLAUDE_STREAM_IDLE_TIMEOUT_MS`	Ein Stream kann nur mit Pings bestehen bleiben für
`300000`, der Standardwert	Etwa 12,5 Minuten
`900000`	Etwa 22,5 Minuten
`1800000`	Etwa 37,5 Minuten

Wenn ein Upstream hängt, während das Gateway weiterhin Pings sendet, warten Ihre Entwickler ebenfalls so lange, bevor Claude Code den Stream aufgibt. Eine Verbindung, die vollständig verstummt, endet trotzdem nach 5 bis 6 Minuten, da der Body-Leerlauf-Timeout dieser Variable nicht folgt.

Den Wert in einer Richtlinie bereitstellen

Fügen Sie den env-Eintrag zu jeder Richtlinie in gateway.yaml hinzu, die bereits Claude Code-Einstellungen an die Entwickler liefert, die Sie abdecken möchten. Platzieren Sie ihn unter dem Schlüssel code, cli oder settings, den diese Richtlinie bereits hat. Um den Wert zunächst zu testen, beginnen Sie mit einer Richtlinie, die auf eine Gruppe passt. Unter managed erfahren Sie, wie Richtlinien zugeordnet und vererbt werden. Dieses Beispiel fügt den Eintrag einer match: {}-Richtlinie mit dem Schlüssel cli hinzu:

managed:
  policies:
    - match: {}
      cli:
        env:
          CLAUDE_STREAM_IDLE_TIMEOUT_MS: "1800000"

Mit dem Schlüssel cli decken Sie Terminal-, IDE-Erweiterungs- und Agent SDK-Sitzungen ab. Für den Code-Tab von Claude Desktop siehe cli oder code wählen. Starten Sie das Gateway neu, damit es die bearbeitete Datei liest. Lassen Sie die Entwickler dann Claude Code neu starten, um CLAUDE_STREAM_IDLE_TIMEOUT_MS zu erhalten.

Langes Thinking bei einem Anthropic API-Upstream

Wenn provider: anthropic der einzige Upstream des Modells ist und Ihr Proxy eine Anfrage protokolliert, die etwa 20 Minuten offen ist, gefolgt von 502- oder 504-Fehlern, erhöhen Sie CLAUDE_STREAM_IDLE_TIMEOUT_MS in einer Gateway-Richtlinie.

Die lange Anfrage: ein Stream, der message_start liefert und danach nur noch Pings, während Claude nachdenkt. Claude Code beendet ihn mit den Standardeinstellungen nach etwa 20 Minuten, und später, sobald Sie die Variable erhöhen.
Die Fehler: Anfragen, die Claude Code anschließend ohne Streaming sendet. Jede schlägt mit einem 502 vom Gateway fehl, oder mit dem 504 Ihres Proxys, wenn dessen Timeout kürzer ist als die Wartezeit des Gateways. Diese Wartezeit ist timeouts.upstream_ttfb_ms, die Sie für diese Lösung nicht erhöhen müssen.

Um die Ursache zu bestätigen, siehe Die Ursache bestätigen. Wählen Sie den Wert, dessen Zeit Ihre längste Denkpause abdeckt: etwa 20 Minuten beim Standardwert, 30 bei 900000 und 45 bei 1800000. Folgen Sie dann Den Wert in einer Richtlinie bereitstellen.

Claude-Apps-Gateway-Übersicht: Schnellstart und Entwickler-Verbindung
Konfigurationsreferenz: Jede gateway.yaml-Option

Einrichtung und Zugriff

Bereitstellung

Gateways

Nutzung und Kosten

Sicherheit und Daten

Einführung

Bereitstellung und Betrieb des Claude-Apps-Gateways

Identitätsanbieter-Setup

Bereitstellung

Adresse für das Gateway wählen

Container-Image

Kubernetes

Cloud Run

Pushen Sie die Gateway-URL zu Entwicklermaschinen

Große Rollouts

Betrieb

Logs

Betriebs-Logs als JSON schreiben

Zustand

Gleichzeitige Upstream-Anfragen

`API_TIMEOUT_MS` über der Zeit bis zum ersten Byte des Gateways halten

Eine unbeantwortete Anfrage mit der First-Byte-Frist früher erneut versuchen

Verhalten bei Ausfällen

Readiness-Kulanzzeit

Rotation des JWT-Secrets

Postgres

Den Verbindungspool dimensionieren

Upgrades

Sicherheit

Datenfluss

Bedrohungsmodell-Zusammenfassung

User-Code-Brute-Force-Resistenz

Compliance-Haltung

Plugin-Marketplace-Anfragen

Fehlerbehebung

Langes Thinking endet in Proxy-Timeouts

Die Ursache bestätigen

Einen Wert wählen

Den Wert in einer Richtlinie bereitstellen

Langes Thinking bei einem Anthropic API-Upstream

​Identitätsanbieter-Setup

​Bereitstellung

​Adresse für das Gateway wählen

​Container-Image

​Kubernetes

​Cloud Run

​Pushen Sie die Gateway-URL zu Entwicklermaschinen

​Große Rollouts

​Betrieb

​Logs

​Betriebs-Logs als JSON schreiben

​Zustand

​Gleichzeitige Upstream-Anfragen

​API_TIMEOUT_MS über der Zeit bis zum ersten Byte des Gateways halten

​Eine unbeantwortete Anfrage mit der First-Byte-Frist früher erneut versuchen

​Verhalten bei Ausfällen

​Readiness-Kulanzzeit

​Rotation des JWT-Secrets

​Postgres

​Den Verbindungspool dimensionieren

​Upgrades

​Sicherheit

​Datenfluss

​Bedrohungsmodell-Zusammenfassung

​User-Code-Brute-Force-Resistenz

​Compliance-Haltung

​Plugin-Marketplace-Anfragen

​Fehlerbehebung

​Request-Header nach der Anmeldung zu groß

​Langes Thinking endet in Proxy-Timeouts

​Die Ursache bestätigen

​Einen Wert wählen

​Den Wert in einer Richtlinie bereitstellen

​Langes Thinking bei einem Anthropic API-Upstream

​Verwandt

Identitätsanbieter-Setup

Bereitstellung

Adresse für das Gateway wählen

Container-Image

Kubernetes

Cloud Run

Pushen Sie die Gateway-URL zu Entwicklermaschinen

Große Rollouts

Betrieb

Logs

Betriebs-Logs als JSON schreiben

Zustand

Gleichzeitige Upstream-Anfragen

`API_TIMEOUT_MS` über der Zeit bis zum ersten Byte des Gateways halten

Eine unbeantwortete Anfrage mit der First-Byte-Frist früher erneut versuchen

Verhalten bei Ausfällen

Readiness-Kulanzzeit

Rotation des JWT-Secrets

Postgres

Den Verbindungspool dimensionieren

Upgrades

Sicherheit

Datenfluss

Bedrohungsmodell-Zusammenfassung

User-Code-Brute-Force-Resistenz

Compliance-Haltung

Plugin-Marketplace-Anfragen

Fehlerbehebung

Request-Header nach der Anmeldung zu groß

Langes Thinking endet in Proxy-Timeouts

Die Ursache bestätigen

Einen Wert wählen

Den Wert in einer Richtlinie bereitstellen

Langes Thinking bei einem Anthropic API-Upstream

Verwandt