OpenClaw Gateway CLI: Lokalen WebSocket-Server starten

Das Gateway ist der WebSocket-Server von OpenClaw, der für die Verwaltung von Channels, Nodes, Sessions und Hooks zuständig ist. Mit dem Gateway CLI kannst du diese Komponenten direkt über dein Terminal steuern und überwachen.

Gateway CLI Übersicht

Das Gateway bildet das Herzstück der Kommunikation in OpenClaw und ermöglicht eine effiziente Echtzeit-Datenübertragung. Alle Befehle in diesem Abschnitt werden über das CLI unter dem Namespace openclaw gateway ausgeführt.

1. Stelle sicher, dass du Node.js auf deinem System installiert hast, um die volle Funktionalität des Gateway zu nutzen.
2. Du kannst die verfügbaren Befehle jederzeit mit folgendem Befehl einsehen:

openclaw gateway --help

Gateway Installation und Setup

Bevor du das Gateway starten kannst, musst du die notwendigen Abhängigkeiten in deinem Projekt bereitstellen. Dies stellt sicher, dass alle JSON-Konfigurationen korrekt verarbeitet werden.

1. Installiere die erforderlichen Pakete über npm oder pnpm:

npm install @openclaw/gateway
# oder
pnpm add @openclaw/gateway

2. Überprüfe die Installation, indem du den Status des Gateway abfragst:

openclaw gateway status

Gateway Konfiguration und Webhook Anbindung

Die Konfiguration des Gateway erfolgt über eine zentrale Datei, die festlegt, wie webhook-Ereignisse empfangen und weitergeleitet werden. Eine korrekte Einrichtung ist entscheidend für die Stabilität deiner API-Verbindungen.

1. Erstelle eine Konfigurationsdatei, um dein Gateway mit deinem GitHub-Repository oder anderen Diensten zu verbinden:

{
  "gateway": {
    "port": 8080,
    "webhook_secret": "your-secret-key",
    "enable_logging": true
  }
}

2. Starte das Gateway mit deiner spezifischen Konfiguration:

openclaw gateway start --config gateway.json

Gateway Ausführung in Docker

Für eine isolierte Umgebung kannst du das Gateway in einem Docker-Container betreiben. Dies ist der empfohlene Weg, um Abhängigkeiten sauber von deinem Host-System zu trennen.

1. Nutze das offizielle Image, um das Gateway zu starten:

docker run -p 8080:8080 openclaw/gateway:latest

2. Überwache die Logs des Gateway innerhalb des Containers:

docker logs -f openclaw-gateway

Verwandte Dokumentation:

• /gateway/bonjour
• /gateway/discovery
• /gateway/configuration

AI Setup Assistant

Gateway ausführen

Du kannst einen lokalen Gateway-Prozess mit dem folgenden Befehl starten:

openclaw gateway

Für den Vordergrund-Alias verwendest du diesen Befehl:

openclaw gateway run

Beachte dabei folgende Hinweise:

1. Standardmäßig verweigert der Gateway den Start, sofern nicht gateway.mode=local in der Datei ~/.openclaw/openclaw.json gesetzt ist. Nutze --allow-unconfigured für Ad-hoc- oder Entwicklungs-Durchläufe.
2. Befehle wie openclaw onboard --mode local und openclaw setup sollten gateway.mode=local automatisch in die Konfiguration schreiben. Falls die Datei existiert, aber gateway.mode fehlt, wird dies als beschädigte Konfiguration gewertet und muss repariert werden, anstatt den lokalen Modus implizit anzunehmen.
3. Wenn die Datei vorhanden ist, aber gateway.mode fehlt, stuft der Gateway dies als verdächtige Konfigurationsbeschädigung ein und weigert sich, den lokalen Modus für dich zu “erraten”.
4. Bindungen außerhalb des Loopbacks ohne Authentifizierung sind aus Sicherheitsgründen blockiert.
5. SIGUSR1 löst einen Neustart innerhalb des Prozesses aus, sofern autorisiert (standardmäßig ist commands.restart aktiviert; setze commands.restart: false, um manuelle Neustarts zu blockieren, während Gateway-Tools sowie Konfigurationsanpassungen weiterhin erlaubt bleiben).
6. SIGINT/SIGTERM-Handler stoppen den Gateway-Prozess, stellen jedoch keinen benutzerdefinierten Terminalstatus wieder her. Falls du das CLI mit einem TUI oder Raw-Mode-Input ummantelst, stelle das Terminal vor dem Beenden wieder her.

Optionen

Hier findest du eine Übersicht der verfügbaren Optionen, um den Gateway-Start anzupassen:

1. --port <port>: WebSocket-Port (Standardwert stammt aus der Konfiguration/Umgebung; meist 18789).
2. --bind <loopback|lan|tailnet|auto|custom>: Bindungsmodus für den Listener.
3. --auth <token|password>: Überschreiben des Authentifizierungsmodus.
4. --token <token>: Token-Überschreibung (setzt zudem OPENCLAW_GATEWAY_TOKEN für den Prozess).
5. --password <password>: Passwort-Überschreibung. Achtung: Inline-Passwörter können in lokalen Prozesslisten sichtbar sein.
6. --password-file <path>: Liest das Gateway-Passwort aus einer Datei.
7. --tailscale <off|serve|funnel>: Exponiert den Gateway über Tailscale.
8. --tailscale-reset-on-exit: Setzt die Tailscale-Serve/Funnel-Konfiguration beim Herunterfahren zurück.
9. --allow-unconfigured: Erlaubt den Gateway-Start ohne gateway.mode=local in der Konfiguration. Dies umgeht die Start-Sicherheitsprüfung nur für Ad-hoc/Dev-Bootstrapping; die Konfigurationsdatei wird dabei nicht geschrieben oder repariert.
10. --dev: Erstellt eine Dev-Konfiguration sowie einen Workspace, falls diese fehlen (überspringt BOOTSTRAP.md).
11. --reset: Setzt Dev-Konfiguration, Anmeldedaten, Sitzungen und Workspace zurück (erfordert --dev).
12. --force: Beendet jeden bestehenden Listener auf dem gewählten Port vor dem Start.
13. --verbose: Aktiviert ausführliche Protokolle.
14. --cli-backend-logs: Zeigt nur CLI-Backend-Logs in der Konsole an (und aktiviert stdout/stderr).
15. --ws-log <auto|full|compact>: Stil der WebSocket-Protokolle (Standard ist auto).
16. --compact: Alias für --ws-log compact.
17. --raw-stream: Protokolliert rohe Modell-Stream-Ereignisse im JSON-Format (jsonl).
18. --raw-stream-path <path>: Pfad für den rohen JSON-Stream.

Für das Startup-Profiling stehen dir folgende Möglichkeiten zur Verfügung:

1. Setze OPENCLAW_GATEWAY_STARTUP_TRACE=1, um die Phasen-Timings während des Gateway-Starts zu protokollieren.
2. Führe pnpm test:startup:gateway -- --runs 5 --warmup 1 aus, um den Gateway-Start zu benchen. Der Benchmark zeichnet die erste Prozessausgabe, /healthz, /readyz sowie die Startup-Trace-Timings auf.

AI Setup Assistant

Einen laufenden Gateway abfragen

Alle Abfragebefehle verwenden WebSocket RPC.

Ausgabemodi:

• Standard: menschenlesbar (farbig im TTY).
• --json: maschinenlesbares JSON (ohne Styling/Spinner).
• --no-color (oder NO_COLOR=1): deaktiviert ANSI, behält aber das menschenlesbare Layout bei.

Gemeinsame Optionen (sofern unterstützt):

• --url <url>: Gateway WebSocket URL.
• --token <token>: Gateway Token.
• --password <password>: Gateway Passwort.
• --timeout <ms>: Timeout/Budget (variiert je nach Befehl).
• --expect-final: wartet auf eine „finale“ Antwort (Agenten-Aufrufe).

Hinweis: Wenn du --url setzt, greift die CLI nicht auf Konfigurations- oder Umgebungs-Anmeldedaten zurück. Übergebe --token oder --password explizit. Fehlende Anmeldedaten führen zu einem Fehler.

gateway health

Dieser Befehl prüft den Status deines Gateways.

openclaw gateway health --url ws://127.0.0.1:18789

Der HTTP /healthz Endpunkt ist ein Liveness-Probe: Er antwortet, sobald der Server HTTP-Anfragen beantworten kann. Der HTTP /readyz Endpunkt ist strenger und bleibt rot, während Startup-Sidecars, Kanäle oder konfigurierte Hooks noch initialisiert werden.

gateway usage-cost

Rufe Zusammenfassungen der Nutzungskosten aus den Sitzungsprotokollen ab.

openclaw gateway usage-cost
openclaw gateway usage-cost --days 7
openclaw gateway usage-cost --json

Optionen:

• --days <days>: Anzahl der Tage, die einbezogen werden sollen (Standard 30).

gateway status

gateway status zeigt den Gateway-Dienst (launchd/systemd/schtasks) sowie eine optionale Prüfung der Konnektivität und Authentifizierungsfähigkeit an.

openclaw gateway status
openclaw gateway status --json
openclaw gateway status --require-rpc

Optionen:

• --url <url>: fügt ein explizites Prüfziel hinzu. Konfigurierte Remote-Ziele + localhost werden weiterhin geprüft.
• --token <token>: Token-Authentifizierung für die Prüfung.
• --password <password>: Passwort-Authentifizierung für die Prüfung.
• --timeout <ms>: Prüf-Timeout (Standard 10000).
• --no-probe: überspringt die Konnektivitätsprüfung (nur Dienst-Ansicht).
• --deep: scannt auch Dienste auf Systemebene.
• --require-rpc: wertet die Standard-Konnektivitätsprüfung zu einer Lese-Prüfung auf und beendet den Prozess mit einem Fehlercode, wenn diese fehlschlägt. Kann nicht mit --no-probe kombiniert werden.

Hinweise:

• gateway status bleibt für Diagnosen verfügbar, selbst wenn die lokale CLI-Konfiguration fehlt oder ungültig ist.
• Der Standard gateway status belegt den Dienststatus, die WebSocket-Verbindung und die beim Handshake sichtbare Authentifizierungsfähigkeit. Er belegt keine Lese-/Schreib-/Admin-Operationen.
• gateway status löst konfigurierte Auth-SecretRefs für die Prüfung auf, wenn möglich.
• Wenn eine erforderliche Auth-SecretRef in diesem Befehlspfad nicht aufgelöst werden kann, meldet gateway status --json einen rpc.authWarning, wenn die Konnektivität/Authentifizierung fehlschlägt; übergebe --token/--password explizit oder löse die Secret-Quelle zuerst auf.
• Wenn die Prüfung erfolgreich ist, werden Warnungen zu nicht aufgelösten Auth-Refs unterdrückt, um Fehlalarme zu vermeiden.
• Verwende --require-rpc in Skripten und Automatisierungen, wenn ein laufender Dienst nicht ausreicht und du sicherstellen musst, dass auch Lese-RPC-Aufrufe funktionieren.
• --deep fügt einen Scan nach zusätzlichen launchd/systemd/schtasks-Installationen hinzu. Wenn mehrere Gateway-ähnliche Dienste erkannt werden, gibt die menschenlesbare Ausgabe Bereinigungshinweise aus und warnt, dass die meisten Setups nur ein Gateway pro Maschine ausführen sollten.
• Die menschenlesbare Ausgabe enthält den aufgelösten Dateipfad zum Log sowie einen Snapshot der CLI- vs. Dienst-Konfigurationspfade, um bei der Diagnose von Profil- oder Zustandsverzeichnis-Abweichungen zu helfen.
• Bei Linux systemd-Installationen lesen Abweichungsprüfungen sowohl Environment= als auch EnvironmentFile= Werte aus der Unit (einschließlich %h, Anführungszeichen, mehreren Dateien und optionalen - Dateien).
• Abweichungsprüfungen lösen gateway.auth.token SecretRefs unter Verwendung der zusammengeführten Laufzeitumgebung auf (zuerst Dienstbefehl-Umgebung, dann Prozess-Umgebung als Fallback).
• Wenn die Token-Authentifizierung nicht effektiv aktiv ist (expliziter gateway.auth.mode von password/none/trusted-proxy oder Modus nicht gesetzt, wobei Passwort gewinnen kann und kein Token-Kandidat gewinnen kann), überspringen Token-Abweichungsprüfungen die Konfigurations-Token-Auflösung.

gateway probe

gateway probe ist der Befehl, um alles zu debuggen. Er prüft immer:

• dein konfiguriertes Remote-Gateway (falls gesetzt), und
• localhost (Loopback) auch wenn ein Remote-Gateway konfiguriert ist.

Wenn du --url übergibst, wird dieses explizite Ziel vor beiden anderen geprüft. Die menschenlesbare Ausgabe kennzeichnet die Ziele als:

• URL (explicit)
• Remote (configured) oder Remote (configured, inactive)
• Local loopback

Wenn mehrere Gateways erreichbar sind, werden alle aufgelistet. Mehrere Gateways werden unterstützt, wenn du isolierte Profile/Ports verwendest (z. B. einen Rescue-Bot), aber die meisten Installationen führen nur ein Gateway aus.

openclaw gateway probe
openclaw gateway probe --json

Interpretation:

• Reachable: yes bedeutet, dass mindestens ein Ziel eine WebSocket-Verbindung akzeptiert hat.
• Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only berichtet, was die Prüfung über die Authentifizierung belegen konnte. Dies ist unabhängig von der Erreichbarkeit.
• Read probe: ok bedeutet, dass Detail-RPC-Aufrufe mit Lesezugriff (health/status/system-presence/config.get) ebenfalls erfolgreich waren.
• Read probe: limited - missing scope: operator.read bedeutet, dass die Verbindung erfolgreich war, aber der Lese-RPC eingeschränkt ist. Dies wird als degradierte Erreichbarkeit gemeldet, nicht als vollständiger Ausfall.

JSON-Hinweise (--json):

• Top-Level:
  • ok: mindestens ein Ziel ist erreichbar.
  • degraded: mindestens ein Ziel hatte einen Detail-RPC mit eingeschränktem Umfang.
  • capability: beste Fähigkeit, die über erreichbare Ziele hinweg gesehen wurde (read_only, write_capable, admin_capable, pairing_pending, connected_no_operator_scope oder unknown).
  • primaryTargetId: bestes Ziel, das als aktiver Gewinner behandelt wird, in dieser Reihenfolge: explizite URL, SSH-Tunnel, konfiguriertes Remote-Ziel, dann lokaler Loopback.
  • warnings[]: Warnungsdatensätze mit code, message und optionalen targetIds.
  • network: Hinweise auf lokale Loopback/Tailnet-URLs, abgeleitet aus der aktuellen Konfiguration und dem Host-Netzwerk.
  • discovery.timeoutMs und discovery.count: das tatsächliche Discovery-Budget/Ergebnisanzahl für diesen Prüfdurchlauf.
• Pro Ziel (targets[].connect):
  • ok: Erreichbarkeit nach Verbindung + degradierte Klassifizierung.
  • rpcOk: vollständiger Detail-RPC-Erfolg.
  • scopeLimited: Detail-RPC fehlgeschlagen aufgrund fehlenden Operator-Scopes.
• Pro Ziel (targets[].auth):
  • role: Auth-Rolle, die in hello-ok gemeldet wurde (falls verfügbar).
  • scopes: gewährte Scopes, die in hello-ok gemeldet wurden (falls verfügbar).
  • capability: die ermittelte Auth-Fähigkeitsklassifizierung für dieses Ziel.

Häufige Warncodes:

• ssh_tunnel_failed: SSH-Tunnel-Einrichtung fehlgeschlagen; der Befehl ist auf direkte Prüfungen zurückgefallen.
• multiple_gateways: mehr als ein Ziel war erreichbar; dies ist ungewöhnlich, es sei denn, du betreibst absichtlich isolierte Profile, wie z. B. einen Rescue-Bot.
• auth_secretref_unresolved: eine konfigurierte Auth-SecretRef konnte für ein fehlgeschlagenes Ziel nicht aufgelöst werden.
• probe_scope_limited: WebSocket-Verbindung war erfolgreich, aber die Lese-Prüfung war durch fehlendes operator.read eingeschränkt.

Remote über SSH (Mac App Parität)

Der “Remote über SSH”-Modus der macOS-App verwendet eine lokale Port-Weiterleitung, sodass das Remote-Gateway (das möglicherweise nur an Loopback gebunden ist) unter ws://127.0.0.1:<port> erreichbar wird.

CLI-Äquivalent:

openclaw gateway probe --ssh user@gateway-host

Optionen:

• --ssh <target>: user@host oder user@host:port (Port standardmäßig 22).
• --ssh-identity <path>: Identitätsdatei.
• --ssh-auto: wählt den ersten entdeckten Gateway-Host als SSH-Ziel aus dem aufgelösten Discovery-Endpunkt (local. plus die konfigurierte Wide-Area-Domain, falls vorhanden). TXT-only Hinweise werden ignoriert.

Konfiguration (optional, wird als Standard verwendet):

• gateway.remote.sshTarget
• gateway.remote.sshIdentity

gateway call <method>

Low-Level RPC-Helfer.

openclaw gateway call status
openclaw gateway call logs.tail --params '{"sinceMs": 60000}'

Optionen:

• --params <json>: JSON-Objekt-String für Parameter (Standard {})
• --url <url>
• --token <token>
• --password <password>
• --timeout <ms>
• --expect-final
• --json

Hinweise:

• --params muss gültiges JSON sein.
• --expect-final ist hauptsächlich für RPCs im Agenten-Stil gedacht, die Zwischenereignisse streamen, bevor ein finales Payload gesendet wird.

AI Setup Assistant

Gateway-Dienst verwalten

Du kannst den Gateway-Dienst direkt über die CLI steuern, um den Lebenszyklus deiner Instanz effizient zu verwalten. Nutze dazu die folgenden Befehle, um den Dienst auf deinem System zu konfigurieren und auszuführen:

openclaw gateway install
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway uninstall

Gateway-Befehlsoptionen

Für die verschiedenen Gateway-Befehle stehen dir spezifische Optionen zur Verfügung, mit denen du das Verhalten der API und des Dienstes präzise steuern kannst. Hier ist eine Übersicht der verfügbaren Flags für die jeweiligen Aktionen:

• gateway status: --url, --token, --password, --timeout, --no-probe, --require-rpc, --deep, --json
• gateway install: --port, --runtime <node|bun>, --token, --force, --json
• gateway uninstall|start|stop|restart: --json

Hinweise zur Konfiguration

Wenn du OpenClaw einrichtest, solltest du die folgenden technischen Details beachten, um eine sichere und stabile Umgebung zu gewährleisten. Diese Punkte helfen dir dabei, den Gateway korrekt zu konfigurieren und Fehler bei der Bereitstellung zu vermeiden:

1. Der Befehl gateway install unterstützt die Optionen --port, --runtime, --token, --force und --json.
2. Wenn die Token-Authentifizierung einen Token erfordert und gateway.auth.token über SecretRef verwaltet wird, validiert gateway install, ob der SecretRef auflösbar ist. Der aufgelöste Token wird jedoch nicht dauerhaft in den Metadaten der Dienstumgebung gespeichert.
3. Falls die Token-Authentifizierung einen Token benötigt und der konfigurierte SecretRef nicht aufgelöst werden kann, schlägt die Installation fehl, anstatt ein unsicheres Fallback im Klartext zu speichern.
4. Für die Passwort-Authentifizierung bei gateway run solltest du bevorzugt OPENCLAW_GATEWAY_PASSWORD, --password-file oder einen SecretRef-basierten gateway.auth.password-Eintrag verwenden, anstatt das Passwort direkt als --password einzugeben.
5. Im abgeleiteten Authentifizierungsmodus lockert ein reines Shell-OPENCLAW_GATEWAY_PASSWORD die Token-Anforderungen für die Installation nicht auf; verwende stattdessen eine dauerhafte Konfiguration (gateway.auth.password oder Konfigurations-env), wenn du einen verwalteten Dienst installierst.
6. Wenn sowohl gateway.auth.token als auch gateway.auth.password konfiguriert sind, aber gateway.auth.mode nicht gesetzt ist, wird die Installation blockiert, bis der Modus explizit definiert wurde.
7. Alle Lebenszyklus-Befehle akzeptieren das --json-Flag, um die Automatisierung mittels Skripten zu erleichtern.

Gateways entdecken (Bonjour)

Der Befehl gateway discover sucht aktiv nach Gateway-Beacons, die über das Protokoll _openclaw-gw._tcp ausgesendet werden.

1. Multicast DNS-SD: local.
2. Unicast DNS-SD (Wide-Area Bonjour): Wähle eine Domain (zum Beispiel openclaw.internal.) und richte Split DNS sowie einen DNS-Server ein; weitere Details findest du unter /gateway/bonjour.

Nur Gateways, bei denen die Bonjour-Erkennung aktiviert ist (Standardeinstellung), senden den Beacon aus.

Die Datensätze für die Wide-Area-Erkennung enthalten folgende Informationen (TXT):

• role (Hinweis auf die Gateway-Rolle)
• transport (Hinweis auf den Transportweg, z. B. gateway)
• gatewayPort (WebSocket-Port, normalerweise 18789)
• sshPort (optional; Clients verwenden standardmäßig 22, wenn dieser Wert fehlt)
• tailnetDns (MagicDNS-Hostname, sofern verfügbar)
• gatewayTls / gatewayTlsSha256 (TLS aktiviert + Zertifikats-Fingerprint)
• cliPath (Hinweis für die Remote-Installation, der in die Wide-Area-Zone geschrieben wird)

gateway discover verwenden

Mit diesem Befehl kannst du OpenClaw Gateways in deinem Netzwerk finden und ihre Konfigurationsdetails abrufen.

openclaw gateway discover

Optionen:

• --timeout <ms>: Timeout pro Befehl (Suche/Auflösung); Standardwert ist 2000.
• --json: Ausgabe im maschinenlesbaren Format (deaktiviert zudem Styling und Spinner).

Beispiele:

openclaw gateway discover --timeout 4000
openclaw gateway discover --json | jq '.beacons[].wsUrl'

Hinweise:

• Das CLI scannt sowohl local. als auch die konfigurierte Wide-Area-Domain, sofern eine solche aktiviert ist.
• Die wsUrl in der JSON-Ausgabe wird vom aufgelösten Service-Endpunkt abgeleitet und nicht aus reinen TXT-Hinweisen wie lanHost oder tailnetDns.
• Bei local. mDNS werden sshPort und cliPath nur übertragen, wenn discovery.mdns.mode auf full gesetzt ist. Wide-Area DNS-SD schreibt weiterhin cliPath; sshPort bleibt auch dort optional.