Cài đặt Claude Code từ zero: Hướng dẫn đầy đủ cho macOS, Windows WSL và Linux

Cài đặt Claude Code trên macOS, Windows WSL và Linux từ A-Z. Fix lỗi 'command not found', thiết lập API key Anthropic và bắt đầu pair programming với AI ngay hôm nay.

Định nghĩa

Claude Code không phải là app chat thông thường — nó là AI coding agent sống trực tiếp trong terminal của bạn. Khác với Claude web hay desktop app, đây là công cụ có quyền đọc/ghi file local, thực thi lệnh bash và tự động hóa workflow. Việc cài đặt chính là quá trình "cấp quyền" cho AI để nó trở thành pair programmer 24/7 trên máy tính của bạn.

Giải thích chi tiết

Chuẩn bị trước khi cài

Trước khi chạy lệnh cài đặt, hãy kiểm tra bạn đã có:

Node.js 18+: Kiểm tra bằng node --version. Nếu chưa có, nên dùng nvm (phổ biến trong cộng đồng dev Việt Nam) để quản lý phiên bản.
Git: Đã cài và cấu hình user.name và user.email (git config --global user.name "Your Name").
Tài khoản Anthropic: Đăng ký tại console.anthropic.com và tạo API key.
Terminal hiện đại: Terminal.app/iTerm2 (macOS), Windows Terminal với WSL2 (Windows — đây là combo phổ biến nhất tại VN), hoặc GNOME Terminal (Linux).

Cài đặt trên macOS (Homebrew — Khuyên dùng)

Nếu bạn dùng MacBook (M1/M2/M3 — rất phổ biến trong giới dev Việt Nam), cách nhanh nhất là dùng Homebrew:

brew install claude

Không dùng Homebrew? Dùng npm:

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

Cài đặt trên Windows WSL2 (Phổ biến nhất tại VN)

Tại Việt Nam, đa số developer dùng Windows với WSL2 để có môi trường Linux chuẩn khi làm việc remote cho công ty US/EU. Đây là flow cài đặt chuẩn trên Ubuntu WSL:

# Cập nhật hệ thống
sudo apt update && sudo apt upgrade -y

# Cài Node.js 20 (LTS)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# Cài Claude Code toàn cục
npm install -g @anthropic-ai/claude-code

Quan trọng: Claude Code không chạy được trên PowerShell hay CMD gốc. Bạn bắt buộc phải dùng WSL2 (Ubuntu/Debian) để có môi trường POSIX đầy đủ.

Cài đặt trên Linux native (Ubuntu/Debian)

Tương tự WSL, nếu bạn dùng máy Linux cài natively (thường thấy ở các server dev hoặc máy dual-boot):

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

Nếu gặp lỗi permission, đừng dùng sudo — xem phần sửa lỗi bên dưới.

Sửa lỗi "claude: command not found"

Đây là lỗi 90% người mới gặp sau khi cài. Nguyên nhân: thư mục npm global chưa được thêm vào PATH.

Trên macOS với Zsh (mặc định từ Catalina):

echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.zshrc
source ~/.zshrc

Trên Linux/WSL với Bash:

echo 'export PATH="$PATH:/usr/local/bin"' >> ~/.bashrc
source ~/.bashrc

Nếu bạn dùng nvm (khuyên dùng cho dev Việt Nam vì dễ switch Node version):

echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.bashrc
source ~/.bashrc

Thiết lập API Key Anthropic

Claude Code cần xác thực qua API key. Có hai cách:

Cách 1: Interactive login (Khuyên dùng — an toàn, không lộ key)

claude auth

Lệnh này mở trình duyệt để đăng nhập Anthropic và cấp quyền OAuth.

Cách 2: Environment variable (Dùng cho CI/CD hoặc máy không có GUI)

export ANTHROPIC_API_KEY="sk-ant-xxxxx"

Thêm vào ~/.zshrc hoặc ~/.bashrc để persistent giữa các session.

Ví dụ thực tế

Cài đặt hoàn chỉnh trên Windows WSL2 cho dev Việt Nam

Tình huống: Bạn vừa mua laptop Windows, cài WSL2 Ubuntu để làm việc remote cho công ty startup US. Chưa có gì cả.

# 1. Update và cài git, curl
sudo apt update && sudo apt install -y curl git

# 2. Cài Node.js 20 LTS
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# 3. Verify Node
node --version  # v20.x.x

# 4. Cài Claude Code
npm install -g @anthropic-ai/claude-code

# 5. Fix PATH nếu cần (thường cần với nvm)
echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.bashrc
source ~/.bashrc

# 6. Kiểm tra
claude --version

# 7. Auth lần đầu
claude auth

Sau bước 7, WSL sẽ tự động mở trình duyệt Windows để bạn đăng nhập. Xong thì quay lại terminal gõ claude là vào giao diện tương tác.

Sửa lỗi permission trên MacBook M1/M2/M3

Bạn cài bằng npm nhưng gặp EACCES: permission denied. Đừng bao giờ dùng sudo npm install -g — đây là anti-pattern gây rối permission sau này.

Thay vào đó, đổi thư mục npm global về home:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# Giờ cài lại không cần sudo
npm install -g @anthropic-ai/claude-code

Chạy lần đầu trong dự án React tại công ty outsourcing

Giả sử bạn vừa clone repo dự án React của khách hàng về ~/projects/client-vietnam-dashboard:

cd ~/projects/client-vietnam-dashboard

# Khởi động Claude Code
claude

Lần đầu chạy trong directory này, Claude sẽ hỏi: "Should I create a CLAUDE.md in this directory?" — hãy chọn Yes. Đây là file bộ nhớ dự án, giúp AI nhớ coding standards và context giữa các phiên làm việc, rất quan trọng khi bạn làm việc với codebase lớn của khách hàng Nhật hoặc US.

Ứng dụng

Dành cho sinh viên CNTT Việt Nam (FPT, HUST, HCMUS)

Vibe coding: Người chưa biết code cũng tạo được MVP bằng cách mô tả ý tưởng startup bằng tiếng Việt, Claude sẽ tự viết code và chạy thử ngay trên laptop.
Học tập: Dùng Claude để giải thích đoạn code trong bài tập Data Structures, hoặc refactor assignment trước khi nộp thầy để code sạch hơn.

Dành cho developer chuyên nghiệp tại các công ty như Grab, Shopee, Tiki

Pair programming 24/7: Cài đặt một lần, dùng cho mọi microservice. Claude nhớ coding style của bạn qua file CLAUDE.md trong ~/.claude/ và các project-specific configs.
Tự động hóa workflow: Sau khi cài, tận dụng Slash Commands như /commit để tự động viết commit message theo conventional commits, hoặc /test để chạy unit test trước khi push lên GitLab công ty.

Dành cho team lead và doanh nghiệp

Chuẩn hóa môi trường: Cài đặt Claude Code trên máy chủ CI/CD với headless mode (claude -p) để tự động review code khi có pull request.
Onboarding nhanh: Developer mới join team chỉ cần clone repo, chạy claude, và AI sẽ hướng dẫn cách setup môi trường dựa trên README và cấu trúc thực tế của codebase — giảm thời gian onboarding từ 3 ngày xuống 2 giờ.

So sánh

Đặc điểm	Claude Code (CLI)	Claude Desktop (Web)	Cursor/Copilot
Cách tương tác	Terminal, gõ lệnh trực tiếp	Chat interface, click chuột	IDE integrated
Quyền hạn	Đọc/ghi file local, chạy bash, tự commit git	Chỉ đọc file upload thủ công	Giới hạn trong IDE scope
Tự động hóa	Chạy được trong script, CI/CD, hooks	Không tự động được	Hạn chế
Context window	200K tokens, nhìn cả project	Tương tự nhưng phải upload	Theo file đang mở
Độ trễ	Cực nhanh (terminal native)	Chậm hơn (qua browser)	Trung bình

Kết luận: Claude Code CLI là lựa chọn cho những ai muốn AI "sống" trong terminal và có khả năng tự động hóa thực sự, trong khi Desktop app phù hợp cho người dùng không kỹ thuật chỉ cần chat thông thường.