Claude Code si installa con un unico comando su ogni piattaforma supportata e l'intera prima esecuzione consiste in: installare, digitare claude, accedere. Questa guida contiene il comando esatto per ogni sistema operativo, cosa controllare quando qualcosa non funziona e come indirizzarlo a un endpoint diverso una volta operativo.
Comandi verificati il 10 ottobre 2026 rispetto alla documentazione di configurazione di Claude Code di Anthropic.
Prima di iniziare
| Requisito | Cosa è supportato |
|---|---|
| Sistema operativo | macOS 13.0+, Windows 10 1809+ / Server 2019+, Ubuntu 20.04+, Debian 10+, Alpine Linux 3.19+ |
| Hardware | Almeno 4 GB di RAM, x64 o ARM64 |
| Shell | Bash, Zsh, PowerShell o CMD |
| Rete | Connessione Internet obbligatoria |
| Account | Pro, Max, Team, Enterprise o Console: il piano gratuito Claude.ai non include Claude Code |
Installazione — programma di installazione nativo
Questo è il metodo consigliato su ogni piattaforma. Installa un binario autonomo e lo aggiorna automaticamente in background.
# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash# Windows PowerShell
irm https://claude.ai/install.ps1 | iex:: Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmdSe non sai con certezza quale shell Windows stai usando, lo indica il prompt: PowerShell mostra PS C:\, mentre CMD mostra C:\ senza PS. Eseguire il comando sbagliato è l'errore di installazione più comune su Windows: nella tabella di risoluzione dei problemi qui sotto trovi l'errore esatto per ciascun caso.
Gestori di pacchetti
Usali se preferisci affidare l'installazione al gestore di pacchetti che già utilizzi. Il compromesso riguarda gli aggiornamenti: nessuno di questi si aggiorna automaticamente per impostazione predefinita, a differenza del programma di installazione nativo.
# Homebrew (macOS, Linux) — stable channel
brew install --cask claude-code
# WinGet (Windows)
winget install Anthropic.ClaudeCode
# npm — requires Node.js 22+; never with sudo
npm install -g @anthropic-ai/claude-codeHomebrew pubblica due cask: claude-code segue il canale stabile (in genere con circa una settimana di ritardo e saltando le release con regressioni importanti), mentre claude-code@latest distribuisce immediatamente ogni release. Esistono repository apt, dnf e apk firmati per Debian / Ubuntu, Fedora / RHEL e Alpine, ciascuno con gli stessi canali stabile e latest.
Su npm, non usare mai sudo npm install -g: causa problemi di autorizzazioni e rappresenta un rischio per la sicurezza. Il pacchetto npm installa esattamente lo stesso binario nativo del programma di installazione autonomo, quindi in entrambi i casi non esiste alcuna dipendenza da Node durante l'esecuzione.
Verifica l'installazione
claude --version # prints e.g. "2.1.211 (Claude Code)"
claude doctor # read-only install + settings diagnostics
claude # start a session in the current projectclaude doctor è il comando da ricordare: stampa lo stato dell'installazione, gli errori di convalida dei file delle impostazioni e le correzioni suggerite senza avviare una sessione, rendendolo il modo più rapido per distinguere un'installazione danneggiata da una configurazione danneggiata.
Prima esecuzione e accesso
Apri un terminale nella directory del progetto su cui vuoi lavorare ed esegui claude. Il comando apre una sessione interattiva e ti guida nella procedura di accesso tramite browser. Claude Code richiede un account Pro, Max, Team, Enterprise o Console.
C'è un comportamento che vale la pena conoscere prima che ti colga di sorpresa: se ANTHROPIC_API_KEY è già impostata nel tuo ambiente, Claude Code ti chiede una volta di approvare quella chiave invece di aprire un browser. Rifiuta la richiesta e da quel momento la chiave viene ignorata senza ulteriori richieste: è esattamente come se la variabile non venisse letta. Riattivala in /config → Usa una chiave API personalizzata.
Windows: nativo o WSL
| Opzione | Richiede | Sandbox | Sceglilo quando |
|---|---|---|---|
| Windows nativo | Nulla; Git for Windows è facoltativo | Non supportato | I progetti e gli strumenti sono nativi di Windows |
| WSL 2 | WSL 2 abilitato | Supportato | Toolchain Linux oppure esecuzione di comandi in sandbox |
| WSL 1 | WSL 1 abilitato | Non supportato | WSL 2 non è disponibile |
Su Windows nativo, installare Git for Windows è facoltativo ma consigliato: fornisce Git Bash, che supporta lo strumento Bash. Senza di esso Claude Code esegue i comandi shell tramite lo strumento PowerShell. In WSL devi installare e avviare claude all'interno del terminale WSL, non da PowerShell.
Risoluzione dei problemi
| Sintomo | Causa e soluzione |
|---|---|
The token '&&' is not a valid statement separator | Hai eseguito il comando CMD in PowerShell. Usa invece la riga irm … | iex. |
'irm' is not recognized… | Il contrario: hai eseguito il comando PowerShell in CMD. Usa la riga curl … install.cmd. |
syntax error near unexpected token '<', un 403 o un altro errore curl | Il download non ha restituito lo script, in genere a causa di un proxy o di un filtro di rete tra te e il programma di installazione. Riprova oppure usa l'installazione tramite un gestore di pacchetti. |
claude: command not found dopo un'installazione pulita | Apri un nuovo terminale affinché la shell rilevi la directory di installazione, quindi esegui claude doctor. Un'altra causa comune è una seconda installazione più vecchia o un alias shell obsoleto. |
| Errori di autorizzazione durante un'installazione npm | Hai usato sudo oppure la directory globale di npm non è scrivibile. Correggi il proprietario della directory invece di riprovare con sudo: una directory globale non scrivibile impedisce anche gli aggiornamenti automatici. |
Binario nativo mancante dopo npm install -g | Il gestore di pacchetti è configurato per ignorare le dipendenze opzionali. Il binario della piattaforma viene distribuito come dipendenza opzionale: abilitala e reinstalla. |
| L'installazione non riesce su Alpine o su un'altra distribuzione musl | Alpine viene distribuito senza bash e curl. Installa bash curl libgcc libstdc++ ripgrep, quindi imposta USE_BUILTIN_RIPGREP su "0" nel blocco env del file delle impostazioni. |
| La ricerca e l'individuazione dei file non funzionano | Normalmente ripgrep è incluso. Se non può essere eseguito sulla tua piattaforma, installa il sistema ripgrep e imposta USE_BUILTIN_RIPGREP=0. |
| Strumento Bash mancante su Windows nativo | Installa Git for Windows. Se Claude Code non riesce ancora a trovare Git Bash, imposta CLAUDE_CODE_GIT_BASH_PATH nel blocco env di ~/.claude/settings.json. |
401 dopo aver configurato una chiave | La chiave si trova nell'intestazione che il server non legge: alterna tra ANTHROPIC_AUTH_TOKEN e ANTHROPIC_API_KEY. Dettagli nella guida alle chiavi API. |
Indirizzare Claude Code a Kunavo
Una volta operativo, Claude Code funzionerà con qualsiasi endpoint che fornisca l'Anthropic Messages API: legge ANTHROPIC_BASE_URL nativamente, quindi questa è una configurazione supportata e non una soluzione alternativa. Nessun plugin, nessun proxy, nessun binario modificato:
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
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-5Cinque aspetti di quel blocco, ognuno dei quali può farti perdere un'ora se lo configuri in modo errato:
ANTHROPIC_BASE_URLè solo l'origine. Claude Code aggiunge autonomamente/v1/messages: includere il percorso produce un 404.- Usa
ANTHROPIC_AUTH_TOKEN, nonANTHROPIC_API_KEY. Vanno in intestazioni HTTP diverse. Il bearer token diventa effettivo immediatamente, mentreANTHROPIC_API_KEYrichiede l'approvazione una tantum descritta sopra. Kunavo legge la chiave da entrambe le intestazioni, inclusa/v1/models, quindi su Kunavo è proprio quel passaggio di approvazione a distinguerle. - Imposta esplicitamente
ANTHROPIC_MODEL. Kunavo confronta gli slug dei modelli esattamente e non crea alias per i nomi con data, quindiclaude-sonnet-4-5-20250929restituisce 404 mentreclaude-sonnet-5funziona. - Imposta
ANTHROPIC_DEFAULT_OPUS_MODELe ancheANTHROPIC_DEFAULT_SONNET_MODEL. Il valore predefinito integrato di Claude Code e il relativo aliasopuspuntano entrambi all'ultimo modello Opus e, se Kunavo non offre ancora quel modello, la prima richiesta restituisce 404. Il blocco fissaopussu Opus 5.5 (claude-opus-5-5), che richiede Claude Code v2.1.280 o versioni successive — eseguiclaude updatesu un'installazione precedente. L'aliassonnetrichiede Sonnet 5.5, che Kunavo non offre, quindi senza il pin Sonnet/model sonnet, la fase di esecuzione diopusplane qualsiasi subagent configurato sumodel: sonnetrestituiscono 404. - Fissa anche
ANTHROPIC_DEFAULT_HAIKU_MODEL. L'aliashaikurichiede un ID modello che Kunavo non offre (Haiku 5.5 dalla v2.1.293, oppure un ID Haiku 4.5 con data nelle versioni precedenti); senza questa riga,/model haikue i subagenti impostati sumodel: haiku(compreso ilclaude-code-guideintegrato) restituiscono 404. Sposta inoltre dal modello principale le chiamate in background che Claude Code avvia autonomamente per riepiloghi e titoli:claude-haiku-4-5costa $0,70 / $3,50 per 1M, rispetto a $1,40 / $7,00.
Inseriscili nel blocco env di ~/.claude/settings.json invece che in un export della shell se vuoi che anche editor e agenti in background li vedano, e mai nel file .claude/settings.json versionato del progetto. Crea la chiave sk-kn- nella dashboard dopo esserti registrato; la ricarica minima è di $10, non ci sono costi mensili e il saldo non scade. Il costo di ciascun modello per token, rispetto ai prezzi ufficiali dell'API di Anthropic, determina quanto dureranno quei $10.
Cosa cambia dietro un gateway
Codifica, strumenti, subagent, MCP, hook e memorizzazione nella cache dei prompt non cambiano. Cambiano tre aspetti, che vale la pena conoscere prima di pensare che qualcosa non funzioni:
- Remote Control e la dettatura vocale non sono disponibili. Entrambi richiedono un'identità claude.ai, che una credenziale gateway sostituisce.
/fastpotrebbe segnalare la modalità veloce come disabilitata. Il controllo della disponibilità chiama direttamente Anthropic invece di seguire il tuo base URL. Le richieste normali non sono interessate.- I conteggi di
/contextdiventano stime locali. Il conteggio dei token è l'unico endpoint che la specifica del gateway di Anthropic indica come facoltativo e Claude Code effettua stime locali quando è assente: oggi Kunavo non fornisce/v1/messages/count_tokens. La compattazione automatica e la sessione non sono interessate.
L'elenco completo, insieme alla scelta tra router e nessun router, si trova nella guida al router di Claude Code.
Domande frequenti
Come si installa Claude Code?
Su macOS, Linux o WSL esegui `curl -fsSL https://claude.ai/install.sh | bash`. Su Windows esegui `irm https://claude.ai/install.ps1 | iex` in PowerShell, oppure `curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd` in CMD. Il programma di installazione nativo è il metodo consigliato e si aggiorna automaticamente in background. Sono supportati anche Homebrew (`brew install --cask claude-code`), WinGet (`winget install Anthropic.ClaudeCode`), npm e i repository apt/dnf/apk firmati, ma nessuno di questi si aggiorna automaticamente per impostazione predefinita.
È necessario Node.js per installare Claude Code?
Non per il programma di installazione nativo, Homebrew, WinGet o i repository di pacchetti Linux: tutti installano un binario nativo che non usa Node durante l'esecuzione. Solo il percorso di installazione tramite npm richiede Node e, a partire da v2.1.198, quel pacchetto richiede Node.js 22 o versione successiva. Anche in questo caso npm installa semplicemente lo stesso binario nativo tramite una dipendenza opzionale specifica per piattaforma.
Quali sono i requisiti di sistema per Claude Code?
macOS 13.0+, Windows 10 1809+ o Windows Server 2019+, Ubuntu 20.04+, Debian 10+ oppure Alpine Linux 3.19+; almeno 4 GB di RAM su un processore x64 o ARM64; una connessione Internet; e Bash, Zsh, PowerShell o CMD come shell. Devi inoltre trovarti in un Paese supportato da Anthropic.
Come si accede a Claude Code per la prima volta?
Esegui `claude` in una directory di progetto e segui le istruzioni nel browser. Claude Code richiede un account Pro, Max, Team, Enterprise o Console: il piano gratuito Claude.ai non include l'accesso a Claude Code. Se la variabile d'ambiente ANTHROPIC_API_KEY è impostata, Claude Code ti chiede una volta di approvare quella chiave invece di aprire un browser.
Posso installare Claude Code su Windows senza WSL?
Sì. Esegui il programma di installazione PowerShell o CMD e avvia `claude` da qualsiasi terminale; non sono necessari i diritti di amministratore. Git for Windows è facoltativo ma consigliato, perché fornisce Git Bash, che supporta lo strumento Bash: senza di esso Claude Code esegue i comandi shell tramite lo strumento PowerShell. WSL 2 è l'opzione da scegliere se vuoi toolchain Linux o l'esecuzione di comandi in sandbox, che Windows nativo non supporta.
Perché dopo l'installazione `claude` restituisce «command not found»?
La directory di installazione non è inclusa nel PATH della shell che stai usando. Apri prima un nuovo terminale: il programma di installazione aggiunge ~/.local/bin su macOS e Linux, ma una sessione già aperta non lo rileverà. Esegui `claude doctor` per ottenere diagnostica di sola lettura dell'installazione e dei file delle impostazioni. Un'altra causa comune è una seconda installazione più vecchia o un alias shell rimasto.
Come posso indirizzare Claude Code a un endpoint API diverso?
Imposta ANTHROPIC_BASE_URL sull'origine di qualsiasi endpoint che esponga l'API Anthropic Messages: Claude Code la legge nativamente e aggiunge autonomamente /v1/messages, quindi non sono coinvolti plugin o proxy. Abbinala ad ANTHROPIC_AUTH_TOKEN per la credenziale e a un ANTHROPIC_MODEL esplicito, quindi fissa ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL e ANTHROPIC_DEFAULT_HAIKU_MODEL su modelli serviti dall'endpoint, perché altrimenti gli alias opus e sonnet seguono i modelli più recenti di Anthropic. Su Kunavo, questo esegue gli stessi modelli Claude a 30% in meno rispetto al prezzo di listino di Anthropic, con pagamento a consumo.
Prossimi passaggi
- Chiave API di Claude Code — dove ottenerla, dove inserirla e la mancata corrispondenza delle intestazioni alla base della maggior parte degli errori 401.
- Prezzi di Claude Code — abbonamento rispetto all'API, tariffe per modello e costo mensile.
- Claude Code è gratuito? — cosa è gratuito, cosa non lo è e dove passa il confine.
- Eseguirlo senza richieste di autorizzazione — cosa rimuove effettivamente
--dangerously-skip-permissionse tre contenimenti che richiedono circa un minuto ciascuno. - Claude Code rispetto a Codex CLI — se stai ancora scegliendo un agente da terminale.