مهاجرت Plugin SDK

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های فایل، نوع‌های تأیید، و utilityهای نامرتبط را با هم مخلوط می‌کرد.
• openclaw/plugin-sdk/config-runtime - یک barrel گسترده سازگاری config که هنوز در بازه مهاجرت، helperهای مستقیم منسوخ‌شده برای load/write را نگه می‌دارد.
• openclaw/extension-api - پلی که به Pluginها دسترسی مستقیم به helperهای سمت host مانند runner عامل تعبیه‌شده می‌داد.
• api.registerEmbeddedExtensionFactory(...) - یک hook حذف‌شده مخصوص Pi برای extension بسته‌بندی‌شده که می‌توانست رویدادهای embedded-runner مانند tool_result را مشاهده کند.

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

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

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

رویکرد قدیمی مشکل‌ساز بود:

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

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

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

نمونه‌های فعلی providerهای بسته‌بندی‌شده:

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

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

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

این مهاجرت Talk عمداً breaking-clean است:

1. primitiveهای runtime/کنترل‌کننده مشترک را در plugin-sdk/realtime-voice نگه دارید.
2. سطح‌های بسته‌بندی‌شده را به کنترل‌کننده مشترک منتقل کنید: 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 رویداد زنده Talk را در Gateway hello-ok.features.events تبلیغ کنید: talk.event.
5. endpoint قدیمی HTTP realtime و هر مسیر override دستورالعمل در زمان request را حذف کنید.

کد جدید نباید مستقیماً createTalkEventSequencer(...) را صدا بزند، مگر اینکه در حال پیاده‌سازی یک adapter سطح پایین یا fixture تست باشد. کنترل‌کننده مشترک را ترجیح دهید تا رویدادهای scoped به نوبت بدون turn id صادر نشوند، فراخوانی‌های stale turnEnd / turnCancel نتوانند یک نوبت فعال جدیدتر را پاک کنند، و رویدادهای lifecycle audio خروجی در telephony، meetings، browser relay، managed-room handoff، و clientهای 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 });
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 استفاده می‌کنند، زیرا مرورگر مالک negotiation provider و transport رسانه است، در حالی که Gateway مالک credentials، instructions، و policy ابزار است. 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 repair شوند؛ runtime Talk config provider speech/TTS را به عنوان config provider realtime بازتفسیر نمی‌کند.

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

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

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

برای کار کردن این موضوع، special caseهای provider یا platform را در core معرفی نکنید. core مالک semantics session Talk است. Pluginهای provider مالک setup session vendor هستند. voice-call و Google Meet مالک adapterهای telephony/meeting هستند. مرورگر و appهای native مالک UX مربوط به capture/playback دستگاه هستند.

# policy سازگاری

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

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

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

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

# نحوه مهاجرت

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

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

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

// Before
const program = applyWindowsSpawnProgramPolicy({ candidate });

// After
const 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 build
pnpm test -- my-plugin/

# مرجع مسیر import

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

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

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

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

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

// Before
import { buildHelpMessage } from "openclaw/plugin-sdk/command-auth";

// After
import { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

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

// Before
const flow = api.runtime.tasks.flow.fromToolContext(ctx);
// After
const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Before
import type { OpenClawSchemaType } from "openclaw/plugin-sdk";
// After
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";

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

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

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

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

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

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

# مرتبط

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