20 KiB
| read_when | sidebarTitle | summary | title | x-i18n | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Getting Started | أنشئ أول Plugin لـ OpenClaw في غضون دقائق | بناء Plugins |
|
بناء 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 الذي تريد إنشاءه؟
اربط OpenClaw بمنصة مراسلة (Discord أو IRC أو غيرهما) أضف موفّر نماذج (LLM أو وكيل أو نقطة نهاية مخصّصة) سجّل أدوات الوكيل أو event hooks أو الخدمات — تابع أدناهإذا كان Plugin القناة اختياريًا وقد لا يكون مُثبّتًا عند تشغيل الإعداد أو
التهيئة الأولية، فاستخدم createOptionalChannelSetupSurface(...) من
openclaw/plugin-sdk/channel-setup. فهو ينتج زوجًا من محوّل إعداد + معالج إعداد
يعرض متطلب التثبيت ويفشل بشكل آمن عند أي عمليات كتابة فعلية للإعدادات
إلى أن يتم تثبيت Plugin.
بداية سريعة: Plugin أداة
ينشئ هذا الدليل العملي Plugin بسيطًا يسجّل أداة وكيل. لدى Plugins القنوات والموفّرين أدلة مخصّصة مرتبطة أعلاه.
```json package.json { "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" } } } ``````json openclaw.plugin.json
{
"id": "my-plugin",
"name": "My Plugin",
"description": "Adds a custom tool to OpenClaw",
"configSchema": {
"type": "object",
"additionalProperties": false
}
}
```
</CodeGroup>
يحتاج كل Plugin إلى ملف manifest، حتى إذا لم تكن لديه إعدادات. راجع
[Manifest](/ar/plugins/manifest) للاطلاع على المخطط الكامل. توجد مقتطفات النشر
القياسية إلى ClawHub في `docs/snippets/plugin-publish/`.
```typescript
// 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` — راجع [Plugins القنوات](/ar/plugins/sdk-channel-plugins).
وللاطلاع على الخيارات الكاملة لنقطة الإدخال، راجع [نقاط الإدخال](/ar/plugins/sdk-entrypoints).
**Plugins الخارجية:** تحقّق منها وانشرها باستخدام ClawHub، ثم ثبّتها:
```bash
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 داخل المستودع:** ضعها ضمن شجرة مساحة عمل Plugins المضمّنة — وسيتم اكتشافها تلقائيًا.
```bash
pnpm test -- <bundled-plugin-root>/my-plugin/
```
قدرات Plugin
يمكن لـ Plugin واحد تسجيل أي عدد من القدرات عبر الكائن api:
| القدرة | طريقة التسجيل | الدليل المفصل |
|---|---|---|
| الاستدلال النصي (LLM) | api.registerProvider(...) |
Plugins الموفّر |
| واجهة خلفية للاستدلال عبر CLI | api.registerCliBackend(...) |
واجهات CLI الخلفية |
| القناة / المراسلة | api.registerChannel(...) |
Plugins القنوات |
| الكلام (TTS/STT) | api.registerSpeechProvider(...) |
Plugins الموفّر |
| النسخ الفوري | api.registerRealtimeTranscriptionProvider(...) |
Plugins الموفّر |
| الصوت الفوري | api.registerRealtimeVoiceProvider(...) |
Plugins الموفّر |
| فهم الوسائط | api.registerMediaUnderstandingProvider(...) |
Plugins الموفّر |
| توليد الصور | api.registerImageGenerationProvider(...) |
Plugins الموفّر |
| توليد الموسيقى | api.registerMusicGenerationProvider(...) |
Plugins الموفّر |
| توليد الفيديو | api.registerVideoGenerationProvider(...) |
Plugins الموفّر |
| جلب الويب | api.registerWebFetchProvider(...) |
Plugins الموفّر |
| البحث على الويب | api.registerWebSearchProvider(...) |
Plugins الموفّر |
| امتداد Pi مضمّن | api.registerEmbeddedExtensionFactory(...) |
نظرة عامة على SDK |
| أدوات الوكيل | api.registerTool(...) |
أدناه |
| أوامر مخصّصة | api.registerCommand(...) |
نقاط الإدخال |
| event hooks | api.registerHook(...) |
نقاط الإدخال |
| مسارات HTTP | api.registerHttpRoute(...) |
الداخليات |
| أوامر CLI فرعية | api.registerCli(...) |
نقاط الإدخال |
للاطلاع على API التسجيل الكامل، راجع نظرة عامة على SDK.
استخدم api.registerEmbeddedExtensionFactory(...) عندما يحتاج Plugin إلى
hooks خاصة بالمشغّل المضمّن الأصلية في Pi مثل إعادة كتابة tool_result
غير المتزامنة قبل إصدار رسالة نتيجة الأداة النهائية. ويفضَّل استخدام hooks
Plugin العادية في OpenClaw عندما لا يتطلب العمل توقيت امتداد Pi.
إذا كان Plugin الخاص بك يسجّل أساليب RPC مخصّصة لـ Gateway، فاحتفظ بها ضمن
بادئة خاصة بالـ 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 }توقف تنفيذ الوكيل مؤقتًا وتطلب موافقة المستخدم عبر طبقة موافقات التنفيذ، أو أزرار Telegram، أو تفاعلات Discord، أو الأمر/approveعلى أي قناة.before_install: القيمة{ block: true }نهائية وتوقف المعالجات ذات الأولوية الأقل.before_install: القيمة{ block: false }تُعامل على أنها بلا قرار.message_sending: القيمة{ cancel: true }نهائية وتوقف المعالجات ذات الأولوية الأقل.message_sending: القيمة{ cancel: false }تُعامل على أنها بلا قرار.
يتعامل الأمر /approve مع كلٍّ من موافقات التنفيذ وموافقات Plugin مع بديل
احتياطي مقيّد: عندما لا يتم العثور على معرّف موافقة تنفيذ، يعيد OpenClaw
محاولة استخدام المعرّف نفسه عبر موافقات Plugin. ويمكن تهيئة إعادة توجيه
موافقات Plugin بشكل مستقل عبر approvals.plugin في الإعدادات.
إذا كانت بنية الموافقات المخصّصة تحتاج إلى اكتشاف حالة البديل الاحتياطي
المقيّد نفسها، فافضّل استخدام isApprovalNotFoundError من
openclaw/plugin-sdk/error-runtime بدلًا من مطابقة سلاسل انتهاء صلاحية
الموافقة يدويًا.
راجع دلالات قرارات 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 الخاص به.
بالنسبة إلى Plugins الموفّر، احتفظ بالمساعدات الخاصة بالموفّر في ملفات barrel الموجودة في جذر الحزمة ما لم يكن الحد الفاصل عامًا فعلًا. أمثلة الحزم المضمّنة الحالية:
- Anthropic: أغلفة Claude للبث ومساعدات
service_tierو beta - OpenAI: بُنّاة الموفّرين، ومساعدات النماذج الافتراضية، وموفّرو الزمن الحقيقي
- OpenRouter: باني الموفّر بالإضافة إلى مساعدات الإعداد الأولي والتهيئة
إذا كان المساعد مفيدًا فقط داخل حزمة موفّر مضمّنة واحدة، فأبقِه ضمن هذا
الحد الفاصل في جذر الحزمة بدلًا من ترقيته إلى 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 داخل المستودع)
اختبار الإصدار التجريبي
- راقب وسوم إصدارات GitHub في openclaw/openclaw واشترك عبر
Watch>Releases. تبدو وسوم الإصدارات التجريبية مثلv2026.3.N-beta.1. يمكنك أيضًا تفعيل الإشعارات لحساب OpenClaw الرسمي على X @openclaw لإعلانات الإصدارات. - اختبر Plugin الخاص بك مع الوسم التجريبي فور ظهوره. تكون المهلة قبل الإصدار المستقر عادة بضع ساعات فقط.
- انشر في سلسلة Plugin الخاص بك في قناة Discord
plugin-forumبعد الاختبار بإحدى العبارتين:all goodأو ما الذي تعطّل. إذا لم تكن لديك سلسلة بعد، فأنشئ واحدة. - إذا تعطّل شيء ما، فافتح Issue أو حدّث واحدة بعنوان
Beta blocker: <plugin-name> - <summary>وطبّق التصنيفbeta-blocker. ضع رابط الـ Issue في سلسلتك. - افتح PR إلى
mainبعنوانfix(<plugin-id>): beta blocker - <summary>واربط الـ Issue في كلٍّ من PR وسلسلة Discord الخاصة بك. لا يمكن للمساهمين وضع تصنيفات على PRs، لذا يُعد العنوان الإشارة في جهة PR للمشرفين والأتمتة. يتم دمج العناصر المانعة مع PR؛ أما العناصر المانعة من دون PR فقد تُشحن على أي حال. يراقب المشرفون هذه السلاسل أثناء اختبار الإصدارات التجريبية. - عدم وجود ردود يعني أن كل شيء جيد. إذا فاتتك المهلة، فمن المرجّح أن يصل إصلاحك في الدورة التالية.
الخطوات التالية
أنشئ Plugin لقناة مراسلة أنشئ Plugin لموفّر نماذج مرجع خريطة الاستيراد وAPI التسجيل TTS والبحث وsubagent عبر api.runtime أدوات وأنماط الاختبار المرجع الكامل لمخطط manifestذو صلة
- معمارية Plugin — شرح معماري داخلي متعمّق
- نظرة عامة على SDK — مرجع Plugin SDK
- Manifest — تنسيق manifest الخاص بالـ plugin
- Plugins القنوات — بناء Plugins القنوات
- Plugins الموفّر — بناء Plugins الموفّر