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

Diepgaande probleemoplossing

Symptoomgerichte diagnostiek met exacte commandoreeksen en logsignaturen.

Configuratie

Taakgerichte installatiehandleiding + volledige configuratiereferentie.

Geheimenbeheer

SecretRef-contract, gedrag van runtimesnapshots en migratie-/herlaadbewerkingen.

Contract voor geheimenplan

Exacte doel-/padregels voor secrets apply en ref-only auth-profielgedrag.

​
Lokale opstart in 5 minuten

1

Start de Gateway

openclaw gateway --port 18789
# debug/trace mirrored to stdio
openclaw gateway --port 18789 --verbose
# force-kill listener on selected port, then start
openclaw gateway --force
2

Controleer de servicestatus

openclaw gateway status
openclaw status
openclaw logs --follow
Gezonde basislijn: Runtime: running, Connectivity probe: ok en Capability: ... dat overeenkomt met wat je verwacht. Gebruik openclaw gateway status --require-rpc wanneer je RPC-bewijs met leesbereik nodig hebt, niet alleen bereikbaarheid.
3

Valideer kanaalgereedheid

openclaw channels status --probe
Met een bereikbare Gateway voert dit live kanaalprobes per account en optionele audits uit. Als de Gateway onbereikbaar is, valt de CLI terug op alleen-configuratie-kanaalsamenvattingen in plaats van live probe-uitvoer.
Gateway-configuratieherlaad kijkt naar het actieve configuratiebestandspad (opgelost vanuit profiel-/statusstandaarden, of OPENCLAW_CONFIG_PATH wanneer ingesteld). De standaardmodus is gateway.reload.mode="hybrid". Na de eerste succesvolle laadactie bedient het draaiende proces de actieve in-memory configuratiesnapshot; een succesvolle herlaadactie wisselt die snapshot atomair om.

​
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

InstellingOplossingsvolgorde
Gateway-poort--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
BindmodusCLI/override → gateway.bind → loopback
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

gateway.reload.modeGedrag
offGeen configuratieherlaad
hotAlleen hot-safe wijzigingen toepassen
restartHerstarten bij wijzigingen die herstart vereisen
hybrid (standaard)Hot toepassen wanneer veilig, herstarten wanneer vereist

​
Commandoset voor operators

openclaw gateway status
openclaw gateway status --deep   # adds a system-level service scan
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw 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 --deep
openclaw 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 19001
OPENCLAW_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.
SSH-tunnels omzeilen Gateway-auth niet. Voor auth met gedeelde geheimen moeten clients nog steeds token/password verzenden, ook via de tunnel. Voor modi met identiteit moet het verzoek nog steeds aan dat auth-pad voldoen.
Zie: Remote Gateway, Authenticatie, Tailscale.

​
Supervisie en servicelevenscyclus

Gebruik gesuperviseerde runs voor productieachtige betrouwbaarheid. 
openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop
Gebruik openclaw gateway restart voor herstarts. Koppel openclaw gateway stop en openclaw gateway start niet als vervanging voor een herstart.Op macOS gebruikt gateway stop standaard launchctl bootout — dit verwijdert de LaunchAgent uit de huidige bootsessie zonder een uitschakeling persistent te maken, zodat KeepAlive-autoherstel nog steeds werkt na onverwachte crashes en gateway start netjes opnieuw inschakelt. Geef --disable mee om automatische respawn persistent te onderdrukken over herstarts heen: openclaw gateway stop --disable.LaunchAgent-labels zijn ai.openclaw.gateway (standaard) of ai.openclaw.<profile> (benoemd profiel). openclaw doctor audit en repareert drift in serviceconfiguratie.

​
Snel pad voor dev-profiel

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --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 status
openclaw channels status --probe
openclaw health

​
Hiaatherstel

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

​
Veelvoorkomende foutsignaturen

HandtekeningWaarschijnlijk probleem
refusing to bind gateway ... without authNon-loopback-binding zonder geldig gateway-auth-pad
another gateway instance is already listening / EADDRINUSEPoortconflict
Gateway start blocked: set gateway.mode=localConfiguratie staat op externe modus, of local-mode-stempel ontbreekt in beschadigde configuratie
unauthorized during connectAuth-mismatch tussen client en Gateway
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:

​
Gerelateerd