Node.js + npm (PATH sanity)

OpenClaw yêu cầu Node 22 trở lên.

Nếu các bạn chạy npm install -g openclaw@latest thành công nhưng sau đó gặp lỗi openclaw: command not found, thì gần như chắc chắn là do vấn đề PATH: thư mục mà npm lưu các file binary global không nằm trong PATH của shell.

Kiểm tra nhanh

Chạy các lệnh sau:

node -v
npm -v
npm prefix -g
echo "$PATH"

Nếu $(npm prefix -g)/bin (macOS/Linux) hoặc $(npm prefix -g) (Windows) không có trong kết quả của echo "$PATH", thì shell không thể tìm thấy các binary npm global (bao gồm cả openclaw).

Cách fix: thêm thư mục npm global bin vào PATH

  1. Tìm global npm prefix của các bạn:
npm prefix -g
  1. Thêm thư mục npm global bin vào file startup của shell:
  • zsh: ~/.zshrc
  • bash: ~/.bashrc

Ví dụ (thay đường dẫn bằng kết quả từ npm prefix -g của các bạn):

# macOS / Linux
export PATH="/path/from/npm/prefix/bin:$PATH"

Sau đó mở terminal mới (hoặc chạy rehash trong zsh / hash -r trong bash).

Trên Windows, thêm kết quả của npm prefix -g vào PATH của hệ thống.

Cách fix: tránh sudo npm install -g / lỗi permissions (Linux)

Nếu npm install -g ... bị lỗi EACCES, hãy chuyển npm global prefix sang thư mục mà user có quyền ghi:

mkdir -p "$HOME/.npm-global"
npm config set prefix "$HOME/.npm-global"
export PATH="$HOME/.npm-global/bin:$PATH"

Nhớ thêm dòng export PATH=... vào file startup của shell để lưu cấu hình này nhé.

Các cách cài Node.js được khuyên dùng

Các bạn sẽ gặp ít vấn đề nhất nếu cài Node/npm theo cách:

  • giữ Node luôn được cập nhật (22+)
  • làm cho thư mục npm global bin ổn định và có trong PATH của các shell mới

Các lựa chọn phổ biến:

  • macOS: Homebrew (brew install node) hoặc version manager
  • Linux: version manager mà các bạn thích, hoặc cài từ distro hỗ trợ Node 22+
  • Windows: Node installer chính thức, winget, hoặc Windows Node version manager

Nếu các bạn dùng version manager (nvm/fnm/asdf/etc), hãy đảm bảo nó được khởi tạo trong shell mà các bạn dùng hàng ngày (zsh hay bash) để PATH được set đúng khi chạy các installer.