بسته‌های Plugin

OpenClaw می‌تواند Pluginها را از سه زیست‌بوم خارجی نصب کند: Codex، Claude، و Cursor. به این‌ها باندل گفته می‌شود؛ بسته‌های محتوا و فراداده‌ای که OpenClaw آن‌ها را به قابلیت‌های بومی مانند Skills، هوک‌ها و ابزارهای MCP نگاشت می‌کند.

چرا باندل‌ها وجود دارند

بسیاری از Pluginهای کاربردی با قالب Codex، Claude یا Cursor منتشر می‌شوند. OpenClaw به‌جای ملزم‌کردن نویسندگان به بازنویسی آن‌ها به‌صورت Pluginهای بومی OpenClaw، این قالب‌ها را تشخیص می‌دهد و محتوای پشتیبانی‌شدهٔ آن‌ها را به مجموعه قابلیت‌های بومی نگاشت می‌کند. می‌توانید یک بستهٔ فرمان Claude یا باندل Skill مربوط به Codex را نصب کرده و بلافاصله از آن استفاده کنید.

نصب باندل

# پوشهٔ محلیopenclaw plugins install ./my-bundle # بایگانیopenclaw plugins install ./my-bundle.tgz # بازار Claudeopenclaw plugins marketplace list <source>openclaw plugins install <plugin> --marketplace <source>

openclaw plugins listopenclaw plugins inspect <id>

openclaw gateway restart

مواردی که OpenClaw از باندل‌ها نگاشت می‌کند

در حال حاضر همهٔ قابلیت‌های باندل در OpenClaw اجرا نمی‌شوند. در ادامه مواردی آمده است که کار می‌کنند و مواردی که تشخیص داده می‌شوند اما هنوز متصل نشده‌اند.

مواردی که اکنون پشتیبانی می‌شوند

محتوای Skill

• ریشه‌های Skill باندل مانند ریشه‌های Skill عادی OpenClaw بارگذاری می‌شوند.
• ریشه‌های commands/ مربوط به Claude به‌عنوان ریشه‌های Skill اضافی در نظر گرفته می‌شوند.
• ریشه‌های .cursor/commands/ مربوط به Cursor به‌عنوان ریشه‌های Skill اضافی در نظر گرفته می‌شوند.

فایل‌های فرمان Markdown مربوط به Claude و Markdown فرمان Cursor، هر دو از طریق بارگذار عادی Skill در OpenClaw کار می‌کنند.

بسته‌های هوک

ریشه‌های هوک باندل فقط زمانی کار می‌کنند که از چیدمان عادی بستهٔ هوک OpenClaw استفاده کنند: HOOK.md به‌همراه handler.ts یا handler.js. در حال حاضر، این مورد عمدتاً برای سازگاری با Codex کاربرد دارد.

MCP برای OpenClaw توکار

• باندل‌های فعال می‌توانند پیکربندی سرور MCP ارائه دهند.
• OpenClaw پیکربندی MCP باندل را با نام mcpServers در تنظیمات مؤثر OpenClaw توکار ادغام می‌کند.
• OpenClaw ابزارهای MCP پشتیبانی‌شدهٔ باندل را در نوبت‌های عامل OpenClaw توکار، با اجرای سرورهای stdio یا اتصال به سرورهای HTTP ارائه می‌کند.
• نمایه‌های ابزار coding و messaging به‌طور پیش‌فرض شامل ابزارهای MCP باندل هستند؛ برای انصراف یک عامل یا Gateway از tools.deny: ["bundle-mcp"] استفاده کنید.
• تنظیمات عامل توکار محلی پروژه پس از پیش‌فرض‌های باندل همچنان اعمال می‌شوند، بنابراین تنظیمات فضای کاری می‌توانند در صورت نیاز ورودی‌های MCP باندل را بازنویسی کنند.
• فهرست ابزارهای MCP باندل پیش از ثبت به‌صورت قطعی مرتب می‌شود تا تغییرات ترتیب listTools() در بالادست باعث آشفتگی بلوک‌های ابزار حافظهٔ نهان پرامپت نشود.

انتقال‌ها

سرورهای MCP می‌توانند از انتقال stdio یا HTTP استفاده کنند.

Stdio یک فرایند فرزند را اجرا می‌کند:

{  "mcp": {    "servers": {      "my-server": {        "command": "node",        "args": ["server.js"],        "env": { "PORT": "3000" }      }    }  }}

HTTP به یک سرور MCP در حال اجرا متصل می‌شود و پیش‌فرض آن sse است، مگر اینکه streamable-http درخواست شود:

{  "mcp": {    "servers": {      "my-server": {        "url": "http://localhost:3100/mcp",        "transport": "streamable-http",        "headers": {          "Authorization": "Bearer ${MY_SECRET_TOKEN}"        },        "connectionTimeoutMs": 30000      }    }  }}

• transport مقدار "streamable-http" یا "sse" را می‌پذیرد؛ در صورت حذف، مقدار پیش‌فرض sse است.
• type: "http" یک ساختار پایین‌دستی بومی CLI است؛ در پیکربندی OpenClaw از transport: "streamable-http" استفاده کنید. openclaw mcp set و openclaw doctor --fix نام مستعار رایج را عادی‌سازی می‌کنند.
• فقط طرح‌های نشانی http: و https: مجاز هستند.
• مقادیر headers از درون‌یابی ${ENV_VAR} پشتیبانی می‌کنند.
• ورودی سروری که هم command و هم url داشته باشد رد می‌شود.
• اطلاعات احراز هویت موجود در نشانی (اطلاعات کاربر و پارامترهای پرس‌وجو) از توضیحات ابزار و گزارش‌ها حذف می‌شوند.
• connectionTimeoutMs مهلت پیش‌فرض ۳۰ ثانیه‌ای اتصال را برای هر دو انتقال stdio و HTTP بازنویسی می‌کند. مهلت درخواست به‌طور پیش‌فرض ۶۰ ثانیه است و می‌توان آن را با requestTimeoutMs بازنویسی کرد.

نام‌گذاری ابزار

OpenClaw ابزارهای MCP باندل را با نام‌های امن برای ارائه‌دهنده و به‌شکل serverName__toolName ثبت می‌کند. برای نمونه، سروری با کلید "vigil-harbor" که ابزار memory_search را ارائه می‌دهد، با نام vigil-harbor__memory_search ثبت می‌شود.

• نویسه‌های خارج از A-Za-z0-9_- با - جایگزین می‌شوند.
• بخش‌هایی که با نویسه‌ای غیرحرفی آغاز می‌شوند، یک پیشوند حرفی دریافت می‌کنند؛ بنابراین کلیدهای عددی سرور مانند 12306 به پیشوندهای ابزار امن برای ارائه‌دهنده تبدیل می‌شوند.
• طول پیشوندهای سرور حداکثر ۳۰ نویسه است.
• طول کامل نام ابزار حداکثر ۶۴ نویسه است.
• نام‌های خالی سرور از mcp به‌عنوان مقدار جایگزین استفاده می‌کنند.
• نام‌های پاک‌سازی‌شدهٔ متداخل با پسوندهای عددی از یکدیگر متمایز می‌شوند.
• ترتیب نهایی ابزارهای ارائه‌شده بر اساس نام امن قطعی است و نوبت‌های مکرر عامل توکار را از نظر حافظهٔ نهان پایدار نگه می‌دارد.
• پالایش نمایه، همهٔ ابزارهای یک سرور MCP باندل را متعلق به Plugin با کلید bundle-mcp در نظر می‌گیرد؛ بنابراین فهرست‌های مجاز/غیرمجاز نمایه می‌توانند به نام‌های تک‌تک ابزارهای ارائه‌شده یا کلید Plugin یعنی bundle-mcp ارجاع دهند.

تنظیمات OpenClaw توکار

هنگامی که باندل فعال باشد، فایل settings.json مربوط به Claude به‌عنوان تنظیمات پیش‌فرض OpenClaw توکار وارد می‌شود. OpenClaw کلیدهای بازنویسی پوسته را پیش از اعمال پاک‌سازی می‌کند:

• shellPath
• shellCommandPrefix

LSP توکار OpenClaw

• باندل‌های فعال Claude می‌توانند پیکربندی سرور LSP ارائه دهند.
• OpenClaw فایل .lsp.json را به‌همراه مسیرهای lspServers تعریف‌شده در مانیفست بارگذاری می‌کند.
• پیکربندی LSP باندل در پیش‌فرض‌های مؤثر LSP توکار OpenClaw ادغام می‌شود.
• در حال حاضر فقط سرورهای LSP پشتیبانی‌شده و مبتنی بر stdio قابل اجرا هستند؛ انتقال‌های پشتیبانی‌نشده همچنان در openclaw plugins inspect <id> نمایش داده می‌شوند.

تشخیص داده‌شده اما اجرا نمی‌شوند

موارد زیر شناسایی شده و در اطلاعات تشخیصی نمایش داده می‌شوند، اما OpenClaw آن‌ها را اجرا نمی‌کند:

• agents مربوط به Claude، خودکارسازی hooks/hooks.json و outputStyles
• .cursor/agents، .cursor/hooks.json و .cursor/rules مربوط به Cursor
• فرادادهٔ .app.json مربوط به Codex، فراتر از گزارش قابلیت‌ها

قالب‌های باندل

اولویت تشخیص

OpenClaw ابتدا قالب Plugin بومی را بررسی می‌کند:

1. openclaw.plugin.json یا یک package.json معتبر دارای openclaw.extensions؛ به‌عنوان Plugin بومی در نظر گرفته می‌شود
2. نشانگرهای باندل (.codex-plugin/، .claude-plugin/ یا چیدمان پیش‌فرض Claude/Cursor)؛ به‌عنوان باندل در نظر گرفته می‌شود

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

وابستگی‌های زمان اجرا و پاک‌سازی

• باندل‌های سازگار شخص ثالث هنگام راه‌اندازی، ترمیم با npm install دریافت نمی‌کنند. آن‌ها باید از طریق openclaw plugins install نصب شوند و هرآنچه نیاز دارند را در پوشهٔ Plugin نصب‌شده همراه داشته باشند.
• Pluginهای باندل‌شده و متعلق به OpenClaw یا به‌شکل سبک‌وزن همراه هسته عرضه می‌شوند یا از طریق نصب‌کنندهٔ Plugin قابل دریافت هستند. راه‌اندازی Gateway هرگز برای آن‌ها مدیر بسته اجرا نمی‌کند.
• openclaw doctor --fix رکوردهای منسوخ نصب محلی Pluginهای باندل‌شده را حذف می‌کند و اگر پیکربندی همچنان به Pluginهای قابل دریافت اشاره کند که در نمایهٔ محلی Plugin موجود نیستند، می‌تواند آن‌ها را بازیابی کند.

امنیت

باندل‌ها نسبت به Pluginهای بومی مرز اعتماد محدودتری دارند:

• OpenClaw ماژول‌های دلخواه زمان اجرای باندل را درون‌پردازه‌ای بارگذاری نمی‌کند.
• مسیرهای Skills و بستهٔ هوک باید داخل ریشهٔ Plugin باقی بمانند (با بررسی مرز).
• فایل‌های تنظیمات با همان بررسی‌های مرزی خوانده می‌شوند.
• سرورهای stdio MCP پشتیبانی‌شده ممکن است به‌عنوان زیرپردازه اجرا شوند.

این موضوع باندل‌ها را به‌طور پیش‌فرض ایمن‌تر می‌کند، اما همچنان باید باندل‌های شخص ثالث را برای قابلیت‌هایی که ارائه می‌دهند، محتوای مورد اعتماد در نظر بگیرید.

عیب‌یابی

مرتبط

• نصب و پیکربندی Pluginها
• ساخت Pluginها - ایجاد یک Plugin بومی
• مانیفست Plugin - طرح‌وارهٔ مانیفست بومی