OpenClaw trên Hetzner (Docker, Hướng dẫn Production VPS)

Mục tiêu

Chạy OpenClaw Gateway bền vững trên Hetzner VPS bằng Docker, với dữ liệu lưu trữ lâu dài, binaries được tích hợp sẵn, và cơ chế khởi động lại an toàn.

Nếu các bạn muốn “OpenClaw 24/7 với ~$5”, đây là cách setup đơn giản và ổn định nhất. Giá Hetzner có thể thay đổi; chọn VPS Debian/Ubuntu nhỏ nhất và scale up nếu gặp lỗi OOM.

Mình sẽ làm gì (giải thích đơn giản)?

• Thuê một Linux server nhỏ (Hetzner VPS)
• Cài Docker (môi trường chạy app độc lập)
• Khởi động OpenClaw Gateway trong Docker
• Lưu trữ ~/.openclaw + ~/.openclaw/workspace trên host (tồn tại qua các lần restart/rebuild)
• Truy cập Control UI từ laptop qua SSH tunnel

Gateway có thể được truy cập qua:

• SSH port forwarding từ laptop của các bạn
• Expose port trực tiếp nếu các bạn tự quản lý firewall và tokens

Hướng dẫn này giả định các bạn dùng Ubuntu hoặc Debian trên Hetzner. Nếu dùng Linux VPS khác, hãy điều chỉnh packages cho phù hợp. Để xem hướng dẫn Docker tổng quát, xem Docker.

Các bước nhanh (dành cho người có kinh nghiệm)

1. Provision Hetzner VPS
2. Cài Docker
3. Clone OpenClaw repository
4. Tạo thư mục persistent trên host
5. Cấu hình .env và docker-compose.yml
6. Tích hợp binaries cần thiết vào image
7. docker compose up -d
8. Kiểm tra persistence và truy cập Gateway

Các bạn cần gì

• Hetzner VPS với quyền root
• SSH access từ laptop
• Biết cơ bản về SSH + copy/paste
• ~20 phút
• Docker và Docker Compose
• Thông tin xác thực model
• Thông tin xác thực provider (tùy chọn)
  • WhatsApp QR
  • Telegram bot token
  • Gmail OAuth

1) Provision VPS

Tạo một Ubuntu hoặc Debian VPS trong Hetzner.

Kết nối với quyền root:

ssh root@YOUR_VPS_IP

Hướng dẫn này giả định VPS là stateful. Đừng coi nó như disposable infrastructure.

2) Cài Docker (trên VPS)

apt-get update
apt-get install -y git curl ca-certificates
curl -fsSL https://get.docker.com | sh

Kiểm tra:

docker --version
docker compose version

3) Clone OpenClaw repository

git clone https://github.com/openclaw/openclaw.git
cd openclaw

Hướng dẫn này giả định các bạn sẽ build custom image để đảm bảo binary persistence.

4) Tạo thư mục persistent trên host

Docker containers là ephemeral. Tất cả dữ liệu lâu dài phải được lưu trên host.

mkdir -p /root/.openclaw
mkdir -p /root/.openclaw/workspace

# Set ownership cho container user (uid 1000):
chown -R 1000:1000 /root/.openclaw
chown -R 1000:1000 /root/.openclaw/workspace

5) Cấu hình environment variables

Tạo file .env trong thư mục gốc của repository.

OPENCLAW_IMAGE=openclaw:latest
OPENCLAW_GATEWAY_TOKEN=change-me-now
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_PORT=18789

OPENCLAW_CONFIG_DIR=/root/.openclaw
OPENCLAW_WORKSPACE_DIR=/root/.openclaw/workspace

GOG_KEYRING_PASSWORD=change-me-now
XDG_CONFIG_HOME=/home/node/.openclaw

Tạo secrets mạnh:

openssl rand -hex 32

Đừng commit file này.

6) Cấu hình Docker Compose

Tạo hoặc cập nhật docker-compose.yml.

services:
  openclaw-gateway:
    image: ${OPENCLAW_IMAGE}
    build: .
    restart: unless-stopped
    env_file:
      - .env
    environment:
      - HOME=/home/node
      - NODE_ENV=production
      - TERM=xterm-256color
      - OPENCLAW_GATEWAY_BIND=${OPENCLAW_GATEWAY_BIND}
      - OPENCLAW_GATEWAY_PORT=${OPENCLAW_GATEWAY_PORT}
      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
      - GOG_KEYRING_PASSWORD=${GOG_KEYRING_PASSWORD}
      - XDG_CONFIG_HOME=${XDG_CONFIG_HOME}
      - PATH=/home/linuxbrew/.linuxbrew/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
    volumes:
      - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
      - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
    ports:
      # Khuyến nghị: giữ Gateway chỉ ở loopback trên VPS; truy cập qua SSH tunnel.
      # Để expose công khai, xóa prefix `127.0.0.1:` và cấu hình firewall phù hợp.
      - "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789"

      # Tùy chọn: chỉ khi các bạn chạy iOS/Android nodes với VPS này và cần Canvas host.
      # Nếu expose công khai, đọc /gateway/security và cấu hình firewall phù hợp.
      # - "18793:18793"
    command:
      [
        "node",
        "dist/index.js",
        "gateway",
        "--bind",
        "${OPENCLAW_GATEWAY_BIND}",
        "--port",
        "${OPENCLAW_GATEWAY_PORT}",
      ]

7) Tích hợp binaries cần thiết vào image (quan trọng)

Cài binaries bên trong container đang chạy là một cái bẫy. Bất cứ thứ gì được cài lúc runtime sẽ mất khi restart.

Tất cả binaries bên ngoài mà skills cần phải được cài lúc build image.

Các ví dụ dưới đây chỉ hiển thị ba binaries phổ biến:

• gog cho Gmail access
• goplaces cho Google Places
• wacli cho WhatsApp

Đây chỉ là ví dụ, không phải danh sách đầy đủ. Các bạn có thể cài nhiều binaries tùy thích theo cùng pattern.

Nếu thêm skills mới sau này cần binaries bổ sung, các bạn phải:

1. Cập nhật Dockerfile
2. Rebuild image
3. Restart containers

Ví dụ Dockerfile

FROM node:22-bookworm

RUN apt-get update && apt-get install -y socat && rm -rf /var/lib/apt/lists/*

# Example binary 1: Gmail CLI
RUN curl -L https://github.com/steipete/gog/releases/latest/download/gog_Linux_x86_64.tar.gz \
  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/gog

# Example binary 2: Google Places CLI
RUN curl -L https://github.com/steipete/goplaces/releases/latest/download/goplaces_Linux_x86_64.tar.gz \
  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/goplaces

# Example binary 3: WhatsApp CLI
RUN curl -L https://github.com/steipete/wacli/releases/latest/download/wacli_Linux_x86_64.tar.gz \
  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/wacli

# Add more binaries below using the same pattern

WORKDIR /app
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts

RUN corepack enable
RUN pnpm install --frozen-lockfile

COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build

ENV NODE_ENV=production

CMD ["node","dist/index.js"]

8) Build và khởi động

docker compose build
docker compose up -d openclaw-gateway

Kiểm tra binaries:

docker compose exec openclaw-gateway which gog
docker compose exec openclaw-gateway which goplaces
docker compose exec openclaw-gateway which wacli

Kết quả mong đợi:

/usr/local/bin/gog
/usr/local/bin/goplaces
/usr/local/bin/wacli

9) Kiểm tra Gateway

docker compose logs -f openclaw-gateway

Thành công:

[gateway] listening on ws://0.0.0.0:18789

Từ laptop của các bạn:

ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP

Mở:

http://127.0.0.1:18789/

Paste gateway token của các bạn.

Dữ liệu được lưu ở đâu (source of truth)

OpenClaw chạy trong Docker, nhưng Docker không phải là source of truth. Tất cả dữ liệu lâu dài phải tồn tại qua các lần restart, rebuild và reboot.