Cài đặt Claude Code trên macOS: Từ Homebrew đến lệnh đầu tiên

Hướng dẫn cài đặt Claude Code trên macOS từ A-Z: Homebrew, xử lý lỗi PATH, API key. Copy-paste chạy ngay cho developer Việt.

Định nghĩa

Claude Code là AI coding agent của Anthropic biến terminal macOS thành pair programmer thông minh — hiểu codebase bằng ngôn ngữ tự nhiên, tự chạy lệnh và sửa lỗi thay vì chỉ gợi ý từng dòng code như Copilot.

Giải thích chi tiết

Yêu cầu hệ thống thực tế

Với phần lớn MacBook đời 2020+ đang lưu hành tại các coworking space Sài Gòn và Hà Nội, bạn chỉ cần:

macOS 12+ (Monterey trở lên — cả Intel lẫn Apple Silicon M1/M2/M3 đều chạy tốt)
Terminal (Zsh mặc định trên macOS đời mới hoặc iTerm2 nếu bạn thích customize)
Homebrew (nên có sẵn — đây là chuẩn vàng của dev Việt dùng Mac)
API key Anthropic (lấy free tại console.anthropic.com, có thể dùng token dùng thử hoặc mua gói Pro)

Lưu ý nhỏ: Trên Mac chip M1/M2/M3 (ARM64), Homebrew cài vào /opt/homebrew, còn Mac Intel thì vào /usr/local. Đường dẫn này ảnh hưởng đến việc fix lỗi PATH bên dưới.

Cách 1: Homebrew (Khuyến nghị 99%)

Homebrew là ecosystem quen thuộc của dân dev Mac Việt Nam — giống như apt trên Ubuntu nhưng "sang chảnh" hơn và cập nhật nhanh hơn nhiều.

# Cập nhật brew database
brew update

# Cài đặt chính thức từ Anthropic
brew install claude

# Kiểm tra — bạn sẽ thấy version ví dụ: 0.9.x
claude --version

Ưu điểm vượt trội: Tự động inject PATH, cập nhật một lệnh brew upgrade claude, và xử lý dependency sạch sẽ không lo conflict với Node.js version manager (nvm/fnm) bạn đang dùng cho dự án React/Vue.

Cách 2: npm global (Dành cho ai sợ Homebrew "nặng")

Nếu bạn đang làm việc với Node.js và không muốn cài thêm package manager:

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

Nhưng nhớ: npm global thường cài vào thư mục khác với system PATH. Nếu gõ claude báo command not found, cuộn xuống phần xử lý lỗi bên dưới.

Xác thực API Key lần đầu

Không giống các tool cần copy-paste key thủ công, Claude Code tự mở browser để auth:

# Lần đầu chạy — terminal sẽ hiện link hoặc tự bật Safari/Chrome
claude

Key được lưu an toàn tại ~/.config/claude/config.json với permission 600 (chỉ owner đọc được), tương đương chuẩn bảo mật SSH key.

Xử lý "claude: command not found" (Bệnh phổ biến nhất)

Triệu chứng 1: Chưa reload shell

source ~/.zshrc
# Hoặc nếu dùng Bash hiếm gặp trên Mac:
source ~/.bash_profile

Triệu chứng 2: Homebrew chưa vào PATH (Mac M1/M2/M3 thường gặp)

# Thêm vào ~/.zprofile (chứ không phải .zshrc trên macOS đời mới)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Triệu chứng 3: npm global bị lạc đường

# Thêm vào ~/.zshrc
export PATH="$PATH:$(npm config get prefix)/bin"

Ví dụ thực tế

Setup từ zero cho dự án Startup tại Quận 4

Bạn vừa nhận MacBook Pro M3 từ công ty startup fintech tại Quận 4, cần setup để code backend NestJS tích hợp VietQR:

# 1. Cài Homebrew (chưa có thì cài, có rồi thì skip)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 2. Fix PATH cho Silicon Mac — bước này 90% người Việt bị quên
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

# 3. Cài Claude Code
brew install claude

# 4. Auth và vào dự án
claude
# Sau đó cd vào folder dự án NestJS và bắt đầu yêu cầu: "Tích hợp API VietQR vào module payment"

Fix quyền truy cập trên macOS Sonoma cho dự án Zalo Mini App

Khi làm Zalo Mini App (rất phổ biến ở VN), bạn cần đọc file cấu hình trong Desktop hoặc Documents để sync với Zalo OA. macOS sẽ chặn:

# Vào System Settings > Privacy & Security > Full Disk Access
# Thêm Terminal hoặc iTerm vào danh sách
# Hoặc nếu dùng VS Code integrated terminal, thêm VS Code vào đó

Nếu Claude báo lỗi permission denied khi đọc file trong ~/Documents/zalo-mini-app:

# Sửa quyền cho cả thư mục config
chmod 700 ~/.config/claude
# Và cấp quyền cho Documents (nếu cần)
chmod 755 ~/Documents/zalo-mini-app

Chuyển đổi giữa stable và nightly (Khi cần tính năng beta)

Giả sử team bạn đang cần test tính năng MCP (Model Context Protocol) mới nhất chưa có trên bản stable:

# Chuyển sang bản head (nightly)
brew unlink claude
brew install claude --head

# Nếu nightly bị lỗi, rollback về stable an toàn
brew unlink claude
brew install claude
brew switch claude 0.9.5  # hoặc version cụ thể bạn cần

Ứng dụng

Developer tại startup Fintech (Hà Nội/TP.HCM)

Setup nhanh trên MacBook cá nhân để code microservices thanh toán (Momo, ZaloPay, VietQR). Claude Code giúp generate boilerplate NestJS nhanh hơn 70% so với viết tay, đặc biệt hữu ích khi xử lý logic phức tạp như xác thực callback từ các cổng thanh toán Việt Nam.

Freelancer làm website cho chủ shop Shopee/Lazada

Dùng MacBook Air để maintain các site WordPress/WooCommerce hoặc Next.js frontend cho đối tác bán hàng online. Claude Code giúp sửa CSS responsive hoặc optimize ảnh hàng loạt mà không cần nhớ command ffmpeg hay ImageMagick cụ thể.

Sinh viên IT (BKU, HCMUS, FPT)

Cài đặt trên MacBook Air M1 dùng cho 4 năm học — từ code C++ cơ bản đến thesis về Machine Learning. Khác với các IDE nặng như IntelliJ, Claude Code chạy nhẹ trên terminal sẵn có, phù hợp máy cấu hình trung bình.

Tech Lead setup cho team 10 người

Triển khai đồng bộ qua Brewfile để cả team dùng Mac có cùng version, tránh lỗi "tại sao máy anh chạy được mà máy em không":

# Brewfile đặt trong repo công ty
brew "claude"
brew "node"
brew "git"

So sánh

Phương pháp	Thời gian	Độ phức tạp	Cập nhật	Khi nào dùng
Homebrew	dưới 2 phút	Thấp (tự động)	`brew upgrade`	99% dev Việt dùng Mac
npm global	dưới 1 phút	Trung bình (cần fix PATH)	`npm update -g`	Developer Node.js cứng, không thích Homebrew
Build từ source	5-10 phút	Cao (cần Rust/Node)	Thủ công clone	Muốn contribute code cho Anthropic

Insight: Tại Việt Nam, Homebrew thống trị vì cộng đồng startup tech chịu ảnh hưởng Silicon Valley nhiều, nên chuẩn hóa trên Homebrew giúp dễ tìm support trên các group Facebook như "Node.js Vietnam" hay "Python Việt Nam" hơn là dùng npm global lạc lõng.