الانتقال إلى المحتوى الرئيسي

OpenClaw على Hetzner (Docker، دليل VPS للإنتاج)

الهدف

تشغيل OpenClaw Gateway بشكل دائم على VPS من Hetzner باستخدام Docker، مع حالة دائمة، وثنائيات مضمّنة، وسلوك آمن لإعادة التشغيل. إذا كنت تريد «OpenClaw على مدار الساعة مقابل ~$5»، فهذا أبسط إعداد موثوق. تتغير أسعار Hetzner؛ اختر أصغر VPS بنظام Debian/Ubuntu ثم وسّع إذا واجهت أخطاء نفاد الذاكرة (OOM).

ماذا نفعل (بمصطلحات بسيطة)؟

  • استئجار خادم Linux صغير (VPS من Hetzner)
  • تثبيت Docker (بيئة تشغيل معزولة للتطبيق)
  • تشغيل OpenClaw Gateway داخل Docker
  • حفظ ~/.openclaw + ~/.openclaw/workspace على المضيف (لتجاوز إعادة التشغيل/إعادة البناء)
  • الوصول إلى واجهة التحكم من حاسوبك المحمول عبر نفق SSH
يمكن الوصول إلى Gateway عبر:
  • إعادة توجيه منفذ SSH من حاسوبك المحمول
  • تعريض المنفذ مباشرة إذا كنت تدير الجدار الناري والرموز بنفسك
يفترض هذا الدليل استخدام Ubuntu أو Debian على Hetzner.
إذا كنت على VPS بنظام Linux آخر، فقم بمواءمة الحزم وفقًا لذلك. للتدفق العام لـ Docker، راجع Docker.

المسار السريع (للمشغّلين ذوي الخبرة)

  1. تجهيز VPS من Hetzner
  2. تثبيت Docker
  3. استنساخ مستودع OpenClaw
  4. إنشاء أدلة مضيف دائمة
  5. تهيئة .env و docker-compose.yml
  6. تضمين الثنائيات المطلوبة داخل الصورة
  7. docker compose up -d
  8. التحقق من الاستمرارية والوصول إلى Gateway

ما تحتاجه

  • VPS من Hetzner مع وصول root
  • وصول SSH من حاسوبك المحمول
  • إلمام أساسي بـ SSH + النسخ/اللصق
  • ~20 دقيقة
  • Docker و Docker Compose
  • بيانات اعتماد مصادقة النموذج
  • بيانات اعتماد موفّر اختيارية
    • رمز QR لـ WhatsApp
    • رمز بوت Telegram
    • OAuth لـ Gmail

1. تجهيز الـ VPS

أنشئ VPS بنظام Ubuntu أو Debian في Hetzner. اتصل كمستخدم root:
ssh root@YOUR_VPS_IP
يفترض هذا الدليل أن الـ VPS ذو حالة (stateful). لا تتعامل معه كبنية تحتية قابلة للتخلص.

2. تثبيت Docker (على الـ VPS)

apt-get update
apt-get install -y git curl ca-certificates
curl -fsSL https://get.docker.com | sh
تحقق:
docker --version
docker compose version

3. استنساخ مستودع OpenClaw

git clone https://github.com/openclaw/openclaw.git
cd openclaw
يفترض هذا الدليل أنك ستبني صورة مخصّصة لضمان استمرارية الثنائيات.

4. إنشاء أدلة مضيف دائمة

حاويات Docker مؤقتة. يجب أن تعيش كل الحالة طويلة الأمد على المضيف.
10. mkdir -p /root/.openclaw/workspace

# تعيين الملكية لمستخدم الحاوية (uid 1000):
chown -R 1000:1000 /root/.openclaw

5. تهيئة متغيرات البيئة

أنشئ .env في جذر المستودع.
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
ولّد أسرارًا قوية:
openssl rand -hex 32
لا تقم بإضافة هذا الملف إلى المستودع.

6. تهيئة Docker Compose

أنشئ أو حدّث docker-compose.yml.
11. 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:
      # موصى به: إبقاء البوابة مقصورة على loopback فقط على الـ VPS؛ الوصول عبر نفق SSH.
      # لعرضها علناً، أزل بادئة `127.0.0.1:` واضبط الجدار الناري وفقاً لذلك.
      - "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789"

      # اختياري: فقط إذا كنت تشغّل عقد iOS/Android مقابل هذا الـ VPS وتحتاج إلى Canvas host.
      # إذا عرضته علناً، اقرأ /gateway/security واضبط الجدار الناري وفقاً لذلك.
      # - "18793:18793"
    command:
      [
        "node",
        "dist/index.js",
        "gateway",
        "--bind",
        "${OPENCLAW_GATEWAY_BIND}",
        "--port",
        "${OPENCLAW_GATEWAY_PORT}",
        "--allow-unconfigured",
      ]
الخيار --allow-unconfigured مخصّص فقط لتسهيل الإقلاع الأولي، وليس بديلاً عن إعداد بوابة مناسب. لا تزال بحاجة إلى تعيين المصادقة (gateway.auth.token أو كلمة المرور) واستخدام إعدادات ربط آمنة لنشرِك.

7. تضمين الثنائيات المطلوبة داخل الصورة (أمر حاسم)

تثبيت الثنائيات داخل حاوية قيد التشغيل فخّ. أي شيء يُثبَّت وقت التشغيل سيُفقد عند إعادة التشغيل. يجب تثبيت جميع الثنائيات الخارجية المطلوبة من Skills أثناء بناء الصورة. تُظهر الأمثلة أدناه ثلاث ثنائيات شائعة فقط:
  • gog للوصول إلى Gmail
  • goplaces لـ Google Places
  • wacli لـ WhatsApp
هذه أمثلة وليست قائمة كاملة. يمكنك تثبيت أي عدد من الثنائيات باستخدام النمط نفسه. إذا أضفت Skills جديدة لاحقًا تعتمد على ثنائيات إضافية، فيجب عليك:
  1. تحديث Dockerfile
  2. إعادة بناء الصورة
  3. إعادة تشغيل الحاويات
مثال 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. البناء والتشغيل

docker compose build
docker compose up -d openclaw-gateway
تحقق من الثنائيات:
docker compose exec openclaw-gateway which gog
docker compose exec openclaw-gateway which goplaces
docker compose exec openclaw-gateway which wacli
المخرجات المتوقعة:
/usr/local/bin/gog
/usr/local/bin/goplaces
/usr/local/bin/wacli

9. التحقق من Gateway

docker compose logs -f openclaw-gateway
النجاح:
[gateway] listening on ws://0.0.0.0:18789
من حاسوبك المحمول:
ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP
افتح: http://127.0.0.1:18789/ الصق رمز Gateway الخاص بك.

ما الذي يستمر وأين (مصدر الحقيقة)

يعمل OpenClaw داخل Docker، لكن Docker ليس مصدر الحقيقة. يجب أن تبقى كل الحالة طويلة الأمد عبر إعادة التشغيل وإعادة البناء وإعادة الإقلاع.
المكونالموقعآلية الاستمراريةملاحظات
تهيئة Gateway/home/node/.openclaw/تحميل حجم صوت المضيفتتضمن openclaw.json، والرموز
ملفات مصادقة النموذج/home/node/.openclaw/تحميل حجم صوت المضيفرموز OAuth، مفاتيح API
تهيئات Skills/home/node/.openclaw/skills/تحميل حجم صوت المضيفحالة على مستوى Skill
مساحة عمل الوكيل/home/node/.openclaw/workspace/تحميل حجم صوت المضيفالشيفرة ومواد الوكيل
جلسة WhatsApp/home/node/.openclaw/تحميل حجم صوت المضيفيحفظ تسجيل الدخول عبر QR
حلقة مفاتيح Gmail/home/node/.openclaw/وحدة تخزين للمضيف + كلمة مروريتطلب GOG_KEYRING_PASSWORD
الثنائيات الخارجية/usr/local/bin/صورة Dockerيجب تضمينها وقت البناء
بيئة تشغيل Nodeنظام ملفات الحاويةصورة Dockerتُعاد بناؤها مع كل بناء للصورة
حزم نظام التشغيلنظام ملفات الحاويةصورة Dockerلا تُثبَّت وقت التشغيل
حاوية Dockerمؤقّتقابلة لإعادة التشغيلآمنة للإزالة

البنية التحتية ككود (Terraform)

للفِرق التي تفضّل سير عمل البنية التحتية ككود، يوفّر إعداد Terraform المُدار من المجتمع ما يلي:
  • إعداد Terraform معياري مع إدارة حالة بعيدة
  • توفير تلقائي عبر cloud-init
  • نصوص نشر (bootstrap، deploy، backup/restore)
  • تعزيز الأمان (جدار ناري، UFW، وصول عبر SSH فقط)
  • إعداد نفق SSH للوصول إلى Gateway
المستودعات: يُكمل هذا النهج إعداد Docker أعلاه من خلال عمليات نشر قابلة لإعادة الإنتاج، وبنية تحتية مُدارة بالإصدارات، وتعافٍ تلقائي من الكوارث.
ملاحظة: مُدار من المجتمع. للمشكلات أو المساهمات، راجع روابط المستودعات أعلاه.