> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hetzner

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

## Mục tiêu

Chạy một OpenClaw Gateway bền vững trên VPS Hetzner bằng Docker, với trạng thái được lưu lâu dài, các binary được đóng gói sẵn và hành vi khởi động lại an toàn.

If you want “OpenClaw 24/7 for \~\$5”, this is the simplest reliable setup.
Hetzner pricing changes; pick the smallest Debian/Ubuntu VPS and scale up if you hit OOMs.

## Chúng ta đang làm gì (nói đơn giản)?

* Thuê một máy chủ Linux nhỏ (VPS Hetzner)
* Cài Docker (môi trường chạy ứng dụng tách biệt)
* Khởi động OpenClaw Gateway trong Docker
* Lưu `~/.openclaw` + `~/.openclaw/workspace` trên máy chủ (tồn tại qua các lần restart/rebuild)
* Truy cập Control UI từ laptop của bạn qua đường hầm SSH

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

* Chuyển tiếp cổng SSH từ laptop của bạn
* Mở cổng trực tiếp nếu bạn tự quản lý firewall và token

This guide assumes Ubuntu or Debian on Hetzner.\
If you are on another Linux VPS, map packages accordingly.
For the generic Docker flow, see [Docker](/install/docker).

***

## Lộ trình nhanh (người vận hành có kinh nghiệm)

1. Tạo VPS Hetzner
2. Cài Docker
3. Clone repository OpenClaw
4. Tạo các thư mục host lưu trữ lâu dài
5. Cấu hình `.env` và `docker-compose.yml`
6. Đóng gói các binary cần thiết vào image
7. `docker compose up -d`
8. Xác minh tính bền vững và truy cập Gateway

***

## Những gì bạn cần

* VPS Hetzner với quyền root
* Truy cập SSH từ laptop của bạn
* Thoải mái cơ bản với SSH + copy/paste
* \~20 phút
* Docker và Docker Compose
* Thông tin xác thực mô hình
* Thông tin xác thực nhà cung cấp (tùy chọn)
  * WhatsApp QR
  * Telegram bot token
  * Gmail OAuth

***

## 1. Tạo VPS

Tạo một VPS Ubuntu hoặc Debian trên Hetzner.

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
ssh root@YOUR_VPS_IP
```

This guide assumes the VPS is stateful.
Đừng coi đây là hạ tầng dùng rồi bỏ.

***

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
apt-get update
apt-get install -y git curl ca-certificates
curl -fsSL https://get.docker.com | sh
```

Xác minh:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
docker --version
docker compose version
```

***

## 3. Clone repository OpenClaw

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
git clone https://github.com/openclaw/openclaw.git
cd openclaw
```

Hướng dẫn này giả định bạn sẽ build một image tùy chỉnh để đảm bảo binary được lưu bền vững.

***

## 4. Tạo các thư mục host lưu trữ lâu dài

Docker containers are ephemeral.
All long-lived state must live on the host.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
mkdir -p /root/.openclaw/workspace

# Set ownership to the container user (uid 1000):
chown -R 1000:1000 /root/.openclaw
```

***

## 5. Cấu hình biến môi trường

Tạo `.env` ở thư mục gốc của repository.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 các secret mạnh:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openssl rand -hex 32
```

**Không commit file này.**

***

## 6. Cấu hình Docker Compose

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

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
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:
      # Recommended: keep the Gateway loopback-only on the VPS; access via SSH tunnel.
      # To expose it publicly, remove the `127.0.0.1:` prefix and firewall accordingly.
      - "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789"

      # Optional: only if you run iOS/Android nodes against this VPS and need Canvas host.
      # If you expose this publicly, read /gateway/security and firewall accordingly.
      # - "18793:18793"
    command:
      [
        "node",
        "dist/index.js",
        "gateway",
        "--bind",
        "${OPENCLAW_GATEWAY_BIND}",
        "--port",
        "${OPENCLAW_GATEWAY_PORT}",
        "--allow-unconfigured",
      ]
```

`--allow-unconfigured` is only for bootstrap convenience, it is not a replacement for a proper gateway configuration. Still set auth (`gateway.auth.token` or password) and use safe bind settings for your deployment.

***

## 7. Đóng gói các binary cần thiết vào image (quan trọng)

Installing binaries inside a running container is a trap.
Anything installed at runtime will be lost on restart.

Tất cả các binary bên ngoài mà Skills cần phải được cài ở bước build image.

Ví dụ dưới đây chỉ minh họa ba binary phổ biến:

* `gog` cho truy cập Gmail
* `goplaces` cho Google Places
* `wacli` cho WhatsApp

These are examples, not a complete list.
You may install as many binaries as needed using the same pattern.

Nếu sau này bạn thêm Skills mới phụ thuộc vào các binary khác, bạn phải:

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

**Ví dụ Dockerfile**

```dockerfile theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 chạy

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
docker compose build
docker compose up -d openclaw-gateway
```

Xác minh các binary:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
docker compose exec openclaw-gateway which gog
docker compose exec openclaw-gateway which goplaces
docker compose exec openclaw-gateway which wacli
```

Đầu ra mong đợi:

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

***

## 9. Xác minh Gateway

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
docker compose logs -f openclaw-gateway
```

Thành công:

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

Từ laptop của bạn:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP
```

Mở:

`http://127.0.0.1:18789/`

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

***

## Những gì được lưu ở đâu (nguồn sự thật)

OpenClaw runs in Docker, but Docker is not the source of truth.
All long-lived state must survive restarts, rebuilds, and reboots.

| Thành phần             | Vị trí                            | Cơ chế lưu trữ         | Ghi chú                        |
| ---------------------- | --------------------------------- | ---------------------- | ------------------------------ |
| Cấu hình Gateway       | `/home/node/.openclaw/`           | Gắn volume host        | Bao gồm `openclaw.json`, token |
| Hồ sơ xác thực mô hình | `/home/node/.openclaw/`           | Gắn volume host        | OAuth token, khóa API          |
| Cấu hình Skill         | `/home/node/.openclaw/skills/`    | Gắn volume host        | Trạng thái cấp Skill           |
| Workspace agent        | `/home/node/.openclaw/workspace/` | Gắn volume host        | Mã và artifact của agent       |
| Phiên WhatsApp         | `/home/node/.openclaw/`           | Gắn volume host        | Giữ đăng nhập QR               |
| Keyring Gmail          | `/home/node/.openclaw/`           | Volume host + mật khẩu | Yêu cầu `GOG_KEYRING_PASSWORD` |
| Binary bên ngoài       | `/usr/local/bin/`                 | Docker image           | Phải được đóng gói khi build   |
| Runtime Node           | Hệ thống file container           | Docker image           | Rebuild mỗi lần build image    |
| Gói OS                 | Hệ thống file container           | Docker image           | Không cài ở runtime            |
| Docker container       | Tạm thời                          | Có thể restart         | An toàn để xóa                 |

***

## Hạ tầng dưới dạng mã (Terraform)

Đối với các nhóm ưu tiên quy trình hạ tầng dưới dạng mã, một cấu hình Terraform do cộng đồng duy trì cung cấp:

* Cấu hình Terraform dạng module với quản lý remote state
* Tự động cấp phát thông qua cloud-init
* Các script triển khai (bootstrap, deploy, backup/restore)
* Tăng cường bảo mật (tường lửa, UFW, chỉ cho phép truy cập SSH)
* Cấu hình SSH tunnel để truy cập gateway

**Kho lưu trữ:**

* Infrastructure: [openclaw-terraform-hetzner](https://github.com/andreesg/openclaw-terraform-hetzner)
* Docker config: [openclaw-docker-config](https://github.com/andreesg/openclaw-docker-config)

Cách tiếp cận này bổ sung cho thiết lập Docker ở trên bằng các triển khai có thể tái tạo, hạ tầng được quản lý bằng version control và khôi phục sau thảm họa tự động.

> **Lưu ý:** Do cộng đồng duy trì. Đối với sự cố hoặc đóng góp, xem các liên kết repository ở trên.