Cài đặt Claude Code trên Windows WSL2: Từ cài đặt đến chạy lệnh đầu tiên

Hướng dẫn cài Claude Code trên Windows bằng WSL2: Giải quyết lỗi 'command not found', cấu hình PATH đúng chuẩn, và kết nối API key để dùng AI coding agent trên máy Windows.

Định nghĩa

Claude Code là AI coding agent chạy native trên terminal Unix/Linux, không có phiên bản cho Windows. Để dùng trên Windows, bạn cần cài WSL2 (Windows Subsystem for Linux) — một "lớp tương thích" cho phép chạy môi trường Linux ngay bên trong Windows, như thể máy bạn có hai hệ điều hành song song nhưng chia sẻ chung ổ cứng và file system.

Giải thích chi tiết

Tại sao bắt buộc phải dùng WSL?

Claude Code được Anthropic thiết kế cho lập trình viên macOS và Linux — những hệ điều hành có sẵn terminal Unix chuẩn. Windows dùng kiến trúc kernel khác (NT), nên không chạy trực tiếp được các công cụ này.

WSL2 là giải pháp "cửa sau" của Microsoft: nó tạo một máy ảo Linux siêu nhẹ (chỉ vài trăm MB) chạy ngầm bên trong Windows. Khi bạn mở Windows Terminal và gõ bash, thực chất bạn đang nói chuyện với một Ubuntu thu nhỏ. Claude Code chạy trong môi trường này sẽ hoạt động y hệt như trên Mac — từ đọc file, chạy git, đến thực thi npm hay python.

Kiểm tra và cài WSL2 (Windows 10/11)

Nếu máy chưa có WSL2, mở PowerShell hoặc Command Prompt (không phải WSL) với quyền Administrator và chạy:

wsl --install

Lệnh này cài Ubuntu mặc định và bật các tính năng ảo hóa cần thiết. Khởi động lại máy khi được yêu cầu.

Sau khi khởi động lại, mở Windows Terminal (hoặc tìm app "Ubuntu" trong Start Menu). Lần đầu chạy, bạn sẽ tạo username và password cho Linux — đây là tài khoản riêng biệt với tài khoản Windows.

Kiểm tra WSL đã sẵn sàng:

whoami

Nếu ra tên username vừa tạo (ví dụ: hiep), WSL đã hoạt động.

Cài đặt Claude Code trong WSL

Trong terminal Ubuntu (WSL), chạy lệnh chính thức từ Anthropic:

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

Script này tải Claude Code về ~/.local/bin. Nếu bạn dùng npm:

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

Xử lý lỗi "claude: command not found"

Đây là lỗi phổ biến nhất sau cài đặt. Nguyên nhân là shell chưa biết đường dẫn đến file thực thi. Thêm vào PATH:

Với Bash (mặc định của Ubuntu):

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

Với Zsh (khuyên dùng cho trải nghiệm tốt hơn):

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

Kiểm tra lại:

claude --version

Nếu hiện số phiên bản (ví dụ: 0.2.45), bạn đã sẵn sàng.

Kết nối API Key

Claude Code cần API key từ Anthropic. Truy cập console.anthropic.com, tạo tài khoản, vào API Keys → Create Key. Copy key (bắt đầu bằng sk-ant-...).

Trong terminal WSL, chạy:

claude config set apiKey sk-ant-api03-...

Hoặc Claude sẽ tự hỏi key khi bạn chạy claude lần đầu. Key được lưu trong ~/.claude/settings.json — riêng biệt với Windows, nên bạn cần lưu lại key để dùng nếu cài lại WSL.

Ví dụ thực tế

Scenario 1: Developer công ty dùng laptop Windows cấp phát Bạn làm backend cho startup fintech ở Quận 7, máy cấp là Windows 11 Corporate. Thay vì xin đổi MacBook, bạn cài WSL2 + Ubuntu, cài Claude Code trong 5 phút. Giờ bạn chạy claude ngay trong Windows Terminal, để AI giúp refactor code tích hợc cổng thanh toán MoMo và VietQR — môi trường WSL giúp test Unicode tiếng Việt chuẩn xác như trên server Linux production.

Scenario 2: Freelancer build MVP cho khách hàng Việt Nam Bạn nhận làm app đặt lịch khám bệnh cho phòng khám tư nhân, deploy lên server Viettel Cloud chạy Ubuntu. Thay vì code trên Windows rồi "hy vọng" chạy được trên server, bạn dùng Claude Code trực tiếp trong WSL. Môi trường dev (WSL) giờ giống hệt production (Ubuntu server), tránh lỗi "trên máy tôi chạy được nhưng lên server Viettel Cloud lỗi font tiếng Việt".

Scenario 3: Sinh viên Đại học Bách Khoa học lập trình Bạn năm 3, máy cá nhân chạy Windows, muốn học AI coding nhưng mọi hướng dẫn trên mạng đều là lệnh Linux. Cài WSL2 cho phép bạn thực hành đúng workflow lập trình viên chuyên nghiệp: dùng git, vim, docker trong terminal, và dùng Claude Code như "senior dev ảo" đứng bên cạnh giải thích từng dòng code C++ và giúp viết script kiểm tra điểm thi tự động.

Ứng dụng

Developer Windows chuyên nghiệp Biến máy Windows thành workstation hiện đại không thua kém Mac Studio. Kết hợp VS Code (bản Windows) với terminal WSL chạy Claude Code, bạn có "bộ đôi" hoàn hảo: IDE mạnh trên Windows và AI agent chạy trong môi trường Linux chuẩn — đặc biệt hữu ích khi làm việc với các stack phổ biến ở VN như Laravel, Node.js, hoặc Python Django.

PM/Designer cần prototype nhanh Không cần biết code sâu, chỉ cần mô tả bằng tiếng Việt trong terminal WSL: "Tạo trang landing page có form đăng ký nhận thông tin khuyến mãi", Claude Code sẽ tự viết file HTML/CSS và mở trên browser Windows để bạn demo cho khách hàng ngay.

Tech lead setup team đồng nhất Trong công ty có 20 developer dùng Windows, bạn viết script cài đặt WSL + Claude Code tự động (dùng wsl --install và curl), đảm bảo cả team có môi trường giống hệt nhau để pair programming với AI — tránh tình trạng "máy anh chạy được, máy em không chạy".

So sánh

Tiêu chí	Claude Code trên WSL (Windows)	Claude Code trên macOS/Linux (Native)
Hiệu năng	Gần như native, overhead nhẹ từ WSL (~5-10%)	Tối ưu nhất, không có lớp dịch
Cài đặt	Cần bước cài WSL2 trước, phức tạp hơn 1 chút	Cài trực tiếp bằng 1 lệnh curl
Tích hợp file	Truy cập file Windows qua `/mnt/c/` (hơi chậm hơn)	Truy cập file hệ thống trực tiếp
Ổn định	Rất ổn định với WSL2, thỉnh thoảng cần restart WSL	Ổn định tuyệt đối
Phù hợp	Phổ biến nhất ở VN — dành cho developer dùng laptop Windows công ty	Dành cho freelancer hoặc công ty cho phép dùng Mac/Linux

Kết luận: WSL2 là "cầu nối" hoàn hảo để developer Việt Nam dùng Windows không bị bỏ lỡ sóng AI coding. Mặc dù có thêm bước cài đặt ban đầu, trải nghiệm sau đó gần như giống hệt trên Mac. Thay vì chờ Anthropic ra bản Windows native (chưa có lộ trình), hãy dùng WSL2 ngay hôm nay để bắt kịp công nghệ.