2026 OpenClaw in der Praxis: Gateway-Metrik-Export und Schwellenalarme auf gemietetem Remote-Mac (Prometheus- / OpenTelemetry-kompatibles HowTo)

Prometheus scraped klassisch HTTP-Endpunkte im Raster. OpenTelemetry exportiert häufig per OTLP aus Apps oder Collectors—Sie können aber brücken: einen OTel-Collector mit Prometheus-Receiver laufen lassen, der Ihr Gateway (oder einen Sidecar) abfragt, und danach an Ihr Vendor-Backend schicken. Auf einem Miet-Mac mit kleiner Blast-Radius beginnen Sie mit drei Signalen: (1) synthetische Verfügbarkeit über /healthz und /readyz, (2) Host-CPU, RAM und Platte über node_exporter oder den Agenten Ihres Anbieters, (3) strukturierte Gateway-Logs für Kausalität, sobald eine Probe rot wird.

Wenn OpenClaw später eine erste Klasse /metrics-Seite oder natives OTLP liefert, behalten Sie dieselben Job-Labels (env, instance, service_name=openclaw-gateway) bei—sonst springen Dashboards und Alarme bei jedem Release. Dieses HowTo konzentriert sich auf Erreichbarkeit, Probelatenz und Log-Korrelation; projektbezogene Budget-Zähler am Gateway ergänzen Sie bei Bedarf separat.

Der Gateway-Listener (häufig 18789) stellt leichte Probes bereit. Prüfen Sie zuerst in der Shell auf dem Miet-Host—ohne Mehrdeutigkeit im Netzpfad:

# Liveness: Prozess oben, HTTP-Stack antwortet
curl -fsS http://127.0.0.1:18789/healthz

# Readiness: Abhängigkeiten ausreichend für neue Arbeit (Semantik je Release)
curl -fsS http://127.0.0.1:18789/readyz

Vom Laptop spiegeln Sie dieselben Checks über einen SSH-Tunnel (empfohlen, wenn das Gateway an Loopback bindet):

ssh -N -L 18789:127.0.0.1:18789 user@miet-host
curl -fsS http://127.0.0.1:18789/healthz

Im Runbook erwarteten Body und Statuscode festhalten, damit der Dienst „grün“ eindeutig ist. Fällt readyz aus, während healthz grün bleibt, werten Sie das als degradiert: Prozess lebt, neue Sessions sind riskant—korrelieren Sie mit voller Platte, hängenden Subprozessen oder API-Ausfällen in den Logs.

Zeigen Sie Prometheus (oder den prometheus-Receiver des OTel-Collectors) auf dieselben URLs. Zwei gängige Muster:

• Nativer Scrape — Wenn das Gateway Prometheus-Textformat unter z. B. /metrics ausliefert, scrapen Sie dieses Ziel direkt.
• Blackbox-Probe — Nutzen Sie das Modul http_2xx des blackbox_exporter gegen /healthz und /readyz, wenn nur HTTP-Probes verfügbar sind.

Intervall-Richtwerte: 15s für interaktive Control Planes, wenn Minuten „blind“ zu teuer sind; 30s als ausgewogener Default; 60s, wenn der Mac überbucht ist oder der Scrape einen hohen Latenz-Tailnet-Pfad kreuzt. global.scrape_interval und job-spezifisches scrape_interval konsistent halten—evaluation_interval sollte kleiner oder gleich dem feinsten Alarmfenster sein, das Sie durchsetzen wollen.

scrape_configs:
  - job_name: openclaw_gateway_health
    scrape_interval: 30s
    metrics_path: /probe
    params:
      module: [http_2xx]
    static_configs:
      - targets:
          - http://127.0.0.1:18789/healthz
          - http://127.0.0.1:18789/readyz
        labels:
          service: openclaw-gateway
          env: prod-rental-mac
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - target_label: __address__
        replacement: 127.0.0.1:9115  # blackbox_exporter Listen-Adresse

Unter Docker ersetzen Sie 127.0.0.1 durch den veröffentlichten Host-Port oder die Bridge-IP aus Ihrer Compose-Doku. Ziel ist eine Quelle der Wahrheit für „erreichen wir das Gateway?“, bevor Sie in RED-Metriken investieren.

Die folgenden Metriknamen gehen von probe_success via Blackbox aus; bei nativer Exposition ersetzen Sie durch Ihre Histogramme oder Counter.

groups:
  - name: openclaw_gateway
    interval: 30s
    rules:
      - alert: OpenClawHealthzDown
        expr: probe_success{job="openclaw_gateway_health"} == 0
        for: 2m
        labels:
          severity: page
        annotations:
          summary: "OpenClaw Health-Probe schlägt fehl"
          description: "Ziel {{ $labels.instance }} ist länger als 2m rot."

      - alert: OpenClawReadyzDegraded
        expr: probe_success{job="openclaw_gateway_health", instance=~".*readyz.*"} == 0
        for: 5m
        labels:
          severity: ticket
        annotations:
          summary: "OpenClaw Readiness fehlgeschlagen (Arbeit ggf. unsicher)"

      - alert: OpenClawProbeSlow
        expr: probe_duration_seconds > 2
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Gateway-Probes langsamer als 2s"

Ergänzen Sie bei Request-Countern oder Latenz-Histogrammen (Gateway-nativ oder Sidecar wie Envoy/Caddy) klassische SLO-Regeln: Fehlerrate auf 5xx oder Tool-Failures, p95-Latenz über Budget. Kardinalität auf geteilten Miet-Hosts niedrig halten—explodierende Labels pro Nutzer-ID belasten Prometheus und Ihr Portemonnaie gleichermaßen.

Metriken sagen wann, Logs warum. Standardisieren Sie Felder, damit jeder Alarm in einem Sprung im Log landet:

• Zeitstempel — RFC3339 mit Zeitzone; Uhrzeit auf dem Miet-Mac per sntp synchron halten.
• level — info, warn, error; error an Paging-Policy hängen.
• request_id oder trace_id — Mehrtakt-Tool-Calls verfolgen.
• Kanal / Session — Welche Oberfläche das Gateway trifft (Konsole, Messaging-Bridge, CI-Webhook).
• tool oder skill_pack — Benennt den fehlgeschlagenen Codepfad.
• upstream — Modell-Vendor, HTTP-Host oder lokales Loopback-Ziel.
• duration_ms — Passt zu Spikes der Probelatenz.
• error_class — Timeout, 429, Auth, Sandbox-Verweigerung—mappt auf Playbooks.

In Grafana Loki oder Elastic: gespeicherte Abfrage service="openclaw-gateway" AND level="error" mit demselben env-Label wie in Prometheus. So bleibt der Vorfall Ende-zu-Ende nachvollziehbar, ohne dass Metriken und Logs auseinanderlaufen.

Tokens. OPENCLAW_GATEWAY_TOKEN (oder Äquivalent) gehört nicht in Prometheus-Labels. Ablage in launchd-Umgebungsdateien, Docker-Secrets oder Vault-Sidecar; Rotation im gleichen Rhythmus wie Tailscale- oder API-Keys. Niemals Geheimnisse in Scrape-URLs—Konfigurationen und Exporter-Logs sind Leckage-Flächen. Brauchen Probes Auth, terminieren Sie TLS/mTLS an einem lokalen Reverse-Proxy und scrapen Sie nur Loopback.

Ausgang (Egress). Miet-Macs als Agent-Inseln fahren oft Domain-Allowlists für Skills. Ihr Observability-Stack (OTLP-Endpunkt, Grafana Cloud, gehostetes remote_write) ist ein weiteres ausgehendes Ziel: explizit freischalten oder den Collector im Management-Netz betreiben. Sonst wirkt „Metriken fließen nicht“ wie ein Gateway-Ausfall, obwohl die Firewall nur ihre Arbeit macht.

Rate und Kardinalität. Hochfrequente Scrapes plus ausführliche Debug-Logs können dieselbe CPU-Budget knappen wie Ihre Agenten. Debug lieber sampeln, in Produktion standardmäßig info, Label-Dimensionen deckeln—besonders bei mandantenfähigen Gateways.

Sollen Alarme auf dem Miet-Mac selbst laufen? Besser extern auswerten (managed Prometheus, Cloud-Monitoring), damit ein toter Host Sie noch pager kann. Ein minimales watchdog-Skript nur als letzte Reserve.

Nur Logs verfügbar? Logs in den Stack shipen, fehlerbasierte Metriken ableiten und Prometheus-Probes nachziehen—gleicher Incident-Workflow, andere Signalqualität.

Ein gemieteter Remote-Mac mit OpenClaw wird betreibbar, wenn /healthz und /readyz auf einem dokumentierten Scrape-Pfad liegen, Intervalle zur SLO-Kultur passen, PromQL-nahe Regeln Liveness und Readiness kodieren und strukturierte Logs den Kreis schließen. Härten Sie Tokens und Egress, damit Observability die Sicherheitslage nicht schwächt.

Öffentliche Listenpreise, Kauf- und Mietpfade sowie Hilfe ohne Login finden Sie auf den unten verlinkten Seiten, wenn Sie diesen Stack an dauerhafte Mac-Kapazität binden wollen.