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

​

مسار التحميل

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 غير المضمّنة

​

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

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

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

​

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

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

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

​

نموذج السجل

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

​

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

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: ملخص الطلب الأصلي، وتلميح الفصل، ومعرّف المرسل، وبيانات تعريف المحادثة

​

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

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

​

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

​

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

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);
  },
});

​

أمثلة مضمّنة

​

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

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 فلا يدعمها.

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 لعقود القدرات تلك.

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.*

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,
});

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(...) اسمًا بديلًا للتوافق.

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 بنطاق إداري.

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,
  },
});

• احتفظ باختيار المزوّد وحل بيانات الاعتماد ودلالات الطلب المشتركة في الجزء الأساسي.
• استخدم مزوّدي البحث على الويب لعمليات نقل البحث الخاصة بالمورّد.
• ‏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

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

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

​

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

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

​

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

• يقرر 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 العامة.

​

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

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

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

​

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

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

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

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

​

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

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

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

​

حزم الحزم

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

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

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

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

​

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

{
  "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"
    }
  }
}

• 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/plugins.json
• ~/.openclaw/mpm/catalog.json
• ~/.openclaw/plugins/catalog.json

​

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

import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";
import { resolveSessionAgentId } from "openclaw/plugin-sdk/memory-host-core";

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 };
    },
  }));
}

import {
  buildMemorySystemPromptAddition,
  delegateCompactionToRuntime,
} from "openclaw/plugin-sdk/core";
import { resolveSessionAgentId } from "openclaw/plugin-sdk/memory-host-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);
    },
  }));
}

​

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

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

​

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

• أنواع عقد النواة في 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 contract
export type VideoGenerationProviderPlugin = {
  id: string;
  label: string;
  generateVideo: (req: VideoGenerationRequest) => Promise<VideoGenerationResult>;
};

// plugin API
api.registerVideoGenerationProvider({
  id: "openai",
  label: "OpenAI",
  async generateVideo(req) {
    return await generateOpenAiVideo(req);
  },
});

// shared runtime helper for feature/channel plugins
const clip = await api.runtime.videoGeneration.generate({
  prompt: "Show the robot walking through the lab.",
  cfg,
});

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

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

​

ذو صلة

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