Ho visto OpenClaw fare cose strane. Bloccarsi senza messaggi di errore. Rispondere nella lingua sbagliata senza motivo. Rifiutarsi di riconoscere che esiste un canale Slack perfettamente configurato. Una volta, ha iniziato a rispondere a ogni messaggio con un haiku. Non ho richiesto la modalità haiku. Non c’è una modalità haiku.
Dopo otto mesi e circa 400 momenti di “cosa sta succedendo?”, ho compilato i 10 problemi che ho visto più spesso—secondo la mia esperienza e aiutando le persone sul Discord della comunità. Non si tratta di problemi teorici derivati da casi limite nella documentazione. Sono le cose che si rompono realmente su installazioni reali.
1. Sindrome “Funzionava Ieri”
Il problema più comune con OpenClaw non è un bug — è una chiave API scaduta, un modello deprecato o un endpoint di servizio che è cambiato. Non hai cambiato nulla, ma qualcosa a monte lo ha fatto.
Diagnosi: Controlla prima la pagina di stato del tuo fornitore di modelli. Poi, verifica la validità della tua chiave API. Successivamente, controlla se il nome del modello nella tua configurazione esiste ancora. Nove volte su dieci, il problema è esterno.
Soluzione: Aggiorna la chiave, il nome del modello o l’endpoint. E fissa un promemoria sul tuo calendario per controllare questi elementi ogni mese, poiché i fornitori cambiano le cose senza avvisarti via email.
2. La Fuga di Memoria Che Rovina il Tuo Server
Dopo alcuni giorni di esecuzione, OpenClaw diventa lento, poi più lento, poi si blocca. L’uso della memoria aumenta regolarmente fino a quando il sistema operativo chiude il processo.
Diagnosi: È quasi sempre un contesto di conversazione che cresce senza limiti. Ogni messaggio si aggiunge al contesto, e se i messaggi più vecchi non sono potati, il contesto finisce per consumare tutta la memoria disponibile.
Soluzione: Configura la compressione del contesto. Definisci una dimensione massima del contesto. Abilita la potatura automatica dei messaggi più vecchi. Riavvia il servizio dopo aver applicato la soluzione e monitora l’uso della memoria per 24 ore per confermare che si stabilizzi.
3. Il Bot Slack/Discord Non Risponde
Hai configurato tutto, il bot appare “online” in Slack/Discord, ma non risponde a nessun messaggio.
Diagnosi: Di solito è un problema di autorizzazione. Il bot ha bisogno di autorizzazioni specifiche (leggere messaggi, inviare messaggi, leggere canali) ed è necessario invitarlo in ogni canale esplicitamente. Un’altra causa comune: l’URL del webhook non è accessibile dall’esterno.
Soluzione: Controlla le autorizzazioni del bot nella console per sviluppatori della piattaforma. Verifica che il bot sia membro del canale dove stai testando. Testa l’URL del webhook da una fonte esterna (usa un servizio come httpbin o requestbin per verificare che il tuo endpoint sia accessibile).
4. I Compiti Cron Funzionano Ma Producono Uscite Vuote
Il tuo compito programmato si esegue all’ora stabilita (puoi vederlo nei log), ma l’uscita è vuota o incoerente.
Diagnosi: Il prompt è probabilmente troppo vago o fa riferimento a dati ai quali l’agente non ha accesso. “Riassumi le metriche di oggi” fallisce se l’agente non ha accesso al database delle metriche. Il lavoro si esegue, l’IA non ha nulla con cui lavorare e produce cose inutilizzabili.
Soluzione: Testa il prompt esatto come compito manuale prima. Assicurati che tutte le fonti di dati siano accessibili. Includi istruzioni esplicite su dove trovare i dati.
5. Le Risposte Sono Lentissime
Ogni risposta richiede 15-30 secondi invece delle 2-3 secondi attesi.
Diagnosi: Tre cause comuni. Prima di tutto: il tuo contesto di conversazione è troppo grande (il modello deve elaborare migliaia di token di cronologia prima di generare una risposta). In secondo luogo: l’API del modello è lenta (controlla lo stato del fornitore). In terzo luogo: latenza di rete tra il tuo server e l’endpoint API.
Soluzione: Per la dimensione del contesto: attiva la compressione, limita la lunghezza della cronologia. Per la lentezza dell’API: aspetta, cambia fornitore temporaneamente, o usa una risposta memorizzata quando possibile. Per la rete: considera di ospitare più vicino alla regione del fornitore dell’API.
6. Errori “Rate Limited”
Raffiche improvvise di errori 429, o il bot che diventa silenzioso durante i periodi di alta utilizzo.
Diagnosi: Stai superando il limite di rate del tuo fornitore di API. Questo accade quando più utenti interagiscono contemporaneamente, o quando un flusso di lavoro attiva molte chiamate API in rapida successione.
Soluzione: Implementa una coda per le richieste con un pianificatore consapevole dei limiti di rate. Aggiorna il tuo piano API se quello gratuito è troppo restrittivo. Per scenari di picco, aggiungi un ritardo esponenziale (aspetta e riprova con ritardi crescenti).
7. L’Agente Dice Cose che Non Dovrebbe
L’agente rivela dettagli sul prompt di sistema, risponde in modo inappropriato, o si discosta dal tema in modi che sembrano derivare da iniezioni di prompt.
Diagnosi: Se l’agente è esposto a input non affidabili (canali pubblici, messaggi degli utenti), è probabile un’iniezione di prompt. Qualcuno ha creato un input che sostituisce le tue istruzioni di sistema.
Soluzione: Aggiungi un filtro di uscita per i modelli sensibili (chiavi API, frammenti di prompt di sistema). Implementa una validazione dell’input per i modelli di iniezione noti. Per configurazioni ad alta sicurezza, gestisci gli input non affidabili in un contesto separato dalle istruzioni di sistema.
8. Fallimenti di Connessione al Database
L’agente non riesce a connettersi al tuo database, o le connessioni cadono in modo intermittente.
Diagnosi: Esaurimento del pool di connessioni (troppe connessioni aperte), problemi di autenticazione (password cambiata, certificato SSL scaduto), o problemi di rete (firewall bloccante, fallimento della risoluzione DNS).
Soluzione: Controlla le impostazioni del pool di connessioni e aumentale se necessario. Controlla le credenziali. Testa la connessione in modo indipendente (usa un client di database per confermare che puoi connetterti con le stesse credenziali dallo stesso server).
9. Permessi del File System
L’agente non può leggere o scrivere file, anche se i percorsi sembrano corretti.
Diagnosi: Il processo OpenClaw viene eseguito con un account utente specifico. Questo account utente ha bisogno di permessi di lettura/scrittura sulle directory a cui l’agente cerca di accedere.
Soluzione: Controlla sotto quale utente OpenClaw viene eseguito. Verifica che questo utente abbia i permessi appropriati sulle directory di destinazione. Su Linux: ls -la per verificare, chown o chmod per correggere. Non usare permessi 777 — dai il minimo accesso necessario.
10. Gli Aggiornamenti Rompono Tutto
Aggiorni OpenClaw e la tua configurazione accuratamente regolata smette di funzionare.
Diagnosi: Cambiamenti nel formato di configurazione tra le versioni, funzionalità deprecate rimosse o conflitti di dipendenze. È il problema più frustrante perché non hai cambiato il tuo codice — volevi solo le ultime funzionalità.
Soluzione: Leggi il changelog prima di aggiornare. Fai un backup della tua configurazione prima di aggiornare. Testa l’aggiornamento su un’istanza di sviluppo prima. Se qualcosa si rompe, il tuo backup ti permette di tornare indietro immediatamente. Non aggiornare mai la produzione senza un backup verificato e un piano di rollback.
L’Approccio Universale al Debugging
Quando qualcosa si rompe e non sai perché:
1. Controlla i log (il 90% delle risposte si trova nei log)
2. Controlla i servizi esterni (stato dell’API, connessione al database, rete)
3. Controlla cosa è cambiato (hai aggiornato qualcosa? Il fornitore ha cambiato qualcosa?)
4. Riproduci il problema (puoi attivarlo costantemente?)
5. Cerca nel Discord della comunità (qualcun altro ha probabilmente già incontrato questo problema)
E quando tutto fallisce: riavvia il servizio e vedi se il problema scompare. Non dovrebbe essere il primo passo, ma è un valido ultimo ricorso. A volte, i computer semplicemente fanno di testa loro.
🕒 Published: