---
read_when:
    - إنشاء Plugins أصلية لـ OpenClaw أو تصحيح أخطائها
    - فهم نموذج إمكانات Plugin أو حدود الملكية
    - العمل على مسار تحميل الـ Plugin أو السجل
    - تنفيذ خطافات وقت تشغيل المزوّد أو Plugins القنوات
sidebarTitle: Internals
summary: 'البنية الداخلية لـ Plugin: نموذج القدرات والملكية والعقود ومسار التحميل ومساعدات وقت التشغيل'
title: البنية الداخلية للـ Plugin
x-i18n:
    generated_at: "2026-07-12T06:12:06Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 07ab077080285b5b7a93f58f71cd00be62cfd79cdc2cfa40f0e64cc91cc5ac46
    source_path: plugins/architecture.md
    workflow: 16
---

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

<CardGroup cols={2}>
  <Card title="تثبيت Plugins واستخدامها" icon="plug" href="/ar/tools/plugin">
    دليل المستخدم النهائي لإضافة Plugins وتمكينها واستكشاف أخطائها وإصلاحها.
  </Card>
  <Card title="بناء Plugins" icon="rocket" href="/ar/plugins/building-plugins">
    برنامج تعليمي لبناء أول Plugin باستخدام أصغر ملف بيان صالح للعمل.
  </Card>
  <Card title="Plugins القنوات" icon="comments" href="/ar/plugins/sdk-channel-plugins">
    أنشئ Plugin لقناة مراسلة.
  </Card>
  <Card title="Plugins المزوّدين" icon="microchip" href="/ar/plugins/sdk-provider-plugins">
    أنشئ Plugin لمزوّد نماذج.
  </Card>
  <Card title="نظرة عامة على SDK" icon="book" href="/ar/plugins/sdk-overview">
    مرجع خريطة الاستيراد وواجهة API للتسجيل.
  </Card>
</CardGroup>

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

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

| الإمكانية             | طريقة التسجيل                              | أمثلة على Plugins                |
| ---------------------- | ------------------------------------------------ | ------------------------------ |
| استدلال النص         | `api.registerProvider(...)`                      | `anthropic`, `openai`          |
| خلفية استدلال CLI  | `api.registerCliBackend(...)`                    | `anthropic`, `openai`          |
| التضمينات             | `api.registerEmbeddingProvider(...)`             | Plugins متجهات يملكها المزوّد  |
| الكلام                 | `api.registerSpeechProvider(...)`                | `elevenlabs`, `microsoft`      |
| النسخ الفوري | `api.registerRealtimeTranscriptionProvider(...)` | `openai`                       |
| الصوت الفوري         | `api.registerRealtimeVoiceProvider(...)`         | `google`, `openai`             |
| فهم الوسائط    | `api.registerMediaUnderstandingProvider(...)`    | `google`, `openai`             |
| مصدر النصوص المنسوخة     | `api.registerTranscriptSourceProvider(...)`      | `discord`                      |
| توليد الصور       | `api.registerImageGenerationProvider(...)`       | `fal`, `google`, `openai`      |
| توليد الموسيقى       | `api.registerMusicGenerationProvider(...)`       | `fal`, `google`, `minimax`     |
| توليد الفيديو       | `api.registerVideoGenerationProvider(...)`       | `fal`, `google`, `qwen`        |
| جلب الويب              | `api.registerWebFetchProvider(...)`              | `firecrawl`                    |
| البحث في الويب             | `api.registerWebSearchProvider(...)`             | `brave`, `firecrawl`, `google` |
| القناة / المراسلة    | `api.registerChannel(...)`                       | `matrix`, `msteams`            |
| اكتشاف Gateway      | `api.registerGatewayDiscoveryService(...)`       | `bonjour`                      |

<Note>
يُعدّ Plugin الذي لا يسجّل أي إمكانات لكنه يوفّر خطافات أو أدوات أو خدمات اكتشاف أو خدمات خلفية Plugin **قديمًا يعتمد على الخطافات فقط**. لا يزال هذا النمط مدعومًا بالكامل.
</Note>

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

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

| حالة Plugin                                  | الإرشاد                                                                                         |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Plugins الخارجية الحالية                         | حافظ على عمل عمليات التكامل القائمة على الخطافات؛ فهذا هو خط أساس التوافق.                        |
| Plugins المضمّنة/الأصلية الجديدة                        | فضّل التسجيل الصريح للإمكانات على الوصول المباشر الخاص بمورّد أو التصاميم الجديدة المعتمدة على الخطافات فقط. |
| Plugins الخارجية التي تتبنى تسجيل الإمكانات | مسموح بذلك، لكن تعامل مع الأسطح المساعدة الخاصة بالإمكانات على أنها متطورة ما لم تذكر الوثائق أنها مستقرة. |

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

### أشكال Plugins

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

<AccordionGroup>
  <Accordion title="إمكانات بسيطة">
    يسجّل نوع إمكانات واحدًا بالضبط (على سبيل المثال، Plugin خاص بالمزوّد فقط مثل `arcee` أو `chutes`).
  </Accordion>
  <Accordion title="إمكانات هجينة">
    يسجّل أنواعًا متعددة من الإمكانات (على سبيل المثال، يملك `openai` استدلال النص والكلام وفهم الوسائط وتوليد الصور).
  </Accordion>
  <Accordion title="خطافات فقط">
    يسجّل الخطافات فقط (المحددة النوع أو المخصصة)، دون إمكانات أو أدوات أو أوامر أو خدمات.
  </Accordion>
  <Accordion title="دون إمكانات">
    يسجّل أدوات أو أوامر أو خدمات أو مسارات، لكن دون إمكانات.
  </Accordion>
</AccordionGroup>

استخدم `openclaw plugins inspect <id>` لعرض شكل Plugin وتفصيل إمكاناته. راجع [مرجع CLI](/ar/cli/plugins#inspect) للتفاصيل.

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

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

الاتجاه:

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

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

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

| الإشارة                                     | المعنى                                                                                                       |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| **إعداد صالح**                           | يُحلَّل الإعداد بنجاح وتُحلّ Plugins                                                                        |
| **خطافات فقط** (معلومات)                       | لا يسجّل Plugin إلا الخطافات؛ وهو مسار مدعوم، لكنه لم يُرحَّل بعد إلى تسجيل الإمكانات                |
| **`before_agent_start` قديم** (تحذير)     | يستخدم Plugin الخطاف المهمل `before_agent_start` بدلًا من `before_model_resolve`/`before_prompt_build`  |
| **واجهة API قديمة لتضمينات الذاكرة** (تحذير) | يستخدم Plugin غير مضمّن واجهة API القديمة لمزوّد التضمينات الخاصة بالذاكرة بدلًا من `registerEmbeddingProvider` |
| **خطأ حاسم**                             | الإعداد غير صالح أو فشل تحميل Plugin                                                                    |

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

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

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

<Steps>
  <Step title="البيان + الاكتشاف">
    يعثر OpenClaw على Plugins المرشحة من المسارات المضبوطة وجذور مساحة العمل وجذور Plugins العامة وPlugins المضمّنة. يقرأ الاكتشاف أولًا بيانات `openclaw.plugin.json` الأصلية وبيانات الحزم المدعومة.
  </Step>
  <Step title="التمكين + التحقق">
    تقرر النواة ما إذا كان Plugin المكتشف ممكّنًا أو معطّلًا أو محظورًا أو محددًا لخانة حصرية مثل الذاكرة.
  </Step>
  <Step title="التحميل وقت التشغيل">
    تُحمَّل Plugins الأصلية في OpenClaw داخل العملية وتسجّل الإمكانات في سجل مركزي. تُحمَّل حزم JavaScript عبر `require` الأصلي؛ وتمثل ملفات TypeScript المصدرية المحلية التابعة لجهات خارجية خيار Jiti الاحتياطي في حالات الطوارئ. تُطبَّع الحزم المتوافقة إلى سجلات في السجل دون استيراد شيفرة وقت التشغيل.
  </Step>
  <Step title="استهلاك الأسطح">
    تقرأ بقية مكونات OpenClaw السجل لإتاحة الأدوات والقنوات وإعداد المزوّد والخطافات ومسارات HTTP وأوامر CLI والخدمات.
  </Step>
</Steps>

بالنسبة إلى 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](/ar/plugins/architecture-internals#plugin-cache-boundary): تكون بيانات البيان والاكتشاف الوصفية حديثة ما لم يحتفظ المستدعي بلقطة صريحة أو جدول بحث أو سجل بيانات خاص بالتدفق الحالي. لا تُعد ذاكرات التخزين المؤقت المخفية للبيانات الوصفية ومدد TTL المستندة إلى ساعة النظام جزءًا من تحميل Plugin. لا يجوز الاستمرار بعد تحميل الشيفرة أو العناصر المثبّتة فعليًا إلا لذاكرات التخزين المؤقت الخاصة بمحمّل وقت التشغيل والوحدات وعناصر التبعيات.

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

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

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

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

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

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

### 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](/ar/plugins/architecture-internals) للاطلاع على تسلسل بدء التشغيل الكامل.

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

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

وهذا يعني:

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

<AccordionGroup>
  <Accordion title="مزوّد متعدد القدرات">
    يمتلك `google` الاستدلال النصي، وخلفية CLI، والتضمينات، والكلام، والصوت الآني، وفهم الوسائط، وتوليد الصور/الموسيقى/الفيديو، والبحث على الويب. ويمتلك `openai` الاستدلال النصي، والتضمينات، والكلام، والنسخ الآني، والصوت الآني، وفهم الوسائط، وتوليد الصور/الفيديو. ويمتلك `minimax` الاستدلال النصي إلى جانب فهم الوسائط، والكلام، وتوليد الصور/الموسيقى/الفيديو، والبحث على الويب.
  </Accordion>
  <Accordion title="مزوّد أحادي القدرة">
    يمتلك `arcee` و`chutes` الاستدلال النصي فقط؛ ويمتلك `microsoft` الكلام فقط. يمكن أن يظل Plugin المزوّد بهذا النطاق الضيق إلى أن يحتاج إلى تغطية مساحة أوسع من سطح ذلك المزوّد.
  </Accordion>
  <Accordion title="Plugin الميزة">
    يمتلك `voice-call` نقل المكالمات، والأدوات، وCLI، والمسارات، وجسر تدفق الوسائط الخاص بـ Twilio، لكنه يستهلك قدرات الكلام والنسخ الآني والصوت الآني المشتركة بدلًا من استيراد Plugins المزوّدين مباشرةً.
  </Accordion>
</AccordionGroup>

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

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

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

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

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

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

<Steps>
  <Step title="تعريف القدرة">
    عرّف القدرة المفقودة في النواة.
  </Step>
  <Step title="عرضها عبر SDK">
    اعرضها عبر واجهة API/وقت التشغيل الخاصة بـ Plugin بطريقة محددة الأنواع.
  </Step>
  <Step title="ربط المستهلكين">
    اربط القنوات/الميزات بتلك القدرة.
  </Step>
  <Step title="تنفيذات المزوّدين">
    اسمح لـ Plugins المزوّدين بتسجيل التنفيذات.
  </Step>
</Steps>

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

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

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

<Tabs>
  <Tab title="طبقة قدرات النواة">
    التنسيق المشترك، والسياسة، والرجوع الاحتياطي، وقواعد دمج الإعدادات، ودلالات التسليم، والعقود محددة الأنواع.
  </Tab>
  <Tab title="طبقة Plugin المزوّد">
    واجهات API الخاصة بالمزوّد، والمصادقة، وكتالوجات النماذج، وتركيب الكلام، وتوليد الصور، وخلفيات الفيديو، ونقاط نهاية الاستخدام.
  </Tab>
  <Tab title="طبقة Plugin القناة/الميزة">
    تكامل Discord/Slack/voice-call/وغيرها الذي يستهلك قدرات النواة ويعرضها على سطح ما.
  </Tab>
</Tabs>

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

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

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

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

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

```ts
import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry";
import {
  describeImageWithModel,
  transcribeOpenAiCompatibleAudio,
} from "openclaw/plugin-sdk/media-understanding";
import { createPluginBackedWebSearchProvider } from "openclaw/plugin-sdk/provider-web-search";

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

<Steps>
  <Step title="النواة تعرّف العقد">
    تعرّف النواة عقد فهم الوسائط.
  </Step>
  <Step title="Plugins المزوّدين تسجّل">
    تسجّل Plugins المزوّدين `describeImage` و`transcribeAudio` و`describeVideo` حسب الاقتضاء.
  </Step>
  <Step title="المستهلكون يستخدمون السلوك المشترك">
    تستهلك القنوات وPlugins الميزات سلوك النواة المشترك بدلًا من الربط المباشر بشيفرة المزوّد.
  </Step>
</Steps>

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

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

هل تحتاج إلى قائمة تحقق عملية للتنفيذ؟ راجع [دليل القدرات العملي](/ar/plugins/adding-capabilities).

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

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

أهمية ذلك:

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

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

<AccordionGroup>
  <Accordion title="إنفاذ التسجيل في وقت التشغيل">
    يتحقق سجل Plugins من التسجيلات أثناء تحميل Plugins. على سبيل المثال: تؤدي معرّفات المزوّدين المكررة، ومعرّفات مزوّدي الكلام المكررة، والتسجيلات غير الصحيحة إلى إصدار تشخيصات Plugins بدلًا من سلوك غير محدد.
  </Accordion>
  <Accordion title="اختبارات العقود">
    تُلتقط Plugins المضمّنة في سجلات العقود أثناء تشغيل الاختبارات لكي يتمكن OpenClaw من التحقق من الملكية صراحةً. يُستخدم هذا حاليًا لمزوّدي النماذج، ومزوّدي الكلام، ومزوّدي البحث على الويب، وملكية التسجيلات المضمّنة.
  </Accordion>
</AccordionGroup>

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

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

<Tabs>
  <Tab title="العقود الجيدة">
    - مُنمّطة
    - صغيرة
    - خاصة بقدرة معينة
    - مملوكة للنواة
    - قابلة لإعادة الاستخدام بواسطة عدة Plugins
    - قابلة للاستهلاك من القنوات/الميزات دون معرفة بالمورّد

  </Tab>
  <Tab title="العقود السيئة">
    - سياسة خاصة بالمورّد مخفية في النواة
    - منافذ استثنائية مخصصة لـ Plugin واحد تتجاوز السجل
    - وصول شيفرة القناة مباشرةً إلى تنفيذ مورّد
    - كائنات وقت تشغيل مخصصة ليست جزءًا من `OpenClawPluginApi` أو `api.runtime`

  </Tab>
</Tabs>

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

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

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

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

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

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

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

<Note>
**ملاحظة حول الثقة:** يثق `plugins.allow` في **معرّفات Plugins**، وليس في مصدر الشيفرة. يحجب Plugin في مساحة العمل يحمل المعرّف نفسه الخاص بـ Plugin مضمّن النسخة المضمّنة عمدًا عند تمكين Plugin مساحة العمل هذا/إدراجه في قائمة السماح. هذا سلوك طبيعي ومفيد للتطوير المحلي، واختبار التصحيحات، والإصلاحات العاجلة. تُحدَّد الثقة في Plugin المضمّن من لقطة المصدر — ملف البيان والشيفرة الموجودة على القرص وقت التحميل — بدلًا من البيانات الوصفية للتثبيت. لا يمكن لسجل تثبيت تالف أو مستبدل أن يوسّع بصمت سطح الثقة الخاص بـ Plugin مضمّن إلى ما يتجاوز ما يدّعيه المصدر الفعلي.
</Note>

## حدود التصدير

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

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

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

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

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

للاطلاع على مسار التحميل، ونموذج السجل، وخطافات وقت تشغيل المزوّد، ومسارات HTTP الخاصة بـ Gateway، ومخططات أدوات الرسائل، وحل أهداف القنوات، وكتالوجات المزوّدين، وPlugins الخاصة بمحرك السياق، ودليل إضافة قدرة جديدة، راجع [التفاصيل الداخلية لبنية Plugins](/ar/plugins/architecture-internals).

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

- [إنشاء Plugins](/ar/plugins/building-plugins)
- [بيان Plugin](/ar/plugins/manifest)
- [إعداد SDK الخاص بـ Plugin](/ar/plugins/sdk-setup)
