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 19:51:23 +00:00
parent 14c98fc84d
commit 5bb2d57548
9 changed files with 2177 additions and 1980 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

File diff suppressed because it is too large Load Diff

225
docs/ar/concepts/system-prompt.md
View File

@ -1,103 +1,104 @@
---
read_when:
- تحرير نص مطالبة النظام أو قائمة الأدوات أو أقسام الوقت/نبضات القلب
- تغيير تهيئة مساحة العمل أو سلوك حقن Skills
summary: ما الذي تتضمنه مطالبة نظام OpenClaw وكيف يتم تجميعها
title: مطالبة النظام
- تحرير نص موجه النظام، أو قائمة الأدوات، أو أقسام الوقت/Heartbeat
- تغيير سلوك تهيئة مساحة العمل أو حقن Skills
summary: ما الذي يحتويه موجه نظام OpenClaw وكيف يتم تجميعه
title: موجه النظام
x-i18n:
generated_at: "2026-04-12T07:15:29Z"
generated_at: "2026-04-15T19:41:40Z"
model: gpt-5.4
provider: openai
source_hash: 057f01aac51f7737b5223f61f5d55e552d9011232aebb130426e269d8f6c257f
source_hash: c740e4646bc4980567338237bfb55126af0df72499ca00a48e4848d9a3608ab4
source_path: concepts/system-prompt.md
workflow: 15
---
# مطالبة النظام
# موجه النظام
يبني OpenClaw مطالبة نظام مخصصة لكل تشغيل وكيل. المطالبة **مملوكة لـ OpenClaw** ولا تستخدم المطالبة الافتراضية لـ pi-coding-agent.
يبني OpenClaw موجه نظام مخصصًا لكل تشغيل وكيل. الموجه **مملوك لـ OpenClaw** ولا يستخدم الموجه الافتراضي الخاص بـ pi-coding-agent.
يتم تجميع المطالبة بواسطة OpenClaw وحقنها في كل تشغيل وكيل.
يتم تجميع الموجه بواسطة OpenClaw وحقنه في كل تشغيل وكيل.
يمكن لإضافات الموفر المساهمة بإرشادات مطالبة تراعي التخزين المؤقت دون استبدال
مطالبة OpenClaw الكاملة المملوكة له. يمكن لوقت تشغيل الموفر أن:
يمكن لإضافات الموفر المساهمة بإرشادات موجه تراعي الذاكرة المؤقتة دون استبدال
موجه OpenClaw الكامل المملوك له. يمكن لبيئة تشغيل الموفر القيام بما يلي:
- يستبدل مجموعة صغيرة من الأقسام الأساسية المسمّاة (`interaction_style`,
- استبدال مجموعة صغيرة من الأقسام الأساسية المسماة (`interaction_style`,
`tool_call_style`, `execution_bias`)
- يحقن **بادئة مستقرة** فوق حد التخزين المؤقت للمطالبة
- يحقن **لاحقة ديناميكية** أسفل حد التخزين المؤقت للمطالبة
- حقن **بادئة مستقرة** فوق حد الذاكرة المؤقتة للموجه
- حقن **لاحقة ديناميكية** أسفل حد الذاكرة المؤقتة للموجه
استخدم المساهمات المملوكة للموفر من أجل الضبط الخاص بعائلات النماذج. أبقِ
تعديل المطالبة القديم `before_prompt_build` للتوافق أو لتغييرات المطالبة
العالمية فعلًا، وليس لسلوك الموفر العادي.
استخدم المساهمات المملوكة للموفر من أجل الضبط الخاص بعائلة النموذج. أبقِ
التعديل القديم للموجه عبر `before_prompt_build` من أجل التوافق أو تغييرات
الموجه العامة فعلًا، وليس لسلوك الموفر المعتاد.
## البنية
المطالبة مضغوطة عمدًا وتستخدم أقسامًا ثابتة:
الموجه مضغوط عمدًا ويستخدم أقسامًا ثابتة:
- **الأدوات**: تذكير بمصدر الحقيقة للأدوات المهيكلة بالإضافة إلى إرشادات وقت التشغيل لاستخدام الأدوات.
- **السلامة**: تذكير قصير بالضوابط لتجنب السلوك الساعي إلى السلطة أو تجاوز الإشراف.
- **Skills** (عند توفرها): يوضح للنموذج كيفية تحميل تعليمات Skill عند الطلب.
- **الأدوات**: تذكير بالمصدر المرجعي المنظم للأدوات بالإضافة إلى إرشادات وقت التشغيل لاستخدام الأدوات.
- **السلامة**: تذكير قصير بالضوابط لتجنب السلوك الساعي إلى القوة أو تجاوز الإشراف.
- **Skills** (عند توفرها): يوضح للنموذج كيفية تحميل تعليمات المهارات عند الطلب.
- **التحديث الذاتي لـ OpenClaw**: كيفية فحص الإعدادات بأمان باستخدام
`config.schema.lookup`، وترقيع الإعدادات باستخدام `config.patch`، واستبدال
الإعدادات كاملة باستخدام `config.apply`، وتشغيل `update.run` فقط عند طلب
صريح من المستخدم. كما أن أداة `gateway` المخصصة للمالك فقط ترفض أيضًا إعادة
`config.schema.lookup`، وتصحيح الإعدادات باستخدام `config.patch`، واستبدال
الإعدادات بالكامل باستخدام `config.apply`، وتشغيل `update.run` فقط عند طلب
المستخدم الصريح. كما أن أداة `gateway` المخصصة للمالك فقط ترفض أيضًا إعادة
كتابة `tools.exec.ask` / `tools.exec.security`، بما في ذلك الأسماء
المستعارة القديمة `tools.bash.*` التي تُطبَّع إلى مسارات التنفيذ المحمية هذه.
المستعارة القديمة `tools.bash.*` التي تُطبَّع إلى مسارات exec المحمية تلك.
- **مساحة العمل**: دليل العمل (`agents.defaults.workspace`).
- **التوثيق**: المسار المحلي إلى مستندات OpenClaw (المستودع أو حزمة npm) ومتى يجب قراءتها.
- **التوثيق**: المسار المحلي إلى وثائق OpenClaw (المستودع أو حزمة npm) ومتى يجب قراءتها.
- **ملفات مساحة العمل (محقونة)**: يشير إلى أن ملفات التهيئة الأولية مضمنة أدناه.
- **Sandbox** (عند التمكين): يشير إلى بيئة تشغيل معزولة، ومسارات العزل، وما إذا كان التنفيذ المرتفع الصلاحيات متاحًا.
- **Sandbox** (عند التمكين): يشير إلى بيئة تشغيل معزولة، ومسارات sandbox، وما إذا كان التنفيذ المرتفع الصلاحيات متاحًا.
- **التاريخ والوقت الحاليان**: الوقت المحلي للمستخدم، والمنطقة الزمنية، وتنسيق الوقت.
- **وسوم الرد**: صياغة اختيارية لوسوم الرد لموفري الخدمة المدعومين.
- **نبضات القلب**: مطالبة نبضات القلب وسلوك الإقرار، عندما تكون نبضات القلب مفعلة للوكيل الافتراضي.
- **وقت التشغيل**: المضيف، ونظام التشغيل، وNode، والنموذج، وجذر المستودع (عند اكتشافه)، ومستوى التفكير (سطر واحد).
- **الاستدلال**: مستوى الرؤية الحالي + تلميح تبديل `/reasoning`.
- **وسوم الرد**: صياغة وسوم الرد الاختيارية للموفرين المدعومين.
- **Heartbeats**: موجه Heartbeat وسلوك الإقرار، عندما تكون Heartbeats مفعلة للوكيل الافتراضي.
- **وقت التشغيل**: المضيف، ونظام التشغيل، وnode، والنموذج، وجذر المستودع (عند اكتشافه)، ومستوى التفكير (سطر واحد).
- **الاستدلال**: مستوى الرؤية الحالي + تلميح تبديل /reasoning.
يتضمن قسم الأدوات أيضًا إرشادات وقت التشغيل للأعمال طويلة التشغيل:
- استخدم cron للمتابعة المستقبلية (`تحقق لاحقًا`، والتذكيرات، والعمل المتكرر)
بدلًا من حلقات النوم في `exec`، أو حيل التأخير `yieldMs`، أو الاستطلاع
- استخدم Cron للمتابعة المستقبلية (`check back later`، والتذكيرات، والأعمال المتكررة)
بدلًا من حلقات السكون عبر `exec`، أو حيل التأخير `yieldMs`، أو الاستطلاع
المتكرر لـ `process`
- استخدم `exec` / `process` فقط للأوامر التي تبدأ الآن وتستمر في العمل في
الخلفية
- عندما تكون خاصية التنبيه التلقائي عند الاكتمال مفعلة، ابدأ الأمر مرة واحدة
واعتمد على مسار التنبيه القائم على الدفع عندما يُخرج ناتجًا أو يفشل
- استخدم `process` للسجلات أو الحالة أو الإدخال أو التدخل عندما تحتاج إلى
- عند تمكين التنبيه التلقائي عند الاكتمال، ابدأ الأمر مرة واحدة ثم اعتمد على
مسار التنبيه المعتمد على الدفع عندما يصدر مخرجات أو يفشل
- استخدم `process` للسجلات، أو الحالة، أو الإدخال، أو التدخل عندما تحتاج إلى
فحص أمر قيد التشغيل
- إذا كانت المهمة أكبر، ففضّل `sessions_spawn`؛ إذ إن اكتمال الوكيل الفرعي
قائم على الدفع ويُعلن تلقائيًا للطالب
- لا تستطلع `subagents list` / `sessions_list` في حلقة لمجرد انتظار
- إذا كانت المهمة أكبر، ففضّل `sessions_spawn`; يكتمل الوكيل الفرعي بأسلوب
قائم على الدفع ويعلن تلقائيًا الرجوع إلى الطالب
- لا تستطلع `subagents list` / `sessions_list` في حلقة فقط لانتظار
الاكتمال
عندما تكون أداة `update_plan` التجريبية مفعلة، يوضح قسم الأدوات أيضًا
للنموذج أن يستخدمها فقط للأعمال متعددة الخطوات غير البسيطة، وأن يبقي خطوة
واحدة فقط بحالة `in_progress`، وأن يتجنب تكرار الخطة كاملة بعد كل تحديث.
عند تمكين الأداة التجريبية `update_plan`، يوضح قسم الأدوات أيضًا للنموذج أن
يستخدمها فقط للأعمال غير التافهة متعددة الخطوات، وأن يُبقي خطوة واحدة فقط
`in_progress`، وأن يتجنب تكرار الخطة كاملة بعد كل تحديث.
ضوابط السلامة في مطالبة النظام إرشادية. فهي توجه سلوك النموذج لكنها لا تفرض
السياسة. استخدم سياسة الأدوات، وموافقات التنفيذ، والعزل، وقوائم سماح القنوات
للفرض الصارم؛ إذ يمكن للمشغلين تعطيل هذه الأمور عن قصد.
ضوابط السلامة في موجه النظام إرشادية. فهي توجه سلوك النموذج لكنها لا تفرض سياسة. استخدم سياسة الأدوات، وموافقات exec، وsandboxing، وقوائم السماح الخاصة بالقنوات من أجل الفرض الصارم؛ ويمكن للمشغلين تعطيل هذه الأمور عمدًا.
في القنوات التي تحتوي على بطاقات/أزرار موافقة أصلية، توضح مطالبة وقت التشغيل
الآن للوكيل أن يعتمد أولًا على واجهة الموافقة الأصلية تلك. ويجب ألا يتضمن أمر
`/approve` يدويًا إلا عندما تشير نتيجة الأداة إلى أن موافقات الدردشة غير
في القنوات التي تحتوي على بطاقات/أزرار موافقة أصلية، يوجه موجه وقت التشغيل الآن
الوكيل إلى الاعتماد أولًا على واجهة الموافقة الأصلية هذه. ولا ينبغي أن يتضمن
أمر `/approve` يدويًا إلا عندما تشير نتيجة الأداة إلى أن موافقات الدردشة غير
متاحة أو أن الموافقة اليدوية هي المسار الوحيد.
## أوضاع المطالبة
## أوضاع الموجه
يمكن لـ OpenClaw عرض مطالبات نظام أصغر للوكلاء الفرعيين. يضبط وقت التشغيل
يمكن لـ OpenClaw عرض موجهات نظام أصغر للوكلاء الفرعيين. يحدد وقت التشغيل
`promptMode` لكل تشغيل (وليس إعدادًا ظاهرًا للمستخدم):
- `full` (الافتراضي): يتضمن جميع الأقسام أعلاه.
- `minimal`: يُستخدم للوكلاء الفرعيين؛ ويحذف **Skills** و**استدعاء الذاكرة** و**التحديث الذاتي لـ OpenClaw** و**أسماء النماذج المستعارة** و**هوية المستخدم** و**وسوم الرد** و**المراسلة** و**الردود الصامتة** و**نبضات القلب**. تظل الأدوات و**السلامة** ومساحة العمل وSandbox والتاريخ والوقت الحاليان (عند توفرهما) ووقت التشغيل والسياق المحقون متاحة.
- `none`: يعيد فقط سطر الهوية الأساسي.
- `full` (افتراضي): يتضمن جميع الأقسام أعلاه.
- `minimal`: يُستخدم للوكلاء الفرعيين؛ ويحذف **Skills**، و**استدعاء الذاكرة**، و**التحديث الذاتي لـ OpenClaw**، و**أسماء النماذج المستعارة**، و**هوية المستخدم**، و**وسوم الرد**،
و**المراسلة**، و**الردود الصامتة**، و**Heartbeats**. وتظل الأدوات، و**السلامة**،
ومساحة العمل، وSandbox، والتاريخ والوقت الحاليان (عند معرفتهما)، ووقت التشغيل، والسياق
المحقون متاحة.
- `none`: يعيد سطر الهوية الأساسي فقط.
عندما يكون `promptMode=minimal`، تُوسم المطالبات الإضافية المحقونة باسم **سياق الوكيل الفرعي** بدلًا من **سياق الدردشة الجماعية**.
عندما يكون `promptMode=minimal`، تُسمى الموجهات الإضافية المحقونة **سياق الوكيل
الفرعي** بدلًا من **سياق الدردشة الجماعية**.
## حقن تهيئة مساحة العمل الأولية
## حقن تهيئة مساحة العمل
تُقص ملفات التهيئة الأولية وتُلحق تحت **سياق المشروع** بحيث يرى النموذج
الهوية وسياق الملف الشخصي من دون الحاجة إلى قراءتها صراحةً:
تُقص ملفات التهيئة الأولية وتُلحق تحت **سياق المشروع** حتى يرى النموذج سياق الهوية والملف الشخصي دون الحاجة إلى قراءات صريحة:
- `AGENTS.md`
- `SOUL.md`
@ -108,70 +109,68 @@ x-i18n:
- `BOOTSTRAP.md` (فقط في مساحات العمل الجديدة تمامًا)
- `MEMORY.md` عند وجوده، وإلا `memory.md` كبديل بأحرف صغيرة
تُحقن جميع هذه الملفات **في نافذة السياق** في كل دور ما لم تنطبق بوابة خاصة
بملف معين. ويُحذف `HEARTBEAT.md` في التشغيلات العادية عندما تكون نبضات القلب
معطلة للوكيل الافتراضي أو عندما تكون
`agents.defaults.heartbeat.includeSystemPromptSection` مساوية لـ false. اجعل
الملفات المحقونة موجزة — وخاصة `MEMORY.md`، الذي قد ينمو بمرور الوقت ويؤدي إلى
استخدام سياق أعلى من المتوقع وإلى ضغط أكثر تكرارًا.
كل هذه الملفات **تُحقن داخل نافذة السياق** في كل دورة ما لم
تنطبق بوابة خاصة بالملف. يُحذف `HEARTBEAT.md` في التشغيلات العادية عندما تكون
Heartbeats معطلة للوكيل الافتراضي أو عندما يكون
`agents.defaults.heartbeat.includeSystemPromptSection` يساوي false. أبقِ الملفات
المحقونة موجزة — خاصة `MEMORY.md`، الذي يمكن أن ينمو مع الوقت ويؤدي إلى
استخدام سياق أعلى من المتوقع وCompaction أكثر تكرارًا.
> **ملاحظة:** ملفات `memory/*.md` اليومية **ليست** جزءًا من سياق مشروع
> التهيئة الأولية العادي. ففي الأدوار العادية يُصار إلى الوصول إليها عند
> الطلب عبر أداتي `memory_search` و`memory_get`، لذلك لا تُحتسب ضمن نافذة
> السياق ما لم يقرأها النموذج صراحةً. وتُعد أدوار `/new` و`/reset` المجردة
> الاستثناء: إذ يمكن لوقت التشغيل أن يسبق مؤخرات الذاكرة اليومية كسياق
> بدء لمرة واحدة لذلك الدور الأول.
> **ملاحظة:** ملفات `memory/*.md` اليومية **ليست** جزءًا من سياق المشروع
> الافتراضي للتهيئة الأولية. ففي الدورات العادية يتم الوصول إليها عند الطلب عبر
> أداتي `memory_search` و`memory_get`، لذلك لا تُحتسب ضمن نافذة السياق
> ما لم يقرأها النموذج صراحةً. وتمثل دورات `/new` و`/reset` المجردة
> الاستثناء: إذ يمكن لوقت التشغيل أن يسبق ذاكرة يومية حديثة
> ككتلة سياق بدء لمرة واحدة لتلك الدورة الأولى.
تُقتطع الملفات الكبيرة مع علامة. ويُتحكم في الحد الأقصى للحجم لكل ملف بواسطة
`agents.defaults.bootstrapMaxChars` (الافتراضي: 20000). كما يُحدد سقف لإجمالي
محتوى التهيئة الأولية المحقون عبر الملفات بواسطة
`agents.defaults.bootstrapTotalMaxChars` (الافتراضي: 150000). وتحقن الملفات
المفقودة علامة قصيرة تشير إلى فقدان الملف. وعند حدوث اقتطاع، يمكن لـ OpenClaw
حقن كتلة تحذير في سياق المشروع؛ تحكم في ذلك باستخدام
`agents.defaults.bootstrapPromptTruncationWarning` (`off` أو `once` أو `always`؛
والافتراضي: `once`).
تُقتطع الملفات الكبيرة مع علامة. ويُتحكم في الحد الأقصى لحجم كل ملف عبر
`agents.defaults.bootstrapMaxChars` (الافتراضي: 20000). كما أن إجمالي محتوى
التهيئة الأولية المحقون عبر الملفات مقيّد بواسطة
`agents.defaults.bootstrapTotalMaxChars`
(الافتراضي: 150000). وتحقن الملفات المفقودة علامة قصيرة تدل على فقدان الملف. وعند حدوث الاقتطاع،
يمكن لـ OpenClaw حقن كتلة تحذير في سياق المشروع؛ ويمكن التحكم في ذلك عبر
`agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`;
الافتراضي: `once`).
تقوم جلسات الوكيل الفرعي بحقن `AGENTS.md` و`TOOLS.md` فقط (وتُرشَّح ملفات
التهيئة الأولية الأخرى لإبقاء سياق الوكيل الفرعي صغيرًا).
جلسات الوكيل الفرعي تحقن فقط `AGENTS.md` و`TOOLS.md` (تُرشَّح ملفات التهيئة الأولية الأخرى
لإبقاء سياق الوكيل الفرعي صغيرًا).
يمكن للخطافات الداخلية اعتراض هذه الخطوة عبر `agent:bootstrap` لتعديل ملفات
التهيئة الأولية المحقونة أو استبدالها (على سبيل المثال استبدال `SOUL.md`
بشخصية بديلة).
يمكن للخطافات الداخلية اعتراض هذه الخطوة عبر `agent:bootstrap` لتعديل أو استبدال
ملفات التهيئة الأولية المحقونة (على سبيل المثال استبدال `SOUL.md` بشخصية بديلة).
إذا كنت تريد أن تجعل الوكيل يبدو أقل عمومية، فابدأ من
إذا كنت تريد جعل الوكيل يبدو أقل عمومية، فابدأ من
[دليل شخصية SOUL.md](/ar/concepts/soul).
لفحص مقدار مساهمة كل ملف محقون (الخام مقابل المحقون، والاقتطاع، إضافةً إلى
العبء الإضافي لمخطط الأداة)، استخدم `/context list` أو `/context detail`.
راجع [السياق](/ar/concepts/context).
لفحص مقدار مساهمة كل ملف محقون (الخام مقابل المحقون، والاقتطاع، بالإضافة إلى حمل مخطط الأداة)، استخدم `/context list` أو `/context detail`. راجع [السياق](/ar/concepts/context).
## التعامل مع الوقت
تتضمن مطالبة النظام قسم **التاريخ والوقت الحاليان** مخصصًا عندما تكون المنطقة
الزمنية للمستخدم معروفة. وللحفاظ على ثبات التخزين المؤقت للمطالبة، فهي تتضمن
الآن فقط **المنطقة الزمنية** (من دون ساعة ديناميكية أو تنسيق وقت).
يتضمن موجه النظام قسمًا مخصصًا بعنوان **التاريخ والوقت الحاليان** عندما تكون
المنطقة الزمنية للمستخدم معروفة. وللحفاظ على استقرار الذاكرة المؤقتة للموجه، فهو الآن
يتضمن فقط **المنطقة الزمنية** (من دون ساعة ديناميكية أو تنسيق وقت).
استخدم `session_status` عندما يحتاج الوكيل إلى الوقت الحالي؛ إذ تتضمن بطاقة
الحالة سطرًا للطابع الزمني. ويمكن للأداة نفسها أيضًا تعيين تجاوز نموذج لكل
جلسة اختياريًا (`model=default` يمسحه).
استخدم `session_status` عندما يحتاج الوكيل إلى الوقت الحالي؛
تتضمن بطاقة الحالة سطر طابع زمني. ويمكن للأداة نفسها أيضًا تعيين
تجاوز نموذج خاص بكل جلسة (`model=default` يمسحه).
اضبط ذلك باستخدام:
- `agents.defaults.userTimezone`
- `agents.defaults.timeFormat` (`auto` | `12` | `24`)
راجع [التاريخ والوقت](/ar/date-time) للاطلاع على التفاصيل الكاملة للسلوك.
راجع [التاريخ والوقت](/ar/date-time) للحصول على التفاصيل الكاملة للسلوك.
## Skills
عندما تكون هناك Skills مؤهلة، يحقن OpenClaw **قائمة Skills متاحة** مضغوطة
(`formatSkillsForPrompt`) تتضمن **مسار الملف** لكل Skill. وتوجه المطالبة
النموذج إلى استخدام `read` لتحميل SKILL.md من الموقع المدرج (مساحة العمل، أو
المدار، أو المضمن). وإذا لم تكن هناك Skills مؤهلة، فيُحذف قسم Skills.
(`formatSkillsForPrompt`) تتضمن **مسار الملف** لكل Skill. وتوجّه
الموجه النموذج لاستخدام `read` لتحميل ملف SKILL.md في الموقع المدرج
(مساحة العمل، أو المُدار، أو المضمّن). وإذا لم توجد Skills مؤهلة، فيُحذف قسم
Skills.
تشمل الأهلية بوابات بيانات Skill الوصفية، وفحوصات بيئة/إعدادات وقت التشغيل،
وقائمة السماح الفعلية لـ Skills الخاصة بالوكيل عندما تكون
`agents.defaults.skills` أو `agents.list[].skills` مضبوطة.
تشمل الأهلية بوابات بيانات تعريف Skill، وفحوصات بيئة التشغيل/الإعدادات،
وقائمة السماح الفعلية لمهارات الوكيل عند ضبط `agents.defaults.skills` أو
`agents.list[].skills`.
```
<available_skills>
@ -183,14 +182,26 @@ x-i18n:
</available_skills>
```
يحافظ هذا على صغر حجم المطالبة الأساسية مع الاستمرار في تمكين استخدام Skills
المستهدف.
يبقي هذا الموجه الأساسي صغيرًا مع الاستمرار في تمكين استخدام Skills المستهدفة.
تعود ملكية ميزانية قائمة Skills إلى نظام Skills الفرعي:
- الافتراضي العام: `skills.limits.maxSkillsPromptChars`
- تجاوز لكل وكيل: `agents.list[].skillsLimits.maxSkillsPromptChars`
تستخدم المقاطع المحدودة العامة لوقت التشغيل سطحًا مختلفًا:
- `agents.defaults.contextLimits.*`
- `agents.list[].contextLimits.*`
يبقي هذا الفصل تحديد حجم Skills منفصلًا عن تحديد حجم القراءة/الحقن في وقت التشغيل مثل
`memory_get`، ونتائج الأدوات الحية، وتحديثات AGENTS.md بعد Compaction.
## التوثيق
عند توفره، تتضمن مطالبة النظام قسم **التوثيق** الذي يشير إلى
دليل مستندات OpenClaw المحلي (إما `docs/` في مساحة عمل المستودع أو مستندات
حزمة npm المضمنة)، ويذكر أيضًا النسخة العامة المعكوسة، والمستودع المصدري،
ومجتمع Discord، وClawHub ([https://clawhub.ai](https://clawhub.ai)) لاكتشاف Skills. وتوجه المطالبة النموذج إلى الرجوع إلى المستندات المحلية أولًا
لسلوك OpenClaw أو الأوامر أو الإعدادات أو البنية، وإلى تشغيل
`openclaw status` بنفسه عند الإمكان (ولا يسأل المستخدم إلا عندما يفتقر إلى الوصول).
عند توفره، يتضمن موجه النظام قسم **التوثيق** الذي يشير إلى
دليل وثائق OpenClaw المحلي (إما `docs/` في مساحة عمل المستودع أو وثائق حزمة npm
المضمنة)، كما يذكر أيضًا النسخة العامة المطابقة، ومستودع المصدر، وDiscord المجتمع،
وClawHub ([https://clawhub.ai](https://clawhub.ai)) لاكتشاف Skills. ويوجه الموجه النموذج إلى الرجوع إلى
الوثائق المحلية أولًا فيما يخص سلوك OpenClaw، أو الأوامر، أو الإعدادات، أو
البنية، وأن يشغّل `openclaw status` بنفسه عندما يكون ذلك ممكنًا (ولا يسأل المستخدم إلا عند عدم توفر الوصول).

1884
docs/ar/gateway/configuration-reference.md
View File

File diff suppressed because it is too large Load Diff

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

@ -2,29 +2,29 @@
read_when:
- أنت تبني Plugin جديدًا لقناة مراسلة
- تريد ربط OpenClaw بمنصة مراسلة
- تحتاج إلى فهم واجهة المهايئ `ChannelPlugin`
- تحتاج إلى فهم واجهة المهايئ ChannelPlugin
sidebarTitle: Channel Plugins
summary: دليل خطوة بخطوة لبناء Plugin لقناة مراسلة لـ OpenClaw
title: بناء Plugins القنوات
title: بناء Plugins للقنوات
x-i18n:
generated_at: "2026-04-15T07:17:51Z"
generated_at: "2026-04-15T19:41:41Z"
model: gpt-5.4
provider: openai
source_hash: a7f4c746fe3163a8880e14c433f4db4a1475535d91716a53fb879551d8d62f65
source_hash: 80e47e61d1e47738361692522b79aff276544446c58a7b41afe5296635dfad4b
source_path: plugins/sdk-channel-plugins.md
workflow: 15
---
# بناء Plugins القنوات
# بناء Plugins للقنوات
يشرح هذا الدليل كيفية بناء Plugin قناة يربط OpenClaw بمنصة
مراسلة. وبنهاية هذا الدليل سيكون لديك قناة عاملة تتضمن أمان الرسائل
المباشرة، والاقتران، وتوجيه الردود ضمن السلاسل، والرسائل الصادرة.
يوضح هذا الدليل كيفية بناء Plugin لقناة يربط OpenClaw بمنصة
مراسلة. بنهاية هذا الدليل، سيكون لديك قناة عاملة تتضمن أمان الرسائل
المباشرة، والاقتران، وتسلسل الردود، والمراسلة الصادرة.
<Info>
إذا لم تكن قد أنشأت أي Plugin لـ OpenClaw من قبل، فاقرأ
[البدء](/ar/plugins/building-plugins) أولًا لمعرفة بنية الحزمة
الأساسية وإعداد ملف البيان.
إذا لم تكن قد بنيت أي Plugin لـ OpenClaw من قبل، فاقرأ
[البدء](/ar/plugins/building-plugins) أولًا للتعرّف على بنية
الحزمة الأساسية وإعداد ملف البيان.
</Info>
## كيف تعمل Plugins القنوات
@ -35,80 +35,82 @@ x-i18n:
- **الإعداد** — حلّ الحسابات ومعالج الإعداد
- **الأمان** — سياسة الرسائل المباشرة وقوائم السماح
- **الاقتران** — تدفق الموافقة على الرسائل المباشرة
- **صياغة الجلسة** — كيفية ربط معرّفات المحادثات الخاصة بالموفّر بالمحادثات الأساسية ومعرّفات السلاسل وبدائل الأصل
- **الإرسال الصادر** — إرسال النصوص والوسائط والاستطلاعات إلى المنصة
- **التسلسل** — كيفية ترتيب الردود ضمن السلاسل
- **بنية الجلسة** — كيفية تعيين معرّفات المحادثات الخاصة بالموفّر إلى الدردشات الأساسية، ومعرّفات السلاسل، وبدائل الأصل
- **الصادر** — إرسال النصوص والوسائط والاستطلاعات إلى المنصة
- **التسلسل** — كيفية تنظيم الردود ضمن سلاسل
تتولى النواة أداة الرسائل المشتركة، وربط الـ prompt، والشكل الخارجي لمفتاح
الجلسة، وتتبع `:thread:` العام، والإرسال.
تتولى النواة أداة الرسائل المشتركة، وتوصيل المطالبات، وشكل مفتاح الجلسة
الخارجي، وآلية `:thread:` العامة، والتوجيه.
إذا كانت قناتك تضيف معاملات إلى أداة الرسائل تحمل مصادر وسائط، فاكشف عن أسماء
هذه المعاملات عبر `describeMessageTool(...).mediaSourceParams`. تستخدم النواة
هذه القائمة الصريحة لتطبيع مسارات sandbox ولسياسة الوصول إلى الوسائط الصادرة،
لذلك لا تحتاج Plugins إلى حالات خاصة في النواة المشتركة لمعاملات الصور الرمزية
أو المرفقات أو صور الغلاف الخاصة بموفّر معيّن.
ويُفضّل إرجاع خريطة مفاتيحها مبنية على الإجراء مثل
إذا كانت قناتك تضيف معاملات إلى أداة الرسائل تحمل مصادر وسائط، فاكشف عن
أسماء هذه المعاملات عبر `describeMessageTool(...).mediaSourceParams`. تستخدم
النواة هذه القائمة الصريحة لتطبيع مسارات sandbox وسياسة الوصول إلى الوسائط
الصادرة، لذلك لا تحتاج Plugins إلى حالات خاصة مشتركة في النواة لمعلمات
الصورة الرمزية أو المرفقات أو صورة الغلاف الخاصة بموفّرين محددين.
يُفضَّل إرجاع خريطة مرتبطة بالإجراءات مثل
`{ "set-profile": ["avatarUrl", "avatarPath"] }` حتى لا ترث الإجراءات غير
ذات الصلة معاملات الوسائط الخاصة بإجراء آخر. ولا يزال المصفوفة المسطحة تعمل مع
المعاملات التي يُقصد مشاركتها عمدًا عبر كل إجراء مكشوف.
ذات الصلة معاملات الوسائط الخاصة بإجراء آخر. ولا يزال استخدام مصفوفة
مسطحة يعمل مع المعاملات التي يُقصَد مشاركتها عمدًا عبر كل إجراء مكشوف.
إذا كانت منصتك تخزّن نطاقًا إضافيًا داخل معرّفات المحادثة، فأبقِ هذا التحليل
داخل Plugin باستخدام `messaging.resolveSessionConversation(...)`. هذا هو
الخطاف المعتمد لربط `rawId` بمعرّف المحادثة الأساسي، ومعرّف السلسلة الاختياري،
و`baseConversationId` الصريح، وأي `parentConversationCandidates`.
وعندما تُرجع `parentConversationCandidates`، فاحرص على إبقائها مرتبة من
الأصل الأضيق إلى الأصل الأوسع/المحادثة الأساسية.
إذا كانت منصتك تخزّن نطاقًا إضافيًا داخل معرّفات المحادثات، فأبقِ هذا
التحليل داخل Plugin باستخدام `messaging.resolveSessionConversation(...)`.
هذا هو الخطاف القياسي لتعيين `rawId` إلى معرّف المحادثة الأساسي، ومعرّف
السلسلة الاختياري، و`baseConversationId` الصريح، وأي
`parentConversationCandidates`.
وعند إرجاع `parentConversationCandidates`، احرص على ترتيبها من الأصل الأكثر
تحديدًا إلى الأصل الأوسع/المحادثة الأساسية.
يمكن أيضًا لـ Plugins المضمّنة التي تحتاج إلى التحليل نفسه قبل تشغيل سجل
يمكن أيضًا لـ Plugins المضمّنة التي تحتاج إلى التحليل نفسه قبل إقلاع سجل
القنوات أن تكشف عن ملف `session-key-api.ts` على المستوى الأعلى مع
تصدير مطابق لـ `resolveSessionConversation(...)`. تستخدم النواة هذا السطح
الآمن أثناء الإقلاع فقط عندما لا يكون سجل Plugins وقت التشغيل متاحًا بعد.
الآمن لمرحلة الإقلاع فقط عندما لا يكون سجل Plugins وقت التشغيل متاحًا بعد.
لا يزال `messaging.resolveParentConversationCandidates(...)` متاحًا كبديل
توافقي قديم عندما يحتاج Plugin فقط إلى بدائل الأصل فوق المعرّف العام/الخام.
يبقى `messaging.resolveParentConversationCandidates(...)` متاحًا كبديل
توافقي قديم عندما يحتاج Plugin فقط إلى بدائل الأصل فوق المعرّف الخام/العام.
إذا وُجد الخطافان معًا، تستخدم النواة
`resolveSessionConversation(...).parentConversationCandidates` أولًا ولا
تعود إلى `resolveParentConversationCandidates(...)` إلا عندما يهمل الخطاف
المعتمد إرجاعها.
`resolveSessionConversation(...).parentConversationCandidates` أولًا، ثم
تعود إلى `resolveParentConversationCandidates(...)` فقط عندما يتجاهل
الخطاف القياسي إرجاعها.
## الموافقات وإمكانات القناة
## الموافقات وإمكانات القنوات
لا تحتاج معظم Plugins القنوات إلى كود خاص بالموافقات.
معظم Plugins القنوات لا تحتاج إلى شيفرة خاصة بالموافقات.
- تتولى النواة `/approve` داخل المحادثة نفسها، وحمولات أزرار الموافقة المشتركة، وآلية التسليم العامة البديلة.
- يُفضَّل استخدام كائن `approvalCapability` واحد على Plugin القناة عندما تحتاج القناة إلى سلوك خاص بالموافقة.
- تمت إزالة `ChannelPlugin.approvals`. ضع حقائق تسليم/أصلية/عرض/مصادقة الموافقة على `approvalCapability`.
- تتولى النواة `/approve` داخل المحادثة نفسها، وحمولات أزرار الموافقة المشتركة، والتسليم الاحتياطي العام.
- فضّل استخدام كائن `approvalCapability` واحد على Plugin القناة عندما تحتاج القناة إلى سلوك خاص بالموافقة.
- أُزيل `ChannelPlugin.approvals`. ضع حقائق تسليم/أصلي/عرض/مصادقة الموافقة ضمن `approvalCapability`.
- يقتصر `plugin.auth` على login/logout فقط؛ لم تعد النواة تقرأ خطافات مصادقة الموافقة من هذا الكائن.
- يُعد `approvalCapability.authorizeActorAction` و`approvalCapability.getActionAvailabilityState` الواجهة المعتمدة لمصادقة الموافقات.
- يُعدّ `approvalCapability.authorizeActorAction` و`approvalCapability.getActionAvailabilityState` الواجهة القياسية لمصادقة الموافقات.
- استخدم `approvalCapability.getActionAvailabilityState` لإتاحة مصادقة الموافقة داخل المحادثة نفسها.
- إذا كانت قناتك تكشف عن موافقات تنفيذ أصلية، فاستخدم `approvalCapability.getExecInitiatingSurfaceState` لحالة سطح البدء/العميل الأصلي عندما تختلف عن مصادقة الموافقة داخل المحادثة نفسها. تستخدم النواة هذا الخطاف الخاص بالتنفيذ للتمييز بين `enabled` و`disabled`، وتحديد ما إذا كانت القناة الداعية تدعم موافقات التنفيذ الأصلية، وإدراج القناة في إرشادات الرجوع إلى العميل الأصلي. يقوم `createApproverRestrictedNativeApprovalCapability(...)` بملء ذلك في الحالة الشائعة.
- إذا كانت قناتك تكشف عن موافقات exec أصلية، فاستخدم `approvalCapability.getExecInitiatingSurfaceState` لحالة سطح البدء/العميل الأصلي عندما تختلف عن مصادقة الموافقة داخل المحادثة نفسها. تستخدم النواة هذا الخطاف الخاص بـ exec للتمييز بين `enabled` و`disabled`، وتحديد ما إذا كانت قناة البدء تدعم موافقات exec الأصلية، وإدراج القناة في إرشادات الرجوع إلى العميل الأصلي. يملأ `createApproverRestrictedNativeApprovalCapability(...)` هذا الجزء للحالة الشائعة.
- استخدم `outbound.shouldSuppressLocalPayloadPrompt` أو `outbound.beforeDeliverPayload` لسلوك دورة حياة الحمولة الخاص بالقناة، مثل إخفاء مطالبات الموافقة المحلية المكررة أو إرسال مؤشرات الكتابة قبل التسليم.
- استخدم `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` — خطافات اختيارية لربط/فصل/مسح الإجراءات للأزرار أو التفاعلات الأصلية
- استخدم `approvalCapability.delivery` فقط لتوجيه الموافقة الأصلي أو منع الرجوع الاحتياطي.
- استخدم `approvalCapability.nativeRuntime` للحقائق الأصلية الخاصة بالموافقة التي تملكها القناة. أبقه كسول التحميل في نقاط دخول القنوات الساخنة باستخدام `createLazyChannelApprovalNativeRuntimeAdapter(...)`، والذي يمكنه استيراد وحدة وقت التشغيل عند الطلب مع السماح للنواة بتجميع دورة حياة الموافقة.
- استخدم `approvalCapability.render` فقط عندما تحتاج القناة فعلًا إلى حمولات موافقة مخصصة بدلًا من العارض المشترك.
- استخدم `approvalCapability.describeExecApprovalSetup` عندما تريد القناة أن يشرح رد المسار المعطّل مقابض الإعداد الدقيقة اللازمة لتمكين موافقات exec الأصلية. يستقبل الخطاف `{ 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
اعتمادًا على حالة محلية خاصة بالقناة.
- يمكن لأنواع الموافقة المختلفة أن تكشف عمدًا عن أسطح أصلية مختلفة.
- إذا كانت القناة تحتاج إلى كائنات مملوكة لوقت التشغيل مثل عميل أو رمز مميّز أو تطبيق Bolt أو مستقبل Webhook، فسجّلها من خلال `openclaw/plugin-sdk/channel-runtime-context`. يتيح سجل runtime-context العام للنواة إقلاع معالجات مدفوعة بالإمكانات من حالة بدء تشغيل القناة دون إضافة غراء تغليف خاص بالموافقة.
- لا تلجأ إلى `createChannelApprovalHandler` أو `createChannelNativeApprovalRuntime` منخفضي المستوى إلا عندما لا تكون الواجهة المدفوعة بالإمكانات معبّرة بما يكفي بعد.
- يجب أن تمرّر قنوات الموافقة الأصلية كِلا `accountId` و`approvalKind` عبر هذه المساعدات. يُبقي `accountId` سياسة الموافقة متعددة الحسابات ضمن نطاق حساب البوت الصحيح، ويُبقي `approvalKind` سلوك exec مقابل موافقة Plugin متاحًا للقناة دون تفرعات مشفّرة مسبقًا في النواة.
- تتولى النواة الآن أيضًا إشعارات إعادة توجيه الموافقات. يجب ألا ترسل Plugins القنوات رسائل متابعة خاصة بها من نوع "تم إرسال الموافقة إلى الرسائل المباشرة / قناة أخرى" من `createChannelNativeApprovalRuntime`; وبدلًا من ذلك، اكشف عن توجيه دقيق للأصل + الرسائل المباشرة للموافق عبر مساعدات إمكانات الموافقة المشتركة، ودع النواة تجمع عمليات التسليم الفعلية قبل نشر أي إشعار مرة أخرى إلى محادثة البدء.
- حافظ على نوع معرّف الموافقة الذي تم تسليمه من البداية إلى النهاية. يجب ألا
تخمّن العملاء الأصلية أو تعيد كتابة توجيه موافقة exec مقابل Plugin من حالة
محلية خاصة بالقناة.
- يمكن لأنواع الموافقات المختلفة عمدًا أن تكشف عن أسطح أصلية مختلفة.
الأمثلة المضمّنة الحالية:
- يُبقي Slack توجيه الموافقات الأصلية متاحًا لكلٍّ من معرّفات موافقة التنفيذ وموافقة Plugin.
- يُبقي Matrix توجيه الرسائل المباشرة/القناة الأصلي نفسه وتجربة UX نفسها القائمة على التفاعل لكلٍّ من موافقات التنفيذ وموافقات Plugin، مع الاستمرار في السماح باختلاف المصادقة حسب نوع الموافقة.
- لا يزال `createApproverRestrictedNativeApprovalAdapter` موجودًا كغلاف توافقي، لكن يجب أن يفضّل الكود الجديد باني الإمكانات وأن يكشف `approvalCapability` على Plugin.
- يحتفظ Slack بإتاحة توجيه الموافقة الأصلي لكل من معرّفات exec وPlugin.
- يحتفظ Matrix بالتوجيه الأصلي نفسه للرسائل المباشرة/القناة وتجربة التفاعل لـ exec
وموافقات Plugin، مع الاستمرار في السماح لاختلاف المصادقة حسب نوع الموافقة.
- لا يزال `createApproverRestrictedNativeApprovalAdapter` موجودًا كغلاف توافقي، لكن الشيفرة الجديدة يجب أن تفضّل مُنشئ الإمكانات وتكشف عن `approvalCapability` على Plugin.
بالنسبة إلى نقاط دخول القنوات الساخنة، يُفضّل استخدام المسارات الفرعية الأضيق لوقت التشغيل عندما تحتاج فقط
إلى جزء واحد من هذه المجموعة:
لنقاط دخول القنوات الساخنة، فضّل المسارات الفرعية الأضيق لوقت التشغيل عندما
تحتاج فقط إلى جزء واحد من هذه المجموعة:
- `openclaw/plugin-sdk/approval-auth-runtime`
- `openclaw/plugin-sdk/approval-client-runtime`
@ -120,94 +122,93 @@ x-i18n:
- `openclaw/plugin-sdk/approval-reply-runtime`
- `openclaw/plugin-sdk/channel-runtime-context`
وبالمثل، يُفضّل `openclaw/plugin-sdk/setup-runtime`،
و`openclaw/plugin-sdk/setup-adapter-runtime`،
و`openclaw/plugin-sdk/reply-runtime`،
و`openclaw/plugin-sdk/reply-dispatch-runtime`،
وبالمثل، فضّل `openclaw/plugin-sdk/setup-runtime`,
و`openclaw/plugin-sdk/setup-adapter-runtime`,
و`openclaw/plugin-sdk/reply-runtime`,
و`openclaw/plugin-sdk/reply-dispatch-runtime`,
و`openclaw/plugin-sdk/reply-reference`، و
`openclaw/plugin-sdk/reply-chunking` عندما لا تحتاج إلى السطح الأشمل
ذي المظلة الأوسع.
`openclaw/plugin-sdk/reply-chunking` عندما لا تحتاج إلى السطح
الأوسع الشامل.
وبالنسبة إلى الإعداد تحديدًا:
وبالنسبة إلى الإعداد على وجه التحديد:
- يغطي `openclaw/plugin-sdk/setup-runtime` مساعدات الإعداد الآمنة لوقت التشغيل:
مهايئات ترقيع الإعداد الآمنة للاستيراد (`createPatchedAccountSetupAdapter`,
`createEnvPatchedAccountSetupAdapter`,
`createSetupInputPresenceValidator`)، ومخرجات
ملاحظات البحث، و`promptResolvedAllowFrom`، و`splitSetupEntries`، وبُناة
الوكيل المفوّض للإعداد
- يمثّل `openclaw/plugin-sdk/setup-adapter-runtime` الواجهة
الضيقة الواعية بالبيئة الخاصة بـ `createEnvPatchedAccountSetupAdapter`
- يغطي `openclaw/plugin-sdk/channel-setup` بُناة الإعداد
الخاصة بالتثبيت الاختياري بالإضافة إلى بعض الأساسيات الآمنة للإعداد:
`createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`,
ملاحظات البحث، و`promptResolvedAllowFrom`، و`splitSetupEntries`، ومنشئات
وكيل الإعداد المفوّض
- يُعد `openclaw/plugin-sdk/setup-adapter-runtime` الواجهة الضيقة الواعية بالبيئة
لـ `createEnvPatchedAccountSetupAdapter`
- يغطي `openclaw/plugin-sdk/channel-setup` منشئات الإعداد ذات التثبيت الاختياري
بالإضافة إلى بعض البدائيات الآمنة للإعداد:
`createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`،
إذا كانت قناتك تدعم إعدادًا أو مصادقة مدفوعَين بالبيئة وكان ينبغي أن تعرف
تدفقات الإقلاع/الإعداد العامة أسماء متغيرات البيئة هذه قبل تحميل وقت التشغيل،
فصرّح بها في ملف بيان Plugin عبر `channelEnvVars`. واحتفظ بـ
`envVars` الخاص بوقت تشغيل القناة أو الثوابت المحلية لنسخ النصوص الموجّهة
للمشغّل فقط.
إذا كانت قناتك تدعم إعدادًا أو مصادقة مدفوعين بالبيئة، وكان ينبغي أن تعرف
تدفقات البدء/الإعداد العامة أسماء متغيرات البيئة تلك قبل تحميل وقت التشغيل،
فصرّح عنها في ملف بيان Plugin باستخدام `channelEnvVars`. واحتفظ بمتغيرات
البيئة `envVars` وقت تشغيل القناة أو الثوابت المحلية فقط لنسخة النص
الموجّهة للمشغّل.
`createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`,
`createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`، و
`createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, و
`splitSetupEntries`
- استخدم واجهة `openclaw/plugin-sdk/setup` الأوسع فقط عندما تحتاج أيضًا إلى
مساعدات الإعداد/الضبط المشتركة الأثقل مثل
مساعدات الإعداد/التهيئة المشتركة الأثقل مثل
`moveSingleAccountChannelSectionToDefaultAccount(...)`
إذا كانت قناتك تريد فقط الإعلان عن "ثبّت هذا Plugin أولًا" في
أسطح الإعداد، ففضّل `createOptionalChannelSetupSurface(...)`. يفشل
المهايئ/المعالج المُنشأان بإغلاق آمن عند كتابة الإعدادات وعند الإنهاء،
ويعيدان استخدام رسالة "التثبيت مطلوب" نفسها عبر التحقق والإنهاء ونسخة
رابط التوثيق.
المهايئ/المعالج المُولَّدان بشكل مغلق عند عمليات كتابة الإعداد والإنهاء،
ويعيدان استخدام الرسالة نفسها التي تفيد بضرورة التثبيت عبر التحقق والإنهاء
ونص رابط الوثائق.
بالنسبة إلى مسارات القنوات الساخنة الأخرى، يُفضّل استخدام المساعدات الضيقة بدلًا من
الأسطح القديمة الأوسع:
وبالنسبة لمسارات القنوات الساخنة الأخرى، فضّل المساعدات الضيقة على الأسطح
القديمة الأوسع:
- `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` فقط عندما يكون تخطيط حقول
حمولة الوكيل/الوسائط القديم لا يزال مطلوبًا
- `openclaw/plugin-sdk/telegram-command-config` لتطبيع أوامر Telegram المخصصة،
والتحقق من التكرار/التعارض، وعقد إعداد الأوامر المستقر عند الرجوع الاحتياطي
يمكن لقنوات المصادقة فقط عادةً الاكتفاء بالمسار الافتراضي: تتولى النواة الموافقات ويكشف Plugin فقط عن إمكانات الإرسال الصادر/المصادقة. أما قنوات الموافقة الأصلية مثل Matrix وSlack وTelegram ووسائط الدردشة المخصصة، فيجب أن تستخدم المساعدات الأصلية المشتركة بدلًا من بناء دورة حياة الموافقة الخاصة بها.
يمكن للقنوات التي تعتمد على المصادقة فقط عادةً الاكتفاء بالمسار الافتراضي: تتولى النواة الموافقات، ويكشف Plugin فقط عن إمكانات الصادر/المصادقة. يجب على قنوات الموافقة الأصلية مثل Matrix وSlack وTelegram ووسائط نقل الدردشة المخصصة استخدام المساعدات الأصلية المشتركة بدلًا من بناء دورة حياة الموافقة الخاصة بها.
## سياسة الإشارة الواردة
## سياسة الإشارات الواردة
أبقِ معالجة الإشارات الواردة مقسّمة إلى طبقتين:
احرص على إبقاء معالجة الإشارات الواردة مقسّمة إلى طبقتين:
- جمع الأدلة الذي يملكه Plugin
- جمع الأدلة المملوك لـ Plugin
- تقييم السياسة المشتركة
استخدم `openclaw/plugin-sdk/channel-inbound` للطبقة المشتركة.
ملائم لمنطق Plugin المحلي:
ما يناسب المنطق المحلي في Plugin:
- اكتشاف الرد على البوت
- اكتشاف الاقتباس من البوت
- التحقق من المشاركة في السلسلة
- استبعاد رسائل الخدمة/النظام
- الذاكرات المؤقتة الأصلية الخاصة بالمنصة اللازمة لإثبات مشاركة البوت
- الذاكرات المؤقتة الأصلية للمنصة اللازمة لإثبات مشاركة البوت
ملائم للمساعد المشترك:
ما يناسب المساعد المشترك:
- `requireMention`
- نتيجة الإشارة الصريحة
- قائمة سماح الإشارة الضمنية
- قائمة السماح للإشارة الضمنية
- تجاوز الأوامر
- قرار التخطي النهائي
@ -215,7 +216,7 @@ x-i18n:
1. احسب حقائق الإشارة المحلية.
2. مرّر هذه الحقائق إلى `resolveInboundMentionDecision({ facts, policy })`.
3. استخدم `decision.effectiveWasMentioned` و`decision.shouldBypassMention` و`decision.shouldSkip` في بوابة الوارد لديك.
3. استخدم `decision.effectiveWasMentioned` و`decision.shouldBypassMention` و`decision.shouldSkip` في بوابة الوارد الخاصة بك.
```typescript
import {
@ -254,8 +255,8 @@ const decision = resolveInboundMentionDecision({
if (decision.shouldSkip) return;
```
يكشف `api.runtime.channel.mentions` عن مساعدات الإشارة المشتركة نفسها
لـ Plugins القنوات المضمّنة التي تعتمد بالفعل على حقن وقت التشغيل:
يكشف `api.runtime.channel.mentions` عن مساعدات الإشارة المشتركة نفسها من أجل
Plugins القنوات المضمّنة التي تعتمد بالفعل على حقن وقت التشغيل:
- `buildMentionRegexes`
- `matchesMentionPatterns`
@ -263,18 +264,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="الحزمة وملف البيان">
أنشئ ملفات Plugin القياسية. إن الحقل `channel` في `package.json` هو
ما يجعل هذا Plugin قناة. وللاطلاع على سطح بيانات الحزمة الكامل،
راجع [إعداد Plugin وضبطه](/ar/plugins/sdk-setup#openclaw-channel):
أنشئ ملفات Plugin القياسية. الحقل `channel` في `package.json` هو
ما يجعل هذا Plugin قناة. وللاطلاع على سطح بيانات وصف الحزمة الكامل،
راجع [إعداد Plugin والتهيئة](/ar/plugins/sdk-setup#openclaw-channel):
<CodeGroup>
```json package.json
@ -323,9 +324,9 @@ if (decision.shouldSkip) return;
</Step>
<Step title="أنشئ كائن Plugin القناة">
<Step title="بناء كائن Plugin للقناة">
تحتوي الواجهة `ChannelPlugin` على العديد من أسطح المهايئات الاختيارية. ابدأ
بالحد الأدنى — `id` و`setup` — ثم أضف المهايئات حسب الحاجة.
بالحد الأدنى — `id` و`setup` — ثم أضف المهايئات حسب حاجتك.
أنشئ `src/channel.ts`:
@ -335,7 +336,7 @@ if (decision.shouldSkip) return;
createChannelPluginBase,
} from "openclaw/plugin-sdk/channel-core";
import type { OpenClawConfig } from "openclaw/plugin-sdk/channel-core";
import { acmeChatApi } from "./client.js"; // your platform API client
import { acmeChatApi } from "./client.js"; // عميل API الخاص بمنصتك
type ResolvedAccount = {
accountId: string | null;
@ -376,7 +377,7 @@ if (decision.shouldSkip) return;
},
}),
// DM security: who can message the bot
// أمان الرسائل المباشرة: من يمكنه مراسلة البوت
security: {
dm: {
channelKey: "acme-chat",
@ -386,21 +387,21 @@ if (decision.shouldSkip) return;
},
},
// Pairing: approval flow for new DM contacts
// الاقتران: تدفق الموافقة لجهات الاتصال الجديدة في الرسائل المباشرة
pairing: {
text: {
idLabel: "Acme Chat username",
message: "Send this code to verify your identity:",
idLabel: "اسم مستخدم Acme Chat",
message: "أرسل هذا الرمز للتحقق من هويتك:",
notify: async ({ target, code }) => {
await acmeChatApi.sendDm(target, `Pairing code: ${code}`);
},
},
},
// Threading: how replies are delivered
// التسلسل: كيفية تسليم الردود
threading: { topLevelReplyToMode: "reply" },
// Outbound: send messages to the platform
// الصادر: إرسال الرسائل إلى المنصة
outbound: {
attachedResults: {
sendText: async (params) => {
@ -420,24 +421,24 @@ if (decision.shouldSkip) return;
});
```
<Accordion title="ما الذي يقدمه لك createChatChannelPlugin">
بدلًا من تنفيذ واجهات المهايئات منخفضة المستوى يدويًا، تمرّر
خيارات تصريحية ويتولى الباني تجميعها:
<Accordion title="ما الذي ينجزه `createChatChannelPlugin` لك">
بدلًا من تنفيذ واجهات المهايئات منخفضة المستوى يدويًا، فإنك تمرّر
خيارات تصريحية ويتولى المُنشئ تركيبها:
| Option | ما الذي يربطه |
| الخيار | ما الذي يوصله |
| --- | --- |
| `security.dm` | محلّل أمان الرسائل المباشرة المقيّد بنطاق حقول الإعداد |
| `pairing.text` | تدفق اقتران رسائل مباشرة قائم على النص مع تبادل الرموز |
| `threading` | محلّل نمط الرد (ثابت، مقيّد بالحساب، أو مخصص) |
| `outbound.attachedResults` | دوال إرسال تُرجع بيانات تعريفية للنتيجة (معرّفات الرسائل) |
| `security.dm` | محلّل أمان الرسائل المباشرة المقيّد بنطاق حقول التهيئة |
| `pairing.text` | تدفق اقتران رسائل مباشرة قائم على النص مع تبادل الرمز |
| `threading` | محلّل وضع الرد (ثابت أو مقيّد بالحساب أو مخصص) |
| `outbound.attachedResults` | دوال إرسال تُرجع بيانات وصفية للنتيجة (معرّفات الرسائل) |
يمكنك أيضًا تمرير كائنات مهايئ خام بدلًا من الخيارات التصريحية
إذا كنت تحتاج إلى تحكم كامل.
يمكنك أيضًا تمرير كائنات مهايئات خام بدلًا من الخيارات التصريحية
إذا كنت بحاجة إلى تحكم كامل.
</Accordion>
</Step>
<Step title="اربط نقطة الدخول">
<Step title="توصيل نقطة الإدخال">
أنشئ `index.ts`:
```typescript index.ts
@ -473,21 +474,21 @@ if (decision.shouldSkip) return;
});
```
ضع واصفات CLI التي تملكها القناة في `registerCliMetadata(...)` حتى يتمكن OpenClaw
من عرضها في المساعدة الجذرية من دون تفعيل وقت تشغيل القناة الكامل،
بينما تلتقط عمليات التحميل الكاملة العادية الواصفات نفسها لتسجيل
الأوامر الفعلي. وأبقِ `registerFull(...)` للأعمال الخاصة بوقت التشغيل فقط.
إذا كان `registerFull(...)` يسجّل أساليب Gateway RPC، فاستخدم
بادئة خاصة بالـ Plugin. تظل مساحات أسماء إدارة النواة (`config.*`,
`exec.approvals.*`, `wizard.*`, `update.*`) محجوزة وتُحل دائمًا
إلى `operator.admin`.
يتولى `defineChannelPluginEntry` معالجة تقسيم وضع التسجيل تلقائيًا. راجع
[نقاط الدخول](/ar/plugins/sdk-entrypoints#definechannelpluginentry) لمعرفة جميع
ضع واصفات CLI المملوكة للقناة في `registerCliMetadata(...)` حتى يتمكن OpenClaw
من عرضها في المساعدة الجذرية دون تفعيل وقت تشغيل القناة الكامل،
بينما تستمر التحميلات الكاملة العادية في التقاط الواصفات نفسها لتسجيل
الأوامر الفعلي. أبقِ `registerFull(...)` للأعمال الخاصة بوقت التشغيل فقط.
وإذا كان `registerFull(...)` يسجّل أساليب Gateway RPC، فاستخدم
بادئة خاصة بـ Plugin. تبقى مساحات أسماء الإدارة في النواة (`config.*`,
و`exec.approvals.*`، و`wizard.*`، و`update.*`) محجوزة وتُحل دائمًا إلى
`operator.admin`.
يتولى `defineChannelPluginEntry` معالجة فصل أوضاع التسجيل تلقائيًا. راجع
[نقاط الإدخال](/ar/plugins/sdk-entrypoints#definechannelpluginentry) لجميع
الخيارات.
</Step>
<Step title="أضف نقطة دخول للإعداد">
<Step title="إضافة نقطة إدخال للإعداد">
أنشئ `setup-entry.ts` للتحميل الخفيف أثناء الإعداد الأولي:
```typescript setup-entry.ts
@ -497,28 +498,33 @@ if (decision.shouldSkip) return;
export default defineSetupPluginEntry(acmeChatPlugin);
```
يحمّل OpenClaw هذا بدلًا من نقطة الدخول الكاملة عندما تكون القناة معطّلة
أو غير مهيأة. وهذا يتجنب سحب كود وقت تشغيل ثقيل أثناء تدفقات الإعداد.
راجع [الإعداد والضبط](/ar/plugins/sdk-setup#setup-entry) لمعرفة التفاصيل.
يحمّل OpenClaw هذا بدلًا من نقطة الإدخال الكاملة عندما تكون القناة معطّلة
أو غير مهيأة. وهذا يتجنب سحب شيفرة وقت تشغيل ثقيلة أثناء تدفقات الإعداد.
راجع [الإعداد والتهيئة](/ar/plugins/sdk-setup#setup-entry) لمزيد من التفاصيل.
يمكن لقنوات مساحة العمل المضمّنة التي تفصل التصديرات الآمنة للإعداد في
وحدات جانبية أن تستخدم `defineBundledChannelSetupEntry(...)` من
`openclaw/plugin-sdk/channel-entry-contract` عندما تحتاج أيضًا إلى
مُعيّن صريح لوقت التشغيل في وقت الإعداد.
</Step>
<Step title="عالج الرسائل الواردة">
يحتاج Plugin الخاص بك إلى استلام الرسائل من المنصة وتمريرها إلى
OpenClaw. النمط الشائع هو Webhook يتحقق من الطلب ثم
يرسله عبر معالج الوارد الخاص بقناتك:
<Step title="معالجة الرسائل الواردة">
يحتاج Plugin الخاص بك إلى تلقي الرسائل من المنصة وتمريرها إلى
OpenClaw. النمط المعتاد هو Webhook يتحقق من الطلب ويقوم
بإرساله عبر معالج الوارد الخاص بقناتك:
```typescript
registerFull(api) {
api.registerHttpRoute({
path: "/acme-chat/webhook",
auth: "plugin", // plugin-managed auth (verify signatures yourself)
auth: "plugin", // مصادقة يديرها Plugin (تحقق من التواقيع بنفسك)
handler: async (req, res) => {
const event = parseWebhookPayload(req);
// Your inbound handler dispatches the message to OpenClaw.
// The exact wiring depends on your platform SDK —
// see a real example in the bundled Microsoft Teams or Google Chat plugin package.
// يقوم معالج الوارد الخاص بك بإرسال الرسالة إلى OpenClaw.
// يعتمد التوصيل الدقيق على SDK الخاص بمنصتك —
// راجع مثالًا حقيقيًا في حزمة Plugin المضمّنة الخاصة بـ Microsoft Teams أو Google Chat.
await handleAcmeChatInbound(api, event);
res.statusCode = 200;
@ -531,15 +537,15 @@ if (decision.shouldSkip) return;
<Note>
معالجة الرسائل الواردة خاصة بكل قناة. كل Plugin قناة يملك
خط أنبوب الوارد الخاص به. انظر إلى Plugins القنوات المضمّنة
(مثل حزمة Plugin الخاصة بـ Microsoft Teams أو Google Chat) للاطلاع على أنماط فعلية.
مسار الوارد الخاص به. انظر إلى 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";
@ -577,7 +583,7 @@ if (decision.shouldSkip) return;
pnpm test -- <bundled-plugin-root>/acme-chat/
```
للاطلاع على مساعدات الاختبار المشتركة، راجع [الاختبار](/ar/plugins/sdk-testing).
بالنسبة إلى مساعدات الاختبار المشتركة، راجع [الاختبار](/ar/plugins/sdk-testing).
</Step>
</Steps>
@ -587,7 +593,7 @@ if (decision.shouldSkip) return;
```
<bundled-plugin-root>/acme-chat/
├── package.json # بيانات openclaw.channel الوصفية
├── openclaw.plugin.json # ملف البيان مع مخطط الإعداد
├── openclaw.plugin.json # ملف البيان مع مخطط التهيئة
├── index.ts # defineChannelPluginEntry
├── setup-entry.ts # defineSetupPluginEntry
├── api.ts # التصديرات العامة (اختياري)
@ -595,7 +601,7 @@ if (decision.shouldSkip) return;
└── src/
├── channel.ts # ChannelPlugin عبر createChatChannelPlugin
├── channel.test.ts # الاختبارات
├── client.ts # عميل API للمنصة
├── client.ts # عميل API الخاص بالمنصة
└── runtime.ts # مخزن وقت التشغيل (عند الحاجة)
```
@ -608,8 +614,8 @@ if (decision.shouldSkip) return;
<Card title="تكامل أداة الرسائل" icon="puzzle" href="/ar/plugins/architecture#channel-plugins-and-the-shared-message-tool">
describeMessageTool واكتشاف الإجراءات
</Card>
<Card title="تحليل الهدف" icon="crosshair" href="/ar/plugins/architecture#channel-target-resolution">
inferTargetChatType وlooksLikeId وresolveTarget
<Card title="حل الأهداف" icon="crosshair" href="/ar/plugins/architecture#channel-target-resolution">
inferTargetChatType, looksLikeId, resolveTarget
</Card>
<Card title="مساعدات وقت التشغيل" icon="settings" href="/ar/plugins/sdk-runtime">
TTS وSTT والوسائط وsubagent عبر api.runtime
@ -617,15 +623,15 @@ if (decision.shouldSkip) return;
</CardGroup>
<Note>
لا تزال بعض واجهات المساعدات المضمّنة موجودة لصيانة Plugins المضمّنة
ولأغراض التوافق. وهي ليست النمط الموصى به لـ Plugins القنوات الجديدة؛
بل يُفضّل استخدام المسارات الفرعية العامة channel/setup/reply/runtime من
سطح SDK المشترك ما لم تكن تصون تلك العائلة من Plugins المضمّنة مباشرةً.
لا تزال بعض واجهات المساعدة المضمّنة موجودة لصيانة Plugins المضمّنة
والتوافق. وهي ليست النمط الموصى به لـ Plugins القنوات الجديدة؛
فضّل المسارات الفرعية العامة للقناة/الإعداد/الرد/وقت التشغيل من سطح 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) — أدوات الاختبار واختبارات العقود
- [ملف بيان Plugin](/ar/plugins/manifest) — المخطط الكامل لملف البيان
- [ملف بيان Plugin](/ar/plugins/manifest) — مخطط ملف البيان الكامل

224
docs/ar/plugins/sdk-entrypoints.md
View File

@ -1,35 +1,35 @@
---
read_when:
- تحتاج إلى التوقيع النوعي الدقيق لـ `definePluginEntry` أو `defineChannelPluginEntry`
- تريد فهم وضع التسجيل (كامل مقابل إعداد فقط مقابل بيانات CLI الوصفية)
- تبحث عن خيارات نقطة الدخول
- أنت بحاجة إلى التوقيع النوعي الدقيق لـ `definePluginEntry` أو `defineChannelPluginEntry`
- تريد فهم وضع التسجيل (كامل مقابل الإعداد مقابل بيانات CLI الوصفية)
- أنت تبحث عن خيارات نقطة الدخول
sidebarTitle: Entry Points
summary: مرجع `definePluginEntry` و`defineChannelPluginEntry` و`defineSetupPluginEntry`
title: نقاط دخول المكونات الإضافية
title: نقاط دخول Plugin
x-i18n:
generated_at: "2026-04-05T12:51:23Z"
generated_at: "2026-04-15T19:41:40Z"
model: gpt-5.4
provider: openai
source_hash: 799dbfe71e681dd8ba929a7a631dfe745c3c5c69530126fea2f9c137b120f51f
source_hash: aabca25bc9b8ff1b5bb4852bafe83640ffeba006ea6b6a8eff4e2c37a10f1fe4
source_path: plugins/sdk-entrypoints.md
workflow: 15
---
# نقاط دخول المكونات الإضافية
# نقاط دخول Plugin
يصدّر كل مكوّن إضافي كائن دخول افتراضيًا. ويوفر SDK ثلاث أدوات مساعدة
يُصدر كل Plugin كائن دخول افتراضيًا. توفّر SDK ثلاثة مساعدين
لإنشائها.
<Tip>
**هل تبحث عن شرح عملي؟** راجع [Channel Plugins](/plugins/sdk-channel-plugins)
أو [Provider Plugins](/plugins/sdk-provider-plugins) للحصول على أدلة خطوة بخطوة.
**هل تبحث عن شرح عملي؟** راجع [Plugins القنوات](/ar/plugins/sdk-channel-plugins)
أو [Plugins المزوّد](/ar/plugins/sdk-provider-plugins) للحصول على أدلة خطوة بخطوة.
</Tip>
## `definePluginEntry`
**الاستيراد:** `openclaw/plugin-sdk/plugin-entry`
لمكونات provider الإضافية، ومكونات الأدوات الإضافية، ومكونات hooks الإضافية، وأي شيء **ليس**
لـ Plugins المزوّد، وPlugins الأدوات، وPlugins الخطافات، وأي شيء **ليس**
قناة مراسلة.
```typescript
@ -50,28 +50,28 @@ export default definePluginEntry({
});
```
| الحقل | النوع | مطلوب | الافتراضي |
| -------------- | ---------------------------------------------------------------- | ------ | -------------------- |
| `id` | `string` | نعم | — |
| `name` | `string` | نعم | — |
| `description` | `string` | نعم | — |
| `kind` | `string` | لا | — |
| `configSchema` | `OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema` | لا | schema كائن فارغة |
| `register` | `(api: OpenClawPluginApi) => void` | نعم | — |
| الحقل | النوع | مطلوب | الافتراضي |
| -------------- | ---------------------------------------------------------------- | ----- | ------------------ |
| `id` | `string` | نعم | — |
| `name` | `string` | نعم | — |
| `description` | `string` | نعم | — |
| `kind` | `string` | لا | — |
| `configSchema` | `OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema` | لا | مخطط كائن فارغ |
| `register` | `(api: OpenClawPluginApi) => void` | نعم | — |
- يجب أن يطابق `id` ملف manifest الخاص بك في `openclaw.plugin.json`.
- يُستخدم `kind` للفتحات الحصرية: `"memory"` أو `"context-engine"`.
- يمكن أن تكون `configSchema` دالة للتقييم الكسول.
- يحل OpenClaw هذه الـ schema ويخزنها مؤقتًا عند أول وصول، لذلك لا تعمل
أدوات بناء schema المكلفة إلا مرة واحدة.
- يجب أن يطابق `id` ملف manifest ‏`openclaw.plugin.json` الخاص بك.
- يُستخدم `kind` للخانات الحصرية: `"memory"` أو `"context-engine"`.
- يمكن أن يكون `configSchema` دالة للتقييم الكسول.
- يقوم OpenClaw بحل هذا المخطط وتخزينه مؤقتًا عند أول وصول، لذلك فإن بُناة
المخططات المكلفة لا تعمل إلا مرة واحدة.
## `defineChannelPluginEntry`
**الاستيراد:** `openclaw/plugin-sdk/channel-core`
يغلف `definePluginEntry` بربط خاص بالقنوات. ويستدعي تلقائيًا
`api.registerChannel({ plugin })`، ويعرض نقطة وصل اختيارية لبيانات CLI الوصفية الخاصة بمساعدة الجذر،
ويقيّد `registerFull` بحسب وضع التسجيل.
يلف `definePluginEntry` مع توصيلات خاصة بالقنوات. ويستدعي تلقائيًا
`api.registerChannel({ plugin })`، ويكشف عن نقطة وصل اختيارية لبيانات CLI الوصفية
للمساعدة الجذرية، ويقيّد `registerFull` حسب وضع التسجيل.
```typescript
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
@ -91,44 +91,45 @@ export default defineChannelPluginEntry({
});
```
| الحقل | النوع | مطلوب | الافتراضي |
| --------------------- | ---------------------------------------------------------------- | ------ | -------------------- |
| `id` | `string` | نعم | — |
| `name` | `string` | نعم | — |
| `description` | `string` | نعم | — |
| `plugin` | `ChannelPlugin` | نعم | — |
| `configSchema` | `OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema` | لا | schema كائن فارغة |
| `setRuntime` | `(runtime: PluginRuntime) => void` | لا | — |
| `registerCliMetadata` | `(api: OpenClawPluginApi) => void` | لا | — |
| `registerFull` | `(api: OpenClawPluginApi) => void` | لا | — |
| الحقل | النوع | مطلوب | الافتراضي |
| --------------------- | ---------------------------------------------------------------- | ----- | ------------------ |
| `id` | `string` | نعم | — |
| `name` | `string` | نعم | — |
| `description` | `string` | نعم | — |
| `plugin` | `ChannelPlugin` | نعم | — |
| `configSchema` | `OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema` | لا | مخطط كائن فارغ |
| `setRuntime` | `(runtime: PluginRuntime) => void` | لا | — |
| `registerCliMetadata` | `(api: OpenClawPluginApi) => void` | لا | — |
| `registerFull` | `(api: OpenClawPluginApi) => void` | لا | — |
- يُستدعى `setRuntime` أثناء التسجيل حتى تتمكن من تخزين مرجع وقت التشغيل
(عادةً عبر `createPluginRuntimeStore`). ويُتخطى أثناء
- يتم استدعاء `setRuntime` أثناء التسجيل حتى تتمكن من تخزين مرجع runtime
(عادةً عبر `createPluginRuntimeStore`). ويتم تخطيه أثناء
التقاط بيانات CLI الوصفية.
- تعمل `registerCliMetadata` خلال كل من `api.registrationMode === "cli-metadata"`
و`api.registrationMode === "full"`.
استخدمها بوصفها المكان الرسمي لوصافات CLI المملوكة للقناة حتى تبقى
المساعدة الجذرية غير مفعِّلة بينما يظل تسجيل أوامر CLI العادي متوافقًا
مع تحميلات المكونات الإضافية الكاملة.
- لا تعمل `registerFull` إلا عندما يكون `api.registrationMode === "full"`. وتُتخطى
- يعمل `registerCliMetadata` أثناء كل من
`api.registrationMode === "cli-metadata"` و `api.registrationMode === "full"`.
استخدمه باعتباره المكان القياسي لوصفات CLI المملوكة للقناة حتى
تبقى المساعدة الجذرية غير مفعِّلة، مع بقاء تسجيل أوامر CLI العادي متوافقًا
مع تحميلات Plugin الكاملة.
- لا يعمل `registerFull` إلا عندما يكون `api.registrationMode === "full"`. ويتم تخطيه
أثناء التحميل الخاص بالإعداد فقط.
- مثل `definePluginEntry`، يمكن أن تكون `configSchema` مصنعًا كسولًا ويقوم OpenClaw
بتخزين schema المحلولة مؤقتًا عند أول وصول.
- بالنسبة إلى أوامر CLI الجذرية المملوكة للمكون الإضافي، فضّل `api.registerCli(..., { descriptors: [...] })`
عندما تريد أن يبقى الأمر محمَّلًا كسولًا من دون أن يختفي من
شجرة تحليل CLI الجذرية. وبالنسبة إلى مكونات القنوات الإضافية، فضّل تسجيل هذه الواصفات
من `registerCliMetadata(...)` وأبقِ `registerFull(...)` مركزة على العمل الخاص بوقت التشغيل فقط.
- إذا كانت `registerFull(...)` تسجل أيضًا طرق Gateway RPC، فأبقها ضمن
بادئة خاصة بالمكون الإضافي. أما مساحات أسماء الإدارة الأساسية المحجوزة (`config.*`,
`exec.approvals.*`, `wizard.*`, `update.*`) فستُحوَّل دائمًا إلى
- مثل `definePluginEntry`، يمكن أن يكون `configSchema` مصنعًا كسولًا ويقوم OpenClaw
بتخزين المخطط المحلول مؤقتًا عند أول وصول.
- بالنسبة إلى أوامر CLI الجذرية المملوكة لـ Plugin، ففضّل `api.registerCli(..., { descriptors: [...] })`
عندما تريد أن يبقى الأمر محمّلًا كسولًا من دون أن يختفي من
شجرة تحليل CLI الجذرية. أما بالنسبة إلى Plugins القنوات، ففضّل تسجيل تلك
الواصفات من `registerCliMetadata(...)` وأبقِ `registerFull(...)` مركّزًا
على الأعمال الخاصة بـ runtime فقط.
- إذا كان `registerFull(...)` يسجّل أيضًا أساليب Gateway RPC، فأبقِها على
بادئة خاصة بالـ Plugin. يتم دائمًا فرض مساحات أسماء إدارة النواة المحجوزة (`config.*`،
`exec.approvals.*`، `wizard.*`، `update.*`) إلى
`operator.admin`.
## `defineSetupPluginEntry`
**الاستيراد:** `openclaw/plugin-sdk/channel-core`
مخصص لملف `setup-entry.ts` الخفيف. ويعيد فقط `{ plugin }` من دون
ربط وقت تشغيل أو CLI.
لملف `setup-entry.ts` خفيف الوزن. يُرجع فقط `{ plugin }` من دون
توصيلات runtime أو CLI.
```typescript
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
@ -136,35 +137,60 @@ import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
export default defineSetupPluginEntry(myChannelPlugin);
```
يحمّل OpenClaw هذا بدل نقطة الدخول الكاملة عندما تكون قناة معطلة،
أو غير مهيأة، أو عندما يكون التحميل المؤجل مفعّلًا. راجع
[Setup and Config](/plugins/sdk-setup#setup-entry) لمعرفة متى يكون هذا مهمًا.
يقوم OpenClaw بتحميل هذا بدلًا من نقطة الدخول الكاملة عندما تكون القناة معطّلة،
أو غير مُعدّة، أو عند تمكين التحميل المؤجّل. راجع
[الإعداد والتهيئة](/ar/plugins/sdk-setup#setup-entry) لمعرفة متى يكون هذا مهمًا.
عمليًا، اربط `defineSetupPluginEntry(...)` بعائلات مساعدات الإعداد
الضيقة التالية:
عمليًا، يمكنك إقران `defineSetupPluginEntry(...)` بعائلات
مساعدات الإعداد الضيقة التالية:
- `openclaw/plugin-sdk/setup-runtime` لمساعدات الإعداد الآمنة وقت التشغيل مثل
محولات setup patch الآمنة للاستيراد، ومخرجات lookup-note،
و`promptResolvedAllowFrom`، و`splitSetupEntries`، ووكلاء الإعداد المفوضين
- `openclaw/plugin-sdk/channel-setup` لأسطح الإعداد الخاصة بالتثبيت الاختياري
- `openclaw/plugin-sdk/setup-tools` لمساعدات CLI/الأرشفة/الوثائق الخاصة بالإعداد/التثبيت
- `openclaw/plugin-sdk/setup-runtime` لمساعدات الإعداد الآمنة مع runtime مثل
محولات تصحيح الإعداد الآمنة للاستيراد، ومخرجات ملاحظات البحث،
و`promptResolvedAllowFrom`، و`splitSetupEntries`، ووكلاء الإعداد المفوَّضين
- `openclaw/plugin-sdk/channel-setup` لواجهات الإعداد الخاصة بالتثبيت الاختياري
- `openclaw/plugin-sdk/setup-tools` لمساعدات CLI/الأرشيف/الوثائق الخاصة بالإعداد/التثبيت
أبقِ SDKs الثقيلة، وتسجيل CLI، وخدمات وقت التشغيل طويلة العمر في
أبقِ SDKs الثقيلة، وتسجيل CLI، وخدمات runtime طويلة العمر في
نقطة الدخول الكاملة.
يمكن لقنوات مساحة العمل المجمّعة التي تقسّم بين أسطح الإعداد وruntime استخدام
`defineBundledChannelSetupEntry(...)` من
`openclaw/plugin-sdk/channel-entry-contract` بدلًا من ذلك. يتيح هذا العقد لـ
نقطة دخول الإعداد الاحتفاظ بتصديرات plugin/secrets الآمنة للإعداد مع
الاستمرار في كشف أداة تعيين runtime:
```typescript
import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract";
export default defineBundledChannelSetupEntry({
importMetaUrl: import.meta.url,
plugin: {
specifier: "./channel-plugin-api.js",
exportName: "myChannelPlugin",
},
runtime: {
specifier: "./runtime-api.js",
exportName: "setMyChannelRuntime",
},
});
```
استخدم هذا العقد المجمّع فقط عندما تحتاج تدفقات الإعداد فعلًا إلى أداة تعيين
runtime خفيفة الوزن قبل تحميل نقطة دخول القناة الكاملة.
## وضع التسجيل
يخبرك `api.registrationMode` كيف جرى تحميل المكوّن الإضافي:
يخبر `api.registrationMode` الـ Plugin الخاص بك بكيفية تحميله:
| الوضع | متى | ما الذي يجب تسجيله |
| ----------------- | --------------------------------- | ---------------------------------------------------------------------------------------- |
| `"full"` | بدء تشغيل gateway العادي | كل شيء |
| `"setup-only"` | قناة معطلة/غير مهيأة | تسجيل القناة فقط |
| `"setup-runtime"` | تدفق إعداد مع توفر وقت التشغيل | تسجيل القناة بالإضافة إلى وقت التشغيل الخفيف فقط المطلوب قبل تحميل نقطة الدخول الكاملة |
| `"cli-metadata"` | التقاط مساعدة الجذر / بيانات CLI الوصفية | واصفات CLI فقط |
| الوضع | متى | ما الذي يجب تسجيله |
| ----------------- | ----------------------------------- | ------------------------------------------------------------------------------------ |
| `"full"` | بدء تشغيل Gateway العادي | كل شيء |
| `"setup-only"` | قناة معطّلة/غير مُعدّة | تسجيل القناة فقط |
| `"setup-runtime"` | تدفق إعداد مع توفر runtime | تسجيل القناة بالإضافة إلى runtime الخفيف فقط المطلوب قبل تحميل نقطة الدخول الكاملة |
| `"cli-metadata"` | المساعدة الجذرية / التقاط بيانات CLI الوصفية | واصفات CLI فقط |
يتولى `defineChannelPluginEntry` هذا التقسيم تلقائيًا. وإذا استخدمت
`definePluginEntry` مباشرة لقناة، فتحقق من الوضع بنفسك:
يتعامل `defineChannelPluginEntry` مع هذا التقسيم تلقائيًا. إذا استخدمت
`definePluginEntry` مباشرةً لقناة، فتحقق من الوضع بنفسك:
```typescript
register(api) {
@ -181,37 +207,37 @@ register(api) {
}
```
تعامل مع `"setup-runtime"` باعتباره النافذة التي يجب أن توجد فيها
أسطح بدء التشغيل الخاصة بالإعداد فقط من دون إعادة الدخول إلى وقت تشغيل القناة
المجمعة الكامل. ومن الملائم هنا تسجيل القنوات، ومسارات HTTP الآمنة للإعداد،
وطرق gateway الآمنة للإعداد، ومساعدات الإعداد المفوضة. أما الخدمات الخلفية الثقيلة،
ومسجلات CLI، وتهيئة SDKs الخاصة بالمزوّد/العميل فما تزال تنتمي إلى `"full"`.
تعامل مع `"setup-runtime"` باعتباره النافذة التي يجب أن تكون فيها أسطح بدء التشغيل
الخاصة بالإعداد فقط موجودة من دون إعادة الدخول إلى runtime القناة المجمّعة الكاملة.
وتشمل الحالات المناسبة تسجيل القنوات، ومسارات HTTP الآمنة للإعداد، وأساليب Gateway
الآمنة للإعداد، ومساعدات الإعداد المفوَّضة. أما خدمات الخلفية الثقيلة، ومسجلات CLI،
وتهيئات SDK الخاصة بالمزوّد/العميل فما تزال تنتمي إلى `"full"`.
وبالنسبة إلى مسجلات CLI تحديدًا:
- استخدم `descriptors` عندما يملك المسجل أمرًا جذريًا واحدًا أو أكثر وتريد
من OpenClaw تحميل وحدة CLI الفعلية بكسل عند أول استدعاء
- تأكد من أن هذه الواصفات تغطي كل جذر أمر من المستوى الأعلى يعرضه
- استخدم `descriptors` عندما يمتلك المسجل أمرًا جذريًا واحدًا أو أكثر وتريد
من OpenClaw أن يحمّل وحدة CLI الحقيقية بكسل عند أول استدعاء
- تأكد من أن هذه الواصفات تغطي كل جذر أوامر من المستوى الأعلى يكشفه
المسجل
- استخدم `commands` وحدها فقط لمسارات التوافق المتحمسة
- استخدم `commands` وحده فقط لمسارات التوافق المتعجلة
## أشكال المكونات الإضافية
## أشكال Plugin
يصنف OpenClaw المكونات الإضافية المحمّلة بحسب سلوك التسجيل الخاص بها:
يصنّف OpenClaw Plugins المحمّلة وفقًا لسلوك التسجيل الخاص بها:
| الشكل | الوصف |
| --------------------- | --------------------------------------------------- |
| **plain-capability** | نوع إمكانة واحد (مثل مزوّد فقط) |
| **hybrid-capability** | عدة أنواع من الإمكانات (مثل مزوّد + speech) |
| **hook-only** | hooks فقط، من دون إمكانات |
| **non-capability** | أدوات/أوامر/خدمات لكن من دون إمكانات |
| الشكل | الوصف |
| --------------------- | ------------------------------------------------ |
| **plain-capability** | نوع قدرة واحد (مثل مزوّد فقط) |
| **hybrid-capability** | أنواع قدرات متعددة (مثل مزوّد + كلام) |
| **hook-only** | خطافات فقط، من دون قدرات |
| **non-capability** | أدوات/أوامر/خدمات ولكن من دون قدرات |
استخدم `openclaw plugins inspect <id>` لرؤية شكل المكوّن الإضافي.
استخدم `openclaw plugins inspect <id>` لرؤية شكل Plugin.
## ذو صلة
- [SDK Overview](/plugins/sdk-overview) — واجهة API الخاصة بالتسجيل ومرجع subpath
- [Runtime Helpers](/plugins/sdk-runtime) — `api.runtime` و`createPluginRuntimeStore`
- [Setup and Config](/plugins/sdk-setup) — manifest، ونقطة دخول الإعداد، والتحميل المؤجل
- [Channel Plugins](/plugins/sdk-channel-plugins) — بناء كائن `ChannelPlugin`
- [Provider Plugins](/plugins/sdk-provider-plugins) — تسجيل المزوّد وhooks
- [نظرة عامة على SDK](/ar/plugins/sdk-overview) — مرجع API التسجيل والمسارات الفرعية
- [مساعدات Runtime](/ar/plugins/sdk-runtime) — ‏`api.runtime` و`createPluginRuntimeStore`
- [الإعداد والتهيئة](/ar/plugins/sdk-setup) — manifest، ونقطة دخول الإعداد، والتحميل المؤجّل
- [Plugins القنوات](/ar/plugins/sdk-channel-plugins) — بناء كائن `ChannelPlugin`
- [Plugins المزوّد](/ar/plugins/sdk-provider-plugins) — تسجيل المزوّد والخطافات

182
docs/ar/plugins/sdk-runtime.md
View File

@ -1,29 +1,29 @@
---
read_when:
- أنت بحاجة إلى استدعاء مساعدات النواة من إضافة (TTS وSTT وتوليد الصور والبحث على الويب وsubagent)
- أنت تريد فهم ما الذي يتيحه `api.runtime`
- أنت تصل إلى مساعدات الإعدادات أو العامل أو الوسائط من داخل كود الإضافة
- تحتاج إلى استدعاء مساعدات النواة من Plugin (TTS وSTT وتوليد الصور والبحث على الويب وsubagent)
- تريد فهم ما الذي يتيحه `api.runtime`
- أنت تصل إلى مساعدات التكوين أو الوكيل أو الوسائط من داخل كود Plugin
sidebarTitle: Runtime Helpers
summary: '`api.runtime` -- مساعدات وقت التشغيل المحقونة المتاحة للإضافات'
title: مساعدات وقت تشغيل الإضافات
summary: api.runtime -- مساعدات وقت التشغيل المُحقنة المتاحة للإضافات
title: مساعدات وقت تشغيل Plugin
x-i18n:
generated_at: "2026-04-11T02:47:07Z"
generated_at: "2026-04-15T19:41:44Z"
model: gpt-5.4
provider: openai
source_hash: fbf8a6ecd970300f784b8aca20eed40ba12c83107abd27385bfdc3347d2544be
source_hash: c77a6e9cd48c84affa17dce684bbd0e072c8b63485e4a5d569f3793a4ea4f9c8
source_path: plugins/sdk-runtime.md
workflow: 15
---
# مساعدات وقت تشغيل الإضافات
# مساعدات وقت التشغيل لـ Plugin
مرجع لكائن `api.runtime` الذي يُحقن في كل إضافة أثناء
التسجيل. استخدم هذه المساعدات بدلًا من استيراد العناصر الداخلية للمضيف مباشرة.
مرجع لكائن `api.runtime` الذي يُحقن في كل Plugin أثناء
التسجيل. استخدم هذه المساعدات بدلًا من استيراد مكوّنات المضيف الداخلية مباشرةً.
<Tip>
**هل تبحث عن شرح عملي؟** راجع [إضافات القنوات](/ar/plugins/sdk-channel-plugins)
أو [إضافات الموفّرين](/ar/plugins/sdk-provider-plugins) للحصول على أدلة خطوة بخطوة
تُظهر هذه المساعدات ضمن السياق.
**هل تبحث عن شرح عملي؟** راجع [Channel Plugins](/ar/plugins/sdk-channel-plugins)
أو [Provider Plugins](/ar/plugins/sdk-provider-plugins) للحصول على أدلة خطوة بخطوة
تعرض هذه المساعدات ضمن سياقها.
</Tip>
```typescript
@ -36,42 +36,42 @@ register(api) {
### `api.runtime.agent`
هوية العامل، والأدلة، وإدارة الجلسات.
هوية الوكيل، والأدلة، وإدارة الجلسات.
```typescript
// حل دليل عمل العامل
// Resolve the agent's working directory
const agentDir = api.runtime.agent.resolveAgentDir(cfg);
// حل مساحة عمل العامل
// Resolve agent workspace
const workspaceDir = api.runtime.agent.resolveAgentWorkspaceDir(cfg);
// الحصول على هوية العامل
// Get agent identity
const identity = api.runtime.agent.resolveAgentIdentity(cfg);
// الحصول على مستوى التفكير الافتراضي
// Get default thinking level
const thinking = api.runtime.agent.resolveThinkingDefault(cfg, provider, model);
// الحصول على مهلة العامل
// Get agent timeout
const timeoutMs = api.runtime.agent.resolveAgentTimeoutMs(cfg);
// التأكد من وجود مساحة العمل
// Ensure workspace exists
await api.runtime.agent.ensureAgentWorkspace(cfg);
// تشغيل دورة عامل مضمّن
// Run an embedded agent turn
const agentDir = api.runtime.agent.resolveAgentDir(cfg);
const result = await api.runtime.agent.runEmbeddedAgent({
sessionId: "my-plugin:task-1",
runId: crypto.randomUUID(),
sessionFile: path.join(agentDir, "sessions", "my-plugin-task-1.jsonl"),
workspaceDir: api.runtime.agent.resolveAgentWorkspaceDir(cfg),
prompt: "لخّص أحدث التغييرات",
prompt: "Summarize the latest changes",
timeoutMs: api.runtime.agent.resolveAgentTimeoutMs(cfg),
});
```
يُعد `runEmbeddedAgent(...)` المساعد المحايد لبدء دورة عامل OpenClaw
عادية من داخل كود الإضافة. ويستخدم نفس آلية حل الموفّر/النموذج واختيار
حزمة العامل المستخدمة في الردود التي تُشغَّل من القنوات.
`runEmbeddedAgent(...)` هي المساعدة المحايدة لبدء دورة وكيل عادية في OpenClaw
من كود Plugin. وهي تستخدم نفس آلية حل الموفّر/النموذج واختيار
تجهيز الوكيل المستخدمة في الردود التي تُفعَّل عبر القنوات.
يبقى `runEmbeddedPiAgent(...)` اسمًا مستعارًا للتوافق.
@ -86,66 +86,66 @@ const filePath = api.runtime.agent.session.resolveSessionFilePath(cfg, sessionId
### `api.runtime.agent.defaults`
ثوابت النموذج والموفّر الافتراضية:
ثوابت النموذج والموفّر الافتراضيين:
```typescript
const model = api.runtime.agent.defaults.model; // مثال: "anthropic/claude-sonnet-4-6"
const provider = api.runtime.agent.defaults.provider; // مثال: "anthropic"
const model = api.runtime.agent.defaults.model; // e.g. "anthropic/claude-sonnet-4-6"
const provider = api.runtime.agent.defaults.provider; // e.g. "anthropic"
```
### `api.runtime.subagent`
تشغيل وإدارة عمليات subagent في الخلفية.
تشغيل عمليات subagent في الخلفية وإدارتها.
```typescript
// بدء تشغيل subagent
// Start a subagent run
const { runId } = await api.runtime.subagent.run({
sessionKey: "agent:main:subagent:search-helper",
message: "وسّع هذا الاستعلام إلى عمليات بحث متابعة أكثر تركيزًا.",
provider: "openai", // تجاوز اختياري
model: "gpt-4.1-mini", // تجاوز اختياري
message: "Expand this query into focused follow-up searches.",
provider: "openai", // optional override
model: "gpt-4.1-mini", // optional override
deliver: false,
});
// الانتظار حتى الاكتمال
// Wait for completion
const result = await api.runtime.subagent.waitForRun({ runId, timeoutMs: 30000 });
// قراءة رسائل الجلسة
// Read session messages
const { messages } = await api.runtime.subagent.getSessionMessages({
sessionKey: "agent:main:subagent:search-helper",
limit: 10,
});
// حذف جلسة
// Delete a session
await api.runtime.subagent.deleteSession({
sessionKey: "agent:main:subagent:search-helper",
});
```
<Warning>
تتطلب تجاوزات النموذج (`provider`/`model`) اشتراكًا صريحًا من المشغّل عبر
تتطلب تجاوزات النموذج (`provider`/`model`) موافقة صريحة من المشغّل عبر
`plugins.entries.<id>.subagent.allowModelOverride: true` في الإعدادات.
لا تزال الإضافات غير الموثوقة قادرة على تشغيل subagents، لكن طلبات التجاوز تُرفَض.
لا يزال بإمكان Plugins غير الموثوقة تشغيل subagents، لكن طلبات التجاوز تُرفض.
</Warning>
### `api.runtime.taskFlow`
اربط وقت تشغيل Task Flow بمفتاح جلسة OpenClaw موجود أو بسياق أداة موثوق،
ثم أنشئ Task Flows وأدرها من دون تمرير مالك في كل استدعاء.
اربط وقت تشغيل TaskFlow بمفتاح جلسة OpenClaw موجود أو بسياق أداة موثوق،
ثم أنشئ Task Flows وأدرها دون تمرير مالك مع كل استدعاء.
```typescript
const taskFlow = api.runtime.taskFlow.fromToolContext(ctx);
const created = taskFlow.createManaged({
controllerId: "my-plugin/review-batch",
goal: "مراجعة طلبات السحب الجديدة",
goal: "Review new pull requests",
});
const child = taskFlow.runTask({
flowId: created.flowId,
runtime: "acp",
childSessionKey: "agent:main:subagent:reviewer",
task: "راجع PR #123",
task: "Review PR #123",
status: "running",
startedAt: Date.now(),
});
@ -159,73 +159,74 @@ const waiting = taskFlow.setWaiting({
```
استخدم `bindSession({ sessionKey, requesterOrigin })` عندما يكون لديك بالفعل
مفتاح جلسة OpenClaw موثوق من طبقة الربط الخاصة بك. لا تربط انطلاقًا من
مفتاح جلسة OpenClaw موثوق من طبقة الربط الخاصة بك. لا تُجرِ الربط من
إدخال مستخدم خام.
### `api.runtime.tts`
تحويل النص إلى كلام.
تركيب تحويل النص إلى كلام.
```typescript
// TTS قياسي
// Standard TTS
const clip = await api.runtime.tts.textToSpeech({
text: "مرحبًا من OpenClaw",
text: "Hello from OpenClaw",
cfg: api.config,
});
// TTS محسّن للاتصالات الهاتفية
// Telephony-optimized TTS
const telephonyClip = await api.runtime.tts.textToSpeechTelephony({
text: "مرحبًا من OpenClaw",
text: "Hello from OpenClaw",
cfg: api.config,
});
// إدراج الأصوات المتاحة
// List available voices
const voices = await api.runtime.tts.listVoices({
provider: "elevenlabs",
cfg: api.config,
});
```
يستخدم إعدادات `messages.tts` الأساسية واختيار الموفّر. ويُرجع مخزنًا مؤقتًا
لصوت PCM + معدل العينة.
يستخدم إعدادات `messages.tts` الأساسية واختيار الموفّر. ويعيد مخزنًا مؤقتًا
لصوت PCM مع معدل العينة.
### `api.runtime.mediaUnderstanding`
تحليل الصور والصوت والفيديو.
```typescript
// وصف صورة
// Describe an image
const image = await api.runtime.mediaUnderstanding.describeImageFile({
filePath: "/tmp/inbound-photo.jpg",
cfg: api.config,
agentDir: "/tmp/agent",
});
// نسخ صوت إلى نص
// Transcribe audio
const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
filePath: "/tmp/inbound-audio.ogg",
cfg: api.config,
mime: "audio/ogg", // اختياري، عندما لا يمكن استنتاج MIME
mime: "audio/ogg", // optional, for when MIME cannot be inferred
});
// وصف فيديو
// Describe a video
const video = await api.runtime.mediaUnderstanding.describeVideoFile({
filePath: "/tmp/inbound-video.mp4",
cfg: api.config,
});
// تحليل ملف عام
// Generic file analysis
const result = await api.runtime.mediaUnderstanding.runFile({
filePath: "/tmp/inbound-file.pdf",
cfg: api.config,
});
```
يُرجع `{ text: undefined }` عندما لا يتم إنتاج أي مخرجات (مثل إدخال تم تخطيه).
يعيد `{ text: undefined }` عندما لا يتم إنتاج أي مخرجات (على سبيل المثال، عند
تخطي الإدخال).
<Info>
يبقى `api.runtime.stt.transcribeAudioFile(...)` اسمًا مستعارًا للتوافق
لـ `api.runtime.mediaUnderstanding.transcribeAudioFile(...)`.
مع `api.runtime.mediaUnderstanding.transcribeAudioFile(...)`.
</Info>
### `api.runtime.imageGeneration`
@ -234,7 +235,7 @@ const result = await api.runtime.mediaUnderstanding.runFile({
```typescript
const result = await api.runtime.imageGeneration.generate({
prompt: "روبوت يرسم غروب الشمس",
prompt: "A robot painting a sunset",
cfg: api.config,
});
@ -256,7 +257,7 @@ const result = await api.runtime.webSearch.search({
### `api.runtime.media`
أدوات وسائط منخفضة المستوى.
أدوات الوسائط منخفضة المستوى.
```typescript
const webMedia = await api.runtime.media.loadWebMedia(url);
@ -278,7 +279,7 @@ await api.runtime.config.writeConfigFile(cfg);
### `api.runtime.system`
أدوات مساعدة على مستوى النظام.
أدوات على مستوى النظام.
```typescript
await api.runtime.system.enqueueSystemEvent(event);
@ -311,7 +312,7 @@ const childLogger = api.runtime.logging.getChildLogger({ plugin: "my-plugin" },
### `api.runtime.modelAuth`
حل مصادقة النموذج والموفّر.
حلّ مصادقة النموذج والموفّر.
```typescript
const auth = await api.runtime.modelAuth.getApiKeyForModel({ model, cfg });
@ -323,7 +324,7 @@ const providerAuth = await api.runtime.modelAuth.resolveApiKeyForProvider({
### `api.runtime.state`
حل دليل الحالة.
حلّ دليل الحالة.
```typescript
const stateDir = api.runtime.state.resolveStateDir();
@ -331,7 +332,7 @@ const stateDir = api.runtime.state.resolveStateDir();
### `api.runtime.tools`
مصانع أدوات الذاكرة وCLI.
مصانع أداة الذاكرة وCLI.
```typescript
const getTool = api.runtime.tools.createMemoryGetTool(/* ... */);
@ -341,10 +342,10 @@ api.runtime.tools.registerMemoryCli(/* ... */);
### `api.runtime.channel`
مساعدات وقت تشغيل خاصة بالقناة (متاحة عند تحميل إضافة قناة).
مساعدات وقت تشغيل خاصة بالقناة (تكون متاحة عند تحميل Channel Plugin).
يُعد `api.runtime.channel.mentions` سطح سياسة الإشارة الواردة المشتركة
لإضافات القنوات المضمّنة التي تستخدم حقن وقت التشغيل:
`api.runtime.channel.mentions` هي واجهة سياسة الإشارة الواردة المشتركة
لـ Channel Plugins المضمّنة التي تستخدم حقن وقت التشغيل:
```typescript
const mentionMatch = api.runtime.channel.mentions.matchesMentionWithExplicit(text, {
@ -379,56 +380,63 @@ const decision = api.runtime.channel.mentions.resolveInboundMentionDecision({
- `implicitMentionKindWhen`
- `resolveInboundMentionDecision`
لا يكشف `api.runtime.channel.mentions` عمدًا عن مساعدات التوافق الأقدم
`resolveMentionGating*`. ويفضَّل استخدام المسار المطبّع
لا يعرّض `api.runtime.channel.mentions` عمدًا مساعدات التوافق الأقدم
`resolveMentionGating*`. يُفضَّل استخدام المسار الموحّد
`{ facts, policy }`.
## تخزين مراجع وقت التشغيل
استخدم `createPluginRuntimeStore` لتخزين مرجع وقت التشغيل من أجل استخدامه خارج
دالة الاستدعاء `register`:
استخدم `createPluginRuntimeStore` لتخزين مرجع وقت التشغيل لاستخدامه خارج
دالة `register`:
```typescript
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";
const store = createPluginRuntimeStore<PluginRuntime>("لم يتم تهيئة وقت تشغيل my-plugin");
const store = createPluginRuntimeStore<PluginRuntime>({
pluginId: "my-plugin",
errorMessage: "my-plugin runtime not initialized",
});
// في نقطة الدخول الخاصة بك
// In your entry point
export default defineChannelPluginEntry({
id: "my-plugin",
name: "My Plugin",
description: "مثال",
description: "Example",
plugin: myPlugin,
setRuntime: store.setRuntime,
});
// في ملفات أخرى
// In other files
export function getRuntime() {
return store.getRuntime(); // يرمي خطأ إذا لم تتم التهيئة
return store.getRuntime(); // throws if not initialized
}
export function tryGetRuntime() {
return store.tryGetRuntime(); // يُرجع null إذا لم تتم التهيئة
return store.tryGetRuntime(); // returns null if not initialized
}
```
## حقول `api` الأخرى ذات المستوى الأعلى
يُفضَّل `pluginId` لهوية runtime-store. أما الصيغة الأدنى مستوى `key`
فهي للحالات غير الشائعة التي يحتاج فيها Plugin واحد عمدًا إلى أكثر من خانة
وقت تشغيل واحدة.
## حقول `api` العلوية الأخرى
إلى جانب `api.runtime`، يوفّر كائن API أيضًا:
| الحقل | النوع | الوصف |
| الحقل | النوع | الوصف |
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
| `api.id` | `string` | معرّف الإضافة |
| `api.name` | `string` | الاسم المعروض للإضافة |
| `api.config` | `OpenClawConfig` | لقطة الإعدادات الحالية (لقطة وقت التشغيل النشطة داخل الذاكرة عند توفرها) |
| `api.pluginConfig` | `Record<string, unknown>` | إعدادات خاصة بالإضافة من `plugins.entries.<id>.config` |
| `api.logger` | `PluginLogger` | مسجّل بنطاق محدد (`debug` و`info` و`warn` و`error`) |
| `api.registrationMode` | `PluginRegistrationMode` | وضع التحميل الحالي؛ تمثّل `"setup-runtime"` نافذة بدء التشغيل/الإعداد الخفيفة قبل الإدخال الكامل |
| `api.resolvePath(input)` | `(string) => string` | حل مسار نسبةً إلى جذر الإضافة |
| `api.id` | `string` | معرّف Plugin |
| `api.name` | `string` | الاسم المعروض لـ Plugin |
| `api.config` | `OpenClawConfig` | لقطة الإعدادات الحالية (لقطة وقت التشغيل النشطة داخل الذاكرة عند توفرها) |
| `api.pluginConfig` | `Record<string, unknown>` | إعدادات خاصة بـ Plugin من `plugins.entries.<id>.config` |
| `api.logger` | `PluginLogger` | مسجّل بنطاق محدد (`debug` و`info` و`warn` و`error`) |
| `api.registrationMode` | `PluginRegistrationMode` | وضع التحميل الحالي؛ يشير `"setup-runtime"` إلى نافذة بدء/إعداد خفيفة قبل التشغيل الكامل |
| `api.resolvePath(input)` | `(string) => string` | حلّ مسار نسبةً إلى جذر Plugin |
## ذو صلة
- [نظرة عامة على SDK](/ar/plugins/sdk-overview) -- مرجع المسارات الفرعية
- [نقاط دخول SDK](/ar/plugins/sdk-entrypoints) -- خيارات `definePluginEntry`
- [الأجزاء الداخلية للإضافات](/ar/plugins/architecture) -- نموذج الإمكانات والسجل
- [المكوّنات الداخلية لـ Plugin](/ar/plugins/architecture) -- نموذج القدرات والسجل

393
docs/ar/plugins/sdk-setup.md
View File

@ -1,37 +1,37 @@
---
read_when:
- أنت تضيف معالج إعداد إلى إضافة
- تحتاج إلى فهم الفرق بين `setup-entry.ts` و`index.ts`
- أنت تعرّف مخططات config للإضافة أو بيانات `openclaw` الوصفية في `package.json`
- أنت تضيف معالج إعداد إلى Plugin
- تحتاج إلى فهم `setup-entry.ts` مقابل `index.ts`
- أنت تعرّف مخططات تكوين Plugin أو بيانات تعريف `openclaw` في `package.json`
sidebarTitle: Setup and Config
summary: معالجات الإعداد، و`setup-entry.ts`، ومخططات config، وبيانات `package.json` الوصفية
title: إعداد الإضافة وConfig الخاص بها
summary: معالجات الإعداد، `setup-entry.ts`، مخططات التكوين، وبيانات التعريف في `package.json`
title: إعداد Plugin والتكوين
x-i18n:
generated_at: "2026-04-06T03:11:22Z"
generated_at: "2026-04-15T19:41:39Z"
model: gpt-5.4
provider: openai
source_hash: eac2586516d27bcd94cc4c259fe6274c792b3f9938c7ddd6dbf04a6dbb988dc9
source_hash: ddf28e25e381a4a38ac478e531586f59612e1a278732597375f87c2eeefc521b
source_path: plugins/sdk-setup.md
workflow: 15
---
# إعداد الإضافة وConfig الخاص بها
# إعداد Plugin والتكوين
مرجع لتغليف الإضافات (بيانات `package.json` الوصفية)، وmanifest
(`openclaw.plugin.json`)، ومداخل الإعداد، ومخططات config.
مرجع لتغليف Plugin (بيانات تعريف `package.json`)، وملفات البيان
(`openclaw.plugin.json`)، ومداخل الإعداد، ومخططات التكوين.
<Tip>
**هل تبحث عن شرح عملي؟** تغطي أدلة التنفيذ التغليف ضمن السياق:
[إضافات القنوات](/ar/plugins/sdk-channel-plugins#step-1-package-and-manifest) و
[إضافات المزوّدين](/ar/plugins/sdk-provider-plugins#step-1-package-and-manifest).
**هل تبحث عن شرح تطبيقي؟** تغطي أدلة كيفية التنفيذ التغليف ضمن السياق:
[Plugins القنوات](/ar/plugins/sdk-channel-plugins#step-1-package-and-manifest) و
[Plugins المزوّدين](/ar/plugins/sdk-provider-plugins#step-1-package-and-manifest).
</Tip>
## بيانات الحزمة الوصفية
## بيانات تعريف الحزمة
يحتاج `package.json` الخاص بك إلى حقل `openclaw` يخبر نظام الإضافات بما
توفّره إضافتك:
يحتاج ملف `package.json` الخاص بك إلى حقل `openclaw` يوضح لنظام Plugin ما
الذي يوفّره Plugin الخاص بك:
**إضافة قناة:**
**Plugin قناة:**
```json
{
@ -44,13 +44,13 @@ x-i18n:
"channel": {
"id": "my-channel",
"label": "My Channel",
"blurb": "وصف قصير للقناة."
"blurb": "Short description of the channel."
}
}
}
```
**إضافة مزوّد / خط أساس النشر على ClawHub:**
**Plugin مزوّد / خط الأساس للنشر في ClawHub:**
```json openclaw-clawhub-package.json
{
@ -71,47 +71,47 @@ x-i18n:
}
```
إذا كنت تنشر الإضافة خارجيًا على ClawHub، فإن حقلي `compat` و`build`
مطلوبان. وتوجد مقتطفات النشر القانونية في
إذا كنت تنشر Plugin خارجيًا على ClawHub، فإن حقلي `compat` و`build`
مطلوبان. توجد مقتطفات النشر القياسية في
`docs/snippets/plugin-publish/`.
### حقول `openclaw`
| الحقل | النوع | الوصف |
| ------------ | ---------- | ------------------------------------------------------------------------------------------------- |
| `extensions` | `string[]` | ملفات نقاط الإدخال (نسبةً إلى جذر الحزمة) |
| `setupEntry` | `string` | إدخال خفيف مخصص للإعداد فقط (اختياري) |
| `channel` | `object` | بيانات وصفية لفهرس القنوات لأسطح الإعداد والمنتقي والبداية السريعة والحالة |
| `providers` | `string[]` | معرّفات المزوّدين التي تسجلها هذه الإضافة |
| `install` | `object` | تلميحات التثبيت: `npmSpec` و`localPath` و`defaultChoice` و`minHostVersion` و`allowInvalidConfigRecovery` |
| `startup` | `object` | رايات سلوك بدء التشغيل |
| الحقل | النوع | الوصف |
| ------------ | ---------- | ------------------------------------------------------------------------------------------------------ |
| `extensions` | `string[]` | ملفات نقطة الإدخال (بالنسبة إلى جذر الحزمة) |
| `setupEntry` | `string` | إدخال خفيف مخصّص للإعداد فقط (اختياري) |
| `channel` | `object` | بيانات تعريف فهرس القناة لأسطح الإعداد والمنتقي والبدء السريع والحالة |
| `providers` | `string[]` | معرّفات المزوّدين التي يسجّلها هذا Plugin |
| `install` | `object` | تلميحات التثبيت: `npmSpec`, `localPath`, `defaultChoice`, `minHostVersion`, `allowInvalidConfigRecovery` |
| `startup` | `object` | إشارات سلوك بدء التشغيل |
### `openclaw.channel`
يمثل `openclaw.channel` بيانات وصفية رخيصة على مستوى الحزمة لاكتشاف القنوات وأسطر الإعداد
قبل تحميل وقت التشغيل.
يُعد `openclaw.channel` بيانات تعريف حزمة منخفضة التكلفة لاكتشاف القناة
وأسطح الإعداد قبل تحميل وقت التشغيل.
| الحقل | النوع | ما الذي يعنيه |
| -------------------------------------- | ---------- | ---------------------------------------------------------------------------- |
| `id` | `string` | معرّف القناة القانوني. |
| `label` | `string` | التسمية الأساسية للقناة. |
| `selectionLabel` | `string` | تسمية المنتقي/الإعداد عندما ينبغي أن تختلف عن `label`. |
| `detailLabel` | `string` | تسمية تفاصيل ثانوية لفهارس القنوات الأغنى وأسطر الحالة. |
| `docsPath` | `string` | مسار المستندات لروابط الإعداد والاختيار. |
| `docsLabel` | `string` | تجاوز للتسمية المستخدمة لروابط المستندات عندما ينبغي أن تختلف عن معرّف القناة. |
| `blurb` | `string` | وصف قصير للفهرس/التهيئة الأولية. |
| `order` | `number` | ترتيب الفرز في فهارس القنوات. |
| `aliases` | `string[]` | أسماء بديلة إضافية للبحث عن القناة عند الاختيار. |
| `preferOver` | `string[]` | معرّفات إضافات/قنوات أقل أولوية ينبغي أن تتفوق عليها هذه القناة. |
| `systemImage` | `string` | اسم icon/system-image اختياري لفهارس UI الخاصة بالقنوات. |
| `selectionDocsPrefix` | `string` | نص بادئة قبل روابط المستندات في أسطح الاختيار. |
| `selectionDocsOmitLabel` | `boolean` | عرض مسار المستندات مباشرة بدل رابط مستندات ذي تسمية في نص الاختيار. |
| `selectionExtras` | `string[]` | سلاسل قصيرة إضافية تُلحَق في نص الاختيار. |
| `markdownCapable` | `boolean` | يضع علامة على أن القناة تدعم Markdown لقرارات التنسيق الصادر. |
| `exposure` | `object` | عناصر تحكم في ظهور القناة في أسطح الإعداد والقوائم المهيأة والمستندات. |
| `quickstartAllowFrom` | `boolean` | يدرج هذه القناة في تدفق إعداد `allowFrom` القياسي للبداية السريعة. |
| `forceAccountBinding` | `boolean` | يطلب ربط حساب صريحًا حتى عند وجود حساب واحد فقط. |
| `preferSessionLookupForAnnounceTarget` | `boolean` | يفضّل البحث في الجلسة عند حل أهداف الإعلان لهذه القناة. |
| الحقل | النوع | ما الذي يعنيه |
| -------------------------------------- | ---------- | ----------------------------------------------------------------------------- |
| `id` | `string` | معرّف القناة القياسي. |
| `label` | `string` | التسمية الأساسية للقناة. |
| `selectionLabel` | `string` | تسمية المنتقي/الإعداد عندما ينبغي أن تختلف عن `label`. |
| `detailLabel` | `string` | تسمية تفصيلية ثانوية لفهارس القنوات الأغنى وأسطح الحالة. |
| `docsPath` | `string` | مسار الوثائق لروابط الإعداد والاختيار. |
| `docsLabel` | `string` | تسمية بديلة مستخدمة لروابط الوثائق عندما ينبغي أن تختلف عن معرّف القناة. |
| `blurb` | `string` | وصف قصير للفهرس/التهيئة الأولية. |
| `order` | `number` | ترتيب الفرز في فهارس القنوات. |
| `aliases` | `string[]` | أسماء بديلة إضافية للبحث عن القناة. |
| `preferOver` | `string[]` | معرّفات Plugin/قناة ذات أولوية أقل ينبغي لهذه القناة أن تتقدّم عليها. |
| `systemImage` | `string` | اسم أيقونة/صورة نظام اختياري لواجهات فهارس القنوات. |
| `selectionDocsPrefix` | `string` | نص بادئة قبل روابط الوثائق في أسطح الاختيار. |
| `selectionDocsOmitLabel` | `boolean` | عرض مسار الوثائق مباشرة بدلًا من رابط وثائق ذي تسمية في نص الاختيار. |
| `selectionExtras` | `string[]` | سلاسل قصيرة إضافية تُلحَق في نص الاختيار. |
| `markdownCapable` | `boolean` | يحدد أن القناة تدعم Markdown لقرارات التنسيق الصادر. |
| `exposure` | `object` | عناصر تحكم في ظهور القناة للإعداد والقوائم المهيأة وأس surfaces الوثائق. |
| `quickstartAllowFrom` | `boolean` | يضم هذه القناة إلى تدفق إعداد `allowFrom` القياسي للبدء السريع. |
| `forceAccountBinding` | `boolean` | يفرض ربط الحساب صراحة حتى عند وجود حساب واحد فقط. |
| `preferSessionLookupForAnnounceTarget` | `boolean` | يفضّل البحث في الجلسة عند حل أهداف الإعلان لهذه القناة. |
مثال:
@ -125,11 +125,11 @@ x-i18n:
"detailLabel": "My Channel Bot",
"docsPath": "/channels/my-channel",
"docsLabel": "my-channel",
"blurb": "تكامل دردشة مستضاف ذاتيًا قائم على webhook.",
"blurb": "Webhook-based self-hosted chat integration.",
"order": 80,
"aliases": ["mc"],
"preferOver": ["my-channel-legacy"],
"selectionDocsPrefix": "الدليل:",
"selectionDocsPrefix": "Guide:",
"selectionExtras": ["Markdown"],
"markdownCapable": true,
"exposure": {
@ -145,37 +145,37 @@ x-i18n:
يدعم `exposure` ما يلي:
- `configured`: تضمين القناة في أسطح القوائم من نمط configured/status
- `configured`: تضمين القناة في أسطح القوائم المهيأة/على نمط الحالة
- `setup`: تضمين القناة في منتقيات الإعداد/التهيئة التفاعلية
- `docs`: وضع علامة على أن القناة موجهة للعامة في أسطح المستندات/التنقل
- `docs`: تحديد القناة على أنها موجهة للعامة في أسطح الوثائق/التنقل
لا يزال `showConfigured` و`showInSetup` مدعومين كأسماء بديلة قديمة. ويفضَّل
لا يزال `showConfigured` و`showInSetup` مدعومين كأسماء بديلة قديمة. يُفضّل
استخدام `exposure`.
### `openclaw.install`
يمثل `openclaw.install` بيانات وصفية على مستوى الحزمة، وليس بيانات manifest وصفية.
يُعد `openclaw.install` بيانات تعريف حزمة، وليس بيانات تعريف بيان.
| الحقل | النوع | ما الذي يعنيه |
| ---------------------------- | -------------------- | ---------------------------------------------------------------------------------- |
| `npmSpec` | `string` | مواصفة npm القانونية لتدفقات التثبيت/التحديث. |
| `localPath` | `string` | مسار تثبيت محلي للتطوير أو للإضافات المجمعة. |
| `defaultChoice` | `"npm"` \| `"local"` | مصدر التثبيت المفضل عند توفر الاثنين. |
| `minHostVersion` | `string` | الحد الأدنى لإصدار OpenClaw المدعوم بصيغة `>=x.y.z`. |
| `allowInvalidConfigRecovery` | `boolean` | يتيح لتدفقات إعادة تثبيت الإضافات المجمعة التعافي من إخفاقات config قديمة محددة. |
| الحقل | النوع | ما الذي يعنيه |
| ---------------------------- | -------------------- | -------------------------------------------------------------------------------- |
| `npmSpec` | `string` | مواصفة npm القياسية لتدفقات التثبيت/التحديث. |
| `localPath` | `string` | مسار تثبيت محلي للتطوير أو مضمّن. |
| `defaultChoice` | `"npm"` \| `"local"` | مصدر التثبيت المفضّل عندما يكون كلاهما متاحًا. |
| `minHostVersion` | `string` | الحد الأدنى لإصدار OpenClaw المدعوم بصيغة `>=x.y.z`. |
| `allowInvalidConfigRecovery` | `boolean` | يسمح لتدفقات إعادة تثبيت Plugin المضمّن بالتعافي من أعطال تهيئة قديمة محددة. |
إذا تم تعيين `minHostVersion`، فإن التثبيت وتحميل سجل manifest يفرضان
هذا الحقل كليهما. وتتجاوز المضيفات الأقدم الإضافة؛ أما سلاسل الإصدارات غير الصالحة فتُرفض.
إذا تم تعيين `minHostVersion`، فإن كلًا من التثبيت وتحميل سجل البيان يفرضان
ذلك. تتجاوز الاستضافات الأقدم هذا Plugin؛ وتُرفض سلاسل الإصدار غير الصالحة.
إن `allowInvalidConfigRecovery` ليس تجاوزًا عامًا لإعدادات config المكسورة. بل هو
للتعافي الضيق الخاص بالإضافات المجمعة فقط، حتى تتمكن إعادة التثبيت/الإعداد من إصلاح
مخلّفات الترقيات المعروفة مثل مسار إضافة مجمعة مفقود أو إدخال `channels.<id>`
قديم لتلك الإضافة نفسها. وإذا كان config مكسورًا لأسباب غير مرتبطة، فلا يزال
التثبيت يفشل بشكل مغلق ويوجه المشغّل إلى تشغيل `openclaw doctor --fix`.
لا يُعد `allowInvalidConfigRecovery` تجاوزًا عامًا للتكوينات المعطوبة. بل هو
مخصّص فقط لتعافٍ ضيق النطاق لـ Plugin المضمّن، بحيث يمكن لإعادة التثبيت/الإعداد
إصلاح بقايا ترقيات معروفة مثل غياب مسار Plugin المضمّن أو وجود إدخال قديم
`channels.<id>` لذاك Plugin نفسه. إذا كان التكوين معطوبًا لأسباب غير مرتبطة،
فلا يزال التثبيت يفشل بشكل آمن ويخبر المشغّل بتشغيل `openclaw doctor --fix`.
### تأجيل التحميل الكامل
يمكن لإضافات القنوات الاشتراك في التحميل المؤجل باستخدام:
يمكن لـ Plugins القنوات الاشتراك في التحميل المؤجل عبر:
```json
{
@ -189,45 +189,46 @@ x-i18n:
}
```
عند التمكين، يحمّل OpenClaw `setupEntry` فقط أثناء مرحلة بدء التشغيل
التي تسبق الاستماع، حتى للقنوات المهيأة بالفعل. ويُحمّل الإدخال الكامل بعد أن
تبدأ البوابة في الاستماع.
عند التفعيل، يحمّل OpenClaw فقط `setupEntry` خلال مرحلة بدء التشغيل السابقة
للاستماع، حتى بالنسبة إلى القنوات المُهيأة بالفعل. ويُحمَّل الإدخال الكامل بعد
أن تبدأ Gateway بالاستماع.
<Warning>
لا تفعّل التحميل المؤجل إلا عندما يسجل `setupEntry` الخاص بك كل ما
تحتاجه البوابة قبل أن تبدأ الاستماع (تسجيل القناة، ومسارات HTTP، وطرائق البوابة). وإذا كان الإدخال الكامل يملك إمكانات بدء تشغيل مطلوبة، فأبقِ
لا تفعّل التحميل المؤجل إلا عندما كان `setupEntry` الخاص بك يسجّل كل ما
تحتاجه Gateway قبل أن تبدأ بالاستماع (تسجيل القناة، ومسارات HTTP، وطرق
Gateway). إذا كان الإدخال الكامل يملك قدرات مطلوبة عند بدء التشغيل، فأبقِ
السلوك الافتراضي.
</Warning>
إذا كان إدخال الإعداد/الإدخال الكامل لديك يسجل طرائق Gateway RPC، فأبقِها على
بادئة خاصة بالإضافة. وتظل مساحات أسماء الإدارة الأساسية المحجوزة (`config.*`،
`exec.approvals.*`، `wizard.*`، `update.*`) مملوكة للنواة وتُحل دائمًا
إلى `operator.admin`.
إذا كان إدخال الإعداد/الإدخال الكامل لديك يسجّل طرق Gateway RPC، فاحتفظ بها
ضمن بادئة خاصة بـ Plugin. تظل مساحات أسماء إدارة النواة المحجوزة (`config.*`,
`exec.approvals.*`, `wizard.*`, `update.*`) مملوكة للنواة وتُحل دائمًا إلى
`operator.admin`.
## Plugin manifest
## بيان Plugin
يجب أن تُرفق كل إضافة أصلية ملف `openclaw.plugin.json` في جذر الحزمة.
ويستخدم OpenClaw هذا للتحقق من config من دون تنفيذ شيفرة الإضافة.
يجب أن يشحن كل Plugin أصلي ملف `openclaw.plugin.json` في جذر الحزمة.
يستخدم OpenClaw هذا للتحقق من صحة التكوين دون تنفيذ شيفرة Plugin.
```json
{
"id": "my-plugin",
"name": "My Plugin",
"description": "يضيف إمكانات My Plugin إلى OpenClaw",
"description": "Adds My Plugin capabilities to OpenClaw",
"configSchema": {
"type": "object",
"additionalProperties": false,
"properties": {
"webhookSecret": {
"type": "string",
"description": "سر التحقق من webhook"
"description": "Webhook verification secret"
}
}
}
}
```
بالنسبة إلى إضافات القنوات، أضف `kind` و`channels`:
بالنسبة إلى Plugins القنوات، أضف `kind` و`channels`:
```json
{
@ -242,7 +243,7 @@ x-i18n:
}
```
حتى الإضافات التي لا تحتوي على config يجب أن تُرفق schema. ويُعد المخطط الفارغ صالحًا:
حتى Plugins التي لا تحتوي على أي تكوين يجب أن تشحن مخططًا. مخطط فارغ صالح:
```json
{
@ -254,24 +255,24 @@ x-i18n:
}
```
راجع [Plugin Manifest](/ar/plugins/manifest) للاطلاع على المرجع الكامل للمخطط.
راجع [بيان Plugin](/ar/plugins/manifest) للاطلاع على المرجع الكامل للمخطط.
## النشر على ClawHub
بالنسبة إلى حزم الإضافات، استخدم أمر ClawHub الخاص بالحزمة:
بالنسبة إلى حزم Plugins، استخدم أمر ClawHub الخاص بالحزمة:
```bash
clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
```
الاسم البديل القديم للنشر الخاص بالـ Skill فقط مخصص لـ Skills. ويجب أن تستخدم حزم الإضافات
دائمًا `clawhub package publish`.
الاسم البديل القديم الخاص بالنشر للمهارات فقط مخصّص للمهارات. يجب على حزم Plugins
استخدام `clawhub package publish` دائمًا.
## إدخال الإعداد
ملف `setup-entry.ts` هو بديل خفيف لـ `index.ts`
يحمّله OpenClaw عندما يحتاج فقط إلى أسطح الإعداد (التهيئة الأولية، وإصلاح config، وفحص القنوات المعطلة).
ملف `setup-entry.ts` هو بديل خفيف لـ `index.ts` يقوم OpenClaw بتحميله عندما
يحتاج فقط إلى أسطح الإعداد (التهيئة الأولية، إصلاح التكوين، فحص القنوات المعطلة).
```typescript
// setup-entry.ts
@ -281,77 +282,84 @@ import { myChannelPlugin } from "./src/channel.js";
export default defineSetupPluginEntry(myChannelPlugin);
```
وهذا يتجنب تحميل شيفرة وقت تشغيل ثقيلة (مكتبات crypto، وتسجيلات CLI،
هذا يتجنب تحميل شيفرة وقت تشغيل ثقيلة (مكتبات التشفير، وتسجيلات CLI،
والخدمات الخلفية) أثناء تدفقات الإعداد.
**متى يستخدم OpenClaw `setupEntry` بدل الإدخال الكامل:**
يمكن لقنوات مساحة العمل المضمّنة التي تحتفظ بتصديرات آمنة للإعداد في وحدات
جانبية استخدام `defineBundledChannelSetupEntry(...)` من
`openclaw/plugin-sdk/channel-entry-contract` بدلًا من
`defineSetupPluginEntry(...)`. يدعم هذا العقد المضمّن أيضًا تصدير `runtime`
اختياريًا بحيث يبقى توصيل وقت التشغيل في وقت الإعداد خفيفًا وواضحًا.
- تكون القناة معطلة لكنها تحتاج إلى أسطح إعداد/تهيئة أولية
- تكون القناة مفعلة لكنها غير مهيأة
**متى يستخدم OpenClaw `setupEntry` بدلًا من الإدخال الكامل:**
- تكون القناة معطّلة ولكنها تحتاج إلى أسطح الإعداد/التهيئة الأولية
- تكون القناة مفعّلة ولكن غير مهيأة
- يكون التحميل المؤجل مفعّلًا (`deferConfiguredChannelFullLoadUntilAfterListen`)
**ما الذي يجب أن يسجله `setupEntry`:**
**ما الذي يجب أن يسجّله `setupEntry`:**
- كائن إضافة القناة (عبر `defineSetupPluginEntry`)
- أي مسارات HTTP مطلوبة قبل استماع البوابة
- أي طرائق للبوابة مطلوبة أثناء بدء التشغيل
- كائن Plugin الخاص بالقناة (عبر `defineSetupPluginEntry`)
- أي مسارات HTTP مطلوبة قبل استماع Gateway
- أي طرق Gateway مطلوبة أثناء بدء التشغيل
ويجب أن تتجنب طرائق البوابة الخاصة ببدء التشغيل تلك أيضًا مساحات أسماء الإدارة
الأساسية المحجوزة مثل `config.*` أو `update.*`.
يجب أن تتجنب طرق Gateway الخاصة ببدء التشغيل هذه أيضًا مساحات أسماء إدارة
النواة المحجوزة مثل `config.*` أو `update.*`.
**ما الذي يجب ألا يتضمنه `setupEntry`:**
**ما الذي يجب ألّا يتضمنه `setupEntry`:**
- تسجيلات CLI
- الخدمات الخلفية
- واردات وقت تشغيل ثقيلة (crypto وSDKs)
- طرائق البوابة المطلوبة فقط بعد بدء التشغيل
- استيرادات وقت التشغيل الثقيلة (التشفير، وحِزم SDK)
- طرق Gateway المطلوبة فقط بعد بدء التشغيل
### واردات مساعدات الإعداد الضيقة
### استيرادات مساعدات الإعداد الضيقة
بالنسبة إلى المسارات الساخنة الخاصة بالإعداد فقط، فَضّل واجهات المساعدات الضيقة هذه بدل الواجهة الأوسع
`plugin-sdk/setup` عندما لا تحتاج إلا إلى جزء من سطح الإعداد:
بالنسبة إلى مسارات الإعداد فقط الساخنة، يُفضَّل استخدام واجهات مساعدات الإعداد
الضيقة بدلًا من الواجهة الأوسع `plugin-sdk/setup` عندما تحتاج فقط إلى جزء من
سطح الإعداد:
| مسار الاستيراد | استخدمه من أجل | الصادرات الأساسية |
| ----------------------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin-sdk/setup-runtime` | مساعدات وقت التشغيل الخاصة بالإعداد التي تبقى متاحة في `setupEntry` / بدء القناة المؤجل | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
| `plugin-sdk/setup-adapter-runtime` | محوّلات إعداد الحساب الواعية بالبيئة | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | مساعدات CLI/التثبيت/الأرشيف/المستندات الخاصة بالإعداد | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| مسار الاستيراد | استخدمه من أجل | التصديرات الأساسية |
| ---------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin-sdk/setup-runtime` | مساعدات وقت التشغيل وقت الإعداد التي تبقى متاحة في `setupEntry` / بدء تشغيل القناة المؤجل | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
| `plugin-sdk/setup-adapter-runtime` | محوّلات إعداد الحساب الواعية بالبيئة | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | مساعدات CLI/الأرشيف/الوثائق الخاصة بالإعداد/التثبيت | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
استخدم الواجهة الأوسع `plugin-sdk/setup` عندما تريد صندوق أدوات الإعداد
المشترك الكامل، بما في ذلك مساعدات تصحيح config مثل
استخدم الواجهة الأوسع `plugin-sdk/setup` عندما تريد مجموعة أدوات الإعداد
المشتركة الكاملة، بما في ذلك مساعدات تصحيح التكوين مثل
`moveSingleAccountChannelSectionToDefaultAccount(...)`.
وتبقى محولات تصحيح الإعداد آمنة في المسار الساخن عند الاستيراد. ويكون
البحث عن سطح العقد الخاص بترقية الحساب الواحد المجمّع كسولًا، لذلك لا يؤدي استيراد
`plugin-sdk/setup-runtime` إلى تحميل اكتشاف سطح العقد المجمّع مبكرًا قبل استخدام
المحول فعليًا.
تبقى محوّلات تصحيح الإعداد آمنة للاستيراد في المسار الساخن. ويكون بحث سطح عقد
ترقية الحساب الفردي المضمّن كسولًا، لذا فإن استيراد
`plugin-sdk/setup-runtime` لا يحمّل مسبقًا اكتشاف سطح العقد المضمّن قبل
استخدام المحوّل فعليًا.
### ترقية الحساب الواحد المملوكة للقناة
### ترقية الحساب الفردي المملوكة للقناة
عندما تنتقل القناة من config ذي مستوى أعلى لحساب واحد إلى
`channels.<id>.accounts.*`، يكون السلوك المشترك الافتراضي هو نقل القيم
التي تقع ضمن نطاق الحساب المرقّى إلى `accounts.default`.
عندما تُرقّي قناة من تكوين علوي لحساب واحد إلى
`channels.<id>.accounts.*`، يكون السلوك الافتراضي المشترك هو نقل القيم
المحددة بنطاق الحساب التي جرت ترقيتها إلى `accounts.default`.
يمكن للقنوات المجمعة تضييق هذه الترقية أو تجاوزها عبر سطح عقد الإعداد
الخاص بها:
يمكن للقنوات المضمّنة تضييق هذه الترقية أو تجاوزها عبر سطح عقد الإعداد الخاص
بها:
- `singleAccountKeysToMove`: مفاتيح إضافية ذات مستوى أعلى ينبغي نقلها إلى
الحساب المرقّى
- `namedAccountPromotionKeys`: عندما تكون الحسابات المسماة موجودة بالفعل، لا تُنقل إلا هذه
المفاتيح إلى الحساب المرقّى؛ بينما تبقى مفاتيح السياسة/التسليم المشتركة في
جذر القناة
- `singleAccountKeysToMove`: مفاتيح علوية إضافية يجب نقلها إلى الحساب الذي
جرت ترقيته
- `namedAccountPromotionKeys`: عندما تكون الحسابات المسماة موجودة بالفعل،
تُنقل هذه المفاتيح فقط إلى الحساب الذي جرت ترقيته؛ بينما تبقى مفاتيح
السياسة/التسليم المشتركة في جذر القناة
- `resolveSingleAccountPromotionTarget(...)`: اختيار الحساب الموجود الذي
يستقبل القيم المرقّاة
سيتلقى القيم التي جرت ترقيتها
تمثل Matrix المثال المجمّع الحالي. وإذا كان هناك حساب Matrix مسمّى واحد موجود
بالفعل، أو إذا كان `defaultAccount` يشير إلى مفتاح غير قانوني موجود
مثل `Ops`، فإن الترقية تحافظ على ذلك الحساب بدل إنشاء إدخال جديد
`accounts.default`.
تُعد Matrix المثال المضمّن الحالي. إذا كان هناك حساب Matrix مسمّى واحد
بالضبط موجود بالفعل، أو إذا كانت `defaultAccount` تشير إلى مفتاح موجود
غير قياسي مثل `Ops`، فإن الترقية تحافظ على ذلك الحساب بدلًا من إنشاء إدخال
جديد `accounts.default`.
## مخطط config
## مخطط التكوين
يُتحقق من config الإضافة مقابل JSON Schema الموجود في manifest الخاص بك. ويهيّئ المستخدمون
الإضافات عبر:
يُتحقق من صحة تكوين Plugin مقابل JSON Schema الموجود في البيان الخاص بك. يقوم
المستخدمون بتكوين Plugins عبر:
```json5
{
@ -367,9 +375,9 @@ export default defineSetupPluginEntry(myChannelPlugin);
}
```
تتلقى إضافتك هذا config على هيئة `api.pluginConfig` أثناء التسجيل.
يتلقى Plugin الخاص بك هذا التكوين على هيئة `api.pluginConfig` أثناء التسجيل.
أما بالنسبة إلى config الخاص بالقناة، فاستخدم قسم config الخاص بالقناة بدلًا من ذلك:
وبالنسبة إلى التكوين الخاص بالقناة، استخدم قسم تكوين القناة بدلًا من ذلك:
```json5
{
@ -382,10 +390,10 @@ export default defineSetupPluginEntry(myChannelPlugin);
}
```
### بناء مخططات config القنوات
### بناء مخططات تكوين القناة
استخدم `buildChannelConfigSchema` من `openclaw/plugin-sdk/core` لتحويل
مخطط Zod إلى الغلاف `ChannelConfigSchema` الذي يتحقق منه OpenClaw:
استخدم `buildChannelConfigSchema` من `openclaw/plugin-sdk/core` لتحويل مخطط
Zod إلى الغلاف `ChannelConfigSchema` الذي يتحقق OpenClaw من صحته:
```typescript
import { z } from "zod";
@ -403,8 +411,8 @@ const configSchema = buildChannelConfigSchema(accountSchema);
## معالجات الإعداد
يمكن لإضافات القنوات توفير معالجات إعداد تفاعلية لـ `openclaw onboard`.
ويكون المعالج عبارة عن كائن `ChannelSetupWizard` على `ChannelPlugin`:
يمكن لـ Plugins القنوات توفير معالجات إعداد تفاعلية للأمر `openclaw onboard`.
والمعالج هو كائن `ChannelSetupWizard` على `ChannelPlugin`:
```typescript
import type { ChannelSetupWizard } from "openclaw/plugin-sdk/channel-setup";
@ -412,19 +420,19 @@ import type { ChannelSetupWizard } from "openclaw/plugin-sdk/channel-setup";
const setupWizard: ChannelSetupWizard = {
channel: "my-channel",
status: {
configuredLabel: "متصل",
unconfiguredLabel: "غير مهيأ",
configuredLabel: "Connected",
unconfiguredLabel: "Not configured",
resolveConfigured: ({ cfg }) => Boolean((cfg.channels as any)?.["my-channel"]?.token),
},
credentials: [
{
inputKey: "token",
providerHint: "my-channel",
credentialLabel: "token البوت",
credentialLabel: "Bot token",
preferredEnvVar: "MY_CHANNEL_BOT_TOKEN",
envPrompt: "هل تريد استخدام MY_CHANNEL_BOT_TOKEN من البيئة؟",
keepPrompt: "هل تريد الاحتفاظ بالـ token الحالي؟",
inputPrompt: "أدخل token البوت:",
envPrompt: "Use MY_CHANNEL_BOT_TOKEN from environment?",
keepPrompt: "Keep current token?",
inputPrompt: "Enter your bot token:",
inspect: ({ cfg, accountId }) => {
const token = (cfg.channels as any)?.["my-channel"]?.token;
return {
@ -437,24 +445,27 @@ const setupWizard: ChannelSetupWizard = {
};
```
يدعم النوع `ChannelSetupWizard` الحقول `credentials` و`textInputs` و
`dmPolicy` و`allowFrom` و`groupAccess` و`prepare` و`finalize` وغيرها.
راجع حزم الإضافات المجمعة (مثلًا إضافة Discord في `src/channel.setup.ts`) للحصول على
يدعم النوع `ChannelSetupWizard` كلاً من `credentials` و`textInputs` و
`dmPolicy` و`allowFrom` و`groupAccess` و`prepare` و`finalize` وغير ذلك.
راجع حزم Plugins المضمّنة (على سبيل المثال Discord plugin في `src/channel.setup.ts`) للاطلاع على
أمثلة كاملة.
بالنسبة إلى مطالبات قائمة السماح في الرسائل المباشرة التي تحتاج فقط إلى التدفق القياسي
`note -> prompt -> parse -> merge -> patch`، فَضّل مساعدات الإعداد
المشتركة من `openclaw/plugin-sdk/setup`: وهي `createPromptParsedAllowFromForAccount(...)`،
و`createTopLevelChannelParsedAllowFromPrompt(...)`، و
بالنسبة إلى مطالبات قائمة السماح للرسائل المباشرة التي تحتاج فقط إلى تدفق
`note -> prompt -> parse -> merge -> patch` القياسي، يُفضَّل استخدام
مساعدات الإعداد المشتركة من `openclaw/plugin-sdk/setup`:
`createPromptParsedAllowFromForAccount(...)`,
`createTopLevelChannelParsedAllowFromPrompt(...)`، و
`createNestedChannelParsedAllowFromPrompt(...)`.
أما لكتل حالة إعداد القناة التي تختلف فقط في التسميات، والدرجات، والأسطر
الإضافية الاختيارية، فَضّل `createStandardChannelSetupStatus(...)` من
`openclaw/plugin-sdk/setup` بدل بناء كائن `status` نفسه يدويًا
في كل إضافة.
وبالنسبة إلى كتل حالة إعداد القناة التي تختلف فقط في التسميات والدرجات
والأسطر الإضافية الاختيارية، يُفضَّل استخدام
`createStandardChannelSetupStatus(...)` من
`openclaw/plugin-sdk/setup` بدلًا من إنشاء الكائن `status` نفسه يدويًا في
كل Plugin.
وبالنسبة إلى أسطح الإعداد الاختيارية التي ينبغي أن تظهر فقط في سياقات معينة، استخدم
`createOptionalChannelSetupSurface` من `openclaw/plugin-sdk/channel-setup`:
بالنسبة إلى أسطح الإعداد الاختيارية التي ينبغي أن تظهر فقط في سياقات معينة،
استخدم `createOptionalChannelSetupSurface` من
`openclaw/plugin-sdk/channel-setup`:
```typescript
import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup";
@ -468,42 +479,43 @@ const setupSurface = createOptionalChannelSetupSurface({
// Returns { setupAdapter, setupWizard }
```
يكشف `plugin-sdk/channel-setup` أيضًا عن البانيين الأدنى مستوى
يكشف `plugin-sdk/channel-setup` أيضًا عن البنّائين الأدنى مستوى
`createOptionalChannelSetupAdapter(...)` و
`createOptionalChannelSetupWizard(...)` عندما تحتاج إلى نصف واحد فقط من
سطح التثبيت الاختياري هذا.
يفشل المحول/المعالج الاختياريان المولدان بشكل مغلق عند عمليات كتابة config الحقيقية. كما
يعيدان استخدام رسالة واحدة تفيد بأن التثبيت مطلوب عبر `validateInput` و
`applyAccountConfig` و`finalize`، ويُلحقان رابطًا للمستندات عندما يكون `docsPath`
مضبوطًا.
يفشل المحوّل/المعالج الاختياري المُنشأ بشكل آمن عند عمليات كتابة التكوين
الفعلية. ويعيدان استخدام رسالة واحدة تفيد بضرورة التثبيت عبر
`validateInput` و`applyAccountConfig` و`finalize`، ويُلحقان رابط وثائق
عندما يكون `docsPath` مضبوطًا.
أما بالنسبة إلى واجهات إعداد UI المدعومة بملفات تنفيذية، فَضّل المساعدات المشتركة المفوّضة بدل
نسخ نفس منطق الملف التنفيذي/الحالة في كل قناة:
بالنسبة إلى واجهات إعداد المستخدم المدعومة بملفات تنفيذية، يُفضَّل استخدام
المساعدات المشتركة المفوّضة بدلًا من نسخ منطق الربط نفسه الخاص بالملف
التنفيذي/الحالة إلى كل قناة:
- `createDetectedBinaryStatus(...)` لكتل الحالة التي تختلف فقط بحسب التسميات،
- `createDetectedBinaryStatus(...)` لكتل الحالة التي تختلف فقط في التسميات،
والتلميحات، والدرجات، واكتشاف الملف التنفيذي
- `createCliPathTextInput(...)` لمدخلات النص المدعومة بالمسار
- `createCliPathTextInput(...)` لإدخالات النص المدعومة بالمسار
- `createDelegatedSetupWizardStatusResolvers(...)`،
و`createDelegatedPrepare(...)`، و`createDelegatedFinalize(...)`، و
`createDelegatedResolveConfigured(...)` عندما يحتاج `setupEntry` إلى الإحالة
كسولًا إلى معالج أثقل وكامل
`createDelegatedPrepare(...)`، `createDelegatedFinalize(...)`، و
`createDelegatedResolveConfigured(...)` عندما يحتاج `setupEntry` إلى
التمرير إلى معالج كامل أثقل بشكل كسول
- `createDelegatedTextInputShouldPrompt(...)` عندما يحتاج `setupEntry` فقط إلى
تفويض قرار `textInputs[*].shouldPrompt`
## النشر والتثبيت
**الإضافات الخارجية:** انشرها على [ClawHub](/ar/tools/clawhub) أو npm، ثم ثبّتها:
**Plugins الخارجية:** انشر إلى [ClawHub](/ar/tools/clawhub) أو npm، ثم ثبّت:
```bash
openclaw plugins install @myorg/openclaw-my-plugin
```
يحاول OpenClaw استخدام ClawHub أولًا ثم يرجع إلى npm تلقائيًا. ويمكنك أيضًا
فرض ClawHub صراحةً:
يجرّب OpenClaw أولًا ClawHub ثم يعود تلقائيًا إلى npm. يمكنك أيضًا
فرض ClawHub صراحة:
```bash
openclaw plugins install clawhub:@myorg/openclaw-my-plugin # ClawHub فقط
openclaw plugins install clawhub:@myorg/openclaw-my-plugin # ClawHub only
```
لا يوجد تجاوز مماثل لـ `npm:`. استخدم مواصفة حزمة npm العادية عندما
@ -513,7 +525,7 @@ openclaw plugins install clawhub:@myorg/openclaw-my-plugin # ClawHub فقط
openclaw plugins install @myorg/openclaw-my-plugin
```
**الإضافات داخل المستودع:** ضعها تحت شجرة مساحة عمل الإضافات المجمعة وسيتم
**Plugins داخل المستودع:** ضعها ضمن شجرة مساحة عمل Plugins المضمّنة وسيتم
اكتشافها تلقائيًا أثناء البناء.
**يمكن للمستخدمين التثبيت:**
@ -523,13 +535,14 @@ openclaw plugins install <package-name>
```
<Info>
بالنسبة إلى التثبيتات القادمة من npm، يشغّل `openclaw plugins install`
الأمر `npm install --ignore-scripts` (من دون lifecycle scripts). أبقِ شجرة اعتماديات الإضافة
JavaScript/TypeScript خالصة وتجنب الحزم التي تتطلب بناء `postinstall`.
بالنسبة إلى عمليات التثبيت ذات المصدر npm، يقوم `openclaw plugins install`
بتشغيل `npm install --ignore-scripts` (من دون نصوص دورة الحياة). حافظ على
أشجار تبعيات Plugin بلغة JS/TS خالصة وتجنب الحزم التي تتطلب بناء
`postinstall`.
</Info>
## ذو صلة
- [نقاط إدخال SDK](/ar/plugins/sdk-entrypoints) -- `definePluginEntry` و`defineChannelPluginEntry`
- [Plugin Manifest](/ar/plugins/manifest) -- المرجع الكامل لمخطط manifest
- [بناء الإضافات](/ar/plugins/building-plugins) -- دليل بدء خطوة بخطوة
- [نقاط إدخال SDK](/ar/plugins/sdk-entrypoints) -- `definePluginEntry` و `defineChannelPluginEntry`
- [بيان Plugin](/ar/plugins/manifest) -- المرجع الكامل لمخطط البيان
- [بناء Plugins](/ar/plugins/building-plugins) -- دليل بدء خطوة بخطوة

96
docs/ar/plugins/sdk-testing.md
View File

@ -1,35 +1,35 @@
---
read_when:
- أنت تكتب اختبارات لـ plugin
- أنت تكتب اختبارات لإضافة Plugin
- أنت بحاجة إلى أدوات اختبار من Plugin SDK
- أنت تريد فهم اختبارات العقد الخاصة بالـ plugins المضمّنة
- تريد فهم اختبارات العقد للإضافات المضمنة
sidebarTitle: Testing
summary: أدوات وأنماط الاختبار الخاصة بـ Plugins في OpenClaw
title: اختبار Plugins
summary: أدوات الاختبار والأنماط الخاصة بإضافات OpenClaw
title: اختبار الإضافات
x-i18n:
generated_at: "2026-04-05T12:52:16Z"
generated_at: "2026-04-15T19:41:39Z"
model: gpt-5.4
provider: openai
source_hash: 2e95ed58ed180feadad17bb5138bd09e3b45f1f3ecdff4e2fba4874bb80099fe
source_hash: 2f75bd3f3b5ba34b05786e0dd96d493c36db73a1d258998bf589e27e45c0bd09
source_path: plugins/sdk-testing.md
workflow: 15
---
# اختبار Plugins
# اختبار الإضافات
مرجع لأدوات الاختبار والأنماط وفرض lint الخاصة بـ Plugins في OpenClaw.
مرجع لأدوات الاختبار والأنماط وفرض قواعد lint لإضافات OpenClaw.
<Tip>
**هل تبحث عن أمثلة اختبارات؟** تتضمن الأدلة العملية أمثلة اختبارات جاهزة:
[اختبارات plugin القناة](/plugins/sdk-channel-plugins#step-6-test) و
[اختبارات plugin الموفّر](/plugins/sdk-provider-plugins#step-6-test).
**هل تبحث عن أمثلة للاختبارات؟** تتضمن أدلة الشرح العملية أمثلة اختبار مكتملة:
[اختبارات إضافات القنوات](/ar/plugins/sdk-channel-plugins#step-6-test) و
[اختبارات إضافات المزوّدين](/ar/plugins/sdk-provider-plugins#step-6-test).
</Tip>
## أدوات الاختبار
**الاستيراد:** `openclaw/plugin-sdk/testing`
يكشف المسار الفرعي الخاص بالاختبار مجموعة ضيقة من المساعدات لمطوري plugins:
يُصدّر المسار الفرعي الخاص بالاختبار مجموعة محدودة من المساعدات لمؤلفي الإضافات:
```typescript
import {
@ -39,17 +39,17 @@ import {
} from "openclaw/plugin-sdk/testing";
```
### الصادرات المتاحة
### العناصر المصدّرة المتاحة
| التصدير | الغرض |
| العنصر المصدَّر | الغرض |
| -------------------------------------- | ------------------------------------------------------ |
| `installCommonResolveTargetErrorCases` | حالات اختبار مشتركة لأخطاء تحليل الهدف |
| `shouldAckReaction` | التحقق مما إذا كانت القناة يجب أن تضيف تفاعل ack |
| `removeAckReactionAfterReply` | إزالة تفاعل ack بعد تسليم الرد |
| `installCommonResolveTargetErrorCases` | حالات اختبار مشتركة لمعالجة أخطاء حل الهدف |
| `shouldAckReaction` | التحقق مما إذا كان يجب على القناة إضافة تفاعل إقرار |
| `removeAckReactionAfterReply` | إزالة تفاعل الإقرار بعد تسليم الرد |
### الأنواع
يعيد المسار الفرعي الخاص بالاختبار أيضًا تصدير أنواع مفيدة داخل ملفات الاختبار:
يعيد المسار الفرعي الخاص بالاختبار أيضًا تصدير أنواع مفيدة في ملفات الاختبار:
```typescript
import type {
@ -62,10 +62,9 @@ import type {
} from "openclaw/plugin-sdk/testing";
```
## اختبار تحليل الأهداف
## اختبار حل الهدف
استخدم `installCommonResolveTargetErrorCases` لإضافة حالات الأخطاء القياسية
لتحليل أهداف القناة:
استخدم `installCommonResolveTargetErrorCases` لإضافة حالات الخطأ القياسية لحل هدف القناة:
```typescript
import { describe } from "vitest";
@ -89,7 +88,7 @@ describe("my-channel target resolution", () => {
## أنماط الاختبار
### اختبار وحدة لـ plugin قناة
### اختبار وحدة لإضافة قناة
```typescript
import { describe, it, expect, vi } from "vitest";
@ -125,7 +124,7 @@ describe("my-channel plugin", () => {
});
```
### اختبار وحدة لـ plugin موفّر
### اختبار وحدة لإضافة مزوّد
```typescript
import { describe, it, expect } from "vitest";
@ -153,15 +152,18 @@ describe("my-provider plugin", () => {
});
```
### محاكاة وقت تشغيل plugin
### محاكاة Runtime الخاص بالإضافة
بالنسبة إلى الشيفرة التي تستخدم `createPluginRuntimeStore`، قم بمحاكاة وقت التشغيل في الاختبارات:
بالنسبة إلى الشيفرة التي تستخدم `createPluginRuntimeStore`، قم بمحاكاة runtime في الاختبارات:
```typescript
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";
const store = createPluginRuntimeStore<PluginRuntime>("test runtime not set");
const store = createPluginRuntimeStore<PluginRuntime>({
pluginId: "test-plugin",
errorMessage: "test runtime not set",
});
// In test setup
const mockRuntime = {
@ -182,9 +184,9 @@ store.setRuntime(mockRuntime);
store.clearRuntime();
```
### الاختبار باستخدام stubs لكل مثيل
### الاختبار باستخدام بدائل على مستوى المثيل
فضّل استخدام stubs لكل مثيل بدلًا من تغيير prototype:
فضّل استخدام البدائل على مستوى المثيل بدلًا من تعديل prototype:
```typescript
// Preferred: per-instance stub
@ -195,24 +197,24 @@ client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" });
// MyChannelClient.prototype.sendMessage = vi.fn();
```
## اختبارات العقد (plugins داخل المستودع)
## اختبارات العقد (الإضافات داخل المستودع)
تحتوي plugins المضمّنة على اختبارات عقد تتحقق من ملكية التسجيل:
تحتوي الإضافات المضمنة على اختبارات عقد تتحقق من ملكية التسجيل:
```bash
pnpm test -- src/plugins/contracts/
```
تؤكد هذه الاختبارات:
تؤكد هذه الاختبارات ما يلي:
- أي plugins تسجل أي موفّرين
- أي plugins تسجل أي موفري كلام
- أي الإضافات تسجل أي مزوّدين
- أي الإضافات تسجل أي مزوّدي speech
- صحة شكل التسجيل
- الامتثال لعقد وقت التشغيل
- الامتثال لعقد Runtime
### تشغيل اختبارات محددة النطاق
بالنسبة إلى plugin محدد:
لإضافة محددة:
```bash
pnpm test -- <bundled-plugin-root>/my-channel/
@ -226,19 +228,19 @@ pnpm test -- src/plugins/contracts/auth.contract.test.ts
pnpm test -- src/plugins/contracts/runtime.contract.test.ts
```
## فرض lint ‏(plugins داخل المستودع)
## فرض قواعد lint (الإضافات داخل المستودع)
يتم فرض ثلاث قواعد بواسطة `pnpm check` على plugins داخل المستودع:
يتم فرض ثلاث قواعد بواسطة `pnpm check` للإضافات داخل المستودع:
1. **لا استيرادات جذرية ضخمة** -- يتم رفض root barrel ‏`openclaw/plugin-sdk`
2. **لا استيرادات مباشرة من `src/`** -- لا يمكن للـ plugins الاستيراد من `../../src/` مباشرة
3. **لا استيرادات ذاتية** -- لا يمكن للـ plugins استيراد مسارها الفرعي `plugin-sdk/<name>` الخاص بها
1. **عدم استخدام استيرادات الجذر الأحادية** -- يتم رفض الحزمة المجمعة الجذرية `openclaw/plugin-sdk`
2. **عدم استخدام استيرادات `src/` المباشرة** -- لا يمكن للإضافات الاستيراد مباشرة من `../../src/`
3. **عدم استخدام الاستيراد الذاتي** -- لا يمكن للإضافات استيراد مسارها الفرعي `plugin-sdk/<name>` الخاص بها
لا تخضع plugins الخارجية لقواعد lint هذه، لكن يُوصى باتباع الأنماط نفسها.
لا تخضع الإضافات الخارجية لقواعد lint هذه، ولكن يُنصح باتباع الأنماط نفسها.
## إعداد الاختبار
يستخدم OpenClaw أداة Vitest مع حدود تغطية V8. وبالنسبة إلى اختبارات plugins:
يستخدم OpenClaw أداة Vitest مع حدود تغطية V8. بالنسبة لاختبارات الإضافات:
```bash
# Run all tests
@ -254,7 +256,7 @@ pnpm test -- <bundled-plugin-root>/my-channel/ -t "resolves account"
pnpm test:coverage
```
إذا سببت التشغيلات المحلية ضغطًا على الذاكرة:
إذا كانت عمليات التشغيل المحلية تسبب ضغطًا على الذاكرة:
```bash
OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test
@ -262,7 +264,7 @@ OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test
## ذو صلة
- [نظرة عامة على SDK](/plugins/sdk-overview) -- اصطلاحات الاستيراد
- [SDK الخاص بـ Plugins القنوات](/plugins/sdk-channel-plugins) -- واجهة plugin القناة
- [SDK الخاص بـ Plugins الموفّر](/plugins/sdk-provider-plugins) -- خطافات plugin الموفّر
- [بناء Plugins](/plugins/building-plugins) -- دليل البدء
- [نظرة عامة على SDK](/ar/plugins/sdk-overview) -- اصطلاحات الاستيراد
- [إضافات قنوات SDK](/ar/plugins/sdk-channel-plugins) -- واجهة إضافة القناة
- [إضافات مزوّدي SDK](/ar/plugins/sdk-provider-plugins) -- خطافات إضافة المزوّد
- [بناء الإضافات](/ar/plugins/building-plugins) -- دليل البدء

188
docs/ar/reference/token-use.md
View File

@ -1,96 +1,103 @@
---
read_when:
- شرح استخدام الرموز أو التكاليف أو نوافذ السياق
- تصحيح نمو السياق أو سلوك الضغط
summary: كيف يبني OpenClaw سياق المطالبة ويبلّغ عن استخدام الرموز والتكاليف
- تصحيح نمو السياق أو سلوك Compaction
summary: كيف يبني OpenClaw سياق الـ prompt ويعرض استخدام الرموز والتكاليف
title: استخدام الرموز والتكاليف
x-i18n:
generated_at: "2026-04-12T07:16:07Z"
generated_at: "2026-04-15T19:42:07Z"
model: gpt-5.4
provider: openai
source_hash: f8c856549cd28b8364a640e6fa9ec26aa736895c7a993e96cbe85838e7df2dfb
source_hash: 9a706d3df8b2ea1136b3535d216c6b358e43aee2a31a4759824385e1345e6fe5
source_path: reference/token-use.md
workflow: 15
---
# استخدام الرموز والتكاليف
يتتبع OpenClaw **الرموز** وليس الأحرف. وتختلف الرموز حسب النموذج، لكن معظم
النماذج على نمط OpenAI يبلغ متوسطها نحو 4 أحرف لكل رمز في النص الإنجليزي.
يتتبع OpenClaw **الرموز**، وليس الأحرف. تختلف الرموز حسب النموذج، لكن معظم النماذج بأسلوب OpenAI يكون متوسطها نحو 4 أحرف لكل رمز في النص الإنجليزي.
## كيف تُبنى مطالبة النظام
## كيف يُبنى system prompt
يجمع OpenClaw مطالبة النظام الخاصة به في كل تشغيل. وهي تتضمن:
يقوم OpenClaw بتجميع system prompt الخاص به في كل تشغيل. ويتضمن ما يلي:
- قائمة الأدوات + أوصافًا قصيرة
- قائمة Skills (بيانات وصفية فقط؛ وتُحمَّل التعليمات عند الطلب باستخدام `read`)
- قائمة الأدوات + أوصاف قصيرة
- قائمة Skills (بيانات وصفية فقط؛ تُحمَّل التعليمات عند الطلب باستخدام `read`).
تكون كتلة Skills المضغوطة محدودة بواسطة `skills.limits.maxSkillsPromptChars`،
مع إمكانية التجاوز لكل وكيل بشكل اختياري عند
`agents.list[].skillsLimits.maxSkillsPromptChars`.
- تعليمات التحديث الذاتي
- مساحة العمل + ملفات التهيئة الأولية (`AGENTS.md` و`SOUL.md` و`TOOLS.md` و`IDENTITY.md` و`USER.md` و`HEARTBEAT.md` و`BOOTSTRAP.md` عند الجديد، بالإضافة إلى `MEMORY.md` عند وجوده أو `memory.md` كبديل بأحرف صغيرة). تُقتطع الملفات الكبيرة بواسطة `agents.defaults.bootstrapMaxChars` (الافتراضي: 20000)، ويُحدد حد أعلى لإجمالي حقن التهيئة الأولية بواسطة `agents.defaults.bootstrapTotalMaxChars` (الافتراضي: 150000). ولا تُعد ملفات `memory/*.md` اليومية جزءًا من مطالبة التهيئة الأولية العادية؛ بل تظل عند الطلب عبر أدوات الذاكرة في الأدوار العادية، لكن يمكن لأوامر `/new` و`/reset` المجردة أن تسبقها بكتلة سياق بدء لمرة واحدة تتضمن الذاكرة اليومية الحديثة لذلك الدور الأول. ويُتحكم في تمهيد البدء هذا بواسطة `agents.defaults.startupContext`.
- ملفات مساحة العمل + ملفات bootstrap (`AGENTS.md` و`SOUL.md` و`TOOLS.md` و`IDENTITY.md` و`USER.md` و`HEARTBEAT.md` و`BOOTSTRAP.md` عند كونها جديدة، بالإضافة إلى `MEMORY.md` عند وجوده أو `memory.md` كبديل بأحرف صغيرة). تُقتطع الملفات الكبيرة بواسطة `agents.defaults.bootstrapMaxChars` (الافتراضي: 12000)، ويكون الحد الأقصى الإجمالي لحقن bootstrap هو `agents.defaults.bootstrapTotalMaxChars` (الافتراضي: 60000). لا تُعد ملفات `memory/*.md` اليومية جزءًا من prompt bootstrap العادي؛ بل تبقى عند الطلب عبر أدوات الذاكرة في الأدوار العادية، لكن يمكن لأوامر `/new` و`/reset` المجردة إلحاق كتلة سياق بدء تشغيل لمرة واحدة تحتوي على الذاكرة اليومية الحديثة لذلك الدور الأول. ويتم التحكم في هذه المقدمة الابتدائية بواسطة `agents.defaults.startupContext`.
- الوقت (UTC + المنطقة الزمنية للمستخدم)
- وسوم الرد + سلوك نبضات القلب
- بيانات وصفية لوقت التشغيل (المضيف/نظام التشغيل/النموذج/التفكير)
- وسوم الرد + سلوك Heartbeat
- بيانات Runtime الوصفية (المضيف/نظام التشغيل/النموذج/التفكير)
راجع التفصيل الكامل في [مطالبة النظام](/ar/concepts/system-prompt).
راجع التفصيل الكامل في [System Prompt](/ar/concepts/system-prompt).
## ما الذي يُحتسب ضمن نافذة السياق
كل ما يتلقاه النموذج يُحتسب ضمن حد السياق:
- مطالبة النظام (كل الأقسام المذكورة أعلاه)
- سجل المحادثة (رسائل المستخدم + المساعد)
- استدعاءات الأدوات ونتائج الأدوات
- system prompt (جميع الأقسام المذكورة أعلاه)
- محفوظات المحادثة (رسائل المستخدم + المساعد)
- استدعاءات الأدوات ونتائجها
- المرفقات/التفريغات (الصور والصوت والملفات)
- ملخصات الضغط وآثار التقليم
- أغلفة الموفر أو ترويسات السلامة (غير مرئية، لكنها ما تزال تُحتسب)
- ملخصات Compaction وعناصر التقليم
- أغلفة المزوّد أو ترويسات الأمان (غير مرئية، لكنها ما تزال محتسبة)
بالنسبة إلى الصور، يقوم OpenClaw بتصغير حمولات صور التفريغ/الأدوات قبل
استدعاءات الموفر.
لبعض الأسطح الثقيلة وقت التشغيل حدود صريحة خاصة بها:
- `agents.defaults.contextLimits.memoryGetMaxChars`
- `agents.defaults.contextLimits.memoryGetDefaultLines`
- `agents.defaults.contextLimits.toolResultMaxChars`
- `agents.defaults.contextLimits.postCompactionMaxChars`
توجد التجاوزات الخاصة بكل وكيل تحت `agents.list[].contextLimits`. هذه المفاتيح
مخصصة للمقتطفات المحدودة وقت التشغيل والكتل المحقونة المملوكة لوقت التشغيل. وهي
منفصلة عن حدود bootstrap، وحدود سياق بدء التشغيل، وحدود prompt الخاصة بـ Skills.
بالنسبة للصور، يقوم OpenClaw بتصغير أحجام حمولات صور التفريغ/الأدوات قبل استدعاءات المزوّد.
استخدم `agents.defaults.imageMaxDimensionPx` (الافتراضي: `1200`) لضبط ذلك:
- تؤدي القيم الأقل عادةً إلى تقليل استخدام رموز الرؤية وحجم الحمولة.
- وتحافظ القيم الأعلى على مزيد من التفاصيل البصرية للصور الثقيلة على OCR/واجهات المستخدم.
- القيم الأقل تقلل عادةً استخدام رموز الرؤية وحجم الحمولة.
- القيم الأعلى تحافظ على مزيد من التفاصيل البصرية لعمليات OCR ولقطات الشاشة الثقيلة بواجهات المستخدم.
للحصول على تفصيل عملي (لكل ملف محقون، والأدوات، وSkills، وحجم مطالبة النظام)، استخدم `/context list` أو `/context detail`. راجع [السياق](/ar/concepts/context).
للحصول على تفصيل عملي (لكل ملف محقون، والأدوات، وSkills، وحجم system prompt)، استخدم `/context list` أو `/context detail`. راجع [Context](/ar/concepts/context).
## كيفية رؤية استخدام الرموز الحالي
استخدم ما يلي في الدردشة:
- `/status` ← **بطاقة حالة غنية بالرموز التعبيرية** تتضمن نموذج الجلسة، واستخدام السياق،
ورموز الإدخال/الإخراج لآخر استجابة، و**التكلفة التقديرية** (مفتاح API فقط).
- `/usage off|tokens|full` ← يضيف **تذييل استخدام لكل استجابة** إلى كل رد.
- يستمر لكل جلسة (ويُخزَّن باسم `responseUsage`).
- مصادقة OAuth **تخفي التكلفة** (الرموز فقط).
- `/usage cost` ← يعرض ملخصًا محليًا للتكلفة من سجلات جلسات OpenClaw.
- `/status` ← **بطاقة حالة غنية بالرموز التعبيرية** تعرض نموذج الجلسة، واستخدام السياق،
ورموز الإدخال/الإخراج لآخر استجابة، و**التكلفة التقديرية** (عند استخدام مفتاح API فقط).
- `/usage off|tokens|full` ← يُلحق **تذييل استخدام لكل استجابة** بكل رد.
- يُحفَظ لكل جلسة (ويُخزَّن باعتباره `responseUsage`).
- تخفي مصادقة OAuth **التكلفة** (الرموز فقط).
- `/usage cost` ← يعرض ملخص تكلفة محليًا من سجلات جلسة OpenClaw.
واجهات أخرى:
أسطح أخرى:
- **TUI/Web TUI:** يدعمان `/status` و`/usage`.
- **TUI/Web TUI:** يتم دعم `/status` و`/usage`.
- **CLI:** يعرض `openclaw status --usage` و`openclaw channels list`
نوافذ حصة الموفر الموحدة (`X% left`، وليس تكاليف لكل استجابة).
موفرو نافذة الاستخدام الحاليون: Anthropic وGitHub Copilot وGemini CLI
نوافذ حصص المزوّد الموحّدة (`X% left`، وليس التكاليف لكل استجابة).
مزوّدو نوافذ الاستخدام الحاليون: Anthropic وGitHub Copilot وGemini CLI
وOpenAI Codex وMiniMax وXiaomi وz.ai.
تُوحد واجهات الاستخدام الأسماء المستعارة الشائعة الأصلية من الموفر قبل العرض.
وبالنسبة إلى حركة Responses من عائلة OpenAI، يشمل ذلك كلًا من `input_tokens` /
`output_tokens` و`prompt_tokens` / `completion_tokens`، بحيث لا تؤدي أسماء
الحقول الخاصة بالنقل إلى تغيير `/status` أو `/usage` أو ملخصات الجلسات.
كما يُوحد استخدام JSON الخاص بـ Gemini CLI أيضًا: يأتي نص الرد من `response`،
وتُحوَّل `stats.cached` إلى `cacheRead` مع استخدام `stats.input_tokens - stats.cached`
عندما يهمل CLI حقل `stats.input` الصريح.
وبالنسبة إلى حركة Responses الأصلية من عائلة OpenAI، تُوحَّد الأسماء المستعارة
لاستخدام WebSocket/SSE بالطريقة نفسها، وتعود المجاميع إلى الإدخال + الإخراج
الموحَّدين عندما يكون `total_tokens` مفقودًا أو يساوي `0`.
وعندما تكون لقطة الجلسة الحالية متناثرة، يمكن لـ `/status` و`session_status`
أيضًا استعادة عدادات الرموز/التخزين المؤقت ووسم نموذج وقت التشغيل النشط من
أحدث سجل استخدام في التفريغ. وتظل القيم الحية غير الصفرية الموجودة لها
الأولوية على القيم الاحتياطية من التفريغ، ويمكن أن تفوز مجاميع التفريغ الأكبر
الموجهة للمطالبة عندما تكون المجاميع المخزنة مفقودة أو أصغر.
وتأتي مصادقة الاستخدام الخاصة بنوافذ حصة الموفر من خطافات خاصة بالموفر عند
توفرها؛ وإلا يعود OpenClaw إلى مطابقة بيانات اعتماد OAuth/مفتاح API من ملفات
المصادقة أو البيئة أو الإعدادات.
تقوم أسطح الاستخدام بتوحيد الأسماء البديلة الشائعة الأصلية للمزوّد قبل العرض.
وبالنسبة لحركة Responses من عائلة OpenAI، يشمل ذلك كلاً من `input_tokens` /
`output_tokens` و`prompt_tokens` / `completion_tokens`، بحيث لا تؤدي
أسماء الحقول الخاصة بالنقل إلى تغيير `/status` أو `/usage` أو ملخصات الجلسات.
كما يتم أيضًا توحيد استخدام JSON الخاص بـ Gemini CLI: يأتي نص الرد من `response`،
ويُطابِق `stats.cached` إلى `cacheRead` مع استخدام `stats.input_tokens - stats.cached`
عندما تحذف CLI الحقل الصريح `stats.input`.
وبالنسبة لحركة Responses الأصلية من عائلة OpenAI، يتم توحيد الأسماء البديلة للاستخدام في WebSocket/SSE بالطريقة نفسها، وتعود المجاميع إلى الإدخال + الإخراج الموحّدين عندما يكون
`total_tokens` مفقودًا أو يساوي `0`.
وعندما تكون لقطة الجلسة الحالية متناثرة، يمكن أيضًا لـ `/status` و`session_status`
استعادة عدادات الرموز/الذاكرة المؤقتة ووسم نموذج Runtime النشط من أحدث سجل استخدام في التفريغ.
وتبقى القيم الحية غير الصفرية الموجودة مسبقًا ذات أولوية على قيم الرجوع إلى التفريغ، ويمكن أن تفوز المجاميع الأكبر المرتبطة بـ prompt في التفريغ عندما تكون المجاميع المخزنة مفقودة أو أصغر.
تأتي مصادقة الاستخدام الخاصة بنوافذ حصص المزوّد من الخطافات الخاصة بالمزوّد عند توفرها؛ وإلا يعود OpenClaw إلى مطابقة بيانات اعتماد OAuth/مفتاح API من ملفات تعريف المصادقة أو البيئة أو الإعدادات.
## تقدير التكلفة (عند عرضه)
## تقدير التكلفة (عند العرض)
تُقدَّر التكاليف من إعدادات تسعير النموذج لديك:
@ -98,38 +105,26 @@ x-i18n:
models.providers.<provider>.models[].cost
```
وهذه هي **دولارات أمريكية لكل مليون رمز** لكل من `input` و`output` و`cacheRead` و
`cacheWrite`. وإذا كانت التسعيرة مفقودة، فسيعرض OpenClaw الرموز فقط. كما أن
رموز OAuth لا تعرض التكلفة بالدولار مطلقًا.
وهذه القيم هي **بالدولار الأمريكي لكل مليون رمز** لكل من `input` و`output` و`cacheRead` و`cacheWrite`. وإذا كانت التسعيرة مفقودة، فسيعرض OpenClaw الرموز فقط. لا تعرض رموز OAuth تكلفة بالدولار مطلقًا.
## تأثير TTL للتخزين المؤقت والتقليم
## تأثير TTL الخاص بالذاكرة المؤقتة والتقليم
لا ينطبق التخزين المؤقت لمطالبة الموفر إلا ضمن نافذة TTL الخاصة بالتخزين
المؤقت. ويمكن لـ OpenClaw اختياريًا تشغيل **تقليم cache-ttl**: إذ يقلّم
الجلسة بمجرد انتهاء TTL للتخزين المؤقت، ثم يعيد تعيين نافذة التخزين المؤقت
بحيث يمكن للطلبات اللاحقة إعادة استخدام السياق المُخزَّن مؤخرًا بدلًا من
إعادة تخزين السجل الكامل مؤقتًا. ويساعد ذلك على إبقاء تكاليف كتابة التخزين
المؤقت أقل عندما تبقى الجلسة خاملة بعد TTL.
لا ينطبق التخزين المؤقت لـ prompt الخاص بالمزوّد إلا ضمن نافذة TTL الخاصة بالذاكرة المؤقتة. يمكن لـ OpenClaw اختياريًا تشغيل **تقليم cache-ttl**: حيث يقوم بتقليم الجلسة بمجرد انتهاء TTL الخاص بالذاكرة المؤقتة، ثم يعيد ضبط نافذة الذاكرة المؤقتة حتى تتمكن الطلبات اللاحقة من إعادة استخدام السياق المُخزَّن حديثًا بدلًا من إعادة تخزين المحفوظات الكاملة مؤقتًا. وهذا يُبقي تكاليف كتابة الذاكرة المؤقتة أقل عندما تبقى الجلسة خاملة بعد TTL.
اضبط ذلك في [إعدادات Gateway](/ar/gateway/configuration) وراجع تفاصيل السلوك في
[تقليم الجلسة](/ar/concepts/session-pruning).
قم بإعداده في [إعداد Gateway](/ar/gateway/configuration) وراجع تفاصيل السلوك في [تقليم الجلسة](/ar/concepts/session-pruning).
يمكن لنبضات القلب إبقاء التخزين المؤقت **دافئًا** عبر فجوات الخمول. فإذا كان
TTL للتخزين المؤقت في نموذجك هو `1h`، فإن ضبط فترة نبضات القلب إلى أقل قليلًا
من ذلك (مثلًا `55m`) يمكن أن يتجنب إعادة تخزين المطالبة الكاملة مؤقتًا، مما
يقلل تكاليف كتابة التخزين المؤقت.
يمكن لـ Heartbeat إبقاء الذاكرة المؤقتة **دافئة** خلال فترات الخمول. إذا كان TTL لذاكرة النموذج المؤقتة لديك هو `1h`، فإن ضبط فاصل Heartbeat إلى ما دون ذلك بقليل (مثل `55m`) يمكن أن يتجنب إعادة تخزين prompt الكامل مؤقتًا، مما يقلل تكاليف كتابة الذاكرة المؤقتة.
في إعدادات الوكلاء المتعددين، يمكنك الاحتفاظ بإعداد نموذج مشترك واحد وضبط سلوك
التخزين المؤقت لكل وكيل عبر `agents.list[].params.cacheRetention`.
في إعدادات الوكلاء المتعددين، يمكنك الاحتفاظ بإعداد نموذج مشترك واحد وضبط سلوك الذاكرة المؤقتة
لكل وكيل عبر `agents.list[].params.cacheRetention`.
وللحصول على دليل كامل لكل خيار على حدة، راجع [التخزين المؤقت للمطالبة](/ar/reference/prompt-caching).
للحصول على دليل كامل لكل مفتاح إعداد على حدة، راجع [Prompt Caching](/ar/reference/prompt-caching).
بالنسبة إلى تسعير Anthropic API، تكون قراءات التخزين المؤقت أرخص بكثير من
رموز الإدخال، بينما تُفوتر كتابات التخزين المؤقت بمعامل أعلى. راجع تسعير
التخزين المؤقت للمطالبة لدى Anthropic للاطلاع على أحدث الأسعار ومعاملات TTL:
بالنسبة إلى تسعير Anthropic API، تكون قراءات الذاكرة المؤقتة أرخص بكثير من
رموز الإدخال، بينما تُفوتر كتابات الذاكرة المؤقتة بمعامل أعلى. راجع تسعير التخزين المؤقت لـ prompt الخاص بـ Anthropic لأحدث الأسعار ومعاملات TTL:
[https://docs.anthropic.com/docs/build-with-claude/prompt-caching](https://docs.anthropic.com/docs/build-with-claude/prompt-caching)
### مثال: إبقاء التخزين المؤقت لمدة 1h دافئًا باستخدام نبضات القلب
### مثال: إبقاء ذاكرة مؤقتة لمدة 1h دافئة باستخدام Heartbeat
```yaml
agents:
@ -144,7 +139,7 @@ agents:
every: "55m"
```
### مثال: حركة مختلطة مع استراتيجية تخزين مؤقت لكل وكيل
### مثال: حركة مختلطة مع استراتيجية ذاكرة مؤقتة لكل وكيل
```yaml
agents:
@ -154,25 +149,24 @@ agents:
models:
"anthropic/claude-opus-4-6":
params:
cacheRetention: "long" # خط أساس افتراضي لمعظم الوكلاء
cacheRetention: "long" # baseline الافتراضي لمعظم الوكلاء
list:
- id: "research"
default: true
heartbeat:
every: "55m" # إبقاء التخزين المؤقت الطويل دافئًا للجلسات العميقة
every: "55m" # إبقاء الذاكرة المؤقتة الطويلة دافئة للجلسات العميقة
- id: "alerts"
params:
cacheRetention: "none" # تجنب كتابات التخزين المؤقت للإشعارات المتدفقة
cacheRetention: "none" # تجنب كتابات الذاكرة المؤقتة للإشعارات المتدفقة
```
يُدمج `agents.list[].params` فوق `params` الخاصة بالنموذج المحدد، لذا يمكنك
تجاوز `cacheRetention` فقط مع إبقاء إعدادات النموذج الافتراضية الأخرى كما هي.
يُدمَج `agents.list[].params` فوق `params` الخاص بالنموذج المحدد، بحيث يمكنك
تجاوز `cacheRetention` فقط مع إبقاء بقية إعدادات النموذج الافتراضية كما هي.
### مثال: تمكين ترويسة Anthropic 1M context التجريبية
### مثال: تفعيل ترويسة Anthropic التجريبية لسياق 1M
إن نافذة السياق 1M لدى Anthropic تخضع حاليًا لبوابة تجريبية. ويمكن لـ OpenClaw
حقن قيمة `anthropic-beta` المطلوبة عندما تمكّن `context1m` على نماذج Opus أو
Sonnet المدعومة.
تكون نافذة السياق 1M من Anthropic حاليًا خلف بوابة تجريبية. يمكن لـ OpenClaw حقن قيمة `anthropic-beta` المطلوبة عند تفعيل `context1m` على نماذج Opus
أو Sonnet المدعومة.
```yaml
agents:
@ -185,21 +179,21 @@ agents:
يُطابِق هذا ترويسة Anthropic التجريبية `context-1m-2025-08-07`.
ولا ينطبق هذا إلا عندما يكون `context1m: true` مضبوطًا على مُدخل ذلك النموذج.
ولا ينطبق هذا إلا عندما تكون `context1m: true` مضبوطة على إدخال ذلك النموذج.
المتطلب: يجب أن تكون بيانات الاعتماد مؤهلة لاستخدام السياق الطويل. وإذا لم
تكن كذلك، فستستجيب Anthropic بخطأ حد معدل من جهة الموفر لذلك الطلب.
المتطلب: يجب أن تكون بيانات الاعتماد مؤهلة لاستخدام السياق الطويل. وإذا لم تكن كذلك،
فإن Anthropic تستجيب بخطأ تحديد معدل من جهة المزوّد لذلك الطلب.
إذا قمت بمصادقة Anthropic باستخدام رموز OAuth/الاشتراك (`sk-ant-oat-*`)،
فسيتخطى OpenClaw الترويسة التجريبية `context-1m-*` لأن Anthropic ترفض حاليًا
هذا الجمع بخطأ HTTP 401.
إذا كنت تصادق Anthropic باستخدام رموز OAuth/الاشتراك (`sk-ant-oat-*`)،
فإن OpenClaw يتخطى الترويسة التجريبية `context-1m-*` لأن Anthropic ترفض حاليًا
هذا الجمع باستخدام HTTP 401.
## نصائح لتقليل ضغط الرموز
- استخدم `/compact` لتلخيص الجلسات الطويلة.
- قلّص مخرجات الأدوات الكبيرة في مسارات عملك.
- اخفض `agents.defaults.imageMaxDimensionPx` للجلسات التي تكثر فيها لقطات الشاشة.
- أبقِ أوصاف Skills قصيرة (إذ تُحقن قائمة Skills في المطالبة).
- فضّل النماذج الأصغر للأعمال الاستكشافية المطولة.
- قلّص مخرجات الأدوات الكبيرة في تدفقات العمل لديك.
- اخفض `agents.defaults.imageMaxDimensionPx` للجلسات التي تعتمد بكثرة على لقطات الشاشة.
- اجعل أوصاف Skills قصيرة (يتم حقن قائمة Skills في prompt).
- فضّل النماذج الأصغر للأعمال الاستكشافية المطوّلة.
راجع [Skills](/ar/tools/skills) للاطلاع على الصيغة الدقيقة لعبء قائمة Skills.
راجع [Skills](/ar/tools/skills) للاطلاع على الصيغة الدقيقة لحساب الحمل الإضافي لقائمة Skills.