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 existiert, aber gateway.mode fehlt, behandeln Sie dies als beschädigte oder überschriebene Konfiguration und reparieren Sie sie, statt implizit den lokalen Modus anzunehmen.
• Wenn die Datei existiert und gateway.mode fehlt, behandelt der Gateway dies als verdächtige Konfigurationsbeschädigung und verweigert es, für Sie „lokal zu raten“.
• Binden über Loopback hinaus ohne Authentifizierung wird blockiert (Sicherheitsleitplanke).
• lan, tailnet und custom werden derzeit über reine IPv4-BYOH-Pfade aufgelöst.
• Reines IPv6-BYOH wird auf diesem Pfad heute nicht nativ unterstützt. Verwenden Sie einen IPv4-Sidecar oder -Proxy, wenn der Host selbst nur IPv6 unterstützt.
• SIGUSR1 löst bei Autorisierung einen prozessinternen Neustart aus (commands.restart ist standardmäßig aktiviert; setzen Sie commands.restart: false, um manuelle Neustarts zu blockieren, während Anwenden/Aktualisieren von 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.

• Aufzeichnungen behalten operative Metadaten: Ereignisnamen, Zählwerte, Byte-Größen, Speichermesswerte, Queue-/Sitzungsstatus, Genehmigungs-IDs, Kanal-/Plugin-Namen und geschwärzte Sitzungszusammenfassungen. Sie behalten keine Chattexte, Webhook-Bodies, Tool-Ausgaben, rohen Request- oder Response-Bodies, Tokens, Cookies, Geheimwerte, Hostnamen oder rohen Sitzungs-IDs. Setzen Sie diagnostics.enabled: false, um den Recorder vollständig zu deaktivieren.
• Bei fatalen Gateway-Beendigungen, Shutdown-Timeouts und Neustart-Startfehlern 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-Config fehlt oder ungültig ist.
• Das standardmäßige gateway status weist Dienststatus, WebSocket-Verbindung und die zum Handshake-Zeitpunkt sichtbare Auth-Fähigkeit nach. Es weist keine Lese-/Schreib-/Admin-Operationen nach.
• Diagnoseprüfungen verändern bei erstmaliger Geräte-Auth nichts: Sie verwenden ein vorhandenes gecachtes Geräte-Token wieder, wenn eines existiert, erstellen aber keine neue CLI-Geräteidentität und keinen schreibgeschützten Geräte-Pairing-Eintrag nur zur Statusprüfung.
• gateway status löst konfigurierte Auth-SecretRefs für Prüf-Auth auf, wenn möglich.
• Wenn ein erforderlicher Auth-SecretRef in diesem Befehlspfad nicht aufgelöst ist, meldet gateway status --json rpc.authWarning, wenn Prüf-Konnektivität/Auth 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 Auth-Refs unterdrückt, um Fehlalarme zu vermeiden.
• Wenn Prüfungen aktiviert sind, enthält die JSON-Ausgabe gateway.version, wenn der laufende Gateway sie meldet; --require-rpc kann auf den RPC-Payload status.runtimeVersion zurückfallen, wenn die nachfolgende Handshake-Prüfung keine Versionsmetadaten bereitstellen kann.
• Verwenden Sie --require-rpc in Skripten und Automatisierung, wenn ein lauschender Dienst nicht ausreicht und auch RPC-Aufrufe mit Lese-Scope funktionieren müssen.
• --deep fügt einen Best-Effort-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 einen Gateway pro Maschine ausführen sollten.
• --deep meldet außerdem eine kürzliche Übergabe eines Gateway-Supervisor-Neustarts, wenn der Dienstprozess sauber für einen externen Supervisor-Neustart beendet wurde.
• --deep führt Config-Validierung im Plugin-bewussten Modus (pluginValidation: "full") aus und zeigt Warnungen aus konfigurierten Plugin-Manifesten an (zum Beispiel fehlende Metadaten zur Channel-Config), damit Installations- und Update-Smoke-Checks sie erfassen. Das standardmäßige gateway status behält den schnellen schreibgeschützten Pfad bei, der Plugin-Validierung überspringt.
• Die menschenlesbare Ausgabe enthält den aufgelösten Datei-Logpfad sowie einen Snapshot der CLI-gegen-Dienst-Config-Pfade/-Gültigkeit, um Drift bei Profilen oder State-Verzeichnissen zu diagnostizieren.

• Bei Linux-systemd-Installationen lesen Dienst-Auth-Drift-Prüfungen sowohl Environment=- als auch EnvironmentFile=-Werte aus der Unit (einschließlich %h, zitierter Pfade, mehrerer Dateien und optionaler --Dateien).
• Drift-Prüfungen lösen gateway.auth.token-SecretRefs mithilfe zusammengeführter Runtime-Env auf (zuerst Dienstbefehls-Env, dann Prozess-Env als Fallback).
• Wenn Token-Auth nicht effektiv aktiv ist (expliziter gateway.auth.mode von password/none/trusted-proxy oder nicht gesetzter Modus, bei dem Passwort gewinnen kann und kein Token-Kandidat gewinnen kann), überspringen Token-Drift-Prüfungen die Auflösung des Config-Tokens.

• 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 Auth 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, aber der Lese-Scope-RPC eingeschränkt ist. Dies wird als eingeschränkte Erreichbarkeit gemeldet, nicht als vollständiger Fehler.
• Read probe: failed nach Connect: ok bedeutet, dass der Gateway die WebSocket-Verbindung akzeptiert hat, nachfolgende Lesediagnosen jedoch einen Timeout hatten oder fehlgeschlagen sind. Auch dies ist eingeschränkte Erreichbarkeit, kein unerreichbarer Gateway.
• Wie gateway status verwendet probe vorhandene gecachte Geräte-Auth wieder, erstellt aber keine erstmalige Geräteidentität oder Pairing-State.
• 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 keine vollständigen Detail-RPC-Diagnosen abgeschlossen.
• capability: beste Fähigkeit über erreichbare Ziele hinweg (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-Verbindung, dann local loopback.
• warnings[]: Best-Effort-Warndatensätze mit code, message und optionalen targetIds.
• network: local loopback-/tailnet-URL-Hinweise, abgeleitet aus aktueller Config und Host-Netzwerk.
• discovery.timeoutMs und discovery.count: das tatsächliche Discovery-Budget bzw. die Ergebnisanzahl, die für diesen Prüf-Durchlauf verwendet wurden.

Pro Ziel (targets[].connect):

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

Pro Ziel (targets[].auth):

• role: in hello-ok gemeldete Auth-Rolle, wenn verfügbar.
• scopes: in hello-ok gemeldete gewährte Scopes, wenn verfügbar.
• capability: die für dieses Ziel angezeigte Auth-Fähigkeitsklassifizierung.

• ssh_tunnel_failed: Einrichtung des SSH-Tunnels fehlgeschlagen; der Befehl ist auf direkte Prüfungen zurückgefallen.
• multiple_gateways: unterschiedliche Gateway-Identitäten waren erreichbar, oder OpenClaw konnte nicht nachweisen, dass erreichbare Ziele derselbe Gateway sind. Ein SSH-Tunnel, eine Proxy-URL oder eine konfigurierte Remote-URL zum selben Gateway löst diese Warnung nicht aus.
• auth_secretref_unresolved: Ein konfigurierter Auth-SecretRef konnte für ein fehlgeschlagenes Ziel nicht aufgelöst werden.
• probe_scope_limited: WebSocket-Verbindung war 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 künftige Abstürze aktiv, und gateway start aktiviert sauber wieder, ohne ein manuelles launchctl enable. Übergeben Sie --disable, um KeepAlive und RunAtLoad dauerhaft zu unterdrücken, damit der Gateway bis zum nächsten ausdrücklichen gateway start nicht erneut startet; verwenden Sie dies, wenn ein manueller Stopp Neustarts des Systems überdauern soll.
• gateway restart --safe bittet den laufenden Gateway, aktive Arbeit vorab zu prüfen und einen zusammengefassten Neustart zu planen, nachdem aktive Arbeit abgearbeitet ist. Der standardmäßige sichere Neustart wartet bis zum konfigurierten gateway.reload.deferralTimeoutMs (Standard: 5 Minuten) auf aktive Arbeit; wenn dieses Budget abläuft, wird der Neustart erzwungen. Setzen Sie gateway.reload.deferralTimeoutMs auf 0, um unbegrenzt sicher zu warten, ohne jemals zu erzwingen. --safe kann nicht mit --force oder --wait kombiniert werden.
• gateway restart --wait 30s überschreibt das konfigurierte Neustart-Drain-Budget für diesen Neustart. Bloße Zahlen 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 die Aufschubprüfung, sodass der Gateway den Neustart sofort ausgibt, selbst wenn Blocker gemeldet werden. Operator-Notausstieg für Aufschübe durch festhängende Task-Ausführungen; erfordert --safe.
• gateway restart --force überspringt das Abarbeiten aktiver Arbeit und startet sofort neu. Verwenden Sie dies, wenn ein Operator die aufgelisteten Task-Blocker bereits geprüft hat und den Gateway jetzt wieder verfügbar haben möchte.
• Lifecycle-Befehle akzeptieren --json für Skripting.

• Wenn Token-Auth ein Token erfordert und gateway.auth.token SecretRef-verwaltet ist, prüft gateway install, ob die SecretRef auflösbar ist, speichert das aufgelöste Token aber nicht in den Dienstumgebungsmetadaten.
• Wenn Token-Auth ein Token erfordert und die konfigurierte Token-SecretRef nicht aufgelöst werden kann, schlägt die Installation fail-closed fehl, statt Fallback-Klartext zu speichern.
• Für Passwort-Auth bei gateway run bevorzugen Sie OPENCLAW_GATEWAY_PASSWORD, --password-file oder ein SecretRef-gestütztes gateway.auth.password gegenüber inline --password.
• Im abgeleiteten Auth-Modus 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 config 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 ausdrücklich gesetzt wird.