Probleemoplossing

• model_not_found met een lokale MLX/vLLM-achtige server → verifieer dat baseUrl /v1 bevat, api "openai-completions" is voor /v1/chat/completions-backends, en models.providers.<provider>.models[].id de kale provider-lokale id is. Selecteer deze één keer met het providerprefix, bijvoorbeeld mlx/mlx-community/Qwen3-30B-A3B-6bit; houd de catalogusvermelding als mlx-community/Qwen3-30B-A3B-6bit.
• messages[...].content: invalid type: sequence, expected a string → backend weigert gestructureerde Chat Completions-contentonderdelen. Oplossing: stel models.providers.<provider>.models[].compat.requiresStringContent: true in.
• incomplete turn detected ... stopReason=stop payloads=0 → de backend heeft het Chat Completions-verzoek voltooid, maar gaf geen voor de gebruiker zichtbare assistenttekst terug voor die beurt. OpenClaw probeert replay-veilige lege OpenAI-compatibele beurten één keer opnieuw; aanhoudende fouten betekenen meestal dat de backend lege/niet-tekstuele content uitgeeft of uiteindelijke antwoordtekst onderdrukt.
• directe kleine verzoeken slagen, maar OpenClaw-agentruns mislukken met backend-/modelcrashes (bijvoorbeeld Gemma op sommige inferrs-builds) → OpenClaw-transport is waarschijnlijk al correct; de backend faalt op de grotere promptvorm van de agentruntime.
• fouten nemen af na het uitschakelen van tools, maar verdwijnen niet → toolschema's maakten deel uit van de druk, maar het resterende probleem is nog steeds upstream model-/servercapaciteit of een backendbug.

1. Stel compat.requiresStringContent: true in voor Chat Completions-backends die alleen strings ondersteunen.
2. Stel compat.supportsTools: false in voor modellen/backends die OpenClaw's toolschema-oppervlak niet betrouwbaar aankunnen.
3. Verlaag promptdruk waar mogelijk: kleinere workspace-bootstrap, kortere sessiegeschiedenis, lichter lokaal model of een backend met sterkere ondersteuning voor lange context.
4. Als kleine directe verzoeken blijven slagen terwijl OpenClaw-agentbeurten nog steeds binnen de backend crashen, behandel dit dan als een upstream server-/modelbeperking en dien daar een repro in met de geaccepteerde payloadvorm.

• device identity required → niet-veilige context of ontbrekende apparaatauthenticatie.
• origin not allowed → browser-Origin staat niet in gateway.controlUi.allowedOrigins (of je maakt verbinding vanaf een niet-loopback browser-origin zonder expliciete allowlist).
• device nonce required / device nonce mismatch → client voltooit de challenge-gebaseerde apparaatauthenticatieflow niet (connect.challenge + device.nonce).
• device signature invalid / device signature expired → client heeft de verkeerde payload (of verouderde timestamp) ondertekend voor de huidige handshake.
• AUTH_TOKEN_MISMATCH met canRetryWithDeviceToken=true → client kan één vertrouwde retry doen met gecachte apparaattoken.
• Die retry met gecachte token hergebruikt de gecachte scopeset die met de gekoppelde apparaattoken is opgeslagen. Aanroepers met expliciete deviceToken / expliciete scopes behouden in plaats daarvan hun aangevraagde scopeset.
• Buiten dat retrypad is de voorrang voor connect-authenticatie eerst expliciete gedeelde token/wachtwoord, daarna expliciete deviceToken, daarna opgeslagen apparaattoken, daarna bootstraptoken.
• Op het asynchrone Tailscale Serve Control UI-pad worden mislukte pogingen voor dezelfde {scope, ip} geserialiseerd voordat de limiter de fout registreert. Twee slechte gelijktijdige retries vanaf dezelfde client kunnen daarom bij de tweede poging retry later tonen in plaats van twee gewone mismatches.
• too many failed authentication attempts (retry later) vanaf een browser-origin loopback-client → herhaalde fouten vanaf dezelfde genormaliseerde Origin worden tijdelijk buitengesloten; een andere localhost-origin gebruikt een aparte bucket.
• herhaalde unauthorized na die retry → drift in gedeelde token/apparaattoken; vernieuw tokenconfiguratie en keur de apparaattoken indien nodig opnieuw goed of roteer deze.
• gateway connect failed: → verkeerde host-/poort-/URL-doel.

• Gateway start blocked: set gateway.mode=local of existing config is missing gateway.mode → lokale Gateway-modus is niet ingeschakeld, of het configuratiebestand is overschreven en heeft gateway.mode verloren. Oplossing: stel gateway.mode="local" in uw configuratie in, of voer openclaw onboard --mode local / openclaw setup opnieuw uit om de verwachte lokale-modusconfiguratie opnieuw te stempelen. Als u OpenClaw via Podman draait, is het standaardconfiguratiepad ~/.openclaw/openclaw.json.
• refusing to bind gateway ... without auth → niet-loopback-bind zonder geldig Gateway-authenticatiepad (token/wachtwoord, of trusted-proxy waar geconfigureerd).
• another gateway instance is already listening / EADDRINUSE → poortconflict.
• Other gateway-like services detected (best effort) → er bestaan verouderde of parallelle launchd/systemd/schtasks-units. De meeste setups horen één Gateway per machine te behouden; als u er wel meer dan één nodig hebt, isoleer dan poorten + configuratie/status/werkruimte. Zie /gateway#multiple-gateways-same-host.
• System-level OpenClaw gateway service detected van doctor → er bestaat een systemd-systeemunit terwijl de service op gebruikersniveau ontbreekt. Verwijder of schakel het duplicaat uit voordat u doctor toestaat een gebruikersservice te installeren, of stel OPENCLAW_SERVICE_REPAIR_POLICY=external in als de systeemunit de bedoelde supervisor is.
• Gateway service port does not match current gateway config → de geïnstalleerde supervisor pint nog steeds de oude --port. Voer openclaw doctor --fix of openclaw gateway install --force uit en herstart daarna de Gateway-service.

• De configuratie is niet gevalideerd tijdens het opstarten, hot reload of een door OpenClaw beheerde schrijfactie.
• Gateway-opstarten faalt gesloten in plaats van openclaw.json te herschrijven.
• Hot reload slaat ongeldige externe wijzigingen over en houdt de huidige runtimeconfiguratie actief.
• Door OpenClaw beheerde schrijfacties weigeren ongeldige/destructieve payloads vóór commit en slaan .rejected.* op.
• openclaw doctor --fix beheert reparatie. Het kan niet-JSON-prefixen verwijderen of de laatste bekende goede kopie herstellen terwijl de geweigerde payload als .clobbered.* behouden blijft.

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

• .clobbered.* bestaat → doctor heeft een kapotte externe wijziging behouden terwijl de actieve configuratie werd gerepareerd.
• .rejected.* bestaat → een door OpenClaw beheerde configuratieschrijfactie is vóór commit mislukt op schema- of clobbercontroles.
• Config write rejected: → de schrijfactie probeerde de vereiste structuur te verwijderen, het bestand sterk te verkleinen of ongeldige configuratie op te slaan.
• config reload skipped (invalid config): → een directe wijziging is niet door validatie gekomen en is genegeerd door de draaiende Gateway.
• Invalid config at ... → opstarten is mislukt voordat Gateway-services zijn gestart.
• missing-meta-vs-last-good, gateway-mode-missing-vs-last-good of size-drop-vs-last-good:* → een door OpenClaw beheerde schrijfactie is geweigerd omdat velden of omvang verloren gingen ten opzichte van de laatste bekende goede back-up.
• Config last-known-good promotion skipped → de kandidaat bevatte geredigeerde geheimplaatshouders zoals ***.

1. Voer openclaw doctor --fix uit om doctor geprefixte/geclobberde configuratie te laten repareren of de laatste bekende goede configuratie te herstellen.
2. Kopieer alleen de bedoelde sleutels uit .clobbered.* of .rejected.* en pas ze daarna toe met openclaw config set of config.patch.
3. Voer openclaw config validate uit voordat u opnieuw start.
4. Als u handmatig bewerkt, behoud dan de volledige JSON5-configuratie, niet alleen het deelobject dat u wilde wijzigen.

• cron: scheduler disabled; jobs will not run automatically → cron uitgeschakeld.
• cron: timer tick failed → schedulertick mislukt; controleer bestands-/log-/runtimefouten.
• heartbeat skipped met reason=quiet-hours → buiten het actieve urenvenster.
• heartbeat skipped met reason=empty-heartbeat-file → HEARTBEAT.md bestaat maar bevat alleen lege regels / markdownkoppen, dus OpenClaw slaat de modelaanroep over.
• heartbeat skipped met reason=no-tasks-due → HEARTBEAT.md bevat een tasks:-blok, maar geen van de taken is verschuldigd op deze tick.
• heartbeat: unknown accountId → ongeldig account-id voor bezorgdoel van Heartbeat.
• heartbeat skipped met reason=dm-blocked → Heartbeat-doel is omgezet naar een DM-achtige bestemming terwijl agents.defaults.heartbeat.directPolicy (of override per agent) is ingesteld op block.

• unknown command "browser" of unknown command 'browser' → de meegeleverde browser-Plugin is uitgesloten door plugins.allow.
• browsertool ontbreekt / is niet beschikbaar terwijl browser.enabled=true → plugins.allow sluit browser uit, dus de Plugin is nooit geladen.
• Failed to start Chrome CDP on port → browserproces kon niet starten.
• browser.executablePath not found → geconfigureerd pad is ongeldig.
• browser.cdpUrl must be http(s) or ws(s) → de geconfigureerde CDP-URL gebruikt een niet-ondersteund schema zoals file: of ftp:.
• browser.cdpUrl has invalid port → de geconfigureerde CDP-URL heeft een slechte of buiten bereik vallende poort.
• Playwright is not available in this gateway build; '<feature>' is unsupported. → de huidige Gateway-installatie mist de kernruntime-afhankelijkheid voor browsers; installeer OpenClaw opnieuw of werk OpenClaw bij en herstart daarna de Gateway. ARIA-snapshots en eenvoudige paginaschermafbeeldingen kunnen nog werken, maar navigatie, AI-snapshots, schermafbeeldingen van elementen via CSS-selectors en PDF-export blijven niet beschikbaar.

• Could not find DevToolsActivePort for chrome → Chrome MCP bestaande sessie kon nog niet koppelen aan de geselecteerde browserdatamap. Open de inspectiepagina van de browser, schakel remote debugging in, houd de browser open, keur de eerste koppelprompt goed en probeer het opnieuw. Als aangemelde status niet vereist is, geef dan de voorkeur aan het beheerde openclaw-profiel.
• 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 niet bereikbaar vanaf de Gateway-host.
• Browser attachOnly is enabled ... not reachable of Browser attachOnly is enabled and CDP websocket ... is not reachable → attach-only-profiel heeft geen bereikbaar doel, of het HTTP-eindpunt antwoordde maar de CDP-WebSocket kon nog steeds niet worden geopend.

• fullPage is not supported for element screenshots → schermafbeeldingsverzoek combineerde --full-page met --ref of --element.
• element screenshots are not supported for existing-session profiles; use ref from snapshot. → Chrome MCP- / existing-session-schermafbeeldingsaanroepen moeten pagina-opname of een snapshot---ref gebruiken, niet CSS --element.
• existing-session file uploads do not support element selectors; use ref/inputRef. → Chrome MCP-uploadhooks hebben snapshotrefs nodig, geen CSS-selectors.
• existing-session file uploads currently support one file at a time. → verstuur één upload per aanroep op Chrome MCP-profielen.
• existing-session dialog handling does not support timeoutMs. → dialooghooks op Chrome MCP-profielen ondersteunen geen timeout-overrides.
• existing-session type does not support timeoutMs overrides. → laat timeoutMs weg voor act:type op profile="user" / Chrome MCP-profielen met bestaande sessie, of gebruik een beheerd/CDP-browserprofiel wanneer een aangepaste timeout vereist is.
• existing-session evaluate does not support timeoutMs overrides. → laat timeoutMs weg voor act:evaluate op profile="user" / Chrome MCP-profielen met bestaande sessie, of gebruik een beheerd/CDP-browserprofiel wanneer een aangepaste timeout vereist is.
• response body is not supported for existing-session profiles yet. → responsebody vereist nog steeds een beheerde browser of raw CDP-profiel.
• verouderde viewport- / dark-mode- / locale- / offline-overrides op attach-only- of externe CDP-profielen → voer openclaw browser stop --browser-profile <name> uit om de actieve controlesessie te sluiten en de Playwright-/CDP-emulatiestatus vrij te geven zonder de hele Gateway opnieuw te starten.

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 naar remote gaan terwijl je lokale service in orde is.
• Expliciete --url-aanroepen vallen niet terug op opgeslagen credentials.

Veelvoorkomende signaturen:

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

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

Wat te controleren:

• Niet-loopback-binds (lan, tailnet, custom) hebben een geldig Gateway-authpad nodig: gedeelde token-/wachtwoordauth, of een correct geconfigureerde niet-loopback-trusted-proxy-deployment.
• Oude sleutels zoals gateway.token vervangen gateway.auth.token niet.

Veelvoorkomende signaturen:

• refusing to bind gateway ... without auth → niet-loopback-bind zonder geldig Gateway-authpad.
• Connectivity probe: failed terwijl runtime draait → Gateway leeft maar is niet toegankelijk met huidige auth/url.

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

Wat te controleren:

• Wachtende apparaatgoedkeuringen voor dashboard/nodes.
• Wachtende DM-koppelingsgoedkeuringen na beleids- of identiteitswijzigingen.

Veelvoorkomende signaturen:

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