Pluginها

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

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

نیازمندی‌ها

پیش از نصب یک Plugin، مطمئن شوید که موارد زیر را دارید:

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

شروع سریع

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

پیکربندی

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

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

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

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

security.installPolicy را پیکربندی کنید تا پیش از ادامه نصب یا به‌روزرسانی Plugin، یک فرمان سیاست محلی مورد اعتماد اجرا شود. این سیاست فراداده به‌همراه مسیر منبع staged را دریافت می‌کند و می‌تواند نصب را مجاز یا مسدود کند. این مسیرهای نصب/به‌روزرسانی Plugin از طریق CLI و Gateway را پوشش می‌دهد. hookهای before_install Plugin بعداً فقط در فرایندهای OpenClaw که hookهای Plugin بارگذاری شده‌اند اجرا می‌شوند، بنابراین برای تصمیم‌های نصب متعلق به اپراتور از security.installPolicy استفاده کنید. flag منسوخ‌شده --dangerously-force-unsafe-install برای سازگاری پذیرفته می‌شود اما سیاست نصب یا فهرست انکار وابستگی 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 را رد می‌کند. ارجاع‌های کهنه 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های همراه از فراداده داخلی default-on/default-off خود پیروی می‌کنند، مگر اینکه پیکربندی صریحاً آن‌ها را override کند.
• plugins.slots.<slot> یک Plugin را برای دسته‌های انحصاری مانند حافظه و موتورهای context انتخاب می‌کند. انتخاب slot با حساب شدن به‌عنوان فعال‌سازی صریح، Plugin انتخاب‌شده برای آن slot را force-enable می‌کند؛ این Plugin حتی وقتی در حالت دیگر opt-in بود نیز می‌تواند بارگذاری شود. plugins.deny و plugins.entries.<id>.enabled: false همچنان آن را مسدود می‌کنند.
• Pluginهای opt-in همراه می‌توانند زمانی auto-activate شوند که پیکربندی یکی از سطوح متعلق به آن‌ها را نام ببرد، مانند یک provider/model ref، پیکربندی کانال، backend CLI، یا زمان اجرای harness عامل.
• مسیریابی Codex خانواده OpenAI مرزهای provider و Plugin زمان اجرا را جدا نگه می‌دارد: refهای مدل Codex legacy پیکربندی legacy هستند که توسط doctor تعمیر می‌شوند، در حالی که Plugin همراه codex مالک زمان اجرای app-server Codex برای refهای عامل canonical openai/*، agentRuntime.id: "codex" صریح، و refهای legacy codex/* است.

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

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

درک قالب‌های Plugin

OpenClaw دو قالب Plugin را تشخیص می‌دهد:

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

hookهای Plugin

Pluginها می‌توانند hookها را در زمان اجرا ثبت کنند، اما دو API متفاوت با وظایف متفاوت وجود دارد.

• از hookهای typed از طریق api.on(...) برای hookهای چرخه عمر زمان اجرا استفاده کنید. این سطح ترجیحی برای middleware، سیاست، بازنویسی پیام، شکل‌دهی prompt، و کنترل ابزار است.
• فقط وقتی می‌خواهید در سیستم hook داخلی توصیف‌شده در Hooks مشارکت کنید، از api.registerHook(...) استفاده کنید. این عمدتاً برای side effectهای درشت فرمان/چرخه عمر و سازگاری با automation موجود به سبک HOOK است.

قاعده سریع:

• اگر handler به اولویت، semantics ادغام، یا رفتار block/cancel نیاز دارد، از hookهای typed Plugin استفاده کنید.
• اگر handler فقط به 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 را هدف می‌گیرد که کانال‌های شما را سرویس می‌دهد، نه فقط یک wrapper یا supervisor.

عیب‌یابی

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

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

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

مالکیت مسیر 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 را فعال کنید و خطوط زمان‌بندی factory ابزارهای Plugin را بررسی کنید:

openclaw config set logging.level traceopenclaw logs --follow

دنبال این بگردید:

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

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

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

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

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

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

برای ریشه‌های وابستگی، اعتبارسنجی metadata بسته، رکوردهای رجیستری، رفتار reload هنگام راه‌اندازی، و پاک‌سازی legacy، حل وابستگی Plugin را ببینید.

مرتبط

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