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

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

فراداده‌ی بسته

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": "My Channel",      "blurb": "Short description of the channel."    }  }}

{  "name": "@myorg/openclaw-my-plugin",  "version": "1.0.0",  "type": "module",  "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 فراداده‌ی سبک بسته برای کشف کانال و سطوح راه‌اندازی، پیش از بارگذاری زمان اجرا است.

مثال:

{  "openclaw": {    "channel": {      "id": "my-channel",      "label": "My Channel",      "selectionLabel": "My Channel (self-hosted)",      "detailLabel": "My Channel Bot",      "docsPath": "/channels/my-channel",      "docsLabel": "my-channel",      "blurb": "Webhook-based self-hosted chat integration.",      "order": 80,      "aliases": ["mc"],      "preferOver": ["my-channel-legacy"],      "selectionDocsPrefix": "Guide:",      "selectionExtras": ["Markdown"],      "markdownCapable": true,      "exposure": {        "configured": true,        "setup": true,        "docs": true      },      "quickstartAllowFrom": true    }  }}

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

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

openclaw.install

openclaw.install فراداده‌ی بسته است، نه فراداده‌ی manifest.

{  "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 در مرحله‌ی راه‌اندازی پیش از listen، حتی برای کانال‌هایی که از قبل پیکربندی شده‌اند، فقط setupEntry را بارگذاری می‌کند. ورودی کامل پس از شروع listen توسط gateway بارگذاری می‌شود.

اگر ورودی setup/full شما methodهای RPC مربوط به gateway را ثبت می‌کند، آن‌ها را روی پیشوند مخصوص Plugin نگه دارید. namespaceهای رزروشده‌ی مدیریت core (config.*، exec.approvals.*، wizard.*، update.*) در مالکیت core می‌مانند و همیشه به operator.admin resolve می‌شوند.

manifest مربوط به 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های کانال، kind و channels را اضافه کنید:

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

حتی Pluginهایی که هیچ پیکربندی‌ای ندارند باید یک schema ارائه کنند. schema خالی معتبر است:

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

برای مرجع کامل schema، manifest مربوط به Plugin را ببینید.

انتشار در ClawHub

برای بسته‌های Plugin، از دستور مخصوص بسته در ClawHub استفاده کنید:

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، سرویس‌های پس‌زمینه) در جریان‌های راه‌اندازی جلوگیری می‌کند.

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

importهای کم‌دامنه کمکی راه‌اندازی

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

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

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

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

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

کانال‌های همراه می‌توانند این ارتقا را از طریق سطح قرارداد راه‌اندازی خود محدود یا بازنویسی کنند:

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

طرح‌واره پیکربندی

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

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

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

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

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

ساختن طرح‌واره‌های پیکربندی کانال

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

  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 را در مسیرهای metadata کنار بگذارد:

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

برای Pluginهای شخص ثالث، قرارداد مسیر سرد همچنان manifest Plugin است: JSON Schema تولیدشده را در openclaw.plugin.json#channelConfigs منعکس کنید تا طرح‌واره پیکربندی، راه‌اندازی، و سطح‌های UI بتوانند 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 از credentials، textInputs، dmPolicy، allowFrom، groupAccess، prepare، finalize و موارد بیشتر پشتیبانی می‌کند. برای نمونه‌های کامل، بسته‌های Plugin همراه را ببینید (برای مثال Plugin مربوط به Discord در src/channel.setup.ts).

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 }

انتشار و نصب

پلاگین‌های خارجی: در 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های همراه قرار دهید تا هنگام ساخت به‌طور خودکار شناسایی شوند.

کاربران می‌توانند نصب کنند:

openclaw plugins install <package-name>

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

مرتبط

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