ترحيل Plugin SDK

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

ما الذي يتغير

كان نظام Plugin القديم يوفر سطحين واسعين ومفتوحين يتيحان لـ Plugins استيراد أي شيء تحتاج إليه من نقطة دخول واحدة:

• openclaw/plugin-sdk/compat - استيراد واحد يعيد تصدير عشرات المساعدات. قُدّم لإبقاء Plugins الأقدم المعتمدة على الخطافات تعمل بينما كانت بنية Plugin الجديدة قيد البناء.
• openclaw/plugin-sdk/infra-runtime - حزمة مساعدات تشغيلية واسعة تمزج أحداث النظام، وحالة Heartbeat، وطوابير التسليم، ومساعدات الجلب/الوكيل، ومساعدات الملفات، وأنواع الموافقة، وأدوات غير ذات صلة.
• openclaw/plugin-sdk/config-runtime - حزمة توافق إعدادات واسعة ما تزال تحمل مساعدات التحميل/الكتابة المباشرة المهملة خلال نافذة الترحيل.
• openclaw/extension-api - جسر منح Plugins وصولاً مباشراً إلى مساعدات جانب المضيف مثل مشغّل الوكيل المضمّن.
• api.registerEmbeddedExtensionFactory(...) - خطاف Plugin مضمّن خاص بالمشغّل المضمّن فقط تمت إزالته، وكان يستطيع مراقبة أحداث المشغّل المضمّن مثل tool_result.

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

لا يزيل OpenClaw سلوك Plugin الموثق أو يعيد تفسيره في التغيير نفسه الذي يقدم بديلاً. يجب أن تمر تغييرات العقود الكاسرة أولاً عبر محول توافق، وتشخيصات، ومستندات، ونافذة إهمال. ينطبق ذلك على استيرادات SDK، وحقول البيان، وواجهات إعداد API، والخطافات، وسلوك التسجيل في وقت التشغيل.

لماذا تغير هذا

تسبب النهج القديم في مشكلات:

• بدء تشغيل بطيء - كان استيراد مساعد واحد يحمّل عشرات الوحدات غير ذات الصلة
• اعتماديات دائرية - جعلت إعادة التصدير الواسعة إنشاء دورات استيراد أمراً سهلاً
• سطح API غير واضح - لم تكن هناك طريقة لمعرفة أي الصادرات مستقرة وأيها داخلية

يصلح SDK Plugin الحديث هذا: فكل مسار استيراد (openclaw/plugin-sdk/\<subpath\>) هو وحدة صغيرة ومكتفية ذاتياً لها غرض واضح وعقد موثق.

اختفت أيضاً طبقات التسهيل القديمة للمزودين الخاصة بالقنوات المضمّنة. كانت طبقات المساعدة ذات العلامة القنوية اختصارات خاصة بمستودع أحادي، وليست عقود Plugin مستقرة. استخدم بدلاً منها مسارات SDK فرعية عامة وضيقة. داخل مساحة عمل Plugin المضمّنة، أبقِ المساعدات المملوكة للمزود داخل api.ts أو runtime-api.ts الخاصة بذلك Plugin.

أمثلة المزودين المضمّنين الحالية:

• يحتفظ Anthropic بمساعدات البث الخاصة بـ Claude في طبقة api.ts / contract-api.ts الخاصة به
• يحتفظ OpenAI ببناة المزودين، ومساعدات النموذج الافتراضي، وبناة مزود الوقت الحقيقي في api.ts الخاصة به
• يحتفظ OpenRouter بباني المزود ومساعدات الإعداد/التكوين في api.ts الخاصة به

خطة ترحيل Talk والصوت في الوقت الحقيقي

تنتقل شيفرة Talk الخاصة بالصوت في الوقت الحقيقي، والاتصالات الهاتفية، والاجتماعات، والمتصفح من مسك دفاتر الدور المحلي لكل سطح إلى متحكم جلسة Talk مشترك يصدّره openclaw/plugin-sdk/realtime-voice. يمتلك المتحكم الجديد مظروف أحداث Talk المشترك، وحالة الدور النشط، وحالة الالتقاط، وحالة الصوت الخارج، وسجل الأحداث الحديثة، ورفض الأدوار القديمة. ينبغي أن تظل Plugins المزودين مالكة لجلسات الوقت الحقيقي الخاصة بالمورّد؛ وينبغي أن تظل Plugins الأسطح مالكة لخصوصيات الالتقاط، والتشغيل، والاتصالات الهاتفية، والاجتماعات.

ترحيل Talk هذا كاسر ونظيف عمداً:

1. أبقِ متحكم/بدائيات وقت التشغيل المشتركة في plugin-sdk/realtime-voice.
2. انقل الأسطح المضمّنة إلى المتحكم المشترك: مرحّل المتصفح، وتسليم الغرفة المُدارة، ووقت الاتصال الصوتي الحقيقي، وSTT المتدفق للاتصال الصوتي، ووقت Google Meet الحقيقي، والضغط الأصلي للتحدث.
3. استبدل عائلات RPC القديمة الخاصة بـ Talk بواجهة API النهائية talk.session.* و talk.client.*.
4. أعلن عن قناة أحداث Talk حية واحدة في Gateway hello-ok.features.events: talk.event.
5. احذف نقطة نهاية HTTP القديمة للوقت الحقيقي وأي مسار لتجاوز التعليمات وقت الطلب.

ينبغي ألا تستدعي الشيفرة الجديدة createTalkEventSequencer(...) مباشرة إلا إذا كانت تنفذ محولاً منخفض المستوى أو أداة اختبار. فضّل المتحكم المشترك حتى لا يمكن إصدار أحداث نطاق الدور من دون معرف دور، ولا يمكن لاستدعاءات turnEnd / turnCancel القديمة مسح دور نشط أحدث، وتبقى أحداث دورة حياة الصوت الخارج متسقة عبر الاتصالات الهاتفية، والاجتماعات، ومرحل المتصفح، وتسليم الغرفة المُدارة، وعملاء Talk الأصليين.

شكل API العام المستهدف هو:

// Gateway-owned Talk session API.await gateway.request("talk.session.create", {  mode: "realtime",  transport: "gateway-relay",  brain: "agent-consult",  sessionKey: "main",});await gateway.request("talk.session.appendAudio", { sessionId, audioBase64 });await gateway.request("talk.session.cancelOutput", { sessionId, reason: "barge-in" });await gateway.request("talk.session.submitToolResult", {  sessionId,  callId,  result: { status: "working" },  options: { willContinue: true },});await gateway.request("talk.session.submitToolResult", {  sessionId,  callId,  result: { status: "already_delivered" },  options: { suppressResponse: true },});await gateway.request("talk.session.submitToolResult", { sessionId, callId, result });await gateway.request("talk.session.close", { sessionId }); // Client-owned provider session API.await gateway.request("talk.client.create", {  mode: "realtime",  transport: "webrtc",  brain: "agent-consult",  sessionKey: "main",});await gateway.request("talk.client.toolCall", { sessionKey, callId, name, args });await gateway.request("talk.client.steer", { sessionKey, text, mode: "steer" });

تستخدم جلسات WebRTC/provider-websocket المملوكة للمتصفح talk.client.create، لأن المتصفح يمتلك تفاوض المزود ونقل الوسائط، بينما يمتلك Gateway بيانات الاعتماد والتعليمات وسياسة الأدوات. talk.session.* هو السطح المشترك المُدار بواسطة Gateway للوقت الحقيقي عبر gateway-relay، والنسخ عبر gateway-relay، وجلسات STT/TTS الأصلية في الغرفة المُدارة.

ينبغي إصلاح الإعدادات القديمة التي وضعت محددات الوقت الحقيقي بجانب talk.provider / talk.providers باستخدام openclaw doctor --fix؛ لا يعيد Talk في وقت التشغيل تفسير إعداد مزود الكلام/TTS باعتباره إعداد مزود وقت حقيقي.

توليفات talk.session.create المدعومة صغيرة عمداً:

خريطة الطرق المُزالة:

كما أن مفردات التحكم الموحدة ضيقة عمداً:

لا تُدخل حالات خاصة بالمزوّد أو المنصة في النواة لجعل هذا يعمل. تملك النواة دلالات جلسة Talk. وتملك إضافات المزوّد إعداد جلسة البائع. وتملك المكالمات الصوتية وGoogle Meet محوّلات الهاتفية/الاجتماعات. وتملك تطبيقات المتصفح والتطبيقات الأصلية تجربة مستخدم التقاط/تشغيل الجهاز.

سياسة التوافق

بالنسبة إلى الإضافات الخارجية، يتبع عمل التوافق هذا الترتيب:

1. أضف العقد الجديد
2. أبقِ السلوك القديم موصولًا عبر محوّل توافق
3. أصدِر تشخيصًا أو تحذيرًا يذكر المسار القديم والبديل
4. غطِّ كلا المسارين في الاختبارات
5. وثّق الإيقاف التدريجي ومسار الترحيل
6. أزِل فقط بعد نافذة الترحيل المُعلنة، عادةً في إصدار رئيسي

يمكن للمشرفين تدقيق قائمة انتظار الترحيل الحالية باستخدام pnpm plugins:boundary-report. استخدم pnpm plugins:boundary-report:summary للحصول على أعداد موجزة، و--owner <id> لإضافة واحدة أو مالك توافق واحد، و pnpm plugins:boundary-report:ci عندما ينبغي لبوابة CI أن تفشل عند وجود سجلات توافق مستحقة، أو استيرادات SDK محجوزة عابرة للمالكين، أو مسارات SDK فرعية محجوزة غير مستخدمة. يجمع التقرير سجلات التوافق الموقوفة تدريجيًا حسب تاريخ الإزالة، ويعدّ مراجع الكود/المستندات المحلية، ويُظهر استيرادات SDK المحجوزة العابرة للمالكين، ويلخّص جسر SDK الخاص بمضيف الذاكرة بحيث يبقى تنظيف التوافق صريحًا بدلًا من الاعتماد على عمليات بحث مخصصة. يجب أن يكون للمسارات الفرعية المحجوزة في SDK استخدام مالك متتبّع؛ وينبغي إزالة صادرات المساعدين المحجوزة غير المستخدمة من SDK العام.

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

كيفية الترحيل

await api.runtime.config.mutateConfigFile({  afterWrite: { mode: "auto" },  mutate(draft) {    draft.plugins ??= {};  },});

// OpenClaw and Codex runtime dynamic toolsapi.registerAgentToolResultMiddleware(async (event) => {  return compactToolResult(event);}, {  runtimes: ["openclaw", "codex"],});

{  "contracts": {    "agentToolResultMiddleware": ["openclaw", "codex"]  }}

// Beforeconst program = applyWindowsSpawnProgramPolicy({ candidate }); // Afterconst program = applyWindowsSpawnProgramPolicy({  candidate,  // Only set this for trusted compatibility callers that intentionally  // accept shell-mediated fallback.  allowShellFallback: true,});

grep -r "plugin-sdk/compat" my-plugin/grep -r "plugin-sdk/infra-runtime" my-plugin/grep -r "plugin-sdk/config-runtime" my-plugin/grep -r "openclaw/extension-api" my-plugin/

// Before (deprecated backwards-compatibility layer)import {  createChannelReplyPipeline,  createPluginRuntimeStore,  resolveControlCommandGate,} from "openclaw/plugin-sdk/compat"; // After (modern focused imports)import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth";

// Before (deprecated extension-api bridge)import { runEmbeddedAgent } from "openclaw/extension-api";const result = await runEmbeddedAgent({ sessionId, prompt }); // After (injected runtime)const result = await api.runtime.agent.runEmbeddedAgent({ sessionId, prompt });

pnpm buildpnpm test -- my-plugin/

مرجع مسارات الاستيراد

هذا الجدول هو عمدا مجموعة الترحيل المشتركة، وليس سطح SDK الكامل. يوجد مخزون نقطة دخول المصرّف في scripts/lib/plugin-sdk-entrypoints.json؛ وتُولَّد صادرات الحزمة من المجموعة الفرعية العامة.

أُحيلت وصلات مساعد Plugin المضمّن المحجوزة إلى التقاعد من خريطة تصدير SDK العامة، باستثناء واجهات التوافق الموثقة صراحة مثل طبقة التوافق المهملة plugin-sdk/discord المحتفظ بها لحزمة @openclaw/discord@2026.3.13 المنشورة. توجد المساعدات الخاصة بالمالك داخل حزمة Plugin المالكة؛ وينبغي أن ينتقل سلوك المضيف المشترك عبر عقود SDK العامة مثل plugin-sdk/gateway-runtime وplugin-sdk/security-runtime وplugin-sdk/plugin-config-runtime.

استخدم أضيق استيراد يطابق المهمة. إذا لم تتمكن من العثور على تصدير، فافحص المصدر في src/plugin-sdk/ أو اسأل المشرفين أي عقد عام ينبغي أن يملكه.

الإهمالات النشطة

إهمالات أضيق تنطبق عبر SDK الخاص بـ Plugin، وعقد المزوّد، وسطح وقت التشغيل، والبيان. كل واحد منها ما زال يعمل اليوم، لكنه سيُزال في إصدار رئيسي مستقبلي. يربط الإدخال أسفل كل عنصر API القديم ببديله المعياري.

// Beforeimport { buildHelpMessage } from "openclaw/plugin-sdk/command-auth"; // Afterimport { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

// Beforeapi.on("deactivate", async (event, ctx) => {  await stopPluginService(ctx);}); // Afterapi.on("gateway_stop", async (event, ctx) => {  await stopPluginService(ctx);});

// Beforeapi.on("subagent_spawning", async () => ({  status: "ok",  threadBindingReady: true,  deliveryOrigin: { channel: "discord", to: "channel:123", threadId: "456" },})); // Afterapi.on("subagent_spawned", async (event) => {  await observeSubagentLaunch(event);});

{  "contracts": {    "externalAuthProviders": ["anthropic", "openai"]  }}

// Beforeconst flow = api.runtime.tasks.flow.fromToolContext(ctx);// Afterconst flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Beforeimport type { OpenClawSchemaType } from "openclaw/plugin-sdk";// Afterimport type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";

الجدول الزمني للإزالة

تم ترحيل كل plugins الأساسية بالفعل. ينبغي أن ترحّل plugins الخارجية قبل الإصدار الرئيسي التالي.

إيقاف التحذيرات مؤقتًا

اضبط متغيرات البيئة هذه أثناء العمل على الترحيل:

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway runOPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

هذا مسار مؤقت لتجاوز المشكلة، وليس حلًا دائمًا.

ذات صلة

• بدء الاستخدام - أنشئ أول plugin لك
• نظرة عامة على SDK - مرجع كامل لاستيراد المسارات الفرعية
• Plugins القنوات - بناء plugins القنوات
• Plugins المزوّدين - بناء plugins المزوّدين
• داخليات Plugin - تعمّق في البنية
• بيان Plugin - مرجع مخطط البيان