الإضافات

تُوسّع Plugins إمكانات OpenClaw بإضافة القنوات، وموفّري النماذج، وأُطر تشغيل الوكلاء، والأدوات، وSkills، والكلام، والنسخ الفوري، والصوت، وفهم الوسائط، والتوليد، وجلب الويب، والبحث في الويب، وإمكانات تشغيل أخرى. استخدم هذه الصفحة لتثبيت Plugin، وإعادة تشغيل Gateway، والتحقق من أن بيئة التشغيل قد حمّلته، ومعالجة حالات فشل الإعداد الشائعة. للاطلاع على أمثلة الأوامر فقط، راجع إدارة Plugins. وللاطلاع على القائمة المُنشأة لـPlugins المضمّنة، والخارجية الرسمية، والمتاحة كمصدر فقط، راجع قائمة Plugins.

المتطلبات

نسخة عمل أو تثبيت من OpenClaw تتوفر فيه CLI ‏openclaw
إمكانية الوصول إلى الشبكة للمصدر المحدد (ClawHub أو npm أو مضيف git)
أي بيانات اعتماد أو مفاتيح إعداد أو أدوات نظام تشغيل خاصة بـPlugin ومذكورة في وثائق إعداد ذلك الـPlugin
إذن لـGateway الذي يخدم قنواتك لإعادة التحميل أو إعادة التشغيل

البدء السريع

العثور على Plugin

ابحث في ClawHub عن حزم Plugins العامة:

openclaw plugins search "calendar"

يُعد ClawHub الواجهة الأساسية لاكتشاف Plugins المجتمعية. خلال الانتقال عند الإطلاق، تظل مواصفات الحزم العادية المجرّدة تُثبَّت من npm ما لم تطابق معرّف Plugin رسميًا. تُحل مواصفات @openclaw/* الأولية التي تطابق Plugin مضمّنًا إلى النسخة المضمّنة منه. استخدم بادئة مصدر صريحة عندما تحتاج إلى مصدر بعينه.

تثبيت Plugin

# من ClawHub.
openclaw plugins install clawhub:<package>

# من npm.
openclaw plugins install npm:<package>

# من git.
openclaw plugins install git:github.com/<owner>/<repo>@<ref>

# من نسخة عمل تطوير محلية.
openclaw plugins install ./my-plugin
openclaw plugins install --link ./my-plugin

تعامل مع عمليات تثبيت Plugins كأنها تشغيل للتعليمات البرمجية. فضّل الإصدارات المثبّتة لعمليات تثبيت إنتاجية قابلة لإعادة الإنتاج. تُعد حزم ClawHub وكتالوج OpenClaw المضمّن/الرسمي مصادر موثوقة. تتطلب مصادر npm أو git أو المسار/الأرشيف المحلي أو npm-pack: أو المتجر التعسفية الجديدة استخدام --force في عمليات التثبيت غير التفاعلية بعد مراجعة المصدر والثقة به.

إعداده وتمكينه

اضبط الإعدادات الخاصة بالـPlugin ضمن plugins.entries.<id>.config. مكّن الـPlugin إذا لم يكن ممكّنًا بالفعل:

openclaw plugins enable <plugin-id>

إذا كان plugins.allow مضبوطًا، فيجب أن يكون معرّف الـPlugin المثبّت ضمن تلك القائمة قبل أن يتمكن الـPlugin من التحميل. يضيف openclaw plugins install المعرّف المثبّت إلى قائمة plugins.allow موجودة ويزيل المعرّف نفسه من plugins.deny لكي يتمكن التثبيت الصريح من التحميل بعد إعادة التشغيل.

السماح لـGateway بإعادة التحميل

يتطلب تثبيت تعليمات Plugin البرمجية أو تحديثها أو إلغاء تثبيتها إعادة تشغيل Gateway. يكتشف Gateway مُدار مع تمكين إعادة تحميل الإعدادات تغيّر سجل تثبيت الـPlugin ويعيد التشغيل تلقائيًا. وإلا فأعد تشغيله بنفسك:

openclaw gateway restart

يؤدي التمكين/التعطيل إلى تحديث الإعدادات والسجل البارد. ويظل فحص بيئة التشغيل أوضح دليل على واجهات بيئة التشغيل النشطة.

التحقق من التسجيل في بيئة التشغيل

openclaw plugins inspect <plugin-id> --runtime --json

استخدم --runtime لإثبات الأدوات والخطافات والخدمات وأساليب Gateway أو أوامر CLI المملوكة للـPlugin والمسجّلة. أما inspect العادي فهو فحص بارد للبيان والسجل فقط.

الإعداد

اختيار مصدر التثبيت

المصدر	يُستخدم عندما	المثال
ClawHub	تريد اكتشافًا أصيلًا لـOpenClaw، وعمليات فحص، وبيانات وصفية للإصدارات، وتلميحات تثبيت	`openclaw plugins install clawhub:<package>`
npm	تحتاج إلى سير عمل مباشر لسجل npm أو وسوم التوزيع	`openclaw plugins install npm:<package>`
git	تحتاج إلى فرع أو وسم أو إيداع من مستودع	`openclaw plugins install git:github.com/<owner>/<repo>@<ref>`
مسار محلي	تطوّر أو تختبر Plugin على الجهاز نفسه	`openclaw plugins install --link ./my-plugin`
متجر	تثبّت Plugin من متجر متوافق مع Claude	`openclaw plugins install <plugin> --marketplace <source>`

لمواصفات الحزم المجرّدة سلوك توافق خاص: فالاسم المجرّد الذي يطابق معرّف Plugin مضمّنًا يستخدم ذلك المصدر المضمّن؛ والاسم المجرّد الذي يطابق معرّف Plugin خارجيًا رسميًا يستخدم كتالوج الحزم الرسمي؛ وأي مواصفة مجرّدة أخرى تُثبَّت عبر npm خلال الانتقال عند الإطلاق. كما تُحل مواصفات @openclaw/* الأولية التي تطابق Plugins مضمّنة إلى النسخة المضمّنة قبل الرجوع إلى npm. استخدم npm:@openclaw/<plugin>@<version> لتثبيت حزمة npm الخارجية عمدًا بدلًا من النسخة المضمّنة. استخدم clawhub: أو npm: أو git: أو npm-pack: لتحديد المصدر بشكل حتمي. راجع openclaw plugins للاطلاع على عقد الأمر الكامل. بالنسبة إلى عمليات تثبيت npm، تختار المواصفات غير المثبّتة و@latest أحدث حزمة مستقرة تعلن توافقها مع إصدار OpenClaw هذا. إذا كان أحدث إصدار حالي في npm يعلن openclaw.compat.pluginApi أو openclaw.install.minHostVersion أحدث مما يدعمه هذا الإصدار، يفحص OpenClaw الإصدارات المستقرة الأقدم ويثبّت أحدث إصدار ملائم. تظل الإصدارات الدقيقة ووسوم القنوات الصريحة مثل @beta مثبّتة على الحزمة المحددة وتفشل عند عدم التوافق.

سياسة تثبيت المشغّل

اضبط security.installPolicy لتشغيل أمر سياسة محلي موثوق قبل متابعة تثبيت Plugin أو تحديثه. تستقبل السياسة البيانات الوصفية بالإضافة إلى مسار المصدر المرحلي، ويمكنها السماح بالتثبيت أو حظره. وتشمل مسارات التثبيت/التحديث المستندة إلى CLI وGateway معًا. تعمل خطافات before_install الخاصة بالـPlugin لاحقًا، وفقط في عمليات OpenClaw التي تُحمّل فيها خطافات الـPlugin، لذا استخدم security.installPolicy بدلًا منها لقرارات التثبيت المملوكة للمشغّل. يُقبل العَلَم المهمل --dangerously-force-unsafe-install لأغراض التوافق، لكنه لا ينفذ شيئًا: فهو لا يتجاوز سياسة التثبيت ولا قائمة OpenClaw المدمجة لمنع تبعيات Plugins. راجع إعداد Skills للاطلاع على مخطط التنفيذ المشترك security.installPolicy الذي تستخدمه كل من Skills وPlugins.

ضبط سياسة Plugins

صيغة إعداد Plugins الشائعة هي:

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: ["untrusted-plugin"],
    load: { paths: ["~/Projects/oss/voice-call-plugin"] },
    slots: { memory: "memory-core" },
    entries: {
      "voice-call": { enabled: true, config: { provider: "twilio" } },
    },
  },
}

قواعد السياسة الأساسية:

plugins.enabled: false يعطّل جميع Plugins ويتخطى أعمال الاكتشاف/التحميل. تظل مراجع Plugins القديمة خاملة أثناء تفعيل هذا الإعداد؛ أعد تمكين Plugins قبل تشغيل تنظيف الطبيب إذا أردت إزالة المعرّفات القديمة.
يتغلب plugins.deny على قائمة السماح والتمكين الخاص بكل Plugin.
plugins.allow هو قائمة سماح حصرية. تظل الأدوات المملوكة للـPlugin خارج قائمة السماح غير متاحة حتى عندما يتضمن tools.allow القيمة "*".
يعطّل plugins.entries.<id>.enabled: false Plugin واحدًا مع الاحتفاظ بإعداده.
يضيف plugins.load.paths ملفات أو أدلة Plugins محلية صريحة. يجب أن تكون المسارات المحلية المُدارة بواسطة plugins install أدلة Plugins أو أرشيفات؛ استخدم plugins.load.paths لملفات Plugins المستقلة.
تُعطّل Plugins الناشئة من مساحة العمل افتراضيًا؛ مكّنها صراحةً أو أضفها إلى قائمة السماح قبل استخدام تعليمات مساحة العمل المحلية البرمجية.
تتبع Plugins المضمّنة بياناتها الوصفية المدمجة للتشغيل أو الإيقاف الافتراضي ما لم يتجاوزها الإعداد صراحةً.
يختار plugins.slots.<slot> ‏(memory أو contextEngine) Plugin واحدًا لفئة حصرية. يُعد تحديد الخانة تنشيطًا صريحًا ويفرض تمكين الـPlugin المحدد لتلك الخانة، حتى لو كان سيتطلب الاشتراك بخلاف ذلك. يظل plugins.deny وplugins.entries.<id>.enabled: false يحظرانه.
يمكن أن تُنشَّط Plugins المضمّنة التي تتطلب الاشتراك تلقائيًا عندما يسمّي الإعداد إحدى واجهاتها المملوكة، مثل مرجع موفّر/نموذج، أو إعداد قناة، أو خلفية CLI، أو بيئة تشغيل إطار وكيل.
يحافظ توجيه Codex ضمن عائلة OpenAI على فصل حدود Plugin الخاص بالموفّر وبيئة التشغيل: مراجع نماذج Codex القديمة هي إعدادات قديمة يصلحها الطبيب، بينما يمتلك Plugin ‏codex المضمّن بيئة تشغيل خادم تطبيق Codex لمراجع الوكلاء القياسية openai/*، وagentRuntime.id: "codex" الصريح، ومراجع codex/* القديمة.

عندما لا يكون plugins.allow مضبوطًا وتُكتشف Plugins غير المضمّنة تلقائيًا من مساحة العمل أو جذور Plugins العامة، تسجّل عملية البدء plugins.allow is empty; discovered non-bundled plugins may auto-load: ... مع معرّفات Plugins المكتشفة، وبالنسبة إلى القوائم القصيرة، مقتطف plugins.allow مختصرًا. شغّل openclaw plugins list --enabled --verbose أو openclaw plugins inspect <id> على معرّف الـPlugin المدرج قبل نسخ Plugins الموثوقة إلى openclaw.json. ينطبق تثبيت الثقة نفسه عندما تشير التشخيصات إلى أن Plugin حُمّل without install/load-path provenance: افحص معرّف ذلك الـPlugin، ثم ثبّته في plugins.allow أو أعد تثبيته من مصدر موثوق لكي يسجل OpenClaw مصدر التثبيت. شغّل openclaw doctor أو openclaw doctor --fix عندما يبلغ التحقق من صحة الإعداد عن معرّفات Plugins قديمة، أو حالات عدم تطابق في قائمة السماح/الأدوات، أو مسارات Plugins مضمّنة قديمة.

فهم تنسيقات Plugins

يتعرف OpenClaw على تنسيقين لـPlugins:

التنسيق	كيفية التحميل	يُستخدم عندما
Plugin أصيل لـOpenClaw	`openclaw.plugin.json` بالإضافة إلى وحدة بيئة تشغيل تُحمّل داخل العملية	تثبّت أو تبني إمكانات بيئة تشغيل خاصة بـOpenClaw
حزمة متوافقة	تخطيط Plugin لـCodex أو Claude أو Cursor يُربط بقائمة Plugins في OpenClaw	تعيد استخدام Skills أو الأوامر أو الخطافات أو البيانات الوصفية للحزم المتوافقة

يظهر كلا التنسيقين في openclaw plugins list وopenclaw plugins inspect وopenclaw plugins enable وopenclaw plugins disable. راجع حزم Plugins لمعرفة حدود توافق الحزم، و بناء Plugins لتأليف Plugins الأصلية.

خطافات Plugins

يمكن لـPlugins تسجيل خطافات في وقت التشغيل من خلال واجهتي API مختلفتين:

خطافات api.on(...) ذات الأنواع لأحداث دورة حياة بيئة التشغيل. هذه هي الواجهة المفضلة للبرمجيات الوسيطة والسياسة وإعادة كتابة الرسائل وتشكيل المطالبات والتحكم في الأدوات.
api.registerHook(...) لنظام الخطافات الداخلي الموضح في الخطافات. يُستخدم هذا أساسًا للآثار الجانبية العامة للأوامر/دورة الحياة وللتوافق مع الأتمتة الحالية بأسلوب HOOK.

قاعدة سريعة: إذا كان المعالج يحتاج إلى أولوية أو دلالات دمج أو سلوك حظر/إلغاء، فاستخدم الخطافات ذات الأنواع. وإذا كان يتفاعل فقط مع command:new أو command:reset أو message:sent أو أحداث عامة مشابهة، فإن api.registerHook مناسب. تظهر الخطافات الداخلية التي تديرها Plugins في openclaw hooks list مع plugin:<id>. لا يمكنك تمكينها أو تعطيلها عبر openclaw hooks؛ بل مكّن الـPlugin أو عطّله بدلًا من ذلك.

التحقق من Gateway النشط

يقرأ openclaw plugins list وopenclaw plugins inspect العادي حالة الإعدادات غير النشطة والبيان والسجل. ولا يثبتان أن Gateway قيد التشغيل بالفعل قد استورد رمز Plugin نفسه. عندما يبدو أن Plugin مثبت، لكن حركة المحادثة المباشرة لا تستخدمه:

openclaw gateway status --deep --require-rpc
openclaw plugins inspect <plugin-id> --runtime --json
openclaw gateway restart

تُعاد تشغيل بوابات Gateway المُدارة تلقائيًا بعد تغييرات تثبيت Plugin وتحديثه وإلغاء تثبيته التي تعدّل مصدر Plugin. في عمليات التثبيت على VPS أو الحاويات، تأكد من أن أي إعادة تشغيل يدوية تستهدف عملية openclaw gateway run الفرعية الفعلية التي تخدم قنواتك، لا مجرد مغلّف أو مشرف.

استكشاف الأخطاء وإصلاحها

العَرَض	التحقق	الإصلاح
يظهر Plugin في `plugins list` لكن خطافات وقت التشغيل لا تعمل	استخدم `openclaw plugins inspect <id> --runtime --json` وأكّد Gateway النشط باستخدام `gateway status --deep --require-rpc`	أعد تشغيل Gateway المباشر بعد تغييرات التثبيت أو التحديث أو الإعدادات أو المصدر
تظهر تشخيصات تكرار ملكية القناة أو الأداة	شغّل `openclaw plugins list --enabled --verbose`، وافحص كل Plugin مشتبه به باستخدام `--runtime --json`، وقارن ملكية القنوات/الأدوات	عطّل أحد المالكين، أو أزل عمليات التثبيت القديمة، أو استخدم `preferOver` في البيان للاستبدال المتعمد
تشير الإعدادات إلى أن Plugin مفقود	راجع مخزون Plugin لمعرفة ما إذا كان مضمّنًا أو خارجيًا رسميًا أو متاحًا كمصدر فقط	ثبّت الحزمة الخارجية، أو فعّل Plugin المضمّن، أو أزل الإعدادات القديمة
الإعدادات غير صالحة أثناء التثبيت	اقرأ رسالة التحقق وشغّل `openclaw doctor --fix` إذا كانت تشير إلى حالة Plugin قديمة	يستطيع Doctor عزل إعدادات Plugin غير الصالحة بتعطيل الإدخال وإزالة الحمولة غير الصالحة
مسار Plugin محظور بسبب ملكية أو أذونات مشبوهة	افحص التشخيص الذي يسبق خطأ الإعدادات	أصلح ملكية نظام الملفات/أذوناته، ثم شغّل `openclaw plugins registry --refresh`
يحظر `OPENCLAW_NIX_MODE=1` أوامر دورة الحياة	تأكد من أن التثبيت مُدار بواسطة Nix	غيّر تحديد Plugin في مصدر Nix بدلًا من استخدام أوامر تعديل Plugin
يفشل استيراد التبعية في وقت التشغيل	تحقق مما إذا كان Plugin قد ثُبّت عبر npm/git/ClawHub أو حُمّل من مسار محلي	شغّل `openclaw plugins update <id>`، أو أعد تثبيت المصدر، أو ثبّت تبعيات Plugin المحلي بنفسك

عندما تظل إعدادات Plugin القديمة تسمّي Plugin قناة لم يعد قابلًا للاكتشاف، يخفض التحقق من الإعدادات مستوى مفتاح تلك القناة إلى تحذير بدلًا من فشل قطعي، كي يظل بإمكان بدء تشغيل Gateway خدمة جميع القنوات الأخرى. شغّل openclaw doctor --fix لإزالة إدخالات Plugin والقناة القديمة. تظل مفاتيح القنوات غير المعروفة التي لا يوجد دليل على ارتباطها بـ Plugin قديم مسببة لفشل التحقق، كي تظل الأخطاء الإملائية ظاهرة. عند استبدال قناة عمدًا، ينبغي أن يعلن Plugin المفضّل عن channelConfigs.<channel-id>.preferOver باستخدام معرّف Plugin القديم أو الأقل أولوية. إذا فُعّل كلا المكوّنين الإضافيين صراحةً، يحتفظ OpenClaw بهذا الطلب ويبلغ عن تشخيصات تكرار القناة/الأداة بدلًا من اختيار مالك بصمت. إذا أفادت حزمة مثبتة بأنها requires compiled runtime output for TypeScript entry ...، فهذا يعني أن الحزمة نُشرت من دون ملفات JavaScript التي يحتاج إليها OpenClaw في وقت التشغيل. حدّثها أو أعد تثبيتها بعد أن ينشر الناشر JavaScript المترجم برمجيًا، أو عطّل/ألغِ تثبيت Plugin حتى ذلك الحين.

ملكية مسار Plugin المحظور

إذا أشارت التشخيصات إلى blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) ثم أعقب التحقق ذلك بـ plugin present but blocked، فهذا يعني أن OpenClaw عثر على ملفات Plugin يملكها مستخدم Unix مختلف عن العملية التي تحمّلها. أبقِ إعدادات Plugin كما هي؛ أصلح ملكية نظام الملفات أو شغّل OpenClaw بالمستخدم نفسه الذي يملك دليل الحالة. بالنسبة إلى عمليات تثبيت Docker، تعمل الصورة الرسمية باسم node (uid 1000)، لذا ينبغي عادةً أن تكون أدلة إعدادات OpenClaw ومساحة العمل المربوطة من المضيف مملوكة لـ uid 1000:

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

إذا كنت تشغّل OpenClaw عمدًا بصلاحيات root، فأصلح جذر Plugin المُدار ليصبح مملوكًا لـ root بدلًا من ذلك:

sudo chown -R root:root /path/to/openclaw-config/npm

بعد إصلاح الملكية، أعد تشغيل openclaw doctor --fix أو openclaw plugins registry --refresh كي يتطابق سجل Plugin المحفوظ مع الملفات التي أُصلحت.

بطء إعداد أدوات Plugin

إذا بدت دورات الوكيل متوقفة أثناء تجهيز الأدوات، ففعّل تسجيل التتبع وابحث عن أسطر توقيت مصنع أدوات Plugin:

openclaw config set logging.level trace
openclaw logs --follow

ابحث عن:

[trace:plugin-tools] توقيتات المصنع ...

يسرد الملخص إجمالي وقت المصنع وأبطأ مصانع أدوات Plugin، بما في ذلك معرّف Plugin وأسماء الأدوات المعلنة وشكل النتيجة وما إذا كانت الأداة اختيارية. تُرفع الأسطر البطيئة إلى تحذيرات عندما يستغرق مصنع واحد 1s على الأقل، أو يستغرق إجمالي تجهيز مصانع أدوات Plugin مقدار 5s على الأقل. يخزّن OpenClaw نتائج مصانع أدوات Plugin الناجحة مؤقتًا لعمليات الحل المتكررة التي تستخدم سياق الطلب الفعلي نفسه. يتضمن مفتاح ذاكرة التخزين المؤقت إعدادات وقت التشغيل الفعلية، ومساحة العمل ومعرّف الوكيل، وسياسة صندوق العزل، وإعدادات المتصفح، وسياق التسليم، وهوية مقدم الطلب، وحالة الملكية، لذا تُعاد تشغيل المصانع التي تعتمد على هذه الحقول الموثوقة عند تغير السياق. إذا ظلت التوقيتات مرتفعة، فقد يكون Plugin ينفذ عملًا مكلفًا قبل إرجاع تعريفات أدواته. إذا هيمن Plugin واحد على التوقيت، فافحص تسجيلاته في وقت التشغيل:

openclaw plugins inspect <plugin-id> --runtime --json

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

ذو صلة

إدارة المكوّنات الإضافية - أمثلة أوامر العرض والتثبيت والتحديث وإلغاء التثبيت والنشر
openclaw plugins - مرجع CLI الكامل
مخزون Plugin - قائمة مُولّدة بالمكوّنات الإضافية المضمّنة والخارجية
مرجع Plugin - صفحات مرجعية مُولّدة لكل Plugin
المكوّنات الإضافية المجتمعية - سياسة الاكتشاف عبر ClawHub وطلبات السحب الخاصة بالوثائق
حل تبعيات Plugin - جذور التثبيت وسجلات السجل وحدود وقت التشغيل
بناء المكوّنات الإضافية - دليل تأليف Plugin أصلي
نظرة عامة على حزمة تطوير Plugin - التسجيل في وقت التشغيل والخطافات وحقول API
بيان Plugin - البيان وبيانات الحزمة الوصفية

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

المتطلبات

البدء السريع

الإعداد

اختيار مصدر التثبيت

سياسة تثبيت المشغّل

ضبط سياسة Plugins

فهم تنسيقات Plugins

خطافات Plugins

التحقق من Gateway النشط

استكشاف الأخطاء وإصلاحها

ملكية مسار Plugin المحظور

بطء إعداد أدوات Plugin

ذو صلة

​المتطلبات

​البدء السريع

​الإعداد

​اختيار مصدر التثبيت

​سياسة تثبيت المشغّل

​ضبط سياسة Plugins

​فهم تنسيقات Plugins

​خطافات Plugins

​التحقق من Gateway النشط

​استكشاف الأخطاء وإصلاحها

​ملكية مسار Plugin المحظور

​بطء إعداد أدوات Plugin

​ذو صلة

المتطلبات

البدء السريع

الإعداد

اختيار مصدر التثبيت

سياسة تثبيت المشغّل

ضبط سياسة Plugins

فهم تنسيقات Plugins

خطافات Plugins

التحقق من Gateway النشط

استكشاف الأخطاء وإصلاحها

ملكية مسار Plugin المحظور

بطء إعداد أدوات Plugin

ذو صلة