الإضافات

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

الأوامر

openclaw plugins list [--enabled] [--verbose] [--json]openclaw plugins search <query> [--limit <n>] [--json]openclaw plugins install <path-or-spec> [--link] [--force] [--pin] [--marketplace <source>]openclaw plugins inspect <id> [--runtime] [--json]openclaw plugins inspect --all [--runtime] [--json]openclaw plugins info <id>                    # alias for inspectopenclaw plugins enable <id>openclaw plugins disable <id>openclaw plugins uninstall <id> [--dry-run] [--keep-files] [--force]openclaw plugins update <id-or-npm-spec> | --all [--dry-run]openclaw plugins registry [--refresh] [--json]openclaw plugins doctoropenclaw plugins init <id> [--name <name>] [--type tool|provider] [--directory <path>]openclaw plugins build [--entry <path>] [--check]openclaw plugins validate [--entry <path>]openclaw plugins marketplace entries [--offline] [--feed-profile <name>] [--json]openclaw plugins marketplace list <source> [--json]openclaw plugins marketplace refresh [--feed-profile <name>] [--expected-sha256 <sha256>] [--json]

للتحقيق في بطء التثبيت أو الفحص أو إلغاء التثبيت أو تحديث السجل، شغّل الأمر مع 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 وتنشئ النصين البرمجيين plugin:build و plugin:validate في package.json، حيث ينفّذان البناء ثم يستدعيان openclaw plugins build/validate.

يستورد plugins build نقطة الدخول المبنية، ويقرأ بياناتها الوصفية الثابتة للأدوات، ويكتب openclaw.plugin.json، ويحافظ على توافق openclaw.extensions في package.json. يتحقق 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 عامًا لموفّر نماذج متوافق مع OpenAI، مع تجهيز مصادقة مفتاح API، ونص برمجي npm run validate يشغّل clawhub package validate، وبيانات وصفية لحزمة ClawHub، وسير عمل GitHub Actions يُشغَّل يدويًا للنشر الموثوق مستقبلًا عبر GitHub OIDC. لا تنشئ قوالب الموفّرين Skills ولا تستخدم openclaw plugins build/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 tarballopenclaw plugins install git:github.com/<owner>/<repo>     # git repoopenclaw plugins install git:github.com/<owner>/<repo>@<ref>openclaw plugins install <path>                            # local path or archiveopenclaw plugins install -l <path>                         # link instead of copyopenclaw plugins install <plugin>@<marketplace>             # marketplace shorthandopenclaw plugins install <plugin> --marketplace <name>      # marketplace (explicit)openclaw plugins install <package> --force                  # overwrite existing installopenclaw plugins install <package> --pin                    # pin resolved npm versionopenclaw plugins install clawhub:<package> --acknowledge-clawhub-riskopenclaw plugins install <package> --dangerously-force-unsafe-install

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

يستعلم plugins search من ClawHub عن حزم code-plugin و bundle-plugin القابلة للتثبيت (وليس Skills؛ استخدم openclaw skills search لها). القيمة الافتراضية لـ --limit هي 20، وبحد أقصى 100. يقرأ الأمر الفهرس البعيد فقط، من دون فحص الحالة المحلية، أو تعديل الإعدادات، أو تثبيت الحزم، أو تحميل وقت تشغيل Plugin. تتضمن النتائج اسم حزمة ClawHub، والعائلة، والقناة، والإصدار، والملخص، وتلميح تثبيت مثل openclaw plugins install clawhub:<package>.

تستخدم عمليات التثبيت من ClawHub محدِّدًا صريحًا بصيغة clawhub:<package>:

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

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

استخدم -l/--link للإشارة إلى دليل Plugin محلي دون نسخه (يضيفه إلى plugins.load.paths):

openclaw plugins install -l ./my-plugin

لا يُدعم --link مع --force (تشير Plugins المرتبطة إلى مسار المصدر مباشرةً، لذلك لا يوجد ما يمكن استبداله في موضعه)، أو --marketplace، أو عمليات تثبيت git:، ويتطلب مسارًا محليًا موجودًا بالفعل.

العرض

openclaw plugins listopenclaw plugins list --enabledopenclaw plugins list --verboseopenclaw plugins list --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 منشأ التثبيت.

للعمل على 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 عنوان URL/ملف التعريف القابل للوصول لـ 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.

فهرس Plugins

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

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

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

openclaw plugins uninstall <id>openclaw plugins uninstall <id> --dry-runopenclaw plugins uninstall <id> --keep-filesopenclaw plugins uninstall <id> --force

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

يطبع uninstall معاينة لما سيُزال، ثم يعرض المطالبة Uninstall plugin "<id>"? قبل إجراء التغييرات. مرّر --force لتجاوز مطالبة التأكيد (وهو مفيد للبرامج النصية وعمليات التشغيل غير التفاعلية)؛ ومن دونه، يتطلب إلغاء التثبيت طرفية TTY تفاعلية. يطبع --dry-run المعاينة نفسها ثم يخرج من دون عرض مطالبة أو تغيير أي شيء.

التحديث

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

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

الفحص

openclaw plugins inspect <id>openclaw plugins inspect <id> --runtimeopenclaw plugins inspect <id> --jsonopenclaw plugins inspect --all

يعرض الفحص الهوية وحالة التحميل والمصدر وإمكانات البيان وأعلام السياسة وبيانات التشخيص وبيانات تعريف التثبيت وإمكانات الحزمة وأي دعم مكتشف لخادم 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 وفق ما يسجّله فعليًا في وقت التشغيل:

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

التشخيص

openclaw plugins doctor

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

إذا كان 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 مُدار لـ 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 تسمية المصدر التي جرى حلّها، بالإضافة إلى بيان السوق المحلّل وإدخالات Plugins.

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

ذو صلة

• إنشاء Plugins
• مرجع CLI
• ClawHub