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 entriesopenclaw plugins marketplace entries --offlineopenclaw plugins marketplace entries --jsonopenclaw plugins marketplace list <marketplace>openclaw plugins marketplace list <marketplace> --jsonopenclaw plugins marketplace refreshopenclaw plugins marketplace refresh --feed-profile clawhub-public --jsonopenclaw plugins marketplace refresh --feed-url https://clawhub.ai/v1/feeds/plugins --expected-sha256 <sha256>openclaw plugins init my-tool --name "My Tool"openclaw plugins init my-provider --name "My Provider" --type provideropenclaw plugins init my-provider --name "My Provider" --type provider --directory ./my-provideropenclaw plugins build --entry ./dist/index.jsopenclaw plugins build --entry ./dist/index.js --checkopenclaw plugins validate --entry ./dist/index.js

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

المؤلف

openclaw plugins init stock-quotes --name "Stock Quotes"cd stock-quotesnpm run plugin:buildnpm run plugin:validate

ينشئ plugins init افتراضيًا Plugin أدوات TypeScript بسيطًا. الوسيط الأول هو معرّف Plugin؛ مرّر --name لاسم العرض. يستخدم OpenClaw المعرّف لمجلد الإخراج الافتراضي وتسمية الحزمة. تستخدم قوالب الأدوات defineToolPlugin. يستورد plugins build نقطة الدخول المبنية، ويقرأ بيانات تعريف الأدوات الثابتة، ويكتب openclaw.plugin.json، ويحافظ على اتساق package.json openclaw.extensions. يتحقق plugins validate من استمرار توافق البيان المُنشأ، وبيانات تعريف الحزمة، وتصدير نقطة الدخول الحالية. راجع Plugins الأدوات للاطلاع على سير عمل تأليف الأدوات الكامل.

يكتب القالب مصدر TypeScript لكنه ينشئ بيانات التعريف من نقطة الدخول المبنية ./dist/index.js حتى يعمل سير العمل أيضًا مع CLI المنشور. استخدم --entry <path> عندما لا تكون نقطة الدخول هي نقطة دخول الحزمة الافتراضية. استخدم plugins build --check في CI للفشل عندما تكون بيانات التعريف المُنشأة قديمة دون إعادة كتابة الملفات.

قالب المزوّد

openclaw plugins init acme-models --name "Acme Models" --type providercd acme-modelsnpm installnpm run buildnpm testnpm run validate

تنشئ قوالب المزوّد Plugin مزوّد نص/نموذج عامًا مع توصيل مفتاح API متوافق مع OpenAI، وسكربت npm run validate مدمج لـ clawhub package validate، وبيانات تعريف حزمة ClawHub، وسير عمل GitHub يُشغّل يدويًا للنشر الموثوق مستقبلًا عبر GitHub Actions OIDC. لا تنشئ قوالب المزوّد Skills ولا تستخدم openclaw plugins build أو openclaw plugins validate؛ فهذه الأوامر مخصصة لمسار بيانات التعريف المُنشأة لقالب الأدوات.

قبل النشر، استبدل عنوان URL الأساسي لواجهة API النائب، وكتالوج النماذج، ومسار الوثائق، ونص بيانات الاعتماد، ونسخة README بتفاصيل المزوّد الحقيقية. استخدم README المُنشأ للنشر الأول على ClawHub وإعداد الناشر الموثوق.

التثبيت

openclaw plugins search "calendar"                   # search ClawHub pluginsopenclaw plugins install <package>                      # source auto-detectionopenclaw 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 clawhub:<package> --acknowledge-clawhub-riskopenclaw 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

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

openclaw plugins install openclaw-codex-app-server

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

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

يفحص 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: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)

يجب أن تكون التثبيتات المحلية المُدارة دلائل Plugins أو أرشيفات. لا تُنسخ ملفات Plugin المستقلة .js و.mjs و.cjs و.ts إلى جذر Plugin المُدار بواسطة plugins install؛ أدرجها صراحةً في plugins.load.paths بدلًا من ذلك.

القائمة

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.allow is empty; discovered non-bundled plugins may auto-load: ...، فشغّل openclaw plugins list --enabled --verbose أو openclaw plugins inspect <id> مع معرّف Plugin مُدرج لتأكيد معرّفات Plugin ونسخ المعرّفات الموثوقة إلى plugins.allow في openclaw.json. عندما يستطيع التحذير سرد كل Plugin مكتشف، فإنه يطبع مقتطف plugins.allow جاهزًا للصق ويتضمن تلك المعرّفات مسبقًا. إذا حُمّل Plugin دون مصدر تثبيت/مسار تحميل، فافحص معرّف ذلك Plugin، ثم إما ثبّت المعرّف الموثوق في plugins.allow أو أعد تثبيت Plugin من مصدر موثوق حتى يسجل OpenClaw مصدر التثبيت.

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

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

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

• يعرض openclaw plugins inspect <id> --runtime --json hooks المسجلة والتشخيصات من مرور فحص محمّل كوحدة. لا يثبّت فحص وقت التشغيل التبعيات أبدًا؛ استخدم openclaw doctor --fix لتنظيف حالة التبعيات القديمة أو استعادة Plugins القابلة للتنزيل المفقودة والمشار إليها في الإعدادات.
• يؤكد openclaw gateway status --deep --require-rpc عنوان URL/الملف الشخصي القابل للوصول لـ Gateway، وتلميحات الخدمة/العملية، ومسار الإعدادات، وصحة RPC.
• تتطلب hooks المحادثة غير المضمّنة (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 لتجنب نسخ دليل Plugin محلي (يضيفه إلى plugins.load.paths):

openclaw plugins install -l ./my-plugin

يجب إدراج ملفات Plugin المستقلة في plugins.load.paths بدلًا من تثبيتها باستخدام plugins install أو وضعها مباشرةً في ~/.openclaw/extensions أو <workspace>/.openclaw/extensions. تحمّل تلك الجذور المكتشفة تلقائيًا دلائل حزم Plugin أو الحزم المتوافقة، بينما تُعامَل ملفات السكربتات في المستوى الأعلى كمساعدات محلية ويتم تخطيها.

فهرس Plugin

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

عندما يرى 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 --acknowledge-clawhub-riskopenclaw 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 افتراضيًا. يتضمن خرج JSON عقود بيان تعريف Plugin، مثل contracts.agentToolResultMiddleware وcontracts.trustedToolPolicies، حتى يتمكن المشغلون من تدقيق تصريحات الأسطح الموثوقة قبل تمكين 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 وفق ما يسجله فعليًا في وقت التشغيل:

• قدرة-عادية — نوع قدرة واحد (مثل Plugin لمزود فقط)
• قدرة-هجينة — عدة أنواع قدرات (مثل نص + كلام + صور)
• خطافات-فقط — خطافات فقط، بلا قدرات أو أسطح
• بلا-قدرات — أدوات/أوامر/خدمات لكن بلا قدرات

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

Doctor

openclaw plugins doctor

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

إذا كان 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

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

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

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

السوق

openclaw plugins marketplace entriesopenclaw plugins marketplace entries --offlineopenclaw plugins marketplace entries --jsonopenclaw plugins marketplace entries --feed-profile <name>openclaw plugins marketplace entries --feed-url <url>openclaw plugins marketplace list <source>openclaw plugins marketplace list <source> --jsonopenclaw plugins marketplace refreshopenclaw plugins marketplace refresh --feed-profile <name>openclaw plugins marketplace refresh --feed-url <url>openclaw plugins marketplace refresh --expected-sha256 <sha256> --json

يعرض plugins marketplace entries الإدخالات من موجز سوق OpenClaw المُكوَّن. يحاول افتراضيًا استخدام الموجز المستضاف، ثم يعود إلى أحدث لقطة مقبولة أو البيانات المضمّنة. استخدم --feed-profile <name> لقراءة ملف تعريف مُكوَّن محدد، و--feed-url <url> لقراءة عنوان URL صريح لموجز مستضاف، و--offline لقراءة أحدث لقطة مقبولة دون جلب الموجز.

يحدّث plugins marketplace refresh لقطة الموجز المستضاف المُكوَّن، ويبلّغ عمّا إذا كان OpenClaw قد قبل البيانات المستضافة، أو لقطة مستضافة، أو بيانات احتياطية مضمّنة. استخدم --expected-sha256 عندما يحتاج المستدعي إلى فشل الأمر ما لم تطابق حمولة مستضافة حديثة مجموعًا اختباريًا مثبّتًا.

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

يحمّل تحديث السوق موجز سوق OpenClaw مستضافًا ويحتفظ بالاستجابة المتحقق منها كلقطة محلية للموجز المستضاف. من دون خيارات، يستخدم ملف تعريف الموجز الافتراضي المُكوَّن. استخدم --feed-profile <name> لتحديث ملف تعريف مُكوَّن محدد، و--feed-url <url> لتحديث عنوان URL صريح لموجز مستضاف، و--expected-sha256 <sha256> لاشتراط مجموع اختباري مطابق للحمولة (sha256:<hex> أو ملخص سداسي عشري مجرد بطول 64 حرفًا)، و--json للحصول على مخرجات قابلة للقراءة آليًا. يجب ألا تتضمن عناوين URL الصريحة للموجزات المستضافة بيانات اعتماد، أو سلاسل استعلام، أو أجزاء. يمكن للتحديثات غير المثبّتة الإبلاغ عن نتيجة لقطة مستضافة أو نتيجة احتياطية مضمّنة دون إفشال الأمر. تفشل التحديثات المثبّتة ما لم تقبل حمولة مستضافة حديثة، وتفشل التحديثات المستضافة الناجحة إذا تعذّر على OpenClaw الاحتفاظ باللقطة المتحقق منها.

ذو صلة

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