Cách cài đặt Claude Code trên Windows, macOS và Linux — và cách sử dụng mà không cần đăng ký

Để cài 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, CMD, 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ào thư mục dự án và chạy claude; lệnh hữu ích đầu tiên là /init. Có hai cách kết nối: đăng nhập bằng tài khoản Pro, Max, Team, Enterprise hoặc Console (gói miễn phí của Claude.ai không bao gồm Claude Code), hoặc định nghĩa hai biến môi trường, ANTHROPIC_BASE_URL và ANTHROPIC_AUTH_TOKEN, rồi sử dụng API key trả theo mức dùng, không cần đăng ký.

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

Yêu cầu

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 một binary độc lập tự động cập nhật trong nền. Tệp thực thi nằm tại ~/.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 thử. Trong WSL, lệnh cũng giống như vậy.

Cài Claude Code trên Windows

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

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

:: Windows Símbolo del sistema (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. Lệnh CMD trong PowerShell trả về The token '&&' is not a valid statement separator; lệnh PowerShell trong CMD trả về 'irm' is not recognized as an internal or external command (trên Windows tiếng Tây Ban Nha là «không được nhận dạng là lệnh nội bộ hoặc bên ngoài»); còn 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 tương ứng.

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

Với WSL, chạy dòng lệnh của macOS/Linux bên trong terminal WSL và mở claude ở đó, không mở từ PowerShell hoặc CMD.

Với trình quản lý gói

Cũng hoạt động, nhưng có một điểm khác biệt quan trọng: mặc định không có trình nào tự động cập nhật (bạn sẽ phải chạy brew upgrade claude-code hoặc winget upgrade Anthropic.ClaudeCode). Ngoài ra còn có các kho apt, dnf và apk được 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 — requiere Node.js 22 o posterior; nunca con sudo
npm install -g @anthropic-ai/claude-code

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

Kiểm tra cài đặt

claude --version   # imprime la versión, por ejemplo 2.1.211 (Claude Code)
claude doctor      # diagnóstico de la instalación y la configuración, sin abrir sesión

Hãy dùng claude doctor: không cần đăng nhập, lệnh này hiển thị trạng thái cài đặt, lỗi trong các tệp cấu hình và giải pháp được đề xuất. Đây là cách nhanh nhất để biết lỗi nằm ở quá trình cài đặt hay cấu hình.

Nếu thấy command not found: claude (hoặc trên Windows, thấy claude không được nhận dạng), thư mục cài đặt chưa nằm trong PATH. Trên macOS và Linux, mở một terminal mới; nếu vẫn không đượ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 này từ PowerShell:

# 1. Comprueba si la carpeta de instalación ya está en el PATH
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. ¿Sin salida? Añádela al PATH de usuario y abre una terminal nueva
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. En la terminal nueva: si hay dos instalaciones, verás dos rutas
where.exe claude

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

Tùy chọn A — đăng nhập bằng gói đăng ký của bạn

Trong thư mục dự án, chạy claude và hoàn tất đă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 dễ gây nhầm lẫn: nếu biến ANTHROPIC_API_KEY đã được định nghĩa, Claude Code sẽ chỉ hỏi một lần bạn có muốn sử dụng key đó không. Nếu bạn trả lời không, Claude Code sẽ bỏ qua biến này từ đó về sau mà 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: /config → Sử dụng API key tùy chỉnh.

Tùy chọn B — không cần đăng ký, dùng API key trả theo mức sử dụng

Claude Code đọc trực tiếp ANTHROPIC_BASE_URL, vì vậy trỏ nó tới 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 hoặc binary đã sửa đổi. Các bước: tạo tài khoản, nạp số dư (tối thiểu $10), tạo key sk-kn- trong bảng điều khiển key (chỉ hiển thị một lần), rồi thêm khối env này vào cấu hình người dùng, ~/.claude/settings.json (trên Windows, %USERPROFILE%\.claude\settings.json). Nhờ vậy, tất cả terminal, tiện ích mở rộng trình chỉnh sửa và tiến trình nền đều có thể sử dụng:

{
  "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"
  }
}

Để thử trước trong một cửa sổ PowerShell duy nhất:

# Solo para esta ventana de PowerShell (en macOS/Linux: export VARIABLE=valor)
$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

• ANTHROPIC_BASE_URL chỉ chứa domain. Claude Code tự thêm /v1/messages; nếu kết thúc bằng /v1, yêu cầu sẽ đi tới /v1/v1/messages và trả về 404.
• Dùng ANTHROPIC_AUTH_TOKEN, không dùng ANTHROPIC_API_KEY. Hai biến này nằm trong các header HTTP khác nhau: biến thứ nhất gửi Authorization: Bearer và hoạt động ngay; biến thứ hai gửi x-api-key và còn đi qua bước phê duyệt một lần ở trên.
• Nhập chính xác tên model vào ANTHROPIC_MODEL. Kunavo chỉ nhận diện tên trùng khớp tuyệt đối và không dịch các tên cũ có ngày tháng.
• Cũng cố định ANTHROPIC_DEFAULT_OPUS_MODEL. Mô hình mặc định của Claude Code và bí danh opus trỏ đến Opus mới nhất; nếu Kunavo chưa cung cấp mô hình đó, yêu cầu đầu tiên sẽ trả về 404. Ở đây, bí danh opus được cố định ở Claude Opus 5.5 (claude-opus-5-5), yêu cầu Claude Code v2.1.280 trở lên; với phiên bản cũ hơn, hãy chạy claude update.
• Và cũng ANTHROPIC_DEFAULT_SONNET_MODEL. Bí danh sonnet yêu cầu Sonnet 5.5, mô hình mà Kunavo không cung cấp: nếu không có biến này, /model sonnet, giai đoạn thực thi của opusplan và các tác tử con được cấu hình bằng sonnet sẽ trả về 404. Đặt biến này thành claude-sonnet-5 sẽ tránh được lỗi đó.
• Làm tương tự với 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 thiếu biến này, /model haiku và các tác tử con được cấu hình dùng haiku sẽ trả về 404. Cố định giá trị thành claude-haiku-4-5 sẽ khắc phục việc đó, đồng thời 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.

Tuyệt đối không đặt key trong .claude/settings.json của dự án: tệp này sẽ được đưa vào repository. Trong tiện ích mở rộng VS Code, các biến được đặt trong claudeCode.environmentVariables, bên trong cấu hình người dùng của 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.

Mức giá trên mỗi 1M token, đọc từ catalog:

Cách biết tùy chọn nào đang hoạt động

Trong Claude Code, chạy /status. Một dòng Auth token nghĩa là key đang được sử dụng; một dòng Login method cùng tài khoản claude.ai nghĩa là biến chưa được đọc. Hai tùy chọn không cộng dồn: khi biến còn tồn tại, gói đăng ký sẽ bị tạm ngưng; xóa biến và Claude Code sẽ quay lại dùng gói đăng ký mà không cần cài đặt lại.

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

Cách sử dụng Claude Code: những bước đầu tiên

# 1. Arranca siempre dentro de la carpeta del proyecto
cd ~/proyectos/mi-app
claude

# 2. Primer comando: lee el repositorio y genera CLAUDE.md
> /init

# 3. Pide las tareas en español y con la ruta del archivo
> cambia la validación de src/api/user.ts a zod y arregla los tests

# 4. Para tareas que tocan muchos archivos: Shift+Tab activa el modo plan

Claude Code yêu cầu quyền trước khi chỉnh sửa tệp hoặc chạy lệnh; nếu đi sai hướng, nhấn Esc để dừng và /rewind để quay lại điểm trước đó. CLAUDE.md mà /init tạo ra chỉ là bản nháp: hãy giữ trong đó những điều bạn sẽ lặp lại ở mỗi phiên (lệnh test, quy ước, các thư mục không được chỉnh sửa). Tệp này được tải trong mỗi phiên và gửi trong mỗi yêu cầu, đồng thời Anthropic khuyến nghị không vượt quá 200 dòng.

• Chuyển model: /model rồi nhập tên đầy đủ, chẳng hạn /model claude-opus-5, hoặc khởi động bằng claude --model claude-opus-5. Hãy chuyển model giữa các tác vụ: mỗi model có cache riêng, và chuyển giữa chừng sẽ buộc hệ thống đọc lại toàn bộ cuộc hội thoại mà không có cache.
• Dùng /clear giữa các tác vụ không liên quan. Bắt đầu một cuộc hội thoại mới không tốn phí; cuộc hội thoại trước có thể khôi phục bằng /resume.
• Dùng /compact khi tác vụ kéo dài: tóm tắt lịch sử rồi tiếp tục. Với API key, cache mặc định tồn tại trong năm phút, vì vậy hãy compact trước một khoảng dừng dài, không phải sau đó.
• Chi phí của một phiên: /usage hiển thị số token, nhưng số tiền được tính là ước tính cục bộ theo giá niêm yết của Anthropic; với Kunavo, khoản phí thực tế nằm trên trang sử dụng của bạn.

Thanh toán và sự trung thực về lựa chọn

Số dư được trả trước qua Stripe: thẻ (Visa, Mastercard, American Express, JCB, UnionPay), Apple Pay, Google Pay hoặc Link; ghi nợ trực tiếp SEPA không khả dụng. Mức nạp tối thiểu là $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ó giới hạn chi tiêu hàng tháng. Tất cả giá được nêu trên trang giá.

Nếu bạn sử dụng Claude Code nhiều giờ mỗi ngày, phí cố định của gói đăng ký thường rẻ hơn; hình thức trả theo mức sử dụng phù hợp khi nhu cầu không đều hoặc bạn không muốn phụ thuộc vào cửa sổ 5 giờ, và một tháng không hoạt động sẽ có chi phí bằng không. So sánh đầy đủ, bằng tiếng Anh, có tại Giá Claude Code. Khi sử dụng qua Kunavo, bạn dùng năng lực dùng chung, không có quota riêng và không có SLA theo hợp đồng: nếu cần những đảm bảo đó, hãy ký hợp đồng trực tiếp với Anthropic.

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