قفل Gateway

السبب

يجب أن تمتلك عملية Gateway واحدة فقط إعدادًا ومنفذًا محددَين على المضيف؛ شغّل بوابات إضافية بملفات تعريف معزولة ومنافذ فريدة.
الاستمرار بعد حالات التعطل/SIGKILL دون ترك ملفات قفل قديمة.
الإخفاق سريعًا مع خطأ واضح عندما يمتلك Gateway آخر المنفذ بالفعل.

يفرض بدء التشغيل ملكية النسخة الواحدة في خطوتين مستقلتين، بالترتيب:

قفل الملف يحصل على ملف قفل خاص بكل إعداد ضمن دليل أقفال الحالة. وأثناء الحصول عليه، يتحقق بدء التشغيل من المنفذ المُعدّ بحثًا عن مستمع نشط لاكتشاف مالك قفل قديم (متعطل).
ربط المقبس يربط مستمع HTTP/WebSocket (الافتراضي ws://127.0.0.1:18789) بوصفه مستمع TCP حصريًا.

يمكن أن تفشل كل طبقة بصورة مستقلة، وتطرح خطأ GatewayLockError خاصًا بها.

إذا كان ملف القفل مفقودًا، أو انتهت عملية المالك المسجّلة، أو أظهر فحص منفذ المالك عدم وجود مستمع نشط، يستعيد بدء التشغيل القفل ويتابع.
إذا كان القفل محتجزًا بفعالية ولم تنطبق أي من الحالات أعلاه، يعيد بدء التشغيل المحاولة لمدة تصل إلى 5 ثوانٍ (افتراضيًا) قبل الاستسلام:
GatewayLockError("gateway already running (pid <pid>); lock timeout after <ms>ms")

عند حدوث EADDRINUSE، يعيد بدء التشغيل محاولة الربط حتى 20 مرة بفواصل زمنية قدرها 500 مللي ثانية (نحو 10 ثوانٍ إجمالًا) لتجاوز نافذة TIME_WAIT بعد انتهاء عملية مؤخرًا.

إذا ظل المنفذ قيد الاستخدام بعد إعادة المحاولة:

GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")

حالات فشل الربط الأخرى:

GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: <cause>")

عند إيقاف التشغيل، يغلق Gateway خادم HTTP/WebSocket ويزيل ملف القفل.

إذا كان المنفذ مشغولًا بعملية أخرى ليست Gateway، فسيكون الخطأ نفسه؛ حرّر المنفذ أو اختر منفذًا آخر باستخدام openclaw gateway --port <port>.
عند التشغيل تحت إشراف مدير خدمات، تفحص عملية Gateway جديدة تصادف أيًا من الخطأين أعلاه أولًا المسار /healthz في العملية الحالية. إذا كانت تلك العملية سليمة، تتركها العملية الجديدة مسيطرة بدلًا من الإخفاق. في systemd، تخرج برمز 78؛ ويمنع إعداد الوحدة RestartPreventExitStatus=78 الخيار Restart=always من الدخول في حلقة بسبب تعارض قفل أو EADDRINUSE. إذا لم تصبح العملية الحالية سليمة مطلقًا، تكون إعادة محاولة فحص السلامة محدودة زمنيًا، ثم يفشل بدء التشغيل بخطأ القفل أعلاه بدلًا من الاستمرار في حلقة إلى الأبد.
يحتفظ تطبيق macOS بحارس PID خفيف خاص به قبل تشغيل Gateway؛ أما قفل الملف وربط المقبس الموضحان أعلاه فهما آليتا الفرض الفعليتان أثناء التشغيل.