Plugin‌ها

Pluginها OpenClaw را با قابلیت‌های جدید گسترش می‌دهند: کانال‌ها، ارائه‌دهندگان مدل، هارنس‌های عامل، ابزارها، Skills، گفتار، رونویسی بی‌درنگ، صدای بی‌درنگ، درک رسانه، تولید تصویر، تولید ویدئو، واکشی وب، جستجوی وب و موارد بیشتر. برخی Pluginها هسته‌ای هستند (همراه OpenClaw ارائه می‌شوند)، و برخی دیگر خارجی هستند. بیشتر Pluginهای خارجی از طریق ClawHub منتشر و کشف می‌شوند. Npm همچنان برای نصب‌های مستقیم و برای مجموعه‌ای موقت از بسته‌های Plugin متعلق به OpenClaw تا زمان تکمیل آن مهاجرت پشتیبانی می‌شود.

شروع سریع

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

openclaw plugins list

# Search ClawHub pluginsopenclaw plugins search "calendar" # From ClawHubopenclaw plugins install clawhub:openclaw-codex-app-server # From npmopenclaw plugins install npm:@acme/openclaw-pluginopenclaw plugins install npm-pack:./openclaw-plugin-1.2.3.tgz # From gitopenclaw plugins install git:github.com/acme/openclaw-plugin@v1.0.0 # From a local directory or archiveopenclaw plugins install ./my-pluginopenclaw plugins install ./my-plugin.tgz

openclaw gateway restart

openclaw plugins inspect <plugin-id> --runtime --json # If the plugin registered a CLI root, run one command from that root.openclaw <plugin-command> --help

اگر کنترل بومی چت را ترجیح می‌دهید، commands.plugins: true را فعال کنید و از این موارد استفاده کنید:

/plugin install clawhub:<package>/plugin show <plugin-id>/plugin enable <plugin-id>

مسیر نصب از همان resolver استفاده می‌کند که CLI استفاده می‌کند: مسیر/آرشیو محلی، clawhub:<pkg> صریح، npm:<pkg> صریح، npm-pack:<path.tgz> صریح، git:<repo> صریح، یا مشخصه بسته بدون پیشوند از طریق npm.

اگر پیکربندی نامعتبر باشد، نصب معمولاً بسته شکست می‌خورد و شما را به openclaw doctor --fix هدایت می‌کند. تنها استثنای بازیابی، یک مسیر محدود نصب دوباره Plugin همراه‌سازی‌شده برای Pluginهایی است که به openclaw.install.allowInvalidConfigRecovery opt in می‌کنند. در هنگام راه‌اندازی Gateway، پیکربندی نامعتبر Plugin مانند هر پیکربندی نامعتبر دیگری بسته شکست می‌خورد. openclaw doctor --fix را اجرا کنید تا پیکربندی خراب Plugin با غیرفعال کردن آن ورودی Plugin و حذف payload نامعتبر پیکربندی آن قرنطینه شود؛ پشتیبان‌گیری عادی پیکربندی مقادیر قبلی را نگه می‌دارد. وقتی پیکربندی یک کانال به Pluginی اشاره می‌کند که دیگر قابل کشف نیست اما همان شناسه Plugin کهنه در پیکربندی Plugin یا رکوردهای نصب باقی مانده است، راه‌اندازی Gateway هشدارها را ثبت می‌کند و به‌جای مسدود کردن همه کانال‌های دیگر، آن کانال را رد می‌کند. برای حذف ورودی‌های کانال/Plugin کهنه، openclaw doctor --fix را اجرا کنید؛ کلیدهای کانال ناشناخته بدون شواهد Plugin کهنه همچنان در اعتبارسنجی شکست می‌خورند تا خطاهای تایپی قابل مشاهده بمانند. اگر plugins.enabled: false تنظیم شده باشد، ارجاع‌های کهنه Plugin بی‌اثر در نظر گرفته می‌شوند: راه‌اندازی Gateway کار کشف/بارگذاری Plugin را رد می‌کند و openclaw doctor به‌جای حذف خودکار پیکربندی غیرفعال Plugin، آن را حفظ می‌کند. اگر می‌خواهید شناسه‌های کهنه Plugin حذف شوند، پیش از اجرای پاک‌سازی doctor، Pluginها را دوباره فعال کنید.

نصب وابستگی‌های Plugin فقط در جریان‌های نصب/به‌روزرسانی صریح یا تعمیر doctor انجام می‌شود. راه‌اندازی Gateway، بارگذاری مجدد پیکربندی و بازرسی runtime مدیران بسته را اجرا نمی‌کنند یا درخت‌های وابستگی را تعمیر نمی‌کنند. Pluginهای محلی باید از قبل وابستگی‌های خود را نصب‌شده داشته باشند، در حالی که Pluginهای npm، git و ClawHub زیر ریشه‌های Plugin مدیریت‌شده OpenClaw نصب می‌شوند. وابستگی‌های npm ممکن است درون ریشه npm مدیریت‌شده OpenClaw hoist شوند؛ نصب/به‌روزرسانی آن ریشه مدیریت‌شده را پیش از اعتماد اسکن می‌کند و حذف نصب، بسته‌های مدیریت‌شده با npm را از طریق npm حذف می‌کند. Pluginهای خارجی و مسیرهای بارگذاری سفارشی همچنان باید از طریق openclaw plugins install نصب شوند. برای دیدن dependencyStatus ایستا برای هر Plugin قابل مشاهده، بدون import کردن کد runtime یا تعمیر وابستگی‌ها، از openclaw plugins list --json استفاده کنید. برای چرخه عمر زمان نصب، حل وابستگی Plugin را ببینید.

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

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

برای نصب‌های Docker، image رسمی با کاربر node (uid 1000) اجرا می‌شود، بنابراین دایرکتوری‌های پیکربندی و workspace مربوط به OpenClaw که از میزبان bind-mounted شده‌اند معمولاً باید مالکیت 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 پایدارشده با فایل‌های تعمیرشده هم‌خوان شود.

برای نصب‌های npm، selectorهای تغییرپذیر مانند latest یا dist-tag پیش از نصب resolve می‌شوند و سپس به نسخه دقیق تأییدشده در ریشه npm مدیریت‌شده OpenClaw pin می‌شوند. پس از پایان کار npm، OpenClaw تأیید می‌کند که ورودی نصب‌شده package-lock.json همچنان با نسخه و integrity حل‌شده مطابقت دارد. اگر npm فراداده بسته متفاوتی بنویسد، نصب شکست می‌خورد و بسته مدیریت‌شده به عقب برگردانده می‌شود، به‌جای اینکه artifact متفاوتی از Plugin پذیرفته شود. ریشه‌های npm مدیریت‌شده همچنین overrides سطح بسته npm مربوط به OpenClaw را به ارث می‌برند، بنابراین pinهای امنیتی که از میزبان بسته‌بندی‌شده محافظت می‌کنند برای وابستگی‌های Plugin خارجی hoistشده نیز اعمال می‌شوند.

checkoutهای منبع workspaceهای pnpm هستند. اگر OpenClaw را برای کار روی Pluginهای همراه‌سازی‌شده clone می‌کنید، pnpm install را اجرا کنید؛ سپس OpenClaw Pluginهای همراه‌سازی‌شده را از extensions/<id> بارگذاری می‌کند تا ویرایش‌ها و وابستگی‌های محلی بسته مستقیماً استفاده شوند. نصب‌های ساده ریشه npm برای OpenClaw بسته‌بندی‌شده هستند، نه توسعه checkout منبع.

انواع Plugin

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

هر دو زیر openclaw plugins list نمایش داده می‌شوند. برای جزئیات bundle، Plugin Bundleها را ببینید.

اگر در حال نوشتن یک Plugin بومی هستید، با ساخت Pluginها و نمای کلی Plugin SDK شروع کنید.

entrypointهای بسته

بسته‌های npm مربوط به Plugin بومی باید openclaw.extensions را در package.json اعلام کنند. هر ورودی باید داخل دایرکتوری بسته باقی بماند و به یک فایل runtime خواندنی resolve شود، یا به یک فایل منبع TypeScript با همتای JavaScript ساخته‌شده استنباطی مانند src/index.ts به dist/index.js resolve شود. نصب‌های بسته‌بندی‌شده باید آن خروجی runtime جاوااسکریپت را همراه خود داشته باشند. fallback منبع TypeScript برای checkoutهای منبع و مسیرهای توسعه محلی است، نه برای بسته‌های npm نصب‌شده در ریشه Plugin مدیریت‌شده OpenClaw.

دایرکتوری‌های ردیابی‌نشده‌ای که در ریشه extension سراسری انداخته می‌شوند، به‌عنوان checkoutهای منبع محلی در نظر گرفته می‌شوند و ممکن است ورودی‌های TypeScript را مستقیماً بارگذاری کنند. دایرکتوری‌هایی که همچنان توسط یک رکورد نصب نام‌گذاری شده‌اند، از جمله installPath یا sourcePath، مدیریت‌شده باقی می‌مانند و حتی وقتی اسکن سراسری آن‌ها را می‌بیند، الزام خروجی کامپایل‌شده را حفظ می‌کنند. اگر عمداً یک نصب مدیریت‌شده را به checkout محلی ردیابی‌نشده تبدیل می‌کنید، ابتدا رکورد نصب کهنه را با حذف نصب یا پاک‌سازی doctor حذف کنید.

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

وقتی فایل‌های runtime منتشرشده در همان مسیرهای ورودی‌های منبع قرار ندارند، از openclaw.runtimeExtensions استفاده کنید. وقتی وجود داشته باشد، runtimeExtensions باید دقیقاً برای هر ورودی extensions یک ورودی داشته باشد. فهرست‌های نامطابق نصب و کشف Plugin را با شکست روبه‌رو می‌کنند، نه اینکه بی‌صدا به مسیرهای منبع fallback کنند. اگر openclaw.setupEntry را نیز منتشر می‌کنید، از openclaw.runtimeSetupEntry برای همتای JavaScript ساخته‌شده آن استفاده کنید؛ وقتی اعلام شود، آن فایل الزامی است.

{  "name": "@acme/openclaw-plugin",  "openclaw": {    "extensions": ["./src/index.ts"],    "runtimeExtensions": ["./dist/index.js"]  }}

Pluginهای رسمی

بسته‌های npm متعلق به OpenClaw در طول مهاجرت

ClawHub مسیر توزیع اصلی برای بیشتر Pluginهاست. نسخه‌های بسته‌بندی‌شده فعلی OpenClaw از قبل بسیاری از Pluginهای رسمی را همراه خود دارند، بنابراین در تنظیمات عادی به نصب‌های npm جداگانه نیاز ندارند. تا زمانی که هر Plugin متعلق به OpenClaw به ClawHub مهاجرت کند، OpenClaw همچنان برخی بسته‌های Plugin با نام @openclaw/* را برای نصب‌های قدیمی‌تر/سفارشی و workflowهای مستقیم npm روی npm منتشر می‌کند.

اگر npm یک بسته Plugin با نام @openclaw/* را deprecated گزارش کند، آن نسخه بسته از یک ردیف قدیمی‌تر بسته خارجی است. تا زمانی که بسته npm جدیدتری منتشر شود، از Plugin همراه نسخه فعلی OpenClaw یا یک checkout محلی استفاده کنید.

هسته (همراه OpenClaw ارائه می‌شود)

دنبال Plugin‌های شخص ثالث هستید؟ ClawHub را ببینید.

پیکربندی

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

plugins.allow انحصاری است. وقتی خالی نباشد، فقط Plugin‌های فهرست‌شده می‌توانند بارگذاری شوند یا ابزارها را در معرض دسترس قرار دهند، حتی اگر tools.allow شامل "*" یا نام ابزار مشخصی باشد که مالک آن یک Plugin است. اگر فهرست مجاز ابزار به ابزارهای Plugin اشاره می‌کند، شناسه‌های Plugin مالک را به plugins.allow اضافه کنید یا plugins.allow را حذف کنید؛ openclaw doctor درباره‌ی این شکل هشدار می‌دهد.

plugins.bundledDiscovery برای پیکربندی‌های جدید به‌صورت پیش‌فرض "allowlist" است، بنابراین یک موجودی محدودکننده‌ی plugins.allow، Plugin‌های ارائه‌دهنده‌ی همراهِ حذف‌شده را نیز مسدود می‌کند، از جمله کشف ارائه‌دهنده‌ی جست‌وجوی وب در runtime. Doctor هنگام مهاجرت، پیکربندی‌های قدیمی‌ترِ فهرست مجاز محدودکننده را با "compat" مهر می‌کند تا ارتقاها رفتار قدیمی ارائه‌دهنده‌ی همراه را حفظ کنند تا زمانی که اپراتور حالت سخت‌گیرانه‌تر را انتخاب کند. plugins.allow خالی همچنان به‌عنوان تنظیم‌نشده/باز در نظر گرفته می‌شود.

تغییرات پیکربندی که از طریق /plugins enable یا /plugins disable انجام می‌شوند، بازبارگذاری درون‌فرایندی Pluginهای Gateway را آغاز می‌کنند. نوبت‌های جدید agent فهرست ابزارهای خود را از registry تازه‌سازی‌شده‌ی Plugin بازسازی می‌کنند. عملیات تغییردهنده‌ی منبع مانند نصب، به‌روزرسانی، و حذف نصب همچنان فرایند Gateway را ری‌استارت می‌کنند، چون ماژول‌های Plugin که از قبل import شده‌اند را نمی‌توان با اطمینان درجا جایگزین کرد.

openclaw plugins list یک snapshot محلی از registry/پیکربندی Plugin است. یک Plugin با وضعیت enabled در آن‌جا یعنی registry پایدارشده و پیکربندی فعلی اجازه می‌دهند Plugin مشارکت کند. این ثابت نمی‌کند که یک Gateway راه‌دورِ در حال اجرا، به همان کد Plugin بازبارگذاری یا ری‌استارت شده است. در راه‌اندازی‌های VPS/container با فرایندهای wrapper، ری‌استارت‌ها یا نوشتن‌هایی که بازبارگذاری را فعال می‌کنند به فرایند واقعی openclaw gateway run بفرستید، یا وقتی بازبارگذاری خطا گزارش می‌کند از openclaw gateway restart روی Gateway در حال اجرا استفاده کنید.

کشف و تقدم

OpenClaw به این ترتیب به‌دنبال Plugin‌ها می‌گردد (اولین تطابق برنده است):

نصب‌های بسته‌بندی‌شده و imageهای Docker معمولاً Plugin‌های همراه را از درخت کامپایل‌شده‌ی dist/extensions resolve می‌کنند. اگر دایرکتوری منبع یک Plugin همراه روی مسیر منبع بسته‌بندی‌شده‌ی متناظر bind-mounted شود، برای مثال /app/extensions/synology-chat، OpenClaw آن دایرکتوری منبع mount‌شده را به‌عنوان overlay منبع همراه در نظر می‌گیرد و آن را پیش از bundle بسته‌بندی‌شده‌ی /app/dist/extensions/synology-chat کشف می‌کند. این کار loopهای container مربوط به maintainer را بدون برگرداندن همه‌ی Plugin‌های همراه به منبع TypeScript فعال نگه می‌دارد. برای اجبار به استفاده از bundleهای dist بسته‌بندی‌شده حتی وقتی mountهای overlay منبع وجود دارند، OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1 را تنظیم کنید.

قواعد فعال‌سازی

• plugins.enabled: false همه‌ی Plugin‌ها را غیرفعال می‌کند و کار کشف/بارگذاری Plugin را رد می‌کند
• plugins.deny همیشه بر allow اولویت دارد
• plugins.entries.\<id\>.enabled: false آن Plugin را غیرفعال می‌کند
• Plugin‌های با منشأ workspace به‌صورت پیش‌فرض غیرفعال‌اند (باید صریحاً فعال شوند)
• Plugin‌های همراه از مجموعه‌ی داخلیِ پیش‌فرض فعال پیروی می‌کنند مگر این‌که override شوند
• اسلات‌های انحصاری می‌توانند Plugin انتخاب‌شده برای آن اسلات را force-enable کنند
• برخی Plugin‌های همراه opt-in وقتی پیکربندی یک سطح متعلق به Plugin را نام می‌برد، مانند ارجاع مدل ارائه‌دهنده، پیکربندی channel، یا runtime harness، به‌صورت خودکار فعال می‌شوند
• پیکربندی کهنه‌ی Plugin تا زمانی که plugins.enabled: false فعال است حفظ می‌شود؛ اگر می‌خواهید شناسه‌های کهنه حذف شوند، پیش از اجرای پاک‌سازی doctor، Plugin‌ها را دوباره فعال کنید
• مسیرهای Codex خانواده‌ی OpenAI مرزهای Plugin جداگانه را حفظ می‌کنند: openai-codex/* متعلق به Plugin OpenAI است، در حالی‌که Plugin app-server همراه Codex با ارجاع‌های canonical agent با نام openai/*، agentRuntime.id: "codex" صریح provider/model، یا ارجاع‌های قدیمی مدل codex/* انتخاب می‌شود

عیب‌یابی hookهای runtime

اگر یک Plugin در plugins list دیده می‌شود اما اثرات جانبی یا hookهای register(api) در ترافیک چت زنده اجرا نمی‌شوند، ابتدا این موارد را بررسی کنید:

• openclaw gateway status --deep --require-rpc را اجرا کنید و تأیید کنید URL فعال Gateway، profile، مسیر پیکربندی، و فرایند همان‌هایی هستند که ویرایش می‌کنید.
• پس از تغییرات نصب/پیکربندی/کد Plugin، Gateway زنده را ری‌استارت کنید. در containerهای wrapper، PID 1 ممکن است فقط یک supervisor باشد؛ فرایند فرزند openclaw gateway run را ری‌استارت یا signal کنید.
• از openclaw plugins inspect <id> --runtime --json برای تأیید ثبت hookها و diagnostics استفاده کنید. hookهای گفت‌وگوی غیرهمراه مانند before_model_resolve، before_agent_reply، before_agent_run، llm_input، llm_output، before_agent_finalize، و agent_end به plugins.entries.<id>.hooks.allowConversationAccess=true نیاز دارند.
• برای تغییر مدل، before_model_resolve را ترجیح دهید. این hook پیش از resolve مدل برای نوبت‌های agent اجرا می‌شود؛ llm_output فقط پس از آن اجرا می‌شود که یک تلاش مدل خروجی assistant تولید کند.
• برای اثبات مدل مؤثر جلسه، از openclaw sessions یا سطح‌های session/status در Gateway استفاده کنید و هنگام debug کردن payloadهای provider، Gateway را با --raw-stream --raw-stream-path <path> شروع کنید.

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

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

openclaw config set logging.level traceopenclaw logs --follow

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

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

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

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

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

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

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

مالکیت تکراری channel یا ابزار

نشانه‌ها:

• channel already registered: <channel-id> (<plugin-id>)
• channel setup already registered: <channel-id> (<plugin-id>)
• plugin tool name conflict (<plugin-id>): <tool-name>

این‌ها یعنی بیش از یک Plugin فعال تلاش می‌کند مالک همان channel، جریان راه‌اندازی، یا نام ابزار باشد. رایج‌ترین علت، نصب یک Plugin خارجی channel در کنار یک Plugin همراه است که اکنون همان شناسه‌ی channel را فراهم می‌کند.

مراحل debug:

• برای دیدن هر Plugin فعال و منشأ آن، openclaw plugins list --enabled --verbose را اجرا کنید.
• برای هر Plugin مشکوک، openclaw plugins inspect <id> --runtime --json را اجرا کنید و channels، channelConfigs، tools، و diagnostics را مقایسه کنید.
• پس از نصب یا حذف packageهای Plugin، openclaw plugins registry --refresh را اجرا کنید تا metadata پایدارشده وضعیت نصب فعلی را بازتاب دهد.
• پس از تغییرات نصب، registry، یا پیکربندی، Gateway را ری‌استارت کنید.

گزینه‌های رفع:

• اگر یک Plugin عمداً دیگری را برای همان شناسه‌ی channel جایگزین می‌کند، Plugin ترجیحی باید channelConfigs.<channel-id>.preferOver را با شناسه‌ی Plugin دارای اولویت پایین‌تر اعلام کند. /plugins/manifest#replacing-another-channel-plugin را ببینید.
• اگر تکرار تصادفی است، یک طرف را با plugins.entries.<plugin-id>.enabled: false غیرفعال کنید یا نصب Plugin کهنه را حذف کنید.
• اگر هر دو Plugin را صریحاً فعال کرده‌اید، OpenClaw آن درخواست را حفظ می‌کند و تعارض را گزارش می‌دهد. یک مالک برای channel انتخاب کنید یا ابزارهای متعلق به Plugin را تغییر نام دهید تا سطح runtime ابهام نداشته باشد.

اسلات‌های Plugin (دسته‌های انحصاری)

برخی دسته‌ها انحصاری‌اند (در هر زمان فقط یکی فعال است):

{  plugins: {    slots: {      memory: "memory-core", // or "none" to disable      contextEngine: "legacy", // or a plugin id    },  },}

مرجع CLI

openclaw plugins list                       # compact inventoryopenclaw plugins list --enabled            # only enabled pluginsopenclaw plugins list --verbose            # per-plugin detail linesopenclaw plugins list --json               # machine-readable inventoryopenclaw plugins search <query>            # search ClawHub plugin catalogopenclaw plugins inspect <id>              # static detailopenclaw plugins inspect <id> --runtime    # registered hooks/tools/CLI/gateway methodsopenclaw plugins inspect <id> --json       # machine-readableopenclaw plugins inspect --all             # fleet-wide tableopenclaw plugins info <id>                 # inspect aliasopenclaw plugins doctor                    # diagnosticsopenclaw plugins registry                  # inspect persisted registry stateopenclaw plugins registry --refresh        # rebuild persisted registryopenclaw doctor --fix                      # repair plugin registry state openclaw plugins install <package>         # install from npm by defaultopenclaw plugins install clawhub:<pkg>     # install from ClawHub onlyopenclaw plugins install npm:<pkg>         # install from npm onlyopenclaw plugins install git:<repo>        # install from gitopenclaw plugins install git:<repo>@<ref>  # install from git refopenclaw plugins install <spec> --force    # overwrite existing installopenclaw plugins install <path>            # install from local pathopenclaw plugins install -l <path>         # link (no copy) for devopenclaw plugins install <plugin> --marketplace <source>openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>openclaw plugins install <spec> --pin      # record exact resolved npm specopenclaw plugins install <spec> --dangerously-force-unsafe-installopenclaw plugins update <id-or-npm-spec> # update one pluginopenclaw plugins update <id-or-npm-spec> --dangerously-force-unsafe-installopenclaw plugins update --all            # update allopenclaw plugins uninstall <id>          # remove config and plugin index recordsopenclaw plugins uninstall <id> --keep-filesopenclaw plugins marketplace list <source>openclaw plugins marketplace list <source> --json # Verify runtime registrations after install.openclaw plugins inspect <id> --runtime --json # Run plugin-owned CLI commands directly from the OpenClaw root CLI.openclaw <plugin-command> --help openclaw plugins enable <id>openclaw plugins disable <id>

Pluginهای همراه، با OpenClaw عرضه می‌شوند. بسیاری از آن‌ها به‌طور پیش‌فرض فعال هستند (برای نمونه ارائه‌دهندگان مدل همراه، ارائه‌دهندگان گفتار همراه، و Plugin مرورگر همراه). سایر Pluginهای همراه همچنان به openclaw plugins enable <id> نیاز دارند.

--force یک Plugin نصب‌شده یا بسته hook موجود را درجا بازنویسی می‌کند. برای ارتقاهای معمول Pluginهای npm ردیابی‌شده از openclaw plugins update <id-or-npm-spec> استفاده کنید. این گزینه با --link پشتیبانی نمی‌شود، چون --link به‌جای کپی‌کردن روی یک هدف نصب مدیریت‌شده، مسیر منبع را دوباره استفاده می‌کند.

وقتی plugins.allow از قبل تنظیم شده باشد، openclaw plugins install شناسه Plugin نصب‌شده را پیش از فعال‌سازی به آن فهرست مجاز اضافه می‌کند. اگر همان شناسه Plugin در plugins.deny وجود داشته باشد، نصب آن ورودی deny کهنه را حذف می‌کند تا نصب صریح بلافاصله پس از راه‌اندازی دوباره قابل بارگذاری باشد.

OpenClaw یک رجیستری محلی ماندگار Plugin را به‌عنوان مدل خواندن سرد برای موجودی Plugin، مالکیت مشارکت‌ها، و برنامه‌ریزی راه‌اندازی نگه می‌دارد. جریان‌های نصب، به‌روزرسانی، حذف نصب، فعال‌سازی، و غیرفعال‌سازی پس از تغییر وضعیت Plugin آن رجیستری را تازه‌سازی می‌کنند. همان فایل plugins/installs.json فراداده نصب پایدار را در installRecords سطح بالا و فراداده manifest قابل بازسازی را در plugins نگه می‌دارد. اگر رجیستری موجود نباشد، کهنه باشد، یا نامعتبر باشد، openclaw plugins registry --refresh نمای manifest آن را از رکوردهای نصب، سیاست config، و فراداده manifest/package بدون بارگذاری ماژول‌های runtime مربوط به Plugin بازسازی می‌کند.

در حالت Nix (OPENCLAW_NIX_MODE=1)، تغییر‌دهنده‌های چرخه‌عمر Plugin غیرفعال هستند. به‌جای آن، انتخاب بسته Plugin و config را از طریق منبع Nix همان نصب مدیریت کنید؛ برای nix-openclaw، از شروع سریع عامل‌محور آغاز کنید. openclaw plugins update <id-or-npm-spec> برای نصب‌های ردیابی‌شده اعمال می‌شود. دادن یک spec بسته npm همراه با dist-tag یا نسخه دقیق، نام بسته را دوباره به رکورد Plugin ردیابی‌شده resolve می‌کند و spec جدید را برای به‌روزرسانی‌های آینده ثبت می‌کند. دادن نام بسته بدون نسخه، یک نصب دقیق pin‌شده را به خط انتشار پیش‌فرض رجیستری برمی‌گرداند. اگر Plugin نصب‌شده npm از قبل با نسخه resolve‌شده و هویت artifact ثبت‌شده مطابق باشد، OpenClaw به‌روزرسانی را بدون دانلود، نصب دوباره، یا بازنویسی config رد می‌کند. وقتی openclaw update روی کانال beta اجرا می‌شود، رکوردهای Plugin مربوط به خط پیش‌فرض npm و ClawHub ابتدا @beta را امتحان می‌کنند و وقتی انتشار beta برای Plugin وجود نداشته باشد به default/latest برمی‌گردند. نسخه‌های دقیق و tagهای صریح همچنان pin‌شده می‌مانند.

--pin فقط مخصوص npm است. این گزینه با --marketplace پشتیبانی نمی‌شود، چون نصب‌های marketplace به‌جای spec مربوط به npm، فراداده منبع marketplace را پایدار نگه می‌دارند.

--dangerously-force-unsafe-install یک override اضطراری برای مثبت‌های کاذب اسکنر داخلی کد خطرناک است. این گزینه اجازه می‌دهد نصب‌ها و به‌روزرسانی‌های Plugin از یافته‌های داخلی critical عبور کنند، اما همچنان blockهای سیاست before_install مربوط به Plugin یا مسدودسازی ناشی از شکست اسکن را دور نمی‌زند. اسکن‌های نصب، برای جلوگیری از مسدود کردن mockهای تست بسته‌بندی‌شده، فایل‌ها و دایرکتوری‌های رایج تست مانند tests/، __tests__/، *.test.*، و *.spec.* را نادیده می‌گیرند؛ entrypointهای runtime اعلام‌شده برای Plugin همچنان اسکن می‌شوند حتی اگر یکی از آن نام‌ها را استفاده کنند.

این flag در CLI فقط برای جریان‌های نصب/به‌روزرسانی Plugin اعمال می‌شود. نصب‌های وابستگی Skill که با پشتوانه Gateway انجام می‌شوند به‌جای آن از override متناظر درخواست dangerouslyForceUnsafeInstall استفاده می‌کنند، درحالی‌که openclaw skills install همچنان جریان جداگانه دانلود/نصب Skill از ClawHub باقی می‌ماند.

اگر Pluginی که در ClawHub منتشر کرده‌اید به‌دلیل یک اسکن پنهان یا مسدود شده است، داشبورد ClawHub را باز کنید یا clawhub package rescan <name> را اجرا کنید تا از ClawHub بخواهید دوباره آن را بررسی کند. --dangerously-force-unsafe-install فقط روی نصب‌ها در دستگاه خودتان اثر دارد؛ از ClawHub نمی‌خواهد Plugin را دوباره اسکن کند یا یک انتشار مسدودشده را عمومی کند.

بسته‌های سازگار در همان جریان فهرست/بازرسی/فعال‌سازی/غیرفعال‌سازی Plugin مشارکت می‌کنند. پشتیبانی runtime فعلی شامل Skills بسته، command-skillهای Claude، پیش‌فرض‌های Claude settings.json، پیش‌فرض‌های Claude .lsp.json و lspServers اعلام‌شده در manifest، command-skillهای Cursor، و دایرکتوری‌های hook سازگار Codex است.

openclaw plugins inspect <id> همچنین قابلیت‌های شناسایی‌شده بسته به‌علاوه ورودی‌های پشتیبانی‌شده یا پشتیبانی‌نشده سرورهای MCP و LSP برای Pluginهای پشتیبانی‌شده با بسته را گزارش می‌کند.

منابع marketplace می‌توانند یک نام marketplace شناخته‌شده Claude از ~/.claude/plugins/known_marketplaces.json، یک ریشه marketplace محلی یا مسیر marketplace.json، یک shorthand گیت‌هاب مانند owner/repo، یک URL مخزن گیت‌هاب، یا یک URL git باشند. برای marketplaceهای remote، ورودی‌های Plugin باید داخل مخزن marketplace کلون‌شده باقی بمانند و فقط از منابع مسیر نسبی استفاده کنند.

برای جزئیات کامل، مرجع CLI مربوط به openclaw plugins را ببینید.

نمای کلی API مربوط به Plugin

Pluginهای native یک شیء entry صادر می‌کنند که register(api) را در دسترس می‌گذارد. Pluginهای قدیمی‌تر ممکن است همچنان از activate(api) به‌عنوان alias قدیمی استفاده کنند، اما Pluginهای جدید باید از register استفاده کنند.

export default definePluginEntry({  id: "my-plugin",  name: "My Plugin",  register(api) {    api.registerProvider({      /* ... */    });    api.registerTool({      /* ... */    });    api.registerChannel({      /* ... */    });  },});

OpenClaw در هنگام فعال‌سازی Plugin، شیء entry را بارگذاری می‌کند و register(api) را فراخوانی می‌کند. loader همچنان برای Pluginهای قدیمی‌تر به activate(api) fallback می‌کند، اما Pluginهای همراه و Pluginهای خارجی جدید باید register را به‌عنوان قرارداد عمومی در نظر بگیرند.

api.registrationMode به یک Plugin می‌گوید چرا entry آن در حال بارگذاری است:

entryهای Plugin که socket، database، worker پس‌زمینه، یا clientهای بلندعمر باز می‌کنند باید این side effectها را با api.registrationMode === "full" محافظت کنند. بارگذاری‌های discovery جدا از بارگذاری‌های activation cache می‌شوند و جایگزین رجیستری Gateway در حال اجرا نمی‌شوند. Discovery غیرفعال‌ساز است، اما import-free نیست: OpenClaw ممکن است برای ساخت snapshot، entry قابل‌اعتماد Plugin یا ماژول Plugin کانال را ارزیابی کند. سطح‌های بالایی ماژول را سبک و بدون side effect نگه دارید، و clientهای شبکه، subprocessها، listenerها، خواندن credentialها، و راه‌اندازی سرویس را پشت مسیرهای full-runtime منتقل کنید.

روش‌های رایج registration:

رفتار guard مربوط به hookهای چرخه‌عمر typed:

• before_tool_call: { block: true } نهایی است؛ handlerهای با اولویت پایین‌تر رد می‌شوند.
• before_tool_call: { block: false } یک no-op است و block قبلی را پاک نمی‌کند.
• before_install: { block: true } نهایی است؛ handlerهای با اولویت پایین‌تر رد می‌شوند.
• before_install: { block: false } یک no-op است و block قبلی را پاک نمی‌کند.
• message_sending: { cancel: true } نهایی است؛ handlerهای با اولویت پایین‌تر رد می‌شوند.
• message_sending: { cancel: false } یک no-op است و cancel قبلی را پاک نمی‌کند.

سرور برنامهٔ بومی Codex رویدادهای ابزار بومیِ Codex را دوباره از طریق پل به این سطح hook برمی‌گرداند. Pluginها می‌توانند ابزارهای بومی Codex را از طریق before_tool_call مسدود کنند، نتایج را از طریق after_tool_call مشاهده کنند و در تأییدهای PermissionRequest در Codex مشارکت داشته باشند. این پل هنوز آرگومان‌های ابزارهای بومی Codex را بازنویسی نمی‌کند. مرز دقیق پشتیبانی زمان اجرای Codex در قرارداد پشتیبانی نسخهٔ ۱ harness Codex قرار دارد.

برای رفتار کامل hook با نوع‌دهی، نمای کلی SDK را ببینید.

مرتبط

• ساخت Pluginها - Plugin خودتان را بسازید
• بسته‌های Plugin - سازگاری بستهٔ Codex/Claude/Cursor
• مانیفست Plugin - طرح‌وارهٔ مانیفست
• ثبت ابزارها - افزودن ابزارهای عامل در یک Plugin
• جزئیات داخلی Plugin - مدل قابلیت و خط لولهٔ بارگذاری
• ClawHub - کشف Pluginهای شخص ثالث