المتطلبات
- تثبيت flyctl CLI
- حساب Fly.io (تعمل الخطة المجانية)
- مصادقة النموذج: مفتاح API لمزوّد النموذج الذي اخترته
- بيانات اعتماد القناة: رمز بوت Discord، ورمز Telegram، وما إلى ذلك.
المسار السريع للمبتدئين
- استنسخ المستودع، وخصّص
fly.toml - أنشئ التطبيق ووحدة التخزين، واضبط الأسرار
- انشر باستخدام
fly deploy - اتصل عبر SSH لإنشاء الإعدادات، أو استخدم واجهة التحكم
1
إنشاء تطبيق Fly
lhr (لندن)، وiad (فرجينيا)، وsjc (سان خوسيه).2
إعداد fly.toml
عدّل نقطة دخول صورة Docker الخاصة بـ OpenClaw هي
fly.toml ليتوافق مع اسم تطبيقك ومتطلباتك. ملف fly.toml المتتبَّع في المستودع هو القالب العام الموضح أدناه؛ أما deploy/fly.private.toml فهو النسخة المحصّنة التي لا تستخدم عنوان IP عامًا (راجع النشر الخاص).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
النشر
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
استكشاف الأخطاء وإصلاحها
”التطبيق لا يستمع على العنوان المتوقع”
يرتبط 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:
مشكلات قفل 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: وكيل محلي (الأبسط)Webhook مع عملية نشر خاصة
لمعاودات اتصال Webhook (Twilio وTelnyx وغيرهما) من دون إتاحة عامة:- نفق ngrok: شغّل ngrok داخل الحاوية أو كحاوية جانبية
- Tailscale Funnel: أتِح مسارات محددة عبر Tailscale
- الصادر فقط: يعمل بعض المزوّدين (مثل Twilio) للمكالمات الصادرة من دون Webhook
plugins.entries.voice-call.config:
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 لمعرفة الأسعار الحالية.
الخطوات التالية
- إعداد قنوات المراسلة: القنوات
- تهيئة Gateway: تهيئة Gateway
- الحفاظ على تحديث OpenClaw: التحديث