الأجزاء الداخلية لـ Plugin

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

تثبيت Plugins واستخدامها

دليل المستخدم النهائي لإضافة Plugins وتمكينها واستكشاف مشكلاتها وإصلاحها.

بناء Plugins

درس تعليمي لأول Plugin مع أصغر manifest عامل.

Plugins القنوات

ابنِ Plugin لقناة مراسلة.

Plugins المزوّدين

ابنِ Plugin لمزوّد نماذج.

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

مرجع خريطة الاستيراد وواجهة 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`

أي Plugin يسجل صفراً من القدرات لكنه يوفّر hooks أو أدوات أو خدمات اكتشاف أو خدمات خلفية هو Plugin قديم يعتمد على hooks فقط. لا يزال هذا النمط مدعوماً بالكامل.

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

نموذج القدرات موجود في 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 للخطة عن تسميات السبب حتى تتمكن التشخيصات من تمييز التلميحات الصريحة عن بديل الملكية

لا تتعامل مع activation باعتباره خطاف دورة حياة أو بديلا عن register(...). إنه بيانات وصفية تُستخدم لتضييق التحميل. فضّل حقول الملكية عندما تصف العلاقة بالفعل؛ ولا تستخدم activation إلا لتلميحات المخطِّط الإضافية.

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 استدلال النص، والكلام، والصوت الآني، وفهم الوسائط، وتوليد الصور. ويمتلك 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 المزوّد
طبقة Plugin القناة/الميزة

التنسيق المشترك، والسياسة، والرجوع الاحتياطي، وقواعد دمج الإعدادات، ودلالات التسليم، والعقود ذات الأنواع.

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

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

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

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

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

import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry";
import {
  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 الأصلي المحمّل حدود الثقة نفسها على مستوى العملية مثل كود النواة.

آثار Plugin الأصلي: يمكن لـ Plugin تسجيل الأدوات، ومعالجات الشبكة، والخطافات، والخدمات؛ ويمكن لخلل في Plugin أن يتسبب في تعطل Gateway أو زعزعته؛ ويعادل Plugin أصلي خبيث تنفيذ كود عشوائي داخل عملية OpenClaw.

الحزم المتوافقة أكثر أمانًا افتراضيًا لأن OpenClaw يتعامل معها حاليًا كحزم بيانات وصفية/محتوى. في الإصدارات الحالية، يعني ذلك في الغالب Skills المضمّنة. استخدم قوائم السماح ومسارات التثبيت/التحميل الصريحة لـ Plugins غير المضمّنة. تعامل مع Plugins مساحة العمل ككود وقت التطوير، وليس كإعدادات إنتاج افتراضية. لأسماء حزم مساحة العمل المضمّنة، أبقِ معرّف Plugin مثبتًا في اسم npm: @openclaw/<id> افتراضيًا، أو لاحقة typed معتمدة مثل -provider أو -plugin أو -speech أو -sandbox أو -media-understanding عندما تعرض الحزمة عمدًا دور Plugin أضيق.

ملاحظة ثقة: يثق plugins.allow في معرّفات Plugin، وليس في مصدر المنشأ. إن Plugin مساحة عمل يحمل المعرّف نفسه مثل Plugin مضمّن يظلّل عمدًا النسخة المضمّنة عندما يكون Plugin مساحة العمل هذا مفعّلًا/مسموحًا به. هذا طبيعي ومفيد للتطوير المحلي، واختبار التصحيحات، والإصلاحات العاجلة. تُحل ثقة Plugin المضمّن من لقطة المصدر — البيان والكود على القرص وقت التحميل — وليس من بيانات التثبيت الوصفية. لا يمكن لسجل تثبيت تالف أو مستبدل أن يوسّع بصمت سطح ثقة 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.

CLI commands

RPC and API

Codex harness

Plugin reference

Plugin SDK reference

Plugin maintainer reference

Templates

Technical reference

Concept internals

Project

Release and CI

الأجزاء الداخلية لـ Plugin

تثبيت Plugins واستخدامها

بناء Plugins

Plugins القنوات

Plugins المزوّدين

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

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

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

أشكال Plugin

hooks القديمة

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

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

لقطة metadata الخاصة بـ Plugin وجدول البحث

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

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

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

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

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

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

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

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

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

حدّ التصدير

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

ذو صلة

CLI commands

RPC and API

Codex harness

Plugin reference

Plugin SDK reference

Plugin maintainer reference

Templates

Technical reference

Concept internals

Project

Release and CI

Documentation Index

تثبيت Plugins واستخدامها

بناء Plugins

Plugins القنوات

Plugins المزوّدين

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

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

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

​أشكال Plugin

​hooks القديمة

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

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

​لقطة metadata الخاصة بـ Plugin وجدول البحث

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

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

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

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

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

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

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

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

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

​حدّ التصدير

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

​ذو صلة

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

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

أشكال Plugin

hooks القديمة

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

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

لقطة metadata الخاصة بـ Plugin وجدول البحث

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

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

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

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

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

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

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

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

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

حدّ التصدير

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

ذو صلة