Installare Claude Code: Windows, macOS e Linux, chiave API senza abbonamento e pagamento con Bancontact

Per installare Claude Code basta una riga, ma non è la stessa ovunque: curl -fsSL https://claude.ai/install.sh | bash nel terminale di macOS, Linux o WSL, irm https://claude.ai/install.ps1 | iex in PowerShell e una riga install.cmd nel prompt dei comandi di Windows. La vera domanda arriva al primo avvio: chi paga le richieste? Un account Pro, Max, Team, Enterprise o Console consente di accedere (il piano gratuito di Claude.ai non include Claude Code). Senza abbonamento basta una chiave API: sei variabili, tra cui ANTHROPIC_BASE_URL senza /v1 e ANTHROPIC_AUTH_TOKEN, poi una rapida verifica con /status. Il saldo Kunavo si paga con carta, Apple Pay, Google Pay, Link o, in Belgio, Bancontact, a partire da $10, senza abbonamento.

Origine delle informazioni: i comandi e le variabili provengono dalla documentazione ufficiale di Claude Code (installazione, variabili d’ambiente, connessione a un gateway), ricontrollata il 3 ottobre 2026; i prezzi e i metodi di pagamento di Kunavo sono stati verificati il 10 ottobre 2026. Secondo l’elenco dei paesi supportati da Anthropic (consultato il 3 ottobre 2026), Claude.ai e l’API sono disponibili in Francia, Belgio, Svizzera, Lussemburgo e Canada, così come in Marocco, Tunisia, Algeria, Senegal e Costa d’Avorio. La stessa guida è disponibile in inglese e, per le Fiandre, in olandese.

Quale comando digitare: dipende tutto dalla finestra

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

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

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

Le prime tre righe configurano la versione nativa, quella consigliata da Anthropic: un binario autonomo, collocato in ~/.local/bin (%USERPROFILE%\.local\bin su Windows), che scarica gli aggiornamenti in background e li applica al successivo avvio. Al termine dell’installazione, chiudete il terminale e riapritene uno: quello utilizzato per l’installazione non conosce ancora il nuovo PATH.

Su Windows, scegliere la finestra sbagliata è la causa principale degli errori, e il messaggio lo dice chiaramente. The token '&&' is not a valid statement separator: avete incollato la riga CMD in PowerShell. 'irm' is not recognized as an internal or external command: è il contrario. Su un Windows in francese, questo secondo messaggio può apparire tradotto; la causa non cambia. Gli altri messaggi sono nella tabella degli errori, alla fine della guida.

Requisiti

Windows: cosa dicono i vecchi tutorial e cosa è vero

Molti tutorial in francese risalgono alle prime versioni di Claude Code. Ecco le istruzioni più diffuse, confrontate con la documentazione di installazione attuale e la pagina di risoluzione dei problemi (consultate il 3 ottobre 2026):

Se installate Git for Windows, Claude Code usa Git Bash e mantiene disponibile anche lo strumento PowerShell. A volte non riesce a trovare bash.exe: in tal caso, indicate il percorso nella variabile CLAUDE_CODE_GIT_BASH_PATH, all’interno del blocco env di ~/.claude/settings.json (la documentazione riporta C:\Program Files\Git\bin\bash.exe come esempio). Un’ultima insidia: il collegamento «Windows PowerShell (x86)» avvia una versione a 32 bit, che Claude Code rifiuta.

Nativo o WSL: la scelta dipende da dove si trovano i vostri progetti:

Per WSL, tutto avviene all’interno della distribuzione Linux: è lì che si incolla la riga curl … | bash e lì che poi si digita claude. Se avviato da PowerShell o CMD, non vedrebbe questa installazione.

Homebrew, WinGet, apt o npm

I gestori di pacchetti funzionano, con una contropartita: Claude Code non viene aggiornato automaticamente. Per Homebrew e WinGet, la variabile CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 ordina a Claude Code di avviare autonomamente l’aggiornamento; senza di essa, dovete farlo voi:

# Homebrew (macOS)
brew install --cask claude-code
brew upgrade claude-code              # pas de mise à jour automatique

# WinGet (Windows)
winget install Anthropic.ClaudeCode
winget upgrade Anthropic.ClaudeCode   # pas de mise à jour automatique

Su Debian, Ubuntu, Fedora, RHEL e Alpine, Anthropic pubblica anche repository firmati apt, dnf e apk, aggiornati insieme al resto del sistema; la procedura è riportata nella pagina di installazione.

Resta npm, pratico se Node.js fa già parte dei vostri strumenti. Il pacchetto richiede almeno Node.js 22. Con una versione precedente, npm si limita a mostrare un avviso EBADENGINE e procede, perché il pacchetto installa lo stesso binario nativo, che non ha bisogno di Node.js per funzionare. Due regole: non usare sudo npm install -g e aggiornare con @latest, perché npm update -g rimane nell’intervallo delle versioni originali e può lasciarvi indietro.

node -v                                       # v22 ou plus récent
npm install -g @anthropic-ai/claude-code      # jamais avec sudo

# mise à jour : avec @latest, pas avec npm update -g
npm install -g @anthropic-ai/claude-code@latest

Verificare l’installazione e correggere il PATH

claude --version   # affiche le numéro de version, suivi de (Claude Code)
claude doctor      # diagnostic de l’installation et des réglages, sans ouvrir de session

Se restituisce un numero di versione, è installato. claude doctor va oltre senza avviare una sessione: stato dell’installazione, errori nei file di configurazione, risultato dell’ultimo aggiornamento. Quando qualcosa non va, è il primo comando da eseguire.

Il messaggio command not found: claude su macOS o Linux e claude «non riconosciuto» su Windows indicano che il programma è installato, ma la shell non sa dove trovarlo. Nella maggior parte dei casi basta aprire una nuova finestra. Altrimenti, aggiungete ~/.local/bin al PATH in ~/.zshrc o ~/.bashrc. Su Windows, la pagina ufficiale di risoluzione dei problemi illustra questi tre passaggi di PowerShell:

# 1. Le dossier d'installation est-il déjà dans le PATH ?
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Aucun résultat ? Ajoutez-le au PATH de l'utilisateur, puis ouvrez une nouvelle fenêtre
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. Dans la nouvelle fenêtre : deux chemins = deux installations concurrentes
where.exe claude

Installato tramite npm e PowerShell risponde npm.ps1 cannot be loaded? La relativa strategia di esecuzione blocca gli script di npm. Passate all’installer nativo oppure autorizzate gli script locali solo per il vostro account:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Chi paga le richieste: abbonamento Claude o chiave API

La scelta non viene effettuata durante l’installazione, ma al primo avvio, e resta reversibile. Una chiave definita nell’ambiente prevale su una connessione claude.ai salvata, che rimane inattiva; eliminate la variabile e la connessione tornerà ad avere effetto al successivo avvio.

Con un abbonamento Claude

Niente da configurare: claude nella cartella del progetto, poi accesso nel browser. Un’unica eccezione: una ANTHROPIC_API_KEY eventualmente presente nell’ambiente. Claude Code chiederà una volta se deve utilizzarla; un rifiuto viene memorizzato e la chiave viene poi ignorata senza messaggi, facendo pensare che la variabile non venga letta. Per modificare questa scelta: /config → Use custom API key.

Senza abbonamento: la chiave API Kunavo

Reindirizzare Claude Code in modo che si colleghi a un endpoint diverso da Anthropic non è una soluzione improvvisata. L’elenco ufficiale delle variabili d’ambiente indica ANTHROPIC_BASE_URL come metodo per inviare le richieste tramite un proxy o un gateway. Kunavo è compatibile con il formato dell’API Messages di Anthropic: potete continuare a usare Claude Code ufficiale, senza estensioni né versioni modificate.

1. Create un account: registrazione Kunavo.
2. Ricaricate il saldo in Billing, almeno $10 (metodi di pagamento più sotto).
3. Generate una chiave in /app/keys. Inizia con sk-kn- e viene mostrata solo al momento della creazione: copiatela subito.
4. Inserite le sei variabili qui sotto.

Perché fissare quattro modelli? Gli alias di Claude Code seguono le nuove versioni di Anthropic. Secondo la documentazione sulla configurazione dei modelli (consultata il 3 ottobre 2026), per un account API, l’impostazione predefinita e opus puntano attualmente a Opus 5.5, mentre sonnet punta a Sonnet 5.5, che Kunavo non offre: senza ANTHROPIC_DEFAULT_SONNET_MODEL, /model sonnet, la fase di esecuzione di opusplan e i subagenti impostati su sonnet restituiscono un errore 404. L’alias opus è fissato a Opus 5.5 (claude-opus-5-5), che richiede Claude Code v2.1.280 o versione successiva; se usate una versione precedente, eseguite claude update. Inoltre, un modello appena rilasciato potrebbe non essere subito disponibile su Kunavo. Con i nomi completi, ogni richiesta viene inviata a un modello disponibile, alla tariffa che conoscete. La documentazione sul protocollo dei gateway (consultata il 3 ottobre 2026) conferma quanto detto sulle attività in background: con Claude Haiku 4.5 hanno un costo contenuto.

Dove inserire le variabili

La versione consigliata, da unire al contenuto esistente del file se presente (aggiungete solo 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"
  }
}

Gli stessi valori nella shell, su macOS e Linux:

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # le domaine seul, sans /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

Per un test rapido in una finestra PowerShell:

# Valable uniquement dans cette fenêtre 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

E per l’estensione VS Code, nelle impostazioni utente dell’editor (comando Preferences: Open User Settings (JSON)):

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://api.kunavo.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-kn-..." },
    { "name": "ANTHROPIC_MODEL", "value": "claude-sonnet-5" },
    { "name": "ANTHROPIC_DEFAULT_OPUS_MODEL", "value": "claude-opus-5-5" },
    { "name": "ANTHROPIC_DEFAULT_SONNET_MODEL", "value": "claude-sonnet-5" },
    { "name": "ANTHROPIC_DEFAULT_HAIKU_MODEL", "value": "claude-haiku-4-5" }
  ]
}

L’app desktop Claude fa eccezione: non legge né ANTHROPIC_BASE_URL né settings.json. Una variabile modificata nella shell che continua a non avere effetto? Cercate prima la stessa variabile in un settings.json, che ha la precedenza.

Tariffe per milione di token tratte dal catalogo Kunavo, accanto al prezzo di listino di Anthropic rilevato su claude.com/pricing (consultato il 3 ottobre 2026):

Per passare a Opus per la durata di un’attività: /model opus durante la sessione (l’alias fissato su claude-opus-5-5), oppure claude --model claude-opus-5-5 all’avvio. Il budget mensile in base al vostro utilizzo e la soglia oltre la quale l’abbonamento diventa più conveniente sono quantificati in il prezzo di Claude Code. Il calcolatore dei costi in token di Claude esegue il calcolo per i vostri volumi, mentre la pagina dei prezzi elenca tutti i modelli.

Verificare con /status

Il primo segnale, ancora prima di /status: con ANTHROPIC_AUTH_TOKEN configurato, Claude Code si avvia senza schermata di accesso. Se compare questa schermata, non è stata letta alcuna chiave, spesso perché si trova solo nelle impostazioni del progetto (.claude/settings.json o .claude/settings.local.json). In una sessione interattiva, questo blocco env viene applicato solo dopo la procedura guidata del primo avvio e la domanda di attendibilità della cartella. Spostate la chiave nella shell o in ~/.claude/settings.json.

Una volta avviata la sessione, /status si apre nella scheda Status. Ecco come leggerla, secondo la documentazione sui gateway (consultata il 3 ottobre 2026):

Eravate già connessi con un abbonamento? Claude Code può allora segnalare all’avvio due fonti di autenticazione attive, in un avviso che termina con auth may not work as expected. È la chiave a essere utilizzata per le richieste; /logout elimina la vecchia connessione e fa scomparire l’avviso.

Per sapere se un problema dipende da Kunavo o dalla vostra configurazione, testate senza Claude Code. La documentazione propone una richiesta limitata a un solo token di output, che costa una frazione di centesimo. I due comandi qui sotto prendono indirizzo e chiave dalla shell: se definiti solo in settings.json, qui non verrebbero rilevati.

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": "."}]}'

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": "."}]}'

Un JSON che inizia con {"id":"msg_, oppure in PowerShell un oggetto il cui id inizia con msg_: indirizzo e chiave funzionano. Un 401: la chiave viene rifiutata.

Cosa cambia con una chiave API

• Remote Control e dettatura vocale scompaiono. Entrambi dipendono da un account claude.ai e restano indisponibili finché ANTHROPIC_AUTH_TOKEN è definita. Remote Control viene disattivato anche quando ANTHROPIC_BASE_URL indica un host diverso da Anthropic.
• La modalità rapida (/fast) appare disattivata, perché la sua verifica richiede una connessione claude.ai o una chiave Anthropic, non un semplice bearer token.
• La ricerca degli strumenti MCP è disattivata per impostazione predefinita quando ANTHROPIC_BASE_URL punta fuori da Anthropic.
• /context mostra stime. Kunavo non offre /v1/messages/count_tokens; in tal caso Claude Code calcola il numero di token in base al numero di caratteri (documentazione sul protocollo dei gateway).

Per il resto (lettura e scrittura del codice, strumenti, sottoagenti, server MCP, hook, cache dei prompt), non cambia nulla. I dettagli tecnici, in inglese, sono nella documentazione sull’integrazione di Claude Code.

Pagare dalla Francia o dal Belgio

Due sistemi di pagamento da non confondere. L’abbonamento Claude acquistato sul web si paga solo con carta di credito o di debito (FAQ sulla fatturazione di Anthropic, consultata il 3 ottobre 2026); se sottoscritto nell’app mobile, si paga tramite App Store o Google Play. Gli importi su claude.com/pricing sono al netto delle imposte.

Il saldo Kunavo si ricarica invece tramite una pagina di pagamento Stripe. La tariffa è stabilita in dollari statunitensi, ma se vi trovate in Francia o in Belgio Stripe mostra l’importo in euro, con un tasso di cambio garantito per 24 ore che include una commissione di conversione del 2–4% a vostro carico (documentazione di Stripe su Adaptive Pricing, consultata il 3 ottobre 2026). Potete pagare in dollari per evitare questa commissione, ma in tal caso la vostra banca applicherà il proprio tasso di cambio; Bancontact è disponibile solo in euro. Metodi di pagamento disponibili:

• Carta CB francese? Secondo la documentazione di Stripe su Cartes Bancaires (consultata il 3 ottobre 2026), oltre il 95% delle carte CB reca un doppio marchio: CB e Visa o Mastercard. Vengono quindi accettate alla pagina di pagamento come Visa o Mastercard; è sufficiente una normale carta di debito.
• Bancontact è disponibile per gli acquirenti che si trovano in Belgio. Stripe vi reindirizza al sito o all’app Bancontact per autorizzare il pagamento e l’esito è immediato (documentazione di Stripe su Bancontact, consultata il 3 ottobre 2026).
• Pay by Bank, il pagamento tramite il proprio servizio bancario online, non è disponibile in Francia né in Belgio: il checkout lo mostra solo agli acquirenti che si trovano nel Regno Unito, in Irlanda e in Finlandia. La documentazione di Stripe su Pay by Bank (consultata il 3 ottobre 2026) lo indica come disponibile in anteprima privata in Francia e non menziona il Belgio.
• Dalla Svizzera o dal Canada, l’importo viene mostrato in franchi svizzeri o dollari canadesi, con carta e Link, oltre ad Apple Pay e Google Pay, che si basano su una carta.

Non disponibili: PayPal, addebito SEPA, Klarna, riservato agli acquirenti situati negli Stati Uniti (pagare in dollari non basta).

1. Registratevi su Kunavo; in questa fase non è richiesta alcuna carta.
2. In Billing, scegliete l’importo: almeno $10. Gli importi più elevati danno diritto a un bonus ($100 pagati, $110 accreditati; $1.000 pagati, $1.200 accreditati; $5.000 pagati, $6.250 accreditati).
3. Nella pagina Stripe, selezionate il metodo di pagamento; l’importo in euro viene mostrato prima della conferma. Con Bancontact, confermate nell’app o con la carta.
4. Create la chiave in /app/keys e inseritela in ANTHROPIC_AUTH_TOKEN.

Il saldo è prepagato: nessun costo mensile, nessuna scadenza e una richiesta che fallisce non viene addebitata. La ricarica automatica richiede una carta salvata o Link. Bancontact non gestisce i pagamenti ricorrenti su Stripe, quindi ogni ricarica Bancontact deve essere avviata manualmente. Kunavo non emette fatture con IVA, né francese, né belga, né di altri Paesi; la cronologia delle ricariche è consultabile in Billing. Infine, questi metodi di pagamento servono esclusivamente per il saldo API Kunavo e non pagano un abbonamento Claude Pro o Max. Tutte le altre possibilità, inclusi App Store e Google Play, sono esaminate in pagare Claude senza carta bancaria.

Errori comuni

Primi passi in un progetto

In un repository che Claude Code sta esaminando, iniziate con /init: esplora il codice e redige un file CLAUDE.md che registra i comandi di test e le convenzioni individuate. Rileggete questo file e snellitelo, poiché viene ricaricato a ogni sessione. Per cambiare argomento, /clear riparte da una conversazione vuota; per proseguire un'attività lunga, /compact ne riassume la cronologia.

I limiti della chiave API

• Pagate a consumo, non con un abbonamento Claude Pro o Max. Per diverse ore di Claude Code al giorno, tutti i giorni, l'abbonamento è spesso più conveniente; per un uso irregolare, il pagamento per token è più flessibile e i mesi di scarso utilizzo non costano nulla. Dati in il prezzo di Claude Code.
• Niente Remote Control né dettatura vocale finché la chiave è attiva.
• La capacità di Kunavo è condivisa, senza quota riservata né impegno contrattuale; se ne avete bisogno, stipulate un contratto direttamente con Anthropic.
• Bancontact consente solo ricariche manuali; quelle automatiche passano da una carta salvata o da Link.
• Gli importi in euro includono le commissioni di conversione di Stripe e Kunavo non emette fatture con IVA.

Domande frequenti