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; damit wird die Prü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 Läufe reparieren niemals automatisch; stattdessen geben sie den Befehl aus. Ist die reparierte Konfiguration weiterhin ungültig, bleibt der Startvorgang 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/überschriebene Konfiguration behandelt, und der Gateway weigert sich, 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 Delegationswerkzeug 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, Zähler, Bytegrößen, Speicherwerte, Warteschlangen-/Sitzungsstatus, Genehmigungs-IDs, Kanal-/Plugin-Namen und redigierte Sitzungszusammenfassungen. Sie schließen Chattext, Webhook-Inhalte, Tool-Ausgaben, unverarbeitete Anfrage-/Antwortinhalte, Tokens, Cookies, geheime Werte, Hostnamen und unverarbeitete Sitzungs-IDs aus. Setzen Sie diagnostics.enabled: false, um den Rekorder vollständig zu deaktivieren.
• Bei schwerwiegenden Gateway-Abbrüchen, Zeitüberschreitungen beim Herunterfahren und Startfehlern nach einem Neustart wird derselbe Diagnoseschnappschuss nach ~/.openclaw/logs/stability/openclaw-stability-*.json geschrieben, sofern der Rekorder 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 Authentifizierungsfähigkeit nach – nicht Lese-, Schreib- oder Administratorvorgänge.
• Proben 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 Probeauthentifizierung nach Möglichkeit auf. Wenn eine erforderliche SecretRef nicht aufgelöst ist, meldet --json bei einem Fehlschlag der Probekonnektivität/-authentifizierung rpc.authWarning; übergeben Sie --token/--password explizit oder korrigieren Sie die Quelle des Geheimnisses. Warnungen zu nicht aufgelöster Authentifizierung werden unterdrückt, sobald die Probe 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-Probe keine Versionsmetadaten liefern kann.
• Verwenden Sie --require-rpc in Skripten/Automatisierungen, wenn ein lauschender Dienst nicht ausreicht und auch RPC mit Leseberechtigung fehlerfrei funktionieren muss.
• --deep sucht nach zusätzlichen launchd-/systemd-/schtasks-Installationen; wenn mehrere Gateway-ähnliche Dienste gefunden werden, gibt die menschenlesbare Ausgabe Bereinigungshinweise aus (üblicherweise sollte pro Rechner ein Gateway ausgeführt werden) und meldet gegebenenfalls eine kürzlich erfolgte Neustartübergabe durch den Supervisor.
• --deep führt außerdem die Konfigurationsvalidierung im Plugin-fähigen Modus (pluginValidation: "full") aus und zeigt Warnungen zum Plugin-Manifest 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 Dateipfad des Protokolls 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 seiner adaptiven 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, dann ersatzweise die Prozessumgebung).
• Prüfungen auf Token-Abweichungen überspringen die Auflösung des Konfigurations-Tokens, wenn die Token-Authentifizierung tatsächlich 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 Probe hinsichtlich der Authentifizierung nachweisen konnte.
• Read probe: ok bedeutet, dass auch detaillierte RPC-Aufrufe mit Leseberechtigung (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 gemeldet, nicht als vollständiger Fehlschlag.
• Read probe: failed nach Connect: ok bedeutet, dass die WebSocket-Verbindung hergestellt wurde, nachfolgende Lesediagnosen jedoch eine Zeitüberschreitung erreichten oder fehlschlugen – ebenfalls beeinträchtigt, nicht unerreichbar.
• Wie gateway status verwendet die Probe vorhandene zwischengespeicherte Geräteauthentifizierung erneut, erstellt jedoch keine erstmalige Geräteidentität oder keinen Kopplungsstatus.
• Der Beendigungscode 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 angenommen, aber die vollständige detaillierte RPC-Diagnose nicht abgeschlossen.
• capability: Beste für erreichbare Ziele 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, konfigurierte Gegenstelle, lokale Loopback-Schnittstelle.
• warnings[]: Nach bestem Bemühen erstellte Warnungsdatensätze mit code, message und optional targetIds.
• network: Aus der aktuellen Konfiguration und dem Hostnetzwerk abgeleitete URL-Hinweise für lokale Loopback-Schnittstellen 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 (vollständiger Erfolg des Detail-RPC), scopeLimited (Detail-RPC wegen fehlendem Operator-Berechtigungsumfang 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 zu demselben 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 durch das fehlende 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> (Standardwert: 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 zuvor gestartet.
• 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.
• In einer nicht interaktiven Shell erfordert gateway stop die Option --force. Interaktive Terminals behalten das bestehende Verhalten ohne Eingabeaufforderung bei. Für Automatisierung und Tests sollten Sie gateway run --dev oder ein isoliertes --profile mit einem freien Port bevorzugen.
• Unter macOS verwendet gateway stop standardmäßig launchctl bootout. Dadurch wird der LaunchAgent aus der aktuellen Startsitzung entfernt, ohne eine Deaktivierung dauerhaft zu speichern – die automatische KeepAlive-Wiederherstellung bleibt bei zukünftigen Abstürzen aktiv, und gateway start aktiviert den Dienst ohne ein manuelles launchctl enable wieder ordnungsgemäß. Übergeben Sie --disable, um KeepAlive und RunAtLoad dauerhaft zu unterdrücken, sodass das Gateway erst nach dem nächsten expliziten gateway start erneut gestartet wird; verwenden Sie dies, wenn ein manuelles Anhalten Neustarts des Systems überdauern soll.
• Mutationen am Gateway-Lebenszyklus hängen nach bestem Bemühen Schlüssel-Wert-Prüfdatensätze an <state-dir>/logs/gateway-restart.log an, darunter CLI-Start-, Stopp- und Neustartvorgänge, Anforderungen für sichere Neustarts, Supervisor-Neustarts und entkoppelte Übergaben.
• Lebenszyklusbefehle akzeptieren --json für Skripting.

• 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, mit einer zusätzlichen Obergrenze, die 75 % für nativen Speicher freihält. Auf kleinen Hosts kann diese Obergrenze dazu führen, dass das angewendete Limit unter dem nominellen Mindestwert von 2048 MiB liegt.
• Ein gültiges explizites --max-old-space-size, das bereits im installierten Dienst gespeichert ist, bleibt bei erzwungenen Neuinstallationen und Reparaturen durch Doctor erhalten. Andere NODE_OPTIONS-Flags werden nicht in den verwalteten Dienst übernommen.
• Das aus der Shell-Umgebung stammende NODE_OPTIONS setzt diese Richtlinie nicht außer Kraft. 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-Einheiten behalten ihre eigene Laufzeitkonfiguration bei.

• 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, statt ersatzweise Klartext zu speichern.
• Bevorzugen Sie für die Passwortauthentifizierung auf gateway run OPENCLAW_GATEWAY_PASSWORD, --password-file oder ein durch SecretRef gestütztes gateway.auth.password gegenüber einem eingebetteten --password.
• Im abgeleiteten Authentifizierungsmodus lockert das ausschließlich in der Shell gesetzte 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 festgelegt ist, wird die Installation blockiert, bis der Modus explizit festgelegt wurde.