نقاط دخول Plugin

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

​

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 اختياري. عند حذفه، يستخدم OpenClaw مخطط كائن فارغًا صارمًا ويظل البيان المولّد يتضمن configSchema.
• تعيد execute سلسلة نصية عادية أو قيمة قابلة للتسلسل إلى JSON. يلفّها المساعد كنتيجة أداة نصية مع details.
• أسماء الأدوات ثابتة. يشتق 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 لديك.
• 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. بالنسبة إلى أوامر Plugins المتداخلة الأخرى، أضف parentPath وسجّل الأوامر على كائن program الممرّر إلى المسجّل؛ يحلّه OpenClaw إلى الأمر الأب قبل استدعاء Plugin. بالنسبة إلى 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 لمساعدي الإعداد الآمنين لوقت التشغيل مثل createSetupTranslator، ومحوّلات تصحيح الإعداد الآمنة للاستيراد، ومخرجات ملاحظات البحث، و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",
  },
  registerSetupRuntime(api) {
    api.registerHttpRoute({
      path: "/my-channel/events",
      auth: "plugin",
      handler: async (req, res) => {
        /* setup-safe route */
      },
    });
  },
});

​

وضع التسجيل

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 المزوّدين - تسجيل المزوّد والخطافات