Skip to main content
الهدف: تشغيل OpenClaw Gateway على جهاز Fly.io مع تخزين دائم، وHTTPS تلقائي، وإمكانية الوصول عبر Discord/القنوات.

المتطلبات

  • تثبيت flyctl CLI
  • حساب Fly.io (تعمل الخطة المجانية)
  • مصادقة النموذج: مفتاح API لمزوّد النموذج الذي اخترته
  • بيانات اعتماد القناة: رمز بوت Discord، ورمز Telegram، وما إلى ذلك.

المسار السريع للمبتدئين

  1. استنسخ المستودع، وخصّص fly.toml
  2. أنشئ التطبيق ووحدة التخزين، واضبط الأسرار
  3. انشر باستخدام fly deploy
  4. اتصل عبر SSH لإنشاء الإعدادات، أو استخدم واجهة التحكم
1

إنشاء تطبيق Fly

اختر منطقة قريبة منك. من الخيارات الشائعة: lhr (لندن)، وiad (فرجينيا)، وsjc (سان خوسيه).
2

إعداد fly.toml

عدّل fly.toml ليتوافق مع اسم تطبيقك ومتطلباتك. ملف fly.toml المتتبَّع في المستودع هو القالب العام الموضح أدناه؛ أما deploy/fly.private.toml فهو النسخة المحصّنة التي لا تستخدم عنوان IP عامًا (راجع النشر الخاص).
نقطة دخول صورة Docker الخاصة بـ OpenClaw هي tini، وتشغّل node openclaw.mjs gateway افتراضيًا. يستبدل [processes] في Fly تعليمة Docker ‏CMD (وهنا يشغّل node dist/index.js gateway ... مباشرةً، وهي نقطة الدخول المترجمة نفسها) من دون المساس بـ ENTRYPOINT، لذلك تظل العملية تعمل تحت tini.الإعدادات الأساسية:
3

ضبط الأسرار

تتطلب عمليات الربط خارج عنوان الاسترجاع (--bind lan) مسار مصادقة صالحًا لـ Gateway. يستخدم هذا المثال OPENCLAW_GATEWAY_TOKEN، لكن gateway.auth.password أو نشر وكيل موثوق خارج عنوان الاسترجاع ومُعدّ إعدادًا صحيحًا يفيان بالمتطلب أيضًا. راجع إدارة الأسرار للاطلاع على عقد SecretRef.تعامل مع هذه الرموز كما تتعامل مع كلمات المرور. يُفضَّل استخدام متغيرات البيئة/fly secrets بدلًا من ملف الإعدادات لمفاتيح API والرموز كي تظل الأسرار خارج openclaw.json.
4

النشر

يبني النشر الأول صورة Docker. تحقّق بعد النشر:
تسجّل عملية بدء Gateway الرسالة gateway ready بمجرد تشغيل مستمع HTTP/WebSocket. تراقب عملية التحقق من السلامة الخاصة بـ Fly المسار internal_port = 3000 وفقًا لـ fly.toml؛ كما تستطلع تعليمة Docker ‏HEALTHCHECK في الصورة المسار /healthz على منفذها الافتراضي 18789، وهو غير مستخدم هنا لأن هذا النشر يغيّر منفذ Gateway إلى --port 3000.
5

إنشاء ملف الإعدادات

اتصل بالجهاز عبر SSH لإنشاء إعدادات صحيحة:
عند استخدام OPENCLAW_STATE_DIR=/data، يكون مسار الإعدادات هو /data/openclaw.json.استبدل https://my-openclaw.fly.dev بالأصل الفعلي لتطبيق Fly الخاص بك. تملأ عملية بدء Gateway أصول واجهة التحكم المحلية أوليًا من قيمتي وقت التشغيل --bind و--port حتى يمكن إتمام التشغيل الأول قبل وجود الإعدادات، لكن الوصول عبر المتصفح من خلال Fly يظل يتطلب إدراج أصل HTTPS الدقيق في gateway.controlUi.allowedOrigins.يمكن الحصول على رمز Discord من أيٍّ مما يلي:
  • متغير البيئة DISCORD_BOT_TOKEN (موصى به للأسرار)؛ لا حاجة إلى إضافته إلى الإعدادات، إذ يقرأه Gateway تلقائيًا
  • ملف الإعدادات channels.discord.token
أعد التشغيل لتطبيق التغييرات:
6

الوصول إلى Gateway

واجهة التحكم

أو زُر https://my-openclaw.fly.dev/.صادِق باستخدام السر المشترك المُعدّ: رمز Gateway من OPENCLAW_GATEWAY_TOKEN، أو كلمة مرورك إذا انتقلت إلى المصادقة بكلمة مرور.

السجلات

وحدة تحكم SSH

استكشاف الأخطاء وإصلاحها

”التطبيق لا يستمع على العنوان المتوقع”

يرتبط Gateway بـ 127.0.0.1 بدلًا من 0.0.0.0. الإصلاح: أضف --bind lan إلى أمر العملية في fly.toml.

فشل عمليات التحقق من السلامة / رفض الاتصال

يتعذر على Fly الوصول إلى Gateway على المنفذ المُعدّ. الإصلاح: تأكد من أن internal_port يطابق منفذ Gateway ‏(--port 3000 أو OPENCLAW_GATEWAY_PORT=3000).

نفاد الذاكرة / مشكلات الذاكرة

تستمر الحاوية في إعادة التشغيل أو تُنهى. من العلامات: SIGABRT، أو v8::internal::Runtime_AllocateInYoungGeneration، أو عمليات إعادة تشغيل صامتة. الإصلاح: زِد الذاكرة في fly.toml:
أو حدّث جهازًا موجودًا:
سعة 512MB صغيرة جدًا. قد تعمل سعة 1GB، لكنها قد تنفد تحت الحمل أو عند استخدام تسجيل مطوّل. يُوصى بسعة 2GB.

مشكلات قفل Gateway

يرفض Gateway بدء التشغيل مع أخطاء “قيد التشغيل بالفعل” بعد إعادة تشغيل الحاوية. توجد ملفات قفل وقت التشغيل في <tmpdir>/openclaw-<uid>/gateway.<hash>.lock وgateway.state.<hash>.lock (في Linux: /tmp/openclaw-<uid>/gateway.*.lock)، وليس على وحدة التخزين الدائمة /data، ولذلك تمسح إعادة التشغيل الكاملة للحاوية هذه الملفات عادةً مع بقية نظام ملفات الحاوية. إذا استمر وجود قفل (مثلًا بسبب fly machine restart يحافظ على نظام ملفات الحاوية) ومنع بدء التشغيل، فأزله يدويًا:

عدم قراءة الإعدادات

يتجاوز --allow-unconfigured حارس بدء التشغيل فقط. ولا ينشئ /data/openclaw.json أو يصلحه، لذا تأكد من وجود إعداداتك الفعلية وتضمينها "gateway": { "mode": "local" } لبدء Gateway محلي بصورة طبيعية. تحقّق من وجود الإعدادات:

كتابة الإعدادات عبر SSH

لا يدعم fly ssh console -C إعادة توجيه الصدفة. لكتابة ملف إعدادات:
قد يفشل fly sftp إذا كان الملف موجودًا بالفعل؛ احذفه أولًا:

عدم استمرار الحالة

إذا فقدت ملفات تعريف المصادقة أو حالة القناة/المزوّد أو الجلسات بعد إعادة التشغيل، فهذا يعني أن دليل الحالة يُكتب في نظام ملفات الحاوية بدلًا من وحدة التخزين. الإصلاح: تأكد من ضبط OPENCLAW_STATE_DIR=/data في fly.toml، ثم أعد النشر.

التحديث

يمثّل git pull + fly deploy المسار المُدار هنا: فهو يعيد بناء الصورة من Dockerfile، ولذلك يتحدّث إصدار CLI/Gateway وصورة نظام التشغيل الأساسية وأي تغييرات في Dockerfile معًا. ليست عملية openclaw update داخل الحاوية قيد التشغيل هي العملية نفسها، لأن الصورة تُشحَن كشجرة dist/ مبنية باستخدام Docker من دون نسخة عمل .git ومن دون تثبيت عام يديره npm كي تكتشفه؛ راجع التحديث للاطلاع على هذا المسار في عمليات التثبيت المشابهة للأجهزة الافتراضية.

تحديث أمر الجهاز

لتغيير أمر بدء التشغيل دون إعادة نشر كاملة:
تعيد عملية fly deploy اللاحقة أمر الجهاز إلى ما هو موجود في fly.toml؛ أعِد تطبيق التغييرات اليدوية بعد إعادة النشر.

النشر الخاص (المحصّن)

يخصّص Fly عناوين IP عامة افتراضيًا، ولذلك يمكن الوصول إلى Gateway عبر https://your-app.fly.dev ويمكن لأدوات فحص الإنترنت اكتشافه (Shodan وCensys وغيرهما). استخدم deploy/fly.private.toml لنشر محصّن دون عنوان IP عام: فهو يحذف [http_service]، ولذلك لا يُخصّص أي دخول عام.

متى تستخدم النشر الخاص

  • المكالمات/الرسائل الصادرة فقط (دون Webhook واردة)
  • تتولى أنفاق ngrok أو Tailscale أي استدعاءات راجعة لـ Webhook
  • يتم الوصول إلى Gateway عبر SSH أو وكيل أو WireGuard بدلًا من المتصفح
  • يجب إخفاء النشر عن أدوات فحص الإنترنت

الإعداد

أو حوّل نشرًا موجودًا:
بعد ذلك، يجب أن يعرض fly ips list عنوان IP من النوع private فقط:

الوصول إلى عملية نشر خاصة

الخيار 1: وكيل محلي (الأبسط)
الخيار 2: شبكة WireGuard VPN
الخيار 3: SSH فقط

Webhook مع عملية نشر خاصة

لمعاودات اتصال Webhook ‏(Twilio وTelnyx وغيرهما) من دون إتاحة عامة:
  1. نفق ngrok: شغّل ngrok داخل الحاوية أو كحاوية جانبية
  2. Tailscale Funnel: أتِح مسارات محددة عبر Tailscale
  3. الصادر فقط: يعمل بعض المزوّدين (مثل Twilio) للمكالمات الصادرة من دون Webhook
مثال على إعداد المكالمات الصوتية باستخدام ngrok، ضمن plugins.entries.voice-call.config:
يعمل نفق ngrok داخل الحاوية ويوفّر عنوان URL عامًا لـ Webhook من دون إتاحة تطبيق Fly نفسه. اضبط webhookSecurity.allowedHosts على اسم مضيف النفق للسماح بترويسات المضيف المُعاد توجيهها.

المفاضلات الأمنية

ملاحظات

  • تستخدم Fly.io معمارية x86؛ ويتوافق Dockerfile مع كل من x86 وARM.
  • لتهيئة WhatsApp/Telegram، استخدم fly ssh console.
  • توجد البيانات الدائمة على وحدة التخزين في /data.
  • يتطلب Signal وجود signal-cli (أداة CLI مبنية على Java) في الصورة؛ استخدم صورة مخصصة وأبقِ الذاكرة عند 2GB أو أكثر.

التكلفة

مع الإعداد الموصى به (shared-cpu-2x وذاكرة RAM بسعة 2GB)، توقّع تكلفة تقارب $10-15 شهريًا حسب الاستخدام؛ وتغطي الخطة المجانية قدرًا أساسيًا من الاستهلاك. راجع أسعار Fly.io لمعرفة الأسعار الحالية.

الخطوات التالية

ذو صلة