Zum Hauptinhalt springen

​
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

openclaw gateway --port 18789
# for full debug/trace logs in stdio:
openclaw gateway --port 18789 --verbose
# if the port is busy, terminate listeners then start:
openclaw gateway --force
# dev loop (auto-reload on TS changes):
pnpm gateway:watch
2

Verify service health

openclaw --profile main gateway install
openclaw --profile rescue gateway install
Gesunde Basis: Runtime: running und RPC probe: ok.
3

Validate channel readiness

openclaw channels status --probe
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

EinstellungAuflösungsreihenfolge
Abgeleitete Ports (Faustregeln):Port‑Priorität: --port > OPENCLAW_GATEWAY_PORT > gateway.port > Standard 18789.
Bind-ModusCLI/Override → gateway.bind → loopback

​
Hot-Reload-Modi

Deaktivieren mit gateway.reload.mode="off".Verhalten
offKein Konfigurations-Reload
hotNur hot-sichere Änderungen anwenden
restartBei reload-erforderlichen Änderungen neu starten
hybrid (Standard)Wenn möglich hot anwenden, andernfalls neu starten

​
Operator-Befehlssatz

openclaw gateway status
openclaw gateway install
openclaw gateway stop
openclaw gateway restart
openclaw logs --follow

​
Remote‑Zugriff

Tailscale/VPN bevorzugt; andernfalls SSH‑Tunnel: Fallback: SSH-Tunnel. 
ssh -N -L 18789:127.0.0.1:18789 user@host
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. 
Zum Neustart verwenden Sie `openclaw gateway restart` (oder `launchctl kickstart -k gui/$UID/bot.molt.gateway`).
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: 
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002
Vollständige Anleitung: Multiple gateways.

​
Dev‑Profil (--dev)

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
# then target the dev instance:
openclaw --dev status
openclaw --dev health
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

`openclaw gateway health|status` — Health/Status über den Gateway‑WS anfordern.

​
Gap-Recovery

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

​
Häufige Fehlersignaturen

SignaturWahrscheinliches Problem
weigert sich, Gateway zu binden ... ohne AuthentifizierungBind an Nicht-Loopback-Adresse ohne Token/Passwort
another gateway instance is already listening / EADDRINUSEPortkonflikt
Gateway start blocked: set gateway.mode=localKonfiguration auf Remote-Modus gesetzt
unauthorized während des VerbindungsaufbausAuthentifizierungsabweichung zwischen Client und Gateway
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: