安裝 Claude Code：Windows、macOS 與 Linux 的指令——以及無訂閱使用方法

安裝 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 的那一行）。 接著開啟新的終端機，使用 claude --version 確認，並執行 claude 開始使用。第一次連線時有兩條路徑：使用 Pro、Max、Team、Enterprise 或 Console 帳戶登入（Claude.ai 免費方案不包含 Claude Code），或設定兩個環境變數 ANTHROPIC_BASE_URL 與 ANTHROPIC_AUTH_TOKEN，使用按用量付費的 API 金鑰——完全不需訂閱。

已在 2026年9月11日 的 Anthropic 官方安裝文件中核對過的命令。

安裝前

在 macOS 與 Linux 上安裝

開啟終端機並貼上：

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

這是建議的方法：它會安裝可在背景中自動更新的獨立二進位檔。捷徑位於 ~/.local/bin/claude，而已開啟的終端機不會看到新的 PATH——因此請開啟另一個視窗再進行測試。在 WSL 中命令相同。

在 Windows 上安裝

Windows 有兩行不同的命令，唯一差異在於你使用的終端機。如果提示字元以 PS C:\Users\SeuNome> 開頭，就是 PowerShell；沒有 PS、只有 C:\Users\SeuNome>，就是命令提示字元（CMD）。不需要以系統管理員身分執行。

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

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

把命令貼到錯誤的終端機是最常見的失敗原因。在 PowerShell 中執行 CMD 行會得到 The token '&&' is not a valid statement separator；在 CMD 中執行 PowerShell 行會得到 'irm' is not recognized as an internal or external command（葡萄牙文 Windows 會顯示「não é reconhecido como um comando interno ou externo」）。而把 macOS 的 curl … | bash 貼到 PowerShell 會得到 A parameter cannot be found that matches parameter name 'fsSL'。三種情況只要使用正確的命令即可。

安裝 Git for Windows 是選用項目，但建議安裝：Claude Code 會使用其中附帶的 Git Bash 執行命令；沒有它時則使用 PowerShell。如果 Git 已安裝但仍找不到 Git Bash，請在設定檔的 env 區塊中將 CLAUDE_CODE_GIT_BASH_PATH 設定為指向 bash.exe。

在 WSL 中，請於 WSL 終端機內執行 macOS/Linux 那一行，並直接在該處開啟 claude——不要透過 PowerShell 或 CMD。

透過套件管理器

可以運作，但有一項重要差異：這些套件預設都不會自動更新。你需要手動更新（brew upgrade claude-code、winget upgrade Anthropic.ClaudeCode）。此外也有適用於 Debian/Ubuntu、Fedora/RHEL 與 Alpine 的已簽署 apt、dnf 與 apk 套件庫。

# Homebrew (macOS, Linux) — canal stable
brew install --cask claude-code

# WinGet (Windows)
winget install Anthropic.ClaudeCode

# npm — exige Node.js 22 ou mais novo; nunca com sudo
npm install -g @anthropic-ai/claude-code

透過 npm 安裝時，自 2.1.198 版起，套件要求 Node.js 22 或更新版本；使用舊版 Node 時，npm 只會顯示 EBADENGINE 警告，安裝仍會完成。套件會安裝相同的原生二進位檔，執行時不使用 Node.js。絕對不要使用 sudo npm install -g：這會造成權限問題並帶來安全風險。

確認安裝

claude --version   # imprime a versão, por exemplo 2.1.211 (Claude Code)
claude doctor      # diagnóstico da instalação e das configurações, sem abrir sessão

記住 claude doctor：不需建立工作階段，它會顯示安裝狀態、設定檔錯誤與建議修正方式——這是最快判斷問題出在安裝還是設定的方法。

如果出現 command not found: claude（或 Windows 顯示無法辨識 claude），表示安裝資料夾不在 PATH 中。在 macOS 與 Linux 上，開啟新的終端機；若仍未解決，請將 ~/.local/bin 加入 ~/.zshrc 或 ~/.bashrc 的 PATH。在 Windows 上，資料夾是 %USERPROFILE%\.local\bin；請檢查並透過 PowerShell 加入：

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

# 2. Sem saída? Adicione ao PATH do usuário e abra um terminal novo
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. No terminal novo: se houver duas instalações, aparecem dois caminhos
where.exe claude

第一次連線：訂閱或 API 金鑰

路徑 A——使用訂閱登入

在專案資料夾中執行 claude，並使用 Pro、Max、Team、Enterprise 或 Console 帳戶依照瀏覽器中的登入流程操作。一項常造成混淆的細節是：如果已設定 ANTHROPIC_API_KEY 變數，Claude Code 會詢問一次是否使用該金鑰。如果拒絕，它會靜默忽略該金鑰，不再詢問——看起來就像沒有讀取變數。若要重新啟用，請前往 /config → Use custom API key。

路徑 B——不使用訂閱，改用按用量付費的金鑰

Claude Code 原生讀取 ANTHROPIC_BASE_URL，因此將它指向任何 Anthropic Messages API 端點都是受支援的設定——不需要外掛、代理伺服器或修改過的二進位檔。流程如下：建立帳戶、儲值（最低 $10）、在金鑰面板中產生 sk-kn- 金鑰（只會顯示一次），然後設定變數。在 macOS 與 Linux 上：

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

若要永久設定，最佳位置是使用者設定檔案 ~/.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"
  }
}

每一行都有需要注意的地方：

• ANTHROPIC_BASE_URL 只包含網域。 Claude Code 會附加 /v1/messages；若結尾包含 /v1，請求會送至 /v1/v1/messages 並回傳 404。
• 使用 ANTHROPIC_AUTH_TOKEN，不要使用 ANTHROPIC_API_KEY。 它們會放在不同的 HTTP 標頭中：前者傳送 Authorization: Bearer 並立即生效；後者傳送 x-api-key，且還需要上述的一次性核准。
• 在 ANTHROPIC_MODEL 中填寫確切的模型名稱。 Kunavo 只辨識完全相同的名稱，不會翻譯名稱結尾帶日期的舊模型。
• 也請固定 ANTHROPIC_DEFAULT_OPUS_MODEL 和 ANTHROPIC_DEFAULT_SONNET_MODEL。Claude Code 的預設模型和 opus 別名會指向最新的 Opus；如果 Kunavo 尚未提供該模型，第一個請求會回傳 404。sonnet 別名已經要求 Sonnet 5.5，而 Kunavo 不提供該模型：如果不固定它，/model sonnet、opusplan 的執行階段以及使用 model: sonnet 的子代理程式都會收到 404。opus 別名會固定到 Opus 5.5（claude-opus-5-5），需要 Claude Code v2.1.280 或更新版本；在舊版安裝上請執行 claude update。
• ANTHROPIC_DEFAULT_HAIKU_MODEL 涵蓋 Claude Code 自行發出的背景呼叫（摘要、標題）。將其指向 Haiku 就能輕鬆節省成本。

絕對不要將金鑰放在專案的 .claude/settings.json 中——該檔案會進入 git，也會提供給複製儲存庫的人。在 VS Code 擴充功能中，變數應放在 claudeCode.environmentVariables，也就是 VS Code 本身的使用者設定中，因為擴充功能會在啟動前檢查憑證。

從目錄讀取的每 1M 個權杖費率：

若要在工作階段內切換模型，請使用 /model 搭配完整名稱（例如 /model claude-opus-5-5），或使用 claude --model claude-opus-5-5 啟動 Claude Code。每月使用成本與訂閱何時更划算，請參閱 Claude Code 價格指南。

如何確認目前啟用的路徑

在 Claude Code 中執行 /status。出現 Auth token 行表示金鑰正在生效；出現 Login method 行且搭配 claude.ai 帳戶，表示未讀取變數。兩者不會疊加：設定變數後，訂閱會暫停；移除變數後，它會回到訂閱模式，不需要重新安裝。

透過閘道時有三件事會改變：Remote Control 與語音聽寫無法運作（需要 claude.ai 身分）；/fast 可能顯示快速模式不可用，因為該檢查會直接連線至 Anthropic，但一般請求不會改變；而 /context 中的數字會變成當地估算值。程式碼、工具、子代理程式、MCP、hooks 與提示快取的運作方式相同。詳細資訊請參閱整合文件（英文）。

從巴西付款 — 結帳頁面中的 Pix

claude.ai 訂閱是以美元計費的定期扣款，需要已啟用海外購物功能的國際卡片。在 API 金鑰流程中，儲值會經過 Stripe 結帳頁面，對於從巴西付款的使用者，Pix 會顯示為付款方式：價格以 USD 計算，Stripe 會在您確認前顯示換算成巴西雷亞爾的金額。國際卡片（Visa、Mastercard、American Express）、Apple Pay、Google Pay 和 Link 也會出現在結帳頁面。這是預付錢包——最低儲值 $10，餘額不會過期，失敗的請求不會收費——而且每把金鑰都可以設定每月支出上限。逐步的畫面說明請參閱 如何使用 Pix 支付 API。

常見錯誤

安裝後

第一次使用時，請在專案內執行 /init：Claude Code 會讀取儲存庫，並產生包含測試命令與所找到慣例的 CLAUDE.md。請檢查此檔案並保持簡短——它會在每個工作階段載入。在不相關的工作之間，/clear 會開始新的對話；對於已經很長的工作，/compact 會摘要歷史記錄並繼續。

坦白說，選擇方式如下：每天長時間使用 Claude Code 的人，訂閱月費通常更便宜；當使用量波動，或你不想受 5 小時視窗限制時，按用量付費更划算——而完全不用的月份費用為零。透過 Kunavo，你使用的是共用容量，沒有專用配額，也沒有合約 SLA；需要這些保障的人應直接向 Anthropic 訂購。

常見問題