بیانیه Plugin

این صفحه فقط برای مانیفست Plugin بومی OpenClaw است.

برای چیدمان‌های بسته سازگار، بسته‌های Plugin را ببینید.

قالب‌های بسته سازگار از فایل‌های مانیفست متفاوتی استفاده می‌کنند:

• بسته 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ها. برای مدل قابلیت بومی و راهنمای فعلی سازگاری خارجی: مدل قابلیت.

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

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 تعلق دارند.

نمونه حداقلی

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

نمونه غنی

{  "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"      }    }  }}

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

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

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

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

{  "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"]          }        }      ]    }  }}

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

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

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

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

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

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

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

{  "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 ارائه‌دهنده استفاده می‌کنند.

مرجع commandAliases

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

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

مرجع 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، حافظه یا دیگر محرک‌های فعال‌سازی باریک‌تر، از فراداده فعال‌سازی صریح استفاده کنید.

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

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

• برنامه‌ریزی راه‌اندازی 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 را صادر می‌کند.

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

مرجع setup

از setup زمانی استفاده کنید که سطح‌های راه‌اندازی و شروع به کار، پیش از بارگذاری runtime، به فراداده ارزان و متعلق به plugin نیاز دارند.

{  "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

authEvidence برای نشانگرهای credential محلی متعلق به provider است که می‌توانند بدون بارگذاری کد runtime تأیید شوند. این بررسی‌ها باید ارزان و محلی بمانند: بدون فراخوانی شبکه، بدون خواندن keychain یا secret-manager، بدون فرمان shell، و بدون probeهای API provider.

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

فیلدهای setup

مرجع uiHints

uiHints نگاشتی از نام فیلدهای پیکربندی به hintهای کوچک rendering است.

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

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

مرجع contracts

از contracts فقط برای فراداده ایستای مالکیت قابلیت استفاده کنید که OpenClaw می‌تواند بدون import کردن runtime plugin آن را بخواند.

{  "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"]  }}

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

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 نیز اعلام شده باشند.

{  "contracts": {    "mediaUnderstandingProviders": ["example"]  },  "mediaUnderstandingProviderMetadata": {    "example": {      "capabilities": ["image", "audio"],      "defaultModels": {        "image": "example-vision-latest",        "audio": "example-transcribe-latest"      },      "autoPriority": {        "image": 40      },      "nativeDocumentInputs": ["pdf"]    }  }}

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

مرجع channelConfigs

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

channelConfigs metadata manifest Plugin است، نه یک بخش جدید config کاربر در سطح بالا. کاربران همچنان نمونه‌های کانال را زیر channels.<channel-id> پیکربندی می‌کنند. OpenClaw metadata manifest را می‌خواند تا پیش از اجرای کد زمان اجرای Plugin تصمیم بگیرد کدام Plugin مالک آن کانال پیکربندی‌شده است.

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

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

Pluginهای غیرباندل‌شده‌ای که channels[] را اعلام می‌کنند، باید ورودی‌های منطبق channelConfigs را نیز اعلام کنند. بدون آن‌ها، OpenClaw همچنان می‌تواند Plugin را بارگذاری کند، اما schema config مسیر سرد، راه‌اندازی، و سطح‌های Control UI نمی‌توانند شکل گزینه‌های متعلق به کانال را تا زمان اجرای زمان اجرای Plugin بدانند.

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

{  "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"]    }  }}

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

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

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

{  "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 استنتاج کند.

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

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

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

فیلدها:

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

مرجع modelCatalog

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

{  "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"    }  }}

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

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

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

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

فیلدهای مدل:

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

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

مرجع modelIdNormalization

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

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

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

مرجع providerEndpoints

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

فیلدهای endpoint:

مرجع providerRequest

از providerRequest برای فراداده ارزان سازگاری درخواست استفاده کنید که سیاست درخواست عمومی بدون بارگذاری runtime ارائه‌دهنده به آن نیاز دارد. بازنویسی payloadهای مختص رفتار را در hookهای runtime ارائه‌دهنده یا helperهای مشترک خانواده ارائه‌دهنده نگه دارید.

{  "providers": ["vllm"],  "providerRequest": {    "providers": {      "vllm": {        "family": "vllm",        "openAICompletions": {          "supportsStreamingUsage": true        }      }    }  }}

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

مرجع secretProviderIntegrations

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

{  "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 یک ارجاع ارائه‌دهنده مانند زیر می‌نویسد:

{  "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 ارائه‌دهنده می‌خواند.

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

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

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

شاخص ارائه‌دهنده 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 آن را بداند، آن را در 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 در زیر استفاده کنند.

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

فراداده 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.<id> برای همان Plugin bundled. خطاهای نامرتبط config همچنان install را مسدود می‌کنند و operatorها را به openclaw doctor --fix می‌فرستند.

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

{  "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 دنبال می‌کند:

{  "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 را ببینید. اگر دو کشف، id یکسانی داشته باشند، فقط manifest با بالاترین اولویت نگه داشته می‌شود؛ موارد تکراری با اولویت پایین‌تر به جای اینکه کنار آن بارگذاری شوند، حذف می‌شوند.

اولویت، از بیشترین تا کمترین:

1. انتخاب‌شده در config — مسیری که به‌صراحت در plugins.entries.<id> 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.<id> 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.<id>.config.myNewKey در پیکربندی کاربر بدون افزودن myNewKey به configSchema.properties پیش از بارگذاری runtime Plugin رد خواهد شد.

نمونهٔ گسترش طرح‌واره:

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

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

• کلیدهای ناشناختهٔ channels.* خطا هستند، مگر اینکه شناسهٔ کانال توسط مانیفست Plugin اعلام شده باشد.
• plugins.entries.<id>، plugins.allow، plugins.deny، و plugins.slots.* باید به شناسه‌های Plugin قابل کشف ارجاع دهند. شناسه‌های ناشناخته خطا هستند.
• اگر Plugin نصب شده باشد اما مانیفست یا طرح‌وارهٔ خراب یا مفقود داشته باشد، اعتبارسنجی شکست می‌خورد و Doctor خطای Plugin را گزارش می‌کند.
• اگر پیکربندی Plugin وجود داشته باشد اما Plugin غیرفعال باشد، پیکربندی نگه داشته می‌شود و یک هشدار در Doctor و logها نمایش داده می‌شود.

برای طرح‌وارهٔ کامل plugins.*، مرجع پیکربندی را ببینید.

یادداشت‌ها

• مانیفست برای 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 ارائه‌دهنده را ببینید.
• اگر Plugin شما به ماژول‌های بومی وابسته است، مراحل build و هرگونه الزام allowlist در package manager را مستند کنید (برای مثال، pnpm allow-build-scripts + pnpm rebuild <package>).

مرتبط