Bot OpenClaw en panne ? La checklist de diagnostic définitive

Quand un bot OpenClaw refuse obstinément de coopérer, la première réaction est souvent de tout redémarrer en espérant un miracle. Mauvaise idée. La documentation officielle d’OpenClaw propose une méthode bien plus fiable : une échelle de commandes à exécuter dans l’ordre, pour passer du simple constat « ça ne marche pas » à un diagnostic précis.

Les 5 commandes à lancer immédiatement

Ouvrez votre terminal et exécutez ces commandes l’une après l’autre. C’est la feuille de route recommandée par OpenClaw :

1. openclaw status

2. openclaw gateway status

3. openclaw logs --follow

4. openclaw doctor

5. openclaw channels status --probe

Un état de santé normal doit afficher

Runtime: running

Connectivity probe: ok

audit ok

Les pannes Telegram les plus fréquentes (et leurs solutions)

Telegram est souvent le canal qui donne le plus de fil à retordre. Voici les quatre coupables habituels.

1. Le bot est en ligne, mais ignore le groupe

Votre bot apparaît bien « en ligne », mais reste désespérément muet dans la conversation de groupe. Le problème vient presque toujours d’une seule chose : le mode privacy de Telegram. Par défaut, un bot ne voit pas tous les messages d’un groupe, seulement ceux qui le mentionnent explicitement ou qui sont des commandes.

La solution :

• Ouvrez une discussion avec BotFather sur Telegram.
• Envoyez la commande /setprivacy.
• Choisissez votre bot, puis sélectionnez Désactiver le mode privacy.
• Pour être certain que la modification soit prise en compte, retirez le bot du groupe, puis réinvitez-le. Lui donner les droits d’administrateur est une alternative qui fonctionne aussi .

Dans certains cas, vérifiez aussi la configuration de requireMention dans votre fichier de paramètres OpenClaw. Si cette option est activée, le bot n’écoutera que les messages où il est explicitement tagué .

2. Erreur

getMe returned 401

Ce message au démarrage est sans appel : votre token d’authentification est incorrect ou a expiré. Vous devez le remettre à jour à l’un des trois endroits suivants :

• Le champ botToken dans votre fichier de configuration.
• Le fichier référencé par tokenFile.
• La variable d’environnement TELEGRAM_BOT_TOKEN (utilisée pour le compte par défaut).

Générez un nouveau token via BotFather si nécessaire et redémarrez la gateway.

3. Déconnexions aléatoires ou boucles de reconnexion

Si votre bot se déconnecte et se reconnecte en permanence, la piste réseau est la plus probable. La documentation pointe vers trois suspects : un proxy mal configuré, un souci de résolution DNS, ou un problème de routage IPv6 vers api.telegram.org .

• Surveillez les logs avec

  openclaw logs --follow

  pour voir les tentatives de reconnexion.
• Si cela persiste, vérifiez votre configuration réseau. Désactiver l’IPv6 au niveau du système ou configurer un proxy fonctionnel peut résoudre la situation.

4. Conflit de polling : erreur

getUpdates 409

Cette erreur signifie qu’un autre processus utilise déjà le même token de bot. OpenClaw est conçu pour qu’un seul « poller » soit actif par token. Si vous voyez un conflit 409, c’est qu’une autre instance de la gateway, un autre script, ou un outil externe est déjà connecté avec ce bot .

La solution : Arrêtez tous les processus OpenClaw, vérifiez qu’aucun autre service n’utilise ce token, puis relancez uniquement la gateway dont vous avez besoin.

Que faire juste après une mise à jour ?

Une mise à jour a parfois des effets de bord sur les dépendances. La procédure de remise en état est simple :

1. openclaw status --all

2. openclaw doctor --fix

3. openclaw gateway restart

4. openclaw status --all

   (pour vérifier)

Si le statut affiche un message comme

plugin load failed: dependency tree corrupted

openclaw doctor --fix

Particularités de la configuration Telegram

Contrairement à d’autres canaux, Telegram ne s’active pas avec

openclaw channels login telegram

1. S’assurer que

   channels.telegram.enabled: true

   est bien présent dans la configuration.
2. Démarrer la gateway.
3. Appairer le compte : Les messages privés (DM) utilisent un système de pairing. Une fois la gateway lancée, envoyez un message à votre bot sur Telegram. Vous recevrez un code.
4. Lancez

   openclaw pairing list telegram

   pour voir les demandes en attente, puis approuvez avec

   openclaw pairing approve telegram VOTRE_CODE

   .

En résumé

Sans les retours précis des diagnostics, il est impossible de pointer du doigt une cause unique. La force de la procédure recommandée par OpenClaw, c’est qu’elle transforme un problème flou en une erreur explicite. Prenez le temps d’exécuter les 5 commandes de la « command ladder » : leurs sorties vous mèneront directement à la solution, que ce soit un banal réglage de privacy Telegram ou un conflit de token plus pernicieux .