نقاط دخول Plugin

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

{
  "openclaw": {
    "extensions": ["./src/index.ts"],
    "runtimeExtensions": ["./dist/index.js"],
    "setupEntry": "./src/setup-entry.ts",
    "runtimeSetupEntry": "./dist/setup-entry.js"
  }
}

​

definePluginEntry

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Short summary",
  register(api) {
    api.registerProvider({
      /* ... */
    });
    api.registerTool({
      /* ... */
    });
  },
});

• يجب أن يطابق id بيان openclaw.plugin.json الخاص بك.
• يُستخدم kind للفتحات الحصرية: "memory" أو "context-engine".
• يمكن أن يكون configSchema دالة للتقييم الكسول.
• يحل OpenClaw هذا المخطط ويخزّنه مؤقتًا عند أول وصول، لذلك لا تعمل بُناة المخططات المكلفة إلا مرة واحدة.

​

defineChannelPluginEntry

import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";

export default defineChannelPluginEntry({
  id: "my-channel",
  name: "My Channel",
  description: "Short summary",
  plugin: myChannelPlugin,
  setRuntime: setMyRuntime,
  registerCliMetadata(api) {
    api.registerCli(/* ... */);
  },
  registerFull(api) {
    api.registerGatewayMethod(/* ... */);
  },
});

• يُستدعى setRuntime أثناء التسجيل حتى تتمكن من تخزين مرجع وقت التشغيل (عادةً عبر createPluginRuntimeStore). يتم تخطيه أثناء التقاط بيانات CLI الوصفية.
• يعمل registerCliMetadata أثناء api.registrationMode === "cli-metadata"، وapi.registrationMode === "discovery"، و api.registrationMode === "full". استخدمه كمكان مرجعي لموصّفات CLI المملوكة للقناة حتى تبقى المساعدة الجذرية غير مفعّلة، وتتضمن لقطات الاكتشاف بيانات تعريف أوامر ثابتة، ويبقى تسجيل أوامر CLI العادي متوافقًا مع تحميلات Plugin الكاملة.
• تسجيل الاكتشاف غير مفعّل، وليس خاليًا من الاستيراد. قد يقيّم OpenClaw إدخال Plugin الموثوق ووحدة Plugin القناة لبناء اللقطة، لذلك أبقِ الاستيرادات على المستوى الأعلى خالية من الآثار الجانبية، وضع المقابس والعملاء والعمّال والخدمات خلف مسارات "full" فقط.
• لا يعمل registerFull إلا عندما يكون api.registrationMode === "full". يتم تخطيه أثناء التحميل المخصص للإعداد فقط.
• مثل definePluginEntry، يمكن أن يكون configSchema مصنعًا كسولًا، ويخزّن OpenClaw المخطط المحلول مؤقتًا عند أول وصول.
• بالنسبة إلى أوامر CLI الجذرية المملوكة لـ Plugin، فضّل api.registerCli(..., { descriptors: [...] }) عندما تريد أن يبقى الأمر محمّلًا بكسل دون أن يختفي من شجرة تحليل CLI الجذرية. بالنسبة إلى أوامر ميزات العقد المزدوجة، فضّل api.registerNodeCliFeature(...) حتى يقع الأمر تحت openclaw nodes. بالنسبة إلى أوامر Plugin المتداخلة الأخرى، أضف parentPath وسجّل الأوامر على كائن program الممرّر إلى المسجّل؛ يحلّه OpenClaw إلى الأمر الأب قبل استدعاء Plugin. بالنسبة إلى Channel Plugins، فضّل تسجيل تلك الموصّفات من registerCliMetadata(...) وأبقِ registerFull(...) مركّزًا على العمل الخاص بوقت التشغيل فقط.
• إذا كان registerFull(...) يسجّل أيضًا طرق RPC في Gateway، فأبقها على بادئة خاصة بـ Plugin. تُجبر مساحات أسماء الإدارة الأساسية المحجوزة (config.*، exec.approvals.*، وwizard.*، وupdate.*) دائمًا على operator.admin.

​

defineSetupPluginEntry

import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";

export default defineSetupPluginEntry(myChannelPlugin);

• openclaw/plugin-sdk/setup-runtime لدوال الإعداد المساعدة الآمنة لوقت التشغيل مثل محوّلات تصحيح الإعداد الآمنة للاستيراد، ومخرجات ملاحظات البحث، promptResolvedAllowFrom، وsplitSetupEntries، ووكلاء الإعداد المفوّضين
• openclaw/plugin-sdk/channel-setup لأسطح إعداد التثبيت الاختياري
• openclaw/plugin-sdk/setup-tools لدوال CLI/الأرشيف/التوثيق المساعدة للإعداد/التثبيت

import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract";

export default defineBundledChannelSetupEntry({
  importMetaUrl: import.meta.url,
  plugin: {
    specifier: "./channel-plugin-api.js",
    exportName: "myChannelPlugin",
  },
  runtime: {
    specifier: "./runtime-api.js",
    exportName: "setMyChannelRuntime",
  },
});

​

وضع التسجيل

register(api) {
  if (
    api.registrationMode === "cli-metadata" ||
    api.registrationMode === "discovery" ||
    api.registrationMode === "full"
  ) {
    api.registerCli(/* ... */);
    if (api.registrationMode === "cli-metadata") return;
  }

  api.registerChannel({ plugin: myPlugin });
  if (api.registrationMode !== "full") return;

  // Heavy runtime-only registrations
  api.registerService(/* ... */);
}

• استخدم descriptors عندما يملك المسجِّل أمرا جذريا واحدا أو أكثر وتريد من OpenClaw تحميل وحدة CLI الفعلية كسولا عند أول استدعاء
• تأكد من أن تلك الواصفات تغطي كل جذر أمر من المستوى الأعلى يعرّضه المسجِّل
• أبقِ أسماء أوامر الواصفات مقتصرة على الأحرف والأرقام والواصلة والشرطة السفلية، وأن تبدأ بحرف أو رقم؛ يرفض OpenClaw أسماء الواصفات الخارجة عن هذا الشكل ويزيل تسلسلات التحكم الطرفية من الأوصاف قبل عرض المساعدة
• استخدم commands وحدها فقط لمسارات التوافق المحمّلة بشغف

​

أشكال Plugin

​

ذو صلة

• نظرة عامة على SDK - واجهة API للتسجيل ومرجع المسارات الفرعية
• مساعدات وقت التشغيل - api.runtime وcreatePluginRuntimeStore
• الإعداد والتكوين - البيان، نقطة دخول الإعداد، التحميل المؤجل
• Plugins القنوات - بناء كائن ChannelPlugin
• Plugins المزوّدين - تسجيل المزوّد والخطافات