راه‌اندازی و پیکربندی Plugin

مرجع بسته‌بندی Plugin (فرادادهٔ package.json)، مانیفست‌ها (openclaw.plugin.json)، ورودی‌های راه‌اندازی و طرح‌واره‌های پیکربندی.

فرادادهٔ بسته

package.json شما به یک فیلد openclaw نیاز دارد که به سامانهٔ Plugin اعلام کند Plugin شما چه چیزی ارائه می‌دهد:

{  "name": "@myorg/openclaw-my-channel",  "version": "1.0.0",  "type": "module",  "openclaw": {    "extensions": ["./index.ts"],    "setupEntry": "./setup-entry.ts",    "channel": {      "id": "my-channel",      "label": "کانال من",      "blurb": "توضیح کوتاهی دربارهٔ کانال."    }  }}

{  "name": "@myorg/openclaw-my-plugin",  "version": "1.0.0",  "type": "module",  "dependencies": {    "typebox": "1.1.39"  },  "peerDependencies": {    "openclaw": ">=2026.3.24-beta.2"  },  "openclaw": {    "extensions": ["./index.ts"],    "compat": {      "pluginApi": ">=2026.3.24-beta.2",      "minGatewayVersion": "2026.3.24-beta.2"    },    "build": {      "openclawVersion": "2026.3.24-beta.2",      "pluginSdkVersion": "2026.3.24-beta.2"    }  }}

فیلدهای openclaw

openclaw.channel

openclaw.channel فرادادهٔ کم‌هزینهٔ بسته برای کشف کانال و سطوح راه‌اندازی، پیش از بارگیری زمان اجرا است.

فیلدهای راه‌اندازی متعلق به کانال

Pluginهای کانال باید فیلدهای راه‌اندازی را یک‌بار در کد زمان اجرا با defineChannelSetupContract(...) تعریف کنند و تصویر سریال‌پذیر متناظر را زیر openclaw.channel.setup.fields منتشر کنند. تعریف زمان اجرا، نوع ورودی محلی Plugin را استنتاج می‌کند، مقادیر هدایت‌شده و غیرتعاملی را تجزیه می‌کند و کلیدهای مختص کانال را از نوع‌های هسته دور نگه می‌دارد. فرادادهٔ بسته به openclaw channels add <channel-id> --help و openclaw channels add --channel <channel-id> --help اجازه می‌دهد بدون بارگیری Plugin، فقط گزینه‌های کانال انتخاب‌شده را کشف کنند.

 export const setupContract = defineChannelSetupContract({  fields: {    endpoint: {      kind: "string",      cli: { flags: "--endpoint <url>", description: "نقطهٔ پایانی سرویس" },    },    transport: {      kind: "choice",      choices: ["native", "container"],      cli: { flags: "--transport <kind>", description: "مالک انتقال" },    },  },  adapter: {    applyAccountConfig: ({ cfg, input }) => ({      ...cfg,      channels: { ...cfg.channels, example: input },    }),  },});

{  "openclaw": {    "channel": {      "id": "example",      "setup": {        "fields": [          {            "key": "endpoint",            "kind": "string",            "cli": { "flags": "--endpoint <url>", "description": "نقطهٔ پایانی سرویس" }          },          {            "key": "transport",            "kind": "choice",            "choices": ["native", "container"],            "cli": { "flags": "--transport <kind>", "description": "مالک انتقال" }          }        ]      }    }  }}

انواع فیلد پشتیبانی‌شده عبارت‌اند از string، boolean، integer، string-list و choice. برای اطلاعات ورود از sensitive: true استفاده کنید. کلید هر فیلد باید با نام ویژگی camelCase پرچم بلند CLI آن، از جمله هر شکل منفی‌شده، برابر باشد؛ مانند apiToken برای --api-token. وقتی هر دو شکل مثبت و --no-* لازم باشند، فیلدهای بولی می‌توانند cli.negatedFlags را اضافه کنند. channel، account و name مربوط به نمایش حساب، همچنان پوشش کنترلی مشترک باقی می‌مانند.

آداپتور منتشرشدهٔ setup/ChannelSetupInput برای Pluginهای خارجی موجود همچنان در دسترس است. Pluginهای جدید باید setupContract را ارائه کنند؛ OpenClaw هرگاه هر دو موجود باشند، همیشه آن را ترجیح می‌دهد.

مثال:

{  "openclaw": {    "channel": {      "id": "my-channel",      "label": "کانال من",      "selectionLabel": "کانال من (خودمیزبان)",      "detailLabel": "ربات کانال من",      "docsPath": "/channels/my-channel",      "docsLabel": "my-channel",      "blurb": "یکپارچه‌سازی گفت‌وگوی خودمیزبان مبتنی بر Webhook.",      "order": 80,      "aliases": ["mc"],      "preferOver": ["my-channel-legacy"],      "selectionDocsPrefix": "راهنما:",      "selectionExtras": ["Markdown"],      "markdownCapable": true,      "exposure": {        "configured": true,        "setup": true,        "docs": true      },      "quickstartAllowFrom": true    }  }}

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

• configured: کانال را در سطوح فهرست‌سازی پیکربندی‌شده/سبک وضعیت قرار می‌دهد
• setup: کانال را در انتخاب‌گرهای تعاملی راه‌اندازی/پیکربندی قرار می‌دهد
• docs: کانال را در سطوح مستندات/ناوبری به‌عنوان عمومی علامت‌گذاری می‌کند

openclaw.install

openclaw.install فرادادهٔ بسته است، نه فرادادهٔ مانیفست.

{  "openclaw": {    "install": {      "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3",      "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",      "defaultChoice": "npm"    }  }}

بارگذاری کاملِ به‌تعویق‌افتاده

Pluginهای کانال می‌توانند با پیکربندی زیر بارگذاری به‌تعویق‌افتاده را فعال کنند:

{  "openclaw": {    "extensions": ["./index.ts"],    "setupEntry": "./setup-entry.ts",    "startup": {      "deferConfiguredChannelFullLoadUntilAfterListen": true    }  }}

هنگام فعال بودن، OpenClaw در مرحلهٔ راه‌اندازی پیش از گوش‌دادن فقط setupEntry را بارگذاری می‌کند، حتی برای کانال‌هایی که از قبل پیکربندی شده‌اند. ورودی کامل پس از آغاز گوش‌دادن Gateway بارگذاری می‌شود.

اگر ورودی راه‌اندازی/کامل شما متدهای RPC مربوط به Gateway را ثبت می‌کند، آن‌ها را زیر یک پیشوند ویژهٔ Plugin نگه دارید. فضاهای نام مدیریتی رزروشدهٔ هسته (config.*، exec.approvals.*، wizard.*، update.*) در مالکیت هسته باقی می‌مانند و همیشه به operator.admin نرمال‌سازی می‌شوند.

مانیفست Plugin

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

{  "id": "my-plugin",  "name": "My Plugin",  "description": "Adds My Plugin capabilities to OpenClaw",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "webhookSecret": {        "type": "string",        "description": "Webhook verification secret"      }    }  }}

برای Pluginهای کانال، channels را اضافه کنید (و Pluginهای ارائه‌دهنده providers را اضافه می‌کنند):

{  "id": "my-channel",  "channels": ["my-channel"],  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {}  }}

حتی Pluginهای بدون پیکربندی نیز باید یک طرح‌واره ارائه کنند. طرح‌وارهٔ خالی معتبر است:

{  "id": "my-plugin",  "configSchema": {    "type": "object",    "additionalProperties": false  }}

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

انتشار در ClawHub

Skills و بسته‌های Plugin از فرمان‌های انتشار جداگانهٔ ClawHub استفاده می‌کنند. برای بسته‌های Plugin، از فرمان ویژهٔ بسته استفاده کنید:

clawhub package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-plugin

ورودی راه‌اندازی

setup-entry.ts جایگزینی سبک‌وزن برای index.ts است که OpenClaw هنگامی بارگذاری می‌کند که فقط به بخش‌های راه‌اندازی نیاز دارد (راه‌اندازی اولیه، ترمیم پیکربندی، بررسی کانال غیرفعال):

// setup-entry.ts  export default defineSetupPluginEntry(myChannelPlugin);

این کار از بارگذاری کد سنگین زمان اجرا (کتابخانه‌های رمزنگاری، ثبت‌های CLI، سرویس‌های پس‌زمینه) هنگام جریان‌های راه‌اندازی جلوگیری می‌کند.

کانال‌های فضای کاری همراه محصول که خروجی‌های امن برای راه‌اندازی را در ماژول‌های جانبی نگه می‌دارند، می‌توانند به‌جای defineSetupPluginEntry(...) از defineBundledChannelSetupEntry(...) در openclaw/plugin-sdk/channel-entry-contract استفاده کنند. آن قرارداد همراه محصول همچنین از خروجی اختیاری runtime پشتیبانی می‌کند تا سیم‌کشی زمان اجرا هنگام راه‌اندازی سبک‌وزن و صریح باقی بماند.

درون‌ریزی‌های محدود کمک‌ابزار راه‌اندازی

برای مسیرهای داغ و مختص راه‌اندازی، هنگامی که فقط به بخشی از سطح راه‌اندازی نیاز دارید، درگاه‌های محدود کمک‌ابزار راه‌اندازی را به چتر گسترده‌تر plugin-sdk/setup ترجیح دهید:

هنگامی که مجموعه‌ابزار مشترک کامل راه‌اندازی، از جمله کمک‌ابزارهای وصلهٔ پیکربندی مانند moveSingleAccountChannelSectionToDefaultAccount(...)، را می‌خواهید از درگاه گسترده‌تر plugin-sdk/setup استفاده کنید.

برای متن ثابت جادوگر راه‌اندازی از createSetupTranslator(...) استفاده کنید. این بخش به‌ترتیب از نخستین مقدار غیرخالی میان OPENCLAW_LOCALE، LC_ALL، LC_MESSAGES و LANG استفاده می‌کند و سپس به انگلیسی برمی‌گردد. برای بازنویسی صریح انگلیسی، OPENCLAW_LOCALE=en را تنظیم کنید. متن راه‌اندازی ویژهٔ Plugin را در کد متعلق به Plugin نگه دارید و فقط برای برچسب‌های مشترک راه‌اندازی، متن وضعیت و متن راه‌اندازی Pluginهای رسمی همراه محصول از کلیدهای کاتالوگ مشترک استفاده کنید.

آداپتورهای وصلهٔ راه‌اندازی هنگام درون‌ریزی برای مسیر داغ ایمن باقی می‌مانند. جست‌وجوی سطح قرارداد ارتقای حساب منفرد همراه محصول آن‌ها تنبل است؛ بنابراین درون‌ریزی plugin-sdk/setup-runtime پیش از استفادهٔ واقعی از آداپتور، کشف سطح قرارداد همراه محصول را مشتاقانه بارگذاری نمی‌کند.

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

ChannelSetupInput یک پوشش عمومی مشترک میان فراخواننده‌های راه‌اندازی و Pluginهای کانال است. فیلدهای دارای نوع دائمی آن عبارت‌اند از name، token، tokenFile، useEnv، allowFrom و defaultTo. کلیدهای اضافی متعلق به Plugin همچنان می‌توانند در شیء ورودی زمان اجرا وجود داشته باشند، اما نوع مشترک هیچ امضای شاخصی را اعلام نمی‌کند. هر Plugin باید فیلدهای راه‌اندازی خود را اعلام و محدود کند یا آن‌ها را با یک طرح‌وارهٔ متعلق به Plugin در مرز آداپتور اعتبارسنجی کند:

 type AcmeSetupInput = ChannelSetupInput & {  workspaceId?: string;  webhookUrl?: string;}; export const acmeSetupAdapter: ChannelSetupAdapter = {  applyAccountConfig: ({ cfg, input }) => {    const setupInput = input as AcmeSetupInput;    return {      ...cfg,      channels: {        ...cfg.channels,        acme: {          token: setupInput.token,          workspaceId: setupInput.workspaceId,          webhookUrl: setupInput.webhookUrl,        },      },    };  },};

فیلدهای مختص کانال که پیش‌تر مستقیماً روی ChannelSetupInput تعریف شده بودند، برای سازگاری با کد منبع خارجی موقتاً دارای نوع باقی می‌مانند. آن‌ها منسوخ شده‌اند. پیمایش رجیستری در 2026-07-22 روی 426 Plugin کانال منتشرشده خارج از درخت، 21 فیلد بدون خواننده را حذف کرد و 22 فیلد دارای خواننده‌های شناخته‌شده را نگه داشت. هر فیلد نگه‌داشته‌شده به‌محض اینکه هیچ Plugin منتشرشده‌ای آن را نخواند، حذف می‌شود؛ هیچ مرز نسخه‌ای لازم نیست. Pluginهای جدید و همراه نباید به این لایه متکی باشند؛ فیلدهای تحت مالکیت خود را به‌صورت محلی تعریف کنید.

ارتقای تک‌حساب تحت مالکیت کانال

هنگامی که یک کانال از پیکربندی سطح‌بالای تک‌حساب به channels.<id>.accounts.* ارتقا می‌یابد، رفتار مشترک پیش‌فرض، مقادیر ارتقایافته در محدوده حساب را به accounts.default منتقل می‌کند.

هر Plugin کانال می‌تواند این ارتقا را از طریق آداپتور راه‌اندازی خود گسترش دهد یا محدودتر کند:

• singleAccountKeysToMove: کلیدهای سطح‌بالای اضافی که باید به حساب ارتقایافته منتقل شوند
• namedAccountPromotionKeys: وقتی حساب‌های نام‌گذاری‌شده از قبل وجود دارند، فقط این کلیدها به حساب ارتقایافته منتقل می‌شوند؛ کلیدهای مشترک سیاست/تحویل در ریشه کانال باقی می‌مانند
• resolveSingleAccountPromotionTarget(...): انتخاب کنید کدام حساب موجود مقادیر ارتقایافته را دریافت کند

وجود singleAccountKeysToMove نشان می‌دهد قرارداد ارتقا کامل است. حتی وقتی این فیلد یک آرایه خالی است، آن را تعریف کنید تا از ارتقای کلیدهای قدیمی انصراف دهید. آداپتورهایی که این فیلد را حذف می‌کنند، برای Pluginهای ازپیش‌منتشرشده یک لایه ارتقای پیش از تعریف با پشتوانه خواننده را حفظ می‌کنند. پیمایش رجیستری در 2026-07-22، تعداد 23 کلید بدون وابسته منتشرشده را حذف کرد و شش کلید رایج به‌همراه کلید صرفاً مخصوص راه‌اندازی rooms را نگه داشت. هر کلید نگه‌داشته‌شده به‌محض اینکه خواننده‌های منتشرشده آن به تعریف‌ها مهاجرت کنند، حذف می‌شود؛ هیچ مرز نسخه‌ای لازم نیست.

هنگامی که doctor باید این تعریف‌ها را از آرتیفکت سبک راه‌اندازی همراه بارگذاری کند، openclaw.setupFeatures.configPromotion: true را در مانیفست بسته Plugin تعریف کنید. سطح Plugin صرفاً مخصوص راه‌اندازی و Plugin کامل کانال باید تعریف‌های یکسانی ارائه دهند.

هنگام فراخوانی moveSingleAccountChannelSectionToDefaultAccount(...) با یک Plugin ازپیش‌حل‌شده، آداپتور راه‌اندازی آن را به‌عنوان setupSurface ارسال کنید. سطوح راه‌اندازی ارائه‌شده توسط فراخواننده بر جست‌وجوی بارگذاری‌شده و همراه اولویت دارند؛ در نتیجه Pluginهای محدوده‌بندی‌شده یا صرفاً مخصوص راه‌اندازی از ثبت سراسری مستقل می‌مانند.

شِمای پیکربندی

پیکربندی Plugin در برابر JSON Schema موجود در مانیفست اعتبارسنجی می‌شود. کاربران Pluginها را از این طریق پیکربندی می‌کنند:

{  plugins: {    entries: {      "my-plugin": {        config: {          webhookSecret: "abc123",        },      },    },  },}

Plugin شما هنگام ثبت، این پیکربندی را به‌صورت api.pluginConfig دریافت می‌کند.

برای پیکربندی مختص کانال، در عوض از بخش پیکربندی کانال استفاده کنید:

{  channels: {    "my-channel": {      token: "bot-token",      allowFrom: ["user1", "user2"],    },  },}

ساخت شِماهای پیکربندی کانال

برای تبدیل یک شِمای Zod به پوشش ChannelConfigSchema که آرتیفکت‌های پیکربندی تحت مالکیت Plugin از آن استفاده می‌کنند، از buildChannelConfigSchema استفاده کنید:

  const accountSchema = z.object({  token: z.string().optional(),  allowFrom: z.array(z.string()).optional(),  accounts: z.object({}).catchall(z.any()).optional(),  defaultAccount: z.string().optional(),}); const configSchema = buildChannelConfigSchema(accountSchema);

اگر قرارداد را از قبل به‌صورت JSON Schema یا TypeBox می‌نویسید، از تابع کمکی مستقیم استفاده کنید تا OpenClaw بتواند در مسیرهای فراداده از تبدیل Zod به JSON Schema صرف‌نظر کند:

  const configSchema = buildJsonChannelConfigSchema(  Type.Object({    token: Type.Optional(Type.String()),    allowFrom: Type.Optional(Type.Array(Type.String())),  }),);

برای Pluginهای شخص ثالث، قرارداد مسیر سرد همچنان مانیفست Plugin است: JSON Schema تولیدشده را در openclaw.plugin.json#channelConfigs بازتاب دهید تا سطوح شِمای پیکربندی، راه‌اندازی و رابط کاربری بتوانند بدون بارگذاری کد زمان اجرا، channels.<id> را بررسی کنند.

جادوگرهای راه‌اندازی

Pluginهای کانال می‌توانند جادوگرهای راه‌اندازی تعاملی برای openclaw onboard ارائه دهند. جادوگر یک شیء ChannelSetupWizard روی ChannelPlugin است:

 const setupWizard: ChannelSetupWizard = {  channel: "my-channel",  status: {    configuredLabel: "Connected",    unconfiguredLabel: "Not configured",    resolveConfigured: ({ cfg }) => Boolean((cfg.channels as any)?.["my-channel"]?.token),  },  credentials: [    {      inputKey: "token",      providerHint: "my-channel",      credentialLabel: "Bot token",      preferredEnvVar: "MY_CHANNEL_BOT_TOKEN",      envPrompt: "Use MY_CHANNEL_BOT_TOKEN from environment?",      keepPrompt: "Keep current token?",      inputPrompt: "Enter your bot token:",      inspect: ({ cfg, accountId }) => {        const token = (cfg.channels as any)?.["my-channel"]?.token;        return {          accountConfigured: Boolean(token),          hasConfiguredValue: Boolean(token),        };      },    },  ],};

ChannelSetupWizard همچنین از textInputs، dmPolicy، allowFrom، groupAccess، prepare، finalize و موارد دیگر پشتیبانی می‌کند. برای مشاهده یک نمونه کامل همراه، به src/setup-core.ts در Plugin مربوط به Discord مراجعه کنید.

import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup"; const setupSurface = createOptionalChannelSetupSurface({  channel: "my-channel",  label: "My Channel",  npmSpec: "@myorg/openclaw-my-channel",  docsPath: "/channels/my-channel",});// Returns { setupAdapter, setupWizard }

انتشار و نصب

Pluginهای خارجی: در ClawHub منتشر کنید، سپس نصب کنید:

openclaw plugins install @myorg/openclaw-my-plugin

openclaw plugins install clawhub:@myorg/openclaw-my-plugin

openclaw plugins install npm:@myorg/openclaw-my-plugin

Pluginهای داخل مخزن: آن‌ها را زیر درخت فضای کاری Pluginهای همراه قرار دهید؛ در طول ساخت به‌طور خودکار شناسایی می‌شوند.

فراداده بسته همراه صریح است و هنگام راه‌اندازی Gateway از JavaScript ساخته‌شده استنباط نمی‌شود. وابستگی‌های زمان اجرا به بسته Plugin مالک آن‌ها تعلق دارند؛ راه‌اندازی OpenClaw بسته‌بندی‌شده هرگز وابستگی‌های Plugin را ترمیم یا بازتاب نمی‌دهد.

مرتبط

• ساخت Pluginها — راهنمای گام‌به‌گام شروع کار
• مانیفست Plugin — مرجع کامل شِمای مانیفست
• نقاط ورود SDK — definePluginEntry و defineChannelPluginEntry