Gateway

• Standardmäßig verweigert der Gateway den Start, sofern gateway.mode=local nicht in ~/.openclaw/openclaw.json festgelegt ist. Verwenden Sie --allow-unconfigured für Ad-hoc-/Dev-Ausführungen.
• openclaw onboard --mode local und openclaw setup sollen gateway.mode=local schreiben. Wenn die Datei existiert, aber gateway.mode fehlt, behandeln Sie dies als beschädigte oder überschriebene Konfiguration und reparieren Sie sie, statt den lokalen Modus implizit anzunehmen.
• Wenn die Datei existiert und gateway.mode fehlt, behandelt der Gateway dies als verdächtigen Konfigurationsschaden und verweigert es, für Sie „local zu erraten“.
• Binden über Loopback hinaus ohne Authentifizierung wird blockiert (Sicherheitsleitplanke).
• SIGUSR1 löst einen In-Process-Neustart aus, wenn dies autorisiert ist (commands.restart ist standardmäßig aktiviert; setzen Sie commands.restart: false, um manuelle Neustarts zu blockieren, während Anwenden/Aktualisieren per Gateway-Tool/Konfiguration weiterhin erlaubt bleibt).
• SIGINT-/SIGTERM-Handler stoppen den Gateway-Prozess, stellen aber keinen benutzerdefinierten Terminalzustand wieder her. Wenn Sie die CLI mit einer TUI oder Raw-Mode-Eingabe umschließen, stellen Sie das Terminal vor dem Beenden wieder her.

• Datensätze behalten operative Metadaten: Ereignisnamen, Zählwerte, Bytegrößen, Speicherwerte, Warteschlangen-/Sitzungszustand, Kanal-/Plugin-Namen und redigierte Sitzungszusammenfassungen. Sie behalten keinen Chattext, keine Webhook-Bodys, keine Tool-Ausgaben, keine rohen Anfrage- oder Antwortbodys, Tokens, Cookies, geheimen Werte, Hostnamen oder rohen Sitzungs-IDs. Setzen Sie diagnostics.enabled: false, um den Recorder vollständig zu deaktivieren.
• Bei fatalen Gateway-Beendigungen, Shutdown-Timeouts und Startfehlern nach Neustarts schreibt OpenClaw denselben Diagnose-Snapshot nach ~/.openclaw/logs/stability/openclaw-stability-*.json, wenn der Recorder Ereignisse hat. Prüfen Sie das neueste Bundle mit openclaw gateway stability --bundle latest; --limit, --type und --since-seq gelten ebenfalls für Bundle-Ausgaben.

• gateway status bleibt für Diagnosen verfügbar, selbst wenn die lokale CLI-Konfiguration fehlt oder ungültig ist.
• Das standardmäßige gateway status weist den Service-Zustand, die WebSocket-Verbindung und die zum Handshake-Zeitpunkt sichtbare Authentifizierungsfähigkeit nach. Es weist keine Lese-/Schreib-/Admin-Operationen nach.
• Diagnoseprüfungen verändern bei der erstmaligen Geräteauthentifizierung nichts: Sie verwenden ein vorhandenes zwischengespeichertes Geräte-Token wieder, falls eines vorhanden ist, erstellen aber keine neue CLI-Geräteidentität oder schreibgeschützten Gerätekopplungsdatensatz nur zur Statusprüfung.
• gateway status löst konfigurierte Authentifizierungs-SecretRefs für die Prüf-Authentifizierung auf, wenn möglich.
• Wenn ein erforderlicher Authentifizierungs-SecretRef in diesem Befehlspfad nicht aufgelöst wird, meldet gateway status --json rpc.authWarning, wenn Prüfkonnektivität/Authentifizierung fehlschlägt; übergeben Sie --token/--password explizit oder lösen Sie zuerst die Secret-Quelle auf.
• Wenn die Prüfung erfolgreich ist, werden Warnungen zu nicht aufgelösten Authentifizierungsreferenzen unterdrückt, um falsch positive Meldungen zu vermeiden.
• Verwenden Sie --require-rpc in Skripten und Automatisierung, wenn ein lauschender Service nicht ausreicht und auch RPC-Aufrufe mit Leseumfang fehlerfrei sein müssen.
• --deep fügt einen Best-Effort-Scan nach zusätzlichen launchd-/systemd-/schtasks-Installationen hinzu. Wenn mehrere Gateway-ähnliche Services erkannt werden, gibt die Ausgabe für Menschen Bereinigungshinweise aus und warnt, dass die meisten Setups ein Gateway pro Maschine ausführen sollten.
• --deep meldet außerdem eine kürzliche Übergabe eines Gateway-Supervisor-Neustarts, wenn der Service-Prozess für einen externen Supervisor-Neustart sauber beendet wurde.
• --deep führt die Konfigurationsvalidierung im Plugin-fähigen Modus (pluginValidation: "full") aus und zeigt konfigurierte Plugin-Manifestwarnungen an (zum Beispiel fehlende Metadaten zur Kanalkonfiguration), damit Installations- und Update-Smoke-Checks sie erkennen. Das standardmäßige gateway status behält den schnellen schreibgeschützten Pfad bei, der die Plugin-Validierung überspringt.
• Die Ausgabe für Menschen enthält den aufgelösten Dateilogpfad sowie eine Momentaufnahme der CLI-gegenüber-Service-Konfigurationspfade/-Gültigkeit, um Profil- oder Zustandsverzeichnisdrift zu diagnostizieren.

• Bei Linux-systemd-Installationen lesen Prüfungen auf Service-Authentifizierungsdrift sowohl Environment=- als auch EnvironmentFile=-Werte aus der Unit (einschließlich %h, zitierter Pfade, mehrerer Dateien und optionaler --Dateien).
• Driftprüfungen lösen gateway.auth.token-SecretRefs mit der zusammengeführten Laufzeitumgebung auf (zuerst Service-Befehlsumgebung, dann Prozessumgebung als Fallback).
• Wenn Token-Authentifizierung nicht effektiv aktiv ist (expliziter gateway.auth.mode von password/none/trusted-proxy oder nicht gesetzter Modus, bei dem das Passwort gewinnen kann und kein Token-Kandidat gewinnen kann), überspringen Token-Driftprüfungen die Auflösung des Konfigurationstokens.

• Reachable: yes bedeutet, dass mindestens ein Ziel eine WebSocket-Verbindung akzeptiert hat.
• Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only meldet, was die Prüfung über die Authentifizierung nachweisen konnte. Dies ist von der Erreichbarkeit getrennt.
• Read probe: ok bedeutet, dass auch Detail-RPC-Aufrufe mit Leseumfang (health/status/system-presence/config.get) erfolgreich waren.
• Read probe: limited - missing scope: operator.read bedeutet, dass die Verbindung erfolgreich war, RPC mit Leseumfang aber eingeschränkt ist. Dies wird als eingeschränkte Erreichbarkeit gemeldet, nicht als vollständiger Fehler.
• Read probe: failed nach Connect: ok bedeutet, dass das Gateway die WebSocket-Verbindung akzeptiert hat, nachfolgende Lesediagnosen aber wegen Zeitüberschreitung oder Fehlern scheiterten. Auch dies ist eingeschränkte Erreichbarkeit, kein unerreichbares Gateway.
• Wie gateway status verwendet probe vorhandene zwischengespeicherte Geräteauthentifizierung wieder, erstellt aber keine erstmalige Geräteidentität oder keinen Kopplungszustand.
• Der Exit-Code ist nur dann ungleich null, wenn kein geprüftes Ziel erreichbar ist.

Oberste Ebene:

• ok: Mindestens ein Ziel ist erreichbar.
• degraded: Mindestens ein Ziel hat eine Verbindung akzeptiert, aber die vollständige Detail-RPC-Diagnose nicht abgeschlossen.
• 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 in dieser Reihenfolge als aktiver Gewinner behandelt werden soll: explizite URL, SSH-Tunnel, konfiguriertes Remote-Ziel, dann local loopback.
• warnings[]: Best-Effort-Warndatensätze mit code, message und optionalen targetIds.
• network: Hinweise auf local loopback-/Tailnet-URLs, abgeleitet aus aktueller Konfiguration und Host-Netzwerk.
• discovery.timeoutMs und discovery.count: Das tatsächlich für diesen Prüfdurchlauf verwendete Discovery-Budget bzw. die Ergebnisanzahl.

Pro Ziel (targets[].connect):

• ok: Erreichbarkeit nach Verbindung + Einstufung als eingeschränkt.
• rpcOk: Vollständiger Detail-RPC-Erfolg.
• scopeLimited: Detail-RPC ist wegen fehlendem Operator-Umfang fehlgeschlagen.

Pro Ziel (targets[].auth):

• role: In hello-ok gemeldete Authentifizierungsrolle, wenn verfügbar.
• scopes: In hello-ok gemeldete gewährte Umfänge, wenn verfügbar.
• capability: Die angezeigte Klassifizierung der Authentifizierungsfähigkeit für dieses Ziel.

• ssh_tunnel_failed: Einrichtung des SSH-Tunnels fehlgeschlagen; der Befehl ist auf direkte Prüfungen zurückgefallen.
• multiple_gateways: Mehr als ein Ziel war erreichbar; dies ist ungewöhnlich, sofern Sie nicht absichtlich isolierte Profile ausführen, etwa einen Rettungs-Bot.
• auth_secretref_unresolved: Ein konfigurierter Authentifizierungs-SecretRef konnte für ein fehlgeschlagenes Ziel nicht aufgelöst werden.
• probe_scope_limited: WebSocket-Verbindung erfolgreich, aber die Leseprüfung wurde durch fehlendes operator.read eingeschränkt.

• gateway status: --url, --token, --password, --timeout, --no-probe, --require-rpc, --deep, --json
• gateway install: --port, --runtime <node|bun>, --token, --wrapper <path>, --force, --json
• gateway restart: --safe, --skip-deferral, --force, --wait <duration>, --json
• gateway uninstall|start: --json
• gateway stop: --disable, --json

• Verwenden Sie gateway restart, um einen verwalteten Dienst neu zu starten. Verketten Sie gateway stop und gateway start nicht als Ersatz für einen Neustart.
• Unter macOS verwendet gateway stop standardmäßig launchctl bootout, wodurch der LaunchAgent aus der aktuellen Boot-Sitzung entfernt wird, ohne eine Deaktivierung dauerhaft zu speichern — die automatische KeepAlive-Wiederherstellung bleibt für zukünftige Abstürze aktiv und gateway start aktiviert sauber erneut, ohne ein manuelles launchctl enable. Übergeben Sie --disable, um KeepAlive und RunAtLoad dauerhaft zu unterdrücken, damit der Gateway bis zum nächsten expliziten gateway start nicht neu startet; verwenden Sie dies, wenn ein manueller Stopp Neustarts oder Systemneustarts überdauern soll.
• gateway restart --safe weist den laufenden Gateway an, aktive OpenClaw-Arbeit vorab zu prüfen und den Neustart aufzuschieben, bis Antwortzustellung, eingebettete Runs und Task-Runs abgearbeitet sind. --safe kann nicht mit --force oder --wait kombiniert werden.
• gateway restart --wait 30s überschreibt das konfigurierte Drain-Budget für diesen Neustart. Zahlen ohne Einheit sind Millisekunden; Einheiten wie s, m und h werden akzeptiert. --wait 0 wartet unbegrenzt.
• gateway restart --safe --skip-deferral führt den OpenClaw-bewussten sicheren Neustart aus, umgeht aber das Aufschub-Gate, sodass der Gateway den Neustart sofort auslöst, auch wenn Blocker gemeldet werden. Operator-Notausstieg für Aufschübe durch hängende Task-Runs; erfordert --safe.
• gateway restart --force überspringt das Drain aktiver Arbeit und startet sofort neu. Verwenden Sie dies, wenn ein Operator die aufgeführten Task-Blocker bereits geprüft hat und den Gateway jetzt zurückhaben möchte.
• Lifecycle-Befehle akzeptieren --json für Skripting.

• Wenn Token-Authentifizierung ein Token erfordert und gateway.auth.token von SecretRef verwaltet wird, validiert gateway install, dass die SecretRef auflösbar ist, speichert das aufgelöste Token jedoch nicht dauerhaft in Dienstumgebungs-Metadaten.
• Wenn Token-Authentifizierung ein Token erfordert und die konfigurierte Token-SecretRef nicht aufgelöst ist, schlägt die Installation geschlossen fehl, statt Fallback-Klartext dauerhaft zu speichern.
• Für Passwortauthentifizierung bei gateway run bevorzugen Sie OPENCLAW_GATEWAY_PASSWORD, --password-file oder ein SecretRef-gestütztes gateway.auth.password gegenüber inline --password.
• Im abgeleiteten Authentifizierungsmodus lockert ein nur in der Shell gesetztes OPENCLAW_GATEWAY_PASSWORD die Token-Anforderungen für die Installation nicht; verwenden Sie dauerhafte Konfiguration (gateway.auth.password oder Konfiguration env), wenn Sie einen verwalteten Dienst installieren.
• 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 ist.