Gateway CLI

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

Die Unterbefehle auf dieser Seite befinden sich unter openclaw gateway ....

Verwandte Docs:

Gateway starten

Einen lokalen Gateway-Prozess starten:

openclaw gateway

Vordergrund-Alias:

openclaw gateway run

Hinweise:

  • Standardm\u00e4\u00dfig verweigert das Gateway den Start, wenn gateway.mode=local nicht in ~/.openclaw/openclaw.json gesetzt ist. Verwende --allow-unconfigured f\u00fcr Ad-hoc/Dev-L\u00e4ufe.
  • Binding \u00fcber Loopback hinaus ohne Auth wird blockiert (Sicherheitsschutz).
  • SIGUSR1 l\u00f6st einen In-Process-Neustart aus, wenn autorisiert (commands.restart ist standardm\u00e4\u00dfig aktiviert; setze commands.restart: false, um manuellen Neustart zu blockieren, w\u00e4hrend Gateway-Tool/Config-Apply/Update weiterhin erlaubt bleiben).
  • SIGINT/SIGTERM-Handler stoppen den Gateway-Prozess, stellen aber keinen benutzerdefinierten Terminal-State wieder her. Wenn du die CLI mit einer TUI oder Raw-Mode-Eingabe umh\u00fcllst, stelle das Terminal vor dem Beenden wieder her.

Optionen

  • --port <port>: WebSocket-Port (Standard kommt aus Config/Env; normalerweise 18789).
  • --bind <loopback|lan|tailnet|auto|custom>: Listener-Bind-Modus.
  • --auth <token|password>: Auth-Modus-\u00dcberschreibung.
  • --token <token>: Token-\u00dcberschreibung (setzt auch OPENCLAW_GATEWAY_TOKEN f\u00fcr den Prozess).
  • --password <password>: Passwort-\u00dcberschreibung. Warnung: Inline-Passw\u00f6rter k\u00f6nnen in lokalen Prozesslisten sichtbar sein.
  • --password-file <path>: Gateway-Passwort aus einer Datei lesen.
  • --tailscale <off|serve|funnel>: Gateway \u00fcber Tailscale bereitstellen.
  • --tailscale-reset-on-exit: Tailscale-Serve/Funnel-Config beim Herunterfahren zur\u00fccksetzen.
  • --allow-unconfigured: Gateway-Start ohne gateway.mode=local in der Config erlauben.
  • --dev: Dev-Config + Workspace erstellen, falls fehlend (BOOTSTRAP.md wird \u00fcbersprungen).
  • --reset: Dev-Config + Anmeldeinformationen + Sessions + Workspace zur\u00fccksetzen (erfordert --dev).
  • --force: Bestehenden Listener auf dem gew\u00e4hlten Port vor dem Start beenden.
  • --verbose: Ausf\u00fchrliche 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\u00fcr --ws-log compact.
  • --raw-stream: Rohe Model-Stream-Events in JSONL loggen.
  • --raw-stream-path <path>: Pfad f\u00fcr Raw-Stream-JSONL.

Ein laufendes Gateway abfragen

Alle Abfragebefehle verwenden WebSocket-RPC.

Ausgabemodi:

  • Standard: Menschenlesbar (farbig im TTY).
  • --json: Maschinenlesbares JSON (kein Styling/Spinner).
  • --no-color (oder NO_COLOR=1): ANSI deaktivieren, menschliches Layout beibehalten.

Gemeinsame Optionen (wo unterst\u00fctzt):

  • --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).

Hinweis: Wenn du --url setzt, f\u00e4llt die CLI nicht auf Config- oder Umgebungs-Anmeldeinformationen zur\u00fcck. \u00dcbergib --token oder --password explizit. Fehlende explizite Anmeldeinformationen sind ein Fehler.

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 \u00fcberschreiben.
  • --token <token>: Token-Auth f\u00fcr den Probe.
  • --password <password>: Passwort-Auth f\u00fcr den Probe.
  • --timeout <ms>: Probe-Timeout (Standard 10000).
  • --no-probe: RPC-Probe \u00fcberspringen (nur Service-Ansicht).
  • --deep: Auch System-Level-Services scannen.

Hinweise:

  • gateway status l\u00f6st konfigurierte Auth-SecretRefs f\u00fcr die Probe-Authentifizierung auf, wenn m\u00f6glich.
  • Wenn ein erforderlicher Auth-SecretRef in diesem Befehlspfad nicht aufgel\u00f6st ist, kann die Probe-Auth fehlschlagen; \u00fcbergib --token/--password explizit oder l\u00f6se zuerst die Secret-Quelle auf.
  • Bei Linux-systemd-Installationen lesen Status-Token-Drift-Checks sowohl Environment=- als auch EnvironmentFile=-Werte aus der Unit (einschlie\u00dflich %h, quotierte Pfade, mehrere Dateien und optionale --Dateien).

gateway probe

gateway probe ist der “alles debuggen”-Befehl. Er pr\u00fcft 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\u00fctzt, wenn du isolierte Profile/Ports verwendest (z.B. einen Rescue-Bot), aber die meisten Installationen betreiben ein einzelnes Gateway.

openclaw gateway probe
openclaw gateway probe --json

Remote \u00fcber SSH (Mac-App-Parit\u00e4t)

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

CLI-\u00c4quivalent:

openclaw gateway probe --ssh user@gateway-host

Optionen:

  • --ssh <target>: user@host oder user@host:port (Port-Standard ist 22).
  • --ssh-identity <path>: Identity-Datei.
  • --ssh-auto: Den ersten entdeckten Gateway-Host als SSH-Ziel verwenden (nur LAN/WAB).

Config (optional, als Standards 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\u00fctzt --port, --runtime, --token, --force, --json.
  • Wenn Token-Auth ein Token erfordert und gateway.auth.token SecretRef-verwaltet ist, validiert gateway install, dass der SecretRef aufl\u00f6sbar ist, persistiert aber nicht das aufgel\u00f6ste Token in Service-Environment-Metadaten.
  • Wenn Token-Auth ein Token erfordert und der konfigurierte Token-SecretRef nicht aufgel\u00f6st ist, schl\u00e4gt die Installation fehl, anstatt Fallback-Klartext zu persistieren.
  • F\u00fcr Passwort-Auth bei gateway run bevorzuge OPENCLAW_GATEWAY_PASSWORD, --password-file oder ein SecretRef-gest\u00fctztes gateway.auth.password gegen\u00fcber Inline---password.
  • Im abgeleiteten Auth-Modus lockert Shell-only OPENCLAW_GATEWAY_PASSWORD/CLAWDBOT_GATEWAY_PASSWORD die Install-Token-Anforderungen nicht; verwende dauerhafte Config (gateway.auth.password oder Config env) beim Installieren eines verwalteten Service.
  • Wenn sowohl gateway.auth.token als auch gateway.auth.password konfiguriert sind und gateway.auth.mode nicht gesetzt ist, wird die Installation blockiert, bis der Modus explizit gesetzt wird.
  • Lifecycle-Befehle akzeptieren --json f\u00fcr Scripting.

Gateways entdecken (Bonjour)

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

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

Nur Gateways mit aktiviertem Bonjour-Discovery (Standard) senden das Beacon.

Wide-Area-Discovery-Records enthalten (TXT):

  • role (Gateway-Rollen-Hint)
  • transport (Transport-Hint, z.B. gateway)
  • gatewayPort (WebSocket-Port, normalerweise 18789)
  • sshPort (SSH-Port; Standard 22, wenn nicht vorhanden)
  • tailnetDns (MagicDNS-Hostname, wenn verf\u00fcgbar)
  • gatewayTls / gatewayTlsSha256 (TLS aktiviert + Zertifikats-Fingerprint)
  • cliPath (optionaler Hint f\u00fcr Remote-Installationen)

gateway discover

openclaw gateway discover

Optionen:

  • --timeout <ms>: Per-Command-Timeout (Browse/Resolve); Standard 2000.
  • --json: Maschinenlesbare Ausgabe (deaktiviert auch Styling/Spinner).

Beispiele:

openclaw gateway discover --timeout 4000
openclaw gateway discover --json | jq '.beacons[].wsUrl'
arrow_back
Zurück
Doctor
Weiter
Health
arrow_forward