返回指南
設定·2026年8月5日·更新於 2026年10月3日·閱讀約 8 分鐘

安裝 Claude Code——適用所有作業系統的指令、首次登入與常見錯誤

Claude Code 在每個平台上都只需一個指令即可安裝。以下列出各作業系統的指令、無法運作時應執行的內容，以及之後將其指向不同端點的四個環境變數。

最後審核於 。

Claude Code 在每個支援的平台上都能透過單一命令安裝，第一次執行的完整流程是：安裝、輸入 claude、登入。本指南提供每個作業系統的確切命令、無法運作時應檢查的項目，以及成功後如何將其指向不同端點。

已驗證命令 2026年10月3日，依據Anthropic 的 Claude Code 設定文件。

開始之前

需求支援內容
作業系統macOS 13.0+、Windows 10 1809+ / Server 2019+、Ubuntu 20.04+、Debian 10+、Alpine Linux 3.19+
硬體4 GB+ RAM、x64 或 ARM64
命令殼層Bash、Zsh、PowerShell 或 CMD
網路需要網際網路連線
帳戶Pro、Max、Team、Enterprise 或 Console — 免費的 Claude.ai 方案不包含 Claude Code

安裝 — 原生安裝程式

這是每個平台上的建議方法。它會安裝自含式二進位檔，並在背景自動更新。

install.sh
# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash
PowerShell
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
cmd.exe
:: Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

如果你不確定目前使用哪個 Windows shell，提示字元會告訴你：PowerShell 顯示 PS C:\，CMD 顯示沒有 PS 的 C:\。使用錯誤的命令是 Windows 上最常見的安裝失敗原因 — 請參閱下方疑難排解表，查看兩種情況各自的確切錯誤。

套件管理員

如果你希望由現有套件管理員管理安裝，請使用這些方式。取捨在於更新：與原生安裝程式不同，這些方式預設都不會自動更新。

package-managers.sh
# Homebrew (macOS, Linux) — stable channel
brew install --cask claude-code

# WinGet (Windows)
winget install Anthropic.ClaudeCode

# npm — requires Node.js 22+; never with sudo
npm install -g @anthropic-ai/claude-code

Homebrew 發布兩個 cask：claude-code 追蹤穩定頻道（通常落後約一週，並跳過有重大回歸問題的版本），claude-code@latest 則會立即發布每個版本。Debian / Ubuntu、Fedora / RHEL 與 Alpine 分別都有簽署的 apt、dnf 與 apk 儲存庫，每個儲存庫都有相同的 stable 與 latest 頻道。

使用 npm 時，絕不要使用 sudo npm install -g — 它會造成權限問題並帶來安全風險。npm 套件安裝的原生二進位檔與獨立安裝程式完全相同，因此無論採用哪種方式，執行時都不需要 Node。

驗證安裝

verify.sh
claude --version   # prints e.g. "2.1.211 (Claude Code)"
claude doctor      # read-only install + settings diagnostics
claude             # start a session in the current project

claude doctor 是最值得記住的命令：它會列出安裝健康狀態、設定檔驗證錯誤與建議修正方式，但不會啟動工作階段，因此是判斷安裝損壞還是設定損壞的最快方法。

第一次執行與登入

在你想要工作的專案中開啟終端機，並執行 claude。它會開啟互動式工作階段，並引導你在瀏覽器中登入。Claude Code 需要 Pro、Max、Team、Enterprise 或 Console 帳戶。

有一項行為值得事先了解，以免日後感到意外：如果環境中已設定 ANTHROPIC_API_KEY，Claude Code 會提示一次讓你核准該金鑰，而不是開啟瀏覽器。拒絕該提示後，金鑰會從此被靜默忽略，不再進一步提示 — 看起來就像程式沒有讀取該變數。在 /config → 使用自訂 API 金鑰 中重新啟用。

Windows：原生或 WSL

選項需要沙箱化在以下情況選擇它
原生 Windows無；Git for Windows 可選不支援你的專案與工具原生執行於 Windows
WSL 2已啟用 WSL 2支援Linux 工具鏈，或你希望進行沙箱化命令執行
WSL 1已啟用 WSL 1不支援你無法使用 WSL 2

在原生 Windows 上，安裝 Git for Windows 可選但建議安裝：它提供支援 Bash 工具的 Git Bash。沒有它時，Claude Code 會改用 PowerShell 工具執行 shell 命令。在 WSL 下，你應在 WSL 終端機內安裝並啟動 claude，而不是從 PowerShell 啟動。

疑難排解

症狀原因與修正方式
The token '&&' is not a valid statement separator你在 PowerShell 中執行了 CMD 命令。請改用 irm … | iex 這一行。
'irm' is not recognized…相反情況 — 你在 CMD 中執行了 PowerShell 命令。請使用 curl … install.cmd 這一行。
syntax error near unexpected token '<'、403 或其他 curl 錯誤下載未傳回指令碼 — 通常是因為你與安裝程式之間存在代理伺服器或網路篩選器。請重試，或改用套件管理員安裝。
乾淨安裝後出現 claude: command not found開啟新的終端機，讓 shell 取得安裝目錄，然後執行 claude doctor。另一個常見原因是第二個較舊的安裝，或過時的 shell 別名。
npm 安裝期間發生權限錯誤你使用了 sudo，或 npm 全域目錄不可寫入。請修正目錄所有權，不要用 sudo 重新執行；不可寫入的全域目錄也會阻止自動更新。
npm install -g 後缺少原生二進位檔你的套件管理員已設定為略過選用相依套件。平台二進位檔就是其中一個選用相依套件，因此請允許它們並重新安裝。
在 Alpine 或其他 musl 發行版上安裝失敗Alpine 未隨附 bash 與 curl。請安裝 bash curl libgcc libstdc++ ripgrep，然後在設定檔的 env 區塊中，將 USE_BUILTIN_RIPGREP 設為 "0"。
搜尋與檔案探索失敗通常會隨附 ripgrep。如果它無法在你的平台上執行，請安裝系統 ripgrep 並設定 USE_BUILTIN_RIPGREP=0。
原生 Windows 缺少 Bash 工具請安裝 Git for Windows。如果 Claude Code 仍找不到 Git Bash，請在 ~/.claude/settings.json 的 env 區塊中設定 CLAUDE_CODE_GIT_BASH_PATH。
設定金鑰後出現 401金鑰位於伺服器不會讀取的標頭中 — 請在 ANTHROPIC_AUTH_TOKEN 與 ANTHROPIC_API_KEY 之間切換。詳細資訊請參閱API 金鑰指南。

將 Claude Code 指向 Kunavo

Claude Code 執行後，可搭配任何提供 Anthropic Messages API 的端點運作 — 它原生讀取 ANTHROPIC_BASE_URL，因此這是受支援的設定，而非權宜方案。不需要外掛、代理伺服器或修補過的二進位檔：

~/.zshrc
export ANTHROPIC_BASE_URL=https://api.kunavo.com
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

關於該區塊有五件事必須注意，任何一項弄錯都會讓你多花一小時：

  • ANTHROPIC_BASE_URL 只能是來源。 Claude Code 會自行附加 /v1/messages — 如果連路徑也加上，會得到 404。
  • 使用 ANTHROPIC_AUTH_TOKEN，不要使用 ANTHROPIC_API_KEY。 它們會放在不同的 HTTP 標頭中。Bearer token 會立即生效，而 ANTHROPIC_API_KEY 需要依照上述說明進行一次性核准。Kunavo 會讀取任一標頭中的金鑰，包括 /v1/models，因此在 Kunavo 上，區分兩者的就是該核准步驟。
  • 明確設定 ANTHROPIC_MODEL。 Kunavo 會精確比對模型 slug，不會為名稱加上日期後綴的模型建立別名，因此 claude-sonnet-4-5-20250929 會回傳 404，而 claude-sonnet-5 可以運作。
  • 也請固定設定 ANTHROPIC_DEFAULT_OPUS_MODEL 與 ANTHROPIC_DEFAULT_SONNET_MODEL。 Claude Code 內建的預設值及其 opus 別名都會解析為最新的 Opus；如果 Kunavo 尚未提供該模型，第一個請求就會回傳 404。此區塊會將 opus 固定為 Opus 5.5（claude-opus-5-5），需要 Claude Code v2.1.280 或更新版本 — 舊版本請執行 claude update。sonnet 別名會要求 Sonnet 5.5，而 Kunavo 不提供此模型，因此沒有 Sonnet 固定設定 /model sonnet 時，opusplan 的執行階段及任何設定為 model: sonnet 的子代理程式都會回傳 404。
  • ANTHROPIC_DEFAULT_HAIKU_MODEL 負責處理背景呼叫，這些呼叫是 Claude Code 為產生摘要與標題而自行發出的。claude-haiku-4-5 的費用為每 1M $0.70 / $3.50，主力模型則為每 1M $1.40 / $7.00，因此只需一行就能持續節省費用。

如果希望編輯器與背景代理程式也能看到這些設定，請將它們放在 ~/.claude/settings.json 的 env 區塊中，而不是 shell export 中 — 絕不要放進專案已提交的 .claude/settings.json。請在控制面板中註冊後建立 sk-kn- 金鑰；最低儲值額為 $10，沒有月費，餘額也不會過期。相對於Anthropic 官方 API 定價，每個模型按 token 計價的金額，決定了這 $10 能用多久。

閘道後哪些內容會改變

程式撰寫、工具、子代理程式、MCP、hooks 與提示快取都不受影響。確實會改變的有三件事，在你以為某些功能損壞之前，值得先了解：

  • Remote Control 與語音聽寫無法使用。 兩者都需要 claude.ai 身分，而閘道憑證會取代該身分。
  • /fast 可能會回報快速模式已停用。 可用性檢查會直接呼叫 Anthropic，而不會遵循你的 base URL。一般請求不受影響。
  • /context 計數會變成在地估算值。 Token 計數是 Anthropic 自有閘道規格標示為選用的唯一端點；缺少時，Claude Code 會在本地估算 — Kunavo 目前不提供 /v1/messages/count_tokens。自動壓縮與工作階段本身不受影響。

完整清單，以及是否使用路由器的決策，請參閱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 中執行 `curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd`。原生安裝程式是建議方法，並會在背景自動更新。也支援 Homebrew（`brew install --cask claude-code`）、WinGet（`winget install Anthropic.ClaudeCode`）、npm，以及簽署的 apt/dnf/apk 儲存庫，但這些方式預設都不會自動更新。

安裝 Claude Code 需要 Node.js 嗎？

使用原生安裝程式、Homebrew、WinGet 或 Linux 套件儲存庫時不需要 — 它們都會安裝執行時不使用 Node 的原生二進位檔。只有 npm 安裝路徑涉及 Node；截至 v2.1.198，該套件需要 Node.js 22 或更新版本。即使如此，npm 也只是透過依平台而定的選用相依套件引入相同的原生二進位檔。

Claude Code 的系統需求是什麼？

macOS 13.0+、Windows 10 1809+ 或 Windows Server 2019+、Ubuntu 20.04+、Debian 10+ 或 Alpine Linux 3.19+；x64 或 ARM64 處理器上的 4 GB 以上 RAM；網際網路連線；以及 Bash、Zsh、PowerShell 或 CMD shell。此外，你必須位於 Anthropic 支援的國家/地區。

第一次如何登入 Claude Code？

在專案目錄中執行 `claude`，並依照瀏覽器提示操作。Claude Code 需要 Pro、Max、Team、Enterprise 或 Console 帳戶 — 免費的 Claude.ai 方案不包含 Claude Code 存取權。如果已設定 ANTHROPIC_API_KEY 環境變數，Claude Code 會提示你一次以核准該金鑰，而不是開啟瀏覽器。

可以不使用 WSL 在 Windows 上安裝 Claude Code 嗎？

可以。執行 PowerShell 或 CMD 安裝程式，並從任何終端機啟動 `claude`；不需要系統管理員權限。Git for Windows 可選但建議安裝，因為它提供支援 Bash 工具的 Git Bash — 沒有它時，Claude Code 會改用 PowerShell 工具執行 shell 命令。如果你需要 Linux 工具鏈或沙箱化命令執行，WSL 2 是應選的方案，原生 Windows 不支援這些功能。

為什麼安裝後 `claude` 顯示找不到命令？

安裝目錄不在你所使用 shell 的 PATH 中。先開啟新的終端機 — 安裝程式會在 macOS 與 Linux 上加入 ~/.local/bin，而現有工作階段不會取得這項變更。執行 `claude doctor`，取得安裝與設定檔的唯讀診斷結果。另一個常見原因是第二個較舊的安裝，或殘留的 shell 別名。

如何讓 Claude Code 指向不同的 API 端點？

將 ANTHROPIC_BASE_URL 設定為任何提供 Anthropic Messages API 之端點的來源網址 — Claude Code 原生讀取此設定，並自行附加 /v1/messages，因此不涉及外掛程式或代理伺服器。將其與 ANTHROPIC_AUTH_TOKEN 搭配作為憑證，並將 ANTHROPIC_MODEL 明確設定為端點所提供的模型；同時將 ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL 與 ANTHROPIC_DEFAULT_HAIKU_MODEL 固定為端點提供的模型，因為 Opus 與 Sonnet 別名否則會跟隨 Anthropic 最新的模型。在 Kunavo 上，這些模型以 Anthropic 定價低 30% 的價格按量計費。

下一步