Cơ chế nội bộ của trình cài đặt

OpenClaw cung cấp ba tập lệnh cài đặt, được phân phối từ openclaw.ai.

Tập lệnh	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 quy trình thiết lập ban đầu.
install-cli.sh	macOS / Linux / WSL	Cài đặt Node + OpenClaw vào một tiền tố cục bộ (~/.openclaw) qua npm hoặc git. Không yêu cầu 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 quy trình thiết lập ban đầu.

Cả ba đều hỗ trợ Node 22.22.3+, 24.15+ hoặc 25.9+; Node 24 là phiên bản đích mặc định cho các lượt cài đặt mới.

​

Lệnh nhanh

install.sh

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

install-cli.sh

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

install.ps1

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

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

​

Quy trình (install.sh)

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

   Hỗ trợ macOS và Linux (bao gồm WSL).

2. Mặc định bảo đảm có Node.js 24

   Kiểm tra phiên bản Node và cài đặt Node 24 nếu cần (Homebrew trên macOS, các tập lệnh thiết lập NodeSource trên Linux apt/dnf/yum). Trên macOS, Homebrew chỉ được cài đặt khi trình cài đặt cần dùng để cài Node hoặc Git. Node 22.22.3+, Node 24.15+ và Node 25.9+ được hỗ trợ; Node 23 không được hỗ trợ. Trên Alpine/musl Linux, trình cài đặt dùng các gói apk thay cho NodeSource và xác minh phiên bản SQLite thực tế được liên kết. Các luồng gói Alpine ổn định hiện tại có thể cung cấp phiên bản Node đủ mới nhưng liên kết với SQLite hệ thống có lỗ hổng; khi điều đó xảy ra, hãy dùng container node:24-alpine chính thức hoặc máy chủ dựa trên glibc.

3. Bảo đảm có Git

   Cài đặt Git nếu chưa có bằng trình quản lý gói được phát hiện, bao gồm Homebrew trên macOS và apk trên Alpine.

4. Cài đặt OpenClaw

   • Phương thức npm (mặc định): cài đặt npm toàn cục
   • Phương thức git: sao chép/cập nhật kho mã nguồn, cài đặt các phần phụ thuộc bằng pnpm, dựng dự án, sau đó cài đặt trình bao bọc tại ~/.local/bin/openclaw
5. Tác vụ sau cài đặt

   • Phân giải tệp nhị phân openclaw vừa cài đặt để dùng cho các lệnh tiếp theo
   • Đối với bản cài đặt chưa được cấu hình, bắt đầu quy trình thiết lập ban đầu trước khi chạy doctor hoặc kiểm tra Gateway. Khi dùng --no-onboard hoặc không có TTY, tập lệnh sẽ in lệnh để hoàn tất thiết lập sau.
   • Đối với bản cài đặt đã được cấu hình, cố gắng hết mức có thể để làm mới và khởi động lại dịch vụ Gateway đã được nạp, rồi chạy doctor. Khi nâng cấp, tập lệnh cập nhật các Plugin nếu có thể hoặc in lệnh thủ công trong lượt chạy không có giao diện nhưng cho phép lời nhắc.
   • Khi --verify chạy, tập lệnh kiểm tra phiên bản đã cài đặt và chỉ kiểm tra tình trạng Gateway sau khi đã có cấu hình.

​

Phát hiện bản sao mã nguồn

Nếu chạy bên trong một bản sao mã nguồn OpenClaw (package.json + pnpm-workspace.yaml), tập lệnh cung cấp các lựa chọn:

• dùng bản sao mã nguồn (git), hoặc
• dùng bản cài đặt toàn cục (npm)

Nếu không có TTY và chưa đặt phương thức cài đặt, tập lệnh mặc định dùng npm và đưa ra cảnh báo.

Tập lệnh thoát với mã 2 khi lựa chọn phương thức không hợp lệ hoặc giá trị --install-method không hợp lệ.

​

Ví dụ (install.sh)

Mặc định

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

Bỏ qua thiết lập ban đầu

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

Cài đặt bằng Git

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

Bản sao nhánh main trên GitHub

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

Chạy thử

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

Xác minh sau khi cài đặt

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

Tham chiếu cờ

Cờ	Mô tả
--install-method | --method npm|git	Chọn phương thức cài đặt (mặc định: npm)
--npm	Lối tắt cho phương thức npm
--git | --github	Lối tắt cho phương thức git
--version <version|dist-tag|spec>	Phiên bản npm, dist-tag hoặc đặc tả gói (mặc định: latest)
--beta	Dùng dist-tag beta nếu có, nếu không thì chuyển về latest
--git-dir | --dir <path>	Thư mục bản sao mã nguồn (mặc định: ~/openclaw)
--no-git-update	Bỏ qua git pull đối với bản sao mã nguồn hiện có
--no-prompt	Tắt lời nhắc
--no-onboard	Bỏ qua thiết lập ban đầu
--onboard	Bật thiết lập ban đầu
--verify	Chạy xác minh nhanh sau cài đặt (--version, tình trạng Gateway nếu đã được nạp)
--dry-run	In các hành động mà không áp dụng thay đổi
--verbose	Bật đầu ra gỡ lỗi (set -x, nhật ký npm ở mức notice)
--help | -h	Hiển thị cách dùng

Tham chiếu biến môi trường

Biến	Mô tả
OPENCLAW_INSTALL_METHOD=git|npm	Phương thức cài đặt
OPENCLAW_VERSION=latest|next|<semver>|<spec>	Phiên bản npm, dist-tag hoặc đặc tả gói
OPENCLAW_BETA=0|1	Dùng phiên bản beta nếu có
OPENCLAW_HOME=<path>	Thư mục cơ sở cho trạng thái OpenClaw và các đường dẫn git/thiết lập ban đầu mặc định
OPENCLAW_GIT_DIR=<path>	Thư mục bản sao mã nguồn
OPENCLAW_GIT_UPDATE=0|1	Bật/tắt cập nhật git
OPENCLAW_NO_PROMPT=1	Tắt lời nhắc
OPENCLAW_VERIFY_INSTALL=1	Chạy xác minh nhanh sau cài đặt
OPENCLAW_NO_ONBOARD=1	Bỏ qua thiết lập ban đầu
OPENCLAW_DRY_RUN=1	Chế độ chạy thử
OPENCLAW_VERBOSE=1	Chế độ gỡ lỗi
OPENCLAW_NPM_LOGLEVEL=error|warn|notice	Mức nhật ký npm (mặc định: error, ẩn thông báo ngừng hỗ trợ của npm)

---

​

install-cli.sh

Được thiết kế cho các môi trường mà bạn muốn mọi thứ nằm dưới một tiền tố cục bộ (mặc định ~/.openclaw) và không phụ thuộc vào Node hệ thống. Mặc định hỗ trợ cài đặt bằng npm, đồng thời hỗ trợ cài đặt từ bản sao mã nguồn git theo cùng quy trình tiền tố.

​

Quy trình (install-cli.sh)

1. Cài đặt môi trường chạy Node cục bộ

   Tải xuống tarball Node LTS được ghim ở phiên bản được hỗ trợ (phiên bản được nhúng trong tập lệnh và cập nhật độc lập, mặc định 24.15.0) vào <prefix>/tools/node-v<version> và xác minh SHA-256. Linux ARMv7 dùng Node 22.22.3 vì không có tệp nhị phân ARMv7 chính thức cho Node 24+. Trên Alpine/musl Linux, nơi Node không phát hành tarball tương thích với môi trường chạy được ghim, tập lệnh cài đặt nodejs và npm bằng apk, sau đó xác minh cả Node lẫn thư viện SQLite thực tế được liên kết. Các luồng gói Alpine ổn định hiện tại vẫn có thể liên kết với SQLite có lỗ hổng ngay cả khi Node đủ mới; hãy dùng container node:24-alpine chính thức hoặc máy chủ dựa trên glibc khi kiểm tra an toàn từ chối gói đó.

2. Bảo đảm có Git

   Nếu chưa có Git, tập lệnh sẽ thử cài đặt qua apt/dnf/yum/apk trên Linux hoặc Homebrew trên macOS.

3. Cài đặt OpenClaw dưới tiền tố

   • Phương thức npm (mặc định): cài đặt dưới tiền tố bằng npm, sau đó ghi trình bao bọc vào <prefix>/bin/openclaw
   • Phương thức git: sao chép/cập nhật một bản sao mã nguồn (mặc định ~/openclaw) và vẫn ghi trình bao bọc vào <prefix>/bin/openclaw
4. Làm mới dịch vụ Gateway đã được nạp

   Nếu một dịch vụ Gateway đã được nạp từ chính tiền tố đó, tập lệnh sẽ chạy openclaw gateway install --force, thao tác này kích hoạt dịch vụ thay thế, rồi cố gắng hết mức có thể để kiểm tra tình trạng Gateway.

​

Ví dụ (install-cli.sh)

Mặc định

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

Tiền tố + phiên bản tùy chỉnh

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

Cài đặt bằng Git

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

Đầu ra JSON cho tự động hóa

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

Chạy thiết lập ban đầu

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

Tham chiếu cờ

Cờ	Mô tả
--prefix <path>	Tiền tố cài đặt (mặc định: ~/.openclaw)
--install-method | --method npm|git	Chọn phương thức cài đặt (mặc định: npm)
--npm	Lối tắt cho phương thức npm
--git | --github	Lối tắt cho phương thức git
--git-dir | --dir <path>	Thư mục checkout Git (mặc định: ~/openclaw)
--version <ver>	Phiên bản hoặc dist-tag của OpenClaw (mặc định: latest)
--node-version <ver>	Phiên bản Node (mặc định: 24.15.0; 22.22.3 trên Linux ARMv7)
--json	Xuất các sự kiện NDJSON
--onboard	Chạy openclaw onboard sau khi cài đặt
--no-onboard	Bỏ qua quy trình thiết lập ban đầu (mặc định)
--set-npm-prefix	Trên Linux, buộc tiền tố npm thành ~/.npm-global nếu tiền tố hiện tại không thể ghi
--help | -h	Hiển thị cách sử dụng

Tham chiếu biến môi trường

Biến	Mô tả
OPENCLAW_PREFIX=<path>	Tiền tố cài đặt
OPENCLAW_INSTALL_METHOD=git|npm	Phương thức cài đặt
OPENCLAW_VERSION=<ver>	Phiên bản hoặc dist-tag của OpenClaw
OPENCLAW_NODE_VERSION=<ver>	Phiên bản Node
OPENCLAW_HOME=<path>	Thư mục cơ sở cho trạng thái OpenClaw và các đường dẫn git/thiết lập ban đầu mặc định
OPENCLAW_GIT_DIR=<path>	Thư mục checkout Git cho các bản cài đặt bằng git
OPENCLAW_GIT_UPDATE=0|1	Bật/tắt cập nhật git cho các checkout hiện có
OPENCLAW_NO_ONBOARD=1	Bỏ qua quy trình thiết lập ban đầu
OPENCLAW_NPM_LOGLEVEL=error|warn|notice	Mức ghi log npm (mặc định: error)

openclaw@main và các đặc tả nguồn GitHub khác không phải là đích --version hợp lệ cho bản cài đặt npm. Thay vào đó, hãy dùng --install-method git --version main.

---

​

install.ps1

​

Luồng (install.ps1)

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

   Yêu cầu PowerShell 5+.

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

   Nếu chưa có, hệ thống sẽ thử cài đặt qua winget, sau đó Chocolatey, rồi Scoop. Nếu không có trình quản lý gói nào, tập lệnh sẽ tải tệp zip Node.js 24 chính thức dành cho Windows vào %LOCALAPPDATA%\OpenClaw\deps\portable-node và thêm tệp này vào PATH của tiến trình hiện tại và người dùng. Hỗ trợ Node 22.22.3+, Node 24.15+ và Node 25.9+; không hỗ trợ Node 23.

3. Cài đặt OpenClaw

   • Phương thức npm (mặc định): cài đặt npm toàn cục bằng -Tag đã chọn, được khởi chạy từ thư mục tạm của trình cài đặt có thể ghi để các shell mở trong thư mục được bảo vệ như C:\ vẫn hoạt động
   • Phương thức git: sao chép/cập nhật kho lưu trữ, cài đặt/biên dịch bằng pnpm và cài đặt trình bao bọc tại %USERPROFILE%\.local\bin\openclaw.cmd. Nếu thiếu Git, tập lệnh sẽ thiết lập MinGit cục bộ cho người dùng trong %LOCALAPPDATA%\OpenClaw\deps\portable-git và thêm nó vào PATH của tiến trình hiện tại và người dùng.
4. Các tác vụ sau cài đặt

   • Thêm thư mục bin cần thiết vào PATH của người dùng khi có thể
   • Làm mới dịch vụ Gateway đã nạp theo cơ chế nỗ lực tối đa (openclaw gateway install --force, sau đó khởi động lại)
   • Chạy openclaw doctor --non-interactive khi nâng cấp và cài đặt bằng git (nỗ lực tối đa)
5. Xử lý lỗi

   Các bản cài đặt bằng iwr ... | iex và khối tập lệnh báo lỗi kết thúc mà không đóng phiên PowerShell hiện tại. Các bản cài đặt trực tiếp bằng powershell -File / pwsh -File vẫn thoát với mã khác 0 để phục vụ tự động hóa.

​

Ví dụ (install.ps1)

Mặc định

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

Cài đặt bằng Git

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

Checkout nhánh main trên GitHub

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

Thư mục git tùy chỉnh

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

Chạy thử

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

Tham chiếu cờ

Cờ	Mô tả
-InstallMethod npm|git	Phương thức cài đặt (mặc định: npm)
-Tag <tag|version|spec>	dist-tag, phiên bản hoặc đặc tả gói npm (mặc định: latest)
-GitDir <path>	Thư mục checkout (mặc định: %USERPROFILE%\openclaw)
-NoOnboard	Bỏ qua quy trình thiết lập ban đầu
-NoGitUpdate	Bỏ qua git pull
-DryRun	Chỉ in các hành động

Tham chiếu biến môi trường

Biến	Mô tả
OPENCLAW_INSTALL_METHOD=git|npm	Phương thức cài đặt
OPENCLAW_GIT_DIR=<path>	Thư mục checkout
OPENCLAW_NO_ONBOARD=1	Bỏ qua quy trình thiết lập ban đầu
OPENCLAW_GIT_UPDATE=0	Tắt git pull
OPENCLAW_DRY_RUN=1	Chế độ chạy thử

Nếu sử dụng -InstallMethod git và thiếu Git, tập lệnh sẽ thử thiết lập MinGit cục bộ cho người dùng trước khi in liên kết Git for Windows.

---

​

CI và tự động hóa

Sử dụng cờ/biến môi trường không tương tác để các lần chạy có thể dự đoán được.

install.sh (npm không tương tác)

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

install.sh (git không tương tác)

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

install-cli.sh (JSON)

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

install.ps1 (bỏ qua thiết lập ban đầu)

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

---

​

Khắc phục sự cố

Tại sao cần Git?

Git là bắt buộc đối với phương thức cài đặt git. Đối với các bản 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ần phụ thuộc sử dụng URL git.

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

Một số cấu hình Linux trỏ tiền tố toàn cục của npm đến các đường dẫn thuộc sở hữu của root. install.sh có thể chuyển tiền tố sang ~/.npm-global và thêm các lệnh xuất PATH vào tệp rc của shell (khi các tệp đó tồn tại).

Windows: "npm error spawn git / ENOENT"

Chạy lại trình cài đặt để nó có thể thiết lập MinGit cục bộ cho người dùng, hoặc cài đặt Git for Windows rồi mở lại PowerShell.

Windows: "openclaw is not recognized"

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

Windows: cách lấy đầu ra chi tiết của trình cài đặt

install.ps1 không cung cấp tùy chọn -Verbose. Sử dụng tính năng theo dõi PowerShell để chẩn đoán ở cấp tập lệnh:

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

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

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

​

Liên quan

• Tổng quan về cài đặt
• Cập nhật
• Gỡ cài đặt