بناء Plugins

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

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

openclaw plugins install clawhub:<package-name>

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

المتطلبات

• استخدم Node 22.19+، أو Node 23.11+، أو Node 24+ ومدير حزم مثل npm أو pnpm.
• كن ملمًا بوحدات TypeScript ESM.
• للعمل على مكوّن إضافي مضمّن داخل المستودع، انسخ المستودع وشغّل pnpm install. تطوير المكوّنات الإضافية من نسخة المصدر يستخدم pnpm فقط لأن OpenClaw يحمّل المكوّنات الإضافية المضمّنة من حزم مساحة العمل extensions/*.

اختر شكل المكوّن الإضافي

البدء السريع

ابنِ مكوّنًا إضافيًا بسيطًا للأدوات عبر تسجيل أداة وكيل مطلوبة واحدة. هذا هو أقصر شكل مكوّن إضافي مفيد، ويوضح الحزمة، والبيان، ونقطة الدخول، والإثبات المحلي.

{"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

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

يمكن أن تكون الأدوات مطلوبة أو اختيارية. تكون الأدوات المطلوبة متاحة دائمًا عندما يكون المكوّن الإضافي ممكّنًا. تتطلب الأدوات الاختيارية موافقة المستخدم.

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(...) في بيان المكوّن الإضافي:

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

يوافق المستخدمون باستخدام tools.allow:

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

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

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

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

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

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

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

لا تستورد من البرميل الجذري المهمل:

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

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

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

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

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: