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های همراه مطابقت دارند نیز پیش از fallback به 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، یک دستور سیاست محلی مورداعتماد اجرا شود. سیاست، فراداده به‌همراه مسیر منبع staging‌شده را دریافت می‌کند و می‌تواند نصب را مجاز یا مسدود کند. این سیاست هم مسیرهای نصب/به‌روزرسانی CLI و هم مسیرهای مبتنی بر Gateway را پوشش می‌دهد. hookهای before_install مربوط به Plugin بعداً و فقط در فرایندهای OpenClaw که hookهای Plugin در آن‌ها بارگذاری شده‌اند اجرا می‌شوند؛ بنابراین برای تصمیم‌های نصب متعلق به اپراتور، به‌جای آن از security.installPolicy استفاده کنید. فلگ منسوخ --dangerously-force-unsafe-install برای سازگاری پذیرفته می‌شود، اما هیچ اثری ندارد: سیاست نصب یا denylist داخلی وابستگی‌های Plugin در OpenClaw را دور نمی‌زند.

برای schema مشترک اجرای 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 یک allowlist انحصاری است. ابزارهای متعلق به Plugin خارج از allowlist حتی وقتی tools.allow شامل "*" باشد، در دسترس نمی‌مانند.
• plugins.entries.<id>.enabled: false یک Plugin را ضمن حفظ پیکربندی آن غیرفعال می‌کند.
• plugins.load.paths فایل‌ها یا دایرکتوری‌های صریح Plugin محلی را اضافه می‌کند. مسیرهای محلی مدیریت‌شده plugins install باید دایرکتوری یا بایگانی Plugin باشند؛ برای فایل‌های مستقل Plugin از plugins.load.paths استفاده کنید.
• Pluginهای منشأگرفته از workspace به‌طور پیش‌فرض غیرفعال‌اند؛ پیش از استفاده از کد workspace محلی، آن‌ها را صریحاً فعال یا به allowlist اضافه کنید.
• 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، روی شناسه Plugin فهرست‌شده openclaw plugins list --enabled --verbose یا openclaw plugins inspect <id> را اجرا کنید. همین ثابت‌سازی اعتماد هنگامی اعمال می‌شود که عیب‌یابی اعلام کند یک Plugin با without install/load-path provenance بارگذاری شده است: آن شناسه Plugin را بررسی کنید، سپس آن را در plugins.allow ثابت کنید یا از یک منبع مورداعتماد دوباره نصب کنید تا OpenClaw منشأ نصب را ثبت کند.

وقتی اعتبارسنجی پیکربندی شناسه‌های قدیمی Plugin، عدم تطابق allowlist/ابزار یا مسیرهای قدیمی 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ها توضیح داده شده است. این مورد عمدتاً برای اثرات جانبی کلی دستور/چرخه‌عمر و سازگاری با خودکارسازی موجود به سبک 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 همچنان یک 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 و PR مستندات
• تفکیک وابستگی Plugin - ریشه‌های نصب، رکوردهای رجیستری و مرزهای زمان اجرا
• ساخت Pluginها - راهنمای توسعهٔ Plugin بومی
• نمای کلی SDKِ Plugin - ثبت زمان اجرا، هوک‌ها و فیلدهای API
• مانیفست Plugin - مانیفست و فرادادهٔ بسته