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

​
بناء Plugins

توسّع Plugins قدرات OpenClaw بإمكانات جديدة: القنوات، وموفرو النماذج، والكلام، والنسخ الفوري، والصوت الفوري، وفهم الوسائط، وتوليد الصور، وتوليد الفيديو، وجلب الويب، والبحث على الويب، وأدوات الوكيل، أو أي مزيج منها. لا تحتاج إلى إضافة plugin الخاص بك إلى مستودع OpenClaw. انشره على ClawHub أو npm وسيقوم المستخدمون بتثبيته باستخدام openclaw plugins install <package-name>. يحاول OpenClaw استخدام ClawHub أولًا ثم يرجع تلقائيًا إلى npm.

​
المتطلبات الأساسية

  • Node >= 22 ومدير حزم (npm أو pnpm)
  • الإلمام بـ TypeScript ‏(ESM)
  • بالنسبة إلى plugins داخل المستودع: يجب أن يكون المستودع مستنسخًا وقد تم تشغيل pnpm install

​
ما نوع plugin الذي تريده؟

Channel plugin

وصّل OpenClaw بمنصة مراسلة (Discord وIRC وغيرهما)

Provider plugin

أضف مزود نماذج (LLM أو proxy أو endpoint مخصص)

Tool / hook plugin

سجّل أدوات الوكيل أو event hooks أو الخدمات — تابع أدناه
إذا كان Channel plugin اختياريًا وقد لا يكون مثبتًا عند تشغيل onboarding/setup، فاستخدم createOptionalChannelSetupSurface(...) من openclaw/plugin-sdk/channel-setup. فهو ينتج setup adapter + wizard يعلن عن متطلب التثبيت ويفشل بشكل مغلق عند محاولات كتابة الإعدادات الفعلية إلى أن يتم تثبيت plugin.

​
بدء سريع: Tool plugin

ينشئ هذا الدليل plugin بسيطًا يسجل أداة وكيل. أما Channel plugins وProvider plugins فلها أدلة مخصصة مرتبطة أعلاه.
1

أنشئ الحزمة وmanifest

{
  "name": "@myorg/openclaw-my-plugin",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./index.ts"],
    "compat": {
      "pluginApi": ">=2026.3.24-beta.2",
      "minGatewayVersion": "2026.3.24-beta.2"
    },
    "build": {
      "openclawVersion": "2026.3.24-beta.2",
      "pluginSdkVersion": "2026.3.24-beta.2"
    }
  }
}
يحتاج كل plugin إلى manifest، حتى من دون إعدادات. راجع Manifest للاطلاع على المخطط الكامل. وتوجد مقتطفات النشر القياسية الخاصة بـ ClawHub في docs/snippets/plugin-publish/.
2

اكتب نقطة الإدخال

// index.ts
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { Type } from "@sinclair/typebox";

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Adds a custom tool to OpenClaw",
  register(api) {
    api.registerTool({
      name: "my_tool",
      description: "Do a thing",
      parameters: Type.Object({ input: Type.String() }),
      async execute(_id, params) {
        return { content: [{ type: "text", text: `Got: ${params.input}` }] };
      },
    });
  },
});
يُستخدم definePluginEntry للـ plugins غير الخاصة بالقنوات. أما القنوات فاستخدم defineChannelPluginEntry — راجع Channel Plugins. وللاطلاع على الخيارات الكاملة لنقطة الإدخال، راجع Entry Points.
3

اختبر وانشر

Plugins الخارجية: تحقّق وانشر باستخدام ClawHub، ثم ثبّت:
clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
openclaw plugins install clawhub:@myorg/openclaw-my-plugin
يفحص OpenClaw أيضًا ClawHub قبل npm عند استخدام مواصفات حزم مجردة مثل @myorg/openclaw-my-plugin.Plugins داخل المستودع: ضَعها ضمن شجرة workspace الخاصة بالـ plugin المضمّن — سيتم اكتشافها تلقائيًا.
pnpm test -- <bundled-plugin-root>/my-plugin/

​
قدرات plugin

يمكن لـ plugin واحد تسجيل أي عدد من القدرات عبر الكائن api:
القدرةطريقة التسجيلالدليل المفصل
الاستدلال النصي (LLM)api.registerProvider(...)Provider Plugins
CLI inference backendapi.registerCliBackend(...)CLI Backends
القناة / المراسلةapi.registerChannel(...)Channel Plugins
الكلام (TTS/STT)api.registerSpeechProvider(...)Provider Plugins
النسخ الفوريapi.registerRealtimeTranscriptionProvider(...)Provider Plugins
الصوت الفوريapi.registerRealtimeVoiceProvider(...)Provider Plugins
فهم الوسائطapi.registerMediaUnderstandingProvider(...)Provider Plugins
توليد الصورapi.registerImageGenerationProvider(...)Provider Plugins
توليد الموسيقىapi.registerMusicGenerationProvider(...)Provider Plugins
توليد الفيديوapi.registerVideoGenerationProvider(...)Provider Plugins
جلب الويبapi.registerWebFetchProvider(...)Provider Plugins
البحث على الويبapi.registerWebSearchProvider(...)Provider Plugins
أدوات الوكيلapi.registerTool(...)أدناه
أوامر مخصصةapi.registerCommand(...)Entry Points
Event hooksapi.registerHook(...)Entry Points
مسارات HTTPapi.registerHttpRoute(...)Internals
أوامر CLI فرعيةapi.registerCli(...)Entry Points
للاطلاع على API التسجيل الكامل، راجع نظرة عامة على SDK. إذا كان plugin الخاص بك يسجل أساليب Gateway RPC مخصصة، فاحتفظ بها ضمن بادئة خاصة بـ plugin. تظل مساحات أسماء الإدارة الأساسية (config.*, exec.approvals.*, wizard.*, update.*) محجوزة وتُحل دائمًا إلى operator.admin، حتى إذا طلب plugin نطاقًا أضيق. دلالات حرس الـ hook التي يجب وضعها في الاعتبار:
  • before_tool_call: ‏{ block: true } نهائية وتوقف المعالجات ذات الأولوية الأقل.
  • before_tool_call: ‏{ block: false } تُعامل على أنها بدون قرار.
  • before_tool_call: ‏{ requireApproval: true } توقف تنفيذ الوكيل مؤقتًا وتطلب موافقة المستخدم عبر طبقة exec approval، أو أزرار Telegram، أو تفاعلات Discord، أو الأمر /approve على أي قناة.
  • before_install: ‏{ block: true } نهائية وتوقف المعالجات ذات الأولوية الأقل.
  • before_install: ‏{ block: false } تُعامل على أنها بدون قرار.
  • message_sending: ‏{ cancel: true } نهائية وتوقف المعالجات ذات الأولوية الأقل.
  • message_sending: ‏{ cancel: false } تُعامل على أنها بدون قرار.
يعالج الأمر /approve كلًا من exec approvals وplugin approvals مع fallback مقيّد: فعندما لا يتم العثور على معرّف exec approval، يعيد OpenClaw محاولة المعرّف نفسه عبر plugin approvals. ويمكن ضبط تمرير plugin approval بشكل مستقل عبر approvals.plugin في الإعدادات. إذا كان من الضروري أن يكتشف منطق approval المخصص حالة fallback المقيّدة نفسها، ففضّل استخدام isApprovalNotFoundError من openclaw/plugin-sdk/error-runtime بدلًا من مطابقة سلاسل انتهاء صلاحية approval يدويًا. راجع دلالات قرارات hook في نظرة عامة على SDK للتفاصيل.

​
تسجيل أدوات الوكيل

الأدوات هي دوال typed يمكن لـ LLM استدعاؤها. ويمكن أن تكون مطلوبة (متاحة دائمًا) أو اختيارية (اشتراك من المستخدم): 
register(api) {
  // Required tool — always available
  api.registerTool({
    name: "my_tool",
    description: "Do a thing",
    parameters: Type.Object({ input: Type.String() }),
    async execute(_id, params) {
      return { content: [{ type: "text", text: params.input }] };
    },
  });

  // Optional tool — user must add to allowlist
  api.registerTool(
    {
      name: "workflow_tool",
      description: "Run a workflow",
      parameters: Type.Object({ pipeline: Type.String() }),
      async execute(_id, params) {
        return { content: [{ type: "text", text: params.pipeline }] };
      },
    },
    { optional: true },
  );
}
يفعّل المستخدمون الأدوات الاختيارية في الإعدادات: 
{
  tools: { allow: ["workflow_tool"] },
}
  • يجب ألا تتعارض أسماء الأدوات مع الأدوات الأساسية (يتم تخطي التعارضات)
  • استخدم optional: true للأدوات ذات التأثيرات الجانبية أو متطلبات الملفات التنفيذية الإضافية
  • يمكن للمستخدمين تفعيل جميع أدوات plugin عبر إضافة معرّف plugin إلى tools.allow

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

استورد دائمًا من مسارات فرعية مركّزة openclaw/plugin-sdk/<subpath>: 
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";

// Wrong: monolithic root (deprecated, will be removed)
import { ... } from "openclaw/plugin-sdk";
للاطلاع على المرجع الكامل للمسارات الفرعية، راجع نظرة عامة على SDK. داخل plugin الخاص بك، استخدم ملفات barrel محلية (api.ts, runtime-api.ts) لعمليات الاستيراد الداخلية — ولا تستورد plugin الخاص بك أبدًا عبر مسار SDK الخاص به. بالنسبة إلى Provider plugins، احتفظ بالمساعدات الخاصة بالمزود داخل ملفات barrel الموجودة في جذر الحزمة ما لم تكن نقطة الربط عامة فعلًا. ومن الأمثلة المضمنة الحالية:
  • Anthropic: مغلفات تدفق Claude ومساعدات service_tier / beta
  • OpenAI: بُناة المزودات، ومساعدات النماذج الافتراضية، ومزودات الوقت الفعلي
  • OpenRouter: باني المزود بالإضافة إلى مساعدات onboarding/config
إذا كان المساعد مفيدًا فقط داخل حزمة مزود مضمّنة واحدة، فأبقِه ضمن نقطة الربط الموجودة في جذر تلك الحزمة بدلًا من ترقيته إلى openclaw/plugin-sdk/*. لا تزال بعض نقاط الربط المساعدة المولدة openclaw/plugin-sdk/<bundled-id> موجودة لصيانة plugins المضمّنة والتوافق، مثل plugin-sdk/feishu-setup أو plugin-sdk/zalo-setup. تعامل معها على أنها أسطح محجوزة، وليست النمط الافتراضي لـ plugins الخارجية الجديدة.

​
قائمة التحقق قبل الإرسال

يحتوي package.json على بيانات openclaw الوصفية الصحيحة
يوجد manifest openclaw.plugin.json وهو صالح
تستخدم نقطة الإدخال defineChannelPluginEntry أو definePluginEntry
تستخدم جميع عمليات الاستيراد مسارات مركّزة plugin-sdk/<subpath>
تستخدم عمليات الاستيراد الداخلية وحدات محلية، لا عمليات استيراد ذاتية عبر SDK
تجتاز الاختبارات (pnpm test -- <bundled-plugin-root>/my-plugin/)
يجتاز pnpm check (للـ plugins داخل المستودع)

​
اختبار الإصدار التجريبي

  1. راقب وسوم إصدارات GitHub على openclaw/openclaw واشترك عبر Watch > Releases. تبدو الوسوم التجريبية مثل v2026.3.N-beta.1. ويمكنك أيضًا تفعيل الإشعارات للحساب الرسمي لـ OpenClaw على X ‏@openclaw للإعلانات الخاصة بالإصدارات.
  2. اختبر plugin الخاص بك مقابل الوسم التجريبي بمجرد ظهوره. وعادةً ما تكون النافذة قبل الإصدار المستقر بضع ساعات فقط.
  3. انشر في سلسلة plugin الخاصة بك في قناة Discord ‏plugin-forum بعد الاختبار بإحدى العبارتين all good أو ما الذي تعطل. وإذا لم تكن لديك سلسلة بعد، فأنشئ واحدة.
  4. إذا تعطل شيء ما، فافتح أو حدّث issue بعنوان Beta blocker: <plugin-name> - <summary> وطبّق الوسم beta-blocker. ضَع رابط issue في سلسلتك.
  5. افتح PR إلى main بعنوان fix(<plugin-id>): beta blocker - <summary> واربط issue في كل من PR وسلسلة Discord الخاصة بك. لا يستطيع المساهمون إضافة وسوم إلى PRs، لذا فالعنوان هو الإشارة الخاصة بـ PR للمشرفين وللأتمتة. يتم دمج المشكلات الحرجة التي لها PR؛ أما التي لا تملك واحدًا فقد تُشحن على أي حال. يراقب المشرفون هذه السلاسل أثناء الاختبار التجريبي.
  6. الصمت يعني أن كل شيء على ما يرام. وإذا فاتتك النافذة، فمن المرجح أن يصل إصلاحك في الدورة التالية.

​
الخطوات التالية

Channel Plugins

ابنِ Channel plugin للمراسلة

Provider Plugins

ابنِ Provider plugin للنماذج

SDK Overview

مرجع خريطة الاستيراد وAPI التسجيل

Runtime Helpers

TTS والبحث وsubagent عبر api.runtime

Testing

أدوات وأنماط الاختبار

Plugin Manifest

المرجع الكامل لمخطط manifest

​
ذو صلة