Dépannage

• model_not_found avec un serveur local de style MLX/vLLM → vérifiez que baseUrl inclut /v1, que api vaut "openai-completions" pour les backends /v1/chat/completions, et que models.providers.<provider>.models[].id est l’id local au fournisseur nu. Sélectionnez-le une fois avec le préfixe du fournisseur, par exemple mlx/mlx-community/Qwen3-30B-A3B-6bit ; conservez l’entrée de catalogue comme mlx-community/Qwen3-30B-A3B-6bit.
• messages[...].content: invalid type: sequence, expected a string → le backend rejette les parties de contenu structurées de Chat Completions. Correctif : définissez models.providers.<provider>.models[].compat.requiresStringContent: true.
• incomplete turn detected ... stopReason=stop payloads=0 → le backend a terminé la requête Chat Completions mais n’a renvoyé aucun texte d’assistant visible par l’utilisateur pour ce tour. OpenClaw réessaie une fois les tours vides compatibles OpenAI qui peuvent être rejoués sans risque ; des échecs persistants signifient généralement que le backend émet du contenu vide/non textuel ou supprime le texte de réponse finale.
• les petites requêtes directes réussissent, mais les exécutions d’agent OpenClaw échouent avec des plantages de backend/modèle (par exemple Gemma sur certaines builds inferrs) → le transport OpenClaw est probablement déjà correct ; le backend échoue sur la forme plus volumineuse du prompt de runtime d’agent.
• les échecs diminuent après la désactivation des outils mais ne disparaissent pas → les schémas d’outils faisaient partie de la pression, mais le problème restant est toujours la capacité du modèle/serveur en amont ou un bogue du backend.

1. Définissez compat.requiresStringContent: true pour les backends Chat Completions qui n’acceptent que des chaînes.
2. Définissez compat.supportsTools: false pour les modèles/backends qui ne peuvent pas gérer de manière fiable la surface de schéma d’outils d’OpenClaw.
3. Réduisez la pression du prompt lorsque c’est possible : amorçage d’espace de travail plus petit, historique de session plus court, modèle local plus léger ou backend avec une meilleure prise en charge du contexte long.
4. Si les petites requêtes directes continuent de réussir alors que les tours d’agent OpenClaw plantent toujours dans le backend, traitez cela comme une limitation du serveur/modèle en amont et déposez-y une reproduction avec la forme de charge utile acceptée.

• device identity required → contexte non sécurisé ou authentification d’appareil manquante.
• origin not allowed → l’Origin du navigateur n’est pas dans gateway.controlUi.allowedOrigins (ou vous vous connectez depuis une origine de navigateur non local loopback sans liste d’autorisation explicite).
• device nonce required / device nonce mismatch → le client ne termine pas le flux d’authentification d’appareil basé sur un défi (connect.challenge + device.nonce).
• device signature invalid / device signature expired → le client a signé la mauvaise charge utile (ou un horodatage obsolète) pour la négociation actuelle.
• AUTH_TOKEN_MISMATCH avec canRetryWithDeviceToken=true → le client peut effectuer une tentative approuvée avec le jeton d’appareil en cache.
• Cette nouvelle tentative avec jeton en cache réutilise l’ensemble de portées en cache stocké avec le jeton d’appareil appairé. Les appelants avec deviceToken explicite / scopes explicite conservent plutôt l’ensemble de portées qu’ils ont demandé.
• En dehors de ce chemin de nouvelle tentative, la priorité d’authentification de connexion est d’abord le jeton/mot de passe partagé explicite, puis le deviceToken explicite, puis le jeton d’appareil stocké, puis le jeton d’amorçage.
• Sur le chemin async de l’interface utilisateur de contrôle Tailscale Serve, les tentatives échouées pour le même {scope, ip} sont sérialisées avant que le limiteur n’enregistre l’échec. Deux mauvaises nouvelles tentatives concurrentes depuis le même client peuvent donc afficher retry later à la deuxième tentative au lieu de deux simples incompatibilités.
• too many failed authentication attempts (retry later) depuis un client local loopback d’origine navigateur → les échecs répétés depuis cette même Origin normalisée sont verrouillés temporairement ; une autre origine localhost utilise un compartiment séparé.
• unauthorized répété après cette nouvelle tentative → dérive du jeton partagé/jeton d’appareil ; actualisez la configuration du jeton et réapprouvez/faites tourner le jeton d’appareil si nécessaire.
• gateway connect failed: → mauvaise cible hôte/port/url.

• Gateway start blocked: set gateway.mode=local ou existing config is missing gateway.mode → le mode Gateway local n’est pas activé, ou le fichier de configuration a été écrasé et a perdu gateway.mode. Correctif : définissez gateway.mode="local" dans votre configuration, ou relancez openclaw onboard --mode local / openclaw setup pour réappliquer la configuration de mode local attendue. Si vous exécutez OpenClaw via Podman, le chemin de configuration par défaut est ~/.openclaw/openclaw.json.
• refusing to bind gateway ... without auth → liaison non-loopback sans chemin d’authentification Gateway valide (jeton/mot de passe, ou trusted-proxy si configuré).
• another gateway instance is already listening / EADDRINUSE → conflit de port.
• Other gateway-like services detected (best effort) → des unités launchd/systemd/schtasks obsolètes ou parallèles existent. La plupart des configurations doivent conserver un seul Gateway par machine ; si vous en avez besoin de plusieurs, isolez les ports + la configuration/l’état/l’espace de travail. Voir /gateway#multiple-gateways-same-host.
• System-level OpenClaw gateway service detected depuis doctor → une unité système systemd existe alors que le service de niveau utilisateur est absent. Supprimez ou désactivez le doublon avant d’autoriser doctor à installer un service utilisateur, ou définissez OPENCLAW_SERVICE_REPAIR_POLICY=external si l’unité système est le superviseur prévu.
• Gateway service port does not match current gateway config → le superviseur installé fixe encore l’ancien --port. Exécutez openclaw doctor --fix ou openclaw gateway install --force, puis redémarrez le service Gateway.

• La configuration n’a pas été validée pendant le démarrage, le rechargement à chaud ou une écriture détenue par OpenClaw.
• Le démarrage du Gateway échoue de façon fermée au lieu de réécrire openclaw.json.
• Le rechargement à chaud ignore les modifications externes invalides et conserve la configuration d’exécution actuelle active.
• Les écritures détenues par OpenClaw rejettent les charges utiles invalides/destructrices avant validation et enregistrent .rejected.*.
• openclaw doctor --fix possède la réparation. Il peut supprimer les préfixes non JSON ou restaurer la dernière copie connue comme bonne tout en conservant la charge utile rejetée sous .clobbered.*.

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.* existe → doctor a conservé une modification externe cassée pendant la réparation de la configuration active.
• .rejected.* existe → une écriture de configuration détenue par OpenClaw a échoué aux vérifications de schéma ou d’écrasement avant validation.
• Config write rejected: → l’écriture a tenté de supprimer la forme requise, de réduire fortement le fichier ou de persister une configuration invalide.
• config reload skipped (invalid config): → une modification directe a échoué à la validation et a été ignorée par le Gateway en cours d’exécution.
• Invalid config at ... → le démarrage a échoué avant le lancement des services Gateway.
• missing-meta-vs-last-good, gateway-mode-missing-vs-last-good ou size-drop-vs-last-good:* → une écriture détenue par OpenClaw a été rejetée parce qu’elle a perdu des champs ou de la taille par rapport à la dernière sauvegarde connue comme bonne.
• Config last-known-good promotion skipped → le candidat contenait des espaces réservés de secrets masqués tels que ***.

1. Exécutez openclaw doctor --fix pour laisser doctor réparer une configuration préfixée/écrasée ou restaurer la dernière version connue comme bonne.
2. Copiez uniquement les clés prévues depuis .clobbered.* ou .rejected.*, puis appliquez-les avec openclaw config set ou config.patch.
3. Exécutez openclaw config validate avant de redémarrer.
4. Si vous modifiez à la main, conservez la configuration JSON5 complète, pas seulement l’objet partiel que vous vouliez changer.

• cron: scheduler disabled; jobs will not run automatically → Cron désactivé.
• cron: timer tick failed → échec du tick du planificateur ; vérifiez les erreurs de fichier/journal/runtime.
• heartbeat skipped avec reason=quiet-hours → en dehors de la fenêtre d’heures actives.
• heartbeat skipped avec reason=empty-heartbeat-file → HEARTBEAT.md existe mais ne contient que des lignes vides / en-têtes Markdown, donc OpenClaw ignore l’appel au modèle.
• heartbeat skipped avec reason=no-tasks-due → HEARTBEAT.md contient un bloc tasks:, mais aucune tâche n’est due à ce tick.
• heartbeat: unknown accountId → identifiant de compte invalide pour la cible de livraison Heartbeat.
• heartbeat skipped avec reason=dm-blocked → la cible Heartbeat se résout en une destination de type DM alors que agents.defaults.heartbeat.directPolicy (ou une surcharge par agent) est défini sur block.

• unknown command "browser" ou unknown command 'browser' → le Plugin de navigateur fourni est exclu par plugins.allow.
• outil navigateur manquant / indisponible alors que browser.enabled=true → plugins.allow exclut browser, donc le Plugin ne s’est jamais chargé.
• Failed to start Chrome CDP on port → échec du lancement du processus navigateur.
• browser.executablePath not found → le chemin configuré est invalide.
• browser.cdpUrl must be http(s) or ws(s) → l’URL CDP configurée utilise un schéma non pris en charge comme file: ou ftp:.
• browser.cdpUrl has invalid port → l’URL CDP configurée a un port incorrect ou hors plage.
• Playwright is not available in this gateway build; '<feature>' is unsupported. → l’installation actuelle du Gateway ne dispose pas de la dépendance runtime principale du navigateur ; réinstallez ou mettez à jour OpenClaw, puis redémarrez le Gateway. Les instantanés ARIA et les captures d’écran de page basiques peuvent toujours fonctionner, mais la navigation, les instantanés IA, les captures d’éléments par sélecteur CSS et l’export PDF restent indisponibles.

• Could not find DevToolsActivePort for chrome → Chrome MCP existing-session n’a pas encore pu s’attacher au répertoire de données du navigateur sélectionné. Ouvrez la page d’inspection du navigateur, activez le débogage à distance, gardez le navigateur ouvert, approuvez la première invite d’attachement, puis réessayez. Si l’état connecté n’est pas requis, préférez le profil openclaw géré.
• No Chrome tabs found for profile="user" → le profil d’attachement Chrome MCP n’a aucun onglet Chrome local ouvert.
• Remote CDP for profile "<name>" is not reachable → le point de terminaison CDP distant configuré n’est pas accessible depuis l’hôte du Gateway.
• Browser attachOnly is enabled ... not reachable ou Browser attachOnly is enabled and CDP websocket ... is not reachable → le profil en attachement seul n’a pas de cible accessible, ou le point de terminaison HTTP a répondu mais le WebSocket CDP n’a toujours pas pu être ouvert.

• fullPage is not supported for element screenshots → la demande de capture d’écran a combiné --full-page avec --ref ou --element.
• element screenshots are not supported for existing-session profiles; use ref from snapshot. → les appels de capture d’écran Chrome MCP / existing-session doivent utiliser une capture de page ou une --ref d’instantané, pas un --element CSS.
• existing-session file uploads do not support element selectors; use ref/inputRef. → les hooks de téléversement Chrome MCP nécessitent des refs d’instantané, pas des sélecteurs CSS.
• existing-session file uploads currently support one file at a time. → envoyez un téléversement par appel sur les profils Chrome MCP.
• existing-session dialog handling does not support timeoutMs. → les hooks de dialogue sur les profils Chrome MCP ne prennent pas en charge les surcharges de délai.
• existing-session type does not support timeoutMs overrides. → omettez timeoutMs pour act:type sur les profils profile="user" / Chrome MCP existing-session, ou utilisez un profil de navigateur géré/CDP lorsqu’un délai personnalisé est requis.
• existing-session evaluate does not support timeoutMs overrides. → omettez timeoutMs pour act:evaluate sur les profils profile="user" / Chrome MCP existing-session, ou utilisez un profil de navigateur géré/CDP lorsqu’un délai personnalisé est requis.
• response body is not supported for existing-session profiles yet. → responsebody nécessite toujours un navigateur géré ou un profil CDP brut.
• surcharges obsolètes de viewport / mode sombre / locale / hors ligne sur les profils en attachement seul ou CDP distant → exécutez openclaw browser stop --browser-profile <name> pour fermer la session de contrôle active et libérer l’état d’émulation Playwright/CDP sans redémarrer tout le Gateway.

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

À vérifier :

• Si gateway.mode=remote, les appels CLI peuvent cibler le distant alors que votre service local fonctionne correctement.
• Les appels explicites avec --url ne se rabattent pas sur les identifiants stockés.

Signatures courantes :

• gateway connect failed: → mauvaise cible d’URL.
• unauthorized → point de terminaison accessible mais mauvaise authentification.

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

À vérifier :

• Les liaisons non-local loopback (lan, tailnet, custom) nécessitent un chemin d’authentification Gateway valide : authentification par jeton partagé/mot de passe, ou déploiement trusted-proxy non-local loopback correctement configuré.
• Les anciennes clés comme gateway.token ne remplacent pas gateway.auth.token.

Signatures courantes :

• refusing to bind gateway ... without auth → liaison non-local loopback sans chemin d’authentification Gateway valide.
• Connectivity probe: failed alors que le runtime est en cours d’exécution → Gateway actif mais inaccessible avec l’authentification/l’URL actuelles.

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

À vérifier :

• Approbations d’appareils en attente pour tableau de bord/Nodes.
• Approbations d’appairage DM en attente après des changements de politique ou d’identité.

Signatures courantes :

• device identity required → authentification de l’appareil non satisfaite.
• pairing required → l’expéditeur/appareil doit être approuvé.