Chi tiết bên trong Installer

OpenClaw cung cấp ba script cài đặt, được phục vụ từ openclaw.ai.

Script	Nền tảng	Chức năng
`install.sh`	macOS / Linux / WSL	Cài đặt Node nếu cần, cài đặt OpenClaw qua npm (mặc định) hoặc git, và có thể chạy onboarding.
`install-cli.sh`	macOS / Linux / WSL	Cài đặt Node + OpenClaw vào một prefix cục bộ (`~/.openclaw`). Không cần quyền root.
`install.ps1`	Windows (PowerShell)	Cài đặt Node nếu cần, cài đặt OpenClaw qua npm (mặc định) hoặc git, và có thể chạy onboarding.

Lệnh nhanh

install.sh
install-cli.sh
install.ps1

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --help

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --help

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

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -Tag beta -NoOnboard -DryRun

Nếu cài đặt thành công nhưng không tìm thấy openclaw trong terminal mới, hãy xem khắc phục sự cố Node.js.

install.sh

Khuyến nghị cho hầu hết các cài đặt tương tác trên macOS/Linux/WSL.

Quy trình (install.sh)

Phát hiện hệ điều hành

Hỗ trợ macOS và Linux (bao gồm WSL). Nếu phát hiện macOS, cài đặt Homebrew nếu chưa có.

Đảm bảo Node.js 24 mặc định

Kiểm tra phiên bản Node và cài đặt Node 24 nếu cần (Homebrew trên macOS, script thiết lập NodeSource trên Linux apt/dnf/yum). OpenClaw vẫn hỗ trợ Node 22 LTS, hiện tại là 22.16+, để tương thích.

Đảm bảo Git

Cài đặt Git nếu chưa có.

Cài đặt OpenClaw

Phương pháp npm (mặc định): cài đặt npm toàn cầu
Phương pháp git: clone/cập nhật repo, cài đặt phụ thuộc với pnpm, build, sau đó cài đặt wrapper tại ~/.local/bin/openclaw

Nhiệm vụ sau cài đặt

Chạy openclaw doctor --non-interactive khi nâng cấp và cài đặt git (nỗ lực tốt nhất)
Thực hiện onboarding khi thích hợp (TTY có sẵn, onboarding không bị vô hiệu hóa, và kiểm tra bootstrap/cấu hình thành công)
Mặc định SHARP_IGNORE_GLOBAL_LIBVIPS=1

Phát hiện checkout nguồn

Nếu chạy bên trong một checkout OpenClaw (package.json + pnpm-workspace.yaml), script cung cấp:

sử dụng checkout (git), hoặc
sử dụng cài đặt toàn cầu (npm)

Nếu không có TTY và không có phương pháp cài đặt nào được thiết lập, nó mặc định là npm và cảnh báo. Script thoát với mã 2 cho lựa chọn phương pháp không hợp lệ hoặc giá trị --install-method không hợp lệ.

Ví dụ (install.sh)

Mặc định
Bỏ qua onboarding
Cài đặt Git
GitHub main qua npm
Chạy thử

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-onboard

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --version main

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --dry-run

Tham khảo các flag

Flag	Mô tả
`--install-method npm\|git`	Chọn phương pháp cài đặt (mặc định: `npm`). Alias: `--method`
`--npm`	Phím tắt cho phương pháp npm
`--git`	Phím tắt cho phương pháp git. Alias: `--github`
`--version <version\|dist-tag\|spec>`	Phiên bản npm, dist-tag, hoặc spec package (mặc định: `latest`)
`--beta`	Sử dụng beta dist-tag nếu có, nếu không thì dùng `latest`
`--git-dir <path>`	Thư mục checkout (mặc định: `~/openclaw`). Alias: `--dir`
`--no-git-update`	Bỏ qua `git pull` cho checkout hiện có
`--no-prompt`	Vô hiệu hóa nhắc nhở
`--no-onboard`	Bỏ qua onboarding
`--onboard`	Kích hoạt onboarding
`--dry-run`	In ra các hành động mà không áp dụng thay đổi
`--verbose`	Kích hoạt đầu ra debug (`set -x`, nhật ký cấp độ thông báo npm)
`--help`	Hiển thị cách sử dụng (`-h`)

Tham khảo các biến môi trường

Biến	Mô tả
`OPENCLAW_INSTALL_METHOD=git\|npm`	Phương pháp cài đặt
`OPENCLAW_VERSION=latest\|next\|main\|<semver>\|<spec>`	Phiên bản npm, dist-tag, hoặc spec package
`OPENCLAW_BETA=0\|1`	Sử dụng beta nếu có
`OPENCLAW_GIT_DIR=<path>`	Thư mục checkout
`OPENCLAW_GIT_UPDATE=0\|1`	Bật/tắt cập nhật git
`OPENCLAW_NO_PROMPT=1`	Vô hiệu hóa nhắc nhở
`OPENCLAW_NO_ONBOARD=1`	Bỏ qua onboarding
`OPENCLAW_DRY_RUN=1`	Chế độ chạy thử
`OPENCLAW_VERBOSE=1`	Chế độ debug
`OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice`	Mức độ nhật ký npm
`SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1`	Kiểm soát hành vi sharp/libvips (mặc định: `1`)

install-cli.sh

Thiết kế cho các môi trường mà bạn muốn mọi thứ nằm dưới một prefix cục bộ (mặc định ~/.openclaw) và không phụ thuộc vào Node hệ thống.

Quy trình (install-cli.sh)

Cài đặt runtime Node cục bộ

Tải xuống một tarball Node LTS được hỗ trợ đã được ghim (phiên bản được nhúng trong script và cập nhật độc lập) vào <prefix>/tools/node-v<version> và xác minh SHA-256.

Đảm bảo Git

Nếu Git thiếu, cố gắng cài đặt qua apt/dnf/yum trên Linux hoặc Homebrew trên macOS.

Cài đặt OpenClaw dưới prefix

Cài đặt với npm sử dụng --prefix <prefix>, sau đó ghi wrapper vào <prefix>/bin/openclaw.

Ví dụ (install-cli.sh)

Mặc định
Prefix tùy chỉnh + phiên bản
Đầu ra JSON tự động
Chạy onboarding

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix /opt/openclaw --version latest

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --onboard

Tham khảo các flag

Flag	Mô tả
`--prefix <path>`	Prefix cài đặt (mặc định: `~/.openclaw`)
`--version <ver>`	Phiên bản OpenClaw hoặc dist-tag (mặc định: `latest`)
`--node-version <ver>`	Phiên bản Node (mặc định: `22.22.0`)
`--json`	Xuất sự kiện NDJSON
`--onboard`	Chạy `openclaw onboard` sau khi cài đặt
`--no-onboard`	Bỏ qua onboarding (mặc định)
`--set-npm-prefix`	Trên Linux, buộc npm prefix thành `~/.npm-global` nếu prefix hiện tại không ghi được
`--help`	Hiển thị cách sử dụng (`-h`)

Tham khảo các biến môi trường

Biến	Mô tả
`OPENCLAW_PREFIX=<path>`	Prefix cài đặt
`OPENCLAW_VERSION=<ver>`	Phiên bản OpenClaw hoặc dist-tag
`OPENCLAW_NODE_VERSION=<ver>`	Phiên bản Node
`OPENCLAW_NO_ONBOARD=1`	Bỏ qua onboarding
`OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice`	Mức độ nhật ký npm
`OPENCLAW_GIT_DIR=<path>`	Đường dẫn tìm kiếm dọn dẹp cũ (sử dụng khi loại bỏ checkout submodule `Peekaboo` cũ)
`SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1`	Kiểm soát hành vi sharp/libvips (mặc định: `1`)

install.ps1

Quy trình (install.ps1)

Đảm bảo môi trường PowerShell + Windows

Yêu cầu PowerShell 5+.

Đảm bảo Node.js 24 mặc định

Nếu thiếu, cố gắng cài đặt qua winget, sau đó Chocolatey, rồi Scoop. Node 22 LTS, hiện tại là 22.16+, vẫn được hỗ trợ để tương thích.

Cài đặt OpenClaw

Phương pháp npm (mặc định): cài đặt npm toàn cầu sử dụng -Tag đã chọn
Phương pháp git: clone/cập nhật repo, cài đặt/xây dựng với pnpm, và cài đặt wrapper tại %USERPROFILE%\.local\bin\openclaw.cmd

Nhiệm vụ sau cài đặt

Thêm thư mục bin cần thiết vào PATH người dùng khi có thể, sau đó chạy openclaw doctor --non-interactive khi nâng cấp và cài đặt git (nỗ lực tốt nhất).

Ví dụ (install.ps1)

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

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -Tag main

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git -GitDir "C:\openclaw"

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -DryRun

# install.ps1 chưa có flag -Verbose riêng.
Set-PSDebug -Trace 1
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0

Tham khảo các flag

Flag	Mô tả
`-InstallMethod npm\|git`	Phương pháp cài đặt (mặc định: `npm`)
`-Tag <tag\|version\|spec>`	npm dist-tag, phiên bản, hoặc spec package (mặc định: `latest`)
`-GitDir <path>`	Thư mục checkout (mặc định: `%USERPROFILE%\openclaw`)
`-NoOnboard`	Bỏ qua onboarding
`-NoGitUpdate`	Bỏ qua `git pull`
`-DryRun`	Chỉ in ra các hành động

Tham khảo các biến môi trường

Biến	Mô tả
`OPENCLAW_INSTALL_METHOD=git\|npm`	Phương pháp cài đặt
`OPENCLAW_GIT_DIR=<path>`	Thư mục checkout
`OPENCLAW_NO_ONBOARD=1`	Bỏ qua onboarding
`OPENCLAW_GIT_UPDATE=0`	Vô hiệu hóa git pull
`OPENCLAW_DRY_RUN=1`	Chế độ chạy thử

Nếu sử dụng -InstallMethod git và Git thiếu, script sẽ thoát và in ra liên kết Git for Windows.

CI và tự động hóa

Sử dụng các flag/biến môi trường không tương tác để chạy ổn định.

install.sh (npm không tương tác)
install.sh (git không tương tác)
install-cli.sh (JSON)
install.ps1 (bỏ qua onboarding)

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-prompt --no-onboard

OPENCLAW_INSTALL_METHOD=git OPENCLAW_NO_PROMPT=1 \
  curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

Khắc phục sự cố

Tại sao cần Git?

Git cần thiết cho phương pháp cài đặt git. Đối với cài đặt npm, Git vẫn được kiểm tra/cài đặt để tránh lỗi spawn git ENOENT khi các phụ thuộc sử dụng URL git.

Tại sao npm gặp lỗi EACCES trên Linux?

Một số thiết lập Linux chỉ định npm global prefix đến các đường dẫn thuộc quyền root. install.sh có thể chuyển prefix thành ~/.npm-global và thêm các xuất PATH vào các file rc shell (khi các file đó tồn tại).

Vấn đề sharp/libvips

Các script mặc định SHARP_IGNORE_GLOBAL_LIBVIPS=1 để tránh sharp xây dựng dựa trên libvips hệ thống. Để ghi đè:

SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

Windows: "npm error spawn git / ENOENT"

Cài đặt Git for Windows, mở lại PowerShell, chạy lại installer.

Windows: "openclaw không được nhận diện"

Chạy npm config get prefix và thêm thư mục đó vào PATH người dùng của bạn (không cần hậu tố \bin trên Windows), sau đó mở lại PowerShell.

Windows: làm thế nào để có đầu ra installer chi tiết

install.ps1 hiện không cung cấp switch -Verbose. Sử dụng theo dõi PowerShell để chẩn đoán cấp độ script:

Set-PSDebug -Trace 1
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0

openclaw không tìm thấy sau khi cài đặt

Thường là vấn đề PATH. Xem khắc phục sự cố Node.js.

Tổng quan cài đặt

Chạy qua Container

Triển khai (Hosting)

Bảo trì & Nâng cấp

Chi tiết bên trong Installer

Chi tiết bên trong Installer

Lệnh nhanh

install.sh

Quy trình (install.sh)

Phát hiện checkout nguồn

Ví dụ (install.sh)

install-cli.sh

Quy trình (install-cli.sh)

Ví dụ (install-cli.sh)

install.ps1

Quy trình (install.ps1)

Ví dụ (install.ps1)

CI và tự động hóa

Khắc phục sự cố

​Chi tiết bên trong Installer

​Lệnh nhanh

​install.sh

​Quy trình (install.sh)

​Phát hiện checkout nguồn

​Ví dụ (install.sh)

​install-cli.sh

​Quy trình (install-cli.sh)

​Ví dụ (install-cli.sh)

​install.ps1

​Quy trình (install.ps1)

​Ví dụ (install.ps1)

​CI và tự động hóa

​Khắc phục sự cố

Chi tiết bên trong Installer

Lệnh nhanh

install.sh

Quy trình (install.sh)

Phát hiện checkout nguồn

Ví dụ (install.sh)

install-cli.sh

Quy trình (install-cli.sh)

Ví dụ (install-cli.sh)

install.ps1

Quy trình (install.ps1)

Ví dụ (install.ps1)

CI và tự động hóa

Khắc phục sự cố