Cài đặt Claude Code: lệnh cho Windows, macOS và Linux — và cách dùng không cần thuê bao

Để cài đặt Claude Code, chỉ cần một lệnh: trên macOS, Linux hoặc WSL, chạy curl -fsSL https://claude.ai/install.sh | bash; trên Windows, chạy irm https://claude.ai/install.ps1 | iex trong PowerShell (trong Command Prompt, tức CMD, hãy dùng dòng install.cmd bên dưới). Sau đó mở một terminal mới, kiểm tra bằng claude --version và chạy claude để bắt đầu. Ở lần kết nối đầu tiên có hai cách: đăng nhập bằng tài khoản Pro, Max, Team, Enterprise hoặc Console (gói Claude.ai miễn phí không bao gồm Claude Code) hoặc thiết lập hai biến môi trường, ANTHROPIC_BASE_URL và ANTHROPIC_AUTH_TOKEN, rồi dùng khóa API trả phí theo mức sử dụng — hoàn toàn không cần gói đăng ký.

Các lệnh được kiểm tra vào ngày 11 tháng 9, 2026 theo tài liệu cài đặt chính thức của Anthropic.

Trước khi cài đặt

Cài đặt trên macOS và Linux

Mở Terminal và dán:

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

Đây là phương pháp được khuyến nghị: cài đặt một tệp nhị phân độc lập và tự cập nhật trong nền. Lối tắt nằm ở ~/.local/bin/claude, và terminal đã mở trước đó sẽ không thấy PATH mới — vì vậy hãy mở một cửa sổ khác trước khi kiểm tra. Trên WSL, lệnh cũng giống như vậy.

Cài đặt trên Windows

Trên Windows có hai dòng lệnh khác nhau, và điểm khác biệt duy nhất là terminal bạn đang sử dụng. Nếu dấu nhắc bắt đầu bằng PS C:\Users\SeuNome>, đó là PowerShell; nếu không có PS, chỉ có C:\Users\SeuNome>, đó là Command Prompt (CMD). Không cần chạy với tư cách quản trị viên.

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

:: Windows Prompt de Comando (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Dán dòng lệnh vào sai terminal là lỗi phổ biến nhất. Dòng CMD trong PowerShell trả về The token '&&' is not a valid statement separator; dòng PowerShell trong CMD trả về 'irm' is not recognized as an internal or external command (trên Windows tiếng Bồ Đào Nha là “không được nhận dạng là lệnh nội bộ hoặc lệnh bên ngoài”). Và curl … | bash của macOS khi dán vào PowerShell trả về A parameter cannot be found that matches parameter name 'fsSL'. Trong cả ba trường hợp, chỉ cần dùng đúng dòng lệnh.

Cài đặt Git for Windows là tùy chọn nhưng được khuyến nghị: Claude Code sử dụng Git Bash đi kèm để chạy lệnh; nếu không có, nó sử dụng PowerShell. Nếu Git đã được cài đặt nhưng Git Bash vẫn không được tìm thấy, hãy thiết lập CLAUDE_CODE_GIT_BASH_PATH trong khối env của phần cài đặt, trỏ đến bash.exe.

Trong WSL, chạy dòng lệnh dành cho macOS/Linux bên trong terminal WSL và mở claude ngay tại đó — không mở bằng PowerShell hay CMD.

Thông qua trình quản lý gói

Hoạt động, với một điểm khác biệt quan trọng: không trình quản lý nào trong số đó tự cập nhật theo mặc định. Bạn phải cập nhật thủ công (brew upgrade claude-code, winget upgrade Anthropic.ClaudeCode). Ngoài ra còn có các kho apt, dnf và apk đã ký cho Debian/Ubuntu, Fedora/RHEL và Alpine.

# Homebrew (macOS, Linux) — canal stable
brew install --cask claude-code

# WinGet (Windows)
winget install Anthropic.ClaudeCode

# npm — exige Node.js 22 ou mais novo; nunca com sudo
npm install -g @anthropic-ai/claude-code

Với npm, kể từ phiên bản 2.1.198, gói yêu cầu Node.js 22 hoặc mới hơn; trên Node cũ, npm chỉ hiển thị cảnh báo EBADENGINE rồi kết thúc cài đặt. Gói cài đặt cùng tệp nhị phân native, không sử dụng Node.js để chạy. Không bao giờ dùng sudo npm install -g: điều này gây ra vấn đề về quyền và là rủi ro bảo mật.

Kiểm tra cài đặt

claude --version   # imprime a versão, por exemplo 2.1.211 (Claude Code)
claude doctor      # diagnóstico da instalação e das configurações, sem abrir sessão

Hãy ghi nhớ claude doctor: không cần mở phiên, lệnh này hiển thị tình trạng cài đặt, lỗi trong tệp cấu hình và cách khắc phục được đề xuất — đây là cách nhanh nhất để biết vấn đề nằm ở cài đặt hay cấu hình.

Nếu xuất hiện command not found: claude (hoặc trên Windows, báo rằng claude không được nhận dạng), thư mục cài đặt chưa có trong PATH. Trên macOS và Linux, hãy mở một terminal mới; nếu không giải quyết được, thêm ~/.local/bin vào PATH trong ~/.zshrc hoặc ~/.bashrc. Trên Windows, thư mục là %USERPROFILE%\.local\bin; kiểm tra và thêm thư mục bằng PowerShell:

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

# 2. Sem saída? Adicione ao PATH do usuário e abra um terminal novo
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. No terminal novo: se houver duas instalações, aparecem dois caminhos
where.exe claude

Kết nối lần đầu: gói đăng ký hoặc khóa API

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

Trong thư mục dự án, chạy claude và làm theo quy trình đăng nhập trong trình duyệt bằng tài khoản Pro, Max, Team, Enterprise hoặc Console. Một chi tiết thường gây nhầm lẫn: nếu biến ANTHROPIC_API_KEY đã được thiết lập, Claude Code sẽ hỏi một lần liệu có sử dụng khóa đó không. Nếu bạn từ chối, nó sẽ âm thầm bỏ qua khóa này và không hỏi lại — khiến bạn tưởng rằng biến không được đọc. Để kích hoạt lại, đi đến /config → Sử dụng khóa API tùy chỉnh.

Cách B — không có gói đăng ký, dùng khóa trả phí theo mức sử dụng

Claude Code đọc trực tiếp ANTHROPIC_BASE_URL, vì vậy trỏ nó đến bất kỳ endpoint nào của Anthropic Messages API là cấu hình được hỗ trợ — không cần plugin, proxy hay tệp nhị phân đã chỉnh sửa. Quy trình: tạo tài khoản, nạp số dư (tối thiểu $10), tạo khóa sk-kn- trong bảng điều khiển khóa (khóa chỉ hiển thị một lần) và thiết lập các biến. Trên macOS và Linux:

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, để kiểm tra trong một cửa sổ 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

Để thiết lập cố định, vị trí tốt nhất là khối env trong tệp cài đặt của người dùng, ~/.claude/settings.json (trên Windows, %USERPROFILE%\.claude\settings.json). Tại đó, các biến áp dụng cho mọi terminal, tiện ích mở rộng trình soạn thảo và quy trình chạy nền. Nếu tệp đã có các cài đặt khác, chỉ cần thêm khối env:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.kunavo.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-kn-...",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

Mỗi dòng này đều có một cái bẫy:

• ANTHROPIC_BASE_URL chỉ nhận tên miền. Claude Code thêm /v1/messages; khi có /v1 ở cuối, yêu cầu sẽ được gửi đến /v1/v1/messages và trả về 404.
• Hãy dùng ANTHROPIC_AUTH_TOKEN, không dùng ANTHROPIC_API_KEY. Chúng được gửi trong các tiêu đề HTTP khác nhau: tiêu đề đầu tiên gửi Authorization: Bearer và có hiệu lực ngay; tiêu đề thứ hai gửi x-api-key và vẫn phải qua bước phê duyệt một lần được mô tả ở trên.
• Ghi chính xác tên mô hình vào ANTHROPIC_MODEL. Kunavo chỉ nhận diện tên trùng khớp hoàn toàn và không dịch các tên cũ có ngày tháng ở hậu tố.
• Cũng hãy cố định ANTHROPIC_DEFAULT_OPUS_MODEL và ANTHROPIC_DEFAULT_SONNET_MODEL. Model mặc định của Claude Code và bí danh opus trỏ đến Opus mới nhất và nếu Kunavo chưa cung cấp model đó, yêu cầu đầu tiên sẽ trả về 404. Bí danh sonnet hiện yêu cầu Sonnet 5.5, model mà Kunavo không cung cấp: nếu không cố định nó, /model sonnet, giai đoạn thực thi của opusplan và các subagent dùng model: sonnet sẽ nhận 404. Bí danh opus được cố định ở Opus 5.5 (claude-opus-5-5), yêu cầu Claude Code v2.1.280 hoặc mới hơn — trên bản cài đặt cũ, hãy chạy claude update.
• Và cố định ANTHROPIC_DEFAULT_HAIKU_MODEL. Bí danh haiku yêu cầu một ID mà Kunavo không cung cấp (Haiku 5.5 từ v2.1.293): nếu không cố định, /model haiku và các tác tử con có model: haiku sẽ nhận lỗi 404. Dòng này cũng chuyển các lệnh gọi chạy nền mà Claude Code tự thực hiện (tóm tắt, tiêu đề) khỏi mô hình chính.

Không bao giờ đặt khóa trong .claude/settings.json của dự án — tệp này sẽ được đưa lên git và đến tay bất kỳ ai sao chép kho lưu trữ. Trong tiện ích mở rộng VS Code, các biến nằm ở claudeCode.environmentVariables, trong phần cài đặt người dùng của chính VS Code, vì tiện ích mở rộng kiểm tra thông tin xác thực trước khi khởi động.

Giá trên 1M token, lấy từ danh mục:

Để đổi mô hình trong phiên, hãy dùng /model với tên đầy đủ (ví dụ /model claude-opus-5-5) hoặc khởi động Claude Code bằng claude --model claude-opus-5-5. Chi phí sử dụng một tháng và thời điểm gói đăng ký đáng tiền hơn được nêu trong hướng dẫn giá Claude Code.

Cách biết đường dẫn nào đang hoạt động

Trong Claude Code, chạy /status. Dòng Auth token có nghĩa là khóa đang có hiệu lực; dòng Login method cùng với tài khoản claude.ai có nghĩa là biến chưa được đọc. Hai cơ chế này không cộng dồn: khi biến được thiết lập, gói đăng ký sẽ tạm dừng; xóa biến thì Claude Code quay lại dùng gói đăng ký mà không cần cài đặt lại.

Khi đi qua một gateway, có ba thay đổi: Remote Control và tính năng đọc chính tả bằng giọng nói không hoạt động (chúng yêu cầu danh tính claude.ai); /fast có thể báo chế độ nhanh không khả dụng vì bước kiểm tra này đi thẳng đến Anthropic, nhưng các yêu cầu thông thường không thay đổi; và các con số trong /context trở thành ước tính cục bộ. Mã, công cụ, subagent, MCP, hook và bộ nhớ đệm prompt hoạt động như cũ. Chi tiết có trong tài liệu tích hợp (bằng tiếng Anh).

Thanh toán từ Brazil — Pix trong checkout

Gói đăng ký claude.ai là khoản phí định kỳ bằng đô la, yêu cầu thẻ quốc tế được bật cho giao dịch ở nước ngoài. Với tuyến khóa API, khoản nạp tiền đi qua trang thanh toán của Stripe và Pix xuất hiện làm phương thức thanh toán cho người thanh toán từ Brazil: giá tính bằng USD và Stripe hiển thị số tiền đã quy đổi sang real trước khi bạn xác nhận. Thẻ quốc tế (Visa, Mastercard, American Express), Apple Pay, Google Pay và Link cũng xuất hiện tại trang thanh toán. Ví là ví trả trước — khoản nạp tối thiểu $10, số dư không hết hạn, các yêu cầu thất bại không bị tính phí — và mỗi khóa có thể có giới hạn chi tiêu hàng tháng. Hướng dẫn từng bước, theo từng màn hình, nằm trong cách thanh toán API bằng Pix.

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

Sau khi cài đặt

Khi sử dụng lần đầu, hãy chạy /init bên trong dự án: Claude Code đọc kho lưu trữ và tạo CLAUDE.md chứa các lệnh kiểm thử cùng các quy ước mà nó tìm thấy. Hãy xem lại tệp này và giữ cho ngắn gọn — nó được tải trong mọi phiên. Giữa các tác vụ không liên quan, /clear bắt đầu một cuộc trò chuyện mới; khi một tác vụ trở nên quá dài, /compact tóm tắt lịch sử rồi tiếp tục.

Nói thẳng về lựa chọn: với người dùng Claude Code nhiều giờ mỗi ngày, phí tháng của gói đăng ký thường rẻ hơn; pay-as-you-go phù hợp khi mức sử dụng dao động hoặc khi bạn không muốn bị ràng buộc bởi khung 5 giờ — và một tháng không sử dụng có chi phí bằng không. Qua Kunavo, bạn sử dụng năng lực dùng chung, không có hạn mức dành riêng và không có SLA theo hợp đồng; ai cần những bảo đảm đó nên ký hợp đồng trực tiếp với Anthropic.

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