إعداد Plugin وتكوينه

مرجع لتغليف المكوّنات الإضافية (بيانات package.json الوصفية)، والبيانات التعريفية (openclaw.plugin.json)، وإدخالات الإعداد، ومخططات الإعدادات.

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

يحتاج package.json لديك إلى حقل openclaw يخبر نظام المكوّنات الإضافية بما يقدّمه المكوّن الإضافي:

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

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

يمكن للمكوّنات الإضافية للقنوات الاشتراك في التحميل المؤجل عبر:

{  "openclaw": {    "extensions": ["./index.ts"],    "setupEntry": "./setup-entry.ts",    "startup": {      "deferConfiguredChannelFullLoadUntilAfterListen": true    }  }}

عند تفعيله، يحمّل OpenClaw فقط setupEntry أثناء مرحلة بدء التشغيل السابقة للاستماع، حتى للقنوات المهيأة مسبقًا. يتم تحميل الإدخال الكامل بعد أن يبدأ Gateway بالاستماع.

إذا كان إدخال الإعداد/الكامل لديك يسجّل طرق Gateway RPC، فأبقِها على بادئة خاصة بالمكوّن الإضافي. تبقى مساحات أسماء إدارة النواة المحجوزة (config.* وexec.approvals.* وwizard.* وupdate.*) مملوكة للنواة وتُحل دائمًا إلى operator.admin.

بيان المكوّن الإضافي

يجب أن يشحن كل مكوّن إضافي أصلي ملف openclaw.plugin.json في جذر الحزمة. يستخدم OpenClaw هذا للتحقق من الإعدادات دون تنفيذ كود المكوّن الإضافي.

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

بالنسبة إلى المكوّنات الإضافية للقنوات، أضف 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(...).

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

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