Windows、Mac、LinuxにClaude Codeをインストール：サブスクリプション不要のAPIキーとSatispay決済

Claude Codeのインストールは、ターミナルによって異なる1つのコマンドだけで完了します。macOS、Linux、WSLではinstall.shを含む行、PowerShellではirm … | iex、コマンドプロンプトではinstall.cmdを含む行を使います。Anthropicが推奨する方法です。npmも利用できますが、Node.js 22以降が必要です。Claudeの無料プランにはClaude Codeが含まれないため、Pro以上のサブスクリプションまたはAPIキーが必要です。ここでは後者を使います。ANTHROPIC_BASE_URL=https://api.kunavo.com（/v1なし）、ANTHROPIC_AUTH_TOKENにキーを設定し、モデルを固定する4つの変数を設定して、最後に/statusで確認します。クレジットはSatispayでユーロ建てに$10からチャージでき、使用したトークン分だけ支払います。

# 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 2026年10月3日, in particolare le pagine su インストール e LLMゲートウェイ. Prezzi e metodi di pagamento di Kunavo sono aggiornati al 2026年10月3日. Anthropic serve l'Italia sia su Claude.ai sia con l'API (対応国, letto il 2026年10月3日).

必要なもの

I requisiti della 公式ドキュメント (letta il 2026年10月3日) sono bassi:

• macOS 13.0以降；Windows 10 1809以降、またはWindows Server 2019以降；Ubuntu 20.04以降、Debian 10以降、またはAlpine Linux 3.19以降。
• 少なくとも4 GBのRAMと、x64またはARM64プロセッサ。32ビット版Windowsは対象外です。
• Bash、Zsh、PowerShell、CMDのいずれかのシェル。
• Anthropicが対応する国からの接続。イタリアは対応しています。
• npmを選ぶ場合のみNode.jsが必要で、その場合はバージョン22以降。

どのターミナルでどのコマンドを使うか

管理者権限もWSLも必要ありません。公式ドキュメントにも明記されていますが、反対のことを勧めるガイドも少なくありません。インストール後、Claude Codeはバックグラウンドで自動更新されます。パッケージマネージャーを使いたい場合はHomebrewまたはWinGetを利用できますが、その場合は自分で更新を実行します。

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

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

試す前に、ターミナルを閉じて新しいターミナルを開いてください。新しいウィンドウだけがPATHを再読み込みします。その後で確認します。claude doctorは後でも役立ちます。セッションを開かずにインストールと設定を確認し、問題がどちらにあるかをすぐに知らせてくれます。

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

ダウンロードがブロックされる：403またはスクリプトの代わりにHTMLページが表示される

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 インストール問題に関する公式ページ (in inglese, letta il 2026年10月3日) 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.

npmの場合：18ではなくNode.js 22

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 (公式ドキュメント, letta il 2026年10月3日). 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

避けるべき3つの習慣：

• sudoをnpm install -gの前に付ける。権限の競合とセキュリティ上の理由から、ドキュメントでも推奨されていません。
• 更新にnpm update -gを使う。代わりに、上の最後の行のように@latestを付けてインストールを繰り返してください。
• 任意の依存関係をスキップする。 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 (インストールの問題, in inglese, letta il 2026年10月3日).

Windows上のClaude Code：つまずきやすい点

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: ドキュメント, letta il 2026年10月3日).

スタートメニューにも注意してください。「Windows PowerShell (x86)」は32ビットプロセスを開くため、PCが64ビットでもClaude CodeはClaude Code does not support 32-bit Windowsで停止します。(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:

WSLではすべてがLinux内で実行されます。install.shの行はWSLのシェルで実行し、そこからclaudeを起動します。

「claude」が見つからない

インストール後にターミナルがcommand not found: claudeまたは'claude' is not recognizedと返す場合、プログラムは存在しますが、そのフォルダーがPATHに含まれていません。ネイティブインストーラーはmacOSとLinuxでは~/.local/bin/claudeに、Windowsでは%USERPROFILE%\.local\bin\claude.exeにコピーします。まず新しいターミナルを試してください。Windowsで解決しない場合は、フォルダーをユーザーのPATHに確認・追加するための公式ドキュメントのPowerShellコマンドを使います。

# 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

PowerShellでnpm.ps1 cannot be loaded

npmでインストールした場合に限ります。PowerShellの実行ポリシーが、npmが作成する.ps1スクリプトをブロックし、完全なメッセージにはrunning scripts is disabled on this systemが含まれます。ドキュメントでは3つの対処法が示されています。下のコマンドで現在のユーザーにローカルスクリプトの実行を許可する、PowerShellスクリプトの代わりにnpm.cmdとclaude.cmdを実行する、またはnpmをやめてネイティブインストーラーを使う、のいずれかです。

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

サブスクリプションなし：ClaudeアカウントまたはAPIキー

Installato non vuol dire pronto: al primo avvio Claude Code chiede di autenticarsi, e il piano gratuito di Claude.ai non basta (ドキュメント, letta il 2026年10月3日). 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 (Anthropicのサポート, letto il 2026年10月3日); si paga con carta, mentre il bonifico ACH è riservato agli account API con fatturazione mensile (Anthropicのサポート). Il credito Kunavo non ha scadenza.

APIキーの設定：6つの変数

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 LLMゲートウェイに接続する. Nessun plugin, nessuna versione modificata. Bastano queste variabili:

macOSとLinuxでは、~/.zshrcまたは~/.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

Windowsで、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

毎回再設定しなくて済むように、~/.claude/settings.json（Windowsでは%USERPROFILE%\.claude\settings.json）のenvブロックに設定します。すべてのプロジェクトに適用されます。ファイルに他の設定がすでにある場合は、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と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 → カスタムAPIキーを使用. ANTHROPIC_AUTH_TOKEN non chiede niente, ed è anche la variabile che la ゲートウェイのドキュメント (letta il 2026年10月3日) suggerisce quando non sai quale scegliere.

モデルを固定する理由

Senza variabili Claude Code ragiona per alias, e gli alias seguono le uscite di Anthropic. Oggi, secondo la モデル設定に関するドキュメント (letta il 2026年10月3日), per chi usa l'API opus corrisponde a Opus 5.5 e sonnet a Sonnet 5.5. Kunavo, al 2026年10月3日, 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.

設定した3モデルのKunavo料金（100万トークンあたり、入力 / 出力）：Claude Sonnet 5 $1,40 / $7,00 （Anthropicの料金表：$2,00 / $10,00）；Claude Opus 5.5 $2,80 / $14,00；Claude Haiku 4.5 $0,70 / $3,50。このモデルはバックグラウンドでも動作します。

どこに設定してはいけないか、そしてどの設定が優先されるか

Il .claude/settings.json dentro il progetto viene committato: una chiave scritta lì finisce nel repository e arriva a chiunque lo cloni (ゲートウェイのドキュメント). 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 (ゲートウェイのドキュメント, letta il 2026年10月3日).

初回起動と/statusによる確認

Se la chiave è al suo posto, claude parte ログイン画面なし: 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 (ゲートウェイのドキュメント, letta il 2026年10月3日), 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.

セッション内で/statusと入力します。重要なのは次の2行です。

• ゲートウェイが設定されている場合のみ表示されるAnthropic base URL。https://api.kunavo.comと表示される必要があります。表示されない場合、ANTHROPIC_BASE_URLがセッションに渡っていません。
• Auth tokenにANTHROPIC_AUTH_TOKENという名前が表示される場合は、キーを使用しています。代わりにclaude.aiアカウントのLogin methodが表示される場合、変数は無視されています。

Claude Codeを開く前に確認したい場合は、ドキュメントにある最小限のリクエストを使えます。出力トークンは1つで、クレジットから差し引かれる金額はごくわずかです。コマンドは現在のシェルの変数を読み取ります。キーがsettings.jsonにしかない場合は、先にこのターミナルでエクスポートしてください。{"id":"msg_で始まるJSONが返れば問題ありません。401はキーが拒否されたことを意味します。

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

PowerShellでは同じテストを次のように実行します。正常な応答にはidが含まれ、その値は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": "."}]}'

APIキーで失われるもの

• Remote Controlと音声入力。これらにはclaude.aiのIDが必要で、ANTHROPIC_AUTH_TOKENまたはANTHROPIC_API_KEYでは動作しません。バージョン2.1.196以降では、ANTHROPIC_BASE_URLがAnthropic以外のホストを指している場合もRemote Controlが無効になります。
• /fastモード。Bearerトークンだけの場合、Claude Codeはこれを無効とみなし、要求しようとすらしません。
• 最初に行われるMCPツールの検索。 Con un ANTHROPIC_BASE_URL personalizzato parte spenta (MCPドキュメント, in inglese, letta il 2026年10月3日). Si riaccende con ENABLE_TOOL_SEARCH=true se il gateway inoltra i blocchi tool_reference; con Kunavo non l'abbiamo provato.
• /contextの精度。 Kunavo non espone /v1/messages/count_tokens, un endpoint facoltativo secondo la ゲートウェイの仕様 (letta il 2026年10月3日); senza, Claude Code stima i token a partire dai caratteri.

詳しくは英語のClaude Code統合ドキュメント、ANTHROPIC_BASE_URLの特殊ケースのページ、Claude Codeのインストールガイドをご覧ください。

クレジットカードなしでSatispayで支払う

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 (Anthropicのサポート) e non accetta PayPal (Anthropicのサポート), entrambi letti il 2026年10月3日. 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 SatispayでClaudeの料金を支払う. Per Claude Code la sequenza è questa:

1. メールアドレスまたはGoogleアカウントでKunavoに登録してください。カードは不要です。
2. 請求を開き、チャージ額を選びます。最低額は$10で、サブスクリプション料金はありません。 一定額以上ではボーナスがあります：クレジット$100 diventano $110, $1.000 diventano $1.200, $5.000 diventano $6.250。
3. Nel checkout di Stripe, che mostra l'importo in euro, scegli Satispay. Si passa alla pagina di Satispay (Stripeドキュメント): numero di cellulare o QR code dall'app, poi conferma con 送信 (Satispayサポート, letto il 2026年10月3日). Meglio avere già abbastanza Disponibilità prima di cominciare.
4. Stripeが支払いを確認すると、クレジットはすぐに請求に表示されます。すぐに表示されない場合は、再度支払うのではなくページを更新してください。2回目の支払いは最初の支払いを置き換えず、クレジットに加算されます。
5. APIキーでキーsk-kn-…を生成し、すぐにANTHROPIC_AUTH_TOKENへコピーしてください。一度しか表示されません。

Kunavo fissa i prezzi in dollari e Stripe li converte in euro con una 2–4%の為替手数料 a carico di chi paga (Stripe、Adaptive Pricing, letto il 2026年10月3日): 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 (Satispayサポート, letto il 2026年10月3日), 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 料金.

正直な注記：Satispayは2026年10月3日からKunavoのチェックアウトに表示され、Stripeはユーロ建ての支払いで提供していますが、まだSatispay経由で完了したチャージはありません。表示されない場合は、カード、Apple Pay、Google Pay、Linkで同じように支払えます。

作業セッションの料金

APIキーを使う場合、料金はトークンに基づきます。Claude Codeは各ステップでコンテキスト全体を再送するため、多くのトークンを送信します。ただし、変化しない部分はキャッシュから読み取れるため、料金は大幅に下がります。以下は前提を明示した架空の例です。測定値でも、支出上限でもありません。

• リクエストあたりの入力トークン40.000。そのうち36.000（90%）はキャッシュから読み取り、4.000はキャッシュに書き込み；
• リクエストあたりの出力トークン1.000；
• 1セッションあたり50件のリクエスト。バックグラウンドのClaude Haiku 4.5呼び出しは含みません；
• キャッシュからの読み取りは入力料金の10%、書き込みは入力料金の1,25倍です。これはClaude Sonnet 5に対するKunavoの比率であり、表の各行ではそのモデルの比率を使用しています。

長いコンテキスト、キャッシュからの読み取りが少ないこと、冗長な回答によって料金は上がります。タスクの合間に/clearを実行すると下がります。サブスクリプションとAPIのどちらが有利かはClaude Codeの料金で確認できます。すべてのClaudeモデルの料金はClaude APIの料金と料金ページにあります。自分の数値で計算し直すには、Claudeトークンコスト計算ツール（英語）を使ってください。

エラー：メッセージ、原因、対処法

この設定でできないこと

• Claude ProまたはMaxのサブスクリプションは有効になりません。KunavoのクレジットはAPIとキーを使うClaude Codeの料金に充てられるもので、claude.aiやClaudeアプリには使えません。
• 請求書は発行されません。VAT請求書も、SDI経由の電子請求書も対象外です。
• Satispayによる自動チャージは行われません。自動チャージには保存済みカードまたはLinkが必要です。
• KunavoがSonnet 5.5を提供するまで、モデル変数なしでは動作しません（2026年10月3日現在）。sonnetエイリアスは404になり、それに伴って/model sonnet、opusplanの実行フェーズ、model: sonnetを指定したサブエージェントも404になります。
• Kunavoのイタリア語ドキュメントはありません。統合ガイドと残高と支払いのページは英語ですが、AnthropicのClaude Codeドキュメントは翻訳されています。

イタリアからClaudeを使って開発する人向けの全体像については、イタリアでClaude APIを使うためのガイドをご覧ください。始めるには、アカウントを作成し、Satispayで$10をチャージし、6つの変数を設定して/statusで確認します。

よくある質問