Plugins
الأجزاء الداخلية لـ Plugin
هذا هو مرجع البنية العميقة لنظام Plugin في OpenClaw. للأدلة العملية، ابدأ بإحدى الصفحات المركزة أدناه.
دليل المستخدم النهائي لإضافة Plugins وتمكينها واستكشاف مشكلاتها وإصلاحها.
درس تعليمي لأول Plugin مع أصغر manifest عامل.
ابنِ Plugin لقناة مراسلة.
ابنِ Plugin لمزوّد نماذج.
مرجع خريطة الاستيراد وواجهة API للتسجيل.
نموذج القدرات العام
القدرات هي نموذج Plugin الأصلي العام داخل OpenClaw. يسجل كل Plugin أصلي في OpenClaw نفسه مقابل نوع واحد أو أكثر من أنواع القدرات:
| القدرة | طريقة التسجيل | أمثلة Plugins |
|---|---|---|
| استدلال النص | api.registerProvider(...) |
openai, anthropic |
| خلفية استدلال CLI | api.registerCliBackend(...) |
openai, anthropic |
| الكلام | api.registerSpeechProvider(...) |
elevenlabs, microsoft |
| النسخ الفوري | api.registerRealtimeTranscriptionProvider(...) |
openai |
| الصوت الفوري | api.registerRealtimeVoiceProvider(...) |
openai |
| فهم الوسائط | api.registerMediaUnderstandingProvider(...) |
openai, google |
| توليد الصور | api.registerImageGenerationProvider(...) |
openai, google, fal, minimax |
| توليد الموسيقى | api.registerMusicGenerationProvider(...) |
google, minimax |
| توليد الفيديو | api.registerVideoGenerationProvider(...) |
qwen |
| جلب الويب | api.registerWebFetchProvider(...) |
firecrawl |
| بحث الويب | api.registerWebSearchProvider(...) |
google |
| القناة / المراسلة | api.registerChannel(...) |
msteams, matrix |
| اكتشاف Gateway | api.registerGatewayDiscoveryService(...) |
bonjour |
موقف التوافق الخارجي
نموذج القدرات موجود في core وتستخدمه Plugins المضمّنة/الأصلية اليوم، لكن توافق Plugins الخارجية ما يزال يحتاج إلى معيار أشد من "إنه مُصدَّر، لذلك فهو مجمّد."
| حالة Plugin | الإرشاد |
|---|---|
| Plugins خارجية موجودة | أبقِ التكاملات المستندة إلى hooks عاملة؛ فهذا هو خط أساس التوافق. |
| Plugins مضمّنة/أصلية جديدة | فضّل تسجيل القدرات الصريح على الوصول الخاص بالمورّدين أو التصاميم الجديدة المعتمدة على hooks فقط. |
| Plugins خارجية تعتمد تسجيل القدرات | مسموح، لكن تعامل مع أسطح المساعدة الخاصة بكل قدرة على أنها متطورة ما لم تضعها الوثائق كواجهات مستقرة. |
تسجيل القدرات هو الاتجاه المقصود. تبقى hooks القديمة المسار الأكثر أماناً لتجنب الكسر بالنسبة إلى Plugins الخارجية أثناء الانتقال. ليست كل مسارات المساعدة الفرعية المصدّرة متساوية — فضّل العقود الضيقة الموثقة على صادرات المساعدة العرضية.
أشكال Plugin
يصنف OpenClaw كل Plugin محمّل إلى شكل بناءً على سلوك التسجيل الفعلي لديه (وليس فقط metadata ثابتة):
plain-capability
يسجل نوع قدرة واحداً فقط (على سبيل المثال Plugin خاص بالمزوّد فقط مثل mistral).
hybrid-capability
يسجل أنواع قدرات متعددة (على سبيل المثال، يملك openai استدلال النص والكلام وفهم الوسائط وتوليد الصور).
hook-only
يسجل hooks فقط (مكتوبة أو مخصصة)، ولا يسجل قدرات أو أدوات أو أوامر أو خدمات.
non-capability
يسجل أدوات أو أوامر أو خدمات أو مسارات لكنه لا يسجل قدرات.
استخدم 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>، قد ترى إحدى هذه التسميات:
| الإشارة | المعنى |
|---|---|
| config valid | يتم تحليل config بشكل سليم ويتم حل Plugins |
| compatibility advisory | يستخدم Plugin نمطاً مدعوماً لكنه أقدم (مثل hook-only) |
| legacy warning | يستخدم Plugin before_agent_start، وهي مهجورة |
| hard error | config غير صالحة أو فشل تحميل Plugin |
لن يكسر hook-only ولا before_agent_start Plugin الخاص بك اليوم: hook-only إرشادي، وbefore_agent_start لا يطلق إلا تحذيراً. تظهر هذه الإشارات أيضاً في openclaw status --all وopenclaw plugins doctor.
نظرة عامة على البنية
يتكون نظام Plugin في OpenClaw من أربع طبقات:
Manifest + الاكتشاف
يعثر OpenClaw على Plugins مرشحة من المسارات المكوّنة وجذور مساحات العمل وجذور Plugins العامة وPlugins المضمّنة. يقرأ الاكتشاف manifests الأصلية openclaw.plugin.json بالإضافة إلى manifests الحزم المدعومة أولاً.
التمكين + التحقق
يقرر core ما إذا كان Plugin المكتشف ممكناً أو معطلاً أو محظوراً أو محدداً لخانة حصرية مثل الذاكرة.
تحميل وقت التشغيل
يتم تحميل Plugins الأصلية في OpenClaw داخل العملية وتسجل القدرات في registry مركزي. تُحمّل JavaScript المعبأة عبر require الأصلية؛ أما TypeScript المصدر المحلي التابع لجهة خارجية فهو مسار Jiti الاحتياطي الطارئ. تُطبّع الحزم المتوافقة إلى سجلات registry بدون استيراد كود وقت التشغيل.
استهلاك السطوح
يقرأ بقية OpenClaw من registry لكشف الأدوات والقنوات وإعداد المزوّدين وhooks ومسارات HTTP وأوامر CLI والخدمات.
بالنسبة إلى CLI الخاص بـ Plugin تحديداً، ينقسم اكتشاف أمر الجذر إلى مرحلتين:
- تأتي metadata وقت التحليل من
registerCli(..., { descriptors: [...] }) - يمكن أن تبقى وحدة CLI الحقيقية الخاصة بـ Plugin كسولة وتسجل عند الاستدعاء الأول
هذا يبقي كود CLI المملوك لـ Plugin داخل Plugin مع السماح لـ OpenClaw بحجز أسماء أوامر الجذر قبل التحليل.
حد التصميم المهم:
- يجب أن يعمل تحقق manifest/config من metadata المخطط/manifest بدون تنفيذ كود Plugin
- قد يحمّل اكتشاف القدرات الأصلية كود إدخال Plugin موثوقاً لبناء لقطة registry غير مُفعِّلة
- يأتي سلوك وقت التشغيل الأصلي من مسار
register(api)الخاص بوحدة Plugin معapi.registrationMode === "full"
يسمح هذا الفصل لـ OpenClaw بالتحقق من config، وشرح Plugins المفقودة/المعطلة، وبناء تلميحات UI/schema قبل أن يصبح وقت التشغيل الكامل نشطاً.
لقطة metadata الخاصة بـ Plugin وجدول البحث
يبني بدء Gateway لقطة PluginMetadataSnapshot واحدة للقطات config الحالية. اللقطة metadata فقط: تخزن فهرس Plugins المثبتة وregistry الخاص بـ manifests وتشخيصات manifest وخرائط المالك ومطبّع معرف Plugin وسجلات manifest. لا تحتفظ بوحدات Plugin المحمّلة أو SDKs المزوّدين أو محتويات الحزم أو صادرات وقت التشغيل.
يستهلك تحقق config الواعي بـ Plugin، والتمكين التلقائي عند بدء التشغيل، وتهيئة Plugin في Gateway تلك اللقطة بدلاً من إعادة بناء metadata الخاصة بـ manifest/index بشكل مستقل. يُشتق PluginLookUpTable من اللقطة نفسها ويضيف خطة Plugins عند بدء التشغيل لـ config وقت التشغيل الحالي.
بعد بدء التشغيل، يحتفظ Gateway بلقطة metadata الحالية كمنتج وقت تشغيل قابل للاستبدال. يمكن لاكتشاف مزوّدي وقت التشغيل المتكرر أن يستعير تلك اللقطة بدلاً من إعادة بناء الفهرس المثبت وregistry الخاص بـ manifest لكل تمرير على كتالوج المزوّدين. تُمسح اللقطة أو تُستبدل عند إيقاف Gateway، وتغييرات config/مخزون Plugins، وكتابات الفهرس المثبت؛ ويرجع المستدعون إلى مسار manifest/index البارد عندما لا توجد لقطة حالية متوافقة. يجب أن تتضمن فحوصات التوافق جذور اكتشاف Plugins مثل plugins.load.paths ومساحة عمل الوكيل الافتراضية، لأن Plugins مساحة العمل جزء من نطاق metadata.
تحافظ اللقطة وجدول البحث على قرارات بدء التشغيل المتكررة في المسار السريع:
- ملكية القنوات
- بدء تشغيل القنوات المؤجل
- معرفات Plugins عند بدء التشغيل
- ملكية المزوّد وخلفية CLI
- ملكية مزوّد الإعداد، والاسم المستعار للأمر، ومزوّد كتالوج النماذج، وعقد manifest
- التحقق من مخطط config الخاص بـ Plugin ومخطط config الخاص بالقناة
- قرارات التمكين التلقائي عند بدء التشغيل
حد السلامة هو استبدال اللقطة، لا تعديلها. أعد بناء اللقطة عندما يتغير config أو مخزون Plugins أو سجلات التثبيت أو سياسة الفهرس المستمرة. لا تعاملها كـ registry عام واسع قابل للتعديل، ولا تحتفظ بلقطات تاريخية غير محدودة. يظل تحميل Plugin وقت التشغيل منفصلاً عن لقطات metadata حتى لا يمكن إخفاء حالة وقت تشغيل قديمة خلف ذاكرة metadata مؤقتة.
تم توثيق قاعدة التخزين المؤقت في الأجزاء الداخلية لبنية Plugin: تكون metadata الخاصة بـ manifest والاكتشاف حديثة ما لم يحتفظ مستدعٍ بلقطة صريحة أو جدول بحث أو registry manifest للتدفق الحالي. ليست ذاكرات metadata المؤقتة المخفية ولا TTLs المعتمدة على ساعة الحائط جزءاً من تحميل Plugin. وحدها ذاكرات التخزين المؤقت لمحمل وقت التشغيل والوحدات وأدوات اعتماد dependencies يمكن أن تستمر بعد تحميل الكود أو artifacts المثبتة فعلياً.
ما يزال بعض مستدعي المسار البارد يعيدون بناء registries الخاصة بـ manifest مباشرة من فهرس Plugins المثبتة المستمر بدلاً من تلقي PluginLookUpTable من Gateway. يعيد ذلك المسار الآن بناء registry عند الطلب؛ فضّل تمرير جدول البحث الحالي أو registry manifest صريح عبر تدفقات وقت التشغيل عندما يكون أحدهما متاحاً بالفعل لدى المستدعي.
تخطيط التفعيل
تخطيط التفعيل جزء من مستوى التحكم. يمكن للمستدعين السؤال عن Plugins ذات الصلة بأمر أو مزوّد أو قناة أو مسار أو حزام وكيل أو قدرة محددة قبل تحميل registries وقت تشغيل أوسع.
يحافظ المخطط على توافق سلوك manifest الحالي:
- حقول
activation.*هي تلميحات صريحة للمخطط - تبقى
providersوchannelsوcommandAliasesوsetup.providersوcontracts.toolsوhooks كبديل لملكية manifest - تبقى واجهة API للمخطط المعتمدة على المعرفات فقط متاحة للمستدعين الموجودين
- تبلّغ واجهة API للخطة عن تسميات السبب حتى تتمكن التشخيصات من تمييز التلميحات الصريحة عن بديل الملكية
Plugins القنوات وأداة الرسائل المشتركة
لا تحتاج Plugins القنوات إلى تسجيل أداة منفصلة للإرسال/التحرير/التفاعل لإجراءات الدردشة العادية. يحتفظ OpenClaw بأداة message مشتركة واحدة في النواة، وتمتلك Plugins القنوات الاكتشاف والتنفيذ الخاصين بالقناة خلفها.
الحد الحالي هو:
- تمتلك النواة مضيف أداة
messageالمشتركة، وتوصيل الموجّه، ومسك دفاتر الجلسات/المحادثات، وتوجيه التنفيذ - تمتلك Plugins القنوات اكتشاف الإجراءات محدود النطاق، واكتشاف القدرات، وأي أجزاء مخطط خاصة بالقناة
- تمتلك Plugins القنوات قواعد محادثة الجلسة الخاصة بالمزوّد، مثل كيفية ترميز معرّفات المحادثات لمعرّفات السلاسل أو وراثتها من المحادثات الأصلية
- تنفّذ Plugins القنوات الإجراء النهائي من خلال محوّل الإجراءات الخاص بها
بالنسبة إلى Plugins القنوات، يكون سطح SDK هو ChannelMessageActionAdapter.describeMessageTool(...). تتيح مكالمة الاكتشاف الموحّدة تلك للـ Plugin إرجاع إجراءاته المرئية وقدراته ومساهماته في المخطط معا، بحيث لا تنحرف هذه الأجزاء عن بعضها.
عندما يحمل وسيط أداة الرسائل الخاص بقناة مصدر وسائط مثل مسار محلي أو عنوان URL لوسائط بعيدة، ينبغي للـ Plugin أيضا إرجاع mediaSourceParams من describeMessageTool(...). تستخدم النواة هذه القائمة الصريحة لتطبيق تطبيع مسارات صندوق الرمل وتلميحات الوصول إلى الوسائط الصادرة من دون ترميز أسماء الوسائط التي يمتلكها الـ Plugin ترميزا ثابتا. فضّل الخرائط محدودة النطاق بحسب الإجراء هناك، لا قائمة مسطحة واحدة على مستوى القناة، حتى لا يجري تطبيع وسيط وسائط خاص بالملف الشخصي فقط على إجراءات غير مرتبطة مثل send.
تمرّر النواة نطاق وقت التشغيل إلى خطوة الاكتشاف تلك. تتضمن الحقول المهمة:
accountIdcurrentChannelIdcurrentThreadTscurrentMessageIdsessionKeysessionIdagentIdrequesterSenderIdوارد موثوق
هذا مهم للـ 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 استدلال النص، والكلام، والصوت الآني، وفهم الوسائط، وتوليد الصور. ويمتلك google استدلال النص إضافة إلى فهم الوسائط، وتوليد الصور، والبحث في الويب. ويمتلك qwen استدلال النص إضافة إلى فهم الوسائط وتوليد الفيديو.
مزوّد أحادي القدرة
يمتلك elevenlabs وmicrosoft الكلام؛ ويمتلك firecrawl جلب الويب؛ وتمتلك minimax / mistral / moonshot / zai خلفيات فهم الوسائط.
Plugin ميزة
يمتلك voice-call نقل المكالمات، والأدوات، وCLI، والمسارات، وتجسير تدفق وسائط Twilio، لكنه يستهلك قدرات الكلام المشتركة، والنسخ الآني، والصوت الآني بدلا من استيراد Plugins المزوّدين مباشرة.
الحالة النهائية المقصودة هي:
- يعيش OpenAI في Plugin واحد حتى لو شمل نماذج نصية وكلاما وصورا وفيديو مستقبليا
- يستطيع مزوّد آخر فعل الشيء نفسه لمساحة السطح الخاصة به
- لا تهتم القنوات بأي Plugin مزوّد يمتلك المزوّد؛ فهي تستهلك عقد القدرة المشترك الذي تكشفه النواة
هذا هو التمييز الأساسي:
- plugin = حد الملكية
- capability = عقد النواة الذي يمكن لعدة Plugins تنفيذه أو استهلاكه
لذلك، إذا أضاف OpenClaw نطاقا جديدا مثل الفيديو، فالسؤال الأول ليس "أي مزوّد ينبغي أن يرمّز معالجة الفيديو ترميزا ثابتا؟" السؤال الأول هو "ما عقد قدرة الفيديو في النواة؟" ما إن يوجد ذلك العقد، يمكن لـ Plugins المزوّدين التسجيل مقابله ويمكن لـ Plugins القنوات/الميزات استهلاكه.
إذا لم تكن القدرة موجودة بعد، فالخطوة الصحيحة عادة هي:
تعريف القدرة
عرّف القدرة المفقودة في النواة.
كشفها عبر SDK
اكشفها عبر API/وقت تشغيل Plugin بطريقة ذات أنواع.
ربط المستهلكين
اربط القنوات/الميزات بتلك القدرة.
تنفيذات المزوّدين
اسمح لـ Plugins المزوّدين بتسجيل التنفيذات.
يبقي هذا الملكية صريحة مع تجنب سلوك في النواة يعتمد على مزوّد واحد أو مسار كود مخصص لـ Plugin واحد.
طبقات القدرات
استخدم هذا النموذج الذهني عند تحديد مكان الكود:
طبقة قدرة النواة
التنسيق المشترك، والسياسة، والرجوع الاحتياطي، وقواعد دمج الإعدادات، ودلالات التسليم، والعقود ذات الأنواع.
طبقة Plugin المزوّد
واجهات API الخاصة بالمزوّد، والمصادقة، وكتالوجات النماذج، وتركيب الكلام، وتوليد الصور، وخلفيات الفيديو المستقبلية، ونقاط نهاية الاستخدام.
طبقة Plugin القناة/الميزة
تكامل Slack/Discord/voice-call/إلخ. الذي يستهلك قدرات النواة ويعرضها على سطح.
على سبيل المثال، يتبع 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 بالفعل مع فهم الصور/الصوت/الفيديو باعتباره قدرة مشتركة واحدة. ينطبق نموذج الملكية نفسه هناك:
النواة تعرّف العقد
تعرّف النواة عقد فهم الوسائط.
Plugins المزوّدين تسجّل
تسجّل Plugins المزوّدين describeImage وtranscribeAudio وdescribeVideo بحسب الاقتضاء.
المستهلكون يستخدمون السلوك المشترك
تستهلك القنوات وPlugins الميزات سلوك النواة المشترك بدلا من الربط مباشرة بكود المزوّد.
يتجنب ذلك تضمين افتراضات فيديو خاصة بمزوّد واحد في النواة. يمتلك الـ Plugin سطح المزوّد؛ وتمتلك النواة عقد القدرة وسلوك الرجوع الاحتياطي.
يستخدم توليد الفيديو بالفعل التسلسل نفسه: تمتلك النواة عقد القدرة ذا الأنواع ومساعد وقت التشغيل، وتسجّل Plugins المزوّدين تنفيذات api.registerVideoGenerationProvider(...) مقابله.
هل تحتاج إلى قائمة تحقق طرح ملموسة؟ راجع دليل وصفات القدرات.
العقود والإنفاذ
سطح API الخاص بالـ Plugin مضبوط الأنواع ومركزي عمدا في OpenClawPluginApi. يعرّف ذلك العقد نقاط التسجيل المدعومة ومساعدات وقت التشغيل التي قد يعتمد عليها الـ Plugin.
لماذا هذا مهم:
- يحصل مؤلفو Plugins على معيار داخلي ثابت واحد
- تستطيع النواة رفض الملكية المكررة مثل تسجيل Pluginين لمعرّف المزوّد نفسه
- يستطيع بدء التشغيل إظهار تشخيصات قابلة للتنفيذ للتسجيل المشوّه
- تستطيع اختبارات العقود إنفاذ ملكية Plugins المضمّنة ومنع الانحراف الصامت
هناك طبقتان من الإنفاذ:
فرض تسجيل وقت التشغيل
يتحقق سجل Plugins من التسجيلات أثناء تحميل Plugins. أمثلة: معرّفات مقدمي الخدمة المكررة، ومعرّفات مقدمي خدمة الكلام المكررة، والتسجيلات غير الصحيحة تنتج تشخيصات Plugin بدلاً من سلوك غير محدد.
اختبارات العقد
تُلتقط Plugins المضمّنة في سجلات العقود أثناء تشغيل الاختبارات حتى يتمكن OpenClaw من تأكيد الملكية صراحة. يُستخدم هذا اليوم لمقدمي النماذج، ومقدمي الكلام، ومقدمي البحث على الويب، وملكية التسجيل المضمّنة.
الأثر العملي هو أن OpenClaw يعرف مسبقًا أي Plugin يملك أي سطح. يتيح ذلك للنواة والقنوات التركيب بسلاسة لأن الملكية مُعلنة ومحددة الأنواع وقابلة للاختبار بدلاً من أن تكون ضمنية.
ما الذي ينتمي إلى عقد
العقود الجيدة
- محددة الأنواع
- صغيرة
- خاصة بالإمكانات
- مملوكة للنواة
- قابلة لإعادة الاستخدام بواسطة عدة Plugins
- قابلة للاستهلاك بواسطة القنوات/الميزات دون معرفة بالمورّد
العقود السيئة
- سياسة خاصة بالمورّد مخفية في النواة
- منافذ هروب Plugin أحادية الاستخدام تتجاوز السجل
- كود قناة يصل مباشرة إلى تنفيذ مورّد
- كائنات وقت تشغيل مخصصة ليست جزءًا من
OpenClawPluginApiأوapi.runtime
عند الشك، ارفع مستوى التجريد: عرّف الإمكانية أولاً، ثم دع Plugins تتصل بها.
نموذج التنفيذ
تعمل Plugins الأصلية في OpenClaw داخل العملية مع Gateway. وهي غير معزولة في بيئة محمية. يمتلك Plugin الأصلي المحمّل حدود الثقة نفسها على مستوى العملية مثل كود النواة.
الحزم المتوافقة أكثر أمانًا افتراضيًا لأن OpenClaw يتعامل معها حاليًا كحزم بيانات وصفية/محتوى. في الإصدارات الحالية، يعني ذلك في الغالب Skills المضمّنة.
استخدم قوائم السماح ومسارات التثبيت/التحميل الصريحة لـ Plugins غير المضمّنة. تعامل مع Plugins مساحة العمل ككود وقت التطوير، وليس كإعدادات إنتاج افتراضية.
لأسماء حزم مساحة العمل المضمّنة، أبقِ معرّف Plugin مثبتًا في اسم npm: @openclaw/<id> افتراضيًا، أو لاحقة typed معتمدة مثل -provider أو -plugin أو -speech أو -sandbox أو -media-understanding عندما تعرض الحزمة عمدًا دور Plugin أضيق.
حدّ التصدير
يصدّر OpenClaw الإمكانات، وليس سهولة التنفيذ.
أبقِ تسجيل الإمكانات عامًا. قلّص صادرات المساعدين غير العقدية:
- مسارات فرعية لمساعدين خاصين بـ Plugin مضمّن
- مسارات فرعية لسباكة وقت التشغيل غير المقصودة كواجهة API عامة
- مساعدون ملائمون خاصون بالمورّد
- مساعدو الإعداد/التجهيز الذين يمثلون تفاصيل تنفيذ
تقاعدت المسارات الفرعية المحجوزة لمساعدي Plugin المضمّن من خريطة تصدير SDK المولّدة. أبقِ المساعدين الخاصين بالمالك داخل حزمة Plugin المالكة؛ ولا ترقِّ إلا سلوك المضيف القابل لإعادة الاستخدام إلى عقود SDK عامة مثل plugin-sdk/gateway-runtime وplugin-sdk/security-runtime وplugin-sdk/plugin-config-runtime.
التفاصيل الداخلية والمرجع
للاطلاع على مسار التحميل، ونموذج السجل، وخطافات وقت تشغيل المزوّد، ومسارات HTTP في Gateway، ومخططات أداة الرسائل، وحل أهداف القنوات، وفهارس المزوّدين، وPlugins محرك السياق، ودليل إضافة إمكانية جديدة، راجع التفاصيل الداخلية لمعمارية Plugin.