Gateway

• Der Start wird verweigert, sofern gateway.mode=local nicht in ~/.openclaw/openclaw.json festgelegt ist. Verwenden Sie --allow-unconfigured für Ad-hoc-/Entwicklungsausführungen; damit wird die Schutzprüfung umgangen, ohne die Konfiguration zu schreiben oder zu reparieren.
• Wenn beim Start eine reparierbare ungültige Konfiguration gefunden wird, bietet ein interaktives Terminal an, openclaw doctor --fix auszuführen, und versucht den Start nach Zustimmung einmal erneut. Nicht interaktive Ausführungen reparieren niemals automatisch, sondern geben stattdessen den Befehl aus. Ist die reparierte Konfiguration weiterhin ungültig, bleibt der Start angehalten.
• 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 versucht nicht, local für Sie zu erraten — führen Sie das Onboarding erneut aus, legen Sie den Schlüssel manuell fest oder übergeben Sie --allow-unconfigured.
• Eine Bindung über die Loopback-Schnittstelle hinaus wird ohne Authentifizierung blockiert.
• Die --bind-Werte lan, tailnet und custom werden derzeit ausschließlich über IPv4-Pfade aufgelöst; reine IPv6-Setups 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; setzen Sie den Wert auf false, um manuelle Neustarts durch Betriebssystemsignale zu blockieren. Das agentenseitige Werkzeug gateway ist schreibgeschützt; Agenten fordern einen Neustart über das von Menschen genehmigte Delegierungswerkzeug openclaw an.
• SIGINT/SIGTERM beenden den Prozess, stellen jedoch keinen benutzerdefinierten Terminalzustand wieder her — wenn Sie die CLI in eine TUI oder eine Eingabe im Raw-Modus einbetten, stellen Sie das Terminal vor dem Beenden selbst wieder her.

• Datensätze enthalten betriebliche Metadaten: Ereignisnamen, Anzahlen, Bytegrößen, Speicherwerte, Warteschlangen-/Sitzungsstatus, Genehmigungs-IDs, Kanal-/Plugin-Namen und redigierte Sitzungszusammenfassungen. Ausgeschlossen sind Chattext, Webhook-Inhalte, Tool-Ausgaben, unverarbeitete Anfrage-/Antwortinhalte, Token, Cookies, geheime Werte, Hostnamen und unverarbeitete Sitzungs-IDs. Setzen Sie diagnostics.enabled: false, um die Aufzeichnung vollständig zu deaktivieren.
• Bei schwerwiegenden Gateway-Abbrüchen, Zeitüberschreitungen beim Herunterfahren und Startfehlern nach einem Neustart wird derselbe Diagnose-Snapshot nach ~/.openclaw/logs/stability/openclaw-stability-*.json geschrieben, sofern die Aufzeichnung Ereignisse enthält. Prüfen Sie das neueste Paket mit openclaw gateway stability --bundle latest; --limit, --type und --since-seq gelten auch für die Paketausgabe.

• Bleibt für Diagnosen verfügbar, selbst wenn die lokale CLI-Konfiguration fehlt oder ungültig ist.
• Die Standardausgabe weist den Dienststatus, die WebSocket-Verbindung und die beim Handshake sichtbare Authentifizierungsfunktion 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, erstellen jedoch niemals nur zur Statusprüfung eine neue CLI-Geräteidentität oder einen schreibgeschützten Kopplungsdatensatz.
• Löst konfigurierte Authentifizierungs-SecretRefs für die Prüfauthentifizierung nach Möglichkeit auf. Wenn ein erforderlicher SecretRef nicht aufgelöst ist, meldet --json bei einem Fehler der Prüfverbindung/-authentifizierung rpc.authWarning; übergeben Sie --token/--password explizit oder korrigieren Sie die Geheimnisquelle. 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 dies meldet; --require-rpc kann auf die status.runtimeVersion-RPC-Nutzlast zurückgreifen, wenn die Handshake-Prüfung keine Versionsmetadaten bereitstellen 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 (in der Regel sollte pro Rechner ein Gateway ausgeführt werden) und meldet gegebenenfalls eine kürzlich erfolgte Neustartübergabe des Supervisors.
• --deep führt außerdem eine Konfigurationsvalidierung im Plugin-kompatiblen Modus (pluginValidation: "full") aus und zeigt Warnungen aus Plugin-Manifesten an (z. B. fehlende Metadaten zur Kanalkonfiguration). Das standardmäßige 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 Dateiprotokolle sowie die Konfigurationspfade und deren Gültigkeit für CLI und Dienst, um Abweichungen bei Profilen oder Zustandsverzeichnissen leichter zu diagnostizieren.
• Die menschenlesbare Ausgabe enthält Gateway heap: mit dem angewendeten Grenzwert und dessen adaptiver Herleitung. Die JSON-Ausgabe stellt denselben Bericht als service.gatewayHeap bereit.

• 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).
• Löst gateway.auth.token-SecretRefs mithilfe der zusammengeführten Laufzeitumgebung auf (zuerst die Befehlsumgebung des Dienstes, danach 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 explizit password/none/trusted-proxy oder kein Modus festgelegt ist, sodass 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 meldet unabhängig von der Erreichbarkeit, was die Prüfung hinsichtlich der Authentifizierung nachweisen konnte.
• Read probe: ok bedeutet, dass auch Detail-RPC-Aufrufe mit Leseberechtigung (health/status/system-presence/config.get) erfolgreich waren.
• Read probe: limited - missing scope: operator.read bedeutet, dass die Verbindung erfolgreich hergestellt wurde, RPC mit Leseberechtigung jedoch eingeschränkt ist. Dies wird als beeinträchtigte Erreichbarkeit und nicht als vollständiger Fehler gemeldet.
• Read probe: failed nach Connect: ok bedeutet, dass die WebSocket-Verbindung hergestellt wurde, nachfolgende Lesediagnosen jedoch das Zeitlimit überschritten haben oder fehlgeschlagen sind – ebenfalls beeinträchtigt, nicht unerreichbar.
• Wie gateway status verwendet die Prüfung eine vorhandene zwischengespeicherte Geräteauthentifizierung, erstellt jedoch keine erstmalige Geräteidentität oder keinen Kopplungsstatus.
• Der Exit-Code ist nur dann von null verschieden, wenn keines der geprüften Ziele 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 Fähigkeit (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 dieser Reihenfolge: explizite URL, SSH-Tunnel, konfiguriertes Remote-Ziel, lokale Loopback-Adresse.
• warnings[]: Nach bestem Bemühen erstellte Warnungsdatensätze mit code, message und optional targetIds.
• network: Aus der aktuellen Konfiguration und der Host-Netzwerkkonfiguration abgeleitete URL-Hinweise für lokale Loopback-Adressen bzw. das Tailnet.
• discovery.timeoutMs / discovery.count: Das für diesen Prüfdurchlauf tatsächlich verwendete Ermittlungsbudget bzw. die tatsächliche Ergebnisanzahl.

Pro Ziel (targets[].connect): ok (Erreichbarkeit und Klassifizierung als eingeschränkt), rpcOk (Erfolg des vollständigen Detail-RPC), scopeLimited (Detail-RPC wegen fehlenden Operator-Bereichs fehlgeschlagen).

Pro Ziel (targets[].auth): role und scopes werden, sofern verfügbar, in hello-ok gemeldet, zusammen mit der ausgegebenen Klassifizierung capability.

• ssh_tunnel_failed: Die Einrichtung des SSH-Tunnels ist fehlgeschlagen; der Befehl ist auf direkte Prüfungen ausgewichen.
• 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 zum selben Gateway löst dies nicht aus.
• auth_secretref_unresolved: Eine konfigurierte Authentifizierungs-SecretRef konnte für ein fehlgeschlagenes Ziel nicht aufgelöst werden.
• probe_scope_limited: Die WebSocket-Verbindung wurde erfolgreich hergestellt, aber die Leseprüfung war aufgrund des fehlenden operator.read eingeschränkt.
• local_tls_runtime_unavailable: TLS ist für das lokale Gateway aktiviert, aber OpenClaw konnte den Fingerabdruck des lokalen Zertifikats nicht laden.

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

• gateway start ist idempotent: Wenn der verwaltete Dienst bereits ausgeführt wird, meldet der Befehl den laufenden Prozess und lässt ihn unverändert. Ein geladener, aber angehaltener Dienst wird wie bisher gestartet.
• 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.
• In einer nicht interaktiven Shell erfordert gateway stop die Option --force. Interaktive Terminals behalten das bestehende Verhalten ohne Eingabeaufforderung bei. Bevorzugen Sie für Automatisierungen und Tests gateway run --dev oder eine isolierte --profile mit einem freien Port.
• Unter macOS verwendet gateway stop standardmäßig launchctl bootout. Dadurch wird der LaunchAgent aus der aktuellen Startsitzung entfernt, ohne eine Deaktivierung zu persistieren – die automatische Wiederherstellung durch KeepAlive bleibt bei zukünftigen Abstürzen aktiv, und gateway start aktiviert den Dienst ohne ein manuelles launchctl enable ordnungsgemäß wieder. Übergeben Sie --disable, um KeepAlive und RunAtLoad dauerhaft zu unterdrücken, sodass der Gateway bis zum nächsten expliziten gateway start nicht erneut gestartet wird. Verwenden Sie dies, wenn ein manuelles Anhalten Neustarts des Systems überdauern soll.
• Änderungen am Gateway-Lebenszyklus hängen nach dem Best-Effort-Prinzip Schlüssel-Wert-Auditdatensätze an <state-dir>/logs/gateway-restart.log an. Dazu gehören Start-, Stopp- und Neustartvorgänge der CLI, sichere Neustartanforderungen, Supervisor-Neustarts und abgekoppelte Übergaben.
• Lebenszyklusbefehle akzeptieren --json für Skripte.

• gateway install schreibt für den verwalteten Gateway-Dienst einen ausschließlich den Heap betreffenden Wert für NODE_OPTIONS. Wenn Node eine Container- oder Dienstbegrenzung meldet, werden 50 % des begrenzten Arbeitsspeichers angestrebt, andernfalls 50 % des physischen Arbeitsspeichers.
• Der nominelle Zielbereich beträgt 2048–8192 MiB, ergänzt durch eine Obergrenze, die 75 % für nativen Spielraum vorbehält. Auf kleinen Hosts kann diese Spielraumbegrenzung das angewendete Limit unter die nominelle Untergrenze von 2048 MiB senken.
• Ein gültiger expliziter Wert für --max-old-space-size, der bereits im installierten Dienst gespeichert ist, bleibt bei erzwungenen Neuinstallationen und Reparaturen durch doctor erhalten. Andere Flags von NODE_OPTIONS werden nicht in den verwalteten Dienst übernommen.
• Das in der umgebenden Shell gesetzte NODE_OPTIONS überschreibt diese Richtlinie nicht. Verwenden Sie gateway status oder doctor, um den installierten Wert zu prüfen. Führen Sie openclaw gateway install --force aus, um ältere Dienstmetadaten neu zu erzeugen, die keine verwaltete Heap-Einstellung enthalten.
• Die Richtlinie gilt nur für den verwalteten Gateway-Dienst. Im Vordergrund ausgeführte gateway run, Node-Dienste und manuell erstellte Supervisor-Units behalten ihre eigene Laufzeitkonfiguration bei.

• Wenn die Token-Authentifizierung ein Token erfordert und gateway.auth.token über SecretRef verwaltet wird, prüft gateway install, ob die SecretRef aufgelöst werden kann, persistiert 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 persistieren.
• Bevorzugen Sie für die Passwortauthentifizierung auf gateway run die Optionen OPENCLAW_GATEWAY_PASSWORD, --password-file oder ein durch SecretRef gestütztes gateway.auth.password gegenüber einem inline angegebenen --password.
• Im abgeleiteten Authentifizierungsmodus lockert ein ausschließlich in der Shell gesetztes OPENCLAW_GATEWAY_PASSWORD die Token-Anforderungen der Installation nicht. Verwenden Sie bei der Installation eines verwalteten Dienstes eine dauerhafte Konfiguration (gateway.auth.password oder die Konfiguration env).
• 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 festgelegt wurde.