Telegram

Statut : prêt pour la production pour les DM de bot + groupes via grammY. Le long polling est le mode par défaut ; le mode webhook est optionnel.

Configuration rapide

Étape 1 : Créer le token du bot dans BotFather

Ouvrez Telegram et discutez avec @BotFather (vérifiez que le pseudo est exactement @BotFather). Exécutez /newbot, suivez les invites et sauvegardez le token.

Étape 2 : Configurer le token et la politique DM

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } },
    },
  },
}

Fallback d'environnement : TELEGRAM_BOT_TOKEN=... (compte par défaut uniquement). Telegram n'utilise pas openclaw channels login telegram ; configurez le token dans config/env, puis démarrez la passerelle.

Étape 3 : Démarrer la passerelle et approuver le premier DM

openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

Les codes d'appairage expirent après 1 heure.

Étape 4 : Ajouter le bot à un groupe

Ajoutez le bot à votre groupe, puis définissez channels.telegram.groups et groupPolicy pour correspondre à votre modèle d'accès.

ℹ️ L'ordre de résolution du token tient compte du compte. En pratique, les valeurs de configuration priment sur le fallback d'environnement, et TELEGRAM_BOT_TOKEN ne s'applique qu'au compte par défaut.

Paramètres côté Telegram

Contrôle d'accès et activation

curl "https://api.telegram.org/bot<bot_token>/getUpdates"

Comportement d'exécution

• Telegram est détenu par le processus de la passerelle.
• Le routage est déterministe : les réponses entrantes de Telegram reviennent vers Telegram (le modèle ne choisit pas les canaux).
• Les messages entrants sont normalisés dans l'enveloppe de canal partagée avec les métadonnées de réponse et les espaces réservés pour les médias.
• Les sessions de groupe sont isolées par ID de groupe. Les sujets de forum ajoutent :topic:<threadId> pour garder les sujets isolés.
• Les messages DM peuvent porter un message_thread_id ; OpenClaw les route avec des clés de session sensibles au fil de discussion et préserve l'ID du fil pour les réponses.
• Le long polling utilise grammY runner avec un séquencement par chat/par fil de discussion. La concurrence globale du récepteur runner utilise agents.defaults.maxConcurrent.
• L'API Bot de Telegram ne prend pas en charge les accusés de lecture (sendReadReceipts ne s'applique pas).

Référence des fonctionnalités

Dépannage

Plus d'aide : Dépannage des canaux.

Pointeurs de référence de configuration Telegram

Référence principale :

• channels.telegram.enabled : activer/désactiver le démarrage du canal.
• channels.telegram.botToken : token du bot (BotFather).
• channels.telegram.tokenFile : lire le token depuis un chemin de fichier.
• channels.telegram.dmPolicy : pairing | allowlist | open | disabled (par défaut : pairing).
• channels.telegram.allowFrom : liste autorisée DM (ID utilisateur Telegram numériques). allowlist nécessite au moins un ID d'expéditeur. open nécessite "*". openclaw doctor --fix peut résoudre les entrées héritées @username en ID et peut récupérer les entrées de liste autorisée à partir des fichiers de stockage d'appairage dans les flux de migration de liste autorisée.
• channels.telegram.actions.poll : activer ou désactiver la création de sondages Telegram (par défaut : activé ; nécessite toujours sendMessage).
• channels.telegram.defaultTo : cible Telegram par défaut utilisée par la CLI --deliver lorsqu'aucun --reply-to explicite n'est fourni.
• channels.telegram.groupPolicy : open | allowlist | disabled (par défaut : allowlist).
• channels.telegram.groupAllowFrom : liste autorisée des expéditeurs de groupe (ID utilisateur Telegram numériques). openclaw doctor --fix peut résoudre les entrées héritées @username en ID. Les entrées non numériques sont ignorées au moment de l'authentification. L'authentification de groupe n'utilise pas le fallback de stockage d'appairage DM (2026.2.25+).
• Prépondérance multi-compte :
  • Lorsque deux ID de compte ou plus sont configurés, définissez channels.telegram.defaultAccount (ou incluez channels.telegram.accounts.default) pour rendre le routage par défaut explicite.
  • Si aucun n'est défini, OpenClaw revient au premier ID de compte normalisé et openclaw doctor avertit.
  • channels.telegram.accounts.default.allowFrom et channels.telegram.accounts.default.groupAllowFrom s'appliquent uniquement au compte default.
  • Les comptes nommés héritent de channels.telegram.allowFrom et channels.telegram.groupAllowFrom lorsque les valeurs au niveau du compte ne sont pas définies.
  • Les comptes nommés n'héritent pas de channels.telegram.accounts.default.allowFrom / groupAllowFrom.
• channels.telegram.groups : valeurs par défaut par groupe + liste autorisée (utilisez "*" pour les valeurs par défaut globales).
  • channels.telegram.groups.<id>.groupPolicy : remplacement par groupe pour groupPolicy (open | allowlist | disabled).
  • channels.telegram.groups.<id>.requireMention : restriction de mention par défaut.
  • channels.telegram.groups.<id>.skills : filtre de compétences (omis = toutes les compétences, vide = aucune).
  • channels.telegram.groups.<id>.allowFrom : remplacement de liste autorisée des expéditeurs par groupe.
  • channels.telegram.groups.<id>.systemPrompt : invite système supplémentaire pour le groupe.
  • channels.telegram.groups.<id>.enabled : désactiver le groupe lorsque false.
  • channels.telegram.groups.<id>.topics.<threadId>.* : remplacements par sujet (champs de groupe + agentId spécifique au sujet).
  • channels.telegram.groups.<id>.topics.<threadId>.agentId : router ce sujet vers un agent spécifique (remplace le routage au niveau du groupe et des liaisons).
  • channels.telegram.groups.<id>.topics.<threadId>.groupPolicy : remplacement par sujet pour groupPolicy (open | allowlist | disabled).
  • `ch