---
read_when:
    - تشغيل عملية Gateway أو تصحيح أخطائها
    - جارٍ التحقق من فرض تشغيل مثيل واحد
summary: حارس المثيل المفرد لـ Gateway باستخدام ربط مستمع WebSocket
title: قفل Gateway
x-i18n:
    generated_at: "2026-04-30T16:29:15Z"
    model: gpt-5.5
    provider: openai
    source_hash: 85a1cb55f08d47d36fde25900e4247ef01c9a6800bf017fbff44a337f299ce13
    source_path: gateway/gateway-lock.md
    workflow: 16
---

## لماذا

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

## الآلية

- يحصل Gateway أولًا على ملف قفل لكل تهيئة ضمن دليل أقفال الحالة، ويفحص المنفذ المهيأ بحثًا عن مستمع موجود.
- إذا كان مالك القفل المسجل غير موجود، أو كان المنفذ حرًا، أو كان القفل قديمًا، تستعيد عملية بدء التشغيل القفل وتتابع.
- بعد ذلك يربط Gateway مستمع HTTP/WebSocket (الافتراضي `ws://127.0.0.1:18789`) باستخدام مستمع TCP حصري.
- إذا فشل الربط مع `EADDRINUSE`، ترمي عملية بدء التشغيل `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`.
- عند الإيقاف، يغلق Gateway خادم HTTP/WebSocket ويزيل ملف القفل.

## واجهة الأخطاء

- إذا كانت عملية أخرى تحتفظ بالمنفذ، ترمي عملية بدء التشغيل `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>: …")`.

## ملاحظات تشغيلية

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

## ذات صلة

- [عدة مثيلات Gateway](/ar/gateway/multiple-gateways) — تشغيل عدة مثيلات بمنافذ فريدة
- [استكشاف الأخطاء وإصلاحها](/ar/gateway/troubleshooting) — تشخيص `EADDRINUSE` وتعارضات المنافذ