Dépanner Telegram dans OpenClaw

Un bot Telegram qui échoue le fait rarement bruyamment ; il ne répond simplement pas, et la raison est presque toujours l’un d’une courte liste de réglages côté Telegram, côté configuration ou sur le réseau entre les deux. La documentation range les correctifs par symptôme, donc ce billet aussi : le groupe qui ignore tout le monde, le groupe que le bot ne voit pas, les commandes qui marchent à moitié, le jeton rejeté au démarrage, et le sondage qui se bloque.

Groupes et commandes

• Quand la mention obligatoire est désactivée, le mode privé de Telegram doit autoriser la visibilité complète : réglez le mode privé sur désactivé avec BotFather, puis retirez et réajoutez le bot au groupe ; la commande d’état des canaux avertit quand la configuration attend des messages de groupe sans mention, son option de sonde vérifie les identifiants numériques explicites de groupe tandis qu’un joker ne peut pas être sondé, et la commande d’activation permanente est un test de session rapide.
• Si le bot ne voit aucun message de groupe, vérifiez que le groupe figure dans la carte des groupes, ou que la carte contient le joker, dès que cette carte existe, vérifiez que le bot est bien membre, et suivez les journaux pour lire les raisons de saut.
• Des commandes qui marchent partiellement ou pas du tout signifient généralement que l’identité de l’expéditeur n’est pas autorisée, par appairage ou par une entrée numérique de la liste, parce que l’autorisation des commandes s’applique même quand la politique de groupe est ouverte ; l’erreur de trop de commandes sur setMyCommands signifie que le menu natif déborde, donc réduisez les commandes d’extensions, de compétences et personnalisées ou désactivez les menus natifs.
• Les appels de démarrage qui suppriment et définissent les commandes et les appels d’indicateur de frappe sont bornés et réessaient une fois par le transport de repli de Telegram en cas de dépassement de délai ; des erreurs réseau persistantes à cet endroit signifient généralement que le DNS ou le HTTPS vers l’hôte de l’API Bot est injoignable.

getMe returned 401 est un échec d’authentification Telegram pour le jeton de bot configuré.

Jeton et sondage

Un 401 sur getMe signifie que Telegram a rejeté le jeton configuré : recopiez-le ou régénérez-le dans BotFather et mettez à jour la clé du jeton, le fichier de jeton, le jeton au niveau du compte ou la variable d’environnement du compte par défaut. Un 401 sur deleteWebhook au démarrage est aussi un échec d’authentification, et le traiter comme l’absence de webhook ne ferait que reporter le même échec de jeton à un appel ultérieur. L’instabilité du sondage a davantage de causes. Node 22 et suivants avec un fetch ou un proxy personnalisé peuvent abandonner immédiatement quand les types de signal d’abandon ne correspondent pas, certains hôtes résolvent l’hôte de l’API en IPv6 d’abord de sorte qu’une sortie IPv6 cassée provoque des échecs intermittents, et les erreurs de fetch échoué ou de réseau sur getUpdates dans les journaux sont réessayées comme récupérables. Au démarrage du sondage, OpenClaw réutilise la sonde getMe réussie du démarrage pour grammY, donc l’exécuteur n’a pas besoin d’une seconde sonde avant le premier getUpdates ; si deleteWebhook échoue sur une erreur réseau passagère, le sondage continue au lieu de faire un autre appel au plan de contrôle, et un webhook encore actif se manifeste alors comme un conflit sur getUpdates qui reconstruit le transport et réessaie le nettoyage. Une ligne de journal de blocage du sondage signifie qu’OpenClaw redémarre le sondage et reconstruit le transport après 120 secondes sans vivacité de sondage long aboutie, et la sonde d’état et le doctor avertissent quand un compte en sondage n’a pas achevé getUpdates après le délai de grâce du démarrage, quand un compte en webhook n’a pas achevé setWebhook, ou quand la dernière activité réussie du transport est périmée.

Réseau, proxys et DNS

• Telegram honore l’environnement de proxy du processus pour le transport de l’API Bot, les variables de proxy HTTP, HTTPS et ALL en majuscules comme en minuscules, les variables d’exclusion pouvant encore contourner l’hôte de l’API ; si l’URL de proxy d’OpenClaw est définie pour un environnement de service et qu’aucune variable de proxy standard n’est présente, Telegram utilise aussi cette URL, et sur les serveurs virtuels à sortie directe ou TLS instables vous faites passer l’API par un proxy SOCKS5 ou HTTP sous la clé de proxy du canal.
• Si le texte fonctionne mais que les pièces jointes échouent sur une erreur DNS, les simples variables de proxy laissent encore les téléchargements de médias soumis aux vérifications DNS locales : réglez le proxy du canal sur un proxy HTTP ou SOCKS5 de confiance pour qu’il résolve les hôtes de médias, ou configurez un proxy réseau géré, en gardant le point de terminaison du proxy lui-même résoluble et joignable localement, et notez que l’indicateur dangereux de réseau privé ne corrige pas un DNS manquant.
• Node 22 sélectionne automatiquement la famille d’adresses par défaut sauf sous WSL2, l’ordre des résultats DNS suit la variable d’environnement Telegram, puis la clé réseau du canal, puis la valeur par défaut du processus, en retombant sur IPv4 d’abord sous Node 22 quand rien ne s’applique, et la clé réseau du canal peut désactiver la sélection de famille ; la plage de test RFC 2544 est déjà autorisée pour les téléchargements de médias, et ce n’est que lorsqu’un proxy de confiance à fausses adresses ou transparent réécrit l’hôte de l’API vers une autre adresse privée ou réservée que vous activez le contournement de réseau privé propre à Telegram, au niveau du canal ou par compte, qui affaiblit les protections contre la SSRF des médias et n’a sa place que dans des environnements de proxy contrôlés par l’opérateur comme Clash, Mihomo ou Surge ; des surcharges d’environnement temporaires existent pour la sélection de famille et l’ordre des résultats, et deux commandes dig valident les réponses A et AAAA.

OpenClaw sur Telegram est le billet du canal auquel ces symptômes appartiennent, et Le contrôle d’accès Telegram d’OpenClaw les listes d’autorisation derrière la plupart des groupes silencieux.

Lire le symptôme d’abord

Presque chaque correctif commence ici par une commande qui connaît déjà la réponse : la commande d’état avertit sur le mode privé et le sondage périmé, le doctor avertit sur les sondes manquantes, et les journaux listent les raisons de saut. Le comportement des messages Telegram dans OpenClaw explique le modèle de sondage que ces avertissements surveillent, et La protection contre les boucles de bots dans OpenClaw la garde qui empêche deux bots de se répondre l’un l’autre une fois que le vôtre parle enfin.

Sur Diali

Sur Diali, le canal Telegram se connecte depuis le tableau de bord et la configuration d’exécution est générée puis remplacée à chaque version, donc l’essentiel de cette liste est à surveiller de notre côté hébergé, tandis que le jeton, le réglage du mode privé dans BotFather et l’appartenance aux groupes restent du vôtre. Telegram sur Diali est le canal sur Diali et La sécurité chez Diali la frontière qui s’applique à chaque canal connecté.

• Pas de mention, pas de réponse : désactivez le mode privé et réajoutez le bot.
• Un 401 au démarrage désigne le jeton, pas le webhook.
• Les blocages redémarrent après 120 secondes ; les proxys ont besoin du DNS pour les médias.