安裝 Claude Code：Windows 與 macOS 的安裝指令、不需 Pro/Max 方案的 API 金鑰設定，以及使用信用卡或 Link 付款

若想在不購買 Pro／Max 方案的情況下使用 Claude Code，請完成三件事：使用官方原生指令安裝（每種終端機各有一行，就在下方）、設定 ANTHROPIC_BASE_URL=https://api.kunavo.com（不含 /v1）與 ANTHROPIC_AUTH_TOKEN 以及四個模型固定變數，然後輸入 /status 確認 Claude Code 正在使用金鑰。Token 費用會從預付餘額扣除，從 10 USD 使用 Visa／Mastercard 或 Link 儲值；不提供 MoMo、ZaloPay 和 VNPay。若使用 npm 安裝，電腦需要 Node.js 22 或更新版本。

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

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

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

Lệnh cài và tên biến trong bài lấy từ tài liệu chính thức của Claude Code, gồm 安裝頁面 và 環境變數清單, đọc lại ngày 2026年10月3日. Anthropic chưa có bản tiếng Việt của các trang này (đường dẫn /docs/vi/setup báo 404 cùng ngày), nên thông báo lỗi trong bài được giữ nguyên tiếng Anh để bạn tìm cho dễ. Giá và cách thanh toán của Kunavo được kiểm tra ngày 2026年10月3日.

依目前開啟的終端機選擇安裝指令

所有安裝方式都會得到相同的 claude 程式；差別在於由誰負責更新。官方文件將原生方式放在「Native Install (Recommended)」分頁中，而這也是唯一會自動升級到新版本、無需你做任何事的方式。

# Homebrew (macOS, Linux) – mặc định không tự cập nhật
brew install --cask claude-code

# WinGet (Windows) – mặc định không tự cập nhật
winget install Anthropic.ClaudeCode

電腦需要符合以下條件（依據於 2026年10月3日 閱讀的安裝頁面）：

• 作業系統：macOS 13.0 或更新版本；Windows 10 1809 版或更新版本，或 Windows Server 2019 或更新版本；Ubuntu 20.04+、Debian 10+ 或 Alpine Linux 3.19+。
• 至少 4 GB RAM，CPU 為 x64 或 ARM64。不支援 32 位元 Windows。
• Shell 為 Bash、Zsh、PowerShell 或 CMD，並且具備網際網路連線。
• 只有透過 npm 安裝時才需要 Node.js，且必須是 22 或更新版本。

安裝完成後，不要立即在舊視窗中輸入 claude：該視窗尚未取得新的 PATH。請開啟另一個終端機，然後執行：

claude --version   # in ra số phiên bản, kèm chữ (Claude Code)
claude doctor      # chẩn đoán cài đặt và file cấu hình, không mở phiên làm việc

如果 claude --version 印出版本號，表示安裝已完成；之後的錯誤都屬於設定問題。當你不確定錯誤出在哪裡時，claude doctor 很有用，因為它會檢查安裝和 settings 檔案，而不會開啟任何工作階段。

Windows：最常遇到的五個問題

1. 貼錯指令列。 PowerShell 遇到 CMD 的指令列會顯示 The token '&&' is not a valid statement separator；CMD 遇到 PowerShell 的指令列會顯示 'irm' is not recognized as an internal or external command。查看提示字元：若有 PS，請使用 irm 那一列；若沒有，請使用 install.cmd 那一列。
2. 誤開「Windows PowerShell (x86)」。 開始功能表中的這個項目是 32 位元程序，因此即使在 64 位元電腦上也會顯示 Claude Code does not support 32-bit Windows。請選擇不含 (x86) 的項目。
3. 使用 Administrator 權限執行是多餘的。 文件沒有要求此權限，而原生版本會安裝到使用者資料夾：%USERPROFILE%\.local\bin\claude.exe。
4. 輸入 claude 後顯示「not recognized」。 上述資料夾尚未加入 PATH。先嘗試開啟新的終端機；若仍然出錯，請使用下方的 PowerShell 片段檢查並加入路徑。在 macOS／Linux 上，相應的錯誤是 command not found: claude，程式位於 ~/.local/bin/claude。
5. npm 顯示 npm.ps1 cannot be loaded because running scripts is disabled on this system。 PowerShell 的執行原則封鎖了 npm 建立的 .ps1 指令碼。文件提供三種處理方式：使用下方的 Set-ExecutionPolicy 指令允許目前使用者執行本機指令碼、改用 npm.cmd 和 claude.cmd（而非 .ps1 版本），或放棄 npm，改用原生指令。

# 1. Kiểm tra thư mục cài đặt đã có trong PATH chưa
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Không có kết quả nào? Thêm vào PATH của người dùng, rồi đóng và mở lại terminal
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. Trong terminal mới
claude --version

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

原生安裝還是 WSL？ Dự án sống trên Windows thì chạy native là đủ. Lúc đó Git for Windows là tùy chọn: có nó, Claude Code chạy lệnh qua Git Bash; không có, nó dùng PowerShell. Nếu Git đã cài mà Claude Code không thấy Git Bash, khai báo CLAUDE_CODE_GIT_BASH_PATH trong khối env của ~/.claude/settings.json, trỏ tới bash.exe (tài liệu lấy ví dụ C:\Program Files\Git\bin\bash.exe). Chọn WSL 2 khi bạn cần công cụ Linux hoặc muốn lệnh chạy trong sandbox, vì sandbox chỉ có trên WSL 2; Windows native và WSL 1 đều không có. WSL 1 chỉ là phương án khi máy không bật được WSL 2. Đã chọn WSL thì cài bằng dòng install.sh và chạy claude hoàn toàn trong terminal WSL.

透過 npm 安裝：條件與三項注意事項

npm hợp lý khi bạn đã quản lý công cụ dòng lệnh bằng Node, hoặc khi mạng công ty chỉ cho tải gói qua registry npm. Điều kiện là Node.js 22 或更新版本; con số Node 18 trong nhiều bài cũ không còn đúng. Đáng chú ý là Node cũ hơn không làm hỏng việc cài: npm chỉ in cảnh báo EBADENGINE, vì thứ thật sự chạy là một chương trình native mà gói npm tải về, không phụ thuộc Node. Máy chưa có Node thì lấy bản 22+ ở nodejs.org.

node -v                                    # cần v22 trở lên
npm install -g @anthropic-ai/claude-code   # không dùng sudo

# nâng cấp bằng @latest, không dùng npm update -g
npm install -g @anthropic-ai/claude-code@latest

• 不要使用 sudo npm install -g：文件警告此方式會造成權限錯誤並帶來安全風險。
• 使用 npm install -g @anthropic-ai/claude-code@latest 升級；npm update -g 不是文件建議的方式。
• 原生程式來自選用相依套件（與你的平台相對應的 @anthropic-ai/claude-code-* 套件）。--omit=optional 旗標、.npmrc 中的 optional=false 設定，或 --ignore-scripts 都會使其缺失；在 macOS／Linux 上，你會看到 claude native binary not installed。

需要 VPN 嗎？下載安裝指令碼時發生錯誤

Không cần. Việt Nam nằm trong Anthropic 支援的國家清單 cho cả Claude.ai lẫn API (kiểm tra ngày 2026年10月3日). Chính VPN mới hay gây chuyện: theo 安裝故障排除頁面 (đọc ngày 2026年10月3日), khi địa chỉ cài đặt trả về App unavailable in region, Claude Code không khả dụng ở nơi mà kết nối của bạn được nhìn thấy. Ở Việt Nam mà gặp dòng này thì tắt VPN hoặc proxy đặt ở nước khác rồi chạy lại.

剩下的兩個錯誤源自同一個原因：syntax error near unexpected token '<' 或 curl: (22) The requested URL returned error: 403 表示你收到的是 HTML 頁面或錯誤碼，而不是指令碼。公司網路中的 proxy 或防火牆封鎖檔案下載，是首要嫌疑。不要急著改用 Homebrew、WinGet 或 npm：文件建議先檢查網路連線，因為替代安裝方式也會從同一台伺服器下載。請嘗試其他網路，或請 IT 部門解除封鎖。

設定 API 金鑰：執行 Claude Code，不需要 Pro/Max 方案

Claude Code 支援兩種驗證方式。下表提供快速比較；本文其餘內容將沿用右側欄位。

將 Claude Code 指向 Anthropic 以外的其他服務並不是取巧：官方文件說明 ANTHROPIC_BASE_URL 是在透過 proxy 或 gateway 時，用來覆寫 API endpoint 的變數。Kunavo 完整採用 Anthropic Messages API 協定，因此您可以原封不動地使用 Claude Code，不需 plugin，也不需修補程式。需要正好六個變數：

在哪裡設定變數

長期使用時，最簡潔的方式是在使用者 settings 檔案中的 env 區塊，也就是 ~/.claude/settings.json（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"
  }
}

若偏好放在 shell 中，請加入 ~/.zshrc 或 ~/.bashrc。在 Windows 上，以下第二段（$env: 各行）適合快速測試，但關閉 PowerShell 視窗後變數就會消失。

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # chỉ tên miền, không thêm /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

# Chỉ có hiệu lực trong cửa sổ PowerShell này, đóng cửa sổ là mất
$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 中。 Gateway 連線文件 nhắc rằng file này được commit, ai clone repo cũng có.
• Settings 檔案優先於 shell。 同一變數若在兩處都有設定，會使用 settings 檔案 env 區塊中的值。在 shell 中修改後看不到任何變化時，先檢查 settings 檔案。
• 第一次執行需要使用者層級的金鑰。 在互動模式中，專案的 env、.claude/settings.json 或 .claude/settings.local.json 中的區塊，只有在完成第一次精靈流程並回答是否信任資料夾後才會生效。若金鑰只放在這些位置，第一次啟動時仍會顯示登入畫面。

ANTHROPIC_AUTH_TOKEN 或 ANTHROPIC_API_KEY，以及「403 錯誤」問題

Kunavo đọc key ở cả Authorization: Bearer lẫn x-api-key, nên biến nào cũng kết nối được. Khác biệt nằm ở phía Claude Code. Theo 環境變數文件 (đọc ngày 2026年10月3日), ANTHROPIC_AUTH_TOKEN đi vào header Authorization với tiền tố Bearer và có hiệu lực ngay. ANTHROPIC_API_KEY đi vào header X-Api-Key, và ở chế độ tương tác Claude Code hỏi bạn một lần có dùng key này thay cho gói đăng ký không. Trả lời “không” thì key bị bỏ qua mà không hỏi lại; muốn bật lại thì vào /config, mục 使用自訂 API 金鑰. Bài này chọn ANTHROPIC_AUTH_TOKEN chỉ để bỏ được bước hỏi đó.

Vài hướng dẫn tiếng Việt viết rằng ANTHROPIC_API_KEY khiến Claude Code phớt lờ ANTHROPIC_BASE_URL, gọi thẳng api.anthropic.com và nhận 403. Cả tài liệu biến môi trường lẫn gateway 連線文件 (đọc ngày 2026年10月3日) đều không nói vậy: hai biến là hai cách đưa key tới cùng một gateway trong ANTHROPIC_BASE_URL. Nếu bạn thật sự gặp 403 sau khi đổi biến, hãy kiểm tra lại base URL và key thay vì đổi qua đổi lại tên biến.

為什麼要固定模型，以及每個模型的價格

Alias của Claude Code không đứng yên. Theo 模型設定文件 (đọc ngày 2026年10月3日), với người dùng API, mô hình mặc định và alias opus đang trỏ tới Opus 5.5, alias sonnet trỏ tới Sonnet 5.5; tài liệu cũng nói alias “được cập nhật theo thời gian” và khuyên dùng tên đầy đủ hoặc các biến ANTHROPIC_DEFAULT_*_MODEL khi cần cố định. Tính đến ngày 2026年10月3日, Kunavo có Opus 5.5 nhưng không có Sonnet 5.5. Hệ quả nếu bỏ qua bước ghim: phiên mặc định chạy Opus 5.5, đắt hơn Claude Sonnet 5; /model sonnet, giai đoạn thực thi của opusplan và subagent đặt model: sonnet trả về 404; và lần tới alias opus nhảy sang bản Opus mới, bản đó chưa chắc đã có trên Kunavo. Vì vậy đoạn cấu hình ở trên ghim alias sonnet vào claude-sonnet-5 bằng ANTHROPIC_DEFAULT_SONNET_MODEL, và ghim alias opus vào Opus 5.5 (claude-opus-5-5). Opus 5.5 cần Claude Code v2.1.280 trở lên; bản cũ hơn thì chạy claude update.

Kunavo 的價格以每百萬 token 計算（輸入／輸出）：Claude Sonnet 5 1,40 USD / 7,00 USD （Anthropic 價格：2,00 美元／10,00 美元）；Claude Opus 5.5 2,80 USD / 14,00 USD；Claude Haiku 4.5 0,70 USD / 3,50 USD。

使用 /status 檢查

讀取 ANTHROPIC_AUTH_TOKEN 後，執行 claude 會直接進入工作階段，不會出現登入畫面（依據 gateway 連線文件，檢查日期為 2026年10月3日）；第一次仍會有一些設定步驟，例如回答是否信任資料夾。若看到登入畫面，表示金鑰尚未傳到正確位置。在工作階段中輸入 /status 並尋找：

• Anthropic base URL：https://api.kunavo.com。只有在存在 gateway 位址時才會顯示此行；缺少此行表示 ANTHROPIC_BASE_URL 未能進入工作階段。
• Auth token：ANTHROPIC_AUTH_TOKEN。如果此處是 Login method 且搭配 claude.ai 帳戶，表示工作階段仍在使用已儲存的登入。

若要在開啟 Claude Code 前確認金鑰和位址是否正確，請先傳送一個只要求 1 個輸出 token 的 request（會從餘額中扣除極少量費用）。該指令會從目前的 shell 讀取變數，因此若金鑰只存在於 settings 檔案中，請先在此 terminal 執行 export。結果以 {"id":"msg_ 開頭表示正常；401 表示金鑰遭拒。

curl -sS -w '\n%{http_code}\n' -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": "."}]}'

相同測試的 PowerShell 版本；成功時，結果中的 id 欄位會以 msg_ 開頭：

Invoke-RestMethod -Method Post -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `
  -Headers @{ "Authorization" = "Bearer $env:ANTHROPIC_AUTH_TOKEN"; "anthropic-version" = "2023-06-01" } `
  -ContentType "application/json" `
  -Body '{"model": "claude-sonnet-5", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

使用 API 金鑰會失去什麼

• Remote Control 和語音輸入 需要 claude.ai 身分，因此 ANTHROPIC_AUTH_TOKEN 生效時無法執行。當 ANTHROPIC_BASE_URL 指向不同於 api.anthropic.com 的其他伺服器時，Remote Control 也會停用。
• /fast 會顯示 Fast mode has been disabled by your organization：依據 gateway 連線文件，fast mode 檢查需要登入 claude.ai 或使用 Anthropic API 金鑰，因此使用 bearer token 時 Claude Code 會將其視為已停用，也不會詢問伺服器。
• 當 base URL 不是 Anthropic 的 URL 時，MCP tool search 預設會停用。
• /context 中的資料 là ước tính: Kunavo không có endpoint /v1/messages/count_tokens, và theo Gateway 協定文件 (đọc ngày 2026年10月3日), khi thiếu endpoint này Claude Code đếm token dựa trên số ký tự.

整合詳細資訊請參閱Claude Code 整合文件（英文）；相應的英文文章是 Install Claude Code。

從越南加值：支援卡片或 Link，不支援本地電子錢包

先直說：Kunavo 不接受 MoMo、ZaloPay、VNPay 或銀行轉帳。 只支援 Napas 網路的本地 ATM 卡也無法使用，因為它不是 Visa 或 Mastercard。Kunavo 的 Stripe 付款頁面為越南買家提供以下選項：

• Visa 或 Mastercard 卡片，國際信用卡或簽帳金融卡皆可。
• Link, ví của Stripe, lưu phương thức thanh toán để lần sau trả nhanh hơn (Link 文件, đọc ngày 2026年10月3日).
• Apple Pay 或 Google Pay, chỉ xuất hiện trên thiết bị và trình duyệt đã thiết lập ví, vì chúng trả bằng thẻ có trong ví. Apple Pay có mặt ở Việt Nam từ 08/08/2023 và dùng được khi mua hàng trực tuyến (Apple Newsroom 越南, đọc ngày 2026年10月3日).

Phía Anthropic cũng vậy: gói Claude mua trên web chỉ nhận thẻ tín dụng hoặc ghi nợ (Claude 付款常見問題, đọc ngày 2026年10月3日), nên ví điện tử Việt Nam không trả trực tiếp được ở đó; gói mua trong ứng dụng iOS hay Android thì đi theo phương thức của App Store hoặc Google Play. Khác ở chỗ, tiền nạp vào Kunavo thành số dư API, và Claude Code trừ dần theo token sau khi bạn cấu hình key như trên.

以 VND 或 USD 付款

Kunavo niêm yết giá bằng USD. Vì Việt Nam nằm trong các thị trường của Stripe Adaptive Pricing (đọc ngày 2026年10月3日), trang thanh toán có thể hiện số tiền đã quy đổi sang VND, và con số chính xác luôn hiện ra trước khi bạn bấm xác nhận. Tỷ giá Stripe đưa ra đã cộng phí chuyển đổi 2–4%, người mua chịu. Chọn trả bằng USD thì không có khoản đó, nhưng ngân hàng phát hành thẻ có thể áp tỷ giá và phí của họ.

Trả bằng VND cũng chưa chắc rẻ hơn: một số ngân hàng thu phí khi thẻ thanh toán bằng VND cho đơn vị bán hàng đăng ký ở nước ngoài. Chẳng hạn Techcombank thu “phí giao dịch nội tệ ở nước ngoài” 1,1% số tiền giao dịch (đã gồm VAT) với thẻ ghi nợ Visa, áp dụng từ 13/08/2023 (Techcombank 常見問題, đọc ngày 2026年10月3日). Đây chỉ là ví dụ của một ngân hàng, và Kunavo chưa xác minh được ngân hàng có xếp giao dịch của mình vào loại này hay không; xem biểu phí thẻ của bạn rồi hãy chọn VND hay USD.

卡片遭拒通常是因為尚未在銀行應用程式中啟用線上付款或國際付款。啟用後再試，或改用 Link，或使用該錢包支援的卡片搭配 Apple Pay／Google Pay。

從註冊到取得金鑰

1. 使用電子郵件或 Google 帳戶註冊 Kunavo；此步驟不會要求卡片。
2. 開啟 Billing，選擇加值金額（最低 10 USD）。較大金額會額外增加：nạp 100 USD được 110 USD vào số dư; nạp 1.000 USD được 1.200 USD vào số dư; nạp 5.000 USD được 6.250 USD vào số dư。
3. 在 Stripe 頁面選擇卡片、Link 或裝置上可用的錢包，確認金額後送出。
4. 前往 API Keys，建立金鑰 sk-kn-…。金鑰只會顯示一次，因此請立即複製到 ANTHROPIC_AUTH_TOKEN。

若要在餘額偏低時自動加值，必須使用已儲存的卡片或 Link。餘額不會過期，失敗的 request 不會計費。Kunavo 不開立 VAT 發票，包括依越南規定的電子發票；加值紀錄可在 Billing 中查看。此餘額只能用於 Kunavo API，無法支付 Claude Pro、Claude Max 或 ChatGPT Plus。

一次程式編寫工作階段大約要花多少錢？

每次執行時，Claude Code 都會重新傳送完整的對話內容，因此費用很大程度取決於快取：重複的上下文會以明顯較低的快取讀取價格計費。下表是在明確假設下的紙上計算，不是實際測量值，也不是上限：

• 每個 request 有 40.000 個輸入 token：36.000 個 token（90%）從快取讀取，4.000 個 token 寫入快取；
• 每個 request 有 1.000 個輸出 token；
• 一次工作階段有 50 個 request，不計入背景執行的 Claude Haiku 4.5 次；
• 對於 Kunavo 上的 Claude Sonnet 5，快取讀取價格為輸入價格的 10%，快取寫入價格為輸入價格的 1,25 倍；表中的每個模型都使用各自的比例。

最後一欄顯示快取的重要程度。上下文較長、回答較長，或在不同工作之間忘記使用 /clear，都會推高數字。在Claude Code 價格文章中，可以比較訂閱方案與 API 並進行每月估算；各模型價格請查看Claude API 價格表或價格頁面；若要自行輸入資料，請使用Claude token 成本計算工具（英文）。

依錯誤訊息排查

加值前

• 僅支援 Visa／Mastercard 卡片、Link 和以卡片運作的錢包；不支援 MoMo、ZaloPay、VNPay 或銀行轉帳。
• 自動加值僅適用於已儲存的卡片或 Link。Kunavo 不開立 VAT 發票。
• 這是按 token 計費的 API，不是 Claude Pro/Max 方案：沒有 Remote Control 和語音輸入，/fast 會顯示已停用，MCP tool search 預設停用。
• 截至 2026年10月3日，Kunavo 沒有 Sonnet 5.5，因此尚未固定的 alias sonnet 會回傳 404。
• Claude Code 文件和Kunavo 整合文件目前只有英文版。

常見問題