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 13 phút

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

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

Claude Code được cài đặt bằng một lệnh chính thức cho từng hệ thống: trên macOS, Linux và WSL, dùng curl -fsSL https://claude.ai/install.sh | bash; trên Windows, trong PowerShell, dùng irm https://claude.ai/install.ps1 | iex (trong Command Prompt, tức CMD, dùng dòng lệnh install.cmd ở bên dưới). Sau đó có hai cách sử dụng. Với gói đăng ký, đăng nhập bằng tài khoản Pro, Max, Team, Enterprise hoặc Console (người chỉ có gói miễn phí của Claude.ai không có quyền truy cập Claude Code). Không có gói đăng ký thì dùng khóa API: thiết lập ANTHROPIC_BASE_URL (chỉ tên miền, không có /v1), ANTHROPIC_AUTH_TOKEN và bốn biến mô hình, rồi xác nhận bằng /status. Có thể nạp số dư Kunavo bằng MB WAY tại trang thanh toán bằng euro, từ US$ 10, không có phí hằng tháng.

Các lệnh và biến đã được kiểm tra vào 3 tháng 10, 2026 trong tài liệu cài đặt Claude Code chính thức và tài liệu về biến môi trường; giá và phương thức thanh toán được kiểm tra vào 10 tháng 10, 2026. Bồ Đào Nha nằm trong danh sách quốc gia được Anthropic hỗ trợ (được tra cứu vào 3 tháng 10, 2026), cho cả Claude.ai và API. Hướng dẫn này cũng có bằng tiếng Anh: Cài đặt Claude Code.

Trước khi cài đặt

Thành phầnYêu cầu (tài liệu cài đặt chính thức, tham khảo ngày 3 tháng 10, 2026)
Hệ điều hànhmacOS 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ứngRAM từ 4 GB trở lên, bộ xử lý x64 hoặc ARM64 (không hỗ trợ Windows 32 bit)
ShellBash, Zsh, PowerShell hoặc CMD
Mạng và vị tríKết nối Internet tại một quốc gia được Anthropic hỗ trợ (Bồ Đào Nha có trong danh sách)
Tài khoảnĐể đăng nhập: Pro, Max, Team, Enterprise hoặc Console (gói miễn phí của Claude.ai không đủ). Với khóa API thì không có gói đăng ký, cũng không có bước đăng nhập.
Node.jsChỉ cần khi cài đặt bằng npm, và khi đó cần phiên bản 22 trở lên; trình cài đặt native không cần đến nó

macOS, Linux và WSL: chỉ một dòng lệnh

Trong Terminal (trên macOS, nằm trong Ứng dụng › Tiện ích), hãy chạy:

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

Đây là cách cài đặt native được khuyến nghị: một chương trình độc lập mà theo tài liệu chính thức sẽ tự cập nhật trong nền. Lệnh claude nằm trong ~/.local/bin. Một terminal đã mở từ trước chưa biết PATH mới, vì vậy hãy mở một cửa sổ mới trước khi thử. Trong WSL, dòng lệnh vẫn hoàn toàn giống như vậy, được chạy bên trong terminal WSL.

Cài đặt trên Windows

Trên Windows có hai dòng lệnh, và việc lựa chọn chỉ phụ thuộc vào cửa sổ đang mở. Nếu dòng dấu nhắc bắt đầu bằng PS C:\Users\Nome>, bạn đang ở PowerShell; nếu chỉ hiện C:\Users\Nome>, không có PS, bạn đang ở Command Prompt (CMD). Không cần dùng “Chạy với tư cách quản trị viên”: tài liệu chính thức nói rõ là việc đó không cần thiết, trái với khuyến nghị của một số hướng dẫn bằng tiếng Bồ Đào Nha.

PowerShell
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
cmd.exe
:: Linha de Comandos do Windows (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Trên Windows, chỗ vấp thường gặp nhất là nhầm cửa sổ. Nếu PowerShell báo The token '&&' is not a valid statement separator, nó đã nhận dòng lệnh của CMD; nếu CMD báo 'irm' is not recognized as an internal or external command, nó đã nhận dòng lệnh của PowerShell. Trên Windows tiếng Bồ Đào Nha, thông báo thứ hai này có thể xuất hiện ở dạng đã dịch, với cùng nguyên nhân. Còn dòng lệnh của macOS, có | bash, khi dán vào PowerShell sẽ gây ra lỗi báo rằng bash không được nhận diện. Trong cả ba trường hợp, cách khắc phục là dùng dòng lệnh tương ứng với cửa sổ.

Git for Windows là tùy chọn. Khi cài đặt, công cụ Bash của Claude Code sẽ chạy trong Git Bash, còn PowerShell vẫn dùng được song song; nếu không có Git Bash, tất cả lệnh sẽ chạy qua PowerShell. Nếu Git được cài trong một thư mục khác vị trí thông thường và Claude Code không tìm thấy bash.exe, hãy chỉ định đường dẫn tại CLAUDE_CODE_GIT_BASH_PATH, trong khối env của ~/.claude/settings.json; ví dụ trong tài liệu là C:\Program Files\Git\bin\bash.exe.

Tùy chọnCần những gìMôi trường cách lyKhi nào nên chọn
Windows nativeKhông có; Git for Windows là tùy chọnKhông được hỗ trợDự án và công cụ chạy trực tiếp trên Windows
WSL 2Đã bật WSL 2Được hỗ trợKhi cần công cụ Linux hoặc lệnh chạy trong sandbox
WSL 1Đã bật WSL 1Không được hỗ trợKhi WSL 2 không khả dụng

Vì vậy, WSL là một lựa chọn chứ không phải một yêu cầu, trái với những gì một số hướng dẫn viết. Ai chọn WSL thì chạy dòng lệnh của macOS/Linux trong terminal WSL và cũng khởi chạy claude tại đó, không phải từ PowerShell hay CMD.

Thông qua Homebrew, WinGet hoặc npm

Cách này cũng hoạt động, với một điểm khác biệt quan trọng: theo tài liệu chính thức, các bản cài đặt qua Homebrew và WinGet không tự cập nhật. Việc cập nhật phải thực hiện thủ công. Ngoài ra còn có các kho apt, dnf và apk có chữ ký dành cho Linux.

# Homebrew
brew install --cask claude-code
brew upgrade claude-code              # não se atualiza sozinho

# WinGet (Windows)
winget install Anthropic.ClaudeCode
winget upgrade Anthropic.ClaudeCode   # não se atualiza sozinho

Gói npm yêu cầu Node.js 22 trở lên — không phải Node.js 18 mà một số hướng dẫn vẫn còn ghi. Với Node.js cũ hơn, npm chỉ hiển thị một cảnh báo EBADENGINE trong lúc cài đặt, thay vì thất bại. Không bao giờ dùng sudo npm install -g: tài liệu chính thức khuyến cáo rõ ràng là không nên dùng lệnh này. Để cập nhật, hãy dùng @latest, không dùng npm update -g.

Terminal
node -v                                           # tem de ser v22 ou posterior
npm install -g @anthropic-ai/claude-code          # nunca com sudo

# para atualizar mais tarde: com @latest, não com npm update -g
npm install -g @anthropic-ai/claude-code@latest

Xác nhận việc cài đặt

claude --version   # mostra o número da versão, seguido de (Claude Code)
claude doctor      # diagnóstico só de leitura da instalação e das definições, sem abrir sessão

claude doctor không đăng nhập vào bất kỳ tài khoản nào: lệnh này hiển thị trạng thái cài đặt và các tệp cấu hình. Đây là cách nhanh nhất để xác định vấn đề nằm ở việc cài đặt hay cấu hình.

Thông báo command not found: claude (hoặc trên Windows, thông báo cho biết claude không phải là lệnh đã biết) có nghĩa là terminal không biết chương trình được cài ở đâu. Thường chỉ cần đóng cửa sổ rồi mở cửa sổ mới. Nếu vẫn không được, thư mục chưa có trong PATH: trên macOS và Linux, đó là ~/.local/bin, cần được thêm vào tệp khởi động shell (~/.zshrc hoặc ~/.bashrc); trên Windows, đó là %USERPROFILE%\.local\bin. Theo hướng dẫn khắc phục sự cố chính thức, hãy kiểm tra và thêm đường dẫn trong PowerShell như sau:

PowerShell
# 1. A pasta de instalação já está no PATH?
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Sem resultado? Acrescente-a ao PATH do utilizador e abra uma janela nova
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. Na janela nova: dois caminhos significam duas instalações lado a lado
where.exe claude

Nếu bạn đã cài đặt bằng npm và PowerShell báo npm.ps1 cannot be loaded because running scripts is disabled on this system, thì đó là do chính sách thực thi của PowerShell đang chặn các tập lệnh của npm. Hãy dùng trình cài đặt native hoặc cho phép tập lệnh cục bộ đối với tài khoản người dùng của bạn:

PowerShell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Còn nếu xuất hiện Claude Code does not support 32-bit Windows thì bạn đã mở “Windows PowerShell (x86)”. Windows có hai mục PowerShell và phiên bản x86 chạy dưới dạng tiến trình 32 bit; hãy mở mục “Windows PowerShell”, không có (x86).

Lần sử dụng đầu tiên: gói đăng ký hoặc khóa API

Ở lần khởi động đầu tiên, bạn quyết định cách thanh toán cho Claude Code. Không cần cài đặt lại để đổi cách: điều quyết định là có khóa nào được thiết lập hay không.

Cách A: đăng nhập bằng gói đăng kýCách B: khóa API, không cần gói đăng ký
Cần những gìTài khoản Pro, Max, Team, Enterprise hoặc ConsoleMột khóa Kunavo bắt đầu bằng sk-kn-
Thanh toán như thế nàoPro và Max: mức phí cố định, theo tháng hoặc theo năm; Console: trả cho Anthropic theo từng tokenThanh toán theo từng token từ số dư trả trước; không có phí hằng tháng
Phương thức thanh toánPro và Max mua trên trang web: chỉ thẻ tín dụng hoặc thẻ ghi nợMB WAY, thẻ, Apple Pay, Google Pay hoặc Link
Remote Control và nhập văn bản bằng giọng nóiCó sẵn với tài khoản claude.ai (Pro, Max, Team, Enterprise); không có sẵn với tài khoản ConsoleKhông có sẵn
Cấu hìnhĐăng nhập trên trình duyệtSáu biến môi trường

Cách A — đăng nhập bằng gói đăng ký

Trong thư mục dự án, chạy claude và đăng nhập trên trình duyệt. Lưu ý với những ai đã có ANTHROPIC_API_KEY trong môi trường: thay vì mở trình duyệt, Claude Code yêu cầu phê duyệt khóa đó một lần duy nhất. Nếu việc phê duyệt đó bị từ chối, khóa sẽ bị bỏ qua từ đó về sau, câu hỏi không lặp lại, và trông như thể biến không được đọc. Để kích hoạt lại khóa: /config → Use custom API key.

Cách B — không cần gói đăng ký, dùng khóa API

ANTHROPIC_BASE_URL là một biến của chính Claude Code, được thiết kế để định tuyến các yêu cầu qua proxy hoặc gateway. Vì vậy, trỏ biến này tới một endpoint tương thích với Messages API của Anthropic là một cấu hình được hỗ trợ, không cần plugin hay phiên bản đã chỉnh sửa. Các bước:

  1. Tạo tài khoản Kunavo.
  2. Nạp số dư trong mục Thanh toán, từ US$ 10 (cách thanh toán bằng MB WAY được giải thích ở bên dưới).
  3. Tại /app/keys, tạo một khóa bắt đầu bằng sk-kn-. Khóa chỉ được hiển thị một lần, vì vậy nên lưu lại ngay.
  4. Thiết lập các biến. Trên macOS và Linux, trong ~/.zshrc hoặc ~/.bashrc:
~/.zshrc
export ANTHROPIC_BASE_URL=https://api.kunavo.com   # só o domínio, sem /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

Trên Windows, để thử trước trong một cửa sổ PowerShell:

PowerShell
# Vale só para esta janela do 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

Để sử dụng cố định, nơi tốt nhất là khối env trong phần cài đặt người dùng: ~/.claude/settings.json (trên Windows là %USERPROFILE%\.claude\settings.json). Tại đó, các giá trị áp dụng cho mọi dự án, kể cả các agent chạy nền; tiện ích mở rộng VS Code là ngoại lệ (xem bên dưới). Một biến được export trong shell chỉ đến được những chương trình khởi chạy từ shell đó: một trình soạn thảo mở từ Dock hoặc từ menu Start sẽ không thấy biến này. Nếu tệp đã có các cài đặt khác, 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"
  }
}

Đừng bao giờ đặt khóa trong .claude/settings.json của dự án: theo tài liệu gateway chính thức (được tra cứu vào 3 tháng 10, 2026), tệp này được đưa vào các commit và chia sẻ với bất kỳ ai sao chép kho lưu trữ. Cũng cần lưu ý thứ tự ưu tiên: khi shell và một tệp cài đặt cùng đặt một biến, giá trị trong tệp cài đặt sẽ được ưu tiên. Nếu thay đổi trong shell không có tác dụng, trước tiên hãy kiểm tra settings.json.

Ai dùng tiện ích mở rộng VS Code thì thiết lập các biến trong claudeCode.environmentVariables, thuộc phần cài đặt người dùng của chính VS Code (lệnh Preferences: Open User Settings (JSON)). Theo tài liệu về gateway, tiện ích mở rộng kiểm tra thông tin xác thực trong mục cài đặt này trước khi khởi động; các giá trị trong ~/.claude/settings.json đến được tiến trình Claude Code, nhưng không đến được bước kiểm tra đó:

VS Code settings.json
{
  "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" }
  ]
}

Bốn biến mô hình và những cạm bẫy khác

Mỗi dòng trong khối đều có cạm bẫy riêng:

  • Không đưa đường dẫn vào ANTHROPIC_BASE_URL. Đường dẫn /v1/messages do chính Claude Code tự thêm vào; một địa chỉ đã kết thúc bằng /v1 sẽ thành /v1/v1/messages, và đường dẫn đó trả về 404.
  • ANTHROPIC_AUTH_TOKEN hoặc ANTHROPIC_API_KEY: Kunavo chấp nhận cả hai. Theo tài liệu về gateway, ANTHROPIC_AUTH_TOKEN được gửi trong tiêu đề Authorization: Bearer và có hiệu lực ngay; ANTHROPIC_API_KEY được gửi trong tiêu đề x-api-key và, trong chế độ tương tác, phải được phê duyệt một lần trước khi có hiệu lực (xem Cách A). Vì vậy hướng dẫn này sử dụng ANTHROPIC_AUTH_TOKEN.
  • Tên trong ANTHROPIC_MODEL phải hoàn toàn chính xác. Hãy sao chép đúng như hiển thị ở đây: claude-sonnet-5.
  • Nếu không thiết lập ANTHROPIC_DEFAULT_SONNET_MODEL và ANTHROPIC_DEFAULT_OPUS_MODEL, các bí danh sẽ tự thay đổi. Theo tài liệu cấu hình mô hình (được tra cứu vào 3 tháng 10, 2026), với người dùng API của Anthropic, bí danh opus trỏ đến Opus 5.5 và bí danh sonnet trỏ đến Sonnet 5.5; các bí danh này thay đổi khi có phiên bản mới. Có thể cố định bằng tên mô hình đầy đủ hoặc bằng các biến như ANTHROPIC_DEFAULT_OPUS_MODEL. Kunavo không cung cấp Sonnet 5.5; mô hình không tồn tại sẽ trả về lỗi 404. Nếu không có ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5, các mục sau sẽ gặp lỗi: /model sonnet, tác nhân con dùng model: sonnet và bước thực thi của opusplan. Trong khi đó, opus trỏ đến claude-opus-5-5, mô hình được Kunavo cung cấp, nhưng chỉ từ phiên bản Claude Code v2.1.280 trở lên; nếu đang dùng phiên bản cũ hơn, hãy chạy claude update.
  • Cũng hãy đặt ANTHROPIC_DEFAULT_HAIKU_MODEL. Bí danh haiku yêu cầu một ID mà Kunavo không cung cấp: kể từ v2.1.293 là Haiku 5.5, còn trước đó là một ID Haiku 4.5 có kèm ngày. Nếu thiếu dòng này, /model haiku và các tác tử phụ dùng model: haiku sẽ trả về lỗi 404.
  • ANTHROPIC_DEFAULT_HAIKU_MODEL cũng áp dụng cho các tác vụ nền. Theo tài liệu, biến này xác định bí danh haiku và mô hình cho các chức năng nền của Claude Code. Với Claude Haiku 4.5, các lệnh gọi này dùng mô hình rẻ nhất trong bảng bên dưới.

Giá mỗi triệu token lấy từ danh mục Kunavo; cột Anthropic lấy từ claude.com/pricing (được tra cứu vào 3 tháng 10, 2026):

Mô hìnhKunavo (đầu vào / đầu ra)Giá niêm yết của Anthropic (đầu vào / đầu ra)Chênh lệchDùng để làm gì
claude-haiku-4-5US$ 0,70 / US$ 3,50US$ 1,00 / US$ 5,00rẻ hơn khoảng 30%Các tác vụ nền của chính Claude Code và công việc đơn giản
claude-sonnet-5US$ 1,40 / US$ 7,00US$ 2,00 / US$ 10,00rẻ hơn khoảng 30%Mô hình mặc định cho công việc hằng ngày
claude-opus-5-5US$ 2,80 / US$ 14,00US$ 4,00 / US$ 20,00rẻ hơn khoảng 30%Tái cấu trúc lớn và lập kế hoạch

Trong một phiên, bạn đổi mô hình bằng /model claude-opus-5-5, hoặc khởi động ngay với claude --model claude-opus-5-5. Phép tính bằng euro, kèm các ví dụ về mức sử dụng hằng tháng và điểm mà từ đó gói đăng ký có lợi hơn, nằm trong Giá Claude Code bằng euro; mức tiêu thụ của mỗi người được tính bằng công cụ tính chi phí token. Tất cả mô hình và giá đều có trên trang giá.

Xác nhận bằng /status

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

Trong phiên làm việc, nhập /status và tìm hai dòng trong thẻ Status (nguồn: tài liệu gateway chính thức, được tra cứu vào 3 tháng 10, 2026):

  • Anthropic base URL phải hiển thị https://api.kunavo.com. Dòng này chỉ xuất hiện khi có địa chỉ gateway được thiết lập; nếu thiếu dòng này thì ANTHROPIC_BASE_URL đã không đến được phiên.
  • Dòng Auth token phải ghi ANTHROPIC_AUTH_TOKEN. Nếu thay vào đó xuất hiện Login method kèm theo một tài khoản claude.ai thì biến chưa được đọc và phiên đang dùng gói đăng ký.

Ai trước đó đã đăng nhập bằng gói đăng ký thì khi khởi động có thể thấy một cảnh báo rằng có hai thông tin xác thực đang hoạt động (thông báo kết thúc bằng auth may not work as expected). Các yêu cầu được gửi qua khóa; /logout xóa lần đăng nhập cũ.

Để kiểm tra địa chỉ và khóa trước khi mở Claude Code, tài liệu gợi ý gửi một yêu cầu chỉ xin một token đầu ra, tiêu tốn một phần cực nhỏ của số dư. Các lệnh đọc các biến của shell, vì vậy hãy thiết lập chúng cả ở đó, ngay cả khi chúng đã có trong settings.json.

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 phản hồi JSON bắt đầu bằng {"id":"msg_ có nghĩa là địa chỉ và khóa hoạt động; trong PowerShell sẽ xuất hiện một id bắt đầu bằng msg_. 401 có nghĩa là khóa không được nhận diện.

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

  • Không có Remote Control, cũng không có nhập văn bản bằng giọng nói. Theo tài liệu về gateway, hai tính năng này không khả dụng khi ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN hoặc một apiKeyHelper đang hoạt động; Remote Control cũng bị tắt khi ANTHROPIC_BASE_URL trỏ tới một địa chỉ bên ngoài Anthropic.
  • /fast hiển thị chế độ nhanh là đã bị vô hiệu hóa. Khi chỉ có bearer token, Claude Code coi chế độ nhanh là đã tắt.
  • Tính năng tìm kiếm công cụ MCP (MCP tool search) được tắt theo mặc định khi ANTHROPIC_BASE_URL trỏ đến một địa chỉ bên ngoài Anthropic (tài liệu về biến môi trường, được tra cứu vào 3 tháng 10, 2026).
  • Các con số của /context chỉ là ước tính. Kunavo không cung cấp /v1/messages/count_tokens và theo tài liệu về khả năng tương thích với gateway (đã kiểm tra vào 3 tháng 10, 2026), nếu không có endpoint này, Claude Code sẽ dùng ước tính dựa trên số ký tự.

Phần còn lại — mã, công cụ, subagent, máy chủ MCP, hook và prompt caching — vẫn hoạt động như thường lệ. Xem thêm chi tiết trong tài liệu tích hợp Claude Code (bằng tiếng Anh) và trong Claude Code không cần gói đăng ký (bằng tiếng Anh).

Nạp số dư bằng MB WAY

Trước tiên là gói đăng ký: gói Claude mua trên trang web chỉ có thể thanh toán bằng thẻ tín dụng hoặc thẻ ghi nợ (bài viết trợ giúp của Anthropic về các gói trả phí, đã kiểm tra vào 3 tháng 10, 2026); với gói đăng ký mua trong ứng dụng Claude dành cho iOS hoặc Android, phương thức thanh toán là các phương thức của App Store hoặc Google Play. Các phương thức thanh toán của Kunavo, bao gồm MB WAY, không thể dùng để thanh toán Claude Pro hoặc Max: chúng nạp số dư API Kunavo, là phương thức được dùng cho Tuyến B.

Số dư được nạp tại trang thanh toán Stripe. Giá được tính bằng đô la Mỹ; với người mua ở Bồ Đào Nha, Stripe hiển thị số tiền bằng euro. Theo tài liệu của Stripe về Adaptive Pricing (đã kiểm tra vào 3 tháng 10, 2026), việc chuyển đổi này bao gồm phí 2–4% do người mua trả; người chọn thanh toán bằng đô la (qua thẻ, Apple Pay, Google Pay hoặc Link) không phải trả khoản phí này, dù ngân hàng có thể áp dụng tỷ giá hối đoái và các khoản phí riêng. MB WAY chỉ hoạt động với euro. Khi thanh toán bằng euro, bạn sẽ thấy:

  • MB WAY. Chọn MB WAY, nhập số điện thoại di động rồi xác nhận giao dịch mua trong ứng dụng MB WAY thông qua thông báo hoặc trong mục hoạt động (Stripe về MB WAY và MB WAY về giao dịch mua trực tuyến, đã kiểm tra vào 3 tháng 10, 2026). Theo Stripe, chấp nhận số điện thoại quốc tế, nhưng phần lớn khách hàng dùng số điện thoại Bồ Đào Nha bắt đầu bằng +351.
  • Thẻ (Visa, Mastercard), Apple Pay, Google Pay và Link.

Không có: mã tham chiếu Multibanco (thanh toán bằng đơn vị thu và mã tham chiếu), PayPal, ghi nợ trực tiếp SEPA và Klarna, vốn chỉ hiển thị với người mua ở Hoa Kỳ. Việc chuyển đổi sang euro dùng Adaptive Pricing của Stripe; danh sách phương thức thanh toán mà dịch vụ này cung cấp có MB WAY nhưng không có Multibanco. MB WAY cũng cho phép tạo thẻ ảo MB NET để mua hàng trực tuyến (MB WAY về MB NET, đã kiểm tra vào 3 tháng 10, 2026); chưa xác nhận được rằng trường thẻ tại trang thanh toán chấp nhận loại thẻ này, vì vậy cách an toàn là chọn trực tiếp MB WAY.

Những gì Stripe ghi trong tài liệu về MB WAY (tham khảo ngày 3 tháng 10, 2026):

  • Mỗi lần thanh toán: từ 0,50 € đến 5.000 €.
  • Mỗi ngày: mặc định 1000 €, có thể điều chỉnh lên đến 10.000 € trong ứng dụng MB WAY. Các khoản nạp lớn hơn có thể vượt hạn mức hằng ngày mặc định; khi đó, hãy tăng hạn mức trong ứng dụng trước khi thanh toán. Hãy so sánh số tiền bằng euro mà trang thanh toán hiển thị với các hạn mức này.
  • Thanh toán định kỳ: không được hỗ trợ.
  • Trên sao kê sẽ hiển thị tên Stripe (Stripe Inc), cùng với số tiền giao dịch.
  1. Tạo tài khoản Kunavo.
  2. Trong Thanh toán, chọn số tiền từ US$ 10 trở lên. Các khoản nạp lớn hơn được cộng thêm số dư: người nạp US$ 100 sẽ nhận US$ 110; người nạp US$ 1000 sẽ nhận US$ 1200; người nạp US$ 5000 sẽ nhận US$ 6250.
  3. Trên trang thanh toán Stripe, với số tiền bằng euro, chọn MB WAY, nhập số điện thoại di động và xác nhận giao dịch mua trong ứng dụng MB WAY. Số tiền bằng euro hiển thị trước khi xác nhận.
  4. Tại /app/keys, tạo khóa và đặt khóa vào ANTHROPIC_AUTH_TOKEN.

Số dư được trả trước: không có phí hằng tháng, số dư không hết hạn và các yêu cầu thất bại không bị tính phí. Nạp tiền tự động chỉ hoạt động với thẻ đã lưu hoặc với Link; với MB WAY thì luôn phải nạp thủ công, vì theo Stripe, MB WAY không chấp nhận thanh toán định kỳ và cũng không được lưu lại cho các lần thanh toán sau. Kunavo không xuất hóa đơn, dù là hóa đơn có mã số thuế (NIF) hay có VAT; lịch sử nạp tiền nằm trong mục Thanh toán. Các phương thức thanh toán này chỉ nạp số dư API của Kunavo. Xem thêm về chủ đề này trong Thanh toán Claude bằng MB WAY.

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

Hiển thịNguyên nhân và cách khắc phục
The token '&&' is not a valid statement separatorDòng lệnh của CMD bị 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 Bồ Đào Nha)Dòng lệnh của PowerShell bị dán vào CMD. Hãy dùng dòng lệnh install.cmd.
'bash' is not recognized as the name of a cmdletPowerShell đã nhận dòng lệnh có | bash, vốn dành cho macOS, Linux và WSL. Trong PowerShell, dòng lệnh đúng là dòng install.ps1.
Lệnh hiển thị nội dung tập lệnh nhưng không cài đặt gìLệnh bị cắt khi dán: irm chỉ tải tập lệnh về, còn thứ chạy tập lệnh là | iex. Trong CMD, thường thiếu phần -o install.cmd && install.cmd.
syntax error near unexpected token '<' hoặc 403Lần tải xuống đã trả về một trang web hoặc một mã lỗi thay vì tập lệnh. Theo hướng dẫn khắc phục sự cố chính thức (tham khảo ngày 3 tháng 10, 2026), một trang ghi “App unavailable in region” có nghĩa là Claude Code không khả dụng tại quốc gia đó (Bồ Đào Nha có trong danh sách). Một lỗi 403 đơn thuần cũng có thể đến từ proxy hoặc tường lửa của công ty: ở một quốc gia được hỗ trợ, hãy kiểm tra mạng trước (nếu ở sau proxy, hãy thiết lập HTTPS_PROXY và HTTP_PROXY), vì Homebrew và WinGet kết nối tới cùng các máy chủ đó. Ngoài trường hợp đó, có thể là do mạng, định tuyến theo khu vực hoặc một sự cố tạm thời: hãy thử lại sau, hoặc cài đặt qua Homebrew trên macOS và qua WinGet trên Windows.
Claude Code does not support 32-bit WindowsBạn đã mở Windows PowerShell (x86). Hãy mở Windows PowerShell thông thường.
npm.ps1 cannot be loadedChính sách thực thi của PowerShell chặn npm. Hãy chạy dòng lệnh Set-ExecutionPolicy hoặc dùng trình cài đặt native.
command not found: claude, hoặc claude không được nhận diệnTerminal không tìm thấy chương trình. Hãy đóng rồi mở lại cửa sổ; nếu lỗi vẫn còn, hãy thêm thư mục vào PATH (trên Windows, dùng khối lệnh ở trên).
Màn hình đăng nhập xuất hiện dù đã thiết lập khóaClaude Code chưa đọc được khóa. Hãy thiết lập các biến trong shell hoặc trong ~/.claude/settings.json, không chỉ trong phần cài đặt của dự án, rồi mở một cửa sổ mới.
Cảnh báo kết thúc bằng auth may not work as expectedKhóa và một lần đăng nhập cũ đang hoạt động cùng lúc. Hãy dùng /logout để chỉ giữ lại khóa, hoặc gỡ bỏ biến để quay lại gói đăng ký.
401Khóa không được nhận diện: hãy xác nhận rằng bạn đã sao chép đầy đủ khóa sk-kn-, không có khoảng trắng, rằng khóa chưa bị xóa trong /app/keys và rằng khóa nằm trong một biến có tên đúng, chẳng hạn ANTHROPIC_AUTH_TOKEN.
404ANTHROPIC_BASE_URL kết thúc bằng /v1, mô hình được yêu cầu không tồn tại trên Kunavo, hoặc /model sonnet đã được dùng mà không có ANTHROPIC_DEFAULT_SONNET_MODEL.

Sau khi cài đặt

Ở lần khởi động đầu tiên trong một dự án, hãy nhập /init: Claude Code duyệt qua kho mã và viết một tệp CLAUDE.md ghi lại những gì nó suy ra được: cách chạy dự án, cách kiểm thử các thay đổi, dự án tuân theo những quy tắc phong cách nào. Hãy xem lại tệp này và giữ cho nó ngắn gọn, vì nó được tải trong mọi phiên. Giữa các tác vụ độc lập, /clear bắt đầu một cuộc trò chuyện mới; trong một tác vụ dài, /compact tóm tắt lịch sử để tiếp tục.

Những điều cần biết

  • Đây là một API tính phí theo token, không phải gói đăng ký Claude Pro hoặc Max. Ai dùng Claude Code nhiều giờ mỗi ngày thường trả ít hơn với gói đăng ký; trả theo token có lợi khi mức sử dụng không đều, và một tháng không dùng thì không tốn gì. Phần so sánh bằng euro có trong Giá Claude Code bằng euro.
  • Người dùng khóa API không thể sử dụng Remote Control và tính năng nhập văn bản bằng giọng nói.
  • Qua Kunavo, bạn sử dụng công suất dùng chung, không có hạn mức dành riêng và không có bảo đảm theo hợp đồng; ai cần những điều đó nên ký hợp đồng trực tiếp với Anthropic.
  • MB WAY chỉ dùng để nạp tiền thủ công; nạp tiền tự động yêu cầu thẻ hoặc Link.
  • Các số tiền bằng euro hiển thị trên trang thanh toán đã bao gồm phí chuyển đổi của Stripe.

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

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

Bằng một lệnh chính thức cho từng hệ điều hành. Trên macOS, Linux và WSL: curl -fsSL https://claude.ai/install.sh | bash. Trên Windows, trong PowerShell: irm https://claude.ai/install.ps1 | iex. Trong Dòng lệnh Windows (CMD): curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd. Đây là cách cài đặt native được Anthropic khuyến nghị và tự cập nhật trong nền. Sau đó, mở một cửa sổ terminal mới, xác nhận bằng claude --version và bắt đầu với claude.

Có cần WSL hoặc quyền quản trị viên để cài đặt Claude Code trên Windows không?

Không cần cả hai. Theo tài liệu cài đặt chính thức, lệnh chạy trong PowerShell hoặc Dòng lệnh (CMD) mà không cần mở cửa sổ với quyền quản trị viên. Git for Windows là tùy chọn: nếu đã cài đặt, Claude Code chạy lệnh qua Git Bash; nếu không, qua PowerShell. WSL 2 phù hợp khi dự án phụ thuộc vào các công cụ Linux hoặc bạn muốn chạy lệnh trong sandbox; trong trường hợp đó, Claude Code được cài đặt và khởi chạy bên trong terminal WSL. Không sử dụng Windows PowerShell (x86): Claude Code không hỗ trợ Windows 32 bit.

Có cần Node.js để cài đặt Claude Code không?

Chỉ khi cài đặt bằng npm, và khi đó cần Node.js 22 trở lên — không phải bản 18 mà một số hướng dẫn vẫn còn đề cập. Trình cài đặt native, Homebrew và WinGet không cần Node.js. Với Node.js cũ hơn, npm chỉ hiển thị cảnh báo EBADENGINE và quá trình cài đặt vẫn tiếp tục. Không bao giờ dùng sudo npm install -g; hãy cập nhật bằng npm install -g @anthropic-ai/claude-code@latest thay vì npm update -g.

Có thể sử dụng Claude Code mà không cần gói đăng ký Pro hoặc Max không?

Có. Đăng nhập yêu cầu tài khoản trả phí (Pro, Max, Team hoặc Enterprise) hoặc tài khoản Console; gói miễn phí của Claude.ai không được hỗ trợ. Khi không có gói đăng ký, hãy đặt ANTHROPIC_BASE_URL=https://api.kunavo.com và ANTHROPIC_AUTH_TOKEN bằng khóa Kunavo: Claude Code sẽ bỏ qua bước đăng nhập và tính phí theo token, từ số dư trả trước có thể nạp từ US$ 10, không có phí hàng tháng. Với cách này, bạn mất hai chức năng: Remote Control và nhập văn bản bằng giọng nói.

Cấu hình khóa API của Claude Code ở đâu: trong settings.json hay PowerShell?

Để sử dụng cố định, trong khối env của ~/.claude/settings.json (trên Windows là %USERPROFILE%\.claude\settings.json). Để kiểm tra, dùng $env:ANTHROPIC_AUTH_TOKEN trong một cửa sổ PowerShell, chỉ có hiệu lực với cửa sổ đó, hoặc dùng export trong ~/.zshrc hay ~/.bashrc. Không bao giờ đặt trong .claude/settings.json của dự án, vì tệp này sẽ được đưa vào các commit của repository. Nếu shell và tệp cài đặt chứa cùng một biến, tệp cài đặt sẽ được ưu tiên. Kunavo chấp nhận khóa trong cả ANTHROPIC_AUTH_TOKEN (tiêu đề Authorization: Bearer, có hiệu lực ngay) và ANTHROPIC_API_KEY (tiêu đề x-api-key, trong chế độ tương tác yêu cầu phê duyệt một lần); hướng dẫn này sử dụng ANTHROPIC_AUTH_TOKEN. ANTHROPIC_BASE_URL chỉ chứa miền, https://api.kunavo.com, không có /v1.

Tại sao /model sonnet trả về lỗi 404?

Vì bí danh sonnet của Claude Code yêu cầu Sonnet 5.5, mô hình mà Kunavo không cung cấp. Theo tài liệu cấu hình mô hình (tham khảo ngày 3 tháng 10, 2026), đối với người dùng API của Anthropic, các bí danh đi theo những mô hình mới nhất: opus trỏ tới Opus 5.5 và sonnet trỏ tới Sonnet 5.5. Với ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5, cùng với ANTHROPIC_MODEL=claude-sonnet-5, ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5 và ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5, mỗi yêu cầu đều dùng một mô hình mà Kunavo cung cấp, kể cả các subagent và bước thực thi của opusplan. Opus 5.5 yêu cầu Claude Code v2.1.280 trở lên (cập nhật bằng claude update). Lỗi 404 thường gặp còn lại là một ANTHROPIC_BASE_URL kết thúc bằng /v1, tạo ra /v1/v1/messages.

Làm sao tôi biết Claude Code đang dùng khóa chứ không phải gói đăng ký?

Nhập /status trong Claude Code. Trong tab Status, dòng Anthropic base URL phải hiển thị https://api.kunavo.com và dòng Auth token phải ghi ANTHROPIC_AUTH_TOKEN. Nếu xuất hiện Login method kèm theo một tài khoản claude.ai thì biến chưa được đọc và phiên đang dùng gói đăng ký. Nếu Claude Code yêu cầu đăng nhập ngay khi khởi động thì nó chưa đọc được khóa nào.

Tôi có thể thanh toán cho Claude Code bằng MB WAY không?

Có thể nạp số dư API Kunavo: MB WAY có sẵn trên trang thanh toán Stripe khi trang này hiển thị số tiền bằng euro. Chọn MB WAY, nhập số điện thoại di động và xác nhận giao dịch mua trong ứng dụng MB WAY. Theo Stripe, mỗi khoản thanh toán MB WAY nằm trong khoảng từ 0,50 € đến 5000 €, và hạn mức hằng ngày mặc định là 1000 € có thể được tăng lên đến 10.000 € trong ứng dụng. Việc chuyển đổi từ đô la sang euro bao gồm phí 2–4%, mức nạp tối thiểu là US$ 10 và không có phí hằng tháng. MB WAY chỉ dùng để nạp tiền thủ công: nạp tiền tự động yêu cầu thẻ đã lưu hoặc Link. Thanh toán bằng mã tham chiếu Multibanco, PayPal và ghi nợ trực tiếp SEPA không khả dụng, và Kunavo không xuất hóa đơn. Trang thanh toán Kunavo không dùng để thanh toán gói đăng ký Claude Pro hoặc Max; gói đó được mua trên trang web Claude và chỉ có thể thanh toán bằng thẻ tín dụng hoặc thẻ ghi nợ.