إعداد 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",
  "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 الاستماع.

إذا كان إدخال الإعداد/الإدخال الكامل لديك يسجل طرق Gateway RPC، فاحتفظ بها ضمن بادئة خاصة بـ 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

بالنسبة إلى حزم Plugins، استخدم أمر ClawHub الخاص بالحزمة:

clawhub package publish your-org/your-plugin --dry-run
clawhub 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 اختياريًا حتى تظل توصيلات وقت التشغيل أثناء الإعداد خفيفة وصريحة.

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

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

استخدم seam الأوسع 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> دون تحميل كود وقت التشغيل.

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

يمكن لـ 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 والمزيد. راجع حزم Plugins المضمّنة (مثل Discord Plugin 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

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

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

openclaw plugins install <package-name>

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

# ذو صلة

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