---
read_when:
    - بناء Plugins أصلية في OpenClaw أو تصحيح أخطائها
    - فهم نموذج إمكانات Plugin أو حدود الملكية
    - العمل على خط أنابيب تحميل Plugin أو السجل
    - تنفيذ hooks وقت التشغيل الخاصة بالمزوّد أو Plugins القنوات
sidebarTitle: Internals
summary: 'الجوانب الداخلية لـ Plugin: نموذج الإمكانات، والملكية، والعقود، وخط أنابيب التحميل، ومساعدات وقت التشغيل'
title: الجوانب الداخلية لـ Plugin
x-i18n:
  refreshed_at: '2026-04-28T05:23:26Z'
  generated_at: "2026-04-26T11:35:20Z"
  model: gpt-5.4
  provider: openai
  source_hash: 16664d284a8bfbfcb9914bb012d1f36dfdd60406636d6bf4b011f76e886cb518
  source_path: plugins/architecture.md
  workflow: 15
---

هذه هي **المرجع المعماري العميق** لنظام Plugins في 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 الأول مع أصغر manifest عملي.
  </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">
    مرجع import map وAPI التسجيل.
  </Card>
</CardGroup>

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

الإمكانات هي النموذج العام لـ **Plugins الأصلية** داخل 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`                            |

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

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

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

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

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

### أشكال Plugin

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

<AccordionGroup>
  <Accordion title="plain-capability">
    تسجل نوع قدرة واحدًا بالضبط (مثل Plugin خاصة بمزوّد فقط مثل `mistral`).
  </Accordion>
  <Accordion title="hybrid-capability">
    تسجل أنواع قدرات متعددة (مثل `openai` التي تملك الاستدلال النصي، والكلام، وفهم الوسائط، وإنشاء الصور).
  </Accordion>
  <Accordion title="hook-only">
    تسجل hooks فقط (مكتوبة النوع أو مخصصة)، من دون قدرات أو أدوات أو أوامر أو خدمات.
  </Accordion>
  <Accordion title="non-capability">
    تسجل أدوات أو أوامر أو خدمات أو مسارات لكن من دون قدرات.
  </Accordion>
</AccordionGroup>

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

### hooks القديمة

لا يزال hook ‏`before_agent_start` مدعومًا كمسار توافق لـ Plugins من نوع hook-only. ولا تزال Plugins قديمة حقيقية تعتمد عليه.

الاتجاه:

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

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

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

| الإشارة | المعنى |
| -------------------------- | ------------------------------------------------------------ |
| **config valid**           | يُحلَّل التكوين بشكل صحيح وتُحل Plugins                       |
| **compatibility advisory** | تستخدم Plugin نمطًا مدعومًا لكنه أقدم (مثل `hook-only`) |
| **legacy warning**         | تستخدم Plugin ‏`before_agent_start`، وهو مهمل        |
| **hard error**             | التكوين غير صالح أو فشل تحميل Plugin                   |

لن تؤدي `hook-only` ولا `before_agent_start` إلى كسر Plugin لديك اليوم: فـ `hook-only` إشارة استشارية، و`before_agent_start` لا يؤدي إلا إلى تحذير. كما تظهر هذه الإشارات أيضًا في `openclaw status --all` و`openclaw plugins doctor`.

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

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

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

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

- تأتي البيانات الوصفية وقت التحليل من `registerCli(..., { descriptors: [...] })`
- ويمكن أن تظل وحدة CLI الحقيقية الخاصة بالـ Plugin كسولة وتُسجَّل عند أول استدعاء

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

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

- يجب أن يعمل التحقق من manifest/config من **البيانات الوصفية للـ manifest/schema** من دون تنفيذ شيفرة Plugin
- قد يؤدي اكتشاف القدرات الأصلية إلى تحميل شيفرة إدخال Plugin موثوقة لبناء لقطة سجل غير مفعَّلة
- يأتي السلوك الأصلي في وقت التشغيل من مسار وحدة Plugin ‏`register(api)` مع `api.registrationMode === "full"`

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

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

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

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

- تمثل الحقول `activation.*` تلميحات صريحة للمخطط
- تظل `providers` و`channels` و`commandAliases` و`setup.providers` و`contracts.tools` وhooks بمثابة رجوع ملكية للـ manifest
- يبقى API الخاص بالمخطط المعتمد على المعرّفات فقط متاحًا للمستدعين الحاليين
- يبلّغ plan API عن تسميات الأسباب حتى تتمكن التشخيصات من التمييز بين التلميحات الصريحة والرجوع إلى الملكية

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

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

لا تحتاج Plugins القنوات إلى تسجيل أداة إرسال/تعديل/تفاعل منفصلة لأعمال الدردشة العادية. إذ يحتفظ OpenClaw بأداة `message` مشتركة واحدة في core، بينما تمتلك Plugins القنوات آليات الاكتشاف والتنفيذ الخاصة بالقناة خلفها.

الحد الحالي هو:

- يملك core المضيف المشترك لأداة `message`، وربط المطالبة، وإدارة الجلسة/الخيط، وتوجيه التنفيذ
- تملك Plugins القنوات اكتشاف الإجراءات ضمن النطاق، واكتشاف الإمكانات، وأي أجزاء schema خاصة بالقناة
- تملك Plugins القنوات قواعد لغة المحادثة الخاصة بالمزوّد في الجلسة، مثل كيفية ترميز معرّفات المحادثات لمعرّفات الخيوط أو وراثتها من المحادثات الأصلية
- تنفذ Plugins القنوات الإجراء النهائي عبر مهايئ الإجراء الخاص بها

بالنسبة إلى Plugins القنوات، يكون سطح SDK هو `ChannelMessageActionAdapter.describeMessageTool(...)`. ويتيح استدعاء الاكتشاف الموحد هذا للـ Plugin إعادة إجراءاتها المرئية وإمكاناتها ومساهماتها في schema معًا حتى لا تنجرف هذه الأجزاء بعيدًا عن بعضها.

عندما يحمل param خاص بأداة الرسائل في قناة معينة مصدر وسائط مثل مسار محلي أو URL وسائط بعيد، يجب على Plugin أيضًا أن تعيد `mediaSourceParams` من `describeMessageTool(...)`. ويستخدم core هذه القائمة الصريحة لتطبيق تطبيع مسارات sandbox وتلميحات الوصول إلى الوسائط الصادرة من دون ترميز أسماء params المملوكة للـ Plugin بشكل صلب. ويفضَّل هناك استخدام خرائط ضمن نطاق الإجراء، لا قائمة مسطحة واحدة على مستوى القناة، حتى لا يتم تطبيع param خاص بالملف الشخصي على إجراءات غير ذات صلة مثل `send`.

يمرر core نطاق وقت التشغيل إلى خطوة الاكتشاف هذه. وتشمل الحقول المهمة:

- `accountId`
- `currentChannelId`
- `currentThreadTs`
- `currentMessageId`
- `sessionKey`
- `sessionId`
- `agentId`
- `requesterSenderId` الوارد والموثوق

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

ولهذا السبب تظل تغييرات توجيه embedded-runner عملًا يخص Plugin: فالمشغّل مسؤول عن تمرير هوية الدردشة/الجلسة الحالية إلى حد الاكتشاف الخاص بالـ Plugin حتى تعرض أداة `message` المشتركة السطح المملوك للقناة المناسب للدور الحالي.

بالنسبة إلى مساعدات التنفيذ المملوكة للقناة، ينبغي على Plugins المضمنة إبقاء بيئة التنفيذ داخل وحدات الامتداد الخاصة بها. ولم يعد core يملك بيئات تنفيذ إجراءات الرسائل الخاصة بـ Discord أو Slack أو Telegram أو WhatsApp ضمن `src/agents/tools`. ونحن لا ننشر مسارات فرعية منفصلة من نوع `plugin-sdk/*-action-runtime`، وينبغي على Plugins المضمنة استيراد شيفرة وقت التشغيل المحلية الخاصة بها مباشرة من وحداتها المملوكة للامتداد.

ينطبق الحد نفسه أيضًا على مسارات SDK المسماة بأسماء المزوّدين بشكل عام: يجب ألا يستورد core حِزَم تسهيلية خاصة بالقنوات مثل Slack أو Discord أو Signal أو WhatsApp أو امتدادات مشابهة. وإذا احتاج core إلى سلوك ما، فإما أن يستهلك الحزمة `api.ts` / `runtime-api.ts` الخاصة بالـ Plugin المضمنة نفسها أو يرفع الحاجة إلى قدرة عامة ضيقة في SDK المشترك.

وبالنسبة إلى استطلاعات الرأي تحديدًا، يوجد مساران للتنفيذ:

- `outbound.sendPoll` هو خط الأساس المشترك للقنوات التي تناسب نموذج الاستطلاع العام
- `actions.handleAction("poll")` هو المسار المفضل لدلالات الاستطلاع الخاصة بالقناة أو معلمات الاستطلاع الإضافية

ويؤجل core الآن تحليل الاستطلاع المشترك إلى ما بعد رفض توجيه استطلاع الـ Plugin للإجراء، بحيث يمكن لمعالجات الاستطلاع المملوكة للـ Plugin قبول حقول استطلاع خاصة بالقناة من دون أن يحظرها محلل الاستطلاع العام أولًا.

راجع [الجوانب الداخلية لبنية Plugin](/ar/plugins/architecture-internals) للحصول على تسلسل بدء التشغيل الكامل.

## نموذج ملكية الإمكانات

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

وهذا يعني:

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

<AccordionGroup>
  <Accordion title="مزوّد متعدد الإمكانات">
    يملك `openai` الاستدلال النصي، والكلام، والصوت الفوري، وفهم الوسائط، وإنشاء الصور. ويملك `google` الاستدلال النصي بالإضافة إلى فهم الوسائط، وإنشاء الصور، وبحث الويب. ويملك `qwen` الاستدلال النصي بالإضافة إلى فهم الوسائط وإنشاء الفيديو.
  </Accordion>
  <Accordion title="مزوّد أحادي القدرة">
    يملك `elevenlabs` و`microsoft` الكلام؛ ويملك `firecrawl` جلب الويب؛ ويملك `minimax` / `mistral` / `moonshot` / `zai` الواجهات الخلفية لفهم الوسائط.
  </Accordion>
  <Accordion title="Plugin ميزة">
    تملك `voice-call` نقل المكالمات، والأدوات، وCLI، والمسارات، وجسر Twilio media-stream، لكنها تستهلك إمكانات الكلام، والنسخ الفوري، والصوت الفوري المشتركة بدلًا من استيراد Plugins المزوّدين مباشرة.
  </Accordion>
</AccordionGroup>

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

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

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

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

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

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

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

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

### طبقات الإمكانات

استخدم هذا النموذج الذهني عند تقرير المكان الذي يجب أن تنتمي إليه الشيفرة:

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

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

- يملك core سياسة 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 واحدة سطح المزوّد
- يظل core مالكًا لعقود الإمكانات
- تستهلك القنوات وPlugins الميزات المساعدات `api.runtime.*`، لا شيفرة المزوّد
- يمكن لاختبارات العقد أن تتحقق من أن Plugin سجلت الإمكانات التي تدّعي امتلاكها

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

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

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

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

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

هل تحتاج إلى قائمة تحقق عملية للنشر؟ راجع [Capability Cookbook](/ar/plugins/architecture).

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

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

لماذا يهم هذا:

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

هناك طبقتان من الإنفاذ:

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

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

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

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

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

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

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

<Warning>
النتائج المترتبة:

يمكن لـ Plugin أصلية تسجيل أدوات، ومعالجات شبكة، وhooks، وخدمات. يمكن أن يؤدي خطأ في 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 مساحة العمل ممكّنة أو موجودة في قائمة السماح. هذا طبيعي ومفيد للتطوير المحلي واختبار التصحيحات والإصلاحات العاجلة. تُحل ثقة Plugins المضمنة من لقطة المصدر، أي من manifest والشيفرة الموجودة على القرص وقت التحميل، لا من بيانات التثبيت الوصفية. ولا يمكن لسجل تثبيت تالف أو مستبدَل أن يوسّع سطح الثقة لPlugin مضمّنة بصمت إلى ما يتجاوز ما يدعيه المصدر الفعلي.
</Note>

## حد التصدير

يصدر OpenClaw الإمكانات، لا وسائل الراحة الخاصة بالتنفيذ.

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

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

لا تزال بعض المسارات الفرعية لمساعدات Plugins المضمنة موجودة في خريطة تصدير SDK المولّدة لأغراض التوافق وصيانة Plugins المضمنة. وتشمل الأمثلة الحالية `plugin-sdk/feishu`، و`plugin-sdk/feishu-setup`، و`plugin-sdk/zalo`، و`plugin-sdk/zalo-setup`، والعديد من المسارات `plugin-sdk/matrix*`. تعامل معها على أنها صادرات محفوظة لتفاصيل التنفيذ، لا على أنها النمط الموصى به في SDK لPlugins الجديدة التابعة لجهات خارجية.

## الجوانب الداخلية والمرجع

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

## ذو صلة

- [بناء Plugins](/ar/plugins/building-plugins)
- [Plugin manifest](/ar/plugins/manifest)
- [إعداد Plugin SDK](/ar/plugins/sdk-setup)
