Come installare Claude Code su Windows, macOS e Linux — e 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, irm https://claude.ai/install.ps1 | iex in PowerShell (nel Prompt dei comandi, CMD, usa la riga install.cmd riportata più sotto). Poi apri un nuovo terminale, verifica con claude --version, entra nella cartella del progetto ed esegui claude; il primo comando utile è /init. Per connetterti 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 abbonamento.

Comandi verificati il 11 settembre 2026 con la documentazione ufficiale di Anthropic per l'installazione.

Requisiti

Installare 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 autonomo che si aggiorna automaticamente in background. L'eseguibile viene salvato in ~/.local/bin/claude e un terminale già aperto non vede il nuovo PATH, quindi apri un'altra finestra prima di provare. In WSL il comando è lo stesso.

Installare Claude Code su Windows

Su Windows esistono due righe diverse e cambia solo il terminale. Se il prompt inizia con PS C:\Users\TuNombre>, sei in PowerShell; senza PS, con solo C:\Users\TuNombre>, sei nel Prompt dei comandi (CMD). Non è necessario eseguirlo come amministratore.

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

:: Windows Símbolo del sistema (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. Quella di 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 (in un Windows in italiano, «non è riconosciuto come comando interno o esterno»); e il curl … | bash di macOS incollato in PowerShell restituisce A parameter cannot be found that matches parameter name 'fsSL'. In tutti e tre i casi basta usare la riga corrispondente.

Installare Git for Windows è facoltativo ma consigliato: Claude Code usa Git Bash per eseguire i comandi e, in sua assenza, usa PowerShell. Se Git è installato ma Git Bash non viene comunque trovato, definisci CLAUDE_CODE_GIT_BASH_PATH nel blocco env della configurazione, indicando il percorso di bash.exe.

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

Con un gestore di pacchetti

Funziona anche in questo modo, con una differenza importante: nessuno si aggiorna automaticamente per impostazione predefinita (dovrai eseguire brew upgrade claude-code o winget upgrade Anthropic.ClaudeCode). Esistono inoltre 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 — requiere Node.js 22 o posterior; nunca con sudo
npm install -g @anthropic-ai/claude-code

Con npm, dalla versione 2.1.198 il pacchetto richiede Node.js 22 o versioni successive; con un Node meno recente npm mostra solo un avviso EBADENGINE e l'installazione termina. 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.

Verificare l'installazione

claude --version   # imprime la versión, por ejemplo 2.1.211 (Claude Code)
claude doctor      # diagnóstico de la instalación y la configuración, sin abrir sesión

Mantieni claude doctor: senza effettuare l'accesso, mostra lo stato dell'installazione, gli errori nei file di configurazione e la soluzione suggerita. È il modo più rapido per capire se il problema riguarda l'installazione o la configurazione.

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

# 1. Comprueba si la carpeta de instalación ya está en el PATH
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. ¿Sin salida? Añádela al PATH de usuario y abre una terminal nueva
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. En la terminal nueva: si hay dos instalaciones, verás dos rutas
where.exe claude

Prima connessione: abbonamento o chiave API

Opzione A — accedere con il proprio 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 può confondere: se la variabile ANTHROPIC_API_KEY è già definita, Claude Code ti chiede una sola volta se vuoi usare quella chiave. Se rispondi di no, da quel momento la ignora senza chiedertelo di nuovo e sembra che la variabile non venga letta. Per riattivarla: /config → Use custom API key.

Opzione B — senza abbonamento, con una chiave a consumo

Claude Code legge nativamente ANTHROPIC_BASE_URL, quindi indirizzarlo verso qualsiasi endpoint dell'Anthropic Messages API è una configurazione supportata: nessun plugin, nessun proxy e nessun binario modificato. I passaggi: crea l'account, ricarica il saldo (minimo $10), genera una chiave sk-kn- nel pannello delle chiavi (viene mostrata una sola volta) e aggiungi questo blocco env alla configurazione dell'utente, ~/.claude/settings.json (su Windows, %USERPROFILE%\.claude\settings.json). In questo modo sarà disponibile in tutti i terminali, nell'estensione dell'editor e nei processi in background:

{
  "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"
  }
}

Per provare prima in una sola finestra di PowerShell:

# Solo para esta ventana de PowerShell (en macOS/Linux: export VARIABLE=valor)
$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

• ANTHROPIC_BASE_URL contiene 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 e funziona immediatamente; il secondo invia x-api-key e passa inoltre attraverso l'approvazione una tantum indicata sopra.
• Inserisci il nome esatto del modello in ANTHROPIC_MODEL. Kunavo riconosce solo il nome identico e non traduce i nomi precedenti con data.
• Imposta anche ANTHROPIC_DEFAULT_OPUS_MODEL. Il modello predefinito di Claude Code e il relativo alias opus puntano all'Opus più recente e, se Kunavo non lo offre ancora, la prima richiesta restituisce un 404. Qui l'alias opus viene fissato su Claude Opus 5.5 (claude-opus-5-5), che richiede Claude Code v2.1.280 o successivo; con una versione precedente, esegui claude update.
• E anche ANTHROPIC_DEFAULT_SONNET_MODEL. L'alias sonnet richiede Sonnet 5.5, che Kunavo non offre: senza questa variabile, /model sonnet, la fase di esecuzione di opusplan e i sottoagenti configurati con sonnet restituiscono un 404. Impostarla su claude-sonnet-5 evita il problema.
• Lo stesso vale per ANTHROPIC_DEFAULT_HAIKU_MODEL. L'alias haiku richiede un ID che Kunavo non offre (Haiku 5.5 dalla v2.1.293): senza questa variabile, /model haiku e i subagenti impostati su haiku restituiscono 404. Impostarla su claude-haiku-4-5 evita il problema e sposta inoltre 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: quel file viene inviato al repository. Nell'estensione VS Code, le variabili vanno in claudeCode.environmentVariables, nella configurazione utente di VS Code, perché l'estensione verifica le credenziali prima di avviarsi.

Tariffe per 1M di token, lette dal catalogo:

Come sapere quale opzione è attiva

All'interno di Claude Code, esegui /status. Una riga Auth token significa che la chiave è in uso; una riga Login method con un account claude.ai significa che la variabile non è stata letta. Non si sommano: finché la variabile esiste, l'abbonamento resta sospeso; rimuovila e Claude Code torna all'abbonamento, senza reinstallare.

Dietro un gateway cambiano tre cose: Remote Control e la dettatura vocale non sono disponibili (richiedono l'identità di claude.ai); /fast può indicare che la modalità rapida non è disponibile, perché quel controllo passa direttamente da Anthropic, anche se le richieste normali non cambiano; e i valori di /context diventano stime locali. Il codice, gli strumenti, i sottoagenti, MCP, gli hook e il prompt caching funzionano allo stesso modo. Tutti i dettagli sono nella documentazione dell'integrazione e nella guida alle chiavi API di Claude Code (entrambe in inglese).

Come usare Claude Code: primi passi

# 1. Arranca siempre dentro de la carpeta del proyecto
cd ~/proyectos/mi-app
claude

# 2. Primer comando: lee el repositorio y genera CLAUDE.md
> /init

# 3. Pide las tareas en español y con la ruta del archivo
> cambia la validación de src/api/user.ts a zod y arregla los tests

# 4. Para tareas que tocan muchos archivos: Shift+Tab activa el modo plan

Claude Code chiede l'autorizzazione prima di modificare un file o eseguire un comando; se prende una direzione sbagliata, premi Esc per interromperlo e /rewind per tornare a un punto precedente. Il CLAUDE.md generato da /init è una bozza: inserisci solo ciò che ripeteresti in ogni sessione (comandi di test, convenzioni, cartelle da non modificare). Viene caricato in ogni sessione e inviato in ogni richiesta, e Anthropic consiglia di non superare 200 righe.

• Cambiare modello: /model seguito dal nome completo, ad esempio /model claude-opus-5, oppure avvia con claude --model claude-opus-5. Fallo tra un'attività e l'altra: ogni modello ha una propria cache e cambiare a metà attività costringe a rileggere l'intera conversazione senza cache.
• /clear tra attività non correlate. Inizia una nuova conversazione: non costa nulla; quella precedente può essere recuperata con /resume.
• /compact quando un'attività si prolunga: riassume la cronologia e continua. Con una chiave API la cache dura cinque minuti per impostazione predefinita, quindi compatta prima di una pausa lunga, non dopo.
• Quanto costa una sessione: /usage mostra i token, ma l'importo calcolato è una stima locale al prezzo di listino Anthropic; con Kunavo, l'addebito effettivo è nella tua pagina dell'utilizzo.

Pagamenti e trasparenza sulla scelta

Il saldo è prepagato tramite Stripe: carta (Visa, Mastercard, American Express, JCB, UnionPay), Apple Pay, Google Pay o Link; l'addebito diretto SEPA non è disponibile. La ricarica minima è di $10, il saldo non scade, le richieste non riuscite non vengono addebitate e ogni chiave prevede un limite di spesa mensile. Tutte le tariffe sono nella pagina dei prezzi.

Se usi Claude Code molte ore al giorno, il costo fisso di un abbonamento è spesso più conveniente; il pagamento a consumo conviene quando l'utilizzo è irregolare o non vuoi dipendere dalla finestra di 5 ore, e un mese senza attività costa zero. Il confronto completo, in inglese, è disponibile in Claude Code pricing. Tramite Kunavo utilizzi capacità condivisa, senza quota dedicata né SLA contrattuale: se hai bisogno di queste garanzie, stipula un contratto direttamente con Anthropic.

Domande frequenti