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

Claude Code si installa con un comando ufficiale per sistema: su macOS, Linux e WSL, curl -fsSL https://claude.ai/install.sh | bash; su Windows, in PowerShell, irm https://claude.ai/install.ps1 | iex (nel prompt dei comandi, CMD, la riga di install.cmd più sotto). Dopo l'installazione ci sono due modi per usarlo. Con un abbonamento, accedi con un account Pro, Max, Team, Enterprise o Console (chi ha solo il piano gratuito di Claude.ai non può accedere a Claude Code). Senza abbonamento, usa una chiave API: imposta ANTHROPIC_BASE_URL (solo il dominio, senza /v1), ANTHROPIC_AUTH_TOKEN e quattro variabili del modello, quindi verifica con /status. Il saldo Kunavo si ricarica con MB WAY nel checkout in euro, a partire da US$ 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. Il Portogallo figura nell'elenco dei paesi supportati da Anthropic (consultato il 3 ottobre 2026), sia per Claude.ai sia per l'API. Questa guida è disponibile anche in inglese: Install Claude Code.

Prima dell'installazione

macOS, Linux e WSL: una sola riga

Nel Terminale (su macOS si trova in Applicazioni › Utility), esegui:

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

È l'installazione nativa consigliata: un programma autonomo che, secondo la documentazione ufficiale, si aggiorna automaticamente in background. Il comando claude si trova in ~/.local/bin. Un terminale già aperto non conosce ancora il nuovo PATH, quindi apri una nuova finestra prima di eseguire il test. In WSL, la riga è esattamente la stessa, eseguita all'interno del terminale WSL.

Installazione su Windows

Su Windows ci sono due righe e la scelta dipende solo dalla finestra aperta. Se la riga inizia con PS C:\Users\Nome>, sei in PowerShell; se compare solo C:\Users\Nome>, senza PS, sei nel prompt dei comandi (CMD). Non è necessario usare «Esegui come amministratore»: la documentazione ufficiale afferma esplicitamente che non è necessario, contrariamente a quanto raccomandano alcune guide in portoghese.

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

:: Linha de Comandos do Windows (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Su Windows, l'errore più frequente è usare la finestra sbagliata. Se PowerShell risponde The token '&&' is not a valid statement separator, hai ricevuto la riga del CMD; se il CMD risponde 'irm' is not recognized as an internal or external command, hai ricevuto quella di PowerShell. In un Windows in portoghese, questo secondo messaggio può apparire tradotto, con la stessa causa. Inoltre, incollando la riga di macOS con | bash in PowerShell, compare un errore che indica che bash non è riconosciuto. In tutti e tre i casi, la soluzione è usare la riga corrispondente alla finestra.

Git for Windows è facoltativo. Con esso, lo strumento Bash di Claude Code viene eseguito in Git Bash, mentre PowerShell continua a essere disponibile; senza di esso, tutti i comandi vengono eseguiti tramite PowerShell. Quando Git è installato in una cartella non standard e Claude Code non trova bash.exe, si indica il percorso in CLAUDE_CODE_GIT_BASH_PATH, all'interno del blocco env di ~/.claude/settings.json; l'esempio fornito dalla documentazione è C:\Program Files\Git\bin\bash.exe.

WSL è quindi una scelta, non un requisito, contrariamente a quanto si legge in alcune guide. Chi sceglie WSL esegue la riga macOS/Linux nel terminale WSL e avvia claude anch'esso lì, non da PowerShell né dal CMD.

Tramite Homebrew, WinGet o npm

Funziona anche in questo modo, con una differenza importante: secondo la documentazione ufficiale, le installazioni tramite Homebrew e WinGet non si aggiornano automaticamente. L'aggiornamento deve essere eseguito manualmente. Esistono inoltre repository apt, dnf e apk firmati per Linux.

# Homebrew
brew install --cask claude-code
brew upgrade claude-code              # não se atualiza sozinho

# WinGet (Windows)
winget install Anthropic.ClaudeCode
winget upgrade Anthropic.ClaudeCode   # não se atualiza sozinho

Il pacchetto npm richiede Node.js 22 o successivo, non Node.js 18 ancora indicato in alcune guide. Con una versione precedente di Node.js, npm mostra solo un avviso EBADENGINE durante l'installazione invece di interrompersi. Non usare mai sudo npm install -g: la documentazione ufficiale lo sconsiglia esplicitamente. Per aggiornare, usa @latest, non npm update -g.

node -v                                           # tem de ser v22 ou posterior
npm install -g @anthropic-ai/claude-code          # nunca com sudo

# para atualizar mais tarde: com @latest, não com npm update -g
npm install -g @anthropic-ai/claude-code@latest

Verifica dell'installazione

claude --version   # mostra o número da versão, seguido de (Claude Code)
claude doctor      # diagnóstico só de leitura da instalação e das definições, sem abrir sessão

claude doctor non avvia alcuna sessione: mostra lo stato dell'installazione e dei file di configurazione. È il modo più rapido per capire se il problema riguarda l'installazione o la configurazione.

Un messaggio command not found: claude (oppure, su Windows, l'indicazione che claude non è un comando riconosciuto) significa che il terminale non sa dove è stato installato il programma. Spesso basta chiudere la finestra e aprirne un'altra. Se il problema persiste, la cartella non è inclusa nel PATH: su macOS e Linux è ~/.local/bin, da aggiungere al file di avvio della shell (~/.zshrc o ~/.bashrc); su Windows è %USERPROFILE%\.local\bin. Secondo la guida ufficiale alla risoluzione dei problemi, ecco come verificarlo e aggiungerlo in PowerShell:

# 1. A pasta de instalação já está no PATH?
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Sem resultado? Acrescente-a ao PATH do utilizador e abra uma janela nova
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. Na janela nova: dois caminhos significam duas instalações lado a lado
where.exe claude

Se hai installato tramite npm e PowerShell risponde npm.ps1 cannot be loaded because running scripts is disabled on this system, è la politica di esecuzione di PowerShell a bloccare gli script npm. Usa l'installatore nativo oppure consenti gli script locali per il tuo utente:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Se compare Claude Code does not support 32-bit Windows, è stato aperto «Windows PowerShell (x86)». Windows dispone di due voci PowerShell e la versione x86 viene eseguita come processo a 32 bit; apri la voce «Windows PowerShell», senza (x86).

Primo utilizzo: abbonamento o chiave API

Al primo avvio si decide come viene pagato Claude Code. Non è necessario reinstallarlo per cambiare modalità: ciò che conta è la presenza o meno di una chiave definita.

Percorso A — accesso con l'abbonamento

Nella cartella del progetto, esegui claude e accedi nel browser. Attenzione se nell'ambiente è già presente ANTHROPIC_API_KEY: invece di aprire il browser, Claude Code richiede un'unica approvazione per quella chiave. Dopo il rifiuto, la chiave viene ignorata da quel momento in poi e la domanda non viene ripetuta, facendo sembrare che la variabile non venga letta. Per riattivarla: /config → Use custom API key.

Percorso B — senza abbonamento, con chiave API

ANTHROPIC_BASE_URL è una variabile di Claude Code pensata per instradare le richieste tramite un proxy o un gateway. Indicarla a un endpoint compatibile con la Messages API di Anthropic è quindi una configurazione supportata, senza plug-in né versioni modificate. Procedi come segue:

1. Crea un account Kunavo.
2. Ricarica il saldo in Fatturazione, a partire da US$ 10 (il pagamento con MB WAY è spiegato più sotto).
3. In /app/keys, crea una chiave che inizia con sk-kn-. Viene mostrata una sola volta, quindi è consigliabile salvarla subito.
4. Imposta le variabili. Su macOS e Linux, in ~/.zshrc o ~/.bashrc:

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # só o domínio, sem /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 effettuare prima un test in una finestra di PowerShell:

# Vale só para esta janela do 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

Per l'uso permanente, il posto migliore è il blocco env nelle impostazioni dell'utente: ~/.claude/settings.json (su Windows, %USERPROFILE%\.claude\settings.json). Qui i valori si applicano a tutti i progetti, inclusi gli agenti in background; l'estensione VS Code è l'eccezione (vedi sotto). Una variabile esportata nella shell viene ereditata solo dai programmi avviati da quella shell: un editor aperto dal Dock o dal menu Start non la vede. Se il file contiene già 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 sui gateway (consultata il 3 ottobre 2026), questo file viene incluso nei commit e condiviso con chiunque cloni il repository. Presta inoltre attenzione alla precedenza: quando la shell e un file delle impostazioni definiscono la stessa variabile, prevale il file delle impostazioni. Se una modifica nella shell non ha effetto, controlla prima il settings.json.

Chi usa l'estensione VS Code imposta le variabili in claudeCode.environmentVariables, nelle impostazioni utente di VS Code stesso (comando Preferences: Open User Settings (JSON)). Secondo la documentazione dei gateway, l'estensione verifica le credenziali in questa impostazione prima dell'avvio; i valori di ~/.claude/settings.json arrivano al processo di Claude Code, ma non a 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" }
  ]
}

Le quattro variabili del modello e altre trappole

Ogni riga del blocco nasconde una trappola:

• In ANTHROPIC_BASE_URL non va inserito il percorso. Il percorso /v1/messages viene aggiunto direttamente da Claude Code; un indirizzo che termina già con /v1 diventa /v1/v1/messages, che restituisce 404.
• ANTHROPIC_AUTH_TOKEN o ANTHROPIC_API_KEY: Kunavo accetta entrambi. Secondo la documentazione dei gateway, ANTHROPIC_AUTH_TOKEN viene inviato nell'intestazione Authorization: Bearer e si applica immediatamente; ANTHROPIC_API_KEY viene inviato nell'intestazione x-api-key e, in modalità interattiva, deve essere approvato una volta prima di diventare attivo (vedi Percorso A). Per questo questa guida usa ANTHROPIC_AUTH_TOKEN.
• Il nome in ANTHROPIC_MODEL deve essere esatto. Copialo esattamente come appare qui: claude-sonnet-5.
• Senza ANTHROPIC_DEFAULT_SONNET_MODEL e ANTHROPIC_DEFAULT_OPUS_MODEL, gli alias cambiano da soli. Secondo la documentazione sulla configurazione dei modelli (consultata il 3 ottobre 2026), per chi usa l'API di Anthropic l'alias opus punta a Opus 5.5 e l'alias sonnet a Sonnet 5.5; questi alias cambiano con le nuove versioni. Per fissarli si usa il nome completo del modello o variabili come ANTHROPIC_DEFAULT_OPUS_MODEL. Kunavo non offre Sonnet 5.5 e un modello inesistente restituisce 404: senza ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5, falliscono /model sonnet, i subagenti con model: sonnet e la fase di esecuzione di opusplan. Invece opus punta a claude-opus-5-5, disponibile su Kunavo, ma solo a partire da Claude Code v2.1.280; chi usa una versione precedente deve eseguire claude update.
• Imposta anche ANTHROPIC_DEFAULT_HAIKU_MODEL. L'alias haiku richiede un ID che Kunavo non fornisce: dalla v2.1.293 è Haiku 5.5 e, prima, un ID di Haiku 4.5 con data. Senza questa riga, /model haiku e i sottoagenti con model: haiku restituiscono 404.
• ANTHROPIC_DEFAULT_HAIKU_MODEL vale anche per le attività in background. Secondo la documentazione, definisce l'alias haiku e il modello delle funzioni in background di Claude Code. Con Claude Haiku 4.5, queste chiamate usano il modello meno costoso della tabella seguente.

Prezzi per milione di token dal catalogo Kunavo; la colonna di Anthropic proviene da claude.com/pricing (consultato 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 calcolo in euro, con esempi di utilizzo mensile e il punto a partire dal quale conviene di più un abbonamento, è disponibile in Prezzo di Claude Code in euro; puoi calcolare il consumo individuale con la calcolatrice dei costi dei token. Tutti i modelli e i prezzi sono nella pagina dei prezzi.

Confermare con /status

Esegui claude. Con ANTHROPIC_AUTH_TOKEN definita, non viene visualizzata la schermata di accesso: la variabile si applica immediatamente. Se compare la schermata di accesso, Claude Code non ha letto alcuna chiave. In tal caso, definiscila in un punto che Claude Code legge prima della procedura guidata del primo avvio: un export nella shell oppure il blocco env di ~/.claude/settings.json. Un blocco env in .claude/settings.json o in .claude/settings.local.json di un progetto si applica, in una sessione interattiva, solo dopo la procedura guidata del primo avvio e la domanda sulla fiducia nella cartella.

All'interno della sessione, digita /status e cerca due righe nella scheda Status (fonte: la documentazione ufficiale sui gateway, consultata il 3 ottobre 2026):

• Anthropic base URL deve mostrare https://api.kunavo.com. Questa riga compare solo quando è definito un indirizzo del gateway; se manca, ANTHROPIC_BASE_URL non è arrivata alla sessione.
• La riga Auth token deve indicare ANTHROPIC_AUTH_TOKEN. Se invece compare Login method con un account claude.ai, la variabile non è stata letta e la sessione sta usando l'abbonamento.

Chi aveva già effettuato l'accesso con un abbonamento può visualizzare, all'avvio, un avviso che indica la presenza di due credenziali attive (il messaggio termina con auth may not work as expected). Le richieste passano attraverso la chiave; /logout cancella il vecchio accesso.

Per testare indirizzo e chiave prima di aprire Claude Code, la documentazione suggerisce una richiesta con un singolo token di output, che consuma una frazione infinitesimale del saldo. I comandi leggono le variabili della shell, quindi definiscile anche lì, anche 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 compare un id che inizia con msg_. Un 401 significa che la chiave non è stata riconosciuta.

Cosa cambia con una chiave API

• Senza Remote Control né dettatura vocale. Secondo la documentazione sui gateway, non sono disponibili quando sono attivi ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN o un apiKeyHelper; Remote Control viene inoltre disattivato quando ANTHROPIC_BASE_URL punta a un indirizzo esterno ad Anthropic.
• Il comando /fast mostra la modalità rapida come disattivata. Con un solo bearer token, Claude Code considera la modalità rapida disattivata.
• La ricerca degli strumenti MCP (MCP tool search) è disattivata per impostazione predefinita quando ANTHROPIC_BASE_URL punta a un indirizzo esterno ad Anthropic (documentazione sulle variabili d'ambiente, consultata il 3 ottobre 2026).
• I numeri di /context sono stime. Kunavo non supporta /v1/messages/count_tokens e, secondo la documentazione sulla compatibilità dei gateway (consultata il 3 ottobre 2026), senza questo endpoint Claude Code ricorre a una stima basata sul numero di caratteri.

Il resto — codice, strumenti, sottoagenti, server MCP, hook e memorizzazione nella cache dei prompt — funziona come sempre. Maggiori dettagli nella documentazione sull'integrazione di Claude Code (in inglese) e in Claude Code without a subscription (in inglese).

Ricaricare il saldo con MB WAY

Per prima cosa, l’abbonamento: un abbonamento Claude acquistato sul sito si paga solo con carta di credito o di debito (articolo di assistenza Anthropic sui piani a pagamento, consultato il 3 ottobre 2026); per un abbonamento sottoscritto nell’app Claude per iOS o Android, i metodi di pagamento sono quelli dell’App Store o di Google Play. I metodi di pagamento Kunavo, MB WAY incluso, non pagano Claude Pro né Max: ricaricano il saldo API di Kunavo, che è quello usato dalla Rotta B.

Il saldo si ricarica al checkout di Stripe. I prezzi sono in dollari statunitensi; per chi acquista in Portogallo, Stripe mostra l’importo in euro. Secondo la documentazione di Stripe su Adaptive Pricing (consultata il 3 ottobre 2026), questa conversione include una commissione del 2–4% a carico dell’acquirente; chi sceglie di pagare in dollari (con carta, Apple Pay, Google Pay o Link) non paga questa commissione, anche se la banca potrebbe applicare il proprio tasso di cambio e le proprie commissioni. MB WAY funziona solo in euro. Al checkout in euro sono disponibili:

• MB WAY. Si seleziona MB WAY, si inserisce il numero di cellulare e si conferma l’acquisto nell’app MB WAY, tramite la notifica o nella sezione attività (Stripe su MB WAY e MB WAY sugli acquisti online, consultati il 3 ottobre 2026). Secondo Stripe, sono accettati numeri internazionali, ma la maggior parte dei clienti usa un numero portoghese, che inizia con +351.
• Carte (Visa, Mastercard), Apple Pay, Google Pay e Link.

Non sono disponibili: i riferimenti Multibanco (pagamento tramite ente e riferimento), PayPal, l’addebito diretto SEPA e Klarna, disponibile solo per gli acquirenti negli Stati Uniti. La conversione in euro è gestita da Adaptive Pricing di Stripe, e l’elenco dei metodi di pagamento che mette a disposizione include MB WAY ma non Multibanco. MB WAY permette anche di generare carte virtuali MB NET per gli acquisti online (MB WAY su MB NET, consultato il 3 ottobre 2026); non è confermato che il campo della carta al checkout le accetti, quindi la soluzione più sicura è selezionare direttamente MB WAY.

Ciò che Stripe documenta su MB WAY (consultato il 3 ottobre 2026):

• Per pagamento: tra 0,50 € e 5000 €.
• Al giorno: 1000 € per impostazione predefinita, regolabile fino a 10.000 € nell'app MB WAY. Le ricariche più consistenti possono superare il limite giornaliero predefinito; in tal caso, aumentalo nell'app prima di pagare. Confronta l'importo in euro mostrato dal checkout con questi limiti.
• Pagamenti ricorrenti: non supportati.
• Nell'estratto conto compare il nome di Stripe (Stripe Inc), insieme all'importo dell'operazione.

1. Crea un account Kunavo.
2. In Fatturazione, scegli un importo a partire da US$ 10. Le ricariche più consistenti includono saldo aggiuntivo: chi carica US$ 100 riceve US$ 110; chi carica US$ 1000 riceve US$ 1200; chi carica US$ 5000 riceve US$ 6250.
3. Nel checkout di Stripe, con l'importo in euro, scegli MB WAY, inserisci il numero di cellulare e conferma l'acquisto nell'app MB WAY. L'importo in euro viene mostrato prima della conferma.
4. In /app/keys, crea la chiave e inseriscila in ANTHROPIC_AUTH_TOKEN.

Il saldo è prepagato: non c'è alcun canone mensile, il saldo non scade e le richieste non riuscite non vengono addebitate. La ricarica automatica funziona solo con una carta salvata o con Link; con MB WAY, la ricarica deve sempre essere effettuata manualmente perché, secondo Stripe, MB WAY non accetta pagamenti ricorrenti né viene salvato per pagamenti futuri. Kunavo non emette fatture, né con NIF né con IVA; la cronologia delle ricariche è disponibile in Billing. Questi metodi di pagamento ricaricano solo il saldo dell'API Kunavo. Maggiori informazioni in Pagare Claude con MB WAY.

Errori comuni

Dopo l'installazione

Al primo avvio in un progetto, digita /init: Claude Code esamina il repository e scrive un CLAUDE.md con ciò che ha dedotto: come eseguire il progetto, come testare le modifiche e quali regole di stile seguire. Esamina questo file e mantienilo breve, perché viene caricato in tutte le sessioni. Tra attività indipendenti, /clear avvia una nuova conversazione; durante un'attività lunga, /compact riassume la cronologia per continuare.

Cosa conviene sapere

• È un'API a pagamento in base ai token, non un abbonamento Claude Pro o Max. Chi usa Claude Code per diverse ore ogni giorno di solito paga meno con un abbonamento; pagare in base ai token conviene con un utilizzo irregolare, e un mese senza utilizzo non costa nulla. Il confronto in euro è disponibile in Prezzo di Claude Code in euro.
• Chi lavora con una chiave API non ha accesso a Remote Control né alla dettatura vocale.
• Tramite Kunavo si utilizza capacità condivisa, senza quota riservata né garanzie contrattuali; chi ne ha bisogno deve stipulare un contratto direttamente con Anthropic.
• MB WAY serve solo per le ricariche manuali; la ricarica automatica richiede una carta o Link.
• Gli importi in euro mostrati nel checkout includono già la commissione di conversione di Stripe.

Domande frequenti