Dépannage

Ceci est le guide opérationnel approfondi. Commencez d’abord par /help/troubleshooting pour suivre le processus de triage rapide.

Séquence de commandes

Exécutez-les dans cet ordre :

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

Signaux de bon fonctionnement :

• openclaw gateway status affiche Runtime: running, Connectivity probe: ok et une ligne Capability: ....
• openclaw doctor ne signale aucun problème bloquant de configuration ou de service.
• openclaw channels status --probe affiche l’état en direct du transport pour chaque compte et, lorsque cette fonction est prise en charge, works ou audit ok.

Après une mise à jour

Utilisez cette procédure lorsqu’une mise à jour est terminée, mais que le Gateway est arrêté, que les canaux sont vides ou que les appels aux modèles échouent avec des erreurs 401.

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

Recherchez :

• Update restart dans openclaw status / openclaw status --all. Les transferts en attente ou ayant échoué indiquent la prochaine commande à exécuter.
• plugin load failed: dependency tree corrupted; run openclaw doctor --fix sous Channels : la configuration du canal existe toujours, mais l’enregistrement du Plugin a échoué avant le chargement du canal.
• Des erreurs 401 du fournisseur après une nouvelle authentification : openclaw doctor --fix recherche les copies obsolètes des données d’authentification OAuth propres à chaque agent et les supprime afin que tous les agents utilisent le profil partagé actuel.

Installations incohérentes et protection contre une configuration plus récente

Utilisez cette procédure lorsqu’un service Gateway s’arrête de manière inattendue après une mise à jour, ou lorsque les journaux indiquent qu’un binaire openclaw est plus ancien que la version ayant écrit openclaw.json pour la dernière fois.

OpenClaw marque les écritures de configuration avec meta.lastTouchedVersion. Les commandes en lecture seule peuvent examiner une configuration écrite par une version plus récente d’OpenClaw, mais les mutations de processus et de services refusent de s’exécuter depuis un binaire plus ancien. Actions bloquées : démarrage, arrêt, redémarrage et désinstallation du service Gateway, réinstallation forcée du service, démarrage du Gateway en mode service et nettoyage du port avec gateway --force.

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

openclaw gateway install --forceopenclaw gateway restart

Incompatibilité de protocole après une restauration

Utilisez cette procédure lorsque les journaux continuent d’afficher protocol mismatch après une rétrogradation ou une restauration. Un ancien Gateway est en cours d’exécution, mais un processus client local plus récent continue de se reconnecter avec une plage de protocoles que l’ancien Gateway ne prend pas en charge.

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

Recherchez :

• protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n> dans les journaux du Gateway.
• Established clients: dans openclaw gateway status --deep ou Gateway clients dans openclaw doctor --deep : les clients TCP actifs connectés au port du Gateway, avec leur PID et leur ligne de commande lorsque le système d’exploitation le permet.
• Un processus client dont la ligne de commande pointe vers l’installation ou le wrapper OpenClaw plus récent depuis lequel vous avez effectué la rétrogradation.

Correction :

1. Arrêtez ou redémarrez le processus client OpenClaw obsolète affiché par gateway status --deep.
2. Redémarrez les applications ou wrappers qui intègrent OpenClaw : tableaux de bord locaux, éditeurs, utilitaires de serveur d’application ou shells openclaw logs --follow de longue durée.
3. Réexécutez openclaw gateway status --deep ou openclaw doctor --deep et vérifiez que le PID du client obsolète a disparu.

Ne faites pas en sorte qu’un ancien Gateway accepte un protocole plus récent et incompatible. Les changements de version du protocole protègent le contrat de communication ; la récupération après restauration consiste à nettoyer les processus et les versions.

Lien symbolique de Skill ignoré pour sortie du chemin autorisé

Utilisez cette procédure lorsque les journaux contiennent :

Chemin de Skill ignoré car il sort de sa racine configurée : ... reason=symlink-escape

Chaque racine de Skill constitue une limite de confinement. Un lien symbolique sous ~/.agents/skills, <workspace>/.agents/skills, <workspace>/skills ou ~/.openclaw/skills est ignoré lorsque sa cible réelle se trouve hors de cette racine, sauf si cette cible est explicitement approuvée.

Examinez le lien :

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

Si la cible est intentionnelle, configurez à la fois la racine directe de Skill et la cible de lien symbolique autorisée :

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

Démarrez ensuite une nouvelle session ou attendez que l’observateur de Skills actualise son état. Redémarrez le Gateway si le processus en cours d’exécution est antérieur à la modification de la configuration.

N’utilisez pas de cibles trop larges telles que ~, / ou l’intégralité d’un dossier de projet synchronisé. Limitez allowSymlinkTargets à la véritable racine de Skill contenant les répertoires SKILL.md approuvés.

Si l’application des modifications depuis Skill Workshop doit également écrire via ces chemins de Skills d’espace de travail liés symboliquement et approuvés, activez skills.workshop.allowSymlinkTargetWrites. Laissez cette option désactivée pour les racines de Skills partagées en lecture seule.

Voir aussi :

• Configuration des Skills
• Exemples de configuration

L’utilisation supplémentaire d’Anthropic est requise pour le contexte long en cas d’erreur 429

Utilisez cette procédure lorsque les journaux ou les erreurs contiennent : HTTP 429: rate_limit_error: Extra usage is required for long context requests.

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

Recherchez :

• Le modèle Anthropic sélectionné est un modèle Claude 4.x à disponibilité générale prenant en charge 1M (Opus 4.6/4.7/4.8, Sonnet 4.6), ou la configuration du modèle contient encore l’ancien paramètre params.context1m: true.
• Les identifiants Anthropic actuels ne sont pas éligibles à l’utilisation du contexte long.
• Les requêtes échouent uniquement pendant les longues sessions ou exécutions de modèle nécessitant le chemin de contexte 1M.

Options de correction :

Voir aussi :

• Anthropic
• Utilisation des jetons et coûts
• Pourquoi une erreur HTTP 429 d’Anthropic s’affiche-t-elle ?

Réponses 403 bloquées en amont

Utilisez cette procédure lorsqu’un fournisseur de LLM en amont renvoie une erreur 403 générique telle que Your request was blocked.

Ne supposez pas qu’il s’agit toujours d’un problème de configuration d’OpenClaw. La réponse peut provenir d’une couche de sécurité en amont, telle qu’un CDN, un WAF, une règle de gestion des robots ou un proxy inverse placé devant un point de terminaison compatible avec OpenAI.

openclaw statusopenclaw gateway statusopenclaw logs --follow

Recherchez :

• Plusieurs modèles du même fournisseur échouent de la même manière.
• Du HTML ou un texte de sécurité générique à la place d’une erreur normale de l’API du fournisseur.
• Des événements de sécurité côté fournisseur correspondant à l’heure de la requête.
• Une minuscule requête de vérification directe avec curl réussit, alors que les requêtes normales structurées comme celles du SDK échouent.

Corrigez d’abord le filtrage côté fournisseur lorsque les éléments indiquent un blocage par un WAF/CDN. Privilégiez une règle d’autorisation ou d’exclusion limitée au chemin d’API utilisé par OpenClaw et évitez de désactiver la protection pour l’ensemble du site.

Voir aussi :

• Points de terminaison compatibles avec OpenAI
• Configuration des fournisseurs
• Journaux

Le backend local compatible avec OpenAI réussit les vérifications directes, mais les exécutions d’agent échouent

Utilisez cette procédure lorsque :

• curl ... /v1/models fonctionne.
• Les petits appels directs à /v1/chat/completions fonctionnent.
• Les exécutions de modèles OpenClaw échouent uniquement lors des tours d’agent normaux.

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

Recherchez :

• Les petits appels directs réussissent, mais les exécutions OpenClaw échouent uniquement avec des prompts plus volumineux.
• Des erreurs model_not_found ou 404, même si l’appel direct à /v1/chat/completions fonctionne avec le même identifiant de modèle sans préfixe.
• Des erreurs du backend indiquant que messages[].content doit être une chaîne.
• Des avertissements intermittents incomplete turn detected ... stopReason=stop payloads=0 avec un backend local compatible avec OpenAI.
• Des plantages du backend qui apparaissent uniquement avec un plus grand nombre de jetons dans le prompt ou avec les prompts complets de l’environnement d’exécution de l’agent.

Voir aussi :

• Configuration
• Modèles locaux
• Points de terminaison compatibles avec OpenAI

Aucune réponse

Si les canaux sont opérationnels, mais que rien ne répond, vérifiez le routage et la politique avant de reconnecter quoi que ce soit.

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

Recherchez :

• Un appairage en attente pour les expéditeurs de messages privés.
• Le filtrage des mentions de groupe (requireMention, mentionPatterns).
• Des incohérences dans les listes d’autorisation de canaux/groupes.

Signatures courantes :

• drop guild message (mention required → message de groupe ignoré jusqu’à ce qu’une mention soit effectuée.
• pairing request → l’expéditeur doit être approuvé.
• blocked / allowlist → l’expéditeur/le canal a été filtré par la politique.

Voir aussi :

• Dépannage des canaux
• Groupes
• Appairage

Connectivité de l’interface de contrôle du tableau de bord

Lorsque le tableau de bord ou l’interface de contrôle ne parvient pas à se connecter, vérifiez l’URL, le mode d’authentification et les hypothèses relatives au contexte sécurisé.

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

Recherchez :

• L’URL de sonde et l’URL du tableau de bord correctes.
• Une incohérence de mode d’authentification ou de jeton entre le client et le Gateway.
• L’utilisation de HTTP lorsqu’une identité d’appareil est requise.

Si un navigateur local ne parvient pas à se connecter à 127.0.0.1:18789 après une mise à jour, rétablissez d’abord le service Gateway local et vérifiez qu’il fournit le tableau de bord :

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

Si curl renvoie du HTML OpenClaw, le Gateway fonctionne et le problème restant est probablement dû au cache du navigateur, à un ancien lien profond ou à l’état obsolète d’un onglet. Ouvrez directement http://127.0.0.1:18789 et naviguez depuis le tableau de bord. Si le redémarrage ne laisse pas le service en cours d’exécution, exécutez openclaw gateway start, puis vérifiez à nouveau openclaw gateway status.

Aperçu des codes de détail d’authentification

Utilisez error.details.code dans la réponse connect ayant échoué pour choisir l’action suivante :

Vérification de la migration de l’authentification des appareils v2 :

openclaw --versionopenclaw doctoropenclaw gateway status

Si les journaux affichent des erreurs de nonce/signature, mettez à jour le client qui se connecte et vérifiez-le :

Si openclaw devices rotate / revoke / remove est refusé de manière inattendue :

• Les sessions utilisant un jeton d’appareil appairé ne peuvent gérer que leur propre appareil, sauf si l’appelant dispose également de operator.admin.
• openclaw devices rotate --scope ... ne peut demander que les portées d’opérateur que la session de l’appelant possède déjà.

Voir aussi :

• Configuration (modes d’authentification du Gateway)
• Interface de contrôle
• Appareils
• Accès à distance
• Authentification par proxy de confiance

Service Gateway non démarré

À utiliser lorsque le service est installé, mais que le processus ne reste pas actif.

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --deep   # analyse également les services au niveau système

Recherchez :

• Runtime: stopped accompagné d’indications sur la sortie.
• Une incohérence de configuration du service (Config (cli) par rapport à Config (service)).
• Des conflits de port/d’écouteur.
• Des installations launchd/systemd/schtasks supplémentaires lorsque --deep est utilisé.
• Des indications de nettoyage Other gateway-like services detected (best effort).

Voir aussi :

• Exécution en arrière-plan et outil de processus
• Configuration
• Doctor

Sous macOS, le Gateway cesse silencieusement de répondre, puis reprend lorsque vous interagissez avec le tableau de bord

À utiliser lorsque les canaux (Telegram, WhatsApp, etc.) d’un hôte macOS restent silencieux pendant plusieurs minutes, voire plusieurs heures, et que le Gateway semble se réactiver dès que vous ouvrez l’interface de contrôle, établissez une connexion SSH ou interagissez d’une autre manière avec l’hôte. openclaw status n’affiche généralement aucun symptôme évident, car au moment où vous consultez l’état, le Gateway fonctionne de nouveau.

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"

Recherchez :

• Un ou plusieurs ensembles *-uncaught_exception.json dans ~/.openclaw/logs/stability/, avec error.code défini sur un code réseau transitoire tel que ENETDOWN, ENETUNREACH, EHOSTUNREACH ou ECONNREFUSED.
• Des lignes de pmset -g log telles que Entering Sleep state due to 'Maintenance Sleep' ou en0 driver is slow (msg: WillChangeState to 0) correspondant aux horodatages des plantages. Power Nap / Maintenance Sleep place brièvement le pilote Wi-Fi dans l’état 0 ; tout appel connect() sortant effectué pendant cet intervalle peut échouer avec ENETDOWN, même sur un hôte disposant par ailleurs d’une connectivité réseau complète.
• Une sortie de launchctl print affichant state = not running, avec plusieurs runs récents et un code de sortie, en particulier lorsque l’intervalle entre le plantage et le lancement suivant est de l’ordre d’une heure plutôt que de quelques secondes. Après une série de plantages, launchd de macOS applique un mécanisme non documenté de protection contre les relances qui peut cesser de respecter KeepAlive=true jusqu’à ce qu’un déclencheur externe, tel qu’une connexion interactive, une connexion au tableau de bord ou launchctl kickstart, le réarme.

Signatures courantes :

• Un ensemble de stabilité dont error.code vaut ENETDOWN ou un code apparenté, avec une pile d’appels pointant vers lookupAndConnect / Socket.connect du module net de Node. OpenClaw 2026.5.26 et les versions ultérieures classent ces erreurs comme des erreurs réseau transitoires bénignes, afin qu’elles ne se propagent plus jusqu’au gestionnaire global des exceptions non interceptées ; si vous utilisez une version antérieure, commencez par effectuer une mise à niveau.
• De longues périodes d’inactivité qui prennent fin dès que vous vous connectez à l’interface de contrôle ou à l’hôte par SSH : c’est l’activité visible par l’utilisateur qui réarme le mécanisme de relance de launchd, et non une action du tableau de bord sur le Gateway.
• Un compteur runs qui augmente au fil de la journée sans ligne received SIG*; shutting down correspondante dans ~/Library/Logs/openclaw/gateway.log : les arrêts propres consignent un signal dans les journaux, contrairement aux plantages transitoires.

Procédure à suivre :

1. Mettez à niveau le Gateway si vous utilisez une version antérieure à 2026.5.26. Après la mise à niveau, les futures erreurs ENETDOWN sont consignées comme avertissements au lieu d’arrêter le processus.

2. Réduisez l’activité de veille de maintenance sur les Mac mini / hôtes de bureau destinés à fonctionner comme des serveurs toujours actifs :

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

   Cela réduit considérablement, sans toutefois l’éliminer complètement, l’instabilité sous-jacente du pilote. Le système peut toujours effectuer certaines veilles de maintenance pour maintenir les connexions TCP et entretenir mDNS, indépendamment de ces indicateurs.

3. Ajoutez un mécanisme de surveillance de disponibilité afin qu’une future série de plantages bloquée par launchd soit rapidement détectée :

   # Exemple de contrôle de disponibilité tenant compte de launchd, adapté à une tâche Cron ou à un LaunchAgent exécuté toutes les 5 minutesstate=$(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

   L’objectif est de réarmer extérieurement le mécanisme de relance ; KeepAlive=true seul ne suffit pas sous macOS après une série de plantages.

Voir aussi :

• Notes sur la plateforme macOS
• Journalisation
• Doctor

Boucle de supervision launchd sous macOS avec des LaunchAgents Gateway/Node en double

Utilisez cette procédure lorsqu’une installation macOS redémarre sans cesse toutes les quelques secondes, que les contrôles d’intégrité d’openclaw oscillent entre un état sain et une indisponibilité, et que l’acheminement vers les canaux se bloque, même si le service semble fonctionner.

Ce problème a été observé sur d’anciennes installations où les LaunchAgents ai.openclaw.gateway et ai.openclaw.node étaient tous deux actifs et injectaient chacun OPENCLAW_LAUNCHD_LABEL. Dans cet état, OpenClaw peut détecter la supervision par launchd, tenter de lui déléguer le redémarrage, puis tomber dans une boucle rapide EADDRINUSE/relance au lieu de conserver un seul processus Gateway stable.

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

Éléments à rechercher :

• Plusieurs PID de Gateway dans l’échantillon de 30 secondes au lieu d’un seul processus stable.
• EADDRINUSE, another gateway instance is already listening ou des lignes répétées de redémarrage/transfert dans gateway.log.
• ~/Library/LaunchAgents/ai.openclaw.gateway.plist et ~/Library/LaunchAgents/ai.openclaw.node.plist chargés simultanément sur un hôte qui ne devrait exécuter qu’un seul service Gateway géré.

Procédure à suivre :

1. Si cet hôte ne doit exécuter que le service Gateway, supprimez le service Node géré au moyen d’OpenClaw. Ignorez cette étape si vous dépendez activement du service Node pour les fonctionnalités de Node distant ; sa désinstallation arrête ces fonctionnalités sur cet hôte :

   openclaw node uninstall

2. Installez un wrapper Gateway persistant qui efface les marqueurs launchd hérités avant de démarrer OpenClaw. Utilisez l’option prise en charge --wrapper ; ne modifiez pas le fichier généré sous ~/.openclaw/service-env/, car la réinstallation du service, la mise à jour et la réparation par Doctor régénèrent ce fichier :

   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 conserve le chemin du wrapper lors des réinstallations forcées, des mises à jour et des réparations par Doctor.

3. Vérifiez que le Gateway est stable et fournit le service RPC, et qu’il ne se contente pas d’écouter :

   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

   L’échantillon de PID doit afficher un seul processus stable au lieu d’un ensemble de PID en rotation, et l’acheminement entrant vers les canaux doit reprendre.

4. Après la mise à niveau vers une version dans laquelle la boucle sous-jacente des deux LaunchAgents est corrigée, supprimez la solution de contournement et réinstallez le service géré normal :

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

Voir aussi :

• Notes sur la plateforme macOS
• Doctor
• CLI du Gateway

Le Gateway s’arrête lors d’une utilisation élevée de la mémoire

Utilisez cette procédure lorsque le Gateway disparaît sous charge, que le superviseur signale un redémarrage de type mémoire insuffisante ou que les journaux mentionnent critical memory pressure bundle written.

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

Éléments à rechercher :

• Reason: diagnostic.memory.pressure.critical dans le dernier ensemble de stabilité.
• Memory pressure: avec critical/rss_threshold, critical/heap_threshold ou critical/rss_growth.
• Des valeurs V8 heap: proches de la limite du tas.
• Des entrées Largest session files: telles que agents/<agent>/sessions/<session>.jsonl ou sessions/<session>.jsonl.
• Les compteurs de mémoire des cgroups Linux lorsque le Gateway s’exécute dans un conteneur ou un service à mémoire limitée.

Signatures courantes :

• critical memory pressure bundle written apparaît peu avant le redémarrage → OpenClaw a capturé un ensemble de stabilité avant l’épuisement de la mémoire. Examinez-le avec openclaw gateway stability --bundle latest.
• memory pressure: level=critical ... memoryPressureSnapshot=disabled apparaît dans les journaux du Gateway → OpenClaw a détecté une pression mémoire critique, mais l’instantané de stabilité précédant l’épuisement de la mémoire est désactivé.
• Largest session files: pointe vers un très grand chemin de transcription expurgé → réduisez l’historique de session conservé, examinez la croissance de la session ou déplacez les anciennes transcriptions hors du stockage actif avant de redémarrer.
• Le nombre d’octets utilisés indiqué par V8 heap: est proche de la limite du tas → réduisez la pression exercée par les prompts/sessions, diminuez le nombre de tâches simultanées ou augmentez la limite du tas de Node uniquement après avoir confirmé que la charge de travail est attendue.
• Memory pressure: critical/rss_growth → la mémoire a augmenté rapidement au cours d’une seule fenêtre d’échantillonnage. Consultez les derniers journaux pour détecter une importation volumineuse, une sortie d’outil incontrôlée, des tentatives répétées ou un lot de tâches d’agent mises en file d’attente.
• Une pression mémoire critique apparaît dans les journaux, mais aucun ensemble n’existe → il s’agit du comportement par défaut. Définissez diagnostics.memoryPressureSnapshot: true pour capturer l’ensemble de stabilité précédant l’épuisement de la mémoire lors des futurs événements de pression mémoire critique.

L’ensemble de stabilité ne contient aucune charge utile. Il inclut des données opérationnelles sur la mémoire et des chemins de fichiers relatifs expurgés, mais aucun texte de message, corps de Webhook, identifiant, jeton, cookie ou identifiant de session brut. Joignez l’exportation des diagnostics aux rapports de bogue plutôt que de copier les journaux bruts.

Voir aussi :

• Intégrité du Gateway
• Exportation des diagnostics
• Sessions

Le Gateway a rejeté une configuration non valide

Utilisez cette procédure lorsque le démarrage du Gateway échoue avec Invalid config ou que les journaux de rechargement à chaud indiquent qu’une modification non valide a été ignorée.

openclaw logs --followopenclaw config fileopenclaw config validateopenclaw doctor

Éléments à rechercher :

• Invalid config at ...
• config reload skipped (invalid config): ...
• Config write rejected: ...
• Un fichier horodaté openclaw.json.rejected.* à côté de la configuration active.
• Un fichier horodaté openclaw.json.clobbered.* si doctor --fix a réparé une modification directe défectueuse.
• OpenClaw conserve les 32 derniers fichiers .clobbered.* pour chaque chemin de configuration et effectue une rotation des plus anciens.

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

Voir aussi :

• Configuration
• Configuration : rechargement à chaud
• Configuration : validation stricte
• Doctor

Avertissements de la sonde du Gateway

À utiliser lorsque openclaw gateway probe atteint une cible, mais affiche tout de même un bloc d’avertissement.

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

Recherchez :

• warnings[].code et primaryTargetId dans la sortie JSON.
• Si l’avertissement concerne le repli SSH, plusieurs gateways, des portées manquantes ou des références d’authentification non résolues.

Signatures courantes :

• SSH tunnel failed to start; falling back to direct probes. → la configuration SSH a échoué, mais la commande a tout de même tenté d’interroger directement les cibles configurées ou de bouclage.
• multiple reachable gateway identities detected → des gateways distincts ont répondu, ou OpenClaw n’a pas pu prouver que les cibles accessibles correspondent au même gateway. Un tunnel SSH, une URL de proxy ou une URL distante configurée vers le même gateway sont considérés comme un seul gateway utilisant plusieurs transports, même si les ports de transport diffèrent.
• Read-probe diagnostics are limited by gateway scopes (missing operator.read) → la connexion a réussi, mais les RPC détaillés sont limités par les portées ; associez l’identité de l’appareil ou utilisez des identifiants disposant de operator.read.
• Gateway accepted the WebSocket connection, but follow-up read diagnostics failed → la connexion a réussi, mais l’ensemble complet des RPC de diagnostic a expiré ou échoué. Considérez ce Gateway comme accessible avec des diagnostics dégradés ; comparez connect.ok et connect.rpcOk dans la sortie de --json.
• Capability: pairing-pending ou gateway closed (1008): pairing required → le gateway a répondu, mais ce client doit encore être associé ou approuvé avant de disposer d’un accès opérateur normal.
• Texte d’avertissement de SecretRef gateway.auth.* / gateway.remote.* non résolue → les données d’authentification n’étaient pas disponibles dans ce chemin de commande pour la cible en échec.

Voir aussi :

• Gateway
• Plusieurs gateways sur le même hôte
• Accès distant

Canal connecté, mais les messages ne circulent pas

Si l’état du canal indique qu’il est connecté, mais que le flux de messages est interrompu, concentrez-vous sur la stratégie, les autorisations et les règles de livraison propres au canal.

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

Recherchez :

• La stratégie de messages privés (pairing, allowlist, open, disabled).
• La liste d’autorisation des groupes et les exigences de mention.
• Les autorisations ou portées d’API du canal manquantes.

Signatures courantes :

• mention required → message ignoré par la stratégie de mention du groupe.
• Traces pairing / d’approbation en attente → l’expéditeur n’est pas approuvé.
• missing_scope, not_in_channel, Forbidden, 401/403 → problème d’authentification ou d’autorisations du canal.

Voir aussi :

• Dépannage des canaux
• Discord
• Telegram
• WhatsApp

Livraison Cron et Heartbeat

Si Cron ou Heartbeat ne s’est pas exécuté ou n’a rien livré, vérifiez d’abord l’état du planificateur, puis la cible de livraison.

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

Recherchez :

• Si Cron est activé et si le prochain réveil est indiqué.
• L’état de l’historique d’exécution de la tâche (ok, skipped, error).
• Les motifs d’omission de Heartbeat (quiet-hours, requests-in-flight, cron-in-progress, lanes-busy, alerts-disabled, empty-heartbeat-file, no-tasks-due).

Voir aussi :

• Heartbeat
• Tâches planifiées
• Tâches planifiées : dépannage

Node associé, échec de l’outil

Si un Node est associé, mais que les outils échouent, isolez l’état de premier plan, des autorisations et de l’approbation.

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

Recherchez :

• Si le Node est en ligne avec les capacités attendues.
• Les autorisations du système d’exploitation pour la caméra, le microphone, la localisation et l’écran.
• L’état des approbations d’exécution et de la liste d’autorisation.

Signatures courantes :

• NODE_BACKGROUND_UNAVAILABLE → l’application du Node doit être au premier plan.
• *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → autorisation du système d’exploitation manquante.
• SYSTEM_RUN_DENIED: approval required → approbation d’exécution en attente.
• SYSTEM_RUN_DENIED: allowlist miss → commande bloquée par la liste d’autorisation.

Voir aussi :

• Approbations d’exécution
• Dépannage des Nodes
• Nodes

Échec de l’outil de navigation

À utiliser lorsque les actions de l’outil de navigation échouent alors que le gateway lui-même fonctionne correctement.

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

Recherchez :

• Si plugins.allow est défini et inclut browser.
• Un chemin valide vers l’exécutable du navigateur.
• L’accessibilité du profil CDP.
• La disponibilité locale de Chrome pour les profils existing-session / user.

Voir aussi :

• Navigateur (géré par OpenClaw)
• Dépannage du navigateur

Si vous avez effectué une mise à niveau et qu’un élément a soudainement cessé de fonctionner

La plupart des dysfonctionnements après une mise à niveau proviennent d’une dérive de configuration ou de valeurs par défaut plus strictes désormais appliquées.

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

Si la configuration du service et l’environnement d’exécution divergent encore après ces vérifications, réinstallez les métadonnées du service depuis le même répertoire de profil/d’état :

openclaw gateway install --forceopenclaw gateway restart

Voir aussi :

• Authentification
• Exécution en arrière-plan et outil de processus
• Association des Nodes

Voir aussi

• Doctor
• FAQ
• Guide opérationnel du Gateway