• disabilitare la modalità privacy tramite /setprivacy, oppure
• rendere il bot amministratore del gruppo.

• /setjoingroups per consentire/negare l’aggiunta ai gruppi
• /setprivacy per il comportamento di visibilità nei gruppi

• chat dirette: messaggio di anteprima + editMessageText
• gruppi/topic: messaggio di anteprima + editMessageText

• channels.telegram.streaming è off | partial | block | progress (predefinito: partial)
• progress corrisponde a partial su Telegram (compatibilità con la denominazione cross-channel)
• i valori legacy channels.telegram.streamMode e booleani streaming sono mappati automaticamente

• DM: OpenClaw mantiene lo stesso messaggio di anteprima ed esegue una modifica finale sul posto (nessun secondo messaggio)
• gruppo/topic: OpenClaw mantiene lo stesso messaggio di anteprima ed esegue una modifica finale sul posto (nessun secondo messaggio)

• /reasoning stream invia il ragionamento all’anteprima live durante la generazione
• la risposta finale viene inviata senza testo di ragionamento

• Il testo in stile Markdown viene renderizzato in HTML sicuro per Telegram.
• L’HTML grezzo del modello viene escaped per ridurre gli errori di parsing di Telegram.
• Se Telegram rifiuta l’HTML parsato, OpenClaw ritenta come testo semplice.

• commands.native: "auto" abilita i comandi nativi per Telegram

{
  channels: {
    telegram: {
      customCommands: [
        { command: "backup", description: "Backup Git" },
        { command: "generate", description: "Crea un'immagine" },
      ],
    },
  },
}

• i nomi sono normalizzati (rimozione di / iniziale, minuscolo)
• pattern valido: a-z, 0-9, _, lunghezza 1..32
• i comandi personalizzati non possono sovrascrivere i comandi nativi
• conflitti/duplicati vengono saltati e registrati nei log

• i comandi personalizzati sono solo voci di menu; non implementano automaticamente il comportamento
• i comandi plugin/Skills possono comunque funzionare se digitati, anche se non sono mostrati nel menu Telegram

• setMyCommands failed con BOT_COMMANDS_TOO_MUCH significa che il menu Telegram continua a essere troppo pieno dopo il trimming; riduci i comandi plugin/Skills/personalizzati o disabilita channels.telegram.commands.native.
• setMyCommands failed con errori di rete/fetch di solito significa che il DNS/HTTPS in uscita verso api.telegram.org è bloccato.

​

Comandi di abbinamento dispositivo (plugin device-pair)

1. /pair genera un codice di configurazione
2. incolla il codice nell’app iOS
3. /pair pending elenca le richieste in sospeso (inclusi ruolo/scopes)
4. approva la richiesta:
   • /pair approve <requestId> per l’approvazione esplicita
   • /pair approve quando c’è una sola richiesta in sospeso
   • /pair approve latest per la più recente

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

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

• off
• dm
• group
• all
• allowlist (predefinito)

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  message: "Scegli un'opzione:",
  buttons: [
    [
      { text: "Sì", callback_data: "yes" },
      { text: "No", callback_data: "no" },
    ],
    [{ text: "Annulla", callback_data: "cancel" }],
  ],
}

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

• channels.telegram.actions.sendMessage
• channels.telegram.actions.deleteMessage
• channels.telegram.actions.reactions
• channels.telegram.actions.sticker (predefinito: disabilitato)

• [[reply_to_current]] risponde al messaggio che ha attivato l’azione
• [[reply_to:<id>]] risponde a uno specifico ID messaggio Telegram

• off (predefinito)
• first
• all

• le chiavi di sessione del topic aggiungono :topic:<threadId>
• le risposte e la digitazione sono indirizzate al thread del topic
• percorso config del topic: channels.telegram.groups.<chatId>.topics.<threadId>

• gli invii di messaggi omettono message_thread_id (Telegram rifiuta sendMessage(...thread_id=1))
• le azioni di digitazione includono comunque message_thread_id

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "1": { agentId: "main" },      // Topic generale → agente main
            "3": { agentId: "zu" },        // Topic sviluppo → agente zu
            "5": { agentId: "coder" }      // Revisione codice → agente coder
          }
        }
      }
    }
  }
}

• bindings[] con type: "acp" e 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 può associare il topic Telegram corrente a una nuova sessione ACP.
• I messaggi successivi nel topic vengono instradati direttamente alla sessione ACP associata (senza bisogno di /acp steer).
• OpenClaw fissa il messaggio di conferma dello spawn nel topic dopo un binding riuscito.
• Richiede channels.telegram.threadBindings.spawnAcpSessions=true.

• MessageThreadId
• IsForum

• le chat private con message_thread_id mantengono l’instradamento DM ma usano chiavi di sessione e destinazioni di risposta sensibili al thread.

​

Messaggi audio

• predefinito: comportamento da file audio
• tag [[audio_as_voice]] nella risposta dell’agente per forzare l’invio come nota vocale

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

​

Messaggi video

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

​

Sticker

• WEBP statico: scaricato ed elaborato (segnaposto <media:sticker>)
• TGS animato: ignorato
• WEBM video: ignorato

• 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: "gatto che saluta",
  limit: 5,
}

• Reazione Telegram aggiunta: 👍 da Alice (@alice) al msg 42

• channels.telegram.reactionNotifications: off | own | all (predefinito: own)
• channels.telegram.reactionLevel: off | ack | minimal | extensive (predefinito: minimal)

• own significa solo reazioni dell’utente ai messaggi inviati dal bot (best-effort tramite cache dei messaggi inviati).
• Gli eventi di reazione rispettano comunque i controlli di accesso Telegram (dmPolicy, allowFrom, groupPolicy, groupAllowFrom); i mittenti non autorizzati vengono scartati.
• Telegram non fornisce ID thread negli aggiornamenti di reazione.
  • i gruppi non forum vengono instradati alla sessione della chat di gruppo
  • i gruppi forum vengono instradati alla sessione del topic generale del gruppo (:topic:1), non all’esatto topic di origine

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• fallback all’emoji identità dell’agente (agents.list[].identity.emoji, altrimenti ”👀”)

• Telegram si aspetta emoji unicode (ad esempio ”👀”).
• Usa "" per disabilitare la reazione per un canale o account.

• eventi di migrazione del gruppo (migrate_to_chat_id) per aggiornare channels.telegram.groups
• /config set e /config unset (richiede l’abilitazione dei comandi)

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

• imposta channels.telegram.webhookUrl
• imposta channels.telegram.webhookSecret (obbligatorio quando è impostato l’URL Webhook)
• channels.telegram.webhookPath facoltativo (predefinito /telegram-webhook)
• channels.telegram.webhookHost facoltativo (predefinito 127.0.0.1)
• channels.telegram.webhookPort facoltativo (predefinito 8787)

• il valore predefinito di channels.telegram.textChunkLimit è 4000.
• channels.telegram.chunkMode="newline" preferisce i confini dei paragrafi (righe vuote) prima della suddivisione per lunghezza.
• channels.telegram.mediaMaxMb (predefinito 100) impone un limite alla dimensione dei media Telegram in ingresso e in uscita.
• channels.telegram.timeoutSeconds sovrascrive il timeout del client Telegram API (se non impostato, si applica il valore predefinito di grammY).
• la cronologia del contesto di gruppo usa channels.telegram.historyLimit o messages.groupChat.historyLimit (predefinito 50); 0 la disabilita.
• il contesto supplementare di risposta/citazione/inoltro viene attualmente passato così come ricevuto.
• le allowlist Telegram limitano principalmente chi può attivare l’agente, non costituiscono un confine completo di redazione del contesto supplementare.
• controlli della cronologia DM:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• la configurazione channels.telegram.retry si applica agli helper di invio Telegram (CLI/tools/actions) per gli errori recuperabili della API in uscita.

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 per i topic del forum (oppure usa una destinazione :topic:)

• --buttons per tastiere inline quando channels.telegram.capabilities.inlineButtons lo consente
• --force-document per inviare immagini e GIF in uscita come documenti invece che come foto compresse o caricamenti di media animati

• channels.telegram.actions.sendMessage=false disabilita i messaggi Telegram in uscita, inclusi i poll
• channels.telegram.actions.poll=false disabilita la creazione di poll Telegram lasciando abilitati i normali invii

• channels.telegram.execApprovals.enabled
• channels.telegram.execApprovals.approvers (facoltativo; usa come fallback gli ID proprietario numerici dedotti da allowFrom e da defaultTo diretto quando possibile)
• channels.telegram.execApprovals.target (dm | channel | both, predefinito: dm)
• agentFilter, sessionFilter

• target: "dm" invia i prompt di approvazione solo ai DM degli approvatori risolti
• target: "channel" invia il prompt di nuovo alla chat/topic Telegram di origine
• target: "both" invia ai DM degli approvatori e alla chat/topic di origine

• Gli ID con prefisso plugin: vengono sempre risolti tramite le approvazioni del plugin.
• Gli altri ID di approvazione provano prima exec.approval.resolve.
• Se Telegram è autorizzato anche per le approvazioni del plugin e il gateway dice che l’approvazione exec è sconosciuta/scaduta, Telegram ritenta una volta tramite plugin.approval.resolve.
• I dinieghi/errori reali delle approvazioni exec non ricadono silenziosamente sulla risoluzione delle approvazioni del plugin.

• Se requireMention=false, la modalità privacy di Telegram deve consentire piena visibilità.
  • BotFather: /setprivacy -> Disable
  • quindi rimuovi e riaggiungi il bot al gruppo
• openclaw channels status avvisa quando la configurazione prevede messaggi di gruppo senza menzione.
• openclaw channels status --probe può controllare ID di gruppo numerici espliciti; il carattere jolly "*" non può essere verificato come appartenenza.
• test rapido della sessione: /activation always.

• quando esiste channels.telegram.groups, il gruppo deve essere elencato (oppure includere "*")
• verifica che il bot sia membro del gruppo
• controlla i log: openclaw logs --follow per i motivi di esclusione

• autorizza la tua identità mittente (abbinamento e/o allowFrom numerico)
• l’autorizzazione dei comandi si applica comunque anche quando il criterio di gruppo è open
• setMyCommands failed con BOT_COMMANDS_TOO_MUCH significa che il menu nativo ha troppe voci; riduci i comandi plugin/Skills/personalizzati o disabilita i menu nativi
• setMyCommands failed con errori di rete/fetch di solito indica problemi di raggiungibilità DNS/HTTPS verso api.telegram.org

• Node 22+ + fetch/proxy personalizzato possono attivare un comportamento di abort immediato se i tipi AbortSignal non corrispondono.
• Alcuni host risolvono api.telegram.org prima in IPv6; un’uscita IPv6 difettosa può causare errori intermittenti della Telegram API.
• Se i log includono TypeError: fetch failed o Network request for 'getUpdates' failed!, OpenClaw ora li ritenta come errori di rete recuperabili.
• Su host VPS con uscita diretta/TLS instabile, instrada le chiamate Telegram API tramite channels.telegram.proxy:

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

• Node 22+ usa per impostazione predefinita autoSelectFamily=true (eccetto WSL2) e dnsResultOrder=ipv4first.
• Se il tuo host è WSL2 o funziona esplicitamente meglio con comportamento solo IPv4, forza la selezione della famiglia:

channels:
  telegram:
    network:
      autoSelectFamily: false

• Le risposte nell’intervallo benchmark RFC 2544 (198.18.0.0/15) sono già consentite per impostazione predefinita per i download dei media Telegram. Se un fake-IP affidabile o un proxy trasparente riscrive api.telegram.org verso un altro indirizzo privato/interno/special-use durante i download dei media, puoi attivare il bypass solo per Telegram:

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• Lo stesso opt-in è disponibile per account in channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork.
• Se il tuo proxy risolve gli host media Telegram in 198.18.x.x, lascia prima disattivato il flag pericoloso. I media Telegram già consentono per impostazione predefinita l’intervallo benchmark RFC 2544.

• Override ambiente (temporanei):
  • OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first
• Convalida le risposte DNS:

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