مهاجرت SDK افزونه

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

چه چیزهایی تغییر کرد

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

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

SDK ریشه، barrel سازگاری، پل افزونه و کارخانهٔ افزونهٔ تعبیه‌شده حذف شده‌اند. infra-runtime و config-runtime فقط برای بازه‌های بعدی که جداگانه ثبت شده‌اند باقی می‌مانند؛ Pluginهای جدید باید از زیرمسیرهای متمرکز استفاده کنند.

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

چرا

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

اکنون هر 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 اختصاصی خود نگه می‌دارد.

خط‌مشی سازگاری

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

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

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

سازگاری راه‌اندازی کانال‌های منتشرشده

بسته‌های Slack، Discord، Signal و Microsoft Teams که از طریق 2026.7.1 منتشر شده‌اند، schemaهای پیکربندی مختص کانال را از openclaw/plugin-sdk/bundled-channel-config-schema import می‌کنند. بسته‌های منتشرشدهٔ Slack و Discord همچنین createLegacyCompatChannelDmPolicy و promptLegacyChannelAllowFromForAccount را از openclaw/plugin-sdk/setup-runtime import می‌کنند.

این exportها به‌عنوان آداپتورهای منسوخ‌شدهٔ سازگاری زمان اجرا در دسترس باقی می‌مانند. Pluginهای جدید و بازنشرشده باید schemaهای پیکربندی و خط‌مشی راه‌اندازی خود را به‌صورت محلی در اختیار داشته باشند و از اجزای عمومی channel-config-schema و setup-runtime استفاده کنند. exportهای سازگاری فقط زمانی قابل حذف‌اند که حداقل نسخه‌های پشتیبانی‌شدهٔ بسته‌های منتشرشده دیگر آن‌ها را import نکنند.

سازگاری فیلدهای ورودی راه‌اندازی کانال

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

OpenClaw انتشار اصلی ارائه نمی‌کند. یک پیمایش registry در 2026-07-22، 426 Plugin کانال منتشرشدهٔ خارج از درخت را بررسی و 21 فیلد بدون خواننده را حذف کرد. هر یک از 22 فیلد حفظ‌شده، یک خوانندهٔ منتشرشدهٔ شناخته‌شده دارد. هر فیلد بعدی به‌محض اینکه هیچ Plugin منتشرشده‌ای آن را نخواند حذف می‌شود؛ مجموعهٔ حفظ‌شده با مهاجرت نویسندگان Plugin به انواع ورودی راه‌اندازی محلی Plugin کوچک‌تر می‌شود.

همان پیمایش، 23 کلید قدیمی ارتقای آداپتور اعلام‌نشده را که وابستهٔ منتشرشده‌ای نداشتند حذف کرد. شش کلید رایج و کلید مختص راه‌اندازی rooms باقی مانده‌اند. این مجموعه نیز با اعلام singleAccountKeysToMove توسط Pluginهای منتشرشده کوچک‌تر می‌شود.

نوع مشترک هیچ index signature ندارد. کلیدهای متعلق به Plugin همچنان می‌توانند در اشیای ورودی زمان اجرا وجود داشته باشند؛ آن‌ها را در یک intersection محلی Plugin اعلام کنید یا از طریق schema راه‌اندازی Plugin مالک محدودشان کنید.

سطح قدیمی ارتقای آداپتور اعلام‌نشده نیز از همان خط‌مشی مبتنی بر خواننده پیروی می‌کند. singleAccountKeysToMove را اعلام کنید، از جمله یک آرایهٔ خالی زمانی که Plugin به کلیدهای ارتقای اضافی نیاز ندارد، تا fallback مشترک بتواند هر بار یک کلید را بازنشسته کند.

تأیید خواننده‌ها

1. با هر nextCursor در https://clawhub.ai/api/v1/packages?family=code-plugin&limit=100 صفحه‌به‌صفحه پیش بروید و بسته‌هایی را نگه دارید که categories آن‌ها شامل channels است.
2. گزینه‌های npm را از npm search --json --searchlimit=1000 "openclaw channel plugin" اضافه کنید. گزینه‌های صرفاً منبع را از جست‌وجوهای کد GitHub برای openclaw/plugin-sdk/channel-setup، openclaw/plugin-sdk/setup و openclaw/plugin-sdk/core اضافه کنید.
3. آخرین نسخهٔ منتشرشدهٔ هر گزینه را تعیین کنید. npm pack <package>@<version> --json --pack-destination <temp-dir> را اجرا و آن را باز کنید، سپس JavaScript و declarationهای عرضه‌شدهٔ dist را برای خواندن مستقیم یا destructured فیلد بررسی کنید. وقتی بسته‌ای انتشار npm ندارد، artifact مربوط به ClawHub را دانلود کنید.
4. بسته، نسخه، فیلد یا کلید ارتقا و فایل منطبق را ثبت کنید. یک فیلد یا کلید فقط زمانی قابل حذف است که هیچ artifact منتشرشدهٔ Plugin آن را نخواند. نام خواننده‌ها را در توضیحات کد کنار فهرست فیلدها و کلیدهای حفظ‌شده، همگام با پیمایش نگه دارید.

این فقط یک سابقهٔ سازگاری منبع/نوع است. هیچ آداپتور زمان اجرا یا ورودی registry سازگاری ندارد، زیرا اشیای ورودی راه‌اندازی زمان اجرا و رفتار راه‌اندازی تغییری نکرده‌اند.

صف مهاجرت کنونی را با pnpm plugins:boundary-report ممیزی کنید:

pnpm plugins:boundary-report:ci با هر سه پرچم شکست اجرا می‌شود. رکوردهای منسوخ‌شده معمولاً به‌جای عبارت مبهم «انتشار اصلی بعدی»، تاریخ صریح removeAfter دارند. رکوردی که مالک آن تاریخی را تأیید نکرده است، removeAfter ندارد، به‌شکل no-date نمایش داده می‌شود و هرگز واجد شرایط حذف نیست. گزارش، رکوردهای منسوخ‌شده را براساس تاریخ گروه‌بندی می‌کند، ارجاعات محلی کد/مستندات را می‌شمارد، importهای رزروشدهٔ SDK میان مالکان را نشان می‌دهد و پل خصوصی SDK میزبان حافظه را خلاصه می‌کند. زیرمسیرهای رزروشدهٔ SDK باید استفادهٔ ردیابی‌شده توسط مالک داشته باشند؛ exportهای رزروشدهٔ بدون استفاده باید از SDK عمومی حذف شوند.

نگاشت قدیمی رسانه

رکورد سازگاری media-legacy-projection فیلدهای موازی قدیمی رسانه، سازنده‌های payload، نام‌های مستعار metadata مربوط به hook و نام‌های template رسانه را پوشش می‌دهد. تاریخ تأییدشدهٔ removeAfter آن 2026-10-01 است (دو چرخهٔ انتشار پس از عرضهٔ جایگزین‌های facts-first). حذف همچنین مستلزم یک پیمایش پاک از artifactهای Plugin منتشرشده در آن زمان است؛ پیش از تاریخ مهاجرت کنید.

برای ورودی کانال، MediaPath، MediaUrl، MediaType، MediaPaths، MediaUrls، MediaTypes، MediaTranscribedIndexes، MediaWorkspaceDir و MediaStaged مفرد/جمع را با facts مرتب‌شده جایگزین کنید:

 const media = toInboundMediaFacts([  { path: saved.path, url: nativeUrl, contentType: saved.contentType, messageId },]); const ctx = finalizeInboundContext({ Body: caption, media });

از event.media در hookهای inbound_claim و message_received استفاده کنید. اگر رسانهٔ راه‌دور به‌صورت محلی stage نشده است، از event.originalMedia برای هویت/عیب‌یابی استفاده کنید و منتظر event.media بمانید؛ event.mediaStagingPending آن وضعیت را متمایز می‌کند. ویژگی‌های منسوخ‌شدهٔ مفرد/جمع را از event.metadata نخوانید.

برای مدل‌های رسانهٔ CLI، {{MediaPath}}، {{MediaUrl}}، {{MediaType}} و {{MediaDir}} را با {{AttachmentPath}}، {{AttachmentUrl}}، {{AttachmentContentType}} و {{AttachmentDir}} جایگزین کنید. هنگامی که موقعیت پیوست اهمیت دارد، از {{AttachmentIndex}} استفاده کنید.

برای خط‌مشی خواندن رسانهٔ محلی، getAgentScopedMediaLocalRoots(...) یا getAgentScopedMediaLocalRootsForSources(...) را از openclaw/plugin-sdk/media-local-roots import کنید. facade مربوط به openclaw/plugin-sdk/agent-media-payload و نگاشت buildAgentMediaPayload(...) آن منسوخ شده‌اند.

نحوهٔ مهاجرت

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

// ابزارهای زمان‌اجرای OpenClaw و ابزارهای پویای زمان‌اجرای Codex (نتیجه ممکن است// تبدیل شود). نتایج ابزارهای بومی Codex نیز برای مشاهده منتقل می‌شوند،// اما خروجی تبدیل‌شدهٔ آن‌ها هرگز به مدل نمی‌رسد: قرارداد hook مربوط به// PostToolUse در Codex نمی‌تواند پاسخ یک ابزار بومی را جایگزین کند.api.registerAgentToolResultMiddleware(async (event) => {  return compactToolResult(event);}, {  runtimes: ["openclaw", "codex"],});

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

// پیش از تغییرconst program = applyWindowsSpawnProgramPolicy({ candidate }); // پس از تغییرconst program = applyWindowsSpawnProgramPolicy({  candidate,  // این مقدار را فقط برای فراخواننده‌های سازگاری مورداعتماد تنظیم کنید که عمداً  // fallback با واسطهٔ shell را می‌پذیرند.  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/

// پیش از تغییر (لایهٔ منسوخ سازگاری با نسخه‌های پیشین)import {  createChannelReplyPipeline,  createPluginRuntimeStore,  resolveControlCommandGate,} from "openclaw/plugin-sdk/compat"; // پس از تغییر (درون‌ریزی‌های مدرن و متمرکز)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";

// پیش از تغییر (پل منسوخ extension-api)import { runEmbeddedAgent } from "openclaw/extension-api";const result = await runEmbeddedAgent({ sessionId, prompt }); // پس از تغییر (زمان‌اجرای تزریق‌شده)const result = await api.runtime.agent.runEmbeddedAgent({ sessionId, prompt });

pnpm buildpnpm test my-plugin/

مرجع مسیر درون‌ریزی

نگاشت export عمومی بسته، منبع حقیقت برای زیرمسیرهای قابل درون‌ریزی SDK است. از راهنماهای موضوعی SDK که در نمای کلی SDK پیوند داده شده‌اند استفاده کنید و محدودترین زیرمسیر عمومی مستندشده را ترجیح دهید. فهرست کامپایلر در scripts/lib/plugin-sdk-entrypoints.json همچنین شامل ورودی‌های خصوصی-محلی مورداستفاده برای ساخت Pluginهای همراه است؛ وجود آن‌ها در آنجا به‌معنای export عمومی بسته نیست.

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

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

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

سطوح سازگاری حذف‌شده

پاک‌سازی ژوئیهٔ 2026، barrelهای SDK ریشه و سازگاری، پل API افزونه، aliasهای منقضی‌شدهٔ زیرمسیر SDK، زیرمسیرهای بلااستفادهٔ SDK و exportهای عمومی ماژول‌های SDK ویژهٔ Pluginهای همراه را حذف کرد. ماژول‌های ویژهٔ Pluginهای همراه از طریق نگاشت‌های ساخت خصوصی-محلی برای مالکان مخزنشان در دسترس می‌مانند؛ این ماژول‌ها از بستهٔ منتشرشده قابل درون‌ریزی نیستند.

انتشار سراسری فرایندِ ارائه‌دهندهٔ API

registerApiProvider(...) و unregisterApiProviders(...) از openclaw/plugin-sdk/llm حذف شدند. آن‌ها انتقال‌های API را در وضعیت سراسری فرایند منتشر می‌کردند و سپس زمان‌اجراهای مدلِ دارای مالک چرخهٔ حیات مجبور بودند آن‌ها را در هر رجیستری آماده‌شده کپی کنند.

Pluginهای ارائه‌دهنده باید ارائه‌دهندگان استنتاج متن را از طریق api.registerProvider(...) ثبت کنند. کد و آزمون‌های متعلق به میزبان که یک ApiRegistry می‌سازند باید مستقیماً در همان رجیستری ثبت کنند تا مالکیت ارائه‌دهنده و پاک‌سازی در محدودهٔ زمان‌اجرای آماده‌شده باقی بماند.

barrel خصوصی آزمون

openclaw/plugin-sdk/testing محلی مخزن بود و از مصنوعات بستهٔ منتشرشده حذف می‌شد، بنابراین پیش از تاریخ removeAfter آن در 2026-07-28 حذف شد. آزمون‌های مخزن از زیرمسیرهای متمرکزی مانند plugin-sdk/plugin-test-runtime، plugin-sdk/channel-test-helpers، plugin-sdk/channel-target-testing، plugin-sdk/test-env و plugin-sdk/test-fixtures استفاده می‌کنند.

مرجع انتقال

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

// پیش از اینimport { buildHelpMessage } from "openclaw/plugin-sdk/command-auth"; // پس از اینimport { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

// پیش از اینapi.on("deactivate", async (event, ctx) => {  await stopPluginService(ctx);}); // پس از اینapi.on("gateway_stop", async (event, ctx) => {  await stopPluginService(ctx);});

// پیش از اینapi.on("subagent_spawning", async () => ({  status: "ok",  threadBindingReady: true,  deliveryOrigin: { channel: "discord", to: "channel:123", threadId: "456" },})); // پس از اینapi.on("subagent_spawned", async (event) => {  await observeSubagentLaunch(event);});

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

// پیش از تغییرconst flow = api.runtime.tasks.flow.fromToolContext(ctx);// پس از تغییرconst flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// پیش از تغییرimport type { OpenClawSchemaType } from "openclaw/plugin-sdk";// پس از تغییرimport type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";

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

کد صدای بی‌درنگ، تلفن، جلسه و Talk مرورگر، یک کنترل‌کنندهٔ نشست Talk مشترک دارد که توسط openclaw/plugin-sdk/realtime-voice صادر می‌شود. این کنترل‌کننده مالک پوش رویداد مشترک Talk، وضعیت نوبت فعال، وضعیت ضبط، وضعیت صدای خروجی، تاریخچهٔ رویدادهای اخیر و رد نوبت‌های منقضی‌شده است. Pluginهای ارائه‌دهنده مالک نشست‌های بی‌درنگ مختص فروشنده هستند. Pluginهای جلسهٔ مرورگر از openclaw/plugin-sdk/meeting-runtime برای سازوکارهای نشست، مرورگر، صدا، میزبان Node، مشاوره با عامل و تماس صوتی استفاده می‌کنند و سپس MeetingPlatformAdapter را برای قواعد URL، اسکریپت‌های DOM، نگاشت اقدام دستی، زیرنویس‌ها، ایجاد و طرح‌های شماره‌گیری ورودی پیاده‌سازی می‌کنند. APIهای REST پلتفرم، OAuth، مصنوعات، انتخابگرها و نام‌های سیمی در Plugin باقی می‌مانند. طرح‌های مجوز مرورگر URL جلسهٔ درخواستی را دریافت می‌کنند تا هر پلتفرم بتواند فقط به مبدأهای دقیقاً پشتیبانی‌شدهٔ خود مجوز دهد. زمان‌های اجرای نشست باید سلامت زندهٔ مختص پلتفرم را نیز پس از خروج تأییدشده از مرورگر عادی‌سازی کنند؛ فیلدهای رونوشت تاریخی می‌توانند باقی بمانند، اما آمادگی زیرنویس و صدا نباید پس از خروج فعال بماند.

همهٔ سطوح همراه روی کنترل‌کنندهٔ مشترک اجرا می‌شوند: رلهٔ مرورگر، واگذاری اتاق مدیریت‌شده، بی‌درنگ تماس صوتی، STT جریانی تماس صوتی، بی‌درنگ Google Meet و فشردن برای صحبت بومی. Gateway یک کانال رویداد زندهٔ Talk را در hello-ok.features.events اعلام می‌کند: talk.event.

کد جدید نباید createTalkEventSequencer(...) را مستقیماً فراخوانی کند، مگر اینکه یک آداپتور سطح‌پایین یا فیکسچر آزمون را پیاده‌سازی کند. از کنترل‌کنندهٔ مشترک استفاده کنید تا رویدادهای محدود به نوبت بدون شناسهٔ نوبت منتشر نشوند، فراخوانی‌های منقضی‌شدهٔ turnEnd / turnCancel نتوانند نوبت فعال جدیدتری را پاک کنند و رویدادهای چرخهٔ عمر صدای خروجی در تلفن، جلسات، رلهٔ مرورگر، واگذاری اتاق مدیریت‌شده و کلاینت‌های بومی Talk سازگار بمانند.

شکل API عمومی:

// API نشست Talk تحت مالکیت Gateway.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 }); // 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/وب‌سوکت ارائه‌دهنده تحت مالکیت مرورگر از talk.client.create استفاده می‌کنند، زیرا مرورگر مالک مذاکره با ارائه‌دهنده و انتقال رسانه است، درحالی‌که Gateway مالک اعتبارنامه‌ها، دستورالعمل‌ها و سیاست ابزار است. talk.session.* سطح مشترک مدیریت‌شده توسط Gateway برای بی‌درنگ رلهٔ Gateway، رونویسی رلهٔ Gateway و نشست‌های بومی STT/TTS اتاق مدیریت‌شده است.

پیکربندی‌های قدیمی که انتخابگرهای بی‌درنگ را کنار talk.provider / talk.providers قرار می‌دهند باید با openclaw doctor --fix تعمیر شوند؛ Talk در زمان اجرا پیکربندی ارائه‌دهندهٔ گفتار/TTS را به‌عنوان پیکربندی ارائه‌دهندهٔ بی‌درنگ بازتفسیر نمی‌کند.

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

نگاشت متد برای خوانندگانی که از خانواده‌های قدیمی talk.realtime.* / talk.transcription.* / talk.handoff.* مهاجرت می‌کنند (همگی حذف شده‌اند):

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

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

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

زیرمسیرهای عمومی باقی‌مانده SDK در زیر، بازه‌های حذف مبتنی بر رجیستری دارند. ردیف‌های 30 ژوئیه پس از پاک‌سازی زودهنگامِ مجازشده توسط نگه‌دارنده حذف شدند: زیرمسیرهای استفاده‌نشده حذف شدند، نام‌های مستعار سازگاری پیشین حذف شدند و ماژول‌های مخصوص نسخه همراه به نگاشت‌های ساخت خصوصی و محلی تنزل یافتند.

همه Pluginهای هسته از قبل مهاجرت کرده‌اند. Pluginهای خارجی باید پیش از نسخه اصلی بعدی مهاجرت کنند. برای مشاهده اینکه کدام رکوردهای سازگاری برای سطوح مورداستفاده Plugin شما زودتر سررسید می‌شوند، pnpm plugins:boundary-report را اجرا کنید.

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

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway runOPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

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

مرتبط

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