Skip to main content
Diese Seite zeigt eine Möglichkeit, Claude-Apps-Gateway auf AWS auszuführen. Die Konfiguration ist ein funktionierendes Beispiel für kundenverwaltete Infrastruktur und keine unterstützte Produktionsbereitstellung. Nutzen Sie sie, um zu verstehen, wie die einzelnen Komponenten zusammenpassen, bevor Sie sie an Ihre eigene Umgebung anpassen. Für die plattformunabhängigen Anforderungen siehe den Bereitstellungsleitfaden.
Dieses Beispiel stellt Claude-Apps-Gateway auf AWS mit Amazon Bedrock als Modell-Upstream bereit und nutzt entweder Amazon ECS auf AWS Fargate oder Amazon EKS für die Berechnung. Okta ist der Beispiel-Identitätsanbieter (IdP), aber jeder OpenID Connect (OIDC) konforme IdP funktioniert. Siehe Identitätsanbieter-Setup für Details pro IdP.
Bedrock ist nicht der einzige Claude-Upstream auf AWS. Das Gateway unterstützt auch Claude Platform on AWS, die von Anthropic betriebene Claude-API mit AWS-Authentifizierung und AWS-Marketplace-Abrechnung, anstelle von Bedrock oder neben ihm. Der Upstream-Eintrag, die Anmeldedaten und die IAM-Berechtigungen unterscheiden sich von den auf dieser Seite beschriebenen Bedrock-spezifischen; die Claude Platform on AWS Upstream-Referenz behandelt, was sich ändert, und der Rest dieser Seite gilt unverändert.

Architektur

Diagramm von Claude-Apps-Gateway auf AWS: Claude Code Clients verbinden sich über HTTPS mit einem internen Application Load Balancer, der das Gateway (ECS Fargate oder EKS) frontet, das in privaten Subnetzen neben einer Amazon RDS für PostgreSQL Instanz für Sitzungszustand läuft. Das Gateway meldet Benutzer über OIDC gegen den Unternehmens-IdP an, liest Geheimnisse aus AWS Secrets Manager, leitet Modellanfragen an Amazon Bedrock mit seiner IAM-Rolle weiter und zieht sein Image bei der Bereitstellung aus Amazon ECR.

Die Beispielarchitektur mit Amazon Bedrock als Modell-Upstream. Ein Claude Platform on AWS Upstream nimmt die gleiche Position ein.

Das Gateway läuft als privater HTTPS-Endpunkt in Ihrem Netzwerk, bei dem sich Entwickler über Ihren IdP anmelden. Ihre Claude Code Sitzungen erreichen Claude-Modelle auf Amazon Bedrock über die IAM-Rolle des Gateways, sodass keine Modellanmeldedaten auf Entwicklermaschinen landen. Die Referenzkonfiguration stellt bereit:
  • Amazon ECS auf AWS Fargate Service oder Amazon EKS Deployment, das den Gateway-Container ausführt
  • Amazon ECR Repository für das Gateway-Image
  • Amazon RDS für PostgreSQL Instanz in privaten Subnetzen, nicht öffentlich zugänglich, für den Store des Gateways
  • AWS Secrets Manager Geheimnisse für den JWT-Signaturschlüssel, das OIDC-Client-Geheimnis und die Postgres-URL
  • IAM-Rolle mit bedrock:InvokeModel, bedrock:InvokeModelWithResponseStream und bedrock:CountTokens, angehängt als ECS-Task-Rolle oder gebunden über IAM Roles for Service Accounts (IRSA) auf EKS
  • Interner Application Load Balancer für HTTPS

Voraussetzungen

Die Anleitung erstellt die eigenen Ressourcen des Gateways, basiert aber auf Netzwerk- und Identitätsinfrastruktur, die Sie bereits haben. Bevor Sie beginnen, benötigen Sie:

Legen Sie Ihre Umgebungsvariablen fest

Jeder Befehl auf dieser Seite liest vier Werte aus Ihrer Shell: AWS_REGION, ACCOUNT_ID, VPC_ID und PRIVATE_SUBNETS. Wählen Sie eine US-Region, in der Bedrock die Claude-Modelle bereitstellt, die Sie benötigen. Die Anleitung basiert auf dem integrierten Modellkatalog des Gateways, der zu us.anthropic.* Inferenzprofilen aufgelöst wird, und die IAM-Richtlinie gewährt diese ARNs. In einer nicht-US-Region fügen Sie einen models: Block mit den Inferenzprofil-IDs dieser Region hinzu und ändern das ARN-Präfix der IAM-Richtlinie entsprechend. Wenn Sie die VPC-ID nicht zur Hand haben, listen Sie Ihre VPCs mit aws ec2 describe-vpcs auf und listen Sie dann die Subnetze dieser VPC auf, um zwei private in verschiedenen Verfügbarkeitszonen zu finden:
Exportieren Sie alle vier, bevor Sie fortfahren:

Stellen Sie das Gateway bereit

Die folgenden Schritte stellen die vollständige Bereitstellung mit aws Befehlen bereit.
1

Erstellen Sie die Sicherheitsgruppen

Drei Sicherheitsgruppen verketten den Verkehrspfad: Ihr Unternehmensnetzwerk erreicht den Load Balancer auf 443, der Load Balancer erreicht das Gateway auf 8080, und das Gateway erreicht Postgres auf 5432. Nichts anderes ist erreichbar. Wie Sie sie anhängen, hängt vom Compute-Pfad ab:
  • Auf ECS Fargate hängt der Bereitstellungsschritt $ALB_SG an den Load Balancer und $GW_SG an den Service an.
  • Auf EKS erstellt der AWS Load Balancer Controller seine eigene Frontend-Sicherheitsgruppe für den ALB, daher werden $ALB_SG und $GW_SG nicht verwendet: die Annotation inbound-cidrs des Bereitstellungsschritts beschränkt den Listener auf Ihr Unternehmensnetzwerk, und die Datenbanksicherheitsgruppe lässt stattdessen die Sicherheitsgruppe des Clusters zu.
2

Erstellen Sie die IAM-Rollen und reichen Sie das Use-Case-Formular ein

Das Gateway läuft mit einer dedizierten Task-Rolle, deren einzige Berechtigung das Aufrufen von Claude-Modellen auf Bedrock ist. Gemäß der Bedrock Upstream-Referenz muss die Richtlinie sowohl die Cross-Region-Inferenzprofil-ARNs als auch die zugrunde liegenden Foundation-Model-ARNs abdecken:
ECS benötigt auch eine Ausführungsrolle, die der ECS-Agent selbst verwendet, um das Image aus ECR zu ziehen und die später erstellten Secrets Manager-Werte einzuspritzen. Sie ist getrennt von der Task-Rolle, die das Gateway zur Laufzeit mit dem AWS SDK verwendet:
Die Richtlinie nennt eine ARN pro Geheimnis statt eines bloßen gateway-* Wildcards, das in einem gemeinsamen Konto auch nicht verwandte Geheimnisse abgleichen würde; das nachfolgende -?????? gleicht genau das zufällige sechsstellige Suffix ab, das Secrets Manager an jede Geheimnis-ARN anhängt. Ein nachfolgendes -* wäre ein einfaches Präfix-Glob und würde auch längere Namen wie gateway-postgres-url-prod abgleichen.Die IAM-Richtlinie gewährt dem Gateway die Berechtigung, Bedrock aufzurufen, und Bedrock ermöglicht den Modellzugriff standardmäßig in kommerziellen Regionen. Das verbleibende Konto-Level-Gate ist Anthropics einmaliges Use-Case-Formular: Wenn niemand in Ihrem Konto es eingereicht hat, öffnen Sie die Amazon Bedrock Konsole, wählen Sie ein Anthropic-Modell aus dem Modellkatalog und füllen Sie das Formular aus. Der Zugriff wird unmittelbar nach der Einreichung gewährt; siehe Claude Code auf Amazon Bedrock für das AWS Organizations Formular und die IAM-Berechtigungen, die der Einreicher benötigt.Der EKS-Pfad verwendet beide Richtliniendokumente stattdessen auf einer IRSA-Rolle anstelle der zwei ECS-Rollen; siehe den Bereitstellungsschritt.
3

Stellen Sie Amazon RDS für PostgreSQL bereit

Die Instanz läuft in den privaten Subnetzen ohne öffentliche Adresse und mit aktivierter Speicherverschlüsselung. Die Engine-Version ist auf Postgres 16 festgelegt, was den unterstützten Boden des Gateways von PostgreSQL 14 erfüllt und garantiert, dass die Parametergruppe unten mit der Instanz übereinstimmt.Erstellen Sie zunächst die Subnet-Gruppe, die die Datenbank in den privaten Subnetzen platziert, und eine Parametergruppe mit rds.force_ssl=1, damit der Server Klartextverbindungen ablehnt. Die Engine-Version ist einmal festgelegt, da die Parametergruppen-Familie mit der Engine-Hauptversion übereinstimmen muss, die die Instanz ausführt:
Erstellen Sie dann die Instanz mit einem generierten Master-Passwort:
Das Literal --master-user-password Argument ist in der Prozesstabelle und in Audit-/EDR-Protokollen sichtbar, während der Befehl ausgeführt wird, die gleiche Exposition, die der Geheimnisse-Schritt behandelt. Auf einem gemeinsamen oder überwachten Host übergeben Sie das Passwort stattdessen über --cli-input-json aus einer 0600 Datei, wie es das setup.sh des Bundles tut.Warten Sie, bis die Instanz hochfährt, was mehrere Minuten dauern kann, lesen Sie dann ihren privaten Endpunkt und stellen Sie die Verbindungszeichenfolge zusammen, die das Gateway verwendet:
sslmode=verify-full lässt das Gateway das RDS-Serverzertifikat und den Hostnamen überprüfen, nicht nur verschlüsseln. Der Vertrauensanker ist das AWS RDS Zertifikat-Bundle, das der Image-Build-Schritt unten zu /etc/claude/rds-global-bundle.pem kopiert und über NODE_EXTRA_CA_CERTS vertraut. Hängen Sie keinen libpq-Stil sslrootcert= Parameter an die URL an: Der Gateway-Treiber liest nur sslmode aus der Abfragezeichenfolge und würde sslrootcert als Startup-Parameter an Postgres weiterleiten, das der Server ablehnt.Der ECS-Service oder die EKS-Pods müssen in diesem VPC ausgeführt werden, damit sie den privaten Endpunkt der Instanz erreichen können, und die claude-gateway-db Sicherheitsgruppe lässt nur die Sicherheitsgruppe des Gateways zu.
4

Schreiben Sie gateway.yaml

Der upstreams Block zeigt auf Bedrock mit auth: {}, daher authentifiziert sich das Gateway über die AWS-Standard-Anmeldekette aus der Task-Rolle auf ECS oder der IRSA-Rolle auf EKS. Siehe die Konfigurationsreferenz für jedes Feld.Zwei listen Felder beschreiben, was das Gateway frontet:
  • public_url: die externe https:// Herkunft, erforderlich für jeden nicht-Loopback-Bind; siehe die listen Referenz. Das Gateway erstellt den IdP redirect_uri und sein Discovery-Dokument nur aus diesem Wert, niemals aus X-Forwarded-* Headern.
  • trusted_proxies: die Quellbereiche des Front-End. Das Gateway berücksichtigt X-Forwarded-For nur, wenn der TCP-Peer in dieser Liste ist, geht dann die Kette über vertrauenswürdige Hops, sodass Anmelderate-Limits pro IP und Audit-Events Entwickler-IPs statt der Load-Balancer-IP aufzeichnen.
Auf beiden Pfaden ist das Front-End ein interner ALB, ob direkt erstellt oder vom AWS Load Balancer Controller, und ALB-Knoten nehmen Adressen aus den Subnetzen, an die sie angehängt sind, daher setzen Sie trusted_proxies auf die CIDRs dieser Subnetze. Dies vertraut jedem Host in diesen Subnetzen als Proxy. Halten Sie die Ingress-Quelle des ALB, Ihre Unternehmens-CIDR, davon ab, sich zu überlappen, und teilen Sie die Subnetze nicht mit nicht vertrauenswürdigen Workloads, die Client-IPs über X-Forwarded-For fälschen könnten.Das ALB-Attribut zur Beibehaltung des Client-Ports, routing.http.xff_client_port.enabled, kann bei beiden Einstellungen bleiben: Wenn es aktiviert ist, schreibt der ALB den Client als 203.0.113.7:54321 oder [2001:db8::1]:54321, und das Gateway liest beide mit dem Port gelöscht.
gateway.yaml
Nur der oidc Block ist Okta-spezifisch. Um stattdessen Microsoft Entra ID zu verwenden, setzen Sie issuer auf https://login.microsoftonline.com/<tenant-id>/v2.0, lassen Sie userinfo_fallback und den groups Scope weg, und beachten Sie, dass Entra Gruppen-Objekt-IDs statt Namen ausgibt, daher müssen managed.policies auf den GUIDs abgleichen, oder auf App-Rollen mit oidc.groups_claim: roles. Siehe Identitätsanbieter-Setup.
5

Speichern Sie Geheimnisse in AWS Secrets Manager

Erstellen Sie drei Geheimnisse; die Ausführungsrolle aus dem IAM-Schritt kann sie bereits lesen:
Beachten Sie die ARN, die jeder Aufruf ausgibt; die ECS-Task-Definition referenziert Geheimnisse nach ARN.
Literal --secret-string Argumente sind in der Prozesstabelle und in Audit-/EDR-Protokollen sichtbar, während jeder Befehl ausgeführt wird. Auf einem gemeinsamen oder überwachten Host legen Sie den Wert in eine 0600 Datei und übergeben Sie stattdessen --secret-string file://<path>. Das setup.sh des Bundles hält Geheimniswerte auf die gleiche Weise aus dem Prozess-argv, indem es 0600 temporäre Dateien an --cli-input-json übergibt.
Im Gegensatz zu den Geheimnissen enthält gateway.yaml selbst keine Geheimniswerte, da jede Anmeldedaten beim Start über ${VAR} oder ${file:...} Erweiterung aufgelöst wird. Wie alles den Container erreicht, unterscheidet sich je nach Pfad:
  • Auf ECS kopiert der Build des nächsten Schritts gateway.yaml in das Image bei /etc/claude/gateway.yaml, und die Task-Definition injiziert die drei Geheimnisse als Umgebungsvariablen über sein secrets Feld, daher referenziert die YAML ${GATEWAY_JWT_SECRET}, ${OIDC_CLIENT_SECRET} und ${GATEWAY_POSTGRES_URL}.
  • Auf EKS mounten Sie gateway.yaml aus einer ConfigMap und die Geheimnisse als Dateien bei /secrets, referenziert als ${file:/secrets/...}. Beziehen Sie die Kubernetes Secrets aus Secrets Manager mit dem External Secrets Operator oder dem AWS-Provider des Secrets Store CSI-Treibers, oder erstellen Sie sie direkt mit kubectl.
6

Erstellen Sie das Image und pushen Sie es zu Amazon ECR

Erstellen Sie das Image gemäß den Container-Image-Anforderungen, wobei Sie die linux-x64 glibc-Binärdatei bei ./claude im Build-Kontext platzieren. Schreiben Sie Ihr eigenes Dockerfile gemäß diesen Anforderungen oder beginnen Sie mit dem Dockerfile des Bundles, das die ausgefüllte gateway.yaml aus den vorherigen Schritten in das Image bei /etc/claude/gateway.yaml kopiert. Auf ECS ist diese eingebettete Kopie, wie die Konfiguration den Container erreicht, weshalb der Build nach dem Schreiben der Datei kommt. Der EKS-Pfad mountet stattdessen gateway.yaml aus einer ConfigMap bei der Bereitstellung, daher ist die eingebettete Kopie dort ungenutzt.Das Image trägt auch das AWS RDS Zertifikat-Bundle als Vertrauensanker für das sslmode=verify-full der Verbindungszeichenfolge, daher laden Sie es zunächst in den Build-Kontext herunter. AWS rotiert das Bundle (neue regionale CAs werden angehängt), daher laden Sie es pro Build herunter, statt einen Checksum zu pinnen oder es zu committen:
Die Container-Image-Anforderungen decken das Bundle nicht ab, daher müssen Sie, wenn Sie Ihr eigenes Dockerfile schreiben, die zwei Zeilen hinzufügen, die es kopieren und vertrauen; das Dockerfile des Bundles enthält bereits beide:
Erstellen Sie das ECR-Repository und melden Sie Docker darin an. Unveränderliche Tags bedeuten, dass das <version> Tag, das der Bereitstellungsschritt pinnt, später nicht stillschweigend auf ein anderes Image umgeleitet werden kann:
Erstellen und pushen Sie das Image. Die Task-Definition unten führt linux/amd64 aus, daher muss die Plattform hier übereinstimmen; für Fargate auf ARM64 (Graviton) erstellen Sie linux/arm64 mit der linux-arm64 Binärdatei und setzen Sie cpuArchitecture stattdessen auf ARM64:
7

Bereitstellen

Erstellen Sie den Cluster und eine Log-Gruppe für die stderr des Gateways, die sowohl seine Audit-Events als auch Betriebsprotokolle trägt. Die Aufbewahrung ist ein separater Aufruf, und ohne eine CloudWatch behält die Protokolle für immer; richten Sie die 90 Tage auf Ihre Audit-Aufbewahrungsrichtlinie aus:
Schreiben Sie die Task-Definition. Die Task-Rolle trägt die Bedrock-Berechtigung und die Ausführungsrolle injiziert die Geheimnisse; verwenden Sie die Geheimnis-ARNs aus dem Secrets Manager-Schritt:
claude-gateway-task.json
Registrieren Sie es:
Setzen Sie einen internen ALB davor mit einer Zielgruppe, die das Gateway health-checkt. --ip-address-type ipv4 ist wichtig: Ein interner Dual-Stack-ALB veröffentlicht öffentliche AAAA-Datensätze, die die /login private-Netzwerk-Prüfung ablehnt:
Fügen Sie den HTTPS-Listener hinzu. --ssl-policy pinnt einen modernen TLS-Boden, da das Weglassen auf die Legacy-Standard-Richtlinie ELBSecurityPolicy-2016-08 zurückfällt, die immer noch TLS 1.0/1.1 akzeptiert.Der ALB schließt eine Verbindung nach 60 Sekunden ohne Daten standardmäßig. Die Keepalive-Pings des Gateways halten Streams innerhalb dieses Standards, daher erhöht das Erhöhen des Timeouts die Marge über der Ping-Kadenz; die Troubleshooting Zeile auf abgebrochenen Streams behandelt den Mechanismus und ältere Gateways. Die folgenden Befehle fügen den Listener hinzu und erhöhen das Timeout:
Erstellen Sie den Service. Der Deployment-Schalter rollt eine Bereitstellung, deren Tasks weiterhin fehlschlagen, von einem schlechten Image oder einer nicht bootfähigen Konfiguration, zurück zum letzten stabilen Zustand, statt fehlgeschlagene Tasks für immer neu zu starten:
Die 60-Sekunden-Gnadenfrist gibt einer kalten Task Zeit, das Image zu ziehen, sich mit dem Store zu verbinden und seinen ersten Health-Check zu beantworten, bevor ECS beginnt, Fehler gegen die Bereitstellung zu zählen. Der Health-Check der Zielgruppe auf GET /readyz überprüft, ob der Store erreichbar ist, daher kommt eine Task, die Postgres nicht erreichen kann, nie in Rotation; siehe Ausfallverhalten für den Tradeoff und die /healthz Alternative.Die Tasks laufen in privaten Subnetzen ohne öffentliche IP, daher geht der gesamte Egress (zu Bedrock, Ihrem IdP, Secrets Manager, ECR und CloudWatch Logs) durch das NAT-Gateway. Um Bedrock-Verkehr vom öffentlichen Pfad zu halten, erstellen Sie einen bedrock-runtime Interface VPC-Endpunkt und zeigen Sie die base_url des Upstream darauf, wie in der Bedrock Upstream-Referenz gezeigt; der IdP benötigt immer noch Internet-Egress.Beenden Sie, indem Sie Entwicklern einen privat auflösbaren Hostnamen geben: In einer Route 53 privaten gehosteten Zone, alias den internen DNS-Namen des Gateways zum ALB, und setzen Sie listen.public_url auf diesen Hostnamen. Der eigene *.elb.amazonaws.com Name des ALB wird zu privaten Adressen auf einem internen ALB aufgelöst, kann aber Ihr ACM-Zertifikat nicht tragen, daher verwenden Sie Ihren eigenen Namen.Aktualisieren Sie die autorisierte Redirect-URI des OAuth-Clients auf <public_url>/oauth/callback, bevor die erste Anmeldung. Nach dem Ändern von public_url erstellen Sie das Image unter einem neuen Tag neu, registrieren Sie eine neue Task-Definition-Revision und stellen Sie erneut bereit. Auf ECS lebt die Einstellung in der eingebetteten gateway.yaml des Images, und das Gateway erstellt seinen öffentlichen Ursprung nur aus dieser Einstellung, ignoriert X-Forwarded-Host und X-Forwarded-Proto. X-Forwarded-For wird nur berücksichtigt, wenn listen.trusted_proxies gesetzt ist.
8

Pushen Sie die Gateway-URL zu Entwicklermaschinen

Das Gateway läuft jetzt, aber Entwickler können es von /login nicht erreichen, bis die Gateway-URL auf ihren Maschinen ist. Setzen Sie forceLoginMethod und forceLoginGatewayUrl in der verwalteten Einstellungsdatei, die Sie über MDM auf jedes Gerät bereitstellen. Es gibt keine Gateway-Option im Login-Picker für einen Entwickler, um manuell auszuwählen.

Terraform-Referenz

Das Begleit-Bundle bei examples/gateway/aws packt diese Seite als Code:
  • setup.sh skriptet die Bereitstellungs-Anleitung oben mit den gleichen aws Befehlen auf dem ECS Fargate-Pfad. Es ist idempotent: Bestehende Ressourcen werden erkannt und übersprungen, daher ist das erneute Ausführen sicher, und jeder Standard kann über Umgebungsvariable überschrieben werden. Sie erstellen immer noch das Okta OIDC-Client-Geheimnis und das ACM-Zertifikat selbst: Ein Lauf ohne sie überspringt die ECS/ALB-Bereitstellung, nennt die fehlenden Eingaben und druckt den create-secret Befehl; erstellen Sie beide und führen Sie erneut aus. Das Bedrock-Use-Case-Formular und der Route 53-Alias werden als nächste Schritte statt automatisch ausgeführt, und der Client-MDM-Push bleibt ein manueller Schritt von dieser Seite.
  • gateway.yaml.example ist die Konfigurationsvorlage aus dem gateway.yaml-Schritt, mit den optionalen Schlüsseln kommentiert. Kopieren Sie sie zu gateway.yaml und ersetzen Sie jeden REPLACE_ME, bevor Sie erstellen.
  • Dockerfile erstellt das Runtime-Image aus der vorkompilierten linux-x64 Binärdatei und kopiert Ihre ausgefüllte gateway.yaml bei /etc/claude/gateway.yaml, plus das AWS RDS Zertifikat-Bundle, das das sslmode=verify-full des Stores verankert. setup.sh lädt das Bundle nur herunter, wenn es nicht bereits im Build-Kontext ist; löschen Sie die Datei und erstellen Sie unter einem neuen Tag neu, um eine AWS CA-Rotation zu erhalten. Die Konfigurationsdatei enthält keine Geheimniswerte, da jede Anmeldedaten beim Start über ${VAR} Erweiterung aufgelöst wird. Eine Konfigurationsbearbeitung bedeutet daher einen Rebuild unter einem neuen Tag; setup.sh automatisiert dies durch Tagging-Images mit einem Hash der Datei.
  • terraform/ stellt den gleichen ECS Fargate-Umfang deklarativ bereit: die Sicherheitsgruppen, IAM-Rollen, ECR-Repository, RDS-Instanz, Secrets Manager-Geheimnisse und den ECS-Service hinter dem internen ALB. Das VPC und die privaten Subnetze bleiben Voraussetzungen, die als Variablen übergeben werden. Terraform erstellt das ECR-Repository, erstellt aber nicht das Image, und die Service-Definition referenziert das Image, daher ist die Anwendung zwei Durchläufe: eine gezielte Anwendung für das Repository, dann der Build und Push, dann die vollständige Anwendung. Das terraform/README.md des Bundles behandelt die Variablen, den Remote-State und den Abbau.
Wie diese Seite ist das Bundle ein funktionierendes Beispiel für kundenverwaltete Infrastruktur statt einer unterstützten Produktionsbereitstellung; überprüfen und passen Sie es an Ihre eigene Umgebung an, bevor Sie sich darauf verlassen.

Troubleshooting

Für Gateway-Boot- und Login-Fehler siehe die plattformunabhängige Troubleshooting-Tabelle. Die Einträge unten sind spezifisch für AWS.

Telemetrie

Das Gateway gibt Ihnen pro-Entwickler Nutzungsmetriken ohne jede pro-Maschinen OTEL-Konfiguration. Claude Code gibt OpenTelemetry (OTLP) Metriken, Protokolle und Opt-in-Traces aus; Überwachung der Nutzung behandelt alles, was die CLI meldet. Bei Gateway-Sitzungen stempelt die CLI jeden Export mit den authentifizierten IdP-Identitätsattributen user.id, user.email und user.groups, daher wird die Nutzung pro Entwickler ohne OTEL_RESOURCE_ATTRIBUTES Rohrleitungen zusammengefasst. Das Gateway selbst ist ein authentifiziertes OTLP-Relais. Setzen Sie telemetry.forward_to zusammen mit listen.public_url, und es pusht die OTEL-Exporter-Einstellungen zu jedem verbundenen Client und leitet seinen OTLP-Verkehr wörtlich zu jedem Ziel weiter, das Sie auflisten. Jedes Ziel entscheidet sich unabhängig für Metriken, Protokolle und Traces, und der Standard ist nur Metriken; siehe die telemetry Referenz für die pro-Signal-Felder und ihre Empfindlichkeits-Tradeoffs. Das Gateway puffert, aggregiert oder speichert keine Telemetrie, daher ist, wo die Daten landen, vollständig die Exporter-Konfiguration des Collectors. Client-Telemetrie ist standardmäßig aus; das Konfigurieren von telemetry.forward_to ist, was sie für verbundene Entwickler einschaltet, und jeder interaktive Client zeigt einen einmaligen Sicherheitsgenehmigungsdialog für die gepushten Einstellungen, wie in der Konfigurationsreferenz beschrieben. Auf AWS wird jedes Signal wie folgt einem Ziel zugeordnet.

Client-Metriken, Protokolle und Traces

Zeigen Sie telemetry.forward_to auf einen OpenTelemetry-Collector, wie den AWS Distro for OpenTelemetry (ADOT) Collector, und exportieren Sie von dort zu Amazon CloudWatch, Amazon Managed Service for Prometheus oder einem beliebigen OTLP-Backend. Führen Sie den Collector als seinen eigenen internen Service aus, der über https:// erreichbar ist; die telemetry Referenz behandelt die Loopback-Ausnahme und CLAUDE_GATEWAY_ALLOW_LOOPBACK.

Gateway-Protokolle

Auf ECS Fargate, kein zusätzliches Setup: Der awslogs Treiber liefert die stderr des Gateways, die seine Audit-Events und Betriebsprotokolle trägt, zur /ecs/claude-gateway Log-Gruppe, die oben erstellt wurde. Auf EKS erreichen Pod-Protokolle CloudWatch nicht standardmäßig, daher geht die Audit-Spur verloren, bis Sie Log-Erfassung installieren: Das Amazon CloudWatch Observability Add-on mit aktivierter Container-Log-Erfassung, oder ein Fluent Bit DaemonSet. Auf beiden Pfaden fragen Sie die Protokolle mit CloudWatch Logs Insights ab und fahren Alarme von Metrik-Filtern.

Container-Metriken

Aktivieren Sie Container Insights auf dem Cluster mit aws ecs update-cluster-settings --cluster claude-gateway --settings name=containerInsights,value=enabled für pro-Task CPU, Speicher und Netzwerk. Auf EKS installieren Sie das Amazon CloudWatch Observability Add-on.

Ausgaben

Telemetrie zeigt Nutzung im Nachhinein; Ausgabenlimits sind die Live-Ansicht des Gateways pro Entwickler und Durchsetzung auf der gemeinsamen Upstream-Anmeldedaten.

Nächste Schritte