Gateway

• Der Start wird verweigert, sofern gateway.mode=local nicht in ~/.openclaw/openclaw.json festgelegt ist. Verwenden Sie --allow-unconfigured für Ad-hoc-/Entwicklungsläufe; dies umgeht die Schutzprüfung, ohne die Konfiguration zu schreiben oder zu reparieren.
• openclaw onboard --mode local und openclaw setup schreiben gateway.mode=local. Wenn die Konfigurationsdatei vorhanden ist, aber gateway.mode fehlt, wird dies als beschädigte oder überschriebene Konfiguration behandelt, und der Gateway nimmt nicht eigenständig local für Sie an — führen Sie das Onboarding erneut aus, legen Sie den Schlüssel manuell fest oder übergeben Sie --allow-unconfigured.
• Eine Bindung über Loopback hinaus wird ohne Authentifizierung blockiert.
• Die --bind-Werte lan, tailnet und custom werden derzeit ausschließlich über IPv4-Pfade aufgelöst; reine IPv6-Installationen mit eigenem Host benötigen einen IPv4-Sidecar oder Proxy vor dem Gateway.
• SIGUSR1 löst bei entsprechender Autorisierung einen prozessinternen Neustart aus. commands.restart (Standard: aktiviert) steuert extern gesendete SIGUSR1-Signale; setzen Sie den Wert auf false, um manuelle Neustarts über Betriebssystemsignale zu blockieren, während Neustarts über den Befehl gateway restart, das Gateway-Tool sowie das Anwenden oder Aktualisieren der Konfiguration weiterhin möglich bleiben.
• SIGINT/SIGTERM beenden den Prozess, stellen jedoch keinen benutzerdefinierten Terminalzustand wieder her — wenn Sie die CLI in eine TUI oder eine Eingabe im Rohmodus einbetten, stellen Sie das Terminal vor dem Beenden selbst wieder her.

• Aufzeichnungen bewahren betriebliche Metadaten auf: Ereignisnamen, Anzahlen, Bytegrößen, Speicherwerte, Warteschlangen-/Sitzungsstatus, Genehmigungs-IDs, Kanal-/Plugin-Namen und redigierte Sitzungszusammenfassungen. Ausgeschlossen sind Chattexte, Webhook-Inhalte, Tool-Ausgaben, unverarbeitete Anfrage-/Antwortinhalte, Tokens, Cookies, geheime Werte, Hostnamen und unverarbeitete Sitzungs-IDs. Setzen Sie diagnostics.enabled: false, um die Aufzeichnung vollständig zu deaktivieren.
• Schwerwiegende Gateway-Beendigungen, Zeitüberschreitungen beim Herunterfahren und Startfehler nach Neustarts schreiben denselben Diagnose-Snapshot nach ~/.openclaw/logs/stability/openclaw-stability-*.json, wenn die Aufzeichnung Ereignisse enthält. Untersuchen Sie das neueste Paket mit openclaw gateway stability --bundle latest; --limit, --type und --since-seq gelten auch für die Paketausgabe.

• Bleibt für Diagnosezwecke verfügbar, auch wenn die lokale CLI-Konfiguration fehlt oder ungültig ist.
• Die Standardausgabe weist den Dienststatus, die WebSocket-Verbindung und die beim Handshake sichtbare Authentifizierungsberechtigung nach – nicht Lese-, Schreib- oder Administratorvorgänge.
• Prüfungen verändern bei der erstmaligen Geräteauthentifizierung nichts: Sie verwenden ein vorhandenes zwischengespeichertes Geräte-Token erneut, erstellen jedoch niemals nur zur Statusprüfung eine neue CLI-Geräteidentität oder einen schreibgeschützten Kopplungsdatensatz.
• Löst konfigurierte SecretRefs für die Authentifizierung nach Möglichkeit für die Prüfauthentifizierung auf. Wenn ein erforderlicher SecretRef nicht aufgelöst ist, meldet --json rpc.authWarning, falls die Verbindung oder Authentifizierung der Prüfung fehlschlägt. Übergeben Sie --token/--password explizit oder korrigieren Sie die Secret-Quelle. Warnungen wegen nicht aufgelöster Authentifizierung werden unterdrückt, sobald die Prüfung erfolgreich ist.
• Die JSON-Ausgabe enthält gateway.version, wenn das laufende Gateway diese meldet. --require-rpc kann auf die RPC-Nutzlast status.runtimeVersion zurückgreifen, wenn die Handshake-Prüfung keine Versionsmetadaten liefern kann.
• Verwenden Sie --require-rpc in Skripten und Automatisierungen, wenn ein lauschender Dienst nicht ausreicht und auch RPC mit Leseberechtigung funktionsfähig sein muss.
• --deep sucht nach zusätzlichen launchd-/systemd-/schtasks-Installationen. Wenn mehrere Gateway-ähnliche Dienste gefunden werden, gibt die menschenlesbare Ausgabe Bereinigungshinweise aus (normalerweise sollte pro Computer ein Gateway ausgeführt werden) und meldet gegebenenfalls eine kürzlich erfolgte Neustartübergabe durch den Supervisor.
• --deep führt außerdem die Konfigurationsvalidierung in einem Plugin-kompatiblen Modus (pluginValidation: "full") aus und zeigt Warnungen zu Plugin-Manifesten an (z. B. fehlende Metadaten zur Kanalkonfiguration). Der standardmäßige Befehl gateway status behält den schnellen schreibgeschützten Pfad bei, der die Plugin-Validierung überspringt.
• Die menschenlesbare Ausgabe enthält den aufgelösten Pfad der Protokolldatei sowie die Konfigurationspfade und deren Gültigkeit für CLI und Dienst, um Abweichungen bei Profilen oder Zustandsverzeichnissen leichter zu diagnostizieren.

• Prüfungen auf Abweichungen bei der Dienstauthentifizierung lesen sowohl Environment= als auch EnvironmentFile= aus der Unit (einschließlich %h, Pfaden in Anführungszeichen, mehreren Dateien und optionalen Dateien mit -).
• Löst SecretRefs für gateway.auth.token mithilfe der zusammengeführten Laufzeitumgebung auf (zuerst die Befehlsumgebung des Dienstes, anschließend ersatzweise die Prozessumgebung).
• Prüfungen auf Token-Abweichungen überspringen die Auflösung des Konfigurations-Tokens, wenn die Token-Authentifizierung faktisch nicht aktiv ist (gateway.auth.mode ist explizit password/none/trusted-proxy, oder der Modus ist nicht festgelegt, wobei das Passwort Vorrang haben kann und kein Token-Kandidat Vorrang erhalten kann).

• Reachable: yes bedeutet, dass mindestens ein Ziel eine WebSocket-Verbindung akzeptiert hat.
• Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only gibt unabhängig von der Erreichbarkeit an, welche Authentifizierungsberechtigung die Prüfung nachweisen konnte.
• Read probe: ok bedeutet, dass auch RPC-Aufrufe mit Leseberechtigung für Detailinformationen (health/status/system-presence/config.get) erfolgreich waren.
• Read probe: limited - missing scope: operator.read bedeutet, dass die Verbindung erfolgreich war, RPC mit Leseberechtigung jedoch eingeschränkt ist. Dies wird als beeinträchtigte Erreichbarkeit und nicht als vollständiger Ausfall gemeldet.
• Read probe: failed nach Connect: ok bedeutet, dass die WebSocket-Verbindung hergestellt wurde, die anschließende Lesediagnose jedoch das Zeitlimit überschritten hat oder fehlgeschlagen ist – ebenfalls beeinträchtigt, nicht unerreichbar.
• Wie gateway status verwendet die Prüfung eine vorhandene zwischengespeicherte Geräteauthentifizierung erneut, erstellt jedoch keine erstmalige Geräteidentität oder keinen Kopplungsstatus.
• Der Exit-Code ist nur dann von null verschieden, 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 RPC-Detaildiagnose nicht abgeschlossen.
• capability: Beste bei den erreichbaren Zielen festgestellte Berechtigung (read_only, write_capable, admin_capable, pairing_pending, connected_no_operator_scope oder unknown).
• primaryTargetId: Bestes Ziel, das als aktiver Gewinner behandelt werden soll, in folgender Reihenfolge: explizite URL, SSH-Tunnel, konfiguriertes entferntes Ziel, local loopback.
• warnings[]: Nach bestem Bemühen erstellte Warnungsdatensätze mit code, message und optional targetIds.
• network: URL-Hinweise für local loopback/Tailnet, die aus der aktuellen Konfiguration und der Hostnetzwerkkonfiguration abgeleitet werden.
• discovery.timeoutMs / discovery.count: Das tatsächlich für diesen Prüfdurchlauf verwendete Erkennungsbudget bzw. die Ergebnisanzahl.

Pro Ziel (targets[].connect): ok (Erreichbarkeit und Einstufung der Beeinträchtigung), rpcOk (vollständiger Erfolg der RPC-Detaildiagnose), scopeLimited (Detail-RPC ist aufgrund fehlender Operator-Berechtigung fehlgeschlagen).

Pro Ziel (targets[].auth): role und scopes, wie in hello-ok gemeldet, sofern verfügbar, sowie die ausgegebene capability-Einstufung.

• ssh_tunnel_failed: Die Einrichtung des SSH-Tunnels ist fehlgeschlagen; der Befehl ist auf direkte Prüfungen zurückgefallen.
• multiple_gateways: Unterschiedliche Gateway-Identitäten waren erreichbar oder OpenClaw konnte nicht nachweisen, dass die erreichbaren Ziele dasselbe Gateway sind. Ein SSH-Tunnel, eine Proxy-URL oder eine konfigurierte Remote-URL zu demselben Gateway löst dies nicht aus.
• auth_secretref_unresolved: Ein konfigurierter SecretRef für die Authentifizierung konnte für ein fehlgeschlagenes Ziel nicht aufgelöst werden.
• probe_scope_limited: Die WebSocket-Verbindung war erfolgreich, die Leseprüfung war jedoch durch das fehlende operator.read eingeschränkt.
• local_tls_runtime_unavailable: Lokales Gateway-TLS ist aktiviert, OpenClaw konnte jedoch den Fingerabdruck des lokalen Zertifikats nicht laden.

• gateway status: --url, --token, --password, --timeout, --no-probe, --require-rpc, --deep, --json
• gateway install: --port, --runtime <node|bun> (Standardwert: node), --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 nicht gateway stop und gateway start als Ersatz für einen Neustart.
• Unter macOS verwendet gateway stop standardmäßig launchctl bootout. Dadurch wird der LaunchAgent aus der aktuellen Startsitzung entfernt, ohne dauerhaft deaktiviert zu werden – die automatische Wiederherstellung durch KeepAlive bleibt für zukünftige Abstürze aktiv, und gateway start aktiviert den Dienst ordnungsgemäß wieder, ohne dass ein manuelles launchctl enable erforderlich ist. Übergeben Sie --disable, um KeepAlive und RunAtLoad dauerhaft zu unterdrücken, sodass der Gateway erst nach dem nächsten expliziten gateway start erneut gestartet wird. Verwenden Sie diese Option, wenn ein manueller Stopp Neustarts des Systems überdauern soll.
• Lebenszyklusbefehle akzeptieren --json zur Verwendung in Skripten.

• Wenn die Token-Authentifizierung ein Token erfordert und gateway.auth.token über eine SecretRef verwaltet wird, prüft gateway install, ob die SecretRef aufgelöst werden kann, speichert das aufgelöste Token jedoch nicht in den Umgebungsmetadaten des Dienstes.
• Wenn die Token-Authentifizierung ein Token erfordert und die konfigurierte Token-SecretRef nicht aufgelöst werden kann, schlägt die Installation sicher fehl, anstatt ersatzweise Klartext zu speichern.
• Bevorzugen Sie für die Passwortauthentifizierung bei gateway run OPENCLAW_GATEWAY_PASSWORD, --password-file oder ein durch eine SecretRef gestütztes gateway.auth.password gegenüber einem direkt 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 bei der Installation eines verwalteten Dienstes eine dauerhafte Konfiguration (gateway.auth.password oder env in der Konfiguration).
• Wenn sowohl gateway.auth.token als auch gateway.auth.password konfiguriert sind und gateway.auth.mode nicht festgelegt ist, wird die Installation blockiert, bis der Modus explizit festgelegt wurde.