Tóm lại: Bạn cài đặt Claude Code bằng một dòng duy nhất trong terminal, không cần Node.js và không cần quyền quản trị viên. Dòng lệnh phụ thuộc vào cửa sổ đang dùng: curl -fsSL https://claude.ai/install.sh | bash trên macOS, Linux và WSL, irm https://claude.ai/install.ps1 | iex trong Windows PowerShell, còn dòng thứ ba bên dưới trong Command Prompt (CMD). Nếu không có gói Claude, sau đó kết nối Claude Code với Kunavo bằng API Key: ANTHROPIC_BASE_URL=https://api.kunavo.com (không có /v1), ANTHROPIC_AUTH_TOKEN và bốn biến model. /status cho biết thiết lập có hoạt động hay không. Bạn thanh toán theo token từ số dư bắt đầu từ $10, nạp bằng thẻ ghi nợ hoặc tín dụng (bao gồm Visa Debit và Debit Mastercard), Apple Pay, Google Pay, Link hoặc EPS tại Áo. PayPal và ghi nợ SEPA không được hỗ trợ.
# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash# Windows PowerShell
irm https://claude.ai/install.ps1 | iex:: Windows-Eingabeaufforderung (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmdAnthropic duy trì toàn bộ tài liệu Claude Code bằng tiếng Đức, vì vậy hướng dẫn này liên kết đến các trang tiếng Đức. Chúng tôi đối chiếu các lệnh ở trên với thiết lập Claude Code vào ngày 3 tháng 10, 2026, còn các biến được đối chiếu với danh sách biến môi trường. Giá và phương thức thanh toán của Kunavo được cập nhật đến ngày 10 tháng 10, 2026. Đức, Áo và Thụy Sĩ đều có trong danh sách quốc gia của Anthropic dành cho cả Claude.ai lẫn API (cập nhật ngày 3 tháng 10, 2026). Có bản tiếng Anh tại đây.
Tổng quan quy trình
- Cài đặt: chạy dòng phù hợp ở trên, sau đó mở một cửa sổ terminal mới.
- Kiểm tra:
claude --versionhiển thị số phiên bản. - Quyết định: đăng nhập bằng gói Claude hoặc sử dụng API Key (xem phần so sánh bên dưới).
- Với API Key: nạp số dư, tạo Key và thiết lập sáu biến môi trường.
- Kiểm tra: nhập
/statustrong phiên.
Điều kiện tiên quyết: những gì đang áp dụng hiện nay
Một số hướng dẫn bằng tiếng Đức mô tả phiên bản Claude Code cũ hơn. Bảng này đối chiếu các thông tin phổ biến với yêu cầu trên trang thiết lập chính thức vào ngày 3 tháng 10, 2026.
| Chủ đề | Thông tin thường vẫn được đọc | Theo Anthropic |
|---|---|---|
| macOS | macOS 10.15 trở lên | macOS 13.0 trở lên |
| Windows | chỉ qua WSL | trực tiếp trên Windows 10 từ 1809 hoặc Windows Server 2019; WSL là một tùy chọn, không bắt buộc |
| Quyền | khởi động PowerShell với quyền quản trị viên | không cần |
| Node.js | Node.js 18 trở lên | chỉ dành cho cài đặt npm, sau đó cần phiên bản 22 trở lên |
| npm | lỗi thời | vẫn là một phương thức được ghi rõ trong tài liệu; trình cài đặt native được khuyến nghị |
| Linux | — | Ubuntu 20.04+, Debian 10+, Alpine Linux 3.19+ |
| Máy tính và shell | — | ít nhất 4 GB RAM, x64 hoặc ARM64, không phải Windows 32-bit; Bash, Zsh, PowerShell hoặc CMD |
| Vị trí | — | một quốc gia được Anthropic hỗ trợ; Đức, Áo và Thụy Sĩ nằm trong số đó |
| Tài khoản | — | để đăng nhập cần Pro, Max, Team, Enterprise hoặc Console; với API Key thì không cần gói đăng ký hay đăng nhập |
Cài đặt trên macOS, Linux và WSL
Trong terminal, thêm dòng có install.sh. Trong tài liệu chính thức, phương thức này nằm ở tab “Native Installation (Recommended)”. Tập lệnh đặt trình khởi chạy tại ~/.local/bin/claude và sau đó tự cập nhật bản cài đặt ở chế độ nền. Trên WSL, cũng dùng dòng này và chạy trong terminal WSL.
Cài đặt Claude Code trên Windows
Trên Windows, lệnh nào hoạt động tùy thuộc vào cửa sổ đang mở; chỉ cần nhìn vào dấu nhắc nhập lệnh là biết: PS C:\Users\Name> là PowerShell, còn C:\Users\Name> không có PS là Command Prompt (CMD). Theo trang thiết lập, không cần quyền quản trị cho cả hai cách. Trình cài đặt đặt claude.exe tại %USERPROFILE%\.local\bin.
Nếu nhầm cửa sổ, bạn sẽ nhận được thông báo bằng tiếng Anh, hoặc đôi khi bằng tiếng Đức trên Windows dùng tiếng Đức. Dòng CMD trong PowerShell kết thúc bằng The token '&&' is not a valid statement separator, còn dòng PowerShell trong CMD kết thúc bằng 'irm' is not recognized as an internal or external command. Cả hai đều có cùng ý nghĩa: dùng sai cửa sổ, hãy sử dụng dòng còn lại.
Trong menu Start, đừng chọn mục “Windows PowerShell (x86)”. Theo tài liệu khắc phục sự cố, mục này khởi chạy tiến trình 32 bit và khi đó trình cài đặt sẽ dừng với thông báo Claude Code does not support 32-bit Windows, kể cả trên máy tính 64 bit. Nếu chạy [Environment]::Is64BitOperatingSystem trong cửa sổ này và nhận được True, Windows của bạn hoạt động bình thường; chỉ cần mở “Windows PowerShell” không có phần bổ sung đó.
Bạn không cần cài đặt Git cho Windows. Nếu đã cài, Claude Code chạy các lệnh shell trong Git Bash; nếu không, chương trình dùng PowerShell. Nếu Claude Code không tìm thấy Git Bash đã cài, hãy nhập đường dẫn đến bash.exe dưới dạng CLAUDE_CODE_GIT_BASH_PATH trong khối env của ~/.claude/settings.json; với cài đặt mặc định, đó là C:\Program Files\Git\bin\bash.exe.
Việc dùng Windows native hay WSL phụ thuộc vào vị trí dự án của bạn:
| Biến thể | Điều kiện tiên quyết | Sandbox | Phù hợp khi |
|---|---|---|---|
| Windows native | không có; Git cho Windows là tùy chọn | không | dự án và công cụ của bạn tự chạy trên Windows |
| WSL 2 | đã bật WSL 2 | có | bạn cần công cụ Linux hoặc muốn chạy lệnh trong sandbox |
| WSL 1 | đã bật WSL 1 | không | WSL 2 không khả dụng trên máy |
Với WSL, hãy cài đặt và khởi chạy claude trong terminal WSL, không phải PowerShell hoặc CMD.
Các lựa chọn khác: Homebrew, WinGet và npm
Nếu thích quản lý phần mềm qua trình quản lý gói, bạn có thể làm vậy, với một lưu ý: theo tài liệu, các bản cài đặt Homebrew và WinGet không tự cập nhật, vì vậy bạn phải thường xuyên chạy upgrade. Homebrew cung cấp hai Cask. claude-code theo kênh ổn định, chậm hơn khoảng một tuần và bỏ qua các phiên bản có hồi quy lớn; claude-code@latest nhận mọi phiên bản ngay lập tức.
# Homebrew (macOS) – stabiler Kanal; claude-code@latest für den neuesten Stand
brew install --cask claude-code
brew upgrade claude-code # aktualisiert sich nicht von selbst
# WinGet (Windows)
winget install Anthropic.ClaudeCode
winget upgrade Anthropic.ClaudeCode # aktualisiert sich nicht von selbstQua npm
npm vẫn là một phương thức được mô tả chính thức. Điều kiện tiên quyết là Node.js 22 trở lên. Gói npm tải cùng một tệp nhị phân native như trình cài đặt và hoàn toàn không cần Node.js khi chạy. Vì vậy, cài đặt với Node.js cũ không bị dừng; npm chỉ cảnh báo bằng EBADENGINE. Nếu chưa có Node.js, trình cài đặt native là cách ngắn gọn hơn.
node -v # muss v22 oder neuer zeigen
npm install -g @anthropic-ai/claude-code # niemals mit sudo
# später aktualisieren: mit @latest, nicht mit npm update -g
npm install -g @anthropic-ai/claude-code@latestBa quy tắc từ trang thiết lập: không dùng sudo npm install -g, vì cách này gây ra vấn đề về quyền và rủi ro bảo mật. Cập nhật bằng @latest, vì npm update -g vẫn giữ nguyên trong phạm vi phiên bản ban đầu. Và đừng tắt các phần phụ thuộc tùy chọn: binary được cung cấp dưới dạng phần phụ thuộc tùy chọn dành riêng cho nền tảng; nếu có --omit=optional hoặc optional=false trong .npmrc, phần phụ thuộc này sẽ bị thiếu và claude sẽ báo Error: claude native binary not installed. trên macOS và Linux.
Kiểm tra cài đặt
Để làm vậy, hãy mở một cửa sổ terminal mới. Cửa sổ đã mở trước khi cài đặt chưa biết PATH mở rộng nên không tìm thấy claude.
claude --version # zeigt eine Versionsnummer wie 2.1.211 (Claude Code)
claude doctor # Diagnose von Installation und Einstellungen, startet keine Sitzungclaude doctor là công cụ dùng khi có vấn đề. Công cụ này không khởi chạy phiên, nhưng liệt kê trạng thái cài đặt, lỗi trong các tệp cài đặt và cảnh báo kèm đề xuất khắc phục. Nhờ đó, bạn có thể xác định vấn đề nằm ở cài đặt hay cấu hình.
Khi cài đặt gặp trục trặc
Tệp tải xuống trả về HTML hoặc 403
Nếu đầu ra bắt đầu bằng syntax error near unexpected token '<' hoặc curl báo 403, theo tài liệu khắc phục sự cố (cập nhật tại 3 tháng 10, 2026), máy chủ đã trả về một trang web hoặc trạng thái lỗi thay vì tập lệnh. Nếu trang đó ghi App unavailable in region, Anthropic cho rằng kết nối đến từ một quốc gia không được hỗ trợ. Nếu đang ở Đức, Áo hoặc Thụy Sĩ, điều này cho thấy lưu lượng truy cập có thể đang đi qua một điểm thoát VPN hoặc proxy ở nước ngoài. Lỗi 403 không có văn bản có thể do cùng nguyên nhân hoặc do tường lửa của công ty. Tài liệu khuyên trước tiên hãy kiểm tra kết nối mạng vì các cách cài đặt khác cũng truy cập cùng máy chủ. Thử một mạng khác hoặc nhờ bộ phận CNTT cấp quyền truy cập sẽ hữu ích hơn việc dùng trình cài đặt khác.
Không tìm thấy “claude”
command not found: claude trên macOS và Linux hoặc claude không được nhận dạng trên Windows có nghĩa là thư mục cài đặt bị thiếu trong PATH. Thông thường chỉ cần mở cửa sổ mới. Nếu cách đó không hiệu quả trên macOS hoặc Linux, hãy thêm ~/.local/bin vào ~/.zshrc hoặc ~/.bashrc. Trên Windows, hãy kiểm tra và bổ sung thư mục theo hướng dẫn khắc phục sự cố:
# 1. Steht der Installationsordner schon im PATH?
$env:PATH -split ';' | Select-String '\.local\\bin'
# 2. Keine Ausgabe? Ordner zum Benutzer-PATH hinzufügen, dann ein neues Fenster öffnen
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')
# 3. Im neuen Fenster
claude --versionPowerShell chặn npm.ps1
Điều này chỉ ảnh hưởng đến biến thể npm. Thông báo npm.ps1 cannot be loaded because running scripts is disabled on this system có nghĩa là chính sách thực thi đang chặn tập lệnh khởi động của npm. Bạn có thể gọi npm.cmd và claude.cmd, những lệnh không bị chính sách này áp dụng, chuyển sang trình cài đặt native hoặc cho phép các tập lệnh cục bộ đối với tài khoản người dùng của mình:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserGói đăng ký hay API Key?
Khi khởi chạy lần đầu, Claude Code hỏi ai sẽ thanh toán. Bạn có thể đăng nhập bằng tài khoản Claude hoặc cung cấp khóa API qua biến môi trường. Nếu đã đặt khóa, theo hướng dẫn gateway, khóa sẽ được ưu tiên: thông tin đăng nhập đã lưu vẫn ở đó nhưng không được dùng; nó sẽ có hiệu lực trở lại khi bạn xóa biến môi trường. Không cần cài đặt lại để chuyển đổi.
| Gói đăng ký Claude | API Key từ Kunavo | |
|---|---|---|
| Tính phí | hằng tháng: Pro giá 20 đô la hoặc 17 đô la mỗi tháng khi thanh toán theo năm (trả trước 200 đô la), Max từ 100 đô la, tất cả chưa bao gồm các khoản thuế nếu có (claude.com/de/pricing, cập nhật ngày 3 tháng 10, 2026) | theo token từ số dư trả trước, nạp từ $10, không có phí hàng tháng và không hết hạn |
| Phù hợp với | sử dụng hằng ngày trong nhiều giờ | sử dụng không thường xuyên; một tháng không sử dụng không mất phí |
| Thanh toán | chỉ thanh toán bằng thẻ tín dụng hoặc thẻ ghi nợ trên web; trong ứng dụng iOS và Android, thanh toán qua App Store hoặc Google Play (Câu hỏi thường gặp về thanh toán của Anthropic, cập nhật ngày 3 tháng 10, 2026) | Thẻ ghi nợ và tín dụng (Visa, Mastercard), Apple Pay, Google Pay, Link; EPS tại Áo |
| Thiết lập | khởi chạy claude và đăng nhập trong trình duyệt | sáu biến môi trường, không cần đăng nhập |
| Không bao gồm | — | Remote Control và đọc chính tả bằng giọng nói |
Hướng dẫn giá Claude Code cho biết từ mức nào Pro hoặc Max trở nên đáng dùng hơn Key.
Thiết lập API Key (không cần gói đăng ký)
Để Claude Code gửi yêu cầu đến một endpoint khác không phải là thủ thuật. ANTHROPIC_BASE_URL có trong danh sách biến của Anthropic và được thiết kế chính xác để định tuyến yêu cầu qua proxy hoặc gateway. Bạn không cần tiện ích mở rộng hay phiên bản Claude Code đã chỉnh sửa.
- Đăng ký Kunavo bằng địa chỉ email hoặc tài khoản Google.
- Trong Billing, nạp ít nhất $10 (các phương thức thanh toán nằm trong phần Thanh toán).
- Trong API-Keys, tạo một Key. Key bắt đầu bằng
sk-kn-và chỉ hiển thị một lần, vì vậy hãy sao chép ngay. - Thiết lập các biến như minh họa bên dưới.
Khi được thêm vào ~/.zshrc hoặc ~/.bashrc, các giá trị sẽ áp dụng cho mọi terminal mới trên macOS, Linux và WSL:
export ANTHROPIC_BASE_URL=https://api.kunavo.com # nur die Domain, ohne /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-5Trong PowerShell, các phép gán $env: chỉ áp dụng cho cửa sổ đang mở, phù hợp cho lần thử đầu tiên:
# Gilt nur für dieses PowerShell-Fenster
$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"
claudeVề lâu dài, hãy đặt các giá trị trong khối env của ~/.claude/settings.json (trên Windows là %USERPROFILE%\.claude\settings.json). Theo hướng dẫn Gateway (cập nhật 3 tháng 10, 2026), tệp này áp dụng cho tất cả dự án của bạn. Nếu tệp đã tồn tại, chỉ bổ sung 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"
}
}Tiện ích mở rộng VS Code đọc các biến từ claudeCode.environmentVariables trong cài đặt người dùng của VS Code (lệnh Preferences: Open User 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" }
]
}Chức năng của từng biến
| Biến | Giá trị | Tác động | Nếu thiếu hoặc sai |
|---|---|---|---|
ANTHROPIC_BASE_URL | https://api.kunavo.com | chuyển tất cả yêu cầu đến Kunavo; Claude Code tự thêm /v1/messages | Nếu kết thúc bằng /v1, yêu cầu sẽ đến /v1/v1/messages và thất bại với 404. |
ANTHROPIC_AUTH_TOKEN | Key của bạn (sk-kn-…) | được gửi dưới dạng Authorization: Bearer và được ưu tiên ngay lập tức | Nếu thay vào đó đặt ANTHROPIC_API_KEY (header x-api-key), bạn phải xác nhận Key một lần trong chế độ tương tác. Nếu bị từ chối, Claude Code sẽ bỏ qua Key mà không hỏi lại; có thể bật lại tại /config → Use custom API key. Kunavo chấp nhận Key trong cả hai header. |
ANTHROPIC_MODEL | claude-sonnet-5 | Model khởi động của mỗi phiên | Nếu thiếu, phiên sẽ khởi động bằng model của ghim Opus, tức Opus 5.5; nếu ghim đó cũng thiếu, phiên dùng mặc định tương ứng của Anthropic (hiện cũng là Opus 5.5). |
ANTHROPIC_DEFAULT_OPUS_MODEL | claude-opus-5-5 | Đích của /model opus và phiên bản mà mặc định sử dụng khi không có ANTHROPIC_MODEL | Nếu thiếu, bí danh sẽ theo chỉ định của Anthropic, hiện cũng là Opus 5.5; khi Opus mới hơn xuất hiện, bí danh có thể trỏ đến model mà Kunavo chưa cung cấp. Opus 5.5 yêu cầu Claude Code từ phiên bản 2.1.280; các phiên bản cũ hơn được cập nhật bởi claude update. |
ANTHROPIC_DEFAULT_SONNET_MODEL | claude-sonnet-5 | Đích của /model sonnet, giai đoạn thực thi của opusplan và các Subagent với model: sonnet | Nếu thiếu, bí danh dành cho người dùng API sẽ trỏ đến Sonnet 5.5, model mà Kunavo hiện không cung cấp (tính đến 3 tháng 10, 2026): 404. |
ANTHROPIC_DEFAULT_HAIKU_MODEL | claude-haiku-4-5 | Đích của /model haiku và model cho các chức năng nền | Nếu thiếu dòng này, từ Claude Code 2.1.293 bí danh sẽ trỏ đến Haiku 5.5, còn trước đó sẽ trỏ đến một ID Haiku 4.5 có kèm ngày; Kunavo không cung cấp ID nào trong hai ID này: lỗi 404. |
Vì sao nên cố định mô hình khởi chạy? Theo cấu hình mô hình (cập nhật 3 tháng 10, 2026), Opus 5.5 là mặc định cho người dùng API và các bí danh sẽ được chuyển sang phiên bản mới theo thời gian. Kunavo cung cấp Opus 5.5; do đó, khởi chạy mà không đặt biến mô hình sẽ dùng Opus 5.5; chi phí cho mỗi token cao gấp đôi so với Claude Sonnet 5. Dùng tên mô hình cố định giúp bạn biết mô hình nào đang trả lời và mức giá áp dụng. Việc ghim Opus giữ bí danh opus ở Claude Opus 5.5 (claude-opus-5-5), ngay cả khi Anthropic sau này chuyển bí danh đó sang Opus mới hơn. Opus 5.5 có giá mỗi token tại Kunavo là ít hơn Claude Opus 5 ($2,80 / $14,00 so với $3,50 / $17,50 cho mỗi 1 triệu token đầu vào/đầu ra) và yêu cầu Claude Code phiên bản 2.1.280 trở lên; nếu cài đặt phiên bản cũ hơn, claude update sẽ cập nhật lên phiên bản hiện tại. Việc ghim Sonnet là bắt buộc: với người dùng API, bí danh sonnet trỏ đến Sonnet 5.5, phiên bản Kunavo không cung cấp; nếu thiếu ANTHROPIC_DEFAULT_SONNET_MODEL, /model sonnet, giai đoạn thực thi của opusplan và các subagent có model: sonnet sẽ kết thúc với lỗi 404. Claude Haiku 4.5 giúp các tác vụ nền có chi phí thấp, còn /model cho phép bạn chuyển đổi bất cứ lúc nào trong phiên.
Có hai điều cần lưu ý về vị trí lưu trữ. Key không bao giờ được đặt trong .claude/settings.json, vì theo hướng dẫn về gateway, tệp này được commit và sẽ đến tay bất kỳ ai clone repository. Nếu một shell export và một khối env đặt cùng một biến, tệp cấu hình sẽ được ưu tiên. Vì vậy, nếu bạn thay đổi một biến trong shell mà không có gì xảy ra, có lẽ giá trị cũ vẫn còn trong settings.json.
So sánh các mô hình, giá của Kunavo lấy từ danh mục, giá niêm yết của Anthropic theo claude.com/de/pricing (cập nhật 3 tháng 10, 2026), tính trên mỗi 1 triệu token:
| Mô hình | Kunavo (Đầu vào / Đầu ra) | Giá niêm yết của Anthropic (Input / Output) | Chênh lệch | Vai trò trong Claude Code |
|---|---|---|---|---|
claude-haiku-4-5 | $0,70 / $3,50 | $1,00 / $5,00 | ~30% rẻ hơn | Bí danh haiku và các tác vụ nền của Claude Code |
claude-sonnet-5 | $1,40 / $7,00 | $2,00 / $10,00 | ~30% rẻ hơn | Model chính (ANTHROPIC_MODEL) cho công việc hằng ngày |
claude-opus-5-5 | $2,80 / $14,00 | $4,00 / $20,00 | ~30% rẻ hơn | Bí danh opus với ghim ở trên (tái cấu trúc lớn, lập kế hoạch); nếu không ghim, đây là mặc định cho người dùng API |
claude-opus-5 | $3,50 / $17,50 | $5,00 / $25,00 | ~30% rẻ hơn | Không có bí danh; chỉ chỉ định bằng /model claude-opus-5 |
Tất cả mô hình và mức giá của Claude được nêu trong hướng dẫn về giá Claude API và trên trang giá.
Lần chạy đầu tiên: kiểm tra bằng /status
Chuyển đến thư mục dự án và khởi chạy claude. Khi đã đặt ANTHROPIC_AUTH_TOKEN, bạn sẽ vào thẳng phiên làm việc, không cần màn hình đăng nhập. Nếu màn hình đó vẫn xuất hiện, Claude Code chưa tìm thấy khóa. Theo hướng dẫn Gateway, nguyên nhân thường gặp nhất là khóa chỉ được đặt trong .claude/settings.json hoặc .claude/settings.local.json của dự án. Claude Code chỉ đọc các khối env như vậy trong phiên tương tác sau khi chạy trình hướng dẫn thiết lập và trả lời câu hỏi xác nhận bạn có tin cậy thư mục đó hay không. Vì vậy, hãy đặt khóa trong shell (export) hoặc trong ~/.claude/settings.json.
Trong phiên, /status trong tab Status cho biết Claude Code lấy địa chỉ và thông tin xác thực từ đâu. Có hai dòng cần chú ý:
| Dòng | Đúng | Nếu không |
|---|---|---|
Anthropic base URL | https://api.kunavo.com | Dòng này chỉ xuất hiện khi đã đặt địa chỉ gateway. Nếu thiếu, ANTHROPIC_BASE_URL chưa được nạp vào phiên. |
Auth token | cho biết ANTHROPIC_AUTH_TOKEN | Nếu thay vào đó hiển thị Login method cùng tài khoản claude.ai, biến này chưa được đọc và phiên đang chạy qua gói thuê bao của bạn. |
Bạn cũng có thể kiểm tra kết nối mà không cần Claude Code, bằng yêu cầu trong hướng dẫn về gateway (ở đây mô hình được đặt thành claude-sonnet-5). Yêu cầu này chỉ định đúng một output token nên chi phí tương ứng chỉ là một khoản rất nhỏ. Các lệnh đọc các biến shell; nếu giá trị của bạn chỉ nằm trong settings.json, hãy export chúng thêm cho lần kiểm tra này.
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": "."}]}'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": "."}]}'Nếu JSON trả về bắt đầu bằng {"id":"msg_, hoặc trong PowerShell là một đối tượng có id bắt đầu bằng msg_, thì địa chỉ và key là chính xác. 401 có nghĩa là key đã bị từ chối.
Điều gì thay đổi khi dùng API key
Phần lớn vẫn giữ nguyên: chỉnh sửa mã, công cụ, subagent, máy chủ MCP, hook và bộ nhớ đệm prompt vẫn hoạt động như thường. Bạn cần biết bốn điểm khác biệt:
- Remote Control và tính năng đọc chính tả bằng giọng nói không còn hoạt động. Theo hướng dẫn về gateway, cả hai đều cần danh tính claude.ai và bị khóa khi
ANTHROPIC_AUTH_TOKENhoặcANTHROPIC_API_KEYđang hoạt động. Kể từ phiên bản 2.1.196, Remote Control cũng bị khóa nếuANTHROPIC_BASE_URLtrỏ đến một máy chủ bên ngoài Anthropic. /fastbáo Fast-Mode không khả dụng. Khi chỉ có Bearer token, Claude Code coi tính năng này là đã tắt và thậm chí không gửi yêu cầu kiểm tra khả dụng.- Tính năng tìm kiếm công cụ cho MCP đang tắt. Theo tài liệu MCP (cập nhật 3 tháng 10, 2026), Claude Code sẽ tắt tính năng này khi
ANTHROPIC_BASE_URLtrỏ đến nhà cung cấp bên thứ ba; có thể bật rõ ràng bằngENABLE_TOOL_SEARCH. /contextchỉ hiển thị giá trị ước tính. Kunavo không cung cấp/v1/messages/count_tokens. Khi không có endpoint này, theo hướng dẫn tương thích Gateway (cập nhật 3 tháng 10, 2026), Claude Code sẽ đếm dựa trên số ký tự.
Bạn có thể tìm hiểu thêm về việc tích hợp trong hướng dẫn tích hợp Claude Code (bằng tiếng Anh).
Thanh toán không cần PayPal và SEPA
Trước tiên, cần phân biệt rõ: Kunavo không bán gói đăng ký Claude mà bán số dư để truy cập API, từ đó Claude Code trừ phí cho từng token. Với gói Pro và Max của Anthropic: trên web chỉ chấp nhận thẻ tín dụng hoặc thẻ ghi nợ; trong ứng dụng, khoản thanh toán được xử lý qua App Store hoặc Google Play (Câu hỏi thường gặp về thanh toán). Theo bài viết trợ giúp về thẻ bị từ chối, Anthropic không chấp nhận PayPal hoặc Venmo (cả hai thông tin đều được cập nhật 3 tháng 10, 2026).
Kunavo nạp số dư qua trang thanh toán Stripe. Giá được niêm yết bằng đô la Mỹ; khách hàng thanh toán từ Đức hoặc Áo sẽ thấy số tiền bằng euro. Theo tài liệu của Stripe về Adaptive Pricing (cập nhật 3 tháng 10, 2026), tỷ giá này bao gồm phí chuyển đổi từ 2–4% do người mua chịu. Nếu chọn thanh toán bằng đô la Mỹ tại trang thanh toán, bạn sẽ không mất khoản phí này; khi đó, ngân hàng sẽ chuyển đổi theo tỷ giá riêng và có thể tính phí riêng. Trang thanh toán hỗ trợ:
| Phương thức thanh toán | Nơi áp dụng | Ghi chú |
|---|---|---|
| Thẻ (Visa, Mastercard, Amex, JCB, UnionPay) | mọi nơi | Thẻ tín dụng và thẻ ghi nợ, bao gồm Visa Debit và Debit Mastercard; không bao gồm girocard thuần túy |
| Apple Pay | Safari trên iPhone và iPad; không có ở Ấn Độ | bằng thẻ trong Wallet, bao gồm thẻ ghi nợ Visa hoặc Mastercard; không dùng được thẻ girocard đơn thuần |
| Google Pay | Chrome và Android đã thiết lập Google Pay; không có ở Ấn Độ | bằng thẻ trong Wallet, bao gồm thẻ ghi nợ Visa hoặc Mastercard; không dùng được thẻ girocard đơn thuần |
| Liên kết | mọi nơi ngoại trừ Ấn Độ | Dịch vụ thanh toán của Stripe, lưu thẻ của bạn; cũng cho phép tự động nạp |
| EPS | Áo, trang thanh toán bằng euro | Chuyển hướng đến dịch vụ ngân hàng trực tuyến của ngân hàng bạn |
EPS là phương thức thanh toán của Áo, theo Stripe được tất cả ngân hàng tại Áo hỗ trợ. Bạn sẽ được chuyển đến trang của ngân hàng để xác nhận; phương thức này chỉ dùng được khi thanh toán bằng euro. Khách hàng thanh toán từ Thụy Sĩ có thể dùng thẻ, Apple Pay, Google Pay hoặc Link.
girocard: Thẻ chỉ có girocard (trước đây là EC-Karte) sẽ không được chấp nhận tại trang thanh toán Kunavo, vì Stripe không liệt kê girocard trong số thương hiệu thẻ được hỗ trợ (cập nhật 3 tháng 10, 2026). Nếu thẻ của bạn cũng có logo Visa hoặc Mastercard, khoản thanh toán sẽ được xử lý qua mạng lưới đó, kể cả khi dùng Apple Pay và Google Pay.
Không được hỗ trợ: PayPal, ghi nợ trực tiếp SEPA, chuyển khoản thủ công (thanh toán trước), giropay và Sofort. Checkout chỉ cung cấp Klarna cho người mua ở Hoa Kỳ; ngay cả khi chuyển sang đô la Mỹ từ bên ngoài Hoa Kỳ, bạn vẫn không thấy Klarna.
- Tạo tài khoản; Kunavo không yêu cầu thẻ khi đăng ký.
- Trong Billing, chọn một mức nạp tiền từ $10. Các mức lớn hơn sẽ có số dư thưởng: $100 trở thành $110, $1.000 trở thành $1.200 và $5.000 trở thành $6.250.
- Trong Stripe Checkout, chọn phương thức thanh toán. Bạn sẽ thấy số tiền bằng euro trước khi xác nhận; với EPS, hãy xác nhận trong ngân hàng trực tuyến.
- Trong API-Keys, tạo một key và nhập key đó làm
ANTHROPIC_AUTH_TOKEN.
Số dư được thanh toán trước: không có phí hàng tháng, không hết hạn và các yêu cầu thất bại không bị tính phí. Chỉ có thể tự động nạp thêm bằng thẻ đã lưu hoặc Link; với Apple Pay, Google Pay và EPS, bạn phải nạp thủ công. Kunavo không xuất hóa đơn có ghi rõ thuế GTGT; bạn có thể xem các lần nạp tiền trong Billing. Tìm hiểu thêm về phương thức thanh toán và thẻ bị từ chối tại: Thanh toán Claude không cần thẻ tín dụng.
Một phiên tốn bao nhiêu: ví dụ tính toán
Khi thanh toán bằng API key, bạn trả tiền cho token và Claude Code gửi toàn bộ ngữ cảnh trước đó trong mỗi bước. Tuy nhiên, ngữ cảnh này không bị tính phí đầy đủ mỗi lần: phần đầu không thay đổi được mô hình đọc từ bộ nhớ đệm và áp dụng mức giá đọc bộ nhớ đệm thấp hơn. Bảng dưới đây tính theo một mẫu giả định; đây không phải phép đo hay mức giới hạn trên. Giả định:
- 40.000 input token cho mỗi yêu cầu, trong đó 36.000 (90%) được đọc từ bộ nhớ đệm và 4.000 được ghi mới vào bộ nhớ đệm;
- 1.000 output token cho mỗi yêu cầu;
- 50 yêu cầu như vậy trong mỗi phiên làm việc, không tính các lệnh gọi chạy nền;
- Đọc bộ nhớ đệm có giá bằng 10% của mức giá input ở Claude Sonnet 5, còn ghi bộ nhớ đệm có giá gấp 1,25 lần; mỗi mô hình trong bảng được tính theo các hệ số riêng.
| Mô hình | Một yêu cầu | 50 yêu cầu | 50 yêu cầu hoàn toàn không có lượt truy cập bộ nhớ đệm |
|---|---|---|---|
| Claude Sonnet 5 | $0,019 | $0,952 | $3,15 |
| Claude Opus 5 | $0,0476 | $2,38 | $7,88 |
| Claude Opus 5.5 | $0,033 | $1,65 | $6,30 |
Số tiền bạn thực sự trả phụ thuộc vào độ dài ngữ cảnh, số lượt truy cập bộ nhớ đệm và độ dài câu trả lời, cũng như việc bạn có bắt đầu lại bằng /clear giữa hai tác vụ hay không. Để tính theo số liệu của riêng bạn, hãy dùng Trình tính chi phí token Claude (bằng tiếng Anh); phần so sánh với Pro và Max được tính trong Hướng dẫn giá Claude Code.
Thông báo lỗi và ý nghĩa
| Thông báo | Ý nghĩa và cách khắc phục |
|---|---|
The token '&&' is not a valid statement separator | Dòng lệnh CMD đang nằm trong cửa sổ PowerShell. Dòng irm … | iex phải được chạy ở đó. |
'irm' is not recognized as an internal or external command (hoặc thông báo tương tự bằng tiếng Đức) | Dòng PowerShell đang nằm trong CMD. Dòng chứa install.cmd phải được chạy ở đó. |
Claude Code does not support 32-bit Windows | Bạn đã mở “Windows PowerShell (x86)”. Hãy chọn mục không có (x86). |
syntax error near unexpected token '<' hoặc 403 | Thay vì script, một trang web hoặc mã lỗi đã được trả về. Hãy kiểm tra VPN, proxy và tường lửa của công ty, hoặc thử một mạng khác. |
App unavailable in region | Kết nối có vẻ đến từ một quốc gia không được hỗ trợ. Ở DE, AT và CH, nguyên nhân thường là VPN hoặc proxy. |
Không nhận dạng được command not found: claude hoặc claude | Thư mục cài đặt không có trong PATH. Hãy mở một cửa sổ mới; trên Windows, dùng lệnh PATH ở phía trên. |
Cảnh báo EBADENGINE | Node.js cũ hơn 22. Quá trình cài đặt vẫn hoàn tất; tuy vậy, bạn nên cập nhật. |
claude native binary not installed (macOS, Linux) | npm đã bỏ qua các phần phụ thuộc tùy chọn (--omit=optional, optional=false). Hãy xóa cài đặt này rồi cài đặt lại. |
npm.ps1 cannot be loaded | Chính sách thực thi đang chặn npm. Hãy dùng npm.cmd, chạy dòng Set-ExecutionPolicy hoặc sử dụng trình cài đặt native. |
| Hiển thị màn hình đăng nhập dù đã đặt key | Key chỉ được đặt trong phần cài đặt dự án. Hãy đặt bằng export hoặc trong ~/.claude/settings.json, rồi mở một terminal mới. |
Đã đặt ANTHROPIC_API_KEY nhưng không có tác dụng | Xác nhận một lần đã bị từ chối. Hãy bật trong /config → Use custom API key hoặc chuyển sang ANTHROPIC_AUTH_TOKEN. |
401 | Key đã bị từ chối. Key có được sao chép đầy đủ, không có khoảng trắng, vẫn còn trong /app/keys và đã được nhập vào ANTHROPIC_AUTH_TOKEN không? |
404 | ANTHROPIC_BASE_URL kết thúc bằng /v1, hoặc mô hình được yêu cầu không có trên Kunavo, chẳng hạn sau /model sonnet mà không ghim Sonnet. |
Giới hạn của phương thức này
- Bạn trả tiền theo token, không phải một khoản cố định. Nếu sử dụng Claude Code hàng giờ mỗi ngày, Pro hoặc Max thường sẽ rẻ hơn. Với mức sử dụng thay đổi, bạn chỉ trả cho phần đã dùng và một tháng không sử dụng sẽ không tốn phí.
- Không có tài khoản claude.ai thì không có Remote Control và tính năng đọc chính tả bằng giọng nói;
/fastđược coi là đã tắt và tính năng tìm kiếm công cụ cho MCP mặc định bị tắt. - Hiện Kunavo chưa cung cấp Sonnet 5.5; vì vậy,
/model sonnet,opusplanvà các subagent Sonnet cần ghim Sonnet trong các ví dụ ở trên. - Apple Pay, Google Pay và EPS chỉ dùng để nạp tiền thủ công; tự động nạp chỉ thực hiện được bằng thẻ hoặc Link. Số tiền bằng euro bao gồm phí chuyển đổi của Stripe.
- Kunavo không xuất hóa đơn có ghi rõ thuế GTGT.
- Tài liệu Claude Code của Anthropic có bản tiếng Đức, còn hướng dẫn tích hợp của Kunavo chỉ có bằng tiếng Anh.
Câu hỏi thường gặp
Quá trình cài đặt Claude Code diễn ra như thế nào?
Bạn mở một terminal và chạy lệnh chính thức dành cho hệ thống của mình. Trên macOS, Linux và WSL: curl -fsSL https://claude.ai/install.sh | bash. Trong Windows PowerShell: irm https://claude.ai/install.ps1 | iex. Trong Windows Command Prompt (CMD): curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd. Sau đó mở một cửa sổ terminal mới và nhập claude --version. Nếu xuất hiện số phiên bản thì Claude Code đã được cài đặt. Bản cài đặt native này tự cập nhật ở chế độ nền; các bản cài đặt qua Homebrew hoặc WinGet phải được bạn tự cập nhật.
Cài đặt Claude Code trên Windows: Tôi có cần WSL hoặc quyền quản trị viên không?
Không cần cả hai. Claude Code chạy trực tiếp trên Windows 10 từ phiên bản 1809 và trên Windows Server 2019; theo Anthropic, trình cài đặt không cần chạy với quyền quản trị viên. WSL 2 chỉ đáng dùng nếu bạn cần các công cụ Linux hoặc sandbox; khi đó hãy cài đặt và khởi chạy Claude Code trong terminal WSL. Git cho Windows là tùy chọn: khi có Git, Claude Code chạy các lệnh trong Git Bash; khi không có Git, Claude Code chạy các lệnh trong PowerShell. Các lỗi thường gặp là dùng dòng CMD trong cửa sổ PowerShell (hoặc ngược lại) và mục menu Start “Windows PowerShell (x86)”, mục này sẽ dừng vì chạy dưới dạng quy trình 32-bit.
Tôi có cần Node.js cho Claude Code không?
Chỉ khi bạn cài đặt qua npm, và khi đó cần Node.js 22 trở lên. Các hướng dẫn cũ thường nêu Node.js 18, nhưng thông tin đó đã lỗi thời. Trình cài đặt native, Homebrew và WinGet hoàn toàn không cần Node.js. Nếu Node.js quá cũ, npm sẽ cảnh báo bằng EBADENGINE nhưng vẫn cài đặt. Không bao giờ cài đặt bằng sudo; hãy cập nhật bằng npm install -g @anthropic-ai/claude-code@latest thay vì npm update -g.
Tôi có thể sử dụng Claude Code mà không cần gói đăng ký không?
Có, bằng API Key. Để đăng nhập, bạn cần Pro, Max, Team, Enterprise hoặc tài khoản Console; gói Claude miễn phí không bao gồm Claude Code. Với Kunavo, thay vào đó hãy đặt ANTHROPIC_BASE_URL=https://api.kunavo.com và ANTHROPIC_AUTH_TOKEN; Claude Code sẽ khởi chạy mà không hiển thị màn hình đăng nhập. Mỗi token được trừ từ số dư trả trước mà bạn nạp từ $10; không có phí hàng tháng. Bạn sẽ không có Remote Control và đọc chính tả bằng giọng nói vì cả hai đều yêu cầu tài khoản claude.ai.
Tôi thiết lập API Key trong Claude Code như thế nào?
Tốt nhất là đặt trong khối env của ~/.claude/settings.json (trên Windows là %USERPROFILE%\.claude\settings.json), nếu không thì dùng các dòng export trong ~/.zshrc hoặc ~/.bashrc. Bạn cần sáu giá trị: ANTHROPIC_BASE_URL=https://api.kunavo.com không có /v1 (nếu không, yêu cầu sẽ đến /v1/v1/messages và thất bại với 404), ANTHROPIC_AUTH_TOKEN cùng Key của bạn, cùng với 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. ANTHROPIC_AUTH_TOKEN có hiệu lực ngay. ANTHROPIC_API_KEY cũng hoạt động vì Kunavo chấp nhận Key trong cả hai header, nhưng trong chế độ tương tác phải xác nhận một lần. Không bao giờ ghi Key vào .claude/settings.json của dự án vì tệp này được chia sẻ cùng repository.
Claude Code sử dụng model nào với API Key?
Model do bạn chỉ định. Nếu không chỉ định, theo Anthropic, Claude Code dành cho người dùng API sẽ khởi động với Opus 5.5 (tính đến 3 tháng 10, 2026). Kunavo cung cấp Opus 5.5, chi phí cho mỗi token cao gấp đôi so với Claude Sonnet 5. Với ANTHROPIC_MODEL=claude-sonnet-5, Claude Sonnet 5 sẽ là model khởi động; một yêu cầu theo ví dụ tính toán chi phí trên trang này sẽ có giá khoảng $0,019. ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5 xác định model được /model opus khởi chạy; Opus 5.5 yêu cầu Claude Code từ phiên bản 2.1.280, bản cài đặt cũ sẽ được claude update cập nhật lên phiên bản hiện tại. ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5 cũng cần thiết vì bí danh sonnet dành cho người dùng API trỏ đến Sonnet 5.5 và Kunavo không cung cấp Sonnet 5.5: nếu thiếu dòng này, /model sonnet, giai đoạn thực thi của opusplan và các Subagent với model: sonnet sẽ kết thúc bằng 404. ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5 cũng áp dụng cho các tác vụ nền.
Làm sao tôi biết trong /status rằng Claude Code đang sử dụng API Key?
Trong phiên đang chạy, nhập /status rồi xem tab Status. Dòng Anthropic base URL phải hiển thị https://api.kunavo.com và dòng Auth token phải nêu ANTHROPIC_AUTH_TOKEN. Nếu thiếu dòng Base-URL, biến chưa đến được phiên. Nếu ở đó ghi Login method cùng tài khoản claude.ai, phiên đang chạy qua gói đăng ký của bạn. Nếu màn hình đăng nhập xuất hiện ngay khi khởi động lần đầu, có thể Key chỉ được đặt trong cài đặt dự án, nơi Claude Code chỉ đọc sau trình hướng dẫn thiết lập.
Tôi có thể thanh toán bằng PayPal, ghi nợ SEPA, girocard hoặc EPS cho Claude Code không?
Đối với số dư Kunavo: có EPS nếu bạn thanh toán bằng euro từ Áo. Không có PayPal và ghi nợ trực tiếp SEPA; Klarna chỉ dành cho người mua ở Hoa Kỳ. Thẻ girocard đơn thuần sẽ thất bại vì Stripe không hỗ trợ girocard như một thương hiệu thẻ. Nếu thẻ của bạn có thêm logo Visa hoặc Mastercard, bạn có thể thanh toán qua mạng lưới đó, kể cả bằng Apple Pay hoặc Google Pay. Thẻ tín dụng, thẻ ghi nợ và Link cũng được hỗ trợ. Số tiền tối thiểu $10, không có phí hàng tháng và số dư không hết hạn; theo Stripe, số tiền bằng euro bao gồm phí chuyển đổi 2–4%. Chỉ có thể nạp tiền tự động bằng thẻ đã lưu hoặc Link. Kunavo không phát hành hóa đơn có thể hiện thuế giá trị gia tăng. Bạn không thể thanh toán gói Claude Pro hoặc Max theo cách này; bản thân Anthropic trên web chỉ nhận thẻ và không nhận PayPal.