نقاط ورود Plugin

هر Plugin یک شیء ورودی پیش‌فرض صادر می‌کند. SDK سه کمک‌کننده برای ایجاد آن‌ها فراهم می‌کند.

برای Pluginهای نصب‌شده، package.json باید بارگذاری زمان اجرا را، در صورت وجود، به JavaScript ساخته‌شده اشاره دهد:

{  "openclaw": {    "extensions": ["./src/index.ts"],    "runtimeExtensions": ["./dist/index.js"],    "setupEntry": "./src/setup-entry.ts",    "runtimeSetupEntry": "./dist/setup-entry.js"  }}

extensions و setupEntry همچنان ورودی‌های منبع معتبر برای توسعه در workspace و git checkout باقی می‌مانند. وقتی OpenClaw یک package نصب‌شده را بارگذاری می‌کند، runtimeExtensions و runtimeSetupEntry ترجیح داده می‌شوند و به packageهای npm اجازه می‌دهند از کامپایل TypeScript در زمان اجرا اجتناب کنند. ورودی‌های زمان اجرای صریح الزامی هستند: runtimeSetupEntry به setupEntry نیاز دارد، و نبود artifactهای runtimeExtensions یا runtimeSetupEntry باعث شکست نصب/کشف می‌شود به‌جای اینکه بی‌سروصدا به منبع fallback کند. اگر یک package نصب‌شده فقط یک ورودی منبع TypeScript اعلام کند، OpenClaw وقتی peer متناظر ساخته‌شده dist/*.js وجود داشته باشد از آن استفاده می‌کند، سپس به منبع TypeScript fallback می‌کند.

همه مسیرهای ورودی باید داخل دایرکتوری package مربوط به Plugin بمانند. ورودی‌های زمان اجرا و peerهای JavaScript ساخته‌شده استنباط‌شده، یک مسیر منبع extensions یا setupEntry خارج‌شونده را معتبر نمی‌کنند.

definePluginEntry

Import: openclaw/plugin-sdk/plugin-entry

برای Pluginهای ارائه‌دهنده، Pluginهای ابزار، Pluginهای hook، و هر چیزی که یک کانال پیام‌رسانی نیست.

 export default definePluginEntry({  id: "my-plugin",  name: "My Plugin",  description: "Short summary",  register(api) {    api.registerProvider({      /* ... */    });    api.registerTool({      /* ... */    });  },});

• id باید با manifest شما در openclaw.plugin.json مطابقت داشته باشد.
• kind برای slotهای انحصاری است: "memory" یا "context-engine".
• configSchema می‌تواند برای ارزیابی تنبل یک تابع باشد.
• OpenClaw آن schema را در اولین دسترسی resolve و memoize می‌کند، بنابراین سازنده‌های schema پرهزینه فقط یک‌بار اجرا می‌شوند.

defineChannelPluginEntry

Import: openclaw/plugin-sdk/channel-core

definePluginEntry را با سیم‌کشی مخصوص کانال wrap می‌کند. به‌طور خودکار api.registerChannel({ plugin }) را فراخوانی می‌کند، یک seam اختیاری metadata برای CLI راهنمای ریشه را expose می‌کند، و registerFull را بر اساس حالت ثبت gate می‌کند.

 export default defineChannelPluginEntry({  id: "my-channel",  name: "My Channel",  description: "Short summary",  plugin: myChannelPlugin,  setRuntime: setMyRuntime,  registerCliMetadata(api) {    api.registerCli(/* ... */);  },  registerFull(api) {    api.registerGatewayMethod(/* ... */);  },});

• setRuntime هنگام ثبت فراخوانی می‌شود تا بتوانید reference زمان اجرا را ذخیره کنید (معمولاً از طریق createPluginRuntimeStore). هنگام capture کردن metadata مربوط به CLI از آن صرف‌نظر می‌شود.
• registerCliMetadata در زمان api.registrationMode === "cli-metadata"، api.registrationMode === "discovery"، و api.registrationMode === "full" اجرا می‌شود. از آن به‌عنوان محل canonical برای descriptorهای CLI متعلق به کانال استفاده کنید تا راهنمای ریشه non-activating بماند، snapshotهای discovery شامل metadata ایستای command باشند، و ثبت command معمول CLI با بارگذاری کامل Plugin سازگار بماند.
• ثبت discovery غیر‌فعال‌کننده است، نه بدون import. OpenClaw ممکن است ورودی Plugin معتمد و ماژول Plugin کانال را evaluate کند تا snapshot را بسازد، بنابراین importهای سطح بالا را بدون side effect نگه دارید و socketها، clientها، workerها و serviceها را پشت مسیرهای فقط "full" قرار دهید.
• registerFull فقط وقتی اجرا می‌شود که api.registrationMode === "full". هنگام بارگذاری setup-only از آن صرف‌نظر می‌شود.
• مانند definePluginEntry، configSchema می‌تواند یک factory تنبل باشد و OpenClaw schema resolveشده را در اولین دسترسی memoize می‌کند.
• برای commandهای CLI ریشه متعلق به Plugin، وقتی می‌خواهید command بدون ناپدید شدن از درخت parse مربوط به CLI ریشه به‌صورت lazy-loaded باقی بماند، api.registerCli(..., { descriptors: [...] }) را ترجیح دهید. برای commandهای feature مربوط به paired-node، api.registerNodeCliFeature(...) را ترجیح دهید تا command زیر openclaw nodes قرار بگیرد. برای دیگر commandهای تودرتوی Plugin، parentPath را اضافه کنید و commandها را روی شیء program که به registrar پاس داده می‌شود ثبت کنید؛ OpenClaw آن را پیش از فراخوانی Plugin به command والد resolve می‌کند. برای Pluginهای کانال، ثبت آن descriptorها از registerCliMetadata(...) را ترجیح دهید و registerFull(...) را روی کارهای فقط زمان اجرا متمرکز نگه دارید.
• اگر registerFull(...) همچنین methodهای RPC مربوط به Gateway را ثبت می‌کند، آن‌ها را روی یک prefix مخصوص Plugin نگه دارید. namespaceهای رزروشده مدیریت هسته (config.*، exec.approvals.*، wizard.*، update.*) همیشه به operator.admin وادار می‌شوند.

defineSetupPluginEntry

Import: openclaw/plugin-sdk/channel-core

برای فایل سبک‌وزن setup-entry.ts. فقط { plugin } را بدون سیم‌کشی زمان اجرا یا CLI برمی‌گرداند.

 export default defineSetupPluginEntry(myChannelPlugin);

OpenClaw وقتی یک کانال disabled، پیکربندی‌نشده، یا deferred loading فعال باشد، این را به‌جای ورودی کامل بارگذاری می‌کند. برای زمان‌هایی که این موضوع اهمیت دارد، Setup و Config را ببینید.

در عمل، defineSetupPluginEntry(...) را با خانواده‌های کمک‌کننده setup محدود جفت کنید:

• openclaw/plugin-sdk/setup-runtime برای کمک‌کننده‌های setup امن برای زمان اجرا مانند adapterهای setup patch امن برای import، خروجی lookup-note، promptResolvedAllowFrom، splitSetupEntries، و proxyهای setup واگذارشده
• openclaw/plugin-sdk/channel-setup برای سطح‌های setup نصب اختیاری
• openclaw/plugin-sdk/setup-tools برای کمک‌کننده‌های CLI/archive/docs مربوط به setup/install

SDKهای سنگین، ثبت CLI، و serviceهای زمان اجرای طولانی‌مدت را در ورودی کامل نگه دارید.

کانال‌های workspace باندل‌شده که سطح‌های setup و زمان اجرا را جدا می‌کنند می‌توانند به‌جای آن از defineBundledChannelSetupEntry(...) از openclaw/plugin-sdk/channel-entry-contract استفاده کنند. این contract به ورودی setup اجازه می‌دهد exportهای Plugin/secrets امن برای setup را نگه دارد و در عین حال همچنان یک setter زمان اجرا expose کند:

 export default defineBundledChannelSetupEntry({  importMetaUrl: import.meta.url,  plugin: {    specifier: "./channel-plugin-api.js",    exportName: "myChannelPlugin",  },  runtime: {    specifier: "./runtime-api.js",    exportName: "setMyChannelRuntime",  },});

از آن contract باندل‌شده فقط وقتی استفاده کنید که flowهای setup واقعاً پیش از بارگذاری ورودی کامل کانال به یک setter زمان اجرای سبک‌وزن نیاز داشته باشند.

حالت ثبت

api.registrationMode به Plugin شما می‌گوید چگونه بارگذاری شده است:

defineChannelPluginEntry این جداسازی را به‌طور خودکار مدیریت می‌کند. اگر مستقیماً از definePluginEntry برای یک کانال استفاده می‌کنید، خودتان mode را بررسی کنید:

register(api) {  if (    api.registrationMode === "cli-metadata" ||    api.registrationMode === "discovery" ||    api.registrationMode === "full"  ) {    api.registerCli(/* ... */);    if (api.registrationMode === "cli-metadata") return;  }   api.registerChannel({ plugin: myPlugin });  if (api.registrationMode !== "full") return;   // Heavy runtime-only registrations  api.registerService(/* ... */);}

حالت discovery یک snapshot registry غیر‌فعال‌کننده می‌سازد. با این حال ممکن است ورودی Plugin و شیء Plugin کانال را evaluate کند تا OpenClaw بتواند قابلیت‌های کانال و descriptorهای CLI ایستا را ثبت کند. ارزیابی ماژول در discovery را معتمد اما سبک‌وزن در نظر بگیرید: هیچ client شبکه، subprocess، listener، اتصال database، worker پس‌زمینه، خواندن credential، یا side effect زنده زمان اجرا در سطح بالا نباشد.

"setup-runtime" را پنجره‌ای بدانید که در آن سطح‌های startup فقط setup باید بدون ورود دوباره به زمان اجرای کامل کانال باندل‌شده وجود داشته باشند. موارد مناسب شامل ثبت کانال، routeهای HTTP امن برای setup، methodهای Gateway امن برای setup، و کمک‌کننده‌های setup واگذارشده هستند. serviceهای پس‌زمینه سنگین، registrarهای CLI، و bootstrapهای SDK مربوط به provider/client همچنان به "full" تعلق دارند.

به‌طور خاص برای registrarهای CLI:

• از descriptors زمانی استفاده کنید که registrar مالک یک یا چند دستور ریشه‌ای است و می‌خواهید OpenClaw ماژول واقعی CLI را هنگام نخستین فراخوانی به‌صورت تنبل بارگذاری کند
• مطمئن شوید این descriptorها همه ریشه‌های دستور سطح‌بالا را که registrar ارائه می‌کند پوشش می‌دهند
• نام دستورهای descriptor را به حروف، اعداد، خط تیره و زیرخط محدود کنید و با حرف یا عدد شروع کنید؛ OpenClaw نام‌های descriptor خارج از این الگو را رد می‌کند و پیش از نمایش راهنما، دنباله‌های کنترلی ترمینال را از توضیحات حذف می‌کند
• از commands به‌تنهایی فقط برای مسیرهای سازگاری eager استفاده کنید

شکل‌های Plugin

OpenClaw، Pluginهای بارگذاری‌شده را بر اساس رفتار ثبت آن‌ها دسته‌بندی می‌کند:

برای دیدن شکل یک Plugin، از openclaw plugins inspect <id> استفاده کنید.

مرتبط

• نمای کلی SDK - API ثبت و مرجع زیربخش‌ها
• کمک‌کننده‌های Runtime - api.runtime و createPluginRuntimeStore
• راه‌اندازی و پیکربندی - manifest، نقطه ورود راه‌اندازی، بارگذاری معوق
• Pluginهای کانال - ساخت شیء ChannelPlugin
• Pluginهای ارائه‌دهنده - ثبت ارائه‌دهنده و قلاب‌ها