Hetzner

Provision the VPS

یک VPS با Ubuntu یا Debian در Hetzner ایجاد کنید.

به‌عنوان root وصل شوید:

ssh root@YOUR_VPS_IP

این راهنما فرض می‌کند VPS وضعیت‌مند است. با آن مثل زیرساخت دورریختنی رفتار نکنید.

Install Docker (on the VPS)

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

تأیید کنید:

docker --version
docker compose version

Clone the OpenClaw repository

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

این راهنما فرض می‌کند برای تضمین ماندگاری باینری‌ها یک image سفارشی می‌سازید.

Create persistent host directories

کانتینرهای Docker گذرا هستند. همه وضعیت‌های بلندمدت باید روی میزبان قرار بگیرند.

mkdir -p /root/.openclaw/workspace

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

Configure environment variables

فایل .env را در ریشه مخزن ایجاد کنید.

OPENCLAW_IMAGE=openclaw:latest
OPENCLAW_GATEWAY_TOKEN=
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_PORT=18789

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

GOG_KEYRING_PASSWORD=
XDG_CONFIG_HOME=/home/node/.openclaw

وقتی می‌خواهید توکن پایدار gateway را از طریق .env مدیریت کنید، OPENCLAW_GATEWAY_TOKEN را تنظیم کنید؛ در غیر این صورت، پیش از تکیه بر کلاینت‌ها در راه‌اندازی‌های مجدد، gateway.auth.token را پیکربندی کنید. اگر هیچ‌کدام از این منابع وجود نداشته باشد، OpenClaw برای آن راه‌اندازی از یک توکن فقط در زمان اجرا استفاده می‌کند. یک گذرواژه keyring تولید کنید و آن را در GOG_KEYRING_PASSWORD جای‌گذاری کنید:

openssl rand -hex 32

این فایل را commit نکنید.

این فایل .env برای env کانتینر/محیط اجرا مانند OPENCLAW_GATEWAY_TOKEN است. احراز هویت ذخیره‌شده OAuth/API-key مربوط به providerها در مسیر mount‌شده‌ی ~/.openclaw/agents/<agentId>/agent/auth-profiles.json قرار دارد.

Docker Compose configuration

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:
      # 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"
    command:
      [
        "node",
        "dist/index.js",
        "gateway",
        "--bind",
        "${OPENCLAW_GATEWAY_BIND}",
        "--port",
        "${OPENCLAW_GATEWAY_PORT}",
        "--allow-unconfigured",
      ]

--allow-unconfigured فقط برای راحتی bootstrap است و جایگزین پیکربندی درست gateway نیست. همچنان auth (gateway.auth.token یا گذرواژه) را تنظیم کنید و برای deployment خود از تنظیمات bind ایمن استفاده کنید.

Shared Docker VM runtime steps

برای جریان مشترک میزبان Docker از راهنمای محیط اجرای مشترک استفاده کنید:

• قراردادن باینری‌های لازم داخل image
• ساخت و راه‌اندازی
• چه چیزی کجا ماندگار می‌شود
• به‌روزرسانی‌ها

Hetzner-specific access

پس از مراحل ساخت و راه‌اندازی مشترک، برای باز کردن تونل، راه‌اندازی زیر را کامل کنید:

پیش‌نیاز: مطمئن شوید پیکربندی sshd در VPS شما بازارسال TCP را مجاز می‌کند. اگر پیکربندی SSH خود را سخت‌گیرانه کرده‌اید، /etc/ssh/sshd_config را بررسی کنید و تنظیم کنید:

AllowTcpForwarding local

local بازارسال‌های محلی ssh -L از لپ‌تاپ شما را مجاز می‌کند و هم‌زمان بازارسال‌های راه‌دور از سرور را مسدود می‌کند. تنظیم آن روی no باعث شکست تونل با این پیام می‌شود: channel 3: open failed: administratively prohibited: open failed

پس از تأیید فعال بودن بازارسال TCP، سرویس SSH را راه‌اندازی مجدد کنید (systemctl restart ssh) و تونل را از لپ‌تاپ خود اجرا کنید:

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

باز کنید:

http://127.0.0.1:18789/

راز مشترک پیکربندی‌شده را جای‌گذاری کنید. این راهنما به‌صورت پیش‌فرض از توکن gateway استفاده می‌کند؛ اگر به احراز هویت با گذرواژه تغییر داده‌اید، به‌جای آن از همان گذرواژه استفاده کنید.