Risoluzione dei problemi

​

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.

Conflitti di versione nvm: Se hai nvm installato sia in WSL che in Windows, potresti sperimentare 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
• Sperimentando 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"

​

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

Quando installi Claude Code con npm, problemi di PATH potrebbero impedire l’accesso a claude. Potresti anche incontrare errori di permesso 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.

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.

​

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 permesso ripetute

Se ti trovi a approvare ripetutamente gli stessi comandi, puoi permettere a strumenti specifici di funzionare senza approvazione usando il comando /permissions. Vedi Documentazione Permessi.

​

Problemi di autenticazione

Se stai sperimentando 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 grandi. Se stai sperimentando 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 cancellare 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 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 Impostazioni → Strumenti → Terminale
2. Clicca il collegamento ipertestuale “Configura keybinding terminale” accanto a “Sovrascrivi scorciatoie IDE”
3. All’interno dei keybinding del terminale, scorri verso il basso fino a “Cambia focus all’Editor” e cancella quella scorciatoia

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

​

Problemi di ricerca e scoperta

Se lo strumento di Ricerca, 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 corrispondenze inferiori al previsto (ma non una completa mancanza di funzionalità di ricerca) quando si usa Claude Code su WSL.

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 progetto al filesystem Linux: Se possibile, assicurati che il tuo progetto sia localizzato sul filesystem Linux (/home/) piuttosto che sul 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 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 di hook di 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 del 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 sperimentando 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 le sue capacità e funzionalità - Claude ha accesso integrato alla sua documentazione