Cách cài đặt Claude Code trên Windows, macOS và Linux (tháng 5, 2026)

Claude Code tăng vọt từ con số 0 lên hơn 1 triệu lượt tìm kiếm mỗi tháng, dù ra mắt chưa đầy 1 năm. Nếu bạn lướt thấy nhiều người bàn tán rồi tò mò muốn tự tay cài thử, thì đây là hướng dẫn setup nhanh gọn trong 5 phút cho mọi hệ điều hành.

Bốn điều cần biết trước khi bắt đầu:

1. Bạn cần tài khoản trả phí. Các gói Claude Pro ($20/tháng), Max, Team, Enterprise hoặc tài khoản Console đều mở khóa được Claude Code. Gói miễn phí của Claude.ai không hỗ trợ tính năng này.
2. Claude Code hoạt động trên terminal — cái cửa sổ dòng lệnh quen thuộc. (Nếu ngại gõ lệnh, Anthropic vẫn có app desktop để bạn dùng thay thế.)
3. Native installer là cách cài chính thức tính đến 2026. Từ đầu năm 2026, Anthropic còn hỗ trợ thêm Homebrew, WinGet và các repo package Linux có chữ ký số. Bạn nào quen dùng package manager sẽ thấy tiện lợi hơn. Đường cài qua npm cũ vẫn dùng được nhưng Anthropic đã khuyến cáo không nên dùng nữa.
4. Lưu ý nhỏ về token: Các bản từ v2.1.100 trở đi có thể khiến lượng token tiêu thụ tăng khoảng 40%. Bản mới nhất tính đến ngày 4 tháng 5 là v2.1.126 — cách khắc phục mình sẽ chỉ ở phần dưới.

Chọn OS của bạn — mỗi đường install chỉ một lệnh:

Bắt đầu thôi.

Yêu cầu hệ thống

Trước khi bấm cài, hãy chắc chắn máy bạn đủ điều kiện hỗ trợ:

Windows 11 thì chạy rất mượt. Còn nếu bạn đang dùng macOS Monterey (12) hoặc bản cũ hơn, thì hãy update hệ điều hành trước khi tiếp tục nhé.

Cài đặt trên Windows

Trên Windows, bạn có ba lựa chọn cài đặt. Hãy chọn theo nhu cầu: nếu bạn cần môi trường giống Linux (WSL) hoặc muốn cài native ngay trên PowerShell/Git Bash.

Windows native: PowerShell (đường đơn giản nhất)

Mở PowerShell (không cần quyền Admin) rồi chạy lệnh sau:

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

Nếu lệnh irm báo lỗi “is not recognized…”, nghĩa là bạn đang ở CMD chứ không phải PowerShell. Dấu nhắc PS C:\ báo hiệu PowerShell, còn C:\ không có PS là CMD. Nếu muốn dùng CMD, hãy chạy:

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

Sau khi cài xong, hãy đóng và mở lại terminal để hệ thống cập nhật đường dẫn PATH, rồi kiểm tra lại bằng lệnh:

claude --version
claude doctor

Mẹo nhỏ: Nên cài Git for Windows trước khi chạy claude. Anthropic khuyên vậy vì Claude Code cần Git Bash để hoạt động mượt mà. Nếu thiếu Git Bash, nó sẽ tự chuyển về dùng PowerShell, khiến bạn mất đi nhiều tính năng hỗ trợ.

Nếu claude doctor báo lỗi không tìm thấy Git Bash, bạn có thể chỉ rõ đường dẫn trong file ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

Windows native: WinGet (cài qua package manager)

Anthropic đã đưa Claude Code lên package manager chính thức của Microsoft:

winget install Anthropic.ClaudeCode

Lưu ý: Cài qua WinGet không tự động cập nhật. Bạn cần chạy winget upgrade Anthropic.ClaudeCode định kỳ để giữ bản mới nhất.

Cài đặt trên Windows với WSL

WSL 2 (Windows Subsystem for Linux) giúp bạn chạy môi trường Linux nguyên bản ngay trên Windows. Anthropic khuyên dùng WSL nếu bạn muốn tách biệt môi trường chạy lệnh (sandbox) hoặc đã quen thuộc với các công cụ Linux.

Bước 1 — Cài WSL. Mở PowerShell với quyền Administrator rồi chạy:

wsl --install

Khởi động lại máy khi hệ thống yêu cầu. Sau khi vào lại Windows, mở terminal Ubuntu từ menu Start.

Bước 2 — Cài Claude Code trong WSL. Tại dấu nhắc lệnh Ubuntu:

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

Bước 3 — Kiểm tra và bắt đầu làm việc với dự án:

claude --version
claude doctor
cd /mnt/c/Users/TEN_CUA_BAN/duong-dan/toi/project
claude

Đường dẫn /mnt/c/ chính là cách WSL truy cập các ổ đĩa Windows. Ổ C: sẽ nằm ở /mnt/c/, ổ D: ở /mnt/d/, và cứ thế tiếp theo.

Cài đặt trên macOS hoặc Linux

Mở Terminal. Dán lệnh này vào và nhấn Enter.

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

Vậy là xong phần cài đặt. Native installer sẽ tự tải về file nhị phân, đặt vào ~/.local/bin và cấu hình tự động cập nhật. Không cần cài Node.js, không phụ thuộc thư viện ngoài, và cũng chẳng cần lo lắng về package manager.

Kiểm tra xem nó đã hoạt động chưa:

claude --version
claude doctor

claude doctor sẽ chạy kiểm tra tổng thể: trạng thái đăng nhập, đường dẫn PATH, file config và MCP server. Hãy luôn chạy lệnh này ngay sau khi cài để phát hiện lỗi sớm.

Giờ thì bước vào dự án thôi:

cd /duong-dan/toi/project/cua/ban
claude

Xong. Giờ bạn đã chính thức ở trong môi trường Claude Code rồi.

Cài đặt bằng Homebrew (macOS)

Nếu bạn quen quản lý công cụ bằng Homebrew, Anthropic đã phát hành cask chính thức:

brew install --cask claude-code

Trên thực tế, có hai phiên bản cask cho bạn lựa chọn:

• claude-code — theo kênh stable (chậm hơn latest khoảng 1 tuần, thường bỏ qua các bản release có lỗi nặng). An toàn hơn cho người dùng phổ thông.
• claude-code@latest — theo kênh latest (cập nhật version mới ngay khi phát hành).

# Cho channel bleeding-edge:
brew install --cask claude-code@latest

Lưu ý: Cài qua Homebrew không tự động cập nhật. Bạn cần chạy brew upgrade claude-code (hoặc claude-code@latest) thủ công để nhận bản mới và vá lỗi bảo mật.

Cài đặt Linux bằng package manager

Anthropic đã cung cấp các repo apt, dnf, apk có chữ ký số. Đây là cách cài đặt gọn gàng nhất cho Debian/Ubuntu, Fedora/RHEL và Alpine, vì việc cập nhật sẽ đi theo quy trình nâng cấp hệ thống tiêu chuẩn của bạn.

Debian / Ubuntu (apt):

sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc \
  -o /etc/apt/keyrings/claude-code.asc
echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/stable stable main" \
  | sudo tee /etc/apt/sources.list.d/claude-code.list
sudo apt update
sudo apt install claude-code

Hãy kiểm tra GPG fingerprint trước khi tin tưởng repo: gpg --show-keys /etc/apt/keyrings/claude-code.asc phải trả về 31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE.

Fedora / RHEL (dnf):

sudo tee /etc/yum.repos.d/claude-code.repo <<'EOF'
[claude-code]
name=Claude Code
baseurl=https://downloads.claude.ai/claude-code/rpm/stable
enabled=1
gpgcheck=1
gpgkey=https://downloads.claude.ai/keys/claude-code.asc
EOF
sudo dnf install claude-code

Alpine (apk):

wget -O /etc/apk/keys/claude-code.rsa.pub \
  https://downloads.claude.ai/keys/claude-code.rsa.pub
echo "https://downloads.claude.ai/claude-code/apk/stable" >> /etc/apk/repositories
apk add claude-code

Nếu muốn dùng kênh cập nhật liên tục, chỉ cần đổi stable thành latest trong URL và tên suite. Việc cập nhật sau này sẽ thực hiện bình thường qua lệnh package manager (sudo apt upgrade claude-code, sudo dnf upgrade claude-code, apk upgrade claude-code).

Cài qua npm (đường legacy)

Nếu máy bạn đã sẵn sàng Node.js 18+ và bạn quen dùng npm:

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

Lệnh này cũng sẽ cài file nhị phân giống như bản native, nhưng hoạt động như một dependency tùy chọn theo nền tảng. Hiện tại, đại đa số bạn đều chuyển sang cách khác vì 3 lý do sau:

1. Không tự động cập nhật. Bạn phải tự chạy npm update mỗi khi có bản mới.
2. Bắt buộc Node.js 18+. Trong khi native installer không cần gì thêm.
3. Dễ dính lỗi quyền. Đặc biệt nếu bạn cố dùng sudo npm install -g — tuyệt đối tránh cách này.

Nếu bạn đã lỡ cài qua npm và muốn chuyển sang bản native:

curl -fsSL https://claude.ai/install.sh | bash
npm uninstall -g @anthropic-ai/claude-code

Authentication (điệu nhảy login)

Lần đầu tiên chạy claude, trình duyệt sẽ tự động mở ra để thực hiện đăng nhập OAuth. Hãy dùng đúng tài khoản Anthropic mà bạn đang dùng:

• Gói cá nhân Claude Pro/Max — đăng nhập tại claude.ai
• Claude Team hoặc Enterprise — đăng nhập vào workspace của tổ chức
• Claude Console — nếu workspace của bạn đã mời bạn vào

Nếu trình duyệt không tự mở, hãy nhấn c trong terminal để copy đường link đăng nhập, dán vào trình duyệt, hoàn tất đăng nhập, rồi quay lại terminal paste mã xác thực khi Claude Code yêu cầu.

Sau này nếu muốn đổi tài khoản khác:

/logout

(Lưu ý: lệnh này phải chạy bên trong Claude Code, không phải ở shell thông thường.)

Lệnh đầu tiên của bạn

Khi Claude Code đưa bạn vào môi trường tương tác (interactive session), hãy thử:

/help          # Show tất cả lệnh
/status        # Xem auth, subscription, rate limit
/config        # Xem config hiện tại
/logout        # Đăng xuất

Hoặc chạy trực tiếp từ shell (bên ngoài môi trường tương tác):

claude doctor    # Báo cáo diagnostic
claude --version # Version đã cài
claude mcp list  # List MCP server đã cấu hình

Một task thật đầu tiên

Mở thư mục dự án hiện có của bạn ra. Cứ bất kỳ thứ gì cũng được — Next.js app, script Python, hay repo cấu hình gì đó. Sau đó khởi động Claude Code:

cd /duong-dan/toi/project
claude

Rồi hãy nhập yêu cầu thực tế bằng tiếng Việt hoặc tiếng Anh. Ví dụ:

“Đọc README và nói cho mình biết project này được tổ chức thế nào.”

Hoặc:

“Thêm function validate địa chỉ email. Đặt nó vào chỗ phù hợp nhất trong codebase.”

Hoặc:

“Tìm tất cả comment TODO và list ra với đường dẫn file.”

Claude Code sẽ quét qua các file của bạn, phân tích và đề xuất chỉnh sửa. Quan trọng là nó sẽ hỏi bạn xác nhận (approve) từng thay đổi trước khi thực thi. Bạn vẫn hoàn toàn nắm quyền kiểm soát.

Vấn đề setup thường gặp (và fix)

“command not found: claude”

Trình cài đặt thường đặt file thực thi vào ~/.local/bin, nhưng shell của máy bạn có thể chưa nhận ra thư mục này. Hãy thêm nó vào PATH:

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

Nếu bạn đang dùng zsh (mặc định trên macOS từ Catalina trở đi), hãy thay .bashrc bằng .zshrc.

“The token ‘&&’ is not a valid statement separator”

Lỗi này xảy ra khi bạn dán lệnh dạng CMD vào PowerShell. Giải pháp là chuyển sang dùng CMD, hoặc dùng phiên bản PowerShell:

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

“Permission denied” khi npm install

Lỗi này thường do bạn cố chạy sudo npm install -g và vô tình làm rối quyền truy cập. Tuyệt đối không dùng sudo với npm. Thay vào đó, hãy:

• Dùng native installer (không cần sudo): curl -fsSL https://claude.ai/install.sh | bash
• Dùng nvm (Node Version Manager) để cài Node.js trong thư mục home của chính bạn

WSL không vào được internet

Hãy test bằng lệnh curl https://claude.ai. Nếu báo lỗi, có thể firewall Windows hoặc VPN đang chặn kết nối của WSL. Đa số các phần mềm VPN đều có tùy chọn “exclude local traffic” — hãy bật nó lên.

Bị rate limit ngay sau khi cài

Bạn đang dùng gói Pro nhưng đã chạm giới hạn tốc độ (rate limit) chỉ sau 1 tiếng? Đây là lỗi có thật mà Anthropic đã xác nhận vào ngày 31 tháng 3 năm 2026. Hãy kiểm tra lại version Claude Code:

claude --version

Bản build mới nhất tính đến ngày 4 tháng 5 là v2.1.126 (phát hành ngày 1 tháng 5), đi kèm lệnh hữu ích claude project purge [path] và vá lỗi tính toán /context của Opus 4.7. Tuy nhiên, vấn đề token tăng đột biến do v2.1.100 gây ra hiện vẫn chưa có bản vá chính thức. Theo phản hồi từ cộng đồng, cách khắc phục tạm thời là downgrade về v2.1.34, hoặc cài lại qua npm thay vì dùng bản native.

Nếu dùng native installer, bạn có thể khóa cứng version cụ thể:

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

Hoặc thiết lập mức version tối thiểu trong ~/.claude/settings.json để các lần cập nhật sau không vô tình kéo bạn về bản lỗi:

{
  "autoUpdatesChannel": "stable",
  "minimumVersion": "2.1.34"
}

Mở rộng Claude Code với MCP

Khi phần cơ bản đã vận hành ổn định, sức mạnh thực sự nằm ở việc kết nối Claude Code với các công cụ khác thông qua MCP (Model Context Protocol). Nhờ MCP, Claude Code không còn là “trợ lý viết code” đơn thuần, mà trở thành “trợ lý có quyền truy cập trực tiếp” vào database, API và các công cụ làm việc của team bạn.

Danh sách các MCP server hiện có:

claude mcp list

Cách thêm server mới (ví dụ kết nối database):

claude mcp add my-db --command "docker run --rm my-db-mcp:latest"

Mỗi dự án có thể có file .claude/.mcp.json riêng để liệt kê các MCP server tương ứng. Với repo chung, bạn có thể commit file này để cả team cùng chia sẻ và áp dụng chung cấu hình công cụ.

Cheat sheet theo OS

Điều này có ý nghĩa gì với bạn

Nếu bạn chưa từng dùng terminal: (Dù trên macOS hay WSL Windows). Terminal chính là “bộ mặt” của Claude Code — bạn sẽ thấy rất khó dùng nếu chưa quen. Hãy dành chút thời gian làm quen với cd, ls, pwd và các lệnh git cơ bản nếu bạn chưa rành.

Nếu bạn là dev đang cân nhắc Claude Code: Cài đặt chỉ mất 5 phút, hãy trỏ nó vào một dự án phụ và giao một task thực tế. Cursor thiên về IDE, Copilot thiên về autocomplete — còn Claude Code có một hướng đi khác biệt hẳn. Bạn cần trải nghiệm trực tiếp mới thấy rõ sự khác biệt.

Nếu bạn đang triển khai cho team: Tạo thư mục .claude/ trong repo chung, đính kèm file cấu hình MCP của team. Commit nó lên. Member mới chỉ cần chạy installer, đăng nhập và họ sẽ tự động thừa hưởng đúng cấu hình công cụ mà team đã dựng sẵn.

Nếu bạn đã cài Claude Code rồi: Hệ sinh thái plugin và MCP chính là nơi bạn chuyển từ “người dùng” sang “chuyên gia”. Bạn có thể đào sâu hơn qua khóa học AI cho Lập Trình Viên và AI Lập Trình Viết Code, được thiết kế riêng cho workflow lập trình hỗ trợ bởi AI.

Tóm lại

Việc cài Claude Code chỉ tốn từ 30 giây đến 5 phút tùy hệ điều hành. Native installer (chính thức từ tháng 4 năm 2026) rất ổn định, nhanh nhẹn và không yêu cầu bất kỳ dependency nào thêm.

Thử thách thực sự không nằm ở bước cài đặt, mà là làm sao để Claude Code thực sự giúp bạn tăng năng suất sau đó. Hãy bắt đầu với những task nhỏ, dần dần mở rộng thành workflow hoàn chỉnh, và chỉ thêm MCP tool khi bạn thực sự thấy cần. Đừng cố cấu hình hết tính năng trong ngày đầu tiên.

Và đừng quên chuẩn bị ngân sách cho gói đăng ký. Plan miễn phí không đủ sức hỗ trợ công việc thực tế. Mức $20/tháng cho Claude Pro mới là điểm khởi đầu thực sự.

Bước tiếp theo: Khóa AI cho Lập Trình Viên sẽ cover toàn bộ quy trình lập trình với AI. Nếu bạn muốn đi sâu hơn vào Claude cụ thể, hãy xem tiếp Hướng Dẫn Claude AI.

Nguồn (kiểm tra ngày 4 tháng 5 năm 2026):

• Claude Code Setup — Tài liệu chính thức (verify live cho cú pháp lệnh)
• Claude Code Changelog — Chính thức
• Release Claude Code v2.1.126 — 1 tháng 5, 2026
• Install Claude Code — Anthropic