Installare Claude Code: il comando per Windows, macOS e Linux — e come usarlo senza abbonamento

Per installare Claude Code basta un comando: 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 (nel Prompt dei comandi, CMD, usa la riga di install.cmd più sotto). Poi apri un nuovo terminale, verifica con claude --version ed esegui claude per iniziare. Al primo collegamento hai due possibilità: accedere con un account Pro, Max, Team, Enterprise o Console (il piano gratuito di Claude.ai non include Claude Code) oppure definire due variabili d'ambiente, ANTHROPIC_BASE_URL e ANTHROPIC_AUTH_TOKEN, e usare una chiave API a consumo, senza alcun abbonamento.

Comandi verificati il 11 settembre 2026 nella documentazione ufficiale di installazione di Anthropic.

Prima dell'installazione

Installazione su macOS e Linux

Apri il Terminale e incolla:

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash

È il metodo consigliato: installa un binario indipendente che si aggiorna automaticamente in background. Il collegamento si trova in ~/.local/bin/claude e un terminale già aperto non rileva il nuovo PATH: perciò apri un'altra finestra prima di eseguire il test. In WSL il comando è lo stesso.

Installazione su Windows

Su Windows esistono due righe diverse e l'unica differenza è il terminale in uso. Se il prompt inizia con PS C:\Users\SeuNome>, è PowerShell; senza PS, con solo C:\Users\SeuNome>, è il Prompt dei comandi (CMD). Non è necessario eseguire il comando come amministratore.

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

:: Windows Prompt de Comando (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Incollare la riga nel terminale sbagliato è l'errore più comune. La riga CMD in PowerShell restituisce The token '&&' is not a valid statement separator; quella di PowerShell in CMD restituisce 'irm' is not recognized as an internal or external command (su Windows in portoghese, “não é reconhecido como um comando interno ou externo”). Inoltre, incollando curl … | bash da macOS in PowerShell si ottiene A parameter cannot be found that matches parameter name 'fsSL'. In tutti e tre i casi basta usare la riga corretta.

Installare Git for Windows è facoltativo, ma consigliato: Claude Code usa Git Bash, incluso nel pacchetto, per eseguire i comandi; in sua assenza usa PowerShell. Se Git è installato ma Git Bash non viene comunque trovato, definisci CLAUDE_CODE_GIT_BASH_PATH nel blocco env delle impostazioni, indicando bash.exe.

In WSL, esegui la riga macOS/Linux all'interno del terminale WSL e apri claude direttamente lì, non da PowerShell né da CMD.

Tramite il gestore di pacchetti

Funziona, con una differenza importante: nessuno di questi si aggiorna automaticamente per impostazione predefinita. Devi aggiornarli manualmente (brew upgrade claude-code, winget upgrade Anthropic.ClaudeCode). Sono disponibili anche repository apt, dnf e apk firmati per Debian/Ubuntu, Fedora/RHEL e Alpine.

# Homebrew (macOS, Linux) — canal stable
brew install --cask claude-code

# WinGet (Windows)
winget install Anthropic.ClaudeCode

# npm — exige Node.js 22 ou mais novo; nunca com sudo
npm install -g @anthropic-ai/claude-code

Tramite npm, dalla versione 2.1.198 il pacchetto richiede Node.js 22 o una versione successiva; con una versione obsoleta di Node, npm mostra solo un avviso EBADENGINE e l'installazione termina. Il pacchetto installa lo stesso binario nativo, che non usa Node.js per funzionare. Non usare mai sudo npm install -g: causa problemi di autorizzazioni e rappresenta un rischio per la sicurezza.

Verifica dell'installazione

claude --version   # imprime a versão, por exemplo 2.1.211 (Claude Code)
claude doctor      # diagnóstico da instalação e das configurações, sem abrir sessão

Conserva claude doctor: senza aprire una sessione, mostra lo stato dell'installazione, gli errori nei file di configurazione e la correzione suggerita; è il modo più rapido per capire se il problema riguarda l'installazione o la configurazione.

Se compare command not found: claude (oppure, su Windows, che claude non è riconosciuto), la cartella di installazione non è nel PATH. Su macOS e Linux apri un nuovo terminale; se non basta, aggiungi ~/.local/bin al PATH in ~/.zshrc o in ~/.bashrc. Su Windows la cartella è %USERPROFILE%\.local\bin; verifica e aggiungila tramite PowerShell:

# 1. Veja se a pasta de instalação já está no PATH
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Sem saída? Adicione ao PATH do usuário e abra um terminal novo
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. No terminal novo: se houver duas instalações, aparecem dois caminhos
where.exe claude

Primo collegamento: abbonamento o chiave API

Percorso A — accesso con abbonamento

Nella cartella del progetto, esegui claude e completa l'accesso nel browser con un account Pro, Max, Team, Enterprise o Console. Un dettaglio che spesso crea confusione: se la variabile ANTHROPIC_API_KEY è già definita, Claude Code chiede una volta se deve usare quella chiave. Se rifiuti, la ignora silenziosamente e non lo chiede più: sembra che la variabile non venga letta. Per riattivarla, vai a /config → Use custom API key.

Percorso B — senza abbonamento, con chiave a consumo

Claude Code legge nativamente ANTHROPIC_BASE_URL, quindi indirizzarlo verso qualsiasi endpoint dell'Anthropic Messages API è una configurazione supportata: senza plugin, proxy o binario modificato. Procedura: crea l'account, ricarica il saldo (minimo $10), genera una chiave sk-kn- nel pannello delle chiavi (viene mostrata una sola volta) e definisci le variabili. Su macOS e Linux:

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # só o domínio, sem /v1
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-5

Su Windows, per eseguire un test in una finestra di PowerShell:

# Vale só para esta janela do PowerShell
$env:ANTHROPIC_BASE_URL = "https://api.kunavo.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-kn-..."
$env:ANTHROPIC_MODEL = "claude-sonnet-5"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL = "claude-opus-5-5"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL = "claude-sonnet-5"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "claude-haiku-4-5"
claude

Per renderle permanenti, il posto migliore è il blocco env del file delle impostazioni dell'utente, ~/.claude/settings.json (su Windows, %USERPROFILE%\.claude\settings.json). Qui le variabili valgono per qualsiasi terminale, per l'estensione dell'editor e per i processi in background. Se il file contiene già altre impostazioni, aggiungi soltanto il blocco env:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.kunavo.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-kn-...",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

Ognuna di queste righe nasconde un'insidia:

• ANTHROPIC_BASE_URL deve contenere solo il dominio. Claude Code aggiunge /v1/messages; con /v1 alla fine, la richiesta viene inviata a /v1/v1/messages e restituisce 404.
• Usa ANTHROPIC_AUTH_TOKEN, non ANTHROPIC_API_KEY. Vengono inviati in intestazioni HTTP diverse: il primo invia Authorization: Bearer ed è valido immediatamente; il secondo invia x-api-key e richiede anche l'approvazione una tantum descritta sopra.
• Inserisci il nome esatto del modello in ANTHROPIC_MODEL. Kunavo riconosce solo il nome identico e non traduce i nomi precedenti con la data nel suffisso.
• Fissa anche ANTHROPIC_DEFAULT_OPUS_MODEL e ANTHROPIC_DEFAULT_SONNET_MODEL. Il modello predefinito di Claude Code e l'alias opus puntano all'Opus più recente e, se Kunavo non lo offre ancora, la prima richiesta restituisce 404. L'alias sonnet richiede già Sonnet 5.5, che Kunavo non offre: senza fissarlo, /model sonnet, la fase di esecuzione di opusplan e i subagenti con model: sonnet ricevono 404. L'alias opus è fissato su Opus 5.5 (claude-opus-5-5), che richiede Claude Code v2.1.280 o successivo; in un'installazione precedente, esegui claude update.
• E imposta ANTHROPIC_DEFAULT_HAIKU_MODEL. L'alias haiku richiede un ID che Kunavo non offre (Haiku 5.5 dalla v2.1.293): senza impostarlo, /model haiku e i subagenti con model: haiku restituiscono 404. La stessa riga sposta dal modello principale le chiamate in background che Claude Code esegue autonomamente (riepiloghi e titoli).

Non inserire mai la chiave nel .claude/settings.json del progetto: questo file finisce in git e nelle mani di chi clona il repository. Nell'estensione VS Code, le variabili si trovano in claudeCode.environmentVariables, nelle impostazioni utente di VS Code, perché l'estensione verifica la credenziale prima di avviarsi.

Tariffe per 1M di token, lette dal catalogo:

Per cambiare modello durante la sessione, usa /model con il nome completo (ad esempio /model claude-opus-5-5) oppure avvia Claude Code con claude --model claude-opus-5-5. Il costo di un mese di utilizzo e quando conviene di più l'abbonamento sono illustrati nella guida ai prezzi di Claude Code.

Come capire quale percorso è attivo

All'interno di Claude Code, esegui /status. Una riga Auth token significa che la chiave è attiva; una riga Login method con un account claude.ai significa che la variabile non è stata letta. Le due modalità non si sommano: con la variabile definita, l'abbonamento resta inattivo; rimuovendo la variabile, torna a essere usato senza reinstallare.

Dietro un gateway cambiano tre cose: Remote Control e dettatura vocale non funzionano (richiedono l'identità di claude.ai); /fast può indicare che la modalità rapida non è disponibile, perché il controllo viene eseguito direttamente su Anthropic, ma le richieste normali non cambiano; e i numeri di /context diventano stime locali. Codice, strumenti, sottoagenti, MCP, hook e caching dei prompt funzionano allo stesso modo. I dettagli sono nella documentazione dell'integrazione (in inglese).

Pagare dal Brasile — Pix al checkout

L'abbonamento a claude.ai è un addebito ricorrente in dollari che richiede una carta internazionale abilitata agli acquisti all'estero. Nel percorso con chiave API, la ricarica passa dal checkout di Stripe e Pix compare come metodo di pagamento per chi paga dal Brasile: il prezzo è in USD e Stripe mostra l'importo convertito in real prima della conferma. Nel checkout compaiono anche carte internazionali (Visa, Mastercard, American Express), Apple Pay, Google Pay e Link. Il portafoglio è prepagato — ricarica minima di $10, saldo che non scade, le richieste non riuscite non vengono addebitate — e ogni chiave può avere un limite mensile di spesa. La procedura dettagliata, schermata per schermata, è disponibile in come pagare l'API con Pix.

Errori comuni

Dopo l'installazione

Al primo utilizzo, esegui /init all'interno del progetto: Claude Code legge il repository e genera un CLAUDE.md con i comandi di test e le convenzioni che trova. Controlla questo file e mantienilo breve: viene caricato in ogni sessione. Tra attività non correlate, /clear avvia una nuova conversazione; per un'attività diventata lunga, /compact riassume la cronologia e prosegue.

Parlando con franchezza della scelta: per chi usa Claude Code molte ore al giorno, il canone mensile dell'abbonamento tende a costare meno; il pagamento a consumo conviene quando l'utilizzo varia o quando non vuoi essere vincolato alla finestra di 5 ore, e un mese senza utilizzo costa zero. Con Kunavo utilizzi capacità condivisa, senza quota dedicata né SLA contrattuale; chi ha bisogno di queste garanzie deve rivolgersi direttamente ad Anthropic.

Domande frequenti