openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh ar translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-15 07:23:32 +00:00
parent 607f938dc1
commit e67abf997c
11 changed files with 2767 additions and 2636 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

657
docs/ar/channels/matrix.md
View File

File diff suppressed because it is too large Load Diff

181
docs/ar/concepts/dreaming.md
View File

@ -1,136 +1,141 @@
---
read_when:
- تريد أن يعمل ترقية الذاكرة تلقائيًا
- تريد فهم ما الذي تفعله كل مرحلة من مراحل الأحلام
- تريد ضبط الدمج دون تلويث `MEMORY.md`
summary: دمج ذاكرة في الخلفية بمراحل خفيفة وعميقة وREM بالإضافة إلى يوميات الأحلام
title: الأحلام (تجريبي)
- تريد أن تفهم ما الذي تفعله كل مرحلة من مراحل Dreaming
- تريد ضبط التوحيد دون تلويث `MEMORY.md`
summary: توحيد الذاكرة في الخلفية مع مراحل خفيفة وعميقة وREM بالإضافة إلى يوميات الأحلام
title: Dreaming (تجريبي)
x-i18n:
generated_at: "2026-04-09T01:27:52Z"
generated_at: "2026-04-15T07:17:44Z"
model: gpt-5.4
provider: openai
source_hash: 26476eddb8260e1554098a6adbb069cf7f5e284cf2e09479c6d9d8f8b93280ef
source_hash: 5882a5068f2eabe54ca9893184e5385330a432b921870c38626399ce11c31e25
source_path: concepts/dreaming.md
workflow: 15
---
# الأحلام (تجريبي)
# Dreaming (تجريبي)
الأحلام هي نظام دمج الذاكرة في الخلفية داخل `memory-core`.
وهي تساعد OpenClaw على نقل الإشارات القوية قصيرة الأمد إلى ذاكرة دائمة مع
إبقاء العملية قابلة للتفسير والمراجعة.
Dreaming هو نظام توحيد الذاكرة في الخلفية داخل `memory-core`.
يساعد OpenClaw على نقل الإشارات القوية قصيرة الأجل إلى ذاكرة دائمة مع
الحفاظ على العملية قابلة للتفسير والمراجعة.
الأحلام **تعمل بالاشتراك** وهي معطلة افتراضيًا.
Dreaming هو **اختياري** ومُعطَّل افتراضيًا.
## ما الذي تكتبه الأحلام
## ما الذي يكتبه Dreaming
تحتفظ الأحلام بنوعين من المخرجات:
يحتفظ Dreaming بنوعين من المخرجات:
- **حالة الآلة** في `memory/.dreams/` (مخزن الاستدعاء، إشارات المراحل، نقاط تحقق الإدخال، والأقفال).
- **حالة الآلة** في `memory/.dreams/` (مخزن الاسترجاع، إشارات المراحل، نقاط تحقق الاستيعاب، الأقفال).
- **مخرجات قابلة للقراءة البشرية** في `DREAMS.md` (أو `dreams.md` الموجود) وملفات تقارير المراحل الاختيارية ضمن `memory/dreaming/<phase>/YYYY-MM-DD.md`.
تظل الترقية طويلة الأمد تكتب فقط إلى `MEMORY.md`.
تستمر الترقية طويلة الأجل في الكتابة إلى `MEMORY.md` فقط.
## نموذج المراحل
تستخدم الأحلام ثلاث مراحل تعاونية:
يستخدم Dreaming ثلاث مراحل تعاونية:
| المرحلة | الغرض | الكتابة الدائمة |
| ----- | ----------------------------------------- | ----------------- |
| خفيفة | فرز وتجهيز المواد الحديثة قصيرة الأمد | لا |
| عميقة | تقييم المرشحين الدائمين وترقيتهم | نعم (`MEMORY.md`) |
| REM | التأمل في الموضوعات والأفكار المتكررة | لا |
| المرحلة | الغرض | الكتابة الدائمة |
| ------- | --------------------------------------- | ------------------- |
| Light | فرز وتجهيز المواد الحديثة قصيرة الأجل | لا |
| Deep | تقييم المرشحين الدائمين وترقيتهم | نعم (`MEMORY.md`) |
| REM | التأمل في السمات والأفكار المتكررة | لا |
هذه المراحل تفاصيل تنفيذ داخلية وليست "أوضاعًا" منفصلة يضبطها المستخدم.
هذه المراحل هي تفاصيل تنفيذ داخلية، وليست "أوضاعًا" منفصلة
يمكن للمستخدم إعدادها.
### المرحلة الخفيفة
### مرحلة Light
تستوعب المرحلة الخفيفة إشارات الذاكرة اليومية الحديثة وآثار الاستدعاء، وتزيل
التكرار منها، وتجهز أسطرًا مرشحة.
تستوعب مرحلة Light إشارات الذاكرة اليومية الحديثة وآثار الاسترجاع، وتزيل التكرار منها،
وتجهز سطورًا مرشحة.
- تقرأ من حالة الاستدعاء قصيرة الأمد، وملفات الذاكرة اليومية الحديثة، ونصوص الجلسات المنقحة عند توفرها.
- تكتب كتلة `## Light Sleep` مُدارة عندما يتضمن التخزين مخرجات مضمنة.
- تسجل إشارات تعزيز لاستخدامها لاحقًا في الترتيب العميق.
- تقرأ من حالة الاسترجاع قصيرة الأجل، وملفات الذاكرة اليومية الحديثة، ونصوص الجلسات المنقحة عند توفرها.
- تكتب كتلة `## Light Sleep` مُدارة عندما يتضمن التخزين مخرجات مضمّنة.
- تسجل إشارات تعزيز لاستخدامها لاحقًا في ترتيب Deep.
- لا تكتب أبدًا إلى `MEMORY.md`.
### المرحلة العميقة
### مرحلة Deep
تحدد المرحلة العميقة ما الذي يصبح ذاكرة طويلة الأمد.
تقرر مرحلة Deep ما الذي يصبح ذاكرة طويلة الأجل.
- ترتب المرشحين باستخدام تقييم موزون وبوابات عتبة.
- ترتب المرشحين باستخدام التقييم الموزون وبوابات العتبة.
- تتطلب اجتياز `minScore` و`minRecallCount` و`minUniqueQueries`.
- تعيد إماهة المقاطع من الملفات اليومية الحية قبل الكتابة، لذلك يتم تخطي المقاطع القديمة أو المحذوفة.
- تعيد ترطيب المقتطفات من الملفات اليومية الحية قبل الكتابة، لذلك يتم تخطي المقتطفات القديمة أو المحذوفة.
- تُلحق الإدخالات المُرقّاة إلى `MEMORY.md`.
- تكتب ملخص `## Deep Sleep` داخل `DREAMS.md`، وتكتب اختياريًا إلى `memory/dreaming/deep/YYYY-MM-DD.md`.
- تكتب ملخص `## Deep Sleep` داخل `DREAMS.md`، ويمكنها اختياريًا الكتابة إلى `memory/dreaming/deep/YYYY-MM-DD.md`.
### مرحلة REM
تستخرج مرحلة REM الأنماط والإشارات التأملية.
- تبني ملخصات للموضوعات والتأملات من الآثار قصيرة الأمد الحديثة.
- تكتب كتلة `## REM Sleep` مُدارة عندما يتضمن التخزين مخرجات مضمنة.
- تسجل إشارات تعزيز REM المستخدمة في الترتيب العميق.
- تُنشئ ملخصات للسمات والتأملات من آثار قصيرة الأجل حديثة.
- تكتب كتلة `## REM Sleep` مُدارة عندما يتضمن التخزين مخرجات مضمّنة.
- تسجل إشارات تعزيز REM المستخدمة في ترتيب Deep.
- لا تكتب أبدًا إلى `MEMORY.md`.
## إدخال نصوص الجلسات
## استيعاب نصوص الجلسات
يمكن للأحلام أن تستوعب نصوص الجلسات المنقحة في مجموعة بيانات الأحلام. عندما
تكون النصوص متاحة، يتم تمريرها إلى المرحلة الخفيفة إلى جانب إشارات الذاكرة
اليومية وآثار الاستدعاء. ويتم تنقيح المحتوى الشخصي والحساس قبل الإدخال.
يمكن لـ Dreaming استيعاب نصوص الجلسات المنقحة ضمن corpus الخاص بـ Dreaming. عند
توفر النصوص، يتم تمريرها إلى مرحلة Light جنبًا إلى جنب مع إشارات
الذاكرة اليومية وآثار الاسترجاع. يتم تنقيح المحتوى الشخصي والحساس
قبل الاستيعاب.
## يوميات الأحلام
## Dream Diary
تحتفظ الأحلام أيضًا بسرد **يوميات الأحلام** في `DREAMS.md`.
بعد أن تمتلك كل مرحلة مادة كافية، يشغّل `memory-core` محاولةً بأفضل جهد
لدورة وكيل فرعي في الخلفية (باستخدام نموذج وقت التشغيل الافتراضي) ثم يُلحق
إدخال يوميات قصيرًا.
يحتفظ Dreaming أيضًا بـ **Dream Diary** سردية داخل `DREAMS.md`.
بعد أن تتوفر لكل مرحلة مادة كافية، يشغّل `memory-core`
دورة فرعية في الخلفية بأفضل جهد ممكن (باستخدام نموذج وقت التشغيل الافتراضي)
ويُلحق إدخال يوميات قصيرًا.
هذه اليوميات مخصصة للقراءة البشرية في واجهة Dreams، وليست مصدرًا للترقية.
تُستبعد ملفات اليوميات/التقارير التي يُنشئها Dreaming من
الترقية قصيرة الأجل. فقط مقتطفات الذاكرة المرتكزة على مصادر حقيقية تكون مؤهلة للترقية إلى
`MEMORY.md`.
يوجد أيضًا مسار تعبئة تاريخية مرتكز للمراجعة وأعمال الاستعادة:
يوجد أيضًا مسار تعبئة تاريخية مرتكز على مصادر حقيقية لأعمال المراجعة والاستعادة:
- `memory rem-harness --path ... --grounded` يعرض معاينة لمخرجات يوميات مرتكزة من ملاحظات `YYYY-MM-DD.md` التاريخية.
- `memory rem-backfill --path ...` يكتب إدخالات يوميات مرتكزة قابلة للعكس إلى `DREAMS.md`.
- `memory rem-backfill --path ... --stage-short-term` يجهز مرشحين دائمين مرتكزين في نفس مخزن الأدلة قصيرة الأمد الذي تستخدمه المرحلة العميقة العادية بالفعل.
- `memory rem-backfill --rollback` و`--rollback-short-term` يزيلان عناصر التعبئة الراجعة المُجهزة هذه دون المساس بإدخالات اليوميات العادية أو الاستدعاء الحي قصير الأمد.
- يعاين `memory rem-harness --path ... --grounded` مخرجات يوميات مرتكزة على مصادر حقيقية من ملاحظات `YYYY-MM-DD.md` التاريخية.
- يكتب `memory rem-backfill --path ...` إدخالات يوميات مرتكزة قابلة للعكس داخل `DREAMS.md`.
- يُجهّز `memory rem-backfill --path ... --stage-short-term` مرشحين دائمين مرتكزين على مصادر حقيقية في نفس مخزن الأدلة قصيرة الأجل الذي تستخدمه مرحلة Deep العادية بالفعل.
- يزيل `memory rem-backfill --rollback` و`--rollback-short-term` ملفات التعبئة المرحلية هذه دون المساس بإدخالات اليوميات العادية أو الاسترجاع الحي قصير الأجل.
تعرض واجهة Control UI نفس تدفق التعبئة الراجعة/إعادة التعيين لليوميات حتى تتمكن من
فحص النتائج في مشهد Dreams قبل تقرير ما إذا كان المرشحون المرتكزون
يستحقون الترقية. ويعرض المشهد أيضًا مسارًا مرتكزًا منفصلًا حتى تتمكن من رؤية
إدخالات المدى القصير المُجهزة التي جاءت من إعادة تشغيل تاريخية، والعناصر
المُرقّاة التي قادها التأريض، ومسح الإدخالات المُجهزة المرتكزة فقط دون
المساس بحالة المدى القصير الحية العادية.
تعرض واجهة Control أيضًا نفس تدفق تعبئة/إعادة تعيين اليوميات بحيث يمكنك فحص
النتائج في مشهد Dreams قبل أن تقرر ما إذا كانت المرشحات المرتكزة على مصادر حقيقية
تستحق الترقية. ويعرض المشهد أيضًا مسارًا مرتكزًا مميزًا حتى تتمكن من رؤية
إدخالات المرحلة قصيرة الأجل التي جاءت من إعادة تشغيل تاريخية، والعناصر المُرقّاة
التي كانت مدفوعة بالمحتوى المرتكز، ومسح الإدخالات المرحلية المرتكزة فقط دون
المساس بحالة الإدخالات الحية قصيرة الأجل العادية.
## إشارات الترتيب العميق
## إشارات ترتيب Deep
يستخدم الترتيب العميق ست إشارات أساسية موزونة بالإضافة إلى تعزيز المراحل:
يستخدم ترتيب Deep ست إشارات أساسية موزونة بالإضافة إلى تعزيز المراحل:
| الإشارة | الوزن | الوصف |
| ------------------- | ------ | ------------------------------------------------- |
| التكرار | 0.24 | عدد إشارات المدى القصير التي راكمها الإدخال |
| الصلة | 0.30 | متوسط جودة الاسترجاع للإدخال |
| تنوع الاستعلامات | 0.15 | سياقات الاستعلام/اليوم المميزة التي أظهرته |
| الحداثة | 0.15 | درجة حداثة متناقصة بمرور الوقت |
| الدمج | 0.10 | قوة التكرار عبر عدة أيام |
| الثراء المفاهيمي | 0.06 | كثافة وسوم المفاهيم من المقطع/المسار |
| الإشارة | الوزن | الوصف |
| ------------------- | ----- | ------------------------------------------------ |
| التكرار | 0.24 | عدد الإشارات قصيرة الأجل التي تراكمت للإدخال |
| الصلة | 0.30 | متوسط جودة الاسترجاع للإدخال |
| تنوع الاستعلامات | 0.15 | سياقات الاستعلام/اليوم المميزة التي أظهرته |
| الحداثة | 0.15 | درجة حداثة متضائلة مع الزمن |
| التوحيد | 0.10 | قوة التكرار عبر أيام متعددة |
| الثراء المفاهيمي | 0.06 | كثافة وسوم المفاهيم من المقتطف/المسار |
تضيف إصابات المرحلتين الخفيفة وREM دفعة صغيرة متناقصة مع الحداثة من
تضيف إصابات مرحلتي Light وREM دفعة صغيرة متضائلة مع الزمن من
`memory/.dreams/phase-signals.json`.
## الجدولة
عند التمكين، يدير `memory-core` تلقائيًا مهمة cron واحدة لاجتياز كامل
للأحلام. يشغّل كل اجتياز المراحل بالترتيب: خفيفة -> REM -> عميقة.
عند تفعيله، يدير `memory-core` تلقائيًا مهمة Cron واحدة لاجتياز Dreaming كامل.
يشغّل كل اجتياز المراحل بالترتيب: light -> REM -> deep.
سلوك الوتيرة الافتراضية:
| الإعداد | الافتراضي |
| -------------------- | ----------- |
| الإعداد | الافتراضي |
| -------------------- | ---------- |
| `dreaming.frequency` | `0 3 * * *` |
## البدء السريع
فعّل الأحلام:
فعّل Dreaming:
```json
{
@ -148,7 +153,7 @@ x-i18n:
}
```
فعّل الأحلام مع وتيرة اجتياز مخصصة:
فعّل Dreaming مع وتيرة اجتياز مخصصة:
```json
{
@ -188,17 +193,17 @@ openclaw memory promote --limit 5
openclaw memory status --deep
```
يستخدم `memory promote` اليدوي عتبات المرحلة العميقة افتراضيًا ما لم يتم
تجاوزها بعلامات CLI.
يستخدم `memory promote` اليدوي عتبات مرحلة Deep افتراضيًا ما لم يتم تجاوزها
باستخدام أعلام CLI.
اشرح لماذا سيُرقّى مرشح محدد أو لن يُرقّى:
اشرح لماذا سيُرقّى مرشح معيّن أو لن يُرقّى:
```bash
openclaw memory promote-explain "router vlan"
openclaw memory promote-explain "router vlan" --json
```
اعرض تأملات REM وحقائق المرشحين ومخرجات الترقية العميقة دون
عاين تأملات REM، والحقائق المرشحة، ومخرجات ترقية Deep دون
كتابة أي شيء:
```bash
@ -210,27 +215,27 @@ openclaw memory rem-harness --json
توجد جميع الإعدادات تحت `plugins.entries.memory-core.config.dreaming`.
| المفتاح | الافتراضي |
| ----------- | ----------- |
| `enabled` | `false` |
| المفتاح | الافتراضي |
| ---------- | ---------- |
| `enabled` | `false` |
| `frequency` | `0 3 * * *` |
سياسة المراحل والعتبات وسلوك التخزين هي تفاصيل تنفيذ داخلية
(وليست إعدادات موجّهة للمستخدم).
سياسة المراحل، والعتبات، وسلوك التخزين هي تفاصيل تنفيذ داخلية
(وليست إعدادات موجهة للمستخدم).
راجع [مرجع إعدادات الذاكرة](/ar/reference/memory-config#dreaming-experimental)
للحصول على القائمة الكاملة للمفاتيح.
## واجهة Dreams
عند التمكين، تعرض علامة تبويب **Dreams** في Gateway ما يلي:
عند التفعيل، تعرض علامة التبويب **Dreams** في Gateway ما يلي:
- حالة تمكين الأحلام الحالية
- حالة على مستوى المرحلة ووجود الاجتياز المُدار
- أعداد المدى القصير، والمرتكز، والإشارات، وما تمت ترقيته اليوم
- حالة تفعيل Dreaming الحالية
- حالة على مستوى المراحل ووجود اجتياز مُدار
- أعداد العناصر قصيرة الأجل، والمرتكزة، والإشارات، والمُرقّاة اليوم
- توقيت التشغيل المجدول التالي
- مسار Scene مرتكز منفصل لإدخالات إعادة التشغيل التاريخية المُجهزة
- قارئ يوميات أحلام قابل للتوسيع ومدعوم بواسطة `doctor.memory.dreamDiary`
- مسار Scene مرتكز مميز لإدخالات إعادة التشغيل التاريخية المرحلية
- قارئ Dream Diary قابل للتوسيع ومدعوم بواسطة `doctor.memory.dreamDiary`
## ذو صلة

91
docs/ar/gateway/local-models.md
View File

@ -1,28 +1,28 @@
---
read_when:
- تريد تقديم النماذج من جهاز GPU الخاص بك
- أنت تُعدّ LM Studio أو وكيلاً متوافقًا مع OpenAI
- أنت تقوم بإعداد LM Studio أو وكيل متوافق مع OpenAI
- تحتاج إلى أكثر إرشادات النماذج المحلية أمانًا
summary: شغّل OpenClaw على نماذج اللغة الكبيرة المحلية (LM Studio وvLLM وLiteLLM ونقاط نهاية OpenAI المخصّصة)
summary: شغّل OpenClaw على نماذج LLM المحلية (LM Studio، vLLM، LiteLLM، ونقاط نهاية OpenAI المخصّصة)
title: النماذج المحلية
x-i18n:
generated_at: "2026-04-14T07:17:43Z"
generated_at: "2026-04-15T07:17:57Z"
model: gpt-5.4
provider: openai
source_hash: 1544c522357ba4b18dfa6d05ea8d60c7c6262281b53863d9aee7002464703ca7
source_hash: 8778cc1c623a356ff3cf306c494c046887f9417a70ec71e659e4a8aae912a780
source_path: gateway/local-models.md
workflow: 15
---
# النماذج المحلية
التشغيل المحلي ممكن، لكن OpenClaw يتوقع سياقًا كبيرًا + دفاعات قوية ضد حقن التلقين. البطاقات الصغيرة تقتطع السياق وتُضعف الأمان. استهدف مستوى عالٍ: **استوديوهَا Mac Studio مضبوطتان للحد الأقصى على الأقل أو منصة GPU مكافئة (~أكثر من 30 ألف دولار)**. تعمل وحدة GPU واحدة بسعة **24 GB** فقط مع التلقينات الأخف وبزمن استجابة أعلى. استخدم **أكبر / البديل الكامل الحجم من النموذج الذي يمكنك تشغيله**؛ إذ إن نقاط التحقق المضغوطة بقوة أو “الصغيرة” ترفع مخاطر حقن التلقين (راجع [الأمان](/ar/gateway/security)).
التشغيل المحلي ممكن، لكن OpenClaw يتوقع سياقًا كبيرًا + دفاعات قوية ضد حقن المطالبات. البطاقات الصغيرة تقطع السياق وتُضعف الأمان. استهدف مستوى مرتفعًا: **استوديوهَي Mac Studio على الأقل بكامل المواصفات أو منصة GPU مكافئة (~30 ألف دولار فأكثر)**. تعمل بطاقة GPU واحدة بسعة **24 GB** فقط مع المطالبات الأخف وزمن استجابة أعلى. استخدم **أكبر / النسخة كاملة الحجم من النموذج التي يمكنك تشغيلها**؛ فالإصدارات المضغوطة بشدة أو نقاط التحقق “الصغيرة” تزيد من مخاطر حقن المطالبات (راجع [الأمان](/ar/gateway/security)).
إذا كنت تريد إعدادًا محليًا بأقل قدر من التعقيد، فابدأ بـ [LM Studio](/ar/providers/lmstudio) أو [Ollama](/ar/providers/ollama) و`openclaw onboard`. هذه الصفحة هي الدليل العملي الموجَّه للحِزم المحلية الأعلى مستوى وخوادم OpenAI-compatible المحلية المخصّصة.
إذا كنت تريد إعدادًا محليًا بأقل قدر من التعقيد، فابدأ بـ [LM Studio](/ar/providers/lmstudio) أو [Ollama](/ar/providers/ollama) واستخدم `openclaw onboard`. هذه الصفحة هي الدليل العملي الموجّه للبنى المحلية الأعلى مستوى وخوادم OpenAI المحلية المخصّصة المتوافقة.
## الموصى به: LM Studio + نموذج محلي كبير (Responses API)
أفضل حزمة محلية حاليًا. حمّل نموذجًا كبيرًا في LM Studio (على سبيل المثال، إصدارًا كامل الحجم من Qwen أو DeepSeek أو Llama)، ثم فعّل الخادم المحلي (الافتراضي `http://127.0.0.1:1234`) واستخدم Responses API لإبقاء الاستدلال منفصلًا عن النص النهائي.
أفضل بنية محلية حاليًا. حمّل نموذجًا كبيرًا في LM Studio (على سبيل المثال، إصدارًا كامل الحجم من Qwen أو DeepSeek أو Llama)، وفعّل الخادم المحلي (الافتراضي `http://127.0.0.1:1234`)، واستخدم Responses API للحفاظ على فصل الاستدلال عن النص النهائي.
```json5
{
@ -59,18 +59,18 @@ x-i18n:
}
```
**قائمة الإعداد**
**قائمة إعداد سريعة**
- ثبّت LM Studio: [https://lmstudio.ai](https://lmstudio.ai)
- في LM Studio، نزّل **أكبر إصدار نموذج متاح** (تجنّب البدائل “الصغيرة” أو المضغوطة بشدة)، وابدأ الخادم، وتأكد من أن `http://127.0.0.1:1234/v1/models` يعرضه.
- في LM Studio، نزّل **أكبر إصدار متاح من النموذج** (تجنّب الإصدارات “الصغيرة”/المضغوطة بشدة)، ثم شغّل الخادم، وتأكد من أن `http://127.0.0.1:1234/v1/models` يعرضه.
- استبدل `my-local-model` بمعرّف النموذج الفعلي الظاهر في LM Studio.
- أبقِ النموذج محمّلًا؛ فالتحميل البارد يضيف زمن بدء تشغيل.
- اضبط `contextWindow`/`maxTokens` إذا كان إصدار LM Studio لديك مختلفًا.
- بالنسبة إلى WhatsApp، التزم بـ Responses API حتى لا يُرسل إلا النص النهائي.
- أبقِ النموذج محمّلًا؛ فالتحميل البارد يضيف زمن بدء.
- اضبط `contextWindow` و`maxTokens` إذا كان إصدار LM Studio لديك مختلفًا.
- بالنسبة إلى WhatsApp، التزم باستخدام Responses API بحيث لا يُرسل سوى النص النهائي.
أبقِ النماذج المستضافة مُعدّة حتى عند التشغيل المحلي؛ استخدم `models.mode: "merge"` حتى تظل خيارات الرجوع الاحتياطي متاحة.
أبقِ النماذج المستضافة مهيأة حتى عند التشغيل المحلي؛ استخدم `models.mode: "merge"` حتى تظل بدائل التراجع متاحة.
### إعداد هجين: نموذج مستضاف أساسي، ونموذج محلي احتياطي
### إعداد هجين: نموذج مستضاف أساسي، وتراجع محلي
```json5
{
@ -113,16 +113,16 @@ x-i18n:
### محلي أولًا مع شبكة أمان مستضافة
بدّل ترتيب الأساسي والاحتياطي؛ وأبقِ كتلة المزوّدين نفسها و`models.mode: "merge"` حتى تتمكن من الرجوع إلى Sonnet أو Opus عندما يتعطل الجهاز المحلي.
بدّل ترتيب النموذج الأساسي وبدائل التراجع؛ وأبقِ كتلة providers نفسها و`models.mode: "merge"` حتى تتمكن من التراجع إلى Sonnet أو Opus عندما يتعطل الجهاز المحلي.
### الاستضافة الإقليمية / توجيه البيانات
- تتوفر أيضًا بدائل MiniMax/Kimi/GLM المستضافة على OpenRouter مع نقاط نهاية مثبّتة حسب المنطقة (مثلًا، مستضافة في الولايات المتحدة). اختر البديل الإقليمي هناك للإبقاء على حركة البيانات داخل النطاق القضائي الذي تختاره مع الاستمرار في استخدام `models.mode: "merge"` كخيارات احتياطية لـ Anthropic/OpenAI.
- يظل التشغيل المحلي فقط هو أقوى مسار للخصوصية؛ أما التوجيه الإقليمي المستضاف فهو الحل الوسط عندما تحتاج إلى مزايا المزوّد لكنك تريد التحكم في تدفق البيانات.
- تتوفر أيضًا إصدارات MiniMax/Kimi/GLM المستضافة على OpenRouter مع نقاط نهاية مثبتة على مناطق محددة (مثل الاستضافة داخل الولايات المتحدة). اختر الإصدار الإقليمي هناك لإبقاء الحركة ضمن النطاق القضائي الذي تختاره، مع الاستمرار في استخدام `models.mode: "merge"` لبدائل التراجع من Anthropic/OpenAI.
- يظل التشغيل المحلي فقط هو المسار الأقوى من ناحية الخصوصية؛ أما التوجيه الإقليمي للاستضافة فهو الحل الوسط عندما تحتاج إلى ميزات المزوّد لكنك تريد التحكم في تدفق البيانات.
## وكلاء محليون آخرون متوافقون مع OpenAI
يعمل vLLM وLiteLLM وOAI-proxy أو البوابات المخصّصة إذا كانت توفّر نقطة نهاية `/v1` بأسلوب OpenAI. استبدل كتلة المزوّد أعلاه بنقطة النهاية ومعرّف النموذج لديك:
يمكن استخدام vLLM أو LiteLLM أو OAI-proxy أو البوابات المخصصة إذا كانت توفّر نقطة نهاية `/v1` بأسلوب OpenAI. استبدل كتلة provider أعلاه بنقطة النهاية ومعرّف النموذج الخاصين بك:
```json5
{
@ -150,42 +150,45 @@ x-i18n:
}
```
أبقِ `models.mode: "merge"` حتى تظل النماذج المستضافة متاحة كخيارات احتياطية.
أبقِ `models.mode: "merge"` حتى تظل النماذج المستضافة متاحة كبدائل تراجع.
ملاحظة سلوكية لخلفيات `/v1` المحلية/الوسيطة:
ملاحظة سلوكية للخلفيات المحلية/المعتمدة على وكيل `/v1`:
- يتعامل OpenClaw مع هذه المسارات على أنها مسارات وسيطة متوافقة مع OpenAI، وليست
- يتعامل OpenClaw مع هذه المسارات على أنها مسارات وكيل متوافقة مع OpenAI، وليست
نقاط نهاية OpenAI أصلية
- لا ينطبق هنا تشكيل الطلبات الخاص بـ OpenAI الأصلية فقط: لا
`service_tier`، ولا `store` في Responses، ولا تشكيل حمولة التوافق مع استدلال OpenAI،
ولا تلميحات ذاكرة التخزين المؤقت للتلقين
- لا تُحقن ترويسات الإسناد المخفية الخاصة بـ OpenClaw (`originator` و`version` و`User-Agent`)
في عناوين URL المخصّصة لهذه الوكلاء
- لا ينطبق هنا تشكيل الطلبات الخاص بـ OpenAI الأصلي فقط: لا يوجد
`service_tier`، ولا `store` الخاص بـ Responses، ولا تشكيل حمولة
التوافق مع الاستدلال في OpenAI، ولا تلميحات cache للمطالبة
- لا يتم حقن ترويسات الإسناد المخفية الخاصة بـ OpenClaw (`originator` و`version` و`User-Agent`)
على عناوين URL الخاصة بهذه الوكلاء المخصصة
ملاحظات التوافق للخلفيات الأكثر تشددًا والمتوافقة مع OpenAI:
ملاحظات التوافق للخلفيات الأكثر صرامة والمتوافقة مع OpenAI:
- بعض الخوادم تقبل فقط `messages[].content` كسلسلة نصية في Chat Completions، وليس
مصفوفات أجزاء المحتوى المهيكلة. اضبط
`models.providers.<provider>.models[].compat.requiresStringContent: true` لنقاط
النهاية تلك.
- بعض الخلفيات المحلية الأصغر أو الأكثر تشددًا تكون غير مستقرة مع شكل التلقين الكامل
لبيئة تشغيل الوكلاء في OpenClaw، خاصةً عند تضمين مخططات الأدوات. إذا كانت
الخلفية تعمل مع استدعاءات `/v1/chat/completions` المباشرة الصغيرة لكنها تفشل في
أدوار الوكيل العادية في OpenClaw، فجرّب أولًا
- تقبل بعض الخوادم فقط `messages[].content` كسلسلة نصية في Chat Completions، وليس
مصفوفات أجزاء المحتوى المنظمة. اضبط
`models.providers.<provider>.models[].compat.requiresStringContent: true` لتلك
النقاط النهائية.
- تكون بعض الخلفيات المحلية الأصغر أو الأكثر صرامة غير مستقرة مع الشكل الكامل
لمطالبة بيئة تشغيل الوكيل في OpenClaw، خاصةً عند تضمين مخططات الأدوات. إذا كانت
الخلفية تعمل مع طلبات `/v1/chat/completions` المباشرة والصغيرة لكنها تفشل في
دورات الوكيل العادية في OpenClaw، فجرّب أولًا
`agents.defaults.localModelMode: "lean"` لإسقاط الأدوات الافتراضية الثقيلة
مثل `browser` و`cron` و`message`؛ وإذا استمر الفشل بعد ذلك، فجرّب
`models.providers.<provider>.models[].compat.supportsTools: false`.
- إذا استمرت الخلفية في الفشل فقط مع تشغيلات OpenClaw الأكبر، فعادةً ما تكون المشكلة
في سعة النموذج/الخادم المصدر أو في خطأ في الخلفية، وليس في طبقة النقل الخاصة بـ OpenClaw.
- إذا كانت الخلفية لا تزال تفشل فقط في تشغيلات OpenClaw الأكبر، فغالبًا تكون
المشكلة المتبقية سعة النموذج/الخادم من الجهة العليا أو خطأ في الخلفية، وليس
في طبقة النقل الخاصة بـ OpenClaw.
## استكشاف الأخطاء وإصلاحها
- هل يستطيع Gateway الوصول إلى الوكيل؟ `curl http://127.0.0.1:1234/v1/models`.
- هل تستطيع Gateway الوصول إلى الوكيل؟ `curl http://127.0.0.1:1234/v1/models`.
- هل تم إلغاء تحميل نموذج LM Studio؟ أعد تحميله؛ فالبدء البارد سبب شائع لـ “التعليق”.
- يحذّر OpenClaw عندما تكون نافذة السياق المكتشفة أقل من **32k** ويمنع التشغيل عندما تكون أقل من **16k**. إذا واجهت هذا الفحص المسبق، فارفع حد السياق في الخادم/النموذج أو اختر نموذجًا أكبر.
- أخطاء في السياق؟ خفّض `contextWindow` أو ارفع حد الخادم لديك.
- هل يعيد الخادم المتوافق مع OpenAI الخطأ `messages[].content ... expected a string`؟
- أخطاء السياق؟ خفّض `contextWindow` أو ارفع حد الخادم لديك.
- هل يُرجع الخادم المتوافق مع OpenAI الخطأ `messages[].content ... expected a string`؟
أضف `compat.requiresStringContent: true` إلى إدخال ذلك النموذج.
- هل تعمل استدعاءات `/v1/chat/completions` الصغيرة المباشرة، لكن `openclaw infer model run`
- تعمل طلبات `/v1/chat/completions` المباشرة والصغيرة، لكن `openclaw infer model run`
يفشل مع Gemma أو نموذج محلي آخر؟ عطّل مخططات الأدوات أولًا باستخدام
`compat.supportsTools: false`، ثم اختبر مجددًا. إذا استمر الخادم في التعطل فقط
مع تلقينات OpenClaw الأكبر، فاعتبر ذلك قيدًا في الخادم/النموذج المصدر.
- الأمان: تتجاوز النماذج المحلية عوامل التصفية الموجودة لدى المزوّد؛ لذا اجعل الوكلاء محدودي النطاق وأبقِ Compaction مفعّلًا لتقليل نطاق تأثير حقن التلقين.
`compat.supportsTools: false`، ثم أعد الاختبار. إذا استمر الخادم في الانهيار فقط
مع مطالبات OpenClaw الأكبر، فاعتبر ذلك قيدًا في الخادم/النموذج من الجهة العليا.
- الأمان: تتخطى النماذج المحلية عوامل التصفية على جهة المزوّد؛ أبقِ الوكلاء محدودي النطاق وفعّل Compaction للحد من نطاق تأثير حقن المطالبات.

877
docs/ar/help/testing.md
View File

File diff suppressed because it is too large Load Diff

1669
docs/ar/plugins/architecture.md
View File

File diff suppressed because it is too large Load Diff

556
docs/ar/plugins/manifest.md
View File

@ -1,74 +1,75 @@
---
read_when:
- أنت تبني Plugin لـ OpenClaw
- أنت تقوم ببناء Plugin لـ OpenClaw
- تحتاج إلى شحن مخطط إعدادات Plugin أو تصحيح أخطاء التحقق من صحة Plugin
summary: متطلبات Plugin manifest + مخطط JSON ‏(التحقق الصارم من صحة الإعدادات)
summary: متطلبات Plugin manifest + مخطط JSON (التحقق الصارم من صحة الإعدادات)
title: Plugin Manifest
x-i18n:
generated_at: "2026-04-12T23:28:37Z"
generated_at: "2026-04-15T07:18:06Z"
model: gpt-5.4
provider: openai
source_hash: 93b57c7373e4ccd521b10945346db67991543bd2bed4cc8b6641e1f215b48579
source_hash: ba2183bfa8802871e4ef33a0ebea290606e8351e9e83e25ee72456addb768730
source_path: plugins/manifest.md
workflow: 15
---
# Plugin manifest ‏(`openclaw.plugin.json`)
# Plugin manifest (`openclaw.plugin.json`)
هذه الصفحة مخصّصة فقط لـ **Plugin manifest الأصلي في OpenClaw**.
للتعرف على تخطيطات الحزم المتوافقة، راجع [حزم Plugin](/ar/plugins/bundles).
للاطّلاع على تنسيقات الحِزم المتوافقة، راجع [Plugin bundles](/ar/plugins/bundles).
تستخدم تنسيقات الحزم المتوافقة ملفات manifest مختلفة:
تستخدم تنسيقات الحِزم المتوافقة ملفات manifest مختلفة:
- حزمة Codex: `.codex-plugin/plugin.json`
- حزمة Claude: `.claude-plugin/plugin.json` أو تخطيط مكوّن Claude الافتراضي
من دون manifest
- حزمة Claude: `.claude-plugin/plugin.json` أو تنسيق مكوّن Claude الافتراضي
بدون manifest
- حزمة Cursor: `.cursor-plugin/plugin.json`
يكتشف OpenClaw تلقائيًا تخطيطات الحزم هذه أيضًا، لكنها لا تُتحقق
مقابل مخطط `openclaw.plugin.json` الموضّح هنا.
يكتشف OpenClaw هذه تنسيقات الحِزم تلقائيًا أيضًا، لكنها لا تُتحقَّق
مقارنتها بمخطط `openclaw.plugin.json` الموضَّح هنا.
بالنسبة إلى الحزم المتوافقة، يقرأ OpenClaw حاليًا بيانات تعريف الحزمة بالإضافة إلى
جذور skill المعلنة، وجذور أوامر Claude، والقيم الافتراضية لملف `settings.json` في حزمة Claude،
والقيم الافتراضية لـ Claude bundle LSP، وحِزم Hook المدعومة عندما يطابق التخطيط
توقعات وقت تشغيل OpenClaw.
بالنسبة إلى الحِزم المتوافقة، يقرأ OpenClaw حاليًا بيانات الحزمة الوصفية
بالإضافة إلى جذور Skills المعلنة، وجذور أوامر Claude، والقيم الافتراضية
لملف `settings.json` في حزمة Claude، والقيم الافتراضية لـ Claude bundle LSP،
وحِزم hooks المدعومة عندما يطابق التنسيق توقعات وقت تشغيل OpenClaw.
يجب على كل Plugin أصلي في OpenClaw **أن** يوفّر ملف `openclaw.plugin.json` داخل
**جذر Plugin**. يستخدم OpenClaw هذا الـ manifest للتحقق من صحة الإعدادات
يجب على كل Plugin أصلي في OpenClaw **أن يضمّ** ملف `openclaw.plugin.json` في
**جذر Plugin**. يستخدم OpenClaw هذا manifest للتحقق من صحة الإعدادات
**من دون تنفيذ كود Plugin**. وتُعامل ملفات manifest المفقودة أو غير الصالحة
كأخطاء Plugin وتمنع التحقق من صحة الإعدادات.
على أنها أخطاء في Plugin وتمنع التحقق من صحة الإعدادات.
راجع الدليل الكامل لنظام Plugin: [Plugins](/ar/tools/plugin).
وللاطلاع على نموذج القدرات الأصلي وإرشادات التوافق الخارجي الحالية:
[نموذج القدرات](/ar/plugins/architecture#public-capability-model).
راجع الدليل الكامل لنظام Plugins: [Plugins](/ar/tools/plugin).
وللاطّلاع على نموذج القدرات الأصلي وإرشادات التوافق الخارجي الحالية:
[Capability model](/ar/plugins/architecture#public-capability-model).
## ما وظيفة هذا الملف
## ما الذي يفعله هذا الملف
`openclaw.plugin.json` هو ملف البيانات الوصفية الذي يقرأه OpenClaw قبل أن يحمّل
`openclaw.plugin.json` هو البيانات الوصفية التي يقرأها OpenClaw قبل أن يحمّل
كود Plugin الخاص بك.
استخدمه من أجل:
- هوية Plugin
- التحقق من صحة الإعدادات
- بيانات تعريف المصادقة والإعداد الأولي التي يجب أن تكون متاحة من دون تشغيل وقت تشغيل Plugin
- تلميحات تنشيط خفيفة يمكن لأسطح مستوى التحكم فحصها قبل تحميل وقت التشغيل
- واصفات إعداد خفيفة يمكن لأسطح الإعداد/التهيئة الأولية فحصها قبل
- بيانات auth وonboarding الوصفية التي يجب أن تكون متاحة دون تشغيل وقت تشغيل Plugin
- تلميحات تنشيط منخفضة الكلفة يمكن لأسطح control plane فحصها قبل تحميل وقت التشغيل
- واصفات إعداد منخفضة الكلفة يمكن لأسطح الإعداد/التهيئة الأولية فحصها قبل
تحميل وقت التشغيل
- بيانات تعريف الأسماء البديلة والتمكين التلقائي التي يجب حلها قبل تحميل وقت تشغيل Plugin
- بيانات تعريف مختصرة لملكية عائلة النموذج يجب أن تفعّل
Plugin تلقائيًا قبل تحميل وقت التشغيل
- لقطات ثابتة لملكية القدرات تُستخدم في أسلاك التوافق المجمّعة وتغطية العقود
- بيانات تعريف إعدادات خاصة بالقنوات يجب دمجها في أسطح الكتالوج والتحقق
من دون تحميل وقت التشغيل
- بيانات alias وauto-enable الوصفية التي يجب حلّها قبل تحميل وقت تشغيل Plugin
- بيانات وصفية مختصرة لملكية عائلة النموذج ينبغي أن تفعّل Plugin تلقائيًا قبل تحميل وقت التشغيل
- لقطات ثابتة لملكية القدرات تُستخدم في توصيل التوافق المضمّن وتغطية العقود
- بيانات وصفية منخفضة الكلفة لمشغّل QA يمكن للمضيف المشترك `openclaw qa` فحصها
قبل تحميل وقت تشغيل Plugin
- بيانات وصفية خاصة بإعدادات القنوات ينبغي دمجها في أسطح الفهرسة والتحقق
من الصحة من دون تحميل وقت التشغيل
- تلميحات واجهة المستخدم للإعدادات
لا تستخدمه من أجل:
- تسجيل سلوك وقت التشغيل
- تعريف نقاط دخول الكود
- بيانات تعريف تثبيت npm
- التصريح بنقاط دخول الكود
- بيانات `npm` الوصفية الخاصة بالتثبيت
فهذه تنتمي إلى كود Plugin الخاص بك وإلى `package.json`.
@ -85,7 +86,7 @@ x-i18n:
}
```
## مثال موسّع
## مثال غني
```json
{
@ -143,62 +144,63 @@ x-i18n:
## مرجع الحقول ذات المستوى الأعلى
| الحقل | مطلوب | النوع | المعنى |
| ----------------------------------- | ------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | نعم | `string` | معرّف Plugin القياسي. هذا هو المعرّف المستخدم في `plugins.entries.<id>`. |
| `configSchema` | نعم | `object` | مخطط JSON Schema مضمن لإعدادات هذا Plugin. |
| `enabledByDefault` | لا | `true` | يحدّد أن Plugin المجمّع مفعّل افتراضيًا. احذف هذا الحقل، أو اضبطه على أي قيمة ليست `true`، لترك Plugin معطّلًا افتراضيًا. |
| `legacyPluginIds` | لا | `string[]` | معرّفات قديمة تُطبّع إلى معرّف Plugin القياسي هذا. |
| `autoEnableWhenConfiguredProviders` | لا | `string[]` | معرّفات Provider التي يجب أن تفعّل هذا Plugin تلقائيًا عندما تشير إليها المصادقة أو الإعدادات أو مراجع النموذج. |
| `kind` | لا | `"memory"` \| `"context-engine"` | يصرّح بنوع Plugin حصري يُستخدم بواسطة `plugins.slots.*`. |
| `channels` | لا | `string[]` | معرّفات القنوات التي يملكها هذا Plugin. تُستخدم للاكتشاف والتحقق من صحة الإعدادات. |
| `providers` | لا | `string[]` | معرّفات Provider التي يملكها هذا Plugin. |
| `modelSupport` | لا | `object` | بيانات تعريف مختصرة لعائلة النموذج يملكها manifest وتُستخدم لتحميل Plugin تلقائيًا قبل وقت التشغيل. |
| `cliBackends` | لا | `string[]` | معرّفات واجهات CLI الخلفية للاستدلال التي يملكها هذا Plugin. تُستخدم للتنشيط التلقائي عند بدء التشغيل من مراجع الإعدادات الصريحة. |
| `commandAliases` | لا | `object[]` | أسماء الأوامر التي يملكها هذا Plugin والتي يجب أن تنتج إعدادات خاصة بالـ Plugin وتشخيصات CLI قبل تحميل وقت التشغيل. |
| `providerAuthEnvVars` | لا | `Record<string, string[]>` | بيانات تعريف خفيفة لمتغيرات بيئة مصادقة Provider يمكن لـ OpenClaw فحصها من دون تحميل كود Plugin. |
| `providerAuthAliases` | لا | `Record<string, string>` | معرّفات Provider التي يجب أن تعيد استخدام معرّف Provider آخر لبحث المصادقة، مثل Provider خاص بالبرمجة يشارك مفتاح API الأساسي وملفات تعريف المصادقة مع Provider الأساسي. |
| `channelEnvVars` | لا | `Record<string, string[]>` | بيانات تعريف خفيفة لمتغيرات بيئة القنوات يمكن لـ OpenClaw فحصها من دون تحميل كود Plugin. استخدم هذا لأسطح إعداد القنوات أو المصادقة المعتمدة على البيئة التي ينبغي أن تراها مساعدات بدء التشغيل/الإعداد العامة. |
| `providerAuthChoices` | لا | `object[]` | بيانات تعريف خفيفة لاختيارات المصادقة لمحددات الإعداد الأولي، وحل Provider المفضّل، وربط أعلام CLI البسيطة. |
| `activation` | لا | `object` | تلميحات تنشيط خفيفة لتحميل يعتمد على Provider أو الأمر أو القناة أو المسار أو القدرات. بيانات تعريف فقط؛ وما يزال وقت تشغيل Plugin يملك السلوك الفعلي. |
| `setup` | لا | `object` | واصفات إعداد/تهيئة أولية خفيفة يمكن لأسطح الاكتشاف والإعداد فحصها من دون تحميل وقت تشغيل Plugin. |
| `contracts` | لا | `object` | لقطة قدرات ثابتة مجمّعة لملكية speech وrealtime transcription وrealtime voice وmedia-understanding وimage-generation وmusic-generation وvideo-generation وweb-fetch وweb search والأدوات. |
| `channelConfigs` | لا | `Record<string, object>` | بيانات تعريف إعدادات القنوات المملوكة من manifest والتي تُدمج في أسطح الاكتشاف والتحقق قبل تحميل وقت التشغيل. |
| `skills` | لا | `string[]` | أدلة Skills التي يجب تحميلها، نسبةً إلى جذر Plugin. |
| `name` | لا | `string` | اسم Plugin مقروء للبشر. |
| `description` | لا | `string` | ملخص قصير يظهر في أسطح Plugin. |
| `version` | لا | `string` | إصدار معلوماتي لـ Plugin. |
| `uiHints` | لا | `Record<string, object>` | تسميات واجهة المستخدم، والعناصر النائبة، وتلميحات الحساسية لحقول الإعدادات. |
| الحقل | مطلوب | النوع | ما الذي يعنيه |
| ----------------------------------- | ------ | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | نعم | `string` | المعرّف القياسي لـ Plugin. هذا هو المعرّف المستخدم في `plugins.entries.<id>`. |
| `configSchema` | نعم | `object` | مخطط JSON مضمن لإعدادات هذا Plugin. |
| `enabledByDefault` | لا | `true` | يحدّد أن Plugin مضمّن ومفعّل افتراضيًا. احذفه، أو اضبطه على أي قيمة غير `true`، لترك Plugin معطّلًا افتراضيًا. |
| `legacyPluginIds` | لا | `string[]` | معرّفات قديمة تُطبَّع إلى معرّف Plugin القياسي هذا. |
| `autoEnableWhenConfiguredProviders` | لا | `string[]` | معرّفات providers التي يجب أن تفعّل هذا Plugin تلقائيًا عندما تشير auth أو الإعدادات أو مراجع النماذج إليها. |
| `kind` | لا | `"memory"` \| `"context-engine"` | يصرّح بنوع Plugin حصري يُستخدم بواسطة `plugins.slots.*`. |
| `channels` | لا | `string[]` | معرّفات القنوات المملوكة لهذا Plugin. تُستخدم للاكتشاف والتحقق من صحة الإعدادات. |
| `providers` | لا | `string[]` | معرّفات providers المملوكة لهذا Plugin. |
| `modelSupport` | لا | `object` | بيانات وصفية مختصرة مملوكة للـ manifest لعائلة النماذج وتُستخدم لتحميل Plugin تلقائيًا قبل وقت التشغيل. |
| `cliBackends` | لا | `string[]` | معرّفات backends الخاصة بالاستدلال في CLI والمملوكة لهذا Plugin. تُستخدم للتنشيط التلقائي عند بدء التشغيل من مراجع إعدادات صريحة. |
| `commandAliases` | لا | `object[]` | أسماء الأوامر المملوكة لهذا Plugin والتي يجب أن تنتج إعدادات وتشخيصات CLI مدركة للـ Plugin قبل تحميل وقت التشغيل. |
| `providerAuthEnvVars` | لا | `Record<string, string[]>` | بيانات وصفية منخفضة الكلفة لمتغيرات بيئة auth الخاصة بالـ provider يمكن لـ OpenClaw فحصها من دون تحميل كود Plugin. |
| `providerAuthAliases` | لا | `Record<string, string>` | معرّفات providers التي يجب أن تعيد استخدام معرّف provider آخر لبحث auth، مثل provider للبرمجة يشارك مفتاح API الأساسي وملفات auth التعريفية الخاصة بالـ provider الأساسي. |
| `channelEnvVars` | لا | `Record<string, string[]>` | بيانات وصفية منخفضة الكلفة لمتغيرات بيئة القنوات يمكن لـ OpenClaw فحصها من دون تحميل كود Plugin. استخدم هذا لإعداد القنوات المعتمد على البيئة أو لأسطح auth التي ينبغي أن تراها مساعدات البدء/الإعداد العامة. |
| `providerAuthChoices` | لا | `object[]` | بيانات وصفية منخفضة الكلفة لاختيارات auth من أجل منتقيات onboarding، وحل provider المفضّل، وربط أعلام CLI البسيط. |
| `activation` | لا | `object` | تلميحات تنشيط منخفضة الكلفة لتحميل يعتمد على provider أو command أو channel أو route أو capability. بيانات وصفية فقط؛ لا يزال وقت تشغيل Plugin يملك السلوك الفعلي. |
| `setup` | لا | `object` | واصفات إعداد/تهيئة أولية منخفضة الكلفة يمكن لأسطح الاكتشاف والإعداد فحصها من دون تحميل وقت تشغيل Plugin. |
| `qaRunners` | لا | `object[]` | واصفات منخفضة الكلفة لمشغّلات QA يستخدمها المضيف المشترك `openclaw qa` قبل تحميل وقت تشغيل Plugin. |
| `contracts` | لا | `object` | لقطة قدرات ثابتة ومضمّنة لـ speech وrealtime transcription وrealtime voice وmedia-understanding وimage-generation وmusic-generation وvideo-generation وweb-fetch وweb search وملكية الأدوات. |
| `channelConfigs` | لا | `Record<string, object>` | بيانات وصفية مملوكة للـ manifest لإعدادات القنوات تُدمج في أسطح الاكتشاف والتحقق قبل تحميل وقت التشغيل. |
| `skills` | لا | `string[]` | أدلة Skills المطلوب تحميلها، نسبةً إلى جذر Plugin. |
| `name` | لا | `string` | اسم Plugin مقروء للبشر. |
| `description` | لا | `string` | ملخص قصير يظهر في أسطح Plugin. |
| `version` | لا | `string` | إصدار Plugin لأغراض معلوماتية. |
| `uiHints` | لا | `Record<string, object>` | تسميات واجهة المستخدم، والعناصر النائبة، وتلميحات الحساسية لحقول الإعدادات. |
## مرجع `providerAuthChoices`
يصف كل إدخال في `providerAuthChoices` خيار إعداد أولي أو مصادقة واحدًا.
يقرأ OpenClaw هذا قبل تحميل وقت تشغيل Provider.
يصف كل عنصر في `providerAuthChoices` خيارًا واحدًا من خيارات onboarding أو auth.
يقرأ OpenClaw هذا قبل تحميل وقت تشغيل provider.
| الحقل | مطلوب | النوع | المعنى |
| -------------------- | ------ | ----------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `provider` | نعم | `string` | معرّف Provider الذي ينتمي إليه هذا الخيار. |
| `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` | معرّف Provider الذي ينتمي إليه هذا الخيار. |
| `method` | نعم | `string` | معرّف طريقة auth المطلوب التوجيه إليها. |
| `choiceId` | نعم | `string` | معرّف ثابت لخيار auth تستخدمه تدفقات onboarding وCLI. |
| `choiceLabel` | لا | `string` | تسمية موجهة للمستخدم. إذا حُذفت، يعود OpenClaw إلى `choiceId`. |
| `choiceHint` | لا | `string` | نص مساعد قصير للمنتقي. |
| `assistantPriority` | لا | `number` | تُرتَّب القيم الأقل أولًا في المنتقيات التفاعلية التي يقودها المساعد. |
| `assistantVisibility`| لا | `"visible"` \| `"manual-only"` | يُخفي الخيار من منتقيات المساعد مع الاستمرار في السماح بالاختيار اليدوي عبر CLI. |
| `deprecatedChoiceIds`| لا | `string[]` | معرّفات خيارات قديمة يجب أن تعيد توجيه المستخدمين إلى هذا الخيار البديل. |
| `groupId` | لا | `string` | معرّف مجموعة اختياري لتجميع الخيارات ذات الصلة. |
| `groupLabel` | لا | `string` | تسمية موجهة للمستخدم لتلك المجموعة. |
| `groupHint` | لا | `string` | نص مساعد قصير للمجموعة. |
| `optionKey` | لا | `string` | مفتاح خيار داخلي لتدفقات auth البسيطة التي تعتمد على علم واحد. |
| `cliFlag` | لا | `string` | اسم علم CLI، مثل `--openrouter-api-key`. |
| `cliOption` | لا | `string` | الشكل الكامل لخيار CLI، مثل `--openrouter-api-key <key>`. |
| `cliDescription` | لا | `string` | الوصف المستخدم في تعليمات CLI. |
| `onboardingScopes` | لا | `Array<"text-inference" \| "image-generation">` | أسطح onboarding التي يجب أن يظهر فيها هذا الخيار. إذا حُذفت، تكون القيمة الافتراضية `["text-inference"]`. |
## مرجع `commandAliases`
استخدم `commandAliases` عندما يملك Plugin اسم أمر وقت تشغيل قد يضعه المستخدمون
عن طريق الخطأ في `plugins.allow` أو يحاولون تشغيله كأمر CLI جذري. يستخدم OpenClaw
هذه البيانات الوصفية لأغراض التشخيص من دون استيراد كود وقت تشغيل Plugin.
استخدم `commandAliases` عندما يملك Plugin اسم أمر في وقت التشغيل قد يضعه
المستخدمون عن طريق الخطأ في `plugins.allow` أو يحاولون تشغيله كأمر CLI جذري.
يستخدم OpenClaw هذه البيانات الوصفية للتشخيصات من دون استيراد كود وقت تشغيل Plugin.
```json
{
@ -212,22 +214,46 @@ x-i18n:
}
```
| الحقل | مطلوب | النوع | المعنى |
| ----------- | ------ | ----------------- | ---------------------------------------------------------------------------- |
| `name` | نعم | `string` | اسم الأمر الذي ينتمي إلى هذا Plugin. |
| `kind` | لا | `"runtime-slash"` | يحدد الاسم البديل كأمر slash للدردشة بدلًا من أمر CLI جذري. |
| `cliCommand`| لا | `string` | أمر CLI جذري ذو صلة يُقترح لعمليات CLI، إذا كان موجودًا. |
| الحقل | مطلوب | النوع | ما الذي يعنيه |
| ----------- | ------ | ----------------- | -------------------------------------------------------------------------- |
| `name` | نعم | `string` | اسم الأمر الذي ينتمي إلى هذا Plugin. |
| `kind` | لا | `"runtime-slash"` | يحدّد أن alias هو أمر slash للدردشة وليس أمر CLI جذريًا. |
| `cliCommand`| لا | `string` | أمر CLI جذري ذو صلة يُقترح لعمليات CLI، إذا كان موجودًا. |
## مرجع `activation`
استخدم `activation` عندما يمكن لـ Plugin أن يصرّح بتكلفة منخفضة عن أحداث مستوى التحكم
استخدم `activation` عندما يستطيع Plugin التصريح بكلفة منخفضة عن أحداث control plane
التي ينبغي أن تفعّله لاحقًا.
هذه الكتلة عبارة عن بيانات وصفية فقط. فهي لا تسجل سلوك وقت التشغيل، ولا
تحل محل `register(...)` أو `setupEntry` أو نقاط دخول وقت التشغيل/Plugin الأخرى.
يستخدمها المستهلكون الحاليون كتلميح تضييق قبل تحميل Plugin الأوسع، لذلك فإن
غياب بيانات تعريف التنشيط عادةً لا يكلّف سوى الأداء؛ ولا ينبغي أن
يغيّر الصحة ما دامت آليات fallback القديمة لملكية manifest لا تزال موجودة.
## مرجع `qaRunners`
استخدم `qaRunners` عندما يساهم Plugin بمشغّل نقل واحد أو أكثر تحت الجذر
المشترك `openclaw qa`. احرص على أن تكون هذه البيانات الوصفية منخفضة الكلفة
وثابتة؛ إذ لا يزال وقت تشغيل Plugin يملك تسجيل CLI الفعلي من خلال سطح
`runtime-api.ts` خفيف يصدّر `qaRunnerCliRegistrations`.
```json
{
"qaRunners": [
{
"commandName": "matrix",
"description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver"
}
]
}
```
| الحقل | مطلوب | النوع | ما الذي يعنيه |
| ------------ | ------ | -------- | ---------------------------------------------------------------------------- |
| `commandName`| نعم | `string` | الأمر الفرعي المُثبت تحت `openclaw qa`، مثل `matrix`. |
| `description`| لا | `string` | نص مساعدة احتياطي يُستخدم عندما يحتاج المضيف المشترك إلى أمر stub. |
هذه الكتلة هي بيانات وصفية فقط. فهي لا تسجل سلوك وقت التشغيل، ولا تستبدل
`register(...)` أو `setupEntry` أو نقاط دخول وقت التشغيل/Plugin الأخرى.
يستخدمها المستهلكون الحاليون كتلميح للتضييق قبل تحميل Plugin على نطاق أوسع،
لذا فإن غياب بيانات activation الوصفية يؤدي عادةً فقط إلى تكلفة في الأداء؛
ولا ينبغي أن يغيّر الصحة ما دامت آليات الرجوع إلى ملكية manifest القديمة
لا تزال موجودة.
```json
{
@ -241,28 +267,28 @@ x-i18n:
}
```
| الحقل | مطلوب | النوع | المعنى |
| ---------------- | ------ | ---------------------------------------------------- | ------------------------------------------------------------- |
| `onProviders` | لا | `string[]` | معرّفات Provider التي ينبغي أن تفعّل هذا Plugin عند طلبها. |
| `onCommands` | لا | `string[]` | معرّفات الأوامر التي ينبغي أن تفعّل هذا Plugin. |
| `onChannels` | لا | `string[]` | معرّفات القنوات التي ينبغي أن تفعّل هذا Plugin. |
| `onRoutes` | لا | `string[]` | أنواع المسارات التي ينبغي أن تفعّل هذا Plugin. |
| `onCapabilities` | لا | `Array<"provider" \| "channel" \| "tool" \| "hook">` | تلميحات قدرات عامة تُستخدم في تخطيط التنشيط على مستوى التحكم. |
| الحقل | مطلوب | النوع | ما الذي يعنيه |
| ---------------- | ------ | ---------------------------------------------------- | ------------------------------------------------------------------ |
| `onProviders` | لا | `string[]` | معرّفات providers التي يجب أن تفعّل هذا Plugin عند طلبها. |
| `onCommands` | لا | `string[]` | معرّفات الأوامر التي يجب أن تفعّل هذا Plugin. |
| `onChannels` | لا | `string[]` | معرّفات القنوات التي يجب أن تفعّل هذا Plugin. |
| `onRoutes` | لا | `string[]` | أنواع routes التي يجب أن تفعّل هذا Plugin. |
| `onCapabilities` | لا | `Array<"provider" \| "channel" \| "tool" \| "hook">` | تلميحات قدرات عامة تُستخدم في تخطيط التنشيط ضمن control plane. |
المستهلكون الحاليون الفعليون:
المستهلكون المباشرون الحاليون:
- تخطيط CLI المُفعّل بالأوامر يعود إلى الآلية القديمة
`commandAliases[].cliCommand` أو `commandAliases[].name`
- تخطيط الإعداد/القنوات المُفعّل بالقنوات يعود إلى ملكية
`channels[]` القديمة عندما تكون بيانات تعريف تنشيط القنوات الصريحة مفقودة
- تخطيط الإعداد/وقت التشغيل المُفعّل بمزوّد Provider يعود إلى الملكية القديمة
`providers[]` وملكية `cliBackends[]` ذات المستوى الأعلى عندما تكون بيانات تعريف
تنشيط Provider الصريحة مفقودة
- يعود تخطيط CLI المحفَّز بالأوامر إلى
`commandAliases[].cliCommand` أو `commandAliases[].name` القديمين
- يعود تخطيط الإعداد/القنوات المحفَّز بالقنوات إلى ملكية `channels[]` القديمة
عندما تكون بيانات تنشيط القنوات الصريحة مفقودة
- يعود تخطيط الإعداد/وقت التشغيل المحفَّز بالـ provider إلى ملكية
`providers[]` وملكية `cliBackends[]` ذات المستوى الأعلى القديمة عندما
تكون بيانات تنشيط provider الصريحة مفقودة
## مرجع `setup`
استخدم `setup` عندما تحتاج أسطح الإعداد والتهيئة الأولية إلى بيانات تعريف منخفضة الكلفة يملكها Plugin
قبل تحميل وقت التشغيل.
استخدم `setup` عندما تحتاج أسطح الإعداد والتهيئة الأولية إلى بيانات وصفية
منخفضة الكلفة ومملوكة للـ Plugin قبل تحميل وقت التشغيل.
```json
{
@ -281,41 +307,41 @@ x-i18n:
}
```
يبقى `cliBackends` ذو المستوى الأعلى صالحًا ويستمر في وصف
واجهات CLI الخلفية للاستدلال. أمّا `setup.cliBackends` فهو سطح الواصفات
الخاص بالإعداد لمسارات مستوى التحكم/الإعداد التي ينبغي أن تبقى بيانات وصفية فقط.
يبقى `cliBackends` على المستوى الأعلى صالحًا ويواصل وصف backends الخاصة
بالاستدلال في CLI. أما `setup.cliBackends` فهو سطح الواصفات الخاص بالإعداد
لتدفقات control plane/الإعداد التي ينبغي أن تبقى بيانات وصفية فقط.
عند وجودها، تُعد `setup.providers` و`setup.cliBackends` سطح البحث المفضل
القائم على الواصفات أولًا لاكتشاف الإعداد. وإذا كان الواصف يضيّق فقط
Plugin المرشح وكان الإعداد لا يزال يحتاج إلى Hooks وقت تشغيل أغنى في وقت الإعداد،
فاضبط `requiresRuntime: true` وأبقِ `setup-api` في مكانه
عند وجوده، يكون `setup.providers` و`setup.cliBackends` هما سطح البحث المفضّل
المعتمد على الواصفات أولًا لاكتشاف الإعداد. إذا كان الواصف يضيّق فقط نطاق
Plugin المرشّح ولا يزال الإعداد يحتاج إلى hooks أغنى خاصة بوقت الإعداد ضمن
وقت التشغيل، فاضبط `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` | معرّف Provider المُعرَض أثناء الإعداد أو التهيئة الأولية. حافظ على فرادة المعرّفات المطَبَّعة عالميًا. |
| `authMethods` | لا | `string[]` | معرّفات أساليب الإعداد/المصادقة التي يدعمها هذا Provider من دون تحميل وقت التشغيل الكامل. |
| الحقل | مطلوب | النوع | ما الذي يعنيه |
| ------------- | ------ | ---------- | ----------------------------------------------------------------------------------- |
| `id` | نعم | `string` | معرّف Provider الذي يُعرَض أثناء الإعداد أو onboarding. احرص على أن تبقى المعرّفات المطَبَّعة فريدة عالميًا. |
| `authMethods` | لا | `string[]` | معرّفات طرق الإعداد/auth التي يدعمها هذا الـ Provider من دون تحميل وقت التشغيل الكامل. |
| `envVars` | لا | `string[]` | متغيرات البيئة التي يمكن لأسطح الإعداد/الحالة العامة التحقق منها قبل تحميل وقت تشغيل Plugin. |
### حقول `setup`
| الحقل | مطلوب | النوع | المعنى |
| ------------------ | ------ | ---------- | ------------------------------------------------------------------------------------------------- |
| `providers` | لا | `object[]` | واصفات إعداد Provider المعروضة أثناء الإعداد والتهيئة الأولية. |
| `cliBackends` | لا | `string[]` | معرّفات الواجهات الخلفية وقت الإعداد المستخدمة للبحث القائم على الواصفات أولًا. حافظ على فرادة المعرّفات المطَبَّعة عالميًا. |
| `configMigrations` | لا | `string[]` | معرّفات ترحيل الإعدادات التي يملكها سطح الإعداد لهذا Plugin. |
| `requiresRuntime` | لا | `boolean` | ما إذا كان الإعداد لا يزال يحتاج إلى تنفيذ `setup-api` بعد البحث القائم على الواصفات. |
| الحقل | مطلوب | النوع | ما الذي يعنيه |
| ------------------ | ------ | ---------- | -------------------------------------------------------------------------------------------------- |
| `providers` | لا | `object[]` | واصفات إعداد providers التي تُعرَض أثناء الإعداد وonboarding. |
| `cliBackends` | لا | `string[]` | معرّفات backends في وقت الإعداد والمستخدمة للبحث المعتمد على الواصفات أولًا. احرص على أن تبقى المعرّفات المطَبَّعة فريدة عالميًا. |
| `configMigrations` | لا | `string[]` | معرّفات ترحيل الإعدادات المملوكة لسطح الإعداد الخاص بهذا Plugin. |
| `requiresRuntime` | لا | `boolean` | ما إذا كان الإعداد لا يزال يحتاج إلى تنفيذ `setup-api` بعد البحث المعتمد على الواصفات. |
## مرجع `uiHints`
`uiHints` هو خريطة من أسماء حقول الإعدادات إلى تلميحات عرض صغيرة.
`uiHints` عبارة عن خريطة من أسماء حقول الإعدادات إلى تلميحات عرض صغيرة.
```json
{
@ -330,20 +356,20 @@ Plugin المرشح وكان الإعداد لا يزال يحتاج إلى Hook
}
```
يمكن أن يتضمن كل تلميح حقل ما يلي:
يمكن أن يتضمن تلميح كل حقل ما يلي:
| الحقل | النوع | المعنى |
| ------------ | ---------- | -------------------------------------- |
| `label` | `string` | تسمية الحقل الموجهة للمستخدم. |
| `help` | `string` | نص مساعد قصير. |
| `tags` | `string[]` | وسوم واجهة مستخدم اختيارية. |
| `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
@ -364,22 +390,22 @@ Plugin المرشح وكان الإعداد لا يزال يحتاج إلى Hook
كل قائمة اختيارية:
| الحقل | النوع | المعنى |
| -------------------------------- | ---------- | ---------------------------------------------------------- |
| `speechProviders` | `string[]` | معرّفات موفري Speech التي يملكها هذا Plugin. |
| `realtimeTranscriptionProviders` | `string[]` | معرّفات موفري realtime-transcription التي يملكها هذا Plugin. |
| `realtimeVoiceProviders` | `string[]` | معرّفات موفري realtime-voice التي يملكها هذا Plugin. |
| `mediaUnderstandingProviders` | `string[]` | معرّفات موفري media-understanding التي يملكها هذا Plugin. |
| `imageGenerationProviders` | `string[]` | معرّفات موفري image-generation التي يملكها هذا Plugin. |
| `videoGenerationProviders` | `string[]` | معرّفات موفري video-generation التي يملكها هذا Plugin. |
| `webFetchProviders` | `string[]` | معرّفات موفري web-fetch التي يملكها هذا Plugin. |
| `webSearchProviders` | `string[]` | معرّفات موفري web-search التي يملكها هذا Plugin. |
| `tools` | `string[]` | أسماء أدوات الوكيل التي يملكها هذا Plugin لفحوصات العقود المجمّعة. |
| الحقل | النوع | ما الذي يعنيه |
| ------------------------------- | ---------- | --------------------------------------------------------------- |
| `speechProviders` | `string[]` | معرّفات providers الخاصة بـ speech التي يملكها هذا Plugin. |
| `realtimeTranscriptionProviders`| `string[]` | معرّفات providers الخاصة بـ realtime-transcription التي يملكها هذا Plugin. |
| `realtimeVoiceProviders` | `string[]` | معرّفات providers الخاصة بـ realtime-voice التي يملكها هذا Plugin. |
| `mediaUnderstandingProviders` | `string[]` | معرّفات providers الخاصة بـ media-understanding التي يملكها هذا Plugin. |
| `imageGenerationProviders` | `string[]` | معرّفات providers الخاصة بـ image-generation التي يملكها هذا Plugin. |
| `videoGenerationProviders` | `string[]` | معرّفات providers الخاصة بـ video-generation التي يملكها هذا Plugin. |
| `webFetchProviders` | `string[]` | معرّفات providers الخاصة بـ web-fetch التي يملكها هذا Plugin. |
| `webSearchProviders` | `string[]` | معرّفات providers الخاصة بـ web-search التي يملكها هذا Plugin. |
| `tools` | `string[]` | أسماء أدوات agent التي يملكها هذا Plugin لفحوصات العقود المضمّنة. |
## مرجع `channelConfigs`
استخدم `channelConfigs` عندما يحتاج Plugin قناة إلى بيانات تعريف إعدادات منخفضة الكلفة قبل
تحميل وقت التشغيل.
استخدم `channelConfigs` عندما يحتاج Plugin قناة إلى بيانات وصفية منخفضة الكلفة
للإعدادات قبل تحميل وقت التشغيل.
```json
{
@ -408,18 +434,18 @@ Plugin المرشح وكان الإعداد لا يزال يحتاج إلى Hook
يمكن أن يتضمن كل إدخال قناة ما يلي:
| الحقل | النوع | المعنى |
| ------------ | ------------------------ | --------------------------------------------------------------------------------------- |
| `schema` | `object` | JSON Schema لـ `channels.<id>`. مطلوب لكل إدخال إعدادات قناة مُعلن عنه. |
| `uiHints` | `Record<string, object>` | تسميات واجهة مستخدم/عناصر نائبة/تلميحات حساسية اختيارية لقسم إعدادات تلك القناة. |
| `label` | `string` | تسمية القناة المدمجة في أسطح الاختيار والفحص عندما لا تكون بيانات تعريف وقت التشغيل جاهزة. |
| `description`| `string` | وصف قصير للقناة لأسطح الفحص والكتالوج. |
| `preferOver` | `string[]` | معرّفات Plugin قديمة أو أقل أولوية ينبغي أن تتفوق عليها هذه القناة في أسطح الاختيار. |
| الحقل | النوع | ما الذي يعنيه |
| ------------- | ------------------------ | --------------------------------------------------------------------------------------------- |
| `schema` | `object` | مخطط JSON لـ `channels.<id>`. مطلوب لكل إدخال مُعلَن لإعدادات القناة. |
| `uiHints` | `Record<string, object>` | تسميات واجهة مستخدم/عناصر نائبة/تلميحات حساسية اختيارية لذلك القسم من إعدادات القناة. |
| `label` | `string` | تسمية القناة المدمجة في أسطح المنتقي والفحص عندما لا تكون بيانات وقت التشغيل الوصفية جاهزة. |
| `description` | `string` | وصف قصير للقناة لأسطح الفحص والفهرس. |
| `preferOver` | `string[]` | معرّفات Plugins قديمة أو أقل أولوية ينبغي أن تتفوّق عليها هذه القناة في أسطح الاختيار. |
## مرجع `modelSupport`
استخدم `modelSupport` عندما ينبغي لـ OpenClaw أن يستنتج Plugin Provider الخاص بك من
معرّفات نماذج مختصرة مثل `gpt-5.4` أو `claude-sonnet-4.6` قبل أن يُحمَّل وقت تشغيل Plugin.
استخدم `modelSupport` عندما ينبغي لـ OpenClaw استنتاج Plugin الـ provider الخاص بك
من معرّفات نماذج مختصرة مثل `gpt-5.4` أو `claude-sonnet-4.6` قبل تحميل وقت تشغيل Plugin.
```json
{
@ -430,75 +456,73 @@ Plugin المرشح وكان الإعداد لا يزال يحتاج إلى Hook
}
```
يطبّق OpenClaw أسبقية الترتيب التالية:
يطبّق OpenClaw ترتيب الأولوية التالي:
- تستخدم مراجع `provider/model` الصريحة بيانات تعريف manifest المملوكة في `providers`
- تتفوق `modelPatterns` على `modelPrefixes`
- إذا طابق Plugin غير مجمّع وPlugin مجمّع معًا، فإن
Plugin غير المجمّع يفوز
- يتم تجاهل أي غموض متبقٍ حتى يحدد المستخدم أو الإعدادات Provider
- تستخدم مراجع `provider/model` الصريحة بيانات manifest الخاصة بالملكية في `providers`
- تتفوّق `modelPatterns` على `modelPrefixes`
- إذا طابق كل من Plugin غير مضمّن وPlugin مضمّن، يفوز الـ Plugin غير المضمّن
- يُتجاهل أي غموض متبقٍّ إلى أن يحدّد المستخدم أو الإعدادات provider
الحقول:
| الحقل | النوع | المعنى |
| -------------- | ---------- | ----------------------------------------------------------------------------- |
| `modelPrefixes`| `string[]` | بادئات تتم مطابقتها باستخدام `startsWith` مع معرّفات النماذج المختصرة. |
| `modelPatterns`| `string[]` | مصادر Regex تتم مطابقتها مع معرّفات النماذج المختصرة بعد إزالة لاحقة profile. |
| الحقل | النوع | ما الذي يعنيه |
| -------------- | ---------- | -------------------------------------------------------------------------------- |
| `modelPrefixes`| `string[]` | بادئات تُطابَق باستخدام `startsWith` مع معرّفات النماذج المختصرة. |
| `modelPatterns`| `string[]` | مصادر Regex تُطابَق مع معرّفات النماذج المختصرة بعد إزالة لاحقة profile. |
مفاتيح القدرات القديمة ذات المستوى الأعلى أصبحت مهجورة. استخدم `openclaw doctor --fix`
لنقل `speechProviders` و`realtimeTranscriptionProviders`،
و`realtimeVoiceProviders` و`mediaUnderstandingProviders`،
و`imageGenerationProviders` و`videoGenerationProviders`،
و`webFetchProviders` و`webSearchProviders` إلى `contracts`؛ ولم يعد
تحميل manifest العادي يعامل تلك الحقول ذات المستوى الأعلى على أنها
ملكية للقدرات.
مفاتيح القدرات القديمة ذات المستوى الأعلى مهجورة. استخدم `openclaw doctor --fix`
لنقل `speechProviders` و`realtimeTranscriptionProviders` و
`realtimeVoiceProviders` و`mediaUnderstandingProviders` و
`imageGenerationProviders` و`videoGenerationProviders` و
`webFetchProviders` و`webSearchProviders` إلى `contracts`؛ لم يعد تحميل
manifest العادي يتعامل مع تلك الحقول ذات المستوى الأعلى على أنها ملكية للقدرات.
## الـ Manifest مقابل `package.json`
## manifest مقابل package.json
يخدم الملفان وظيفتين مختلفتين:
| الملف | استخدمه من أجل |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.plugin.json` | الاكتشاف، والتحقق من صحة الإعدادات، وبيانات تعريف خيارات المصادقة، وتلميحات واجهة المستخدم التي يجب أن توجد قبل تشغيل كود Plugin |
| `package.json` | بيانات تعريف npm، وتثبيت التبعيات، وكتلة `openclaw` المستخدمة لنقاط الدخول، وبوابات التثبيت، والإعداد، أو بيانات تعريف الكتالوج |
| الملف | استخدمه من أجل |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.plugin.json` | الاكتشاف، والتحقق من صحة الإعدادات، وبيانات auth-choice الوصفية، وتلميحات واجهة المستخدم التي يجب أن تكون موجودة قبل تشغيل كود Plugin |
| `package.json` | بيانات npm الوصفية، وتثبيت الاعتماديات، وكتلة `openclaw` المستخدمة لنقاط الدخول، أو بوابات التثبيت، أو الإعداد، أو بيانات الفهرس الوصفية |
إذا لم تكن متأكدًا من موضع قطعة بيانات تعريف معينة، فاستخدم هذه القاعدة:
إذا لم تكن متأكدًا من الموضع الذي تنتمي إليه معلومة وصفية ما، فاستخدم هذه القاعدة:
- إذا كان يجب على OpenClaw معرفتها قبل تحميل كود Plugin، فضعها في `openclaw.plugin.json`
- إذا كانت تتعلق بالتغليف أو ملفات الدخول أو سلوك تثبيت npm، فضعها في `package.json`
- إذا كان يجب على OpenClaw معرفتها قبل تحميل كود Plugin، فضَعها في `openclaw.plugin.json`
- إذا كانت تتعلق بالتغليف، أو ملفات الدخول، أو سلوك تثبيت npm، فضَعها في `package.json`
### حقول `package.json` التي تؤثر في الاكتشاف
توجد بعض بيانات تعريف Plugin السابقة لوقت التشغيل عمدًا داخل `package.json` تحت
توجد بعض بيانات Plugin الوصفية السابقة لوقت التشغيل عمدًا داخل `package.json` تحت
كتلة `openclaw` بدلًا من `openclaw.plugin.json`.
أمثلة مهمة:
| الحقل | المعنى |
| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.extensions` | يصرّح بنقاط دخول Plugin الأصلية. |
| `openclaw.setupEntry` | نقطة دخول خفيفة مخصّصة للإعداد فقط تُستخدم أثناء التهيئة الأولية وبدء تشغيل القنوات المؤجل. |
| `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 الأصلية. |
| `openclaw.setupEntry` | نقطة دخول خفيفة مخصّصة للإعداد فقط وتُستخدم أثناء onboarding وبدء تشغيل القناة المؤجل. |
| `openclaw.channel` | بيانات وصفية منخفضة الكلفة لفهرس القنوات مثل التسميات، ومسارات الوثائق، وaliases، ونصوص الاختيار. |
| `openclaw.channel.configuredState` | بيانات وصفية خفيفة لوحدة فحص الحالة المُعدّة يمكنها الإجابة عن سؤال "هل يوجد إعداد يعتمد على البيئة فقط بالفعل؟" من دون تحميل وقت تشغيل القناة الكامل. |
| `openclaw.channel.persistedAuthState` | بيانات وصفية خفيفة لوحدة فحص auth المحفوظة يمكنها الإجابة عن سؤال "هل تم تسجيل الدخول إلى أي شيء بالفعل؟" من دون تحميل وقت تشغيل القناة الكامل. |
| `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` أثناء التثبيت
وأثناء تحميل سجل manifest. تُرفض القيم غير الصالحة؛ أما القيم الصحيحة
ولكن الأحدث فتتسبب في تخطي Plugin على المضيفات الأقدم.
يُفرَض `openclaw.install.minHostVersion` أثناء التثبيت وتحميل سجل manifest.
تُرفَض القيم غير الصالحة؛ أما القيم الأحدث ولكن الصالحة فتتخطى Plugin
على المضيفات الأقدم.
إن `openclaw.install.allowInvalidConfigRecovery` ضيق النطاق عمدًا. فهو
لا يجعل الإعدادات المعطوبة التعسفية قابلة للتثبيت. اليوم، هو يسمح فقط
لمسارات التثبيت بالتعافي من إخفاقات ترقية معينة قديمة تخص Plugins المجمّعة، مثل
مسار Plugin مجمّع مفقود أو إدخال `channels.<id>` قديم لذلك Plugin المجمّع نفسه.
أما أخطاء الإعدادات غير ذات الصلة فما تزال تمنع التثبيت وتوجّه المشغلين
إلى `openclaw doctor --fix`.
إن `openclaw.install.allowInvalidConfigRecovery` ضيق النطاق عمدًا. فهو لا
يجعل الإعدادات المعطوبة بشكل عشوائي قابلة للتثبيت. في الوقت الحالي، يسمح فقط
لتدفقات التثبيت بالتعافي من حالات فشل ترقية محددة وقديمة لPlugin مضمّن،
مثل غياب مسار Plugin مضمّن أو وجود إدخال `channels.<id>` قديم لذلك Plugin
المضمّن نفسه. أما أخطاء الإعدادات غير المرتبطة فلا تزال تمنع التثبيت وتوجّه
المشغّلين إلى `openclaw doctor --fix`.
يمثل `openclaw.channel.persistedAuthState` بيانات تعريف حزمة لوحدة فحص صغيرة:
إن `openclaw.channel.persistedAuthState` هي بيانات وصفية للحزمة لوحدة فحص صغيرة:
```json
{
@ -514,13 +538,12 @@ Plugin المرشح وكان الإعداد لا يزال يحتاج إلى Hook
}
```
استخدمه عندما تحتاج مسارات الإعداد أو doctor أو الحالة المهيأة إلى
فحص مصادقة بسيط بنعم/لا قبل تحميل Plugin القناة الكامل. ينبغي أن يكون
التصدير الهدف دالة صغيرة تقرأ الحالة المحفوظة فقط؛ ولا توجّهها
عبر شريط وقت تشغيل القناة الكامل.
استخدمها عندما تحتاج تدفقات الإعداد أو doctor أو الحالة المُعدّة إلى فحص auth
خفيف بنعم/لا قبل تحميل Plugin القناة الكامل. يجب أن يكون التصدير الهدف
دالة صغيرة تقرأ الحالة المحفوظة فقط؛ لا تمرّرها عبر barrel الخاص بوقت تشغيل القناة الكامل.
يتبع `openclaw.channel.configuredState` الشكل نفسه من أجل فحوصات التهيئة
البسيطة المعتمدة على البيئة فقط:
يتبع `openclaw.channel.configuredState` الشكل نفسه لعمليات الفحص الخفيفة
للحالة المُعدّة المعتمدة على البيئة فقط:
```json
{
@ -536,65 +559,68 @@ Plugin المرشح وكان الإعداد لا يزال يحتاج إلى Hook
}
```
استخدمه عندما تتمكن قناة من تحديد حالة التهيئة من البيئة أو من مدخلات صغيرة
أخرى غير تشغيلية. وإذا كان الفحص يحتاج إلى حل كامل للإعدادات أو إلى
وقت تشغيل القناة الحقيقي، فأبقِ هذا المنطق داخل Hook
`config.hasConfiguredState` في Plugin بدلًا من ذلك.
استخدمه عندما تستطيع قناة ما الإجابة عن الحالة المُعدّة اعتمادًا على البيئة
أو مدخلات صغيرة أخرى غير مرتبطة بوقت التشغيل. إذا كان الفحص يحتاج إلى الحل
الكامل للإعدادات أو إلى وقت تشغيل القناة الحقيقي، فأبقِ هذا المنطق في hook
`config.hasConfiguredState` الخاص بالـ Plugin بدلًا من ذلك.
## متطلبات JSON Schema
## متطلبات مخطط JSON
- **يجب على كل Plugin أن يوفّر JSON Schema**، حتى لو كان لا يقبل أي إعدادات.
- يُعد المخطط الفارغ مقبولًا (على سبيل المثال، `{ "type": "object", "additionalProperties": false }`).
- يتم التحقق من المخططات وقت قراءة/كتابة الإعدادات، وليس في وقت التشغيل.
- **يجب على كل Plugin أن يضمّ مخطط JSON**، حتى إذا كان لا يقبل أي إعدادات.
- يُقبل مخطط فارغ (على سبيل المثال، `{ "type": "object", "additionalProperties": false }`).
- تُتحقَّق المخططات عند قراءة/كتابة الإعدادات، وليس في وقت التشغيل.
## سلوك التحقق
## سلوك التحقق من الصحة
- تُعد مفاتيح `channels.*` غير المعروفة **أخطاء**، ما لم يكن معرّف القناة معلنًا بواسطة
manifest خاص بـ Plugin.
- مفاتيح `channels.*` غير المعروفة هي **أخطاء**، ما لم يكن معرّف القناة
مُعلَنًا بواسطة manifest تابع لـ Plugin.
- يجب أن تشير `plugins.entries.<id>` و`plugins.allow` و`plugins.deny` و`plugins.slots.*`
إلى معرّفات Plugin **قابلة للاكتشاف**. وتُعد المعرّفات غير المعروفة **أخطاء**.
- إذا كان Plugin مثبتًا لكن manifest أو schema الخاص به معطوبًا أو مفقودًا،
يفشل التحقق ويبلّغ Doctor عن خطأ Plugin.
- إذا كانت إعدادات Plugin موجودة لكن Plugin **معطّل**، يتم الاحتفاظ بالإعدادات
وتظهر **تحذير** في Doctor + السجلات.
إلى معرّفات Plugins **قابلة للاكتشاف**. والمعرّفات غير المعروفة هي **أخطاء**.
- إذا كان Plugin مثبّتًا لكن لديه manifest أو schema معطوب أو مفقود،
يفشل التحقق من الصحة ويبلّغ Doctor عن خطأ Plugin.
- إذا كانت إعدادات Plugin موجودة لكن Plugin **معطّل**، فستُحفَظ الإعدادات
ويظهر **تحذير** في Doctor + السجلات.
راجع [مرجع الإعدادات](/ar/gateway/configuration) للاطلاع على مخطط `plugins.*` الكامل.
راجع [Configuration reference](/ar/gateway/configuration) للاطلاع على مخطط `plugins.*` الكامل.
## ملاحظات
- إن الـ manifest **مطلوب للـ Plugins الأصلية في OpenClaw**، بما في ذلك التحميلات المحلية من نظام الملفات.
- ما يزال وقت التشغيل يحمّل وحدة Plugin بشكل منفصل؛ والـ manifest مخصّص فقط
للاكتشاف + التحقق.
- يتم تحليل ملفات manifest الأصلية باستخدام JSON5، لذا تُقبل التعليقات والفواصل اللاحقة
والمفاتيح غير المحاطة بعلامات اقتباس ما دامت القيمة النهائية لا تزال كائنًا.
- لا يقرأ محمّل manifest سوى حقول manifest الموثقة. تجنّب إضافة
- ملف manifest **مطلوب للـ Plugins الأصلية في OpenClaw**، بما في ذلك التحميلات المحلية من نظام الملفات.
- لا يزال وقت التشغيل يحمّل وحدة Plugin بشكل منفصل؛ manifest مخصّص فقط
للاكتشاف + التحقق من الصحة.
- تُحلَّل ملفات manifest الأصلية باستخدام JSON5، لذا تُقبل التعليقات،
والفواصل اللاحقة، والمفاتيح غير الموضوعة بين علامات اقتباس ما دامت
القيمة النهائية لا تزال كائنًا.
- لا يقرأ مُحمِّل manifest إلا حقول manifest الموثقة. تجنّب إضافة
مفاتيح مخصّصة ذات مستوى أعلى هنا.
- يمثل `providerAuthEnvVars` مسار البيانات الوصفية منخفض الكلفة لفحوصات المصادقة، والتحقق من
علامات البيئة، والأسطح المماثلة لمصادقة Provider التي ينبغي ألا تشغّل وقت تشغيل Plugin
لمجرد فحص أسماء متغيرات البيئة.
- يتيح `providerAuthAliases` لمتغيرات Provider إعادة استخدام متغيرات بيئة المصادقة الخاصة بـ Provider آخر،
وملفات تعريف المصادقة، والمصادقة المعتمدة على الإعدادات، وخيار التهيئة الأولية بمفتاح API
من دون ترميز هذه العلاقة بشكل صريح داخل النواة.
- يمثل `channelEnvVars` مسار البيانات الوصفية منخفض الكلفة للرجوع إلى shell-env، وموجّهات الإعداد،
والأسطح المماثلة الخاصة بالقنوات التي ينبغي ألا تشغّل وقت تشغيل Plugin
لمجرد فحص أسماء متغيرات البيئة.
- يمثل `providerAuthChoices` مسار البيانات الوصفية منخفض الكلفة لمحددات خيارات المصادقة،
وحل `--auth-choice`، وربط Provider المفضل، وتسجيل أعلام CLI البسيطة الخاصة بالتهيئة الأولية
قبل تحميل وقت تشغيل Provider. أما بيانات تعريف المعالج التفاعلي في وقت التشغيل
التي تتطلب كود Provider، فراجع
[Provider runtime hooks](/ar/plugins/architecture#provider-runtime-hooks).
- يتم اختيار أنواع Plugin الحصرية عبر `plugins.slots.*`.
- `providerAuthEnvVars` هو مسار البيانات الوصفية منخفضة الكلفة لفحوصات auth،
والتحقق من env-marker، والأسطح المشابهة الخاصة بـ provider-auth التي
لا ينبغي أن تشغّل وقت تشغيل Plugin لمجرد فحص أسماء env.
- يتيح `providerAuthAliases` لمتغيرات provider إعادة استخدام متغيرات env
الخاصة بـ auth لProvider آخر، وملفات auth التعريفية الخاصة به، وauth
المدعوم بالإعدادات، وخيار onboarding الخاص بمفتاح API، من دون ترميز هذه
العلاقة بشكل ثابت في النواة.
- `channelEnvVars` هو مسار البيانات الوصفية منخفضة الكلفة لبدائل shell-env،
ورسائل الإعداد، والأسطح المشابهة الخاصة بالقنوات التي لا ينبغي أن تشغّل
وقت تشغيل Plugin لمجرد فحص أسماء env.
- `providerAuthChoices` هو مسار البيانات الوصفية منخفضة الكلفة لمنتقيات
auth-choice، وحل `--auth-choice`، وربط provider المفضّل، وتسجيل أعلام CLI
البسيطة الخاصة بالتهيئة الأولية قبل تحميل وقت تشغيل provider. أما بالنسبة
إلى بيانات wizard الوصفية الخاصة بوقت التشغيل التي تتطلب كود provider،
فراجع [Provider runtime hooks](/ar/plugins/architecture#provider-runtime-hooks).
- تُختار أنواع Plugins الحصرية عبر `plugins.slots.*`.
- يتم اختيار `kind: "memory"` بواسطة `plugins.slots.memory`.
- يتم اختيار `kind: "context-engine"` بواسطة `plugins.slots.contextEngine`
(الافتراضي: `legacy` المدمج).
- يمكن حذف `channels` و`providers` و`cliBackends` و`skills` عندما لا
يحتاجها Plugin.
(الافتراضي: `legacy` المضمّن).
- يمكن حذف `channels` و`providers` و`cliBackends` و`skills` عندما لا يحتاج
Plugin إليها.
- إذا كان Plugin الخاص بك يعتمد على وحدات أصلية، فوثّق خطوات البناء وأي
متطلبات قائمة سماح لمدير الحزم (على سبيل المثال، `allow-build-scripts` في pnpm
متطلبات لقائمة السماح الخاصة بمدير الحزم (على سبيل المثال، `allow-build-scripts`
في pnpm
- `pnpm rebuild <package>`).
## ذو صلة
- [بناء Plugins](/ar/plugins/building-plugins) — بدء العمل مع Plugins
- [بنية Plugin](/ar/plugins/architecture) — البنية الداخلية
- [نظرة عامة على SDK](/ar/plugins/sdk-overview) — مرجع Plugin SDK
- [Building Plugins](/ar/plugins/building-plugins) — البدء باستخدام Plugins
- [Plugin Architecture](/ar/plugins/architecture) — البنية الداخلية
- [SDK Overview](/ar/plugins/sdk-overview) — مرجع Plugin SDK

353
docs/ar/plugins/sdk-channel-plugins.md
View File

@ -1,102 +1,113 @@
---
read_when:
- أنت تبني plugin جديدًا لقناة مراسلة
- أنت تبني Plugin جديدًا لقناة مراسلة
- تريد ربط OpenClaw بمنصة مراسلة
- تحتاج إلى فهم واجهة المهايئ ChannelPlugin
- تحتاج إلى فهم واجهة المهايئ `ChannelPlugin`
sidebarTitle: Channel Plugins
summary: دليل خطوة بخطوة لبناء plugin لقناة مراسلة لـ OpenClaw
title: بناء plugins القنوات
summary: دليل خطوة بخطوة لبناء Plugin لقناة مراسلة لـ OpenClaw
title: بناء Plugins القنوات
x-i18n:
generated_at: "2026-04-11T02:46:30Z"
generated_at: "2026-04-15T07:17:51Z"
model: gpt-5.4
provider: openai
source_hash: 8a026e924f9ae8a3ddd46287674443bcfccb0247be504261522b078e1f440aef
source_hash: a7f4c746fe3163a8880e14c433f4db4a1475535d91716a53fb879551d8d62f65
source_path: plugins/sdk-channel-plugins.md
workflow: 15
---
# بناء plugins القنوات
# بناء Plugins القنوات
يرشدك هذا الدليل خلال بناء plugin قناة يربط OpenClaw بمنصة
مراسلة. وبنهاية هذا الدليل، سيكون لديك قناة عاملة مع أمان DM،
والاقتران، وتسلسل الردود، والمراسلة الصادرة.
يشرح هذا الدليل كيفية بناء Plugin قناة يربط OpenClaw بمنصة
مراسلة. وبنهاية هذا الدليل سيكون لديك قناة عاملة تتضمن أمان الرسائل
المباشرة، والاقتران، وتوجيه الردود ضمن السلاسل، والرسائل الصادرة.
<Info>
إذا لم تكن قد بنيت أي plugin لـ OpenClaw من قبل، فاقرأ
[البدء](/ar/plugins/building-plugins) أولًا للتعرّف على البنية الأساسية
للحزمة وإعداد manifest.
إذا لم تكن قد أنشأت أي Plugin لـ OpenClaw من قبل، فاقرأ
[البدء](/ar/plugins/building-plugins) أولًا لمعرفة بنية الحزمة
الأساسية وإعداد ملف البيان.
</Info>
## كيف تعمل plugins القنوات
## كيف تعمل Plugins القنوات
لا تحتاج plugins القنوات إلى أدوات send/edit/react خاصة بها. يحتفظ OpenClaw
بأداة `message` مشتركة واحدة في core. ويتولى plugin الخاص بك:
لا تحتاج Plugins القنوات إلى أدوات send/edit/react خاصة بها. يحتفظ OpenClaw
بأداة `message` واحدة مشتركة في النواة. ويتولى Plugin الخاص بك ما يلي:
- **الإعدادات** — تحليل الحسابات ومعالج الإعداد
- **الأمان** — سياسة DM وقوائم السماح
- **الاقتران** — تدفق الموافقة على DM
- **بنية الجلسة** — كيفية ربط معرّفات المحادثات الخاصة بالمزوّد بالدردشات الأساسية ومعرّفات السلاسل والرجوع إلى الأصل
- **الصادر** — إرسال النصوص والوسائط واستطلاعات الرأي إلى المنصة
- **الإعداد** — حلّ الحسابات ومعالج الإعداد
- **الأمان** — سياسة الرسائل المباشرة وقوائم السماح
- **الاقتران** — تدفق الموافقة على الرسائل المباشرة
- **صياغة الجلسة** — كيفية ربط معرّفات المحادثات الخاصة بالموفّر بالمحادثات الأساسية ومعرّفات السلاسل وبدائل الأصل
- **الإرسال الصادر** — إرسال النصوص والوسائط والاستطلاعات إلى المنصة
- **التسلسل** — كيفية ترتيب الردود ضمن السلاسل
يتولى core أداة الرسائل المشتركة، وربط الموجّهات، وبنية مفتاح الجلسة الخارجية،
ومسك الدفاتر العام لـ `:thread:`، والإرسال.
تتولى النواة أداة الرسائل المشتركة، وربط الـ prompt، والشكل الخارجي لمفتاح
الجلسة، وتتبع `:thread:` العام، والإرسال.
إذا كانت منصتك تخزّن نطاقًا إضافيًا داخل معرّفات المحادثات، فأبقِ هذا التحليل
داخل plugin باستخدام `messaging.resolveSessionConversation(...)`. فهذا هو
المدخل القياسي لربط `rawId` بمعرّف المحادثة الأساسي، ومعرّف السلسلة الاختياري،
إذا كانت قناتك تضيف معاملات إلى أداة الرسائل تحمل مصادر وسائط، فاكشف عن أسماء
هذه المعاملات عبر `describeMessageTool(...).mediaSourceParams`. تستخدم النواة
هذه القائمة الصريحة لتطبيع مسارات sandbox ولسياسة الوصول إلى الوسائط الصادرة،
لذلك لا تحتاج Plugins إلى حالات خاصة في النواة المشتركة لمعاملات الصور الرمزية
أو المرفقات أو صور الغلاف الخاصة بموفّر معيّن.
ويُفضّل إرجاع خريطة مفاتيحها مبنية على الإجراء مثل
`{ "set-profile": ["avatarUrl", "avatarPath"] }` حتى لا ترث الإجراءات غير
ذات الصلة معاملات الوسائط الخاصة بإجراء آخر. ولا يزال المصفوفة المسطحة تعمل مع
المعاملات التي يُقصد مشاركتها عمدًا عبر كل إجراء مكشوف.
إذا كانت منصتك تخزّن نطاقًا إضافيًا داخل معرّفات المحادثة، فأبقِ هذا التحليل
داخل Plugin باستخدام `messaging.resolveSessionConversation(...)`. هذا هو
الخطاف المعتمد لربط `rawId` بمعرّف المحادثة الأساسي، ومعرّف السلسلة الاختياري،
و`baseConversationId` الصريح، وأي `parentConversationCandidates`.
وعندما تعيد `parentConversationCandidates`، فأبقِ ترتيبها من
الأصل الأضيق إلى المحادثة الأساسية/الأوسع.
وعندما تُرجع `parentConversationCandidates`، فاحرص على إبقائها مرتبة من
الأصل الأضيق إلى الأصل الأوسع/المحادثة الأساسية.
يمكن أيضًا لـ plugins المضمّنة التي تحتاج إلى التحليل نفسه قبل تشغيل
سجل القنوات أن تعرض ملف `session-key-api.ts` من المستوى الأعلى مع
تصدير مطابق لـ `resolveSessionConversation(...)`. ويستخدم core هذا السطح
الآمن للتهيئة فقط عندما لا يكون سجل plugin في وقت التشغيل متاحًا بعد.
يمكن أيضًا لـ Plugins المضمّنة التي تحتاج إلى التحليل نفسه قبل تشغيل سجل
القنوات أن تكشف عن ملف `session-key-api.ts` على المستوى الأعلى مع
تصدير مطابق لـ `resolveSessionConversation(...)`. تستخدم النواة هذا السطح
الآمن أثناء الإقلاع فقط عندما لا يكون سجل Plugins وقت التشغيل متاحًا بعد.
لا يزال `messaging.resolveParentConversationCandidates(...)` متاحًا كحل
توافقي قديم عندما يحتاج plugin فقط إلى الرجوع إلى المحادثات الأصلية
فوق المعرّف العام/الخام. وإذا وُجد كلا المدخلين، يستخدم core
أولًا `resolveSessionConversation(...).parentConversationCandidates` ثم يعود
إلى `resolveParentConversationCandidates(...)` فقط عندما يهملهما المدخل القياسي.
لا يزال `messaging.resolveParentConversationCandidates(...)` متاحًا كبديل
توافقي قديم عندما يحتاج Plugin فقط إلى بدائل الأصل فوق المعرّف العام/الخام.
إذا وُجد الخطافان معًا، تستخدم النواة
`resolveSessionConversation(...).parentConversationCandidates` أولًا ولا
تعود إلى `resolveParentConversationCandidates(...)` إلا عندما يهمل الخطاف
المعتمد إرجاعها.
## الموافقات وإمكانات القنوات
## الموافقات وإمكانات القناة
لا تحتاج معظم plugins القنوات إلى شيفرة خاصة بالموافقات.
لا تحتاج معظم Plugins القنوات إلى كود خاص بالموافقات.
- يتولى core الأمر `/approve` داخل الدردشة نفسها، وحمولات أزرار الموافقة المشتركة، وآلية التسليم الاحتياطي العامة.
- فضّل كائن `approvalCapability` واحدًا على plugin القناة عندما تحتاج القناة إلى سلوك خاص بالموافقة.
- تمت إزالة `ChannelPlugin.approvals`. ضع حقائق تسليم/أصلي/عرض/مصادقة الموافقة ضمن `approvalCapability`.
- يقتصر `plugin.auth` على login/logout فقط؛ ولم يعد core يقرأ مداخل مصادقة الموافقات من هذا الكائن.
- يُعد `approvalCapability.authorizeActorAction` و`approvalCapability.getActionAvailabilityState` مدخل المصادقة القياسي للموافقات.
- استخدم `approvalCapability.getActionAvailabilityState` لتوفّر مصادقة الموافقة داخل الدردشة نفسها.
- إذا كانت قناتك تعرض موافقات exec أصلية، فاستخدم `approvalCapability.getExecInitiatingSurfaceState` لحالة السطح المبدئي/العميل الأصلي عندما تختلف عن مصادقة الموافقة داخل الدردشة نفسها. ويستخدم core هذا المدخل الخاص بـ exec للتمييز بين `enabled` و`disabled`، وتحديد ما إذا كانت القناة المبدئية تدعم موافقات exec الأصلية، وإدراج القناة في إرشادات العميل الأصلي الاحتياطية. ويملأ `createApproverRestrictedNativeApprovalCapability(...)` ذلك للحالة الشائعة.
- تتولى النواة `/approve` داخل المحادثة نفسها، وحمولات أزرار الموافقة المشتركة، وآلية التسليم العامة البديلة.
- يُفضَّل استخدام كائن `approvalCapability` واحد على Plugin القناة عندما تحتاج القناة إلى سلوك خاص بالموافقة.
- تمت إزالة `ChannelPlugin.approvals`. ضع حقائق تسليم/أصلية/عرض/مصادقة الموافقة على `approvalCapability`.
- يقتصر `plugin.auth` على login/logout فقط؛ لم تعد النواة تقرأ خطافات مصادقة الموافقة من هذا الكائن.
- يُعد `approvalCapability.authorizeActorAction` و`approvalCapability.getActionAvailabilityState` الواجهة المعتمدة لمصادقة الموافقات.
- استخدم `approvalCapability.getActionAvailabilityState` لإتاحة مصادقة الموافقة داخل المحادثة نفسها.
- إذا كانت قناتك تكشف عن موافقات تنفيذ أصلية، فاستخدم `approvalCapability.getExecInitiatingSurfaceState` لحالة سطح البدء/العميل الأصلي عندما تختلف عن مصادقة الموافقة داخل المحادثة نفسها. تستخدم النواة هذا الخطاف الخاص بالتنفيذ للتمييز بين `enabled` و`disabled`، وتحديد ما إذا كانت القناة الداعية تدعم موافقات التنفيذ الأصلية، وإدراج القناة في إرشادات الرجوع إلى العميل الأصلي. يقوم `createApproverRestrictedNativeApprovalCapability(...)` بملء ذلك في الحالة الشائعة.
- استخدم `outbound.shouldSuppressLocalPayloadPrompt` أو `outbound.beforeDeliverPayload` لسلوك دورة حياة الحمولة الخاص بالقناة، مثل إخفاء مطالبات الموافقة المحلية المكررة أو إرسال مؤشرات الكتابة قبل التسليم.
- استخدم `approvalCapability.delivery` فقط لتوجيه الموافقة الأصلية أو منع التسليم الاحتياطي.
- استخدم `approvalCapability.nativeRuntime` للحقائق الأصلية للموافقة المملوكة للقناة. وأبقِه كسول التحميل في نقاط دخول القنوات الساخنة باستخدام `createLazyChannelApprovalNativeRuntimeAdapter(...)`، الذي يمكنه استيراد module وقت التشغيل الخاص بك عند الطلب مع السماح لـ core بتجميع دورة حياة الموافقة.
- استخدم `approvalCapability.render` فقط عندما تحتاج القناة فعلًا إلى حمولات موافقة مخصصة بدلًا من العارض المشترك.
- استخدم `approvalCapability.describeExecApprovalSetup` عندما تريد القناة أن يشرح رد مسار التعطيل مقابض الإعدادات الدقيقة اللازمة لتمكين موافقات exec الأصلية. ويتلقى هذا المدخل `{ channel, channelLabel, accountId }`؛ ويجب على القنوات ذات الحسابات المسماة أن تعرض مسارات ضمن نطاق الحساب مثل `channels.<channel>.accounts.<id>.execApprovals.*` بدلًا من الإعدادات الافتراضية في المستوى الأعلى.
- إذا كانت القناة تستطيع استنتاج هويات DM مستقرة شبيهة بالمالك من الإعدادات الموجودة، فاستخدم `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` — مداخل اختيارية لربط/فك/مسح الإجراءات للأزرار أو التفاعلات الأصلية
- `observe` — مداخل اختيارية لتشخيصات التسليم
- إذا كانت القناة تحتاج إلى كائنات مملوكة لوقت التشغيل مثل عميل أو رمز أو تطبيق Bolt أو مستقبِل webhook، فسجّلها عبر `openclaw/plugin-sdk/channel-runtime-context`. يتيح سجل runtime-context العام لـ core تهيئة المعالجات المعتمدة على الإمكانات من حالة بدء القناة من دون إضافة طبقة ربط خاصة بالموافقات.
- لا تلجأ إلى `createChannelApprovalHandler` أو `createChannelNativeApprovalRuntime` ذوي المستوى الأدنى إلا عندما لا يكون المدخل المعتمد على الإمكانات قادرًا على التعبير عما تحتاجه بعد.
- يجب على القنوات الأصلية للموافقات توجيه كلٍّ من `accountId` و`approvalKind` عبر هذه المساعدات. إذ يبقي `accountId` سياسة الموافقات متعددة الحسابات ضمن نطاق حساب البوت الصحيح، بينما يبقي `approvalKind` سلوك موافقة exec مقابل موافقة plugin متاحًا للقناة من دون تفرعات ثابتة في core.
- يتولى core الآن أيضًا إشعارات إعادة توجيه الموافقات. لذلك يجب ألا ترسل plugins القنوات رسائل متابعة خاصة بها من نوع "تم إرسال الموافقة إلى الرسائل الخاصة / قناة أخرى" من `createChannelNativeApprovalRuntime`؛ بل عرّض بدلًا من ذلك توجيهًا دقيقًا للأصل + DM الخاص بالموافِق عبر مساعدات إمكانات الموافقة المشتركة ودَع core يجمع عمليات التسليم الفعلية قبل نشر أي إشعار مرة أخرى إلى الدردشة التي بدأت الطلب.
- حافظ على نوع معرّف الموافقة المُسلَّم من البداية إلى النهاية. يجب ألا تقوم العملاء الأصلية
بتخمين أو إعادة كتابة توجيه موافقة exec مقابل موافقة plugin استنادًا إلى حالة محلية في القناة.
- يمكن عمدًا لأنواع الموافقات المختلفة أن تعرض أسطحًا أصلية مختلفة.
من الأمثلة المضمّنة الحالية:
- يحتفظ Slack بإتاحة توجيه الموافقات الأصلية لكل من معرّفات exec وplugin.
- يحتفظ Matrix بنفس توجيه DM/القناة الأصلي وتجربة التفاعل عبر reactions لموافقات exec
وplugin، مع الاستمرار في السماح باختلاف المصادقة حسب نوع الموافقة.
- لا يزال `createApproverRestrictedNativeApprovalAdapter` موجودًا كغلاف توافق، لكن الشيفرة الجديدة يجب أن تفضّل منشئ الإمكانات وتعرض `approvalCapability` على plugin.
- استخدم `approvalCapability.delivery` فقط لتوجيه الموافقات الأصلية أو منع التسليم الاحتياطي.
- استخدم `approvalCapability.nativeRuntime` للحقائق الأصلية الخاصة بالموافقة التي تملكها القناة. أبقه كسول التحميل في نقاط دخول القنوات الساخنة باستخدام `createLazyChannelApprovalNativeRuntimeAdapter(...)`، إذ يمكنه استيراد وحدة وقت التشغيل عند الطلب مع الاستمرار في تمكين النواة من تجميع دورة حياة الموافقة.
- استخدم `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`. يتيح سجل سياق وقت التشغيل العام للنواة إقلاع المعالجات المبنية على الإمكانات انطلاقًا من حالة بدء القناة من دون إضافة طبقة ربط خاصة بالموافقة.
- لا تلجأ إلى `createChannelApprovalHandler` أو `createChannelNativeApprovalRuntime` منخفضَي المستوى إلا عندما لا تكون الواجهة المعتمدة على الإمكانات معبّرة بما يكفي بعد.
- يجب على قنوات الموافقة الأصلية تمرير كلٍّ من `accountId` و`approvalKind` عبر هذه المساعدات. يُبقي `accountId` سياسة الموافقة متعددة الحسابات ضمن نطاق حساب البوت الصحيح، ويُبقي `approvalKind` سلوك موافقة التنفيذ مقابل موافقة Plugin متاحًا للقناة من دون تفرعات مضمّنة في النواة.
- تتولى النواة الآن أيضًا إشعارات إعادة توجيه الموافقة. يجب ألا ترسل Plugins القنوات رسائل متابعة خاصة بها من نوع "تم إرسال الموافقة إلى الرسائل المباشرة / قناة أخرى" من `createChannelNativeApprovalRuntime`؛ بل اكشف بدلًا من ذلك عن توجيه دقيق للأصل + الرسائل المباشرة للموافق عبر مساعدات إمكانات الموافقة المشتركة، ودع النواة تجمع عمليات التسليم الفعلية قبل نشر أي إشعار مرة أخرى إلى محادثة البدء.
- حافظ على نوع معرّف الموافقة المُسلَّم من البداية إلى النهاية. يجب ألا
تخمّن العملاء الأصلية أو تعيد كتابة توجيه موافقة التنفيذ مقابل موافقة Plugin
اعتمادًا على حالة محلية خاصة بالقناة.
- يمكن لأنواع الموافقة المختلفة أن تكشف عمدًا عن أسطح أصلية مختلفة.
الأمثلة المضمّنة الحالية:
- يُبقي Slack توجيه الموافقات الأصلية متاحًا لكلٍّ من معرّفات موافقة التنفيذ وموافقة Plugin.
- يُبقي Matrix توجيه الرسائل المباشرة/القناة الأصلي نفسه وتجربة UX نفسها القائمة على التفاعل لكلٍّ من موافقات التنفيذ وموافقات Plugin، مع الاستمرار في السماح باختلاف المصادقة حسب نوع الموافقة.
- لا يزال `createApproverRestrictedNativeApprovalAdapter` موجودًا كغلاف توافقي، لكن يجب أن يفضّل الكود الجديد باني الإمكانات وأن يكشف `approvalCapability` على Plugin.
بالنسبة إلى نقاط دخول القنوات الساخنة، فضّل المسارات الفرعية الأضيق لوقت التشغيل عندما تحتاج فقط
بالنسبة إلى نقاط دخول القنوات الساخنة، يُفضّل استخدام المسارات الفرعية الأضيق لوقت التشغيل عندما تحتاج فقط
إلى جزء واحد من هذه المجموعة:
- `openclaw/plugin-sdk/approval-auth-runtime`
@ -109,90 +120,94 @@ x-i18n:
- `openclaw/plugin-sdk/approval-reply-runtime`
- `openclaw/plugin-sdk/channel-runtime-context`
وبالمثل، فضّل `openclaw/plugin-sdk/setup-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`)، ومخرجات
مهايئات ترقيع الإعداد الآمنة للاستيراد (`createPatchedAccountSetupAdapter`,
`createEnvPatchedAccountSetupAdapter`,
`createSetupInputPresenceValidator`)، ومخرجات
ملاحظات البحث، و`promptResolvedAllowFrom`، و`splitSetupEntries`، وبُناة
setup-proxy المُفوَّضة
- يمثل `openclaw/plugin-sdk/setup-adapter-runtime` المدخل الضيق
الواعي بالبيئة لـ `createEnvPatchedAccountSetupAdapter`
- يغطي `openclaw/plugin-sdk/channel-setup` بُناة الإعداد ذات التثبيت الاختياري بالإضافة إلى بعض العناصر الأولية الآمنة للإعداد:
`createOptionalChannelSetupSurface` و`createOptionalChannelSetupAdapter`،
الوكيل المفوّض للإعداد
- يمثّل `openclaw/plugin-sdk/setup-adapter-runtime` الواجهة
الضيقة الواعية بالبيئة الخاصة بـ `createEnvPatchedAccountSetupAdapter`
- يغطي `openclaw/plugin-sdk/channel-setup` بُناة الإعداد
الخاصة بالتثبيت الاختياري بالإضافة إلى بعض الأساسيات الآمنة للإعداد:
`createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`,
إذا كانت قناتك تدعم الإعداد أو المصادقة المدفوعين بالبيئة ويجب أن تعرف تدفقات البدء/الإعدادات العامة
أسماء متغيرات البيئة هذه قبل تحميل وقت التشغيل، فأعلن عنها في
manifest الخاص بـ plugin ضمن `channelEnvVars`. وأبقِ `envVars` الخاصة بوقت تشغيل القناة أو الثوابت المحلية
للنص الموجّه للمشغّل فقط.
`createOptionalChannelSetupWizard`، و`DEFAULT_ACCOUNT_ID`،
و`createTopLevelChannelDmPolicy`، و`setSetupChannelEnabled`، و
إذا كانت قناتك تدعم إعدادًا أو مصادقة مدفوعَين بالبيئة وكان ينبغي أن تعرف
تدفقات الإقلاع/الإعداد العامة أسماء متغيرات البيئة هذه قبل تحميل وقت التشغيل،
فصرّح بها في ملف بيان Plugin عبر `channelEnvVars`. واحتفظ بـ
`envVars` الخاص بوقت تشغيل القناة أو الثوابت المحلية لنسخ النصوص الموجّهة
للمشغّل فقط.
`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/messaging-targets` لتحليل/مطابقة الأهداف
`openclaw/plugin-sdk/inbound-reply-dispatch` لربط
المسار/الغلاف الوارد وتسجيله ثم إرساله
- `openclaw/plugin-sdk/messaging-targets` لتحليل الأهداف ومطابقتها
- `openclaw/plugin-sdk/outbound-media` و
`openclaw/plugin-sdk/outbound-runtime` لتحميل الوسائط بالإضافة إلى
مفوّضي الهوية/الإرسال الصادر
`openclaw/plugin-sdk/outbound-runtime` لتحميل الوسائط
بالإضافة إلى مفوّضي الهوية/الإرسال الصادر
- `openclaw/plugin-sdk/thread-bindings-runtime` لدورة حياة ربط السلاسل
وتسجيل المهايئات
- `openclaw/plugin-sdk/agent-media-payload` فقط عندما يظل هناك حاجة إلى
تخطيط حقول حمولة agent/media قديم
- `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-inbound` للطبقة المشتركة.
ما يناسب المنطق المحلي في plugin:
ملائم لمنطق Plugin المحلي:
- اكتشاف الرد على البوت
- اكتشاف الاقتباس من البوت
- فحوصات المشاركة في السلاسل
- استثناءات رسائل الخدمة/النظام
- الذاكرات المؤقتة الأصلية للمنصة اللازمة لإثبات مشاركة البوت
- التحقق من المشاركة في السلسلة
- استبعاد رسائل الخدمة/النظام
- الذاكرات المؤقتة الأصلية الخاصة بالمنصة اللازمة لإثبات مشاركة البوت
ما يناسب المساعد المشترك:
ملائم للمساعد المشترك:
- `requireMention`
- نتيجة الإشارة الصريحة
- قائمة السماح للإشارة الضمنية
- قائمة سماح الإشارة الضمنية
- تجاوز الأوامر
- قرار التخطي النهائي
@ -200,7 +215,7 @@ manifest الخاص بـ plugin ضمن `channelEnvVars`. وأبقِ `envVars` ا
1. احسب حقائق الإشارة المحلية.
2. مرّر هذه الحقائق إلى `resolveInboundMentionDecision({ facts, policy })`.
3. استخدم `decision.effectiveWasMentioned` و`decision.shouldBypassMention` و`decision.shouldSkip` في بوابة الوارد الخاصة بك.
3. استخدم `decision.effectiveWasMentioned` و`decision.shouldBypassMention` و`decision.shouldSkip` في بوابة الوارد لديك.
```typescript
import {
@ -240,7 +255,7 @@ if (decision.shouldSkip) return;
```
يكشف `api.runtime.channel.mentions` عن مساعدات الإشارة المشتركة نفسها
لـ plugins القنوات المضمّنة التي تعتمد أصلًا على حقن وقت التشغيل:
لـ Plugins القنوات المضمّنة التي تعتمد بالفعل على حقن وقت التشغيل:
- `buildMentionRegexes`
- `matchesMentionPatterns`
@ -248,18 +263,18 @@ if (decision.shouldSkip) return;
- `implicitMentionKindWhen`
- `resolveInboundMentionDecision`
تظل مساعدات `resolveMentionGating*` الأقدم موجودة على
`openclaw/plugin-sdk/channel-inbound` كتصديرات توافق فقط. ويجب أن تستخدم الشيفرة الجديدة
`resolveInboundMentionDecision({ facts, policy })`.
تبقى مساعدات `resolveMentionGating*` الأقدم موجودة على
`openclaw/plugin-sdk/channel-inbound` كتصديرات توافقية فقط. يجب أن يستخدم
الكود الجديد `resolveInboundMentionDecision({ facts, policy })`.
## شرح عملي
<Steps>
<a id="step-1-package-and-manifest"></a>
<Step title="الحزمة وmanifest">
أنشئ ملفات plugin القياسية. الحقل `channel` في `package.json` هو
ما يجعل هذا plugin قناة. وللاطلاع على السطح الكامل لبيانات تعريف الحزمة،
راجع [إعداد plugin وتهيئته](/ar/plugins/sdk-setup#openclaw-channel):
<Step title="الحزمة وملف البيان">
أنشئ ملفات Plugin القياسية. إن الحقل `channel` في `package.json` هو
ما يجعل هذا Plugin قناة. وللاطلاع على سطح بيانات الحزمة الكامل،
راجع [إعداد Plugin وضبطه](/ar/plugins/sdk-setup#openclaw-channel):
<CodeGroup>
```json package.json
@ -308,7 +323,7 @@ if (decision.shouldSkip) return;
</Step>
<Step title="بناء كائن plugin القناة">
<Step title="أنشئ كائن Plugin القناة">
تحتوي الواجهة `ChannelPlugin` على العديد من أسطح المهايئات الاختيارية. ابدأ
بالحد الأدنى — `id` و`setup` — ثم أضف المهايئات حسب الحاجة.
@ -405,24 +420,24 @@ if (decision.shouldSkip) return;
});
```
<Accordion title="ما الذي يفعله `createChatChannelPlugin` من أجلك">
بدلًا من تنفيذ واجهات المهايئات منخفضة المستوى يدويًا، فإنك تمرر
خيارات تعريفية ويتولى المنشئ تركيبها:
<Accordion title="ما الذي يقدمه لك createChatChannelPlugin">
بدلًا من تنفيذ واجهات المهايئات منخفضة المستوى يدويًا، تمرّر
خيارات تصريحية ويتولى الباني تجميعها:
| الخيار | ما الذي يربطه |
| Option | ما الذي يربطه |
| --- | --- |
| `security.dm` | محلل أمان DM ضمن النطاق من حقول الإعدادات |
| `pairing.text` | تدفق اقتران DM قائم على النص مع تبادل الرمز |
| `threading` | محلل وضع reply-to (ثابت، أو ضمن نطاق الحساب، أو مخصص) |
| `outbound.attachedResults` | دوال إرسال تُرجع بيانات تعريف النتيجة (معرّفات الرسائل) |
| `security.dm` | محلّل أمان الرسائل المباشرة المقيّد بنطاق حقول الإعداد |
| `pairing.text` | تدفق اقتران رسائل مباشرة قائم على النص مع تبادل الرموز |
| `threading` | محلّل نمط الرد (ثابت، مقيّد بالحساب، أو مخصص) |
| `outbound.attachedResults` | دوال إرسال تُرجع بيانات تعريفية للنتيجة (معرّفات الرسائل) |
يمكنك أيضًا تمرير كائنات مهايئات خام بدلًا من الخيارات التعريفية
يمكنك أيضًا تمرير كائنات مهايئ خام بدلًا من الخيارات التصريحية
إذا كنت تحتاج إلى تحكم كامل.
</Accordion>
</Step>
<Step title="ربط نقطة الإدخال">
<Step title="اربط نقطة الدخول">
أنشئ `index.ts`:
```typescript index.ts
@ -458,21 +473,21 @@ 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` فصل أوضاع التسجيل تلقائيًا. راجع
[نقاط الإدخال](/ar/plugins/sdk-entrypoints#definechannelpluginentry) للاطلاع على جميع
يتولى `defineChannelPluginEntry` معالجة تقسيم وضع التسجيل تلقائيًا. راجع
[نقاط الدخول](/ar/plugins/sdk-entrypoints#definechannelpluginentry) لمعرفة جميع
الخيارات.
</Step>
<Step title="إضافة إدخال إعداد">
<Step title="أضف نقطة دخول للإعداد">
أنشئ `setup-entry.ts` للتحميل الخفيف أثناء الإعداد الأولي:
```typescript setup-entry.ts
@ -482,16 +497,16 @@ if (decision.shouldSkip) return;
export default defineSetupPluginEntry(acmeChatPlugin);
```
يحمّل OpenClaw هذا بدلًا من الإدخال الكامل عندما تكون القناة معطلة
أو غير مكوّنة. وهذا يتجنب سحب شيفرة وقت تشغيل ثقيلة أثناء تدفقات الإعداد.
راجع [الإعداد والتهيئة](/ar/plugins/sdk-setup#setup-entry) لمزيد من التفاصيل.
يحمّل OpenClaw هذا بدلًا من نقطة الدخول الكاملة عندما تكون القناة معطّلة
أو غير مهيأة. وهذا يتجنب سحب كود وقت تشغيل ثقيل أثناء تدفقات الإعداد.
راجع [الإعداد والضبط](/ar/plugins/sdk-setup#setup-entry) لمعرفة التفاصيل.
</Step>
<Step title="معالجة الرسائل الواردة">
يحتاج plugin الخاص بك إلى استقبال الرسائل من المنصة وتمريرها إلى
OpenClaw. والنمط المعتاد هو webhook يتحقق من الطلب
ويرسله عبر معالج الوارد الخاص بقناتك:
<Step title="عالج الرسائل الواردة">
يحتاج Plugin الخاص بك إلى استلام الرسائل من المنصة وتمريرها إلى
OpenClaw. النمط الشائع هو Webhook يتحقق من الطلب ثم
يرسله عبر معالج الوارد الخاص بقناتك:
```typescript
registerFull(api) {
@ -515,16 +530,16 @@ if (decision.shouldSkip) return;
```
<Note>
معالجة الرسائل الواردة خاصة بكل قناة. فكل plugin قناة يملك
مسار الوارد الخاص به. انظر إلى plugins القنوات المضمّنة
(مثل حزمة plugin الخاصة بـ Microsoft Teams أو Google Chat) للاطلاع على أنماط فعلية.
معالجة الرسائل الواردة خاصة بكل قناة. كل Plugin قناة يملك
خط أنبوب الوارد الخاص به. انظر إلى Plugins القنوات المضمّنة
(مثل حزمة Plugin الخاصة بـ Microsoft Teams أو Google Chat) للاطلاع على أنماط فعلية.
</Note>
</Step>
<a id="step-6-test"></a>
<Step title="الاختبار">
اكتب اختبارات موضوعة بجانب الشيفرة في `src/channel.test.ts`:
اكتب اختبارات مرافقة في `src/channel.test.ts`:
```typescript src/channel.test.ts
import { describe, it, expect } from "vitest";
@ -571,8 +586,8 @@ if (decision.shouldSkip) return;
```
<bundled-plugin-root>/acme-chat/
├── package.json # بيانات تعريف openclaw.channel
├── openclaw.plugin.json # Manifest مع مخطط الإعدادات
├── package.json # بيانات openclaw.channel الوصفية
├── openclaw.plugin.json # ملف البيان مع مخطط الإعداد
├── index.ts # defineChannelPluginEntry
├── setup-entry.ts # defineSetupPluginEntry
├── api.ts # التصديرات العامة (اختياري)
@ -580,7 +595,7 @@ if (decision.shouldSkip) return;
└── src/
├── channel.ts # ChannelPlugin عبر createChatChannelPlugin
├── channel.test.ts # الاختبارات
├── client.ts # عميل API الخاص بالمنصة
├── client.ts # عميل API للمنصة
└── runtime.ts # مخزن وقت التشغيل (عند الحاجة)
```
@ -588,7 +603,7 @@ if (decision.shouldSkip) return;
<CardGroup cols={2}>
<Card title="خيارات التسلسل" icon="git-branch" href="/ar/plugins/sdk-entrypoints#registration-mode">
أوضاع reply ثابتة أو ضمن نطاق الحساب أو مخصصة
أوضاع رد ثابتة، أو مقيّدة بالحساب، أو مخصصة
</Card>
<Card title="تكامل أداة الرسائل" icon="puzzle" href="/ar/plugins/architecture#channel-plugins-and-the-shared-message-tool">
describeMessageTool واكتشاف الإجراءات
@ -602,15 +617,15 @@ if (decision.shouldSkip) return;
</CardGroup>
<Note>
لا تزال بعض المداخل المساعدة المضمّنة موجودة لصيانة plugins المضمّنة
ولأغراض التوافق. لكنها ليست النمط الموصى به لـ plugins القنوات الجديدة؛
فضّل المسارات الفرعية العامة channel/setup/reply/runtime من
سطح SDK المشترك ما لم تكن تصون تلك العائلة من plugins المضمّنة مباشرة.
لا تزال بعض واجهات المساعدات المضمّنة موجودة لصيانة Plugins المضمّنة
ولأغراض التوافق. وهي ليست النمط الموصى به لـ Plugins القنوات الجديدة؛
بل يُفضّل استخدام المسارات الفرعية العامة channel/setup/reply/runtime من
سطح SDK المشترك ما لم تكن تصون تلك العائلة من Plugins المضمّنة مباشرةً.
</Note>
## الخطوات التالية
- [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) — أدوات الاختبار واختبارات العقود
- [Manifest الخاص بـ plugin](/ar/plugins/manifest) — المخطط الكامل لـ manifest
- [ملف بيان Plugin](/ar/plugins/manifest) — المخطط الكامل لملف البيان

227
docs/ar/reference/RELEASING.md
View File

@ -5,10 +5,10 @@ read_when:
summary: قنوات الإصدار العامة، وتسمية الإصدارات، والوتيرة
title: سياسة الإصدار
x-i18n:
generated_at: "2026-04-14T07:17:39Z"
generated_at: "2026-04-15T07:17:46Z"
model: gpt-5.4
provider: openai
source_hash: 3eaf9f1786b8c9fd4f5a9c657b623cb69d1a485958e1a9b8f108511839b63587
source_hash: 88724307269ab783a9fbf8a0540fea198d8a3add68457f4e64d5707114fa518c
source_path: reference/RELEASING.md
workflow: 15
---
@ -17,178 +17,171 @@ x-i18n:
لدى OpenClaw ثلاث مسارات إصدار عامة:
- stable: إصدارات موسومة تُنشر إلى npm `beta` افتراضيًا، أو إلى npm `latest` عند الطلب الصريح
- beta: وسوم إصدارات تمهيدية تُنشر إلى npm `beta`
- stable: إصدارات موسومة تُنشَر إلى npm `beta` افتراضيًا، أو إلى npm `latest` عند الطلب الصريح
- beta: وسوم إصدارات تمهيدية تُنشَر إلى npm `beta`
- dev: الرأس المتحرك لفرع `main`
## تسمية الإصدارات
- إصدار الإصدار المستقر: `YYYY.M.D`
- وسم Git: `vYYYY.M.D`
- إصدار تصحيح الإصدار المستقر: `YYYY.M.D-N`
- إصدار التصحيح للإصدار المستقر: `YYYY.M.D-N`
- وسم Git: `vYYYY.M.D-N`
- إصدار بيتا التمهيدي: `YYYY.M.D-beta.N`
- إصدار beta التمهيدي: `YYYY.M.D-beta.N`
- وسم Git: `vYYYY.M.D-beta.N`
- لا تُضِف أصفارًا بادئة إلى الشهر أو اليوم
- لا تضف أصفارًا بادئة إلى الشهر أو اليوم
- `latest` يعني إصدار npm المستقر المُرقّى الحالي
- `beta` يعني هدف تثبيت بيتا الحالي
- تُنشر الإصدارات المستقرة وإصدارات التصحيح المستقرة إلى npm `beta` افتراضيًا؛ ويمكن لمشغّلي الإصدار استهداف `latest` صراحةً، أو ترقية بنية بيتا مُتحقَّق منها لاحقًا
- يشحن كل إصدار من OpenClaw حزمة npm وتطبيق macOS معًا
- `beta` يعني هدف تثبيت beta الحالي
- تُنشَر الإصدارات المستقرة وتصحيحات الإصدارات المستقرة إلى npm `beta` افتراضيًا؛ ويمكن لمشغّلي الإصدار استهداف `latest` صراحةً، أو ترقية بنية beta تم التحقق منها لاحقًا
- كل إصدار من OpenClaw يشحن حزمة npm وتطبيق macOS معًا
## وتيرة الإصدار
- تبدأ الإصدارات من beta أولًا
- لا يأتي stable إلا بعد التحقق من أحدث beta
- إجراء الإصدار التفصيلي، والموافقات، وبيانات الاعتماد، وملاحظات الاسترداد
- تبدأ الإصدارات عبر beta أولًا
- لا يأتي الإصدار المستقر إلا بعد التحقق من أحدث إصدار beta
- إن إجراءات الإصدار التفصيلية، والموافقات، وبيانات الاعتماد، وملاحظات الاسترداد
مخصّصة للمشرفين فقط
## التحقق المسبق للإصدار
## الفحوصات التمهيدية للإصدار
- شغّل `pnpm build && pnpm ui:build` قبل `pnpm release:check` حتى تكون
عناصر إصدار `dist/*` المتوقعة وحزمة Control UI موجودة من أجل
عناصر الإصدار المتوقعة `dist/*` وحزمة Control UI موجودة من أجل
خطوة التحقق من الحزمة
- شغّل `pnpm release:check` قبل كل إصدار موسوم
- تعمل الآن فحوصات الإصدار ضمن سير عمل يدوي منفصل:
- تعمل فحوصات الإصدار الآن ضمن سير عمل يدوي منفصل:
`OpenClaw Release Checks`
- هذا الفصل مقصود: إبقاء مسار إصدار npm الحقيقي قصيرًا،
- يتم إرسال التحقق من التثبيت والترقية عبر الأنظمة المختلفة وقت التشغيل من
سير العمل الخاص المستدعي
`openclaw/releases-private/.github/workflows/openclaw-cross-os-release-checks.yml`,
الذي يستدعي سير العمل العام القابل لإعادة الاستخدام
`.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
- هذا الفصل مقصود: للحفاظ على مسار إصدار npm الفعلي قصيرًا،
وحتميًا، ومركّزًا على العناصر، بينما تبقى الفحوصات الحية الأبطأ في
مسارها الخاص حتى لا تؤخر النشر أو تمنعه
- يجب تشغيل فحوصات الإصدار من مرجع سير العمل `main` حتى تبقى
منطقية سير العمل والأسرار معتمدة وموحدة
- يقبل سير العمل هذا إما وسم إصدار موجودًا أو SHA الكامل الحالي
المكوّن من 40 حرفًا لالتزام `main`
- في وضع commit-SHA، لا يقبل إلا HEAD الحالي لـ `origin/main`؛ استخدم
وسم إصدار للالتزامات الأقدم الخاصة بالإصدار
- يقبل التحقق المسبق للتحقق فقط في `OpenClaw NPM Release` أيضًا
SHA الكامل الحالي المكوّن من 40 حرفًا لالتزام `main` من دون الحاجة إلى وسم مدفوع
- هذا المسار المعتمد على SHA مخصص للتحقق فقط ولا يمكن ترقيته إلى نشر حقيقي
- في وضع SHA، ينشئ سير العمل `v<package.json version>` فقط
من أجل فحص بيانات تعريف الحزمة؛ ولا يزال النشر الحقيقي يتطلب وسم إصدار حقيقي
- يُبقي كلا سيرَي العمل مسار النشر والترقية الحقيقيين على مشغّلات GitHub المستضافة،
بينما يمكن لمسار التحقق غير المُعدِّل استخدام مشغّلات
Blacksmith Linux الأكبر
مسارها الخاص حتى لا تؤخر أو تمنع النشر
- يجب إرسال فحوصات الإصدار من مرجع سير عمل `main` حتى تبقى
منطقية سير العمل والأسرار معتمدة وقياسية
- يقبل سير العمل هذا إما وسم إصدار موجودًا أو قيمة SHA كاملة من 40 حرفًا
لالتزام `main` الحالي
- في وضع SHA الخاص بالالتزام، لا يقبل إلا HEAD الحالي لـ `origin/main`؛ استخدم
وسم إصدار لالتزامات الإصدار الأقدم
- إن الفحص التمهيدي للتحقق فقط في `OpenClaw NPM Release` يقبل أيضًا
قيمة SHA كاملة من 40 حرفًا لالتزام `main` الحالي دون الحاجة إلى وسم مدفوع
- هذا المسار الخاص بـ SHA مخصّص للتحقق فقط ولا يمكن ترقيته إلى نشر فعلي
- في وضع SHA، ينشئ سير العمل `v<package.json version>` فقط من أجل
فحص بيانات الحزمة؛ أما النشر الفعلي فما زال يتطلب وسم إصدار حقيقي
- يحافظ كلا سيرَي العمل على مسار النشر والترقية الفعليين على
GitHub-hosted runners، بينما يمكن لمسار التحقق غير المعدِّل استخدام
مشغلات Blacksmith Linux الأكبر
- يشغّل سير العمل هذا
`OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`
باستخدام سريَي سير العمل `OPENAI_API_KEY` و`ANTHROPIC_API_KEY`
- لم يعد التحقق المسبق لإصدار npm ينتظر مسار فحوصات الإصدار المنفصل
باستخدام سريَّي سير العمل `OPENAI_API_KEY` و`ANTHROPIC_API_KEY`
- لم يعد الفحص التمهيدي لإصدار npm ينتظر مسار فحوصات الإصدار المنفصل
- شغّل `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`
(أو وسم beta/التصحيح المطابق) قبل الموافقة
- بعد نشر npm، شغّل
`node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`
(أو إصدار beta/التصحيح المطابق) للتحقق من
مسار التثبيت من السجل المنشور في بادئة temp جديدة
- تستخدم الآن أتمتة الإصدار الخاصة بالمشرفين أسلوب التحقق المسبق ثم الترقية:
- يجب أن يمر نشر npm الحقيقي عبر `preflight_run_id` ناجح لـ npm
(أو إصدار beta/التصحيح المطابق) للتحقق من مسار التثبيت من السجل المنشور
في بادئة مؤقتة جديدة
- تستخدم أتمتة الإصدار الخاصة بالمشرفين الآن أسلوب الفحص التمهيدي ثم الترقية:
- يجب أن يجتاز نشر npm الفعلي قيمة `preflight_run_id` ناجحة لـ npm
- تُوجَّه إصدارات npm المستقرة إلى `beta` افتراضيًا
- يمكن أن يستهدف نشر npm المستقر `latest` صراحةً عبر إدخال سير العمل
- ما تزال ترقية npm المستقرة من `beta` إلى `latest` متاحة كوضع يدوي صريح ضمن سير العمل الموثوق `OpenClaw NPM Release`
- يمكن أيضًا لعمليات النشر المستقرة المباشرة تشغيل وضع مزامنة `dist-tag` صريح
يشير فيه كل من `latest` و`beta` إلى الإصدار المستقر المنشور بالفعل
- ما تزال أوضاع `dist-tag` هذه تحتاج إلى `NPM_TOKEN` صالح في بيئة `npm-release` لأن إدارة npm `dist-tag` منفصلة عن النشر الموثوق
- إصدار `macOS Release` العام مخصص للتحقق فقط
- يجب أن يمر نشر mac الخاص الحقيقي والخاص عبر
`preflight_run_id` و`validate_run_id` ناجحين لـ mac الخاص
- تروّج مسارات النشر الحقيقية للعناصر المُحضّرة بدلًا من إعادة بنائها
مرة أخرى
- بالنسبة إلى إصدارات التصحيح المستقرة مثل `YYYY.M.D-N`، يتحقق مُراجِع ما بعد النشر
أيضًا من مسار الترقية نفسه في بادئة temp من `YYYY.M.D` إلى `YYYY.M.D-N`
حتى لا تترك تصحيحات الإصدار بصمت عمليات التثبيت العالمية الأقدم على
- يمكن لنشر npm المستقر استهداف `latest` صراحةً عبر مدخلات سير العمل
- أصبحت عملية تغيير npm dist-tag المعتمدة على الرمز المميز موجودة الآن في
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
لأسباب أمنية، لأن `npm dist-tag add` لا يزال يحتاج إلى `NPM_TOKEN` بينما يحتفظ
المستودع العام بنشر يعتمد على OIDC فقط
- إن `macOS Release` العام مخصّص للتحقق فقط
- يجب أن يجتاز النشر الخاص الفعلي لـ mac قيمة mac خاصة ناجحة لكل من
`preflight_run_id` و`validate_run_id`
- تقوم مسارات النشر الفعلية بترقية العناصر المُحضّرة بدلًا من
إعادة بنائها مرة أخرى
- بالنسبة إلى إصدارات التصحيح المستقرة مثل `YYYY.M.D-N`، يتحقق فاحص ما بعد النشر
أيضًا من مسار الترقية نفسه في البادئة المؤقتة من `YYYY.M.D` إلى `YYYY.M.D-N`
حتى لا تترك تصحيحات الإصدار تثبيتات global الأقدم بصمت على
الحمولة الأساسية للإصدار المستقر
- يفشل التحقق المسبق لإصدار npm بشكل مغلق ما لم تتضمن الحزمة المضغوطة كلاً من
`dist/control-ui/index.html` وحمولة غير فارغة ضمن `dist/control-ui/assets/`
حتى لا نشحن مجددًا لوحة متصفح فارغة
- يفرض `pnpm test:install:smoke` أيضًا ميزانية `unpackedSize` الخاصة بحزمة npm
على الحزمة المرشحة للتحديث، بحيث تلتقط اختبارات e2e الخاصة بالمثبّت تضخم الحزمة غير المقصود
قبل مسار نشر الإصدار
- إذا كانت أعمال الإصدار قد مست تخطيط CI أو بيانات توقيت الإضافات أو
مصفوفات اختبارات الإضافات، فأعِد توليد وراجِع
مخرجات مصفوفة سير العمل `checks-node-extensions` المملوكة للمخطِّط من `.github/workflows/ci.yml`
قبل الموافقة حتى لا تصف ملاحظات الإصدار تخطيط CI قديمًا
- تتضمن جاهزية إصدار macOS المستقر أيضًا أسطح أداة التحديث:
- يجب أن ينتهي إصدار GitHub محتويًا على `.zip` و`.dmg` و`.dSYM.zip` المُعبأة
- يفشل الفحص التمهيدي لإصدار npm بشكل مغلق ما لم تتضمن الحزمة المضغوطة كِلا
`dist/control-ui/index.html` وحمولة غير فارغة لـ `dist/control-ui/assets/`
حتى لا نشحن لوحة تحكم متصفح فارغة مرة أخرى
- يفرض `pnpm test:install:smoke` أيضًا ميزانية `unpackedSize` الخاصة بحزمة npm على
الحزمة المضغوطة المرشحة للتحديث، بحيث تلتقط اختبارات المُثبّت الشاملة
التضخم العرضي في الحزمة قبل مسار نشر الإصدار
- إذا لمس عمل الإصدار تخطيط CI أو ملفات توقيت الإضافات أو
مصفوفات اختبارات الإضافات، فأعد توليد وراجع مخرجات مصفوفة سير العمل
`checks-node-extensions` المملوكة للمخطط من `.github/workflows/ci.yml`
قبل الموافقة حتى لا تصف ملاحظات الإصدار بنية CI قديمة
- يتضمن جاهزية إصدار macOS المستقر أيضًا أسطح التحديث:
- يجب أن ينتهي إصدار GitHub مع الحزم `.zip` و`.dmg` و`.dSYM.zip`
- يجب أن يشير `appcast.xml` على `main` إلى ملف zip المستقر الجديد بعد النشر
- يجب أن يحافظ التطبيق المُعبأ على معرّف حزمة غير تصحيحي، وURL غير فارغ
لخلاصة Sparkle، و`CFBundleVersion` يساوي أو يفوق حد Sparkle الأدنى القياسي
لإصدار ذلك الإصدار
- يجب أن يحتفظ التطبيق المعبأ بمعرّف حزمة غير خاص بالتصحيح، وعنوان URL غير فارغ
لخلاصة Sparkle، وقيمة `CFBundleVersion` تساوي أو تتجاوز الحد الأدنى
المعتمد لبناء Sparkle لذلك الإصدار
## مُدخلات سير عمل NPM
## مدخلات سير عمل NPM
يقبل `OpenClaw NPM Release` مُدخلات يتحكم بها المشغّل كما يلي:
يقبل `OpenClaw NPM Release` مدخلات يتحكم بها المشغّل التالية:
- `tag`: وسم الإصدار المطلوب مثل `v2026.4.2` أو `v2026.4.2-1` أو
`v2026.4.2-beta.1`؛ وعند `preflight_only=true`، يمكن أن يكون أيضًا
SHA الكامل الحالي المكوّن من 40 حرفًا لالتزام `main` من أجل تحقق مسبق للتحقق فقط
- `preflight_only`: القيمة `true` للتحقق/البناء/الحزمة فقط، و`false` لمسار
النشر الحقيقي
- `preflight_run_id`: مطلوب في مسار النشر الحقيقي حتى يعيد سير العمل استخدام
الحزمة المضغوطة المُحضّرة من تشغيل التحقق المسبق الناجح
- `tag`: وسم إصدار مطلوب مثل `v2026.4.2` أو `v2026.4.2-1` أو
`v2026.4.2-beta.1`; وعندما يكون `preflight_only=true`، يمكن أن يكون أيضًا
قيمة SHA كاملة من 40 حرفًا لالتزام `main` الحالي للتحقق التمهيدي فقط
- `preflight_only`: `true` للتحقق/البناء/الحزمة فقط، و`false` لمسار النشر
الفعلي
- `preflight_run_id`: مطلوب في مسار النشر الفعلي حتى يعيد سير العمل استخدام
الحزمة المضغوطة المُحضّرة من تشغيل الفحص التمهيدي الناجح
- `npm_dist_tag`: وسم npm الهدف لمسار النشر؛ والقيمة الافتراضية هي `beta`
- `promote_beta_to_latest`: القيمة `true` لتخطي النشر ونقل
بنية `beta` مستقرة منشورة بالفعل إلى `latest`
- `sync_stable_dist_tags`: القيمة `true` لتخطي النشر وتوجيه كل من `latest` و
`beta` إلى إصدار مستقر منشور بالفعل
يقبل `OpenClaw Release Checks` مُدخلات يتحكم بها المشغّل كما يلي:
يقبل `OpenClaw Release Checks` مدخلات يتحكم بها المشغّل التالية:
- `ref`: وسم إصدار موجود أو SHA الكامل الحالي المكوّن من 40 حرفًا لالتزام `main`
للتحقق
- `ref`: وسم إصدار موجود أو قيمة SHA كاملة من 40 حرفًا لالتزام `main`
الحالي من أجل التحقق
القواعد:
- يمكن لوسوم stable ووسوم التصحيح النشر إلى `beta` أو `latest`
- يمكن لوسوم stable وcorrection النشر إلى `beta` أو `latest`
- يمكن لوسوم beta التمهيدية النشر إلى `beta` فقط
- يُسمح بإدخال SHA الكامل للالتزام فقط عندما يكون `preflight_only=true`
- يتطلب وضع commit-SHA في فحوصات الإصدار أيضًا HEAD الحالي لـ `origin/main`
- يجب أن يستخدم مسار النشر الحقيقي القيمة نفسها لـ `npm_dist_tag` المستخدمة أثناء التحقق المسبق؛
ويتحقق سير العمل من تلك البيانات التعريفية قبل متابعة النشر
- يجب أن يستخدم وضع الترقية وسم stable أو وسم تصحيح، و`preflight_only=false`،
و`preflight_run_id` فارغًا، و`npm_dist_tag=beta`
- يجب أن يستخدم وضع مزامنة `dist-tag` وسم stable أو وسم تصحيح،
و`preflight_only=false`، و`preflight_run_id` فارغًا، و`npm_dist_tag=latest`،
و`promote_beta_to_latest=false`
- تتطلب أوضاع الترقية ومزامنة `dist-tag` أيضًا `NPM_TOKEN` صالحًا لأن
`npm dist-tag add` ما يزال يحتاج إلى مصادقة npm العادية؛ أما النشر الموثوق
فيغطي مسار نشر الحزمة فقط
- يتطلب وضع SHA الخاص بالالتزام في فحوصات الإصدار أيضًا HEAD الحالي لـ `origin/main`
- يجب أن يستخدم مسار النشر الفعلي نفس `npm_dist_tag` المستخدم أثناء الفحص التمهيدي؛
ويتحقق سير العمل من تلك البيانات الوصفية قبل متابعة النشر
## تسلسل إصدار npm المستقر
عند إصدار نسخة npm مستقرة:
1. شغّل `OpenClaw NPM Release` مع `preflight_only=true`
- قبل وجود وسم، يمكنك استخدام SHA الكامل الحالي لالتزام `main` من أجل
تشغيل جاف للتحقق فقط من سير عمل التحقق المسبق
2. اختر `npm_dist_tag=beta` للتدفق العادي الذي يبدأ بـ beta، أو `latest` فقط
- قبل وجود وسم، يمكنك استخدام قيمة SHA الكاملة الحالية لفرع `main`
لإجراء تشغيل تجريبي للتحقق فقط من سير عمل الفحص التمهيدي
2. اختر `npm_dist_tag=beta` للتدفق المعتاد الذي يبدأ عبر beta، أو `latest` فقط
عندما تريد عمدًا نشر إصدار مستقر مباشر
3. شغّل `OpenClaw Release Checks` بشكل منفصل باستخدام الوسم نفسه أو
SHA الكامل الحالي لـ `main` عندما تريد تغطية حية لذاكرة التخزين المؤقت للمطالبات
- هذا فصل مقصود حتى تبقى التغطية الحية متاحة من دون
قيمة SHA الكاملة الحالية لفرع `main` عندما تريد تغطية حية لذاكرة التخزين المؤقت للمطالبات
- هذا الفصل مقصود حتى يبقى التغطية الحية متاحة دون
إعادة ربط الفحوصات الطويلة أو غير المستقرة بسير عمل النشر
4. احفظ `preflight_run_id` الناجح
5. شغّل `OpenClaw NPM Release` مرة أخرى مع `preflight_only=false`، و`tag`
نفسه، و`npm_dist_tag` نفسه، و`preflight_run_id` المحفوظ
6. إذا وصل الإصدار إلى `beta`، فشغّل `OpenClaw NPM Release` لاحقًا باستخدام
وسم stable نفسه، و`promote_beta_to_latest=true`، و`preflight_only=false`،
و`preflight_run_id` فارغًا، و`npm_dist_tag=beta` عندما تريد نقل ذلك
الإصدار المنشور إلى `latest`
7. إذا نُشر الإصدار عمدًا مباشرةً إلى `latest` وكان يجب أن يتبع `beta`
البنية المستقرة نفسها، فشغّل `OpenClaw NPM Release` باستخدام
وسم stable نفسه، و`sync_stable_dist_tags=true`، و`promote_beta_to_latest=false`،
و`preflight_only=false`، و`preflight_run_id` فارغًا، و`npm_dist_tag=latest`
4. احفظ قيمة `preflight_run_id` الناجحة
5. شغّل `OpenClaw NPM Release` مرة أخرى مع `preflight_only=false`، ونفس
`tag`، ونفس `npm_dist_tag`، وقيمة `preflight_run_id` المحفوظة
6. إذا نزل الإصدار إلى `beta`، فاستخدم سير العمل الخاص
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
لترقية ذلك الإصدار المستقر من `beta` إلى `latest`
7. إذا نُشر الإصدار عمدًا مباشرة إلى `latest` وكان ينبغي أن يتبعه `beta`
بالبنية المستقرة نفسها فورًا، فاستخدم سير العمل الخاص نفسه
لتوجيه كلا dist-tags إلى الإصدار المستقر، أو اترك مزامنة الإصلاح الذاتي
المجدولة تنقل `beta` لاحقًا
ما تزال أوضاع الترقية ومزامنة `dist-tag` تتطلب موافقة بيئة `npm-release`
و`NPM_TOKEN` صالحًا يمكن لسير العمل هذا الوصول إليه.
توجد عملية تعديل dist-tag في المستودع الخاص لأسباب أمنية لأنها ما تزال
تتطلب `NPM_TOKEN`، بينما يحتفظ المستودع العام بنشر يعتمد على OIDC فقط.
هذا يُبقي كلاً من مسار النشر المباشر ومسار الترقية الذي يبدأ بـ beta
موثقين ومرئيين للمشغّل.
وهذا يُبقي كلاً من مسار النشر المباشر ومسار الترقية الذي يبدأ عبر beta
موثّقين ومرئيين للمشغّل.
## مراجع عامة
## المراجع العامة
- [`.github/workflows/openclaw-npm-release.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/openclaw-npm-release.yml)
- [`.github/workflows/openclaw-release-checks.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/openclaw-release-checks.yml)
- [`.github/workflows/openclaw-cross-os-release-checks-reusable.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/openclaw-cross-os-release-checks-reusable.yml)
- [`scripts/openclaw-npm-release-check.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/openclaw-npm-release-check.ts)
- [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh)
- [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh)
يستخدم المشرفون مستندات الإصدار الخاصة في
يستخدم المشرفون وثائق الإصدار الخاصة في
[`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md)
كدليل التشغيل الفعلي.
لدليل التشغيل الفعلي.

61
docs/ar/reference/secretref-credential-surface.md
View File

@ -1,29 +1,29 @@
---
read_when:
- التحقق من تغطية بيانات اعتماد SecretRef
- تدقيق ما إذا كانت بيانات اعتماد مؤهلة لـ `secrets configure` أو `secrets apply`
- التحقق من سبب كون بيانات اعتماد خارج السطح المدعوم
summary: السطح القياسي المعتمد وغير المعتمد لبيانات اعتماد SecretRef
title: سطح بيانات اعتماد SecretRef
- التحقق من تغطية اعتمادات SecretRef
- تدقيق ما إذا كان الاعتماد مؤهلًا لـ `secrets configure` أو `secrets apply`
- التحقق من سبب كون الاعتماد خارج السطح المدعوم
summary: السطح المعياري المدعوم وغير المدعوم لاعتمادات SecretRef
title: سطح اعتماد SecretRef
x-i18n:
generated_at: "2026-04-07T07:21:48Z"
generated_at: "2026-04-15T07:18:19Z"
model: gpt-5.4
provider: openai
source_hash: 211f4b504c5808f7790683066fc2c8b700c705c598f220a264daf971b81cc593
source_hash: dd0b9c379236b17a72f552d6360b8b5a2269009e019c138c6bb50f4f7328ddaf
source_path: reference/secretref-credential-surface.md
workflow: 15
---
# سطح بيانات اعتماد SecretRef
# سطح اعتماد SecretRef
تحدد هذه الصفحة السطح القياسي لبيانات اعتماد SecretRef.
تحدد هذه الصفحة السطح المعياري لاعتمادات SecretRef.
الغرض من النطاق:
مقصود النطاق:
- ضمن النطاق: بيانات الاعتماد التي يزوّدها المستخدم مباشرةً والتي لا يقوم OpenClaw بإصدارها أو تدويرها.
- خارج النطاق: بيانات الاعتماد التي تُصدر أثناء التشغيل أو التي تتناوب، ومواد تحديث OAuth، والعناصر الشبيهة بالجلسات.
- ضمن النطاق: الاعتمادات التي يزوّدها المستخدم مباشرةً ولا يقوم OpenClaw بإصدارها أو تدويرها.
- خارج النطاق: الاعتمادات التي تُصدر في وقت التشغيل أو التي يتم تدويرها، ومواد تحديث OAuth، والعناصر الشبيهة بالجلسات.
## بيانات الاعتماد المدعومة
## الاعتمادات المدعومة
### أهداف `openclaw.json` (`secrets configure` + `secrets apply` + `secrets audit`)
@ -49,6 +49,7 @@ x-i18n:
- `messages.tts.providers.*.apiKey`
- `tools.web.fetch.firecrawl.apiKey`
- `plugins.entries.brave.config.webSearch.apiKey`
- `plugins.entries.exa.config.webSearch.apiKey`
- `plugins.entries.google.config.webSearch.apiKey`
- `plugins.entries.xai.config.webSearch.apiKey`
- `plugins.entries.moonshot.config.webSearch.apiKey`
@ -107,33 +108,33 @@ x-i18n:
- `channels.zalo.webhookSecret`
- `channels.zalo.accounts.*.botToken`
- `channels.zalo.accounts.*.webhookSecret`
- `channels.googlechat.serviceAccount` عبر النظير `serviceAccountRef` (استثناء توافق)
- `channels.googlechat.accounts.*.serviceAccount` عبر النظير `serviceAccountRef` (استثناء توافق)
- `channels.googlechat.serviceAccount` عبر `serviceAccountRef` المجاور (استثناء توافق)
- `channels.googlechat.accounts.*.serviceAccount` عبر `serviceAccountRef` المجاور (استثناء توافق)
### أهداف `auth-profiles.json` (`secrets configure` + `secrets apply` + `secrets audit`)
- `profiles.*.keyRef` (`type: "api_key"`؛ غير مدعوم عندما تكون `auth.profiles.<id>.mode = "oauth"`)
- `profiles.*.tokenRef` (`type: "token"`؛ غير مدعوم عندما تكون `auth.profiles.<id>.mode = "oauth"`)
- `profiles.*.keyRef` (`type: "api_key"`؛ غير مدعوم عندما يكون `auth.profiles.<id>.mode = "oauth"`)
- `profiles.*.tokenRef` (`type: "token"`؛ غير مدعوم عندما يكون `auth.profiles.<id>.mode = "oauth"`)
[//]: # "secretref-supported-list-end"
ملاحظات:
- تتطلب أهداف خطة ملف تعريف المصادقة `agentId`.
- تستهدف إدخالات الخطة `profiles.*.key` / `profiles.*.token` وتكتب المراجع النظيرة (`keyRef` / `tokenRef`).
- تُدرج مراجع ملفات تعريف المصادقة في تحليل وقت التشغيل وتغطية التدقيق.
- حاجز سياسة OAuth: لا يمكن دمج `auth.profiles.<id>.mode = "oauth"` مع مدخلات SecretRef لذلك الملف التعريفي. يفشل بدء التشغيل/إعادة التحميل وتحليل ملف تعريف المصادقة بسرعة عند انتهاك هذه السياسة.
- بالنسبة إلى موفري النماذج المُدارين عبر SecretRef، تستمر إدخالات `agents/*/agent/models.json` المُنشأة في حفظ علامات غير سرية (وليس القيم السرية المحلَّلة) لأسطح `apiKey`/الترويسات.
- حفظ العلامات ذو مصدر موثوق: يكتب OpenClaw العلامات من لقطة تهيئة المصدر النشطة (قبل التحليل)، وليس من القيم السرية المحلَّلة وقت التشغيل.
- تتطلب أهداف خطة ملف التعريف الخاص بالمصادقة `agentId`.
- تستهدف إدخالات الخطة `profiles.*.key` / `profiles.*.token` وتكتب المراجع المجاورة (`keyRef` / `tokenRef`).
- يتم تضمين مراجع ملف التعريف الخاص بالمصادقة في دقة وقت التشغيل وتغطية التدقيق.
- حاجز سياسة OAuth: لا يمكن دمج `auth.profiles.<id>.mode = "oauth"` مع مدخلات SecretRef لهذا الملف التعريفي. يفشل بدء التشغيل/إعادة التحميل ودقة ملف التعريف الخاص بالمصادقة بسرعة عند انتهاك هذه السياسة.
- بالنسبة إلى موفري النماذج المُدارين بواسطة SecretRef، تحتفظ الإدخالات المُولَّدة في `agents/*/agent/models.json` بمؤشرات غير سرية (وليس القيم السرية التي تم حلها) لأسطح `apiKey`/الرؤوس.
- استمرار المؤشرات يعتمد على المصدر بشكل موثوق: يكتب OpenClaw المؤشرات من لقطة إعدادات المصدر النشطة (قبل الحل)، وليس من قيم الأسرار المحلولة في وقت التشغيل.
- بالنسبة إلى البحث على الويب:
- في وضع الموفّر الصريح (مع تعيين `tools.web.search.provider`)، يكون مفتاح الموفّر المحدد فقط نشطًا.
- في الوضع التلقائي (عندما لا يكون `tools.web.search.provider` معيّنًا)، يكون مفتاح الموفّر الأول فقط الذي يُحل وفق الأسبقية نشطًا.
- في وضع الموفّر الصريح (عند تعيين `tools.web.search.provider`) يكون مفتاح الموفّر المحدد فقط نشطًا.
- في الوضع التلقائي (عند عدم تعيين `tools.web.search.provider`) يكون مفتاح الموفّر الأول الذي يتم حله حسب الأسبقية فقط هو النشط.
- في الوضع التلقائي، تُعامل مراجع الموفّرين غير المحددين على أنها غير نشطة حتى يتم تحديدها.
- ما تزال مسارات الموفّر القديمة `tools.web.search.*` تُحل خلال نافذة التوافق، لكن السطح القياسي لـ SecretRef هو `plugins.entries.<plugin>.config.webSearch.*`.
- لا تزال مسارات الموفّر القديمة `tools.web.search.*` تُحل خلال نافذة التوافق، لكن سطح SecretRef المعياري هو `plugins.entries.<plugin>.config.webSearch.*`.
## بيانات الاعتماد غير المدعومة
## الاعتمادات غير المدعومة
تشمل بيانات الاعتماد الخارجة عن النطاق ما يلي:
تشمل الاعتمادات خارج النطاق ما يلي:
[//]: # "secretref-unsupported-list-start"
@ -149,6 +150,6 @@ x-i18n:
[//]: # "secretref-unsupported-list-end"
المبررات:
المبرر:
- تُصدر هذه البيانات الاعتمادية، أو تُدوَّر، أو تحمل جلسات، أو تنتمي إلى فئات OAuth دائمة لا تتوافق مع تحليل SecretRef الخارجي للقراءة فقط.
- هذه الاعتمادات مُصدَرة، أو مُدوَّرة، أو مرتبطة بالجلسات، أو من فئات OAuth دائمة لا تتوافق مع حل SecretRef الخارجي للقراءة فقط.

373
docs/ar/start/showcase.md
View File

@ -1,133 +1,160 @@
---
description: Real-world OpenClaw projects from the community
read_when:
- تبحث عن أمثلة حقيقية لاستخدام OpenClaw
- تقوم بتحديث أبرز مشروعات المجتمع
summary: مشروعات وتكاملات من بناء المجتمع تعمل بواسطة OpenClaw
title: واجهة العرض
- أبحث عن أمثلة حقيقية على استخدام OpenClaw
- تحديث أبرز مشاريع المجتمع
summary: مشاريع وتكاملات أنشأها المجتمع ومدعومة بواسطة OpenClaw
title: العرض
x-i18n:
generated_at: "2026-04-05T12:57:37Z"
generated_at: "2026-04-15T07:18:25Z"
model: gpt-5.4
provider: openai
source_hash: 2917e9a476ef527ddb3e51c610bbafbd145e705c9cc29f191639fb63d238ef70
source_hash: 797d0b85c9eca920240c79d870eb9636216714f3eba871c5ebd0f7f40cf7bbf1
source_path: start/showcase.md
workflow: 15
---
# واجهة العرض
<!-- markdownlint-disable MD033 -->
مشروعات حقيقية من المجتمع. تعرّف على ما يبنيه الناس باستخدام OpenClaw.
# العرض
<div className="showcase-hero">
<p className="showcase-kicker">مبني داخل الدردشات، والمحطات الطرفية، والمتصفحات، وغرف المعيشة</p>
<p className="showcase-lead">
مشاريع OpenClaw ليست عروضًا تجريبية بسيطة. الناس يطلقون حلقات مراجعة PR، وتطبيقات جوال، وأتمتة منزلية،
وأنظمة صوتية، وأدوات تطوير، وسير عمل كثيف الذاكرة من القنوات التي يستخدمونها بالفعل.
</p>
<div className="showcase-actions">
<a href="#videos">شاهد العروض التوضيحية</a>
<a href="#fresh-from-discord">تصفح المشاريع</a>
<a href="https://discord.gg/clawd">شارك مشروعك</a>
</div>
<div className="showcase-highlights">
<div className="showcase-highlight">
<strong>بناءات أصلية للدردشة</strong>
<span>Telegram وWhatsApp وDiscord وBeeper ودردشة الويب وسير العمل المعتمد على الطرفية أولًا.</span>
</div>
<div className="showcase-highlight">
<strong>أتمتة حقيقية</strong>
<span>الحجز، والتسوق، والدعم، وإعداد التقارير، والتحكم في المتصفح دون انتظار واجهة API.</span>
</div>
<div className="showcase-highlight">
<strong>العالم المحلي والمادي</strong>
<span>الطابعات، والمكانس، والكاميرات، والبيانات الصحية، والأنظمة المنزلية، وقواعد المعرفة الشخصية.</span>
</div>
</div>
</div>
<Info>
**هل تريد أن يظهر مشروعك هنا؟** شارك مشروعك في [#self-promotion on Discord](https://discord.gg/clawd) أو [ضع إشارة @openclaw على X](https://x.com/openclaw).
**هل تريد أن يظهر مشروعك هنا؟** شارك مشروعك في [#self-promotion on Discord](https://discord.gg/clawd) أو [ضع إشارة إلى @openclaw على X](https://x.com/openclaw).
</Info>
## 🎥 OpenClaw أثناء العمل
شرح كامل للإعداد (28 دقيقة) من VelvetShark.
<div
style={{
position: "relative",
paddingBottom: "56.25%",
height: 0,
overflow: "hidden",
borderRadius: 16,
}}
>
<iframe
src="https://www.youtube-nocookie.com/embed/SaWSPZoPX34"
title="OpenClaw: The self-hosted AI that Siri should have been (Full setup)"
style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%" }}
frameBorder="0"
loading="lazy"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
allowFullScreen
/>
<div className="showcase-jump-links">
<a href="#videos">الفيديوهات</a>
<a href="#fresh-from-discord">أحدث ما جاء من Discord</a>
<a href="#automation-workflows">الأتمتة</a>
<a href="#knowledge-memory">الذاكرة</a>
<a href="#voice-phone">الصوت والهاتف</a>
<a href="#infrastructure-deployment">البنية التحتية والنشر</a>
<a href="#home-hardware">المنزل والأجهزة</a>
<a href="#community-projects">المجتمع</a>
<a href="#submit-your-project">أرسل مشروعًا</a>
</div>
[شاهد على YouTube](https://www.youtube.com/watch?v=SaWSPZoPX34)
<h2 id="videos">الفيديوهات</h2>
<div
style={{
position: "relative",
paddingBottom: "56.25%",
height: 0,
overflow: "hidden",
borderRadius: 16,
}}
>
<iframe
src="https://www.youtube-nocookie.com/embed/mMSKQvlmFuQ"
title="OpenClaw showcase video"
style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%" }}
frameBorder="0"
loading="lazy"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
allowFullScreen
/>
<p className="showcase-section-intro">
ابدأ من هنا إذا أردت أقصر طريق من «ما هذا؟» إلى «حسنًا، فهمت».
</p>
<div className="showcase-video-grid">
<div className="showcase-video-card">
<div className="showcase-video-shell">
<iframe
src="https://www.youtube-nocookie.com/embed/SaWSPZoPX34"
title="OpenClaw: الذكاء الاصطناعي المستضاف ذاتيًا الذي كان ينبغي أن تكون عليه Siri (إعداد كامل)"
loading="lazy"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
allowFullScreen
/>
</div>
<h3>شرح كامل للإعداد</h3>
<p>VelvetShark، 28 دقيقة. ثبّت، وأكمل الإعداد الأولي، ووصل إلى أول مساعد يعمل من البداية إلى النهاية.</p>
<a href="https://www.youtube.com/watch?v=SaWSPZoPX34">شاهد على YouTube</a>
</div>
<div className="showcase-video-card">
<div className="showcase-video-shell">
<iframe
src="https://www.youtube-nocookie.com/embed/mMSKQvlmFuQ"
title="فيديو عرض OpenClaw"
loading="lazy"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
allowFullScreen
/>
</div>
<h3>شريط عرض من المجتمع</h3>
<p>مرور أسرع على مشاريع حقيقية وواجهات وسير عمل مبنية حول OpenClaw.</p>
<a href="https://www.youtube.com/watch?v=mMSKQvlmFuQ">شاهد على YouTube</a>
</div>
<div className="showcase-video-card">
<div className="showcase-video-shell">
<iframe
src="https://www.youtube-nocookie.com/embed/5kkIJNUGFho"
title="عرض مجتمع OpenClaw"
loading="lazy"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
allowFullScreen
/>
</div>
<h3>مشاريع في العالم الحقيقي</h3>
<p>أمثلة من المجتمع، من حلقات البرمجة الأصلية للدردشة إلى الأجهزة والأتمتة الشخصية.</p>
<a href="https://www.youtube.com/watch?v=5kkIJNUGFho">شاهد على YouTube</a>
</div>
</div>
[شاهد على YouTube](https://www.youtube.com/watch?v=mMSKQvlmFuQ)
<h2 id="fresh-from-discord">أحدث ما جاء من Discord</h2>
<div
style={{
position: "relative",
paddingBottom: "56.25%",
height: 0,
overflow: "hidden",
borderRadius: 16,
}}
>
<iframe
src="https://www.youtube-nocookie.com/embed/5kkIJNUGFho"
title="OpenClaw community showcase"
style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%" }}
frameBorder="0"
loading="lazy"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
allowFullScreen
/>
</div>
[شاهد على YouTube](https://www.youtube.com/watch?v=5kkIJNUGFho)
## 🆕 جديد من Discord
<p className="showcase-section-intro">
أبرز الأمثلة الحديثة عبر البرمجة، وأدوات التطوير، والجوال، وبناء المنتجات الأصلية للدردشة.
</p>
<CardGroup cols={2}>
<Card title="مراجعة PR ← ملاحظات Telegram" icon="code-pull-request" href="https://x.com/i/status/2010878524543131691">
<Card title="مراجعة PR → ملاحظات Telegram" icon="code-pull-request" href="https://x.com/i/status/2010878524543131691">
**@bangnokia** • `review` `github` `telegram`
يكمل OpenCode التغيير ← يفتح PR ← يراجع OpenClaw الفرق ويرد في Telegram بملاحظات "طفيفة" مع قرار دمج واضح (بما في ذلك الإصلاحات الحرجة التي يجب تطبيقها أولًا).
ينهي OpenCode التغيير → يفتح PR → يراجع OpenClaw الفرق ويرد في Telegram مع «اقتراحات بسيطة» بالإضافة إلى حكم واضح بشأن الدمج (بما في ذلك الإصلاحات الحرجة التي يجب تطبيقها أولًا).
<img src="/assets/showcase/pr-review-telegram.jpg" alt="ملاحظات مراجعة PR من OpenClaw مُرسلة في Telegram" />
<img src="/assets/showcase/pr-review-telegram.jpg" alt="ملاحظات مراجعة PR من OpenClaw مُرسلة عبر Telegram" />
</Card>
<Card title="مهارة قبو النبيذ في دقائق" icon="wine-glass" href="https://x.com/i/status/2010916352454791216">
<Card title="Skill لقبو نبيذ خلال دقائق" icon="wine-glass" href="https://x.com/i/status/2010916352454791216">
**@prades_maxime** • `skills` `local` `csv`
طلب من “Robby” (@openclaw) مهارة محلية لإدارة قبو نبيذ. تطلب تصدير CSV نموذجيًا + مكان تخزينه، ثم تبني المهارة وتختبرها بسرعة (962 زجاجة في المثال).
طُلِب من “Robby” (@openclaw) إنشاء Skill محلي لقبو نبيذ. يطلب نموذج CSV مُصدَّرًا ومكان تخزينه، ثم يبني/يختبر Skill بسرعة (962 زجاجة في المثال).
<img src="/assets/showcase/wine-cellar-skill.jpg" alt="OpenClaw يبني مهارة محلية لقبو نبيذ من CSV" />
<img src="/assets/showcase/wine-cellar-skill.jpg" alt="OpenClaw يبني Skill محليًا لقبو نبيذ من CSV" />
</Card>
<Card title="القيادة الذاتية لتسوق Tesco" icon="cart-shopping" href="https://x.com/i/status/2009724862470689131">
<Card title="القيادة الآلية لتسوق Tesco" icon="cart-shopping" href="https://x.com/i/status/2009724862470689131">
**@marchattonhere** • `automation` `browser` `shopping`
خطة وجبات أسبوعية ← العناصر المعتادة ← حجز موعد التوصيل ← تأكيد الطلب. بلا API، فقط تحكم بالمتصفح.
خطة وجبات أسبوعية → المعتادون → حجز موعد التوصيل → تأكيد الطلب. بلا واجهات API، فقط تحكم في المتصفح.
<img src="/assets/showcase/tesco-shop.jpg" alt="أتمتة تسوق Tesco عبر الدردشة" />
<img src="/assets/showcase/tesco-shop.jpg" alt="أتمتة التسوق من Tesco عبر الدردشة" />
</Card>
<Card title="SNAG من لقطة شاشة إلى Markdown" icon="scissors" href="https://github.com/am-will/snag">
**@am-will** • `devtools` `screenshots` `markdown`
اختصار لوحة مفاتيح لتحديد منطقة من الشاشة ← Gemini vision ← Markdown فوري في الحافظة.
اختصار سريع لمنطقة من الشاشة → Gemini vision → Markdown فوري في الحافظة.
<img src="/assets/showcase/snag.png" alt="أداة SNAG من لقطة شاشة إلى Markdown" />
<img src="/assets/showcase/snag.png" alt="أداة SNAG للتحويل من لقطة شاشة إلى Markdown" />
</Card>
<Card title="Agents UI" icon="window-maximize" href="https://releaseflow.net/kitze/agents-ui">
<Card title="واجهة Agents UI" icon="window-maximize" href="https://releaseflow.net/kitze/agents-ui">
**@kitze** • `ui` `skills` `sync`
تطبيق سطح مكتب لإدارة Skills/الأوامر عبر Agents وClaude وCodex وOpenClaw.
@ -135,18 +162,18 @@ x-i18n:
<img src="/assets/showcase/agents-ui.jpg" alt="تطبيق Agents UI" />
</Card>
<Card title="ملاحظات صوتية على Telegram ‏(papla.media)" icon="microphone" href="https://papla.media/docs">
**Community** • `voice` `tts` `telegram`
<Card title="ملاحظات صوتية على Telegram (papla.media)" icon="microphone" href="https://papla.media/docs">
**المجتمع** • `voice` `tts` `telegram`
يلف TTS من papla.media ويرسل النتائج كملاحظات صوتية على Telegram (من دون تشغيل تلقائي مزعج).
يغلف papla.media TTS ويرسل النتائج كملاحظات صوتية على Telegram (من دون تشغيل تلقائي مزعج).
<img src="/assets/showcase/papla-tts.jpg" alt="إخراج ملاحظة صوتية على Telegram من TTS" />
<img src="/assets/showcase/papla-tts.jpg" alt="مخرجات ملاحظة صوتية على Telegram من TTS" />
</Card>
<Card title="CodexMonitor" icon="eye" href="https://clawhub.ai/odrobnik/codexmonitor">
**@odrobnik** • `devtools` `codex` `brew`
أداة مساعدة تُثبّت عبر Homebrew لسرد جلسات OpenAI Codex المحلية وفحصها ومراقبتها (CLI + VS Code).
أداة مساعدة تُثبَّت عبر Homebrew لعرض/فحص/مراقبة جلسات OpenAI Codex المحلية (CLI + VS Code).
<img src="/assets/showcase/codexmonitor.png" alt="CodexMonitor على ClawHub" />
</Card>
@ -154,225 +181,245 @@ x-i18n:
<Card title="التحكم في طابعة Bambu ثلاثية الأبعاد" icon="print" href="https://clawhub.ai/tobiasbischoff/bambu-cli">
**@tobiasbischoff** • `hardware` `3d-printing` `skill`
تحكم في طابعات BambuLab واستكشف أخطاءها: الحالة، والمهام، والكاميرا، وAMS، والمعايرة، وغير ذلك.
التحكم في طابعات BambuLab واستكشاف مشكلاتها: الحالة، والمهام، والكاميرا، وAMS، والمعايرة، وغير ذلك.
<img src="/assets/showcase/bambu-cli.png" alt="مهارة Bambu CLI على ClawHub" />
<img src="/assets/showcase/bambu-cli.png" alt="Skill Bambu CLI على ClawHub" />
</Card>
<Card title="مواصلات فيينا (Wiener Linien)" icon="train" href="https://clawhub.ai/hjanuschka/wienerlinien">
**@hjanuschka** • `travel` `transport` `skill`
مغادرات آنية، واضطرابات، وحالة المصاعد، وتوجيه لوسائل النقل العام في فيينا.
مواعيد المغادرة في الوقت الحقيقي، والاضطرابات، وحالة المصاعد، والتوجيه لمواصلات فيينا العامة.
<img src="/assets/showcase/wienerlinien.png" alt="مهارة Wiener Linien" />
<img src="/assets/showcase/wienerlinien.png" alt="Skill Wiener Linien على ClawHub" />
</Card>
<Card title="وجبات المدرسة عبر ParentPay" icon="utensils" href="#">
<Card title="وجبات المدرسة عبر ParentPay" icon="utensils">
**@George5562** • `automation` `browser` `parenting`
أتمتة حجز الوجبات المدرسية في المملكة المتحدة عبر ParentPay. تستخدم إحداثيات الفأرة للنقر الموثوق على خلايا الجدول.
أتمتة حجز وجبات المدارس في المملكة المتحدة عبر ParentPay. يستخدم إحداثيات الفأرة للنقر الموثوق على خلايا الجدول.
</Card>
<Card title="رفع إلى R2 ‏(أرسل لي ملفاتي)" icon="cloud-arrow-up" href="https://clawhub.ai/skills/r2-upload">
<Card title="رفع R2 (أرسل لي ملفاتي)" icon="cloud-arrow-up" href="https://clawhub.ai/skills/r2-upload">
**@julianengel** • `files` `r2` `presigned-urls`
الرفع إلى Cloudflare R2/S3 وإنشاء روابط تنزيل مؤقتة وآمنة. مثالي لنسخ OpenClaw البعيدة.
رفع الملفات إلى Cloudflare R2/S3 وإنشاء روابط تنزيل آمنة موقعة مسبقًا. مثالي لنسخ OpenClaw البعيدة.
</Card>
<Card title="تطبيق iOS عبر Telegram" icon="mobile" href="#">
<Card title="تطبيق iOS عبر Telegram" icon="mobile">
**@coard** • `ios` `xcode` `testflight`
بنى تطبيق iOS كاملًا مع الخرائط وتسجيل الصوت، ونشره إلى TestFlight بالكامل عبر دردشة Telegram.
بنى تطبيق iOS كاملًا يتضمن الخرائط وتسجيل الصوت، ثم نشره إلى TestFlight بالكامل عبر دردشة Telegram.
<img src="/assets/showcase/ios-testflight.jpg" alt="تطبيق iOS على TestFlight" />
</Card>
<Card title="مساعد الصحة Oura Ring" icon="heart-pulse" href="#">
<Card title="مساعد صحي لخاتم Oura" icon="heart-pulse">
**@AS** • `health` `oura` `calendar`
مساعد صحة شخصي بالذكاء الاصطناعي يدمج بيانات Oura ring مع التقويم والمواعيد وجدول النادي الرياضي.
مساعد صحي شخصي بالذكاء الاصطناعي يدمج بيانات خاتم Oura مع التقويم، والمواعيد، وجدول النادي الرياضي.
<img src="/assets/showcase/oura-health.png" alt="مساعد الصحة Oura ring" />
<img src="/assets/showcase/oura-health.png" alt="مساعد صحي لخاتم Oura" />
</Card>
<Card title="فريق Kev الحلمي (أكثر من 14 وكيلًا)" icon="robot" href="https://github.com/adam91holt/orchestrated-ai-articles">
<Card title="فريق أحلام Kev (14+ وكيلًا)" icon="robot" href="https://github.com/adam91holt/orchestrated-ai-articles">
**@adam91holt** • `multi-agent` `orchestration` `architecture` `manifesto`
أكثر من 14 وكيلًا تحت Gateway واحد مع منسق Opus 4.5 يوزع العمل على عمال Codex. [عرض تقني مفصل](https://github.com/adam91holt/orchestrated-ai-articles) يغطي قائمة فريق الأحلام، واختيار النماذج، والعزل، وwebhooks، ونبضات الحياة، وتدفقات التفويض. [Clawdspace](https://github.com/adam91holt/clawdspace) لعزل الوكلاء. [مقالة مدونة](https://adams-ai-journey.ghost.io/2026-the-year-of-the-orchestrator/).
أكثر من 14 وكيلًا تحت Gateway واحد مع منسّق Opus 4.5 يفوّض المهام إلى عمّال Codex. [عرض تقني مفصل](https://github.com/adam91holt/orchestrated-ai-articles) يغطي قائمة Dream Team، واختيار النماذج، وsandboxing، وwebhooks، وHeartbeats، وتدفّقات التفويض. [Clawdspace](https://github.com/adam91holt/clawdspace) من أجل sandboxing للوكلاء. [تدوينة](https://adams-ai-journey.ghost.io/2026-the-year-of-the-orchestrator/).
</Card>
<Card title="Linear CLI" icon="terminal" href="https://github.com/Finesssee/linear-cli">
**@NessZerra** • `devtools` `linear` `cli` `issues`
CLI لـ Linear يتكامل مع تدفقات العمل المعتمدة على الوكلاء (Claude Code وOpenClaw). أدر القضايا والمشروعات وتدفقات العمل من الطرفية. تم دمج أول PR خارجي!
واجهة CLI لـ Linear تتكامل مع سير العمل الوكيلي (Claude Code وOpenClaw). أدِر القضايا، والمشاريع، وسير العمل من الطرفية. تم دمج أول PR خارجي!
</Card>
<Card title="Beeper CLI" icon="message" href="https://github.com/blqke/beepcli">
**@jules** • `messaging` `beeper` `cli` `automation`
اقرأ الرسائل وأرسلها وأرشفها عبر Beeper Desktop. يستخدم Beeper local MCP API حتى تتمكن الوكلاء من إدارة كل محادثاتك (iMessage وWhatsApp وغير ذلك) في مكان واحد.
اقرأ الرسائل وأرسلها وأرشفها عبر Beeper Desktop. يستخدم Beeper local MCP API حتى تتمكن الوكلاء من إدارة جميع دردشاتك (iMessage وWhatsApp وما إلى ذلك) من مكان واحد.
</Card>
</CardGroup>
## 🤖 الأتمتة وتدفقات العمل
<h2 id="automation-workflows">الأتمتة وسير العمل</h2>
<p className="showcase-section-intro">
الجدولة، والتحكم في المتصفح، وحلقات الدعم، وجانب «نفّذ المهمة بدلًا عني» من المنتج.
</p>
<CardGroup cols={2}>
<Card title="التحكم في منقّي هواء Winix" icon="wind" href="https://x.com/antonplex/status/2010518442471006253">
<Card title="التحكم في جهاز تنقية الهواء Winix" icon="wind" href="https://x.com/antonplex/status/2010518442471006253">
**@antonplex** • `automation` `hardware` `air-quality`
اكتشف Claude Code عناصر تحكم المنقّي وأكدها، ثم يتولى OpenClaw الإدارة للحفاظ على جودة هواء الغرفة.
اكتشف Claude Code عناصر التحكم في جهاز التنقية وأكدها، ثم يتولى OpenClaw إدارة جودة هواء الغرفة.
<img src="/assets/showcase/winix-air-purifier.jpg" alt="التحكم في منقّي هواء Winix عبر OpenClaw" />
<img src="/assets/showcase/winix-air-purifier.jpg" alt="التحكم في جهاز تنقية الهواء Winix عبر OpenClaw" />
</Card>
<Card title="لقطات كاميرا لسماء جميلة" icon="camera" href="https://x.com/signalgaining/status/2010523120604746151">
<Card title="لقطات جميلة للسماء من الكاميرا" icon="camera" href="https://x.com/signalgaining/status/2010523120604746151">
**@signalgaining** • `automation` `camera` `skill` `images`
يُفعَّل عبر كاميرا على السطح: اطلب من OpenClaw التقاط صورة للسماء كلما بدت جميلة — لقد صمّم مهارة والتقط الصورة.
يُفعَّل بواسطة كاميرا على السطح: اطلب من OpenClaw التقاط صورة للسماء كلما بدا المنظر جميلًا — فقد صمم Skill والتقط الصورة.
<img src="/assets/showcase/roof-camera-sky.jpg" alt="لقطة للسماء من كاميرا السطح التقطها OpenClaw" />
</Card>
<Card title="مشهد إحاطة صباحية مرئي" icon="robot" href="https://x.com/buddyhadry/status/2010005331925954739">
<Card title="مشهد الإحاطة الصباحية المرئي" icon="robot" href="https://x.com/buddyhadry/status/2010005331925954739">
**@buddyhadry** • `automation` `briefing` `images` `telegram`
تنتج مطالبة مجدولة صورة "مشهد" واحدة كل صباح (الطقس، المهام، التاريخ، المنشور/الاقتباس المفضل) عبر شخصية OpenClaw.
ينشئ موجّه مجدول صورة «مشهد» واحدة كل صباح (الطقس، والمهام، والتاريخ، والمنشور/الاقتباس المفضل) عبر persona من OpenClaw.
</Card>
<Card title="حجز ملعب Padel" icon="calendar-check" href="https://github.com/joshp123/padel-cli">
**@joshp123** • `automation` `booking` `cli`
أداة CLI للتحقق من التوفر والحجز في Playtomic. لا تفوّت ملعبًا متاحًا مرة أخرى.
أداة CLI للتحقق من التوفر والحجز في Playtomic. لا تفوّت ملعبًا شاغرًا مرة أخرى.
<img src="/assets/showcase/padel-screenshot.jpg" alt="لقطة شاشة لـ padel-cli" />
</Card>
<Card title="استقبال المحاسبة" icon="file-invoice-dollar">
**Community** • `automation` `email` `pdf`
<Card title="إدخال المستندات المحاسبية" icon="file-invoice-dollar">
**المجتمع** • `automation` `email` `pdf`
يجمع ملفات PDF من البريد الإلكتروني ويجهز المستندات للمستشار الضريبي. محاسبة شهرية تعمل تلقائيًا.
يجمع ملفات PDF من البريد الإلكتروني ويجهز المستندات للمستشار الضريبي. المحاسبة الشهرية على الطيار الآلي.
</Card>
<Card title="وضع المطور من Couch Potato" icon="couch" href="https://davekiss.com">
<Card title="وضع المطور من الأريكة" icon="couch" href="https://davekiss.com">
**@davekiss** • `telegram` `website` `migration` `astro`
أعاد بناء موقعه الشخصي بالكامل عبر Telegram أثناء مشاهدة Netflix — نقل من Notion إلى Astro، وترحيل 18 منشورًا، وDNS إلى Cloudflare. لم يفتح حاسوبًا محمولًا مطلقًا.
أعاد بناء موقعه الشخصي بالكامل عبر Telegram بينما كان يشاهد Netflix — من Notion إلى Astro، مع ترحيل 18 منشورًا، ونقل DNS إلى Cloudflare. لم يفتح حاسوبًا محمولًا مطلقًا.
</Card>
<Card title="وكيل البحث عن وظائف" icon="briefcase">
<Card title="وكيل البحث عن وظيفة" icon="briefcase">
**@attol8** • `automation` `api` `skill`
يبحث في قوائم الوظائف، ويطابقها مع كلمات مفتاحية من السيرة الذاتية، ويعيد الفرص ذات الصلة مع الروابط. بُني في 30 دقيقة باستخدام JSearch API.
يبحث في إعلانات الوظائف، ويطابقها مع كلمات مفتاحية من السيرة الذاتية، ويعيد الفرص المناسبة مع الروابط. بُني خلال 30 دقيقة باستخدام JSearch API.
</Card>
<Card title="منشئ مهارات Jira" icon="diagram-project" href="https://x.com/jdrhyne/status/2008336434827002232">
<Card title="منشئ Skill لـ Jira" icon="diagram-project" href="https://x.com/jdrhyne/status/2008336434827002232">
**@jdrhyne** • `automation` `jira` `skill` `devtools`
اتصل OpenClaw بـ Jira، ثم أنشأ مهارة جديدة مباشرة أثناء العمل (قبل أن توجد على ClawHub).
اتصل OpenClaw بـ Jira، ثم أنشأ Skill جديدًا أثناء التشغيل مباشرة (قبل أن يكون موجودًا على ClawHub).
</Card>
<Card title="مهارة Todoist عبر Telegram" icon="list-check" href="https://x.com/iamsubhrajyoti/status/2009949389884920153">
<Card title="Skill لـ Todoist عبر Telegram" icon="list-check" href="https://x.com/iamsubhrajyoti/status/2009949389884920153">
**@iamsubhrajyoti** • `automation` `todoist` `skill` `telegram`
أتمت مهام Todoist وجعلت OpenClaw ينشئ المهارة مباشرة داخل دردشة Telegram.
قام بأتمتة مهام Todoist وجعل OpenClaw ينشئ Skill مباشرة داخل دردشة Telegram.
</Card>
<Card title="تحليل TradingView" icon="chart-line">
**@bheem1798** • `finance` `browser` `automation`
يسجل الدخول إلى TradingView عبر أتمتة المتصفح، ويلتقط لقطات للشاشات، ويجري تحليلًا فنيًا عند الطلب. لا حاجة إلى API—فقط تحكم بالمتصفح.
يسجل الدخول إلى TradingView عبر أتمتة المتصفح، ويلتقط صورًا للشاشات للرسوم البيانية، ويُجري تحليلًا فنيًا عند الطلب. لا حاجة إلى واجهة API — فقط تحكم في المتصفح.
</Card>
<Card title="دعم تلقائي على Slack" icon="slack">
**@henrymascot** • `slack` `automation` `support`
يراقب قناة الشركة على Slack، ويرد بشكل مفيد، ويحوّل الإشعارات إلى Telegram. أصلح تلقائيًا خطأ إنتاج في تطبيق منشور من دون أن يُطلب منه ذلك.
يراقب قناة الشركة على Slack، ويرد بشكل مفيد، ويرسل الإشعارات إلى Telegram. أصلح تلقائيًا خطأً في الإنتاج داخل تطبيق منشور من دون أن يُطلب منه ذلك.
</Card>
</CardGroup>
## 🧠 المعرفة والذاكرة
<h2 id="knowledge-memory">المعرفة والذاكرة</h2>
<p className="showcase-section-intro">
أنظمة تقوم بالفهرسة، والبحث، والتذكر، والاستدلال على المعرفة الشخصية أو معرفة الفريق.
</p>
<CardGroup cols={2}>
<Card title="تعلم الصينية xuezh" icon="language" href="https://github.com/joshp123/xuezh">
**@joshp123** • `learning` `voice` `skill`
محرك لتعلم الصينية مع ملاحظات على النطق وتدفقات دراسة عبر OpenClaw.
محرك لتعلم اللغة الصينية مع ملاحظات على النطق وتدفقات دراسية عبر OpenClaw.
<img src="/assets/showcase/xuezh-pronunciation.jpeg" alt="ملاحظات نطق xuezh" />
<img src="/assets/showcase/xuezh-pronunciation.jpeg" alt="ملاحظات xuezh على النطق" />
</Card>
<Card title="خزنة ذاكرة WhatsApp" icon="vault">
**Community** • `memory` `transcription` `indexing`
**المجتمع** • `memory` `transcription` `indexing`
يستوعب صادرات WhatsApp كاملة، ويفرغ أكثر من 1k من الملاحظات الصوتية، ويقارنها بسجلات git، ويخرج تقارير Markdown مترابطة.
يستوعب صادرات WhatsApp الكاملة، ويفرغ أكثر من 1k من الملاحظات الصوتية، ويجري مطابقة متقاطعة مع سجلات git، ويُخرج تقارير Markdown مترابطة.
</Card>
<Card title="بحث Karakeep الدلالي" icon="magnifying-glass" href="https://github.com/jamesbrooksco/karakeep-semantic-search">
<Card title="بحث دلالي في Karakeep" icon="magnifying-glass" href="https://github.com/jamesbrooksco/karakeep-semantic-search">
**@jamesbrooksco** • `search` `vector` `bookmarks`
يضيف بحثًا متجهيًا إلى إشارات Karakeep المرجعية باستخدام Qdrant وتضمينات OpenAI/Ollama.
يضيف بحثًا متجهيًا إلى إشارات Karakeep المرجعية باستخدام Qdrant + OpenAI/Ollama embeddings.
</Card>
<Card title="ذاكرة Inside-Out-2" icon="brain">
**Community** • `memory` `beliefs` `self-model`
**المجتمع** • `memory` `beliefs` `self-model`
مدير ذاكرة منفصل يحوّل ملفات الجلسات إلى ذكريات ← معتقدات ← نموذج ذاتي متطور.
مدير ذاكرة منفصل يحول ملفات الجلسات إلى ذكريات ← معتقدات ← نموذج ذاتي متطور.
</Card>
</CardGroup>
## 🎙️ الصوت والهاتف
<h2 id="voice-phone">الصوت والهاتف</h2>
<p className="showcase-section-intro">
نقاط دخول تعتمد على الكلام أولًا، وجسور الهاتف، وسير العمل الكثيف بالتفريغ الصوتي.
</p>
<CardGroup cols={2}>
<Card title="جسر الهاتف Clawdia" icon="phone" href="https://github.com/alejandroOPI/clawdia-bridge">
**@alejandroOPI** • `voice` `vapi` `bridge`
جسر HTTP بين مساعد Vapi الصوتي وOpenClaw. مكالمات هاتفية شبه آنية مع وكيلك.
جسر HTTP بين مساعد Vapi الصوتي وOpenClaw. مكالمات هاتفية شبه فورية مع وكيلك.
</Card>
<Card title="تفريغ OpenRouter الصوتي" icon="microphone" href="https://clawhub.ai/obviyus/openrouter-transcribe">
<Card title="التفريغ الصوتي عبر OpenRouter" icon="microphone" href="https://clawhub.ai/obviyus/openrouter-transcribe">
**@obviyus** • `transcription` `multilingual` `skill`
تفريغ صوتي متعدد اللغات عبر OpenRouter ‏(Gemini وغيرها). متاح على ClawHub.
تفريغ صوتي متعدد اللغات عبر OpenRouter (Gemini وغيرها). متاح على ClawHub.
</Card>
</CardGroup>
## 🏗️ البنية التحتية والنشر
<h2 id="infrastructure-deployment">البنية التحتية والنشر</h2>
<p className="showcase-section-intro">
التغليف، والنشر، والتكاملات التي تجعل OpenClaw أسهل تشغيلًا وتوسعة.
</p>
<CardGroup cols={2}>
<Card title="إضافة Home Assistant" icon="home" href="https://github.com/ngutman/openclaw-ha-addon">
**@ngutman** • `homeassistant` `docker` `raspberry-pi`
تشغيل OpenClaw gateway على Home Assistant OS مع دعم نفق SSH وحالة دائمة.
يعمل OpenClaw Gateway على Home Assistant OS مع دعم نفق SSH وحالة دائمة.
</Card>
<Card title="مهارة Home Assistant" icon="toggle-on" href="https://clawhub.ai/skills/homeassistant">
<Card title="Skill لـ Home Assistant" icon="toggle-on" href="https://clawhub.ai/skills/homeassistant">
**ClawHub** • `homeassistant` `skill` `automation`
تحكم في أجهزة Home Assistant وأتمتها باستخدام اللغة الطبيعية.
</Card>
<Card title="حزم Nix" icon="snowflake" href="https://github.com/openclaw/nix-openclaw">
<Card title="تغليف Nix" icon="snowflake" href="https://github.com/openclaw/nix-openclaw">
**@openclaw** • `nix` `packaging` `deployment`
إعداد OpenClaw معبأ بـ nix وجاهز للاستخدام من أجل عمليات نشر قابلة لإعادة الإنتاج.
إعداد OpenClaw مُحوّل إلى nix مع كل ما يلزم من أجل عمليات نشر قابلة لإعادة الإنتاج.
</Card>
<Card title="تقويم CalDAV" icon="calendar" href="https://clawhub.ai/skills/caldav-calendar">
**ClawHub** • `calendar` `caldav` `skill`
مهارة تقويم تستخدم khal/vdirsyncer. تكامل تقويم مستضاف ذاتيًا.
Skill للتقويم باستخدام khal/vdirsyncer. تكامل تقويم مستضاف ذاتيًا.
</Card>
</CardGroup>
## 🏠 المنزل والأجهزة
<h2 id="home-hardware">المنزل والأجهزة</h2>
<p className="showcase-section-intro">
الجانب المادي من OpenClaw: المنازل، والمستشعرات، والكاميرات، والمكانس، وغيرها من الأجهزة.
</p>
<CardGroup cols={2}>
@ -394,32 +441,40 @@ CLI لـ Linear يتكامل مع تدفقات العمل المعتمدة عل
</CardGroup>
## 🌟 مشروعات المجتمع
<h2 id="community-projects">مشاريع المجتمع</h2>
<p className="showcase-section-intro">
أشياء نمت إلى ما هو أبعد من سير عمل واحد لتصبح منتجات أو أنظمة بيئية أوسع.
</p>
<CardGroup cols={2}>
<Card title="سوق StarSwap" icon="star" href="https://star-swap.com/">
**Community** • `marketplace` `astronomy` `webapp`
**المجتمع** • `marketplace` `astronomy` `webapp`
سوق كامل لمعدات الفلك. بُني باستخدام/حول منظومة OpenClaw.
سوق كامل لمعدات علم الفلك. بُني باستخدام/حول نظام OpenClaw البيئي.
</Card>
</CardGroup>
---
## أرسل مشروعك
<h2 id="submit-your-project">أرسل مشروعك</h2>
هل لديك شيء تشاركه؟ يسعدنا عرضه!
<p className="showcase-section-intro">
إذا كنت تبني شيئًا مثيرًا للاهتمام باستخدام OpenClaw، فأرسله إلينا. تساعد لقطات الشاشة القوية والنتائج الملموسة.
</p>
هل لديك شيء لتشاركه؟ يسعدنا عرضه!
<Steps>
<Step title="شاركه">
انشر في [#self-promotion on Discord](https://discord.gg/clawd) أو [غرّد إلى @openclaw](https://x.com/openclaw)
انشره في [#self-promotion on Discord](https://discord.gg/clawd) أو [غرّد إلى @openclaw](https://x.com/openclaw)
</Step>
<Step title="أدرج التفاصيل">
أخبرنا بما يفعله، واربط المستودع/العرض التوضيحي، وشارك لقطة شاشة إذا كانت لديك
أخبرنا بما يفعله، واربط بالمستودع/العرض التوضيحي، وشارك لقطة شاشة إذا كانت لديك
</Step>
<Step title="احصل على ظهور">
سنضيف المشروعات المميزة إلى هذه الصفحة
<Step title="احصل على الظهور">
سنضيف المشاريع البارزة إلى هذه الصفحة
</Step>
</Steps>

358
docs/ar/tools/video-generation.md
View File

@ -1,39 +1,39 @@
---
read_when:
- إنشاء الفيديوهات عبر الوكيل
- تكوين مزودي ونماذج إنشاء الفيديوهات
- إنشاء مقاطع فيديو عبر الوكيل
- إعداد موفري ونماذج توليد الفيديو
- فهم معلمات أداة `video_generate`
summary: أنشئ مقاطع فيديو من النصوص أو الصور أو مقاطع الفيديو الموجودة باستخدام 14 واجهة مزود.
title: إنشاء الفيديوهات
summary: أنشئ مقاطع فيديو من نصوص أو صور أو مقاطع فيديو موجودة باستخدام 14 واجهة مزوّد خلفية
title: توليد الفيديو
x-i18n:
generated_at: "2026-04-11T15:16:03Z"
generated_at: "2026-04-15T07:18:45Z"
model: gpt-5.4
provider: openai
source_hash: 0ec159a0bbb6b8a030e68828c0a8bcaf40c8538ecf98bc8ff609dab9d0068263
source_hash: c182f24b25e44f157a820e82a1f7422247f26125956944b5eb98613774268cfe
source_path: tools/video-generation.md
workflow: 15
---
# إنشاء الفيديوهات
# توليد الفيديو
يمكن لوكلاء OpenClaw إنشاء مقاطع فيديو من المطالبات النصية أو الصور المرجعية أو مقاطع الفيديو الموجودة. يتم دعم أربع عشرة واجهة مزود، ولكل منها خيارات نماذج وأوضاع إدخال ومجموعات ميزات مختلفة. يختار الوكيل المزود المناسب تلقائيًا استنادًا إلى تكوينك ومفاتيح API المتاحة.
يمكن لوكلاء OpenClaw إنشاء مقاطع فيديو من مطالبات نصية أو صور مرجعية أو مقاطع فيديو موجودة. يتم دعم أربع عشرة واجهة مزوّد خلفية، ولكل منها خيارات نماذج وأوضاع إدخال ومجموعات ميزات مختلفة. يختار الوكيل المزوّد المناسب تلقائيًا بناءً على إعداداتك ومفاتيح API المتاحة.
<Note>
لا تظهر أداة `video_generate` إلا عند توفر مزود واحد على الأقل لإنشاء الفيديوهات. إذا لم تظهر ضمن أدوات الوكيل لديك، فقم بتعيين مفتاح API للمزود أو كوّن `agents.defaults.videoGenerationModel`.
تظهر أداة `video_generate` فقط عند توفر مزوّد واحد على الأقل لتوليد الفيديو. إذا لم ترها ضمن أدوات الوكيل، فقم بتعيين مفتاح API لمزوّد أو اضبط `agents.defaults.videoGenerationModel`.
</Note>
يتعامل OpenClaw مع إنشاء الفيديوهات على أنه ثلاثة أوضاع تشغيل:
يتعامل OpenClaw مع توليد الفيديو على أنه ثلاثة أوضاع تشغيل:
- `generate` لطلبات تحويل النص إلى فيديو بدون وسائط مرجعية
- `generate` لطلبات النص إلى فيديو التي لا تحتوي على وسائط مرجعية
- `imageToVideo` عندما يتضمن الطلب صورة مرجعية واحدة أو أكثر
- `videoToVideo` عندما يتضمن الطلب مقطع فيديو مرجعيًا واحدًا أو أكثر
يمكن للمزودين دعم أي مجموعة فرعية من هذه الأوضاع. تتحقق الأداة من الوضع
يمكن للمزوّدين دعم أي مجموعة فرعية من هذه الأوضاع. تتحقق الأداة من الوضع
النشط قبل الإرسال وتعرض الأوضاع المدعومة في `action=list`.
## البدء السريع
1. عيّن مفتاح API لأي مزود مدعوم:
1. عيّن مفتاح API لأي مزوّد مدعوم:
```bash
export GEMINI_API_KEY="your-key"
@ -47,31 +47,31 @@ openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1
3. اطلب من الوكيل:
> أنشئ فيديو سينمائيًا مدته 5 ثوانٍ لكركند ودود يتزلج على الأمواج عند غروب الشمس.
> أنشئ فيديو سينمائيًا مدته 5 ثوانٍ لكركند ودود يتزلج على الأمواج عند الغروب.
سيستدعي الوكيل `video_generate` تلقائيًا. لا حاجة إلى قائمة سماح للأدوات.
## ماذا يحدث عند إنشاء فيديو
إنشاء الفيديو عملية غير متزامنة. عندما يستدعي الوكيل `video_generate` في جلسة:
توليد الفيديو غير متزامن. عندما يستدعي الوكيل `video_generate` في جلسة:
1. يرسل OpenClaw الطلب إلى المزود ويعيد فورًا معرّف مهمة.
2. يعالج المزود المهمة في الخلفية (عادةً من 30 ثانية إلى 5 دقائق حسب المزود والدقة).
1. يرسل OpenClaw الطلب إلى المزوّد ويعيد فورًا معرّف مهمة.
2. يعالج المزوّد المهمة في الخلفية (عادةً من 30 ثانية إلى 5 دقائق حسب المزوّد والدقة).
3. عندما يصبح الفيديو جاهزًا، يوقظ OpenClaw الجلسة نفسها عبر حدث إكمال داخلي.
4. ينشر الوكيل الفيديو النهائي مرة أخرى في المحادثة الأصلية.
4. ينشر الوكيل الفيديو المكتمل مرة أخرى في المحادثة الأصلية.
أثناء تنفيذ المهمة، فإن أي استدعاءات مكررة لـ `video_generate` في الجلسة نفسها تعيد حالة المهمة الحالية بدلًا من بدء إنشاء جديد. استخدم `openclaw tasks list` أو `openclaw tasks show <taskId>` للتحقق من التقدم من خلال CLI.
أثناء تنفيذ مهمة، فإن استدعاءات `video_generate` المكررة في الجلسة نفسها تعيد حالة المهمة الحالية بدلًا من بدء عملية توليد أخرى. استخدم `openclaw tasks list` أو `openclaw tasks show <taskId>` للتحقق من التقدم من خلال CLI.
خارج عمليات تشغيل الوكيل المدعومة بجلسة (على سبيل المثال، استدعاءات الأدوات المباشرة)، تعود الأداة إلى الإنشاء المضمن وتعيد مسار الوسائط النهائي في نفس الدورة.
خارج عمليات تشغيل الوكيل المدعومة بجلسة (على سبيل المثال، استدعاءات الأدوات المباشرة)، تعود الأداة إلى التوليد المضمن وتعيد مسار الوسائط النهائي في الدورة نفسها.
### دورة حياة المهمة
يمر كل طلب `video_generate` عبر أربع حالات:
1. **queued** -- تم إنشاء المهمة وهي بانتظار أن يقبلها المزود.
2. **running** -- يعالج المزود المهمة (عادةً من 30 ثانية إلى 5 دقائق حسب المزود والدقة).
3. **succeeded** -- أصبح الفيديو جاهزًا؛ يستيقظ الوكيل وينشره في المحادثة.
4. **failed** -- خطأ من المزود أو انتهاء مهلة؛ يستيقظ الوكيل مع تفاصيل الخطأ.
1. **queued** -- تم إنشاء المهمة، وهي بانتظار أن يقبلها المزوّد.
2. **running** -- يعالج المزوّد المهمة (عادةً من 30 ثانية إلى 5 دقائق حسب المزوّد والدقة).
3. **succeeded** -- أصبح الفيديو جاهزًا؛ يوقظ الوكيل نفسه وينشره في المحادثة.
4. **failed** -- خطأ من المزوّد أو انتهاء مهلة؛ يوقظ الوكيل نفسه مع تفاصيل الخطأ.
تحقق من الحالة من خلال CLI:
@ -81,165 +81,165 @@ openclaw tasks show <taskId>
openclaw tasks cancel <taskId>
```
منع التكرار: إذا كانت هناك بالفعل مهمة فيديو بالحالة `queued` أو `running` للجلسة الحالية، فستعيد `video_generate` حالة المهمة الموجودة بدلًا من بدء مهمة جديدة. استخدم `action: "status"` للتحقق بشكل صريح بدون تشغيل إنشاء جديد.
منع التكرار: إذا كانت هناك مهمة فيديو بحالة `queued` أو `running` بالفعل للجلسة الحالية، فإن `video_generate` يعيد حالة المهمة الموجودة بدلًا من بدء مهمة جديدة. استخدم `action: "status"` للتحقق صراحةً من دون تشغيل عملية توليد جديدة.
## المزودون المدعومون
## المزوّدون المدعومون
| المزود | النموذج الافتراضي | نص | صورة مرجعية | فيديو مرجعي | مفتاح API |
| ------ | ----------------- | --- | ------------ | ------------ | --------- |
| Alibaba | `wan2.6-t2v` | نعم | نعم (URL بعيد) | نعم (URL بعيد) | `MODELSTUDIO_API_KEY` |
| BytePlus (1.0) | `seedance-1-0-pro-250528` | نعم | حتى صورتين (نماذج I2V فقط؛ الإطار الأول + الأخير) | لا | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | نعم | حتى صورتين (الإطار الأول + الأخير عبر الدور) | لا | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | نعم | حتى 9 صور مرجعية | حتى 3 مقاطع فيديو | `BYTEPLUS_API_KEY` |
| ComfyUI | `workflow` | نعم | صورة واحدة | لا | `COMFY_API_KEY` أو `COMFY_CLOUD_API_KEY` |
| fal | `fal-ai/minimax/video-01-live` | نعم | صورة واحدة | لا | `FAL_KEY` |
| Google | `veo-3.1-fast-generate-preview` | نعم | صورة واحدة | مقطع فيديو واحد | `GEMINI_API_KEY` |
| MiniMax | `MiniMax-Hailuo-2.3` | نعم | صورة واحدة | لا | `MINIMAX_API_KEY` |
| OpenAI | `sora-2` | نعم | صورة واحدة | مقطع فيديو واحد | `OPENAI_API_KEY` |
| Qwen | `wan2.6-t2v` | نعم | نعم (URL بعيد) | نعم (URL بعيد) | `QWEN_API_KEY` |
| Runway | `gen4.5` | نعم | صورة واحدة | مقطع فيديو واحد | `RUNWAYML_API_SECRET` |
| Together | `Wan-AI/Wan2.2-T2V-A14B` | نعم | صورة واحدة | لا | `TOGETHER_API_KEY` |
| Vydra | `veo3` | نعم | صورة واحدة (`kling`) | لا | `VYDRA_API_KEY` |
| xAI | `grok-imagine-video` | نعم | صورة واحدة | مقطع فيديو واحد | `XAI_API_KEY` |
| المزوّد | النموذج الافتراضي | نص | مرجع صورة | مرجع فيديو | مفتاح API |
| -------------------- | ------------------------------- | --- | ---------------------------------------------------- | ---------------- | ----------------------------------------- |
| Alibaba | `wan2.6-t2v` | نعم | نعم (URL بعيد) | نعم (URL بعيد) | `MODELSTUDIO_API_KEY` |
| BytePlus (1.0) | `seedance-1-0-pro-250528` | نعم | حتى صورتين (لنماذج I2V فقط؛ الإطار الأول + الأخير) | لا | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | نعم | حتى صورتين (الإطار الأول + الأخير عبر role) | لا | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | نعم | حتى 9 صور مرجعية | حتى 3 مقاطع فيديو | `BYTEPLUS_API_KEY` |
| ComfyUI | `workflow` | نعم | صورة واحدة | لا | `COMFY_API_KEY` أو `COMFY_CLOUD_API_KEY` |
| fal | `fal-ai/minimax/video-01-live` | نعم | صورة واحدة | لا | `FAL_KEY` |
| Google | `veo-3.1-fast-generate-preview` | نعم | صورة واحدة | مقطع فيديو واحد | `GEMINI_API_KEY` |
| MiniMax | `MiniMax-Hailuo-2.3` | نعم | صورة واحدة | لا | `MINIMAX_API_KEY` |
| OpenAI | `sora-2` | نعم | صورة واحدة | مقطع فيديو واحد | `OPENAI_API_KEY` |
| Qwen | `wan2.6-t2v` | نعم | نعم (URL بعيد) | نعم (URL بعيد) | `QWEN_API_KEY` |
| Runway | `gen4.5` | نعم | صورة واحدة | مقطع فيديو واحد | `RUNWAYML_API_SECRET` |
| Together | `Wan-AI/Wan2.2-T2V-A14B` | نعم | صورة واحدة | لا | `TOGETHER_API_KEY` |
| Vydra | `veo3` | نعم | صورة واحدة (`kling`) | لا | `VYDRA_API_KEY` |
| xAI | `grok-imagine-video` | نعم | صورة واحدة | مقطع فيديو واحد | `XAI_API_KEY` |
تقبل بعض المزودات متغيرات بيئة إضافية أو بديلة لمفاتيح API. راجع [صفحات المزود الفردية](#related) للحصول على التفاصيل.
تقبل بعض المزوّدين متغيرات بيئة إضافية أو بديلة لمفتاح API. راجع [صفحات المزوّد](#related) الفردية للحصول على التفاصيل.
شغّل `video_generate action=list` لفحص المزودات والنماذج
وأوضاع التشغيل المتاحة أثناء وقت التشغيل.
شغّل `video_generate action=list` لفحص المزوّدين والنماذج وأوضاع التشغيل
المتاحة في وقت التشغيل.
### مصفوفة القدرات المعلنة
هذا هو عقد الأوضاع الصريح الذي تستخدمه `video_generate` واختبارات العقد
والفحص الحي المشترك.
وعملية الفحص الحي المشتركة.
| المزود | `generate` | `imageToVideo` | `videoToVideo` | مسارات الفحص الحي المشتركة الحالية |
| ------ | ---------- | -------------- | -------------- | ----------------------------------- |
| Alibaba | نعم | نعم | نعم | `generate` و`imageToVideo`؛ تم تخطي `videoToVideo` لأن هذا المزود يتطلب عناوين URL لفيديوهات `http(s)` بعيدة |
| BytePlus | نعم | نعم | لا | `generate` و`imageToVideo` |
| ComfyUI | نعم | نعم | لا | ليس ضمن الفحص المشترك؛ التغطية الخاصة بسير العمل موجودة ضمن اختبارات Comfy |
| fal | نعم | نعم | لا | `generate` و`imageToVideo` |
| Google | نعم | نعم | نعم | `generate` و`imageToVideo`؛ تم تخطي `videoToVideo` المشترك لأن فحص Gemini/Veo الحالي المعتمد على المخزن المؤقت لا يقبل هذا الإدخال |
| MiniMax | نعم | نعم | لا | `generate` و`imageToVideo` |
| OpenAI | نعم | نعم | نعم | `generate` و`imageToVideo`؛ تم تخطي `videoToVideo` المشترك لأن مسار المؤسسة/الإدخال هذا يحتاج حاليًا إلى وصول inpaint/remix من جهة المزود |
| Qwen | نعم | نعم | نعم | `generate` و`imageToVideo`؛ تم تخطي `videoToVideo` لأن هذا المزود يتطلب عناوين URL لفيديوهات `http(s)` بعيدة |
| Runway | نعم | نعم | نعم | `generate` و`imageToVideo`؛ يتم تشغيل `videoToVideo` فقط عندما يكون النموذج المحدد هو `runway/gen4_aleph` |
| Together | نعم | نعم | لا | `generate` و`imageToVideo` |
| Vydra | نعم | نعم | لا | `generate`؛ تم تخطي `imageToVideo` المشترك لأن `veo3` المضمن يدعم النص فقط و`kling` المضمن يتطلب عنوان URL بعيدًا للصورة |
| xAI | نعم | نعم | نعم | `generate` و`imageToVideo`؛ تم تخطي `videoToVideo` لأن هذا المزود يتطلب حاليًا عنوان URL بعيدًا لملف MP4 |
| المزوّد | `generate` | `imageToVideo` | `videoToVideo` | مسارات الاختبار الحي المشتركة اليوم |
| ------- | ---------- | -------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Alibaba | نعم | نعم | نعم | `generate`، `imageToVideo`؛ يتم تخطي `videoToVideo` لأن هذا المزوّد يحتاج إلى عناوين URL لفيديو بعيدة من نوع `http(s)` |
| BytePlus | نعم | نعم | لا | `generate`، `imageToVideo` |
| ComfyUI | نعم | نعم | لا | غير موجود في الفحص المشترك؛ وتوجد التغطية الخاصة بسير العمل ضمن اختبارات Comfy |
| fal | نعم | نعم | لا | `generate`، `imageToVideo` |
| Google | نعم | نعم | نعم | `generate`، `imageToVideo`؛ يتم تخطي `videoToVideo` المشترك لأن فحص Gemini/Veo الحالي المعتمد على buffer لا يقبل هذا الإدخال |
| MiniMax | نعم | نعم | لا | `generate`، `imageToVideo` |
| OpenAI | نعم | نعم | نعم | `generate`، `imageToVideo`؛ يتم تخطي `videoToVideo` المشترك لأن هذا المسار للمؤسسة/الإدخال يحتاج حاليًا إلى وصول inpaint/remix من جهة المزوّد |
| Qwen | نعم | نعم | نعم | `generate`، `imageToVideo`؛ يتم تخطي `videoToVideo` لأن هذا المزوّد يحتاج إلى عناوين URL لفيديو بعيدة من نوع `http(s)` |
| Runway | نعم | نعم | نعم | `generate`، `imageToVideo`؛ لا يعمل `videoToVideo` إلا عندما يكون النموذج المحدد هو `runway/gen4_aleph` |
| Together | نعم | نعم | لا | `generate`، `imageToVideo` |
| Vydra | نعم | نعم | لا | `generate`؛ يتم تخطي `imageToVideo` المشترك لأن `veo3` المجمّع نصي فقط و`kling` المجمّع يتطلب URL صورة بعيدًا |
| xAI | نعم | نعم | نعم | `generate`، `imageToVideo`؛ يتم تخطي `videoToVideo` لأن هذا المزوّد يحتاج حاليًا إلى URL بعيد لملف MP4 |
## معلمات الأداة
### مطلوبة
| المعلمة | النوع | الوصف |
| ------- | ----- | ------ |
| `prompt` | string | وصف نصي للفيديو المراد إنشاؤه (مطلوب لـ `action: "generate"`) |
| المعلمة | النوع | الوصف |
| ------- | ------ | ------------------------------------------------------------------------ |
| `prompt`| string | وصف نصي للفيديو المراد إنشاؤه (مطلوب لـ `action: "generate"`) |
### مدخلات المحتوى
| المعلمة | النوع | الوصف |
| ------- | ----- | ------ |
| `image` | string | صورة مرجعية واحدة (مسار أو URL) |
| `images` | string[] | صور مرجعية متعددة (حتى 9) |
| `imageRoles` | string[] | تلميحات أدوار اختيارية لكل موضع بالتوازي مع قائمة الصور المدمجة. القيم القياسية: `first_frame` و`last_frame` و`reference_image` |
| `video` | string | مقطع فيديو مرجعي واحد (مسار أو URL) |
| `videos` | string[] | مقاطع فيديو مرجعية متعددة (حتى 4) |
| `videoRoles` | string[] | تلميحات أدوار اختيارية لكل موضع بالتوازي مع قائمة الفيديوهات المدمجة. القيمة القياسية: `reference_video` |
| `audioRef` | string | ملف صوت مرجعي واحد (مسار أو URL). يُستخدم مثلًا للموسيقى الخلفية أو مرجع الصوت عندما يدعم المزود مدخلات الصوت |
| `audioRefs` | string[] | ملفات صوت مرجعية متعددة (حتى 3) |
| `audioRoles` | string[] | تلميحات أدوار اختيارية لكل موضع بالتوازي مع قائمة المقاطع الصوتية المدمجة. القيمة القياسية: `reference_audio` |
| المعلمة | النوع | الوصف |
| ----------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `image` | string | صورة مرجعية واحدة (مسار أو URL) |
| `images` | string[] | عدة صور مرجعية (حتى 9) |
| `imageRoles`| string[] | تلميحات role اختيارية لكل موضع بالتوازي مع قائمة الصور المجمعة. القيم القياسية: `first_frame` و`last_frame` و`reference_image` |
| `video` | string | مقطع فيديو مرجعي واحد (مسار أو URL) |
| `videos` | string[] | عدة مقاطع فيديو مرجعية (حتى 4) |
| `videoRoles`| string[] | تلميحات role اختيارية لكل موضع بالتوازي مع قائمة الفيديو المجمعة. القيمة القياسية: `reference_video` |
| `audioRef` | string | مرجع صوتي واحد (مسار أو URL). يُستخدم مثلًا للموسيقى الخلفية أو مرجع الصوت عندما يدعم المزوّد مدخلات الصوت |
| `audioRefs` | string[] | عدة مراجع صوتية (حتى 3) |
| `audioRoles`| string[] | تلميحات role اختيارية لكل موضع بالتوازي مع قائمة الصوت المجمعة. القيمة القياسية: `reference_audio` |
تُمرَّر تلميحات الأدوار إلى المزود كما هي. تأتي القيم القياسية من
اتحاد `VideoGenerationAssetRole` ولكن قد تقبل المزودات
سلاسل أدوار إضافية. يجب ألا تحتوي مصفوفات `*Roles` على عدد إدخالات أكبر من
القائمة المرجعية المقابلة؛ وتفشل أخطاء الزيادة أو النقصان بمقدار واحد برسالة خطأ واضحة.
استخدم سلسلة فارغة لترك خانة بدون تعيين.
يتم تمرير تلميحات role إلى المزوّد كما هي. تأتي القيم القياسية من
اتحاد `VideoGenerationAssetRole` لكن قد تقبل بعض المزوّدات سلاسل role
إضافية. يجب ألا تحتوي مصفوفات `*Roles` على إدخالات أكثر من
قائمة المراجع المقابلة؛ تؤدي أخطاء الزيادة أو النقصان بمقدار واحد إلى فشل
واضح برسالة خطأ. استخدم سلسلة فارغة لترك موضع من دون تعيين.
### عناصر التحكم في النمط
| المعلمة | النوع | الوصف |
| ------- | ----- | ------ |
| `aspectRatio` | string | `1:1` أو `2:3` أو `3:2` أو `3:4` أو `4:3` أو `4:5` أو `5:4` أو `9:16` أو `16:9` أو `21:9` أو `adaptive` |
| `resolution` | string | `480P` أو `720P` أو `768P` أو `1080P` |
| `durationSeconds` | number | المدة المستهدفة بالثواني (تُقرَّب إلى أقرب قيمة يدعمها المزود) |
| `size` | string | تلميح للحجم عندما يدعمه المزود |
| `audio` | boolean | تمكين الصوت المُنشأ في الناتج عندما يكون مدعومًا. وهو مختلف عن `audioRef*` (المدخلات) |
| `watermark` | boolean | تبديل العلامة المائية الخاصة بالمزود عندما تكون مدعومة |
| المعلمة | النوع | الوصف |
| ---------------- | ------- | -------------------------------------------------------------------------------------- |
| `aspectRatio` | string | ‏`1:1` أو `2:3` أو `3:2` أو `3:4` أو `4:3` أو `4:5` أو `5:4` أو `9:16` أو `16:9` أو `21:9` أو `adaptive` |
| `resolution` | string | ‏`480P` أو `720P` أو `768P` أو `1080P` |
| `durationSeconds`| number | المدة المستهدفة بالثواني (تُقرّب إلى أقرب قيمة يدعمها المزوّد) |
| `size` | string | تلميح للحجم عندما يدعمه المزوّد |
| `audio` | boolean | تفعيل الصوت المُولَّد في المخرجات عند دعمه. وهو مختلف عن `audioRef*` (المدخلات) |
| `watermark` | boolean | تبديل العلامة المائية الخاصة بالمزوّد عند دعمها |
تُعد `adaptive` قيمة خاصة مرتبطة بالمزود: حيث تُمرَّر كما هي إلى
المزودين الذين يعلنون `adaptive` ضمن قدراتهم (على سبيل المثال، يستخدمها BytePlus
تُعد `adaptive` قيمة sentinel خاصة بالمزوّد: يتم تمريرها كما هي إلى
المزوّدين الذين يعلنون `adaptive` ضمن قدراتهم (على سبيل المثال، يستخدمها BytePlus
Seedance لاكتشاف النسبة تلقائيًا من أبعاد
الصورة المدخلة). أما المزودون الذين لا يعلنون عنها فيعرضون هذه القيمة عبر
`details.ignoredOverrides` في نتيجة الأداة بحيث يكون تجاهلها ظاهرًا.
صورة الإدخال). أما المزوّدون الذين لا يعلنون عنها فيعرضون هذه القيمة عبر
`details.ignoredOverrides` في نتيجة الأداة بحيث يكون تجاهلها مرئيًا.
### متقدمة
| المعلمة | النوع | الوصف |
| ------- | ----- | ------ |
| `action` | string | `"generate"` (افتراضي) أو `"status"` أو `"list"` |
| `model` | string | تجاوز المزود/النموذج (مثل `runway/gen4.5`) |
| `filename` | string | تلميح لاسم ملف الإخراج |
| `providerOptions` | object | خيارات خاصة بالمزود على شكل كائن JSON (مثل `{"seed": 42, "draft": true}`). تتحقق المزودات التي تعلن مخططًا ذا أنواع محددة من المفاتيح وأنواع القيم؛ أما المفاتيح غير المعروفة أو عدم تطابق الأنواع فيؤديان إلى تخطي المرشح أثناء التبديل الاحتياطي. وتتلقى المزودات التي لا تحتوي على مخطط معلن الخيارات كما هي. شغّل `video_generate action=list` لمعرفة ما يقبله كل مزود |
| المعلمة | النوع | الوصف |
| ---------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `action` | string | ‏`"generate"` (الافتراضي) أو `"status"` أو `"list"` |
| `model` | string | تجاوز المزوّد/النموذج (مثل `runway/gen4.5`) |
| `filename` | string | تلميح لاسم ملف الإخراج |
| `providerOptions`| object | خيارات خاصة بالمزوّد ككائن JSON (مثل `{"seed": 42, "draft": true}`). تقوم المزوّدات التي تعلن مخططًا Typed بالتحقق من المفاتيح والأنواع؛ أما المفاتيح غير المعروفة أو عدم تطابق الأنواع فيؤديان إلى تخطي المرشح أثناء التراجع. وتتلقى المزوّدات التي لا تملك مخططًا معلنًا الخيارات كما هي. شغّل `video_generate action=list` لمعرفة ما الذي يقبله كل مزوّد |
لا تدعم جميع المزودات كل المعلمات. يقوم OpenClaw بالفعل بتطبيع المدة إلى أقرب قيمة يدعمها المزود، كما يعيد أيضًا تعيين تلميحات الهندسة المترجمة مثل تحويل الحجم إلى نسبة أبعاد عندما يكشف مزود احتياطي سطح تحكم مختلفًا. أما التجاوزات غير المدعومة فعلًا فيتم تجاهلها بأفضل جهد ممكن والإبلاغ عنها كتحذيرات في نتيجة الأداة. وتفشل حدود القدرات الصارمة (مثل كثرة عدد المدخلات المرجعية) قبل الإرسال.
لا تدعم جميع المزوّدات جميع المعلمات. يقوم OpenClaw بالفعل بتطبيع المدة إلى أقرب قيمة يدعمها المزوّد، كما يعيد أيضًا تعيين تلميحات الهندسة المترجمة مثل التحويل من الحجم إلى نسبة العرض إلى الارتفاع عندما يوفّر مزوّد التراجع سطح تحكم مختلفًا. أما قيم التجاوز غير المدعومة فعليًا فيتم تجاهلها بأفضل جهد ممكن ويُبلَّغ عنها كتحذيرات في نتيجة الأداة. وتفشل حدود القدرات الصارمة (مثل كثرة المدخلات المرجعية) قبل الإرسال.
تعرض نتائج الأداة الإعدادات المطبقة. عندما يعيد OpenClaw تعيين المدة أو الهندسة أثناء التبديل الاحتياطي بين المزودات، فإن القيم المعادة في `durationSeconds` و`size` و`aspectRatio` و`resolution` تعكس ما تم إرساله، بينما يلتقط `details.normalization` التحويل من القيم المطلوبة إلى القيم المطبقة.
تعرض نتائج الأداة الإعدادات المطبقة. عندما يعيد OpenClaw تعيين المدة أو الهندسة أثناء التراجع بين المزوّدين، فإن القيم المعادة في `durationSeconds` و`size` و`aspectRatio` و`resolution` تعكس ما تم إرساله، بينما يلتقط `details.normalization` ترجمة القيم المطلوبة إلى القيم المطبقة.
تحدد المدخلات المرجعية أيضًا وضع التشغيل:
- بدون وسائط مرجعية: `generate`
- أي صورة مرجعية: `imageToVideo`
- أي فيديو مرجعي: `videoToVideo`
- لا تغيّر المدخلات الصوتية المرجعية الوضع الذي تم تحديده؛ بل تُطبَّق فوق أي وضع تحدده المراجع الصورية/الفيديوية، ولا تعمل إلا مع المزودات التي تعلن `maxInputAudios`
- أي مرجع صورة: `imageToVideo`
- أي مرجع فيديو: `videoToVideo`
- لا تغيّر مدخلات الصوت المرجعي الوضع المحدد؛ بل تُطبّق فوق أي وضع تختاره مراجع الصور/الفيديو، ولا تعمل إلا مع المزوّدين الذين يعلنون `maxInputAudios`
إن المزج بين مراجع الصور والفيديو ليس سطح قدرات مشتركة مستقرًا.
يُفضَّل استخدام نوع مرجعي واحد لكل طلب.
لا يُعد خلط مراجع الصور والفيديو سطح قدرات مشتركًا مستقرًا.
ويُفضّل استخدام نوع مرجعي واحد لكل طلب.
#### التبديل الاحتياطي والخيارات ذات الأنواع المحددة
#### التراجع والخيارات Typed
تُطبَّق بعض فحوصات القدرات في طبقة التبديل الاحتياطي بدلًا من
حدود الأداة حتى يتمكن الطلب الذي يتجاوز حدود المزود الأساسي
من العمل على مزود احتياطي قادر:
يتم تطبيق بعض فحوصات القدرات في طبقة التراجع بدلًا من
حدود الأداة حتى يتمكن الطلب الذي يتجاوز حدود المزوّد الأساسي
من العمل على مزوّد تراجع قادر:
- إذا لم يعلن المرشح النشط عن `maxInputAudios` (أو أعلن عنها على أنها
`0`)، فسيتم تخطيه عندما يحتوي الطلب على مراجع صوتية، وتتم
تجربة المرشح التالي.
- إذا كانت `maxDurationSeconds` لدى المرشح النشط أقل من
`durationSeconds` المطلوبة ولم يعلن المرشح عن قائمة
- إذا كان المرشح النشط لا يعلن `maxInputAudios` (أو يعلنه
على أنه `0`)، فسيتم تخطيه عندما يحتوي الطلب على مراجع صوتية، ثم
تتم تجربة المرشح التالي.
- إذا كانت قيمة `maxDurationSeconds` لدى المرشح النشط أقل من القيمة المطلوبة
في `durationSeconds` ولم يكن المرشح يعلن قائمة
`supportedDurationSeconds`، فسيتم تخطيه.
- إذا كان الطلب يحتوي على `providerOptions` وكان المرشح النشط
يعلن صراحة عن مخطط `providerOptions` ذي أنواع محددة، فسيتم
تخطي المرشح عندما لا تكون المفاتيح الموردة موجودة في المخطط أو عندما
لا تتطابق أنواع القيم. أما المزودات التي لم تعلن عن مخطط بعد فتتلقى
الخيارات كما هي (تمرير متوافق مع الإصدارات السابقة). ويمكن للمزود
إلغاء قبول جميع خيارات المزود صراحة عبر إعلان مخطط فارغ
- إذا احتوى الطلب على `providerOptions` وكان المرشح النشط
يعلن صراحةً مخطط `providerOptions` Typed، فسيتم
تخطي المرشح عندما لا تكون المفاتيح المرسلة موجودة في المخطط أو عندما لا
تتطابق أنواع القيم. أما المزوّدات التي لم تعلن مخططًا بعد فتتلقى
الخيارات كما هي (تمرير متوافق مع الإصدارات السابقة). ويمكن لمزوّد
أن ينسحب صراحةً من جميع خيارات المزوّد عبر إعلان مخطط فارغ
(`capabilities.providerOptions: {}`)، مما يؤدي إلى نفس التخطي الناتج عن
عدم تطابق النوع.
يُسجَّل أول سبب للتخطي في الطلب عند مستوى `warn` حتى يرى المشغلون
متى تم تجاوز مزودهم الأساسي؛ أما أسباب التخطي اللاحقة فتُسجَّل عند
`debug` للحفاظ على هدوء سلاسل التبديل الاحتياطي الطويلة. وإذا تم تخطي
كل المرشحين، فسيشمل الخطأ المجمّع سبب التخطي لكل منهم.
يتم تسجيل أول سبب تخطٍ في الطلب عند مستوى `warn` حتى يرى المشغّلون
متى تم تجاوز المزوّد الأساسي لديهم؛ أما أسباب التخطي اللاحقة فتُسجَّل عند
`debug` للحفاظ على هدوء سلاسل التراجع الطويلة. وإذا تم تخطي كل المرشحين،
فسيتضمن الخطأ المجمّع سبب التخطي لكل واحد منهم.
## الإجراءات
- **generate** (افتراضي) -- إنشاء فيديو من المطالبة المعطاة والمدخلات المرجعية الاختيارية.
- **status** -- التحقق من حالة مهمة الفيديو الجارية للجلسة الحالية دون بدء إنشاء آخر.
- **list** -- عرض المزودات والنماذج المتاحة وقدراتها.
- **generate** (الافتراضي) -- إنشاء فيديو من المطالبة المحددة مع مدخلات مرجعية اختيارية.
- **status** -- التحقق من حالة مهمة الفيديو الجاري تنفيذها للجلسة الحالية دون بدء عملية توليد أخرى.
- **list** -- عرض المزوّدين والنماذج المتاحة وقدراتها.
## اختيار النموذج
عند إنشاء فيديو، يحل OpenClaw النموذج بهذا الترتيب:
عند إنشاء فيديو، يحدّد OpenClaw النموذج بهذا الترتيب:
1. **معلمة الأداة `model`** -- إذا حددها الوكيل في الاستدعاء.
2. **`videoGenerationModel.primary`** -- من التكوين.
1. **معلمة الأداة `model`** -- إذا حدّدها الوكيل في الاستدعاء.
2. **`videoGenerationModel.primary`** -- من الإعدادات.
3. **`videoGenerationModel.fallbacks`** -- تُجرَّب بالترتيب.
4. **الاكتشاف التلقائي** -- يستخدم المزودات التي لديها مصادقة صالحة، بدءًا من المزود الافتراضي الحالي، ثم المزودات المتبقية بترتيب أبجدي.
4. **الاكتشاف التلقائي** -- يستخدم المزوّدين الذين يملكون مصادقة صالحة، بدءًا من المزوّد الافتراضي الحالي، ثم بقية المزوّدين بترتيب أبجدي.
إذا فشل مزود، فسيتم تجربة المرشح التالي تلقائيًا. وإذا فشل جميع المرشحين، فسيتضمن الخطأ تفاصيل من كل محاولة.
إذا فشل أحد المزوّدين، تتم تجربة المرشح التالي تلقائيًا. وإذا فشل جميع المرشحين، فسيتضمن الخطأ تفاصيل من كل محاولة.
عيّن `agents.defaults.mediaGenerationAutoProviderFallback: false` إذا كنت تريد
أن يستخدم إنشاء الفيديو فقط إدخالات `model` و`primary` و`fallbacks`
اضبط `agents.defaults.mediaGenerationAutoProviderFallback: false` إذا كنت تريد
أن يستخدم توليد الفيديو فقط إدخالات `model` و`primary` و`fallbacks`
الصريحة.
```json5
@ -255,30 +255,30 @@ Seedance لاكتشاف النسبة تلقائيًا من أبعاد
}
```
## ملاحظات حول المزودين
## ملاحظات حول المزوّدين
| المزود | ملاحظات |
| ------ | -------- |
| Alibaba | يستخدم نقطة النهاية غير المتزامنة DashScope/Model Studio. يجب أن تكون الصور ومقاطع الفيديو المرجعية عناوين URL بعيدة من نوع `http(s)`. |
| BytePlus (1.0) | معرّف المزود `byteplus`. النماذج: `seedance-1-0-pro-250528` (افتراضي)، و`seedance-1-0-pro-t2v-250528`، و`seedance-1-0-pro-fast-251015`، و`seedance-1-0-lite-t2v-250428`، و`seedance-1-0-lite-i2v-250428`. لا تقبل نماذج T2V (`*-t2v-*`) مدخلات الصور؛ بينما تدعم نماذج I2V ونماذج `*-pro-*` العامة صورة مرجعية واحدة (الإطار الأول). مرّر الصورة موضعيًا أو عيّن `role: "first_frame"`. يتم تبديل معرّفات نماذج T2V تلقائيًا إلى متغير I2V المقابل عند توفير صورة. مفاتيح `providerOptions` المدعومة: `seed` (رقم)، و`draft` (قيمة منطقية، يفرض دقة 480p)، و`camera_fixed` (قيمة منطقية). |
| BytePlus Seedance 1.5 | يتطلب إضافة [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark). معرّف المزود `byteplus-seedance15`. النموذج: `seedance-1-5-pro-251215`. يستخدم واجهة `content[]` الموحدة. يدعم بحد أقصى صورتين مدخلتين (first_frame + last_frame). يجب أن تكون جميع المدخلات عناوين URL بعيدة من نوع `https://`. عيّن `role: "first_frame"` / `"last_frame"` لكل صورة، أو مرّر الصور موضعيًا. يقوم `aspectRatio: "adaptive"` باكتشاف النسبة تلقائيًا من صورة الإدخال. يتم تحويل `audio: true` إلى `generate_audio`. ويتم تمرير `providerOptions.seed` (رقم). |
| BytePlus Seedance 2.0 | يتطلب إضافة [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark). معرّف المزود `byteplus-seedance2`. النماذج: `dreamina-seedance-2-0-260128` و`dreamina-seedance-2-0-fast-260128`. يستخدم واجهة `content[]` الموحدة. يدعم حتى 9 صور مرجعية و3 مقاطع فيديو مرجعية و3 ملفات صوت مرجعية. يجب أن تكون جميع المدخلات عناوين URL بعيدة من نوع `https://`. عيّن `role` لكل أصل — القيم المدعومة: `"first_frame"` و`"last_frame"` و`"reference_image"` و`"reference_video"` و`"reference_audio"`. يقوم `aspectRatio: "adaptive"` باكتشاف النسبة تلقائيًا من صورة الإدخال. يتم تحويل `audio: true` إلى `generate_audio`. ويتم تمرير `providerOptions.seed` (رقم). |
| ComfyUI | تنفيذ محلي أو سحابي قائم على سير العمل. يدعم تحويل النص إلى فيديو وتحويل الصورة إلى فيديو عبر الرسم البياني المكوَّن. |
| fal | يستخدم تدفقًا مدعومًا بالطابور للمهام طويلة التشغيل. يدعم صورة مرجعية واحدة فقط. |
| Google | يستخدم Gemini/Veo. يدعم صورة مرجعية واحدة أو مقطع فيديو مرجعي واحد. |
| MiniMax | يدعم صورة مرجعية واحدة فقط. |
| OpenAI | يتم تمرير تجاوز `size` فقط. ويتم تجاهل تجاوزات النمط الأخرى (`aspectRatio` و`resolution` و`audio` و`watermark`) مع تحذير. |
| Qwen | يستخدم الواجهة الخلفية DashScope نفسها الخاصة بـ Alibaba. يجب أن تكون المدخلات المرجعية عناوين URL بعيدة من نوع `http(s)`؛ ويتم رفض الملفات المحلية مسبقًا. |
| Runway | يدعم الملفات المحلية عبر معرّفات URI للبيانات. يتطلب تحويل الفيديو إلى فيديو `runway/gen4_aleph`. تكشف عمليات التشغيل النصية فقط نسب الأبعاد `16:9` و`9:16`. |
| Together | يدعم صورة مرجعية واحدة فقط. |
| Vydra | يستخدم `https://www.vydra.ai/api/v1` مباشرة لتجنب عمليات إعادة التوجيه التي تُسقط المصادقة. يأتي `veo3` مضمّنًا كنمط تحويل النص إلى فيديو فقط؛ بينما يتطلب `kling` عنوان URL بعيدًا للصورة. |
| xAI | يدعم تحويل النص إلى فيديو، وتحويل الصورة إلى فيديو، وتدفقات تحرير/تمديد الفيديو البعيدة. |
| المزوّد | الملاحظات |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Alibaba | يستخدم نقطة النهاية غير المتزامنة الخاصة بـ DashScope/Model Studio. يجب أن تكون الصور ومقاطع الفيديو المرجعية عناوين URL بعيدة من نوع `http(s)`. |
| BytePlus (1.0) | معرّف المزوّد `byteplus`. النماذج: `seedance-1-0-pro-250528` (الافتراضي)، و`seedance-1-0-pro-t2v-250528`، و`seedance-1-0-pro-fast-251015`، و`seedance-1-0-lite-t2v-250428`، و`seedance-1-0-lite-i2v-250428`. لا تقبل نماذج T2V (`*-t2v-*`) مدخلات الصور؛ بينما تدعم نماذج I2V ونماذج `*-pro-*` العامة صورة مرجعية واحدة (الإطار الأول). مرّر الصورة موضعيًا أو اضبط `role: "first_frame"`. يتم التبديل تلقائيًا من معرّفات نماذج T2V إلى إصدار I2V المقابل عند توفير صورة. مفاتيح `providerOptions` المدعومة: `seed` (رقم)، و`draft` (منطقي، ويفرض دقة 480p)، و`camera_fixed` (منطقي). |
| BytePlus Seedance 1.5 | يتطلب Plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark). معرّف المزوّد `byteplus-seedance15`. النموذج: `seedance-1-5-pro-251215`. يستخدم واجهة `content[]` الموحّدة. يدعم بحد أقصى صورتين للإدخال (first_frame + last_frame). يجب أن تكون جميع المدخلات عناوين URL بعيدة من نوع `https://`. اضبط `role: "first_frame"` / `"last_frame"` على كل صورة، أو مرّر الصور موضعيًا. يقوم `aspectRatio: "adaptive"` باكتشاف النسبة تلقائيًا من صورة الإدخال. يتم ربط `audio: true` إلى `generate_audio`. ويتم تمرير `providerOptions.seed` (رقم). |
| BytePlus Seedance 2.0 | يتطلب Plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark). معرّف المزوّد `byteplus-seedance2`. النماذج: `dreamina-seedance-2-0-260128` و`dreamina-seedance-2-0-fast-260128`. يستخدم واجهة `content[]` الموحّدة. يدعم حتى 9 صور مرجعية و3 مقاطع فيديو مرجعية و3 مراجع صوتية. يجب أن تكون جميع المدخلات عناوين URL بعيدة من نوع `https://`. اضبط `role` على كل أصل — القيم المدعومة: `"first_frame"` و`"last_frame"` و`"reference_image"` و`"reference_video"` و`"reference_audio"`. يقوم `aspectRatio: "adaptive"` باكتشاف النسبة تلقائيًا من صورة الإدخال. يتم ربط `audio: true` إلى `generate_audio`. ويتم تمرير `providerOptions.seed` (رقم). |
| ComfyUI | تنفيذ محلي أو سحابي قائم على سير العمل. يدعم النص إلى فيديو والصورة إلى فيديو من خلال الرسم البياني الذي تم تكوينه. |
| fal | يستخدم تدفقًا مدعومًا بالطابور للمهام طويلة التشغيل. يدعم صورة مرجعية واحدة فقط. |
| Google | يستخدم Gemini/Veo. يدعم صورة مرجعية واحدة أو مقطع فيديو مرجعي واحد. |
| MiniMax | يدعم صورة مرجعية واحدة فقط. |
| OpenAI | لا يتم تمرير سوى تجاوز `size`. أما تجاوزات النمط الأخرى (`aspectRatio` و`resolution` و`audio` و`watermark`) فيتم تجاهلها مع تحذير. |
| Qwen | يستخدم نفس الخلفية DashScope مثل Alibaba. يجب أن تكون المدخلات المرجعية عناوين URL بعيدة من نوع `http(s)`؛ ويتم رفض الملفات المحلية مسبقًا. |
| Runway | يدعم الملفات المحلية عبر data URI. يتطلب وضع الفيديو إلى فيديو `runway/gen4_aleph`. تعرض عمليات التشغيل النصية فقط نسب العرض إلى الارتفاع `16:9` و`9:16`. |
| Together | يدعم صورة مرجعية واحدة فقط. |
| Vydra | يستخدم `https://www.vydra.ai/api/v1` مباشرةً لتجنب عمليات إعادة التوجيه التي تُسقط المصادقة. يتم تجميع `veo3` كنموذج نص إلى فيديو فقط؛ بينما يتطلب `kling` عنوان URL بعيدًا لصورة. |
| xAI | يدعم تدفقات النص إلى فيديو، والصورة إلى فيديو، وتحرير/تمديد الفيديو البعيد. |
## أوضاع قدرات المزود
## أوضاع قدرات المزوّد
يتيح عقد إنشاء الفيديوهات المشترك الآن للمزودات إعلان
قدرات خاصة بكل وضع بدلًا من الاكتفاء بحدود مجمعة مسطحة فقط. ويجب على
التنفيذات الجديدة للمزودات تفضيل كتل الأوضاع الصريحة:
يتيح عقد توليد الفيديو المشترك الآن للمزوّدين إعلان قدرات خاصة بكل وضع
بدلًا من حدود مجمعة ومسطحة فقط. يجب أن تفضّل
التنفيذات الجديدة للمزوّدين كتل أوضاع صريحة:
```typescript
capabilities: {
@ -302,43 +302,55 @@ capabilities: {
}
```
لا تكفي الحقول المجمعة المسطحة مثل `maxInputImages` و`maxInputVideos`
للإعلان عن دعم أوضاع التحويل. يجب على المزودات إعلان
`generate` و`imageToVideo` و`videoToVideo` بشكل صريح حتى تتمكن الاختبارات الحية
واختبارات العقد وأداة `video_generate` المشتركة من التحقق من دعم الأوضاع
الحقول المجمعة المسطحة مثل `maxInputImages` و`maxInputVideos` ليست
كافية للإعلان عن دعم أوضاع التحويل. يجب على المزوّدين الإعلان عن
`generate` و`imageToVideo` و`videoToVideo` بشكل صريح حتى تتمكن الاختبارات الحية،
واختبارات العقد، وأداة `video_generate` المشتركة من التحقق من دعم الأوضاع
بشكل حتمي.
## الاختبارات الحية
تغطية حية اختيارية للمزودات المضمنة المشتركة:
تغطية حية اختيارية للمزوّدين المجمّعين المشتركين:
```bash
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts
```
مغلّف المستودع:
غلاف المستودع:
```bash
pnpm test:live:media video
```
يقوم هذا الملف الحي بتحميل متغيرات بيئة المزودات الناقصة من `~/.profile`،
ويعطي الأفضلية افتراضيًا لمفاتيح API الحية/الخاصة بالبيئة على ملفات
المصادقة المخزنة، ويشغّل الأوضاع المعلنة التي يمكنه اختبارها بأمان باستخدام
وسائط محلية:
يقوم هذا الملف الحي بتحميل متغيرات بيئة المزوّد غير الموجودة من `~/.profile`، ويفضّل
مفاتيح API الحية/البيئية على ملفات المصادقة المخزنة افتراضيًا، ويشغّل
اختبار smoke آمنًا للإصدار بشكل افتراضي:
- `generate` لكل مزوّد غير FAL ضمن الفحص
- مطالبة كركند مدتها ثانية واحدة
- حد عمليات لكل مزوّد من `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS`
(`180000` افتراضيًا)
يكون FAL اختياريًا لأن زمن الانتظار في الطابور من جهة المزوّد قد يهيمن على وقت الإصدار:
```bash
pnpm test:live:media video --video-providers fal
```
اضبط `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` لتشغيل أوضاع التحويل المعلنة أيضًا
التي يمكن للفحص المشترك تنفيذها بأمان باستخدام وسائط محلية:
- `generate` لكل مزود في الفحص
- `imageToVideo` عندما تكون `capabilities.imageToVideo.enabled`
- `videoToVideo` عندما تكون `capabilities.videoToVideo.enabled` ويقبل المزود/النموذج
إدخال الفيديو المحلي المعتمد على المخزن المؤقت في الفحص المشترك
- `videoToVideo` عندما تكون `capabilities.videoToVideo.enabled` وكان المزوّد/النموذج
يقبل إدخال فيديو محليًا معتمدًا على buffer في الفحص المشترك
يغطي مسار `videoToVideo` الحي المشترك اليوم:
حاليًا يغطي المسار الحي المشترك `videoToVideo` ما يلي:
- `runway` فقط عند اختيار `runway/gen4_aleph`
- `runway` فقط عندما تختار `runway/gen4_aleph`
## التكوين
## الإعداد
عيّن نموذج إنشاء الفيديو الافتراضي في تكوين OpenClaw الخاص بك:
عيّن نموذج توليد الفيديو الافتراضي في إعدادات OpenClaw الخاصة بك:
```json5
{
@ -362,7 +374,7 @@ openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2
## ذو صلة
- [نظرة عامة على الأدوات](/ar/tools)
- [المهام في الخلفية](/ar/automation/tasks) -- تتبع المهام لإنشاء الفيديوهات غير المتزامن
- [المهام الخلفية](/ar/automation/tasks) -- تتبع المهام لتوليد الفيديو غير المتزامن
- [Alibaba Model Studio](/ar/providers/alibaba)
- [BytePlus](/ar/concepts/model-providers#byteplus-international)
- [ComfyUI](/ar/providers/comfy)
@ -375,5 +387,5 @@ openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2
- [Together AI](/ar/providers/together)
- [Vydra](/ar/providers/vydra)
- [xAI](/ar/providers/xai)
- [مرجع التكوين](/ar/gateway/configuration-reference#agent-defaults)
- [مرجع الإعدادات](/ar/gateway/configuration-reference#agent-defaults)
- [النماذج](/ar/concepts/models)