مهاجرت SDK Plugin

OpenClaw از یک لایه‌ی گسترده‌ی سازگاری با نسخه‌های قبلی به معماری مدرن Plugin با importهای متمرکز و مستند منتقل شده است. اگر Plugin شما پیش از معماری جدید ساخته شده، این راهنما به شما کمک می‌کند آن را مهاجرت دهید.

چه چیزی تغییر می‌کند

سیستم قدیمی Plugin دو سطح کاملاً باز فراهم می‌کرد که به Pluginها اجازه می‌داد هر چیزی را که نیاز داشتند از یک نقطه‌ی ورود واحد import کنند:

• openclaw/plugin-sdk/compat - یک import واحد که ده‌ها helper را دوباره export می‌کرد. این برای فعال نگه داشتن Pluginهای قدیمی مبتنی بر hook معرفی شد تا زمانی که معماری جدید Plugin در حال ساخت بود.
• openclaw/plugin-sdk/infra-runtime - یک barrel گسترده برای helperهای runtime که رویدادهای سیستم، وضعیت Heartbeat، صف‌های تحویل، helperهای fetch/proxy، helperهای فایل، نوع‌های approval، و utilityهای نامرتبط را با هم ترکیب می‌کرد.
• openclaw/plugin-sdk/config-runtime - یک barrel گسترده‌ی سازگاری config که هنوز helperهای مستقیم load/write منسوخ‌شده را در طول پنجره‌ی مهاجرت نگه می‌دارد.
• openclaw/extension-api - پلی که به Pluginها دسترسی مستقیم به helperهای سمت host مانند runner عامل جاسازی‌شده می‌داد.
• api.registerEmbeddedExtensionFactory(...) - یک hook حذف‌شده‌ی extension فقط برای Pi و bundled که می‌توانست رویدادهای embedded-runner مانند tool_result را مشاهده کند.

سطح‌های import گسترده اکنون منسوخ شده‌اند. آن‌ها هنوز در runtime کار می‌کنند، اما Pluginهای جدید نباید از آن‌ها استفاده کنند، و Pluginهای موجود باید پیش از حذف آن‌ها در نسخه‌ی major بعدی مهاجرت کنند. API ثبت factory برای extension جاسازی‌شده‌ی فقط Pi حذف شده است؛ به‌جای آن از middleware نتیجه‌ی ابزار استفاده کنید.

OpenClaw رفتار مستند Plugin را در همان تغییری که جایگزین معرفی می‌کند حذف یا باز تفسیر نمی‌کند. تغییرات شکننده‌ی قرارداد ابتدا باید از adapter سازگاری، diagnostics، docs، و یک پنجره‌ی deprecation عبور کنند. این درباره‌ی importهای SDK، فیلدهای manifest، APIهای setup، hookها، و رفتار ثبت runtime صدق می‌کند.

چرا این تغییر انجام شد

رویکرد قدیمی مشکلاتی ایجاد می‌کرد:

• راه‌اندازی کند - import کردن یک helper ده‌ها ماژول نامرتبط را load می‌کرد
• وابستگی‌های چرخه‌ای - export مجدد گسترده ایجاد چرخه‌های import را آسان می‌کرد
• سطح API نامشخص - راهی برای تشخیص اینکه کدام exportها پایدار و کدام داخلی بودند وجود نداشت

SDK مدرن Plugin این را برطرف می‌کند: هر مسیر import (openclaw/plugin-sdk/\<subpath\>) یک ماژول کوچک، خودبسنده، با هدف روشن و قرارداد مستند است.

seamهای convenience قدیمی provider برای channelهای bundled نیز حذف شده‌اند. seamهای helper با برند channel میان‌برهای خصوصی mono-repo بودند، نه قراردادهای پایدار Plugin. به‌جای آن از subpathهای باریک و generic SDK استفاده کنید. داخل workspace Plugin bundled، helperهای متعلق به provider را در api.ts یا runtime-api.ts خود همان Plugin نگه دارید.

نمونه‌های فعلی providerهای bundled:

• Anthropic helperهای stream اختصاصی Claude را در seam خودش یعنی api.ts / contract-api.ts نگه می‌دارد
• OpenAI provider builderها، helperهای مدل پیش‌فرض، و provider builderهای realtime را در api.ts خودش نگه می‌دارد
• OpenRouter provider builder و helperهای onboarding/config را در api.ts خودش نگه می‌دارد

برنامه‌ی مهاجرت Talk و صدای realtime

کد Talk برای صدای realtime، تلفن، جلسه، و مرورگر از bookkeeping نوبت محلیِ سطح به کنترل‌کننده‌ی مشترک session Talk که توسط openclaw/plugin-sdk/realtime-voice export می‌شود منتقل می‌شود. کنترل‌کننده‌ی جدید envelope مشترک رویداد Talk، وضعیت نوبت فعال، وضعیت capture، وضعیت audio خروجی، تاریخچه‌ی رویدادهای اخیر، و رد کردن نوبت‌های stale را در اختیار دارد. Pluginهای provider باید همچنان مالک sessionهای realtime اختصاصی vendor باشند؛ Pluginهای surface باید همچنان مالک capture، playback، تلفن، و quirks جلسه باشند.

این مهاجرت Talk عمداً با شکست تمیز طراحی شده است:

1. primitiveهای مشترک controller/runtime را در plugin-sdk/realtime-voice نگه دارید.
2. سطح‌های bundled را به کنترل‌کننده‌ی مشترک منتقل کنید: browser relay، managed-room handoff، voice-call realtime، voice-call streaming STT، Google Meet realtime، و native push-to-talk.
3. خانواده‌های قدیمی RPC Talk را با API نهایی talk.session.* و talk.client.* جایگزین کنید.
4. یک channel رویداد live Talk را در Gateway hello-ok.features.events اعلام کنید: talk.event.
5. endpoint قدیمی HTTP realtime و هر مسیر override دستورالعمل در زمان request را حذف کنید.

کد جدید نباید مستقیماً createTalkEventSequencer(...) را فراخوانی کند، مگر اینکه یک adapter سطح پایین یا test fixture پیاده‌سازی کند. کنترل‌کننده‌ی مشترک را ترجیح دهید تا رویدادهای محدود به نوبت بدون turn id منتشر نشوند، فراخوانی‌های stale turnEnd / turnCancel نتوانند نوبت فعال جدیدتر را پاک کنند، و رویدادهای lifecycle مربوط به audio خروجی در تلفن، جلسات، browser relay، managed-room handoff، و کلاینت‌های native 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 });

sessionهای WebRTC/provider-websocket متعلق به مرورگر از talk.client.create استفاده می‌کنند، زیرا مرورگر مالک مذاکره‌ی provider و transport رسانه است، در حالی که Gateway مالک credentials، instructions، و سیاست ابزار است. talk.session.* سطح مشترک مدیریت‌شده توسط Gateway برای gateway-relay realtime، gateway-relay transcription، و sessionهای native STT/TTS در managed-room است.

configهای قدیمی که selectorهای realtime را کنار talk.provider / talk.providers قرار داده‌اند باید با openclaw doctor --fix تعمیر شوند؛ Talk در runtime، config مربوط به speech/TTS provider را به‌عنوان config مربوط به realtime provider باز تفسیر نمی‌کند.

ترکیب‌های پشتیبانی‌شده‌ی talk.session.create عمداً کوچک هستند:

نقشه‌ی methodهای حذف‌شده:

واژگان کنترل یکپارچه نیز عمداً محدود است:

در core، حالت‌های ویژهٔ provider یا platform را برای کار کردن این قابلیت وارد نکنید. core مالک معناشناسی نشست Talk است. Pluginهای provider مالک راه‌اندازی نشست vendor هستند. Voice-call و Google Meet مالک سازگارکننده‌های تلفنی/جلسه هستند. مرورگر و برنامه‌های native مالک تجربهٔ کاربری ضبط/پخش دستگاه هستند.

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

برای Pluginهای خارجی، کار سازگاری با این ترتیب انجام می‌شود:

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

نگه‌دارندگان می‌توانند صف مهاجرت فعلی را با pnpm plugins:boundary-report بازبینی کنند. برای شمارش‌های فشرده از pnpm plugins:boundary-report:summary، برای یک Plugin یا مالک سازگاری از --owner <id>، و زمانی که یک gate در CI باید روی رکوردهای سازگاری سررسیدشده، واردکردن‌های SDK رزرو‌شدهٔ بین‌مالکی، یا زیرمسیرهای SDK رزروشدهٔ استفاده‌نشده fail شود، از pnpm plugins:boundary-report:ci استفاده کنید. گزارش، رکوردهای سازگاری منسوخ‌شده را بر اساس تاریخ حذف گروه‌بندی می‌کند، ارجاع‌های کد/مستندات محلی را می‌شمارد، واردکردن‌های SDK رزرو‌شدهٔ بین‌مالکی را آشکار می‌کند، و پل خصوصی SDK میزبان حافظه را خلاصه می‌کند تا پاک‌سازی سازگاری صریح باقی بماند، به‌جای اینکه به جست‌وجوهای موردی متکی باشد. زیرمسیرهای SDK رزروشده باید استفادهٔ مالکِ رهگیری‌شده داشته باشند؛ exportهای helper رزروشدهٔ استفاده‌نشده باید از SDK عمومی حذف شوند.

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

روش مهاجرت

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

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

{  "contracts": {    "agentToolResultMiddleware": ["pi", "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 { runEmbeddedPiAgent } from "openclaw/extension-api";const result = await runEmbeddedPiAgent({ sessionId, prompt }); // After (injected runtime)const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });

pnpm buildpnpm test -- my-plugin/

مرجع مسیر import

این جدول عمداً زیرمجموعهٔ مشترک مهاجرت است، نه کل سطح SDK. فهرست نقطه‌های ورود کامپایلر در scripts/lib/plugin-sdk-entrypoints.json قرار دارد؛ خروجی‌های package از زیرمجموعهٔ عمومی تولید می‌شوند.

درزهای کمکی رزرو‌شدهٔ Pluginهای همراه، از نقشهٔ خروجی SDK عمومی بازنشسته شده‌اند، به‌جز facadeهای سازگاری که صراحتاً مستند شده‌اند؛ مانند shim منسوخ plugin-sdk/discord که برای package منتشرشدهٔ @openclaw/discord@2026.3.13 حفظ شده است. کمک‌کننده‌های مخصوص مالک داخل package همان Plugin مالک قرار دارند؛ رفتار مشترک میزبان باید از طریق قراردادهای عمومی SDK مانند plugin-sdk/gateway-runtime، plugin-sdk/security-runtime، و plugin-sdk/plugin-config-runtime منتقل شود.

از محدودترین import متناسب با کار استفاده کنید. اگر خروجی‌ای پیدا نمی‌کنید، منبع را در src/plugin-sdk/ بررسی کنید یا از نگه‌دارندگان بپرسید کدام قرارداد عمومی باید مالک آن باشد.

منسوخ‌سازی‌های فعال

منسوخ‌سازی‌های محدودتری که در سراسر SDK Plugin، قرارداد provider، سطح runtime، و manifest اعمال می‌شوند. هرکدام امروز هنوز کار می‌کنند اما در یک انتشار major آینده حذف خواهند شد. ورودی زیر هر مورد، API قدیمی را به جایگزین canonical آن نگاشت می‌کند.

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

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

زمان‌بندی حذف

همهٔ Pluginهای core قبلاً مهاجرت داده شده‌اند. Pluginهای خارجی باید پیش از انتشار major بعدی مهاجرت کنند.

غیرفعال کردن موقت هشدارها

هنگام کار روی مهاجرت، این متغیرهای محیطی را تنظیم کنید:

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway runOPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

این یک راه فرار موقت است، نه یک راه‌حل دائمی.

مرتبط

• شروع کار - نخستین Plugin خود را بسازید
• نمای کلی SDK - مرجع کامل importهای subpath
• Pluginهای channel - ساخت Pluginهای channel
• Pluginهای provider - ساخت Pluginهای provider
• جزئیات داخلی Plugin - بررسی عمیق معماری
• manifest Plugin - مرجع schema manifest