Vai al contenuto principale

​
Problemi comuni di installazione

​
Problemi di installazione su Windows: errori in WSL

Potresti incontrare i seguenti problemi in WSL: Problemi di rilevamento del sistema operativo/piattaforma: Se ricevi un errore durante l’installazione, WSL potrebbe stare utilizzando 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 di Node non trovato: Se vedi exec: node: not found quando esegui claude, il tuo ambiente WSL potrebbe stare utilizzando un’installazione di Node.js di Windows. 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 di Node in WSL. Questo accade perché WSL importa il PATH di Windows per impostazione predefinita, causando a nvm/npm di Windows di avere priorità rispetto all’installazione WSL. Puoi identificare questo problema da:
  • Eseguire which npm e which node - se puntano a percorsi Windows (che iniziano con /mnt/c/), le versioni di Windows vengono utilizzate
  • Riscontrare funzionalità interrotta dopo aver cambiato versioni di Node con nvm in WSL
Per risolvere questo problema, correggi il tuo PATH Linux per assicurarti che le versioni Linux di node/npm abbiano priorità: Soluzione principale: Assicurati che nvm sia caricato correttamente nella tua shell La causa più comune è che nvm non viene caricato in shell non interattive. Aggiungi quanto segue al file di configurazione della tua shell (~/.bashrc, ~/.zshrc, ecc.): 
# Load nvm if it exists
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"
Oppure esegui direttamente nella tua sessione corrente: 
source ~/.nvm/nvm.sh
Alternativa: Regola l’ordine del PATH Se nvm è caricato correttamente ma i percorsi di Windows hanno ancora priorità, puoi esplicitamente anteporre i tuoi percorsi Linux a PATH nella configurazione della tua shell: 
export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"
Evita di disabilitare l’importazione del PATH di Windows (appendWindowsPath = false) poiché questo interrompe la capacità di chiamare facilmente eseguibili di Windows da WSL. Allo stesso modo, evita di disinstallare Node.js da Windows se lo usi per lo sviluppo di Windows.

​
Problemi di installazione su Linux e Mac: errori di permesso 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 permesso se il tuo prefisso globale npm non è scrivibile dall’utente (ad 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.
Usa il seguente comando per eseguire l’installer nativo. macOS, Linux, WSL: 
# Install stable version (default)
curl -fsSL https://claude.ai/install.sh | bash

# Install latest version
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Install specific version number
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58
Windows PowerShell: 
# Install stable version (default)
irm https://claude.ai/install.ps1 | iex

# Install latest version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest

# Install specific version number
& ([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 un’installazione locale

In alternativa, se Claude Code è in esecuzione, puoi migrare a un’installazione locale: 
claude migrate-installer
Questo sposta Claude Code in ~/.claude/local/ e configura un alias nella configurazione della tua shell. Non è richiesto sudo per gli aggiornamenti futuri. Dopo la migrazione, riavvia la tua shell, quindi verifica la tua installazione: Su macOS/Linux/WSL: 
which claude  # Should show an alias to ~/.claude/local/claude
Su Windows: 
where claude  # Should show path to claude executable
Verifica l’installazione: 
claude doctor # Check installation health

​
Permessi e autenticazione

​
Richieste di permesso ripetute

Se ti trovi a dover approvare ripetutamente gli stessi comandi, puoi consentire a strumenti specifici di essere eseguiti 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 il processo di autenticazione di nuovo
Se i problemi persistono, prova: 
rm -rf ~/.config/claude-code/auth.json
claude
Questo rimuove le tue informazioni di autenticazione archiviate 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 potrebbe consumare risorse significative durante l’elaborazione di grandi basi di codice. Se stai riscontrando problemi di prestazioni:
  1. Usa /compact regolarmente per ridurre la dimensione del contesto
  2. Chiudi e riavvia Claude Code tra i compiti principali
  3. Considera di aggiungere grandi directory di build al tuo file .gitignore

​
I comandi si bloccano o si congelano

Se Claude Code sembra non rispondere:
  1. Premi Ctrl+C per tentare di annullare l’operazione corrente
  2. Se non risponde, potrebbe essere necessario 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 il sistema ripgrep: 
# 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
Quindi imposta USE_BUILTIN_RIPGREP=0 nel tuo ambiente.

​
Risultati di ricerca lenti o incompleti su WSL

Le penalità di prestazioni di lettura del disco quando lavori tra file system su WSL potrebbero risultare in meno corrispondenze del previsto (ma non una completa mancanza di funzionalità di ricerca) quando usi 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 convalida JWT nel pacchetto auth-service” o “Trova l’uso di hash md5 nei file JS”.
  2. Sposta il progetto nel file system Linux: Se possibile, assicurati che il tuo progetto si trovi nel file system Linux (/home/) piuttosto che nel file system Windows (/mnt/c/).
  3. Usa Windows nativo invece: Considera di eseguire Claude Code nativamente su Windows invece che tramite WSL, per migliori prestazioni del file system.

​
Problemi di integrazione IDE

​
IDE JetBrains non rilevato su WSL2

Se stai utilizzando 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 utilizza la rete NAT per impostazione predefinita, che può impedire il rilevamento dell’IDE. Hai due opzioni: Opzione 1: Configura Windows Firewall (consigliato)
  1. Trova il tuo indirizzo IP WSL2: 
    wsl hostname -I
# Example 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 l’intervallo di IP in base alla tua subnet WSL2 dal passaggio 1)
  3. Riavvia sia il tuo IDE che Claude Code
Opzione 2: Passa alla rete con mirroring Aggiungi a .wslconfig nella tua directory utente Windows: 
[wsl2]
networkingMode=mirrored
Quindi riavvia WSL con wsl --shutdown da PowerShell.
Questi problemi di rete interessano solo WSL2. WSL1 utilizza direttamente la rete dell’host e non richiede queste configurazioni.
Per ulteriori suggerimenti di configurazione JetBrains, vedi la nostra guida di integrazione IDE.

​
Segnalazione di problemi di integrazione IDE su 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 dell’estensione/plugin Claude Code, e tipo di shell (bash/zsh/ecc)

​
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 uno scontro di keybinding con i scorciatoie predefinite di JetBrains. Per risolvere questo problema:
  1. Vai a Settings → Tools → Terminal
  2. Uno tra:
    • Deseleziona “Move focus to the editor with Escape”, oppure
    • Fai clic su “Configure terminal keybindings” e elimina il scorciatoia “Switch focus to Editor”
  3. Applica le modifiche
Questo consente al tasto ESC di interrompere correttamente le operazioni di Claude Code.

​
Problemi di formattazione Markdown

Claude Code a volte genera file markdown con tag di linguaggio mancanti sui fence di codice, il che può influire sull’evidenziazione della sintassi e la leggibilità in GitHub, editor e strumenti di documentazione.

​
Tag di 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 di linguaggio: Semplicemente richiedi “Please add appropriate language tags to all code blocks in this markdown file.”
  2. Usa hook di post-elaborazione: Configura hook di formattazione automatica per rilevare e aggiungere tag di linguaggio mancanti. Vedi l’esempio di hook di formattazione markdown per i dettagli di implementazione.
  3. Verifica manuale: Dopo aver generato file markdown, esamina la formattazione corretta dei blocchi di codice e richiedi correzioni se necessario.

​
Spaziatura e formattazione incoerenti

Se il markdown generato ha righe vuote eccessive o spaziatura incoerente: Soluzioni:
  1. Richiedi correzioni di formattazione: Chiedi a Claude di “Fix spacing and formatting issues in this markdown file.”
  2. Usa strumenti di formattazione: Configura hook per eseguire formattatori markdown come prettier o script di formattazione personalizzati su file markdown generati.
  3. Specifica preferenze di formattazione: Includi requisiti di formattazione nei tuoi prompt o nei file memory del progetto.

​
Best practice per la generazione di markdown

Per minimizzare i problemi di formattazione:
  • Sii esplicito nelle richieste: Chiedi “properly formatted markdown with language-tagged code blocks”
  • Usa convenzioni di progetto: Documenta il tuo stile markdown preferito in CLAUDE.md
  • Configura hook di convalida: Usa hook di post-elaborazione per verificare e correggere automaticamente i problemi di formattazione comuni

​
Ottenere più aiuto

Se stai riscontrando problemi non trattati qui:
  1. Usa il comando /bug all’interno di Claude Code per segnalare i problemi direttamente ad Anthropic
  2. Controlla il repository GitHub per i problemi noti
  3. Esegui /doctor per verificare lo stato di salute della tua installazione di Claude Code
  4. Chiedi direttamente a Claude sulle sue capacità e funzionalità - Claude ha accesso integrato alla sua documentazione