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

​
المتطلبات

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

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

1

Find the plugin

ابحث في ClawHub عن حزم plugins العامة:
openclaw plugins search "calendar"
ClawHub هو سطح الاكتشاف الأساسي لـ plugins المجتمع. أثناء الانتقال عند الإطلاق، تظل مواصفات الحزم العادية المجردة تثبت من npm ما لم تطابق معرف Plugin رسميًا. مواصفات حزم @openclaw/* الخام التي تطابق plugins مضمنة تستخدم النسخة المضمنة من بناء OpenClaw الحالي. استخدم بادئة صريحة عندما تحتاج إلى مصدر محدد.
2

Install the plugin

# From ClawHub.
openclaw plugins install clawhub:<package>

# From npm.
openclaw plugins install npm:<package>

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

# From a local development checkout.
openclaw plugins install ./my-plugin
openclaw plugins install --link ./my-plugin
تعامل مع تثبيت plugins كما تتعامل مع تشغيل الكود. فضّل الإصدارات المثبتة عندما تحتاج إلى تثبيتات إنتاجية قابلة لإعادة الإنتاج.
3

Configure and enable it

اضبط الإعدادات الخاصة بـ Plugin ضمن plugins.entries.<id>.config. فعّل Plugin عندما لا يكون مفعّلًا بالفعل:
openclaw plugins enable <plugin-id>
إذا كان إعدادك يستخدم قائمة plugins.allow مقيّدة، فيجب أن يكون معرف Plugin المثبت موجودًا فيها قبل أن يتمكن Plugin من التحميل. يضيف openclaw plugins install المعرف المثبت إلى قائمة plugins.allow موجودة ويزيل المعرف نفسه من plugins.deny لكي يتمكن التثبيت الصريح من التحميل بعد إعادة التشغيل.
4

Let the Gateway reload

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

Verify runtime registration

openclaw plugins inspect <plugin-id> --runtime --json
استخدم --runtime عندما تحتاج إلى إثبات الأدوات، أو الخطافات، أو الخدمات، أو طرق Gateway، أو أوامر CLI المملوكة لـ Plugin المسجلة. أما inspect العادي فهو فحص بارد للبيان والسجل.

​
الإعداد

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

المصدراستخدمه عندمامثال
ClawHubتريد اكتشافًا أصيلًا لـ OpenClaw، وفحوصات، وبيانات وصفية للإصدارات، وتلميحات تثبيتopenclaw plugins install clawhub:<package>
npmتحتاج إلى سجل npm مباشر أو مسارات عمل dist-tagopenclaw plugins install npm:<package>
gitتحتاج إلى فرع، أو وسم، أو commit من مستودع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 مضمنًا، يستخدم OpenClaw ذلك المصدر المضمن. وإذا طابق معرف Plugin رسميًا خارجيًا، يستخدم OpenClaw كتالوج الحزم الرسمي. أما مواصفات الحزم العادية المجردة الأخرى فتثبت عبر 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 أو تحديثه. تتلقى السياسة بيانات وصفية إضافة إلى مسار المصدر المرحلي ويمكنها السماح بالتثبيت أو حظره. تغطي هذه السياسة مسارات تثبيت/تحديث Plugin عبر CLI والمدعومة من Gateway. تعمل خطافات Plugin before_install لاحقًا فقط داخل عمليات OpenClaw التي تُحمّل فيها خطافات Plugin، لذلك استخدم security.installPolicy لقرارات التثبيت المملوكة للمشغّل. يُقبل العلم المهمل --dangerously-force-unsafe-install للتوافق، لكنه لا يتجاوز سياسة التثبيت أو قائمة حظر تبعيات Plugin المدمجة في OpenClaw. راجع إعداد Skills لمخطط تنفيذ security.installPolicy المشترك الذي تستخدمه كل من Skills و plugins.

​
ضبط سياسة Plugin

الشكل الشائع لإعداد Plugin هو: 
{
  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 ويتخطى عمل اكتشاف/تحميل Plugin. تكون مراجع Plugin القديمة خاملة أثناء تفعيل ذلك؛ أعد تفعيل plugins قبل تشغيل تنظيف doctor عندما تريد إزالة المعرفات القديمة.
  • يتقدم plugins.deny على allow وعلى تفعيل Plugin الفردي.
  • plugins.allow قائمة سماح حصرية. تبقى الأدوات المملوكة لـ Plugin خارج قائمة السماح غير متاحة، حتى عندما يتضمن tools.allow القيمة "*".
  • يعطّل plugins.entries.<id>.enabled: false Plugin واحدًا مع الحفاظ على إعداده.
  • يضيف plugins.load.paths ملفات أو أدلة Plugin محلية صريحة. يجب أن تكون المسارات المحلية التي يديرها plugins install أدلة Plugin أو أرشيفات؛ استخدم plugins.load.paths لملفات Plugin المستقلة.
  • تكون plugins ذات أصل مساحة العمل معطلة افتراضيًا؛ فعّلها صراحة أو أضفها إلى قائمة السماح قبل استخدام كود مساحة العمل المحلي.
  • تتبع plugins المضمنة بياناتها الوصفية المدمجة الخاصة بالتفعيل الافتراضي/التعطيل الافتراضي ما لم يتجاوزها الإعداد صراحة.
  • يختار plugins.slots.<slot> Plugin واحدًا للفئات الحصرية مثل محركات الذاكرة والسياق. يفعّل اختيار الخانة Plugin المحدد إجباريًا لتلك الخانة باعتباره تفعيلًا صريحًا؛ ويمكنه التحميل حتى عندما كان سيحتاج خلاف ذلك إلى اشتراك صريح. ما زال plugins.deny و plugins.entries.<id>.enabled: false يحظرانه.
  • يمكن أن تتفعّل plugins المضمنة الاختيارية تلقائيًا عندما يذكر الإعداد أحد أسطحها المملوكة، مثل مرجع موفر/نموذج، أو إعداد قناة، أو خلفية CLI، أو وقت تشغيل حاوية وكيل.
  • يحافظ توجيه Codex من عائلة OpenAI على فصل حدود Plugin الخاصة بالموفر ووقت التشغيل: مراجع نماذج Codex القديمة هي إعداد قديم يصلحه doctor، بينما يملك Plugin codex المضمن وقت تشغيل خادم تطبيق Codex لمراجع وكلاء openai/* القياسية، وagentRuntime.id: "codex" الصريح، ومراجع codex/* القديمة.
عندما لا يكون plugins.allow معينًا وتُكتشف plugins غير مضمنة تلقائيًا من مساحة العمل أو جذور Plugin العامة، تسجل بدء التشغيل plugins.allow is empty; discovered non-bundled plugins may auto-load: .... يتضمن التحذير معرفات Plugin المكتشفة، وللقوائم القصيرة، مقتطف 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 عندما يبلغ التحقق من الإعداد عن معرفات Plugin قديمة، أو عدم تطابق بين قائمة السماح والأدوات، أو مسارات Plugin مضمنة قديمة.

​
فهم صيغ Plugin

يتعرف OpenClaw على صيغتين لـ Plugin:
الصيغةكيفية تحميلهااستخدمها عندما
Plugin أصلي لـ OpenClawopenclaw.plugin.json مع وحدة وقت تشغيل تُحمّل داخل العمليةتثبّت أو تبني قدرات وقت تشغيل خاصة بـ OpenClaw
حزمة متوافقةتخطيط Plugin خاص بـ Codex أو Claude أو Cursor يُربط بمخزون Plugin في OpenClawتعيد استخدام Skills أو أوامر أو خطافات أو بيانات وصفية للحزم متوافقة
تظهر كلتا الصيغتين في openclaw plugins list وopenclaw plugins inspect و openclaw plugins enable وopenclaw plugins disable. راجع حزم Plugin لحدود توافق الحزم و بناء plugins لتأليف Plugin أصلي.

​
خطافات Plugin

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

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

openclaw plugins list وopenclaw plugins inspect العاديان يقرآن حالة الإعدادات والـ manifest والسجل الباردة. ولا يثبتان أن Gateway قيد التشغيل بالفعل استورد رمز Plugin نفسه. عندما يبدو Plugin مثبتًا لكن حركة المحادثة المباشرة لا تستخدمه: 
openclaw gateway status --deep --require-rpc
openclaw plugins inspect <plugin-id> --runtime --json
openclaw gateway restart
تُعاد تشغيل Gateways المُدارة تلقائيًا بعد تغييرات تثبيت 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 في manifest للاستبدال المقصود
تقول الإعدادات إن 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 تلك القناة المدعومة بـ Plugin بدلًا من حظر كل القنوات الأخرى. شغّل openclaw doctor --fix لإزالة إدخالات Plugin والقنوات القديمة. ستظل مفاتيح القنوات غير المعروفة التي لا تملك دليلًا على Plugin قديم تفشل في التحقق حتى تبقى الأخطاء المطبعية ظاهرة. لاستبدال قناة مقصود، يجب أن يعلن Plugin المفضّل channelConfigs.<channel-id>.preferOver مع معرّف Plugin القديم أو الأقل أولوية. إذا كان كلا Pluginين مفعّلين صراحةً، يحتفظ OpenClaw بذلك الطلب ويبلغ عن تشخيصات تكرار القناة أو الأداة بدلًا من اختيار مالك واحد بصمت. إذا أبلغت حزمة مثبتة أنها requires compiled runtime output for TypeScript entry ...، فقد نُشرت الحزمة من دون ملفات JavaScript التي يحتاجها OpenClaw في وقت التشغيل. حدّث أو أعد التثبيت بعد أن ينشر الناشر JavaScript المترجم، أو عطّل/أزل تثبيت Plugin حتى ذلك الحين.

​
ملكية مسار 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] factory timings ...
يعرض الملخص إجمالي وقت المصنع وأبطأ مصانع أدوات Plugin، بما في ذلك معرّف Plugin، وأسماء الأدوات المعلنة، وشكل النتيجة، وما إذا كانت الأداة اختيارية. تُرقّى الأسطر البطيئة إلى تحذيرات عندما يستغرق مصنع واحد ثانية واحدة على الأقل أو يستغرق إعداد مصانع أدوات Plugin إجمالًا 5 ثوانٍ على الأقل. يخزّن OpenClaw نتائج مصانع أدوات Plugin الناجحة مؤقتًا لعمليات الحل المتكررة مع سياق الطلب الفعال نفسه. يتضمن مفتاح التخزين المؤقت إعدادات وقت التشغيل الفعالة، ومساحة العمل، ومعرّفات الوكيل/الجلسة، وسياسة sandbox، وإعدادات المتصفح، وسياق التسليم، وهوية الطالب، وحالة الملكية، لذلك يُعاد تشغيل المصانع التي تعتمد على تلك الحقول الموثوقة عندما يتغير السياق. إذا ظلت التوقيتات مرتفعة، فقد يكون Plugin ينفذ عملًا مكلفًا قبل إرجاع تعريفات أدواته. إذا هيمن Plugin واحد على التوقيت، فافحص تسجيلاته في وقت التشغيل: 
openclaw plugins inspect <plugin-id> --runtime --json
ثم حدّث ذلك Plugin أو أعد تثبيته أو عطّله. يجب على مؤلفي Plugin نقل تحميل التبعيات المكلف إلى مسار تنفيذ الأداة بدلًا من تنفيذه داخل مصنع الأداة. لجذور التبعيات، والتحقق من بيانات تعريف الحزمة، وسجلات السجل، وسلوك إعادة التحميل عند بدء التشغيل، والتنظيف القديم، راجع حل تبعيات Plugin.

​
ذات صلة