OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Start here

Algemene probleemoplossing

Ingang voor triage. Binnen 2 minuten een diagnose, ga daarna naar de verdiepende pagina.

Eerste 60 seconden

Voer deze reeks in de aangegeven volgorde uit:

bash
openclaw statusopenclaw status --allopenclaw gateway probeopenclaw gateway statusopenclaw doctoropenclaw channels status --probeopenclaw logs --follow

Goede uitvoer, één regel per opdracht:

  • openclaw status toont geconfigureerde kanalen zonder authenticatiefouten.
  • openclaw status --all produceert een volledig, deelbaar rapport.
  • openclaw gateway probe toont Reachable: yes. Capability: ... is het authenticatieniveau dat door de probe is aangetoond; Read probe: limited - missing scope: operator.read duidt op beperkte diagnostiek, niet op een verbindingsfout.
  • openclaw gateway status toont Runtime: running, Connectivity probe: ok en een aannemelijke Capability: .... Voeg --require-rpc toe om ook RPC-bewijs voor leesbereik te vereisen.
  • openclaw doctor meldt geen blokkerende configuratie- of servicefouten.
  • openclaw channels status --probe retourneert de actuele transportstatus per account (works / audit ok) wanneer de Gateway bereikbaar is; anders wordt teruggevallen op samenvattingen die alleen op de configuratie zijn gebaseerd.
  • openclaw logs --follow toont gestage activiteit zonder terugkerende fatale fouten.

Assistent voelt beperkt aan of mist hulpmiddelen

Controleer het effectieve hulpmiddelenprofiel:

bash
openclaw statusopenclaw status --allopenclaw doctor

Veelvoorkomende oorzaken:

  • tools.profile: "minimal" staat alleen session_status toe.
  • tools.profile: "messaging" is beperkt en bedoeld voor agents die alleen chatten.
  • tools.profile: "coding" is de standaard voor nieuwe lokale configuraties (werk aan repository, bestanden, shell en runtime).
  • tools.profile: "full" verwijdert profielbeperkingen; beperk dit tot vertrouwde agents die door de operator worden beheerd.
  • agents.list[].tools per agent overschrijft het hoofdprofiel om dit voor één agent te beperken of uit te breiden.

Wijzig het profiel, start de Gateway opnieuw of laad deze opnieuw en controleer daarna opnieuw met openclaw status --all. Volledige profiel-/groepentabel: Hulpmiddelenprofielen.

Anthropic 429 bij lange context

HTTP 429: rate_limit_error: Extra usage is required for long context requests → Voor lange context is extra Anthropic-gebruik vereist bij fout 429.

Lokale OpenAI-compatibele backend werkt rechtstreeks, maar mislukt in OpenClaw

Uw lokale/zelfgehoste /v1-backend beantwoordt rechtstreekse probes naar /v1/chat/completions, maar mislukt bij openclaw infer model run of normale agentbeurten:

  1. Als de fout vermeldt dat messages[].content een tekenreeks verwacht: stel models.providers.<provider>.models[].compat.requiresStringContent: true in.
  2. Als het nog steeds alleen bij agentbeurten van OpenClaw mislukt: stel models.providers.<provider>.models[].compat.supportsTools: false in en probeer het opnieuw.
  3. Als kleine rechtstreekse aanroepen werken, maar grotere prompts van OpenClaw de backend laten vastlopen: dit is een beperking van het bovenliggende model/de server, geen fout in OpenClaw. Ga verder in Lokale OpenAI-compatibele backend slaagt voor rechtstreekse probes, maar agentuitvoeringen mislukken.

Installatie van Plugin mislukt door ontbrekende openclaw-extensies

package.json missing openclaw.extensions betekent dat het pluginpakket een structuur gebruikt die OpenClaw niet meer accepteert.

Los dit op in het pluginpakket:

  1. Voeg openclaw.extensions toe aan package.json en laat dit verwijzen naar gebouwde runtimebestanden (meestal ./dist/index.js).
  2. Publiceer opnieuw en voer daarna nogmaals openclaw plugins install <package> uit.
json
{  "name": "@openclaw/my-plugin",  "version": "1.2.3",  "openclaw": {    "extensions": ["./dist/index.js"]  }}

Referentie: Pluginarchitectuur

Installatiebeleid blokkeert installaties of updates van plugins

De update wordt voltooid, maar plugins zijn verouderd, uitgeschakeld of tonen blocked by install policy, install policy failed closed of Disabled "<plugin>" after plugin update failure: controleer security.installPolicy.

Het installatiebeleid wordt uitgevoerd bij installaties en updates van plugins. Versies van plugins onder @openclaw/* veranderen normaal gesproken mee met de OpenClaw-release, waardoor een OpenClaw-update tijdens de synchronisatie na de update een bijpassende pluginupdate kan vereisen.

Vermijd deze beleidsvormen, tenzij u ook de bijpassende upgraderegel onderhoudt:

  • Plugins van OpenClaw vastzetten op één specifieke oude versie (bijvoorbeeld alleen @openclaw/*@2026.5.3).
  • Alleen op basis van het brontype blokkeren (elk npm-, netwerk- of request.mode: "update"-verzoek).
  • De beleidsopdracht als optioneel behandelen: wanneer security.installPolicy is ingeschakeld, zorgt een ontbrekend, traag, onleesbaar of door machtigingen geblokkeerd uitvoerbaar beleidsbestand ervoor dat het systeem uit veiligheidsoverwegingen blokkeert.
  • Versies goedkeuren zonder de openclawVersion van het verzoek te vergelijken met de metagegevens van de kandidaat-plugin.

Geef de voorkeur aan regels die vertrouwde updates van @openclaw/* toestaan wanneer deze compatibel zijn met de huidige host, in plaats van één release voor altijd vast te zetten. Als u npm standaard blokkeert, voegt u een beperkte uitzondering toe voor de plugin-id's die u gebruikt en past u dezelfde vertrouwensregel toe op request.mode: "update" als op installaties.

Herstel:

bash
openclaw doctor --deepopenclaw plugins update --allopenclaw status --all

Als het beleid bewust streng is, versoepelt u het tijdens het vertrouwde upgradevenster, voert u openclaw plugins update --all opnieuw uit en herstelt u daarna de strengere regel. Als een mislukte update een plugin heeft uitgeschakeld, inspecteert u deze voordat u hem opnieuw inschakelt:

bash
openclaw plugins inspect <plugin-id> --runtime --jsonopenclaw plugins enable <plugin-id>

Referentie: Installatiebeleid voor operators

Plugin aanwezig, maar geblokkeerd wegens verdacht eigendom

Waarschuwingen van openclaw doctor, de installatie of het opstarten tonen:

text
blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root)plugin present but blocked

De pluginbestanden zijn eigendom van een andere Unix-gebruiker dan het proces dat ze laadt. Verwijder de pluginconfiguratie niet; corrigeer het bestandseigendom of voer OpenClaw uit als de gebruiker die eigenaar is van de statusmap.

Docker-installaties worden uitgevoerd als node (uid 1000). Herstel de bindmounts van de host:

bash
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspaceopenclaw doctor --fix

Als u OpenClaw bewust als root uitvoert, herstelt u in plaats daarvan de beheerde hoofdmap voor plugins:

bash
sudo chown -R root:root /path/to/openclaw-config/npmopenclaw doctor --fix

Verdiepende documentatie: Geblokkeerd eigendom van pluginpad, Docker: machtigingen en EACCES

Beslisboom

flowchart TD
  A[OpenClaw werkt niet] --> B{Wat gaat als eerste mis}
  B --> C[Geen antwoorden]
  B --> D[Dashboard of Control UI maakt geen verbinding]
  B --> E[Gateway start niet of service draait niet]
  B --> F[Kanaal maakt verbinding maar berichten stromen niet door]
  B --> G[Cron of Heartbeat is niet geactiveerd of heeft niet afgeleverd]
  B --> H[Node is gekoppeld maar camera canvas screen exec mislukt]
  B --> I[Browserhulpmiddel mislukt]

  C --> C1[/Sectie Geen antwoorden/]
  D --> D1[/Sectie Control UI/]
  E --> E1[/Sectie Gateway/]
  F --> F1[/Sectie Kanaalstroom/]
  G --> G1[/Sectie Automatisering/]
  H --> H1[/Sectie Node-hulpmiddelen/]
  I --> I1[/Sectie Browser/]
Geen antwoorden
bash
openclaw statusopenclaw gateway statusopenclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw logs --follow

Goede uitvoer:

  • Runtime: running
  • Connectivity probe: ok
  • Capability: read-only, write-capable of admin-capable
  • Kanaal toont dat het transport is verbonden en, waar ondersteund, works of audit ok in channels status --probe
  • Afzender is goedgekeurd (of het DM-beleid is open/toelatingslijst)

Logboekpatronen:

  • drop guild message (mention required → Discord-vermeldingscontrole heeft het bericht geblokkeerd.
  • pairing request → afzender niet goedgekeurd; wacht op goedkeuring van DM-koppeling.
  • blocked / allowlist in kanaallogboeken → afzender, ruimte of groep is uitgefilterd.

Verdiepende pagina's: Geen antwoorden, Problemen met kanalen oplossen, Koppelen

Dashboard of Control UI maakt geen verbinding
bash
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

Goede uitvoer:

  • Dashboard: http://... wordt getoond in openclaw gateway status
  • Connectivity probe: ok
  • Capability: read-only, write-capable of admin-capable
  • Geen authenticatielus in de logboeken

Logboekpatronen:

  • device identity required → HTTP/niet-beveiligde context kan apparaatauthenticatie niet voltooien.
  • origin not allowed → browser-Origin is niet toegestaan voor het Gateway-doel van de Control UI.
  • AUTH_TOKEN_MISMATCH met canRetryWithDeviceToken=true → één nieuwe poging met een vertrouwd apparaattoken kan automatisch plaatsvinden, waarbij de in het cachegeheugen opgeslagen bereiken van het gekoppelde token opnieuw worden gebruikt.
  • herhaaldelijk unauthorized na die nieuwe poging → verkeerd token/wachtwoord, niet-overeenkomende authenticatiemodus of verouderd token van gekoppeld apparaat.
  • too many failed authentication attempts (retry later) → herhaalde mislukkingen vanuit die browser-Origin zijn tijdelijk geblokkeerd; andere localhost-origins gebruiken afzonderlijke categorieën. Zie Connectiviteit van Dashboard/Control UI voor de nuance rond gelijktijdige nieuwe pogingen met Tailscale Serve.
  • gateway connect failed: → UI is gericht op de verkeerde URL/poort of de Gateway is onbereikbaar.

Verdiepende pagina's: Connectiviteit van Dashboard/Control UI, Control UI, Authenticatie

Gateway start niet of service is geïnstalleerd maar draait niet
bash
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

Goede uitvoer:

  • Service: ... (loaded)
  • Runtime: running
  • Connectivity probe: ok
  • Capability: read-only, write-capable of admin-capable

Logboekpatronen:

  • Gateway start blocked: set gateway.mode=local of existing config is missing gateway.mode → de Gateway-modus is extern of de configuratie mist de markering voor lokale modus en moet worden hersteld.
  • refusing to bind gateway ... without auth → binding buiten local loopback zonder geldig authenticatiepad (token/wachtwoord of vertrouwde proxy indien geconfigureerd).
  • another gateway instance is already listening of EADDRINUSE → de poort is al in gebruik.

Verdiepende pagina's: Gateway-service draait niet, Achtergrondproces, Configuratie

Kanaal maakt verbinding, maar berichten stromen niet door
bash
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

Goede uitvoer:

  • Kanaaltransport is verbonden.
  • Controles voor koppeling/toelatingslijst slagen.
  • Vermeldingen worden gedetecteerd waar dat vereist is.

Logboekpatronen:

  • mention required → controle op groepsvermeldingen heeft de verwerking geblokkeerd.
  • pairing / pending → DM-afzender is nog niet goedgekeurd.
  • not_in_channel, missing_scope, Forbidden, 401/403 → probleem met het machtigingstoken van het kanaal.

Verdiepende pagina's: Kanaal verbonden, berichten stromen niet door, Problemen met kanalen oplossen

Cron of Heartbeat is niet geactiveerd of heeft niet afgeleverd
bash
openclaw statusopenclaw gateway statusopenclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw logs --follow

Goede uitvoer:

  • cron status toont dat de planner is ingeschakeld en wanneer deze de volgende keer wordt geactiveerd.
  • cron runs toont recente vermeldingen met ok.
  • Heartbeat is ingeschakeld en bevindt zich binnen de actieve uren.

Logboekpatronen:

  • cron: scheduler disabled; jobs will not run automatically → cron is uitgeschakeld.
  • heartbeat skipped reden quiet-hours → buiten de geconfigureerde actieve uren.
  • heartbeat skipped reden empty-heartbeat-file → HEARTBEAT.md bestaat, maar bevat alleen lege regels, opmerkingen, koppen, fences of een lege checkliststructuur.
  • heartbeat skipped reden no-tasks-due → taakmodus is actief, maar er is nog geen taakinterval verstreken.
  • heartbeat skipped reden alerts-disabled → showOk, showAlerts en useIndicator zijn allemaal uitgeschakeld.
  • requests-in-flight → hoofdlane is bezet; Heartbeat-activering is uitgesteld.
  • unknown accountId → het doelaccount voor Heartbeat-bezorging bestaat niet.

Verdiepende pagina's: Cron- en Heartbeat-bezorging, Geplande taken: probleemoplossing, Heartbeat

Node is gekoppeld, maar de tool voor camera, canvas, scherm of exec werkt niet
bash
openclaw statusopenclaw gateway statusopenclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>openclaw logs --follow

Goede uitvoer:

  • Node wordt vermeld als verbonden en gekoppeld voor de rol node.
  • De mogelijkheid bestaat voor de opdracht die u uitvoert.
  • De machtigingsstatus voor de tool is toegekend.

Logpatronen:

  • NODE_BACKGROUND_UNAVAILABLE → breng de Node-app naar de voorgrond.
  • *_PERMISSION_REQUIRED → machtiging van het besturingssysteem is geweigerd of ontbreekt.
  • SYSTEM_RUN_DENIED: approval required → goedkeuring voor exec is in behandeling.
  • SYSTEM_RUN_DENIED: allowlist miss → opdracht staat niet op de exec-toestaanlijst.

Verdiepende pagina's: Node gekoppeld, tool werkt niet, Probleemoplossing voor Node, Exec-goedkeuringen

Exec vraagt plotseling om goedkeuring
bash
openclaw config get tools.exec.hostopenclaw config get tools.exec.securityopenclaw config get tools.exec.askopenclaw gateway restart

Wat er is gewijzigd:

  • Een niet-ingestelde tools.exec.host gebruikt standaard auto, wat wordt omgezet naar sandbox wanneer een sandbox-runtime actief is, en anders naar gateway.
  • host=auto bepaalt alleen de routering; het gedrag zonder prompt komt van security=full in combinatie met ask=off op Gateway/Node.
  • Een niet-ingestelde tools.exec.security gebruikt standaard full op gateway/node.
  • Een niet-ingestelde tools.exec.ask gebruikt standaard off.
  • Als u goedkeuringsverzoeken ziet, heeft lokaal hostbeleid of beleid per sessie exec aangescherpt ten opzichte van deze standaardwaarden.

Herstel de huidige standaardwaarden zonder goedkeuring:

bash
openclaw config set tools.exec.host gatewayopenclaw config set tools.exec.security fullopenclaw config set tools.exec.ask offopenclaw gateway restart

Veiligere alternatieven:

  • Stel alleen tools.exec.host=gateway in voor stabiele hostroutering.
  • Gebruik security=allowlist met ask=on-miss voor exec op de host met beoordeling wanneer een opdracht niet op de toestaanlijst staat.
  • Schakel de sandboxmodus in, zodat host=auto weer naar sandbox wordt omgezet.

Logpatronen:

  • Approval required. → opdracht wacht op /approve ....
  • SYSTEM_RUN_DENIED: approval required → goedkeuring voor exec op de Node-host is in behandeling.
  • exec host=sandbox requires a sandbox runtime for this session → impliciete/expliciete sandboxselectie, maar de sandboxmodus is uitgeschakeld.

Verdiepende pagina's: Exec, Exec-goedkeuringen, Beveiliging: wat de audit controleert

Browsertool werkt niet
bash
openclaw statusopenclaw gateway statusopenclaw browser statusopenclaw logs --followopenclaw doctor

Goede uitvoer:

  • De browserstatus toont running: true en een gekozen browser/profiel.
  • Het profiel openclaw start, of het profiel user ziet lokale Chrome-tabbladen.

Logpatronen:

  • unknown command "browser" → plugins.allow is ingesteld en sluit browser uit.
  • Failed to start Chrome CDP on port → starten van de lokale browser is mislukt.
  • browser.executablePath not found → het geconfigureerde pad naar het uitvoerbare bestand is onjuist.
  • browser.cdpUrl must be http(s) or ws(s) → de geconfigureerde CDP-URL gebruikt een niet-ondersteund schema.
  • browser.cdpUrl has invalid port → de geconfigureerde CDP-URL heeft een ongeldige poort of een poort buiten het toegestane bereik.
  • No Chrome tabs found for profile="user" → het Chrome MCP-koppelprofiel heeft geen geopende lokale Chrome-tabbladen.
  • Remote CDP for profile "<name>" is not reachable → het geconfigureerde externe CDP-eindpunt is vanaf deze host niet bereikbaar.
  • Browser attachOnly is enabled ... not reachable → het profiel dat alleen koppelt, heeft geen actief CDP-doel.
  • Verouderde overschrijvingen voor viewport, donkere modus, landinstelling of offlinemodus op profielen die alleen koppelen of externe CDP-profielen → voer openclaw browser stop --browser-profile <name> uit om de besturingssessie te sluiten en de emulatiestatus vrij te geven zonder de Gateway opnieuw te starten.

Verdiepende pagina's: Browsertool werkt niet, Ontbrekende browseropdracht of -tool, Browser: probleemoplossing voor Linux, Browser: probleemoplossing voor externe CDP met WSL2/Windows

Gerelateerd

Was this useful?
On this page

On this page