نظرة عامة على SDK الخاص بالـ 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.

​

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

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

​

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

​

واجهة API للتسجيل

​

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

​

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

​

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

​

خطافات المضيف لمكونات سير العمل الإضافية

• 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(...)

• يمكن للـ Plugins الخارجية امتلاك امتدادات الجلسة، وواصفات واجهة المستخدم، والأوامر، وبيانات تعريف الأدوات، وحقن الدور التالي، والخطافات العادية.
• تعمل سياسات الأدوات الموثوقة قبل خطافات before_tool_call العادية، وهي مخصصة للحزم المضمنة فقط لأنها تشارك في سياسة سلامة المضيف.
• ملكية الأوامر المحجوزة مخصصة للحزم المضمنة فقط. ينبغي للـ Plugins الخارجية استخدام أسماء أوامرها أو أسمائها البديلة.
• يعطل 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 الخاص بالخلفية بادئة المزوّد في مراجع النماذج مثل codex-cli/gpt-5.
• يستخدم config الخاص بالخلفية الشكل نفسه مثل agents.defaults.cliBackends.<id>.
• يظل تكوين المستخدم هو الغالب. يدمج OpenClaw agents.defaults.cliBackends.<id> فوق افتراض Plugin قبل تشغيل CLI.
• استخدم normalizeConfig عندما تحتاج خلفية إلى إعادة كتابات توافق بعد الدمج (مثل تسوية أشكال الرايات القديمة).
• استخدم resolveExecutionArgs لإعادة كتابة argv محددة بنطاق الطلب وتنتمي إلى لهجة CLI، مثل ربط مستويات التفكير في OpenClaw براية جهد أصلية.

​

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

​

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

• 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 لـ Plugin الذاكرة النشط تسجيل معرف محول تضمين واحد أو أكثر (مثل openai أو gemini أو معرف مخصص يعرّفه Plugin).
• يحل تكوين المستخدم مثل agents.defaults.memorySearch.provider و agents.defaults.memorySearch.fallback مقابل معرفات المحولات المسجلة هذه.

​

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

​

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

• 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 لمساعدات ترويسة Claude التجريبية وتدفق service_tier.
• @openclaw/openai-provider: يصدّر api.ts بناة المزوّد، ومساعدات النموذج الافتراضي، وبناة مزوّد الوقت الفعلي.
• @openclaw/openrouter-provider: يصدّر api.ts باني المزوّد بالإضافة إلى مساعدات الإعداد الأولي/الإعدادات.

​

ذات صلة