安裝 Claude Code：Windows、macOS 與 Linux 的指令、不需訂閱的 API 金鑰，以及使用 MB WAY 付款

Claude Code 可使用每個系統的一個官方指令安裝：在 macOS、Linux 與 WSL 上使用curl -fsSL https://claude.ai/install.sh | bash；在 Windows 的 PowerShell 中使用irm https://claude.ai/install.ps1 | iex（在命令提示字元 CMD 中，則使用下方的install.cmd指令）。之後有兩種使用方式。使用訂閱時，以 Pro、Max、Team、Enterprise 或 Console 帳戶登入（只有 Claude.ai 免費方案的使用者無法存取 Claude Code）。沒有訂閱時，使用 API 金鑰：設定ANTHROPIC_BASE_URL（只填網域，不含/v1）、ANTHROPIC_AUTH_TOKEN與四個模型變數，並以/status確認。Kunavo 餘額可在以歐元顯示的結帳頁面使用 MB WAY 儲值，最低US$ 10，無月費。

Comandos e variáveis verificados a 2026年10月3日 na Claude Code 官方安裝文件 e na 環境變數文件; preços e meios de pagamento verificados a 2026年10月3日. Portugal consta da Anthropic 支援的國家／地區清單 (consultada a 2026年10月3日), tanto para o Claude.ai como para a API. Este guia existe também em inglês: 安裝 Claude Code.

安裝前

macOS、Linux 與 WSL：單行指令

在終端機中（macOS 上位於「應用程式 › 工具程式」）執行：

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

這是建議的原生安裝方式：根據官方文件，這是一個會在背景自動更新的獨立程式。claude指令位於~/.local/bin。已開啟的終端機尚未取得新的 PATH，因此請在測試前開啟新的視窗。在 WSL 中，指令完全相同，並在 WSL 終端機內執行。

在 Windows 上安裝

Windows 有兩行指令，選擇哪一行只取決於目前開啟的視窗。若該行以PS C:\Users\Nome>開頭，表示您在 PowerShell 中；若只出現C:\Users\Nome>而沒有PS，表示您在命令提示字元（CMD）中。不需要使用「以系統管理員身分執行」：官方文件明確表示不需要，這與某些葡萄牙文指南的建議相反。

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

:: Linha de Comandos do Windows (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

在 Windows 上，最常見的問題是使用了錯誤的視窗。若 PowerShell 回應The token '&&' is not a valid statement separator，表示您收到的是 CMD 指令；若 CMD 回應'irm' is not recognized as an internal or external command，表示您收到的是 PowerShell 指令。在葡萄牙文 Windows 中，第二則訊息可能會以翻譯後的文字顯示，但原因相同。此外，將 macOS 指令中的| bash貼到 PowerShell 會產生錯誤，表示bash未被辨識。這三種情況的解決方法都是使用與目前視窗相符的指令。

O Git for Windows é opcional. Com ele, a ferramenta Bash do Claude Code passa a correr no Git Bash, e o PowerShell continua disponível ao lado; sem ele, todos os comandos correm pelo PowerShell. Quando o Git está instalado numa pasta fora do habitual e o Claude Code não dá com o bash.exe, indica-se o caminho em CLAUDE_CODE_GIT_BASH_PATH, dentro do bloco env de ~/.claude/settings.json; o exemplo da documentação é C:\Program Files\Git\bin\bash.exe.

因此，WSL 是選擇而非必要條件，這與某些指南中的說法相反。選擇使用 WSL 的使用者，應在 WSL 終端機中執行 macOS/Linux 指令，並在其中啟動claude，而不是從 PowerShell 或 CMD 啟動。

使用 Homebrew、WinGet 或 npm

也可以使用，但有一項重要差異：根據官方文件，透過 Homebrew 與 WinGet 的安裝不會自動更新。更新必須手動執行。此外，Linux 還有已簽署的 apt、dnf 與 apk 儲存庫。

# Homebrew
brew install --cask claude-code
brew upgrade claude-code              # não se atualiza sozinho

# WinGet (Windows)
winget install Anthropic.ClaudeCode
winget upgrade Anthropic.ClaudeCode   # não se atualiza sozinho

npm 套件需要 Node.js 22 或更新版本——不是某些指南仍指出的 Node.js 18。使用較舊的 Node.js 時，npm 只會在安裝期間顯示EBADENGINE警告，而不會失敗。請勿使用sudo npm install -g：官方文件明確不建議這麼做。若要更新，請使用@latest，不要使用npm update -g。

node -v                                           # tem de ser v22 ou posterior
npm install -g @anthropic-ai/claude-code          # nunca com sudo

# para atualizar mais tarde: com @latest, não com npm update -g
npm install -g @anthropic-ai/claude-code@latest

確認安裝

claude --version   # mostra o número da versão, seguido de (Claude Code)
claude doctor      # diagnóstico só de leitura da instalação e das definições, sem abrir sessão

claude doctor不會啟動任何工作階段：它會顯示安裝與設定檔案的狀態。這是最快判斷問題出在安裝還是設定的方法。

Um command not found: claude (ou, no Windows, a indicação de que claude não é um comando conhecido) quer dizer que o terminal não sabe onde o programa ficou. Muitas vezes basta fechar a janela e abrir outra. Se continuar, falta a pasta no PATH: no macOS e no Linux é ~/.local/bin, a acrescentar no ficheiro de arranque da shell (~/.zshrc ou ~/.bashrc); no Windows é %USERPROFILE%\.local\bin; segundo a 官方疑難排解文件, confirma-se e acrescenta-se assim no PowerShell:

# 1. A pasta de instalação já está no PATH?
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Sem resultado? Acrescente-a ao PATH do utilizador e abra uma janela nova
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. Na janela nova: dois caminhos significam duas instalações lado a lado
where.exe claude

如果您透過 npm 安裝，而 PowerShell 回應npm.ps1 cannot be loaded because running scripts is disabled on this system，表示 PowerShell 的執行原則封鎖了 npm 指令碼。請使用原生安裝程式，或允許目前使用者執行本機指令碼：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

如果出現Claude Code does not support 32-bit Windows，表示您開啟了「Windows PowerShell (x86)」。Windows 有兩個 PowerShell 入口，而 x86 版本會以 32 位元程序執行；請開啟「Windows PowerShell」入口，不要選擇 (x86)。

首次使用：訂閱或 API 金鑰

首次啟動時，您要決定 Claude Code 的付款方式。切換路徑不需要重新安裝：決定因素是是否已設定金鑰。

路徑 A——使用訂閱登入

在專案資料夾中執行claude，並在瀏覽器中登入。請注意，對於環境中已有ANTHROPIC_API_KEY的使用者：Claude Code 不會開啟瀏覽器，而是要求對該金鑰進行一次性核准。拒絕核准後，該金鑰會一直被忽略，且不會再次詢問，因此看起來像是未讀取變數。若要重新啟用：/config → Use custom API key。

路徑 B——不需訂閱，使用 API 金鑰

ANTHROPIC_BASE_URL是 Claude Code 自有的變數，用於將請求導向 proxy 或 gateway。因此，將它指向與 Anthropic Messages API 相容的端點，是受支援的設定，不需要外掛程式或修改版本。步驟如下：

1. 建立 Kunavo 帳戶。
2. 在帳務中儲值，最低US$ 10（MB WAY 付款方式說明如下）。
3. 在/app/keys中建立以sk-kn-開頭的金鑰。金鑰只會顯示一次，因此最好立即儲存。
4. 設定變數。在 macOS 與 Linux 上，於~/.zshrc或~/.bashrc中設定：

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # só o domínio, sem /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 só para esta janela do 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

若要永久使用，最佳位置是使用者設定中的env區塊：~/.claude/settings.json（Windows 上為%USERPROFILE%\.claude\settings.json）。其中的值會套用至所有專案，包括背景代理；VS Code 擴充功能例外（如下所述）。在 shell 中 export 的變數只會傳遞給從該 shell 啟動的程式：從 Dock 或開始功能表開啟的編輯器看不到它。如果檔案已有其他設定，只需加入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"
  }
}

絕不 ponha a chave no .claude/settings.json de um projeto: segundo a gateway 官方文件 (consultada a 2026年10月3日), esse ficheiro entra nos commits e é partilhado com quem clonar o repositório. E atenção à precedência: quando a shell e um ficheiro de definições definem a mesma variável, prevalece o ficheiro de definições. Se uma alteração na shell não surtir efeito, veja primeiro o settings.json.

使用 VS Code 擴充功能時，請在claudeCode.environmentVariables中設定變數，也就是 VS Code 本身的使用者設定（命令Preferences: Open User Settings (JSON)）。根據 gateway 文件，擴充功能會在啟動前先從此設定檢查憑證；~/.claude/settings.json中的值會傳遞給 Claude Code 程序，但不會傳遞給該檢查：

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

四個模型變數與其他陷阱

區塊中的每一行都有自己的陷阱：

• ANTHROPIC_BASE_URL中不能填路徑。路徑/v1/messages由 Claude Code 自動加上；已經以/v1結尾的位址會變成/v1/v1/messages，並回應 404。
• ANTHROPIC_AUTH_TOKEN或ANTHROPIC_API_KEY：Kunavo 兩者都接受。根據 gateway 文件，ANTHROPIC_AUTH_TOKEN會放在Authorization: Bearer標頭中並立即生效；ANTHROPIC_API_KEY會放在x-api-key標頭中，互動模式下必須先核准一次才能生效（見路徑 A）。因此，本指南使用ANTHROPIC_AUTH_TOKEN。
• ANTHROPIC_MODEL中的名稱必須完全正確。請照此處顯示的內容複製：claude-sonnet-5。
• 沒有ANTHROPIC_DEFAULT_SONNET_MODEL與ANTHROPIC_DEFAULT_OPUS_MODEL時，別名會自行變更。 Segundo a 模型設定文件 (consultada a 2026年10月3日), para quem usa a API da Anthropic o alias opus aponta para o Opus 5.5 e o alias sonnet para o Sonnet 5.5, e estes aliases mudam com as novas versões. Fixa-se com o nome completo do modelo ou com variáveis como ANTHROPIC_DEFAULT_OPUS_MODEL. O Kunavo não serve o Sonnet 5.5, e um modelo que não existe devolve 404: sem ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5, falham o /model sonnet, os subagentes com model: sonnet e o passo de execução do opusplan. Já o opus aponta para claude-opus-5-5, que o Kunavo serve, mas só a partir do Claude Code v2.1.280; quem tiver uma versão anterior corre claude update.
• ANTHROPIC_DEFAULT_HAIKU_MODEL也會影響背景任務。根據文件，它會定義haiku別名與 Claude Code 背景功能使用的模型。設定Claude Haiku 4.5後，這些呼叫會使用下表中最便宜的模型。

Preços por milhão de tokens, do catálogo do Kunavo; a coluna da Anthropic vem de claude.com/pricing (consultado a 2026年10月3日):

在工作階段內，可使用/model claude-opus-5-5切換模型，或直接以claude --model claude-opus-5-5啟動。歐元計價、每月使用範例及訂閱何時更划算，請參閱Claude Code 的歐元價格；每位使用者的用量可使用token 成本計算器計算。所有模型與價格均列於價格頁面。

使用 /status 確認

執行claude。設定ANTHROPIC_AUTH_TOKEN後，不會出現登入畫面：變數會立即生效。如果出現登入畫面，表示 Claude Code 沒有讀取任何金鑰。此時，請在 Claude Code 讀取首次啟動精靈前會讀取的位置設定金鑰：在 shell 中使用export，或在~/.claude/settings.json的env區塊中設定。在專案的.claude/settings.json或.claude/settings.local.json中設定env區塊時，互動工作階段只有在首次啟動精靈及信任資料夾的詢問之後才會套用。

Dentro da sessão, escreva /status e procure duas linhas no separador Status (fonte: a gateway 官方文件, consultada a 2026年10月3日):

• Anthropic base URL應顯示https://api.kunavo.com。只有在設定 gateway 位址時才會出現此行；若缺少，表示ANTHROPIC_BASE_URL未傳遞至工作階段。
• Auth token行應指示ANTHROPIC_AUTH_TOKEN。如果出現的是Login method，並搭配 claude.ai 帳戶，表示變數未被讀取，目前工作階段使用的是訂閱。

已使用訂閱登入的使用者，啟動時可能會看到有兩組憑證處於啟用狀態的警告（訊息以auth may not work as expected結尾）。請求會透過金鑰傳送；/logout會清除舊的登入狀態。

若要在開啟 Claude Code 前測試位址與金鑰，文件建議傳送只要求一個輸出 token 的請求，只會消耗極少一部分餘額。指令會讀取 shell 中的變數，因此即使變數已在settings.json中設定，也請在 shell 中再次設定。

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

以{"id":"msg_開頭的 JSON 回應表示位址與金鑰正常；在 PowerShell 中會出現以msg_開頭的id。出現401表示金鑰未被辨識。

API 金鑰帶來的變化

• 沒有 Remote Control 或語音聽寫。根據 gateway 相容性文件，當ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN或apiKeyHelper處於啟用狀態時，這些功能不可用；當ANTHROPIC_BASE_URL指向 Anthropic 以外的位址時，Remote Control 也會停用。
• /fast會顯示快速模式已停用。只有 bearer token 時，Claude Code 會將快速模式視為關閉。
• MCP 工具搜尋（MCP tool search）預設為關閉 quando ANTHROPIC_BASE_URL aponta para um endereço fora da Anthropic (環境變數文件, consultada a 2026年10月3日).
• /context中的數字是估計值。 O Kunavo não serve /v1/messages/count_tokens e, segundo a gateway 相容性文件 (consultada a 2026年10月3日), sem esse endpoint o Claude Code recorre a uma estimativa baseada em caracteres.

其餘功能——程式碼、工具、子代理、MCP 伺服器、hooks 與 prompt caching——均照常運作。更多詳情請參閱Claude Code 整合文件（英文）以及Claude Code without a subscription（英文）。

使用 MB WAY 支付餘額

Primeiro, a subscrição: uma subscrição Claude comprada no site paga-se só com cartão de crédito ou de débito (Anthropic 關於付費方案的說明文章, consultado a 2026年10月3日); numa subscrição feita na aplicação Claude para iOS ou Android, os meios de pagamento são os da App Store ou do Google Play. Os meios de pagamento do Kunavo, MB WAY incluído, não pagam o Claude Pro nem o Max: carregam o saldo da API do Kunavo, que é o que a Rota B usa.

O saldo carrega-se no checkout da Stripe. Os preços estão em dólares americanos; para quem compra em Portugal, a Stripe mostra o valor em euros. Segundo a Stripe 的 Adaptive Pricing 文件 (consultada a 2026年10月3日), essa conversão inclui uma comissão de 2–4% paga pelo comprador; quem escolhe pagar em dólares (com cartão, Apple Pay, Google Pay ou Link) não paga essa comissão, embora o banco possa aplicar a sua própria taxa de câmbio e comissões. O MB WAY só funciona em euros. No checkout em euros aparecem:

• MB WAY。 Escolhe-se MB WAY, introduz-se o número de telemóvel e confirma-se a compra na aplicação MB WAY, através da notificação ou na área de atividade (Stripe 關於 MB WAY 的文件 e MB WAY 關於線上購買的文件, consultados a 2026年10月3日). Segundo a Stripe, são aceites números internacionais, mas a maioria dos clientes usa um número português, começado por +351.
• 卡片（Visa、Mastercard）、Apple Pay、Google Pay 與 Link。

Não aparecem: referências Multibanco (pagamento por entidade e referência), PayPal, débito direto SEPA e Klarna, que só aparece a compradores nos Estados Unidos. A conversão para euros vem do Adaptive Pricing da Stripe, e a lista de meios de pagamento que ele disponibiliza inclui o MB WAY mas não o Multibanco. O MB WAY também permite gerar cartões virtuais MB NET para compras online (MB WAY 關於 MB NET 的文件, consultado a 2026年10月3日); não está confirmado que o campo do cartão do checkout os aceite, por isso o caminho seguro é escolher MB WAY diretamente.

Stripe 對 MB WAY 的文件內容（查閱於2026年10月3日）：

• 每筆付款：0.50 € 至 5000 €。
• 每日：預設為 1000 €，可在 MB WAY 應用程式中調整至 10 000 €。較大的儲值可能超過預設每日上限；在這種情況下，請在付款前於應用程式中提高上限。請將結帳頁面顯示的歐元金額與這些上限比較。
• 週期性付款：不支援。
• 對帳單會顯示 Stripe 的名稱（Stripe Inc）及交易金額。

1. 建立 Kunavo 帳戶。
2. 在帳務中選擇金額，最低為US$ 10。較大的儲值會獲得額外餘額：quem carrega US$ 100 recebe US$ 110; quem carrega US$ 1000 recebe US$ 1200; quem carrega US$ 5000 recebe US$ 6250。
3. 在 Stripe 結帳頁面中，確認歐元金額後選擇 MB WAY，輸入手機號碼，並在 MB WAY 應用程式中確認購買。歐元金額會在確認前顯示。
4. 在/app/keys中建立金鑰，並將其填入ANTHROPIC_AUTH_TOKEN。

餘額採預付制：無月費，餘額不會過期，失敗的請求不會收費。自動儲值只能使用已儲存的卡片或 Link；使用 MB WAY 時一律手動儲值，因為根據 Stripe，MB WAY 不接受週期性付款，也不會儲存以供日後付款。Kunavo 不開立發票，無論是否提供 NIF 或 IVA；儲值記錄位於 Billing。這些付款方式只能為 Kunavo API 餘額儲值。更多資訊請參閱使用 MB WAY 支付 Claude。

常見錯誤

安裝後

在專案中第一次啟動時，請輸入 /init：Claude Code 會掃描儲存庫，並撰寫一份 CLAUDE.md，記錄它推斷出的資訊：如何執行專案、如何測試變更，以及遵循哪些樣式規則。請檢閱此檔案並保持簡短，因為它會在每個工作階段載入。在獨立工作之間，/clear 會開始新的對話；在長時間工作中，/compact 會摘要歷史記錄以便繼續。

值得了解的事項

• 這是按 Token 計費的付費 API，不是 Claude Pro 或 Max 訂閱。每天使用 Claude Code 數小時的人，通常透過訂閱支付的費用較低；按 Token 計費適合使用不規律的情況，而閒置一個月不會產生費用。歐元比較請參閱 Claude Code 的歐元價格。
• 使用 API 金鑰的人無法使用 Remote Control 和語音聽寫。
• 透過 Kunavo 使用的是共享容量，沒有保留配額，也沒有合約保證；需要這些條件的人應直接與 Anthropic 簽約。
• MB WAY 僅用於手動儲值；自動儲值需要信用卡或 Link。
• 結帳頁面顯示的歐元金額已包含 Stripe 的換匯手續費。

常見問題