إنشاء Plugins

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

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

openclaw plugins install clawhub:<package-name>

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

المتطلبات

• Node 22.19+، أو Node 23.11+، أو Node 24+، و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 الخاصة بـPlugin التي تصرّح عن 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: