مانیفست Plugin

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

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

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

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

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

برای راهنمای کامل سامانهٔ Plugin به Pluginها و برای مدل قابلیت بومی و راهنمای فعلی سازگاری خارجی به مدل قابلیت مراجعه کنید.

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

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

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

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

از آن برای موارد زیر استفاده نکنید: ثبت رفتار زمان اجرا، اعلام نقاط ورود کد یا فرادادهٔ نصب 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"      }    }  }}

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

مرجع catalog

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

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

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

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

این فیلدها را فقط برای واقعیت‌های کم‌هزینه و اعلانی به کار ببرید. انتقال، تبدیل درخواست‌ها، نوسازی توکن، اعتبارسنجی اطلاعات احراز هویت و رفتار واقعی تولید در زمان اجرای 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 فقط برای اینکه کارخانه ابزار آن null برگرداند، از واردکردن زمان اجرای Plugin خودداری کند.

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

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

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

مرجع providerAuthChoices

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

مرجع commandAliases

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

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

مرجع activation

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

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

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

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

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

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

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

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

مرجع qaRunners

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

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

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

مرجع setup

هنگامی از setup استفاده کنید که بخش‌های راه‌اندازی و ورود اولیه، پیش از بارگذاری زمان اجرا، به فرادادهٔ کم‌هزینه و تحت مالکیت 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 سطح بالا همچنان معتبر است و به توصیف بک‌اندهای استنتاج CLI ادامه می‌دهد. setup.cliBackends سطح توصیف‌گر مختص راه‌اندازی برای جریان‌های صفحهٔ کنترل/راه‌اندازی است که باید صرفاً مبتنی بر فراداده باقی بمانند.

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

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

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

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

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

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

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

مرجع setup.providers

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

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

فیلدهای setup

مرجع uiHints

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

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

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

مرجع contracts

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

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

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

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

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

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

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

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

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

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

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

مرجع configContracts

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

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

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

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

مرجع mediaUnderstandingProviderMetadata

زمانی از 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"],      "documentModels": {        "pdf": {          "textExtraction": "example-doc-text-latest",          "image": "example-doc-vision-latest"        }      }    }  }}

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

مرجع channelConfigs

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

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

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

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

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

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

{  "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 کانال دیگر

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

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

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

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

مرجع modelSupport

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

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

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

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

فیلدها:

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

مرجع 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 می‌تواند بدون بارگذاری زمان اجرای ارائه‌دهنده، مانیفست مالک را بخواند و بازنویسی‌های API/نشانی پایه نام مستعار را اعمال کند. نام‌های مستعار، فهرست‌های پالایش‌نشده کاتالوگ را گسترش نمی‌دهند؛ فهرست‌های گسترده فقط ردیف‌های ارائه‌دهنده متعارفِ مالک را خروجی می‌دهند.

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

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

فیلدهای مدل:

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

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

مرجع modelIdNormalization

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

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

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

مرجع providerEndpoints

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

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

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

مرجع providerRequest

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

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

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

مرجع secretProviderIntegrations

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

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

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

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

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

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

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

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

مرجع modelPricing

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

پیامدها:

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

الزامات JSON Schema

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

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

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

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

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

برای schema کامل plugins.*، مرجع پیکربندی را ببینید.

نکته‌ها

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

مرتبط