Cài đặt

Dùng installer trừ khi các bạn có lý do đặc biệt. Nó sẽ setup CLI và chạy onboarding.

Cài nhanh (khuyên dùng)

curl -fsSL https://openclaw.ai/install.sh | bash

Windows (PowerShell):

iwr -useb https://openclaw.ai/install.ps1 | iex

Bước tiếp theo (nếu bỏ qua onboarding):

openclaw onboard --install-daemon

Yêu cầu hệ thống

  • Node >=22
  • macOS, Linux, hoặc Windows qua WSL2
  • pnpm chỉ cần nếu build từ source

Chọn cách cài đặt

1) Installer script (khuyên dùng)

Cài openclaw global qua npm và chạy onboarding.

curl -fsSL https://openclaw.ai/install.sh | bash

Các flag của installer:

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --help

Chi tiết: Installer internals.

Chế độ không tương tác (bỏ qua onboarding):

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

2) Cài global (thủ công)

Nếu các bạn đã có Node:

npm install -g openclaw@latest

Nếu các bạn đã cài libvips global (phổ biến trên macOS qua Homebrew) và sharp bị lỗi khi cài, hãy force dùng prebuilt binaries:

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

Nếu thấy lỗi sharp: Please add node-gyp to your dependencies, các bạn có thể cài build tooling (macOS: Xcode CLT + npm install -g node-gyp) hoặc dùng workaround SHARP_IGNORE_GLOBAL_LIBVIPS=1 ở trên để bỏ qua native build.

Hoặc dùng pnpm:

pnpm add -g openclaw@latest
pnpm approve-builds -g                # approve openclaw, node-llama-cpp, sharp, etc.
pnpm add -g openclaw@latest           # chạy lại để execute postinstall scripts

pnpm yêu cầu approve rõ ràng cho các package có build scripts. Sau khi lần cài đầu tiên hiện cảnh báo “Ignored build scripts”, chạy pnpm approve-builds -g và chọn các package được liệt kê, sau đó chạy lại lệnh cài để postinstall scripts được thực thi.

Sau đó:

openclaw onboard --install-daemon

3) Từ source (contributors/dev)

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build # tự động cài UI deps ở lần chạy đầu
pnpm build
openclaw onboard --install-daemon

Tip: nếu chưa có global install, chạy lệnh repo qua pnpm openclaw ....

4) Các tùy chọn cài đặt khác

Sau khi cài

  • Chạy onboarding: openclaw onboard --install-daemon
  • Kiểm tra nhanh: openclaw doctor
  • Kiểm tra Gateway health: openclaw status + openclaw health
  • Mở dashboard: openclaw dashboard

Phương thức cài: npm vs git (installer)

Installer hỗ trợ hai phương thức:

  • npm (mặc định): npm install -g openclaw@latest
  • git: clone/build từ GitHub và chạy từ source checkout

CLI flags

# Chỉ định npm rõ ràng
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm

# Cài từ GitHub (source checkout)
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git

Các flag thường dùng:

  • --install-method npm|git
  • --git-dir <path> (mặc định: ~/openclaw)
  • --no-git-update (bỏ qua git pull khi dùng checkout có sẵn)
  • --no-prompt (tắt prompts; cần thiết trong CI/automation)
  • --dry-run (in ra những gì sẽ xảy ra; không thay đổi gì)
  • --no-onboard (bỏ qua onboarding)

Biến môi trường

Các biến env tương đương (hữu ích cho automation):

  • OPENCLAW_INSTALL_METHOD=git|npm
  • OPENCLAW_GIT_DIR=...
  • OPENCLAW_GIT_UPDATE=0|1
  • OPENCLAW_NO_PROMPT=1
  • OPENCLAW_DRY_RUN=1
  • OPENCLAW_NO_ONBOARD=1
  • SHARP_IGNORE_GLOBAL_LIBVIPS=0|1 (mặc định: 1; tránh sharp build với system libvips)

Troubleshooting: không tìm thấy openclaw (PATH)

Chẩn đoán nhanh:

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 echo "$PATH", shell của các bạn không tìm thấy npm binaries global (bao gồm openclaw).

Cách sửa: thêm vào shell startup file (zsh: ~/.zshrc, bash: ~/.bashrc):

# macOS / Linux
export PATH="$(npm prefix -g)/bin:$PATH"

Trên Windows, thêm output của npm prefix -g vào PATH.

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

Cập nhật / gỡ cài đặt