--- read_when: - بناء أو تصحيح أخطاء Pluginات OpenClaw الأصلية - فهم نموذج قدرات Plugin أو حدود الملكية - العمل على مسار تحميل Plugin أو السجل - تنفيذ خطافات وقت تشغيل المزوّد أو Plugins القنوات sidebarTitle: Internals summary: 'الأجزاء الداخلية لـ Plugin: نموذج الإمكانات، والملكية، والعقود، ومسار التحميل، ومساعدات وقت التشغيل' title: الأجزاء الداخلية لـ Plugin x-i18n: generated_at: "2026-05-02T07:35:22Z" model: gpt-5.5 provider: openai source_hash: 138fb962c98f71e29e8b2621ce318336c38a317636d090eb315fed806fc6abda source_path: plugins/architecture.md workflow: 16 --- هذا هو **مرجع البنية العميقة** لنظام 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` | أي Plugin يسجل صفراً من القدرات لكنه يوفّر hooks أو أدوات أو خدمات اكتشاف أو خدمات خلفية هو Plugin **قديم يعتمد على hooks فقط**. لا يزال هذا النمط مدعوماً بالكامل. ### موقف التوافق الخارجي نموذج القدرات موجود في core وتستخدمه Plugins المضمّنة/الأصلية اليوم، لكن توافق Plugins الخارجية ما يزال يحتاج إلى معيار أشد من "إنه مُصدَّر، لذلك فهو مجمّد." | حالة Plugin | الإرشاد | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | Plugins خارجية موجودة | أبقِ التكاملات المستندة إلى hooks عاملة؛ فهذا هو خط أساس التوافق. | | Plugins مضمّنة/أصلية جديدة | فضّل تسجيل القدرات الصريح على الوصول الخاص بالمورّدين أو التصاميم الجديدة المعتمدة على hooks فقط. | | Plugins خارجية تعتمد تسجيل القدرات | مسموح، لكن تعامل مع أسطح المساعدة الخاصة بكل قدرة على أنها متطورة ما لم تضعها الوثائق كواجهات مستقرة. | تسجيل القدرات هو الاتجاه المقصود. تبقى hooks القديمة المسار الأكثر أماناً لتجنب الكسر بالنسبة إلى Plugins الخارجية أثناء الانتقال. ليست كل مسارات المساعدة الفرعية المصدّرة متساوية — فضّل العقود الضيقة الموثقة على صادرات المساعدة العرضية. ### أشكال Plugin يصنف OpenClaw كل Plugin محمّل إلى شكل بناءً على سلوك التسجيل الفعلي لديه (وليس فقط metadata ثابتة): يسجل نوع قدرة واحداً فقط (على سبيل المثال Plugin خاص بالمزوّد فقط مثل `mistral`). يسجل أنواع قدرات متعددة (على سبيل المثال، يملك `openai` استدلال النص والكلام وفهم الوسائط وتوليد الصور). يسجل hooks فقط (مكتوبة أو مخصصة)، ولا يسجل قدرات أو أدوات أو أوامر أو خدمات. يسجل أدوات أو أوامر أو خدمات أو مسارات لكنه لا يسجل قدرات. استخدم `openclaw plugins inspect ` لرؤية شكل Plugin وتفصيل قدراته. راجع [مرجع CLI](/ar/cli/plugins#inspect) للتفاصيل. ### hooks القديمة تبقى hook المسماة `before_agent_start` مدعومة كمسار توافق لـ Plugins التي تعتمد على hooks فقط. لا تزال Plugins القديمة الواقعية تعتمد عليها. الاتجاه: - إبقاؤها عاملة - توثيقها كقديمة - تفضيل `before_model_resolve` لأعمال تجاوز النموذج/المزوّد - تفضيل `before_prompt_build` لأعمال تعديل المطالبة - إزالتها فقط بعد انخفاض الاستخدام الحقيقي وإثبات تغطية fixtures سلامة الترحيل ### إشارات التوافق عند تشغيل `openclaw doctor` أو `openclaw plugins inspect `، قد ترى إحدى هذه التسميات: | الإشارة | المعنى | | -------------------------- | ------------------------------------------------------------ | | **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 من أربع طبقات: يعثر 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](/ar/plugins/architecture-internals#plugin-cache-boundary): تكون 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/` الموسومة باسمه. تبقى هذه الواجهات الموسومة طبقات توافق للـ 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 الداخلية](/ar/plugins/architecture-internals) لمعرفة تسلسل بدء التشغيل الكامل. ## نموذج ملكية القدرات يتعامل OpenClaw مع Plugin أصلي باعتباره حد الملكية لـ **شركة** أو **ميزة**، لا باعتباره مجموعة عشوائية من تكاملات غير مترابطة. هذا يعني: - ينبغي عادة أن يمتلك Plugin الشركة كل الأسطح المواجهة لـ OpenClaw الخاصة بتلك الشركة - ينبغي عادة أن يمتلك Plugin الميزة سطح الميزة الكامل الذي يقدمه - ينبغي للقنوات استهلاك قدرات النواة المشتركة بدلا من إعادة تنفيذ سلوك المزوّد بأسلوب مخصص يمتلك `openai` استدلال النص، والكلام، والصوت الآني، وفهم الوسائط، وتوليد الصور. ويمتلك `google` استدلال النص إضافة إلى فهم الوسائط، وتوليد الصور، والبحث في الويب. ويمتلك `qwen` استدلال النص إضافة إلى فهم الوسائط وتوليد الفيديو. يمتلك `elevenlabs` و`microsoft` الكلام؛ ويمتلك `firecrawl` جلب الويب؛ وتمتلك `minimax` / `mistral` / `moonshot` / `zai` خلفيات فهم الوسائط. يمتلك `voice-call` نقل المكالمات، والأدوات، وCLI، والمسارات، وتجسير تدفق وسائط Twilio، لكنه يستهلك قدرات الكلام المشتركة، والنسخ الآني، والصوت الآني بدلا من استيراد Plugins المزوّدين مباشرة. الحالة النهائية المقصودة هي: - يعيش OpenAI في Plugin واحد حتى لو شمل نماذج نصية وكلاما وصورا وفيديو مستقبليا - يستطيع مزوّد آخر فعل الشيء نفسه لمساحة السطح الخاصة به - لا تهتم القنوات بأي Plugin مزوّد يمتلك المزوّد؛ فهي تستهلك عقد القدرة المشترك الذي تكشفه النواة هذا هو التمييز الأساسي: - **plugin** = حد الملكية - **capability** = عقد النواة الذي يمكن لعدة Plugins تنفيذه أو استهلاكه لذلك، إذا أضاف OpenClaw نطاقا جديدا مثل الفيديو، فالسؤال الأول ليس "أي مزوّد ينبغي أن يرمّز معالجة الفيديو ترميزا ثابتا؟" السؤال الأول هو "ما عقد قدرة الفيديو في النواة؟" ما إن يوجد ذلك العقد، يمكن لـ Plugins المزوّدين التسجيل مقابله ويمكن لـ Plugins القنوات/الميزات استهلاكه. إذا لم تكن القدرة موجودة بعد، فالخطوة الصحيحة عادة هي: عرّف القدرة المفقودة في النواة. اكشفها عبر API/وقت تشغيل Plugin بطريقة ذات أنواع. اربط القنوات/الميزات بتلك القدرة. اسمح لـ Plugins المزوّدين بتسجيل التنفيذات. يبقي هذا الملكية صريحة مع تجنب سلوك في النواة يعتمد على مزوّد واحد أو مسار كود مخصص لـ Plugin واحد. ### طبقات القدرات استخدم هذا النموذج الذهني عند تحديد مكان الكود: التنسيق المشترك، والسياسة، والرجوع الاحتياطي، وقواعد دمج الإعدادات، ودلالات التسليم، والعقود ذات الأنواع. واجهات API الخاصة بالمزوّد، والمصادقة، وكتالوجات النماذج، وتركيب الكلام، وتوليد الصور، وخلفيات الفيديو المستقبلية، ونقاط نهاية الاستخدام. تكامل Slack/Discord/voice-call/إلخ. الذي يستهلك قدرات النواة ويعرضها على سطح. على سبيل المثال، يتبع TTS هذا الشكل: - تمتلك النواة سياسة TTS وقت الرد، وترتيب الرجوع الاحتياطي، والتفضيلات، والتسليم عبر القنوات - يمتلك `openai` و`elevenlabs` و`microsoft` تنفيذات التركيب - يستهلك `voice-call` مساعد وقت تشغيل TTS الهاتفي ينبغي تفضيل النمط نفسه للقدرات المستقبلية. ### مثال Plugin شركة متعدد القدرات ينبغي أن يبدو Plugin الشركة مترابطا من الخارج. إذا كان لدى OpenClaw عقود مشتركة للنماذج، والكلام، والنسخ الآني، والصوت الآني، وفهم الوسائط، وتوليد الصور، وتوليد الفيديو، وجلب الويب، والبحث في الويب، فيمكن لمزوّد أن يمتلك كل أسطحه في مكان واحد: ```ts 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 المزوّدين `describeImage` و`transcribeAudio` و`describeVideo` بحسب الاقتضاء. تستهلك القنوات وPlugins الميزات سلوك النواة المشترك بدلا من الربط مباشرة بكود المزوّد. يتجنب ذلك تضمين افتراضات فيديو خاصة بمزوّد واحد في النواة. يمتلك الـ Plugin سطح المزوّد؛ وتمتلك النواة عقد القدرة وسلوك الرجوع الاحتياطي. يستخدم توليد الفيديو بالفعل التسلسل نفسه: تمتلك النواة عقد القدرة ذا الأنواع ومساعد وقت التشغيل، وتسجّل Plugins المزوّدين تنفيذات `api.registerVideoGenerationProvider(...)` مقابله. هل تحتاج إلى قائمة تحقق طرح ملموسة؟ راجع [دليل وصفات القدرات](/ar/plugins/architecture). ## العقود والإنفاذ سطح 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/` افتراضيًا، أو لاحقة 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](/ar/plugins/architecture-internals). ## ذو صلة - [بناء Plugins](/ar/plugins/building-plugins) - [بيان Plugin](/ar/plugins/manifest) - [إعداد Plugin SDK](/ar/plugins/sdk-setup)