Skip to main content

​
Gateway‑Dienst‑Runbook

Verwenden Sie diese Seite für den Day-1-Start und die Day-2-Operationen des Gateway-Dienstes.

Deep troubleshooting

Symptomorientierte Diagnose mit exakten Befehlsabfolgen und Log-Signaturen.

Configuration

Aufgabenorientierte Einrichtungsanleitung + vollständige Konfigurationsreferenz.

​
5-Minuten-Local-Startup

1

Start the Gateway

2

Verify service health

Gesunde Basis: Runtime: running und RPC probe: ok.
3

Validate channel readiness

Das Gateway-Konfigurations-Reload überwacht den aktiven Konfigurationsdateipfad (aufgelöst aus Profil-/Status-Standardwerten oder OPENCLAW_CONFIG_PATH, wenn gesetzt). Standardmodus: gateway.reload.mode="hybrid" (sichere Änderungen hot anwenden, Neustart bei kritischen Änderungen).

​
Laufzeitmodell

  • Ein dauerhaft laufender Prozess für Routing, Control Plane und Kanalverbindungen.
  • Single‑Port‑Multiplex.
    • WebSocket-Control/RPC
    • OpenResponses (HTTP): /v1/responses.
    • Control-UI und Hooks
  • Standard-Bind-Modus: loopback.
  • Gateway‑Authentifizierung ist standardmäßig erforderlich: setzen Sie gateway.auth.token (oder OPENCLAW_GATEWAY_TOKEN) oder gateway.auth.password.

​
Port- und Bind-Priorität

​
Hot-Reload-Modi

​
Operator-Befehlssatz

​
Remote‑Zugriff

Tailscale/VPN bevorzugt; andernfalls SSH‑Tunnel: Fallback: SSH-Tunnel.
Clients verbinden sich anschließend über den Tunnel mit ws://127.0.0.1:18789.
Wenn ein Token konfiguriert ist, müssen Clients es auch über den Tunnel in connect.params.auth.token mitsenden.
Siehe: Remote Gateway, Authentication, Tailscale.

​
Überwachung und Service-Lebenszyklus

Verwenden Sie überwachte Läufe für produktionsähnliche Zuverlässigkeit.
OpenClaw.app kann ein Node‑basiertes Gateway‑Relay bündeln und einen benutzerbezogenen LaunchAgent mit der Bezeichnung bot.molt.gateway (oder bot.molt.<profile> ; Legacy com.openclaw.*‑Labels werden weiterhin sauber entladen).(benanntes Profil).openclaw doctor` prüft und behebt Konfigurationsabweichungen des Service.

​
Mehrere Gateways (gleicher Host)

Die meisten Setups sollten ein Gateway ausführen. Verwenden Sie mehrere Gateways nur für Redundanz oder strikte Isolation (z. B. Checkliste pro Instanz:
  • eindeutiges gateway.port
  • eindeutiges OPENCLAW_CONFIG_PATH
  • eindeutiges OPENCLAW_STATE_DIR
  • eindeutiges agents.defaults.workspace
Beispiel:
Vollständige Anleitung: Multiple gateways.

​
Dev‑Profil (--dev)

Standardmäßig enthalten sind ein isolierter Status/Konfiguration und der Basis-Gateway-Port 19001.

​
Protokoll (Operator‑Sicht)

  • Der erste Client-Frame muss connect sein.
  • Das Gateway gibt einen hello-ok-Snapshot zurück (presence, health, stateVersion, uptimeMs, Limits/Policy).
  • Requests: {type:"req", id, method, params} → {type:"res", id, ok, payload|error}
  • Häufige Events: connect.challenge, agent, chat, presence, tick, health, heartbeat, shutdown.
Agent-Läufe sind zweistufig:
  1. Sofortige Bestätigungs-Antwort (status:"accepted")
  2. agent‑Antworten sind zweistufig: zuerst res‑Ack {runId,status:"accepted"}, dann ein finales res {runId,status:"ok"|"error",summary} nach Abschluss des Laufs; gestreamte Ausgabe trifft als event:"agent" ein.
Vollständige Doku: Gateway‑Protokoll und Bridge‑Protokoll (Legacy).

​
Betriebliche Prüfungen

​
Liveness

  • WS öffnen und connect senden.
  • hello-ok-Antwort mit Snapshot erwarten.

​
Readiness

​
Gap-Recovery

Events werden nicht wiederholt. Bei Sequenzlücken den Status (health, system-presence) aktualisieren, bevor fortgefahren wird.

​
Häufige Fehlersignaturen

Für vollständige Diagnoseleitfäden siehe Gateway Troubleshooting.

​
Sicherheitsgarantien

  • Gateway-Protokoll-Clients schlagen sofort fehl, wenn das Gateway nicht verfügbar ist (kein impliziter Direct-Channel-Fallback).
  • Ungültige/Nicht-connect-First-Frames werden abgelehnt und die Verbindung wird geschlossen.
  • Geordneter Shutdown: Emit shutdown‑Event vor dem Schließen; Clients müssen Close + Reconnect handhaben.
Verwandt: