​
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 usare 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.

Conflitti di versione nvm: Se hai nvm installato sia in WSL che in Windows, potresti riscontrare conflitti di versione quando cambi versioni Node in WSL. Questo accade perché WSL importa il PATH di Windows per impostazione predefinita, causando che nvm/npm di Windows abbiano priorità sull’installazione WSL.

Puoi identificare questo problema:

  • Eseguendo which npm e which node - se puntano a percorsi Windows (che iniziano con /mnt/c/), vengono utilizzate le versioni Windows
  • Riscontrando funzionalità interrotte dopo aver cambiato versioni Node con nvm in WSL

Per risolvere questo problema, correggi il tuo PATH Linux per assicurarti che le versioni Linux node/npm abbiano priorità:

Soluzione principale: Assicurati che nvm sia caricato correttamente nella tua shell

La causa più comune è che nvm non è caricato nelle shell non interattive. Aggiungi quanto segue al tuo file di configurazione shell (~/.bashrc, ~/.zshrc, ecc.):

# Carica nvm se esiste
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

O esegui direttamente nella tua sessione corrente:

source ~/.nvm/nvm.sh

Alternativa: Regola l’ordine PATH

Se nvm è caricato correttamente ma i percorsi Windows hanno ancora priorità, puoi anteporre esplicitamente i tuoi percorsi Linux al PATH nella configurazione della tua shell:

export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"

Evita di disabilitare l’importazione PATH di Windows (appendWindowsPath = false) poiché questo interrompe la capacità di chiamare facilmente eseguibili Windows da WSL. Allo stesso modo, evita di disinstallare Node.js da Windows se lo usi per lo sviluppo Windows.

​
Problemi di installazione Linux e Mac: errori di permessi o comando non trovato

Quando installi Claude Code con npm, 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 raccomandata: 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.

Usa 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 symlink all’installazione in ~/.local/bin/claude.

Assicurati di avere la directory di installazione nel tuo PATH di sistema.

​
Soluzione alternativa: Migra a 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 ad approvare ripetutamente gli stessi comandi, puoi permettere a strumenti specifici di eseguire senza approvazione usando 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 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

​
Problemi di ricerca e scoperta

Se lo strumento Search, le menzioni @file, gli agenti personalizzati e i comandi slash personalizzati non funzionano, installa ripgrep di sistema:

# macOS (Homebrew)  
brew install ripgrep

# Windows (winget)
winget install BurntSushi.ripgrep.MSVC

# Ubuntu/Debian
sudo apt install ripgrep

# Alpine Linux
apk add ripgrep

# Arch Linux
pacman -S ripgrep

Poi imposta USE_BUILTIN_RIPGREP=0 nel tuo ambiente.

​
Risultati di ricerca lenti o incompleti su WSL

Le penalità di prestazioni di lettura disco quando si lavora attraverso file system su WSL possono risultare in meno corrispondenze del previsto (ma non una completa mancanza di funzionalità di ricerca) quando si usa Claude Code su WSL.

/doctor mostrerà Search come OK in questo caso.

Soluzioni:

  1. Invia ricerche più specifiche: Riduci il numero di file cercati specificando directory o tipi di file: “Cerca logica di validazione JWT nel pacchetto auth-service” o “Trova uso di hash md5 nei file JS”.

  2. Sposta il progetto nel filesystem Linux: Se possibile, assicurati che il tuo progetto sia situato nel filesystem Linux (/home/) piuttosto che nel filesystem Windows (/mnt/c/).

  3. Usa Windows nativo invece: Considera di eseguire Claude Code nativamente su Windows invece che attraverso WSL, per migliori prestazioni del file system.

​
Problemi di integrazione IDE

​
IDE JetBrains non rilevato su WSL2

Se stai usando Claude Code su WSL2 con IDE JetBrains e ricevi errori “No available IDEs detected”, questo è probabilmente dovuto alla configurazione di rete di WSL2 o al Windows Firewall che blocca la connessione.

​
Modalità di rete WSL2

WSL2 usa la rete NAT per impostazione predefinita, che può impedire il rilevamento IDE. Hai due opzioni:

Opzione 1: Configura Windows Firewall (raccomandato)

  1. Trova il tuo indirizzo IP WSL2:

    wsl hostname -I
# Esempio output: 172.21.123.456

  2. Apri PowerShell come Amministratore e crea una regola firewall:

    New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16

    (Regola il range IP basato sulla tua subnet WSL2 dal passo 1)

  3. Riavvia sia il tuo IDE che Claude Code

Opzione 2: Passa alla rete mirrored

Aggiungi a .wslconfig nella tua directory utente Windows:

[wsl2]
networkingMode=mirrored

Poi riavvia WSL con wsl --shutdown da PowerShell.

Questi problemi di rete interessano solo WSL2. WSL1 usa direttamente la rete dell’host e non richiede queste configurazioni.

Per ulteriori suggerimenti di configurazione JetBrains, vedi la nostra guida integrazione IDE.

​
Segnalazione problemi integrazione IDE Windows (sia nativo che WSL)

Se stai riscontrando problemi di integrazione IDE su Windows, per favore crea un issue con le seguenti informazioni: se sei nativo (git bash), o WSL1/WSL2, modalità di rete WSL (NAT o mirrored), nome/versione IDE, versione estensione/plugin Claude Code, e tipo di shell (bash/zsh/ecc)

​
Tasto ESC non funziona nei terminali JetBrains (IntelliJ, PyCharm, ecc.)

Se stai usando 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 Settings → Tools → Terminal
  2. O:
    • Deseleziona “Move focus to the editor with Escape”, o
    • Clicca “Configure terminal keybindings” e cancella la scorciatoia “Switch focus to Editor”
  3. Applica le modifiche

Questo permette al tasto ESC di interrompere correttamente le operazioni di Claude Code.

​
Problemi di formattazione Markdown

Claude Code a volte genera file markdown con tag linguaggio mancanti sui code fence, che possono influenzare l’evidenziazione della sintassi e la leggibilità in GitHub, editor e strumenti di documentazione.

​
Tag linguaggio mancanti nei blocchi di codice

Se noti blocchi di codice come questo nel markdown generato:

```
function example() {
  return "hello";
}
```

Invece di blocchi correttamente taggati come:

```javascript
function example() {
  return "hello";
}
```

Soluzioni:

  1. Chiedi a Claude di aggiungere tag linguaggio: Semplicemente richiedi “Per favore aggiungi tag linguaggio appropriati a tutti i blocchi di codice in questo file markdown.”

  2. Usa hook di post-elaborazione: Imposta hook di formattazione automatica per rilevare e aggiungere tag linguaggio mancanti. Vedi l’esempio hook formattazione markdown per dettagli di implementazione.

  3. Verifica manuale: Dopo aver generato file markdown, rivedili per la corretta formattazione dei blocchi di codice e richiedi correzioni se necessario.

​
Spaziatura e formattazione inconsistenti

Se il markdown generato ha righe vuote eccessive o spaziatura inconsistente:

Soluzioni:

  1. Richiedi correzioni di formattazione: Chiedi a Claude di “Correggere problemi di spaziatura e formattazione in questo file markdown.”

  2. Usa strumenti di formattazione: Imposta hook per eseguire formattatori markdown come prettier o script di formattazione personalizzati sui file markdown generati.

  3. Specifica preferenze di formattazione: Includi requisiti di formattazione nei tuoi prompt o file di memoria del progetto.

​
Migliori pratiche per la generazione markdown

Per minimizzare problemi di formattazione:

  • Sii esplicito nelle richieste: Chiedi “markdown correttamente formattato con blocchi di codice taggati per linguaggio”
  • Usa convenzioni di progetto: Documenta il tuo stile markdown preferito in CLAUDE.md
  • Imposta hook di validazione: Usa hook di post-elaborazione per verificare automaticamente e correggere problemi di formattazione comuni

​
Ottenere più 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 Claude Code
  4. Chiedi direttamente a Claude riguardo alle sue capacità e funzionalità - Claude ha accesso integrato alla sua documentazione