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

Cài đặt Claude Code: Windows, macOS và Linux, khóa API không cần gói đăng ký và thanh toán bằng Bancontact

Claude Code được cài đặt bằng một lệnh. Các vấn đề thường xuất hiện sau đó, chủ yếu là: mở sai cửa sổ trên Windows, PATH hoặc phiên bản Node.js khi dùng npm. Sau đó, bạn vẫn cần thiết lập khóa API không cần gói đăng ký và thanh toán từ Pháp hoặc Bỉ.

Để cài đặt Claude Code, chỉ cần một dòng lệnh, nhưng dòng lệnh đó khác nhau tùy nơi: curl -fsSL https://claude.ai/install.sh | bash trong terminal macOS, Linux hoặc WSL, irm https://claude.ai/install.ps1 | iex trong PowerShell và dòng install.cmd trong dấu nhắc lệnh Windows. Câu hỏi thực sự xuất hiện ở lần khởi chạy đầu tiên: ai trả tiền cho các yêu cầu? Tài khoản Pro, Max, Team, Enterprise hoặc Console cho phép đăng nhập (gói miễn phí của Claude.ai không bao gồm Claude Code). Không có thuê bao, chỉ cần API key: sáu biến, trong đó có ANTHROPIC_BASE_URL không có /v1 và ANTHROPIC_AUTH_TOKEN, sau đó kiểm tra nhanh bằng /status. Số dư Kunavo có thể thanh toán bằng thẻ, Apple Pay, Google Pay, Link hoặc, tại Bỉ, Bancontact, từ $10, không cần thuê bao.

Thông tin lấy từ đâu: các lệnh và biến được trích từ tài liệu chính thức của Claude Code (cài đặt, biến môi trường, kết nối với gateway), được xem lại ngày 3 tháng 10, 2026; giá Kunavo và phương thức thanh toán được kiểm tra ngày 10 tháng 10, 2026. Theo danh sách quốc gia được Anthropic hỗ trợ (xem ngày 3 tháng 10, 2026), Claude.ai và API khả dụng tại Pháp, Bỉ, Thụy Sĩ, Luxembourg và Canada, cũng như Maroc, Tunisia, Algeria, Senegal và Bờ Biển Ngà. Hướng dẫn này cũng có bản tiếng Anh và, dành cho vùng Flanders, bản tiếng Hà Lan.

Nhập lệnh nào: tất cả tùy thuộc vào cửa sổ

Bạn đang ở đâuLệnhCập nhật
Terminal macOS, Linux hoặc WSLcurl -fsSL https://claude.ai/install.sh | bashTự động
Windows, PowerShell (dấu nhắc PS C:\…>)irm https://claude.ai/install.ps1 | iexTự động
Windows, dấu nhắc lệnh (C:\…> không có PS)Dòng install.cmd bên dướiTự động
Homebrew, WinGetbrew install --cask claude-code, winget install Anthropic.ClaudeCodeBạn tự chạy
apt, dnf, apk (Debian, Ubuntu, Fedora, RHEL, Alpine)Kho đã ký của Anthropic, xem trang cài đặtCùng với các bản cập nhật hệ thống
Terminal
# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash
PowerShell
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
cmd.exe
:: Invite de commandes Windows (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Ba dòng đầu tiên cài đặt phiên bản native, phiên bản được Anthropic khuyến nghị: một binary độc lập, được đặt trong ~/.local/bin (%USERPROFILE%\.local\bin trên Windows), tự tải xuống các bản cập nhật ở chế độ nền và áp dụng chúng khi khởi động lần sau. Sau khi cài đặt xong, hãy đóng terminal và mở lại một terminal khác: terminal đã dùng để cài đặt chưa biết PATH mới.

Trên Windows, chọn nhầm cửa sổ là nguyên nhân thất bại số một và thông báo cho biết rất rõ. The token '&&' is not a valid statement separator: bạn đã dán dòng CMD vào PowerShell. 'irm' is not recognized as an internal or external command: ngược lại. Trên Windows tiếng Pháp, thông báo thứ hai có thể xuất hiện dưới dạng bản dịch; nguyên nhân không thay đổi. Các thông báo khác nằm trong bảng lỗi ở cuối hướng dẫn.

Yêu cầu hệ thống

Hạng mụcTài liệu chính thức yêu cầu gì (được đọc vào 3 tháng 10, 2026)
Hệ thốngmacOS 13.0 trở lên; Windows 10 1809 trở lên hoặc Windows Server 2019 trở lên; Ubuntu 20.04+, Debian 10+, Alpine Linux 3.19+
Phần cứngÍt nhất 4 GB RAM, bộ xử lý x64 hoặc ARM64 (không hỗ trợ Windows 32 bit)
ShellBash, Zsh, PowerShell hoặc CMD
Quốc giaMột quốc gia được Anthropic hỗ trợ (Pháp, Bỉ, Thụy Sĩ, Luxembourg, Canada…)
Tài khoảnĐăng nhập: Pro, Max, Team, Enterprise hoặc Console; gói miễn phí không bao gồm Claude Code. Với API key thì không cần thuê bao hoặc đăng nhập.
Node.jsChỉ dành cho cài đặt bằng npm, phiên bản 22 trở lên

Windows: các hướng dẫn cũ nói gì và sự thật là gì

Nhiều hướng dẫn bằng tiếng Pháp có từ những phiên bản đầu tiên của Claude Code. Dưới đây là các chỉ dẫn phổ biến nhất, được đối chiếu với tài liệu cài đặt hiện hành và trang khắc phục sự cố (được xem ngày 3 tháng 10, 2026):

Điều vẫn còn được đọcĐiều đúng ở hiện tại
“Trước tiên hãy cài đặt WSL”Claude Code chạy trực tiếp trên Windows. Việc dùng WSL 2 chỉ hợp lý khi bạn cần các công cụ Linux hoặc chạy lệnh trong sandbox.
“Mở PowerShell với tư cách quản trị viên”Không cần: tài liệu nêu rõ rằng việc này không cần thiết.
“Git là bắt buộc”Không bắt buộc nhưng được khuyến nghị: Git for Windows cung cấp Git Bash, phụ thuộc vào đó là các công cụ Bash và Monitor. Không có Git, Claude Code thực thi các lệnh bằng PowerShell.
“Cần Node.js 18”Node.js chỉ cần cho việc cài đặt bằng npm, và khi đó phải dùng phiên bản 22 trở lên.
“curl … | bash hoạt động ở mọi nơi”Không phải trong Windows PowerShell, nơi curl là bí danh của Invoke-WebRequest: lệnh sẽ thất bại với tham số fsSL.

Nếu cài đặt Git for Windows, Claude Code sử dụng Git Bash và vẫn giữ công cụ PowerShell bên cạnh. Đôi khi chương trình không tìm thấy bash.exe: khi đó, hãy khai báo đường dẫn đến tệp này trong biến CLAUDE_CODE_GIT_BASH_PATH, thuộc khối env của ~/.claude/settings.json (tài liệu đưa ra ví dụ C:\Program Files\Git\bin\bash.exe). Một điều dễ bỏ sót cuối cùng: lối tắt “Windows PowerShell (x86)” khởi chạy phiên bản 32 bit mà Claude Code từ chối.

Windows native hoặc WSL, lựa chọn phụ thuộc vào nơi lưu dự án của bạn:

Chế độCần chuẩn bịMôi trường cách lyDành cho ai
Windows nativeKhông cần gì; Git for Windows là tùy chọnKhôngCác dự án và công cụ Windows
WSL 2Đã bật WSL 2CóBộ công cụ Linux, các lệnh biệt lập
WSL 1Đã bật WSL 1KhôngCác máy không hỗ trợ WSL 2

Với WSL, mọi thứ diễn ra bên trong bản phân phối Linux: bạn dán dòng curl … | bash ở đó và sau đó nhập claude cũng ở đó. Nếu khởi chạy từ PowerShell hoặc CMD, lệnh sẽ không thấy bản cài đặt này.

Homebrew, WinGet, apt hoặc npm

Các trình quản lý gói vẫn hoạt động, nhưng có một đánh đổi: Claude Code không được cập nhật tự động qua chúng. Với Homebrew và WinGet, biến CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 yêu cầu Claude Code tự khởi chạy quá trình cập nhật; nếu không có biến này, bạn phải tự thực hiện:

# Homebrew (macOS)
brew install --cask claude-code
brew upgrade claude-code              # pas de mise à jour automatique

# WinGet (Windows)
winget install Anthropic.ClaudeCode
winget upgrade Anthropic.ClaudeCode   # pas de mise à jour automatique

Trên Debian, Ubuntu, Fedora, RHEL và Alpine, Anthropic cũng phát hành các kho apt, dnf và apk có chữ ký, được cập nhật cùng với phần còn lại của hệ thống; quy trình được trình bày trên trang cài đặt.

Còn npm, tiện lợi nếu Node.js đã nằm trong bộ công cụ của bạn. Gói yêu cầu tối thiểu Node.js 22. Với phiên bản cũ hơn, npm chỉ hiển thị cảnh báo EBADENGINE rồi vẫn hoàn tất vì gói cài cùng một binary native, vốn không cần Node.js để chạy. Hai quy tắc: không dùng sudo npm install -g và cập nhật bằng @latest, vì npm update -g vẫn nằm trong phạm vi phiên bản ban đầu và có thể khiến bạn bị tụt lại.

Terminal
node -v                                       # v22 ou plus récent
npm install -g @anthropic-ai/claude-code      # jamais avec sudo

# mise à jour : avec @latest, pas avec npm update -g
npm install -g @anthropic-ai/claude-code@latest

Kiểm tra cài đặt và sửa PATH

claude --version   # affiche le numéro de version, suivi de (Claude Code)
claude doctor      # diagnostic de l’installation et des réglages, sans ouvrir de session

Nếu trả về số phiên bản thì đã cài đặt thành công. claude doctor kiểm tra sâu hơn mà không khởi chạy phiên: trạng thái cài đặt, lỗi trong tệp cấu hình và kết quả của lần cập nhật gần nhất. Khi có vấn đề, đây là lệnh đầu tiên cần chạy.

Trên macOS hoặc Linux, lỗi command not found: claude; trên Windows, thông báo claude: chương trình đã được cài đặt nhưng shell không biết tìm chương trình ở đâu. Thường chỉ cần mở cửa sổ mới. Nếu vẫn không được, hãy thêm ~/.local/bin vào PATH trong ~/.zshrc hoặc ~/.bashrc. Trên Windows, trang khắc phục sự cố chính thức hướng dẫn ba bước PowerShell sau:

PowerShell
# 1. Le dossier d'installation est-il déjà dans le PATH ?
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Aucun résultat ? Ajoutez-le au PATH de l'utilisateur, puis ouvrez une nouvelle fenêtre
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. Dans la nouvelle fenêtre : deux chemins = deux installations concurrentes
where.exe claude

Đã cài đặt bằng npm nhưng PowerShell trả về npm.ps1 cannot be loaded? Chính sách thực thi của PowerShell đang chặn các tập lệnh npm. Hãy chuyển sang trình cài đặt native hoặc cho phép các tập lệnh cục bộ chỉ cho tài khoản của bạn:

PowerShell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Ai thanh toán cho các yêu cầu: gói đăng ký Claude hay khóa API

Lựa chọn này không được thực hiện khi cài đặt mà ở lần khởi chạy đầu tiên, và có thể thay đổi bất cứ lúc nào. Khóa được đặt trong môi trường sẽ được ưu tiên hơn kết nối claude.ai đã lưu, kết nối này vẫn ở trạng thái chờ; hãy xóa biến đó để kết nối được ưu tiên lại ở lần khởi chạy tiếp theo.

Gói đăng ký ClaudeKhóa API Kunavo, không cần gói đăng ký
Bạn cầnTài khoản Pro, Max, Team, Enterprise hoặc ConsoleMột khóa sk-kn-…
Chi phíPro: 20 đô la mỗi tháng, hoặc trả trước 200 đô la cho cả năm; Max: từ 100 đô la mỗi tháng; giá chưa bao gồm thuế (claude.com/pricing, xem ngày 3 tháng 10, 2026). Console: tính theo token, do Anthropic cung cấpTính theo token, trừ vào số dư trả trước; không có phí hằng tháng
Thanh toánTrên web, chỉ chấp nhận thẻ tín dụng hoặc thẻ ghi nợThẻ, Apple Pay, Google Pay, Link; Bancontact tại Bỉ
Remote Control, nhập liệu bằng giọng nóiCó, với kết nối claude.aiKhông
Thiết lậpĐăng nhập trong trình duyệtSáu biến môi trường

Với gói đăng ký Claude

Không cần cấu hình: chạy claude trong thư mục dự án, sau đó đăng nhập trong trình duyệt. Chỉ có một ngoại lệ: nếu trong môi trường của bạn còn sót lại ANTHROPIC_API_KEY. Khi đó, Claude Code sẽ hỏi một lần liệu có nên sử dụng biến này hay không; lựa chọn từ chối sẽ được ghi nhớ, và khóa sau đó bị bỏ qua mà không hiển thị thông báo, khiến bạn tưởng rằng biến không được đọc. Để thay đổi lựa chọn này: /config → Use custom API key.

Không cần gói đăng ký: khóa API Kunavo

Chuyển Claude Code sang sử dụng một dịch vụ khác thay vì Anthropic không phải là cách làm chắp vá. Danh sách biến môi trường chính thức nêu ANTHROPIC_BASE_URL là cách gửi yêu cầu qua proxy hoặc gateway. Kunavo phản hồi theo định dạng Anthropic Messages API: bạn vẫn sử dụng Claude Code chính thức, không cần tiện ích mở rộng hay phiên bản đã chỉnh sửa.

  1. Mở tài khoản: đăng ký Kunavo.
  2. Nạp số dư trong Billing, tối thiểu $10 (các phương thức thanh toán ở bên dưới).
  3. Tạo khóa tại /app/keys. Khóa bắt đầu bằng sk-kn- và chỉ được hiển thị khi tạo: hãy sao chép ngay.
  4. Điền sáu biến bên dưới.
BiếnGiá trịLý do và những gì sẽ hỏng nếu không làm vậy
ANTHROPIC_BASE_URLhttps://api.kunavo.comChỉ tên miền. Claude Code tự thêm /v1/messages: nếu có thêm /v1, yêu cầu sẽ được gửi tới /v1/v1/messages và trả về lỗi 404.
ANTHROPIC_AUTH_TOKENKhóa sk-kn-… của bạnĐược gửi trong tiêu đề Authorization: Bearer và có hiệu lực ngay lập tức. ANTHROPIC_API_KEY được truyền qua tiêu đề x-api-key, tiêu đề này cũng được Kunavo chấp nhận nhưng yêu cầu phê duyệt ở lần khởi chạy tương tác đầu tiên.
ANTHROPIC_MODELclaude-sonnet-5Mô hình chính, được ghi chính xác như trong danh mục Kunavo; tên không tồn tại sẽ trả về lỗi 404.
ANTHROPIC_DEFAULT_OPUS_MODELclaude-opus-5-5Xác định alias opus trỏ tới mô hình nào và opusplan khi ở chế độ lập kế hoạch. Opus 5.5 yêu cầu Claude Code v2.1.280 trở lên; nếu không, hãy chạy claude update.
ANTHROPIC_DEFAULT_SONNET_MODELclaude-sonnet-5Xác định alias sonnet trỏ tới mô hình nào và opusplan khi không ở chế độ lập kế hoạch. Nếu không có biến này, /model sonnet và các tác nhân con được cấu hình là sonnet sẽ yêu cầu Sonnet 5.5 và nhận lỗi 404.
ANTHROPIC_DEFAULT_HAIKU_MODELclaude-haiku-4-5Khi sử dụng cổng trung gian, các tác vụ nền (tiêu đề phiên…) nếu không sẽ dùng mô hình chính. Nếu thiếu dòng này, ngoài ra bí danh haiku sẽ yêu cầu một ID mà Kunavo không cung cấp (Haiku 5.5 kể từ v2.1.293): /model haiku và các tác tử phụ được thiết lập dùng haiku sẽ nhận lỗi 404.

Tại sao cần cố định bốn mô hình? Các bí danh của Claude Code thay đổi theo những phiên bản Anthropic phát hành. Theo tài liệu cấu hình mô hình (được xem ngày 3 tháng 10, 2026), đối với tài khoản API, cài đặt mặc định và opus hiện trỏ đến Opus 5.5, còn sonnet trỏ đến Sonnet 5.5, mô hình mà Kunavo không cung cấp: nếu không đặt ANTHROPIC_DEFAULT_SONNET_MODEL, /model sonnet, giai đoạn thực thi của opusplan và các tác nhân con được đặt thành sonnet sẽ gặp lỗi 404. Bí danh opus được cố định vào Opus 5.5 (claude-opus-5-5), mô hình yêu cầu Claude Code v2.1.280 trở lên; nếu dùng phiên bản cũ hơn, hãy chạy claude update. Mô hình vừa phát hành cũng không phải lúc nào cũng có trên Kunavo ngay trong ngày. Dùng tên đầy đủ để mỗi yêu cầu được gửi đến một mô hình đang được cung cấp với mức giá đã biết. Tài liệu về giao thức gateway (được xem ngày 3 tháng 10, 2026) xác nhận điểm liên quan đến các tác vụ chạy nền: với Claude Haiku 4.5, chi phí của chúng thấp.

Nơi ghi các biến

Vị tríPhạm viĐiều cần biết
Khối env trong ~/.claude/settings.jsonTất cả dự án của bạn, bất kể thiết bị đầu cuốiLựa chọn tốt nhất. Trên Windows: %USERPROFILE%\.claude\settings.json. Nếu trùng với shell, tệp này sẽ được ưu tiên.
export trong ~/.zshrc hoặc ~/.bashrcCác thiết bị đầu cuối được mở sau đóTrình chỉnh sửa được khởi chạy từ Dock hoặc menu Start sẽ không thấy chúng.
$env: trong PowerShellCửa sổ hiện tạiPhù hợp để thử lần đầu, nhưng mất khi đóng cửa sổ.
claudeCode.environmentVariables (VS Code)Tiện ích mở rộng VS CodeTiện ích mở rộng kiểm tra thông tin xác thực tại đây trước khi khởi động; settings.json được truyền tới tiến trình chứ không ảnh hưởng đến bước kiểm tra này.
.claude/settings.json của một dự ánToàn bộ kho mãKhông bao giờ dùng làm nơi lưu khóa: tệp này được quản lý phiên bản và chia sẻ với bất kỳ ai sao chép kho mã (tài liệu về gateway, được xem ngày 3 tháng 10, 2026).

Phiên bản được khuyến nghị, cần hợp nhất với nội dung hiện có của tệp nếu tệp đã tồn tại (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-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

Các giá trị tương tự trong shell trên macOS và Linux:

~/.zshrc
export ANTHROPIC_BASE_URL=https://api.kunavo.com   # le domaine seul, sans /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

Để kiểm tra nhanh trong cửa sổ PowerShell:

PowerShell
# Valable uniquement dans cette fenêtre 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

Đối với tiện ích mở rộng VS Code, trong phần cài đặt người dùng của trình chỉnh sửa (lệnh Preferences: Open User Settings (JSON)):

settings.json (VS Code)
{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://api.kunavo.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-kn-..." },
    { "name": "ANTHROPIC_MODEL", "value": "claude-sonnet-5" },
    { "name": "ANTHROPIC_DEFAULT_OPUS_MODEL", "value": "claude-opus-5-5" },
    { "name": "ANTHROPIC_DEFAULT_SONNET_MODEL", "value": "claude-sonnet-5" },
    { "name": "ANTHROPIC_DEFAULT_HAIKU_MODEL", "value": "claude-haiku-4-5" }
  ]
}

Ứng dụng Claude trên máy tính là ngoại lệ: ứng dụng không đọc ANTHROPIC_BASE_URL cũng như settings.json. Một biến đã sửa trong shell nhưng vẫn không có tác dụng? Trước tiên, hãy kiểm tra biến tương tự trong settings.json, nơi được ưu tiên.

Giá mỗi một triệu token lấy từ danh mục Kunavo, bên cạnh giá công khai của Anthropic được ghi nhận trên claude.com/pricing (xem ngày 3 tháng 10, 2026):

Mô hìnhKunavo (đầu vào / đầu ra)Giá công khai của Anthropic (đầu vào / đầu ra)Chênh lệchMức sử dụng điển hình
claude-haiku-4-5$0,70 / $3,50$1,00 / $5,00~30% thấp hơnTác vụ nền (tiêu đề phiên…), các bản sửa nhỏ
claude-sonnet-5$1,40 / $7,00$2,00 / $10,00~30% thấp hơnMô hình dùng hằng ngày, được thiết lập bởi ANTHROPIC_MODEL
claude-opus-5-5$2,80 / $14,00$4,00 / $20,00~30% thấp hơnThiết kế lại toàn bộ một mô-đun, lập kế hoạch kiến trúc

Để chuyển sang Opus trong thời gian thực hiện một tác vụ: chạy /model opus trong phiên hiện tại (alias được ghim vào claude-opus-5-5), hoặc dùng claude --model claude-opus-5-5 khi khởi động. Ngân sách hằng tháng theo mức sử dụng của bạn và ngưỡng từ đó gói đăng ký trở nên có lợi hơn được tính trong giá Claude Code. Công cụ tính chi phí token Claude sẽ tính theo khối lượng riêng của bạn, còn trang giá liệt kê tất cả các mô hình.

Kiểm tra bằng /status

Dấu hiệu đầu tiên, ngay cả trước /status: khi ANTHROPIC_AUTH_TOKEN được thiết lập, Claude Code khởi động mà không hiển thị màn hình đăng nhập. Nếu màn hình này xuất hiện, không có khóa nào được đọc, thường là vì khóa chỉ nằm trong cài đặt dự án (.claude/settings.json hoặc .claude/settings.local.json). Trong phiên tương tác, khối env này chỉ được áp dụng sau trình hướng dẫn khởi chạy đầu tiên và câu hỏi xác nhận độ tin cậy của thư mục. Hãy chuyển khóa vào shell hoặc ~/.claude/settings.json.

Sau khi vào phiên, /status mở ra ở tab Status. Dưới đây là cách đọc thông tin, theo tài liệu về gateway (được xem ngày 3 tháng 10, 2026):

Những gì bạn thấyĐiều đó có nghĩa là
Anthropic base URL : https://api.kunavo.comCác yêu cầu thực sự được gửi tới Kunavo.
Không có dòng Anthropic base URLDòng này chỉ tồn tại khi có cổng trung gian được xác định: ANTHROPIC_BASE_URL chưa được truyền tới phiên.
Auth token chỉ đến ANTHROPIC_AUTH_TOKENKhóa Kunavo của bạn là thứ thanh toán.
Login method với tài khoản claude.aiBiến chưa được đọc: phiên đang chạy bằng gói đăng ký của bạn.

Bạn đã đăng nhập bằng gói đăng ký? Khi đó Claude Code có thể thông báo lúc khởi động rằng có hai nguồn xác thực đang hoạt động, với cảnh báo kết thúc bằng auth may not work as expected. Khóa là thứ được dùng cho các yêu cầu; /logout xóa kết nối cũ và loại bỏ cảnh báo.

Để biết sự cố đến từ Kunavo hay cấu hình của bạn, hãy kiểm tra mà không dùng Claude Code. Tài liệu đề xuất một yêu cầu chỉ giới hạn ở một token đầu ra, có chi phí chưa đến một xu. Hai lệnh bên dưới lấy địa chỉ và khóa từ shell; nếu chúng chỉ được định nghĩa trong settings.json, chúng sẽ không được nhìn thấy ở đây.

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

Một JSON bắt đầu bằng {"id":"msg_, hoặc trong PowerShell một đối tượng có id bắt đầu bằng msg_: địa chỉ và khóa hoạt động. 401: khóa bị từ chối.

Những thay đổi khi dùng khóa API

  • Remote Control và nhập liệu bằng giọng nói sẽ biến mất. Cả hai đều dựa trên tài khoản claude.ai và vẫn không khả dụng khi ANTHROPIC_AUTH_TOKEN được định nghĩa. Remote Control cũng bị tắt ngay khi ANTHROPIC_BASE_URL trỏ tới máy chủ khác với Anthropic.
  • Chế độ nhanh (/fast) hiển thị là đã tắt vì bước xác minh yêu cầu kết nối claude.ai hoặc khóa Anthropic, không phải chỉ một bearer token.
  • Tính năng tìm kiếm công cụ MCP bị tắt theo mặc định khi ANTHROPIC_BASE_URL trỏ ra ngoài Anthropic.
  • /context hiển thị các con số ước tính. Kunavo không cung cấp /v1/messages/count_tokens, nên trong trường hợp này Claude Code tính dựa trên số ký tự (tài liệu về giao thức gateway).

Đối với mọi thứ còn lại (đọc và ghi mã, công cụ, tác nhân con, máy chủ MCP, hook, bộ nhớ đệm prompt), không có gì thay đổi. Chi tiết kỹ thuật bằng tiếng Anh có trong tài liệu tích hợp Claude Code.

Thanh toán từ Pháp hoặc Bỉ

Có hai cách thanh toán cần phân biệt. Gói đăng ký Claude mua trên web chỉ có thể được thanh toán bằng thẻ tín dụng hoặc thẻ ghi nợ (Câu hỏi thường gặp về thanh toán của Anthropic, xem ngày 3 tháng 10, 2026); nếu đăng ký trong ứng dụng di động, khoản thanh toán được thực hiện qua App Store hoặc Google Play. Mức giá trên claude.com/pricing chưa bao gồm thuế.

Số dư Kunavo được nạp qua trang thanh toán Stripe. Giá được tính bằng đô la Mỹ, nhưng khi thanh toán từ Pháp hoặc Bỉ, Stripe hiển thị số tiền bằng euro với tỷ giá được đảm bảo trong 24 giờ, đã bao gồm phí chuyển đổi 2–4% do bạn chịu (tài liệu Stripe về Adaptive Pricing, được xem ngày 3 tháng 10, 2026). Bạn có thể thanh toán bằng đô la để tránh khoản phí này, nhưng khi đó ngân hàng sẽ áp dụng tỷ giá riêng; Bancontact chỉ khả dụng khi thanh toán bằng euro. Các phương thức thanh toán hiện có:

Phương thức thanh toánNó xuất hiện ở đâuBạn cần gì
Thẻ Visa hoặc MastercardỞ mọi nơiChỉ cần thẻ ghi nợ; thẻ CB đồng thương hiệu được chấp nhận như Visa hoặc Mastercard
Apple PaySafari trên Mac, iPhone và iPadThẻ được lưu trong ứng dụng Thẻ (Wallet)
Google PayChrome và AndroidGoogle Pay đã được thiết lập bằng thẻ
Liên kếtỞ mọi nơi trừ Ấn ĐộThẻ được Link, ví của Stripe, ghi nhớ
BancontactBỉ, số tiền hiển thị bằng euroỨng dụng hoặc thẻ Bancontact của ngân hàng bạn
  • Thẻ CB của Pháp? Theo tài liệu Stripe về Cartes Bancaires (được xem ngày 3 tháng 10, 2026), hơn 95% thẻ CB đồng thương hiệu với Visa hoặc Mastercard. Vì vậy, các thẻ này được xử lý tại trang thanh toán dưới dạng Visa hoặc Mastercard; thẻ ghi nợ thông thường là đủ.
  • Bancontact dành cho người mua ở Bỉ. Stripe chuyển bạn đến trang web hoặc ứng dụng Bancontact để xác nhận và kết quả được thông báo ngay lập tức (tài liệu Stripe về Bancontact, được xem ngày 3 tháng 10, 2026).
  • Pay by Bank, phương thức thanh toán qua ngân hàng trực tuyến của bạn, không khả dụng tại Pháp hoặc Bỉ: trang thanh toán chỉ hiển thị phương thức này cho người mua ở Vương quốc Anh, Ireland và Phần Lan. Tài liệu Stripe về Pay by Bank (được xem ngày 3 tháng 10, 2026) xếp phương thức này vào giai đoạn xem trước riêng tư tại Pháp và không đề cập đến Bỉ.
  • Từ Thụy Sĩ hoặc Canada, số tiền được hiển thị bằng franc Thụy Sĩ hoặc đô la Canada, với thẻ và Link, cùng Apple Pay và Google Pay, vốn sử dụng một thẻ.

Không được cung cấp: PayPal, ghi nợ trực tiếp SEPA, Klarna; Klarna chỉ dành cho người mua ở Hoa Kỳ (thanh toán bằng đô la là chưa đủ).

  1. Đăng ký Kunavo; ở giai đoạn này không yêu cầu thẻ.
  2. Trong Billing, chọn số tiền: tối thiểu $10. Các khoản tiền cao hơn được hưởng tiền thưởng (Đã thanh toán $100, đã cộng $110; Đã thanh toán $1.000, đã cộng $1.200; Đã thanh toán $5.000, đã cộng $6.250).
  3. Trên trang Stripe, chọn phương thức thanh toán; số tiền bằng euro được hiển thị trước khi xác nhận. Với Bancontact, hãy xác nhận trong ứng dụng hoặc bằng thẻ.
  4. Tạo khóa tại /app/keys và đặt khóa vào ANTHROPIC_AUTH_TOKEN.

Số dư được trả trước: không có phí hằng tháng, không có ngày hết hạn và yêu cầu thất bại không bị tính phí. Tính năng tự động nạp yêu cầu thẻ đã lưu hoặc Link. Bancontact không hỗ trợ thanh toán định kỳ trên Stripe, vì vậy mỗi lần nạp bằng Bancontact phải được thực hiện thủ công. Kunavo không phát hành hóa đơn có VAT, dù là của Pháp, Bỉ hay bất kỳ quốc gia nào khác; lịch sử nạp tiền có thể xem trong Billing. Cuối cùng, các phương thức thanh toán này chỉ dùng cho số dư API Kunavo và không thanh toán cho gói đăng ký Claude Pro hoặc Max. Tất cả các lựa chọn khác, bao gồm App Store và Google Play, được xem xét trong thanh toán Claude không cần thẻ ngân hàng.

Các lỗi thường gặp

Thông báo hoặc triệu chứngGiải thích và cách khắc phục
The token '&&' is not a valid statement separatorDòng lệnh CMD đã được dán vào PowerShell. Hãy dùng irm … | iex.
'irm' is not recognized as an internal or external command, hoặc cùng thông báo bằng tiếng PhápDòng PowerShell đã được dán vào CMD. Hãy dùng dòng install.cmd.
A parameter cannot be found that matches parameter name 'fsSL'Dòng macOS/Linux đã được dán vào Windows PowerShell, nơi curl tương ứng với Invoke-WebRequest. Hãy dùng dòng PowerShell.
'bash' is not recognized as the name of a cmdletDòng macOS/Linux đã được chạy trên Windows. Hãy dùng dòng PowerShell.
Văn bản của tập lệnh được hiển thị nhưng không có gì được cài đặtThiếu nửa sau của lệnh: | iex trong PowerShell, phần sau -o install.cmd trong CMD. Hãy sao chép lại toàn bộ dòng.
syntax error near unexpected token '<' hoặc lỗi 403Một trang web đã xuất hiện thay cho tập lệnh. Theo trang khắc phục sự cố chính thức, lỗi 403 thường nhất đến từ proxy hoặc bộ lọc mạng (mạng doanh nghiệp), hoặc từ một khu vực chưa được hỗ trợ (nếu trang nhận được hiển thị « App unavailable in region », đó là do quốc gia). Hãy kiểm tra mạng trước khi chuyển sang Homebrew hoặc WinGet: tài liệu nhắc rằng chúng liên hệ với cùng các máy chủ.
Claude Code does not support 32-bit WindowsCửa sổ đang mở là Windows PowerShell (x86). Hãy mở Windows PowerShell tiêu chuẩn.
npm.ps1 cannot be loadedChính sách thực thi của PowerShell đang chặn npm: dùng dòng Set-ExecutionPolicy ở trên hoặc trình cài đặt native.
command not found: claude, hoặc claude không được nhận dạngThư mục cài đặt không có trong PATH. Trước tiên hãy mở cửa sổ mới; trên Windows, dùng các lệnh PowerShell trong phần PATH.
Màn hình đăng nhập xuất hiện dù đã có khóaKhông có khóa nào được đọc: có lẽ khóa chỉ nằm trong cài đặt dự án. Đặt khóa trong shell hoặc ~/.claude/settings.json, rồi khởi chạy lại trong cửa sổ mới.
Cảnh báo kết thúc bằng auth may not work as expectedKhóa và kết nối cũ cùng hoạt động. Dùng /logout để giữ khóa, hoặc xóa biến để quay lại gói đăng ký.
401Khóa bị từ chối. Hãy kiểm tra khóa đầy đủ (bao gồm sk-kn-, không có khoảng trắng), khóa vẫn tồn tại trong /app/keys và được đặt đúng trong ANTHROPIC_AUTH_TOKEN.
402Số dư không đủ cho yêu cầu: hãy nạp tiền trong Billing. Một nguyên nhân khác có thể là đã chạm giới hạn chi tiêu hằng tháng được đặt trên khóa.
404Có thêm /v1 ở cuối ANTHROPIC_BASE_URL, hoặc mô hình mà Kunavo không cung cấp, thường do chưa ghim đủ bốn biến mô hình.
429 hoặc « đã đạt giới hạn »Hạn mức của gói đăng ký khi dùng gói đăng ký, giới hạn tốc độ khi dùng khóa. Chẩn đoán theo từng trường hợp: Claude Code: đã đạt giới hạn.

Bắt đầu trong một dự án

Trong một kho mã mà Claude Code khám phá, hãy bắt đầu bằng /init: công cụ sẽ duyệt mã và soạn CLAUDE.md ghi lại các lệnh kiểm thử cùng những quy ước đã phát hiện. Hãy đọc lại và rút gọn tệp này vì tệp được tải lại ở mỗi phiên. Để chuyển sang chủ đề khác, /clear bắt đầu một cuộc hội thoại mới; để tiếp tục một tác vụ dài, /compact tóm tắt lịch sử.

Các giới hạn của khóa API

  • Bạn trả tiền theo mức sử dụng, không phải gói Claude Pro hoặc Max. Nếu dùng Claude Code vài giờ mỗi ngày, mỗi ngày, gói đăng ký thường có lợi hơn; với mức sử dụng không đều, thanh toán theo token linh hoạt hơn và những tháng ít dùng không tốn phí. Xem số liệu trong giá Claude Code.
  • Không có Remote Control hay nhập liệu bằng giọng nói khi khóa đang hoạt động.
  • Năng lực của Kunavo được chia sẻ, không có hạn mức dành riêng hay cam kết theo hợp đồng; nếu cần, hãy ký hợp đồng trực tiếp với Anthropic.
  • Bancontact chỉ cho phép nạp tiền thủ công; nạp tự động phải dùng thẻ đã lưu hoặc Link.
  • Các khoản tiền bằng euro đã bao gồm phí chuyển đổi của Stripe và Kunavo không phát hành hóa đơn có VAT.

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

Cài đặt Claude Code trên Windows như thế nào?

Mở PowerShell (dấu nhắc bắt đầu bằng PS) và nhập irm https://claude.ai/install.ps1 | iex. Trong dấu nhắc lệnh thông thường (CMD), dòng lệnh khác: curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd. Không cần quyền quản trị viên hoặc WSL: Claude Code chạy trực tiếp trên Windows 10 phiên bản 1809 trở lên. Git for Windows được khuyến nghị vì cung cấp Git Bash, nhưng không bắt buộc. Sau đó đóng cửa sổ, mở một cửa sổ mới và nhập claude --version. Tránh Windows PowerShell (x86): Claude Code không hỗ trợ Windows 32 bit.

Claude Code có miễn phí không?

Cài đặt thì được, nhưng sử dụng thì không. Gói miễn phí của Claude.ai không cho phép truy cập Claude Code: bạn cần tài khoản Pro, Max, Team, Enterprise hoặc Console, hoặc API key tính phí theo mức sử dụng. Tại Kunavo, key được thanh toán bằng số dư trả trước, từ $10, không có phí hàng tháng và một tháng không viết mã cũng không tốn phí. Để biết lựa chọn nào trong hai lựa chọn có chi phí thấp hơn theo nhịp sử dụng của bạn, hãy xem giá Claude Code.

Claude Code yêu cầu phiên bản Node.js nào?

Không cần phiên bản nào với trình cài đặt native, Homebrew hoặc WinGet. Node.js chỉ cần nếu bạn dùng npm; khi đó phải dùng phiên bản 22 trở lên. Phiên bản 18 được một số hướng dẫn đề cập đã lỗi thời. Với Node.js cũ hơn, npm hiển thị cảnh báo EBADENGINE nhưng vẫn hoàn tất cài đặt vì gói cài đặt cùng một binary native. Không dùng sudo.

Cập nhật Claude Code như thế nào?

Bản cài đặt native tự cập nhật: phiên bản mới được tải xuống ở chế độ nền và áp dụng khi khởi chạy lần tiếp theo; claude update buộc cập nhật ngay. Homebrew và WinGet không tự làm việc này: brew upgrade claude-code, winget upgrade Anthropic.ClaudeCode, hoặc biến CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1. Với npm, dùng npm install -g @anthropic-ai/claude-code@latest, không dùng npm update -g.

Sử dụng Claude Code mà không cần thuê bao như thế nào?

Bằng API key. Đặt ANTHROPIC_BASE_URL=https://api.kunavo.com và ANTHROPIC_AUTH_TOKEN bằng key Kunavo của bạn: Claude Code sẽ không còn hiển thị màn hình đăng nhập và tính phí từng yêu cầu theo token trên số dư của bạn. Hai tính năng cần tài khoản claude.ai sẽ biến mất: Remote Control và đọc chính tả bằng giọng nói. Nếu bạn lập trình nhiều giờ mỗi ngày, hãy so sánh với gói thuê bao trong giá Claude Code.

Đặt API key ở đâu trong Claude Code?

Trong khối env của ~/.claude/settings.json (%USERPROFILE%\.claude\settings.json trên Windows): khối này áp dụng cho tất cả dự án và được ưu tiên hơn shell. Đặt sáu dòng: ANTHROPIC_BASE_URL=https://api.kunavo.com (không có /v1, nếu không sẽ nhận 404), ANTHROPIC_AUTH_TOKEN với key, tiếp theo là ANTHROPIC_MODEL=claude-sonnet-5, ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5, ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5 và ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5. Bốn tên mô hình này ngăn các bí danh của Claude Code, vốn chạy theo các bản phát hành mới của Anthropic, trỏ đến một mô hình mà Kunavo không cung cấp: bí danh sonnet yêu cầu Sonnet 5.5, và nếu không ghim /model sonnet, giai đoạn thực thi của opusplan cùng các subagent được thiết lập cho sonnet sẽ nhận 404. Opus 5.5 (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ơn, hãy chạy claude update. Kunavo đọc key trong cả Authorization: Bearer và x-api-key; ANTHROPIC_AUTH_TOKEN chỉ được chấp nhận mà không yêu cầu xác nhận, khác với ANTHROPIC_API_KEY. Tuyệt đối không đặt trong .claude/settings.json của dự án, vì tệp đó sẽ được đưa vào Git.

Làm thế nào biết Claude Code đang sử dụng API key của tôi?

Chạy /status. Có hai dòng xác nhận trong tab Status: Anthropic base URL, phải hiển thị https://api.kunavo.com, và Auth token, phải cho biết ANTHROPIC_AUTH_TOKEN. Dòng Login method cùng tài khoản claude.ai của bạn có nghĩa là phiên vẫn đang chạy qua gói thuê bao. Nếu Claude Code mở màn hình đăng nhập ngay khi khởi động, nghĩa là không tìm thấy key nào.

Có thể thanh toán Claude Code bằng Bancontact, PayPal hoặc ghi nợ trực tiếp SEPA không?

Có thể nạp số dư API Kunavo bằng Bancontact: Stripe Checkout cung cấp phương thức này cho người mua ở Bỉ, với số tiền bằng euro, cùng với thẻ Visa hoặc Mastercard, Apple Pay, Google Pay và Link. PayPal và ghi nợ trực tiếp SEPA thì không. Giá được tính bằng đô la; Stripe chuyển đổi sang euro với phí chuyển đổi 2 đến 4% do người mua trả. Tối thiểu $10, không có thuê bao và số dư không hết hạn. Vì tính năng tự động nạp yêu cầu thẻ đã lưu hoặc Link, mọi lần nạp bằng Bancontact đều phải thực hiện thủ công. Gói thuê bao Claude Pro hoặc Max mua trên claude.ai chỉ được thanh toán bằng thẻ.

Phải làm gì khi Claude Code hiển thị « đã đạt giới hạn »?

Bắt đầu bằng /status để biết bên nào tính phí cho phiên. Với gói thuê bao, hạn mức của gói sẽ bị tiêu hao. Với key Kunavo, mã HTTP sẽ quyết định: 402 là số dư không đủ hoặc đã đạt giới hạn chi tiêu hàng tháng, 401 là key bị từ chối, 429 là giới hạn tốc độ. Lưu ý: chỉ có ANTHROPIC_BASE_URL, không có ANTHROPIC_AUTH_TOKEN, thì phiên vẫn sử dụng kết nối claude.ai của bạn. Tất cả trường hợp được trình bày chi tiết trong Claude Code: đã đạt giới hạn.