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

نمونه:

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

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

مانیفست 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هایی که هیچ پیکربندی‌ای ندارند نیز باید یک طرحواره ارائه کنند. یک طرحواره خالی معتبر است:

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

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

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

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

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

برای متن ثابت ویزارد راه‌اندازی از createSetupTranslator(...) استفاده کنید. این تابع از locale ویزارد CLI (OPENCLAW_LOCALE، سپس متغیرهای locale سیستم) پیروی می‌کند و به انگلیسی برمی‌گردد. متن راه‌اندازی اختصاصی Plugin را در کد متعلق به Plugin نگه دارید و کلیدهای کاتالوگ مشترک را فقط برای برچسب‌های رایج راه‌اندازی، متن وضعیت، و متن راه‌اندازی Pluginهای رسمی همراه استفاده کنید.

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

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

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

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

• singleAccountKeysToMove: کلیدهای سطح بالای اضافی که باید به حساب ارتقایافته منتقل شوند
• namedAccountPromotionKeys: وقتی حساب‌های نام‌دار از قبل وجود دارند، فقط این کلیدها به حساب ارتقایافته منتقل می‌شوند؛ کلیدهای policy/delivery مشترک در ریشه کانال می‌مانند
• 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 به 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 بتواند در مسیرهای metadata از تبدیل 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 mirror کنید تا طرحواره پیکربندی، راه‌اندازی، و سطح‌های 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 }

انتشار و نصب

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های بسته‌بندی‌شده قرار دهید تا در زمان ساخت به‌صورت خودکار کشف شوند.

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

openclaw plugins install <package-name>

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

مرتبط

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