Mi è capitato più volte: riavvio OpenClaw dopo un aggiornamento, una modifica alla configurazione o semplicemente un riavvio del server, oppure faccio una richiesta che riavvia il gateway o per sbaglio mando il comando /restart anziché /reset e qualcosa non torna. Il bot Telegram risulta online, i messaggi arrivano, nessun errore evidente… ma l’agente non risponde.
In situazioni come questa, è naturale pensare subito a un problema di Telegram, al token del bot o al container Docker. E invece, nel caso che ti racconto, la causa era completamente diversa: un evento rimasto bloccato nella coda interna di OpenClaw dopo un riavvio del gateway.
Quello che ho scoperto è interessante perché il problema si manifesta in modo molto silenzioso, portandoti a perdere tempo in verifiche che, in realtà, non c’entrano nulla con l’origine del guasto.
Di cosa parleremo..
Le AI non hanno saputo risolvere il problema
Lo preciso da subito: il mio primo istinto è stato rivolgermi a ChatGPT e Claude per risolvere il problema, beh.. NON FATELO.
Non solo non ti aiutano a risolvere il problema, ma proporranno modifiche sostanziali enormi che complicheranno ulteriormente le cose.
Una volta capito il problema, la soluzione non è complessa ma la configurazione deve rimanere così com’era!
Vediamo nel dettaglio.
Prima di tutto capiamo cosa succede a Telegram su OpenClaude: quali sono i sintomi?
Quando si verifica questo problema, OpenClaw continua a sembrare operativo sotto molti aspetti:
- Il gateway è avviato
- Il provider Telegram viene caricato correttamente
- Il bot continua a ricevere messaggi
Ma dal punto di vista dell’utente nessuna risposta arriva.
In particolare:
- Il bot Telegram risulta online
- I messaggi vengono consegnati
- Il comando
/newnon produce alcun effetto - Il gateway risulta attivo
- Nei log non compaiono errori evidenti
- La getUpdates di Telegram mostra uno spool vuoto
Questa combinazione di sintomi è ciò che rende il problema così subdolo. Lo spool telegram vuoto significa che Telegram ha consegnato il messaggio ad OpenClaw che l’ha ricevuto ma poi non l’ha elaborato, quindi che fine ha fatto?
Le ipotesi iniziali (sbagliate) che ho fatto
Quando Telegram smette di funzionare, ho imparato a fare alcune verifiche automatiche.
In questo caso, però, erano tutte corrette e mostravano uno stato OK.
Non era Telegram
La prima ipotesi era un problema di comunicazione tra Telegram e OpenClaw. Invece Telegram continuava a consegnare gli aggiornamenti al bot e il polling era operativo. Nessun errore di connessione.
Non era il token del bot
Un token errato o revocato è una causa comune. Ma le chiamate di verifica funzionavano perfettamente: le credenziali erano valide.
Non era il provider Telegram
Viene caricato regolarmente all’avvio di OpenClaw. Nessun errore di inizializzazione.
Non era Docker
Ho persino ripristinato una versione precedente dell’immagine, ma il comportamento non cambiava. Ho così escluso il container.
Il problema era nei dati persistenti quindi o configurazione o database.
Non era l’autorizzazione dell’utente
Il pairing era corretto, l’utente Telegram già autorizzato. Nessun errore di permessi.
Dov’era davvero il blocco di Telegram su OpenClaw?
Dopo aver escluso tutte le cause più comuni, ho spostato l’attenzione sulla pipeline interna di elaborazione degli eventi.
Ecco cosa succede: quando OpenClaw riceve un messaggio da Telegram, questo non viene inviato subito all’agente. Prima attraversa una serie di passaggi interni, con una coda e diversi stati.
Gli stati principali sono:
pending– in attesa di essere preso in caricoclaimed– preso in carico da un workerfailed– elaborazione fallita
Lo stato claimed è il punto critico
Uno stato claimed indica che un worker ha preso in carico un evento e sta provando a elaborarlo. Di solito dura pochissimo.
Il problema nasce quando un riavvio, un crash o un’interruzione avvengono nel momento sbagliato. L’evento rimane marcato come “preso in carico” ma non viene mai completato. Dal punto di vista del sistema, resta sospeso in uno stato intermedio. E se la coda contiene eventi bloccati, quelli successivi restano in attesa.
Come ho individuato il problema
La svolta è arrivata analizzando direttamente la coda interna degli eventi.
OpenClaw salva il suo stato persistente in un database SQLite. La posizione esatta varia in base a versione, sistema operativo e personalizzazioni, ma ho trovato il modo di localizzarlo.
Analizzando i conteggi per stato, ho visto subito qualcosa di anomalo: eventi Telegram in stato claimed e altri in pending che non venivano più elaborati.
A quel punto il problema era chiaro: non era Telegram, non era il bot, era la coda interna bloccata.
La soluzione
Una volta individuata la causa, la correzione è stata semplice: liberare la coda.
Ecco i passaggi che ho seguito:
- Arrestare temporaneamente il gateway
- Creare un backup del database di stato
- Identificare gli eventi bloccati
- Marcarli come non più elaborabili (stato
failed) - Riavviare il gateway
Dopo questa pulizia, OpenClaw ha ripreso immediatamente a processare i nuovi messaggi. Ho trovato particolarmente utile anche creare una nuova sessione con /new per forzare la ripartenza del flusso conversazionale.
Automatizzare la procedura con uno script
Una volta compreso il problema, mi sono reso conto che la procedura è sempre la stessa. Così ho scritto uno script Bash che automatizza tutto.
Ecco le tre modalità che ho implementato:
Modalità status
Mostra lo stato attuale della coda: quanti eventi in pending, claimed o failed. Utile per un controllo rapido.
Modalità inspect
Mostra informazioni dettagliate sugli ultimi eventi, compresi timestamp e messaggi di errore. Così puoi capire da quanto tempo qualcosa è bloccato.
Modalità recover
Esegue il recupero completo:
- Ferma il gateway
- Crea un backup del database
- Marca come
failedgli eventi bloccati - Riavvia il servizio
Prima di procedere, chiede conferma esplicita, perché significa rinunciare agli aggiornamenti rimasti in coda.
Come usare lo script
nano ~/openclaw-telegram-queue.sh
chmod +x ~/openclaw-telegram-queue.sh
# Controllare lo stato
~/openclaw-telegram-queue.sh status
# Ispezionare gli eventi bloccati
~/openclaw-telegram-queue.sh inspect
# Eseguire il recovery
~/openclaw-telegram-queue.sh recoverLo script trova automaticamente il database SQLite e la cartella docker-compose, oppure puoi indicarli manualmente con le variabili d’ambiente OPENCLAW_DB_PATH e OPENCLAW_COMPOSE_PATH.
Cosa potrebbe migliorare in OpenClaw
Questa esperienza mi ha fatto pensare ad alcuni miglioramenti che renderebbero il sistema più resiliente:
- Timeout automatici per eventi
claimedtroppo vecchi - Recovery automatica durante l’avvio del gateway
- Strumenti diagnostici integrati per le code
- Comandi CLI dedicati all’ispezione e pulizia delle queue
