Installare Claude Code: comandi per Windows, macOS e Linux, chiave API senza abbonamento e pagamento con iDEAL

Claude Code si installa con un unico comando ufficiale: su macOS, Linux e WSL con curl -fsSL https://claude.ai/install.sh | bash, su Windows in PowerShell con irm https://claude.ai/install.ps1 | iex (nel Prompt dei comandi, CMD, con la riga install.cmd riportata sotto). Poi scegli come pagare. Puoi accedere con un account Pro, Max, Team, Enterprise o Console (il piano gratuito Claude.ai non include Claude Code), oppure usare una chiave API senza abbonamento: imposta ANTHROPIC_BASE_URL (solo il dominio, senza /v1), ANTHROPIC_AUTH_TOKEN e quattro variabili del modello, quindi verifica con /status che la chiave sia attiva. Il credito Kunavo può essere ricaricato con iDEAL (Paesi Bassi) o Bancontact (Belgio), a partire da $10, senza canone mensile.

Comandi e variabili verificati il 3 ottobre 2026 nella documentazione ufficiale di installazione di Claude Code e nella documentazione sulle variabili d’ambiente; prezzi e metodi di pagamento verificati il 10 ottobre 2026. Paesi Bassi e Belgio sono entrambi nell’elenco dei paesi supportati da Anthropic (verificato il 3 ottobre 2026), sia per Claude.ai sia per l’API. Questa guida è disponibile anche in inglese: Install Claude Code.

Prima di installare

Installare Claude Code su macOS e Linux

Apri Terminale e incolla questa riga:

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

Questa è l’installazione nativa consigliata: un unico programma autonomo che si aggiorna automaticamente in background. Il comando claude viene installato in ~/.local/bin. Un terminale già aperto non conosce ancora il nuovo PATH, quindi apri prima una nuova finestra. In WSL usa esattamente la stessa riga, nel terminale WSL.

Installare Claude Code su Windows

Su Windows ci sono due righe e quella necessaria dipende esclusivamente dalla finestra aperta. Se il prompt inizia con PS C:\Users\Naam>, sei in PowerShell; se mostra solo C:\Users\Naam> senza PS, è il Prompt dei comandi (CMD). Non è necessario aprire la finestra come amministratore: secondo la documentazione ufficiale non serve.

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

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

L’errore più comune è incollare la riga nella finestra sbagliata. La riga CMD in PowerShell restituisce The token '&&' is not a valid statement separator; la riga PowerShell in CMD restituisce 'irm' is not recognized as an internal or external command. Su una versione di Windows in olandese, il secondo messaggio può comparire in olandese, con la stessa causa. Inoltre, la riga macOS con | bash in PowerShell restituisce un errore secondo cui bash non è riconosciuto. In tutti e tre i casi: usa la riga corrispondente alla finestra.

Git for Windows è facoltativo. Se è installato, Claude Code esegue i comandi tramite Git Bash, incluso con Git; senza Git usa PowerShell. Se Git è installato ma Git Bash non viene trovato, imposta CLAUDE_CODE_GIT_BASH_PATH nel blocco env di ~/.claude/settings.json sul percorso di bash.exe; il percorso di esempio nella documentazione è C:\Program Files\Git\bin\bash.exe.

WSL non è quindi un requisito, come sostengono alcune guide meno recenti, ma una scelta. Se scegli WSL, esegui la riga macOS/Linux nel terminale WSL e avvia claude anche lì, non da PowerShell o CMD.

Tramite Homebrew, WinGet o npm

È possibile anche in questo modo, con una differenza importante: secondo la documentazione ufficiale, le installazioni tramite Homebrew e WinGet non si aggiornano automaticamente. In tal caso devi aggiornarle manualmente:

# Homebrew (macOS)
brew install --cask claude-code
brew upgrade claude-code              # bijwerken gebeurt niet vanzelf

# WinGet (Windows)
winget install Anthropic.ClaudeCode
winget upgrade Anthropic.ClaudeCode   # bijwerken gebeurt niet vanzelf

Il pacchetto npm richiede Node.js 22 o successivo, non Node.js 18 come indicano ancora le guide meno recenti. Con una versione precedente di Node.js, npm mostra solo un avviso EBADENGINE e l’installazione prosegue normalmente: il pacchetto installa lo stesso programma nativo, che non richiede Node.js per funzionare. Non usare mai sudo npm install -g: causa problemi di autorizzazioni e rappresenta un rischio per la sicurezza. Per aggiornare usa @latest, non npm update -g.

node -v                                           # moet v22 of hoger zijn
npm install -g @anthropic-ai/claude-code          # nooit met sudo

# later bijwerken: met @latest, niet met npm update -g
npm install -g @anthropic-ai/claude-code@latest

Verificare l’installazione

claude --version   # toont het versienummer, gevolgd door (Claude Code)
claude doctor      # alleen-lezen diagnose van installatie en instellingen, start geen sessie

claude doctor non avvia una sessione, ma mostra lo stato dell’installazione e dei file delle impostazioni. In questo modo puoi capire rapidamente se il problema riguarda l’installazione o la configurazione.

Se ricevi command not found: claude o Windows indica che claude non è riconosciuto, la cartella di installazione non è inclusa nel PATH. Per prima cosa, apri una nuova finestra del terminale. Se non basta, su macOS e Linux aggiungi ~/.local/bin al PATH tramite ~/.zshrc o ~/.bashrc. Su Windows la cartella è %USERPROFILE%\.local\bin; secondo la guida ufficiale alla risoluzione dei problemi, controllala e aggiungila con PowerShell nel modo seguente:

# 1. Staat de installatiemap al in je PATH?
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Geen uitvoer? Voeg de map toe aan je gebruikers-PATH en open een nieuw venster
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. In het nieuwe venster: twee paden betekent twee installaties naast elkaar
where.exe claude

Se installi tramite npm e PowerShell mostra npm.ps1 cannot be loaded because running scripts is disabled on this system, i criteri di esecuzione di PowerShell stanno bloccando gli script di avvio di npm. Usa l’installer nativo, avvia npm.cmd e claude.cmd, oppure consenti gli script locali per il tuo utente:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Primo avvio: abbonamento o chiave API

Al primo avvio scegli come pagare Claude Code. I due percorsi si escludono a vicenda: se è configurata una chiave API, un accesso salvato rimane inutilizzato; se rimuovi la variabile, Claude Code torna a usare l’accesso senza doverlo reinstallare.

Percorso A: accedere con il tuo abbonamento

Avvia claude nella cartella del progetto e accedi tramite il browser. C’è una particolarità: se ANTHROPIC_API_KEY è già configurata, Claude Code chiede una volta se deve usare quella chiave. Se rifiuti, in seguito ignora la chiave senza chiedertelo di nuovo e sembra che la variabile non venga letta. Riattivala tramite /config → Use custom API key.

Percorso B: senza abbonamento, con una chiave API

ANTHROPIC_BASE_URL è una variabile integrata di Claude Code. Secondo la documentazione ufficiale, sovrascrive l’endpoint API per inviare le richieste tramite un proxy o un gateway. Configurare Claude Code per puntare a un endpoint con l’Anthropic Messages API è quindi una configurazione supportata, senza plugin e senza una versione personalizzata. Procedura:

1. Crea un account Kunavo.
2. Ricarica il credito tramite Billing, a partire da $10 (iDEAL e Bancontact sono descritti più avanti).
3. Crea una chiave in /app/keys che inizi con sk-kn-. Viene mostrata una sola volta, quindi conservala subito.
4. Imposta le variabili. Su macOS e Linux in ~/.zshrc o ~/.bashrc:

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # alleen het domein, zonder /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 prima un test in un’unica finestra PowerShell:

# Geldt alleen voor dit PowerShell-venster
$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 un uso permanente, il posto migliore è il blocco env delle impostazioni utente: ~/.claude/settings.json (su Windows %USERPROFILE%\.claude\settings.json). I valori si applicano ovunque venga eseguito Claude Code, anche agli agenti in background. Le variabili della shell valgono solo per quella finestra del terminale: un editor aperto dal Dock o dal menu Start non le vede. Se nel file sono già presenti altre impostazioni, aggiungi 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"
  }
}

Non inserire mai la chiave nel .claude/settings.json di un progetto: secondo la documentazione ufficiale del gateway (verificata il 3 ottobre 2026), quel file viene sottoposto a commit e condiviso con chiunque cloni il repository. Fai attenzione anche all’ordine di precedenza: se imposti la stessa variabile sia nella shell sia in un file delle impostazioni, prevale il file delle impostazioni. Se una modifica alla variabile della shell non produce effetti, controlla prima settings.json.

Ogni riga presenta una propria insidia:

• ANTHROPIC_BASE_URL contiene solo il dominio. Claude Code aggiunge automaticamente /v1/messages; se termini con /v1, la richiesta viene inviata a /v1/v1/messages e ricevi un 404.
• Usa ANTHROPIC_AUTH_TOKEN, non ANTHROPIC_API_KEY. Secondo la documentazione, ANTHROPIC_AUTH_TOKEN viene inviata nell’header Authorization con Bearer davanti ed è valida immediatamente. ANTHROPIC_API_KEY viene inserita nell’header x-api-key e nella modalità interattiva deve essere approvata una volta prima dell’uso (vedi percorso A).
• Scrivi esattamente il nome del modello in ANTHROPIC_MODEL. Kunavo riconosce solo il nome esatto e non converte i nomi meno recenti con una data aggiunta.
• Fissa anche ANTHROPIC_DEFAULT_OPUS_MODEL e ANTHROPIC_DEFAULT_SONNET_MODEL. Secondo la documentazione sulla configurazione dei modelli (verificata il 3 ottobre 2026), per gli utenti API l’impostazione predefinita e l’alias opus puntano a Opus 5.5, mentre l’alias sonnet punta a Sonnet 5.5; gli alias cambiano insieme alle nuove versioni. Per fissarli, usa il nome completo del modello o variabili come ANTHROPIC_DEFAULT_OPUS_MODEL. Kunavo al momento non offre Sonnet 5.5 e un nuovo modello Opus non è sempre disponibile immediatamente; un modello non disponibile restituisce 404. Senza ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5, quindi, /model sonnet, la fase di esecuzione di opusplan e i subagent impostati su model: sonnet falliscono. Fissa l’alias opus su Opus 5.5 (claude-opus-5-5); per farlo serve Claude Code v2.1.280 o una versione successiva; aggiorna una versione precedente con claude update.
• Fissa anche ANTHROPIC_DEFAULT_HAIKU_MODEL. L'alias haiku richiede un ID che Kunavo non offre: dalla v2.1.293 Haiku 5.5, mentre nelle versioni precedenti un ID Haiku 4.5 con data. Senza questa riga, /model haiku e i subagenti impostati su model: haiku restituiscono 404.
• ANTHROPIC_DEFAULT_HAIKU_MODEL vale anche per le attività in background. Secondo la documentazione, questa variabile determina l’alias haiku e il modello per le funzioni in background, come i titoli delle sessioni. Con Claude Haiku 4.5 queste attività rimangono economiche.

Se usi l’estensione VS Code, imposta le variabili in claudeCode.environmentVariables, nelle impostazioni utente di VS Code stesso (comando Preferences: Open User Settings (JSON)). L’estensione verifica già lì le credenziali di accesso prima di avviarsi; i valori di ~/.claude/settings.json raggiungono il processo avviato, ma non quella verifica.

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

Prezzi per un milione di token dal catalogo Kunavo; il prezzo di listino Anthropic proviene da claude.com/pricing (verificato il 3 ottobre 2026):

Durante una sessione puoi cambiare modello con /model claude-opus-5-5, oppure avviare direttamente con claude --model claude-opus-5-5. Il costo mensile approssimativo di Claude Code e quando conviene un abbonamento sono descritti in Claude Code pricing (in inglese); puoi calcolare il tuo consumo con la calcolatrice dei token di Claude. Tutti i modelli e i prezzi sono riportati nella pagina dei prezzi.

Verifica con /status

Avvia claude. Con ANTHROPIC_AUTH_TOKEN configurata, non viene mostrata alcuna schermata di accesso: la variabile è valida immediatamente. Se la schermata compare comunque, Claude Code non ha letto alcuna chiave. Impostala in un punto che Claude Code legge prima della procedura guidata iniziale: un export nella shell o il blocco env di ~/.claude/settings.json. Un blocco env in .claude/settings.json o .claude/settings.local.json di un progetto si applica in una sessione interattiva solo dopo la procedura guidata iniziale e la richiesta di considerare attendibile la cartella.

Digita /status nella sessione e controlla due righe nella scheda Status (fonte: la documentazione ufficiale del gateway, verificata il 3 ottobre 2026):

• Anthropic base URL deve mostrare https://api.kunavo.com. Questa riga compare solo quando è configurato un indirizzo gateway; se manca, ANTHROPIC_BASE_URL non ha raggiunto la sessione.
• Auth token deve indicare ANTHROPIC_AUTH_TOKEN. Se invece vedi Login method con un account claude.ai, la variabile non è stata letta e la sessione usa il tuo abbonamento.

Se in precedenza avevi effettuato l’accesso con un abbonamento, all’avvio Claude Code può avvisare che sono attive due fonti di accesso (il messaggio termina con auth may not work as expected). Le richieste passano quindi tramite la chiave; con /logout rimuovi il vecchio accesso.

Vuoi testare indirizzo e chiave prima di aprire Claude Code? Invia, come suggerisce la documentazione, una richiesta con un solo token di output; consuma una quantità minima di credito. I comandi leggono le variabili dalla shell, quindi impostale anche lì se sono già presenti in settings.json.

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

Una risposta JSON che inizia con {"id":"msg_ significa che indirizzo e chiave funzionano; in PowerShell vedrai un id che inizia con msg_. Un 401 significa che la chiave è stata rifiutata.

Cosa cambia con una chiave API

• Niente Remote Control e niente dettatura vocale. Entrambi richiedono un account claude.ai e non sono disponibili finché ANTHROPIC_AUTH_TOKEN è attivo; inoltre Remote Control rimane disabilitato finché ANTHROPIC_BASE_URL punta a un indirizzo esterno ad Anthropic.
• /fast segnala che la modalità fast è disattivata. Con il solo bearer token, Claude Code considera la modalità fast disabilitata senza inviare la verifica.
• La ricerca degli strumenti MCP è disabilitata per impostazione predefinita quando ANTHROPIC_BASE_URL punta a un indirizzo esterno ad Anthropic.
• I valori in /context sono approssimativi: Kunavo al momento non offre /v1/messages/count_tokens. Secondo la documentazione ufficiale sulla compatibilità dei gateway (verificata il 3 ottobre 2026), senza quell'endpoint Claude Code ripiega su una stima basata sul numero di caratteri, quindi /context mostra quantità approssimative.

Codice, strumenti, subagent, server MCP, hook e prompt caching funzionano come sempre. Ulteriori dettagli sono disponibili nella documentazione sull’integrazione di Claude Code (in inglese) e in Claude Code without a subscription (in inglese).

Pagare con iDEAL o Bancontact

Un abbonamento Claude si paga tramite il sito solo con carta di credito o di debito (articolo di assistenza di Claude sugli abbonamenti a pagamento, verificato il 3 ottobre 2026); i prezzi su claude.com/pricing non includono le imposte.

Il saldo Kunavo si ricarica tramite Stripe Checkout. I prezzi sono in dollari statunitensi; per gli acquirenti nei Paesi Bassi e in Belgio, Stripe mostra l'importo in euro. Secondo la documentazione di Stripe sui prezzi adattivi (verificata il 3 ottobre 2026), il tasso di cambio include una maggiorazione di conversione del 2–4%, a carico dell'acquirente; chi paga in dollari (con carta, Apple Pay, Google Pay o Link) non paga tale maggiorazione. iDEAL e Bancontact funzionano solo in euro. Nella pagina di pagamento sono disponibili:

• iDEAL, per i Paesi Bassi. Il metodo ora si chiama iDEAL | Wero (Stripe ha chiesto di adottare questo nome nel primo trimestre del 2026), quindi potresti vedere anche questo nome nella pagina di pagamento. Verrai reindirizzato all'ambiente della tua banca e lì potrai confermare (Stripe su iDEAL, verificato il 3 ottobre 2026).
• Bancontact, per il Belgio, con la tua carta Bancontact o l'app (Stripe su Bancontact, verificato il 3 ottobre 2026).
• Carte (Visa, Mastercard), Apple Pay, Google Pay e Link.

Non disponibili: PayPal, addebito diretto SEPA, Klarna (disponibile solo per gli acquirenti negli Stati Uniti), Tikkie, Riverty (il precedente AfterPay) e un normale bonifico bancario.

1. Crea un account Kunavo.
2. In Billing scegli un importo, almeno $10. Chi ricarica una somma maggiore in un’unica volta riceve credito aggiuntivo: con $100 ottieni $110, con $1.000 ottieni $1.200 e con $5.000 ottieni $6.250.
3. Nella pagina di pagamento Stripe scegli iDEAL o Bancontact e completa il pagamento nell’ambiente della tua banca (iDEAL) oppure con l’app o la carta Bancontact. L’importo in euro è visibile nella pagina di pagamento prima della conferma.
4. Crea una chiave in /app/keys e inseriscila in ANTHROPIC_AUTH_TOKEN.

Il credito è prepagato: nessun canone mensile, il credito non scade e le richieste non riuscite non vengono addebitate. La ricarica automatica è possibile solo con una carta salvata o Link; con iDEAL e Bancontact devi quindi ricaricare manualmente ogni volta. Kunavo non emette fatture IVA; la cronologia delle ricariche è disponibile in Billing. Questi metodi di pagamento ricaricano esclusivamente il credito API Kunavo: non puoi usarli per pagare un abbonamento Claude Pro o Max. Ulteriori informazioni sui pagamenti in euro: Pagare Claude con iDEAL.

Errori comuni

Dopo l’installazione

Se avvii Claude Code per la prima volta in un progetto, digita /init: Claude Code legge il repository e crea un file CLAUDE.md con i comandi di test e le convenzioni individuate. Controlla quel file e mantienilo breve, perché viene caricato in ogni sessione. Tra attività separate, /clear avvia una nuova conversazione; se un’attività diventa lunga, /compact riassume la cronologia e puoi continuare.

Cosa devi sapere

• Questa è un’API con pagamento a token, non un abbonamento Claude Pro o Max. Chi usa Claude Code per ore ogni giorno spesso spende meno con un abbonamento; il pagamento a token è adatto a un utilizzo variabile e un mese senza attività non costa nulla. Il confronto è disponibile in Claude Code pricing (in inglese).
• Con una chiave API, Remote Control e la dettatura vocale non sono disponibili.
• Tramite Kunavo usi capacità condivisa, senza una quota riservata né garanzie contrattuali; se ne hai bisogno, stipula un contratto direttamente con Anthropic.
• iDEAL e Bancontact sono disponibili solo per le ricariche manuali; la ricarica automatica è possibile solo con una carta o Link.
• Gli importi in euro includono la maggiorazione di conversione di Stripe. Kunavo non emette fatture IVA.

Domande frequenti