البنية الداخلية للـ Plugin

هذا هو المرجع المعماري المتعمّق لنظام Plugin في OpenClaw. للحصول على أدلة عملية، ابدأ بإحدى الصفحات المتخصصة أدناه.

نموذج الإمكانات العام

الإمكانات هي نموذج Plugin الأصلي العام داخل OpenClaw. يُسجَّل كل Plugin أصلي في OpenClaw ضمن نوع واحد أو أكثر من أنواع الإمكانات:

موقف التوافق الخارجي

أُدمج نموذج الإمكانات في النواة وتستخدمه Plugins المضمّنة/الأصلية حاليًا، لكن توافق Plugins الخارجية لا يزال يحتاج إلى معيار أكثر صرامة من «إنه مُصدَّر، ولذلك فهو ثابت».

تسجيل الإمكانات هو الاتجاه المقصود. تظل الخطافات القديمة المسار الأكثر أمانًا لتجنب الأعطال في Plugins الخارجية خلال فترة الانتقال. ليست كل المسارات الفرعية المساعدة المُصدَّرة متساوية — فضّل العقود الضيقة الموثقة على الصادرات المساعدة العرضية.

أشكال Plugins

يصنّف OpenClaw كل Plugin محمّل ضمن شكل يستند إلى سلوك التسجيل الفعلي الخاص به (وليس فقط إلى البيانات الوصفية الثابتة):

استخدم openclaw plugins inspect <id> لعرض شكل Plugin وتفصيل إمكاناته. راجع مرجع CLI للتفاصيل.

الخطافات القديمة

يظل الخطاف before_agent_start مدعومًا بوصفه مسار توافق لـ Plugins التي تعتمد على الخطافات فقط. لا تزال Plugins القديمة المستخدمة فعليًا تعتمد عليه.

الاتجاه:

• إبقاؤه عاملًا
• توثيقه باعتباره قديمًا
• تفضيل before_model_resolve لأعمال تجاوز النموذج/المزوّد
• تفضيل before_prompt_build لأعمال تعديل الموجّه
• عدم إزالته إلا بعد انخفاض الاستخدام الفعلي وإثبات تغطية التركيبات لسلامة الترحيل

إشارات التوافق

تعرض openclaw doctor وopenclaw plugins inspect <id> وopenclaw status --all وopenclaw plugins doctor إشعارات التوافق التالية:

لا تؤدي أي من إشارات الإرشاد/التحذير إلى تعطيل Plugin حاليًا. تظهر هذه الإشارات أيضًا في openclaw status --all وopenclaw plugins doctor.

نظرة عامة على المعمارية

يتكون نظام Plugin في OpenClaw من أربع طبقات:

بالنسبة إلى CLI الخاص بـ Plugins تحديدًا، ينقسم اكتشاف الأوامر الجذرية إلى مرحلتين:

• تأتي البيانات الوصفية في وقت التحليل من registerCli(..., { descriptors: [...] })
• يمكن أن تظل وحدة CLI الفعلية الخاصة بـ Plugin كسولة وأن تُسجَّل عند أول استدعاء

يبقي ذلك شيفرة CLI التي يملكها Plugin داخله، مع السماح لـ OpenClaw بحجز أسماء الأوامر الجذرية قبل التحليل.

حد التصميم المهم:

• يجب أن يعمل التحقق من البيان/الإعداد باستخدام البيانات الوصفية للبيان/المخطط دون تنفيذ شيفرة Plugin
• قد يحمّل اكتشاف الإمكانات الأصلية شيفرة إدخال Plugin موثوق لبناء لقطة غير منشِّطة للسجل
• يأتي سلوك وقت التشغيل الأصلي من مسار register(api) لوحدة Plugin مع api.registrationMode === "full"

يتيح هذا الفصل لـ OpenClaw التحقق من الإعداد، وشرح Plugins المفقودة/المعطّلة، وبناء تلميحات واجهة المستخدم/المخطط قبل تنشيط وقت التشغيل الكامل.

لقطة البيانات الوصفية لـ Plugin وجدول البحث

ينشئ بدء تشغيل Gateway لقطة PluginMetadataSnapshot واحدة للقطة الإعداد الحالية. تقتصر اللقطة على البيانات الوصفية: فهي تخزّن فهرس Plugins المثبّتة وسجل البيانات وسجلات تشخيص البيانات وخرائط الملكية ومطبّع معرّفات Plugins وسجلات البيانات. ولا تحتفظ بوحدات Plugins المحمّلة أو حزم SDK للمزوّدين أو محتويات الحزم أو صادرات وقت التشغيل.

تستهلك عمليات التحقق من الإعداد المدركة لـ Plugins والتمكين التلقائي عند بدء التشغيل وتهيئة Plugins في Gateway هذه اللقطة بدلًا من إعادة بناء البيانات الوصفية للبيانات/الفهرس بشكل مستقل. يُشتق PluginLookUpTable من اللقطة نفسها، ويضيف خطة Plugins لبدء التشغيل الخاصة بإعداد وقت التشغيل الحالي.

بعد بدء التشغيل، يحتفظ Gateway بلقطة البيانات الوصفية الحالية بوصفها ناتجًا قابلًا للاستبدال في وقت التشغيل. يمكن لعمليات اكتشاف المزوّدين المتكررة وقت التشغيل استعارة تلك اللقطة بدلًا من إعادة إنشاء الفهرس المثبّت وسجل البيانات في كل تمريرة لكتالوج المزوّدين. تُمسح اللقطة أو تُستبدل عند إيقاف Gateway، وعند تغيّر الإعداد أو مخزون Plugins، وعند الكتابة إلى الفهرس المثبّت؛ ويعود المستدعون إلى مسار البيانات/الفهرس البارد عند عدم وجود لقطة حالية متوافقة. يجب أن تشمل عمليات التحقق من التوافق جذور اكتشاف Plugins مثل plugins.load.paths ومساحة عمل الوكيل الافتراضية، لأن Plugins مساحة العمل جزء من نطاق البيانات الوصفية.

تحافظ اللقطة وجدول البحث على قرارات بدء التشغيل المتكررة ضمن المسار السريع:

• ملكية القناة
• بدء تشغيل القناة المؤجل
• معرّفات Plugins عند بدء التشغيل
• ملكية المزوّد وخلفية CLI
• ملكية مزوّد الإعداد والاسم المستعار للأمر ومزوّد كتالوج النماذج وعقد البيان
• التحقق من مخطط إعداد Plugin ومخطط إعداد القناة
• قرارات التمكين التلقائي عند بدء التشغيل

حد الأمان هو استبدال اللقطة، وليس تعديلها. أعد بناء اللقطة عندما يتغيّر الإعداد أو مخزون Plugins أو سجلات التثبيت أو سياسة الفهرس الدائم. لا تتعامل معها بوصفها سجلًا عامًا واسعًا قابلًا للتعديل، ولا تحتفظ بلقطات تاريخية غير محدودة. يظل تحميل Plugins وقت التشغيل منفصلًا عن لقطات البيانات الوصفية، حتى لا تُخفى حالة وقت تشغيل قديمة خلف ذاكرة تخزين مؤقت للبيانات الوصفية.

قاعدة التخزين المؤقت موثقة في التفاصيل الداخلية لمعمارية Plugin: تكون بيانات البيان والاكتشاف الوصفية حديثة ما لم يحتفظ المستدعي بلقطة صريحة أو جدول بحث أو سجل بيانات خاص بالتدفق الحالي. لا تُعد ذاكرات التخزين المؤقت المخفية للبيانات الوصفية ومدد TTL المستندة إلى ساعة النظام جزءًا من تحميل Plugin. لا يجوز الاستمرار بعد تحميل الشيفرة أو العناصر المثبّتة فعليًا إلا لذاكرات التخزين المؤقت الخاصة بمحمّل وقت التشغيل والوحدات وعناصر التبعيات.

لا يزال بعض مستدعي المسار البارد يعيدون إنشاء سجلات البيانات مباشرةً من فهرس Plugins المثبّتة الدائم بدلًا من تلقي PluginLookUpTable من Gateway. يعيد هذا المسار الآن إنشاء السجل عند الطلب؛ فضّل تمرير جدول البحث الحالي أو سجل بيانات صريح عبر تدفقات وقت التشغيل عندما يتوفر لدى المستدعي أحدهما بالفعل.

تخطيط التفعيل

يُعد تخطيط التفعيل جزءًا من مستوى التحكم. يمكن للجهات المستدعية الاستعلام عن Plugins ذات الصلة بأمر محدد، أو مزوّد، أو قناة، أو مسار، أو بيئة تشغيل وكيل، أو قدرة، قبل تحميل سجلات وقت التشغيل الأوسع.

يحافظ المخطِّط على توافق سلوك البيان الحالي:

• حقول activation.* هي تلميحات صريحة للمخطِّط
• تظل providers وchannels وcommandAliases وsetup.providers وcontracts.tools والخطافات آلية الرجوع الاحتياطية لملكية البيان
• تظل واجهة API للمخطِّط التي تقتصر على المعرّفات متاحة للجهات المستدعية الحالية
• تعرض واجهة API للخطة تسميات الأسباب كي تتمكن أدوات التشخيص من التمييز بين التلميحات الصريحة والرجوع الاحتياطي إلى الملكية

Plugins القنوات وأداة الرسائل المشتركة

لا تحتاج Plugins القنوات إلى تسجيل أداة منفصلة للإرسال أو التحرير أو التفاعل لإجراءات الدردشة العادية. يحتفظ OpenClaw بأداة message مشتركة واحدة في النواة، وتتولى Plugins القنوات الاكتشاف والتنفيذ الخاصين بكل قناة خلفها.

الحد الفاصل الحالي هو:

• تمتلك النواة مضيف أداة message المشتركة، وربط الموجّه، ومسك دفاتر الجلسات/سلاسل المحادثات، وتوجيه التنفيذ
• تمتلك Plugins القنوات اكتشاف الإجراءات المحددة النطاق، واكتشاف القدرات، وأي أجزاء مخطط خاصة بالقناة
• تمتلك Plugins القنوات قواعد محادثة الجلسة الخاصة بالمزوّد، مثل كيفية تضمين معرّفات المحادثات لمعرّفات سلاسل المحادثات أو وراثتها من المحادثات الأصل
• تنفّذ Plugins القنوات الإجراء النهائي من خلال محوّل الإجراءات الخاص بها

بالنسبة إلى Plugins القنوات، فإن سطح SDK هو ChannelMessageActionAdapter.describeMessageTool(...). تتيح استدعائية الاكتشاف الموحّدة هذه لـ Plugin إعادة إجراءاته المرئية وقدراته ومساهماته في المخطط معًا، بحيث لا تتباعد هذه الأجزاء.

عندما تحمل معلمة خاصة بقناة ضمن أداة الرسائل مصدر وسائط، مثل مسار محلي أو عنوان URL بعيد للوسائط، ينبغي أن يعيد Plugin أيضًا mediaSourceParams من describeMessageTool(...). تستخدم النواة هذه القائمة الصريحة لتطبيق تسوية مسارات صندوق العزل وتلميحات الوصول إلى الوسائط الصادرة من دون ترميز أسماء المعلمات المملوكة لـ Plugin داخلها. فضّل هناك الخرائط المحددة بنطاق الإجراء، لا قائمة مسطحة واحدة على مستوى القناة، حتى لا تخضع معلمة وسائط خاصة بالملف الشخصي للتسوية في إجراءات غير مرتبطة مثل send.

تمرّر النواة نطاق وقت التشغيل إلى خطوة الاكتشاف تلك. تشمل الحقول المهمة:

• accountId
• currentChannelId
• currentThreadTs
• currentMessageId
• sessionKey
• sessionId
• agentId
• requesterSenderId الوارد الموثوق

وهذا مهم لـ Plugins الحساسة للسياق. يمكن للقناة إخفاء إجراءات الرسائل أو إظهارها استنادًا إلى الحساب النشط، أو الغرفة/سلسلة المحادثة/الرسالة الحالية، أو هوية مقدّم الطلب الموثوقة، من دون ترميز فروع خاصة بالقناة داخل أداة message الأساسية.

لهذا السبب تظل تغييرات توجيه المشغّل المضمّن من عمل Plugin: فالمشغّل مسؤول عن تمرير هوية الدردشة/الجلسة الحالية إلى حد اكتشاف Plugin، بحيث تعرض أداة message المشتركة السطح الصحيح المملوك للقناة للدور الحالي.

بالنسبة إلى مساعدات التنفيذ المملوكة للقناة، ينبغي أن تُبقي Plugins المضمّنة وقت تشغيل التنفيذ داخل وحدات Plugin الخاصة بها. لم تعد النواة تمتلك أوقات تشغيل إجراءات الرسائل الخاصة بـ Discord أو Slack أو Telegram أو WhatsApp ضمن src/agents/tools. نحن لا ننشر مسارات فرعية منفصلة من نوع plugin-sdk/*-action-runtime، وينبغي أن تستورد Plugins المضمّنة شيفرة وقت التشغيل المحلية الخاصة بها مباشرةً من وحداتها المملوكة لـ Plugin.

ينطبق الحد الفاصل نفسه على منافذ SDK المسماة بحسب المزوّد عمومًا: ينبغي ألا تستورد النواة حزم تصدير ملائمة خاصة بالقناة لـ Discord أو Signal أو Slack أو WhatsApp أو Plugins مشابهة. إذا احتاجت النواة إلى سلوك ما، فعليها إما استهلاك حزمة التصدير api.ts / runtime-api.ts الخاصة بـ Plugin المضمّن، أو ترقية الحاجة إلى قدرة عامة ضيقة في SDK المشترك.

تتبع Plugins المضمّنة القاعدة نفسها. ينبغي ألا يعيد runtime-api.ts الخاص بـ Plugin مضمّن تصدير واجهته ذات العلامة التجارية openclaw/plugin-sdk/<plugin-id>. تظل هذه الواجهات ذات العلامة التجارية طبقات توافق لـ Plugins الخارجية والمستهلكين الأقدم، لكن ينبغي أن تستخدم Plugins المضمّنة عمليات التصدير المحلية إلى جانب مسارات SDK فرعية عامة وضيقة مثل openclaw/plugin-sdk/channel-policy أو openclaw/plugin-sdk/runtime-store أو openclaw/plugin-sdk/webhook-ingress. ينبغي ألا تضيف الشيفرة الجديدة واجهات SDK خاصة بمعرّف Plugin إلا إذا كان حد التوافق لمنظومة خارجية قائمة يتطلب ذلك.

بالنسبة إلى استطلاعات الرأي تحديدًا، يوجد مسارا تنفيذ:

• يمثّل outbound.sendPoll خط الأساس المشترك للقنوات التي تتوافق مع نموذج استطلاع الرأي العام
• يمثّل actions.handleAction("poll") المسار المفضّل لدلالات استطلاع الرأي الخاصة بالقناة أو معلمات استطلاع الرأي الإضافية

تؤجل النواة الآن تحليل استطلاع الرأي المشترك إلى ما بعد رفض توجيه استطلاع الرأي في Plugin للإجراء، بحيث يمكن لمعالجات استطلاع الرأي المملوكة لـ Plugin قبول حقول استطلاع رأي خاصة بالقناة من دون أن يمنعها محلّل استطلاع الرأي العام أولًا.

راجع البنية الداخلية لمعمارية Plugin للاطلاع على تسلسل بدء التشغيل الكامل.

نموذج ملكية القدرات

يتعامل OpenClaw مع Plugin أصلي بوصفه حد الملكية الخاص بشركة أو بميزة، لا بوصفه تجميعة عشوائية من عمليات التكامل غير المرتبطة.

وهذا يعني:

• ينبغي عادةً أن يمتلك Plugin الشركة جميع أسطح تلك الشركة المواجهة لـ OpenClaw
• ينبغي عادةً أن يمتلك Plugin الميزة كامل سطح الميزة التي يقدمها
• ينبغي أن تستهلك القنوات قدرات النواة المشتركة بدلًا من إعادة تنفيذ سلوك المزوّد بصورة ارتجالية

الحالة النهائية المقصودة هي:

• يعيش سطح المزوّد المواجه لـ OpenClaw في Plugin واحد حتى لو امتد عبر النماذج النصية والكلام والصور والفيديو
• يمكن للمزوّدين الآخرين فعل الشيء نفسه لمساحات أسطحهم الخاصة
• لا تهتم القنوات بأي Plugin مزوّد يمتلك المزوّد؛ بل تستهلك عقد القدرة المشترك الذي تعرضه النواة

هذا هو الفرق الأساسي:

• Plugin = حد الملكية
• القدرة = عقد النواة الذي يمكن لعدة Plugins تنفيذه أو استهلاكه

لذلك، إذا أضاف OpenClaw نطاقًا جديدًا مثل الفيديو، فالسؤال الأول ليس «أي مزوّد ينبغي أن يرمّز معالجة الفيديو داخله؟». بل السؤال الأول هو «ما عقد قدرة الفيديو في النواة؟». بعد وجود هذا العقد، يمكن لـ Plugins المزوّدين التسجيل استنادًا إليه، ويمكن لـ Plugins القنوات/الميزات استهلاكه.

إذا لم تكن القدرة موجودة بعد، فالخطوة الصحيحة عادةً هي:

يحافظ ذلك على وضوح الملكية، مع تجنب سلوك في النواة يعتمد على مزوّد واحد أو مسار شيفرة مخصص لـ Plugin بعينه.

طبقات القدرات

استخدم هذا النموذج الذهني عند تحديد موضع الشيفرة:

على سبيل المثال، يتبع تحويل النص إلى كلام هذا الشكل:

• تمتلك النواة سياسة تحويل النص إلى كلام وقت الرد، وترتيب الرجوع الاحتياطي، والتفضيلات، والتسليم إلى القناة
• يمتلك elevenlabs وgoogle وmicrosoft وopenai تنفيذات التركيب
• يستهلك voice-call مساعد وقت تشغيل تحويل النص إلى كلام للاتصالات الهاتفية

ينبغي تفضيل النمط نفسه للقدرات المستقبلية.

مثال على Plugin شركة متعدد القدرات

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

    describeImageWithModel,  transcribeOpenAiCompatibleAudio,} from "openclaw/plugin-sdk/media-understanding"; const plugin: OpenClawPluginDefinition = {  id: "exampleai",  name: "ExampleAI",  register(api) {    api.registerProvider({      id: "exampleai",      // auth/model catalog/runtime hooks    });     api.registerSpeechProvider({      id: "exampleai",      // vendor speech config — implement the SpeechProviderPlugin interface directly    });     api.registerMediaUnderstandingProvider({      id: "exampleai",      capabilities: ["image", "audio", "video"],      async describeImage(req) {        return describeImageWithModel({          ...req,          provider: "exampleai",        });      },      async transcribeAudio(req) {        return transcribeOpenAiCompatibleAudio({          ...req,          provider: "exampleai",        });      },    });     api.registerWebSearchProvider(      createPluginBackedWebSearchProvider({        id: "exampleai-search",        // credential + fetch logic      }),    );  },}; export default plugin;

ما يهم ليس أسماء المساعدات الدقيقة، بل البنية:

• يمتلك Plugin واحد سطح المزوّد
• تظل النواة مالكة لعقود القدرات
• تستهلك القنوات وPlugins الميزات مساعدات api.runtime.*، لا شيفرة المزوّد
• يمكن لاختبارات العقود التحقق من أن Plugin سجّل القدرات التي يدّعي امتلاكها

مثال على قدرة: فهم الفيديو

يتعامل OpenClaw بالفعل مع فهم الصور/الصوت/الفيديو بوصفه قدرة مشتركة واحدة. وينطبق نموذج الملكية نفسه هنا:

يمنع ذلك تضمين افتراضات الفيديو الخاصة بمزوّد واحد داخل النواة. يمتلك Plugin سطح المزوّد؛ وتمتلك النواة عقد القدرة وسلوك الرجوع الاحتياطي.

يستخدم توليد الفيديو بالفعل التسلسل نفسه: تمتلك النواة عقد القدرة محدد الأنواع ومساعد وقت التشغيل، وتسجّل Plugins المزوّدين تنفيذات api.registerVideoGenerationProvider(...) استنادًا إليه.

هل تحتاج إلى قائمة تحقق عملية للتنفيذ؟ راجع دليل القدرات العملي.

العقود والإنفاذ

سطح واجهة برمجة تطبيقات Plugin مُنمّط ومركزي عمدًا في OpenClawPluginApi. يحدد هذا العقد نقاط التسجيل المدعومة ومساعدات وقت التشغيل التي يمكن أن يعتمد عليها Plugin.

أهمية ذلك:

• يحصل مؤلفو Plugins على معيار داخلي واحد مستقر
• يمكن للنواة رفض ازدواجية الملكية، مثل تسجيل Pluginين لمعرّف المزوّد نفسه
• يمكن لبدء التشغيل إظهار تشخيصات قابلة للتنفيذ للتسجيلات غير الصحيحة
• يمكن لاختبارات العقود فرض ملكية Plugins المضمّنة ومنع الانحراف الصامت

توجد طبقتان للإنفاذ:

الأثر العملي هو أن OpenClaw يعرف مسبقًا أي Plugin يملك أي سطح. وهذا يتيح للنواة والقنوات التكامل بسلاسة، لأن الملكية مُعلنة ومُنمّطة وقابلة للاختبار بدلًا من أن تكون ضمنية.

ما الذي ينتمي إلى العقد

عند الشك، ارفع مستوى التجريد: عرّف القدرة أولًا، ثم اسمح لـ Plugins بالتكامل معها.

نموذج التنفيذ

تعمل Plugins الأصلية في OpenClaw داخل العملية مع Gateway. وهي غير معزولة في بيئة حماية. يمتلك Plugin أصلي محمّل حدود الثقة نفسها على مستوى العملية التي تمتلكها شيفرة النواة.

تكون الحزم المتوافقة أكثر أمانًا افتراضيًا لأن OpenClaw يعاملها حاليًا بوصفها حزم بيانات وصفية/محتوى. وفي الإصدارات الحالية، يعني ذلك غالبًا Skills المضمّنة.

استخدم قوائم السماح ومسارات التثبيت/التحميل الصريحة لـ Plugins غير المضمّنة. تعامل مع Plugins الخاصة بمساحة العمل بوصفها شيفرة لوقت التطوير، لا إعدادات افتراضية للإنتاج.

بالنسبة إلى أسماء حزم مساحة العمل المضمّنة، أبقِ معرّف Plugin مرتبطًا باسم npm: ‏@openclaw/<id> افتراضيًا، أو استخدم لاحقة مُنمّطة معتمدة مثل -provider أو -plugin أو -speech أو -sandbox أو -media-understanding عندما تعرض الحزمة عمدًا دورًا أضيق لـ Plugin.

حدود التصدير

يصدّر OpenClaw القدرات، لا وسائل تسهيل التنفيذ.

أبقِ تسجيل القدرات عامًا. وقلّص تصديرات المساعدات غير التعاقدية:

• المسارات الفرعية للمساعدات الخاصة بـ Plugins المضمّنة
• المسارات الفرعية للبنية التحتية لوقت التشغيل غير المخصصة لتكون واجهة برمجة تطبيقات عامة
• مساعدات التسهيل الخاصة بالمورّد
• مساعدات الإعداد/التهيئة الأولية التي تُعد تفاصيل تنفيذ

تم إيقاف المسارات الفرعية المحجوزة لمساعدات Plugins المضمّنة في خريطة تصدير SDK المُنشأة. أبقِ المساعدات الخاصة بالمالك داخل حزمة Plugin المالكة؛ ولا ترقِّ إلى عقود SDK عامة سوى سلوك المضيف القابل لإعادة الاستخدام، مثل plugin-sdk/gateway-runtime وplugin-sdk/security-runtime وplugin-sdk/plugin-config-runtime.

التفاصيل الداخلية والمرجع

للاطلاع على مسار التحميل، ونموذج السجل، وخطافات وقت تشغيل المزوّد، ومسارات HTTP الخاصة بـ Gateway، ومخططات أدوات الرسائل، وحل أهداف القنوات، وكتالوجات المزوّدين، وPlugins الخاصة بمحرك السياق، ودليل إضافة قدرة جديدة، راجع التفاصيل الداخلية لبنية Plugins.

مواضيع ذات صلة

• إنشاء Plugins
• بيان Plugin
• إعداد SDK الخاص بـ Plugin