تكاملات Gateway للتطبيقات الخارجية

تتواصل التطبيقات الخارجية مع OpenClaw عبر بروتوكول Gateway: نقل ويب سوكيت بالإضافة إلى أساليب RPC. استخدمه عندما يريد برنامج نصي أو لوحة معلومات أو مهمة CI أو امتداد IDE أو عملية أخرى بدء عمليات تشغيل الوكيل، أو بث الأحداث، أو انتظار النتائج، أو إلغاء العمل، أو فحص موارد Gateway.

ما المتاح حاليًا

يجري العمل داخليًا على حزمة مكتبة عميل مستقبلية، لكنها ليست واجهة تثبيت عامة حتى الآن. تعامل معها كتفصيل تنفيذي تجريبي إلى أن يُعلن إصدار عن حزمة منشورة وذات إصدار محدد.

المسار الموصى به

1. شغّل Gateway أو اكتشفه.
2. اتصل عبر بروتوكول Gateway.
3. استدعِ أساليب RPC الموثقة في مرجع Gateway RPC.
4. ثبّت إصدار OpenClaw الذي تختبر عليه.
5. أعد مراجعة مرجع RPC عند ترقية OpenClaw.

بالنسبة إلى عمليات تشغيل الوكيل، ابدأ بأسلوب RPC‏ agent واقرنه بـ agent.wait للحصول على نتيجة نهائية. ولحالة المحادثة الدائمة، استخدم أساليب sessions.*. أما تكاملات واجهة المستخدم، فاشترك في أحداث Gateway واعرض فقط فئات الأحداث التي يفهمها تطبيقك.

التعليق التعاوني للمضيف

يمكن لوحدات تحكم الاستضافة التي تجمّد عملية قيد التشغيل أو تأخذ لقطة منها استخدام مصافحة التعليق المحايدة تجاه المضيف:

1. أوقف قبول حركة الدخول الخارجية التي يتحكم فيها المضيف.
2. استدعِ gateway.suspend.prepare باستخدام requestId ثابت وفريد.
3. إذا كانت الاستجابة busy، فأبقِ العملية قيد التشغيل وأعد المحاولة لاحقًا.
4. إذا كانت ready، فاحفظ suspensionId المُعاد، ثم جمّد العملية أو التقط لقطة لها قبل expiresAtMs.
5. بعد استئناف العملية من التجميد، أو إذا أُلغي التعليق، استدعِ gateway.suspend.resume باستخدام suspensionId نفسه عبر اتصال ويب سوكيت الحالي أو مسار تحكم Admin HTTP.

يرفض Gateway المُعَدّ مسبقًا مصافحات ويب سوكيت الجديدة. يجب على وحدة تحكم ويب سوكيت إبقاء اتصالها الموثّق مفتوحًا طوال عملية المضيف. إذا تعذّر ضمان ذلك، ففعّل واستخدم Plugin ‏Admin HTTP RPC قبل الإعداد. إذا فُقد مسار التحكم، فانتظر انتهاء مدة الإيجار البالغة دقيقتين قبل إعادة الاتصال؛ إذ يعيد انتهاء الصلاحية فتح القبول تلقائيًا.

عقد RPC هو:

• gateway.suspend.prepare — operator.admin؛ المعاملات { "requestId": "stable-host-operation-id" }
• gateway.suspend.status — operator.read؛ المعاملات { "suspensionId": "id-from-prepare" }
• gateway.suspend.resume — operator.admin؛ المعاملات { "suspensionId": "id-from-prepare" }

تُزال المسافات المحيطة بالمُعرّفات، ويجب أن تحتوي على محرف واحد على الأقل غير فارغ، كما يقتصر طولها على 128 محرفًا. تتضمن نتيجة الإعداد المشغول status: "busy" وreason وretryAfterMs وactiveCount وblockers. وتكون نتيجة الجاهزية بهذا الشكل:

{  "status": "ready",  "suspensionId": "2c3f...",  "expiresAtMs": 1770000000000,  "activeCount": 0,  "blockers": []}

تعيد الحالة {"status":"running"} أو نتيجة جاهزية تتضمن expiresAtMs. ويعيد الاستئناف {"ok":true,"status":"running","resumed":true}؛ أما تكراره بعد استئناف ناجح فيعيد resumed: false.

يؤدي استخدام مُعرّف طلب متعارض أو حدوث فشل عابر في استئناف المُجدول إلى إعادة UNAVAILABLE قابل لإعادة المحاولة مع retryAfterMs. أثناء استعادة المُجدول، تعيد عمليات الإعداد والحالة والاستئناف جميعها هذا الخطأ، ويبقى Gateway غير جاهز ومغلقًا عند الفشل، ويجب ألا يجمّده المضيف أو يأخذ لقطة منه. يعيد OpenClaw محاولة تشغيل المُجدول تلقائيًا، ولا يعيد فتح القبول إلا بعد نجاح الاستعادة. ويعيد مُعرّف استئناف غير مطابق INVALID_REQUEST. يشترك الإعداد في ميزانية الكتابة لمستوى تحكم Gateway، والبالغة ثلاث محاولات في الدقيقة؛ التزم بمدة تأخير إعادة المحاولة المُعادة. تُقسّم عملاء ويب سوكيت إلى مجموعات حسب الجهاز وعنوان IP. أما وحدات تحكم Admin HTTP فتُقسّم حسب عنوان IP المحسوم للعميل، ولذلك قد تتشارك وحدات التحكم الموجودة خلف وكيل واحد الميزانية نفسها.

الإعداد قائم على الرفض فقط: يغلق OpenClaw قبول الجذر والجلسات والأوامر الجديدة، ويوقف مؤقتًا نبضات Cron التلقائية، ويفحص العمل بصورة متزامنة. إذا كان أي شيء نشطًا، فإنه يستأنف المُجدول ويعيد فتح القبول قبل إعادة busy؛ ولا يقاطع ذلك العمل أو يفرّغه. يستمر إيجار الجاهزية دقيقتين. يؤدي تكرار prepare باستخدام requestId نفسه إلى تجديده؛ ويستأنف انتهاء الصلاحية المُجدول قبل إعادة فتح القبول. أما إرسال إعادة التشغيل الذي يحين موعده خلال إيجار الجاهزية، فينتظر حتى استئناف الإيجار؛ وتجعل إعادة التشغيل الجارية الإعداد يعيد busy.

أثناء الجاهزية، يظل /healthz نشطًا ويعيد /readyz الرمز 503. تتضمن استجابات الجاهزية المحلية أو الموثّقة gateway-draining؛ بينما لا تتلقى اختبارات الفحص البعيدة غير الموثّقة سوى { "ready": false }. يظل اختبار سلامة HTTP، وأساليب التعليق على اتصالات ويب سوكيت القائمة، ومسار Admin HTTP RPC المفعّل مسبقًا متاحًا. أما استدعاءات RPC الأخرى فتعيد UNAVAILABLE قابلًا لإعادة المحاولة. وتعيد مسارات HTTP المضمّنة لأعمال المستخدم ومسارات HTTP العادية الخاصة بالـ Plugins، بما فيها واجهات API المتوافقة مع OpenAI، وعمليات الأدوات والجلسات، ومراقبات Node، والخطافات المُعدّة، الرمز 503 مع error.code: "gateway_unavailable". كما تعيد ترقيات ويب سوكيت الجديدة المملوكة للـ Plugins الرمز 503؛ ويغطي ذلك ملكية الترقية، لا العمل المنفّذ لاحقًا عبر مقبس Plugin قائم.

لا تحفظ هذه المصافحة الرسائل الواردة، ولا توقف وسائل نقل القنوات التابعة لجهات خارجية، ولا تتحكم في منصة الاستضافة. يجب على المضيف عزل حركة الدخول الخاصة به قبل الإعداد، ويظل مسؤولًا عن الإيقاظ واللقطة أو التجميد والإيقاف. يمثّل activeCount العدد الإجمالي للأعمال المتتبعة، بينما يحتوي blockers على أعداد الفئات غير الصفرية وتفاصيل محدودة للمهام. وهذا ليس حاجزًا عامًا لسكون العملية. الحاجب background-exec إجمالي فقط: لا تعبر البروتوكول مطلقًا نصوص الأوامر أو مُعرّفات العمليات أو المخرجات أو مُعرّفات الجلسات أو النطاقات. وقد تظل سلامة القناة والصيانة وتحديث ذاكرة التخزين المؤقت وجلسات ويب سوكيت القائمة الخاصة بالـ Plugins والأعمال الخلفية غير المسجلة والمملوكة للـ Plugins نشطة. يجب على منصة الاستضافة تجميد شجرة العمليات الكاملة ونظام ملفاتها أو أخذ لقطة منهما بشكل متسق؛ ولا يمكن لهذا العقد الأول إثبات خمول العمل غير المسجل.

تعليمات التطبيق البرمجية مقارنة بتعليمات Plugin البرمجية

استخدم Gateway RPC عندما تكون التعليمات البرمجية خارج OpenClaw:

• برامج Node النصية التي تبدأ عمليات تشغيل الوكيل أو تراقبها
• مهام CI التي تستدعي Gateway
• لوحات المعلومات ولوحات الإدارة
• امتدادات IDE
• الجسور الخارجية التي لا تحتاج إلى أن تصبح Plugins للقنوات
• اختبارات التكامل باستخدام وسائل نقل Gateway وهمية أو حقيقية

استخدم Plugin SDK عندما تعمل التعليمات البرمجية داخل OpenClaw:

• Plugins لمزوّدي الخدمة
• Plugins للقنوات
• خطافات الأدوات أو دورة الحياة
• Plugins لأُطر تشغيل الوكلاء
• مساعدات وقت تشغيل موثوقة

ينبغي ألا تستورد التطبيقات الخارجية openclaw/plugin-sdk/*؛ فهذه المسارات الفرعية مخصصة للـ Plugins التي يحمّلها OpenClaw.

ذو صلة

• بروتوكول Gateway
• مرجع Gateway RPC
• أمر الوكيل في CLI
• أمر الرسائل في CLI
• حلقة الوكيل
• بيئات تشغيل الوكيل
• الجلسات
• المهام الخلفية
• وكلاء ACP
• نظرة عامة على Plugin SDK