الإضافات

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

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

المتطلبات

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

البدء السريع

openclaw plugins search "calendar"

# من 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-pluginopenclaw plugins install --link ./my-plugin

openclaw plugins enable <plugin-id>

openclaw gateway restart

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

الإعداد

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

لمواصفات الحزم المجرّدة سلوك توافق خاص: فالاسم المجرّد الذي يطابق معرّف 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:

يظهر كلا التنسيقين في 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-rpcopenclaw plugins inspect <plugin-id> --runtime --jsonopenclaw gateway restart

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

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

عندما تظل إعدادات 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 traceopenclaw 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 - البيان وبيانات الحزمة الوصفية