Claude Code 安裝教學：Windows、macOS 安裝指令，不登入帳戶使用 API key 設定，以及使用支付寶、微信支付儲值

Claude Code 建議使用 Anthropic 官方原生安裝命令安裝，npm 是官方備選方式，需要 Node.js 22 以上。不登入 Claude 帳戶也能使用 Claude Code：設定 ANTHROPIC_BASE_URL（只寫到網域，不加 /v1）、ANTHROPIC_AUTH_TOKEN 以及四行模型固定設定，即可改用按 token 計費的 API key。Kunavo 的 API 餘額可以使用支付寶或微信支付儲值，最低 $10。最後在 Claude Code 中執行 /status 確認連線。

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

# 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

命令和环境变量核对于 2026年10月3日，依据 Claude Code 官方安裝文件和 官方環境變數文件；价格和付款方式核对于 2026年10月3日。先说明一个事实：Anthropic 支援的國家和地區名單（核对于 2026年10月3日）中没有中国大陆、香港和澳门，Claude Code 安装文档的系统要求里也有一行「所在地区：Anthropic 支持的国家」。本页只讲官方文档写明的安装和配置方法，不提供任何绕过地区限制的办法。Kunavo 没有在中国大陆做过网络连通性测试，下面提到的下载地址、npm 源和 api.kunavo.com 能否在你的网络里访问，需要你自己确认。

安裝前確認

方式一：官方原生安裝（推薦）

官方安裝文件將原生安裝列為推薦方式，命令就是本頁開頭的三段：macOS、Linux 和 WSL 使用 install.sh 那一行，Windows PowerShell 使用 irm … | iex，Windows CMD 使用 install.cmd 那一行。原生安裝會在背景自動更新到最新版本；官方文件同時指出，Homebrew 和 WinGet 安裝預設不會自動更新。

安裝完成後開啟新的終端機視窗（已開啟的視窗讀不到新的 PATH），然後確認：

claude --version   # 正常会打印版本号，后面跟着 (Claude Code)
claude doctor      # 只读的安装与设置诊断，不会开启会话

claude doctor 不會開啟工作階段，只會列印安裝狀態和設定檔的診斷資訊，可用來判斷是「安裝損壞」還是「設定損壞」。

下載出錯時

如果终端里出现 syntax error near unexpected token '<' 或 curl: (22) The requested URL returned error: 403，按 官方安裝疑難排解文件（核对于 2026年10月3日）的说法，这表示安装地址返回的是一个网页或错误状态码，而不是安装脚本。如果返回的网页写着 App unavailable in region，官方的解释是：Claude Code 在你所在的国家或地区不可用。不带网页内容的 403 也可能来自公司代理或防火墙拦截下载；官方建议，在支持地区内仍然遇到 403 时，先排查网络连接，再考虑其他安装方式。

方式二：npm 安裝（需要 Node.js 22 以上）

npm 仍是官方文档列出的安装方式。官方文档写明 npm 包需要 Node.js 22 或更高版本；版本较旧时 npm 会打印 EBADENGINE 警告但不会失败，安装照样完成，因为这个包下载的是一个运行时不依赖 Node.js 的原生程序。没有 Node.js 的话，从 Node.js 官方網站安装 22 或更高版本。

node -v                                    # 需要 v22 或更高
npm install -g @anthropic-ai/claude-code   # 不要加 sudo

官方文件明確要求不要使用 sudo npm install -g，否則會產生權限問題和安全風險。升級時使用 npm install -g @anthropic-ai/claude-code@latest，不要使用 npm update -g。

預設來源下載失敗或速度很慢時：npmmirror

如果从 npm 默认源下载失败或很慢，可以改用 npmmirror。npmmirror 首頁（核对于 2026年10月3日）说明它是「完整 npmjs.com 镜像」，只读，会「尽量与官方服务实时同步」，并给出了 registry 地址和设置命令。首页没有写明具体同步频率。

# 只在这一次安装时使用 npmmirror
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

# 或者把 npmmirror 设为 npm 的默认源（之后所有 npm 安装都会走它）
npm config set registry https://registry.npmmirror.com

# 以后升级用 @latest，不要用 npm update -g
npm install -g @anthropic-ai/claude-code@latest --registry=https://registry.npmmirror.com

使用鏡像安裝 Claude Code 有兩個容易忽略的條件，兩者都來自官方疑難排解文件：

• 鏡像必須同時提供 8 個平台套件。npm 套件本身只是一個外殼，真正的程式會以 @anthropic-ai/claude-code-* 平台套件的形式，作為選用相依套件下載。鏡像缺少平台套件時，安裝完成後在 macOS 或 Linux 上執行 claude 會提示 claude native binary not installed（Windows 上則會由 PowerShell 或 CMD 回報無法執行此檔案）。2026年10月3日，Kunavo 從中國大陸以外的網路查看，npmmirror 上的主套件以及 Windows x64、macOS ARM64、Linux x64 三個平台套件與 npmjs 的最新版本一致；其餘平台套件（ARM64 Windows、Intel Mac、ARM64 Linux 和兩個 musl 版本）未核對。
• 不能略過選用相依套件。安裝命令中不要帶 --omit=optional，也要確認 .npmrc 中沒有設定 optional=false。

Windows 專項

Windows 有兩條不同的安裝命令，差別只在於你開啟的是哪種終端機。提示字元是 PS C:\Users\你的用户名> 的是 PowerShell；沒有 PS、只有 C:\Users\你的用户名> 的是命令提示字元（CMD）。官方文件說明安裝不需要以系統管理員身分執行。

Windows 上常見的錯誤是貼錯終端機：在 PowerShell 中執行 CMD 那一行，會看到 The token '&&' is not a valid statement separator；在 CMD 中執行 PowerShell 那一行，會看到 'irm' is not recognized as an internal or external command。兩種情況都改回對應的那一行即可。此外，開始功能表中有「Windows PowerShell」和「Windows PowerShell (x86)」兩個入口，後者是 32 位元程序，會顯示 Claude Code does not support 32-bit Windows，請開啟不帶 (x86) 的那個。

Git for Windows 是可选的：装了以后 Claude Code 用它附带的 Git Bash 执行命令；没装时改用 PowerShell 工具执行。装了却找不到 Git Bash 时，在 ~/.claude/settings.json 的 env 里设置 CLAUDE_CODE_GIT_BASH_PATH，指向 bash.exe，官方示例路径是 C:\Program Files\Git\bin\bash.exe。

如果選擇 WSL，請在 WSL 終端中執行 macOS／Linux 那一行，也在 WSL 中啟動 claude，而不是在 PowerShell 或 CMD 中。

npm 方式的執行策略錯誤

在 PowerShell 中使用 npm 安裝或執行時，如果看到 npm.ps1 cannot be loaded because running scripts is disabled on this system，表示 PowerShell 的執行策略阻止了 npm 產生的 .ps1 啟動腳本。官方提供三種解決方式：允許目前使用者執行本機腳本（如下方這一行）；改用 npm.cmd、claude.cmd；或改用 PowerShell 原生安裝命令。

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

安裝完成後提示找不到 claude

出現 command not found: claude 或 'claude' is not recognized，表示安裝目錄不在 PATH 中。原生安裝會將程式放在 macOS／Linux 的 ~/.local/bin/claude，以及 Windows 的 %USERPROFILE%\.local\bin\claude.exe。先開啟新的終端機再試；Windows 上仍然無法使用時，依照官方疑難排解文件用 PowerShell 檢查並加入使用者 PATH：

# 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. 重新打开终端后确认
claude --version

設定 API key：不登入 Claude 帳戶

ANTHROPIC_BASE_URL 是 Claude Code 內建的環境變數，官方文件對它的描述是：覆寫 API 端點，讓請求經由代理或閘道。因此，將 Claude Code 指向提供 Anthropic Messages API 的端點，是官方支援的設定方式，不需要外掛或修改過的程式。macOS／Linux 請寫入 shell 設定檔：

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # 只写到域名，不要加 /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 視窗中測試：

# 只对当前 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。官方文件說明，ANTHROPIC_AUTH_TOKEN 的值會作為 Authorization 標頭傳送，並自動加上 Bearer 前綴，設定後立即生效；ANTHROPIC_API_KEY 則需要在互動模式中先確認一次，確認時選擇拒絕後，之後此 key 會被靜默忽略（需要在 /config 的 Use custom API key 中重新啟用）。
• ANTHROPIC_MODEL 決定主模型。這裡固定為 Claude Sonnet 5（claude-sonnet-5）。模型名稱必須與 Kunavo 的模型清單完全一致，帶日期後綴的舊名稱不會自動對應。
• ANTHROPIC_DEFAULT_OPUS_MODEL 決定 opus 別名。按 官方模型設定文件（核对于 2026年10月3日），API 用户的默认模型和 opus 别名指向最新的 Opus（目前是 Opus 5.5），sonnet 别名指向 Sonnet 5.5，而且别名会跟着 Anthropic 的新版本移动。官方文档写明别名「会随时间更新」，要固定版本，就写完整模型名或设置 ANTHROPIC_DEFAULT_OPUS_MODEL 这类变量。Kunavo 目前没有提供 Sonnet 5.5，Anthropic 以后发布新 Opus 时 Kunavo 也不一定已经上架，没上架的模型会返回 404。这就是要把主模型、opus 和 sonnet 别名都固定下来的原因。这里 opus 别名固定为 Claude Opus 5.5（claude-opus-5-5），需要 Claude Code v2.1.280 或更高版本，旧版本先运行 claude update 升级。
• ANTHROPIC_DEFAULT_SONNET_MODEL 決定 sonnet 別名。官方文件說明，此變數決定 sonnet 別名指向哪個模型，也決定 opusplan 在計畫模式以外（執行階段）使用哪個模型。sonnet 別名預設請求 Sonnet 5.5，Kunavo 目前未提供，因此未設定此行時，/model sonnet、opusplan 的執行階段和指定 model: sonnet 的子代理都會回傳 404。這裡同樣固定為 Claude Sonnet 5（claude-sonnet-5）。
• ANTHROPIC_DEFAULT_HAIKU_MODEL 也負責背景工作。官方文件說明，此變數決定 haiku 別名，也用於背景功能。Claude Haiku 4.5 在 Kunavo 每百萬 token 的輸入費用為 $0.70、輸出費用為 $3.50；主模型 Claude Sonnet 5 為 $1.40 / $7.00（Anthropic 官方價格 $2.00 / $10.00）；opus 別名的 Claude Opus 5.5 為 $2.80 / $14.00。

key不要寫入專案中的 .claude/settings.json：官方文件提醒，此檔案會被提交，並分享給每個複製儲存庫的人。另外請注意一項優先順序：shell 和 settings 檔案同時設定同一個變數時，以 settings 檔案中的值為準。修改 shell 變數卻未生效時，請先檢查 settings 檔案。

第一次執行會發生什麼

按官方的 閘道連線文件（核对于 2026年10月3日），设置了 ANTHROPIC_AUTH_TOKEN 后运行 claude，会直接进入会话，不顯示登入頁；这个变量立即生效，不像 ANTHROPIC_API_KEY 那样要先确认一次。如果打开后看到的是登录页，说明 Claude Code 没有读到凭据。

憑據必須放在 Claude Code 首次設定前就會讀取的位置：shell 中的 export，或使用者層級 ~/.claude/settings.json 的 env。官方文件說明，在互動模式下，專案中的 .claude/settings.json 或 .claude/settings.local.json 的 env 要等首次設定精靈和資料夾信任提示之後才會生效，因此 key 寫在專案層級設定中時，第一次啟動仍會看到登入頁。

進入工作階段後，執行 /status，在 Status 頁面查看兩行：

• Anthropic base URL：只有設定閘道網址時才會出現，應顯示 https://api.kunavo.com。沒有這一行表示 ANTHROPIC_BASE_URL 沒有傳入此工作階段。
• Auth token：顯示 ANTHROPIC_AUTH_TOKEN 表示正在使用 API key，而不是已儲存的 claude.ai 登入資訊。如果看到的是 Login method 加上一個 claude.ai 帳戶，表示變數未生效。

想在開啟 Claude Code 前單獨測試網址和 key，可以依照官方文件的方法發送一個只需要 1 個輸出 token 的請求（會按 token 扣除極少量餘額）。此命令讀取 shell 中的變數，因此即使你將 key 寫入 settings 檔案，也要先在目前的終端機中執行一次 export。回傳以 {"id":"msg_ 開頭的 JSON，表示網址和 key 都沒有問題；回傳 401，表示 key 未被識別。

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

使用 API key 時有哪些不同

• Remote Control 和語音輸入無法使用。官方文件說明，這兩項功能依賴 claude.ai 身分，設定 ANTHROPIC_AUTH_TOKEN 時無法使用；當 ANTHROPIC_BASE_URL 指向非 Anthropic 網址時，Remote Control 也會被關閉。
• /fast 會顯示 fast 模式已關閉。官方文件說明，只有 bearer token 時，Claude Code 會直接將 fast 模式視為關閉，不發送可用性檢查。
• MCP 工具搜尋預設為關閉。官方文件說明，當 ANTHROPIC_BASE_URL 指向非 Anthropic 網址時，MCP tool search 預設為關閉。
• /context 中的數字是本機估算值。Kunavo 目前不提供 /v1/messages/count_tokens。按 官方閘道相容性文件（核对于 2026年10月3日），网关没有这个端点时，Claude Code 改用按字符估算，/context 显示的是近似值。

完整的整合說明請參閱 Claude Code 整合文件（英文）。

CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 到底關閉了什麼

按 官方環境變數文件（核对于 2026年10月3日），它的作用是关闭 Claude Code 的非必要网络流量，官方列出的内容是：

• 自動更新、遙測、錯誤報告；
• /feedback 命令和 Claude 起草的回饋；
• 發行說明、PR／MR 狀態徽章檢查；
• fast 模式等可用性檢查；
• 功能開關（feature flag）擷取，因此 Remote Control 和其他依賴功能開關的功能將無法使用；
• 外掛 command 來源的背景重新執行（這是本機命令，不是網路流量，因為它可能觸發相依套件安裝）。

還有幾項官方明確說明的細節：設定為 0 或 false 也算開啟，與大多數開關變數不同，只有刪除這個變數才會恢復；官方外掛市場的自動安裝不在其範圍內；它不影響閘道模型探索。官方閘道文件補充，它不影響 WebFetch 工具的網域安全檢查，這項檢查仍會存取 api.anthropic.com；若要關閉，必須另外在設定中加入 skipWebFetchPreflight: true。官方文件沒有將此變數描述為與帳戶風險控制相關的設定。

Kunavo 不要求设置它，它也不影响发往 Kunavo 的模型请求。什么时候值得开启，官方 閘道連線文件（核对于 2026年10月3日）给了一个场景：即使 ANTHROPIC_BASE_URL 指向网关，Claude Code 仍会向 Anthropic 和 GitHub 等第三方发送版本检查、遥测、发布说明之类的后台请求；如果你的网络只允许访问网关地址，这些请求会失败，并可能在出站监控里显示为被拦截的连接，官方的做法就是和网关变量一起设置这个变量。

啟用的代價是不再自動更新，官方建議另行安排更新方式。若使用 npm 安裝，請使用 @latest 手動升級（參閱上方 npmmirror 段落的最後一行）。

# 可选：关闭 Claude Code 的非必要网络流量（会同时关闭自动更新）
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

# 想恢复时删掉这个变量；设成 0 或 false 仍然算开启
unset CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC

使用支付寶或微信支付儲值並取得 key

Anthropic 官方的网页订阅只收信用卡或借记卡（Claude 付費方案帳單常見問題，核对于 2026年10月3日）。在 Kunavo 充值可以用支付宝或微信支付，步骤概要如下，完整步骤见 Claude API 支付寶、微信支付儲值教學：

1. 註冊 Kunavo 帳戶，可以使用電子郵件或 Google 帳戶，註冊不需要綁定卡片。
2. 在 帳務 中選擇儲值金額，最低 $10，沒有月費。儲值金額較高時有加贈：充 $100 到账 $110、充 $1000 到账 $1200、充 $5000 到账 $6250。
3. 在 Stripe 結帳頁面選擇支付寶或微信支付，掃描 QR code 付款。在中國大陸開啟時，金額會以人民幣顯示，以結帳頁面上的數字為準。
4. 前往 /app/keys 建立一組以 sk-kn- 開頭的 key（只顯示一次，請立即儲存），填入上方的 ANTHROPIC_AUTH_TOKEN。

支付寶和微信支付只能手動儲值；自動儲值只能綁定卡片或 Link。Kunavo 不開立中國增值稅發票，儲值記錄可以在 Billing 頁面查看。

大約需要多少費用（示意計算方式）

Claude Code 按 token 計費，每次請求都會重新傳送一次對話內容，其中與上次相同的前綴可以按快取讀取計價。以下只是一組示意性的 token 計算，不是實際帳單，也不是費用上限。所有假設條件如下：

• 每次請求輸入 40,000 個 token，其中 36,000 個（90%）按快取讀取計價，其餘 4,000 個按快取寫入計價；
• 每次請求輸出 1,000 個 token；
• 一段工作時間發出 50 次這類請求；不計入 Claude Haiku 4.5 的背景呼叫；
• Kunavo 價格：快取讀取費用為輸入價格的 10%，快取寫入費用為輸入價格的 1.25 倍（Claude Sonnet 5 的比例；表格中每個模型均按各自的比例計算）。

實際費用取決於內容長度、快取命中率、輸出長度，以及你是否在工作之間使用 /clear 清除對話。Claude Code 訂閱與 API 的選擇、每月大約費用，請參閱 Claude Code 價格；各模型的完整價格請參閱 Claude API 價格和價格頁面；若想依自己的用量估算，可以使用Claude token 成本計算器（英文）。

常見錯誤對照

需要了解的限制

• Kunavo 不開立中國增值稅發票。
• 支付寶和微信支付只能手動儲值；自動儲值只能綁定卡片或 Link。
• 這是按 token 計費的 API，不是 Claude Pro／Max 訂閱；使用 API key 時 Remote Control 和語音輸入無法使用。兩者如何選擇請參閱 Claude Code 價格。
• Kunavo 未在中國大陸進行網路連線測試。claude.ai 的安裝網址、npm 來源、npmmirror 和 api.kunavo.com 在你的網路中是否可存取、速度如何，都需要你自行確認。
• Anthropic 支援的國家和地區名單（核對於 2026年10月3日）中沒有中國大陸、香港和澳門，Claude Code 官方安裝文件將所在地區列為系統需求之一。

常見問題