Gateway

• Standaard weigert de Gateway te starten tenzij gateway.mode=local is ingesteld in ~/.openclaw/openclaw.json. Gebruik --allow-unconfigured voor ad-hoc-/dev-uitvoeringen.
• 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 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".
• Binding buiten loopback zonder auth wordt geblokkeerd (veiligheidsvangrail).
• lan, tailnet en custom worden momenteel via IPv4-only BYOH-paden opgelost.
• IPv6-only BYOH wordt vandaag niet native ondersteund op dit pad. Gebruik een IPv4-sidecar of proxy als de host zelf IPv6-only is.
• SIGUSR1 triggert een herstart binnen het proces wanneer geautoriseerd (commands.restart is standaard ingeschakeld; stel commands.restart: false in om handmatige herstart te blokkeren, terwijl gateway-tool/config apply/update toegestaan blijven).
• SIGINT/SIGTERM-handlers stoppen het gateway-proces, maar herstellen geen aangepaste terminalstatus. Als je de CLI met een TUI of raw-mode-invoer omwikkelt, herstel de terminal dan vóór afsluiten.

• Records bewaren operationele metadata: gebeurtenisnamen, aantallen, bytegroottes, geheugenmetingen, queue-/sessiestatus, approval-id's, kanaal-/plug-innamen 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, afsluit-timeouts en opstartherstartfouten schrijft OpenClaw dezelfde diagnostische snapshot naar ~/.openclaw/logs/stability/openclaw-stability-*.json wanneer de recorder gebeurtenissen 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 bewijst gateway status de servicestatus, WebSocket-verbinding en de auth-mogelijkheid die zichtbaar is tijdens de handshake. Het bewijst geen lees-/schrijf-/adminbewerkingen.
• Diagnostische probes wijzigen niets voor eerste apparaatauth: 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 auth-SecretRefs voor probe-auth op wanneer mogelijk.
• Als een vereiste auth-SecretRef in dit opdrachtpad niet is opgelost, rapporteert gateway status --json rpc.authWarning wanneer probe-connectiviteit/auth mislukt; geef --token/--password expliciet door of los eerst de geheime bron op.
• Als de probe slaagt, worden waarschuwingen over onopgeloste auth-verwijzingen onderdrukt om fout-positieven te vermijden.
• Wanneer proben is ingeschakeld, bevat JSON-uitvoer gateway.version wanneer de actieve Gateway dit rapporteert; --require-rpc kan terugvallen op de RPC-payload status.runtimeVersion als de vervolghandshakeprobe geen versiemetadata kan leveren.
• Gebruik --require-rpc in scripts en automatisering wanneer een luisterende service niet genoeg is en je ook gezonde RPC-aanroepen met leesbereik nodig hebt.
• --deep voegt een best-effort scan toe voor extra launchd/systemd/schtasks-installaties. Wanneer meerdere gateway-achtige services worden gedetecteerd, drukt menselijke uitvoer opruimtips af en waarschuwt dat de meeste setups éé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 Plugin-manifestwaarschuwingen (bijvoorbeeld ontbrekende metadata voor kanaalconfiguratie), zodat smokechecks voor installatie en updates ze opvangen. Standaard gateway status houdt het snelle alleen-lezen pad dat Plugin-validatie overslaat.
• Menselijke uitvoer bevat het opgeloste bestandslogpad plus de snapshot van CLI-versus-serviceconfiguratiepaden/-geldigheid om profiel- of state-dir-afwijking te helpen diagnosticeren.

• Op Linux-systemd-installaties lezen controles op service-auth-afwijking zowel Environment=- als EnvironmentFile=-waarden uit de unit (inclusief %h, gequote paden, meerdere bestanden en optionele --bestanden).
• Afwijkingscontroles lossen gateway.auth.token SecretRefs op met de samengevoegde runtime-env (eerst serviceopdracht-env, daarna process-env als fallback).
• Als token-auth niet effectief actief is (expliciete gateway.auth.mode van password/none/trusted-proxy, of mode niet ingesteld waarbij wachtwoord kan winnen en geen tokenkandidaat kan winnen), slaan token-afwijkingscontroles het oplossen van de configuratietoken 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 kon bewijzen over auth. 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 geslaagd, maar RPC met leesbereik beperkt is. Dit wordt gerapporteerd als gedegradeerde 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 gedegradeerde bereikbaarheid, geen onbereikbare Gateway.
• Net als gateway status hergebruikt probe bestaande gecachete apparaatauth, maar maakt geen eerste apparaatidentiteit of koppelingsstatus aan.
• De afsluitcode is alleen niet-nul wanneer geen geprobed doel bereikbaar is.

Bovenste niveau:

• ok: ten minste één doel is bereikbaar.
• degraded: ten minste één doel accepteerde een verbinding maar voltooide niet de volledige detail-RPC-diagnostiek.
• capability: beste mogelijkheid 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, geconfigureerd extern doel, daarna local loopback.
• warnings[]: best-effort waarschuwingsrecords met code, message en optioneel targetIds.
• network: local loopback-/tailnet-URL-hints afgeleid van huidige configuratie en hostnetwerk.
• discovery.timeoutMs en discovery.count: het werkelijke discovery-budget/resultaantal dat voor deze probe-pass is gebruikt.

Per doel (targets[].connect):

• ok: bereikbaarheid na verbinden + gedegradeerde classificatie.
• rpcOk: volledige detail-RPC gelukt.
• scopeLimited: detail-RPC mislukt door ontbrekend operatorbereik.

Per doel (targets[].auth):

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

• ssh_tunnel_failed: instellen van SSH-tunnel mislukt; de opdracht viel terug op directe probes.
• multiple_gateways: afzonderlijke gateway-identiteiten waren bereikbaar, of OpenClaw kon niet bewijzen dat bereikbare doelen dezelfde gateway zijn. Een SSH-tunnel, proxy-URL of geconfigureerde externe URL naar dezelfde gateway triggert deze waarschuwing niet.
• 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. Keten gateway stop en gateway start niet als vervanging voor een herstart.
• Op macOS gebruikt gateway stop standaard launchctl bootout, waarmee de LaunchAgent uit de huidige bootsessie wordt verwijderd zonder een uitschakeling permanent te maken — automatisch herstel via KeepAlive blijft actief voor toekomstige crashes en gateway start schakelt weer schoon in zonder handmatige launchctl enable. Geef --disable door om KeepAlive en RunAtLoad permanent te onderdrukken, zodat de gateway niet opnieuw opstart tot de volgende expliciete gateway start; gebruik dit wanneer een handmatige stop herstarts of systeemherstarts moet overleven.
• gateway restart --safe vraagt de actieve Gateway om actief werk vooraf te controleren en één samengevoegde herstart te plannen nadat actief werk is leeggemaakt. De standaard veilige herstart wacht op actief werk tot de geconfigureerde gateway.reload.deferralTimeoutMs (standaard 5 minuten); wanneer dat budget verloopt, wordt de herstart geforceerd. Stel gateway.reload.deferralTimeoutMs in op 0 voor onbeperkt veilig wachten dat nooit forceert. --safe kan niet worden gecombineerd met --force of --wait.
• gateway restart --wait 30s overschrijft het geconfigureerde drainbudget voor die herstart. Losse 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 uitzendt, zelfs wanneer blokkades worden gemeld. Dit is een ontsnappingsroute voor operators bij vastgelopen uitstel van taakuitvoeringen; vereist --safe.
• gateway restart --force slaat het leegmaken 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 hebben.
• 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 bewaart het opgeloste token niet in metadata van de serviceomgeving.
• Als tokenauthenticatie een token vereist en de geconfigureerde token-SecretRef niet is opgelost, mislukt de installatie gesloten in plaats van terug te vallen op platte tekst.
• Voor wachtwoordauthenticatie bij gateway run geef je de voorkeur aan OPENCLAW_GATEWAY_PASSWORD, --password-file of een door SecretRef ondersteunde gateway.auth.password boven inline --password.
• In afgeleide authenticatiemodus versoepelt alleen-shell OPENCLAW_GATEWAY_PASSWORD de tokenvereisten voor installatie niet; gebruik duurzame configuratie (gateway.auth.password of config env) wanneer je een beheerde service installeert.
• 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.