Accueil › OpenClaw › Telegram

OpenClaw Telegram : connecter votre assistant IA en 5 minutes

Telegram est le canal le plus simple à configurer avec OpenClaw. Pas de QR code, pas de webhook obligatoire, pas de protocole non officiel : vous créez un bot via @BotFather, collez le token dans la config, et c’est parti. Le long-polling fonctionne sans exposer de port public, ce qui en fait le choix idéal pour un premier setup ou un serveur derrière un NAT.

Pourquoi Telegram est le meilleur premier canal

Si vous débutez avec OpenClaw, commencez par Telegram. Trois raisons concrètes.

Stabilité. L’intégration utilise l’API Bot officielle de Telegram, pas un protocole reverse-engineered comme pour WhatsApp. Les déconnexions sont quasi inexistantes. Pas de session QR à re-scanner, pas de risque de ban pour activité automatisée.

Simplicité. La configuration se résume à un token de bot. Créez un bot en 2 minutes avec @BotFather, copiez le token, collez-le dans la config OpenClaw. Le long-polling fonctionne sans IP publique, sans webhook, sans reverse proxy.

Fonctionnalités riches. Telegram supporte les fichiers jusqu’à 2 Go, le Markdown natif, les boutons inline, les réactions, les stickers, les forums avec topics, et les messages vocaux. C’est le canal le plus complet de l’écosystème OpenClaw.

Créer votre bot Telegram

Étape 1 : @BotFather

Ouvrez Telegram et cherchez @BotFather (vérifiez le handle exact, il y a des imitations). C’est le bot officiel de Telegram pour gérer les bots.

Envoyez /newbot et suivez les instructions. BotFather vous demande un nom d’affichage (peut contenir des espaces, ex: « Mon Assistant IA ») puis un username (doit se terminer par « bot », ex: « monassistant_bot »). Une fois créé, BotFather vous donne un token qui ressemble à 123456789:ABCdefGHIjklMNOpqrsTUVwxyz.

Étape 2 : Configurer les groupes dans BotFather (optionnel)

Si vous prévoyez d’ajouter votre bot à des groupes Telegram, configurez ces paramètres maintenant dans BotFather :

Envoyez /setjoingroups, sélectionnez votre bot, et choisissez « Enable » pour autoriser l’ajout aux groupes.

Par défaut, les bots Telegram ne voient que les messages qui les mentionnent (@votrebot). Pour voir tous les messages d’un groupe, vous pouvez désactiver le mode privacy dans BotFather (/setprivacy > Disable) ou rendre le bot administrateur du groupe. Les bots administrateurs voient tous les messages quel que soit le mode privacy.

Connecter Telegram à OpenClaw

Via le wizard d’onboarding

Si vous installez OpenClaw pour la première fois, sélectionnez Telegram quand le wizard demande les canaux. Collez le token de bot quand demandé. Le wizard valide le token et configure le canal automatiquement.

Ajouter Telegram après l’installation

# Méthode 1 : via la config
openclaw config set channels.telegram.enabled true
openclaw config set channels.telegram.botToken "VOTRE_TOKEN_BOT"
openclaw gateway restart

# Méthode 2 : via variable d'environnement (compte par défaut)
export TELEGRAM_BOT_TOKEN="VOTRE_TOKEN_BOT"
openclaw gateway restart

# Vérifier le status
openclaw channels status
# Doit afficher : Telegram default: enabled, configured, running, mode:polling

Contrairement à WhatsApp, Telegram n’utilise pas openclaw channels login. La configuration se fait entièrement via le fichier de config ou les variables d’environnement.

Tester le premier message

Ouvrez Telegram, cherchez votre bot par son username, et cliquez sur « Start ». Le bot vous renvoie un message de pairing :

OpenClaw: access not configured.
Your Telegram user id: 5077021035
Pairing code: Z2EDQKMK

Ce message signifie que la connexion Telegram fonctionne, mais que vous n’êtes pas encore autorisé. Deux options pour vous autoriser : entrez le code de pairing dans le dashboard OpenClaw, ou ajoutez votre user ID directement dans la config.

# Ajouter votre user ID à l'allowlist
openclaw config set channels.telegram.allowFrom '["5077021035"]'
openclaw gateway restart

Après autorisation, envoyez un message test. Si l’agent répond, tout est configuré.

Configuration avancée

Configuration type complète

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123456789:ABCdefGHI...",
      "dmPolicy": "pairing",
      "allowFrom": ["5077021035"],
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["5077021035"],
      "streamMode": "partial",
      "groups": {
        "*": {
          "requireMention": true
        }
      }
    }
  }
}

Politique de messages directs

Le champ dmPolicy contrôle qui peut interagir avec votre bot en message privé. L’option pairing (par défaut) exige un code de validation pour les nouveaux utilisateurs. L’option allowlist restreint l’accès aux seuls user IDs listés dans allowFrom.

Pour un bot personnel (un seul utilisateur), la configuration la plus robuste est dmPolicy: "allowlist" avec votre user ID explicite. C’est plus durable que de dépendre des approbations de pairing précédentes.

Pour trouver votre Telegram user ID : envoyez un message à votre bot et consultez les logs avec openclaw logs --follow (cherchez from.id). Alternative : utilisez @userinfobot ou @getidsbot sur Telegram.

Politique de groupes

Les groupes Telegram ont leur propre politique d’accès, indépendante des DMs. Depuis la version 2026.2.25, l’autorisation de groupe n’hérite plus des approbations de pairing DM. Vous devez configurer explicitement groupAllowFrom ou un allowFrom par groupe.

Le paramètre requireMention: true dans le bloc groups signifie que le bot ne répond que quand il est mentionné (@votrebot) ou quand quelqu’un répond directement à un de ses messages. C’est le comportement recommandé pour éviter le bruit.

Pour les Telegram Forums (groupes avec topics), chaque topic peut avoir ses propres paramètres (requireMention, allowFrom, skills, systemPrompt). Les topics héritent des paramètres du groupe sauf s’ils sont explicitement surchargés.

Streaming des réponses

OpenClaw peut streamer les réponses partielles dans Telegram via les « draft bubbles » : l’indicateur de saisie affiche le texte en cours de génération. C’est le mode streamMode: "partial", disponible uniquement en DM (pas en groupes).

Pour les groupes ou si vous préférez des messages complets plutôt que des drafts, activez le block streaming : channels.telegram.blockStreaming: true. L’agent envoie alors des messages entiers plutôt que des mises à jour progressives.

Multi-comptes

OpenClaw supporte plusieurs bots Telegram simultanés. Configurez les comptes sous channels.telegram.accounts.<id>. Définissez channels.telegram.defaultAccount pour le routage par défaut. Chaque compte peut avoir son propre allowFrom et groupAllowFrom.

Fonctionnalités Telegram spécifiques

Formatage et médias

Les réponses d’OpenClaw sont rendues en HTML Telegram (parse_mode: "HTML"). Le Markdown du modèle est converti en HTML compatible Telegram. Si Telegram rejette le HTML parsé, OpenClaw retente en texte brut. Les aperçus de liens sont activés par défaut et désactivables avec channels.telegram.linkPreview: false.

Les fichiers jusqu’à 2 Go sont supportés. Telegram distingue les notes vocales des fichiers audio, et les vidéos des vidéo-notes. Les stickers sont décrits une fois (quand possible) et mis en cache pour éviter les appels répétés au modèle de vision.

Réactions

Telegram supporte les réactions aux messages. Quand activé, OpenClaw enregistre les réactions comme des événements système. L’agent peut aussi envoyer des réactions via l’action react.

Commandes dans le menu Telegram

OpenClaw enregistre automatiquement les commandes disponibles dans le menu Telegram via setMyCommands au démarrage. Les commandes intégrées et les commandes custom/plugin s’affichent dans le menu de commandes du bot.

Mode webhook (optionnel)

Pour les déploiements à grande échelle qui nécessitent une latence plus basse, passez en mode webhook. Cela nécessite HTTPS et une URL publique.

openclaw config set channels.telegram.mode webhook
openclaw config set channels.telegram.webhookUrl "https://votre-domaine.com/webhook/telegram"
openclaw gateway restart

Le long-polling reste recommandé pour la plupart des cas d’usage : pas besoin d’IP publique, fonctionne derrière un NAT, et la latence est négligeable pour un assistant personnel.

Cas d’usage

Centre de commande mobile

Telegram devient votre interface mobile pour contrôler OpenClaw. Envoyez des instructions depuis votre téléphone, recevez des résultats, déclenchez des automatisations. Combiné avec les cron jobs d’OpenClaw, votre bot peut vous envoyer des résumés matinaux, des alertes de monitoring, ou des rappels de calendrier directement dans Telegram.

Groupes comme espaces de projets

Créez un groupe Telegram par projet et ajoutez votre bot. Chaque groupe devient un espace de travail isolé avec sa propre session, sa propre mémoire et ses propres skills. Utilisez les Telegram Forums (topics) pour segmenter encore plus : un topic pour le développement, un pour le design, un pour le marketing. L’agent garde le contexte séparé par topic.

Contrôle vocal

Envoyez des notes vocales à votre bot Telegram. OpenClaw transcrit le message via le speech-to-text configuré (Whisper, etc.), traite la demande, et peut répondre par texte ou par message vocal selon votre configuration. C’est un workflow mains-libres pratique en déplacement.

Automatisation et notifications

Combiné avec les outils d’OpenClaw (cron jobs, webhooks, Gmail Pub/Sub), Telegram devient un canal de notifications intelligent. Configurez des alertes proactives : résumé des emails non lus chaque matin à 8h, notification quand un déploiement échoue, rappel de réunion 15 minutes avant. L’agent vous envoie les alertes sur Telegram sans que vous ayez à demander quoi que ce soit.

Vous pouvez aussi déclencher des actions complexes par un simple message Telegram. Par exemple, envoyez « déploie la branche staging » et l’agent exécute le workflow de déploiement via les skills configurées. Ou demandez « résume les 3 derniers PRs sur le repo principal » et l’agent interroge l’API GitHub, analyse les changements et vous renvoie un résumé structuré.

Continuité avec d’autres canaux

L’un des atouts majeurs d’OpenClaw est la continuité de conversation entre canaux. Commencez une discussion sur Telegram depuis votre laptop, continuez sur WhatsApp depuis votre téléphone en mobilité, et reprenez sur le WebChat du dashboard au bureau. L’agent conserve le même contexte, la même mémoire et les mêmes projets en cours. C’est cette capacité multi-canal avec mémoire partagée qui distingue OpenClaw des assistants IA classiques cloisonnés dans une seule interface.

Sécurité

Quelques points de sécurité spécifiques à Telegram.

Sans allowlist, votre bot est ouvert. Si vous ne configurez ni pairing ni allowFrom, quiconque connaît le handle de votre bot peut lui envoyer des commandes. Configurez systématiquement une restriction d’accès, même pour un usage personnel.

Les group IDs ne vont pas dans groupAllowFrom. Le champ groupAllowFrom prend des user IDs (numériques, positifs). Les group/supergroup chat IDs (négatifs, ex: -1001234567890) vont sous channels.telegram.groups. Mélanger les deux est une erreur fréquente qui laisse des accès non prévus.

L’autorisation de groupe est séparée des DMs. Depuis la version 2026.2.25, les approbations de pairing en DM ne s’appliquent pas aux groupes. C’est une amélioration de sécurité : un utilisateur autorisé en DM n’est pas automatiquement autorisé dans les groupes.

Chaque token correspond à un seul Gateway. N’utilisez pas le même token de bot pour plusieurs instances OpenClaw. Si vous avez besoin de plusieurs agents, créez plusieurs bots.

Dépannage

Erreur 401 Unauthorized

Le token est invalide. Allez dans @BotFather, envoyez /mybots, sélectionnez votre bot, puis « API Token ». Copiez le token caractère par caractère (attention aux espaces en trop). Mettez à jour la config et redémarrez le Gateway.

Le bot reçoit les messages mais ne répond pas

Vérifiez les logs avec openclaw logs --follow. Si le message est reçu mais pas de réponse : vérifiez que la clé API du fournisseur LLM est valide (openclaw doctor), que tools.profile n’est pas sur disabled, et que l’utilisateur est bien dans l’allowlist ou a complété le pairing.

Le bot ne voit pas les messages de groupe

Le mode privacy de Telegram fait que les bots ne voient que les messages qui les mentionnent. Soit désactivez le privacy mode dans BotFather (/setprivacy > Disable), soit rendez le bot administrateur du groupe, soit gardez le comportement par défaut et mentionnez le bot quand vous voulez une réponse. N’oubliez pas de retirer et re-ajouter le bot après un changement de privacy.

Les réponses sont lentes

Le temps de réponse dépend du modèle LLM utilisé. Opus 4.6 est plus lent que Sonnet 4.6 ou Haiku 4.5. Si vous êtes sur un VPS limité en ressources, vérifiez la charge CPU/RAM avec htop. Pour les réponses les plus rapides, utilisez un modèle léger (Haiku, GPT-4o-mini) ou activez le streaming pour que l’utilisateur voie la réponse se construire en temps réel.

Migration depuis Clawdbot/Moltbot

Si vous avez mis à jour depuis Clawdbot ou Moltbot et que Telegram ne fonctionne plus, vérifiez qu’il n’y a pas de processus gateway dupliqués (ps aux | grep -E '(moltbot|clawdbot|openclaw).*gateway'). Stoppez les anciennes instances, et si nécessaire, copiez les données depuis ~/.clawdbot/ ou ~/.moltbot/ vers ~/.openclaw/.

Questions fréquentes