Plugins

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

# الأوامر

openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
openclaw plugins search <query>
openclaw plugins search <query> --limit 20
openclaw plugins search <query> --json
openclaw plugins install <path-or-spec>
openclaw plugins inspect <id>
openclaw plugins inspect <id> --runtime
openclaw plugins inspect <id> --json
openclaw plugins inspect --all
openclaw plugins info <id>
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins registry
openclaw plugins registry --refresh
openclaw plugins uninstall <id>
openclaw plugins doctor
openclaw plugins update <id-or-npm-spec>
openclaw plugins update --all
openclaw plugins marketplace list <marketplace>
openclaw plugins marketplace list <marketplace> --json

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

# التثبيت

openclaw plugins search "calendar"                   # search ClawHub plugins
openclaw plugins install <package>                      # npm by default
openclaw plugins install clawhub:<package>              # ClawHub only
openclaw plugins install npm:<package>                  # npm only
openclaw plugins install npm-pack:<path.tgz>            # local npm pack through npm install semantics
openclaw plugins install git:github.com/<owner>/<repo>  # git repo
openclaw plugins install git:github.com/<owner>/<repo>@<ref>
openclaw plugins install <package> --force              # overwrite existing install
openclaw plugins install <package> --pin                # pin version
openclaw plugins install <package> --dangerously-force-unsafe-install
openclaw plugins install <path>                         # local path
openclaw plugins install <plugin>@<marketplace>         # marketplace
openclaw plugins install <plugin> --marketplace <name>  # marketplace (explicit)
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>

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

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

openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:[email protected]

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

openclaw plugins install openclaw-codex-app-server

استخدم npm: لجعل الحل الخاص بـ npm فقط صريحًا:

openclaw plugins install npm:openclaw-codex-app-server
openclaw plugins install npm:@scope/[email protected]

يتحقق OpenClaw من API الـ Plugin المعلنة / الحد الأدنى لتوافق Gateway قبل التثبيت. عندما ينشر إصدار ClawHub المحدد أثر ClawPack، ينزّل OpenClaw حزمة npm-pack ذات الإصدار .tgz، ويتحقق من رأس بصمة ClawHub وبصمة الأثر، ثم يثبّتها عبر مسار الأرشيف العادي. تظل إصدارات ClawHub الأقدم التي لا تحتوي على بيانات ClawPack الوصفية تُثبَّت عبر مسار التحقق القديم لأرشيف الحزمة. تحتفظ التثبيتات المسجّلة ببيانات مصدر ClawHub الوصفية، ونوع الأثر، وسلامة npm، وshasum الخاص بـ npm، واسم ملف tarball، وحقائق بصمة ClawPack للتحديثات اللاحقة. تحافظ تثبيتات ClawHub غير محددة الإصدار على مواصفة مسجّلة غير محددة الإصدار كي يتمكن openclaw plugins update من متابعة إصدارات ClawHub الأحدث؛ وتظل محددات الإصدار أو الوسم الصريحة مثل clawhub:[email protected] و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 تلقائيًا:

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

# القائمة

openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
openclaw plugins search <query>
openclaw plugins search <query> --limit 20
openclaw plugins search <query> --json

--enabledboolean

اعرض عناصر Plugin المفعّلة فقط.

--verboseboolean

بدّل من عرض الجدول إلى أسطر تفاصيل لكل Plugin تتضمن بيانات المصدر/الأصل/الإصدار/التفعيل الوصفية.

--jsonboolean

مخزون قابل للقراءة آليًا بالإضافة إلى تشخيصات السجل وحالة تثبيت تبعيات الحزم.

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 لتنظيف حالة التبعيات القديمة أو استعادة عناصر Plugin القابلة للتنزيل المفقودة والمشار إليها في الإعدادات.
• يؤكد 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، وإلغاء التثبيت، والتشخيصات، وسجل Plugin البارد.

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

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

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

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

# التحديث

openclaw plugins update <id-or-npm-spec>
openclaw plugins update --all
openclaw plugins update <id-or-npm-spec> --dry-run
openclaw plugins update @openclaw/voice-call
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install

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

# الفحص

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

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

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

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

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

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

# Doctor

openclaw plugins doctor

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

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

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

# السجل

openclaw plugins registry
openclaw plugins registry --refresh
openclaw plugins registry --json

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

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

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

# Marketplace

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

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

# ذات صلة

• بناء Plugins
• مرجع CLI
• Plugins المجتمع