Hướng dẫn cài đặt OpenClaw trên Windows, macOS và Linux

OpenClaw là nền tảng self-hosted giúp bạn biến AI agent thành trợ lý cá nhân có thể chạy 24/7, kết nối với Telegram, WhatsApp, Discord, Slack, Signal, Zalo và nhiều kênh khác. Bài viết này hướng dẫn cách cài đặt OpenClaw trên Windows, macOS và Linux theo cách dễ hiểu nhất cho người mới.

OpenClaw là gì?

OpenClaw là một gateway mã nguồn mở dùng để kết nối các mô hình AI với những kênh giao tiếp quen thuộc như Telegram, WhatsApp, Discord, Slack, Microsoft Teams, Signal, Matrix, iMessage, Zalo và nhiều nền tảng khác.

Thay vì chỉ dùng AI trong một giao diện chat cố định, OpenClaw cho phép bạn triển khai một AI assistant riêng, có bộ nhớ, có workspace, có thể chạy công cụ, đọc ghi file, xử lý tác vụ định kỳ và phản hồi qua các kênh nhắn tin mà bạn đã cấu hình.

Một hệ thống OpenClaw cơ bản thường gồm:

• OpenClaw CLI: công cụ dòng lệnh để cài đặt, cấu hình và quản lý hệ thống.
• Gateway: dịch vụ trung tâm nhận tin nhắn, điều phối agent và kết nối các kênh.
• Control UI / Dashboard: giao diện web để kiểm tra trạng thái, cấu hình và chat thử.
• Workspace: nơi lưu hướng dẫn vận hành, bộ nhớ, file làm việc và cấu hình hành vi của agent.
• Model provider: nhà cung cấp mô hình AI như OpenAI, Anthropic, Google hoặc provider tương thích khác.

Yêu cầu trước khi cài đặt

Trước khi cài OpenClaw, bạn nên chuẩn bị:

• Máy tính chạy Windows, macOS hoặc Linux.
• Node.js 24 là khuyến nghị. OpenClaw vẫn hỗ trợ Node 22.16+.
• Một API key từ nhà cung cấp mô hình AI, ví dụ OpenAI, Anthropic hoặc Google.
• Terminal/PowerShell có quyền chạy lệnh cài đặt.
• Kết nối Internet ổn định.

Nếu cài bằng script chính thức, OpenClaw có thể tự xử lý phần Node.js trong nhiều trường hợp. Tuy nhiên, bạn vẫn nên kiểm tra trước bằng lệnh:

node --version

Nếu máy chưa có Node.js hoặc phiên bản quá cũ, hãy cài Node.js bản LTS hoặc Node 24 trước khi tiếp tục.

Cài đặt nhanh OpenClaw

OpenClaw cung cấp script cài đặt tự động cho từng hệ điều hành. Đây là cách phù hợp nhất cho đa số người dùng.

Cài OpenClaw trên macOS hoặc Linux

Mở Terminal và chạy:

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

Script này sẽ kiểm tra môi trường, cài OpenClaw CLI, chuẩn bị các thành phần cần thiết và đưa bạn vào luồng onboarding.

Nếu bạn chỉ muốn cài CLI mà chưa chạy onboarding ngay, dùng:

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

Cài OpenClaw trên Windows bằng PowerShell

Mở PowerShell và chạy:

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

Nếu muốn cài nhưng bỏ qua onboarding ban đầu:

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

Nên cài OpenClaw trên Windows native hay WSL2?

OpenClaw hỗ trợ cả Windows native và WSL2, nhưng WSL2 là lựa chọn ổn định hơn nếu bạn muốn dùng đầy đủ Gateway, CLI và các công cụ kỹ thuật.

Bạn có thể chọn theo nhu cầu:

• Windows native: phù hợp nếu bạn chỉ muốn chạy CLI/Gateway cơ bản, kiểm tra nhanh hoặc dùng thử.
• WSL2: phù hợp nếu bạn muốn môi trường Linux ổn định, dễ chạy service, dễ debug và gần với môi trường production hơn.

Với người dùng nghiêm túc, đặc biệt nếu muốn chạy OpenClaw lâu dài, nên dùng WSL2.

Cài OpenClaw trên Windows qua WSL2

Bước 1: Cài WSL2 và Ubuntu

Mở PowerShell với quyền Administrator:

wsl --install

Hoặc chọn bản Ubuntu cụ thể:

wsl --list --online
wsl --install -d Ubuntu-24.04

Sau khi cài xong, khởi động lại máy nếu Windows yêu cầu.

Bước 2: Bật systemd trong WSL2

Trong terminal Ubuntu của WSL, chạy:

sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF

Sau đó quay lại PowerShell và tắt WSL:

wsl --shutdown

Mở lại Ubuntu và kiểm tra:

systemctl --user status

Bước 3: Cài OpenClaw trong WSL2

Trong Ubuntu/WSL, chạy:

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

Sau khi cài, chạy onboarding:

openclaw onboard --install-daemon

Lệnh này sẽ hướng dẫn bạn cấu hình model provider, API key, Gateway và service chạy nền.

Cài OpenClaw trên macOS

Trên macOS, bạn có hai hướng phổ biến:

Cài bằng script CLI.

Dùng OpenClaw macOS companion app nếu bạn muốn tích hợp sâu với hệ điều hành.

Cài bằng Terminal

Chạy:

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

Sau đó chạy onboarding nếu script chưa tự mở:

openclaw onboard --install-daemon

Gateway trên macOS có thể được quản lý qua LaunchAgent. Khi cài daemon, OpenClaw có thể tự cấu hình để Gateway chạy nền.

Kiểm tra Gateway trên macOS

openclaw gateway status

Nếu Gateway hoạt động đúng, bạn sẽ thấy dịch vụ đang lắng nghe ở cổng mặc định `18789`.

Mở dashboard:

openclaw dashboard

Nếu dùng macOS companion app, app có thể giúp quản lý Gateway, quyền hệ thống, thông báo, screen recording, automation và các quyền TCC khác.

Cài OpenClaw trên Linux

Linux là môi trường rất phù hợp để chạy OpenClaw lâu dài, đặc biệt trên VPS hoặc máy chủ cá nhân.

Cài nhanh bằng script

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

Sau đó chạy:

openclaw onboard --install-daemon

Trên Linux, OpenClaw thường dùng systemd user service để chạy Gateway nền.

Kiểm tra service

openclaw gateway status

Hoặc kiểm tra bằng systemd:

systemctl --user status openclaw-gateway.service --no-pager

Nếu muốn Gateway tiếp tục chạy sau khi logout khỏi server, bật lingering:

sudo loginctl enable-linger $USER

Đây là bước quan trọng nếu bạn chạy OpenClaw trên VPS và muốn assistant hoạt động 24/7.

Onboarding OpenClaw sau khi cài đặt

Sau khi cài CLI, bước quan trọng nhất là onboarding:

openclaw onboard --install-daemon

Quá trình này thường yêu cầu bạn chọn hoặc cấu hình:

• Nhà cung cấp model AI.
• API key.
• Agent mặc định.
• Gateway chạy nền hay chạy thủ công.
• Dashboard/Control UI.
• Một số thiết lập bảo mật cơ bản.

Sau khi onboarding xong, kiểm tra lại:

openclaw --version
openclaw doctor
openclaw gateway status

Nếu không có lỗi nghiêm trọng, mở dashboard:

openclaw dashboard

Cấu trúc thư mục quan trọng của OpenClaw

Mặc định, OpenClaw lưu dữ liệu trong thư mục:

~/.openclaw

Một số vị trí quan trọng:

~/.openclaw/openclaw.json

File cấu hình chính của OpenClaw.

~/.openclaw/workspace

Workspace của agent, nơi chứa hướng dẫn vận hành, memory và file làm việc.

~/.openclaw/credentials

Nơi lưu thông tin xác thực cho các kênh như WhatsApp, Telegram hoặc các tích hợp khác.

~/.openclaw/agents/<agentId>/sessions

Nơi lưu session chat và metadata của agent.

Bạn nên sao lưu thư mục `~/.openclaw/workspace`, đặc biệt nếu đã tùy biến persona, memory hoặc quy trình làm việc của assistant.

Kết nối OpenClaw với Telegram hoặc WhatsApp

Sau khi Gateway hoạt động, bạn có thể kết nối OpenClaw với các kênh nhắn tin.

Với Telegram, bạn thường cần bot token từ BotFather và cấu hình token trong OpenClaw.

Với WhatsApp, nên dùng một số điện thoại riêng cho assistant thay vì liên kết trực tiếp WhatsApp cá nhân. Cách này giúp tránh việc mọi tin nhắn cá nhân đều bị xem là input cho agent.

Về bảo mật, hãy luôn cấu hình danh sách người được phép nhắn cho assistant, ví dụ `allowFrom`, để tránh mở agent cho người lạ.

Các lệnh OpenClaw cơ bản nên biết

Kiểm tra phiên bản:

openclaw --version

Kiểm tra lỗi cấu hình:

openclaw doctor

Kiểm tra Gateway:

openclaw gateway status

Khởi động Gateway thủ công:

openclaw gateway --port 18789

Cài Gateway chạy nền:

openclaw gateway install

Mở dashboard:

openclaw dashboard

Cài OpenClaw bằng npm, pnpm hoặc bun

Nếu bạn đã quản lý Node.js thủ công, có thể cài OpenClaw bằng npm:

npm install -g openclaw@latest
openclaw onboard --install-daemon

Với pnpm:

pnpm add -g openclaw@latest
pnpm approve-builds -g
openclaw onboard --install-daemon

Với bun:

bun add -g openclaw@latest
openclaw onboard --install-daemon

Tuy nhiên, với Gateway chạy lâu dài, Node.js vẫn là runtime được khuyến nghị.

Cài OpenClaw từ source code

Nếu bạn là developer hoặc muốn chạy bản mới nhất từ mã nguồn:

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
pnpm ui:build
pnpm link --global
openclaw onboard --install-daemon

Khi phát triển Gateway, có thể dùng:

pnpm gateway:watch

Cách này phù hợp cho contributor hoặc người muốn tùy biến sâu, không phải lựa chọn tối ưu cho người dùng phổ thông.

Lỗi thường gặp khi cài OpenClaw

Lỗi `openclaw: command not found`

Nguyên nhân thường là global npm bin chưa nằm trong `PATH`.

Kiểm tra:

node -v
npm prefix -g
echo $PATH

Nếu thư mục global bin chưa có trong PATH, thêm vào `~/.zshrc` hoặc `~/.bashrc`:

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

Sau đó mở terminal mới và chạy lại:

openclaw --version

Gateway không chạy

Chạy:

openclaw doctor
openclaw gateway status

Nếu đang dùng Linux/WSL2, kiểm tra systemd user service:

systemctl --user status openclaw-gateway.service --no-pager

Nếu service không tự chạy sau khi logout, bật lingering:

sudo loginctl enable-linger $USER

Windows Scheduled Task bị chặn

Trên Windows native, OpenClaw ưu tiên tạo Scheduled Task để chạy Gateway. Nếu quyền hệ thống hoặc policy chặn thao tác này, OpenClaw có thể fallback sang Startup folder của user.

Nếu muốn đơn giản hơn, hãy dùng WSL2 và cài OpenClaw như môi trường Linux.

Dashboard không mở được

Kiểm tra Gateway trước:

openclaw gateway status

Gateway mặc định dùng cổng `18789`.

Nếu chạy trên server Linux/VPS và muốn mở dashboard từ máy cá nhân, có thể tạo SSH tunnel:

ssh -N -L 18789:127.0.0.1:18789 user@server

Sau đó mở trên máy cá nhân:

http://127.0.0.1:18789/

Gợi ý cấu hình bảo mật ban đầu

OpenClaw có thể kết nối với kênh nhắn tin, đọc/ghi file và chạy công cụ tùy cấu hình. Vì vậy, không nên bỏ qua phần bảo mật.

Một số nguyên tắc nên áp dụng:

• Không mở Gateway trực tiếp ra Internet nếu chưa hiểu rõ cơ chế auth.
• Luôn giới hạn người được phép nhắn assistant qua `allowFrom` hoặc cơ chế pairing.
• Dùng số WhatsApp riêng cho assistant nếu triển khai WhatsApp.
• Không lưu API key trong file public hoặc repository công khai.
• Bật heartbeat/proactive mode sau khi đã kiểm tra kỹ hành vi của agent.
• Với server/VPS, ưu tiên truy cập dashboard qua SSH tunnel hoặc VPN riêng.

Quy trình cài đặt đề xuất cho người mới

Nếu bạn mới bắt đầu, đây là quy trình gọn nhất:

Cài Node.js 24 hoặc dùng installer script để tự xử lý.

Cài OpenClaw bằng script chính thức.

Chạy onboarding:

openclaw onboard --install-daemon

Kiểm tra hệ thống:

openclaw doctor
openclaw gateway status

Mở dashboard:

openclaw dashboard

Gửi thử một tin nhắn trong Control UI.

Sau khi ổn định, mới kết nối Telegram, WhatsApp hoặc các kênh khác.

Kết luận

OpenClaw là lựa chọn mạnh nếu bạn muốn tự triển khai một AI assistant riêng, có thể chạy liên tục, kết nối nhiều kênh nhắn tin và tùy biến sâu theo workflow cá nhân hoặc doanh nghiệp.

Với người dùng phổ thông, cách nhanh nhất là dùng script cài đặt chính thức và chạy `openclaw onboard –install-daemon`. Với Windows, WSL2 là lựa chọn ổn định hơn native Windows. Với Linux hoặc VPS, cần chú ý systemd user service và bật lingering nếu muốn Gateway chạy 24/7. Với macOS, bạn có thể dùng CLI hoặc companion app để quản lý Gateway và quyền hệ thống thuận tiện hơn.

Sau khi cài xong, hãy kiểm tra bằng `openclaw doctor`, mở dashboard bằng `openclaw dashboard`, rồi từng bước kết nối các kênh như Telegram hoặc WhatsApp theo nhu cầu.

Cập nhật thêm: nếu bạn muốn theo dõi phiên bản mới, xem bài tổng hợp OpenClaw 2026.5.18 có gì mới để nắm các thay đổi về Gateway, plugin, mobile và QA.

Series hướng dẫn OpenClaw

Đây là bài 2/10 trong series Hướng dẫn OpenClaw từ A-Z trên ThanhTuan.VN.

• Bài trước: OpenClaw là gì? Trợ lý AI mã nguồn mở cho người dùng Việt
• Mục lục series: Hướng dẫn OpenClaw từ A-Z
• Bài tiếp theo: API key, model và chi phí OpenClaw: chọn sao cho hợp lý?