Gateway

• Standaard weigert de Gateway te starten tenzij gateway.mode=local is ingesteld in ~/.openclaw/openclaw.json. Gebruik --allow-unconfigured voor ad-hoc-/dev-runs.
• 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 defecte 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 hij voor jou "lokaal te raden".
• Binden buiten loopback zonder auth wordt geblokkeerd (veiligheidsvangrail).
• SIGUSR1 activeert een herstart binnen het proces wanneer dit is geautoriseerd (commands.restart is standaard ingeschakeld; stel commands.restart: false in om handmatig herstarten te blokkeren, terwijl gateway-tool/config apply/update toegestaan blijven).
• SIGINT/SIGTERM-handlers stoppen het gateway-proces, maar ze herstellen geen aangepaste terminalstatus. Als je de CLI omwikkelt met een TUI of raw-mode-invoer, herstel dan de terminal vóór het afsluiten.

• Records bewaren operationele metadata: eventnamen, aantallen, bytegroottes, geheugenuitlezingen, wachtrij-/sessiestatus, kanaal-/Plugin-namen en geredigeerde sessiesamenvattingen. Ze bewaren geen chattekst, webhook-bodies, tooluitvoer, onbewerkte request- of response-bodies, tokens, cookies, geheime waarden, hostnamen of onbewerkte sessie-id's. Stel diagnostics.enabled: false in om de recorder volledig uit te schakelen.
• Bij fatale Gateway-afsluitingen, shutdown-time-outs en startup-fouten bij herstart 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 zijn ook van toepassing op bundeluitvoer.

• gateway status blijft beschikbaar voor diagnostiek, zelfs wanneer de lokale CLI-configuratie ontbreekt of ongeldig is.
• Standaard gateway status bewijst servicestatus, WebSocket-verbinding en de auth-capability die zichtbaar is tijdens de handshake. Het bewijst geen lees-/schrijf-/adminbewerkingen.
• Diagnostische probes muteren niets voor eerste apparaatauthenticatie: ze hergebruiken een bestaande gecachte apparaattoken wanneer die bestaat, maar ze maken geen nieuwe CLI-apparaatidentiteit of alleen-lezen apparaatkoppelingsrecord aan alleen om status te controleren.
• gateway status lost geconfigureerde auth SecretRefs voor probe-authenticatie op wanneer dat mogelijk is.
• Als een vereiste auth SecretRef in dit commandopad niet is opgelost, rapporteert gateway status --json rpc.authWarning wanneer probe-connectiviteit/authenticatie mislukt; geef --token/--password expliciet door of los eerst de secret-bron op.
• Als de probe slaagt, worden waarschuwingen over niet-opgeloste auth-refs onderdrukt om fout-positieven te vermijden.
• Gebruik --require-rpc in scripts en automatisering wanneer een luisterende service niet genoeg is en ook RPC-aanroepen met leesbereik gezond moeten zijn.
• --deep voegt een best-effort scan toe voor extra launchd/systemd/schtasks-installaties. Wanneer meerdere gateway-achtige services worden gedetecteerd, toont de menselijke uitvoer opruimhints en waarschuwt die dat de meeste opstellingen één Gateway per machine zouden moeten draaien.
• --deep rapporteert ook een recente Gateway supervisor-herstartoverdracht wanneer het serviceproces netjes is afgesloten voor een externe supervisor-herstart.
• --deep voert configuratievalidatie uit in plugin-bewuste modus (pluginValidation: "full") en toont geconfigureerde waarschuwingen uit Plugin-manifests (bijvoorbeeld ontbrekende kanaalconfiguratiemetadata), zodat install- en update-smokechecks ze vinden. Standaard gateway status behoudt het snelle alleen-lezen pad dat pluginvalidatie overslaat.
• Menselijke uitvoer bevat het opgeloste pad naar het bestandslog plus een snapshot van CLI-versus-serviceconfiguratiepaden/geldigheid om profiel- of state-dir-afwijkingen te helpen diagnosticeren.

• Op Linux systemd-installaties lezen service-auth-driftcontroles zowel Environment=- als EnvironmentFile=-waarden uit de unit (inclusief %h, paden tussen aanhalingstekens, meerdere bestanden en optionele --bestanden).
• Driftcontroles lossen gateway.auth.token SecretRefs op met samengevoegde runtime-env (eerst servicecommando-env, daarna process-env als fallback).
• Als token-auth niet effectief 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 rapporteert wat de probe over auth kon bewijzen. Dit staat los van bereikbaarheid.
• Read probe: ok betekent dat RPC-aanroepen voor details met leesbereik (health/status/system-presence/config.get) ook zijn geslaagd.
• Read probe: limited - missing scope: operator.read betekent dat de verbinding is geslaagd, maar RPC met leesbereik beperkt is. Dit wordt gerapporteerd als verminderde bereikbaarheid, niet als volledige fout.
• 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 gecachte apparaatauthenticatie, maar maakt het geen eerste apparaatidentiteit of koppelingsstatus aan.
• De exitcode is alleen niet-nul wanneer geen enkel geprobed doel bereikbaar is.

Hoogste niveau:

• ok: ten minste één doel is bereikbaar.
• degraded: ten minste één doel heeft een verbinding geaccepteerd, maar heeft de volledige detail-RPC-diagnostiek niet voltooid.
• capability: beste capability die over bereikbare doelen is gezien (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: hints voor local loopback-/tailnet-URL's 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 + degraded-classificatie.
• rpcOk: volledig detail-RPC-succes.
• scopeLimited: detail-RPC is mislukt door ontbrekend operatorbereik.

Per doel (targets[].auth):

• role: auth-rol gerapporteerd in hello-ok wanneer beschikbaar.
• scopes: toegekende scopes gerapporteerd in hello-ok wanneer beschikbaar.
• capability: de getoonde auth-capabilityclassificatie voor dat doel.

• ssh_tunnel_failed: SSH-tunnelconfiguratie is mislukt; het commando 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 rescue-bot.
• auth_secretref_unresolved: een geconfigureerde auth SecretRef kon niet worden opgelost voor een mislukt doel.
• probe_scope_limited: WebSocket-verbinding is geslaagd, maar de leesprobe werd 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, --skip-deferral, --force, --wait <duration>, --json
• gateway uninstall|start: --json
• gateway stop: --disable, --json

• Gebruik gateway restart om een beheerde service opnieuw te starten. Koppel gateway stop en gateway start niet aan elkaar als vervanging voor opnieuw starten.
• Op macOS gebruikt gateway stop standaard launchctl bootout, waarmee de LaunchAgent uit de huidige opstartsessie wordt verwijderd zonder een uitschakeling blijvend te maken — automatische KeepAlive-herstel blijft actief voor toekomstige crashes en gateway start schakelt opnieuw netjes in zonder handmatige launchctl enable. Geef --disable door om KeepAlive en RunAtLoad blijvend te onderdrukken, zodat de gateway niet opnieuw start tot de volgende expliciete gateway start; gebruik dit wanneer een handmatige stop herstarts of systeemherstarts moet overleven.
• gateway restart --safe vraagt de draaiende Gateway om actief OpenClaw-werk vooraf te controleren en de herstart uit te stellen totdat antwoordlevering, ingesloten runs en taakruns zijn leeggemaakt. --safe kan niet worden gecombineerd met --force of --wait.
• gateway restart --wait 30s overschrijft het geconfigureerde drainbudget voor die herstart. Kale getallen zijn milliseconden; eenheden zoals s, m en h worden geaccepteerd. --wait 0 wacht onbeperkt.
• gateway restart --safe --skip-deferral voert de OpenClaw-bewuste veilige herstart uit, maar omzeilt de uitstelpoort zodat de Gateway de herstart onmiddellijk uitstoot, zelfs wanneer blokkades worden gemeld. Nooduitgang voor operators bij vastgelopen taakrun-uitstel; vereist --safe.
• gateway restart --force slaat het leegmaken van actief werk over en start onmiddellijk opnieuw. Gebruik dit wanneer een operator de vermelde taakblokkades al heeft gecontroleerd en de gateway nu terug wil.
• Levenscyclusopdrachten accepteren --json voor scripting.

• Wanneer tokenauthenticatie een token vereist en gateway.auth.token door SecretRef wordt beheerd, valideert gateway install dat de SecretRef oplosbaar is, maar wordt het opgeloste token niet opgeslagen in service-omgevingsmetadata.
• Als tokenauthenticatie een token vereist en de geconfigureerde token-SecretRef niet oplosbaar is, mislukt de installatie gesloten in plaats van terugval-plattetekst op te slaan.
• Geef voor wachtwoordauthenticatie bij gateway run de voorkeur aan OPENCLAW_GATEWAY_PASSWORD, --password-file of een door SecretRef ondersteunde gateway.auth.password boven inline --password.
• In afgeleide authenticatiemodus versoepelt shell-only OPENCLAW_GATEWAY_PASSWORD de tokenvereisten voor installatie 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.