نظرة عامة على Plugin SDK

​

اصطلاح الاستيراد

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

​

مرجع المسارات الفرعية

​

API التسجيل

​

تسجيل القدرات

​

الأدوات والأوامر

agentPromptGuidance: [
  "Global command hint.",
  { text: "Only show this in the main OpenClaw prompt.", surfaces: ["openclaw_main"] },
];

​

البنية التحتية

​

خطافات المضيف لـ Plugins سير العمل

• api.session.state.registerSessionExtension(...)
• api.session.workflow.enqueueNextTurnInjection(...)
• api.session.workflow.registerSessionSchedulerJob(...)
• api.session.workflow.sendSessionAttachment(...)
• api.session.workflow.scheduleSessionTurn(...)
• api.session.workflow.unscheduleSessionTurnsByTag(...)
• api.session.controls.registerSessionAction(...)
• api.session.controls.registerControlUiDescriptor(...)
• api.agent.events.registerAgentEventSubscription(...)
• api.agent.events.emitAgentEvent(...)
• api.runContext.setRunContext(...) / getRunContext(...) / clearRunContext(...)
• api.lifecycle.registerRuntimeLifecycle(...)

• يمكن لإضافات Plugin الخارجية امتلاك امتدادات الجلسات، وواصفات واجهة المستخدم، والأوامر، وبيانات تعريف الأدوات، وحقن الدورة التالية، والخطافات العادية.
• تعمل سياسات الأدوات الموثوقة قبل خطافات before_tool_call العادية وتكون موثوقة من المضيف. تعمل السياسات المضمّنة أولاً؛ وتتطلب سياسات إضافات Plugin المثبتة تمكيناً صريحاً إضافة إلى معرّفاتها المحلية في contracts.trustedToolPolicies، ثم تعمل تالياً بترتيب تحميل Plugin. تكون معرّفات السياسات محددة بنطاق Plugin الذي سجّلها.
• ملكية الأوامر المحجوزة مخصصة للميزات المضمّنة فقط. ينبغي لإضافات Plugin الخارجية استخدام أسماء أوامرها أو أسمائها البديلة الخاصة بها.
• يعطّل allowPromptInjection=false الخطافات التي تغيّر الموجهات، بما في ذلك agent_turn_prepare وbefore_prompt_build وheartbeat_prompt_contribution وحقول الموجهات من before_agent_start القديم و enqueueNextTurnInjection.

​

تسجيل اكتشاف Gateway

api.registerGatewayDiscoveryService({
  id: "my-discovery",
  async advertise(ctx) {
    const handle = await startMyAdvertiser({
      gatewayPort: ctx.gatewayPort,
      tls: ctx.gatewayTlsEnabled,
      displayName: ctx.machineDisplayName,
    });
    return { stop: () => handle.stop() };
  },
});

​

بيانات تعريف تسجيل CLI

• commands: أسماء أوامر صريحة يملكها المسجّل
• descriptors: واصفات أوامر وقت التحليل المستخدمة لمساعدة CLI، والتوجيه، وتسجيل CLI الكسول للـ Plugin
• parentPath: مسار أمر أصل اختياري لمجموعات الأوامر المتداخلة، مثل ["nodes"]

api.registerCli(
  async ({ program }) => {
    const { registerMatrixCli } = await import("./src/cli.js");
    registerMatrixCli({ program });
  },
  {
    descriptors: [
      {
        name: "matrix",
        description: "Manage Matrix accounts, verification, devices, and profile state",
        hasSubcommands: true,
      },
    ],
  },
);

api.registerCli(
  async ({ program }) => {
    const { registerNodesCanvasCommands } = await import("./src/cli.js");
    registerNodesCanvasCommands(program);
  },
  {
    parentPath: ["nodes"],
    descriptors: [
      {
        name: "canvas",
        description: "Capture or render canvas content from a paired node",
        hasSubcommands: true,
      },
    ],
  },
);

​

تسجيل خلفية CLI

• يصبح id الخاص بالخلفية بادئة المزوّد في مراجع النماذج مثل my-cli/gpt-5.
• يستخدم config الخاص بالخلفية البنية نفسها مثل agents.defaults.cliBackends.<id>.
• تظل إعدادات المستخدم هي الغالبة. يدمج OpenClaw agents.defaults.cliBackends.<id> فوق الإعداد الافتراضي الخاص بـ Plugin قبل تشغيل CLI.
• استخدم normalizeConfig عندما تحتاج الخلفية إلى إعادة كتابة للتوافق بعد الدمج (مثل تطبيع بُنى الرايات القديمة).
• استخدم resolveExecutionArgs لإعادة كتابة argv على نطاق الطلب التي تنتمي إلى لهجة CLI، مثل ربط مستويات التفكير في OpenClaw براية جهد أصلية. يتلقى الخطاف ctx.executionMode؛ استخدم "side-question" لإضافة رايات عزل أصلية للخلفية لاستدعاءات /btw المؤقتة. إذا كانت تلك الرايات تعطل الأدوات الأصلية بشكل موثوق في CLI تكون مفعّلة دائمًا بخلاف ذلك، فأعلن sideQuestionToolMode: "disabled" أيضًا.

​

الخانات الحصرية

​

محوّلات تضمين الذاكرة المهملة

• registerMemoryCapability هي واجهة API الحصرية المفضلة لـ Plugin الذاكرة.
• قد تعرض registerMemoryCapability أيضًا publicArtifacts.listArtifacts(...) حتى تتمكن Plugins المصاحبة من استهلاك عناصر الذاكرة المصدّرة عبر openclaw/plugin-sdk/memory-host-core بدلًا من الوصول إلى التخطيط الخاص بـ Plugin ذاكرة محدد.
• registerMemoryPromptSection وregisterMemoryFlushPlan و registerMemoryRuntime هي واجهات API حصرية لـ Plugin الذاكرة ومتوافقة مع الإرث.
• يستطيع MemoryFlushPlan.model تثبيت دورة التفريغ على مرجع provider/model دقيق، مثل ollama/qwen3:8b، من دون وراثة سلسلة الرجوع النشطة.
• registerMemoryEmbeddingProvider مهملة. يجب على مزوّدي التضمين الجدد استخدام api.registerEmbeddingProvider(...) و contracts.embeddingProviders.
• يستمر مزوّدو الذاكرة المحددون الحاليون في العمل خلال نافذة الترحيل، لكن تقارير فحص Plugin تسجل هذا كدين توافق لـ Plugins غير المضمّنة.

​

الأحداث ودورة الحياة

​

دلالات قرار الخطاف

• before_tool_call: إرجاع { block: true } نهائي. بمجرد أن يضبطه أي معالج، تُتخطى المعالجات ذات الأولوية الأدنى.
• before_tool_call: إرجاع { block: false } يُعامل على أنه لا قرار (مثل حذف block)، وليس كتجاوز.
• before_install: إرجاع { block: true } نهائي. بمجرد أن يضبطه أي معالج، تُتخطى المعالجات ذات الأولوية الأدنى.
• before_install: إرجاع { block: false } يُعامل على أنه لا قرار (مثل حذف block)، وليس كتجاوز.
• reply_dispatch: إرجاع { handled: true, ... } نهائي. بمجرد أن يطالب أي معالج بالإرسال، تُتخطى المعالجات ذات الأولوية الأدنى ومسار إرسال النموذج الافتراضي.
• message_sending: إرجاع { cancel: true } نهائي. بمجرد أن يضبطه أي معالج، تُتخطى المعالجات ذات الأولوية الأدنى.
• message_sending: إرجاع { cancel: false } يُعامل على أنه لا قرار (مثل حذف cancel)، وليس كتجاوز.
• message_received: استخدم حقل threadId النمطي عندما تحتاج إلى توجيه الخيط/الموضوع الوارد. أبقِ metadata للإضافات الخاصة بالقناة.
• message_sending: استخدم حقول التوجيه النمطية replyToId / threadId قبل الرجوع إلى metadata الخاصة بالقناة.
• gateway_start: استخدم ctx.config وctx.workspaceDir وctx.getCron?.() لحالة بدء التشغيل المملوكة لـ Gateway بدلًا من الاعتماد على خطافات gateway:startup الداخلية.
• cron_changed: راقب تغييرات دورة حياة Cron المملوكة لـ Gateway. استخدم event.job?.state?.nextRunAtMs وctx.getCron?.() عند مزامنة مجدولات الإيقاظ الخارجية، وأبقِ OpenClaw مصدر الحقيقة لفحوصات الاستحقاق والتنفيذ.

​

حقول كائن API

​

اصطلاح الوحدات الداخلية

my-plugin/
  api.ts            # Public exports for external consumers
  runtime-api.ts    # Internal-only runtime exports
  index.ts          # Plugin entry point
  setup-entry.ts    # Lightweight setup-only entry (optional)

• Anthropic: سطح api.ts / contract-api.ts العام لمساعدات البث الخاصة بـ beta-header لـ Claude وservice_tier.
• @openclaw/openai-provider: يصدّر api.ts بُناة المزوّدين، ومساعدات النموذج الافتراضي، وبُناة مزوّدي الوقت الفعلي.
• @openclaw/openrouter-provider: يصدّر api.ts باني المزوّد بالإضافة إلى مساعدات التهيئة/الإعداد.

​

ذات صلة