Connecter OpenClaw à Telegram : bot, jeton et pairing

Un agent qui tourne sur un serveur ne sert à rien si vous ne pouvez pas lui parler. La force d’OpenClaw est de se brancher sur les messageries que vous utilisez déjà. Telegram est de loin la plus simple à connecter : pas de validation d’entreprise, pas de numéro vérifié, juste un bot et un jeton. À la fin de ce tutoriel, vous écrirez à votre assistant depuis votre téléphone et il vous répondra, où que vous soyez.

🎯 Ce que vous allez apprendre

• Créer un bot Telegram et récupérer son jeton auprès de BotFather.
• Déclarer le canal Telegram dans la configuration d’OpenClaw.
• Comprendre et choisir une politique d’accès aux messages privés.
• Appairer votre compte via le mécanisme de pairing sécurisé.
• Faire répondre l’agent dans un groupe sans qu’il réagisse à tout.

🛠️ Ce que vous allez construire

Vous allez transformer un agent muet en assistant joignable : un bot Telegram à votre nom, relié à votre passerelle OpenClaw, qui ne répond qu’à vous (et aux personnes que vous autorisez explicitement). C’est la « bouche et les oreilles » de l’assistant personnel que la série construit.

Prérequis

• OpenClaw installé et sa passerelle fonctionnelle (openclaw gateway status répond).
• L’application Telegram sur votre téléphone, avec un compte actif.
• Un éditeur de texte pour modifier ~/.openclaw/openclaw.json.
• Niveau : débutant. Test express : si vous savez ouvrir un fichier avec nano et coller un bloc, vous êtes prêt.
• ⏱️ Temps estimé : ~20 minutes.

Étape 1 — Créer le bot avec BotFather

Sur Telegram, les bots se créent eux-mêmes via un bot officiel nommé BotFather. C’est lui qui vous délivre le jeton d’authentification dont OpenClaw a besoin pour piloter votre bot. Attention à l’orthographe exacte : un faux BotFather qui usurpe le nom pourrait récupérer votre jeton.

Dans la barre de recherche de Telegram, cherchez @BotFather et vérifiez qu’il porte bien le badge de compte vérifié. Ouvrez la conversation et lancez la commande de création :

/newbot

BotFather vous demande un nom d’affichage (libre, par exemple « Assistant perso ») puis un identifiant unique qui doit se terminer par bot (par exemple monassistant_perso_bot). Une fois validé, il affiche un message contenant votre jeton, de la forme 123456789:AAExxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.

✅ Point d’étape — vous avez un jeton en main. Traitez-le comme un mot de passe : quiconque le possède peut piloter votre bot. Ne le collez jamais dans un dépôt public ni dans un message.

Étape 2 — Déclarer Telegram dans la configuration

OpenClaw lit ses canaux depuis ~/.openclaw/openclaw.json. Le format est du JSON5 : il tolère les commentaires et les virgules finales, ce qui le rend plus confortable qu’un JSON strict. Telegram est un canal intégré — il se déclare sous channels.telegram, surtout pas sous une section de plugins.

Ouvrez le fichier et ajoutez (ou complétez) le bloc channels :

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123456789:AAExxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      dmPolicy: "pairing"
    }
  }
}

Le champ enabled active le canal, botToken reçoit le jeton de l’étape 1, et dmPolicy définit qui peut écrire à l’agent en privé. Nous gardons "pairing", la valeur par défaut et la plus sûre : tout inconnu devra prouver qu’il est autorisé avant que l’agent ne lui réponde.

Si vous préférez ne pas écrire le jeton en clair dans le fichier, OpenClaw lit aussi la variable d’environnement TELEGRAM_BOT_TOKEN (pour le compte par défaut). C’est l’option recommandée sur un serveur partagé.

Étape 3 — Relancer la passerelle

Toute modification de la configuration n’est prise en compte qu’après un redémarrage de la passerelle. C’est le réflexe à garder pendant toute la série : on édite, on relance, on vérifie.

openclaw gateway stop
openclaw gateway status

Si le service système est installé, il redémarre tout seul après l’arrêt ; sinon relancez avec openclaw gateway. Au démarrage, les journaux doivent mentionner l’initialisation du canal Telegram. Si vous voyez une erreur d’authentification, le jeton est mal copié — un espace ou un retour à la ligne parasite suffit à le casser.

✅ Point d’étape — les journaux de la passerelle indiquent que Telegram est connecté, sans erreur de jeton. Le bot est en ligne ; il ne répond simplement pas encore aux inconnus.

Étape 4 — Appairer votre compte

Avec la politique pairing, le premier message d’un inconnu ne reçoit pas de réponse directe : l’agent réclame une validation. C’est exactement ce qui protège votre assistant d’un usage par n’importe qui ayant deviné le nom du bot. Le déroulé est en deux temps : vous écrivez au bot, puis vous approuvez côté serveur.

Ouvrez la conversation avec votre bot sur Telegram et envoyez un simple message, par exemple « bonjour ». Le bot répond qu’un appairage est nécessaire et un code apparaît dans les journaux ou via la commande de listing. Sur le serveur, listez les demandes en attente :

openclaw pairing list telegram

La commande affiche les codes d’appairage en attente avec l’identifiant qui les a demandés. Approuvez le vôtre :

openclaw pairing approve telegram <CODE>

Remplacez <CODE> par la valeur affichée. Attention : les codes d’appairage expirent au bout d’une heure ; si vous tardez, renvoyez un message au bot pour en générer un nouveau. Une fois approuvé, écrivez de nouveau au bot : il vous répond enfin. Votre compte est désormais reconnu comme un interlocuteur de confiance.

✅ Point d’étape — vous envoyez un message au bot et il répond. L’aller-retour fonctionne de bout en bout, depuis votre téléphone jusqu’à la passerelle et retour.

Étape 5 — Autoriser explicitement un compte (option)

Le pairing convient pour s’ajouter soi-même. Mais si vous connaissez déjà l’identifiant numérique d’un utilisateur à autoriser, vous pouvez l’inscrire directement dans la liste blanche allowFrom, ce qui lui évite l’étape d’appairage. C’est pratique pour donner accès à un proche de confiance.

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123456789:AAExxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      dmPolicy: "pairing",
      allowFrom: ["987654321"]
    }
  }
}

La valeur est l’identifiant numérique Telegram de l’utilisateur (un nombre, pas le pseudo @). Après modification, relancez la passerelle. Notez que dmPolicy accepte aussi "allowlist" (seuls les comptes de allowFrom passent, sans pairing possible), "open" (tout le monde, à proscrire) et "disabled" (aucun message privé).

Étape 6 — Faire répondre l’agent dans un groupe

Dans un groupe, vous ne voulez pas que l’agent réagisse à chaque message — seulement quand on l’interpelle. OpenClaw gère cela via la section groups, indexée par l’identifiant du groupe, avec l’option requireMention qui n’active l’agent que lorsqu’on le mentionne par son nom.

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123456789:AAExxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      dmPolicy: "pairing",
      groups: {
        "-1001234567890": { requireMention: true }
      }
    }
  }
}

L’identifiant d’un supergroupe Telegram est un nombre négatif commençant par -100 ; il se place comme clé sous groups (et non dans une liste d’utilisateurs). Avec requireMention: true, l’agent reste silencieux tant qu’on n’écrit pas @monassistant_perso_bot suivi de la demande. Relancez la passerelle, mentionnez le bot dans le groupe, et vérifiez qu’il ne répond que là.

Étape 7 — Vérification finale

Bouclez en confirmant les deux modes d’usage. En message privé, écrivez une demande simple à l’agent (« quelle heure est-il là où tu tournes ? ») : il répond. Dans un groupe configuré, vérifiez qu’il ignore les messages ordinaires et ne réagit qu’à une mention. Si ces deux comportements sont au rendez-vous, votre canal Telegram est correctement câblé et sécurisé par défaut.

🐞 Pièges fréquents

🌍 Une messagerie déjà dans toutes les poches

Le choix de Telegram n’est pas anodin : c’est l’une des messageries les plus répandues, gratuite, peu gourmande en données et fonctionnelle même sur une connexion mobile modeste. Piloter son agent par Telegram évite d’ouvrir un port web, de payer un nom de domaine ou de gérer un certificat : la passerelle se connecte sortante vers les serveurs de Telegram, donc même un agent hébergé derrière une box domestique ou sur un VPS sans IP publique dédiée reste joignable. Pour qui paie l’API du modèle en devises, ce zéro coût d’infrastructure de messagerie est appréciable. Si vous visez plus tard WhatsApp, sachez que c’est faisable mais nettement plus contraignant à mettre en place que Telegram — d’où l’intérêt de commencer ici.

✅ Récapitulatif

Vous avez créé un bot Telegram, récupéré son jeton, déclaré le canal dans openclaw.json, relancé la passerelle, appairé votre compte par le mécanisme de pairing, puis réglé le comportement en groupe avec requireMention. Votre assistant est désormais joignable depuis votre téléphone, et il ne répond qu’aux personnes que vous avez validées. Reste à lui donner un cerveau capable de raisonner : c’est le rôle du modèle de langage.

🧾 Aide-mémoire

💪 À vous de jouer

Défi : autorisez un deuxième compte (un proche) à utiliser votre agent en message privé, sans qu’il ait à passer par le pairing.

allowFrom: ["987654321", "555111222"]

Tutoriels frères

• Configurer un modèle LLM dans OpenClaw — donner un cerveau à l’agent qui répond maintenant sur Telegram.
• Sécuriser un agent OpenClaw auto-hébergé — durcir les accès au-delà du pairing.

Pour aller plus loin

• 🔝 Retour au guide principal : OpenClaw, panorama et mise en route.
• Documentation officielle du canal Telegram : docs.openclaw.ai/channels/telegram.

Bien choisir sa politique d’accès

Le champ dmPolicy est la décision de sécurité la plus importante de ce tutoriel, parce qu’il détermine qui peut faire agir votre assistant — et donc lancer des commandes en votre nom. Comprendre les quatre valeurs évite de laisser une porte ouverte par mégarde.

• pairing (défaut) — un inconnu doit demander un code, que vous approuvez manuellement. Bon compromis : ouvert à vous, fermé au reste tant que vous n’avez rien validé.
• allowlist — seuls les identifiants présents dans allowFrom sont acceptés ; aucun appairage n’est proposé aux autres. C’est le réglage le plus strict, idéal sur un serveur exposé.
• open — l’agent répond à n’importe qui. À réserver à des démonstrations très encadrées : un agent ouvert sur Internet peut être détourné par un inconnu.
• disabled — aucun message privé n’est traité ; utile si vous ne voulez piloter l’agent qu’en groupe.

La logique est celle du moindre privilège : commencez fermé (allowlist ou pairing), ouvrez seulement si un besoin précis l’exige. Un assistant personnel qui peut lire vos fichiers et lancer des commandes ne devrait jamais être en open.

Trouver son identifiant Telegram numérique

Pour remplir allowFrom, il vous faut un identifiant numérique, pas un pseudo. Telegram ne l’affiche pas dans l’interface, mais plusieurs bots d’information de compte le renvoient en un message. Le plus fiable reste cependant le mécanisme de pairing lui-même : quand vous écrivez au bot, l’identifiant du demandeur apparaît dans openclaw pairing list telegram à côté du code. Vous pouvez donc relever votre propre identifiant à ce moment-là, puis le figer dans allowFrom pour ne plus jamais avoir à vous réappairer après une réinstallation.

FAQ

Faut-il un numéro de téléphone dédié pour le bot ?
Non. Un bot Telegram n’a pas de numéro : il s’authentifie par son jeton. Votre propre compte (avec votre numéro) sert seulement à dialoguer avec lui.

Le pairing est-il obligatoire ?
Non, mais c’est le réglage par défaut et le plus sûr. Vous pouvez vous en passer en listant les comptes dans allowFrom avec dmPolicy: "allowlist", ce qui interdit tout compte non listé.

Puis-je connecter plusieurs messageries en même temps ?
Oui. La passerelle gère plusieurs canaux simultanément. Vous pouvez ajouter d’autres entrées sous channels et l’agent répondra sur chacune, en gardant le contexte par interlocuteur.

Mon jeton a fuité, que faire ?
Retournez voir BotFather et utilisez sa commande de révocation pour régénérer un jeton. L’ancien devient immédiatement inutilisable ; mettez le nouveau dans la configuration et relancez la passerelle.