بسته‌های Plugin

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

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

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

نصب یک باندل

# Local directoryopenclaw plugins install ./my-bundle # Archiveopenclaw plugins install ./my-bundle.tgz # Claude marketplaceopenclaw plugins marketplace list <marketplace-name>openclaw plugins install <plugin-name>@<marketplace-name>

openclaw plugins listopenclaw plugins inspect <id>

openclaw gateway restart

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

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

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

محتوای Skill

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

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

بسته‌های Hook

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

MCP برای OpenClaw توکار

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

ترابری‌ها

سرورهای MCP می‌توانند از ترابری stdio یا HTTP استفاده کنند:

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

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

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

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

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

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

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

• نویسه‌های خارج از A-Za-z0-9_- با - جایگزین می‌شوند
• قطعه‌هایی که با حرف شروع نمی‌شوند یک پیشوند حرفی می‌گیرند، بنابراین کلیدهای عددی سرور مانند 12306 به پیشوندهای ابزار ایمن برای provider تبدیل می‌شوند
• پیشوندهای سرور به ۳۰ نویسه محدود می‌شوند
• نام کامل ابزارها به ۶۴ نویسه محدود می‌شود
• نام‌های خالی سرور به mcp برمی‌گردند
• نام‌های پاک‌سازی‌شده برخوردکننده با پسوندهای عددی از هم متمایز می‌شوند
• ترتیب نهایی ابزارهای ارائه‌شده بر اساس نام ایمن قطعی است تا نوبت‌های تکراری embedded-agent از نظر کش پایدار بمانند
• فیلتر پروفایل همه ابزارهای یک سرور MCP باندل را متعلق به Plugin با کلید bundle-mcp در نظر می‌گیرد، بنابراین allowlistها و deny listهای پروفایل می‌توانند هم نام‌های ابزار ارائه‌شده منفرد و هم کلید Plugin یعنی bundle-mcp را شامل شوند

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

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

کلیدهای پاک‌سازی‌شده:

• shellPath
• shellCommandPrefix

LSP توکار OpenClaw

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

شناسایی‌شده اما اجرا نمی‌شود

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

• agents، اتوماسیون hooks.json، و outputStyles در Claude
• .cursor/agents، .cursor/hooks.json، و .cursor/rules در Cursor
• فراداده درون‌خطی/برنامه 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 یا به‌صورت سبک در core ارسال می‌شوند یا از طریق نصب‌کننده Plugin قابل دانلود هستند. راه‌اندازی Gateway هرگز برای آن‌ها package manager اجرا نمی‌کند.
• openclaw doctor --fix پوشه‌های وابستگی staged قدیمی را حذف می‌کند و می‌تواند Pluginهای قابل دانلودی را که در نمایه Plugin محلی وجود ندارند اما config به آن‌ها ارجاع می‌دهد بازیابی کند.

امنیت

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

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

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

عیب‌یابی

مرتبط

• نصب و پیکربندی Pluginها
• ساخت Pluginها — ایجاد یک Plugin بومی
• Manifest Plugin — schema مربوط به manifest بومی