Cài đặt

Đã làm theo Bắt đầu nhanh rồi? Vậy là xong — trang này dành cho các phương pháp cài đặt thay thế, hướng dẫn theo nền tảng và bảo trì.

Yêu cầu hệ thống

Node 24 (khuyến nghị) (Node 22 LTS, hiện tại 22.16+, vẫn được hỗ trợ để tương thích; script cài đặt sẽ cài Node 24 nếu chưa có)
macOS, Linux hoặc Windows
pnpm chỉ cần khi bạn build từ mã nguồn

Lưu ý: Trên Windows, chúng tôi khuyến nghị chạy OpenClaw dưới WSL2.

Phương thức cài đặt

Mẹo: Script cài đặt là cách được khuyến nghị để cài OpenClaw. Nó xử lý phát hiện Node, cài đặt và thiết lập ban đầu trong một bước.

Cảnh báo: Đối với VPS/cloud host, hãy tránh sử dụng image “1-click” từ marketplace bên thứ ba khi có thể. Ưu tiên image OS gốc sạch (ví dụ Ubuntu LTS), sau đó tự cài OpenClaw bằng script cài đặt.

Script cài đặt

Tải CLI, cài đặt toàn cục qua npm và khởi chạy trình hướng dẫn thiết lập.


  #### macOS / Linux / WSL2
    ```bash
    curl -fsSL https://openclaw.ai/install.sh | bash
    ```

  #### Windows (PowerShell)
    ```powershell
    iwr -useb https://openclaw.ai/install.ps1 | iex
    ```



Vậy là xong — script xử lý phát hiện Node, cài đặt và thiết lập ban đầu.

Để bỏ qua thiết lập ban đầu và chỉ cài binary:


  #### macOS / Linux / WSL2
    ```bash
    curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
    ```

  #### Windows (PowerShell)
    ```powershell
    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
    ```



Để xem tất cả flag, biến môi trường và tùy chọn CI/tự động hóa, xem [Chi tiết script cài đặt](/docs/install/installer).

npm / pnpm

Nếu bạn đã tự quản lý Node, chúng tôi khuyến nghị Node 24. OpenClaw vẫn hỗ trợ Node 22 LTS, hiện tại `22.16+`, để tương thích:


  #### npm
    ```bash
    npm install -g openclaw@latest
    openclaw onboard --install-daemon
    ```

    <details>

Lỗi build sharp?

      Nếu bạn đã cài libvips toàn cục (phổ biến trên macOS qua Homebrew) và `sharp` bị lỗi, hãy buộc dùng binary dựng sẵn:

      ```bash
      SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest
      ```

      Nếu bạn thấy `sharp: Please add node-gyp to your dependencies`, hãy cài công cụ build (macOS: Xcode CLT + `npm install -g node-gyp`) hoặc dùng biến môi trường ở trên.
    </details>

  #### pnpm
    ```bash
    pnpm add -g openclaw@latest
    pnpm approve-builds -g        # phê duyệt openclaw, node-llama-cpp, sharp, v.v.
    openclaw onboard --install-daemon
    ```

    > **Lưu ý:** pnpm yêu cầu phê duyệt rõ ràng cho các package có build script. Sau lần cài đầu tiên hiển thị cảnh báo "Ignored build scripts", chạy `pnpm approve-builds -g` và chọn các package được liệt kê.

Từ mã nguồn

Dành cho contributor hoặc ai muốn chạy từ checkout cục bộ.


  ### Bước 1: Clone và build
    Clone [repo OpenClaw](https://github.com/openclaw/openclaw) và build:

    ```bash
    git clone https://github.com/openclaw/openclaw.git
    cd openclaw
    pnpm install
    pnpm ui:build
    pnpm build
    ```

  ### Bước 2: Link CLI
    Đưa lệnh `openclaw` ra toàn cục:

    ```bash
    pnpm link --global
    ```

    Hoặc bỏ qua bước link và chạy lệnh qua `pnpm openclaw ...` từ bên trong repo.

  ### Bước 3: Chạy thiết lập ban đầu
    ```bash
    openclaw onboard --install-daemon
    ```



Để tìm hiểu quy trình phát triển sâu hơn, xem [Thiết lập](/docs/start/setup).

Phương thức cài đặt khác

Docker — Triển khai container hoặc headless.
Podman — Container rootless: chạy setup-podman.sh một lần, sau đó dùng script khởi chạy.
Nix — Cài đặt khai báo qua Nix.
Ansible — Triển khai tự động hàng loạt.
Bun — Sử dụng CLI qua runtime Bun.

Sau khi cài đặt

Kiểm tra mọi thứ hoạt động bình thường:

openclaw doctor         # kiểm tra vấn đề cấu hình
openclaw status         # trạng thái gateway
openclaw dashboard      # mở giao diện trình duyệt

Nếu bạn cần đường dẫn runtime tùy chỉnh, sử dụng:

OPENCLAW_HOME cho đường dẫn nội bộ dựa trên thư mục home
OPENCLAW_STATE_DIR cho vị trí lưu trữ trạng thái
OPENCLAW_CONFIG_PATH cho vị trí file cấu hình

Xem Biến môi trường để biết thứ tự ưu tiên và chi tiết đầy đủ.

Xử lý sự cố: không tìm thấy `openclaw`

Chẩn đoán và sửa 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 nằm trong $PATH, shell của bạn không thể tìm thấy các binary npm toàn cục (bao gồm openclaw).

Sửa — thêm vào file khởi động shell (~/.zshrc hoặc ~/.bashrc):

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

Cập nhật — Giữ OpenClaw luôn mới nhất.
Di chuyển — Chuyển sang máy mới.
Gỡ cài đặt — Xóa OpenClaw hoàn toàn.