نقاط دخول Plugin

​

إدخالات الحزمة

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

• extensions وsetupEntry هما إدخالا المصدر، ويُستخدمان للتطوير في مساحة العمل ونسخ مستودعات git.
• يُفضّل استخدام runtimeExtensions وruntimeSetupEntry للحزم المثبّتة، إذ يتيحان لحزم npm تجاوز تصريف TypeScript في وقت التشغيل.
• يجب أن يطابق runtimeExtensions، عند وجوده، طول مصفوفة extensions (تُقرن الإدخالات بحسب مواضعها). يتطلب runtimeSetupEntry وجود setupEntry.
• إذا صُرّح عن عنصر runtimeExtensions/runtimeSetupEntry لكنه كان مفقودًا، يفشل التثبيت/الاكتشاف بسبب خطأ في التحزيم؛ ولا يعود OpenClaw ضمنيًا إلى المصدر. ولا ينطبق الرجوع إلى المصدر (أدناه) إلا في حال عدم التصريح عن أي إدخال لوقت التشغيل أصلًا.
• إذا صرّحت حزمة مثبّتة عن إدخال مصدر TypeScript فقط، يبحث OpenClaw عن نظير مبني مطابق من dist/*.js (أو .mjs/.cjs) ويستخدمه؛ وإلا فإنه يعود إلى مصدر TypeScript.
• يجب أن تبقى جميع مسارات الإدخال داخل دليل حزمة Plugin. ولا تجعل إدخالات وقت التشغيل ولا نظراء JavaScript المبنيون والمستنتجون مسار مصدر extensions أو setupEntry الخارج من الحزمة صالحًا.

​

defineToolPlugin

import { Type } from "typebox";
import { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin";

export default defineToolPlugin({
  id: "stock-quotes",
  name: "Stock Quotes",
  description: "Fetch stock quotes.",
  configSchema: Type.Object({
    apiKey: Type.Optional(Type.String({ description: "API key." })),
  }),
  tools: (tool) => [
    tool({
      name: "quote",
      label: "Quote",
      description: "Fetch a quote.",
      parameters: Type.Object({
        symbol: Type.String({ description: "Ticker symbol." }),
      }),
      execute: async ({ symbol }, config) => ({ symbol, hasKey: Boolean(config.apiKey) }),
    }),
  ],
});

• configSchema اختياري؛ ويؤدي حذفه إلى استخدام مخطط كائن فارغ صارم (يظل البيان المُنشأ متضمنًا configSchema).
• يعيد execute سلسلة عادية أو قيمة قابلة للتسلسل إلى JSON؛ وتغلّفها الدالة المساعدة كنتيجة أداة نصية مع تعيين details إلى قيمة الإرجاع الأصلية (غير المحوّلة إلى سلسلة).
• لنتائج الأدوات المخصّصة، يصدّر openclaw/plugin-sdk/tool-results كلاً من textResult وjsonResult.
• أسماء الأدوات ثابتة، لذا يستنتج openclaw plugins build قيمة contracts.tools من الأدوات المعلنة دون تكرار الأسماء يدويًا.
• يظل التحميل في وقت التشغيل صارمًا: لا تزال Plugins المثبّتة بحاجة إلى openclaw.plugin.json وpackage.json openclaw.extensions. ولا ينفّذ OpenClaw أبدًا شيفرة Plugin لاستنتاج بيانات البيان المفقودة.

​

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 الخاص بك.
• تستخدم كتالوجات الجلسات الخارجية openclaw/plugin-sdk/session-catalog و api.registerSessionCatalog({ id, label, list, read, continueSession?, archive? }). يمتلك النواة توابع Gateway ‏sessions.catalog.*؛ ويعيد المزوّدون إسقاطات المضيف والجلسة والنص المنسوخ الموحّد من دون تسجيل استدعاءات RPC.
• kind مهمل: أعلن عن خانة حصرية ("memory" أو "context-engine") في حقل kind من بيان openclaw.plugin.json بدلًا منه. لا يبقى kind في إدخال وقت التشغيل إلا بوصفه رجوعًا للتوافق مع Plugins الأقدم.
• يمكن أن تكون configSchema دالة للتقييم الكسول. يحل OpenClaw المخطط ويخزّنه مؤقتًا عند أول وصول، وبذلك لا تعمل منشئات المخطط المكلفة إلا مرة واحدة.
• يمكن لواصف nodeHostCommands تعريف isAvailable({ config, env }). يؤدي إرجاع false إلى حذف ذلك الأمر وإمكاناته من إعلان Gateway الخاص بـ Node عديمة الواجهة. يقيّمه OpenClaw بالاستناد إلى إعداد بدء التشغيل المحلي لـ Node؛ ومع ذلك ينبغي لمعالجات الأوامر التحقق من التوفر عند استدعائها.

​

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 في كل وضع باستثناء "cli-metadata" و "tool-discovery". خزّن مرجع وقت التشغيل هنا، عادةً عبر createPluginRuntimeStore.
• تعمل registerCliMetadata مع "cli-metadata" و"discovery" و "full". استخدمها باعتبارها الموضع الأساسي للواصفات التي يملكها CLI الخاص بالقناة لكي تظل مساعدة الجذر غير منشّطة، وتتضمن لقطات الاكتشاف البيانات الوصفية الثابتة للأوامر، ويظل تسجيل CLI العادي متوافقًا مع عمليات التحميل الكامل لـ Plugin.
• لا تعمل registerFull إلا مع "full" و"tool-discovery". أما مع "tool-discovery" فتعمل بدلًا من تسجيل القناة: يتجاوز OpenClaw registerChannel/setRuntime بالكامل ولا يستدعي سوى registerFull، لذا يجب أن يوجد هناك أي تسجيل لمزوّد/أداة تحتاج إليه قناتك لاكتشاف الأدوات أو تنفيذها بصورة مستقلة، لا خلف إعداد القناة المعتاد.
• تسجيل الاكتشاف غير منشّط، لكنه ليس خاليًا من الاستيراد: قد يقيّم OpenClaw إدخال Plugin الموثوق ووحدة Plugin القناة لبناء اللقطة. أبقِ الاستيرادات في المستوى الأعلى خالية من الآثار الجانبية، وضع المقابس والعملاء والعمّال والخدمات خلف مسارات "full" فقط.
• كما هو الحال مع definePluginEntry، يمكن أن تكون configSchema مصنعًا كسولًا؛ ويخزّن OpenClaw المخطط المحلول مؤقتًا عند أول وصول.

• استخدم api.registerCli(..., { descriptors: [...] }) لأوامر CLI الجذرية المملوكة لـ Plugin التي تريد تحميلها تحميلًا كسولًا من دون أن تختفي من شجرة التحليل الجذرية لـ CLI. يجب أن تتطابق أسماء الواصفات مع الحروف والأرقام والواصلة والشرطة السفلية، وأن تبدأ بحرف أو رقم؛ يرفض OpenClaw البنى الأخرى ويزيل تسلسلات التحكم الطرفية من الأوصاف قبل عرض المساعدة. غطِّ كل جذر لأوامر المستوى الأعلى يعرضه المسجِّل. يظل commands وحده في مسار التوافق الحريص.
• استخدم api.registerNodeCliFeature(...) لأوامر ميزات Node المقترنة كي تندرج ضمن openclaw nodes (بما يعادل registerCli(registrar, { parentPath: ["nodes"], ... })).
• لأوامر Plugin المتداخلة الأخرى، أضف parentPath وسجّل الأوامر على كائن program الممرّر إلى المسجِّل؛ يحلّه OpenClaw إلى الأمر الأب قبل استدعاء Plugin.
• بالنسبة إلى Plugins القنوات، سجّل واصفات CLI من 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);

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",
  },
  registerSetupRuntime(api) {
    api.registerHttpRoute({
      path: "/my-channel/events",
      auth: "plugin",
      handler: async (req, res) => {
        /* مسار آمن للإعداد */
      },
    });
  },
});

​

وضع التسجيل

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

  if (api.registrationMode === "tool-discovery") {
    // سجّل واجهات الإمكانات فقط (المزوّدين/الأدوات)، من دون قناة.
    return;
  }

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

  // تسجيلات ثقيلة خاصة بوقت التشغيل
  api.registerService(/* ... */);
}

api.registerService({
  id: "index-events",
  start(ctx) {
    ctx.gatewayEvents?.emit("changed", { revision: 1 }, { scope: "operator.read" });
  },
});

​

أشكال Plugins

​

ذو صلة

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