Probleemoplossing

Dit is het uitgebreide draaiboek. Begin eerst bij /help/problemen-oplossen voor de snelle triageflow.

Commandovolgorde

Voer de volgende opdrachten in deze volgorde uit:

openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

Signalen van een gezonde werking:

• openclaw gateway status toont Runtime: running, Connectivity probe: ok en een Capability: ...-regel.
• openclaw doctor meldt geen blokkerende configuratie- of serviceproblemen.
• openclaw channels status --probe toont de actuele transportstatus per account en, waar ondersteund, works of audit ok.

Na een update

Gebruik dit wanneer een update is voltooid, maar de Gateway niet actief is, kanalen leeg zijn of modelaanroepen mislukken met 401-fouten.

openclaw status --allopenclaw update status --jsonopenclaw gateway status --deepopenclaw doctor --fixopenclaw gateway restart

Let op:

• Update restart in openclaw status / openclaw status --all. Overdrachten die in behandeling zijn of zijn mislukt, bevatten de volgende opdracht die moet worden uitgevoerd.
• plugin load failed: dependency tree corrupted; run openclaw doctor --fix onder Kanalen: de kanaalconfiguratie bestaat nog, maar de Plugin-registratie is mislukt voordat het kanaal kon worden geladen.
• 401-fouten van de provider na herauthenticatie: openclaw doctor --fix controleert op verouderde OAuth-authenticatieschaduwen per agent en verwijdert oude kopieën, zodat alle agents het huidige gedeelde profiel gebruiken.

Gesplitste installaties en beveiliging tegen nieuwere configuraties

Gebruik dit wanneer een Gateway-service na een update onverwacht stopt, of wanneer uit de logboeken blijkt dat één openclaw-binair bestand ouder is dan de versie die openclaw.json voor het laatst heeft geschreven.

OpenClaw markeert configuratieschrijfbewerkingen met meta.lastTouchedVersion. Alleen-lezenopdrachten kunnen een configuratie inspecteren die door een nieuwere OpenClaw is geschreven, maar proces- en servicemutaties worden niet uitgevoerd vanuit een ouder binair bestand. Geblokkeerde acties: de Gateway-service starten, stoppen, herstarten of verwijderen, geforceerde herinstallatie van de service, het starten van de Gateway in servicemodus en het opschonen van de gateway --force-poort.

which openclawopenclaw --versionopenclaw gateway status --deepopenclaw config get meta.lastTouchedVersion

openclaw gateway install --forceopenclaw gateway restart

Protocolverschil na terugdraaien

Gebruik dit wanneer de logboeken na een downgrade of rollback protocol mismatch blijven weergeven. Er wordt een oudere Gateway uitgevoerd, maar een nieuwer lokaal clientproces probeert nog steeds opnieuw verbinding te maken met een protocolbereik dat de oudere Gateway niet ondersteunt.

openclaw --versionwhich -a openclawopenclaw gateway status --deepopenclaw doctor --deepopenclaw logs --follow

Let op:

• protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n> in de Gateway-logboeken.
• Established clients: in openclaw gateway status --deep of Gateway clients in openclaw doctor --deep: actieve TCP-clients die zijn verbonden met de Gateway-poort, met PID's en opdrachtregels wanneer het besturingssysteem dit toestaat.
• Een clientproces waarvan de opdrachtregel verwijst naar de nieuwere OpenClaw-installatie of wrapper waarvan je bent teruggegaan.

Oplossing:

1. Stop of herstart het verouderde OpenClaw-clientproces dat door gateway status --deep wordt weergegeven.
2. Herstart apps of wrappers waarin OpenClaw is ingebed: lokale dashboards, editors, appserverhelpers of langlopende openclaw logs --follow-shells.
3. Voer openclaw gateway status --deep of openclaw doctor --deep opnieuw uit en bevestig dat de PID van de verouderde client verdwenen is.

Zorg er niet voor dat een oudere Gateway een nieuwer, incompatibel protocol accepteert. Protocolverhogingen beschermen het communicatiecontract; herstel na een rollback is een probleem dat moet worden opgelost door processen en versies op te schonen.

Symlink van Skill overgeslagen wegens ontsnapping uit pad

Gebruik dit wanneer de logboeken het volgende bevatten:

Overgeslagen ontsnapt Skill-pad buiten de geconfigureerde hoofdmap: ... reason=symlink-escape

Elke hoofdmap voor Skills vormt een insluitingsgrens. Een symlink onder ~/.agents/skills, <workspace>/.agents/skills, <workspace>/skills of ~/.openclaw/skills wordt overgeslagen wanneer het werkelijke doel buiten die hoofdmap valt, tenzij het doel expliciet wordt vertrouwd.

Inspecteer de koppeling:

ls -l ~/.agents/skills/<name>realpath ~/.agents/skills/<name>openclaw config get skills.load

Als het doel opzettelijk is, configureer je zowel de directe hoofdmap voor Skills als het toegestane symlinkdoel:

{  skills: {    load: {      extraDirs: ["~/Projects/manager/skills"],      allowSymlinkTargets: ["~/Projects/manager/skills"],    },  },}

Start vervolgens een nieuwe sessie of wacht totdat de Skills-watcher is vernieuwd. Herstart de Gateway als het actieve proces van vóór de configuratiewijziging dateert.

Gebruik geen brede doelen zoals ~, / of een volledige gesynchroniseerde projectmap. Beperk allowSymlinkTargets tot de werkelijke hoofdmap voor Skills die vertrouwde SKILL.md-mappen bevat.

Als toepassen vanuit Skill Workshop ook moet schrijven via die vertrouwde, gesymlinkte paden voor werkruimte-Skills, schakel je skills.workshop.allowSymlinkTargetWrites in. Laat dit uitgeschakeld voor gedeelde hoofd­mappen voor Skills die alleen-lezen zijn.

Gerelateerd:

• Configuratie van Skills
• Configuratievoorbeelden

Anthropic 429: extra gebruik vereist voor lange context

Gebruik dit wanneer logboeken of fouten het volgende bevatten: HTTP 429: rate_limit_error: Extra usage is required for long context requests.

openclaw logs --followopenclaw models statusopenclaw config get agents.defaults.models

Let op:

• Het geselecteerde Anthropic-model is een algemeen beschikbaar Claude 4.x-model met ondersteuning voor 1M (Opus 4.6/4.7/4.8, Sonnet 4.6), of de modelconfiguratie bevat nog de verouderde params.context1m: true.
• De huidige Anthropic-referentie is niet geschikt voor gebruik met lange context.
• Aanvragen mislukken uitsluitend tijdens lange sessies of modeluitvoeringen waarvoor het 1M-contextpad nodig is.

Oplossingsopties:

Gerelateerd:

• Anthropic
• Tokengebruik en kosten
• Waarom zie ik HTTP 429 van Anthropic?

Geblokkeerde upstream-403-antwoorden

Gebruik dit wanneer een upstream-LLM-provider een algemene 403 retourneert, zoals Your request was blocked.

Ga er niet van uit dat dit altijd een OpenClaw-configuratieprobleem is. Het antwoord kan afkomstig zijn van een upstream-beveiligingslaag, zoals een CDN, WAF, botbeheerregel of reverse proxy vóór een OpenAI-compatibel eindpunt.

openclaw statusopenclaw gateway statusopenclaw logs --follow

Let op:

• Meerdere modellen van dezelfde provider mislukken op dezelfde manier.
• HTML of algemene beveiligingstekst in plaats van een normale API-fout van de provider.
• Beveiligingsgebeurtenissen aan de kant van de provider voor hetzelfde tijdstip van de aanvraag.
• Een minimale directe curl-test slaagt, terwijl normale aanvragen met een SDK-vorm mislukken.

Herstel eerst de filtering aan de kant van de provider wanneer het bewijs op een WAF/CDN-blokkering wijst. Geef de voorkeur aan een nauwkeurig afgebakende toestemmings- of overslaregel voor het API-pad dat OpenClaw gebruikt en schakel de beveiliging niet voor de hele site uit.

Gerelateerd:

• OpenAI-compatibele eindpunten
• Providerconfiguratie
• Logboeken

Lokale OpenAI-compatibele backend slaagt voor directe tests, maar agentuitvoeringen mislukken

Gebruik dit wanneer:

• curl ... /v1/models werkt.
• Minimale directe /v1/chat/completions-aanroepen werken.
• OpenClaw-modeluitvoeringen mislukken alleen tijdens normale agentbeurten.

curl http://127.0.0.1:1234/v1/modelscurl http://127.0.0.1:1234/v1/chat/completions \  -H 'content-type: application/json' \  -d '{"model":"<id>","messages":[{"role":"user","content":"hi"}],"stream":false}'openclaw infer model run --model <provider/model> --prompt "hi" --jsonopenclaw logs --follow

Let op:

• Directe minimale aanroepen slagen, maar OpenClaw-uitvoeringen mislukken alleen bij grotere prompts.
• model_not_found- of 404-fouten, hoewel directe /v1/chat/completions werkt met dezelfde kale model-id.
• Backendfouten over messages[].content die een tekenreeks verwacht.
• Onregelmatige incomplete turn detected ... stopReason=stop payloads=0-waarschuwingen met een OpenAI-compatibele lokale backend.
• Backendcrashes die alleen optreden bij grotere aantallen prompttokens of volledige prompts van de agentruntime.

Gerelateerd:

• Configuratie
• Lokale modellen
• OpenAI-compatibele eindpunten

Geen antwoorden

Als kanalen actief zijn maar niets antwoordt, controleer dan de routering en het beleid voordat je iets opnieuw verbindt.

openclaw statusopenclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw config get channelsopenclaw logs --follow

Let op:

• Koppeling in afwachting voor afzenders van privéberichten.
• Vermeldingsbeperking voor groepen (requireMention, mentionPatterns).
• Niet-overeenkomende toestemmingslijsten voor kanalen/groepen.

Veelvoorkomende meldingen:

• drop guild message (mention required → groepsbericht genegeerd tot er een vermelding is.
• pairing request → afzender moet worden goedgekeurd.
• blocked / allowlist → afzender/kanaal is door beleid gefilterd.

Gerelateerd:

• Problemen met kanalen oplossen
• Groepen
• Koppeling

Connectiviteit van het dashboard en de bedieningsinterface

Als het dashboard/de bedieningsinterface geen verbinding maakt, controleer dan de URL, verificatiemodus en aannames over de beveiligde context.

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --json

Let op:

• Juiste URL voor de test en het dashboard.
• Niet-overeenkomende verificatiemodus/token tussen client en Gateway.
• Gebruik van HTTP waar apparaatidentiteit vereist is.

Als een lokale browser na een update geen verbinding kan maken met 127.0.0.1:18789, herstel dan eerst de lokale Gateway-service en controleer of deze het dashboard aanbiedt:

openclaw gateway restartlsof -i :18789curl http://127.0.0.1:18789

Als curl OpenClaw-HTML retourneert, werkt de Gateway en is het resterende probleem waarschijnlijk de browsercache, een oude deeplink of verouderde tabbladstatus. Open http://127.0.0.1:18789 rechtstreeks en navigeer vanaf het dashboard. Als de service na een herstart niet actief blijft, voer dan openclaw gateway start uit en controleer openclaw gateway status opnieuw.

Sneloverzicht van detailcodes voor verificatie

Gebruik error.details.code uit het mislukte connect-antwoord om de volgende actie te kiezen:

Migratiecontrole voor apparaatverificatie v2:

openclaw --versionopenclaw doctoropenclaw gateway status

Als de logboeken nonce-/handtekeningfouten tonen, werk dan de verbindende client bij en controleer deze:

Als openclaw devices rotate / revoke / remove onverwacht wordt geweigerd:

• Tokensessies van gekoppelde apparaten kunnen alleen hun eigen apparaat beheren, tenzij de aanroeper ook operator.admin heeft.
• openclaw devices rotate --scope ... kan alleen operatorscopes aanvragen die de sessie van de aanroeper al heeft.

Gerelateerd:

• Configuratie (Gateway-verificatiemodi)
• Bedieningsinterface
• Apparaten
• Externe toegang
• Verificatie via vertrouwde proxy

Gateway-service is niet actief

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

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --deep   # scan ook services op systeemniveau

Let op:

• Runtime: stopped met aanwijzingen over het afsluiten.
• Niet-overeenkomende serviceconfiguratie (Config (cli) versus Config (service)).
• Conflicten met poort/listener.
• Extra installaties van launchd/systemd/schtasks wanneer --deep wordt gebruikt.
• Other gateway-like services detected (best effort)-aanwijzingen voor opschoning.

Gerelateerd:

• Uitvoering op de achtergrond en procestool
• Configuratie
• Doctor

macOS-Gateway reageert stilzwijgend niet meer en hervat wanneer je het dashboard aanraakt

Gebruik dit wanneer kanalen (Telegram, WhatsApp enz.) op een macOS-host telkens minuten tot uren stilvallen en de Gateway weer lijkt te werken zodra je de Control UI opent, via SSH verbinding maakt of anderszins interactie met de host hebt. In openclaw status is doorgaans geen duidelijk symptoom zichtbaar, omdat de Gateway alweer actief is tegen de tijd dat je kijkt.

ls ~/.openclaw/logs/stability/ | tail -5openclaw gateway stability --bundle latestpmset -g log | grep -iE "sleep|wake|maintenance" | tail -50launchctl print gui/$UID/ai.openclaw.gateway | grep -E "state|last exit|runs"

Let op:

• Een of meer *-uncaught_exception.json-bundels in ~/.openclaw/logs/stability/ waarbij error.code is ingesteld op een tijdelijke netwerkcode, zoals ENETDOWN, ENETUNREACH, EHOSTUNREACH of ECONNREFUSED.
• pmset -g log-regels zoals Entering Sleep state due to 'Maintenance Sleep' of en0 driver is slow (msg: WillChangeState to 0) die samenvallen met de tijdstempels van de crashes. Power Nap / Maintenance Sleep zet het wifi-stuurprogramma kort in status 0; elke uitgaande connect() die in dat tijdsvenster valt, kan mislukken met ENETDOWN, zelfs op een host die verder volledige netwerkconnectiviteit heeft.
• launchctl print-uitvoer die state = not running toont met meerdere recente runs en een afsluitcode, vooral wanneer het interval tussen de crash en de volgende start eerder ongeveer een uur dan enkele seconden bedraagt. macOS launchd past na een reeks crashes een ongedocumenteerde beveiliging tegen herhaald starten toe, waardoor KeepAlive=true mogelijk niet meer wordt gehonoreerd totdat een externe trigger, zoals een interactieve aanmelding, dashboardverbinding of launchctl kickstart, deze opnieuw activeert.

Veelvoorkomende kenmerken:

• Een stabiliteitsbundel waarvan error.code gelijk is aan ENETDOWN of een verwante code, waarbij de aanroepstack verwijst naar Node net lookupAndConnect / Socket.connect. OpenClaw 2026.5.26 en nieuwer classificeren deze als onschuldige tijdelijke netwerkfouten, zodat ze niet meer worden doorgegeven aan de niet-afgevangen handler op het hoogste niveau; werk je met een oudere release, voer dan eerst een upgrade uit.
• Lange stille perioden die onmiddellijk eindigen zodra je verbinding maakt met de Control UI of via SSH met de host: de voor de gebruiker zichtbare activiteit activeert launchd's beveiliging tegen herhaald starten opnieuw, niet iets wat het dashboard met de Gateway doet.
• Het aantal runs neemt gedurende de dag toe zonder bijbehorende received SIG*; shutting down-regel in ~/Library/Logs/openclaw/gateway.log: bij correct afsluiten wordt een signaal geregistreerd; bij tijdelijke crashes niet.

Wat je moet doen:

1. Voer een upgrade van de Gateway uit als je een release van vóór 2026.5.26 gebruikt. Na de upgrade worden toekomstige ENETDOWN-fouten als waarschuwingen geregistreerd in plaats van dat ze het proces beëindigen.

2. Beperk activiteit tijdens de onderhoudsslaapstand op Mac mini-/desktophosts die als permanent actieve servers moeten functioneren:

   sudo pmset -a sleep 0 disksleep 0 standby 0 powernap 0

   Dit vermindert de onderliggende uitval van het stuurprogramma aanzienlijk, maar voorkomt deze niet volledig. Het systeem kan ondanks deze vlaggen nog steeds bepaalde onderhoudsslaapstanden uitvoeren voor TCP-keepalive en mDNS-onderhoud.

3. Voeg een bewakingsproces voor beschikbaarheid toe, zodat een toekomstige reeks crashes die door launchd wordt geparkeerd snel wordt gedetecteerd:

   # Voorbeeld van een launchd-bewuste beschikbaarheidscontrole, geschikt voor een vijfminuten-Cron of LaunchAgentstate=$(launchctl print gui/$UID/ai.openclaw.gateway 2>/dev/null | awk -F'= ' '/state =/ {print $2; exit}')if [ "$state" != "running" ]; then  launchctl kickstart -k gui/$UID/ai.openclaw.gatewayfi

   Het doel is om de beveiliging tegen herhaald starten extern opnieuw te activeren; alleen KeepAlive=true is op macOS na een reeks crashes niet voldoende.

Gerelateerd:

• macOS-platformnotities
• Logboekregistratie
• Doctor

macOS launchd-supervisorlus met dubbele Gateway/Node-LaunchAgents

Gebruik dit wanneer een macOS-installatie om de paar seconden opnieuw wordt gestart, openclaw statuscontroles wisselen tussen beschikbaar en niet beschikbaar en de kanaalafhandeling vastloopt, ook al lijkt de service actief te zijn.

Dit is waargenomen bij oudere installaties waarbij zowel ai.openclaw.gateway als ai.openclaw.node LaunchAgents actief waren en beide OPENCLAW_LAUNCHD_LABEL invoegden. In die toestand kan OpenClaw launchd- supervisie detecteren, proberen het opnieuw starten weer aan launchd over te dragen en in een snelle EADDRINUSE-/herstartlus terechtkomen in plaats van één stabiel Gateway-proces.

for i in 1 2 3 4; do  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'  sleep 10done openclaw gateway status --deepopenclaw node statuslaunchctl print gui/$UID/ai.openclaw.gateway | grep -E 'state|last exit|runs'tail -n 80 ~/Library/Logs/openclaw/gateway.log

Let op:

• Meer dan één Gateway-PID tijdens de steekproef van 30 seconden in plaats van één stabiel proces.
• EADDRINUSE, another gateway instance is already listening of herhaalde regels over opnieuw starten/overdracht in gateway.log.
• Zowel ~/Library/LaunchAgents/ai.openclaw.gateway.plist als ~/Library/LaunchAgents/ai.openclaw.node.plist zijn tegelijkertijd geladen op een host waarop slechts één beheerde Gateway-service actief hoort te zijn.

Wat je moet doen:

1. Als op deze host alleen de Gateway-service actief hoort te zijn, verwijder je de beheerde Node- service via OpenClaw. Sla deze stap over als je de Node- service actief gebruikt voor functies van externe Nodes; als je deze verwijdert, stoppen die functies op deze host:

   openclaw node uninstall

2. Installeer een permanente Gateway-wrapper die de overgenomen launchd- markeringen wist voordat OpenClaw wordt gestart. Gebruik de ondersteunde optie --wrapper; bewerk het gegenereerde bestand onder ~/.openclaw/service-env/ niet, omdat dit bestand bij het opnieuw installeren of bijwerken van de service en bij herstel door Doctor opnieuw wordt gegenereerd:

   mkdir -p ~/.local/bincat >~/.local/bin/openclaw-launchd-workaround <<'EOF'#!/bin/shset -euunset OPENCLAW_LAUNCHD_LABEL LAUNCH_JOB_LABEL LAUNCH_JOB_NAME XPC_SERVICE_NAME || trueexec openclaw "$@"EOFchmod 700 ~/.local/bin/openclaw-launchd-workaround openclaw gateway install \  --wrapper ~/.local/bin/openclaw-launchd-workaround \  --force

   gateway install bewaart het wrapperpad bij gedwongen herinstallaties, updates en reparaties door Doctor.

3. Controleer of de Gateway stabiel is en RPC bedient, en niet alleen luistert:

   openclaw gateway status --deep --require-rpc for i in 1 2 3 4; do  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'  sleep 10done

   De PID-steekproef moet één stabiel proces tonen in plaats van een wisselende reeks PID's, en de afhandeling van inkomende kanalen moet worden hervat.

4. Verwijder na de upgrade naar een release waarin de onderliggende dubbele LaunchAgent-lus is opgelost de tijdelijke oplossing en installeer de normale beheerde service opnieuw:

   OPENCLAW_WRAPPER= openclaw gateway install --forcerm ~/.local/bin/openclaw-launchd-workaround

Gerelateerd:

• macOS-platformopmerkingen
• Doctor
• Gateway-CLI

Gateway wordt afgesloten bij hoog geheugengebruik

Gebruik dit wanneer de Gateway onder belasting verdwijnt, de supervisor een herstart in OOM-stijl meldt of de logs critical memory pressure bundle written vermelden.

openclaw gateway status --deepopenclaw logs --followopenclaw gateway stability --bundle latestopenclaw gateway diagnostics export

Let op:

• Reason: diagnostic.memory.pressure.critical in de nieuwste stabiliteitsbundel.
• Memory pressure: met critical/rss_threshold, critical/heap_threshold of critical/rss_growth.
• V8 heap:-waarden nabij de heaplimiet.
• Largest session files:-vermeldingen zoals agents/<agent>/sessions/<session>.jsonl of sessions/<session>.jsonl.
• Linux-cgroup-geheugentellers wanneer de Gateway in een container of service met een geheugenlimiet draait.

Veelvoorkomende signalen:

• critical memory pressure bundle written verschijnt kort vóór de herstart → OpenClaw heeft een stabiliteitsbundel van vóór de OOM vastgelegd. Inspecteer deze met openclaw gateway stability --bundle latest.
• memory pressure: level=critical verschijnt in de Gateway-logs → OpenClaw heeft kritieke geheugendruk gedetecteerd en de beschikbare geheugengegevens binnen het proces vastgelegd.
• Largest session files: verwijst naar een zeer groot geredigeerd transcriptpad → verklein de bewaarde sessiegeschiedenis, inspecteer de sessiegroei of verplaats oude transcripten uit de actieve opslag voordat je opnieuw opstart.
• V8 heap: gebruikte bytes liggen dicht bij de heaplimiet → verlaag eerst de prompt-/sessiedruk of verminder gelijktijdig werk. Inspecteer voor een beheerde service Gateway heap: in openclaw gateway status; als er not set staat, genereer je oude servicemetadata opnieuw met openclaw gateway install --force. NODE_OPTIONS uit de omringende shell wordt bewust genegeerd. Gebruik alleen een expliciete heap-override op supervisorniveau nadat je de aanhoudende werkbelasting hebt bevestigd en voldoende ruimte voor native geheugen hebt vrijgehouden.
• Memory pressure: critical/rss_growth → het geheugengebruik groeide snel binnen één meetvenster. Controleer de nieuwste logs op een grote import, uit de hand gelopen tooluitvoer, herhaalde nieuwe pogingen of een reeks in de wachtrij geplaatste agenttaken.
• Kritieke geheugendruk verschijnt in de logs, maar er bestaat geen bundel → leg na de gebeurtenis openclaw gateway diagnostics export vast voor het beschikbare operationele bewijs.

De stabiliteitsbundel bevat geen payloads. Deze bevat operationeel geheugenbewijs en geredigeerde relatieve bestandspaden, maar geen berichttekst, webhook-bodies, inloggegevens, tokens, cookies of onbewerkte sessie-id's. Voeg de diagnostische export toe aan bugrapporten in plaats van onbewerkte logs te kopiëren.

Gerelateerd:

• Gateway-status
• Diagnostische export
• Sessies

Gateway heeft ongeldige configuratie geweigerd

Gebruik dit wanneer het opstarten van de Gateway mislukt met Invalid config of wanneer hot-reloadlogs melden dat een ongeldige bewerking is overgeslagen.

openclaw logs --followopenclaw config fileopenclaw config validateopenclaw doctor

Let op:

• Invalid config at ...
• config reload skipped (invalid config): ...
• Config write rejected: ...
• Een van een tijdstempel voorzien openclaw.json.rejected.*-bestand naast de actieve configuratie.
• Een van een tijdstempel voorzien openclaw.json.clobbered.*-bestand als doctor --fix een defecte rechtstreekse bewerking heeft hersteld.
• OpenClaw bewaart voor elk configuratiepad de nieuwste 32 .clobbered.*-bestanden en roteert oudere bestanden.

CONFIG="$(openclaw config file)"ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | headdiff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"openclaw config validateopenclaw doctor

Gerelateerd:

• Configuratie
• Configuratie: dynamisch herladen
• Configuratie: strikte validatie
• Doctor

Waarschuwingen van de Gateway-probe

Gebruik dit wanneer openclaw gateway probe iets bereikt, maar nog steeds een waarschuwingsblok weergeeft.

openclaw gateway probeopenclaw gateway probe --jsonopenclaw gateway probe --ssh user@gateway-host

Let op:

• warnings[].code en primaryTargetId in de JSON-uitvoer.
• Of de waarschuwing gaat over SSH-terugval, meerdere gateways, ontbrekende bereiken of niet-opgeloste authenticatieverwijzingen.

Veelvoorkomende signalen:

• SSH tunnel failed to start; falling back to direct probes. → de SSH-configuratie is mislukt, maar de opdracht heeft nog steeds rechtstreeks geconfigureerde of loopbackdoelen geprobeerd.
• multiple reachable gateway identities detected → verschillende gateways hebben geantwoord, of OpenClaw kon niet bewijzen dat de bereikbare doelen dezelfde Gateway zijn. Een SSH-tunnel, proxy-URL of geconfigureerde externe URL naar dezelfde Gateway wordt behandeld als één Gateway met meerdere transportmethoden, zelfs wanneer de transportpoorten verschillen.
• Read-probe diagnostics are limited by gateway scopes (missing operator.read) → de verbinding werkte, maar de gedetailleerde RPC is beperkt door het bereik; koppel de apparaatidentiteit of gebruik aanmeldgegevens met operator.read.
• Gateway accepted the WebSocket connection, but follow-up read diagnostics failed → de verbinding werkte, maar de volledige set diagnostische RPC's heeft een time-out bereikt of is mislukt. Behandel dit als een bereikbare Gateway met beperkte diagnostiek; vergelijk connect.ok en connect.rpcOk in de uitvoer van --json.
• Capability: pairing-pending of gateway closed (1008): pairing required → de Gateway heeft geantwoord, maar deze client moet nog worden gekoppeld of goedgekeurd voordat normale beheerderstoegang mogelijk is.
• Niet-opgeloste waarschuwingstekst voor gateway.auth.* / gateway.remote.* SecretRef → authenticatiemateriaal was in dit opdrachtpad niet beschikbaar voor het mislukte doel.

Gerelateerd:

• Gateway
• Meerdere gateways op dezelfde host
• Externe toegang

Kanaal verbonden, berichten worden niet doorgegeven

Als de kanaalstatus verbonden is maar de berichtenstroom stilligt, richt je dan op beleid, machtigingen en kanaalspecifieke leveringsregels.

openclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw status --deepopenclaw logs --followopenclaw config get channels

Let op:

• DM-beleid (pairing, allowlist, open, disabled).
• Toestaanlijst voor groepen en vereisten voor vermeldingen.
• Ontbrekende API-machtigingen of bereiken voor het kanaal.

Veelvoorkomende signalen:

• mention required → bericht genegeerd door het beleid voor groepsvermeldingen.
• pairing / sporen van een wachtende goedkeuring → de afzender is niet goedgekeurd.
• missing_scope, not_in_channel, Forbidden, 401/403 → probleem met kanaalauthenticatie of -machtigingen.

Gerelateerd:

• Problemen met kanalen oplossen
• Discord
• Telegram
• WhatsApp

Levering via Cron en Heartbeat

Als Cron of Heartbeat niet is uitgevoerd of niets heeft geleverd, controleer dan eerst de plannerstatus en vervolgens het leveringsdoel.

openclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw system heartbeat lastopenclaw logs --follow

Let op:

• Cron is ingeschakeld en de volgende activering is aanwezig.
• Status van de uitvoeringsgeschiedenis van de taak (ok, skipped, error).
• Redenen voor het overslaan van Heartbeat (quiet-hours, requests-in-flight, cron-in-progress, lanes-busy, alerts-disabled, empty-heartbeat-file).

Gerelateerd:

• Heartbeat
• Geplande taken
• Geplande taken: problemen oplossen

Node gekoppeld, tool mislukt

Als een Node is gekoppeld maar tools mislukken, isoleer dan de status van de voorgrond, machtigingen en goedkeuringen.

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

Let op:

• Node is online met de verwachte mogelijkheden.
• OS-machtigingen voor camera, microfoon, locatie en scherm.
• Status van uitvoeringsgoedkeuringen en de toestaanlijst.

Veelvoorkomende signalen:

• NODE_BACKGROUND_UNAVAILABLE → de Node-app moet op de voorgrond staan.
• *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → ontbrekende OS-machtiging.
• SYSTEM_RUN_DENIED: approval required → uitvoeringsgoedkeuring in behandeling.
• SYSTEM_RUN_DENIED: allowlist miss → opdracht geblokkeerd door de toestaanlijst.

Gerelateerd:

• Uitvoeringsgoedkeuringen
• Problemen met Nodes oplossen
• Nodes

Browsertool mislukt

Gebruik dit wanneer acties van de browsertool mislukken, hoewel de Gateway zelf goed werkt.

openclaw browser statusopenclaw browser start --browser-profile openclawopenclaw browser profilesopenclaw logs --followopenclaw doctor

Let op:

• Of plugins.allow is ingesteld en browser bevat.
• Geldig pad naar het uitvoerbare browserbestand.
• Bereikbaarheid van het CDP-profiel.
• Beschikbaarheid van lokale Chrome voor profielen van existing-session / user.

Gerelateerd:

• Browser (beheerd door OpenClaw)
• Browserproblemen oplossen

Als je een upgrade hebt uitgevoerd en er plotseling iets niet meer werkt

De meeste problemen na een upgrade worden veroorzaakt door configuratieafwijkingen of doordat strengere standaardinstellingen nu worden afgedwongen.

openclaw gateway statusopenclaw config get gateway.modeopenclaw config get gateway.remote.urlopenclaw config get gateway.auth.mode

openclaw config get gateway.bindopenclaw config get gateway.auth.modeopenclaw config get gateway.auth.tokenopenclaw gateway statusopenclaw logs --follow

openclaw devices listopenclaw pairing list --channel <channel> [--account <id>]openclaw logs --followopenclaw doctor

Als de serviceconfiguratie en runtime na de controles nog steeds niet overeenkomen, installeer je de servicemetadata opnieuw vanuit dezelfde profiel-/statusmap:

openclaw gateway install --forceopenclaw gateway restart

Gerelateerd:

• Authenticatie
• Uitvoering op de achtergrond en procestool
• Node-koppeling

Gerelateerd

• Doctor
• Veelgestelde vragen
• Gateway-draaiboek