Come installare Claude Code su Windows, macOS e Linux: chiave API senza abbonamento e pagamento con BLIK

Claude Code si installa con un unico comando ufficiale (di seguito trovi le versioni per macOS e Linux, PowerShell e CMD). Anthropic consiglia l'installer nativo, mentre npm è un'alternativa che richiede Node.js 22 o versione successiva. Senza un abbonamento Pro/Max e senza effettuare l'accesso, è sufficiente impostare ANTHROPIC_BASE_URL=https://api.kunavo.com (senza /v1), ANTHROPIC_AUTH_TOKEN con la chiave API e quattro variabili che fissano i modelli. In questo modo paghi solo i token utilizzati, scalati dal saldo che puoi ricaricare con BLIK in złoty, a partire da 10 USD. Infine, digita /status in Claude Code per verificare che la chiave funzioni.

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

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

:: Windows – wiersz polecenia (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Abbiamo verificato comandi e variabili il 3 ottobre 2026 nella documentazione ufficiale di installazione di Claude Code e nella documentazione sulle variabili d'ambiente. Questa documentazione non è disponibile in polacco. Abbiamo verificato prezzi e metodi di pagamento il 10 ottobre 2026. La Polonia è nell'elenco dei paesi supportati da Anthropic (verificato il 3 ottobre 2026), sia per Claude.ai sia per l'API.

Accesso o chiave API?

Dopo l'installazione, Claude Code deve autenticarsi. Esistono due modalità; questa guida descrive in dettaglio la seconda:

Prima di iniziare

Metodo 1: installer nativo (consigliato)

Nella documentazione ufficiale questo metodo ha la scheda “Native Install (Recommended)”. I comandi si trovano all'inizio della pagina. Su macOS, Linux e WSL si utilizza la riga con install.sh. In Windows PowerShell usa irm … | iex, mentre nel prompt dei comandi CMD usa la riga con install.cmd. L'installazione nativa si aggiorna automaticamente in background. Claude Code può essere installato anche tramite Homebrew o WinGet, ma secondo la documentazione queste installazioni non si aggiornano automaticamente per impostazione predefinita; pertanto devi aggiornarle manualmente nel gestore dei pacchetti:

# Homebrew – kanał stable; domyślnie nie aktualizuje się sam
brew install --cask claude-code

# WinGet (Windows) – domyślnie nie aktualizuje się sam
winget install Anthropic.ClaudeCode

Dopo l'installazione, apri una nuova finestra del terminale, perché una finestra aperta in precedenza non vede la variabile PATH aggiornata. Poi verifica:

claude --version   # wypisuje numer wersji, np. 2.1.280 (Claude Code)
claude doctor      # diagnostyka instalacji i ustawień, bez otwierania sesji

claude doctor non apre una sessione. Visualizza soltanto lo stato dell'installazione e la diagnostica dei file di configurazione. In questo modo puoi distinguere rapidamente un problema di installazione da un problema di configurazione.

Quando il download non riesce

Se il terminale mostra syntax error near unexpected token '<' oppure curl: (22) The requested URL returned error: 403, secondo la pagina ufficiale per la risoluzione dei problemi di installazione (verificata il 3 ottobre 2026), l'indirizzo dell'installer ha restituito una pagina HTML o un codice di errore invece dello script. Secondo la documentazione, una pagina con la dicitura App unavailable in region significa che Claude Code non è disponibile nel tuo paese. Tuttavia, la Polonia è nell'elenco dei paesi supportati, quindi se visualizzi questa dicitura in Polonia, verifica che la connessione non passi tramite VPN o proxy. Un errore 403 senza contenuto può anche provenire da un proxy aziendale o da un firewall che blocca il download. In tal caso, la documentazione consiglia di controllare prima la connessione di rete, poiché gli altri metodi di installazione si connettono agli stessi server. Prova con un'altra rete oppure chiedi all'amministratore di sbloccare questi indirizzi.

Metodo 2: npm (Node.js 22 o versione successiva)

npm è ancora uno dei metodi descritti nella documentazione ufficiale. Il pacchetto richiede Node.js 22 o versione successiva. Alcune guide polacche indicano ancora Node.js 18, informazione ormai non aggiornata. Con una versione precedente di Node.js, npm visualizzerà l'avviso EBADENGINE, ma non interromperà l'installazione e claude funzionerà, perché il pacchetto scarica un programma nativo che non usa Node.js durante l'esecuzione. Se non hai Node.js, installa la versione 22 o successiva dal sito nodejs.org.

node -v                                    # potrzebna wersja v22 lub nowsza
npm install -g @anthropic-ai/claude-code   # bez sudo

# aktualizacja: @latest, a nie npm update -g
npm install -g @anthropic-ai/claude-code@latest

• Non usare mai sudo npm install -g. La documentazione avverte che ciò causa problemi di autorizzazioni e rappresenta un rischio per la sicurezza.
• Aggiorna tramite @latest. Per l'aggiornamento usa npm install -g @anthropic-ai/claude-code@latest, non npm update -g.
• Non saltare le dipendenze facoltative. Il programma corretto viene installato come dipendenza facoltativa, ovvero il pacchetto @anthropic-ai/claude-code-* per la tua piattaforma. Con il flag --omit=optional oppure con optional=false in .npmrc, l'installazione su macOS o Linux termina con il messaggio claude native binary not installed.

Claude Code su Windows: PowerShell, CMD, WSL e PATH

Windows ha due comandi di installazione diversi e la scelta dipende esclusivamente dal terminale. Se la riga inizia con PS C:\Users\TwojaNazwa>, stai lavorando in PowerShell. Se vedi soltanto C:\Users\TwojaNazwa>, senza PS, si tratta del prompt dei comandi (CMD). Secondo la documentazione, non è necessario avviare il terminale come amministratore, anche se alcune guide lo consigliano.

L'errore più comune consiste nell'incollare il comando nel terminale sbagliato. Una riga per CMD incollata in PowerShell produce The token '&&' is not a valid statement separator. Una riga per PowerShell incollata in CMD produce 'irm' is not recognized as an internal or external command. In Windows in italiano, lo stesso messaggio è: “irm” non è riconosciuto come comando interno o esterno, programma eseguibile o file batch. Al contrario, la riga curl … | bash per macOS incollata in PowerShell termina con l'errore A parameter cannot be found that matches parameter name 'fsSL' o 'bash' is not recognized as the name of a cmdlet. In tutti questi casi è sufficiente usare la riga destinata al tuo terminale.

Nel menu Start sono presenti due voci: “Windows PowerShell” e “Windows PowerShell (x86)”. La seconda viene eseguita come processo a 32 bit, quindi produce l'errore Claude Code does not support 32-bit Windows anche su un computer a 64 bit. Apri la voce senza il suffisso (x86).

Git for Windows è facoltativo, ma consigliato. Quando è installato, Claude Code esegue i comandi tramite Git Bash incluso con Git; in sua assenza li esegue tramite PowerShell. Se Git è installato ma Claude Code non trova Git Bash, imposta nel blocco env del file ~/.claude/settings.json la variabile CLAUDE_CODE_GIT_BASH_PATH con il percorso di bash.exe. Un percorso di esempio fornito dalla documentazione è C:\Program Files\Git\bin\bash.exe.

Se scegli WSL, esegui la riga per macOS e Linux nel terminale WSL e avvia claude anch'esso lì, non in PowerShell o CMD.

Errore relativo ai criteri di esecuzione degli script (npm in PowerShell)

Il messaggio npm.ps1 cannot be loaded because running scripts is disabled on this system durante l'installazione o l'avvio tramite npm indica che i criteri di esecuzione di PowerShell bloccano lo script di avvio .ps1 generato da npm. Secondo la documentazione, puoi consentire all'utente corrente di eseguire script locali (con il comando riportato di seguito), usare npm.cmd e claude.cmd oppure passare all'installer nativo per PowerShell.

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Il comando “claude” non viene riconosciuto dopo l'installazione

command not found: claude oppure 'claude' is not recognized indica che la directory di installazione non è inclusa in PATH. L'installer nativo colloca il programma in ~/.local/bin/claude su macOS e Linux e in %USERPROFILE%\.local\bin\claude.exe su Windows. Innanzitutto, apri un nuovo terminale. Se su Windows continua a non funzionare, verifica e aggiungi il percorso in PowerShell come indicato nella documentazione:

# 1. Sprawdź, czy katalog instalacji jest już w PATH
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Brak wyniku? Dopisz go do PATH użytkownika, zamknij i otwórz terminal
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. W nowym terminalu
claude --version

Chiave API anziché accesso (senza abbonamento)

ANTHROPIC_BASE_URL è una variabile integrata di Claude Code. Secondo la documentazione ufficiale, sovrascrive l'endpoint API per indirizzare le richieste attraverso un proxy o un gateway. Collegare Claude Code a un servizio compatibile con Anthropic Messages API è quindi una configurazione prevista da Anthropic. Non servono plugin né un programma modificato. Su macOS e Linux, aggiungi le variabili al file di configurazione della shell (~/.zshrc o ~/.bashrc):

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # sama domena, bez /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 puoi prima verificare la configurazione in una finestra di PowerShell:

# Działa tylko w tym oknie PowerShella – po zamknięciu znika
$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, è preferibile inserire le variabili nel blocco env del file delle impostazioni utente ~/.claude/settings.json (su Windows %USERPROFILE%\.claude\settings.json). Secondo la documentazione, questo file si applica a tutti i tuoi progetti. Se nel file sono già presenti 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"
  }
}

È facile commettere un errore in ognuna di queste sei righe:

• ANTHROPIC_BASE_URL è solo il dominio. Claude Code aggiunge automaticamente /v1/messages. Con /v1 alla fine, la richiesta verrà indirizzata a /v1/v1/messages e restituirà 404.
• ANTHROPIC_AUTH_TOKEN, non ANTHROPIC_API_KEY. Il valore di ANTHROPIC_AUTH_TOKEN viene inserito nell'intestazione Authorization con il prefisso Bearer e funziona immediatamente. ANTHROPIC_API_KEY viene inserito nell'intestazione x-api-key e, in modalità interattiva, deve essere approvato una volta. Se rifiuti, la chiave verrà ignorata silenziosamente. Puoi riattivarla in /config → Use custom API key.
• ANTHROPIC_MODEL seleziona il modello principale. In questo caso è Claude Sonnet 5 (claude-sonnet-5). Il nome deve corrispondere esattamente a quello presente nell'elenco dei modelli Kunavo. Kunavo non riconosce i nomi precedenti con la data alla fine.
• ANTHROPIC_DEFAULT_OPUS_MODEL e ANTHROPIC_DEFAULT_SONNET_MODEL fissano gli alias opus e sonnet. Secondo la documentazione ufficiale sulla configurazione dei modelli (verificata il 3 ottobre 2026), per chi usa l'API il modello predefinito e l'alias opus puntano a Opus 5.5, mentre l'alias sonnet punta a Sonnet 5.5. Gli alias cambiano nel tempo e per fissare una versione si usa il nome completo del modello oppure variabili come queste due. Una richiesta per un modello non disponibile su Kunavo restituisce 404. Fissiamo l'alias opus a Claude Opus 5.5 (claude-opus-5-5), perché il successivo modello Opus rilasciato da Anthropic potrebbe non essere subito disponibile su Kunavo. Opus 5.5 richiede Claude Code versione 2.1.280 o successiva; puoi aggiornare una versione precedente con il comando claude update. Sonnet 5.5 al momento non è disponibile su Kunavo (situazione al 3 ottobre 2026), quindi, se non si fissa l'alias sonnet a claude-sonnet-5, restituiscono un errore 404 /model sonnet, la fase di esecuzione in modalità opusplan e i subagenti configurati su model: sonnet.
• Fissa anche ANTHROPIC_DEFAULT_HAIKU_MODEL. L'alias haiku richiede un ID modello che Kunavo non supporta: dalla versione 2.1.293 di Claude Code è Haiku 5.5, mentre nelle versioni precedenti è un ID Haiku 4.5 con data. Senza questa variabile, /model haiku e i subagenti impostati su model: haiku restituiscono 404.
• ANTHROPIC_DEFAULT_HAIKU_MODEL gestisce anche le attività in background. Secondo la documentazione, questa variabile seleziona il modello per l'alias haiku e per le funzioni eseguite in background. Su Kunavo, Claude Haiku 4.5 costa 0,70 USD per milione di token di input e 3,50 USD per milione di token di output. Il modello principale Claude Sonnet 5 costa 1,40 USD / 7,00 USD (listino Anthropic: 2,00 USD / 10,00 USD), mentre Claude Opus 5.5 costa 2,80 USD / 14,00 USD (input / output, per milione di token).

Non inserire la chiave nel file di progetto .claude/settings.json. Secondo la documentazione sulla connessione a un gateway, questo file entra nel repository e quindi viene esposto a chiunque lo cloni. Tieni presente anche l'ordine di precedenza. Se la stessa variabile è impostata sia nella shell sia nel blocco env del file delle impostazioni, nella maggior parte delle sessioni prevale il valore del file. Una regola specifica riguarda la chiave model nel file delle impostazioni: la variabile ANTHROPIC_MODEL ha la precedenza su di essa e model viene usato solo se la variabile non è presente. Se una modifica nella shell non ha effetto, controlla prima il file delle impostazioni. Nell'estensione Claude Code per VS Code, le variabili si impostano in claudeCode.environmentVariables, nelle impostazioni utente di VS Code.

Primo avvio e /status

Secondo la documentazione sul collegamento del gateway (verificato il 3 ottobre 2026), con ANTHROPIC_AUTH_TOKEN impostato, il comando claude apre immediatamente una sessione senza schermata di accesso. La variabile funziona subito e non deve essere approvata, come invece accade con ANTHROPIC_API_KEY. Se visualizzi una schermata di accesso, Claude Code non ha letto la chiave.

La chiave deve trovarsi nel punto in cui Claude Code la legge prima della prima configurazione, cioè impostata con il comando export nella shell oppure nel blocco env del file utente ~/.claude/settings.json. In modalità interattiva, il blocco env delle impostazioni del progetto .claude/settings.json o .claude/settings.local.json diventa attivo solo dopo la procedura guidata del primo avvio e la domanda relativa all'attendibilità della cartella. Se la chiave è presente solo nelle impostazioni del progetto, al primo avvio visualizzerai comunque la schermata di accesso.

Nella sessione digita /status e verifica le due righe:

• Anthropic base URL appare solo quando è impostato l'indirizzo del gateway. Dovrebbe mostrare https://api.kunavo.com. Se questa riga non è presente, ANTHROPIC_BASE_URL non è arrivato alla sessione.
• Auth token con il nome ANTHROPIC_AUTH_TOKEN indica che è in uso una chiave API, non un accesso claude.ai salvato. Se visualizzi Login method con un account claude.ai, la variabile non ha funzionato.

Puoi verificare l'indirizzo e la chiave anche prima di avviare Claude Code, usando il metodo della documentazione ufficiale. Consiste nell'inviare una richiesta per 1 token di output, che addebiterà al saldo un importo simbolico. Il comando legge le variabili dalla shell corrente, quindi, anche se la chiave si trova nel file delle impostazioni, devi prima impostare le variabili con il comando export in questo terminale. Una risposta JSON che inizia con {"id":"msg_ indica che l'indirizzo e la chiave funzionano. Il codice 401 indica che la chiave è stata 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 verifica è simile a questa. Se tutto funziona, nella risposta vedrai il campo 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 funziona diversamente con una chiave API

• Remote Control e la dettatura vocale non sono disponibili. Secondo la documentazione, richiedono un'identità claude.ai e non funzionano quando ANTHROPIC_AUTH_TOKEN è attivo. A partire dalla versione 2.1.196, Remote Control viene disabilitato anche quando ANTHROPIC_BASE_URL indica un host diverso da api.anthropic.com.
• /fast mostra la modalità rapida come disabilitata. Secondo la documentazione, quando è presente solo un token bearer, Claude Code considera la fast mode disabilitata e non invia una richiesta per verificarne la disponibilità.
• La ricerca degli strumenti MCP è disabilitata per impostazione predefinita. Ciò accade quando ANTHROPIC_BASE_URL indica un host diverso da Anthropic.
• I valori in /context sono approssimativi. Kunavo non offre l'endpoint /v1/messages/count_tokens. Secondo la documentazione sulla compatibilità dei gateway (verificata il 3 ottobre 2026), in tal caso Claude Code calcola i token localmente in base al numero di caratteri.

Trovi la descrizione completa dell'integrazione nella documentazione sull'integrazione di Claude Code (in inglese) e la versione inglese di questa guida nell'articolo Install Claude Code.

Pagamento con BLIK: ricarica del saldo e chiave API

Gli abbonamenti Claude acquistati sul sito di Anthropic si possono pagare solo con carta di credito o di debito (FAQ sulla fatturazione di Claude, verificate il 3 ottobre 2026). Non è possibile pagare Pro o Max con BLIK. Su Kunavo, BLIK ricarica il saldo API prepagato, da cui Claude Code paga i token dopo aver impostato la chiave come sopra. Tutti i passaggi di pagamento sono descritti nella guida come pagare Claude con BLIK; in breve, la procedura è questa:

1. Crea un account Kunavo tramite e-mail o account Google. Non è necessario fornire una carta durante la registrazione.
2. Nella scheda Fatturazione (Billing), seleziona l'importo della ricarica. Il minimo è 10 USD e non ci sono costi mensili. Per importi maggiori ricevi un bonus: 100 USD → 110 USD sul saldo, 1000 USD → 1200 USD sul saldo e 5000 USD → 6250 USD sul saldo.
3. Nella pagina di pagamento Stripe, l'importo è mostrato in złoty. Seleziona BLIK, genera nell'app bancaria un codice di sei cifre, inseriscilo e conferma il pagamento nell'app. Secondo la documentazione di Stripe (verificata il 3 ottobre 2026), il codice BLIK è valido per 2 minuti e, dopo aver avviato il pagamento, hai 60 secondi per approvarlo.
4. Nella scheda Chiavi API, crea una chiave che inizi con sk-kn-. La chiave viene visualizzata una sola volta, quindi salvala subito e inseriscila in ANTHROPIC_AUTH_TOKEN.

Nella pagina di pagamento in złoty sono disponibili, oltre a BLIK, anche le carte (Visa, Mastercard), Apple Pay e Google Pay sui dispositivi supportati, oltre a Link. Non sono invece disponibili Przelewy24, PayU, PayPal né il normale bonifico bancario. I prezzi sono stabiliti in dollari e Stripe li converte in złoty. Secondo la documentazione di Stripe sui prezzi adattivi (verificata il 3 ottobre 2026), il tasso di cambio include una commissione di conversione del 2–4%, a carico dell'acquirente. Pagando con carta in dollari eviterai questa commissione, anche se si applicheranno il tasso di cambio e le commissioni della tua banca; BLIK funziona solo in złoty. L'importo esatto in złoty viene mostrato nella pagina di pagamento prima della conferma.

BLIK funziona solo per le ricariche manuali. La ricarica automatica richiede una carta o Link salvati. Il saldo non scade e non paghi per le richieste non riuscite. Kunavo non emette fatture IVA; trovi la cronologia delle ricariche nella scheda Fatturazione (Billing). Ricorda che si tratta di una ricarica del saldo dell'API Kunavo, non di un pagamento per Claude Pro o Max.

Quanto costa (calcolo di esempio)

In Claude Code paghi per i token. Per ogni richiesta, Claude Code invia nuovamente l'intero contesto della conversazione, ma l'inizio ripetuto del contesto può essere fatturato alla tariffa di lettura dalla cache. Di seguito trovi un calcolo di esempio basato sui token. Non si tratta di una misurazione né di un limite massimo dei costi. Sono indicate tutte le ipotesi:

• ogni richiesta contiene 40.000 token di input, di cui 36.000 (90%) vengono fatturati come lettura dalla cache, mentre i restanti 4000 come scrittura nella cache;
• ogni richiesta restituisce 1000 token di output;
• in una sessione di lavoro ci sono 50 richieste di questo tipo, senza chiamate Claude Haiku 4.5 in background;
• su Kunavo, la lettura dalla cache costa 10% della tariffa di input, mentre la scrittura nella cache costa 1,25× la tariffa di input. Queste sono le proporzioni per Claude Sonnet 5, mentre ogni modello nella tabella viene calcolato secondo le proprie proporzioni.

Il costo effettivo dipende dalla lunghezza del contesto, dal numero di riscontri nella cache, dalla lunghezza della risposta e dal fatto che tu cancelli o meno la conversazione tra un'attività e l'altra con il comando /clear. Trovi le tariffe di tutti i modelli nel listino prezzi. Puoi stimare il tuo consumo con il calcolatore dei costi dei token di Claude (in inglese). La guida quanto costa Claude Code descrive quando conviene di più un abbonamento e quando l'API.

Errori più comuni

Limitazioni

• Kunavo non emette fatture IVA.
• BLIK funziona solo per le ricariche manuali. La ricarica automatica richiede una carta o Link salvati.
• Questa è un'API con fatturazione a consumo di token, non un abbonamento Claude Pro o Max. Con una chiave API, Remote Control e la dettatura vocale non funzionano, la modalità /fast è disabilitata e la ricerca degli strumenti MCP è disabilitata per impostazione predefinita.
• Attualmente Kunavo (situazione al 3 ottobre 2026) non offre Sonnet 5.5; per questo la configurazione precedente assegna l'alias sonnet a claude-sonnet-5. Senza modelli assegnati, gli alias predefiniti possono restituire 404. Claude Opus 5.5, assegnato all'alias opus, richiede Claude Code versione 2.1.280 o successiva.
• La documentazione ufficiale di Claude Code e la documentazione sull'integrazione di Kunavo sono disponibili solo in inglese.

Domande frequenti