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 stdio
openclaw gateway --port 18789 --verbose
# force-kill listener on selected port, then start
openclaw gateway --force

openclaw gateway status
openclaw status
openclaw 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, OpenAI-compatibel (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • Besturings-UI en hooks
• Standaard bindmodus: loopback.
• Auth is standaard vereist. Setups met gedeeld geheim gebruiken gateway.auth.token / gateway.auth.password (of OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD), en niet-loopback reverse-proxy-setups kunnen gateway.auth.mode: "trusted-proxy" gebruiken.

# OpenAI-compatibele eindpunten

OpenClaw's compatibiliteitsoppervlak met de hoogste impact 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.

Planningsopmerking:

• /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 override voor backendprovider/model wilt; anders blijft de normale model- en embeddingsetup van de geselecteerde agent leidend.

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

# 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 het lokale oorsprongen voor de besturings-UI seedt voor niet-loopback binds. Bijvoorbeeld: --bind lan --port 3000 seedt http://localhost:3000 en http://127.0.0.1:3000 voordat runtime- validatie wordt uitgevoerd. Voeg externe browseroorsprongen, zoals HTTPS-proxy-URL's, expliciet toe aan gateway.controlUi.allowedOrigins.

# Hot-reloadmodi

# Operatorset met commando's

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 system units/schtasks), niet voor een diepere RPC-gezondheidsprobe.

# Meerdere gateways (zelfde 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 opruimhints afdrukken wanneer verouderde launchd/systemd/schtasks-installaties nog aanwezig zijn.
• gateway probe kan waarschuwen voor multiple reachable gateways wanneer meer dan één doel antwoordt.
• Als dat de bedoeling is, isoleer dan poorten, configuratie/status en workspace-roots 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 setup: /gateway/multiple-gateways.

# Externe toegang

Voorkeur: Tailscale/VPN. Fallback: 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: Externe Gateway, Authenticatie, Tailscale.

# Supervisie en servicelevenscyclus

Gebruik gesuperviseerde runs voor productieachtige betrouwbaarheid.

openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

openclaw gateway install
systemctl --user enable --now openclaw-gateway[-<profile>].service
openclaw gateway status

sudo loginctl enable-linger <user>

[Unit]
Description=OpenClaw Gateway
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
TimeoutStopSec=30
TimeoutStartSec=30
SuccessExitStatus=0 143
KillMode=control-group

[Install]
WantedBy=default.target

openclaw gateway install
openclaw gateway status --json
openclaw gateway restart
openclaw gateway stop

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

# Snel pad voor dev-profiel

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status

Standaarden omvatten geïsoleerde status/configuratie en basisgatewaypoort 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, niet een gegenereerde dump van elke aanroepbare helperroute.
• Verzoeken: req(method, params) → res(ok/payload|error).
• Veelvoorkomende events omvatten connect.challenge, agent, chat, session.message, session.tool, sessions.changed, presence, tick, health, heartbeat, lifecycle-events voor pairing/approval en shutdown.

Agentruns verlopen in twee fasen:

1. Direct geaccepteerde ack (status:"accepted")
2. Eindrespons bij voltooiing (status:"ok"|"error"), met gestreamde agent-events ertussen.

Zie volledige protocoldocumentatie: Gateway-protocol.

# Operationele controles

# Liveness

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

# Readiness

openclaw gateway status
openclaw channels status --probe
openclaw health

# Gap-herstel

Events worden niet opnieuw afgespeeld. Vernieuw bij sequence gaps de status (health, system-presence) voordat je doorgaat.

# Veelvoorkomende foutsignaturen

Gebruik Gateway-probleemoplossing voor volledige diagnosereeksen.

# Veiligheidsgaranties

• Gateway-protocolclients falen snel wanneer Gateway niet beschikbaar is (geen impliciete fallback naar een direct kanaal).
• Ongeldige eerste frames of eerste frames zonder connect worden geweigerd en gesloten.
• Gecontroleerd afsluiten zendt de shutdown-gebeurtenis uit voordat de socket wordt gesloten.

Gerelateerd:

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

# Gerelateerd

• Configuratie
• Gateway-probleemoplossing
• Externe toegang
• Geheimenbeheer