安裝 Claude Code：Windows、macOS 與 Linux、無訂閱的 API 金鑰，以及使用 Bancontact 付款

安裝 Claude Code 只需一行命令，但各平台不同：在 macOS、Linux 或 WSL 的終端機中使用 curl -fsSL https://claude.ai/install.sh | bash，在 PowerShell 中使用 irm https://claude.ai/install.ps1 | iex，在 Windows 命令提示字元中使用 install.cmd。真正的問題會在第一次啟動時出現：由誰支付請求費用？Pro、Max、Team、Enterprise 或 Console 帳戶可以登入（Claude.ai 免費方案不包含 Claude Code）。沒有訂閱方案時，只需 API 金鑰：設定六個變數，其中包含 ANTHROPIC_BASE_URL，但不要加上 /v1 和 ANTHROPIC_AUTH_TOKEN，然後查看 /status。Kunavo 餘額可使用卡片、Apple Pay、Google Pay、Link，或在比利時使用 Bancontact 付款，自 $10 起，無需訂閱。

D’où viennent les informations : les commandes et les variables sont reprises de la documentation officielle de Claude Code (安裝, 環境變數, 連線至閘道), relue le 2026年10月3日 ; les prix Kunavo et les moyens de paiement ont été contrôlés le 2026年10月3日. D’après la Anthropic 支援的國家／地區清單 (lue le 2026年10月3日), Claude.ai et l’API sont ouverts en France, en Belgique, en Suisse, au Luxembourg et au Canada, comme au Maroc, en Tunisie, en Algérie, au Sénégal et en Côte d’Ivoire. Le même guide existe 英文 et, pour la Flandre, 荷蘭文.

要輸入哪個指令：完全取決於您所在的視窗

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

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

:: Invite de commandes Windows (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

前三行會建立 Anthropic 建議的原生版本：一個獨立的二進位檔，存放於 ~/.local/bin（Windows 上為 %USERPROFILE%\.local\bin），會在背景下載更新，並於下次啟動時套用。安裝完成後，請關閉終端機並重新開啟一個：用於安裝的終端機尚未識別新的 PATH。

在 Windows 上，選錯視窗是最常見的失敗原因，而錯誤訊息會清楚說明。The token '&&' is not a valid statement separator：您將 CMD 行貼到了 PowerShell。'irm' is not recognized as an internal or external command：反之亦然。在法文版 Windows 上，第二則訊息可能會以翻譯後的文字顯示；原因不變。其他訊息列於指南末尾的錯誤表中。

系統需求

Windows：舊教學所說的內容，以及目前正確的資訊

Une bonne partie des tutoriels en français datent des premières versions de Claude Code. Voici leurs consignes les plus répandues, confrontées à la 目前的安裝文件 et à la 疑難排解頁面 (lues le 2026年10月3日) :

Si vous installez Git for Windows, Claude Code passe par Git Bash et garde l’outil PowerShell à côté. Il arrive qu’il ne trouve pas bash.exe : indiquez alors son chemin dans la variable CLAUDE_CODE_GIT_BASH_PATH, au sein du bloc env de ~/.claude/settings.json (la documentation donne C:\Program Files\Git\bin\bash.exe en exemple). Dernier piège : le raccourci « Windows PowerShell (x86) » lance une version 32 bits, que Claude Code refuse.

使用原生環境或 WSL，取決於您的專案所在位置：

在 WSL 端，所有操作都在 Linux 發行版內進行：您會在這裡貼上 curl … | bash，接著也在這裡輸入 claude。若從 PowerShell 或 CMD 啟動，它看不到這個安裝。

Homebrew、WinGet、apt 或 npm

套件管理員都能運作，但有一項代價：Claude Code 不會在其中自動更新。對於 Homebrew 和 WinGet，變數 CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 會讓 Claude Code 自行啟動更新；沒有此變數時，您必須手動更新：

# Homebrew (macOS)
brew install --cask claude-code
brew upgrade claude-code              # pas de mise à jour automatique

# WinGet (Windows)
winget install Anthropic.ClaudeCode
winget upgrade Anthropic.ClaudeCode   # pas de mise à jour automatique

Sur Debian, Ubuntu, Fedora, RHEL et Alpine, Anthropic publie aussi des dépôts apt, dnf et apk signés, mis à jour avec le reste du système ; la procédure figure sur la 安裝頁面.

剩下 npm；如果 Node.js 已是您工具鏈的一部分，npm 會很方便。套件至少需要 Node.js 22。在較舊版本上，npm 只會顯示 EBADENGINE 警告並繼續完成安裝，因為該套件安裝的是相同的原生二進位檔，而其執行不需要 Node.js。請遵守兩項規則：不要使用 sudo npm install -g，並使用 @latest 更新，因為 npm update -g 會留在原始版本範圍內，可能讓您落後於最新版本。

node -v                                       # v22 ou plus récent
npm install -g @anthropic-ai/claude-code      # jamais avec sudo

# mise à jour : avec @latest, pas avec npm update -g
npm install -g @anthropic-ai/claude-code@latest

驗證安裝並修復 PATH

claude --version   # affiche le numéro de version, suivi de (Claude Code)
claude doctor      # diagnostic de l’installation et des réglages, sans ouvrir de session

如果回傳版本號，就表示已安裝完成。claude doctor 不會啟動工作階段，而是進一步檢查：安裝狀態、設定檔中的錯誤，以及上次更新的結果。發生問題時，這是第一個應執行的指令。

command not found: claude sur macOS ou Linux, claude « non reconnu » sous Windows : le programme est bien installé, mais le shell ne sait pas où le chercher. Une nouvelle fenêtre suffit le plus souvent. Sinon, ajoutez ~/.local/bin au PATH dans ~/.zshrc ou ~/.bashrc. Sous Windows, la 官方疑難排解頁面 donne ces trois étapes PowerShell :

# 1. Le dossier d'installation est-il déjà dans le PATH ?
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Aucun résultat ? Ajoutez-le au PATH de l'utilisateur, puis ouvrez une nouvelle fenêtre
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. Dans la nouvelle fenêtre : deux chemins = deux installations concurrentes
where.exe claude

透過 npm 安裝後，PowerShell 回應 npm.ps1 cannot be loaded？其執行原則封鎖了 npm 指令碼。請改用原生安裝程式，或僅為您的帳戶允許本機指令碼：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

誰支付請求費用：Claude 訂閱或 API 金鑰

這項選擇不是在安裝時做出，而是在首次啟動時做出，且之後仍可切換。環境中設定的金鑰優先於已儲存的 claude.ai 登入，而後者會暫時停用；刪除該變數後，下次啟動時登入就會重新生效。

使用 Claude 訂閱

無需設定：在專案資料夾中執行 claude，然後在瀏覽器中登入。唯一例外是環境中殘留的 ANTHROPIC_API_KEY。Claude Code 會詢問一次是否使用它；拒絕後會記住此選擇，之後直接忽略金鑰且不顯示訊息，讓人以為系統沒有讀取該變數。若要重新選擇：/config → Use custom API key。

不使用訂閱：Kunavo API 金鑰

Faire pointer Claude Code ailleurs que chez Anthropic n’a rien d’un bricolage. La 官方環境變數清單 présente ANTHROPIC_BASE_URL comme le moyen d’envoyer les requêtes vers un proxy ou une passerelle. Kunavo répond au format de l’API Messages d’Anthropic : vous gardez le Claude Code officiel, sans extension ni version modifiée.

1. 建立帳戶：註冊 Kunavo。
2. 在 Billing 中儲值，最低 $10（付款方式見下方）。
3. 在 /app/keys 中產生金鑰。金鑰以 sk-kn- 開頭，且只會在建立時顯示：請立即複製。
4. 填入下方的六個變數。

Pourquoi épingler quatre modèles ? Les alias de Claude Code suivent les sorties d’Anthropic. D’après la 模型設定文件 (lue le 2026年10月3日), pour un compte API, le réglage par défaut et opus visent aujourd’hui Opus 5.5, et sonnet vise Sonnet 5.5, que Kunavo ne sert pas : sans ANTHROPIC_DEFAULT_SONNET_MODEL, /model sonnet, la phase d’exécution d’opusplan et les sous-agents réglés sur sonnet tombent sur une 404. L’alias opus est épinglé sur Opus 5.5 (claude-opus-5-5), qui exige Claude Code v2.1.280 ou plus récent ; sur une version plus ancienne, lancez claude update. Un modèle tout juste sorti n’est pas non plus toujours disponible chez Kunavo le jour même. Avec des noms complets, chaque requête part vers un modèle servi, au prix que vous connaissez. La 閘道通訊協定文件 (lue le 2026年10月3日) confirme le point sur les tâches de fond : avec Claude Haiku 4.5, elles coûtent peu.

在哪裡寫入變數

建議版本；若檔案已有內容，請與現有內容合併（只加入 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"
  }
}

macOS 和 Linux 上 shell 中的相同值：

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # le domaine seul, sans /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

若要在 PowerShell 視窗中快速測試：

# Valable uniquement dans cette fenêtre 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

至於 VS Code 擴充功能，請在編輯器的使用者設定中使用指令 Preferences: Open User Settings (JSON)：

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

Claude 桌面版應用程式是例外：它既不讀取 ANTHROPIC_BASE_URL，也不讀取 settings.json。在 shell 中修改變數後仍未生效？先在優先級較高的 settings.json 中尋找相同變數。

Tarifs par million de tokens tirés du catalogue Kunavo, à côté du prix public d’Anthropic relevé sur claude.com/pricing (lu le 2026年10月3日) :

若要在單一工作中暫時切換至 Opus：在工作階段中執行 /model opus（固定在 claude-opus-5-5 上的別名），或在啟動時使用 claude --model claude-opus-5-5。依用量計算的每月預算，以及訂閱開始更划算的門檻，均列於Claude Code 價格。Claude token 成本計算器可依您自己的用量計算，而價格頁面列出所有模型。

使用 /status 驗證

第一個跡象甚至早於 /status：設定 ANTHROPIC_AUTH_TOKEN 後，Claude Code 會在啟動時不顯示登入畫面。若出現此畫面，表示沒有讀取任何金鑰，通常是因為金鑰只存在於專案設定（.claude/settings.json 或 .claude/settings.local.json）中。在互動工作階段中，這個 env 區塊只有在首次啟動精靈以及對資料夾的信任問題之後才會套用。請將金鑰移至 shell 或 ~/.claude/settings.json。

Une fois dans la session, /status s’ouvre sur l’onglet Status. Voici comment le lire, d’après la 閘道文件 (lue le 2026年10月3日) :

您原本已使用訂閱登入？此時 Claude Code 可能會在啟動時指出有兩個作用中的身分識別來源，並以 auth may not work as expected 結尾。請求使用的是金鑰；/logout 會移除舊登入並消除警告。

若要判斷問題來自 Kunavo 還是您的設定，請不使用 Claude Code 進行測試。文件提供了一個輸出限制為單一 token 的請求，成本不到一美分。下方兩個指令會從 shell 取得網址和金鑰：如果只在 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": "."}]}'

若 JSON 以 {"id":"msg_ 開頭，或在 PowerShell 中物件的 id 以 msg_ 開頭，表示網址和金鑰有效。若出現 401，表示金鑰遭拒。

使用 API 金鑰後的變化

• Remote Control 和語音聽寫會消失。兩者都依賴 claude.ai 帳戶，只要設定 ANTHROPIC_AUTH_TOKEN 就無法使用。只要 ANTHROPIC_BASE_URL 指向 Anthropic 以外的主機，Remote Control 也會停用。
• 快速模式（/fast）會顯示為已停用，因為其驗證要求 claude.ai 登入或 Anthropic 金鑰，而不是一般的 bearer token。
• 當 ANTHROPIC_BASE_URL 指向 Anthropic 以外的位置時，MCP 工具搜尋預設會停用。
• /context 會顯示估算值。 Kunavo ne propose pas /v1/messages/count_tokens, et dans ce cas Claude Code compte à partir du nombre de caractères (閘道通訊協定文件).

至於其他功能（程式碼讀寫、工具、子代理程式、MCP 伺服器、hooks、提示快取），一切維持不變。英文技術細節請參閱Claude Code 整合文件。

從法國或比利時付款

Deux circuits à ne pas confondre. L’abonnement Claude acheté sur le web se règle uniquement par carte de crédit ou de débit (Anthropic 帳務常見問題, lue le 2026年10月3日) ; souscrit dans l’app mobile, il passe par l’App Store ou Google Play. Les montants de claude.com/pricing sont hors taxes.

Le solde Kunavo, lui, se recharge sur une page de paiement Stripe. Le tarif est fixé en dollars américains, mais depuis la France ou la Belgique Stripe vous montre le montant en euros, à un taux garanti 24 heures qui intègre 2 à 4 % de frais de conversion à votre charge (Stripe 的 Adaptive Pricing 文件, lue le 2026年10月3日). Vous pouvez payer en dollars pour éviter ces frais, mais votre banque applique alors son propre change, et Bancontact n’est proposé qu’en euros. Les moyens de paiement disponibles :

• 法國 CB 卡？ Selon la Stripe 的 Cartes Bancaires 文件 (lue le 2026年10月3日), plus de 95 % des cartes CB sont co-badgées Visa ou Mastercard. Elles passent donc au checkout en tant que Visa ou Mastercard, et une simple carte de débit fait l’affaire.
• Bancontact est proposé aux acheteurs situés en Belgique. Stripe vous envoie sur le site ou l’app Bancontact pour valider, et le résultat est connu immédiatement (Stripe 的 Bancontact 文件, lue le 2026年10月3日).
• Pay by Bank, le paiement depuis votre banque en ligne, n’est pas proposé depuis la France ni la Belgique : le checkout ne l’affiche qu’aux acheteurs situés au Royaume-Uni, en Irlande et en Finlande. La Stripe 的 Pay by Bank 文件 (lue le 2026年10月3日) le classe en préversion privée pour la France et ne mentionne pas la Belgique.
• 從瑞士或加拿大付款時，金額會以瑞士法郎或加拿大元顯示，可使用信用卡和 Link，另可使用 Apple Pay 與 Google Pay；後兩者都需要綁定卡片。

不提供：PayPal、SEPA 直接扣款、Klarna；Klarna 僅限位於美國的買家（以美元付款並不足夠）。

1. 註冊 Kunavo；此階段不需要提供卡片。
2. 在 Billing 中選擇金額：最低 $10。較高金額可獲得獎勵（$100 payés, $110 crédités ; $1 000 payés, $1 200 crédités ; $5 000 payés, $6 250 crédités）。
3. 在 Stripe 頁面上選擇付款方式；確認前會顯示歐元金額。使用 Bancontact 時，請在應用程式中或使用卡片進行確認。
4. 在 /app/keys 中建立金鑰，並將其放入 ANTHROPIC_AUTH_TOKEN。

餘額採預付制：無月費、無到期日，失敗的請求不會收費。自動儲值需要已儲存的卡片或 Link。Stripe 的 Bancontact 不支援定期付款，因此每次 Bancontact 儲值都必須手動啟動。Kunavo 不會開立含增值稅的發票，不論是法國、比利時或其他國家的發票；儲值記錄可在 Billing 中查看。最後，這些付款方式僅用於 Kunavo API 餘額，不能支付 Claude Pro 或 Max 訂閱。其他所有方式，包括 App Store 和 Google Play，均已在不使用卡片支付 Claude中說明。

常見錯誤

專案入門

在 Claude Code 探索的儲存庫中，先執行 /init：它會探索程式碼並撰寫 CLAUDE.md，記錄找到的測試指令與慣例。請檢閱並精簡此檔案，因為每個工作階段都會重新載入。若要切換主題，/clear 會從空白對話重新開始；若要繼續長時間工作，/compact 會摘要其歷史記錄。

API 金鑰的限制

• 您是按用量付費，而不是購買 Claude Pro 或 Max 方案。若每天使用 Claude Code 數小時，且每天都使用，訂閱通常更划算；若使用不固定，按 token 付費更有彈性，低用量月份也不會產生費用。數據請參閱Claude Code 價格。
• 只要金鑰啟用，就不能使用 Remote Control 或語音聽寫。
• Kunavo 的容量由所有使用者共用，沒有保留配額或合約承諾；如有此需求，請直接與 Anthropic 簽約。
• Bancontact 只能手動儲值；自動儲值需使用已儲存的卡片或 Link。
• 歐元金額包含 Stripe 的轉換費用，且 Kunavo 不會開立含增值稅的發票。

常見問題