Community translations by veiseule.ai — Help improve them on Crowdin
Skip to main content

Gateway-problemen oplossen

Deze pagina is het diepe runbook. Begin bij /help/troubleshooting als je eerst de snelle triageflow wilt.

Commandoladder

Voer deze eerst uit, in deze volgorde:

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

Verwachte gezonde signalen:

  • openclaw gateway status toont Runtime: running en RPC probe: ok.
  • openclaw doctor meldt geen blokkerende config-/serviceproblemen.
  • openclaw channels status --probe toont verbonden/gereedstaande kanalen.

Geen antwoorden

Als kanalen actief zijn maar niets antwoordt, controleer routing en beleid voordat je iets opnieuw verbindt.

openclaw status
openclaw channels status --probe
openclaw pairing list <channel>
openclaw config get channels
openclaw logs --follow

Let op:

  • Koppeling in afwachting voor DM-afzenders.
  • Groepsvermelding-gating (requireMention, mentionPatterns).
  • Mismatches in kanaal-/groeps-toegestane lijst.

Veelvoorkomende signalen:

  • drop guild message (mention required → groepsbericht genegeerd tot vermelding.
  • pairing request → afzender heeft goedkeuring nodig.
  • blocked / allowlist → afzender/kanaal gefilterd door beleid.

Gerelateerd:

Dashboard/control UI-connectiviteit

Wanneer de dashboard/control UI niet wil verbinden, valideer URL, auth-modus en aannames over een veilige context.

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --json

Let op:

  • Juiste probe-URL en dashboard-URL.
  • Mismatch in auth-modus/token tussen client en gateway.
  • Gebruik van HTTP waar apparaatidentiteit vereist is.

Veelvoorkomende signalen:

  • device identity required → niet-veilige context of ontbrekende apparaatauthenticatie.
  • unauthorized / reconnect-lus → token-/wachtwoordmismatch.
  • gateway connect failed: → verkeerde host/poort/URL-doel.

Gerelateerd:

Gateway-service draait niet

Gebruik dit wanneer de service is geïnstalleerd maar het proces niet actief blijft.

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep

Let op:

  • Runtime: stopped met exit-hints.
  • Serviceconfig-mismatch (Config (cli) vs Config (service)).
  • Poort-/listenerconflicten.

Veelvoorkomende signalen:

  • Gateway start blocked: set gateway.mode=local → lokale gateway-modus is niet ingeschakeld.
  • refusing to bind gateway ... without auth → niet-loopback binding zonder token/wachtwoord.
  • another gateway instance is already listening / EADDRINUSE → poortconflict.

Gerelateerd:

Kanaal verbonden maar berichten stromen niet

Als de kanaalstatus verbonden is maar de berichtstroom dood is, focus op beleid, rechten en kanaalspecifieke leveringsregels.

openclaw channels status --probe
openclaw pairing list <channel>
openclaw status --deep
openclaw logs --follow
openclaw config get channels

Let op:

  • DM-beleid (pairing, allowlist, open, disabled).
  • Groeps-toegestane lijst en vereisten voor vermeldingen.
  • Ontbrekende kanaal-API-rechten/scopes.

Veelvoorkomende signalen:

  • mention required → bericht genegeerd door groepsvermeldingsbeleid.
  • pairing / sporen van goedkeuring in afwachting → afzender is niet goedgekeurd.
  • missing_scope, not_in_channel, Forbidden, 401/403 → kanaal-auth/rechtenprobleem.

Gerelateerd:

Cron- en heartbeat-levering

Als cron of heartbeat niet heeft gedraaid of niet is afgeleverd, verifieer eerst de schedulerstatus en daarna het afleverdoel.

openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow

Let op:

  • Cron ingeschakeld en volgende wekmoment aanwezig.
  • Status van job-uitvoergeschiedenis (ok, skipped, error).
  • Redenen voor het overslaan van heartbeats (quiet-hours, requests-in-flight, alerts-disabled).

Veelvoorkomende signalen:

  • cron: scheduler disabled; jobs will not run automatically → cron uitgeschakeld.
  • cron: timer tick failed → scheduler-tick mislukt; controleer bestand-/log-/runtimefouten.
  • heartbeat skipped met reason=quiet-hours → buiten het venster voor actieve uren.
  • heartbeat: unknown accountId → ongeldig account-id voor het afleverdoel van de heartbeat.

Gerelateerd:

Node gekoppeld maar tool faalt

Als een node is gekoppeld maar tools falen, isoleer voorgrondstatus, rechten en goedkeuringsstatus.

openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow
openclaw status

Let op:

  • Node online met de verwachte capabilities.
  • OS-rechten voor camera/microfoon/locatie/scherm.
  • Uitvoeringsgoedkeuringen en status van de toegestane lijst.

Veelvoorkomende signalen:

  • NODE_BACKGROUND_UNAVAILABLE → node-app moet op de voorgrond staan.
  • *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → ontbrekende OS-rechten.
  • SYSTEM_RUN_DENIED: approval required → uitvoeringsgoedkeuring in afwachting.
  • SYSTEM_RUN_DENIED: allowlist miss → opdracht geblokkeerd door toegestane lijst.

Gerelateerd:

Browsertool faalt

Gebruik dit wanneer browsertool-acties falen terwijl de gateway zelf gezond is.

openclaw browser status
openclaw browser start --browser-profile openclaw
openclaw browser profiles
openclaw logs --follow
openclaw doctor

Let op:

  • Geldig pad naar het browser-executable.
  • Bereikbaarheid van het CDP-profiel.
  • Bijlage van het extensierelay-tabblad voor profile="chrome".

Veelvoorkomende signalen:

  • Failed to start Chrome CDP on port → browserproces kon niet worden gestart.
  • browser.executablePath not found → geconfigureerd pad is ongeldig.
  • Chrome extension relay is running, but no tab is connected → extensierelay niet gekoppeld.
  • Browser attachOnly is enabled ... not reachable → profiel met alleen koppelen heeft geen bereikbaar doel.

Gerelateerd:

Als je hebt geüpgraded en er plotseling iets is stukgegaan

De meeste problemen na een upgrade zijn config-drift of strengere standaardwaarden die nu worden afgedwongen.

1. Auth- en URL-overridegedrag is gewijzigd

openclaw gateway status
openclaw config get gateway.mode
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode

Wat te controleren:

  • Als gateway.mode=remote, kunnen CLI-aanroepen op remote gericht zijn terwijl je lokale service in orde is.
  • Expliciete --url-aanroepen vallen niet terug op opgeslagen referenties.

Veelvoorkomende signalen:

  • gateway connect failed: → verkeerd URL-doel.
  • unauthorized → endpoint bereikbaar maar verkeerde auth.

2. Bind- en auth-guardrails zijn strenger

openclaw config get gateway.bind
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow

Wat te controleren:

  • Niet-loopback bindings (lan, tailnet, custom) vereisen geconfigureerde auth.
  • Oude sleutels zoals gateway.token vervangen gateway.auth.token niet.

Veelvoorkomende signalen:

  • refusing to bind gateway ... without auth → bind+auth-mismatch.
  • RPC probe: failed terwijl de runtime draait → gateway leeft maar is ontoegankelijk met de huidige auth/URL.

3. Koppeling en apparaatidentiteitsstatus zijn gewijzigd

openclaw devices list
openclaw pairing list <channel>
openclaw logs --follow
openclaw doctor

Wat te controleren:

  • Apparaatgoedkeuringen in afwachting voor dashboard/nodes.
  • DM-koppelingsgoedkeuringen in afwachting na beleids- of identiteitswijzigingen.

Veelvoorkomende signalen:

  • device identity required → apparaatauthenticatie niet voldaan.
  • pairing required → afzender/apparaat moet worden goedgekeurd.

Als serviceconfig en runtime na controles nog steeds niet overeenkomen, installeer service-metadata opnieuw vanuit dezelfde profiel-/statusdirectory:

openclaw gateway install --force
openclaw gateway restart

Gerelateerd:

veiseule.ai — Community translations maintained by John Kelly. Improve translations on Crowdin.