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

• /setjoingroups pour autoriser/interdire l’ajout à des groupes
• /setprivacy pour le comportement de visibilité dans les groupes

• chats directs : message d’aperçu + editMessageText
• groupes/sujets : message d’aperçu + editMessageText

• channels.telegram.streaming vaut off | partial | block | progress (par défaut : partial)
• progress correspond à partial sur Telegram (compatibilité avec la dénomination inter-canaux)
• les anciennes valeurs booléennes de channels.telegram.streamMode et streaming sont mappées automatiquement

• DM : OpenClaw conserve le même message d’aperçu et effectue une modification finale sur place (pas de second message)
• groupe/sujet : OpenClaw conserve le même message d’aperçu et effectue une modification finale sur place (pas de second message)

• /reasoning stream envoie le raisonnement vers l’aperçu en direct pendant la génération
• la réponse finale est envoyée sans le texte de raisonnement

• Le texte de type Markdown est rendu en HTML sûr pour Telegram.
• Le HTML brut du modèle est échappé pour réduire les échecs d’analyse de Telegram.
• Si Telegram rejette le HTML analysé, OpenClaw réessaie en texte brut.

• commands.native: "auto" active les commandes natives pour Telegram

{
  channels: {
    telegram: {
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
    },
  },
}

• les noms sont normalisés (suppression du / initial, minuscules)
• motif valide : a-z, 0-9, _, longueur 1..32
• les commandes personnalisées ne peuvent pas remplacer les commandes natives
• les conflits/doublons sont ignorés et journalisés

• les commandes personnalisées sont uniquement des entrées de menu ; elles n’implémentent pas automatiquement un comportement
• les commandes de plugin/Skills peuvent toujours fonctionner lorsqu’elles sont saisies, même si elles ne sont pas affichées dans le menu Telegram

• setMyCommands failed avec BOT_COMMANDS_TOO_MUCH signifie que le menu Telegram déborde toujours après réduction ; réduisez les commandes personnalisées/de plugin/de Skills ou désactivez channels.telegram.commands.native.
• setMyCommands failed avec des erreurs réseau/fetch signifie généralement que le DNS/HTTPS sortant vers api.telegram.org est bloqué.

​

Commandes d’appairage d’appareil (plugin device-pair)

1. /pair génère un code de configuration
2. collez le code dans l’application iOS
3. /pair pending liste les demandes en attente (y compris rôle/portées)
4. approuvez la demande :
   • /pair approve <requestId> pour une approbation explicite
   • /pair approve lorsqu’il n’y a qu’une seule demande en attente
   • /pair approve latest pour la plus récente

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

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

• off
• dm
• group
• all
• allowlist (par défaut)

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  message: "Choose an option:",
  buttons: [
    [
      { text: "Yes", callback_data: "yes" },
      { text: "No", callback_data: "no" },
    ],
    [{ text: "Cancel", callback_data: "cancel" }],
  ],
}

• sendMessage (to, content, mediaUrl, replyToMessageId, messageThreadId facultatifs)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content)
• createForumTopic (chatId, name, iconColor, iconCustomEmojiId facultatifs)

• channels.telegram.actions.sendMessage
• channels.telegram.actions.deleteMessage
• channels.telegram.actions.reactions
• channels.telegram.actions.sticker (par défaut : désactivé)

• [[reply_to_current]] répond au message déclencheur
• [[reply_to:<id>]] répond à un ID de message Telegram spécifique

• off (par défaut)
• first
• all

• les clés de session de sujet ajoutent :topic:<threadId>
• les réponses et les indicateurs de saisie ciblent le fil du sujet
• chemin de configuration du sujet : channels.telegram.groups.<chatId>.topics.<threadId>

• les envois de message omettent message_thread_id (Telegram rejette sendMessage(...thread_id=1))
• les actions de saisie incluent toujours message_thread_id

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

• bindings[] avec type: "acp" et match.channel: "telegram"

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "telegram",
        accountId: "default",
        peer: { kind: "group", id: "-1001234567890:topic:42" },
      },
    },
  ],
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "42": {
              requireMention: false,
            },
          },
        },
      },
    },
  },
}

• /acp spawn <agent> --thread here|auto peut lier le sujet Telegram actuel à une nouvelle session ACP.
• Les messages suivants dans le sujet sont routés directement vers la session ACP liée (pas de /acp steer requis).
• OpenClaw épingle le message de confirmation du lancement dans le sujet après une liaison réussie.
• Nécessite channels.telegram.threadBindings.spawnAcpSessions=true.

• MessageThreadId
• IsForum

• les chats privés avec message_thread_id conservent le routage DM mais utilisent des clés de session/cibles de réponse conscientes des fils.

​

Messages audio

• par défaut : comportement de fichier audio
• balise [[audio_as_voice]] dans la réponse de l’agent pour forcer l’envoi en note vocale

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

​

Messages vidéo

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

​

Stickers

• WEBP statique : téléchargé et traité (espace réservé <media:sticker>)
• TGS animé : ignoré
• WEBM vidéo : ignoré

• Sticker.emoji
• Sticker.setName
• Sticker.fileId
• Sticker.fileUniqueId
• Sticker.cachedDescription

• ~/.openclaw/telegram/sticker-cache.json

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

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

{
  action: "sticker-search",
  channel: "telegram",
  query: "cat waving",
  limit: 5,
}

• Telegram reaction added: 👍 by Alice (@alice) on msg 42

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

• own signifie uniquement les réactions des utilisateurs aux messages envoyés par le bot (au mieux via le cache des messages envoyés).
• Les événements de réaction respectent toujours les contrôles d’accès 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 non forum sont routés vers la session de chat de groupe
  • les groupes forum sont routés vers la session du sujet général du groupe (:topic:1), et non vers le sujet d’origine exact

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• repli sur l’emoji d’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.

• les événements de migration de groupe (migrate_to_chat_id) pour mettre à jour channels.telegram.groups
• /config set et /config unset (nécessite l’activation de la commande)

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

• définissez channels.telegram.webhookUrl
• définissez channels.telegram.webhookSecret (obligatoire lorsque l’URL webhook est définie)
• channels.telegram.webhookPath facultatif (par défaut /telegram-webhook)
• channels.telegram.webhookHost facultatif (par défaut 127.0.0.1)
• channels.telegram.webhookPort facultatif (par défaut 8787)

• channels.telegram.textChunkLimit vaut 4000 par défaut.
• channels.telegram.chunkMode="newline" privilégie les frontières de paragraphe (lignes vides) avant la segmentation par longueur.
• channels.telegram.mediaMaxMb (par défaut 100) limite la taille des médias Telegram entrants et sortants.
• channels.telegram.timeoutSeconds remplace le délai d’expiration du client Telegram API (si non défini, la valeur par défaut de grammY s’applique).
• l’historique du contexte de groupe utilise channels.telegram.historyLimit ou messages.groupChat.historyLimit (par défaut 50) ; 0 le désactive.
• le contexte supplémentaire de réponse/citation/transfert est actuellement transmis tel que reçu.
• les listes d’autorisation Telegram servent principalement à contrôler qui peut déclencher l’agent, et non une frontière complète de caviardage du contexte supplémentaire.
• contrôles d’historique DM :
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• la configuration channels.telegram.retry s’applique aux helpers d’envoi Telegram (CLI/outils/actions) pour les erreurs API sortantes récupérables.

openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"

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

• --poll-duration-seconds (5-600)
• --poll-anonymous
• --poll-public
• --thread-id pour les sujets de forum (ou utilisez une cible :topic:)

• --buttons pour les claviers intégrés lorsque channels.telegram.capabilities.inlineButtons l’autorise
• --force-document pour envoyer des images et GIF sortants comme documents au lieu de photos compressées ou de médias animés

• channels.telegram.actions.sendMessage=false désactive les messages Telegram sortants, y compris les sondages
• channels.telegram.actions.poll=false désactive la création de sondages Telegram tout en laissant les envois classiques activés

• channels.telegram.execApprovals.enabled
• channels.telegram.execApprovals.approvers (facultatif ; retombe sur les ID de propriétaire numériques déduits de allowFrom et de defaultTo direct lorsque possible)
• channels.telegram.execApprovals.target (dm | channel | both, par défaut : dm)
• agentFilter, sessionFilter

• target: "dm" envoie les invites d’approbation uniquement aux DM des approbateurs résolus
• target: "channel" renvoie l’invite au chat/sujet Telegram d’origine
• target: "both" envoie aux DM des approbateurs et au chat/sujet d’origine

• les ID préfixés par plugin: sont toujours résolus via les approbations de plugin.
• les autres ID essaient d’abord exec.approval.resolve.
• si Telegram est aussi autorisé pour les approbations de plugin et que gateway indique que l’approbation exec est inconnue/expirée, Telegram réessaie une fois via plugin.approval.resolve.
• les refus/erreurs d’approbation exec réels ne retombent pas silencieusement sur la résolution d’approbation de plugin.

• Si requireMention=false, le mode confidentialité Telegram doit autoriser une visibilité complète.
  • BotFather : /setprivacy -> Désactiver
  • puis supprimer + réajouter le bot au groupe
• openclaw channels status avertit lorsque la configuration attend des messages de groupe sans mention.
• openclaw channels status --probe peut vérifier des ID de groupe numériques explicites ; le joker "*" ne peut pas être sondé pour l’appartenance.
• test rapide de session : /activation always.

• lorsque channels.telegram.groups existe, le groupe doit être listé (ou inclure "*")
• vérifiez l’appartenance du bot au groupe
• consultez les journaux : openclaw logs --follow pour les raisons d’ignorance

• autorisez votre identité d’expéditeur (appairage et/ou allowFrom numérique)
• l’autorisation des commandes s’applique toujours même lorsque la politique de groupe est open
• setMyCommands failed avec BOT_COMMANDS_TOO_MUCH signifie que le menu natif a trop d’entrées ; réduisez les commandes personnalisées/de plugin/de Skills ou désactivez les menus natifs
• setMyCommands failed avec des erreurs réseau/fetch indique généralement des problèmes d’accessibilité DNS/HTTPS vers api.telegram.org

• Node 22+ + fetch/proxy personnalisé peuvent déclencher un comportement d’abandon immédiat si les types AbortSignal ne correspondent pas.
• Certains hôtes résolvent api.telegram.org vers IPv6 en premier ; une sortie IPv6 défectueuse peut provoquer des échecs intermittents de Telegram API.
• Si les journaux incluent TypeError: fetch failed ou Network request for 'getUpdates' failed!, OpenClaw réessaie désormais ces cas comme des erreurs réseau récupérables.
• Sur des hôtes VPS avec sortie directe/TLS instable, faites passer les appels Telegram API via channels.telegram.proxy :

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

• Node 22+ utilise par défaut autoSelectFamily=true (sauf WSL2) et dnsResultOrder=ipv4first.
• Si votre hôte est WSL2 ou fonctionne explicitement mieux avec un comportement IPv4 uniquement, forcez la sélection de famille :

channels:
  telegram:
    network:
      autoSelectFamily: false

• Les réponses de plage de benchmark 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 faux IP ou un proxy transparent de confiance réécrit api.telegram.org vers une autre adresse privée/interne/spéciale lors des téléchargements de médias, vous pouvez activer le contournement réservé à Telegram :

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• Le même opt-in est disponible par compte dans channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork.
• Si votre proxy résout les hôtes média Telegram en 198.18.x.x, laissez d’abord le drapeau dangereux désactivé. Les médias Telegram autorisent déjà la plage de benchmark RFC 2544 par défaut.

• Remplacements via variables d’environnement (temporaires) :
  • 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 A
dig +short api.telegram.org AAAA