Plugins

إدارة Plugins الخاصة بـ Gateway، وحزم الخطافات، والحزم المتوافقة.

الأوامر

openclaw plugins listopenclaw plugins list --enabledopenclaw plugins list --verboseopenclaw plugins list --jsonopenclaw plugins search <query>openclaw plugins search <query> --limit 20openclaw plugins search <query> --jsonopenclaw plugins install <path-or-spec>openclaw plugins inspect <id>openclaw plugins inspect <id> --runtimeopenclaw plugins inspect <id> --jsonopenclaw plugins inspect --allopenclaw plugins info <id>openclaw plugins enable <id>openclaw plugins disable <id>openclaw plugins registryopenclaw plugins registry --refreshopenclaw plugins uninstall <id>openclaw plugins doctoropenclaw plugins update <id-or-npm-spec>openclaw plugins update --allopenclaw plugins marketplace list <marketplace>openclaw plugins marketplace list <marketplace> --json

للتحقيق في بطء التثبيت، أو الفحص، أو إلغاء التثبيت، أو تحديث السجل، شغّل الأمر مع OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1. يكتب التتبع أزمنة المراحل إلى stderr ويبقي مخرجات JSON قابلة للتحليل. راجع تصحيح الأخطاء.

التثبيت

openclaw plugins search "calendar"                   # search ClawHub pluginsopenclaw plugins install <package>                      # npm by defaultopenclaw plugins install clawhub:<package>              # ClawHub onlyopenclaw plugins install npm:<package>                  # npm onlyopenclaw plugins install npm-pack:<path.tgz>            # local npm pack through npm install semanticsopenclaw plugins install git:github.com/<owner>/<repo>  # git repoopenclaw plugins install git:github.com/<owner>/<repo>@<ref>openclaw plugins install <package> --force              # overwrite existing installopenclaw plugins install <package> --pin                # pin versionopenclaw plugins install <package> --dangerously-force-unsafe-installopenclaw plugins install <path>                         # local pathopenclaw plugins install <plugin>@<marketplace>         # marketplaceopenclaw plugins install <plugin> --marketplace <name>  # marketplace (explicit)openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>

يمكن للمشرفين الذين يختبرون التثبيتات وقت الإعداد تجاوز مصادر تثبيت Plugin التلقائية باستخدام متغيرات بيئة محمية. راجع تجاوزات تثبيت Plugin.

يستعلم plugins search من ClawHub عن حزم Plugin القابلة للتثبيت ويطبع أسماء حزم جاهزة للتثبيت. يبحث في حزم code-plugin وbundle-plugin، وليس Skills. استخدم openclaw skills search للبحث عن Skills في ClawHub.

تستخدم تثبيتات ClawHub محدد موقع صريحًا clawhub:<package>:

openclaw plugins install clawhub:openclaw-codex-app-serveropenclaw plugins install clawhub:openclaw-codex-app-server@1.2.3

تُثبَّت مواصفات Plugin الآمنة لـ npm المجردة من npm افتراضيًا أثناء مرحلة انتقال الإطلاق:

openclaw plugins install openclaw-codex-app-server

استخدم npm: لجعل الحل المقتصر على npm صريحًا:

openclaw plugins install npm:openclaw-codex-app-serveropenclaw plugins install npm:@scope/plugin-name@1.0.1

يتحقق OpenClaw من توافق واجهة API المعلنة للـ Plugin / الحد الأدنى لتوافق Gateway قبل التثبيت. عندما ينشر إصدار ClawHub المحدد قطعة ClawPack أثرية، ينزّل OpenClaw حزمة npm ذات الإصدار .tgz، ويتحقق من ترويسة ملخص ClawHub وملخص القطعة الأثرية، ثم يثبتها عبر مسار الأرشيف العادي. لا تزال إصدارات ClawHub الأقدم التي لا تحتوي على بيانات تعريف ClawPack تثبّت عبر مسار التحقق القديم لأرشيف الحزمة. تحتفظ التثبيتات المسجلة ببيانات تعريف مصدر ClawHub، ونوع القطعة الأثرية، وتكامل npm، وملخص shasum في npm، واسم tarball، وحقائق ملخص ClawPack للتحديثات اللاحقة. تحتفظ تثبيتات ClawHub غير ذات الإصدار بمواصفة مسجلة غير ذات إصدار كي يتمكن openclaw plugins update من تتبع إصدارات ClawHub الأحدث؛ أما محددات الإصدار أو الوسم الصريحة مثل clawhub:pkg@1.2.3 وclawhub:pkg@beta فتبقى مثبتة على ذلك المحدد.

اختصار السوق

استخدم اختصار plugin@marketplace عندما يكون اسم السوق موجودًا في ذاكرة التخزين المؤقت للسجل المحلي الخاصة بـ Claude في ~/.claude/plugins/known_marketplaces.json:

openclaw plugins marketplace list <marketplace-name>openclaw plugins install <plugin-name>@<marketplace-name>

استخدم --marketplace عندما تريد تمرير مصدر السوق صراحةً:

openclaw plugins install <plugin-name> --marketplace <marketplace-name>openclaw plugins install <plugin-name> --marketplace <owner/repo>openclaw plugins install <plugin-name> --marketplace https://github.com/<owner>/<repo>openclaw plugins install <plugin-name> --marketplace ./my-marketplace

بالنسبة إلى المسارات والأرشيفات المحلية، يكتشف OpenClaw تلقائيًا:

• Plugins أصلية لـ OpenClaw (openclaw.plugin.json)
• حزم متوافقة مع Codex (.codex-plugin/plugin.json)
• حزم متوافقة مع Claude (.claude-plugin/plugin.json أو تخطيط مكونات Claude الافتراضي)
• حزم متوافقة مع Cursor (.cursor-plugin/plugin.json)

القائمة

openclaw plugins listopenclaw plugins list --enabledopenclaw plugins list --verboseopenclaw plugins list --jsonopenclaw plugins search <query>openclaw plugins search <query> --limit 20openclaw plugins search <query> --json

plugins search هو بحث بعيد في كتالوج ClawHub. لا يفحص الحالة المحلية، ولا يغيّر الإعدادات، ولا يثبت الحزم، ولا يحمّل كود وقت تشغيل Plugin. تتضمن نتائج البحث اسم حزمة ClawHub، والعائلة، والقناة، والإصدار، والملخص، و تلميح تثبيت مثل openclaw plugins install clawhub:<package>.

للعمل على Plugin مضمّن داخل صورة Docker معبأة، اربط دليل مصدر Plugin فوق مسار المصدر المعبأ المطابق، مثل /app/extensions/synology-chat. سيكتشف OpenClaw طبقة المصدر المركّبة هذه قبل /app/dist/extensions/synology-chat؛ أما دليل المصدر المنسوخ فقط فيبقى غير فعّال، بحيث تظل التثبيتات المعبأة العادية تستخدم dist المجمّع.

لتصحيح أخطاء خطافات وقت التشغيل:

• يعرض openclaw plugins inspect <id> --runtime --json الخطافات المسجلة والتشخيصات من تمريرة فحص حمّلت الوحدة. لا يثبت فحص وقت التشغيل الاعتماديات أبدًا؛ استخدم openclaw doctor --fix لتنظيف حالة الاعتماديات القديمة أو استرداد Plugins القابلة للتنزيل المفقودة المشار إليها في الإعدادات.
• يؤكد openclaw gateway status --deep --require-rpc Gateway القابل للوصول، وتلميحات الخدمة/العملية، ومسار الإعدادات، وصحة RPC.
• تتطلب خطافات المحادثة غير المضمّنة (llm_input, llm_output, before_model_resolve, before_agent_reply, before_agent_run, before_agent_finalize, agent_end) القيمة plugins.entries.<id>.hooks.allowConversationAccess=true.

استخدم --link لتجنب نسخ دليل محلي (يضيفه إلى plugins.load.paths):

openclaw plugins install -l ./my-plugin

فهرس Plugin

بيانات تعريف تثبيت Plugin هي حالة مُدارة آليًا، وليست إعدادات مستخدم. تكتبها عمليات التثبيت والتحديث إلى plugins/installs.json ضمن دليل حالة OpenClaw النشط. خريطة installRecords ذات المستوى الأعلى هي المصدر الدائم لبيانات تعريف التثبيت، بما في ذلك السجلات الخاصة ببيانات Plugin الظاهرة المعطوبة أو المفقودة. مصفوفة plugins هي ذاكرة التخزين المؤقت لسجل البدء البارد المشتقة من البيانات الظاهرة. يتضمن الملف تحذيرًا بعدم التحرير ويستخدمه openclaw plugins update، وإلغاء التثبيت، والتشخيصات، وسجل Plugins البارد.

عندما يرى OpenClaw سجلات plugins.installs القديمة المشحونة في الإعدادات، تتعامل قراءات وقت التشغيل معها كمدخلات توافق دون إعادة كتابة openclaw.json. تنقل عمليات الكتابة الصريحة لـ Plugin وopenclaw doctor --fix تلك السجلات إلى فهرس Plugin وتزيل مفتاح الإعدادات عندما تكون كتابة الإعدادات مسموحة؛ إذا فشلت أي من عمليتي الكتابة، تُحفظ سجلات الإعدادات حتى لا تضيع بيانات تعريف التثبيت.

إلغاء التثبيت

openclaw plugins uninstall <id>openclaw plugins uninstall <id> --dry-runopenclaw plugins uninstall <id> --keep-files

يزيل uninstall سجلات Plugin من plugins.entries، وفهرس Plugin المحفوظ، وإدخالات قوائم السماح/المنع الخاصة بـ Plugin، وإدخالات plugins.load.paths المرتبطة عند الاقتضاء. ما لم يتم ضبط --keep-files، يزيل إلغاء التثبيت أيضًا دليل التثبيت المُدار المتتبَّع عندما يكون داخل جذر امتدادات Plugin في OpenClaw. بالنسبة إلى Plugins الذاكرة النشطة، تُعاد خانة الذاكرة إلى memory-core.

التحديث

openclaw plugins update <id-or-npm-spec>openclaw plugins update --allopenclaw plugins update <id-or-npm-spec> --dry-runopenclaw plugins update @openclaw/voice-callopenclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install

تنطبق التحديثات على تثبيتات Plugin المتتبَّعة في فهرس Plugin المُدار وتثبيتات حزم الخطافات المتتبَّعة في hooks.internal.installs.

الفحص

openclaw plugins inspect <id>openclaw plugins inspect <id> --runtimeopenclaw plugins inspect <id> --json

يعرض الفحص الهوية، وحالة التحميل، والمصدر، وإمكانات البيانات الظاهرة، وأعلام السياسة، والتشخيصات، وبيانات تعريف التثبيت، وإمكانات الحزمة، وأي دعم مكتشف لخوادم MCP أو LSP دون استيراد وقت تشغيل Plugin افتراضيًا. أضف --runtime لتحميل وحدة Plugin وتضمين الخطافات، والأدوات، والأوامر، والخدمات، وطرق Gateway، ومسارات HTTP المسجلة. يبلّغ فحص وقت التشغيل عن اعتماديات Plugin المفقودة مباشرةً؛ أما التثبيتات والإصلاحات فتبقى في openclaw plugins install وopenclaw plugins update وopenclaw doctor --fix.

عادةً ما تُثبّت أوامر CLI المملوكة للـ Plugin كمجموعات أوامر جذرية لـ openclaw، لكن يمكن للـ Plugins أيضًا تسجيل أوامر متداخلة تحت أصل أساسي مثل openclaw nodes. بعد أن يعرض inspect --runtime أمرًا ضمن cliCommands، شغّله في المسار المدرج؛ على سبيل المثال، يمكن التحقق من Plugin يسجل demo-git باستخدام openclaw demo-git ping.

يُصنّف كل Plugin حسب ما يسجله فعليًا في وقت التشغيل:

• plain-capability — نوع قدرة واحد (مثل Plugin خاص بالمزوّد فقط)
• hybrid-capability — أنواع قدرات متعددة (مثل النص + الكلام + الصور)
• hook-only — hooks فقط، بلا قدرات أو أسطح
• non-capability — أدوات/أوامر/خدمات لكن بلا قدرات

راجع أشكال Plugin لمزيد من المعلومات حول نموذج القدرات.

الفحص

openclaw plugins doctor

يُبلّغ doctor عن أخطاء تحميل Plugin، وتشخيصات البيان/الاكتشاف، وإشعارات التوافق. عندما يكون كل شيء سليمًا، يطبع No plugin issues detected.

إذا كان Plugin مكوّنًا موجودًا على القرص لكنه محظور بسبب فحوص أمان المسار الخاصة بالمحمّل، فإن التحقق من التكوين يُبقي إدخال Plugin ويُبلّغ عنه كـ present but blocked. أصلح تشخيص Plugin المحظور السابق، مثل ملكية المسار أو أذونات الكتابة للعامة، بدلًا من إزالة تكوين plugins.entries.<id> أو plugins.allow.

بالنسبة إلى حالات فشل شكل الوحدة مثل فقدان صادرات register/activate، أعد التشغيل مع OPENCLAW_PLUGIN_LOAD_DEBUG=1 لتضمين ملخص مضغوط لشكل الصادرات في مخرجات التشخيص.

السجل

openclaw plugins registryopenclaw plugins registry --refreshopenclaw plugins registry --json

سجل Plugins المحلي هو نموذج القراءة الباردة المستمر في OpenClaw لهوية Plugins المثبتة، وتمكينها، وبيانات تعريف المصدر، وملكية المساهمات. يمكن لبدء التشغيل العادي، والبحث عن مالك المزوّد، وتصنيف إعداد القناة، وجرد Plugins قراءته من دون استيراد وحدات تشغيل Plugins.

استخدم plugins registry لفحص ما إذا كان السجل المستمر موجودًا أو حديثًا أو قديمًا. استخدم --refresh لإعادة بنائه من فهرس Plugins المستمر، وسياسة التكوين، وبيانات تعريف البيان/الحزمة. هذا مسار إصلاح، وليس مسار تفعيل وقت التشغيل.

يُصلح openclaw doctor --fix أيضًا الانحراف المُدار في npm المجاور للسجل: إذا كانت حزمة @openclaw/* يتيمة أو مستعادة ضمن جذر npm المُدار الخاص بـ Plugins تحجب Plugin مضمّنًا، يزيل doctor تلك الحزمة القديمة ويعيد بناء السجل حتى يتحقق بدء التشغيل مقابل البيان المضمّن. يعيد Doctor أيضًا ربط حزمة المضيف openclaw داخل Plugins المُدارة عبر npm التي تُعلن peerDependencies.openclaw، بحيث تُحلّ استيرادات وقت التشغيل المحلية للحزمة مثل openclaw/plugin-sdk/* بعد التحديثات أو إصلاحات npm.

السوق

openclaw plugins marketplace list <source>openclaw plugins marketplace list <source> --json

تقبل قائمة السوق مسار سوق محليًا، أو مسار marketplace.json، أو اختصار GitHub مثل owner/repo، أو عنوان URL لمستودع GitHub، أو عنوان URL لـ git. يطبع --json تسمية المصدر المحلولة إضافة إلى بيان السوق المحلل وإدخالات Plugins.

ذات صلة

• بناء Plugins
• مرجع CLI
• ClawHub