---
read_when:
    - شما در حال ساخت یک Plugin برای OpenClaw هستید
    - باید یک طرح‌وارهٔ پیکربندی Plugin منتشر کنید یا خطاهای اعتبارسنجی Plugin را اشکال‌زدایی کنید
summary: الزامات مانیفست Plugin و شِمای JSON (اعتبارسنجی سخت‌گیرانهٔ پیکربندی)
title: مانیفست Plugin
x-i18n:
    generated_at: "2026-07-12T10:31:07Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: cd4ab5b10108585abb9a83a416b129e6f6351023016064b5d64b66aeabd04b2f
    source_path: plugins/manifest.md
    workflow: 16
---

این صفحه **مانیفست بومی Plugin در OpenClaw**، یعنی `openclaw.plugin.json`، را پوشش می‌دهد. برای چیدمان بسته‌های سازگار (Codex، Claude، Cursor)، به [بسته‌های Plugin](/fa/plugins/bundles) مراجعه کنید.

قالب‌های بستهٔ سازگار در عوض از فایل‌های مانیفست خودشان استفاده می‌کنند:

- بستهٔ Codex: `.codex-plugin/plugin.json`
- بستهٔ Claude: `.claude-plugin/plugin.json`، یا چیدمان پیش‌فرض مؤلفه‌های Claude بدون مانیفست
- بستهٔ Cursor: `.cursor-plugin/plugin.json`

OpenClaw این چیدمان‌ها را به‌طور خودکار شناسایی می‌کند، اما آن‌ها را بر اساس شِمای `openclaw.plugin.json` در ادامه اعتبارسنجی نمی‌کند. برای یک بستهٔ سازگار، هرگاه چیدمان با انتظارات زمان اجرای OpenClaw مطابقت داشته باشد، OpenClaw فرادادهٔ بسته، ریشه‌های اعلام‌شدهٔ Skills، ریشه‌های فرمان Claude، مقادیر پیش‌فرض `settings.json` در Claude، مقادیر پیش‌فرض LSP در Claude و بسته‌های هوک پشتیبانی‌شده را می‌خواند.

هر Plugin بومی OpenClaw **باید** فایل `openclaw.plugin.json` را در **ریشهٔ Plugin** ارائه کند. OpenClaw آن را برای اعتبارسنجی پیکربندی، **بدون اجرای کد Plugin**، می‌خواند. مانیفست مفقود یا نامعتبر، اعتبارسنجی پیکربندی را مسدود می‌کند و خطای Plugin در نظر گرفته می‌شود.

برای راهنمای کامل سامانهٔ Plugin به [Pluginها](/fa/tools/plugin) و برای مدل قابلیت بومی و راهنمای فعلی سازگاری خارجی به [مدل قابلیت](/fa/plugins/architecture#public-capability-model) مراجعه کنید.

## این فایل چه کاری انجام می‌دهد

`openclaw.plugin.json` فراداده‌ای است که OpenClaw آن را **پیش از بارگذاری کد Plugin شما** می‌خواند. بررسی تمام موارد موجود در آن باید بدون راه‌اندازی زمان اجرای Plugin به‌اندازهٔ کافی کم‌هزینه باشد.

**از آن برای موارد زیر استفاده کنید:**

- هویت Plugin، اعتبارسنجی پیکربندی و راهنمای رابط کاربری پیکربندی
- فرادادهٔ احراز هویت، ورود اولیه و راه‌اندازی (نام مستعار، فعال‌سازی خودکار، متغیرهای محیطی ارائه‌دهنده، گزینه‌های احراز هویت)
- راهنمای فعال‌سازی برای سطوح صفحهٔ کنترل
- مالکیت مختصر خانوادهٔ مدل
- نماهای ایستای مالکیت قابلیت (`contracts`)
- فرادادهٔ اجراکنندهٔ تضمین کیفیت که میزبان مشترک `openclaw qa` بتواند بررسی کند
- فرادادهٔ پیکربندی مخصوص کانال که در سطوح فهرست و اعتبارسنجی ادغام می‌شود

**از آن برای موارد زیر استفاده نکنید:** ثبت رفتار زمان اجرا، اعلام نقاط ورود کد یا فرادادهٔ نصب npm. این موارد به کد Plugin شما و `package.json` تعلق دارند.

## نمونهٔ حداقلی

```json
{
  "id": "voice-call",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  }
}
```

## نمونهٔ جامع

```json
{
  "id": "openrouter",
  "name": "OpenRouter",
  "description": "OpenRouter provider plugin",
  "version": "1.0.0",
  "providers": ["openrouter"],
  "modelSupport": {
    "modelPrefixes": ["router-"]
  },
  "modelIdNormalization": {
    "providers": {
      "openrouter": {
        "prefixWhenBare": "openrouter"
      }
    }
  },
  "providerEndpoints": [
    {
      "endpointClass": "openrouter",
      "hostSuffixes": ["openrouter.ai"]
    }
  ],
  "providerRequest": {
    "providers": {
      "openrouter": {
        "family": "openrouter"
      }
    }
  },
  "cliBackends": ["openrouter-cli"],
  "syntheticAuthRefs": ["openrouter-cli"],
  "setup": {
    "providers": [
      {
        "id": "openrouter",
        "envVars": ["OPENROUTER_API_KEY"]
      }
    ]
  },
  "providerAuthAliases": {
    "openrouter-coding": "openrouter"
  },
  "channelEnvVars": {
    "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"]
  },
  "providerAuthChoices": [
    {
      "provider": "openrouter",
      "method": "api-key",
      "choiceId": "openrouter-api-key",
      "choiceLabel": "OpenRouter API key",
      "groupId": "openrouter",
      "groupLabel": "OpenRouter",
      "optionKey": "openrouterApiKey",
      "cliFlag": "--openrouter-api-key",
      "cliOption": "--openrouter-api-key <key>",
      "cliDescription": "OpenRouter API key",
      "onboardingScopes": ["text-inference"]
    }
  ],
  "uiHints": {
    "apiKey": {
      "label": "API key",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  },
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "apiKey": {
        "type": "string"
      }
    }
  }
}
```

## مرجع فیلدهای سطح بالا

| فیلد                                | الزامی | نوع                          | مفهوم                                                                                                                                                                                                                                                              |
| ------------------------------------ | -------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                                 | بله      | `string`                     | شناسهٔ استاندارد Plugin. این همان شناسه‌ای است که در `plugins.entries.<id>` استفاده می‌شود.                                                                                                                                                                                                        |
| `configSchema`                       | بله      | `object`                     | طرح‌وارهٔ JSON درون‌خطی برای پیکربندی این Plugin.                                                                                                                                                                                                                               |
| `requiresPlugins`                    | خیر       | `string[]`                   | شناسه‌های Pluginهایی که برای اثرگذاری این Plugin باید آن‌ها نیز نصب شده باشند. فرایند کشف، Plugin را قابل بارگذاری نگه می‌دارد، اما در صورت نبود هر یک از Pluginهای الزامی هشدار می‌دهد.                                                                                                               |
| `enabledByDefault`                   | خیر       | `true`                       | یک Plugin همراه را به‌عنوان فعال به‌صورت پیش‌فرض علامت‌گذاری می‌کند. برای غیرفعال ماندن پیش‌فرض Plugin، این فیلد را حذف کنید یا مقداری غیر از `true` برای آن تنظیم کنید.                                                                                                                                               |
| `enabledByDefaultOnPlatforms`        | خیر       | `string[]`                   | یک Plugin همراه را فقط در پلتفرم‌های فهرست‌شدهٔ Node.js، برای مثال `["darwin"]`، به‌صورت پیش‌فرض فعال علامت‌گذاری می‌کند. پیکربندی صریح همچنان اولویت دارد.                                                                                                                                   |
| `legacyPluginIds`                    | خیر       | `string[]`                   | شناسه‌های قدیمی که به این شناسهٔ استاندارد Plugin نرمال‌سازی می‌شوند.                                                                                                                                                                                                                     |
| `autoEnableWhenConfiguredProviders`  | خیر       | `string[]`                   | شناسه‌های ارائه‌دهنده‌ای که هنگام اشارهٔ احراز هویت، پیکربندی یا ارجاع‌های مدل به آن‌ها، باید این Plugin را به‌طور خودکار فعال کنند.                                                                                                                                                                            |
| `kind`                               | خیر       | `PluginKind \| PluginKind[]` | یک یا چند نوع انحصاری Plugin (`"memory"`، `"context-engine"`) را که `plugins.slots.*` استفاده می‌کند اعلام می‌کند. Pluginی که مالک هر دو شکاف است، هر دو نوع را در یک آرایه اعلام می‌کند.                                                                                                    |
| `channels`                           | خیر       | `string[]`                   | شناسه‌های کانالی که این Plugin مالک آن‌ها است. برای کشف و اعتبارسنجی پیکربندی استفاده می‌شود.                                                                                                                                                                                                |
| `providers`                          | خیر       | `string[]`                   | شناسه‌های ارائه‌دهنده‌ای که این Plugin مالک آن‌ها است.                                                                                                                                                                                                                                         |
| `providerCatalogEntry`               | خیر       | `string`                     | مسیر ماژول سبک‌وزن کاتالوگ ارائه‌دهنده، نسبت به ریشهٔ Plugin، برای فرادادهٔ کاتالوگ ارائه‌دهنده با دامنهٔ مانیفست که می‌توان آن را بدون فعال‌سازی کامل زمان اجرای Plugin بارگذاری کرد.                                                                                        |
| `modelSupport`                       | خیر       | `object`                     | فرادادهٔ خلاصهٔ خانوادهٔ مدل تحت مالکیت مانیفست که برای بارگذاری خودکار Plugin پیش از زمان اجرا استفاده می‌شود.                                                                                                                                                                                |
| `modelCatalog`                       | خیر       | `object`                     | فرادادهٔ اعلانی کاتالوگ مدل برای ارائه‌دهندگانی که این Plugin مالک آن‌ها است. این قرارداد صفحهٔ کنترل برای فهرست‌سازی فقط‌خواندنی آینده، راه‌اندازی اولیه، انتخاب‌گرهای مدل، نام‌های مستعار و پنهان‌سازی بدون بارگذاری زمان اجرای Plugin است.                                                |
| `modelPricing`                       | خیر       | `object`                     | خط‌مشی جست‌وجوی قیمت‌گذاری خارجی تحت مالکیت ارائه‌دهنده. از آن برای خارج کردن ارائه‌دهندگان محلی/خودمیزبان از کاتالوگ‌های قیمت‌گذاری راه‌دور یا نگاشت ارجاع‌های ارائه‌دهنده به شناسه‌های کاتالوگ OpenRouter/LiteLLM بدون کدنویسی ثابت شناسه‌های ارائه‌دهنده در هسته استفاده کنید.                                                    |
| `modelIdNormalization`               | خیر       | `object`                     | پاک‌سازی نام مستعار/پیشوند شناسهٔ مدل تحت مالکیت ارائه‌دهنده که باید پیش از بارگذاری زمان اجرای ارائه‌دهنده انجام شود.                                                                                                                                                                                  |
| `providerEndpoints`                  | خیر       | `object[]`                   | فرادادهٔ میزبان/`baseUrl` نقطهٔ پایانی تحت مالکیت مانیفست برای مسیرهای ارائه‌دهنده که هسته باید پیش از بارگذاری زمان اجرای ارائه‌دهنده طبقه‌بندی کند.                                                                                                                                                   |
| `providerRequest`                    | خیر       | `object`                     | فرادادهٔ کم‌هزینهٔ خانوادهٔ ارائه‌دهنده و سازگاری درخواست که خط‌مشی عمومی درخواست پیش از بارگذاری زمان اجرای ارائه‌دهنده از آن استفاده می‌کند.                                                                                                                                                     |
| `secretProviderIntegrations`         | خیر       | `Record<string, object>`     | پیش‌تنظیم‌های اعلانی ارائه‌دهندهٔ اجرایی SecretRef که بخش‌های راه‌اندازی یا نصب می‌توانند بدون کدنویسی ثابت یکپارچه‌سازی‌های مختص ارائه‌دهنده در هسته عرضه کنند.                                                                                                                            |
| `cliBackends`                        | خیر       | `string[]`                   | شناسه‌های پشتیبان استنتاج CLI که این Plugin مالک آن‌ها است. برای فعال‌سازی خودکار هنگام راه‌اندازی بر اساس ارجاع‌های صریح پیکربندی استفاده می‌شود.                                                                                                                                                                |
| `syntheticAuthRefs`                  | خیر       | `string[]`                   | ارجاع‌های ارائه‌دهنده یا پشتیبان CLI که قلاب احراز هویت مصنوعی تحت مالکیت Plugin آن‌ها باید هنگام کشف سرد مدل و پیش از بارگذاری زمان اجرا بررسی شود.                                                                                                                                     |
| `nonSecretAuthMarkers`               | خیر       | `string[]`                   | مقادیر جای‌نگهدار کلید API تحت مالکیت Plugin همراه که بیانگر وضعیت اعتبارنامهٔ غیرمحرمانهٔ محلی، OAuth یا محیطی هستند.                                                                                                                                                       |
| `commandAliases`                     | خیر       | `object[]`                   | نام‌های فرمان تحت مالکیت این Plugin که باید پیش از بارگذاری زمان اجرا، عیب‌یابی پیکربندی و CLI آگاه از Plugin ایجاد کنند.                                                                                                                                                       |
| `providerAuthEnvVars`                | خیر       | `Record<string, string[]>`   | فرادادهٔ متغیر محیطی سازگاری منسوخ‌شده برای جست‌وجوی احراز هویت/وضعیت ارائه‌دهنده. برای Pluginهای جدید، `setup.providers[].envVars` را ترجیح دهید؛ OpenClaw همچنان در بازهٔ منسوخ‌سازی این مورد را می‌خواند.                                                                                        |
| `providerUsageAuthEnvVars`           | خیر       | `Record<string, string[]>`   | اعتبارنامه‌های ارائه‌دهنده فقط برای مصرف/صورتحساب. OpenClaw این نام‌ها را برای کشف مصرف و پاک‌سازی اسرار استفاده می‌کند، اما هرگز برای احراز هویت استنتاج به کار نمی‌برد.                                                                                                                                  |
| `providerAuthAliases`                | خیر       | `Record<string, string>`     | شناسه‌های ارائه‌دهنده‌ای که برای جست‌وجوی احراز هویت باید از شناسهٔ ارائه‌دهندهٔ دیگری استفاده کنند؛ برای مثال، یک ارائه‌دهندهٔ کدنویسی که کلید API و نمایه‌های احراز هویت ارائه‌دهندهٔ پایه را به اشتراک می‌گذارد.                                                                                                                 |
| `channelEnvVars`                     | خیر       | `Record<string, string[]>`   | فرادادهٔ کم‌هزینهٔ متغیر محیطی کانال که OpenClaw می‌تواند بدون بارگذاری کد Plugin بررسی کند. از این مورد برای راه‌اندازی کانال مبتنی بر متغیر محیطی یا بخش‌های احراز هویت استفاده کنید که کمک‌کننده‌های عمومی راه‌اندازی/پیکربندی باید مشاهده کنند.                                                                                   |
| `providerAuthChoices`                | خیر       | `object[]`                   | فرادادهٔ کم‌هزینهٔ گزینه‌های احراز هویت برای انتخاب‌گرهای راه‌اندازی اولیه، تشخیص ارائه‌دهندهٔ ترجیحی و سیم‌کشی سادهٔ پرچم‌های CLI.                                                                                                                                                              |
| `activation`                         | خیر       | `object`                     | فرادادهٔ کم‌هزینهٔ برنامه‌ریز فعال‌سازی برای بارگذاری برانگیخته‌شده توسط راه‌اندازی، ارائه‌دهنده، فرمان، کانال، مسیر و قابلیت. فقط فراداده است؛ زمان اجرای Plugin همچنان مالک رفتار واقعی است.                                                                                              |
| `setup`                              | خیر       | `object`                     | توصیف‌گرهای کم‌هزینهٔ راه‌اندازی/راه‌اندازی اولیه که بخش‌های کشف و راه‌اندازی می‌توانند بدون بارگذاری زمان اجرای Plugin بررسی کنند.                                                                                                                                                           |
| `qaRunners`                          | خیر       | `object[]`                   | توصیف‌گرهای کم‌هزینهٔ اجراکنندهٔ تضمین کیفیت که میزبان مشترک `openclaw qa` پیش از بارگذاری زمان اجرای Plugin استفاده می‌کند.                                                                                                                                                                             |
| `contracts`                          | خیر       | `object`                     | تصویر ثابت مالکیت قابلیت‌ها برای قلاب‌های احراز هویت خارجی، تعبیه‌سازی‌ها، گفتار، رونویسی بلادرنگ، صدای بلادرنگ، درک رسانه، تولید تصویر/ویدئو/موسیقی، واکشی وب، جست‌وجوی وب، ارائه‌دهندگان کارگر، استخراج سند/محتوای وب و مالکیت ابزار. |
| `configContracts`                    | خیر       | `object`                     | رفتار پیکربندی تحت مالکیت مانیفست که کمک‌کننده‌های عمومی هسته از آن استفاده می‌کنند: تشخیص پرچم خطرناک، مقصدهای مهاجرت SecretRef و محدودسازی مسیر پیکربندی قدیمی. [مرجع configContracts](#configcontracts-reference) را ببینید.                                                     |
| `mediaUnderstandingProviderMetadata` | خیر       | `Record<string, object>`     | پیش‌فرض‌های کم‌هزینهٔ درک رسانه برای شناسه‌های ارائه‌دهندهٔ اعلام‌شده در `contracts.mediaUnderstandingProviders`.                                                                                                                                                                   |
| `imageGenerationProviderMetadata`    | خیر       | `Record<string, object>`     | فرادادهٔ کم‌هزینهٔ احراز هویت تولید تصویر برای شناسه‌های ارائه‌دهندهٔ اعلام‌شده در `contracts.imageGenerationProviders`، شامل نام‌های مستعار احراز هویت تحت مالکیت ارائه‌دهنده و محافظ‌های نشانی پایه.                                                                                                         |
| `videoGenerationProviderMetadata`    | خیر       | `Record<string, object>`     | فرادادهٔ کم‌هزینهٔ احراز هویت تولید ویدئو برای شناسه‌های ارائه‌دهندهٔ اعلام‌شده در `contracts.videoGenerationProviders`، شامل نام‌های مستعار احراز هویت تحت مالکیت ارائه‌دهنده و محافظ‌های نشانی پایه.                                                                                                         |
| `musicGenerationProviderMetadata`    | خیر       | `Record<string, object>`     | فرادادهٔ کم‌هزینهٔ احراز هویت تولید موسیقی برای شناسه‌های ارائه‌دهندهٔ اعلام‌شده در `contracts.musicGenerationProviders`، شامل نام‌های مستعار احراز هویت تحت مالکیت ارائه‌دهنده و محافظ‌های نشانی پایه.                                                                                                         |
| `toolMetadata`                       | خیر       | `Record<string, object>`     | فرادادهٔ کم‌هزینهٔ دسترس‌پذیری برای ابزارهای تحت مالکیت Plugin که در `contracts.tools` اعلام شده‌اند. زمانی از آن استفاده کنید که ابزار نباید زمان‌اجرا را بارگذاری کند، مگر اینکه شواهد پیکربندی، محیط یا احراز هویت وجود داشته باشد.                                                                                                  |
| `channelConfigs`                     | خیر       | `Record<string, object>`     | فرادادهٔ پیکربندی کانال تحت مالکیت مانیفست که پیش از بارگذاری زمان‌اجرا، در سطوح کشف و اعتبارسنجی ادغام می‌شود.                                                                                                                                                                 |
| `skills`                             | خیر       | `string[]`                   | پوشه‌های Skills که باید بارگذاری شوند، به‌صورت نسبی نسبت به ریشهٔ Plugin.                                                                                                                                                                                                                    |
| `name`                               | خیر       | `string`                     | نام خوانای Plugin برای انسان.                                                                                                                                                                                                                                                |
| `description`                        | خیر       | `string`                     | خلاصهٔ کوتاهی که در سطوح Plugin نمایش داده می‌شود.                                                                                                                                                                                                                                    |
| `catalog`                            | خیر       | `object`                     | راهنمای اختیاری نمایش برای سطوح کاتالوگ Plugin. این فراداده یک Plugin را نصب یا فعال نمی‌کند و به آن اعتماد اعطا نمی‌کند.                                                                                                                                               |
| `icon`                               | خیر       | `string`                     | نشانی HTTPS تصویر برای کارت‌های بازار/کاتالوگ. ClawHub هر نشانی معتبر `https://` را می‌پذیرد و اگر این مقدار حذف شده یا نامعتبر باشد، از نماد پیش‌فرض Plugin استفاده می‌کند.                                                                                                         |
| `version`                            | خیر       | `string`                     | نسخهٔ اطلاع‌رسانی Plugin.                                                                                                                                                                                                                                              |
| `uiHints`                            | خیر       | `Record<string, object>`     | برچسب‌های رابط کاربری، جای‌نگهدارها و راهنمای حساسیت برای فیلدهای پیکربندی.                                                                                                                                                                                                          |

## مرجع catalog

`catalog` راهنمای اختیاری برای نحوه نمایش در مرورگرهای Plugin فراهم می‌کند. میزبان‌ها می‌توانند این راهنماها را نادیده بگیرند. این راهنماها هرگز Plugin را نصب یا فعال نمی‌کنند و رفتار زمان اجرا یا سطح اعتماد آن را تغییر نمی‌دهند.

```json
{
  "catalog": {
    "featured": true,
    "order": 10
  }
}
```

| فیلد       | نوع       | مفهوم                                                                    |
| ---------- | --------- | ------------------------------------------------------------------------ |
| `featured` | `boolean` | آیا سطوح catalog باید این Plugin را برجسته کنند.                         |
| `order`    | `number`  | راهنمای ترتیب نمایش صعودی میان Pluginهای گزینش‌شده؛ مقادیر کمتر زودتر نمایش داده می‌شوند. |

## مرجع فراداده ارائه‌دهنده تولید

فیلدهای فراداده ارائه‌دهنده تولید، نشانه‌های ایستای احراز هویت را برای ارائه‌دهندگانی توصیف می‌کنند که در فهرست متناظر `contracts.*GenerationProviders` اعلام شده‌اند. OpenClaw این فیلدها را پیش از بارگذاری زمان اجرای ارائه‌دهنده می‌خواند تا ابزارهای هسته بتوانند بدون واردکردن همه Pluginهای ارائه‌دهنده تصمیم بگیرند که آیا یک ارائه‌دهنده تولید در دسترس است.

این فیلدها را فقط برای واقعیت‌های کم‌هزینه و اعلانی به کار ببرید. انتقال، تبدیل درخواست‌ها، نوسازی توکن، اعتبارسنجی اطلاعات احراز هویت و رفتار واقعی تولید در زمان اجرای Plugin باقی می‌مانند.

```json
{
  "contracts": {
    "imageGenerationProviders": ["example-image"]
  },
  "imageGenerationProviderMetadata": {
    "example-image": {
      "aliases": ["example-image-oauth"],
      "authProviders": ["example-image"],
      "configSignals": [
        {
          "rootPath": "plugins.entries.example-image.config",
          "overlayPath": "image",
          "mode": {
            "path": "mode",
            "default": "local",
            "allowed": ["local"]
          },
          "requiredAny": ["workflow", "workflowPath"],
          "required": ["promptNodeId"]
        }
      ],
      "authSignals": [
        {
          "provider": "example-image"
        },
        {
          "provider": "example-image-oauth",
          "providerBaseUrl": {
            "provider": "example-image",
            "defaultBaseUrl": "https://api.example.com/v1",
            "allowedBaseUrls": ["https://api.example.com/v1"]
          }
        }
      ]
    }
  }
}
```

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

| فیلد                   | الزامی | نوع        | مفهوم                                                                                                                                          |
| ---------------------- | ------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `aliases`              | خیر    | `string[]` | شناسه‌های اضافی ارائه‌دهنده که باید برای ارائه‌دهنده تولید، نام مستعار ایستای احراز هویت محسوب شوند.                                           |
| `authProviders`        | خیر    | `string[]` | شناسه‌های ارائه‌دهنده‌ای که نمایه‌های احراز هویت پیکربندی‌شده آن‌ها باید برای این ارائه‌دهنده تولید، احراز هویت محسوب شوند.                    |
| `configSignals`        | خیر    | `object[]` | نشانه‌های دسترس‌پذیری کم‌هزینه و صرفاً مبتنی بر پیکربندی برای ارائه‌دهندگان محلی یا خودمیزبانی‌شده که بدون نمایه احراز هویت یا متغیر محیطی پیکربندی می‌شوند. |
| `authSignals`          | خیر    | `object[]` | نشانه‌های صریح احراز هویت. در صورت وجود، این موارد جایگزین مجموعه نشانه پیش‌فرض حاصل از شناسه ارائه‌دهنده، `aliases` و `authProviders` می‌شوند. |
| `referenceAudioInputs` | خیر    | `boolean`  | فقط برای تولید ویدئو. وقتی ارائه‌دهنده دارایی‌های صوتی مرجع را می‌پذیرد، روی `true` تنظیم کنید؛ در غیر این صورت `video_generate` پارامترهای مرجع صوتی را پنهان می‌کند. |

هر ورودی `configSignals` از موارد زیر پشتیبانی می‌کند:

| فیلد             | الزامی | نوع        | مفهوم                                                                                                                                                                                                            |
| ---------------- | ------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rootPath`       | بله    | `string`   | مسیر نقطه‌ای به شیء پیکربندی متعلق به Plugin که باید بررسی شود؛ برای مثال `plugins.entries.example.config`.                                                                                                      |
| `overlayPath`    | خیر    | `string`   | مسیر نقطه‌ای درون پیکربندی ریشه که شیء آن باید پیش از ارزیابی نشانه روی شیء ریشه قرار گیرد. از این گزینه برای پیکربندی ویژه قابلیت‌هایی مانند `image`، `video` یا `music` استفاده کنید.                           |
| `overlayMapPath` | خیر    | `string`   | مسیر نقطه‌ای درون پیکربندی ریشه که هرکدام از مقادیر شیء آن باید روی شیء ریشه قرار گیرند. از این گزینه برای نگاشت‌های حساب نام‌گذاری‌شده مانند `accounts` استفاده کنید که در آن هر حساب پیکربندی‌شده باید واجد شرایط باشد. |
| `required`       | خیر    | `string[]` | مسیرهای نقطه‌ای درون پیکربندی مؤثر که باید دارای مقادیر پیکربندی‌شده باشند. رشته‌ها باید ناتهی باشند؛ اشیا و آرایه‌ها نیز نباید تهی باشند.                                                                       |
| `requiredAny`    | خیر    | `string[]` | مسیرهای نقطه‌ای درون پیکربندی مؤثر که دست‌کم یکی از آن‌ها باید دارای مقدار پیکربندی‌شده باشد.                                                                                                                     |
| `mode`           | خیر    | `object`   | محدودکننده اختیاری حالت رشته‌ای درون پیکربندی مؤثر. وقتی دسترس‌پذیری صرفاً مبتنی بر پیکربندی فقط برای یک حالت کاربرد دارد، از این گزینه استفاده کنید.                                                            |

هر محدودکننده `mode` از موارد زیر پشتیبانی می‌کند:

| فیلد         | الزامی | نوع        | مفهوم                                                                                         |
| ------------ | ------ | ---------- | --------------------------------------------------------------------------------------------- |
| `path`       | خیر    | `string`   | مسیر نقطه‌ای درون پیکربندی مؤثر. مقدار پیش‌فرض `mode` است.                                   |
| `default`    | خیر    | `string`   | مقدار حالت که وقتی مسیر در پیکربندی وجود ندارد استفاده می‌شود.                               |
| `allowed`    | خیر    | `string[]` | در صورت وجود، نشانه فقط زمانی پذیرفته می‌شود که حالت مؤثر یکی از این مقادیر باشد.             |
| `disallowed` | خیر    | `string[]` | در صورت وجود، نشانه زمانی رد می‌شود که حالت مؤثر یکی از این مقادیر باشد.                      |

هر ورودی `authSignals` از موارد زیر پشتیبانی می‌کند:

| فیلد              | الزامی | نوع      | مفهوم                                                                                                                                                                               |
| ----------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider`        | بله    | `string` | شناسه ارائه‌دهنده‌ای که باید در نمایه‌های احراز هویت پیکربندی‌شده بررسی شود.                                                                                                       |
| `providerBaseUrl` | خیر    | `object` | محدودکننده اختیاری که باعث می‌شود نشانه فقط زمانی لحاظ شود که ارائه‌دهنده پیکربندی‌شده مورد ارجاع از یک URL پایه مجاز استفاده کند. وقتی نام مستعار احراز هویت فقط برای APIهای خاص معتبر است، از این گزینه استفاده کنید. |

هر محدودکننده `providerBaseUrl` از موارد زیر پشتیبانی می‌کند:

| فیلد              | الزامی | نوع        | مفهوم                                                                                                                                                     |
| ----------------- | ------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider`        | بله    | `string`   | شناسه پیکربندی ارائه‌دهنده که باید `baseUrl` آن بررسی شود.                                                                                                |
| `defaultBaseUrl`  | خیر    | `string`   | URL پایه‌ای که وقتی `baseUrl` در پیکربندی ارائه‌دهنده وجود ندارد، باید فرض شود.                                                                          |
| `allowedBaseUrls` | بله    | `string[]` | URLهای پایه مجاز برای این نشانه احراز هویت. وقتی URL پایه پیکربندی‌شده یا پیش‌فرض با یکی از این مقادیر نرمال‌شده مطابقت نداشته باشد، نشانه نادیده گرفته می‌شود. |

## مرجع فراداده ابزار

`toolMetadata` از همان ساختارهای `configSignals` و `authSignals` در فراداده ارائه‌دهنده تولید استفاده می‌کند و کلید آن نام ابزار است. `contracts.tools` مالکیت را اعلام می‌کند. `toolMetadata` شواهد کم‌هزینه دسترس‌پذیری را اعلام می‌کند تا OpenClaw فقط برای اینکه کارخانه ابزار آن `null` برگرداند، از واردکردن زمان اجرای Plugin خودداری کند.

```json
{
  "setup": {
    "providers": [
      {
        "id": "example",
        "envVars": ["EXAMPLE_API_KEY"]
      }
    ]
  },
  "contracts": {
    "tools": ["example_search"]
  },
  "toolMetadata": {
    "example_search": {
      "authSignals": [
        {
          "provider": "example"
        }
      ],
      "configSignals": [
        {
          "rootPath": "plugins.entries.example.config",
          "overlayPath": "search",
          "required": ["apiKey"]
        }
      ]
    }
  }
}
```

ورودی‌های `toolMetadata` علاوه بر فیلدهای مشترک `configSignals`/`authSignals` در بالا، `optional` (ابزار را برای فعال‌سازی Plugin غیرالزامی علامت‌گذاری می‌کند) و `replaySafe` (اجرای ابزار را پس از یک نوبت ناقص مدل، برای تکرار ایمن علامت‌گذاری می‌کند) را نیز می‌پذیرند.

اگر ابزاری `toolMetadata` نداشته باشد، OpenClaw رفتار موجود را حفظ می‌کند و هنگامی که قرارداد ابزار با خط‌مشی مطابقت داشته باشد، Plugin مالک را بارگذاری می‌کند. برای ابزارهای مسیر داغ که کارخانه آن‌ها به احراز هویت/پیکربندی وابسته است، نویسندگان Plugin باید به‌جای وادارکردن هسته به واردکردن زمان اجرا برای پرس‌وجو، `toolMetadata` را اعلام کنند.

## مرجع providerAuthChoices

هر ورودی `providerAuthChoices` یک گزینه راه‌اندازی اولیه یا احراز هویت را توصیف می‌کند. OpenClaw این مورد را پیش از بارگذاری زمان اجرای ارائه‌دهنده می‌خواند. فهرست‌های راه‌اندازی ارائه‌دهنده از این گزینه‌های مانیفست، گزینه‌های راه‌اندازی مشتق‌شده از توصیفگر و فراداده catalog نصب استفاده می‌کنند، بدون اینکه زمان اجرای ارائه‌دهنده را بارگذاری کنند.

| فیلد                 | الزامی | نوع                                                                   | مفهوم                                                                                                                         |
| --------------------- | ------ | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `provider`            | بله    | `string`                                                              | شناسهٔ ارائه‌دهنده‌ای که این گزینه به آن تعلق دارد.                                                                            |
| `method`              | بله    | `string`                                                              | شناسهٔ روش احراز هویت که درخواست باید به آن هدایت شود.                                                                         |
| `choiceId`            | بله    | `string`                                                              | شناسهٔ پایدار گزینهٔ احراز هویت که در فرایندهای راه‌اندازی اولیه و CLI استفاده می‌شود.                                         |
| `choiceLabel`         | خیر    | `string`                                                              | برچسب قابل‌نمایش به کاربر. اگر حذف شود، OpenClaw از `choiceId` استفاده می‌کند.                                                  |
| `choiceHint`          | خیر    | `string`                                                              | متن راهنمای کوتاه برای انتخاب‌گر.                                                                                              |
| `assistantPriority`   | خیر    | `number`                                                              | مقادیر کمتر در انتخاب‌گرهای تعاملی هدایت‌شده توسط دستیار، زودتر مرتب می‌شوند.                                                   |
| `assistantVisibility` | خیر    | `"visible"` \| `"manual-only"`                                        | گزینه را از انتخاب‌گرهای دستیار پنهان می‌کند، درحالی‌که انتخاب دستی آن از طریق CLI همچنان مجاز است.                             |
| `deprecatedChoiceIds` | خیر    | `string[]`                                                            | شناسه‌های قدیمی گزینه که باید کاربران را به این گزینهٔ جایگزین هدایت کنند.                                                      |
| `groupId`             | خیر    | `string`                                                              | شناسهٔ اختیاری گروه برای دسته‌بندی گزینه‌های مرتبط.                                                                            |
| `groupLabel`          | خیر    | `string`                                                              | برچسب قابل‌نمایش به کاربر برای آن گروه.                                                                                         |
| `groupHint`           | خیر    | `string`                                                              | متن راهنمای کوتاه برای گروه.                                                                                                   |
| `onboardingFeatured`  | خیر    | `boolean`                                                             | این گروه را پیش از ورودی «بیشتر...» در ردهٔ ویژهٔ انتخاب‌گر تعاملی راه‌اندازی اولیه نمایش می‌دهد.                               |
| `optionKey`           | خیر    | `string`                                                              | کلید داخلی گزینه برای فرایندهای سادهٔ احراز هویت تک‌پرچمی.                                                                      |
| `cliFlag`             | خیر    | `string`                                                              | نام پرچم CLI، مانند `--openrouter-api-key`.                                                                                     |
| `cliOption`           | خیر    | `string`                                                              | ساختار کامل گزینهٔ CLI، مانند `--openrouter-api-key <key>`.                                                                     |
| `cliDescription`      | خیر    | `string`                                                              | توضیحی که در راهنمای CLI استفاده می‌شود.                                                                                        |
| `onboardingScopes`    | خیر    | `Array<"text-inference" \| "image-generation" \| "music-generation">` | مشخص می‌کند این گزینه در کدام بخش‌های راه‌اندازی اولیه نمایش داده شود. اگر حذف شود، مقدار پیش‌فرض آن `["text-inference"]` است. |

## مرجع `commandAliases`

وقتی یک plugin مالک نام یک فرمان زمان اجراست که ممکن است کاربران آن را به‌اشتباه در `plugins.allow` قرار دهند یا بکوشند آن را به‌عنوان فرمان ریشهٔ CLI اجرا کنند، از `commandAliases` استفاده کنید. OpenClaw بدون وارد کردن کد زمان اجرای plugin، از این فراداده برای عیب‌یابی استفاده می‌کند.

```json
{
  "commandAliases": [
    {
      "name": "dreaming",
      "kind": "runtime-slash",
      "cliCommand": "memory"
    }
  ]
}
```

| فیلد         | الزامی | نوع               | مفهوم                                                                        |
| ------------ | ------ | ----------------- | ---------------------------------------------------------------------------- |
| `name`       | بله    | `string`          | نام فرمانی که به این plugin تعلق دارد.                                        |
| `kind`       | خیر    | `"runtime-slash"` | نام مستعار را به‌جای فرمان ریشهٔ CLI، به‌عنوان فرمان اسلش در گفت‌وگو مشخص می‌کند. |
| `cliCommand` | خیر    | `string`          | فرمان ریشهٔ مرتبط CLI که در صورت وجود، برای عملیات CLI پیشنهاد می‌شود.         |

## مرجع `activation`

وقتی plugin می‌تواند با هزینهٔ اندک اعلام کند که کدام رویدادهای صفحهٔ کنترل باید آن را در طرح فعال‌سازی/بارگذاری بگنجانند، از `activation` استفاده کنید.

این بلوک فرادادهٔ برنامه‌ریز است، نه API چرخهٔ حیات. رفتار زمان اجرا را ثبت نمی‌کند، جایگزین `register(...)` نمی‌شود و تضمین نمی‌کند که کد plugin از قبل اجرا شده باشد. برنامه‌ریز فعال‌سازی از این فیلدها برای محدود کردن pluginهای نامزد استفاده می‌کند و سپس در صورت نیاز به فرادادهٔ مالکیت موجود در مانیفست، مانند `providers`، `channels`، `commandAliases`، `setup.providers`، `contracts.tools` و hookها بازمی‌گردد.

محدودترین فراداده‌ای را ترجیح دهید که از قبل مالکیت را توصیف می‌کند. وقتی فیلدهای `providers`، `channels`، `commandAliases`، توصیف‌گرهای راه‌اندازی یا `contracts` این رابطه را بیان می‌کنند، از آن‌ها استفاده کنید. برای راهنمایی‌های اضافی برنامه‌ریز که با آن فیلدهای مالکیت قابل بیان نیستند، از `activation` استفاده کنید. برای نام‌های مستعار زمان اجرای CLI مانند `claude-cli`، `my-cli` یا `google-gemini-cli` از `cliBackends` سطح‌بالا استفاده کنید؛ `activation.onAgentHarnesses` فقط برای شناسه‌های چارچوب عامل تعبیه‌شده‌ای است که از قبل فیلد مالکیتی ندارند.

هر plugin باید `activation.onStartup` را آگاهانه تنظیم کند. فقط زمانی آن را روی `true` قرار دهید که plugin باید هنگام راه‌اندازی Gateway اجرا شود. وقتی plugin هنگام راه‌اندازی غیرفعال است و باید فقط بر اساس محرک‌های محدودتر بارگذاری شود، آن را روی `false` قرار دهید. حذف `onStartup` دیگر باعث بارگذاری ضمنی plugin هنگام راه‌اندازی نمی‌شود؛ برای راه‌اندازی، کانال، پیکربندی، چارچوب عامل، حافظه یا دیگر محرک‌های محدودتر فعال‌سازی، از فرادادهٔ فعال‌سازی صریح استفاده کنید.

```json
{
  "activation": {
    "onStartup": false,
    "onProviders": ["openai"],
    "onCommands": ["models"],
    "onChannels": ["web"],
    "onRoutes": ["gateway-webhook"],
    "onConfigPaths": ["browser"],
    "onCapabilities": ["provider", "tool"]
  }
}
```

| فیلد               | الزامی | نوع                                                  | مفهوم                                                                                                                                                                                                        |
| ------------------ | ------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `onStartup`        | خیر    | `boolean`                                            | فعال‌سازی صریح هنگام راه‌اندازی Gateway. هر plugin باید این فیلد را تنظیم کند. `true` هنگام راه‌اندازی plugin را وارد می‌کند؛ `false` آن را هنگام راه‌اندازی به‌صورت تنبل نگه می‌دارد، مگر اینکه محرک منطبق دیگری بارگذاری را ضروری کند. |
| `onProviders`      | خیر    | `string[]`                                           | شناسه‌های ارائه‌دهنده‌ای که باید این plugin را در طرح‌های فعال‌سازی/بارگذاری بگنجانند.                                                                                                                         |
| `onAgentHarnesses` | خیر    | `string[]`                                           | شناسه‌های زمان اجرای چارچوب عامل تعبیه‌شده که باید این plugin را در طرح‌های فعال‌سازی/بارگذاری بگنجانند. برای نام‌های مستعار پشتیبان CLI از `cliBackends` سطح‌بالا استفاده کنید.                                 |
| `onCommands`       | خیر    | `string[]`                                           | شناسه‌های فرمانی که باید این plugin را در طرح‌های فعال‌سازی/بارگذاری بگنجانند.                                                                                                                                |
| `onChannels`       | خیر    | `string[]`                                           | شناسه‌های کانالی که باید این plugin را در طرح‌های فعال‌سازی/بارگذاری بگنجانند.                                                                                                                                |
| `onRoutes`         | خیر    | `string[]`                                           | انواع مسیری که باید این plugin را در طرح‌های فعال‌سازی/بارگذاری بگنجانند.                                                                                                                                     |
| `onConfigPaths`    | خیر    | `string[]`                                           | مسیرهای پیکربندی نسبی به ریشه که در صورت وجود مسیر و غیرفعال نبودن صریح آن، باید این plugin را در طرح‌های راه‌اندازی/بارگذاری بگنجانند.                                                                          |
| `onCapabilities`   | خیر    | `Array<"provider" \| "channel" \| "tool" \| "hook">` | راهنمایی‌های کلی قابلیت که در برنامه‌ریزی فعال‌سازی صفحهٔ کنترل استفاده می‌شوند. در صورت امکان، فیلدهای محدودتر را ترجیح دهید.                                                                                   |

مصرف‌کنندگان فعال کنونی:

- برنامه‌ریزی راه‌اندازی Gateway برای وارد کردن صریح هنگام راه‌اندازی از `activation.onStartup` استفاده می‌کند.
- برنامه‌ریزی CLI که با فرمان فعال می‌شود، به `commandAliases[].cliCommand` یا `commandAliases[].name` قدیمی بازمی‌گردد.
- برنامه‌ریزی راه‌اندازی زمان اجرای عامل، برای چارچوب‌های تعبیه‌شده از `activation.onAgentHarnesses` و برای نام‌های مستعار زمان اجرای CLI از `cliBackends[]` سطح‌بالا استفاده می‌کند.
- برنامه‌ریزی راه‌اندازی/کانال که با کانال فعال می‌شود، در صورت نبود فرادادهٔ صریح فعال‌سازی کانال به مالکیت قدیمی `channels[]` بازمی‌گردد.
- برنامه‌ریزی plugin هنگام راه‌اندازی، برای بخش‌های پیکربندی ریشه‌ای غیرکانالی مانند بلوک `browser` در plugin مرورگر همراه، از `activation.onConfigPaths` استفاده می‌کند.
- برنامه‌ریزی راه‌اندازی/زمان اجرا که با ارائه‌دهنده فعال می‌شود، در صورت نبود فرادادهٔ صریح فعال‌سازی ارائه‌دهنده به مالکیت قدیمی `providers[]` و `cliBackends[]` سطح‌بالا بازمی‌گردد.

عیب‌یابی برنامه‌ریز می‌تواند راهنمایی‌های صریح فعال‌سازی را از بازگشت به مالکیت مانیفست متمایز کند. برای مثال، `activation-command-hint` یعنی `activation.onCommands` منطبق شده است، درحالی‌که `manifest-command-alias` یعنی برنامه‌ریز به‌جای آن از مالکیت `commandAliases` استفاده کرده است. این برچسب‌های دلیل برای عیب‌یابی میزبان و آزمون‌ها هستند؛ نویسندگان plugin باید همچنان فراداده‌ای را اعلام کنند که مالکیت را به بهترین شکل توصیف می‌کند.

## مرجع `qaRunners`

وقتی یک plugin یک یا چند اجراکنندهٔ انتقال را زیر ریشهٔ مشترک `openclaw qa`
ارائه می‌کند، از `qaRunners` استفاده کنید. این فراداده را سبک و ایستا نگه دارید؛ زمان اجرای
plugin همچنان ثبت واقعی CLI را از طریق سطح سبک‌وزن `runtime-api.ts` که
`qaRunnerCliRegistrations` منطبق را صادر می‌کند، در اختیار دارد. یک
`adapterFactory` اختیاری، بدون تغییر اجراکنندهٔ فرمان ثبت‌شده، انتقال را در اختیار
سناریوهای مشترک تضمین کیفیت قرار می‌دهد.

```json
{
  "qaRunners": [
    {
      "commandName": "matrix",
      "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver"
    }
  ]
}
```

| فیلد          | الزامی | نوع      | مفهوم                                                                                 |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------- |
| `commandName` | بله    | `string` | زیرفرمانی که زیر `openclaw qa` سوار می‌شود؛ برای مثال `matrix`.                        |
| `description` | خیر    | `string` | متن راهنمای جایگزین که وقتی میزبان مشترک به یک فرمان جای‌نگهدار نیاز دارد، استفاده می‌شود. |

شناسهٔ `adapterFactory` باید با `commandName` مطابقت داشته باشد. برای فرمان‌هایی که در مانیفست وجود ندارند، ثبت‌ها را صادر نکنید.

## مرجع setup

هنگامی از `setup` استفاده کنید که بخش‌های راه‌اندازی و ورود اولیه، پیش از بارگذاری زمان اجرا، به فرادادهٔ کم‌هزینه و تحت مالکیت Plugin نیاز دارند.

```json
{
  "setup": {
    "providers": [
      {
        "id": "openai",
        "authMethods": ["api-key"],
        "envVars": ["OPENAI_API_KEY"],
        "authEvidence": [
          {
            "type": "local-file-with-env",
            "fileEnvVar": "OPENAI_CREDENTIALS_FILE",
            "requiresAllEnv": ["OPENAI_PROJECT"],
            "credentialMarker": "openai-local-credentials",
            "source": "openai local credentials"
          }
        ]
      }
    ],
    "cliBackends": ["openai-cli"],
    "configMigrations": ["legacy-openai-auth"],
    "requiresRuntime": false
  }
}
```

`cliBackends` سطح بالا همچنان معتبر است و به توصیف بک‌اندهای استنتاج CLI ادامه می‌دهد. `setup.cliBackends` سطح توصیف‌گر مختص راه‌اندازی برای جریان‌های صفحهٔ کنترل/راه‌اندازی است که باید صرفاً مبتنی بر فراداده باقی بمانند.

در صورت وجود، `setup.providers` و `setup.cliBackends` سطح ترجیحیِ جست‌وجوی توصیف‌گرمحور برای کشف راه‌اندازی هستند. اگر توصیف‌گر فقط Plugin نامزد را محدود می‌کند و راه‌اندازی همچنان به هوک‌های غنی‌تر زمان اجرا در زمان راه‌اندازی نیاز دارد، `requiresRuntime: true` را تنظیم کنید و `setup-api` را به‌عنوان مسیر اجرایی جایگزین حفظ کنید.

OpenClaw همچنین `setup.providers[].envVars` را در جست‌وجوهای عمومی احراز هویت ارائه‌دهنده و متغیرهای محیطی لحاظ می‌کند. `providerAuthEnvVars` در طول دورهٔ منسوخ‌سازی از طریق یک سازگارکنندهٔ سازگاری همچنان پشتیبانی می‌شود، اما Pluginهای غیربسته‌ای که هنوز از آن استفاده می‌کنند، یک عیب‌یابی مانیفست دریافت می‌کنند. Pluginهای جدید باید فرادادهٔ محیطی راه‌اندازی/وضعیت را در `setup.providers[].envVars` قرار دهند.

هنگامی از `providerUsageAuthEnvVars` استفاده کنید که یک اعتبارنامهٔ سطح صورت‌حساب یا سازمان باید `resolveUsageAuth` را فعال کند، بی‌آنکه به اعتبارنامهٔ استنتاج تبدیل شود. این نام‌ها به مسدودسازی dotenv فضای کاری، حذف از فرایند فرزند ACP، پالایش اسرار در جعبهٔ شنی و پاک‌سازی گستردهٔ اسرار افزوده می‌شوند. زمان اجرای ارائه‌دهنده همچنان مقدار را درون `resolveUsageAuth` می‌خواند و طبقه‌بندی می‌کند.

OpenClaw همچنین می‌تواند هنگامی که هیچ ورودی راه‌اندازی در دسترس نیست، یا وقتی `setup.requiresRuntime: false` غیرضروری بودن زمان اجرای راه‌اندازی را اعلام می‌کند، گزینه‌های سادهٔ راه‌اندازی را از `setup.providers[].authMethods` استخراج کند. ورودی‌های صریح `providerAuthChoices` برای برچسب‌های سفارشی، پرچم‌های CLI، دامنهٔ ورود اولیه و فرادادهٔ دستیار همچنان ترجیح داده می‌شوند.

فقط زمانی `requiresRuntime: false` را تنظیم کنید که این توصیف‌گرها برای سطح راه‌اندازی کافی باشند. OpenClaw مقدار صریح `false` را یک قرارداد صرفاً توصیف‌گرمحور تلقی می‌کند و برای جست‌وجوی راه‌اندازی، `setup-api` یا `openclaw.setupEntry` را اجرا نخواهد کرد. اگر یک Plugin صرفاً توصیف‌گرمحور همچنان یکی از این ورودی‌های زمان اجرای راه‌اندازی را ارائه کند، OpenClaw یک عیب‌یابی افزوده گزارش می‌دهد و به نادیده گرفتن آن ادامه می‌دهد. حذف `requiresRuntime` رفتار جایگزین قدیمی را حفظ می‌کند تا Pluginهای موجودی که توصیف‌گرها را بدون این پرچم افزوده‌اند، خراب نشوند.

از آنجا که جست‌وجوی راه‌اندازی می‌تواند کد `setup-api` تحت مالکیت Plugin را اجرا کند، مقادیر نرمال‌شدهٔ `setup.providers[].id` و `setup.cliBackends[]` باید در میان Pluginهای کشف‌شده یکتا باقی بمانند. در صورت ابهام مالکیت، عملیات به‌صورت بسته شکست می‌خورد و برنده‌ای بر اساس ترتیب کشف انتخاب نمی‌شود.

هنگامی که زمان اجرای راه‌اندازی اجرا می‌شود، اگر `setup-api` ارائه‌دهنده یا بک‌اند CLIای را ثبت کند که توصیف‌گرهای مانیفست آن را اعلام نکرده‌اند، یا اگر توصیف‌گری ثبت متناظر زمان اجرا نداشته باشد، عیب‌یابی‌های رجیستری راه‌اندازی ناهماهنگی توصیف‌گر را گزارش می‌کنند. این عیب‌یابی‌ها افزوده هستند و Pluginهای قدیمی را رد نمی‌کنند.

### مرجع setup.providers

| فیلد           | الزامی | نوع        | مفهوم                                                                                                 |
| -------------- | ------ | ---------- | ----------------------------------------------------------------------------------------------------- |
| `id`           | بله    | `string`   | شناسهٔ ارائه‌دهنده که هنگام راه‌اندازی یا ورود اولیه در معرض قرار می‌گیرد. شناسه‌های نرمال‌شده را در سطح سراسری یکتا نگه دارید. |
| `authMethods`  | خیر    | `string[]` | شناسه‌های روش راه‌اندازی/احراز هویت که این ارائه‌دهنده بدون بارگذاری کامل زمان اجرا پشتیبانی می‌کند. |
| `envVars`      | خیر    | `string[]` | متغیرهای محیطی که بخش‌های عمومی راه‌اندازی/وضعیت می‌توانند پیش از بارگذاری زمان اجرای Plugin بررسی کنند. |
| `authEvidence` | خیر    | `object[]` | بررسی‌های کم‌هزینهٔ شواهد احراز هویت محلی برای ارائه‌دهندگانی که می‌توانند از طریق نشانگرهای غیرمحرمانه احراز هویت کنند. |

`authEvidence` برای نشانگرهای اعتبارنامهٔ محلی تحت مالکیت ارائه‌دهنده است که می‌توان آن‌ها را بدون بارگذاری کد زمان اجرا تأیید کرد. این بررسی‌ها باید کم‌هزینه و محلی باقی بمانند: بدون فراخوانی شبکه، بدون خواندن از جاکلیدی یا مدیر اسرار، بدون فرمان پوسته و بدون کاوش API ارائه‌دهنده.

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

| فیلد               | الزامی | نوع        | مفهوم                                                                                                          |
| ------------------ | ------ | ---------- | -------------------------------------------------------------------------------------------------------------- |
| `type`             | بله    | `string`   | در حال حاضر `local-file-with-env`.                                                                             |
| `fileEnvVar`       | خیر    | `string`   | متغیر محیطی حاوی مسیر صریح فایل اعتبارنامه.                                                                    |
| `fallbackPaths`    | خیر    | `string[]` | مسیرهای فایل اعتبارنامهٔ محلی که هنگام نبودن یا خالی بودن `fileEnvVar` بررسی می‌شوند. از `${HOME}` و `${APPDATA}` پشتیبانی می‌کند. |
| `requiresAnyEnv`   | خیر    | `string[]` | پیش از معتبر شدن شواهد، دست‌کم یکی از متغیرهای محیطی فهرست‌شده باید خالی نباشد.                                |
| `requiresAllEnv`   | خیر    | `string[]` | پیش از معتبر شدن شواهد، همهٔ متغیرهای محیطی فهرست‌شده باید خالی نباشند.                                       |
| `credentialMarker` | بله    | `string`   | نشانگر غیرمحرمانه‌ای که هنگام وجود شواهد بازگردانده می‌شود.                                                    |
| `source`           | خیر    | `string`   | برچسب منبع قابل‌نمایش به کاربر برای خروجی احراز هویت/وضعیت.                                                    |

### فیلدهای setup

| فیلد               | الزامی | نوع        | مفهوم                                                                                                  |
| ------------------ | ------ | ---------- | ------------------------------------------------------------------------------------------------------ |
| `providers`        | خیر    | `object[]` | توصیف‌گرهای راه‌اندازی ارائه‌دهنده که هنگام راه‌اندازی و ورود اولیه در معرض قرار می‌گیرند.              |
| `cliBackends`      | خیر    | `string[]` | شناسه‌های بک‌اند زمان راه‌اندازی که برای جست‌وجوی راه‌اندازی توصیف‌گرمحور استفاده می‌شوند. شناسه‌های نرمال‌شده را در سطح سراسری یکتا نگه دارید. |
| `configMigrations` | خیر    | `string[]` | شناسه‌های مهاجرت پیکربندی تحت مالکیت سطح راه‌اندازی این Plugin.                                        |
| `requiresRuntime`  | خیر    | `boolean`  | اینکه آیا راه‌اندازی پس از جست‌وجوی توصیف‌گر همچنان به اجرای `setup-api` نیاز دارد یا نه.               |

## مرجع uiHints

`uiHints` نگاشتی از نام فیلدهای پیکربندی به راهنمایی‌های کوچک رندر است. کلیدها می‌توانند برای فیلدهای پیکربندی تودرتو از نقطه استفاده کنند، اما هیچ بخش مسیر نباید `__proto__`، `constructor` یا `prototype` باشد؛ راه‌اندازی این نام‌ها را رد می‌کند.

```json
{
  "uiHints": {
    "apiKey": {
      "label": "API key",
      "help": "Used for OpenRouter requests",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  }
}
```

هر راهنمای فیلد می‌تواند شامل موارد زیر باشد:

| فیلد          | نوع        | مفهوم                                  |
| ------------- | ---------- | -------------------------------------- |
| `label`       | `string`   | برچسب فیلد قابل‌نمایش به کاربر.        |
| `help`        | `string`   | متن راهنمای کوتاه.                     |
| `tags`        | `string[]` | برچسب‌های اختیاری رابط کاربری.         |
| `advanced`    | `boolean`  | فیلد را به‌عنوان پیشرفته علامت می‌زند. |
| `sensitive`   | `boolean`  | فیلد را محرمانه یا حساس علامت می‌زند.  |
| `placeholder` | `string`   | متن جای‌نگهدار برای ورودی‌های فرم.     |

## مرجع contracts

فقط برای فرادادهٔ ایستای مالکیت قابلیت که OpenClaw می‌تواند بدون وارد کردن زمان اجرای Plugin بخواند، از `contracts` استفاده کنید.

```json
{
  "contracts": {
    "agentToolResultMiddleware": ["openclaw", "codex"],
    "trustedToolPolicies": ["workflow-budget"],
    "externalAuthProviders": ["acme-ai"],
    "embeddingProviders": ["openai-compatible"],
    "speechProviders": ["openai"],
    "realtimeTranscriptionProviders": ["openai"],
    "realtimeVoiceProviders": ["openai"],
    "memoryEmbeddingProviders": ["local"],
    "mediaUnderstandingProviders": ["openai"],
    "imageGenerationProviders": ["openai"],
    "videoGenerationProviders": ["qwen"],
    "musicGenerationProviders": ["stability-audio"],
    "documentExtractors": ["example-docs"],
    "webContentExtractors": ["firecrawl"],
    "webFetchProviders": ["firecrawl"],
    "webSearchProviders": ["gemini"],
    "workerProviders": ["example-worker"],
    "usageProviders": ["acme-ai"],
    "migrationProviders": ["hermes"],
    "gatewayMethodDispatch": ["authenticated-request"],
    "tools": ["firecrawl_search", "firecrawl_scrape"]
  }
}
```

هر فهرست اختیاری است:

| فیلد                            | نوع        | مفهوم                                                                                                                                    |
| -------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `embeddedExtensionFactories`     | `string[]` | شناسه‌های کارخانهٔ افزونهٔ app-server مربوط به Codex، که در حال حاضر `codex-app-server` است.                                              |
| `agentToolResultMiddleware`      | `string[]` | شناسه‌های زمان اجرایی که این Plugin می‌تواند میان‌افزار نتیجهٔ ابزار را برای آن‌ها ثبت کند.                                               |
| `trustedToolPolicies`            | `string[]` | شناسه‌های سیاست مورد اعتمادِ محلی Plugin پیش از اجرای ابزار که یک Plugin نصب‌شده می‌تواند ثبت کند. Pluginهای همراه می‌توانند بدون این فیلد سیاست ثبت کنند. |
| `externalAuthProviders`          | `string[]` | شناسه‌های ارائه‌دهنده‌ای که قلاب پروفایل احراز هویت خارجی آن‌ها در مالکیت این Plugin است.                                                 |
| `embeddingProviders`             | `string[]` | شناسه‌های ارائه‌دهندهٔ عمومی تعبیه‌سازی که برای استفادهٔ مجدد از تعبیه‌سازی برداری، از جمله حافظه، در مالکیت این Plugin هستند.               |
| `speechProviders`                | `string[]` | شناسه‌های ارائه‌دهندهٔ گفتار که در مالکیت این Plugin هستند.                                                                              |
| `realtimeTranscriptionProviders` | `string[]` | شناسه‌های ارائه‌دهندهٔ رونویسی بلادرنگ که در مالکیت این Plugin هستند.                                                                    |
| `realtimeVoiceProviders`         | `string[]` | شناسه‌های ارائه‌دهندهٔ صدای بلادرنگ که در مالکیت این Plugin هستند.                                                                       |
| `memoryEmbeddingProviders`       | `string[]` | شناسه‌های منسوخ‌شدهٔ ارائه‌دهندهٔ تعبیه‌سازی ویژهٔ حافظه که در مالکیت این Plugin هستند.                                                   |
| `mediaUnderstandingProviders`    | `string[]` | شناسه‌های ارائه‌دهندهٔ درک رسانه که در مالکیت این Plugin هستند.                                                                          |
| `transcriptSourceProviders`      | `string[]` | شناسه‌های ارائه‌دهندهٔ منبع رونویسی که در مالکیت این Plugin هستند.                                                                       |
| `documentExtractors`             | `string[]` | شناسه‌های ارائه‌دهندهٔ استخراج‌کنندهٔ سند، برای مثال PDF، که در مالکیت این Plugin هستند.                                                  |
| `imageGenerationProviders`       | `string[]` | شناسه‌های ارائه‌دهندهٔ تولید تصویر که در مالکیت این Plugin هستند.                                                                        |
| `videoGenerationProviders`       | `string[]` | شناسه‌های ارائه‌دهندهٔ تولید ویدئو که در مالکیت این Plugin هستند.                                                                        |
| `musicGenerationProviders`       | `string[]` | شناسه‌های ارائه‌دهندهٔ تولید موسیقی که در مالکیت این Plugin هستند.                                                                       |
| `webContentExtractors`           | `string[]` | شناسه‌های ارائه‌دهندهٔ استخراج محتوای صفحهٔ وب که در مالکیت این Plugin هستند.                                                            |
| `webFetchProviders`              | `string[]` | شناسه‌های ارائه‌دهندهٔ واکشی وب که در مالکیت این Plugin هستند.                                                                           |
| `webSearchProviders`             | `string[]` | شناسه‌های ارائه‌دهندهٔ جست‌وجوی وب که در مالکیت این Plugin هستند.                                                                        |
| `workerProviders`                | `string[]` | شناسه‌های ارائه‌دهندهٔ کارگر ابری که برای تأمین و چرخهٔ عمر اجارهٔ مبتنی بر پروفایل در مالکیت این Plugin هستند.                            |
| `usageProviders`                 | `string[]` | شناسه‌های ارائه‌دهنده‌ای که قلاب‌های احراز هویت مصرف و تصویر لحظه‌ای مصرف آن‌ها در مالکیت این Plugin است.                                 |
| `migrationProviders`             | `string[]` | شناسه‌های ارائه‌دهندهٔ واردسازی که برای `openclaw migrate` در مالکیت این Plugin هستند.                                                    |
| `gatewayMethodDispatch`          | `string[]` | مجوز محفوظ برای مسیرهای HTTP احرازشدهٔ Plugin که متدهای Gateway را درون‌فرایندی فراخوانی می‌کنند.                                         |
| `tools`                          | `string[]` | نام ابزارهای عامل که در مالکیت این Plugin هستند.                                                                                         |

`contracts.embeddedExtensionFactories` برای کارخانه‌های افزونهٔ همراه که فقط مختص app-server مربوط به Codex هستند، حفظ شده است. تبدیل‌های همراهِ نتیجهٔ ابزار باید در عوض `contracts.agentToolResultMiddleware` را اعلام و با `api.registerAgentToolResultMiddleware(...)` ثبت کنند. Pluginهای نصب‌شده تنها در صورتی می‌توانند از همین درگاه میان‌افزار استفاده کنند که به‌صراحت فعال شده باشند و فقط برای زمان‌های اجرایی که در `contracts.agentToolResultMiddleware` اعلام می‌کنند.

Pluginهای نصب‌شده‌ای که به لایهٔ سیاست مورد اعتماد میزبان پیش از اجرای ابزار نیاز دارند، باید هر شناسهٔ محلی ثبت‌شده را در `contracts.trustedToolPolicies` اعلام کنند و به‌صراحت فعال شوند. Pluginهای همراه مسیر موجود سیاست مورد اعتماد را حفظ می‌کنند، اما Pluginهای نصب‌شده با شناسه‌های سیاست اعلام‌نشده پیش از ثبت رد می‌شوند. دامنهٔ شناسه‌های سیاست به Plugin ثبت‌کننده محدود است؛ بنابراین دو Plugin می‌توانند هر دو `workflow-budget` را اعلام و ثبت کنند، اما یک Plugin نمی‌تواند یک شناسهٔ محلی را دو بار ثبت کند.

ثبت‌های زمان اجرای `api.registerTool(...)` باید با `contracts.tools` مطابقت داشته باشند. کشف ابزار از این فهرست استفاده می‌کند تا فقط زمان‌های اجرای Pluginهایی را بارگذاری کند که می‌توانند مالک ابزارهای درخواستی باشند.

Pluginهای ارائه‌دهنده‌ای که `resolveExternalAuthProfiles` را پیاده‌سازی می‌کنند باید `contracts.externalAuthProviders` را اعلام کنند؛ قلاب‌های احراز هویت خارجی اعلام‌نشده نادیده گرفته می‌شوند.

Pluginهای ارائه‌دهنده‌ای که هم `resolveUsageAuth` و هم `fetchUsageSnapshot` را پیاده‌سازی می‌کنند، باید هر شناسهٔ ارائه‌دهندهٔ کشف‌شدهٔ خودکار را در `contracts.usageProviders` اعلام کنند. کشف مصرف، پیش از بارگذاری کد زمان اجرا این قرارداد را می‌خواند و سپس، پس از بارگذاری فقط مالکان اعلام‌شده، وجود هر دو قلاب را تأیید می‌کند.

ارائه‌دهندگان عمومی تعبیه‌سازی باید برای هر آداپتور ثبت‌شده با `api.registerEmbeddingProvider(...)`، `contracts.embeddingProviders` را اعلام کنند. برای تولید بردار قابل استفادهٔ مجدد، از جمله ارائه‌دهندگانی که جست‌وجوی حافظه از آن‌ها استفاده می‌کند، از قرارداد عمومی استفاده کنید. `contracts.memoryEmbeddingProviders` سازگاری منسوخ‌شدهٔ ویژهٔ حافظه است و فقط تا زمانی باقی می‌ماند که ارائه‌دهندگان موجود به درگاه عمومی ارائه‌دهندهٔ تعبیه‌سازی مهاجرت کنند.

ارائه‌دهندگان کارگر باید هر شناسهٔ `api.registerWorkerProvider(...)` را در `contracts.workerProviders` اعلام کنند. هسته پیش از فراخوانی `provision` قصد پایدار را ذخیره می‌کند؛ ارائه‌دهندگان تنظیمات خود را پیش از تخصیص خارجی اعتبارسنجی می‌کنند و فراخوانی‌های تکراری با شناسهٔ عملیات یکسان باید همان اجاره را به‌کار گیرند. هسته همچنین تصویر لحظه‌ای تنظیمات اعتبارسنجی‌شده را ذخیره می‌کند و آن را همراه با `leaseId` به `inspect({ leaseId, profile })` و `destroy({ leaseId, profile })` می‌فرستد؛ حتی پس از تغییر یا حذف پروفایل نام‌گذاری‌شده. تخریب هم‌توان است، بازرسی یکی از وضعیت‌های مجموعهٔ بستهٔ `active` / `destroyed` / `unknown` را برمی‌گرداند و به محتوای کلید خصوصی SSH فقط از طریق `SecretRef` ارجاع داده می‌شود. نقاط پایانی SSH تأمین‌شده باید یک `hostKey` عمومی از خروجی تأمین مورد اعتماد نیز دقیقاً با قالب `algorithm base64` و بدون نام میزبان یا توضیح داشته باشند تا هسته بتواند پیش از اتصال، میزبان را سنجاق کند. ارائه‌دهندگانی که ارجاع‌های هویت پویا صادر می‌کنند می‌توانند `resolveSshIdentity({ leaseId, profile, keyRef })` معتبر را پیاده‌سازی کنند؛ ارائه‌دهندگان فاقد آن از حل‌کنندهٔ عمومی راز هسته استفاده می‌کنند. پاسخ معتبر `unknown` یک رکورد محلی فعال را بی‌صاحب می‌کند؛ پس از درخواست تخریب ذخیره‌شده، این پاسخ برچیده‌شدن را تأیید می‌کند.

`contracts.gatewayMethodDispatch` در حال حاضر `"authenticated-request"` را می‌پذیرد. این یک دروازهٔ پاکیزگی API برای مسیرهای HTTP بومی Plugin است که عمداً متدهای صفحهٔ کنترل Gateway را درون‌فرایندی فراخوانی می‌کنند، نه یک محیط ایزوله در برابر Pluginهای بومی مخرب. از آن فقط برای سطوح همراه یا عملیاتی که با دقت بازبینی شده‌اند و از قبل به احراز هویت HTTP در Gateway نیاز دارند استفاده کنید. هنگامی که پذیرش کار ریشه در Gateway بسته است، یک مسیر دارای مجوز فقط وقتی همچنان قابل دسترسی می‌ماند که `auth: "gateway"` و مقدار ویژهٔ مسیرِ `gatewayRuntimeScopeSurface: "trusted-operator"` را نیز اعلام کند؛ مسیرهای هم‌ردهٔ عادی از همان Plugin همچنان پشت مرز پذیرش باقی می‌مانند. این کار وضعیت تعلیق و ازسرگیری را بدون اعطای امکان دورزدن پذیرش به کل Plugin، قابل دسترسی نگه می‌دارد. تجزیه و شکل‌دهی پاسخ را به‌صورت محدود خارج از فراخوانی نگه دارید؛ کار اساسی یا تغییردهنده باید از طریق فراخوانی متد Gateway انجام شود که مالک اعمال پذیرش و دامنه است.

## مرجع configContracts

برای رفتار پیکربندی تحت مالکیت مانیفست که کمک‌تابع‌های عمومی هسته بدون واردکردن زمان اجرای Plugin به آن نیاز دارند، از `configContracts` استفاده کنید: تشخیص پرچم خطرناک، اهداف مهاجرت `SecretRef` و محدودسازی مسیر پیکربندی قدیمی.

```json
{
  "configContracts": {
    "compatibilityMigrationPaths": ["legacyProvider"],
    "compatibilityRuntimePaths": ["legacyProvider.webhook"],
    "dangerousFlags": [
      {
        "path": "accounts.*.allowUnverifiedSenders",
        "equals": true
      }
    ],
    "secretInputs": {
      "bundledDefaultEnabled": false,
      "paths": [
        {
          "path": "apiKey",
          "expected": "string"
        }
      ]
    }
  }
}
```

| فیلد                          | الزامی | نوع        | مفهوم                                                                                                                                                                                                                                    |
| ----------------------------- | ------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `compatibilityMigrationPaths` | خیر    | `string[]` | مسیرهای پیکربندی نسبی به ریشه که نشان می‌دهند مهاجرت‌های سازگاری زمان راه‌اندازی این Plugin ممکن است اعمال شوند. به خواندن‌های عمومی پیکربندی زمان اجرا اجازه می‌دهد وقتی پیکربندی هرگز به Plugin ارجاع نمی‌دهد، از همهٔ سطوح راه‌اندازی Plugin صرف‌نظر کنند. |
| `compatibilityRuntimePaths`   | خیر    | `string[]` | مسیرهای سازگاری نسبی به ریشه که این Plugin می‌تواند پیش از فعال‌شدن کامل کد Plugin در زمان اجرا ارائه دهد. از این مورد برای سطوح قدیمی استفاده کنید که باید مجموعه‌های نامزد همراه را بدون واردکردن زمان اجرای همهٔ Pluginهای سازگار محدود کنند. |
| `dangerousFlags`              | خیر    | `object[]` | مقادیر ثابت پیکربندی که `openclaw doctor` باید هنگام فعال‌بودن، آن‌ها را ناامن یا خطرناک علامت‌گذاری کند. به بخش زیر مراجعه کنید.                                                                                                          |
| `secretInputs`                | خیر    | `object`   | مسیرهای پیکربندی زیر `plugins.entries.<id>.config` که ثبت اهداف مهاجرت/ممیزی `SecretRef` باید با آن‌ها به‌عنوان رشته‌هایی با ساختار راز برخورد کند. به بخش زیر مراجعه کنید.                                                                |

هر ورودی `dangerousFlags` از موارد زیر پشتیبانی می‌کند:

| فیلد     | الزامی | نوع                                   | مفهوم                                                                                                                      |
| -------- | ------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `path`   | بله    | `string`                              | مسیر پیکربندی جداشده با نقطه، نسبت به `plugins.entries.<id>.config`. از نویسه‌های عام `*` برای بخش‌های نگاشت/آرایه پشتیبانی می‌کند. |
| `equals` | بله    | `string \| number \| boolean \| null` | مقدار ثابت دقیقی که این مقدار پیکربندی را خطرناک مشخص می‌کند.                                                              |

`secretInputs` از موارد زیر پشتیبانی می‌کند:

| فیلد                   | الزامی | نوع        | مفهوم                                                                                                                                                                                                                     |
| ----------------------- | ------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bundledDefaultEnabled` | خیر    | `boolean`  | هنگام تصمیم‌گیری دربارهٔ فعال بودن این سطح SecretRef، فعال‌سازی پیش‌فرض Plugin همراه را بازنویسی می‌کند. زمانی از این گزینه استفاده کنید که Plugin همراه است، اما سطح باید تا زمان فعال‌سازی صریح در پیکربندی غیرفعال بماند. |
| `paths`                 | بله    | `object[]` | مسیرهای پیکربندی با ساختار راز، هرکدام دارای `path` (با جداسازی نقطه‌ای، نسبی به `plugins.entries.<id>.config` و با پشتیبانی از نویسه‌های عام `*`) و `expected` اختیاری (در حال حاضر فقط `"string"`).                         |

## مرجع mediaUnderstandingProviderMetadata

زمانی از `mediaUnderstandingProviderMetadata` استفاده کنید که یک ارائه‌دهندهٔ درک رسانه دارای مدل‌های پیش‌فرض، اولویت بازگشت خودکار احراز هویت، یا پشتیبانی بومی از سند است که کمک‌تابع‌های عمومی هسته پیش از بارگذاری زمان اجرا به آن نیاز دارند. کلیدها باید در `contracts.mediaUnderstandingProviders` نیز اعلان شوند.

```json
{
  "contracts": {
    "mediaUnderstandingProviders": ["example"]
  },
  "mediaUnderstandingProviderMetadata": {
    "example": {
      "capabilities": ["image", "audio"],
      "defaultModels": {
        "image": "example-vision-latest",
        "audio": "example-transcribe-latest"
      },
      "autoPriority": {
        "image": 40
      },
      "nativeDocumentInputs": ["pdf"],
      "documentModels": {
        "pdf": {
          "textExtraction": "example-doc-text-latest",
          "image": "example-doc-vision-latest"
        }
      }
    }
  }
}
```

هر ورودی ارائه‌دهنده می‌تواند شامل موارد زیر باشد:

| فیلد                   | نوع                                                              | مفهوم                                                                                                                               |
| ---------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `capabilities`         | `("image" \| "audio" \| "video")[]`                              | قابلیت‌های رسانه‌ای ارائه‌شده توسط این ارائه‌دهنده.                                                                                  |
| `defaultModels`        | `Record<string, string>`                                         | پیش‌فرض‌های نگاشت قابلیت به مدل که وقتی پیکربندی مدلی را مشخص نمی‌کند، استفاده می‌شوند.                                              |
| `autoPriority`         | `Record<string, number>`                                         | برای بازگشت خودکار ارائه‌دهنده بر پایهٔ اطلاعات ورود، اعداد کمتر زودتر مرتب می‌شوند.                                                  |
| `nativeDocumentInputs` | `"pdf"[]`                                                        | ورودی‌های بومی سند که ارائه‌دهنده پشتیبانی می‌کند.                                                                                    |
| `documentModels`       | `{ pdf?: { textExtraction?: string; image?: string \| false } }` | بازنویسی مدل به‌ازای هر نوع سند. برای غیرفعال‌کردن استخراج مبتنی بر تصویر برای آن نوع سند، `image: false` را تنظیم کنید.              |

## مرجع channelConfigs

زمانی از `channelConfigs` استفاده کنید که یک Plugin کانال پیش از بارگذاری زمان اجرا به فرادادهٔ کم‌هزینهٔ پیکربندی نیاز دارد. کشف فقط‌خواندنی راه‌اندازی/وضعیت کانال می‌تواند برای کانال‌های خارجی پیکربندی‌شده، وقتی هیچ ورودی راه‌اندازی موجود نیست یا وقتی `setup.requiresRuntime: false` غیرضروری بودن زمان اجرای راه‌اندازی را اعلان می‌کند، مستقیماً از این فراداده استفاده کند.

`channelConfigs` فرادادهٔ مانیفست Plugin است، نه یک بخش جدید پیکربندی سطح‌بالای کاربر. کاربران همچنان نمونه‌های کانال را زیر `channels.<channel-id>` پیکربندی می‌کنند. OpenClaw فرادادهٔ مانیفست را می‌خواند تا پیش از اجرای کد زمان اجرای Plugin تعیین کند کدام Plugin مالک آن کانال پیکربندی‌شده است.

برای یک Plugin کانال، `configSchema` و `channelConfigs` مسیرهای متفاوتی را توصیف می‌کنند:

- `configSchema` اعتبار `plugins.entries.<plugin-id>.config` را بررسی می‌کند
- `channelConfigs.<channel-id>.schema` اعتبار `channels.<channel-id>` را بررسی می‌کند

Pluginهای غیرهمراهی که `channels[]` را اعلان می‌کنند، باید ورودی‌های منطبق `channelConfigs` را نیز اعلان کنند. بدون آن‌ها، OpenClaw همچنان می‌تواند Plugin را بارگذاری کند، اما سطوح طرح‌وارهٔ پیکربندی مسیر سرد، راه‌اندازی و رابط کاربری کنترل تا زمان اجرای زمان اجرای Plugin نمی‌توانند ساختار گزینه‌های متعلق به کانال را تشخیص دهند.

`channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled` و `nativeSkillsAutoEnabled` می‌توانند پیش‌فرض‌های ایستای `auto` را برای بررسی‌های پیکربندی فرمان که پیش از بارگذاری زمان اجرای کانال انجام می‌شوند، اعلان کنند. کانال‌های همراه همچنین می‌توانند همین پیش‌فرض‌ها را از طریق `package.json#openclaw.channel.commands` در کنار دیگر فرادادهٔ کاتالوگ کانال متعلق به بستهٔ خود منتشر کنند.

```json
{
  "channelConfigs": {
    "matrix": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "homeserverUrl": { "type": "string" }
        }
      },
      "uiHints": {
        "homeserverUrl": {
          "label": "Homeserver URL",
          "placeholder": "https://matrix.example.com"
        }
      },
      "label": "Matrix",
      "description": "Matrix homeserver connection",
      "commands": {
        "nativeCommandsAutoEnabled": true,
        "nativeSkillsAutoEnabled": true
      },
      "preferOver": ["matrix-legacy"]
    }
  }
}
```

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

| فیلد          | نوع                      | مفهوم                                                                                                              |
| ------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `schema`      | `object`                 | طرح‌وارهٔ JSON برای `channels.<id>`. برای هر ورودی اعلان‌شدهٔ پیکربندی کانال الزامی است.                           |
| `uiHints`     | `Record<string, object>` | برچسب‌ها/متن‌های جای‌نما/راهنمای حساس‌بودن اختیاری رابط کاربری برای آن بخش پیکربندی کانال.                         |
| `label`       | `string`                 | برچسب کانال که وقتی فرادادهٔ زمان اجرا آماده نیست، در سطوح انتخاب‌گر و بازرسی ادغام می‌شود.                         |
| `description` | `string`                 | توضیح کوتاه کانال برای سطوح بازرسی و کاتالوگ.                                                                      |
| `commands`    | `object`                 | پیش‌فرض‌های خودکار ایستای فرمان بومی و Skills بومی برای بررسی‌های پیکربندی پیش از زمان اجرا.                       |
| `preferOver`  | `string[]`               | شناسه‌های Plugin قدیمی یا کم‌اولویت‌تری که این کانال باید در سطوح انتخاب بر آن‌ها اولویت داشته باشد.               |

### جایگزین‌کردن Plugin کانال دیگر

زمانی از `preferOver` استفاده کنید که Plugin شما مالک ترجیحی شناسهٔ کانالی است که Plugin دیگری نیز می‌تواند آن را ارائه کند. موارد رایج شامل شناسهٔ تغییرنام‌یافتهٔ Plugin، یک Plugin مستقل که جایگزین Plugin همراه می‌شود، یا یک انشعاب نگه‌داری‌شده است که برای سازگاری پیکربندی همان شناسهٔ کانال را حفظ می‌کند.

```json
{
  "id": "acme-chat",
  "channels": ["chat"],
  "channelConfigs": {
    "chat": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "webhookUrl": { "type": "string" }
        }
      },
      "preferOver": ["chat"]
    }
  }
}
```

وقتی `channels.chat` پیکربندی شده باشد، OpenClaw هم شناسهٔ کانال و هم شناسهٔ Plugin ترجیحی را در نظر می‌گیرد. اگر Plugin کم‌اولویت‌تر فقط به‌دلیل همراه بودن یا فعال بودن پیش‌فرض انتخاب شده باشد، OpenClaw آن را در پیکربندی مؤثر زمان اجرا غیرفعال می‌کند تا یک Plugin مالک کانال و ابزارهای آن باشد. انتخاب صریح کاربر همچنان اولویت دارد: اگر کاربر هر دو Plugin را به‌صراحت فعال کند (از طریق `plugins.allow` یا یک پیکربندی مؤثر `plugins.entries`)، OpenClaw آن انتخاب را حفظ می‌کند و به‌جای تغییر بی‌سروصدای مجموعهٔ Pluginهای درخواستی، عیب‌یابی کانال/ابزار تکراری را گزارش می‌دهد.

دامنهٔ `preferOver` را به شناسه‌های Pluginی محدود کنید که واقعاً می‌توانند همان کانال را ارائه کنند. این یک فیلد اولویت عمومی نیست و کلیدهای پیکربندی کاربر را تغییرنام نمی‌دهد.

## مرجع modelSupport

زمانی از `modelSupport` استفاده کنید که OpenClaw باید پیش از بارگذاری زمان اجرای Plugin، Plugin ارائه‌دهندهٔ شما را از شناسه‌های کوتاه مدل مانند `gpt-5.6-sol` یا `claude-sonnet-4.6` استنباط کند.

```json
{
  "modelSupport": {
    "modelPrefixes": ["gpt-", "o1", "o3", "o4"],
    "modelPatterns": ["^computer-use-preview"]
  }
}
```

OpenClaw این ترتیب تقدم را اعمال می‌کند:

- ارجاع‌های صریح `provider/model` از فرادادهٔ مانیفست `providers` متعلق به مالک استفاده می‌کنند
- `modelPatterns` بر `modelPrefixes` مقدم است
- اگر یک Plugin غیرهمراه و یک Plugin همراه هر دو منطبق باشند، Plugin غیرهمراه برنده می‌شود
- ابهام باقی‌مانده تا زمانی که کاربر یا پیکربندی یک ارائه‌دهنده را مشخص کند، نادیده گرفته می‌شود

فیلدها:

| فیلد            | نوع        | مفهوم                                                                                         |
| --------------- | ---------- | --------------------------------------------------------------------------------------------- |
| `modelPrefixes` | `string[]` | پیشوندهایی که با `startsWith` در برابر شناسه‌های کوتاه مدل تطبیق داده می‌شوند.                 |
| `modelPatterns` | `string[]` | منابع عبارت منظم که پس از حذف پسوند پروفایل در برابر شناسه‌های کوتاه مدل تطبیق داده می‌شوند.   |

ورودی‌های `modelPatterns` از طریق `compileSafeRegex` کامپایل می‌شوند که الگوهای دارای تکرار تودرتو (برای مثال `(a+)+$`) را رد می‌کند. الگوهایی که بررسی ایمنی را نمی‌گذرانند، همانند عبارت‌های منظم دارای نحو نامعتبر، بی‌سروصدا نادیده گرفته می‌شوند. الگوها را ساده نگه دارید و از کمیت‌سازهای تودرتو پرهیز کنید.

## مرجع modelCatalog

زمانی از `modelCatalog` استفاده کنید که OpenClaw باید پیش از بارگذاری زمان اجرای Plugin، فرادادهٔ مدل ارائه‌دهنده را بداند. این منبع متعلق به مانیفست برای ردیف‌های ثابت کاتالوگ، نام‌های مستعار ارائه‌دهنده، قواعد حذف و حالت کشف است. تازه‌سازی زمان اجرا همچنان متعلق به کد زمان اجرای ارائه‌دهنده است، اما مانیفست به هسته اعلام می‌کند چه زمانی زمان اجرا لازم است.

```json
{
  "providers": ["openai"],
  "modelCatalog": {
    "providers": {
      "openai": {
        "baseUrl": "https://api.openai.com/v1",
        "api": "openai-responses",
        "models": [
          {
            "id": "gpt-5.4",
            "name": "GPT-5.4",
            "input": ["text", "image"],
            "reasoning": true,
            "contextWindow": 256000,
            "maxTokens": 128000,
            "cost": {
              "input": 1.25,
              "output": 10,
              "cacheRead": 0.125
            },
            "status": "available",
            "tags": ["default"]
          }
        ]
      }
    },
    "aliases": {
      "azure-openai-responses": {
        "provider": "openai",
        "api": "azure-openai-responses"
      }
    },
    "suppressions": [
      {
        "provider": "azure-openai-responses",
        "model": "gpt-5.3-codex-spark",
        "reason": "not available on Azure OpenAI Responses"
      }
    ],
    "discovery": {
      "openai": "static"
    }
  }
}
```

فیلدهای سطح‌بالا:

| فیلد            | نوع                                                     | مفهوم                                                                                                                    |
| ---------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `providers`      | `Record<string, object>`                                 | ردیف‌های کاتالوگ برای شناسه‌های ارائه‌دهنده‌ای که مالکیتشان با این Plugin است. کلیدها باید در `providers` سطح بالا نیز ظاهر شوند. |
| `aliases`        | `Record<string, object>`                                 | نام‌های مستعار ارائه‌دهنده که برای برنامه‌ریزی کاتالوگ یا سرکوب باید به یک ارائه‌دهنده تحت مالکیت تفکیک شوند.             |
| `suppressions`   | `object[]`                                               | ردیف‌های مدل از منبعی دیگر که این Plugin به دلیلی مختص ارائه‌دهنده سرکوب می‌کند.                                         |
| `discovery`      | `Record<string, "static" \| "refreshable" \| "runtime">` | اینکه آیا کاتالوگ ارائه‌دهنده از فراداده مانیفست قابل خواندن است، می‌توان آن را در کش تازه‌سازی کرد، یا به زمان اجرا نیاز دارد. |
| `runtimeAugment` | `boolean`                                                | فقط زمانی روی `true` تنظیم شود که زمان اجرای ارائه‌دهنده باید پس از برنامه‌ریزی مانیفست/پیکربندی، ردیف‌هایی به کاتالوگ بیفزاید. |

`aliases` در جست‌وجوی مالکیت ارائه‌دهنده برای برنامه‌ریزی کاتالوگ مدل مشارکت دارد. مقصد نام‌های مستعار باید ارائه‌دهندگان سطح بالایی باشند که تحت مالکیت همان Plugin هستند. وقتی فهرستی پالایش‌شده بر اساس ارائه‌دهنده از یک نام مستعار استفاده می‌کند، OpenClaw می‌تواند بدون بارگذاری زمان اجرای ارائه‌دهنده، مانیفست مالک را بخواند و بازنویسی‌های API/نشانی پایه نام مستعار را اعمال کند. نام‌های مستعار، فهرست‌های پالایش‌نشده کاتالوگ را گسترش نمی‌دهند؛ فهرست‌های گسترده فقط ردیف‌های ارائه‌دهنده متعارفِ مالک را خروجی می‌دهند.

`suppressions` جایگزین هوک قدیمی `suppressBuiltInModel` در زمان اجرای ارائه‌دهنده می‌شود. ورودی‌های سرکوب فقط زمانی اعمال می‌شوند که ارائه‌دهنده تحت مالکیت Plugin باشد یا به‌عنوان کلید `modelCatalog.aliases` تعریف شده باشد که به یک ارائه‌دهنده تحت مالکیت اشاره می‌کند. هوک‌های سرکوب زمان اجرا دیگر هنگام تفکیک مدل فراخوانی نمی‌شوند.

فیلدهای ارائه‌دهنده:

| فیلد                  | نوع                      | مفهوم                                                                                                                                                                                                                         |
| --------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `baseUrl`             | `string`                 | نشانی پایه پیش‌فرض اختیاری برای مدل‌های این کاتالوگ ارائه‌دهنده.                                                                                                                                                              |
| `api`                 | `ModelApi`               | آداپتور API پیش‌فرض اختیاری برای مدل‌های این کاتالوگ ارائه‌دهنده.                                                                                                                                                              |
| `headers`             | `Record<string, string>` | سرآیندهای ایستای اختیاری که برای این کاتالوگ ارائه‌دهنده اعمال می‌شوند.                                                                                                                                                       |
| `defaultUtilityModel` | `string`                 | شناسه اختیاری مدل کوچک پیشنهادی ارائه‌دهنده برای وظایف کوتاه و داخلی کمکی (عنوان‌ها، روایت پیشرفت). وقتی `agents.defaults.utilityModel` تنظیم نشده باشد و این ارائه‌دهنده مدل اصلی عامل را ارائه کند، استفاده می‌شود. |
| `models`              | `object[]`               | ردیف‌های الزامی مدل. ردیف‌های فاقد `id` نادیده گرفته می‌شوند.                                                                                                                                                                |

فیلدهای مدل:

| فیلد               | نوع                                                            | مفهوم                                                                                      |
| ------------------ | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `id`               | `string`                                                       | شناسه مدل محلیِ ارائه‌دهنده، بدون پیشوند `provider/`.                                      |
| `name`             | `string`                                                       | نام نمایشی اختیاری.                                                                        |
| `api`              | `ModelApi`                                                     | بازنویسی اختیاری API برای هر مدل.                                                          |
| `baseUrl`          | `string`                                                       | بازنویسی اختیاری نشانی پایه برای هر مدل.                                                   |
| `headers`          | `Record<string, string>`                                       | سرآیندهای ایستای اختیاری برای هر مدل.                                                      |
| `input`            | `Array<"text" \| "image" \| "document">`                       | شیوه‌های ورودی پذیرفته‌شده توسط مدل. مقادیر دیگر بدون هشدار حذف می‌شوند.                   |
| `reasoning`        | `boolean`                                                      | اینکه آیا مدل رفتار استدلالی ارائه می‌کند.                                                 |
| `contextWindow`    | `number`                                                       | پنجره زمینه بومی ارائه‌دهنده.                                                              |
| `contextTokens`    | `number`                                                       | سقف مؤثر و اختیاری زمینه در زمان اجرا، هنگامی که با `contextWindow` متفاوت است.            |
| `maxTokens`        | `number`                                                       | حداکثر توکن‌های خروجی، در صورت مشخص بودن.                                                  |
| `thinkingLevelMap` | `Record<string, string \| null>`                               | بازنویسی‌های اختیاری شناسه مدل یا پارامتر برای هر سطح تفکر.                                |
| `cost`             | `object`                                                       | قیمت‌گذاری اختیاری دلاری به‌ازای هر یک میلیون توکن، شامل `tieredPricing` اختیاری.          |
| `compat`           | `object`                                                       | پرچم‌های سازگاری اختیاری منطبق با سازگاری پیکربندی مدل OpenClaw.                           |
| `mediaInput`       | `object`                                                       | پیکربندی اختیاری ورودی برای هر شیوه، که در حال حاضر فقط تصویر را پوشش می‌دهد.              |
| `status`           | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | وضعیت فهرست‌شدن. فقط زمانی سرکوب شود که ردیف نباید به‌هیچ‌وجه ظاهر شود.                    |
| `statusReason`     | `string`                                                       | دلیل اختیاری که همراه وضعیت غیرقابل‌دسترس نمایش داده می‌شود.                               |
| `replaces`         | `string[]`                                                     | شناسه‌های قدیمی‌تر مدل محلیِ ارائه‌دهنده که این مدل جایگزین آن‌ها می‌شود.                  |
| `replacedBy`       | `string`                                                       | شناسه مدل محلیِ ارائه‌دهنده جایگزین برای ردیف‌های منسوخ‌شده.                               |
| `tags`             | `string[]`                                                     | برچسب‌های پایداری که انتخاب‌گرها و پالایه‌ها از آن‌ها استفاده می‌کنند.                     |

فیلدهای سرکوب:

| فیلد                       | نوع        | مفهوم                                                                                                         |
| -------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------- |
| `provider`                 | `string`   | شناسه ارائه‌دهنده برای ردیف بالادستی که باید سرکوب شود. باید تحت مالکیت این Plugin باشد یا به‌عنوان نام مستعار تحت مالکیت تعریف شده باشد. |
| `model`                    | `string`   | شناسه مدل محلیِ ارائه‌دهنده که باید سرکوب شود.                                                               |
| `reason`                   | `string`   | پیام اختیاری که هنگام درخواست مستقیم ردیف سرکوب‌شده نمایش داده می‌شود.                                       |
| `when.baseUrlHosts`        | `string[]` | فهرست اختیاری میزبان‌های مؤثر نشانی پایه ارائه‌دهنده که پیش از اعمال سرکوب باید وجود داشته باشند.            |
| `when.providerConfigApiIn` | `string[]` | فهرست اختیاری مقادیر دقیق `api` در پیکربندی ارائه‌دهنده که پیش از اعمال سرکوب الزامی هستند.                  |

داده‌های مخصوص زمان اجرا را در `modelCatalog` قرار ندهید. فقط زمانی از `static` استفاده کنید که ردیف‌های مانیفست به‌اندازه کافی کامل باشند تا سطوح فهرست و انتخاب‌گرِ پالایش‌شده بر اساس ارائه‌دهنده بتوانند از کشف رجیستری/زمان اجرا صرف‌نظر کنند. از `refreshable` زمانی استفاده کنید که ردیف‌های مانیفست بذرها یا مکمل‌های مفیدی برای فهرست‌شدن باشند، اما تازه‌سازی/کش بتواند بعداً ردیف‌های بیشتری اضافه کند؛ ردیف‌های قابل تازه‌سازی به‌تنهایی مرجع قطعی نیستند. از `runtime` زمانی استفاده کنید که OpenClaw برای دانستن فهرست باید زمان اجرای ارائه‌دهنده را بارگذاری کند.

## مرجع modelIdNormalization

از `modelIdNormalization` برای پاک‌سازی کم‌هزینه شناسه مدل تحت مالکیت ارائه‌دهنده استفاده کنید که باید پیش از بارگذاری زمان اجرای ارائه‌دهنده انجام شود. این کار نام‌های مستعار مانند نام‌های کوتاه مدل، شناسه‌های قدیمی محلیِ ارائه‌دهنده و قواعد پیشوند پراکسی را به‌جای جدول‌های اصلی انتخاب مدل، در مانیفست Plugin مالک نگه می‌دارد.

```json
{
  "providers": ["anthropic", "openrouter"],
  "modelIdNormalization": {
    "providers": {
      "anthropic": {
        "aliases": {
          "sonnet-4.6": "claude-sonnet-4-6"
        }
      },
      "openrouter": {
        "prefixWhenBare": "openrouter"
      }
    }
  }
}
```

فیلدهای ارائه‌دهنده:

| فیلد                                 | نوع                     | مفهوم                                                                                           |
| ------------------------------------ | ----------------------- | ----------------------------------------------------------------------------------------------- |
| `aliases`                            | `Record<string,string>` | نام‌های مستعار دقیق شناسه مدل بدون حساسیت به حروف بزرگ و کوچک. مقادیر همان‌گونه که نوشته شده‌اند بازگردانده می‌شوند. |
| `stripPrefixes`                      | `string[]`              | پیشوندهایی که پیش از جست‌وجوی نام مستعار حذف می‌شوند و برای تکرار قدیمی ارائه‌دهنده/مدل مفیدند. |
| `prefixWhenBare`                     | `string`                | پیشوندی که وقتی شناسه مدل نرمال‌شده از قبل شامل `/` نیست، افزوده می‌شود.                       |
| `prefixWhenBareAfterAliasStartsWith` | `object[]`              | قواعد شرطی پیشوند برای شناسه بدون پیشوند پس از جست‌وجوی نام مستعار، با کلیدهای `modelPrefix` و `prefix`. |

## مرجع providerEndpoints

از `providerEndpoints` برای دسته‌بندی نقطه پایانی استفاده کنید که سیاست عمومی درخواست باید پیش از بارگذاری زمان اجرای ارائه‌دهنده از آن آگاه باشد. هسته همچنان مالک معنای هر `endpointClass` است؛ مانیفست‌های Plugin مالک فراداده میزبان و نشانی پایه هستند.

Pluginهای ارائه‌دهنده که رسماً بیرونی شده‌اند از توزیع هسته کنار گذاشته می‌شوند، بنابراین
مانیفست‌های آن‌ها تا زمان نصب قابل مشاهده نیستند. `providerEndpoints` آن‌ها باید
در `scripts/lib/official-external-provider-catalog.json` نیز منعکس شود تا
دسته‌بندی نقطه پایانی بدون Plugin همچنان کار کند؛ یک آزمون قرارداد
این همسان‌سازی را اعمال می‌کند.

فیلدهای نقطه پایانی:

| فیلد                           | نوع        | مفهوم                                                                                                  |
| ------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------ |
| `endpointClass`                | `string`   | کلاس شناخته‌شدهٔ نقطهٔ پایانی هسته، مانند `openrouter`، `moonshot-native` یا `google-vertex`.          |
| `hosts`                        | `string[]` | نام‌های میزبان دقیقی که به کلاس نقطهٔ پایانی نگاشت می‌شوند.                                            |
| `hostSuffixes`                 | `string[]` | پسوندهای میزبانی که به کلاس نقطهٔ پایانی نگاشت می‌شوند. برای تطبیق صرفاً با پسوند دامنه، با `.` آغاز کنید. |
| `baseUrls`                     | `string[]` | نشانی‌های پایهٔ HTTP(S) دقیق و نرمال‌سازی‌شده‌ای که به کلاس نقطهٔ پایانی نگاشت می‌شوند.                 |
| `googleVertexRegion`           | `string`   | منطقهٔ ایستای Google Vertex برای میزبان‌های سراسری دقیق.                                               |
| `googleVertexRegionHostSuffix` | `string`   | پسوندی که از میزبان‌های منطبق حذف می‌شود تا پیشوند منطقهٔ Google Vertex آشکار شود.                     |

## مرجع providerRequest

از `providerRequest` برای فرادادهٔ کم‌هزینهٔ سازگاری درخواست استفاده کنید که سیاست عمومی درخواست بدون بارگذاری زمان اجرای ارائه‌دهنده به آن نیاز دارد. بازنویسی محمولهٔ مختص رفتار را در هوک‌های زمان اجرای ارائه‌دهنده یا کمک‌تابع‌های مشترک خانوادهٔ ارائه‌دهندگان نگه دارید.

```json
{
  "providerRequest": {
    "providers": {
      "vllm": {
        "family": "vllm",
        "openAICompletions": {
          "supportsStreamingUsage": true
        }
      }
    }
  }
}
```

فیلدهای ارائه‌دهنده:

| فیلد                  | نوع          | مفهوم                                                                                               |
| --------------------- | ------------ | --------------------------------------------------------------------------------------------------- |
| `family`              | `string`     | برچسب خانوادهٔ ارائه‌دهنده که تصمیم‌های عمومی سازگاری درخواست و عیب‌یابی از آن استفاده می‌کنند.       |
| `compatibilityFamily` | `"moonshot"` | دستهٔ اختیاری سازگاری خانوادهٔ ارائه‌دهنده برای کمک‌تابع‌های مشترک درخواست.                           |
| `openAICompletions`   | `object`     | پرچم‌های درخواست تکمیل سازگار با OpenAI که در حال حاضر شامل `supportsStreamingUsage` است.            |

## مرجع secretProviderIntegrations

هنگامی از `secretProviderIntegrations` استفاده کنید که یک Plugin بتواند پیش‌تنظیم ارائه‌دهندهٔ اجرایی و قابل‌استفادهٔ مجدد SecretRef را منتشر کند. OpenClaw این فراداده را پیش از بارگذاری زمان اجرای Plugin می‌خواند، مالکیت Plugin را در `secrets.providers.<alias>.pluginIntegration` ذخیره می‌کند و حل واقعی محرمانه را به زمان اجرای SecretRef واگذار می‌کند. پیش‌تنظیم‌ها فقط برای Pluginهای همراه و Pluginهای نصب‌شده‌ای ارائه می‌شوند که از ریشه‌های مدیریت‌شدهٔ نصب Plugin، مانند نصب‌های git و ClawHub، کشف شده‌اند.

```json
{
  "secretProviderIntegrations": {
    "secret-store": {
      "providerAlias": "team-secrets",
      "displayName": "Team secrets",
      "source": "exec",
      "command": "${node}",
      "args": ["./bin/resolve-secrets.mjs"]
    }
  }
}
```

کلید نگاشت، شناسهٔ یکپارچه‌سازی است. اگر `providerAlias` حذف شود، OpenClaw از شناسهٔ یکپارچه‌سازی به‌عنوان نام مستعار ارائه‌دهندهٔ SecretRef استفاده می‌کند. نام‌های مستعار ارائه‌دهنده باید با الگوی عادی نام مستعار ارائه‌دهندهٔ SecretRef مطابقت داشته باشند؛ برای مثال `team-secrets` یا `onepassword-work`.

هنگامی که یک اپراتور پیش‌تنظیم را انتخاب می‌کند، OpenClaw مرجع ارائه‌دهنده‌ای مانند نمونهٔ زیر می‌نویسد:

```json
{
  "secrets": {
    "providers": {
      "team-secrets": {
        "source": "exec",
        "pluginIntegration": {
          "pluginId": "acme-secrets",
          "integrationId": "secret-store"
        }
      }
    }
  }
}
```

هنگام راه‌اندازی یا بارگذاری مجدد، OpenClaw این ارائه‌دهنده را با بارگذاری فرادادهٔ فعلی مانیفست Plugin، بررسی نصب و فعال‌بودن Plugin مالک، و ساخت دستور اجرایی از مانیفست حل می‌کند. غیرفعال یا حذف‌کردن Plugin، ارائه‌دهنده را برای SecretRefهای فعال لغو می‌کند. اپراتورهایی که پیکربندی اجرایی مستقل می‌خواهند، همچنان می‌توانند ارائه‌دهندگان دستی `command`/`args` را مستقیماً تعریف کنند.

در حال حاضر فقط پیش‌تنظیم‌های `source: "exec"` پشتیبانی می‌شوند. `command` باید `${node}` باشد و `args[0]` باید یک اسکریپت حل‌کنندهٔ نسبی به ریشهٔ Plugin با پیشوند `./` باشد. OpenClaw هنگام راه‌اندازی یا بارگذاری مجدد، آن را به فایل اجرایی فعلی Node و مسیر مطلق اسکریپت درون Plugin تبدیل می‌کند. گزینه‌های Node مانند `--require`، `--import`، `--loader`، `--env-file`، `--eval` و `--print` بخشی از قرارداد پیش‌تنظیم مانیفست نیستند. اپراتورهایی که به دستورهای غیر Node نیاز دارند، می‌توانند ارائه‌دهندگان اجرایی دستی و مستقل را مستقیماً پیکربندی کنند.

OpenClaw مقدار `trustedDirs` را برای پیش‌تنظیم‌های مانیفست از ریشهٔ Plugin و، برای پیش‌تنظیم‌های `${node}`، از پوشهٔ فایل اجرایی فعلی Node استخراج می‌کند. مقادیر `trustedDirs` تعریف‌شده در مانیفست نادیده گرفته می‌شوند. سایر گزینه‌های ارائه‌دهندهٔ اجرایی مانند `timeoutMs`، `noOutputTimeoutMs`، `maxOutputBytes`، `jsonOnly`، `env`، `passEnv` و `allowInsecurePath` بدون تغییر به پیکربندی عادی ارائه‌دهندهٔ اجرایی SecretRef منتقل می‌شوند.

## مرجع modelPricing

هنگامی از `modelPricing` استفاده کنید که یک ارائه‌دهنده پیش از بارگذاری زمان اجرا به کنترل رفتار قیمت‌گذاری در صفحهٔ کنترل نیاز دارد. حافظهٔ نهان قیمت‌گذاری Gateway این فراداده را بدون واردکردن کد زمان اجرای ارائه‌دهنده می‌خواند.

```json
{
  "providers": ["ollama", "openrouter"],
  "modelPricing": {
    "providers": {
      "ollama": {
        "external": false
      },
      "openrouter": {
        "openRouter": {
          "passthroughProviderModel": true
        },
        "liteLLM": false
      }
    }
  }
}
```

فیلدهای ارائه‌دهنده:

| فیلد         | نوع               | مفهوم                                                                                                    |
| ------------ | ----------------- | -------------------------------------------------------------------------------------------------------- |
| `external`   | `boolean`         | برای ارائه‌دهندگان محلی یا خودمیزبان که هرگز نباید قیمت‌گذاری OpenRouter یا LiteLLM را دریافت کنند، روی `false` تنظیم کنید. |
| `openRouter` | `false \| object` | نگاشت جست‌وجوی قیمت‌گذاری OpenRouter. مقدار `false` جست‌وجوی OpenRouter را برای این ارائه‌دهنده غیرفعال می‌کند. |
| `liteLLM`    | `false \| object` | نگاشت جست‌وجوی قیمت‌گذاری LiteLLM. مقدار `false` جست‌وجوی LiteLLM را برای این ارائه‌دهنده غیرفعال می‌کند. |

فیلدهای منبع:

| فیلد                       | نوع                | مفهوم                                                                                                                     |
| -------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `provider`                 | `string`           | شناسهٔ ارائه‌دهنده در کاتالوگ خارجی، هنگامی که با شناسهٔ ارائه‌دهندهٔ OpenClaw متفاوت است؛ برای مثال `z-ai` برای ارائه‌دهندهٔ `zai`. |
| `passthroughProviderModel` | `boolean`          | شناسه‌های مدل دارای اسلش را به‌عنوان مراجع تودرتوی ارائه‌دهنده/مدل در نظر می‌گیرد؛ برای ارائه‌دهندگان پراکسی مانند OpenRouter مفید است. |
| `modelIdTransforms`        | `"version-dots"[]` | گونه‌های اضافی شناسهٔ مدل در کاتالوگ خارجی. `version-dots` شناسه‌های نسخهٔ نقطه‌دار مانند `claude-opus-4.6` را امتحان می‌کند. |

### نمایهٔ ارائه‌دهندگان OpenClaw

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

ترتیب اعتبار کاتالوگ:

1. پیکربندی کاربر.
2. `modelCatalog` مانیفست Plugin نصب‌شده.
3. حافظهٔ نهان کاتالوگ مدل حاصل از نوسازی صریح.
4. ردیف‌های پیش‌نمایش نمایهٔ ارائه‌دهندگان OpenClaw.

نمایهٔ ارائه‌دهندگان نباید شامل محرمانه‌ها، وضعیت فعال‌بودن، هوک‌های زمان اجرا یا داده‌های زندهٔ مدل مختص حساب باشد. کاتالوگ‌های پیش‌نمایش آن از همان ساختار ردیف ارائه‌دهندهٔ `modelCatalog` در مانیفست‌های Plugin استفاده می‌کنند، اما باید به فرادادهٔ نمایشی پایدار محدود بمانند؛ مگر اینکه فیلدهای آداپتور زمان اجرا مانند `api`، `baseUrl`، قیمت‌گذاری یا پرچم‌های سازگاری عمداً با مانیفست Plugin نصب‌شده هم‌تراز نگه داشته شوند. ارائه‌دهندگانی که کشف زندهٔ `/models` دارند باید ردیف‌های نوسازی‌شده را از مسیر صریح حافظهٔ نهان کاتالوگ مدل بنویسند، نه اینکه فهرست‌سازی عادی یا فرایند ورود اولیه را وادار به فراخوانی APIهای ارائه‌دهنده کنند.

ورودی‌های نمایهٔ ارائه‌دهندگان همچنین می‌توانند فرادادهٔ Plugin قابل‌نصب را برای ارائه‌دهندگانی داشته باشند که Plugin آن‌ها از هسته خارج شده یا هنوز نصب نشده است. این فراداده از الگوی کاتالوگ کانال پیروی می‌کند: نام بسته، مشخصات نصب npm، یکپارچگی مورد انتظار و برچسب‌های کم‌هزینهٔ انتخاب احراز هویت برای نمایش یک گزینهٔ راه‌اندازی قابل‌نصب کافی هستند. پس از نصب Plugin، مانیفست آن اولویت دارد و ورودی نمایهٔ ارائه‌دهندگان برای آن ارائه‌دهنده نادیده گرفته می‌شود.

`openclaw doctor --fix` مجموعه‌ای کوچک و بسته از کلیدهای قدیمی قابلیت در سطح بالای مانیفست را به `contracts.*` منتقل می‌کند: `speechProviders`، `mediaUnderstandingProviders`، `imageGenerationProviders` و `tools`. دیگر هیچ‌یک از این موارد یا هر فهرست قابلیت دیگری به‌عنوان فیلدهای سطح بالای مانیفست خوانده نمی‌شوند؛ بارگذاری عادی مانیفست فقط آن‌ها را زیر `contracts` می‌شناسد.

## مانیفست در برابر package.json

این دو فایل وظایف متفاوتی دارند:

| فایل                   | کاربرد                                                                                                                                    |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.plugin.json` | کشف، اعتبارسنجی پیکربندی، فرادادهٔ انتخاب احراز هویت و راهنمایی‌های رابط کاربری که باید پیش از اجرای کد Plugin وجود داشته باشند             |
| `package.json`         | فرادادهٔ npm، نصب وابستگی‌ها و بلوک `openclaw` که برای نقاط ورود، محدودسازی نصب، راه‌اندازی یا فرادادهٔ کاتالوگ استفاده می‌شود              |

اگر مطمئن نیستید یک بخش از فراداده به کدام فایل تعلق دارد، از این قاعده استفاده کنید:

- اگر OpenClaw باید پیش از بارگذاری کد Plugin آن را بداند، در `openclaw.plugin.json` قرارش دهید
- اگر مربوط به بسته‌بندی، فایل‌های ورودی یا رفتار نصب npm است، در `package.json` قرارش دهید

### فیلدهای package.json که بر کشف اثر می‌گذارند

بخشی از فرادادهٔ پیش از زمان اجرای Plugin عمداً به‌جای `openclaw.plugin.json`، در بلوک `openclaw` درون `package.json` قرار دارد. `openclaw.bundle` و `openclaw.bundle.json` قراردادهای Plugin در OpenClaw نیستند؛ Pluginهای بومی باید از `openclaw.plugin.json` به‌همراه فیلدهای پشتیبانی‌شدهٔ `package.json#openclaw` در ادامه استفاده کنند.

نمونه‌های مهم:

| فیلد                                                                                      | معنی آن                                                                                                                                                                        |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `openclaw.extensions`                                                                      | نقاط ورود Plugin بومی را اعلام می‌کند. باید داخل پوشهٔ بستهٔ Plugin باقی بماند.                                                                                                   |
| `openclaw.runtimeExtensions`                                                               | نقاط ورود زمان اجرای JavaScript ساخته‌شده برای بسته‌های نصب‌شده را اعلام می‌کند. باید داخل پوشهٔ بستهٔ Plugin باقی بماند.                                                                 |
| `openclaw.setupEntry`                                                                      | نقطهٔ ورود سبک‌وزن و مختص راه‌اندازی که هنگام آغاز به کار، شروع با تأخیر کانال و کشف وضعیت فقط‌خواندنی کانال/SecretRef استفاده می‌شود. باید داخل پوشهٔ بستهٔ Plugin باقی بماند. |
| `openclaw.runtimeSetupEntry`                                                               | نقطهٔ ورود راه‌اندازی JavaScript ساخته‌شده را برای بسته‌های نصب‌شده اعلام می‌کند. به `setupEntry` نیاز دارد، باید موجود باشد و باید داخل پوشهٔ بستهٔ Plugin باقی بماند.                         |
| `openclaw.channel`                                                                         | فرادادهٔ کم‌هزینهٔ فهرست کانال، مانند برچسب‌ها، مسیرهای مستندات، نام‌های مستعار و متن انتخاب.                                                                                                 |
| `openclaw.channel.commands`                                                                | فرادادهٔ ایستای فرمان بومی و پیش‌فرض خودکار Skills بومی که پیش از بارگذاری زمان اجرای کانال، در سطوح پیکربندی، ممیزی و فهرست فرمان‌ها استفاده می‌شود.                                          |
| `openclaw.channel.configuredState`                                                         | فرادادهٔ سبک‌وزن بررسی‌کنندهٔ وضعیت پیکربندی‌شده که بدون بارگذاری کامل زمان اجرای کانال می‌تواند پاسخ دهد «آیا راه‌اندازی صرفاً مبتنی بر env از قبل وجود دارد؟».                                         |
| `openclaw.channel.persistedAuthState`                                                      | فرادادهٔ سبک‌وزن بررسی‌کنندهٔ احراز هویت ماندگار که بدون بارگذاری کامل زمان اجرای کانال می‌تواند پاسخ دهد «آیا از قبل ورود به حسابی انجام شده است؟».                                               |
| `openclaw.install.clawhubSpec` / `openclaw.install.npmSpec` / `openclaw.install.localPath` | راهنمای نصب/به‌روزرسانی برای Pluginهای همراه و منتشرشده به‌صورت خارجی.                                                                                                                   |
| `openclaw.install.defaultChoice`                                                           | مسیر نصب ترجیحی هنگامی که چند منبع نصب در دسترس است.                                                                                                                  |
| `openclaw.install.minHostVersion`                                                          | حداقل نسخهٔ پشتیبانی‌شدهٔ میزبان OpenClaw، با استفاده از کران پایین semver مانند `>=2026.3.22` یا `>=2026.5.1-beta.1`.                                                                             |
| `openclaw.compat.pluginApi`                                                                | حداقل بازهٔ API مربوط به Plugin در OpenClaw که این بسته به آن نیاز دارد، با استفاده از کران پایین semver مانند `>=2026.5.27`.                                                                                 |
| `openclaw.install.expectedIntegrity`                                                       | رشتهٔ یکپارچگی مورد انتظار برای توزیع npm، مانند `sha512-...`؛ جریان‌های نصب و به‌روزرسانی مصنوع دریافت‌شده را با آن تطبیق می‌دهند.                                                            |
| `openclaw.install.allowInvalidConfigRecovery`                                              | در صورت نامعتبر بودن پیکربندی، مسیر بازیابی محدودِ نصب مجدد Plugin همراه را مجاز می‌کند.                                                                                                       |
| `openclaw.install.requiredPlatformPackages`                                                | نام‌های مستعار بسته‌های npm که وقتی محدودیت‌های سکوی آن‌ها در فایل قفل با میزبان فعلی مطابقت دارد، باید ایجاد شوند.                                                                           |
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen`                          | اجازه می‌دهد سطوح کانال زمان اجرای راه‌اندازی پیش از آغاز گوش‌دادن بارگذاری شوند و سپس Plugin کامل کانال پیکربندی‌شده تا فعال‌سازی پس از گوش‌دادن به تعویق بیفتد.                                                 |

فرادادهٔ مانیفست تعیین می‌کند پیش از بارگذاری زمان اجرا، کدام گزینه‌های ارائه‌دهنده/کانال/راه‌اندازی در آغاز به کار نمایش داده شوند. `package.json#openclaw.install` به فرایند آغاز به کار می‌گوید وقتی کاربر یکی از آن گزینه‌ها را انتخاب می‌کند، چگونه آن Plugin را دریافت یا فعال کند. راهنمای نصب را به `openclaw.plugin.json` منتقل نکنید.

`openclaw.install.minHostVersion` هنگام نصب و بارگذاری رجیستری مانیفست برای منابع Plugin غیرهمراه اعمال می‌شود. مقادیر نامعتبر رد می‌شوند؛ مقادیر جدیدتر اما معتبر باعث می‌شوند Pluginهای خارجی روی میزبان‌های قدیمی‌تر نادیده گرفته شوند. فرض بر این است که Pluginهای منبع همراه با نسخهٔ کد منبع میزبان هم‌نسخه هستند.

`openclaw.install.requiredPlatformPackages` برای بسته‌های npm است که فایل‌های اجرایی بومی الزامی را از طریق نام‌های مستعار اختیاری و مختص سکو ارائه می‌کنند. نام سادهٔ بستهٔ npm را برای نام مستعار هر سکوی پشتیبانی‌شده فهرست کنید. هنگام نصب npm، OpenClaw فقط نام مستعار اعلام‌شده‌ای را بررسی می‌کند که محدودیت‌های فایل قفل آن با میزبان فعلی مطابقت دارد. اگر npm موفقیت را گزارش کند اما آن نام مستعار را حذف کرده باشد، OpenClaw یک بار با حافظهٔ نهان تازه دوباره تلاش می‌کند و اگر نام مستعار همچنان وجود نداشته باشد، نصب را بازمی‌گرداند.

`openclaw.compat.pluginApi` هنگام نصب بسته برای منابع Plugin غیرهمراه اعمال می‌شود. از آن برای تعیین کران پایین API مربوط به SDK/زمان اجرای Plugin در OpenClaw استفاده کنید که بسته بر مبنای آن ساخته شده است. هنگامی که یک بستهٔ Plugin به API جدیدتری نیاز دارد اما همچنان برای جریان‌های دیگر راهنمای نصب پایین‌تری را حفظ می‌کند، این مقدار می‌تواند سخت‌گیرانه‌تر از `minHostVersion` باشد. همگام‌سازی انتشار رسمی OpenClaw به‌طور پیش‌فرض کران‌های پایین موجود API مربوط به Pluginهای رسمی را به نسخهٔ انتشار OpenClaw افزایش می‌دهد، اما انتشارهای مختص Plugin می‌توانند در صورتی که بسته عمداً از میزبان‌های قدیمی‌تر پشتیبانی می‌کند، کران پایین‌تری را حفظ کنند. نسخهٔ بسته را به‌تنهایی به‌عنوان قرارداد سازگاری استفاده نکنید. `peerDependencies.openclaw` همچنان فرادادهٔ بستهٔ npm است؛ OpenClaw برای تصمیم‌های سازگاری نصب از قرارداد `openclaw.compat.pluginApi` استفاده می‌کند.

فرادادهٔ رسمی نصب در صورت نیاز، وقتی Plugin در ClawHub منتشر شده است، باید از `clawhubSpec` استفاده کند؛ فرایند آغاز به کار آن را منبع راه‌دور ترجیحی در نظر می‌گیرد و پس از نصب، اطلاعات مصنوع ClawHub را ثبت می‌کند. `npmSpec` برای بسته‌هایی که هنوز به ClawHub منتقل نشده‌اند، به‌عنوان مسیر جایگزین سازگاری باقی می‌ماند.

ثابت‌کردن دقیق نسخهٔ npm از قبل در `npmSpec` قرار دارد؛ برای مثال `"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. مدخل‌های رسمی فهرست خارجی باید مشخصات دقیق را با `expectedIntegrity` جفت کنند تا اگر مصنوع npm دریافت‌شده دیگر با انتشار ثابت‌شده مطابقت نداشت، جریان‌های به‌روزرسانی به‌صورت بسته و امن شکست بخورند. فرایند تعاملی آغاز به کار برای سازگاری همچنان مشخصات npm رجیستری مورد اعتماد، از جمله نام سادهٔ بسته و برچسب‌های توزیع، را ارائه می‌دهد. عیب‌یابی فهرست می‌تواند منابع دقیق، شناور، ثابت‌شده با یکپارچگی، فاقد یکپارچگی، دارای عدم تطابق نام بسته و دارای انتخاب پیش‌فرض نامعتبر را از یکدیگر تشخیص دهد. همچنین وقتی `expectedIntegrity` وجود دارد اما منبع معتبر npm برای ثابت‌کردن آن وجود ندارد، هشدار می‌دهد. وقتی `expectedIntegrity` وجود دارد، جریان‌های نصب/به‌روزرسانی آن را اعمال می‌کنند؛ وقتی حذف شده باشد، وضوح رجیستری بدون ثابت‌کردن یکپارچگی ثبت می‌شود.

Pluginهای کانال باید زمانی `openclaw.setupEntry` را ارائه کنند که بررسی‌های وضعیت، فهرست کانال یا SecretRef لازم است حساب‌های پیکربندی‌شده را بدون بارگذاری کامل زمان اجرا شناسایی کنند. نقطهٔ ورود راه‌اندازی باید فرادادهٔ کانال را به‌همراه سازگارکننده‌های امن برای راه‌اندازیِ پیکربندی، وضعیت و اسرار ارائه کند؛ کلاینت‌های شبکه، شنونده‌های Gateway و زمان‌های اجرای انتقال را در نقطهٔ ورود افزونهٔ اصلی نگه دارید.

فیلدهای نقطهٔ ورود زمان اجرا، بررسی‌های مرز بسته برای فیلدهای نقطهٔ ورود منبع را بازنویسی نمی‌کنند. برای مثال، `openclaw.runtimeExtensions` نمی‌تواند مسیر `openclaw.extensions` خارج‌شونده از بسته را قابل بارگذاری کند.

`openclaw.install.allowInvalidConfigRecovery` عمداً محدود است. این گزینه پیکربندی‌های خراب دلخواه را قابل نصب نمی‌کند. در حال حاضر فقط به جریان‌های نصب اجازه می‌دهد از شکست‌های مشخص و قدیمی ارتقای Plugin همراه بازیابی شوند؛ مانند نبود مسیر Plugin همراه یا مدخل قدیمی `channels.<id>` برای همان Plugin همراه. خطاهای نامرتبط پیکربندی همچنان نصب را مسدود می‌کنند و راهبران را به `openclaw doctor --fix` هدایت می‌کنند.

`openclaw.channel.persistedAuthState` فرادادهٔ بسته برای یک ماژول بررسی‌کنندهٔ کوچک است:

```json
{
  "openclaw": {
    "channel": {
      "id": "whatsapp",
      "persistedAuthState": {
        "specifier": "./auth-presence",
        "exportName": "hasAnyWhatsAppAuth"
      }
    }
  }
}
```

از آن زمانی استفاده کنید که راه‌اندازی، doctor، وضعیت یا جریان‌های فقط‌خواندنی حضور، پیش از بارگذاری کامل Plugin کانال به یک بررسی ارزان بله/خیر برای احراز هویت نیاز دارند. وضعیت احراز هویت ماندگار با وضعیت کانال پیکربندی‌شده یکسان نیست: از این فراداده برای فعال‌سازی خودکار Pluginها، ترمیم وابستگی‌های زمان اجرا یا تصمیم‌گیری دربارهٔ بارگذاری زمان اجرای کانال استفاده نکنید. خروجی هدف باید تابع کوچکی باشد که فقط وضعیت ماندگار را می‌خواند؛ آن را از مسیر barrel کامل زمان اجرای کانال عبور ندهید.

`openclaw.channel.configuredState` برای بررسی‌های کم‌هزینهٔ وضعیت پیکربندی‌شدهٔ صرفاً مبتنی بر env از همین ساختار پیروی می‌کند:

```json
{
  "openclaw": {
    "channel": {
      "id": "telegram",
      "configuredState": {
        "specifier": "./configured-state",
        "exportName": "hasTelegramConfiguredState"
      }
    }
  }
}
```

از آن زمانی استفاده کنید که یک کانال بتواند وضعیت پیکربندی‌شده را از env یا ورودی‌های کوچک دیگرِ غیرزمان‌اجرا تعیین کند. اگر بررسی به وضوح کامل پیکربندی یا زمان اجرای واقعی کانال نیاز دارد، آن منطق را در هوک `config.hasConfiguredState` مربوط به Plugin نگه دارید.

## تقدم کشف (شناسه‌های تکراری Plugin)

OpenClaw، Pluginها را از سه ریشه کشف می‌کند که به این ترتیب بررسی می‌شوند: Pluginهای همراه عرضه‌شده با OpenClaw، ریشهٔ نصب سراسری (`~/.openclaw/extensions`) و ریشهٔ فضای کاری فعلی (`<workspace>/.openclaw/extensions`)، به‌علاوهٔ هر مدخل صریح `plugins.load.paths`.

اگر دو کشف `id` یکسانی داشته باشند، فقط مانیفست دارای **بالاترین تقدم** نگه داشته می‌شود؛ موارد تکراری با تقدم پایین‌تر به‌جای بارگذاری در کنار آن حذف می‌شوند. تقدم از بالاترین به پایین‌ترین:

1. **انتخاب‌شده با پیکربندی** — مسیری که به‌صراحت در `plugins.entries.<id>` ثابت شده است
2. **نصب سراسری منطبق با یک سابقهٔ نصب ردیابی‌شده** — Pluginی که از طریق `openclaw plugin install`/`openclaw plugin update` نصب شده و ردیابی نصب OpenClaw آن را برای همان شناسه تشخیص می‌دهد، حتی وقتی شناسه به یک Plugin همراه نیز تعلق دارد
3. **همراه** — Pluginهای عرضه‌شده با OpenClaw
4. **فضای کاری** — Pluginهایی که نسبت به فضای کاری فعلی کشف شده‌اند
5. هر نامزد کشف‌شدهٔ دیگر

پیامدها:

- یک نسخهٔ منشعب یا قدیمی از Plugin همراه که بدون ردیابی در فضای کاری یا ریشهٔ سراسری قرار دارد، نسخهٔ همراه را تحت‌الشعاع قرار نمی‌دهد.
- برای بازنویسی یک Plugin همراه، یا `openclaw plugin install` را برای آن شناسه اجرا کنید تا نصب سراسری ردیابی‌شده بر نسخهٔ همراه تقدم پیدا کند، یا مسیر مشخصی را از طریق `plugins.entries.<id>` ثابت کنید تا به‌واسطهٔ تقدم انتخاب‌شده با پیکربندی برنده شود.
- حذف موارد تکراری ثبت می‌شود تا Doctor و عیب‌یابی هنگام شروع بتوانند نسخهٔ کنار گذاشته‌شده را مشخص کنند.
- بازنویسی‌های تکراری انتخاب‌شده با پیکربندی در عیب‌یابی به‌عنوان بازنویسی‌های صریح بیان می‌شوند، اما همچنان هشدار می‌دهند تا انشعاب‌های قدیمی و تحت‌الشعاع‌قرارگیری‌های تصادفی قابل مشاهده بمانند.

## الزامات JSON Schema

- **هر Plugin باید یک JSON Schema ارائه کند**، حتی اگر هیچ پیکربندی‌ای نپذیرد.
- یک schema خالی قابل‌قبول است (برای مثال، `{ "type": "object", "additionalProperties": false }`).
- schemaها هنگام خواندن/نوشتن پیکربندی اعتبارسنجی می‌شوند، نه هنگام اجرا.
- هنگام گسترش یا انشعاب‌گرفتن از یک Plugin همراه و افزودن کلیدهای پیکربندی جدید، هم‌زمان `configSchema` آن Plugin را در `openclaw.plugin.json` به‌روزرسانی کنید. schemaهای Pluginهای همراه سخت‌گیرانه‌اند؛ بنابراین، افزودن `plugins.entries.<id>.config.myNewKey` به پیکربندی کاربر بدون افزودن `myNewKey` به `configSchema.properties`، پیش از بارگذاری زمان اجرای Plugin رد خواهد شد.

نمونهٔ گسترش schema:

```json
{
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "myNewKey": {
        "type": "string"
      }
    }
  }
}
```

## رفتار اعتبارسنجی

- کلیدهای ناشناختهٔ `channels.*` **خطا** هستند، مگر اینکه شناسهٔ کانال در مانیفست یک Plugin اعلام شده باشد. اگر همان شناسه در `plugins.allow`، `plugins.entries` یا `plugins.installs` نیز وجود داشته باشد (Pluginی که به آن ارجاع شده اما در حال حاضر قابل کشف نیست)، OpenClaw در عوض سطح آن را به **هشدار** کاهش می‌دهد.
- ارجاع `plugins.entries.<id>`، `plugins.allow` و `plugins.deny` به شناسه‌های ناشناختهٔ Plugin **هشدار** است («ورودی منسوخ پیکربندی نادیده گرفته شد»)، نه خطا؛ بنابراین ارتقاها و Pluginهای حذف‌شده یا تغییرنام‌یافته مانع راه‌اندازی Gateway نمی‌شوند.
- ارجاع `plugins.slots.memory` به شناسهٔ ناشناختهٔ Plugin **خطا** است، به‌جز Plugin خارجی رسمی و شناخته‌شدهٔ `memory-lancedb` که در عوض هشدار می‌دهد.
- اگر Pluginی نصب شده باشد اما مانیفست یا schema آن خراب یا مفقود باشد، اعتبارسنجی ناموفق می‌شود و Doctor خطای Plugin را گزارش می‌کند.
- اگر پیکربندی Plugin وجود داشته باشد اما Plugin **غیرفعال** باشد، پیکربندی حفظ می‌شود و یک **هشدار** در Doctor و گزارش‌ها نمایش داده می‌شود.

برای schema کامل `plugins.*`، [مرجع پیکربندی](/fa/gateway/configuration) را ببینید.

## نکته‌ها

- مانیفست برای **Pluginهای بومی OpenClaw الزامی است**، از جمله بارگذاری‌ها از فایل‌سیستم محلی. زمان اجرا همچنان ماژول Plugin را جداگانه بارگذاری می‌کند؛ مانیفست فقط برای کشف و اعتبارسنجی است.
- مانیفست‌های بومی با JSON5 تجزیه می‌شوند؛ بنابراین توضیحات، ویرگول‌های پایانی و کلیدهای بدون نقل‌قول پذیرفته می‌شوند، مشروط بر اینکه مقدار نهایی همچنان یک شیء باشد.
- بارگذار مانیفست فقط فیلدهای مستندشدهٔ مانیفست را می‌خواند. از کلیدهای سفارشی سطح‌بالا اجتناب کنید.
- وقتی Plugin به آن‌ها نیازی ندارد، همهٔ `channels`، `providers`، `cliBackends` و `skills` را می‌توان حذف کرد.
- `providerCatalogEntry` باید سبک باقی بماند و نباید کد گستردهٔ زمان اجرا را وارد کند؛ از آن برای فرادادهٔ ایستای فهرست ارائه‌دهندگان یا توصیفگرهای محدود کشف استفاده کنید، نه اجرای هنگام درخواست.
- گونه‌های انحصاری Plugin از طریق `plugins.slots.*` انتخاب می‌شوند: `kind: "memory"` از طریق `plugins.slots.memory` (پیش‌فرض `memory-core`) و `kind: "context-engine"` از طریق `plugins.slots.contextEngine` (پیش‌فرض `legacy`).
- گونهٔ انحصاری Plugin را در این مانیفست اعلام کنید. `OpenClawPluginDefinition.kind` در ورودی زمان اجرا منسوخ شده و فقط به‌عنوان راهکار سازگاری جایگزین برای Pluginهای قدیمی باقی مانده است.
- فرادادهٔ متغیر محیطی (`setup.providers[].envVars`، `providerAuthEnvVars` منسوخ‌شده و `channelEnvVars`) فقط جنبهٔ اعلامی دارد. وضعیت، ممیزی، اعتبارسنجی تحویل Cron و دیگر سطوح فقط‌خواندنی، پیش از پیکربندی‌شده تلقی‌کردن یک متغیر محیطی، همچنان سیاست اعتماد و فعال‌سازی مؤثر Plugin را اعمال می‌کنند.
- برای فرادادهٔ راهنمای زمان اجرا که به کد ارائه‌دهنده نیاز دارد، [قلاب‌های زمان اجرای ارائه‌دهنده](/fa/plugins/architecture-internals#provider-runtime-hooks) را ببینید.
- اگر Plugin شما به ماژول‌های بومی وابسته است، مراحل ساخت و هرگونه الزام فهرست مجاز مدیر بسته را مستند کنید (برای مثال، `allow-build-scripts` در pnpm به‌همراه `pnpm rebuild <package>`).

## مرتبط

<CardGroup cols={3}>
  <Card title="ساخت Pluginها" href="/fa/plugins/building-plugins" icon="rocket">
    آغاز کار با Pluginها.
  </Card>
  <Card title="معماری Plugin" href="/fa/plugins/architecture" icon="diagram-project">
    معماری داخلی و مدل قابلیت‌ها.
  </Card>
  <Card title="نمای کلی SDK" href="/fa/plugins/sdk-overview" icon="book">
    مرجع SDK مربوط به Plugin و واردکردن زیرمسیرها.
  </Card>
</CardGroup>