Cách cài đặt Claude Code trên Windows & macOS (2026): hướng dẫn từng bước

mọi lệnh và số phiên bản trong bài nên được đối chiếu lại tại tài liệu chính thức code.claude.com/docs trước khi làm theo, vì Anthropic cập nhật khá nhanh.

Mình là Jasmine, dev dùng Claude Code hằng ngày trên cả Windows lẫn macOS. Bài này gộp cả hai hệ điều hành vào một trang, đi từng bước có lệnh copy được, kèm cách chọn phương pháp phù hợp, cách kiểm tra và các lỗi hay gặp. Nếu bạn chưa rõ công cụ này là gì, đọc trước bài Claude Code là gì rồi quay lại đây.

Cần chuẩn bị gì trước khi cài? (Yêu cầu hệ thống)

Trước khi gõ lệnh, kiểm tra nhanh các điều kiện sau để tránh cài xong mà không chạy được:

• Hệ điều hành: Windows 10 (bản 1809 trở lên) hoặc Windows 11; hoặc macOS (Apple Silicon và Intel đều được).
• Tài khoản Claude trả phí - bắt buộc: Claude Code cần gói Pro ($20/tháng), Max 5x ($100/tháng), Max 20x ($200/tháng), gói Team/Enterprise, hoặc thanh toán theo token qua Anthropic Console (API). Gói Free trên claude.ai không mở khoá được Claude Code.
• Terminal: PowerShell hoặc Windows Terminal (Windows); Terminal hoặc iTerm2 (macOS).
• Tuỳ phương pháp: nếu cài qua npm, bạn cần Node.js 22 trở lên. Nếu dùng native installer thì không cần Node. Trên Windows, cài WSL2 hoặc Git for Windows sẽ cho trải nghiệm dòng lệnh mượt hơn.

Lưu ý quan trọng: đây là chỗ nhiều người mới vấp - bạn có thể tải và cài Claude Code bằng gói Free, nhưng khi đăng nhập sẽ bị chặn vì tài khoản chưa có quyền. Hãy nâng cấp lên gói trả phí trước, hoặc chuẩn bị một API key từ Console.

Một mẹo nhỏ trước khi bắt đầu: nếu máy bạn đã có sẵn Node, gõ node --version để biết đang ở phiên bản nào - nếu là bản cũ (18 hoặc 20) bạn sẽ cần nâng cấp trước khi cài qua npm, hoặc đơn giản là chuyển sang native installer để bỏ qua Node hoàn toàn. Về dung lượng, Claude Code là công cụ dòng lệnh nhẹ, không đòi nhiều ổ đĩa hay RAM; yếu tố quyết định tốc độ là kết nối mạng chứ không phải cấu hình máy.

Cách chọn phương pháp cài phù hợp

Có bốn cách phổ biến. Nếu bạn phân vân, cứ chọn Native installer - nó gọn nhất và tự cập nhật. Bảng dưới giúp bạn quyết định trong 30 giây:

Cài đặt Claude Code trên Windows

Windows 2026 đã có native installer và WinGet, nên không còn bắt buộc phải dùng WSL như trước. Tuy vậy, WSL2 vẫn cho trải nghiệm dòng lệnh giống Linux mượt nhất. Chọn một trong ba cách dưới.

Cách 1 - Native installer (khuyến nghị)

Mở PowerShell và chạy lệnh cài một dòng của Anthropic. Cách này không cần Node.js và tự cập nhật về sau:

irm https://claude.ai/install.ps1 | iex

Lệnh này tải bản ổn định phù hợp với OS/kiến trúc máy bạn, cài binary vào thư mục người dùng và tự thêm vào PATH. Sau khi cài xong, đóng và mở lại terminal để PATH được nạp, rồi kiểm tra bằng claude --version. Nếu PowerShell chặn script vì Execution Policy, bạn có thể tạm nới quyền cho phiên hiện tại bằng Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass rồi chạy lại.

Cách 2 - WinGet

Nếu bạn đã quen quản lý phần mềm bằng WinGet, có thể cài trực tiếp:

winget install Anthropic.ClaudeCode

WinGet phù hợp với ai muốn cập nhật đồng bộ cùng các phần mềm khác qua winget upgrade.

Cách 3 - WSL2 + npm (môi trường Linux)

Đây là lựa chọn cho ai muốn môi trường Linux thật trên Windows. Mở PowerShell với quyền admin và bật WSL2:

wsl --install

Khởi động lại máy nếu được yêu cầu, mở Ubuntu, rồi cài Node.js 22 LTS bên trong WSL (dùng nvm hoặc kho chính thức của NodeSource). Sau đó cài Claude Code qua npm:

npm install -g @anthropic-ai/claude-code

Vài lưu ý quan trọng khi dùng WSL2:

• KHÔNG chạy sudo npm install -g - cài global bằng sudo dễ gây lỗi quyền về sau. Hãy cấu hình npm prefix trong thư mục người dùng, hoặc dùng nvm.
• Đặt code trong filesystem WSL (ví dụ ~/projects) thay vì mount /mnt/c/... để I/O nhanh hơn nhiều.
• Nên cài Git for Windows (hoặc git trong WSL) - Claude Code hoạt động tốt nhất khi có git. Nếu chỉ dùng PowerShell thuần không có git, một số thao tác sẽ hạn chế.

Cài đặt Claude Code trên macOS

Trên macOS bạn có hai cách gọn: native installer/Homebrew (không cần Node) hoặc npm nếu bạn đã có Node. Cả hai phương pháp đều chạy tốt trên máy Apple Silicon (M1/M2/M3 trở lên) lẫn Mac Intel; installer tự nhận đúng kiến trúc nên bạn không phải chọn thủ công. Nếu bạn chưa từng dùng Terminal trên Mac, mở nó bằng Spotlight (Cmd+Space, gõ "Terminal") là xong.

Cách 1 - Native installer / Homebrew

Cách nhanh nhất, không cần Node.js, chạy trong Terminal:

curl -fsSL https://claude.ai/install.sh | bash

Nếu đã dùng Homebrew và muốn quản lý cùng các tool khác:

brew install --cask claude-code

Cách 2 - npm

Nếu bạn quen Node, cài Node.js 22+ trước (tải LTS từ nodejs.org hoặc chạy brew install node), rồi cài Claude Code:

brew install node
npm install -g @anthropic-ai/claude-code

Kiểm tra Node đủ mới bằng node --version (phải là 22 trở lên). Nếu gặp lỗi quyền khi cài global, tránh dùng sudo - thay vào đó đặt lại npm prefix về thư mục người dùng.

Xác thực & phiên chạy đầu tiên

Cài xong chưa đủ - bạn cần đăng nhập để mở khoá. Vào thư mục một dự án bất kỳ rồi chạy:

cd duong-dan-du-an
claude

Lần đầu chạy, Claude Code sẽ mở trình duyệt để bạn đăng nhập tài khoản Anthropic (hoặc dán API key nếu dùng Console). Đăng nhập xong, quay lại terminal là phiên làm việc bắt đầu. Nếu bạn đăng nhập bằng tài khoản Pro/Max, hạn mức sử dụng gắn theo gói đăng ký; nếu dùng API key thì tính theo token - hai cách này tách biệt, chọn cách nào tuỳ nhu cầu và ngân sách của bạn.

Ngay lần đầu, hãy thử một câu lệnh đơn giản như "liệt kê cấu trúc thư mục này" để chắc chắn Claude Code đọc được project. Đây cũng là lúc tốt để làm quen: gõ yêu cầu bằng tiếng Việt hay tiếng Anh đều được, và bạn luôn xem trước thay đổi trước khi đồng ý ghi file.

Claude Code cũng hỏi bạn có tin tưởng thư mục (trust folder) hiện tại không. Đây là cơ chế an toàn: công cụ chỉ đọc/ghi file trong thư mục bạn cho phép. Với dự án lạ mới clone về, hãy cân nhắc trước khi cấp quyền.

Kiểm tra cài đặt thành công (verify)

Đa số bài hướng dẫn bỏ qua bước này, nhưng verify giúp bạn phát hiện sớm lỗi PATH hay phiên bản. Chạy các lệnh sau và đối chiếu kết quả mong đợi:

Nếu claude --version chạy được và claude doctor không báo lỗi đỏ, coi như bạn đã cài thành công.

Các lỗi cài đặt thường gặp & cách khắc phục nhanh

Dưới đây là những lỗi mình gặp nhiều nhất khi cài trên cả hai hệ điều hành, kèm cách xử lý nhanh:

• 'claude' is not recognized / command not found: file thực thi chưa nằm trong PATH. Đóng và mở lại terminal; nếu vẫn lỗi, thêm thư mục cài (thường là ~/.local/bin) vào PATH rồi khởi động lại terminal.
• Node quá cũ: npm báo lỗi khi Node dưới mức yêu cầu. Nâng Node lên bản 22+ bằng nvm hoặc tải lại LTS từ nodejs.org.
• Lỗi quyền (EACCES) khi npm install -g: đừng vá bằng sudo. Cấu hình lại npm prefix về thư mục người dùng, hoặc chuyển sang native installer để né hẳn vấn đề quyền global.
• WSL chưa bật (Windows): nếu wsl --install báo lỗi, bật hai tính năng "Virtual Machine Platform" và "Windows Subsystem for Linux" trong Windows Features rồi khởi động lại.
• Terminal chưa refresh: sau khi cài, biến môi trường mới chỉ áp dụng cho phiên terminal mới. Luôn mở terminal mới trước khi thử lại.

Gặp lỗi khác hoặc muốn đào sâu hơn? Xem bài chuyên đề khắc phục lỗi Claude Code thường gặp - nơi mình gom đầy đủ cách sửa từng tình huống.

Cập nhật & gỡ cài đặt

Cập nhật:

• Native installer: tự cập nhật nền, bạn không cần làm gì. Muốn kiểm tra thủ công có thể chạy claude update.
• npm: chạy npm update -g @anthropic-ai/claude-code.

Gỡ cài đặt:

• npm: npm uninstall -g @anthropic-ai/claude-code.
• Homebrew: brew uninstall --cask claude-code.
• Native installer: xoá binary trong ~/.local/bin và thư mục cấu hình liên quan.

Bước tiếp theo sau khi cài

Đã có Claude Code chạy được, giờ là lúc dùng thật. Gợi ý lộ trình:

• Người mới nên đọc 10 bước bắt đầu cho người mới để nắm quy trình làm việc cơ bản.
• Nếu bạn code trong VS Code, xem cách dùng Claude Code trong VS Code để tích hợp editor.
• Chưa chắc về khái niệm? Quay lại Claude Code là gì.

Khi đã quen tay, bạn có thể tăng tốc bằng các bộ kit skills/subagents dựng sẵn - ví dụ bộ kit AgentKit cho Claude Code (đọc thêm tại Engineer Kit — giảm 20%, còn $79.20) giúp bỏ qua bước tự cấu hình từng skill. Không bắt buộc - Claude Code vẫn dùng tốt khi chưa cần đến kit.

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

Cài Claude Code có mất phí không?

Bản thân việc cài đặt miễn phí, nhưng để dùng bạn cần tài khoản Claude trả phí: Pro ($20/tháng), Max 5x ($100/tháng), Max 20x ($200/tháng), gói Team/Enterprise, hoặc trả theo token qua Anthropic Console. Gói Free của claude.ai không mở khoá được Claude Code.

Có cần biết code không?

Nên có kiến thức lập trình cơ bản để làm việc hiệu quả, nhưng không bắt buộc phải là chuyên gia. Bạn cần biết mở terminal, di chuyển thư mục và đọc hiểu kết quả. Người mới hoàn toàn vẫn dùng được nếu chịu khó làm theo hướng dẫn từng bước.

Trên Windows có bắt buộc dùng WSL không?

Không. Windows 2026 đã có native installer và WinGet nên bạn cài trực tiếp mà không cần WSL. Tuy nhiên WSL2 vẫn cho trải nghiệm giống Linux mượt nhất, phù hợp nếu dự án của bạn quen môi trường POSIX.

Cần Node.js phiên bản nào?

Chỉ khi cài qua npm bạn mới cần Node, và nên dùng Node.js 22 trở lên. Nếu dùng native installer thì không cần Node.js chút nào.

Cài trên máy yếu được không?

Được. Claude Code chạy phần lớn xử lý trên máy chủ Anthropic nên không đòi cấu hình máy mạnh; điều kiện thật sự là kết nối mạng ổn định và một tài khoản trả phí. Máy cấu hình khiêm tốn vẫn dùng bình thường.

Gỡ Claude Code ra sao?

Tuỳ cách cài: npm dùng npm uninstall -g @anthropic-ai/claude-code; Homebrew dùng brew uninstall gói tương ứng; native installer thì xoá binary trong ~/.local/bin cùng thư mục cấu hình.

Kết luận

Cài đặt Claude Code trên Windows hay macOS đều xoay quanh ba việc: chọn phương pháp (native installer là an toàn nhất cho người mới), đăng nhập tài khoản trả phí, rồi verify bằng claude --version và claude doctor. Nếu vướng, quay lại mục lỗi thường gặp hoặc bài khắc phục lỗi Claude Code. Cài xong, bắt đầu với 10 bước cho người mới để có phiên làm việc đầu tiên thật sự hiệu quả.

Nguồn lệnh cài đặt và yêu cầu hệ thống: tài liệu chính thức Anthropic tại code.claude.com/docs (truy cập 08/2026).