إعداد Plugin وتهيئته

مرجع لتحزيم Plugin (بيانات package.json الوصفية)، والبيانات التعريفية (openclaw.plugin.json)، ومداخل الإعداد، ومخططات الإعدادات.

البيانات الوصفية للحزمة

يحتاج ملف package.json إلى حقل openclaw يوضّح لنظام Plugins ما يوفّره 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"    }  }}

تأجيل التحميل الكامل

يمكن لـ Plugins القنوات الاشتراك في التحميل المؤجّل باستخدام:

{  "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"      }    }  }}

بالنسبة إلى Plugins القنوات، أضف channels (وتضيف Plugins المزوّدات providers):

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

حتى Plugins التي لا تحتوي على إعدادات يجب أن توفّر مخططًا. المخطط الفارغ صالح:

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

راجع بيان Plugin للاطلاع على مرجع المخطط الكامل.

النشر على ClawHub

تستخدم حزم Skills وPlugins أوامر نشر منفصلة في ClawHub. بالنسبة إلى حزم Plugins، استخدم الأمر الخاص بالحزم:

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، وخدمات الخلفية) أثناء تدفقات الإعداد.

يمكن لقنوات مساحة العمل المضمّنة التي تحتفظ بصادرات آمنة للإعداد في وحدات جانبية استخدام defineBundledChannelSetupEntry(...) من openclaw/plugin-sdk/channel-entry-contract بدلًا من defineSetupPluginEntry(...). يدعم هذا العقد المضمّن أيضًا تصدير runtime اختياريًا، بحيث تظل توصيلات وقت التشغيل في أثناء الإعداد خفيفة وصريحة.

استيرادات مساعد الإعداد المحدودة

بالنسبة إلى المسارات السريعة الخاصة بالإعداد فقط، فضّل واجهات مساعد الإعداد المحدودة على الواجهة الشاملة الأوسع plugin-sdk/setup عندما لا تحتاج إلا إلى جزء من واجهة الإعداد:

استخدم الواجهة الأوسع plugin-sdk/setup عندما تريد مجموعة أدوات الإعداد المشتركة الكاملة، بما في ذلك مساعدات تصحيح الإعدادات مثل moveSingleAccountChannelSectionToDefaultAccount(...).

استخدم createSetupTranslator(...) للنصوص الثابتة في معالج الإعداد. فهو يتبع لغة معالج CLI (OPENCLAW_LOCALE، ثم متغيرات لغة النظام)، ويعود إلى الإنجليزية عند التعذّر. احتفظ بنصوص الإعداد الخاصة بكل Plugin داخل الشيفرة التي يملكها ذلك Plugin، واستخدم مفاتيح الكتالوج المشتركة فقط لتسميات الإعداد العامة، ونصوص الحالة، ونصوص إعداد Plugins الرسمية المضمّنة.

تظل محوّلات تصحيح الإعداد آمنة عند استيرادها في المسار السريع. ويكون البحث في واجهة عقد ترقية الحساب الفردي المضمّنة كسولًا، لذا لا يؤدي استيراد plugin-sdk/setup-runtime إلى تحميل اكتشاف واجهة العقد المضمّنة مسبقًا قبل استخدام المحوّل فعليًا.

ترقية الحساب الفردي المملوكة للقناة

عندما تنتقل قناة من إعداد علوي لحساب فردي إلى channels.<id>.accounts.*، ينقل السلوك المشترك الافتراضي القيم المرقّاة الخاصة بالحساب إلى accounts.default.

يمكن للقنوات المضمّنة تضييق نطاق هذه الترقية أو تجاوزها عبر واجهة عقد الإعداد الخاصة بها:

• singleAccountKeysToMove: مفاتيح علوية إضافية يجب نقلها إلى الحساب المرقّى
• namedAccountPromotionKeys: عندما تكون الحسابات المسماة موجودة بالفعل، تُنقل هذه المفاتيح فقط إلى الحساب المرقّى؛ وتبقى مفاتيح السياسة والتسليم المشتركة في جذر القناة
• resolveSingleAccountPromotionTarget(...): اختيار الحساب الموجود الذي يتلقى القيم المرقّاة

مخطط الإعدادات

يُتحقق من صحة إعدادات Plugin وفق JSON Schema الموجود في البيان. يضبط المستخدمون Plugins عبر:

{  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())),  }),);

بالنسبة إلى Plugins التابعة لجهات خارجية، يظل عقد المسار البارد هو بيان Plugin: انسخ JSON Schema المُنشأ إلى openclaw.plugin.json#channelConfigs بحيث تتمكن واجهات مخطط الإعدادات والإعداد وواجهة المستخدم من فحص channels.<id> دون تحميل شيفرة وقت التشغيل.

معالجات الإعداد

يمكن لـ Plugins القنوات توفير معالجات إعداد تفاعلية للأمر 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 }

النشر والتثبيت

الإضافات الخارجية: انشرها على ClawHub، ثم ثبّتها:

openclaw plugins install @myorg/openclaw-my-plugin

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

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

الإضافات داخل المستودع: ضعها ضمن شجرة مساحة عمل الإضافات المضمّنة؛ إذ تُكتشف تلقائيًا أثناء البناء.

بيانات تعريف الحزم المضمّنة صريحة، ولا تُستنتج من JavaScript المبني عند بدء تشغيل Gateway. تنتمي اعتماديات وقت التشغيل إلى حزمة الإضافة المالكة لها؛ ولا يُصلح تشغيل OpenClaw المعبّأ اعتماديات الإضافات ولا يعكسها مطلقًا.

ذو صلة

• إنشاء الإضافات — دليل بدء تدريجي خطوة بخطوة
• بيان الإضافة — مرجع مخطط البيان الكامل
• نقاط دخول SDK — definePluginEntry وdefineChannelPluginEntry