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 riaggiungi il bot in ogni gruppo affinché Telegram applichi la modifica.

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

I bot amministratori ricevono tutti i messaggi di gruppo, il che è 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/topic: messaggio di anteprima + editMessageText

Requisito:

• channels.telegram.streaming è off | partial | block | progress (predefinito: partial)
• progress mantiene una bozza di stato modificabile per l'avanzamento degli strumenti, la cancella al completamento e invia la risposta finale come messaggio normale
• streaming.preview.toolProgress controlla se gli aggiornamenti degli strumenti/di avanzamento riutilizzano lo stesso messaggio di anteprima modificato (predefinito: true quando lo streaming di anteprima è attivo)
• streaming.preview.commandText controlla il dettaglio command/exec all'interno di quelle righe di avanzamento strumenti: raw (predefinito, conserva il comportamento rilasciato) o status (solo etichetta dello strumento)
• i valori legacy channels.telegram.streamMode e booleani streaming vengono rilevati; esegui openclaw doctor --fix per migrarli a channels.telegram.streaming.mode

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 o riepiloghi di patch. Telegram li mantiene abilitati per impostazione predefinita per corrispondere al comportamento rilasciato di OpenClaw 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 command/exec, imposta:

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

Usa la modalità progress quando vuoi un avanzamento degli strumenti visibile senza modificare la risposta finale nello stesso messaggio. Inserisci la policy del testo del 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 dell'anteprima di Telegram sono disabilitate e le comunicazioni generiche su strumenti/avanzamento vengono soppresse invece di essere inviate come messaggi di stato autonomi. Le richieste di approvazione, i payload multimediali e gli errori passano comunque attraverso la normale consegna finale. Usa streaming.preview.toolProgress: false quando vuoi solo mantenere le modifiche dell'anteprima della risposta nascondendo al contempo le righe di stato dell'avanzamento degli strumenti.

Per risposte solo testo:

• anteprime brevi in DM/gruppo/topic: 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 nella risposta
• se la modifica finale fallisce prima che il testo completato sia confermato, OpenClaw usa la normale consegna finale e ripulisce l'anteprima obsoleta

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

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

Flusso di ragionamento solo Telegram:

• /reasoning stream invia il ragionamento all'anteprima live durante la generazione
• l'anteprima del ragionamento viene eliminata dopo la consegna finale; usa /reasoning on quando il ragionamento deve rimanere visibile
• la risposta finale viene inviata senza testo di ragionamento

Il testo in uscita usa Telegram parse_mode: "HTML".

• Il testo in stile Markdown viene renderizzato in HTML sicuro per Telegram.
• L'HTML grezzo del modello viene sottoposto a escape per ridurre gli errori di parsing di Telegram.
• Se Telegram rifiuta l'HTML parsato, OpenClaw riprova come testo normale.

Le anteprime dei link sono abilitate per impostazione predefinita e possono essere disabilitate con channels.telegram.linkPreview: false.

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

Valori predefiniti dei comandi nativi:

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

Aggiungi voci di menu per comandi personalizzati:

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

Regole:

• i nomi vengono normalizzati (rimozione di / iniziale, minuscole)
• 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 un comportamento
• i comandi di plugin/skill possono comunque funzionare quando digitati anche se non sono mostrati nel menu Telegram

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

Errori comuni di configurazione:

• setMyCommands failed con BOT_COMMANDS_TOO_MUCH significa che il menu Telegram è ancora andato oltre il limite dopo il taglio; riduci i comandi plugin/skill/personalizzati o disabilita channels.telegram.commands.native.
• deleteWebhook, deleteMyCommands o setMyCommands che falliscono con 404: Not Found mentre i comandi curl diretti della Bot API funzionano possono indicare che channels.telegram.apiRoot è stato impostato sull'endpoint completo /bot<TOKEN>. apiRoot deve essere solo la root della 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 arresta prima del polling, quindi questo non viene riportato come errore di pulizia del Webhook.
• setMyCommands failed con errori di rete/fetch di solito significa che DNS/HTTPS in uscita verso api.telegram.org è bloccato.

# Comandi di abbinamento 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 trasporta un token di bootstrap a breve durata. Il passaggio di bootstrap integrato mantiene il token del nodo primario a scopes: []; qualsiasi token operatore passato resta limitato a operator.approvals, operator.read, operator.talk.secrets e operator.write. I controlli degli ambiti di bootstrap sono prefissati dal ruolo, quindi quella lista consentita per l'operatore soddisfa solo richieste operatore; i ruoli non operatore hanno comunque bisogno di ambiti sotto il proprio prefisso di ruolo.

Se un dispositivo ritenta 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: Abbinamento.

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)

capabilities: ["inlineButtons"] legacy 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" }],
],
}

I clic di callback vengono passati all'agente come testo: callback_data: <value>

Le azioni degli strumenti Telegram includono:

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

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

Controlli di gating:

• 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 attivo di configurazione/segreti (avvio/ricaricamento), quindi i percorsi di azione non eseguono una nuova risoluzione ad hoc di SecretRef 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 nativo della citazione Telegram. Telegram limita il testo delle citazioni native 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 dei topic aggiungono :topic:<threadId>
• le risposte e la digitazione mirano al thread del topic
• percorso di configurazione del topic: channels.telegram.groups.<chatId>.topics.<threadId>

Caso speciale topic 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à del topic: le voci topic ereditano le impostazioni del gruppo salvo override (requireMention, allowFrom, skills, systemPrompt, enabled, groupPolicy). agentId è solo del topic e non eredita dai valori predefiniti del gruppo.

Routing degli agenti per topic: Ogni topic può instradare a un agente diverso impostando agentId nella configurazione del topic. Questo dà a ogni topic il proprio workspace, la propria memoria e la propria 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 topic ha quindi la propria chiave di sessione: agent:zu:telegram:group:-1001234567890:topic:3

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

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

Il contesto del template espone MessageThreadId e IsForum. Le chat DM con message_thread_id mantengono per impostazione predefinita il routing DM e i metadati di risposta nelle sessioni piatte; usano chiavi di sessione consapevoli dei thread solo quando sono configurate con threadReplies: "inbound", threadReplies: "always", requireTopic: true o una configurazione di argomento corrispondente. Usa channels.telegram.dm.threadReplies di primo livello per l'impostazione predefinita dell'account, oppure direct.<chatId>.threadReplies per un DM.

# 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 sono 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 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 i file video dalle note video.

Esempio di azione 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 (segnaposto <media:sticker>)
• TGS animato: saltato
• WEBM video: saltato

Campi del contesto sticker:

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

File della cache sticker:

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

Gli sticker vengono descritti una volta (quando possibile) e memorizzati nella cache per ridurre le chiamate di visione ripetute.

Abilita le azioni sticker:

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

Azione di invio sticker:

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

Cerca sticker 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 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 significa solo 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 di reazione.
  • i gruppi non forum vengono instradati alla sessione della chat di gruppo
  • i gruppi forum vengono instradati alla sessione dell'argomento generale del gruppo (:topic:1), non all'argomento esatto di origine

allowed_updates per polling/webhook include automaticamente message_reaction.

ackReaction invia un'emoji di conferma mentre OpenClaw elabora un messaggio in ingresso.

Ordine di risoluzione:

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

Note:

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

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,
},
},
}

L'impostazione predefinita è 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 persiste il proprio watermark di riavvio solo dopo che un aggiornamento viene inviato correttamente. Se un handler fallisce, quell'aggiornamento rimane riprovabile 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 convalida le protezioni 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 corsie del bot per chat/per argomento usate dal long polling, così 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 di Telegram vengono memorizzati nel buffer 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 di risposta agli album.
• channels.telegram.timeoutSeconds sovrascrive il timeout del client API Telegram (se non impostato, si applica il predefinito di grammY). I client bot limitano i valori configurati sotto la guardia di 60 secondi per richieste di testo/typing in uscita, così grammY non interrompe la consegna visibile della risposta 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 poll inattivi non vengono abbandonati indefinitamente.
• channels.telegram.pollingStallThresholdMs ha valore predefinito 120000; regola tra 30000 e 600000 solo per riavvii di polling-stall falsi positivi.
• 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 di Telegram regolano principalmente chi può attivare l'agente, non 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 errori API in uscita recuperabili. Anche la consegna della risposta finale in ingresso usa un retry bounded safe-send per errori Telegram pre-connessione, ma non riprova envelope di rete ambigue post-invio che potrebbero duplicare i messaggi visibili.

I target di invio CLI e message-tool possono essere ID chat numerico, username o un 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 poll 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 poll 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 e GIF in uscita come documenti invece che come caricamenti foto compressi o media animati

Gating delle azioni:

• 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 gli invii regolari

Telegram supporta approvazioni exec nei DM degli approvatori e può opzionalmente 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 proprietario 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 pairing DM approvato inizializza commands.ownerAllowFrom quando non esiste ancora un proprietario dei comandi, quindi la configurazione con un solo proprietario continua a funzionare senza duplicare gli ID in execApprovals.approvers.

La consegna nel canale mostra il testo del comando nella chat; abilita channel o both solo in gruppi/argomenti fidati. 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 anche che channels.telegram.capabilities.inlineButtons consenta la superficie target (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 -> Disabilita
  • quindi rimuovi e aggiungi di nuovo il bot al gruppo
• openclaw channels status avvisa quando la configurazione si aspetta messaggi di gruppo senza menzione.
• openclaw channels status --probe può controllare ID di gruppo numerici espliciti; il carattere jolly "*" non può essere verificato per l'appartenenza.
• test rapido di sessione: /activation always.

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

• autorizza la tua identità mittente (associazione 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 di Plugin/Skill/personalizzati oppure disabilita i menu nativi
• le chiamate di avvio deleteMyCommands / setMyCommands e le chiamate di digitazione sendChatAction sono limitate e riprovano 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 del bot configurato.
• Copia di nuovo o rigenera il token del bot in BotFather, quindi aggiorna channels.telegram.botToken, channels.telegram.tokenFile, channels.telegram.accounts.<id>.botToken o TELEGRAM_BOT_TOKEN per l'account predefinito.
• deleteWebhook 401 Unauthorized durante l'avvio è anch'esso un errore di autenticazione; trattarlo come "non esiste alcun webhook" rinvierebbe soltanto lo stesso errore di token non valido alle chiamate API successive.

• Node 22+ + fetch/proxy personalizzato possono attivare un comportamento di interruzione immediata 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 li ritenta come errori di rete recuperabili.
• Durante l'avvio del polling, OpenClaw riutilizza il probe getMe di avvio riuscito 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 passa comunque al long polling invece di effettuare un'altra chiamata di control plane pre-polling. Un webhook ancora attivo emerge come conflitto getUpdates; OpenClaw quindi ricostruisce il trasporto Telegram e ritenta la pulizia del webhook.
• Se i socket Telegram vengono riciclati con una cadenza fissa breve, controlla se channels.telegram.timeoutSeconds è basso; i client bot limitano i valori configurati sotto le protezioni delle richieste in uscita e getUpdates, ma le versioni precedenti potevano interrompere ogni polling o risposta quando questo valore era impostato sotto tali protezioni.
• Se i log includono Polling stall detected, OpenClaw riavvia il polling e ricostruisce il trasporto Telegram dopo 120 secondi senza liveness di long-poll completata 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 dell'avvio, quando un account webhook in esecuzione non ha completato setWebhook dopo il periodo di tolleranza dell'avvio, o quando l'ultima attività riuscita del trasporto di polling è obsoleta.
• Aumenta channels.telegram.pollingStallThresholdMs solo quando le chiamate getUpdates di lunga durata sono sane ma il tuo host segnala comunque falsi riavvii per stallo del polling. Stalli persistenti di solito indicano problemi di proxy, DNS, IPv6 o egress TLS tra l'host e api.telegram.org.
• Telegram rispetta anche le env proxy del processo per il trasporto Bot API, incluse HTTP_PROXY, HTTPS_PROXY, ALL_PROXY e le loro varianti minuscole. NO_PROXY / no_proxy possono 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 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 come 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 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 i download dei media Telegram per impostazione predefinita. Se una fake-IP attendibile o un proxy trasparente riscrive api.telegram.org verso un 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 media Telegram in 198.18.x.x, lascia prima disattivato il flag pericoloso. I media Telegram consentono già l'intervallo 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
• Valida le risposte DNS:

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