Gateway-runbook

Gebruik deze pagina voor het opstarten op dag 1 en het beheer vanaf dag 2 van de Gateway-service.

Lokale opstart in 5 minuten

openclaw gateway --port 18789# debug/trace gespiegeld naar stdioopenclaw gateway --port 18789 --verbose# beëindig geforceerd de listener op de geselecteerde poort en start vervolgensopenclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

Runtimemodel

• Eén permanent actief proces voor routering, het besturingsvlak en kanaalverbindingen.
• Eén gemultiplexte poort voor:
  • WebSocket-besturing/RPC
  • HTTP-API's (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • HTTP-routes van Plugins, zoals de optionele /api/v1/admin/rpc
  • Bedieningsinterface en hooks
• Standaardbindingsmodus: loopback. Binnen een gedetecteerde containeromgeving is de effectieve standaardwaarde auto (wordt omgezet naar 0.0.0.0 voor port forwarding), tenzij Tailscale serve/funnel actief is; dat dwingt altijd loopback af.
• Authenticatie is standaard vereist. Configuraties met een gedeeld geheim gebruiken gateway.auth.token / gateway.auth.password (of OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD) en reverse-proxyconfiguraties buiten loopback kunnen gateway.auth.mode: "trusted-proxy" gebruiken.

OpenAI-compatibele eindpunten

Het compatibiliteitsoppervlak met de grootste impact van OpenClaw:

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

Waarom deze verzameling belangrijk is:

• De meeste integraties met Open WebUI, LobeChat en LibreChat controleren eerst /v1/models.
• Veel RAG- en geheugenpijplijnen verwachten /v1/embeddings.
• Clients die specifiek voor agents zijn ontworpen, geven steeds vaker de voorkeur aan /v1/responses.

/v1/models is primair voor agents: het retourneert openclaw, openclaw/default en openclaw/<agentId> voor elke geconfigureerde agent. openclaw/default is de stabiele alias die altijd naar de geconfigureerde standaardagent verwijst. Stuur x-openclaw-model wanneer je een andere backendprovider of een ander model wilt gebruiken; anders blijven het normale model en de embeddingconfiguratie van de geselecteerde agent leidend.

Al deze eindpunten draaien op de hoofdpoort van de Gateway en gebruiken dezelfde vertrouwde authenticatiegrens voor operators als de rest van de HTTP-API van de Gateway.

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

Prioriteit van poort en binding

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

Bij het opstarten gebruikt de Gateway dezelfde effectieve poort en binding wanneer lokale oorsprongen voor de bedieningsinterface worden ingesteld voor bindingen buiten loopback. Zo stelt --bind lan --port 3000 bijvoorbeeld http://localhost:3000 en http://127.0.0.1:3000 in voordat de runtimevalidatie wordt uitgevoerd. Voeg oorsprongen voor externe browsers, zoals HTTPS-proxy-URL's, expliciet toe aan gateway.controlUi.allowedOrigins.

Modi voor direct herladen

Opdrachtenset voor operators

openclaw gateway statusopenclaw gateway status --deep   # voegt een servicecontrole op systeemniveau toeopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

gateway status --deep is bedoeld voor aanvullende servicedetectie (LaunchDaemons/systemd-systeemeenheden/schtasks), niet voor een diepgaandere RPC-statuscontrole.

Meerdere gateways (dezelfde host)

Voor de meeste installaties moet één gateway per machine worden uitgevoerd. Eén gateway kan meerdere agents en kanalen hosten. Je hebt alleen meerdere gateways nodig wanneer je bewust isolatie of een reddingsbot wilt.

Nuttige controles:

openclaw gateway status --deepopenclaw gateway probe

Wat je kunt verwachten:

• gateway status --deep kan Other gateway-like services detected (best effort) melden en opschoningstips weergeven wanneer verouderde installaties van launchd/systemd/schtasks nog aanwezig zijn.
• gateway probe kan waarschuwen voor multiple reachable gateway identities wanneer verschillende gateways antwoorden, of wanneer OpenClaw niet kan aantonen dat bereikbare doelen dezelfde gateway zijn. Een SSH-tunnel, proxy-URL of geconfigureerde externe URL naar dezelfde gateway is één gateway met meerdere transportmethoden, zelfs wanneer de transportpoorten verschillen.
• Als dit de bedoeling is, isoleer dan de poorten, configuratie/status en werkmaphoofdmappen per gateway.

Controlelijst 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 configuratie: /gateway/multiple-gateways.

Externe toegang

Aanbevolen: Tailscale/VPN. Alternatief: SSH-tunnel.

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

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

Zie: Externe Gateway, Authenticatie, Tailscale.

Supervisie en servicelevenscyclus

Gebruik uitvoeringen onder supervisie voor productiewaardige 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 $(whoami)

[Unit]Description=OpenClaw GatewayAfter=network-online.targetWants=network-online.targetStartLimitBurst=5StartLimitIntervalSec=60 [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5RestartPreventExitStatus=78TimeoutStopSec=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

Bij fouten door een ongeldige configuratie wordt het proces afgesloten met code 78. Linux-systemd-eenheden gebruiken RestartPreventExitStatus=78 om te stoppen met opnieuw starten totdat de configuratie is hersteld. launchd en Windows Task Scheduler hebben geen gelijkwaardige stopregel per afsluitcode. Daarom bewaart de Gateway ook de geschiedenis van snelle, onjuiste opstartpogingen en onderdrukt deze het automatisch starten van kanaal-/provideraccounts na herhaalde opstartfouten. In die veilige modus start het besturingsvlak nog steeds voor inspectie en herstel, weigeren directe herlaadbewerkingen van de configuratie en secrets.reload het automatisch opnieuw starten van kanalen, en kan een expliciet channels.start-verzoek van een operator de onderdrukking opheffen.

Snel pad voor ontwikkelprofiel

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

Standaardwaarden omvatten geïsoleerde status/configuratie en Gateway-basispoort 19001.

Beknopt protocoloverzicht (operatorperspectief)

• Het eerste clientframe moet connect zijn.
• De Gateway retourneert een hello-ok-frame met een snapshot (presence, health, stateVersion, uptimeMs) plus policy-limieten (maxPayload, maxBufferedBytes, tickIntervalMs).
• hello-ok.features.methods / events vormen een conservatieve lijst voor detectie, niet een gegenereerde dump van elke aanroepbare hulproute.
• Verzoeken: req(method, params) → res(ok/payload|error).
• Veelvoorkomende gebeurtenissen zijn onder meer connect.challenge, agent, chat, session.message, session.operation, session.tool, optionele session.approval, sessions.changed, presence, tick, health, heartbeat, levenscyclusgebeurtenissen voor koppeling/goedkeuring en shutdown.

Agentuitvoeringen bestaan uit twee fasen:

1. Onmiddellijke bevestiging van acceptatie (status:"accepted")
2. Definitief voltooiingsantwoord (status:"ok"|"error"), met tussendoor gestreamde agent-gebeurtenissen.

Zie de volledige protocoldocumentatie: Gateway-protocol.

Operationele controles

Beschikbaarheid

• Open WS en verzend connect.
• Verwacht een hello-ok-antwoord met momentopname.

Gereedheid

openclaw gateway statusopenclaw channels status --probeopenclaw health

Herstel na hiaten

Gebeurtenissen worden niet opnieuw afgespeeld. Vernieuw bij hiaten in de reeks de status (health, system-presence) voordat je doorgaat.

Veelvoorkomende foutsignaturen

Gebruik Problemen met de Gateway oplossen voor volledige diagnosestappen.

Veiligheidsgaranties

• Clients van het Gateway-protocol stoppen onmiddellijk met een fout wanneer de Gateway niet beschikbaar is (geen impliciete terugval naar een rechtstreeks kanaal).
• Ongeldige eerste frames of eerste frames die geen verbindingsframes zijn, worden geweigerd en gesloten.
• Bij correct afsluiten wordt vóór het sluiten van de socket een shutdown-gebeurtenis verzonden.

Gerelateerd

• Configuratie
• Problemen met de Gateway oplossen
• Achtergrondproces
• Status
• Doctor
• Authenticatie
• Externe toegang
• Geheimenbeheer