Cài đặt qua Ansible

Cách được khuyên dùng để deploy OpenClaw lên production server là qua openclaw-ansible — một trình cài đặt tự động với kiến trúc bảo mật ưu tiên.

Bắt đầu nhanh

Cài đặt bằng một lệnh:

curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw-ansible/main/install.sh | bash

📦 Hướng dẫn đầy đủ: github.com/openclaw/openclaw-ansible

Repo openclaw-ansible là nguồn chính thức cho việc deploy qua Ansible. Trang này chỉ là tổng quan nhanh.

Những gì các bạn nhận được

  • 🔒 Bảo mật firewall ưu tiên: UFW + cách ly Docker (chỉ SSH + Tailscale có thể truy cập)
  • 🔐 Tailscale VPN: Truy cập từ xa an toàn mà không cần expose service ra public
  • 🐳 Docker: Container sandbox cách ly, chỉ bind localhost
  • 🛡️ Defense in depth: Kiến trúc bảo mật 4 lớp
  • 🚀 Setup một lệnh: Deploy hoàn chỉnh trong vài phút
  • 🔧 Tích hợp Systemd: Tự động khởi động khi boot với hardening

Yêu cầu

  • OS: Debian 11+ hoặc Ubuntu 20.04+
  • Access: Quyền root hoặc sudo
  • Network: Kết nối Internet để cài đặt package
  • Ansible: 2.14+ (được cài tự động bởi script quick-start)

Những gì được cài đặt

Ansible playbook sẽ cài đặt và cấu hình:

  1. Tailscale (mesh VPN cho truy cập từ xa an toàn)
  2. UFW firewall (chỉ mở port SSH + Tailscale)
  3. Docker CE + Compose V2 (cho agent sandbox)
  4. Node.js 22.x + pnpm (runtime dependencies)
  5. OpenClaw (chạy trực tiếp trên host, không containerized)
  6. Systemd service (tự động khởi động với security hardening)

Lưu ý: Gateway chạy trực tiếp trên host (không trong Docker), nhưng agent sandbox sử dụng Docker để cách ly. Xem Sandboxing để biết chi tiết.

Thiết lập sau khi cài đặt

Sau khi cài đặt xong, chuyển sang user openclaw:

sudo -i -u openclaw

Script post-install sẽ hướng dẫn các bạn qua:

  1. Onboarding wizard: Cấu hình các thiết lập OpenClaw
  2. Provider login: Kết nối WhatsApp/Telegram/Discord/Signal
  3. Gateway testing: Xác minh cài đặt
  4. Tailscale setup: Kết nối vào VPN mesh của bạn

Các lệnh nhanh

# Kiểm tra trạng thái service
sudo systemctl status openclaw

# Xem log trực tiếp
sudo journalctl -u openclaw -f

# Khởi động lại gateway
sudo systemctl restart openclaw

# Provider login (chạy với user openclaw)
sudo -i -u openclaw
openclaw channels login

Kiến trúc bảo mật

Phòng thủ 4 lớp

  1. Firewall (UFW): Chỉ SSH (22) + Tailscale (41641/udp) được expose ra public
  2. VPN (Tailscale): Gateway chỉ có thể truy cập qua VPN mesh
  3. Docker Isolation: DOCKER-USER iptables chain ngăn chặn expose port ra ngoài
  4. Systemd Hardening: NoNewPrivileges, PrivateTmp, unprivileged user

Xác minh

Test bề mặt tấn công từ bên ngoài:

nmap -p- YOUR_SERVER_IP

Kết quả chỉ nên hiển thị port 22 (SSH) mở. Tất cả các service khác (gateway, Docker) đều bị khóa.

Docker Availability

Docker được cài đặt cho agent sandbox (thực thi tool cách ly), không phải để chạy gateway. Gateway chỉ bind localhost và có thể truy cập qua Tailscale VPN.

Xem Multi-Agent Sandbox & Tools để biết cấu hình sandbox.

Cài đặt thủ công

Nếu các bạn muốn kiểm soát thủ công thay vì tự động:

# 1. Cài đặt prerequisites
sudo apt update && sudo apt install -y ansible git

# 2. Clone repository
git clone https://github.com/openclaw/openclaw-ansible.git
cd openclaw-ansible

# 3. Cài đặt Ansible collections
ansible-galaxy collection install -r requirements.yml

# 4. Chạy playbook
./run-playbook.sh

# Hoặc chạy trực tiếp (sau đó thực thi /tmp/openclaw-setup.sh thủ công)
# ansible-playbook playbook.yml --ask-become-pass

Cập nhật OpenClaw

Ansible installer thiết lập OpenClaw để cập nhật thủ công. Xem Updating để biết quy trình cập nhật chuẩn.

Để chạy lại Ansible playbook (ví dụ: cho thay đổi cấu hình):

cd openclaw-ansible
./run-playbook.sh

Lưu ý: Lệnh này là idempotent và an toàn để chạy nhiều lần.

Troubleshooting

Firewall chặn kết nối của tôi

Nếu bị khóa không vào được:

  • Đảm bảo các bạn có thể truy cập qua Tailscale VPN trước
  • SSH access (port 22) luôn được cho phép
  • Gateway chỉ có thể truy cập qua Tailscale theo thiết kế

Service không khởi động

# Kiểm tra log
sudo journalctl -u openclaw -n 100

# Xác minh quyền
sudo ls -la /opt/openclaw

# Test khởi động thủ công
sudo -i -u openclaw
cd ~/openclaw
pnpm start

Vấn đề với Docker sandbox

# Xác minh Docker đang chạy
sudo systemctl status docker

# Kiểm tra sandbox image
sudo docker images | grep openclaw-sandbox

# Build sandbox image nếu thiếu
cd /opt/openclaw/openclaw
sudo -u openclaw ./scripts/sandbox-setup.sh

Provider login thất bại

Đảm bảo các bạn đang chạy với user openclaw:

sudo -i -u openclaw
openclaw channels login

Cấu hình nâng cao

Để biết chi tiết về kiến trúc bảo mật và troubleshooting:

Liên quan