chore(i18n): refresh ar translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
8c419dfd57
commit
ca31fcb9c0
@ -1,81 +1,82 @@
|
||||
---
|
||||
read_when:
|
||||
- تحتاج إلى فهم سبب تشغيل مهمة CI أو عدم تشغيلها
|
||||
- أنت تقوم بتصحيح أخطاء فحوصات GitHub Actions الفاشلة
|
||||
summary: مخطط مهام CI، وبوابات النطاق، وما يعادلها من الأوامر المحلية
|
||||
- أنت تُصحّح أخطاء فحوصات GitHub Actions الفاشلة
|
||||
summary: رسم مهام CI البياني، وبوابات النطاق، وما يعادلها من الأوامر المحلية
|
||||
title: مسار CI
|
||||
x-i18n:
|
||||
generated_at: "2026-04-22T04:21:43Z"
|
||||
generated_at: "2026-04-22T07:17:53Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: ae08bad6cbd0f2eced6c88a792a11bc1c2b1a2bfb003a56f70ff328a2739d3fc
|
||||
source_hash: fc7ec59123aee65634736320dbf1cf5cdfb08786a78cca82ce9596fedc68b3cc
|
||||
source_path: ci.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# مسار CI
|
||||
|
||||
يعمل CI عند كل push إلى `main` وعند كل pull request. ويستخدم تحديد نطاق ذكيًا لتخطي المهام المكلفة عندما تتغير مناطق غير مرتبطة فقط.
|
||||
يعمل CI عند كل دفع إلى `main` وعند كل طلب سحب. ويستخدم تحديد نطاق ذكيًا لتخطي المهام المكلفة عندما تكون التغييرات محصورة في أجزاء غير ذات صلة.
|
||||
|
||||
## نظرة عامة على المهام
|
||||
|
||||
| المهمة | الغرض | وقت التشغيل |
|
||||
| -------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------- |
|
||||
| `preflight` | اكتشاف التغييرات الخاصة بالوثائق فقط، والنطاقات المتغيرة، وPlugins المتغيرة، وبناء بيان CI | دائمًا في push وPR غير المسودين |
|
||||
| `security-scm-fast` | اكتشاف المفاتيح الخاصة وتدقيق workflow عبر `zizmor` | دائمًا في push وPR غير المسودين |
|
||||
| `security-dependency-audit` | تدقيق lockfile الإنتاجي بدون تبعيات مقابل تنبيهات npm | دائمًا في push وPR غير المسودين |
|
||||
| `security-fast` | مجمّع مطلوب لمهام الأمان السريعة | دائمًا في push وPR غير المسودين |
|
||||
| `build-artifacts` | بناء `dist/` وواجهة Control UI مرة واحدة، ورفع artifacts قابلة لإعادة الاستخدام للمهام التابعة | تغييرات ذات صلة بـ Node |
|
||||
| `checks-fast-core` | مسارات صحة Linux السريعة مثل فحوصات bundled/plugin-contract/protocol | تغييرات ذات صلة بـ Node |
|
||||
| `checks-fast-contracts-channels` | فحوصات عقود القنوات المجزأة مع نتيجة فحص مجمعة مستقرة | تغييرات ذات صلة بـ Node |
|
||||
| `checks-node-extensions` | شظايا اختبارات Plugin المضمّنة الكاملة عبر مجموعة extension | تغييرات ذات صلة بـ Node |
|
||||
| `checks-node-core-test` | شظايا اختبارات Node الأساسية، باستثناء مسارات القنوات وbundled والعقود وextension | تغييرات ذات صلة بـ Node |
|
||||
| `extension-fast` | اختبارات مركزة فقط لـ Plugins المضمّنة التي تغيّرت | عند اكتشاف تغييرات في extension |
|
||||
| `check` | ما يعادل البوابة المحلية الرئيسية المجزأة: أنواع الإنتاج وlint وguards وأنواع الاختبار وsmoke الصارم | تغييرات ذات صلة بـ Node |
|
||||
| `check-additional` | شظايا architecture وboundary وextension-surface guards وpackage-boundary وgateway-watch | تغييرات ذات صلة بـ Node |
|
||||
| `build-smoke` | اختبارات smoke لـ CLI المبني وsmoke ذاكرة بدء التشغيل | تغييرات ذات صلة بـ Node |
|
||||
| `checks` | مسارات Linux Node المتبقية: اختبارات القنوات وتوافق Node 22 الخاص بـ push فقط | تغييرات ذات صلة بـ Node |
|
||||
| `check-docs` | تنسيق الوثائق وlint وفحوصات الروابط المعطلة | عند تغير الوثائق |
|
||||
| `skills-python` | Ruff + pytest للـ Skills المعتمدة على Python | تغييرات ذات صلة بـ Python Skills |
|
||||
| `checks-windows` | مسارات الاختبار الخاصة بـ Windows | تغييرات ذات صلة بـ Windows |
|
||||
| `macos-node` | مسار اختبارات TypeScript على macOS باستخدام artifacts المبنية المشتركة | تغييرات ذات صلة بـ macOS |
|
||||
| `macos-swift` | lint وبناء واختبارات Swift لتطبيق macOS | تغييرات ذات صلة بـ macOS |
|
||||
| `android` | مصفوفة بناء Android واختباره | تغييرات ذات صلة بـ Android |
|
||||
| المهمة | الغرض | وقت التشغيل |
|
||||
| ----------------------------------- | ------------------------------------------------------------------------------------------ | ---------------------------------- |
|
||||
| `preflight` | اكتشاف التغييرات الخاصة بالوثائق فقط، والنطاقات المتغيرة، وPlugins المتغيرة، وبناء بيان CI | دائمًا في عمليات الدفع وطلبات السحب غير المسودة |
|
||||
| `security-scm-fast` | اكتشاف المفاتيح الخاصة وتدقيق سير العمل عبر `zizmor` | دائمًا في عمليات الدفع وطلبات السحب غير المسودة |
|
||||
| `security-dependency-audit` | تدقيق ملف قفل الإنتاج بدون تبعيات مقابل تنبيهات npm | دائمًا في عمليات الدفع وطلبات السحب غير المسودة |
|
||||
| `security-fast` | التجميع المطلوب لمهام الأمان السريعة | دائمًا في عمليات الدفع وطلبات السحب غير المسودة |
|
||||
| `build-artifacts` | بناء `dist/` وواجهة Control UI مرة واحدة، ورفع المخرجات القابلة لإعادة الاستخدام للمهام اللاحقة | التغييرات ذات الصلة بـ Node |
|
||||
| `checks-fast-core` | مسارات صحة Linux السريعة مثل فحوصات bundled/plugin-contract/protocol | التغييرات ذات الصلة بـ Node |
|
||||
| `checks-fast-contracts-channels` | فحوصات عقود القنوات المجزأة مع نتيجة فحص تجميعية مستقرة | التغييرات ذات الصلة بـ Node |
|
||||
| `checks-node-extensions` | تجزئات اختبارات bundled-plugin الكاملة عبر مجموعة الامتدادات | التغييرات ذات الصلة بـ Node |
|
||||
| `checks-node-core-test` | تجزئات اختبارات Node الأساسية، باستثناء مسارات القنوات وbundled والعقود والامتدادات | التغييرات ذات الصلة بـ Node |
|
||||
| `extension-fast` | اختبارات مركزة على bundled plugins المتغيرة فقط | عند اكتشاف تغييرات في الامتدادات |
|
||||
| `check` | المعادل الرئيسي المحلي المجزأ: أنواع الإنتاج، وlint، والحواجز، وأنواع الاختبار، وstrict smoke | التغييرات ذات الصلة بـ Node |
|
||||
| `check-additional` | حواجز البنية والحدود وأسطح الامتدادات وحدود الحزم وتجزيئات gateway-watch | التغييرات ذات الصلة بـ Node |
|
||||
| `build-smoke` | اختبارات smoke للـ CLI المبني وsmoke لذاكرة بدء التشغيل | التغييرات ذات الصلة بـ Node |
|
||||
| `checks` | مسارات Linux Node المتبقية: اختبارات القنوات وتوافق Node 22 للدفع فقط | التغييرات ذات الصلة بـ Node |
|
||||
| `check-docs` | تنسيق الوثائق وlint وفحوصات الروابط المعطلة | عند تغير الوثائق |
|
||||
| `skills-python` | `Ruff` + `pytest` للـ Skills المعتمدة على Python | التغييرات ذات الصلة بـ Skills في Python |
|
||||
| `checks-windows` | مسارات اختبار خاصة بـ Windows | التغييرات ذات الصلة بـ Windows |
|
||||
| `macos-node` | مسار اختبار TypeScript على macOS باستخدام مخرجات البناء المشتركة | التغييرات ذات الصلة بـ macOS |
|
||||
| `macos-swift` | lint وبناء واختبارات Swift لتطبيق macOS | التغييرات ذات الصلة بـ macOS |
|
||||
| `android` | مصفوفة بناء واختبار Android | التغييرات ذات الصلة بـ Android |
|
||||
|
||||
## ترتيب الإخفاق السريع
|
||||
|
||||
تُرتَّب المهام بحيث تفشل الفحوصات الرخيصة قبل تشغيل المهام المكلفة:
|
||||
تُرتَّب المهام بحيث تفشل الفحوصات الرخيصة قبل تشغيل الفحوصات المكلفة:
|
||||
|
||||
1. يحدد `preflight` أي المسارات موجودة أصلًا. ومنطق `docs-scope` و`changed-scope` هو خطوات داخل هذه المهمة، وليس مهام مستقلة.
|
||||
2. تفشل `security-scm-fast` و`security-dependency-audit` و`security-fast` و`check` و`check-additional` و`check-docs` و`skills-python` بسرعة دون انتظار مهام artifact ومصفوفات المنصات الأثقل.
|
||||
3. يتداخل `build-artifacts` مع مسارات Linux السريعة حتى يتمكن المستهلكون التابعون من البدء بمجرد جاهزية البناء المشترك.
|
||||
4. بعد ذلك تتفرع مسارات المنصات وبيئات التشغيل الأثقل: `checks-fast-core` و`checks-fast-contracts-channels` و`checks-node-extensions` و`checks-node-core-test` و`extension-fast` و`checks` و`checks-windows` و`macos-node` و`macos-swift` و`android`.
|
||||
1. يحدد `preflight` أي المسارات موجودة أصلًا. ومنطق `docs-scope` و`changed-scope` عبارة عن خطوات داخل هذه المهمة، وليس مهام مستقلة.
|
||||
2. تفشل `security-scm-fast` و`security-dependency-audit` و`security-fast` و`check` و`check-additional` و`check-docs` و`skills-python` بسرعة من دون انتظار مهام المخرجات والمنصات الأثقل.
|
||||
3. تعمل `build-artifacts` بالتوازي مع مسارات Linux السريعة حتى تتمكن المهام اللاحقة من البدء بمجرد جاهزية البناء المشترك.
|
||||
4. بعد ذلك تتفرع مسارات المنصات وبيئة التشغيل الأثقل: `checks-fast-core` و`checks-fast-contracts-channels` و`checks-node-extensions` و`checks-node-core-test` و`extension-fast` و`checks` و`checks-windows` و`macos-node` و`macos-swift` و`android`.
|
||||
|
||||
يوجد منطق النطاق في `scripts/ci-changed-scope.mjs` وتغطيه اختبارات وحدة في `src/scripts/ci-changed-scope.test.ts`.
|
||||
ويعيد workflow المنفصل `install-smoke` استخدام سكربت النطاق نفسه عبر مهمة `preflight` الخاصة به. إذ يحسب `run_install_smoke` من إشارة changed-smoke الأضيق، لذلك لا يعمل Docker/install smoke إلا عند التغييرات ذات الصلة بالتثبيت والتغليف والحاويات.
|
||||
يوجد منطق النطاق في `scripts/ci-changed-scope.mjs` وتغطيه اختبارات وحدات في `src/scripts/ci-changed-scope.test.ts`.
|
||||
ويعيد سير العمل المنفصل `install-smoke` استخدام سكربت النطاق نفسه عبر مهمة `preflight` الخاصة به. إذ يحسب `run_install_smoke` انطلاقًا من إشارة changed-smoke الأضيق، لذلك لا يعمل Docker/install smoke إلا مع التغييرات ذات الصلة بالتثبيت والتغليف والحاويات.
|
||||
|
||||
يوجد منطق المسارات المتغيرة المحلية في `scripts/changed-lanes.mjs` ويُنفَّذ بواسطة `scripts/check-changed.mjs`. وهذه البوابة المحلية أكثر صرامة بشأن حدود architecture من نطاق منصة CI الواسع: فتغييرات الإنتاج الأساسية تشغّل typecheck للإنتاج الأساسي بالإضافة إلى اختبارات الأساس، وتغييرات اختبارات الأساس فقط تشغّل typecheck/اختبارات الأساس فقط، وتغييرات إنتاج extension تشغّل typecheck لإنتاج extension بالإضافة إلى اختبارات extension، وتغييرات اختبارات extension فقط تشغّل typecheck/اختبارات extension فقط. أما تغييرات Plugin SDK العامة أو plugin-contract فتوسّع التحقق ليشمل extension لأن extension تعتمد على هذه العقود الأساسية. وتُشغّل زيادات الإصدار التي تقتصر على بيانات الإصدار الوصفية فحوصات مستهدفة للإصدار/التهيئة/تبعيات الجذر. أما تغييرات الجذر/التهيئة غير المعروفة فتميل احتياطيًا إلى جميع المسارات.
|
||||
يوجد منطق المسارات المحلية المتغيرة في `scripts/changed-lanes.mjs` ويُنفَّذ بواسطة `scripts/check-changed.mjs`. وهذه البوابة المحلية أكثر صرامة فيما يتعلق بحدود البنية من نطاق منصة CI العام: تغييرات الإنتاج الأساسية تشغّل typecheck للإنتاج الأساسي بالإضافة إلى الاختبارات الأساسية، وتغييرات الاختبارات الأساسية فقط تشغّل typecheck للاختبارات الأساسية واختباراتها فقط، وتغييرات إنتاج الامتدادات تشغّل typecheck لإنتاج الامتدادات بالإضافة إلى اختبارات الامتدادات، وتغييرات اختبارات الامتدادات فقط تشغّل typecheck لاختبارات الامتدادات واختباراتها فقط. وتوسّع تغييرات Plugin SDK العامة أو plugin-contract التحقق ليشمل الامتدادات لأن الامتدادات تعتمد على هذه العقود الأساسية. أما زيادات الإصدار التي تقتصر على بيانات الإصدار الوصفية فتشغّل فحوصات مستهدفة للإصدار/الإعداد/تبعية الجذر. والتغييرات غير المعروفة في الجذر/الإعداد تنتقل احتياطيًا إلى جميع المسارات.
|
||||
|
||||
عند push، تضيف مصفوفة `checks` مسار `compat-node22` الخاص بـ push فقط. أما في pull requests، فيتم تخطي هذا المسار وتبقى المصفوفة مركزة على مسارات الاختبار/القنوات العادية.
|
||||
عند عمليات الدفع، تضيف مصفوفة `checks` مسار `compat-node22` الخاص بالدفع فقط. أما في طلبات السحب، فيُتخطى هذا المسار وتبقى المصفوفة مركزة على مسارات الاختبار/القنوات المعتادة.
|
||||
|
||||
تنقسم أبطأ عائلات اختبارات Node إلى شظايا include-file بحيث تبقى كل مهمة صغيرة: تقسم عقود القنوات تغطية registry والأساس إلى ثماني شظايا موزونة لكل منهما، وتنقسم اختبارات auto-reply reply command إلى أربع شظايا include-pattern، وتنقسم مجموعات auto-reply reply prefix الكبيرة الأخرى إلى شظيتين لكل منها. كما يفصل `check-additional` أيضًا بين أعمال package-boundary compile/canary وبين أعمال runtime topology الخاصة بـ gateway/architecture.
|
||||
تنقسم أبطأ عائلات اختبارات Node إلى تجزئات تعتمد على include-file حتى تبقى كل مهمة صغيرة: تنقسم عقود القنوات إلى تغطية registry وcore في ثمانية تجزئات موزونة لكل منهما، وتنقسم اختبارات أوامر الرد لاختبارات auto-reply إلى أربع تجزئات بأنماط include، بينما تنقسم مجموعات بادئات الرد الكبيرة الأخرى في auto-reply إلى تجزئتين لكل مجموعة. كما يفصل `check-additional` بين أعمال compile/canary الخاصة بحدود الحزم وبين أعمال topology الخاصة بوقت التشغيل gateway/architecture.
|
||||
|
||||
قد يضع GitHub علامة `cancelled` على المهام المستبدلة عندما يصل push أحدث إلى PR نفسه أو مرجع `main`. تعامل مع ذلك على أنه ضوضاء CI ما لم يكن التشغيل الأحدث للمرجع نفسه يفشل أيضًا. وتشير فحوصات الشظايا المجمعة صراحةً إلى حالة الإلغاء هذه بحيث يسهل تمييزها عن فشل الاختبار.
|
||||
قد يضع GitHub علامة `cancelled` على المهام المستبدلة عندما يصل دفع أحدث إلى المرجع نفسه في PR أو `main`. اعتبر ذلك ضجيجًا من CI ما لم يكن أحدث تشغيل للمرجع نفسه فاشلًا أيضًا. وتوضح فحوصات التجميع الخاصة بالتجزئات هذه الحالة الملغاة صراحةً حتى يسهل تمييزها عن فشل الاختبار.
|
||||
|
||||
## المشغلات
|
||||
|
||||
| المشغّل | المهام |
|
||||
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `blacksmith-16vcpu-ubuntu-2404` | `preflight` و`security-scm-fast` و`security-dependency-audit` و`security-fast` و`build-artifacts` وفحوصات Linux وفحوصات الوثائق وPython Skills و`android` |
|
||||
| `blacksmith-32vcpu-windows-2025` | `checks-windows` |
|
||||
| `blacksmith-12vcpu-macos-latest` | `macos-node` و`macos-swift` على `openclaw/openclaw`؛ أما forks فتعود إلى `macos-latest` |
|
||||
| المشغل | المهام |
|
||||
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `ubuntu-24.04` | `preflight`؛ كما يستخدم preflight الخاص بـ install-smoke أيضًا Ubuntu مستضافًا من GitHub حتى تتمكن مصفوفة Blacksmith من الاصطفاف مبكرًا |
|
||||
| `blacksmith-16vcpu-ubuntu-2404` | `security-scm-fast` و`security-dependency-audit` و`security-fast` و`build-artifacts` وفحوصات Linux وفحوصات الوثائق وSkills Python و`android` |
|
||||
| `blacksmith-32vcpu-windows-2025` | `checks-windows` |
|
||||
| `blacksmith-12vcpu-macos-latest` | `macos-node` و`macos-swift` على `openclaw/openclaw`؛ أما الـ forks فتعود إلى `macos-latest` |
|
||||
|
||||
## المكافئات المحلية
|
||||
## المعادلات المحلية
|
||||
|
||||
```bash
|
||||
pnpm changed:lanes # فحص مصنف المسارات المتغيرة المحلي لـ origin/main...HEAD
|
||||
pnpm check:changed # البوابة المحلية الذكية: typecheck/lint/tests المتغيرة حسب مسار الحدود
|
||||
pnpm check # البوابة المحلية السريعة: tsgo للإنتاج + lint مجزأ + fast guards متوازية
|
||||
pnpm changed:lanes # فحص مصنف المسارات المحلية المتغيرة لـ origin/main...HEAD
|
||||
pnpm check:changed # البوابة المحلية الذكية: typecheck/lint/اختبارات متغيرة حسب مسار الحدود
|
||||
pnpm check # البوابة المحلية السريعة: production tsgo + lint مجزأ + حواجز سريعة متوازية
|
||||
pnpm check:test-types
|
||||
pnpm check:timed # البوابة نفسها مع توقيتات لكل مرحلة
|
||||
pnpm build:strict-smoke
|
||||
@ -85,5 +86,5 @@ pnpm test # اختبارات vitest
|
||||
pnpm test:channels
|
||||
pnpm test:contracts:channels
|
||||
pnpm check:docs # تنسيق الوثائق + lint + الروابط المعطلة
|
||||
pnpm build # بناء dist عندما تكون مسارات CI artifact/build-smoke مهمة
|
||||
pnpm build # بناء dist عندما تكون مسارات CI الخاصة بالمخرجات/build-smoke مهمة
|
||||
```
|
||||
|
||||
@ -1,13 +1,13 @@
|
||||
---
|
||||
read_when:
|
||||
- تغيير سلوك مؤشرات الكتابة أو القيم الافتراضية
|
||||
- تغيير سلوك مؤشرات الكتابة أو الإعدادات الافتراضية لها
|
||||
summary: متى يعرض OpenClaw مؤشرات الكتابة وكيفية ضبطها
|
||||
title: مؤشرات الكتابة
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T12:41:44Z"
|
||||
generated_at: "2026-04-22T07:17:58Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 28c8c395a135fc0745181aab66a93582177e6acd0b3496debcbb98159a4f11dc
|
||||
source_hash: 2e7e8ca448b6706b6f53fcb6a582be6d4a84715c82dfde3d53abe4268af3ae0d
|
||||
source_path: concepts/typing-indicators.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -15,34 +15,35 @@ x-i18n:
|
||||
# مؤشرات الكتابة
|
||||
|
||||
تُرسل مؤشرات الكتابة إلى قناة الدردشة أثناء نشاط التشغيل. استخدم
|
||||
`agents.defaults.typingMode` للتحكم في **وقت** بدء الكتابة، واستخدم `typingIntervalSeconds`
|
||||
للتحكم في **مدى تكرار** تحديثها.
|
||||
`agents.defaults.typingMode` للتحكم في **متى** تبدأ الكتابة و`typingIntervalSeconds`
|
||||
للتحكم في **عدد المرات** التي يتم فيها تحديثها.
|
||||
|
||||
## القيم الافتراضية
|
||||
## الإعدادات الافتراضية
|
||||
|
||||
عندما تكون `agents.defaults.typingMode` **غير معيّنة**، يحتفظ OpenClaw بالسلوك القديم:
|
||||
عندما يكون `agents.defaults.typingMode` **غير مضبوط**، يحافظ OpenClaw على السلوك القديم:
|
||||
|
||||
- **الدردشات المباشرة**: تبدأ الكتابة فورًا بمجرد بدء حلقة النموذج.
|
||||
- **الدردشات الجماعية مع إشارة**: تبدأ الكتابة فورًا.
|
||||
- **الدردشات الجماعية من دون إشارة**: تبدأ الكتابة فقط عندما يبدأ بث نص الرسالة.
|
||||
- **تشغيلات heartbeat**: تكون الكتابة معطلة.
|
||||
- **الدردشات الجماعية بدون إشارة**: تبدأ الكتابة فقط عندما يبدأ تدفق نص الرسالة.
|
||||
- **عمليات Heartbeat**: تبدأ الكتابة عند بدء تشغيل Heartbeat إذا كان
|
||||
هدف Heartbeat المحسوم دردشة تدعم الكتابة ولم تكن الكتابة معطلة.
|
||||
|
||||
## الأوضاع
|
||||
|
||||
اضبط `agents.defaults.typingMode` على أحد القيم التالية:
|
||||
|
||||
- `never` — لا يوجد مؤشر كتابة مطلقًا.
|
||||
- `instant` — ابدأ الكتابة **بمجرد بدء حلقة النموذج**، حتى لو أعاد التشغيل
|
||||
لاحقًا رمز الرد الصامت فقط.
|
||||
- `thinking` — ابدأ الكتابة عند **أول delta للاستدلال** (يتطلب
|
||||
`reasoningLevel: "stream"` لذلك التشغيل).
|
||||
- `message` — ابدأ الكتابة عند **أول delta نصي غير صامت** (ويتجاهل
|
||||
رمز الصمت `NO_REPLY`).
|
||||
- `never` — لا توجد أي إشارة كتابة إطلاقًا.
|
||||
- `instant` — ابدأ الكتابة **بمجرد بدء حلقة النموذج**، حتى إذا كان التشغيل
|
||||
سيُرجع لاحقًا رمز الرد الصامت فقط.
|
||||
- `thinking` — ابدأ الكتابة عند **أول دلتا استدلال** (يتطلب
|
||||
`reasoningLevel: "stream"` لهذا التشغيل).
|
||||
- `message` — ابدأ الكتابة عند **أول دلتا نصية غير صامتة** (ويتجاهل
|
||||
الرمز الصامت `NO_REPLY`).
|
||||
|
||||
ترتيب "مدى سرعة تشغيله":
|
||||
`never` ← `message` ← `thinking` ← `instant`
|
||||
ترتيب “مدى سرعة التشغيل”:
|
||||
`never` → `message` → `thinking` → `instant`
|
||||
|
||||
## التكوين
|
||||
## الإعداد
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -53,7 +54,7 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
يمكنك تجاوز الوضع أو الوتيرة لكل جلسة:
|
||||
يمكنك تجاوز الوضع أو وتيرة التحديث لكل جلسة:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -66,11 +67,16 @@ x-i18n:
|
||||
|
||||
## ملاحظات
|
||||
|
||||
- لا يعرض وضع `message` الكتابة للردود الصامتة فقط عندما تكون الحمولة
|
||||
بالكامل هي رمز الصمت الدقيق (مثل `NO_REPLY` / `no_reply`،
|
||||
- وضع `message` لن يعرض الكتابة للردود الصامتة فقط عندما تكون
|
||||
الحمولة بالكامل هي الرمز الصامت المطابق تمامًا (على سبيل المثال `NO_REPLY` / `no_reply`،
|
||||
مع مطابقة غير حساسة لحالة الأحرف).
|
||||
- لا يعمل `thinking` إلا إذا كان التشغيل يبث الاستدلال (`reasoningLevel: "stream"`).
|
||||
وإذا لم يصدر النموذج deltas للاستدلال، فلن تبدأ الكتابة.
|
||||
- لا تعرض heartbeat الكتابة أبدًا، بغض النظر عن الوضع.
|
||||
إذا لم يصدر النموذج دلتا للاستدلال، فلن تبدأ الكتابة.
|
||||
- كتابة Heartbeat هي إشارة حيوية لهدف التسليم المحسوم. وهي
|
||||
تبدأ عند بدء تشغيل Heartbeat بدلًا من اتباع توقيت تدفق `message` أو `thinking`.
|
||||
اضبط `typingMode: "never"` لتعطيلها.
|
||||
- لا تعرض Heartbeats الكتابة عندما يكون `target: "none"`، أو عندما يتعذر
|
||||
حسم الهدف، أو عندما يكون تسليم الدردشة معطلًا لـ Heartbeat، أو عندما
|
||||
لا تدعم القناة الكتابة.
|
||||
- يتحكم `typingIntervalSeconds` في **وتيرة التحديث**، وليس وقت البدء.
|
||||
والقيمة الافتراضية هي 6 ثوانٍ.
|
||||
القيمة الافتراضية هي 6 ثوانٍ.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,39 +1,39 @@
|
||||
---
|
||||
read_when:
|
||||
- ضبط وتيرة نبضات الحياة أو رسائلها
|
||||
- اتخاذ قرار بين نبضات الحياة وcron للمهام المجدولة
|
||||
summary: رسائل استطلاع نبضات الحياة وقواعد الإشعارات
|
||||
title: نبضات الحياة
|
||||
- ضبط وتيرة Heartbeat أو الرسائل
|
||||
- اتخاذ قرار بين Heartbeat وCron للمهام المجدولة
|
||||
summary: رسائل استطلاع Heartbeat وقواعد الإشعارات
|
||||
title: Heartbeat
|
||||
x-i18n:
|
||||
generated_at: "2026-04-11T02:44:48Z"
|
||||
generated_at: "2026-04-22T07:17:52Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: e4485072148753076d909867a623696829bf4a82dcd0479b95d5d0cae43100b0
|
||||
source_hash: 13004e4e20b02b08aaf16f22cdf664d0b59da69446ecb30453db51ffdfd1d267
|
||||
source_path: gateway/heartbeat.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# نبضات الحياة (Gateway)
|
||||
# Heartbeat (Gateway)
|
||||
|
||||
> **نبضات الحياة أم Cron؟** راجع [الأتمتة والمهام](/ar/automation) للحصول على إرشادات حول وقت استخدام كل منهما.
|
||||
> **Heartbeat أم Cron؟** راجع [الأتمتة والمهام](/ar/automation) للحصول على إرشادات حول وقت استخدام كل منهما.
|
||||
|
||||
تشغّل نبضات الحياة **دورات دورية للوكيل** في الجلسة الرئيسية حتى يتمكن النموذج من
|
||||
إبراز أي شيء يحتاج إلى اهتمام من دون إغراقك بالرسائل.
|
||||
يشغّل Heartbeat **أدوار وكيل دورية** في الجلسة الرئيسية حتى يتمكن النموذج من
|
||||
إظهار أي شيء يحتاج إلى انتباه من دون إغراقك بالرسائل.
|
||||
|
||||
نبضات الحياة هي دورة مجدولة في الجلسة الرئيسية — وهي **لا** تنشئ سجلات [مهام في الخلفية](/ar/automation/tasks).
|
||||
سجلات المهام مخصصة للعمل المنفصل (عمليات ACP، والوكلاء الفرعيون، ووظائف cron المعزولة).
|
||||
Heartbeat هو دور مجدول في الجلسة الرئيسية — وهو **لا** ينشئ سجلات [مهام في الخلفية](/ar/automation/tasks).
|
||||
سجلات المهام مخصّصة للعمل المنفصل (عمليات ACP، والوكلاء الفرعيون، ووظائف Cron المعزولة).
|
||||
|
||||
استكشاف الأخطاء وإصلاحها: [المهام المجدولة](/ar/automation/cron-jobs#troubleshooting)
|
||||
|
||||
## بدء سريع (للمبتدئين)
|
||||
## البدء السريع (للمبتدئين)
|
||||
|
||||
1. اترك نبضات الحياة مفعلة (الإعداد الافتراضي هو `30m`، أو `1h` لمصادقة Anthropic OAuth/token، بما في ذلك إعادة استخدام Claude CLI) أو اضبط الوتيرة التي تريدها.
|
||||
1. اترك Heartbeat مفعّلًا (القيمة الافتراضية هي `30m`، أو `1h` لمصادقة Anthropic OAuth/الرمز المميز، بما في ذلك إعادة استخدام Claude CLI) أو اضبط وتيرتك الخاصة.
|
||||
2. أنشئ قائمة تحقق صغيرة في `HEARTBEAT.md` أو كتلة `tasks:` في مساحة عمل الوكيل (اختياري لكنه موصى به).
|
||||
3. حدّد إلى أين يجب أن تذهب رسائل نبضات الحياة (`target: "none"` هو الإعداد الافتراضي؛ اضبط `target: "last"` للتوجيه إلى آخر جهة اتصال).
|
||||
4. اختياري: فعّل تسليم الاستدلال الخاص بنبضات الحياة من أجل مزيد من الشفافية.
|
||||
5. اختياري: استخدم سياق bootstrap خفيفًا إذا كانت عمليات نبضات الحياة تحتاج فقط إلى `HEARTBEAT.md`.
|
||||
6. اختياري: فعّل الجلسات المعزولة لتجنب إرسال سجل المحادثة الكامل مع كل نبضة حياة.
|
||||
7. اختياري: قيّد نبضات الحياة بالساعات النشطة (بالتوقيت المحلي).
|
||||
3. حدّد المكان الذي يجب أن تذهب إليه رسائل Heartbeat (`target: "none"` هو الخيار الافتراضي؛ اضبط `target: "last"` للتوجيه إلى آخر جهة اتصال).
|
||||
4. اختياري: فعّل تسليم الاستدلال الخاص بـ Heartbeat لمزيد من الشفافية.
|
||||
5. اختياري: استخدم سياق تهيئة خفيف إذا كانت تشغيلات Heartbeat تحتاج فقط إلى `HEARTBEAT.md`.
|
||||
6. اختياري: فعّل الجلسات المعزولة لتجنب إرسال السجل الكامل للمحادثة مع كل Heartbeat.
|
||||
7. اختياري: قيّد Heartbeat بالساعات النشطة (بالتوقيت المحلي).
|
||||
|
||||
مثال على الإعداد:
|
||||
|
||||
@ -43,59 +43,59 @@ x-i18n:
|
||||
defaults: {
|
||||
heartbeat: {
|
||||
every: "30m",
|
||||
target: "last", // تسليم صريح إلى آخر جهة اتصال (الإعداد الافتراضي هو "none")
|
||||
directPolicy: "allow", // الافتراضي: السماح بالأهداف المباشرة/الرسائل الخاصة؛ اضبط "block" لمنعها
|
||||
lightContext: true, // اختياري: حقن `HEARTBEAT.md` فقط من ملفات bootstrap
|
||||
isolatedSession: true, // اختياري: جلسة جديدة في كل تشغيل (من دون سجل محادثة)
|
||||
target: "last", // تسليم صريح إلى آخر جهة اتصال (القيمة الافتراضية هي "none")
|
||||
directPolicy: "allow", // الافتراضي: السماح بالأهداف المباشرة/الرسائل الخاصة؛ اضبط "block" لكبتها
|
||||
lightContext: true, // اختياري: حقن HEARTBEAT.md فقط من ملفات التهيئة
|
||||
isolatedSession: true, // اختياري: جلسة جديدة لكل تشغيل (من دون سجل محادثة)
|
||||
// activeHours: { start: "08:00", end: "24:00" },
|
||||
// includeReasoning: true, // اختياري: إرسال رسالة `Reasoning:` منفصلة أيضًا
|
||||
// includeReasoning: true, // اختياري: أرسل أيضًا رسالة `Reasoning:` منفصلة
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## الإعدادات الافتراضية
|
||||
## القيم الافتراضية
|
||||
|
||||
- الفاصل الزمني: `30m` (أو `1h` عندما يكون وضع المصادقة المكتشف هو Anthropic OAuth/token، بما في ذلك إعادة استخدام Claude CLI). اضبط `agents.defaults.heartbeat.every` أو `agents.list[].heartbeat.every` لكل وكيل؛ استخدم `0m` للتعطيل.
|
||||
- الفاصل الزمني: `30m` (أو `1h` عندما يكون وضع المصادقة المكتشف هو Anthropic OAuth/مصادقة الرمز المميز، بما في ذلك إعادة استخدام Claude CLI). اضبط `agents.defaults.heartbeat.every` أو لكل وكيل `agents.list[].heartbeat.every`؛ استخدم `0m` للتعطيل.
|
||||
- نص المطالبة (قابل للتهيئة عبر `agents.defaults.heartbeat.prompt`):
|
||||
`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`
|
||||
- يتم إرسال مطالبة نبضات الحياة **حرفيًا** كرسالة مستخدم. وتتضمن مطالبة النظام
|
||||
قسمًا بعنوان “Heartbeat” فقط عندما تكون نبضات الحياة مفعلة للوكيل
|
||||
الافتراضي، ويكون التشغيل مميزًا داخليًا على هذا الأساس.
|
||||
- عند تعطيل نبضات الحياة باستخدام `0m`، تحذف العمليات العادية أيضًا `HEARTBEAT.md`
|
||||
من سياق bootstrap حتى لا يرى النموذج تعليمات مخصصة لنبضات الحياة فقط.
|
||||
- يتم التحقق من الساعات النشطة (`heartbeat.activeHours`) في المنطقة الزمنية المهيأة.
|
||||
وخارج النافذة المحددة، يتم تخطي نبضات الحياة حتى النبضة التالية داخل النافذة.
|
||||
- تُرسل مطالبة Heartbeat **حرفيًا** بوصفها رسالة المستخدم. وتتضمن
|
||||
مطالبة النظام قسمًا باسم “Heartbeat” فقط عندما تكون Heartbeat مفعّلة
|
||||
للوكيل الافتراضي، وعندما يتم تمييز التشغيل داخليًا.
|
||||
- عند تعطيل Heartbeat باستخدام `0m`، تحذف التشغيلات العادية أيضًا `HEARTBEAT.md`
|
||||
من سياق التهيئة حتى لا يرى النموذج تعليمات خاصة بـ Heartbeat فقط.
|
||||
- يتم التحقق من الساعات النشطة (`heartbeat.activeHours`) في المنطقة الزمنية المضبوطة.
|
||||
وخارج النافذة، يتم تخطي Heartbeat حتى النبضة التالية داخل النافذة.
|
||||
|
||||
## ما الغرض من مطالبة نبضات الحياة
|
||||
## الغرض من مطالبة Heartbeat
|
||||
|
||||
المطالبة الافتراضية عامة عمدًا:
|
||||
|
||||
- **المهام في الخلفية**: إن عبارة “Consider outstanding tasks” تدفع الوكيل إلى مراجعة
|
||||
المتابعات (الوارد، والتقويم، والتذكيرات، والعمل الموجود في الطابور) وإبراز أي شيء عاجل.
|
||||
- **الاطمئنان على الإنسان**: إن عبارة “Checkup sometimes on your human during day time” تدفع إلى
|
||||
إرسال رسالة خفيفة من حين لآخر مثل “هل تحتاج إلى شيء؟”، لكنها تتجنب الإزعاج ليلًا
|
||||
باستخدام منطقتك الزمنية المحلية المهيأة (راجع [/concepts/timezone](/ar/concepts/timezone)).
|
||||
- **المهام في الخلفية**: عبارة “Consider outstanding tasks” تدفع الوكيل إلى مراجعة
|
||||
المتابعات (البريد الوارد، والتقويم، والتذكيرات، والعمل المدرج في قائمة الانتظار) وإبراز أي شيء عاجل.
|
||||
- **التحقق مع الإنسان**: عبارة “Checkup sometimes on your human during day time” تدفع إلى
|
||||
إرسال رسالة خفيفة أحيانًا مثل “هل تحتاج إلى أي شيء؟”، لكنها تتجنب الإزعاج ليلًا
|
||||
باستخدام منطقتك الزمنية المحلية المضبوطة (راجع [/concepts/timezone](/ar/concepts/timezone)).
|
||||
|
||||
يمكن لنبضات الحياة التفاعل مع [المهام في الخلفية](/ar/automation/tasks) المكتملة، لكن تشغيل نبضات الحياة نفسه لا ينشئ سجل مهمة.
|
||||
يمكن لـ Heartbeat التفاعل مع [المهام في الخلفية](/ar/automation/tasks) المكتملة، لكن تشغيل Heartbeat نفسه لا ينشئ سجل مهمة.
|
||||
|
||||
إذا كنت تريد من نبضات الحياة أن تقوم بشيء محدد جدًا (مثل “check Gmail PubSub
|
||||
stats” أو “verify gateway health”)، فاضبط `agents.defaults.heartbeat.prompt` (أو
|
||||
إذا أردت أن ينفّذ Heartbeat شيئًا محددًا جدًا (مثل “تحقق من إحصاءات Gmail PubSub”
|
||||
أو “تحقق من سلامة Gateway”)، فاضبط `agents.defaults.heartbeat.prompt` (أو
|
||||
`agents.list[].heartbeat.prompt`) على نص مخصص (يُرسل حرفيًا).
|
||||
|
||||
## عقد الاستجابة
|
||||
|
||||
- إذا لم يكن هناك شيء يحتاج إلى اهتمام، فاستجب بـ **`HEARTBEAT_OK`**.
|
||||
- أثناء تشغيل نبضات الحياة، يتعامل OpenClaw مع `HEARTBEAT_OK` على أنه
|
||||
تأكيد عندما يظهر في **بداية** الرد أو **نهايته**. وتُزال هذه العلامة ويُحذف الرد
|
||||
- إذا لم يكن هناك ما يحتاج إلى انتباه، فردّ بـ **`HEARTBEAT_OK`**.
|
||||
- أثناء تشغيلات Heartbeat، يتعامل OpenClaw مع `HEARTBEAT_OK` بوصفه
|
||||
إقرارًا عندما يظهر في **بداية الرد أو نهايته**. تتم إزالة الرمز ويُسقط الرد
|
||||
إذا كان المحتوى المتبقي **≤ `ackMaxChars`** (الافتراضي: 300).
|
||||
- إذا ظهر `HEARTBEAT_OK` في **منتصف** الرد، فلا تتم معاملته
|
||||
- إذا ظهر `HEARTBEAT_OK` في **منتصف** الرد، فلن يُعامل
|
||||
معاملة خاصة.
|
||||
- بالنسبة إلى التنبيهات، **لا** تُضمّن `HEARTBEAT_OK`؛ أرجع نص التنبيه فقط.
|
||||
- في التنبيهات، **لا** تُضمّن `HEARTBEAT_OK`؛ أعد نص التنبيه فقط.
|
||||
|
||||
خارج نبضات الحياة، تتم إزالة أي `HEARTBEAT_OK` عارضة في بداية الرسالة/نهايتها
|
||||
ويُسجل ذلك؛ أما الرسالة التي تكون فقط `HEARTBEAT_OK` فتُحذف.
|
||||
خارج Heartbeat، تتم إزالة أي `HEARTBEAT_OK` عارض في بداية/نهاية الرسالة
|
||||
ويُسجل؛ والرسالة التي تكون فقط `HEARTBEAT_OK` تُسقط.
|
||||
|
||||
## الإعداد
|
||||
|
||||
@ -104,37 +104,37 @@ stats” أو “verify gateway health”)، فاضبط `agents.defaults.heartbe
|
||||
agents: {
|
||||
defaults: {
|
||||
heartbeat: {
|
||||
every: "30m", // الافتراضي: 30m (0m للتعطيل)
|
||||
every: "30m", // الافتراضي: 30m (0m يعطل)
|
||||
model: "anthropic/claude-opus-4-6",
|
||||
includeReasoning: false, // الافتراضي: false (تسليم رسالة `Reasoning:` منفصلة عند توفرها)
|
||||
lightContext: false, // الافتراضي: false؛ تجعل القيمة true السياق مقتصرًا على `HEARTBEAT.md` فقط من ملفات bootstrap في مساحة العمل
|
||||
isolatedSession: false, // الافتراضي: false؛ تجعل القيمة true كل نبضة حياة تعمل في جلسة جديدة (من دون سجل محادثة)
|
||||
target: "last", // الافتراضي: none | الخيارات: last | none | <channel id> (أساسي أو plugin، مثل "bluebubbles")
|
||||
includeReasoning: false, // الافتراضي: false (تسليم رسالة Reasoning: منفصلة عند توفرها)
|
||||
lightContext: false, // الافتراضي: false؛ true يُبقي فقط HEARTBEAT.md من ملفات تهيئة مساحة العمل
|
||||
isolatedSession: false, // الافتراضي: false؛ true يشغّل كل Heartbeat في جلسة جديدة (من دون سجل محادثة)
|
||||
target: "last", // الافتراضي: none | الخيارات: last | none | <channel id> (أساسي أو Plugin، مثل "bluebubbles")
|
||||
to: "+15551234567", // تجاوز اختياري خاص بالقناة
|
||||
accountId: "ops-bot", // معرّف قناة اختياري للحسابات المتعددة
|
||||
prompt: "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.",
|
||||
ackMaxChars: 300, // الحد الأقصى للأحرف المسموح بها بعد `HEARTBEAT_OK`
|
||||
ackMaxChars: 300, // الحد الأقصى للأحرف المسموح بها بعد HEARTBEAT_OK
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### النطاق والأولوية
|
||||
### النطاق والأسبقية
|
||||
|
||||
- يحدد `agents.defaults.heartbeat` سلوك نبضات الحياة العام.
|
||||
- يندمج `agents.list[].heartbeat` فوقه؛ وإذا كان لدى أي وكيل كتلة `heartbeat`، فإن **هؤلاء الوكلاء فقط** هم من يشغّلون نبضات الحياة.
|
||||
- يحدد `channels.defaults.heartbeat` إعدادات الرؤية الافتراضية لجميع القنوات.
|
||||
- يتجاوز `channels.<channel>.heartbeat` إعدادات القناة الافتراضية.
|
||||
- يتجاوز `channels.<channel>.accounts.<id>.heartbeat` (في القنوات متعددة الحسابات) الإعدادات على مستوى كل قناة.
|
||||
- يضبط `agents.defaults.heartbeat` سلوك Heartbeat العام.
|
||||
- يتم دمج `agents.list[].heartbeat` فوقه؛ وإذا كان لأي وكيل كتلة `heartbeat`، **فلن تشغّل Heartbeat إلا تلك الوكلاء فقط**.
|
||||
- يضبط `channels.defaults.heartbeat` القيم الافتراضية للظهور لكل القنوات.
|
||||
- يتجاوز `channels.<channel>.heartbeat` القيم الافتراضية الخاصة بالقنوات.
|
||||
- يتجاوز `channels.<channel>.accounts.<id>.heartbeat` (القنوات متعددة الحسابات) إعدادات كل قناة على حدة.
|
||||
|
||||
### نبضات الحياة لكل وكيل
|
||||
### Heartbeat لكل وكيل
|
||||
|
||||
إذا تضمّن أي إدخال في `agents.list[]` كتلة `heartbeat`، فإن **هؤلاء الوكلاء فقط**
|
||||
هم من يشغّلون نبضات الحياة. وتندمج الكتلة الخاصة بكل وكيل فوق `agents.defaults.heartbeat`
|
||||
(حتى تتمكن من تعيين إعدادات مشتركة مرة واحدة ثم تجاوزها لكل وكيل).
|
||||
إذا كانت أي خانة في `agents.list[]` تتضمن كتلة `heartbeat`، فإن **تلك الوكلاء فقط**
|
||||
هم الذين يشغّلون Heartbeat. ويتم دمج الكتلة الخاصة بكل وكيل فوق `agents.defaults.heartbeat`
|
||||
(لذلك يمكنك ضبط القيم الافتراضية المشتركة مرة واحدة والتجاوز لكل وكيل).
|
||||
|
||||
مثال: وكيلان، ولا يشغّل نبضات الحياة إلا الوكيل الثاني.
|
||||
مثال: وكيلان، والوكيل الثاني فقط هو الذي يشغّل Heartbeat.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -142,7 +142,7 @@ stats” أو “verify gateway health”)، فاضبط `agents.defaults.heartbe
|
||||
defaults: {
|
||||
heartbeat: {
|
||||
every: "30m",
|
||||
target: "last", // تسليم صريح إلى آخر جهة اتصال (الإعداد الافتراضي هو "none")
|
||||
target: "last", // تسليم صريح إلى آخر جهة اتصال (القيمة الافتراضية هي "none")
|
||||
},
|
||||
},
|
||||
list: [
|
||||
@ -164,7 +164,7 @@ stats” أو “verify gateway health”)، فاضبط `agents.defaults.heartbe
|
||||
|
||||
### مثال على الساعات النشطة
|
||||
|
||||
قيّد نبضات الحياة بساعات العمل في منطقة زمنية محددة:
|
||||
قيّد Heartbeat بساعات العمل في منطقة زمنية محددة:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -172,11 +172,11 @@ stats” أو “verify gateway health”)، فاضبط `agents.defaults.heartbe
|
||||
defaults: {
|
||||
heartbeat: {
|
||||
every: "30m",
|
||||
target: "last", // تسليم صريح إلى آخر جهة اتصال (الإعداد الافتراضي هو "none")
|
||||
target: "last", // تسليم صريح إلى آخر جهة اتصال (القيمة الافتراضية هي "none")
|
||||
activeHours: {
|
||||
start: "09:00",
|
||||
end: "22:00",
|
||||
timezone: "America/New_York", // اختياري؛ يستخدم `userTimezone` إذا كان مضبوطًا، وإلا فيستخدم المنطقة الزمنية للمضيف
|
||||
timezone: "America/New_York", // اختياري؛ يستخدم userTimezone إن كان مضبوطًا، وإلا يستخدم المنطقة الزمنية للمضيف
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -184,19 +184,19 @@ stats” أو “verify gateway health”)، فاضبط `agents.defaults.heartbe
|
||||
}
|
||||
```
|
||||
|
||||
خارج هذه النافذة (قبل التاسعة صباحًا أو بعد العاشرة مساءً بتوقيت الساحل الشرقي)، يتم تخطي نبضات الحياة. وستعمل النبضة المجدولة التالية داخل النافذة بشكل طبيعي.
|
||||
خارج هذه النافذة (قبل 9 صباحًا أو بعد 10 مساءً بالتوقيت الشرقي)، يتم تخطي Heartbeat. وستعمل النبضة المجدولة التالية داخل النافذة بشكل طبيعي.
|
||||
|
||||
### إعداد 24/7
|
||||
|
||||
إذا كنت تريد تشغيل نبضات الحياة طوال اليوم، فاستخدم أحد هذين النمطين:
|
||||
إذا أردت تشغيل Heartbeat طوال اليوم، فاستخدم أحد هذه الأنماط:
|
||||
|
||||
- احذف `activeHours` بالكامل (من دون تقييد بنافذة زمنية؛ وهذا هو السلوك الافتراضي).
|
||||
- احذف `activeHours` بالكامل (من دون تقييد نافذة زمنية؛ وهذا هو السلوك الافتراضي).
|
||||
- اضبط نافذة يوم كامل: `activeHours: { start: "00:00", end: "24:00" }`.
|
||||
|
||||
لا تضبط `start` و`end` على الوقت نفسه (مثلًا `08:00` إلى `08:00`).
|
||||
يُعامل ذلك على أنه نافذة بعرض صفري، لذلك تُتخطى نبضات الحياة دائمًا.
|
||||
لا تضبط القيمتين `start` و`end` على الوقت نفسه (على سبيل المثال `08:00` إلى `08:00`).
|
||||
فهذا يُعامل على أنه نافذة بعرض صفري، لذلك يتم دائمًا تخطي Heartbeat.
|
||||
|
||||
### مثال على الحسابات المتعددة
|
||||
### مثال على تعدد الحسابات
|
||||
|
||||
استخدم `accountId` لاستهداف حساب محدد في القنوات متعددة الحسابات مثل Telegram:
|
||||
|
||||
@ -209,7 +209,7 @@ stats” أو “verify gateway health”)، فاضبط `agents.defaults.heartbe
|
||||
heartbeat: {
|
||||
every: "1h",
|
||||
target: "telegram",
|
||||
to: "12345678:topic:42", // اختياري: التوجيه إلى موضوع/سلسلة رسائل محددة
|
||||
to: "12345678:topic:42", // اختياري: التوجيه إلى topic/thread محدد
|
||||
accountId: "ops-bot",
|
||||
},
|
||||
},
|
||||
@ -227,85 +227,88 @@ stats” أو “verify gateway health”)، فاضبط `agents.defaults.heartbe
|
||||
|
||||
### ملاحظات الحقول
|
||||
|
||||
- `every`: الفاصل الزمني لنبضات الحياة (سلسلة مدة؛ ووحدة القياس الافتراضية = الدقائق).
|
||||
- `model`: تجاوز اختياري للنموذج في تشغيلات نبضات الحياة (`provider/model`).
|
||||
- `includeReasoning`: عند التفعيل، يُسلَّم أيضًا رسالة `Reasoning:` المنفصلة عند توفرها (بنفس صيغة `/reasoning on`).
|
||||
- `lightContext`: عند تفعيلها، تستخدم تشغيلات نبضات الحياة سياق bootstrap خفيفًا وتحتفظ فقط بـ `HEARTBEAT.md` من ملفات bootstrap في مساحة العمل.
|
||||
- `isolatedSession`: عند تفعيلها، تعمل كل نبضة حياة في جلسة جديدة من دون أي سجل محادثة سابق. وتستخدم نمط العزل نفسه المستخدم في cron مع `sessionTarget: "isolated"`. وهذا يقلل بصورة كبيرة تكلفة التوكن لكل نبضة حياة. اجمعها مع `lightContext: true` لتحقيق أكبر قدر من التوفير. ومع ذلك، يظل توجيه التسليم يستخدم سياق الجلسة الرئيسية.
|
||||
- `session`: مفتاح جلسة اختياري لتشغيلات نبضات الحياة.
|
||||
- `every`: فاصل Heartbeat الزمني (سلسلة مدة؛ وحدة القياس الافتراضية = الدقائق).
|
||||
- `model`: تجاوز اختياري للنموذج لتشغيلات Heartbeat (`provider/model`).
|
||||
- `includeReasoning`: عند تفعيله، يسلّم أيضًا رسالة `Reasoning:` المنفصلة عند توفرها (بنفس صيغة `/reasoning on`).
|
||||
- `lightContext`: عند تفعيله، تستخدم تشغيلات Heartbeat سياق تهيئة خفيفًا وتحتفظ فقط بـ `HEARTBEAT.md` من ملفات تهيئة مساحة العمل.
|
||||
- `isolatedSession`: عند تفعيله، تعمل كل تشغيلات Heartbeat في جلسة جديدة من دون أي سجل محادثة سابق. ويستخدم نمط العزل نفسه الموجود في Cron `sessionTarget: "isolated"`. وهذا يقلل بشكل كبير تكلفة الرموز لكل Heartbeat. اجمعه مع `lightContext: true` لتحقيق أقصى توفير. ويظل توجيه التسليم يستخدم سياق الجلسة الرئيسية.
|
||||
- `session`: مفتاح جلسة اختياري لتشغيلات Heartbeat.
|
||||
- `main` (الافتراضي): الجلسة الرئيسية للوكيل.
|
||||
- مفتاح جلسة صريح (انسخه من `openclaw sessions --json` أو من [CLI الجلسات](/cli/sessions)).
|
||||
- تنسيقات مفاتيح الجلسات: راجع [الجلسات](/ar/concepts/session) و[المجموعات](/ar/channels/groups).
|
||||
- مفتاح جلسة صريح (انسخه من `openclaw sessions --json` أو من [sessions CLI](/cli/sessions)).
|
||||
- صيغ مفاتيح الجلسة: راجع [الجلسات](/ar/concepts/session) و[المجموعات](/ar/channels/groups).
|
||||
- `target`:
|
||||
- `last`: التسليم إلى آخر قناة خارجية مستخدمة.
|
||||
- قناة صريحة: أي قناة مهيأة أو معرّف plugin، مثل `discord` أو `matrix` أو `telegram` أو `whatsapp`.
|
||||
- `none` (الافتراضي): تشغيل نبضات الحياة لكن **من دون تسليم** خارجي.
|
||||
- قناة صريحة: أي قناة أو معرّف Plugin مهيأ، على سبيل المثال `discord` أو `matrix` أو `telegram` أو `whatsapp`.
|
||||
- `none` (الافتراضي): شغّل Heartbeat لكن **لا تسلّمه** خارجيًا.
|
||||
- `directPolicy`: يتحكم في سلوك التسليم المباشر/الرسائل الخاصة:
|
||||
- `allow` (الافتراضي): السماح بتسليم نبضات الحياة المباشر/عبر الرسائل الخاصة.
|
||||
- `block`: منع التسليم المباشر/عبر الرسائل الخاصة (`reason=dm-blocked`).
|
||||
- `to`: تجاوز اختياري للمستلم (معرّف خاص بالقناة، مثل E.164 لـ WhatsApp أو معرّف دردشة Telegram). وبالنسبة إلى مواضيع/سلاسل Telegram، استخدم `<chatId>:topic:<messageThreadId>`.
|
||||
- `accountId`: معرّف حساب اختياري للقنوات متعددة الحسابات. عند استخدام `target: "last"`، يُطبَّق معرّف الحساب على آخر قناة محلولة إذا كانت تدعم الحسابات؛ وإلا فيتم تجاهله. وإذا لم يطابق معرّف الحساب حسابًا مهيأً للقناة المحلولة، فسيتم تخطي التسليم.
|
||||
- `allow` (الافتراضي): السماح بتسليم Heartbeat المباشر/الرسائل الخاصة.
|
||||
- `block`: كبت التسليم المباشر/الرسائل الخاصة (`reason=dm-blocked`).
|
||||
- `to`: تجاوز اختياري للمستلم (معرّف خاص بالقناة، مثل E.164 لـ WhatsApp أو معرّف دردشة Telegram). بالنسبة إلى topics/threads في Telegram، استخدم `<chatId>:topic:<messageThreadId>`.
|
||||
- `accountId`: معرّف حساب اختياري للقنوات متعددة الحسابات. عندما يكون `target: "last"`، يُطبّق معرّف الحساب على آخر قناة محلولة إذا كانت تدعم الحسابات؛ وإلا فيتم تجاهله. وإذا لم يطابق معرّف الحساب حسابًا مهيأً للقناة المحلولة، فسيتم تخطي التسليم.
|
||||
- `prompt`: يتجاوز نص المطالبة الافتراضي (من دون دمج).
|
||||
- `ackMaxChars`: الحد الأقصى للأحرف المسموح بها بعد `HEARTBEAT_OK` قبل التسليم.
|
||||
- `suppressToolErrorWarnings`: عند تفعيلها، تُمنع حمولات تحذيرات أخطاء الأدوات أثناء تشغيلات نبضات الحياة.
|
||||
- `activeHours`: يقيّد تشغيلات نبضات الحياة بنافذة زمنية. وهو كائن يحتوي على `start` (بتنسيق HH:MM، شامل؛ استخدم `00:00` لبداية اليوم)، و`end` (بتنسيق HH:MM، غير شامل؛ ويُسمح بـ `24:00` لنهاية اليوم)، و`timezone` اختياري.
|
||||
- إذا حُذف أو كانت قيمته `"user"`: يستخدم `agents.defaults.userTimezone` إذا كان مضبوطًا، وإلا يعود إلى المنطقة الزمنية لنظام المضيف.
|
||||
- `suppressToolErrorWarnings`: عند تفعيله، يكبت حمولات تحذير أخطاء الأدوات أثناء تشغيلات Heartbeat.
|
||||
- `activeHours`: يقيّد تشغيلات Heartbeat بنافذة زمنية. وهو كائن يحتوي على `start` (HH:MM، شامل؛ استخدم `00:00` لبداية اليوم)، و`end` (HH:MM غير شامل؛ يُسمح بـ `24:00` لنهاية اليوم)، و`timezone` اختياري.
|
||||
- إذا حُذف أو كان `"user"`: يستخدم `agents.defaults.userTimezone` إن كان مضبوطًا، وإلا يعود إلى المنطقة الزمنية لنظام المضيف.
|
||||
- `"local"`: يستخدم دائمًا المنطقة الزمنية لنظام المضيف.
|
||||
- أي معرّف IANA (مثل `America/New_York`): يُستخدم مباشرة؛ وإذا كان غير صالح، يعود إلى سلوك `"user"` المذكور أعلاه.
|
||||
- يجب ألا تكون `start` و`end` متساويتين بالنسبة إلى نافذة نشطة؛ إذ تُعامل القيم المتساوية كنافذة بعرض صفري (دائمًا خارج النافذة).
|
||||
- خارج النافذة النشطة، يتم تخطي نبضات الحياة حتى النبضة التالية داخل النافذة.
|
||||
- أي معرّف IANA (مثل `America/New_York`): يُستخدم مباشرة؛ وإذا كان غير صالح، فسيعود إلى سلوك `"user"` المذكور أعلاه.
|
||||
- يجب ألا تكون `start` و`end` متساويتين بالنسبة إلى نافذة نشطة؛ فالقيم المتساوية تُعامل على أنها عرض صفري (دائمًا خارج النافذة).
|
||||
- خارج النافذة النشطة، يتم تخطي Heartbeat حتى النبضة التالية داخل النافذة.
|
||||
|
||||
## سلوك التسليم
|
||||
|
||||
- تعمل نبضات الحياة في الجلسة الرئيسية للوكيل افتراضيًا (`agent:<id>:<mainKey>`)،
|
||||
أو `global` عندما تكون `session.scope = "global"`. اضبط `session` لتجاوز ذلك إلى
|
||||
- تعمل Heartbeat في الجلسة الرئيسية للوكيل افتراضيًا (`agent:<id>:<mainKey>`)،
|
||||
أو `global` عندما يكون `session.scope = "global"`. اضبط `session` لتجاوزه إلى
|
||||
جلسة قناة محددة (Discord/WhatsApp/إلخ).
|
||||
- يؤثر `session` في سياق التشغيل فقط؛ أما التسليم فتتحكم فيه `target` و`to`.
|
||||
- للتسليم إلى قناة/مستلم محدد، اضبط `target` + `to`. وعند استخدام
|
||||
- يؤثر `session` فقط في سياق التشغيل؛ ويتم التحكم في التسليم بواسطة `target` و`to`.
|
||||
- للتسليم إلى قناة/مستلم محدد، اضبط `target` + `to`. ومع
|
||||
`target: "last"`، يستخدم التسليم آخر قناة خارجية لتلك الجلسة.
|
||||
- تسمح عمليات تسليم نبضات الحياة بالأهداف المباشرة/الرسائل الخاصة افتراضيًا. اضبط `directPolicy: "block"` لمنع الإرسال إلى الأهداف المباشرة مع الاستمرار في تشغيل دورة نبضات الحياة.
|
||||
- إذا كان الطابور الرئيسي مشغولًا، يتم تخطي نبضات الحياة وتُعاد المحاولة لاحقًا.
|
||||
- إذا لم يُحل `target` إلى وجهة خارجية، فسيستمر التشغيل ولكن لن
|
||||
- تسمح عمليات تسليم Heartbeat بالأهداف المباشرة/الرسائل الخاصة افتراضيًا. اضبط `directPolicy: "block"` لكبت الإرسال إلى الأهداف المباشرة مع الاستمرار في تشغيل دور Heartbeat.
|
||||
- إذا كان الطابور الرئيسي مشغولًا، يتم تخطي Heartbeat وتُعاد المحاولة لاحقًا.
|
||||
- إذا لم يُحل `target` إلى وجهة خارجية، فسيستمر التشغيل لكن لن
|
||||
تُرسل أي رسالة صادرة.
|
||||
- إذا كانت `showOk` و`showAlerts` و`useIndicator` كلها معطلة، فسيتم تخطي التشغيل مسبقًا مع `reason=alerts-disabled`.
|
||||
- إذا كان تسليم التنبيهات فقط معطلًا، فلا يزال بإمكان OpenClaw تشغيل نبضات الحياة، وتحديث الطوابع الزمنية للمهام المستحقة، واستعادة الطابع الزمني لخمول الجلسة، ومنع حمولة التنبيه الخارجية.
|
||||
- الردود الخاصة بنبضات الحياة فقط **لا** تُبقي الجلسة نشطة؛ إذ تتم استعادة آخر قيمة لـ `updatedAt`
|
||||
بحيث يعمل انتهاء الخمول كالمعتاد.
|
||||
- يمكن [للمهام في الخلفية](/ar/automation/tasks) المنفصلة إدراج حدث نظام وتنشيط نبضات الحياة عندما ينبغي أن تلاحظ الجلسة الرئيسية شيئًا بسرعة. هذا التنشيط لا يجعل تشغيل نبضات الحياة مهمةً في الخلفية.
|
||||
- إذا كانت `showOk` و`showAlerts` و`useIndicator` كلها معطلة، فيتم تخطي التشغيل مسبقًا على أنه `reason=alerts-disabled`.
|
||||
- إذا كان تسليم التنبيهات فقط معطلًا، فلا يزال بإمكان OpenClaw تشغيل Heartbeat، وتحديث الطوابع الزمنية للمهام المستحقة، واستعادة الطابع الزمني لخمول الجلسة، وكبت حمولة التنبيه الخارجية.
|
||||
- إذا كان هدف Heartbeat المحلول يدعم مؤشر الكتابة، فسيعرض OpenClaw حالة الكتابة أثناء
|
||||
نشاط تشغيل Heartbeat. ويستخدم هذا الهدف نفسه الذي كان Heartbeat
|
||||
سيرسل إليه مخرجات الدردشة، ويُعطَّل بواسطة `typingMode: "never"`.
|
||||
- الردود الخاصة بـ Heartbeat فقط **لا** تُبقي الجلسة نشطة؛ إذ تتم استعادة قيمة `updatedAt`
|
||||
الأخيرة حتى يعمل انتهاء الخمول بشكل طبيعي.
|
||||
- يمكن لـ [المهام في الخلفية](/ar/automation/tasks) المنفصلة وضع حدث نظامي في الطابور وتنبيه Heartbeat عندما يجب أن تلاحظ الجلسة الرئيسية شيئًا بسرعة. ولا يجعل هذا التنبيه تشغيل Heartbeat مهمة في الخلفية.
|
||||
|
||||
## عناصر التحكم في الظهور
|
||||
|
||||
افتراضيًا، تُحجب تأكيدات `HEARTBEAT_OK` بينما يتم
|
||||
تسليم محتوى التنبيه. ويمكنك ضبط هذا لكل قناة أو لكل حساب:
|
||||
افتراضيًا، يتم كبت إقرارات `HEARTBEAT_OK` بينما يتم
|
||||
تسليم محتوى التنبيه. ويمكنك ضبط ذلك لكل قناة أو لكل حساب:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
defaults:
|
||||
heartbeat:
|
||||
showOk: false # إخفاء `HEARTBEAT_OK` (الافتراضي)
|
||||
showOk: false # إخفاء HEARTBEAT_OK (الافتراضي)
|
||||
showAlerts: true # إظهار رسائل التنبيه (الافتراضي)
|
||||
useIndicator: true # إصدار أحداث المؤشر (الافتراضي)
|
||||
telegram:
|
||||
heartbeat:
|
||||
showOk: true # إظهار تأكيدات OK على Telegram
|
||||
showOk: true # إظهار إقرارات OK على Telegram
|
||||
whatsapp:
|
||||
accounts:
|
||||
work:
|
||||
heartbeat:
|
||||
showAlerts: false # منع تسليم التنبيهات لهذا الحساب
|
||||
showAlerts: false # كبت تسليم التنبيهات لهذا الحساب
|
||||
```
|
||||
|
||||
الأولوية: لكل حساب → لكل قناة → إعدادات القنوات الافتراضية → الإعدادات الافتراضية المضمنة.
|
||||
الأسبقية: لكل حساب ← لكل قناة ← القيم الافتراضية للقناة ← القيم الافتراضية المضمّنة.
|
||||
|
||||
### ما الذي تفعله كل علامة
|
||||
### ما الذي يفعله كل خيار
|
||||
|
||||
- `showOk`: يرسل تأكيد `HEARTBEAT_OK` عندما يعيد النموذج ردًا يتضمن OK فقط.
|
||||
- `showAlerts`: يرسل محتوى التنبيه عندما يعيد النموذج ردًا لا يتضمن OK.
|
||||
- `useIndicator`: يصدر أحداث مؤشر لواجهات حالة UI.
|
||||
- `showOk`: يرسل إقرار `HEARTBEAT_OK` عندما يعيد النموذج ردًا يقتصر على OK.
|
||||
- `showAlerts`: يرسل محتوى التنبيه عندما يعيد النموذج ردًا لا يحتوي على OK.
|
||||
- `useIndicator`: يصدر أحداث المؤشر لواجهات حالة UI.
|
||||
|
||||
إذا كانت **القيم الثلاث كلها** false، فإن OpenClaw يتخطى تشغيل نبضات الحياة بالكامل (من دون استدعاء للنموذج).
|
||||
إذا كانت **الخيارات الثلاثة جميعها** false، فسيتخطى OpenClaw تشغيل Heartbeat بالكامل (من دون استدعاء للنموذج).
|
||||
|
||||
### أمثلة: لكل قناة مقابل لكل حساب
|
||||
### أمثلة لكل قناة مقابل لكل حساب
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -320,53 +323,53 @@ channels:
|
||||
accounts:
|
||||
ops:
|
||||
heartbeat:
|
||||
showAlerts: false # منع التنبيهات لحساب ops فقط
|
||||
showAlerts: false # كبت التنبيهات لحساب ops فقط
|
||||
telegram:
|
||||
heartbeat:
|
||||
showOk: true
|
||||
```
|
||||
|
||||
### الأنماط الشائعة
|
||||
### أنماط شائعة
|
||||
|
||||
| الهدف | الإعداد |
|
||||
| ----------------------------------------- | ----------------------------------------------------------------------------------------- |
|
||||
| السلوك الافتراضي (OK صامتة، والتنبيهات مفعلة) | _(لا حاجة إلى إعداد)_ |
|
||||
| صامت بالكامل (لا رسائل، لا مؤشر) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` |
|
||||
| مؤشر فقط (من دون رسائل) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }` |
|
||||
| OK في قناة واحدة فقط | `channels.telegram.heartbeat: { showOk: true }` |
|
||||
| الهدف | الإعداد |
|
||||
| ---------------------------------------- | ---------------------------------------------------------------------------------------- |
|
||||
| السلوك الافتراضي (إقرارات OK صامتة، والتنبيهات مفعلة) | _(لا حاجة إلى أي إعداد)_ |
|
||||
| صامت بالكامل (لا رسائل، لا مؤشر) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` |
|
||||
| مؤشر فقط (من دون رسائل) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }` |
|
||||
| إقرارات OK في قناة واحدة فقط | `channels.telegram.heartbeat: { showOk: true }` |
|
||||
|
||||
## `HEARTBEAT.md` (اختياري)
|
||||
|
||||
إذا كان هناك ملف `HEARTBEAT.md` في مساحة العمل، فإن المطالبة الافتراضية تطلب من
|
||||
الوكيل قراءته. ويمكنك اعتباره “قائمة التحقق الخاصة بنبضات الحياة”: صغيرة، وثابتة،
|
||||
إذا كان ملف `HEARTBEAT.md` موجودًا في مساحة العمل، فإن المطالبة الافتراضية تطلب من
|
||||
الوكيل قراءته. ويمكنك اعتباره “قائمة التحقق الخاصة بـ Heartbeat”: صغيرة، وثابتة،
|
||||
وآمنة للتضمين كل 30 دقيقة.
|
||||
|
||||
في التشغيلات العادية، لا يتم حقن `HEARTBEAT.md` إلا عندما تكون إرشادات نبضات الحياة
|
||||
مفعلة للوكيل الافتراضي. يؤدي تعطيل وتيرة نبضات الحياة باستخدام `0m` أو
|
||||
ضبط `includeSystemPromptSection: false` إلى حذف الملف من سياق bootstrap
|
||||
في التشغيلات العادية، لا يتم حقن `HEARTBEAT.md` إلا عندما تكون إرشادات Heartbeat
|
||||
مفعلة للوكيل الافتراضي. يؤدي تعطيل وتيرة Heartbeat باستخدام `0m` أو
|
||||
ضبط `includeSystemPromptSection: false` إلى حذفه من سياق التهيئة
|
||||
العادي.
|
||||
|
||||
إذا كان `HEARTBEAT.md` موجودًا ولكنه فارغ فعليًا (فقط أسطر فارغة وعناوين markdown
|
||||
مثل `# Heading`)، فإن OpenClaw يتخطى تشغيل نبضات الحياة لتوفير استدعاءات API.
|
||||
إذا كان `HEARTBEAT.md` موجودًا لكنه فارغ فعليًا (أسطر فارغة فقط وعناوين markdown
|
||||
مثل `# Heading`)، فسيتخطى OpenClaw تشغيل Heartbeat لتوفير استدعاءات API.
|
||||
ويتم الإبلاغ عن هذا التخطي على أنه `reason=empty-heartbeat-file`.
|
||||
أما إذا كان الملف مفقودًا، فستستمر نبضات الحياة ويقرر النموذج ما يجب فعله.
|
||||
أما إذا كان الملف مفقودًا، فسيستمر Heartbeat في العمل ويقرر النموذج ما يجب فعله.
|
||||
|
||||
اجعله صغيرًا (قائمة تحقق قصيرة أو تذكيرات) لتجنب تضخم المطالبة.
|
||||
اجعله صغيرًا جدًا (قائمة تحقق قصيرة أو تذكيرات) لتجنب تضخم المطالبة.
|
||||
|
||||
مثال على `HEARTBEAT.md`:
|
||||
|
||||
```md
|
||||
# قائمة التحقق الخاصة بنبضات الحياة
|
||||
# قائمة التحقق الخاصة بـ Heartbeat
|
||||
|
||||
- فحص سريع: هل يوجد شيء عاجل في صناديق الوارد؟
|
||||
- إذا كان الوقت نهارًا، فأجرِ تواصلًا خفيفًا إذا لم يكن هناك شيء آخر قيد الانتظار.
|
||||
- إذا كانت مهمة ما متوقفة، فاكتب _ما الذي ينقص_ واسأل Peter في المرة القادمة.
|
||||
- فحص سريع: هل هناك شيء عاجل في صناديق الوارد؟
|
||||
- إذا كان الوقت نهارًا، فقم بتحقق خفيف إذا لم يكن هناك شيء آخر معلق.
|
||||
- إذا كانت هناك مهمة معطلة، فاكتب _ما الذي ينقص_ واسأل Peter في المرة القادمة.
|
||||
```
|
||||
|
||||
### كتل `tasks:`
|
||||
|
||||
يدعم `HEARTBEAT.md` أيضًا كتلة منظمة صغيرة `tasks:` للفحوصات
|
||||
القائمة على الفواصل الزمنية داخل نبضات الحياة نفسها.
|
||||
يدعم `HEARTBEAT.md` أيضًا كتلة `tasks:` منظمة صغيرة لعمليات
|
||||
التحقق المعتمدة على الفاصل الزمني داخل Heartbeat نفسه.
|
||||
|
||||
مثال:
|
||||
|
||||
@ -375,84 +378,85 @@ tasks:
|
||||
|
||||
- name: inbox-triage
|
||||
interval: 30m
|
||||
prompt: "افحص رسائل البريد الإلكتروني غير المقروءة العاجلة وحدد أي شيء حساس للوقت."
|
||||
prompt: "تحقق من وجود رسائل بريد إلكتروني غير مقروءة وعاجلة وعلّم أي شيء حساس زمنيًا."
|
||||
- name: calendar-scan
|
||||
interval: 2h
|
||||
prompt: "افحص الاجتماعات القادمة التي تحتاج إلى تحضير أو متابعة."
|
||||
prompt: "تحقق من الاجتماعات القادمة التي تحتاج إلى تحضير أو متابعة."
|
||||
|
||||
# تعليمات إضافية
|
||||
|
||||
- اجعل التنبيهات قصيرة.
|
||||
- إذا لم يكن هناك ما يحتاج إلى اهتمام بعد جميع المهام المستحقة، فردّ بـ HEARTBEAT_OK.
|
||||
- إذا لم يكن هناك ما يحتاج إلى انتباه بعد جميع المهام المستحقة، فردّ بـ HEARTBEAT_OK.
|
||||
```
|
||||
|
||||
السلوك:
|
||||
|
||||
- يقوم OpenClaw بتحليل كتلة `tasks:` والتحقق من كل مهمة وفق `interval` الخاص بها.
|
||||
- لا تُضمَّن في مطالبة نبضات الحياة لتلك النبضة إلا المهام **المستحقة**.
|
||||
- إذا لم تكن هناك مهام مستحقة، يتم تخطي نبضات الحياة بالكامل (`reason=no-tasks-due`) لتجنب استدعاء نموذج بلا فائدة.
|
||||
- يحلل OpenClaw كتلة `tasks:` ويفحص كل مهمة وفق `interval` الخاص بها.
|
||||
- لا يتم تضمين سوى المهام **المستحقة** في مطالبة Heartbeat الخاصة بتلك النبضة.
|
||||
- إذا لم تكن هناك مهام مستحقة، يتم تخطي Heartbeat بالكامل (`reason=no-tasks-due`) لتجنب استدعاء نموذج بلا فائدة.
|
||||
- يتم الاحتفاظ بالمحتوى غير الخاص بالمهام في `HEARTBEAT.md` وإلحاقه كسياق إضافي بعد قائمة المهام المستحقة.
|
||||
- تُخزَّن الطوابع الزمنية لآخر تشغيل للمهام في حالة الجلسة (`heartbeatTaskState`)، لذلك تبقى الفواصل الزمنية محفوظة عبر عمليات إعادة التشغيل العادية.
|
||||
- لا يتم تقديم الطوابع الزمنية للمهام إلا بعد أن يكمل تشغيل نبضات الحياة مسار الرد العادي. أما التشغيلات المتخطاة بسبب `empty-heartbeat-file` / `no-tasks-due` فلا تُعلَّم فيها المهام على أنها مكتملة.
|
||||
- يتم تخزين الطوابع الزمنية لآخر تشغيل للمهام في حالة الجلسة (`heartbeatTaskState`)، لذا تبقى الفواصل الزمنية محفوظة عبر عمليات إعادة التشغيل العادية.
|
||||
- لا يتم تقديم الطوابع الزمنية للمهام إلا بعد أن يكمل تشغيل Heartbeat مسار الرد العادي. أما التشغيلات المتخطاة `empty-heartbeat-file` / `no-tasks-due` فلا تضع علامة على المهام على أنها مكتملة.
|
||||
|
||||
وضع المهام مفيد عندما تريد أن يحتوي ملف نبضات حياة واحد على عدة فحوصات دورية من دون دفع تكلفة جميعها في كل نبضة.
|
||||
يفيد وضع المهام عندما تريد أن يحتوي ملف Heartbeat واحد على عدة عمليات تحقق دورية من دون دفع تكلفة جميعها في كل نبضة.
|
||||
|
||||
### هل يمكن للوكيل تحديث `HEARTBEAT.md`؟
|
||||
|
||||
نعم — إذا طلبت منه ذلك.
|
||||
|
||||
`HEARTBEAT.md` هو مجرد ملف عادي في مساحة عمل الوكيل، لذلك يمكنك أن تطلب من
|
||||
الوكيل (في محادثة عادية) شيئًا مثل:
|
||||
`HEARTBEAT.md` هو مجرد ملف عادي في مساحة عمل الوكيل، لذا يمكنك أن تطلب من
|
||||
الوكيل (في دردشة عادية) شيئًا مثل:
|
||||
|
||||
- “حدّث `HEARTBEAT.md` لإضافة فحص يومي للتقويم.”
|
||||
- “أعد كتابة `HEARTBEAT.md` ليكون أقصر وأكثر تركيزًا على متابعات الوارد.”
|
||||
- “حدّث `HEARTBEAT.md` لإضافة تحقق يومي من التقويم.”
|
||||
- “أعد كتابة `HEARTBEAT.md` ليكون أقصر ومركزًا على متابعات صندوق الوارد.”
|
||||
|
||||
إذا كنت تريد أن يحدث هذا بشكل استباقي، فيمكنك أيضًا تضمين سطر صريح في
|
||||
مطالبة نبضات الحياة مثل: “إذا أصبحت قائمة التحقق قديمة، فحدّث HEARTBEAT.md
|
||||
وإذا أردت أن يحدث ذلك بشكل استباقي، فيمكنك أيضًا تضمين سطر صريح في
|
||||
مطالبة Heartbeat مثل: “إذا أصبحت قائمة التحقق قديمة، فحدّث HEARTBEAT.md
|
||||
بقائمة أفضل.”
|
||||
|
||||
ملاحظة أمان: لا تضع أسرارًا (مفاتيح API، أو أرقام هواتف، أو رموز وصول خاصة) في
|
||||
ملاحظة أمان: لا تضع أسرارًا (مفاتيح API، أو أرقام الهواتف، أو الرموز الخاصة) داخل
|
||||
`HEARTBEAT.md` — لأنه يصبح جزءًا من سياق المطالبة.
|
||||
|
||||
## تنشيط يدوي (عند الطلب)
|
||||
## التنبيه اليدوي (عند الطلب)
|
||||
|
||||
يمكنك إدراج حدث نظام وتشغيل نبضة حياة فورية باستخدام:
|
||||
يمكنك وضع حدث نظامي في الطابور وتشغيل Heartbeat فورًا باستخدام:
|
||||
|
||||
```bash
|
||||
openclaw system event --text "Check for urgent follow-ups" --mode now
|
||||
```
|
||||
|
||||
إذا كانت هناك عدة وكلاء لديهم `heartbeat` مهيأ، فإن التنشيط اليدوي يشغّل نبضات حياة كل واحد من هؤلاء الوكلاء فورًا.
|
||||
إذا كان لدى عدة وكلاء إعداد `heartbeat`، فإن التنبيه اليدوي يشغّل Heartbeat الخاص بكل من هذه
|
||||
الوكلاء فورًا.
|
||||
|
||||
استخدم `--mode next-heartbeat` للانتظار حتى النبضة المجدولة التالية.
|
||||
استخدم `--mode next-heartbeat` لانتظار النبضة المجدولة التالية.
|
||||
|
||||
## تسليم الاستدلال (اختياري)
|
||||
|
||||
افتراضيًا، تسلّم نبضات الحياة حمولة “الإجابة” النهائية فقط.
|
||||
افتراضيًا، تسلّم Heartbeat حمولة “الإجابة” النهائية فقط.
|
||||
|
||||
إذا كنت تريد مزيدًا من الشفافية، فعّل:
|
||||
إذا أردت مزيدًا من الشفافية، فعّل:
|
||||
|
||||
- `agents.defaults.heartbeat.includeReasoning: true`
|
||||
|
||||
عند التفعيل، ستسلّم نبضات الحياة أيضًا رسالة منفصلة مسبوقة بـ
|
||||
`Reasoning:` (بنفس صيغة `/reasoning on`). قد يكون هذا مفيدًا عندما يكون الوكيل
|
||||
يدير عدة جلسات/Skills وتريد معرفة سبب قراره بتنبيهك —
|
||||
لكنه قد يكشف أيضًا تفاصيل داخلية أكثر مما تريد. لذا يُفضَّل إبقاؤه
|
||||
عند التفعيل، ستسلّم Heartbeat أيضًا رسالة منفصلة مسبوقة بـ
|
||||
`Reasoning:` (بنفس صيغة `/reasoning on`). وقد يكون ذلك مفيدًا عندما يكون الوكيل
|
||||
يدير عدة جلسات/حالات codex وتريد معرفة سبب قراره بتنبيهك
|
||||
— لكنه قد يكشف أيضًا تفاصيل داخلية أكثر مما تريد. ومن الأفضل إبقاؤه
|
||||
معطلًا في الدردشات الجماعية.
|
||||
|
||||
## مراعاة التكلفة
|
||||
## الوعي بالتكلفة
|
||||
|
||||
تشغّل نبضات الحياة دورات وكيل كاملة. وكلما قصرت الفواصل الزمنية زاد استهلاك التوكنات. لتقليل التكلفة:
|
||||
تشغّل Heartbeat أدوار وكيل كاملة. وكلما قصرت الفواصل الزمنية زاد استهلاك الرموز. لتقليل التكلفة:
|
||||
|
||||
- استخدم `isolatedSession: true` لتجنب إرسال سجل المحادثة الكامل (من ~100K توكن إلى ~2-5K لكل تشغيل).
|
||||
- استخدم `lightContext: true` لحصر ملفات bootstrap على `HEARTBEAT.md` فقط.
|
||||
- استخدم `isolatedSession: true` لتجنب إرسال السجل الكامل للمحادثة (من ~100K رمز إلى ~2-5K لكل تشغيل).
|
||||
- استخدم `lightContext: true` لحصر ملفات التهيئة في `HEARTBEAT.md` فقط.
|
||||
- اضبط `model` أرخص (مثل `ollama/llama3.2:1b`).
|
||||
- أبقِ `HEARTBEAT.md` صغيرًا.
|
||||
- اجعل `HEARTBEAT.md` صغيرًا.
|
||||
- استخدم `target: "none"` إذا كنت تريد فقط تحديثات الحالة الداخلية.
|
||||
|
||||
## ذو صلة
|
||||
|
||||
- [الأتمتة والمهام](/ar/automation) — نظرة سريعة على جميع آليات الأتمتة
|
||||
- [المهام في الخلفية](/ar/automation/tasks) — كيفية تتبع العمل المنفصل
|
||||
- [المنطقة الزمنية](/ar/concepts/timezone) — كيف تؤثر المنطقة الزمنية في جدولة نبضات الحياة
|
||||
- [المنطقة الزمنية](/ar/concepts/timezone) — كيف تؤثر المنطقة الزمنية في جدولة Heartbeat
|
||||
- [استكشاف الأخطاء وإصلاحها](/ar/automation/cron-jobs#troubleshooting) — تصحيح مشكلات الأتمتة
|
||||
|
||||
@ -1,65 +1,65 @@
|
||||
---
|
||||
read_when:
|
||||
- تريد إنشاء plugin جديد لـ OpenClaw
|
||||
- تحتاج إلى دليل بدء سريع لتطوير plugin
|
||||
- تضيف قناة أو مزودًا أو أداة أو قدرة أخرى جديدة إلى OpenClaw
|
||||
- تريد إنشاء Plugin جديد لـ OpenClaw
|
||||
- تحتاج إلى بداية سريعة لتطوير Plugin
|
||||
- أنت تضيف قناة أو موفّرًا أو أداة أو قدرة أخرى جديدة إلى OpenClaw
|
||||
sidebarTitle: Getting Started
|
||||
summary: أنشئ أول plugin لـ OpenClaw خلال دقائق
|
||||
summary: أنشئ أول Plugin لـ OpenClaw في غضون دقائق
|
||||
title: بناء Plugins
|
||||
x-i18n:
|
||||
generated_at: "2026-04-07T07:19:17Z"
|
||||
generated_at: "2026-04-22T07:17:53Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 509c1f5abe1a0a74966054ed79b71a1a7ee637a43b1214c424acfe62ddf48eef
|
||||
source_hash: 67368be311537f984f14bea9239b88c3eccf72a76c9dd1347bb041e02697ae24
|
||||
source_path: plugins/building-plugins.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# بناء Plugins
|
||||
|
||||
توسّع Plugins قدرات OpenClaw بإمكانات جديدة: القنوات، وموفرو النماذج،
|
||||
والكلام، والنسخ الفوري، والصوت الفوري، وفهم الوسائط، وتوليد
|
||||
الصور، وتوليد الفيديو، وجلب الويب، والبحث على الويب، وأدوات الوكيل، أو أي
|
||||
مزيج منها.
|
||||
توسّع Plugins قدرات OpenClaw بإمكانات جديدة: القنوات، وموفّرو النماذج،
|
||||
والكلام، والنسخ الفوري، والصوت الفوري، وفهم الوسائط، وتوليد الصور،
|
||||
وتوليد الفيديو، وجلب الويب، والبحث على الويب، وأدوات الوكيل، أو أي
|
||||
مزيج من ذلك.
|
||||
|
||||
لا تحتاج إلى إضافة plugin الخاص بك إلى مستودع OpenClaw. انشره على
|
||||
[ClawHub](/ar/tools/clawhub) أو npm وسيقوم المستخدمون بتثبيته باستخدام
|
||||
`openclaw plugins install <package-name>`. يحاول OpenClaw استخدام ClawHub أولًا ثم
|
||||
يرجع تلقائيًا إلى npm.
|
||||
لا تحتاج إلى إضافة Plugin الخاص بك إلى مستودع OpenClaw. انشره إلى
|
||||
[ClawHub](/ar/tools/clawhub) أو npm وسيقوم المستخدمون بالتثبيت باستخدام
|
||||
`openclaw plugins install <package-name>`. يحاول OpenClaw استخدام ClawHub أولًا
|
||||
ثم يعود إلى npm تلقائيًا عند الحاجة.
|
||||
|
||||
## المتطلبات الأساسية
|
||||
## المتطلبات المسبقة
|
||||
|
||||
- Node >= 22 ومدير حزم (npm أو pnpm)
|
||||
- الإلمام بـ TypeScript (ESM)
|
||||
- بالنسبة إلى plugins داخل المستودع: يجب أن يكون المستودع مستنسخًا وقد تم تشغيل `pnpm install`
|
||||
- إلمام بـ TypeScript (ESM)
|
||||
- بالنسبة إلى Plugins داخل المستودع: أن يكون المستودع مستنسخًا وتم تنفيذ `pnpm install`
|
||||
|
||||
## ما نوع plugin الذي تريده؟
|
||||
## ما نوع Plugin الذي تريد إنشاءه؟
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Channel plugin" icon="messages-square" href="/ar/plugins/sdk-channel-plugins">
|
||||
وصّل OpenClaw بمنصة مراسلة (Discord وIRC وغيرهما)
|
||||
<Card title="Plugin قناة" icon="messages-square" href="/ar/plugins/sdk-channel-plugins">
|
||||
اربط OpenClaw بمنصة مراسلة (Discord أو IRC أو غيرهما)
|
||||
</Card>
|
||||
<Card title="Provider plugin" icon="cpu" href="/ar/plugins/sdk-provider-plugins">
|
||||
أضف مزود نماذج (LLM أو proxy أو endpoint مخصص)
|
||||
<Card title="Plugin موفّر" icon="cpu" href="/ar/plugins/sdk-provider-plugins">
|
||||
أضف موفّر نماذج (LLM أو وكيل أو نقطة نهاية مخصّصة)
|
||||
</Card>
|
||||
<Card title="Tool / hook plugin" icon="wrench">
|
||||
<Card title="Plugin أداة / hook" icon="wrench">
|
||||
سجّل أدوات الوكيل أو event hooks أو الخدمات — تابع أدناه
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
إذا كان Channel plugin اختياريًا وقد لا يكون مثبتًا عند تشغيل
|
||||
onboarding/setup، فاستخدم `createOptionalChannelSetupSurface(...)` من
|
||||
`openclaw/plugin-sdk/channel-setup`. فهو ينتج setup adapter + wizard
|
||||
يعلن عن متطلب التثبيت ويفشل بشكل مغلق عند محاولات كتابة الإعدادات الفعلية
|
||||
إلى أن يتم تثبيت plugin.
|
||||
إذا كان Plugin القناة اختياريًا وقد لا يكون مُثبّتًا عند تشغيل الإعداد أو
|
||||
التهيئة الأولية، فاستخدم `createOptionalChannelSetupSurface(...)` من
|
||||
`openclaw/plugin-sdk/channel-setup`. فهو ينتج زوجًا من محوّل إعداد + معالج إعداد
|
||||
يعرض متطلب التثبيت ويفشل بشكل آمن عند أي عمليات كتابة فعلية للإعدادات
|
||||
إلى أن يتم تثبيت Plugin.
|
||||
|
||||
## بدء سريع: Tool plugin
|
||||
## بداية سريعة: Plugin أداة
|
||||
|
||||
ينشئ هذا الدليل plugin بسيطًا يسجل أداة وكيل. أما Channel plugins
|
||||
وProvider plugins فلها أدلة مخصصة مرتبطة أعلاه.
|
||||
ينشئ هذا الدليل العملي Plugin بسيطًا يسجّل أداة وكيل. لدى Plugins القنوات
|
||||
والموفّرين أدلة مخصّصة مرتبطة أعلاه.
|
||||
|
||||
<Steps>
|
||||
<Step title="أنشئ الحزمة وmanifest">
|
||||
<Step title="أنشئ الحزمة وملف manifest">
|
||||
<CodeGroup>
|
||||
```json package.json
|
||||
{
|
||||
@ -93,9 +93,9 @@ onboarding/setup، فاستخدم `createOptionalChannelSetupSurface(...)` من
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
يحتاج كل plugin إلى manifest، حتى من دون إعدادات. راجع
|
||||
[Manifest](/ar/plugins/manifest) للاطلاع على المخطط الكامل. وتوجد مقتطفات النشر
|
||||
القياسية الخاصة بـ ClawHub في `docs/snippets/plugin-publish/`.
|
||||
يحتاج كل Plugin إلى ملف manifest، حتى إذا لم تكن لديه إعدادات. راجع
|
||||
[Manifest](/ar/plugins/manifest) للاطلاع على المخطط الكامل. توجد مقتطفات النشر
|
||||
القياسية إلى ClawHub في `docs/snippets/plugin-publish/`.
|
||||
|
||||
</Step>
|
||||
|
||||
@ -123,15 +123,15 @@ onboarding/setup، فاستخدم `createOptionalChannelSetupSurface(...)` من
|
||||
});
|
||||
```
|
||||
|
||||
يُستخدم `definePluginEntry` للـ plugins غير الخاصة بالقنوات. أما القنوات فاستخدم
|
||||
`defineChannelPluginEntry` — راجع [Channel Plugins](/ar/plugins/sdk-channel-plugins).
|
||||
وللاطلاع على الخيارات الكاملة لنقطة الإدخال، راجع [Entry Points](/ar/plugins/sdk-entrypoints).
|
||||
يُستخدم `definePluginEntry` مع Plugins غير الخاصة بالقنوات. أما بالنسبة إلى القنوات، فاستخدم
|
||||
`defineChannelPluginEntry` — راجع [Plugins القنوات](/ar/plugins/sdk-channel-plugins).
|
||||
وللاطلاع على الخيارات الكاملة لنقطة الإدخال، راجع [نقاط الإدخال](/ar/plugins/sdk-entrypoints).
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="اختبر وانشر">
|
||||
|
||||
**Plugins الخارجية:** تحقّق وانشر باستخدام ClawHub، ثم ثبّت:
|
||||
**Plugins الخارجية:** تحقّق منها وانشرها باستخدام ClawHub، ثم ثبّتها:
|
||||
|
||||
```bash
|
||||
clawhub package publish your-org/your-plugin --dry-run
|
||||
@ -139,10 +139,10 @@ onboarding/setup، فاستخدم `createOptionalChannelSetupSurface(...)` من
|
||||
openclaw plugins install clawhub:@myorg/openclaw-my-plugin
|
||||
```
|
||||
|
||||
يفحص OpenClaw أيضًا ClawHub قبل npm عند استخدام مواصفات حزم مجردة مثل
|
||||
يتحقق OpenClaw أيضًا من ClawHub قبل npm عند استخدام محددات الحزم المجردة مثل
|
||||
`@myorg/openclaw-my-plugin`.
|
||||
|
||||
**Plugins داخل المستودع:** ضَعها ضمن شجرة workspace الخاصة بالـ plugin المضمّن — سيتم اكتشافها تلقائيًا.
|
||||
**Plugins داخل المستودع:** ضعها ضمن شجرة مساحة عمل Plugins المضمّنة — وسيتم اكتشافها تلقائيًا.
|
||||
|
||||
```bash
|
||||
pnpm test -- <bundled-plugin-root>/my-plugin/
|
||||
@ -151,62 +151,69 @@ onboarding/setup، فاستخدم `createOptionalChannelSetupSurface(...)` من
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## قدرات plugin
|
||||
## قدرات Plugin
|
||||
|
||||
يمكن لـ plugin واحد تسجيل أي عدد من القدرات عبر الكائن `api`:
|
||||
يمكن لـ Plugin واحد تسجيل أي عدد من القدرات عبر الكائن `api`:
|
||||
|
||||
| القدرة | طريقة التسجيل | الدليل المفصل |
|
||||
| ---------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------- |
|
||||
| الاستدلال النصي (LLM) | `api.registerProvider(...)` | [Provider Plugins](/ar/plugins/sdk-provider-plugins) |
|
||||
| CLI inference backend | `api.registerCliBackend(...)` | [CLI Backends](/ar/gateway/cli-backends) |
|
||||
| القناة / المراسلة | `api.registerChannel(...)` | [Channel Plugins](/ar/plugins/sdk-channel-plugins) |
|
||||
| الكلام (TTS/STT) | `api.registerSpeechProvider(...)` | [Provider Plugins](/ar/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| النسخ الفوري | `api.registerRealtimeTranscriptionProvider(...)` | [Provider Plugins](/ar/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| الصوت الفوري | `api.registerRealtimeVoiceProvider(...)` | [Provider Plugins](/ar/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| فهم الوسائط | `api.registerMediaUnderstandingProvider(...)` | [Provider Plugins](/ar/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| توليد الصور | `api.registerImageGenerationProvider(...)` | [Provider Plugins](/ar/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| توليد الموسيقى | `api.registerMusicGenerationProvider(...)` | [Provider Plugins](/ar/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| توليد الفيديو | `api.registerVideoGenerationProvider(...)` | [Provider Plugins](/ar/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| جلب الويب | `api.registerWebFetchProvider(...)` | [Provider Plugins](/ar/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| البحث على الويب | `api.registerWebSearchProvider(...)` | [Provider Plugins](/ar/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| أدوات الوكيل | `api.registerTool(...)` | أدناه |
|
||||
| أوامر مخصصة | `api.registerCommand(...)` | [Entry Points](/ar/plugins/sdk-entrypoints) |
|
||||
| Event hooks | `api.registerHook(...)` | [Entry Points](/ar/plugins/sdk-entrypoints) |
|
||||
| مسارات HTTP | `api.registerHttpRoute(...)` | [Internals](/ar/plugins/architecture#gateway-http-routes) |
|
||||
| أوامر CLI فرعية | `api.registerCli(...)` | [Entry Points](/ar/plugins/sdk-entrypoints) |
|
||||
| القدرة | طريقة التسجيل | الدليل المفصل |
|
||||
| ---------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------ |
|
||||
| الاستدلال النصي (LLM) | `api.registerProvider(...)` | [Plugins الموفّر](/ar/plugins/sdk-provider-plugins) |
|
||||
| واجهة خلفية للاستدلال عبر CLI | `api.registerCliBackend(...)` | [واجهات CLI الخلفية](/ar/gateway/cli-backends) |
|
||||
| القناة / المراسلة | `api.registerChannel(...)` | [Plugins القنوات](/ar/plugins/sdk-channel-plugins) |
|
||||
| الكلام (TTS/STT) | `api.registerSpeechProvider(...)` | [Plugins الموفّر](/ar/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| النسخ الفوري | `api.registerRealtimeTranscriptionProvider(...)` | [Plugins الموفّر](/ar/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| الصوت الفوري | `api.registerRealtimeVoiceProvider(...)` | [Plugins الموفّر](/ar/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| فهم الوسائط | `api.registerMediaUnderstandingProvider(...)` | [Plugins الموفّر](/ar/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| توليد الصور | `api.registerImageGenerationProvider(...)` | [Plugins الموفّر](/ar/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| توليد الموسيقى | `api.registerMusicGenerationProvider(...)` | [Plugins الموفّر](/ar/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| توليد الفيديو | `api.registerVideoGenerationProvider(...)` | [Plugins الموفّر](/ar/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| جلب الويب | `api.registerWebFetchProvider(...)` | [Plugins الموفّر](/ar/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| البحث على الويب | `api.registerWebSearchProvider(...)` | [Plugins الموفّر](/ar/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| امتداد Pi مضمّن | `api.registerEmbeddedExtensionFactory(...)` | [نظرة عامة على SDK](/ar/plugins/sdk-overview#registration-api) |
|
||||
| أدوات الوكيل | `api.registerTool(...)` | أدناه |
|
||||
| أوامر مخصّصة | `api.registerCommand(...)` | [نقاط الإدخال](/ar/plugins/sdk-entrypoints) |
|
||||
| event hooks | `api.registerHook(...)` | [نقاط الإدخال](/ar/plugins/sdk-entrypoints) |
|
||||
| مسارات HTTP | `api.registerHttpRoute(...)` | [الداخليات](/ar/plugins/architecture#gateway-http-routes) |
|
||||
| أوامر CLI فرعية | `api.registerCli(...)` | [نقاط الإدخال](/ar/plugins/sdk-entrypoints) |
|
||||
|
||||
للاطلاع على API التسجيل الكامل، راجع [نظرة عامة على SDK](/ar/plugins/sdk-overview#registration-api).
|
||||
|
||||
إذا كان plugin الخاص بك يسجل أساليب Gateway RPC مخصصة، فاحتفظ بها ضمن
|
||||
بادئة خاصة بـ plugin. تظل مساحات أسماء الإدارة الأساسية (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) محجوزة وتُحل دائمًا إلى
|
||||
`operator.admin`، حتى إذا طلب plugin نطاقًا أضيق.
|
||||
استخدم `api.registerEmbeddedExtensionFactory(...)` عندما يحتاج Plugin إلى
|
||||
hooks خاصة بالمشغّل المضمّن الأصلية في Pi مثل إعادة كتابة `tool_result`
|
||||
غير المتزامنة قبل إصدار رسالة نتيجة الأداة النهائية. ويفضَّل استخدام hooks
|
||||
Plugin العادية في OpenClaw عندما لا يتطلب العمل توقيت امتداد Pi.
|
||||
|
||||
دلالات حرس الـ hook التي يجب وضعها في الاعتبار:
|
||||
إذا كان Plugin الخاص بك يسجّل أساليب RPC مخصّصة لـ Gateway، فاحتفظ بها ضمن
|
||||
بادئة خاصة بالـ Plugin. تظل مساحات الأسماء الإدارية الأساسية (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) محجوزة ويجري حلّها دائمًا إلى
|
||||
`operator.admin`، حتى إذا طلب Plugin نطاقًا أضيق.
|
||||
|
||||
- `before_tool_call`: `{ block: true }` نهائية وتوقف المعالجات ذات الأولوية الأقل.
|
||||
- `before_tool_call`: `{ block: false }` تُعامل على أنها بدون قرار.
|
||||
- `before_tool_call`: `{ requireApproval: true }` توقف تنفيذ الوكيل مؤقتًا وتطلب موافقة المستخدم عبر طبقة exec approval، أو أزرار Telegram، أو تفاعلات Discord، أو الأمر `/approve` على أي قناة.
|
||||
- `before_install`: `{ block: true }` نهائية وتوقف المعالجات ذات الأولوية الأقل.
|
||||
- `before_install`: `{ block: false }` تُعامل على أنها بدون قرار.
|
||||
- `message_sending`: `{ cancel: true }` نهائية وتوقف المعالجات ذات الأولوية الأقل.
|
||||
- `message_sending`: `{ cancel: false }` تُعامل على أنها بدون قرار.
|
||||
دلالات حارس hook التي ينبغي أخذها في الاعتبار:
|
||||
|
||||
يعالج الأمر `/approve` كلًا من exec approvals وplugin approvals مع fallback
|
||||
مقيّد: فعندما لا يتم العثور على معرّف exec approval، يعيد OpenClaw محاولة
|
||||
المعرّف نفسه عبر plugin approvals. ويمكن ضبط تمرير plugin approval
|
||||
بشكل مستقل عبر `approvals.plugin` في الإعدادات.
|
||||
- `before_tool_call`: القيمة `{ block: true }` نهائية وتوقف المعالجات ذات الأولوية الأقل.
|
||||
- `before_tool_call`: القيمة `{ block: false }` تُعامل على أنها بلا قرار.
|
||||
- `before_tool_call`: القيمة `{ requireApproval: true }` توقف تنفيذ الوكيل مؤقتًا وتطلب موافقة المستخدم عبر طبقة موافقات التنفيذ، أو أزرار Telegram، أو تفاعلات Discord، أو الأمر `/approve` على أي قناة.
|
||||
- `before_install`: القيمة `{ block: true }` نهائية وتوقف المعالجات ذات الأولوية الأقل.
|
||||
- `before_install`: القيمة `{ block: false }` تُعامل على أنها بلا قرار.
|
||||
- `message_sending`: القيمة `{ cancel: true }` نهائية وتوقف المعالجات ذات الأولوية الأقل.
|
||||
- `message_sending`: القيمة `{ cancel: false }` تُعامل على أنها بلا قرار.
|
||||
|
||||
إذا كان من الضروري أن يكتشف منطق approval المخصص حالة fallback المقيّدة نفسها،
|
||||
ففضّل استخدام `isApprovalNotFoundError` من `openclaw/plugin-sdk/error-runtime`
|
||||
بدلًا من مطابقة سلاسل انتهاء صلاحية approval يدويًا.
|
||||
يتعامل الأمر `/approve` مع كلٍّ من موافقات التنفيذ وموافقات Plugin مع بديل
|
||||
احتياطي مقيّد: عندما لا يتم العثور على معرّف موافقة تنفيذ، يعيد OpenClaw
|
||||
محاولة استخدام المعرّف نفسه عبر موافقات Plugin. ويمكن تهيئة إعادة توجيه
|
||||
موافقات Plugin بشكل مستقل عبر `approvals.plugin` في الإعدادات.
|
||||
|
||||
راجع [دلالات قرارات hook في نظرة عامة على SDK](/ar/plugins/sdk-overview#hook-decision-semantics) للتفاصيل.
|
||||
إذا كانت بنية الموافقات المخصّصة تحتاج إلى اكتشاف حالة البديل الاحتياطي
|
||||
المقيّد نفسها، فافضّل استخدام `isApprovalNotFoundError` من
|
||||
`openclaw/plugin-sdk/error-runtime` بدلًا من مطابقة سلاسل انتهاء صلاحية
|
||||
الموافقة يدويًا.
|
||||
|
||||
راجع [دلالات قرارات hook في نظرة عامة على SDK](/ar/plugins/sdk-overview#hook-decision-semantics) لمزيد من التفاصيل.
|
||||
|
||||
## تسجيل أدوات الوكيل
|
||||
|
||||
الأدوات هي دوال typed يمكن لـ LLM استدعاؤها. ويمكن أن تكون مطلوبة (متاحة
|
||||
دائمًا) أو اختيارية (اشتراك من المستخدم):
|
||||
دائمًا) أو اختيارية (يختار المستخدم تفعيلها):
|
||||
|
||||
```typescript
|
||||
register(api) {
|
||||
@ -243,13 +250,13 @@ register(api) {
|
||||
}
|
||||
```
|
||||
|
||||
- يجب ألا تتعارض أسماء الأدوات مع الأدوات الأساسية (يتم تخطي التعارضات)
|
||||
- استخدم `optional: true` للأدوات ذات التأثيرات الجانبية أو متطلبات الملفات التنفيذية الإضافية
|
||||
- يمكن للمستخدمين تفعيل جميع أدوات plugin عبر إضافة معرّف plugin إلى `tools.allow`
|
||||
- يجب ألا تتعارض أسماء الأدوات مع أدوات النواة الأساسية (سيتم تخطي التعارضات)
|
||||
- استخدم `optional: true` للأدوات ذات الآثار الجانبية أو التي تتطلب ملفات تنفيذية إضافية
|
||||
- يمكن للمستخدمين تفعيل جميع الأدوات من Plugin عبر إضافة معرّف Plugin إلى `tools.allow`
|
||||
|
||||
## اصطلاحات الاستيراد
|
||||
|
||||
استورد دائمًا من مسارات فرعية مركّزة `openclaw/plugin-sdk/<subpath>`:
|
||||
استورد دائمًا من مسارات `openclaw/plugin-sdk/<subpath>` المركّزة:
|
||||
|
||||
```typescript
|
||||
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
|
||||
@ -261,60 +268,60 @@ import { ... } from "openclaw/plugin-sdk";
|
||||
|
||||
للاطلاع على المرجع الكامل للمسارات الفرعية، راجع [نظرة عامة على SDK](/ar/plugins/sdk-overview).
|
||||
|
||||
داخل plugin الخاص بك، استخدم ملفات barrel محلية (`api.ts`, `runtime-api.ts`)
|
||||
لعمليات الاستيراد الداخلية — ولا تستورد plugin الخاص بك أبدًا عبر مسار SDK الخاص به.
|
||||
داخل Plugin الخاص بك، استخدم ملفات barrel المحلية (`api.ts`, `runtime-api.ts`) في
|
||||
عمليات الاستيراد الداخلية — ولا تستورد Plugin الخاص بك مطلقًا عبر مسار SDK الخاص به.
|
||||
|
||||
بالنسبة إلى Provider plugins، احتفظ بالمساعدات الخاصة بالمزود داخل ملفات
|
||||
barrel الموجودة في جذر الحزمة ما لم تكن نقطة الربط عامة فعلًا. ومن الأمثلة
|
||||
المضمنة الحالية:
|
||||
بالنسبة إلى Plugins الموفّر، احتفظ بالمساعدات الخاصة بالموفّر في ملفات
|
||||
barrel الموجودة في جذر الحزمة ما لم يكن الحد الفاصل عامًا فعلًا. أمثلة
|
||||
الحزم المضمّنة الحالية:
|
||||
|
||||
- Anthropic: مغلفات تدفق Claude ومساعدات `service_tier` / beta
|
||||
- OpenAI: بُناة المزودات، ومساعدات النماذج الافتراضية، ومزودات الوقت الفعلي
|
||||
- OpenRouter: باني المزود بالإضافة إلى مساعدات onboarding/config
|
||||
- Anthropic: أغلفة Claude للبث ومساعدات `service_tier` و beta
|
||||
- OpenAI: بُنّاة الموفّرين، ومساعدات النماذج الافتراضية، وموفّرو الزمن الحقيقي
|
||||
- OpenRouter: باني الموفّر بالإضافة إلى مساعدات الإعداد الأولي والتهيئة
|
||||
|
||||
إذا كان المساعد مفيدًا فقط داخل حزمة مزود مضمّنة واحدة، فأبقِه ضمن
|
||||
نقطة الربط الموجودة في جذر تلك الحزمة بدلًا من ترقيته إلى `openclaw/plugin-sdk/*`.
|
||||
إذا كان المساعد مفيدًا فقط داخل حزمة موفّر مضمّنة واحدة، فأبقِه ضمن هذا
|
||||
الحد الفاصل في جذر الحزمة بدلًا من ترقيته إلى `openclaw/plugin-sdk/*`.
|
||||
|
||||
لا تزال بعض نقاط الربط المساعدة المولدة `openclaw/plugin-sdk/<bundled-id>` موجودة
|
||||
لصيانة plugins المضمّنة والتوافق، مثل
|
||||
`plugin-sdk/feishu-setup` أو `plugin-sdk/zalo-setup`. تعامل معها على أنها
|
||||
أسطح محجوزة، وليست النمط الافتراضي لـ plugins الخارجية الجديدة.
|
||||
لا تزال بعض حدود المساعدات المُولَّدة `openclaw/plugin-sdk/<bundled-id>`
|
||||
موجودة لصيانة Plugins المضمّنة والتوافق، على سبيل المثال
|
||||
`plugin-sdk/feishu-setup` أو `plugin-sdk/zalo-setup`. تعامل مع هذه الأسطح على
|
||||
أنها أسطح محجوزة، لا على أنها النمط الافتراضي لـ Plugins الخارجية الجديدة.
|
||||
|
||||
## قائمة التحقق قبل الإرسال
|
||||
|
||||
<Check>يحتوي **package.json** على بيانات `openclaw` الوصفية الصحيحة</Check>
|
||||
<Check>يوجد manifest **openclaw.plugin.json** وهو صالح</Check>
|
||||
<Check>ملف manifest **openclaw.plugin.json** موجود وصالح</Check>
|
||||
<Check>تستخدم نقطة الإدخال `defineChannelPluginEntry` أو `definePluginEntry`</Check>
|
||||
<Check>تستخدم جميع عمليات الاستيراد مسارات مركّزة `plugin-sdk/<subpath>`</Check>
|
||||
<Check>تستخدم عمليات الاستيراد الداخلية وحدات محلية، لا عمليات استيراد ذاتية عبر SDK</Check>
|
||||
<Check>تجتاز الاختبارات (`pnpm test -- <bundled-plugin-root>/my-plugin/`)</Check>
|
||||
<Check>يجتاز `pnpm check` (للـ plugins داخل المستودع)</Check>
|
||||
<Check>تستخدم جميع عمليات الاستيراد مسارات `plugin-sdk/<subpath>` المركّزة</Check>
|
||||
<Check>تستخدم عمليات الاستيراد الداخلية وحدات محلية، وليس عمليات استيراد ذاتية عبر SDK</Check>
|
||||
<Check>تنجح الاختبارات (`pnpm test -- <bundled-plugin-root>/my-plugin/`)</Check>
|
||||
<Check>ينجح `pnpm check` (Plugins داخل المستودع)</Check>
|
||||
|
||||
## اختبار الإصدار التجريبي
|
||||
|
||||
1. راقب وسوم إصدارات GitHub على [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) واشترك عبر `Watch` > `Releases`. تبدو الوسوم التجريبية مثل `v2026.3.N-beta.1`. ويمكنك أيضًا تفعيل الإشعارات للحساب الرسمي لـ OpenClaw على X [@openclaw](https://x.com/openclaw) للإعلانات الخاصة بالإصدارات.
|
||||
2. اختبر plugin الخاص بك مقابل الوسم التجريبي بمجرد ظهوره. وعادةً ما تكون النافذة قبل الإصدار المستقر بضع ساعات فقط.
|
||||
3. انشر في سلسلة plugin الخاصة بك في قناة Discord `plugin-forum` بعد الاختبار بإحدى العبارتين `all good` أو ما الذي تعطل. وإذا لم تكن لديك سلسلة بعد، فأنشئ واحدة.
|
||||
4. إذا تعطل شيء ما، فافتح أو حدّث issue بعنوان `Beta blocker: <plugin-name> - <summary>` وطبّق الوسم `beta-blocker`. ضَع رابط issue في سلسلتك.
|
||||
5. افتح PR إلى `main` بعنوان `fix(<plugin-id>): beta blocker - <summary>` واربط issue في كل من PR وسلسلة Discord الخاصة بك. لا يستطيع المساهمون إضافة وسوم إلى PRs، لذا فالعنوان هو الإشارة الخاصة بـ PR للمشرفين وللأتمتة. يتم دمج المشكلات الحرجة التي لها PR؛ أما التي لا تملك واحدًا فقد تُشحن على أي حال. يراقب المشرفون هذه السلاسل أثناء الاختبار التجريبي.
|
||||
6. الصمت يعني أن كل شيء على ما يرام. وإذا فاتتك النافذة، فمن المرجح أن يصل إصلاحك في الدورة التالية.
|
||||
1. راقب وسوم إصدارات GitHub في [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) واشترك عبر `Watch` > `Releases`. تبدو وسوم الإصدارات التجريبية مثل `v2026.3.N-beta.1`. يمكنك أيضًا تفعيل الإشعارات لحساب OpenClaw الرسمي على X [@openclaw](https://x.com/openclaw) لإعلانات الإصدارات.
|
||||
2. اختبر Plugin الخاص بك مع الوسم التجريبي فور ظهوره. تكون المهلة قبل الإصدار المستقر عادة بضع ساعات فقط.
|
||||
3. انشر في سلسلة Plugin الخاص بك في قناة Discord `plugin-forum` بعد الاختبار بإحدى العبارتين: `all good` أو ما الذي تعطّل. إذا لم تكن لديك سلسلة بعد، فأنشئ واحدة.
|
||||
4. إذا تعطّل شيء ما، فافتح Issue أو حدّث واحدة بعنوان `Beta blocker: <plugin-name> - <summary>` وطبّق التصنيف `beta-blocker`. ضع رابط الـ Issue في سلسلتك.
|
||||
5. افتح PR إلى `main` بعنوان `fix(<plugin-id>): beta blocker - <summary>` واربط الـ Issue في كلٍّ من PR وسلسلة Discord الخاصة بك. لا يمكن للمساهمين وضع تصنيفات على PRs، لذا يُعد العنوان الإشارة في جهة PR للمشرفين والأتمتة. يتم دمج العناصر المانعة مع PR؛ أما العناصر المانعة من دون PR فقد تُشحن على أي حال. يراقب المشرفون هذه السلاسل أثناء اختبار الإصدارات التجريبية.
|
||||
6. عدم وجود ردود يعني أن كل شيء جيد. إذا فاتتك المهلة، فمن المرجّح أن يصل إصلاحك في الدورة التالية.
|
||||
|
||||
## الخطوات التالية
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Channel Plugins" icon="messages-square" href="/ar/plugins/sdk-channel-plugins">
|
||||
ابنِ Channel plugin للمراسلة
|
||||
<Card title="Plugins القنوات" icon="messages-square" href="/ar/plugins/sdk-channel-plugins">
|
||||
أنشئ Plugin لقناة مراسلة
|
||||
</Card>
|
||||
<Card title="Provider Plugins" icon="cpu" href="/ar/plugins/sdk-provider-plugins">
|
||||
ابنِ Provider plugin للنماذج
|
||||
<Card title="Plugins الموفّر" icon="cpu" href="/ar/plugins/sdk-provider-plugins">
|
||||
أنشئ Plugin لموفّر نماذج
|
||||
</Card>
|
||||
<Card title="SDK Overview" icon="book-open" href="/ar/plugins/sdk-overview">
|
||||
<Card title="نظرة عامة على SDK" icon="book-open" href="/ar/plugins/sdk-overview">
|
||||
مرجع خريطة الاستيراد وAPI التسجيل
|
||||
</Card>
|
||||
<Card title="Runtime Helpers" icon="settings" href="/ar/plugins/sdk-runtime">
|
||||
<Card title="مساعدات Runtime" icon="settings" href="/ar/plugins/sdk-runtime">
|
||||
TTS والبحث وsubagent عبر api.runtime
|
||||
</Card>
|
||||
<Card title="Testing" icon="test-tubes" href="/ar/plugins/sdk-testing">
|
||||
<Card title="الاختبار" icon="test-tubes" href="/ar/plugins/sdk-testing">
|
||||
أدوات وأنماط الاختبار
|
||||
</Card>
|
||||
<Card title="Plugin Manifest" icon="file-json" href="/ar/plugins/manifest">
|
||||
@ -324,8 +331,8 @@ barrel الموجودة في جذر الحزمة ما لم تكن نقطة ال
|
||||
|
||||
## ذو صلة
|
||||
|
||||
- [بنية plugin](/ar/plugins/architecture) — نظرة عميقة على البنية الداخلية
|
||||
- [معمارية Plugin](/ar/plugins/architecture) — شرح معماري داخلي متعمّق
|
||||
- [نظرة عامة على SDK](/ar/plugins/sdk-overview) — مرجع Plugin SDK
|
||||
- [Manifest](/ar/plugins/manifest) — تنسيق manifest الخاص بالـ plugin
|
||||
- [Channel Plugins](/ar/plugins/sdk-channel-plugins) — بناء Channel plugins
|
||||
- [Provider Plugins](/ar/plugins/sdk-provider-plugins) — بناء Provider plugins
|
||||
- [Plugins القنوات](/ar/plugins/sdk-channel-plugins) — بناء Plugins القنوات
|
||||
- [Plugins الموفّر](/ar/plugins/sdk-provider-plugins) — بناء Plugins الموفّر
|
||||
|
||||
@ -1,66 +1,65 @@
|
||||
---
|
||||
read_when:
|
||||
- تريد استخدام حزام app-server المضمّن لـ Codex
|
||||
- أنت بحاجة إلى مراجع نماذج Codex وأمثلة إعدادات
|
||||
- تريد تعطيل الرجوع إلى Pi لعمليات النشر التي تستخدم Codex فقط
|
||||
summary: شغّل أدوار الوكيل المضمّن في OpenClaw عبر حزام app-server المضمّن لـ Codex
|
||||
title: حزام Codex
|
||||
- تريد استخدام حزمة تسخير app-server الخاصة بـ Codex
|
||||
- تحتاج إلى مراجع نماذج Codex وأمثلة على الإعدادات
|
||||
- تريد تعطيل الرجوع الاحتياطي إلى Pi لعمليات النشر الخاصة بـ Codex فقط
|
||||
summary: شغّل أدوار الوكيل المضمّن في OpenClaw عبر حزمة تسخير app-server الخاصة بـ Codex
|
||||
title: حزمة تسخير Codex
|
||||
x-i18n:
|
||||
generated_at: "2026-04-21T07:22:35Z"
|
||||
generated_at: "2026-04-22T07:17:56Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 3f0cdaf68be3b2257de1046103ff04f53f9d3a65ffc15ab7af5ab1f425643d6c
|
||||
source_hash: d45dbd39a7d8ebb3a39d8dca3a5125c07b7168d1658ca07b85792645fb98613c
|
||||
source_path: plugins/codex-harness.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# حزام Codex
|
||||
# حزمة تسخير Codex
|
||||
|
||||
يتيح Plugin `codex` المضمّن لـ OpenClaw تشغيل أدوار الوكيل المضمّن عبر
|
||||
Codex app-server بدلًا من حزام Pi المضمّن.
|
||||
يتيح Plugin `codex` المضمّن لـ OpenClaw تشغيل أدوار الوكيل المضمّن عبر
|
||||
خادم تطبيقات Codex بدلًا من حزمة تسخير PI المدمجة.
|
||||
|
||||
استخدم هذا عندما تريد أن يتولى Codex جلسة الوكيل منخفضة المستوى: اكتشاف
|
||||
النموذج، واستئناف الخيوط الأصلي، وCompaction الأصلي، وتنفيذ app-server.
|
||||
يظل OpenClaw مسؤولًا عن قنوات الدردشة، وملفات الجلسات، واختيار النموذج، والأدوات،
|
||||
والموافقات، وتسليم الوسائط، ونسخة transcript المرئية.
|
||||
النموذج، والاستئناف الأصلي للخيط، وCompaction الأصلية، والتنفيذ عبر خادم
|
||||
التطبيقات. يظل OpenClaw مسؤولًا عن قنوات الدردشة، وملفات الجلسات، واختيار
|
||||
النموذج، والأدوات، والموافقات، وتسليم الوسائط، ونسخة السجل الظاهرة.
|
||||
|
||||
يكون الحزام معطّلًا افتراضيًا. ولا يتم اختياره إلا عندما يكون Plugin `codex`
|
||||
مفعّلًا ويكون النموذج المحلول نموذج `codex/*`، أو عندما تفرض صراحةً
|
||||
تكون حزمة التسخير معطّلة افتراضيًا. ويتم اختيارها فقط عندما يكون Plugin `codex`
|
||||
مفعّلًا ويكون النموذج المحلول نموذجًا من نوع `codex/*`، أو عندما تفرض صراحةً
|
||||
`embeddedHarness.runtime: "codex"` أو `OPENCLAW_AGENT_RUNTIME=codex`.
|
||||
إذا لم تضبط أبدًا `codex/*`، فإن تشغيلات PI وOpenAI وAnthropic وGemini وlocal
|
||||
وcustom-provider الحالية تحتفظ بسلوكها الحالي.
|
||||
إذا لم تقم مطلقًا بتهيئة `codex/*`، فستحافظ تشغيلات PI وOpenAI وAnthropic وGemini وlocal
|
||||
وcustom-provider الحالية على سلوكها الحالي.
|
||||
|
||||
## اختر بادئة النموذج الصحيحة
|
||||
## اختر بادئة النموذج المناسبة
|
||||
|
||||
يمتلك OpenClaw مسارات منفصلة للوصول بشكل OpenAI وبشكل Codex:
|
||||
يحتوي OpenClaw على مسارات منفصلة للوصول على هيئة OpenAI والوصول على هيئة Codex:
|
||||
|
||||
| مرجع النموذج | مسار وقت التشغيل | استخدمه عندما |
|
||||
| ---------------------- | --------------------------------------------- | ------------------------------------------------------------------------- |
|
||||
| `openai/gpt-5.4` | مزود OpenAI عبر مسار OpenClaw/PI | تريد وصولًا مباشرًا إلى OpenAI Platform API باستخدام `OPENAI_API_KEY`. |
|
||||
| `openai-codex/gpt-5.4` | مزود OpenAI Codex OAuth عبر PI | تريد ChatGPT/Codex OAuth بدون حزام Codex app-server. |
|
||||
| `codex/gpt-5.4` | مزود Codex المضمّن مع حزام Codex | تريد تنفيذًا أصليًا عبر Codex app-server لدور الوكيل المضمّن. |
|
||||
| مرجع النموذج | مسار وقت التشغيل | استخدم هذا عندما |
|
||||
| --------------------- | --------------------------------------------- | ------------------------------------------------------------------------- |
|
||||
| `openai/gpt-5.4` | مزود OpenAI عبر بنية OpenClaw/PI | تريد وصولًا مباشرًا إلى OpenAI Platform API باستخدام `OPENAI_API_KEY`. |
|
||||
| `openai-codex/gpt-5.4` | مزود OpenAI Codex OAuth عبر PI | تريد ChatGPT/Codex OAuth من دون حزمة تسخير خادم تطبيقات Codex. |
|
||||
| `codex/gpt-5.4` | مزود Codex المضمّن بالإضافة إلى حزمة تسخير Codex | تريد تنفيذًا أصليًا عبر خادم تطبيقات Codex لدور الوكيل المضمّن. |
|
||||
|
||||
لا يطالب حزام Codex إلا بمراجع النماذج `codex/*`. أما مراجع `openai/*`
|
||||
و`openai-codex/*` وAnthropic وGemini وxAI وlocal وcustom provider الحالية
|
||||
فتحتفظ بمساراتها العادية.
|
||||
لا تتولى حزمة تسخير Codex إلا مراجع النماذج `codex/*`. أما مراجع `openai/*`
|
||||
و`openai-codex/*` وAnthropic وGemini وxAI وlocal وcustom provider الحالية فتبقى
|
||||
على مساراتها العادية.
|
||||
|
||||
## المتطلبات
|
||||
|
||||
- OpenClaw مع توفر Plugin `codex` المضمّن.
|
||||
- Codex app-server بالإصدار `0.118.0` أو أحدث.
|
||||
- توفر مصادقة Codex لعملية app-server.
|
||||
- OpenClaw مع توفر Plugin `codex` المضمّن.
|
||||
- خادم تطبيقات Codex بالإصدار `0.118.0` أو أحدث.
|
||||
- توفر مصادقة Codex لعملية خادم التطبيقات.
|
||||
|
||||
يمنع Plugin مصافحات app-server الأقدم أو غير المرقّمة بالإصدار. وهذا يُبقي
|
||||
OpenClaw على سطح البروتوكول الذي تم اختباره معه.
|
||||
يحظر Plugin مصافحات خادم التطبيقات الأقدم أو غير ذات الإصدار. وهذا يُبقي
|
||||
OpenClaw على سطح البروتوكول الذي تم اختباره عليه.
|
||||
|
||||
بالنسبة لاختبارات smoke الحية وDocker، تأتي المصادقة عادةً من `OPENAI_API_KEY`، مع
|
||||
ملفات Codex CLI الاختيارية مثل `~/.codex/auth.json` و
|
||||
`~/.codex/config.toml`. استخدم مادة المصادقة نفسها التي يستخدمها Codex app-server
|
||||
المحلي لديك.
|
||||
في اختبارات التشغيل الحي واختبارات Docker الدخانية، تأتي المصادقة عادةً من
|
||||
`OPENAI_API_KEY`، بالإضافة إلى ملفات Codex CLI الاختيارية مثل `~/.codex/auth.json` و
|
||||
`~/.codex/config.toml`. استخدم مواد المصادقة نفسها التي يستخدمها خادم تطبيقات Codex المحلي لديك.
|
||||
|
||||
## الحد الأدنى من الإعدادات
|
||||
|
||||
استخدم `codex/gpt-5.4`، وفعّل Plugin المضمّن، وافرِض حزام `codex`:
|
||||
استخدم `codex/gpt-5.4`، وفعّل Plugin المضمّن، وافرِض حزمة تسخير `codex`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -83,7 +82,7 @@ OpenClaw على سطح البروتوكول الذي تم اختباره معه.
|
||||
}
|
||||
```
|
||||
|
||||
إذا كانت إعداداتك تستخدم `plugins.allow`، فأدرج `codex` هناك أيضًا:
|
||||
إذا كان إعدادك يستخدم `plugins.allow`، فأدرج `codex` هناك أيضًا:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -98,13 +97,13 @@ OpenClaw على سطح البروتوكول الذي تم اختباره معه.
|
||||
}
|
||||
```
|
||||
|
||||
يؤدي ضبط `agents.defaults.model` أو نموذج وكيل إلى `codex/<model>` أيضًا
|
||||
إلى التفعيل التلقائي لـ Plugin `codex` المضمّن. ولا يزال إدخال Plugin الصريح
|
||||
مفيدًا في الإعدادات المشتركة لأنه يجعل نية النشر واضحة.
|
||||
كما أن تعيين `agents.defaults.model` أو نموذج وكيل إلى `codex/<model>` يؤدي أيضًا
|
||||
إلى التفعيل التلقائي لـ Plugin `codex` المضمّن. وتظل إضافة Plugin الصريحة مفيدة
|
||||
في الإعدادات المشتركة لأنها توضّح نية النشر بوضوح.
|
||||
|
||||
## أضف Codex بدون استبدال النماذج الأخرى
|
||||
## أضف Codex من دون استبدال النماذج الأخرى
|
||||
|
||||
احتفظ بالقيمة `runtime: "auto"` عندما تريد Codex لنماذج `codex/*` وPI لكل
|
||||
أبقِ `runtime: "auto"` عندما تريد Codex لنماذج `codex/*` وPI لكل
|
||||
شيء آخر:
|
||||
|
||||
```json5
|
||||
@ -139,15 +138,15 @@ OpenClaw على سطح البروتوكول الذي تم اختباره معه.
|
||||
|
||||
مع هذا الشكل:
|
||||
|
||||
- يستخدم `/model codex` أو `/model codex/gpt-5.4` حزام Codex app-server.
|
||||
- يستخدم `/model codex` أو `/model codex/gpt-5.4` حزمة تسخير خادم تطبيقات Codex.
|
||||
- يستخدم `/model gpt` أو `/model openai/gpt-5.4` مسار مزود OpenAI.
|
||||
- يستخدم `/model opus` مسار مزود Anthropic.
|
||||
- إذا تم اختيار نموذج غير Codex، يظل PI حزام التوافق.
|
||||
- إذا تم اختيار نموذج غير Codex، يظل PI هو حزمة التسخير التوافقية.
|
||||
|
||||
## عمليات النشر التي تستخدم Codex فقط
|
||||
## عمليات النشر الخاصة بـ Codex فقط
|
||||
|
||||
عطّل الرجوع إلى Pi عندما تحتاج إلى إثبات أن كل دور وكيل مضمّن يستخدم
|
||||
حزام Codex:
|
||||
عطّل الرجوع الاحتياطي إلى PI عندما تحتاج إلى إثبات أن كل دور للوكيل المضمّن يستخدم
|
||||
حزمة تسخير Codex:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -171,14 +170,14 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \
|
||||
openclaw gateway run
|
||||
```
|
||||
|
||||
مع تعطيل الرجوع، يفشل OpenClaw مبكرًا إذا كان Plugin Codex معطّلًا،
|
||||
أو لم يكن النموذج المطلوب مرجع `codex/*`، أو كان app-server قديمًا جدًا، أو
|
||||
تعذر بدء app-server.
|
||||
عند تعطيل الرجوع الاحتياطي، يفشل OpenClaw مبكرًا إذا كان Plugin Codex معطّلًا،
|
||||
أو إذا لم يكن النموذج المطلوب مرجعًا من نوع `codex/*`، أو إذا كان خادم التطبيقات قديمًا جدًا،
|
||||
أو إذا تعذر بدء خادم التطبيقات.
|
||||
|
||||
## Codex لكل وكيل
|
||||
|
||||
يمكنك جعل وكيل واحد يستخدم Codex فقط بينما يحتفظ الوكيل الافتراضي بالاختيار
|
||||
التلقائي العادي:
|
||||
يمكنك جعل وكيل واحد يعمل بـ Codex فقط بينما يحتفظ الوكيل الافتراضي
|
||||
بالاختيار التلقائي العادي:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -210,19 +209,19 @@ openclaw gateway run
|
||||
```
|
||||
|
||||
استخدم أوامر الجلسة العادية للتبديل بين الوكلاء والنماذج. ينشئ `/new` جلسة
|
||||
OpenClaw جديدة وينشئ حزام Codex أو يستأنف خيط app-server الجانبي حسب
|
||||
الحاجة. ويمسح `/reset` ربط جلسة OpenClaw لذلك الخيط.
|
||||
OpenClaw جديدة، وتقوم حزمة تسخير Codex بإنشاء خيط خادم التطبيقات الجانبي أو
|
||||
استئنافه حسب الحاجة. يقوم `/reset` بمسح ربط جلسة OpenClaw لذلك الخيط.
|
||||
|
||||
## اكتشاف النموذج
|
||||
|
||||
افتراضيًا، يطلب Plugin Codex من app-server النماذج المتاحة. وإذا
|
||||
فشل الاكتشاف أو انتهت مهلته، فإنه يستخدم catalog الاحتياطي المضمّن:
|
||||
افتراضيًا، يطلب Plugin Codex من خادم التطبيقات النماذج المتاحة. إذا فشل
|
||||
الاكتشاف أو انتهت مهلته، فإنه يستخدم فهرس الرجوع الاحتياطي المضمّن:
|
||||
|
||||
- `codex/gpt-5.4`
|
||||
- `codex/gpt-5.4-mini`
|
||||
- `codex/gpt-5.2`
|
||||
|
||||
يمكنك ضبط الاكتشاف تحت `plugins.entries.codex.config.discovery`:
|
||||
يمكنك ضبط الاكتشاف ضمن `plugins.entries.codex.config.discovery`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -242,8 +241,8 @@ OpenClaw جديدة وينشئ حزام Codex أو يستأنف خيط app-serve
|
||||
}
|
||||
```
|
||||
|
||||
عطّل الاكتشاف عندما تريد أن يتجنب بدء التشغيل فحص Codex ويلتزم بـ
|
||||
catalog الاحتياطي:
|
||||
عطّل الاكتشاف عندما تريد أن يتجنب بدء التشغيل فحص Codex وأن يلتزم
|
||||
بفهرس الرجوع الاحتياطي:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -262,16 +261,16 @@ catalog الاحتياطي:
|
||||
}
|
||||
```
|
||||
|
||||
## اتصال app-server والسياسة
|
||||
## اتصال خادم التطبيقات والسياسة
|
||||
|
||||
افتراضيًا، يبدأ Plugin Codex محليًا باستخدام:
|
||||
افتراضيًا، يبدأ Plugin Codex محليًا باستخدام:
|
||||
|
||||
```bash
|
||||
codex app-server --listen stdio://
|
||||
```
|
||||
|
||||
افتراضيًا، يطلب OpenClaw من Codex طلب الموافقات الأصلية. ويمكنك ضبط هذه
|
||||
السياسة أكثر، مثلًا عبر تشديدها وتوجيه المراجعات عبر guardian:
|
||||
افتراضيًا، يطلب OpenClaw من Codex طلب موافقات أصلية. ويمكنك ضبط هذه
|
||||
السياسة بشكل أكبر، مثل تشديدها وتوجيه المراجعات عبر guardian:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -293,7 +292,7 @@ codex app-server --listen stdio://
|
||||
}
|
||||
```
|
||||
|
||||
بالنسبة إلى app-server قيد التشغيل بالفعل، استخدم نقل WebSocket:
|
||||
بالنسبة إلى خادم تطبيقات قيد التشغيل بالفعل، استخدم نقل WebSocket:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -317,22 +316,22 @@ codex app-server --listen stdio://
|
||||
|
||||
حقول `appServer` المدعومة:
|
||||
|
||||
| الحقل | الافتراضي | المعنى |
|
||||
| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------ |
|
||||
| `transport` | `"stdio"` | يقوم `"stdio"` ببدء Codex؛ ويتصل `"websocket"` إلى `url`. |
|
||||
| `command` | `"codex"` | الملف التنفيذي لنقل stdio. |
|
||||
| `args` | `["app-server", "--listen", "stdio://"]` | الوسائط لنقل stdio. |
|
||||
| `url` | غير مضبوط | عنوان WebSocket لـ app-server. |
|
||||
| `authToken` | غير مضبوط | Bearer token لنقل WebSocket. |
|
||||
| `headers` | `{}` | ترويسات WebSocket إضافية. |
|
||||
| `requestTimeoutMs` | `60000` | المهلة لاستدعاءات مستوى التحكم في app-server. |
|
||||
| `approvalPolicy` | `"on-request"` | سياسة موافقة Codex الأصلية المرسلة عند بدء/استئناف/دور الخيط. |
|
||||
| `sandbox` | `"workspace-write"` | وضع sandbox الأصلي لـ Codex المرسل عند بدء/استئناف الخيط. |
|
||||
| `approvalsReviewer` | `"user"` | استخدم `"guardian_subagent"` لجعل Codex guardian يراجع الموافقات الأصلية. |
|
||||
| `serviceTier` | غير مضبوط | طبقة خدمة Codex اختيارية، مثل `"priority"`. |
|
||||
| الحقل | الافتراضي | المعنى |
|
||||
| ------------------- | ----------------------------------------- | ------------------------------------------------------------------------- |
|
||||
| `transport` | `"stdio"` | تؤدي `"stdio"` إلى تشغيل Codex؛ وتؤدي `"websocket"` إلى الاتصال بـ `url`. |
|
||||
| `command` | `"codex"` | الملف التنفيذي لنقل stdio. |
|
||||
| `args` | `["app-server", "--listen", "stdio://"]` | الوسيطات الخاصة بنقل stdio. |
|
||||
| `url` | غير معيّن | عنوان URL لخادم تطبيقات WebSocket. |
|
||||
| `authToken` | غير معيّن | Bearer token لنقل WebSocket. |
|
||||
| `headers` | `{}` | ترويسات WebSocket إضافية. |
|
||||
| `requestTimeoutMs` | `60000` | المهلة الزمنية لاستدعاءات مستوى التحكم الخاصة بخادم التطبيقات. |
|
||||
| `approvalPolicy` | `"on-request"` | سياسة موافقات Codex الأصلية المُرسلة إلى بدء/استئناف/دور الخيط. |
|
||||
| `sandbox` | `"workspace-write"` | وضع sandbox الأصلي في Codex المُرسل إلى بدء/استئناف الخيط. |
|
||||
| `approvalsReviewer` | `"user"` | استخدم `"guardian_subagent"` للسماح لـ guardian في Codex بمراجعة الموافقات الأصلية. |
|
||||
| `serviceTier` | غير معيّن | طبقة خدمة Codex اختيارية، مثل `"priority"`. |
|
||||
|
||||
لا تزال متغيرات البيئة الأقدم تعمل كبدائل لاختبارات local عندما
|
||||
يكون حقل الإعداد المطابق غير مضبوط:
|
||||
لا تزال متغيرات البيئة الأقدم تعمل كخيارات رجوع احتياطي للاختبارات المحلية عندما
|
||||
يكون حقل الإعداد المطابق غير معيّن:
|
||||
|
||||
- `OPENCLAW_CODEX_APP_SERVER_BIN`
|
||||
- `OPENCLAW_CODEX_APP_SERVER_ARGS`
|
||||
@ -340,7 +339,7 @@ codex app-server --listen stdio://
|
||||
- `OPENCLAW_CODEX_APP_SERVER_SANDBOX`
|
||||
- `OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1`
|
||||
|
||||
تُفضَّل الإعدادات من أجل عمليات نشر قابلة للتكرار.
|
||||
تُفضَّل الإعدادات لعمليات النشر القابلة لإعادة الإنتاج.
|
||||
|
||||
## وصفات شائعة
|
||||
|
||||
@ -358,7 +357,7 @@ Codex محلي مع نقل stdio الافتراضي:
|
||||
}
|
||||
```
|
||||
|
||||
التحقق من الحزام الذي يستخدم Codex فقط، مع تعطيل الرجوع إلى Pi:
|
||||
التحقق من حزمة تسخير Codex فقط، مع تعطيل الرجوع الاحتياطي إلى PI:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -375,7 +374,7 @@ Codex محلي مع نقل stdio الافتراضي:
|
||||
}
|
||||
```
|
||||
|
||||
موافقات Codex يراجعها guardian:
|
||||
موافقات Codex التي يراجعها guardian:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -396,7 +395,7 @@ Codex محلي مع نقل stdio الافتراضي:
|
||||
}
|
||||
```
|
||||
|
||||
app-server بعيد مع ترويسات صريحة:
|
||||
خادم تطبيقات بعيد مع ترويسات صريحة:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -419,80 +418,84 @@ app-server بعيد مع ترويسات صريحة:
|
||||
}
|
||||
```
|
||||
|
||||
يبقى تبديل النماذج تحت تحكم OpenClaw. عندما تكون جلسة OpenClaw مرفقة
|
||||
بخيط Codex موجود، يرسل الدور التالي النموذج المحدد حاليًا
|
||||
`codex/*`، والمزوّد، وسياسة الموافقة، وsandbox، وservice tier إلى
|
||||
app-server مرة أخرى. يؤدي التبديل من `codex/gpt-5.4` إلى `codex/gpt-5.2` إلى
|
||||
الاحتفاظ بربط الخيط لكنه يطلب من Codex المتابعة باستخدام النموذج المحدد حديثًا.
|
||||
يبقى تبديل النموذج تحت تحكم OpenClaw. عندما تكون جلسة OpenClaw مرفقة
|
||||
بخيط Codex موجود، يرسل الدور التالي النموذج المحدد حاليًا من نوع
|
||||
`codex/*`، والمزود، وسياسة الموافقة، وsandbox، وطبقة الخدمة إلى
|
||||
خادم التطبيقات مرة أخرى. يؤدي التبديل من `codex/gpt-5.4` إلى `codex/gpt-5.2`
|
||||
إلى الإبقاء على ربط الخيط، لكنه يطلب من Codex المتابعة بالنموذج المحدد حديثًا.
|
||||
|
||||
## أمر Codex
|
||||
|
||||
يسجل Plugin المضمّن الأمر `/codex` كأمر slash مخوّل. وهو
|
||||
عام ويعمل على أي قناة تدعم أوامر النص في OpenClaw.
|
||||
يسجل Plugin المضمّن `/codex` بوصفه أمر slash مصرحًا به. وهو
|
||||
عام ويعمل على أي قناة تدعم أوامر OpenClaw النصية.
|
||||
|
||||
الصيغ الشائعة:
|
||||
|
||||
- يعرض `/codex status` الاتصال الحي بـ app-server، والنماذج، والحساب، وحدود المعدل، وخوادم MCP، وSkills.
|
||||
- يسرد `/codex models` نماذج Codex app-server الحية.
|
||||
- يسرد `/codex threads [filter]` أحدث خيوط Codex.
|
||||
- يعرض `/codex status` حالة الاتصال الحي بخادم التطبيقات، والنماذج، والحساب، وحدود المعدل، وخوادم MCP، وSkills.
|
||||
- يسرد `/codex models` نماذج خادم تطبيقات Codex الحية.
|
||||
- يسرد `/codex threads [filter]` خيوط Codex الحديثة.
|
||||
- يربط `/codex resume <thread-id>` جلسة OpenClaw الحالية بخيط Codex موجود.
|
||||
- يطلب `/codex compact` من Codex app-server تنفيذ Compaction للخيط المرفق.
|
||||
- يبدأ `/codex review` مراجعة Codex الأصلية للخيط المرفق.
|
||||
- يعرض `/codex account` حالة الحساب وحد المعدل.
|
||||
- يسرد `/codex mcp` حالة خادم MCP في Codex app-server.
|
||||
- يسرد `/codex skills` Skills في Codex app-server.
|
||||
- يطلب `/codex compact` من خادم تطبيقات Codex إجراء Compaction للخيط المرفق.
|
||||
- يبدأ `/codex review` المراجعة الأصلية في Codex للخيط المرفق.
|
||||
- يعرض `/codex account` حالة الحساب وحدود المعدل.
|
||||
- يسرد `/codex mcp` حالة خادم MCP في خادم تطبيقات Codex.
|
||||
- يسرد `/codex skills` Skills في خادم تطبيقات Codex.
|
||||
|
||||
يكتب `/codex resume` ملف الربط الجانبي نفسه الذي يستخدمه الحزام في
|
||||
الأدوار العادية. وفي الرسالة التالية، يستأنف OpenClaw خيط Codex ذلك، ويمرّر
|
||||
نموذج OpenClaw الحالي المحدد `codex/*` إلى app-server، ويُبقي
|
||||
السجل الموسّع مفعّلًا.
|
||||
يكتب `/codex resume` ملف ربط sidecar نفسه الذي تستخدمه حزمة التسخير في
|
||||
الأدوار العادية. في الرسالة التالية، يستأنف OpenClaw خيط Codex ذلك، ويمرر
|
||||
نموذج OpenClaw `codex/*` المحدد حاليًا إلى خادم التطبيقات، ويحافظ على
|
||||
تفعيل السجل الموسّع.
|
||||
|
||||
يتطلب سطح الأوامر Codex app-server بالإصدار `0.118.0` أو أحدث. ويتم
|
||||
الإبلاغ عن طرق التحكم الفردية على أنها `unsupported by this Codex app-server` إذا
|
||||
لم يكشف app-server مستقبلي أو مخصص عن طريقة JSON-RPC تلك.
|
||||
يتطلب سطح الأوامر خادم تطبيقات Codex بالإصدار `0.118.0` أو أحدث. ويتم
|
||||
الإبلاغ عن أساليب التحكم الفردية على أنها `unsupported by this Codex app-server` إذا كان
|
||||
خادم تطبيقات مستقبلي أو مخصص لا يكشف أسلوب JSON-RPC هذا.
|
||||
|
||||
## الأدوات، والوسائط، وCompaction
|
||||
## الأدوات والوسائط وCompaction
|
||||
|
||||
يغيّر حزام Codex منفّذ الوكيل المضمّن منخفض المستوى فقط.
|
||||
تغيّر حزمة تسخير Codex منفّذ الوكيل المضمّن منخفض المستوى فقط.
|
||||
|
||||
يظل OpenClaw يبني قائمة الأدوات ويتلقى نتائج الأدوات الديناميكية من
|
||||
الحزام. ويستمر النص، والصور، والفيديو، والموسيقى، وTTS، والموافقات، ومخرجات
|
||||
أدوات المراسلة عبر مسار التسليم العادي في OpenClaw.
|
||||
يواصل OpenClaw إنشاء قائمة الأدوات واستقبال نتائج الأدوات الديناميكية من
|
||||
حزمة التسخير. وتستمر النصوص والصور والفيديو والموسيقى وTTS والموافقات
|
||||
ومخرجات أدوات المراسلة عبر مسار التسليم العادي في OpenClaw.
|
||||
|
||||
عندما يستخدم النموذج المحدد حزام Codex، يتم تفويض Compaction الخيط
|
||||
الأصلي إلى Codex app-server. يحتفظ OpenClaw بنسخة transcript
|
||||
لأجل سجل القناة، والبحث، و`/new`، و`/reset`، والتبديل المستقبلي للنموذج أو الحزام. وتتضمن
|
||||
النسخة مطالبة المستخدم، ونص المساعد النهائي، وسجلات reasoning أو plan
|
||||
الخفيفة الخاصة بـ Codex عندما يصدرها app-server.
|
||||
عندما يستخدم النموذج المحدد حزمة تسخير Codex، يتم تفويض Compaction
|
||||
الأصلية للخيط إلى خادم تطبيقات Codex. يحتفظ OpenClaw بنسخة معكوسة من
|
||||
السجل من أجل سجل القناة، والبحث، و`/new`، و`/reset`، وعمليات التبديل
|
||||
المستقبلية للنموذج أو حزمة التسخير. وتتضمن النسخة المعكوسة مطالبة المستخدم،
|
||||
ونص المساعد النهائي، وسجلات reasoning أو الخطة الخفيفة الخاصة بـ Codex عندما
|
||||
يصدرها خادم التطبيقات.
|
||||
|
||||
لا يتطلب إنشاء الوسائط PI. وتستمر الصور، والفيديو، والموسيقى، وPDF، وTTS، وفهم
|
||||
الوسائط في استخدام إعدادات المزود/النموذج المطابقة مثل
|
||||
لا يتطلب إنشاء الوسائط PI. وتستمر عملية إنشاء الصور والفيديو والموسيقى وPDF
|
||||
وTTS وفهم الوسائط في استخدام إعدادات المزود/النموذج المطابقة مثل
|
||||
`agents.defaults.imageGenerationModel` و`videoGenerationModel` و`pdfModel` و
|
||||
`messages.tts`.
|
||||
|
||||
## استكشاف الأخطاء وإصلاحها
|
||||
|
||||
**لا يظهر Codex في `/model`:** فعّل `plugins.entries.codex.enabled`،
|
||||
واضبط مرجع نموذج `codex/*`، أو تحقّق مما إذا كان `plugins.allow` يستبعد `codex`.
|
||||
واضبط مرجع نموذج `codex/*`، أو تحقق مما إذا كان `plugins.allow` يستبعد `codex`.
|
||||
|
||||
**يعود OpenClaw إلى PI:** اضبط `embeddedHarness.fallback: "none"` أو
|
||||
`OPENCLAW_AGENT_HARNESS_FALLBACK=none` أثناء الاختبار.
|
||||
**يستخدم OpenClaw PI بدلًا من Codex:** إذا لم تطالب أي حزمة تسخير Codex
|
||||
بهذا التشغيل، فقد يستخدم OpenClaw PI كخلفية توافقية. اضبط
|
||||
`embeddedHarness.runtime: "codex"` لفرض اختيار Codex أثناء الاختبار، أو
|
||||
`embeddedHarness.fallback: "none"` للفشل عندما لا تتطابق أي حزمة تسخير Plugin. بمجرد
|
||||
اختيار خادم تطبيقات Codex، تظهر أعطاله مباشرةً من دون إعدادات رجوع احتياطي إضافية.
|
||||
|
||||
**يتم رفض app-server:** حدّث Codex بحيث تُبلغ مصافحة app-server
|
||||
**يتم رفض خادم التطبيقات:** حدّث Codex بحيث تُبلغ مصافحة خادم التطبيقات
|
||||
عن الإصدار `0.118.0` أو أحدث.
|
||||
|
||||
**اكتشاف النموذج بطيء:** خفّض `plugins.entries.codex.config.discovery.timeoutMs`
|
||||
أو عطّل الاكتشاف.
|
||||
|
||||
**يفشل نقل WebSocket فورًا:** تحقّق من `appServer.url` و
|
||||
`authToken` ومن أن app-server البعيد يتحدث بإصدار بروتوكول Codex app-server نفسه.
|
||||
**يفشل نقل WebSocket فورًا:** تحقق من `appServer.url` و`authToken`،
|
||||
ومن أن خادم التطبيقات البعيد يتحدث بإصدار بروتوكول خادم تطبيقات Codex نفسه.
|
||||
|
||||
**يستخدم نموذج غير Codex حزام PI:** هذا متوقع. لا يطالب حزام Codex إلا
|
||||
**يستخدم نموذج غير Codex PI:** هذا متوقع. لا تطالب حزمة تسخير Codex إلا
|
||||
بمراجع النماذج `codex/*`.
|
||||
|
||||
## ذات صلة
|
||||
## ذو صلة
|
||||
|
||||
- [Plugins حزام الوكيل](/ar/plugins/sdk-agent-harness)
|
||||
- [Plugins حزمة تسخير الوكيل](/ar/plugins/sdk-agent-harness)
|
||||
- [مزودو النماذج](/ar/concepts/model-providers)
|
||||
- [مرجع الإعدادات](/ar/gateway/configuration-reference)
|
||||
- [الاختبار](/ar/help/testing#live-codex-app-server-harness-smoke)
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- أنت تبني Plugin لـ OpenClaw
|
||||
- تحتاج إلى شحن مخطط تكوين للـ plugin أو تصحيح أخطاء التحقق من صحة plugin
|
||||
summary: بيان Plugin ومتطلبات مخطط JSON (تحقق صارم من التكوين)
|
||||
- تحتاج إلى شحن مخطط إعدادات Plugin أو تصحيح أخطاء التحقق من صحة Plugin
|
||||
summary: متطلبات بيان Plugin ومخطط JSON (تحقق صارم من صحة الإعدادات)
|
||||
title: بيان Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-04-22T04:24:55Z"
|
||||
generated_at: "2026-04-22T07:17:52Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 52a52f7e2c78bbef2cc51ade6eb12b6edc950237bdfc478f6e82248374c687bf
|
||||
source_hash: 085c1baccb96b8e6bd4033ad11bdd5f79bdb0daec470e977fce723c3ae38cc99
|
||||
source_path: plugins/manifest.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -17,63 +17,62 @@ x-i18n:
|
||||
|
||||
هذه الصفحة مخصصة **لبيان Plugin الأصلي في OpenClaw** فقط.
|
||||
|
||||
للتخطيطات المتوافقة الخاصة بالحزم، راجع [حزم Plugin](/ar/plugins/bundles).
|
||||
للتعرّف على تخطيطات الحِزم المتوافقة، راجع [حِزم Plugin](/ar/plugins/bundles).
|
||||
|
||||
تستخدم تنسيقات الحزم المتوافقة ملفات بيان مختلفة:
|
||||
تستخدم تنسيقات الحِزم المتوافقة ملفات بيان مختلفة:
|
||||
|
||||
- حزمة Codex: `.codex-plugin/plugin.json`
|
||||
- حزمة Claude: `.claude-plugin/plugin.json` أو تخطيط مكونات Claude
|
||||
الافتراضي من دون بيان
|
||||
- حزمة Claude: `.claude-plugin/plugin.json` أو تخطيط مكوّن Claude الافتراضي
|
||||
بدون بيان
|
||||
- حزمة Cursor: `.cursor-plugin/plugin.json`
|
||||
|
||||
يقوم OpenClaw أيضًا باكتشاف تخطيطات الحزم تلك تلقائيًا، لكنها لا تُتحقق
|
||||
يكتشف OpenClaw أيضًا تخطيطات الحِزم تلك تلقائيًا، لكنها لا تُتحقق
|
||||
مقابل مخطط `openclaw.plugin.json` الموضح هنا.
|
||||
|
||||
بالنسبة إلى الحزم المتوافقة، يقرأ OpenClaw حاليًا بيانات الحزمة الوصفية بالإضافة إلى
|
||||
جذور Skill المعلنة، وجذور أوامر Claude، والقيم الافتراضية لملف `settings.json` في حزمة Claude،
|
||||
والقيم الافتراضية لـ Claude bundle LSP، وحزم hooks المدعومة عندما يطابق التخطيط
|
||||
بالنسبة إلى الحِزم المتوافقة، يقرأ OpenClaw حاليًا بيانات تعريف الحزمة بالإضافة إلى
|
||||
جذور Skills المعلنة، وجذور أوامر Claude، وإعدادات `settings.json` الافتراضية في حزمة Claude،
|
||||
وإعدادات LSP الافتراضية في حزمة Claude، وحِزم الخطافات المدعومة عندما يتطابق التخطيط مع
|
||||
توقعات وقت تشغيل OpenClaw.
|
||||
|
||||
يجب على كل Plugin أصلي في OpenClaw **أن يوفّر** ملف `openclaw.plugin.json` في
|
||||
**جذر Plugin**. يستخدم OpenClaw هذا البيان للتحقق من التكوين
|
||||
يجب على كل Plugin أصلي في OpenClaw **أن يتضمّن** ملف `openclaw.plugin.json` في
|
||||
**جذر Plugin**. يستخدم OpenClaw هذا البيان للتحقق من صحة الإعدادات
|
||||
**من دون تنفيذ كود Plugin**. وتُعامل البيانات المفقودة أو غير الصالحة على أنها
|
||||
أخطاء Plugin وتمنع التحقق من صحة التكوين.
|
||||
أخطاء في Plugin وتمنع التحقق من صحة الإعدادات.
|
||||
|
||||
راجع دليل نظام Plugin الكامل: [Plugins](/ar/tools/plugin).
|
||||
وللاطلاع على نموذج القدرات الأصلي وإرشادات التوافق الخارجي الحالية:
|
||||
[نموذج القدرات](/ar/plugins/architecture#public-capability-model).
|
||||
وللاطلاع على نموذج الإمكانات الأصلي وإرشادات التوافق الخارجي الحالية:
|
||||
[نموذج الإمكانات](/ar/plugins/architecture#public-capability-model).
|
||||
|
||||
## ما الذي يفعله هذا الملف
|
||||
|
||||
يمثل `openclaw.plugin.json` البيانات الوصفية التي يقرؤها OpenClaw قبل تحميل
|
||||
يمثل `openclaw.plugin.json` بيانات التعريف التي يقرأها OpenClaw قبل أن يحمّل
|
||||
كود Plugin الخاص بك.
|
||||
|
||||
استخدمه من أجل:
|
||||
|
||||
- هوية Plugin
|
||||
- التحقق من صحة التكوين
|
||||
- بيانات المصادقة والإعداد الأولي الوصفية التي يجب أن تكون متاحة من دون تشغيل
|
||||
وقت تشغيل Plugin
|
||||
- تلميحات تفعيل منخفضة التكلفة يمكن لأسطح مستوى التحكم فحصها قبل تحميل وقت التشغيل
|
||||
- واصفات إعداد منخفضة التكلفة يمكن لأسطح الإعداد/الإعداد الأولي فحصها قبل
|
||||
- التحقق من صحة الإعدادات
|
||||
- بيانات تعريف المصادقة والإعداد الأوّلي التي يجب أن تكون متاحة من دون تشغيل وقت تشغيل Plugin
|
||||
- تلميحات تفعيل منخفضة التكلفة يمكن لواجهات مستوى التحكّم فحصها قبل تحميل وقت التشغيل
|
||||
- واصفات إعداد منخفضة التكلفة يمكن لواجهات الإعداد/الإعداد الأوّلي فحصها قبل
|
||||
تحميل وقت التشغيل
|
||||
- بيانات الأسماء المستعارة والتفعيل التلقائي التي يجب حلها قبل تحميل وقت تشغيل Plugin
|
||||
- بيانات ملكية مختصرة لعائلات النماذج يجب أن تفعّل
|
||||
- بيانات تعريف الأسماء المستعارة والتفعيل التلقائي التي يجب حلّها قبل تحميل وقت تشغيل Plugin
|
||||
- بيانات تعريف مختصرة لملكية عائلات النماذج يجب أن تفعّل
|
||||
Plugin تلقائيًا قبل تحميل وقت التشغيل
|
||||
- لقطات ثابتة لملكية القدرات تُستخدم لأسلاك التوافق المرفقة وتغطية العقود
|
||||
- بيانات وصفية منخفضة التكلفة لمشغل QA يمكن للمضيف المشترك `openclaw qa` فحصها
|
||||
- لقطات ثابتة لملكية الإمكانات تُستخدم في توصيل التوافق المضمّن وتغطية العقود
|
||||
- بيانات تعريف منخفضة التكلفة لمشغّل QA يمكن لمضيف `openclaw qa` المشترك فحصها
|
||||
قبل تحميل وقت تشغيل Plugin
|
||||
- بيانات وصفية خاصة بتكوين القناة يجب دمجها في الكتالوج وأسطح التحقق
|
||||
- بيانات تعريف إعدادات خاصة بالقناة يجب دمجها في أسطح الفهرسة والتحقق
|
||||
من دون تحميل وقت التشغيل
|
||||
- تلميحات UI الخاصة بالتكوين
|
||||
- تلميحات واجهة مستخدم للإعدادات
|
||||
|
||||
لا تستخدمه من أجل:
|
||||
|
||||
- تسجيل سلوك وقت التشغيل
|
||||
- إعلان نقاط دخول الكود
|
||||
- بيانات تثبيت npm الوصفية
|
||||
- التصريح بنقاط إدخال الكود
|
||||
- بيانات تعريف تثبيت npm
|
||||
|
||||
فهذه تخص كود Plugin و`package.json`.
|
||||
فهذه تنتمي إلى كود Plugin و`package.json`.
|
||||
|
||||
## مثال أدنى
|
||||
|
||||
@ -88,13 +87,13 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
## مثال غني
|
||||
## مثال موسّع
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "openrouter",
|
||||
"name": "OpenRouter",
|
||||
"description": "Plugin مزود OpenRouter",
|
||||
"description": "OpenRouter provider plugin",
|
||||
"version": "1.0.0",
|
||||
"providers": ["openrouter"],
|
||||
"modelSupport": {
|
||||
@ -122,19 +121,19 @@ x-i18n:
|
||||
"provider": "openrouter",
|
||||
"method": "api-key",
|
||||
"choiceId": "openrouter-api-key",
|
||||
"choiceLabel": "مفتاح OpenRouter API",
|
||||
"choiceLabel": "OpenRouter API key",
|
||||
"groupId": "openrouter",
|
||||
"groupLabel": "OpenRouter",
|
||||
"optionKey": "openrouterApiKey",
|
||||
"cliFlag": "--openrouter-api-key",
|
||||
"cliOption": "--openrouter-api-key <key>",
|
||||
"cliDescription": "مفتاح OpenRouter API",
|
||||
"cliDescription": "OpenRouter API key",
|
||||
"onboardingScopes": ["text-inference"]
|
||||
}
|
||||
],
|
||||
"uiHints": {
|
||||
"apiKey": {
|
||||
"label": "مفتاح API",
|
||||
"label": "API key",
|
||||
"placeholder": "sk-or-v1-...",
|
||||
"sensitive": true
|
||||
}
|
||||
@ -151,68 +150,69 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
## مرجع الحقول العليا
|
||||
## مرجع الحقول ذات المستوى الأعلى
|
||||
|
||||
| الحقل | مطلوب | النوع | ما الذي يعنيه |
|
||||
| ----------------------------------- | -------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `id` | نعم | `string` | معرّف Plugin القياسي. هذا هو المعرّف المستخدم في `plugins.entries.<id>`. |
|
||||
| `configSchema` | نعم | `object` | مخطط JSON مضمن لتكوين هذا Plugin. |
|
||||
| `enabledByDefault` | لا | `true` | يحدد أن Plugin المرفق مفعّل افتراضيًا. احذفه، أو اضبط أي قيمة غير `true`، لترك Plugin معطلًا افتراضيًا. |
|
||||
| `legacyPluginIds` | لا | `string[]` | معرّفات قديمة تتم تسويتها إلى معرّف Plugin القياسي هذا. |
|
||||
| `autoEnableWhenConfiguredProviders` | لا | `string[]` | معرّفات المزوّدين التي يجب أن تفعّل هذا Plugin تلقائيًا عندما تشير إليها المصادقة أو التكوين أو مراجع النماذج. |
|
||||
| `kind` | لا | `"memory"` \| `"context-engine"` | يعلن نوع Plugin حصريًا يُستخدم بواسطة `plugins.slots.*`. |
|
||||
| `channels` | لا | `string[]` | معرّفات القنوات التي يملكها هذا Plugin. تُستخدم للاكتشاف والتحقق من صحة التكوين. |
|
||||
| `providers` | لا | `string[]` | معرّفات المزوّدين التي يملكها هذا Plugin. |
|
||||
| `modelSupport` | لا | `object` | بيانات وصفية مختصرة تملكها البيان لعائلات النماذج وتُستخدم لتحميل Plugin تلقائيًا قبل وقت التشغيل. |
|
||||
| `providerEndpoints` | لا | `object[]` | بيانات وصفية يملكها البيان حول مضيفي نقاط النهاية/`baseUrl` لمسارات المزوّدين التي يجب أن يصنفها core قبل تحميل وقت تشغيل المزوّد. |
|
||||
| `cliBackends` | لا | `string[]` | معرّفات الواجهة الخلفية للاستدلال في CLI التي يملكها هذا Plugin. تُستخدم للتفعيل التلقائي عند بدء التشغيل من مراجع التكوين الصريحة. |
|
||||
| `syntheticAuthRefs` | لا | `string[]` | مراجع المزوّد أو الواجهة الخلفية لـ CLI التي يجب فحص hook المصادقة الاصطناعية المملوك للـ Plugin لها أثناء اكتشاف النماذج البارد قبل تحميل وقت التشغيل. |
|
||||
| `nonSecretAuthMarkers` | لا | `string[]` | قيم مفاتيح API النائبة المملوكة للـ plugin المرفق والتي تمثل حالة بيانات اعتماد محلية أو OAuth أو محيطة غير سرية. |
|
||||
| `commandAliases` | لا | `object[]` | أسماء الأوامر التي يملكها هذا Plugin والتي يجب أن تنتج تشخيصات واعية بالـ Plugin للتكوين وCLI قبل تحميل وقت التشغيل. |
|
||||
| `providerAuthEnvVars` | لا | `Record<string, string[]>` | بيانات وصفية منخفضة التكلفة لمتغيرات بيئة مصادقة المزوّد يمكن لـ OpenClaw فحصها من دون تحميل كود Plugin. |
|
||||
| `providerAuthAliases` | لا | `Record<string, string>` | معرّفات المزوّدين التي يجب أن تعيد استخدام معرّف مزوّد آخر للبحث عن المصادقة، على سبيل المثال مزوّد برمجة يشارك مفتاح API الأساسي وملفات تعريف المصادقة مع المزوّد الأساسي. |
|
||||
| `channelEnvVars` | لا | `Record<string, string[]>` | بيانات وصفية منخفضة التكلفة لمتغيرات بيئة القناة يمكن لـ OpenClaw فحصها من دون تحميل كود Plugin. استخدم هذا لأسطح إعداد القنوات أو المصادقة المعتمدة على البيئة التي يجب أن تراها أدوات البدء/التكوين العامة. |
|
||||
| `providerAuthChoices` | لا | `object[]` | بيانات وصفية منخفضة التكلفة لاختيارات المصادقة لمنتقيات الإعداد الأولي، وحل المزوّد المفضل، وربط علامات CLI البسيط. |
|
||||
| `activation` | لا | `object` | تلميحات تفعيل منخفضة التكلفة للتحميل الذي يتم تشغيله بواسطة المزوّد أو الأمر أو القناة أو المسار أو القدرات. بيانات وصفية فقط؛ ولا يزال وقت تشغيل Plugin يملك السلوك الفعلي. |
|
||||
| `setup` | لا | `object` | واصفات إعداد/إعداد أولي منخفضة التكلفة يمكن لأسطح الاكتشاف والإعداد فحصها من دون تحميل وقت تشغيل Plugin. |
|
||||
| `qaRunners` | لا | `object[]` | واصفات QA runner منخفضة التكلفة يستخدمها المضيف المشترك `openclaw qa` قبل تحميل وقت تشغيل Plugin. |
|
||||
| `contracts` | لا | `object` | لقطة قدرات مرفقة ثابتة للتعرّف على الكلام، والنسخ الفوري، والصوت الفوري، وفهم الوسائط، وتوليد الصور، وتوليد الموسيقى، وتوليد الفيديو، وجلب الويب، والبحث على الويب، وملكية الأدوات. |
|
||||
| `channelConfigs` | لا | `Record<string, object>` | بيانات وصفية لتكوين القناة يملكها البيان وتُدمج في أسطح الاكتشاف والتحقق قبل تحميل وقت التشغيل. |
|
||||
| `skills` | لا | `string[]` | أدلة Skills المطلوب تحميلها، نسبةً إلى جذر Plugin. |
|
||||
| `name` | لا | `string` | اسم Plugin قابل للقراءة البشرية. |
|
||||
| `description` | لا | `string` | ملخص قصير يظهر في أسطح Plugin. |
|
||||
| `version` | لا | `string` | إصدار Plugin لأغراض معلوماتية. |
|
||||
| `uiHints` | لا | `Record<string, object>` | تسميات UI وعناصر نائبة وتلميحات الحساسية لحقول التكوين. |
|
||||
| الحقل | مطلوب | النوع | ما الذي يعنيه |
|
||||
| ------------------------------------ | ------ | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `id` | نعم | `string` | معرّف Plugin القياسي. هذا هو المعرّف المستخدم في `plugins.entries.<id>`. |
|
||||
| `configSchema` | نعم | `object` | مخطط JSON مضمّن لإعدادات Plugin هذا. |
|
||||
| `enabledByDefault` | لا | `true` | يحدد أن Plugin المضمّن مفعّل افتراضيًا. احذفه، أو اضبطه على أي قيمة ليست `true`، لترك Plugin معطّلًا افتراضيًا. |
|
||||
| `legacyPluginIds` | لا | `string[]` | معرّفات قديمة تُطبَّع إلى معرّف Plugin القياسي هذا. |
|
||||
| `autoEnableWhenConfiguredProviders` | لا | `string[]` | معرّفات المزوّدين التي يجب أن تفعّل Plugin هذا تلقائيًا عندما تشير إليها المصادقة أو الإعدادات أو مراجع النماذج. |
|
||||
| `kind` | لا | `"memory"` \| `"context-engine"` | يصرّح بنوع Plugin حصري يُستخدم بواسطة `plugins.slots.*`. |
|
||||
| `channels` | لا | `string[]` | معرّفات القنوات التي يملكها Plugin هذا. تُستخدم للاكتشاف والتحقق من صحة الإعدادات. |
|
||||
| `providers` | لا | `string[]` | معرّفات المزوّدين التي يملكها Plugin هذا. |
|
||||
| `modelSupport` | لا | `object` | بيانات تعريف مختصرة لعائلات النماذج مملوكة للبيان وتُستخدم لتحميل Plugin تلقائيًا قبل وقت التشغيل. |
|
||||
| `providerEndpoints` | لا | `object[]` | بيانات تعريف `host`/`baseUrl` لنقاط نهاية المزوّد مملوكة للبيان لمسارات المزوّد التي يجب على النواة تصنيفها قبل تحميل وقت تشغيل المزوّد. |
|
||||
| `cliBackends` | لا | `string[]` | معرّفات الواجهات الخلفية للاستدلال في CLI التي يملكها Plugin هذا. تُستخدم للتفعيل التلقائي عند بدء التشغيل من مراجع إعدادات صريحة. |
|
||||
| `syntheticAuthRefs` | لا | `string[]` | مراجع المزوّد أو الواجهة الخلفية لـ CLI التي يجب فحص خطاف المصادقة الاصطناعية المملوك لـ Plugin لها أثناء الاكتشاف البارد للنماذج قبل تحميل وقت التشغيل. |
|
||||
| `nonSecretAuthMarkers` | لا | `string[]` | قيم مفاتيح API بديلة مملوكة لـ Plugin المضمّن تمثل حالة بيانات اعتماد غير سرية محلية أو OAuth أو محيطة. |
|
||||
| `commandAliases` | لا | `object[]` | أسماء الأوامر التي يملكها Plugin هذا والتي يجب أن تنتج إعدادات وتشخيصات CLI مدركة لـ Plugin قبل تحميل وقت التشغيل. |
|
||||
| `providerAuthEnvVars` | لا | `Record<string, string[]>` | بيانات تعريف متغيرات البيئة لمصادقة المزوّد منخفضة التكلفة التي يمكن لـ OpenClaw فحصها من دون تحميل كود Plugin. |
|
||||
| `providerAuthAliases` | لا | `Record<string, string>` | معرّفات مزوّدين يجب أن تعيد استخدام معرّف مزوّد آخر للبحث عن المصادقة، مثل مزوّد برمجة يشارك مفتاح API الأساسي وملفات تعريف المصادقة مع المزوّد الأساسي. |
|
||||
| `channelEnvVars` | لا | `Record<string, string[]>` | بيانات تعريف متغيرات البيئة للقناة منخفضة التكلفة التي يمكن لـ OpenClaw فحصها من دون تحميل كود Plugin. استخدم هذا لأسطح إعداد القنوات أو المصادقة المعتمدة على متغيرات البيئة والتي يجب أن تراها أدوات البدء/الإعدادات العامة. |
|
||||
| `providerAuthChoices` | لا | `object[]` | بيانات تعريف خيارات مصادقة منخفضة التكلفة لمنتقيات الإعداد الأوّلي، وحل المزوّد المفضّل، وربط أعلام CLI البسيط. |
|
||||
| `activation` | لا | `object` | تلميحات تفعيل منخفضة التكلفة للتحميل المستند إلى المزوّد والأمر والقناة والمسار والإمكانات. بيانات تعريف فقط؛ يظل وقت تشغيل Plugin مالك السلوك الفعلي. |
|
||||
| `setup` | لا | `object` | واصفات إعداد/إعداد أوّلي منخفضة التكلفة يمكن لأسطح الاكتشاف والإعداد فحصها من دون تحميل وقت تشغيل Plugin. |
|
||||
| `qaRunners` | لا | `object[]` | واصفات مشغّلات QA منخفضة التكلفة التي يستخدمها مضيف `openclaw qa` المشترك قبل تحميل وقت تشغيل Plugin. |
|
||||
| `contracts` | لا | `object` | لقطة ثابتة لإمكانات مضمّنة للتعرّف على الكلام، والنسخ الفوري، والصوت الفوري، وفهم الوسائط، وتوليد الصور، وتوليد الموسيقى، وتوليد الفيديو، وجلب الويب، والبحث في الويب، وملكية الأدوات. |
|
||||
| `mediaUnderstandingProviderMetadata` | لا | `Record<string, object>` | إعدادات افتراضية منخفضة التكلفة لفهم الوسائط لمعرّفات المزوّدين المصرّح بها في `contracts.mediaUnderstandingProviders`. |
|
||||
| `channelConfigs` | لا | `Record<string, object>` | بيانات تعريف إعدادات القناة مملوكة للبيان وتُدمج في أسطح الاكتشاف والتحقق قبل تحميل وقت التشغيل. |
|
||||
| `skills` | لا | `string[]` | أدلة Skills المطلوب تحميلها، نسبةً إلى جذر Plugin. |
|
||||
| `name` | لا | `string` | اسم Plugin بصيغة قابلة للقراءة البشرية. |
|
||||
| `description` | لا | `string` | ملخص قصير يُعرض في أسطح Plugin. |
|
||||
| `version` | لا | `string` | إصدار Plugin لأغراض معلوماتية. |
|
||||
| `uiHints` | لا | `Record<string, object>` | تسميات واجهة المستخدم، والعناصر النائبة، وتلميحات الحساسية لحقول الإعدادات. |
|
||||
|
||||
## مرجع `providerAuthChoices`
|
||||
|
||||
يصف كل إدخال في `providerAuthChoices` اختيارًا واحدًا من اختيارات الإعداد الأولي أو المصادقة.
|
||||
يصف كل إدخال في `providerAuthChoices` خيارًا واحدًا للإعداد الأوّلي أو المصادقة.
|
||||
يقرأ OpenClaw هذا قبل تحميل وقت تشغيل المزوّد.
|
||||
|
||||
| الحقل | مطلوب | النوع | ما الذي يعنيه |
|
||||
| --------------------- | -------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
|
||||
| `provider` | نعم | `string` | معرّف المزوّد الذي ينتمي إليه هذا الاختيار. |
|
||||
| `method` | نعم | `string` | معرّف طريقة المصادقة المطلوب التوجيه إليه. |
|
||||
| `choiceId` | نعم | `string` | معرّف ثابت لاختيار المصادقة تستخدمه تدفقات الإعداد الأولي وCLI. |
|
||||
| `choiceLabel` | لا | `string` | تسمية موجهة للمستخدم. إذا حُذفت، يعود OpenClaw إلى `choiceId`. |
|
||||
| `choiceHint` | لا | `string` | نص مساعد قصير لمنتقي الاختيار. |
|
||||
| `assistantPriority` | لا | `number` | القيم الأقل تُرتَّب أولًا في المنتقيات التفاعلية التي يقودها المساعد. |
|
||||
| `assistantVisibility` | لا | `"visible"` \| `"manual-only"` | إخفاء الاختيار من منتقيات المساعد مع السماح مع ذلك بالاختيار اليدوي عبر CLI. |
|
||||
| `deprecatedChoiceIds` | لا | `string[]` | معرّفات اختيارات قديمة يجب أن تعيد توجيه المستخدمين إلى هذا الاختيار البديل. |
|
||||
| `groupId` | لا | `string` | معرّف مجموعة اختياري لتجميع الاختيارات ذات الصلة. |
|
||||
| `groupLabel` | لا | `string` | تسمية موجهة للمستخدم لتلك المجموعة. |
|
||||
| `groupHint` | لا | `string` | نص مساعد قصير للمجموعة. |
|
||||
| `optionKey` | لا | `string` | مفتاح خيار داخلي لتدفقات المصادقة البسيطة ذات العلم الواحد. |
|
||||
| `cliFlag` | لا | `string` | اسم علم CLI، مثل `--openrouter-api-key`. |
|
||||
| `cliOption` | لا | `string` | الشكل الكامل لخيار CLI، مثل `--openrouter-api-key <key>`. |
|
||||
| `cliDescription` | لا | `string` | الوصف المستخدم في تعليمات CLI. |
|
||||
| `onboardingScopes` | لا | `Array<"text-inference" \| "image-generation">` | أسطح الإعداد الأولي التي يجب أن يظهر فيها هذا الاختيار. إذا حُذفت، فالقيمة الافتراضية هي `["text-inference"]`. |
|
||||
| الحقل | مطلوب | النوع | ما الذي يعنيه |
|
||||
| --------------------- | ------ | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
|
||||
| `provider` | نعم | `string` | معرّف المزوّد الذي ينتمي إليه هذا الخيار. |
|
||||
| `method` | نعم | `string` | معرّف طريقة المصادقة المطلوب التوجيه إليها. |
|
||||
| `choiceId` | نعم | `string` | معرّف ثابت لخيار المصادقة تستخدمه تدفقات الإعداد الأوّلي وCLI. |
|
||||
| `choiceLabel` | لا | `string` | تسمية موجهة للمستخدم. إذا لم تُحدَّد، يعود OpenClaw إلى `choiceId`. |
|
||||
| `choiceHint` | لا | `string` | نص مساعد قصير للمنتقي. |
|
||||
| `assistantPriority` | لا | `number` | تُرتَّب القيم الأقل أولًا في المنتقيات التفاعلية التي يقودها المساعد. |
|
||||
| `assistantVisibility` | لا | `"visible"` \| `"manual-only"` | يُخفي الخيار من منتقيات المساعد مع السماح مع ذلك بالاختيار اليدوي عبر CLI. |
|
||||
| `deprecatedChoiceIds` | لا | `string[]` | معرّفات خيارات قديمة يجب أن تعيد توجيه المستخدمين إلى خيار الاستبدال هذا. |
|
||||
| `groupId` | لا | `string` | معرّف مجموعة اختياري لتجميع الخيارات ذات الصلة. |
|
||||
| `groupLabel` | لا | `string` | تسمية موجهة للمستخدم لتلك المجموعة. |
|
||||
| `groupHint` | لا | `string` | نص مساعد قصير للمجموعة. |
|
||||
| `optionKey` | لا | `string` | مفتاح خيار داخلي لتدفقات المصادقة البسيطة ذات العلم الواحد. |
|
||||
| `cliFlag` | لا | `string` | اسم علم CLI، مثل `--openrouter-api-key`. |
|
||||
| `cliOption` | لا | `string` | الشكل الكامل لخيار CLI، مثل `--openrouter-api-key <key>`. |
|
||||
| `cliDescription` | لا | `string` | الوصف المستخدم في تعليمات CLI. |
|
||||
| `onboardingScopes` | لا | `Array<"text-inference" \| "image-generation">` | أسطح الإعداد الأوّلي التي يجب أن يظهر فيها هذا الخيار. إذا لم تُحدَّد، تكون القيمة الافتراضية `["text-inference"]`. |
|
||||
|
||||
## مرجع `commandAliases`
|
||||
|
||||
استخدم `commandAliases` عندما يملك Plugin اسم أمر وقت تشغيل قد
|
||||
يضعه المستخدمون عن طريق الخطأ في `plugins.allow` أو يحاولون تشغيله كأمر CLI جذري. يستخدم OpenClaw
|
||||
هذه البيانات الوصفية للتشخيصات من دون استيراد كود وقت تشغيل Plugin.
|
||||
استخدم `commandAliases` عندما يملك Plugin اسم أمر وقت تشغيل قد يضعه المستخدمون
|
||||
بالخطأ في `plugins.allow` أو يحاولون تشغيله كأمر CLI جذري. يستخدم OpenClaw
|
||||
بيانات التعريف هذه للتشخيصات من دون استيراد كود وقت تشغيل Plugin.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -226,45 +226,45 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
| الحقل | مطلوب | النوع | ما الذي يعنيه |
|
||||
| ------------ | -------- | ----------------- | ----------------------------------------------------------------------- |
|
||||
| `name` | نعم | `string` | اسم الأمر الذي ينتمي إلى هذا Plugin. |
|
||||
| `kind` | لا | `"runtime-slash"` | يحدد الاسم المستعار على أنه أمر slash للدردشة وليس أمر CLI جذريًا. |
|
||||
| `cliCommand` | لا | `string` | أمر CLI جذري ذو صلة يمكن اقتراحه لعمليات CLI، إذا كان موجودًا. |
|
||||
| الحقل | مطلوب | النوع | ما الذي يعنيه |
|
||||
| ------------ | ------ | ----------------- | --------------------------------------------------------------------------- |
|
||||
| `name` | نعم | `string` | اسم الأمر الذي ينتمي إلى هذا Plugin. |
|
||||
| `kind` | لا | `"runtime-slash"` | يحدد أن الاسم المستعار أمر slash للدردشة وليس أمر CLI جذريًا. |
|
||||
| `cliCommand` | لا | `string` | أمر CLI جذري ذو صلة يُقترح لعمليات CLI، إذا كان موجودًا. |
|
||||
|
||||
## مرجع `activation`
|
||||
|
||||
استخدم `activation` عندما يستطيع Plugin أن يعلن بتكلفة منخفضة عن أحداث مستوى التحكم
|
||||
استخدم `activation` عندما يستطيع Plugin أن يصرّح بتكلفة منخفضة عن أحداث مستوى التحكّم
|
||||
التي يجب أن تفعّله لاحقًا.
|
||||
|
||||
## مرجع `qaRunners`
|
||||
|
||||
استخدم `qaRunners` عندما يساهم Plugin بواحد أو أكثر من transport runners تحت
|
||||
الجذر المشترك `openclaw qa`. اجعل هذه البيانات الوصفية منخفضة التكلفة وثابتة؛ فما زال وقت تشغيل Plugin
|
||||
يملك تسجيل CLI الفعلي عبر سطح
|
||||
`runtime-api.ts` خفيف يصدّر `qaRunnerCliRegistrations`.
|
||||
استخدم `qaRunners` عندما يضيف Plugin مشغّل نقل واحدًا أو أكثر تحت الجذر المشترك
|
||||
`openclaw qa`. اجعل بيانات التعريف هذه منخفضة التكلفة وثابتة؛ فما يزال وقت تشغيل Plugin
|
||||
يملك تسجيل CLI الفعلي عبر سطح `runtime-api.ts` خفيف الوزن
|
||||
يُصدّر `qaRunnerCliRegistrations`.
|
||||
|
||||
```json
|
||||
{
|
||||
"qaRunners": [
|
||||
{
|
||||
"commandName": "matrix",
|
||||
"description": "تشغيل مسار Matrix QA المباشر المدعوم بـ Docker مقابل homeserver مؤقت"
|
||||
"description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
| الحقل | مطلوب | النوع | ما الذي يعنيه |
|
||||
| ------------- | -------- | -------- | ------------------------------------------------------------------ |
|
||||
| `commandName` | نعم | `string` | أمر فرعي يُركّب تحت `openclaw qa`، مثل `matrix`. |
|
||||
| `description` | لا | `string` | نص مساعدة احتياطي يُستخدم عندما يحتاج المضيف المشترك إلى أمر stub. |
|
||||
| الحقل | مطلوب | النوع | ما الذي يعنيه |
|
||||
| ------------- | ------ | -------- | ------------------------------------------------------------------ |
|
||||
| `commandName` | نعم | `string` | الأمر الفرعي المثبّت تحت `openclaw qa`، مثل `matrix`. |
|
||||
| `description` | لا | `string` | نص تعليمات بديل يُستخدم عندما يحتاج المضيف المشترك إلى أمر stub. |
|
||||
|
||||
هذه الكتلة بيانات وصفية فقط. فهي لا تسجّل سلوك وقت التشغيل، ولا
|
||||
تحل محل `register(...)` أو `setupEntry` أو نقاط دخول Plugin/وقت التشغيل الأخرى.
|
||||
يستخدمها المستهلكون الحاليون كتلميح تضييق قبل تحميل Plugin على نطاق أوسع، لذا
|
||||
فإن غياب بيانات `activation` الوصفية يؤدي عادةً فقط إلى تكلفة في الأداء؛ ويجب ألا
|
||||
يغير الصحة ما دامت تراجعات ملكية البيان القديمة لا تزال موجودة.
|
||||
هذه الكتلة بيانات تعريف فقط. فهي لا تسجل سلوك وقت التشغيل، ولا
|
||||
تحل محل `register(...)` أو `setupEntry` أو نقاط دخول وقت التشغيل/Plugin الأخرى.
|
||||
يستخدمها المستهلكون الحاليون كتلميح تضييق قبل تحميل Plugin على نطاق أوسع، لذلك فإن
|
||||
غياب بيانات تعريف التفعيل عادة لا يكلّف سوى الأداء؛ ويجب ألا
|
||||
يغير الصحة ما دامت بدائل ملكية البيان القديمة لا تزال موجودة.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -278,28 +278,28 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
| الحقل | مطلوب | النوع | ما الذي يعنيه |
|
||||
| ---------------- | -------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
|
||||
| `onProviders` | لا | `string[]` | معرّفات المزوّدين التي يجب أن تفعّل هذا Plugin عند طلبها. |
|
||||
| `onCommands` | لا | `string[]` | معرّفات الأوامر التي يجب أن تفعّل هذا Plugin. |
|
||||
| `onChannels` | لا | `string[]` | معرّفات القنوات التي يجب أن تفعّل هذا Plugin. |
|
||||
| `onRoutes` | لا | `string[]` | أنواع المسارات التي يجب أن تفعّل هذا Plugin. |
|
||||
| `onCapabilities` | لا | `Array<"provider" \| "channel" \| "tool" \| "hook">` | تلميحات قدرات عامة تُستخدم في تخطيط التفعيل لمستوى التحكم. |
|
||||
| الحقل | مطلوب | النوع | ما الذي يعنيه |
|
||||
| ---------------- | ------ | ---------------------------------------------------- | ---------------------------------------------------------------- |
|
||||
| `onProviders` | لا | `string[]` | معرّفات المزوّدين التي يجب أن تفعّل هذا Plugin عند طلبها. |
|
||||
| `onCommands` | لا | `string[]` | معرّفات الأوامر التي يجب أن تفعّل هذا Plugin. |
|
||||
| `onChannels` | لا | `string[]` | معرّفات القنوات التي يجب أن تفعّل هذا Plugin. |
|
||||
| `onRoutes` | لا | `string[]` | أنواع المسارات التي يجب أن تفعّل هذا Plugin. |
|
||||
| `onCapabilities` | لا | `Array<"provider" \| "channel" \| "tool" \| "hook">` | تلميحات إمكانات عامة تُستخدم في تخطيط التفعيل على مستوى التحكّم. |
|
||||
|
||||
المستهلكون المباشرون الحاليون:
|
||||
|
||||
- يعتمد تخطيط CLI الذي يتم تشغيله بالأوامر على التراجع إلى
|
||||
`commandAliases[].cliCommand` أو `commandAliases[].name`
|
||||
- يعتمد تخطيط الإعداد/القناة الذي يتم تشغيله بالقنوات على التراجع إلى ملكية
|
||||
`channels[]` القديمة عندما تكون بيانات تفعيل القناة الصريحة مفقودة
|
||||
- يعتمد تخطيط الإعداد/وقت التشغيل الذي يتم تشغيله بالمزوّدين على التراجع إلى
|
||||
ملكية `providers[]` و`cliBackends[]` على المستوى الأعلى عندما تكون بيانات
|
||||
- يعود تخطيط CLI المعتمد على تشغيل الأمر إلى
|
||||
`commandAliases[].cliCommand` أو `commandAliases[].name` القديمين
|
||||
- يعود تخطيط الإعداد/القنوات المعتمد على تشغيل القناة إلى ملكية
|
||||
`channels[]` القديمة عندما تكون بيانات تعريف تفعيل القناة الصريحة مفقودة
|
||||
- يعود تخطيط الإعداد/وقت التشغيل المعتمد على تشغيل المزوّد إلى
|
||||
ملكية `providers[]` القديمة وملكية `cliBackends[]` ذات المستوى الأعلى عندما تكون بيانات تعريف
|
||||
تفعيل المزوّد الصريحة مفقودة
|
||||
|
||||
## مرجع `setup`
|
||||
|
||||
استخدم `setup` عندما تحتاج أسطح الإعداد والإعداد الأولي إلى بيانات وصفية منخفضة التكلفة يملكها Plugin
|
||||
قبل تحميل وقت التشغيل.
|
||||
استخدم `setup` عندما تحتاج أسطح الإعداد والإعداد الأوّلي إلى بيانات تعريف منخفضة التكلفة
|
||||
مملوكة لـ Plugin قبل تحميل وقت التشغيل.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -318,48 +318,48 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
يبقى `cliBackends` على المستوى الأعلى صالحًا ويستمر في وصف الواجهات الخلفية
|
||||
لاستدلال CLI. أما `setup.cliBackends` فهو سطح الواصفات الخاص بالإعداد
|
||||
لتدفقات مستوى التحكم/الإعداد التي يجب أن تبقى بيانات وصفية فقط.
|
||||
يبقى `cliBackends` ذو المستوى الأعلى صالحًا ويستمر في وصف الواجهات الخلفية للاستدلال في CLI.
|
||||
أما `setup.cliBackends` فهو سطح الواصفات الخاص بالإعداد من أجل
|
||||
تدفقات مستوى التحكّم/الإعداد التي يجب أن تبقى بيانات تعريف فقط.
|
||||
|
||||
عند وجودها، تكون `setup.providers` و`setup.cliBackends` هما
|
||||
سطح البحث المفضل القائم على الواصفات أولًا لاكتشاف الإعداد. وإذا كان الواصف
|
||||
يضيّق Plugin المرشح فقط بينما لا يزال الإعداد يحتاج إلى hooks أغنى وقت الإعداد
|
||||
في وقت التشغيل، فاضبط `requiresRuntime: true` وأبقِ `setup-api`
|
||||
كمسار تنفيذ احتياطي.
|
||||
عند وجودهما، تكون `setup.providers` و`setup.cliBackends` هما
|
||||
سطح البحث المفضل القائم أولًا على الواصفات لاكتشاف الإعداد. وإذا كان الواصف
|
||||
يضيّق Plugin المرشح فقط وما زال الإعداد يحتاج إلى خطافات وقت إعداد أغنى في وقت التشغيل،
|
||||
فاضبط `requiresRuntime: true` وأبقِ `setup-api` في مكانه باعتباره
|
||||
مسار التنفيذ الاحتياطي.
|
||||
|
||||
ولأن بحث الإعداد يمكن أن ينفّذ كود `setup-api` يملكه Plugin، فيجب أن تبقى القيم
|
||||
المطبّعة في `setup.providers[].id` و`setup.cliBackends[]` فريدة على مستوى جميع
|
||||
Plugins المكتشفة. تفشل الملكية الملتبسة بشكل مغلق بدلًا من اختيار
|
||||
فائز بحسب ترتيب الاكتشاف.
|
||||
ولأن بحث الإعداد يمكنه تنفيذ كود `setup-api` مملوكًا لـ Plugin، فيجب أن تبقى القيم
|
||||
المطبّعة لـ `setup.providers[].id` و`setup.cliBackends[]` فريدة عبر
|
||||
Plugins المكتشفة. وتفشل الملكية الملتبسة بإغلاق آمن بدلًا من اختيار فائز
|
||||
استنادًا إلى ترتيب الاكتشاف.
|
||||
|
||||
### مرجع `setup.providers`
|
||||
|
||||
| الحقل | مطلوب | النوع | ما الذي يعنيه |
|
||||
| ------------- | -------- | ---------- | ------------------------------------------------------------------------------------ |
|
||||
| `id` | نعم | `string` | معرّف المزوّد المعروض أثناء الإعداد أو الإعداد الأولي. حافظ على فرادة المعرّفات المطبّعة عالميًا. |
|
||||
| `authMethods` | لا | `string[]` | معرّفات طرق الإعداد/المصادقة التي يدعمها هذا المزوّد من دون تحميل وقت التشغيل الكامل. |
|
||||
| `envVars` | لا | `string[]` | متغيرات البيئة التي يمكن لأسطح الإعداد/الحالة العامة التحقق منها قبل تحميل وقت تشغيل Plugin. |
|
||||
| الحقل | مطلوب | النوع | ما الذي يعنيه |
|
||||
| ------------- | ------ | ---------- | ------------------------------------------------------------------------------------ |
|
||||
| `id` | نعم | `string` | معرّف المزوّد المعروض أثناء الإعداد أو الإعداد الأوّلي. احرص على أن تكون المعرّفات المطبّعة فريدة عالميًا. |
|
||||
| `authMethods` | لا | `string[]` | معرّفات طرق الإعداد/المصادقة التي يدعمها هذا المزوّد من دون تحميل وقت التشغيل الكامل. |
|
||||
| `envVars` | لا | `string[]` | متغيرات البيئة التي يمكن لأسطح الإعداد/الحالة العامة التحقق منها قبل تحميل وقت تشغيل Plugin. |
|
||||
|
||||
### حقول `setup`
|
||||
|
||||
| الحقل | مطلوب | النوع | ما الذي يعنيه |
|
||||
| ------------------ | -------- | ---------- | --------------------------------------------------------------------------------------------------- |
|
||||
| `providers` | لا | `object[]` | واصفات إعداد المزوّدين المعروضة أثناء الإعداد والإعداد الأولي. |
|
||||
| `cliBackends` | لا | `string[]` | معرّفات الواجهات الخلفية وقت الإعداد المستخدمة للبحث القائم على الواصفات أولًا. حافظ على فرادة المعرّفات المطبّعة عالميًا. |
|
||||
| `configMigrations` | لا | `string[]` | معرّفات ترحيل التكوين التي يملكها سطح الإعداد في هذا Plugin. |
|
||||
| `requiresRuntime` | لا | `boolean` | ما إذا كان الإعداد لا يزال يحتاج إلى تنفيذ `setup-api` بعد البحث بالواصفات. |
|
||||
| الحقل | مطلوب | النوع | ما الذي يعنيه |
|
||||
| ------------------ | ------ | ---------- | -------------------------------------------------------------------------------------------------- |
|
||||
| `providers` | لا | `object[]` | واصفات إعداد المزوّد المعروضة أثناء الإعداد والإعداد الأوّلي. |
|
||||
| `cliBackends` | لا | `string[]` | معرّفات الواجهات الخلفية في وقت الإعداد المستخدمة في البحث القائم أولًا على الواصفات. احرص على أن تكون المعرّفات المطبّعة فريدة عالميًا. |
|
||||
| `configMigrations` | لا | `string[]` | معرّفات ترحيل الإعدادات التي يملكها سطح إعداد هذا Plugin. |
|
||||
| `requiresRuntime` | لا | `boolean` | ما إذا كان الإعداد لا يزال يحتاج إلى تنفيذ `setup-api` بعد البحث بالواصفات. |
|
||||
|
||||
## مرجع `uiHints`
|
||||
|
||||
تمثل `uiHints` خريطة من أسماء حقول التكوين إلى تلميحات عرض صغيرة.
|
||||
تمثل `uiHints` خريطة من أسماء حقول الإعدادات إلى تلميحات عرض صغيرة.
|
||||
|
||||
```json
|
||||
{
|
||||
"uiHints": {
|
||||
"apiKey": {
|
||||
"label": "مفتاح API",
|
||||
"help": "يُستخدم لطلبات OpenRouter",
|
||||
"label": "API key",
|
||||
"help": "Used for OpenRouter requests",
|
||||
"placeholder": "sk-or-v1-...",
|
||||
"sensitive": true
|
||||
}
|
||||
@ -367,25 +367,26 @@ Plugins المكتشفة. تفشل الملكية الملتبسة بشكل مغ
|
||||
}
|
||||
```
|
||||
|
||||
يمكن أن يتضمن كل تلميح حقل ما يلي:
|
||||
يمكن أن يتضمن تلميح كل حقل ما يلي:
|
||||
|
||||
| الحقل | النوع | ما الذي يعنيه |
|
||||
| ------------- | ---------- | --------------------------------------- |
|
||||
| `label` | `string` | تسمية الحقل الموجهة للمستخدم. |
|
||||
| `help` | `string` | نص مساعد قصير. |
|
||||
| `tags` | `string[]` | وسوم UI اختيارية. |
|
||||
| `advanced` | `boolean` | يحدد الحقل على أنه متقدم. |
|
||||
| `sensitive` | `boolean` | يحدد الحقل على أنه سري أو حساس. |
|
||||
| `placeholder` | `string` | نص العنصر النائب لحقول الإدخال في النماذج. |
|
||||
| الحقل | النوع | ما الذي يعنيه |
|
||||
| ------------- | ---------- | ------------------------------------- |
|
||||
| `label` | `string` | تسمية الحقل الموجهة للمستخدم. |
|
||||
| `help` | `string` | نص مساعد قصير. |
|
||||
| `tags` | `string[]` | وسوم واجهة مستخدم اختيارية. |
|
||||
| `advanced` | `boolean` | يحدد الحقل على أنه متقدم. |
|
||||
| `sensitive` | `boolean` | يحدد الحقل على أنه سري أو حساس. |
|
||||
| `placeholder` | `string` | نص العنصر النائب لمدخلات النماذج. |
|
||||
|
||||
## مرجع `contracts`
|
||||
|
||||
استخدم `contracts` فقط لبيانات وصفية ثابتة لملكية القدرات يستطيع OpenClaw
|
||||
استخدم `contracts` فقط لبيانات تعريف ملكية الإمكانات الثابتة التي يمكن لـ OpenClaw
|
||||
قراءتها من دون استيراد وقت تشغيل Plugin.
|
||||
|
||||
```json
|
||||
{
|
||||
"contracts": {
|
||||
"embeddedExtensionFactories": ["pi"],
|
||||
"speechProviders": ["openai"],
|
||||
"realtimeTranscriptionProviders": ["openai"],
|
||||
"realtimeVoiceProviders": ["openai"],
|
||||
@ -401,21 +402,59 @@ Plugins المكتشفة. تفشل الملكية الملتبسة بشكل مغ
|
||||
|
||||
كل قائمة اختيارية:
|
||||
|
||||
| الحقل | النوع | ما الذي يعنيه |
|
||||
| -------------------------------- | ---------- | -------------------------------------------------------------- |
|
||||
| `speechProviders` | `string[]` | معرّفات مزوّدي الكلام التي يملكها هذا Plugin. |
|
||||
| `realtimeTranscriptionProviders` | `string[]` | معرّفات مزوّدي النسخ الفوري التي يملكها هذا Plugin. |
|
||||
| `realtimeVoiceProviders` | `string[]` | معرّفات مزوّدي الصوت الفوري التي يملكها هذا Plugin. |
|
||||
| `mediaUnderstandingProviders` | `string[]` | معرّفات مزوّدي فهم الوسائط التي يملكها هذا Plugin. |
|
||||
| `imageGenerationProviders` | `string[]` | معرّفات مزوّدي توليد الصور التي يملكها هذا Plugin. |
|
||||
| `videoGenerationProviders` | `string[]` | معرّفات مزوّدي توليد الفيديو التي يملكها هذا Plugin. |
|
||||
| `webFetchProviders` | `string[]` | معرّفات مزوّدي جلب الويب التي يملكها هذا Plugin. |
|
||||
| `webSearchProviders` | `string[]` | معرّفات مزوّدي البحث على الويب التي يملكها هذا Plugin. |
|
||||
| `tools` | `string[]` | أسماء أدوات الوكيل التي يملكها هذا Plugin لفحوصات العقود المرفقة. |
|
||||
| الحقل | النوع | ما الذي يعنيه |
|
||||
| -------------------------------- | ---------- | ------------------------------------------------------------------ |
|
||||
| `embeddedExtensionFactories` | `string[]` | معرّفات وقت التشغيل المضمّن التي يمكن أن يسجل Plugin المضمّن factories لها. |
|
||||
| `speechProviders` | `string[]` | معرّفات مزوّدي الكلام التي يملكها Plugin هذا. |
|
||||
| `realtimeTranscriptionProviders` | `string[]` | معرّفات مزوّدي النسخ الفوري التي يملكها Plugin هذا. |
|
||||
| `realtimeVoiceProviders` | `string[]` | معرّفات مزوّدي الصوت الفوري التي يملكها Plugin هذا. |
|
||||
| `mediaUnderstandingProviders` | `string[]` | معرّفات مزوّدي فهم الوسائط التي يملكها Plugin هذا. |
|
||||
| `imageGenerationProviders` | `string[]` | معرّفات مزوّدي توليد الصور التي يملكها Plugin هذا. |
|
||||
| `videoGenerationProviders` | `string[]` | معرّفات مزوّدي توليد الفيديو التي يملكها Plugin هذا. |
|
||||
| `webFetchProviders` | `string[]` | معرّفات مزوّدي جلب الويب التي يملكها Plugin هذا. |
|
||||
| `webSearchProviders` | `string[]` | معرّفات مزوّدي البحث في الويب التي يملكها Plugin هذا. |
|
||||
| `tools` | `string[]` | أسماء أدوات الوكيل التي يملكها Plugin هذا لفحوصات العقود المضمّنة. |
|
||||
|
||||
## مرجع `mediaUnderstandingProviderMetadata`
|
||||
|
||||
استخدم `mediaUnderstandingProviderMetadata` عندما يكون لدى مزوّد فهم الوسائط
|
||||
نماذج افتراضية، أو أولوية احتياطية للمصادقة التلقائية، أو دعم أصلي للمستندات
|
||||
تحتاجه مساعدات النواة العامة قبل تحميل وقت التشغيل. ويجب أيضًا التصريح بالمفاتيح في
|
||||
`contracts.mediaUnderstandingProviders`.
|
||||
|
||||
```json
|
||||
{
|
||||
"contracts": {
|
||||
"mediaUnderstandingProviders": ["example"]
|
||||
},
|
||||
"mediaUnderstandingProviderMetadata": {
|
||||
"example": {
|
||||
"capabilities": ["image", "audio"],
|
||||
"defaultModels": {
|
||||
"image": "example-vision-latest",
|
||||
"audio": "example-transcribe-latest"
|
||||
},
|
||||
"autoPriority": {
|
||||
"image": 40
|
||||
},
|
||||
"nativeDocumentInputs": ["pdf"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
يمكن أن يتضمن كل إدخال مزوّد ما يلي:
|
||||
|
||||
| الحقل | النوع | ما الذي يعنيه |
|
||||
| ---------------------- | ----------------------------------- | ----------------------------------------------------------------------------- |
|
||||
| `capabilities` | `("image" \| "audio" \| "video")[]` | إمكانات الوسائط التي يوفّرها هذا المزوّد. |
|
||||
| `defaultModels` | `Record<string, string>` | الإعدادات الافتراضية من الإمكانية إلى النموذج المستخدمة عندما لا يحدد الإعداد نموذجًا. |
|
||||
| `autoPriority` | `Record<string, number>` | تُرتَّب الأرقام الأقل أولًا للاحتياط التلقائي للمزوّد المستند إلى بيانات الاعتماد. |
|
||||
| `nativeDocumentInputs` | `"pdf"[]` | مدخلات المستندات الأصلية التي يدعمها المزوّد. |
|
||||
|
||||
## مرجع `channelConfigs`
|
||||
|
||||
استخدم `channelConfigs` عندما يحتاج Plugin قناة إلى بيانات وصفية منخفضة التكلفة للتكوين قبل
|
||||
استخدم `channelConfigs` عندما يحتاج Plugin القناة إلى بيانات تعريف إعدادات منخفضة التكلفة قبل
|
||||
تحميل وقت التشغيل.
|
||||
|
||||
```json
|
||||
@ -431,12 +470,12 @@ Plugins المكتشفة. تفشل الملكية الملتبسة بشكل مغ
|
||||
},
|
||||
"uiHints": {
|
||||
"homeserverUrl": {
|
||||
"label": "عنوان URL لـ Homeserver",
|
||||
"label": "Homeserver URL",
|
||||
"placeholder": "https://matrix.example.com"
|
||||
}
|
||||
},
|
||||
"label": "Matrix",
|
||||
"description": "اتصال Matrix homeserver",
|
||||
"description": "Matrix homeserver connection",
|
||||
"preferOver": ["matrix-legacy"]
|
||||
}
|
||||
}
|
||||
@ -445,19 +484,18 @@ Plugins المكتشفة. تفشل الملكية الملتبسة بشكل مغ
|
||||
|
||||
يمكن أن يتضمن كل إدخال قناة ما يلي:
|
||||
|
||||
| الحقل | النوع | ما الذي يعنيه |
|
||||
| ------------- | ------------------------ | ----------------------------------------------------------------------------------------- |
|
||||
| `schema` | `object` | مخطط JSON لـ `channels.<id>`. وهو مطلوب لكل إدخال تكوين قناة مُعلن. |
|
||||
| `uiHints` | `Record<string, object>` | تسميات UI/عناصر نائبة/تلميحات حساسية اختيارية لذلك القسم من تكوين القناة. |
|
||||
| `label` | `string` | تسمية القناة المدمجة في أسطح المنتقي والفحص عندما لا تكون بيانات وقت التشغيل الوصفية جاهزة. |
|
||||
| `description` | `string` | وصف قصير للقناة لأسطح الفحص والكتالوج. |
|
||||
| `preferOver` | `string[]` | معرّفات Plugins قديمة أو أقل أولوية يجب أن تتفوق عليها هذه القناة في أسطح الاختيار. |
|
||||
| الحقل | النوع | ما الذي يعنيه |
|
||||
| ------------- | ------------------------ | ------------------------------------------------------------------------------------------ |
|
||||
| `schema` | `object` | مخطط JSON لـ `channels.<id>`. وهو مطلوب لكل إدخال معلن لإعدادات القناة. |
|
||||
| `uiHints` | `Record<string, object>` | تسميات/عناصر نائبة/تلميحات حساسية اختيارية لواجهة المستخدم لقسم إعدادات تلك القناة. |
|
||||
| `label` | `string` | تسمية القناة المدمجة في أسطح المنتقي والمعاينة عندما لا تكون بيانات تعريف وقت التشغيل جاهزة. |
|
||||
| `description` | `string` | وصف قصير للقناة لأسطح المعاينة والفهرس. |
|
||||
| `preferOver` | `string[]` | معرّفات Plugin قديمة أو أقل أولوية يجب أن تتفوق عليها هذه القناة في أسطح الاختيار. |
|
||||
|
||||
## مرجع `modelSupport`
|
||||
|
||||
استخدم `modelSupport` عندما يجب على OpenClaw استنتاج Plugin المزوّد الخاص بك من
|
||||
معرّفات النماذج المختصرة مثل `gpt-5.4` أو `claude-sonnet-4.6` قبل تحميل
|
||||
وقت تشغيل Plugin.
|
||||
استخدم `modelSupport` عندما يجب على OpenClaw أن يستنتج Plugin المزوّد الخاص بك من
|
||||
معرّفات نماذج مختصرة مثل `gpt-5.4` أو `claude-sonnet-4.6` قبل تحميل وقت تشغيل Plugin.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -468,88 +506,87 @@ Plugins المكتشفة. تفشل الملكية الملتبسة بشكل مغ
|
||||
}
|
||||
```
|
||||
|
||||
يطبّق OpenClaw ترتيب الأولوية التالي:
|
||||
يطبق OpenClaw ترتيب الأولوية هذا:
|
||||
|
||||
- تستخدم مراجع `provider/model` الصريحة بيانات البيان الوصفية المملوكة في `providers`
|
||||
- تتغلب `modelPatterns` على `modelPrefixes`
|
||||
- إذا طابق كل من Plugin غير مرفق وPlugin مرفق، فإن Plugin
|
||||
غير المرفق يفوز
|
||||
- يتم تجاهل الغموض المتبقي حتى يحدد المستخدم أو التكوين مزوّدًا
|
||||
- تستخدم مراجع `provider/model` الصريحة بيانات تعريف `providers` المملوكة في البيان
|
||||
- تتفوق `modelPatterns` على `modelPrefixes`
|
||||
- إذا تطابق Plugin غير مضمّن وPlugin مضمّن معًا، فإن Plugin غير المضمّن
|
||||
هو الذي يفوز
|
||||
- يُتجاهل أي غموض متبقٍ إلى أن يحدد المستخدم أو الإعدادات مزوّدًا
|
||||
|
||||
الحقول:
|
||||
|
||||
| الحقل | النوع | ما الذي يعنيه |
|
||||
| --------------- | ---------- | ------------------------------------------------------------------------------- |
|
||||
| `modelPrefixes` | `string[]` | بادئات تتم مطابقتها باستخدام `startsWith` مقابل معرّفات النماذج المختصرة. |
|
||||
| `modelPatterns` | `string[]` | مصادر regex تتم مطابقتها مقابل معرّفات النماذج المختصرة بعد إزالة لاحقة ملف التعريف. |
|
||||
| الحقل | النوع | ما الذي يعنيه |
|
||||
| --------------- | ---------- | -------------------------------------------------------------------------------- |
|
||||
| `modelPrefixes` | `string[]` | بادئات تُطابَق باستخدام `startsWith` مع معرّفات النماذج المختصرة. |
|
||||
| `modelPatterns` | `string[]` | مصادر regex تُطابَق مع معرّفات النماذج المختصرة بعد إزالة لاحقة ملف التعريف. |
|
||||
|
||||
أصبحت مفاتيح القدرات القديمة على المستوى الأعلى مهجورة. استخدم `openclaw doctor --fix` من أجل
|
||||
أصبحت مفاتيح الإمكانات القديمة ذات المستوى الأعلى مهملة. استخدم `openclaw doctor --fix` من أجل
|
||||
نقل `speechProviders` و`realtimeTranscriptionProviders`،
|
||||
و`realtimeVoiceProviders`، و`mediaUnderstandingProviders`،
|
||||
و`imageGenerationProviders`، و`videoGenerationProviders`،
|
||||
و`webFetchProviders`، و`webSearchProviders` إلى `contracts`؛ إذ لم يعد
|
||||
تحميل البيان العادي يتعامل مع تلك الحقول العليا على أنها ملكية
|
||||
قدرات.
|
||||
و`realtimeVoiceProviders` و`mediaUnderstandingProviders`،
|
||||
و`imageGenerationProviders` و`videoGenerationProviders`،
|
||||
و`webFetchProviders` و`webSearchProviders` إلى `contracts`؛ لم يعد
|
||||
تحميل البيان العادي يعامل تلك الحقول ذات المستوى الأعلى على أنها
|
||||
ملكية للإمكانات.
|
||||
|
||||
## البيان مقابل `package.json`
|
||||
## البيان مقابل package.json
|
||||
|
||||
يخدم الملفان وظيفتين مختلفتين:
|
||||
يؤدي الملفان مهمتين مختلفتين:
|
||||
|
||||
| الملف | استخدمه من أجل |
|
||||
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `openclaw.plugin.json` | الاكتشاف، والتحقق من صحة التكوين، وبيانات اختيار المصادقة الوصفية، وتلميحات UI التي يجب أن توجد قبل تشغيل كود Plugin |
|
||||
| `package.json` | بيانات npm الوصفية، وتثبيت الاعتماديات، وكتلة `openclaw` المستخدمة لنقاط الدخول، وبوابة التثبيت، والإعداد، أو بيانات الكتالوج الوصفية |
|
||||
| الملف | استخدمه من أجل |
|
||||
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `openclaw.plugin.json` | الاكتشاف، والتحقق من صحة الإعدادات، وبيانات تعريف خيارات المصادقة، وتلميحات واجهة المستخدم التي يجب أن تكون موجودة قبل تشغيل كود Plugin |
|
||||
| `package.json` | بيانات تعريف npm، وتثبيت التبعيات، وكتلة `openclaw` المستخدمة لنقاط الدخول، أو تقييد التثبيت، أو الإعداد، أو بيانات تعريف الفهرس |
|
||||
|
||||
إذا لم تكن متأكدًا من موضع قطعة من البيانات الوصفية، فاستخدم هذه القاعدة:
|
||||
إذا لم تكن متأكدًا من الموضع الذي يجب أن تنتمي إليه قطعة من بيانات التعريف، فاستخدم هذه القاعدة:
|
||||
|
||||
- إذا كان يجب على OpenClaw معرفتها قبل تحميل كود Plugin، فضعها في `openclaw.plugin.json`
|
||||
- إذا كانت تتعلق بالتغليف أو ملفات الدخول أو سلوك تثبيت npm، فضعها في `package.json`
|
||||
|
||||
### حقول `package.json` التي تؤثر في الاكتشاف
|
||||
|
||||
توجد بعض بيانات Plugin الوصفية قبل وقت التشغيل عمدًا في `package.json` تحت كتلة
|
||||
`openclaw` بدلًا من `openclaw.plugin.json`.
|
||||
توجد بعض بيانات تعريف Plugin قبل وقت التشغيل عمدًا في `package.json` تحت
|
||||
كتلة `openclaw` بدلًا من `openclaw.plugin.json`.
|
||||
|
||||
أمثلة مهمة:
|
||||
|
||||
| الحقل | ما الذي يعنيه |
|
||||
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `openclaw.extensions` | يعلن نقاط دخول Plugin الأصلية. يجب أن تبقى داخل دليل حزمة Plugin. |
|
||||
| `openclaw.runtimeExtensions` | يعلن نقاط دخول وقت تشغيل JavaScript المبنية للحزم المثبتة. يجب أن تبقى داخل دليل حزمة Plugin. |
|
||||
| `openclaw.setupEntry` | نقطة دخول خفيفة خاصة بالإعداد تُستخدم أثناء الإعداد الأولي، وبدء القنوات المؤجل، واكتشاف حالة القناة/SecretRef للقراءة فقط. يجب أن تبقى داخل دليل حزمة Plugin. |
|
||||
| `openclaw.runtimeSetupEntry` | يعلن نقطة دخول الإعداد المبنية بلغة JavaScript للحزم المثبتة. يجب أن تبقى داخل دليل حزمة Plugin. |
|
||||
| `openclaw.channel` | بيانات وصفية منخفضة التكلفة لكتالوج القنوات مثل التسميات ومسارات الوثائق والأسماء المستعارة ونصوص الاختيار. |
|
||||
| `openclaw.channel.configuredState` | بيانات وصفية خفيفة لفاحص الحالة المكوّنة يمكنها الإجابة عن السؤال "هل يوجد إعداد معتمد على البيئة فقط بالفعل؟" من دون تحميل وقت تشغيل القناة الكامل. |
|
||||
| `openclaw.channel.persistedAuthState` | بيانات وصفية خفيفة لفاحص المصادقة المحفوظة يمكنها الإجابة عن السؤال "هل يوجد أي تسجيل دخول بالفعل؟" من دون تحميل وقت تشغيل القناة الكامل. |
|
||||
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | تلميحات تثبيت/تحديث للـ Plugins المرفقة والمنشورة خارجيًا. |
|
||||
| `openclaw.install.defaultChoice` | مسار التثبيت المفضل عند توفر مصادر تثبيت متعددة. |
|
||||
| `openclaw.install.minHostVersion` | الحد الأدنى المدعوم لإصدار مضيف OpenClaw، باستخدام حد أدنى semver مثل `>=2026.3.22`. |
|
||||
| `openclaw.install.allowInvalidConfigRecovery` | يسمح بمسار استرداد ضيق لإعادة تثبيت Plugin مرفق عندما يكون التكوين غير صالح. |
|
||||
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | يسمح لأسطح القنوات الخاصة بالإعداد فقط بالتحميل قبل Plugin القناة الكامل أثناء بدء التشغيل. |
|
||||
| الحقل | ما الذي يعنيه |
|
||||
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `openclaw.extensions` | يصرّح بنقاط دخول Plugin الأصلية. يجب أن تبقى داخل دليل حزمة Plugin. |
|
||||
| `openclaw.runtimeExtensions` | يصرّح بنقاط دخول وقت تشغيل JavaScript المبنية للحزم المثبتة. يجب أن تبقى داخل دليل حزمة Plugin. |
|
||||
| `openclaw.setupEntry` | نقطة دخول خفيفة للإعداد فقط تُستخدم أثناء الإعداد الأوّلي، وبدء تشغيل القنوات المؤجل، واكتشاف حالة القناة/SecretRef للقراءة فقط. يجب أن تبقى داخل دليل حزمة Plugin. |
|
||||
| `openclaw.runtimeSetupEntry` | يصرّح بنقطة دخول الإعداد المبنية لـ JavaScript للحزم المثبتة. يجب أن تبقى داخل دليل حزمة Plugin. |
|
||||
| `openclaw.channel` | بيانات تعريف منخفضة التكلفة لفهرس القناة مثل التسميات ومسارات التوثيق والأسماء المستعارة ونص الاختيار. |
|
||||
| `openclaw.channel.configuredState` | بيانات تعريف خفيفة لفاحص الحالة المهيّأة يمكنها الإجابة عن السؤال «هل يوجد بالفعل إعداد يعتمد فقط على البيئة؟» من دون تحميل وقت تشغيل القناة الكامل. |
|
||||
| `openclaw.channel.persistedAuthState` | بيانات تعريف خفيفة لفاحص حالة المصادقة المستمرة يمكنها الإجابة عن السؤال «هل تم بالفعل تسجيل الدخول إلى أي شيء؟» من دون تحميل وقت تشغيل القناة الكامل. |
|
||||
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | تلميحات التثبيت/التحديث للـ Plugins المضمّنة والمنشورة خارجيًا. |
|
||||
| `openclaw.install.defaultChoice` | مسار التثبيت المفضل عندما تتوفر مصادر تثبيت متعددة. |
|
||||
| `openclaw.install.minHostVersion` | الحد الأدنى لإصدار مضيف OpenClaw المدعوم، باستخدام حد semver أدنى مثل `>=2026.3.22`. |
|
||||
| `openclaw.install.allowInvalidConfigRecovery` | يسمح بمسار استرداد ضيق لإعادة تثبيت Plugin مضمّن عندما تكون الإعدادات غير صالحة. |
|
||||
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | يسمح بتحميل أسطح القناة الخاصة بالإعداد فقط قبل Plugin القناة الكامل أثناء بدء التشغيل. |
|
||||
|
||||
يتم فرض `openclaw.install.minHostVersion` أثناء التثبيت وتحميل سجل
|
||||
البيان. وتُرفض القيم غير الصالحة؛ أما القيم الأحدث لكن الصالحة فتتجاوز
|
||||
يُفرَض `openclaw.install.minHostVersion` أثناء التثبيت وتحميل سجل
|
||||
البيان. وتُرفض القيم غير الصالحة؛ أما القيم الأحدث ولكن الصالحة فتتجاوز
|
||||
Plugin على المضيفين الأقدم.
|
||||
|
||||
يجب على Plugins القنوات توفير `openclaw.setupEntry` عندما تحتاج الحالة أو قائمة القنوات
|
||||
أو فحوصات SecretRef إلى تحديد الحسابات المكوّنة من دون تحميل
|
||||
وقت التشغيل الكامل. يجب أن تعرض نقطة دخول الإعداد بيانات القناة الوصفية بالإضافة إلى
|
||||
مهايئات التكوين والحالة والأسرار الآمنة للإعداد؛ واحفظ عملاء الشبكة ومستمعي gateway
|
||||
وأوقات تشغيل النقل في نقطة دخول الامتداد الرئيسية.
|
||||
يجب على Plugins القنوات توفير `openclaw.setupEntry` عندما تحتاج عمليات فحص الحالة أو قائمة القنوات
|
||||
أو SecretRef إلى تحديد الحسابات المهيّأة من دون تحميل وقت التشغيل الكامل.
|
||||
ويجب أن تعرض نقطة دخول الإعداد بيانات تعريف القناة بالإضافة إلى محوّلات الإعداد الآمنة،
|
||||
والحالة، والأسرار؛ وأبقِ عملاء الشبكة، ومستمعي Gateway، وبيئات تشغيل النقل
|
||||
في نقطة دخول extension الرئيسية.
|
||||
|
||||
لا تتجاوز حقول نقطة دخول وقت التشغيل فحوصات حدود الحزمة لحقول
|
||||
نقطة دخول المصدر. على سبيل المثال، لا يمكن لـ `openclaw.runtimeExtensions` أن تجعل
|
||||
مسار `openclaw.extensions` الهارب قابلاً للتحميل.
|
||||
حقول نقطة دخول وقت التشغيل لا تتجاوز فحوصات حدود الحزمة الخاصة بحقول نقاط
|
||||
دخول المصدر. على سبيل المثال، لا يمكن لـ `openclaw.runtimeExtensions` أن يجعل
|
||||
مسار `openclaw.extensions` المتجاوز للحدود قابلًا للتحميل.
|
||||
|
||||
إن `openclaw.install.allowInvalidConfigRecovery` ضيق عمدًا. فهو
|
||||
لا يجعل التكوينات المعطوبة العشوائية قابلة للتثبيت. واليوم يسمح فقط
|
||||
لتدفقات التثبيت بالتعافي من إخفاقات ترقية معينة قديمة لPlugins المرفقة، مثل
|
||||
مسار Plugin مرفق مفقود أو إدخال `channels.<id>` قديم لذلك Plugin المرفق نفسه.
|
||||
أما أخطاء التكوين غير ذات الصلة فلا تزال تمنع التثبيت وتوجّه المشغّلين إلى
|
||||
`openclaw doctor --fix`.
|
||||
إن `openclaw.install.allowInvalidConfigRecovery` ضيق النطاق عمدًا. فهو لا
|
||||
يجعل الإعدادات المعطلة بشكل تعسفي قابلة للتثبيت. وهو اليوم يسمح فقط
|
||||
لتدفقات التثبيت بالتعافي من أعطال ترقية محددة في Plugins المضمّنة القديمة، مثل
|
||||
مسار Plugin مضمّن مفقود أو إدخال قديم `channels.<id>` لذلك
|
||||
Plugin المضمّن نفسه. وتظل أخطاء الإعدادات غير المرتبطة تمنع التثبيت وتوجّه
|
||||
المشغّلين إلى `openclaw doctor --fix`.
|
||||
|
||||
إن `openclaw.channel.persistedAuthState` هو بيانات حزمة وصفية خاصة
|
||||
بوحدة فاحص صغيرة:
|
||||
تمثل `openclaw.channel.persistedAuthState` بيانات تعريف حزمة لوحدة فحص صغيرة:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -565,13 +602,13 @@ Plugin على المضيفين الأقدم.
|
||||
}
|
||||
```
|
||||
|
||||
استخدمه عندما تحتاج تدفقات الإعداد أو doctor أو الحالة المكوّنة إلى
|
||||
فحص مصادقة منخفض التكلفة بنعم/لا قبل تحميل Plugin القناة الكامل. يجب أن يكون
|
||||
التصدير المستهدف دالة صغيرة تقرأ الحالة المحفوظة فقط؛ ولا تمرره عبر
|
||||
الحاوية الكاملة لوقت تشغيل القناة.
|
||||
استخدمها عندما تحتاج تدفقات الإعداد أو doctor أو الحالة المهيّأة إلى فحص
|
||||
مصادقة سريع بنعم/لا قبل تحميل Plugin القناة الكامل. ويجب أن يكون التصدير
|
||||
المستهدف دالة صغيرة تقرأ الحالة المستمرة فقط؛ ولا تمرّرها عبر barrel
|
||||
وقت تشغيل القناة الكامل.
|
||||
|
||||
يتبع `openclaw.channel.configuredState` الشكل نفسه لفحوصات
|
||||
الحالة المكوّنة منخفضة التكلفة المعتمدة على البيئة فقط:
|
||||
ويتبع `openclaw.channel.configuredState` الشكل نفسه لفحوصات الحالة المهيّأة
|
||||
الرخيصة المعتمدة على البيئة فقط:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -587,92 +624,92 @@ Plugin على المضيفين الأقدم.
|
||||
}
|
||||
```
|
||||
|
||||
استخدمه عندما تستطيع القناة الإجابة عن الحالة المكوّنة من البيئة أو مدخلات
|
||||
صغيرة أخرى غير وقت التشغيل. وإذا كان الفحص يحتاج إلى حل كامل للتكوين أو إلى
|
||||
وقت تشغيل القناة الحقيقي، فأبقِ هذا المنطق في hook
|
||||
`config.hasConfiguredState` الخاص بالـ Plugin بدلًا من ذلك.
|
||||
استخدمه عندما تستطيع قناة ما الإجابة عن الحالة المهيّأة من البيئة أو من
|
||||
مدخلات صغيرة أخرى غير وقت التشغيل. وإذا كان الفحص يحتاج إلى حل كامل
|
||||
للإعدادات أو إلى وقت تشغيل القناة الحقيقي، فأبقِ هذا المنطق في الخطاف
|
||||
`config.hasConfiguredState` الخاص بـ Plugin بدلًا من ذلك.
|
||||
|
||||
## أولوية الاكتشاف (معرّفات Plugin المكررة)
|
||||
|
||||
يكتشف OpenClaw Plugins من عدة جذور (مرفقة، وتثبيت عام، ومساحة عمل، ومسارات صريحة محددة في التكوين). إذا اشتركت عمليتا اكتشاف في نفس `id`، فسيتم الاحتفاظ فقط بالبيان ذي **الأولوية الأعلى**؛ أما النسخ المكررة ذات الأولوية الأدنى فيتم إسقاطها بدلًا من تحميلها بجانبه.
|
||||
يكتشف OpenClaw Plugins من عدة جذور (المضمّنة، والتثبيت العام، ومساحة العمل، والمسارات الصريحة المختارة من الإعدادات). وإذا اشترك اكتشافان في `id` نفسه، فلا يُحتفَظ إلا بالبيان ذي **الأولوية الأعلى**؛ وتُسقَط النسخ المكررة ذات الأولوية الأدنى بدلًا من تحميلها بجانبه.
|
||||
|
||||
الأولوية، من الأعلى إلى الأدنى:
|
||||
ترتيب الأولوية، من الأعلى إلى الأدنى:
|
||||
|
||||
1. **محدد في التكوين** — مسار مثبت صراحةً في `plugins.entries.<id>`
|
||||
2. **مرفق** — Plugins تُشحن مع OpenClaw
|
||||
3. **تثبيت عام** — Plugins مثبّتة في جذر Plugins العام لـ OpenClaw
|
||||
4. **مساحة العمل** — Plugins مكتشفة نسبةً إلى مساحة العمل الحالية
|
||||
1. **المختار من الإعدادات** — مسار مثبّت صراحة في `plugins.entries.<id>`
|
||||
2. **المضمّن** — Plugins المشحونة مع OpenClaw
|
||||
3. **التثبيت العام** — Plugins المثبتة في جذر Plugin العام لـ OpenClaw
|
||||
4. **مساحة العمل** — Plugins المكتشفة نسبة إلى مساحة العمل الحالية
|
||||
|
||||
الآثار المترتبة:
|
||||
|
||||
- لن تؤدي نسخة متفرعة أو قديمة من Plugin مرفق موجودة في مساحة العمل إلى حجب النسخة المرفقة.
|
||||
- لتجاوز Plugin مرفق فعليًا بنسخة محلية، ثبّته عبر `plugins.entries.<id>` حتى يفوز بالأولوية بدلًا من الاعتماد على اكتشاف مساحة العمل.
|
||||
- يتم تسجيل إسقاط النسخ المكررة حتى يتمكن Doctor وتشخيصات بدء التشغيل من الإشارة إلى النسخة المستبعدة.
|
||||
- لن تطغى نسخة متفرعة أو قديمة من Plugin مضمّن موجودة في مساحة العمل على النسخة المضمّنة.
|
||||
- لتجاوز Plugin مضمّن فعليًا بنسخة محلية، ثبّته عبر `plugins.entries.<id>` لكي يفوز بالأولوية بدلًا من الاعتماد على اكتشاف مساحة العمل.
|
||||
- تُسجَّل عمليات إسقاط النسخ المكررة حتى يتمكن Doctor وتشخيصات بدء التشغيل من الإشارة إلى النسخة التي تم تجاهلها.
|
||||
|
||||
## متطلبات مخطط JSON
|
||||
|
||||
- **يجب على كل Plugin أن يوفّر مخطط JSON**، حتى إذا كان لا يقبل أي تكوين.
|
||||
- يُعد المخطط الفارغ مقبولًا (مثلًا، `{ "type": "object", "additionalProperties": false }`).
|
||||
- يتم التحقق من صحة المخططات وقت قراءة/كتابة التكوين، وليس وقت التشغيل.
|
||||
- **يجب على كل Plugin أن يشحن مخطط JSON**، حتى إذا كان لا يقبل أي إعدادات.
|
||||
- يُقبل مخطط فارغ (على سبيل المثال، `{ "type": "object", "additionalProperties": false }`).
|
||||
- تُتحقق المخططات عند وقت قراءة/كتابة الإعدادات، وليس عند وقت التشغيل.
|
||||
|
||||
## سلوك التحقق
|
||||
|
||||
- مفاتيح `channels.*` غير المعروفة هي **أخطاء**، ما لم يكن معرّف القناة مُعلنًا بواسطة
|
||||
- مفاتيح `channels.*` غير المعروفة تُعد **أخطاء**، ما لم يكن معرّف القناة مصرّحًا به بواسطة
|
||||
بيان Plugin.
|
||||
- يجب أن تشير `plugins.entries.<id>` و`plugins.allow` و`plugins.deny` و`plugins.slots.*`
|
||||
إلى معرّفات Plugin **قابلة للاكتشاف**. المعرّفات غير المعروفة هي **أخطاء**.
|
||||
- إذا كان Plugin مثبتًا لكنه يملك بيانًا أو مخططًا معطوبًا أو مفقودًا،
|
||||
إلى معرّفات Plugin **قابلة للاكتشاف**. وتُعد المعرّفات غير المعروفة **أخطاء**.
|
||||
- إذا كان Plugin مثبتًا ولكن لديه بيان أو مخطط معطّل أو مفقود،
|
||||
يفشل التحقق ويبلّغ Doctor عن خطأ Plugin.
|
||||
- إذا كان تكوين Plugin موجودًا لكن Plugin **معطّل**، فيُحتفظ بالتكوين
|
||||
وتظهر **تحذير** في Doctor + السجلات.
|
||||
- إذا وُجدت إعدادات Plugin ولكن Plugin **معطّل**، فسيتم الاحتفاظ بالإعدادات
|
||||
وسيظهر **تحذير** في Doctor + السجلات.
|
||||
|
||||
راجع [مرجع التكوين](/ar/gateway/configuration) للاطلاع على مخطط `plugins.*` الكامل.
|
||||
راجع [مرجع الإعدادات](/ar/gateway/configuration) للاطلاع على مخطط `plugins.*` الكامل.
|
||||
|
||||
## ملاحظات
|
||||
|
||||
- البيان **مطلوب للـ Plugins الأصلية في OpenClaw**، بما في ذلك التحميل من نظام الملفات المحلي.
|
||||
- البيان **مطلوب لـ Plugins الأصلية في OpenClaw**، بما في ذلك التحميلات المحلية من نظام الملفات.
|
||||
- لا يزال وقت التشغيل يحمّل وحدة Plugin بشكل منفصل؛ فالبيان مخصص فقط
|
||||
للاكتشاف + التحقق.
|
||||
- تُحلَّل البيانات الأصلية باستخدام JSON5، لذا تُقبل التعليقات والفواصل اللاحقة
|
||||
والمفاتيح غير المقتبسة طالما أن القيمة النهائية لا تزال كائنًا.
|
||||
- لا يقرأ محمّل البيان إلا حقول البيان الموثقة. تجنب إضافة
|
||||
مفاتيح عليا مخصصة هنا.
|
||||
- يمثل `providerAuthEnvVars` مسار البيانات الوصفية منخفضة التكلفة لفحوصات المصادقة، والتحقق من
|
||||
علامات البيئة، والأسطح المشابهة الخاصة بمصادقة المزوّد التي يجب ألا تشغّل
|
||||
وقت تشغيل Plugin لمجرد فحص أسماء متغيرات البيئة.
|
||||
- يسمح `providerAuthAliases` لمتغيرات المزوّد بإعادة استخدام متغيرات بيئة
|
||||
مصادقة مزوّد آخر، وملفات تعريف المصادقة، والمصادقة المدعومة بالتكوين، وخيار الإعداد الأولي لمفتاح API
|
||||
من دون ترميز هذه العلاقة صراحةً في core.
|
||||
- يسمح `providerEndpoints` لPlugins المزوّدين بامتلاك بيانات وصفية بسيطة
|
||||
لمطابقة مضيف نقطة النهاية/`baseUrl`. استخدمه فقط لفئات نقاط النهاية التي يدعمها core
|
||||
بالفعل؛ ولا يزال Plugin يملك سلوك وقت التشغيل.
|
||||
- يمثل `syntheticAuthRefs` مسار البيانات الوصفية منخفضة التكلفة
|
||||
لـ hooks المصادقة الاصطناعية المملوكة للمزوّد التي يجب أن تكون مرئية
|
||||
لاكتشاف النماذج البارد قبل وجود سجل وقت التشغيل. أدرج فقط المراجع التي ينفذ
|
||||
مزوّد وقت التشغيل أو الواجهة الخلفية لـ CLI الخاصة بها `resolveSyntheticAuth` فعلًا.
|
||||
- يمثل `nonSecretAuthMarkers` مسار البيانات الوصفية منخفضة التكلفة
|
||||
لمفاتيح API النائبة المملوكة للـ plugin المرفق مثل العلامات المحلية أو OAuth أو
|
||||
بيانات الاعتماد المحيطة. يعاملها core على أنها غير سرية لعرض المصادقة
|
||||
وتدقيق الأسرار من دون ترميز المزوّد المالك صراحةً.
|
||||
- يمثل `channelEnvVars` مسار البيانات الوصفية منخفضة التكلفة للتراجع إلى
|
||||
متغيرات بيئة shell، ومطالبات الإعداد، والأسطح المماثلة للقنوات التي يجب ألا تشغّل
|
||||
وقت تشغيل Plugin لمجرد فحص أسماء متغيرات البيئة. أسماء متغيرات البيئة هي بيانات وصفية،
|
||||
وليست تفعيلًا بحد ذاتها: فما زالت الحالة، والتدقيق، والتحقق من تسليم Cron،
|
||||
والأسطح الأخرى للقراءة فقط تطبق الثقة الخاصة بالـ Plugin وسياسة التفعيل الفعالة قبل أن
|
||||
تتعامل مع متغير بيئة على أنه قناة مكوّنة.
|
||||
- يمثل `providerAuthChoices` مسار البيانات الوصفية منخفضة التكلفة لمنتقيات اختيار المصادقة،
|
||||
وحل `--auth-choice`، وتعيين المزوّد المفضل، وتسجيل أعلام CLI البسيط للإعداد الأولي
|
||||
قبل تحميل وقت تشغيل المزوّد. وبالنسبة إلى بيانات المعالج الوصفية في وقت التشغيل
|
||||
التي تتطلب كود المزوّد، راجع
|
||||
[hooks وقت تشغيل المزوّد](/ar/plugins/architecture#provider-runtime-hooks).
|
||||
- تُحدَّد أنواع Plugins الحصرية عبر `plugins.slots.*`.
|
||||
- تُحلَّل البيانات الأصلية باستخدام JSON5، لذا تُقبل التعليقات، والفواصل
|
||||
اللاحقة، والمفاتيح غير الموضوعة بين علامتَي اقتباس ما دامت القيمة النهائية لا تزال كائنًا.
|
||||
- لا يقرأ محمّل البيان إلا حقول البيان الموثقة. تجنّب إضافة
|
||||
مفاتيح مخصصة ذات مستوى أعلى هنا.
|
||||
- تمثل `providerAuthEnvVars` مسار بيانات التعريف الرخيص لفحوصات المصادقة، والتحقق من
|
||||
علامات البيئة، وأسطح مصادقة المزوّد المشابهة التي يجب ألا تشغّل وقت تشغيل Plugin
|
||||
فقط لفحص أسماء متغيرات البيئة.
|
||||
- تسمح `providerAuthAliases` لمتغيرات المزوّد بإعادة استخدام مصادقة
|
||||
مزوّد آخر: متغيرات البيئة، وملفات تعريف المصادقة، والمصادقة المدعومة بالإعدادات، وخيار
|
||||
الإعداد الأوّلي لمفتاح API من دون ترميز تلك العلاقة داخل النواة.
|
||||
- تسمح `providerEndpoints` لـ Plugins المزوّدين بامتلاك بيانات تعريف بسيطة لمطابقة
|
||||
`host`/`baseUrl` لنقاط النهاية. استخدمها فقط لفئات نقاط النهاية التي تدعمها النواة
|
||||
بالفعل؛ وما يزال Plugin يملك سلوك وقت التشغيل.
|
||||
- تمثل `syntheticAuthRefs` مسار بيانات التعريف الرخيص لخطافات المصادقة الاصطناعية
|
||||
المملوكة للمزوّد والتي يجب أن تكون مرئية لاكتشاف النماذج البارد قبل وجود
|
||||
سجل وقت التشغيل. لا تُدرج إلا المراجع التي يطبّق مزوّد وقت التشغيل أو الواجهة الخلفية لـ CLI الخاصة بها
|
||||
بالفعل `resolveSyntheticAuth`.
|
||||
- تمثل `nonSecretAuthMarkers` مسار بيانات التعريف الرخيص لعناصر
|
||||
مفتاح API البديلة المملوكة لـ Plugin المضمّن مثل العلامات المحلية أو OAuth أو بيانات الاعتماد المحيطة.
|
||||
وتتعامل النواة مع هذه القيم على أنها غير سرية لأغراض عرض المصادقة وتدقيق الأسرار
|
||||
من دون ترميز المزوّد المالك داخلها.
|
||||
- تمثل `channelEnvVars` مسار بيانات التعريف الرخيص للاحتياط المعتمد على بيئة الصدفة،
|
||||
ومطالبات الإعداد، وأسطح القنوات المشابهة التي يجب ألا تشغّل وقت تشغيل Plugin
|
||||
فقط لفحص أسماء متغيرات البيئة. أسماء متغيرات البيئة هي بيانات تعريف، وليست تفعيلًا
|
||||
بحد ذاتها: فما تزال أسطح الحالة، والتدقيق، والتحقق من تسليم Cron، وغيرها من الأسطح
|
||||
المخصّصة للقراءة فقط تطبق سياسة الثقة والتفعيل الفعّال الخاصة بـ Plugin قبل أن
|
||||
تتعامل مع متغير البيئة على أنه قناة مهيّأة.
|
||||
- تمثل `providerAuthChoices` مسار بيانات التعريف الرخيص لمنتقيات خيارات المصادقة،
|
||||
وحل `--auth-choice`، وتخطيط المزوّد المفضل، وتسجيل أعلام
|
||||
CLI البسيطة للإعداد الأوّلي قبل تحميل وقت تشغيل المزوّد. أما بالنسبة إلى بيانات تعريف معالج
|
||||
وقت التشغيل التي تتطلب كود المزوّد، فراجع
|
||||
[خطافات وقت تشغيل المزوّد](/ar/plugins/architecture#provider-runtime-hooks).
|
||||
- تُختار أنواع Plugin الحصرية عبر `plugins.slots.*`.
|
||||
- يتم اختيار `kind: "memory"` بواسطة `plugins.slots.memory`.
|
||||
- يتم اختيار `kind: "context-engine"` بواسطة `plugins.slots.contextEngine`
|
||||
(الافتراضي: `legacy` المدمج).
|
||||
- يمكن حذف `channels` و`providers` و`cliBackends` و`skills` عندما
|
||||
لا يحتاج Plugin إليها.
|
||||
- ويتم اختيار `kind: "context-engine"` بواسطة `plugins.slots.contextEngine`
|
||||
(الافتراضي: `legacy` المضمّن).
|
||||
- يمكن حذف `channels` و`providers` و`cliBackends` و`skills` عندما لا
|
||||
يحتاجها Plugin.
|
||||
- إذا كان Plugin الخاص بك يعتمد على وحدات أصلية، فوثّق خطوات البناء وأي
|
||||
متطلبات قائمة سماح خاصة بمدير الحزم (على سبيل المثال، pnpm `allow-build-scripts`
|
||||
متطلبات قائمة سماح لمدير الحزم (على سبيل المثال، `allow-build-scripts` في pnpm
|
||||
- `pnpm rebuild <package>`).
|
||||
|
||||
## ذو صلة
|
||||
|
||||
@ -1,59 +1,59 @@
|
||||
---
|
||||
read_when:
|
||||
- أنت تغيّر وقت تشغيل الوكيل المضمّن أو سجل Harness الخاص به
|
||||
- أنت تسجّل Harness وكيل من مكوّن إضافي مضمّن أو موثوق به
|
||||
- تحتاج إلى فهم كيفية ارتباط مكوّن Codex الإضافي بموفري النماذج
|
||||
- أنت تغيّر وقت تشغيل الوكيل المضمّن أو سجل أداة التسخير الخاص به
|
||||
- أنت تسجّل أداة تسخير وكيل من Plugin مضمّنة أو موثوقة
|
||||
- تحتاج إلى فهم كيفية ارتباط Plugin Codex بموفّري النماذج
|
||||
sidebarTitle: Agent Harness
|
||||
summary: سطح SDK تجريبي للمكوّنات الإضافية التي تستبدل منفّذ الوكيل المضمّن منخفض المستوى
|
||||
title: مكوّنات Harness الإضافية للوكيل
|
||||
summary: واجهة SDK تجريبية للإضافات التي تستبدل منفّذ الوكيل المضمّن منخفض المستوى
|
||||
title: إضافات أداة تسخير الوكيل
|
||||
x-i18n:
|
||||
generated_at: "2026-04-12T00:18:56Z"
|
||||
generated_at: "2026-04-22T07:17:54Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 62b88fd24ce8b600179db27e16e8d764a2cd7a14e5c5df76374c33121aa5e365
|
||||
source_hash: 728fef59ae3cce29a3348842820f1f71a2eac98ae6b276179bce6c85d16613df
|
||||
source_path: plugins/sdk-agent-harness.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# مكوّنات Agent Harness الإضافية
|
||||
# إضافات أداة تسخير الوكيل
|
||||
|
||||
يُعد **agent harness** المنفّذ منخفض المستوى لدورة واحدة مُحضّرة لوكيل OpenClaw.
|
||||
وهو ليس موفر نماذج، وليس قناة، وليس سجل أدوات.
|
||||
**أداة تسخير الوكيل** هي المنفّذ منخفض المستوى لدورة واحدة مُحضّرة من وكيل OpenClaw.
|
||||
وهي ليست موفّر نماذج، وليست قناة، وليست سجل أدوات.
|
||||
|
||||
استخدم هذا السطح فقط للمكوّنات الإضافية الأصلية المضمّنة أو الموثوق بها. لا يزال
|
||||
هذا التعاقد تجريبيًا لأن أنواع المعاملات تعكس عمدًا المنفّذ المضمّن الحالي.
|
||||
استخدم هذه الواجهة فقط مع Plugins أصلية مضمّنة أو موثوقة. لا يزال هذا العقد
|
||||
تجريبيًا لأن أنواع المعاملات تعكس عمدًا المنفّذ المضمّن الحالي.
|
||||
|
||||
## متى تستخدم harness
|
||||
## متى تستخدم أداة تسخير
|
||||
|
||||
سجّل agent harness عندما تكون لعائلة نماذج ما بيئة جلسات أصلية خاصة بها
|
||||
ويكون نقل موفر OpenClaw العادي تجريدًا غير مناسب.
|
||||
سجّل أداة تسخير وكيل عندما تمتلك عائلة نماذج وقت تشغيل جلسة أصليًا خاصًا بها
|
||||
ويكون نقل الموفّر العادي في OpenClaw تجريدًا غير مناسب.
|
||||
|
||||
أمثلة:
|
||||
|
||||
- خادم coding-agent أصلي يملك سلاسل التنفيذ والضغط
|
||||
- CLI أو daemon محلي يجب أن يبث أحداث الخطة/الاستدلال/الأدوات الأصلية
|
||||
- بيئة تشغيل نموذج تحتاج إلى معرّف استئناف خاص بها بالإضافة إلى
|
||||
نص جلسة OpenClaw
|
||||
- خادم وكيل برمجة أصلي يمتلك سلاسل المحادثة وCompaction
|
||||
- CLI أو خدمة daemon محلية يجب أن تبث أحداث الخطة/الاستدلال/الأدوات الأصلية
|
||||
- وقت تشغيل نموذج يحتاج إلى معرّف استئناف خاص به بالإضافة إلى
|
||||
نص الجلسة في OpenClaw
|
||||
|
||||
**لا** تسجّل harness لمجرد إضافة واجهة API جديدة لـ LLM. بالنسبة لواجهات
|
||||
HTTP أو WebSocket العادية للنماذج، أنشئ [مكوّن provider إضافي](/ar/plugins/sdk-provider-plugins).
|
||||
**لا** تسجّل أداة تسخير فقط لإضافة واجهة API جديدة لـ LLM. بالنسبة إلى واجهات API
|
||||
العادية للنماذج عبر HTTP أو WebSocket، أنشئ [Plugin موفّر](/ar/plugins/sdk-provider-plugins).
|
||||
|
||||
## ما الذي لا يزال core يملكه
|
||||
## ما الذي لا يزال الأساس يمتلكه
|
||||
|
||||
قبل اختيار harness، يكون OpenClaw قد حدّد بالفعل:
|
||||
قبل اختيار أداة تسخير، يكون OpenClaw قد حدّد بالفعل:
|
||||
|
||||
- الموفر والنموذج
|
||||
- حالة المصادقة في وقت التشغيل
|
||||
- الموفّر والنموذج
|
||||
- حالة المصادقة وقت التشغيل
|
||||
- مستوى التفكير وميزانية السياق
|
||||
- ملف النص/جلسة OpenClaw
|
||||
- مساحة العمل وsandbox وسياسة الأدوات
|
||||
- عمليات رد القناة وعمليات البث
|
||||
- سياسة الرجوع إلى نموذج بديل والتبديل بين النماذج الحية
|
||||
- ملف النص/الجلسة الخاص بـ OpenClaw
|
||||
- مساحة العمل، وsandbox، وسياسة الأدوات
|
||||
- استدعاءات رد القناة واستدعاءات البث
|
||||
- سياسة الرجوع إلى نموذج بديل والتبديل الحي للنموذج
|
||||
|
||||
هذا التقسيم مقصود. يقوم harness بتشغيل محاولة مُحضّرة؛ ولا يختار
|
||||
الموفرين، ولا يستبدل تسليم القنوات، ولا يبدّل النماذج بصمت.
|
||||
هذا الفصل مقصود. أداة التسخير تشغّل محاولة مُحضّرة؛ ولا تختار
|
||||
الموفّرين، ولا تستبدل تسليم القناة، ولا تبدّل النماذج بصمت.
|
||||
|
||||
## تسجيل harness
|
||||
## تسجيل أداة تسخير
|
||||
|
||||
**الاستيراد:** `openclaw/plugin-sdk/agent-harness`
|
||||
|
||||
@ -91,84 +91,88 @@ export default definePluginEntry({
|
||||
|
||||
## سياسة الاختيار
|
||||
|
||||
يختار OpenClaw harness بعد تحديد الموفر/النموذج:
|
||||
يختار OpenClaw أداة تسخير بعد تحديد الموفّر/النموذج:
|
||||
|
||||
1. يفرض `OPENCLAW_AGENT_RUNTIME=<id>` استخدام harness مسجّل بهذا المعرّف.
|
||||
2. يفرض `OPENCLAW_AGENT_RUNTIME=pi` استخدام harness المدمج PI.
|
||||
3. يطلب `OPENCLAW_AGENT_RUNTIME=auto` من الـ harnesses المسجّلة ما إذا كانت تدعم
|
||||
الموفر/النموذج الذي تم تحديده.
|
||||
4. إذا لم يطابق أي harness مسجّل، يستخدم OpenClaw PI ما لم يكن الرجوع إلى PI
|
||||
1. `OPENCLAW_AGENT_RUNTIME=<id>` يفرض أداة تسخير مسجّلة بذلك المعرّف.
|
||||
2. `OPENCLAW_AGENT_RUNTIME=pi` يفرض أداة تسخير PI المضمّنة.
|
||||
3. `OPENCLAW_AGENT_RUNTIME=auto` يطلب من أدوات التسخير المسجّلة ما إذا كانت تدعم
|
||||
الموفّر/النموذج الذي تم تحديده.
|
||||
4. إذا لم تتطابق أي أداة تسخير مسجّلة، يستخدم OpenClaw PI ما لم يكن الرجوع إلى PI
|
||||
معطّلًا.
|
||||
|
||||
تظهر أعطال harness الخاص بالمكوّن الإضافي المفروض كأعطال تشغيل. في وضع `auto`،
|
||||
قد يرجع OpenClaw إلى PI عندما يفشل harness المحدد من المكوّن الإضافي قبل أن
|
||||
تنتج الدورة آثارًا جانبية. عيّن `OPENCLAW_AGENT_HARNESS_FALLBACK=none` أو
|
||||
`embeddedHarness.fallback: "none"` لجعل هذا الرجوع فشلًا صارمًا بدلًا من ذلك.
|
||||
تظهر أعطال أداة التسخير التابعة لـ Plugin كأعطال تشغيل. في وضع `auto`، لا يُستخدم
|
||||
الرجوع إلى PI إلا عندما لا تدعم أي أداة تسخير Plugin مسجّلة
|
||||
الموفّر/النموذج الذي تم تحديده. بمجرد أن تعلن أداة تسخير Plugin عن امتلاكها
|
||||
للتشغيل، لا يعيد OpenClaw تشغيل الدورة نفسها عبر PI لأن ذلك قد يغيّر
|
||||
دلالات المصادقة/وقت التشغيل أو يكرر الآثار الجانبية.
|
||||
|
||||
يسجّل مكوّن Codex الإضافي المضمّن `codex` كمعرّف harness له. ويتعامل core مع ذلك
|
||||
باعتباره معرّف harness عاديًا لمكوّن إضافي؛ أما الأسماء المستعارة الخاصة بـ Codex
|
||||
فينبغي أن تكون ضمن المكوّن الإضافي أو إعدادات المشغّل، لا في محدد وقت التشغيل المشترك.
|
||||
تسجّل Plugin Codex المضمّنة `codex` بوصفه معرّف أداة التسخير الخاصة بها. يتعامل
|
||||
الأساس مع ذلك بوصفه معرّف أداة تسخير Plugin عاديًا؛ أما الأسماء المستعارة
|
||||
الخاصة بـ Codex فمكانها داخل Plugin أو إعدادات المشغّل، وليس في محدِّد
|
||||
وقت التشغيل المشترك.
|
||||
|
||||
## إقران provider مع harness
|
||||
## إقران الموفّر مع أداة التسخير
|
||||
|
||||
ينبغي لمعظم الـ harnesses أيضًا تسجيل provider. يجعل provider مراجع النماذج،
|
||||
وحالة المصادقة، وبيانات النموذج الوصفية، واختيار `/model` مرئية لباقي OpenClaw.
|
||||
ثم يطالب harness بهذا الموفر في `supports(...)`.
|
||||
ينبغي لمعظم أدوات التسخير أن تسجّل أيضًا موفّرًا. يتيح الموفّر
|
||||
مراجع النماذج، وحالة المصادقة، وبيانات النموذج الوصفية، واختيار `/model`
|
||||
لبقية OpenClaw. ثم تعلن أداة التسخير امتلاكها لهذا الموفّر في `supports(...)`.
|
||||
|
||||
يتبع مكوّن Codex الإضافي المضمّن هذا النمط:
|
||||
تتبع Plugin Codex المضمّنة هذا النمط:
|
||||
|
||||
- معرّف provider: `codex`
|
||||
- معرّف الموفّر: `codex`
|
||||
- مراجع النماذج للمستخدم: `codex/gpt-5.4` و`codex/gpt-5.2` أو نموذج آخر يعيده
|
||||
خادم تطبيق Codex
|
||||
- معرّف harness: `codex`
|
||||
- المصادقة: إتاحة موفر تركيبية، لأن Codex harness يملك تسجيل الدخول/الجلسة الأصلية لـ Codex
|
||||
- طلب خادم التطبيق: يرسل OpenClaw معرّف النموذج المجرد إلى Codex ويترك
|
||||
لـ harness التحدث مع بروتوكول خادم التطبيق الأصلي
|
||||
- معرّف أداة التسخير: `codex`
|
||||
- المصادقة: إتاحة موفّر اصطناعية، لأن أداة تسخير Codex تمتلك
|
||||
تسجيل الدخول/الجلسة الأصلية لـ Codex
|
||||
- طلب خادم التطبيق: يرسل OpenClaw معرّف النموذج الخام إلى Codex ويترك
|
||||
لأداة التسخير التحدّث إلى بروتوكول خادم التطبيق الأصلي
|
||||
|
||||
مكوّن Codex الإضافي ذو طبيعة إضافية. تظل مراجع `openai/gpt-*` العادية
|
||||
مراجع لموفر OpenAI وتستمر في استخدام مسار موفر OpenClaw العادي. اختر `codex/gpt-*`
|
||||
عندما تريد مصادقة مُدارة بواسطة Codex، واكتشاف نماذج Codex، وسلاسل تنفيذ أصلية،
|
||||
Plugin Codex إضافية. تظل مراجع `openai/gpt-*` العادية مراجع لموفّر OpenAI
|
||||
وتستمر في استخدام مسار موفّر OpenClaw المعتاد. اختر `codex/gpt-*`
|
||||
عندما تريد مصادقة مُدارة من Codex، واكتشاف نماذج Codex، وسلاسل محادثة أصلية،
|
||||
وتنفيذ خادم تطبيق Codex. يمكن لـ `/model` التبديل بين نماذج Codex التي يعيدها
|
||||
خادم تطبيق Codex من دون الحاجة إلى بيانات اعتماد موفر OpenAI.
|
||||
خادم تطبيق Codex من دون الحاجة إلى بيانات اعتماد موفّر OpenAI.
|
||||
|
||||
لإعدادات المشغّل، وأمثلة بادئات النماذج، وإعدادات Codex فقط، راجع
|
||||
[Codex Harness](/ar/plugins/codex-harness).
|
||||
لإعداد المشغّل، وأمثلة بادئات النماذج، وإعدادات Codex فقط، راجع
|
||||
[أداة تسخير Codex](/ar/plugins/codex-harness).
|
||||
|
||||
يتطلب OpenClaw إصدار Codex app-server `0.118.0` أو أحدث. يتحقق مكوّن Codex
|
||||
الإضافي من مصافحة التهيئة مع app-server ويحظر الخوادم الأقدم أو غير المرقمة
|
||||
حتى لا يعمل OpenClaw إلا على سطح البروتوكول الذي جرى اختباره معه.
|
||||
يتطلب OpenClaw إصدار Codex app-server `0.118.0` أو أحدث. تتحقق Plugin Codex
|
||||
من مصافحة تهيئة خادم التطبيق وتمنع الخوادم الأقدم أو غير ذات الإصدار
|
||||
بحيث يعمل OpenClaw فقط مع سطح البروتوكول الذي تم اختباره معه.
|
||||
|
||||
### وضع Codex harness الأصلي
|
||||
### وضع أداة تسخير Codex الأصلية
|
||||
|
||||
يُعد `codex` harness المضمّن وضع Codex الأصلي لدورات وكلاء OpenClaw المضمّنة.
|
||||
فعّل مكوّن `codex` الإضافي المضمّن أولًا، وأدرج `codex` في
|
||||
`plugins.allow` إذا كان إعدادك يستخدم قائمة سماح مقيّدة. وهو يختلف عن
|
||||
`openai-codex/*`:
|
||||
أداة التسخير المضمّنة `codex` هي وضع Codex الأصلي لدورات وكيل OpenClaw
|
||||
المضمّنة. فعّل Plugin `codex` المضمّنة أولًا، وأدرج `codex` ضمن
|
||||
`plugins.allow` إذا كان إعدادك يستخدم قائمة سماح مقيّدة. وهي تختلف
|
||||
عن `openai-codex/*`:
|
||||
|
||||
- يستخدم `openai-codex/*` OAuth الخاص بـ ChatGPT/Codex عبر مسار موفر OpenClaw العادي.
|
||||
- يستخدم `codex/*` موفر Codex المضمّن ويوجّه الدورة عبر Codex
|
||||
- يستخدم `openai-codex/*` OAuth الخاص بـ ChatGPT/Codex عبر مسار موفّر OpenClaw
|
||||
المعتاد.
|
||||
- يستخدم `codex/*` موفّر Codex المضمّن ويوجّه الدورة عبر Codex
|
||||
app-server.
|
||||
|
||||
عند تشغيل هذا الوضع، يملك Codex معرّف سلسلة التنفيذ الأصلية، وسلوك الاستئناف،
|
||||
والضغط، وتنفيذ app-server. ولا يزال OpenClaw يملك قناة الدردشة،
|
||||
ومرآة النص الظاهرة، وسياسة الأدوات، والموافقات، وتسليم الوسائط، واختيار
|
||||
الجلسة. استخدم `embeddedHarness.runtime: "codex"` مع
|
||||
`embeddedHarness.fallback: "none"` عندما تحتاج إلى إثبات أن مسار Codex
|
||||
app-server مستخدم وأن الرجوع إلى PI لا يخفي harness أصليًا معطّلًا.
|
||||
عند تشغيل هذا الوضع، يمتلك Codex معرّف سلسلة المحادثة الأصلي، وسلوك
|
||||
الاستئناف، وCompaction، وتنفيذ خادم التطبيق. ولا يزال OpenClaw يمتلك قناة
|
||||
الدردشة، ومرآة النص الظاهرة، وسياسة الأدوات، وعمليات الموافقة، وتسليم الوسائط،
|
||||
واختيار الجلسة. استخدم `embeddedHarness.runtime: "codex"` مع
|
||||
`embeddedHarness.fallback: "none"` عندما تحتاج إلى إثبات أن
|
||||
مسار Codex app-server فقط هو الذي يمكنه امتلاك التشغيل. هذا الإعداد
|
||||
ليس سوى حاجز اختيار: فأعطال Codex app-server تتسبب بالفعل في الفشل مباشرة
|
||||
بدلًا من إعادة المحاولة عبر PI.
|
||||
|
||||
## تعطيل الرجوع إلى PI
|
||||
|
||||
بشكل افتراضي، يشغّل OpenClaw الوكلاء المضمّنين مع تعيين `agents.defaults.embeddedHarness`
|
||||
إلى `{ runtime: "auto", fallback: "pi" }`. في وضع `auto`، يمكن لـ harnesses
|
||||
المسجّلة من المكوّنات الإضافية المطالبة بزوج موفر/نموذج. إذا لم يطابق أي منها،
|
||||
أو إذا فشل harness لمكوّن إضافي تم اختياره تلقائيًا قبل إنتاج أي مخرجات،
|
||||
يرجع OpenClaw إلى PI.
|
||||
افتراضيًا، يشغّل OpenClaw الوكلاء المضمّنين مع تعيين `agents.defaults.embeddedHarness`
|
||||
إلى `{ runtime: "auto", fallback: "pi" }`. في وضع `auto`، يمكن لأدوات تسخير
|
||||
Plugins المسجّلة امتلاك زوج موفّر/نموذج. وإذا لم يتطابق أي منها، يرجع OpenClaw إلى PI.
|
||||
|
||||
عيّن `fallback: "none"` عندما تحتاج إلى إثبات أن harness الخاص بالمكوّن الإضافي
|
||||
هو وقت التشغيل الوحيد الجاري استخدامه. يؤدي ذلك إلى تعطيل الرجوع التلقائي إلى PI؛
|
||||
لكنه لا يمنع `runtime: "pi"` الصريح أو `OPENCLAW_AGENT_RUNTIME=pi`.
|
||||
عيّن `fallback: "none"` عندما تحتاج إلى أن يفشل غياب اختيار أداة تسخير Plugin
|
||||
بدلًا من استخدام PI. أما أعطال أداة تسخير Plugin المختارة فتفشل بالفعل بشكل
|
||||
صارم. وهذا لا يمنع `runtime: "pi"` الصريح أو `OPENCLAW_AGENT_RUNTIME=pi`.
|
||||
|
||||
لتشغيلات مضمّنة خاصة بـ Codex:
|
||||
لتشغيلات مضمّنة تعتمد على Codex فقط:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -184,8 +188,8 @@ app-server مستخدم وأن الرجوع إلى PI لا يخفي harness أص
|
||||
}
|
||||
```
|
||||
|
||||
إذا كنت تريد أن تطالب أي harness مسجّل من المكوّنات الإضافية بالنماذج المطابقة ولكنك
|
||||
لا تريد أبدًا أن يرجع OpenClaw بصمت إلى PI، فأبقِ `runtime: "auto"` وعطّل
|
||||
إذا كنت تريد أن تمتلك أي أداة تسخير Plugin مسجّلة النماذج المطابقة لكنك لا تريد
|
||||
أن يرجع OpenClaw بصمت إلى PI مطلقًا، فأبقِ `runtime: "auto"` وعطّل
|
||||
الرجوع:
|
||||
|
||||
```json
|
||||
@ -226,8 +230,8 @@ app-server مستخدم وأن الرجوع إلى PI لا يخفي harness أص
|
||||
}
|
||||
```
|
||||
|
||||
لا يزال `OPENCLAW_AGENT_RUNTIME` يتجاوز وقت التشغيل المكوَّن. استخدم
|
||||
`OPENCLAW_AGENT_HARNESS_FALLBACK=none` لتعطيل الرجوع إلى PI من
|
||||
لا يزال `OPENCLAW_AGENT_RUNTIME` يتجاوز وقت التشغيل المضبوط في الإعداد.
|
||||
استخدم `OPENCLAW_AGENT_HARNESS_FALLBACK=none` لتعطيل الرجوع إلى PI من
|
||||
البيئة.
|
||||
|
||||
```bash
|
||||
@ -236,53 +240,54 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \
|
||||
openclaw gateway run
|
||||
```
|
||||
|
||||
مع تعطيل الرجوع، تفشل الجلسة مبكرًا عندما لا يكون harness المطلوب
|
||||
مسجّلًا، أو لا يدعم الموفر/النموذج الذي تم تحديده، أو يفشل قبل
|
||||
إنتاج آثار جانبية للدورة. وهذا مقصود لعمليات النشر الخاصة بـ Codex فقط
|
||||
ولاختبارات live التي يجب أن تثبت أن مسار Codex app-server قيد الاستخدام فعلًا.
|
||||
عند تعطيل الرجوع، تفشل الجلسة مبكرًا عندما لا تكون أداة التسخير المطلوبة
|
||||
مسجّلة، أو لا تدعم الموفّر/النموذج الذي تم تحديده، أو تفشل قبل
|
||||
إنتاج آثار جانبية للدورة. وهذا مقصود لبيئات النشر التي تعتمد على Codex فقط
|
||||
وللاختبارات الحية التي يجب أن تثبت أن مسار Codex app-server مستخدم بالفعل.
|
||||
|
||||
يتحكم هذا الإعداد فقط في embedded agent harness. ولا يعطّل
|
||||
توجيه النماذج الخاص بالموفر للصور أو الفيديو أو الموسيقى أو TTS أو PDF أو غيرها.
|
||||
يتحكم هذا الإعداد فقط في أداة تسخير الوكيل المضمّنة. وهو لا يعطّل
|
||||
توجيه النماذج الخاص بالموفّر للصور أو الفيديو أو الموسيقى أو TTS أو PDF
|
||||
أو غير ذلك.
|
||||
|
||||
## الجلسات الأصلية ومرآة النص
|
||||
|
||||
قد يحتفظ harness بمعرّف جلسة أصلي، أو معرّف سلسلة تنفيذ، أو رمز استئناف
|
||||
على جانب daemon. أبقِ هذا الارتباط مقترنًا صراحةً بجلسة OpenClaw، واستمر
|
||||
قد تحتفظ أداة التسخير بمعرّف جلسة أصلي، أو معرّف سلسلة محادثة، أو رمز استئناف
|
||||
على جانب الخدمة. احتفظ بهذا الارتباط مرتبطًا صراحة بجلسة OpenClaw، واستمر
|
||||
في عكس مخرجات المساعد/الأداة الظاهرة للمستخدم إلى نص OpenClaw.
|
||||
|
||||
يبقى نص OpenClaw طبقة التوافق من أجل:
|
||||
يظل نص OpenClaw طبقة التوافق من أجل:
|
||||
|
||||
- سجل الجلسة الظاهر في القناة
|
||||
- البحث في النص وفهرسته
|
||||
- العودة إلى harness المدمج PI في دورة لاحقة
|
||||
- السلوك العام لـ `/new` و`/reset` وحذف الجلسة
|
||||
- العودة إلى أداة تسخير PI المضمّنة في دورة لاحقة
|
||||
- سلوك `/new` و`/reset` وحذف الجلسة العام
|
||||
|
||||
إذا كان harness يخزن ارتباطًا جانبيًا، فنفّذ `reset(...)` حتى يتمكن OpenClaw من
|
||||
مسحه عند إعادة تعيين جلسة OpenClaw المالكة له.
|
||||
إذا كانت أداة التسخير تخزّن ارتباطًا جانبيًا، فنفّذ `reset(...)` بحيث يتمكن OpenClaw
|
||||
من مسحه عند إعادة تعيين جلسة OpenClaw المالكة.
|
||||
|
||||
## نتائج الأدوات والوسائط
|
||||
|
||||
يبني core قائمة أدوات OpenClaw ويمررها إلى المحاولة المُحضّرة.
|
||||
عندما ينفّذ harness استدعاء أداة ديناميكيًا، أعد نتيجة الأداة عبر
|
||||
صيغة نتيجة harness بدلًا من إرسال وسائط القناة بنفسك.
|
||||
ينشئ الأساس قائمة أدوات OpenClaw ويمررها إلى المحاولة المُحضّرة.
|
||||
عندما تنفّذ أداة تسخير استدعاء أداة ديناميكيًا، فأعد نتيجة الأداة عبر
|
||||
شكل نتيجة أداة التسخير بدلًا من إرسال وسائط القناة بنفسك.
|
||||
|
||||
يحافظ ذلك على مخرجات النص والصورة والفيديو والموسيقى وTTS والموافقة وأدوات المراسلة
|
||||
ضمن مسار التسليم نفسه كما في التشغيلات المدعومة بـ PI.
|
||||
يحافظ ذلك على النص، والصورة، والفيديو، والموسيقى، وTTS، والموافقة، ومخرجات
|
||||
أدوات المراسلة على مسار التسليم نفسه مثل التشغيلات المدعومة بـ PI.
|
||||
|
||||
## القيود الحالية
|
||||
|
||||
- مسار الاستيراد العام عام، لكن بعض الأسماء المستعارة لأنواع المحاولة/النتيجة لا تزال
|
||||
تحمل أسماء `Pi` من أجل التوافق.
|
||||
- تثبيت harnesses الخارجية تجريبي. فضّل مكوّنات provider الإضافية
|
||||
إلى أن تحتاج إلى بيئة جلسات أصلية.
|
||||
- التبديل بين harnesses مدعوم عبر الدورات. لا تبدّل بين harnesses في
|
||||
منتصف الدورة بعد بدء الأدوات الأصلية أو الموافقات أو نص المساعد أو إرسال
|
||||
الرسائل.
|
||||
- مسار الاستيراد العام عامّ، لكن بعض الأسماء المستعارة لأنواع المحاولة/النتيجة لا تزال
|
||||
تحمل أسماء `Pi` حفاظًا على التوافق.
|
||||
- تثبيت أدوات التسخير التابعة لجهات خارجية تجريبي. فضّل Plugins الموفّرين
|
||||
إلى أن تحتاج إلى وقت تشغيل جلسة أصلي.
|
||||
- التبديل بين أدوات التسخير مدعوم عبر الدورات. لا تبدّل أدوات التسخير في
|
||||
منتصف دورة بعد بدء الأدوات الأصلية، أو الموافقات، أو نص المساعد، أو عمليات
|
||||
إرسال الرسائل.
|
||||
|
||||
## ذو صلة
|
||||
|
||||
- [نظرة عامة على SDK](/ar/plugins/sdk-overview)
|
||||
- [مساعدات وقت التشغيل](/ar/plugins/sdk-runtime)
|
||||
- [مكوّنات Provider الإضافية](/ar/plugins/sdk-provider-plugins)
|
||||
- [Codex Harness](/ar/plugins/codex-harness)
|
||||
- [موفرو النماذج](/ar/concepts/model-providers)
|
||||
- [Plugins الموفّرين](/ar/plugins/sdk-provider-plugins)
|
||||
- [أداة تسخير Codex](/ar/plugins/codex-harness)
|
||||
- [موفّرو النماذج](/ar/concepts/model-providers)
|
||||
|
||||
@ -1,114 +1,120 @@
|
||||
---
|
||||
read_when:
|
||||
- أنت تبني Plugin قناة مراسلة جديدة
|
||||
- أنت تبني Plugin جديدًا لقناة مراسلة
|
||||
- تريد ربط OpenClaw بمنصة مراسلة
|
||||
- تحتاج إلى فهم سطح المهايئ ChannelPlugin
|
||||
- تحتاج إلى فهم واجهة المهايئ `ChannelPlugin`
|
||||
sidebarTitle: Channel Plugins
|
||||
summary: دليل خطوة بخطوة لبناء Plugin قناة مراسلة لـ OpenClaw
|
||||
summary: دليل خطوة بخطوة لإنشاء Plugin لقناة مراسلة لـ OpenClaw
|
||||
title: بناء Plugins القنوات
|
||||
x-i18n:
|
||||
generated_at: "2026-04-22T04:25:25Z"
|
||||
generated_at: "2026-04-22T07:18:18Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: f08bf785cd2e16ed6ce0317f4fd55c9eccecf7476d84148ad47e7be516dd71fb
|
||||
source_hash: e67d8c4be8cc4a312e5480545497b139c27bed828304de251e6258a3630dd9b5
|
||||
source_path: plugins/sdk-channel-plugins.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# بناء Plugins القنوات
|
||||
|
||||
يرشدك هذا الدليل خلال بناء Plugin قناة يربط OpenClaw بمنصة
|
||||
مراسلة. وبنهاية هذا الدليل سيكون لديك قناة عاملة مع أمان الرسائل المباشرة،
|
||||
يرشدك هذا الدليل خلال بناء Plugin لقناة يربط OpenClaw بمنصة مراسلة.
|
||||
وبحلول النهاية سيكون لديك قناة عاملة تتضمن أمان الرسائل المباشرة،
|
||||
والاقتران، وتسلسل الردود، والمراسلة الصادرة.
|
||||
|
||||
<Info>
|
||||
إذا لم تكن قد بنيت أي Plugin لـ OpenClaw من قبل، فاقرأ أولًا
|
||||
[البدء](/ar/plugins/building-plugins) لمعرفة بنية الحزمة الأساسية
|
||||
وإعداد البيان.
|
||||
إذا لم تكن قد بنيت أي Plugin لـ OpenClaw من قبل، فاقرأ
|
||||
[البدء](/ar/plugins/building-plugins) أولًا للتعرف على بنية
|
||||
الحزمة الأساسية وإعداد manifest.
|
||||
</Info>
|
||||
|
||||
## كيف تعمل Plugins القنوات
|
||||
|
||||
لا تحتاج Plugins القنوات إلى أدوات send/edit/react خاصة بها. يحتفظ OpenClaw
|
||||
بأداة `message` مشتركة واحدة في Core. ويتولى Plugin الخاص بك ما يلي:
|
||||
بأداة `message` واحدة مشتركة في النواة. ويتولى Plugin الخاص بك ما يلي:
|
||||
|
||||
- **التكوين** — حل الحسابات ومعالج الإعداد
|
||||
- **الإعداد** — حلّ الحساب ومعالج الإعداد
|
||||
- **الأمان** — سياسة الرسائل المباشرة وقوائم السماح
|
||||
- **الاقتران** — تدفق الموافقة على الرسائل المباشرة
|
||||
- **قواعد الجلسة** — كيفية ربط معرّفات المحادثات الخاصة بالمزوّد بالمحادثات الأساسية، ومعرّفات السلاسل، وعمليات الرجوع إلى الأصل
|
||||
- **الصادر** — إرسال النصوص والوسائط والاستطلاعات إلى المنصة
|
||||
- **التسلسل** — كيفية تسلسل الردود
|
||||
- **قواعد الجلسة** — كيفية ربط معرّفات المحادثات الخاصة بالموفر بالدردشات الأساسية ومعرّفات السلاسل وبدائل الأصل
|
||||
- **الإرسال الصادر** — إرسال النصوص والوسائط والاستطلاعات إلى المنصة
|
||||
- **التسلسل** — كيفية تنظيم الردود ضمن سلاسل
|
||||
- **كتابة Heartbeat** — إشارات الكتابة/الانشغال الاختيارية لأهداف تسليم Heartbeat
|
||||
|
||||
يمتلك Core أداة الرسائل المشتركة، وتوصيل المطالبات، وشكل مفتاح الجلسة الخارجي،
|
||||
وسجل `:thread:` العام، والتوزيع.
|
||||
تتولى النواة أداة الرسائل المشتركة، وربط المطالبات، والشكل الخارجي لمفتاح الجلسة،
|
||||
وتتبّع `:thread:` العام، والتوزيع.
|
||||
|
||||
إذا كانت قناتك تضيف معلمات لأداة الرسائل تحمل مصادر وسائط، فاكشف أسماء
|
||||
هذه المعلمات عبر `describeMessageTool(...).mediaSourceParams`. يستخدم Core هذه
|
||||
القائمة الصريحة لتطبيع مسارات sandbox ولسياسة الوصول إلى الوسائط الصادرة،
|
||||
بحيث لا تحتاج Plugins إلى حالات خاصة في Core المشتركة لمعلمات
|
||||
الصورة الرمزية أو المرفقات أو صور الغلاف الخاصة بالمزوّد.
|
||||
ويُفضَّل إرجاع خريطة مفهرسة بالمفاتيح الإجرائية مثل
|
||||
`{ "set-profile": ["avatarUrl", "avatarPath"] }` حتى لا ترث الإجراءات غير المرتبطة
|
||||
معلمات الوسائط التابعة لإجراء آخر. وتظل المصفوفة المسطحة تعمل للمعلمات
|
||||
المشتركة عمدًا بين كل الإجراءات المكشوفة.
|
||||
إذا كانت قناتك تدعم مؤشرات الكتابة خارج الردود الواردة، فكشف
|
||||
`heartbeat.sendTyping(...)` على Plugin القناة. تستدعيه النواة مع
|
||||
هدف تسليم Heartbeat المحسوم قبل بدء تشغيل نموذج Heartbeat وتستخدم
|
||||
دورة الحياة المشتركة للإبقاء على الكتابة/تنظيفها. أضف `heartbeat.clearTyping(...)`
|
||||
عندما تحتاج المنصة إلى إشارة توقف صريحة.
|
||||
|
||||
إذا كانت منصتك تخزن نطاقًا إضافيًا داخل معرّفات المحادثات، فأبقِ هذا التحليل
|
||||
داخل Plugin باستخدام `messaging.resolveSessionConversation(...)`. فهذا هو الخطاف
|
||||
المرجعي لربط `rawId` بمعرّف المحادثة الأساسي، ومعرّف السلسلة الاختياري،
|
||||
و`baseConversationId` الصريح، وأي `parentConversationCandidates`.
|
||||
وعندما تُرجع `parentConversationCandidates`، فأبقِ ترتيبها من
|
||||
الأصل الأضيق إلى المحادثة الأساسية/الأوسع.
|
||||
إذا كانت قناتك تضيف معاملات message tool تحمل مصادر وسائط، فكشف أسماء
|
||||
هذه المعاملات عبر `describeMessageTool(...).mediaSourceParams`. تستخدم النواة
|
||||
هذه القائمة الصريحة لتطبيع مسارات sandbox ولسياسة الوصول إلى الوسائط الصادرة،
|
||||
بحيث لا تحتاج Plugins إلى حالات خاصة في النواة المشتركة لمعاملات الصور
|
||||
الرمزية أو المرفقات أو صور الغلاف الخاصة بموفر معين.
|
||||
يُفضّل إرجاع خريطة مفاتيحها هي الإجراءات مثل
|
||||
`{ "set-profile": ["avatarUrl", "avatarPath"] }`
|
||||
حتى لا ترث الإجراءات غير المرتبطة معاملات الوسائط الخاصة بإجراء آخر.
|
||||
ولا تزال المصفوفة المسطحة تعمل للمعاملات التي يُقصد مشاركتها عمدًا بين
|
||||
كل إجراء مكشوف.
|
||||
|
||||
يمكن أيضًا للPlugins المضمّنة التي تحتاج إلى التحليل نفسه قبل إقلاع سجل
|
||||
القنوات أن تكشف ملف `session-key-api.ts` على المستوى الأعلى مع
|
||||
تصدير مطابق لـ `resolveSessionConversation(...)`.
|
||||
يستخدم Core هذا السطح الآمن للإقلاع فقط عندما لا يكون سجل Plugins وقت التشغيل
|
||||
متاحًا بعد.
|
||||
إذا كانت منصتك تخزن نطاقًا إضافيًا داخل معرّفات المحادثة، فأبقِ هذا التحليل
|
||||
داخل Plugin عبر `messaging.resolveSessionConversation(...)`. فهذه هي
|
||||
الخطاف القياسي لربط `rawId` بمعرّف المحادثة الأساسي ومعرّف السلسلة الاختياري
|
||||
و`baseConversationId` الصريح وأي `parentConversationCandidates`.
|
||||
وعند إرجاع `parentConversationCandidates`، أبقِ ترتيبها من الأصل الأضيق
|
||||
إلى المحادثة الأوسع/الأساسية.
|
||||
|
||||
يبقى `messaging.resolveParentConversationCandidates(...)` متاحًا كرجوع
|
||||
توافقي قديم عندما يحتاج Plugin فقط إلى عمليات رجوع إلى الأصل فوق
|
||||
المعرّف الخام/العام. وإذا وُجد الخطافان معًا، يستخدم Core
|
||||
`resolveSessionConversation(...).parentConversationCandidates` أولًا ثم
|
||||
لا يعود إلى `resolveParentConversationCandidates(...)` إلا عندما يحذفها
|
||||
الخطاف المرجعي.
|
||||
يمكن أيضًا للـ Plugins المضمّنة التي تحتاج إلى التحليل نفسه قبل إقلاع
|
||||
سجل القنوات أن تكشف ملف `session-key-api.ts` على المستوى الأعلى مع
|
||||
تصدير `resolveSessionConversation(...)` مطابق. تستخدم النواة هذه الواجهة
|
||||
الآمنة لمرحلة الإقلاع فقط عندما لا يكون سجل Plugins وقت التشغيل متاحًا بعد.
|
||||
|
||||
## الموافقات وإمكانات القناة
|
||||
يبقى `messaging.resolveParentConversationCandidates(...)` متاحًا كبديل
|
||||
توافقي قديم عندما يحتاج Plugin فقط إلى بدائل الأصل فوق المعرف العام/الخام.
|
||||
إذا وُجد الخطافان معًا، تستخدم النواة
|
||||
`resolveSessionConversation(...).parentConversationCandidates` أولًا ولا
|
||||
تعود إلى `resolveParentConversationCandidates(...)` إلا إذا أغفل الخطاف
|
||||
القياسي هذه القيم.
|
||||
|
||||
معظم Plugins القنوات لا تحتاج إلى كود خاص بالموافقات.
|
||||
## الموافقات وقدرات القناة
|
||||
|
||||
- يمتلك Core أمر `/approve` داخل المحادثة نفسها، وحمولات أزرار الموافقة المشتركة، وتسليم الرجوع الاحتياطي العام.
|
||||
- فضّل كائن `approvalCapability` واحدًا على Plugin القناة عندما تحتاج القناة إلى سلوك خاص بالموافقة.
|
||||
- تمت إزالة `ChannelPlugin.approvals`. ضع حقائق التسليم/الواجهة الأصلية/العرض/المصادقة الخاصة بالموافقة في `approvalCapability`.
|
||||
- `plugin.auth` مخصص لتسجيل الدخول/الخروج فقط؛ ولم يعد Core يقرأ خطافات مصادقة الموافقة من ذلك الكائن.
|
||||
- يشكل `approvalCapability.authorizeActorAction` و`approvalCapability.getActionAvailabilityState` طبقة مصادقة الموافقة المرجعية.
|
||||
- استخدم `approvalCapability.getActionAvailabilityState` لتوفر مصادقة الموافقة داخل المحادثة نفسها.
|
||||
- إذا كانت قناتك تكشف موافقات تنفيذ أصلية، فاستخدم `approvalCapability.getExecInitiatingSurfaceState` لحالة السطح البادئ/العميل الأصلي عندما تختلف عن مصادقة الموافقة داخل المحادثة نفسها. يستخدم Core هذا الخطاف الخاص بالتنفيذ للتمييز بين `enabled` و`disabled`، وتحديد ما إذا كانت القناة البادئة تدعم موافقات التنفيذ الأصلية، وإدراج القناة في إرشادات الرجوع الاحتياطي للعميل الأصلي. ويملأ `createApproverRestrictedNativeApprovalCapability(...)` هذا في الحالة الشائعة.
|
||||
- استخدم `outbound.shouldSuppressLocalPayloadPrompt` أو `outbound.beforeDeliverPayload` لسلوك دورة حياة الحمولة الخاص بالقناة مثل إخفاء مطالبات الموافقة المحلية المكررة أو إرسال مؤشرات الكتابة قبل التسليم.
|
||||
- استخدم `approvalCapability.delivery` فقط لتوجيه الموافقات الأصلية أو منع الرجوع الاحتياطي.
|
||||
- استخدم `approvalCapability.nativeRuntime` للحقائق الأصلية للموافقات التي تملكها القناة. وأبقِه كسولًا على نقاط دخول القنوات السريعة باستخدام `createLazyChannelApprovalNativeRuntimeAdapter(...)`، الذي يمكنه استيراد وحدة وقت التشغيل عند الطلب مع السماح لـ Core بتجميع دورة حياة الموافقة.
|
||||
- استخدم `approvalCapability.render` فقط عندما تحتاج القناة فعلًا إلى حمولات موافقة مخصصة بدلًا من العارِض المشترك.
|
||||
- استخدم `approvalCapability.describeExecApprovalSetup` عندما تريد القناة أن يشرح رد المسار المعطل مفاتيح التكوين الدقيقة المطلوبة لتفعيل موافقات التنفيذ الأصلية. يتلقى الخطاف `{ channel, channelLabel, accountId }`؛ ويجب على القنوات ذات الحسابات المسماة عرض مسارات بنطاق الحساب مثل `channels.<channel>.accounts.<id>.execApprovals.*` بدلًا من الإعدادات الافتراضية العليا.
|
||||
- إذا كانت القناة تستطيع استنتاج هويات مستقرة شبيهة بالمالكين في الرسائل المباشرة من التكوين القائم، فاستخدم `createResolvedApproverActionAuthAdapter` من `openclaw/plugin-sdk/approval-runtime` لتقييد `/approve` داخل المحادثة نفسها من دون إضافة منطق خاص بالموافقة في Core.
|
||||
- إذا كانت القناة تحتاج إلى تسليم موافقة أصلية، فاحرص على إبقاء كود القناة مركزًا على تطبيع الهدف وحقائق النقل/العرض. استخدم `createChannelExecApprovalProfile` و`createChannelNativeOriginTargetResolver` و`createChannelApproverDmTargetResolver` و`createApproverRestrictedNativeApprovalCapability` من `openclaw/plugin-sdk/approval-runtime`. ضع حقائق القناة الخاصة خلف `approvalCapability.nativeRuntime`، ويفضل عبر `createChannelApprovalNativeRuntimeAdapter(...)` أو `createLazyChannelApprovalNativeRuntimeAdapter(...)`، حتى يتمكن Core من تجميع المعالج وامتلاك تصفية الطلبات، والتوجيه، وإزالة التكرار، وانتهاء الصلاحية، واشتراك Gateway، وإشعارات التوجيه إلى مكان آخر. وقد قُسِّم `nativeRuntime` إلى طبقات أصغر:
|
||||
- `availability` — ما إذا كان الحساب مُكوَّنًا وما إذا كان ينبغي التعامل مع الطلب
|
||||
- `presentation` — ربط نموذج عرض الموافقة المشترك إلى حمولات أصلية معلقة/محلولة/منتهية أو إجراءات نهائية
|
||||
- `transport` — إعداد الأهداف بالإضافة إلى إرسال/تحديث/حذف رسائل الموافقة الأصلية
|
||||
- `interactions` — خطافات اختيارية للربط/فك الربط/مسح الإجراءات للأزرار أو التفاعلات الأصلية
|
||||
لا تحتاج معظم Plugins القنوات إلى شيفرة خاصة بالموافقة.
|
||||
|
||||
- تتولى النواة `/approve` داخل الدردشة نفسها، وحمولات أزرار الموافقة المشتركة، وتسليم البدائل العام.
|
||||
- يُفضّل استخدام كائن `approvalCapability` واحد على Plugin القناة عندما تحتاج القناة إلى سلوك خاص بالموافقة.
|
||||
- تمت إزالة `ChannelPlugin.approvals`. ضع حقائق تسليم/أصلي/عرض/مصادقة الموافقة على `approvalCapability`.
|
||||
- يختص `plugin.auth` بتسجيل الدخول/الخروج فقط؛ ولم تعد النواة تقرأ خطافات مصادقة الموافقة من هذا الكائن.
|
||||
- يُعد `approvalCapability.authorizeActorAction` و`approvalCapability.getActionAvailabilityState` الواجهة القياسية لمصادقة الموافقة.
|
||||
- استخدم `approvalCapability.getActionAvailabilityState` لتوافر مصادقة الموافقة داخل الدردشة نفسها.
|
||||
- إذا كانت قناتك تكشف موافقات تنفيذ أصلية، فاستخدم `approvalCapability.getExecInitiatingSurfaceState` لحالة سطح البدء/العميل الأصلي عندما تختلف عن مصادقة الموافقة داخل الدردشة نفسها. تستخدم النواة هذا الخطاف الخاص بالتنفيذ للتمييز بين `enabled` و`disabled`، وتحديد ما إذا كانت قناة البدء تدعم موافقات التنفيذ الأصلية، وإدراج القناة في إرشادات بدائل العميل الأصلي. يملأ `createApproverRestrictedNativeApprovalCapability(...)` هذا الجزء للحالة الشائعة.
|
||||
- استخدم `outbound.shouldSuppressLocalPayloadPrompt` أو `outbound.beforeDeliverPayload` لسلوك دورة حياة الحمولة الخاص بالقناة، مثل إخفاء مطالبات الموافقة المحلية المكررة أو إرسال مؤشرات الكتابة قبل التسليم.
|
||||
- استخدم `approvalCapability.delivery` فقط لتوجيه الموافقة الأصلية أو منع التسليم البديل.
|
||||
- استخدم `approvalCapability.nativeRuntime` للحقائق الأصلية الخاصة بالقناة المتعلقة بالموافقة. أبقه كسول التحميل على نقاط دخول القنوات الساخنة باستخدام `createLazyChannelApprovalNativeRuntimeAdapter(...)`، الذي يمكنه استيراد module وقت التشغيل عند الطلب مع السماح للنواة بتجميع دورة حياة الموافقة.
|
||||
- استخدم `approvalCapability.render` فقط عندما تحتاج القناة فعلًا إلى حمولات موافقة مخصصة بدلًا من العارض المشترك.
|
||||
- استخدم `approvalCapability.describeExecApprovalSetup` عندما تريد القناة أن يشرح رد مسار التعطيل مفاتيح الإعداد الدقيقة اللازمة لتمكين موافقات التنفيذ الأصلية. يتلقى الخطاف `{ channel, channelLabel, accountId }`؛ ويجب على القنوات ذات الحسابات المسماة عرض مسارات ضمن نطاق الحساب مثل `channels.<channel>.accounts.<id>.execApprovals.*` بدلًا من الإعدادات الافتراضية ذات المستوى الأعلى.
|
||||
- إذا كانت القناة تستطيع استنتاج هويات رسائل مباشرة مستقرة شبيهة بالمالك من الإعداد الحالي، فاستخدم `createResolvedApproverActionAuthAdapter` من `openclaw/plugin-sdk/approval-runtime` لتقييد `/approve` داخل الدردشة نفسها من دون إضافة منطق خاص بالموافقة إلى النواة.
|
||||
- إذا كانت القناة تحتاج إلى تسليم موافقة أصلية، فاحصر شيفرة القناة في تطبيع الهدف وحقائق النقل/العرض. استخدم `createChannelExecApprovalProfile` و`createChannelNativeOriginTargetResolver` و`createChannelApproverDmTargetResolver` و`createApproverRestrictedNativeApprovalCapability` من `openclaw/plugin-sdk/approval-runtime`. ضع الحقائق الخاصة بالقناة خلف `approvalCapability.nativeRuntime`، ويفضل عبر `createChannelApprovalNativeRuntimeAdapter(...)` أو `createLazyChannelApprovalNativeRuntimeAdapter(...)`، حتى تتمكن النواة من تجميع المعالج وامتلاك ترشيح الطلبات والتوجيه وإزالة التكرار والانتهاء والاشتراك في Gateway وإشعارات التوجيه إلى مكان آخر. ينقسم `nativeRuntime` إلى عدة واجهات أصغر:
|
||||
- `availability` — ما إذا كان الحساب مضبوطًا وما إذا كان يجب التعامل مع الطلب
|
||||
- `presentation` — ربط نموذج عرض الموافقة المشترك بحمولات أصلية معلقة/محلولة/منتهية أو إجراءات نهائية
|
||||
- `transport` — تحضير الأهداف إضافة إلى إرسال/تحديث/حذف رسائل الموافقة الأصلية
|
||||
- `interactions` — خطافات اختيارية لربط/فك ربط/مسح الإجراءات الخاصة بالأزرار أو التفاعلات الأصلية
|
||||
- `observe` — خطافات اختيارية لتشخيصات التسليم
|
||||
- إذا كانت القناة تحتاج إلى كائنات يملكها وقت التشغيل مثل عميل أو رمز أو تطبيق Bolt أو مستقبِل Webhook، فسجّلها عبر `openclaw/plugin-sdk/channel-runtime-context`. يتيح سجل سياق وقت التشغيل العام لـ Core إقلاع معالجات مدفوعة بالإمكانات من حالة بدء تشغيل القناة من دون إضافة غراء تغليف خاص بالموافقة.
|
||||
- لا تلجأ إلى `createChannelApprovalHandler` أو `createChannelNativeApprovalRuntime` منخفضي المستوى إلا عندما لا تكون طبقة الإمكانات التعبيرية كافية بعد.
|
||||
- يجب على قنوات الموافقات الأصلية تمرير كل من `accountId` و`approvalKind` عبر تلك المساعدات. فـ `accountId` يحافظ على سياسة الموافقة متعددة الحسابات ضمن نطاق حساب البوت الصحيح، و`approvalKind` يبقي سلوك موافقة التنفيذ مقابل Plugin متاحًا للقناة من دون فروع صلبة في Core.
|
||||
- يمتلك Core الآن أيضًا إشعارات إعادة توجيه الموافقات. يجب ألا ترسل Plugins القنوات رسائل متابعة خاصة بها من نوع "تم إرسال الموافقة إلى الرسائل المباشرة / قناة أخرى" من `createChannelNativeApprovalRuntime`؛ بل اكشف بدلًا من ذلك توجيه الأصل + الرسائل المباشرة للموافق عبر مساعدات إمكانات الموافقة المشتركة ودع Core يجمع عمليات التسليم الفعلية قبل نشر أي إشعار إلى الدردشة البادئة.
|
||||
- حافظ على نوع معرّف الموافقة المُسلَّم من البداية إلى النهاية. يجب ألا
|
||||
تخمّن العملاء الأصلية أو تعيد كتابة توجيه موافقة التنفيذ مقابل Plugin من حالة محلية خاصة بالقناة.
|
||||
- يمكن لأنواع مختلفة من الموافقات أن تكشف عمدًا عن أسطح أصلية مختلفة.
|
||||
من الأمثلة المضمّنة الحالية:
|
||||
- يبقي Slack توجيه الموافقات الأصلية متاحًا لكل من معرّفات التنفيذ وPlugin.
|
||||
- يحتفظ Matrix بالتوجيه الأصلي نفسه للرسائل المباشرة/القنوات وبواجهة التفاعلات نفسها لموافقات التنفيذ وPlugin، مع السماح في الوقت نفسه باختلاف المصادقة حسب نوع الموافقة.
|
||||
- لا يزال `createApproverRestrictedNativeApprovalAdapter` موجودًا كغلاف توافق، لكن ينبغي للكود الجديد تفضيل باني الإمكانات وكشف `approvalCapability` على Plugin.
|
||||
- إذا كانت القناة تحتاج إلى كائنات يملكها وقت التشغيل مثل عميل أو token أو تطبيق Bolt أو مستقبِل Webhook، فسجلها عبر `openclaw/plugin-sdk/channel-runtime-context`. يتيح سجل runtime-context العام للنواة إقلاع المعالجات المدفوعة بالقدرات من حالة بدء تشغيل القناة دون إضافة غلاف خاص بالموافقة.
|
||||
- انتقل إلى `createChannelApprovalHandler` أو `createChannelNativeApprovalRuntime` ذوي المستوى الأدنى فقط عندما لا تكون الواجهة المعتمدة على القدرات معبرة بما يكفي بعد.
|
||||
- يجب على قنوات الموافقة الأصلية تمرير كلٍّ من `accountId` و`approvalKind` عبر هذه المساعدات. يحافظ `accountId` على تقييد سياسة الموافقة متعددة الحسابات بالحساب الآلي الصحيح، ويحافظ `approvalKind` على إتاحة سلوك موافقة التنفيذ مقابل Plugin للقناة من دون فروع مبرمجة بشكل ثابت في النواة.
|
||||
- تتولى النواة الآن أيضًا إشعارات إعادة توجيه الموافقة. يجب ألا ترسل Plugins القنوات رسائل متابعة خاصة بها من نوع "تم إرسال الموافقة إلى الرسائل المباشرة / قناة أخرى" من `createChannelNativeApprovalRuntime`؛ بل عليها كشف توجيه صحيح لكل من الأصل + الرسائل المباشرة للموافق عبر مساعدات قدرة الموافقة المشتركة وترك النواة تجمع عمليات التسليم الفعلية قبل نشر أي إشعار إلى الدردشة التي بدأت الطلب.
|
||||
- حافظ على نوع معرّف الموافقة الذي تم تسليمه من البداية إلى النهاية. يجب ألا تقوم العملاء الأصلية بتخمين أو إعادة كتابة توجيه موافقة التنفيذ مقابل Plugin استنادًا إلى حالة محلية في القناة.
|
||||
- يمكن لأنواع الموافقة المختلفة أن تكشف عمدًا أسطحًا أصلية مختلفة.
|
||||
الأمثلة المضمّنة الحالية:
|
||||
- يحافظ Slack على إتاحة توجيه الموافقة الأصلية لكل من معرّفات التنفيذ وPlugin.
|
||||
- يحافظ Matrix على التوجيه الأصلي نفسه للرسائل المباشرة/القناة وتجربة التفاعلات لكل من موافقات التنفيذ وPlugin، مع الاستمرار في السماح باختلاف المصادقة حسب نوع الموافقة.
|
||||
- لا يزال `createApproverRestrictedNativeApprovalAdapter` موجودًا كغلاف توافقي، لكن يجب أن تفضّل الشيفرة الجديدة مُنشئ القدرة وأن تكشف `approvalCapability` على Plugin.
|
||||
|
||||
بالنسبة لنقاط دخول القنوات السريعة، فضّل المسارات الفرعية الأضيق لوقت التشغيل عندما تحتاج فقط
|
||||
إلى جزء واحد من هذه العائلة:
|
||||
بالنسبة إلى نقاط دخول القنوات الساخنة، فضّل المسارات الفرعية الأضيق لوقت التشغيل عندما
|
||||
تحتاج إلى جزء واحد فقط من هذه العائلة:
|
||||
|
||||
- `openclaw/plugin-sdk/approval-auth-runtime`
|
||||
- `openclaw/plugin-sdk/approval-client-runtime`
|
||||
@ -120,98 +126,105 @@ x-i18n:
|
||||
- `openclaw/plugin-sdk/approval-reply-runtime`
|
||||
- `openclaw/plugin-sdk/channel-runtime-context`
|
||||
|
||||
وبالمثل، فضّل `openclaw/plugin-sdk/setup-runtime`,
|
||||
و`openclaw/plugin-sdk/setup-adapter-runtime`,
|
||||
و`openclaw/plugin-sdk/reply-runtime`,
|
||||
و`openclaw/plugin-sdk/reply-dispatch-runtime`,
|
||||
وبالمثل، فضّل `openclaw/plugin-sdk/setup-runtime`،
|
||||
و`openclaw/plugin-sdk/setup-adapter-runtime`،
|
||||
و`openclaw/plugin-sdk/reply-runtime`،
|
||||
و`openclaw/plugin-sdk/reply-dispatch-runtime`،
|
||||
و`openclaw/plugin-sdk/reply-reference`، و
|
||||
`openclaw/plugin-sdk/reply-chunking` عندما لا تحتاج إلى سطح
|
||||
التجميع الأوسع.
|
||||
`openclaw/plugin-sdk/reply-chunking` عندما لا تحتاج إلى الواجهة
|
||||
الأوسع ذات المستوى الأعلى.
|
||||
|
||||
بالنسبة إلى الإعداد تحديدًا:
|
||||
وبالنسبة إلى الإعداد تحديدًا:
|
||||
|
||||
- يغطي `openclaw/plugin-sdk/setup-runtime` مساعدات الإعداد الآمنة وقت التشغيل:
|
||||
مهايئات تصحيح الإعداد الآمنة للاستيراد (`createPatchedAccountSetupAdapter`,
|
||||
و`createEnvPatchedAccountSetupAdapter`,
|
||||
و`createSetupInputPresenceValidator`)، ومخرجات ملاحظات البحث،
|
||||
و`promptResolvedAllowFrom`، و`splitSetupEntries`، وبناة
|
||||
setup-proxy المفوضة
|
||||
- يشكل `openclaw/plugin-sdk/setup-adapter-runtime` طبقة المهايئ الضيقة الواعية بالبيئة
|
||||
لـ `createEnvPatchedAccountSetupAdapter`
|
||||
- يغطي `openclaw/plugin-sdk/channel-setup` بناة الإعداد ذات التثبيت الاختياري
|
||||
- يغطي `openclaw/plugin-sdk/setup-runtime` مساعدات الإعداد الآمنة لوقت التشغيل:
|
||||
مهايئات ترقيع الإعداد الآمنة للاستيراد (`createPatchedAccountSetupAdapter`,
|
||||
`createEnvPatchedAccountSetupAdapter`,
|
||||
`createSetupInputPresenceValidator`)، ومخرجات
|
||||
ملاحظات البحث، و`promptResolvedAllowFrom`، و`splitSetupEntries`، وبناة
|
||||
setup-proxy المفوّضة
|
||||
- يُعد `openclaw/plugin-sdk/setup-adapter-runtime` الواجهة الضيقة الواعية بالبيئة
|
||||
الخاصة بـ `createEnvPatchedAccountSetupAdapter`
|
||||
- يغطي `openclaw/plugin-sdk/channel-setup` بُناة الإعداد ذي التثبيت الاختياري
|
||||
بالإضافة إلى بعض البدائيات الآمنة للإعداد:
|
||||
`createOptionalChannelSetupSurface` و`createOptionalChannelSetupAdapter`،
|
||||
`createOptionalChannelSetupSurface`، `createOptionalChannelSetupAdapter`،
|
||||
|
||||
إذا كانت قناتك تدعم إعدادًا أو مصادقة مدفوعين بمتغيرات البيئة، وكان يجب أن تعرف
|
||||
تدفقات الإقلاع/التكوين العامة أسماء متغيرات البيئة تلك قبل تحميل وقت التشغيل،
|
||||
فصرّح بها في بيان Plugin باستخدام `channelEnvVars`. وأبقِ `envVars` الخاصة بوقت تشغيل القناة أو الثوابت المحلية لنسخة المشغّل فقط.
|
||||
إذا كانت قناتك تدعم إعدادًا أو مصادقة مدفوعين بالبيئة وكان ينبغي لتدفقات
|
||||
البدء/الإعداد العامة معرفة أسماء متغيرات البيئة هذه قبل تحميل وقت التشغيل،
|
||||
فصرّح بها في manifest الخاص بـ Plugin باستخدام `channelEnvVars`.
|
||||
واحتفظ بـ `envVars` وقت تشغيل القناة أو الثوابت المحلية فقط للنصوص
|
||||
الموجهة للمشغّل.
|
||||
|
||||
إذا كان يمكن لقناتك أن تظهر في `status` أو `channels list` أو `channels status` أو في عمليات فحص SecretRef قبل بدء وقت تشغيل Plugin، فأضف `openclaw.setupEntry` في `package.json`. يجب أن تكون نقطة الدخول هذه آمنة للاستيراد في مسارات الأوامر للقراءة فقط، ويجب أن تعيد بيانات تعريف القناة، ومهايئ التكوين الآمن للإعداد، ومهايئ الحالة، وبيانات تعريف أهداف أسرار القناة اللازمة لتلك الملخصات. لا تبدأ عملاء أو مستمعين أو أزمنة تشغيل للنقل من نقطة دخول الإعداد.
|
||||
إذا كانت قناتك قد تظهر في `status` أو `channels list` أو `channels status` أو
|
||||
عمليات فحص SecretRef قبل بدء وقت تشغيل Plugin، فأضف `openclaw.setupEntry` في
|
||||
`package.json`. يجب أن تكون نقطة الدخول هذه آمنة للاستيراد في مسارات الأوامر
|
||||
للقراءة فقط، ويجب أن تعيد بيانات القناة الوصفية، ومهايئ الإعداد الآمن،
|
||||
ومهايئ الحالة، وبيانات هدف سر القناة اللازمة لهذه الملخصات. لا تبدأ
|
||||
العملاء أو المستمعين أو أوقات تشغيل النقل من نقطة دخول الإعداد.
|
||||
|
||||
`createOptionalChannelSetupWizard`، و`DEFAULT_ACCOUNT_ID`,
|
||||
`createOptionalChannelSetupWizard`، و`DEFAULT_ACCOUNT_ID`،
|
||||
و`createTopLevelChannelDmPolicy`، و`setSetupChannelEnabled`، و
|
||||
`splitSetupEntries`
|
||||
|
||||
- استخدم سطح `openclaw/plugin-sdk/setup` الأوسع فقط عندما تحتاج أيضًا إلى
|
||||
مساعدات الإعداد/التكوين المشتركة الأثقل مثل
|
||||
- استخدم الواجهة الأوسع `openclaw/plugin-sdk/setup` فقط عندما تحتاج أيضًا إلى
|
||||
مساعدات الإعداد/التهيئة المشتركة الأثقل مثل
|
||||
`moveSingleAccountChannelSectionToDefaultAccount(...)`
|
||||
|
||||
إذا كانت قناتك تريد فقط الإعلان عن "ثبّت هذا Plugin أولًا" في أسطح الإعداد،
|
||||
ففضّل `createOptionalChannelSetupSurface(...)`. يفشل المهايئ/المعالج الناتج
|
||||
بشكل مغلق في عمليات كتابة التكوين والإنهاء، ويعيد استخدام الرسالة نفسها
|
||||
المطلوبة للتثبيت عبر التحقق والإنهاء ونسخة رابط الوثائق.
|
||||
إذا كانت قناتك تريد فقط الإعلان عن "ثبّت هذا Plugin أولًا" في أسطح
|
||||
الإعداد، ففضّل `createOptionalChannelSetupSurface(...)`. إذ إن
|
||||
المهايئ/المعالج المُولَّدين يفشلان بشكل مغلق عند كتابة الإعدادات وعند
|
||||
الإتمام، ويعيدان استخدام رسالة الحاجة إلى التثبيت نفسها عبر التحقق
|
||||
والإتمام ونص رابط التوثيق.
|
||||
|
||||
وبالنسبة إلى المسارات السريعة الأخرى للقنوات، فضّل المساعدات الضيقة على الأسطح
|
||||
القديمة الأوسع:
|
||||
وبالنسبة إلى مسارات القنوات الساخنة الأخرى، فضّل المساعدات الضيقة بدلًا من
|
||||
الواجهات القديمة الأوسع:
|
||||
|
||||
- `openclaw/plugin-sdk/account-core`,
|
||||
و`openclaw/plugin-sdk/account-id`,
|
||||
- `openclaw/plugin-sdk/account-core`،
|
||||
و`openclaw/plugin-sdk/account-id`،
|
||||
و`openclaw/plugin-sdk/account-resolution`، و
|
||||
`openclaw/plugin-sdk/account-helpers` لتكوين الحسابات المتعددة
|
||||
والرجوع الاحتياطي إلى الحساب الافتراضي
|
||||
`openclaw/plugin-sdk/account-helpers` لإعدادات تعدد الحسابات
|
||||
والرجوع إلى الحساب الافتراضي
|
||||
- `openclaw/plugin-sdk/inbound-envelope` و
|
||||
`openclaw/plugin-sdk/inbound-reply-dispatch` لتوصيل المسار/المغلف الوارد
|
||||
`openclaw/plugin-sdk/inbound-reply-dispatch` لمسار/غلاف الوارد
|
||||
وربط التسجيل والتوزيع
|
||||
- `openclaw/plugin-sdk/messaging-targets` لتحليل/مطابقة الأهداف
|
||||
- `openclaw/plugin-sdk/messaging-targets` لتحليل الأهداف ومطابقتها
|
||||
- `openclaw/plugin-sdk/outbound-media` و
|
||||
`openclaw/plugin-sdk/outbound-runtime` لتحميل الوسائط بالإضافة إلى
|
||||
مفوّضي هوية/إرسال الصادر وتخطيط الحمولة
|
||||
`openclaw/plugin-sdk/outbound-runtime` لتحميل الوسائط إضافة إلى
|
||||
مفوضات الهوية/الإرسال الصادر وتخطيط الحمولة
|
||||
- `buildThreadAwareOutboundSessionRoute(...)` من
|
||||
`openclaw/plugin-sdk/channel-core` عندما يجب أن يحافظ مسار الإرسال الصادر على
|
||||
`replyToId`/`threadId` صريح أو يستعيد جلسة `:thread:` الحالية
|
||||
بعد أن يظل مفتاح الجلسة الأساسي مطابقًا. ويمكن لـ Plugins المزوّدات
|
||||
`openclaw/plugin-sdk/channel-core` عندما ينبغي للمسار الصادر الحفاظ على
|
||||
`replyToId`/`threadId` صريح أو استعادة جلسة `:thread:` الحالية
|
||||
بعد أن يظل مفتاح الجلسة الأساسي مطابقًا. ويمكن لـ Plugins الموفر
|
||||
تجاوز الأولوية وسلوك اللاحقة وتطبيع معرّف السلسلة عندما تكون لدى منصتها
|
||||
دلالات أصلية لتسليم السلاسل.
|
||||
- `openclaw/plugin-sdk/thread-bindings-runtime` لدورة حياة ربط السلاسل
|
||||
وتسجيل المهايئات
|
||||
- `openclaw/plugin-sdk/agent-media-payload` فقط عندما يظل تخطيط
|
||||
حقل حمولة الوكيل/الوسائط القديم مطلوبًا
|
||||
- `openclaw/plugin-sdk/telegram-command-config` لتطبيع أوامر Telegram
|
||||
المخصصة، والتحقق من التكرار/التعارض، وعقد تكوين أوامر مستقر في
|
||||
الرجوع الاحتياطي
|
||||
- `openclaw/plugin-sdk/agent-media-payload` فقط عندما يكون تخطيط حقل
|
||||
حمولة agent/media القديم لا يزال مطلوبًا
|
||||
- `openclaw/plugin-sdk/telegram-command-config` لتطبيع الأوامر المخصصة في Telegram،
|
||||
والتحقق من التكرار/التعارض، وعقد إعداد أوامر ثابت كبديل
|
||||
|
||||
يمكن لقنوات المصادقة فقط عادةً التوقف عند المسار الافتراضي: يتولى Core الموافقات وتكشف Plugin فقط عن إمكانات الصادر/المصادقة. ويجب على قنوات الموافقات الأصلية مثل Matrix وSlack وTelegram وناقلات الدردشة المخصصة استخدام المساعدات الأصلية المشتركة بدلًا من بناء دورة حياة الموافقة الخاصة بها.
|
||||
يمكن للقنوات التي تقتصر على المصادقة عادةً الاكتفاء بالمسار الافتراضي: تتولى النواة الموافقات ويكشف Plugin فقط عن قدرات الإرسال الصادر/المصادقة. أما قنوات الموافقة الأصلية مثل Matrix وSlack وTelegram ووسائط الدردشة المخصصة فيجب أن تستخدم المساعدات الأصلية المشتركة بدلًا من بناء دورة حياة الموافقة الخاصة بها.
|
||||
|
||||
## سياسة الإشارة الواردة
|
||||
|
||||
أبقِ التعامل مع الإشارة الواردة منقسمًا إلى طبقتين:
|
||||
أبقِ التعامل مع الإشارات الواردة مقسومًا إلى طبقتين:
|
||||
|
||||
- جمع الأدلة الذي تملكه Plugin
|
||||
- جمع الأدلة المملوك للـ Plugin
|
||||
- تقييم السياسة المشتركة
|
||||
|
||||
استخدم `openclaw/plugin-sdk/channel-mention-gating` لقرارات سياسة الإشارة.
|
||||
واستخدم `openclaw/plugin-sdk/channel-inbound` فقط عندما تحتاج إلى
|
||||
مجمّع مساعدات الوارد الأوسع.
|
||||
الواجهة الأوسع لمساعدات الوارد.
|
||||
|
||||
مناسب جيدًا للمنطق المحلي في Plugin:
|
||||
حالات مناسبة للمنطق المحلي في Plugin:
|
||||
|
||||
- كشف الرد على البوت
|
||||
- كشف الاقتباس من البوت
|
||||
- اكتشاف الرد على bot
|
||||
- اكتشاف الاقتباس من bot
|
||||
- التحقق من المشاركة في السلسلة
|
||||
- استثناءات رسائل الخدمة/النظام
|
||||
- الذاكرات المؤقتة الأصلية للمنصة المطلوبة لإثبات مشاركة البوت
|
||||
- استبعاد رسائل الخدمة/النظام
|
||||
- مخابئ أصلية خاصة بالمنصة لازمة لإثبات مشاركة bot
|
||||
|
||||
مناسب جيدًا للمساعد المشترك:
|
||||
حالات مناسبة للمساعد المشترك:
|
||||
|
||||
- `requireMention`
|
||||
- نتيجة الإشارة الصريحة
|
||||
@ -222,7 +235,7 @@ x-i18n:
|
||||
التدفق المفضّل:
|
||||
|
||||
1. احسب حقائق الإشارة المحلية.
|
||||
2. مرّر تلك الحقائق إلى `resolveInboundMentionDecision({ facts, policy })`.
|
||||
2. مرّر هذه الحقائق إلى `resolveInboundMentionDecision({ facts, policy })`.
|
||||
3. استخدم `decision.effectiveWasMentioned` و`decision.shouldBypassMention` و`decision.shouldSkip` في بوابة الوارد لديك.
|
||||
|
||||
```typescript
|
||||
@ -277,17 +290,17 @@ if (decision.shouldSkip) return;
|
||||
وقت تشغيل الوارد غير المرتبطة.
|
||||
|
||||
تبقى مساعدات `resolveMentionGating*` الأقدم على
|
||||
`openclaw/plugin-sdk/channel-inbound` كتصديرات توافق فقط. يجب على الكود الجديد
|
||||
استخدام `resolveInboundMentionDecision({ facts, policy })`.
|
||||
`openclaw/plugin-sdk/channel-inbound` كتصديرات توافقية فقط. ويجب أن تستخدم
|
||||
الشيفرة الجديدة `resolveInboundMentionDecision({ facts, policy })`.
|
||||
|
||||
## الشرح العملي
|
||||
|
||||
<Steps>
|
||||
<a id="step-1-package-and-manifest"></a>
|
||||
<Step title="الحزمة والبيان">
|
||||
أنشئ ملفات Plugin القياسية. إن الحقل `channel` في `package.json` هو
|
||||
ما يجعل هذا Plugin قناة. وللاطلاع على سطح بيانات تعريف الحزمة الكامل،
|
||||
راجع [إعداد Plugin والتكوين](/ar/plugins/sdk-setup#openclaw-channel):
|
||||
<Step title="الحزمة وmanifest">
|
||||
أنشئ ملفات Plugin القياسية. إن حقل `channel` في `package.json` هو
|
||||
ما يجعل هذا Plugin قناة. وللاطلاع على سطح بيانات الحزمة الوصفية الكامل،
|
||||
راجع [إعداد Plugin والتهيئة](/ar/plugins/sdk-setup#openclaw-channel):
|
||||
|
||||
<CodeGroup>
|
||||
```json package.json
|
||||
@ -301,7 +314,7 @@ if (decision.shouldSkip) return;
|
||||
"channel": {
|
||||
"id": "acme-chat",
|
||||
"label": "Acme Chat",
|
||||
"blurb": "ربط OpenClaw بـ Acme Chat."
|
||||
"blurb": "Connect OpenClaw to Acme Chat."
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -313,7 +326,7 @@ if (decision.shouldSkip) return;
|
||||
"kind": "channel",
|
||||
"channels": ["acme-chat"],
|
||||
"name": "Acme Chat",
|
||||
"description": "Plugin قناة Acme Chat",
|
||||
"description": "Acme Chat channel plugin",
|
||||
"configSchema": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
@ -336,9 +349,9 @@ if (decision.shouldSkip) return;
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="ابنِ كائن Plugin القناة">
|
||||
تحتوي الواجهة `ChannelPlugin` على العديد من أسطح المهايئات الاختيارية. ابدأ
|
||||
بالحد الأدنى — `id` و`setup` — ثم أضف المهايئات عند الحاجة.
|
||||
<Step title="بناء كائن Plugin القناة">
|
||||
تحتوي واجهة `ChannelPlugin` على العديد من أسطح المهايئات الاختيارية. ابدأ
|
||||
بالحد الأدنى — `id` و`setup` — ثم أضف المهايئات حسب الحاجة.
|
||||
|
||||
أنشئ `src/channel.ts`:
|
||||
|
||||
@ -348,7 +361,7 @@ if (decision.shouldSkip) return;
|
||||
createChannelPluginBase,
|
||||
} from "openclaw/plugin-sdk/channel-core";
|
||||
import type { OpenClawConfig } from "openclaw/plugin-sdk/channel-core";
|
||||
import { acmeChatApi } from "./client.js"; // عميل API الخاص بمنصتك
|
||||
import { acmeChatApi } from "./client.js"; // your platform API client
|
||||
|
||||
type ResolvedAccount = {
|
||||
accountId: string | null;
|
||||
@ -389,7 +402,7 @@ if (decision.shouldSkip) return;
|
||||
},
|
||||
}),
|
||||
|
||||
// أمان الرسائل المباشرة: من يمكنه مراسلة البوت
|
||||
// DM security: who can message the bot
|
||||
security: {
|
||||
dm: {
|
||||
channelKey: "acme-chat",
|
||||
@ -399,21 +412,21 @@ if (decision.shouldSkip) return;
|
||||
},
|
||||
},
|
||||
|
||||
// الاقتران: تدفق الموافقة لجهات اتصال الرسائل المباشرة الجديدة
|
||||
// Pairing: approval flow for new DM contacts
|
||||
pairing: {
|
||||
text: {
|
||||
idLabel: "اسم مستخدم Acme Chat",
|
||||
message: "أرسل هذا الرمز للتحقق من هويتك:",
|
||||
idLabel: "Acme Chat username",
|
||||
message: "Send this code to verify your identity:",
|
||||
notify: async ({ target, code }) => {
|
||||
await acmeChatApi.sendDm(target, `Pairing code: ${code}`);
|
||||
},
|
||||
},
|
||||
},
|
||||
|
||||
// التسلسل: كيف يتم تسليم الردود
|
||||
// Threading: how replies are delivered
|
||||
threading: { topLevelReplyToMode: "reply" },
|
||||
|
||||
// الصادر: إرسال الرسائل إلى المنصة
|
||||
// Outbound: send messages to the platform
|
||||
outbound: {
|
||||
attachedResults: {
|
||||
sendText: async (params) => {
|
||||
@ -433,24 +446,24 @@ if (decision.shouldSkip) return;
|
||||
});
|
||||
```
|
||||
|
||||
<Accordion title="ما الذي يفعله createChatChannelPlugin نيابةً عنك">
|
||||
بدلًا من تنفيذ واجهات مهايئات منخفضة المستوى يدويًا، فإنك تمرّر
|
||||
خيارات تصريحية، ويتولى الباني تركيبها:
|
||||
<Accordion title="ما الذي يفعله `createChatChannelPlugin` لك">
|
||||
بدلًا من تنفيذ واجهات المهايئات منخفضة المستوى يدويًا، فإنك تمرر
|
||||
خيارات وصفية ويقوم الباني بتجميعها:
|
||||
|
||||
| الخيار | ما الذي يوصّله |
|
||||
| الخيار | ما الذي يربطه |
|
||||
| --- | --- |
|
||||
| `security.dm` | محلل أمان رسائل مباشرة ضمن النطاق من حقول التكوين |
|
||||
| `pairing.text` | تدفق اقتران رسائل مباشرة قائم على النص مع تبادل الرموز |
|
||||
| `threading` | محلل وضع الرد (ثابت، أو ضمن الحساب، أو مخصص) |
|
||||
| `outbound.attachedResults` | دوال إرسال تعيد بيانات تعريف النتيجة (معرّفات الرسائل) |
|
||||
| `security.dm` | محلّل أمان DM مقيّد النطاق من حقول التهيئة |
|
||||
| `pairing.text` | تدفق اقتران DM قائم على النص مع تبادل الرموز |
|
||||
| `threading` | محلّل وضع الرد (ثابت أو مقيّد بالحساب أو مخصص) |
|
||||
| `outbound.attachedResults` | دوال إرسال تُرجع بيانات وصفية للنتيجة (معرّفات الرسائل) |
|
||||
|
||||
يمكنك أيضًا تمرير كائنات المهايئات الخام بدلًا من الخيارات التصريحية
|
||||
إذا كنت بحاجة إلى تحكم كامل.
|
||||
يمكنك أيضًا تمرير كائنات مهايئات خام بدلًا من الخيارات الوصفية
|
||||
إذا كنت تحتاج إلى تحكم كامل.
|
||||
</Accordion>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="وصّل نقطة الدخول">
|
||||
<Step title="ربط نقطة الدخول">
|
||||
أنشئ `index.ts`:
|
||||
|
||||
```typescript index.ts
|
||||
@ -460,20 +473,20 @@ if (decision.shouldSkip) return;
|
||||
export default defineChannelPluginEntry({
|
||||
id: "acme-chat",
|
||||
name: "Acme Chat",
|
||||
description: "Plugin قناة Acme Chat",
|
||||
description: "Acme Chat channel plugin",
|
||||
plugin: acmeChatPlugin,
|
||||
registerCliMetadata(api) {
|
||||
api.registerCli(
|
||||
({ program }) => {
|
||||
program
|
||||
.command("acme-chat")
|
||||
.description("إدارة Acme Chat");
|
||||
.description("Acme Chat management");
|
||||
},
|
||||
{
|
||||
descriptors: [
|
||||
{
|
||||
name: "acme-chat",
|
||||
description: "إدارة Acme Chat",
|
||||
description: "Acme Chat management",
|
||||
hasSubcommands: false,
|
||||
},
|
||||
],
|
||||
@ -486,21 +499,22 @@ if (decision.shouldSkip) return;
|
||||
});
|
||||
```
|
||||
|
||||
ضع واصفات CLI التي تملكها القناة في `registerCliMetadata(...)` حتى يتمكن OpenClaw
|
||||
من عرضها في المساعدة الجذرية من دون تفعيل وقت تشغيل القناة الكامل،
|
||||
بينما تلتقط عمليات التحميل الكاملة العادية الواصفات نفسها لتسجيل الأوامر
|
||||
الفعلي. وأبقِ `registerFull(...)` للأعمال الخاصة بوقت التشغيل فقط.
|
||||
إذا كان `registerFull(...)` يسجل أساليب Gateway RPC، فاستخدم
|
||||
بادئة خاصة بـ Plugin. تبقى نطاقات إدارة Core (`config.*`,
|
||||
و`exec.approvals.*`، و`wizard.*`، و`update.*`) محجوزة، وتُحل دائمًا
|
||||
ضع واصفات CLI الخاصة بالقناة في `registerCliMetadata(...)` حتى يتمكن OpenClaw
|
||||
من عرضها في مساعدة الجذر دون تنشيط وقت تشغيل القناة الكامل،
|
||||
بينما تستمر عمليات التحميل الكاملة العادية في التقاط الواصفات نفسها
|
||||
لتسجيل الأوامر الفعلي. وأبقِ `registerFull(...)` للأعمال الخاصة
|
||||
بوقت التشغيل فقط.
|
||||
وإذا كان `registerFull(...)` يسجّل أساليب Gateway RPC، فاستخدم
|
||||
بادئة خاصة بالـ Plugin. إذ تبقى نطاقات أسماء إدارة النواة (`config.*`،
|
||||
و`exec.approvals.*`، و`wizard.*`، و`update.*`) محجوزة وتُحل دائمًا
|
||||
إلى `operator.admin`.
|
||||
يتولى `defineChannelPluginEntry` معالجة تقسيم وضع التسجيل تلقائيًا. راجع
|
||||
يتولى `defineChannelPluginEntry` تقسيم وضع التسجيل تلقائيًا. راجع
|
||||
[نقاط الدخول](/ar/plugins/sdk-entrypoints#definechannelpluginentry) لجميع
|
||||
الخيارات.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="أضف نقطة دخول للإعداد">
|
||||
<Step title="إضافة نقطة دخول للإعداد">
|
||||
أنشئ `setup-entry.ts` للتحميل الخفيف أثناء الإعداد الأولي:
|
||||
|
||||
```typescript setup-entry.ts
|
||||
@ -511,18 +525,18 @@ if (decision.shouldSkip) return;
|
||||
```
|
||||
|
||||
يحمّل OpenClaw هذا بدلًا من نقطة الدخول الكاملة عندما تكون القناة معطلة
|
||||
أو غير مكوّنة. وهذا يتجنب سحب كود وقت تشغيل ثقيل أثناء تدفقات الإعداد.
|
||||
راجع [الإعداد والتكوين](/ar/plugins/sdk-setup#setup-entry) للتفاصيل.
|
||||
أو غير مضبوطة. وهو يتجنب سحب شيفرة وقت تشغيل ثقيلة أثناء تدفقات الإعداد.
|
||||
راجع [الإعداد والتهيئة](/ar/plugins/sdk-setup#setup-entry) للتفاصيل.
|
||||
|
||||
يمكن لقنوات مساحة العمل المضمّنة التي تفصل التصديرات الآمنة للإعداد إلى
|
||||
وحدات جانبية استخدام `defineBundledChannelSetupEntry(...)` من
|
||||
يمكن لقنوات workspace المضمّنة التي تفصل التصديرات الآمنة للإعداد إلى
|
||||
وحدات sidecar أن تستخدم `defineBundledChannelSetupEntry(...)` من
|
||||
`openclaw/plugin-sdk/channel-entry-contract` عندما تحتاج أيضًا إلى
|
||||
معيّن وقت تشغيل صريح في وقت الإعداد.
|
||||
أداة ضبط صريحة لوقت التشغيل في وقت الإعداد.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="تعامل مع الرسائل الواردة">
|
||||
يحتاج Plugin الخاص بك إلى استقبال الرسائل من المنصة وتمريرها إلى
|
||||
<Step title="معالجة الرسائل الواردة">
|
||||
يحتاج Plugin الخاص بك إلى تلقي الرسائل من المنصة وتمريرها إلى
|
||||
OpenClaw. والنمط المعتاد هو Webhook يتحقق من الطلب ثم
|
||||
يوزعه عبر معالج الوارد الخاص بقناتك:
|
||||
|
||||
@ -534,9 +548,9 @@ if (decision.shouldSkip) return;
|
||||
handler: async (req, res) => {
|
||||
const event = parseWebhookPayload(req);
|
||||
|
||||
// يوزّع معالج الوارد الخاص بك الرسالة إلى OpenClaw.
|
||||
// يعتمد التوصيل الدقيق على SDK الخاصة بمنصتك —
|
||||
// راجع مثالًا حقيقيًا في حزمة Plugin الخاصة بـ Microsoft Teams أو Google Chat المضمّنة.
|
||||
// يوزّع معالج الوارد لديك الرسالة إلى OpenClaw.
|
||||
// يعتمد الربط الدقيق على SDK الخاص بمنصتك —
|
||||
// راجع مثالًا حقيقيًا في حزمة Plugin Microsoft Teams أو Google Chat المضمّنة.
|
||||
await handleAcmeChatInbound(api, event);
|
||||
|
||||
res.statusCode = 200;
|
||||
@ -548,9 +562,9 @@ if (decision.shouldSkip) return;
|
||||
```
|
||||
|
||||
<Note>
|
||||
إن التعامل مع الرسائل الواردة خاص بكل قناة. فكل Plugin قناة يمتلك
|
||||
خط أنابيب الوارد الخاص به. انظر إلى Plugins القنوات المضمّنة
|
||||
(مثل حزمة Plugin الخاصة بـ Microsoft Teams أو Google Chat) لمعرفة الأنماط الفعلية.
|
||||
إن معالجة الرسائل الواردة خاصة بكل قناة. إذ يمتلك كل Plugin قناة
|
||||
خط معالجة وارد خاصًا به. انظر إلى Plugins القنوات المضمّنة
|
||||
(مثل حزمة Plugin Microsoft Teams أو Google Chat) للاطلاع على أنماط حقيقية.
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
@ -595,7 +609,7 @@ if (decision.shouldSkip) return;
|
||||
pnpm test -- <bundled-plugin-root>/acme-chat/
|
||||
```
|
||||
|
||||
بالنسبة إلى مساعدات الاختبار المشتركة، راجع [الاختبار](/ar/plugins/sdk-testing).
|
||||
للاطلاع على مساعدات الاختبار المشتركة، راجع [الاختبار](/ar/plugins/sdk-testing).
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
@ -604,8 +618,8 @@ if (decision.shouldSkip) return;
|
||||
|
||||
```
|
||||
<bundled-plugin-root>/acme-chat/
|
||||
├── package.json # بيانات تعريف openclaw.channel
|
||||
├── openclaw.plugin.json # البيان مع مخطط التكوين
|
||||
├── package.json # بيانات openclaw.channel الوصفية
|
||||
├── openclaw.plugin.json # Manifest مع مخطط التهيئة
|
||||
├── index.ts # defineChannelPluginEntry
|
||||
├── setup-entry.ts # defineSetupPluginEntry
|
||||
├── api.ts # التصديرات العامة (اختياري)
|
||||
@ -613,20 +627,20 @@ if (decision.shouldSkip) return;
|
||||
└── src/
|
||||
├── channel.ts # ChannelPlugin عبر createChatChannelPlugin
|
||||
├── channel.test.ts # الاختبارات
|
||||
├── client.ts # عميل API الخاص بالمنصة
|
||||
└── runtime.ts # مخزن وقت التشغيل (إذا لزم الأمر)
|
||||
├── client.ts # عميل API للمنصة
|
||||
└── runtime.ts # مخزن وقت التشغيل (عند الحاجة)
|
||||
```
|
||||
|
||||
## موضوعات متقدمة
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="خيارات التسلسل" icon="git-branch" href="/ar/plugins/sdk-entrypoints#registration-mode">
|
||||
أوضاع الرد الثابتة، أو ضمن الحساب، أو المخصصة
|
||||
أوضاع رد ثابتة، أو مقيّدة بالحساب، أو مخصصة
|
||||
</Card>
|
||||
<Card title="تكامل أداة الرسائل" icon="puzzle" href="/ar/plugins/architecture#channel-plugins-and-the-shared-message-tool">
|
||||
<Card title="تكامل message tool" icon="puzzle" href="/ar/plugins/architecture#channel-plugins-and-the-shared-message-tool">
|
||||
describeMessageTool واكتشاف الإجراءات
|
||||
</Card>
|
||||
<Card title="حل الأهداف" icon="crosshair" href="/ar/plugins/architecture#channel-target-resolution">
|
||||
<Card title="حلّ الهدف" icon="crosshair" href="/ar/plugins/architecture#channel-target-resolution">
|
||||
inferTargetChatType وlooksLikeId وresolveTarget
|
||||
</Card>
|
||||
<Card title="مساعدات وقت التشغيل" icon="settings" href="/ar/plugins/sdk-runtime">
|
||||
@ -635,15 +649,15 @@ if (decision.shouldSkip) return;
|
||||
</CardGroup>
|
||||
|
||||
<Note>
|
||||
لا تزال بعض طبقات المساعدات المضمّنة موجودة لصيانة Plugins المضمّنة
|
||||
ولأغراض التوافق. لكنها ليست النمط الموصى به لـ Plugins القنوات الجديدة؛
|
||||
فضّل المسارات الفرعية العامة للقنوات/الإعداد/الرد/وقت التشغيل من
|
||||
سطح SDK المشترك ما لم تكن تصون عائلة Plugin المضمّنة تلك مباشرة.
|
||||
لا تزال بعض واجهات المساعدات المضمّنة موجودة لصيانة Plugins المضمّنة
|
||||
ولأغراض التوافق. وهي ليست النمط الموصى به لـ Plugins القنوات الجديدة؛
|
||||
بل يُفضّل استخدام المسارات الفرعية العامة للقناة/الإعداد/الرد/وقت التشغيل من
|
||||
سطح SDK المشترك ما لم تكن تصون عائلة Plugin المضمّنة تلك مباشرةً.
|
||||
</Note>
|
||||
|
||||
## الخطوات التالية
|
||||
|
||||
- [Provider Plugins](/ar/plugins/sdk-provider-plugins) — إذا كان Plugin الخاص بك يوفّر أيضًا نماذج
|
||||
- [نظرة عامة على SDK](/ar/plugins/sdk-overview) — المرجع الكامل لاستيراد المسارات الفرعية
|
||||
- [Plugins الموفر](/ar/plugins/sdk-provider-plugins) — إذا كان Plugin الخاص بك يوفر أيضًا نماذج
|
||||
- [نظرة عامة على SDK](/ar/plugins/sdk-overview) — مرجع كامل لاستيراد المسارات الفرعية
|
||||
- [اختبار SDK](/ar/plugins/sdk-testing) — أدوات الاختبار واختبارات العقود
|
||||
- [بيان Plugin](/ar/plugins/manifest) — المخطط الكامل للبيان
|
||||
- [Manifest Plugin](/ar/plugins/manifest) — مخطط manifest الكامل
|
||||
|
||||
@ -1,30 +1,30 @@
|
||||
---
|
||||
read_when:
|
||||
- تحتاج إلى معرفة أي مسار فرعي من SDK يجب الاستيراد منه
|
||||
- تريد مرجعًا لجميع أساليب التسجيل في `OpenClawPluginApi`
|
||||
- أنت تبحث عن تصدير محدد من SDK
|
||||
- تحتاج إلى معرفة أي مسار فرعي من Plugin SDK يجب الاستيراد منه
|
||||
- تريد مرجعًا لجميع أساليب التسجيل في OpenClawPluginApi
|
||||
- أنت تبحث عن تصدير محدد في SDK
|
||||
sidebarTitle: SDK Overview
|
||||
summary: خريطة الاستيراد، ومرجع واجهة API للتسجيل، وبنية SDK
|
||||
summary: خريطة الاستيراد، ومرجع API للتسجيل، وبنية Plugin SDK
|
||||
title: نظرة عامة على Plugin SDK
|
||||
x-i18n:
|
||||
generated_at: "2026-04-22T04:26:25Z"
|
||||
generated_at: "2026-04-22T07:18:33Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 8045c11976bbda6afe3303a0aab08caf0d0a86ebcf1aaaf927943b90cc517673
|
||||
source_hash: e57019e6f9a7fed7842ac575e025b6db41d125f5fa9d0d1de03923fdb1f6bcc3
|
||||
source_path: plugins/sdk-overview.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# نظرة عامة على Plugin SDK
|
||||
|
||||
يُعد Plugin SDK العقد المطبّع بين plugins والنواة. وهذه الصفحة هي
|
||||
المرجع الخاص بـ **ما يجب استيراده** و**ما الذي يمكنك تسجيله**.
|
||||
يمثل Plugin SDK العقد المطبوع بين Plugins والنواة. وتعد هذه الصفحة
|
||||
مرجعًا لـ **ما الذي يجب استيراده** و**ما الذي يمكنك تسجيله**.
|
||||
|
||||
<Tip>
|
||||
**هل تبحث عن دليل إرشادي؟**
|
||||
- أول plugin؟ ابدأ من [البدء](/ar/plugins/building-plugins)
|
||||
- plugin قناة؟ راجع [Channel Plugins](/ar/plugins/sdk-channel-plugins)
|
||||
- plugin مزوّد؟ راجع [Provider Plugins](/ar/plugins/sdk-provider-plugins)
|
||||
- أول Plugin؟ ابدأ من [Getting Started](/ar/plugins/building-plugins)
|
||||
- Plugin للقنوات؟ راجع [Channel Plugins](/ar/plugins/sdk-channel-plugins)
|
||||
- Plugin لموفّر؟ راجع [Provider Plugins](/ar/plugins/sdk-provider-plugins)
|
||||
</Tip>
|
||||
|
||||
## اصطلاح الاستيراد
|
||||
@ -36,43 +36,43 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
|
||||
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
```
|
||||
|
||||
كل مسار فرعي هو وحدة صغيرة ومكتفية ذاتيًا. وهذا يحافظ على سرعة بدء التشغيل
|
||||
ويمنع مشكلات التبعيات الدائرية. وبالنسبة إلى وسائل المساعدة الخاصة بإدخال/بناء القنوات،
|
||||
ففضّل `openclaw/plugin-sdk/channel-core`؛ وأبقِ `openclaw/plugin-sdk/core` من أجل
|
||||
السطح الأشمل والمساعدات المشتركة مثل
|
||||
كل مسار فرعي هو وحدة صغيرة ومكتفية ذاتيًا. يحافظ ذلك على سرعة بدء التشغيل
|
||||
ويمنع مشكلات التبعيات الدائرية. وبالنسبة إلى أدوات الإدخال/البناء الخاصة بالقنوات،
|
||||
فمن المفضل استخدام `openclaw/plugin-sdk/channel-core`؛ واحتفظ بـ `openclaw/plugin-sdk/core` لواجهة
|
||||
المظلة الأوسع وللمساعدات المشتركة مثل
|
||||
`buildChannelConfigSchema`.
|
||||
|
||||
لا تُضف أو تعتمد على مسارات convenience seams المسماة باسم المزوّد مثل
|
||||
`openclaw/plugin-sdk/slack` أو `openclaw/plugin-sdk/discord`،
|
||||
أو `openclaw/plugin-sdk/signal`، أو `openclaw/plugin-sdk/whatsapp`، أو
|
||||
المسارات المساعدة ذات العلامة التجارية الخاصة بالقنوات. يجب على plugins المضمّنة أن تركّب
|
||||
المسارات الفرعية العامة لـ SDK داخل ملفات `api.ts` أو `runtime-api.ts`
|
||||
الخاصة بها، ويجب على النواة إما استخدام تلك الملفات المحلية الخاصة بالplugin أو إضافة
|
||||
عقد SDK عامًا ضيقًا عندما تكون الحاجة فعلًا عابرة للقنوات.
|
||||
لا تُضف ولا تعتمد على واجهات تسهيلية مسماة باسم الموفّر مثل
|
||||
`openclaw/plugin-sdk/slack` أو `openclaw/plugin-sdk/discord` أو
|
||||
`openclaw/plugin-sdk/signal` أو `openclaw/plugin-sdk/whatsapp` أو
|
||||
واجهات مساعدة تحمل علامة القناة. يجب على bundled plugins تركيب
|
||||
المسارات الفرعية العامة في SDK داخل حاويات `api.ts` أو `runtime-api.ts` الخاصة بها، ويجب على النواة
|
||||
إما استخدام هذه الحاويات المحلية الخاصة بالـ plugin أو إضافة عقد SDK عام وضيّق
|
||||
عندما تكون الحاجة مشتركة فعلًا بين القنوات.
|
||||
|
||||
ما زالت خريطة التصدير المولدة تحتوي على مجموعة صغيرة من المسارات المساعدة الخاصة بالplugins المضمّنة
|
||||
مثل `plugin-sdk/feishu`، و`plugin-sdk/feishu-setup`،
|
||||
و`plugin-sdk/zalo`، و`plugin-sdk/zalo-setup`، و`plugin-sdk/matrix*`. توجد هذه
|
||||
المسارات الفرعية لصيانة plugins المضمّنة والتوافق فقط؛ وقد تم حذفها عمدًا من الجدول المشترك أدناه
|
||||
وليست مسار الاستيراد الموصى به للplugins الجديدة التابعة لجهات خارجية.
|
||||
لا تزال خريطة التصدير المُولّدة تتضمن مجموعة صغيرة من
|
||||
واجهات المساعدة الخاصة بـ bundled-plugin مثل `plugin-sdk/feishu` و`plugin-sdk/feishu-setup`
|
||||
و`plugin-sdk/zalo` و`plugin-sdk/zalo-setup` و`plugin-sdk/matrix*`. هذه
|
||||
المسارات الفرعية موجودة فقط لصيانة bundled-plugin والتوافق؛ وقد أُزيلت عمدًا من الجدول الشائع أدناه
|
||||
وليست مسار الاستيراد الموصى به للـ Plugins الخارجية الجديدة.
|
||||
|
||||
## مرجع المسارات الفرعية
|
||||
|
||||
أكثر المسارات الفرعية استخدامًا، مجمّعة حسب الغرض. وتوجد القائمة الكاملة المولدة
|
||||
التي تضم أكثر من 200 مسار فرعي في `scripts/lib/plugin-sdk-entrypoints.json`.
|
||||
أكثر المسارات الفرعية استخدامًا، مجمعة حسب الغرض. توجد القائمة الكاملة المُولّدة التي تضم
|
||||
أكثر من 200 مسار فرعي في `scripts/lib/plugin-sdk-entrypoints.json`.
|
||||
|
||||
ما زالت المسارات الفرعية المساعدة المحجوزة الخاصة بالplugins المضمّنة تظهر في هذه القائمة المولدة.
|
||||
تعامل معها على أنها تفاصيل تنفيذ/أسطح توافق ما لم تروّج لها صفحة وثائق
|
||||
صراحةً باعتبارها عامة.
|
||||
لا تزال المسارات الفرعية المحجوزة لمساعدات bundled-plugin تظهر في تلك القائمة المُولّدة.
|
||||
تعامل معها على أنها تفاصيل تنفيذ/واجهات توافق، ما لم تقم صفحة وثائق
|
||||
بالترويج الصريح لإحداها على أنها عامة.
|
||||
|
||||
### إدخال Plugin
|
||||
|
||||
| المسار الفرعي | أهم التصديرات |
|
||||
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
|
||||
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
|
||||
| `plugin-sdk/config-schema` | `OpenClawSchema` |
|
||||
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
|
||||
| المسار الفرعي | أهم التصديرات |
|
||||
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
|
||||
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
|
||||
| `plugin-sdk/config-schema` | `OpenClawSchema` |
|
||||
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="المسارات الفرعية للقنوات">
|
||||
@ -80,199 +80,199 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
| --- | --- |
|
||||
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
|
||||
| `plugin-sdk/config-schema` | تصدير مخطط Zod الجذري لـ `openclaw.json` (`OpenClawSchema`) |
|
||||
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`، بالإضافة إلى `DEFAULT_ACCOUNT_ID` و`createTopLevelChannelDmPolicy` و`setSetupChannelEnabled` و`splitSetupEntries` |
|
||||
| `plugin-sdk/setup` | مساعدات معالج الإعداد المشتركة، ومطالبات قائمة السماح، وبناة حالة الإعداد |
|
||||
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`، بالإضافة إلى `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
|
||||
| `plugin-sdk/setup` | مساعدات مشتركة لمعالج الإعداد، ورسائل allowlist، وبُناة حالة الإعداد |
|
||||
| `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
|
||||
| `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` |
|
||||
| `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
|
||||
| `plugin-sdk/account-core` | مساعدات تكوين/بوابة الإجراءات متعددة الحسابات، ومساعدات fallback للحساب الافتراضي |
|
||||
| `plugin-sdk/account-core` | مساعدات إعدادات/بوابة إجراءات متعددة الحسابات، ومساعدات الرجوع إلى الحساب الافتراضي |
|
||||
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`، ومساعدات تطبيع معرّف الحساب |
|
||||
| `plugin-sdk/account-resolution` | مساعدات البحث عن الحساب + fallback الافتراضي |
|
||||
| `plugin-sdk/account-resolution` | مساعدات البحث عن الحساب + الرجوع إلى الافتراضي |
|
||||
| `plugin-sdk/account-helpers` | مساعدات ضيقة لقائمة الحسابات/إجراءات الحساب |
|
||||
| `plugin-sdk/channel-pairing` | `createChannelPairingController` |
|
||||
| `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` |
|
||||
| `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` |
|
||||
| `plugin-sdk/channel-config-schema` | أنواع مخطط تكوين القناة |
|
||||
| `plugin-sdk/telegram-command-config` | مساعدات تطبيع/تحقق الأوامر المخصصة في Telegram مع fallback لعقد مضمّن |
|
||||
| `plugin-sdk/channel-config-schema` | أنواع مخطط إعداد القناة |
|
||||
| `plugin-sdk/telegram-command-config` | مساعدات تطبيع/تحقق للأوامر المخصصة في Telegram مع رجوع إلى bundled-contract |
|
||||
| `plugin-sdk/command-gating` | مساعدات ضيقة لبوابة تفويض الأوامر |
|
||||
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
|
||||
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`، ومساعدات دورة حياة/finalization الخاصة ببث المسودات |
|
||||
| `plugin-sdk/inbound-envelope` | مساعدات مشتركة لبناء التوجيه الداخل + envelope |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | مساعدات مشتركة لتسجيل وتوزيع الرسائل الداخلة |
|
||||
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`، ومساعدات دورة الحياة/الإنهاء لمسودة التدفق |
|
||||
| `plugin-sdk/inbound-envelope` | مساعدات مشتركة للتوجيه الوارد + بناء الظرف |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | مساعدات مشتركة للتسجيل الوارد ثم الإرسال |
|
||||
| `plugin-sdk/messaging-targets` | مساعدات تحليل/مطابقة الأهداف |
|
||||
| `plugin-sdk/outbound-media` | مساعدات مشتركة لتحميل الوسائط الصادرة |
|
||||
| `plugin-sdk/outbound-runtime` | مساعدات الهوية الصادرة، ومفوّض الإرسال، وتخطيط الحمولة |
|
||||
| `plugin-sdk/poll-runtime` | مساعدات ضيقة لتطبيع الاستطلاعات |
|
||||
| `plugin-sdk/thread-bindings-runtime` | مساعدات دورة حياة ارتباطات الخيوط والمهايئات |
|
||||
| `plugin-sdk/agent-media-payload` | باني حمولة وسائط الوكيل القديم |
|
||||
| `plugin-sdk/conversation-runtime` | مساعدات المحادثة/ربط الخيوط، وpairing، والارتباطات المكوّنة |
|
||||
| `plugin-sdk/runtime-config-snapshot` | مساعد snapshot لتكوين وقت التشغيل |
|
||||
| `plugin-sdk/runtime-group-policy` | مساعدات حل سياسة المجموعة في وقت التشغيل |
|
||||
| `plugin-sdk/channel-status` | مساعدات مشتركة لـ snapshot/summary حالة القناة |
|
||||
| `plugin-sdk/channel-config-primitives` | العناصر الأولية الضيقة لمخطط تكوين القناة |
|
||||
| `plugin-sdk/channel-config-writes` | مساعدات تفويض كتابة تكوين القناة |
|
||||
| `plugin-sdk/channel-plugin-common` | تصديرات المقدمة المشتركة لـ plugin القناة |
|
||||
| `plugin-sdk/allowlist-config-edit` | مساعدات تعديل/قراءة تكوين قائمة السماح |
|
||||
| `plugin-sdk/thread-bindings-runtime` | مساعدات دورة الحياة والمهايئ لربط الخيوط |
|
||||
| `plugin-sdk/agent-media-payload` | باني حمولة وسائط العامل القديم |
|
||||
| `plugin-sdk/conversation-runtime` | مساعدات المحادثة/ربط الخيوط، والاقتران، والربط المُعد |
|
||||
| `plugin-sdk/runtime-config-snapshot` | مساعد لقطة إعدادات وقت التشغيل |
|
||||
| `plugin-sdk/runtime-group-policy` | مساعدات حل سياسات المجموعات في وقت التشغيل |
|
||||
| `plugin-sdk/channel-status` | مساعدات مشتركة للّقطة/الملخص الخاص بحالة القناة |
|
||||
| `plugin-sdk/channel-config-primitives` | بدائيات ضيقة لمخطط إعداد القناة |
|
||||
| `plugin-sdk/channel-config-writes` | مساعدات تفويض كتابة إعدادات القناة |
|
||||
| `plugin-sdk/channel-plugin-common` | تصديرات تمهيدية مشتركة لـ channel plugin |
|
||||
| `plugin-sdk/allowlist-config-edit` | مساعدات قراءة/تعديل إعدادات allowlist |
|
||||
| `plugin-sdk/group-access` | مساعدات مشتركة لقرارات وصول المجموعات |
|
||||
| `plugin-sdk/direct-dm` | مساعدات مشتركة لمصادقة/حماية الرسائل المباشرة المباشرة |
|
||||
| `plugin-sdk/interactive-runtime` | العرض الدلالي للرسائل، والتسليم، ومساعدات الردود التفاعلية القديمة. راجع [عرض الرسائل](/ar/plugins/message-presentation) |
|
||||
| `plugin-sdk/channel-inbound` | ملف توافق للتعامل مع debounce للواردات، ومطابقة الذكر، ومساعدات سياسة الذكر، ومساعدات envelope |
|
||||
| `plugin-sdk/channel-mention-gating` | مساعدات ضيقة لسياسة الذكر من دون السطح الأشمل لوقت تشغيل الواردات |
|
||||
| `plugin-sdk/channel-location` | مساعدات سياق الموقع في القناة وتنسيقه |
|
||||
| `plugin-sdk/channel-logging` | مساعدات تسجيل القنوات لحالات إسقاط الواردات وإخفاقات الكتابة/الإقرار |
|
||||
| `plugin-sdk/channel-send-result` | أنواع نتائج الرد |
|
||||
| `plugin-sdk/channel-actions` | مساعدات إجراءات رسائل القناة، بالإضافة إلى مساعدات المخطط الأصلية المهجورة التي أُبقي عليها من أجل توافق plugin |
|
||||
| `plugin-sdk/direct-dm` | مساعدات مشتركة للمصادقة/الحماية الخاصة بـ direct-DM |
|
||||
| `plugin-sdk/interactive-runtime` | مساعدات العرض الدلالي للرسائل، والتسليم، والردود التفاعلية القديمة. راجع [Message Presentation](/ar/plugins/message-presentation) |
|
||||
| `plugin-sdk/channel-inbound` | حاوية توافق لمساعدات inbound debounce، ومطابقة الإشارات، ومساعدات mention-policy، ومساعدات الظرف |
|
||||
| `plugin-sdk/channel-mention-gating` | مساعدات ضيقة لسياسات الإشارة من دون واجهة وقت التشغيل الوارد الأوسع |
|
||||
| `plugin-sdk/channel-location` | مساعدات سياق موقع القناة وتنسيقه |
|
||||
| `plugin-sdk/channel-logging` | مساعدات تسجيل القناة لحالات إسقاط الوارد وإخفاقات typing/ack |
|
||||
| `plugin-sdk/channel-send-result` | أنواع نتيجة الرد |
|
||||
| `plugin-sdk/channel-actions` | مساعدات إجراءات رسائل القناة، بالإضافة إلى مساعدات المخطط الأصلي المتقادمة المُحتفَظ بها لتوافق plugin |
|
||||
| `plugin-sdk/channel-targets` | مساعدات تحليل/مطابقة الأهداف |
|
||||
| `plugin-sdk/channel-contract` | أنواع عقد القناة |
|
||||
| `plugin-sdk/channel-feedback` | ربط الملاحظات/التفاعلات |
|
||||
| `plugin-sdk/channel-secret-runtime` | مساعدات ضيقة لعقد الأسرار مثل `collectSimpleChannelFieldAssignments` و`getChannelSurface` و`pushAssignment` وأنواع أهداف الأسرار |
|
||||
| `plugin-sdk/channel-feedback` | توصيل التغذية الراجعة/التفاعلات |
|
||||
| `plugin-sdk/channel-secret-runtime` | مساعدات ضيقة لعقد الأسرار مثل `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`، وأنواع أهداف الأسرار |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="المسارات الفرعية للمزوّدين">
|
||||
<Accordion title="المسارات الفرعية للمزوّد">
|
||||
| المسار الفرعي | أهم التصديرات |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
|
||||
| `plugin-sdk/provider-setup` | مساعدات منسّقة لإعداد المزوّدات المحلية/ذاتية الاستضافة |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | مساعدات مركزة لإعداد مزوّدات ذاتية الاستضافة متوافقة مع OpenAI |
|
||||
| `plugin-sdk/cli-backend` | الإعدادات الافتراضية لخلفية CLI + ثوابت watchdog |
|
||||
| `plugin-sdk/provider-auth-runtime` | مساعدات حل مفاتيح API في وقت التشغيل لـ plugins المزوّدين |
|
||||
| `plugin-sdk/provider-auth-api-key` | مساعدات إعداد/كتابة ملف تعريف مفتاح API مثل `upsertApiKeyProfile` |
|
||||
| `plugin-sdk/provider-auth-result` | الباني القياسي لنتيجة مصادقة OAuth |
|
||||
| `plugin-sdk/provider-auth-login` | مساعدات تسجيل الدخول التفاعلي المشتركة لـ plugins المزوّدين |
|
||||
| `plugin-sdk/provider-env-vars` | مساعدات البحث عن متغيرات بيئة مصادقة المزوّد |
|
||||
| `plugin-sdk/provider-setup` | مساعدات منسقة لإعداد الموفّرات المحلية/المستضافة ذاتيًا |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | مساعدات مركزة لإعداد موفّر مستضاف ذاتيًا ومتوافق مع OpenAI |
|
||||
| `plugin-sdk/cli-backend` | القيم الافتراضية للواجهة الخلفية لـ CLI + ثوابت watchdog |
|
||||
| `plugin-sdk/provider-auth-runtime` | مساعدات حل API key في وقت التشغيل لـ provider plugins |
|
||||
| `plugin-sdk/provider-auth-api-key` | مساعدات ضم API key وكتابة الملف التعريفي مثل `upsertApiKeyProfile` |
|
||||
| `plugin-sdk/provider-auth-result` | باني قياسي لنتيجة مصادقة OAuth |
|
||||
| `plugin-sdk/provider-auth-login` | مساعدات تسجيل دخول تفاعلية مشتركة لـ provider plugins |
|
||||
| `plugin-sdk/provider-env-vars` | مساعدات البحث عن متغيرات البيئة الخاصة بمصادقة الموفّر |
|
||||
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` |
|
||||
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`، و`buildProviderReplayFamilyHooks`، و`normalizeModelCompat`، وبناة سياسة replay المشتركة، ومساعدات نقاط نهاية المزوّد، ومساعدات تطبيع معرّف النموذج مثل `normalizeNativeXaiModelId` |
|
||||
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`، وبُناة سياسات replay المشتركة، ومساعدات endpoint الخاصة بالموفّر، ومساعدات تطبيع model-id مثل `normalizeNativeXaiModelId` |
|
||||
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
|
||||
| `plugin-sdk/provider-http` | مساعدات HTTP/قدرات نقاط نهاية المزوّد العامة |
|
||||
| `plugin-sdk/provider-web-fetch-contract` | مساعدات ضيقة لعقد تكوين/اختيار web-fetch مثل `enablePluginInConfig` و`WebFetchProviderPlugin` |
|
||||
| `plugin-sdk/provider-web-fetch` | مساعدات تسجيل/تخزين مؤقت/وقت تشغيل مزوّد web-fetch |
|
||||
| `plugin-sdk/provider-web-search-config-contract` | مساعدات ضيقة لتكوين/بيانات اعتماد web-search للمزوّدات التي لا تحتاج إلى ربط تمكين plugin |
|
||||
| `plugin-sdk/provider-web-search-contract` | مساعدات ضيقة لعقد تكوين/بيانات اعتماد web-search مثل `createWebSearchProviderContractFields` و`enablePluginInConfig` و`resolveProviderWebSearchPluginConfig` وعمليات تعيين/جلب بيانات الاعتماد ضمن النطاق |
|
||||
| `plugin-sdk/provider-web-search` | مساعدات تسجيل/تخزين مؤقت/وقت تشغيل مزوّد web-search |
|
||||
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`، و`buildProviderToolCompatFamilyHooks`، وتنظيف مخطط Gemini + التشخيصات، ومساعدات توافق xAI مثل `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
|
||||
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` وما شابه |
|
||||
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`، و`buildProviderStreamFamilyHooks`، و`composeProviderStreamWrappers`، وأنواع مغلفات stream، ومساعدات المغلفات المشتركة لـ Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
|
||||
| `plugin-sdk/provider-transport-runtime` | مساعدات نقل المزوّد الأصلية مثل fetch المحمي، وتحويلات رسائل النقل، وتيارات أحداث النقل القابلة للكتابة |
|
||||
| `plugin-sdk/provider-onboard` | مساعدات patch لتكوين الإعداد الأولي |
|
||||
| `plugin-sdk/provider-http` | مساعدات عامة لقدرات HTTP/endpoint الخاصة بالموفّر |
|
||||
| `plugin-sdk/provider-web-fetch-contract` | مساعدات ضيقة لعقد إعداد/اختيار web-fetch مثل `enablePluginInConfig` و`WebFetchProviderPlugin` |
|
||||
| `plugin-sdk/provider-web-fetch` | مساعدات تسجيل/ذاكرة تخزين مؤقت لـ web-fetch provider |
|
||||
| `plugin-sdk/provider-web-search-config-contract` | مساعدات ضيقة لإعداد/بيانات اعتماد web-search للموفّرين الذين لا يحتاجون إلى توصيل تمكين plugin |
|
||||
| `plugin-sdk/provider-web-search-contract` | مساعدات ضيقة لعقد إعداد/بيانات اعتماد web-search مثل `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`، وواضعات/جالبات بيانات الاعتماد ذات النطاق المحدد |
|
||||
| `plugin-sdk/provider-web-search` | مساعدات تسجيل/ذاكرة تخزين مؤقت/وقت تشغيل لـ web-search provider |
|
||||
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`، وتنظيف مخطط Gemini + التشخيصات، ومساعدات التوافق الخاصة بـ xAI مثل `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
|
||||
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` وما شابه ذلك |
|
||||
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`، وأنواع مغلفات التدفق، ومساعدات المغلفات المشتركة لـ Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
|
||||
| `plugin-sdk/provider-transport-runtime` | مساعدات النقل الأصلية الخاصة بالموفّر مثل fetch المحمي، وتحويلات رسائل النقل، وتدفقات أحداث النقل القابلة للكتابة |
|
||||
| `plugin-sdk/provider-onboard` | مساعدات تصحيح إعدادات التهيئة |
|
||||
| `plugin-sdk/global-singleton` | مساعدات singleton/map/cache محلية للعملية |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="المسارات الفرعية للمصادقة والأمان">
|
||||
| المسار الفرعي | أهم التصديرات |
|
||||
| Subpath | أهم التصديرات |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/command-auth` | `resolveControlCommandGate`، ومساعدات سجل الأوامر، ومساعدات تفويض المرسل |
|
||||
| `plugin-sdk/command-status` | بُناة رسائل الأوامر/المساعدة مثل `buildCommandsMessagePaginated` و`buildHelpMessage` |
|
||||
| `plugin-sdk/approval-auth-runtime` | مساعدات حل الموافقين ومصادقة الإجراءات داخل الدردشة نفسها |
|
||||
| `plugin-sdk/approval-client-runtime` | مساعدات ملفات تعريف/عوامل تصفية موافقات exec الأصلية |
|
||||
| `plugin-sdk/approval-delivery-runtime` | مهايئات القدرة/التسليم الأصلية للموافقات |
|
||||
| `plugin-sdk/approval-gateway-runtime` | مساعد مشترك لحل gateway الخاصة بالموافقات |
|
||||
| `plugin-sdk/approval-handler-adapter-runtime` | مساعدات خفيفة لتحميل مهايئات الموافقات الأصلية لنقاط إدخال القنوات السريعة |
|
||||
| `plugin-sdk/approval-handler-runtime` | مساعدات أوسع لوقت تشغيل معالجات الموافقات؛ فضّل المسارات الأضيق الخاصة بالمهايئ/gateway عندما تكون كافية |
|
||||
| `plugin-sdk/approval-auth-runtime` | مساعدات حل المُوافق ومصادقة الإجراءات داخل المحادثة نفسها |
|
||||
| `plugin-sdk/approval-client-runtime` | مساعدات الملف التعريفي/عامل التصفية الخاصة بالموافقة على التنفيذ الأصلي |
|
||||
| `plugin-sdk/approval-delivery-runtime` | مهايئات قدرات/تسليم الموافقة الأصلية |
|
||||
| `plugin-sdk/approval-gateway-runtime` | مساعد حل Gateway للموافقة المشتركة |
|
||||
| `plugin-sdk/approval-handler-adapter-runtime` | مساعدات خفيفة لتحميل مهايئ الموافقة الأصلية لنقاط إدخال القنوات السريعة |
|
||||
| `plugin-sdk/approval-handler-runtime` | مساعدات أوسع لوقت تشغيل معالج الموافقة؛ استخدم واجهات adapter/gateway الأضيق عندما تكون كافية |
|
||||
| `plugin-sdk/approval-native-runtime` | مساعدات الهدف الأصلي للموافقة + ربط الحساب |
|
||||
| `plugin-sdk/approval-reply-runtime` | مساعدات حمولة ردود موافقات exec/plugin |
|
||||
| `plugin-sdk/command-auth-native` | مساعدات مصادقة الأوامر الأصلية + أهداف الجلسات الأصلية |
|
||||
| `plugin-sdk/approval-reply-runtime` | مساعدات حمولة رد الموافقة على التنفيذ/Plugin |
|
||||
| `plugin-sdk/command-auth-native` | المصادقة الأصلية للأوامر + مساعدات هدف الجلسة الأصلية |
|
||||
| `plugin-sdk/command-detection` | مساعدات مشتركة لاكتشاف الأوامر |
|
||||
| `plugin-sdk/command-surface` | مساعدات تطبيع متن الأوامر وسطح الأوامر |
|
||||
| `plugin-sdk/command-surface` | تطبيع نص الأمر ومساعدات واجهة الأمر |
|
||||
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
|
||||
| `plugin-sdk/channel-secret-runtime` | مساعدات ضيقة لتجميع عقود الأسرار لأسطح أسرار القنوات/plugins |
|
||||
| `plugin-sdk/secret-ref-runtime` | مساعدات ضيقة لـ `coerceSecretRef` وأنواع SecretRef لتحليل عقود الأسرار/التكوين |
|
||||
| `plugin-sdk/security-runtime` | مساعدات مشتركة للثقة، وتقييد الرسائل المباشرة، والمحتوى الخارجي، وتجميع الأسرار |
|
||||
| `plugin-sdk/ssrf-policy` | مساعدات سياسة SSRF الخاصة بقائمة سماح المضيفين والشبكات الخاصة |
|
||||
| `plugin-sdk/ssrf-dispatcher` | مساعدات ضيقة لـ pinned-dispatcher من دون السطح الأوسع لوقت تشغيل البنية التحتية |
|
||||
| `plugin-sdk/ssrf-runtime` | مساعدات pinned-dispatcher، وfetch المحمي من SSRF، وسياسة SSRF |
|
||||
| `plugin-sdk/secret-input` | مساعدات تحليل مدخلات الأسرار |
|
||||
| `plugin-sdk/webhook-ingress` | مساعدات طلبات/أهداف Webhook |
|
||||
| `plugin-sdk/webhook-request-guards` | مساعدات حجم متن الطلب/المهلة |
|
||||
| `plugin-sdk/channel-secret-runtime` | مساعدات ضيقة لتجميع عقود الأسرار لواجهات أسرار القناة/Plugin |
|
||||
| `plugin-sdk/secret-ref-runtime` | `coerceSecretRef` الضيق ومساعدات typing الخاصة بـ SecretRef لتحليل عقد الأسرار/الإعدادات |
|
||||
| `plugin-sdk/security-runtime` | مساعدات مشتركة للثقة، وبوابة DM، والمحتوى الخارجي، وتجميع الأسرار |
|
||||
| `plugin-sdk/ssrf-policy` | مساعدات سياسة SSRF الخاصة بقائمة سماح المضيف والشبكة الخاصة |
|
||||
| `plugin-sdk/ssrf-dispatcher` | مساعدات ضيقة لـ pinned-dispatcher من دون واجهة وقت تشغيل البنية الأوسع |
|
||||
| `plugin-sdk/ssrf-runtime` | pinned-dispatcher، وfetch المحمي من SSRF، ومساعدات سياسة SSRF |
|
||||
| `plugin-sdk/secret-input` | مساعدات تحليل إدخال الأسرار |
|
||||
| `plugin-sdk/webhook-ingress` | مساعدات طلب/هدف Webhook |
|
||||
| `plugin-sdk/webhook-request-guards` | مساعدات حجم نص الطلب/المهلة الزمنية |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="المسارات الفرعية لوقت التشغيل والتخزين">
|
||||
| المسار الفرعي | أهم التصديرات |
|
||||
| Subpath | أهم التصديرات |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/runtime` | مساعدات واسعة لوقت التشغيل/التسجيل/النسخ الاحتياطي/تثبيت plugin |
|
||||
| `plugin-sdk/runtime-env` | مساعدات ضيقة لبيئة وقت التشغيل، وlogger، والمهلة، وإعادة المحاولة، وbackoff |
|
||||
| `plugin-sdk/runtime` | مساعدات واسعة لوقت التشغيل/التسجيل/النسخ الاحتياطي/تثبيت Plugin |
|
||||
| `plugin-sdk/runtime-env` | مساعدات ضيقة لبيئة وقت التشغيل، والمسجل، والمهلة الزمنية، وإعادة المحاولة، والتراجع |
|
||||
| `plugin-sdk/channel-runtime-context` | مساعدات عامة لتسجيل والبحث عن سياق وقت تشغيل القناة |
|
||||
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
|
||||
| `plugin-sdk/plugin-runtime` | مساعدات مشتركة لأوامر/hook/http/التفاعل الخاصة بـ plugin |
|
||||
| `plugin-sdk/hook-runtime` | مساعدات مشتركة لخط أنابيب Webhook/internal hook |
|
||||
| `plugin-sdk/plugin-runtime` | مساعدات مشتركة لأوامر/خطافات/HTTP/التفاعل الخاصة بـ Plugin |
|
||||
| `plugin-sdk/hook-runtime` | مساعدات مشتركة لخط أنابيب Webhook/الخطافات الداخلية |
|
||||
| `plugin-sdk/lazy-runtime` | مساعدات الاستيراد/الربط الكسول لوقت التشغيل مثل `createLazyRuntimeModule` و`createLazyRuntimeMethod` و`createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/process-runtime` | مساعدات تنفيذ العمليات |
|
||||
| `plugin-sdk/cli-runtime` | مساعدات تنسيق CLI، والانتظار، والإصدار |
|
||||
| `plugin-sdk/gateway-runtime` | مساعدات عميل Gateway وpatch حالة القناة |
|
||||
| `plugin-sdk/config-runtime` | مساعدات تحميل/كتابة التكوين |
|
||||
| `plugin-sdk/telegram-command-config` | تطبيع أسماء/أوصاف أوامر Telegram والتحقق من التكرار/التعارض، حتى عند عدم توفر سطح عقد Telegram المضمّن |
|
||||
| `plugin-sdk/text-autolink-runtime` | اكتشاف autolink لمراجع الملفات من دون ملف text-runtime الواسع |
|
||||
| `plugin-sdk/approval-runtime` | مساعدات موافقات exec/plugin، وبناة قدرات الموافقة، ومساعدات المصادقة/الملف التعريفي، ومساعدات التوجيه/وقت التشغيل الأصلية |
|
||||
| `plugin-sdk/reply-runtime` | مساعدات مشتركة لوقت تشغيل الوارد/الرد، والتجزئة، والتوزيع، وHeartbeat، ومخطط الرد |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | مساعدات ضيقة لتوزيع/finalize الردود |
|
||||
| `plugin-sdk/reply-history` | مساعدات مشتركة قصيرة النافذة لسجل الردود مثل `buildHistoryContext` و`recordPendingHistoryEntry` و`clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/cli-runtime` | مساعدات تنسيق CLI والانتظار والإصدار |
|
||||
| `plugin-sdk/gateway-runtime` | مساعدات عميل Gateway وتصحيح حالة القناة |
|
||||
| `plugin-sdk/config-runtime` | مساعدات تحميل/كتابة الإعدادات |
|
||||
| `plugin-sdk/telegram-command-config` | تطبيع اسم/وصف أوامر Telegram وفحوصات التكرار/التعارض، حتى عند غياب واجهة عقد Telegram المضمنة |
|
||||
| `plugin-sdk/text-autolink-runtime` | اكتشاف الروابط التلقائية لمراجع الملفات من دون الحاوية الأوسع لـ text-runtime |
|
||||
| `plugin-sdk/approval-runtime` | مساعدات الموافقة على التنفيذ/Plugin، وبناة قدرات الموافقة، ومساعدات المصادقة/الملف التعريفي، ومساعدات التوجيه/وقت التشغيل الأصلية |
|
||||
| `plugin-sdk/reply-runtime` | مساعدات مشتركة لوقت تشغيل الوارد/الرد، والتجزئة، والإرسال، وHeartbeat، ومخطط الرد |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | مساعدات ضيقة لإرسال/إنهاء الرد |
|
||||
| `plugin-sdk/reply-history` | مساعدات مشتركة لسجل الردود ضمن نافذة قصيرة مثل `buildHistoryContext` و`recordPendingHistoryEntry` و`clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
|
||||
| `plugin-sdk/reply-chunking` | مساعدات ضيقة لتجزئة النص/Markdown |
|
||||
| `plugin-sdk/session-store-runtime` | مساعدات مسار مخزن الجلسات + `updated-at` |
|
||||
| `plugin-sdk/session-store-runtime` | مساعدات مسار مخزن الجلسة + `updated-at` |
|
||||
| `plugin-sdk/state-paths` | مساعدات مسارات أدلة state/OAuth |
|
||||
| `plugin-sdk/routing` | مساعدات التوجيه/مفتاح الجلسة/ربط الحساب مثل `resolveAgentRoute` و`buildAgentSessionKey` و`resolveDefaultAgentBoundAccountId` |
|
||||
| `plugin-sdk/routing` | مساعدات route/session-key وربط الحساب مثل `resolveAgentRoute` و`buildAgentSessionKey` و`resolveDefaultAgentBoundAccountId` |
|
||||
| `plugin-sdk/status-helpers` | مساعدات مشتركة لملخص حالة القناة/الحساب، والقيم الافتراضية لحالة وقت التشغيل، ومساعدات بيانات المشكلات الوصفية |
|
||||
| `plugin-sdk/target-resolver-runtime` | مساعدات مشتركة لحل الأهداف |
|
||||
| `plugin-sdk/string-normalization-runtime` | مساعدات تطبيع slug/string |
|
||||
| `plugin-sdk/string-normalization-runtime` | مساعدات تطبيع slug/السلاسل النصية |
|
||||
| `plugin-sdk/request-url` | استخراج عناوين URL النصية من مدخلات شبيهة بـ fetch/request |
|
||||
| `plugin-sdk/run-command` | مشغّل أوامر بزمن محدد مع نتائج stdout/stderr مطبّعة |
|
||||
| `plugin-sdk/param-readers` | قارئات معلمات مشتركة للأدوات/CLI |
|
||||
| `plugin-sdk/tool-payload` | استخراج الحمولات المطبّعة من كائنات نتائج الأدوات |
|
||||
| `plugin-sdk/tool-send` | استخراج حقول هدف الإرسال القياسية من وسائط الأداة |
|
||||
| `plugin-sdk/temp-path` | مساعدات مشتركة لمسارات التنزيل المؤقت |
|
||||
| `plugin-sdk/logging-core` | مساعدات logger للنظام الفرعي والتنقيح |
|
||||
| `plugin-sdk/markdown-table-runtime` | مساعدات أوضاع جداول Markdown |
|
||||
| `plugin-sdk/run-command` | مشغّل أوامر موقّت مع نتائج stdout/stderr مطبّعة |
|
||||
| `plugin-sdk/param-readers` | قارئات شائعة لمعاملات الأدوات/CLI |
|
||||
| `plugin-sdk/tool-payload` | استخراج حمولات مطبّعة من كائنات نتائج الأدوات |
|
||||
| `plugin-sdk/tool-send` | استخراج حقول هدف الإرسال القياسية من معاملات الأداة |
|
||||
| `plugin-sdk/temp-path` | مساعدات مشتركة لمسارات التنزيل المؤقتة |
|
||||
| `plugin-sdk/logging-core` | مساعدات مسجل subsystem والتنقيح |
|
||||
| `plugin-sdk/markdown-table-runtime` | مساعدات وضع جداول Markdown |
|
||||
| `plugin-sdk/json-store` | مساعدات صغيرة لقراءة/كتابة حالة JSON |
|
||||
| `plugin-sdk/file-lock` | مساعدات إعادة الدخول إلى file-lock |
|
||||
| `plugin-sdk/persistent-dedupe` | مساعدات cache إزالة التكرار المعتمد على القرص |
|
||||
| `plugin-sdk/acp-runtime` | مساعدات وقت تشغيل/جلسات ACP وتوزيع الردود |
|
||||
| `plugin-sdk/acp-binding-resolve-runtime` | حل ارتباط ACP للقراءة فقط من دون استيرادات بدء تشغيل دورة الحياة |
|
||||
| `plugin-sdk/agent-config-primitives` | عناصر أولية ضيقة لمخطط تكوين وقت تشغيل الوكيل |
|
||||
| `plugin-sdk/boolean-param` | قارئ مرن لمعلمات boolean |
|
||||
| `plugin-sdk/file-lock` | مساعدات file-lock قابلة لإعادة الدخول |
|
||||
| `plugin-sdk/persistent-dedupe` | مساعدات ذاكرة التخزين المؤقت لإزالة التكرار المدعومة بالقرص |
|
||||
| `plugin-sdk/acp-runtime` | مساعدات وقت التشغيل/الجلسة وإرسال الردود الخاصة بـ ACP |
|
||||
| `plugin-sdk/acp-binding-resolve-runtime` | حل ربط ACP للقراءة فقط من دون استيرادات بدء دورة الحياة |
|
||||
| `plugin-sdk/agent-config-primitives` | بدائيات ضيقة لمخطط إعداد وقت تشغيل العامل |
|
||||
| `plugin-sdk/boolean-param` | قارئ مرن لمعاملات boolean |
|
||||
| `plugin-sdk/dangerous-name-runtime` | مساعدات حل مطابقة الأسماء الخطرة |
|
||||
| `plugin-sdk/device-bootstrap` | مساعدات bootstrap الخاصة بالأجهزة وtoken pairing |
|
||||
| `plugin-sdk/extension-shared` | عناصر أولية مشتركة للمساعدات الخاصة بالقنوات السلبية، والحالة، وambient proxy |
|
||||
| `plugin-sdk/models-provider-runtime` | مساعدات ردود الأمر `/models`/المزوّد |
|
||||
| `plugin-sdk/skill-commands-runtime` | مساعدات إدراج أوامر Skills |
|
||||
| `plugin-sdk/native-command-registry` | مساعدات سجل/بناء/تسلسل الأوامر الأصلية |
|
||||
| `plugin-sdk/agent-harness` | سطح موثوق تجريبي لـ plugin من أجل agent harnesses منخفضة المستوى: أنواع harness، ومساعدات توجيه/إلغاء التشغيلات النشطة، ومساعدات جسر أدوات OpenClaw، وأدوات نتائج المحاولات |
|
||||
| `plugin-sdk/provider-zai-endpoint` | مساعدات اكتشاف نقطة نهاية Z.A.I |
|
||||
| `plugin-sdk/device-bootstrap` | مساعدات التمهيد الأولي للجهاز ورمز الاقتران |
|
||||
| `plugin-sdk/extension-shared` | بدائيات مساعدة مشتركة للقنوات السلبية، والحالة، والوكيل المحيطي |
|
||||
| `plugin-sdk/models-provider-runtime` | مساعدات أوامر `/models`/ردود الموفّر |
|
||||
| `plugin-sdk/skill-commands-runtime` | مساعدات سرد أوامر Skills |
|
||||
| `plugin-sdk/native-command-registry` | مساعدات سجل الأوامر الأصلي/البناء/التسلسل |
|
||||
| `plugin-sdk/agent-harness` | واجهة تجريبية لـ Plugin موثوق للمسارات منخفضة المستوى الخاصة بـ agent harnesses: أنواع harness، ومساعدات التوجيه/الإيقاف للتشغيل النشط، ومساعدات جسر أدوات OpenClaw، وأدوات نتيجة المحاولة |
|
||||
| `plugin-sdk/provider-zai-endpoint` | مساعدات اكتشاف نقطة نهاية Z.AI |
|
||||
| `plugin-sdk/infra-runtime` | مساعدات أحداث النظام/Heartbeat |
|
||||
| `plugin-sdk/collection-runtime` | مساعدات cache صغيرة محدودة |
|
||||
| `plugin-sdk/diagnostic-runtime` | مساعدات العلامات التشخيصية والأحداث |
|
||||
| `plugin-sdk/error-runtime` | مساعدات رسم الأخطاء، والتنسيق، وتصنيف الأخطاء المشترك، و`isApprovalNotFoundError` |
|
||||
| `plugin-sdk/fetch-runtime` | مساعدات fetch المغلف، وproxy، وlookup المثبت |
|
||||
| `plugin-sdk/collection-runtime` | مساعدات صغيرة لذاكرة تخزين مؤقت محدودة |
|
||||
| `plugin-sdk/diagnostic-runtime` | مساعدات الأعلام والأحداث التشخيصية |
|
||||
| `plugin-sdk/error-runtime` | مساعدات رسم الأخطاء، والتنسيق، والتصنيف المشترك للأخطاء، و`isApprovalNotFoundError` |
|
||||
| `plugin-sdk/fetch-runtime` | مساعدات fetch المغلف، والوكيل، والبحث المثبّت |
|
||||
| `plugin-sdk/runtime-fetch` | fetch لوقت التشغيل مدرك لـ dispatcher من دون استيرادات proxy/guarded-fetch |
|
||||
| `plugin-sdk/response-limit-runtime` | قارئ محدود لمتن الاستجابة من دون السطح الأوسع لوقت تشغيل الوسائط |
|
||||
| `plugin-sdk/session-binding-runtime` | حالة ارتباط المحادثة الحالية من دون توجيه الارتباطات المكوّنة أو مخازن pairing |
|
||||
| `plugin-sdk/session-store-runtime` | مساعدات قراءة مخزن الجلسات من دون استيرادات واسعة لكتابة/صيانة التكوين |
|
||||
| `plugin-sdk/context-visibility-runtime` | حل ظهور السياق وتصفية السياق الإضافي من دون استيرادات واسعة للتكوين/الأمان |
|
||||
| `plugin-sdk/string-coerce-runtime` | مساعدات ضيقة للإجبار والتطبيع للسجلات/السلاسل الأولية من دون استيرادات markdown/logging |
|
||||
| `plugin-sdk/host-runtime` | مساعدات تطبيع اسم المضيف وSCP host |
|
||||
| `plugin-sdk/retry-runtime` | مساعدات تكوين إعادة المحاولة ومشغّل إعادة المحاولة |
|
||||
| `plugin-sdk/agent-runtime` | مساعدات دليل/هوية/مساحة عمل الوكيل |
|
||||
| `plugin-sdk/directory-runtime` | الاستعلام/إزالة التكرار من الدليل المدعوم بالتكوين |
|
||||
| `plugin-sdk/response-limit-runtime` | قارئ محدود لنص الاستجابة من دون واجهة وقت تشغيل الوسائط الأوسع |
|
||||
| `plugin-sdk/session-binding-runtime` | حالة ربط المحادثة الحالية من دون توجيه الربط المُعد أو مخازن الاقتران |
|
||||
| `plugin-sdk/session-store-runtime` | مساعدات قراءة مخزن الجلسة من دون استيرادات واسعة لكتابة/صيانة الإعدادات |
|
||||
| `plugin-sdk/context-visibility-runtime` | حل ظهور السياق وتصفية السياق الإضافي من دون استيرادات واسعة للإعدادات/الأمان |
|
||||
| `plugin-sdk/string-coerce-runtime` | مساعدات ضيقة للإكراه والتطبيع للسلاسل/السجلات البدائية من دون استيرادات Markdown/التسجيل |
|
||||
| `plugin-sdk/host-runtime` | مساعدات تطبيع اسم المضيف ومضيف SCP |
|
||||
| `plugin-sdk/retry-runtime` | مساعدات إعداد إعادة المحاولة ومشغّلها |
|
||||
| `plugin-sdk/agent-runtime` | مساعدات دليل/هوية/مساحة عمل العامل |
|
||||
| `plugin-sdk/directory-runtime` | الاستعلام عن الأدلة المدعوم بالإعدادات/إزالة التكرار |
|
||||
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="المسارات الفرعية للقدرات والاختبار">
|
||||
| المسار الفرعي | أهم التصديرات |
|
||||
| Subpath | أهم التصديرات |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/media-runtime` | مساعدات مشتركة لجلب/تحويل/تخزين الوسائط بالإضافة إلى بُناة حمولة الوسائط |
|
||||
| `plugin-sdk/media-generation-runtime` | مساعدات مشتركة لـ failover في توليد الوسائط، واختيار المرشحين، ورسائل غياب النموذج |
|
||||
| `plugin-sdk/media-understanding` | أنواع مزوّدات فهم الوسائط بالإضافة إلى تصديرات مساعدات الصور/الصوت المواجهة للمزوّد |
|
||||
| `plugin-sdk/text-runtime` | مساعدات مشتركة للنص/Markdown/التسجيل مثل إزالة النص المرئي للمساعد، ومساعدات عرض/تجزئة/جداول Markdown، ومساعدات التنقيح، ومساعدات وسوم التوجيه، وأدوات النص الآمن |
|
||||
| `plugin-sdk/media-generation-runtime` | مساعدات مشتركة للتجاوز عند فشل توليد الوسائط، واختيار المرشحين، ورسائل النموذج المفقود |
|
||||
| `plugin-sdk/media-understanding` | أنواع موفّر فهم الوسائط بالإضافة إلى تصديرات مساعدات الصور/الصوت الموجّهة للموفّر |
|
||||
| `plugin-sdk/text-runtime` | مساعدات مشتركة للنص/Markdown/التسجيل مثل إزالة النص المرئي للمساعد، ومساعدات العرض/التجزئة/الجداول في Markdown، ومساعدات التنقيح، ومساعدات وسم التوجيهات، وأدوات النص الآمن |
|
||||
| `plugin-sdk/text-chunking` | مساعد تجزئة النص الصادر |
|
||||
| `plugin-sdk/speech` | أنواع مزوّدات الكلام بالإضافة إلى تصديرات المساعدات المواجهة للمزوّد الخاصة بالتوجيه، والسجل، والتحقق |
|
||||
| `plugin-sdk/speech-core` | مساعدات مشتركة لأنواع مزوّدات الكلام، والسجل، والتوجيه، والتطبيع |
|
||||
| `plugin-sdk/realtime-transcription` | أنواع مزوّدات النسخ الفوري ومساعدات السجل |
|
||||
| `plugin-sdk/realtime-voice` | أنواع مزوّدات الصوت الفوري ومساعدات السجل |
|
||||
| `plugin-sdk/image-generation` | أنواع مزوّدات توليد الصور |
|
||||
| `plugin-sdk/image-generation-core` | مساعدات مشتركة لأنواع توليد الصور، وfailover، والمصادقة، والسجل |
|
||||
| `plugin-sdk/music-generation` | أنواع مزوّد/طلب/نتيجة توليد الموسيقى |
|
||||
| `plugin-sdk/music-generation-core` | مساعدات مشتركة لأنواع توليد الموسيقى، ومساعدات failover، والبحث عن المزوّد، وتحليل model-ref |
|
||||
| `plugin-sdk/video-generation` | أنواع مزوّد/طلب/نتيجة توليد الفيديو |
|
||||
| `plugin-sdk/video-generation-core` | مساعدات مشتركة لأنواع توليد الفيديو، ومساعدات failover، والبحث عن المزوّد، وتحليل model-ref |
|
||||
| `plugin-sdk/webhook-targets` | سجل أهداف Webhook ومساعدات تثبيت المسارات |
|
||||
| `plugin-sdk/speech` | أنواع موفّر الكلام بالإضافة إلى مساعدات التوجيه والسجل والتحقق الموجّهة للموفّر |
|
||||
| `plugin-sdk/speech-core` | أنواع موفّر الكلام المشتركة، والسجل، والتوجيه، ومساعدات التطبيع |
|
||||
| `plugin-sdk/realtime-transcription` | أنواع موفّر النسخ الفوري ومساعدات السجل |
|
||||
| `plugin-sdk/realtime-voice` | أنواع موفّر الصوت الفوري ومساعدات السجل |
|
||||
| `plugin-sdk/image-generation` | أنواع موفّر توليد الصور |
|
||||
| `plugin-sdk/image-generation-core` | الأنواع المشتركة لتوليد الصور، والتجاوز عند الفشل، والمصادقة، ومساعدات السجل |
|
||||
| `plugin-sdk/music-generation` | أنواع موفّر/طلب/نتيجة توليد الموسيقى |
|
||||
| `plugin-sdk/music-generation-core` | الأنواع المشتركة لتوليد الموسيقى، ومساعدات التجاوز عند الفشل، والبحث عن الموفّر، وتحليل model-ref |
|
||||
| `plugin-sdk/video-generation` | أنواع موفّر/طلب/نتيجة توليد الفيديو |
|
||||
| `plugin-sdk/video-generation-core` | الأنواع المشتركة لتوليد الفيديو، ومساعدات التجاوز عند الفشل، والبحث عن الموفّر، وتحليل model-ref |
|
||||
| `plugin-sdk/webhook-targets` | سجل أهداف Webhook ومساعدات تثبيت route |
|
||||
| `plugin-sdk/webhook-path` | مساعدات تطبيع مسار Webhook |
|
||||
| `plugin-sdk/web-media` | مساعدات مشتركة لتحميل الوسائط البعيدة/المحلية |
|
||||
| `plugin-sdk/zod` | إعادة تصدير `zod` لمستهلكي Plugin SDK |
|
||||
@ -280,102 +280,111 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="المسارات الفرعية للذاكرة">
|
||||
| المسار الفرعي | أهم التصديرات |
|
||||
| Subpath | أهم التصديرات |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/memory-core` | سطح المساعدات المضمّن memory-core لمساعدات المدير/التكوين/الملف/CLI |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | واجهة وقت تشغيل فهرسة/بحث الذاكرة |
|
||||
| `plugin-sdk/memory-core` | واجهة المساعدة المضمنة memory-core لمساعدات المدير/الإعدادات/الملفات/CLI |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | واجهة وقت التشغيل للفهرسة/البحث الخاصة بالذاكرة |
|
||||
| `plugin-sdk/memory-core-host-engine-foundation` | تصديرات محرك الأساس لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | عقود embeddings الخاصة بمضيف الذاكرة، والوصول إلى السجل، والمزوّد المحلي، والمساعدات العامة للدفعات/البعيد |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | عقود تضمين مضيف الذاكرة، والوصول إلى السجل، والموفّر المحلي، والمساعدات العامة للدفعات/عن بُعد |
|
||||
| `plugin-sdk/memory-core-host-engine-qmd` | تصديرات محرك QMD لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-core-host-engine-storage` | تصديرات محرك التخزين لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | مساعدات الوسائط المتعددة لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | مساعدات متعددة الوسائط لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-core-host-query` | مساعدات الاستعلام لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-core-host-secret` | مساعدات الأسرار لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-core-host-events` | مساعدات دفتر يوميات الأحداث لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-core-host-status` | مساعدات الحالة لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-core-host-events` | مساعدات سجل أحداث مضيف الذاكرة |
|
||||
| `plugin-sdk/memory-core-host-status` | مساعدات حالة مضيف الذاكرة |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | مساعدات وقت تشغيل CLI لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | مساعدات وقت التشغيل الأساسية لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | مساعدات الملفات/وقت التشغيل لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-host-core` | اسم مستعار محايد للبائع لمساعدات وقت التشغيل الأساسية لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-host-events` | اسم مستعار محايد للبائع لمساعدات دفتر يوميات الأحداث لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-host-files` | اسم مستعار محايد للبائع لمساعدات الملفات/وقت التشغيل لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-host-markdown` | مساعدات managed-markdown المشتركة للplugins المجاورة للذاكرة |
|
||||
| `plugin-sdk/memory-host-search` | واجهة وقت تشغيل Active Memory للوصول إلى مدير البحث |
|
||||
| `plugin-sdk/memory-host-status` | اسم مستعار محايد للبائع لمساعدات الحالة لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-lancedb` | سطح المساعدات المضمّن memory-lancedb |
|
||||
| `plugin-sdk/memory-host-core` | اسم بديل محايد للمورّد لمساعدات وقت التشغيل الأساسية لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-host-events` | اسم بديل محايد للمورّد لمساعدات سجل أحداث مضيف الذاكرة |
|
||||
| `plugin-sdk/memory-host-files` | اسم بديل محايد للمورّد لمساعدات ملفات/وقت تشغيل مضيف الذاكرة |
|
||||
| `plugin-sdk/memory-host-markdown` | مساعدات managed-markdown مشتركة للـ Plugins المجاورة للذاكرة |
|
||||
| `plugin-sdk/memory-host-search` | واجهة Active Memory لوقت التشغيل للوصول إلى مدير البحث |
|
||||
| `plugin-sdk/memory-host-status` | اسم بديل محايد للمورّد لمساعدات حالة مضيف الذاكرة |
|
||||
| `plugin-sdk/memory-lancedb` | واجهة المساعدة المضمنة memory-lancedb |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="المسارات الفرعية المحجوزة للمساعدات المضمّنة">
|
||||
| العائلة | المسارات الفرعية الحالية | الاستخدام المقصود |
|
||||
<Accordion title="المسارات الفرعية المساعدة المضمنة المحجوزة">
|
||||
| الفئة | المسارات الفرعية الحالية | الاستخدام المقصود |
|
||||
| --- | --- | --- |
|
||||
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | مساعدات دعم Browser plugin المضمّن (`browser-support` يظل ملف التوافق) |
|
||||
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | سطح المساعدات/وقت التشغيل المضمّن لـ Matrix |
|
||||
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | سطح المساعدات/وقت التشغيل المضمّن لـ LINE |
|
||||
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | سطح المساعدات المضمّن لـ IRC |
|
||||
| مساعدات خاصة بالقنوات | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | seams التوافق/المساعدات الخاصة بالقنوات المضمّنة |
|
||||
| مساعدات خاصة بالمصادقة/الplugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | seams مساعدات الميزات/الplugins المضمّنة؛ يصدّر `plugin-sdk/github-copilot-token` حاليًا `DEFAULT_COPILOT_API_BASE_URL` و`deriveCopilotApiBaseUrlFromToken` و`resolveCopilotApiToken` |
|
||||
| المتصفح | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | مساعدات دعم Plugin المتصفح المضمنة (`browser-support` تبقى حاوية التوافق) |
|
||||
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | واجهة المساعدة/وقت التشغيل المضمنة لـ Matrix |
|
||||
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | واجهة المساعدة/وقت التشغيل المضمنة لـ LINE |
|
||||
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | واجهة المساعدة المضمنة لـ IRC |
|
||||
| مساعدات خاصة بالقنوات | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | واجهات التوافق/المساعدة المضمنة الخاصة بالقنوات |
|
||||
| مساعدات خاصة بالمصادقة/Plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | واجهات المساعدة المضمنة للميزات/Plugins؛ ويصدر `plugin-sdk/github-copilot-token` حاليًا `DEFAULT_COPILOT_API_BASE_URL` و`deriveCopilotApiBaseUrlFromToken` و`resolveCopilotApiToken` |
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## واجهة API للتسجيل
|
||||
## API التسجيل
|
||||
|
||||
تتلقى دالة callback `register(api)` كائن `OpenClawPluginApi` بهذه
|
||||
يتلقى رد النداء `register(api)` كائن `OpenClawPluginApi` بهذه
|
||||
الأساليب:
|
||||
|
||||
### تسجيل القدرات
|
||||
|
||||
| الأسلوب | ما الذي يسجّله |
|
||||
| الأسلوب | ما الذي يسجله |
|
||||
| ------------------------------------------------ | ------------------------------------- |
|
||||
| `api.registerProvider(...)` | الاستدلال النصي (LLM) |
|
||||
| `api.registerAgentHarness(...)` | منفّذ وكيل منخفض المستوى تجريبي |
|
||||
| `api.registerCliBackend(...)` | خلفية استدلال CLI محلية |
|
||||
| `api.registerChannel(...)` | قناة مراسلة |
|
||||
| `api.registerSpeechProvider(...)` | تحويل النص إلى كلام / توليف STT |
|
||||
| `api.registerRealtimeTranscriptionProvider(...)` | نسخ فوري متدفق |
|
||||
| `api.registerRealtimeVoiceProvider(...)` | جلسات صوتية فورية ثنائية الاتجاه |
|
||||
| `api.registerMediaUnderstandingProvider(...)` | تحليل الصور/الصوت/الفيديو |
|
||||
| `api.registerImageGenerationProvider(...)` | توليد الصور |
|
||||
| `api.registerMusicGenerationProvider(...)` | توليد الموسيقى |
|
||||
| `api.registerVideoGenerationProvider(...)` | توليد الفيديو |
|
||||
| `api.registerWebFetchProvider(...)` | مزوّد Web fetch / scrape |
|
||||
| `api.registerWebSearchProvider(...)` | بحث الويب |
|
||||
| `api.registerProvider(...)` | الاستدلال النصي (LLM) |
|
||||
| `api.registerAgentHarness(...)` | منفذ عامل منخفض المستوى تجريبي |
|
||||
| `api.registerCliBackend(...)` | واجهة خلفية محلية للاستدلال في CLI |
|
||||
| `api.registerChannel(...)` | قناة مراسلة |
|
||||
| `api.registerSpeechProvider(...)` | تحويل النص إلى كلام / توليف STT |
|
||||
| `api.registerRealtimeTranscriptionProvider(...)` | نسخ فوري متدفق |
|
||||
| `api.registerRealtimeVoiceProvider(...)` | جلسات صوتية فورية ثنائية الاتجاه |
|
||||
| `api.registerMediaUnderstandingProvider(...)` | تحليل الصور/الصوت/الفيديو |
|
||||
| `api.registerImageGenerationProvider(...)` | توليد الصور |
|
||||
| `api.registerMusicGenerationProvider(...)` | توليد الموسيقى |
|
||||
| `api.registerVideoGenerationProvider(...)` | توليد الفيديو |
|
||||
| `api.registerWebFetchProvider(...)` | موفّر جلب / كشط الويب |
|
||||
| `api.registerWebSearchProvider(...)` | البحث على الويب |
|
||||
|
||||
### الأدوات والأوامر
|
||||
|
||||
| الأسلوب | ما الذي يسجّله |
|
||||
| ------------------------------- | --------------------------------------------- |
|
||||
| `api.registerTool(tool, opts?)` | أداة وكيل (مطلوبة أو `{ optional: true }`) |
|
||||
| `api.registerCommand(def)` | أمر مخصص (يتجاوز LLM) |
|
||||
| الأسلوب | ما الذي يسجله |
|
||||
| ----------------------------- | ---------------------------------------------- |
|
||||
| `api.registerTool(tool, opts?)` | أداة عامل (مطلوبة أو `{ optional: true }`) |
|
||||
| `api.registerCommand(def)` | أمر مخصص (يتجاوز LLM) |
|
||||
|
||||
### البنية التحتية
|
||||
|
||||
| الأسلوب | ما الذي يسجّله |
|
||||
| ---------------------------------------------- | --------------------------------------- |
|
||||
| `api.registerHook(events, handler, opts?)` | hook حدث |
|
||||
| `api.registerHttpRoute(params)` | نقطة نهاية HTTP في Gateway |
|
||||
| `api.registerGatewayMethod(name, handler)` | أسلوب RPC في Gateway |
|
||||
| `api.registerCli(registrar, opts?)` | أمر فرعي في CLI |
|
||||
| `api.registerService(service)` | خدمة خلفية |
|
||||
| `api.registerInteractiveHandler(registration)` | معالج تفاعلي |
|
||||
| `api.registerMemoryPromptSupplement(builder)` | قسم prompt إضافي مجاور للذاكرة |
|
||||
| `api.registerMemoryCorpusSupplement(adapter)` | corpus إضافي لبحث/قراءة الذاكرة |
|
||||
| الأسلوب | ما الذي يسجله |
|
||||
| ----------------------------------------------- | ------------------------------------ |
|
||||
| `api.registerHook(events, handler, opts?)` | خطاف أحداث |
|
||||
| `api.registerHttpRoute(params)` | نقطة نهاية HTTP في Gateway |
|
||||
| `api.registerGatewayMethod(name, handler)` | أسلوب RPC في Gateway |
|
||||
| `api.registerCli(registrar, opts?)` | أمر فرعي في CLI |
|
||||
| `api.registerService(service)` | خدمة في الخلفية |
|
||||
| `api.registerInteractiveHandler(registration)` | معالج تفاعلي |
|
||||
| `api.registerEmbeddedExtensionFactory(factory)` | مصنع امتداد المشغّل المضمن في Pi |
|
||||
| `api.registerMemoryPromptSupplement(builder)` | قسم إضافي للمطالبة مجاور للذاكرة |
|
||||
| `api.registerMemoryCorpusSupplement(adapter)` | متن إضافي للبحث/القراءة في الذاكرة |
|
||||
|
||||
تظل مساحات أسماء الإدارة الأساسية المحجوزة (`config.*` و`exec.approvals.*` و`wizard.*`،
|
||||
و`update.*`) دائمًا ضمن `operator.admin`، حتى لو حاول plugin تعيين
|
||||
نطاق أضيق لأسلوب gateway. وفضّل البوادئ الخاصة بالplugin من أجل
|
||||
الأساليب المملوكة لـ plugin.
|
||||
تظل مساحات الأسماء الإدارية الأساسية المحجوزة (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
`update.*`) دائمًا `operator.admin`، حتى إذا حاول Plugin تعيين
|
||||
نطاق أضيق لأسلوب Gateway. ويفضَّل استخدام بادئات خاصة بالـ plugin
|
||||
للأساليب التي يملكها plugin.
|
||||
|
||||
### بيانات تسجيل CLI الوصفية
|
||||
استخدم `api.registerEmbeddedExtensionFactory(...)` عندما يحتاج Plugin إلى
|
||||
توقيت أحداث أصلي خاص بـ Pi أثناء التشغيلات المضمنة لـ OpenClaw، مثل إعادة كتابة
|
||||
`tool_result` غير المتزامنة التي يجب أن تحدث قبل إصدار رسالة النتيجة النهائية للأداة.
|
||||
هذه واجهة bundled-plugin اليوم: لا يمكن إلا للـ Plugins المضمنة تسجيل واحدة، ويجب
|
||||
أن تعلن `contracts.embeddedExtensionFactories: ["pi"]` في
|
||||
`openclaw.plugin.json`. واحتفظ بخطافات Plugin العادية في OpenClaw لكل ما
|
||||
لا يتطلب هذه الواجهة منخفضة المستوى.
|
||||
|
||||
يقبل `api.registerCli(registrar, opts?)` نوعين من البيانات الوصفية ذات المستوى الأعلى:
|
||||
### بيانات تعريف تسجيل CLI
|
||||
|
||||
- `commands`: جذور أوامر صريحة يملكها المسجل
|
||||
- `descriptors`: واصفات أوامر وقت التحليل المستخدمة من أجل مساعدة CLI الجذرية،
|
||||
والتوجيه، وتسجيل CLI الكسول للplugin
|
||||
يقبل `api.registerCli(registrar, opts?)` نوعين من بيانات التعريف العليا:
|
||||
|
||||
إذا كنت تريد أن يظل أمر plugin محمّلًا بكسل في مسار CLI الجذري العادي،
|
||||
فقدّم `descriptors` تغطي كل جذر أمر من المستوى الأعلى يكشفه هذا
|
||||
المسجل.
|
||||
- `commands`: جذور أوامر صريحة يملكها المسجِّل
|
||||
- `descriptors`: واصفات أوامر وقت التحليل المستخدمة لمساعدة CLI الجذرية،
|
||||
والتوجيه، وتسجيل CLI الكسول للـ plugin
|
||||
|
||||
إذا كنت تريد أن يبقى أمر plugin محمّلًا كسولًا في المسار الجذري العادي لـ CLI،
|
||||
فقدّم `descriptors` تغطي كل جذر أوامر من المستوى الأعلى يكشفه
|
||||
ذلك المسجِّل.
|
||||
|
||||
```typescript
|
||||
api.registerCli(
|
||||
@ -387,7 +396,7 @@ api.registerCli(
|
||||
descriptors: [
|
||||
{
|
||||
name: "matrix",
|
||||
description: "إدارة حسابات Matrix، والتحقق، والأجهزة، وحالة الملف الشخصي",
|
||||
description: "إدارة حسابات Matrix والتحقق والأجهزة وحالة الملف الشخصي",
|
||||
hasSubcommands: true,
|
||||
},
|
||||
],
|
||||
@ -396,133 +405,133 @@ api.registerCli(
|
||||
```
|
||||
|
||||
استخدم `commands` وحده فقط عندما لا تحتاج إلى تسجيل CLI جذري كسول.
|
||||
ما يزال مسار التوافق الفوري هذا مدعومًا، لكنه لا يثبت
|
||||
عناصر نائبة مدعومة بـ descriptor من أجل التحميل الكسول وقت التحليل.
|
||||
لا يزال مسار التوافق المتحمّس هذا مدعومًا، لكنه لا يثبت
|
||||
عناصر نائبة مدعومة بالواصفات للتحميل الكسول وقت التحليل.
|
||||
|
||||
### تسجيل خلفية CLI
|
||||
### تسجيل الواجهة الخلفية لـ CLI
|
||||
|
||||
يتيح `api.registerCliBackend(...)` لـ plugin امتلاك التكوين الافتراضي لخلفية
|
||||
CLI محلية للذكاء الاصطناعي مثل `codex-cli`.
|
||||
يتيح `api.registerCliBackend(...)` لPlugin امتلاك الإعداد الافتراضي لواجهة
|
||||
خلفية محلية لـ CLI خاصة بالذكاء الاصطناعي مثل `codex-cli`.
|
||||
|
||||
- يصبح `id` الخاص بالخلفية بادئة المزوّد في مراجع النماذج مثل `codex-cli/gpt-5`.
|
||||
- يستخدم `config` الخاص بالخلفية البنية نفسها لـ `agents.defaults.cliBackends.<id>`.
|
||||
- يظل تكوين المستخدم هو الفائز. يدمج OpenClaw القيمة `agents.defaults.cliBackends.<id>` فوق
|
||||
القيمة الافتراضية للplugin قبل تشغيل CLI.
|
||||
- استخدم `normalizeConfig` عندما تحتاج الخلفية إلى عمليات إعادة كتابة توافقية بعد الدمج
|
||||
(على سبيل المثال، تطبيع أشكال العلامات القديمة).
|
||||
- يصبح `id` الخاص بالواجهة الخلفية هو بادئة الموفّر في مراجع النماذج مثل `codex-cli/gpt-5`.
|
||||
- يستخدم `config` الخاص بالواجهة الخلفية البنية نفسها المستخدمة في `agents.defaults.cliBackends.<id>`.
|
||||
- يظل إعداد المستخدم هو الأعلى أولوية. يدمج OpenClaw `agents.defaults.cliBackends.<id>` فوق
|
||||
الإعداد الافتراضي للـ plugin قبل تشغيل CLI.
|
||||
- استخدم `normalizeConfig` عندما تحتاج واجهة خلفية إلى إعادة كتابة للتوافق بعد الدمج
|
||||
(مثل تطبيع أشكال الرايات القديمة).
|
||||
|
||||
### المنافذ الحصرية
|
||||
### الفتحات الحصرية
|
||||
|
||||
| الأسلوب | ما الذي يسجّله |
|
||||
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `api.registerContextEngine(id, factory)` | محرك السياق (واحد نشط في كل مرة). تتلقى دالة callback `assemble()` القيمتين `availableTools` و`citationsMode` بحيث يمكن للمحرك تخصيص الإضافات إلى prompt. |
|
||||
| `api.registerMemoryCapability(capability)` | قدرة ذاكرة موحّدة |
|
||||
| `api.registerMemoryPromptSection(builder)` | باني قسم prompt للذاكرة |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | محلّل خطة flush للذاكرة |
|
||||
| `api.registerMemoryRuntime(runtime)` | مهايئ وقت تشغيل الذاكرة |
|
||||
| الأسلوب | ما الذي يسجله |
|
||||
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `api.registerContextEngine(id, factory)` | محرك سياق (واحد نشط في كل مرة). يتلقى رد النداء `assemble()` كلًا من `availableTools` و`citationsMode` حتى يتمكن المحرك من تخصيص إضافات المطالبة. |
|
||||
| `api.registerMemoryCapability(capability)` | قدرة ذاكرة موحدة |
|
||||
| `api.registerMemoryPromptSection(builder)` | باني قسم مطالبة الذاكرة |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | محلل خطة تفريغ الذاكرة |
|
||||
| `api.registerMemoryRuntime(runtime)` | مهايئ وقت تشغيل الذاكرة |
|
||||
|
||||
### مهايئات embedding الخاصة بالذاكرة
|
||||
### مهايئات تضمين الذاكرة
|
||||
|
||||
| الأسلوب | ما الذي يسجّله |
|
||||
| ---------------------------------------------- | ---------------------------------------------- |
|
||||
| `api.registerMemoryEmbeddingProvider(adapter)` | مهايئ embedding للذاكرة من أجل plugin النشط |
|
||||
| الأسلوب | ما الذي يسجله |
|
||||
| --------------------------------------------- | ---------------------------------------------- |
|
||||
| `api.registerMemoryEmbeddingProvider(adapter)` | مهايئ تضمين الذاكرة الخاص بالـ plugin النشط |
|
||||
|
||||
- تُعد `registerMemoryCapability` واجهة API الحصرية المفضلة لـ plugin الذاكرة.
|
||||
- قد تكشف `registerMemoryCapability` أيضًا عن `publicArtifacts.listArtifacts(...)`
|
||||
بحيث تتمكن plugins المصاحبة من استهلاك عناصر الذاكرة المُصدّرة عبر
|
||||
`openclaw/plugin-sdk/memory-host-core` بدلًا من الوصول إلى التخطيط الخاص
|
||||
الداخلي لـ plugin ذاكرة محدد.
|
||||
- يُعد `registerMemoryCapability` هو API المفضل والحصري لـ plugin الذاكرة.
|
||||
- قد يكشف `registerMemoryCapability` أيضًا عن `publicArtifacts.listArtifacts(...)`
|
||||
حتى تتمكن Plugins المصاحبة من استهلاك عناصر الذاكرة المصدّرة عبر
|
||||
`openclaw/plugin-sdk/memory-host-core` بدلًا من الوصول إلى
|
||||
التخطيط الخاص الداخلي لـ plugin ذاكرة معيّن.
|
||||
- تُعد `registerMemoryPromptSection` و`registerMemoryFlushPlan` و
|
||||
`registerMemoryRuntime` واجهات API حصرية متوافقة مع الإصدارات القديمة لـ plugins الذاكرة.
|
||||
- تتيح `registerMemoryEmbeddingProvider` لـ plugin الذاكرة النشط تسجيل
|
||||
معرّف embedding واحد أو أكثر (على سبيل المثال `openai` أو `gemini` أو
|
||||
معرّف مخصص يحدده plugin).
|
||||
- يتم حل تكوين المستخدم مثل `agents.defaults.memorySearch.provider` و
|
||||
`registerMemoryRuntime` واجهات API حصرية ومتوافقة مع القديم لـ plugin الذاكرة.
|
||||
- يتيح `registerMemoryEmbeddingProvider` لـ plugin الذاكرة النشط تسجيل
|
||||
معرّف مهايئ تضمين واحد أو أكثر (مثل `openai` أو `gemini` أو معرّف مخصص
|
||||
يعرّفه plugin).
|
||||
- تُحل إعدادات المستخدم مثل `agents.defaults.memorySearch.provider` و
|
||||
`agents.defaults.memorySearch.fallback` مقابل معرّفات المهايئات المسجلة تلك.
|
||||
|
||||
### الأحداث ودورة الحياة
|
||||
|
||||
| الأسلوب | ما الذي يفعله |
|
||||
| الأسلوب | ما الذي يفعله |
|
||||
| -------------------------------------------- | ----------------------------- |
|
||||
| `api.on(hookName, handler, opts?)` | hook دورة حياة مطبّع |
|
||||
| `api.onConversationBindingResolved(handler)` | callback لحل ارتباط المحادثة |
|
||||
| `api.on(hookName, handler, opts?)` | خطاف دورة حياة مطبوع |
|
||||
| `api.onConversationBindingResolved(handler)` | رد نداء لحل ربط المحادثة |
|
||||
|
||||
### دلالات قرارات hook
|
||||
### دلالات قرارات الخطافات
|
||||
|
||||
- `before_tool_call`: تؤدي إعادة `{ block: true }` إلى قرار نهائي. وبمجرد أن يعيّن أي معالج هذه القيمة، يتم تخطي المعالجات ذات الأولوية الأقل.
|
||||
- `before_tool_call`: تُعامل إعادة `{ block: false }` على أنها عدم وجود قرار (مثلها مثل حذف `block`)، وليس كتجاوز.
|
||||
- `before_install`: تؤدي إعادة `{ block: true }` إلى قرار نهائي. وبمجرد أن يعيّن أي معالج هذه القيمة، يتم تخطي المعالجات ذات الأولوية الأقل.
|
||||
- `before_install`: تُعامل إعادة `{ block: false }` على أنها عدم وجود قرار (مثلها مثل حذف `block`)، وليس كتجاوز.
|
||||
- `reply_dispatch`: تؤدي إعادة `{ handled: true, ... }` إلى قرار نهائي. وبمجرد أن يدّعي أي معالج التوزيع، يتم تخطي المعالجات ذات الأولوية الأقل ومسار توزيع النموذج الافتراضي.
|
||||
- `message_sending`: تؤدي إعادة `{ cancel: true }` إلى قرار نهائي. وبمجرد أن يعيّن أي معالج هذه القيمة، يتم تخطي المعالجات ذات الأولوية الأقل.
|
||||
- `message_sending`: تُعامل إعادة `{ cancel: false }` على أنها عدم وجود قرار (مثلها مثل حذف `cancel`)، وليس كتجاوز.
|
||||
- `before_tool_call`: تُعد إعادة `{ block: true }` نهائية. وبمجرد أن يعيّنها أي معالج، يتم تخطي المعالجات ذات الأولوية الأقل.
|
||||
- `before_tool_call`: تُعامل إعادة `{ block: false }` على أنها عدم وجود قرار (مثل حذف `block`)، وليس على أنها تجاوز.
|
||||
- `before_install`: تُعد إعادة `{ block: true }` نهائية. وبمجرد أن يعيّنها أي معالج، يتم تخطي المعالجات ذات الأولوية الأقل.
|
||||
- `before_install`: تُعامل إعادة `{ block: false }` على أنها عدم وجود قرار (مثل حذف `block`)، وليس على أنها تجاوز.
|
||||
- `reply_dispatch`: تُعد إعادة `{ handled: true, ... }` نهائية. وبمجرد أن يطالب أي معالج بالإرسال، يتم تخطي المعالجات ذات الأولوية الأقل ومسار الإرسال الافتراضي للنموذج.
|
||||
- `message_sending`: تُعد إعادة `{ cancel: true }` نهائية. وبمجرد أن يعيّنها أي معالج، يتم تخطي المعالجات ذات الأولوية الأقل.
|
||||
- `message_sending`: تُعامل إعادة `{ cancel: false }` على أنها عدم وجود قرار (مثل حذف `cancel`)، وليس على أنها تجاوز.
|
||||
|
||||
### حقول كائن API
|
||||
|
||||
| الحقل | النوع | الوصف |
|
||||
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `api.id` | `string` | معرّف plugin |
|
||||
| `api.name` | `string` | اسم العرض |
|
||||
| `api.version` | `string?` | إصدار plugin (اختياري) |
|
||||
| `api.description` | `string?` | وصف plugin (اختياري) |
|
||||
| `api.source` | `string` | مسار مصدر plugin |
|
||||
| `api.rootDir` | `string?` | الدليل الجذري لـ plugin (اختياري) |
|
||||
| `api.config` | `OpenClawConfig` | snapshot التكوين الحالي (snapshot وقت التشغيل النشط في الذاكرة عند توفره) |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | التكوين الخاص بـ plugin من `plugins.entries.<id>.config` |
|
||||
| `api.runtime` | `PluginRuntime` | [مساعدات وقت التشغيل](/ar/plugins/sdk-runtime) |
|
||||
| `api.logger` | `PluginLogger` | logger ضمن النطاق (`debug` و`info` و`warn` و`error`) |
|
||||
| `api.registrationMode` | `PluginRegistrationMode` | وضع التحميل الحالي؛ وتمثل `"setup-runtime"` نافذة بدء التشغيل/الإعداد الخفيفة قبل الإدخال الكامل |
|
||||
| `api.resolvePath(input)` | `(string) => string` | حل المسار نسبةً إلى جذر plugin |
|
||||
| الحقل | النوع | الوصف |
|
||||
| ----------------------- | ------------------------- | ----------------------------------------------------------------------------------------- |
|
||||
| `api.id` | `string` | معرّف Plugin |
|
||||
| `api.name` | `string` | اسم العرض |
|
||||
| `api.version` | `string?` | إصدار Plugin (اختياري) |
|
||||
| `api.description` | `string?` | وصف Plugin (اختياري) |
|
||||
| `api.source` | `string` | مسار مصدر Plugin |
|
||||
| `api.rootDir` | `string?` | الدليل الجذري لـ Plugin (اختياري) |
|
||||
| `api.config` | `OpenClawConfig` | لقطة الإعدادات الحالية (لقطة وقت تشغيل نشطة داخل الذاكرة عند توفرها) |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | إعدادات خاصة بـ Plugin من `plugins.entries.<id>.config` |
|
||||
| `api.runtime` | `PluginRuntime` | [مساعدات وقت التشغيل](/ar/plugins/sdk-runtime) |
|
||||
| `api.logger` | `PluginLogger` | مسجل ذو نطاق محدد (`debug`, `info`, `warn`, `error`) |
|
||||
| `api.registrationMode` | `PluginRegistrationMode` | وضع التحميل الحالي؛ ويمثل `"setup-runtime"` نافذة بدء التشغيل/الإعداد الخفيفة قبل الإدخال الكامل |
|
||||
| `api.resolvePath(input)` | `(string) => string` | حل المسار نسبةً إلى جذر Plugin |
|
||||
|
||||
## اصطلاح الوحدات الداخلية
|
||||
|
||||
داخل plugin الخاص بك، استخدم ملفات barrel محلية للاستيرادات الداخلية:
|
||||
داخل Plugin الخاص بك، استخدم ملفات الحاوية المحلية للاستيرادات الداخلية:
|
||||
|
||||
```
|
||||
my-plugin/
|
||||
api.ts # تصديرات عامة للمستهلكين الخارجيين
|
||||
runtime-api.ts # تصديرات وقت تشغيل داخلية فقط
|
||||
index.ts # نقطة إدخال plugin
|
||||
setup-entry.ts # إدخال خفيف خاص بالإعداد فقط (اختياري)
|
||||
api.ts # التصديرات العامة للمستهلكين الخارجيين
|
||||
runtime-api.ts # تصديرات وقت التشغيل الداخلية فقط
|
||||
index.ts # نقطة إدخال Plugin
|
||||
setup-entry.ts # إدخال خفيف للإعداد فقط (اختياري)
|
||||
```
|
||||
|
||||
<Warning>
|
||||
لا تستورد plugin الخاص بك أبدًا عبر `openclaw/plugin-sdk/<your-plugin>`
|
||||
لا تستورد Plugin الخاص بك عبر `openclaw/plugin-sdk/<your-plugin>`
|
||||
من كود الإنتاج. وجّه الاستيرادات الداخلية عبر `./api.ts` أو
|
||||
`./runtime-api.ts`. فمسار SDK هو العقد الخارجي فقط.
|
||||
`./runtime-api.ts`. مسار SDK هو العقد الخارجي فقط.
|
||||
</Warning>
|
||||
|
||||
تفضّل الآن الأسطح العامة للplugins المضمّنة المحمّلة عبر الواجهة (`api.ts` و`runtime-api.ts`،
|
||||
و`index.ts`، و`setup-entry.ts`، وملفات الإدخال العامة المماثلة)
|
||||
snapshot التكوين النشط لوقت التشغيل عندما يكون OpenClaw قيد التشغيل بالفعل. وإذا لم توجد
|
||||
snapshot لوقت التشغيل بعد، فإنها تعود إلى ملف التكوين المحلول على القرص.
|
||||
تفضّل الآن الأسطح العامة للـ bundled plugin المحمّلة عبر الواجهة (`api.ts`, `runtime-api.ts`,
|
||||
`index.ts`, `setup-entry.ts`، وملفات الإدخال العامة المشابهة)
|
||||
لقطة إعدادات وقت التشغيل النشطة عندما يكون OpenClaw قيد التشغيل بالفعل. وإذا لم تكن
|
||||
لقطة وقت التشغيل موجودة بعد، فإنها تعود إلى ملف الإعدادات المحلول على القرص.
|
||||
|
||||
يمكن لplugins المزوّدين أيضًا كشف barrel عقد محلي ضيق خاص بالplugin عندما تكون مساعدة ما
|
||||
مقصودة بوصفها خاصة بالمزوّد ولا تنتمي بعد إلى مسار فرعي عام في SDK.
|
||||
المثال المضمّن الحالي: يحتفظ مزوّد Anthropic بمساعدات Claude stream الخاصة به
|
||||
داخل seam عام خاص به في `api.ts` / `contract-api.ts` بدلًا من
|
||||
ترقية منطق رؤوس Anthropic beta و`service_tier` إلى عقد عام
|
||||
`plugin-sdk/*`.
|
||||
يمكن أيضًا لـ provider plugins كشف حاوية عقد محلية خاصة بالـ plugin عندما يكون
|
||||
المساعد خاصًا عمدًا بالموفّر ولا ينتمي بعد إلى مسار فرعي عام في SDK.
|
||||
المثال المضمن الحالي: يحتفظ موفّر Anthropic
|
||||
بمساعدات تدفق Claude في الواجهة العامة الخاصة به `api.ts` / `contract-api.ts`
|
||||
بدلًا من ترقية منطق رأس Anthropic التجريبي و`service_tier` إلى
|
||||
عقد عام في `plugin-sdk/*`.
|
||||
|
||||
أمثلة مضمّنة حالية أخرى:
|
||||
أمثلة مضمنة حالية أخرى:
|
||||
|
||||
- `@openclaw/openai-provider`: يصدّر `api.ts` بُناة المزوّد،
|
||||
ومساعدات النموذج الافتراضي، وبُناة المزوّد الفوري
|
||||
- `@openclaw/openrouter-provider`: يصدّر `api.ts` باني المزوّد بالإضافة إلى
|
||||
مساعدات الإعداد الأولي/التكوين
|
||||
- `@openclaw/openai-provider`: يصدّر `api.ts` بُناة الموفّر،
|
||||
ومساعدات النموذج الافتراضي، وبُناة الموفّر الفوري
|
||||
- `@openclaw/openrouter-provider`: يصدّر `api.ts` باني الموفّر بالإضافة إلى
|
||||
مساعدات التهيئة/الإعدادات
|
||||
|
||||
<Warning>
|
||||
يجب أن يتجنب كود الإنتاج الخاص بالامتداد أيضًا استيراد
|
||||
`openclaw/plugin-sdk/<other-plugin>`. وإذا كانت المساعدة مشتركة فعلًا، فقم بترقيتها إلى مسار فرعي
|
||||
محايد في SDK مثل `openclaw/plugin-sdk/speech` أو `.../provider-model-shared` أو سطح آخر
|
||||
موجّه بالقدرات بدلًا من ربط pluginين معًا.
|
||||
يجب أيضًا على كود إنتاج الامتدادات تجنب استيرادات `openclaw/plugin-sdk/<other-plugin>`.
|
||||
وإذا كان أحد المساعدات مشتركًا فعلًا، فقم بترقيته إلى مسار فرعي محايد في SDK
|
||||
مثل `openclaw/plugin-sdk/speech` أو `.../provider-model-shared` أو أي
|
||||
واجهة أخرى موجهة حسب القدرة بدلًا من ربط Plugins اثنين معًا.
|
||||
</Warning>
|
||||
|
||||
## ذو صلة
|
||||
|
||||
- [نقاط الإدخال](/ar/plugins/sdk-entrypoints) — خيارات `definePluginEntry` و`defineChannelPluginEntry`
|
||||
- [مساعدات وقت التشغيل](/ar/plugins/sdk-runtime) — المرجع الكامل لمساحة الأسماء `api.runtime`
|
||||
- [الإعداد والتكوين](/ar/plugins/sdk-setup) — التغليف، وmanifests، ومخططات التكوين
|
||||
- [الاختبار](/ar/plugins/sdk-testing) — أدوات الاختبار وقواعد lint
|
||||
- [ترحيل SDK](/ar/plugins/sdk-migration) — الترحيل من الأسطح المهجورة
|
||||
- [الأجزاء الداخلية لـ Plugin](/ar/plugins/architecture) — البنية العميقة ونموذج القدرات
|
||||
- [Entry Points](/ar/plugins/sdk-entrypoints) — خيارات `definePluginEntry` و`defineChannelPluginEntry`
|
||||
- [Runtime Helpers](/ar/plugins/sdk-runtime) — مرجع كامل لمساحة الأسماء `api.runtime`
|
||||
- [Setup and Config](/ar/plugins/sdk-setup) — التغليف، والبيانات الوصفية، ومخططات الإعدادات
|
||||
- [Testing](/ar/plugins/sdk-testing) — أدوات الاختبار وقواعد lint
|
||||
- [SDK Migration](/ar/plugins/sdk-migration) — الترحيل من الأسطح المتقادمة
|
||||
- [Plugin Internals](/ar/plugins/architecture) — البنية العميقة ونموذج القدرات
|
||||
|
||||
@ -1,25 +1,25 @@
|
||||
---
|
||||
read_when:
|
||||
- أنت تريد تشغيل OpenClaw مع نماذج سحابية أو محلية عبر Ollama
|
||||
- أنت تحتاج إلى إرشادات إعداد وتهيئة Ollama
|
||||
- أنت تريد نماذج رؤية من Ollama لفهم الصور
|
||||
- تريد تشغيل OpenClaw مع نماذج سحابية أو محلية عبر Ollama
|
||||
- تحتاج إلى إرشادات إعداد Ollama وتهيئته
|
||||
- تريد نماذج رؤية من Ollama لفهم الصور
|
||||
summary: شغّل OpenClaw مع Ollama (النماذج السحابية والمحلية)
|
||||
title: Ollama
|
||||
x-i18n:
|
||||
generated_at: "2026-04-22T04:28:06Z"
|
||||
generated_at: "2026-04-22T07:18:40Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 32623b6523f22930a5987fb22d2074f1e9bb274cc01ae1ad1837825cc04ec179
|
||||
source_hash: 704beed3bf988d6c2ad50b2a1533f6dcef655e44b34f23104827d2acb71b8655
|
||||
source_path: providers/ollama.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Ollama
|
||||
|
||||
يتكامل OpenClaw مع API الأصلية لـ Ollama (`/_api/chat`) للنماذج السحابية المستضافة وخوادم Ollama المحلية/المستضافة ذاتيًا. يمكنك استخدام Ollama بثلاثة أوضاع: `Cloud + Local` عبر مضيف Ollama يمكن الوصول إليه، أو `Cloud only` مقابل `https://ollama.com`، أو `Local only` مقابل مضيف Ollama يمكن الوصول إليه.
|
||||
يتكامل OpenClaw مع واجهة API الأصلية الخاصة بـ Ollama (`/api/chat`) للنماذج السحابية المستضافة وخوادم Ollama المحلية/المستضافة ذاتيًا. يمكنك استخدام Ollama في ثلاثة أوضاع: `Cloud + Local` عبر مضيف Ollama يمكن الوصول إليه، أو `Cloud only` مقابل `https://ollama.com`، أو `Local only` مقابل مضيف Ollama يمكن الوصول إليه.
|
||||
|
||||
<Warning>
|
||||
**مستخدمو Ollama البعيدون**: لا تستخدم عنوان URL المتوافق مع OpenAI من نوع `/v1` (`http://host:11434/v1`) مع OpenClaw. فهذا يعطل استدعاء الأدوات وقد تُخرج النماذج JSON الأدوات الخام كنص عادي. استخدم عنوان URL الخاص بـ API الأصلية لـ Ollama بدلًا من ذلك: `baseUrl: "http://host:11434"` (من دون `/v1`).
|
||||
**مستخدمو Ollama البعيد**: لا تستخدموا عنوان URL المتوافق مع OpenAI على `/v1` (`http://host:11434/v1`) مع OpenClaw. فهذا يعطّل استدعاء الأدوات وقد تُخرج النماذج JSON الأدوات الخام كنص عادي. استخدم عنوان URL الخاص بواجهة API الأصلية لـ Ollama بدلًا من ذلك: `baseUrl: "http://host:11434"` (من دون `/v1`).
|
||||
</Warning>
|
||||
|
||||
## البدء
|
||||
@ -27,24 +27,24 @@ x-i18n:
|
||||
اختر طريقة الإعداد والوضع المفضلين لديك.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Onboarding (موصى به)">
|
||||
**الأفضل من أجل:** أسرع طريق إلى إعداد Ollama سحابي أو محلي يعمل.
|
||||
<Tab title="الإعداد الأولي (موصى به)">
|
||||
**الأفضل لـ:** أسرع طريق إلى إعداد Ollama سحابي أو محلي يعمل.
|
||||
|
||||
<Steps>
|
||||
<Step title="شغّل onboarding">
|
||||
<Step title="تشغيل الإعداد الأولي">
|
||||
```bash
|
||||
openclaw onboard
|
||||
```
|
||||
|
||||
اختر **Ollama** من قائمة المزوّدين.
|
||||
اختر **Ollama** من قائمة الموفّرين.
|
||||
</Step>
|
||||
<Step title="اختر وضعك">
|
||||
- **Cloud + Local** — مضيف Ollama محلي بالإضافة إلى نماذج سحابية موجّهة عبر ذلك المضيف
|
||||
- **Cloud + Local** — مضيف Ollama محلي بالإضافة إلى نماذج سحابية تُوجَّه عبر ذلك المضيف
|
||||
- **Cloud only** — نماذج Ollama المستضافة عبر `https://ollama.com`
|
||||
- **Local only** — نماذج محلية فقط
|
||||
</Step>
|
||||
<Step title="اختر نموذجًا">
|
||||
يطلب `Cloud only` قيمة `OLLAMA_API_KEY` ويقترح القيم الافتراضية السحابية المستضافة. أما `Cloud + Local` و`Local only` فيطلبان عنوان URL الأساسي لـ Ollama، ويكتشفان النماذج المتاحة، ويسحبان النموذج المحلي المحدد تلقائيًا إذا لم يكن متاحًا بعد. ويتحقق `Cloud + Local` أيضًا مما إذا كان مضيف Ollama هذا قد سجّل الدخول للوصول السحابي.
|
||||
يطلب `Cloud only` قيمة `OLLAMA_API_KEY` ويقترح افتراضيات سحابية مستضافة. يطلب كل من `Cloud + Local` و`Local only` عنوان URL الأساسي لـ Ollama، ويكتشفان النماذج المتاحة، ويجريان سحبًا تلقائيًا للنموذج المحلي المحدد إذا لم يكن متاحًا بعد. كما يتحقق `Cloud + Local` أيضًا مما إذا كان مضيف Ollama هذا قد سجّل الدخول للوصول السحابي.
|
||||
</Step>
|
||||
<Step title="تحقق من أن النموذج متاح">
|
||||
```bash
|
||||
@ -61,7 +61,7 @@ x-i18n:
|
||||
--accept-risk
|
||||
```
|
||||
|
||||
ويمكنك اختياريًا تحديد عنوان URL أساسي مخصص أو نموذج:
|
||||
يمكنك اختياريًا تحديد عنوان URL أساسي مخصص أو نموذج:
|
||||
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
@ -73,8 +73,8 @@ x-i18n:
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="إعداد يدوي">
|
||||
**الأفضل من أجل:** تحكم كامل في الإعداد السحابي أو المحلي.
|
||||
<Tab title="الإعداد اليدوي">
|
||||
**الأفضل لـ:** تحكم كامل في الإعداد السحابي أو المحلي.
|
||||
|
||||
<Steps>
|
||||
<Step title="اختر السحابي أو المحلي">
|
||||
@ -82,7 +82,7 @@ x-i18n:
|
||||
- **Cloud only**: استخدم `https://ollama.com` مع `OLLAMA_API_KEY`
|
||||
- **Local only**: ثبّت Ollama من [ollama.com/download](https://ollama.com/download)
|
||||
</Step>
|
||||
<Step title="اسحب نموذجًا محليًا (Local only)">
|
||||
<Step title="اسحب نموذجًا محليًا (محلي فقط)">
|
||||
```bash
|
||||
ollama pull gemma4
|
||||
# أو
|
||||
@ -92,16 +92,16 @@ x-i18n:
|
||||
```
|
||||
</Step>
|
||||
<Step title="فعّل Ollama لـ OpenClaw">
|
||||
بالنسبة إلى `Cloud only`، استخدم `OLLAMA_API_KEY` الحقيقي. أما في الإعدادات المعتمدة على المضيف، فأي قيمة مكانية تعمل:
|
||||
بالنسبة إلى `Cloud only`، استخدم قيمة `OLLAMA_API_KEY` الحقيقية لديك. أما في الإعدادات المعتمدة على المضيف، فأي قيمة بديلة تعمل:
|
||||
|
||||
```bash
|
||||
# سحابي
|
||||
# السحابي
|
||||
export OLLAMA_API_KEY="your-ollama-api-key"
|
||||
|
||||
# محلي فقط
|
||||
# المحلي فقط
|
||||
export OLLAMA_API_KEY="ollama-local"
|
||||
|
||||
# أو اضبطه في ملف الإعدادات
|
||||
# أو اضبطه في ملف الإعداد
|
||||
openclaw config set models.providers.ollama.apiKey "OLLAMA_API_KEY"
|
||||
```
|
||||
</Step>
|
||||
@ -111,7 +111,7 @@ x-i18n:
|
||||
openclaw models set ollama/gemma4
|
||||
```
|
||||
|
||||
أو اضبط القيمة الافتراضية في الإعدادات:
|
||||
أو اضبط الافتراضي في الإعداد:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -134,46 +134,46 @@ x-i18n:
|
||||
<Tab title="Cloud + Local">
|
||||
يستخدم `Cloud + Local` مضيف Ollama يمكن الوصول إليه كنقطة تحكم لكل من النماذج المحلية والسحابية. وهذا هو التدفق الهجين المفضل لدى Ollama.
|
||||
|
||||
استخدم **Cloud + Local** أثناء الإعداد. يطلب OpenClaw عنوان URL الأساسي لـ Ollama، ويكتشف النماذج المحلية من ذلك المضيف، ويتحقق مما إذا كان المضيف قد سجّل الدخول للوصول السحابي باستخدام `ollama signin`. وعندما يكون المضيف قد سجّل الدخول، يقترح OpenClaw أيضًا القيم السحابية الافتراضية المستضافة مثل `kimi-k2.5:cloud` و`minimax-m2.7:cloud` و`glm-5.1:cloud`.
|
||||
استخدم **Cloud + Local** أثناء الإعداد. يطلب OpenClaw عنوان URL الأساسي لـ Ollama، ويكتشف النماذج المحلية من ذلك المضيف، ويتحقق مما إذا كان المضيف قد سجّل الدخول للوصول السحابي باستخدام `ollama signin`. وعندما يكون المضيف قد سجّل الدخول، يقترح OpenClaw أيضًا افتراضيات سحابية مستضافة مثل `kimi-k2.5:cloud` و`minimax-m2.7:cloud` و`glm-5.1:cloud`.
|
||||
|
||||
إذا لم يكن المضيف قد سجّل الدخول بعد، فسيُبقي OpenClaw الإعداد على الوضع المحلي فقط إلى أن تشغّل `ollama signin`.
|
||||
إذا لم يكن المضيف قد سجّل الدخول بعد، فسيُبقي OpenClaw الإعداد في وضع محلي فقط إلى أن تشغّل `ollama signin`.
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Cloud only">
|
||||
يعمل `Cloud only` مقابل API المستضافة من Ollama على `https://ollama.com`.
|
||||
يعمل `Cloud only` مقابل واجهة API المستضافة الخاصة بـ Ollama على `https://ollama.com`.
|
||||
|
||||
استخدم **Cloud only** أثناء الإعداد. يطلب OpenClaw قيمة `OLLAMA_API_KEY`، ويضبط `baseUrl: "https://ollama.com"`، ويزرع قائمة النماذج السحابية المستضافة. لا يتطلب هذا المسار **خادم Ollama محليًا** أو `ollama signin`.
|
||||
استخدم **Cloud only** أثناء الإعداد. يطلب OpenClaw قيمة `OLLAMA_API_KEY`، ويضبط `baseUrl: "https://ollama.com"`، ويهيّئ قائمة النماذج السحابية المستضافة. هذا المسار **لا** يتطلب خادم Ollama محليًا أو `ollama signin`.
|
||||
|
||||
تُملأ قائمة النماذج السحابية المعروضة أثناء `openclaw onboard` مباشرة من `https://ollama.com/api/tags`، بحد أقصى 500 إدخال، بحيث يعكس المنتقي الفهرس المستضاف الحالي بدلًا من بذرة ثابتة. وإذا تعذر الوصول إلى `ollama.com` أو لم يُرجع أي نماذج وقت الإعداد، فسيعود OpenClaw إلى الاقتراحات المضمّنة السابقة حتى يكتمل onboarding.
|
||||
تُملأ قائمة النماذج السحابية المعروضة أثناء `openclaw onboard` مباشرة من `https://ollama.com/api/tags`، مع حد أقصى قدره 500 إدخال، بحيث يعكس المنتقي الفهرس المستضاف الحالي بدلًا من قائمة أولية ثابتة. وإذا تعذّر الوصول إلى `ollama.com` أو لم يُرجع أي نماذج وقت الإعداد، يعود OpenClaw إلى الاقتراحات الثابتة السابقة حتى يكتمل الإعداد الأولي.
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Local only">
|
||||
في وضع المحلي فقط، يكتشف OpenClaw النماذج من نسخة Ollama المُعدّة. وهذا المسار مخصص لخوادم Ollama المحلية أو المستضافة ذاتيًا.
|
||||
في وضع المحلي فقط، يكتشف OpenClaw النماذج من نسخة Ollama المضبوطة. هذا المسار مخصص لخوادم Ollama المحلية أو المستضافة ذاتيًا.
|
||||
|
||||
يقترح OpenClaw حاليًا `gemma4` بوصفه القيمة المحلية الافتراضية.
|
||||
يقترح OpenClaw حاليًا `gemma4` بوصفه الافتراضي المحلي.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## اكتشاف النماذج (مزوّد ضمني)
|
||||
## اكتشاف النماذج (موفّر ضمني)
|
||||
|
||||
عندما تضبط `OLLAMA_API_KEY` (أو ملف auth profile) و**لا** تعرّف `models.providers.ollama`، يكتشف OpenClaw النماذج من نسخة Ollama المحلية على `http://127.0.0.1:11434`.
|
||||
عندما تضبط `OLLAMA_API_KEY` (أو ملف تعريف مصادقة) و**لا** تعرّف `models.providers.ollama`، يكتشف OpenClaw النماذج من نسخة Ollama المحلية على `http://127.0.0.1:11434`.
|
||||
|
||||
| السلوك | التفاصيل |
|
||||
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| استعلام الفهرس | يستعلم عن `/api/tags` |
|
||||
| اكتشاف الإمكانيات | يستخدم عمليات lookup من نوع `/api/show` بأفضل جهد لقراءة `contextWindow` واكتشاف الإمكانيات (بما في ذلك الرؤية) |
|
||||
| نماذج الرؤية | تُعلَّم النماذج ذات إمكانية `vision` التي يُبلغ عنها `/api/show` على أنها قادرة على الصور (`input: ["text", "image"]`)، لذلك يحقن OpenClaw الصور تلقائيًا في prompt |
|
||||
| اكتشاف reasoning | يعلّم `reasoning` باستخدام heuristic لاسم النموذج (`r1` و`reasoning` و`think`) |
|
||||
| حدود الرموز | يضبط `maxTokens` على الحد الأقصى الافتراضي للرموز في Ollama المستخدم بواسطة OpenClaw |
|
||||
| التكاليف | يضبط جميع التكاليف على `0` |
|
||||
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| استعلام الفهرس | يستعلم `/api/tags` |
|
||||
| اكتشاف القدرات | يستخدم عمليات بحث `/api/show` بأفضل جهد لقراءة `contextWindow` واكتشاف القدرات (بما في ذلك الرؤية) |
|
||||
| نماذج الرؤية | تُوسَم النماذج التي تُبلّغ عن قدرة `vision` عبر `/api/show` على أنها قادرة على التعامل مع الصور (`input: ["text", "image"]`)، لذا يحقن OpenClaw الصور تلقائيًا في الموجّه |
|
||||
| اكتشاف الاستدلال | يوسم `reasoning` باستخدام أسلوب تقريبي يعتمد على اسم النموذج (`r1` و`reasoning` و`think`) |
|
||||
| حدود الرموز | يضبط `maxTokens` على حد Ollama الافتراضي الأقصى للرموز الذي يستخدمه OpenClaw |
|
||||
| التكاليف | يضبط جميع التكاليف على `0` |
|
||||
|
||||
وهذا يتجنب إدخالات النماذج اليدوية مع إبقاء الفهرس متوافقًا مع نسخة Ollama المحلية.
|
||||
يؤدي هذا إلى تجنب إدخالات النماذج اليدوية مع إبقاء الفهرس متوافقًا مع نسخة Ollama المحلية.
|
||||
|
||||
```bash
|
||||
# اعرف النماذج المتاحة
|
||||
# اعرض النماذج المتاحة
|
||||
ollama list
|
||||
openclaw models list
|
||||
```
|
||||
@ -187,12 +187,12 @@ ollama pull mistral
|
||||
سيُكتشف النموذج الجديد تلقائيًا ويصبح متاحًا للاستخدام.
|
||||
|
||||
<Note>
|
||||
إذا ضبطت `models.providers.ollama` صراحةً، فسيتم تخطي الاكتشاف التلقائي ويجب عليك تعريف النماذج يدويًا. راجع قسم الإعدادات الصريحة أدناه.
|
||||
إذا ضبطت `models.providers.ollama` صراحةً، فسيُتجاوز الاكتشاف التلقائي ويجب عليك تعريف النماذج يدويًا. راجع قسم الإعداد الصريح أدناه.
|
||||
</Note>
|
||||
|
||||
## الرؤية ووصف الصور
|
||||
|
||||
يسجّل Plugin Ollama المجمّع Ollama بوصفه provider لفهم الوسائط قادرًا على الصور. ويتيح هذا لـ OpenClaw توجيه طلبات وصف الصور الصريحة والقيم الافتراضية المُعدّة لنموذج الصور عبر نماذج الرؤية المحلية أو المستضافة من Ollama.
|
||||
تسجّل Plugin Ollama المضمّنة Ollama بوصفه موفّر فهم وسائط قادرًا على التعامل مع الصور. وهذا يتيح لـ OpenClaw توجيه طلبات وصف الصور الصريحة وافتراضيات نماذج الصور المضبوطة عبر نماذج رؤية Ollama المحلية أو المستضافة.
|
||||
|
||||
بالنسبة إلى الرؤية المحلية، اسحب نموذجًا يدعم الصور:
|
||||
|
||||
@ -201,7 +201,7 @@ ollama pull qwen2.5vl:7b
|
||||
export OLLAMA_API_KEY="ollama-local"
|
||||
```
|
||||
|
||||
ثم تحقق باستخدام infer CLI:
|
||||
ثم تحقّق باستخدام CLI الخاص بالاستدلال:
|
||||
|
||||
```bash
|
||||
openclaw infer image describe \
|
||||
@ -210,9 +210,9 @@ openclaw infer image describe \
|
||||
--json
|
||||
```
|
||||
|
||||
يجب أن يكون `--model` مرجعًا كاملًا بصيغة `<provider/model>`. وعند ضبطه، يشغّل `openclaw infer image describe` ذلك النموذج مباشرةً بدلًا من تخطي الوصف لأن النموذج يدعم الرؤية أصلًا.
|
||||
يجب أن تكون قيمة `--model` مرجعًا كاملًا بصيغة `<provider/model>`. عند ضبطها، يشغّل `openclaw infer image describe` هذا النموذج مباشرة بدلًا من تخطي الوصف لأن النموذج يدعم الرؤية الأصلية.
|
||||
|
||||
ولجعل Ollama نموذج فهم الصور الافتراضي للوسائط الواردة، اضبط `agents.defaults.imageModel`:
|
||||
لجعل Ollama نموذج فهم الصور الافتراضي للوسائط الواردة، اضبط `agents.defaults.imageModel`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -226,7 +226,7 @@ openclaw infer image describe \
|
||||
}
|
||||
```
|
||||
|
||||
إذا عرّفت `models.providers.ollama.models` يدويًا، فعلّم نماذج الرؤية بدعم إدخال الصور:
|
||||
إذا كنت تعرّف `models.providers.ollama.models` يدويًا، فوسّم نماذج الرؤية بدعم إدخال الصور:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -238,26 +238,26 @@ openclaw infer image describe \
|
||||
}
|
||||
```
|
||||
|
||||
يرفض OpenClaw طلبات وصف الصور للنماذج التي لم تُعلَّم على أنها قادرة على الصور. ومع الاكتشاف الضمني، يقرأ OpenClaw ذلك من Ollama عندما يُبلغ `/api/show` عن إمكانية رؤية.
|
||||
يرفض OpenClaw طلبات وصف الصور للنماذج التي لم تُوسَم على أنها قادرة على التعامل مع الصور. ومع الاكتشاف الضمني، يقرأ OpenClaw ذلك من Ollama عندما يبلّغ `/api/show` عن قدرة رؤية.
|
||||
|
||||
## الإعدادات
|
||||
## الإعداد
|
||||
|
||||
<Tabs>
|
||||
<Tab title="أساسي (اكتشاف ضمني)">
|
||||
أبسط مسار لتفعيل الوضع المحلي فقط هو عبر متغير بيئة:
|
||||
أبسط مسار لتمكين الوضع المحلي فقط هو عبر متغير بيئة:
|
||||
|
||||
```bash
|
||||
export OLLAMA_API_KEY="ollama-local"
|
||||
```
|
||||
|
||||
<Tip>
|
||||
إذا تم ضبط `OLLAMA_API_KEY`، فيمكنك حذف `apiKey` من إدخال المزوّد وسيملؤه OpenClaw لفحوصات التوفر.
|
||||
إذا كانت `OLLAMA_API_KEY` مضبوطة، يمكنك حذف `apiKey` من إدخال الموفّر وسيملؤها OpenClaw لفحوصات التوفر.
|
||||
</Tip>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="صريح (نماذج يدوية)">
|
||||
استخدم الإعدادات الصريحة عندما تريد إعدادًا سحابيًا مستضافًا، أو عندما تعمل Ollama على مضيف/منفذ آخر، أو عندما تريد فرض نوافذ سياق أو قوائم نماذج محددة، أو عندما تريد تعريفات نماذج يدوية بالكامل.
|
||||
استخدم الإعداد الصريح عندما تريد إعدادًا سحابيًا مستضافًا، أو عندما يعمل Ollama على مضيف/منفذ آخر، أو عندما تريد فرض نوافذ سياق أو قوائم نماذج محددة، أو عندما تريد تعريفات نماذج يدوية بالكامل.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -287,7 +287,7 @@ openclaw infer image describe \
|
||||
</Tab>
|
||||
|
||||
<Tab title="عنوان URL أساسي مخصص">
|
||||
إذا كانت Ollama تعمل على مضيف أو منفذ مختلف (فالإعداد الصريح يعطل الاكتشاف التلقائي، لذا عرّف النماذج يدويًا):
|
||||
إذا كان Ollama يعمل على مضيف أو منفذ مختلف (الإعداد الصريح يعطّل الاكتشاف التلقائي، لذا عرّف النماذج يدويًا):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -295,7 +295,7 @@ openclaw infer image describe \
|
||||
providers: {
|
||||
ollama: {
|
||||
apiKey: "ollama-local",
|
||||
baseUrl: "http://ollama-host:11434", // بدون /v1 - استخدم عنوان URL الخاص بـ API الأصلية لـ Ollama
|
||||
baseUrl: "http://ollama-host:11434", // بدون /v1 - استخدم عنوان URL لواجهة API الأصلية لـ Ollama
|
||||
api: "ollama", // اضبطه صراحةً لضمان سلوك استدعاء الأدوات الأصلي
|
||||
},
|
||||
},
|
||||
@ -304,7 +304,7 @@ openclaw infer image describe \
|
||||
```
|
||||
|
||||
<Warning>
|
||||
لا تضف `/v1` إلى عنوان URL. يستخدم المسار `/v1` الوضع المتوافق مع OpenAI، حيث لا يكون استدعاء الأدوات موثوقًا. استخدم عنوان Ollama الأساسي من دون لاحقة مسار.
|
||||
لا تضف `/v1` إلى عنوان URL. يستخدم المسار `/v1` الوضع المتوافق مع OpenAI، حيث لا يكون استدعاء الأدوات موثوقًا. استخدم عنوان URL الأساسي لـ Ollama من دون لاحقة مسار.
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
@ -312,7 +312,7 @@ openclaw infer image describe \
|
||||
|
||||
### اختيار النموذج
|
||||
|
||||
بمجرد الإعداد، تصبح جميع نماذج Ollama الخاصة بك متاحة:
|
||||
بمجرد الإعداد، تصبح كل نماذج Ollama الخاصة بك متاحة:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -329,13 +329,13 @@ openclaw infer image describe \
|
||||
|
||||
## Ollama Web Search
|
||||
|
||||
يدعم OpenClaw **Ollama Web Search** بوصفه provider `web_search` مجمّعًا.
|
||||
يدعم OpenClaw **Ollama Web Search** بوصفه موفّر `web_search` مضمّنًا.
|
||||
|
||||
| الخاصية | التفاصيل |
|
||||
| ----------- | ----------------------------------------------------------------------------------------------------------------- |
|
||||
| المضيف | يستخدم مضيف Ollama المُعدّ لديك (`models.providers.ollama.baseUrl` عند ضبطه، وإلا `http://127.0.0.1:11434`) |
|
||||
| المصادقة | بدون مفتاح |
|
||||
| المتطلب | يجب أن تكون Ollama قيد التشغيل وقد تم تسجيل الدخول باستخدام `ollama signin` |
|
||||
| الخاصية | التفاصيل |
|
||||
| ----------- | ---------------------------------------------------------------------------------------------------------------------- |
|
||||
| المضيف | يستخدم مضيف Ollama المضبوط لديك (`models.providers.ollama.baseUrl` عند ضبطه، وإلا `http://127.0.0.1:11434`) |
|
||||
| المصادقة | لا يحتاج إلى مفتاح |
|
||||
| المتطلب | يجب أن يكون Ollama قيد التشغيل وقد تم تسجيل الدخول إليه باستخدام `ollama signin` |
|
||||
|
||||
اختر **Ollama Web Search** أثناء `openclaw onboard` أو `openclaw configure --section web`، أو اضبط:
|
||||
|
||||
@ -352,18 +352,18 @@ openclaw infer image describe \
|
||||
```
|
||||
|
||||
<Note>
|
||||
للاطلاع على تفاصيل الإعداد والسلوك الكاملة، راجع [Ollama Web Search](/ar/tools/ollama-search).
|
||||
للاطلاع على تفاصيل الإعداد والسلوك كاملةً، راجع [Ollama Web Search](/ar/tools/ollama-search).
|
||||
</Note>
|
||||
|
||||
## الإعدادات المتقدمة
|
||||
## الإعداد المتقدم
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="الوضع القديم المتوافق مع OpenAI">
|
||||
<Warning>
|
||||
**استدعاء الأدوات غير موثوق في الوضع المتوافق مع OpenAI.** استخدم هذا الوضع فقط إذا كنت تحتاج إلى تنسيق OpenAI لوكيل proxy ولا تعتمد على سلوك استدعاء الأدوات الأصلي.
|
||||
**استدعاء الأدوات غير موثوق في الوضع المتوافق مع OpenAI.** استخدم هذا الوضع فقط إذا كنت تحتاج إلى تنسيق OpenAI لوكيل وسيط ولا تعتمد على سلوك استدعاء الأدوات الأصلي.
|
||||
</Warning>
|
||||
|
||||
إذا كنت تحتاج إلى استخدام نقطة النهاية المتوافقة مع OpenAI بدلًا من ذلك (على سبيل المثال، خلف proxy لا يدعم إلا تنسيق OpenAI)، فاضبط `api: "openai-completions"` صراحةً:
|
||||
إذا كنت بحاجة إلى استخدام نقطة النهاية المتوافقة مع OpenAI بدلًا من ذلك (على سبيل المثال، خلف وكيل وسيط لا يدعم إلا تنسيق OpenAI)، فاضبط `api: "openai-completions"` صراحةً:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -383,7 +383,7 @@ openclaw infer image describe \
|
||||
|
||||
قد لا يدعم هذا الوضع البث واستدعاء الأدوات في الوقت نفسه. وقد تحتاج إلى تعطيل البث باستخدام `params: { streaming: false }` في إعداد النموذج.
|
||||
|
||||
عند استخدام `api: "openai-completions"` مع Ollama، يحقن OpenClaw القيمة `options.num_ctx` افتراضيًا حتى لا تعود Ollama بصمت إلى نافذة سياق 4096. وإذا كان proxy/upstream لديك يرفض حقول `options` غير المعروفة، فعطّل هذا السلوك:
|
||||
عند استخدام `api: "openai-completions"` مع Ollama، يحقن OpenClaw القيمة `options.num_ctx` افتراضيًا حتى لا يعود Ollama بصمت إلى نافذة سياق بحجم 4096. وإذا كان الوكيل الوسيط/المصدر العلوي لديك يرفض حقول `options` غير المعروفة، فعطّل هذا السلوك:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -404,9 +404,9 @@ openclaw infer image describe \
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="نوافذ السياق">
|
||||
بالنسبة إلى النماذج المكتشفة تلقائيًا، يستخدم OpenClaw نافذة السياق التي تُبلغ عنها Ollama عند توفرها، وإلا فإنه يعود إلى نافذة السياق الافتراضية لـ Ollama التي يستخدمها OpenClaw.
|
||||
بالنسبة إلى النماذج المكتشفة تلقائيًا، يستخدم OpenClaw نافذة السياق التي يبلّغ عنها Ollama عندما تكون متاحة، وإلا فإنه يعود إلى نافذة سياق Ollama الافتراضية التي يستخدمها OpenClaw.
|
||||
|
||||
يمكنك تجاوز `contextWindow` و`maxTokens` في إعداد provider الصريح:
|
||||
يمكنك تجاوز `contextWindow` و`maxTokens` في إعداد الموفّر الصريح:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -428,32 +428,32 @@ openclaw infer image describe \
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="نماذج reasoning">
|
||||
يتعامل OpenClaw افتراضيًا مع النماذج التي تحمل أسماء مثل `deepseek-r1` أو `reasoning` أو `think` على أنها قادرة على reasoning.
|
||||
<Accordion title="نماذج الاستدلال">
|
||||
يتعامل OpenClaw مع النماذج التي تحمل أسماء مثل `deepseek-r1` أو `reasoning` أو `think` على أنها قادرة على الاستدلال افتراضيًا.
|
||||
|
||||
```bash
|
||||
ollama pull deepseek-r1:32b
|
||||
```
|
||||
|
||||
لا حاجة إلى أي إعداد إضافي -- إذ يعلّمها OpenClaw تلقائيًا.
|
||||
لا حاجة إلى أي إعداد إضافي -- يوسمها OpenClaw تلقائيًا.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="تكاليف النموذج">
|
||||
Ollama مجانية وتعمل محليًا، لذلك يتم ضبط جميع تكاليف النماذج على $0. وينطبق هذا على كل من النماذج المكتشفة تلقائيًا والنماذج المعرّفة يدويًا.
|
||||
<Accordion title="تكاليف النماذج">
|
||||
Ollama مجاني ويعمل محليًا، لذا تُضبط جميع تكاليف النماذج على $0. وينطبق هذا على كل من النماذج المكتشفة تلقائيًا والنماذج المعرّفة يدويًا.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="تضمينات الذاكرة">
|
||||
يسجّل Plugin Ollama المجمّع provider لتضمينات الذاكرة من أجل
|
||||
[البحث في الذاكرة](/ar/concepts/memory). ويستخدم عنوان URL الأساسي
|
||||
ومفتاح API المُعدَّين لـ Ollama.
|
||||
تسجّل Plugin Ollama المضمّنة موفّر تضمينات للذاكرة من أجل
|
||||
[البحث في الذاكرة](/ar/concepts/memory). وهي تستخدم عنوان URL الأساسي
|
||||
لـ Ollama ومفتاح API المضبوطين.
|
||||
|
||||
| الخاصية | القيمة |
|
||||
| ------------- | ------------------- |
|
||||
| الخاصية | القيمة |
|
||||
| -------------- | ------------------- |
|
||||
| النموذج الافتراضي | `nomic-embed-text` |
|
||||
| السحب التلقائي | نعم — يتم سحب نموذج التضمين تلقائيًا إذا لم يكن موجودًا محليًا |
|
||||
| السحب التلقائي | نعم — يُسحب نموذج التضمين تلقائيًا إذا لم يكن موجودًا محليًا |
|
||||
|
||||
لاختيار Ollama بوصفه provider تضمينات البحث في الذاكرة:
|
||||
لاختيار Ollama بوصفه موفّر تضمينات البحث في الذاكرة:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -467,11 +467,13 @@ openclaw infer image describe \
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="إعدادات البث">
|
||||
يستخدم تكامل Ollama في OpenClaw **API الأصلية لـ Ollama** (`/_api/chat`) افتراضيًا، وهي تدعم البث واستدعاء الأدوات بالكامل في الوقت نفسه. ولا حاجة إلى أي إعداد خاص.
|
||||
<Accordion title="إعداد البث">
|
||||
يستخدم تكامل Ollama في OpenClaw **واجهة API الأصلية لـ Ollama** (`/api/chat`) افتراضيًا، وهي تدعم بالكامل البث واستدعاء الأدوات في الوقت نفسه. لا حاجة إلى أي إعداد خاص.
|
||||
|
||||
بالنسبة إلى طلبات `/api/chat` الأصلية، يمرر OpenClaw أيضًا التحكم في التفكير مباشرةً إلى Ollama: إذ يرسل `/think off` و`openclaw agent --thinking off` القيمة العليا `think: false`، بينما ترسل مستويات التفكير غير `off` القيمة `think: true`.
|
||||
|
||||
<Tip>
|
||||
إذا كنت تحتاج إلى استخدام نقطة النهاية المتوافقة مع OpenAI، فراجع قسم "الوضع القديم المتوافق مع OpenAI" أعلاه. قد لا يعمل البث واستدعاء الأدوات في الوقت نفسه في ذلك الوضع.
|
||||
إذا كنت بحاجة إلى استخدام نقطة النهاية المتوافقة مع OpenAI، فراجع قسم "الوضع القديم المتوافق مع OpenAI" أعلاه. قد لا يعمل البث واستدعاء الأدوات في الوقت نفسه في ذلك الوضع.
|
||||
</Tip>
|
||||
|
||||
</Accordion>
|
||||
@ -481,13 +483,13 @@ openclaw infer image describe \
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="لم يتم اكتشاف Ollama">
|
||||
تأكد من أن Ollama قيد التشغيل وأنك قد ضبطت `OLLAMA_API_KEY` (أو auth profile)، وأنك **لم** تعرّف إدخال `models.providers.ollama` صريحًا:
|
||||
تأكد من أن Ollama قيد التشغيل وأنك ضبطت `OLLAMA_API_KEY` (أو ملف تعريف مصادقة)، وأنك **لم** تعرّف إدخال `models.providers.ollama` صريحًا:
|
||||
|
||||
```bash
|
||||
ollama serve
|
||||
```
|
||||
|
||||
تحقق من أن API يمكن الوصول إليها:
|
||||
تحقّق من أن واجهة API قابلة للوصول:
|
||||
|
||||
```bash
|
||||
curl http://localhost:11434/api/tags
|
||||
@ -499,7 +501,7 @@ openclaw infer image describe \
|
||||
إذا لم يكن نموذجك مدرجًا، فإما أن تسحب النموذج محليًا أو تعرّفه صراحةً في `models.providers.ollama`.
|
||||
|
||||
```bash
|
||||
ollama list # اعرف ما هو مثبت
|
||||
ollama list # اعرض ما هو مثبّت
|
||||
ollama pull gemma4
|
||||
ollama pull gpt-oss:20b
|
||||
ollama pull llama3.3 # أو نموذج آخر
|
||||
@ -508,10 +510,10 @@ openclaw infer image describe \
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="تم رفض الاتصال">
|
||||
تحقق من أن Ollama تعمل على المنفذ الصحيح:
|
||||
تحقّق من أن Ollama يعمل على المنفذ الصحيح:
|
||||
|
||||
```bash
|
||||
# تحقق مما إذا كانت Ollama قيد التشغيل
|
||||
# تحقق مما إذا كان Ollama قيد التشغيل
|
||||
ps aux | grep ollama
|
||||
|
||||
# أو أعد تشغيل Ollama
|
||||
@ -528,16 +530,16 @@ openclaw infer image describe \
|
||||
## ذو صلة
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Model providers" href="/ar/concepts/model-providers" icon="layers">
|
||||
نظرة عامة على جميع providers ومراجع النماذج وسلوك failover.
|
||||
<Card title="موفّرو النماذج" href="/ar/concepts/model-providers" icon="layers">
|
||||
نظرة عامة على جميع الموفّرين، ومراجع النماذج، وسلوك تجاوز الفشل.
|
||||
</Card>
|
||||
<Card title="اختيار النموذج" href="/ar/concepts/models" icon="brain">
|
||||
كيفية اختيار النماذج وإعدادها.
|
||||
كيفية اختيار النماذج وتهيئتها.
|
||||
</Card>
|
||||
<Card title="Ollama Web Search" href="/ar/tools/ollama-search" icon="magnifying-glass">
|
||||
تفاصيل الإعداد والسلوك الكاملة للبحث على الويب المدعوم بواسطة Ollama.
|
||||
</Card>
|
||||
<Card title="الإعدادات" href="/ar/gateway/configuration" icon="gear">
|
||||
المرجع الكامل للإعدادات.
|
||||
<Card title="الإعداد" href="/ar/gateway/configuration" icon="gear">
|
||||
المرجع الكامل للإعداد.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
67
docs/ar/providers/tencent.md
Normal file
67
docs/ar/providers/tencent.md
Normal file
@ -0,0 +1,67 @@
|
||||
---
|
||||
read_when:
|
||||
- تريد استخدام نماذج Tencent Hy مع OpenClaw
|
||||
- تحتاج إلى إعداد مفتاح API الخاص بـ TokenHub
|
||||
summary: إعداد Tencent Cloud TokenHub
|
||||
title: Tencent Cloud (TokenHub)
|
||||
x-i18n:
|
||||
generated_at: "2026-04-22T07:18:55Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 04da073973792c55dc0c2d287bfc51187bb2128bbbd5c4a483f850adeea50ab5
|
||||
source_path: providers/tencent.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Tencent Cloud (TokenHub)
|
||||
|
||||
يتيح مزود Tencent Cloud الوصول إلى نماذج Tencent Hy عبر نقطة نهاية TokenHub
|
||||
(`tencent-tokenhub`).
|
||||
|
||||
يستخدم المزود واجهة API متوافقة مع OpenAI.
|
||||
|
||||
## البدء السريع
|
||||
|
||||
```bash
|
||||
openclaw onboard --auth-choice tokenhub-api-key
|
||||
```
|
||||
|
||||
## مثال غير تفاعلي
|
||||
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
--mode local \
|
||||
--auth-choice tokenhub-api-key \
|
||||
--tokenhub-api-key "$TOKENHUB_API_KEY" \
|
||||
--skip-health \
|
||||
--accept-risk
|
||||
```
|
||||
|
||||
## المزودون ونقاط النهاية
|
||||
|
||||
| المزود | نقطة النهاية | حالة الاستخدام |
|
||||
| ------------------ | ----------------------------- | ------------------------ |
|
||||
| `tencent-tokenhub` | `tokenhub.tencentmaas.com/v1` | Hy عبر Tencent TokenHub |
|
||||
|
||||
## النماذج المتاحة
|
||||
|
||||
### tencent-tokenhub
|
||||
|
||||
- **hy3-preview** — معاينة Hy3 (سياق 256K، reasoning، افتراضي)
|
||||
|
||||
## ملاحظات
|
||||
|
||||
- تستخدم مراجع نماذج TokenHub الصيغة `tencent-tokenhub/<modelId>`.
|
||||
- تجاوز بيانات التسعير وبيانات السياق الوصفية في `models.providers` عند الحاجة.
|
||||
|
||||
## ملاحظة حول البيئة
|
||||
|
||||
إذا كانت Gateway تعمل كخدمة daemon (`launchd/systemd`)، فتأكد من أن `TOKENHUB_API_KEY`
|
||||
متاح لتلك العملية (على سبيل المثال، في `~/.openclaw/.env` أو عبر
|
||||
`env.shellEnv`).
|
||||
|
||||
## الوثائق ذات الصلة
|
||||
|
||||
- [إعدادات OpenClaw](/ar/gateway/configuration)
|
||||
- [مزودو النماذج](/ar/concepts/model-providers)
|
||||
- [Tencent TokenHub](https://cloud.tencent.com/document/product/1823/130050)
|
||||
@ -1,128 +1,129 @@
|
||||
---
|
||||
read_when:
|
||||
- تريد فهم الأدوات التي يوفرها OpenClaw
|
||||
- تحتاج إلى إعداد الأدوات أو السماح بها أو منعها
|
||||
- أنت بصدد الاختيار بين الأدوات المدمجة وSkills وplugins
|
||||
summary: 'نظرة عامة على أدوات OpenClaw وplugins: ما الذي يمكن للوكيل فعله وكيفية توسيعه'
|
||||
- تريد فهم الأدوات التي يوفّرها OpenClaw
|
||||
- تحتاج إلى تهيئة الأدوات أو السماح بها أو منعها
|
||||
- أنت تقرر بين الأدوات المدمجة وSkills وPlugins
|
||||
summary: 'نظرة عامة على أدوات OpenClaw وPlugins: ما الذي يمكن للوكيل فعله وكيفية توسيعه'
|
||||
title: الأدوات وPlugins
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T03:13:30Z"
|
||||
generated_at: "2026-04-22T07:18:58Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: b2371239316997b0fe389bfa2ec38404e1d3e177755ad81ff8035ac583d9adeb
|
||||
source_hash: 6edb9e13b72e6345554f25c8d8413d167a69501e6626828d9aa3aac6907cd092
|
||||
source_path: tools/index.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# الأدوات وPlugins
|
||||
|
||||
كل ما يفعله الوكيل خارج توليد النص يتم من خلال **الأدوات**.
|
||||
كل ما يفعله الوكيل خارج نطاق توليد النص يتم عبر **الأدوات**.
|
||||
الأدوات هي الطريقة التي يقرأ بها الوكيل الملفات، ويشغّل الأوامر، ويتصفح الويب، ويرسل
|
||||
الرسائل، ويتفاعل مع الأجهزة.
|
||||
|
||||
## الأدوات والمهارات وplugins
|
||||
## الأدوات وSkills وPlugins
|
||||
|
||||
يحتوي OpenClaw على ثلاث طبقات تعمل معًا:
|
||||
|
||||
<Steps>
|
||||
<Step title="الأدوات هي ما يستدعيه الوكيل">
|
||||
الأداة هي دالة مكتوبة النوع يمكن للوكيل استدعاؤها (مثل `exec` و`browser`،
|
||||
و`web_search` و`message`). يوفّر OpenClaw مجموعة من **الأدوات المدمجة** ويمكن
|
||||
للplugins تسجيل أدوات إضافية.
|
||||
الأداة هي دالة typed يمكن للوكيل استدعاؤها (مثل `exec` و`browser` و
|
||||
`web_search` و`message`). يأتي OpenClaw مع مجموعة من **الأدوات المدمجة**
|
||||
ويمكن لـ Plugins تسجيل أدوات إضافية.
|
||||
|
||||
يرى الوكيل الأدوات على أنها تعريفات دوال مهيكلة تُرسل إلى API الخاصة بالنموذج.
|
||||
يرى الوكيل الأدوات على أنها تعريفات دوال منظَّمة تُرسل إلى API النموذج.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Skills تعلّم الوكيل متى وكيف">
|
||||
الـ skill هي ملف markdown (`SKILL.md`) يُحقن في system prompt.
|
||||
تمنح Skills الوكيل السياق، والقيود، والإرشادات خطوة بخطوة من أجل
|
||||
استخدام الأدوات بفعالية. وتوجد Skills في مساحة العمل الخاصة بك، أو في مجلدات
|
||||
مشتركة، أو تأتي ضمن plugins.
|
||||
<Step title="تعلّم Skills الوكيل متى وكيف">
|
||||
الـ skill هو ملف markdown (`SKILL.md`) يُحقن في system prompt.
|
||||
تمنح Skills الوكيل سياقًا وقيودًا وإرشادات خطوة بخطوة من أجل
|
||||
استخدام الأدوات بفعالية. توجد Skills في مساحة العمل لديك، أو في المجلدات
|
||||
المشتركة، أو تأتي مضمّنة داخل Plugins.
|
||||
|
||||
[مرجع Skills](/ar/tools/skills) | [إنشاء Skills](/ar/tools/creating-skills)
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Plugins تجمع كل شيء معًا">
|
||||
الـ plugin هي حزمة يمكنها تسجيل أي مجموعة من القدرات:
|
||||
القنوات، وموفّري النماذج، والأدوات، وSkills، والكلام، والنسخ الفوري،
|
||||
<Step title="تجمع Plugins كل شيء معًا">
|
||||
الـ Plugin هو حزمة يمكنها تسجيل أي مزيج من القدرات:
|
||||
القنوات، وموفّرو النماذج، والأدوات، وSkills، والكلام، والنسخ الفوري،
|
||||
والصوت الفوري، وفهم الوسائط، وتوليد الصور، وتوليد الفيديو،
|
||||
وجلب الويب، والبحث في الويب، وغير ذلك. بعض plugins تكون **core** (مرفقة مع
|
||||
OpenClaw)، وأخرى تكون **خارجية** (منشورة على npm من قبل المجتمع).
|
||||
وجلب الويب، والبحث على الويب، وغير ذلك. بعض Plugins **أساسية** (تأتي مع
|
||||
OpenClaw)، وبعضها الآخر **خارجية** (ينشرها المجتمع على npm).
|
||||
|
||||
[تثبيت plugins وإعدادها](/ar/tools/plugin) | [ابنِ plugin خاصة بك](/ar/plugins/building-plugins)
|
||||
[تثبيت Plugins وتهيئتها](/ar/tools/plugin) | [أنشئ Plugin خاصًا بك](/ar/plugins/building-plugins)
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## الأدوات المدمجة
|
||||
|
||||
تأتي هذه الأدوات مع OpenClaw وتكون متاحة من دون تثبيت أي plugins:
|
||||
تأتي هذه الأدوات مع OpenClaw وتكون متاحة من دون تثبيت أي Plugins:
|
||||
|
||||
| الأداة | ما الذي تفعله | الصفحة |
|
||||
| ------------------------------------------ | ------------------------------------------------------------------ | ------------------------------------------- |
|
||||
| `exec` / `process` | تشغيل أوامر shell، وإدارة العمليات في الخلفية | [Exec](/ar/tools/exec) |
|
||||
| `code_execution` | تشغيل تحليل Python بعيد ومعزول | [Code Execution](/ar/tools/code-execution) |
|
||||
| `browser` | التحكم في متصفح Chromium (التنقل، والنقر، ولقطات الشاشة) | [Browser](/ar/tools/browser) |
|
||||
| `web_search` / `x_search` / `web_fetch` | البحث في الويب، والبحث في منشورات X، وجلب محتوى الصفحات | [الويب](/ar/tools/web) |
|
||||
| `read` / `write` / `edit` | إدخال/إخراج الملفات في مساحة العمل | |
|
||||
| `apply_patch` | ترقيعات ملفات متعددة المقاطع | [Apply Patch](/ar/tools/apply-patch) |
|
||||
| `message` | إرسال الرسائل عبر جميع القنوات | [Agent Send](/ar/tools/agent-send) |
|
||||
| `canvas` | تشغيل Canvas الخاص بالعقدة (present وeval وsnapshot) | |
|
||||
| `nodes` | اكتشاف الأجهزة المقترنة واستهدافها | |
|
||||
| `cron` / `gateway` | إدارة الوظائف المجدولة؛ وفحص gateway أو ترقيعها أو إعادة تشغيلها أو تحديثها | |
|
||||
| `image` / `image_generate` | تحليل الصور أو توليدها | [توليد الصور](/ar/tools/image-generation) |
|
||||
| `music_generate` | توليد مقاطع موسيقية | [توليد الموسيقى](/tools/music-generation) |
|
||||
| `video_generate` | توليد الفيديوهات | [توليد الفيديو](/tools/video-generation) |
|
||||
| `tts` | تحويل نص إلى كلام لمرة واحدة | [TTS](/ar/tools/tts) |
|
||||
| `sessions_*` / `subagents` / `agents_list` | إدارة الجلسات، والحالة، وتنسيق الوكلاء الفرعيين | [الوكلاء الفرعيون](/ar/tools/subagents) |
|
||||
| `session_status` | أداة قراءة خفيفة بأسلوب `/status` وتجاوز نموذج الجلسة | [أدوات الجلسة](/ar/concepts/session-tool) |
|
||||
| الأداة | ما الذي تفعله | الصفحة |
|
||||
| ------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------- |
|
||||
| `exec` / `process` | تشغيل أوامر shell وإدارة العمليات في الخلفية | [Exec](/ar/tools/exec) |
|
||||
| `code_execution` | تشغيل تحليل Python بعيد داخل بيئة معزولة | [Code Execution](/ar/tools/code-execution) |
|
||||
| `browser` | التحكّم في متصفح Chromium (التنقل، النقر، لقطة شاشة) | [Browser](/ar/tools/browser) |
|
||||
| `web_search` / `x_search` / `web_fetch` | البحث على الويب، والبحث في منشورات X، وجلب محتوى الصفحات | [الويب](/ar/tools/web) |
|
||||
| `read` / `write` / `edit` | إدخال/إخراج الملفات في مساحة العمل | |
|
||||
| `apply_patch` | ترقيعات ملفات متعددة المقاطع | [Apply Patch](/ar/tools/apply-patch) |
|
||||
| `message` | إرسال الرسائل عبر جميع القنوات | [Agent Send](/ar/tools/agent-send) |
|
||||
| `canvas` | تشغيل node Canvas (عرض، eval، snapshot) | |
|
||||
| `nodes` | اكتشاف الأجهزة المقترنة واستهدافها | |
|
||||
| `cron` / `gateway` | إدارة المهام المجدولة؛ وفحص Gateway أو ترقيعه أو إعادة تشغيله أو تحديثه | |
|
||||
| `image` / `image_generate` | تحليل الصور أو إنشاؤها | [Image Generation](/ar/tools/image-generation) |
|
||||
| `music_generate` | إنشاء مقاطع موسيقية | [Music Generation](/ar/tools/music-generation) |
|
||||
| `video_generate` | إنشاء مقاطع فيديو | [Video Generation](/ar/tools/video-generation) |
|
||||
| `tts` | تحويل النص إلى كلام دفعة واحدة | [TTS](/ar/tools/tts) |
|
||||
| `sessions_*` / `subagents` / `agents_list` | إدارة الجلسات، والحالة، وتنسيق الوكلاء الفرعيين | [Sub-agents](/ar/tools/subagents) |
|
||||
| `session_status` | قراءة خفيفة على نمط `/status` وتجاوز نموذج الجلسة | [أدوات الجلسة](/ar/concepts/session-tool) |
|
||||
|
||||
بالنسبة إلى العمل على الصور، استخدم `image` للتحليل و`image_generate` للتوليد أو التحرير. إذا استهدفت `openai/*` أو `google/*` أو `fal/*` أو موفّر صور غير افتراضي آخر، فقم أولًا بإعداد المصادقة/مفتاح API الخاص بذلك الموفّر.
|
||||
بالنسبة إلى العمل على الصور، استخدم `image` للتحليل و`image_generate` للإنشاء أو التحرير. إذا كنت تستهدف `openai/*` أو `google/*` أو `fal/*` أو موفّر صور غير افتراضي آخر، فقم أولًا بتهيئة auth/API key لذلك الموفّر.
|
||||
|
||||
بالنسبة إلى العمل على الموسيقى، استخدم `music_generate`. إذا استهدفت `google/*` أو `minimax/*` أو موفّر موسيقى غير افتراضي آخر، فقم أولًا بإعداد المصادقة/مفتاح API الخاص بذلك الموفّر.
|
||||
بالنسبة إلى العمل الموسيقي، استخدم `music_generate`. إذا كنت تستهدف `google/*` أو `minimax/*` أو موفّر موسيقى غير افتراضي آخر، فقم أولًا بتهيئة auth/API key لذلك الموفّر.
|
||||
|
||||
بالنسبة إلى العمل على الفيديو، استخدم `video_generate`. إذا استهدفت `qwen/*` أو موفّر فيديو غير افتراضي آخر، فقم أولًا بإعداد المصادقة/مفتاح API الخاص بذلك الموفّر.
|
||||
بالنسبة إلى العمل على الفيديو، استخدم `video_generate`. إذا كنت تستهدف `qwen/*` أو موفّر فيديو غير افتراضي آخر، فقم أولًا بتهيئة auth/API key لذلك الموفّر.
|
||||
|
||||
بالنسبة إلى توليد الصوت المدفوع بسير العمل، استخدم `music_generate` عندما
|
||||
تسجّله plugin مثل ComfyUI. وهذا منفصل عن `tts`، التي هي تحويل النص إلى كلام.
|
||||
بالنسبة إلى إنشاء الصوت المعتمد على سير العمل، استخدم `music_generate` عندما يقوم Plugin مثل
|
||||
ComfyUI بتسجيله. وهذا منفصل عن `tts`، الذي يختص بتحويل النص إلى كلام.
|
||||
|
||||
`session_status` هي أداة الحالة/القراءة الخفيفة في مجموعة sessions.
|
||||
فهي تجيب عن الأسئلة بأسلوب `/status` حول الجلسة الحالية ويمكنها
|
||||
اختياريًا تعيين تجاوز نموذج على مستوى الجلسة؛ أما `model=default` فيزيل هذا
|
||||
التجاوز. ومثل `/status`، يمكنها أن تملأ عدادات الرموز/cache الناقصة و
|
||||
تسمية نموذج وقت التشغيل النشط انطلاقًا من أحدث إدخال استخدام في transcript.
|
||||
الأداة `session_status` هي أداة الحالة/القراءة الخفيفة ضمن مجموعة الجلسات.
|
||||
فهي تجيب عن أسئلة على نمط `/status` حول الجلسة الحالية، ويمكنها
|
||||
اختياريًا تعيين تجاوز نموذج لكل جلسة؛ ويؤدي `model=default` إلى مسح ذلك
|
||||
التجاوز. ومثل `/status`، يمكنها إكمال عدادات الرموز/التخزين المؤقت المتفرقة ووسم
|
||||
النموذج النشط في Runtime من أحدث إدخال استخدام في السجل.
|
||||
|
||||
`gateway` هي أداة وقت التشغيل الخاصة بالمالك فقط لعمليات gateway:
|
||||
الأداة `gateway` هي أداة Runtime مخصصة للمالك فقط لعمليات Gateway:
|
||||
|
||||
- `config.schema.lookup` من أجل شجرة إعدادات فرعية محددة بمسار قبل التعديلات
|
||||
- `config.get` من أجل لقطة الإعدادات الحالية + hash
|
||||
- `config.patch` من أجل تحديثات إعدادات جزئية مع إعادة التشغيل
|
||||
- `config.apply` فقط من أجل استبدال الإعدادات كاملة
|
||||
- `update.run` من أجل التحديث الذاتي الصريح + إعادة التشغيل
|
||||
- `config.schema.lookup` للحصول على شجرة إعدادات فرعية بنطاق مسار واحد قبل التحرير
|
||||
- `config.get` للحصول على لقطة الإعدادات الحالية + hash
|
||||
- `config.patch` لتحديثات الإعدادات الجزئية مع إعادة التشغيل
|
||||
- `config.apply` فقط للاستبدال الكامل للإعدادات
|
||||
- `update.run` لتنفيذ التحديث الذاتي + إعادة التشغيل بشكل صريح
|
||||
|
||||
بالنسبة إلى التغييرات الجزئية، فضّل `config.schema.lookup` ثم `config.patch`.
|
||||
واستخدم `config.apply` فقط عندما تقصد استبدال الإعدادات بالكامل.
|
||||
كما ترفض الأداة أيضًا تغيير `tools.exec.ask` أو `tools.exec.security`؛ ويتم
|
||||
تطبيع الأسماء المستعارة القديمة `tools.bash.*` إلى مسارات exec المحمية نفسها.
|
||||
بالنسبة إلى التغييرات الجزئية، يُفضَّل استخدام `config.schema.lookup` ثم
|
||||
`config.patch`. واستخدم `config.apply` فقط عندما تنوي عمدًا استبدال الإعدادات بالكامل.
|
||||
وترفض الأداة أيضًا تغيير `tools.exec.ask` أو `tools.exec.security`؛
|
||||
كما تُطبَّع الأسماء المستعارة القديمة `tools.bash.*` إلى مسارات exec المحمية نفسها.
|
||||
|
||||
### الأدوات التي توفرها plugins
|
||||
### الأدوات التي توفّرها Plugins
|
||||
|
||||
يمكن للplugins تسجيل أدوات إضافية. بعض الأمثلة:
|
||||
يمكن لـ Plugins تسجيل أدوات إضافية. بعض الأمثلة:
|
||||
|
||||
- [Lobster](/ar/tools/lobster) — وقت تشغيل سير عمل مكتوب النوع مع موافقات قابلة للاستئناف
|
||||
- [LLM Task](/ar/tools/llm-task) — خطوة LLM بصيغة JSON فقط من أجل المخرجات المهيكلة
|
||||
- [Music Generation](/tools/music-generation) — أداة `music_generate` مشتركة مع موفّرين مدفوعين بسير العمل
|
||||
- [Diffs](/ar/tools/diffs) — عارض فروق ومُصيّر لها
|
||||
- [OpenProse](/ar/prose) — تنسيق سير عمل قائم على Markdown أولًا
|
||||
- [Diffs](/ar/tools/diffs) — عارض ومُصيّر للاختلافات
|
||||
- [LLM Task](/ar/tools/llm-task) — خطوة LLM تعتمد JSON فقط للمخرجات المنظَّمة
|
||||
- [Lobster](/ar/tools/lobster) — Runtime لسير عمل typed مع موافقات قابلة للاستئناف
|
||||
- [Music Generation](/ar/tools/music-generation) — أداة `music_generate` مشتركة مع موفّرين مدعومين بسير العمل
|
||||
- [OpenProse](/ar/prose) — تنسيق سير العمل بأسلوب markdown-first
|
||||
- [Tokenjuice](/ar/tools/tokenjuice) — نتائج مضغوطة لأداتي `exec` و`bash` كثيرة الضجيج
|
||||
|
||||
## إعداد الأدوات
|
||||
## تهيئة الأدوات
|
||||
|
||||
### قوائم السماح والمنع
|
||||
|
||||
تحكم في الأدوات التي يمكن للوكيل استدعاؤها عبر `tools.allow` و`tools.deny` في
|
||||
الإعدادات. ويفوز المنع دائمًا على السماح.
|
||||
تحكّم في الأدوات التي يمكن للوكيل استدعاؤها عبر `tools.allow` / `tools.deny` في
|
||||
الإعدادات. وتكون الأولوية دائمًا للمنع على السماح.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -135,50 +136,49 @@ x-i18n:
|
||||
|
||||
### ملفات تعريف الأدوات
|
||||
|
||||
يضبط `tools.profile` قائمة السماح الأساسية قبل تطبيق `allow`/`deny`.
|
||||
يضبط `tools.profile` قائمة سماح أساسية قبل تطبيق `allow`/`deny`.
|
||||
التجاوز لكل وكيل: `agents.list[].tools.profile`.
|
||||
|
||||
| ملف التعريف | ما الذي يتضمنه |
|
||||
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `full` | بلا قيود (يماثل عدم الضبط) |
|
||||
| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `music_generate`, `video_generate` |
|
||||
| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` |
|
||||
| `minimal` | `session_status` فقط |
|
||||
| الملف التعريفي | ما الذي يتضمنه |
|
||||
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `full` | بلا قيود (مماثل لعدم التعيين) |
|
||||
| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `music_generate`, `video_generate` |
|
||||
| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` |
|
||||
| `minimal` | `session_status` فقط |
|
||||
|
||||
### مجموعات الأدوات
|
||||
|
||||
استخدم اختصارات `group:*` في قوائم السماح/المنع:
|
||||
|
||||
| المجموعة | الأدوات |
|
||||
| ------------------ | ----------------------------------------------------------------------------------------------------------- |
|
||||
| المجموعة | الأدوات |
|
||||
| ------------------ | ---------------------------------------------------------------------------------------------------------- |
|
||||
| `group:runtime` | exec, process, code_execution (يُقبل `bash` كاسم مستعار لـ `exec`) |
|
||||
| `group:fs` | read, write, edit, apply_patch |
|
||||
| `group:sessions` | sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status |
|
||||
| `group:memory` | memory_search, memory_get |
|
||||
| `group:web` | web_search, x_search, web_fetch |
|
||||
| `group:ui` | browser, canvas |
|
||||
| `group:automation` | cron, gateway |
|
||||
| `group:messaging` | message |
|
||||
| `group:nodes` | nodes |
|
||||
| `group:agents` | agents_list |
|
||||
| `group:media` | image, image_generate, music_generate, video_generate, tts |
|
||||
| `group:openclaw` | جميع أدوات OpenClaw المدمجة (باستثناء أدوات plugin) |
|
||||
| `group:fs` | read, write, edit, apply_patch |
|
||||
| `group:sessions` | sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status |
|
||||
| `group:memory` | memory_search, memory_get |
|
||||
| `group:web` | web_search, x_search, web_fetch |
|
||||
| `group:ui` | browser, canvas |
|
||||
| `group:automation` | cron, gateway |
|
||||
| `group:messaging` | message |
|
||||
| `group:nodes` | nodes |
|
||||
| `group:agents` | agents_list |
|
||||
| `group:media` | image, image_generate, music_generate, video_generate, tts |
|
||||
| `group:openclaw` | جميع أدوات OpenClaw المدمجة (باستثناء أدوات Plugins) |
|
||||
|
||||
تعيد `sessions_history` عرض استدعاء مقيّدًا ومفلترًا لأسباب الأمان. فهي تزيل
|
||||
وسوم التفكير، وهياكل `<relevant-memories>`، وحمولات XML النصية البسيطة الخاصة باستدعاءات الأدوات
|
||||
(بما في ذلك `<tool_call>...</tool_call>`,
|
||||
و`<function_call>...</function_call>`, و`<tool_calls>...</tool_calls>`,
|
||||
و`<function_calls>...</function_calls>`,
|
||||
وكتل استدعاءات الأدوات المقتطعة)، وهياكل استدعاءات الأدوات المخفّضة،
|
||||
ورموز التحكم بالنموذج المتسربة بصيغة ASCII/العرض الكامل،
|
||||
وXML استدعاءات الأدوات المشوهة الخاصة بـ MiniMax من نص المساعد، ثم تطبق
|
||||
الإخفاء/الاقتطاع وإمكانية استخدام عناصر نائبة للصفوف كبيرة الحجم بدلًا من العمل
|
||||
كتفريغ transcript خام.
|
||||
تعيد `sessions_history` عرض استرجاع مقيّدًا ومفلترًا للسلامة. فهي تزيل
|
||||
وسوم التفكير، وهيكل `<relevant-memories>`، وحمولات XML النصية العادية
|
||||
لاستدعاء الأدوات (بما في ذلك `<tool_call>...</tool_call>`،
|
||||
و`<function_call>...</function_call>`، و`<tool_calls>...</tool_calls>`،
|
||||
و`<function_calls>...</function_calls>`، وكتل استدعاء الأدوات المقتطعة)،
|
||||
وهيكل استدعاء الأدوات المخفّض، ورموز التحكم بالنموذج المسرّبة بتنسيق ASCII/العرض الكامل،
|
||||
وXML استدعاء الأدوات غير الصحيح من MiniMax في نص المساعد، ثم تطبق
|
||||
الإخفاء/الاقتطاع وربما عناصر نائبة للصفوف كبيرة الحجم بدلًا من التعامل معه
|
||||
كإخراج خام للسجل.
|
||||
|
||||
### القيود الخاصة بكل موفّر
|
||||
### قيود خاصة بالموفّر
|
||||
|
||||
استخدم `tools.byProvider` لتقييد الأدوات لموفّرين محددين من دون
|
||||
تغيير الإعدادات العامة الافتراضية:
|
||||
تغيير الإعدادات الافتراضية العامة:
|
||||
|
||||
```json5
|
||||
{
|
||||
|
||||
83
docs/ar/tools/tokenjuice.md
Normal file
83
docs/ar/tools/tokenjuice.md
Normal file
@ -0,0 +1,83 @@
|
||||
---
|
||||
read_when:
|
||||
- تريد نتائج أقصر لأداتي `exec` أو `bash` في OpenClaw
|
||||
- تريد تفعيل Plugin tokenjuice المضمّن
|
||||
- تحتاج إلى فهم ما الذي يغيّره tokenjuice وما الذي يتركه بصيغته الخام
|
||||
summary: ضغط نتائج أدوات exec وbash المليئة بالضوضاء باستخدام Plugin مضمّن اختياري
|
||||
title: Tokenjuice
|
||||
x-i18n:
|
||||
generated_at: "2026-04-22T07:19:10Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 9b9a1054c9b1cc62e43ac6d5904c7790f9b27d8e0d0700c9da6e287c00e91783
|
||||
source_path: tools/tokenjuice.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Tokenjuice
|
||||
|
||||
`tokenjuice` هو Plugin مضمّن اختياري يضغط نتائج أدوات `exec` و`bash`
|
||||
المليئة بالضوضاء بعد تنفيذ الأمر بالفعل.
|
||||
|
||||
إنه يغيّر `tool_result` المُعاد، وليس الأمر نفسه. ولا يقوم Tokenjuice
|
||||
بإعادة كتابة إدخال shell، أو إعادة تشغيل الأوامر، أو تغيير رموز الخروج.
|
||||
|
||||
ينطبق هذا اليوم على عمليات التشغيل المضمّنة لـ Pi، حيث يربط tokenjuice نفسه
|
||||
بمسار `tool_result` المضمّن ويقلّم المخرجات التي تعود إلى الجلسة.
|
||||
|
||||
## تفعيل Plugin
|
||||
|
||||
المسار السريع:
|
||||
|
||||
```bash
|
||||
openclaw config set plugins.entries.tokenjuice.enabled true
|
||||
```
|
||||
|
||||
المكافئ:
|
||||
|
||||
```bash
|
||||
openclaw plugins enable tokenjuice
|
||||
```
|
||||
|
||||
يشحن OpenClaw الـ Plugin بالفعل. ولا توجد خطوة منفصلة مثل `plugins install`
|
||||
أو `tokenjuice install openclaw`.
|
||||
|
||||
إذا كنت تفضّل تعديل الإعدادات مباشرةً:
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
tokenjuice: {
|
||||
enabled: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## ما الذي يغيّره tokenjuice
|
||||
|
||||
- يضغط نتائج `exec` و`bash` المليئة بالضوضاء قبل إعادتها إلى الجلسة.
|
||||
- يُبقي تنفيذ الأمر الأصلي من دون تغيير.
|
||||
- يحافظ على قراءات محتوى الملفات الدقيقة والأوامر الأخرى التي ينبغي أن يتركها tokenjuice بصيغتها الخام.
|
||||
- يظل اختياريًا: عطّل Plugin إذا كنت تريد مخرجات حرفية في كل مكان.
|
||||
|
||||
## تحقّق من أنه يعمل
|
||||
|
||||
1. فعّل Plugin.
|
||||
2. ابدأ جلسة يمكنها استدعاء `exec`.
|
||||
3. شغّل أمرًا مليئًا بالضوضاء مثل `git status`.
|
||||
4. تحقّق من أن نتيجة الأداة المُعادة أقصر وأكثر تنظيمًا من مخرجات shell الخام.
|
||||
|
||||
## تعطيل Plugin
|
||||
|
||||
```bash
|
||||
openclaw config set plugins.entries.tokenjuice.enabled false
|
||||
```
|
||||
|
||||
أو:
|
||||
|
||||
```bash
|
||||
openclaw plugins disable tokenjuice
|
||||
```
|
||||
Loading…
Reference in New Issue
Block a user