Plugin maintainer reference

سازگاری Plugin

OpenClaw قراردادهای قدیمی‌تر Plugin را پیش از حذف، از طریق آداپتورهای سازگاری نام‌گذاری‌شده متصل نگه می‌دارد. این کار از Pluginهای همراه و خارجی موجود محافظت می‌کند، درحالی‌که قراردادهای SDK، مانیفست، راه‌اندازی، پیکربندی و زمان اجرای عامل تکامل می‌یابند.

رجیستری سازگاری

قراردادهای سازگاری Plugin در رجیستری هسته در src/plugins/compat/registry.ts پیگیری می‌شوند. هر رکورد شامل موارد زیر است:

یک کد سازگاری پایدار
وضعیت: active، deprecated، removal-pending، یا removed
مالک: sdk، config، setup، channel، provider، plugin-execution، agent-runtime، یا core
تاریخ‌های معرفی و منسوخ‌شدن، در صورت کاربرد
تاریخ دقیق حذف پس از تأیید نگه‌دارنده مالک؛ حذف‌شدن removeAfter باعث می‌شود یک سطح منسوخ واجد شرایط حذف نباشد
راهنمای جایگزینی
مستندات، عیب‌یابی‌ها و آزمون‌هایی که رفتار قدیم و جدید را پوشش می‌دهند

این رجیستری منبع برنامه‌ریزی نگه‌دارندگان و بررسی‌های آینده بازرس Plugin است. اگر رفتاری مرتبط با Plugin تغییر کند، رکورد سازگاری را در همان تغییری که آداپتور را اضافه می‌کند، بیفزایید یا به‌روزرسانی کنید.

سازگاری تعمیر و مهاجرت Doctor به‌صورت جداگانه در src/commands/doctor/shared/deprecation-compat.ts پیگیری می‌شود. این رکوردها شکل‌های قدیمی پیکربندی، چیدمان‌های دفترکل نصب و شیم‌های تعمیری را پوشش می‌دهند که ممکن است پس از حذف مسیر سازگاری زمان اجرا نیز لازم باشد در دسترس بمانند.

بازبینی‌های انتشار باید هر دو رجیستری را بررسی کنند. یک مهاجرت Doctor را صرفاً به این دلیل که رکورد سازگاری متناظر زمان اجرا یا پیکربندی منقضی شده است حذف نکنید؛ ابتدا تأیید کنید هیچ مسیر ارتقای پشتیبانی‌شده‌ای هنوز به آن تعمیر نیاز ندارد. همچنین در برنامه‌ریزی هر انتشار، هر یادداشت جایگزینی را دوباره اعتبارسنجی کنید، زیرا با انتقال ارائه‌دهندگان و کانال‌ها به بیرون از هسته، مالکیت Plugin و گستره پیکربندی می‌تواند تغییر کند.

سیاست منسوخ‌سازی

OpenClaw نباید یک قرارداد مستندشده Plugin را در همان انتشاری حذف کند که جایگزین آن را معرفی می‌کند. توالی مهاجرت:

قرارداد جدید را اضافه کنید.
رفتار قدیمی را از طریق یک آداپتور سازگاری نام‌گذاری‌شده متصل نگه دارید.
هنگامی که نویسندگان Plugin می‌توانند اقدام کنند، عیب‌یابی یا هشدار صادر کنید.
جایگزین و زمان‌بندی را مستند کنید.
هر دو مسیر قدیمی و جدید را آزمایش کنید.
تا پایان بازه مهاجرت اعلام‌شده صبر کنید.
فقط با تأیید صریح انتشار ناسازگار حذف کنید.

رکوردهای منسوخ باید شامل تاریخ شروع هشدار، جایگزین، پیوند مستندات و تاریخ نهایی حذف حداکثر سه ماه پس از شروع هشدار باشند. مسیر سازگاری منسوخی با بازه حذف بدون پایان اضافه نکنید، مگر اینکه نگه‌دارندگان صریحاً تصمیم بگیرند این سازگاری دائمی است و به‌جای آن، آن را با active علامت‌گذاری کنند.

حوزه‌های سازگاری فعلی

بازبینی ژوئیه 2026 نام‌های مستعار منقضی‌شده SDK ریشه، مانیفست، ارائه‌دهنده، زمان اجرا، پرچم رجیستری و پیکربندی وب متعلق به Plugin را حذف کرد. مهاجرت‌های Doctor همچنان جداگانه پیگیری می‌شوند تا مسیرهای ارتقای پشتیبانی‌شده بتوانند پیکربندی قدیمی را تعمیر کنند.

حوزه‌های سازگاری تاریخ‌دار باقی‌مانده عبارت‌اند از:

بازه‌های زیرمسیر SDK در اوت و سپتامبر که در راهنمای مهاجرت فهرست شده‌اند
نام‌های مستعار هوک api.on("deactivate", ...) و api.on("subagent_spawning", ...)
ثبت تعبیه‌سازی مختص حافظه و پل ذخیره‌گاه نشست beta.5
نام‌های مستعار فراخوان برگشتی ورودی WhatsApp که در ادامه شرح داده شده‌اند
تجزیه صریح مقصد کانال و openclaw/plugin-sdk/messaging-targets
نام‌های مستعار عامل Pi تعبیه‌شده
نام‌های مستعار SDK مهار عامل منتشرشده که حذف آن‌ها در انتظار یک تصمیم جدید و مستندشده عمومی برای مهاجرت است

رکوردهای فعال و بدون تاریخ رجیستری، رفتار پشتیبانی‌شده را به‌جای بدهی حذف پوشش می‌دهند، از جمله راهنمایی‌های فعال‌سازی، ثبت Plugin، فعال‌سازی Plugin همراه و مسیر جایگزین تولیدشده پیکربندی کانال.

نام‌های مستعار تخت فراخوان برگشتی ورودی WhatsApp

فراخوان‌های برگشتی زمان اجرای WhatsApp، WebInboundMessage را تحویل می‌دهند: زمینه‌های تو‌در‌توی استاندارد event، payload، quote، group و platform، به‌همراه نام‌های مستعار تخت منسوخ برای فیلدهای فراخوان برگشتی منتشرشده. کد جدید فراخوان برگشتی باید زمینه‌های تو‌در‌تو را بخواند. کدی که پیام‌های فراخوان برگشتی تو‌در‌توی پاک می‌سازد، می‌تواند از WebInboundCallbackMessage استفاده کند؛ شنونده‌های سازگاری که هنوز پیام‌های آزمایشی یا Plugin تخت قدیمی را تزریق می‌کنند باید از LegacyFlatWebInboundMessage یا WebInboundMessageInput استفاده کنند.

نام‌های مستعار تخت تا 2026-08-30 در دسترس می‌مانند؛ این بازه فقط برای دسترسی به نام مستعار تخت کاربرد دارد، نه برای شکل تو‌در‌تو که قرارداد استاندارد زمان اجرا است. یادداشت TypeScript @deprecated هر نام مستعار تخت، جایگزین تو‌در‌توی دقیق آن را مشخص می‌کند. نمونه‌های رایج:

id، timestamp و isBatched به زیر event منتقل می‌شوند.
body، mediaPath، mediaType، mediaFileName، mediaUrl، location و untrustedStructuredContext به زیر payload منتقل می‌شوند.
to، chatId، فیلدهای فرستنده/خود، sendComposing، reply(...) و sendMedia(...) به زیر platform منتقل می‌شوند.
فیلدهای replyTo* به زیر quote منتقل می‌شوند؛ فیلدهای موضوع/شرکت‌کننده/اشاره گروه به زیر group منتقل می‌شوند.

payload.untrustedStructuredContext از محموله‌های ورودی ارائه‌دهنده استخراج می‌شود. Pluginها باید پیش از معتبر دانستن payload آن، label، source و type را بررسی کنند.

فیلدهای پذیرش ورودی WhatsApp

پیام‌های فراخوان برگشتی پذیرفته‌شده WhatsApp حامل admission هستند؛ پوششی امن برای انتشار عمومی که تصمیم کنترل دسترسیِ پذیرنده پیام را نمایش می‌دهد. کد جدید فراخوان برگشتی باید به‌جای فیلدهای پذیرش قدیمی سطح بالا، واقعیت‌های پذیرش را از msg.admission بخواند.

فیلدهای سطح بالا تا 2026-08-30 در دسترس می‌مانند. یادداشت TypeScript @deprecated هر فیلد، جایگزین آن را مشخص می‌کند:

from و conversationId به admission.conversation.id منتقل می‌شوند.
accountId به admission.accountId منتقل می‌شود.
accessControlPassed یک نمای سازگاری مشتق‌شده از admission.ingress.decision === "allow" است؛ در پیام‌هایی که از قبل admission را حمل می‌کنند، نوشتن مقدار بولی قدیمی، گراف ورودی را بازنویسی نمی‌کند.
chatType به admission.conversation.kind منتقل می‌شود.

بسته بازرس Plugin

بازرس Plugin باید خارج از مخزن هسته OpenClaw و به‌صورت یک بسته/مخزن جداگانه، با پشتوانه قراردادهای نسخه‌دار سازگاری و مانیفست قرار گیرد. CLI روز نخست باید چنین باشد:

openclaw-plugin-inspector ./my-plugin

این ابزار باید اعتبارسنجی مانیفست/طرحواره، نسخه سازگاری قرارداد در حال بررسی، بررسی‌های فراداده نصب/منبع، بررسی‌های واردسازی مسیر سرد و هشدارهای منسوخ‌سازی/سازگاری را خروجی دهد. برای خروجی پایدار و ماشین‌خوان در یادداشت‌های CI از --json استفاده کنید. هسته OpenClaw باید قراردادها و داده‌های آزمایشی‌ای را در دسترس بگذارد که بازرس بتواند مصرف کند، اما نباید فایل اجرایی بازرس را از بسته اصلی openclaw منتشر کند.

مسیر پذیرش نگه‌دارندگان

هنگام اعتبارسنجی بازرس خارجی در برابر بسته‌های Plugin مربوط به OpenClaw، برای مسیر پذیرش بسته قابل‌نصب از Blacksmith Testbox با پشتوانه Crabbox استفاده کنید. پس از ساخت بسته، آن را از یک پرداخت تمیز OpenClaw اجرا کنید:

pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "pnpm install && pnpm build && npm exec --yes @openclaw/plugin-inspector@0.1.0 -- ./extensions/telegram --json"pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- ./extensions/discord --json"pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- <clawhub-plugin-dir> --json"

این مسیر را برای نگه‌دارندگان اختیاری نگه دارید، زیرا یک بسته خارجی npm را نصب می‌کند و ممکن است بسته‌های Plugin همتاسازی‌شده خارج از مخزن را بررسی کند. محافظ‌های مخزن محلی، نگاشت خروجی SDK، فراداده رجیستری سازگاری، کاهش تدریجی واردسازی‌های منسوخ SDK و مرزهای واردسازی افزونه‌های همراه را پوشش می‌دهند؛ اثبات بازرس در Testbox بسته را به همان شکلی پوشش می‌دهد که نویسندگان Plugin خارجی آن را مصرف می‌کنند.

یادداشت‌های انتشار

یادداشت‌های انتشار باید پیش از انتقال یک مسیر سازگاری به removal-pending یا removed، منسوخ‌سازی‌های آتی Plugin را همراه با تاریخ‌های هدف و پیوندهای مستندات مهاجرت درج کنند.

Was this useful?