البنية الداخلية لمعمارية Plugin

للاطّلاع على نموذج القدرات العام، وأشكال Plugin، وعقود الملكية/التنفيذ، راجع بنية Plugin. تتناول هذه الصفحة الآليات الداخلية: مسار التحميل، والسجل، وخطافات وقت التشغيل، ومسارات HTTP الخاصة بـ Gateway، ومسارات الاستيراد، وجداول المخططات.

مسار التحميل

عند بدء التشغيل، ينفّذ OpenClaw تقريبًا ما يلي:

1. اكتشاف الجذور المرشحة لـ Plugin
2. قراءة بيانات حزم التجميع الأصلية أو المتوافقة وبيانات تعريف الحزمة
3. رفض المرشحين غير الآمنين
4. تسوية إعدادات Plugin (plugins.enabled وallow وdeny وentries وslots وload.paths)
5. تحديد حالة التمكين لكل مرشح
6. تحميل الوحدات الأصلية الممكّنة: تستخدم الوحدات المضمّنة المبنية محمّلًا أصليًا؛ بينما تستخدم الشيفرة المصدرية المحلية التابعة لجهات خارجية والمكتوبة بـ TypeScript آلية Jiti الاحتياطية الطارئة
7. استدعاء خطافات register(api) الأصلية وجمع التسجيلات في سجل Plugin
8. إتاحة السجل للأوامر وأسطح وقت التشغيل

تعمل بوابات الأمان قبل تنفيذ وقت التشغيل. يحظر الاكتشاف مرشحًا عندما:

• يتجاوز مدخله المحلول جذر Plugin
• يكون مساره (أو دليل الجذر الخاص به) قابلًا للكتابة من الجميع
• لا تتطابق ملكية المسار مع معرّف المستخدم الحالي uid (أو root)، في Plugins غير المضمّنة

تخضع الأدلة المضمّنة القابلة للكتابة من الجميع أولًا لمحاولة إصلاح موضعية باستخدام chmod (قد توزّع عمليات تثبيت npm/العمليات العامة أدلة الحزم بأذونات 0777) قبل أن تعيد البوابة التحقق؛ بينما تُتخطى عمليات التحقق من الملكية كليًا للمصادر المضمّنة.

يظل المرشحون المحظورون يحملون معرّف Plugin الخاص بهم في التشخيص الصادر عندما يكون معروفًا (بما في ذلك المعرّفات المحلولة من بيانات حزمة داخل دليل مرفوض من نواحٍ أخرى)، بحيث ترى الإعدادات التي تشير إلى ذلك المعرّف Plugin محظورًا مرتبطًا بتحذير أمان المسار بدلًا من خطأ "Plugin غير معروف" غير ذي صلة.

سلوك تقديم بيانات الحزمة

تُعد بيانات الحزمة مصدر الحقيقة لمستوى التحكم. يستخدمها OpenClaw من أجل:

• تحديد Plugin
• اكتشاف القنوات/Skills/مخطط الإعدادات أو قدرات حزمة التجميع المعلنة
• التحقق من plugins.entries.<id>.config
• إثراء تسميات واجهة التحكم ونصوصها النائبة
• عرض بيانات تعريف التثبيت/الكتالوج
• الاحتفاظ بواصفات تفعيل وإعداد منخفضة التكلفة دون تحميل وقت تشغيل Plugin

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

تبقى كتلتَا activation وsetup الاختياريتان في مستوى التحكم. وهما واصفتان من بيانات التعريف فقط لتخطيط التفعيل واكتشاف الإعداد؛ ولا تحلان محل التسجيل في وقت التشغيل أو register(...) أو setupEntry. يستخدم مستهلكو التفعيل المباشر تلميحات الأوامر والقنوات والمزوّدين الواردة في بيانات الحزمة لتضييق تحميل Plugins قبل تكوين السجل على نطاق أوسع:

• يضيّق تحميل CLI النطاق إلى Plugins المالكة للأمر الأساسي المطلوب
• يضيّق إعداد القناة/حل Plugin النطاق إلى Plugins المالكة لمعرّف القناة المطلوب
• يضيّق إعداد المزوّد الصريح/حله في وقت التشغيل النطاق إلى Plugins المالكة لمعرّف المزوّد المطلوب
• يستخدم تخطيط بدء تشغيل Gateway القيمة activation.onStartup لعمليات الاستيراد الصريحة عند بدء التشغيل؛ ولا تُحمّل Plugins التي لا تتضمن بيانات تعريف لبدء التشغيل إلا عبر مشغلات تفعيل أضيق نطاقًا

يعرض مخطّط التفعيل واجهة API تقتصر على المعرّفات للمتصلين الحاليين، وواجهة API للخطة لأغراض التشخيص. توضّح إدخالات الخطة سبب اختيار Plugin، مع الفصل بين تلميحات activation.* الصريحة والرجوع إلى ملكية بيانات الحزمة:

يمثل هذا الفصل بين الأسباب حد التوافق: تستمر بيانات تعريف Plugin الحالية في العمل، بينما تستطيع الشيفرة الجديدة اكتشاف التلميحات واسعة النطاق أو سلوك الرجوع دون تغيير دلالات التحميل في وقت التشغيل.

تستمر عمليات التحميل المسبق في وقت الطلب التي تطلب النطاق الواسع all في اشتقاق مجموعة صريحة وفعّالة من معرّفات Plugins من الإعدادات، وتخطيط بدء التشغيل، والقنوات المضبوطة، والخانات، وقواعد التمكين التلقائي (resolveEffectivePluginIds في src/plugins/effective-plugin-ids.ts). وإذا كانت المجموعة المشتقة فارغة، يُبقي OpenClaw النطاق فارغًا بدلًا من توسيعه ليشمل كل Plugin قابل للاكتشاف.

يفضّل اكتشاف الإعداد المعرّفات المملوكة للواصفات، مثل setup.providers وsetup.cliBackends، لتضييق نطاق Plugins المرشحة قبل الرجوع إلى setup-api في Plugins التي لا تزال بحاجة إلى خطافات وقت التشغيل أثناء الإعداد. تستخدم قوائم إعداد المزوّد providerAuthChoices الواردة في بيانات الحزمة، وخيارات الإعداد المشتقة من الواصفات، وبيانات تعريف كتالوج التثبيت دون تحميل وقت تشغيل المزوّد. تمثل القيمة الصريحة setup.requiresRuntime: false حدًا يقتصر على الواصفات؛ بينما يؤدي حذف requiresRuntime إلى الإبقاء على الرجوع القديم إلى setup-api لأغراض التوافق. إذا ادّعى أكثر من Plugin مكتشف ملكية معرّف مزوّد إعداد أو معرّف واجهة CLI خلفية مُسوّى نفسه، يرفض بحث الإعداد المالك الملتبس بدلًا من الاعتماد على ترتيب الاكتشاف. وعند تنفيذ وقت تشغيل الإعداد، تُبلغ تشخيصات السجل عن الانحراف بين setup.providers / setup.cliBackends والمزوّدين أو واجهات CLI الخلفية المسجّلة فعليًا بواسطة setup-api، دون حظر Plugins القديمة.

حدود ذاكرة Plugin المؤقتة

لا يخزّن OpenClaw مؤقتًا نتائج اكتشاف Plugins أو بيانات سجل بيانات الحزمة المباشرة ضمن نوافذ زمنية فعلية. يجب أن تصبح عمليات التثبيت، وتعديلات بيانات الحزمة، وتغييرات مسارات التحميل مرئية عند القراءة الصريحة التالية لبيانات التعريف أو إعادة بناء اللقطة. يحتفظ محلل ملف بيانات الحزمة بذاكرة مؤقتة محدودة لتوقيع الملف، يكون مفتاحها مسار ملف بيانات الحزمة المفتوح مع الجهاز/inode والحجم وmtime/ctime؛ ولا تتجنب تلك الذاكرة المؤقتة سوى إعادة تحليل البايتات غير المتغيرة، ويجب ألا تخزّن مؤقتًا إجابات الاكتشاف أو السجل أو المالك أو السياسة.

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

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

• PluginLoaderCacheState وسجلات وقت التشغيل النشطة المتوافقة
• ذاكرات jiti/الوحدات المؤقتة وذاكرات محمّل السطح العام المؤقتة المستخدمة لتجنب استيراد سطح وقت التشغيل نفسه بصورة متكررة
• ذاكرات نظام الملفات المؤقتة لعناصر Plugin المثبتة
• خرائط قصيرة العمر لكل استدعاء لتسوية المسارات أو حل التكرارات

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

لا تضف ذاكرات مؤقتة دائمة أو مرتبطة بالوقت الفعلي من أجل:

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

يعيد المتصلون الذين يبنون بيانات تعريف بيانات الحزمة من فهرس Plugins المثبتة والمستمر تخزينه تكوين ذلك السجل عند الطلب. الفهرس المثبت هو حالة دائمة لمستوى المصدر؛ وليس ذاكرة مؤقتة مخفية لبيانات التعريف داخل العملية.

نموذج السجل

لا تعدّل Plugins المحمّلة المتغيرات العامة العشوائية في النواة مباشرةً. بل تسجّل في سجل Plugin مركزي (PluginRegistry في src/plugins/registry-types.ts)، يتتبع سجلات Plugins (الهوية، والمصدر، والأصل، والحالة، والتشخيصات)، بالإضافة إلى مصفوفات لكل قدرة: الأدوات، والخطافات القديمة والخطافات المنمطة، والقنوات، والمزوّدون، ومعالجات RPC الخاصة بـ Gateway، ومسارات HTTP، ومسجّلو CLI، وخدمات الخلفية، والأوامر المملوكة لـ Plugin، وعشرات عائلات المزوّدين المنمطة الأخرى (الكلام، والتضمينات، وتوليد الصور/الفيديو/الموسيقى، وجلب الويب/البحث فيه، وأطر الوكلاء، وإجراءات الجلسات، وما إلى ذلك).

تقرأ ميزات النواة بعد ذلك من هذا السجل بدلًا من التواصل مباشرةً مع وحدات Plugin. وهذا يحافظ على اتجاه واحد للتحميل:

• وحدة Plugin -> التسجيل في السجل
• وقت تشغيل النواة -> استهلاك السجل

هذا الفصل مهم لقابلية الصيانة. فهو يعني أن معظم أسطح النواة لا تحتاج إلا إلى نقطة تكامل واحدة: "قراءة السجل"، بدلًا من "إضافة معالجة خاصة لكل وحدة Plugin".

استدعاءات ربط المحادثة

يمكن لـ Plugins التي تربط محادثة أن تتفاعل عند حسم الموافقة.

استخدم api.onConversationBindingResolved(...) لتلقي استدعاء بعد الموافقة على طلب الربط أو رفضه:

export default {  id: "my-plugin",  register(api) {    api.onConversationBindingResolved(async (event) => {      if (event.status === "approved") {        // A binding now exists for this plugin + conversation.        console.log(event.binding?.conversationId);        return;      }       // The request was denied; clear any local pending state.      console.log(event.request.conversation.conversationId);    });  },};

حقول حمولة الاستدعاء:

• status: "approved" أو "denied"
• decision: "allow-once" أو "allow-always" أو "deny"
• binding: الربط المحلول للطلبات الموافق عليها
• request: ملخص الطلب الأصلي، وتلميح الفصل، ومعرّف المرسل، وبيانات تعريف المحادثة

هذا الاستدعاء مخصص للإشعار فقط. ولا يغيّر الجهات المسموح لها بربط محادثة، ويُنفّذ بعد انتهاء معالجة الموافقة في النواة.

خطافات وقت تشغيل المزوّد

تتكون Plugins الخاصة بالمزوّدين من ثلاث طبقات:

• بيانات تعريف بيانات الحزمة للبحث منخفض التكلفة قبل وقت التشغيل: setup.providers[].envVars، وproviderAuthEnvVars المتقادمة المخصصة للتوافق، وproviderAuthAliases، وproviderAuthChoices، وchannelEnvVars.
• خطافات وقت الإعداد: catalog (والاسم القديم discovery) بالإضافة إلى applyConfigDefaults.
• خطافات وقت التشغيل: أكثر من 40 خطافًا اختياريًا تغطي المصادقة، وحل النماذج، وتغليف التدفق، ومستويات التفكير، وسياسة إعادة التشغيل، ونقاط نهاية الاستخدام. راجع ترتيب الخطافات واستخدامها.

يظل OpenClaw مسؤولًا عن حلقة الوكيل العامة، وتجاوز الأعطال، ومعالجة النصوص المنسوخة، وسياسة الأدوات. وتمثل هذه الخطافات سطح التوسعة للسلوك الخاص بالمزوّد دون الحاجة إلى وسيلة نقل استدلال مخصصة بالكامل.

استخدم setup.providers[].envVars في البيان عندما تكون لدى المزوّد بيانات اعتماد قائمة على متغيرات البيئة ينبغي أن تتمكن مسارات المصادقة/الحالة/منتقي النماذج العامة من رؤيتها من دون تحميل وقت تشغيل Plugin. لا يزال محوّل التوافق يقرأ providerAuthEnvVars المهجورة خلال فترة الإهمال، وتتلقى الإضافات غير المضمّنة التي تستخدمها تشخيصًا للبيان. استخدم providerAuthAliases في البيان عندما ينبغي لمعرّف مزوّد أن يعيد استخدام متغيرات البيئة وملفات تعريف المصادقة والمصادقة المدعومة بالإعدادات وخيار إعداد مفتاح API لمعرّف مزوّد آخر. استخدم providerAuthChoices في البيان عندما ينبغي لواجهات CLI الخاصة بالإعداد الأولي/اختيار المصادقة أن تعرف معرّف خيار المزوّد وتسميات المجموعات وآلية توصيل المصادقة البسيطة ذات العلامة الواحدة من دون تحميل وقت تشغيل المزوّد. احتفظ بـ envVars في وقت تشغيل المزوّد للتلميحات الموجّهة إلى المشغّلين، مثل تسميات الإعداد الأولي أو متغيرات إعداد معرّف عميل OAuth/سر العميل.

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

ترتيب الخطافات واستخدامها

بالنسبة إلى إضافات النماذج/المزوّدين، يستدعي OpenClaw الخطافات بهذا الترتيب التقريبي. يمثّل عمود "متى يُستخدم" دليل القرار السريع. لا تُدرج هنا عمدًا حقول المزوّد المخصّصة للتوافق فقط، والتي لم يعد OpenClaw يستدعيها، مثل ProviderPlugin.capabilities وsuppressBuiltInModel.

تتحقق normalizeModelId وnormalizeTransport وnormalizeConfig أولًا من Plugin المزوّد المطابق، ثم تنتقل إلى Plugins المزوّدين الآخرين القادرين على استخدام الخطافات حتى يغيّر أحدها فعليًا معرّف النموذج أو النقل/الإعداد. يحافظ ذلك على عمل طبقات المزوّد البديلة/المتوافقة دون أن يُطلب من المستدعي معرفة أي Plugin مضمّن يملك إعادة الكتابة. إذا لم يُعِد أي خطاف مزوّد كتابة إدخال إعداد مدعوم من عائلة Google، فسيظل مُطبِّع إعداد Google المضمّن يطبّق عملية تنظيف التوافق تلك.

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

تقرر resolveUsageAuth ما إذا كان ينبغي لـ OpenClaw استدعاء fetchUsageSnapshot أو الرجوع إلى الحل العام لبيانات الاعتماد لواجهات الاستخدام/الحالة. أعد { token, accountId?, subscriptionType?, rateLimitTier? } عندما يملك المزوّد بيانات اعتماد للاستخدام (تنتقل بيانات الخطة الوصفية الاختيارية إلى fetchUsageSnapshot)، وأعد { handled: true } عندما تكون مصادقة الاستخدام المملوكة للمزوّد قد عالجت الطلب ويجب أن تمنع الرجوع العام إلى مفتاح API أو OAuth، وأعد null أو undefined عندما لا يعالج المزوّد مصادقة الاستخدام.

صرّح ببيانات اعتماد المؤسسة أو الفوترة في providerUsageAuthEnvVars ضمن البيان. يتيح ذلك لواجهات الاكتشاف العام وتنقية الأسرار التعرّف عليها دون جعلها مرشحة لمصادقة الاستدلال.

مثال على مزوّد

api.registerProvider({  id: "example-proxy",  label: "Example Proxy",  auth: [],  catalog: {    order: "simple",    run: async (ctx) => {      const apiKey = ctx.resolveProviderApiKey("example-proxy").apiKey;      if (!apiKey) {        return null;      }      return {        provider: {          baseUrl: "https://proxy.example.com/v1",          apiKey,          api: "openai-completions",          models: [{ id: "auto", name: "Auto" }],        },      };    },  },  resolveDynamicModel: (ctx) => ({    id: ctx.modelId,    name: ctx.modelId,    provider: "example-proxy",    api: "openai-completions",    baseUrl: "https://proxy.example.com/v1",    reasoning: false,    input: ["text"],    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },    contextWindow: 128000,    maxTokens: 8192,  }),  prepareRuntimeAuth: async (ctx) => {    const exchanged = await exchangeToken(ctx.apiKey);    return {      apiKey: exchanged.token,      baseUrl: exchanged.baseUrl,      expiresAt: exchanged.expiresAt,    };  },  resolveUsageAuth: async (ctx) => {    const auth = await ctx.resolveOAuthToken();    return auth ? { token: auth.token } : null;  },  fetchUsageSnapshot: async (ctx) => {    return await fetchExampleProxyUsage(ctx.token, ctx.timeoutMs, ctx.fetchFn);  },});

أمثلة مضمّنة

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

مساعدات وقت التشغيل

يمكن لـ Plugins الوصول إلى مساعدات أساسية محددة عبر api.runtime. لتحويل النص إلى كلام:

const clip = await api.runtime.tts.textToSpeech({  text: "Hello from OpenClaw",  cfg: api.config,}); const result = await api.runtime.tts.textToSpeechTelephony({  text: "Hello from OpenClaw",  cfg: api.config,}); const voices = await api.runtime.tts.listVoices({  provider: "elevenlabs",  cfg: api.config,});

ملاحظات:

• تعيد textToSpeech حمولة إخراج تحويل النص إلى كلام الأساسية المعتادة لواجهات الملفات/الملاحظات الصوتية.
• تستخدم إعداد messages.tts الأساسي واختيار المزوّد.
• تعيد مخزنًا مؤقتًا لصوت PCM مع معدل العينة. يجب على Plugins إعادة أخذ العينات/الترميز للمزوّدين.
• تكون listVoices اختيارية لكل مزوّد. استخدمها في أدوات اختيار الأصوات أو تدفقات الإعداد المملوكة للمورّد.
• يمرّر الجزء الأساسي مهلة طلب محلولة إلى خطافات listVoices الخاصة بالمزوّد؛ ويمكن لإعدادات المهلة الخاصة بالمزوّد تجاوزها.
• يمكن أن تتضمن قوائم الأصوات بيانات وصفية أغنى، مثل اللغة والمنطقة والجنس ووسوم الشخصية، لاستخدامها في أدوات الاختيار المدركة للمزوّد.
• يدعم OpenAI وElevenLabs الاتصالات الهاتفية حاليًا. أما Microsoft فلا يدعمها.

يمكن لـ Plugins أيضًا تسجيل مزوّدي الكلام عبر api.registerSpeechProvider(...).

api.registerSpeechProvider({  id: "acme-speech",  label: "Acme Speech",  isConfigured: ({ config }) => Boolean(config.messages?.tts),  synthesize: async (req) => {    return {      audioBuffer: Buffer.from([]),      outputFormat: "mp3",      fileExtension: ".mp3",      voiceCompatible: false,    };  },});

ملاحظات:

• احتفظ بسياسة تحويل النص إلى كلام والرجوع وتسليم الردود في الجزء الأساسي.
• استخدم مزوّدي الكلام لسلوك التوليف المملوك للمورّد.
• يُطبَّع إدخال Microsoft القديم edge إلى معرّف المزوّد microsoft.
• نموذج الملكية المفضّل موجّه نحو الشركة: يمكن لـ Plugin مورّد واحد امتلاك مزوّدي النص والكلام والصور والوسائط المستقبلية مع إضافة OpenClaw لعقود القدرات تلك.

لفهم الصور/الصوت/الفيديو، تسجّل Plugins مزوّدًا واحدًا ذا نوع محدد لفهم الوسائط بدلًا من حزمة مفاتيح/قيم عامة:

api.registerMediaUnderstandingProvider({  id: "google",  capabilities: ["image", "audio", "video"],  describeImage: async (req) => ({ text: "..." }),  transcribeAudio: async (req) => ({ text: "..." }),  describeVideo: async (req) => ({ text: "..." }),});

ملاحظات:

• احتفظ بالتنسيق والرجوع والإعداد وتوصيل القنوات في الجزء الأساسي.
• احتفظ بسلوك المورّد في Plugin المزوّد.
• يجب أن يظل التوسّع الإضافي محدد الأنواع: طرائق اختيارية جديدة، وحقول نتائج اختيارية جديدة، وقدرات اختيارية جديدة.
• يتبع توليد الفيديو النمط نفسه بالفعل:
  • يمتلك الجزء الأساسي عقد القدرة ومساعد وقت التشغيل
  • تسجّل Plugins المورّدين api.registerVideoGenerationProvider(...)
  • تستهلك Plugins الميزات/القنوات api.runtime.videoGeneration.*

بالنسبة إلى مساعدات وقت التشغيل لفهم الوسائط، يمكن لـ Plugins استدعاء:

const image = await api.runtime.mediaUnderstanding.describeImageFile({  filePath: "/tmp/inbound-photo.jpg",  cfg: api.config,  agentDir: "/tmp/agent",}); const video = await api.runtime.mediaUnderstanding.describeVideoFile({  filePath: "/tmp/inbound-video.mp4",  cfg: api.config,}); const extraction = await api.runtime.mediaUnderstanding.extractStructuredWithModel({  provider: "codex",  model: "gpt-5.6-sol",  input: [    {      type: "image",      buffer: receiptImageBuffer,      fileName: "receipt.png",      mime: "image/png",    },    { type: "text", text: "Use the printed fields as the source of truth." },  ],  instructions: "Return entities and searchable tags.",  schemaName: "example.evidence",  jsonSchema: {    type: "object",    properties: {      entities: { type: "array", items: { type: "string" } },      tags: { type: "array", items: { type: "string" } },    },  },  cfg: api.config,});

لنسخ الصوت نصيًا، يمكن لـ Plugins استخدام وقت تشغيل فهم الوسائط أو الاسم البديل الأقدم لـ STT:

const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({  filePath: "/tmp/inbound-audio.ogg",  cfg: api.config,  // Optional when MIME cannot be inferred reliably:  mime: "audio/ogg",});

ملاحظات:

• ‏api.runtime.mediaUnderstanding.* هي الواجهة المشتركة المفضّلة لفهم الصور/الصوت/الفيديو.
• ‏extractStructuredWithModel(...) هي الواجهة الموجّهة إلى Plugins للاستخراج المحدود المملوك للمزوّد الذي يبدأ بالصور. ضمّن إدخال صورة واحدًا على الأقل؛ وتكون إدخالات النص سياقًا تكميليًا. تمتلك Plugins المنتج مساراتها ومخططاتها، بينما يمتلك OpenClaw الحد الفاصل بين المزوّد ووقت التشغيل.
• تستخدم إعداد الصوت الأساسي لفهم الوسائط (tools.media.audio) وترتيب الرجوع بين المزوّدين.
• تعيد { text: undefined } عندما لا يُنتج أي إخراج للنسخ النصي (مثلًا عند تخطي الإدخال أو عدم دعمه).
• تظل api.runtime.stt.transcribeAudioFile(...) اسمًا بديلًا للتوافق.

يمكن لـ Plugins أيضًا تشغيل عمليات الوكلاء الفرعيين في الخلفية عبر api.runtime.subagent:

const result = await api.runtime.subagent.run({  sessionKey: "agent:main:subagent:search-helper",  message: "Expand this query into focused follow-up searches.",  provider: "openai",  model: "gpt-4.1-mini",  deliver: false,});

ملاحظات:

• ‏provider وmodel تجاوزان اختياريان لكل عملية تشغيل، وليسا تغييرات دائمة للجلسة.
• لا يحترم OpenClaw حقول التجاوز هذه إلا للمستدعين الموثوقين.
• بالنسبة إلى عمليات الرجوع المملوكة لـ Plugin، يجب على المشغّلين الاشتراك صراحةً باستخدام plugins.entries.<id>.subagent.allowModelOverride: true.
• استخدم plugins.entries.<id>.subagent.allowedModels لتقييد Plugins الموثوقة بأهداف provider/model معيارية محددة، أو "*" للسماح صراحةً بأي هدف.
• تظل عمليات الوكيل الفرعي من Plugins غير الموثوقة تعمل، لكن طلبات التجاوز تُرفض بدلًا من الرجوع بصمت.
• تُوسَم جلسات الوكيل الفرعي التي تنشئها Plugins بمعرّف Plugin المنشئ. يمكن لعملية الرجوع api.runtime.subagent.deleteSession(...) حذف تلك الجلسات المملوكة فقط؛ ولا يزال حذف جلسة عشوائية يتطلب طلب Gateway بنطاق إداري.

للبحث على الويب، يمكن لـ Plugins استهلاك مساعد وقت التشغيل المشترك بدلًا من الوصول إلى توصيل أداة الوكيل:

const providers = api.runtime.webSearch.listProviders({  config: api.config,}); const result = await api.runtime.webSearch.search({  config: api.config,  args: {    query: "OpenClaw plugin runtime helpers",    count: 5,  },});

يمكن لـ Plugins أيضًا تسجيل مزوّدي البحث على الويب عبر api.registerWebSearchProvider(...).

ملاحظات:

• احتفظ باختيار المزوّد وحل بيانات الاعتماد ودلالات الطلب المشتركة في الجزء الأساسي.
• استخدم مزوّدي البحث على الويب لعمليات نقل البحث الخاصة بالمورّد.
• ‏api.runtime.webSearch.* هي الواجهة المشتركة المفضّلة لـ Plugins الميزات/القنوات التي تحتاج إلى سلوك البحث دون الاعتماد على غلاف أداة الوكيل.

api.runtime.imageGeneration

const result = await api.runtime.imageGeneration.generate({  config: api.config,  args: { prompt: "A friendly lobster mascot", size: "1024x1024" },}); const providers = api.runtime.imageGeneration.listProviders({  config: api.config,});

• ‏generate(...): توليد صورة باستخدام سلسلة مزوّدي توليد الصور المضبوطة.
• ‏listProviders(...): سرد مزوّدي توليد الصور المتاحين وقدراتهم.

مسارات HTTP في Gateway

يمكن لـ Plugins كشف نقاط نهاية HTTP باستخدام api.registerHttpRoute(...).

api.registerHttpRoute({  path: "/acme/webhook",  auth: "plugin",  match: "exact",  handler: async (_req, res) => {    res.statusCode = 200;    res.end("ok");    return true;  },});

حقول المسار:

• path: مسار التوجيه ضمن خادم HTTP الخاص بـ Gateway.
• auth: مطلوب، ويكون "gateway" أو "plugin". استخدم "gateway" لفرض مصادقة Gateway المعتادة، أو "plugin" للمصادقة التي يديرها Plugin أو للتحقق من Webhook.
• match: اختياري. "exact" (الافتراضي) أو "prefix".
• handleUpgrade: معالج اختياري لطلبات ترقية WebSocket على المسار نفسه.
• replaceExisting: اختياري. يسمح للـ Plugin نفسه باستبدال تسجيل مساره الحالي.
• handler: أرجِع true عندما يكون المسار قد عالج الطلب.

ملاحظات:

• أُزيل api.registerHttpHandler(...)، وسيؤدي استخدامه إلى خطأ عند تحميل Plugin. استخدم api.registerHttpRoute(...) بدلًا منه.
• يجب أن تعلن مسارات Plugin عن auth صراحةً.
• تُرفض تعارضات path + match المتطابقة ما لم تكن replaceExisting: true، ولا يمكن لـ Plugin استبدال مسار تابع لـ Plugin آخر.
• تُرفض المسارات المتداخلة ذات مستويات auth المختلفة. اجعل سلاسل الانتقال الاحتياطي exact/prefix على مستوى المصادقة نفسه فقط.
• لا تتلقى المسارات ذات auth: "plugin" نطاقات وقت تشغيل المشغّل تلقائيًا. فهي مخصصة لعمليات Webhook والتحقق من التوقيعات التي يديرها Plugin، وليست لاستدعاءات أدوات Gateway المساعدة ذات الامتيازات.
• تعمل المسارات ذات auth: "gateway" داخل نطاق وقت تشغيل طلب Gateway. والسطح الافتراضي (gatewayRuntimeScopeSurface: "write-default") متحفظ عمدًا:
  • تحصل مصادقة حامل السر المشترك (gateway.auth.mode = "token" / "password") وأي طريقة مصادقة لا تستخدم الوكيل الموثوق على نطاق operator.write واحد، حتى إذا أرسل المستدعي x-openclaw-scopes
  • يحتفظ مستدعو trusted-proxy الذين لا يرسلون ترويسة x-openclaw-scopes صريحة أيضًا بالسطح القديم المقتصر على operator.write
  • يحصل مستدعو trusted-proxy الذين يرسلون x-openclaw-scopes على النطاقات المعلنة بدلًا من ذلك
  • يمكن للمسار الاشتراك في gatewayRuntimeScopeSurface: "trusted-operator" لاحترام x-openclaw-scopes دائمًا في أوضاع المصادقة التي تحمل هوية (مع الرجوع إلى مجموعة نطاقات CLI الافتراضية الكاملة عند غياب الترويسة)
• قاعدة عملية: لا تفترض أن مسار Plugin الموثق عبر Gateway يشكل ضمنيًا سطح إدارة. إذا كان مسارك يحتاج إلى سلوك مخصص للمسؤول فقط، فاشترك في سطح النطاق trusted-operator، واشترط وضع مصادقة يحمل هوية، ووثّق عقد ترويسة x-openclaw-scopes الصريح.
• بعد مطابقة المسار والمصادقة، تشارك المعالجات العادية في قبول العمل الجذري لـ Gateway. يعيد Gateway في حالة الاستعداد أو إعادة التشغيل الرمز 503 قبل استدعاء المعالج. والاستثناء المحدود هو مسار ذو auth: "gateway" تمنحه التظاهرة صلاحية، ويشترك أيضًا في سطح trusted-operator الخاص بالمسار؛ إذ يظل قابلًا للوصول حتى لا يتعطل إرسال التحكم في التعليق، بينما تظل المسارات الشقيقة العادية التابعة للـ Plugin نفسه خلف حد القبول. تستخدم ملكية WebSocket في handleUpgrade حد القبول الذري نفسه؛ وما إن يقبل المعالج مقبسًا، تصبح دورة حياة المقبس اللاحقة مملوكة للـ Plugin ولا يتتبعها هذا الحد.

مسارات استيراد SDK الخاصة بالـ Plugin

استخدم المسارات الفرعية المحددة لـ SDK بدلًا من مجمّع الجذر الأحادي openclaw/plugin-sdk عند إنشاء Plugins جديدة. المسارات الفرعية الأساسية:

تختار Plugins القنوات من عائلة من الوصلات المحددة — channel-setup، وsetup-runtime، وsetup-tools، وchannel-pairing، وchannel-contract، وchannel-feedback، وchannel-inbound، وchannel-outbound، وcommand-auth، وsecret-input، وwebhook-ingress، وchannel-targets، وchannel-actions. ينبغي توحيد سلوك الموافقة ضمن عقد approvalCapability واحد بدلًا من توزيعه على حقول Plugin غير المرتبطة. راجع Plugins القنوات.

توجد أدوات وقت التشغيل والإعدادات المساعدة ضمن مسارات فرعية مركزة مطابقة من نمط *-runtime (approval-runtime، وagent-runtime، وlazy-runtime، وdirectory-runtime، وtext-runtime، وruntime-store، وsystem-event-runtime، وheartbeat-runtime، وchannel-activity-runtime، وغيرها). فضّل config-contracts، وplugin-config-runtime، وruntime-config-snapshot، وconfig-mutation بدلًا من مجمّع التوافق الواسع config-runtime.

نقاط الدخول الداخلية للمستودع (لكل جذر حزمة Plugin مضمّنة):

• index.js — نقطة دخول Plugin المضمّنة
• api.js — مجمّع الأدوات المساعدة والأنواع
• runtime-api.js — مجمّع مخصص لوقت التشغيل
• setup-entry.js — نقطة دخول Plugin الإعداد

يجب ألا تستورد Plugins الخارجية إلا المسارات الفرعية openclaw/plugin-sdk/*. لا تستورد مطلقًا src/* من حزمة Plugin أخرى، سواء من النواة أو من Plugin آخر. تفضّل نقاط الدخول المحمّلة عبر الواجهة لقطة إعدادات وقت التشغيل النشطة عند وجودها، ثم ترجع إلى ملف الإعدادات المحلول على القرص.

توجد مسارات فرعية خاصة بالقدرات، مثل image-generation، وmedia-understanding، وspeech، لأن Plugins المضمّنة تستخدمها حاليًا. لكنها ليست عقودًا خارجية ثابتة تلقائيًا على المدى الطويل — تحقّق من صفحة مرجع SDK ذات الصلة عند الاعتماد عليها.

مخططات أداة الرسائل

ينبغي أن تمتلك Plugins مساهمات مخطط describeMessageTool(...) الخاصة بالقنوات للعمليات غير المتعلقة بالرسائل، مثل التفاعلات، وإشعارات القراءة، والاستطلاعات. ينبغي أن يستخدم العرض المشترك للإرسال عقد MessagePresentation العام بدلًا من حقول الأزرار أو المكوّنات أو الكتل أو البطاقات الأصلية الخاصة بمزوّد الخدمة. راجع عرض الرسائل للاطلاع على العقد، وقواعد الرجوع، وتعيين مزوّدي الخدمة، وقائمة التحقق الخاصة بمؤلف Plugin.

تعلن Plugins القادرة على الإرسال عما يمكنها عرضه عبر قدرات الرسائل:

• presentation لكتل العرض الدلالية (text، وcontext، وdivider، وchart، وtable، وbuttons، وselect)
• delivery-pin لطلبات تثبيت التسليم

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

تحليل أهداف القنوات

ينبغي أن تمتلك Plugins القنوات دلالات الأهداف الخاصة بالقنوات. أبقِ مضيف الصادر المشترك عامًا، واستخدم سطح محوّل المراسلة لقواعد مزوّد الخدمة:

• يقرر messaging.inferTargetChatType({ to }) ما إذا كان ينبغي التعامل مع هدف مطبّع باعتباره direct أو group أو channel قبل البحث في الدليل.
• يُعلِم messaging.targetResolver.looksLikeId(raw, normalized) النواة بما إذا كان الإدخال ينبغي أن ينتقل مباشرة إلى تحليل شبيه بالمعرّف بدلًا من البحث في الدليل.
• تسرد messaging.targetResolver.reservedLiterals الكلمات المجرّدة التي تمثل مراجع قناة أو جلسة لذلك المزوّد. يحافظ التحليل على إدخالات الدليل المضبوطة قبل رفض القيم الحرفية المحجوزة، ثم يفشل بصورة مغلقة عند عدم العثور عليها في الدليل.
• يُعد messaging.targetResolver.resolveTarget(...) آلية الرجوع الخاصة بالـ Plugin عندما تحتاج النواة إلى تحليل نهائي يملكه مزوّد الخدمة بعد التطبيع أو بعد عدم العثور على نتيجة في الدليل.
• يمتلك messaging.resolveOutboundSessionRoute(...) إنشاء مسار الجلسة الخاص بمزوّد الخدمة بعد تحليل الهدف.

التقسيم الموصى به:

• استخدم inferTargetChatType لقرارات الفئة التي ينبغي اتخاذها قبل البحث في الأقران أو المجموعات.
• استخدم looksLikeId للتحقق مما إذا كان ينبغي «التعامل مع هذا باعتباره معرّف هدف صريحًا/أصليًا».
• استخدم resolveTarget كآلية رجوع للتطبيع الخاص بمزوّد الخدمة، وليس للبحث الواسع في الدليل.
• احتفظ بالمعرّفات الأصلية الخاصة بمزوّد الخدمة، مثل معرّفات المحادثات، ومعرّفات الخيوط، وJIDs، والمقابض، ومعرّفات الغرف، داخل قيم target أو المعاملات الخاصة بمزوّد الخدمة، وليس في حقول SDK العامة.

الأدلة المدعومة بالإعدادات

ينبغي أن تُبقي Plugins التي تشتق إدخالات الدليل من الإعدادات ذلك المنطق داخل Plugin، وأن تعيد استخدام الأدوات المساعدة المشتركة من openclaw/plugin-sdk/directory-runtime.

استخدم هذا عندما تحتاج القناة إلى أقران أو مجموعات مدعومة بالإعدادات، مثل:

• أقران الرسائل المباشرة المستندين إلى قائمة السماح
• خرائط القنوات أو المجموعات المضبوطة
• آليات رجوع ثابتة للدليل مقيّدة بنطاق الحساب

لا تتعامل الأدوات المساعدة المشتركة في directory-runtime إلا مع العمليات العامة:

• ترشيح الاستعلامات
• تطبيق الحدود
• أدوات إزالة التكرار والتطبيع المساعدة
• إنشاء ChannelDirectoryEntry[]

ينبغي أن يظل فحص الحساب الخاص بالقناة وتطبيع المعرّفات ضمن تنفيذ Plugin.

كتالوجات مزوّدي الخدمة

يمكن لـ Plugins مزوّدي الخدمة تعريف كتالوجات النماذج للاستدلال باستخدام registerProvider({ catalog: { run(...) { ... } } }).

تعيد catalog.run(...) البنية نفسها التي يكتبها OpenClaw في models.providers:

• { provider } لإدخال مزوّد خدمة واحد
• { providers } لعدة إدخالات لمزوّدي الخدمة

استخدم catalog عندما يمتلك Plugin معرّفات النماذج الخاصة بمزوّد الخدمة، أو قيم عناوين URL الأساسية الافتراضية، أو بيانات النماذج الوصفية المشروطة بالمصادقة.

يتحكم catalog.order في توقيت دمج كتالوج Plugin نسبةً إلى مزوّدي OpenClaw الضمنيين المضمّنين:

• simple: مزوّدو خدمة يعتمدون على مفتاح API عادي أو متغيرات البيئة
• profile: مزوّدو خدمة يظهرون عند وجود ملفات تعريف مصادقة
• paired: مزوّدو خدمة ينشئون عدة إدخالات مترابطة لمزوّدي الخدمة
• late: المرور الأخير، بعد مزوّدي الخدمة الضمنيين الآخرين

تفوز إدخالات مزوّدي الخدمة اللاحقة عند تعارض المفاتيح، لذا يمكن للـ Plugins تجاوز إدخال مزوّد خدمة مضمّن يحمل معرّف مزوّد الخدمة نفسه عن قصد.

يمكن للـ Plugins أيضًا نشر صفوف نماذج للقراءة فقط عبر api.registerModelCatalogProvider({ provider, kinds, staticCatalog, liveCatalog }). وهذا هو المسار المستقبلي لأسطح القوائم والمساعدة والاختيار، ويدعم صفوف text، وvoice، وimage_generation، وvideo_generation، وmusic_generation. تظل Plugins مزوّدي الخدمة مالكة لاستدعاءات نقاط النهاية الحية، وتبادل الرموز، وتعيين استجابات المورّد؛ بينما تمتلك النواة بنية الصف المشتركة، وتسميات المصدر، وتنسيق مساعدة أدوات الوسائط. تنشئ تسجيلات مزوّدي إنشاء الوسائط صفوف الكتالوج الثابتة تلقائيًا من defaultModel، وmodels، وcapabilities.

التوافق:

• لا يزال discovery يعمل كاسم مستعار قديم، لكنه يصدر تحذير إهمال
• إذا سُجّل كل من catalog وdiscovery، يستخدم OpenClaw‏ catalog ويصدر تحذيرًا
• أُهمل augmentModelCatalog؛ وينبغي أن تنشر مزوّدات الخدمة المضمّنة الصفوف التكميلية عبر registerModelCatalogProvider

فحص القنوات للقراءة فقط

إذا كان Plugin الخاص بك يسجل قناة، ففضّل تنفيذ plugin.config.inspectAccount(cfg, accountId) إلى جانب resolveAccount(...).

السبب:

• resolveAccount(...) هو مسار وقت التشغيل. ويُسمح له بافتراض أن بيانات الاعتماد متحققة بالكامل، وأن يفشل سريعًا عند غياب الأسرار المطلوبة.
• ينبغي ألا تحتاج مسارات أوامر القراءة فقط، مثل openclaw status، وopenclaw status --all، وopenclaw channels status، وopenclaw channels resolve، ومسارات إصلاح doctor/الإعدادات، إلى إنشاء بيانات اعتماد وقت التشغيل لمجرد وصف الإعدادات.

السلوك الموصى به لـ inspectAccount(...):

• أرجِع حالة وصفية للحساب فقط.
• حافظ على enabled وconfigured.
• ضمّن حقول مصدر بيانات الاعتماد/حالتها عند الاقتضاء، مثل:
  • tokenSource، tokenStatus
  • botTokenSource، botTokenStatus
  • appTokenSource، appTokenStatus
  • signingSecretSource، signingSecretStatus
• لا تحتاج إلى إرجاع قيم الرموز المميزة الأولية لمجرد الإبلاغ عن التوفّر للقراءة فقط. يكفي إرجاع tokenStatus: "available" (وحقل المصدر المطابق) لأوامر عرض الحالة.
• استخدم configured_unavailable عندما تكون بيانات الاعتماد مهيأة عبر SecretRef لكنها غير متاحة في مسار الأمر الحالي.

يتيح ذلك لأوامر القراءة فقط الإبلاغ بأن الحساب «مهيأ لكنه غير متاح في مسار الأمر هذا» بدلًا من التعطل أو الإبلاغ خطأً بأن الحساب غير مهيأ.

حزم الحزم

قد يتضمن دليل Plugin ملف package.json يحتوي على openclaw.extensions:

{  "name": "my-pack",  "openclaw": {    "extensions": ["./src/safety.ts", "./src/tools.ts"],    "setupEntry": "./src/setup-entry.ts"  }}

يصبح كل إدخال Plugin. إذا أدرجت الحزمة امتدادات متعددة، يصبح معرّف Plugin هو <manifestOrPackageName>/<fileBase> (تكون الأولوية لمعرّف البيان عند وجوده؛ وإلا فيُستخدم اسم package.json غير ذي النطاق).

إذا كان Plugin الخاص بك يستورد تبعيات npm، فثبّتها في ذلك الدليل حتى يكون node_modules متاحًا (npm install / pnpm install).

حاجز أمني: يجب أن يبقى كل إدخال في openclaw.extensions داخل دليل Plugin بعد حل الروابط الرمزية. تُرفض الإدخالات التي تخرج من دليل الحزمة.

ملاحظة أمنية: يثبّت openclaw plugins install تبعيات Plugin باستخدام npm install --omit=dev --ignore-scripts محلي للمشروع (من دون نصوص دورة الحياة، ومن دون تبعيات تطوير في وقت التشغيل)، مع تجاهل إعدادات تثبيت npm العامة الموروثة. حافظ على أشجار تبعيات Plugin «JS/TS خالصة» وتجنب الحزم التي تتطلب عمليات بناء postinstall.

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

اختياري: يمكن لـ openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen إشراك Plugin قناة في مسار setupEntry نفسه أثناء مرحلة بدء تشغيل Gateway السابقة للاستماع، حتى عندما تكون القناة مهيأة بالفعل.

استخدم هذا فقط عندما يغطي setupEntry بالكامل سطح بدء التشغيل الذي يجب أن يكون موجودًا قبل أن يبدأ Gateway الاستماع. عمليًا، يعني ذلك أن إدخال الإعداد يجب أن يسجّل كل قدرة مملوكة للقناة يعتمد عليها بدء التشغيل، مثل:

• تسجيل القناة نفسها
• أي مسارات HTTP يجب أن تكون متاحة قبل أن يبدأ Gateway الاستماع
• أي طرائق أو أدوات أو خدمات لـ Gateway يجب أن تكون موجودة خلال النافذة نفسها

إذا ظل إدخالك الكامل مالكًا لأي قدرة مطلوبة لبدء التشغيل، فلا تفعّل هذه العلامة. أبقِ Plugin على السلوك الافتراضي ودع OpenClaw يحمّل الإدخال الكامل أثناء بدء التشغيل.

يمكن للقنوات المضمّنة أيضًا نشر مساعدات سطح عقد مخصصة للإعداد فقط، يستطيع النواة الرجوع إليها قبل تحميل وقت تشغيل القناة الكامل. سطح الترقية الخاص بالإعداد حاليًا هو:

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

تستخدم النواة هذا السطح عندما تحتاج إلى ترقية تهيئة قديمة لقناة ذات حساب واحد إلى channels.<id>.accounts.* من دون تحميل إدخال Plugin الكامل. Matrix هو المثال المضمّن الحالي: فهو ينقل مفاتيح المصادقة/التمهيد فقط إلى حساب مُرقّى مسمّى عندما تكون الحسابات المسمّاة موجودة بالفعل، ويمكنه الاحتفاظ بمفتاح حساب افتراضي مهيأ وغير قياسي بدلًا من إنشاء accounts.default دائمًا.

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

عندما تتضمن أسطح بدء التشغيل هذه طرائق RPC لـ Gateway، فأبقها ضمن بادئة خاصة بـ Plugin. تظل نطاقات إدارة النواة (config.*، exec.approvals.*، wizard.*، update.*) محجوزة وتُحل دائمًا إلى operator.admin، حتى إذا طلب Plugin نطاقًا أضيق.

مثال:

{  "name": "@scope/my-channel",  "openclaw": {    "extensions": ["./index.ts"],    "setupEntry": "./setup-entry.ts",    "startup": {      "deferConfiguredChannelFullLoadUntilAfterListen": true    }  }}

بيانات تعريف دليل القنوات

يمكن لإضافات القنوات الإعلان عن بيانات تعريف الإعداد/الاكتشاف عبر openclaw.channel وعن تلميحات التثبيت عبر openclaw.install. يحافظ ذلك على خلو دليل النواة من البيانات.

مثال:

{  "name": "@openclaw/nextcloud-talk",  "openclaw": {    "extensions": ["./index.ts"],    "channel": {      "id": "nextcloud-talk",      "label": "Nextcloud Talk",      "selectionLabel": "Nextcloud Talk (self-hosted)",      "docsPath": "/channels/nextcloud-talk",      "docsLabel": "nextcloud-talk",      "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.",      "order": 65,      "aliases": ["nc-talk", "nc"]    },    "install": {      "npmSpec": "@openclaw/nextcloud-talk",      "localPath": "<bundled-plugin-local-path>",      "defaultChoice": "npm"    }  }}

حقول openclaw.channel المفيدة إلى جانب المثال الأدنى:

• detailLabel: تسمية ثانوية لأسطح الدليل/الحالة الأكثر تفصيلًا
• docsLabel: تجاوز نص رابط التوثيق
• preferOver: معرّفات Plugin/القنوات ذات الأولوية الأدنى التي ينبغي أن يتفوق عليها إدخال الدليل هذا
• selectionDocsPrefix، selectionDocsOmitLabel، selectionExtras: عناصر تحكم في نص سطح الاختيار
• markdownCapable: يحدد القناة على أنها تدعم Markdown لقرارات تنسيق الرسائل الصادرة
• exposure.configured: يخفي القناة من أسطح قوائم القنوات المهيأة عند ضبطه على false
• exposure.setup: يخفي القناة من منتقيات الإعداد/التهيئة التفاعلية عند ضبطه على false
• exposure.docs: يحدد القناة على أنها داخلية/خاصة لأسطح تنقل التوثيق
• showConfigured / showInSetup: أسماء بديلة قديمة ما زالت مقبولة للتوافق؛ يُفضّل exposure
• quickstartAllowFrom: يشرك القناة في تدفق البدء السريع القياسي allowFrom
• forceAccountBinding: يتطلب ربطًا صريحًا بالحساب حتى عند وجود حساب واحد فقط
• preferSessionLookupForAnnounceTarget: يفضّل البحث في الجلسة عند حل أهداف الإعلان

يمكن لـ OpenClaw أيضًا دمج أدلة قنوات خارجية (على سبيل المثال، تصدير سجل MPM). ضع ملف JSON في أحد المواقع التالية:

• ~/.openclaw/mpm/plugins.json
• ~/.openclaw/mpm/catalog.json
• ~/.openclaw/plugins/catalog.json

أو وجّه OPENCLAW_PLUGIN_CATALOG_PATHS (أو OPENCLAW_MPM_CATALOG_PATHS) إلى ملف JSON واحد أو أكثر (مفصولة بفاصلة/فاصلة منقوطة/PATH). يجب أن يحتوي كل ملف على { "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }. يقبل المحلل أيضًا "packages" أو "plugins" كأسماء بديلة قديمة لمفتاح "entries".

تعرض إدخالات دليل القنوات المُنشأة وإدخالات دليل تثبيت المزوّد حقائق موحّدة عن مصدر التثبيت بجانب كتلة openclaw.install الأولية. تحدد الحقائق الموحّدة ما إذا كانت مواصفة npm إصدارًا دقيقًا أم محددًا متغيرًا، وما إذا كانت بيانات التكامل المتوقعة موجودة، وما إذا كان مسار مصدر محلي متاحًا أيضًا. عندما تكون هوية الدليل/الحزمة معروفة، تحذّر الحقائق الموحّدة إذا انحرف اسم حزمة npm المحلّل عن تلك الهوية. كما تحذّر عندما تكون defaultChoice غير صالحة أو تشير إلى مصدر غير متاح، وعندما تكون بيانات تكامل npm موجودة من دون مصدر npm صالح. ينبغي للمستهلكين التعامل مع installSource بوصفه حقلًا اختياريًا إضافيًا حتى لا تضطر الإدخالات المُنشأة يدويًا ورقع توافق الدليل إلى توليده. يتيح ذلك للإعداد الأولي والتشخيص شرح حالة مستوى المصدر من دون استيراد وقت تشغيل Plugin.

ينبغي لإدخالات npm الخارجية الرسمية تفضيل npmSpec دقيق مع expectedIntegrity. تظل أسماء الحزم المجردة ووسوم التوزيع تعمل للتوافق، لكنها تعرض تحذيرات على مستوى المصدر حتى يتمكن الدليل من التوجه نحو عمليات تثبيت مثبتة الإصدارات ومتحقق من تكاملها من دون تعطيل إضافات Plugin الحالية. عندما يثبّت الإعداد الأولي من مسار دليل محلي، فإنه يسجّل إدخالًا مُدارًا في فهرس إضافات Plugin مع source: "path" وsourcePath نسبيًا إلى مساحة العمل عند الإمكان. يبقى مسار التحميل التشغيلي المطلق في plugins.load.paths؛ ويتجنب سجل التثبيت تكرار مسارات محطة العمل المحلية في التهيئة طويلة الأجل. يحافظ ذلك على ظهور عمليات تثبيت التطوير المحلية لتشخيصات مستوى المصدر من دون إضافة سطح ثانٍ يكشف مسار نظام ملفات أوليًا. يمثل جدول SQLite الدائم installed_plugin_index مصدر الحقيقة للتثبيت ويمكن تحديثه من دون تحميل وحدات وقت تشغيل Plugin. تكون خريطة installRecords فيه دائمة حتى عند فقدان بيان Plugin أو عدم صلاحيته؛ بينما تكون حمولة plugins عرضًا للبيان قابلًا لإعادة البناء.

إضافات محرك السياق

تمتلك إضافات محرك السياق تنسيق سياق الجلسة للإدخال والتجميع وCompaction. سجّلها من Plugin الخاص بك باستخدام api.registerContextEngine(id, factory)، ثم اختر المحرك النشط باستخدام plugins.slots.contextEngine.

استخدم ذلك عندما يحتاج Plugin الخاص بك إلى استبدال مسار السياق الافتراضي أو توسيعه بدلًا من مجرد إضافة البحث في الذاكرة أو الخطافات.

  export default function (api) {  api.registerContextEngine("lossless-claw", (ctx) => ({    info: { id: "lossless-claw", name: "Lossless Claw", ownsCompaction: true },    async ingest() {      return { ingested: true };    },    async assemble({ messages, sessionKey, availableTools, citationsMode }) {      return {        messages,        estimatedTokens: 0,        systemPromptAddition: buildMemorySystemPromptAddition({          availableTools: availableTools ?? new Set(),          citationsMode,          agentId: resolveSessionAgentId({ config: ctx.config, sessionKey }),          agentSessionKey: sessionKey,        }),      };    },    async compact() {      return { ok: true, compacted: false };    },  }));}

يعرض ctx الخاص بالمصنع القيم الاختيارية config وagentDir وworkspaceDir للتهيئة في وقت الإنشاء.

قد تعيد assemble() قيمة contextProjection عندما تكون للبيئة النشطة سلسلة خلفية دائمة. احذفها للإسقاط القديم لكل دورة. أعد { mode: "thread_bootstrap", epoch } عندما ينبغي حقن السياق المجمّع مرة واحدة في سلسلة خلفية وإعادة استخدامه حتى تتغير الحقبة. غيّر الحقبة بعد تغير السياق الدلالي للمحرك، مثلًا بعد مرور Compaction يملكه المحرك. قد تحافظ المضيفات على بيانات تعريف استدعاء الأدوات وشكل الإدخال ونتائج الأدوات المنقّحة في إسقاط تمهيد السلسلة، حتى تحتفظ السلاسل الخلفية الجديدة باستمرارية الأدوات من دون نسخ الحمولات الأولية الحاملة للأسرار.

إذا كان محركك لا يملك خوارزمية Compaction، فأبقِ compact() منفّذة وفوّضها صراحةً:

   buildMemorySystemPromptAddition,  delegateCompactionToRuntime,} from "openclaw/plugin-sdk/core"; export default function (api) {  api.registerContextEngine("my-memory-engine", (ctx) => ({    info: {      id: "my-memory-engine",      name: "My Memory Engine",      ownsCompaction: false,    },    async ingest() {      return { ingested: true };    },    async assemble({ messages, sessionKey, availableTools, citationsMode }) {      return {        messages,        estimatedTokens: 0,        systemPromptAddition: buildMemorySystemPromptAddition({          availableTools: availableTools ?? new Set(),          citationsMode,          agentId: resolveSessionAgentId({ config: ctx.config, sessionKey }),          agentSessionKey: sessionKey,        }),      };    },    async compact(params) {      return await delegateCompactionToRuntime(params);    },  }));}

إضافة قدرة جديدة

عندما يحتاج Plugin إلى سلوك لا تلائمه واجهة API الحالية، فلا تتجاوز نظام Plugin عبر وصول داخلي خاص. أضف القدرة المفقودة.

التسلسل الموصى به:

1. عرّف عقد النواة. حدّد السلوك المشترك الذي ينبغي أن تمتلكه النواة: السياسة، والبديل الاحتياطي، ودمج الإعدادات، ودورة الحياة، والدلالات الموجّهة للقنوات، وشكل مساعد وقت التشغيل.
2. أضف أسطح تسجيل/وقت تشغيل مكتوبة الأنواع للـ Plugin. وسّع OpenClawPluginApi و/أو api.runtime بأصغر سطح قدرة مكتوب الأنواع ومفيد.
3. اربط مستهلكي النواة + القناة/الميزة. ينبغي للقنوات وPlugins الميزات استهلاك القدرة الجديدة عبر النواة، لا باستيراد تنفيذ مورّد مباشرةً.
4. سجّل تنفيذات المورّدين. تسجّل Plugins المورّدين بعد ذلك واجهاتها الخلفية ضمن القدرة.
5. أضف تغطية للعقد. أضف اختبارات كي تظل الملكية وشكل التسجيل صريحين بمرور الوقت.

بهذه الطريقة يظل OpenClaw ذا نهج محدد دون أن يصبح مرتبطًا برمجيًا برؤية مزوّد واحد. راجع دليل وصفات القدرات للحصول على قائمة تحقق عملية للملفات ومثال تطبيقي.

قائمة تحقق القدرة

عندما تضيف قدرة جديدة، ينبغي للتنفيذ عادةً أن يطال هذه الأسطح معًا:

• أنواع عقد النواة في src/<capability>/types.ts
• مشغّل النواة/مساعد وقت التشغيل في src/<capability>/runtime.ts
• سطح تسجيل API الخاص بالـ Plugin في src/plugins/types.ts
• توصيل سجل Plugin في src/plugins/registry.ts
• إتاحة وقت تشغيل Plugin في src/plugins/runtime/* عندما تحتاج Plugins الميزات/القنوات إلى استهلاكه
• مساعدات الالتقاط/الاختبار في src/test-utils/plugin-registration.ts
• تأكيدات الملكية/العقد في src/plugins/contracts/registry.ts
• وثائق المشغّل/Plugin في docs/

إذا كان أحد هذه الأسطح مفقودًا، فهذه عادةً علامة على أن القدرة لم تُدمج بالكامل بعد.

قالب القدرة

النمط الأدنى:

// core contractexport type VideoGenerationProviderPlugin = {  id: string;  label: string;  generateVideo: (req: VideoGenerationRequest) => Promise<VideoGenerationResult>;}; // plugin APIapi.registerVideoGenerationProvider({  id: "openai",  label: "OpenAI",  async generateVideo(req) {    return await generateOpenAiVideo(req);  },}); // shared runtime helper for feature/channel pluginsconst clip = await api.runtime.videoGeneration.generate({  prompt: "Show the robot walking through the lab.",  cfg,});

نمط اختبار العقد (يكشف src/plugins/contracts/registry.ts عمليات بحث الملكية مثل providerContractPluginIds؛ وتتحقق الاختبارات من أن قائمة contracts.videoGenerationProviders الخاصة بـ Plugin تطابق ما يسجله فعليًا):

expect(pluginManifest.contracts?.videoGenerationProviders).toEqual(["openai"]);

يحافظ ذلك على بساطة القاعدة:

• تمتلك النواة عقد القدرة + التنسيق
• تمتلك Plugins المورّدين تنفيذات المورّدين
• تستهلك Plugins الميزات/القنوات مساعدات وقت التشغيل
• تُبقي اختبارات العقد الملكية صريحة

ذو صلة

• معمارية Plugin — نموذج القدرة العام وأشكاله
• المسارات الفرعية لحزمة تطوير Plugin
• إعداد حزمة تطوير Plugin
• بناء Plugins