سازگاری 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
• تاریخ‌های معرفی و منسوخ‌شدن، در صورت کاربرد
• راهنمای جایگزینی
• مستندات، عیب‌یابی‌ها و آزمون‌هایی که رفتار قدیمی و جدید را پوشش می‌دهند

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

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

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

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

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

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

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

حوزه‌های سازگاری کنونی

رجیستری در حال حاضر حدود ۷۰ کد سازگاری را در حوزه‌های زیر ردیابی می‌کند. کد جدید Plugin باید در هر حوزه و راهنمای مهاجرت مربوطه از جایگزین استفاده کند؛ Pluginهای موجود می‌توانند تا زمانی که مستندات، عیب‌یابی‌ها و یادداشت‌های انتشار یک بازه حذف را اعلام کنند، به استفاده از مسیر سازگاری ادامه دهند.

• واردکردن‌های گسترده و قدیمی SDK مانند openclaw/plugin-sdk/compat
• شکل‌های قدیمی Plugin صرفاً مبتنی بر هوک و before_agent_start
• نام‌های قدیمی هوک پاک‌سازی api.on("deactivate", ...) تا زمانی که Pluginها به gateway_stop مهاجرت کنند
• نقاط ورود قدیمی Plugin به‌شکل activate(api) تا زمانی که Pluginها به register(api) مهاجرت کنند
• نام‌های مستعار قدیمی SDK مانند openclaw/extension-api، openclaw/plugin-sdk/channel-runtime، سازنده‌های وضعیت openclaw/plugin-sdk/command-auth، ‏openclaw/plugin-sdk/test-utils (که با زیرمسیرهای متمرکز آزمون openclaw/plugin-sdk/* جایگزین شده است) و نام‌های مستعار نوع ClawdbotConfig / OpenClawSchemaType
• فهرست مجاز و رفتار فعال‌سازی Pluginهای همراه
• فراداده قدیمی مانیفست متغیر محیطی ارائه‌دهنده/کانال
• هوک‌های قدیمی Plugin ارائه‌دهنده و نام‌های مستعار نوع، تا زمانی که ارائه‌دهندگان به هوک‌های صریح کاتالوگ، احراز هویت، تفکر، بازپخش و انتقال منتقل شوند
• نام‌های مستعار قدیمی زمان اجرا مانند api.runtime.taskFlow، api.runtime.subagent.getSession، ‏api.runtime.stt و api.runtime.config.loadConfig() / api.runtime.config.writeConfigFile(...) منسوخ‌شده
• فیلدهای تخت فراخوانی برگشتی WebInboundMessage در WhatsApp (پایین را ببینید)
• فیلدهای سطح‌بالای پذیرش WebInboundMessage در WhatsApp (پایین را ببینید)
• ثبت تفکیک‌شده قدیمی Plugin حافظه، تا زمانی که Pluginهای حافظه به registerMemoryCapability منتقل شوند
• ثبت قدیمی ارائه‌دهنده تعبیه مختص حافظه، تا زمانی که ارائه‌دهندگان تعبیه به api.registerEmbeddingProvider(...) و contracts.embeddingProviders منتقل شوند
• ابزارهای کمکی قدیمی SDK کانال برای شِماهای پیام بومی، کنترل منشن، قالب‌بندی پوش فراگیر ورودی و تودرتوسازی قابلیت تأیید
• نام‌های مستعار قدیمی کلید مسیر کانال و ابزار کمکی هدف قابل‌مقایسه، تا زمانی که Pluginها به openclaw/plugin-sdk/channel-route منتقل شوند
• جایگزینی راهنمایی‌های فعال‌سازی با مالکیت مشارکت مانیفست
• بازگشت زمان اجرای setup-api تا زمانی که توصیف‌گرهای راه‌اندازی به فراداده سرد setup.requiresRuntime: false منتقل شوند
• هوک‌های discovery ارائه‌دهنده، تا زمانی که هوک‌های کاتالوگ ارائه‌دهنده به catalog.run(...) منتقل شوند
• فراداده showConfigured / showInSetup کانال، تا زمانی که بسته‌های کانال به openclaw.channel.exposure منتقل شوند
• کلیدهای قدیمی پیکربندی سیاست زمان اجرا، تا زمانی که Doctor گردانندگان را به agentRuntime مهاجرت دهد
• بازگشت فراداده تولیدشده پیکربندی کانال همراه، تا زمانی که فراداده رجیستری‌محور channelConfigs مستقر شود
• پرچم‌های محیطی پایدار رجیستری Plugin برای غیرفعال‌سازی و مهاجرت نصب، تا زمانی که جریان‌های تعمیر، گردانندگان را به openclaw plugins registry --refresh و openclaw doctor --fix مهاجرت دهند
• مسیرهای قدیمی پیکربندی جست‌وجوی وب، واکشی وب و x_search متعلق به Plugin، تا زمانی که Doctor آن‌ها را به plugins.entries.<plugin>.config مهاجرت دهد
• پیکربندی تألیف‌شده قدیمی plugins.installs و نام‌های مستعار مسیر بارگذاری 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 را همراه با تاریخ‌های هدف و پیوندهای مستندات مهاجرت درج کنند.