إنشاء Plugins

توسّع Plugins قدرات OpenClaw دون تغيير النواة. يمكن أن يضيف Plugin قناة مراسلة، أو موفّر نموذج، أو واجهة CLI خلفية محلية، أو أداة وكيل، أو خطافًا، أو موفّر وسائط، أو قدرة أخرى يملكها Plugin.

لا يلزم إضافة Plugin خارجي إلى مستودع OpenClaw. انشر الحزمة على ClawHub، ويمكن للمستخدمين تثبيتها باستخدام:

openclaw plugins install clawhub:<package-name>

تظل مواصفات الحزم المجرّدة تُثبَّت من npm خلال مرحلة الانتقال عند الإطلاق. استخدم البادئة clawhub: عندما تريد الحل عبر ClawHub.

المتطلبات

• Node 22.22.3+، أو Node 24.15+، أو Node 25.9+، وnpm أو pnpm.
• وحدات TypeScript ESM.
• للعمل على Plugin مضمّن داخل المستودع، استنسخ المستودع وشغّل pnpm install. يقتصر تطوير Plugins من نسخة المصدر على pnpm لأن OpenClaw يكتشف Plugins المضمّنة من حزم مساحة العمل extensions/*.

اختيار بنية Plugin

البدء السريع

أنشئ Plugin أداة بسيطًا بتسجيل أداة وكيل واحدة مطلوبة. هذه هي أقصر بنية مفيدة لـ Plugin، وتشمل الحزمة والبيان ونقطة الدخول والتحقق المحلي.

{"name": "@myorg/openclaw-my-plugin","version": "1.0.0","type": "module","dependencies": {"typebox": "1.1.39"},"peerDependencies": {"openclaw": ">=2026.3.24-beta.2"},"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"}}}

{"id": "my-plugin","name": "My Plugin","description": "Adds a custom tool to OpenClaw","contracts": {"tools": ["my_tool"]},"activation": {"onStartup": true},"configSchema": {"type": "object","additionalProperties": false}}

import { Type } from "typebox";import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; export default definePluginEntry({  id: "my-plugin",  name: "My Plugin",  description: "Adds a custom tool to OpenClaw",  register(api) {    api.registerTool({      name: "my_tool",      description: "Echo one input value",      parameters: Type.Object({ input: Type.String() }),      async execute(_id, params) {        return {          content: [{ type: "text", text: `Got: ${params.input}` }],        };      },    });  },});

openclaw plugins inspect my-plugin --runtime --json

pnpm test extensions/my-plugin/pnpm check

npm pack --pack-destination /tmpopenclaw plugins install npm-pack:/tmp/<plugin-package>.tgz --forceopenclaw plugins inspect my-plugin --runtime --json

clawhub package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-plugin

openclaw plugins install clawhub:your-org/your-plugin

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

يمكن أن تكون الأدوات مطلوبة أو اختيارية. تتوفر الأدوات المطلوبة دائمًا عندما يكون Plugin مفعّلًا. أما الأدوات الاختيارية فتحتاج إلى اشتراك صريح من المستخدم قبل أن يحمّل OpenClaw وقت تشغيل Plugin المالك.

تتلقى مصانع الأدوات سياق وقت تشغيل موثوقًا، بما في ذلك deliveryContext، وnativeChannelId لمحادثة المنصة النشطة عند توفرها، و requesterSenderId.

register(api) {  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 },  );}

يجب أيضًا التصريح عن كل أداة مسجّلة باستخدام api.registerTool(...) في بيان Plugin:

{  "contracts": {    "tools": ["workflow_tool"]  },  "toolMetadata": {    "workflow_tool": {      "optional": true    }  }}

يشترك المستخدمون باستخدام tools.allow:

{  tools: { allow: ["workflow_tool"] }, // or ["my-plugin"] for every tool from one plugin}

تتحكم الأدوات الاختيارية في عرض الأداة للنموذج من عدمه. استخدم طلبات أذونات Plugin عندما ينبغي لأداة أو خطاف طلب الموافقة بعد أن يختاره النموذج وقبل تنفيذ الإجراء.

استخدم الأدوات الاختيارية للآثار الجانبية أو الملفات الثنائية غير المعتادة أو القدرات التي لا ينبغي عرضها افتراضيًا. يجب ألا تتعارض أسماء الأدوات مع أسماء أدوات النواة؛ إذ تُتخطى التعارضات ويُبلّغ عنها في تشخيصات Plugin. كما تُتخطى التسجيلات المشوهة ويُبلّغ عنها بالطريقة نفسها: غياب قيمة غير فارغة لـ name، أو كون execute غير دالة، أو وجود واصف أداة دون كائن parameters.

تتلقى مصانع الأدوات كائن سياق يوفّره وقت التشغيل. استخدم ctx.activeModel عندما تحتاج الأداة إلى تسجيل النموذج النشط للدور الحالي أو عرضه أو التكيّف معه؛ ويمكن أن يتضمن provider وmodelId وmodelRef. تعامل معه على أنه بيانات وصفية معلوماتية لوقت التشغيل، وليس حدًا أمنيًا في مواجهة المشغّل المحلي أو شيفرة Plugin المثبّت أو وقت تشغيل OpenClaw المعدّل. ومع ذلك، ينبغي أن تتطلب الأدوات المحلية الحساسة اشتراكًا صريحًا من Plugin أو المشغّل، وأن تفشل بشكل مغلق عند غياب البيانات الوصفية للنموذج النشط أو عدم ملاءمتها.

يصرّح البيان بالملكية والاكتشاف؛ لكن التنفيذ يظل يستدعي تطبيق الأداة المسجّل والحالي. حافظ على اتساق toolMetadata.<tool>.optional: true مع api.registerTool(..., { optional: true }) كي يتمكن OpenClaw من تجنّب تحميل وقت تشغيل ذلك Plugin إلى أن تُدرج الأداة صراحةً في قائمة السماح.

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

استورد من المسارات الفرعية المركزة في SDK:

لا تستورد من الحزمة الجذرية المهملة:

داخل حزمة Plugin، استخدم ملفات الحزمة المحلية مثل api.ts و runtime-api.ts لعمليات الاستيراد الداخلية. لا تستورد Plugin الخاص بك عبر مسار SDK. ينبغي أن تبقى الأدوات المساعدة الخاصة بالموفّر في حزمة الموفّر ما لم تكن الواجهة عامة فعلًا.

طرق RPC المخصصة في Gateway هي نقطة دخول متقدمة. احتفظ بها تحت بادئة خاصة بـ Plugin؛ إذ تظل نطاقات إدارة النواة مثل config.* وexec.approvals.* وoperator.admin.* وwizard.* وupdate.* محجوزة وتُحل إلى operator.admin. ويُحجز جسر openclaw/plugin-sdk/gateway-method-runtime لمسارات HTTP الخاصة بـ Plugins التي تصرّح عن contracts.gatewayMethodDispatch: ["authenticated-request"].

للاطلاع على خريطة الاستيراد الكاملة، راجع نظرة عامة على SDK الخاص بـ Plugin.

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

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s يحتوي package.json على بيانات openclaw الوصفية الصحيحة OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s بيان openclaw.plugin.json موجود وصالح OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s تستخدم نقطة الدخول defineChannelPluginEntry أو definePluginEntry OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s تستخدم جميع الاستيرادات مسارات plugin-sdk/<subpath> المركزة OPENCLAW_DOCS_MARKER:calloutClose: