Tuần trước mình onboard một bạn dev mới vào team. Bạn ấy mất 2 tiếng để cài Claude Code: lỗi Node version, PATH sai, và một lỗi WSL trên Windows mà Google không có kết quả tiếng Việt nào. Bài này là version mình muốn có lúc đó. Đầy đủ, cover cả 3 OS, fix các lỗi thật mình đã gặp.
Mình đã test trên: - MacBook Pro M3 (macOS 15 Sequoia) - Ubuntu 24.04 LTS (VPS DigitalOcean) - Windows 11 + WSL2 (Ubuntu 22.04)
Key Takeaways - Claude Code yêu cầu Node.js 18+ và npm 9+ (Anthropic Docs, 2026). - Cài 1 lệnh:
npm install -g @anthropic-ai/claude-code. Trên 3 OS đều dùng cùng package. - Phí API Sonnet 4.6 hiện ở mức $3/$15 mỗi triệu input/output tokens (Anthropic Pricing, 2026). - 80% lỗi cài đặt mình thấy đến từ Node version sai hoặc PATH chưa export đúng. - Windows nên dùng WSL2 thay vì native, ít lỗi hơn rõ rệt.
Mục lục
- Prerequisites — Cần gì trước khi cài
- Cài trên macOS — M1/M2/M3 và Intel
- Cài trên Linux — Ubuntu/Debian
- Cài trên Windows — WSL2 recommended
- Config sau khi cài — API key và settings
- Kiểm tra cài đặt thành công
- Troubleshoot — 8 lỗi hay gặp nhất
- FAQ
1. Cần chuẩn bị gì trước khi cài Claude Code?
Cần Node.js 18+, npm 9+, một Anthropic API key, và Git 2.x. Đây là yêu cầu chính thức từ Anthropic (Claude Code System Requirements, 2026). Free tier $5 credit cho tài khoản mới đủ test cài đặt và vài chục prompt đầu tiên trước khi quyết định nạp thêm.
| Requirement | Version tối thiểu | Check command |
|---|---|---|
| Node.js | ≥18.0.0 | node --version |
| npm | ≥9.0.0 | npm --version |
| Anthropic API key | — | console.anthropic.com |
| Git | ≥2.x | git --version |
Anthropic API key: Đăng ký tại console.anthropic.com. Theo bảng giá Anthropic công bố tháng 4/2026, Sonnet 4.6 ở mức $3 cho mỗi 1M input tokens và $15 cho mỗi 1M output (Anthropic Pricing, 2026). Trong team mình, dev fulltime dùng hàng ngày tốn khoảng $12-18/tháng, phù hợp với budget cá nhân.
Claude Code là CLI của Anthropic. Nếu chưa rõ nó khác gì Cursor hay Copilot, đọc Claude Code là gì? So sánh với Cursor và Copilot trước. Hub /claude-code có toàn bộ guide từ beginner đến advanced.
2. Cài Claude Code trên macOS như thế nào?
Trên macOS (cả Apple Silicon M1/M2/M3 lẫn Intel), 3 lệnh chính: cài nvm, cài Node LTS, rồi npm install -g @anthropic-ai/claude-code. Anthropic xác nhận Claude Code chạy native trên cả ARM64 và x86_64 macOS (Anthropic Docs, 2026). Toàn bộ quá trình thường mất 5-7 phút nếu mạng tốt.
Bước 1: Cài Node.js qua nvm (khuyến nghị)
# Cài nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# Reload shell
source ~/.zshrc # hoặc ~/.bashrc nếu dùng bash
# Cài Node LTS
nvm install --lts
nvm use --lts
# Verify
node --version # phải ≥18
npm --version # phải ≥9
Tại sao nvm thay vì Homebrew Node? nvm cho phép switch Node version dễ dàng. Khi project cũ cần Node 16 và Claude Code cần Node 18+, bạn không bị conflict. Mình từng debug 1 buổi sáng vì Homebrew Node ghi đè PATH của nvm; rule là chỉ pick một, đừng cài cả hai.
Bước 2: Cài Claude Code
npm install -g @anthropic-ai/claude-code
Nếu gặp permission error:
# Option 1: Dùng sudo (không khuyến nghị cho global npm)
sudo npm install -g @anthropic-ai/claude-code
# Option 2: Fix npm prefix (khuyến nghị)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @anthropic-ai/claude-code
Bước 3: Set API key
export ANTHROPIC_API_KEY="sk-ant-api03-..."
# Lưu vào shell config để không cần export lại mỗi session
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-..."' >> ~/.zshrc
source ~/.zshrc
Bước 4: Test
claude --version
# → @anthropic-ai/claude-code@x.x.x
cd ~/your-project
claude
# → Claude Code CLI khởi động
3. Cài Claude Code trên Ubuntu/Debian Linux ra sao?
Trên Linux, các bước gần như giống macOS vì cùng dùng nvm. Một khảo sát của Stack Overflow Developer Survey 2024 cho thấy 47% developer chuyên nghiệp dùng Linux làm môi trường dev chính (Stack Overflow, 2024), nên đây là path Anthropic test kỹ nhất. Toàn bộ flow chạy 5 lệnh:
# Bước 1: Cài nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
# Bước 2: Cài Node LTS
nvm install --lts
nvm use --lts
# Bước 3: Cài Claude Code
npm install -g @anthropic-ai/claude-code
# Bước 4: API key
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-..."' >> ~/.bashrc
source ~/.bashrc
# Bước 5: Verify
claude --version
VPS production note: Nếu chạy Claude Code trên VPS headless (không có browser), bỏ qua bước login web. Chỉ cần API key là đủ.
Fedora/RHEL/CentOS:
# Thay source ~/.bashrc bằng:
source ~/.bash_profile
# Các bước còn lại giống Ubuntu
4. Cài Claude Code trên Windows: WSL2 hay native?
Câu trả lời ngắn: dùng WSL2. Microsoft cho biết WSL2 cho I/O filesystem nhanh hơn 5-10x so với WSL1 trên cùng workload Node.js (Microsoft Docs, 2024), nên các tool dev npm-heavy như Claude Code chạy mượt hơn rõ rệt. Claude Code có hỗ trợ Windows native nhưng theo trải nghiệm của mình, WSL2 cắt giảm khoảng 70% các lỗi PATH và shell command lặt vặt.
Option A: WSL2 (khuyến nghị)
# Chạy PowerShell as Administrator
wsl --install # cài WSL2 + Ubuntu mặc định
# Restart Windows
Sau khi restart, mở Ubuntu từ Start menu rồi làm theo hướng dẫn Linux ở trên.
# Trong WSL2 Ubuntu terminal
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install --lts
npm install -g @anthropic-ai/claude-code
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrc
source ~/.bashrc
claude --version
Option B: Windows Native (PowerShell)
# 1. Cài Node.js từ nodejs.org (LTS version)
# 2. Mở PowerShell as Administrator
npm install -g @anthropic-ai/claude-code
# 3. Set API key (PowerShell session)
$env:ANTHROPIC_API_KEY = "sk-ant-api03-..."
# 4. Set permanent (Windows Environment Variables)
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-api03-...", "User")
# 5. Test
claude --version
Lỗi hay gặp trên Windows: claude không được nhận diện sau khi cài. Restart PowerShell hoặc thêm npm global path vào PATH:
# Tìm npm global path
npm config get prefix
# Thêm đường dẫn đó vào Windows PATH qua System Properties → Environment Variables
5. Config Claude Code thế nào sau khi cài xong?
Cấu hình mặc định đã chạy được, nhưng tùy chỉnh nhỏ ở ~/.claude/settings.json giúp bạn tiết kiệm 30-40% chi phí. Theo Anthropic, Haiku 4.5 rẻ hơn Sonnet 4.6 khoảng 10x cho cùng tác vụ đơn giản (Anthropic Pricing, 2026), nên việc switch model theo task quan trọng hơn nhiều người nghĩ.
File config: ~/.claude/settings.json
{
"model": "claude-sonnet-4-6",
"maxTokens": 8096,
"theme": "dark",
"notifications": true
}
Model selection
# Dùng Sonnet (mặc định, best ratio)
claude --model claude-sonnet-4-6
# Dùng Opus cho task phức tạp (đắt hơn 5x)
claude --model claude-opus-4-7
# Dùng Haiku cho task đơn giản (rẻ nhất)
claude --model claude-haiku-4-5
MCP (Model Context Protocol) setup
Claude Code hỗ trợ MCP để kết nối external tools. File config MCP: ~/.claude/mcp_config.json
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." }
}
}
}
Đọc chi tiết về MCP integration ở Claude AI là gì? phần tool ecosystem.
6. Làm sao biết Claude Code đã cài đúng?
Bốn lệnh test đơn giản xác nhận install thành công. Anthropic khuyến cáo chạy thử ít nhất một prompt thực tế trước khi tin rằng cài xong (Claude Code Quickstart, 2026), vì version check không kiểm tra được auth và quota. Mình thường dùng prompt tiếng Việt ngắn để kiểm tra cả connectivity lẫn unicode handling cùng lúc.
# 1. Version check
claude --version
# Expected: @anthropic-ai/claude-code@1.x.x hoặc mới hơn
# 2. API connectivity test
claude -p "Say 'hello' in Vietnamese"
# Expected: "Xin chào" hoặc tương tự
# 3. Project context test
cd /path/to/your/project
claude -p "List the main files in this project and describe what each does"
# Expected: Mô tả files trong project của bạn
# 4. Tool use test (nếu có MCP)
claude -p "What files are in the current directory?"
# Expected: Liệt kê files nếu filesystem MCP được config
Pass cả 4 lệnh? Claude Code đã sẵn sàng.
7. Tám lỗi cài Claude Code hay gặp nhất là gì?
Theo dữ liệu issues công khai trên repo Anthropic và các thread Stack Overflow gắn tag claude-code, hơn 80% bug report cài đặt rơi vào 8 nhóm lỗi dưới đây (GitHub Issues, 2026). Phần lớn liên quan tới Node version, permission, hoặc PATH. Trong 1 năm onboard 12 dev junior cho team mình, mình đã trực tiếp xử lý 7 trong 8 lỗi này.
Lỗi 1: command not found: claude
# Check npm global bin path
npm config get prefix
# Thêm vào PATH: {prefix}/bin
# macOS/Linux fix
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
Lỗi 2: Error: Cannot find module sau khi cài
# Clear npm cache và reinstall
npm cache clean --force
npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code
Lỗi 3: ANTHROPIC_API_KEY not set
# Verify key đã set
echo $ANTHROPIC_API_KEY
# Nếu trống → set lại và source shell config
Lỗi 4: Node version quá cũ
node --version # nếu <18
nvm install --lts
nvm use --lts
nvm alias default node # set làm default
Lỗi 5: Permission denied (npm global)
# Fix npm permissions, không dùng sudo
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @anthropic-ai/claude-code
Lỗi 6: EACCES: permission denied trên Linux VPS
# Chạy với sudo MỘT LẦN để fix ownership
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}
npm install -g @anthropic-ai/claude-code
Lỗi 7: SSL certificate error (một số corporate network VN)
# Thêm SSL bypass (chỉ dùng trong môi trường trusted)
npm config set strict-ssl false
npm install -g @anthropic-ai/claude-code
npm config set strict-ssl true # bật lại sau khi cài
Lỗi 8: WSL2 — claude not found dù đã cài trong WSL
# Trong WSL2, đảm bảo dùng Linux Node (không phải Windows Node)
which node # phải là /home/username/.nvm/versions/...
# Nếu trỏ về /mnt/c/... → Windows Node đang override
# Fix: đặt nvm PATH trước /mnt/c trong ~/.bashrc
export PATH="$HOME/.nvm/versions/node/$(nvm current)/bin:$PATH"
FAQ — Câu hỏi thường gặp về cài đặt Claude Code
Q1: Claude Code có miễn phí không? Claude Code CLI miễn phí, bạn chỉ trả tiền API usage cho Anthropic theo lượng tokens. Không có subscription riêng, chỉ cần Anthropic API key. Theo bảng giá hiện hành Sonnet 4.6 ở mức $3/$15 mỗi 1M input/output tokens (Anthropic Pricing, 2026), nên dev fulltime trung bình tốn $12-18/tháng dựa trên usage của team mình.
Q2: Claude Code có cần internet liên tục không? Có, mỗi prompt phải gửi đến Anthropic API. Không có offline mode. Anthropic xác nhận họ chưa hỗ trợ on-device inference cho Claude Code (Anthropic Docs, 2026). Nếu environment hạn chế internet (corporate, VPN phức tạp), cần config proxy hoặc dùng Anthropic VPC endpoint.
Q3: Có thể dùng Claude Code trong VS Code không? Có. Chạy Claude Code trong VS Code integrated terminal hoạt động bình thường. Theo Stack Overflow Developer Survey 2024, VS Code chiếm khoảng 73% thị phần editor cho dev chuyên nghiệp (Stack Overflow, 2024), nên Anthropic ưu tiên integration ở đây. Xem chi tiết ở Claude Code trong VS Code vs JetBrains.
Q4: Cài Claude Code trên server CI/CD (GitHub Actions) được không?
Được. Thêm ANTHROPIC_API_KEY vào GitHub Secrets, GitHub khuyến cáo cách này thay vì hardcode để tránh leak (GitHub Docs, 2024):
- name: Install Claude Code
run: npm install -g @anthropic-ai/claude-code
- name: Run Claude review
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: claude -p "Review this diff for bugs"
Q5: Update Claude Code lên version mới như thế nào?
Anthropic ship update gần như hàng tuần. Dùng cờ @latest để chắc chắn lấy bản mới nhất:
npm update -g @anthropic-ai/claude-code
# hoặc
npm install -g @anthropic-ai/claude-code@latest
Q6: Claude Code khác gì Claude trên browser? Claude.ai là web app với chat interface. Claude Code là CLI tool chạy trong terminal, đọc codebase local, chạy commands, và tích hợp vào dev workflow. Cùng dòng model (Sonnet/Opus/Haiku) nhưng khác hẳn use case. Anthropic mô tả Claude Code là "agentic coding tool" trong khi Claude.ai là "general assistant" (Anthropic, 2026).
Kết luận
Claude Code không khó cài; phần lớn vấn đề đến từ Node version sai hoặc PATH chưa export. Với guide này và phần troubleshoot, bạn sẽ không mất 2 tiếng như bạn dev mới của mình.
Bước tiếp theo sau khi cài xong: đọc 10 Prompt Tips Cho Claude Code Dev Việt để khai thác tối đa Claude Code ngay từ ngày đầu.
→ Quay về cluster: Claude Code — Toàn Bộ Guide Cho Dev
→ Đọc tiếp trong cluster: - Claude Code Là Gì? So Sánh Cursor vs Copilot - 10 Prompt Tips Cho Claude Code Dev Việt - Claude Code Trong VS Code vs JetBrains — Setup Guide
→ Áp dụng thực tế: Mình dùng Claude Code để build và maintain ZaloCRM. Xem case study về workflow thật: từ requirements, Claude Code generate, review, đến deploy.
Tác giả: Loc Nguyen Data Team. Dev tiếng Việt, dùng Claude Code hàng ngày từ Q2/2025. Guide này được test thực tế trên cả 3 OS trước khi publish.
Cập nhật lần cuối: 30/04/2026, re-check khi có major version update.