الإضافات

إدارة إضافات 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>                    # اسم مستعار للأمر 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 إضافة أدوات مصغّرة بلغة TypeScript افتراضيًا. الوسيطة الأولى هي معرّف الإضافة؛ ويضبط --name اسم العرض. يستخدم OpenClaw المعرّف لدليل الإخراج الافتراضي وتسمية الحزمة. تستخدم قوالب الأدوات defineToolPlugin وتنشئ نصوص package.json البرمجية plugin:build و plugin:validate التي تبني ثم تستدعي openclaw plugins build/validate.

يستورد plugins build نقطة الدخول المبنية، ويقرأ بيانات تعريف أدواتها الثابتة، ويكتب openclaw.plugin.json، ويحافظ على محاذاة openclaw.extensions الخاص بـ package.json. يتحقق plugins validate من استمرار توافق البيان المنشأ وبيانات تعريف الحزمة وتصدير نقطة الدخول الحالية. راجع إضافات الأدوات للاطلاع على سير عمل التأليف الكامل.

يكتب القالب مصدر 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

تنشئ قوالب الموفّرين إضافة عامة لموفّر نماذج متوافق مع 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"                      # البحث عن إضافات ClawHubopenclaw plugins install @openclaw/<package>            # الكتالوج الرسمي الموثوقopenclaw plugins install <package>                       # حزمة npm عشوائيةopenclaw plugins install clawhub:<package>                # ClawHub فقطopenclaw plugins install npm:<package>                    # npm فقطopenclaw plugins install npm-pack:<path.tgz>               # أرشيف npm-pack محليopenclaw plugins install git:github.com/<owner>/<repo>     # مستودع gitopenclaw plugins install git:github.com/<owner>/<repo>@<ref>openclaw plugins install <path>                            # مسار أو أرشيف محليopenclaw plugins install -l <path>                         # الربط بدلًا من النسخopenclaw plugins install <plugin>@<marketplace>             # اختصار السوقopenclaw plugins install <plugin> --marketplace <name>      # السوق (صريح)openclaw plugins install <package> --force                  # تأكيد المصدر / استبدال الموجودopenclaw plugins install <package> --pin                    # تثبيت إصدار npm المحسومopenclaw plugins install clawhub:<package> --acknowledge-clawhub-riskopenclaw plugins install <package> --dangerously-force-unsafe-install

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

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

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

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

openclaw plugins install -l ./my-plugin

لا يُدعم --link مع عمليات تثبيت --marketplace أو git:، كما يتطلب مسارًا محليًا موجودًا بالفعل. لإنشاء رابط محلي غير تفاعلي، مرّر --force بعد مراجعة المصدر؛ فهو يؤكد المنشأ، لكنه لا ينسخ الدليل المرتبط أو يستبدله.

العرض

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

البيانات الوصفية لتثبيت Plugin هي حالة تديرها الآلة، وليست إعدادات مستخدم. تكتبها عمليات التثبيت والتحديث في قاعدة بيانات حالة SQLite المشتركة ضمن دليل حالة OpenClaw النشط. يخزّن صف installed_plugin_index بيانات وصفية دائمة لـinstallRecords، بما في ذلك سجلات بيانات 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 الدائم وإدخالات قوائم السماح/المنع الخاصة بـPlugin وإدخالات 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 @acme/demoopenclaw plugins update openclaw-codex-app-server --acknowledge-clawhub-riskopenclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install

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

الفحص

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 لمزيد من المعلومات عن نموذج الإمكانات.

Doctor

openclaw plugins doctor

doctor يعرض أخطاء تحميل الـ plugin، وتشخيصات البيان/الاكتشاف، وإشعارات التوافق، ومراجع إعدادات الـ plugin القديمة مثل خانات الـ plugin المفقودة. عندما تكون شجرة التثبيت وإعدادات الـ plugin سليمتين، فإنه يطبع 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 مُدار لأحد الـ plugins أو جذر 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