# Ripristino di Claude Code: safe mode, /cd e fallback > Diagnosi di Claude Code con safe mode, il comando /cd, i modelli di fallback e il ripristino delle impostazioni. L'ordine dei controlli e i limiti originali. Source: https://ailoot.ai/blog/it/claude-code-safe-mode-recovery/ Canonical: https://ailoot.ai/blog/it/claude-code-safe-mode-recovery/ Language: it Publisher: Ailoot (https://ailoot.ai/) Translation: guide-140 Revision: sha256-5efac9d3918f75b311378178c8d28251ccb621b3178281d3556f4154b1010418 Materiali pratici per lavorare con gli agenti: [documentazione Ailoot](https://ailoot.ai/docs/). ## Cosa cambia in Claude Code a giugno 2026?
Punto chiave L'8 giugno 2026, in Claude Code v2.1.169, Anthropic ha aggiunto il flag `--safe-mode` e il comando `/cd`. Due giorni prima, v2.1.166 aveva introdotto i modelli di fallback, fino a 3 in una catena. Queste tre funzionalità affrontano il problema più comune per chi fa vibe coding: «è andato tutto in tilt, non so di chi sia la colpa e non voglio perdere un'ora a reinstallare».
In precedenza, quando Claude Code iniziava a comportarsi in modo strano—un indicatore di caricamento infinito, un arresto anomalo all'avvio, l'agente che ignorava le regole in `CLAUDE.md`, un hook che non si attivava senza dare segnali—c'era una sola via d'uscita: commentare manualmente le sezioni di `.claude/settings.json`, disabilitare i server MCP uno per uno o, nel peggiore dei casi, eliminare `~/.claude` e reinstallare. In un caso descritto, è stata eliminata `~/.claude` ed è andata persa la configurazione dei server MCP, che aveva richiesto un'ora e mezza di lavoro. In seguito è emerso che la causa era una riga in `CLAUDE.md`, che si sarebbe potuta individuare in 10 secondi, ma lo si è capito solo dopo un ripristino completo. Nel giugno 2026, Anthropic ha introdotto tre meccanismi che cambiano questo scenario. In breve, cosa è arrivato e quando: | Versione | Data | Novità | |----|----|----| | **2.1.166** | 6 giugno 2026 | Impostazione `fallbackModel` + flag `--fallback-model` per le sessioni interattive | | **2.1.169** | 8 giugno 2026 | Flag `--safe-mode` e variabile d'ambiente `CLAUDE_CODE_SAFE_MODE`, comando `/cd` | | **2.1.176** | 12 giugno 2026 | Correzione: `/cd` e il passaggio ai worktree non mostravano più il vecchio branch git | Di seguito, ogni meccanismo viene spiegato passo dopo passo, insieme all'ordine in cui applicarli quando una sessione di Claude Code deraglia. ## Cosa manda più spesso in crisi Claude Code?
Punto chiave Sulla base dell'esperienza descritta, Claude Code va tipicamente in crisi per chi fa vibe coding a causa di quattro fattori: un `CLAUDE.md` troppo esteso con regole contraddittorie, un hook con il codice di uscita sbagliato, un server MCP che fallisce senza segnalarlo e impostazioni sovrapposte su tre livelli di `settings.json`. C'è un solo colpevole, la diagnosi richiede pochi minuti e il panico spinge a ricorrere subito a `rm -rf`.
Nell'esempio descritto, `CLAUDE.md` era stato inizialmente composto da 80 righe e aveva funzionato per un mese. Nel secondo mese, si è iniziato a notare che una volta a settimana Claude violava tutte le regole impostate: toccava `.env`, eseguiva `git push --force`, frugava in `node_modules`. Non per malizia: semplicemente dimenticava. Una volta è stato eliminato `.gitignore` e non era subito chiaro il motivo. Questo scenario è trattato più nel dettaglio nella [guida a `CLAUDE.md`](https://ailoot.ai/blog/it/claude-md-template/). Quando `CLAUDE.md` supera le 400 righe, inizia a creare problemi silenziosamente: occupa una parte significativa della finestra di contesto all'avvio della sessione e diluisce le istruzioni importanti tra quelle secondarie. Claude continua formalmente a leggere il file, quindi dall'esterno sembra che «le regole ci siano, ma non funzionino»: un segnale tipico di un contratto troppo esteso. Gli hook sono la seconda causa comune. `Claude Code hooks` presentano una particolarità che Anthropic non sottolinea. In altre parole, `sys.exit(1)` in un hook Python (o qualsiasi convenzionale «errore» Unix) non fermerà Claude. Solo il codice `2` è bloccante. Nel caso descritto, l'hook era considerato un «divieto assoluto», ma in pratica registrava una segnalazione e consentiva l'azione. I server MCP sono il terzo livello e possono rompersi a modo loro. Spesso il sintomo è lo stesso: i comandi MCP sono disponibili, ma restituiscono `failed` senza traceback. Per saperne di più sulla configurazione di MCP e sull'aggiunta di server con `claude mcp add`, consulta la [guida dedicata](https://ailoot.ai/blog/it/mcp-servers-claude-code/). La quarta causa è la gerarchia a tre livelli di `settings.json`. Ci sono `~/.claude/settings.json` (livello utente), `.claude/settings.json` nella radice del progetto (progetto), `.claude/settings.local.json` (locale) e, facoltativamente, le impostazioni gestite da un amministratore aziendale. Vengono combinate secondo regole di priorità. Quando qualcuno aggiunge un server MCP a livello di progetto mentre al livello utente ne hai una voce simile con una configurazione di avvio diversa, si verifica un conflitto silenzioso che dà l'impressione che «Claude Code sia rotto». ## Come funziona `--safe-mode` e cosa disabilita?
Punto chiave `claude --safe-mode` avvia Claude Code con le personalizzazioni completamente disabilitate: `CLAUDE.md`, plugin, skill, hook, server MCP, comandi utente, agenti, stili di output, workflow e combinazioni di tasti. Restano disponibili l'autorizzazione, la selezione del modello, gli strumenti integrati e i permessi. È uno strumento diagnostico: se il problema scompare in safe mode, la colpa è di uno dei livelli che hai aggiunto.
La formulazione originale di Anthropic nel changelog della v2.1.169 è:

Aggiunto il flag --safe-mode (e CLAUDE_CODE_SAFE_MODE) per avviare Claude Code con le personalizzazioni disabilitate (CLAUDE.md, plugin, skill, hook, server MCP) a fini diagnostici.

— Registro delle modifiche di Anthropic Claude Code, https://code.claude.com/docs/en/changelog
Anthropic chiarisce nella documentazione sulla configurazione del modello:

Per verificare se la causa sono le personalizzazioni, avvia una sessione con claude --safe-mode, che disabilita CLAUDE.md, le skill, i server MCP e gli hook. Lo stato di Git e i nomi delle directory non sono considerati personalizzazioni e restano disponibili.

— Documentazione Anthropic - Configurazione del modello, https://code.claude.com/docs/en/model-config
È uno **strumento diagnostico**, non un «ambiente pulito». Safe mode aiuta a rispondere a una domanda: il problema dipende dal comportamento predefinito di Claude Code o dalle personalizzazioni aggiunte? Questo rientra nel context engineering: gestire ciò che Claude vede e non vede in un dato momento. Se in safe mode funziona tutto, è chiaro che i livelli vanno controllati con una ricerca binaria. Se non funziona, il problema riguarda l'installazione, l'autorizzazione, la rete o l'infrastruttura; in tal caso ha senso controllare `claude doctor` e i log. Cosa disabilita safe mode (elenco ufficiale di Anthropic: 5 livelli principali): - `CLAUDE.md` a tutti i livelli (utente / progetto) - Plugin - Skill - Hook - Server MCP Cosa continua a funzionare: - Autorizzazione (la sessione OAuth o la chiave API) - Selezione del modello (`--model sonnet`, `--model opus`) - Strumenti integrati (Read, Write, Bash, Grep e così via) - Permessi - Stato di Git - Nomi delle directory Un dettaglio importante: safe mode non disabilita le impostazioni gestite o di policy definite da un amministratore aziendale. Se lavori in un team in cui Bedrock GovCloud o una configurazione MDM imposta `availableModels`, tali restrizioni restano attive: safe mode disabilita solo le tue personalizzazioni, non le policy aziendali. ## Come isolare un livello e trovare il colpevole in 60 secondi?
Punto chiave Passaggio 1: esegui `claude --safe-mode` nella stessa cartella in cui si verificavano i problemi. Se funziona, il problema è nelle tue personalizzazioni; poi le riattivi una per una: `CLAUDE.md` -> hook -> MCP -> skill. Se non funziona neanche in safe mode, il problema riguarda l'autenticazione, la versione, la rete o il sistema operativo. In tal caso, esegui `claude doctor` per una diagnosi automatica, senza ricorrere a `rm -rf`.
Uno scenario diagnostico per quando Claude Code «ha smesso di ascoltare». La versione minima per tutti i comandi seguenti è **Claude Code v2.1.169**. Se la tua è più vecchia, aggiornala prima (`npm update -g @anthropic-ai/claude-code` o il programma di installazione nativo di Anthropic). 1. Apri la stessa cartella in cui si verificavano i problemi. 2. Esegui `claude --safe-mode`. 3. Se si avvia correttamente, verifica la richiesta originale. Ha funzionato? Allora la causa è in uno dei livelli. Vai al passaggio 4. 4. Se non funziona neanche in safe mode, non toccare le configurazioni. Esegui prima `claude doctor`; controlla l'autenticazione, la versione e le installazioni in conflitto. Quando safe mode si avvia correttamente, riattiva i livelli uno alla volta, cominciando dal più probabile responsabile. L'ordine basato sull'esperienza descritta: 1. **`CLAUDE.md`.** Esegui `claude` senza safe mode, ma rinomina temporaneamente il file: `mv CLAUDE.md CLAUDE.md.bak`. Se funziona, la causa è quel file. Puoi poi fare una ricerca binaria: mantieni metà delle righe e verifica. 2. **Hook.** Apri `.claude/settings.json` e imposta temporaneamente `[]` nella sezione `hooks`. Riavvia `claude`. Funziona? Allora la causa è uno degli hook. Riattivali uno alla volta. 3. **Server MCP.** Allo stesso modo, in `~/.claude.json` o `.claude/settings.json`, imposta temporaneamente la sezione `mcpServers` come oggetto vuoto, riavvia e controlla. 4. **Skill.** Sposta `.claude/skills/` in una cartella temporanea. Avvia e controlla. Cosa significa «rinominare temporaneamente»: durante la diagnosi i file non vengono eliminati. `mv` o `git stash` consentono di ripristinare tutto con un solo comando se quel livello non è la causa. ## Come cambiare la cartella di lavoro con `/cd` senza perdere il contesto?
Punto chiave Il comando `/cd ` in Claude Code 2.1.169+ cambia la cartella di lavoro nella sessione attiva senza perdere la cache dei prompt. È utile quando la configurazione del progetto corrente è danneggiata: puoi spostarti in una cartella pulita, verificare che Claude funzioni e tornare indietro. Prima dovevi chiudere la sessione e riavviarla.
Dal changelog della v2.1.169 dell'8 giugno:

Aggiunto il comando /cd per passare la sessione a una nuova cartella di lavoro senza reimpostare la cache dei prompt a sessione in corso.

— Registro delle modifiche di Anthropic Claude Code, https://code.claude.com/docs/en/changelog
Perché è utile quando si cerca di risolvere un problema. Supponi di trovarti nella cartella del progetto `~/work/myapp` e che Claude Code si comporti in modo strano. Prima, l'unico modo per verificare «funziona almeno?» era chiudere la sessione, spostarsi in un'altra cartella e ricominciare. Perdevi contesto, cronologia e cache dei prompt già riscaldata. Ora: ```bash # In the same session: /cd ~/sandbox/test ``` Claude passa alla nuova cartella e legge il suo `CLAUDE.md` (se presente) come messaggio, non come sostituzione del prompt di sistema: la cache viene quindi preservata. Se in `~/sandbox/test` funziona tutto, è chiaro che il problema era nella configurazione di `~/work/myapp`. Il 12 giugno, la v2.1.176 ha corretto una regressione fastidiosa: `/cd` mostrava il vecchio branch git fino a un riavvio completo. Se la tua versione è più vecchia, aggiornala oppure ignora semplicemente `git status` per i primi messaggi dopo il passaggio: si aggiornerà. ## Come configurare i modelli di fallback per un errore 529?
Punto chiave Nella v2.1.166, Anthropic ha aggiunto `fallbackModel`, una catena di fino a 3 modelli provati in sequenza quando il primario è sovraccarico o non disponibile. La catena si attiva solo in caso di sovraccarico e di errori del server non ritentabili. Gli errori di autorizzazione, fatturazione, limite di richieste e trasporto non attivano la catena di fallback: seguono la normale logica dei tentativi.
Nello scenario descritto, una volta a settimana un'attività lunga viene eseguita su Opus in un progetto; dopo 10 minuti, l'API restituisce 529 Overloaded e la sessione si arresta. Prima bisognava aspettare oppure passare manualmente a Sonnet con `--model sonnet`, perdendo tutto il contesto già riscaldato. In una cartella `business/` estesa con una configurazione second-brain, servono circa venti minuti di lavoro. Ora esiste un meccanismo apposito. La citazione esatta della documentazione ufficiale:

Quando il modello primario è sovraccarico, non disponibile o restituisce un altro errore del server non ritentabile, Claude Code può passare a un modello di fallback invece di fallire la richiesta. Gli errori di autorizzazione, fatturazione, limite di richieste, dimensione della richiesta e trasporto non attivano mai il passaggio: seguono il normale flusso di tentativi ed errori.

— Documentazione Anthropic - Configurazione del modello, https://code.claude.com/docs/en/model-config
E, separatamente, il funzionamento della catena:

Configura uno o più modelli di fallback e Claude Code li prova nell'ordine indicato, mostrando una notifica al momento del passaggio. Il cambio si applica solo al turno corrente: il messaggio successivo proverà di nuovo il modello primario. Dopo la deduplicazione, le catene sono limitate a tre modelli; le voci aggiuntive vengono ignorate.

— Documentazione Anthropic - Configurazione del modello, https://code.claude.com/docs/en/model-config
Due modi per configurarlo. Tramite CLI: ```bash claude --fallback-model sonnet,haiku ``` Tramite `~/.claude/settings.json`: ```json { "fallbackModel": ["claude-sonnet-4-6", "claude-haiku-4-5"] } ``` Una precisazione sui limiti di richieste. Anthropic non passa deliberatamente un errore 429 alla catena, così non è possibile aggirare il limite passando al modello successivo. Il fallback funziona solo quando il modello primario è sovraccarico, non disponibile o restituisce un errore del server non ritentabile (ad esempio, 529 Overloaded). Per i limiti di richieste si usano la normale logica dei tentativi e l'attesa progressiva. Un'altra precisazione: il 12 giugno, la v2.1.174 ha corretto una regressione: la compattazione non rispettava `--fallback-model`. Se hai una sessione lunga e viene compattata mentre il servizio è sovraccarico, prima di questa correzione il modello di fallback non veniva chiamato. Se lavori con sessioni lunghe (`/compact`, `/loop` durante la notte), aggiorna almeno alla v2.1.174. ## Cosa correggere se la causa è `CLAUDE.md`, un hook, MCP o una skill?
Punto chiave Quando safe mode individua il livello responsabile, la correzione varia a seconda del livello. Per `CLAUDE.md`, usa una ricerca binaria o riparti da un modello pronto all'uso sotto le 200 righe. Per un hook, controlla il codice di uscita (2 blocca, 1 no) e la logica. Per MCP, rimuovi un server e verifica. Per una skill, controlla che `SKILL.md` non contraddica `CLAUDE.md`.
Strategie specifiche per ogni livello. ### Se la causa è `CLAUDE.md` Apri il file e controllane la lunghezza. Sulla base dell'esperienza descritta, **mantieni il `CLAUDE.md` attivo entro un massimo di 200 righe**; sposta il resto in router e documenti di supporto accanto al progetto (la struttura completa second-brain è nella [guida al second brain](https://ailoot.ai/blog/it/claude-code-second-brain/)). Se supera le 400 righe, è quasi certamente la causa. Passaggi: 1. Crea un backup: `cp CLAUDE.md CLAUDE.md.full`. 2. Ripristina un modello breve e funzionante. Ne trovi uno pronto nella [guida «Come configurare CLAUDE.md»](https://ailoot.ai/blog/it/claude-md-template/). 3. Riavvia Claude Code. Verifica. 4. Se funziona, ripristina le regole in piccoli blocchi da 10–20 righe, verificando dopo ogni blocco. 5. Individua il blocco che altera il comportamento. Riscrivilo come hook con il codice di uscita corretto (i codici di uscita degli hook sono trattati nella sottosezione successiva di questo H2). ### Se la causa è un hook La domanda principale è se il codice di uscita è corretto. Gli hook di Claude Code usano: - **Exit 0** — tutto a posto; l'azione procede. - **Exit 1** — un errore, ma **non bloccante**. Claude continua come se nulla fosse. - **Exit 2** — un errore **bloccante**. Solo questo ferma davvero l'azione. Se hai scritto `sys.exit(1)` o `exit 1` in un hook shell pensando di bloccare, in Claude Code quel codice funziona come un avviso nel log e non ferma l'azione. Cambialo in `2`. Per i dettagli sugli hook e su come configurarli evitando questa insidia, consulta la [guida dedicata](https://ailoot.ai/blog/it/claude-code-hooks/). Il secondo caso comune è un hook che restituisce JSON non valido su stdout. Claude Code analizza la risposta dell'hook come JSON e, se contiene elementi estranei (un log, un indicatore di avanzamento, un'emoji), considera l'hook fallito e l'azione prosegue. Regola: **solo JSON su stdout; tutto il resto va su stderr**. Il terzo caso riguarda un hook che legge qualcosa da `~/.claude/` che safe mode ha nascosto. È uno scenario normale: invece di modificare l'hook, controlla `os.environ.get('CLAUDE_CODE_SAFE_MODE')` all'inizio e termina con 0. ### Se la causa è un server MCP Sintomi: i comandi MCP sono disponibili, ma restituiscono `failed` senza un traceback chiaro. Passaggi: 1. Esegui `claude mcp list`: quali server sono definiti? 2. Disabilita i server uno alla volta in `~/.claude.json`: rinomina la chiave `claude-server-A` in `_claude-server-A` (la disattiva senza eliminarla). 3. Riavvia `claude`. Verifica quali chiamate funzionano. 4. Una volta individuato il server responsabile, controllane il log: `claude mcp logs `. 5. Se è un server di terze parti (`@modelcontextprotocol/server-postgres` e simili), controlla se è disponibile una versione recente. L'ecosistema MCP è ancora in subbuglio: i server si rompono regolarmente con gli aggiornamenti di Claude Code. Se incontri «arresti all'avvio solo con due MCP», confronta il comportamento in safe mode, senza MCP. ### Se la causa è una skill Una skill è composta da `SKILL.md` e dal codice in `.claude/skills//`. Sintomi: Claude ignora la skill, la applica al momento sbagliato oppure la applica ma produce risultati scadenti. Passaggi: 1. Apri `SKILL.md`. Controlla la descrizione: **dovrebbe essere di 1–2 frasi e indicare nello specifico quando usarla**. Se dice «un assistente universale per ogni cosa», Claude non capisce quando attivarla. 2. Controlla che non ci siano contraddizioni con `CLAUDE.md`. Se `CLAUDE.md` dice «scrivi sempre test», ma la descrizione della skill dice «usala per prototipi rapidi senza test», c'è un conflitto. 3. Se la skill usa comandi esterni (npm, python, git), controlla che siano disponibili nel PATH di sistema. Una skill ha un proprio ambiente minimale. ## Cosa fare se safe mode non è servito: diagnosi e conservazione dello stato prima della riparazione
Punto chiave Se anche safe mode fallisce, le possibilità comprendono installazione, autorizzazione, rete e infrastruttura. Esegui `claude doctor` ed esaminane le prove. Un risultato inconcludente non giustifica l’eliminazione di impostazioni o sessioni: conserva e verifica prima lo stato completo, poi ripara soltanto l’installazione diagnosticata.
Rimuovere lo stato utente non è una scorciatoia diagnostica. Usa i controlli seguenti per individuare il guasto; se non sono conclusivi, conserva le prove e indaga ancora. Ogni riparazione inizia con un backup verificato e mantiene account e identità dell’archivio credenziali esistenti. Ordine: 1. **`claude doctor`** — diagnosi automatica. Anthropic scrive nella documentazione:

Se claude --version funziona, ma qualcos'altro non va, esegui claude doctor per generare un rapporto diagnostico automatico.

— Documentazione Anthropic - Risoluzione dei problemi di installazione, https://code.claude.com/docs/en/troubleshoot-install
2. **Controlla le installazioni in conflitto.** Molte persone hanno installato contemporaneamente una versione globale npm e il programma di installazione nativo:

Più installazioni di Claude Code possono causare discrepanze di versione o comportamenti imprevisti.

— Documentazione Anthropic - Risoluzione dei problemi di installazione, https://code.claude.com/docs/en/troubleshoot-install
3. **Controlla se `ANTHROPIC_API_KEY` sta intercettando la sessione OAuth.** È una causa comune di «non funziona niente, la chiave è scaduta»:

Quando `ANTHROPIC_API_KEY` è impostata e l'hai confermata, Claude Code usa quella chiave al posto delle credenziali OAuth dell'abbonamento.

— Documentazione Anthropic - Risoluzione dei problemi di installazione, https://code.claude.com/docs/en/troubleshoot-install
Soluzione: esegui `unset ANTHROPIC_API_KEY` nella sessione shell corrente oppure rimuovila da `~/.zshrc` / `~/.bashrc`. 4. **Ripara soltanto l’installazione identificata dalla diagnostica; conserva prima tutto lo stato utente.** Un guasto in safe mode o un rapporto doctor inconcludente non dimostrano che i dati utente vadano rimossi. Ferma tutte le sessioni Claude e gli altri processi che scrivono prima di eseguire un backup coerente. Mantieni stesso account Unix, HOME, archivio credenziali del sistema operativo e account Anthropic; non ruotare le chiavi né creare un’identità sostitutiva. L’esempio seguente è per **Linux con GNU tar**. Su macOS o Windows usa un backup che conservi ACL, attributi estesi, collegamenti e metadati della piattaforma e verificane il ripristino prima di procedere; non presumere che i flag GNU funzionino lì. L’archivio contiene credenziali e trascrizioni: mantienilo privato e fuori dai repository. ```bash # Run as the same user who owns the Claude state, after stopping writers. set -eu umask 077 backup_dir=$(mktemp -d "$HOME/.claude-recovery-XXXXXXXX") set -- if [ -e "$HOME/.claude" ] || [ -L "$HOME/.claude" ]; then set -- "$@" .claude fi if [ -e "$HOME/.claude.json" ] || [ -L "$HOME/.claude.json" ]; then set -- "$@" .claude.json fi [ "$#" -gt 0 ] || exit 1 tar --acls --xattrs --numeric-owner -cpf "$backup_dir/claude-state.tar" -C "$HOME" "$@" tar --acls --xattrs --compare -f "$backup_dir/claude-state.tar" -C "$HOME" sha256sum "$backup_dir/claude-state.tar" > "$backup_dir/claude-state.sha256" (cd "$backup_dir" && sha256sum -c claude-state.sha256) mkdir "$backup_dir/restore-check" tar --acls --xattrs -xpf "$backup_dir/claude-state.tar" -C "$backup_dir/restore-check" tar --acls --xattrs --compare -f "$backup_dir/claude-state.tar" -C "$backup_dir/restore-check" printf 'Verified recovery directory: %s\n' "$backup_dir" ``` Tutti i comandi devono riuscire. L’archivio comprende l’intero albero `.claude` esistente, incluse sessioni ignorate/non tracciate e stato dei plugin, più `.claude.json`: non soltanto impostazioni tracciate da Git. Se un percorso è un collegamento simbolico o i dati sono in una posizione configurata separatamente, fermati e includi la destinazione risolta nello stesso backup verificato; archiviare solo il collegamento non salva la destinazione. L’archivio non contiene Portachiavi macOS o altri archivi esterni: conserva quelle identità al loro posto. Se la diagnostica identifica proprio l’**installazione locale legacy** come copia in conflitto, sposta soltanto quella nella directory privata di recupero, senza eliminare configurazioni e sessioni: ```bash # Use the verified backup_dir from the previous block. if [ -d "$HOME/.claude/local" ]; then mv "$HOME/.claude/local" "$backup_dir/legacy-local" fi ``` Rimuovi un’installazione npm solo se la diagnostica la identifica come conflitto e intendi mantenere quella nativa. Usa poi l’[installer nativo documentato](https://code.claude.com/docs/en/setup) senza eliminare `.claude` o `.claude.json`: ```bash curl -fsSL https://claude.ai/install.sh | bash claude --version claude doctor ``` Su Windows il comando nativo resta: ```powershell irm https://claude.ai/install.ps1 | iex ``` **Ripristina separatamente.** Ferma di nuovo i processi che scrivono. Controlla il checksum ed estrai in una directory di recupero vuota come sopra; confronta con esito positivo prima di usare i file. Per ripristinare l’installazione legacy spostata, conferma prima l’assenza di `$HOME/.claude/local`, poi riporta `$backup_dir/legacy-local` in quel percorso esatto. Ripristina un file di impostazioni diagnosticato dall’estrazione verificata solo dopo aver conservato l’eventuale sostituto attuale; non sovrascrivere alla cieca l’intero albero. Sessioni, impostazioni MCP e identità originale restano conservate. Uno snapshot Git da solo non copre trascrizioni ignorate/non tracciate, credenziali o metadati del file system. ## Cosa NON fare quando Claude Code non funziona?
Punto chiave Sei anti-pattern emersi dai casi di assistenza descritti: cambiare le chiavi prima della diagnosi, eseguire subito un ripristino completo, farsi prendere dal panico per un errore UI in un hook, alzare il codice di uscita di un hook prima di correggerne la logica, modificare `CLAUDE.md` senza la protezione di safe mode e credere che «Claude ripari da solo il proprio MCP». Ognuno fa perdere ore e nessuno è necessario.
### Non cambiare le chiavi prima della diagnosi Nel 90% dei casi, «l'autorizzazione non funziona» è dovuto a `ANTHROPIC_API_KEY` che intercetta l'abbonamento, a un bug UI di un hook o a un MCP non funzionante. La rotazione delle chiavi non risolverà nulla di tutto questo, ma causerà un'altra ora di interruzione: bisogna revocare la vecchia chiave, emetterne una nuova, aggiornare la CI con la nuova chiave e modificare le variabili in produzione. Esegui prima `claude --safe-mode`. Funziona? Allora il problema è nelle personalizzazioni; non c'è bisogno di toccare le chiavi. ### Non eseguire un ripristino completo prima di safe mode Safe mode offre un ambiente isolato in 1 secondo. Eliminare `.claude` può distruggere sessioni, configurazione MCP e altro stato non tracciato. Esegui prima la diagnosi, verifica un backup privato e usa uno spostamento reversibile solo per il livello di installazione o configurazione effettivamente coinvolto. ### Non farti prendere dal panico per un errore UI in un hook Prima di correggere qualsiasi cosa, verifica se l'hook è stato effettivamente eseguito (tramite un log su `stderr` o una stampa esplicita), invece di affidarti all'indicatore visivo. ### Non alzare il codice di uscita di un hook prima di correggerne la logica Quando il tuo hook bloccante non blocca, viene spontaneo impostare `exit 2` e considerare il problema risolto. È una correzione funzionante, ma nasconde un altro problema: se il blocco non ha funzionato per un mese, allora è passato tutto ciò che l'hook avrebbe dovuto impedire. Prima controlla il log git e scopri esattamente cosa è sfuggito. Poi aggiungi il blocco. Altrimenti, chiudere il varco non annulla ciò che è successo prima. ### Non modificare il `CLAUDE.md` di produzione senza la protezione di safe mode Nel caso descritto: modifichi `CLAUDE.md`, Claude comincia a comportarsi in modo strano, esegui `git diff` e vedi che quella sera qualcuno ha aggiunto anche un server MCP e un hook al repository. Dai la colpa alla tua modifica, la annulli e Claude continua a comportarsi in modo strano. Regola: prima di `git revert`, esegui `claude --safe-mode`. Se il problema persiste in safe mode, la tua modifica non c'entra; non serve annullarla. ### Non credere che «Claude ripari da solo il proprio MCP» Uno scenario tipico: chiedi a Claude di «aggiungere un certo strumento al server MCP»; Claude riscrive la configurazione funzionante, si rompe tutto e poi Claude passa diversi turni a diagnosticare il danno che ha causato, consumando nel frattempo la quota della sessione. Quando MCP non funziona, **recupera manualmente la configurazione**; non lasciare che se ne occupi l'agente. Parte del suo arsenale di strumenti funziona anch'essa su MCP e, se MCP è guasto, anche chi diagnostica è compromesso. ## Dove andare dopo aver risolto il problema?
Punto chiave Una volta ripristinato Claude Code, aggiungi misure preventive per evitare che si rompa di nuovo. Come minimo: `disableBypassPermissionsMode: "disable"` nelle impostazioni utente, hook che bloccano `.env` e `git push --force` e una sandbox per le esecuzioni autonome lunghe. La guida sulla prevenzione è il suo complemento.
Dopo aver analizzato l'incidente, non riprendere subito il lavoro. Aggiungi prima misure preventive per evitare che si ripeta. Si possono perdere ore su un second brain (la cartella `business/` con la struttura del progetto) e su `CLAUDE.md`, e ripristinarli manualmente è difficile: è un motivo più che valido. Set minimo: 1. **`~/.claude/settings.json`** con `permissions.disableBypassPermissionsMode: "disable"`: un divieto architetturale della modalità bypass, così un `--dangerously-skip-permissions` avviato per errore semplicemente non funzionerà. 2. **Hook per `Read(./env*)`, `Bash(git push --force)`, `Write(./node_modules/**)`**: cose che vanno intercettate come una legge, non lasciate alla buona volontà. 3. **Configurazione della sandbox per le lunghe esecuzioni autonome** (`/loop`, `/schedule`). 4. **`/compact` con regole personalizzate** su cosa eliminare dal contesto, così Claude non si sovraccarica. Lo schema completo di protezione a quattro livelli è nella [guida «Come configurare Claude Code affinché non danneggi il tuo progetto durante la notte»](https://ailoot.ai/blog/it/claude-code-safe-overnight-setup/). Una guida tratta la prevenzione prima di avviare `/loop`; l'altra il ripristino dopo che `/loop` ha già danneggiato qualcosa. Una coppia logica.
### Fonti - [Registro delle modifiche di Anthropic Claude Code](https://code.claude.com/docs/en/changelog) - changelog ufficiale che descrive v2.1.166 (`fallbackModel`), v2.1.169 (safe mode, /cd), v2.1.174 (correzione della compattazione), v2.1.176 (correzione del branch git di /cd). - [Documentazione Anthropic - Configurazione del modello](https://code.claude.com/docs/en/model-config) - sezioni «Catene di modelli di fallback», «Verificare cosa ha attivato il fallback», «Impostazione del modello». - [Documentazione Anthropic - Risoluzione dei problemi di installazione e accesso](https://code.claude.com/docs/en/troubleshoot-install) - installazioni in conflitto, `claude doctor`, intercettazione di `ANTHROPIC_API_KEY`.
Materiali pratici: [documentazione Ailoot](https://ailoot.ai/docs/). Altri materiali e strumenti: [Ailoot](https://ailoot.ai/). ## Domande frequenti ### Un guasto in safe mode significa che devo eliminare ~/.claude? No. Restano da indagare installazione, autorizzazione, rete e infrastruttura. Un rapporto doctor inconcludente non dimostra che impostazioni o sessioni debbano essere rimosse. Ripara soltanto il livello diagnosticato. ### Cosa conservo prima di riparare l’installazione? Ferma i processi che scrivono e salva tutto lo stato Claude: sessioni, configurazioni plugin/MCP, file ignorati e metadati. Verifica checksum ed estrazione, mantieni account e archivio credenziali esistenti e ripristina solo il livello diagnosticato senza sovrascrivere alla cieca lo stato corrente. ## Ailoot · L’azienda e il suo portafoglio di progetti Ailoot si basa su un’esperienza operativa consolidata, un’ampia base di clienti, un servizio stabile e un controllo costante dei KPI. L’azienda e il suo portafoglio di progetti: milioni di clienti; vendite nell’ordine dei miliardi ogni mese. Ailoot mette questa esperienza operativa al servizio dell’accesso API alle funzioni AI nei prodotti dei clienti, negli agenti, nelle applicazioni e nelle automazioni.