L'installazione di Claude Code richiede un solo comando, ma i problemi reali iniziano dopo. La maggior parte degli articoli sull'installazione termina con «Installazione completata», ma in Corea del Sud ci sono altri due ostacoli prima di riuscire a eseguirlo — i permessi per l'installazione globale e l'accesso e il pagamento. Questo articolo illustra i tre passaggi in ordine, compresa la soluzione per ciascun blocco.
Passaggio 1 — Installazione (un solo comando)
L'unico prerequisito è Node.js 18 o superiore. macOS, Windows (WSL) e Linux usano lo stesso comando.
# Node.js 18 이상이 필요합니다. 먼저 확인하세요.
node --version
# 설치
npm install -g @anthropic-ai/claude-code
# 확인 — 버전이 출력되면 설치 자체는 끝난 것입니다
claude --versionclaude --versionSe viene visualizzata questa versione, l'installazione è completata. Se il processo si ferma qui, rientri in una delle due sezioni seguenti.
Passaggio 2 — Errori di permessi e percorso
Sono i due errori più comuni durante l'installazione.
| Sintomo | Causa e soluzione |
|---|---|
Errore di permessi EACCES | Nessun permesso di scrittura nella directory globale di npm — sposta il percorso globale nella directory home |
command not found: claude | Il bin globale di npm non è nel PATH — aggiungilo e apri un nuovo terminale |
Non è consigliabile aggiungere EACCES a sudo. L'installazione riuscirà per il momento, ma lo stesso problema si ripresenterà a ogni aggiornamento e il proprietario della directory globale diventerà root, complicando ulteriormente la situazione. È più ordinato spostare il percorso nella directory home.
# npm 전역 설치에서 EACCES가 나면 sudo를 붙이지 말고
# 전역 경로를 홈 디렉터리로 옮기는 편이 안전합니다.
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
# 셸 설정에 추가한 뒤 새 터미널을 엽니다
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrcSu Windows, installa all'interno di WSL. Anche i file del progetto devono trovarsi nel file system WSL affinché il monitoraggio dei file e la gestione dei percorsi funzionino correttamente.
Passaggio 3 — Accesso e pagamento (dove ci si blocca davvero in Corea del Sud)
Al termine dell'installazione, esegui claude: ti verrà richiesto di effettuare l'accesso. È il punto in cui ci si blocca più spesso in Corea del Sud e la causa non ha nulla a che vedere con l'installazione.
- Carta con pagamenti internazionali bloccati — il pagamento dell'abbonamento fallisce. Abilitare i pagamenti internazionali nell'app o sul sito dell'emittente risolve nella maggior parte dei casi.
- KakaoPay e Toss — non sono supportati per i pagamenti web su claude.ai (sono disponibili solo come metodi di pagamento dello store per gli abbonamenti nelle app mobili). Se provi a usare un metodo di pagamento locale, ti bloccherai a questo passaggio.
- Se non disponi di una carta abilitata ai pagamenti internazionali — non puoi usare il percorso dell'abbonamento web. L'autenticazione tramite chiave descritta di seguito utilizza il saldo Kunavo; quando la schermata di pagamento è visualizzata in won coreani, sono disponibili KakaoPay, Naver Pay, PAYCO, Samsung Pay e carte nazionali (anche quelle con i pagamenti internazionali bloccati), quindi puoi ricaricare senza una carta per pagamenti internazionali (Toss non è supportato).
Abbiamo spiegato quali metodi di pagamento funzionano e quali no nella guida ai metodi di pagamento di Claude.
Se il pagamento dell'abbonamento è bloccato — eseguilo con una chiave senza reinstallare nulla
Oltre all'accesso tramite abbonamento, Claude Code supporta anche l'autenticazione con chiave API. Se imposti le due variabili d'ambiente seguenti, il programma viene eseguito senza passare dalla schermata di accesso; eliminandole, torni al comportamento originale. Non è necessario reinstallare nulla.
# 구독 결제가 막혔을 때 설치한 클로드 코드를 그대로 쓰는 방법.
# 이 두 줄이 있으면 로그인 대신 키로 인증하고, 지우면 원래대로 돌아갑니다.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
# 클로드 코드의 기본 모델과 opus·sonnet 별칭은 Anthropic의 최신 모델을 따라가므로,
# Kunavo가 제공하는 모델로 고정해 404를 막습니다. sonnet 별칭은 Kunavo가 제공하지
# 않는 Sonnet 5.5를 요청하므로, 고정하지 않으면 /model sonnet, opusplan의 실행 단계,
# sonnet 서브에이전트가 404로 실패합니다. opus는 Opus 5.5로 고정하며,
# 클로드 코드 v2.1.280 이상이 필요합니다(이전 버전은 claude update).
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5
claudeCon questo percorso paghi solo i token effettivamente utilizzati invece di una tariffa mensile, quindi nei mesi in cui non lavori non sostieni alcun costo. La procedura per ottenere la chiave è descritta in Come ottenere una chiave API Claude; per sapere quale opzione costa meno tra abbonamento e tariffazione a consumo, consulta Prezzi di Claude Code.
Prima esecuzione dopo l'installazione — 3 minuti per verificare
Una volta avviato, dalla directory del progetto esegui claude e poi /init una volta. Leggerà il repository e creerà CLAUDE.md, che verrà letto automaticamente in tutte le sessioni successive. Da qui in poi — scrittura delle regole, configurazione dei permessi e comandi personalizzati — continua con Come usare Claude Code.
Gli errori che compaiono dopo l'avvio (401, 429, 529) hanno cause completamente diverse da quelle della fase di installazione. I criteri per distinguerli sono raccolti in Guida agli errori di Claude Code.
Domande frequenti
Come si installa Claude Code?
Basta un'installazione globale tramite npm. Esegui npm install -g @anthropic-ai/claude-code, poi verifica con claude --version. L'unico prerequisito è Node.js 18 o superiore e lo stesso comando funziona su macOS, Windows e Linux. Su Windows è generalmente meno problematico installarlo all'interno di WSL.
L'installazione è riuscita, ma il programma non si avvia. Cosa devo controllare?
Per prima cosa verifica che claude --version produca un output. Se lo produce, l'installazione è completata e il problema rimasto riguarda l'autenticazione. Se ricevi un errore che indica che il comando non è stato trovato, il percorso globale di npm non è nel PATH: aggiungi al PATH la directory bin del percorso restituito da npm config get prefix e riapri il terminale.
Durante l'installazione ricevo un errore di autorizzazione EACCES.
Significa che non hai il permesso di scrivere nella directory globale di npm. Installare con sudo funziona nell'immediato, ma non è consigliato perché i problemi di autorizzazione si ripresenteranno. È più sicuro spostare il percorso globale nella directory home con npm config set prefix ~/.npm-global e aggiungerlo al PATH.
Dopo l'installazione, il pagamento fallisce durante l'accesso.
È il punto in cui si verificano più spesso blocchi in Corea. Le carte con i pagamenti internazionali bloccati falliscono per gli abbonamenti; abilitarli nell'app o sul sito dell'emittente risolve il problema nella maggior parte dei casi. KakaoPay e Toss non sono supportati per i pagamenti web su claude.ai e compaiono solo nell'elenco dei metodi di pagamento coreani di App Store·Google Play per gli abbonamenti nelle app mobili. Se devi aggirare il pagamento, puoi usare una chiave API invece dell'abbonamento. In questo percorso, la ricarica del saldo Kunavo offre KakaoPay, Naver Pay, PAYCO, Samsung Pay e carte nazionali quando la schermata è visualizzata in won coreani (Toss non è supportato).
Posso usare Claude Code senza abbonamento?
Sì. Oltre all'accesso tramite abbonamento, Claude Code supporta l'autenticazione con chiave API: imposta le due variabili d'ambiente ANTHROPIC_BASE_URL e ANTHROPIC_AUTH_TOKEN per eseguirlo senza effettuare l'accesso. In questo caso paghi solo i token utilizzati invece di una tariffa mensile e nei mesi in cui non lo usi non sostieni alcun costo.
Come si installa su Windows?
Consigliamo di installarlo all'interno di WSL (Windows Subsystem for Linux). Installa Node.js 18 o superiore nel terminale WSL, poi esegui lo stesso comando npm. Anche il progetto su cui lavori deve trovarsi nel file system WSL affinché il monitoraggio dei file e la gestione dei percorsi funzionino correttamente.