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

Diepgaande probleemoplossing

Symptoomgerichte diagnostiek met exacte commandoreeksen en logkenmerken.

Configuratie

Taakgerichte installatiehandleiding + volledige configuratiereferentie.

Beheer van geheimen

SecretRef-contract, gedrag van runtime-snapshots en migratie-/herlaadbewerkingen.

Contract voor geheimenplan

Exacte secrets apply-regels voor doel/pad en gedrag van alleen-verwijzingen voor authenticatieprofielen.

​
Lokale opstart in 5 minuten

1

Start de Gateway

2

Controleer de servicestatus

Gezonde uitgangssituatie: Runtime: running, Connectivity probe: ok en een Capability-regel die overeenkomt met wat je verwacht. Gebruik openclaw gateway status --require-rpc als RPC-bewijs voor leesbereik, niet alleen voor bereikbaarheid.
3

Valideer de gereedheid van kanalen

Met een bereikbare gateway voert dit live kanaalcontroles per account en optionele audits uit. Als de gateway onbereikbaar is, valt de CLI terug op kanaaloverzichten die alleen op de configuratie zijn gebaseerd.
Het herladen van de Gateway-configuratie bewaakt het pad van het actieve configuratiebestand (afgeleid van de standaardwaarden voor profiel/status, of OPENCLAW_CONFIG_PATH wanneer dit is ingesteld). De standaardmodus is gateway.reload.mode="hybrid". Na de eerste geslaagde laadbewerking gebruikt het actieve proces de actieve configuratiesnapshot in het geheugen; bij een geslaagde herlaadbewerking wordt die snapshot atomair vervangen.

​
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

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

​
Externe toegang

Aanbevolen: Tailscale/VPN. Alternatief: SSH-tunnel.
Verbind clients vervolgens lokaal met ws://127.0.0.1:18789.
SSH-tunnels omzeilen de gatewayauthenticatie niet. Voor authenticatie met een gedeeld geheim moeten clients zelfs via de tunnel nog steeds token/password verzenden. Voor modi die een identiteit bevatten, moet het verzoek nog steeds aan dat authenticatiepad voldoen.
Zie: Externe Gateway, Authenticatie, Tailscale.

​
Supervisie en servicelevenscyclus

Gebruik uitvoeringen onder supervisie voor productiewaardige betrouwbaarheid.
Gebruik openclaw gateway restart om opnieuw te starten. Koppel openclaw gateway stop en openclaw gateway start niet aan elkaar als vervanging voor opnieuw starten.Op macOS gebruikt gateway stop standaard launchctl bootout. Hierdoor wordt de LaunchAgent uit de huidige opstartsessie verwijderd zonder deze permanent uit te schakelen, zodat automatisch herstel via KeepAlive na onverwachte crashes blijft werken en gateway start deze correct opnieuw inschakelt. Geef --disable door om automatisch opnieuw starten na een herstart permanent te onderdrukken: openclaw gateway stop --disable.LaunchAgent-labels zijn ai.openclaw.gateway (standaard) of ai.openclaw.<profile> (benoemd profiel). openclaw doctor controleert en herstelt afwijkingen in de serviceconfiguratie.
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

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

​
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