Get started
اصلاحات اعتبارسنجی Plugin
اصلاحات اعتبارسنجی Plugin
ClawHub بستههای Plugin را پیش از انتشار اعتبارسنجی میکند و همچنین میتواند یافتههای حاصل از اسکنهای خودکار بسته را نمایش دهد. این صفحه یافتههای مربوط به نویسنده را پوشش میدهد؛ یعنی یافتههایی که نویسنده Plugin میتواند در فرادادهٔ بسته، مانیفست، importهای SDK یا آرتیفکت منتشرشدهٔ خود برطرف کند.
این صفحه یافتههای داخلی پوشش Plugin Inspector را شامل نمیشود. اگر گزارشی کامل حاوی کدهای نگهداری اسکنر بدون راهنمای رفع مشکل برای نویسنده باشد، آن موارد برای نگهدارندگان OpenClaw هستند، نه نویسندگان Plugin.
پس از اعمال هر اصلاح، دوباره اجرا کنید:
clawhub package validate <path-to-plugin>یافتههای مربوط به نویسنده
فرادادهٔ بسته
package-json-missing
ریشهٔ بسته شامل package.json نیست، بنابراین ClawHub نمیتواند
بستهٔ npm، نسخه، نقاط ورود یا فرادادهٔ OpenClaw را شناسایی کند.
package.jsonرا باname،versionوtypeاضافه کنید.- هنگامی که بسته یک Plugin OpenClaw ارائه میکند، یک بلوک
openclawاضافه کنید. - برای نمونهای حداقلی از بسته، از ساخت Pluginها و برای تفکیک بسته از مانیفست، از مانیفست Plugin استفاده کنید.
clawhub package validate <path-to-plugin>را دوباره اجرا کنید.
package-openclaw-metadata-missing
بسته دارای package.json است، اما فرادادهٔ بستهٔ
OpenClaw را اعلام نمیکند.
package.json#openclawرا اضافه کنید.- فرادادهٔ نقطهٔ ورود مانند
openclaw.extensionsیاopenclaw.runtimeExtensionsرا وارد کنید. - اگر بسته از طریق ClawHub منتشر یا نصب خواهد شد، فرادادهٔ سازگاری و نصب را اضافه کنید.
- به فیلدهای package.json مؤثر بر کشف مراجعه کنید.
clawhub package validate <path-to-plugin>را دوباره اجرا کنید.
package-openclaw-entry-missing
فرادادهٔ بسته وجود دارد، اما نقطهٔ ورود زمان اجرای OpenClaw را اعلام نمیکند.
- برای نقاط ورود بومی Plugin،
openclaw.extensionsرا اضافه کنید. - هنگامی که بستهٔ منتشرشده باید JavaScript ساختهشده را بارگذاری کند،
openclaw.runtimeExtensionsرا اضافه کنید. - همهٔ مسیرهای نقطهٔ ورود را داخل پوشهٔ بسته نگه دارید.
- به نقاط ورود Plugin و فیلدهای package.json مؤثر بر کشف مراجعه کنید.
clawhub package validate <path-to-plugin>را دوباره اجرا کنید.
package-entrypoint-missing
بسته یک نقطهٔ ورود OpenClaw را اعلام میکند، اما فایل ارجاعشده در بستهای که اعتبارسنجی میشود وجود ندارد.
- هر مسیر را در
openclaw.extensions،openclaw.runtimeExtensions،openclaw.setupEntryوopenclaw.runtimeSetupEntryبررسی کنید. - اگر نقطهٔ ورود در
distتولید میشود، بسته را بسازید. - اگر نقطهٔ ورود جابهجا شده است، فراداده را بهروزرسانی کنید.
- به نقاط ورود Plugin مراجعه کنید.
clawhub package validate <path-to-plugin>را دوباره اجرا کنید.
package-install-metadata-incomplete
ClawHub نمیتواند تشخیص دهد بسته چگونه باید نصب یا بهروزرسانی شود.
openclaw.installرا با منبع نصب پشتیبانیشده، مانندclawhubSpec،npmSpecیاlocalPathتکمیل کنید.- هنگامی که بیش از یک منبع نصب در دسترس است،
openclaw.install.defaultChoiceرا تنظیم کنید. - برای حداقل نسخهٔ میزبان OpenClaw از
openclaw.install.minHostVersionاستفاده کنید. - به فیلدهای package.json مؤثر بر کشف مراجعه کنید.
clawhub package validate <path-to-plugin>را دوباره اجرا کنید.
package-plugin-api-compat-missing
بسته محدودهٔ API Plugin OpenClaw مورد پشتیبانی خود را اعلام نمیکند.
openclaw.compat.pluginApiرا بهpackage.jsonاضافه کنید.- از نسخهٔ API Plugin OpenClaw یا کف semver که بسته را بر مبنای آن ساخته و آزمایش کردهاید استفاده کنید.
- این مورد را از نسخهٔ بسته جدا نگه دارید. نسخهٔ بسته انتشار Plugin را توصیف میکند؛
openclaw.compat.pluginApiقرارداد API میزبان را توصیف میکند. - به فیلدهای package.json مؤثر بر کشف مراجعه کنید.
clawhub package validate <path-to-plugin>را دوباره اجرا کنید.
package-min-host-version-drift
حداقل نسخهٔ میزبان بسته با فرادادهٔ نسخهٔ OpenClaw که بسته بر مبنای آن ساخته شده است مطابقت ندارد.
openclaw.install.minHostVersionرا بررسی کنید.- هرگونه فرادادهٔ ساخت OpenClaw در بسته، مانند نسخهٔ OpenClaw استفادهشده هنگام انتشار، را بررسی کنید.
- حداقل نسخهٔ میزبان را با محدودهٔ نسخهٔ میزبانی که بسته واقعاً پشتیبانی میکند همتراز کنید.
- به فیلدهای package.json مؤثر بر کشف مراجعه کنید.
clawhub package validate <path-to-plugin>را دوباره اجرا کنید.
package-manifest-version-drift
نسخهٔ بسته و نسخهٔ مانیفست Plugin با یکدیگر مغایرت دارند.
package.json#versionرا بهعنوان نسخهٔ انتشار بسته ترجیح دهید.- اگر
openclaw.plugin.jsonنیز دارایversionاست، آن را برای مطابقت بهروزرسانی کنید یا وقتی فرادادهٔ بسته مرجع اصلی است، فرادادهٔ قدیمی نسخهٔ مانیفست را حذف کنید. - پس از تغییر فرادادهٔ منتشرشده، نسخهٔ جدیدی از بسته منتشر کنید.
- به مانیفست Plugin مراجعه کنید.
clawhub package validate <path-to-plugin>را دوباره اجرا کنید.
package-openclaw-unsupported-metadata
بلوک package.json#openclaw حاوی فیلدهایی است که بهعنوان
فرادادهٔ بستهٔ OpenClaw پشتیبانی نمیشوند.
- فیلدهای پشتیبانینشده مانند
openclaw.bundleرا حذف کنید. - فرادادهٔ Plugin بومی را در
openclaw.plugin.jsonنگه دارید. - نقاط ورود بسته، فرادادهٔ سازگاری، نصب، راهاندازی و کاتالوگ را
در فیلدهای پشتیبانیشدهٔ
package.json#openclawنگه دارید. - به فیلدهای package.json مؤثر بر کشف مراجعه کنید.
clawhub package validate <path-to-plugin>را دوباره اجرا کنید.
آرتیفکت منتشرشده
package-npm-pack-unavailable
بسته را نمیتوان در آرتیفکتی بستهبندی کرد که ClawHub آن را بازرسی یا منتشر میکند.
npm pack --dry-runرا از ریشهٔ بسته اجرا کنید.- فرادادهٔ نامعتبر بسته، اسکریپتهای چرخهٔ عمر خراب یا ورودیهای files را که باعث شکست بستهبندی میشوند، اصلاح کنید.
- اگر این بسته برای انتشار عمومی در نظر گرفته شده است،
private: trueرا حذف کنید. clawhub package validate <path-to-plugin>را دوباره اجرا کنید.
package-npm-pack-entrypoint-missing
بسته قابلبستهبندی است، اما آرتیفکت بستهبندیشده فایلهای
نقطهٔ ورود اعلامشده در package.json#openclaw را شامل نمیشود.
npm pack --dry-runرا اجرا و فایلهایی را که گنجانده خواهند شد بررسی کنید.- پیش از بستهبندی، نقاط ورود تولیدشده را بسازید.
files،.npmignoreیا خروجی ساخت را بهروزرسانی کنید تا نقاط ورود اعلامشده گنجانده شوند.- به نقاط ورود Plugin مراجعه کنید.
clawhub package validate <path-to-plugin>را دوباره اجرا کنید.
package-npm-pack-metadata-missing
آرتیفکت بستهبندیشده فاقد فرادادهٔ OpenClaw موجود در بستهٔ منبع شما است.
npm pack --dry-runرا اجرا کنید و فایلهای فرادادهٔ موجود را بررسی کنید.- مطمئن شوید
package.jsonبلوکopenclawرا در مصنوع بستهبندیشده شامل میشود. - هنگامی که بسته یک plugin بومی OpenClaw است، مطمئن شوید
openclaw.plugin.jsonدر آن گنجانده شده است. filesیا.npmignoreرا بهروزرسانی کنید تا فرادادهٔ بسته مستثنا نشود.- ساخت pluginها را ببینید.
clawhub package validate <path-to-plugin>را دوباره اجرا کنید.
فرادادهٔ مانیفست
manifest-name-missing
مانیفست plugin بومی شامل نام نمایشی نیست.
- یک فیلد غیرخالی
nameبهopenclaw.plugin.jsonاضافه کنید. nameرا خوانا برای انسان نگه دارید وidرا بهعنوان شناسهٔ پایدار ماشین حفظ کنید.- مانیفست Plugin را ببینید.
clawhub package validate <path-to-plugin>را دوباره اجرا کنید.
manifest-unknown-fields
مانیفست plugin دارای فیلدهای سطح بالایی است که OpenClaw از آنها پشتیبانی نمیکند.
- هر فیلد سطح بالا را با مرجع فیلدهای مانیفست مقایسه کنید.
- فیلدهای سفارشی را از
openclaw.plugin.jsonحذف کنید. - فرادادهٔ بسته یا نصب را بهجای مانیفست، به فیلدهای پشتیبانیشدهٔ
package.json#openclawمنتقل کنید. clawhub package validate <path-to-plugin>را دوباره اجرا کنید.
manifest-unknown-contracts
مانیفست کلیدهای پشتیبانینشدهای را درون contracts اعلام میکند.
- هر کلید زیر
contractsرا با مرجع قراردادها مقایسه کنید. - کلیدهای قرارداد پشتیبانینشده را حذف کنید.
- رفتار زمان اجرا را به کد ثبت plugin منتقل کنید و
contractsرا به فرادادهٔ ایستای مالکیت قابلیت محدود نگه دارید. clawhub package validate <path-to-plugin>را دوباره اجرا کنید.
مهاجرت SDK و سازگاری
legacy-root-sdk-import
plugin از barrel ریشهٔ منسوخشدهٔ SDK وارد میکند:
openclaw/plugin-sdk.
- واردسازیهای barrel ریشه را با واردسازیهای متمرکز از زیرمسیرهای عمومی جایگزین کنید.
- برای
definePluginEntryازopenclaw/plugin-sdk/plugin-entryاستفاده کنید. - برای کمکتابعهای نقطهٔ ورود کانال از
openclaw/plugin-sdk/channel-coreاستفاده کنید. - برای یافتن واردسازی محدود، از قراردادهای واردسازی و زیرمسیرهای SDK مربوط به Plugin استفاده کنید.
clawhub package validate <path-to-plugin>را دوباره اجرا کنید.
reserved-sdk-import
plugin یک مسیر SDK را وارد میکند که برای pluginهای همراه یا سازگاری داخلی رزرو شده است.
- واردسازیهای رزروشدهٔ SDK داخلی OpenClaw را با زیرمسیرهای عمومی و مستندشدهٔ
openclaw/plugin-sdk/*جایگزین کنید. - اگر این رفتار SDK عمومی ندارد، کمکتابع را درون بستهٔ خود نگه دارید یا یک API عمومی OpenClaw درخواست کنید.
- برای انتخاب واردسازی پشتیبانیشده، از زیرمسیرهای SDK مربوط به Plugin و مهاجرت SDK استفاده کنید.
clawhub package validate <path-to-plugin>را دوباره اجرا کنید.
sdk-load-session-store
plugin همچنان از کمکتابع منسوخشدهٔ کل مخزن نشست
loadSessionStore استفاده میکند.
- هنگام خواندن وضعیت نشست، از
getSessionEntry(...)یاlistSessionEntries(...)استفاده کنید. - هنگام نوشتن وضعیت نشست، از
patchSessionEntry(...)یاupsertSessionEntry(...)استفاده کنید. - از بارگذاری، تغییر و ذخیرهسازی کل شیء مخزن نشست خودداری کنید.
loadSessionStore(...)را فقط تا زمانی نگه دارید که محدودهٔ سازگاری اعلامشدهٔ شما همچنان از نسخههای قدیمیتر OpenClaw که به آن نیاز دارند پشتیبانی میکند.- API زمان اجرا و زیرمسیرهای SDK مربوط به Plugin را ببینید.
clawhub package validate <path-to-plugin>را دوباره اجرا کنید.
sdk-session-store-write
plugin همچنان از یک کمکتابع منسوخشدهٔ نوشتن کل مخزن نشست مانند
saveSessionStore یا updateSessionStore استفاده میکند.
- هنگام بهروزرسانی فیلدهای یک ورودی نشست موجود، از
patchSessionEntry(...)استفاده کنید. - هنگام جایگزینی یا ایجاد یک ورودی نشست، از
upsertSessionEntry(...)استفاده کنید. - از بارگذاری، تغییر و ذخیرهسازی کل شیء مخزن نشست خودداری کنید.
- کمکتابعهای نوشتن کل مخزن را فقط تا زمانی نگه دارید که محدودهٔ سازگاری اعلامشدهٔ شما همچنان از نسخههای قدیمیتر OpenClaw که به آنها نیاز دارند پشتیبانی میکند.
- API زمان اجرا و زیرمسیرهای SDK مربوط به Plugin را ببینید.
clawhub package validate <path-to-plugin>را دوباره اجرا کنید.
sdk-session-file-helper
plugin همچنان از کمکتابعهای منسوخشدهٔ مسیر فایل نشست مانند
resolveSessionFilePath یا resolveAndPersistSessionFile استفاده میکند.
- برای خواندن فرادادهٔ نشست بر اساس هویت عامل و نشست، از
getSessionEntry(...)استفاده کنید. - برای ماندگار کردن فرادادهٔ نشست، از
patchSessionEntry(...)یاupsertSessionEntry(...)استفاده کنید. - هنگامی که کد یک عملیات رونوشت را آماده میکند، از هویت رونوشت یا کمکتابعهای هدف استفاده کنید.
- مسیرهای فایل رونوشت قدیمی را ماندگار نکنید و به آنها وابسته نباشید.
- API زمان اجرا و زیرمسیرهای SDK مربوط به Plugin را ببینید.
clawhub package validate <path-to-plugin>را دوباره اجرا کنید.
sdk-session-transcript-file-target
plugin همچنان از کمکتابع منسوخشدهٔ هدف فایل رونوشت
resolveSessionTranscriptLegacyFileTarget استفاده میکند.
- هنگامی که کد فقط به هویت عمومی نشست نیاز دارد، از
resolveSessionTranscriptIdentity(...)استفاده کنید. - هنگامی که کد به یک هدف ساختیافته برای عملیات رونوشت نیاز دارد، از
resolveSessionTranscriptTarget(...)استفاده کنید. - از خواندن یا ساخت مستقیم هدفهای قدیمی فایل رونوشت خودداری کنید.
- کمکتابع قدیمی را فقط تا زمانی نگه دارید که محدودهٔ سازگاری اعلامشدهٔ شما همچنان از نسخههای قدیمیتر OpenClaw که به آن نیاز دارند پشتیبانی میکند.
- API زمان اجرا و زیرمسیرهای SDK مربوط به Plugin را ببینید.
clawhub package validate <path-to-plugin>را دوباره اجرا کنید.
sdk-session-transcript-low-level
plugin همچنان از کمکتابعهای سطح پایین منسوخشدهٔ رونوشت مانند
appendSessionTranscriptMessage یا emitSessionTranscriptUpdate استفاده میکند.
- برای افزودن به رونوشت از
appendSessionTranscriptMessageByIdentity(...)استفاده کنید. - برای اعلانهای بهروزرسانی رونوشت از
publishSessionTranscriptUpdateByIdentity(...)استفاده کنید. - سطح ساختیافتهٔ زمان اجرای رونوشت را ترجیح دهید تا OpenClaw بتواند مرزهای صحیح تراکنش و مدیریت هویت را اعمال کند.
- کمکتابعهای سطح پایین رونوشت را فقط تا زمانی نگه دارید که محدودهٔ سازگاری اعلامشدهٔ شما همچنان از نسخههای قدیمیتر OpenClaw که به آنها نیاز دارند پشتیبانی میکند.
- API زمان اجرا و زیرمسیرهای SDK مربوط به Plugin را ببینید.
clawhub package validate <path-to-plugin>را دوباره اجرا کنید.
legacy-before-agent-start
plugin همچنان از hook قدیمی before_agent_start استفاده میکند.
- کارهای بازنویسی مدل یا ارائهدهنده را به
before_model_resolveمنتقل کنید. - کارهای تغییر prompt یا context را به
before_prompt_buildمنتقل کنید. before_agent_startرا فقط تا زمانی نگه دارید که محدودهٔ سازگاری اعلامشدهٔ شما همچنان از نسخههای قدیمیتر OpenClaw که به آن نیاز دارند پشتیبانی میکند.- Hookها و سازگاری Plugin را ببینید.
clawhub package validate <path-to-plugin>را دوباره اجرا کنید.
provider-auth-env-vars
مانیفست همچنان از فرادادهٔ قدیمی احراز هویت ارائهدهندهٔ providerAuthEnvVars استفاده میکند.
- فرادادهٔ متغیر محیطی ارائهدهنده را در
setup.providers[].envVarsنیز بازتاب دهید. providerAuthEnvVarsرا فقط بهعنوان فرادادهٔ سازگاری نگه دارید، مادامی که محدودهٔ پشتیبانیشدهٔ OpenClaw شما همچنان به آن نیاز دارد.- مرجع راهاندازی و مهاجرت SDK را ببینید.
clawhub package validate <path-to-plugin>را دوباره اجرا کنید.
channel-env-vars
مانیفست از فرادادهٔ قدیمی یا پیشین متغیر محیطی کانال، بدون فرادادهٔ کنونی راهاندازی یا پیکربندی مورد انتظار ClawHub استفاده میکند.
- فرادادهٔ متغیر محیطی کانال را اعلانی نگه دارید تا OpenClaw بتواند وضعیت راهاندازی را بدون بارگذاری زمان اجرای کانال بررسی کند.
- راهاندازی کانال مبتنی بر متغیر محیطی را در فرادادهٔ کنونی راهاندازی، پیکربندی کانال یا کانال بسته که شکل plugin شما استفاده میکند نیز بازتاب دهید.
channelEnvVarsرا فقط بهعنوان فرادادهٔ سازگاری نگه دارید، مادامی که نسخههای قدیمیتر پشتیبانیشدهٔ OpenClaw همچنان به آن نیاز دارند.- مانیفست Plugin و pluginهای کانال را ببینید.
clawhub package validate <path-to-plugin>را دوباره اجرا کنید.
مانیفست امنیتی
security-manifest-schema-unavailable
بسته، openclaw.security.json را با ارجاعی به schema ارائه میکند که ClawHub
آن را در دسترس تشخیص نمیدهد.
- اگر URL مربوط به schema فقط جنبهٔ توصیهای دارد، آن را حذف کنید.
- فقط پس از انتشار یک schema نسخهبندیشده توسط OpenClaw، از آن استفاده کنید.
clawhub package validate <path-to-plugin>را دوباره اجرا کنید.
unrecognized-security-manifest
بسته یک فایل مانیفست امنیتی پشتیبانینشده ارائه میکند.
openclaw.security.jsonرا حذف کنید تا زمانی که OpenClaw یک schema نسخهبندیشدهٔ مانیفست امنیتی و رفتار ClawHub را مستند کند.- تا زمان ایجاد قرارداد مانیفست، رفتار حساس به امنیت را در مستندات عمومی بسته یا README خود مستند نگه دارید.
clawhub package validate <path-to-plugin>را دوباره اجرا کنید.
