Quay lại hướng dẫn
Cài đặt·3 tháng 10, 2026·Đọc 13 phút

Cài đặt Claude Code: lệnh cài trên Windows và macOS, cấu hình API key không cần gói Pro/Max, thanh toán bằng thẻ hoặc Link

Cài Claude Code chỉ cần một lệnh chính thức. Dễ vướng là các bước sau đó: phiên bản Node.js khi cài bằng npm, terminal và PATH trên Windows, cấu hình API key khi không có gói Pro/Max, và cách thanh toán từ Việt Nam khi không có MoMo, ZaloPay hay VNPay.

Muốn dùng Claude Code mà không mua gói Pro/Max, bạn làm ba việc: cài bằng lệnh native chính thức (mỗi loại terminal một dòng, ngay bên dưới), đặt ANTHROPIC_BASE_URL=https://api.kunavo.com (không có /v1) cùng ANTHROPIC_AUTH_TOKEN và ba biến ghim mô hình, rồi gõ /status để chắc Claude Code đang chạy bằng key. Tiền token trừ vào số dư trả trước, nạp từ 10 USD bằng thẻ Visa/Mastercard hoặc Link; MoMo, ZaloPay và VNPay thì không có. Cài bằng npm thì máy cần Node.js 22 trở lên.

Terminal
# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash
PowerShell
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
cmd.exe
:: 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 trang cài đặt và danh sách biến môi trường, đọc lại ngày 3 tháng 10, 2026. 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 3 tháng 10, 2026.

Chọn lệnh cài theo terminal đang mở

Mọi cách cài đều ra cùng một chương trình claude; khác nhau ở chỗ ai lo việc cập nhật. Tài liệu chính thức đặt cách native ở tab “Native Install (Recommended)”, và đó cũng là cách duy nhất tự lên bản mới mà bạn không phải làm gì.

Bạn đang ởDùng lệnhCập nhật
macOS, Linux, hoặc terminal WSLinstall.sh (dòng đầu tiên ở trên)Tự động, chạy ngầm
Windows PowerShell, dấu nhắc dạng PS C:\Users\TenBan>irm https://claude.ai/install.ps1 | iexTự động, chạy ngầm
Windows CMD, dấu nhắc dạng C:\Users\TenBan> (không có PS)Dòng có install.cmdTự động, chạy ngầm
Đã quen Homebrew hoặc WinGetbrew install --cask claude-code, winget install Anthropic.ClaudeCodeMặc định không tự cập nhật; nâng cấp bằng chính trình quản lý gói
Cần đi qua npmnpm install -g @anthropic-ai/claude-code, cần Node.js 22+Chạy lại với @latest
# 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

Máy cần đáp ứng những điều kiện sau (theo trang cài đặt, đọc ngày 3 tháng 10, 2026):

  • Hệ điều hành: macOS 13.0 trở lên; Windows 10 bản 1809 trở lên hoặc Windows Server 2019 trở lên; Ubuntu 20.04+, Debian 10+ hoặc Alpine Linux 3.19+.
  • Tối thiểu 4 GB RAM, CPU x64 hoặc ARM64. Windows 32-bit không được hỗ trợ.
  • Shell là Bash, Zsh, PowerShell hoặc CMD, và có kết nối Internet.
  • Node.js chỉ cần khi cài qua npm, và phải từ bản 22.

Cài xong, đừng gõ claude ngay trong cửa sổ cũ: cửa sổ đó chưa nhận PATH mới. Mở một terminal khác rồi chạy:

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

Nếu claude --version in ra số phiên bản thì phần cài đặt đã xong, mọi lỗi về sau là chuyện cấu hình. claude doctor hữu ích khi bạn không chắc lỗi nằm ở đâu, vì nó soát cả bản cài lẫn các file settings mà không mở phiên làm việc nào.

Windows: năm chỗ hay vấp

  1. Dán nhầm dòng lệnh. PowerShell gặp dòng của CMD sẽ báo The token '&&' is not a valid statement separator; CMD gặp dòng của PowerShell sẽ báo 'irm' is not recognized as an internal or external command. Nhìn dấu nhắc, có PS thì dùng dòng irm, không có thì dùng dòng install.cmd.
  2. Mở nhầm “Windows PowerShell (x86)”. Mục này trong menu Start là tiến trình 32-bit, nên kể cả trên máy 64-bit vẫn nhận Claude Code does not support 32-bit Windows. Chọn mục không có chữ (x86).
  3. Chạy bằng quyền Administrator là thừa. Tài liệu không yêu cầu, và bản native cài vào thư mục của người dùng: %USERPROFILE%\.local\bin\claude.exe.
  4. Gõ claude báo “not recognized”. Thư mục trên chưa vào PATH. Thử terminal mới trước; vẫn lỗi thì dùng đoạn PowerShell bên dưới để kiểm tra và thêm đường dẫn. Trên macOS/Linux, lỗi tương đương là command not found: claude, và chương trình nằm ở ~/.local/bin/claude.
  5. npm báo npm.ps1 cannot be loaded because running scripts is disabled on this system. Execution policy của PowerShell đang chặn script .ps1 mà npm tạo ra. Tài liệu đưa ba lối ra: cho người dùng hiện tại chạy script cục bộ bằng lệnh Set-ExecutionPolicy bên dưới, gọi npm.cmd và claude.cmd thay cho bản .ps1, hoặc bỏ npm và dùng lệnh native.
PowerShell
# 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
PowerShell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Native hay 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.

Cài qua npm: điều kiện và ba lưu ý

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 trở lên; 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.

Terminal
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
  • Không dùng sudo npm install -g: tài liệu cảnh báo cách này gây lỗi phân quyền và là rủi ro bảo mật.
  • Lên bản mới bằng npm install -g @anthropic-ai/claude-code@latest; npm update -g không phải cách được hướng dẫn.
  • Chương trình native đến từ một dependency tùy chọn (gói @anthropic-ai/claude-code-* ứng với nền tảng của bạn). Cờ --omit=optional, dòng optional=false trong .npmrc hoặc --ignore-scripts sẽ làm thiếu nó, và trên macOS/Linux bạn nhận claude native binary not installed.

Có cần VPN không? Lỗi khi tải script cài

Không cần. Việt Nam nằm trong danh sách quốc gia Anthropic hỗ trợ cho cả Claude.ai lẫn API (kiểm tra ngày 3 tháng 10, 2026). Chính VPN mới hay gây chuyện: theo trang xử lý lỗi cài đặt (đọc ngày 3 tháng 10, 2026), 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.

Hai lỗi còn lại cùng một gốc: syntax error near unexpected token '<' hoặc curl: (22) The requested URL returned error: 403 nghĩa là thay vì script, bạn nhận về một trang HTML hoặc mã lỗi. Mạng công ty với proxy hay tường lửa chặn tải file là nghi phạm đầu tiên. Đừng vội đổi sang Homebrew, WinGet hay npm: tài liệu khuyên kiểm tra kết nối mạng trước, vì các cách cài thay thế cũng tải từ cùng máy chủ. Thử một mạng khác hoặc nhờ bộ phận IT mở chặn.

Cấu hình API key: chạy Claude Code không cần gói Pro/Max

Claude Code xác thực theo một trong hai cách. Bảng dưới so sánh nhanh; phần còn lại của bài đi theo cột bên phải.

Đăng nhập tài khoản ClaudeAPI key của Kunavo
Điều kiệnGói Pro, Max, Team, Enterprise hoặc tài khoản Console. Gói Claude.ai miễn phí không có Claude Code.Một key sk-kn-… đặt trong biến môi trường. Không mua gói, không đăng nhập.
Tính tiềnTheo tháng: Pro 20 USD/tháng (17 USD/tháng nếu trả năm, tức 200 USD một lần), Max từ 100 USD/tháng, chưa gồm thuế (claude.com/pricing, đọc ngày 3 tháng 10, 2026).Theo token thực dùng, trừ vào số dư nạp trước từ 10 USD. Không phí tháng, số dư không hết hạn, request lỗi không bị trừ tiền.
Trả bằngMua trên web của Anthropic thì chỉ thẻ tín dụng hoặc ghi nợ (FAQ thanh toán của Claude, đọc ngày 3 tháng 10, 2026).Thẻ Visa, Mastercard, Link; Apple Pay hoặc Google Pay nếu thiết bị có. Không có MoMo, ZaloPay, VNPay.
Thiếu gì—Remote Control và nhập liệu bằng giọng nói. Không có hóa đơn VAT.

Trỏ Claude Code sang một dịch vụ khác Anthropic không phải mẹo: tài liệu chính thức mô tả ANTHROPIC_BASE_URL là biến dùng để ghi đè endpoint API khi đi qua proxy hoặc gateway. Kunavo dùng đúng giao thức Anthropic Messages API, nên bạn dùng nguyên bản Claude Code, không plugin, không bản vá. Cần đúng năm biến:

BiếnGiá trịĐể làm gì, sai ở đâu
ANTHROPIC_BASE_URLhttps://api.kunavo.comChỉ tên miền. Claude Code tự nối /v1/messages; ghi thêm /v1 thì request thành /v1/v1/messages và nhận 404.
ANTHROPIC_AUTH_TOKENKey sk-kn-…Gửi trong header Authorization: Bearer, có hiệu lực ngay, không qua bước xác nhận.
ANTHROPIC_MODELclaude-sonnet-5Mô hình chính (Claude Sonnet 5). Tên phải khớp từng ký tự với danh sách của Kunavo; tên kiểu cũ có hậu tố ngày tháng không được tự quy đổi.
ANTHROPIC_DEFAULT_OPUS_MODELclaude-opus-5Ghim alias opus vào Claude Opus 5, để nó không trôi theo bản Opus mới nhất.
ANTHROPIC_DEFAULT_HAIKU_MODELclaude-haiku-4-5Alias haiku và các tác vụ chạy nền của Claude Code đều dùng mô hình này.

Đặt biến ở đâu

Cách gọn nhất để dùng lâu dài là khối env trong file settings của người dùng, ~/.claude/settings.json (Windows: %USERPROFILE%\.claude\settings.json). File này áp dụng cho mọi dự án; nếu nó đã có nội dung, chỉ thêm khối env:

~/.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",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

Thích để trong shell thì thêm vào ~/.zshrc hoặc ~/.bashrc. Trên Windows, đoạn thứ hai bên dưới (các dòng $env:) hợp để thử nhanh, nhưng biến sẽ mất ngay khi đóng cửa sổ PowerShell.

~/.zshrc
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
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5
PowerShell
# 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"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "claude-haiku-4-5"
claude

Ba điều nên biết trước khi gặp rắc rối:

  • Không đặt key trong .claude/settings.json của dự án. Tài liệu kết nối gateway nhắc rằng file này được commit, ai clone repo cũng có.
  • File settings thắng shell. Một biến có ở cả hai nơi thì giá trị trong khối env của file settings được dùng. Sửa trong shell mà không thấy đổi gì thì xem file settings trước.
  • Lần chạy đầu cần key ở cấp người dùng. Ở chế độ tương tác, khối env trong .claude/settings.json hay .claude/settings.local.json của dự án chỉ có tác dụng sau trình hướng dẫn lần đầu và câu hỏi có tin tưởng thư mục hay không. Key chỉ nằm ở đó thì lần khởi động đầu vẫn hiện màn hình đăng nhập.

ANTHROPIC_AUTH_TOKEN hay ANTHROPIC_API_KEY, và chuyện “lỗi 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 tài liệu biến môi trường (đọc ngày 3 tháng 10, 2026), 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 Use custom API key. 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 tài liệu kết nối gateway (đọc ngày 3 tháng 10, 2026) đề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.

Vì sao ghim mô hình, và mỗi mô hình giá bao nhiêu

Alias của Claude Code không đứng yên. Theo tài liệu cấu hình mô hình (đọc ngày 3 tháng 10, 2026), 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 3 tháng 10, 2026, 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 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. Hay đổi mô hình bằng /model sonnet thì thêm dòng ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5.

Giá trên Kunavo, tính theo mỗi triệu token (đầu vào / đầu ra): Claude Sonnet 5 1,40 USD / 7,00 USD (bảng giá của Anthropic: 2,00 USD / 10,00 USD); Claude Opus 5 3,50 USD / 17,50 USD; Claude Haiku 4.5 0,70 USD / 3,50 USD.

Kiểm tra bằng /status

Khi ANTHROPIC_AUTH_TOKEN đã được đọc, lệnh claude vào thẳng phiên làm việc, không có màn hình đăng nhập (theo tài liệu kết nối gateway, đọc ngày 3 tháng 10, 2026); lần đầu vẫn có vài bước thiết lập như câu hỏi tin tưởng thư mục. Thấy màn hình đăng nhập tức là key chưa tới nơi. Trong phiên, gõ /status và tìm:

  • Anthropic base URL: https://api.kunavo.com. Dòng này chỉ xuất hiện khi có địa chỉ gateway; vắng mặt nghĩa là ANTHROPIC_BASE_URL không vào được phiên.
  • Auth token: ANTHROPIC_AUTH_TOKEN. Nếu chỗ đó là Login method kèm một tài khoản claude.ai, phiên vẫn đang dùng lần đăng nhập đã lưu.

Muốn chắc key và địa chỉ đúng trước khi mở Claude Code, gửi thử một request xin đúng 1 token đầu ra (tốn một khoản rất nhỏ trong số dư). Lệnh đọc biến từ shell hiện tại, nên nếu key chỉ nằm trong file settings thì export trong terminal này trước. Kết quả bắt đầu bằng {"id":"msg_ là ổn; 401 là key bị từ chối.

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

Bản PowerShell của cùng phép thử; thành công thì trường id trong kết quả bắt đầu bằng msg_:

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

Chạy bằng API key thì mất gì

  • Remote Control và nhập liệu bằng giọng nói cần danh tính claude.ai, nên không chạy khi ANTHROPIC_AUTH_TOKEN có hiệu lực. Remote Control cũng tắt khi ANTHROPIC_BASE_URL trỏ tới máy chủ khác api.anthropic.com.
  • /fast báo Fast mode has been disabled by your organization: theo tài liệu kết nối gateway, bước kiểm tra fast mode cần đăng nhập claude.ai hoặc API key của Anthropic, nên với bearer token Claude Code coi như đã tắt và không hỏi máy chủ.
  • MCP tool search mặc định tắt khi base URL không phải của Anthropic.
  • Số liệu trong /context là ước tính: Kunavo không có endpoint /v1/messages/count_tokens, và theo tài liệu giao thức gateway (đọc ngày 3 tháng 10, 2026), khi thiếu endpoint này Claude Code đếm token dựa trên số ký tự.

Chi tiết tích hợp nằm trong tài liệu tích hợp Claude Code (tiếng Anh); bài tương ứng bằng tiếng Anh là Install Claude Code.

Nạp tiền từ Việt Nam: thẻ hoặc Link, không có ví điện tử nội địa

Nói thẳng trước: Kunavo không nhận MoMo, ZaloPay, VNPay hay chuyển khoản ngân hàng. Thẻ ATM nội địa chỉ chạy mạng Napas cũng không dùng được, vì nó không phải thẻ Visa hay Mastercard. Trang thanh toán Stripe của Kunavo có những lựa chọn sau cho người mua ở Việt Nam:

  • Thẻ Visa hoặc Mastercard, tín dụng hay ghi nợ quốc tế đều được.
  • Link, ví của Stripe, lưu phương thức thanh toán để lần sau trả nhanh hơn (tài liệu Link, đọc ngày 3 tháng 10, 2026).
  • Apple Pay hoặc 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 Việt Nam, đọc ngày 3 tháng 10, 2026).

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ợ (FAQ thanh toán của Claude, đọc ngày 3 tháng 10, 2026), 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.

Trả bằng VND hay 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 3 tháng 10, 2026), 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 (FAQ của Techcombank, đọc ngày 3 tháng 10, 2026). Đâ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.

Thẻ bị từ chối thường là do chưa bật thanh toán trực tuyến hoặc thanh toán quốc tế trong ứng dụng ngân hàng. Bật lên rồi thử lại, hoặc đổi sang Link, hay Apple Pay/Google Pay với một thẻ mà ví đó hỗ trợ.

Từ đăng ký đến có key

  1. Đăng ký Kunavo bằng email hoặc tài khoản Google; bước này không hỏi thẻ.
  2. Mở Billing, chọn mức nạp (thấp nhất 10 USD). Các mức lớn có cộng thêm: 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. Ở trang Stripe, chọn thẻ, Link hoặc ví có sẵn trên máy, xem lại số tiền và xác nhận.
  4. Vào API Keys, tạo key sk-kn-…. Key chỉ hiện một lần, nên chép ngay vào ANTHROPIC_AUTH_TOKEN.

Muốn tự động nạp khi số dư xuống thấp thì phải dùng thẻ đã lưu hoặc Link. Số dư không có hạn dùng, request lỗi không bị tính tiền. Kunavo không xuất hóa đơn VAT, kể cả hóa đơn điện tử theo quy định của Việt Nam; lịch sử nạp tiền xem trong Billing. Số dư này chỉ dùng cho API của Kunavo, không trả được Claude Pro, Claude Max hay ChatGPT Plus.

Một buổi code tốn khoảng bao nhiêu?

Mỗi lượt, Claude Code gửi lại cả ngữ cảnh hội thoại, nên chi phí phụ thuộc nhiều vào cache: phần ngữ cảnh lặp lại được tính theo giá đọc cache rẻ hơn hẳn. Bảng sau là phép tính trên giấy với giả định nêu rõ, không phải số đo thực tế và không phải mức trần:

  • mỗi request 40.000 token đầu vào: 36.000 token (90%) đọc từ cache, 4.000 token ghi cache;
  • mỗi request 1.000 token đầu ra;
  • một buổi 50 request, chưa tính các lượt Claude Haiku 4.5 chạy nền;
  • với Claude Sonnet 5 trên Kunavo, đọc cache bằng 10% giá đầu vào và ghi cache bằng 1,25 lần giá đầu vào; mỗi mô hình trong bảng dùng tỷ lệ riêng của nó.
Mô hìnhMột request50 request50 request, không trúng cache lần nào
Claude Sonnet 50,019 USD0,95 USD3,15 USD
Claude Opus 50,048 USD2,38 USD7,88 USD

Cột cuối cho thấy cache quan trọng đến đâu. Ngữ cảnh dài, câu trả lời dài hay quên /clear giữa hai việc khác nhau đều đẩy con số lên. So gói đăng ký với API và ước lượng theo tháng có ở bài Claude Code giá bao nhiêu; giá từng mô hình xem bảng giá Claude API hoặc trang giá; tự nhập số liệu của mình thì dùng công cụ tính chi phí token Claude (tiếng Anh).

Tra lỗi theo thông báo

Lúc nàoThấy gìXử lý
Cài đặtThe token '&&' is not a valid statement separatorĐang ở PowerShell mà dán dòng CMD. Dùng irm … | iex.
Cài đặt'irm' is not recognized as an internal or external commandĐang ở CMD mà dán dòng PowerShell. Dùng dòng install.cmd.
Cài đặtsyntax error near unexpected token '<', 403, App unavailable in regionNhận về trang HTML thay vì script. Tắt VPN/proxy ở nước khác, thử mạng khác trước khi đổi cách cài (các cách khác tải từ cùng máy chủ).
Cài đặtClaude Code does not support 32-bit WindowsĐang mở PowerShell (x86). Mở “Windows PowerShell” thường.
Cài đặt (npm)Cảnh báo EBADENGINENode.js dưới 22. Cài vẫn xong, nhưng nên nâng Node.
Cài đặt (npm)claude native binary not installedThiếu dependency tùy chọn do --omit=optional, optional=false hoặc --ignore-scripts. Bỏ thiết lập đó, cài lại.
Cài đặt (npm)npm.ps1 cannot be loadedExecution policy chặn script. Chạy Set-ExecutionPolicy ở trên, dùng npm.cmd, hoặc chuyển sang lệnh native.
Sau khi càicommand not found: claude, 'claude' is not recognizedThư mục cài chưa có trong PATH. Mở terminal mới; Windows thì chạy đoạn PowerShell thêm PATH.
Cấu hìnhVẫn hiện màn hình đăng nhậpKey chưa được đọc. Đặt ở shell hoặc ~/.claude/settings.json của người dùng, không chỉ ở cấu hình dự án; mở terminal mới.
Cấu hình401Key bị từ chối: chép thiếu, thừa dấu cách, đã xóa trong /app/keys, hoặc nằm nhầm biến.
Cấu hình404Base URL thừa /v1, hoặc mô hình không có trên Kunavo (thường là alias sonnet chưa ghim, đang trỏ tới Sonnet 5.5).
Nạp tiềnThẻ bị từ chốiBật thanh toán trực tuyến và quốc tế trong ứng dụng ngân hàng; thẻ chỉ có Napas không dùng được. Hoặc thử Link, Apple Pay, Google Pay.

Trước khi nạp tiền

  • Chỉ có thẻ Visa/Mastercard, Link và ví chạy trên thẻ; không MoMo, ZaloPay, VNPay hay chuyển khoản.
  • Tự động nạp chỉ hoạt động với thẻ đã lưu hoặc Link. Kunavo không xuất hóa đơn VAT.
  • Đây là API trả theo token chứ không phải gói Claude Pro/Max: không có Remote Control và nhập liệu bằng giọng nói, /fast báo đã tắt, MCP tool search mặc định tắt.
  • Tính đến ngày 3 tháng 10, 2026, Kunavo không có Sonnet 5.5, nên alias sonnet chưa ghim sẽ trả 404.
  • Tài liệu của Claude Code và tài liệu tích hợp của Kunavo hiện chỉ có tiếng Anh.

Câu hỏi thường gặp

Claude Code có miễn phí không? “Claude Code không cần gói” nghĩa là gì?

Tải và cài Claude Code thì không mất tiền, nhưng để nó trả lời được thì cần một trong hai: đăng nhập bằng gói Claude trả phí (Pro, Max, Team, Enterprise) hoặc tài khoản Console, hoặc dùng một API key. Gói Claude.ai miễn phí không kèm Claude Code. “Không cần gói” là cách thứ hai: đặt ANTHROPIC_BASE_URL=https://api.kunavo.com và ANTHROPIC_AUTH_TOKEN, Claude Code bỏ qua bước đăng nhập và trừ tiền theo token thực dùng từ số dư Kunavo nạp trước, tối thiểu 10 USD, không có phí hằng tháng.

Lệnh cài Claude Code trên Windows là gì? Có phải cài WSL hay chạy bằng quyền Administrator không?

Mở PowerShell (dấu nhắc có chữ PS ở đầu) và chạy irm https://claude.ai/install.ps1 | iex; nếu đang ở CMD thì dùng curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd. Không cần quyền Administrator, không bắt buộc WSL hay Git. Có Git for Windows thì Claude Code chạy lệnh qua Git Bash, không có thì qua PowerShell. WSL 2 chỉ đáng cài khi bạn cần công cụ Linux hoặc muốn lệnh chạy trong sandbox. Nhớ mở “Windows PowerShell”, không phải mục có chữ (x86), vì Claude Code không chạy trên Windows 32-bit.

Cài Claude Code bằng npm cần Node.js bản nào?

Node.js 22 trở lên, theo tài liệu cài đặt chính thức đọc ngày 3 tháng 10, 2026. Nhiều bài cũ vẫn ghi Node 18, con số đó đã lỗi thời. Node cũ hơn chỉ khiến npm in cảnh báo EBADENGINE, cài vẫn xong, vì gói npm thực chất tải về một chương trình native chạy không cần Node. Lệnh cài là npm install -g @anthropic-ai/claude-code (không kèm sudo); muốn lên bản mới thì chạy lại với @latest chứ không dùng npm update -g. Nếu không có lý do riêng để dùng npm, lệnh native vẫn gọn hơn.

Nhập API key cho Claude Code ở đâu? ANTHROPIC_BASE_URL có thêm /v1 không?

Chỗ bền nhất là khối env trong file ~/.claude/settings.json của người dùng (Windows: %USERPROFILE%\.claude\settings.json), áp dụng cho mọi dự án; cũng có thể export trong ~/.zshrc, ~/.bashrc hoặc $PROFILE của PowerShell. Base URL chỉ là https://api.kunavo.com, không có /v1, vì Claude Code tự thêm /v1/messages; thừa /v1 sẽ thành /v1/v1/messages và bị 404. Đừng để key trong .claude/settings.json của dự án: file đó nằm trong repo và đi theo mỗi lần clone.

Có bài viết nói dùng ANTHROPIC_API_KEY sẽ bị 403. Có đúng không?

Không đúng với tài liệu chính thức. Cả ANTHROPIC_API_KEY lẫn ANTHROPIC_AUTH_TOKEN đều được gửi tới địa chỉ trong ANTHROPIC_BASE_URL; khác nhau ở header (X-Api-Key so với Authorization: Bearer) và ở chỗ ANTHROPIC_API_KEY phải được bạn đồng ý một lần trong chế độ tương tác. Kunavo đọc key ở cả hai header. Bài này khuyên ANTHROPIC_AUTH_TOKEN chỉ vì nó dùng được ngay. Lỡ bấm từ chối ở lời hỏi đó thì key bị bỏ qua mà không hỏi lại; vào /config, mục Use custom API key để bật lại.

Không đặt ANTHROPIC_MODEL thì Claude Code chạy mô hình nào?

Chạy theo alias, mà alias đổi dần theo thời gian. Tài liệu cấu hình mô hình (đọc ngày 3 tháng 10, 2026) ghi rằng với người dùng API, mặc định và alias opus đang là Opus 5.5, alias sonnet là Sonnet 5.5. Kunavo có Opus 5.5 nhưng không có Sonnet 5.5, nên phiên không ghim sẽ chạy Opus 5.5 với giá cao hơn Claude Sonnet 5, còn /model sonnet trả về 404. Ghim ANTHROPIC_MODEL=claude-sonnet-5, ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5 và ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5 thì bạn biết chắc mỗi lượt đang tính tiền theo mô hình nào.

Gõ /status thấy gì thì nghĩa là đã chạy bằng API key?

Hai dòng: “Anthropic base URL” là https://api.kunavo.com, và “Auth token” ghi ANTHROPIC_AUTH_TOKEN. Nếu thay vào đó là “Login method” với một tài khoản claude.ai thì phiên vẫn đang dùng lần đăng nhập cũ; thoát ra, mở terminal mới và xem lại biến đã được đặt ở đâu. Có thể thử key trước cả khi mở Claude Code bằng một lệnh curl gửi tới /v1/messages với max_tokens là 1: trả về JSON bắt đầu bằng {"id":"msg_ là ổn, 401 là key bị từ chối.

Ở Việt Nam có cần VPN để cài hay dùng Claude Code không?

Không cần. Việt Nam có trong danh sách quốc gia Anthropic hỗ trợ cho cả Claude.ai lẫn API (kiểm tra ngày 3 tháng 10, 2026). Ngược lại, nếu VPN đưa kết nối ra một nước không được hỗ trợ, địa chỉ cài đặt có thể trả về trang “App unavailable in region” thay cho script. Gặp lỗi đó khi đang ở Việt Nam thì tắt VPN hoặc proxy rồi chạy lại lệnh cài.

Nạp tiền bằng MoMo, ZaloPay hay VNPay được không? Có xuất hóa đơn VAT không?

Không có cả hai. Trang thanh toán Stripe của Kunavo cho người mua ở Việt Nam chọn thẻ Visa, Mastercard hoặc Link, và Apple Pay hay Google Pay nếu thiết bị đã cài sẵn; MoMo, ZaloPay, VNPay và chuyển khoản ngân hàng không có. Số tiền có thể hiện bằng VND, khi đó tỷ giá của Stripe đã gồm phí chuyển đổi 2–4% người mua chịu; chọn trả bằng USD thì không có phí đó nhưng ngân hàng của bạn có thể tính tỷ giá và phí riêng. Nạp tối thiểu 10 USD, số dư không hết hạn, tự động nạp chỉ chạy với thẻ đã lưu hoặc Link. Kunavo không xuất hóa đơn VAT, kể cả hóa đơn điện tử.