Telegram

I bot Telegram usano per impostazione predefinita la Modalità Privacy, che limita i messaggi di gruppo che ricevono.

Se il bot deve vedere tutti i messaggi di gruppo, puoi:

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

Quando modifichi la modalità privacy, rimuovi e aggiungi di nuovo il bot in ogni gruppo, così Telegram applica la modifica.

Lo stato di amministratore è controllato nelle impostazioni del gruppo Telegram.

I bot amministratori ricevono tutti i messaggi di gruppo, cosa utile per un comportamento di gruppo sempre attivo.

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

OpenClaw può trasmettere risposte parziali in tempo reale:

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

Requisito:

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

Gli aggiornamenti di anteprima dell'avanzamento strumenti sono le brevi righe di stato mostrate mentre gli strumenti sono in esecuzione, per esempio esecuzione di comandi, letture di file, aggiornamenti di pianificazione, riepiloghi di patch o testo di preambolo/commento Codex in modalità app-server Codex. Telegram li mantiene abilitati per impostazione predefinita per corrispondere al comportamento OpenClaw rilasciato da v2026.4.22 e versioni successive.

Per mantenere l'anteprima modificata per il testo della risposta ma nascondere le righe di avanzamento strumenti, imposta:

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

Per mantenere visibile l'avanzamento strumenti ma nascondere il testo comando/exec, imposta:

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

Usa la modalità progress quando vuoi avanzamento strumenti visibile senza modificare la risposta finale dentro lo stesso messaggio. Inserisci la policy del testo comando sotto streaming.progress:

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

Usa streaming.mode: "off" solo quando vuoi una consegna solo finale: le modifiche di anteprima Telegram sono disabilitate e il chiacchiericcio generico su strumenti/avanzamento viene soppresso invece di essere inviato come messaggi di stato autonomi. Le richieste di approvazione, i payload multimediali e gli errori continuano a passare attraverso la normale consegna finale. Usa streaming.preview.toolProgress: false quando vuoi mantenere solo le modifiche all'anteprima della risposta nascondendo le righe di stato dell'avanzamento strumenti.

Per le risposte solo testo:

• anteprime brevi DM/gruppo/argomento: OpenClaw mantiene lo stesso messaggio di anteprima ed esegue la modifica finale sul posto
• i finali di testo lunghi che si dividono in più messaggi Telegram riutilizzano l'anteprima esistente come primo blocco finale quando possibile, poi inviano solo i blocchi rimanenti
• i finali in modalità progress cancellano la bozza di stato e usano la normale consegna finale invece di modificare la bozza trasformandola nella risposta
• se la modifica finale fallisce prima che il testo completato sia confermato, OpenClaw usa la normale consegna finale e pulisce l'anteprima obsoleta

Per risposte complesse (per esempio payload multimediali), OpenClaw ripiega sulla normale consegna finale e poi pulisce il messaggio di anteprima.

Lo streaming di anteprima è separato dallo streaming a blocchi. Quando lo streaming a blocchi è abilitato esplicitamente per Telegram, OpenClaw salta lo stream di anteprima per evitare il doppio streaming.

Comportamento dello stream di ragionamento:

• /reasoning stream usa il percorso di anteprima del ragionamento di un canale supportato; su Telegram, trasmette il ragionamento nell'anteprima live durante la generazione
• l'anteprima del ragionamento viene eliminata dopo la consegna finale; usa /reasoning on quando il ragionamento deve restare visibile
• la risposta finale viene inviata senza testo di ragionamento

Il testo in uscita usa per impostazione predefinita messaggi HTML Telegram standard, così le risposte restano leggibili nei client Telegram correnti. Questa modalità di compatibilità supporta normale grassetto, corsivo, link, codice, spoiler e citazioni, ma non blocchi solo rich di Bot API 10.1 come tabelle native, dettagli, rich media e formule.

Imposta channels.telegram.richMessages: true per abilitare i messaggi rich di Bot API 10.1:

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

Quando è abilitato:

• All'agente viene comunicato che i messaggi rich Telegram sono disponibili per questo bot/account.
• Il testo Markdown viene renderizzato attraverso la IR Markdown di OpenClaw e inviato come HTML rich Telegram.
• I payload HTML rich espliciti preservano i tag supportati da Bot API 10.1 come titoli, tabelle, dettagli, rich media e formule.
• Le didascalie dei media usano ancora le didascalie HTML Telegram perché i messaggi rich non sostituiscono le didascalie.

Questo tiene il testo del modello lontano dai sigilli Telegram Rich Markdown, così valute come $400-600K non vengono analizzate come matematica. Il testo rich lungo viene diviso automaticamente tra i limiti di testo rich e blocchi rich di Telegram. Le tabelle oltre il limite di colonne di Telegram vengono inviate come blocchi di codice.

Predefinito: disattivato per compatibilità con i client. I messaggi rich richiedono client Telegram compatibili; alcuni client Desktop, Web, Android e di terze parti correnti mostrano i messaggi rich accettati come non supportati. Mantieni questa opzione disabilitata a meno che ogni client usato con il bot possa renderizzarli. /status mostra se la sessione Telegram corrente ha i messaggi rich attivati o disattivati.

Le anteprime dei link sono abilitate per impostazione predefinita. channels.telegram.linkPreview: false salta il rilevamento automatico delle entità per il testo rich.

La registrazione del menu comandi di Telegram viene gestita all'avvio con setMyCommands.

Impostazioni predefinite dei comandi nativi:

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

Aggiungi voci di menu comando personalizzate:

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

Regole:

• i nomi vengono normalizzati (rimuovi / 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

Note:

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

Se i comandi nativi sono disabilitati, quelli integrati vengono rimossi. I comandi personalizzati/plugin possono comunque registrarsi se configurati.

Errori di configurazione comuni:

• setMyCommands failed con BOT_COMMANDS_TOO_MUCH significa che il menu Telegram ha comunque superato il limite dopo il trimming; riduci i comandi plugin/skill/personalizzati o disabilita channels.telegram.commands.native.
• Il fallimento di deleteWebhook, deleteMyCommands o setMyCommands con 404: Not Found mentre i comandi curl diretti di Bot API funzionano può significare che channels.telegram.apiRoot è stato impostato sull'endpoint completo /bot<TOKEN>. apiRoot deve essere solo la root di Bot API, e openclaw doctor --fix rimuove un /bot<TOKEN> finale accidentale.
• getMe returned 401 significa che Telegram ha rifiutato il token bot configurato. Aggiorna botToken, tokenFile o TELEGRAM_BOT_TOKEN con il token BotFather corrente; OpenClaw si ferma prima del polling, quindi questo non viene segnalato come errore di pulizia Webhook.
• setMyCommands failed con errori di rete/fetch di solito significa che DNS/HTTPS in uscita verso api.telegram.org è bloccato.

Comandi di associazione dispositivo (plugin device-pair)

Quando il plugin device-pair è installato:

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

Il codice di configurazione contiene un token bootstrap di breve durata. Il bootstrap integrato con codice di configurazione restituisce un token nodo durevole con scopes: [] più un token di passaggio operatore limitato per onboarding mobile attendibile. Quel token operatore può leggere la configurazione nativa in fase di configurazione, ma non concede ambiti di mutazione dell'associazione né operator.admin.

Se un dispositivo riprova con dettagli di autenticazione modificati (per esempio ruolo/ambiti/chiave pubblica), la richiesta in sospeso precedente viene sostituita e la nuova richiesta usa un requestId diverso. Riesegui /pair pending prima di approvare.

Maggiori dettagli: Accoppiamento.

Configura l'ambito della tastiera inline:

{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 inlineButtons: "all".

Esempio di azione messaggio:

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

Esempio di pulsante Mini App:

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

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

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

Le azioni dello strumento Telegram includono:

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

Le azioni dei messaggi di canale espongono alias ergonomici (send, react, delete, edit, sticker, sticker-search, topic-create).

Controlli di abilitazione:

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

Nota: edit e topic-create sono attualmente abilitati per impostazione predefinita e non hanno toggle channels.telegram.actions.* separati. Gli invii runtime usano lo snapshot di configurazione/segreti attivo (avvio/ricarica), quindi i percorsi delle azioni non eseguono una nuova risoluzione SecretRef ad hoc per ogni invio.

Semantica della rimozione delle reazioni: /tools/reactions

Telegram supporta tag espliciti di threading delle risposte nell'output generato:

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

channels.telegram.replyToMode controlla la gestione:

• off (predefinito)
• first
• all

Quando il threading delle risposte è abilitato e il testo o la didascalia Telegram originale è disponibile, OpenClaw include automaticamente un estratto di citazione nativa Telegram. Telegram limita il testo della citazione nativa a 1024 unità di codice UTF-16, quindi i messaggi più lunghi vengono citati dall'inizio e ripiegano su una risposta semplice se Telegram rifiuta la citazione.

Nota: off disabilita il threading implicito delle risposte. I tag espliciti [[reply_to_*]] vengono comunque rispettati.

Supergruppi forum:

• le chiavi di sessione degli argomenti aggiungono :topic:<threadId>
• risposte e digitazione hanno come destinazione il thread dell'argomento
• percorso di configurazione dell'argomento: channels.telegram.groups.<chatId>.topics.<threadId>

Caso speciale dell'argomento generale (threadId=1):

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

Ereditarietà degli argomenti: le voci degli argomenti ereditano le impostazioni del gruppo salvo override (requireMention, allowFrom, skills, systemPrompt, enabled, groupPolicy). agentId è solo dell'argomento e non eredita dai valori predefiniti del gruppo. topics."*" imposta i valori predefiniti per ogni argomento in quel gruppo; gli ID argomento esatti prevalgono comunque su "*".

Instradamento agente per argomento: ogni argomento può essere instradato a un agente diverso impostando agentId nella configurazione dell'argomento. Questo offre a ogni argomento il proprio spazio di lavoro, memoria e sessione isolati. Esempio:

{  channels: {    telegram: {      groups: {        "-1001234567890": {          topics: {            "1": { agentId: "main" },      // General topic → main agent            "3": { agentId: "zu" },        // Dev topic → zu agent            "5": { agentId: "coder" }      // Code review → coder agent          }        }      }    }  }}

Ogni argomento ha quindi la propria chiave di sessione: agent:zu:telegram:group:-1001234567890:topic:3

Binding persistente di argomento ACP: gli argomenti forum possono fissare sessioni di harness ACP tramite binding ACP tipizzati di primo livello (bindings[] con type: "acp" e match.channel: "telegram", peer.kind: "group" e un id qualificato per argomento come -1001234567890:topic:42). Attualmente è limitato agli argomenti forum in gruppi/supergruppi. Vedi Agenti ACP.

Spawn ACP vincolato al thread dalla chat: /acp spawn <agent> --thread here|auto associa l'argomento corrente a una nuova sessione ACP; i follow-up vengono instradati direttamente lì. OpenClaw fissa la conferma di spawn nell'argomento. Richiede che channels.telegram.threadBindings.spawnSessions rimanga abilitato (predefinito: true).

Il contesto del template espone MessageThreadId e IsForum. Le chat DM con message_thread_id mantengono i metadati di risposta; usano chiavi di sessione consapevoli del thread solo quando Telegram getMe segnala has_topics_enabled: true per il bot. Gli override precedenti dm.threadReplies e direct.*.threadReplies sono stati ritirati intenzionalmente; usa la modalità con thread di BotFather come singola fonte di verità ed esegui openclaw doctor --fix per rimuovere le chiavi di configurazione obsolete.

Messaggi audio

Telegram distingue le note vocali dai file audio.

• predefinito: comportamento da file audio
• tag [[audio_as_voice]] nella risposta dell'agente per forzare l'invio come nota vocale
• le trascrizioni delle note vocali in ingresso vengono incorniciate come testo generato da macchina e non attendibile nel contesto dell'agente; il rilevamento delle menzioni usa comunque la trascrizione grezza, quindi i messaggi vocali soggetti a gate di menzione continuano a funzionare.

Esempio di azione messaggio:

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

Messaggi video

Telegram distingue tra file video e note video.

Esempio di azione del messaggio:

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

Le note video non supportano le didascalie; il testo del messaggio fornito viene inviato separatamente.

Sticker

Gestione degli sticker in ingresso:

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

Campi di contesto degli sticker:

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

Le descrizioni degli sticker vengono memorizzate nella cache dello stato del Plugin SQLite di OpenClaw per ridurre le chiamate ripetute alla visione.

Abilita le azioni sugli sticker:

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

Azione di invio sticker:

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

Cerca sticker memorizzati nella cache:

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

Le reazioni di Telegram arrivano come aggiornamenti message_reaction (separate dai payload dei messaggi).

Quando abilitate, OpenClaw accoda eventi di sistema come:

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

Configurazione:

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

Note:

• own indica solo le reazioni degli utenti ai messaggi inviati dal bot (best-effort tramite 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 scartati.
• Telegram non fornisce ID di thread negli aggiornamenti delle reazioni.
  • i gruppi non forum vengono indirizzati alla sessione della chat di gruppo
  • i gruppi forum vengono indirizzati alla sessione dell'argomento generale del gruppo (:topic:1), non all'argomento di origine esatto

allowed_updates per polling/webhook include automaticamente message_reaction.

ackReaction invia un'emoji di conferma mentre OpenClaw elabora un messaggio in ingresso. ackReactionScope decide quando quell'emoji viene effettivamente inviata.

Ordine di risoluzione dell'emoji (ackReaction):

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

Note:

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

Ambito (messages.ackReactionScope):

Il provider Telegram legge l'ambito da messages.ackReactionScope (predefinito "group-mentions"). Oggi non esiste alcun override a livello di account Telegram o canale Telegram.

Valori: "all" (DM + gruppi), "direct" (solo DM), "group-all" (ogni messaggio di gruppo, nessun DM), "group-mentions" (gruppi quando il bot viene menzionato; nessun DM — questo è il valore predefinito), "off" / "none" (disabilitato).

Le scritture della configurazione del canale sono abilitate per impostazione predefinita (configWrites !== false).

Le scritture attivate da Telegram includono:

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

Disabilita:

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

Il valore predefinito è il long polling. Per la modalità webhook imposta channels.telegram.webhookUrl e channels.telegram.webhookSecret; opzionali webhookPath, webhookHost, webhookPort (predefiniti /telegram-webhook, 127.0.0.1, 8787).

In modalità long polling, OpenClaw conserva il proprio watermark di riavvio solo dopo che un aggiornamento è stato distribuito correttamente. Se un handler fallisce, quell'aggiornamento rimane ritentabile nello stesso processo e non viene scritto come completato per la deduplicazione al riavvio.

Il listener locale si associa a 127.0.0.1:8787. Per l'ingresso pubblico, metti un reverse proxy davanti alla porta locale oppure imposta intenzionalmente webhookHost: "0.0.0.0".

La modalità webhook valida le guardie della richiesta, il token segreto di Telegram e il corpo JSON prima di restituire 200 a Telegram. OpenClaw elabora quindi l'aggiornamento in modo asincrono tramite le stesse lane bot per chat/per argomento usate dal long polling, quindi i turni lenti dell'agente non trattengono l'ACK di consegna di Telegram.

• Il valore predefinito di channels.telegram.textChunkLimit è 4000.
• channels.telegram.chunkMode="newline" preferisce i confini di paragrafo (righe vuote) prima della suddivisione per lunghezza.
• channels.telegram.mediaMaxMb (predefinito 100) limita la dimensione dei media Telegram in ingresso e in uscita.
• channels.telegram.mediaGroupFlushMs (predefinito 500) controlla per quanto tempo gli album/gruppi multimediali Telegram vengono bufferizzati prima che OpenClaw li invii come un unico messaggio in ingresso. Aumentalo se le parti dell'album arrivano in ritardo; diminuiscilo per ridurre la latenza delle risposte agli album.
• channels.telegram.timeoutSeconds sovrascrive il timeout del client API Telegram (se non impostato, si applica il valore predefinito di grammY). I client bot limitano i valori configurati al di sotto della guardia di 60 secondi per le richieste di testo/typing in uscita, in modo che grammY non interrompa la consegna della risposta visibile prima che la guardia di trasporto e il fallback di OpenClaw possano essere eseguiti. Il long polling usa comunque una guardia di 45 secondi per le richieste getUpdates, così i polling inattivi non vengono abbandonati indefinitamente.
• channels.telegram.pollingStallThresholdMs è predefinito a 120000; regolalo tra 30000 e 600000 solo per riavvii da polling bloccato falsi positivi.
• la cronologia del contesto di gruppo usa channels.telegram.historyLimit o messages.groupChat.historyLimit (predefinito 50); 0 disabilita.
• il contesto supplementare di risposta/citazione/inoltro viene normalizzato in un'unica finestra di contesto conversazionale selezionata quando il Gateway ha osservato i messaggi principali; la cache dei messaggi osservati risiede nello stato Plugin SQLite di OpenClaw e openclaw doctor --fix importa i sidecar legacy. Telegram include negli aggiornamenti solo un reply_to_message superficiale, quindi le catene più vecchie della cache sono limitate al payload di aggiornamento corrente di Telegram.
• le allowlist Telegram regolano principalmente chi può attivare l'agente, non un confine completo di oscuramento del contesto supplementare.
• Controlli della cronologia dei DM:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• La configurazione channels.telegram.retry si applica agli helper di invio Telegram (CLI/strumenti/azioni) per errori API in uscita recuperabili. Anche la consegna della risposta finale in ingresso usa un retry safe-send limitato per errori Telegram precedenti alla connessione, ma non ritenta envelope di rete ambigui successivi all'invio che potrebbero duplicare messaggi visibili.

I target di invio CLI e message-tool possono essere ID chat numerico, nome utente o target di argomento 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 Telegram usano openclaw message poll e supportano gli argomenti 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

Flag di sondaggio solo Telegram:

• --poll-duration-seconds (5-600)
• --poll-anonymous
• --poll-public
• --thread-id per argomenti forum (oppure usa un target :topic:)

L'invio Telegram supporta anche:

• --presentation con blocchi buttons per tastiere inline quando channels.telegram.capabilities.inlineButtons lo consente
• --pin o --delivery '{"pin":true}' per richiedere la consegna fissata quando il bot può fissare messaggi in quella chat
• --force-document per inviare immagini, GIF e video in uscita come documenti invece che come caricamenti foto compressa, media animato o video

Controllo delle azioni:

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

Telegram supporta le approvazioni exec nei DM degli approvatori e può facoltativamente pubblicare prompt nella chat o nell'argomento di origine. Gli approvatori devono essere ID utente Telegram numerici.

Percorso di configurazione:

• channels.telegram.execApprovals.enabled (si abilita automaticamente quando almeno un approvatore è risolvibile)
• channels.telegram.execApprovals.approvers (ripiega sugli ID owner numerici da commands.ownerAllowFrom)
• channels.telegram.execApprovals.target: dm (predefinito) | channel | both
• agentFilter, sessionFilter

channels.telegram.allowFrom, groupAllowFrom e defaultTo controllano chi può parlare con il bot e dove invia le risposte normali. Non rendono qualcuno un approvatore exec. Il primo abbinamento DM approvato inizializza commands.ownerAllowFrom quando non esiste ancora alcun owner dei comandi, quindi la configurazione con un solo owner funziona comunque senza duplicare gli ID sotto execApprovals.approvers.

La consegna nel canale mostra il testo del comando nella chat; abilita channel o both solo in gruppi/argomenti attendibili. Quando il prompt arriva in un argomento forum, OpenClaw conserva l'argomento per il prompt di approvazione e il follow-up. Le approvazioni exec scadono dopo 30 minuti per impostazione predefinita.

I pulsanti di approvazione inline 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 Plugin; gli altri vengono risolti prima tramite le approvazioni exec.

Vedi Approvazioni exec.

• Se requireMention=false, la modalità privacy di Telegram deve consentire visibilità completa.
  • 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 gruppo numerici espliciti; il carattere jolly "*" non può essere verificato tramite membership-probe.
• test rapido della sessione: /activation always.

• quando channels.telegram.groups esiste, il gruppo deve essere elencato (oppure includere "*")
• verifica l'appartenenza del bot al gruppo
• esamina i log: openclaw logs --follow per i motivi di salto

• autorizza la tua identità mittente (abbinamento e/o allowFrom numerico)
• l'autorizzazione dei comandi si applica comunque anche quando la policy del gruppo è open
• setMyCommands failed con BOT_COMMANDS_TOO_MUCH significa che il menu nativo ha troppe voci; riduci i comandi Plugin/skill/personalizzati oppure disabilita i menu nativi
• le chiamate di avvio deleteMyCommands / setMyCommands e le chiamate di typing sendChatAction sono limitate e ritentano una volta tramite il fallback di trasporto di Telegram in caso di timeout della richiesta. Errori persistenti di rete/fetch di solito indicano problemi di raggiungibilità DNS/HTTPS verso api.telegram.org

• getMe returned 401 è un errore di autenticazione Telegram per il token bot configurato.
• Ricopia o rigenera il token bot in BotFather, quindi aggiorna channels.telegram.botToken, channels.telegram.tokenFile, channels.telegram.accounts.<id>.botToken o TELEGRAM_BOT_TOKEN per l'account predefinito.
• Anche deleteWebhook 401 Unauthorized durante l'avvio è un errore di autenticazione; trattarlo come "nessun Webhook esiste" rimanderebbe solo lo stesso errore di token non valido a chiamate API successive.

• Node 22+ + fetch/proxy personalizzato può attivare un comportamento di abort immediato se i tipi AbortSignal non corrispondono.
• Alcuni host risolvono prima api.telegram.org in IPv6; un egress IPv6 non funzionante può causare errori intermittenti dell'API Telegram.
• Se i log includono TypeError: fetch failed o Network request for 'getUpdates' failed!, OpenClaw ora ritenta questi casi come errori di rete recuperabili.
• Durante l'avvio del polling, OpenClaw riusa la sonda getMe di avvio riuscita per grammY, così il runner non ha bisogno di un secondo getMe prima del primo getUpdates.
• Se deleteWebhook fallisce con un errore di rete transitorio durante l'avvio del polling, OpenClaw prosegue nel long polling invece di effettuare un'altra chiamata control-plane pre-poll. Un Webhook ancora attivo emerge come conflitto di getUpdates; OpenClaw quindi ricostruisce il trasporto Telegram e ritenta la pulizia del Webhook.
• Se i socket Telegram vengono riciclati a una cadenza fissa breve, controlla se channels.telegram.timeoutSeconds è basso; i client bot limitano i valori configurati al di sotto delle guardie 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 guardie.
• Se i log includono Polling stall detected, OpenClaw riavvia il polling e ricostruisce il trasporto Telegram dopo 120 secondi senza liveness completata del long-poll per impostazione predefinita.
• openclaw channels status --probe e openclaw doctor avvisano quando un account polling in esecuzione non ha completato getUpdates dopo il periodo di tolleranza all'avvio, quando un account Webhook in esecuzione non ha completato setWebhook dopo il periodo di tolleranza all'avvio, oppure quando l'ultima attività riuscita del trasporto di polling è obsoleta.
• Aumenta channels.telegram.pollingStallThresholdMs solo quando le chiamate getUpdates a lunga durata sono sane ma il tuo host segnala comunque falsi riavvii da polling bloccato. Blocchi persistenti di solito indicano problemi di proxy, DNS, IPv6 o egress TLS tra l'host e api.telegram.org.
• Telegram rispetta anche le variabili env proxy di processo per il trasporto Bot API, incluse HTTP_PROXY, HTTPS_PROXY, ALL_PROXY e le rispettive varianti minuscole. NO_PROXY / no_proxy può comunque bypassare api.telegram.org.
• Se il proxy gestito da OpenClaw è configurato tramite OPENCLAW_PROXY_URL per un ambiente di servizio e non è presente alcuna variabile env proxy standard, Telegram usa quell'URL anche per il trasporto Bot API.
• Su host VPS con egress/TLS diretto instabile, instrada le chiamate API Telegram tramite channels.telegram.proxy:

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

• Node 22+ usa per impostazione predefinita autoSelectFamily=true (tranne WSL2). L'ordine dei risultati DNS di Telegram rispetta OPENCLAW_TELEGRAM_DNS_RESULT_ORDER, poi channels.telegram.network.dnsResultOrder, poi il valore predefinito del processo, ad esempio NODE_OPTIONS=--dns-result-order=ipv4first; se nessuno si applica, Node 22+ ripiega su ipv4first.
• Se il tuo host è WSL2 o funziona esplicitamente meglio con il comportamento solo IPv4, forza 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 dei media di Telegram. Se un fake-IP attendibile o un proxy trasparente riscrive api.telegram.org in qualche altro indirizzo privato/interno/a uso speciale durante i download dei media, puoi aderire al bypass solo per Telegram:

channels:telegram:network:  dangerouslyAllowPrivateNetwork: true

• La stessa adesione è disponibile per account in channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork.
• Se il tuo proxy risolve gli host dei media Telegram in 198.18.x.x, lascia prima disattivato il flag pericoloso. I media Telegram consentono già l'intervallo di benchmark RFC 2544 per impostazione predefinita.

• Override di 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 Adig +short api.telegram.org AAAA