Cài đặt Claude Code trên Windows, macOS và Linux (cập nhật 2026)

Claude Code là gì và chạy ở đâu?

Claude Code là coding agent của Anthropic: bạn giao việc bằng lời, nó đọc mã nguồn, sửa file, chạy lệnh và test ngay trong thư mục dự án. Công cụ chạy trong terminal, có extension cho VS Code (dùng được cả trong Cursor), plugin cho JetBrains, và có trong ứng dụng Claude trên máy tính.

Bài này hướng dẫn cài bản dòng lệnh, nền tảng mà các bản khác dùng chung. Extension VS Code tự mang theo bản dòng lệnh của nó, còn plugin JetBrains cần cài bản dòng lệnh trước. Tổng quan những việc Claude Code làm được có ở bài Claude Code là gì.

Yêu cầu hệ thống

Theo tài liệu cài đặt chính thức tại thời điểm cập nhật bài:

• macOS 13 trở lên, Windows 10 bản 1809 trở lên, Ubuntu 20.04, Debian 10 hoặc Alpine 3.19 trở lên.
• Tối thiểu 4 GB RAM, chip x64 hoặc ARM64.
• Ở quốc gia Anthropic hỗ trợ; Việt Nam nằm trong danh sách.
• Một cách trả tiền: gói Claude trả phí, key của Claude Console, hoặc API key của một gateway. Gói Free không gồm Claude Code; cách dùng thử có ở bài Claude Code có miễn phí không.

Cài trên macOS, Linux và WSL

Bộ cài native là cách được khuyên dùng: không cần Node.js, và tự cập nhật ở nền. Mở terminal và chạy:

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

# Hoặc dùng Homebrew (bản này không tự cập nhật, cập nhật bằng brew upgrade)
brew install --cask claude-code

Cài trên Windows

Trên Windows có ba cách tương đương, chọn một. Git for Windows không bắt buộc: thiếu Git Bash thì Claude Code dùng PowerShell để chạy lệnh.

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

# CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

# WinGet
winget install Anthropic.ClaudeCode

Kiểm tra bản cài và cập nhật

Mở một terminal mới rồi kiểm tra. claude doctor báo những gì chưa ổn, như đường dẫn PATH hay quyền ghi; claude update cập nhật lên bản mới.

claude --version
claude doctor
claude update

Đăng nhập: gói thuê bao hay API key

Chạy claude trong thư mục dự án. Lần đầu, Claude Code hỏi cách xác thực. Có hai lối chính:

• Đăng nhập tài khoản Claude có gói Pro, Max, Team hoặc Enterprise: tính vào hạn mức theo phiên và theo tuần của gói.
• Dùng API key: tính theo token, không có giới hạn theo phiên hay theo tuần. Với gateway trả bằng VND, đặt ANTHROPIC_BASE_URL và ANTHROPIC_AUTH_TOKEN theo bài dùng Claude Code với API key riêng; khi các biến này có mặt, Claude Code không hỏi đăng nhập nữa.

Những bước cũ không còn đúng

Nhiều hướng dẫn tiếng Việt viết năm ngoái đã lỗi thời ở các điểm sau:

• Cài bằng npm install -g @anthropic-ai/claude-code: cách này vẫn chạy (cần Node.js 22 trở lên) nhưng README chính thức đã ghi là ngừng khuyến nghị; nên dùng bộ cài native, Homebrew hoặc WinGet.
• Bắt buộc cài WSL mới chạy được trên Windows: Claude Code đã chạy trực tiếp trên Windows.
• Lệnh /cost: đã gộp vào /usage. Phím tắt # để ghi nhớ đã bị bỏ; sửa trí nhớ bằng /memory hoặc file CLAUDE.md.
• Model mặc định: hiện là Opus 5.5, các alias sonnet, haiku trỏ tới đời 5.5.

Lỗi cài đặt hay gặp

Ba lỗi chiếm phần lớn các ca không chạy được sau khi cài:

• “command not found: claude”: thêm ~/.local/bin vào PATH trong file cấu hình shell, rồi mở terminal mới.
• Không tìm thấy Git Bash trên Windows dù đã cài Git: đặt biến CLAUDE_CODE_GIT_BASH_PATH trỏ tới bash.exe.
• Báo không hỗ trợ model sau khi chọn model mới: bản cài đã cũ, chạy claude update.
• Các lỗi khi đang dùng có ở bài lỗi Claude Code thường gặp và cách sửa.

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