Diagnostica delle disconnessioni remote di Claude Code: sintomi, criteri e soluzioni per sei tipi di interruzione

Quando esegui Claude Code in remoto, la cosa più frustrante non è non riuscire a connettersi, ma connettersi e poi perdere la connessione, con una causa diversa ogni volta.

La parola "disconnessione" in realtà copre sei guasti completamente diversi. Hanno sintomi caratteristici e soluzioni indipendenti: se tratti la rottura di una connessione persistente causata dal cambio di rete come se fosse il sonno della macchina, disattivare l'ibernazione non servirà a nulla; se consideri una connessione half-open come rete scadente e aspetti che si riprenda da sola, non si riprenderà nemmeno all'alba.

Questo articolo affronta solo la diagnostica delle disconnessioni. Per l'accesso remoto, vedi Claude Code - Accesso remoto: controlla le sessioni ovunque, anche senza il computer locale; per l'uso dal telefono, vedi Claude Code dallo smartphone: visualizza sessioni e approva strumenti su iOS.

Prima i sintomi: quale tipo stai vedendo

Una connessione remota è composta da due segmenti: la macchina di sviluppo che esegue Claude Code ←→ il dispositivo di visualizzazione che hai in mano. Se uno dei due segmenti ha problemi, il risultato è sempre "disconnesso", ma i sintomi sono diversi:

Sintomo osservato	Probabile causa	Vai a
La sessione si blocca all'improvviso e dopo la riconnessione l'avanzamento è fermo a quel momento	Sleep / blocco schermo della macchina di sviluppo	§1
Si disconette nell'istante in cui entri in ascensore, passi al 4G o cambi WiFi	Connessione persistente interrotta	§2
Se chiudi il terminale locale, o la macchina locale va in sleep, la connessione remota si interrompe immediatamente	Vincolo rigido delle soluzioni a proiezione dello schermo	§3
Mostra online, ma i messaggi non ottengono risposta e non ci sono errori	Connessione half-open	§4
È possibile riconnettersi, ma si ritrova una sessione vuota / i messaggi del periodo di disconnessione sono persi	La riconnessione non riprende la sessione originale	§5
Dopo poche ore, la sessione è sparita	Processo terminato e nessun ripristino a freddo	§6

Il tipo più difficile da diagnosticare è il quarto: non dà alcun errore. Lo stato della connessione è verde, i messaggi vengono inviati, ma non c'è mai risposta: è più difficile da individuare di una disconnessione diretta, perché tutti gli indicatori ti dicono "tutto normale".

1. La macchina di sviluppo entra in sleep / blocco schermo / coperchio chiuso

Sintomi: la sessione si blocca del tutto a un certo punto. Dopo la riconnessione, l'avanzamento è ancora al momento dell'interruzione, senza un solo passo avanti.

Perché: molti pensano "la mia macchina di sviluppo è rimasta accesa", ma l'ibernazione del sistema, il sonno da coperchio chiuso e il blocco schermo programmato possono sospendere o addirittura terminare il processo di Claude Code. Dal lato di visualizzazione, il risultato che si vede è "si è bloccato all'improvviso".

Come confermare: torna alla macchina di sviluppo e controlla se il processo è ancora attivo e se nel log di sistema ci sono voci di sospensione. Se il processo c'è ma il timestamp è fermo al momento della disconnessione, è quasi certamente questo.

Soluzione: imposta il piano di alimentazione della macchina di sviluppo su "mai in sospensione / nessuna sospensione con coperchio chiuso". È l'unica soluzione definitiva: nessuna soluzione remota può salvare una macchina che si è già addormentata.

2. Il cambio di rete interrompe la connessione persistente

Sintomi: la disconnessione avviene in un istante ben preciso: entrando in ascensore, passando da WiFi a 4G, o per il re-dial della banda larga di casa a mezzanotte.

Perché: la sincronizzazione remota in tempo reale si basa su una connessione persistente (WebSocket / SSH). Quando l'IP cambia, la connessione si invalida istantaneamente, senza alcuna trattativa.

Come confermare: se l'ora della disconnessione coincide con il cambio di rete, è questo.

Soluzione: questo tipo non si può evitare; l'unico modo è affidarsi a riconnessione automatica + backoff (1s→2s→5s…, per evitare tentativi aggressivi). La SSH nuda non ha questa capacità: se si interrompe, è interrotta, bisogna ricollegarsi manualmente. Quando scegli una soluzione, questo è un requisito fondamentale.

3. Soluzioni a proiezione dello schermo: la macchina locale deve rimanere in primo piano

Sintomi: se chiudi il terminale locale o la macchina locale va in sleep, il telefono si disconnette immediatamente. Non è un timeout graduale, è una perdita di sincronizzazione.

Perché: il Remote Control ufficiale di Anthropic proietta la sessione in esecuzione sul tuo computer locale verso telefono/browser. Il presupposto è che Claude Code sul computer locale rimanga attivo in primo piano e che la macchina resti online. Se la macchina locale cade, il lato remoto non ha un ciclo di vita indipendente a cui aggrapparsi.

Come confermare: chiudi la finestra del terminale locale e verifica se la connessione remota si interrompe nello stesso secondo. Se sì, stai usando una soluzione a proiezione.

Soluzione: passa a un'architettura con servizio daemon permanente sul lato della macchina di sviluppo: il lato che esegue la sessione diventa un servizio in background avviato all'accensione, indipendente dal tuo dispositivo di visualizzazione. Anche se il dispositivo di visualizzazione viene chiuso, cambiato o disconnesso, la sessione continua a girare sulla macchina di sviluppo. Questa è la differenza sostanziale tra "proiezione" e "servizio permanente", non qualcosa che si può regolare con parametri.

4. Connessione half-open: la più difficile da individuare

Sintomi: mostra online, ma i messaggi non ottengono risposta e non ci sono errori. Può bloccarsi per qualche minuto o rimanere bloccato finché non ti riconnetti manualmente.

Perché: quando la rete si interrompe silenziosamente (timeout delle voci NAT, dispositivi intermedi che perdono lo stato, segnale debole fino a perdere pacchetti senza rompere il collegamento), entrambi i lati TCP possono credere di essere ancora connessi, ma i dati non passano più. Senza heartbeat, entrambi mantengono questa illusione.

Come confermare: lo stato della connessione è normale, ma i messaggi inviati non ottengono né conferma di consegna né errori; dopo una disconnessione manuale e una nuova connessione, tutto si ripristina immediatamente: è questo.

Soluzione: è necessario eseguire un heartbeat (keepalive ping) sulla connessione: se entro un tempo prestabilito non arriva alcuna risposta dall'altra parte, si dichiara la connessione half-open e ci si riconnette proattivamente, invece di aspettare. Il criterio deve essere "nessuna risposta ricevuta", non "nessun errore": una connessione half-open non dà mai errori.

5. La riconnessione non riprende la sessione originale / messaggi persi

Sintomi: dopo una disconnessione è possibile riconnettersi, ma si trova una sessione vuota oppure tutti i messaggi inviati dall'altra parte durante la disconnessione sono spariti.

Perché: la riconnessione crea solo una nuova connessione, senza ri-sottoscrivere la connessione alla sessione originale; i messaggi del periodo di disconnessione non vengono memorizzati nella cache per te.

Come confermare: dopo la riconnessione l'ID della sessione è cambiato, oppure la cronologia inizia solo dal momento della riconnessione.

Soluzione: scegli una soluzione che dopo la riconnessione si ri-iscriva automaticamente alla sessione originale e riproduca la cronologia del periodo di disconnessione. Se la riconnessione non riprende la sessione, è come se non ti fossi riconnesso.

6. Il processo della sessione viene terminato e non c'è ripristino a freddo

Sintomi: disconnessioni brevi e riconnessioni funzionano normalmente, ma dopo alcune ore la sessione è sparita.

Perché: il processo di una sessione inattiva da molto tempo può essere terminato; anche lo stesso processo daemon può essere stato riavviato (per aggiornamento o dopo un crash). Lo stato della sessione in memoria scompare di conseguenza.

Come confermare: il problema si manifesta solo con disconnessioni lunghe, non con quelle brevi.

Soluzione: serve la capacità di ripristino a freddo: lo stato della sessione viene salvato su disco, e anche se il processo termina, il contesto può essere ripristinato dal disco. Nel caso ideale, basta inviare un messaggio e la sessione si ripristina automaticamente, senza che tu te ne accorga.

Lista di controllo per la diagnostica (applicabile a qualsiasi soluzione)

Segui questi passaggi in ordine; ognuno può essere verificato in modo indipendente:

1. La macchina che esegue la sessione è andata in sleep o ha bloccato lo schermo? → Disattiva la sospensione automatica e imposta nessuna sospensione a coperchio chiuso. (§1)
2. L'ora della disconnessione coincide con il tuo cambio di rete? → Serve una soluzione con riconnessione automatica + backoff, non fare affidamento sulla SSH nuda. (§2)
3. Se chiudi il terminale locale, la connessione remota si interrompe subito? → Vincolo rigido delle soluzioni a proiezione; devi passare a un'architettura daemon permanente. (§3)
4. Sei bloccato su "mostra online ma i messaggi non ottengono risposta"? → Connessione half-open; solo il rilevamento heartbeat può recuperarla automaticamente. (§4)
5. Dopo la riconnessione la sessione è vuota / mancano messaggi? → Serve "ripresa della sessione originale + riproduzione della cronologia". (§5)
6. Perdi la sessione solo dopo una lunga disconnessione? → Serve salvataggio su disco + ripristino a freddo. (§6)

Come si applica alle soluzioni concrete

Delle sei categorie precedenti, solo la prima è un problema di configurazione della tua macchina; le altre cinque sono determinate dall'architettura: vengono decise al momento della scelta della soluzione e nessuna regolazione di parametri può risolverle dopo che si sono verificate.

Una soluzione remota che non si interrompe deve avere contemporaneamente: un daemon permanente lato macchina di sviluppo (per i rischi residui del §1 e §3), riconnessione automatica + backoff (§2), rilevamento heartbeat (§4), riconnessione alla sessione originale + riproduzione della cronologia (§5), ripristino a freddo su disco (§6).

PandaNpc + pandapaw è stato costruito seguendo punto per punto questi sei criteri: pandapaw viene registrato sulla macchina di sviluppo come daemon permanente avviato all'avvio (non è un terminale che devi tenere aperto manualmente; se va in crash viene riavviato automaticamente); il lato di visualizzazione si riconnette automaticamente con backoff; sulla connessione viene eseguito un heartbeat e se non arriva una risposta si considera la connessione half-open e ci si riconnette attivamente; dopo la riconnessione si ri-iscrive automaticamente alla sessione originale e riproduce la cronologia del periodo di disconnessione; anche se il processo della sessione viene terminato, inviando un messaggio si può ripristinare a freddo dal disco.

Per i dettagli su installazione e connessione, vedi Claude Code - Accesso remoto: controlla le sessioni ovunque, anche senza il computer locale; per la visualizzazione delle sessioni e l'approvazione degli strumenti da telefono, vedi Claude Code dallo smartphone: visualizza sessioni e approva strumenti su iOS.

Una trappola aggiuntiva: con l'accesso remoto, attenzione alla fatturazione

Quando si diagnostica una disconnessione, è facile passare a claude -p (modalità headless), ma a partire dal 15 giugno 2026 Anthropic ha modificato la fatturazione: la modalità headless non usa più il credito dell'abbonamento, ma consuma un piccolo credito mensile dell'SDK; una volta esaurito, viene fatturata secondo l'API, e con un uso intensivo si può facilmente superare il budget. La modalità interattiva (claude REPL) continua a usare il credito dell'abbonamento. Quando cambi soluzione per diagnosticare le disconnessioni, fai attenzione a non cambiare anche la modalità di fatturazione.