Telegram

Par défaut, les bots Telegram utilisent le Privacy Mode, qui limite les messages de groupe qu’ils reçoivent.

Pour voir tous les messages de groupe :

• désactivez le mode de confidentialité via /setprivacy, ou
• nommez le bot administrateur du groupe.

Après avoir modifié le mode de confidentialité, retirez puis ajoutez de nouveau le bot dans chaque groupe afin que Telegram applique la modification.

Le statut d’administrateur se contrôle dans les paramètres du groupe Telegram. Les bots administrateurs reçoivent tous les messages du groupe, ce qui est utile pour un fonctionnement permanent dans les groupes.

• /setjoingroups — autoriser ou refuser l’ajout aux groupes
• /setprivacy — comportement de visibilité dans les groupes

Les mêmes paramètres sont disponibles dans l’application web de BotFather si vous préférez une interface aux commandes de discussion.

OpenClaw diffuse les réponses partielles en temps réel dans les discussions directes, les groupes et les sujets : il envoie un message d’aperçu, puis exécute editMessageText de manière répétée avant de finaliser le message sur place.

• channels.telegram.streaming est off | partial | block | progress (valeur par défaut : partial)
• les courts aperçus de réponse initiaux sont temporisés, puis matérialisés après un délai limité si l’exécution est toujours active
• progress conserve un unique brouillon d’état modifiable pour la progression des outils, affiche le libellé d’état stable lorsque l’activité de réponse commence avant la progression des outils, l’efface à la fin et envoie la réponse finale comme un message normal
• streaming.preview.toolProgress détermine si les mises à jour des outils et de la progression réutilisent le même message d’aperçu modifié (valeur par défaut : true lorsque la diffusion de l’aperçu est active)
• streaming.preview.commandText contrôle le niveau de détail des commandes et de leur exécution dans ces lignes : raw (valeur par défaut) ou status (libellé de l’outil uniquement)
• streaming.progress.commentary (valeur par défaut : false) permet d’inclure le commentaire et le préambule de l’assistant dans le brouillon de progression temporaire
• l’ancien channels.telegram.streamMode, les valeurs booléennes streaming et les clés d’aperçu de brouillon natif retirées sont détectés ; exécutez openclaw doctor --fix pour les migrer

Les lignes de progression des outils sont les brèves mises à jour d’état affichées pendant l’exécution des outils (exécution de commandes, lecture de fichiers, mises à jour de planification, résumés de correctifs, préambule et commentaires Codex en mode serveur d’application). Telegram les conserve activées par défaut (ce qui correspond au comportement publié depuis v2026.4.22+).

Pour conserver les modifications de l’aperçu de la réponse tout en masquant les lignes de progression des outils :

{  "channels": {    "telegram": {      "streaming": {        "mode": "partial",        "preview": { "toolProgress": false }      }    }  }}

Pour garder la progression des outils visible tout en masquant le texte des commandes et de leur exécution :

{  "channels": {    "telegram": {      "streaming": {        "mode": "partial",        "preview": { "commandText": "status" }      }    }  }}

Le mode progress affiche la progression des outils sans intégrer la réponse finale à ce message par modification. Placez la stratégie relative au texte des commandes sous streaming.progress :

{  "channels": {    "telegram": {      "streaming": {        "mode": "progress",        "progress": {          "toolProgress": true,          "commandText": "status"        }      }    }  }}

streaming.mode: "off" désactive les modifications d’aperçu et supprime les messages génériques relatifs aux outils et à la progression au lieu de les envoyer sous forme de messages d’état autonomes ; les demandes d’approbation, les médias et les erreurs sont toujours acheminés par la livraison finale normale. streaming.preview.toolProgress: false ne conserve que les modifications de l’aperçu de la réponse.

Pour les réponses contenant uniquement du texte : les aperçus courts sont remplacés sur place par la modification finale ; les longues réponses finales divisées en plusieurs messages réutilisent l’aperçu comme premier fragment, puis n’envoient que le reste ; les réponses finales en mode progression effacent le brouillon d’état et utilisent la livraison finale normale ; si la modification finale échoue avant la confirmation de l’achèvement, OpenClaw revient à la livraison finale normale et supprime l’aperçu obsolète. Pour les réponses complexes (charges utiles multimédias), OpenClaw revient toujours à la livraison finale normale et supprime l’aperçu.

La diffusion de l’aperçu et la diffusion par blocs sont mutuellement exclusives — lorsque la diffusion par blocs est explicitement activée, OpenClaw ignore le flux d’aperçu afin d’éviter une double diffusion.

Raisonnement : /reasoning stream diffuse le raisonnement dans l’aperçu en direct pendant la génération, puis supprime l’aperçu du raisonnement après la livraison finale (utilisez /reasoning on pour le conserver visible). La réponse finale est envoyée sans le texte du raisonnement.

Par défaut, le texte sortant utilise les messages HTML standard de Telegram, lisibles dans les clients actuels : gras, italique, liens, code, divulgâcheurs, citations — et non les blocs enrichis exclusifs de Bot API 10.2 (tableaux natifs, détails, médias enrichis, formules).

Pour activer les messages enrichis de Bot API 10.2 :

{channels: {telegram: {  richMessages: true,},},}

Lorsqu’ils sont activés : l’agent est informé que les messages enrichis sont disponibles pour ce bot ou ce compte (avec le contrat de création Markdown et d’îlots HTML pris en charge) ; le texte Markdown est rendu par l’intermédiaire de la représentation intermédiaire Markdown d’OpenClaw sous forme de blocs enrichis typés de Bot API 10.2 (titres, tableaux, détails, listes de contrôle, médias enrichis, formules, cartes, collages) ; les légendes de médias utilisent toujours les légendes HTML de Telegram (les messages enrichis ne remplacent pas les légendes, qui restent limitées à 1024 caractères).

Cela évite que le texte du modèle soit interprété selon les symboles du Markdown enrichi de Telegram, afin que les montants tels que $400-600K ne soient pas analysés comme des expressions mathématiques. Les longs textes enrichis sont automatiquement divisés selon les limites de Telegram. Les tableaux dépassant la limite de 20 colonnes sont remplacés par un bloc de code.

Valeur par défaut : désactivé, pour assurer la compatibilité des clients — certains clients actuels pour ordinateur, Web, Android et tiers affichent les messages enrichis acceptés comme non pris en charge. Laissez cette option désactivée sauf si tous les clients utilisés avec le bot peuvent afficher ces messages. /status indique si les messages enrichis sont activés ou désactivés pour la session actuelle.

Les aperçus de liens sont activés par défaut. channels.telegram.linkPreview: false désactive la détection automatique des entités pour le texte enrichi.

Le menu de commandes de Telegram est enregistré au démarrage avec setMyCommands. commands.native: "auto" active les commandes natives pour Telegram.

Pour ajouter des entrées personnalisées au menu de commandes :

{channels: {telegram: {  customCommands: [    { command: "backup", description: "Sauvegarde Git" },    { command: "generate", description: "Créer une image" },  ],},},}

Règles : les noms sont normalisés (suppression du préfixe /, conversion en minuscules) ; motif valide a-z, 0-9, _, longueur de 1-32 ; les commandes personnalisées ne peuvent pas remplacer les commandes natives ; les conflits et doublons sont ignorés et consignés.

Les commandes personnalisées ne sont que des entrées de menu — elles n’implémentent pas automatiquement de comportement. Les commandes de Plugin ou de compétence peuvent toujours fonctionner lorsqu’elles sont saisies, même si elles ne figurent pas dans le menu Telegram. Si les commandes natives sont désactivées, les commandes intégrées sont supprimées ; les commandes personnalisées ou de Plugin peuvent toujours être enregistrées si elles sont configurées.

Échecs de configuration courants :

• setMyCommands failed avec BOT_COMMANDS_TOO_MUCH après une nouvelle tentative de réduction signifie que le menu dépasse encore la limite ; réduisez le nombre de commandes de Plugin, de compétence ou personnalisées, ou désactivez channels.telegram.commands.native.
• Si deleteWebhook, deleteMyCommands ou setMyCommands échoue avec 404: Not Found alors que les commandes curl directes de Bot API fonctionnent, cela signifie généralement que channels.telegram.apiRoot a été défini sur le point de terminaison /bot<TOKEN> complet. apiRoot doit uniquement correspondre à la racine de Bot API ; openclaw doctor --fix supprime un suffixe /bot<TOKEN> ajouté par erreur.
• getMe returned 401 signifie que Telegram a rejeté le jeton de bot configuré. Mettez à jour botToken, tokenFile ou TELEGRAM_BOT_TOKEN (compte par défaut) avec le jeton BotFather actuel ; OpenClaw s’arrête avant l’interrogation afin que cette erreur ne soit pas signalée comme un échec de nettoyage du Webhook.
• setMyCommands failed accompagné d’erreurs de réseau ou de récupération signifie généralement que les connexions DNS/HTTPS sortantes vers api.telegram.org sont bloquées.

Commandes d’association d’appareils (Plugin device-pair)

Une fois installé :

1. /pair génère un code de configuration
2. collez le code dans l’application iOS
3. /pair pending répertorie les demandes en attente (y compris le rôle et les portées)
4. approuver : /pair approve <requestId>, /pair approve (seule demande en attente) ou /pair approve latest

Si un appareil effectue une nouvelle tentative avec des informations d’authentification modifiées (rôle, portées, clé publique), la demande précédente en attente est remplacée par une nouvelle demande requestId ; réexécutez /pair pending avant de l’approuver.

Plus de détails : Association.

Configurez la portée du clavier intégré :

{channels: {telegram: {  capabilities: {    inlineButtons: "allowlist",  },},},}

Remplacement par compte :

{channels: {telegram: {  accounts: {    main: {      capabilities: {        inlineButtons: "allowlist",      },    },  },},},}

Portées : off, dm, group, all, allowlist (valeur par défaut). L’ancien capabilities: ["inlineButtons"] correspond à "all".

Exemple d’action de message :

{action: "send",channel: "telegram",to: "123456789",message: "Choisissez une option :",buttons: [[  { text: "Oui", callback_data: "yes" },  { text: "Non", callback_data: "no" },],[{ text: "Annuler", callback_data: "cancel" }],],}

Exemple de bouton Mini App :

{action: "send",channel: "telegram",to: "123456789",message: "Ouvrir l’application :",presentation: {blocks: [  {    type: "buttons",    buttons: [{ label: "Lancer", web_app: { url: "https://example.com/app" } }],  },],},}

Les boutons web_app fonctionnent uniquement dans les discussions privées entre un utilisateur et le bot.

Les clics de rappel non revendiqués par un gestionnaire interactif de plugin enregistré sont transmis à l’agent sous forme de texte : callback_data: <value>.

Actions :

• sendMessage (to, content, mediaUrl facultatif, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content ou caption, boutons intégrés presentation facultatifs ; les modifications portant uniquement sur les boutons mettent à jour le balisage de réponse)
• createForumTopic (chatId, name, iconColor facultatif, iconCustomEmojiId)

Alias pratiques : send, react, delete, edit, sticker, sticker-search, topic-create.

Contrôle d’activation : channels.telegram.actions.sendMessage, deleteMessage, reactions, sticker (valeur par défaut : désactivé). edit, createForumTopic et editForumTopic sont activés par défaut sans option dédiée. Les envois à l’exécution utilisent l’instantané actif de la configuration et des secrets créé au démarrage ou au rechargement ; les chemins d’action ne résolvent donc pas à nouveau les valeurs SecretRef à chaque envoi.

Sémantique de suppression des réactions : /tools/reactions.

Balises explicites de fils de réponse dans la sortie générée :

• [[reply_to_current]] — répond au message déclencheur
• [[reply_to:<id>]] — répond à un ID de message précis

channels.telegram.replyToMode : off (valeur par défaut), first, all.

Lorsque les fils de réponse sont activés et que le texte ou la légende d’origine est disponible, OpenClaw ajoute automatiquement un extrait de citation natif. Telegram limite le texte des citations natives à 1024 unités de code UTF-16 ; les messages plus longs sont cités à partir du début et utilisent une réponse simple comme solution de repli si Telegram rejette la citation.

off désactive uniquement les fils de réponse implicites ; les balises [[reply_to_*]] explicites sont toujours respectées.

Supergroupes de forum : les clés de session des sujets ajoutent :topic:<threadId> ; les réponses et l’indicateur de saisie ciblent le fil du sujet ; le chemin de configuration du sujet est channels.telegram.groups.<chatId>.topics.<threadId>.

Le sujet général (threadId=1) constitue un cas particulier : les envois de messages omettent message_thread_id (Telegram rejette sendMessage(...thread_id=1) avec « thread not found »), mais les actions de saisie incluent toujours message_thread_id (nécessaire empiriquement pour que l’indicateur de saisie apparaisse).

Les entrées de sujet héritent des paramètres du groupe sauf s’ils sont remplacés (requireMention, allowFrom, skills, systemPrompt, enabled, groupPolicy). agentId est propre aux sujets et n’hérite pas des valeurs par défaut du groupe. topics."*" définit les valeurs par défaut de chaque sujet de ce groupe ; les ID de sujet exacts restent prioritaires sur "*".

Routage des agents par sujet : chaque sujet peut être routé vers un agent différent au moyen de agentId dans la configuration du sujet, ce qui lui fournit son propre espace de travail, sa propre mémoire et sa propre session :

{  channels: {    telegram: {      groups: {        "-1001234567890": {          topics: {            "1": { agentId: "main" },      // Sujet général -> agent principal            "3": { agentId: "zu" },        // Sujet de développement -> agent zu            "5": { agentId: "coder" }      // Revue de code -> agent coder          }        }      }    }  }}

Chaque sujet possède alors sa propre clé de session, par exemple agent:zu:telegram:group:-1001234567890:topic:3.

Liaison persistante d’un sujet à ACP : les sujets de forum peuvent épingler des sessions de harnais ACP au moyen de liaisons typées de premier niveau (bindings[] avec type: "acp", match.channel: "telegram", peer.kind: "group" et un ID qualifié par sujet tel que -1001234567890:topic:42). Cette fonctionnalité est actuellement limitée aux sujets de forum dans les groupes et supergroupes. Consultez Agents ACP.

Création d’une session ACP liée au fil depuis la discussion : /acp spawn <agent> --thread here|auto lie le sujet actuel à une nouvelle session ACP ; les messages suivants y sont directement routés et OpenClaw épingle la confirmation de création dans le sujet. Nécessite channels.telegram.threadBindings.spawnSessions (valeur par défaut : true).

Le contexte du modèle expose MessageThreadId et IsForum. Les discussions par message privé avec message_thread_id conservent les métadonnées de réponse, mais utilisent des clés de session tenant compte des fils uniquement lorsque getMe de Telegram indique has_topics_enabled: true. Les remplacements retirés dm.threadReplies et direct.*.threadReplies ont disparu ; le mode avec fils de BotFather constitue l’unique source de vérité. Exécutez openclaw doctor --fix pour supprimer les clés de configuration obsolètes.

Messages audio

Telegram distingue les notes vocales des fichiers audio. Par défaut, le comportement est celui d’un fichier audio ; ajoutez la balise [[audio_as_voice]] dans la réponse de l’agent pour forcer l’envoi d’une note vocale. Les transcriptions de notes vocales entrantes sont présentées dans le contexte de l’agent comme du texte non fiable généré par une machine, mais la détection des mentions utilise toujours la transcription brute afin que les messages vocaux soumis à une exigence de mention continuent de fonctionner.

{action: "send",channel: "telegram",to: "123456789",media: "https://example.com/voice.ogg",asVoice: true,}

Messages vidéo

Telegram distingue les fichiers vidéo des notes vidéo. Les notes vidéo ne prennent pas en charge les légendes ; le texte de message fourni est envoyé séparément.

{action: "send",channel: "telegram",to: "123456789",media: "https://example.com/video.mp4",asVideoNote: true,}

Emplacements et lieux

Utilisez l’action send existante avec un seul objet location autonome. Les coordonnées envoient une épingle native ; l’ajout simultané de name et address envoie une fiche de lieu native. Les envois d’emplacement ne peuvent pas être combinés avec du texte de message ou un média.

{action: "send",channel: "telegram",to: "123456789",location: {latitude: 48.858844,longitude: 2.294351,accuracy: 12,name: "Tour Eiffel",address: "Champ de Mars, Paris",},}

Autocollants

À la réception : les fichiers WEBP statiques sont téléchargés et traités (espace réservé <media:sticker>) ; les fichiers TGS animés et les vidéos WEBM sont ignorés.

Champs de contexte des autocollants : Sticker.emoji, Sticker.setName, Sticker.fileId, Sticker.fileUniqueId, Sticker.cachedDescription. Les descriptions sont mises en cache dans l’état SQLite du plugin OpenClaw afin de réduire les appels répétés au modèle de vision.

Activez les actions d’autocollant :

{channels: {telegram: {  actions: {    sticker: true,  },},},}

Envoyer :

{action: "sticker",channel: "telegram",to: "123456789",fileId: "CAACAgIAAxkBAAI...",}

Rechercher dans les autocollants mis en cache :

{action: "sticker-search",channel: "telegram",query: "chat qui fait signe",limit: 5,}

Les réactions Telegram arrivent sous forme de mises à jour message_reaction, séparément des charges utiles des messages. Lorsqu’elles sont activées, OpenClaw place en file d’attente des événements système tels que Telegram reaction added: 👍 by Alice (@alice) on msg 42.

• channels.telegram.reactionNotifications : off | own | all (valeur par défaut : own)
• channels.telegram.reactionLevel : off | ack | minimal | extensive (valeur par défaut : minimal)

own désigne uniquement les réactions des utilisateurs aux messages envoyés par le bot (au mieux, au moyen d’un cache des messages envoyés). Les événements de réaction respectent toujours les contrôles d’accès de Telegram (dmPolicy, allowFrom, groupPolicy, groupAllowFrom) ; les expéditeurs non autorisés sont ignorés.

Telegram ne fournit pas d’ID de fil dans les mises à jour de réaction : les groupes qui ne sont pas des forums sont routés vers la session de discussion du groupe ; les groupes de forum sont routés vers la session du sujet général (:topic:1), et non vers le sujet d’origine exact.

allowed_updates pour l’interrogation ou le Webhook inclut automatiquement message_reaction.

ackReaction envoie un emoji d’accusé de réception pendant qu’OpenClaw traite un message entrant. messages.ackReactionScope détermine quand il est envoyé.

Ordre de résolution de l’emoji :

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• emoji de secours de l’identité de l’agent (agents.list[].identity.emoji, sinon « 👀 »)

Telegram attend un emoji Unicode (par exemple « 👀 ») ; utilisez "" pour désactiver la réaction pour un canal ou un compte.

Portée (messages.ackReactionScope, valeur par défaut : "group-mentions" ; aucun remplacement propre au compte Telegram ou au canal Telegram actuellement) :

all (messages privés + groupes, y compris les événements ambiants de salon), direct (messages privés uniquement), group-all (tous les messages de groupe sauf les événements ambiants de salon, aucun message privé), group-mentions (groupes lorsque le bot est mentionné ; aucun message privé — valeur par défaut), off / none (désactivé).

Les écritures dans la configuration du canal sont activées par défaut (configWrites !== false). Les écritures déclenchées par Telegram comprennent les événements de migration de groupe (migrate_to_chat_id, met à jour channels.telegram.groups) ainsi que /config set / /config unset (nécessite l’activation des commandes).

Désactiver :

{channels: {telegram: {  configWrites: false,},},}

Le mode par défaut est l’interrogation longue. Pour le mode Webhook, définissez channels.telegram.webhookUrl et channels.telegram.webhookSecret ; facultatifs : webhookPath (valeur par défaut : /telegram-webhook), webhookHost (valeur par défaut : 127.0.0.1), webhookPort (valeur par défaut : 8787), webhookCertPath (certificat PEM autosigné pour les configurations avec IP directe ou sans domaine).

En mode d’interrogation longue, OpenClaw ne conserve son point de reprise après redémarrage qu’une fois qu’une mise à jour a été distribuée avec succès ; en cas d’échec d’un gestionnaire, cette mise à jour reste réessayable dans le même processus au lieu d’être marquée comme terminée.

Par défaut, l’écouteur local se lie à 127.0.0.1:8787. Pour une entrée publique, placez un proxy inverse devant le port local ou définissez délibérément webhookHost: "0.0.0.0".

Le mode Webhook valide les protections de la requête, le jeton secret Telegram et le corps JSON, puis enregistre la mise à jour dans sa file d’entrée durable avant de renvoyer un 200 vide. Une adoption durable réussie inclut x-openclaw-delivery-accepted: durable ; les réponses relatives à l’état de santé, au routage, à l’authentification, à la validation et aux erreurs de stockage omettent cet en-tête. Les proxys inverses et les contrôleurs d’hôte peuvent exiger cet en-tête pour distinguer l’adoption par OpenClaw d’un 200 vide générique, sans déduire l’acceptation du délai de réponse.

OpenClaw traite ensuite la mise à jour de manière asynchrone au moyen des mêmes files de bot par discussion et par sujet que celles utilisées par l’interrogation longue ; les tours d’agent lents ne retardent donc pas l’accusé de réception de livraison de Telegram.

• channels.telegram.textChunkLimit vaut 4000 par défaut ; streaming.chunkMode="newline" privilégie les limites de paragraphes (lignes vides) avant le découpage selon la longueur.
• channels.telegram.mediaMaxMb (100 par défaut) limite la taille des médias entrants et sortants.
• channels.telegram.mediaGroupFlushMs (500 par défaut, plage 10-60000) contrôle la durée de mise en mémoire tampon des albums/groupes de médias avant qu’OpenClaw ne les transmette sous forme d’un seul message entrant. Augmentez cette valeur si des éléments de l’album arrivent tardivement ; diminuez-la pour réduire la latence de réponse aux albums.
• channels.telegram.timeoutSeconds remplace le délai d’expiration du client API (la valeur par défaut de grammY s’applique s’il n’est pas défini). Les clients de bot plafonnent les valeurs configurées inférieures à la garde de 60 secondes des requêtes sortantes de texte/de saisie afin que grammY n’interrompe pas la remise d’une réponse visible avant que la garde de transport et le mécanisme de repli d’OpenClaw puissent s’exécuter. L’interrogation longue utilise toujours une garde de requête getUpdates de 45 secondes afin que les interrogations inactives ne soient pas abandonnées indéfiniment.
• channels.telegram.pollingStallThresholdMs vaut 120000 par défaut ; ajustez-la entre 30000 et 600000 uniquement en cas de redémarrages dus à de fausses détections de blocage de l’interrogation.
• l’historique du contexte de groupe utilise channels.telegram.historyLimit ou messages.groupChat.historyLimit (50 par défaut) ; 0 le désactive.
• le contexte supplémentaire de réponse/citation/transfert est normalisé dans une seule fenêtre de contexte de conversation sélectionnée lorsque le Gateway a observé les messages parents ; le cache des messages observés réside dans l’état SQLite du Plugin OpenClaw, et openclaw doctor --fix importe les fichiers annexes hérités. Telegram n’inclut qu’un seul reply_to_message superficiel par mise à jour ; les chaînes plus anciennes que le cache sont donc limitées à cette charge utile.
• les listes d’autorisation Telegram déterminent principalement qui peut déclencher l’agent ; elles ne constituent pas une frontière complète de masquage du contexte supplémentaire.
• historique des messages privés : channels.telegram.dmHistoryLimit, channels.telegram.dms["<user_id>"].historyLimit.
• channels.telegram.retry s’applique aux utilitaires d’envoi Telegram (CLI/outils/actions) pour les erreurs récupérables de l’API sortante. La remise de la réponse finale entrante utilise une nouvelle tentative d’envoi sécurisé et limitée pour les échecs antérieurs à la connexion, mais ne réessaie pas les enveloppes réseau ambiguës postérieures à l’envoi, qui pourraient dupliquer les messages visibles.

Les cibles d’envoi de la CLI et de l’outil de messagerie acceptent un identifiant numérique de discussion, un nom d’utilisateur ou une cible de sujet de forum :

openclaw message send --channel telegram --target 123456789 --message "hi"openclaw message send --channel telegram --target @name --message "hi"openclaw message send --channel telegram --target -1001234567890:topic:42 --message "hi topic"

Les sondages utilisent openclaw message poll et prennent en charge les sujets de forum :

openclaw message poll --channel telegram --target 123456789 \--poll-question "Ship it?" --poll-option "Yes" --poll-option "No"openclaw message poll --channel telegram --target -1001234567890:topic:42 \--poll-question "Pick a time" --poll-option "10am" --poll-option "2pm" \--poll-duration-seconds 300 --poll-public

Options de sondage propres à Telegram : --poll-duration-seconds (5-600), --poll-anonymous, --poll-public, --thread-id (ou une cible :topic:). --poll-option se répète de 2 à 12 fois (limite d’options de Telegram).

L’envoi Telegram prend également en charge --presentation avec des blocs buttons pour les claviers intégrés (lorsque channels.telegram.capabilities.inlineButtons l’autorise), --pin ou --delivery '{"pin":true}' pour demander l’épinglage du message lorsque le bot peut épingler des messages dans cette discussion, et --force-document pour envoyer les images, GIF et vidéos sortants sous forme de documents plutôt que de téléversements compressés/animés/vidéo.

Contrôle des actions : channels.telegram.actions.sendMessage=false désactive tous les messages sortants, y compris les sondages ; channels.telegram.actions.poll=false désactive la création de sondages tout en laissant les envois ordinaires activés.

Telegram prend en charge les approbations d’exécution dans les messages privés des approbateurs et peut facultativement publier les demandes dans la discussion ou le sujet d’origine. Les approbateurs doivent être des identifiants numériques d’utilisateurs Telegram.

• channels.telegram.execApprovals.enabled ("auto" l’active lorsqu’au moins un approbateur peut être résolu)
• channels.telegram.execApprovals.approvers (utilise à défaut les identifiants numériques des propriétaires provenant de commands.ownerAllowFrom)
• channels.telegram.execApprovals.target : dm (par défaut) | channel | both
• agentFilter, sessionFilter

channels.telegram.allowFrom, groupAllowFrom et defaultTo déterminent qui peut communiquer avec le bot et où celui-ci envoie les réponses ordinaires ; ils ne font pas d’une personne un approbateur d’exécution. Le premier appairage approuvé par message privé initialise commands.ownerAllowFrom lorsqu’aucun propriétaire de commande n’existe encore, afin que les configurations à propriétaire unique fonctionnent sans dupliquer les identifiants sous execApprovals.approvers.

La remise dans le canal affiche le texte de la commande dans la discussion ; activez channel ou both uniquement dans des groupes/sujets de confiance. Lorsque la demande arrive dans un sujet de forum, OpenClaw conserve le sujet pour la demande d’approbation et le suivi. Les approbations d’exécution expirent après 30 minutes par défaut.

Les boutons d’approbation intégrés nécessitent également que channels.telegram.capabilities.inlineButtons autorise la surface cible (dm, group ou all). Les identifiants d’approbation préfixés par plugin: sont résolus par les approbations de Plugin ; les autres sont d’abord résolus par les approbations d’exécution.

Consultez Approbations d’exécution.

• Si requireMention=false, le mode de confidentialité de Telegram doit autoriser une visibilité complète : BotFather /setprivacy -> Disable, puis supprimez le bot du groupe et ajoutez-le à nouveau.
• openclaw channels status émet un avertissement lorsque la configuration attend des messages de groupe sans mention.
• openclaw channels status --probe vérifie les identifiants numériques explicites des groupes ; le caractère générique "*" ne permet pas de vérifier l’appartenance.
• Test rapide de session : /activation always.

• Lorsque channels.telegram.groups existe, le groupe doit être répertorié (ou inclure "*").
• Vérifiez que le bot appartient au groupe.
• Consultez openclaw logs --follow pour connaître les motifs d’exclusion.

• Autorisez l’identité de l’expéditeur (appairage et/ou allowFrom numérique) ; l’autorisation des commandes s’applique toujours, même lorsque la politique du groupe est open.
• setMyCommands failed avec BOT_COMMANDS_TOO_MUCH signifie que le menu natif comporte trop d’entrées ; réduisez le nombre de commandes de Plugin/Skills/personnalisées ou désactivez les menus natifs.
• Les appels de démarrage deleteMyCommands / setMyCommands et les appels de saisie sendChatAction sont limités et font l’objet d’une nouvelle tentative via le mécanisme de repli du transport Telegram en cas d’expiration de la requête. Les erreurs persistantes de réseau/récupération signifient généralement que api.telegram.org est inaccessible par DNS/HTTPS.

• getMe returned 401 est un échec d’authentification Telegram pour le jeton de bot configuré. Copiez à nouveau ou régénérez le jeton dans BotFather, puis mettez à jour channels.telegram.botToken, tokenFile, accounts.<id>.botToken ou TELEGRAM_BOT_TOKEN (compte par défaut).
• deleteWebhook 401 Unauthorized au démarrage est également un échec d’authentification ; le traiter comme « aucun Webhook n’existe » ne ferait que différer le même échec dû au jeton incorrect jusqu’à un appel API ultérieur.

• Node 22+ avec un mécanisme de récupération/proxy personnalisé peut provoquer un abandon immédiat si les types AbortSignal ne correspondent pas.
• Certains hôtes résolvent d’abord api.telegram.org en IPv6 ; une sortie IPv6 défectueuse provoque des échecs intermittents de l’API.
• Les journaux contenant TypeError: fetch failed ou Network request for 'getUpdates' failed! font l’objet de nouvelles tentatives en tant qu’erreurs réseau récupérables.
• Au démarrage de l’interrogation, OpenClaw réutilise pour grammY la sonde getMe ayant réussi au démarrage, afin que l’exécuteur n’ait pas besoin d’effectuer un second getMe avant le premier getUpdates.
• Si deleteWebhook échoue en raison d’une erreur réseau temporaire au démarrage de l’interrogation, OpenClaw passe à l’interrogation longue au lieu d’effectuer un autre appel du plan de contrôle avant l’interrogation. Un Webhook encore actif se manifeste alors sous forme de conflit getUpdates ; OpenClaw reconstruit le transport et réessaie de nettoyer le Webhook.
• Si les sockets Telegram sont renouvelés selon une cadence fixe et courte, recherchez une valeur channels.telegram.timeoutSeconds faible : les clients de bot plafonnent les valeurs configurées inférieures aux gardes de requête sortantes et getUpdates, mais les anciennes versions pouvaient interrompre chaque interrogation ou réponse lorsque cette valeur était inférieure à ces gardes.
• Polling stall detected dans les journaux signifie qu’OpenClaw redémarre l’interrogation et reconstruit le transport après 120 secondes sans activité d’interrogation longue achevée par défaut.
• openclaw channels status --probe et openclaw doctor émettent un avertissement lorsqu’un compte d’interrogation actif n’a pas achevé getUpdates après le délai de grâce du démarrage, qu’un compte Webhook actif n’a pas achevé setWebhook après le délai de grâce du démarrage, ou que la dernière activité réussie du transport d’interrogation est obsolète.
• Augmentez channels.telegram.pollingStallThresholdMs uniquement lorsque les appels getUpdates de longue durée fonctionnent correctement, mais que votre hôte signale toujours de faux redémarrages dus au blocage de l’interrogation. Les blocages persistants indiquent généralement des problèmes de proxy, DNS, IPv6 ou de sortie TLS vers api.telegram.org.
• Telegram respecte les variables d’environnement de proxy du processus pour le transport de l’API Bot : HTTP_PROXY, HTTPS_PROXY, ALL_PROXY et leurs variantes en minuscules. NO_PROXY / no_proxy peuvent toujours contourner api.telegram.org.
• Si OPENCLAW_PROXY_URL est défini pour un environnement de service et qu’aucune variable d’environnement de proxy standard n’est présente, Telegram utilise également cette URL pour le transport de l’API Bot.
• Sur les hôtes VPS dont la sortie directe/TLS est instable, acheminez les appels à l’API Telegram via un proxy :

channels:telegram:proxy: socks5://<user>:<password>@proxy-host:1080

• Node 22+ utilise par défaut autoSelectFamily=true (sauf sous WSL2). L’ordre des résultats DNS de Telegram respecte OPENCLAW_TELEGRAM_DNS_RESULT_ORDER, puis channels.telegram.network.dnsResultOrder, puis la valeur par défaut du processus (par exemple NODE_OPTIONS=--dns-result-order=ipv4first), avec un repli vers ipv4first sous Node 22+ si aucune ne s’applique.
• Sous WSL2, ou lorsqu’un fonctionnement exclusivement en IPv4 donne de meilleurs résultats, forcez la sélection de la famille :

channels:telegram:network:  autoSelectFamily: false

• Les réponses de la plage de référence RFC 2544 (198.18.0.0/15) sont déjà autorisées par défaut pour les téléchargements de médias Telegram. Si un proxy fake-IP ou transparent de confiance réécrit api.telegram.org vers une autre adresse privée/interne/à usage spécial pendant les téléchargements de médias, activez le contournement réservé à Telegram :

channels:telegram:network:  dangerouslyAllowPrivateNetwork: true

• La même activation est disponible pour chaque compte dans channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork.
• Si votre proxy résout les hôtes de médias Telegram dans 198.18.x.x, laissez d’abord l’option dangereuse désactivée — cette plage est déjà autorisée par défaut.

• Remplacements temporaires par variables d’environnement : OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1, OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1, OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first.
• Validez les réponses DNS :

dig +short api.telegram.org Adig +short api.telegram.org AAAA