Để cài đặt Claude Code, chỉ cần chạy một dòng của trình cài đặt native chính thức. Mac/Linux/WSL dùng install.sh, Windows dùng install.ps1 trong PowerShell hoặc install.cmd trong CMD (cũng có thể cài bằng npm, nhưng khi đó cần Node.js 22 trở lên). Thông thường sau đó bạn đăng nhập bằng gói Pro, Max, v.v.; nếu không đăng ký gói, hãy đặt ANTHROPIC_BASE_URL=https://api.kunavo.com (không thêm /v1), ANTHROPIC_AUTH_TOKEN chứa khóa API và bốn biến cố định model để khởi động mà không cần đăng nhập. Kiểm tra trạng thái bằng /status. Có thể nạp trước số dư API với số tiền từ $10 trở lên bằng thẻ như JCB, Apple Pay, Google Pay hoặc Link; trang thanh toán hiển thị số tiền bằng yên.
# 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.cmdNguồn chính thức về hướng dẫn cài đặt là tài liệu chính thức bằng tiếng Nhật của Anthropic (Thiết lập, Khắc phục sự cố cài đặt, xác minh 3 tháng 10, 2026). Trang này không chỉ nhắc lại nội dung đó, mà tập trung vào những điểm các bài giải thích bằng tiếng Nhật đưa tin không nhất quán (phiên bản Node.js, quyền quản trị viên trên Windows và Git), cùng những nội dung tài liệu chính thức chưa đề cập — cấu hình để chạy bằng khóa API mà không cần đăng nhập và thanh toán từ Nhật Bản. Thông tin về giá và phương thức thanh toán được cập nhật đến 10 tháng 10, 2026. Nhật Bản có trong danh sách quốc gia được hỗ trợ của Anthropic cho cả Claude.ai và API (xác minh 3 tháng 10, 2026).
Điều cần quyết định trước: đăng nhập bằng gói đăng ký hay chạy bằng khóa API
Bản thân việc cài đặt giống nhau trong cả hai trường hợp; điểm khác biệt nằm sau lần khởi động đầu tiên. Khi khởi động, Claude Code yêu cầu xác thực. Nếu chưa chắc, bạn có thể quyết định dựa trên 3 điểm sau.
- Đã đăng ký Pro, Max, Team, Enterprise hoặc có tài khoản Console: chỉ cần đăng nhập là có thể sử dụng. Bạn không cần cấu hình khóa API trên trang này. Gói miễn phí không bao gồm Claude Code.
- Không muốn trả một khoản cố định hàng tháng, hoặc mức sử dụng chênh lệch nhiều giữa các tháng: dùng khóa API và chỉ trả tiền theo số token đã dùng sẽ phù hợp hơn. Để tham khảo, thuê bao Claude có giá $20 mỗi tháng cho Pro (trả theo năm là $200, tương đương $17 mỗi tháng) và từ $100 mỗi tháng cho Max; cả hai đều chưa tính thuế (Trang giá Claude, xác minh 3 tháng 10, 2026). Chi phí Claude Code có tính toán điểm mà từ đó phương án này bắt đầu rẻ hơn.
- Muốn sử dụng Remote Control hoặc tính năng nhập bằng giọng nói: cả hai đều yêu cầu tài khoản claude.ai nên không thể dùng bằng khóa API. Hãy chọn đăng nhập.
Phương thức thanh toán cũng khác nhau. Thuê bao đăng ký trên trang web Anthropic chỉ chấp nhận thẻ tín dụng hoặc thẻ ghi nợ; nếu đăng ký từ ứng dụng iPhone hoặc Android, App Store hoặc Google Play sẽ xử lý thanh toán (trợ giúp Anthropic, bản tiếng Anh, xác minh 3 tháng 10, 2026). Bạn có thể nạp số dư API Kunavo bằng thẻ, bao gồm JCB, Apple Pay, Google Pay hoặc Link (xem chương thanh toán ở phần sau).
Kiểm tra trước khi cài đặt
Các yêu cầu đúng như trong tài liệu chính thức (xác nhận ngày 3 tháng 10, 2026). Cột bên phải cho biết cách kiểm tra trên thiết bị của bạn.
| Hạng mục | Yêu cầu | Cách kiểm tra |
|---|---|---|
| Hệ điều hành | macOS 13.0 trở lên / Windows 10 1809 trở lên, Windows Server 2019 trở lên / Ubuntu 20.04 trở lên, Debian 10 trở lên, Alpine Linux 3.19 trở lên | Trên Mac, chọn “Giới thiệu về máy Mac này” trong menu Apple; trên Windows, dùng winver |
| CPU/Bộ nhớ | x64 hoặc ARM64, RAM 4 GB trở lên | Không hỗ trợ Windows/PowerShell 32 bit |
| Shell | Bash, Zsh, PowerShell, CMD | Trên Windows, nếu đầu dòng nhắc lệnh có PS thì đó là PowerShell |
| Node.js | Chỉ cần từ 22 trở lên khi cài bằng npm. Không cần đối với trình cài đặt native | node -v |
| Quốc gia sử dụng | Các quốc gia được Anthropic hỗ trợ (Nhật Bản được hỗ trợ) | Có đang sử dụng VPN qua nước ngoài không |
Cài bằng phương pháp nào
Tài liệu chính thức đánh dấu trình cài đặt native là “được khuyến nghị”. Khác biệt chính so với các phương pháp khác là cách cập nhật.
| Phương pháp | Cập nhật | Điều kiện tiên quyết |
|---|---|---|
| Trình cài đặt native (được khuyến nghị) | Tự động cập nhật ở chế độ nền | Không có (lệnh nằm ở đầu trang) |
| Homebrew/WinGet (Windows) | Theo mặc định không tự động cập nhật. Tự cập nhật bằng trình quản lý gói hoặc bật bằng CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 | Từng trình quản lý gói |
| npm | Cài đặt lại với @latest | Node.js 22 trở lên |
# Homebrew(既定では自動更新されない)
brew install --cask claude-code
# WinGet(Windows・既定では自動更新されない)
winget install Anthropic.ClaudeCodeDù dùng phương pháp nào, sau khi hoàn tất, hãy mở lại terminal rồi mới kiểm tra. Các cửa sổ đã mở trước khi cài đặt có thể chưa tải PATH mới. claude doctor chỉ hiển thị trạng thái cài đặt và cấu hình mà không bắt đầu phiên, nên hữu ích để khoanh vùng khi có sự cố.
claude --version # 2.1.211 (Claude Code) のようなバージョン番号が出れば OK
claude doctor # セッションを開かずに、インストールと設定を診断するLưu ý khi cài bằng npm
Các bài giải thích bằng tiếng Nhật thường vẫn ghi “Node.js 18 trở lên”, nhưng yêu cầu trong tài liệu chính thức là Node.js 22 trở lên (tài liệu chính thức, xác minh 3 tháng 10, 2026). Với Node.js cũ, npm chỉ đưa ra cảnh báo EBADENGINE mà không dừng cài đặt, và claude vẫn khởi chạy; tuy vậy, nếu thấy cảnh báo, an toàn hơn là nâng cấp Node.js. Nếu bạn chuyển đổi phiên bản bằng nvm, Volta hoặc công cụ tương tự, hãy kiểm tra node -v trong shell dùng để cài đặt.
node -v # v22 以上であること
npm install -g @anthropic-ai/claude-code # sudo は付けない
# 更新は @latest で(npm update -g は使わない)
npm install -g @anthropic-ai/claude-code@latestTài liệu chính thức nêu rõ không sử dụng sudo npm install -g. Ngoài ra, binary chính được cài dưới dạng dependency tùy chọn; nếu --omit=optional hoặc .npmrc dùng optional=false để bỏ qua dependency tùy chọn, trên Mac/Linux sẽ hiển thị claude native binary not installed và không khởi động được.
Điểm cần lưu ý khi cài trên Windows
Trước tiên, bạn không cần làm theo hai hướng dẫn thường thấy trên mạng. “Chạy PowerShell với tư cách quản trị viên” và “cài Git for Windows trước” đều không phải yêu cầu trong tài liệu chính thức. Không cần quyền quản trị viên; Git for Windows là tùy chọn, và nếu chưa cài, Claude Code sẽ chạy lệnh bằng PowerShell (Thiết lập trên Windows, xác minh 3 tháng 10, 2026).
Sau đó, trước khi dán lệnh, hãy kiểm tra đúng 2 điều.
- Hiện bạn đang mở PowerShell hay CMD? Nếu dấu nhắc là
PS C:\Users\ユーザー名>thì dùng dòngirmdành cho PowerShell; nếu làC:\Users\ユーザー名>không cóPSthì dùng dònginstall.cmddành cho CMD. Nếu nhầm, PowerShell sẽ báo lỗi không nhận diện&&là dấu phân cách, còn CMD sẽ báo lỗi không nhận diệnirm(trên Windows hiển thị tiếng Nhật, thông báo có thể xuất hiện bằng tiếng Nhật). - Bạn có đang mở “Windows PowerShell (x86)” không? Phiên bản (x86) trong menu Start là tiến trình 32 bit, nên ngay cả trên máy tính 64 bit cũng sẽ dừng với
Claude Code does not support 32-bit Windows.
Có 3 cách chạy trên Windows. Nếu chưa chắc, bạn có thể bắt đầu bằng Windows native.
| Môi trường chạy | Sandbox | Phù hợp với |
|---|---|---|
| Windows native (PowerShell/CMD) | Không hỗ trợ | Mã và công cụ đều nằm ở phía Windows. Không cần cài thêm gì |
| WSL 2 | Được hỗ trợ | Muốn dùng công cụ Linux hoặc chạy lệnh trong môi trường cô lập. Chạy dòng dành cho Mac/Linux trong terminal WSL và cũng khởi động claude tại đó |
| WSL 1 | Không hỗ trợ | Môi trường không thể sử dụng WSL 2 |
Nếu đã cài Git for Windows nhưng Claude Code không tìm thấy Git Bash, hãy ghi vị trí của bash.exe vào CLAUDE_CODE_GIT_BASH_PATH trong tệp cấu hình người dùng env.
{
"env": {
"CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
}
}Khi đã cài nhưng claude không chạy
'claude' is not recognized (trên Mac/Linux là command not found: claude) nghĩa là thư mục cài đặt chưa có trong PATH. Vị trí của trình cài đặt native là %USERPROFILE%\.local\bin\claude.exe trên Windows và ~/.local/bin/claude trên Mac/Linux. Nếu mở lại terminal vẫn không khắc phục, hãy kiểm tra và thêm bằng PowerShell theo hướng dẫn trong tài liệu chính thức.
# 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 --versionNếu cài bằng npm mà thấy thông báo npm.ps1 cannot be loaded because running scripts is disabled on this system (hoặc claude.ps1 khi khởi chạy), nguyên nhân là chính sách thực thi của PowerShell đang chặn tập lệnh .ps1 của npm (tài liệu chính thức, xác minh 3 tháng 10, 2026). Khắc phục bằng lệnh sau để chỉ cho phép chạy tập lệnh cục bộ đối với người dùng hiện tại. Nếu không muốn thay đổi chính sách, hãy dùng npm.cmd hoặc claude.cmd, hoặc chuyển sang trình cài đặt native dành cho PowerShell.
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserThiết lập chạy bằng khóa API mà không đăng nhập
Kunavo không phải Anthropic; đây là cổng API độc lập cung cấp quyền truy cập trả trước vào các mô hình như Claude. Claude Code có sẵn biến ANTHROPIC_BASE_URL chính thức để thay đổi đích gửi yêu cầu, và tài liệu chính thức có trang “Kết nối Claude Code với cổng LLM”. Không cần dùng plugin hay phiên bản đã chỉnh sửa. Biến này chỉ thay đổi đích gửi; một biến khác quyết định mô hình nào trả lời (Cấu hình mô hình, xác minh 3 tháng 10, 2026).
Bạn cần thiết lập 6 mục sau.
| Biến | Giá trị | Các điểm dễ nhầm |
|---|---|---|
ANTHROPIC_BASE_URL | https://api.kunavo.com | Chỉ đến domain. Claude Code sẽ tự thêm /v1/messages, vì vậy nếu ghi đến /v1 thì yêu cầu được gửi đến /v1/v1/messages và trả về 404 |
ANTHROPIC_AUTH_TOKEN | Khóa bắt đầu bằng sk-kn- | Chắc chắn hơn ANTHROPIC_API_KEY (giải thích bên dưới) |
ANTHROPIC_MODEL | claude-sonnet-5 | Model chính (Claude Sonnet 5). Phải khớp hoàn toàn với tên trong danh sách model của Kunavo |
ANTHROPIC_DEFAULT_OPUS_MODEL | claude-opus-5-5 | Cố định đích đến của alias opus thành Claude Opus 5.5. Yêu cầu Claude Code v2.1.280 trở lên (nếu cũ hơn, dùng claude update) |
ANTHROPIC_DEFAULT_SONNET_MODEL | claude-sonnet-5 | Đích đến của alias sonnet. Nếu không thiết lập, Sonnet 5.5 không có trên Kunavo sẽ được gọi, khiến /model sonnet, giai đoạn thực thi của opusplan và subagent chỉ định sonnet trả về 404 |
ANTHROPIC_DEFAULT_HAIKU_MODEL | claude-haiku-4-5 | Bí danh haiku và mô hình cho tác vụ chạy nền. Nếu không đặt, hệ thống sẽ gọi một ID mô hình không có trên Kunavo (Haiku 5.5 từ v2.1.293 trở đi), khiến /model haiku và các tác tử con được chỉ định dùng haiku trả về 404. Các tác vụ chạy nền như tóm tắt cũng sẽ chạy trên mô hình chính. |
Trên Mac/Linux, thêm vào tệp cấu hình shell (~/.zshrc hoặc ~/.bashrc) rồi mở lại terminal.
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-5Nếu chỉ muốn thử trên Windows, hãy chạy lệnh sau trong cửa sổ PowerShell. Lệnh sẽ biến mất khi đóng cửa sổ.
# このウィンドウの中だけで有効(閉じると消える)
$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"
claudeNếu không muốn nhập mỗi lần, hãy ghi vào env trong tệp cấu hình người dùng ~/.claude/settings.json (Windows là %USERPROFILE%\.claude\settings.json). Thiết lập này áp dụng cho mọi dự án và dùng cùng một cú pháp trên Mac lẫn Windows. Nếu tệp đã có cấu hình khác, chỉ thêm khối 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"
}
}Có 3 lưu ý về vị trí đặt cấu hình.
.claude/settings.jsoncủa dự án, đừng ghi khóa API vào đó. Khóa sẽ được đưa vào kho mã khi commit và được chia sẻ với tất cả những người sao chép kho mã (tài liệu chính thức).- Nếu cùng một biến tồn tại trong cả shell và tệp cấu hình, giá trị trong tệp cấu hình sẽ được sử dụng. Nếu chạy lại
exportmà vẫn không thay đổi, hãy kiểm tra tệp cấu hình. - Khi sử dụng với tiện ích mở rộng VS Code, hãy đặt các biến tương tự trong
claudeCode.environmentVariablescủa cài đặt người dùng VS Code.
Vì sao nên dùng ANTHROPIC_AUTH_TOKEN
ANTHROPIC_AUTH_TOKEN được gửi qua header Authorization: Bearer và có hiệu lực ngay khi được thiết lập. Ngược lại, ANTHROPIC_API_KEY được gửi qua header x-api-key; ở chế độ tương tác, lần đầu hệ thống sẽ yêu cầu phê duyệt một lần để sử dụng. Nếu từ chối tại đây, khóa sẽ bị bỏ qua mà không hiển thị gì về sau và không được sử dụng cho đến khi bật lại bằng Use custom API key trong /config. Kunavo chấp nhận khóa được gửi qua cả hai header, nên ANTHROPIC_API_KEY cũng hoạt động, nhưng ANTHROPIC_AUTH_TOKEN chắc chắn hơn vì không có cạm bẫy này. Tài liệu chính thức cũng hướng dẫn dùng ANTHROPIC_AUTH_TOKEN nếu không chỉ định loại khóa.
Lý do cố định model (tại thời điểm 3 tháng 10, 2026)
Theo tài liệu chính thức (xác minh 3 tháng 10, 2026), khi dùng khóa API, mô hình mặc định và bí danh opus trỏ đến Opus 5.5, còn bí danh sonnet trỏ đến Sonnet 5.5. Đích của các bí danh thay đổi mỗi khi có mô hình mới, nhưng không có nghĩa là Kunavo sẽ cung cấp mô hình đó ngay trong cùng ngày. Trên thực tế, tại thời điểm 3 tháng 10, 2026, Kunavo chưa cung cấp Sonnet 5.5, vì vậy nếu không ghim mà chọn /model sonnet, bạn sẽ nhận lỗi 404. Giai đoạn thực thi của opusplan và các tác nhân phụ chỉ định model: sonnet cũng vậy. Vì thế, trong cấu hình ở trên, ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5 cũng ghim bí danh sonnet. Bí danh opus cũng được ghim vào Claude Opus 5.5 bằng ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5 để không gặp vấn đề nếu đích của nó đổi sang Opus tiếp theo. Claude Opus 5.5 yêu cầu Claude Code v2.1.280 trở lên; nếu dùng phiên bản cũ, hãy cập nhật bằng lệnh claude update.
Ghim mô hình cũng giúp bạn dự tính chi phí dễ hơn. Nếu không chỉ định, mô hình mặc định sẽ là Claude Opus 5.5, có đơn giá mỗi token cao hơn so với khi dùng Claude Sonnet 5 làm mô hình chính. Đơn giá Kunavo (cho mỗi 1 triệu token, đầu vào / đầu ra) là: Claude Haiku 4.5 có giá $0,70 / $3,50, Claude Sonnet 5 có giá $1,40 / $7,00(Giá của Anthropic là $2,00 / $10,00), và Claude Opus 5.5 có giá $2,80 / $14,00. Nếu không đặt ANTHROPIC_DEFAULT_HAIKU_MODEL, trong phiên kết nối bằng ANTHROPIC_AUTH_TOKEN, các tác vụ nền như tóm tắt hội thoại dành cho claude --resume cũng chạy bằng mô hình chính (Hướng dẫn về khả năng tương thích của cổng, xác minh 3 tháng 10, 2026). Lưu ý, trên trang giá của Anthropic, Sonnet 5 — mô hình được ghim làm mô hình chính — đã được chuyển sang mục “Mô hình cũ” (xác minh 3 tháng 10, 2026).
Kiểm tra hoạt động theo 3 bước
1. Trước khi khởi động, chỉ kiểm tra URL và khóa
Đây là yêu cầu chỉ có 1 token đầu ra, giống tài liệu chính thức (số dư sẽ bị trừ một khoản rất nhỏ). Vì lệnh đọc các biến của shell, nếu chỉ ghi khóa trong tệp cấu hình thì hãy chạy export trong terminal này trước khi thực hiện. Nếu nhận được JSON bắt đầu bằng {"id":"msg_ cùng 200, URL và khóa đều bình thường; 401 nghĩa là khóa bị từ chối.
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": "."}]}'Với PowerShell, thực hiện như sau; nếu id nhận được bắt đầu bằng msg_ thì thành công.
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": "."}]}'2. Khởi động claude và xác nhận không xuất hiện màn hình đăng nhập
Lần đầu sẽ xuất hiện trình hướng dẫn chạy đầu tiên và xác nhận tin cậy thư mục, nhưng sau đó sẽ không yêu cầu đăng nhập bằng trình duyệt. Nếu bị yêu cầu đăng nhập, khóa chưa được nhận.
Một nguyên nhân thường gặp là chỉ ghi khóa vào .claude/settings.json hoặc .claude/settings.local.json của dự án. Trong phiên tương tác, env của cấu hình dự án chỉ được tải sau khi hoàn tất trình hướng dẫn và xác nhận tin cậy thư mục, nên tại thời điểm khởi động lần đầu, hệ thống coi như chưa có khóa. Hãy chuyển khóa vào export của shell hoặc ~/.claude/settings.json của người dùng.
3. Xem 2 dòng trong /status
Trong phiên, chạy /status rồi kiểm tra thẻ Status (tài liệu chính thức, xác minh 3 tháng 10, 2026).
- Trong
Anthropic base URLphải xuất hiệnhttps://api.kunavo.com. Dòng này chỉ xuất hiện khi đã cấu hình cổng; nếu không có dòng này thìANTHROPIC_BASE_URLchưa đến được phiên. - Trong
Auth tokenphải hiển thịANTHROPIC_AUTH_TOKEN. Nếu thay vào đó xuất hiệnLogin methodcủa tài khoản claude.ai thì đang chạy bằng thông tin đăng nhập đã lưu.
Những điểm thay đổi khi chạy bằng khóa API
- Không thể sử dụng Remote Control và tính năng nhập bằng giọng nói. Vì cả hai đều yêu cầu ID claude.ai, chúng bị vô hiệu hóa khi thông tin xác thực của cổng như
ANTHROPIC_AUTH_TOKENđang hoạt động. Từ v2.1.196 trở đi, Remote Control sẽ bị vô hiệu hóa chỉ vìANTHROPIC_BASE_URLtrỏ đến một host không phải Anthropic. /fastsẽ hiển thị là bị vô hiệu hóa. Khi chỉ xác thực bằng bearer token, Claude Code không hỏi khả năng sử dụng chế độ nhanh mà xem chế độ này là bị vô hiệu hóa và hiển thịFast mode has been disabled by your organization.- Con số trong
/contextchỉ là ước tính. Kunavo không cung cấp/v1/messages/count_tokens, nên Claude Code chuyển sang ước tính dựa trên số ký tự (Hướng dẫn về khả năng tương thích của cổng, xác minh 3 tháng 10, 2026).
Thông tin cấu hình chi tiết phía Kunavo có trong tài liệu tích hợp Claude Code và tài liệu về ANTHROPIC_BASE_URL (cả hai đều bằng tiếng Anh).
Thanh toán số dư API: JCB, Apple Pay, Google Pay, Link
Dưới đây là những điểm thường được hỏi trước khi thanh toán từ Nhật Bản.
| Điểm cần quan tâm | Câu trả lời |
|---|---|
| JCB có được chấp nhận không? | Được chấp nhận. Các thẻ có thể dùng trong trang thanh toán Stripe là Visa, Mastercard, American Express, JCB và UnionPay. Thẻ ghi nợ cũng có thể nhập như thẻ thông thường |
| Còn phương thức nào khác không? | Apple Pay (môi trường được hỗ trợ như Safari hoặc iPhone), Google Pay (khi đã thiết lập trên Chrome hoặc Android), Link (cơ chế gọi thông tin thanh toán đã lưu trong Stripe) |
| Có thể thanh toán bằng yên không? | Khi mở trang từ Nhật Bản, giá sẽ hiển thị bằng yên. Giá được tính bằng đô la; số tiền quy đổi sang yên bao gồm phí 2–4% do người mua chịu. Nếu chọn đô la trên trang thanh toán, khoản phí này sẽ không áp dụng, nhưng công ty phát hành thẻ có thể áp dụng tỷ giá và phí riêng (tài liệu Stripe, xác minh 3 tháng 10, 2026) |
| Còn thanh toán tại cửa hàng tiện lợi/PayPay thì sao? | Không hỗ trợ. Chuyển khoản ngân hàng và thanh toán qua nhà mạng cũng không được hỗ trợ |
| Còn tự động nạp tiền? | Chỉ có thể thiết lập bằng thẻ đã lưu hoặc Link |
| Còn hóa đơn đủ điều kiện (invoice)? | Không phát hành |
| Có thể dùng để thanh toán Claude Pro / Max không? | Không thể. Khoản được nạp là số dư API của Kunavo |
Có 4 bước. Trước tiên, đăng ký Kunavo (bằng địa chỉ email hoặc tài khoản Google; khi đăng ký không yêu cầu thông tin thẻ). Tiếp theo, chọn số tiền nạp trong Billing của bảng điều khiển. Tối thiểu là $10, không có phí hàng tháng và các khoản lớn sẽ được cộng bonus ($100 để nhận số dư $110, $1.000 để nhận số dư $1.200 và $5.000 để nhận số dư $6.250). Sau khi chọn một trong các phương thức trên và thanh toán trên trang thanh toán Stripe, cuối cùng tạo khóa sk-kn- trong API Keys rồi nhập vào ANTHROPIC_AUTH_TOKEN. Khóa chỉ hiển thị một lần khi được tạo, vì vậy hãy sao chép ngay lúc đó.
Số dư không có hạn sử dụng và các yêu cầu thất bại không bị tính phí. Các phương thức có thể dùng để thanh toán gói Claude tại Nhật Bản (bao gồm qua App Store/Google Play) được tổng hợp có dẫn nguồn trong Phương thức thanh toán Claude.
Ước tính chi phí
Claude Code chạy bằng khóa API được tính phí theo số token sử dụng. Claude Code gửi toàn bộ ngữ cảnh cuộc trò chuyện trong mỗi yêu cầu, nhưng phần đầu giống lần trước có thể được tính theo đơn giá đọc cache. Bảng dưới đây giả định input của một yêu cầu là 40.000 token (trong đó 36.000 = 90% là đọc cache, phần còn lại 4.000 là ghi cache), output là 1.000 token và một tác vụ gồm 50 yêu cầu. Không bao gồm các lệnh gọi Claude Haiku 4.5 chạy nền. Đơn giá cache của Kunavo có tỷ lệ đọc bằng 10% đơn giá input và ghi bằng 1,25 lần trong trường hợp Claude Sonnet 5 (mỗi model trong bảng được tính theo tỷ lệ tương ứng). Đây không phải số đo thực tế cũng không phải mức trần.
| Mô hình | 1 yêu cầu | 50 yêu cầu | 50 yêu cầu (khi cache hoàn toàn không hoạt động) |
|---|---|---|---|
| Claude Sonnet 5 | $0,019 | $0,95 | $3,15 |
| Claude Opus 5.5 | $0,033 | $1,65 | $6,30 |
Số tiền thực tế thay đổi tùy độ dài ngữ cảnh, hiệu quả của cache, độ dài phản hồi và việc có /clear cho mỗi tác vụ hay không. Đơn giá của tất cả model có trong trang giá; ước tính theo cách bạn sử dụng có trong công cụ tính chi phí token Claude (tiếng Anh); đơn giá API theo từng model có trong giá Claude API.
Các lỗi thường gặp và cách xử lý
| Giai đoạn | Hiển thị/Triệu chứng | Nguyên nhân và cách xử lý |
|---|---|---|
| Cài đặt | The token '&&' is not a valid statement separator | Bạn đang dán dòng dành cho CMD vào PowerShell. Hãy dùng dòng irm … | iex. |
| Cài đặt | 'irm' is not recognized as an internal or external command | Bạn đang dán dòng dành cho PowerShell vào CMD. Hãy dùng dòng install.cmd. |
| Cài đặt | Lỗi liên quan đến -fsSL hoặc bash trong PowerShell | Bạn đang chạy dòng dành cho Mac/Linux trên Windows. Hãy dùng dòng dành cho PowerShell. |
| Cài đặt | syntax error near unexpected token '<'、curl: (22) The requested URL returned error: 403 | URL của trình cài đặt đang trả về HTML hoặc lỗi thay vì tập lệnh (tài liệu chính thức, xác minh 3 tháng 10, 2026). Hãy kiểm tra proxy hoặc tường lửa của công ty; thử mạng khác hoặc hỏi quản trị viên nội bộ. |
| Cài đặt | App unavailable in region | Kết nối bị xác định là đến từ quốc gia không được hỗ trợ. Nhật Bản được hỗ trợ, vì vậy hãy tắt VPN hoặc proxy qua nước ngoài. |
| Cài đặt | Cảnh báo EBADENGINE | Node.js thấp hơn 22. Quá trình cài đặt vẫn hoàn tất, nhưng hãy cập nhật Node.js. |
| Cài đặt | npm.ps1 cannot be loaded | Đây là chính sách thực thi của PowerShell. Chạy Set-ExecutionPolicy hoặc chuyển sang trình cài đặt native. |
| Khởi động | command not found: claude、'claude' is not recognized | Thư mục cài đặt không có trong PATH. Mở lại terminal và trên Windows, thêm nó theo hướng dẫn PowerShell ở trên. |
| Khởi động | claude native binary not installed (Mac/Linux) | Bạn đang bỏ qua dependency tùy chọn khi cài bằng npm (--omit=optional, optional=false). Hãy bỏ thiết lập này rồi cài đặt lại. |
| Khởi động | Claude Code does not support 32-bit Windows | Bạn đang chạy trong “Windows PowerShell (x86)”. Hãy mở phiên bản không có (x86). |
| Khởi động | Đã thiết lập khóa nhưng màn hình đăng nhập vẫn xuất hiện | Khóa chưa được tải. Hãy ghi khóa vào shell hoặc ~/.claude/settings.json, không phải cấu hình dự án, rồi khởi động trong terminal mới. Nếu đang dùng ANTHROPIC_API_KEY và trước đây đã từ chối phê duyệt, hãy bật lại bằng Use custom API key trong /config hoặc chuyển sang ANTHROPIC_AUTH_TOKEN. |
| Kết nối | 401 | Khóa bị từ chối. Kiểm tra xem bạn đã sao chép đầy đủ khóa sk-kn- không có khoảng trắng đến cuối chưa, và khóa có bị xóa trong API Keys không. |
| Kết nối | 402 | Bạn không đủ số dư hoặc đã đạt giới hạn sử dụng hàng tháng đặt cho khóa. Hãy nạp tiền trong Billing hoặc xem lại giới hạn của khóa. |
| Kết nối | 404 | Kiểm tra xem cuối ANTHROPIC_BASE_URL có /v1 hay không; hoặc bạn chưa cố định model nên đang gọi model không có trên Kunavo (chẳng hạn Sonnet 5.5). |
Trường hợp phương pháp này không phù hợp
- Hóa đơn đủ điều kiện là bắt buộc để quyết toán chi phí. Trang thanh toán Kunavo không phát hành hóa đơn hoặc hóa đơn đủ điều kiện có mã đăng ký.
- Muốn thanh toán tại cửa hàng tiện lợi hoặc bằng PayPay. Cả hai phương thức đều không được hỗ trợ, cũng như chuyển khoản ngân hàng và thanh toán qua nhà mạng. Tự động nạp tiền chỉ dùng được với thẻ đã lưu hoặc Link.
- Muốn sử dụng Remote Control hoặc tính năng nhập bằng giọng nói. Không thể dùng bằng khóa API và
/fastcũng sẽ hiển thị là bị vô hiệu hóa. Hãy đăng nhập bằng gói đăng ký. - Muốn sử dụng Sonnet 5.5. Kunavo không cung cấp model này tại thời điểm 3 tháng 10, 2026.
- Muốn hoàn tất cấu hình chỉ bằng tài liệu tiếng Nhật. Tài liệu chính thức của Claude Code có thể đọc bằng tiếng Nhật, nhưng tài liệu tích hợp của Kunavo chỉ có tiếng Anh.
Việc cần làm tiếp theo
Sau khi xác nhận bằng /status, hãy khởi động claude trong thư mục dự án cần làm việc, rồi trước tiên tạo CLAUDE.md bằng /init. Cách viết CLAUDE.md, giảm hộp thoại xác nhận và tạo lệnh tùy chỉnh được giải thích lần lượt trong Cách sử dụng Claude Code.
Câu hỏi thường gặp
Cài đặt Claude Code như thế nào? Có khác nhau giữa Mac và Windows không?
Chỉ khác lệnh sử dụng; cả hai đều được cài bằng một dòng của trình cài đặt native chính thức. Mac/Linux/WSL dùng curl -fsSL https://claude.ai/install.sh | bash, Windows PowerShell dùng irm https://claude.ai/install.ps1 | iex, còn Command Prompt (CMD) dùng curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd. Sau khi cài xong, mở terminal mới và chạy claude --version; nếu số phiên bản xuất hiện thì đã hoàn tất. Bản native tự động cập nhật ở chế độ nền.
Khi cài trên Windows, có cần quyền quản trị, Git for Windows hoặc WSL không?
Không bắt buộc mục nào. Theo tài liệu chính thức (xác nhận ngày 3 tháng 10, 2026), bạn không cần chạy với tư cách quản trị viên, còn Git for Windows là tùy chọn (nếu chưa cài, Claude Code sẽ thực thi lệnh trong PowerShell). WSL cũng không cần; bạn có thể cài trực tiếp từ PowerShell hoặc CMD. Chỉ chọn WSL 2 khi muốn dùng sandbox hoặc công cụ Linux, rồi chạy dòng dành cho Mac/Linux trong terminal WSL. Lưu ý rằng “Windows PowerShell (x86)” chạy 32 bit nên không thể sử dụng.
Có thể cài bằng npm install -g @anthropic-ai/claude-code không? Node.js 18 có được không?
Có thể cài, nhưng yêu cầu chính thức là Node.js 22 trở lên (đã kiểm tra vào 3 tháng 10, 2026). Các bài viết ghi “18 trở lên” là thông tin cũ. Nếu thấp hơn 22, npm sẽ cảnh báo EBADENGINE (bản thân quá trình cài đặt vẫn hoàn tất). Không thêm sudo; để cập nhật, dùng npm install -g @anthropic-ai/claude-code@latest thay vì npm update -g. Nếu không định dùng Node.js, trình cài đặt native sẽ ít rắc rối hơn.
Có thể sử dụng Claude Code mà không cần đăng ký gói (không đăng ký Pro / Max) không?
Có thể. Khi đăng nhập, bạn cần gói Pro, Max, Team, Enterprise hoặc tài khoản Console; gói miễn phí không bao gồm Claude Code. Nếu không đăng nhập, đặt ANTHROPIC_BASE_URL=https://api.kunavo.com và ANTHROPIC_AUTH_TOKEN (khóa API của Kunavo), bạn có thể sử dụng mà không phải trả phí hàng tháng; chi phí chỉ được trừ theo số token đã dùng từ số dư trả trước. Đổi lại, Remote Control và tính năng nhập bằng giọng nói không khả dụng.
Không được đặt khóa API vào ANTHROPIC_API_KEY sao?
Vẫn hoạt động, nhưng chúng tôi khuyến nghị ANTHROPIC_AUTH_TOKEN. ANTHROPIC_AUTH_TOKEN được gửi qua header Authorization: Bearer và có hiệu lực ngay khi được thiết lập. ANTHROPIC_API_KEY được gửi qua header x-api-key; ở chế độ tương tác, lần đầu hệ thống sẽ yêu cầu phê duyệt một lần, và nếu bạn từ chối thì khóa sẽ âm thầm bị bỏ qua về sau (có thể bật lại bằng Use custom API key trong /config). Kunavo chấp nhận khóa ở cả hai header. Hãy đặt khóa trong tệp cấu hình shell hoặc ~/.claude/settings.json, không đặt trong .claude/settings.json của dự án.
Sau khi chuyển sang /model sonnet, tôi nhận được lỗi 404. Tại sao?
Khi sử dụng khóa API, alias sonnet trỏ đến Sonnet 5.5 mới nhất (xác nhận trong tài liệu chính thức, 3 tháng 10, 2026). Tại thời điểm 3 tháng 10, 2026, Kunavo chưa cung cấp Sonnet 5.5, nên để nguyên alias sẽ trả về 404. Giai đoạn thực thi của opusplan và các subagent chỉ định model: sonnet cũng vậy. Hãy thêm ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5 (đã có trong cấu hình của trang này). Vì cùng lý do, cấu hình của trang này cố định model chính là claude-sonnet-5, opus là claude-opus-5-5 (Opus 5.5; yêu cầu Claude Code v2.1.280 trở lên, nếu cũ hơn hãy cập nhật bằng claude update), và haiku là claude-haiku-4-5. Nếu thêm /v1 vào cuối ANTHROPIC_BASE_URL cũng sẽ trả về 404.
Làm thế nào để kiểm tra Claude Code đang chạy bằng khóa API?
Trong Claude Code, chạy /status. Nếu “Anthropic base URL” là https://api.kunavo.com và “Auth token” là ANTHROPIC_AUTH_TOKEN thì đang chạy bằng khóa API. Nếu xuất hiện “Login method” của tài khoản claude.ai thì các biến chưa được tải.
Có thể dùng JCB để thanh toán không? Còn thanh toán tại cửa hàng tiện lợi hoặc PayPay thì sao?
Có thể dùng JCB. Trong trang thanh toán Stripe của Kunavo, bạn có thể chọn thẻ Visa, Mastercard, American Express, JCB và UnionPay, Apple Pay và Google Pay trên các thiết bị được hỗ trợ, cùng Link; khi mở từ Nhật Bản, số tiền được hiển thị bằng yên (quy đổi sang yên bao gồm phí 2–4% của Stripe; thanh toán bằng đô la thì không mất phí này). Nạp tiền từ $10, không có phí hàng tháng và số dư không hết hạn. Không hỗ trợ thanh toán tại cửa hàng tiện lợi, PayPay, chuyển khoản ngân hàng hoặc thanh toán qua nhà mạng. Khoản nạp này được cộng vào số dư API và không thể dùng để thanh toán Claude Pro / Max.
Có cấp hóa đơn đủ điều kiện (invoice) để quyết toán chi phí không?
Không. Trang thanh toán của Kunavo không phát hành hóa đơn đủ điều kiện có mã đăng ký. Nếu hóa đơn đủ điều kiện là bắt buộc để hạch toán chi phí công ty, hãy so sánh với phương án thanh toán trực tiếp cho Anthropic trước khi quyết định. Nếu dùng tự động nạp tiền, bạn cần thẻ đã lưu hoặc Link.