Gateway-draaiboek

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

Lokale opstart in 5 minuten

openclaw gateway --port 18789# debug/trace mirrored to stdioopenclaw gateway --port 18789 --verbose# force-kill listener on selected port, then startopenclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

Runtimemodel

• Eén altijd actief proces voor routering, control plane en kanaalverbindingen.
• Eén gemultiplexte poort voor:
  • WebSocket-besturing/RPC
  • HTTP-API's (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • Plugin-HTTP-routes, zoals optioneel /api/v1/admin/rpc
  • Control-UI en hooks
• Standaard bindmodus: loopback.
• Auth is standaard vereist. Installaties met gedeelde geheimen gebruiken gateway.auth.token / gateway.auth.password (of OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD), en niet-loopback reverse-proxy-installaties kunnen gateway.auth.mode: "trusted-proxy" gebruiken.

OpenAI-compatibele eindpunten

OpenClaw's compatibiliteitsoppervlak met de hoogste hefboomwerking is nu:

• GET /v1/models
• GET /v1/models/{id}
• POST /v1/embeddings
• POST /v1/chat/completions
• POST /v1/responses

Waarom deze set belangrijk is:

• De meeste Open WebUI-, LobeChat- en LibreChat-integraties proben eerst /v1/models.
• Veel RAG- en geheugenpijplijnen verwachten /v1/embeddings.
• Agent-native clients geven steeds vaker de voorkeur aan /v1/responses.

Planningsnotitie:

• /v1/models is agent-first: het retourneert openclaw, openclaw/default en openclaw/<agentId>.
• openclaw/default is de stabiele alias die altijd verwijst naar de geconfigureerde standaardagent.
• Gebruik x-openclaw-model wanneer je een backend-provider/model-override wilt; anders blijft de normale model- en embeddingconfiguratie van de geselecteerde agent leidend.

Al deze werken op de hoofdpoort van de Gateway en gebruiken dezelfde vertrouwde operator-authgrens als de rest van de Gateway-HTTP-API.

Admin-HTTP-RPC (POST /api/v1/admin/rpc) is een afzonderlijke, standaard uitgeschakelde Plugin-route voor hosttools die geen WebSocket-RPC kunnen gebruiken. Zie Admin-HTTP-RPC.

Poort- en bindvolgorde

Geïnstalleerde gatewayservices registreren de opgeloste --port in supervisormetadata. Voer na het wijzigen van gateway.port openclaw doctor --fix of openclaw gateway install --force uit zodat launchd/systemd/schtasks het proces op de nieuwe poort start.

Gateway-opstart gebruikt dezelfde effectieve poort en bind wanneer lokale Control-UI-origins voor niet-loopback-binds worden gezaaid. Bijvoorbeeld: --bind lan --port 3000 zaait http://localhost:3000 en http://127.0.0.1:3000 voordat runtime validatie wordt uitgevoerd. Voeg eventuele remote browser-origins, zoals HTTPS-proxy-URL's, expliciet toe aan gateway.controlUi.allowedOrigins.

Hot-reloadmodi

Commandoset voor operators

openclaw gateway statusopenclaw gateway status --deep   # adds a system-level service scanopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

gateway status --deep is bedoeld voor extra servicedetectie (LaunchDaemons/systemd-systeem units/schtasks), niet voor een diepere RPC-statusprobe.

Meerdere gateways (dezelfde host)

De meeste installaties zouden één Gateway per machine moeten draaien. Eén Gateway kan meerdere agents en kanalen hosten.

Je hebt alleen meerdere gateways nodig wanneer je bewust isolatie of een rescue-bot wilt.

Nuttige controles:

openclaw gateway status --deepopenclaw gateway probe

Wat je kunt verwachten:

• gateway status --deep kan Other gateway-like services detected (best effort) rapporteren en opschoontips tonen wanneer verouderde launchd/systemd/schtasks-installaties nog aanwezig zijn.
• gateway probe kan waarschuwen voor multiple reachable gateway identities wanneer afzonderlijke gateways antwoorden, of wanneer OpenClaw niet kan bewijzen dat bereikbare doelen dezelfde Gateway zijn. Een SSH-tunnel, proxy-URL of geconfigureerde remote URL naar dezelfde Gateway is één Gateway met meerdere transports, zelfs wanneer transportpoorten verschillen.
• Als dat bewust is, isoleer dan poorten, configuratie/status en werkruimteroots per Gateway.

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 19001OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002

Gedetailleerde installatie: /gateway/multiple-gateways.

Externe toegang

Voorkeur: Tailscale/VPN. Terugval: SSH-tunnel.

ssh -N -L 18789:127.0.0.1:18789 user@host

Verbind clients daarna lokaal met ws://127.0.0.1:18789.

Zie: Remote Gateway, Authenticatie, Tailscale.

Supervisie en servicelevenscyclus

Gebruik gesuperviseerde runs voor productieachtige betrouwbaarheid.

openclaw gateway installopenclaw gateway statusopenclaw gateway restartopenclaw gateway stop

openclaw gateway installsystemctl --user enable --now openclaw-gateway[-<profile>].serviceopenclaw gateway status

sudo loginctl enable-linger <user>

[Unit]Description=OpenClaw GatewayAfter=network-online.targetWants=network-online.target [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5TimeoutStopSec=30TimeoutStartSec=30SuccessExitStatus=0 143OOMPolicy=continueKillMode=control-group [Install]WantedBy=default.target

openclaw gateway installopenclaw gateway status --jsonopenclaw gateway restartopenclaw gateway stop

sudo systemctl daemon-reloadsudo systemctl enable --now openclaw-gateway[-<profile>].service

Snel pad voor dev-profiel

openclaw --dev setupopenclaw --dev gateway --allow-unconfiguredopenclaw --dev status

Standaarden omvatten geïsoleerde status/configuratie en basis-Gateway-poort 19001.

Snelle protocolreferentie (operatorweergave)

• Het eerste clientframe moet connect zijn.
• Gateway retourneert hello-ok-snapshot (presence, health, stateVersion, uptimeMs, limieten/beleid).
• hello-ok.features.methods / events zijn een conservatieve detectielijst, geen gegenereerde dump van elke aanroepbare helperroute.
• Verzoeken: req(method, params) → res(ok/payload|error).
• Veelvoorkomende events zijn connect.challenge, agent, chat, session.message, session.operation, session.tool, sessions.changed, presence, tick, health, heartbeat, pairing-/approval-levenscyclusevents en shutdown.

Agentruns verlopen in twee fasen:

1. Directe geaccepteerde ack (status:"accepted")
2. Uiteindelijke voltooiingsrespons (status:"ok"|"error"), met gestreamde agent-events ertussen.

Zie de volledige protocoldocumentatie: Gateway-protocol.

Operationele controles

Liveness

• Open WS en verzend connect.
• Verwacht een hello-ok-respons met snapshot.

Readiness

openclaw gateway statusopenclaw channels status --probeopenclaw health

Hiaatherstel

Events worden niet opnieuw afgespeeld. Vernieuw bij sequentiegaten de status (health, system-presence) voordat je verdergaat.

Veelvoorkomende foutsignaturen

Gebruik Gateway-probleemoplossing voor volledige diagnosestappen.

Veiligheidsgaranties

• Gateway-protocolclients falen snel wanneer Gateway niet beschikbaar is (geen impliciete fallback naar direct kanaal).
• Ongeldige/niet-verbindingsgerichte eerste frames worden geweigerd en gesloten.
• Netjes afsluiten verzendt de shutdown-gebeurtenis voordat de socket wordt gesloten.

Gerelateerd:

• Probleemoplossing
• Achtergrondproces
• Configuratie
• Gezondheid
• Doctor
• Authenticatie

Gerelateerd

• Configuratie
• Gateway-probleemoplossing
• Externe toegang
• Geheimenbeheer