Installare Claude Code su Windows, Mac e Linux: chiave API senza abbonamento e pagamento con Satispay

Per installare Claude Code basta un comando, diverso a seconda del terminale: la riga con install.sh su macOS, Linux e WSL, irm … | iex in PowerShell, la riga con install.cmd nel Prompt dei comandi. È il metodo che Anthropic consiglia; npm resta possibile ma vuole Node.js 22 o successivo. Il piano gratuito di Claude non comprende Claude Code, quindi serve un abbonamento Pro o superiore oppure una chiave API. Qui segui la seconda strada: ANTHROPIC_BASE_URL=https://api.kunavo.com (senza /v1), la chiave in ANTHROPIC_AUTH_TOKEN, tre variabili che fissano i modelli e /status per la verifica finale. Il credito si ricarica con Satispay in euro da $10 e paghi solo i token che consumi.

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

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

:: Windows – Prompt dei comandi (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Da dove vengono questi comandi: la documentazione di Claude Code esiste anche in italiano e l'abbiamo riletta il 3 ottobre 2026, in particolare le pagine su installazione e gateway LLM. Prezzi e metodi di pagamento di Kunavo sono aggiornati al 3 ottobre 2026. Anthropic serve l'Italia sia su Claude.ai sia con l'API (paesi supportati, letto il 3 ottobre 2026).

Cosa serve

I requisiti della documentazione ufficiale (letta il 3 ottobre 2026) sono bassi:

• macOS 13.0 o successivo; Windows 10 1809 o successivo, oppure Windows Server 2019 o successivo; Ubuntu 20.04+, Debian 10+ o Alpine Linux 3.19+.
• Almeno 4 GB di RAM e un processore x64 o ARM64. Windows a 32 bit è escluso.
• Una shell tra Bash, Zsh, PowerShell e CMD.
• Una connessione da un paese supportato da Anthropic: l'Italia lo è.
• Node.js solo se scegli npm, e in quel caso dalla versione 22 in su.

Quale comando, in quale terminale

Non servono i diritti di amministratore e non serve WSL: la documentazione ufficiale lo dice esplicitamente, anche se più di una guida in giro suggerisce il contrario. Una volta installato, Claude Code si aggiorna da solo in background. Chi preferisce un gestore di pacchetti può usare Homebrew o WinGet, sapendo che in quel caso gli aggiornamenti li lancia lui:

# Homebrew – canale stable; non si aggiorna da solo
brew install --cask claude-code

# WinGet (Windows) – non si aggiorna da solo
winget install Anthropic.ClaudeCode

Prima di provare, chiudi il terminale e aprine uno nuovo: solo una finestra nuova rilegge il PATH. Poi verifica. claude doctor tornerà utile anche più avanti, perché controlla installazione e impostazioni senza aprire una sessione e ti dice subito se il guasto è nell'una o nelle altre.

claude --version   # stampa la versione, ad esempio 2.1.211 (Claude Code)
claude doctor      # diagnostica di installazione e impostazioni, senza aprire una sessione

Download bloccato: 403 o pagina HTML al posto dello script

Quando lo script non arriva, il terminale non lo dice in modo chiaro: bash si lamenta con syntax error near unexpected token '<' (sta cercando di eseguire una pagina web), oppure curl si ferma su curl: (22) The requested URL returned error: 403. La pagina ufficiale sui problemi di installazione (in inglese, letta il 3 ottobre 2026) distingue due casi. Se la pagina scaricata dice App unavailable in region, il server crede che ti colleghi da un paese escluso: dall'Italia capita quasi sempre per una VPN o un proxy che esce all'estero. Un 403 senza testo arriva più spesso da un proxy aziendale o da un firewall. Cambiare metodo di installazione non aiuta, perché Homebrew e WinGet scaricano dagli stessi server: prova da un'altra rete oppure chiedi all'IT di sbloccare quei domini.

Con npm: Node.js 22, non 18

Se Node.js lo usi già tutti i giorni, npm sembra la scelta naturale. Funziona ed è tra i metodi documentati, con una condizione che molte guide in italiano non hanno aggiornato: ci vuole Node.js 22 o successivo. Con un Node più vecchio vedrai l'avviso EBADENGINE, però l'installazione arriva in fondo e claude parte lo stesso (documentazione ufficiale, letta il 3 ottobre 2026). Le versioni aggiornate di Node sono su nodejs.org.

node -v                                    # serve v22 o successiva
npm install -g @anthropic-ai/claude-code   # senza sudo

# aggiornamento: @latest, non npm update -g
npm install -g @anthropic-ai/claude-code@latest

Tre abitudini da evitare:

• sudo davanti a npm install -g. La documentazione lo sconsiglia, sia per i permessi che si incastrano sia per la sicurezza.
• npm update -g per aggiornare. Ripeti invece l'installazione con @latest, come nell'ultima riga qui sopra.
• Saltare le dipendenze facoltative. Il binario di Claude Code arriva proprio come dipendenza facoltativa, un pacchetto @anthropic-ai/claude-code-* per ogni piattaforma. Con --omit=optional, o con optional=false nel file .npmrc, non viene scaricato e su macOS o Linux claude risponde claude native binary not installed (problemi di installazione, in inglese, letta il 3 ottobre 2026).

Claude Code su Windows: dove ci si inceppa

Su Windows Claude Code gira in modo nativo, e l'installazione in sé è la parte facile. I problemi nascono dall'ambiente. Il primo è il terminale: se incolli in PowerShell la riga per CMD, PowerShell protesta per il &&; se incolli in CMD la riga per PowerShell, CMD non sa cosa sia irm; e la riga curl … | bash del Mac in PowerShell non funziona proprio. Su un Windows in italiano alcuni di questi messaggi possono comparire tradotti. In ogni caso la soluzione è tornare alla tabella qui sopra e prendere la riga del terminale che hai davanti (i messaggi in inglese sono nella tabella degli errori in fondo; fonte: documentazione, letta il 3 ottobre 2026).

Occhio anche al menu Start: “Windows PowerShell (x86)” apre un processo a 32 bit e Claude Code si ferma con Claude Code does not support 32-bit Windows, anche se il PC è a 64 bit. Scegli la voce senza (x86).

Git for Windows non è obbligatorio. Se è installato, Claude Code esegue i comandi attraverso Git Bash; se manca, usa PowerShell. Quando Git c'è ma Claude Code non trova bash.exe, indicagli il percorso con CLAUDE_CODE_GIT_BASH_PATH nel blocco env di ~/.claude/settings.json, di solito C:\Program Files\Git\bin\bash.exe. E WSL? Serve solo in un caso preciso:

Con WSL tutto succede dentro Linux: la riga install.sh va eseguita nella shell di WSL, e da lì lanci claude.

“claude” non viene trovato

Se dopo l'installazione il terminale risponde command not found: claude oppure 'claude' is not recognized, il programma c'è ma la sua cartella non è nel PATH. L'installer nativo lo copia in ~/.local/bin/claude su macOS e Linux e in %USERPROFILE%\.local\bin\claude.exe su Windows. Primo tentativo: un terminale nuovo. Se su Windows non basta, questi sono i comandi PowerShell della documentazione per controllare e aggiungere la cartella al PATH dell'utente:

# 1. Controlla se la cartella di installazione è già nel PATH
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Nessun risultato? Aggiungila al PATH utente, poi chiudi e riapri il terminale
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. Nel nuovo terminale
claude --version

npm.ps1 cannot be loaded in PowerShell

Riguarda solo chi installa con npm: i criteri di esecuzione (execution policy) di PowerShell bloccano lo script .ps1 che npm crea, e il messaggio completo contiene running scripts is disabled on this system. La documentazione indica tre uscite: permettere all'utente corrente di eseguire script locali con il comando qui sotto, lanciare npm.cmd e claude.cmd al posto degli script PowerShell, oppure lasciare perdere npm e usare l'installer nativo.

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Senza abbonamento: account Claude o chiave API

Installato non vuol dire pronto: al primo avvio Claude Code chiede di autenticarsi, e il piano gratuito di Claude.ai non basta (documentazione, letta il 3 ottobre 2026). Le due strade a confronto:

Esiste anche la chiave della Console di Anthropic, sempre a consumo. Lì però i crediti prepagati scadono dopo un anno e non si rimborsano (assistenza Anthropic, letto il 3 ottobre 2026); si paga con carta, mentre il bonifico ACH è riservato agli account API con fatturazione mensile (assistenza Anthropic). Il credito Kunavo non ha scadenza.

Configurare la chiave API: cinque variabili

Che Claude Code parli con un endpoint diverso da quello di Anthropic è previsto: la documentazione ufficiale ha una pagina, tradotta anche in italiano, su come collegarlo a un gateway LLM. Nessun plugin, nessuna versione modificata. Bastano queste variabili:

Su macOS e Linux aggiungile in fondo a ~/.zshrc o ~/.bashrc:

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # solo il dominio, senza /v1
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

Su Windows, per una prova al volo che dura quanto la finestra di PowerShell:

# Vale solo in questa finestra di PowerShell: chiusa la finestra, sparisce
$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"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "claude-haiku-4-5"
claude

Per non doverle reimpostare ogni volta, la sede giusta è il blocco env di ~/.claude/settings.json (su Windows %USERPROFILE%\.claude\settings.json): vale per tutti i tuoi progetti. Se il file contiene già altre impostazioni, aggiungi solo 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",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

AUTH_TOKEN o API_KEY?

Kunavo legge la chiave da tutti e due gli header, Authorization: Bearer e x-api-key, quindi in teoria vanno bene entrambe le variabili. La differenza la fa Claude Code. Con ANTHROPIC_API_KEY, inviata come x-api-key, la sessione interattiva ti chiede una volta se approvare la chiave; se rispondi no, la ignora senza dire nulla finché non la riattivi da /config → Use custom API key. ANTHROPIC_AUTH_TOKEN non chiede niente, ed è anche la variabile che la documentazione sui gateway (letta il 3 ottobre 2026) suggerisce quando non sai quale scegliere.

Perché fissare i modelli

Senza variabili Claude Code ragiona per alias, e gli alias seguono le uscite di Anthropic. Oggi, secondo la documentazione sulla configurazione dei modelli (letta il 3 ottobre 2026), per chi usa l'API opus corrisponde a Opus 5.5 e sonnet a Sonnet 5.5. Kunavo, al 3 ottobre 2026, non offre Sonnet 5.5: senza ANTHROPIC_MODEL la richiesta andrebbe a un modello che non c'è e tornerebbe 404. Opus 5.5 invece è disponibile, e fissare anche opus serve a un'altra cosa: evitare che modello e tariffa cambino da un giorno all'altro quando l'alias passerà a un Opus successivo. Se preferisci Opus 5.5, scrivi claude-opus-5-5 in ANTHROPIC_DEFAULT_OPUS_MODEL: costa $2,80 / $14,00 per milione di token, contro $3,50 / $17,50 di Claude Opus 5. E se cambi modello con /model sonnet, aggiungi ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5.

Le tariffe Kunavo dei tre modelli della configurazione, per milione di token (input / output): Claude Sonnet 5 $1,40 / $7,00 (listino Anthropic: $2,00 / $10,00); Claude Opus 5 $3,50 / $17,50; Claude Haiku 4.5 $0,70 / $3,50, che lavora anche dietro le quinte.

Dove non metterla, e quale impostazione vince

Il .claude/settings.json dentro il progetto viene committato: una chiave scritta lì finisce nel repository e arriva a chiunque lo cloni (documentazione sui gateway). Se una variabile compare sia nella shell sia nel blocco env di un file di impostazioni, prevale il file: quando una modifica a ~/.zshrc sembra ignorata, il motivo è quasi sempre lì. Il campo model del file di impostazioni, invece, cede il passo ad ANTHROPIC_MODEL. Nell'estensione di Claude Code per VS Code le stesse variabili vanno in claudeCode.environmentVariables, nelle impostazioni utente di VS Code. L'app desktop di Claude resta fuori da tutto questo: non legge né ANTHROPIC_BASE_URL né settings.json (documentazione sui gateway, letta il 3 ottobre 2026).

Primo avvio e controllo con /status

Se la chiave è al suo posto, claude parte senza schermata di accesso: restano solo la configurazione iniziale e la domanda se ti fidi della cartella. Se invece compare il login, Claude Code non ha trovato la chiave. Il caso tipico è la chiave scritta solo nel .claude/settings.json o nel .claude/settings.local.json del progetto: in modalità interattiva quel blocco env entra in gioco solo dopo la configurazione iniziale e la conferma di fiducia (documentazione sui gateway, letta il 3 ottobre 2026), quindi al primo avvio non c'è ancora. Spostala nella shell o nel file utente. Un vecchio login Pro o Max non dà fastidio, perché la variabile ha la precedenza sull'accesso salvato; se vuoi cancellarlo, c'è /logout.

Dentro la sessione digita /status. Le righe che contano sono due:

• Anthropic base URL, che appare solo quando è impostato un gateway: deve dire https://api.kunavo.com. Se non c'è, ANTHROPIC_BASE_URL non è arrivata alla sessione.
• Auth token con il nome ANTHROPIC_AUTH_TOKEN: stai usando la chiave. Se al suo posto trovi Login method con un account claude.ai, la variabile è stata ignorata.

Vuoi controllare prima ancora di aprire Claude Code? La documentazione propone una richiesta minima, con 1 token di output, che scala dal credito un importo trascurabile. Il comando legge le variabili della shell corrente: se la chiave sta solo in settings.json, esportala prima in questo terminale. Se torna un JSON che comincia con {"id":"msg_ sei a posto; 401 vuol dire chiave rifiutata.

curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-5", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

In PowerShell la stessa prova è questa, e la risposta buona contiene un id che inizia con msg_:

Invoke-RestMethod -Method Post -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `
  -Headers @{ "Authorization" = "Bearer $env:ANTHROPIC_AUTH_TOKEN"; "anthropic-version" = "2023-06-01" } `
  -ContentType "application/json" `
  -Body '{"model": "claude-sonnet-5", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

Cosa perdi con la chiave API

• Remote Control e dettatura vocale. Vogliono un'identità claude.ai e non funzionano con ANTHROPIC_AUTH_TOKEN o ANTHROPIC_API_KEY; dalla versione 2.1.196 Remote Control si spegne anche quando ANTHROPIC_BASE_URL punta a un host che non è di Anthropic.
• La modalità /fast. Con il solo token bearer Claude Code la considera disattivata e non prova nemmeno a chiedere.
• La ricerca degli strumenti MCP, all'inizio. Con un ANTHROPIC_BASE_URL personalizzato parte spenta (documentazione MCP, in inglese, letta il 3 ottobre 2026). Si riaccende con ENABLE_TOOL_SEARCH=true se il gateway inoltra i blocchi tool_reference; con Kunavo non l'abbiamo provato.
• La precisione di /context. Kunavo non espone /v1/messages/count_tokens, un endpoint facoltativo secondo la specifica dei gateway (letta il 3 ottobre 2026); senza, Claude Code stima i token a partire dai caratteri.

Per approfondire, in inglese: la documentazione dell'integrazione con Claude Code, la pagina sui casi limite di ANTHROPIC_BASE_URL e la guida Install Claude Code.

Pagare con Satispay, senza carta di credito

Prima una precisazione, perché è la domanda più frequente: Satispay non paga l'abbonamento Claude. Per Pro e Max comprati sul web Anthropic accetta solo carte di credito o di debito (assistenza Anthropic) e non accetta PayPal (assistenza Anthropic), entrambi letti il 3 ottobre 2026. Su Kunavo Satispay ricarica invece il credito API che Claude Code consuma con la chiave configurata sopra. Tutti i dettagli, compresi i costi per caricare la Disponibilità, sono nella guida pagare Claude con Satispay. Per Claude Code la sequenza è questa:

1. Registrati su Kunavo con l'email o con un account Google: nessuna carta richiesta.
2. Apri Billing e scegli quanto ricaricare: minimo $10, nessun canone. Sopra certe soglie c'è un bonus: $100 diventano $110, $1.000 diventano $1.200, $5.000 diventano $6.250 di credito.
3. Nel checkout di Stripe, che mostra l'importo in euro, scegli Satispay. Si passa alla pagina di Satispay (documentazione Stripe): numero di cellulare o QR code dall'app, poi conferma con Invia (assistenza Satispay, letto il 3 ottobre 2026). Meglio avere già abbastanza Disponibilità prima di cominciare.
4. Il credito compare in Billing appena Stripe conferma il pagamento. Se non lo vedi subito, aggiorna la pagina invece di pagare di nuovo: un secondo pagamento si somma al credito, non sostituisce il primo.
5. In Chiavi API genera la chiave sk-kn-… e copiala subito in ANTHROPIC_AUTH_TOKEN: viene mostrata una volta sola.

Kunavo fissa i prezzi in dollari e Stripe li converte in euro con una commissione di cambio del 2–4% a carico di chi paga (Stripe, Adaptive Pricing, letto il 3 ottobre 2026): sulla ricarica minima da $10 sono tra $0,20 e $0,40. In dollari la commissione sparisce, ma sparisce anche Satispay, che esiste solo nel checkout in euro; se il checkout ti appare in dollari, spesso c'entra una VPN. L'importo esatto in euro è quello che leggi nel checkout prima di confermare.

Con Satispay le ricariche si fanno a mano: la ricarica automatica di Kunavo addebita solo una carta salvata o Link. Chi ha la carta Satispay, una Mastercard di debito per i piani Plus, Metal e Velvet (assistenza Satispay, letto il 3 ottobre 2026), può salvarla e usarla come qualsiasi carta. Il credito non scade e le richieste fallite non vengono addebitate. Kunavo non emette fatture, né con IVA né elettroniche via SDI; lo storico delle ricariche resta in Billing.

Una nota onesta: Satispay è nel checkout di Kunavo dal 3 ottobre 2026 e Stripe lo propone nei pagamenti in euro, ma nessuna ricarica è ancora passata da lì. Se non lo trovi, carta, Apple Pay, Google Pay e Link fanno lo stesso lavoro.

Quanto costa una sessione di lavoro

Con la chiave API il costo sta nei token, e Claude Code ne manda parecchi: a ogni passaggio rispedisce l'intero contesto. La parte che non cambia, però, può essere letta dalla cache a una tariffa molto più bassa. Ecco un esempio costruito a tavolino, con le ipotesi in chiaro: non è una misura e non è un tetto di spesa.

• 40.000 token di input per richiesta, di cui 36.000 (90%) letti dalla cache e 4.000 scritti in cache;
• 1.000 token di output per richiesta;
• 50 richieste in una sessione, senza contare le chiamate a Claude Haiku 4.5 in background;
• lettura dalla cache al 10% della tariffa di input e scrittura a 1,25× la tariffa di input: sono i rapporti Kunavo per Claude Sonnet 5, e ogni riga della tabella usa quelli del proprio modello.

Contesti lunghi, poche letture dalla cache e risposte prolisse fanno salire il conto; un /clear tra un compito e l'altro lo fa scendere. Se ti conviene di più l'abbonamento o l'API lo trovi in quanto costa Claude Code; le tariffe di tutti i modelli Claude sono in prezzi dell'API di Claude e nella pagina prezzi. Per rifare il conto con i tuoi numeri c'è il calcolatore dei costi dei token di Claude (in inglese).

Errori: messaggio, causa, rimedio

Cosa questa configurazione non fa

• Non attiva un abbonamento Claude Pro o Max: il credito Kunavo paga l'API e Claude Code con chiave, non claude.ai né l'app di Claude.
• Non produce fatture: né con IVA né elettroniche via SDI.
• Non ricarica da sola con Satispay: la ricarica automatica vuole una carta salvata o Link.
• Non funziona senza le variabili dei modelli finché Kunavo non offre Sonnet 5.5 (situazione al 3 ottobre 2026): l'alias sonnet darebbe 404.
• Non ha documentazione Kunavo in italiano: la guida all'integrazione e la pagina su saldo e pagamenti sono in inglese, mentre quella di Anthropic su Claude Code è tradotta.

Per il quadro generale di chi sviluppa con Claude dall'Italia c'è la guida all'API di Claude in Italia. Da dove partire: crea l'account, ricarica $10 con Satispay, imposta le cinque variabili e controlla con /status.

Domande frequenti