Pluginها

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

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

پیش‌نیازها

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

شروع سریع

openclaw plugins search "calendar"

# از ClawHub.openclaw plugins install clawhub:<package> # از npm.openclaw plugins install npm:<package> # از git.openclaw plugins install git:github.com/<owner>/<repo>@<ref> # از یک 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 جدیدترین بستهٔ پایدار را انتخاب می‌کنند که سازگاری با این build از OpenClaw را اعلام کرده باشد. اگر نسخهٔ latest فعلی npm مقدار جدیدتری برای openclaw.compat.pluginApi یا openclaw.install.minHostVersion نسبت به مقدار پشتیبانی‌شده توسط این build اعلام کند، OpenClaw نسخه‌های پایدار قدیمی‌تر را اسکن می‌کند و جدیدترین نسخهٔ سازگار را نصب می‌کند. نسخه‌های دقیق و برچسب‌های صریح کانال مانند @beta روی بستهٔ انتخاب‌شده ثابت می‌مانند و در صورت ناسازگاری ناموفق می‌شوند.

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

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

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

وقتی plugins.allow تنظیم نشده باشد و Pluginهای غیرهمراه به‌طور خودکار از workspace یا ریشه‌های سراسری Plugin کشف شوند، گزارش‌های راه‌اندازی plugins.allow is empty; discovered non-bundled plugins may auto-load: ... را همراه با شناسه‌های Plugin کشف‌شده و برای فهرست‌های کوتاه، یک قطعهٔ حداقلی plugins.allow ثبت می‌کنند. پیش از کپی‌کردن Pluginهای مورداعتماد در openclaw.json، فرمان openclaw plugins list --enabled --verbose یا openclaw plugins inspect <id> را روی شناسهٔ Plugin فهرست‌شده اجرا کنید. همین تثبیت اعتماد هنگامی نیز اعمال می‌شود که عیب‌یابی اعلام کند یک 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ها مراجعه کنید.

hookهای Plugin

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

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

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

hookهای داخلی مدیریت‌شده توسط 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 مدیریت‌شدهٔ فعال در هنگام راه‌اندازی Gateway ناموفق باشد، OpenClaw دقیقاً همان ریشهٔ Plugin نصب‌شده را برای آن راه‌اندازی قرنطینه می‌کند و به سرویس‌دهی سایر Pluginها ادامه می‌دهد. openclaw status --all، openclaw health و openclaw doctor آن را به‌صورت configured-unavailable گزارش می‌کنند. Plugin را اصلاح یا دوباره نصب کنید، سپس Gateway را راه‌اندازی مجدد کنید. یک بازنویسی صریح و سالم plugins.load.paths با همان شناسهٔ Plugin، به‌دلیل یک نصب خراب منسوخ قرنطینه نمی‌شود.

وقتی پیکربندی منسوخ 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

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

openclaw config set logging.level traceopenclaw logs --follow

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

[trace:plugin-tools] زمان‌بندی سازنده‌ها ...

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

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

اگر یک Plugin بر زمان‌بندی غالب است، ثبت‌های زمان اجرای آن را بررسی کنید:

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

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

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

مرتبط

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