Gateway

• Weigert te starten tenzij gateway.mode=local is ingesteld in ~/.openclaw/openclaw.json. Gebruik --allow-unconfigured voor ad-hoc-/ontwikkeluitvoeringen; dit omzeilt de beveiliging zonder configuratie te schrijven of te repareren.
• Wanneer bij het opstarten een herstelbare ongeldige configuratie wordt gevonden, biedt een interactieve terminal aan om openclaw doctor --fix uit te voeren en wordt na toestemming eenmaal opnieuw geprobeerd op te starten. Niet-interactieve uitvoeringen repareren nooit automatisch; ze tonen in plaats daarvan de opdracht. Als de gerepareerde configuratie nog steeds ongeldig is, blijft het opstarten geblokkeerd.
• openclaw onboard --mode local en openclaw setup schrijven gateway.mode=local. Als het configuratiebestand bestaat maar gateway.mode ontbreekt, wordt dit behandeld als een beschadigde/overschreven configuratie en weigert de Gateway local voor je te raden — voer de onboarding opnieuw uit, stel de sleutel handmatig in of geef --allow-unconfigured door.
• Binden buiten loopback zonder authenticatie wordt geblokkeerd.
• --bind-waarden lan, tailnet en custom worden momenteel via uitsluitend-IPv4-paden omgezet; uitsluitend-IPv6-configuraties met een eigen host vereisen een IPv4-sidecar of proxy vóór de Gateway.
• SIGUSR1 activeert na autorisatie een herstart binnen het proces. commands.restart (standaard: ingeschakeld) regelt extern verzonden SIGUSR1; stel dit in op false om handmatige herstarts via besturingssysteemsignalen te blokkeren. De agentgerichte tool gateway is alleen-lezen; agents vragen een herstart aan via de door een mens goedgekeurde delegatietool openclaw.
• SIGINT/SIGTERM stoppen het proces, maar herstellen geen aangepaste terminalstatus — als je de CLI in een TUI of invoer in raw-modus verpakt, herstel je de terminal zelf vóór het afsluiten.

• Records bewaren operationele metagegevens: gebeurtenisnamen, aantallen, bytegroottes, geheugenmetingen, wachtrij-/sessiestatus, goedkeurings-id's, kanaal-/pluginnamen en geredigeerde sessiesamenvattingen. Ze sluiten chattekst, Webhook-bodies, tooluitvoer, onbewerkte request-/response-bodies, tokens, cookies, geheime waarden, hostnamen en onbewerkte sessie-id's uit. Stel diagnostics.enabled: false in om de recorder volledig uit te schakelen.
• Fatale Gateway-afsluitingen, time-outs bij het afsluiten en opstartfouten na een herstart schrijven dezelfde diagnostische momentopname naar ~/.openclaw/logs/stability/openclaw-stability-*.json wanneer de recorder gebeurtenissen bevat. Inspecteer de nieuwste bundel met openclaw gateway stability --bundle latest; --limit, --type en --since-seq zijn ook van toepassing op bundeluitvoer.

• Blijft beschikbaar voor diagnostiek, zelfs wanneer de lokale CLI-configuratie ontbreekt of ongeldig is.
• De standaarduitvoer bewijst de servicestatus, WebSocket-verbinding en de authenticatiecapaciteit die tijdens de handshake zichtbaar is — niet lees-/schrijf-/beheerbewerkingen.
• Probes wijzigen niets voor de eerste apparaatauthenticatie: ze hergebruiken een bestaand gecachet apparaattoken wanneer dat bestaat, maar maken nooit een nieuwe CLI-apparaatidentiteit of alleen-lezen-koppelingsrecord aan uitsluitend om de status te controleren.
• Lost geconfigureerde SecretRefs voor probe-authenticatie waar mogelijk op. Als een vereiste SecretRef niet is opgelost, rapporteert --json rpc.authWarning wanneer de probe voor verbinding/authenticatie mislukt; geef --token/--password expliciet door of herstel de geheime bron. Waarschuwingen over niet-opgeloste authenticatie worden onderdrukt zodra de probe slaagt.
• JSON-uitvoer bevat gateway.version wanneer de actieve Gateway dit rapporteert; --require-rpc kan terugvallen op de RPC-payload status.runtimeVersion als de handshakeprobe geen versiemetagegevens kan leveren.
• Gebruik --require-rpc in scripts/automatisering wanneer een luisterende service niet voldoende is en RPC met leesbereik ook gezond moet zijn.
• --deep scant op extra installaties van launchd/systemd/schtasks; wanneer meerdere Gateway-achtige services worden gevonden, drukt de voor mensen leesbare uitvoer opschoontips af (voer doorgaans één Gateway per machine uit) en rapporteert deze indien relevant een recente overdracht bij een herstart door de supervisor.
• --deep voert ook configuratievalidatie uit in pluginbewuste modus (pluginValidation: "full") en toont waarschuwingen uit pluginmanifesten (bijvoorbeeld ontbrekende metagegevens voor kanaalconfiguratie). De standaardwaarde gateway status behoudt het snelle alleen-lezen-pad dat pluginvalidatie overslaat.
• De voor mensen leesbare uitvoer bevat het opgeloste pad van het bestandslogboek, plus de configuratiepaden en geldigheid van CLI versus service, om afwijkingen in het profiel of de statusmap te helpen diagnosticeren.
• De voor mensen leesbare uitvoer bevat Gateway heap: met de toegepaste limiet en de adaptieve afleiding daarvan. JSON-uitvoer stelt hetzelfde rapport beschikbaar als service.gatewayHeap.

• Controles op afwijkingen in service-authenticatie lezen zowel Environment= als EnvironmentFile= uit de unit (inclusief %h, paden tussen aanhalingstekens, meerdere bestanden en optionele --bestanden).
• Lost gateway.auth.token-SecretRefs op met behulp van de samengevoegde runtime-omgeving (eerst de omgeving van de serviceopdracht, daarna als terugval de procesomgeving).
• Controles op tokenafwijkingen slaan het oplossen van het configuratietoken over wanneer tokenauthenticatie niet daadwerkelijk actief is (gateway.auth.mode expliciet password/none/trusted-proxy, of wanneer de modus niet is ingesteld en het wachtwoord kan prevaleren en geen tokenkandidaat kan prevaleren).

• 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 authenticatie kon bewijzen, los van de bereikbaarheid.
• Read probe: ok betekent dat RPC-detailaanroepen 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 een volledige mislukking.
• Read probe: failed na Connect: ok betekent dat de WebSocket verbinding heeft gemaakt, maar dat daaropvolgende leesdiagnostiek een time-out kreeg of mislukte — eveneens verminderd, niet onbereikbaar.
• Net als gateway status hergebruikt de probe bestaande gecachete apparaatauthenticatie, maar maakt deze geen apparaatidentiteit of koppelingsstatus voor het eerste gebruik aan.
• De afsluitcode is alleen niet-nul wanneer geen enkel geprobed doel bereikbaar is.

Hoofdniveau:

• ok: ten minste één doel is bereikbaar.
• degraded: ten minste één doel heeft een verbinding geaccepteerd, maar heeft de volledige gedetailleerde RPC-diagnostiek niet voltooid.
• capability: beste mogelijkheid die voor alle bereikbare doelen is waargenomen (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, lokale loopback.
• warnings[]: waarschuwingsrecords op basis van beste inspanning met code, message, optioneel targetIds.
• network: hints voor lokale loopback-/tailnet-URL's, afgeleid van de huidige configuratie en het hostnetwerk.
• discovery.timeoutMs / discovery.count: het daadwerkelijk gebruikte detectiebudget/aantal resultaten voor deze proberonde.

Per doel (targets[].connect): ok (bereikbaarheid + classificatie als gedegradeerd), rpcOk (volledig geslaagde gedetailleerde RPC), scopeLimited (gedetailleerde RPC mislukt door ontbrekend operatorbereik).

Per doel (targets[].auth): role en scopes gerapporteerd in hello-ok wanneer beschikbaar, plus de weergegeven classificatie capability.

• ssh_tunnel_failed: het instellen van de SSH-tunnel is mislukt; de opdracht is teruggevallen op directe probes.
• multiple_gateways: verschillende Gateway-identiteiten waren bereikbaar, of OpenClaw kon niet aantonen dat de bereikbare doelen dezelfde Gateway zijn. Een SSH-tunnel, proxy-URL of geconfigureerde externe URL naar dezelfde Gateway activeert dit niet.
• auth_secretref_unresolved: een geconfigureerde SecretRef voor authenticatie kon voor een mislukt doel niet worden omgezet.
• probe_scope_limited: de WebSocket-verbinding is geslaagd, maar de leesprobe werd beperkt door ontbrekende operator.read.
• local_tls_runtime_unavailable: TLS voor de lokale Gateway is ingeschakeld, maar OpenClaw kon de vingerafdruk van het lokale certificaat niet laden.

• gateway status: --url, --token, --password, --timeout, --no-probe, --require-rpc, --deep, --json
• gateway install: --port, --runtime <node> (standaard: 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 is idempotent: wanneer de beheerde service al actief is, rapporteert de opdracht het actieve proces en laat dit ongemoeid. Een geladen maar gestopte service wordt zoals voorheen gestart.
• Gebruik gateway restart om een beheerde service opnieuw te starten. Koppel gateway stop en gateway start niet aan elkaar als vervanging voor opnieuw starten.
• In een niet-interactieve shell vereist gateway stop de optie --force. Interactieve terminals behouden het bestaande gedrag zonder prompt. Geef voor automatisering en tests de voorkeur aan gateway run --dev of een geïsoleerde --profile met een vrije poort.
• Op macOS gebruikt gateway stop standaard launchctl bootout, waarmee de LaunchAgent uit de huidige opstartsessie wordt verwijderd zonder een uitschakeling permanent te bewaren — automatisch herstel via KeepAlive blijft actief voor toekomstige crashes en gateway start schakelt de service weer correct in zonder een handmatige launchctl enable. Geef --disable door om KeepAlive en RunAtLoad permanent te onderdrukken, zodat de Gateway pas opnieuw wordt gestart na de volgende expliciete gateway start; gebruik dit wanneer een handmatige stop ook na opnieuw opstarten van het systeem moet blijven gelden.
• Mutaties in de Gateway-levenscyclus voegen op basis van beste inspanning auditrecords met sleutel-waardeparen toe aan <state-dir>/logs/gateway-restart.log, waaronder start-, stop- en herstartbewerkingen via de CLI, veilige herstartverzoeken, herstarts door de supervisor en losgekoppelde overdrachten.
• Levenscyclusopdrachten accepteren --json voor scripts.

• gateway install schrijft een uitsluitend voor de heap bestemde waarde voor NODE_OPTIONS voor de beheerde Gateway-service. De waarde richt zich op 50% van het beperkte geheugen wanneer Node een container- of servicelimiet rapporteert, en anders op 50% van het fysieke geheugen.
• Het nominale doelbereik is 2048–8192 MiB, met een aanvullende limiet die 75% ruimte voor native geheugen vrijhoudt. Op kleine hosts kan deze limiet ervoor zorgen dat de toegepaste limiet onder de nominale ondergrens van 2048 MiB ligt.
• Een geldige expliciete --max-old-space-size die al in de geïnstalleerde service is opgeslagen, blijft behouden bij gedwongen herinstallaties en reparaties door doctor. Andere NODE_OPTIONS-vlaggen worden niet overgenomen in de beheerde service.
• NODE_OPTIONS uit de omringende shell overschrijft dit beleid niet. Gebruik gateway status of doctor om de geïnstalleerde waarde te inspecteren; voer openclaw gateway install --force uit om oudere servicemetadata zonder beheerde heapinstelling opnieuw te genereren.
• Het beleid geldt alleen voor de beheerde Gateway-service. gateway run op de voorgrond, Node-services en handmatig geschreven supervisoreenheden behouden hun eigen runtimeconfiguratie.

• Wanneer tokenauthenticatie een token vereist en gateway.auth.token door SecretRef wordt beheerd, controleert gateway install of de SecretRef kan worden omgezet, maar wordt het omgezette token niet opgeslagen in de omgevingsmetadata van de service.
• Als tokenauthenticatie een token vereist en de geconfigureerde SecretRef voor het token niet kan worden omgezet, wordt de installatie veilig geblokkeerd in plaats van terug te vallen op het opslaan van platte tekst.
• Geef voor wachtwoordauthenticatie op gateway run de voorkeur aan OPENCLAW_GATEWAY_PASSWORD, --password-file of een door SecretRef ondersteunde gateway.auth.password boven een inline --password.
• In de afgeleide authenticatiemodus versoepelt OPENCLAW_GATEWAY_PASSWORD die alleen in de shell is ingesteld de tokenvereisten voor installatie niet; gebruik duurzame configuratie (gateway.auth.password of configuratie-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 de installatie geblokkeerd totdat de modus expliciet is ingesteld.