SpyBara
Go Premium

claude-apps-gateway-deploy.md 2026-09-18 23:58 UTC to 2026-09-19 23:57 UTC

This page contains 75 additions and 4 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Fri 18 23:58 Sat 19 23:57 Fri 25 23:58

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.

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.

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 }.

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 und Ihr IdP es über HTTPS erreichen können, und behandeln Sie es wie jeden anderen Dienst, der eine 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.

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. Ohne dies zeigt /login den Standard-Account-Picker ohne Gateway-Option.

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. Setzen Sie es vor allem anderen. Das Gateway protokolliert eine Warnung, wenn es zum ersten Mal einen X-Forwarded-For-Header ignoriert.
  • 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 Verkehr bedient, ist der tägliche Betrieb das Lesen seiner Protokolle, das Prüfen seiner Integrität und das Rotieren seiner Geheimnisse nach Ihrem Zeitplan. Die Unterabschnitte behandeln jeweils, plus was Postgres hält und wie Upgrades und Rollbacks sich verhalten.

Protokolle

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

  • Audit-Events: einzeilige JSON pro sicherheitsrelevantes Event. Leiten Sie stderr an Ihren Log-Aggregator.

    Die ausgegebenen Events umfassen 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. Felder variieren je nach Event:

    • Erfolgreiche Mint- und Refresh-Events tragen sub, email, client_ip und das Ergebnis
    • auth.denied und access.denied tragen den Grund und die Client-IP, plus den Anfragepfad für auth.denied, da bei diesen Ablehnungen keine Benutzeridentität existiert. Zwei access.denied-Gründe ändern, was das Event trägt:
      • xff_unparseable: das Event trägt auch den X-Forwarded-For-Eintrag, der nicht gelesen werden konnte
      • client_ip_unknown: das Event trägt keine Client-IP, da die Verbindung keine Peer-Adresse hatte, während eine access_control-Liste gesetzt war
    • access.public_client trägt die Client-IP der ersten Anfrage pro Prozess, die von einer öffentlichen Adresse ankommt, während access_control.allow_cidrs leer ist. Das Gateway bedient die Anfrage wie gewohnt; das Event signalisiert, dass das Gateway möglicherweise vom öffentlichen Internet erreichbar ist. Siehe die access_control-Referenz für das, was als öffentlich zählt, und für die empfohlene Allow-Liste.
    • inference zeichnet auf, welcher Upstream die Anfrage bedient hat und den Antwortstatus
    • desktop_bootstrap.denied zeichnet einen abgelehnten Claude Desktop Bootstrap-Abruf mit dem Grund (not_configured, policy_not_opted_in oder no_policy_matched) und der Identität des Benutzers auf
    • admin.denied zeichnet einen abgelehnten Admin-API-Auth-Versuch mit der Client-IP, Methode, Pfad und einem Grund auf, ohne das präsentierte Schlüsselmaterial: invalid_key, wenn ein x-api-key präsentiert wurde, aber keinen konfigurierten Schlüssel entsprach, bearer_rejected, wenn nur ein Authorization-Header präsentiert wurde und er sich nicht als Gateway-Sitzung in admin.admin_groups verifizierte, oder no_credentials, wenn keiner der Header präsentiert wurde

  • Operationale Protokolle: lesbare [gateway]-präfixierte Zeilen für Boot, Warnungen und Upstream-Fehler. Die Umgebungsvariable CLAUDE_GATEWAY_LOG_LEVEL steuert die Ausführlichkeit und akzeptiert debug, info, warn oder error, mit info als Standard. Bei debug protokolliert jede Anmeldung und Aktualisierung auch die Namen, nicht die Werte, der Ansprüche im id_token, plus die Namen der userinfo-Ansprüche, wenn userinfo_fallback welche bereitgestellt hat, damit Sie email_claim- und groups_claim-Einstellungen diagnostizieren können, ohne PII zu protokollieren. Es beeinflusst keine Audit-Events, die immer ausgegeben werden.

Integrität

Das Gateway bedient GET /healthz als Liveness-Probe und GET /readyz als Readiness-Probe; /readyz überprüft, dass der Store erreichbar ist. Beide sind von access_control.allow_cidrs ausgenommen, daher funktionieren Proben auf einem abgesperrten Listener.

Das OAuth-Discovery-Dokument unter /.well-known/oauth-authorization-server gibt auch 200 nur zurück, nachdem Konfigurationslast, OIDC-Erkennung, Upstream-Client-Konstruktion und Postgres-Migration alle erfolgreich sind, daher dient es auch als End-to-End-Boot-Prüfung.

Gleichzeitige Upstream-Anfragen

Standardmäßig sendet jede Gateway-Replikation höchstens 256 Anfragen gleichzeitig Upstream. Eine Streaming-Antwort zählt gegen das Limit, bis der Stream endet.

Eine Anfrage, die ankommt, während eine Replikation das Limit erreicht hat, wartet innerhalb des Gateways auf einen freien Slot. Der Entwickler sieht eine Antwort, die langsam zu starten ist oder zu hängen scheint. Bei einem provider: anthropic Upstream 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 es bedient.

Die Startup-Protokollzeile, die upstream requests: enthält, zeigt das geltende Limit. Während eine Replikation mehr Anfragen offen hat als das Limit, protokolliert sie auch eine Warnung, die client requests are open enthält, höchstens einmal pro Minute.

Um mehr Anfragen gleichzeitig zu bedienen, haben Sie zwei Optionen:

  • Fügen Sie Replikationen hinzu.
  • Erhöhen Sie das Limit auf jeder Replikation. Setzen Sie die Umgebungsvariable BUN_CONFIG_MAX_HTTP_REQUESTS auf dem Gateway-Container auf eine ganze Zahl von 1 bis 65535, dann starten Sie den Container neu.

Eine Replikation füllt ihr Limit bei einer Anfragerate von etwa dem Limit geteilt durch die durchschnittliche Anzahl von Sekunden, die eine Anfrage offen bleibt. Wenn Anfragen beispielsweise durchschnittlich 10 Sekunden offen bleiben, füllt eine Replikation mit dem Standardlimit von 256 es bei etwa 26 Anfragen pro Sekunde.

Wenn Sie auf CPU autoskalieren, wartet eine Replikation am Limit Anfragen in die Warteschlange, ohne einen Scale-Out auszulösen, daher setzen Sie das Ziel unter die CPU-Ebene, die Ihre Replikationen zeigen, wenn sie die Warnung client requests are open protokollieren.

Ausfallverhalten

Wenn Postgres ausfällt, bedient das Gateway selbst weiterhin angemeldete Entwickler und neue Anmeldungen schlagen fehl. Ob Entwickler tatsächlich weiterarbeiten, hängt davon ab, wie Ihr Orchestrator die Readiness handhabt:

  • Bestehende Sitzungen: Bearer-Tokens validieren lokal mit dem JWT-Geheimnis, Sitzungs-Refreshes berühren den Store nicht, und der Gateway-Prozess kann immer noch Inferenz bedienen
  • Neue Anmeldungen: schlagen fehl, bis Postgres wiederhergestellt ist, da der Device-Flow und seine Rate-Limit-Zähler in Postgres leben
  • Spend-Limit-Durchsetzung: schlägt während des Ausfalls offen fehl, daher fließt Inferenz weiterhin; schalten Sie es auf Fail-Closed um, wenn Sie lieber blockieren als ungemessen laufen möchten
  • Readiness: /readyz meldet während des Ausfalls nicht bereit, daher entfernen Orchestratoren, die Verkehr auf Readiness gating, jede Replikation auf einmal aus der Rotation. In dieser Topologie schlägt der gesamte Verkehr, einschließlich Inferenz, die das Gateway immer noch bedienen könnte, beim Load Balancer fehl, bis Postgres wiederhergestellt ist. Die Liveness-Probe auf /healthz bleibt bestehen, daher werden Replikationen nicht neu gestartet. Zeigen Sie die Readiness-Probe statt auf /healthz, wenn Sie lieber möchten, dass angemeldete Entwickler durch einen Store-Ausfall weiterarbeiten; die Kosten sind, dass neue Anmeldungen gegen eine Replikation fehlschlagen, die immer noch bereit meldet.

Wenn Ihr IdP ausfällt, funktionieren bestehende Sitzungen bis ttl_hours, und neue Anmeldungen und Refreshes schlagen fehl. Setzen Sie eine längere ttl_hours, wenn Ihr IdP häufige Wartungsfenster hat.

JWT-Geheimnisrotation

Rotieren Sie das Signierungsgeheimnis in Stufen, damit bestehende Sitzungen gültig bleiben:

  1. Generieren Sie ein neues Geheimnis. Stellen Sie es dem session.jwt_secret-Array voran.
  2. Rollen Sie die Bereitstellung aus. Neue Tokens signieren mit dem neuen Geheimnis; alte Tokens validieren immer noch.
  3. Nach ttl_hours plus einer Marge entfernen Sie das alte Geheimnis und rollen erneut aus.

Rotation ist auch die einzige Möglichkeit, Sitzungen vor Ablauf zu erzwingen: Bearer-Tokens validieren lokal gegen das JWT-Geheimnis, daher gibt es keine Pro-Sitzungs-Sperrung. Das Ersetzen des Geheimnisses direkt, ohne das alte in dem Array zu behalten, invalidiert jede ausstehende Sitzung auf einmal. Für einzelnes Offboarding deprovisioning Sie den Benutzer in Ihrem IdP; ihre Sitzung endet innerhalb von ttl_hours.

Postgres

Das Gateway hält fünf Datentabellen plus eine _migrations-Tabelle, alle erstellt durch seine Boot-Zeit-Migrationen:

Tabelle Inhalt Aufbewahrung
kv Device-Grants (10-Minuten-TTL) und Rate-Limit-Zähler TTL pro Zeile
spend Pro-Principal-Periode-bis-Datum-Spend-Zähler, in Cent admin.spend_retention_months, Standard 13
spend_limits Konfigurierte Spend-Caps Bis gelöscht über die API
admin_audit Admin-API-Mutations-Trail admin.audit_retention_days, Standard 365
principal_emails E-Mail, Anzeigename und IdP-Gruppen jedes Principal. Enthält PII. admin.identity_retention_days seit letzter Aktivität, Standard 90

Eine 30-Sekunden-Schleife läuft kv-Zeilen ab ihrer TTL ab, und ein stündlicher Sweep erzwingt die Aufbewahrungsfenster auf den Spend-Tabellen, daher wächst nichts ohne Grenzen. Ohne Spend-Limits konfiguriert, wird nur kv geschrieben. Das Gateway wendet seine eigenen Schema-Migrationen beim Boot und bei jedem Upgrade an, daher benötigt seine Datenbankrolle Rechte zum Erstellen und Ändern von Tabellen. Zeigen Sie auf eine Datenbank oder ein Schema, das dem Gateway gewidmet ist, um diese Berechtigung eng zu halten.

Mit Spend-Limits in Verwendung bedeutet eine verlorene Datenbank verlorene Spend-Verfolgung und Caps, nicht nur Entwickler-Neu-Anmeldungen, daher führen Sie regelmäßige Backups durch. Um einen abgegangenen Entwickler sofort zu löschen, statt auf Aufbewahrung zu warten, führen Sie DELETE FROM principal_emails WHERE principal = '<sub>' direkt aus; das entfernt die einzige Tabelle, die ihre E-Mail, ihren Namen und ihre Gruppen hält. spend- und admin_audit-Zeilen referenzieren nur das pseudonyme OIDC-sub.

Upgrades

Replikationen sind zustandslos, daher ist ein Rolling Restart jederzeit sicher. Das Gateway führt Schema-Migrationen beim Start aus, was bedeutet, dass die Bereitstellung der neuen Binärdatei die Datenbank selbst migriert. Gleichzeitige Replikationen serialisieren auf einem Postgres-Advisory-Lock, daher wendet nur eine jede Migration an.

Wenn Ihr Orchestrator eine Replikation mit SIGTERM stoppt, wie bei einem Rolling Restart oder einer Scale-In, stoppt das Gateway das Akzeptieren neuer Verbindungen und lässt Anfragen und Streams, die bereits in Flug sind, beenden, bevor es beendet wird. Es wartet bis zu 25 Sekunden, genannt das Drain-Fenster, dann schließt es, was noch offen ist. Ein SIGINT, wie Ctrl+C in einem Terminal, startet denselben Drain, und ein zweites Signal während des Drain schließt die offenen Anfragen und beendet sofort. Draining erfordert Gateway v2.1.274 oder später.

Lange Generationen können Minuten lang streamen. Auf Kubernetes und Amazon ECS erhöhen Sie beide dieser 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 von Millisekunden, wie 120000. Das Gateway ignoriert einen Wert in jeder anderen Form, wie 120s, und behält den 25-Sekunden-Standard
  • Die Grace Period Ihres Orchestrators: terminationGracePeriodSeconds auf Kubernetes oder stopTimeout auf Amazon ECS

Die Grace Period beträgt standardmäßig 30 Sekunden auf beiden Plattformen. Halten Sie sie mindestens 5 Sekunden länger als das Drain-Fenster, oder der Orchestrator beendet das Gateway, bevor das Drain beendet ist. Auf Kubernetes addieren Sie auch die Dauer eines preStop-Hooks, da die Grace Period zu zählen beginnt, bevor der Hook ausgeführt wird, statt wenn das Gateway SIGTERM empfängt.

Ihre Plattform kann auch begrenzen, wie lange das Drain laufen kann:

  • Amazon ECS on Fargate: stopTimeout erlaubt höchstens 120 Sekunden
  • Cloud Run: stoppt eine Instanz 10 Sekunden nach SIGTERM, daher bekommen offene Streams dort höchstens 10 Sekunden, egal wie das Drain-Fenster ist

Wenn das Drain-Fenster mit noch offenen Anfragen endet, protokolliert das Gateway eine Warnung, die drain window over after enthält, zählt die Anfragen, die es abschnitt, und nennt beide Einstellungen zum Erhöhen.

Migrationen sind nur Anhänge, daher ist das Rollback zu einer früheren Binärdatei, die weniger Migrationen kennt, sicher; es ignoriert die zusätzlichen Zeilen. Rollback validiert auch die YAML erneut gegen das ältere Binärdatei-Schema, daher schlägt eine Konfiguration, die einen Schlüssel angenommen hat, der von der neueren Version eingeführt wurde, beim Boot auf der älteren fehl. Entfernen Sie den neuen Schlüssel vor dem Rollback.

Da Sie die Gateway-Version in Ihrem eigenen Image pinnen, erreichen Fixes in neuen Claude Code-Releases, einschließlich Sicherheits-Fixes, Ihre Bereitstellung nur, wenn Sie den Pin aktualisieren und erneut bereitstellen. Beziehen Sie das Gateway in denselben Patching-Zyklus ein, den Sie für andere Dienste verwenden, die Produktionsanmeldedaten halten.

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 → JWT → 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. 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

Fehlerbehebung

Für Fragen und Feedback verwenden Sie Claude-Code-Support, oder öffnen Sie ein Issue im Claude-Code-GitHub-Repository. Wenn Sie ein Problem melden, beziehen Sie ein:

  • Gateway-Problem: Das Gateway-Stderr für das relevante Fenster, Ihre gateway.yaml mit Geheimnissen redigiert, die Gateway-Version, auf der Landingpage unter / und im x-cc-gateway-version-Response-Header auf /managed/settings angezeigt, und was sich kürzlich geändert hat
  • Anmeldungs-Problem: Der Entwickler führt claude --debug-file ./claude-debug.txt aus, reproduziert und sendet diese Datei plus das Gateway-Audit-Protokoll für dasselbe Fenster
  • Inferenz-Problem: Das angeforderte Modell, die konfigurierten Upstreams und das Gateway-Audit-Protokoll für die Anfrage, das aufzeichnet, welcher Upstream sie bedient hat und den Response-Status

Die Standardfehlerausgabe des Gateways enthält den Audit-Ereignisstrom, das Audit-Protokoll zeichnet Entwickleridentitäten auf, und die Debug-Datei zeichnet Hook- und MCP-Serverausgaben von der Maschine des Entwicklers auf. Überprüfen und redigieren Sie diese, bevor Sie sie in einem öffentlichen Problem posten.

Symptom Ursache Behebung
Das /login eines Entwicklers zeigt den Standard-Account-Picker statt des Cloud-Gateway-Bildschirms forceLoginMethod oder forceLoginGatewayUrl ist nicht in verwalteten Einstellungen auf dieser Maschine gesetzt Stellen Sie die verwaltete Einstellungsdatei auf dem Gerät bereit; /login liest die Gateway-URL von dort
Die Anfragen eines Entwicklers schlagen mit Not signed in to the Cloud gateway — run /login. fehl Die verwalteten Einstellungen der Maschine setzen forceLoginMethod: "gateway" oder forceLoginGatewayUrl, und die Sitzung hat keine Gateway-Anmeldung. Eine verbleibende claude.ai-Anmeldung erfüllt die Anforderung nicht. Lassen Sie den Entwickler /login ausführen und die Gateway-Anmeldung abschließen. Siehe auch Administrator-Richtlinie erfordert eine Cloud-Gateway-Anmeldung.
Claude Desktop meldet, dass seine Bootstrap-Konfiguration nicht abgerufen werden konnte /user/bootstrap gab 404 zurück: die Richtlinie, die dem Benutzer entspricht, trägt keinen desktop-Schlüssel, oder es wurde keine Richtlinie gefunden. Das Gateway-Audit-Protokoll zeichnet jede Ablehnung als desktop_bootstrap.denied mit dem Grund auf. Fügen Sie einen desktop-Block zur Richtlinie hinzu, die dem Benutzer entspricht, oder zur match: {}-Basisebene; ein leeres desktop: {} reicht aus. Siehe Claude-Desktop-Overlay.
Startup zeigt 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 eine Version aktualisieren, die Cloud-Gateway-Unterstützung enthält
Startup beendet mit Administrator policy requires a Cloud gateway sign-in on this machine Die Umgebung des Entwicklers setzt ANTHROPIC_API_KEY oder ANTHROPIC_AUTH_TOKEN, ihre Einstellungen konfigurieren einen apiKeyHelper, oder ein API-Schlüssel aus einer früheren Claude-Console-Anmeldung ist noch gespeichert Lassen Sie den Entwickler jeden löschen, der zutrifft: die Variable aufheben, den apiKeyHelper-Eintrag entfernen, oder claude auth logout ausführen, um den gespeicherten Schlüssel zu entfernen. Dann lassen Sie ihn claude starten und sich mit /login anmelden. Siehe auch Administrator-Richtlinie erfordert eine Cloud-Gateway-Anmeldung.
Startup oder /login meldet Claude Code may not be enabled for your organization nach einer 403 beim Laden der verwalteten Einstellungen Das Gateway oder etwas davor hat die /managed/settings-Anfrage mit 403 beantwortet. Die Gateway-eigene Einstellungsroute antwortet niemals mit 403. Der Status stammt von den access_control-IP-Überprüfungen oder von einem Proxy oder WAF vor dem Gateway. Das Audit-Protokoll zeichnet eine IP-Überprüfungs-Ablehnung als access.denied mit dem Grund auf. Der Entwickler bleibt angemeldet. Überprüfen Sie das Audit-Protokoll auf access.denied zum Zeitpunkt des Fehlers und beheben Sie die access_control-Listen oder das Front-End, dann lassen Sie den Entwickler 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 /device-Seite kann Too many attempts für Entwickler anzeigen, die es noch nicht versucht haben Das Pro-IP-Anmeldungs-Ratenlimit wurde erreicht. Entweder deckt listen.trusted_proxies den Load-Balancer nicht ab, daher teilen alle Entwickler seine Adresse, oder viele Entwickler teilen eine NAT- oder VPN-Ausgangsadresse. Audit-Ereignisse mit result: rate_limited zeigen dieselbe eine oder wenige client_ip-Werte. Setzen Sie listen.trusted_proxies zuerst auf die Quellbereiche des Load-Balancers, dann erhöhen Sie rate_limits, wenn Entwickler immer noch 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 Gateway-Hostname wird zu mindestens einer öffentlichen IP-Adresse aufgelöst. Claude Code überprüft jede aufgelöste Adresse und erfordert, dass jede privat ist. Eine häufige Ursache ist ein Dual-Stack-Name, bei dem eine Familie zu einer öffentlichen Adresse aufgelöst wird, einschließlich AWS-interner Dual-Stack-Load-Balancer, die öffentliche AAAA-Adressen zurückgeben. Lassen Sie den Gateway-Namen nur zu privaten Adressen auf Entwicklermaschinen auflösen. Für einen Dual-Stack-Namen löschen Sie den öffentlichen Datensatz oder bedienen Sie einen separaten internen DNS-Namen. Siehe die Private-Network-Voraussetzung. Wenn die Adresse öffentlicher Adressraum ist, den Ihre Organisation besitzt und intern nutzt, deklarieren Sie diesen Block stattdessen.
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 Proxy-Hostname 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 zu NO_PROXY auf der Entwicklermaschine hinzu, damit die Verbindung direkt ist, oder verwenden Sie einen Proxy, dessen Hostname zu privaten Adressen aufgelöst wird. Die Nachricht benennt den genauen NO_PROXY-Eintrag, der hinzugefügt werden soll
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 befindet sich auf einem Block, der in gatewayInternalNetworks deklariert ist, und die Maschine des Entwicklers hat es von einer Adresse außerhalb dieses Blocks erreicht: ein VPN-Adresspool, ein Container- oder WSL2-NAT-Segment, oder ein Netzwerk, das nicht Ihres ist Lassen Sie den Entwickler /login vom Host-Betriebssystem in Ihrem Netzwerk ausführen. Wenn die angezeigte Adresse auch Ihr eigener öffentlicher Adressraum der Organisation ist, ersetzen Sie den Gateway-Eintrag durch einen Block, der beide abdeckt, bis zu /8; ein zweiter, überlappender Eintrag wird abgelehnt
CLI /login: Every address for gateway host <host> must be inside its declared network <block>, and it also resolves to <ip> Der Gateway-Name wird zu einer Adresse außerhalb des in gatewayInternalNetworks deklarierten Blocks aufgelöst: eine zweite Website oder ein IPv6-Datensatz auf einem Dual-Stack-Namen. Unter einem deklarierten Block muss jeder Datensatz innerhalb dieses einen IPv4-Blocks liegen, private und IPv6-Adressen eingeschlossen Veröffentlichen Sie nur Datensätze innerhalb des Blocks für den Gateway-Namen auf Entwicklermaschinen, oder bedienen Sie einen separaten internen Namen
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 auf einem deklarierten Block Fügen Sie auf der Entwicklermaschine den NO_PROXY-Eintrag hinzu, den die Nachricht benennt
CLI /login: eine Nachricht, die mit gatewayInternalNetworks in managed settings beginnt Der Wert verstößt gegen eine der Validierungsregeln, und die Nachricht benennt welche. Bis Sie es beheben, lehnt Claude Code jede neue Gateway-/login auf der Maschine ab, Gateways auf privaten Adressen eingeschlossen; bestehende Anmeldungen funktionieren weiterhin Korrigieren Sie in der verwalteten Einstellungsquelle, die Sie bereitstellen, den Eintrag, den die Nachricht benennt, dann führen Sie /login erneut aus
CLI /login: Could not resolve the configured HTTP proxy Der Hostname in HTTPS_PROXY oder HTTP_PROXY wird von der Entwicklermaschine nicht aufgelöst, typischerweise weil sie nicht mit dem Unternehmens-Netzwerk verbunden ist Lassen Sie den Entwickler sich mit Ihrem Netzwerk oder VPN verbinden und versuchen Sie erneut, oder beheben Sie die Proxy-URL
CLI /login: Could not resolve gateway host <host> Die Maschine kann den internen DNS-Namen des Gateways nicht auflösen, typischerweise weil sie nicht im Unternehmens-Netzwerk ist Lassen Sie den Entwickler sich mit Ihrem Netzwerk oder VPN verbinden und versuchen Sie dann /login erneut
Boot beendet mit einem Konfigurationsvalidierungsfehler, der store.postgres_url benennt Kein Postgres konfiguriert; das Gateway erfordert Postgres Setzen Sie store.postgres_url. Für lokale Entwicklung verwenden Sie einen Wegwerf-Container: docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres.
Boot beendet: requires the native binary Läuft unter Node statt der nativen Binärdatei Installieren Sie Claude Code mit einer der Standalone-Installationsmethoden
Boot beendet mit einem OIDC-Discovery-Fehler nach config.load oidc.issuer nicht erreichbar oder TLS-Kette nicht vertraut Überprüfen Sie, dass der Aussteller vom Pod erreichbar ist und /.well-known/openid-configuration bedient. Setzen Sie ca_cert_pem für private PKI. Wenn der Pod den IdP nur über einen Forward-Proxy erreicht, setzen Sie oidc.use_proxy: true; bei Versionen vor v2.1.227 geben Sie dem Pod stattdessen eine direkte Route zu jedem der IdP-Endpunkte. Wenn der Pod auch den Hostnamen des IdP nicht auflösen kann, oder der Proxy verweigert CONNECT zu einer IP-Adresse, siehe Nur-Proxy-Ausgang, das v2.1.277 oder später erfordert.
Boot beendet mit einem Postgres-Berechtigungsfehler Die Datenbankrolle fehlen DDL-Rechte auf ihrem Schema Gewähren Sie der Rolle CREATE auf dem Gateway-Schema, damit sie seine Tabellen beim Boot erstellen und ändern kann
Protokoll: could not connect to Postgres at boot, attempt 1 of 3 Die Datenbank war nicht erreichbar, als das Gateway gestartet wurde, zum Beispiel auf einer kalten Instanz, deren Netzwerk noch aufgebaut wird Wenn das Gateway dann das Booten beendet, ist keine Aktion erforderlich. Wenn die Datenbank nicht erreichbar ist, versucht das Gateway die Verbindung dreimal, zwei Sekunden auseinander, bevor es beendet wird. Wenn es mit could not connect to Postgres beendet wird, überprüfen Sie store.postgres_url und den Netzwerkpfad zur Datenbank. Wenn die Versuche Timeout statt Ablehnung sind, erhöhen Sie store.connect_timeout_seconds, um jedem länger zu geben.
/oauth/callback zeigt "Sign-in could not be completed" E-Mail-Domain abgelehnt, id_token-Validierung fehlgeschlagen, oder email_verified ist explizit false, was das Gateway immer ohne Überschreibung ablehnt Überprüfen Sie allowed_email_domains und dass der IdP einen verifizierten email-Claim zurückgibt. Für email_verified: false beheben Sie die IdP-seitige Verifikation. Wenn Ihr IdP E-Mail unter einem anderen Claim-Namen ausgibt, setzen Sie oidc.email_claim.
Protokoll: token exchange failed request_id=<id>: id_token missing email claim Der IdP enthält email nicht standardmäßig im id_token. Diese Ablehnung wird nur ausgelöst, wenn allowed_email_domains gesetzt ist; ohne sie prägt ein fehlende E-Mail eine Sitzung ohne E-Mail Konfigurieren Sie den IdP, um email im id_token auszugeben. Okta: Fügen Sie email zu den ID-Token-Claims eines benutzerdefinierten Autorisierungsservers hinzu. Entra: Fügen Sie email als optionalen Claim bei der App-Registrierung hinzu. PingFederate: Aktivieren Sie eine OpenID-Connect-Richtlinie, die email ausgibt. Wenn der IdP email vom Userinfo-Endpoint bedient, aber nicht im id_token einbeziehen wird, wie der Okta-Org-Autorisierungsserver, setzen Sie oidc.userinfo_fallback: true.
Protokoll: 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 akzeptierte den Refresh-Token, gab aber keinen id_token damit zurück, daher fragte das Gateway den Userinfo-Endpoint des IdP nach den Claims des Benutzers. Der IdP lehnte den erneuerten Access-Token dort ab. Das Gateway antwortet temporarily_unavailable, daher behält Claude Code den Refresh-Token, kann aber die Sitzung nicht erneuern. Gateway-Versionen vor v2.1.260 protokollieren dieselbe Zeile ohne das (at …)-Detail. Setzen Sie oidc.scope_on_refresh: true, verfügbar in Gateway v2.1.260 oder später, damit die Refresh-Anfrage erneut nach openid fragt. Einige IdPs, wie Okta, geben einen id_token bei Refresh nur zurück, wenn gefragt. Auf PingFederate aktivieren Sie stattdessen Return ID Token On Refresh Grant unter Applications > OAuth > OpenID Connect Policy Management. Der Schlüssel ändert das Verhalten von PingFederate nicht. Für andere IdPs, die ihn immer noch weglassen, überprüfen Sie, ob der Userinfo-Endpoint Access-Token akzeptiert, die von einem Refresh ausgestellt wurden. Als Übergangslösung erhöhen Sie session.ttl_hours. Siehe Identity-Provider-Setup für den Deprovisioning-Tradeoff.
Jede Amazon-Bedrock-Anfrage gibt 502 zurück; Protokoll zeigt Could not load credentials from any providers Auf EC2 blockiert IMDSv2s Standard-Hop-Limit von 1 die Instanz-Metadata-Anfrage von innerhalb des Containers. Boot und /readyz bestehen trotzdem, da das AWS SDK Instanz-Anmeldedaten bei der ersten Anfrage auflöst, nicht bei der Client-Konstruktion 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 in der Launch-Vorlage. Die Änderung gilt für jeden Container auf der Instanz. Bevorzugen Sie ECS-Task-Rollen, wo verfügbar, die Anmeldedaten vom ECS-Container-Credentials-Endpoint lesen und die Änderung ganz vermeiden, oder wenden Sie die Änderung auf einer dedizierten Gateway-Instanz an, um die Exposition zu begrenzen.
Bei Spitzenlast sind Antworten langsam zu starten oder scheinen zu hängen, oder schlagen mit einem 502 all upstreams failed fehl, während der Upstream gesund ist Ein Replikat hat mehr Anfragen offen als es gleichzeitig upstream sendet, daher warten die zusätzlichen Anfragen im Gateway. Bei einem provider: anthropic-Upstream gibt eine Anfrage, die länger als timeouts.upstream_ttfb_ms wartet, auf diesen Upstream auf, was den 502 erzeugt, wenn kein späterer Upstream sie bedient. Das Protokoll zeigt eine Warnung, die client requests are open enthält. Fügen Sie Replikationen hinzu, oder erhöhen Sie das Limit auf jeder Replikation. Siehe Gleichzeitige Upstream-Anfragen.
IdP-Fehler: unknown or unsupported scope Der IdP lehnt Scopes ab, die er nicht erkennt Setzen Sie oidc.scopes auf genau die Liste, die Ihr IdP akzeptiert; sie muss openid enthalten. Der Standard ist openid profile email offline_access.
Sitzungen erneuern sich nicht stillschweigend nach dem Setzen von oidc.scopes offline_access wurde aus der Überschreibung gelöscht Fügen Sie offline_access zurück, wenn Ihr IdP es unterstützt. Ohne einen Refresh-Token führen Entwickler die Browser-Anmeldung alle session.ttl_hours erneut aus.
Browser zeigt "This request came from another site and was blocked" Cross-Site-Form-POST, blockiert als CSRF-Schutz. Erwartet für eingebettete oder proxied Seiten Öffnen Sie den Verifikations-Link direkt
Chrome blockiert die Approve-Schaltfläche mit "Refused to send form data … violates … Content Security Policy directive: form-action", aber dieselbe Seite funktioniert in Safari oder Firefox Chrome erzwingt form-action gegen die gesamte Redirect-Kette. Ihr IdP leitet weiter zu einem zweiten Host, der nicht auf der Allowlist steht. Fügen Sie jeden zusätzlichen Ursprung in der Redirect-Kette zu oidc.form_action_origins hinzu. Öffnen Sie Chrome DevTools → Console auf der Approve-Seite, um zu sehen, welcher Ursprung blockiert wurde.
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 gab den Code über response_mode=form_post zurück, das ihn Cross-Origin über POST zu /oauth/callback automatisch einreicht. Chrome blockiert das unter einer strikten CSP; Safari erlaubt die Einreichung, aber der Callback liest nur die Query-String Stellen Sie sicher, dass Ihr IdP response_mode=query ehrt, das das Gateway explizit anfordert, damit der Callback eine einfache Umleitung ist
Anmeldung funktioniert lokal, schlägt aber hinter einem ALB fehl public_url benennt immer noch den lokalen oder inneren http://-Ursprung, daher erhält der IdP den falschen redirect_uri Setzen Sie listen.public_url auf den externen https://-Ursprung und registrieren Sie <public_url>/oauth/callback beim IdP
Entwickler sieht die Vertrauens-Aufforderung wiederholt TLS-Zert rotiert pro Replikation oder pro Anfrage Verwenden Sie ein stabiles Zert beim Ingress, oder beenden Sie TLS einmal und führen Sie Replikationen intern über einfaches HTTP aus
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 CLI-Host-Trust-Store ist Claude Code liest den OS-Trust-Store standardmäßig auf der nativen Binärdatei und auf Node 22.15 oder später; CLAUDE_CODE_CERT_STORE steuert dieses Verhalten. Wenn die CA im OS-Trust-Store installiert ist, stellen Sie sicher, dass Entwickler auf einer aktuellen Runtime sind. Andernfalls setzen Sie NODE_EXTRA_CA_CERTS auf das CA-Zertifikat-PEM, bevor Sie starten. Die First-Connect-Fingerprint-Aufforderung gilt immer noch.
CLI /login schließt die Browser-Anmeldung ab, dann endet die Sitzung mit Cloud gateway sign-in was not completed und einem TLS-Zertifikat-Mismatch Bei der ersten Anfrage nach der Anmeldung präsentierte das Gateway ein Zertifikat, das nicht dem Fingerprint entspricht, den Claude Code angeheftet hat, daher behielt Claude Code keine Gateway-Anmeldedaten. Die üblichen Ursachen sind Replikationen hinter einer Adresse, die unterschiedliche Zertifikate bedienen, oder etwas auf dem Netzwerkpfad, das TLS abfängt. Bedienen Sie ein Zertifikat für den Hostnamen, zum Beispiel durch einmaliges Beenden von TLS beim Ingress, dann lassen Sie den Entwickler /login erneut ausführen. Wenn sich dieses Zertifikat vom angehefteten unterscheidet, zeigt Claude Code die Vertrauens-Aufforderung erneut mit einer Warnung 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 Anmeldungs-Anfrage erreichte einen Server, dessen Zertifikat nicht dem entspricht, das der Entwickler akzeptiert hat, als /login begann: Replikationen hinter einer Adresse, die unterschiedliche Zertifikate bedienen, TLS-Abfangung auf dem Pfad, oder eine Zertifikat-Rotation während der Anmeldung. Bedienen Sie ein Zertifikat für den Hostnamen, dann lassen Sie den Entwickler die Anmeldung erneut starten und überprüfen Sie das neue Zertifikat bei der Vertrauens-Aufforderung.

Die Cloud gateway sign-in was not completed-Nachricht benennt den Gateway-Hostnamen. Wenn Claude Code sowohl den angehefteten Fingerprint als auch den präsentierten hat, zeigt die Nachricht auch die ersten 16 Zeichen jedes.

Wenn Claude Code couldn't load your organization's managed settings nach einer Gateway-Anmeldung meldet, benennt Claude Code den Grund, startet an Ort und Stelle neu und setzt das Gespräch fort. Wenn Claude Code nicht neu starten kann, zum Beispiel in einer Hintergrund-Sitzung, beendet Claude Code die Sitzung und behält die Anmeldung.