Pluginها

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

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

الزامات

• یک نسخهٔ دریافت‌شده یا نصب‌شده از OpenClaw که CLI ‏openclaw در آن در دسترس باشد
• دسترسی شبکه به منبع انتخاب‌شده (ClawHub، npm یا یک میزبان git)
• هرگونه اعتبارنامه، کلید پیکربندی یا ابزار سیستم‌عامل مختص Plugin که در مستندات راه‌اندازی آن Plugin ذکر شده باشد
• مجوز بارگذاری مجدد یا راه‌اندازی مجدد برای Gateway ارائه‌دهندهٔ کانال‌های شما

شروع سریع

openclaw plugins search "calendar"

# From ClawHub.openclaw plugins install clawhub:<package> # From npm.openclaw plugins install npm:<package> # From git.openclaw plugins install git:github.com/<owner>/<repo>@<ref> # From a local development checkout.openclaw plugins install ./my-pluginopenclaw plugins install --link ./my-plugin

openclaw plugins enable <plugin-id>

openclaw gateway restart

openclaw plugins inspect <plugin-id> --runtime --json

پیکربندی

انتخاب منبع نصب

مشخصه‌های بدون پیشوند بسته رفتار سازگاری ویژه‌ای دارند: نام بدون پیشوندی که با شناسهٔ یک Plugin همراه مطابقت داشته باشد از همان منبع همراه استفاده می‌کند؛ نام بدون پیشوندی که با شناسهٔ یک Plugin رسمی خارجی مطابقت داشته باشد از کاتالوگ بسته‌های رسمی استفاده می‌کند؛ هر مشخصهٔ بدون پیشوند دیگری در دورهٔ انتقال عرضه از طریق npm نصب می‌شود. مشخصه‌های خام @openclaw/* که با Pluginهای همراه مطابقت دارند نیز پیش از بازگشت به npm به نسخهٔ همراه نگاشت می‌شوند. برای نصب عامدانهٔ بستهٔ خارجی npm به‌جای نسخهٔ همراه، از npm:@openclaw/<plugin>@<version> استفاده کنید. برای انتخاب قطعی منبع از clawhub:، npm:، git: یا npm-pack: استفاده کنید. برای قرارداد کامل فرمان، به openclaw plugins مراجعه کنید.

در نصب‌های npm، مشخصه‌های بدون نسخهٔ ثابت و @latest جدیدترین بستهٔ پایداری را انتخاب می‌کنند که سازگاری با این ساخت OpenClaw را اعلام کرده باشد. اگر آخرین انتشار فعلی npm مقدار جدیدتری برای openclaw.compat.pluginApi یا openclaw.install.minHostVersion نسبت به پشتیبانی این ساخت اعلام کند، OpenClaw نسخه‌های پایدار قدیمی‌تر را بررسی می‌کند و جدیدترین نسخهٔ سازگار را نصب می‌کند. نسخه‌های دقیق و برچسب‌های صریح کانال مانند @beta روی بستهٔ انتخاب‌شده ثابت می‌مانند و در صورت ناسازگاری با خطا متوقف می‌شوند.

سیاست نصب اپراتور

security.installPolicy را پیکربندی کنید تا پیش از ادامهٔ نصب یا به‌روزرسانی Plugin، یک فرمان سیاست محلی مورداعتماد اجرا شود. سیاست، فراداده به‌همراه مسیر منبع آماده‌شده را دریافت می‌کند و می‌تواند نصب را مجاز یا مسدود کند. این سیاست هم مسیرهای نصب/به‌روزرسانی CLI و هم مسیرهای مبتنی بر Gateway را پوشش می‌دهد. هوک‌های before_install مربوط به Plugin دیرتر اجرا می‌شوند و فقط در فرایندهای OpenClaw که هوک‌های Plugin در آن‌ها بارگذاری شده‌اند؛ بنابراین برای تصمیم‌های نصب متعلق به اپراتور، به‌جای آن‌ها از security.installPolicy استفاده کنید. پرچم منسوخ‌شدهٔ --dangerously-force-unsafe-install برای سازگاری پذیرفته می‌شود، اما هیچ اثری ندارد: این پرچم نه سیاست نصب را دور می‌زند و نه فهرست ممنوعهٔ داخلی وابستگی‌های Plugin در OpenClaw را.

برای طرح اجرای مشترک security.installPolicy که هم Skills و هم Pluginها از آن استفاده می‌کنند، به پیکربندی Skills مراجعه کنید.

پیکربندی سیاست Plugin

شکل رایج پیکربندی Plugin چنین است:

{  plugins: {    enabled: true,    allow: ["voice-call"],    deny: ["untrusted-plugin"],    load: { paths: ["~/Projects/oss/voice-call-plugin"] },    slots: { memory: "memory-core" },    entries: {      "voice-call": { enabled: true, config: { provider: "twilio" } },    },  },}

قواعد اصلی سیاست:

• plugins.enabled: false همهٔ Pluginها را غیرفعال می‌کند و کار کشف/بارگذاری را نادیده می‌گیرد. ارجاع‌های منسوخ Plugin در مدت فعال بودن این گزینه بی‌اثر می‌مانند؛ اگر می‌خواهید شناسه‌های منسوخ حذف شوند، پیش از اجرای پاک‌سازی doctor دوباره Pluginها را فعال کنید.
• plugins.deny بر فهرست مجاز و فعال‌سازی هر Plugin اولویت دارد.
• plugins.allow یک فهرست مجاز انحصاری است. ابزارهای متعلق به Plugin که خارج از فهرست مجاز باشند، حتی وقتی tools.allow شامل "*" است نیز در دسترس نمی‌مانند.
• plugins.entries.<id>.enabled: false یک Plugin را با حفظ پیکربندی آن غیرفعال می‌کند.
• plugins.load.paths فایل‌ها یا دایرکتوری‌های صریح Plugin محلی را اضافه می‌کند. مسیرهای محلی مدیریت‌شده با plugins install باید دایرکتوری یا بایگانی Plugin باشند؛ برای فایل‌های مستقل Plugin از plugins.load.paths استفاده کنید.
• Pluginهای منشأگرفته از فضای کاری به‌طور پیش‌فرض غیرفعال هستند؛ پیش از استفاده از کد محلی فضای کاری، آن‌ها را صریحاً فعال کنید یا در فهرست مجاز قرار دهید.
• Pluginهای همراه از فرادادهٔ داخلی پیش‌فرض روشن/خاموش خود پیروی می‌کنند، مگر اینکه پیکربندی صریحاً آن را بازنویسی کند.
• plugins.slots.<slot> (memory یا contextEngine) یک Plugin را برای یک دستهٔ انحصاری انتخاب می‌کند. انتخاب جایگاه به‌عنوان فعال‌سازی صریح محسوب می‌شود و Plugin انتخاب‌شده را برای آن جایگاه به‌اجبار فعال می‌کند، حتی اگر در حالت عادی نیازمند فعال‌سازی اختیاری باشد. plugins.deny و plugins.entries.<id>.enabled: false همچنان آن را مسدود می‌کنند.
• Pluginهای همراهِ اختیاری می‌توانند وقتی پیکربندی یکی از سطوح متعلق به آن‌ها، مانند ارجاع ارائه‌دهنده/مدل، پیکربندی کانال، پشتیبان CLI یا زمان اجرای چارچوب عامل را نام می‌برد، به‌طور خودکار فعال شوند.
• مسیریابی Codex از خانوادهٔ OpenAI مرزهای Plugin ارائه‌دهنده و زمان اجرا را جدا نگه می‌دارد: ارجاع‌های قدیمی مدل Codex پیکربندی منسوخی هستند که doctor آن‌ها را اصلاح می‌کند، در حالی که Plugin همراه codex مالک زمان اجرای کارساز برنامهٔ Codex برای ارجاع‌های عامل استاندارد openai/*، agentRuntime.id: "codex" صریح و ارجاع‌های قدیمی codex/* است.

وقتی plugins.allow تنظیم نشده باشد و Pluginهای غیرهمراه به‌طور خودکار از فضای کاری یا ریشه‌های سراسری Plugin کشف شوند، راه‌اندازی پیام plugins.allow is empty; discovered non-bundled plugins may auto-load: ... را همراه با شناسه‌های Plugin کشف‌شده و، برای فهرست‌های کوتاه، یک قطعهٔ حداقلی plugins.allow ثبت می‌کند. پیش از کپی‌کردن Pluginهای مورداعتماد در openclaw.json، برای شناسهٔ Plugin فهرست‌شده openclaw plugins list --enabled --verbose یا openclaw plugins inspect <id> را اجرا کنید. همین ثابت‌سازی اعتماد زمانی نیز اعمال می‌شود که ابزارهای تشخیصی اعلام کنند Plugin without install/load-path provenance بارگذاری شده است: آن شناسهٔ Plugin را بازرسی کنید، سپس آن را در plugins.allow ثابت کنید یا از یک منبع مورداعتماد دوباره نصب کنید تا OpenClaw منشأ نصب را ثبت کند.

وقتی اعتبارسنجی پیکربندی شناسه‌های منسوخ Plugin، عدم تطابق فهرست مجاز/ابزار یا مسیرهای قدیمی Plugin همراه را گزارش می‌کند، openclaw doctor یا openclaw doctor --fix را اجرا کنید.

آشنایی با قالب‌های Plugin

OpenClaw دو قالب Plugin را می‌شناسد:

هر دو قالب در openclaw plugins list، openclaw plugins inspect، openclaw plugins enable و openclaw plugins disable نمایش داده می‌شوند. برای مرز سازگاری بسته‌ها به بسته‌های Plugin و برای ساخت Plugin بومی به ساخت Pluginها مراجعه کنید.

هوک‌های Plugin

Pluginها می‌توانند هنگام اجرا از طریق دو API متفاوت هوک ثبت کنند:

• هوک‌های نوع‌دار api.on(...) برای رویدادهای چرخهٔ حیات زمان اجرا. این سطح ترجیحی برای میان‌افزار، سیاست، بازنویسی پیام، شکل‌دهی پرامپت و کنترل ابزار است.
• api.registerHook(...) برای سامانهٔ داخلی هوک که در هوک‌ها توضیح داده شده است. این روش عمدتاً برای عوارض جانبی کلی فرمان/چرخهٔ حیات و سازگاری با خودکارسازی‌های موجود به سبک HOOK است.

قاعدهٔ سریع: اگر کنترل‌گر به اولویت، معنای ادغام یا رفتار مسدودسازی/لغو نیاز دارد، از هوک‌های نوع‌دار استفاده کنید. اگر فقط به command:new، command:reset، message:sent یا رویدادهای کلی مشابه واکنش نشان می‌دهد، api.registerHook مناسب است.

هوک‌های داخلی مدیریت‌شده توسط Plugin در openclaw hooks list با plugin:<id> نمایش داده می‌شوند. نمی‌توانید آن‌ها را از طریق openclaw hooks فعال یا غیرفعال کنید؛ در عوض Plugin را فعال یا غیرفعال کنید.

تأیید Gateway فعال

openclaw plugins list و openclaw plugins inspect ساده، پیکربندی، مانیفست و وضعیت رجیستری سرد را می‌خوانند. آن‌ها ثابت نمی‌کنند که یک Gateway از قبل در حال اجرا همان کد Plugin را وارد کرده است.

وقتی Plugin نصب‌شده به نظر می‌رسد اما ترافیک زندهٔ گفتگو از آن استفاده نمی‌کند:

openclaw gateway status --deep --require-rpcopenclaw plugins inspect <plugin-id> --runtime --jsonopenclaw gateway restart

Gatewayهای مدیریت‌شده پس از تغییرات نصب، به‌روزرسانی و حذف Plugin که منبع Plugin را تغییر می‌دهند، به‌طور خودکار راه‌اندازی مجدد می‌شوند. در نصب‌های VPS یا کانتینری، مطمئن شوید هر راه‌اندازی مجدد دستی، فرایند فرزند واقعی openclaw gateway run را که به کانال‌های شما سرویس می‌دهد هدف می‌گیرد، نه فقط یک پوشاننده یا ناظر فرایند را.

عیب‌یابی

وقتی پیکربندی منسوخ Plugin همچنان یک Plugin کانالِ دیگر غیرقابل‌شناسایی را نام می‌برد، اعتبارسنجی پیکربندی کلید آن کانال را به‌جای خطای قطعی به هشدار تنزل می‌دهد تا راه‌اندازی Gateway همچنان بتواند به همه کانال‌های دیگر سرویس دهد. برای حذف ورودی‌های منسوخ Plugin و کانال، openclaw doctor --fix را اجرا کنید. کلیدهای ناشناخته کانال که شواهدی از Plugin منسوخ ندارند، همچنان باعث شکست اعتبارسنجی می‌شوند تا خطاهای تایپی قابل مشاهده بمانند.

برای جایگزینی عمدی کانال، Plugin ترجیحی باید channelConfigs.<channel-id>.preferOver را با شناسه Plugin قدیمی یا کم‌اولویت‌تر اعلام کند. اگر هر دو Plugin صراحتاً فعال باشند، OpenClaw آن درخواست را حفظ می‌کند و به‌جای انتخاب بی‌سروصدای یک مالک، عیب‌یابی‌های مالکیت تکراری کانال/ابزار را گزارش می‌دهد.

اگر یک بسته نصب‌شده گزارش دهد که requires compiled runtime output for TypeScript entry ...، آن بسته بدون فایل‌های JavaScript موردنیاز OpenClaw در زمان اجرا منتشر شده است. پس از آنکه ناشر JavaScript کامپایل‌شده را عرضه کرد، بسته را به‌روزرسانی یا دوباره نصب کنید؛ یا تا آن زمان Plugin را غیرفعال/حذف کنید.

مالکیت مسیر مسدودشده Plugin

اگر عیب‌یابی‌ها عبارت blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) را نشان دهند و اعتبارسنجی با plugin present but blocked ادامه یابد، OpenClaw فایل‌های Plugin را یافته است که مالک آن‌ها یک کاربر Unix متفاوت از کاربری است که فرایند بارگذاری با آن اجرا می‌شود. پیکربندی Plugin را حفظ کنید؛ مالکیت سامانه فایل را اصلاح کنید یا OpenClaw را با همان کاربری اجرا کنید که مالک پوشه وضعیت است.

برای نصب‌های Docker، تصویر رسمی با کاربر node و uid برابر با 1000 اجرا می‌شود؛ بنابراین پوشه‌های پیکربندی و فضای کاری OpenClaw که از میزبان به‌صورت bind mount متصل شده‌اند، معمولاً باید متعلق به uid برابر با 1000 باشند:

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

اگر عمداً OpenClaw را با کاربر root اجرا می‌کنید، در عوض مالکیت ریشه مدیریت‌شده Plugin را به root تغییر دهید:

sudo chown -R root:root /path/to/openclaw-config/npm

پس از اصلاح مالکیت، openclaw doctor --fix یا openclaw plugins registry --refresh را دوباره اجرا کنید تا رجیستری پایدارشده Plugin با فایل‌های اصلاح‌شده مطابقت داشته باشد.

راه‌اندازی کند ابزارهای Plugin

اگر نوبت‌های عامل هنگام آماده‌سازی ابزارها ظاهراً متوقف می‌شوند، ثبت گزارش در سطح ردیابی را فعال کنید و خطوط زمان‌بندی کارخانه ابزار Plugin را بررسی کنید:

openclaw config set logging.level traceopenclaw logs --follow

به‌دنبال این مورد بگردید:

[trace:plugin-tools] factory timings ...

خلاصه، زمان کل کارخانه و کندترین کارخانه‌های ابزار Plugin را فهرست می‌کند و شامل شناسه Plugin، نام ابزارهای اعلام‌شده، ساختار نتیجه و اختیاری‌بودن ابزار است. اگر یک کارخانه دست‌کم ۱ ثانیه طول بکشد یا مجموع آماده‌سازی کارخانه ابزار Plugin دست‌کم ۵ ثانیه باشد، خطوط کند به هشدار ارتقا می‌یابند.

OpenClaw نتایج موفق کارخانه ابزار Plugin را برای تفکیک‌های تکراری با زمینه مؤثر درخواست یکسان ذخیره موقت می‌کند. کلید حافظه نهان شامل پیکربندی مؤثر زمان اجرا، فضای کاری و شناسه عامل، سیاست محیط ایزوله، تنظیمات مرورگر، زمینه تحویل، هویت درخواست‌کننده و وضعیت مالکیت است؛ بنابراین کارخانه‌هایی که به این فیلدهای مورداعتماد وابسته‌اند، هنگام تغییر زمینه دوباره اجرا می‌شوند. اگر زمان‌ها همچنان زیاد بمانند، ممکن است Plugin پیش از بازگرداندن تعریف ابزارهایش کار پرهزینه‌ای انجام دهد.

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

openclaw plugins inspect <plugin-id> --runtime --json

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

برای ریشه‌های وابستگی، اعتبارسنجی فراداده بسته، رکوردهای رجیستری، رفتار بارگذاری مجدد هنگام راه‌اندازی و پاک‌سازی قدیمی، به تفکیک وابستگی Plugin مراجعه کنید.

مرتبط

• مدیریت Pluginها - نمونه فرمان‌های فهرست‌کردن، نصب، به‌روزرسانی، حذف و انتشار
• openclaw plugins - مرجع کامل CLI
• فهرست موجودی Plugin - فهرست تولیدشده Pluginهای همراه و خارجی
• مرجع Plugin - صفحه‌های مرجع تولیدشده برای هر Plugin
• Pluginهای جامعه - کشف در ClawHub و سیاست درخواست ادغام مستندات
• تفکیک وابستگی Plugin - ریشه‌های نصب، رکوردهای رجیستری و مرزهای زمان اجرا
• ساخت Pluginها - راهنمای تألیف بومی Plugin
• نمای کلی SDK ‏Plugin - ثبت زمان اجرا، هوک‌ها و فیلدهای API
• مانیفست Plugin - مانیفست و فراداده بسته