Gateway CLI

Das Gateway ist OpenClaws WebSocket-Server (Channels, Nodes, Sessions, Hooks).

Alle Unterbefehle auf dieser Seite gehören zu openclaw gateway ….

Verwandte Dokumentation:

Gateway starten

Starte einen lokalen Gateway-Prozess:

openclaw gateway

Im Vordergrund ausführen:

openclaw gateway run

Hinweise:

  • Standardmäßig startet das Gateway nur, wenn gateway.mode=local in ~/.openclaw/openclaw.json gesetzt ist. Für schnelle Tests nutze --allow-unconfigured.
  • Ohne Authentifizierung ist das Binden außerhalb von Loopback blockiert (Sicherheitsmaßnahme).
  • SIGUSR1 löst einen In-Process-Neustart aus, wenn autorisiert (aktiviere commands.restart oder nutze das Gateway-Tool/Config apply/update).
  • SIGINT/SIGTERM stoppen den Gateway-Prozess, stellen aber keinen benutzerdefinierten Terminal-Zustand wieder her. Wenn du die CLI mit einem TUI oder Raw-Mode-Input verwendest, stelle das Terminal vor dem Beenden wieder her.

Optionen

  • --port <port>: WebSocket-Port (Standard aus Config/Env; normalerweise 18789).
  • --bind <loopback|lan|tailnet|auto|custom>: Listener-Bind-Modus.
  • --auth <token|password>: Auth-Modus überschreiben.
  • --token <token>: Token überschreiben (setzt auch OPENCLAW_GATEWAY_TOKEN für den Prozess).
  • --password <password>: Passwort überschreiben (setzt auch OPENCLAW_GATEWAY_PASSWORD für den Prozess).
  • --tailscale <off|serve|funnel>: Gateway über Tailscale freigeben.
  • --tailscale-reset-on-exit: Tailscale serve/funnel Config beim Beenden zurücksetzen.
  • --allow-unconfigured: Gateway-Start ohne gateway.mode=local in der Config erlauben.
  • --dev: Dev-Config + Workspace erstellen, falls nicht vorhanden (überspringt BOOTSTRAP.md).
  • --reset: Dev-Config + Credentials + Sessions + Workspace zurücksetzen (erfordert --dev).
  • --force: Bestehenden Listener auf dem gewählten Port beenden, bevor gestartet wird.
  • --verbose: Ausführliche Logs.
  • --claude-cli-logs: Nur claude-cli Logs in der Konsole anzeigen (und dessen stdout/stderr aktivieren).
  • --ws-log <auto|full|compact>: WebSocket-Log-Stil (Standard auto).
  • --compact: Alias für --ws-log compact.
  • --raw-stream: Raw Model Stream Events als jsonl loggen.
  • --raw-stream-path <path>: Pfad für Raw Stream jsonl.

Laufendes Gateway abfragen

Alle Abfragebefehle nutzen WebSocket RPC.

Ausgabemodi:

  • Standard: Menschenlesbar (farbig im TTY).
  • --json: Maschinenlesbar als JSON (ohne Styling/Spinner).
  • --no-color (oder NO_COLOR=1): ANSI deaktivieren, aber menschenlesbares Layout beibehalten.

Gemeinsame Optionen (wo 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: Auf eine “finale” Antwort warten (Agent-Aufrufe).

gateway health

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

gateway status

gateway status zeigt den Gateway-Service (launchd/systemd/schtasks) plus einen optionalen RPC-Probe.

openclaw gateway status
openclaw gateway status --json

Optionen:

  • --url <url>: Probe-URL überschreiben.
  • --token <token>: Token-Auth für den Probe.
  • --password <password>: Passwort-Auth für den Probe.
  • --timeout <ms>: Probe-Timeout (Standard 10000).
  • --no-probe: RPC-Probe überspringen (nur Service-Ansicht).
  • --deep: Auch System-Level-Services scannen.

gateway probe

gateway probe ist der “alles debuggen”-Befehl. Er prüft immer:

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

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

openclaw gateway probe
openclaw gateway probe --json

Remote über SSH (Mac-App-Parität)

Der “Remote over SSH”-Modus der macOS-App nutzt einen lokalen Port-Forward, 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 ist standardmäßig 22).
  • --ssh-identity <path>: Identity-Datei.
  • --ssh-auto: Ersten entdeckten Gateway-Host als SSH-Ziel verwenden (nur LAN/WAB).

Config (optional, als Standardwerte 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}'

Gateway-Service verwalten

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

Hinweise:

  • gateway install unterstützt --port, --runtime, --token, --force, --json.
  • Lifecycle-Befehle akzeptieren --json für Scripting.

Gateways entdecken (Bonjour)

gateway discover sucht nach Gateway-Beacons (_openclaw-gw._tcp).

  • Multicast DNS-SD: local.
  • Unicast DNS-SD (Wide-Area Bonjour): Wähle eine Domain (Beispiel: openclaw.internal.) und richte Split-DNS + einen DNS-Server ein; siehe /gateway/bonjour

Nur Gateways mit aktivierter Bonjour-Discovery (Standard) senden den Beacon.

Wide-Area Discovery Records enthalten (TXT):

  • role (Gateway-Rollen-Hinweis)
  • transport (Transport-Hinweis, z.B. gateway)
  • gatewayPort (WebSocket-Port, normalerweise 18789)
  • sshPort (SSH-Port; Standard 22 wenn nicht angegeben)
  • tailnetDns (MagicDNS-Hostname, wenn verfügbar)
  • gatewayTls / gatewayTlsSha256 (TLS aktiviert + Zertifikat-Fingerprint)
  • cliPath (optionaler Hinweis für Remote-Installationen)

gateway discover

openclaw gateway discover

Optionen:

  • --timeout <ms>: Timeout pro Befehl (browse/resolve); Standard 2000.
  • --json: Maschinenlesbare Ausgabe (deaktiviert auch Styling/Spinner).

Beispiele:

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