راه‌اندازی و پیکربندی 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": "My Channel",      "blurb": "Short description of the channel."    }  }}

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

مثال:

{  "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 فرادادهٔ بسته است، نه فرادادهٔ مانیفست.

{  "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(...) استفاده کنید. این تابع از منطقهٔ زبانی جادوگر CLI پیروی می‌کند (ابتدا OPENCLAW_LOCALE، سپس متغیرهای منطقهٔ زبانی سیستم) و در صورت نبود ترجمه به انگلیسی بازمی‌گردد. متن راه‌اندازی ویژهٔ Plugin را در کد متعلق به همان Plugin نگه دارید و کلیدهای کاتالوگ مشترک را فقط برای برچسب‌های عمومی راه‌اندازی، متن وضعیت و متن راه‌اندازی Pluginهای رسمی همراه به‌کار ببرید.

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

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

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

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

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

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

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

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

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

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

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

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

از buildChannelConfigSchema برای تبدیل یک طرح‌وارهٔ Zod به پوشش ChannelConfigSchema استفاده کنید که مصنوعات پیکربندی متعلق به 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 صرف‌نظر کند:

  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