claude-apps-gateway-deploy.md +28 −26
6 6
7> 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.7> 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.
8 8
99Diese Seite behandelt den operativen Aspekt des Betriebs des [Claude-Apps-Gateways](/de/claude-apps-gateway): 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](/de/claude-apps-gateway-config).Diese Seite behandelt den operativen Aspekt des Betriebs des [Claude-Apps-Gateways](/docs/de/claude-apps-gateway): 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](/docs/de/claude-apps-gateway-config).
10 10
11Eine 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.11Eine 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.
12 12
31 31
32Jeder OIDC-konforme IdP funktioniert: Okta, Microsoft Entra ID, Google Workspace, Keycloak, Dex, PingFederate und andere. Der IdP muss drei Anforderungen erfüllen:32Jeder OIDC-konforme IdP funktioniert: Okta, Microsoft Entra ID, Google Workspace, Keycloak, Dex, PingFederate und andere. Der IdP muss drei Anforderungen erfüllen:
33 33
3434* Stellt `/.well-known/openid-configuration` über HTTPS in der Produktion bereit; das Gateway akzeptiert einen [`http://` Aussteller](/de/claude-apps-gateway-config#oidc), und ein Loopback-Aussteller erfordert zusätzlich `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`* Stellt `/.well-known/openid-configuration` über HTTPS in der Produktion bereit; das Gateway akzeptiert einen [`http://` Aussteller](/docs/de/claude-apps-gateway-config#oidc), und ein Loopback-Aussteller erfordert zusätzlich `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`
35* 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ützen35* 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
36* Gibt `email` und optional `groups` im id\_token zurück, oder stellt sie vom Userinfo-Endpoint mit `oidc.userinfo_fallback: true` bereit36* Gibt `email` und optional `groups` im id\_token zurück, oder stellt sie vom Userinfo-Endpoint mit `oidc.userinfo_fallback: true` bereit
37 37
41 41
42* **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.42* **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.
43* **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`.43* **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`.
4444* **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`](/de/claude-apps-gateway-config#oidc), 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 }`.* **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`](/docs/de/claude-apps-gateway-config#oidc), 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 }`.
45 45
46Für Unterstützung bei einem oben nicht behandelten Identitätsanbieter siehe [Troubleshooting](#troubleshooting).46Für Unterstützung bei einem oben nicht behandelten Identitätsanbieter siehe [Troubleshooting](#troubleshooting).
47 47
48<Warning>48<Warning>
49 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.49 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.
50 50
5151 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`](/de/claude-apps-gateway-config#session) 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. 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`](/docs/de/claude-apps-gateway-config#session) 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.
52</Warning>52</Warning>
53 53
54<h2 id="deployment">54<h2 id="deployment">
62Einige Entscheidungen prägen die Bereitstellung über den Ort hinaus, an dem sie läuft:62Einige Entscheidungen prägen die Bereitstellung über den Ort hinaus, an dem sie läuft:
63 63
64* **Kosten**: Es gibt keine separate Lizenz oder Pro-Sitz-Gebühr für das Gateway; es ist Teil der `claude`-Binärdatei. Sie zahlen für Inferenz über Ihr bestehendes Cloud- oder Anthropic-Engagement, plus die Berechnung für den Container und Ihren Telemetrie-Collector.64* **Kosten**: Es gibt keine separate Lizenz oder Pro-Sitz-Gebühr für das Gateway; es ist Teil der `claude`-Binärdatei. Sie zahlen für Inferenz über Ihr bestehendes Cloud- oder Anthropic-Engagement, plus die Berechnung für den Container und Ihren Telemetrie-Collector.
6565* **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](/de/data-usage#webfetch-domain-safety-check), die `api.anthropic.com` von jeder Entwicklermaschine aufruft; setzen Sie `skipWebFetchPreflight: true` in der verwalteten Richtlinie, um sie zu deaktivieren.* **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](/docs/de/data-usage#webfetch-domain-safety-check), die `api.anthropic.com` von jeder Entwicklermaschine aufruft; setzen Sie `skipWebFetchPreflight: true` in der verwalteten Richtlinie, um sie zu deaktivieren.
66* **Mehrere Gateways**: Jedes Gateway ist eine separate Bereitstellung mit seiner eigenen Konfiguration. Die CLI speichert ihren Vertrauens-Fingerprint und ihre Anmeldedaten pro Gateway-Hostname, daher können verschiedene Teams sich mit verschiedenen Gateways verbinden, ohne Konflikte. Um mehrere OIDC-Aussteller zu bedienen, führen Sie separate Instanzen aus.66* **Mehrere Gateways**: Jedes Gateway ist eine separate Bereitstellung mit seiner eigenen Konfiguration. Die CLI speichert ihren Vertrauens-Fingerprint und ihre Anmeldedaten pro Gateway-Hostname, daher können verschiedene Teams sich mit verschiedenen Gateways verbinden, ohne Konflikte. Um mehrere OIDC-Aussteller zu bedienen, führen Sie separate Instanzen aus.
67* **Serverless**: Cloud Run funktioniert; setzen Sie `min-instances: 1`, um kalte OIDC-Erkennung zu vermeiden. Lambda und Cloud Functions funktionieren nicht, da das Gateway ein langlebiger HTTP-Server ist.67* **Serverless**: Cloud Run funktioniert; setzen Sie `min-instances: 1`, um kalte OIDC-Erkennung zu vermeiden. Lambda und Cloud Functions funktionieren nicht, da das Gateway ein langlebiger HTTP-Server ist.
68 68
6969Jede 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`](/de/claude-apps-gateway-config#listen) 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; das [Google Cloud-Beispiel](/de/claude-apps-gateway-on-gcp) hat 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.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`](/docs/de/claude-apps-gateway-config#listen) 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; das [Google Cloud-Beispiel](/docs/de/claude-apps-gateway-on-gcp) hat 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.
70 70
71<h3 id="container-image">71<h3 id="container-image">
72 Container-Image72 Container-Image
74 74
75Erstellen Sie Ihr eigenes Image um die native `claude`-Binärdatei aus der Standard-Claude-Code-Version:75Erstellen Sie Ihr eigenes Image um die native `claude`-Binärdatei aus der Standard-Claude-Code-Version:
76 76
77771. Laden Sie den Linux-Build für Ihre Image-Architektur aus einer gepinnten Version herunter; siehe [Installieren Sie eine bestimmte Version](/de/setup#install-a-specific-version) für die Download-URL.1. Laden Sie den Linux-Build für Ihre Image-Architektur aus einer gepinnten Version herunter; siehe [Installieren Sie eine bestimmte Version](/docs/de/setup#install-a-specific-version) für die Download-URL.
78782. Überprüfen Sie es gegen die GPG-signierte `manifest.json` der Version, wie in [Binäre Integrität und Code-Signierung](/de/setup#binary-integrity-and-code-signing) beschrieben.2. Überprüfen Sie es gegen die GPG-signierte `manifest.json` der Version, wie in [Binäre Integrität und Code-Signierung](/docs/de/setup#binary-integrity-and-code-signing) beschrieben.
793. Kopieren Sie es in den Build-Kontext.793. Kopieren Sie es in den Build-Kontext.
80 80
81Spiegeln 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.81Spiegeln 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.
82 82
83Über die Binärdatei hinaus benötigt das Image:83Über die Binärdatei hinaus benötigt das Image:
84 84
8585* **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](/de/setup#alpine-linux-and-musl-based-distributions).* **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](/docs/de/setup#alpine-linux-and-musl-based-distributions).
86* **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`.86* **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`.
87* **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`.87* **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`.
88 88
99<Note>99<Note>
100 **Workload-Identität**100 **Workload-Identität**
101 101
102102 Bevorzugen Sie die Workload-Identität der Plattform gegenüber statischen Schlüsseln: IRSA auf EKS für Bedrock und für Claude Platform auf AWS, Workload Identity auf GKE für Agent Platform und Workload Identity auf AKS für Foundry. Setzen Sie `auth: {}` im Upstream-Block oder `use_azure_ad: true` für Foundry, und das Gateway nimmt die Identität des Pods durch die Standard-Credential-Chain dieses Anbieters auf. Für eine Cloud-übergreifende Kopplung, wie z. B. einen Bedrock-Upstream auf GKE, setzen Sie explizite Anmeldedaten im `auth`-Block des Upstream statt. Die [`upstreams`-Referenz](/de/claude-apps-gateway-config#upstreams) hat Setup-Details pro Plattform. Bevorzugen Sie die Workload-Identität der Plattform gegenüber statischen Schlüsseln: IRSA auf EKS für Bedrock und für Claude Platform auf AWS, Workload Identity auf GKE für Agent Platform und Workload Identity auf AKS für Foundry. Setzen Sie `auth: {}` im Upstream-Block oder `use_azure_ad: true` für Foundry, und das Gateway nimmt die Identität des Pods durch die Standard-Credential-Chain dieses Anbieters auf. Für eine Cloud-übergreifende Kopplung, wie z. B. einen Bedrock-Upstream auf GKE, setzen Sie explizite Anmeldedaten im `auth`-Block des Upstream statt. Die [`upstreams`-Referenz](/docs/de/claude-apps-gateway-config#upstreams) hat Setup-Details pro Plattform.
103</Note>103</Note>
104 104
105<h3 id="cloud-run">105<h3 id="cloud-run">
109Konfigurieren Sie den Dienst wie folgt:109Konfigurieren Sie den Dienst wie folgt:
110 110
111* Lassen Sie `listen.port` bei seinem Standard von `8080`, das Cloud Runs Standard-`PORT` entspricht, oder setzen Sie `port: ${PORT}`111* Lassen Sie `listen.port` bei seinem Standard von `8080`, das Cloud Runs Standard-`PORT` entspricht, oder setzen Sie `port: ${PORT}`
112112* 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](/de/claude-apps-gateway#prerequisites) 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](/de/claude-apps-gateway-on-gcp#deploy-the-gateway) behandelt beide.* 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](/docs/de/claude-apps-gateway#prerequisites) 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](/docs/de/claude-apps-gateway-on-gcp#deploy-the-gateway) behandelt beide.
113* Binden Sie die Konfiguration als Secret-Volume ein113* Binden Sie die Konfiguration als Secret-Volume ein
114* Setzen Sie `min-instances: 1`, um kalte OIDC-Erkennung bei der ersten Anfrage zu vermeiden114* Setzen Sie `min-instances: 1`, um kalte OIDC-Erkennung bei der ersten Anfrage zu vermeiden
115 115
116<Note>116<Note>
117117 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](/de/claude-apps-gateway-on-gcp). 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](/docs/de/claude-apps-gateway-on-gcp).
118</Note>118</Note>
119 119
120<h3 id="push-the-gateway-url-to-developer-machines">120<h3 id="push-the-gateway-url-to-developer-machines">
121 Pushen Sie die Gateway-URL zu Entwicklermaschinen121 Pushen Sie die Gateway-URL zu Entwicklermaschinen
122</h3>122</h3>
123 123
124124Sobald das Gateway bedient wird, pushen Sie `forceLoginMethod` und `forceLoginGatewayUrl` ü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. Siehe [Client-seitige verwaltete Einstellungen](/de/claude-apps-gateway-config#client-side-managed-settings) für die Dateipfade.Sobald das Gateway bedient wird, pushen Sie `forceLoginMethod` und `forceLoginGatewayUrl` ü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. Siehe [Client-seitige verwaltete Einstellungen](/docs/de/claude-apps-gateway-config#client-side-managed-settings) für die Dateipfade.
125 125
126<h2 id="operations">126<h2 id="operations">
127 Betrieb127 Betrieb
160 160
161* **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 bedienen161* **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
162* **Neue Anmeldungen**: schlagen fehl, bis Postgres wiederhergestellt ist, da der Device-Flow und seine Rate-Limit-Zähler in Postgres leben162* **Neue Anmeldungen**: schlagen fehl, bis Postgres wiederhergestellt ist, da der Device-Flow und seine Rate-Limit-Zähler in Postgres leben
163163* **[Spend-Limit-Durchsetzung](/de/claude-apps-gateway-spend-limits#postgres-availability)**: 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* **[Spend-Limit-Durchsetzung](/docs/de/claude-apps-gateway-spend-limits#postgres-availability)**: 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
164* **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.164* **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.
165 165
166Wenn 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.166Wenn 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.
191| `admin_audit` | Admin-API-Mutations-Trail | `admin.audit_retention_days`, Standard 365 |191| `admin_audit` | Admin-API-Mutations-Trail | `admin.audit_retention_days`, Standard 365 |
192| `principal_emails` | E-Mail, Anzeigename und IdP-Gruppen jedes Principal. Enthält PII. | `admin.identity_retention_days` seit letzter Aktivität, Standard 90 |192| `principal_emails` | E-Mail, Anzeigename und IdP-Gruppen jedes Principal. Enthält PII. | `admin.identity_retention_days` seit letzter Aktivität, Standard 90 |
193 193
194194Eine 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](/de/claude-apps-gateway-spend-limits) konfiguriert, wird nur `kv` geschrieben. Wenn Ihre Sicherheitsrichtlinie DDL von der Anwendungsrolle verbietet, erstellen Sie diese Tabellen und `_migrations` vorab mit einer Admin-Rolle und gewähren Sie der App-Rolle `SELECT, INSERT, UPDATE, DELETE` auf jeder.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](/docs/de/claude-apps-gateway-spend-limits) konfiguriert, wird nur `kv` geschrieben. Wenn Ihre Sicherheitsrichtlinie DDL von der Anwendungsrolle verbietet, erstellen Sie diese Tabellen und `_migrations` vorab mit einer Admin-Rolle und gewähren Sie der App-Rolle `SELECT, INSERT, UPDATE, DELETE` auf jeder.
195 195
196Mit 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`.196Mit 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`.
197 197
218| Daten | Pfad | Vom Gateway an Anthropic gesendet |218| Daten | Pfad | Vom Gateway an Anthropic gesendet |
219| --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------- |219| --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------- |
220| Inferenz (Prompts, Completions) | CLI → Gateway → Ihr Upstream | Nur wenn die Anthropic-API ein konfigurierter Upstream ist |220| Inferenz (Prompts, Completions) | CLI → Gateway → Ihr Upstream | Nur wenn die Anthropic-API ein konfigurierter Upstream ist |
221221| Telemetrie (OTLP-Metriken, plus [Opt-in-Protokolle und Traces](/de/claude-apps-gateway-config#telemetry)) | CLI → Gateway → Ihr Collector | Nie || Telemetrie (OTLP-Metriken, plus [Opt-in-Protokolle und Traces](/docs/de/claude-apps-gateway-config#telemetry)) | CLI → Gateway → Ihr Collector | Nie |
222| Identität (E-Mail, Gruppen, Sub) | IdP → Gateway → JWT → CLI; die CLI stempelt sie auf OTLP-Exporte | Nie |222| Identität (E-Mail, Gruppen, Sub) | IdP → Gateway → JWT → CLI; die CLI stempelt sie auf OTLP-Exporte | Nie |
223| Verwaltete Einstellungen | Ihre Gateway-YAML → CLI | Nie |223| Verwaltete Einstellungen | Ihre Gateway-YAML → CLI | Nie |
224| Audit-Protokoll | Gateway-Stderr → Ihr Aggregator | Nie |224| Audit-Protokoll | Gateway-Stderr → Ihr Aggregator | Nie |
237 237
238Zwei Bedrohungen sind außerhalb des Geltungsbereichs, da sie Ihre Infrastruktur sind, um zu sichern:238Zwei Bedrohungen sind außerhalb des Geltungsbereichs, da sie Ihre Infrastruktur sind, um zu sichern:
239 239
240240* **Ein kompromittierter Gateway-Host**: Der Host hält sowohl die Upstream-Anmeldedaten als auch verteilt [verwaltete Einstellungen](/de/claude-apps-gateway-config#managed) an jeden verbundenen Entwickler, daher ist die Kontrolle über die Gateway-Konfiguration vergleichbar mit der Kontrolle über Ihr MDM. Der Einmal-Genehmigungsdialog der CLI für Shell-fähige Einstellungen begrenzt stille Änderungen, ersetzt aber nicht die Host-Sicherheit.* **Ein kompromittierter Gateway-Host**: Der Host hält sowohl die Upstream-Anmeldedaten als auch verteilt [verwaltete Einstellungen](/docs/de/claude-apps-gateway-config#managed) an jeden verbundenen Entwickler, daher ist die Kontrolle über die Gateway-Konfiguration vergleichbar mit der Kontrolle über Ihr MDM. Der Einmal-Genehmigungsdialog der CLI für Shell-fähige Einstellungen begrenzt stille Änderungen, ersetzt aber nicht die Host-Sicherheit.
241* **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.241* **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.
242 242
243<h3 id="user-code-brute-force-resistance">243<h3 id="user-code-brute-force-resistance">
246 246
247Der `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.247Der `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.
248 248
249249Das Gateway wendet Pro-IP-Rate-Limits auf die Device-Grant-Endpoints an, konfigurierbar über [`rate_limits`](/de/claude-apps-gateway-config#http-tuning). Erhöhen Sie die Limits, wenn sich viele Entwickler von einer einzelnen gemeinsamen Unternehmens-NAT-Adresse anmelden. Die Limits gelten nur für den Anmeldungs-Flow, nicht für Inferenz.Das Gateway wendet Pro-IP-Rate-Limits auf die Device-Grant-Endpoints an, konfigurierbar über [`rate_limits`](/docs/de/claude-apps-gateway-config#http-tuning). Erhöhen Sie die Limits, wenn sich viele Entwickler von einer einzelnen gemeinsamen Unternehmens-NAT-Adresse anmelden. Die Limits gelten nur für den Anmeldungs-Flow, nicht für Inferenz.
250 250
251<h3 id="compliance-posture">251<h3 id="compliance-posture">
252 Compliance-Haltung252 Compliance-Haltung
255* **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.255* **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.
256* **Host-Prozess-Verkehr**: Der Host-Prozess ist die Claude Code CLI, die Startup-Analytik und Update-Prüfungen an Anthropic senden kann. Für Strict-Egress-Bereitstellungen setzen Sie `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` in der Gateway-Container-Umgebung.256* **Host-Prozess-Verkehr**: Der Host-Prozess ist die Claude Code CLI, die Startup-Analytik und Update-Prüfungen an Anthropic senden kann. Für Strict-Egress-Bereitstellungen setzen Sie `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` in der Gateway-Container-Umgebung.
257* **Client-Analytik**: Die CLI deaktiviert ihre eigene Nutzungsanalytik, während sie bei einem Gateway angemeldet ist, und die Fehlerberichterstattung ist standardmäßig auf Third-Party-API-Oberflächen deaktiviert.257* **Client-Analytik**: Die CLI deaktiviert ihre eigene Nutzungsanalytik, während sie bei einem Gateway angemeldet ist, und die Fehlerberichterstattung ist standardmäßig auf Third-Party-API-Oberflächen deaktiviert.
258258* **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](/de/data-usage).* **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](/docs/de/data-usage).
259* **Umfrage-Bewertungen**: Die Gateway-Anmeldedaten deaktivieren die Anthropic-gebundene Bewertungs-Senke, daher werden Bewertungen nicht an Anthropic gesendet.259* **Umfrage-Bewertungen**: Die Gateway-Anmeldedaten deaktivieren die Anthropic-gebundene Bewertungs-Senke, daher werden Bewertungen nicht an Anthropic gesendet.
260* **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.260* **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.
261* **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.261* **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.
262* **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.262* **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.
263263* **Vulnerability-Offenlegung**: Folgen Sie [Sicherheitsprobleme melden](/de/security#reporting-security-issues)* **Vulnerability-Offenlegung**: Folgen Sie [Sicherheitsprobleme melden](/docs/de/security#reporting-security-issues)
264 264
265<h2 id="troubleshooting">265<h2 id="troubleshooting">
266 Fehlerbehebung266 Fehlerbehebung
272* **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 Fenster272* **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
273* **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-Status273* **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
274 274
275Die 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.
276
275| Symptom | Ursache | Behebung |277| Symptom | Ursache | Behebung |
276| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |278| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
277279| 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](/de/claude-apps-gateway#set-the-gateway-url) auf dem Gerät bereit; `/login` liest die Gateway-URL von dort || 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](/docs/de/claude-apps-gateway#set-the-gateway-url) auf dem Gerät bereit; `/login` liest die Gateway-URL von dort |
278| 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 |280| 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 |
279281| 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. {/* min-version: 2.1.206 */}Anthropic-betriebene öffentliche Gateway-Endpunkte sind von der Überprüfung ausgenommen, und `/login` akzeptiert sie über `https://`. Vor v2.1.206 lehnte `/login` sie wie jede andere öffentliche Adresse ab | 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](/de/claude-apps-gateway#prerequisites). || 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. {/* min-version: 2.1.206 */}Anthropic-betriebene öffentliche Gateway-Endpunkte sind von der Überprüfung ausgenommen, und `/login` akzeptiert sie über `https://`. Vor v2.1.206 lehnte `/login` sie wie jede andere öffentliche Adresse ab | 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](/docs/de/claude-apps-gateway#prerequisites). |
280| CLI `/login`: `Gateway login requires a direct connection and does not support connecting through an HTTP proxy` | 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 |282| CLI `/login`: `Gateway login requires a direct connection and does not support connecting through an HTTP proxy` | 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 |
281| 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 |283| 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 |
282| 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`. |284| 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`. |
283285| Boot beendet: `requires the native binary` | Läuft unter Node statt der nativen Binärdatei | Installieren Sie Claude Code mit einer der [Standalone-Installationsmethoden](/de/setup) || Boot beendet: `requires the native binary` | Läuft unter Node statt der nativen Binärdatei | Installieren Sie Claude Code mit einer der [Standalone-Installationsmethoden](/docs/de/setup) |
284| 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. |286| 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. |
285| Boot beendet mit einem Postgres-Berechtigungsfehler | App-Rolle fehlt `CREATE TABLE` | Erstellen Sie das Schema vorab mit einer Admin-Rolle und gewähren Sie DML der App-Rolle, oder gewähren Sie DDL vorübergehend für Boots, die neue Migrationen anwenden |287| Boot beendet mit einem Postgres-Berechtigungsfehler | App-Rolle fehlt `CREATE TABLE` | Erstellen Sie das Schema vorab mit einer Admin-Rolle und gewähren Sie DML der App-Rolle, oder gewähren Sie DDL vorübergehend für Boots, die neue Migrationen anwenden |
286| `/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`. |288| `/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`. |
293| 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 |295| 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 |
294| Anmeldung funktioniert lokal, schlägt aber hinter einem ALB fehl | `public_url` nicht gesetzt, daher erhält der IdP den inneren `http://`-Ursprung als `redirect_uri` | Setzen Sie `listen.public_url` auf den externen `https://`-Ursprung |296| Anmeldung funktioniert lokal, schlägt aber hinter einem ALB fehl | `public_url` nicht gesetzt, daher erhält der IdP den inneren `http://`-Ursprung als `redirect_uri` | Setzen Sie `listen.public_url` auf den externen `https://`-Ursprung |
295| 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 |297| 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 |
296298| 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`](/de/network-config#ca-certificate-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`: "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`](/docs/de/network-config#ca-certificate-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. |
297 299
298<h2 id="related">300<h2 id="related">
299 Verwandt301 Verwandt
300</h2>302</h2>
301 303
302304* [Claude-Apps-Gateway-Übersicht](/de/claude-apps-gateway): Schnellstart und Entwickler-Verbindung* [Claude-Apps-Gateway-Übersicht](/docs/de/claude-apps-gateway): Schnellstart und Entwickler-Verbindung
303305* [Konfigurationsreferenz](/de/claude-apps-gateway-config): Jede `gateway.yaml`-Option* [Konfigurationsreferenz](/docs/de/claude-apps-gateway-config): Jede `gateway.yaml`-Option