Plugin‌ها

مدیریت Pluginهای Gateway، بسته‌های hook و بسته‌های سازگار.

# دستورها

openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
openclaw plugins search <query>
openclaw plugins search <query> --limit 20
openclaw plugins search <query> --json
openclaw plugins install <path-or-spec>
openclaw plugins inspect <id>
openclaw plugins inspect <id> --runtime
openclaw plugins inspect <id> --json
openclaw plugins inspect --all
openclaw plugins info <id>
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins registry
openclaw plugins registry --refresh
openclaw plugins uninstall <id>
openclaw plugins doctor
openclaw plugins update <id-or-npm-spec>
openclaw plugins update --all
openclaw plugins marketplace list <marketplace>
openclaw plugins marketplace list <marketplace> --json

برای بررسی نصب، inspect، حذف نصب، یا نوسازی registry که کند انجام می‌شود، دستور را با OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 اجرا کنید. trace زمان‌بندی فازها را در stderr می‌نویسد و خروجی JSON را قابل parse نگه می‌دارد. اشکال‌زدایی را ببینید.

# نصب

openclaw plugins search "calendar"                   # search ClawHub plugins
openclaw plugins install <package>                      # npm by default
openclaw plugins install clawhub:<package>              # ClawHub only
openclaw plugins install npm:<package>                  # npm only
openclaw plugins install npm-pack:<path.tgz>            # local npm pack through npm install semantics
openclaw plugins install git:github.com/<owner>/<repo>  # git repo
openclaw plugins install git:github.com/<owner>/<repo>@<ref>
openclaw plugins install <package> --force              # overwrite existing install
openclaw plugins install <package> --pin                # pin version
openclaw plugins install <package> --dangerously-force-unsafe-install
openclaw plugins install <path>                         # local path
openclaw plugins install <plugin>@<marketplace>         # marketplace
openclaw plugins install <plugin> --marketplace <name>  # marketplace (explicit)
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>

plugins search از ClawHub برای یافتن بسته‌های Plugin قابل نصب query می‌گیرد و نام بسته‌های آماده نصب را چاپ می‌کند. این دستور بسته‌های code-plugin و bundle-plugin را جست‌وجو می‌کند، نه Skills را. برای Skills در ClawHub از openclaw skills search استفاده کنید.

نصب‌های ClawHub از locator صریح clawhub:<package> استفاده می‌کنند:

openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:[email protected]

specهای Plugin بدون پیشوند و سازگار با npm در دوره گذار راه‌اندازی به‌صورت پیش‌فرض از npm نصب می‌شوند:

openclaw plugins install openclaw-codex-app-server

برای صریح کردن resolution فقط npm از npm: استفاده کنید:

openclaw plugins install npm:openclaw-codex-app-server
openclaw plugins install npm:@scope/[email protected]

OpenClaw پیش از نصب، سازگاری API اعلام‌شدهٔ Plugin / حداقل Gateway را بررسی می‌کند. وقتی نسخهٔ انتخاب‌شدهٔ ClawHub یک آرتیفکت ClawPack منتشر کند، OpenClaw بستهٔ versioned npm-pack با پسوند .tgz را دانلود می‌کند، سرآیند digest مربوط به ClawHub و digest آرتیفکت را بررسی می‌کند، سپس آن را از مسیر معمول آرشیو نصب می‌کند. نسخه‌های قدیمی‌تر ClawHub که metadata مربوط به ClawPack ندارند همچنان از مسیر legacy راستی‌آزمایی آرشیو package نصب می‌شوند. نصب‌های ثبت‌شده metadata منبع ClawHub، نوع آرتیفکت، npm integrity، npm shasum، نام tarball، و داده‌های digest مربوط به ClawPack را برای به‌روزرسانی‌های بعدی نگه می‌دارند. نصب‌های ClawHub بدون نسخه یک spec ثبت‌شدهٔ بدون نسخه نگه می‌دارند تا openclaw plugins update بتواند نسخه‌های جدیدتر ClawHub را دنبال کند؛ selectorهای نسخه یا tag صریح مانند clawhub:[email protected] و clawhub:pkg@beta همچنان به همان selector پین می‌مانند.

# میان‌بر Marketplace

وقتی نام marketplace در cache رجیستری محلی Claude در ~/.claude/plugins/known_marketplaces.json وجود دارد، از میان‌بر plugin@marketplace استفاده کنید:

openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>

وقتی می‌خواهید منبع marketplace را به‌صورت صریح بدهید، از --marketplace استفاده کنید:

openclaw plugins install <plugin-name> --marketplace <marketplace-name>
openclaw plugins install <plugin-name> --marketplace <owner/repo>
openclaw plugins install <plugin-name> --marketplace https://github.com/<owner>/<repo>
openclaw plugins install <plugin-name> --marketplace ./my-marketplace

برای مسیرها و آرشیوهای محلی، OpenClaw این موارد را به‌صورت خودکار تشخیص می‌دهد:

• Pluginهای native مربوط به OpenClaw (openclaw.plugin.json)
• bundleهای سازگار با Codex (.codex-plugin/plugin.json)
• bundleهای سازگار با Claude (.claude-plugin/plugin.json یا چیدمان component پیش‌فرض Claude)
• bundleهای سازگار با Cursor (.cursor-plugin/plugin.json)

# فهرست

openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
openclaw plugins search <query>
openclaw plugins search <query> --limit 20
openclaw plugins search <query> --json

--enabledboolean

فقط Pluginهای فعال را نشان بده.

--verboseboolean

از نمای table به خط‌های جزئیات جداگانه برای هر Plugin همراه با metadata منبع/خاستگاه/نسخه/فعال‌سازی تغییر می‌کند.

--jsonboolean

inventory قابل‌خواندن برای ماشین به‌همراه diagnostics رجیستری و وضعیت نصب dependencyهای package.

plugins search یک lookup catalog remote در ClawHub است. این فرمان state محلی را بررسی نمی‌کند، config را mutate نمی‌کند، package نصب نمی‌کند، و code runtime مربوط به Plugin را load نمی‌کند. نتیجه‌های search شامل نام package در ClawHub، family، channel، version، summary، و یک hint نصب مانند openclaw plugins install clawhub:<package> هستند.

برای کار روی Pluginهای bundled داخل یک image بسته‌بندی‌شدهٔ Docker، directory منبع Plugin را روی مسیر منبع بسته‌بندی‌شدهٔ متناظر bind-mount کنید، مانند /app/extensions/synology-chat. OpenClaw آن overlay منبع mount‌شده را پیش از /app/dist/extensions/synology-chat کشف می‌کند؛ یک directory منبع که صرفا copy شده باشد غیرفعال می‌ماند تا نصب‌های معمول بسته‌بندی‌شده همچنان از dist کامپایل‌شده استفاده کنند.

برای debug کردن hookهای runtime:

• openclaw plugins inspect <id> --runtime --json hookهای ثبت‌شده و diagnostics از یک گذر inspection با module-loaded را نشان می‌دهد. inspection مربوط به runtime هرگز dependency نصب نمی‌کند؛ برای پاک‌سازی state مربوط به dependencyهای legacy یا بازیابی Pluginهای downloadable مفقودی که config به آن‌ها reference داده است، از openclaw doctor --fix استفاده کنید.
• openclaw gateway status --deep --require-rpc Gateway قابل‌دسترسی، hintهای service/process، مسیر config، و سلامت RPC را تایید می‌کند.
• hookهای conversation غیرباندل‌شده (llm_input, llm_output, before_model_resolve, before_agent_reply, before_agent_run, before_agent_finalize, agent_end) به plugins.entries.<id>.hooks.allowConversationAccess=true نیاز دارند.

برای جلوگیری از copy کردن یک directory محلی، از --link استفاده کنید (به plugins.load.paths اضافه می‌کند):

openclaw plugins install -l ./my-plugin

# index مربوط به Plugin

metadata نصب Plugin یک state مدیریت‌شده توسط ماشین است، نه config کاربر. نصب‌ها و به‌روزرسانی‌ها آن را در plugins/installs.json زیر directory فعال state مربوط به OpenClaw می‌نویسند. map سطح بالای installRecords منبع durable برای metadata نصب است، از جمله recordهای مربوط به manifestهای خراب یا مفقود Plugin. آرایهٔ plugins همان cache رجیستری cold مشتق‌شده از manifest است. این فایل یک هشدار do-not-edit دارد و توسط openclaw plugins update، uninstall، diagnostics، و رجیستری cold مربوط به Plugin استفاده می‌شود.

وقتی OpenClaw recordهای legacy ارسال‌شدهٔ plugins.installs را در config ببیند، خواندن‌های runtime با آن‌ها به‌عنوان ورودی compatibility برخورد می‌کنند بدون اینکه openclaw.json را بازنویسی کنند. نوشتن‌های صریح Plugin و openclaw doctor --fix آن recordها را به index مربوط به Plugin منتقل می‌کنند و وقتی نوشتن config مجاز باشد، key مربوط به config را حذف می‌کنند؛ اگر هرکدام از این writeها fail شود، recordهای config نگه داشته می‌شوند تا metadata نصب از دست نرود.

# حذف نصب

openclaw plugins uninstall <id>
openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files

uninstall recordهای Plugin را از plugins.entries، index persisted مربوط به Plugin، entryهای allow/deny list مربوط به Plugin، و در صورت کاربرد، entryهای linked مربوط به plugins.load.paths حذف می‌کند. مگر اینکه --keep-files تنظیم شده باشد، uninstall همچنین directory نصب مدیریت‌شدهٔ track‌شده را وقتی داخل ریشهٔ extensions مربوط به Pluginهای OpenClaw باشد حذف می‌کند. برای Pluginهای active memory، slot حافظه به memory-core reset می‌شود.

# به‌روزرسانی

openclaw plugins update <id-or-npm-spec>
openclaw plugins update --all
openclaw plugins update <id-or-npm-spec> --dry-run
openclaw plugins update @openclaw/voice-call
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install

به‌روزرسانی‌ها روی نصب‌های track‌شدهٔ Plugin در index مدیریت‌شدهٔ Plugin و نصب‌های hook-pack track‌شده در hooks.internal.installs اعمال می‌شوند.

# inspect

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

Inspect بدون import کردن runtime مربوط به Plugin به‌صورت پیش‌فرض، identity، وضعیت load، source، قابلیت‌های manifest، flagهای policy، diagnostics، metadata نصب، قابلیت‌های bundle، و هرگونه پشتیبانی تشخیص‌داده‌شده از serverهای MCP یا LSP را نشان می‌دهد. برای load کردن module مربوط به Plugin و شامل کردن hookها، toolها، commandها، serviceها، methodهای gateway، و routeهای HTTP ثبت‌شده، --runtime را اضافه کنید. Runtime inspection dependencyهای مفقود Plugin را مستقیما گزارش می‌کند؛ نصب‌ها و repairها در openclaw plugins install، openclaw plugins update، و openclaw doctor --fix باقی می‌مانند.

commandهای CLI متعلق به Plugin به‌عنوان command groupهای ریشهٔ openclaw نصب می‌شوند. پس از اینکه inspect --runtime یک command را زیر cliCommands نشان داد، آن را به‌صورت openclaw <command> ... اجرا کنید؛ برای مثال Pluginای که demo-git را register می‌کند با openclaw demo-git ping قابل verify است.

هر Plugin بر اساس آنچه واقعا در runtime ثبت می‌کند طبقه‌بندی می‌شود:

• plain-capability — یک نوع قابلیت (مثلاً یک Plugin فقط-ارائه‌دهنده)
• hybrid-capability — چند نوع قابلیت (مثلاً متن + گفتار + تصویر)
• hook-only — فقط هوک‌ها، بدون قابلیت‌ها یا سطح‌ها
• non-capability — ابزارها/فرمان‌ها/سرویس‌ها، اما بدون قابلیت‌ها

برای اطلاعات بیشتر درباره مدل قابلیت، شکل‌های Plugin را ببینید.

# Doctor

openclaw plugins doctor

doctor خطاهای بارگذاری Plugin، عیب‌یابی‌های مانیفست/کشف، و اعلان‌های سازگاری را گزارش می‌کند. وقتی همه‌چیز پاک باشد، No plugin issues detected. را چاپ می‌کند.

اگر یک Plugin پیکربندی‌شده روی دیسک وجود داشته باشد اما توسط بررسی‌های ایمنی مسیرِ بارگذار مسدود شده باشد، اعتبارسنجی پیکربندی ورودی Plugin را نگه می‌دارد و آن را به‌صورت present but blocked گزارش می‌کند. به‌جای حذف پیکربندی plugins.entries.<id> یا plugins.allow، عیب‌یابی Plugin مسدودشده قبلی، مانند مالکیت مسیر یا مجوزهای قابل نوشتن برای همه را برطرف کنید.

برای خرابی‌های شکل ماژول، مانند نبود خروجی‌های register/activate، دوباره با OPENCLAW_PLUGIN_LOAD_DEBUG=1 اجرا کنید تا خلاصه‌ای فشرده از شکل خروجی‌ها در خروجی عیب‌یابی گنجانده شود.

# رجیستری

openclaw plugins registry
openclaw plugins registry --refresh
openclaw plugins registry --json

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

از plugins registry برای بررسی اینکه رجیستری ماندگار وجود دارد، به‌روز است، یا کهنه شده استفاده کنید. از --refresh برای بازسازی آن از نمایه ماندگار Plugin، سیاست پیکربندی، و فراداده مانیفست/بسته استفاده کنید. این یک مسیر تعمیر است، نه مسیر فعال‌سازی زمان اجرا.

openclaw doctor --fix همچنین انحراف npm مدیریت‌شده نزدیک به رجیستری را تعمیر می‌کند: اگر یک بسته یتیم یا بازیابی‌شده @openclaw/* زیر ریشه npm مدیریت‌شده Plugin یک Plugin باندل‌شده را سایه بیندازد، doctor آن بسته کهنه را حذف می‌کند و رجیستری را بازسازی می‌کند تا راه‌اندازی در برابر مانیفست باندل‌شده اعتبارسنجی شود.

# بازارچه

openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json

فهرست بازارچه یک مسیر محلی بازارچه، مسیر marketplace.json، کوتاه‌نویسی GitHub مانند owner/repo، URL مخزن GitHub، یا URL گیت را می‌پذیرد. --json برچسب منبع حل‌شده را همراه با مانیفست بازارچه تجزیه‌شده و ورودی‌های Plugin چاپ می‌کند.

# مرتبط

• ساخت Pluginها
• مرجع CLI
• Pluginهای جامعه