Claude Code 安裝教學 — macOS、Windows 指令，裝好後用訂閱或 API 金鑰連線

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 官方安裝文件。這頁只講安裝和第一次連線；裝好之後的日常用法見 Claude Code 教學。

安裝前確認

macOS 安裝

打開「終端機」，貼上這一行：

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

這是官方建議的原生安裝方式：裝的是獨立執行檔，會在背景自動更新。執行檔的入口在 ~/.local/bin/claude；已經開著的終端機不會讀到新的 PATH，所以裝完請開一個新視窗。Linux 和 WSL 用的是同一行指令。

Windows 安裝

Windows 有兩行不同的指令，差別只在你開的是哪一種終端機。提示字元是 PS C:\Users\你的名字> 就是 PowerShell；沒有 PS、只有 C:\Users\你的名字> 的是命令提示字元（CMD）。不需要用系統管理員身分執行。

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

:: Windows 命令提示字元（CMD）
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

貼錯地方是 Windows 上最常見的失敗。PowerShell 裡跑了 CMD 那行，會看到 The token '&&' is not a valid statement separator；CMD 裡跑了 PowerShell 那行，會看到 'irm' is not recognized as an internal or external command。把 macOS 的 curl … | bash 貼進 PowerShell，則會出現 A parameter cannot be found that matches parameter name 'fsSL'。三種情況都是換回對應的那一行就好。

建議另外安裝 Git for Windows：Claude Code 會用它附帶的 Git Bash 執行指令；沒裝的話，它改用 PowerShell 執行。如果裝了卻找不到 Git Bash，在設定檔的 env 區塊加上 CLAUDE_CODE_GIT_BASH_PATH，指到 bash.exe 的路徑。

選 WSL 的話，要在 WSL 的終端機裡執行上面 macOS／Linux 那一行，也在 WSL 裡啟動 claude，不是從 PowerShell 或 CMD。

用套件管理工具安裝

想讓既有的套件管理工具管理也可以，代價是預設都不會自動更新，要自己定期升級（例如 brew upgrade claude-code、winget upgrade Anthropic.ClaudeCode）。Debian／Ubuntu、Fedora／RHEL、Alpine 另有官方簽章的 apt、dnf、apk 套件庫。

# Homebrew（macOS、Linux）— stable 通道
brew install --cask claude-code

# WinGet（Windows）
winget install Anthropic.ClaudeCode

# npm — 需要 Node.js 22 以上；絕對不要加 sudo
npm install -g @anthropic-ai/claude-code

npm 這條路從 v2.1.198 起需要 Node.js 22 以上；版本較舊時 npm 只會印出 EBADENGINE 警告，安裝仍會完成。它裝的是和原生安裝程式同一份執行檔，執行時並不依賴 Node.js。千萬不要用 sudo npm install -g，會留下權限問題，也有安全風險。

確認安裝成功

claude --version   # 正常會印出版本號，例如 2.1.211 (Claude Code)
claude doctor      # 唯讀的安裝與設定診斷，不會開啟工作階段

claude doctor 最值得記住：它不開工作階段，只列出安裝狀態、設定檔的錯誤和建議修法，是分辨「安裝壞了」還是「設定壞了」最快的方法。

如果出現 command not found: claude，或 Windows 上的 'claude' is not recognized，代表安裝目錄不在 PATH 裡。macOS／Linux 先開新的終端機再試，還是不行就把 ~/.local/bin 加進 ~/.zshrc 或 ~/.bashrc 的 PATH。Windows 的安裝位置是 %USERPROFILE%\.local\bin，用 PowerShell 檢查並加入：

# 1. 檢查安裝目錄是否已在 PATH 裡
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. 沒有任何輸出的話，把它加進「使用者」PATH，然後關掉終端機重開
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. 重開後再確認一次；若有兩份安裝，這行會列出兩個路徑
where.exe claude

第一次連線：訂閱登入，或按量計費金鑰

路線 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   # 只寫到網域，不要加 /v1
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

Windows 想先在一個 PowerShell 視窗裡試：

# 只對這個 PowerShell 視窗有效，關掉就沒了
$env:ANTHROPIC_BASE_URL = "https://api.kunavo.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-kn-..."
$env:ANTHROPIC_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_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_HAIKU_MODEL 負責背景呼叫。Claude Code 自己做的摘要、標題都走這個模型：Claude Haiku 4.5 每 1M token $0.40 / $2.00，主力的 Claude Sonnet 5 是 $2.00 / $10.00（與 Anthropic 官方同價）。

金鑰不要寫進專案裡的 .claude/settings.json——那個檔案會被 commit，分享給每個 clone 專案的人。用 VS Code 擴充套件的話，變數要放在 VS Code 使用者設定的 claudeCode.environmentVariables，因為擴充套件在啟動前就會先檢查憑證。

確認連上的是哪一條路

進入 Claude Code 後執行 /status。看到 Auth token 那一行，代表金鑰正在生效；看到 Login method 並列出 claude.ai 帳號，代表變數沒有被讀到。兩者不會疊加：只要金鑰變數還在，已登入的訂閱就被擱置；把變數移除就回到訂閱，不必重裝。

走閘道時有三件事會不一樣：Remote Control 和語音輸入需要 claude.ai 身分，無法使用；/fast 的可用性檢查會直接問 Anthropic，可能顯示無法使用，但一般請求不受影響；/context 的數字變成本機估算。寫程式、工具、子代理、MCP、hooks 和提示快取都照常運作。完整說明在 Claude Code 整合文件與 Claude Code API key 指南（皆為英文）。

常見錯誤對照

裝好之後

第一次進專案，先跑 /init 讓它讀過整個專案、產生 CLAUDE.md。之後怎麼依任務切換 Opus、Sonnet、Haiku，一個工作階段實際花多少，怎麼用 /clear、/compact 把花費壓低，都在 Claude Code 教學。

選哪條路，也值得老實說：每天長時間互動、用量很大的人，訂閱的固定月費通常比較划算；按量計費適合用量起伏大、或不想被 5 小時用量窗口卡住的人，沒開工的月份是 $0。透過 Kunavo 用的是共享容量，沒有專屬配額，也沒有合約 SLA，需要這些保證的團隊應該直接向 Anthropic 採購。兩條路的月費與損益平衡點在 Claude Code 費用。

常見問題