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 utilizzare sudo)

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:

# Installa versione stabile (predefinita)
curl -fsSL https://claude.ai/install.sh | bash

# Installa ultima versione
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Installa numero di versione specifico
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

Windows PowerShell:

# Installa versione stabile (predefinita)
irm https://claude.ai/install.ps1 | iex

# Installa ultima versione
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest

# Installa numero di versione specifico
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

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:

claude migrate-installer

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:

which claude  # Dovrebbe mostrare un alias a ~/.claude/local/claude

Su Windows:

where claude  # Dovrebbe mostrare il percorso all'eseguibile claude

Verifica installazione:

claude doctor # Controlla la salute dell'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:

  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à

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:

  1. Usa /compact regolarmente per ridurre la dimensione del contesto
  2. Chiudi e riavvia Claude Code tra attività 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 su Impostazioni → Strumenti → Terminale
  2. Clicca il collegamento ipertestuale “Configure terminal keybindings” accanto a “Override IDE Shortcuts”
  3. 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:

  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 la salute della tua installazione di Claude Code
  4. Chiedi direttamente a Claude riguardo alle sue capacità e funzionalità - Claude ha accesso integrato alla sua documentazione