Risoluzione dei problemi
Scopri le soluzioni ai problemi comuni con l’installazione e l’utilizzo di Claude Code.
Problemi comuni di installazione
Problemi di installazione Windows: errori in WSL
Potresti incontrare i seguenti problemi in WSL:
Problemi di rilevamento OS/piattaforma: Se ricevi un errore durante l’installazione, WSL potrebbe utilizzare npm
di Windows. Prova:
- Esegui
npm config set os linux
prima dell’installazione - Installa con
npm install -g @anthropic-ai/claude-code --force --no-os-check
(NON utilizzaresudo
)
Errori Node non trovato: Se vedi exec: node: not found
quando esegui claude
, il tuo ambiente WSL potrebbe utilizzare un’installazione Windows di Node.js. Puoi confermarlo con which npm
e which node
, che dovrebbero puntare a percorsi Linux che iniziano con /usr/
piuttosto che /mnt/c/
. Per risolvere questo, prova a installare Node tramite il gestore di pacchetti della tua distribuzione Linux o tramite nvm
.
Problemi di installazione Linux e Mac: errori di permessi o comando non trovato
Quando installi Claude Code con npm, i problemi di PATH
potrebbero impedire l’accesso a claude
.
Potresti anche incontrare errori di permessi se il tuo prefisso globale npm non è scrivibile dall’utente (es. /usr
, o /usr/local
).
Soluzione consigliata: Installazione nativa di Claude Code
Claude Code ha un’installazione nativa che non dipende da npm o Node.js.
L’installer nativo di Claude Code è attualmente in beta.
Utilizza il seguente comando per eseguire l’installer nativo.
macOS, Linux, WSL:
Windows PowerShell:
Questo comando installa la build appropriata di Claude Code per il tuo sistema operativo e architettura e aggiunge un collegamento simbolico all’installazione in ~/.local/bin/claude
.
Assicurati di avere la directory di installazione nel tuo PATH di sistema.
Soluzione alternativa: Migra all’installazione locale
In alternativa, se Claude Code funziona, puoi migrare a un’installazione locale:
Questo sposta Claude Code in ~/.claude/local/
e imposta un alias nella configurazione della tua shell. Non è richiesto sudo
per aggiornamenti futuri.
Dopo la migrazione, riavvia la tua shell, e poi verifica la tua installazione:
Su macOS/Linux/WSL:
Su Windows:
Verifica installazione:
Permessi e autenticazione
Richieste di permessi ripetute
Se ti trovi a dover approvare ripetutamente gli stessi comandi, puoi consentire a strumenti specifici
di funzionare senza approvazione utilizzando il comando /permissions
. Vedi Documentazione Permessi.
Problemi di autenticazione
Se stai riscontrando problemi di autenticazione:
- Esegui
/logout
per disconnetterti completamente - Chiudi Claude Code
- Riavvia con
claude
e completa nuovamente il processo di autenticazione
Se i problemi persistono, prova:
Questo rimuove le tue informazioni di autenticazione memorizzate e forza un login pulito.
Prestazioni e stabilità
Alto utilizzo di CPU o memoria
Claude Code è progettato per funzionare con la maggior parte degli ambienti di sviluppo, ma può consumare risorse significative quando elabora codebase di grandi dimensioni. Se stai riscontrando problemi di prestazioni:
- Usa
/compact
regolarmente per ridurre la dimensione del contesto - Chiudi e riavvia Claude Code tra attività importanti
- Considera di aggiungere grandi directory di build al tuo file
.gitignore
Il comando si blocca o si congela
Se Claude Code sembra non rispondere:
- Premi Ctrl+C per tentare di annullare l’operazione corrente
- Se non risponde, potresti dover chiudere il terminale e riavviare
Il tasto ESC non funziona nei terminali JetBrains (IntelliJ, PyCharm, ecc.)
Se stai utilizzando Claude Code nei terminali JetBrains e il tasto ESC non interrompe l’agente come previsto, questo è probabilmente dovuto a un conflitto di keybinding con le scorciatoie predefinite di JetBrains.
Per risolvere questo problema:
- Vai su Impostazioni → Strumenti → Terminale
- Clicca il collegamento ipertestuale “Configure terminal keybindings” accanto a “Override IDE Shortcuts”
- All’interno dei keybinding del terminale, scorri verso il basso fino a “Switch focus to Editor” ed elimina quella scorciatoia
Questo permetterà al tasto ESC di funzionare correttamente per annullare le operazioni di Claude Code invece di essere catturato dall’azione “Switch focus to Editor” di PyCharm.
Ottenere ulteriore aiuto
Se stai riscontrando problemi non coperti qui:
- Usa il comando
/bug
all’interno di Claude Code per segnalare problemi direttamente ad Anthropic - Controlla il repository GitHub per problemi noti
- Esegui
/doctor
per controllare la salute della tua installazione di Claude Code - Chiedi direttamente a Claude riguardo alle sue capacità e funzionalità - Claude ha accesso integrato alla sua documentazione