Skip to Content
👋 Willkommen bei HowToUseOpenClaw Schnellstart
GatewayGateway-Überblick

Gateway-Überblick

Der Gateway ist das Herz Ihrer OpenClaw-Installation—ein dauerhaft laufender Dienst, der Ihre Messaging-Verbindungen (WhatsApp, Telegram usw.) besitzt und die gesamte Orchestrierung zwischen Chat-Kanälen und Ihren Agenten übernimmt.

Stellen Sie ihn sich als Dirigenten vor: Er hört auf eingehende Nachrichten, leitet sie an die richtige Agenten-Sitzung weiter, streamt Antworten zurück und hält alles verbunden, auch wenn Sie nicht aktiv chatten.

Was er tut

  • Unterhält dauerhafte Verbindungen zu Messaging-Plattformen (Baileys für WhatsApp, Bot-API für Telegram usw.)
  • Stellt eine WebSocket-Kontrollebene für CLI, Apps und Remote-Nodes bereit
  • Bedient HTTP-Endpunkte für OpenAI-kompatible APIs, Webhooks und die Control-UI
  • Verwaltet Agenten-Sitzungen, Nachrichten-Warteschlangen und Zustellung
  • Unterstützt Hot-Reload der Konfiguration und In-Process-Neustarts (kein Ausfall bei den meisten Änderungen)

Einstiegspunkt: openclaw gateway

Lokal ausführen

Einfacher Start:

openclaw gateway

Das war’s. Der Gateway bindet standardmäßig an 127.0.0.1:18789 und läuft, bis Sie ihn stoppen.

Mit Optionen:

# Anderen Port verwenden
openclaw gateway --port 19000
 
# Debug-Modus (alle Log-Ereignisse in die Konsole spiegeln)
openclaw gateway --verbose
 
# Zuerst alles auf dem Port beenden, dann starten
openclaw gateway --force
 
# Dev-Modus (Auto-Reload bei Code-Änderungen)
pnpm gateway:watch

Der Gateway überwacht Ihre Konfigurationsdatei (standardmäßig ~/.clawdbot/openclaw.json) und lädt unkritische Änderungen per Hot-Reload. Kritische Änderungen lösen einen In-Process-Neustart per SIGUSR1 aus.

Hot-Reload mit gateway.reload.mode="off" deaktivieren, wenn Sie manuelle Kontrolle bevorzugen.

Authentifizierung

Standardmäßig verlangt der Gateway Authentifizierung, auch auf localhost. Token oder Passwort setzen:

# Token während des Setups erzeugen
openclaw setup
 
# Oder manuell setzen
export CLAWDBOT_GATEWAY_TOKEN="your-secret-token"

Anschließend Ihre Clients (CLI, Apps, Nodes) so konfigurieren, dass sie auth.token im WebSocket-Handshake mitsenden.

Tailscale-Nutzer: Bei Nutzung von Tailscale Serve mit gateway.auth.allowTailscale: true können Anfragen aus Ihrem Tailnet sich über Tailscale-Identity-Header statt über Token authentifizieren.

Fernzugriff

Empfohlen: Tailscale oder VPN

Halten Sie Ihren Gateway privat. Nutzen Sie Tailscale, um von überall darauf zuzugreifen, ohne Ports ins Internet zu öffnen.

Vollständige Anleitung: Tailscale-Setup.

Alternative: SSH-Tunnel

Wenn Tailscale nicht infrage kommt, per SSH tunneln:

ssh -N -L 18789:127.0.0.1:18789 user@remote-host

Dann die CLI mit ws://127.0.0.1:18789 verbinden, als wäre der Gateway lokal.

Mehrere Gateways (meist nicht nötig)

Ein Gateway kann mehrere Messaging-Kanäle und Agenten problemlos bedienen. Mehrere Gateways brauchen Sie nur für:

  • Redundanz (ein Rettungs-Bot, der läuft, wenn Ihre Haupt-Installation ausfällt)
  • Strenge Isolation (getrennte Produktions- und Entwicklungsumgebungen)

In dem Fall: State-Verzeichnisse, Konfigurationsdateien und Ports isolieren.

Muster und Beispiele: Mehrere Gateways.

Dev-Profil (isoliertes Testen)

Änderungen testen, ohne die Produktions-Installation anzurühren? --dev verwenden:

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status

Das Dev-Profil nutzt isolierte Verzeichnisse und Ports:

  • Konfiguration: ~/.clawdbot-dev/openclaw.json
  • State: ~/.clawdbot-dev/
  • Workspace: ~/clawd-dev/
  • Port: 19001 (vs. 18789 für main)

Keine Konflikte mit Ihrem Haupt-Gateway.

Dienstverwaltung

Als Systemdienst installieren:

# macOS (launchd)
openclaw gateway install
 
# Linux (systemd user service)
openclaw gateway install
sudo loginctl enable-linger $USER
 
# Status prüfen
openclaw gateway status

Steuerung:

openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw logs --follow

Der Gateway läuft als überwachter Dienst (launchd unter macOS, systemd unter Linux). Bei Absturz startet der Supervisor ihn automatisch neu.

Dienstnamen

Dienste nutzen profilabhängige Namen:

  • macOS: bot.molt.gateway (oder bot.molt.<profile>)
  • Linux: openclaw-gateway.service (oder openclaw-gateway-<profile>.service)

systemd (Linux/WSL2)

Standardmäßig installiert OpenClaw einen User-Service (einfacher für Einzelplatz). Für dauerhaft laufende Server stattdessen einen System-Service verwenden.

User-Service (Standard):

openclaw gateway install
sudo loginctl enable-linger $USER
systemctl --user enable --now openclaw-gateway.service

System-Service (Multi-User/Dauerbetrieb):

/etc/systemd/system/openclaw-gateway.service mit passendem User= und WorkingDirectory= anlegen, dann:

sudo systemctl daemon-reload
sudo systemctl enable --now openclaw-gateway.service

Beispiele für Unit-Dateien: Hintergrundprozess.

Endpunkte und Ports

Der Gateway bündelt alles auf einem Port (Standard 18789):

  • WebSocket (/) — Haupt-Kontrollebene für CLI, Apps und Nodes
  • HTTP-APIs:
    • /v1/chat/completions — OpenAI-kompatible Chat-API
    • /v1/responses — OpenResponses-API
    • /tools/invoke — direkte Tool-Aufrufe
  • Control-UI (Web-Dashboard, falls aktiviert)
  • Canvas-Dateiserver (Standard Port 18793, separater Port) — liefert ~/clawd/canvas unter /__openclaw__/canvas/

Browser-Steuerung nutzt abgeleitete Ports:

  • Control-Service: Gateway-Port + 2 (z. B. 18791)
  • Extension-Relay: Gateway-Port + 3 (z. B. 18792)
  • Browser-Profile vergeben CDP-Ports automatisch im Bereich 18800–18899

Basis-Port mit --port, CLAWDBOT_GATEWAY_PORT oder gateway.port in der Konfiguration ändern.

Protokoll-Grundlagen

Clients verbinden sich per WebSocket und müssen zuerst eine connect-Anfrage senden:

{
  "type": "req",
  "id": "1",
  "method": "connect",
  "params": {
    "minProtocol": 7,
    "maxProtocol": 7,
    "client": {
      "id": "cli-abc123",
      "version": "1.0.0",
      "platform": "darwin",
      "mode": "operator"
    },
    "auth": {
      "token": "your-gateway-token"
    }
  }
}

Der Gateway antwortet mit einem hello-ok-Payload, der Presence, Health und Konfigurations-Snapshots enthält—alles, was Sie brauchen, um den State ohne weitere Anfragen darzustellen.

Nach dem Handshake:

  • Anfragen folgen dem Muster {type:"req", id, method, params} → {type:"res", id, ok, payload}
  • Ereignisse werden als {type:"event", event, payload} gepusht

Häufige Ereignisse: agent (gestreamte Tool-Ausgabe), presence (wer verbunden ist), tick (Keepalive), shutdown (Gateway startet neu).

Vollständige Spezifikation: Gateway-Protokoll.

Wichtige Methoden

  • health — vollständiger System-Health-Snapshot
  • status — kurze Zusammenfassung
  • agent — einen Agenten-Durchlauf ausführen (streamt Ereignisse zurück)
  • send — Nachricht über einen Kanal senden
  • system-presence — verbundene Clients auflisten
  • node.* — Remote-Nodes finden, koppeln und steuern
  • cron.* — geplante Jobs verwalten

Konfigurations-Hot-Reload

Der Gateway überwacht openclaw.json auf Änderungen. Beim Speichern:

  • Unkritische Änderungen (Allowlists, Schwellen, Feature-Flags) werden sofort angewendet
  • Kritische Änderungen (Kanal-Credentials, Bind-Adresse) lösen einen automatischen Neustart aus

Standardmodus ist "hybrid". Mit gateway.reload.mode="off" komplett deaktivieren.

In-Process-Neustart

SIGUSR1 senden für Neustart ohne Stopp:

kill -USR1 $(pgrep -f "openclaw gateway")

Oder das gateway-Tool aus einem Agenten nutzen:

{
  "tool": "gateway",
  "action": "restart",
  "delayMs": 2000
}

Der Neustart beendet zuerst den aktuellen Agenten-Lauf, sendet ein shutdown-Ereignis, lädt alles neu und ist nach Sekunden wieder da.

Betriebliche Health-Checks

Liveness:

  • Können Sie eine WebSocket-Verbindung zum Gateway-Port herstellen?
  • Erhält eine connect-Anfrage eine hello-ok-Antwort?

Readiness:

  • Gibt health ok: true zurück?
  • Ist Ihr Haupt-Messaging-Kanal verknüpft? (in der Health-Payload linkChannel prüfen)

Monitoring:

  • Auf presence-Ereignisse abonnieren—wenn keine Updates mehr kommen, stimmt etwas nicht
  • Auf shutdown-Ereignisse achten (geplante Neustarts vs. Abstürze)
  • status für Warteschlangentiefe und Fehlerzahlen prüfen

Sicherheitslage

  • Standardmäßig an localhost gebunden (127.0.0.1:18789)—nur lokale Prozesse können sich verbinden
  • Auth erforderlich auch auf Loopback—kein Zugriff ohne Authentifizierung
  • Tailscale Serve für Fernzugriff nutzen (identitätsbasierte Auth, verschlüsselter Tunnel)
  • Keine öffentliche Exposition—nicht an 0.0.0.0 binden ohne starke Auth und Firewall

Wenn Sie Fernzugriff brauchen:

  • Tailscale Serve/Funnel (bevorzugt)
  • SSH-Tunnel (Fallback)
  • VPN (WireGuard usw.)

Den Gateway-Port niemals direkt ins Internet exponieren.

Bedrohungsmodelle und Hardening-Checklisten: Sicherheit.

Fehlersuche

Gateway startet nicht:

  • Prüfen, ob der Port bereits belegt ist: lsof -i :18789
  • openclaw gateway --force nutzen, um bestehende Listener zu beenden
  • Logs prüfen: openclaw logs oder ~/.clawdbot/logs/gateway.log

CLI kann sich nicht verbinden:

  • Prüfen, ob der Gateway läuft: openclaw gateway status
  • Prüfen, ob der Auth-Token übereinstimmt: echo $CLAWDBOT_GATEWAY_TOKEN
  • Verbindung mit expliziter URL versuchen: openclaw --url ws://127.0.0.1:18789 status

Kanal nicht verknüpft:

  • WhatsApp: openclaw setup ausführen und QR-Code scannen
  • Telegram: channels.telegram.accounts prüfen und Bot-Token verifizieren
  • openclaw doctor für einen Health-Check ausführen

Vollständiges Runbook: Fehlersuche.

Nächste Schritte

Zuletzt aktualisiert am:
Authentifizierung