Guide complet de l'integration Telegram avec OpenClaw

Apercu

L'integration Telegram vous permet d'interagir avec OpenClaw via un bot Telegram dedie. OpenClaw utilise le framework grammY pour le long-polling par defaut, avec un support optionnel des webhooks pour les deploiements en production.

Prerequis

• OpenClaw installe et en cours d'execution
• Un compte Telegram

Etape 1 : Creer un bot Telegram

Parler a BotFather

1. Ouvrez Telegram et recherchez @BotFather
2. Demarrez une conversation et envoyez /newbot
3. Suivez les instructions :

You: /newbot

BotFather: Alright, a new bot. How are we going to call it?
           Please choose a name for your bot.

You: My OpenClaw Assistant

BotFather: Good. Now let's choose a username for your bot.
           It must end in `bot`. Like this, for example:
           TetrisBot or tetris_bot.

You: myopenclaw_bot

BotFather: Done! Congratulations on your new bot. You will find it at
           t.me/myopenclaw_bot. You can now add a description, about
           section and profile picture for your bot.

           Use this token to access the HTTP API:
           123456789:ABCdefGHIjklMNOpqrsTUVwxyz

           Keep your token secure and store it safely.

Sauvegardez le token du bot — vous en aurez besoin a l'etape suivante.

Desactiver le mode confidentialite (recommande pour les groupes)

Si vous prevoyez d'utiliser le bot dans des discussions de groupe, desactivez le mode confidentialite pour qu'il puisse lire tous les messages :

/setprivacy
@myopenclaw_bot
Disable

Apres avoir modifie le mode confidentialite, vous devez retirer puis re-ajouter le bot aux groupes existants pour que le changement prenne effet. Alternativement, promouvez le bot en administrateur du groupe — les bots administrateurs recoivent toujours tous les messages.

Etape 2 : Configurer OpenClaw

Stockage du token

Vous pouvez stocker le token du bot de deux facons. La configuration a la priorite sur la variable d'environnement.

Option A — Variable d'environnement :

# Ajouter a ~/.openclaw/.env
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz

Option B — Directement dans la configuration :

// ~/.openclaw/openclaw.json
{
  channels: {
    telegram: {
      botToken: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
    }
  }
}

Configuration minimale

Editez ~/.openclaw/openclaw.json :

{
  channels: {
    telegram: {
      // Token depuis la variable d'environnement TELEGRAM_BOT_TOKEN ou definissez botToken directement
    }
  }
}

C'est tout ce dont vous avez besoin — OpenClaw demarre automatiquement le long-polling lorsqu'un canal Telegram est configure.

Etape 3 : Tester votre bot

1. Ouvrez Telegram et recherchez le nom d'utilisateur de votre bot
2. Demarrez une conversation avec /start
3. Envoyez un message pour tester

Controle d'acces — Politique de messages prives

Controlez qui peut envoyer des messages a votre bot en conversation privee via dmPolicy :

| Politique | Comportement | |-----------|-------------| | "pairing" (par defaut) | Les expediteurs inconnus recoivent un code d'appairage expirant ; vous approuvez via le CLI | | "allowlist" | Seuls les IDs / @noms d'utilisateur dans allowFrom peuvent envoyer des messages | | "open" | N'importe qui peut envoyer des messages au bot | | "disabled" | Les messages prives sont entierement desactives |

Mode appairage (par defaut)

Lorsqu'un nouvel utilisateur envoie un message au bot, il recoit un code d'appairage. Approuvez-le avec :

# Lister les demandes d'appairage en attente
openclaw pairing list telegram

# Approuver un code specifique
openclaw pairing approve telegram <CODE>

Les codes d'appairage expirent apres 1 heure.

Mode liste d'autorisation

{
  channels: {
    telegram: {
      dmPolicy: "allowlist",
      allowFrom: [123456789, "@trusted_user"]
    }
  }
}

Mode ouvert

{
  channels: {
    telegram: {
      dmPolicy: "open"
    }
  }
}

Support des discussions de groupe

Activer l'acces aux groupes

Ajoutez les IDs de groupe a l'objet groups. Utilisez "*" pour autoriser tous les groupes :

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {},           // groupe specifique avec les parametres par defaut
        "-1009876543210": {             // groupe specifique avec des surcharges
          groupPolicy: "open",
          requireMention: false,
          systemPrompt: "You are a helpful coding assistant."
        }
      }
    }
  }
}

Ou autorisez tous les groupes :

{
  channels: {
    telegram: {
      groups: "*"
    }
  }
}

Politique de groupe

Controlez qui peut interagir avec le bot dans les groupes :

| Parametre | Description | |-----------|-------------| | groupPolicy: "open" | N'importe quel membre du groupe peut envoyer des messages au bot | | groupPolicy: "allowlist" | Seuls les expediteurs dans groupAllowFrom peuvent interagir | | groupPolicy: "disabled" | Le bot ignore tous les messages de groupe |

{
  channels: {
    telegram: {
      groupPolicy: "allowlist",
      groupAllowFrom: [123456789, "@allowed_user"]
    }
  }
}

Exigence de mention

Par defaut, le bot necessite une @mention dans les groupes. Vous pouvez modifier cela par groupe :

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          requireMention: false   // le bot repond a tous les messages
        }
      }
    }
  }
}

Ou utilisez la commande de session uniquement /activation always dans la discussion de groupe.

Surcharges par groupe

Chaque entree de groupe prend en charge ces champs :

| Champ | Description | |-------|-------------| | groupPolicy | Surcharger la politique de groupe globale | | requireMention | Si la @mention est requise | | skills | Competences disponibles dans ce groupe | | allowFrom | Liste d'autorisation des expediteurs pour ce groupe | | systemPrompt | Prompt systeme personnalise pour ce groupe | | enabled | Activer/desactiver pour ce groupe specifique |

Format des messages et decoupage

Mode d'analyse HTML

OpenClaw envoie les messages en utilisant le mode d'analyse HTML de Telegram (pas Markdown). Le Markdown du LLM est automatiquement converti en balises HTML compatibles. Si Telegram rejette le HTML, le message est renvoye en texte brut.

Decoupage du texte

Les messages longs sont divises en plusieurs messages Telegram :

{
  channels: {
    telegram: {
      textChunkLimit: 4000,    // nombre max de caracteres par message (par defaut : 4000)
      chunkMode: "newline"     // "length" (par defaut) ou "newline"
    }
  }
}

• "length" — decoupe a la limite de caracteres
• "newline" — decoupe aux limites de paragraphe avant d'appliquer la limite de longueur

Gestion des medias

Limite de taille des medias

{
  channels: {
    telegram: {
      mediaMaxMb: 5    // taille maximale du fichier en Mo (par defaut : 5)
    }
  }
}

Stickers

• Les stickers statiques (WEBP) sont traites par la vision et decrits au LLM
• Les stickers animes / video sont ignores
• Les descriptions de stickers sont mises en cache dans ~/.openclaw/telegram/sticker-cache.json pour eviter les appels de vision redondants

Pour permettre au bot d'envoyer des stickers :

{
  channels: {
    telegram: {
      actions: {
        sticker: true    // par defaut : false
      }
    }
  }
}

Historique et contexte

{
  channels: {
    telegram: {
      historyLimit: 50,        // contexte de groupe (par defaut : 50)
      dmHistoryLimit: 100      // contexte des messages prives
    }
  }
}

Surcharge par utilisateur en messages prives :

{
  channels: {
    telegram: {
      dms: {
        "123456789": {
          historyLimit: 200
        }
      }
    }
  }
}

Definissez a 0 pour desactiver l'historique.

Streaming

OpenClaw prend en charge le streaming base sur les brouillons dans les conversations privees (avec les sujets de forum actives) :

| Parametre | Description | |-----------|-------------| | streamMode: "off" | Streaming desactive (par defaut) | | streamMode: "partial" | Mises a jour continues d'un message brouillon | | streamMode: "block" | Mises a jour par blocs d'un message brouillon |

Parametres du mode bloc :

{
  channels: {
    telegram: {
      streamMode: "block",
      draftChunk: {
        minChars: 200,
        maxChars: 800,
        breakPreference: "paragraph"
      }
    }
  }
}

Mode Webhook (Production)

Pour les deploiements en production, utilisez les webhooks au lieu du long-polling :

{
  channels: {
    telegram: {
      webhookUrl: "https://your-domain.com/telegram-webhook",
      webhookSecret: "your-random-secret-string",
      webhookPath: "/telegram-webhook"    // chemin local, par defaut : /telegram-webhook
    }
  }
}

Le listener webhook se lie a 0.0.0.0:8787. Lorsque webhookUrl est defini, OpenClaw passe automatiquement du polling au mode webhook.

Commandes

Commandes natives

OpenClaw enregistre ces commandes dans le menu bot de Telegram au demarrage :

| Commande | Description | |----------|-------------| | /start | Message de bienvenue | | /status | Afficher le statut du bot | | /reset | Reinitialiser la conversation | | /model | Afficher / changer de modele |

Commandes personnalisees

Ajoutez des entrees de menu via la configuration (menu uniquement — elles ne s'executent pas sauf si elles sont gerees ailleurs) :

{
  channels: {
    telegram: {
      customCommands: [
        { command: "weather", description: "Get weather forecast" },
        { command: "translate", description: "Translate text" }
      ]
    }
  }
}

Les noms de commande doivent etre en minuscules a-z0-9_, de 1 a 32 caracteres. Le / initial est supprime automatiquement. Impossible de surcharger les commandes natives.

Boutons inline

Controlez la disponibilite des boutons inline :

| Parametre | Portee | |-----------|--------| | capabilities.inlineButtons: "off" | Desactive | | capabilities.inlineButtons: "dm" | Messages prives uniquement | | capabilities.inlineButtons: "group" | Groupes uniquement | | capabilities.inlineButtons: "all" | Messages prives et groupes | | capabilities.inlineButtons: "allowlist" | Les deux + filtrage des expediteurs (par defaut) |

Reseau et proxy

{
  channels: {
    telegram: {
      timeoutSeconds: 500,        // delai d'attente des requetes Bot API (par defaut : 500)
      network: {
        autoSelectFamily: false   // desactiver Happy Eyeballs (par defaut sur Node 22)
      },
      proxy: "socks5://127.0.0.1:1080"   // proxy SOCKS/HTTP pour l'API Bot
    }
  }
}

Depannage

Le bot ne repond pas

1. Verifiez que le token est correct :

curl "https://api.telegram.org/bot<TOKEN>/getMe"

2. Verifiez les logs d'OpenClaw :

openclaw logs --follow

Les messages n'atteignent pas les groupes

• Le mode confidentialite doit etre desactive (/setprivacy → Disable) ou le bot doit etre administrateur
• Testez avec /activation always (session uniquement) ; persistez via requireMention: false dans la configuration

Echecs de routage IPv6

Le bot peut cesser de repondre silencieusement si le routage IPv6 echoue. Verifiez le DNS pour api.telegram.org :

dig api.telegram.org AAAA

Corrigez en activant la sortie IPv6 ou en forcant IPv4 :

# Ajouter a /etc/hosts
149.154.167.220  api.telegram.org

Ou utilisez la configuration reseau :

{
  channels: {
    telegram: {
      network: {
        autoSelectFamily: false
      }
    }
  }
}

Interruptions du long-polling (Node 22+)

Node 22 est plus strict avec les instances AbortSignal. Mettez a jour OpenClaw vers la derniere version ou retrograder vers Node 20.

Echecs de setMyCommands

Le HTTPS/DNS sortant vers api.telegram.org peut etre bloque. Verifiez vos regles de pare-feu.

Bonnes pratiques de securite

1. Ne partagez jamais votre token de bot — revoquez-le immediatement via BotFather en cas de compromission
2. Utilisez l'appairage ou la liste d'autorisation pour le controle d'acces aux messages prives
3. Definissez des politiques de groupe pour controler qui peut interagir dans les groupes
4. Trouvez les IDs utilisateur en toute securite via openclaw logs --follow ou le endpoint getUpdates de l'API Bot — evitez les bots tiers de recherche d'ID
5. Utilisez les webhooks avec un secret pour les deploiements en production

Prochaines etapes

• Guide d'integration WhatsApp
• Guide d'integration Discord
• Documentation officielle du canal Telegram