Skip to main content

​
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

2

Verify service health

Gezonde basis: Runtime: running en RPC probe: ok.
3

Validate channel readiness

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

​
Hot-reloadmodi

​
Operator-commandoverzameling

​
Externe toegang

Tailscale/VPN heeft de voorkeur; anders een SSH-tunnel: Fallback: SSH-tunnel.
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.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:
Zie Multiple gateways.

​
Dev-profiel (--dev)

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

​
Gap-herstel

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

​
Veelvoorkomende foutsignaturen

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: