Guida all'installazione di Claude Code — comandi macOS e Windows, collegamento tramite abbonamento o chiave API dopo l'installazione

L'installazione di Claude Code richiede un solo comando: su macOS, Linux e WSL esegui curl -fsSL https://claude.ai/install.sh | bash; su Windows esegui irm https://claude.ai/install.ps1 | iex in PowerShell (nel Prompt dei comandi CMD usa invece la riga install.cmd qui sotto). Dopo l'installazione, apri un nuovo terminale, usa claude --version per verificare, quindi esegui claude per iniziare. Per la prima connessione hai due possibilità: accedere con un account Pro, Max, Team, Enterprise o Console (il piano gratuito Claude.ai non include Claude Code), oppure impostare le due variabili d'ambiente ANTHROPIC_BASE_URL e ANTHROPIC_AUTH_TOKEN per usare una chiave API a consumo, senza alcun abbonamento.

Comandi verificati il 11 settembre 2026, sulla base della documentazione ufficiale di installazione di Anthropic. Questa pagina tratta solo l'installazione e la prima connessione; per l'uso quotidiano dopo l'installazione consulta il tutorial di Claude Code.

Verifiche prima dell'installazione

Installazione su macOS

Apri “Terminale” e incolla questa riga:

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

Questo è il metodo di installazione nativo consigliato ufficialmente: installa un eseguibile indipendente che si aggiorna automaticamente in background. Il punto di ingresso dell'eseguibile è ~/.local/bin/claude; i terminali già aperti non leggeranno il nuovo PATH, quindi dopo l'installazione apri una nuova finestra. Linux e WSL usano lo stesso comando.

Installazione su Windows

Windows dispone di due comandi diversi; la differenza dipende dal terminale aperto. Se il prompt è PS C:\Users\你的名字>, si tratta di PowerShell; se non contiene PS e contiene solo C:\Users\你的名字>, si tratta del Prompt dei comandi (CMD). Non è necessario eseguirli con privilegi di amministratore.

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

:: Windows 命令提示字元（CMD）
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Incollare il comando nel terminale sbagliato è il problema più comune su Windows. Se esegui la riga CMD in PowerShell, vedrai The token '&&' is not a valid statement separator; se esegui la riga PowerShell in CMD, vedrai 'irm' is not recognized as an internal or external command. Se incolli curl … | bash di macOS in PowerShell, comparirà A parameter cannot be found that matches parameter name 'fsSL'. In tutti e tre i casi basta tornare alla riga corrispondente.

È consigliabile installare anche Git for Windows: Claude Code utilizzerà il Git Bash incluso per eseguire i comandi; se non è installato, utilizzerà PowerShell. Se è installato ma Git Bash non viene trovato, aggiungi CLAUDE_CODE_GIT_BASH_PATH al blocco env del file di configurazione e impostalo sul percorso di bash.exe.

Se scegli WSL, esegui la riga macOS/Linux indicata sopra nel terminale WSL e avvia claude anch'esso in WSL, non da PowerShell o CMD.

Installazione con un gestore di pacchetti

Puoi anche lasciare che il gestore di pacchetti esistente gestisca l'installazione; il prezzo da pagare è che per impostazione predefinita non si aggiornerà automaticamente e dovrai aggiornarlo periodicamente (ad esempio brew upgrade claude-code e winget upgrade Anthropic.ClaudeCode). Debian/Ubuntu, Fedora/RHEL e Alpine dispongono inoltre di repository apt, dnf e apk ufficialmente firmati.

# Homebrew（macOS、Linux）— stable 通道
brew install --cask claude-code

# WinGet（Windows）
winget install Anthropic.ClaudeCode

# npm — 需要 Node.js 22 以上；絕對不要加 sudo
npm install -g @anthropic-ai/claude-code

L'installazione tramite npm richiede Node.js 22 o versioni successive a partire da v2.1.198; se la versione di Node.js è più vecchia, npm stampa solo l'avviso EBADENGINE, ma l'installazione viene comunque completata. Installa lo stesso eseguibile del programma di installazione nativo, che durante l'esecuzione non dipende da Node.js. Non usare mai sudo npm install -g: causa problemi di permessi e comporta anche rischi di sicurezza.

Verifica dell'installazione

claude --version   # 正常會印出版本號，例如 2.1.211 (Claude Code)
claude doctor      # 唯讀的安裝與設定診斷，不會開啟工作階段

claude doctor è il comando più importante da ricordare: non avvia una sessione di lavoro, ma elenca lo stato dell'installazione, gli errori dei file di configurazione e le correzioni consigliate. È il modo più rapido per distinguere un'installazione danneggiata da una configurazione errata.

Se compare command not found: claude, oppure 'claude' is not recognized su Windows, significa che la directory di installazione non è inclusa in PATH. Su macOS/Linux apri prima un nuovo terminale e riprova; se non basta, aggiungi ~/.local/bin al PATH di ~/.zshrc o ~/.bashrc. Il percorso di installazione su Windows è %USERPROFILE%\.local\bin; controllalo e aggiungilo con PowerShell:

# 1. 檢查安裝目錄是否已在 PATH 裡
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. 沒有任何輸出的話，把它加進「使用者」PATH，然後關掉終端機重開
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. 重開後再確認一次；若有兩份安裝，這行會列出兩個路徑
where.exe claude

Prima connessione: accesso con abbonamento o chiave a consumo

Percorso A: accedere con un account in abbonamento

Nella cartella del progetto esegui claude e segui le istruzioni del browser per accedere con un account Pro, Max, Team, Enterprise o Console. Nota un dettaglio: se nell'ambiente è già presente ANTHROPIC_API_KEY, Claude Code ti chiederà una volta se vuoi usare quella chiave; se scegli di rifiutare, in seguito la ignorerà silenziosamente e non lo chiederà più, dando l'impressione che la variabile non sia stata letta. Per riattivarla, vai a /config e seleziona Use custom API key.

Percorso B: niente abbonamento, usa una chiave a consumo

Claude Code supporta nativamente ANTHROPIC_BASE_URL, quindi indirizzarlo a qualsiasi endpoint che offra l'API Anthropic Messages è una configurazione ufficialmente supportata; non servono plugin, proxy o eseguibili modificati. I passaggi sono: registrare un account, aggiungere credito (minimo $10), creare nella pagina di gestione delle chiavi una chiave che inizi con sk-kn- (verrà mostrata una sola volta), quindi impostare le variabili qui sotto. macOS/Linux:

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # 只寫到網域，不要加 /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 una prima prova, apri una finestra PowerShell ed esegui:

# 只對這個 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 a lungo termine, è consigliabile inserire la configurazione nel profilo utente ~/.claude/settings.json, nel blocco env (su Windows è %USERPROFILE%\.claude\settings.json). Inserendola qui, ogni terminale, estensione dell'editor e processo in background potrà leggerla; se il file contiene già altre impostazioni, integra semplicemente env al loro interno:

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

In queste sei righe c’è ogni volta un punto in cui una configurazione errata può bloccare il lavoro a lungo:

• ANTHROPIC_BASE_URL deve contenere solo il dominio.Claude Code aggiunge autonomamente /v1/messages; se aggiungi /v1, diventerà /v1/v1/messages e restituirà 404.
• Usa ANTHROPIC_AUTH_TOKEN, non ANTHROPIC_API_KEY.I due valori vengono inseriti in intestazioni HTTP diverse: il primo invia Authorization: Bearer e ha effetto immediato; il secondo invia x-api-key e richiede anche la conferma una tantum descritta sopra.
• ANTHROPIC_MODEL deve contenere il nome completo e corretto del modello.Kunavo riconosce solo i nomi corrispondenti esattamente e non associa automaticamente i vecchi nomi con suffisso di data.
• ANTHROPIC_DEFAULT_OPUS_MODEL gestisce l’alias opus. Il modello predefinito di Claude Code e l’alias opus puntano entrambi all’Opus più recente; se Kunavo non lo offre ancora, restituiscono 404, quindi bisogna fissare sia questa riga sia ANTHROPIC_MODEL. Qui l’alias opus viene fissato su Opus 5.5 (claude-opus-5-5), che richiede Claude Code v2.1.280 o successivo; nelle versioni precedenti esegui claude update.
• ANTHROPIC_DEFAULT_SONNET_MODEL gestisce l’alias sonnet. Nell’API Anthropic, l’alias sonnet punta a Sonnet 5.5, ma Kunavo non offre questo modello. Se non viene fissato, /model sonnet, la fase di esecuzione di opusplan e i subagenti configurati come model: sonnet restituiscono 404; per questo va fissato anche qui su Claude Sonnet 5 (claude-sonnet-5).
• ANTHROPIC_DEFAULT_HAIKU_MODEL gestisce l'alias haiku. Dalla versione 2.1.293 di Claude Code, l'alias haiku punta a Haiku 5.5; nelle versioni precedenti punta a un ID di Haiku 4.5 con suffisso di data. Kunavo non riconosce nessuno dei due ID. Se l'alias non viene fissato a un modello, /model haiku e i subagenti impostati su model: haiku (compreso claude-code-guide, avviato da Claude Code stesso) restituiscono 404. Per questo, qui viene fissato a claude-haiku-4-5.
• ANTHROPIC_DEFAULT_HAIKU_MODEL gestisce le chiamate in background.Le sintesi e i titoli generati da Claude Code usano questo modello: Claude Haiku 4.5 per 1M token costa $0,70 / $3,50, mentre il modello principale Claude Sonnet 5 costa $1,40 / $7,00 (allo stesso prezzo ufficiale di Anthropic).

Non inserire la chiave nel progetto, in .claude/settings.json: il file verrebbe sottoposto a commit e condiviso con chiunque cloni il progetto. Se usi l'estensione VS Code, inserisci le variabili nelle impostazioni utente di VS Code, in claudeCode.environmentVariables, perché l'estensione controlla le credenziali prima dell'avvio.

Verifica del percorso utilizzato per la connessione

Dopo essere entrato in Claude Code, esegui /status. Se vedi la riga Auth token, la chiave è attiva; se vedi Login method con un account claude.ai, le variabili non sono state lette. Le due modalità non si sommano: finché le variabili della chiave sono presenti, l'abbonamento autenticato viene messo da parte; rimuovendo le variabili si torna all'abbonamento, senza reinstallare nulla.

Quando usi un gateway, tre aspetti cambiano: Remote Control e l'input vocale richiedono un'identità claude.ai e non sono disponibili; il controllo di disponibilità di /fast interroga direttamente Anthropic e potrebbe indicare che non è disponibile, mentre le richieste normali non sono interessate; i numeri di /context diventano stime locali. Scrittura del codice, strumenti, sub-agenti, MCP, hook e cache dei prompt continuano a funzionare normalmente. La spiegazione completa è disponibile nella documentazione sull'integrazione di Claude Code e nella guida alle chiavi API di Claude Code (entrambe in inglese).

Tabella degli errori comuni

Dopo l'installazione

Quando entri per la prima volta in un progetto, esegui /init per permettergli di leggere l'intero progetto e generare CLAUDE.md. Per sapere come alternare Opus, Sonnet e Haiku in base all'attività, quanto costa effettivamente una sessione e come usare /clear e /compact per ridurre la spesa, consulta il tutorial di Claude Code.

Vale la pena essere onesti anche sulla scelta del percorso: per chi interagisce a lungo ogni giorno e usa molto il servizio, il costo mensile fisso dell'abbonamento è solitamente più conveniente; la fatturazione a consumo è adatta a chi ha un utilizzo molto variabile o non vuole essere vincolato dalla finestra di utilizzo di 5 ore, e nei mesi senza attività il costo è $0. Tramite Kunavo utilizzi capacità condivisa, senza quota dedicata né SLA contrattuale; i team che necessitano di queste garanzie dovrebbero acquistare direttamente da Anthropic. I costi mensili e il punto di pareggio dei due percorsi sono in costo di Claude Code.

Domande frequenti