Risoluzione dei codici di errore di Claude Code

Causa comune: La directory di installazione non è nel PATH, oppure la shell corrente non ha ricaricato la configurazione.

Soluzione: Apri un nuovo terminale, oppure aggiungi la directory di installazione di Claude Code al PATH e ricarica la configurazione della shell.

export PATH="$PATH:$HOME/.local/bin"
source ~/.zshrc

Causa comune: La versione di Node è inferiore al requisito ufficiale, oppure WSL sta richiamando il Node lato Windows.

Soluzione: Aggiorna Node o usa l'installer nativo ufficiale. In WSL verifica il percorso con which node / which npm per assicurarti che provenga dall'ambiente Linux.

node -v
which node
which npm

Causa comune: La directory globale di npm appartiene a root, oppure una precedente installazione con sudo ha lasciato i permessi in uno stato errato.

Soluzione: Non installare Claude Code con sudo. Sposta il prefisso di npm in una directory utente oppure usa l'installer nativo.

npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"

Causa comune: Il callback OAuth del browser non raggiunge la CLI locale: capita spesso con SSH remoto, devcontainer, firewall restrittivi o callback su localhost bloccati.

Soluzione: Verifica che browser e CLI possano comunicare sulla stessa macchina. Se necessario, esci, riavvia Claude Code e completa di nuovo l'autenticazione.

/logout
# 关闭 Claude Code 后重新运行
claude

Causa comune: Un proxy aziendale o un gateway di sicurezza inietta una CA autofirmata di cui Node non si fida per impostazione predefinita.

Soluzione: Chiedi all'IT il bundle CA aziendale e indicalo tramite NODE_EXTRA_CA_CERTS.

export NODE_EXTRA_CA_CERTS=/path/to/company-ca.pem

Causa comune: Le variabili del proxy sono configurate male, il protocollo del proxy non è supportato, NO_PROXY esclude il dominio di destinazione oppure un firewall aziendale blocca l'accesso.

Soluzione: Claude Code usa le variabili d'ambiente standard per proxy HTTP/HTTPS; la documentazione indica che i proxy SOCKS non sono supportati. Ripeti prima il test con HTTPS_PROXY.

export HTTPS_PROXY=http://proxy.example.com:8080
echo $HTTPS_PROXY
echo $NO_PROXY

Causa comune: L'organizzazione non ha abilitato Claude Code, la whitelist aziendale non include l'uscita attuale, si applicano restrizioni di account/regione/policy, oppure il proxy viene rifiutato.

Soluzione: Per gli account personali, verifica prima i paesi supportati e lo stato dell'account; per gli account aziendali, chiedi a un amministratore di controllare i permessi di Claude Code, SSO, la whitelist degli IP e le regole del firewall.

Causa comune: Le richieste sono troppo frequenti, la concorrenza è troppo alta, oppure il piano dell'account o l'organizzazione ha raggiunto un limite di richieste.

Soluzione: Riduci la concorrenza esterna, interrompi i cicli di ripetizione e attendi il ripristino del limite. Non avvolgere Claude Code in più worker per forzare la velocità.

Causa comune: La chiave API proviene da un'altra shell, una chiave della Console è in conflitto con una sessione OAuth, oppure l'organizzazione richiede l'accesso SSO.

Soluzione: Controlla se ANTHROPIC_API_KEY è impostata nella shell corrente. Gli account aziendali devono seguire la procedura di accesso Console/SSO richiesta dall'amministratore.

echo $ANTHROPIC_API_KEY