الانتقال إلى المحتوى الرئيسي

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

تُعد Plugin SDK العقد المطبوع بين plugins والنواة. وهذه الصفحة هي المرجع الخاص بـ ما الذي يجب استيراده وما الذي يمكنك تسجيله.
هل تبحث عن دليل إرشادي؟

​
أسلوب الاستيراد

استورد دائمًا من مسار فرعي محدد: 
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
كل مسار فرعي هو وحدة صغيرة مستقلة بذاتها. وهذا يحافظ على سرعة بدء التشغيل ويمنع مشكلات الاعتماد الدائري. وبالنسبة إلى مساعدات entry/build الخاصة بالقنوات، ففضّل openclaw/plugin-sdk/channel-core؛ واحتفظ بـ openclaw/plugin-sdk/core من أجل السطح الأوسع والمساعدات المشتركة مثل buildChannelConfigSchema. لا تضف أو تعتمد على مسارات ملائمة مسماة باسم المزوّد مثل openclaw/plugin-sdk/slack أو openclaw/plugin-sdk/discord أو openclaw/plugin-sdk/signal أو openclaw/plugin-sdk/whatsapp أو مسارات مساعدة تحمل علامة القناة التجارية. يجب أن تقوم Plugins المضمّنة بتركيب المسارات الفرعية العامة لـ SDK داخل ملفات api.ts أو runtime-api.ts الخاصة بها، ويجب على النواة إما استخدام هذه الملفات المحلية الخاصة بـ plugin أو إضافة عقد SDK عام ضيق عندما تكون الحاجة عابرة للقنوات فعلًا. ما تزال خريطة التصدير المُولدة تحتوي على مجموعة صغيرة من مسارات المساعدة الخاصة بـ plugins المضمّنة مثل plugin-sdk/feishu وplugin-sdk/feishu-setup وplugin-sdk/zalo وplugin-sdk/zalo-setup وplugin-sdk/matrix*. هذه المسارات الفرعية موجودة لصيانة plugins المضمّنة والتوافق فقط؛ وتم حذفها عمدًا من الجدول الشائع أدناه وليست مسار الاستيراد الموصى به لـ plugins الخارجية الجديدة.

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

أكثر المسارات الفرعية استخدامًا، مجمعة حسب الغرض. توجد القائمة الكاملة المولدة التي تضم أكثر من 200 مسار فرعي في scripts/lib/plugin-sdk-entrypoints.json. ما تزال المسارات الفرعية المحجوزة لمساعدات plugins المضمّنة تظهر في تلك القائمة المولدة. تعامل معها على أنها تفاصيل تنفيذ/أسطح توافق ما لم تروّج صفحة توثيق لها صراحةً على أنها عامة.

​
إدخال plugin

المسار الفرعيأهم التصديرات
plugin-sdk/plugin-entrydefinePluginEntry
plugin-sdk/coredefineChannelPluginEntry وcreateChatChannelPlugin وcreateChannelPluginBase وdefineSetupPluginEntry وbuildChannelConfigSchema
plugin-sdk/config-schemaOpenClawSchema
plugin-sdk/provider-entrydefineSingleProviderPluginEntry
المسار الفرعيأهم التصديرات
plugin-sdk/channel-coredefineChannelPluginEntry وdefineSetupPluginEntry وcreateChatChannelPlugin وcreateChannelPluginBase
plugin-sdk/config-schemaتصدير مخطط Zod الجذري لـ openclaw.json ‏(OpenClawSchema)
plugin-sdk/channel-setupcreateOptionalChannelSetupSurface وcreateOptionalChannelSetupAdapter وcreateOptionalChannelSetupWizard، بالإضافة إلى DEFAULT_ACCOUNT_ID وcreateTopLevelChannelDmPolicy وsetSetupChannelEnabled وsplitSetupEntries
plugin-sdk/setupمساعدات مشتركة لمعالج الإعداد، ومطالبات allowlist، وبناة حالة الإعداد
plugin-sdk/setup-runtimecreatePatchedAccountSetupAdapter وcreateEnvPatchedAccountSetupAdapter وcreateSetupInputPresenceValidator وnoteChannelLookupFailure وnoteChannelLookupSummary وpromptResolvedAllowFrom وsplitSetupEntries وcreateAllowlistSetupWizardProxy وcreateDelegatedSetupWizardProxy
plugin-sdk/setup-adapter-runtimecreateEnvPatchedAccountSetupAdapter
plugin-sdk/setup-toolsformatCliCommand وdetectBinary وextractArchive وresolveBrewExecutable وformatDocsLink وCONFIG_DIR
plugin-sdk/account-coreمساعدات تكوين/بوابات إجراءات متعددة الحسابات ومساعدات الرجوع إلى الحساب الافتراضي
plugin-sdk/account-idDEFAULT_ACCOUNT_ID ومساعدات تطبيع معرّف الحساب
plugin-sdk/account-resolutionمساعدات البحث عن الحساب + الرجوع إلى الافتراضي
plugin-sdk/account-helpersمساعدات ضيقة لقائمة الحسابات/إجراءات الحساب
plugin-sdk/channel-pairingcreateChannelPairingController
plugin-sdk/channel-reply-pipelinecreateChannelReplyPipeline
plugin-sdk/channel-config-helperscreateHybridChannelConfigAdapter
plugin-sdk/channel-config-schemaأنواع مخطط تكوين القناة
plugin-sdk/telegram-command-configمساعدات تطبيع/تحقق لأوامر Telegram المخصصة مع بديل العقد المضمّن
plugin-sdk/channel-policyresolveChannelGroupRequireMention
plugin-sdk/channel-lifecyclecreateAccountStatusSink
plugin-sdk/inbound-envelopeمساعدات مشتركة للمسار الوارد وبناء الغلاف
plugin-sdk/inbound-reply-dispatchمساعدات مشتركة لتسجيل الوارد وإرساله
plugin-sdk/messaging-targetsمساعدات تحليل/مطابقة الأهداف
plugin-sdk/outbound-mediaمساعدات مشتركة لتحميل الوسائط الصادرة
plugin-sdk/outbound-runtimeمساعدات هوية/تفويض الإرسال الصادر
plugin-sdk/thread-bindings-runtimeمساعدات دورة حياة ارتباطات السلاسل والمهايئ
plugin-sdk/agent-media-payloadباني حمولة وسائط الوكيل القديم
plugin-sdk/conversation-runtimeمساعدات المحادثة/ربط السلاسل/الاقتران/الارتباطات المكوّنة
plugin-sdk/runtime-config-snapshotمساعد لقطة تكوين وقت التشغيل
plugin-sdk/runtime-group-policyمساعدات حل سياسة المجموعة في وقت التشغيل
plugin-sdk/channel-statusمساعدات مشتركة للّقطة/الملخص الخاص بحالة القناة
plugin-sdk/channel-config-primitivesأوليات ضيقة لمخطط تكوين القناة
plugin-sdk/channel-config-writesمساعدات تفويض كتابة تكوين القناة
plugin-sdk/channel-plugin-commonتصديرات تمهيدية مشتركة لـ plugin القناة
plugin-sdk/allowlist-config-editمساعدات قراءة/تحرير تكوين allowlist
plugin-sdk/group-accessمساعدات مشتركة لقرارات الوصول إلى المجموعات
plugin-sdk/direct-dmمساعدات مشتركة لمصادقة/حراسة الرسائل الخاصة المباشرة
plugin-sdk/interactive-runtimeمساعدات تطبيع/تقليص حمولات الردود التفاعلية
plugin-sdk/channel-inboundإزالة الارتجاج، ومطابقة الإشارات، ومساعدات الغلاف
plugin-sdk/channel-send-resultأنواع نتائج الرد
plugin-sdk/channel-actionscreateMessageToolButtonsSchema وcreateMessageToolCardSchema
plugin-sdk/channel-targetsمساعدات تحليل/مطابقة الأهداف
plugin-sdk/channel-contractأنواع عقد القناة
plugin-sdk/channel-feedbackتوصيل الملاحظات/التفاعلات
المسار الفرعيأهم التصديرات
plugin-sdk/provider-entrydefineSingleProviderPluginEntry
plugin-sdk/provider-setupمساعدات إعداد منسقة لمزوّدات محلية/مستضافة ذاتيًا
plugin-sdk/self-hosted-provider-setupمساعدات إعداد مركزة لمزوّدات متوافقة ذاتيًا مع OpenAI
plugin-sdk/cli-backendالقيم الافتراضية لـ CLI backend + ثوابت watchdog
plugin-sdk/provider-auth-runtimeمساعدات حل مفتاح API في وقت التشغيل لـ plugins المزوّد
plugin-sdk/provider-auth-api-keyمساعدات onboarding/الكتابة لملف التعريف لمفتاح API
plugin-sdk/provider-auth-resultباني قياسي لنتيجة مصادقة OAuth
plugin-sdk/provider-auth-loginمساعدات تسجيل الدخول التفاعلية المشتركة لـ plugins المزوّد
plugin-sdk/provider-env-varsمساعدات البحث عن متغيرات البيئة الخاصة بمصادقة المزوّد
plugin-sdk/provider-authcreateProviderApiKeyAuthMethod وensureApiKeyFromOptionEnvOrPrompt وupsertAuthProfile
plugin-sdk/provider-model-sharedProviderReplayFamily وbuildProviderReplayFamilyHooks وnormalizeModelCompat وبناة سياسات replay المشتركة، ومساعدات نقاط نهاية المزوّد، ومساعدات تطبيع معرّف النموذج مثل normalizeNativeXaiModelId
plugin-sdk/provider-catalog-sharedfindCatalogTemplate وbuildSingleProviderApiKeyCatalog وsupportsNativeStreamingUsageCompat وapplyProviderNativeStreamingUsageCompat
plugin-sdk/provider-httpمساعدات عامة لإمكانات HTTP/نقاط نهاية المزوّد
plugin-sdk/provider-web-fetchمساعدات تسجيل/تخزين مؤقت لمزوّد web-fetch
plugin-sdk/provider-web-searchمساعدات تسجيل/تخزين مؤقت/تكوين لمزوّد web-search
plugin-sdk/provider-toolsProviderToolCompatFamily وbuildProviderToolCompatFamilyHooks وتنظيف مخطط Gemini + التشخيصات، ومساعدات توافق xAI مثل resolveXaiModelCompatPatch / applyXaiModelCompat
plugin-sdk/provider-usagefetchClaudeUsage وما شابه
plugin-sdk/provider-streamProviderStreamFamily وbuildProviderStreamFamilyHooks وcomposeProviderStreamWrappers وأنواع مغلفات stream، ومساعدات مغلفات Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot المشتركة
plugin-sdk/provider-onboardمساعدات ترقيع تكوين onboarding
plugin-sdk/global-singletonمساعدات singleton/map/cache محلية للعملية
المسار الفرعيأهم التصديرات
plugin-sdk/command-authresolveControlCommandGate، ومساعدات سجل الأوامر، ومساعدات تفويض المرسل
plugin-sdk/approval-auth-runtimeحل الموافق ومساعدات مصادقة الإجراءات داخل الدردشة نفسها
plugin-sdk/approval-client-runtimeمساعدات profile/filter الخاصة بموافقات exec الأصلية
plugin-sdk/approval-delivery-runtimeمهايئات القدرة/التسليم للموافقات الأصلية
plugin-sdk/approval-native-runtimeمساعدات الهدف الأصلي للموافقة + ربط الحساب
plugin-sdk/approval-reply-runtimeمساعدات حمولة الرد الخاصة بموافقات exec/plugin
plugin-sdk/command-auth-nativeمصادقة الأوامر الأصلية + مساعدات الأهداف الأصلية للجلسات
plugin-sdk/command-detectionمساعدات مشتركة لاكتشاف الأوامر
plugin-sdk/command-surfaceتطبيع نص الأمر ومساعدات سطح الأوامر
plugin-sdk/allow-fromformatAllowFromLowercase
plugin-sdk/security-runtimeمساعدات مشتركة للثقة، وتقييد DM، والمحتوى الخارجي، وجمع الأسرار
plugin-sdk/ssrf-policyمساعدات سياسة SSRF لقائمة سماح المضيف والشبكة الخاصة
plugin-sdk/ssrf-runtimeمساعدات pinned-dispatcher وfetch المحمية بـ SSRF وسياسة SSRF
plugin-sdk/secret-inputمساعدات تحليل مدخلات الأسرار
plugin-sdk/webhook-ingressمساعدات طلبات/أهداف webhook
plugin-sdk/webhook-request-guardsمساعدات حجم جسم الطلب/المهلة
المسار الفرعيأهم التصديرات
plugin-sdk/runtimeمساعدات واسعة لوقت التشغيل/التسجيل/النسخ الاحتياطي/تثبيت plugin
plugin-sdk/runtime-envمساعدات ضيقة لبيئة وقت التشغيل، وlogger، والمهلة، وإعادة المحاولة، والتراجع
plugin-sdk/runtime-storecreatePluginRuntimeStore
plugin-sdk/plugin-runtimeمساعدات مشتركة لأوامر/خطافات/http/تفاعلات plugin
plugin-sdk/hook-runtimeمساعدات مشتركة لخط أنابيب webhooks/الخطافات الداخلية
plugin-sdk/lazy-runtimeمساعدات الاستيراد/الربط الكسول لوقت التشغيل مثل createLazyRuntimeModule وcreateLazyRuntimeMethod وcreateLazyRuntimeSurface
plugin-sdk/process-runtimeمساعدات تنفيذ العمليات
plugin-sdk/cli-runtimeمساعدات تنسيق CLI والانتظار والإصدار
plugin-sdk/gateway-runtimeمساعدات عميل Gateway وترقيع حالة القناة
plugin-sdk/config-runtimeمساعدات تحميل/كتابة التكوين
plugin-sdk/telegram-command-configتطبيع اسم/وصف أوامر Telegram والتحقق من التكرار/التعارض، حتى عندما لا يكون سطح عقد Telegram المضمّن متاحًا
plugin-sdk/approval-runtimeمساعدات موافقة exec/plugin، وبناة قدرات الموافقة، ومساعدات auth/profile، ومساعدات التوجيه/وقت التشغيل الأصلية
plugin-sdk/reply-runtimeمساعدات مشتركة لوقت التشغيل الخاص بالوارد/الرد، والتجزئة، والإرسال، وheartbeat، ومخطط الرد
plugin-sdk/reply-dispatch-runtimeمساعدات ضيقة لإرسال/إنهاء الرد
plugin-sdk/reply-historyمساعدات مشتركة لنافذة سجل الرد القصيرة مثل buildHistoryContext وrecordPendingHistoryEntry وclearHistoryEntriesIfEnabled
plugin-sdk/reply-referencecreateReplyReferencePlanner
plugin-sdk/reply-chunkingمساعدات ضيقة لتجزئة النص/Markdown
plugin-sdk/session-store-runtimeمساعدات مسار مخزن الجلسة + updated-at
plugin-sdk/state-pathsمساعدات مسارات دليل الحالة/OAuth
plugin-sdk/routingمساعدات المسار/مفتاح الجلسة/ربط الحساب مثل resolveAgentRoute وbuildAgentSessionKey وresolveDefaultAgentBoundAccountId
plugin-sdk/status-helpersمساعدات مشتركة لملخص حالة القناة/الحساب، وافتراضيات حالة وقت التشغيل، ومساعدات بيانات تعريف المشكلات
plugin-sdk/target-resolver-runtimeمساعدات مشتركة لحل الأهداف
plugin-sdk/string-normalization-runtimeمساعدات تطبيع slug/string
plugin-sdk/request-urlاستخراج عناوين URL النصية من مدخلات شبيهة بـ fetch/request
plugin-sdk/run-commandمشغّل أوامر مؤقت بنتائج stdout/stderr مُطبَّعة
plugin-sdk/param-readersقارئات معلمات شائعة للأدوات/CLI
plugin-sdk/tool-sendاستخراج حقول هدف الإرسال المعتمدة من وسائط الأداة
plugin-sdk/temp-pathمساعدات مشتركة لمسارات التنزيل المؤقتة
plugin-sdk/logging-corelogger للنظام الفرعي ومساعدات التنقيح
plugin-sdk/markdown-table-runtimeمساعدات أوضاع جداول Markdown
plugin-sdk/json-storeمساعدات صغيرة لقراءة/كتابة حالة JSON
plugin-sdk/file-lockمساعدات file-lock معاد الدخول
plugin-sdk/persistent-dedupeمساعدات ذاكرة تخزين مؤقت dedupe مدعومة بالقرص
plugin-sdk/acp-runtimeمساعدات وقت تشغيل/جلسات ACP
plugin-sdk/agent-config-primitivesأوليات ضيقة لمخطط تكوين وقت تشغيل الوكيل
plugin-sdk/boolean-paramقارئ معلمات منطقي مرن
plugin-sdk/dangerous-name-runtimeمساعدات حل مطابقة الأسماء الخطرة
plugin-sdk/device-bootstrapمساعدات bootstrap الجهاز ورمز الاقتران
plugin-sdk/extension-sharedأوليات مشتركة للقناة السلبية ومساعدات الحالة
plugin-sdk/models-provider-runtimeمساعدات الرد لأوامر /models/المزوّد
plugin-sdk/skill-commands-runtimeمساعدات سرد أوامر Skills
plugin-sdk/native-command-registryمساعدات سجل/بناء/تسلسل الأوامر الأصلية
plugin-sdk/provider-zai-endpointمساعدات اكتشاف نقطة نهاية Z.AI
plugin-sdk/infra-runtimeمساعدات system event/heartbeat
plugin-sdk/collection-runtimeمساعدات صغيرة لذاكرة تخزين مؤقت محدودة
plugin-sdk/diagnostic-runtimeمساعدات أعلام وأحداث التشخيص
plugin-sdk/error-runtimeرسم الأخطاء، والتنسيق، ومساعدات تصنيف الأخطاء المشتركة، وisApprovalNotFoundError
plugin-sdk/fetch-runtimeمساعدات fetch المغلفة، وproxy، والبحث المثبت
plugin-sdk/host-runtimeمساعدات تطبيع اسم المضيف وSCP host
plugin-sdk/retry-runtimeمساعدات تكوين وتشغيل إعادة المحاولة
plugin-sdk/agent-runtimeمساعدات agent dir/الهوية/مساحة العمل
plugin-sdk/directory-runtimeاستعلام/إزالة التكرار للدليل المعتمد على التكوين
plugin-sdk/keyed-async-queueKeyedAsyncQueue
المسار الفرعيأهم التصديرات
plugin-sdk/media-runtimeمساعدات مشتركة لجلب/تحويل/تخزين الوسائط بالإضافة إلى بُناة حمولات الوسائط
plugin-sdk/media-understandingأنواع مزوّد فهم الوسائط بالإضافة إلى تصديرات مساعدات الصور/الصوت الموجهة للمزوّد
plugin-sdk/text-runtimeمساعدات مشتركة للنص/Markdown/التسجيل مثل إزالة النص المرئي للمساعد، ومساعدات render/chunking/table في Markdown، ومساعدات التنقيح، ومساعدات directive-tag، وأدوات النص الآمن
plugin-sdk/text-chunkingمساعد تجزئة النص الصادر
plugin-sdk/speechأنواع مزوّد speech بالإضافة إلى تصديرات المساعدات الموجهة للمزوّد الخاصة بالـ directive والسجل والتحقق
plugin-sdk/speech-coreأنواع مزوّد speech المشتركة، والسجل، والـ directive، ومساعدات التطبيع
plugin-sdk/realtime-transcriptionأنواع مزوّد transcription الفورية ومساعدات السجل
plugin-sdk/realtime-voiceأنواع مزوّد الصوت الفوري ومساعدات السجل
plugin-sdk/image-generationأنواع مزوّد توليد الصور
plugin-sdk/image-generation-coreأنواع توليد الصور المشتركة، وfailover، والمصادقة، ومساعدات السجل
plugin-sdk/video-generationأنواع مزوّد/طلب/نتيجة توليد الفيديو
plugin-sdk/video-generation-coreأنواع توليد الفيديو المشتركة، ومساعدات failover، والبحث عن المزوّد، وتحليل model-ref
plugin-sdk/webhook-targetsسجل أهداف webhook ومساعدات تثبيت المسارات
plugin-sdk/webhook-pathمساعدات تطبيع مسار webhook
plugin-sdk/web-mediaمساعدات مشتركة لتحميل الوسائط البعيدة/المحلية
plugin-sdk/zodإعادة تصدير zod لمستهلكي Plugin SDK
plugin-sdk/testinginstallCommonResolveTargetErrorCases وshouldAckReaction
المسار الفرعيأهم التصديرات
plugin-sdk/memory-coreسطح مساعد memory-core المضمّن من أجل مساعدات المدير/التكوين/الملف/CLI
plugin-sdk/memory-core-engine-runtimeواجهة وقت التشغيل لفهرسة/بحث الذاكرة
plugin-sdk/memory-core-host-engine-foundationتصديرات محرك الأساس لمضيف الذاكرة
plugin-sdk/memory-core-host-engine-embeddingsتصديرات محرك embeddings لمضيف الذاكرة
plugin-sdk/memory-core-host-engine-qmdتصديرات محرك QMD لمضيف الذاكرة
plugin-sdk/memory-core-host-engine-storageتصديرات محرك التخزين لمضيف الذاكرة
plugin-sdk/memory-core-host-multimodalمساعدات متعددة الوسائط لمضيف الذاكرة
plugin-sdk/memory-core-host-queryمساعدات الاستعلام لمضيف الذاكرة
plugin-sdk/memory-core-host-secretمساعدات الأسرار لمضيف الذاكرة
plugin-sdk/memory-core-host-statusمساعدات الحالة لمضيف الذاكرة
plugin-sdk/memory-core-host-runtime-cliمساعدات وقت تشغيل CLI لمضيف الذاكرة
plugin-sdk/memory-core-host-runtime-coreمساعدات وقت التشغيل الأساسية لمضيف الذاكرة
plugin-sdk/memory-core-host-runtime-filesمساعدات الملفات/وقت التشغيل لمضيف الذاكرة
plugin-sdk/memory-lancedbسطح مساعد memory-lancedb المضمّن
العائلةالمسارات الفرعية الحاليةالاستخدام المقصود
Browserplugin-sdk/browser-config-support وplugin-sdk/browser-supportمساعدات دعم plugin ‏browser المضمّنة
Matrixplugin-sdk/matrix وplugin-sdk/matrix-helper وplugin-sdk/matrix-runtime-heavy وplugin-sdk/matrix-runtime-shared وplugin-sdk/matrix-runtime-surface وplugin-sdk/matrix-surface وplugin-sdk/matrix-thread-bindingsسطح المساعدة/وقت التشغيل المضمّن لـ Matrix
Lineplugin-sdk/line وplugin-sdk/line-core وplugin-sdk/line-runtime وplugin-sdk/line-surfaceسطح المساعدة/وقت التشغيل المضمّن لـ LINE
IRCplugin-sdk/irc وplugin-sdk/irc-surfaceسطح المساعدة المضمّن لـ IRC
مساعدات خاصة بالقنواتplugin-sdk/googlechat وplugin-sdk/zalouser وplugin-sdk/bluebubbles وplugin-sdk/bluebubbles-policy وplugin-sdk/mattermost وplugin-sdk/mattermost-policy وplugin-sdk/feishu-conversation وplugin-sdk/msteams وplugin-sdk/nextcloud-talk وplugin-sdk/nostr وplugin-sdk/tlon وplugin-sdk/twitchأسطح توافق/مساعدة مضمّنة للقنوات
مساعدات خاصة بالمصادقة/pluginplugin-sdk/github-copilot-login وplugin-sdk/github-copilot-token وplugin-sdk/diagnostics-otel وplugin-sdk/diffs وplugin-sdk/llm-task وplugin-sdk/thread-ownership وplugin-sdk/voice-callأسطح مساعدة مضمّنة للميزات/plugins؛ ويصدّر plugin-sdk/github-copilot-token حاليًا DEFAULT_COPILOT_API_BASE_URL وderiveCopilotApiBaseUrlFromToken وresolveCopilotApiToken

​
API التسجيل

يتلقى رد النداء register(api) كائن OpenClawPluginApi بهذه الطرق:

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

الطريقةما الذي تسجله
api.registerProvider(...)الاستدلال النصي (LLM)
api.registerCliBackend(...)واجهة CLI خلفية للاستدلال المحلي
api.registerChannel(...)قناة مراسلة
api.registerSpeechProvider(...)تحويل النص إلى كلام / تركيب STT
api.registerRealtimeTranscriptionProvider(...)transcription فورية متدفقة
api.registerRealtimeVoiceProvider(...)جلسات صوت فورية ثنائية الاتجاه
api.registerMediaUnderstandingProvider(...)تحليل الصور/الصوت/الفيديو
api.registerImageGenerationProvider(...)توليد الصور
api.registerVideoGenerationProvider(...)توليد الفيديو
api.registerWebFetchProvider(...)مزوّد web fetch / scrape
api.registerWebSearchProvider(...)web search

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

الطريقةما الذي تسجله
api.registerTool(tool, opts?)أداة وكيل (مطلوبة أو { optional: true })
api.registerCommand(def)أمر مخصص (يتجاوز LLM)

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

الطريقةما الذي تسجله
api.registerHook(events, handler, opts?)خطاف حدث
api.registerHttpRoute(params)نقطة نهاية HTTP لـ Gateway
api.registerGatewayMethod(name, handler)طريقة Gateway RPC
api.registerCli(registrar, opts?)أمر فرعي CLI
api.registerService(service)خدمة خلفية
api.registerInteractiveHandler(registration)معالج تفاعلي
تظل مساحات أسماء الإدارة الأساسية المحجوزة (config.* وexec.approvals.* وwizard.* وupdate.*) دائمًا ضمن operator.admin، حتى لو حاولت plugin تعيين نطاق أضيق لطريقة gateway. فضّل البوادئ الخاصة بـ plugin للطرق المملوكة لـ plugin.

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

يقبل api.registerCli(registrar, opts?) نوعين من بيانات التعريف العليا:
  • commands: جذور أوامر صريحة يملكها الـ registrar
  • descriptors: واصفات أوامر وقت التحليل المستخدمة لمساعدة CLI الجذرية، والتوجيه، والتسجيل الكسول لـ CLI الخاصة بـ plugin
إذا كنت تريد أن يبقى أمر plugin محمّلًا بكسل في مسار CLI الجذري العادي، فوفّر descriptors تغطي كل جذر أمر من المستوى الأعلى يعرضه ذلك الـ registrar. 
api.registerCli(
  async ({ program }) => {
    const { registerMatrixCli } = await import("./src/cli.js");
    registerMatrixCli({ program });
  },
  {
    descriptors: [
      {
        name: "matrix",
        description: "إدارة حسابات Matrix، والتحقق، والأجهزة، وحالة الملف الشخصي",
        hasSubcommands: true,
      },
    ],
  },
);
استخدم commands بمفردها فقط عندما لا تحتاج إلى تسجيل CLI جذري كسول. يظل مسار التوافق eager هذا مدعومًا، لكنه لا يثبت عناصر نائبة مدعومة بـ descriptor من أجل التحميل الكسول وقت التحليل.

​
تسجيل CLI backend

تسمح api.registerCliBackend(...) لأي plugin بامتلاك التكوين الافتراضي لـ CLI backend محلية للذكاء الاصطناعي مثل claude-cli أو codex-cli.
  • يصبح id الخاص بالواجهة الخلفية بادئة المزوّد في model refs مثل claude-cli/opus.
  • يستخدم config للواجهة الخلفية الشكل نفسه الموجود في agents.defaults.cliBackends.<id>.
  • يظل تكوين المستخدم هو الفائز. يدمج OpenClaw قيمة agents.defaults.cliBackends.<id> فوق القيمة الافتراضية لـ plugin قبل تشغيل CLI.
  • استخدم normalizeConfig عندما تحتاج الواجهة الخلفية إلى إعادة كتابة توافقية بعد الدمج (مثل تطبيع أشكال العلامات القديمة).

​
الـ slots الحصرية

الطريقةما الذي تسجله
api.registerContextEngine(id, factory)محرك سياق (واحد نشط في كل مرة)
api.registerMemoryPromptSection(builder)باني قسم مطالبة الذاكرة
api.registerMemoryFlushPlan(resolver)محلل خطة تفريغ الذاكرة
api.registerMemoryRuntime(runtime)مهايئ وقت تشغيل الذاكرة

​
مهايئات embeddings الخاصة بالذاكرة

الطريقةما الذي تسجله
api.registerMemoryEmbeddingProvider(adapter)مهايئ embedding للذاكرة لـ plugin النشطة
  • تُعد registerMemoryPromptSection وregisterMemoryFlushPlan و registerMemoryRuntime حصرية لـ plugins الذاكرة.
  • تسمح registerMemoryEmbeddingProvider لـ plugin الذاكرة النشطة بتسجيل معرّف embedding واحد أو أكثر (مثل openai أو gemini أو معرّف مخصص تعرفه plugin).
  • يُحل تكوين المستخدم مثل agents.defaults.memorySearch.provider و agents.defaults.memorySearch.fallback مقابل معرّفات المهايئات المسجلة تلك.

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

الطريقةما الذي تفعله
api.on(hookName, handler, opts?)خطاف دورة حياة مطبوع
api.onConversationBindingResolved(handler)callback لحل ارتباط المحادثة

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

  • before_tool_call: إعادة { block: true } تكون نهائية. فبمجرد أن يضبط أي معالج هذه القيمة، يتم تجاوز المعالجات ذات الأولوية الأدنى.
  • before_tool_call: تُعامل إعادة { block: false } على أنها عدم اتخاذ قرار (مثل حذف block)، وليست تجاوزًا.
  • before_install: إعادة { block: true } تكون نهائية. فبمجرد أن يضبط أي معالج هذه القيمة، يتم تجاوز المعالجات ذات الأولوية الأدنى.
  • before_install: تُعامل إعادة { block: false } على أنها عدم اتخاذ قرار (مثل حذف block)، وليست تجاوزًا.
  • message_sending: إعادة { cancel: true } تكون نهائية. فبمجرد أن يضبط أي معالج هذه القيمة، يتم تجاوز المعالجات ذات الأولوية الأدنى.
  • message_sending: تُعامل إعادة { cancel: false } على أنها عدم اتخاذ قرار (مثل حذف cancel)، وليست تجاوزًا.

​
حقول كائن API

الحقلالنوعالوصف
api.idstringمعرّف plugin
api.namestringاسم العرض
api.versionstring?إصدار plugin ‏(اختياري)
api.descriptionstring?وصف plugin ‏(اختياري)
api.sourcestringمسار مصدر plugin
api.rootDirstring?الدليل الجذري لـ plugin ‏(اختياري)
api.configOpenClawConfigلقطة التكوين الحالية (لقطة وقت التشغيل النشطة داخل الذاكرة عندما تكون متاحة)
api.pluginConfigRecord<string, unknown>تكوين plugin الخاص من plugins.entries.<id>.config
api.runtimePluginRuntimeمساعدات وقت التشغيل
api.loggerPluginLoggerlogger ذو نطاق (debug وinfo وwarn وerror)
api.registrationModePluginRegistrationModeوضع التحميل الحالي؛ وتُعد "setup-runtime" نافذة بدء تشغيل/إعداد خفيفة قبل الإدخال الكامل
api.resolvePath(input)(string) => stringحل المسار نسبةً إلى جذر plugin

​
أسلوب الوحدات الداخلية

داخل plugin الخاصة بك، استخدم ملفات barrel محلية للاستيرادات الداخلية: 
my-plugin/
  api.ts            # تصديرات عامة للمستهلكين الخارجيين
  runtime-api.ts    # تصديرات وقت تشغيل داخلية فقط
  index.ts          # نقطة دخول plugin
  setup-entry.ts    # إدخال خفيف خاص بالإعداد فقط (اختياري)
لا تستورد plugin الخاصة بك عبر openclaw/plugin-sdk/<your-plugin> من شيفرة الإنتاج مطلقًا. وجّه الاستيرادات الداخلية عبر ./api.ts أو ./runtime-api.ts. إن مسار SDK هو العقد الخارجي فقط.
تفضّل الأسطح العامة لـ plugins المضمّنة المحمّلة عبر الواجهة (api.ts وruntime-api.ts و index.ts وsetup-entry.ts وملفات الإدخال العامة المشابهة) الآن استخدام لقطة تكوين وقت التشغيل النشطة عندما يكون OpenClaw يعمل بالفعل. وإذا لم توجد لقطة وقت تشغيل بعد، فإنها تعود إلى ملف التكوين المحلول على القرص. يمكن لـ Plugins المزوّد أيضًا عرض barrel ضيق للعقد المحلي داخل plugin عندما تكون مساعدة ما خاصة بالمزوّد عمدًا ولا تنتمي بعد إلى مسار فرعي عام في SDK. المثال المضمّن الحالي: يحتفظ مزود Anthropic بمساعدات Claude stream الخاصة به في المسار العام المحلي api.ts / contract-api.ts بدلًا من ترقية منطق رؤوس Anthropic التجريبية وservice_tier إلى عقد عام من نوع plugin-sdk/*. أمثلة مضمّنة أخرى حالية:
  • @openclaw/openai-provider: يصدر api.ts بُناة المزوّد، ومساعدات النماذج الافتراضية، وبُناة مزوّدات realtime
  • @openclaw/openrouter-provider: يصدر api.ts باني المزوّد بالإضافة إلى مساعدات onboarding/config
يجب على شيفرة الإنتاج الخاصة بالامتدادات أيضًا تجنب استيرادات openclaw/plugin-sdk/<other-plugin>. وإذا كانت مساعدة ما مشتركة فعلًا، فقم بترقيتها إلى مسار SDK محايد مثل openclaw/plugin-sdk/speech أو .../provider-model-shared أو سطح آخر موجه نحو القدرات بدلًا من ربط pluginين معًا.

​
ذو صلة