在 Windows、Mac 與 Linux 上安裝 Claude Code：無需訂閱的 API 金鑰與使用 Satispay 付款

安裝 Claude Code 只需一個命令，命令會依終端機而異：在 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、設定四個模型變數，以及使用 /status 進行最後驗證。額度可使用 Satispay 以歐元從 $10 儲值，而你只需支付實際使用的 token。

# 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 gateway. 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 其中一種 shell。
• 來自 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：Node.js 22，而不是 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 (官方文件, 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

三個應避免的習慣：

• 在 npm install -g 前加上 sudo。 文件不建議這樣做，原因包括權限衝突與安全性問題。
• 使用 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日).

Claude Code 在 Windows 上：容易卡住的地方

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 位元程序，即使電腦是 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 中進行：請在 WSL shell 中執行 install.sh，並從該處啟動 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。文件列出三種處理方式：使用下方指令允許目前使用者執行本機指令碼、改用 npm.cmd 和 claude.cmd（而非 PowerShell 指令碼），或放棄 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 金鑰：六個變數

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 gateway. 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 的 env 區塊（Windows 上為 %USERPROFILE%\.claude\settings.json）：這會套用到你的所有專案。如果檔案中已有其他設定，只需加入 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 gateway 文件 (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.

設定中三個模型的 Kunavo 費率（每百萬 token，輸入／輸出）：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 (gateway 文件). 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 (gateway 文件, 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 (gateway 文件, 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。需要注意的有兩行：

• Anthropic base URL 只有在設定 gateway 時才會出現：其值應為 https://api.kunavo.com。如果沒有，表示 ANTHROPIC_BASE_URL 尚未傳入工作階段。
• Auth token 的名稱為 ANTHROPIC_AUTH_TOKEN：表示你正在使用金鑰。如果取而代之看到的是使用 claude.ai 帳戶的 Login method，表示變數被忽略了。

想在開啟 Claude Code 之前先進行檢查嗎？文件提供了一個只要求 1 個輸出 token 的最小請求，從餘額扣除的金額微乎其微。該指令會讀取目前 shell 的變數：如果金鑰只存在於 settings.json 中，請先在此終端機中匯出它。如果回傳的 JSON 以 {"id":"msg_ 開頭，就表示設定正確；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 中，相同的測試如下；成功的回應會包含以 msg_ 開頭的 id：

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 身分識別，無法搭配 ANTHROPIC_AUTH_TOKEN 或 ANTHROPIC_API_KEY 使用；自 2.1.196 版本起，當 ANTHROPIC_BASE_URL 指向非 Anthropic 的主機時，Remote Control 也會關閉。
• /fast 模式。 只有 bearer token 時，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 gateway 規格 (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 確認付款後，額度會立即顯示在 計費 中。如果沒有立即看到，請重新整理頁面，不要再次付款：第二筆付款會加到額度中，而不是取代第一筆。
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 也在歐元付款中提供此選項，但目前尚未有任何儲值透過它完成。如果找不到它，卡片、Apple Pay、Google Pay 和 Link 也能完成相同操作。

一個工作階段要花多少錢

使用 API 金鑰時，費用取決於 token，而 Claude Code 會傳送不少 token：每一步都會重新傳送完整上下文。不過，不變的部分可以從快取中讀取，費率低得多。以下是一個刻意設計的範例，假設條件均已列明：這不是實測值，也不是支出上限。

• 每個請求 40.000 個輸入 token，其中 36.000（90%）從快取讀取，4.000 寫入快取；
• 每個請求 1.000 個輸出 token；
• 一個工作階段中有 50 個請求，不包括背景中對 Claude Haiku 4.5 的呼叫；
• 從快取讀取時採用輸入費率的 10%，寫入時採用輸入費率的 1,25×：這些是 Kunavo 對 Claude Sonnet 5 的比例，表格中的每一列都使用其所屬模型的比例。

上下文很長、快取讀取很少，以及冗長的回覆會提高費用；在任務之間執行一次 /clear 則會降低費用。你可以在 Claude Code 的費用 中查看訂閱或 API 哪個更划算；所有 Claude 模型的費率請參閱 Claude API 價格 和 價格頁面。如要使用自己的數字重新計算，請使用 Claude token 費用計算器（英文）。

錯誤：訊息、原因、解決方法

此設定不會做什麼

• 不會啟用 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 的子代理程式。
• 沒有義大利文的 Kunavo 文件：整合指南 和 餘額與付款頁面 為英文，而 Anthropic 的 Claude Code 文件已有翻譯。

若要了解從義大利開發 Claude 的整體情況，請參閱 義大利 Claude API 指南。開始方式：建立帳戶、使用 Satispay 儲值 $10、設定六個變數，並使用 /status 進行檢查。

常見問題