Hướng dẫn Cài Đặt OpenClaw bằng npm

Bài hướng dẫn dựa trên OpenClaw phiên bản mới nhất theo README chính thức — cập nhật tháng 3/2026. OpenClaw đang phát triển nhanh, quy trình cài đặt có thể thay đổi theo version. Hãy kiểm tra repository chính thức nếu bạn đọc bài này sau 3–6 tháng.

Nếu bạn đã thử tìm file install.sh để chạy như các bài hướng dẫn khác ghi — file đó không tồn tại. OpenClaw cài qua npm, không phải qua Docker hay bash script. Đây là điểm hay gây nhầm nhất, vì nhiều AI agent tool khác dùng Docker làm phương thức cài chính. Bài này đi đúng theo README: Node.js → npm → onboard wizard → bảo mật Gateway. Đủ để vận hành thật, không chỉ thử chơi được một buổi.

Cấu hình tối thiểu để chạy OpenClaw mượt

Tối thiểu cần 2 vCPU, 2GB RAM và 20GB ổ NVMe SSD, chạy Ubuntu 22.04 hoặc 24.04 LTS. Đó là ngưỡng để OpenClaw khởi động và xử lý request từ 1–2 channel đơn giản — không phải ngưỡng thoải mái cho production thật.

OpenClaw là Gateway điều phối — bản thân nó không chạy AI model cục bộ, mà gọi ra API provider bên ngoài (OpenAI, Anthropic…). RAM không bị ngốn bởi model inference như các self-hosted LLM. 2GB RAM đủ chạy Gateway + Node.js runtime + một vài channel đồng thời. Tuy nhiên nếu bạn bật nhiều channel cùng lúc (Telegram + Discord + WhatsApp) hoặc có nhiều session song song, 4GB RAM sẽ dễ thở hơn đáng kể.

Ubuntu 22.04 hay 24.04 — nên dùng phiên bản nào?

Cả hai đều chạy được. Ubuntu 22.04 LTS ổn định hơn cho production — package Node.js từ NodeSource tương thích tốt, ít biến số hơn. Ubuntu 24.04 dùng được nhưng cần chú ý: một số gói hệ thống đã thay đổi tên hoặc version, đôi khi gây conflict khi cài Node.js nếu không dùng đúng script setup từ NodeSource. Nếu đây là lần đầu triển khai OpenClaw, chọn 22.04 để đỡ debug.

Chuẩn bị trước khi cài OpenClaw

Bốn điều kiện cần xác nhận trước khi bắt đầu:

• VPS đang chạy Ubuntu 22.04 hoặc 24.04, SSH vào được bằng user có quyền sudo
• Kết nối internet ổn định — npm cần tải package, tổng khoảng 100–300MB
• Đã có API Key từ ít nhất 1 AI provider: OpenAI (sk-...) hoặc Anthropic (sk-ant-...)
• Nếu muốn kết nối Telegram: đã tạo bot qua @BotFather và có botToken

Sau khi SSH vào, update hệ thống trước:

sudo apt update && sudo apt upgrade -y

Không bỏ bước này. Một số package hệ thống cũ có thể conflict với Node.js 22+ khi cài — update trước sẽ tránh được phần lớn lỗi kiểu này. Mất 2–5 phút, đáng hơn là debug sau.

Từng bước cài đặt OpenClaw trên VPS Ubuntu

Toàn bộ quy trình gồm 4 bước. Mỗi bước có lệnh cụ thể và output kỳ vọng để tự xác nhận đúng/sai ngay tại chỗ.

Bước 1 — Cài Node.js 22 hoặc 24 trên Ubuntu

OpenClaw yêu cầu Node.js 24 (khuyến nghị) hoặc tối thiểu Node.js 22.16+. Phiên bản Node có sẵn trong apt của Ubuntu thường quá cũ — phải dùng script setup từ NodeSource:

# Node.js 22 LTS (ổn định hơn cho production)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -
sudo apt install -y nodejs

Hoặc Node.js 24 nếu muốn dùng version mới nhất theo khuyến nghị của OpenClaw:

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo bash -
sudo apt install -y nodejs

Kiểm tra sau khi cài:

node --version
npm --version

Bước 2 — Cài OpenClaw qua npm

Đây là lệnh cài chính thức theo README:

npm install -g openclaw@latest

npm sẽ tải OpenClaw và toàn bộ dependencies. Quá trình mất 1–3 phút tùy tốc độ mạng. Sau khi xong, xác nhận:

openclaw --version

Nếu terminal báo command not found, có thể npm global bin chưa nằm trong PATH. Thêm bằng lệnh:

export PATH="$(npm bin -g):$PATH"
echo 'export PATH="$(npm bin -g):$PATH"' >> ~/.bashrc
source ~/.bashrc

Bước 3 — Chạy Onboard Wizard và cài Gateway daemon

Đây là bước cốt lõi — openclaw onboard sẽ dẫn qua toàn bộ cấu hình và cài Gateway daemon (systemd service) để Gateway tự khởi động khi VPS reboot:

openclaw onboard --install-daemon

Wizard sẽ hỏi tuần tự:

• AI model và provider — chọn provider (OpenAI, Anthropic…) và nhập API Key tương ứng
• Channel muốn kết nối — Telegram, Discord, WhatsApp, Slack… Có thể cấu hình nhiều channel cùng lúc hoặc thêm sau
• Telegram Bot Token (nếu chọn Telegram) — lấy từ @BotFather, format 123456:ABCDEF...
• Cài daemon — wizard tự cài systemd user service, Gateway sẽ chạy nền và tự restart nếu crash

Sau khi wizard hoàn tất, đợi 2-3 phút và kiểm tra trạng thái để xác nhận daemon đang active:

systemctl --user status openclaw

Trạng thái phải là active (running). Nếu inactive hoặc failed, xem log để biết lỗi cụ thể:

journalctl --user -u openclaw -n 50

Bước 4 — Truy cập Control UI và kiểm tra kết nối

OpenClaw Gateway phục vụ Control UI trực tiếp qua port 18789 — không cần cài thêm web server. Mặc định Gateway bind vào 127.0.0.1 (localhost), không expose ra internet. Để truy cập từ máy tính cá nhân, dùng SSH Tunnel:

ssh -L 18789:localhost:18789 user@[IP-VPS] -N

Chạy lệnh này trên máy tính của bạn (không phải trên VPS), rồi mở trình duyệt vào http://localhost:18789. Control UI hiện ra là Gateway đang chạy đúng.

Chạy thêm lệnh này để kiểm tra toàn bộ cấu hình:

openclaw doctor

openclaw doctor phát hiện API Key sai, channel chưa kết nối, hoặc DM policy rủi ro. Nên chạy sau mỗi lần thay đổi config.

Lỗi thường gặp khi cài OpenClaw và cách xử lý

Với hầu hết lỗi khởi động, journalctl --user -u openclaw -n 50 sẽ chỉ rõ dòng lỗi thật sự — đọc từ dưới lên, dòng cuối trước khi process exit là nguyên nhân chính. Tham khảo thêm bài cấu hình tường lửa VPS nếu bạn nghi ngờ vấn đề nằm ở tầng network.

Bảo mật OpenClaw Gateway sau khi cài

Gateway OpenClaw mặc định bind vào 127.0.0.1 — chỉ truy cập được từ chính VPS đó. Đây là hành vi mặc định an toàn. Vấn đề xảy ra khi bạn đổi bind sang 0.0.0.0 để truy cập từ xa mà không có lớp bảo vệ nào — lúc đó Gateway và toàn bộ API Key bên trong đều public ra internet.

Có 2 phương án truy cập từ xa an toàn, không cần mở port thêm:

Phương án 1 — SSH Tunnel (không cài thêm gì)

Chạy lệnh này trên máy tính cá nhân mỗi khi cần truy cập Control UI:

ssh -L 18789:localhost:18789 user@[IP-VPS] -N

Mở trình duyệt vào http://localhost:18789. Session SSH tắt là Control UI không còn truy cập được từ bên ngoài. Phù hợp nếu chỉ cần vào Dashboard thỉnh thoảng để xem log hoặc thay đổi cấu hình.

Phương án 2 — Tailscale Serve (khuyến nghị)

OpenClaw tích hợp sẵn với Tailscale: cấu hình gateway.tailscale.mode: "serve" để Gateway tự expose qua Tailscale HTTPS — chỉ truy cập được từ thiết bị trong cùng tailnet, không cần mở port public.

Cài Tailscale trên VPS trước:

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

Sau đó thêm cấu hình vào ~/.openclaw/openclaw.json:

{
  "gateway": {
    "tailscale": {
      "mode": "serve"
    }
  }
}

Restart daemon để áp dụng:

systemctl --user restart openclaw

Gateway sẽ tự cấu hình Tailscale Serve và bạn truy cập Control UI qua URL Tailscale HTTPS của VPS — không cần giữ SSH session. Tiện hơn hẳn so với SSH Tunnel nếu bạn dùng OpenClaw hàng ngày hoặc từ nhiều thiết bị khác nhau.

Đọc thêm về các lớp bảo mật nên có trên VPS tại bài bảo mật VPS Linux toàn diện.

Câu hỏi thường gặp khi cài OpenClaw trên VPS Ubuntu

VPS Windows có cài được OpenClaw không?

Không trực tiếp — nhưng theo README chính thức, Windows được hỗ trợ qua WSL2 (Windows Subsystem for Linux). Trên VPS cloud, WSL2 thường không enable được do kernel restrictions. Cách đơn giản và ổn định nhất vẫn là dùng VPS Ubuntu riêng — ít biến số hơn nhiều.

Cài OpenClaw có cần kiến thức Linux sâu không?

Không cần sâu. Biết SSH vào VPS, chạy lệnh npm, và đọc output terminal là đủ cho toàn bộ quy trình. Onboarding wizard của OpenClaw hỏi từng thứ một — không cần tự viết config file từ đầu. Nếu bạn đang dùng VPS InterData và gặp khó ở bước nào, đội hỗ trợ kỹ thuật có thể hỗ trợ trực tiếp.

Sau khi cài xong, muốn thêm hoặc đổi API Key thì làm thế nào?

Chỉnh trực tiếp trong file ~/.openclaw/openclaw.json — thêm hoặc sửa block "agent" với model và provider muốn dùng. API Key nên đặt vào biến môi trường (OPENAI_API_KEY hoặc ANTHROPIC_API_KEY) trong ~/.bashrc thay vì ghi thẳng vào config file. Sau khi sửa, restart daemon: systemctl --user restart openclaw, rồi chạy openclaw doctor để xác nhận config mới hợp lệ.

OpenClaw có cập nhật tự động không?

Không tự động — nhưng update rất đơn giản: chạy lại npm install -g openclaw@latest hoặc dùng lệnh tích hợp openclaw update --channel stable. OpenClaw có 3 channel: stable (tagged release), beta (prerelease), và dev (HEAD của main branch). Cho môi trường production, luôn dùng stable.

OpenClaw hỗ trợ những channel nhắn tin nào ngoài Telegram?

Danh sách khá dài: WhatsApp, Discord, Slack, Google Chat, Signal, iMessage (qua BlueBubbles), IRC, Microsoft Teams, Matrix, LINE, Mattermost, Zalo, WeChat, và WebChat tích hợp sẵn trong Control UI. Mỗi channel có hướng dẫn cấu hình riêng tại docs.openclaw.ai/channels. Telegram và Discord là hai channel dễ cấu hình nhất cho người mới.

Kết luận

Quy trình cài đặt OpenClaw trên VPS Ubuntu thực ra gọn hơn nhiều bài mô tả: Node.js → npm install → onboard wizard → bảo mật Gateway. Không có Docker, không có bash script phức tạp. Bước hay bị bỏ qua nhất là bảo mật — Gateway mặc định an toàn vì bind vào localhost, nhưng nếu bạn tự mở port ra internet để tiện truy cập thì API Key AI provider đi kèm. Tailscale Serve giải quyết gọn vấn đề này mà không cần mở terminal giữ SSH session mỗi ngày.

Sau khi Gateway đang chạy ổn định, bước tiếp theo là khai thác các tính năng của OpenClaw — từ multi-channel routing, voice wake, đến Canvas. Đọc thêm tổng quan về tính năng và use case của OpenClaw để biết nên cấu hình thêm gì cho phù hợp với workflow của bạn.