مانیفست 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 فراداده بسته، ریشه‌های اعلام‌شده مهارت‌ها، ریشه‌های فرمان Claude، پیش‌فرض‌های settings.json در Claude، پیش‌فرض‌های LSP در Claude و بسته‌های hook پشتیبانی‌شده را می‌خواند.

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

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

کار این فایل چیست

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

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

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

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

نمونه حداقلی

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

نمونه جامع

{  "id": "openrouter",  "name": "OpenRouter",  "description": "Plugin ارائه‌دهنده OpenRouter",  "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"  },  "providerAuthChoices": [    {      "provider": "openrouter",      "method": "api-key",      "choiceId": "openrouter-api-key",      "choiceLabel": "کلید API در OpenRouter",      "groupId": "openrouter",      "groupLabel": "OpenRouter",      "optionKey": "openrouterApiKey",      "cliFlag": "--openrouter-api-key",      "cliOption": "--openrouter-api-key <key>",      "cliDescription": "کلید API در OpenRouter",      "onboardingScopes": ["text-inference"]    }  ],  "uiHints": {    "apiKey": {      "label": "کلید API",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  },  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "apiKey": {        "type": "string"      }    }  }}

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

مرجع سرور MCP

mcpServers به یک Plugin بومی اجازه می‌دهد یک سرور MCP، از جمله یک برنامه MCP، ارائه کند، بدون اینکه اپراتورها مجبور باشند تعریف ایستای فرایند آن را در openclaw.json تکرار کنند:

{  "mcpServers": {    "example": {      "transport": "stdio",      "command": "node",      "args": ["./mcp-server.js"]    }  }}

OpenClaw این سرورها را فقط تا زمانی در بر می‌گیرد که Plugin مالک فعال باشد. مسیرهای نسبی command، args، cwd و workingDirectory از ریشه Plugin تفکیک می‌شوند. پیکربندی کاربر همچنان مرجع نهایی است: mcp.servers.<name> می‌تواند مقدار پیش‌فرض یک Plugin را جایگزین کند یا با تنظیم enabled: false آن را کنار بگذارد. رندر برنامه MCP و فراخوانی ابزارهای سرور همچنان به تنظیم معمول برنامه‌های MCP و سیاست مؤثر ابزار نیاز دارند؛ اعلام یک سرور هیچ‌یک از این مرزها را دور نمی‌زند.

مرجع داشبورد

dashboard به یک Plugin فعال اجازه می‌دهد RPCهای موجود Gateway را بدون افزودن سیاست Plugin به هسته، در اختیار ویجت‌های مجاز داشبورد قرار دهد. پیوندهای داده باید متدی را نام ببرند که همان Plugin با operator.read ثبت می‌کند؛ افعال کنش باید متدی را نام ببرند که با operator.write ثبت می‌شود. هرگونه عدم تطابق باعث رد Plugin هنگام ثبت می‌شود.

{  "dashboard": {    "dataBindings": [      {        "id": "items.list",        "method": "example.items.list",        "description": "فهرست‌کردن موارد نمونه."      }    ],    "actionVerbs": [      {        "id": "refresh",        "method": "example.items.refresh",        "description": "تازه‌سازی موارد نمونه.",        "paramShape": {          "type": "object",          "additionalProperties": false,          "properties": {            "force": { "type": "boolean" }          }        }      }    ]  }}

شناسه‌های مانیفست محلیِ Plugin هستند. مجوزهای ویجت از <plugin-id>.<id> استفاده می‌کنند، مانند example.items.list و example.refresh. برای بدون ابهام نگه‌داشتن فضای نام مجوزهای ماندگارشده، OpenClaw نویسه‌های % و . را در بخش شناسه Plugin به‌ترتیب به‌صورت %25 و %2E گریز می‌دهد؛ شناسه‌های عادی Plugin شکل طبیعی خود را حفظ می‌کنند. paramShape یک JSON Schema اختیاری است که پیش از فراخوانی RPC مربوط به Plugin توسط OpenClaw، روی شیء پارامترهای کنش اعمال می‌شود.

مرجع کاتالوگ

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 بتواند از واردکردن زمان اجرای 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، علاوه بر فیلدهای مشترک configSignals/authSignals در بالا، optional (ابزار را برای فعال‌سازی Plugin غیرضروری علامت‌گذاری می‌کند) و replaySafe (اجرای ابزار را برای تکرار پس از یک نوبت ناقص مدل ایمن علامت‌گذاری می‌کند) نیز می‌پذیرند.

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

مرجع providerAuthChoices

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

وقتی appGuidedDiscovery درست است، روش احراز هویت ارائه‌دهنده منطبق باید appGuidedSetup.detect و appGuidedSetup.prepare را ارائه کند. تشخیص باید فقط‌خواندنی باشد: بدون ورود، دریافت مدل، دانلود یا نوشتن پیکربندی. آماده‌سازی، مدل دقیق انتخاب‌شده را دوباره بررسی می‌کند و یک پیشنهاد پیکربندی بازمی‌گرداند؛ OpenClaw آن پیشنهاد را به‌صورت مجزا به‌طور زنده آزمایش می‌کند و تنها پس از موفقیت آن را ثبت می‌کند.

مرجع 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 و هوک‌ها بازمی‌گردد.

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

هر Plugin باید activation.onStartup را آگاهانه تنظیم کند. فقط زمانی آن را روی true تنظیم کنید که Plugin باید هنگام راه‌اندازی Gateway اجرا شود. زمانی آن را روی false تنظیم کنید که Plugin هنگام راه‌اندازی غیرفعال است و باید فقط بر اثر محرک‌های محدودتر بارگذاری شود. حذف 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 اختیاری، انتقال را بدون تغییر اجراکننده فرمان ثبت‌شده در اختیار سناریوهای مشترک QA قرار می‌دهد.

{  "qaRunners": [    {      "commandName": "matrix",      "description": "اجرای مسیر QA زنده Matrix با پشتوانه Docker در برابر یک homeserver یک‌بارمصرف"    }  ]}

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

مرجع راه‌اندازی

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

{  "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"          }        ]      }    ],    "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 را در جست‌وجوهای عمومی احراز هویت ارائه‌دهنده و متغیر محیطی لحاظ می‌کند. فراداده محیطی راه‌اندازی و وضعیت را آنجا قرار دهید.

وقتی یک اعتبارنامه در سطح صورت‌حساب یا سازمان باید resolveUsageAuth را بدون تبدیل‌شدن به اعتبارنامه استنتاج فعال کند، از providerUsageAuthEnvVars استفاده کنید. این نام‌ها به مسدودسازی 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 ارائه‌دهنده.

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

فیلدهای راه‌اندازی

مرجع uiHints

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

{  "uiHints": {    "apiKey": {      "label": "کلید API",      "help": "برای درخواست‌های OpenRouter استفاده می‌شود",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  }}

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

مرجع contracts

از contracts فقط برای فراداده ایستای مالکیت قابلیت استفاده کنید که OpenClaw بتواند بدون واردکردن زمان اجرای 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"],    "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 را درون‌پردازشی اعزام می‌کنند، نه یک sandbox در برابر Pluginهای بومی مخرب. از آن فقط برای سطوح همراه/اپراتوریِ به‌دقت بازبینی‌شده‌ای استفاده کنید که از قبل به احراز هویت HTTP در Gateway نیاز دارند. یک مسیر دارای مجوز، هنگام بسته‌بودن پذیرش کار ریشهٔ Gateway، فقط زمانی قابل دسترسی باقی می‌ماند که auth: "gateway" و gatewayRuntimeScopeSurface: "trusted-operator" مختص مسیر را نیز اعلام کند؛ مسیرهای هم‌سطح عادی از همان Plugin همچنان پشت مرز پذیرش می‌مانند. به این ترتیب، وضعیت تعلیق و ازسرگیری قابل دسترسی می‌ماند، بی‌آنکه دورزدن پذیرش به کل Plugin اعطا شود. تجزیه و شکل‌دهی پاسخ را بیرون از اعزام، محدود نگه دارید؛ کار اساسی یا تغییردهنده باید از طریق اعزام متد Gateway انجام شود که مالک اعمال پذیرش و دامنه است.

مرجع configContracts

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

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

هر ورودی 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 را بارگذاری کند، اما سطوح طرح‌وارهٔ پیکربندی در مسیر سرد، راه‌اندازی و Control UI تا پیش از اجرای زمان‌اجرای 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": "نشانی وب سرور خانگی",          "placeholder": "https://matrix.example.com"        }      },      "label": "Matrix",      "description": "اتصال به سرور خانگی Matrix",      "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 مالک فراداده میزبان و URL پایه هستند.

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

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

مرجع providerRequest

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

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

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

مرجع secretProviderIntegrations

وقتی یک Plugin می‌تواند یک پیش‌تنظیم قابل‌استفاده‌مجدد ارائه‌دهنده اجرایی SecretRef منتشر کند، از secretProviderIntegrations استفاده کنید. 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. مانیفست Plugin نصب‌شده modelCatalog.
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، در package.json و زیر بلوک openclaw قرار دارند. openclaw.bundle و openclaw.bundle.json قراردادهای Plugin در OpenClaw نیستند؛ Pluginهای بومی باید از openclaw.plugin.json به‌همراه فیلدهای پشتیبانی‌شدهٔ package.json#openclaw در ادامه استفاده کنند.

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

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

برای openclaw.channel.cliAddOptions، از نحو گزینهٔ بلند Commander مانند --initial-sync-limit <n> استفاده کنید. valueType: "int" را برای تجزیهٔ یک عدد صحیح نامنفی یا valueType: "list" را برای تقسیم ورودی جداشده با ویرگول، نقطه‌ویرگول یا خط جدید به رشته‌ها، پیش از دریافت آن توسط آداپتور راه‌اندازی Plugin، تنظیم کنید. برای عبور بدون تغییر مقدار تجزیه‌شدهٔ Commander، valueType را حذف کنید.

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

openclaw.install.requiredPlatformPackages برای بسته‌های npm است که باینری‌های بومی موردنیاز را از طریق نام‌های مستعار اختیاری و مختص پلتفرم ارائه می‌کنند. نام سادهٔ بستهٔ npm را برای نام مستعار هر پلتفرم پشتیبانی‌شده فهرست کنید. هنگام نصب npm، OpenClaw فقط نام مستعار اعلام‌شده‌ای را بررسی می‌کند که محدودیت‌های lockfile آن با میزبان فعلی مطابقت دارد. اگر 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 رجیستری مورد اعتماد، از جمله نام سادهٔ بسته‌ها و dist-tagها را ارائه می‌دهد. عیب‌یابی کاتالوگ می‌تواند میان منابع دقیق، شناور، سنجاق‌شده با یکپارچگی، فاقد یکپارچگی، دارای عدم تطابق نام بسته و دارای انتخاب پیش‌فرض نامعتبر تمایز بگذارد. همچنین وقتی expectedIntegrity موجود است اما هیچ منبع معتبر npm برای سنجاق‌کردن وجود ندارد، هشدار می‌دهد. هنگامی که expectedIntegrity موجود است، جریان‌های نصب/به‌روزرسانی آن را اعمال می‌کنند؛ هنگامی که حذف شده است، تفکیک رجیستری بدون سنجاق یکپارچگی ثبت می‌شود.

Pluginهای کانال باید زمانی که اسکن‌های وضعیت، فهرست کانال یا SecretRef نیاز دارند حساب‌های پیکربندی‌شده را بدون بارگذاری کامل زمان اجرا شناسایی کنند، openclaw.setupEntry را ارائه دهند. ورودی راه‌اندازی باید فرادادهٔ کانال را به‌همراه آداپتورهای ایمن برای راه‌اندازیِ پیکربندی، وضعیت و اسرار ارائه کند؛ کلاینت‌های شبکه، شنونده‌های 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 از بررسی‌های ارزان پیکربندی‌شدن پشتیبانی می‌کند. هنگامی که متغیرهای محیطی کافی هستند، فرادادهٔ اعلانی محیط را ترجیح دهید:

{  "openclaw": {    "channel": {      "id": "telegram",      "configuredState": {        "env": {          "allOf": ["TELEGRAM_BOT_TOKEN"]        }      }    }  }}

هنگامی که همهٔ متغیرهای فهرست‌شده الزامی‌اند از env.allOf و هنگامی که وجود هر یک از متغیرهای غیرخالی کافی است از env.anyOf استفاده کنید. اگر یک بررسی کوچک و غیرزمان‌اجرا به چیزی بیش از فرادادهٔ محیط نیاز دارد، مطابق نمونهٔ persistedAuthState از specifier به‌همراه exportName استفاده کنید؛ وقتی env وجود داشته باشد، OpenClaw بدون بارگذاری آن ماژول از آن استفاده می‌کند. اگر بررسی به تفکیک کامل پیکربندی یا زمان اجرای واقعی کانال نیاز دارد، آن منطق را در هوک 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. هر نامزد کشف‌شدهٔ دیگر

پیامدها:

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

الزامات JSON Schema

• هر Plugin باید یک JSON Schema ارائه کند، حتی اگر هیچ پیکربندی‌ای نپذیرد.
• یک Schema خالی قابل قبول است (برای مثال، { "type": "object", "additionalProperties": false }).
• Schemaها هنگام خواندن/نوشتن پیکربندی اعتبارسنجی می‌شوند، نه در زمان اجرا.
• هنگام گسترش یا forkکردن یک Plugin همراه با کلیدهای پیکربندی جدید، هم‌زمان openclaw.plugin.json configSchema آن Plugin را نیز به‌روزرسانی کنید. 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 تجزیه می‌شوند؛ بنابراین توضیحات، ویرگول‌های انتهایی و کلیدهای بدون نقل‌قول پذیرفته می‌شوند، مشروط بر اینکه مقدار نهایی همچنان یک شیء باشد.
• بارگذار مانیفست فقط فیلدهای مستندشدهٔ مانیفست را می‌خواند. از کلیدهای سفارشی سطح بالا اجتناب کنید.
• channels، providers، cliBackends و skills همگی می‌توانند در صورت بی‌نیازی Plugin حذف شوند.
• 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 صرفاً اعلانی است. وضعیت، ممیزی، اعتبارسنجی تحویل Cron و دیگر سطوح صرفاً خواندنی، پیش از پیکربندی‌شده تلقی‌کردن یک متغیر محیطی، همچنان سیاست اعتماد Plugin و فعال‌سازی مؤثر را اعمال می‌کنند.
• برای فرادادهٔ راهنمای زمان اجرا که به کد ارائه‌دهنده نیاز دارد، به هوک‌های زمان اجرای ارائه‌دهنده مراجعه کنید.
• اگر Plugin شما به ماژول‌های بومی وابسته است، مراحل ساخت و همهٔ الزامات فهرست مجاز مدیر بسته را مستند کنید (برای مثال، pnpm allow-build-scripts + pnpm rebuild <package>).

مرتبط