​
Problemi comuni di installazione

​
Problemi di permessi su Linux

Quando installi Claude Code con npm, potresti incontrare errori di permessi se il tuo prefisso globale npm non è scrivibile dall’utente (ad esempio /usr, o /usr/local).

​
Soluzione consigliata: Creare un prefisso npm scrivibile dall’utente

L’approccio più sicuro è configurare npm per utilizzare una directory all’interno della tua cartella home:

# Prima, salva un elenco dei tuoi pacchetti globali esistenti per la migrazione successiva
npm list -g --depth=0 > ~/npm-global-packages.txt

# Crea una directory per i tuoi pacchetti globali
mkdir -p ~/.npm-global

# Configura npm per utilizzare il nuovo percorso della directory
npm config set prefix ~/.npm-global

# Nota: Sostituisci ~/.bashrc con ~/.zshrc, ~/.profile, o altro file appropriato per la tua shell
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc

# Applica la nuova impostazione PATH
source ~/.bashrc

# Ora reinstalla Claude Code nella nuova posizione
npm install -g @anthropic-ai/claude-code

# Opzionale: Reinstalla i tuoi precedenti pacchetti globali nella nuova posizione
# Guarda ~/npm-global-packages.txt e installa i pacchetti che vuoi mantenere

Questa soluzione è consigliata perché:

  • Evita di modificare i permessi delle directory di sistema
  • Crea una posizione pulita e dedicata per i tuoi pacchetti npm globali
  • Segue le migliori pratiche di sicurezza

​
Recupero del sistema: Se hai eseguito comandi che cambiano proprietà e permessi di file di sistema o simili

Se hai già eseguito un comando che ha cambiato i permessi delle directory di sistema (come sudo chown -R $USER:$(id -gn) /usr && sudo chmod -R u+w /usr) e il tuo sistema è ora danneggiato (ad esempio, se vedi sudo: /usr/bin/sudo must be owned by uid 0 and have the setuid bit set), dovrai eseguire passaggi di recupero.

Metodo di recupero Ubuntu/Debian:

  1. Durante il riavvio, tieni premuto SHIFT per accedere al menu GRUB

  2. Seleziona “Opzioni avanzate per Ubuntu/Debian”

  3. Scegli l’opzione modalità di recupero

  4. Seleziona “Passa al prompt della shell root”

  5. Rimonta il filesystem come scrivibile:

    mount -o remount,rw /

  6. Correggi i permessi:

    # Ripristina la proprietà root
chown -R root:root /usr
chmod -R 755 /usr

# Assicurati che /usr/local sia di proprietà del tuo utente per i pacchetti npm
chown -R TUO_NOME_UTENTE:TUO_NOME_UTENTE /usr/local

# Imposta il bit setuid per i binari critici
chmod u+s /usr/bin/sudo
chmod 4755 /usr/bin/sudo
chmod u+s /usr/bin/su
chmod u+s /usr/bin/passwd
chmod u+s /usr/bin/newgrp
chmod u+s /usr/bin/gpasswd
chmod u+s /usr/bin/chsh
chmod u+s /usr/bin/chfn

# Correggi la configurazione sudo
chown root:root /usr/libexec/sudo/sudoers.so
chmod 4755 /usr/libexec/sudo/sudoers.so
chown root:root /etc/sudo.conf
chmod 644 /etc/sudo.conf

  7. Reinstalla i pacchetti interessati (opzionale ma consigliato):

    # Salva l'elenco dei pacchetti installati
dpkg --get-selections > /tmp/installed_packages.txt

# Reinstallali
awk '{print $1}' /tmp/installed_packages.txt | xargs -r apt-get install --reinstall -y

  8. Riavvia:

    reboot
Metodo alternativo di recupero con USB live:

Se la modalità di recupero non funziona, puoi utilizzare una USB live:

  1. Avvia da una USB live (Ubuntu, Debian, o qualsiasi distribuzione Linux)

  2. Trova la tua partizione di sistema:

    lsblk

  3. Monta la tua partizione di sistema:

    sudo mount /dev/sdXY /mnt  # sostituisci sdXY con la tua partizione di sistema effettiva

  4. Se hai una partizione boot separata, montala anche:

    sudo mount /dev/sdXZ /mnt/boot  # se necessario

  5. Esegui chroot nel tuo sistema:

    # Per Ubuntu/Debian:
sudo chroot /mnt

# Per sistemi basati su Arch:
sudo arch-chroot /mnt

  6. Segui i passaggi 6-8 dal metodo di recupero Ubuntu/Debian sopra

Dopo aver ripristinato il tuo sistema, segui la soluzione consigliata sopra per impostare un prefisso npm scrivibile dall’utente.

​
Problemi dell’aggiornamento automatico

Se Claude Code non può aggiornarsi automaticamente, potrebbe essere dovuto a problemi di permessi con la directory del prefisso globale npm. Segui la soluzione consigliata sopra per risolvere questo problema.

Se preferisci disabilitare l’aggiornamento automatico invece, puoi impostare la variabile d’ambiente DISABLE_AUTOUPDATER a 1

​
Permessi e autenticazione

​
Richieste di permesso 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 sui permessi.

​
Problemi di autenticazione

Se stai riscontrando problemi di autenticazione:

  1. Esegui /logout per disconnetterti completamente
  2. Chiudi Claude Code
  3. Riavvia con claude e completa nuovamente il processo di autenticazione

Se i problemi persistono, prova:

rm -rf ~/.config/claude-code/auth.json
claude

Questo rimuove le tue informazioni di autenticazione memorizzate e forza un login pulito.

​
Prestazioni e stabilità

​
Utilizzo elevato 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:

  1. Usa /compact regolarmente per ridurre la dimensione del contesto
  2. Chiudi e riavvia Claude Code tra compiti importanti
  3. Considera di aggiungere grandi directory di build al tuo file .gitignore

​
Il comando si blocca o si congela

Se Claude Code sembra non rispondere:

  1. Premi Ctrl+C per tentare di annullare l’operazione corrente
  2. 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:

  1. Vai a Impostazioni → Strumenti → Terminale
  2. Clicca il collegamento ipertestuale “Configura keybinding del terminale” accanto a “Sovrascrivi scorciatoie IDE”
  3. All’interno dei keybinding del terminale, scorri verso il basso fino a “Sposta focus all’Editor” e cancella quella scorciatoia

Questo permetterà al tasto ESC di funzionare correttamente per annullare le operazioni di Claude Code invece di essere catturato dall’azione “Sposta focus all’Editor” di PyCharm.

​
Ottenere ulteriore aiuto

Se stai riscontrando problemi non coperti qui:

  1. Usa il comando /bug all’interno di Claude Code per segnalare problemi direttamente ad Anthropic
  2. Controlla il repository GitHub per problemi noti
  3. Esegui /doctor per controllare lo stato della tua installazione di Claude Code