docs/docs/ar/plugins/architecture.md

read_when: - بناء Plugins أصلية في OpenClaw أو تصحيح أخطائها - فهم نموذج إمكانات Plugin أو حدود الملكية - العمل على خط أنابيب تحميل Plugin أو السجل - تنفيذ hooks وقت التشغيل الخاصة بالمزوّد أو Plugins القنوات sidebarTitle: Internals summary: 'الجوانب الداخلية لـ Plugin: نموذج الإمكانات، والملكية، والعقود، وخط أنابيب التحميل، ومساعدات وقت التشغيل' title: الجوانب الداخلية لـ Plugin x-i18n: refreshed_at: '2026-04-28T05:14:37Z' 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. وللحصول على أدلة عملية، ابدأ بإحدى الصفحات المركزة أدناه.

دليل المستخدم النهائي لإضافة Plugins وتمكينها واستكشاف أخطائها وإصلاحها. درس Plugin الأول مع أصغر manifest عملي. أنشئ Plugin لقناة مراسلة. أنشئ Plugin لمزوّد نموذج. مرجع import map وAPI التسجيل.

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

الإمكانات هي النموذج العام لـ 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

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

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

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

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

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

أشكال Plugin

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

تسجل نوع قدرة واحدًا بالضبط (مثل Plugin خاصة بمزوّد فقط مثل `mistral`). تسجل أنواع قدرات متعددة (مثل `openai` التي تملك الاستدلال النصي، والكلام، وفهم الوسائط، وإنشاء الصور). تسجل hooks فقط (مكتوبة النوع أو مخصصة)، من دون قدرات أو أدوات أو أوامر أو خدمات. تسجل أدوات أو أوامر أو خدمات أو مسارات لكن من دون قدرات.

استخدم openclaw plugins inspect <id> لرؤية شكل Plugin وتفصيل إمكاناتها. راجع مرجع CLI للتفاصيل.

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 من أربع طبقات:

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

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

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

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 للحصول على تسلسل بدء التشغيل الكامل.

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

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

وهذا يعني:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

يعرّف core عقد فهم الوسائط. تسجل Plugins المزوّدين `describeImage` و`transcribeAudio` و`describeVideo` بحسب الاقتضاء. تستهلك القنوات وPlugins الميزات السلوك المشترك في core بدلًا من الربط المباشر مع شيفرة المزوّد.

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

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

هل تحتاج إلى قائمة تحقق عملية للنشر؟ راجع Capability Cookbook.

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

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

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

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

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

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

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

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

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

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

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

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

النتائج المترتبة:

يمكن لـ Plugin أصلية تسجيل أدوات، ومعالجات شبكة، وhooks، وخدمات. يمكن أن يؤدي خطأ في Plugin أصلية إلى تعطل gateway أو زعزعة استقرارها. وتعادل Plugin أصلية خبيثة تنفيذ شيفرة عشوائية داخل عملية OpenClaw.

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

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

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

**ملاحظة ثقة:**

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

حد التصدير

يصدر 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.

ذو صلة

• بناء Plugins
• Plugin manifest
• إعداد Plugin SDK