Gateway

• Standardmäßig verweigert der Gateway den Start, sofern gateway.mode=local nicht in ~/.openclaw/openclaw.json gesetzt ist. Verwenden Sie --allow-unconfigured für Ad-hoc-/Entwicklungsläufe.
• Von openclaw onboard --mode local und openclaw setup wird erwartet, dass sie gateway.mode=local schreiben. Wenn die Datei vorhanden ist, aber gateway.mode fehlt, behandeln Sie dies als beschädigte oder überschrieben konfigurierte Datei und reparieren Sie sie, statt implizit den lokalen Modus anzunehmen.
• Wenn die Datei vorhanden ist und gateway.mode fehlt, behandelt der Gateway dies als verdächtige Konfigurationsbeschädigung und verweigert es, für Sie „lokal zu raten“.
• Das Binden über loopback hinaus ohne Authentifizierung wird blockiert (Sicherheitsleitplanke).
• SIGUSR1 löst einen prozessinternen Neustart aus, wenn autorisiert (commands.restart ist standardmäßig aktiviert; setzen Sie commands.restart: false, um manuelle Neustarts zu blockieren, während das Anwenden/Aktualisieren von Gateway-Tools und -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 Betriebsmetadaten: Ereignisnamen, Zählungen, Bytegrößen, Speichermesswerte, Warteschlangen-/Sitzungsstatus, Kanal-/Plugin-Namen und geschwärzte Sitzungszusammenfassungen. Sie behalten keine Chattexte, Webhook-Bodys, Tool-Ausgaben, rohe Anfrage- oder Antwort-Bodys, Tokens, Cookies, geheime Werte, Hostnamen oder rohen Sitzungs-IDs. Setzen Sie diagnostics.enabled: false, um den Rekorder vollständig zu deaktivieren.
• Bei fatalen Gateway-Beendigungen, Shutdown-Timeouts und Startfehlern nach einem Neustart schreibt OpenClaw denselben Diagnose-Snapshot nach ~/.openclaw/logs/stability/openclaw-stability-*.json, wenn der Rekorder Ereignisse enthält. Prüfen Sie das neueste Bundle mit openclaw gateway stability --bundle latest; --limit, --type und --since-seq gelten auch für Bundle-Ausgaben.

• gateway status bleibt für Diagnosen verfügbar, auch wenn die lokale CLI-Konfiguration fehlt oder ungültig ist.
• Der standardmäßige gateway status weist Service-Status, WebSocket-Verbindung und die beim Handshake sichtbare Authentifizierungs-Capability nach. Lese-/Schreib-/Admin-Operationen werden damit nicht nachgewiesen.
• Diagnose-Probes verändern bei der erstmaligen Geräteauthentifizierung nichts: Sie verwenden ein vorhandenes zwischengespeichertes Geräte-Token erneut, falls eines existiert, erstellen aber keine neue CLI-Geräteidentität und keinen schreibgeschützten Geräte-Pairing-Datensatz, nur um den Status zu prüfen.
• gateway status löst konfigurierte Authentifizierungs-SecretRefs nach Möglichkeit für die Probe-Authentifizierung auf.
• Wenn ein erforderliches Authentifizierungs-SecretRef in diesem Befehlspfad nicht aufgelöst wird, meldet gateway status --json rpc.authWarning, wenn Probe-Konnektivität/-Authentifizierung fehlschlägt; übergeben Sie --token/--password explizit oder lösen Sie zuerst die Secret-Quelle auf.
• Wenn die Probe 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 Lese-Scope fehlerfrei funktionieren 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 menschenlesbare Ausgabe Bereinigungshinweise aus und warnt, dass die meisten Setups ein Gateway pro Maschine ausführen sollten.
• --deep meldet auch eine aktuelle Übergabe für einen Neustart des Gateway-Supervisors, wenn der Service-Prozess für einen Neustart durch einen externen Supervisor sauber beendet wurde.
• Die menschenlesbare Ausgabe enthält den aufgelösten Dateilogpfad sowie eine Momentaufnahme der CLI- und Service-Konfigurationspfade/-Gültigkeit, um Abweichungen bei Profilen oder Statusverzeichnissen zu diagnostizieren.

• Bei Linux-systemd-Installationen lesen Prüfungen auf Service-Authentifizierungsdrift sowohl Environment=- als auch EnvironmentFile=-Werte aus der Unit (einschließlich %h, Pfaden in Anführungszeichen, mehreren Dateien und optionalen --Dateien).
• Drift-Prüfungen lösen gateway.auth.token-SecretRefs mithilfe 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-Drift-Prüfungen die Auflösung des Konfigurationstokens.

• Reachable: yes bedeutet, dass mindestens ein Ziel eine WebSocket-Verbindung angenommen hat.
• Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only meldet, was die Probe über die Authentifizierung nachweisen konnte. Dies ist von der Erreichbarkeit getrennt.
• Read probe: ok bedeutet, dass Detail-RPC-Aufrufe mit Lese-Scope (health/status/system-presence/config.get) ebenfalls erfolgreich waren.
• Read probe: limited - missing scope: operator.read bedeutet, dass die Verbindung erfolgreich war, der RPC mit Lese-Scope 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 angenommen hat, die anschließenden Lesediagnosen aber ein Timeout erreicht haben oder fehlgeschlagen sind. Auch dies ist eingeschränkte Erreichbarkeit, kein unerreichbares Gateway.
• Wie gateway status verwendet die Probe vorhandene zwischengespeicherte Geräteauthentifizierung erneut, erstellt aber keine erstmalige Geräteidentität oder keinen Pairing-Status.
• 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 angenommen, aber keine vollständige Detail-RPC-Diagnose abgeschlossen.
• capability: Beste Capability, 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, konfigurierte Remote-Instanz, dann local loopback.
• warnings[]: Best-Effort-Warnungsdatensä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 verwendete Discovery-Budget und die Ergebnisanzahl für diesen Probe-Durchlauf.

Pro Ziel (targets[].connect):

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

Pro Ziel (targets[].auth):

• role: Authentifizierungsrolle, die in hello-ok gemeldet wurde, sofern verfügbar.
• scopes: Gewährte Scopes, die in hello-ok gemeldet wurden, sofern verfügbar.
• capability: Die offengelegte Authentifizierungs-Capability-Klassifizierung für dieses Ziel.

• ssh_tunnel_failed: SSH-Tunnel-Einrichtung ist fehlgeschlagen; der Befehl ist auf direkte Probes zurückgefallen.
• multiple_gateways: Mehr als ein Ziel war erreichbar; dies ist ungewöhnlich, sofern Sie nicht absichtlich isolierte Profile ausführen, etwa einen Rettungsbot.
• auth_secretref_unresolved: Ein konfiguriertes Authentifizierungs-SecretRef konnte für ein fehlgeschlagenes Ziel nicht aufgelöst werden.
• probe_scope_limited: WebSocket-Verbindung war erfolgreich, aber die Lese-Probe 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, --force, --wait <duration>, --json
• gateway uninstall|start|stop: --json

• Verwenden Sie gateway restart, um einen verwalteten Service neu zu starten. Verketten Sie gateway stop und gateway start nicht als Ersatz für einen Neustart; unter macOS deaktiviert gateway stop den LaunchAgent absichtlich, bevor er gestoppt wird.
• gateway restart --safe fordert das laufende Gateway auf, aktive OpenClaw-Arbeit vorab zu prüfen und den Neustart aufzuschieben, bis Antwortzustellung, eingebettete Ausführungen und Task-Ausführungen abgearbeitet sind. --safe kann nicht mit --force oder --wait kombiniert werden.
• gateway restart --wait 30s überschreibt das konfigurierte Drain-Budget für den Neustart für diesen Neustart. Reine Zahlen sind Millisekunden; Einheiten wie s, m und h werden akzeptiert. --wait 0 wartet unbegrenzt.
• gateway restart --force überspringt das Leerlaufen aktiver Arbeit und startet sofort neu. Verwenden Sie dies, wenn ein Operator die aufgeführten Task-Blocker bereits geprüft hat und das Gateway jetzt wieder verfügbar haben möchte.
• Lebenszyklusbefehle akzeptieren --json für Skripting.

• Wenn die Token-Authentifizierung einen Token erfordert und gateway.auth.token über SecretRef verwaltet wird, validiert gateway install, dass die SecretRef auflösbar ist, speichert den aufgelösten Token aber nicht in den Service-Umgebungsmetadaten.
• Wenn die Token-Authentifizierung einen Token erfordert und die konfigurierte Token-SecretRef nicht aufgelöst ist, schlägt die Installation geschlossen fehl, statt Fallback-Klartext zu speichern.
• Verwenden Sie für die Passwortauthentifizierung bei gateway run bevorzugt OPENCLAW_GATEWAY_PASSWORD, --password-file oder ein SecretRef-gestütztes gateway.auth.password statt eines inline angegebenen --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 Konfigurations-env), wenn Sie einen verwalteten Service 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 wird.