Gateway

• Standaard weigert de Gateway te starten tenzij gateway.mode=local is ingesteld in ~/.openclaw/openclaw.json. Gebruik --allow-unconfigured voor ad-hoc-/ontwikkelruns.
• Van openclaw onboard --mode local en openclaw setup wordt verwacht dat ze gateway.mode=local schrijven. Als het bestand bestaat maar gateway.mode ontbreekt, behandel dat dan als een kapotte of overschreven configuratie en herstel die in plaats van impliciet de lokale modus aan te nemen.
• Als het bestand bestaat en gateway.mode ontbreekt, behandelt de Gateway dat als verdachte configuratieschade en weigert deze voor je "lokaal te raden".
• Binding buiten loopback zonder auth wordt geblokkeerd (veiligheidsvangrail).
• SIGUSR1 activeert een herstart binnen het proces wanneer dit geautoriseerd is (commands.restart is standaard ingeschakeld; stel commands.restart: false in om handmatig herstarten te blokkeren, terwijl toepassen/bijwerken van Gateway-tools/-configuratie toegestaan blijft).
• SIGINT/SIGTERM-handlers stoppen het Gateway-proces, maar herstellen geen aangepaste terminalstatus. Als je de CLI inpakt met een TUI of raw-mode-invoer, herstel dan de terminal voordat je afsluit.

• Records bewaren operationele metadata: eventnamen, aantallen, bytegroottes, geheugenmetingen, wachtrij-/sessiestatus, kanaal-/Plugin-namen en geredigeerde sessiesamenvattingen. Ze bewaren geen chattekst, Webhook-bodies, tooluitvoer, ruwe request- of response-bodies, tokens, cookies, geheime waarden, hostnamen of ruwe sessie-id's. Stel diagnostics.enabled: false in om de recorder volledig uit te schakelen.
• Bij fatale Gateway-afsluitingen, timeouts bij afsluiten en fouten tijdens herstarten schrijft OpenClaw dezelfde diagnostische snapshot naar ~/.openclaw/logs/stability/openclaw-stability-*.json wanneer de recorder events heeft. Inspecteer de nieuwste bundel met openclaw gateway stability --bundle latest; --limit, --type en --since-seq gelden ook voor bundeluitvoer.

• gateway status blijft beschikbaar voor diagnostiek, zelfs wanneer de lokale CLI-configuratie ontbreekt of ongeldig is.
• Standaard bewijst gateway status de servicestatus, WebSocket-verbinding en de authenticatiecapaciteit die zichtbaar is tijdens de handshake. Het bewijst geen lees-/schrijf-/beheerbewerkingen.
• Diagnostische probes muteren niets voor eerste apparaat-authenticatie: ze hergebruiken een bestaande gecachete apparaattoken wanneer die bestaat, maar maken geen nieuwe CLI-apparaatidentiteit of alleen-lezen apparaatkoppelingsrecord aan alleen om de status te controleren.
• gateway status lost geconfigureerde authenticatie-SecretRefs op voor probe-authenticatie wanneer dat mogelijk is.
• Als een vereiste authenticatie-SecretRef in dit commandopad niet kan worden opgelost, meldt gateway status --json rpc.authWarning wanneer probe-connectiviteit/-authenticatie mislukt; geef --token/--password expliciet door of los eerst de geheime bron op.
• Als de probe slaagt, worden waarschuwingen over niet-opgeloste auth-referenties onderdrukt om fout-positieven te vermijden.
• Gebruik --require-rpc in scripts en automatisering wanneer een luisterende service niet genoeg is en RPC-aanroepen met leesbereik ook gezond moeten zijn.
• --deep voegt een best-effort scan toe voor extra launchd-/systemd-/schtasks-installaties. Wanneer meerdere gateway-achtige services worden gedetecteerd, toont mensleesbare uitvoer opruimtips en waarschuwt die dat de meeste setups één Gateway per machine zouden moeten draaien.
• --deep meldt ook een recente overdracht van een Gateway-supervisorherstart wanneer het serviceproces netjes is afgesloten voor een externe supervisorherstart.
• Mensleesbare uitvoer bevat het opgeloste bestandslogpad plus een snapshot van de CLI-versus-service-configuratiepaden/-geldigheid om profiel- of state-dir-afwijkingen te helpen diagnosticeren.

• Bij Linux systemd-installaties lezen controles op service-auth-drift zowel Environment=- als EnvironmentFile=-waarden uit de unit (inclusief %h, gequote paden, meerdere bestanden en optionele --bestanden).
• Driftcontroles lossen gateway.auth.token SecretRefs op met de samengevoegde runtime-omgeving (eerst de servicecommando-omgeving, daarna de procesomgeving als fallback).
• Als tokenauthenticatie feitelijk niet actief is (expliciete gateway.auth.mode van password/none/trusted-proxy, of modus niet ingesteld waarbij wachtwoord kan winnen en geen tokenkandidaat kan winnen), slaan token-driftcontroles configuratietokenresolutie over.

• Reachable: yes betekent dat ten minste één doel een WebSocket-verbinding heeft geaccepteerd.
• Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only meldt wat de probe over authenticatie kon bewijzen. Dit staat los van bereikbaarheid.
• Read probe: ok betekent dat detail-RPC-aanroepen met leesbereik (health/status/system-presence/config.get) ook zijn geslaagd.
• Read probe: limited - missing scope: operator.read betekent dat verbinden is gelukt, maar dat RPC met leesbereik beperkt is. Dit wordt gemeld als verminderde bereikbaarheid, niet als volledige mislukking.
• Read probe: failed na Connect: ok betekent dat de Gateway de WebSocket-verbinding heeft geaccepteerd, maar dat vervolgleesdiagnostiek is verlopen of mislukt. Dit is ook verminderde bereikbaarheid, geen onbereikbare Gateway.
• Net als gateway status hergebruikt probe bestaande gecachete apparaatauthenticatie, maar maakt het geen eerste apparaatidentiteit of koppelingsstatus aan.
• De afsluitcode is alleen niet nul wanneer geen enkel geprobed doel bereikbaar is.

Bovenste niveau:

• ok: ten minste één doel is bereikbaar.
• degraded: ten minste één doel heeft een verbinding geaccepteerd, maar heeft niet alle detail-RPC-diagnostiek voltooid.
• capability: beste capaciteit die is gezien over bereikbare doelen (read_only, write_capable, admin_capable, pairing_pending, connected_no_operator_scope of unknown).
• primaryTargetId: beste doel om als actieve winnaar te behandelen, in deze volgorde: expliciete URL, SSH-tunnel, geconfigureerde remote en daarna local loopback.
• warnings[]: best-effort waarschuwingsrecords met code, message en optionele targetIds.
• network: local loopback-/tailnet-URL-hints afgeleid van de huidige configuratie en hostnetwerken.
• discovery.timeoutMs en discovery.count: het daadwerkelijke discovery-budget/resultaantal dat voor deze probe-run is gebruikt.

Per doel (targets[].connect):

• ok: bereikbaarheid na verbinding + classificatie als verminderd.
• rpcOk: volledige detail-RPC geslaagd.
• scopeLimited: detail-RPC mislukt door ontbrekend operatorbereik.

Per doel (targets[].auth):

• role: authenticatierol gerapporteerd in hello-ok wanneer beschikbaar.
• scopes: toegekende bereiken gerapporteerd in hello-ok wanneer beschikbaar.
• capability: de getoonde classificatie van authenticatiecapaciteit voor dat doel.

• ssh_tunnel_failed: instellen van SSH-tunnel is mislukt; de opdracht viel terug op directe probes.
• multiple_gateways: meer dan één doel was bereikbaar; dit is ongebruikelijk tenzij je bewust geïsoleerde profielen draait, zoals een reddingsbot.
• auth_secretref_unresolved: een geconfigureerde authenticatie-SecretRef kon niet worden opgelost voor een mislukt doel.
• probe_scope_limited: WebSocket-verbinding is gelukt, maar de leesprobe was beperkt door ontbrekende operator.read.

• 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

• Gebruik gateway restart om een beheerde service opnieuw te starten. Keten gateway stop en gateway start niet als vervanging voor een herstart; op macOS schakelt gateway stop de LaunchAgent bewust uit voordat deze wordt gestopt.
• gateway restart --safe vraagt de draaiende Gateway om actief OpenClaw-werk vooraf te controleren en de herstart uit te stellen totdat antwoordlevering, embedded runs en taakruns zijn leeggelopen. --safe kan niet worden gecombineerd met --force of --wait.
• gateway restart --wait 30s overschrijft het geconfigureerde drain-budget voor herstarts voor die herstart. Losse getallen zijn milliseconden; eenheden zoals s, m en h worden geaccepteerd. --wait 0 wacht onbeperkt.
• gateway restart --force slaat het leeglopen van actief werk over en herstart onmiddellijk. Gebruik dit wanneer een operator de vermelde taakblokkades al heeft geïnspecteerd en de gateway nu terug wil.
• Lifecycle-commando's accepteren --json voor scripting.

• Wanneer tokenauth een token vereist en gateway.auth.token door SecretRef wordt beheerd, valideert gateway install dat de SecretRef kan worden opgelost, maar slaat het opgeloste token niet op in metadata van de serviceomgeving.
• Als tokenauth een token vereist en de geconfigureerde token-SecretRef niet is opgelost, faalt de installatie gesloten in plaats van platte fallback-tekst op te slaan.
• Geef voor wachtwoordauth bij gateway run de voorkeur aan OPENCLAW_GATEWAY_PASSWORD, --password-file of een door SecretRef ondersteunde gateway.auth.password boven inline --password.
• In afgeleide auth-modus versoepelt alleen-shell OPENCLAW_GATEWAY_PASSWORD de vereisten voor installatietokens niet; gebruik duurzame configuratie (gateway.auth.password of config env) bij het installeren van een beheerde service.
• Als zowel gateway.auth.token als gateway.auth.password zijn geconfigureerd en gateway.auth.mode niet is ingesteld, wordt installatie geblokkeerd totdat de modus expliciet is ingesteld.