بسته‌های Plugin

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

چرا بسته‌ها وجود دارند

بسیاری از Pluginهای مفید با قالب Codex، Claude یا Cursor منتشر می‌شوند. OpenClaw به‌جای ملزم‌کردن نویسندگان به بازنویسی آن‌ها به‌صورت Pluginهای بومی OpenClaw، این قالب‌ها را شناسایی می‌کند و محتوای پشتیبانی‌شدهٔ آن‌ها را به مجموعه قابلیت‌های بومی نگاشت می‌کند. می‌توان یک بستهٔ فرمان Claude یا بستهٔ مهارت 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 اجرا نمی‌شوند. در ادامه مواردی آمده‌اند که کار می‌کنند و مواردی که شناسایی شده‌اند اما هنوز متصل نشده‌اند.

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

محتوای مهارت

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

فایل‌های فرمان Markdown در Claude و Markdown فرمان در Cursor، هر دو از طریق بارگذار عادی مهارت 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 نام مستعار رایج را نرمال‌سازی می‌کنند.
• فقط طرح‌های URL برابر با http: و https: مجاز هستند.
• مقادیر headers از درون‌یابی ${ENV_VAR} پشتیبانی می‌کنند.
• ورودی سروری که هم command و هم url را داشته باشد رد می‌شود.
• اعتبارنامه‌های URL (اطلاعات کاربر و پارامترهای پرس‌وجو) در توضیحات ابزار و گزارش‌ها پوشانده می‌شوند.
• connectionTimeoutMs مهلت اتصال پیش‌فرض 30 ثانیه‌ای را برای هر دو انتقال stdio و HTTP بازنویسی می‌کند. مهلت درخواست به‌طور پیش‌فرض 60 ثانیه است و می‌توان آن را با requestTimeoutMs بازنویسی کرد.

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

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

• نویسه‌های خارج از A-Za-z0-9_- با - جایگزین می‌شوند.
• قطعه‌هایی که با یک نویسهٔ غیرحرفی آغاز می‌شوند، یک پیشوند حرفی دریافت می‌کنند؛ بنابراین کلیدهای عددی سرور مانند 12306 به پیشوند ابزار امن برای ارائه‌دهنده تبدیل می‌شوند.
• طول پیشوندهای سرور حداکثر 30 نویسه است.
• طول نام کامل ابزار حداکثر 64 نویسه است.
• نام‌های خالی سرور به 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، خودکارسازی hooks/hooks.json و outputStyles در Claude
• .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 ماژول‌های دلخواه زمان اجرای بسته را به‌صورت درون‌فرایندی بارگذاری نمی‌کند.
• مسیرهای مهارت و بستهٔ هوک باید داخل ریشهٔ Plugin باقی بمانند (با بررسی مرز).
• فایل‌های تنظیمات با همان بررسی‌های مرزی خوانده می‌شوند.
• سرورهای پشتیبانی‌شدهٔ MCP مبتنی بر stdio ممکن است به‌صورت زیرفرایند راه‌اندازی شوند.

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

عیب‌یابی

مرتبط

• نصب و پیکربندی Pluginها
• ساخت Pluginها - یک Plugin بومی ایجاد کنید
• مانیفست Plugin - شِمای مانیفست بومی