如何在 Windows、macOS 與 Linux 安裝 Claude Code——以及如何不使用訂閱方案

安裝 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；第一個實用命令是 /init。連線有兩種方式：使用 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 上安裝 Claude Code

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

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

:: Windows Símbolo del sistema (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 會顯示「無法將其辨識為內部或外部命令」）；將 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 — requiere Node.js 22 o posterior; nunca con 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 la versión, por ejemplo 2.1.211 (Claude Code)
claude doctor      # diagnóstico de la instalación y la configuración, sin abrir sesión

保留 claude doctor 即可：不登入也能顯示安裝狀態、設定檔錯誤和建議的解決方案。這是判斷問題出在安裝還是設定的最快方式。

如果看到 command not found: claude（或在 Windows 上看到 claude 無法辨識），表示安裝資料夾不在 PATH 中。在 macOS 和 Linux 上開啟新的終端機；若仍然相同，請在 ~/.zshrc 或 ~/.bashrc 中將 ~/.local/bin 加入 PATH。在 Windows 上，資料夾是 %USERPROFILE%\.local\bin；請確認後從 PowerShell 加入：

# 1. Comprueba si la carpeta de instalación ya está en el PATH
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. ¿Sin salida? Añádela al PATH de usuario y abre una terminal nueva
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. En la terminal nueva: si hay dos instalaciones, verás dos rutas
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- 金鑰（只會顯示一次），並將以下 env 區塊加入使用者設定 ~/.claude/settings.json（Windows 上為 %USERPROFILE%\.claude\settings.json）。如此所有終端機、編輯器擴充功能和背景程序都能使用：

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

若要先在單一 PowerShell 視窗中測試：

# Solo para esta ventana de PowerShell (en macOS/Linux: export VARIABLE=valor)
$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

• 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。Claude Code 的預設模型及其別名 opus 指向最新的 Opus；如果 Kunavo 尚未提供該模型，第一次請求會回傳 404。此處將別名 opus 固定為 Claude Opus 5.5（claude-opus-5-5），這需要 Claude Code v2.1.280 或更新版本；若使用較舊版本，請執行 claude update。
• 也固定 ANTHROPIC_DEFAULT_SONNET_MODEL。別名 sonnet 會要求 Sonnet 5.5，而 Kunavo 不提供該模型：若沒有此變數，/model sonnet、opusplan 的執行階段，以及使用 sonnet 設定的子代理程式都會回傳 404。將其固定為 claude-sonnet-5 即可避免此問題。
• ANTHROPIC_DEFAULT_HAIKU_MODEL 涵蓋 Claude Code 自行執行的背景呼叫（摘要、標題）：將其指向 Haiku 就能輕鬆節省成本。

絕對不要將金鑰放在專案的 .claude/settings.json 中：該檔案會提交至儲存庫。在 VS Code 擴充功能中，變數應放在 claudeCode.environmentVariables，也就是 VS Code 的使用者設定中，因為擴充功能會在啟動前驗證憑證。

每 1M token 的價格，取自目錄：

如何確認目前啟用的選項

在 Claude Code 中執行 /status。Auth token 行表示正在使用金鑰；帶有 claude.ai 帳戶的 Login method 行表示未讀取該變數。兩者不會疊加：只要變數存在，訂閱就會暫停使用；移除變數後，Claude Code 會回到訂閱，不需重新安裝。

使用閘道時有三項差異：Remote Control 和語音聽寫無法使用（需要 claude.ai 身分）；/fast 可能顯示快速模式不可用，因為該檢查會直接連到 Anthropic，但一般請求不受影響；而 /context 的數值會變成本機估算。程式碼、工具、子代理、MCP、hooks 和提示快取的運作方式都相同。所有細節請參閱整合文件和Claude Code API 金鑰指南（兩者皆為英文）。

如何使用 Claude Code：開始使用

# 1. Arranca siempre dentro de la carpeta del proyecto
cd ~/proyectos/mi-app
claude

# 2. Primer comando: lee el repositorio y genera CLAUDE.md
> /init

# 3. Pide las tareas en español y con la ruta del archivo
> cambia la validación de src/api/user.ts a zod y arregla los tests

# 4. Para tareas que tocan muchos archivos: Shift+Tab activa el modo plan

Claude Code 會在編輯檔案或執行命令前要求許可；如果方向不對，按 Esc 可停止，並使用 /rewind 回到先前的狀態。/init 產生的 CLAUDE.md 是草稿：只保留你每次工作階段都會重複的內容（測試命令、慣例、不應修改的資料夾）。它會在每個工作階段載入並隨每個請求傳送，Anthropic 建議不要超過 200 行。

• 切換模型： 輸入 /model 加上完整名稱，例如 /model claude-opus-5，或以 claude --model claude-opus-5 啟動。請在任務之間切換：每個模型都有自己的快取，在任務中途切換會迫使系統重新讀取整段對話，無法使用快取。
• 在不相關的任務之間使用 /clear。 開始新的對話不會產生費用；先前的對話可透過 /resume 還原。
• 任務變長時使用 /compact： 摘要歷史記錄並繼續。使用 API 金鑰時，快取預設持續五分鐘，因此應在長時間暫停前壓縮，而不是之後才壓縮。
• 工作階段的費用： /usage 會顯示 token 數量，但其計算的金額是依 Anthropic 定價計算的本機估算；使用 Kunavo 時，實際費用會顯示在你的使用量頁面。

付款與誠實面對選擇

餘額透過 Stripe 預付：可使用信用卡（Visa、Mastercard、American Express、JCB、UnionPay）、Apple Pay、Google Pay 或 Link；不提供 SEPA 直接扣款。最低儲值金額為 $10，餘額不會過期，失敗的請求不會收費，且每組金鑰都有每月支出上限。所有費率都在價格頁面。

如果你每天長時間使用 Claude Code，訂閱的固定費用通常更便宜；當使用量不規律，或你不想受 5 小時視窗限制時，按用量付費更划算，而整月沒有活動時費用為零。完整比較（英文）請參閱Claude Code pricing。透過 Kunavo 使用的是共享容量，沒有專用配額或合約 SLA；如果需要這些保障，請直接向 Anthropic 訂閱。

常見問題