إعداد 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",  "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/[email protected]",      "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 القنوات، أضف kind وchannels:

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

حتى Plugins التي لا تحتوي على تهيئة يجب أن تشحن مخططًا. المخطط الفارغ صالح:

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

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

استيرادات مساعدي الإعداد الضيقة

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

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

تبقى محولات تصحيح الإعداد آمنة للمسارات الساخنة عند الاستيراد. يكون البحث في سطح عقد ترقية الحساب الواحد المضمّن كسولًا، لذلك لا يؤدي استيراد 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> دون تحميل كود وقت التشغيل.

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

يمكن لـ Channel 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 كلًا من 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 }

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

Plugins الخارجية: انشر إلى ClawHub، ثم ثبّت:

openclaw plugins install @myorg/openclaw-my-plugin

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

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

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

يمكن للمستخدمين التثبيت:

openclaw plugins install <package-name>

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

ذات صلة

• بناء Plugins — دليل بدء خطوة بخطوة
• بيان Plugin — مرجع مخطط البيان الكامل
• نقاط دخول SDK — definePluginEntry و defineChannelPluginEntry