نظرة عامة على حزمة تطوير البرمجيات للـ Plugin

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

اصطلاح الاستيراد

استورد دائمًا من مسار فرعي محدد:

كل مسار فرعي هو وحدة صغيرة مستقلة بذاتها. يحافظ ذلك على سرعة بدء التشغيل ويمنع مشكلات التبعيات الدائرية. بالنسبة إلى مساعدات نقاط الدخول/البناء الخاصة بالقنوات، فضّل openclaw/plugin-sdk/channel-core؛ واحتفظ بـopenclaw/plugin-sdk/core للسطح الأشمل والمساعدات المشتركة مثل buildChannelConfigSchema.

بالنسبة إلى إعداد القناة، انشر مخطط JSON المملوك للقناة عبر openclaw.plugin.json#channelConfigs. المسار الفرعي plugin-sdk/channel-config-schema مخصص لأساسيات المخطط المشتركة والمنشئ العام. تستخدم الـ plugins المضمّنة في OpenClaw المسار plugin-sdk/bundled-channel-config-schema للاحتفاظ بمخططات القنوات المضمّنة. تظل صادرات التوافق المهملة متاحة على plugin-sdk/channel-config-schema-legacy؛ ولا يمثل أيٌّ من المسارين الفرعيين للمخططات المضمّنة نمطًا يُحتذى به للـ plugins الجديدة.

مرجع المسارات الفرعية

تُتاح عُدّة تطوير البرمجيات الخاصة بالـ Plugin في صورة مجموعة من المسارات الفرعية الضيقة المجمّعة حسب المجال (نقطة دخول الـ Plugin، والقناة، والمزوّد، والمصادقة، ووقت التشغيل، والإمكانات، والذاكرة، ومساعدات الـ plugins المضمّنة المحجوزة). للاطلاع على الفهرس الكامل، مجمّعًا ومزوّدًا بالروابط، راجع المسارات الفرعية لعُدّة تطوير البرمجيات الخاصة بالـ Plugin.

توجد قائمة نقاط دخول المصرّف في scripts/lib/plugin-sdk-entrypoints.json؛ وتُولّد صادرات الحزمة من المجموعة الفرعية العامة بعد استبعاد مسارات الاختبار/المسارات الداخلية المحلية للمستودع المدرجة في scripts/lib/plugin-sdk-private-local-only-subpaths.json. شغّل pnpm plugin-sdk:surface لتدقيق عدد الصادرات العامة. تُتتبّع المسارات الفرعية العامة المهملة التي مضى عليها وقت كافٍ ولم تعد مستخدمة في شفرة الإنتاج للامتدادات المضمّنة في scripts/lib/plugin-sdk-deprecated-public-subpaths.json؛ كما تُتتبّع ملفات التصدير الجامعة الواسعة المهملة في scripts/lib/plugin-sdk-deprecated-barrel-subpaths.json.

واجهة برمجة تطبيقات التسجيل

تتلقى دالة الاستدعاء الراجع register(api) كائن OpenClawPluginApi الذي يتضمن الأساليب التالية:

تسجيل الإمكانات

يجب أيضًا على مزوّدي العمال التصريح بمعرّفهم في contracts.workerProviders. تُخزّن النواة النية الدائمة قبل provision(profile, operationId). يتحقق المزوّدون من الإعدادات قبل التخصيص الخارجي ويرمون WorkerProviderError عند الرفض الدائم للملف التعريفي. يجب أن يتبنّى provision عقد الإيجار نفسه عند تكرار معرّف العملية. تُخزّن النواة إعدادات الملف التعريفي المتحقق منها مع عقد الإيجار، وتزوّد destroy({ leaseId, profile }) بتلك اللقطة، ويجب أن تكون هذه العملية عديمة التأثير عند التكرار، كما تزوّد بها inspect({ leaseId, profile }) التي تُرجع active أو destroyed أو unknown. يتيح ذلك للمزوّدين توجيه استدعاءات دورة الحياة بعد إعادة تشغيل Gateway أو إزالة ملف تعريفي مسمّى. تستخدم نقاط نهاية SSH مرجع SecretRef للحقل keyRef، ولا تستخدم أبدًا مادة المفتاح ضمن السطر، وتتضمن hostKey من مخرجات التوفير الموثوقة بالتنسيق algorithm base64 تمامًا، من دون اسم مضيف أو تعليق. تثبّت النواة hostKey ولا تثق مطلقًا بمفتاح من الاتصال الأول. يمكن للمزوّد الذي ينشئ keyRef ديناميكيًا تنفيذ resolveSshIdentity({ leaseId, profile, keyRef })؛ وعند وجوده، يكون هذا المحلّل هو المرجع الحاسم، بينما يستخدم المزوّدون الذين لا يملكونه محلّل الأسرار العام المضبوط. يمكن للمزوّدين الذين لديهم عقود إيجار قابلة للتجديد تنفيذ renew(leaseId) أيضًا. يجب أن ترمي inspect خطأً عند حالات الفشل العابرة أو غير القابلة للحسم؛ ولا تُرجع unknown إلا عند غياب مؤكّد. تضع النواة علامة «يتيم» على سجل محلي نشط، أو تتعامل مع الغياب بوصفه اكتمالًا للإزالة بعد طلب إتلاف مخزّن.

يجب أيضًا إدراج مزوّدي التضمين المسجلين باستخدام api.registerEmbeddingProvider(...) في contracts.embeddingProviders ضمن بيان الـ Plugin. يمثل هذا سطح التضمين العام لتوليد المتجهات القابل لإعادة الاستخدام. يمكن لبحث الذاكرة استهلاك سطح المزوّد العام هذا. أما واجهة api.registerMemoryEmbeddingProvider(...) و contracts.memoryEmbeddingProviders الأقدم فهي واجهة توافق مهملة إلى أن يُرحّل مزوّدو الذاكرة الحاليون المخصّصون.

يظل مزوّدو الذاكرة المخصّصون الذين لا يزالون يكشفون batchEmbed(...) في وقت التشغيل ضمن عقد التجميع الحالي لكل ملف، ما لم يضبط وقت تشغيلهم صراحةً sourceWideBatchEmbed: true. يتيح هذا الاشتراك لمضيف الذاكرة إرسال أجزاء من عدة ملفات ذاكرة معدّلة ومصادر مفعّلة ضمن استدعاء batchEmbed(...) واحد بما لا يتجاوز حدود الدفعة لدى المضيف. يجب على محوّلات الدفعات التي ترفع ملفات طلبات JSONL تقسيم مهام المزوّد قبل بلوغ حد حجم الرفع وكذلك حد عدد الطلبات. يجب أن يعيد المزوّد تضمينًا واحدًا لكل جزء إدخال وبالترتيب نفسه الوارد في batch.chunks؛ احذف العلامة عندما يتوقع المزوّد دفعات محلية لكل ملف أو لا يستطيع الحفاظ على ترتيب الإدخال عبر مهمة أوسع تشمل المصدر بأكمله.

الأدوات والأوامر

استخدم defineToolPlugin للـ plugins البسيطة المخصصة للأدوات فقط ذات أسماء الأدوات الثابتة. استخدم api.registerTool(...) مباشرةً للـ plugins المختلطة أو لتسجيل الأدوات الديناميكي بالكامل.

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

يمكن أن تكون إدخالات الإرشاد سلاسل نصية قديمة تُطبّق على كل سطح من أسطح المطالبات، أو إدخالات منظّمة:

agentPromptGuidance: [  "Global command hint.",  { text: "Only show this in the main OpenClaw prompt.", surfaces: ["openclaw_main"] },];

قد تتضمن surfaces المنظّمة openclaw_main أو codex_app_server أو cli_backend أو acp_backend أو subagent. يظل pi_main اسمًا بديلًا مهملًا لـopenclaw_main. احذف surfaces عند قصد تطبيق الإرشاد على كل الأسطح. لا تمرّر مصفوفة surfaces فارغة؛ إذ تُرفض حتى لا يتحول فقدان النطاق غير المقصود إلى نص عام للمطالبة.

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

تُنفَّذ أوامر مضيف Node على مضيف Node المتصل، وليس داخل عملية Gateway. إذا كان agentTool موجودًا، تنشر Node واصفًا بعد اتصال ناجح بـ Gateway؛ ولا يعرضه Gateway لعمليات تشغيل الوكيل إلا أثناء اتصال تلك Node، وفقط إذا كان command الخاص بالواصف ضمن سطح الأوامر المعتمد في Node. عيّن agentTool.defaultPlatforms لإدراج أمر غير خطير في قائمة السماح الافتراضية لأوامر Node؛ وإلا فاشترط gateway.nodes.allowCommands صريحًا أو سياسة استدعاء Node. يجب أن يكون agentTool.name آمنًا لمزوّد الخدمة: يبدأ بحرف، ويستخدم الحروف أو الأرقام أو الشرطات السفلية أو الواصلات فقط، وألا يتجاوز 64 محرفًا. يمكن لأدوات Node المدعومة بـ MCP تعيين بيانات agentTool.mcp الوصفية لكي تتمكن أسطح الكتالوج والبحث عن الأدوات من إظهار هوية خادم/أداة MCP البعيدة، لكن التنفيذ يظل يمر عبر أمر Node المُعلن.

البنية التحتية

تتلقى أدوات إنشاء ملحق موجّه الذاكرة سياقًا اختياريًا يتضمن agentId وagentSessionKey وsandboxed. وتتلقى استدعاءات search وget في ملحق مجموعة الذاكرة سياقًا اختياريًا يتضمن agentId وsandboxed. ينبغي أن تحل Plugins التي تملك تخزينًا تابعًا للوكيل ذلك التخزين لكل استدعاء بدلًا من التقاط مسار عام واحد أثناء التسجيل. إذا كان معرّف الوكيل مطلوبًا لكنه مفقود في عملية متعددة الوكلاء، فارفض العملية افتراضيًا بدلًا من اختيار وكيل اعتباطي.

يمكن للمعالجات التفاعلية في Telegram إرجاع { submitText } لتوجيه النص عبر مسار الوكيل الوارد المعتاد في Telegram بعد نجاح المعالج. يحتفظ OpenClaw بزر رد الاتصال عندما تتخطى سياسة الوارد النص أو تفشل المعالجة، بحيث يستطيع المستخدم إعادة المحاولة بعد تغيّر الحالة المانعة. حقل النتيجة هذا خاص بـ Telegram؛ وتحتفظ القنوات الأخرى بعقود نتائجها التفاعلية الخاصة.

خطافات المضيف لـ Plugins الخاصة بسير العمل

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

يضيف واصف surface: "tab" علامة تبويب إلى الشريط الجانبي في واجهة التحكم. تُعلَن واصفات علامات تبويب Plugins النشطة لعملاء لوحة المعلومات في رسالة ترحيب Gateway (controlUiTabs)، ولذلك لا تظهر علامة التبويب إلا أثناء تمكين Plugin. يمكن لـ Plugins المضمّنة توفير عرض أصلي متكامل في لوحة المعلومات لعلامة التبويب الخاصة بها؛ ويمكن لـ Plugins الأخرى تعيين path إلى مسار HTTP خاص بـ Plugin (راجع api.registerHttpRoute(...)) تعرضه لوحة المعلومات داخل إطار معزول. يمثّل icon تلميحًا لاسم أيقونة في لوحة المعلومات، ويختار group قسم الشريط الجانبي (control أو agent)، ويحدّد order ترتيب علامات تبويب Plugins، ويخفي requiredScopes علامة التبويب عن الاتصالات التي تفتقر إلى نطاقات المشغّل تلك:

api.session.controls.registerControlUiDescriptor({  surface: "tab",  id: "logbook",  label: "Logbook",  description: "Your day as a timeline, built from screen snapshots.",  icon: "sun",  group: "control",  requiredScopes: ["operator.write"],});

استخدم مساحات الأسماء المجمّعة في شيفرة Plugin الجديدة:

• api.session.state.registerSessionExtension(...)
• api.session.workflow.enqueueNextTurnInjection(...)
• api.session.workflow.registerSessionSchedulerJob(...)
• api.session.workflow.sendSessionAttachment(...)
• api.session.workflow.scheduleSessionTurn(...)
• api.session.workflow.unscheduleSessionTurnsByTag(...)
• api.session.controls.registerSessionAction(...)
• api.session.controls.registerControlUiDescriptor(...)
• api.agent.events.registerAgentEventSubscription(...)
• api.agent.events.emitAgentEvent(...)
• api.runContext.setRunContext(...) / getRunContext(...) / clearRunContext(...)
• api.lifecycle.registerRuntimeLifecycle(...)

تظل الطرق المسطحة المكافئة متاحة كأسماء بديلة متقادمة للتوافق مع Plugins الحالية. لا تضف شيفرة Plugin جديدة تستدعي مباشرةً api.registerSessionExtension أو api.enqueueNextTurnInjection أو api.registerControlUiDescriptor أو api.registerRuntimeLifecycle أو api.registerAgentEventSubscription أو api.emitAgentEvent أو api.setRunContext أو api.getRunContext أو api.clearRunContext أو api.registerSessionSchedulerJob أو api.registerSessionAction أو api.sendSessionAttachment أو api.scheduleSessionTurn أو api.unscheduleSessionTurnsByTag.

تُعد scheduleSessionTurn(...) وسيلة ملائمة محددة النطاق بالجلسة فوق مجدول Cron في Gateway. يمتلك Cron التوقيت وينشئ سجل مهمة الخلفية عند تشغيل الدورة؛ ولا يقيّد Plugin SDK سوى الجلسة المستهدفة، والتسمية التي يملكها Plugin، والتنظيف. استخدم api.runtime.tasks.managedFlows داخل الدورة المجدولة عندما يحتاج العمل نفسه إلى حالة دائمة متعددة الخطوات لـ Task Flow.

تفصل العقود الصلاحيات عن قصد:

• يمكن لـ Plugins الخارجية امتلاك امتدادات الجلسات، وواصفات واجهة المستخدم، والأوامر، والبيانات الوصفية للأدوات، وعمليات الحقن في الدورة التالية، والخطافات العادية.
• تعمل سياسات الأدوات الموثوقة قبل خطافات before_tool_call العادية، ويثق بها المضيف. تعمل السياسات المضمّنة أولًا؛ وتتطلب سياسات Plugins المثبّتة تمكينًا صريحًا بالإضافة إلى معرّفاتها المحلية في contracts.trustedToolPolicies، ثم تعمل وفق ترتيب تحميل Plugins. تقتصر معرّفات السياسات على Plugin الذي سجّلها.
• ملكية الأوامر المحجوزة متاحة فقط للمكوّنات المضمّنة. ينبغي لـ Plugins الخارجية استخدام أسماء أو أسماء بديلة لأوامرها الخاصة.
• يعطّل allowPromptInjection=false الخطافات التي تعدّل الموجّه، بما فيها agent_turn_prepare وbefore_prompt_build و heartbeat_prompt_contribution، وحقول الموجّه من before_agent_start القديم، وenqueueNextTurnInjection.

أمثلة على مستهلكين لا يستخدمون وضع الخطة:

تسجيل اكتشاف Gateway

تتيح api.registerGatewayDiscoveryService(...) للـ Plugin الإعلان عن Gateway النشط عبر وسيلة اكتشاف محلية مثل mDNS/Bonjour. يستدعي OpenClaw الخدمة أثناء بدء تشغيل Gateway عندما يكون الاكتشاف المحلي مفعّلًا، ويمرّر منافذ Gateway الحالية وبيانات تلميحات TXT غير السرية، ويستدعي معالج stop المُعاد أثناء إيقاف تشغيل Gateway.

api.registerGatewayDiscoveryService({  id: "my-discovery",  async advertise(ctx) {    const handle = await startMyAdvertiser({      gatewayPort: ctx.gatewayPort,      tls: ctx.gatewayTlsEnabled,      displayName: ctx.machineDisplayName,    });    return { stop: () => handle.stop() };  },});

يجب ألا تتعامل Plugins اكتشاف Gateway مع قيم TXT المُعلَن عنها باعتبارها أسرارًا أو مصادقة. الاكتشاف تلميح توجيه؛ وتظل مصادقة Gateway وتثبيت TLS مسؤولين عن الثقة.

البيانات الوصفية لتسجيل CLI

تقبل api.registerCli(registrar, opts?) نوعين من البيانات الوصفية للأوامر:

• commands: أسماء أوامر صريحة يملكها المسجّل
• descriptors: واصفات أوامر وقت التحليل المستخدمة لمساعدة CLI، والتوجيه، والتسجيل الكسول لـ CLI الخاص بالـ Plugin
• parentPath: مسار أمر أب اختياري لمجموعات الأوامر المتداخلة، مثل ["nodes"]

بالنسبة إلى ميزات العُقد المقترنة، يُفضّل استخدام api.registerNodeCliFeature(registrar, opts?). وهي مغلّف صغير حول api.registerCli(..., { parentPath: ["nodes"] }) وتجعل أوامر مثل openclaw nodes canvas ميزات عُقد صريحة يملكها Plugin.

إذا أردت أن يظل أمر Plugin محمّلًا بشكل كسول ضمن مسار CLI الجذري المعتاد، فقدّم descriptors تغطي كل جذر أمر من المستوى الأعلى يكشفه ذلك المسجّل.

api.registerCli(  async ({ program }) => {    const { registerMatrixCli } = await import("./src/cli.js");    registerMatrixCli({ program });  },  {    descriptors: [      {        name: "matrix",        description: "Manage Matrix accounts, verification, devices, and profile state",        hasSubcommands: true,      },    ],  },);

تتلقى الأوامر المتداخلة الأمر الأب المحلول بوصفه program:

api.registerCli(  async ({ program }) => {    const { registerNodesCanvasCommands } = await import("./src/cli.js");    registerNodesCanvasCommands(program);  },  {    parentPath: ["nodes"],    descriptors: [      {        name: "canvas",        description: "Capture or render canvas content from a paired node",        hasSubcommands: true,      },    ],  },);

استخدم commands وحدها فقط عندما لا تحتاج إلى تسجيل CLI جذري كسول. يظل مسار التوافق الاستباقي هذا مدعومًا، لكنه لا يثبّت عناصر نائبة مدعومة بالواصفات للتحميل الكسول وقت التحليل.

تسجيل واجهة CLI الخلفية

تتيح api.registerCliBackend(...) للـ Plugin امتلاك الإعداد الافتراضي لواجهة خلفية محلية لـ CLI للذكاء الاصطناعي مثل claude-cli أو my-cli.

• يصبح id للواجهة الخلفية بادئة المزوّد في مراجع النماذج مثل my-cli/gpt-5.
• يستخدم config للواجهة الخلفية البنية نفسها المستخدمة في agents.defaults.cliBackends.<id>.
• تظل الأولوية لإعداد المستخدم. يدمج OpenClaw قيمة agents.defaults.cliBackends.<id> فوق الإعداد الافتراضي للـ Plugin قبل تشغيل CLI.
• استخدم normalizeConfig عندما تحتاج واجهة خلفية إلى عمليات إعادة كتابة توافقية بعد الدمج (مثل تطبيع بُنى العلامات القديمة).
• استخدم resolveExecutionArgs لعمليات إعادة كتابة argv محددة النطاق للطلب وتنتمي إلى لهجة CLI، مثل ربط مستويات التفكير في OpenClaw بعلامة جهد أصلية. يتلقى الخطاف ctx.executionMode؛ استخدم "side-question" لإضافة علامات عزل أصلية للواجهة الخلفية لاستدعاءات /btw المؤقتة. وإذا كانت تلك العلامات تعطّل الأدوات الأصلية بشكل موثوق في CLI تكون أدواته مفعّلة دائمًا بخلاف ذلك، فأعلن أيضًا sideQuestionToolMode: "disabled".
• يمكن للواجهات الخلفية القادرة على تعطيل جميع الأدوات الأصلية لتشغيل محدد أن تعلن nativeToolMode: "selectable". تمرّر الاستدعاءات المقيّدة صفًا فارغًا في ctx.toolAvailability.native بالإضافة إلى قائمة سماح MCP دقيقة ومعزولة عن المضيف؛ ويجب أن يفرض resolveExecutionArgs كليهما على argv النهائي للتشغيل الجديد أو المستأنف. يفشل OpenClaw في وضع مغلق إذا تعذّر على الواجهة الخلفية تنفيذ ذلك.

للاطلاع على دليل تأليف شامل من البداية إلى النهاية، راجع Plugins الواجهات الخلفية لـ CLI.

الخانات الحصرية

محوّلات تضمين الذاكرة المهملة

• تُعد registerMemoryCapability واجهة API الحصرية المفضّلة لـ Plugin الذاكرة.
• قد تكشف registerMemoryCapability أيضًا عن publicArtifacts.listArtifacts(...) لكي تتمكن Plugins المصاحبة من استهلاك عناصر الذاكرة المصدّرة عبر openclaw/plugin-sdk/memory-host-core بدلًا من الوصول إلى التخطيط الخاص لـ Plugin ذاكرة بعينه.
• تُعد registerMemoryPromptSection وregisterMemoryFlushPlan و registerMemoryRuntime واجهات API حصرية متوافقة مع الأنظمة القديمة لـ Plugin الذاكرة.
• يمكن لـ MemoryFlushPlan.model تثبيت دورة التفريغ على مرجع provider/model دقيق، مثل ollama/qwen3:8b، من دون وراثة سلسلة التراجع النشطة.
• أصبحت registerMemoryEmbeddingProvider مهملة. ينبغي لمزوّدي التضمين الجدد استخدام api.registerEmbeddingProvider(...) و contracts.embeddingProviders.
• يستمر مزوّدو الذاكرة الحاليون في العمل خلال فترة الترحيل، لكن فحص Plugin يبلّغ عن ذلك بوصفه دين توافق للـ Plugins غير المضمّنة.

الأحداث ودورة الحياة

راجع خطافات Plugin للاطلاع على أمثلة، وأسماء الخطافات الشائعة، ودلالات الحماية.

دلالات قرارات الخطافات

before_install هو خطاف دورة حياة لوقت تشغيل Plugin، وليس سطح سياسة التثبيت الخاصة بالمشغّل. استخدم security.installPolicy عندما يجب أن يشمل قرار السماح/الحظر مسارات التثبيت أو التحديث المستندة إلى CLI وGateway.

• before_tool_call: تُعدّ إعادة { block: true } نهائية. بمجرد أن يضبطها أي معالج، يتم تخطي المعالجات ذات الأولوية الأدنى.
• before_tool_call: تُعامل إعادة { block: false } على أنها عدم اتخاذ قرار (مثل حذف block)، وليست تجاوزًا.
• before_install: تُعدّ إعادة { block: true } نهائية. بمجرد أن يضبطها أي معالج، يتم تخطي المعالجات ذات الأولوية الأدنى.
• before_install: تُعامل إعادة { block: false } على أنها عدم اتخاذ قرار (مثل حذف block)، وليست تجاوزًا.
• reply_dispatch: تُعدّ إعادة { handled: true, ... } نهائية. بمجرد أن يتولى أي معالج الإرسال، يتم تخطي المعالجات ذات الأولوية الأدنى ومسار الإرسال الافتراضي للنموذج.
• message_sending: تُعدّ إعادة { cancel: true } نهائية. بمجرد أن يضبطها أي معالج، يتم تخطي المعالجات ذات الأولوية الأدنى.
• message_sending: تُعامل إعادة { cancel: false } على أنها عدم اتخاذ قرار (مثل حذف cancel)، وليست تجاوزًا.
• message_received: استخدم الحقل المنمّط threadId عندما تحتاج إلى توجيه السلسلة/الموضوع الوارد. واحتفظ بـmetadata للإضافات الخاصة بالقناة.
• message_sending: استخدم حقول التوجيه المنمّطة replyToId / threadId قبل الرجوع إلى metadata الخاصة بالقناة.
• gateway_start: استخدم ctx.config وctx.workspaceDir وctx.getCron?.() لحالة بدء التشغيل التي يملكها Gateway بدلًا من الاعتماد على خطافات gateway:startup الداخلية. قد يظل Cron قيد التحميل عند هذه النقطة.
• cron_reconciled: أعد بناء إسقاط Cron خارجي كامل بعد بدء التشغيل أو إعادة تحميل المجدول. يتضمن reason وحالة enabled الفعلية، بما في ذلك enabled: false، بينما يعيد ctx.getCron?.() المجدول المتصالح الدقيق. مرّر ctx.abortSignal إلى عمل الإسقاط الدائم؛ إذ يُجهض عندما تحل لقطة أحدث للمجدول محل تلك اللقطة أو عند إغلاق Gateway.
• cron_changed: راقب تغييرات دورة حياة Cron التي يملكها Gateway. أحداث scheduled وremoved هي تلميحات تصالح بعد الاعتماد، وليست سجل فروق مرتبًا. يغيب event.nextRunAtMs في الحدث المجدول عندما لا تكون للمهمة عملية تنبيه تالية؛ ويظل الحدث المُزال يحمل لقطة المهمة المحذوفة.

ينبغي لمجدولات التنبيه الخارجية إزالة ارتداد أحداث cron_changed أو دمجها، ثم إعادة قراءة العرض الدائم الكامل من المجدول الذي التقطه cron_reconciled آخر مرة. لا تعتمد المجدول من سياق cron_changed: فقد يتداخل تلميح منفصل من مجدول أقدم مع إعادة تحميل لاحقة.

استخدم cron_reconciled كمشغّل للقطة الكاملة للحالة الدائمة المحمّلة عند بدء تشغيل Gateway أو استبدال المجدول. ولا يُعاد تشغيله عند إعادة تحميل ساخنة خاصة بالـPlugin فقط. تعمل معالجات المراقبة بالتوازي، ويمكن أن تتداخل عمليات الإرسال دون انتظار النتيجة، لذلك يجب ألا يعتمد المستهلكون على ترتيب اكتمال الأحداث. أبقِ OpenClaw مصدر الحقيقة لعمليات التحقق من الاستحقاق والتنفيذ.

للاطلاع على محوّل أحادي التنفيذ يتضمن استبدالًا دائمًا، وإعادة المحاولة/التراجع، وإيقاف تشغيل نظيف، راجع إسقاط Cron خارجي آمن.

حقول كائن API

اصطلاح الوحدات الداخلية

داخل الـPlugin الخاص بك، استخدم ملفات التصدير التجميعية المحلية للاستيرادات الداخلية:

my-plugin/  api.ts            # Public exports for external consumers  runtime-api.ts    # Internal-only runtime exports  index.ts          # Plugin entry point  setup-entry.ts    # Lightweight setup-only entry (optional)

تفضّل الأسطح العامة للـPlugin المضمّن المحمّلة عبر الواجهة (api.ts وruntime-api.ts وindex.ts وsetup-entry.ts وملفات الدخول العامة المشابهة) لقطة إعداد وقت التشغيل النشطة عندما يكون OpenClaw قيد التشغيل بالفعل. وإذا لم توجد لقطة لوقت التشغيل بعد، فإنها ترجع إلى ملف الإعداد المحلول على القرص. ينبغي تحميل واجهات الـPlugin المضمّن المجمّعة عبر محمّلات واجهات الـPlugin الخاصة بـOpenClaw؛ فالاستيرادات المباشرة من dist/extensions/... تتجاوز فحوصات البيان والملف الجانبي لوقت التشغيل التي تستخدمها عمليات التثبيت المجمّعة للشيفرة التي يملكها الـPlugin.

يمكن لـPlugins الموفّرين كشف ملف تجميعي لعقد محلي ضيق خاص بالـPlugin عندما يكون المساعد خاصًا بالموفّر عمدًا ولا ينتمي بعد إلى مسار فرعي عام في SDK. أمثلة مضمّنة:

• Anthropic: واجهة عامة عبر api.ts / contract-api.ts لمساعدات ترويسة Claude التجريبية وتدفق service_tier.
• @openclaw/openai-provider: يصدّر api.ts منشئات الموفّرين، ومساعدات النموذج الافتراضي، ومنشئات موفّري الوقت الحقيقي.
• @openclaw/openrouter-provider: يصدّر api.ts منشئ الموفّر إلى جانب مساعدات الإعداد الأولي/الإعداد.

ذو صلة