مهاجرت SDK Plugin

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

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

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

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

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

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

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

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

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

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

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

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

• Anthropic کمک‌کننده‌های stream مخصوص Claude را در درز api.ts / contract-api.ts خودش نگه می‌دارد
• OpenAI سازنده‌های provider، کمک‌کننده‌های default-model، و سازنده‌های realtime provider را در api.ts خودش نگه می‌دارد
• OpenRouter سازنده provider و کمک‌کننده‌های onboarding/config را در api.ts خودش نگه می‌دارد

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

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

این مهاجرت 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. یک کانال رویداد زنده Talk را در Gateway hello-ok.features.events اعلام کنید: talk.event.
5. endpoint قدیمی HTTP realtime و هر مسیر override دستورالعمل در زمان درخواست را حذف کنید.

کد جدید نباید مستقیماً createTalkEventSequencer(...) را فراخوانی کند مگر اینکه در حال پیاده‌سازی یک adapter سطح پایین یا fixture تست باشد. کنترلر مشترک را ترجیح دهید تا رویدادهای محدود به turn نتوانند بدون شناسه turn منتشر شوند، فراخوانی‌های stale turnEnd / turnCancel نتوانند turn فعال جدیدتر را پاک کنند، و رویدادهای lifecycle مربوط به output-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 });await gateway.request("talk.client.steer", { sessionKey, text, mode: "steer" });

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

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

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

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

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

برای کار کردن این قابلیت، موارد ویژه ارائه‌دهنده یا پلتفرم را وارد هسته نکنید. هسته مالک معناشناسی نشست Talk است. Pluginهای ارائه‌دهنده مالک راه‌اندازی نشست فروشنده هستند. تماس صوتی و Google Meet مالک آداپتورهای تلفنی/جلسه هستند. مرورگر و برنامه‌های بومی مالک تجربه کاربری ضبط/پخش دستگاه هستند.

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

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

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

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

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

شیوه مهاجرت

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 قرار دارد؛ exportهای package از زیرمجموعهٔ عمومی تولید می‌شوند.

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

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

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

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

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

جدول زمانی حذف

همه Pluginهای هسته از قبل مهاجرت داده شده‌اند. Pluginهای خارجی باید پیش از انتشار اصلی بعدی مهاجرت کنند.

سرکوب موقت هشدارها

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

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway runOPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

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

مرتبط

• شروع به کار - نخستین plugin خود را بسازید
• نمای کلی SDK - مرجع کامل import زیرفرازها
• Pluginهای کانال - ساخت pluginهای کانال
• Pluginهای ارائه‌دهنده - ساخت pluginهای ارائه‌دهنده
• درون‌سازه‌های Plugin - بررسی عمیق معماری
• مانیفست Plugin - مرجع شِمای مانیفست