Ho visto OpenClaw comportarsi in modi strani. Crasha senza messaggi di errore. Risponde nella lingua sbagliata senza motivo. Si rifiuta di riconoscere che esiste un canale Slack perfettamente configurato. Una volta, ha cominciato a rispondere a ogni messaggio con un haiku. Non ho chiesto la modalità haiku. Non esiste una modalità haiku.
Dopo otto mesi e circa 400 momenti di “che diavolo?”, ho compilato i 10 problemi che ho visto più spesso — dalla mia esperienza personale e dall’aiuto a persone nella comunità Discord. Questi non sono problemi teorici provenienti da casi limite della documentazione. Queste sono le cose che si rompono realmente nelle installazioni.
1. Sindrome del “Funzionava Ieri”
Il problema più comune di OpenClaw non è un bug — è una chiave API scaduta, un modello che è stato 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 controlla la validità della tua chiave API. Infine controlla se il nome del modello nella tua configurazione esiste ancora. Nove volte su dieci, il problema è esterno.
Correzione: Aggiorna la chiave, il nome del modello, o l’endpoint. E imposta un promemoria nel calendario per controllarli mensilmente, perché i fornitori cambiano le cose senza avvisarti.
2. Perdita di Memoria Che Distrugge il Tuo Server
Dopo aver funzionato per alcuni giorni, OpenClaw diventa lento, poi più lento, e infine crasha. L’uso della memoria cresce costantemente fino a quando il sistema operativo termina il processo.
Diagnosi: Quasi sempre è un contesto di conversazione che cresce senza limiti. Ogni messaggio si aggiunge al contesto, e se i messaggi vecchi non vengono potati, il contesto alla fine consuma tutta la memoria disponibile.
Correzione: Configura la compattazione del contesto. Imposta una dimensione massima del contesto. Abilita la potatura automatica dei messaggi vecchi. Riavvia il servizio dopo la correzione e monitora l’uso della memoria per 24 ore per confermare che si stabilizzi.
3. Bot di Slack/Discord Non Risponde
Hai impostato tutto, il bot mostra “online” in Slack/Discord, ma non risponde a nessun messaggio.
Diagnosi: Di solito è un problema di permessi. Il bot ha bisogno di permessi specifici (leggi messaggi, scrivi messaggi, leggi canali) e deve essere invitato esplicitamente a ciascun canale. Un’altra causa comune: l’URL del webhook non è raggiungibile dall’esterno.
Correzione: Controlla i permessi del bot nella console per sviluppatori della piattaforma. Verifica che il bot sia membro del canale in cui 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 raggiungibile).
4. I Cron Job Vanno, Ma Producono Output Vuoto
Il tuo lavoro pianificato si svolge puntualmente (puoi vederlo nei log), ma l’output è vuoto o senza senso.
Diagnosi: Il prompt è probabilmente troppo vago o fa riferimento a dati a cui l’agente non può accedere. “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 spazzatura.
Correzione: Testa il prompt esatto come compito manuale singolo prima. Assicurati che tutte le fonti di dati siano accessibili. Includi istruzioni esplicite su dove trovare i dati.
5. Le Risposte Sono Terribilmente Lente
Ogni risposta impiega 15-30 secondi anziché i 2-3 secondi attesi.
Diagnosi: Tre cause comuni. Prima: il tuo contesto di conversazione è troppo grande (il modello deve elaborare migliaia di token di cronologia prima di generare una risposta). Secondo: l’API del modello è lenta (controlla lo stato del fornitore). Terzo: latenza di rete tra il tuo server e l’endpoint API.
Correzione: Per la dimensione del contesto: abilita la compattazione, 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 di “Rate Limited”
Improvvisi picchi di errori 429, o il bot che tace durante i picchi di utilizzo.
Diagnosi: Stai superando il limite di richieste del tuo fornitore API. Questo accade quando più utenti interagiscono simultaneamente, o quando un flusso di lavoro attiva molte chiamate API in rapida successione.
Correzione: Implementa la code di richieste con pianificazione consapevole dei limiti di frequenza. Aggiorna il tuo livello API se il livello gratuito è troppo restrittivo. Per scenari di picco, aggiungi backoff esponenziale (aspetta e riprova con ritardi crescenti).
7. L’Agente Dice Cose Che Non Dovrebbe
L’agente rivela dettagli del prompt di sistema, risponde in modo inappropriato, o si allontana dall’argomento in modi che sembrano iniezione di prompt.
Diagnosi: Se l’agente è esposto a input non attendibili (canali pubblici, messaggi degli utenti), è probabile che ci sia iniezione di prompt. Qualcuno ha creato un input che sovrascrive le tue istruzioni di sistema.
Correzione: Aggiungi filtraggio dell’output per schemi sensibili (chiavi API, frammenti di prompt di sistema). Implementa la validazione degli input per schemi di iniezione noti. Per configurazioni ad alta sicurezza, elabora input non attendibili 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 intermittenti.
Diagnosi: Esaurimento del pool di connessione (troppi collegamenti aperti), problemi di autenticazione (password cambiata, certificato SSL scaduto), o problemi di rete (firewall bloccante, risoluzione DNS che fallisce).
Correzione: Controlla le impostazioni del pool di connessione e aumentale se necessario. Verifica le credenziali. Testa la connessione in modo indipendente (usa un client 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 specifico account utente. Questo account utente deve avere permessi di lettura/scrittura per le directory a cui l’agente sta cercando di accedere.
Correzione: Controlla quale utente esegue OpenClaw. Verifica che quell’utente abbia i permessi appropriati sulle directory di destinazione. Su Linux: ls -la per controllare, 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 impostata smette di funzionare.
Diagnosi: Cambiamenti nel formato di configurazione tra le versioni, rimozione di funzionalità deprecate, o conflitti di dipendenze. Questo è il problema più frustrante perché non hai cambiato il tuo codice — volevi solo le ultime funzionalità.
Correzione: Leggi il changelog prima di aggiornare. Esegui il 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 ripristinare immediatamente. Non aggiornare mai in 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 API, connessione database, rete)
3. Controlla cosa è cambiato (hai aggiornato qualcosa? Il fornitore ha cambiato qualcosa?)
4. Riproduci il problema (puoi attivarlo costantemente?)
5. Cerca nella community Discord (qualcun altro probabilmente ha già affrontato questo)
E quando tutto fallisce: riavvia il servizio e vedi se il problema scompare. Non dovrebbe essere il primo passo, ma è un’ultima risorsa valida. A volte i computer si comportano semplicemente come computer.
🕒 Published: