Vai al contenuto principale

​
Risolvi i problemi di installazione

Se preferisci evitare completamente il terminale, l’app Claude Code Desktop ti consente di installare e utilizzare Claude Code tramite un’interfaccia grafica. Scaricala per macOS o Windows e inizia a programmare senza alcuna configurazione da riga di comando.
Trova il messaggio di errore o il sintomo che stai vedendo:
Cosa vediSoluzione
command not found: claude o 'claude' is not recognizedCorreggi il tuo PATH
syntax error near unexpected token '<'Lo script di installazione restituisce HTML
curl: (56) Failure writing output to destinationScarica lo script prima, poi eseguilo
Killed durante l’installazione su LinuxAggiungi spazio di swap per server con poca memoria
TLS connect error o SSL/TLS secure channelAggiorna i certificati CA
Failed to fetch version o impossibile raggiungere il server di downloadControlla la connettività di rete e le impostazioni proxy
irm is not recognized o && is not validUsa il comando corretto per la tua shell
Claude Code on Windows requires git-bashInstalla o configura Git Bash
Error loading shared libraryVariante binaria sbagliata per il tuo sistema
Illegal instruction su LinuxMancata corrispondenza dell’architettura
dyld: cannot load o Abort trap su macOSIncompatibilità binaria
Invoke-Expression: Missing argument in parameter listLo script di installazione restituisce HTML
App unavailable in regionClaude Code non è disponibile nel tuo paese. Vedi paesi supportati.
unable to get local issuer certificateConfigura i certificati CA aziendali
OAuth error o 403 ForbiddenCorreggi l’autenticazione
Se il tuo problema non è elencato, segui questi passaggi diagnostici.

​
Esegui il debug dei problemi di installazione

​
Controlla la connettività di rete

Il programma di installazione scarica da storage.googleapis.com. Verifica di poterlo raggiungere: 
curl -sI https://storage.googleapis.com
Se questo fallisce, la tua rete potrebbe bloccare la connessione. Le cause comuni sono:
  • Firewall aziendali o proxy che bloccano Google Cloud Storage
  • Restrizioni di rete regionali: prova una VPN o una rete alternativa
  • Problemi TLS/SSL: aggiorna i certificati CA del tuo sistema, oppure controlla se HTTPS_PROXY è configurato
Se sei dietro un proxy aziendale, imposta HTTPS_PROXY e HTTP_PROXY all’indirizzo del tuo proxy prima di installare. Chiedi al tuo team IT l’URL del proxy se non lo conosci, oppure controlla le impostazioni del proxy del tuo browser. Questo esempio imposta entrambe le variabili proxy, quindi esegue il programma di installazione attraverso il tuo proxy: 
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash

​
Verifica il tuo PATH

Se l’installazione è riuscita ma ricevi un errore command not found o not recognized quando esegui claude, la directory di installazione non è nel tuo PATH. La tua shell cerca i programmi nelle directory elencate in PATH, e il programma di installazione posiziona claude in ~/.local/bin/claude su macOS/Linux o %USERPROFILE%\.local\bin\claude.exe su Windows. Controlla se la directory di installazione è nel tuo PATH elencando le voci di PATH e filtrando per local/bin: 
echo $PATH | tr ':' '\n' | grep local/bin
Se non c’è output, la directory manca. Aggiungila alla configurazione della tua shell:
# Zsh (default su macOS)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Bash (default su Linux)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
In alternativa, chiudi e riapri il tuo terminale.Verifica che la correzione abbia funzionato:
claude --version

​
Controlla le installazioni in conflitto

Più installazioni di Claude Code possono causare mancate corrispondenze di versione o comportamenti inaspettati. Controlla cosa è installato:
Elenca tutti i binari claude trovati nel tuo PATH:
which -a claude
Controlla se sono presenti le versioni del programma di installazione nativo e npm:
ls -la ~/.local/bin/claude

ls -la ~/.claude/local/

npm -g ls @anthropic-ai/claude-code 2>/dev/null
Se trovi più installazioni, mantieni solo una. L’installazione nativa in ~/.local/bin/claude è consigliata. Rimuovi eventuali installazioni extra: Disinstalla un’installazione globale npm: 
npm uninstall -g @anthropic-ai/claude-code
Rimuovi un’installazione Homebrew su macOS: 
brew uninstall --cask claude-code

​
Controlla i permessi della directory

Il programma di installazione ha bisogno di accesso in scrittura a ~/.local/bin/ e ~/.claude/. Se l’installazione fallisce con errori di permesso, controlla se queste directory sono scrivibili: 
test -w ~/.local/bin && echo "writable" || echo "not writable"
test -w ~/.claude && echo "writable" || echo "not writable"
Se una delle directory non è scrivibile, crea la directory di installazione e imposta il tuo utente come proprietario: 
sudo mkdir -p ~/.local/bin
sudo chown -R $(whoami) ~/.local

​
Verifica che il binario funzioni

Se claude è installato ma si arresta in modo anomalo o si blocca all’avvio, esegui questi controlli per restringere la causa. Conferma che il binario esiste ed è eseguibile: 
ls -la $(which claude)
Su Linux, controlla le librerie condivise mancanti. Se ldd mostra librerie mancanti, potrebbe essere necessario installare pacchetti di sistema. Su Alpine Linux e altre distribuzioni basate su musl, vedi Configurazione di Alpine Linux. 
ldd $(which claude) | grep "not found"
Esegui un rapido controllo di sanità mentale che il binario possa essere eseguito: 
claude --version

​
Problemi di installazione comuni

Questi sono i problemi di installazione più frequentemente riscontrati e le loro soluzioni.

​
Lo script di installazione restituisce HTML invece di uno script shell

Quando esegui il comando di installazione, potresti vedere uno di questi errori: 
bash: line 1: syntax error near unexpected token `<'
bash: line 1: `<!DOCTYPE html>'
Su PowerShell, lo stesso problema appare come: 
Invoke-Expression: Missing argument in parameter list.
Questo significa che l’URL di installazione ha restituito una pagina HTML invece dello script di installazione. Se la pagina HTML dice “App unavailable in region,” Claude Code non è disponibile nel tuo paese. Vedi paesi supportati. Altrimenti, questo può accadere a causa di problemi di rete, routing regionale, o un’interruzione temporanea del servizio. Soluzioni:
  1. Usa un metodo di installazione alternativo: Su macOS o Linux, installa tramite Homebrew: 
    brew install --cask claude-code
    Su Windows, installa tramite WinGet: 
    winget install Anthropic.ClaudeCode
  2. Riprova dopo alcuni minuti: il problema è spesso temporaneo. Aspetta e prova di nuovo il comando originale.

​
command not found: claude dopo l’installazione

L’installazione è terminata ma claude non funziona. L’errore esatto varia in base alla piattaforma:
PiattaformaMessaggio di errore
macOSzsh: command not found: claude
Linuxbash: claude: command not found
Windows CMD'claude' is not recognized as an internal or external command
PowerShellclaude : The term 'claude' is not recognized as the name of a cmdlet
Questo significa che la directory di installazione non è nel percorso di ricerca della tua shell. Vedi Verifica il tuo PATH per la correzione su ogni piattaforma.

​
curl: (56) Failure writing output to destination

Il comando curl ... | bash scarica lo script e lo passa direttamente a Bash per l’esecuzione usando una pipe (|). Questo errore significa che la connessione si è interrotta prima che lo script finisse di scaricarsi. Le cause comuni includono interruzioni di rete, il download bloccato a metà flusso, o limiti di risorse di sistema. Soluzioni:
  1. Controlla la stabilità della rete: i binari di Claude Code sono ospitati su Google Cloud Storage. Testa di poter raggiungerlo: 
    curl -fsSL https://storage.googleapis.com -o /dev/null
    Se il comando si completa silenziosamente, la tua connessione è buona e il problema è probabilmente intermittente. Riprova il comando di installazione. Se vedi un errore, la tua rete potrebbe bloccare il download.
  2. Prova un metodo di installazione alternativo: Su macOS o Linux: 
    brew install --cask claude-code
    Su Windows: 
    winget install Anthropic.ClaudeCode

​
Errori di connessione TLS o SSL

Errori come curl: (35) TLS connect error, schannel: next InitializeSecurityContext failed, o il Could not establish trust relationship for the SSL/TLS secure channel di PowerShell indicano fallimenti dell’handshake TLS. Soluzioni:
  1. Aggiorna i certificati CA del tuo sistema: Su Ubuntu/Debian: 
    sudo apt-get update && sudo apt-get install ca-certificates
    Su macOS tramite Homebrew: 
    brew install ca-certificates
  2. Su Windows, abilita TLS 1.2 in PowerShell prima di eseguire il programma di installazione: 
    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
irm https://claude.ai/install.ps1 | iex
  3. Controlla l’interferenza del proxy o del firewall: i proxy aziendali che eseguono l’ispezione TLS possono causare questi errori, incluso unable to get local issuer certificate. Imposta NODE_EXTRA_CA_CERTS sul tuo bundle di certificati CA aziendale: 
    export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
    Chiedi al tuo team IT il file del certificato se non lo hai. Puoi anche provare su una connessione diretta per confermare che il proxy è la causa.

​
Failed to fetch version from storage.googleapis.com

Il programma di installazione non ha potuto raggiungere il server di download. Questo in genere significa che storage.googleapis.com è bloccato sulla tua rete. Soluzioni:
  1. Testa la connettività direttamente: 
    curl -sI https://storage.googleapis.com
  2. Se dietro un proxy, imposta HTTPS_PROXY in modo che il programma di installazione possa instradarlo attraverso. Vedi configurazione del proxy per i dettagli. 
    export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash
  3. Se su una rete ristretta, prova una rete diversa o una VPN, oppure usa un metodo di installazione alternativo: Su macOS o Linux: 
    brew install --cask claude-code
    Su Windows: 
    winget install Anthropic.ClaudeCode

​
Windows: irm o && non riconosciuto

Se vedi 'irm' is not recognized o The token '&&' is not valid, stai eseguendo il comando sbagliato per la tua shell.
  • irm non riconosciuto: sei in CMD, non in PowerShell. Hai due opzioni: Apri PowerShell cercando “PowerShell” nel menu Start, quindi esegui il comando di installazione originale: 
    irm https://claude.ai/install.ps1 | iex
    Oppure rimani in CMD e usa il programma di installazione CMD: 
    curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
  • && non valido: sei in PowerShell ma hai eseguito il comando del programma di installazione CMD. Usa il programma di installazione PowerShell: 
    irm https://claude.ai/install.ps1 | iex

​
Installazione interrotta su server Linux con poca memoria

Se vedi Killed durante l’installazione su un VPS o un’istanza cloud: 
Setting up Claude Code...
Installing Claude Code native build latest...
bash: line 142: 34803 Killed    "$binary_path" install ${TARGET:+"$TARGET"}
L’OOM killer di Linux ha terminato il processo perché il sistema ha esaurito la memoria. Claude Code richiede almeno 4 GB di RAM disponibile. Soluzioni:
  1. Aggiungi spazio di swap se il tuo server ha RAM limitata. Lo swap utilizza lo spazio su disco come memoria di overflow, consentendo al programma di installazione di completarsi anche con poca RAM fisica. Crea un file di swap da 2 GB e abilitalo: 
    sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
    Quindi riprova l’installazione: 
    curl -fsSL https://claude.ai/install.sh | bash
  2. Chiudi altri processi per liberare memoria prima di installare.
  3. Usa un’istanza più grande se possibile. Claude Code richiede almeno 4 GB di RAM.

​
L’installazione si blocca in Docker

Quando installi Claude Code in un contenitore Docker, installare come root in / può causare blocchi. Soluzioni:
  1. Imposta una directory di lavoro prima di eseguire il programma di installazione. Quando eseguito da /, il programma di installazione scansiona l’intero filesystem, il che causa un utilizzo eccessivo della memoria. Impostare WORKDIR limita la scansione a una piccola directory: 
    WORKDIR /tmp
RUN curl -fsSL https://claude.ai/install.sh | bash
  2. Aumenta i limiti di memoria di Docker se usi Docker Desktop: 
    docker build --memory=4g .

​
Windows: Claude Desktop sostituisce il comando CLI claude

Se hai installato una versione precedente di Claude Desktop, potrebbe registrare un Claude.exe nella directory WindowsApps che ha priorità nel PATH rispetto a Claude Code CLI. Eseguire claude apre l’app Desktop invece della CLI. Aggiorna Claude Desktop all’ultima versione per risolvere questo problema.

​
Windows: “Claude Code on Windows requires git-bash”

Claude Code su Windows nativo ha bisogno di Git for Windows, che include Git Bash. Se Git non è installato, scaricalo e installalo da git-scm.com/downloads/win. Durante la configurazione, seleziona “Add to PATH.” Riavvia il tuo terminale dopo l’installazione. Se Git è già installato ma Claude Code ancora non riesce a trovarlo, imposta il percorso nel tuo file settings.json: 
{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}
Se il tuo Git è installato da qualche altra parte, trova il percorso eseguendo where.exe git in PowerShell e usa il percorso bin\bash.exe da quella directory.

​
Linux: variante binaria sbagliata installata (mancata corrispondenza musl/glibc)

Se vedi errori su librerie condivise mancanti come libstdc++.so.6 o libgcc_s.so.1 dopo l’installazione, il programma di installazione potrebbe aver scaricato la variante binaria sbagliata per il tuo sistema. 
Error loading shared library libstdc++.so.6: No such file or directory
Questo può accadere su sistemi basati su glibc che hanno pacchetti di cross-compilazione musl installati, causando al programma di installazione di rilevare erroneamente il sistema come musl. Soluzioni:
  1. Controlla quale libc usa il tuo sistema: 
    ldd /bin/ls | head -1
    Se mostra linux-vdso.so o riferimenti a /lib/x86_64-linux-gnu/, sei su glibc. Se mostra musl, sei su musl.
  2. Se sei su glibc ma hai il binario musl, rimuovi l’installazione e reinstalla. Puoi anche scaricare manualmente il binario corretto dal bucket GCS in https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases/{VERSION}/manifest.json. Apri un problema su GitHub con l’output di ldd /bin/ls e ls /lib/libc.musl*.
  3. Se sei effettivamente su musl (Alpine Linux), installa i pacchetti richiesti: 
    apk add libgcc libstdc++ ripgrep

​
Illegal instruction su Linux

Se il programma di installazione stampa Illegal instruction invece del messaggio Killed dell’OOM, il binario scaricato non corrisponde all’architettura della tua CPU. Questo accade comunemente su server ARM che ricevono un binario x86, o su CPU più vecchie che mancano di set di istruzioni richiesti. 
bash: line 142: 2238232 Illegal instruction    "$binary_path" install ${TARGET:+"$TARGET"}
Soluzioni:
  1. Verifica la tua architettura: 
    uname -m
    x86_64 significa 64-bit Intel/AMD, aarch64 significa ARM64. Se il binario non corrisponde, apri un problema su GitHub con l’output.
  2. Prova un metodo di installazione alternativo mentre il problema dell’architettura viene risolto: 
    brew install --cask claude-code

​
dyld: cannot load su macOS

Se vedi dyld: cannot load o Abort trap: 6 durante l’installazione, il binario è incompatibile con la tua versione di macOS o hardware. 
dyld: cannot load 'claude-2.1.42-darwin-x64' (load command 0x80000034 is unknown)
Abort trap: 6
Soluzioni:
  1. Controlla la tua versione di macOS: Claude Code richiede macOS 13.0 o successivo. Apri il menu Apple e seleziona About This Mac per controllare la tua versione.
  2. Aggiorna macOS se sei su una versione precedente. Il binario utilizza comandi di caricamento che le versioni precedenti di macOS non supportano.
  3. Prova Homebrew come metodo di installazione alternativo: 
    brew install --cask claude-code

​
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 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 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 npm/nvm di Windows di avere priorità rispetto all’installazione di WSL. Puoi identificare questo problema da:
  • Eseguire which npm e which node - se puntano a percorsi di Windows (che iniziano con /mnt/c/), vengono utilizzate le versioni di Windows
  • Sperimentare funzionalità interrotte 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 primaria: assicurati che nvm sia correttamente caricato nella tua shell La causa più comune è che nvm non è caricato in shell non interattive. Aggiungi quanto segue al tuo file di configurazione della 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"
Oppure esegui direttamente nella tua sessione corrente: 
source ~/.nvm/nvm.sh
Alternativa: regola l’ordine del PATH Se nvm è correttamente caricato 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 tramite 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.

​
Configurazione sandbox WSL2

Il sandboxing è supportato su WSL2 ma richiede l’installazione di pacchetti aggiuntivi. Se vedi un errore come “Sandbox requires socat and bubblewrap” quando esegui /sandbox, installa le dipendenze: 
sudo apt-get install bubblewrap socat
WSL1 non supporta il sandboxing. Se vedi “Sandboxing requires WSL2”, devi eseguire l’upgrade a WSL2 o eseguire Claude Code senza sandboxing.

​
Errori di permesso durante l’installazione

Se il programma di installazione nativo fallisce con errori di permesso, la directory di destinazione potrebbe non essere scrivibile. Vedi Controlla i permessi della directory. Se hai precedentemente installato con npm e stai riscontrando errori di permesso specifici di npm, passa al programma di installazione nativo: 
curl -fsSL https://claude.ai/install.sh | bash

​
Permessi e autenticazione

Queste sezioni affrontano i fallimenti di accesso, i problemi di token e il comportamento dei prompt di permesso.

​
Prompt di permesso ripetuti

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 Permissions.

​
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 il browser non si apre automaticamente durante l’accesso, premi c per copiare l’URL OAuth negli appunti, quindi incollalo nel tuo browser manualmente.

​
Errore OAuth: codice non valido

Se vedi OAuth error: Invalid code. Please make sure the full code was copied, il codice di accesso è scaduto o è stato troncato durante la copia-incolla. Soluzioni:
  • Premi Invio per riprovare e completa l’accesso rapidamente dopo che il browser si apre
  • Digita c per copiare l’URL completo se il browser non si apre automaticamente
  • Se usi una sessione remota/SSH, il browser potrebbe aprirsi sulla macchina sbagliata. Copia l’URL visualizzato nel terminale e aprilo nel tuo browser locale.

​
403 Forbidden dopo l’accesso

Se vedi API Error: 403 {"error":{"type":"forbidden","message":"Request not allowed"}} dopo l’accesso:
  • Utenti Claude Pro/Max: verifica che il tuo abbonamento sia attivo in claude.ai/settings
  • Utenti Console: conferma che il tuo account abbia il ruolo “Claude Code” o “Developer” assegnato dal tuo amministratore
  • Dietro un proxy: i proxy aziendali possono interferire con le richieste API. Vedi configurazione di rete per la configurazione del proxy.

​
L’accesso OAuth fallisce in WSL2

L’accesso basato su browser in WSL2 potrebbe fallire se WSL non riesce ad aprire il tuo browser di Windows. Imposta la variabile di ambiente BROWSER: 
export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude
Oppure copia l’URL manualmente: quando appare il prompt di accesso, premi c per copiare l’URL OAuth, quindi incollalo nel tuo browser di Windows.

​
”Not logged in” o token scaduto

Se Claude Code ti chiede di accedere di nuovo dopo una sessione, il tuo token OAuth potrebbe essere scaduto. Esegui /login per autenticarti di nuovo. Se questo accade frequentemente, controlla che l’orologio di sistema sia accurato, poiché la convalida del token dipende da timestamp corretti.

​
Posizioni dei file di configurazione

Claude Code memorizza la configurazione in diverse posizioni:
FileScopo
~/.claude/settings.jsonImpostazioni utente (permessi, hooks, override del modello)
.claude/settings.jsonImpostazioni del progetto (controllate nel controllo del codice sorgente)
.claude/settings.local.jsonImpostazioni del progetto locale (non committate)
~/.claude.jsonStato globale (tema, OAuth, server MCP)
.mcp.jsonServer MCP del progetto (controllati nel controllo del codice sorgente)
managed-mcp.jsonServer MCP gestiti
Impostazioni gestiteImpostazioni gestite (gestite dal server, politiche MDM/a livello di sistema operativo, o basate su file)
Su Windows, ~ si riferisce alla tua directory home dell’utente, come C:\Users\YourName. Per i dettagli sulla configurazione di questi file, vedi Settings e MCP.

​
Ripristino della configurazione

Per ripristinare Claude Code alle impostazioni predefinite, puoi rimuovere i file di configurazione: 
# Ripristina tutte le impostazioni utente e lo stato
rm ~/.claude.json
rm -rf ~/.claude/

# Ripristina le impostazioni specifiche del progetto
rm -rf .claude/
rm .mcp.json
Questo rimuoverà tutte le tue impostazioni, configurazioni del server MCP, e cronologia della sessione.

​
Prestazioni e stabilità

Queste sezioni affrontano i problemi relativi all’utilizzo delle risorse, alla reattività e al comportamento della ricerca.

​
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 reattivo:
  1. Premi Ctrl+C per tentare di annullare l’operazione corrente
  2. Se non reattivo, potrebbe essere necessario chiudere il terminale e riavviare

​
Problemi di ricerca e scoperta

Se lo strumento Search, le menzioni @file, gli agenti personalizzati e le skill personalizzate 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 possono risultare in meno corrispondenze del previsto quando usi Claude Code su WSL. La ricerca funziona ancora, ma restituisce meno risultati rispetto a un file system nativo.
/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: “Search for JWT validation logic in the auth-service package” o “Find use of md5 hash in JS files”.
  2. Sposta il progetto al file system Linux: se possibile, assicurati che il tuo progetto si trovi sul file system Linux (/home/) piuttosto che sul file system di 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 IDE

Se Claude Code non si connette al tuo IDE o si comporta inaspettatamente all’interno di un terminale IDE, prova le soluzioni di seguito.

​
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 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
# Esempio di output: 172.21.123.45
  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 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 di 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 guida IDE JetBrains.

​
Segnala problemi di integrazione IDE su Windows

Se stai riscontrando problemi di integrazione 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 mirrored
  • 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 IDE JetBrains

Se stai usando Claude Code nei terminali JetBrains e il tasto Esc non interrompe l’agente come previsto, questo è probabilmente dovuto a uno scontro di scorciatoie da tastiera con i tasti di scelta rapida predefiniti di JetBrains. Per risolvere questo problema:
  1. Vai a Settings → Tools → Terminal
  2. Uno di:
    • Deseleziona “Move focus to the editor with Escape”, oppure
    • Fai clic su “Configure terminal keybindings” e elimina la 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 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 nel markdown generato: 
```
function example() {
  return "hello";
}
```text
Invece di blocchi correttamente taggati come: 
```javascript
function example() {
  return "hello";
}
```text
Soluzioni:
  1. Chiedi a Claude di aggiungere tag di linguaggio: richiedi “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 Auto-format code after edits per un esempio di hook PostToolUse di formattazione.
  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.

​
Riduci i problemi di formattazione 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

​
Ottieni più aiuto

Se stai riscontrando problemi non affrontati 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 diagnosticare i problemi. Controlla:
    • Tipo di installazione, versione e funzionalità di ricerca
    • Stato dell’aggiornamento automatico e versioni disponibili
    • File di impostazioni non validi (JSON malformato, tipi non corretti)
    • Errori di configurazione del server MCP
    • Problemi di configurazione delle scorciatoie da tastiera
    • Avvisi di utilizzo del contesto (file CLAUDE.md di grandi dimensioni, utilizzo elevato di token MCP, regole di permesso non raggiungibili)
    • Errori di caricamento di plugin e agenti
  4. Chiedi a Claude direttamente sulle sue capacità e funzionalità - Claude ha accesso integrato alla sua documentazione