Installer Claude Code sur Windows, Mac et Linux : clé API sans abonnement et paiement avec Satispay

Pour installer Claude Code, une seule commande suffit, différente selon le terminal : la ligne avec install.sh sur macOS, Linux et WSL, irm … | iex dans PowerShell, la ligne avec install.cmd dans l’invite de commandes. C’est la méthode recommandée par Anthropic ; npm reste possible, mais nécessite Node.js 22 ou une version ultérieure. Le forfait gratuit de Claude n’inclut pas Claude Code ; il faut donc un abonnement Pro ou supérieur, ou une clé API. Ici, vous suivez la seconde option : ANTHROPIC_BASE_URL=https://api.kunavo.com (sans /v1), la clé dans ANTHROPIC_AUTH_TOKEN, quatre variables qui fixent les modèles et /status pour la vérification finale. Le crédit est rechargé avec Satispay en euros à partir de $10 et vous ne payez que les tokens consommés.

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

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

:: Windows – Prompt dei comandi (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Da dove vengono questi comandi: la documentazione di Claude Code esiste anche in italiano e l'abbiamo riletta il 3 octobre 2026, in particolare le pagine su installation e passerelle LLM. Prezzi e metodi di pagamento di Kunavo sono aggiornati al 3 octobre 2026. Anthropic serve l'Italia sia su Claude.ai sia con l'API (pays pris en charge, letto il 3 octobre 2026).

Ce qu’il faut

I requisiti della documentation officielle (letta il 3 octobre 2026) sono bassi:

• macOS 13.0 ou version ultérieure ; Windows 10 1809 ou version ultérieure, ou Windows Server 2019 ou version ultérieure ; Ubuntu 20.04+, Debian 10+ ou Alpine Linux 3.19+.
• Au moins 4 Go de RAM et un processeur x64 ou ARM64. Windows 32 bits n’est pas pris en charge.
• Un shell parmi Bash, Zsh, PowerShell et CMD.
• Une connexion depuis un pays pris en charge par Anthropic : l’Italie en fait partie.
• Node.js uniquement si vous choisissez npm, auquel cas la version 22 ou ultérieure est requise.

Quelle commande, dans quel terminal

Les droits d’administrateur et WSL ne sont pas nécessaires : la documentation officielle l’indique explicitement, même si plusieurs guides disponibles en ligne suggèrent le contraire. Une fois installé, Claude Code se met à jour automatiquement en arrière-plan. Si vous préférez un gestionnaire de paquets, vous pouvez utiliser Homebrew ou WinGet, en sachant que vous devrez alors lancer vous-même les mises à jour :

# Homebrew – canale stable; non si aggiorna da solo
brew install --cask claude-code

# WinGet (Windows) – non si aggiorna da solo
winget install Anthropic.ClaudeCode

Avant d’essayer, fermez le terminal et ouvrez-en un nouveau : seule une nouvelle fenêtre relit le PATH. Vérifiez ensuite. claude doctor sera également utile plus tard, car il contrôle l’installation et les paramètres sans ouvrir de session et vous indique immédiatement si le problème concerne l’un ou l’autre.

claude --version   # stampa la versione, ad esempio 2.1.284 (Claude Code)
claude doctor      # diagnostica di installazione e impostazioni, senza aprire una sessione

Téléchargement bloqué : 403 ou page HTML à la place du script

Quando lo script non arriva, il terminale non lo dice in modo chiaro: bash si lamenta con syntax error near unexpected token '<' (sta cercando di eseguire una pagina web), oppure curl si ferma su curl: (22) The requested URL returned error: 403. La page officielle consacrée aux problèmes d’installation (in inglese, letta il 3 octobre 2026) distingue due casi. Se la pagina scaricata dice App unavailable in region, il server crede che ti colleghi da un paese escluso: dall'Italia capita quasi sempre per una VPN o un proxy che esce all'estero. Un 403 senza testo arriva più spesso da un proxy aziendale o da un firewall. Cambiare metodo di installazione non aiuta, perché Homebrew e WinGet scaricano dagli stessi server: prova da un'altra rete oppure chiedi all'IT di sbloccare quei domini.

Avec npm : Node.js 22, pas 18

Se Node.js lo usi già tutti i giorni, npm sembra la scelta naturale. Funziona ed è tra i metodi documentati, con una condizione che molte guide in italiano non hanno aggiornato: ci vuole Node.js 22 o successivo. Con un Node più vecchio vedrai l'avviso EBADENGINE, però l'installazione arriva in fondo e claude parte lo stesso (documentation officielle, letta il 3 octobre 2026). Le versioni aggiornate di Node sono su nodejs.org.

node -v                                    # serve v22 o successiva
npm install -g @anthropic-ai/claude-code   # senza sudo

# aggiornamento: @latest, non npm update -g
npm install -g @anthropic-ai/claude-code@latest

Trois habitudes à éviter :

• sudo devant npm install -g. La documentation le déconseille, à la fois en raison des problèmes de permissions et pour des raisons de sécurité.
• npm update -g pour mettre à jour. Répétez plutôt l’installation avec @latest, comme dans la dernière ligne ci-dessus.
• Ignorer les dépendances facultatives. Il binario di Claude Code arriva proprio come dipendenza facoltativa, un pacchetto @anthropic-ai/claude-code-* per ogni piattaforma. Con --omit=optional, o con optional=false nel file .npmrc, non viene scaricato e su macOS o Linux claude risponde claude native binary not installed (problèmes d’installation, in inglese, letta il 3 octobre 2026).

Claude Code sous Windows : les points de blocage

Su Windows Claude Code gira in modo nativo, e l'installazione in sé è la parte facile. I problemi nascono dall'ambiente. Il primo è il terminale: se incolli in PowerShell la riga per CMD, PowerShell protesta per il &&; se incolli in CMD la riga per PowerShell, CMD non sa cosa sia irm; e la riga curl … | bash del Mac in PowerShell non funziona proprio. Su un Windows in italiano alcuni di questi messaggi possono comparire tradotti. In ogni caso la soluzione è tornare alla tabella qui sopra e prendere la riga del terminale che hai davanti (i messaggi in inglese sono nella tabella degli errori in fondo; fonte: documentation, letta il 3 octobre 2026).

Vérifiez également le menu Démarrer : « Windows PowerShell (x86) » ouvre un processus 32 bits et Claude Code s’arrête avec Claude Code does not support 32-bit Windows, même si l’ordinateur est en 64 bits. Choisissez l’entrée sans (x86).

Git for Windows non è obbligatorio. Se è installato, Claude Code esegue i comandi attraverso Git Bash; se manca, usa PowerShell. Quando Git c'è ma Claude Code non trova bash.exe, indicagli il percorso con CLAUDE_CODE_GIT_BASH_PATH nel blocco env di ~/.claude/settings.json, di solito C:\Program Files\Git\bin\bash.exe. E WSL? Serve solo in un caso preciso:

Avec WSL, tout se passe dans Linux : la ligne install.sh doit être exécutée dans le shell WSL, puis vous lancez claude depuis celui-ci.

« claude » est introuvable

Si, après l’installation, le terminal répond command not found: claude ou 'claude' is not recognized, le programme est présent mais son dossier ne figure pas dans le PATH. L’installateur natif le copie dans ~/.local/bin/claude sous macOS et Linux et dans %USERPROFILE%\.local\bin\claude.exe sous Windows. Premier essai : ouvrez un nouveau terminal. Si cela ne suffit pas sous Windows, voici les commandes PowerShell de la documentation pour vérifier et ajouter le dossier au PATH de l’utilisateur :

# 1. Controlla se la cartella di installazione è già nel PATH
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Nessun risultato? Aggiungila al PATH utente, poi chiudi e riapri il terminale
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. Nel nuovo terminale
claude --version

npm.ps1 cannot be loaded dans PowerShell

Cela concerne uniquement les installations avec npm : les stratégies d’exécution (execution policy) de PowerShell bloquent le script .ps1 créé par npm, et le message complet contient running scripts is disabled on this system. La documentation indique trois solutions : autoriser l’utilisateur actuel à exécuter des scripts locaux avec la commande ci-dessous, lancer npm.cmd et claude.cmd à la place des scripts PowerShell, ou abandonner npm et utiliser l’installateur natif.

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Sans abonnement : compte Claude ou clé API

Installato non vuol dire pronto: al primo avvio Claude Code chiede di autenticarsi, e il piano gratuito di Claude.ai non basta (documentation, letta il 3 octobre 2026). Le due strade a confronto:

Esiste anche la chiave della Console di Anthropic, sempre a consumo. Lì però i crediti prepagati scadono dopo un anno e non si rimborsano (assistance Anthropic, letto il 3 octobre 2026); si paga con carta, mentre il bonifico ACH è riservato agli account API con fatturazione mensile (assistance Anthropic). Il credito Kunavo non ha scadenza.

Configurer la clé API : six variables

Che Claude Code parli con un endpoint diverso da quello di Anthropic è previsto: la documentazione ufficiale ha una pagina, tradotta anche in italiano, su come le connecter à une passerelle LLM. Nessun plugin, nessuna versione modificata. Bastano queste variabili:

Sur macOS et Linux, ajoutez-les à la fin de ~/.zshrc ou ~/.bashrc :

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # solo il dominio, senza /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

Sous Windows, pour un test rapide qui dure aussi longtemps que la fenêtre PowerShell :

# Vale solo in questa finestra di PowerShell: chiusa la finestra, sparisce
$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

Pour ne pas devoir les redéfinir à chaque fois, l’emplacement approprié est le bloc env de ~/.claude/settings.json (sous Windows %USERPROFILE%\.claude\settings.json) : cela s’applique à tous vos projets. Si le fichier contient déjà d’autres paramètres, ajoutez uniquement 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"
  }
}

AUTH_TOKEN ou API_KEY ?

Kunavo legge la chiave da tutti e due gli header, Authorization: Bearer e x-api-key, quindi in teoria vanno bene entrambe le variabili. La differenza la fa Claude Code. Con ANTHROPIC_API_KEY, inviata come x-api-key, la sessione interattiva ti chiede una volta se approvare la chiave; se rispondi no, la ignora senza dire nulla finché non la riattivi da /config → Utiliser une clé API personnalisée. ANTHROPIC_AUTH_TOKEN non chiede niente, ed è anche la variabile che la documentation sur les passerelles (letta il 3 octobre 2026) suggerisce quando non sai quale scegliere.

Pourquoi verrouiller les modèles

Senza variabili Claude Code ragiona per alias, e gli alias seguono le uscite di Anthropic. Oggi, secondo la documentation sur la configuration des modèles (letta il 3 octobre 2026), per chi usa l'API opus corrisponde a Opus 5.5 e sonnet a Sonnet 5.5. Kunavo, al 3 octobre 2026, non offre Sonnet 5.5: senza ANTHROPIC_DEFAULT_SONNET_MODEL, /model sonnet, la fase esecutiva di opusplan e i subagent con model: sonnet chiederebbero un modello che su Kunavo non c'è e tornerebbero 404. Con claude-sonnet-5 in quella variabile l'alias punta a Claude Sonnet 5, lo stesso modello di ANTHROPIC_MODEL. Quest'ultima decide invece il modello della sessione: senza, Claude Code partirebbe dal suo predefinito, oggi Opus 5.5. Opus 5.5 è disponibile, e fissare opus su claude-opus-5-5 serve a un'altra cosa: evitare che modello e tariffa cambino da un giorno all'altro quando l'alias passerà a un Opus successivo. Claude Opus 5.5 richiede Claude Code 2.1.280 o successivo; con una versione più vecchia, lancia prima claude update.

Les tarifs Kunavo des trois modèles de la configuration, par million de tokens (entrée / sortie) : Claude Sonnet 5 $1,40 / $7,00 (tarif catalogue Anthropic : $2,00 / $10,00) ; Claude Opus 5.5 $2,80 / $14,00 ; Claude Haiku 4.5 $0,70 / $3,50, qui fonctionne également en arrière-plan.

Où ne pas la placer et quel paramètre prend le dessus

Il .claude/settings.json dentro il progetto viene committato: una chiave scritta lì finisce nel repository e arriva a chiunque lo cloni (documentation sur les passerelles). Se una variabile compare sia nella shell sia nel blocco env di un file di impostazioni, prevale il file: quando una modifica a ~/.zshrc sembra ignorata, il motivo è quasi sempre lì. Il campo model del file di impostazioni, invece, cede il passo ad ANTHROPIC_MODEL. Nell'estensione di Claude Code per VS Code le stesse variabili vanno in claudeCode.environmentVariables, nelle impostazioni utente di VS Code. L'app desktop di Claude resta fuori da tutto questo: non legge né ANTHROPIC_BASE_URL né settings.json (documentation sur les passerelles, letta il 3 octobre 2026).

Premier démarrage et vérification avec /status

Se la chiave è al suo posto, claude parte sans écran de connexion: restano solo la configurazione iniziale e la domanda se ti fidi della cartella. Se invece compare il login, Claude Code non ha trovato la chiave. Il caso tipico è la chiave scritta solo nel .claude/settings.json o nel .claude/settings.local.json del progetto: in modalità interattiva quel blocco env entra in gioco solo dopo la configurazione iniziale e la conferma di fiducia (documentation sur les passerelles, letta il 3 octobre 2026), quindi al primo avvio non c'è ancora. Spostala nella shell o nel file utente. Un vecchio login Pro o Max non dà fastidio, perché la variabile ha la precedenza sull'accesso salvato; se vuoi cancellarlo, c'è /logout.

Dans la session, saisissez /status. Deux lignes sont importantes :

• Anthropic base URL, qui apparaît uniquement lorsqu’une passerelle est configurée : elle doit indiquer https://api.kunavo.com. Si elle n’apparaît pas, ANTHROPIC_BASE_URL n’est pas parvenue jusqu’à la session.
• Auth token avec le nom ANTHROPIC_AUTH_TOKEN : vous utilisez la clé. Si vous trouvez à la place Login method avec un compte claude.ai, la variable a été ignorée.

Vous voulez vérifier avant même d’ouvrir Claude Code ? La documentation propose une requête minimale, avec 1 token de sortie, qui déduit un montant négligeable du crédit. La commande lit les variables du shell actuel : si la clé se trouve uniquement dans settings.json, exportez-la d’abord dans ce terminal. Si elle renvoie un JSON qui commence par {"id":"msg_, tout est en ordre ; 401 signifie que la clé a été refusée.

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

Dans PowerShell, le même test est le suivant, et la bonne réponse contient un id qui commence par 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": "."}]}'

Ce que vous perdez avec la clé API

• Remote Control et dictée vocale. Ils nécessitent une identité claude.ai et ne fonctionnent pas avec ANTHROPIC_AUTH_TOKEN ou ANTHROPIC_API_KEY ; depuis la version 2.1.196, Remote Control est également désactivé lorsque ANTHROPIC_BASE_URL pointe vers un hôte qui n’est pas celui d’Anthropic.
• Le mode /fast. Avec le seul token bearer, Claude Code le considère comme désactivé et n’essaie même pas de le demander.
• La recherche des outils MCP au démarrage. Con un ANTHROPIC_BASE_URL personalizzato parte spenta (documentation MCP, in inglese, letta il 3 octobre 2026). Si riaccende con ENABLE_TOOL_SEARCH=true se il gateway inoltra i blocchi tool_reference; con Kunavo non l'abbiamo provato.
• La précision de /context. Kunavo non espone /v1/messages/count_tokens, un endpoint facoltativo secondo la spécification des passerelles (letta il 3 octobre 2026); senza, Claude Code stima i token a partire dai caratteri.

Pour aller plus loin, en anglais : la documentation de l’intégration avec Claude Code, la page consacrée aux cas limites de ANTHROPIC_BASE_URL et le guide Install Claude Code.

Payer avec Satispay, sans carte bancaire

Prima una precisazione, perché è la domanda più frequente: Satispay non paga l'abbonamento Claude. Per Pro e Max comprati sul web Anthropic accetta solo carte di credito o di debito (assistance Anthropic) e non accetta PayPal (assistance Anthropic), entrambi letti il 3 octobre 2026. Su Kunavo Satispay ricarica invece il credito API che Claude Code consuma con la chiave configurata sopra. Tutti i dettagli, compresi i costi per caricare la Disponibilità, sono nella guida payer Claude avec Satispay. Per Claude Code la sequenza è questa:

1. Inscrivez-vous sur Kunavo avec votre adresse e-mail ou un compte Google : aucune carte requise.
2. Ouvrez Facturation et choisissez le montant à recharger : minimum $10, aucuns frais d’abonnement. Au-delà de certains seuils, un bonus est accordé : $100 diventano $110, $1.000 diventano $1.200, $5.000 diventano $6.250 de crédit.
3. Nel checkout di Stripe, che mostra l'importo in euro, scegli Satispay. Si passa alla pagina di Satispay (documentation Stripe): numero di cellulare o QR code dall'app, poi conferma con Envoyer (support Satispay, letto il 3 octobre 2026). Meglio avere già abbastanza Disponibilità prima di cominciare.
4. Le crédit apparaît dans Facturation dès que Stripe confirme le paiement. S’il n’apparaît pas immédiatement, actualisez la page au lieu de payer à nouveau : un second paiement s’ajoute au crédit, il ne remplace pas le premier.
5. Dans Clés API, générez la clé sk-kn-… et copiez-la immédiatement dans ANTHROPIC_AUTH_TOKEN : elle n’est affichée qu’une seule fois.

Kunavo fissa i prezzi in dollari e Stripe li converte in euro con una commission de change de 2–4 % a carico di chi paga (Stripe, Adaptive Pricing, letto il 3 octobre 2026): sulla ricarica minima da $10 sono tra $0,20 e $0,40. In dollari la commissione sparisce, ma sparisce anche Satispay, che esiste solo nel checkout in euro; se il checkout ti appare in dollari, spesso c'entra una VPN. L'importo esatto in euro è quello che leggi nel checkout prima di confermare.

Con Satispay le ricariche si fanno a mano: la ricarica automatica di Kunavo addebita solo una carta salvata o Link. Chi ha la carta Satispay, una Mastercard di debito per i piani Plus, Metal e Velvet (support Satispay, letto il 3 octobre 2026), può salvarla e usarla come qualsiasi carta. Il credito non scade e le richieste fallite non vengono addebitate. Kunavo non emette fatture, né con IVA né elettroniche via SDI; lo storico delle ricariche resta in Facturation.

Une remarque honnête : Satispay est disponible dans le checkout de Kunavo depuis le 3 octobre 2026 et Stripe le propose pour les paiements en euros, mais aucune recharge n’est encore passée par ce moyen. Si vous ne le trouvez pas, la carte, Apple Pay, Google Pay et Link font le même travail.

Combien coûte une session de travail

Avec la clé API, le coût dépend des tokens, et Claude Code en envoie beaucoup : à chaque étape, il renvoie l’intégralité du contexte. La partie qui ne change pas peut toutefois être lue depuis le cache à un tarif bien inférieur. Voici un exemple construit de toutes pièces, avec des hypothèses explicites : ce n’est ni une mesure ni un plafond de dépenses.

• 40.000 tokens d’entrée par requête, dont 36.000 (90 %) lus depuis le cache et 4.000 écrits dans le cache ;
• 1.000 tokens de sortie par requête ;
• 50 requêtes dans une session, sans compter les appels à Claude Haiku 4.5 en arrière-plan ;
• lecture depuis le cache à 10% du tarif d’entrée et écriture à 1,25× le tarif d’entrée : ce sont les ratios Kunavo pour Claude Sonnet 5, et chaque ligne du tableau utilise ceux de son propre modèle.

Les contextes longs, les rares lectures depuis le cache et les réponses prolixes font augmenter la facture ; un /clear entre deux tâches la réduit. Pour savoir si l’abonnement ou l’API vous convient le mieux, consultez combien coûte Claude Code ; les tarifs de tous les modèles Claude figurent dans les prix de l’API Claude et sur la page des tarifs. Pour refaire le calcul avec vos chiffres, utilisez le calculateur du coût des tokens de Claude (en anglais).

Erreurs : message, cause, solution

Ce que cette configuration ne fait pas

• Elle n’active pas un abonnement Claude Pro ou Max : le crédit Kunavo paie l’API et Claude Code avec une clé, pas claude.ai ni l’application Claude.
• Elle ne produit pas de factures : ni avec TVA ni électroniques via SDI.
• Elle ne recharge pas automatiquement avec Satispay : la recharge automatique nécessite une carte enregistrée ou Link.
• Elle ne fonctionne pas sans les variables des modèles tant que Kunavo ne propose pas Sonnet 5.5 (situation au 3 octobre 2026) : l’alias sonnet renverrait une 404, de même que /model sonnet, la phase d’exécution de opusplan et les sous-agents avec model: sonnet.
• Kunavo ne propose pas de documentation en italien : le guide d’intégration et la page consacrée au solde et aux paiements sont en anglais, tandis que celle d’Anthropic sur Claude Code est traduite.

Pour une vue d’ensemble destinée aux personnes qui développent avec Claude depuis l’Italie, consultez le guide de l’API Claude en Italie. Pour commencer : créez le compte, rechargez $10 avec Satispay, configurez les six variables et vérifiez avec /status.

Questions fréquentes