آليات Plugin الداخلية

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

نموذج القدرات العام

القدرات هي نموذج Plugin الأصلي العام داخل OpenClaw. كل Plugin أصلي في OpenClaw يسجل نفسه مقابل نوع قدرة واحد أو أكثر:

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

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

تسجيل القدرات هو الاتجاه المقصود. تظل hooks القديمة أكثر مسار آمن بلا كسر لـ Plugins الخارجية أثناء الانتقال. مسارات المساعدات الفرعية المصدّرة ليست كلها متساوية — فضّل العقود الضيقة الموثقة على تصديرات المساعدات العرضية.

أشكال Plugin

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

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

hooks القديمة

يظل hook before_agent_start مدعوما كمسار توافق لـ Plugins المعتمدة على hooks فقط. ما زالت Plugins قديمة مستخدمة فعليا تعتمد عليه.

الاتجاه:

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

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

عند تشغيل openclaw doctor أو openclaw plugins inspect <id>، قد ترى أحد هذه التصنيفات:

لن يكسر hook-only ولا before_agent_start‏ Plugin لديك اليوم: hook-only تنبيه إرشادي، وbefore_agent_start يطلق تحذيرا فقط. تظهر هذه الإشارات أيضا في openclaw status --all وopenclaw plugins doctor.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

قاعدة الذاكرة المؤقتة موثقة في داخليات بنية Plugin: تكون بيانات manifest والاكتشاف الوصفية حديثة ما لم يحتفظ مستدع بلقطة صريحة أو جدول بحث أو سجل manifest للتدفق الحالي. ليست الذاكرات المؤقتة المخفية للبيانات الوصفية ولا TTLs المعتمدة على ساعة الحائط جزءا من تحميل Plugin. فقط ذاكرات التخزين المؤقت لمحمل وقت التشغيل والوحدات وآثار التبعيات يمكن أن تستمر بعد تحميل الكود أو الآثار المثبتة فعليا.

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

تخطيط التنشيط

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

يحافظ المخطط على توافق سلوك manifest الحالي:

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

ينطبق الحد نفسه على منافذ SDK المسماة باسم المزوّد عمومًا: لا ينبغي أن تستورد النواة براميل الملاءمة الخاصة بالقنوات لـ Slack أو Discord أو Signal أو WhatsApp أو الامتدادات المشابهة. إذا احتاجت النواة إلى سلوك ما، فإما أن تستهلك برميل 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 الميزة كامل سطح الميزة الذي يقدمه
• ينبغي أن تستهلك القنوات قدرات النواة المشتركة بدلاً من إعادة تنفيذ سلوك المزوّد بشكل مخصص

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

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

هذا هو التمييز الأساسي:

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

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

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

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

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

استخدم هذا النموذج الذهني عند تحديد مكان الكود:

على سبيل المثال، يتبع TTS هذا الشكل:

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

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

مثال 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({          provider: "exampleai",          model: req.model,          input: req.input,        });      },      async transcribeAudio(req) {        return transcribeOpenAiCompatibleAudio({          provider: "exampleai",          model: req.model,          input: req.input,        });      },    });     api.registerWebSearchProvider(      createPluginBackedWebSearchProvider({        id: "exampleai-search",        // credential + fetch logic      }),    );  },}; export default plugin;

ما يهم ليس أسماء المساعدات الدقيقة. الشكل هو المهم:

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

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

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

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

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

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

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

سطح واجهة Plugin API مكتوب الأنواع ومركزي عمدًا في 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 القدرات، لا وسائل الراحة في التنفيذ.

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

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

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

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

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

ذات صلة

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