---
read_when:
    - می‌خواهید یک بستهٔ سازگار با Codex، Claude یا Cursor نصب کنید
    - باید بدانید OpenClaw چگونه محتوای بسته را به قابلیت‌های بومی نگاشت می‌کند
    - در حال اشکال‌زدایی تشخیص بسته یا قابلیت‌های مفقود هستید
summary: بسته‌های Codex، Claude و Cursor را به‌عنوان Pluginهای OpenClaw نصب و استفاده کنید
title: بسته‌های Plugin
x-i18n:
    generated_at: "2026-07-12T10:26:03Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: d44006866238f53ee2e3e8126cc4f7ed6f7413534257775f7904c9b877778c59
    source_path: plugins/bundles.md
    workflow: 16
---

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

<Info>
  باندل‌ها با Pluginهای بومی OpenClaw **یکسان نیستند**. Pluginهای بومی درون‌پردازه‌ای اجرا
  می‌شوند و می‌توانند هر قابلیتی را ثبت کنند. باندل‌ها بسته‌های محتوایی با
  نگاشت گزینشی قابلیت‌ها و مرز اعتماد محدودتری هستند.
</Info>

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

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

## نصب باندل

<Steps>
  <Step title="نصب از پوشه، بایگانی یا بازار">
    ```bash
    # پوشهٔ محلی
    openclaw plugins install ./my-bundle

    # بایگانی
    openclaw plugins install ./my-bundle.tgz

    # بازار Claude
    openclaw plugins marketplace list <source>
    openclaw plugins install <plugin> --marketplace <source>
    ```

    `<source>` مسیر یا مخزن محلی بازار، یا یک منبع git/GitHub است.

  </Step>

  <Step title="تأیید تشخیص">
    ```bash
    openclaw plugins list
    openclaw plugins inspect <id>
    ```

    باندل‌ها `Format: bundle` را همراه با مقدار `Bundle format:` برابر با `codex`،
    `claude` یا `cursor` نمایش می‌دهند.

  </Step>

  <Step title="راه‌اندازی مجدد و استفاده">
    ```bash
    openclaw gateway restart
    ```

    قابلیت‌های نگاشت‌شده (Skills، هوک‌ها، ابزارهای MCP و پیش‌فرض‌های LSP) در نشست بعدی در دسترس هستند.

  </Step>
</Steps>

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

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

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

| قابلیت         | نحوهٔ نگاشت                                                                                       | قابل‌اعمال به     |
| ------------- | ------------------------------------------------------------------------------------------------- | -------------- |
| محتوای Skill | ریشه‌های Skill باندل مانند Skills عادی OpenClaw بارگذاری می‌شوند                                                 | همهٔ قالب‌ها    |
| فرمان‌ها      | `commands/` و `.cursor/commands/` به‌عنوان ریشه‌های Skill در نظر گرفته می‌شوند                                        | Claude، Cursor |
| بسته‌های هوک    | چیدمان‌های سازگار با OpenClaw شامل `HOOK.md` و `handler.ts`                                                   | Codex          |
| ابزارهای MCP     | پیکربندی MCP باندل در تنظیمات OpenClaw توکار ادغام می‌شود؛ سرورهای stdio و HTTP پشتیبانی‌شده بارگذاری می‌شوند | همهٔ قالب‌ها    |
| سرورهای LSP   | فایل `.lsp.json` مربوط به Claude و `lspServers` تعریف‌شده در مانیفست، در پیش‌فرض‌های LSP توکار OpenClaw ادغام می‌شوند  | Claude         |
| تنظیمات      | فایل `settings.json` مربوط به Claude به‌عنوان پیش‌فرض‌های توکار OpenClaw وارد می‌شود                                     | Claude         |

#### محتوای 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** یک فرایند فرزند را اجرا می‌کند:

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

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

```json
{
  "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، فراتر از گزارش قابلیت‌ها

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

<AccordionGroup>
  <Accordion title="باندل‌های Codex">
    نشانگرها: `.codex-plugin/plugin.json`

    محتوای اختیاری: `skills/`، `hooks/`، `.mcp.json`، `.app.json`

    باندل‌های Codex زمانی بهترین سازگاری را با OpenClaw دارند که از ریشه‌های Skill و پوشه‌های
    بستهٔ هوک با سبک OpenClaw (`HOOK.md` و `handler.ts`) استفاده کنند.

  </Accordion>

  <Accordion title="باندل‌های Claude">
    دو حالت تشخیص:

    - **مبتنی بر مانیفست:** `.claude-plugin/plugin.json`
    - **بدون مانیفست:** چیدمان پیش‌فرض Claude (`skills/`، `commands/`، `agents/`، `hooks/`، `.mcp.json`، `.lsp.json`، `settings.json`)

    رفتار مختص Claude:

    - `commands/` به‌عنوان محتوای Skill در نظر گرفته می‌شود
    - `settings.json` به تنظیمات OpenClaw توکار وارد می‌شود (کلیدهای بازنویسی پوسته پاک‌سازی می‌شوند)
    - `.mcp.json` ابزارهای stdio پشتیبانی‌شده را در اختیار OpenClaw توکار قرار می‌دهد
    - `.lsp.json` به‌همراه مسیرهای `lspServers` تعریف‌شده در مانیفست در پیش‌فرض‌های LSP توکار OpenClaw بارگذاری می‌شوند
    - `hooks/hooks.json` تشخیص داده می‌شود اما اجرا نمی‌شود
    - مسیرهای سفارشی مؤلفه‌ها در مانیفست افزایشی هستند؛ آن‌ها پیش‌فرض‌ها را گسترش می‌دهند، نه اینکه جایگزینشان شوند

  </Accordion>

  <Accordion title="باندل‌های Cursor">
    نشانگرها: `.cursor-plugin/plugin.json`

    محتوای اختیاری: `skills/`، `.cursor/commands/`، `.cursor/agents/`، `.cursor/rules/`، `.cursor/hooks.json`، `.mcp.json`

    - `.cursor/commands/` به‌عنوان محتوای Skill در نظر گرفته می‌شود
    - `.cursor/rules/`، `.cursor/agents/` و `.cursor/hooks.json` فقط تشخیص داده می‌شوند

  </Accordion>
</AccordionGroup>

## اولویت تشخیص

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 پشتیبانی‌شده ممکن است به‌عنوان زیرپردازه اجرا شوند.

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

## عیب‌یابی

<AccordionGroup>
  <Accordion title="باندل تشخیص داده می‌شود اما قابلیت‌ها اجرا نمی‌شوند">
    `openclaw plugins inspect <id>` را اجرا کنید. اگر قابلیتی فهرست شده اما به‌عنوان
    متصل‌نشده علامت‌گذاری شده است، این محدودیت محصول است، نه نصب خراب.
  </Accordion>

  <Accordion title="فایل‌های فرمان Claude ظاهر نمی‌شوند">
    مطمئن شوید باندل فعال است و فایل‌های Markdown داخل یک ریشهٔ تشخیص‌داده‌شدهٔ
    `commands/` یا `skills/` قرار دارند.
  </Accordion>

  <Accordion title="تنظیمات Claude اعمال نمی‌شوند">
    فقط تنظیمات OpenClaw توکار از `settings.json` پشتیبانی می‌شوند. OpenClaw
    تنظیمات باندل را وصله‌های خام پیکربندی در نظر نمی‌گیرد.
  </Accordion>

  <Accordion title="هوک‌های Claude اجرا نمی‌شوند">
    `hooks/hooks.json` فقط تشخیص داده می‌شود. اگر به هوک‌های قابل اجرا نیاز دارید، از
    چیدمان بستهٔ هوک OpenClaw استفاده کنید یا یک Plugin بومی عرضه کنید.
  </Accordion>
</AccordionGroup>

## مرتبط

- [نصب و پیکربندی Pluginها](/fa/tools/plugin)
- [ساخت Pluginها](/fa/plugins/building-plugins) - ایجاد یک Plugin بومی
- [مانیفست Plugin](/fa/plugins/manifest) - طرح‌وارهٔ مانیفست بومی