Naar hoofdinhoud gaan

​
Gateway service runbook

Gebruik deze pagina voor dag-1 opstart en dag-2 operaties van de Gateway-service.

Deep troubleshooting

Symptoomgerichte diagnose met exacte commandolijsten en logsignaturen.

Configuration

Taakgerichte installatiegids + volledige configuratiereferentie.

​
5-minuten lokale opstart

1

Start the Gateway

openclaw gateway --port 18789
# for full debug/trace logs in stdio:
openclaw gateway --port 18789 --verbose
# if the port is busy, terminate listeners then start:
openclaw gateway --force
# dev loop (auto-reload on TS changes):
pnpm gateway:watch
2

Verify service health

Linux: `openclaw-gateway-<profile>.service`
Gezonde basis: Runtime: running en RPC probe: ok.
3

Validate channel readiness

openclaw channels status --probe
Gateway-configuratieherladen bewaakt het actieve configuratiebestandspad (opgelost vanuit profiel-/statusstandaarden, of OPENCLAW_CONFIG_PATH wanneer ingesteld). Standaardmodus: gateway.reload.mode="hybrid" (pas veilige wijzigingen hot toe, herstart bij kritisch).

​
Runtime-model

  • Het always-on proces dat de enkele Baileys/Telegram-verbinding en het control-/eventplane beheert.
  • Single-port multiplex.
    • WebSocket control/RPC
    • OpenResponses (HTTP): /v1/responses.
    • Control-UI en hooks
  • Standaard bindmodus: loopback.
  • Gateway-authenticatie is standaard vereist: stel gateway.auth.token (of OPENCLAW_GATEWAY_TOKEN) of gateway.auth.password in.

​
Poort- en bindprioriteit

InstellingVolgorde van resolutie
Gateway-poortPoortprecedentie: --port > OPENCLAW_GATEWAY_PORT > gateway.port > standaard 18789.
BindmodusCLI/override → gateway.bind → loopback

​
Hot-reloadmodi

Uitschakelen met gateway.reload.mode="off".Keepalive-gedrag
offGeen config-herladen
hotPas alleen hot-veilige wijzigingen toe
restartHerstart bij wijzigingen die een herstart vereisen
hybrid (standaard)Hot-toepassen indien veilig, herstarten indien vereist

​
Operator-commandoverzameling

openclaw gateway status
openclaw gateway install
openclaw gateway stop
openclaw gateway restart
openclaw logs --follow

​
Externe toegang

Tailscale/VPN heeft de voorkeur; anders een SSH-tunnel: Fallback: SSH-tunnel. 
ssh -N -L 18789:127.0.0.1:18789 user@host
Clients verbinden vervolgens met ws://127.0.0.1:18789 via de tunnel.
Als een token is geconfigureerd, moeten clients dit opnemen in connect.params.auth.token, zelfs over de tunnel.
Zie: Remote Gateway, Authentication, Tailscale.

​
Supervisie en servicelifecycle

Gebruik supervised runs voor productie-achtige betrouwbaarheid. 
openclaw --profile main gateway install
openclaw --profile rescue gateway install
OpenClaw.app kan een Node-gebaseerde gateway-relay bundelen en een per-gebruiker LaunchAgent installeren met label bot.molt.gateway (of bot.molt.<profile> ; legacy com.openclaw.*-labels worden nog netjes unloaded).(benoemd profiel).openclaw doctor` controleert en herstelt configuratie-afwijkingen van de service.

​
Meerdere gateways (zelfde host)

Meestal onnodig: één Gateway kan meerdere messagingkanalen en agents bedienen. Gebruik meerdere Gateways alleen voor redundantie of strikte isolatie (bijv. rescue bot). Checklist per instantie:
  • unieke gateway.port
  • unieke OPENCLAW_CONFIG_PATH
  • unieke OPENCLAW_STATE_DIR
  • unieke agents.defaults.workspace
Voorbeeld: 
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002
Zie Multiple gateways.

​
Dev-profiel (--dev)

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
# then target the dev instance:
openclaw --dev status
openclaw --dev health
Standaardinstellingen omvatten een geïsoleerde state/configuratie en basis gateway-poort 19001.

​
Protocol (operatorperspectief)

  • Het eerste clientframe moet connect zijn.
  • Gateway retourneert een hello-ok-snapshot (presence, health, stateVersion, uptimeMs, limieten/beleid).
  • Requests: {type:"req", id, method, params} → {type:"res", id, ok, payload|error}
  • Veelvoorkomende events: connect.challenge, agent, chat, presence, tick, health, heartbeat, shutdown.
Agent-runs bestaan uit twee fasen:
  1. Onmiddellijke accepted-ack (status:"accepted")
  2. agent-responses zijn tweefasig: eerst res ack {runId,status:"accepted"}, daarna een finale res {runId,status:"ok"|"error",summary} nadat de run is voltooid; gestreamde uitvoer arriveert als event:"agent".
Volledige documentatie: Gateway protocol en Bridge protocol (legacy).

​
Operationele controles

​
Liveness

  • Open WS en verstuur connect.
  • Verwacht een hello-ok-antwoord met snapshot.

​
Gereedheid

`openclaw gateway health|status` — vraag health/status op via de Gateway WS.

​
Gap-herstel

Events worden niet herhaald. Bij sequentiegaten, vernieuw de state (health, system-presence) voordat je doorgaat.

​
Veelvoorkomende foutsignaturen

SignatuurWaarschijnlijk probleem
refusing to bind gateway ... without authNon-loopback binding zonder token/wachtwoord
another gateway instance is already listening / EADDRINUSEPoortconflict
Gateway start blocked: set gateway.mode=localConfiguratie ingesteld op remote-modus
unauthorized tijdens connectAuthenticatie-mismatch tussen client en Gateway
Gebruik voor volledige diagnose-stappenplannen Gateway Troubleshooting.

​
Veiligheidsgaranties

  • Gateway-protocolclients falen direct wanneer Gateway niet beschikbaar is (geen impliciete direct-channel fallback).
  • Niet-connect first frames of malformed JSON worden geweigerd en de socket wordt gesloten.
  • Graceful shutdown: zend shutdown-event vóór sluiten; clients moeten sluiten + opnieuw verbinden afhandelen.
Gerelateerd: