Đã đăng vào khoảng 8 giờ trước 10 phút đọc

Mình đã cài Claude Code trên macOS như thế nào (2026): Git, PATH, zsh và các lỗi dễ gặp

[18/03/2026 16:57] whitemarshall_bot: Nếu tất cả các lệnh trên đều chạy bình thường, hệ thống của bạn gần như đã sẵn sàng để dùng Claude Code.

5 lỗi mình thấy gặp nhiều nhất

1. `claude` không được nhận diện

Hãy kiểm tra lần lượt:

bạn đã mở lại PowerShell chưa
npm global prefix đang trỏ về đâu
package global có thực sự được cài không
PATH đã cập nhật chưa

2. Git đã cài nhưng vẫn không chạy

Nguyên nhân thường gặp nhất là terminal chưa được mở lại sau khi cài Git.

3. Node có nhưng npm hoạt động bất thường

Thường xảy ra khi máy đang có nhiều phiên bản Node, hoặc một bản cài cũ gây xung đột.

4. Biến môi trường biến mất sau khi mở cửa sổ mới

Bạn mới chỉ set trong session hiện tại, chưa lưu ở cấp user.

5. PowerShell chạy được nhưng WSL không chạy được

Đó là vì bạn đang dùng hai môi trường khác nhau. Mỗi bên cần cài và cấu hình riêng.

Kết luận

Nếu muốn cài Claude Code trên Windows theo cách ổn định và đỡ tốn thời gian debug, mình khuyên đi theo đúng thứ tự này:

PowerShell
Git
Node.js / npm
Claude Code
PATH
biến môi trường
test trong một Git repo thật

Làm đúng thứ tự này sẽ tiết kiệm thời gian hơn nhiều so với việc sửa từng lỗi lẻ tẻ sau khi cài.

Nếu sau đó bạn muốn kết nối Claude Code với gateway đa model, có thể cấu hình thêm OPENAI_BASE_URL và OPENAI_API_KEY để dùng qua Crazyrouter. Cách này khá tiện nếu bạn muốn thử nhiều model trong cùng một workflow mà không phải đổi cấu hình liên tục.

───

macOS 版

Title Mình đã cài Claude Code trên macOS như thế nào (2026): Git, PATH, zsh và các lỗi dễ gặp

Summary Nếu bạn cài Claude Code trên macOS nhưng lệnh claude không chạy, Homebrew bị lệch path hoặc biến môi trường không được lưu, bài này sẽ giúp bạn đi từng bước theo cách dễ debug hơn.

Tags macos, cli, ai, developer-tools, zsh

Body

Mình đã cài Claude Code trên macOS như thế nào (2026): Git, PATH, zsh và các lỗi dễ gặp

Trên macOS, nhiều người nghĩ rằng chỉ cần chạy một lệnh là mọi thứ sẽ xong. Nhưng khi bắt đầu dùng thật, phần dễ gặp lỗi nhất thường lại nằm ở những thứ rất cơ bản: Homebrew, shell, PATH, npm global bin, hoặc biến môi trường chỉ tồn tại trong cửa sổ terminal hiện tại.

Mình thấy lỗi trên macOS thường rơi vào mấy nhóm quen thuộc:

npm báo cài thành công nhưng claude không chạy
Git chưa được cài hoặc terminal không nhận Git
PATH chưa đúng nên shell không tìm thấy executable
biến môi trường chỉ có ở cửa sổ hiện tại
Apple Silicon và Intel dùng đường dẫn Homebrew khác nhau

Vì vậy bài này không đi theo kiểu “copy một lệnh là xong”. Mình sẽ đi theo trình tự đầy đủ, theo cách dễ debug hơn và đỡ mất thời gian sửa linh tinh về sau.

Nếu muốn ít lỗi, hãy kiểm tra đúng từng mắt xích

Claude Code không chỉ là một package npm. Để dùng ổn định trên macOS, bạn thường cần đủ các thành phần sau:

Terminal
Homebrew
Git
Node.js / npm
Claude Code
PATH
biến môi trường
một thư mục project có Git để test

Chỉ cần một mắt xích gặp vấn đề, bạn rất dễ rơi vào tình huống “đã cài nhưng không dùng được”.

Bước 1: Kiểm tra bạn đang dùng Apple Silicon hay Intel

Chạy:

uname -m

Kết quả thường là:

• arm64 → Apple Silicon
• x86_64 → Intel

Đây là chi tiết rất quan trọng, vì Homebrew thường nằm ở:

• /opt/homebrew trên Apple Silicon
• /usr/local trên Intel

Nếu bạn không để ý điểm này từ đầu, đến bước sửa PATH hoặc shell profile sẽ rất dễ nhầm.

Bước 2: Xác nhận shell hiện tại

Kiểm tra:

echo $SHELL

Phần lớn máy Mac hiện nay dùng zsh.

Nếu bạn đang dùng zsh, hai file quan trọng nhất thường là:

• ~/.zshrc
• ~/.zprofile

Thông thường, đây là nơi PATH và biến môi trường được thêm vào. Nếu về sau có lỗi “terminal này chạy được, terminal khác không chạy được”, gần như bạn sẽ quay lại kiểm tra hai file này.

Bước 3: Cài Homebrew

Kiểm tra Homebrew:

brew --version

Nếu chưa có, cài bằng lệnh chính thức:
[18/03/2026 16:57] whitemarshall_bot: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"


Sau khi cài xong, thêm Homebrew vào shell.

### Với Apple Silicon

```bash
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Với Intel

echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/usr/local/bin/brew shellenv)"

Kiểm tra lại:

which brew
brew --version

Nếu brew chỉ chạy trong terminal hiện tại mà không chạy ở terminal mới, vấn đề thường nằm ở chỗ shell profile chưa được thêm đúng.

Bước 4: Cài Git

Kiểm tra Git:

git --version

Nếu chưa có:

brew install git

Kiểm tra lại:

which git
git --version

Nếu muốn test trong một thư mục sạch:

mkdir -p ~/Projects/claude-code-test
cd ~/Projects/claude-code-test
git init

Git rất đáng để kiểm tra sớm, vì nhiều workflow thực tế của Claude Code làm việc trong repo có Git. Nếu Git chưa ổn, về sau bạn sẽ rất khó phân biệt lỗi đến từ công cụ hay từ môi trường.

Bước 5: Cài Node.js và npm

Kiểm tra:

node --version
npm --version

Nếu chưa có, cách đơn giản nhất là dùng Homebrew:

brew install node

Sau đó kiểm tra lại:

node --version
npm --version
which node
which npm

Nếu node hoặc npm chưa ổn ở bước này, mình khuyên nên xử lý dứt điểm trước khi cài Claude Code. Đừng vội đẩy lỗi lên tầng trên.

Bước 6: Cài Claude Code

Kiểm tra trước:

which claude
claude --version

Nếu chưa có, cài bằng npm global:

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

Sau đó kiểm tra lại:

which claude
claude --version

Nếu claude --version trả kết quả bình thường thì bạn đã qua được phần lớn bước cài đặt.

Bước 7: Nếu claude không chạy, hãy kiểm tra PATH trước

Lỗi phổ biến nhất trên macOS là:

zsh: command not found: claude

Lúc này, việc đầu tiên nên làm là kiểm tra npm global prefix:

npm config get prefix

Sau đó xem thư mục bin:

ls "$(npm config get prefix)/bin"

Nếu trong đó có claude, hãy thêm nó vào PATH:

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

Rồi kiểm tra lại:

which claude
claude --version

Kinh nghiệm thực tế là: nếu package đã cài nhưng shell vẫn không nhận lệnh, thì PATH gần như luôn là thứ cần kiểm tra đầu tiên.

Bước 8: Thiết lập biến môi trường

Tùy workflow, bạn có thể cần các biến như:

export ANTHROPIC_API_KEY="your_key_here"
export OPENAI_API_KEY="your_gateway_key"
export OPENAI_BASE_URL="https://crazyrouter.com/v1"

Nếu chỉ export như vậy, biến sẽ chỉ tồn tại trong cửa sổ hiện tại.

Để lưu lâu dài, thêm vào ~/.zshrc:

echo 'export ANTHROPIC_API_KEY="your_key_here"' >> ~/.zshrc
echo 'export OPENAI_API_KEY="your_gateway_key"' >> ~/.zshrc
echo 'export OPENAI_BASE_URL="https://crazyrouter.com/v1"' >> ~/.zshrc
source ~/.zshrc

Nếu bạn dùng gateway tương thích OpenAI như Crazyrouter, việc thêm sẵn OPENAI_BASE_URL và OPENAI_API_KEY sẽ giúp workflow gọn hơn khá nhiều khi bạn muốn thử nhiều model khác nhau.

Bộ lệnh kiểm tra nhanh

git --version
node --version
npm --version
claude --version
echo $SHELL
git status || true
[18/03/2026 16:57] whitemarshall_bot: 
Nếu các lệnh trên đều chạy ổn, môi trường của bạn đã khá đầy đủ để bắt đầu dùng Claude Code.

## 5 lỗi mình thấy gặp nhiều nhất trên macOS

### 1. `claude` không được nhận diện

Nguyên nhân phổ biến nhất là npm global bin chưa nằm trong `PATH`.

### 2. Git chưa có hoặc terminal không nhận Git

Hãy cài bằng Homebrew rồi mở terminal mới để kiểm tra lại.

### 3. Node/npm có vấn đề

Hãy kiểm tra xem máy đang dùng Homebrew, `nvm` hay một bản cài cũ khác. Nhiều bản Node tồn tại song song rất dễ gây xung đột.

### 4. Biến môi trường chỉ có ở cửa sổ hiện tại

Bạn mới chỉ `export` tạm thời, chưa thêm vào `~/.zshrc` hoặc file shell tương ứng.

### 5. Homebrew chạy ở terminal này nhưng không chạy ở terminal khác

Hãy kiểm tra lại `~/.zprofile` và `~/.zshrc`, sau đó đóng hẳn terminal và mở lại.

## Kết luận

Nếu muốn cài Claude Code trên macOS theo cách ổn định và dễ debug hơn, mình khuyên đi theo đúng thứ tự sau:

1. Homebrew
2. Git
3. Node.js / npm
4. Claude Code
5. `PATH`
6. biến môi trường
7. test trong một project có Git

Đi đúng trình tự này sẽ giúp bạn tiết kiệm khá nhiều thời gian so với việc sửa từng lỗi lẻ tẻ sau khi cài.

Nếu sau đó bạn muốn dùng Claude Code với gateway đa model, có thể cấu hình thêm `OPENAI_BASE_URL` và `OPENAI_API_KEY` để kết nối qua Crazyrouter. Cách này khá tiện nếu bạn muốn thử nhiều model trong cùng một workflow mà không phải thay đổi cấu hình liên tục.

5 lỗi mình thấy gặp nhiều nhất

1. claude không được nhận diện

2. Git đã cài nhưng vẫn không chạy

3. Node có nhưng npm hoạt động bất thường

4. Biến môi trường biến mất sau khi mở cửa sổ mới

5. PowerShell chạy được nhưng WSL không chạy được

Kết luận

Mình đã cài Claude Code trên macOS như thế nào (2026): Git, PATH, zsh và các lỗi dễ gặp

Nếu muốn ít lỗi, hãy kiểm tra đúng từng mắt xích

Bước 1: Kiểm tra bạn đang dùng Apple Silicon hay Intel

Mục lục

1. `claude` không được nhận diện