Bereitstellung und Betrieb des Claude-Apps-Gateways

Registrieren Sie das Gateway bei Ihrem IdP, erstellen Sie den Container, stellen Sie ihn auf Kubernetes oder Cloud Run bereit, und betreiben Sie ihn: Integritätsprüfungen, Geheimnisrotation, Upgrades und Sicherheit.

[!NOTE]

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.

1. 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
2. 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
3. Richten Sie den Betrieb ein: Protokolle, Integritätsprüfungen, Ausfallverhalten, Geheimnisrotation und Upgrades. Referenzmaterial für die Einrichtung von Überwachung und Runbooks
4. Ü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 }.

[!WARNING]

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:

1. 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.
2. Überprüfen Sie es gegen die GPG-signierte manifest.json der Version, wie in Binäre Integrität und Code-Signierung beschrieben.
3. 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 plus zusätzliche Pakete; siehe Alpine-Linux-Setup.
• 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.

[!WARNING]

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:

1. Generieren Sie ein neues Secret. Stellen Sie es dem Array session.jwt_secret voran.
2. Rollen Sie das Deployment aus. Neue Token werden mit dem neuen Secret signiert; alte Token werden weiterhin verifiziert.
3. 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:

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.

[!WARNING]

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

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.

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.

Request-Header nach der Anmeldung zu groß

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:

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.

Verwandt

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