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 di 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 tuo file di configurazione della 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 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 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 esempio, /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. Usa il seguente comando per eseguire il programma di installazione 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 (o %USERPROFILE%\.local\bin\claude.exe su Windows).
Assicurati di avere la directory di installazione nel tuo PATH di sistema.

​
Windows: “Claude Code su Windows richiede git-bash”

Claude Code su Windows nativo richiede Git for Windows che include Git Bash. Se Git è installato ma non rilevato:
  1. Imposta il percorso esplicitamente in PowerShell prima di eseguire Claude: 
    $env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"
  2. Oppure aggiungilo alle tue variabili di ambiente di sistema in modo permanente tramite Proprietà del sistema → Variabili di ambiente.
Se Git è installato in una posizione non standard, regola il percorso di conseguenza.

​
Windows: “installMethod è native, ma il comando claude non trovato”

Se vedi questo errore dopo l’installazione, il comando claude non è nel tuo PATH. Aggiungilo manualmente:
1

Apri Variabili di ambiente

Premi Win + R, digita sysdm.cpl e premi Invio. Fai clic su Avanzate → Variabili di ambiente.
2

Modifica il PATH dell'utente

Sotto “Variabili utente”, seleziona Path e fai clic su Modifica. Fai clic su Nuovo e aggiungi:
%USERPROFILE%\.local\bin
3

Riavvia il tuo terminale

Chiudi e riapri PowerShell o CMD affinché le modifiche abbiano effetto.
Verifica l’installazione: 
claude doctor # Check installation health

​
Permessi e autenticazione

​
Prompt di permesso ripetuti

Se ti trovi a dover approvare ripetutamente gli stessi comandi, puoi consentire a strumenti specifici di eseguirsi 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 di nuovo il processo di autenticazione
Se i problemi persistono, prova: 
rm -rf ~/.config/claude-code/auth.json
claude
Questo rimuove le tue informazioni di autenticazione archiviate e forza un accesso pulito.

​
Posizioni dei file di configurazione

Claude Code archivia la configurazione in diverse posizioni:
FileScopo
~/.claude/settings.jsonImpostazioni utente (permessi, hook, override del modello)
.claude/settings.jsonImpostazioni del progetto (controllate nel controllo del codice sorgente)
.claude/settings.local.jsonImpostazioni del progetto locale (non sottoposte a commit)
~/.claude.jsonStato globale (tema, OAuth, server MCP, strumenti consentiti)
.mcp.jsonServer MCP del progetto (controllati nel controllo del codice sorgente)
managed-settings.jsonImpostazioni gestite
managed-mcp.jsonServer MCP gestiti
Su Windows, ~ si riferisce alla tua directory home dell’utente, come C:\Users\YourName. Posizioni dei file gestiti:
  • macOS: /Library/Application Support/ClaudeCode/
  • Linux/WSL: /etc/claude-code/
  • Windows: C:\Program Files\ClaudeCode\
Per i dettagli sulla configurazione di questi file, vedi Impostazioni e MCP.

​
Ripristino della configurazione

Per ripristinare Claude Code alle impostazioni predefinite, puoi rimuovere i file di configurazione: 
# Reset all user settings and state
rm ~/.claude.json
rm -rf ~/.claude/

# Reset project-specific settings
rm -rf .claude/
rm .mcp.json
Questo rimuoverà tutte le tue impostazioni, strumenti consentiti, configurazioni del server MCP e cronologia della sessione.

​
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

​
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, potrebbe essere necessario chiudere il terminale e riavviare

​
Problemi di ricerca e scoperta

Se lo strumento di ricerca, 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 si lavora tra file system su WSL potrebbero risultare in meno corrispondenze del previsto (ma non una completa mancanza di funzionalità di ricerca) quando si utilizza Claude Code su WSL.
/doctor mostrerà la ricerca come OK in questo caso.
Soluzioni:
  1. Invia ricerche più specifiche: Riduci il numero di file cercati specificando directory o tipi di file: “Cerca la logica di convalida JWT nel pacchetto auth-service” o “Trova l’uso dell’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: Considera di eseguire Claude Code nativamente su Windows invece che tramite WSL, per migliori prestazioni del file system.

​
Problemi di integrazione dell’IDE

​
IDE JetBrains non rilevato su WSL2

Se stai utilizzando Claude Code su WSL2 con IDE JetBrains e ricevi errori “Nessun IDE disponibile rilevato”, questo è probabilmente dovuto alla configurazione di rete di WSL2 o al firewall di Windows 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 il firewall di Windows (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 del 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 di JetBrains, vedi la nostra guida IDE JetBrains.

​
Segnalazione di problemi di integrazione dell’IDE su Windows (sia nativo che WSL)

Se stai riscontrando problemi di integrazione dell’IDE su Windows, crea un problema con le seguenti informazioni:
  • Tipo di ambiente: Windows nativo (Git Bash) o WSL1/WSL2
  • Modalità di rete WSL (se applicabile): NAT o mirroring
  • Nome e versione dell’IDE
  • Versione dell’estensione/plugin di Claude Code
  • Tipo di shell: Bash, Zsh, PowerShell, ecc.

​
Il tasto Escape non funziona nei terminali di JetBrains (IntelliJ, PyCharm, ecc.)

Se stai utilizzando Claude Code nei terminali di JetBrains e il tasto Esc non interrompe l’agente come previsto, questo è probabilmente dovuto a uno scontro di keybinding con i tasti di scelta rapida predefiniti di JetBrains. Per risolvere questo problema:
  1. Vai a Impostazioni → Strumenti → Terminale
  2. Oppure:
    • Deseleziona “Sposta il focus nell’editor con Escape”, oppure
    • Fai clic su “Configura keybinding del terminale” e elimina il tasto di scelta rapida “Cambia focus nell’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 recinti di codice, il che può influire sull’evidenziazione della sintassi e sulla leggibilità in GitHub, editor e strumenti di documentazione.

​
Tag di linguaggio mancanti nei blocchi di codice

Se noti blocchi di codice come questo nei markdown generati: 
```
function example() {
  return "hello";
}
```
Invece di blocchi correttamente etichettati come: 
```javascript
function example() {
  return "hello";
}
```
Soluzioni:
  1. Chiedi a Claude di aggiungere tag di linguaggio: Richiedi “Aggiungi tag di linguaggio appropriati a tutti i blocchi di codice in questo file markdown.”
  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 “Correggi i problemi di spaziatura e formattazione in questo file markdown.”
  2. Usa strumenti di formattazione: Configura hook per eseguire formattatori markdown come prettier o script di formattazione personalizzati su file markdown generati.
  3. Specifica le preferenze di formattazione: Includi i requisiti di formattazione nei tuoi prompt o nei file di memoria del progetto.

​
Best practice per la generazione di markdown

Per minimizzare i problemi di formattazione:
  • Sii esplicito nelle richieste: Chiedi “markdown correttamente formattato con blocchi di codice etichettati con linguaggio”
  • 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