--- read_when: - شما در حال ساخت یک Plugin برای OpenClaw هستید - باید یک طرح‌واره پیکربندی Plugin منتشر کنید یا خطاهای اعتبارسنجی Plugin را اشکال‌زدایی کنید summary: الزامات مانیفست Plugin + طرحواره JSON (اعتبارسنجی سخت‌گیرانه پیکربندی) title: بیانیه Plugin x-i18n: generated_at: "2026-06-27T18:18:33Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: 62f6684ab074e4f14ce5c833fe8c8c624a2750f80215bdeffd972e27dd6bfc9c source_path: plugins/manifest.md workflow: 16 --- این صفحه فقط برای **مانیفست Plugin بومی OpenClaw** است. برای چیدمان‌های بسته سازگار، [بسته‌های 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 در حال حاضر فراداده بسته به‌علاوه ریشه‌های skill اعلام‌شده، ریشه‌های فرمان Claude، پیش‌فرض‌های `settings.json` بسته Claude، پیش‌فرض‌های LSP بسته Claude، و بسته‌های hook پشتیبانی‌شده را زمانی می‌خواند که چیدمان با انتظارات زمان اجرای OpenClaw مطابقت داشته باشد. هر 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، اعتبارسنجی پیکربندی، و راهنمایی‌های UI پیکربندی - فراداده auth، راه‌اندازی اولیه، و setup (alias، فعال‌سازی خودکار، متغیرهای محیطی provider، گزینه‌های auth) - راهنمایی‌های فعال‌سازی برای سطح‌های control-plane - مالکیت کوتاه‌نویسی خانواده مدل - snapshotهای ایستای مالکیت قابلیت (`contracts`) - فراداده اجراکننده QA که میزبان مشترک `openclaw qa` می‌تواند بررسی کند - فراداده پیکربندی مخصوص channel که در سطح‌های کاتالوگ و اعتبارسنجی ادغام می‌شود **برای این موارد از آن استفاده نکنید:** ثبت رفتار زمان اجرا، اعلام entrypointهای کد، یا فراداده نصب 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 ", "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.` استفاده می‌شود. | | `configSchema` | بله | `object` | JSON Schema درون‌خطی برای پیکربندی این 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` | خیر | `"memory"` \| `"context-engine"` | نوع انحصاری Plugin را که توسط `plugins.slots.*` استفاده می‌شود اعلام می‌کند. | | `channels` | خیر | `string[]` | شناسه‌های کانال متعلق به این Plugin. برای کشف و اعتبارسنجی پیکربندی استفاده می‌شود. | | `providers` | خیر | `string[]` | شناسه‌های ارائه‌دهنده متعلق به این Plugin. | | `providerCatalogEntry` | خیر | `string` | مسیر سبک ماژول کاتالوگ ارائه‌دهنده، نسبت به ریشهٔ Plugin، برای فرادادهٔ کاتالوگ ارائه‌دهنده در محدودهٔ manifest که بدون فعال‌سازی کامل زمان اجرای Plugin قابل بارگذاری است. | | `modelSupport` | خیر | `object` | فرادادهٔ کوتاه خانوادهٔ مدل که مالکیت آن با manifest است و برای بارگذاری خودکار Plugin پیش از زمان اجرا استفاده می‌شود. | | `modelCatalog` | خیر | `object` | فرادادهٔ اعلانی کاتالوگ مدل برای ارائه‌دهنده‌های متعلق به این Plugin. این قرارداد سطح کنترل برای فهرست‌کردن فقط‌خواندنی آینده، آنبوردینگ، انتخابگرهای مدل، نام‌های مستعار و سرکوب بدون بارگذاری زمان اجرای Plugin است. | | `modelPricing` | خیر | `object` | سیاست جست‌وجوی قیمت‌گذاری خارجی تحت مالکیت ارائه‌دهنده. از آن برای مستثنا کردن ارائه‌دهنده‌های محلی/خودمیزبان از کاتالوگ‌های قیمت‌گذاری راه‌دور یا نگاشت ارجاع‌های ارائه‌دهنده به شناسه‌های کاتالوگ OpenRouter/LiteLLM بدون هاردکد کردن شناسه‌های ارائه‌دهنده در هسته استفاده کنید. | | `modelIdNormalization` | خیر | `object` | پاک‌سازی نام مستعار/پیشوند شناسهٔ مدل تحت مالکیت ارائه‌دهنده که باید پیش از بارگذاری زمان اجرای ارائه‌دهنده اجرا شود. | | `providerEndpoints` | خیر | `object[]` | فرادادهٔ میزبان/baseUrl نقطهٔ پایانی تحت مالکیت manifest برای مسیرهای ارائه‌دهنده که هسته باید پیش از بارگذاری زمان اجرای ارائه‌دهنده طبقه‌بندی کند. | | `providerRequest` | خیر | `object` | فرادادهٔ سبک خانوادهٔ ارائه‌دهنده و سازگاری درخواست که توسط سیاست درخواست عمومی پیش از بارگذاری زمان اجرای ارائه‌دهنده استفاده می‌شود. | | `secretProviderIntegrations` | خیر | `Record` | پیش‌تنظیم‌های اعلانی ارائه‌دهندهٔ اجرای SecretRef که سطوح راه‌اندازی یا نصب می‌توانند بدون هاردکد کردن ادغام‌های مخصوص ارائه‌دهنده در هسته عرضه کنند. | | `cliBackends` | خیر | `string[]` | شناسه‌های بک‌اند استنتاج CLI متعلق به این Plugin. برای فعال‌سازی خودکار در شروع از ارجاع‌های پیکربندی صریح استفاده می‌شود. | | `syntheticAuthRefs` | خیر | `string[]` | ارجاع‌های ارائه‌دهنده یا بک‌اند CLI که قلاب احراز هویت مصنوعی تحت مالکیت Plugin باید هنگام کشف سرد مدل، پیش از بارگذاری زمان اجرا، بررسی شود. | | `nonSecretAuthMarkers` | خیر | `string[]` | مقادیر جای‌نگهدار کلید API تحت مالکیت Plugin همراه که وضعیت اعتبارنامهٔ محلی غیرمحرمانه، OAuth یا محیطی را نشان می‌دهند. | | `commandAliases` | خیر | `object[]` | نام‌های فرمان متعلق به این Plugin که باید پیش از بارگذاری زمان اجرا، عیب‌یابی‌های پیکربندی و CLI آگاه از Plugin تولید کنند. | | `providerAuthEnvVars` | خیر | `Record` | فرادادهٔ env منسوخ‌شدهٔ سازگاری برای جست‌وجوی احراز هویت/وضعیت ارائه‌دهنده. برای Pluginهای جدید `setup.providers[].envVars` را ترجیح دهید؛ OpenClaw همچنان در بازهٔ منسوخ‌سازی این را می‌خواند. | | `providerAuthAliases` | خیر | `Record` | شناسه‌های ارائه‌دهنده‌ای که باید برای جست‌وجوی احراز هویت از شناسهٔ ارائه‌دهندهٔ دیگری دوباره استفاده کنند؛ برای مثال ارائه‌دهندهٔ کدنویسی که کلید API و پروفایل‌های احراز هویت ارائه‌دهندهٔ پایه را به اشتراک می‌گذارد. | | `channelEnvVars` | خیر | `Record` | فرادادهٔ سبک env کانال که OpenClaw می‌تواند بدون بارگذاری کد Plugin بررسی کند. از این برای راه‌اندازی کانال مبتنی بر env یا سطوح احراز هویتی استفاده کنید که کمک‌کننده‌های عمومی شروع/پیکربندی باید ببینند. | | `providerAuthChoices` | خیر | `object[]` | فرادادهٔ سبک گزینهٔ احراز هویت برای انتخابگرهای آنبوردینگ، حل ارائه‌دهندهٔ ترجیحی و سیم‌کشی سادهٔ پرچم CLI. | | `activation` | خیر | `object` | فرادادهٔ سبک برنامه‌ریز فعال‌سازی برای بارگذاری‌های شروع، ارائه‌دهنده، فرمان، کانال، مسیر و قابلیت‌محور. فقط فراداده است؛ زمان اجرای Plugin همچنان مالک رفتار واقعی است. | | `setup` | خیر | `object` | توصیفگرهای سبک راه‌اندازی/آنبوردینگ که سطوح کشف و راه‌اندازی می‌توانند بدون بارگذاری زمان اجرای Plugin بررسی کنند. | | `qaRunners` | خیر | `object[]` | توصیفگرهای سبک اجراکنندهٔ QA که میزبان مشترک `openclaw qa` پیش از بارگذاری زمان اجرای Plugin استفاده می‌کند. | | `contracts` | خیر | `object` | نمای ثابت مالکیت قابلیت برای قلاب‌های احراز هویت خارجی، embeddings، گفتار، رونویسی بلادرنگ، صدای بلادرنگ، درک رسانه، تولید تصویر، تولید موسیقی، تولید ویدیو، واکشی وب، جست‌وجوی وب و مالکیت ابزار. | | `mediaUnderstandingProviderMetadata` | خیر | `Record` | پیش‌فرض‌های سبک درک رسانه برای شناسه‌های ارائه‌دهنده اعلام‌شده در `contracts.mediaUnderstandingProviders`. | | `imageGenerationProviderMetadata` | خیر | `Record` | فرادادهٔ سبک احراز هویت تولید تصویر برای شناسه‌های ارائه‌دهنده اعلام‌شده در `contracts.imageGenerationProviders`، شامل نام‌های مستعار احراز هویت تحت مالکیت ارائه‌دهنده و محافظ‌های base-url. | | `videoGenerationProviderMetadata` | خیر | `Record` | فرادادهٔ سبک احراز هویت تولید ویدیو برای شناسه‌های ارائه‌دهنده اعلام‌شده در `contracts.videoGenerationProviders`، شامل نام‌های مستعار احراز هویت تحت مالکیت ارائه‌دهنده و محافظ‌های base-url. | | `musicGenerationProviderMetadata` | خیر | `Record` | فرادادهٔ سبک احراز هویت تولید موسیقی برای شناسه‌های ارائه‌دهنده اعلام‌شده در `contracts.musicGenerationProviders`، شامل نام‌های مستعار احراز هویت تحت مالکیت ارائه‌دهنده و محافظ‌های base-url. | | `toolMetadata` | No | `Record` | فرادادهٔ ارزانِ دسترس‌پذیری برای ابزارهای متعلق به Plugin که در `contracts.tools` اعلام شده‌اند. زمانی از آن استفاده کنید که یک ابزار نباید runtime را بارگذاری کند مگر اینکه شواهد config، env یا auth وجود داشته باشد. | | `channelConfigs` | No | `Record` | فرادادهٔ پیکربندی کانالِ متعلق به manifest که پیش از بارگذاری runtime در سطح‌های کشف و اعتبارسنجی ادغام می‌شود. | | `skills` | No | `string[]` | پوشه‌های Skill برای بارگذاری، نسبی به ریشهٔ Plugin. | | `name` | No | `string` | نام خوانای انسانی Plugin. | | `description` | No | `string` | خلاصهٔ کوتاهی که در سطح‌های Plugin نمایش داده می‌شود. | | `icon` | No | `string` | URL تصویر HTTPS برای کارت‌های بازارچه/کاتالوگ. ClawHub هر URL معتبر `https://` را می‌پذیرد و وقتی این مورد حذف شده یا نامعتبر باشد، به آیکون پیش‌فرض Plugin بازمی‌گردد. | | `version` | No | `string` | نسخهٔ اطلاعاتی Plugin. | | `uiHints` | No | `Record` | برچسب‌های UI، جای‌نگهدارها، و راهنمایی‌های حساسیت برای فیلدهای config. | ## مرجع فرادادهٔ ارائه‌دهندهٔ تولید فیلدهای فرادادهٔ ارائه‌دهندهٔ تولید، نشانه‌های احراز هویت ایستای ارائه‌دهنده‌هایی را توصیف می‌کنند که در فهرست متناظر `contracts.*GenerationProviders` اعلام شده‌اند. OpenClaw این فیلدها را پیش از بارگذاری runtime ارائه‌دهنده می‌خواند تا ابزارهای هسته بتوانند بدون وارد کردن هر Plugin ارائه‌دهنده، تصمیم بگیرند که آیا یک ارائه‌دهندهٔ تولید در دسترس است یا نه. از این فیلدها فقط برای واقعیت‌های ارزان و اعلانی استفاده کنید. انتقال، تبدیل‌های درخواست، تازه‌سازی توکن، اعتبارسنجی اعتبارنامه، و رفتار واقعی تولید در runtime 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` | مسیر نقطه‌ای داخل پیکربندی ریشه که شیء آن باید پیش از ارزیابی نشانه روی شیء ریشه overlay شود. از این برای پیکربندی ویژهٔ قابلیت، مانند `image`، `video`، یا `music` استفاده کنید. | | `overlayMapPath` | خیر | `string` | مسیر نقطه‌ای داخل پیکربندی ریشه که مقدارهای شیء آن باید هرکدام روی شیء ریشه overlay شوند. از این برای نگاشت‌های حساب نام‌گذاری‌شده مانند `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 بتواند از وارد کردن runtime یک Plugin فقط برای اینکه کارخانهٔ ابزار آن `null` برگرداند، پرهیز کند. ```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` نداشته باشد، OpenClaw رفتار موجود را حفظ می‌کند و وقتی قرارداد ابزار با خط‌مشی مطابقت داشته باشد، Plugin مالک را بارگذاری می‌کند. برای ابزارهای مسیر پرتکرار که کارخانهٔ آن‌ها به احراز هویت/پیکربندی وابسته است، نویسندگان Plugin باید به‌جای اینکه هسته برای پرسیدن runtime را وارد کند، `toolMetadata` را اعلام کنند. ## مرجع `providerAuthChoices` هر ورودی `providerAuthChoices` یک گزینهٔ onboarding یا احراز هویت را توصیف می‌کند. OpenClaw این را پیش از بارگذاری runtime ارائه‌دهنده می‌خواند. فهرست‌های راه‌اندازی ارائه‌دهنده، از این گزینه‌های manifest، گزینه‌های راه‌اندازی مشتق‌شده از descriptor، و فرادادهٔ install-catalog بدون بارگذاری runtime ارائه‌دهنده استفاده می‌کنند. | فیلد | الزامی | نوع | معنی آن | | --------------------- | -------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | `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` | متن راهنمای کوتاه برای گروه. | | `optionKey` | خیر | `string` | کلید گزینه داخلی برای جریان‌های احراز هویت ساده تک‌پرچمی. | | `cliFlag` | خیر | `string` | نام پرچم CLI، مانند `--openrouter-api-key`. | | `cliOption` | خیر | `string` | شکل کامل گزینه CLI، مانند `--openrouter-api-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های نامزد پیش از بازگشت به فراداده مالکیت موجود در manifest مانند `providers`، `channels`، `commandAliases`، `setup.providers`، `contracts.tools` و hookها استفاده می‌کند. باریک‌ترین فراداده‌ای را ترجیح دهید که از قبل مالکیت را توصیف می‌کند. وقتی این فیلدها رابطه را بیان می‌کنند، از `providers`، `channels`، `commandAliases`، توصیف‌گرهای setup یا `contracts` استفاده کنید. برای راهنمایی‌های اضافی برنامه‌ریز که با آن فیلدهای مالکیت قابل نمایش نیستند، از `activation` استفاده کنید. برای نام‌های مستعار زمان اجرای CLI مانند `claude-cli`، `my-cli` یا `google-gemini-cli` از `cliBackends` سطح بالا استفاده کنید؛ `activation.onAgentHarnesses` فقط برای شناسه‌های harness عامل تعبیه‌شده‌ای است که از قبل فیلد مالکیت ندارند. این بلوک فقط فراداده است. رفتار زمان اجرا را ثبت نمی‌کند، و جایگزین `register(...)`، `setupEntry` یا دیگر نقطه‌های ورود زمان اجرا/Plugin نمی‌شود. مصرف‌کنندگان فعلی از آن به‌عنوان راهنمای محدودسازی پیش از بارگذاری گسترده‌تر Plugin استفاده می‌کنند، بنابراین نبود فراداده فعال‌سازی غیرراه‌اندازی معمولاً فقط هزینه عملکرد دارد؛ تا وقتی fallbackهای مالکیت manifest همچنان وجود دارند، نباید درستی را تغییر دهد. هر Plugin باید `activation.onStartup` را آگاهانه تنظیم کند. فقط زمانی آن را روی `true` تنظیم کنید که Plugin باید هنگام راه‌اندازی Gateway اجرا شود. وقتی Plugin هنگام راه‌اندازی غیرفعال است و باید فقط از محرک‌های باریک‌تر بارگذاری شود، آن را روی `false` تنظیم کنید. حذف `onStartup` دیگر به‌طور ضمنی Plugin را در زمان راه‌اندازی بارگذاری نمی‌کند؛ برای راه‌اندازی، کانال، پیکربندی، agent-harness، حافظه یا دیگر محرک‌های فعال‌سازی باریک‌تر، از فراداده فعال‌سازی صریح استفاده کنید. ```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` آن را در راه‌اندازی lazy نگه می‌دارد، مگر اینکه محرک منطبق دیگری نیازمند بارگذاری باشد. | | `onProviders` | خیر | `string[]` | شناسه‌های ارائه‌دهنده که باید این Plugin را در برنامه‌های فعال‌سازی/بارگذاری لحاظ کنند. | | `onAgentHarnesses` | خیر | `string[]` | شناسه‌های زمان اجرای harness عامل تعبیه‌شده که باید این Plugin را در برنامه‌های فعال‌سازی/بارگذاری لحاظ کنند. برای نام‌های مستعار backendهای CLI از `cliBackends` سطح بالا استفاده کنید. | | `onCommands` | خیر | `string[]` | شناسه‌های فرمان که باید این Plugin را در برنامه‌های فعال‌سازی/بارگذاری لحاظ کنند. | | `onChannels` | خیر | `string[]` | شناسه‌های کانال که باید این Plugin را در برنامه‌های فعال‌سازی/بارگذاری لحاظ کنند. | | `onRoutes` | خیر | `string[]` | گونه‌های route که باید این Plugin را در برنامه‌های فعال‌سازی/بارگذاری لحاظ کنند. | | `onConfigPaths` | خیر | `string[]` | مسیرهای پیکربندی نسبت به ریشه که وقتی مسیر وجود دارد و صریحاً غیرفعال نشده است، باید این Plugin را در برنامه‌های راه‌اندازی/بارگذاری لحاظ کنند. | | `onCapabilities` | خیر | `Array<"provider" \| "channel" \| "tool" \| "hook">` | راهنمایی‌های گسترده قابلیت که توسط برنامه‌ریزی فعال‌سازی صفحه کنترل استفاده می‌شود. هرجا ممکن است، فیلدهای باریک‌تر را ترجیح دهید. | مصرف‌کنندگان زنده فعلی: - برنامه‌ریزی راه‌اندازی Gateway از `activation.onStartup` برای import صریح هنگام راه‌اندازی استفاده می‌کند - برنامه‌ریزی CLI برانگیخته‌شده با فرمان به `commandAliases[].cliCommand` یا `commandAliases[].name` قدیمی برمی‌گردد - برنامه‌ریزی راه‌اندازی agent-runtime از `activation.onAgentHarnesses` برای harnessهای تعبیه‌شده و از `cliBackends[]` سطح بالا برای نام‌های مستعار زمان اجرای CLI استفاده می‌کند - برنامه‌ریزی setup/channel برانگیخته‌شده با کانال، وقتی فراداده فعال‌سازی صریح کانال موجود نیست، به مالکیت قدیمی `channels[]` برمی‌گردد - برنامه‌ریزی Plugin هنگام راه‌اندازی از `activation.onConfigPaths` برای سطوح پیکربندی ریشه غیرکانالی مانند بلوک `browser` در Plugin مرورگر bundled استفاده می‌کند - برنامه‌ریزی setup/runtime برانگیخته‌شده با ارائه‌دهنده، وقتی فراداده فعال‌سازی صریح ارائه‌دهنده موجود نیست، به مالکیت قدیمی `providers[]` و `cliBackends[]` سطح بالا برمی‌گردد عیب‌یابی‌های برنامه‌ریز می‌توانند راهنمایی‌های فعال‌سازی صریح را از fallback مالکیت manifest تشخیص دهند. برای مثال، `activation-command-hint` یعنی `activation.onCommands` منطبق شده است، در حالی که `manifest-command-alias` یعنی برنامه‌ریز به‌جای آن از مالکیت `commandAliases` استفاده کرده است. این برچسب‌های دلیل برای عیب‌یابی میزبان و آزمون‌ها هستند؛ نویسندگان Plugin باید همچنان فراداده‌ای را اعلام کنند که مالکیت را به بهترین شکل توصیف می‌کند. ## مرجع `qaRunners` وقتی یک Plugin یک یا چند runner انتقال را زیر ریشه مشترک `openclaw qa` اضافه می‌کند، از `qaRunners` استفاده کنید. این فراداده را کم‌هزینه و ایستا نگه دارید؛ زمان اجرای Plugin همچنان مالک ثبت واقعی CLI از طریق یک سطح سبک `runtime-api.ts` است که `qaRunnerCliRegistrations` را صادر می‌کند. ```json { "qaRunners": [ { "commandName": "matrix", "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver" } ] } ``` | فیلد | الزامی | نوع | معنی آن | | ------------- | ------ | -------- | ------------------------------------------------------------------ | | `commandName` | بله | `string` | زیرفرمانی که زیر `openclaw qa` نصب می‌شود، برای مثال `matrix`. | | `description` | خیر | `string` | متن راهنمای پشتیبان که وقتی میزبان مشترک به یک فرمان stub نیاز دارد استفاده می‌شود. | ## مرجع setup از `setup` زمانی استفاده کنید که سطح‌های راه‌اندازی و شروع به کار، پیش از بارگذاری runtime، به فراداده ارزان و متعلق به 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` سطح بالا همچنان معتبر می‌ماند و به توصیف backendهای استنتاج CLI ادامه می‌دهد. `setup.cliBackends` سطح توصیفگر ویژه راه‌اندازی برای جریان‌های control-plane/setup است که باید فقط فراداده باقی بمانند. وقتی وجود داشته باشند، `setup.providers` و `setup.cliBackends` سطح ترجیحی جست‌وجوی descriptor-first برای کشف setup هستند. اگر توصیفگر فقط plugin نامزد را محدود می‌کند و setup هنوز به hookهای runtime غنی‌تر در زمان setup نیاز دارد، `requiresRuntime: true` را تنظیم کنید و `setup-api` را به‌عنوان مسیر اجرای پشتیبان نگه دارید. OpenClaw همچنین `setup.providers[].envVars` را در احراز هویت عمومی provider و جست‌وجوهای env-var وارد می‌کند. `providerAuthEnvVars` در طول بازه منسوخ‌سازی همچنان از طریق یک adapter سازگاری پشتیبانی می‌شود، اما pluginهای غیر bundled که هنوز از آن استفاده می‌کنند یک diagnostic مانیفست دریافت می‌کنند. pluginهای جدید باید فراداده env مربوط به setup/status را روی `setup.providers[].envVars` قرار دهند. OpenClaw همچنین می‌تواند انتخاب‌های setup ساده را از `setup.providers[].authMethods` استخراج کند، وقتی هیچ ورودی setup موجود نیست، یا وقتی `setup.requiresRuntime: false` اعلام می‌کند runtime setup لازم نیست. ورودی‌های صریح `providerAuthChoices` برای برچسب‌های سفارشی، flagهای CLI، دامنه onboarding، و فراداده assistant همچنان ترجیح داده می‌شوند. `requiresRuntime: false` را فقط زمانی تنظیم کنید که آن توصیفگرها برای سطح setup کافی باشند. OpenClaw مقدار صریح `false` را به‌عنوان یک قرارداد فقط-توصیفگر در نظر می‌گیرد و برای جست‌وجوی setup، `setup-api` یا `openclaw.setupEntry` را اجرا نمی‌کند. اگر یک plugin فقط-توصیفگر همچنان یکی از آن ورودی‌های runtime مربوط به setup را منتشر کند، OpenClaw یک diagnostic افزایشی گزارش می‌کند و به نادیده گرفتن آن ادامه می‌دهد. حذف `requiresRuntime` رفتار پشتیبان legacy را حفظ می‌کند تا pluginهای موجود که توصیفگرها را بدون این flag اضافه کرده‌اند خراب نشوند. از آنجا که جست‌وجوی setup می‌تواند کد `setup-api` متعلق به plugin را اجرا کند، مقادیر نرمال‌شده `setup.providers[].id` و `setup.cliBackends[]` باید در میان pluginهای کشف‌شده یکتا بمانند. مالکیت مبهم به‌جای انتخاب یک برنده از ترتیب کشف، به‌صورت fail closed شکست می‌خورد. وقتی runtime setup اجرا می‌شود، diagnosticهای registry مربوط به setup در صورتی drift توصیفگر را گزارش می‌کنند که `setup-api` یک provider یا backend CLI را ثبت کند که توصیفگرهای مانیفست اعلام نکرده‌اند، یا اگر یک توصیفگر registration متناظر در runtime نداشته باشد. این diagnosticها افزایشی هستند و pluginهای legacy را رد نمی‌کنند. ### مرجع setup.providers | فیلد | الزامی | نوع | معنی آن | | -------------- | ------ | ---------- | --------------------------------------------------------------------------------------------- | | `id` | بله | `string` | شناسه provider که در طول setup یا onboarding در دسترس قرار می‌گیرد. شناسه‌های نرمال‌شده را در سطح جهانی یکتا نگه دارید. | | `authMethods` | خیر | `string[]` | شناسه‌های روش setup/auth که این provider بدون بارگذاری کامل runtime پشتیبانی می‌کند. | | `envVars` | خیر | `string[]` | env varهایی که سطح‌های عمومی setup/status می‌توانند پیش از بارگذاری runtime plugin بررسی کنند. | | `authEvidence` | خیر | `object[]` | بررسی‌های ارزان شواهد احراز هویت محلی برای providerهایی که می‌توانند از طریق نشانگرهای غیرمحرمانه احراز هویت کنند. | `authEvidence` برای نشانگرهای credential محلی متعلق به provider است که می‌توانند بدون بارگذاری کد runtime تأیید شوند. این بررسی‌ها باید ارزان و محلی بمانند: بدون فراخوانی شبکه، بدون خواندن keychain یا secret-manager، بدون فرمان shell، و بدون probeهای API provider. ورودی‌های evidence پشتیبانی‌شده: | فیلد | الزامی | نوع | معنی آن | | ------------------ | ------ | ---------- | --------------------------------------------------------------------------------------------------------- | | `type` | بله | `string` | در حال حاضر `local-file-with-env`. | | `fileEnvVar` | خیر | `string` | env var حاوی مسیر صریح فایل credential. | | `fallbackPaths` | خیر | `string[]` | مسیرهای فایل credential محلی که وقتی `fileEnvVar` غایب یا خالی است بررسی می‌شوند. از `${HOME}` و `${APPDATA}` پشتیبانی می‌کند. | | `requiresAnyEnv` | خیر | `string[]` | پیش از معتبر بودن evidence، حداقل یکی از env varهای فهرست‌شده باید غیرخالی باشد. | | `requiresAllEnv` | خیر | `string[]` | پیش از معتبر بودن evidence، همه env varهای فهرست‌شده باید غیرخالی باشند. | | `credentialMarker` | بله | `string` | نشانگر غیرمحرمانه‌ای که هنگام وجود evidence برگردانده می‌شود. | | `source` | خیر | `string` | برچسب منبع کاربر-نما برای خروجی auth/status. | ### فیلدهای setup | فیلد | الزامی | نوع | معنی آن | | ------------------ | ------ | ---------- | ----------------------------------------------------------------------------------------------- | | `providers` | خیر | `object[]` | توصیفگرهای setup مربوط به provider که در طول setup و onboarding در دسترس قرار می‌گیرند. | | `cliBackends` | خیر | `string[]` | شناسه‌های backend زمان setup که برای جست‌وجوی setup به روش descriptor-first استفاده می‌شوند. شناسه‌های نرمال‌شده را در سطح جهانی یکتا نگه دارید. | | `configMigrations` | خیر | `string[]` | شناسه‌های migration پیکربندی که متعلق به سطح setup این plugin هستند. | | `requiresRuntime` | خیر | `boolean` | اینکه آیا setup پس از جست‌وجوی توصیفگر هنوز به اجرای `setup-api` نیاز دارد یا نه. | ## مرجع uiHints `uiHints` نگاشتی از نام فیلدهای پیکربندی به hintهای کوچک rendering است. ```json { "uiHints": { "apiKey": { "label": "API key", "help": "Used for OpenRouter requests", "placeholder": "sk-or-v1-...", "sensitive": true } } } ``` هر hint فیلد می‌تواند شامل موارد زیر باشد: | فیلد | نوع | معنی آن | | ------------- | ---------- | ------------------------------------- | | `label` | `string` | برچسب فیلد کاربر-نما. | | `help` | `string` | متن کمکی کوتاه. | | `tags` | `string[]` | تگ‌های اختیاری UI. | | `advanced` | `boolean` | فیلد را به‌عنوان پیشرفته علامت‌گذاری می‌کند. | | `sensitive` | `boolean` | فیلد را به‌عنوان محرمانه یا حساس علامت‌گذاری می‌کند. | | `placeholder` | `string` | متن placeholder برای ورودی‌های فرم. | ## مرجع contracts از `contracts` فقط برای فراداده ایستای مالکیت قابلیت استفاده کنید که OpenClaw می‌تواند بدون import کردن runtime plugin آن را بخواند. ```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"], "webFetchProviders": ["firecrawl"], "webSearchProviders": ["gemini"], "migrationProviders": ["hermes"], "gatewayMethodDispatch": ["authenticated-request"], "tools": ["firecrawl_search", "firecrawl_scrape"] } } ``` هر فهرست اختیاری است: | فیلد | نوع | معنی آن | | -------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `embeddedExtensionFactories` | `string[]` | شناسه‌های کارخانه extension سرور برنامه Codex، در حال حاضر `codex-app-server`. | | `agentToolResultMiddleware` | `string[]` | شناسه‌های زمان اجرا که این Plugin می‌تواند برای آن‌ها middleware نتیجه ابزار ثبت کند. | | `trustedToolPolicies` | `string[]` | شناسه‌های سیاست محلیِ قابل اعتمادِ پیش از ابزار که یک Plugin نصب‌شده می‌تواند ثبت کند. Pluginهای باندل‌شده می‌توانند سیاست‌ها را بدون این فیلد ثبت کنند. | | `externalAuthProviders` | `string[]` | شناسه‌های ارائه‌دهنده‌ای که hook پروفایل احراز هویت خارجی آن‌ها متعلق به این Plugin است. | | `embeddingProviders` | `string[]` | شناسه‌های ارائه‌دهنده embedding عمومی که این Plugin برای استفاده دوباره از embedding برداری، از جمله حافظه، مالک آن‌ها است. | | `speechProviders` | `string[]` | شناسه‌های ارائه‌دهنده گفتار که این Plugin مالک آن‌ها است. | | `realtimeTranscriptionProviders` | `string[]` | شناسه‌های ارائه‌دهنده رونویسی بی‌درنگ که این Plugin مالک آن‌ها است. | | `realtimeVoiceProviders` | `string[]` | شناسه‌های ارائه‌دهنده صدای بی‌درنگ که این Plugin مالک آن‌ها است. | | `memoryEmbeddingProviders` | `string[]` | شناسه‌های منسوخ‌شده ارائه‌دهنده embedding مخصوص حافظه که این Plugin مالک آن‌ها است. | | `mediaUnderstandingProviders` | `string[]` | شناسه‌های ارائه‌دهنده درک رسانه که این Plugin مالک آن‌ها است. | | `transcriptSourceProviders` | `string[]` | شناسه‌های ارائه‌دهنده منبع transcript که این Plugin مالک آن‌ها است. | | `imageGenerationProviders` | `string[]` | شناسه‌های ارائه‌دهنده تولید تصویر که این Plugin مالک آن‌ها است. | | `videoGenerationProviders` | `string[]` | شناسه‌های ارائه‌دهنده تولید ویدئو که این Plugin مالک آن‌ها است. | | `webFetchProviders` | `string[]` | شناسه‌های ارائه‌دهنده fetch وب که این Plugin مالک آن‌ها است. | | `webSearchProviders` | `string[]` | شناسه‌های ارائه‌دهنده جست‌وجوی وب که این Plugin مالک آن‌ها است. | | `migrationProviders` | `string[]` | شناسه‌های ارائه‌دهنده import که این Plugin برای `openclaw migrate` مالک آن‌ها است. | | `gatewayMethodDispatch` | `string[]` | حق دسترسی رزروشده برای مسیرهای HTTP احراز هویت‌شده Plugin که متدهای Gateway را درون فرایند dispatch می‌کنند. | | `tools` | `string[]` | نام ابزارهای عامل که این Plugin مالک آن‌ها است. | `contracts.embeddedExtensionFactories` برای کارخانه‌های extension فقط مخصوص سرور برنامه Codex باندل‌شده حفظ شده است. تبدیل‌های نتیجه ابزار باندل‌شده باید به‌جای آن `contracts.agentToolResultMiddleware` را اعلام کنند و با `api.registerAgentToolResultMiddleware(...)` ثبت شوند. Pluginهای نصب‌شده فقط زمانی می‌توانند از همین seam میان‌افزار استفاده کنند که صریحا فعال شده باشد و فقط برای زمان‌اجراهایی که در `contracts.agentToolResultMiddleware` اعلام می‌کنند. Pluginهای نصب‌شده‌ای که به رده سیاست پیش از ابزارِ مورد اعتماد میزبان نیاز دارند، باید هر شناسه محلی ثبت‌شده را در `contracts.trustedToolPolicies` اعلام کنند و صریحا فعال شوند. Pluginهای باندل‌شده مسیر سیاست مورد اعتماد موجود را حفظ می‌کنند، اما Pluginهای نصب‌شده با شناسه‌های سیاست اعلام‌نشده پیش از ثبت رد می‌شوند. شناسه‌های سیاست در محدوده Plugin ثبت‌کننده هستند، بنابراین دو Plugin می‌توانند هر دو `workflow-budget` را اعلام و ثبت کنند؛ یک Plugin واحد نمی‌تواند یک شناسه محلی یکسان را دو بار ثبت کند. ثبت‌های زمان اجرای `api.registerTool(...)` باید با `contracts.tools` منطبق باشند. کشف ابزار از این فهرست استفاده می‌کند تا فقط زمان‌اجراهای Pluginهایی را بارگذاری کند که می‌توانند مالک ابزارهای درخواست‌شده باشند. Pluginهای ارائه‌دهنده‌ای که `resolveExternalAuthProfiles` را پیاده‌سازی می‌کنند باید `contracts.externalAuthProviders` را اعلام کنند؛ hookهای احراز هویت خارجی اعلام‌نشده نادیده گرفته می‌شوند. ارائه‌دهندگان embedding عمومی باید برای هر adapter ثبت‌شده با `api.registerEmbeddingProvider(...)` مقدار `contracts.embeddingProviders` را اعلام کنند. برای تولید بردار قابل استفاده دوباره، از جمله ارائه‌دهندگانی که جست‌وجوی حافظه مصرف می‌کند، از قرارداد عمومی استفاده کنید. `contracts.memoryEmbeddingProviders` سازگاری منسوخ‌شده مخصوص حافظه است و فقط تا زمان مهاجرت ارائه‌دهندگان موجود به seam عمومی ارائه‌دهنده embedding باقی می‌ماند. `contracts.gatewayMethodDispatch` در حال حاضر `"authenticated-request"` را می‌پذیرد. این یک دروازه بهداشت API برای مسیرهای HTTP بومی Plugin است که عمدا متدهای صفحه کنترل Gateway را درون فرایند dispatch می‌کنند، نه یک sandbox در برابر Pluginهای بومی مخرب. آن را فقط برای سطح‌های باندل‌شده/اپراتوری کاملا بازبینی‌شده‌ای استفاده کنید که از قبل به احراز هویت HTTP Gateway نیاز دارند. ## مرجع mediaUnderstandingProviderMetadata وقتی یک ارائه‌دهنده درک رسانه مدل‌های پیش‌فرض، اولویت fallback احراز هویت خودکار، یا پشتیبانی بومی سند دارد که helperهای عمومی core پیش از بارگذاری زمان اجرا به آن نیاز دارند، از `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"] } } } ``` هر ورودی ارائه‌دهنده می‌تواند شامل موارد زیر باشد: | فیلد | نوع | معنی آن | | ---------------------- | ----------------------------------- | ---------------------------------------------------------------------------- | | `capabilities` | `("image" \| "audio" \| "video")[]` | قابلیت‌های رسانه‌ای که این ارائه‌دهنده در معرض استفاده قرار می‌دهد. | | `defaultModels` | `Record` | پیش‌فرض‌های قابلیت به مدل که وقتی config مدلی مشخص نکرده استفاده می‌شوند. | | `autoPriority` | `Record` | عددهای کمتر برای fallback خودکار ارائه‌دهنده بر پایه credential زودتر مرتب می‌شوند. | | `nativeDocumentInputs` | `"pdf"[]` | ورودی‌های سند بومی که ارائه‌دهنده پشتیبانی می‌کند. | ## مرجع channelConfigs وقتی یک Plugin کانال پیش از بارگذاری زمان اجرا به metadata ارزان config نیاز دارد، از `channelConfigs` استفاده کنید. کشف فقط‌خواندنی راه‌اندازی/وضعیت کانال می‌تواند برای کانال‌های خارجی پیکربندی‌شده، وقتی ورودی راه‌اندازی در دسترس نیست، یا وقتی `setup.requiresRuntime: false` اعلام می‌کند زمان اجرای راه‌اندازی لازم نیست، مستقیما از این metadata استفاده کند. `channelConfigs` metadata manifest Plugin است، نه یک بخش جدید config کاربر در سطح بالا. کاربران همچنان نمونه‌های کانال را زیر `channels.` پیکربندی می‌کنند. OpenClaw metadata manifest را می‌خواند تا پیش از اجرای کد زمان اجرای Plugin تصمیم بگیرد کدام Plugin مالک آن کانال پیکربندی‌شده است. برای یک Plugin کانال، `configSchema` و `channelConfigs` مسیرهای متفاوتی را توصیف می‌کنند: - `configSchema` مقدار `plugins.entries..config` را اعتبارسنجی می‌کند - `channelConfigs..schema` مقدار `channels.` را اعتبارسنجی می‌کند Pluginهای غیرباندل‌شده‌ای که `channels[]` را اعلام می‌کنند، باید ورودی‌های منطبق `channelConfigs` را نیز اعلام کنند. بدون آن‌ها، OpenClaw همچنان می‌تواند Plugin را بارگذاری کند، اما schema config مسیر سرد، راه‌اندازی، و سطح‌های Control UI نمی‌توانند شکل گزینه‌های متعلق به کانال را تا زمان اجرای زمان اجرای Plugin بدانند. `channelConfigs..commands.nativeCommandsAutoEnabled` و `nativeSkillsAutoEnabled` می‌توانند پیش‌فرض‌های ثابت `auto` را برای بررسی‌های config فرمان اعلام کنند که پیش از بارگذاری زمان اجرای کانال اجرا می‌شوند. کانال‌های باندل‌شده نیز می‌توانند همین پیش‌فرض‌ها را از طریق `package.json#openclaw.channel.commands` در کنار سایر metadata کاتالوگ کانال متعلق به package خود منتشر کنند. ```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 Schema برای `channels.`. برای هر ورودی config کانال اعلام‌شده الزامی است. | | `uiHints` | `Record` | برچسب‌ها/placeholderها/راهنماهای حساس اختیاری UI برای آن بخش config کانال. | | `label` | `string` | برچسب کانال که وقتی metadata زمان اجرا آماده نیست، در سطح‌های انتخاب‌گر و inspect ادغام می‌شود. | | `description` | `string` | توضیح کوتاه کانال برای سطح‌های inspect و کاتالوگ. | | `commands` | `object` | پیش‌فرض‌های خودکار ثابت برای فرمان بومی و skill بومی، برای بررسی‌های config پیش از زمان اجرا. | | `preferOver` | `string[]` | شناسه‌های Plugin قدیمی یا کم‌اولویت‌تری که این کانال باید در سطح‌های انتخاب بر آن‌ها اولویت داشته باشد. | ### جایگزینی یک Plugin کانال دیگر وقتی Plugin شما مالک ترجیحی برای یک شناسه کانال است که یک Plugin دیگر نیز می‌تواند آن را فراهم کند، از `preferOver` استفاده کنید. موارد رایج شامل شناسه Plugin تغییرنام‌یافته، Plugin مستقل که جایگزین یک Plugin باندل‌شده می‌شود، یا fork نگه‌داری‌شده‌ای است که همان شناسه کانال را برای سازگاری config حفظ می‌کند. ```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 آن را در config موثر زمان اجرا غیرفعال می‌کند تا یک Plugin مالک کانال و ابزارهای آن باشد. انتخاب صریح کاربر همچنان برنده است: اگر کاربر هر دو Plugin را صریحا فعال کند، OpenClaw آن انتخاب را حفظ می‌کند و به‌جای تغییر بی‌صدای مجموعه Pluginهای درخواست‌شده، diagnostics کانال/ابزار تکراری را گزارش می‌دهد. `preferOver` را به شناسه‌های Pluginهایی محدود نگه دارید که واقعا می‌توانند همان کانال را فراهم کنند. این یک فیلد اولویت عمومی نیست و کلیدهای config کاربر را تغییرنام نمی‌دهد. ## مرجع modelSupport از `modelSupport` زمانی استفاده کنید که OpenClaw باید پیش از بارگذاری زمان اجرای Plugin، Plugin ارائه‌دهنده را از شناسه‌های کوتاه مدل مانند `gpt-5.5` یا `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[]` | منابع Regex که پس از حذف پسوند پروفایل در برابر شناسه‌های کوتاه مدل تطبیق داده می‌شوند. | ورودی‌های `modelPatterns` از طریق `compileSafeRegex` کامپایل می‌شوند؛ این تابع الگوهای دارای تکرار تو در تو (برای مثال `(a+)+$`) را رد می‌کند. الگوهایی که بررسی ایمنی را نگذرند، درست مانند regexهای از نظر نحوی نامعتبر، بی‌صدا نادیده گرفته می‌شوند. الگوها را ساده نگه دارید و از کمیت‌سازهای تو در تو پرهیز کنید. ## مرجع 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` | ردیف‌های کاتالوگ برای شناسه‌های ارائه‌دهنده‌ای که این Plugin مالک آن‌هاست. کلیدها باید در `providers` سطح بالا نیز ظاهر شوند. | | `aliases` | `Record` | نام‌های مستعار ارائه‌دهنده که باید برای برنامه‌ریزی کاتالوگ یا سرکوب به یک ارائه‌دهنده مالکیت‌یافته resolve شوند. | | `suppressions` | `object[]` | ردیف‌های مدل از منبعی دیگر که این Plugin به دلیلی مختص ارائه‌دهنده سرکوب می‌کند. | | `discovery` | `Record` | اینکه کاتالوگ ارائه‌دهنده می‌تواند از فراداده مانیفست خوانده شود، در کش نوسازی شود، یا به زمان اجرا نیاز دارد. | | `runtimeAugment` | `boolean` | فقط زمانی روی `true` تنظیم کنید که زمان اجرای ارائه‌دهنده باید پس از برنامه‌ریزی مانیفست/پیکربندی، ردیف‌های کاتالوگ را اضافه کند. | `aliases` در جست‌وجوی مالکیت ارائه‌دهنده برای برنامه‌ریزی کاتالوگ مدل مشارکت می‌کند. هدف‌های نام مستعار باید ارائه‌دهندگان سطح بالایی باشند که همان Plugin مالک آن‌هاست. وقتی یک فهرست فیلترشده بر اساس ارائه‌دهنده از یک نام مستعار استفاده می‌کند، OpenClaw می‌تواند مانیفست مالک را بخواند و overrideهای API/نشانی پایه نام مستعار را بدون بارگذاری زمان اجرای ارائه‌دهنده اعمال کند. نام‌های مستعار فهرست‌های کاتالوگ فیلترنشده را گسترش نمی‌دهند؛ فهرست‌های گسترده فقط ردیف‌های ارائه‌دهنده کانونی مالک را منتشر می‌کنند. `suppressions` جایگزین hook قدیمی زمان اجرای ارائه‌دهنده `suppressBuiltInModel` می‌شود. ورودی‌های سرکوب فقط زمانی رعایت می‌شوند که ارائه‌دهنده در مالکیت Plugin باشد یا به‌عنوان کلید `modelCatalog.aliases` اعلام شده باشد که به یک ارائه‌دهنده مالکیت‌یافته اشاره می‌کند. hookهای سرکوب زمان اجرا دیگر هنگام حل مدل فراخوانی نمی‌شوند. فیلدهای ارائه‌دهنده: | فیلد | نوع | معنی آن | | --------- | ------------------------ | ----------------------------------------------------------------- | | `baseUrl` | `string` | نشانی پایه پیش‌فرض اختیاری برای مدل‌های این کاتالوگ ارائه‌دهنده. | | `api` | `ModelApi` | آداپتور API پیش‌فرض اختیاری برای مدل‌های این کاتالوگ ارائه‌دهنده. | | `headers` | `Record` | هدرهای ثابت اختیاری که روی این کاتالوگ ارائه‌دهنده اعمال می‌شوند. | | `models` | `object[]` | ردیف‌های مدل الزامی. ردیف‌های بدون `id` نادیده گرفته می‌شوند. | فیلدهای مدل: | فیلد | نوع | معنی آن | | --------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------- | | `id` | `string` | شناسه مدل محلیِ ارائه‌دهنده، بدون پیشوند `provider/`. | | `name` | `string` | نام نمایشی اختیاری. | | `api` | `ModelApi` | override اختیاری API برای هر مدل. | | `baseUrl` | `string` | override اختیاری نشانی پایه برای هر مدل. | | `headers` | `Record` | هدرهای ثابت اختیاری برای هر مدل. | | `input` | `Array<"text" \| "image" \| "document" \| "audio" \| "video">` | Modalitiesهایی که مدل می‌پذیرد. | | `reasoning` | `boolean` | اینکه مدل رفتار استدلالی را آشکار می‌کند یا نه. | | `contextWindow` | `number` | پنجره زمینه بومی ارائه‌دهنده. | | `contextTokens` | `number` | سقف اختیاری زمینه مؤثر زمان اجرا، زمانی که با `contextWindow` متفاوت است. | | `maxTokens` | `number` | بیشینه توکن‌های خروجی، وقتی معلوم باشد. | | `cost` | `object` | قیمت‌گذاری اختیاری دلار آمریکا به‌ازای هر میلیون توکن، شامل `tieredPricing` اختیاری. | | `compat` | `object` | پرچم‌های سازگاری اختیاری مطابق با سازگاری پیکربندی مدل OpenClaw. | | `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | وضعیت فهرست‌شدن. فقط زمانی سرکوب کنید که ردیف اصلاً نباید ظاهر شود. | | `statusReason` | `string` | دلیل اختیاری که همراه وضعیت غیرقابل‌دسترس نشان داده می‌شود. | | `replaces` | `string[]` | شناسه‌های قدیمی‌تر مدل محلیِ ارائه‌دهنده که این مدل جایگزین آن‌ها می‌شود. | | `replacedBy` | `string` | شناسه مدل محلیِ ارائه‌دهنده جایگزین برای ردیف‌های منسوخ. | | `tags` | `string[]` | برچسب‌های پایدار مورد استفاده pickers و فیلترها. | فیلدهای سرکوب: | فیلد | نوع | معنی آن | | -------------------------- | ---------- | --------------------------------------------------------------------------------------------------------- | | `provider` | `string` | شناسه ارائه‌دهنده برای ردیف بالادستی که باید سرکوب شود. باید در مالکیت این Plugin باشد یا به‌عنوان نام مستعار مالکیت‌یافته اعلام شده باشد. | | `model` | `string` | شناسه مدل محلیِ ارائه‌دهنده که باید سرکوب شود. | | `reason` | `string` | پیام اختیاری که وقتی ردیف سرکوب‌شده مستقیماً درخواست می‌شود نشان داده می‌شود. | | `when.baseUrlHosts` | `string[]` | فهرست اختیاری میزبان‌های نشانی پایه مؤثر ارائه‌دهنده که پیش از اعمال سرکوب لازم‌اند. | | `when.providerConfigApiIn` | `string[]` | فهرست اختیاری مقادیر دقیق `api` در پیکربندی ارائه‌دهنده که پیش از اعمال سرکوب لازم‌اند. | داده‌ای را که فقط به زمان اجرا مربوط است در `modelCatalog` قرار ندهید. فقط زمانی از `static` استفاده کنید که ردیف‌های مانیفست برای سطوح فهرست فیلترشده بر اساس ارائه‌دهنده و pickerها به‌اندازه کافی کامل باشند تا از کشف رجیستری/زمان اجرا صرف‌نظر شود. زمانی از `refreshable` استفاده کنید که ردیف‌های مانیفست به‌عنوان seedها یا مکمل‌های قابل فهرست‌شدن مفیدند، اما refresh/cache می‌تواند بعداً ردیف‌های بیشتری اضافه کند؛ ردیف‌های refreshable به‌تنهایی مرجع قطعی نیستند. زمانی از `runtime` استفاده کنید که OpenClaw باید برای دانستن فهرست، زمان اجرای ارائه‌دهنده را بارگذاری کند. ## مرجع modelIdNormalization از `modelIdNormalization` برای پاک‌سازی ارزان شناسه مدل، تحت مالکیت ارائه‌دهنده، استفاده کنید که باید پیش از بارگذاری زمان اجرای ارائه‌دهنده انجام شود. این کار نام‌های مستعار مانند نام‌های کوتاه مدل، شناسه‌های قدیمی محلیِ ارائه‌دهنده، و قواعد پیشوند proxy را به‌جای جدول‌های انتخاب مدل در هسته، در مانیفست Plugin مالک نگه می‌دارد. ```json { "providers": ["anthropic", "openrouter"], "modelIdNormalization": { "providers": { "anthropic": { "aliases": { "sonnet-4.6": "claude-sonnet-4-6" } }, "openrouter": { "prefixWhenBare": "openrouter" } } } } ``` فیلدهای ارائه‌دهنده: | فیلد | نوع | معنی آن | | ------------------------------------ | ----------------------- | ----------------------------------------------------------------------------------------- | | `aliases` | `Record` | نام‌های مستعار دقیق شناسه مدل بدون حساسیت به بزرگی/کوچکی حروف. مقادیر همان‌طور که نوشته شده‌اند بازگردانده می‌شوند. | | `stripPrefixes` | `string[]` | پیشوندهایی که پیش از جست‌وجوی نام مستعار حذف می‌شوند؛ برای تکرار legacy ارائه‌دهنده/مدل مفید است. | | `prefixWhenBare` | `string` | پیشوندی که وقتی شناسه مدل نرمال‌شده هنوز شامل `/` نیست اضافه می‌شود. | | `prefixWhenBareAfterAliasStartsWith` | `object[]` | قواعد شرطی پیشوند برای شناسه بدون ارائه‌دهنده پس از جست‌وجوی نام مستعار، کلیدگذاری‌شده با `modelPrefix` و `prefix`. | ## مرجع providerEndpoints از `providerEndpoints` برای طبقه‌بندی endpointهایی استفاده کنید که سیاست درخواست عمومی باید پیش از بارگذاری زمان اجرای ارائه‌دهنده بداند. هسته همچنان مالک معنای هر `endpointClass` است؛ مانیفست‌های Plugin مالک فراداده میزبان و نشانی پایه هستند. فیلدهای endpoint: | فیلد | نوع | معنی آن | | ------------------------------ | ---------- | ---------------------------------------------------------------------------------------------- | | `endpointClass` | `string` | کلاس endpoint اصلی شناخته‌شده، مانند `openrouter`، `moonshot-native`، یا `google-vertex`. | | `hosts` | `string[]` | نام‌های میزبان دقیق که به کلاس endpoint نگاشت می‌شوند. | | `hostSuffixes` | `string[]` | پسوندهای میزبان که به کلاس endpoint نگاشت می‌شوند. برای تطبیق فقط با پسوند دامنه، پیشوند `.` بگذارید. | | `baseUrls` | `string[]` | URLهای پایه HTTP(S) دقیق و نرمال‌شده که به کلاس endpoint نگاشت می‌شوند. | | `googleVertexRegion` | `string` | منطقه ثابت Google Vertex برای میزبان‌های جهانی دقیق. | | `googleVertexRegionHostSuffix` | `string` | پسوندی که از میزبان‌های مطابق حذف می‌شود تا پیشوند منطقه Google Vertex آشکار شود. | ## مرجع providerRequest از `providerRequest` برای فراداده ارزان سازگاری درخواست استفاده کنید که سیاست درخواست عمومی بدون بارگذاری runtime ارائه‌دهنده به آن نیاز دارد. بازنویسی payloadهای مختص رفتار را در hookهای runtime ارائه‌دهنده یا helperهای مشترک خانواده ارائه‌دهنده نگه دارید. ```json { "providers": ["vllm"], "providerRequest": { "providers": { "vllm": { "family": "vllm", "openAICompletions": { "supportsStreamingUsage": true } } } } } ``` فیلدهای ارائه‌دهنده: | فیلد | نوع | معنی آن | | --------------------- | ------------ | --------------------------------------------------------------------------------------- | | `family` | `string` | برچسب خانواده ارائه‌دهنده که برای تصمیم‌های سازگاری درخواست عمومی و تشخیص‌ها استفاده می‌شود. | | `compatibilityFamily` | `"moonshot"` | bucket اختیاری سازگاری خانواده ارائه‌دهنده برای helperهای مشترک درخواست. | | `openAICompletions` | `object` | پرچم‌های درخواست تکمیل‌های سازگار با OpenAI، در حال حاضر `supportsStreamingUsage`. | ## مرجع secretProviderIntegrations وقتی یک Plugin می‌تواند preset قابل استفاده مجدد ارائه‌دهنده exec برای SecretRef منتشر کند، از `secretProviderIntegrations` استفاده کنید. OpenClaw این فراداده را پیش از بارگذاری runtime Plugin می‌خواند، مالکیت Plugin را در `secrets.providers..pluginIntegration` ذخیره می‌کند، و حل واقعی secret را به runtime مربوط به SecretRef واگذار می‌کند. presetها فقط برای Pluginهای bundled و Pluginهای نصب‌شده‌ای آشکار می‌شوند که از ریشه‌های نصب Plugin مدیریت‌شده کشف شده‌اند، مانند نصب‌های git و ClawHub. ```json { "secretProviderIntegrations": { "secret-store": { "providerAlias": "team-secrets", "displayName": "Team secrets", "source": "exec", "command": "${node}", "args": ["./bin/resolve-secrets.mjs"] } } } ``` کلید map شناسه integration است. اگر `providerAlias` حذف شود، OpenClaw از شناسه integration به عنوان alias ارائه‌دهنده SecretRef استفاده می‌کند. aliasهای ارائه‌دهنده باید با الگوی عادی alias ارائه‌دهنده SecretRef مطابقت داشته باشند، برای مثال `team-secrets` یا `onepassword-work`. وقتی یک اپراتور preset را انتخاب می‌کند، OpenClaw یک ارجاع ارائه‌دهنده مانند زیر می‌نویسد: ```json { "secrets": { "providers": { "team-secrets": { "source": "exec", "pluginIntegration": { "pluginId": "acme-secrets", "integrationId": "secret-store" } } } } } ``` در زمان startup/reload، OpenClaw آن ارائه‌دهنده را با بارگذاری فراداده مانیفست Plugin فعلی، بررسی نصب و فعال بودن Plugin مالک، و مادی‌سازی فرمان exec از مانیفست resolve می‌کند. غیرفعال‌سازی یا حذف Plugin، ارائه‌دهنده را برای SecretRefهای فعال لغو می‌کند. اپراتورهایی که پیکربندی exec مستقل می‌خواهند همچنان می‌توانند ارائه‌دهنده‌های دستی `command`/`args` را مستقیم بنویسند. در حال حاضر فقط presetهای `source: "exec"` پشتیبانی می‌شوند. `command` باید `${node}` باشد، و `args[0]` باید یک اسکریپت resolver نسبی به ریشه Plugin با پیشوند `./` باشد. OpenClaw آن را در زمان startup/reload به executable فعلی Node و مسیر مطلق اسکریپت درون Plugin مادی‌سازی می‌کند. گزینه‌های Node مانند `--require`، `--import`، `--loader`، `--env-file`، `--eval`، و `--print` بخشی از قرارداد preset مانیفست نیستند. اپراتورهایی که به فرمان‌های غیر Node نیاز دارند می‌توانند ارائه‌دهنده‌های exec دستی مستقل را مستقیم پیکربندی کنند. OpenClaw برای presetهای مانیفست، `trustedDirs` را از ریشه Plugin و، برای presetهای `${node}`، از دایرکتوری executable فعلی Node استخراج می‌کند. `trustedDirs` نوشته‌شده در مانیفست نادیده گرفته می‌شوند. گزینه‌های دیگر ارائه‌دهنده exec مانند `timeoutMs`، `maxOutputBytes`، `jsonOnly`، `env`، `passEnv`، و `allowInsecurePath` به پیکربندی عادی ارائه‌دهنده exec مربوط به SecretRef منتقل می‌شوند. ## مرجع modelPricing وقتی یک ارائه‌دهنده پیش از بارگذاری runtime به رفتار قیمت‌گذاری control-plane نیاز دارد، از `modelPricing` استفاده کنید. کش قیمت‌گذاری Gateway این فراداده را بدون import کردن کد runtime ارائه‌دهنده می‌خواند. ```json { "providers": ["ollama", "openrouter"], "modelPricing": { "providers": { "ollama": { "external": false }, "openrouter": { "openRouter": { "passthroughProviderModel": true }, "liteLLM": false } } } } ``` فیلدهای ارائه‌دهنده: | فیلد | نوع | معنی آن | | ------------ | ----------------- | ----------------------------------------------------------------------------------------------- | | `external` | `boolean` | برای ارائه‌دهنده‌های محلی/خودمیزبان که هرگز نباید قیمت‌گذاری OpenRouter یا LiteLLM را fetch کنند، `false` تنظیم کنید. | | `openRouter` | `false \| object` | نگاشت lookup قیمت‌گذاری OpenRouter. `false`، lookup در OpenRouter را برای این ارائه‌دهنده غیرفعال می‌کند. | | `liteLLM` | `false \| object` | نگاشت lookup قیمت‌گذاری LiteLLM. `false`، lookup در LiteLLM را برای این ارائه‌دهنده غیرفعال می‌کند. | فیلدهای منبع: | فیلد | نوع | معنی آن | | -------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------- | | `provider` | `string` | شناسه ارائه‌دهنده کاتالوگ خارجی وقتی با شناسه ارائه‌دهنده OpenClaw متفاوت است، برای مثال `z-ai` برای ارائه‌دهنده `zai`. | | `passthroughProviderModel` | `boolean` | شناسه‌های مدل دارای slash را به عنوان refهای تودرتوی provider/model در نظر بگیرید، مناسب برای ارائه‌دهنده‌های proxy مانند OpenRouter. | | `modelIdTransforms` | `"version-dots"[]` | گونه‌های اضافی شناسه مدل در کاتالوگ خارجی. `version-dots` شناسه‌های نسخه نقطه‌دار مانند `claude-opus-4.6` را امتحان می‌کند. | ### شاخص ارائه‌دهنده OpenClaw شاخص ارائه‌دهنده OpenClaw فراداده preview تحت مالکیت OpenClaw برای ارائه‌دهنده‌هایی است که Pluginهای آن‌ها ممکن است هنوز نصب نشده باشند. این بخشی از مانیفست Plugin نیست. مانیفست‌های Plugin همچنان مرجع Plugin نصب‌شده هستند. شاخص ارائه‌دهنده قرارداد fallback داخلی است که سطح‌های انتخاب مدل مربوط به ارائه‌دهنده قابل نصب آینده و پیش از نصب وقتی Plugin ارائه‌دهنده نصب نشده باشد، از آن استفاده خواهند کرد. ترتیب مرجعیت کاتالوگ: 1. پیکربندی کاربر. 2. `modelCatalog` مانیفست Plugin نصب‌شده. 3. کش کاتالوگ مدل از refresh صریح. 4. ردیف‌های preview شاخص ارائه‌دهنده OpenClaw. شاخص ارائه‌دهنده نباید شامل secrets، وضعیت enabled، hookهای runtime، یا داده مدل زنده مخصوص حساب باشد. کاتالوگ‌های preview آن همان شکل ردیف ارائه‌دهنده `modelCatalog` را مانند مانیفست‌های Plugin استفاده می‌کنند، اما باید به فراداده نمایشی پایدار محدود بمانند، مگر اینکه فیلدهای adapter runtime مانند `api`، `baseUrl`، قیمت‌گذاری، یا پرچم‌های سازگاری عمدا با مانیفست Plugin نصب‌شده هم‌راستا نگه داشته شوند. ارائه‌دهنده‌هایی با کشف زنده `/models` باید ردیف‌های refresh‌شده را از مسیر صریح کش کاتالوگ مدل بنویسند، به جای اینکه listing عادی یا onboarding با APIهای ارائه‌دهنده تماس بگیرد. ورودی‌های شاخص ارائه‌دهنده همچنین می‌توانند فراداده Plugin قابل نصب را برای ارائه‌دهنده‌هایی حمل کنند که Plugin آن‌ها از core خارج شده یا هنوز به شکل دیگری نصب نشده است. این فراداده الگوی کاتالوگ channel را بازتاب می‌دهد: نام package، مشخصات نصب npm، integrity مورد انتظار، و برچسب‌های ارزان انتخاب auth برای نمایش یک گزینه setup قابل نصب کافی هستند. پس از نصب Plugin، مانیفست آن برنده می‌شود و ورودی شاخص ارائه‌دهنده برای آن ارائه‌دهنده نادیده گرفته می‌شود. کلیدهای legacy سطح بالا برای capability منسوخ شده‌اند. از `openclaw doctor --fix` برای انتقال `speechProviders`، `realtimeTranscriptionProviders`، `realtimeVoiceProviders`، `mediaUnderstandingProviders`، `imageGenerationProviders`، `videoGenerationProviders`، `webFetchProviders`، و `webSearchProviders` به زیر `contracts` استفاده کنید؛ بارگذاری عادی مانیفست دیگر این فیلدهای سطح بالا را به عنوان مالکیت capability در نظر نمی‌گیرد. ## مانیفست در برابر package.json این دو فایل کارکردهای متفاوتی دارند: | فایل | کاربرد آن | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `openclaw.plugin.json` | کشف، اعتبارسنجی پیکربندی، فراداده انتخاب auth، و hintهای UI که باید پیش از اجرای کد Plugin وجود داشته باشند | | `package.json` | فراداده npm، نصب وابستگی، و بلوک `openclaw` که برای entrypointها، gating نصب، setup، یا فراداده کاتالوگ استفاده می‌شود | اگر مطمئن نیستید یک قطعه فراداده کجا قرار می‌گیرد، از این قاعده استفاده کنید: - اگر OpenClaw باید پیش از بارگذاری کد Plugin آن را بداند، آن را در `openclaw.plugin.json` بگذارید - اگر درباره packaging، فایل‌های entry، یا رفتار نصب npm است، آن را در `package.json` بگذارید ### فیلدهای package.json که بر کشف اثر می‌گذارند برخی فراداده‌های Plugin پیش از runtime عمدا در `package.json` زیر بلوک `openclaw` قرار دارند، نه در `openclaw.plugin.json`. `openclaw.bundle` و `openclaw.bundle.json` قراردادهای Plugin مربوط به OpenClaw نیستند؛ Pluginهای native باید از `openclaw.plugin.json` به‌همراه فیلدهای پشتیبانی‌شده `package.json#openclaw` در زیر استفاده کنند. نمونه‌های مهم: | فیلد | معنای آن | | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `openclaw.extensions` | entrypointهای Plugin بومی را اعلام می‌کند. باید داخل دایرکتوری پکیج Plugin باقی بماند. | | `openclaw.runtimeExtensions` | entrypointهای runtime جاوااسکریپت ساخته‌شده را برای پکیج‌های نصب‌شده اعلام می‌کند. باید داخل دایرکتوری پکیج Plugin باقی بماند. | | `openclaw.setupEntry` | entrypoint سبک و فقط مخصوص setup که هنگام onboarding، شروع به‌تعویق‌افتاده کانال، و کشف وضعیت فقط‌خواندنی کانال/SecretRef استفاده می‌شود. باید داخل دایرکتوری پکیج Plugin باقی بماند. | | `openclaw.runtimeSetupEntry` | entrypoint ساخته‌شده جاوااسکریپت setup را برای پکیج‌های نصب‌شده اعلام می‌کند. به `setupEntry` نیاز دارد، باید وجود داشته باشد، و باید داخل دایرکتوری پکیج Plugin باقی بماند. | | `openclaw.channel` | فراداده ارزان کاتالوگ کانال، مانند برچسب‌ها، مسیرهای مستندات، نام‌های مستعار، و متن انتخاب. | | `openclaw.channel.commands` | فراداده ایستای فرمان بومی و پیش‌فرض خودکار skill بومی که پیش از بارگذاری runtime کانال توسط سطوح config، audit، و command-list استفاده می‌شود. | | `openclaw.channel.configuredState` | فراداده سبک بررسی‌کننده وضعیت پیکربندی‌شده که می‌تواند بدون بارگذاری کامل runtime کانال پاسخ دهد «آیا setup فقط-env از قبل وجود دارد؟». | | `openclaw.channel.persistedAuthState` | فراداده سبک بررسی‌کننده auth ماندگار که می‌تواند بدون بارگذاری کامل runtime کانال پاسخ دهد «آیا چیزی از قبل وارد سیستم شده است؟». | | `openclaw.install.clawhubSpec` / `openclaw.install.npmSpec` / `openclaw.install.localPath` | راهنمایی‌های install/update برای Pluginهای bundled و منتشرشده خارجی. | | `openclaw.install.defaultChoice` | مسیر install ترجیحی وقتی چند منبع install در دسترس است. | | `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` | رشته integrity مورد انتظار npm dist مانند `sha512-...`؛ جریان‌های install و update artifact دریافت‌شده را در برابر آن بررسی می‌کنند. | | `openclaw.install.allowInvalidConfigRecovery` | یک مسیر بازیابی محدود برای نصب دوباره Plugin bundled را وقتی config نامعتبر است مجاز می‌کند. | | `openclaw.install.requiredPlatformPackages` | نام‌های مستعار پکیج npm که وقتی محدودیت‌های پلتفرمی lockfile آن‌ها با میزبان فعلی مطابقت دارد، باید materialize شوند. | | `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | اجازه می‌دهد سطوح کانال setup-runtime پیش از listen بارگذاری شوند، سپس Plugin کامل کانال پیکربندی‌شده را تا فعال‌سازی پس از listen به تعویق می‌اندازد. | فراداده manifest تعیین می‌کند کدام گزینه‌های provider/channel/setup پیش از بارگذاری runtime در onboarding ظاهر شوند. `package.json#openclaw.install` به onboarding می‌گوید وقتی کاربر یکی از آن گزینه‌ها را انتخاب می‌کند، آن Plugin چگونه دریافت یا فعال شود. راهنمایی‌های install را به `openclaw.plugin.json` منتقل نکنید. `openclaw.install.minHostVersion` هنگام install و بارگذاری رجیستری manifest برای منابع Plugin غیرباندل‌شده اعمال می‌شود. مقادیر نامعتبر رد می‌شوند؛ مقادیر جدیدتر اما معتبر باعث می‌شوند Pluginهای خارجی روی میزبان‌های قدیمی‌تر نادیده گرفته شوند. فرض می‌شود Pluginهای source باندل‌شده با checkout میزبان هم‌نسخه هستند. `openclaw.install.requiredPlatformPackages` برای پکیج‌های npm است که باینری‌های بومی لازم را از طریق نام‌های مستعار اختیاری و مختص پلتفرم ارائه می‌کنند. نام خام پکیج npm را برای هر نام مستعار پلتفرم پشتیبانی‌شده فهرست کنید. هنگام install با npm، OpenClaw فقط نام مستعار اعلام‌شده‌ای را بررسی می‌کند که محدودیت‌های lockfile آن با میزبان فعلی مطابقت دارد. اگر npm موفقیت گزارش کند اما آن نام مستعار را حذف کرده باشد، OpenClaw یک بار با cache تازه دوباره تلاش می‌کند و اگر نام مستعار همچنان موجود نباشد، install را rollback می‌کند. `openclaw.compat.pluginApi` هنگام install پکیج برای منابع Plugin غیرباندل‌شده اعمال می‌شود. از آن برای کف API مربوط به SDK/runtime Plugin در OpenClaw که پکیج بر پایه آن ساخته شده استفاده کنید. وقتی یک پکیج Plugin به API جدیدتری نیاز دارد اما همچنان برای جریان‌های دیگر راهنمای install پایین‌تری نگه می‌دارد، می‌تواند سخت‌گیرانه‌تر از `minHostVersion` باشد. همگام‌سازی انتشار رسمی OpenClaw به‌طور پیش‌فرض کف‌های API رسمی موجود برای Plugin را به نسخه انتشار OpenClaw افزایش می‌دهد، اما انتشارهای فقط-Plugin می‌توانند وقتی پکیج عمدا از میزبان‌های قدیمی‌تر پشتیبانی می‌کند کف پایین‌تری نگه دارند. نسخه پکیج را به تنهایی به‌عنوان قرارداد سازگاری استفاده نکنید. `peerDependencies.openclaw` فراداده پکیج npm باقی می‌ماند؛ OpenClaw برای تصمیم‌های سازگاری install از قرارداد `openclaw.compat.pluginApi` استفاده می‌کند. فراداده رسمی install-on-demand باید وقتی Plugin روی ClawHub منتشر شده است از `clawhubSpec` استفاده کند؛ onboarding آن را به‌عنوان منبع remote ترجیحی در نظر می‌گیرد و پس از install، واقعیت‌های artifact مربوط به ClawHub را ثبت می‌کند. `npmSpec` برای پکیج‌هایی که هنوز به ClawHub منتقل نشده‌اند fallback سازگاری باقی می‌ماند. pin کردن نسخه دقیق npm از قبل در `npmSpec` قرار دارد، برای مثال `"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. ورودی‌های رسمی کاتالوگ خارجی باید specهای دقیق را با `expectedIntegrity` جفت کنند تا اگر artifact دریافت‌شده npm دیگر با انتشار pin‌شده مطابقت نداشت، جریان‌های update به‌صورت fail closed متوقف شوند. onboarding تعاملی همچنان برای سازگاری، specهای npm رجیستری قابل اعتماد، شامل نام‌های خام پکیج و dist-tagها، را ارائه می‌کند. عیب‌یابی‌های کاتالوگ می‌توانند منابع دقیق، شناور، pin‌شده با integrity، فاقد integrity، ناسازگار با نام پکیج، و default-choice نامعتبر را از هم تشخیص دهند. همچنین وقتی `expectedIntegrity` وجود دارد اما هیچ منبع معتبر npm برای pin کردن آن نیست هشدار می‌دهند. وقتی `expectedIntegrity` وجود دارد، جریان‌های install/update آن را اعمال می‌کنند؛ وقتی حذف شده باشد، resolution رجیستری بدون pin مربوط به integrity ثبت می‌شود. Pluginهای کانال باید وقتی اسکن‌های وضعیت، فهرست کانال، یا SecretRef لازم است accountهای پیکربندی‌شده را بدون بارگذاری runtime کامل شناسایی کنند، `openclaw.setupEntry` را ارائه کنند. entry مربوط به setup باید فراداده کانال به‌علاوه adapterهای config، وضعیت، و secrets ایمن برای setup را expose کند؛ clientهای شبکه، listenerهای Gateway، و runtimeهای transport را در entrypoint اصلی extension نگه دارید. فیلدهای runtime entrypoint بررسی‌های مرز پکیج را برای فیلدهای source entrypoint لغو نمی‌کنند. برای مثال، `openclaw.runtimeExtensions` نمی‌تواند یک مسیر `openclaw.extensions` خارج‌شونده را قابل بارگذاری کند. `openclaw.install.allowInvalidConfigRecovery` عمدا محدود است. این گزینه configهای خراب دلخواه را قابل install نمی‌کند. امروز فقط به جریان‌های install اجازه می‌دهد از خرابی‌های مشخص upgrade مربوط به Plugin bundled قدیمی بازیابی شوند، مانند مسیر گم‌شده Plugin bundled یا ورودی stale `channels.` برای همان Plugin bundled. خطاهای نامرتبط config همچنان install را مسدود می‌کنند و operatorها را به `openclaw doctor --fix` می‌فرستند. `openclaw.channel.persistedAuthState` فراداده پکیج برای یک ماژول بررسی‌کننده بسیار کوچک است: ```json { "openclaw": { "channel": { "id": "whatsapp", "persistedAuthState": { "specifier": "./auth-presence", "exportName": "hasAnyWhatsAppAuth" } } } } ``` وقتی setup، doctor، status، یا جریان‌های حضور فقط‌خواندنی پیش از بارگذاری Plugin کامل کانال به یک probe ارزان بله/خیر برای auth نیاز دارند، از آن استفاده کنید. وضعیت auth ماندگار، وضعیت کانال پیکربندی‌شده نیست: از این فراداده برای فعال‌سازی خودکار Pluginها، تعمیر وابستگی‌های runtime، یا تصمیم‌گیری درباره اینکه runtime کانال باید بارگذاری شود استفاده نکنید. export هدف باید یک تابع کوچک باشد که فقط وضعیت ماندگار را می‌خواند؛ آن را از طریق barrel کامل runtime کانال مسیر‌دهی نکنید. `openclaw.channel.configuredState` همین شکل را برای بررسی‌های ارزان پیکربندی‌شده فقط-env دنبال می‌کند: ```json { "openclaw": { "channel": { "id": "telegram", "configuredState": { "specifier": "./configured-state", "exportName": "hasTelegramConfiguredState" } } } } ``` وقتی یک کانال می‌تواند configured-state را از env یا ورودی‌های کوچک غیر-runtime پاسخ دهد، از آن استفاده کنید. اگر بررسی به resolution کامل config یا runtime واقعی کانال نیاز دارد، آن منطق را به جای آن در hook مربوط به `config.hasConfiguredState` در Plugin نگه دارید. ## اولویت کشف (idهای تکراری Plugin) OpenClaw Pluginها را از چند root کشف می‌کند. برای ترتیب خام scan در filesystem، [ترتیب scan Plugin](/fa/gateway/configuration-reference#plugin-scan-order) را ببینید. اگر دو کشف، `id` یکسانی داشته باشند، فقط manifest با **بالاترین اولویت** نگه داشته می‌شود؛ موارد تکراری با اولویت پایین‌تر به جای اینکه کنار آن بارگذاری شوند، حذف می‌شوند. اولویت، از بیشترین تا کمترین: 1. **انتخاب‌شده در config** — مسیری که به‌صراحت در `plugins.entries.` pin شده است 2. **Bundled** — Pluginهایی که همراه OpenClaw عرضه می‌شوند 3. **Install سراسری** — Pluginهایی که در root سراسری Pluginهای OpenClaw نصب شده‌اند 4. **Workspace** — Pluginهایی که نسبت به workspace فعلی کشف شده‌اند پیامدها: - یک نسخه fork شده یا stale از یک Plugin bundled که در workspace قرار دارد، build باندل‌شده را shadow نمی‌کند. - برای override واقعی یک Plugin bundled با یک نسخه local، آن را از طریق `plugins.entries.` pin کنید تا با اولویت برنده شود، نه با اتکا به کشف workspace. - حذف‌های تکراری log می‌شوند تا Doctor و عیب‌یابی‌های startup بتوانند به نسخه کنارگذاشته‌شده اشاره کنند. - overrideهای تکراری انتخاب‌شده در config در عیب‌یابی‌ها به‌عنوان overrideهای صریح بیان می‌شوند، اما همچنان هشدار می‌دهند تا forkهای stale و shadowهای تصادفی قابل مشاهده بمانند. ## الزامات JSON Schema - **هر Plugin باید یک طرح‌وارهٔ JSON ارائه کند**، حتی اگر هیچ پیکربندی‌ای نپذیرد. - طرح‌وارهٔ خالی قابل قبول است (برای مثال، `{ "type": "object", "additionalProperties": false }`). - طرح‌واره‌ها هنگام خواندن/نوشتن پیکربندی اعتبارسنجی می‌شوند، نه هنگام اجرا. - هنگام گسترش دادن یا fork کردن یک Plugin همراه با کلیدهای پیکربندی جدید، هم‌زمان `configSchema` در `openclaw.plugin.json` همان Plugin را به‌روزرسانی کنید. طرح‌واره‌های Pluginهای همراه سخت‌گیر هستند، بنابراین افزودن `plugins.entries..config.myNewKey` در پیکربندی کاربر بدون افزودن `myNewKey` به `configSchema.properties` پیش از بارگذاری runtime Plugin رد خواهد شد. نمونهٔ گسترش طرح‌واره: ```json { "configSchema": { "type": "object", "additionalProperties": false, "properties": { "myNewKey": { "type": "string" } } } } ``` ## رفتار اعتبارسنجی - کلیدهای ناشناختهٔ `channels.*` **خطا** هستند، مگر اینکه شناسهٔ کانال توسط مانیفست Plugin اعلام شده باشد. - `plugins.entries.`، `plugins.allow`، `plugins.deny`، و `plugins.slots.*` باید به شناسه‌های Plugin **قابل کشف** ارجاع دهند. شناسه‌های ناشناخته **خطا** هستند. - اگر Plugin نصب شده باشد اما مانیفست یا طرح‌وارهٔ خراب یا مفقود داشته باشد، اعتبارسنجی شکست می‌خورد و Doctor خطای Plugin را گزارش می‌کند. - اگر پیکربندی Plugin وجود داشته باشد اما Plugin **غیرفعال** باشد، پیکربندی نگه داشته می‌شود و یک **هشدار** در Doctor و logها نمایش داده می‌شود. برای طرح‌وارهٔ کامل `plugins.*`، [مرجع پیکربندی](/fa/gateway/configuration) را ببینید. ## یادداشت‌ها - مانیفست برای **Pluginهای بومی OpenClaw الزامی است**، از جمله بارگذاری‌های filesystem محلی. runtime همچنان ماژول Plugin را جداگانه بارگذاری می‌کند؛ مانیفست فقط برای کشف و اعتبارسنجی است. - مانیفست‌های بومی با JSON5 پردازش می‌شوند، بنابراین commentها، کاماهای انتهایی، و کلیدهای بدون کوتیشن پذیرفته می‌شوند، تا زمانی که مقدار نهایی همچنان یک object باشد. - فقط فیلدهای مستندشدهٔ مانیفست توسط loader مانیفست خوانده می‌شوند. از کلیدهای سفارشی در سطح بالایی پرهیز کنید. - وقتی یک Plugin به `channels`، `providers`، `cliBackends`، و `skills` نیاز ندارد، همهٔ آن‌ها می‌توانند حذف شوند. - `providerCatalogEntry` باید سبک بماند و نباید کد runtime گسترده را import کند؛ از آن برای فرادادهٔ ایستای catalog ارائه‌دهنده یا توصیفگرهای کشف محدود استفاده کنید، نه اجرای هنگام درخواست. - گونه‌های انحصاری Plugin از طریق `plugins.slots.*` انتخاب می‌شوند: `kind: "memory"` از طریق `plugins.slots.memory`، و `kind: "context-engine"` از طریق `plugins.slots.contextEngine` (پیش‌فرض `legacy`). - گونهٔ انحصاری Plugin را در همین مانیفست اعلام کنید. `OpenClawPluginDefinition.kind` در entry runtime منسوخ شده و فقط به‌عنوان fallback سازگاری برای Pluginهای قدیمی‌تر باقی مانده است. - فرادادهٔ متغیرهای محیطی (`setup.providers[].envVars`، `providerAuthEnvVars` منسوخ‌شده، و `channelEnvVars`) فقط اعلانی است. وضعیت، audit، اعتبارسنجی تحویل Cron، و سطوح فقط‌خواندنی دیگر همچنان پیش از در نظر گرفتن یک متغیر محیطی به‌عنوان پیکربندی‌شده، اعتماد Plugin و سیاست فعال‌سازی مؤثر را اعمال می‌کنند. - برای فرادادهٔ wizard runtime که به کد ارائه‌دهنده نیاز دارد، [hookهای runtime ارائه‌دهنده](/fa/plugins/architecture-internals#provider-runtime-hooks) را ببینید. - اگر Plugin شما به ماژول‌های بومی وابسته است، مراحل build و هرگونه الزام allowlist در package manager را مستند کنید (برای مثال، pnpm `allow-build-scripts` + `pnpm rebuild `). ## مرتبط شروع کار با Pluginها. معماری داخلی و مدل قابلیت. مرجع SDK Plugin و importهای subpath.