Telegram

Per impostazione predefinita, i bot Telegram usano la Privacy Mode, che limita i messaggi di gruppo ricevuti.

Per visualizzare tutti i messaggi di gruppo:

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

Dopo aver modificato la modalità privacy, rimuovere e aggiungere nuovamente il bot in ogni gruppo affinché Telegram applichi la modifica.

Lo stato di amministratore viene gestito nelle impostazioni del gruppo Telegram. I bot amministratori ricevono tutti i messaggi di gruppo, funzione utile per un comportamento sempre attivo nei gruppi.

• /setjoingroups — consentire o impedire l'aggiunta ai gruppi
• /setprivacy — comportamento della visibilità nei gruppi

Le stesse impostazioni sono disponibili nell'app web di BotFather se si preferisce un'interfaccia ai comandi di chat.

OpenClaw trasmette le risposte parziali in tempo reale nelle chat dirette, nei gruppi e negli argomenti: invia un messaggio di anteprima, quindi esegue ripetutamente editMessageText, finalizzandolo sul posto.

• channels.telegram.streaming è off | partial | block | progress (predefinito: partial)
• le brevi anteprime iniziali della risposta vengono sottoposte a debounce e quindi materializzate dopo un ritardo limitato se l'esecuzione è ancora attiva
• progress mantiene una singola bozza di stato modificabile per l'avanzamento degli strumenti, mostra l'etichetta di stato stabile quando l'attività della risposta arriva prima dell'avanzamento degli strumenti, la cancella al completamento e invia la risposta finale come messaggio normale
• streaming.preview.toolProgress controlla se gli aggiornamenti degli strumenti/dell'avanzamento riutilizzano lo stesso messaggio di anteprima modificato (predefinito: true quando il flusso di anteprima è attivo)
• streaming.preview.commandText controlla i dettagli di comando/esecuzione all'interno di tali righe: raw (predefinito) o status (solo l'etichetta dello strumento)
• streaming.progress.commentary (predefinito: false) abilita il testo di commento/preambolo dell'assistente nella bozza temporanea di avanzamento
• vengono rilevati il valore legacy channels.telegram.streamMode, i valori booleani streaming e le chiavi ritirate dell'anteprima nativa delle bozze; eseguire openclaw doctor --fix per migrarli

Le righe di avanzamento degli strumenti sono i brevi aggiornamenti di stato mostrati durante l'esecuzione degli strumenti (esecuzione di comandi, lettura di file, aggiornamenti della pianificazione, riepiloghi delle patch, preambolo/commento di Codex in modalità app-server). Telegram le mantiene attive per impostazione predefinita (in linea con il comportamento rilasciato da v2026.4.22+).

Mantenere le modifiche dell'anteprima della risposta ma nascondere le righe di avanzamento degli strumenti:

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

Mantenere visibile l'avanzamento degli strumenti ma nascondere il testo di comando/esecuzione:

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

La modalità progress mostra l'avanzamento degli strumenti senza modificare la risposta finale in quel messaggio. Inserire il criterio del testo dei comandi sotto streaming.progress:

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

streaming.mode: "off" disabilita le modifiche dell'anteprima e sopprime i messaggi generici relativi agli strumenti/all'avanzamento anziché inviarli come messaggi di stato autonomi; le richieste di approvazione, i contenuti multimediali e gli errori continuano a essere instradati tramite la normale consegna finale. streaming.preview.toolProgress: false mantiene solo le modifiche dell'anteprima della risposta.

Per le risposte di solo testo: le anteprime brevi ricevono la modifica finale sul posto; le risposte finali lunghe suddivise in più messaggi riutilizzano l'anteprima come primo frammento e quindi inviano solo il resto; le risposte finali in modalità di avanzamento cancellano la bozza di stato e usano la normale consegna finale; se la modifica finale non riesce prima che il completamento sia confermato, OpenClaw ripiega sulla normale consegna finale e rimuove l'anteprima obsoleta. Per le risposte complesse (payload multimediali), OpenClaw ripiega sempre sulla normale consegna finale e rimuove l'anteprima.

Il flusso di anteprima e il flusso a blocchi si escludono a vicenda: quando il flusso a blocchi è abilitato esplicitamente, OpenClaw salta il flusso di anteprima per evitare una doppia trasmissione.

Ragionamento: /reasoning stream trasmette il ragionamento nell'anteprima in tempo reale durante la generazione, quindi elimina l'anteprima del ragionamento dopo la consegna finale (usare /reasoning on per mantenerla visibile). La risposta finale viene inviata senza il testo del ragionamento.

Per impostazione predefinita, il testo in uscita usa messaggi HTML standard di Telegram, leggibili nei client attuali: grassetto, corsivo, collegamenti, codice, spoiler, citazioni, non blocchi avanzati esclusivi dell'API Bot 10.2 (tabelle native, dettagli, contenuti multimediali avanzati, formule).

Abilitare i messaggi avanzati dell'API Bot 10.2:

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

Quando sono abilitati: l'agente viene informato che i messaggi avanzati sono disponibili per questo bot/account (con il contratto di creazione supportato per Markdown e isole HTML); il testo Markdown viene reso tramite l'IR Markdown di OpenClaw come blocchi avanzati tipizzati dell'API Bot 10.2 (intestazioni, tabelle, dettagli, elenchi di controllo, contenuti multimediali avanzati, formule, mappe, collage); le didascalie dei contenuti multimediali continuano a usare le didascalie HTML di Telegram (i messaggi avanzati non sostituiscono le didascalie, che hanno un limite di 1024 caratteri).

Ciò evita che il testo del modello contenga i simboli speciali del Markdown avanzato di Telegram, in modo che le valute come $400-600K non vengano interpretate come formule matematiche. Il testo avanzato lungo viene suddiviso automaticamente entro i limiti di Telegram. Le tabelle che superano il limite di 20 colonne ripiegano su un blocco di codice.

Impostazione predefinita: disattivata, per la compatibilità con i client; alcuni client Desktop, Web, Android e di terze parti attuali mostrano come non supportati i messaggi avanzati accettati. Lasciare questa opzione disattivata a meno che tutti i client usati con il bot siano in grado di visualizzarli. /status indica se i messaggi avanzati sono attivi o disattivi per la sessione corrente.

Le anteprime dei collegamenti sono attive per impostazione predefinita. channels.telegram.linkPreview: false disabilita il rilevamento automatico delle entità per il testo avanzato.

Il menu dei comandi di Telegram viene registrato all'avvio con setMyCommands. commands.native: "auto" abilita i comandi nativi per Telegram.

Aggiungere voci personalizzate al menu dei comandi:

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

Regole: i nomi vengono normalizzati (rimozione del prefisso /, conversione in minuscolo); schema valido a-z, 0-9, _, lunghezza 1-32; i comandi personalizzati non possono sostituire quelli nativi; i conflitti/duplicati vengono ignorati e registrati.

I comandi personalizzati sono solo voci di menu: non implementano automaticamente il comportamento. I comandi di Plugin/Skills possono comunque funzionare quando vengono digitati, anche se non sono visualizzati nel menu di Telegram. Se i comandi nativi sono disabilitati, quelli integrati vengono rimossi; i comandi personalizzati/di Plugin possono comunque essere registrati se configurati.

Errori comuni di configurazione:

• setMyCommands failed con BOT_COMMANDS_TOO_MUCH dopo un nuovo tentativo di riduzione indica che il menu supera ancora il limite; ridurre i comandi di Plugin/Skills/personalizzati oppure disabilitare channels.telegram.commands.native.
• Se deleteWebhook, deleteMyCommands o setMyCommands non riesce con 404: Not Found, mentre i comandi curl diretti dell'API Bot funzionano, in genere significa che channels.telegram.apiRoot è stato impostato sull'endpoint completo /bot<TOKEN>. apiRoot deve essere solo la radice dell'API Bot; openclaw doctor --fix rimuove un /bot<TOKEN> finale accidentale.
• getMe returned 401 significa che Telegram ha rifiutato il token del bot configurato. Aggiornare botToken, tokenFile o TELEGRAM_BOT_TOKEN (account predefinito) con il token BotFather corrente; OpenClaw si arresta prima del polling, quindi ciò non viene segnalato come errore di pulizia del Webhook.
• setMyCommands failed con errori di rete/recupero indica generalmente che il DNS/HTTPS in uscita verso api.telegram.org è bloccato.

Comandi di associazione del dispositivo (Plugin device-pair)

Quando è installato:

1. /pair genera un codice di configurazione
2. incollare il codice nell'app iOS
3. /pair pending elenca le richieste in sospeso (inclusi ruolo/ambiti)
4. approvare: /pair approve <requestId>, /pair approve (unica richiesta in sospeso) o /pair approve latest

Se un dispositivo riprova con dettagli di autenticazione modificati (ruolo, ambiti, chiave pubblica), la richiesta precedente in sospeso viene sostituita da un nuovo requestId; eseguire nuovamente /pair pending prima dell'approvazione.

Ulteriori dettagli: Associazione.

Configurare l'ambito della tastiera incorporata:

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

Override per account:

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

Ambiti: off, dm, group, all, allowlist (predefinito). Il valore legacy capabilities: ["inlineButtons"] viene mappato a "all".

Esempio di azione del messaggio:

{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" }],],}

Esempio di pulsante Mini App:

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

I pulsanti web_app funzionano solo nelle chat private tra un utente e il bot.

I clic sui callback non acquisiti da un gestore interattivo di Plugin registrato vengono passati all'agente come testo: callback_data: <value>.

Azioni:

• sendMessage (to, content, mediaUrl facoltativo, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content o caption, pulsanti incorporati presentation facoltativi; le modifiche dei soli pulsanti aggiornano il markup della risposta)
• createForumTopic (chatId, name, iconColor facoltativo, iconCustomEmojiId)

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

Controllo di abilitazione: channels.telegram.actions.sendMessage, deleteMessage, reactions, sticker (impostazione predefinita: disabilitata). edit, createForumTopic e editForumTopic sono abilitati per impostazione predefinita senza un'opzione dedicata. Gli invii in fase di esecuzione usano lo snapshot attivo di configurazione/segreti acquisito all'avvio o al ricaricamento, quindi i percorsi delle azioni non risolvono nuovamente i valori SecretRef per ogni invio.

Semantica della rimozione delle reazioni: /tools/reactions.

Tag espliciti per le risposte in thread nell'output generato:

• [[reply_to_current]] — risponde al messaggio che ha attivato l'azione
• [[reply_to:<id>]] — risponde a un ID messaggio specifico

channels.telegram.replyToMode: off (impostazione predefinita), first, all.

Quando le risposte in thread sono abilitate e il testo o la didascalia originale è disponibile, OpenClaw aggiunge automaticamente un estratto citato nativo. Telegram limita il testo delle citazioni native a 1024 unità di codice UTF-16; per i messaggi più lunghi viene citata la parte iniziale e si ricorre a una risposta semplice se Telegram rifiuta la citazione.

off disabilita soltanto le risposte implicite in thread; i tag espliciti [[reply_to_*]] vengono comunque rispettati.

Supergruppi con forum: alle chiavi di sessione degli argomenti viene aggiunto :topic:<threadId>; le risposte e l'indicatore di digitazione sono indirizzati al thread dell'argomento; il percorso di configurazione dell'argomento è channels.telegram.groups.<chatId>.topics.<threadId>.

L'argomento generale (threadId=1) è un caso speciale: gli invii di messaggi omettono message_thread_id (Telegram rifiuta sendMessage(...thread_id=1) con "thread not found"), ma le azioni di digitazione includono comunque message_thread_id (empiricamente necessario affinché venga visualizzato l'indicatore di digitazione).

Le voci degli argomenti ereditano le impostazioni del gruppo, salvo sostituzione (requireMention, allowFrom, skills, systemPrompt, enabled, groupPolicy). agentId è specifico dell'argomento e non eredita i valori predefiniti del gruppo. topics."*" imposta i valori predefiniti per ogni argomento del gruppo; gli ID esatti degli argomenti hanno comunque la precedenza su "*".

Instradamento dell'agente per argomento: ogni argomento può essere instradato a un agente diverso tramite agentId nella configurazione dell'argomento, ottenendo uno spazio di lavoro, una memoria e una sessione propri:

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

Ogni argomento dispone quindi di una propria chiave di sessione, ad esempio agent:zu:telegram:group:-1001234567890:topic:3.

Associazione persistente dell'argomento ACP: gli argomenti dei forum possono fissare le sessioni dell'infrastruttura ACP tramite associazioni tipizzate di primo livello (bindings[] con type: "acp", match.channel: "telegram", peer.kind: "group" e un ID qualificato dall'argomento come -1001234567890:topic:42). Attualmente l'ambito è limitato agli argomenti dei forum nei gruppi/supergruppi. Consultare Agenti ACP.

Avvio ACP associato al thread dalla chat: /acp spawn <agent> --thread here|auto associa l'argomento corrente a una nuova sessione ACP; i messaggi successivi vengono instradati direttamente a tale sessione e OpenClaw fissa la conferma dell'avvio nell'argomento. Richiede channels.telegram.threadBindings.spawnSessions (impostazione predefinita: true).

Il contesto del modello espone MessageThreadId e IsForum. Le chat con messaggi diretti che usano message_thread_id conservano i metadati della risposta, ma usano chiavi di sessione compatibili con i thread solo quando getMe di Telegram restituisce has_topics_enabled: true. Le sostituzioni ritirate dm.threadReplies e direct.*.threadReplies sono state rimosse; la modalità thread di BotFather è l'unica fonte attendibile. Eseguire openclaw doctor --fix per rimuovere le chiavi di configurazione obsolete.

Messaggi audio

Telegram distingue i messaggi vocali dai file audio. Impostazione predefinita: comportamento da file audio; inserire il tag [[audio_as_voice]] nella risposta dell'agente per forzare l'invio come messaggio vocale. Le trascrizioni dei messaggi vocali in entrata vengono presentate nel contesto dell'agente come testo generato automaticamente e non attendibile, ma il rilevamento delle menzioni continua a usare la trascrizione non elaborata, affinché i messaggi vocali soggetti al requisito di menzione continuino a funzionare.

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

Messaggi video

Telegram distingue i file video dai videomessaggi. I videomessaggi non supportano didascalie; il testo del messaggio fornito viene inviato separatamente.

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

Posizioni e luoghi

Usare l'azione send esistente con un unico oggetto autonomo location. Le coordinate inviano un segnaposto nativo; aggiungendo sia name sia address viene inviata una scheda nativa del luogo. Gli invii di posizioni non possono essere combinati con testo del messaggio o contenuti multimediali.

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

Adesivi

In entrata: i file WEBP statici vengono scaricati ed elaborati (segnaposto <media:sticker>); i file TGS animati e WEBM video vengono ignorati.

Campi del contesto degli adesivi: Sticker.emoji, Sticker.setName, Sticker.fileId, Sticker.fileUniqueId, Sticker.cachedDescription. Le descrizioni vengono memorizzate nella cache dello stato SQLite del Plugin OpenClaw per ridurre le chiamate ripetute al sistema di visione.

Abilitare le azioni per gli adesivi:

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

Invio:

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

Ricerca negli adesivi memorizzati nella cache:

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

Le reazioni di Telegram arrivano come aggiornamenti message_reaction, separati dai payload dei messaggi. Quando sono abilitate, OpenClaw accoda eventi di sistema come Telegram reaction added: 👍 by Alice (@alice) on msg 42.

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

own indica soltanto le reazioni degli utenti ai messaggi inviati dal bot (con la massima affidabilità possibile tramite una cache dei messaggi inviati). Gli eventi di reazione rispettano comunque i controlli di accesso di Telegram (dmPolicy, allowFrom, groupPolicy, groupAllowFrom); i mittenti non autorizzati vengono ignorati.

Telegram non fornisce gli ID dei thread negli aggiornamenti delle reazioni: i gruppi senza forum vengono instradati alla sessione della chat di gruppo; i gruppi con forum vengono instradati alla sessione dell'argomento generale (:topic:1), non all'esatto argomento di origine.

allowed_updates per polling/Webhook include automaticamente message_reaction.

ackReaction invia un'emoji di conferma mentre OpenClaw elabora un messaggio in entrata. messages.ackReactionScope stabilisce quando viene inviata.

Ordine di risoluzione dell'emoji:

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• emoji di riserva dell'identità dell'agente (agents.list[].identity.emoji, altrimenti "👀")

Telegram richiede un'emoji Unicode (ad esempio "👀"); usare "" per disabilitare la reazione per un canale o un account.

Ambito (messages.ackReactionScope, valore predefinito "group-mentions"; attualmente nessuna sostituzione a livello di account Telegram o canale Telegram):

all (messaggi diretti + gruppi, inclusi gli eventi ambientali delle stanze), direct (solo messaggi diretti), group-all (ogni messaggio di gruppo tranne gli eventi ambientali delle stanze, nessun messaggio diretto), group-mentions (gruppi quando viene menzionato il bot; nessun messaggio diretto — valore predefinito), off / none (disabilitato).

Le scritture della configurazione del canale sono abilitate per impostazione predefinita (configWrites !== false). Le scritture attivate da Telegram includono gli eventi di migrazione dei gruppi (migrate_to_chat_id, aggiorna channels.telegram.groups) e /config set / /config unset (richiede l'abilitazione del comando).

Disabilitazione:

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

L'impostazione predefinita è il polling prolungato. Per la modalità Webhook, impostare channels.telegram.webhookUrl e channels.telegram.webhookSecret; facoltativi: webhookPath (valore predefinito /telegram-webhook), webhookHost (valore predefinito 127.0.0.1), webhookPort (valore predefinito 8787), webhookCertPath (certificato autofirmato in formato PEM per configurazioni con IP diretto o senza dominio).

In modalità polling prolungato, OpenClaw rende persistente il proprio indicatore di riavvio soltanto dopo che un aggiornamento è stato inoltrato correttamente; se un gestore non riesce a elaborarlo, l'aggiornamento rimane ripetibile nello stesso processo anziché essere contrassegnato come completato.

Il listener locale si associa per impostazione predefinita a 127.0.0.1:8787. Per l'ingresso pubblico, collocare un proxy inverso davanti alla porta locale oppure impostare intenzionalmente webhookHost: "0.0.0.0".

La modalità Webhook convalida le protezioni della richiesta, il token segreto di Telegram e il corpo JSON, quindi registra l'aggiornamento nella coda di ingresso persistente prima di restituire un 200 vuoto. L'acquisizione persistente completata include x-openclaw-delivery-accepted: durable; le risposte relative a integrità, instradamento, autenticazione, convalida ed errori di archiviazione omettono questa intestazione. I proxy inversi e i controller degli host possono richiedere l'intestazione per distinguere l'acquisizione da parte di OpenClaw da un generico 200 vuoto, senza dedurre l'accettazione dai tempi di risposta.

OpenClaw elabora quindi l'aggiornamento in modo asincrono attraverso le stesse corsie del bot per chat/argomento usate dal polling prolungato, in modo che le operazioni lente dell'agente non ritardino l'ACK di consegna di Telegram.

• channels.telegram.textChunkLimit valore predefinito 4000; streaming.chunkMode="newline" preferisce i confini tra paragrafi (righe vuote) prima della suddivisione per lunghezza.
• channels.telegram.mediaMaxMb (valore predefinito 100) limita le dimensioni dei contenuti multimediali in entrata e in uscita.
• channels.telegram.mediaGroupFlushMs (valore predefinito 500, intervallo 10-60000) controlla per quanto tempo gli album/gruppi multimediali vengono memorizzati nel buffer prima che OpenClaw li inoltri come un unico messaggio in entrata. Aumentarlo se le parti dell'album arrivano in ritardo; diminuirlo per ridurre la latenza della risposta all'album.
• channels.telegram.timeoutSeconds sostituisce il timeout del client API (se non impostato, si applica il valore predefinito di grammY). I client bot limitano i valori configurati inferiori al limite di 60 secondi per le richieste di testo/digitazione in uscita, affinché grammY non interrompa la consegna della risposta visibile prima che possano intervenire il limite del trasporto di OpenClaw e il meccanismo di ripiego. Il long polling continua a usare un limite di 45 secondi per le richieste getUpdates, affinché i polling inattivi non vengano abbandonati indefinitamente.
• channels.telegram.pollingStallThresholdMs ha come valore predefinito 120000; regolarlo tra 30000 e 600000 solo in caso di riavvii dovuti a falsi positivi di blocco del polling.
• la cronologia del contesto di gruppo usa channels.telegram.historyLimit o messages.groupChat.historyLimit (valore predefinito 50); 0 la disabilita.
• il contesto supplementare di risposta/citazione/inoltro viene normalizzato in un'unica finestra di contesto della conversazione selezionata quando il Gateway ha osservato i messaggi principali; la cache dei messaggi osservati risiede nello stato del Plugin SQLite di OpenClaw e openclaw doctor --fix importa i file complementari legacy. Telegram include un solo reply_to_message superficiale per aggiornamento, pertanto le catene più vecchie della cache sono limitate a tale payload.
• le liste di autorizzazione di Telegram determinano principalmente chi può attivare l'agente, non costituiscono un limite completo di oscuramento del contesto supplementare.
• cronologia dei messaggi diretti: channels.telegram.dmHistoryLimit, channels.telegram.dms["<user_id>"].historyLimit.
• channels.telegram.retry si applica agli strumenti ausiliari di invio di Telegram (CLI/strumenti/azioni) per gli errori recuperabili dell'API in uscita. La consegna della risposta finale in entrata usa un nuovo tentativo di invio sicuro limitato per gli errori precedenti alla connessione, ma non ripete le richieste in caso di risposte di rete ambigue successive all'invio, che potrebbero duplicare i messaggi visibili.

Le destinazioni di invio della CLI e dello strumento per i messaggi accettano un ID chat numerico, un nome utente o la destinazione di un argomento del 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"

I sondaggi usano openclaw message poll e supportano gli argomenti del 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

Opzioni dei sondaggi esclusive di Telegram: --poll-duration-seconds (5-600), --poll-anonymous, --poll-public, --thread-id (o una destinazione :topic:). --poll-option viene ripetuto 2-12 volte (limite delle opzioni di Telegram).

L'invio tramite Telegram supporta anche --presentation con blocchi buttons per le tastiere incorporate (quando channels.telegram.capabilities.inlineButtons lo consente), --pin o --delivery '{"pin":true}' per richiedere la consegna fissata quando il bot può fissare messaggi nella chat e --force-document per inviare immagini, GIF e video in uscita come documenti anziché come caricamenti compressi, animati o video.

Controllo delle azioni: channels.telegram.actions.sendMessage=false disabilita tutti i messaggi in uscita, inclusi i sondaggi; channels.telegram.actions.poll=false disabilita la creazione di sondaggi lasciando abilitati gli invii normali.

Telegram supporta le approvazioni dell'esecuzione nei messaggi diretti degli approvatori e può facoltativamente pubblicare le richieste nella chat o nell'argomento di origine. Gli approvatori devono essere ID utente Telegram numerici.

• channels.telegram.execApprovals.enabled ("auto" abilita la funzionalità quando è possibile determinare almeno un approvatore)
• channels.telegram.execApprovals.approvers (in alternativa usa gli ID numerici dei proprietari da commands.ownerAllowFrom)
• channels.telegram.execApprovals.target: dm (valore predefinito) | channel | both
• agentFilter, sessionFilter

channels.telegram.allowFrom, groupAllowFrom e defaultTo controllano chi può comunicare con il bot e dove vengono inviate le risposte normali; non rendono un utente approvatore dell'esecuzione. Il primo abbinamento tramite messaggio diretto approvato inizializza commands.ownerAllowFrom quando non esiste ancora un proprietario dei comandi, consentendo alle configurazioni con un solo proprietario di funzionare senza duplicare gli ID in execApprovals.approvers.

La consegna nel canale mostra il testo del comando nella chat; abilitare channel o both solo in gruppi/argomenti attendibili. Quando la richiesta arriva in un argomento del forum, OpenClaw conserva l'argomento per la richiesta di approvazione e il relativo seguito. Per impostazione predefinita, le approvazioni dell'esecuzione scadono dopo 30 minuti.

I pulsanti di approvazione incorporati richiedono inoltre che channels.telegram.capabilities.inlineButtons consenta la superficie di destinazione (dm, group o all). Gli ID di approvazione con prefisso plugin: vengono risolti tramite le approvazioni del Plugin; gli altri vengono prima risolti tramite le approvazioni dell'esecuzione.

Consultare Approvazioni dell'esecuzione.

• Se requireMention=false, la modalità privacy di Telegram deve consentire la visibilità completa: BotFather /setprivacy -> Disable, quindi rimuovere e aggiungere nuovamente il bot al gruppo.
• openclaw channels status avvisa quando la configurazione prevede messaggi di gruppo senza menzione.
• openclaw channels status --probe verifica gli ID numerici espliciti dei gruppi; non è possibile controllare l'appartenenza per il carattere jolly "*".
• Test rapido della sessione: /activation always.

• Quando channels.telegram.groups esiste, il gruppo deve essere elencato (oppure deve includere "*").
• Verificare che il bot appartenga al gruppo.
• Esaminare openclaw logs --follow per conoscere i motivi per cui i messaggi vengono ignorati.

• Autorizzare l'identità del mittente (abbinamento e/o allowFrom numerico); l'autorizzazione dei comandi continua ad applicarsi anche quando il criterio del gruppo è open.
• setMyCommands failed con BOT_COMMANDS_TOO_MUCH indica che il menu nativo contiene troppe voci; ridurre i comandi di Plugin/Skills/personalizzati oppure disabilitare i menu nativi.
• Le chiamate di avvio deleteMyCommands / setMyCommands e le chiamate di digitazione sendChatAction sono limitate e, in caso di timeout della richiesta, vengono ripetute una volta tramite il trasporto di ripiego di Telegram. Gli errori persistenti di rete/recupero indicano generalmente che il DNS/HTTPS verso api.telegram.org non è raggiungibile.

• getMe returned 401 è un errore di autenticazione di Telegram relativo al token del bot configurato. Copiare nuovamente o rigenerare il token in BotFather, quindi aggiornare channels.telegram.botToken, tokenFile, accounts.<id>.botToken o TELEGRAM_BOT_TOKEN (account predefinito).
• deleteWebhook 401 Unauthorized durante l'avvio è anch'esso un errore di autenticazione; considerarlo come «nessun Webhook esistente» rimanderebbe semplicemente lo stesso errore di token non valido a una chiamata API successiva.

• Node 22+ con un recupero/proxy personalizzato può causare un'interruzione immediata se i tipi AbortSignal non corrispondono.
• Alcuni host risolvono prima api.telegram.org in IPv6; un'uscita IPv6 non funzionante causa errori intermittenti dell'API.
• I registri contenenti TypeError: fetch failed o Network request for 'getUpdates' failed! vengono ritentati come errori di rete recuperabili.
• Durante l'avvio del polling, OpenClaw riutilizza per grammY il controllo getMe riuscito all'avvio, affinché l'esecutore non debba eseguire un secondo getMe prima del primo getUpdates.
• Se deleteWebhook non riesce a causa di un errore di rete transitorio durante l'avvio del polling, OpenClaw procede con il long polling invece di effettuare un'altra chiamata al piano di controllo precedente al polling. Un Webhook ancora attivo emerge quindi come conflitto getUpdates; OpenClaw ricrea il trasporto e ripete la pulizia del Webhook.
• Se i socket di Telegram vengono riciclati con una breve cadenza fissa, verificare la presenza di un valore channels.telegram.timeoutSeconds basso: i client bot limitano i valori configurati al di sotto dei limiti delle richieste in uscita e getUpdates, ma le versioni precedenti potevano interrompere ogni polling o risposta quando questo valore era impostato al di sotto di tali limiti.
• Polling stall detected nei registri indica che OpenClaw riavvia il polling e ricrea il trasporto dopo 120 secondi senza un completamento del controllo di attività del long polling, per impostazione predefinita.
• openclaw channels status --probe e openclaw doctor avvisano quando un account di polling in esecuzione non ha completato getUpdates dopo il periodo di tolleranza iniziale, un account Webhook in esecuzione non ha completato setWebhook dopo il periodo di tolleranza iniziale oppure l'ultima attività riuscita del trasporto di polling è obsoleta.
• Aumentare channels.telegram.pollingStallThresholdMs solo quando le chiamate getUpdates di lunga durata funzionano correttamente, ma l'host continua a segnalare falsi riavvii per blocco del polling. I blocchi persistenti indicano generalmente problemi di uscita relativi a proxy, DNS, IPv6 o TLS verso api.telegram.org.
• Telegram rispetta le variabili di ambiente proxy del processo per il trasporto dell'API Bot: HTTP_PROXY, HTTPS_PROXY, ALL_PROXY e le varianti in minuscolo. NO_PROXY / no_proxy possono comunque ignorare api.telegram.org.
• Se OPENCLAW_PROXY_URL è impostato per un ambiente di servizio e non è presente alcuna variabile di ambiente proxy standard, Telegram usa tale URL anche per il trasporto dell'API Bot.
• Sugli host VPS con uscita diretta/TLS instabile, instradare le chiamate API di Telegram attraverso un proxy:

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

• Node 22+ utilizza per impostazione predefinita autoSelectFamily=true (tranne su WSL2). L'ordine dei risultati DNS di Telegram rispetta OPENCLAW_TELEGRAM_DNS_RESULT_ORDER, quindi channels.telegram.network.dnsResultOrder, infine l'impostazione predefinita del processo (ad esempio NODE_OPTIONS=--dns-result-order=ipv4first), con ripiego su ipv4first in Node 22+ se nessuna opzione è applicabile.
• Su WSL2, o quando il comportamento solo IPv4 funziona meglio, forzare la selezione della famiglia:

channels:telegram:network:  autoSelectFamily: false

• Le risposte nell'intervallo di benchmark RFC 2544 (198.18.0.0/15) sono già consentite per impostazione predefinita per i download multimediali di Telegram. Se un proxy fake-IP o trasparente attendibile riscrive api.telegram.org in un altro indirizzo privato/interno/a uso speciale durante i download multimediali, abilitare esplicitamente l'esclusione limitata a Telegram:

channels:telegram:network:  dangerouslyAllowPrivateNetwork: true

• La stessa abilitazione esplicita è disponibile per ogni account in channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork.
• Se il proxy risolve gli host multimediali di Telegram in 198.18.x.x, lasciare inizialmente disattivato il flag pericoloso: tale intervallo è già consentito per impostazione predefinita.

• Sostituzioni temporanee tramite variabili d'ambiente: OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1, OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1, OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first.
• Convalidare le risposte DNS:

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