From 5a0a31a59f1ea7c61dc487c6d83fcaacd4ba69e7 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 18 Apr 2026 07:24:45 +0000 Subject: [PATCH] chore(i18n): refresh ar translations --- docs/ar/concepts/agent-workspace.md | 184 +-- docs/ar/concepts/context.md | 189 ++- docs/ar/concepts/qa-e2e-automation.md | 152 +- docs/ar/concepts/system-prompt.md | 210 ++- docs/ar/gateway/configuration-reference.md | 1739 ++++++++++---------- docs/ar/gateway/protocol.md | 591 +++---- docs/ar/help/testing.md | 946 +++++------ docs/ar/platforms/macos.md | 188 +-- docs/ar/plugins/sdk-channel-plugins.md | 406 ++--- docs/ar/plugins/sdk-overview.md | 588 +++---- docs/ar/refactor/qa.md | 312 ++-- 11 files changed, 2755 insertions(+), 2750 deletions(-) diff --git a/docs/ar/concepts/agent-workspace.md b/docs/ar/concepts/agent-workspace.md index 9f5c30622..fbabc35b4 100644 --- a/docs/ar/concepts/agent-workspace.md +++ b/docs/ar/concepts/agent-workspace.md @@ -1,40 +1,33 @@ --- read_when: - - تحتاج إلى شرح مساحة عمل الوكيل أو بنية ملفاتها - - تريد نسخ مساحة عمل الوكيل احتياطيًا أو ترحيلها -summary: 'مساحة عمل الوكيل: الموقع، والبنية، واستراتيجية النسخ الاحتياطي' + - تحتاج إلى شرح مساحة عمل الوكيل أو تخطيط ملفاته + - تريد إجراء نسخة احتياطية أو ترحيل مساحة عمل وكيل +summary: 'مساحة عمل الوكيل: الموقع، التخطيط، واستراتيجية النسخ الاحتياطي' title: مساحة عمل الوكيل x-i18n: - generated_at: "2026-04-05T12:40:04Z" + generated_at: "2026-04-18T07:14:51Z" model: gpt-5.4 provider: openai - source_hash: 3735633f1098c733415369f9836fdbbc0bf869636a24ed42e95e6784610d964a + source_hash: dd2e74614d8d45df04b1bbda48e2224e778b621803d774d38e4b544195eb234e source_path: concepts/agent-workspace.md workflow: 15 --- # مساحة عمل الوكيل -مساحة العمل هي موطن الوكيل. وهي دليل العمل الوحيد المستخدم لأدوات -الملفات ولسياق مساحة العمل. حافظ على خصوصيتها وتعامل معها على أنها ذاكرة. +مساحة العمل هي منزل الوكيل. وهي دليل العمل الوحيد المستخدم لأدوات الملفات ولسياق مساحة العمل. أبقها خاصة وتعامل معها على أنها ذاكرة. -وهذا منفصل عن `~/.openclaw/`، الذي يخزّن التكوين وبيانات الاعتماد -والجلسات. +وهذا منفصل عن `~/.openclaw/`، الذي يخزن الإعدادات وبيانات الاعتماد والجلسات. -**مهم:** مساحة العمل هي **الدليل الحالي الافتراضي**، وليست sandbox صارمة. تقوم -الأدوات بحل المسارات النسبية اعتمادًا على مساحة العمل، لكن لا تزال المسارات المطلقة -قادرة على الوصول إلى أماكن أخرى على المضيف ما لم يتم تمكين sandboxing. إذا كنت -تحتاج إلى العزل، فاستخدم -[`agents.defaults.sandbox`](/gateway/sandboxing) (و/أو تكوين sandbox لكل وكيل). -عند تمكين sandboxing وعندما لا تكون `workspaceAccess` مساوية لـ `"rw"`، تعمل الأدوات -داخل مساحة عمل sandbox ضمن `~/.openclaw/sandboxes`، وليس داخل مساحة عمل المضيف. +**مهم:** مساحة العمل هي **cwd الافتراضي**، وليست صندوق عزل صارمًا. تحل الأدوات المسارات النسبية نسبةً إلى مساحة العمل، لكن لا يزال بإمكان المسارات المطلقة الوصول إلى أماكن أخرى على المضيف ما لم يكن العزل مفعّلًا. إذا كنت بحاجة إلى العزل، فاستخدم [`agents.defaults.sandbox`](/ar/gateway/sandboxing) (و/أو إعدادات العزل لكل وكيل على حدة). +عند تفعيل العزل وعدم ضبط `workspaceAccess` على `"rw"`، تعمل الأدوات داخل مساحة عمل معزولة تحت `~/.openclaw/sandboxes` بدلًا من مساحة العمل على المضيف. ## الموقع الافتراضي - الافتراضي: `~/.openclaw/workspace` -- إذا تم ضبط `OPENCLAW_PROFILE` ولم تكن قيمته `"default"`، يصبح الافتراضي +- إذا كان `OPENCLAW_PROFILE` مضبوطًا ولم يكن `"default"`، يصبح الافتراضي `~/.openclaw/workspace-`. -- يمكنك التجاوز في `~/.openclaw/openclaw.json`: +- تجاوز الإعداد في `~/.openclaw/openclaw.json`: ```json5 { @@ -45,12 +38,12 @@ x-i18n: ``` سيقوم `openclaw onboard` أو `openclaw configure` أو `openclaw setup` بإنشاء -مساحة العمل وتهيئة ملفات bootstrap إذا كانت مفقودة. -لا تقبل نسخ seed الخاصة بـ sandbox إلا الملفات العادية داخل مساحة العمل؛ ويتم تجاهل -الأسماء البديلة من symlink/hardlink التي تُحل خارج مساحة العمل المصدر. +مساحة العمل وإضافة ملفات التهيئة الأولية إذا كانت مفقودة. +تقبل نسخ البذور المعزولة فقط الملفات العادية داخل مساحة العمل؛ أما الأسماء +المستعارة من symlink/hardlink التي تُحل خارج مساحة العمل المصدر فيتم تجاهلها. -إذا كنت تدير ملفات مساحة العمل بنفسك بالفعل، فيمكنك تعطيل إنشاء -ملفات bootstrap: +إذا كنت تدير ملفات مساحة العمل بنفسك بالفعل، فيمكنك تعطيل إنشاء ملفات +التهيئة الأولية: ```json5 { agent: { skipBootstrap: true } } @@ -58,30 +51,30 @@ x-i18n: ## مجلدات مساحة العمل الإضافية -قد تكون عمليات التثبيت الأقدم قد أنشأت `~/openclaw`. وقد يؤدي الاحتفاظ بعدة -أدلة لمساحة العمل إلى حدوث انحرافات مربكة في المصادقة أو الحالة، لأن -مساحة عمل واحدة فقط تكون نشطة في كل مرة. +قد تكون الإصدارات الأقدم قد أنشأت `~/openclaw`. إن الاحتفاظ بعدة أدلة لمساحة +العمل يمكن أن يسبب التباسًا في المصادقة أو انجرافًا في الحالة، لأن مساحة عمل +واحدة فقط تكون نشطة في كل مرة. -**التوصية:** احتفظ بمساحة عمل نشطة واحدة. وإذا لم تعد تستخدم -المجلدات الإضافية، فأرشفها أو انقلها إلى سلة المهملات (مثل `trash ~/openclaw`). +**التوصية:** احتفظ بمساحة عمل نشطة واحدة. إذا لم تعد تستخدم المجلدات +الإضافية، فقم بأرشفتها أو نقلها إلى سلة المهملات (مثلًا `trash ~/openclaw`). إذا كنت تحتفظ عمدًا بعدة مساحات عمل، فتأكد من أن -`agents.defaults.workspace` يشير إلى النشطة منها. +`agents.defaults.workspace` يشير إلى المساحة النشطة. -يعرض `openclaw doctor` تحذيرًا عندما يكتشف أدلة إضافية لمساحة العمل. +يحذّر `openclaw doctor` عند اكتشافه أدلة إضافية لمساحة العمل. -## خريطة ملفات مساحة العمل (ما الذي يعنيه كل ملف) +## خريطة ملفات مساحة العمل (ماذا يعني كل ملف) -هذه هي الملفات القياسية التي يتوقعها OpenClaw داخل مساحة العمل: +هذه هي الملفات القياسية التي يتوقع OpenClaw وجودها داخل مساحة العمل: - `AGENTS.md` - - تعليمات تشغيلية للوكيل وكيفية استخدامه للذاكرة. + - تعليمات التشغيل الخاصة بالوكيل وكيفية استخدامه للذاكرة. - يُحمَّل في بداية كل جلسة. - مكان مناسب للقواعد والأولويات وتفاصيل "كيفية التصرف". - `SOUL.md` - - الشخصية، والنبرة، والحدود. + - الشخصية والنبرة والحدود. - يُحمَّل في كل جلسة. - - الدليل: [دليل شخصية SOUL.md](/concepts/soul) + - الدليل: [دليل شخصية SOUL.md](/ar/concepts/soul) - `USER.md` - من هو المستخدم وكيفية مخاطبته. @@ -89,75 +82,74 @@ x-i18n: - `IDENTITY.md` - اسم الوكيل وطابعه وemoji الخاص به. - - يُنشأ/يُحدَّث أثناء طقس bootstrap. + - يُنشأ/يُحدَّث أثناء طقس التهيئة الأولية. - `TOOLS.md` - - ملاحظات حول أدواتك المحلية والاصطلاحات الخاصة بك. - - لا يتحكم في توفر الأدوات؛ فهو مجرد إرشاد. + - ملاحظات حول أدواتك المحلية وأعرافك. + - لا يتحكم في توفر الأدوات؛ بل هو مجرد إرشادات. - `HEARTBEAT.md` - - قائمة تحقق صغيرة اختيارية لتشغيلات heartbeat. - - اجعله قصيرًا لتجنب استهلاك token. + - قائمة تحقق صغيرة اختيارية لتشغيلات Heartbeat. + - أبقه قصيرًا لتجنب استهلاك التوكنات. - `BOOT.md` - - قائمة تحقق اختيارية عند بدء التشغيل تُنفذ عند إعادة تشغيل البوابة عندما تكون hooks الداخلية مفعلة. - - اجعلها قصيرة؛ واستخدم أداة الرسائل للإرسال الصادر. + - قائمة تحقق اختيارية عند بدء التشغيل تُنفذ عند إعادة تشغيل Gateway عندما تكون الخطافات الداخلية مفعلة. + - أبقها قصيرة؛ واستخدم أداة الرسائل للإرسال إلى الخارج. - `BOOTSTRAP.md` - - طقس تشغيل أولي لمرة واحدة. - - لا يُنشأ إلا لمساحة عمل جديدة تمامًا. + - طقس أول تشغيل يُنفذ مرة واحدة. + - يُنشأ فقط لمساحة عمل جديدة تمامًا. - احذفه بعد اكتمال الطقس. - `memory/YYYY-MM-DD.md` - - سجل ذاكرة يومي (ملف واحد لكل يوم). + - سجل الذاكرة اليومي (ملف واحد لكل يوم). - يُنصح بقراءة ملف اليوم + الأمس عند بدء الجلسة. - `MEMORY.md` (اختياري) - - ذاكرة طويلة المدى منسقة. - - لا تُحمَّل إلا في الجلسة الرئيسية الخاصة (وليس في السياقات المشتركة/الجماعية). + - ذاكرة طويلة الأمد منسقة. + - لا يُحمَّل إلا في الجلسة الرئيسية الخاصة (وليس في السياقات المشتركة/الجماعية). -راجع [الذاكرة](/concepts/memory) لمعرفة سير العمل والتفريغ التلقائي للذاكرة. +راجع [الذاكرة](/ar/concepts/memory) للاطلاع على سير العمل والتفريغ التلقائي للذاكرة. - `skills/` (اختياري) - Skills خاصة بمساحة العمل. - موقع Skills الأعلى أولوية لتلك المساحة. - - يتجاوز Skills وكيل المشروع، وSkills الوكيل الشخصية، وSkills المُدارة، وSkills المضمنة، و`skills.load.extraDirs` عند تعارض الأسماء. + - يتجاوز Skills وكلاء المشروع، وSkills الوكيل الشخصية، وSkills المُدارة، وSkills المضمّنة، و`skills.load.extraDirs` عند تعارض الأسماء. - `canvas/` (اختياري) - - ملفات واجهة Canvas لعرض العُقد (مثل `canvas/index.html`). + - ملفات واجهة Canvas لعرض Node (مثل `canvas/index.html`). -إذا كان أي ملف bootstrap مفقودًا، فسيحقن OpenClaw علامة "ملف مفقود" داخل -الجلسة ويتابع العمل. وتُقتطع ملفات bootstrap الكبيرة عند حقنها؛ ويمكنك -تعديل الحدود باستخدام `agents.defaults.bootstrapMaxChars` (الافتراضي: 20000) و -`agents.defaults.bootstrapTotalMaxChars` (الافتراضي: 150000). -يمكن لـ `openclaw setup` إعادة إنشاء الإعدادات الافتراضية المفقودة من دون الكتابة فوق +إذا كان أي ملف من ملفات التهيئة الأولية مفقودًا، يضيف OpenClaw علامة "ملف مفقود" +إلى الجلسة ويتابع التشغيل. يتم اقتطاع ملفات التهيئة الأولية الكبيرة عند إدراجها؛ +اضبط الحدود باستخدام `agents.defaults.bootstrapMaxChars` (الافتراضي: 12000) و +`agents.defaults.bootstrapTotalMaxChars` (الافتراضي: 60000). +يمكن لـ `openclaw setup` إعادة إنشاء الإعدادات الافتراضية المفقودة دون الكتابة فوق الملفات الموجودة. -## ما الذي لا يوجد في مساحة العمل +## ما الذي **ليس** داخل مساحة العمل -توجد هذه العناصر ضمن `~/.openclaw/` ويجب **عدم** الالتزام بها في مستودع مساحة العمل: +توجد هذه العناصر تحت `~/.openclaw/` ويجب **عدم** الالتزام بها داخل مستودع مساحة العمل: -- `~/.openclaw/openclaw.json` (التكوين) +- `~/.openclaw/openclaw.json` (الإعدادات) - `~/.openclaw/agents//agent/auth-profiles.json` (ملفات تعريف مصادقة النماذج: OAuth + مفاتيح API) -- `~/.openclaw/credentials/` (حالة القنوات/المزوّدين بالإضافة إلى بيانات استيراد OAuth القديمة) -- `~/.openclaw/agents//sessions/` (نصوص الجلسات + البيانات الوصفية) -- `~/.openclaw/skills/` (Skills مُدارة) +- `~/.openclaw/credentials/` (حالة القناة/المزوّد بالإضافة إلى بيانات استيراد OAuth القديمة) +- `~/.openclaw/agents//sessions/` (سجلات الجلسات + البيانات الوصفية) +- `~/.openclaw/skills/` (Skills المُدارة) -إذا كنت تحتاج إلى ترحيل الجلسات أو التكوين، فانسخها بشكل منفصل وأبقها -خارج version control. +إذا كنت بحاجة إلى ترحيل الجلسات أو الإعدادات، فانسخها بشكل منفصل وأبقها +خارج التحكم بالإصدارات. -## النسخ الاحتياطي باستخدام Git (موصى به، خاص) +## النسخ الاحتياطي عبر Git (موصى به، خاص) -تعامل مع مساحة العمل على أنها ذاكرة خاصة. ضعها في مستودع git **خاص** -حتى تكون منسوخة احتياطيًا وقابلة للاستعادة. +تعامل مع مساحة العمل على أنها ذاكرة خاصة. ضعها في مستودع git **خاص** بحيث +تكون محفوظة احتياطيًا وقابلة للاسترجاع. -نفّذ هذه الخطوات على الجهاز الذي تعمل عليه البوابة (فهناك توجد -مساحة العمل). +نفّذ هذه الخطوات على الجهاز الذي يعمل عليه Gateway (فهناك توجد مساحة العمل). ### 1) تهيئة المستودع -إذا كان git مثبتًا، فستتم تهيئة مساحات العمل الجديدة تمامًا تلقائيًا. وإذا لم تكن -مساحة العمل هذه مستودعًا بالفعل، فشغّل: +إذا كان git مثبتًا، فستُهيَّأ مساحات العمل الجديدة تلقائيًا. إذا لم تكن مساحة +العمل هذه مستودعًا بالفعل، فشغّل: ```bash cd ~/.openclaw/workspace @@ -166,14 +158,14 @@ git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/ git commit -m "Add agent workspace" ``` -### 2) أضف remote خاصًا (خيارات مناسبة للمبتدئين) +### 2) إضافة remote خاص (خيارات سهلة للمبتدئين) الخيار A: واجهة GitHub على الويب -1. أنشئ مستودعًا جديدًا **خاصًا** على GitHub. -2. لا تهيّئه بملف README (لتجنب تعارضات الدمج). -3. انسخ عنوان remote بنمط HTTPS. -4. أضف remote وادفع التغييرات: +1. أنشئ مستودعًا **خاصًا** جديدًا على GitHub. +2. لا تهيئه بملف README (لتجنب تعارضات الدمج). +3. انسخ عنوان remote بصيغة HTTPS. +4. أضف remote وادفع: ```bash git branch -M main @@ -190,10 +182,10 @@ gh repo create openclaw-workspace --private --source . --remote origin --push الخيار C: واجهة GitLab على الويب -1. أنشئ مستودعًا جديدًا **خاصًا** على GitLab. -2. لا تهيّئه بملف README (لتجنب تعارضات الدمج). -3. انسخ عنوان remote بنمط HTTPS. -4. أضف remote وادفع التغييرات: +1. أنشئ مستودعًا **خاصًا** جديدًا على GitLab. +2. لا تهيئه بملف README (لتجنب تعارضات الدمج). +3. انسخ عنوان remote بصيغة HTTPS. +4. أضف remote وادفع: ```bash git branch -M main @@ -212,16 +204,16 @@ git push ## لا تلتزم بالأسرار -حتى في المستودع الخاص، تجنب تخزين الأسرار في مساحة العمل: +حتى داخل مستودع خاص، تجنب تخزين الأسرار في مساحة العمل: -- مفاتيح API أو OAuth tokens أو كلمات المرور أو بيانات الاعتماد الخاصة. -- أي شيء ضمن `~/.openclaw/`. -- عمليات تفريغ خام للدردشات أو المرفقات الحساسة. +- مفاتيح API أو رموز OAuth أو كلمات المرور أو بيانات الاعتماد الخاصة. +- أي شيء تحت `~/.openclaw/`. +- تفريغات خام للمحادثات أو المرفقات الحساسة. -إذا اضطررت إلى تخزين مراجع حساسة، فاستخدم عناصر نائبة واحتفظ بالسر -الحقيقي في مكان آخر (مدير كلمات المرور، أو متغيرات البيئة، أو `~/.openclaw/`). +إذا اضطررت إلى تخزين مراجع حساسة، فاستخدم عناصر نائبة واحتفظ بالسر الحقيقي +في مكان آخر (مدير كلمات مرور، أو متغيرات البيئة، أو `~/.openclaw/`). -بداية مقترحة لملف `.gitignore`: +ملف `.gitignore` مقترح للبدء: ```gitignore .DS_Store @@ -235,20 +227,20 @@ git push 1. انسخ المستودع إلى المسار المطلوب (الافتراضي `~/.openclaw/workspace`). 2. اضبط `agents.defaults.workspace` على ذلك المسار في `~/.openclaw/openclaw.json`. -3. شغّل `openclaw setup --workspace ` لتهيئة أي ملفات مفقودة. -4. إذا كنت تحتاج إلى الجلسات، فانقل `~/.openclaw/agents//sessions/` من +3. شغّل `openclaw setup --workspace ` لإضافة أي ملفات مفقودة. +4. إذا كنت بحاجة إلى الجلسات، فانقل `~/.openclaw/agents//sessions/` من الجهاز القديم بشكل منفصل. ## ملاحظات متقدمة -- يمكن أن يستخدم التوجيه متعدد الوكلاء مساحات عمل مختلفة لكل وكيل. راجع - [توجيه القنوات](/channels/channel-routing) لمعرفة تكوين التوجيه. -- إذا كان `agents.defaults.sandbox` مفعّلًا، فيمكن للجلسات غير الرئيسية استخدام - مساحات عمل sandbox لكل جلسة ضمن `agents.defaults.sandbox.workspaceRoot`. +- يمكن للتوجيه متعدد الوكلاء استخدام مساحات عمل مختلفة لكل وكيل. راجع + [توجيه القنوات](/ar/channels/channel-routing) للحصول على إعدادات التوجيه. +- إذا كان `agents.defaults.sandbox` مفعّلًا، فقد تستخدم الجلسات غير الرئيسية + مساحات عمل معزولة لكل جلسة تحت `agents.defaults.sandbox.workspaceRoot`. ## ذو صلة -- [الأوامر الدائمة](/automation/standing-orders) — تعليمات مستمرة في ملفات مساحة العمل -- [Heartbeat](/gateway/heartbeat) — ملف مساحة العمل HEARTBEAT.md -- [الجلسة](/concepts/session) — مسارات تخزين الجلسات -- [Sandboxing](/gateway/sandboxing) — وصول مساحة العمل في البيئات المعزولة +- [الأوامر الدائمة](/ar/automation/standing-orders) — تعليمات دائمة في ملفات مساحة العمل +- [Heartbeat](/ar/gateway/heartbeat) — ملف مساحة العمل HEARTBEAT.md +- [الجلسة](/ar/concepts/session) — مسارات تخزين الجلسات +- [العزل](/ar/gateway/sandboxing) — الوصول إلى مساحة العمل في البيئات المعزولة diff --git a/docs/ar/concepts/context.md b/docs/ar/concepts/context.md index 79586bac8..9bbc0f55c 100644 --- a/docs/ar/concepts/context.md +++ b/docs/ar/concepts/context.md @@ -1,115 +1,115 @@ --- read_when: - - تريد فهم ما الذي يعنيه "السياق" في OpenClaw - - أنت تستكشف سبب "معرفة" النموذج لشيء ما (أو سبب نسيانه له) - - تريد تقليل حمل السياق (/context، /status، /compact) -summary: 'السياق: ما الذي يراه النموذج، وكيفية بنائه، وكيفية فحصه' + - تريد أن تفهم ما الذي يعنيه «السياق» في OpenClaw + - أنت تصحّح سبب «معرفة» النموذج لشيء ما (أو سبب نسيانه) + - تريد تقليل الحمل الزائد للسياق (`/context`، `/status`، `/compact`) +summary: 'السياق: ما يراه النموذج، وكيفية بنائه، وكيفية فحصه' title: السياق x-i18n: - generated_at: "2026-04-12T23:28:02Z" + generated_at: "2026-04-18T07:14:54Z" model: gpt-5.4 provider: openai - source_hash: 3620db1a8c1956d91a01328966df491388d3a32c4003dc4447197eb34316c77d + source_hash: 477ccb1d9654968d0e904b6846b32b8c14db6b6c0d3d2ec2b7409639175629f9 source_path: concepts/context.md workflow: 15 --- # السياق -"السياق" هو **كل ما يرسله OpenClaw إلى النموذج أثناء التشغيل**. وهو مقيّد بـ **نافذة السياق** الخاصة بالنموذج (حد الرموز). +«السياق» هو **كل ما يرسله OpenClaw إلى النموذج أثناء التشغيل**. وهو مقيّد بـ **نافذة السياق** الخاصة بالنموذج (حد الرموز). -نموذج ذهني للمبتدئين: +نموذج ذهني مبسّط للمبتدئين: -- **موجّه النظام** (يبنيه OpenClaw): القواعد، والأدوات، وقائمة Skills، والوقت/بيئة التشغيل، وملفات مساحة العمل المحقونة. +- **توجيه النظام** (يبنيه OpenClaw): القواعد، والأدوات، وقائمة Skills، والوقت/بيئة التشغيل، وملفات مساحة العمل المُدرجة. - **سجل المحادثة**: رسائلك + رسائل المساعد في هذه الجلسة. -- **استدعاءات/نتائج الأدوات + المرفقات**: مخرجات الأوامر، وقراءات الملفات، والصور/الصوت، وغير ذلك. +- **استدعاءات الأدوات/نتائجها + المرفقات**: مخرجات الأوامر، وقراءات الملفات، والصور/الصوت، وغير ذلك. -السياق _ليس هو نفسه_ "الذاكرة": يمكن تخزين الذاكرة على القرص وإعادة تحميلها لاحقًا؛ أما السياق فهو ما يوجد داخل نافذة النموذج الحالية. +السياق _ليس الشيء نفسه_ الذي تعنيه «الذاكرة»: يمكن تخزين الذاكرة على القرص وإعادة تحميلها لاحقًا؛ أما السياق فهو ما يوجد داخل نافذة النموذج الحالية. -## بدء سريع (فحص السياق) +## بداية سريعة (فحص السياق) -- `/status` → عرض سريع لـ "ما مدى امتلاء نافذتي؟" + إعدادات الجلسة. -- `/context list` → ما الذي تم حقنه + أحجام تقريبية (لكل ملف + الإجماليات). -- `/context detail` → تفصيل أعمق: لكل ملف، وأحجام مخططات كل أداة، وأحجام إدخالات كل Skill، وحجم موجّه النظام. -- `/usage tokens` → إلحاق تذييل استخدام لكل رد ضمن الردود العادية. -- `/compact` → تلخيص السجل الأقدم إلى إدخال مضغوط لتحرير مساحة في النافذة. +- `/status` ← عرض سريع يجيب عن سؤال: «إلى أي مدى امتلأت نافذتي؟» + إعدادات الجلسة. +- `/context list` ← ما الذي تم إدراجه + أحجام تقريبية (لكل ملف + الإجماليات). +- `/context detail` ← تفصيل أعمق: أحجام كل ملف، وأحجام مخططات كل أداة، وأحجام إدخالات كل Skill، وحجم توجيه النظام. +- `/usage tokens` ← يضيف تذييلًا لاستهلاك الرموز لكل رد إلى الردود العادية. +- `/compact` ← يلخّص السجل الأقدم في إدخال مضغوط لتفريغ مساحة في النافذة. -راجع أيضًا: [أوامر الشرطة المائلة](/ar/tools/slash-commands)، [استخدام الرموز والتكاليف](/ar/reference/token-use)، [Compaction](/ar/concepts/compaction). +انظر أيضًا: [أوامر الشرطة المائلة](/ar/tools/slash-commands)، [استخدام الرموز والتكاليف](/ar/reference/token-use)، [Compaction](/ar/concepts/compaction). ## مثال على المخرجات -تختلف القيم حسب النموذج، والموفّر، وسياسة الأدوات، وما يوجد في مساحة عملك. +تختلف القيم حسب النموذج، والمزوّد، وسياسة الأدوات، وما يوجد في مساحة عملك. ### `/context list` ``` -🧠 Context breakdown -Workspace: -Bootstrap max/file: 20,000 chars +🧠 تفصيل السياق +مساحة العمل: +الحد الأقصى للتمهيد/لكل ملف: 12,000 حرف Sandbox: mode=non-main sandboxed=false -System prompt (run): 38,412 chars (~9,603 tok) (Project Context 23,901 chars (~5,976 tok)) +توجيه النظام (التشغيل): 38,412 حرفًا (~9,603 رموز) (سياق المشروع 23,901 حرفًا (~5,976 رموز)) -Injected workspace files: -- AGENTS.md: OK | raw 1,742 chars (~436 tok) | injected 1,742 chars (~436 tok) -- SOUL.md: OK | raw 912 chars (~228 tok) | injected 912 chars (~228 tok) -- TOOLS.md: TRUNCATED | raw 54,210 chars (~13,553 tok) | injected 20,962 chars (~5,241 tok) -- IDENTITY.md: OK | raw 211 chars (~53 tok) | injected 211 chars (~53 tok) -- USER.md: OK | raw 388 chars (~97 tok) | injected 388 chars (~97 tok) -- HEARTBEAT.md: MISSING | raw 0 | injected 0 -- BOOTSTRAP.md: OK | raw 0 chars (~0 tok) | injected 0 chars (~0 tok) +ملفات مساحة العمل المُدرجة: +- AGENTS.md: OK | الخام 1,742 حرفًا (~436 رموز) | المُدرج 1,742 حرفًا (~436 رموز) +- SOUL.md: OK | الخام 912 حرفًا (~228 رموز) | المُدرج 912 حرفًا (~228 رموز) +- TOOLS.md: TRUNCATED | الخام 54,210 حرفًا (~13,553 رموز) | المُدرج 20,962 حرفًا (~5,241 رموز) +- IDENTITY.md: OK | الخام 211 حرفًا (~53 رموز) | المُدرج 211 حرفًا (~53 رموز) +- USER.md: OK | الخام 388 حرفًا (~97 رموز) | المُدرج 388 حرفًا (~97 رموز) +- HEARTBEAT.md: MISSING | الخام 0 | المُدرج 0 +- BOOTSTRAP.md: OK | الخام 0 حرفًا (~0 رموز) | المُدرج 0 حرفًا (~0 رموز) -Skills list (system prompt text): 2,184 chars (~546 tok) (12 skills) -Tools: read, edit, write, exec, process, browser, message, sessions_send, … -Tool list (system prompt text): 1,032 chars (~258 tok) -Tool schemas (JSON): 31,988 chars (~7,997 tok) (counts toward context; not shown as text) -Tools: (same as above) +قائمة Skills (نص توجيه النظام): 2,184 حرفًا (~546 رموز) (12 Skills) +الأدوات: read, edit, write, exec, process, browser, message, sessions_send, … +قائمة الأدوات (نص توجيه النظام): 1,032 حرفًا (~258 رموز) +مخططات الأدوات (JSON): 31,988 حرفًا (~7,997 رموز) (تُحتسب ضمن السياق؛ لا تُعرض كنص) +الأدوات: (كما سبق) -Session tokens (cached): 14,250 total / ctx=32,000 +رموز الجلسة (مخزنة مؤقتًا): 14,250 إجمالًا / ctx=32,000 ``` ### `/context detail` ``` -🧠 Context breakdown (detailed) +🧠 تفصيل السياق (مفصل) … -Top skills (prompt entry size): -- frontend-design: 412 chars (~103 tok) -- oracle: 401 chars (~101 tok) -… (+10 more skills) +أكبر Skills (حجم إدخال التوجيه): +- frontend-design: 412 حرفًا (~103 رموز) +- oracle: 401 حرفًا (~101 رموز) +… (+10 أخرى من Skills) -Top tools (schema size): -- browser: 9,812 chars (~2,453 tok) -- exec: 6,240 chars (~1,560 tok) -… (+N more tools) +أكبر الأدوات (حجم المخطط): +- browser: 9,812 حرفًا (~2,453 رموز) +- exec: 6,240 حرفًا (~1,560 رموز) +… (+N أدوات أخرى) ``` ## ما الذي يُحتسب ضمن نافذة السياق -كل ما يستقبله النموذج يُحتسب، بما في ذلك: +كل ما يتلقاه النموذج يُحتسب، بما في ذلك: -- موجّه النظام (جميع الأقسام). +- توجيه النظام (كل الأقسام). - سجل المحادثة. - استدعاءات الأدوات + نتائج الأدوات. -- المرفقات/التفريغات النصية (الصور/الصوت/الملفات). -- ملخصات Compaction وآثار التشذيب. -- "الأغلفة" الخاصة بالموفّر أو الرؤوس المخفية (غير مرئية، لكنها تُحتسب). +- المرفقات/النصوص المفرّغة (صور/صوت/ملفات). +- ملخصات Compaction وعناصر التقليم. +- «الأغلفة» الخاصة بالمزوّد أو الرؤوس المخفية (غير مرئية، لكنها لا تزال محتسبة). -## كيف يبني OpenClaw موجّه النظام +## كيف يبني OpenClaw توجيه النظام -موجّه النظام **مملوك لـ OpenClaw** ويُعاد بناؤه في كل تشغيل. ويتضمن: +توجيه النظام **مملوك لـ OpenClaw** ويُعاد بناؤه في كل تشغيل. وهو يتضمن: -- قائمة الأدوات + أوصافًا قصيرة. +- قائمة الأدوات + أوصافًا مختصرة. - قائمة Skills (بيانات وصفية فقط؛ انظر أدناه). - موقع مساحة العمل. -- الوقت (UTC + وقت المستخدم المحوّل إذا كان مضبوطًا). -- بيانات وصفية لبيئة التشغيل (المضيف/نظام التشغيل/النموذج/التفكير). -- ملفات bootstrap المحقونة لمساحة العمل ضمن **سياق المشروع**. +- الوقت (UTC + وقت المستخدم بعد التحويل إذا كان مضبوطًا). +- بيانات وقت التشغيل الوصفية (المضيف/نظام التشغيل/النموذج/التفكير). +- ملفات تمهيد مساحة العمل المُدرجة ضمن **سياق المشروع**. -التفصيل الكامل: [موجّه النظام](/ar/concepts/system-prompt). +للاطلاع على التفصيل الكامل: [توجيه النظام](/ar/concepts/system-prompt). -## ملفات مساحة العمل المحقونة (سياق المشروع) +## ملفات مساحة العمل المُدرجة (سياق المشروع) -افتراضيًا، يحقن OpenClaw مجموعة ثابتة من ملفات مساحة العمل (إذا كانت موجودة): +بشكل افتراضي، يدرج OpenClaw مجموعة ثابتة من ملفات مساحة العمل (إذا كانت موجودة): - `AGENTS.md` - `SOUL.md` @@ -119,69 +119,68 @@ Top tools (schema size): - `HEARTBEAT.md` - `BOOTSTRAP.md` (في التشغيل الأول فقط) -تُقتطع الملفات الكبيرة لكل ملف باستخدام `agents.defaults.bootstrapMaxChars` (الافتراضي `20000` حرف). كما يفرض OpenClaw حدًا إجماليًا لحقن bootstrap عبر جميع الملفات باستخدام `agents.defaults.bootstrapTotalMaxChars` (الافتراضي `150000` حرف). يعرض `/context` أحجام **الخام مقابل المحقون** وما إذا كان الاقتطاع قد حدث. +تُقتطع الملفات الكبيرة لكل ملف على حدة باستخدام `agents.defaults.bootstrapMaxChars` (القيمة الافتراضية `12000` حرف). كما يفرض OpenClaw حدًا إجماليًا لحقن التمهيد عبر جميع الملفات باستخدام `agents.defaults.bootstrapTotalMaxChars` (القيمة الافتراضية `60000` حرف). يعرض `/context` الأحجام **الخام مقابل المُدرج** وما إذا كان قد حدث اقتطاع. -عند حدوث اقتطاع، يمكن لبيئة التشغيل حقن كتلة تحذير داخل الموجّه ضمن سياق المشروع. اضبط هذا عبر `agents.defaults.bootstrapPromptTruncationWarning` (`off` أو `once` أو `always`؛ الافتراضي `once`). +عند حدوث اقتطاع، يمكن لوقت التشغيل إدراج كتلة تحذير داخل التوجيه ضمن سياق المشروع. اضبط ذلك عبر `agents.defaults.bootstrapPromptTruncationWarning` (`off` أو `once` أو `always`؛ والقيمة الافتراضية `once`). -## Skills: المحقونة مقابل المحمّلة عند الطلب +## Skills: المُدرج مقابل المُحمّل عند الطلب -يتضمن موجّه النظام **قائمة Skills** مضغوطة (الاسم + الوصف + الموقع). لهذه القائمة حمل فعلي. +يتضمن توجيه النظام **قائمة Skills** مضغوطة (الاسم + الوصف + الموقع). لهذه القائمة حمل فعلي. -تعليمات Skill _لا_ تُضمّن افتراضيًا. ومن المتوقع أن يستخدم النموذج `read` لقراءة ملف `SKILL.md` الخاص بالـ Skill **فقط عند الحاجة**. +لا تُدرج تعليمات Skill _بشكل افتراضي_. من المتوقع أن يستخدم النموذج `read` لقراءة ملف `SKILL.md` الخاص بالـ Skill **عند الحاجة فقط**. ## الأدوات: هناك تكلفتان تؤثر الأدوات في السياق بطريقتين: -1. **نص قائمة الأدوات** في موجّه النظام (ما تراه باسم "Tooling"). -2. **مخططات الأدوات** (JSON). تُرسل هذه إلى النموذج حتى يتمكن من استدعاء الأدوات. وهي تُحتسب ضمن السياق رغم أنك لا تراها كنص عادي. +1. **نص قائمة الأدوات** في توجيه النظام (ما تراه تحت اسم «Tooling»). +2. **مخططات الأدوات** (JSON). تُرسل هذه إلى النموذج حتى يتمكن من استدعاء الأدوات. وهي تُحتسب ضمن السياق حتى لو لم ترها كنص عادي. -يقسم `/context detail` أكبر مخططات الأدوات حتى تتمكن من معرفة ما الذي يهيمن. +يقسم `/context detail` أكبر مخططات الأدوات حتى تتمكن من معرفة ما الذي يهيمن على الحجم. -## الأوامر، والتوجيهات، و"الاختصارات المضمنة" +## الأوامر، والتوجيهات، و"الاختصارات المضمّنة" -تعالج Gateway أوامر الشرطة المائلة. وهناك عدة سلوكيات مختلفة: +تتعامل Gateway مع أوامر الشرطة المائلة. وهناك عدة سلوكيات مختلفة: -- **الأوامر المستقلة**: الرسالة التي تحتوي فقط على `/...` تُنفّذ كأمر. -- **التوجيهات**: تتم إزالة `/think` و`/verbose` و`/trace` و`/reasoning` و`/elevated` و`/model` و`/queue` قبل أن يرى النموذج الرسالة. +- **أوامر مستقلة**: إذا كانت الرسالة تحتوي فقط على `/...`، تُنفّذ كأمر. +- **توجيهات**: `/think` و`/verbose` و`/trace` و`/reasoning` و`/elevated` و`/model` و`/queue` تُزال قبل أن يرى النموذج الرسالة. - الرسائل التي تحتوي على توجيهات فقط تحفظ إعدادات الجلسة. - - التوجيهات المضمنة داخل رسالة عادية تعمل كتلميحات خاصة بتلك الرسالة. -- **الاختصارات المضمنة** (للمرسلين المسموح لهم فقط): يمكن لبعض رموز `/...` داخل رسالة عادية أن تُنفّذ فورًا (مثال: "hey /status")، وتتم إزالتها قبل أن يرى النموذج النص المتبقي. + - التوجيهات المضمّنة داخل رسالة عادية تعمل كتلميحات خاصة بتلك الرسالة. +- **اختصارات مضمّنة** (للمرسلين المسموح لهم فقط): يمكن لبعض رموز `/...` داخل رسالة عادية أن تُنفّذ فورًا (مثال: “hey /status”)، وتُزال قبل أن يرى النموذج النص المتبقي. -التفاصيل: [أوامر الشرطة المائلة](/ar/tools/slash-commands). +للتفاصيل: [أوامر الشرطة المائلة](/ar/tools/slash-commands). -## الجلسات وCompaction والتشذيب (ما الذي يستمر) +## الجلسات، وCompaction، والتقليم (ما الذي يستمر) -ما الذي يستمر عبر الرسائل يعتمد على الآلية: +يعتمد ما يستمر عبر الرسائل على الآلية: -- **السجل العادي** يستمر في تفريغ الجلسة حتى يتم ضغطه/تشذيبه وفق السياسة. -- **Compaction** يحتفظ بملخص داخل التفريغ ويحافظ على الرسائل الحديثة كما هي. -- **التشذيب** يزيل نتائج الأدوات القديمة من الموجّه _داخل الذاكرة_ أثناء التشغيل، لكنه لا يعيد كتابة التفريغ. +- **السجل العادي** يستمر في نص الجلسة حتى يُضغط/يُقلَّم حسب السياسة. +- **Compaction** يحفظ ملخصًا داخل النص ويُبقي الرسائل الحديثة كما هي. +- **التقليم** يزيل نتائج الأدوات القديمة من التوجيه _الموجود في الذاكرة_ أثناء التشغيل، لكنه لا يعيد كتابة النص. -الوثائق: [الجلسة](/ar/concepts/session)، [Compaction](/ar/concepts/compaction)، [تشذيب الجلسة](/ar/concepts/session-pruning). +الوثائق: [الجلسة](/ar/concepts/session)، [Compaction](/ar/concepts/compaction)، [تقليم الجلسة](/ar/concepts/session-pruning). -افتراضيًا، يستخدم OpenClaw محرّك السياق المدمج `legacy` للتجميع و +بشكل افتراضي، يستخدم OpenClaw محرك السياق المدمج `legacy` للتجميع و Compaction. إذا ثبّتَّ Plugin يوفّر `kind: "context-engine"` و -حددتَه باستخدام `plugins.slots.contextEngine`، فإن OpenClaw يفوّض تجميع -السياق، و`/compact`، ومرابط دورة حياة سياق الوكيل الفرعي ذات الصلة إلى ذلك -المحرّك بدلًا من ذلك. لا يؤدي `ownsCompaction: false` إلى الرجوع تلقائيًا إلى -المحرّك `legacy`؛ إذ يجب على المحرّك النشط أن يطبّق `compact()` بشكل صحيح -رغم ذلك. راجع -[Context Engine](/ar/concepts/context-engine) للاطلاع على الواجهة -القابلة للتوصيل كاملةً، ومرابط دورة الحياة، والإعدادات. +اخترته باستخدام `plugins.slots.contextEngine`، فسيفوّض OpenClaw +تجميع السياق، و`/compact`، وخطافات دورة حياة سياق الوكيل الفرعي ذات الصلة إلى ذلك +المحرك بدلًا من ذلك. إن `ownsCompaction: false` لا يؤدي إلى رجوع تلقائي إلى المحرك +`legacy`؛ بل يجب على المحرك النشط أن يطبّق `compact()` بشكل صحيح. راجع +[Context Engine](/ar/concepts/context-engine) للاطلاع على الواجهة الكاملة +القابلة للتوصيل، وخطافات دورة الحياة، والإعدادات. -## ما الذي يبلّغ عنه `/context` فعليًا +## ماذا يعرض `/context` فعليًا -يفضّل `/context` أحدث تقرير **لموجّه نظام مبنيّ أثناء التشغيل** عندما يكون متاحًا: +يفضّل `/context` أحدث تقرير لتوجيه النظام **المبني أثناء التشغيل** عندما يكون متاحًا: -- `System prompt (run)` = مُلتقط من آخر تشغيل مضمن (قابل لاستخدام الأدوات) ومحفوظ في مخزن الجلسة. -- `System prompt (estimate)` = يُحسب لحظيًا عندما لا يوجد تقرير تشغيل (أو عند التشغيل عبر واجهة CLI خلفية لا تولّد التقرير). +- `System prompt (run)` = مُلتقط من آخر تشغيل مضمن (قادر على استخدام الأدوات) ومحفوظ في مخزن الجلسة. +- `System prompt (estimate)` = يُحتسب أثناء التنفيذ عند عدم وجود تقرير تشغيل (أو عند التشغيل عبر خلفية CLI لا تُنشئ التقرير). -في كلتا الحالتين، يبلّغ عن الأحجام وأكبر المساهمين؛ لكنه **لا** يعرض موجّه النظام الكامل أو مخططات الأدوات. +في كلتا الحالتين، يعرض الأحجام وأكبر المساهمين؛ لكنه **لا** يفرّغ توجيه النظام الكامل أو مخططات الأدوات. ## ذو صلة - [Context Engine](/ar/concepts/context-engine) — حقن سياق مخصص عبر Plugins - [Compaction](/ar/concepts/compaction) — تلخيص المحادثات الطويلة -- [موجّه النظام](/ar/concepts/system-prompt) — كيف يُبنى موجّه النظام +- [توجيه النظام](/ar/concepts/system-prompt) — كيف يُبنى توجيه النظام - [حلقة الوكيل](/ar/concepts/agent-loop) — دورة تنفيذ الوكيل الكاملة diff --git a/docs/ar/concepts/qa-e2e-automation.md b/docs/ar/concepts/qa-e2e-automation.md index 147abd380..a6a573e2f 100644 --- a/docs/ar/concepts/qa-e2e-automation.md +++ b/docs/ar/concepts/qa-e2e-automation.md @@ -1,33 +1,33 @@ --- read_when: - توسيع qa-lab أو qa-channel - - إضافة سيناريوهات ضمان جودة مدعومة بالمستودع - - بناء أتمتة ضمان جودة ذات واقعية أعلى حول لوحة تحكم Gateway -summary: الشكل الخاص لأتمتة ضمان الجودة لـ qa-lab وqa-channel والسيناريوهات المُهيأة مسبقًا وتقارير البروتوكول -title: أتمتة ضمان الجودة من البداية إلى النهاية + - إضافة سيناريوهات QA مدعومة من المستودع + - بناء أتمتة QA أعلى واقعية حول لوحة معلومات Gateway +summary: شكل أتمتة QA الخاصة لـ qa-lab وqa-channel والسيناريوهات المُهيأة مسبقًا وتقارير البروتوكول +title: أتمتة QA الشاملة من البداية إلى النهاية x-i18n: - generated_at: "2026-04-17T07:17:52Z" + generated_at: "2026-04-18T07:14:55Z" model: gpt-5.4 provider: openai - source_hash: 51f97293c184d7c04c95d9858305668fbc0f93273f587ec7e54896ad5d603ab0 + source_hash: adf8c5f74e8fabdc8e9fd7ecd41afce8b60354c7dd24d92ac926d3c527927cd4 source_path: concepts/qa-e2e-automation.md workflow: 15 --- -# أتمتة ضمان الجودة من البداية إلى النهاية +# أتمتة QA الشاملة من البداية إلى النهاية -تهدف حزمة ضمان الجودة الخاصة إلى اختبار OpenClaw بطريقة أكثر واقعية وبهيئة قنوات، مقارنةً بما يمكن أن يحققه اختبار وحدات واحد. +تهدف حزمة QA الخاصة إلى اختبار OpenClaw بطريقة أكثر واقعية وتشبه القنوات أكثر مما يمكن أن يفعله اختبار وحدة واحد. -المكوّنات الحالية: +الأجزاء الحالية: -- `extensions/qa-channel`: قناة رسائل اصطناعية تتضمن أسطح الرسائل الخاصة، والقنوات، والخيوط، والتفاعلات، والتعديل، والحذف. -- `extensions/qa-lab`: واجهة Debugger وممر ضمان جودة لمراقبة النص الحواري، وحقن الرسائل الواردة، وتصدير تقرير Markdown. -- `qa/`: أصول تهيئة مدعومة بالمستودع لمهمة البداية وسيناريوهات ضمان الجودة الأساسية. +- `extensions/qa-channel`: قناة رسائل اصطناعية تتضمن أسطح الرسائل الخاصة، والقنوات، وسلاسل المحادثات، والتفاعلات، والتحرير، والحذف. +- `extensions/qa-lab`: واجهة مستخدم للتصحيح وناقل QA لمراقبة النص الحواري، وحقن الرسائل الواردة، وتصدير تقرير Markdown. +- `qa/`: أصول تهيئة مدعومة من المستودع لمهمة البداية وسيناريوهات QA الأساسية. -تدفّق تشغيل ضمان الجودة الحالي عبارة عن موقع ضمان جودة ذي لوحتين: +تدفق عمل مشغّل QA الحالي هو موقع QA مكوّن من لوحتين: -- اليسار: لوحة تحكم Gateway ‏(Control UI) مع الوكيل. -- اليمين: QA Lab، ويعرض نصًا حواريًا شبيهًا بـ Slack وخطة السيناريو. +- اليسار: لوحة معلومات Gateway ‏(Control UI) مع الوكيل. +- اليمين: QA Lab، يعرض نصًا حواريًا شبيهًا بـ Slack وخطة السيناريو. شغّله باستخدام: @@ -35,9 +35,9 @@ x-i18n: pnpm qa:lab:up ``` -يقوم ذلك ببناء موقع ضمان الجودة، وبدء مسار Gateway مدعومًا بـ Docker، وكشف صفحة QA Lab حيث يمكن لمشغّل أو لحلقة أتمتة إسناد مهمة ضمان جودة إلى الوكيل، ومراقبة سلوك القناة الفعلي، وتسجيل ما نجح وما فشل وما بقي معطّلًا. +يقوم ذلك ببناء موقع QA، وبدء مسار Gateway المدعوم بـ Docker، وكشف صفحة QA Lab حيث يمكن لمشغّل أو حلقة أتمتة إعطاء الوكيل مهمة QA، ومراقبة سلوك القناة الفعلي، وتسجيل ما نجح أو فشل أو ظل معطّلًا. -للحصول على تكرار أسرع في واجهة QA Lab من دون إعادة بناء صورة Docker في كل مرة، ابدأ الحزمة باستخدام حزمة QA Lab مركّبة عبر bind mount: +للحصول على تكرار أسرع لواجهة مستخدم QA Lab دون إعادة بناء صورة Docker في كل مرة، ابدأ الحزمة باستخدام حزمة QA Lab مثبّتة عبر bind mount: ```bash pnpm openclaw qa docker-build-image @@ -46,112 +46,115 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -يبقي `qa:lab:up:fast` خدمات Docker على صورة مبنية مسبقًا، ويجري bind-mount للدليل `extensions/qa-lab/web/dist` داخل حاوية `qa-lab`. ويعيد `qa:lab:watch` بناء تلك الحزمة عند التغيير، ويُعاد تحميل المتصفح تلقائيًا عند تغيّر بصمة أصول QA Lab. +يبقي `qa:lab:up:fast` خدمات Docker على صورة مبنية مسبقًا ويستخدم bind mount للمسار `extensions/qa-lab/web/dist` داخل حاوية `qa-lab`. ويعيد `qa:lab:watch` بناء تلك الحزمة عند التغيير، ويُعاد تحميل المتصفح تلقائيًا عندما تتغير بصمة أصول QA Lab. -لتشغيل مسار فحص Matrix حقيقي على مستوى النقل، شغّل: +لتشغيل مسار Matrix اختباري حقيقي على مستوى النقل، شغّل: ```bash pnpm openclaw qa matrix ``` -يقوم هذا المسار بتهيئة خادم منزلي Tuwunel مؤقت داخل Docker، وتسجيل مستخدمين مؤقتين للسائق وSUT والمراقب، وإنشاء غرفة خاصة واحدة، ثم تشغيل Plugin ‏Matrix الفعلي داخل عملية فرعية لـ QA gateway. ويحافظ مسار النقل الحي على إعدادات العملية الفرعية محصورة في النقل قيد الاختبار، بحيث يعمل Matrix من دون `qa-channel` في إعدادات العملية الفرعية. كما يكتب مخرجات التقرير المنظَّمة وسجلًا مدمجًا لـ stdout/stderr داخل دليل إخراج Matrix QA المحدد. ولالتقاط مخرجات البناء/المشغّل الخارجية من `scripts/run-node.mjs` أيضًا، اضبط `OPENCLAW_RUN_NODE_OUTPUT_LOG=` إلى ملف سجل محلي داخل المستودع. +يوفّر هذا المسار خادم Tuwunel homeserver مؤقتًا داخل Docker، ويسجّل مستخدمين مؤقتين للسائق، وSUT، والمراقب، وينشئ غرفة خاصة واحدة، ثم يشغّل Plugin Matrix الحقيقي داخل child خاص بـ QA gateway. يحافظ مسار النقل الحي على ضبط إعدادات child ضمن النقل الجاري اختباره، لذا يعمل Matrix بدون `qa-channel` في إعدادات child. ويكتب أصول التقارير المنظّمة وسجل stdout/stderr المجمّع في دليل إخراج Matrix QA المحدد. لالتقاط مخرجات البناء/التشغيل الخاصة بـ `scripts/run-node.mjs` الخارجية أيضًا، اضبط `OPENCLAW_RUN_NODE_OUTPUT_LOG=` إلى ملف سجل محلي داخل المستودع. -لتشغيل مسار فحص Telegram حقيقي على مستوى النقل، شغّل: +لتشغيل مسار Telegram اختباري حقيقي على مستوى النقل، شغّل: ```bash pnpm openclaw qa telegram ``` -يستهدف هذا المسار مجموعة Telegram خاصة حقيقية واحدة بدلًا من تهيئة خادم مؤقت. ويتطلب `OPENCLAW_QA_TELEGRAM_GROUP_ID` و`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` و`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`، بالإضافة إلى روبوتين مختلفين داخل المجموعة الخاصة نفسها. يجب أن يملك روبوت SUT اسم مستخدم Telegram، وتعمل المراقبة بين الروبوتات على أفضل نحو عندما يكون لدى كلا الروبوتين وضع Bot-to-Bot Communication Mode مفعّلًا في `@BotFather`. +يستهدف هذا المسار مجموعة Telegram خاصة حقيقية واحدة بدلًا من توفير خادم مؤقت. ويتطلب `OPENCLAW_QA_TELEGRAM_GROUP_ID` و`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` و`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`، بالإضافة إلى روبوتين مختلفين في المجموعة الخاصة نفسها. يجب أن يملك روبوت SUT اسم مستخدم على Telegram، وتعمل المراقبة بين الروبوتات بأفضل شكل عندما يكون Bot-to-Bot Communication Mode مفعّلًا لكلا الروبوتين في `@BotFather`. -تتشارك مسارات النقل الحية الآن عقدًا أصغر واحدًا بدلًا من أن يبتكر كل مسار منها شكل قائمة السيناريوهات الخاصة به. +تتشارك مسارات النقل الحي الآن عقدًا أصغر واحدًا بدلًا من أن يخترع كلٌّ منها شكله الخاص لقائمة السيناريوهات. -يبقى `qa-channel` مجموعة الاختبارات الاصطناعية الواسعة لسلوك المنتج وليس جزءًا من مصفوفة تغطية النقل الحي. +يبقى `qa-channel` مجموعة سلوك المنتج الاصطناعية الواسعة وليس جزءًا من مصفوفة تغطية النقل الحي. -| المسار | Canary | حصر الإشارات | حظر قائمة السماح | رد على المستوى الأعلى | الاستئناف بعد إعادة التشغيل | متابعة الخيط | عزل الخيط | رصد التفاعل | أمر المساعدة | -| ------ | ------ | ------------ | ---------------- | ---------------------- | ---------------------------- | ------------ | --------- | ------------ | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| المسار | Canary | بوابة الإشارة | حظر قائمة السماح | رد من المستوى الأعلى | استئناف بعد إعادة التشغيل | متابعة السلسلة | عزل السلسلة | مراقبة التفاعل | أمر المساعدة | +| ------ | ------ | -------------- | ----------------- | --------------------- | -------------------------- | -------------- | ------------ | ---------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | -يحافظ هذا على `qa-channel` بوصفه مجموعة اختبارات سلوك المنتج الواسعة، بينما تتشارك Matrix وTelegram ووسائط النقل الحية المستقبلية قائمة تحقق صريحة واحدة لعقد النقل. +يحافظ هذا على `qa-channel` كمجموعة سلوك المنتج الواسعة بينما تتشارك Matrix وTelegram ووسائط النقل الحية المستقبلية قائمة تحقق صريحة واحدة لعقد النقل. -لتشغيل مسار Linux VM مؤقت من دون إدخال Docker في مسار ضمان الجودة، شغّل: +لتشغيل مسار Linux VM مؤقت دون إدخال Docker في مسار QA، شغّل: ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline ``` -يقوم هذا بتشغيل ضيف Multipass جديد، وتثبيت الاعتماديات، وبناء OpenClaw داخل الضيف، وتشغيل `qa suite`، ثم نسخ تقرير ضمان الجودة العادي والملخص إلى `.artifacts/qa-e2e/...` على المضيف. +يقوم هذا بتشغيل ضيف Multipass جديد، وتثبيت التبعيات، وبناء OpenClaw داخل الضيف، وتشغيل `qa suite`، ثم نسخ تقرير QA والملخص المعتادين مرة أخرى إلى `.artifacts/qa-e2e/...` على المضيف. ويعيد استخدام سلوك اختيار السيناريو نفسه الذي تستخدمه `qa suite` على المضيف. -وتنفّذ عمليات suite على المضيف وMultipass عدة سيناريوهات محددة بالتوازي مع عمّال Gateway معزولين افتراضيًا، حتى 64 عاملًا أو عدد السيناريوهات المحددة. استخدم `--concurrency ` لضبط عدد العمّال، أو `--concurrency 1` للتنفيذ التسلسلي. -وتُمرَّر في التشغيلات الحية مدخلات مصادقة ضمان الجودة المدعومة والعملية داخل الضيف: مفاتيح الموفر المعتمدة على البيئة، ومسار إعدادات موفر QA الحي، و`CODEX_HOME` عند وجوده. أبقِ `--output-dir` تحت جذر المستودع حتى يتمكن الضيف من الكتابة عكسيًا عبر مساحة العمل المركّبة. +تنفذ تشغيلات الحزمة على المضيف وMultipass عدة سيناريوهات محددة بالتوازي مع عمّال Gateway معزولين افتراضيًا، حتى 64 عاملًا أو عدد السيناريوهات المحدد. استخدم `--concurrency ` لضبط عدد العمّال، أو `--concurrency 1` للتنفيذ التسلسلي. +تُمرَّر في التشغيلات الحية مدخلات مصادقة QA المدعومة والعملية للضيف: مفاتيح المزوّد المعتمدة على البيئة، ومسار إعدادات مزوّد QA الحي، و`CODEX_HOME` عند توفره. أبقِ `--output-dir` تحت جذر المستودع حتى يتمكن الضيف من الكتابة مرة أخرى عبر مساحة العمل المركبة. -## البذور المدعومة بالمستودع +## الأصول المهيأة مسبقًا والمدعومة من المستودع توجد أصول التهيئة في `qa/`: - `qa/scenarios/index.md` -- `qa/scenarios/*.md` +- `qa/scenarios//*.md` -وهذه موجودة عمدًا في git حتى تكون خطة ضمان الجودة مرئية لكلٍّ من البشر والوكيل. +هذه موجودة عمدًا في git حتى تكون خطة QA مرئية للبشر وللوكيل معًا. -يجب أن يظل `qa-lab` مشغّل Markdown عامًا. ويجب أن يكون كل ملف Markdown للسيناريو هو مصدر الحقيقة لتشغيل اختبار واحد، وأن يعرّف ما يلي: +يجب أن يظل `qa-lab` مشغّل Markdown عامًا. كل ملف Markdown للسيناريو هو مصدر الحقيقة لتشغيل اختبار واحد ويجب أن يحدد: -- بيانات وصفية للسيناريو +- بيانات تعريف السيناريو +- بيانات تعريف اختيارية للفئة، والقدرة، والمسار، والمخاطر - مراجع الوثائق والكود - متطلبات Plugin اختيارية -- تصحيح اختياري لإعدادات Gateway +- تصحيحًا اختياريًا لإعدادات Gateway - `qa-flow` القابل للتنفيذ -يُسمح لسطح وقت التشغيل القابل لإعادة الاستخدام الذي يدعم `qa-flow` بأن يظل عامًا وعابرًا للجوانب. على سبيل المثال، يمكن لسيناريوهات Markdown أن تجمع بين أدوات مساعدة على جانب النقل وأخرى على جانب المتصفح تدفع Control UI المضمّنة عبر واجهة Gateway ‏`browser.request` من دون إضافة مشغّل مخصص لحالة خاصة. +يُسمح لسطح التشغيل القابل لإعادة الاستخدام الذي يدعم `qa-flow` بأن يظل عامًا وعابرًا للاهتمامات. على سبيل المثال، يمكن لسيناريوهات Markdown دمج مساعدين من جانب النقل مع مساعدين من جانب المتصفح يقودون Control UI المضمّن عبر واجهة Gateway `browser.request` من دون إضافة مشغّل ذي حالات خاصة. -يجب أن تظل القائمة الأساسية واسعة بما يكفي لتغطية: +يجب تجميع ملفات السيناريو حسب قدرة المنتج بدلًا من مجلد شجرة المصدر. أبقِ معرّفات السيناريو ثابتة عند نقل الملفات؛ واستخدم `docsRefs` و`codeRefs` لتتبّع التنفيذ. -- المحادثة في الرسائل الخاصة والقنوات -- سلوك الخيوط +يجب أن تبقى القائمة الأساسية واسعة بما يكفي لتغطية: + +- محادثات الرسائل الخاصة والقنوات +- سلوك السلاسل - دورة حياة إجراءات الرسائل - استدعاءات Cron - استرجاع الذاكرة - تبديل النماذج -- تسليم المهام إلى وكيل فرعي +- تسليم المهام إلى وكلاء فرعيين - قراءة المستودع وقراءة الوثائق -- مهمة بناء صغيرة واحدة مثل Lobster Invaders +- مهمة بناء صغيرة مثل Lobster Invaders -## مسارات محاكاة الموفّر +## مسارات محاكاة المزوّد -يتضمن `qa suite` مسارين محليين لمحاكاة الموفّر: +تحتوي `qa suite` على مسارين محليين لمحاكاة المزوّد: -- `mock-openai` هو محاكي OpenClaw الواعي بالسيناريو. ويظل مسار المحاكاة الحتمي الافتراضي لضمان الجودة المدعوم بالمستودع ولبوابات التماثل. -- `aimock` يشغّل خادم موفّر مدعومًا بـ AIMock لتغطية البروتوكولات والتجهيزات والتسجيل/إعادة التشغيل وحالات الفوضى على نحو تجريبي. وهو إضافة مكملة ولا يستبدل موزّع السيناريو `mock-openai`. +- `mock-openai` هو محاكي OpenClaw الواعي بالسيناريو. ويظل مسار المحاكاة الحتمي الافتراضي لـ QA المدعوم من المستودع وبوابات التكافؤ. +- `aimock` يشغّل خادم مزوّد مدعومًا بـ AIMock لتغطية تجريبية للبروتوكول، والملفات الثابتة، والتسجيل/إعادة التشغيل، والفوضى. وهو إضافة ولا يستبدل موزّع السيناريو `mock-openai`. -يوجد تنفيذ مسار الموفّر تحت `extensions/qa-lab/src/providers/`. -ويمتلك كل موفّر إعداداته الافتراضية، وبدء تشغيل خادمه المحلي، وإعدادات نموذج Gateway، واحتياجات تجهيز ملف المصادقة، وأعلام القدرات الحية/الوهمية. ويجب أن يمرّ كود suite وGateway المشترك عبر سجل الموفّرين بدلًا من التفرع بناءً على أسماء الموفّرين. +يوجد تنفيذ مسار المزوّد تحت `extensions/qa-lab/src/providers/`. +ويمتلك كل مزوّد إعداداته الافتراضية، وبدء خادمه المحلي، وإعدادات نموذج Gateway، واحتياجات تجهيز ملف تعريف المصادقة، وأعلام القدرات الحية/الوهمية الخاصة به. يجب أن يمر الكود المشترك للحزمة وGateway عبر سجل المزوّدين بدلًا من التفريع على أسماء المزوّدين. -## مُكيّفات النقل +## محوّلات النقل -يمتلك `qa-lab` واجهة نقل عامة لسيناريوهات ضمان الجودة المعتمدة على Markdown. -ويُعد `qa-channel` أول مُكيّف على هذه الواجهة، لكن الهدف التصميمي أوسع: يجب أن تتمكن القنوات المستقبلية، سواء كانت حقيقية أو اصطناعية، من الاندماج في مشغّل suite نفسه بدلًا من إضافة مشغّل ضمان جودة خاص بالنقل. +يمتلك `qa-lab` واجهة نقل عامة لسيناريوهات QA المكتوبة بـ Markdown. +ويُعد `qa-channel` أول محوّل على هذه الواجهة، لكن هدف التصميم أوسع: يجب أن تتمكن القنوات المستقبلية، الحقيقية أو الاصطناعية، من الاندماج في مشغّل الحزمة نفسه بدلًا من إضافة مشغّل QA خاص بالنقل. -على مستوى المعمارية، يكون التقسيم كما يلي: +على مستوى البنية، يكون التقسيم كالتالي: -- يمتلك `qa-lab` تنفيذ السيناريوهات العامة، وتوازي العمّال، وكتابة المخرجات، وإعداد التقارير. -- يمتلك مُكيّف النقل إعدادات Gateway، والجاهزية، ومراقبة الوارد والصادر، وإجراءات النقل، وحالة النقل المطَبَّعة. -- تحدد ملفات سيناريو Markdown ضمن `qa/scenarios/` تشغيل الاختبار؛ ويوفّر `qa-lab` سطح وقت التشغيل القابل لإعادة الاستخدام الذي ينفذها. +- يمتلك `qa-lab` تنفيذ السيناريو العام، وتوازي العمّال، وكتابة الأصول، وإعداد التقارير. +- يمتلك محوّل النقل إعدادات Gateway، والجاهزية، ومراقبة الوارد والصادر، وإجراءات النقل، وحالة النقل الموحّدة. +- تحدد ملفات سيناريو Markdown تحت `qa/scenarios/` تشغيل الاختبار؛ ويقدم `qa-lab` سطح التشغيل القابل لإعادة الاستخدام الذي ينفذه. -توجد إرشادات الاعتماد الموجهة للمشرفين لمُكيّفات القنوات الجديدة في +توجد إرشادات التبنّي للمشرفين الخاصة بمحوّلات القنوات الجديدة في [الاختبار](/ar/help/testing#adding-a-channel-to-qa). ## إعداد التقارير -يصدّر `qa-lab` تقرير بروتوكول بصيغة Markdown من المخطط الزمني للممر المرصود. -ويجب أن يجيب التقرير عن: +يصدّر `qa-lab` تقرير بروتوكول بصيغة Markdown من المخطط الزمني لناقل المراقبة. +يجب أن يجيب التقرير عن: - ما الذي نجح - ما الذي فشل -- ما الذي بقي معطّلًا -- ما سيناريوهات المتابعة الجديرة بالإضافة +- ما الذي ظل معطّلًا +- ما سيناريوهات المتابعة التي تستحق الإضافة -لفحوصات الطابع والأسلوب، شغّل السيناريو نفسه عبر عدة مراجع لنماذج حية واكتب تقرير Markdown خاضعًا للتحكيم: +لفحوصات الشخصية والأسلوب، شغّل السيناريو نفسه عبر عدة مراجع نماذج حية واكتب تقرير Markdown مُحكَّمًا: ```bash pnpm openclaw qa character-eval \ @@ -170,18 +173,17 @@ pnpm openclaw qa character-eval \ --judge-concurrency 16 ``` -يشغّل هذا الأمر عمليات QA gateway فرعية محلية، وليس Docker. يجب أن تضبط سيناريوهات تقييم الطابع الشخصية عبر `SOUL.md`، ثم تُجري أدوار مستخدم عادية مثل المحادثة، ومساعدة مساحة العمل، والمهام الصغيرة على الملفات. ويجب ألا يُبلَّغ النموذج المرشح بأنه قيد التقييم. ويحافظ الأمر على كل نص حواري كامل، ويسجل إحصاءات التشغيل الأساسية، ثم يطلب من نماذج التحكيم في الوضع السريع مع استدلال `xhigh` ترتيب التشغيلات بحسب الطبيعية والطابع والفكاهة. -استخدم `--blind-judge-models` عند المقارنة بين الموفّرين: سيظل موجّه التحكيم يتلقى كل نص حواري وحالة تشغيل، لكن ستُستبدل مراجع المرشحين بتسميات محايدة مثل `candidate-01`؛ ويعيد التقرير ربط الترتيب بالمراجع الحقيقية بعد التحليل. -تستخدم تشغيلات المرشحين افتراضيًا مستوى تفكير `high`، مع `xhigh` لنماذج OpenAI التي تدعمه. ويمكنك تجاوز مرشح محدد ضمنيًا باستخدام -`--model provider/model,thinking=`. وما زال `--thinking ` يضبط قيمة احتياطية عامة، كما يُحتفظ بالشكل الأقدم `--model-thinking ` من أجل التوافق. -تستخدم مراجع المرشحين الخاصة بـ OpenAI الوضع السريع افتراضيًا بحيث تُستخدم المعالجة ذات الأولوية عندما يدعمها الموفّر. أضف `,fast` أو `,no-fast` أو `,fast=false` ضمنيًا عندما يحتاج مرشح واحد أو حكم واحد إلى تجاوز. مرّر `--fast` فقط عندما تريد فرض الوضع السريع على كل نموذج مرشح. وتُسجَّل مدد تشغيل المرشحين والحكام في التقرير لتحليل المقاييس، لكن توجيهات التحكيم تنص صراحةً على عدم الترتيب حسب السرعة. +يشغّل هذا الأمر عمليات child محلية لـ QA gateway، وليس Docker. يجب أن تضبط سيناريوهات تقييم الشخصية الشخصيةَ عبر `SOUL.md`، ثم تنفذ أدوار مستخدم عادية مثل الدردشة، ومساعدة مساحة العمل، ومهام الملفات الصغيرة. ويجب ألا يُخبَر النموذج المرشح بأنه قيد التقييم. يحتفظ الأمر بكل نص حواري كامل، ويسجّل إحصاءات التشغيل الأساسية، ثم يطلب من نماذج التحكيم في الوضع السريع مع استدلال `xhigh` ترتيب التشغيلات حسب الطبيعية والطابع وروح الدعابة. +استخدم `--blind-judge-models` عند مقارنة المزوّدين: إذ يستمر موجه التحكيم في الحصول على كل نص حواري وحالة تشغيل، لكن تُستبدل مراجع المرشحين بتسميات محايدة مثل `candidate-01`؛ ثم يربط التقرير التصنيفات مرة أخرى بالمراجع الحقيقية بعد التحليل. +تستخدم تشغيلات المرشحين افتراضيًا مستوى تفكير `high`، مع `xhigh` لنماذج OpenAI التي تدعمه. يمكنك تجاوز مرشح محدد ضمنيًا باستخدام +`--model provider/model,thinking=`. ولا يزال `--thinking ` يضبط قيمة احتياطية عامة، ويُحتفظ بالنموذج الأقدم `--model-thinking ` من أجل التوافق. +تستخدم مراجع المرشحين الخاصة بـ OpenAI الوضع السريع افتراضيًا حتى تُستخدم المعالجة ذات الأولوية حيثما كان المزوّد يدعمها. أضف `,fast` أو `,no-fast` أو `,fast=false` ضمنيًا عندما يحتاج مرشح واحد أو حكم واحد إلى تجاوز. مرّر `--fast` فقط عندما تريد فرض الوضع السريع لكل نموذج مرشح. وتُسجَّل مدد المرشحين والحكام في التقرير لتحليل المقاييس، لكن موجهات التحكيم تنص صراحةً على عدم الترتيب حسب السرعة. تستخدم تشغيلات نماذج المرشحين والحكام افتراضيًا توازيًا مقداره 16. خفّض -`--concurrency` أو `--judge-concurrency` عندما تجعل حدود الموفّر أو ضغط Gateway المحلي التشغيل صاخبًا أكثر من اللازم. -عندما لا يُمرَّر أي `--model` للمرشح، يستخدم تقييم الطابع افتراضيًا -`openai/gpt-5.4` و`openai/gpt-5.2` و`openai/gpt-5` و`anthropic/claude-opus-4-6` و`anthropic/claude-sonnet-4-6` و`zai/glm-5.1` و -`moonshot/kimi-k2.5` و +`--concurrency` أو `--judge-concurrency` عندما تجعل حدود المزوّد أو ضغط Gateway المحلي التشغيل مشوشًا أكثر من اللازم. +عند عدم تمرير أي `--model` للمرشح، يستخدم تقييم الشخصية افتراضيًا +`openai/gpt-5.4` و`openai/gpt-5.2` و`openai/gpt-5` و`anthropic/claude-opus-4-6` و`anthropic/claude-sonnet-4-6` و`zai/glm-5.1` و`moonshot/kimi-k2.5` و `google/gemini-3.1-pro-preview`. -وعندما لا يُمرَّر أي `--judge-model`، تكون النماذج الحكَمية الافتراضية هي +وعند عدم تمرير أي `--judge-model`، تكون النماذج الحاكمة الافتراضية هي `openai/gpt-5.4,thinking=xhigh,fast` و `anthropic/claude-opus-4-6,thinking=high`. @@ -189,4 +191,4 @@ pnpm openclaw qa character-eval \ - [الاختبار](/ar/help/testing) - [قناة QA](/ar/channels/qa-channel) -- [لوحة التحكم](/web/dashboard) +- [لوحة المعلومات](/web/dashboard) diff --git a/docs/ar/concepts/system-prompt.md b/docs/ar/concepts/system-prompt.md index 9d901dd05..73a230758 100644 --- a/docs/ar/concepts/system-prompt.md +++ b/docs/ar/concepts/system-prompt.md @@ -1,104 +1,101 @@ --- read_when: - - تحرير نص موجه النظام، أو قائمة الأدوات، أو أقسام الوقت/Heartbeat - - تغيير سلوك تهيئة مساحة العمل أو حقن Skills -summary: ما الذي يحتويه موجه نظام OpenClaw وكيف يتم تجميعه -title: موجه النظام + - تحرير نص مطالبة النظام أو قائمة الأدوات أو أقسام الوقت/Heartbeat + - تغيير تهيئة مساحة العمل أو سلوك حقن Skills +summary: ما الذي تتضمنه مطالبة نظام OpenClaw وكيف يتم تجميعها +title: مطالبة النظام x-i18n: - generated_at: "2026-04-15T19:41:40Z" + generated_at: "2026-04-18T07:14:51Z" model: gpt-5.4 provider: openai - source_hash: c740e4646bc4980567338237bfb55126af0df72499ca00a48e4848d9a3608ab4 + source_hash: e60705994cebdd9768926168cb1c6d17ab717d7ff02353a5d5e7478ba8191cab 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** (عند توفرها): يوضح للنموذج كيفية تحميل تعليمات المهارات عند الطلب. +- **الأدوات**: تذكير منظَّم بمصدر الحقيقة للأدوات المهيكلة مع إرشادات استخدام الأدوات أثناء وقت التشغيل. +- **السلامة**: تذكير مختصر بالضوابط الوقائية لتجنب السلوك الساعي إلى السلطة أو تجاوز الإشراف. +- **Skills** (عند توفرها): يوضح للنموذج كيفية تحميل تعليمات المهارة عند الطلب. - **التحديث الذاتي لـ OpenClaw**: كيفية فحص الإعدادات بأمان باستخدام - `config.schema.lookup`، وتصحيح الإعدادات باستخدام `config.patch`، واستبدال - الإعدادات بالكامل باستخدام `config.apply`، وتشغيل `update.run` فقط عند طلب - المستخدم الصريح. كما أن أداة `gateway` المخصصة للمالك فقط ترفض أيضًا إعادة - كتابة `tools.exec.ask` / `tools.exec.security`، بما في ذلك الأسماء + `config.schema.lookup`، وتعديل الإعدادات باستخدام `config.patch`، واستبدال + الإعدادات كاملة باستخدام `config.apply`، وتشغيل `update.run` فقط عند طلب + المستخدم الصريح. كما أن أداة `gateway` المخصَّصة للمالك فقط ترفض أيضًا + إعادة كتابة `tools.exec.ask` / `tools.exec.security`، بما في ذلك الأسماء المستعارة القديمة `tools.bash.*` التي تُطبَّع إلى مسارات exec المحمية تلك. - **مساحة العمل**: دليل العمل (`agents.defaults.workspace`). - **التوثيق**: المسار المحلي إلى وثائق OpenClaw (المستودع أو حزمة npm) ومتى يجب قراءتها. -- **ملفات مساحة العمل (محقونة)**: يشير إلى أن ملفات التهيئة الأولية مضمنة أدناه. -- **Sandbox** (عند التمكين): يشير إلى بيئة تشغيل معزولة، ومسارات sandbox، وما إذا كان التنفيذ المرتفع الصلاحيات متاحًا. +- **ملفات مساحة العمل (محقونة)**: تشير إلى أن ملفات التهيئة الأولية مضمنة أدناه. +- **Sandbox** (عند التمكين): يوضح بيئة التشغيل المعزولة، ومسارات Sandbox، وما إذا كان التنفيذ المرفوع الصلاحيات متاحًا. - **التاريخ والوقت الحاليان**: الوقت المحلي للمستخدم، والمنطقة الزمنية، وتنسيق الوقت. - **وسوم الرد**: صياغة وسوم الرد الاختيارية للموفرين المدعومين. -- **Heartbeats**: موجه Heartbeat وسلوك الإقرار، عندما تكون Heartbeats مفعلة للوكيل الافتراضي. -- **وقت التشغيل**: المضيف، ونظام التشغيل، وnode، والنموذج، وجذر المستودع (عند اكتشافه)، ومستوى التفكير (سطر واحد). -- **الاستدلال**: مستوى الرؤية الحالي + تلميح تبديل /reasoning. +- **Heartbeats**: مطالبة Heartbeat وسلوك الإقرار، عندما تكون Heartbeats مفعلة للوكيل الافتراضي. +- **وقت التشغيل**: المضيف، ونظام التشغيل، وNode، والنموذج، وجذر المستودع (عند اكتشافه)، ومستوى التفكير (سطر واحد). +- **الاستدلال**: مستوى الرؤية الحالي + تلميح تبديل `/reasoning`. -يتضمن قسم الأدوات أيضًا إرشادات وقت التشغيل للأعمال طويلة التشغيل: +يتضمن قسم الأدوات أيضًا إرشادات أثناء وقت التشغيل للعمل طويل الأمد: -- استخدم Cron للمتابعة المستقبلية (`check back later`، والتذكيرات، والأعمال المتكررة) +- استخدم Cron للمتابعة المستقبلية (`check back later`، والتذكيرات، والعمل المتكرر) بدلًا من حلقات السكون عبر `exec`، أو حيل التأخير `yieldMs`، أو الاستطلاع المتكرر لـ `process` -- استخدم `exec` / `process` فقط للأوامر التي تبدأ الآن وتستمر في العمل في - الخلفية -- عند تمكين التنبيه التلقائي عند الاكتمال، ابدأ الأمر مرة واحدة ثم اعتمد على - مسار التنبيه المعتمد على الدفع عندما يصدر مخرجات أو يفشل +- استخدم `exec` / `process` فقط للأوامر التي تبدأ الآن وتستمر في العمل + في الخلفية +- عند تمكين التنبيه التلقائي عند الاكتمال، ابدأ الأمر مرة واحدة واعتمد على + مسار التنبيه القائم على الدفع عندما يُخرج مخرجات أو يفشل - استخدم `process` للسجلات، أو الحالة، أو الإدخال، أو التدخل عندما تحتاج إلى فحص أمر قيد التشغيل -- إذا كانت المهمة أكبر، ففضّل `sessions_spawn`; يكتمل الوكيل الفرعي بأسلوب - قائم على الدفع ويعلن تلقائيًا الرجوع إلى الطالب -- لا تستطلع `subagents list` / `sessions_list` في حلقة فقط لانتظار +- إذا كانت المهمة أكبر، ففضّل `sessions_spawn`؛ إذ إن اكتمال الوكيل الفرعي + قائم على الدفع ويُعلَن عنه تلقائيًا لصاحب الطلب +- لا تستطلع `subagents list` / `sessions_list` ضمن حلقة لمجرد انتظار الاكتمال -عند تمكين الأداة التجريبية `update_plan`، يوضح قسم الأدوات أيضًا للنموذج أن -يستخدمها فقط للأعمال غير التافهة متعددة الخطوات، وأن يُبقي خطوة واحدة فقط -`in_progress`، وأن يتجنب تكرار الخطة كاملة بعد كل تحديث. +عند تمكين أداة `update_plan` التجريبية، يوجّه قسم الأدوات النموذج أيضًا إلى +استخدامها فقط للأعمال غير البسيطة متعددة الخطوات، والحفاظ على خطوة واحدة فقط +بحالة `in_progress`، وتجنب تكرار الخطة كاملة بعد كل تحديث. -ضوابط السلامة في موجه النظام إرشادية. فهي توجه سلوك النموذج لكنها لا تفرض سياسة. استخدم سياسة الأدوات، وموافقات exec، وsandboxing، وقوائم السماح الخاصة بالقنوات من أجل الفرض الصارم؛ ويمكن للمشغلين تعطيل هذه الأمور عمدًا. +ضوابط السلامة في مطالبة النظام إرشادية. فهي توجه سلوك النموذج لكنها لا تفرض السياسة. استخدم سياسة الأدوات، وموافقات exec، وSandbox، وقوائم السماح الخاصة بالقنوات لفرض التنفيذ الصارم؛ ويمكن للمشغلين تعطيل هذه الأمور عمدًا. -في القنوات التي تحتوي على بطاقات/أزرار موافقة أصلية، يوجه موجه وقت التشغيل الآن -الوكيل إلى الاعتماد أولًا على واجهة الموافقة الأصلية هذه. ولا ينبغي أن يتضمن -أمر `/approve` يدويًا إلا عندما تشير نتيجة الأداة إلى أن موافقات الدردشة غير -متاحة أو أن الموافقة اليدوية هي المسار الوحيد. +في القنوات التي تحتوي على بطاقات/أزرار موافقة أصلية، توضح مطالبة وقت التشغيل الآن +للوكيل أن يعتمد أولًا على واجهة الموافقة الأصلية تلك. ولا ينبغي له تضمين أمر +`/approve` يدوي إلا عندما تشير نتيجة الأداة إلى أن موافقات الدردشة غير متاحة أو +أن الموافقة اليدوية هي المسار الوحيد. -## أوضاع الموجه +## أوضاع المطالبة -يمكن لـ OpenClaw عرض موجهات نظام أصغر للوكلاء الفرعيين. يحدد وقت التشغيل -`promptMode` لكل تشغيل (وليس إعدادًا ظاهرًا للمستخدم): +يمكن لـ OpenClaw عرض مطالبات نظام أصغر للوكلاء الفرعيين. يضبط وقت التشغيل +`promptMode` لكل تشغيل (وليس إعدادًا مرئيًا للمستخدم): -- `full` (افتراضي): يتضمن جميع الأقسام أعلاه. -- `minimal`: يُستخدم للوكلاء الفرعيين؛ ويحذف **Skills**، و**استدعاء الذاكرة**، و**التحديث الذاتي لـ OpenClaw**، و**أسماء النماذج المستعارة**، و**هوية المستخدم**، و**وسوم الرد**، - و**المراسلة**، و**الردود الصامتة**، و**Heartbeats**. وتظل الأدوات، و**السلامة**، - ومساحة العمل، وSandbox، والتاريخ والوقت الحاليان (عند معرفتهما)، ووقت التشغيل، والسياق - المحقون متاحة. -- `none`: يعيد سطر الهوية الأساسي فقط. +- `full` (الافتراضي): يتضمن جميع الأقسام المذكورة أعلاه. +- `minimal`: يُستخدم للوكلاء الفرعيين؛ ويحذف **Skills** و**استدعاء الذاكرة** و**التحديث الذاتي لـ OpenClaw** و**الأسماء المستعارة للنماذج** و**هوية المستخدم** و**وسوم الرد** و**المراسلة** و**الردود الصامتة** و**Heartbeats**. وتبقى الأدوات، و**السلامة**، ومساحة العمل، وSandbox، و**التاريخ والوقت الحاليان** (عند معرفتهما)، ووقت التشغيل، والسياق المحقون متاحة. +- `none`: يعيد فقط سطر الهوية الأساسي. -عندما يكون `promptMode=minimal`، تُسمى الموجهات الإضافية المحقونة **سياق الوكيل -الفرعي** بدلًا من **سياق الدردشة الجماعية**. +عندما يكون `promptMode=minimal`، تُوسم المطالبات الإضافية المحقونة باسم **سياق الوكيل الفرعي** +بدلًا من **سياق الدردشة الجماعية**. -## حقن تهيئة مساحة العمل +## حقن التهيئة الأولية لمساحة العمل -تُقص ملفات التهيئة الأولية وتُلحق تحت **سياق المشروع** حتى يرى النموذج سياق الهوية والملف الشخصي دون الحاجة إلى قراءات صريحة: +تُقص ملفات التهيئة الأولية وتُلحق تحت **سياق المشروع** بحيث يرى النموذج الهوية وسياق الملف الشخصي دون الحاجة إلى قراءات صريحة: - `AGENTS.md` - `SOUL.md` @@ -109,48 +106,48 @@ x-i18n: - `BOOTSTRAP.md` (فقط في مساحات العمل الجديدة تمامًا) - `MEMORY.md` عند وجوده، وإلا `memory.md` كبديل بأحرف صغيرة -كل هذه الملفات **تُحقن داخل نافذة السياق** في كل دورة ما لم -تنطبق بوابة خاصة بالملف. يُحذف `HEARTBEAT.md` في التشغيلات العادية عندما تكون -Heartbeats معطلة للوكيل الافتراضي أو عندما يكون -`agents.defaults.heartbeat.includeSystemPromptSection` يساوي false. أبقِ الملفات -المحقونة موجزة — خاصة `MEMORY.md`، الذي يمكن أن ينمو مع الوقت ويؤدي إلى -استخدام سياق أعلى من المتوقع وCompaction أكثر تكرارًا. +تُحقن كل هذه الملفات **في نافذة السياق** عند كل دورة ما لم +ينطبق حاجز خاص بملف معين. يُحذف `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` في الحد الأقصى لحجم كل ملف +(الافتراضي: 12000). ويُحدد سقف إجمالي محتوى التهيئة الأولية المحقون عبر الملفات +بواسطة `agents.defaults.bootstrapTotalMaxChars` +(الافتراضي: 60000). وتحقن الملفات المفقودة علامة قصيرة تفيد بفقدان الملف. عند حدوث الاقتطاع، +يمكن لـ OpenClaw حقن كتلة تحذير في سياق المشروع؛ تحكم في ذلك باستخدام +`agents.defaults.bootstrapPromptTruncationWarning` (`off` أو `once` أو `always`؛ +والافتراضي: `once`). -جلسات الوكيل الفرعي تحقن فقط `AGENTS.md` و`TOOLS.md` (تُرشَّح ملفات التهيئة الأولية الأخرى -لإبقاء سياق الوكيل الفرعي صغيرًا). +لا تحقن جلسات الوكيل الفرعي سوى `AGENTS.md` و`TOOLS.md` (تُرشَّح بقية ملفات التهيئة الأولية +للحفاظ على صغر سياق الوكيل الفرعي). يمكن للخطافات الداخلية اعتراض هذه الخطوة عبر `agent:bootstrap` لتعديل أو استبدال -ملفات التهيئة الأولية المحقونة (على سبيل المثال استبدال `SOUL.md` بشخصية بديلة). +ملفات التهيئة الأولية المحقونة (مثل تبديل `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` يمسحه). اضبط ذلك باستخدام: @@ -158,19 +155,20 @@ Heartbeats معطلة للوكيل الافتراضي أو عندما يكون - `agents.defaults.userTimezone` - `agents.defaults.timeFormat` (`auto` | `12` | `24`) -راجع [التاريخ والوقت](/ar/date-time) للحصول على التفاصيل الكاملة للسلوك. +انظر [التاريخ والوقت](/ar/date-time) للحصول على التفاصيل الكاملة للسلوك. ## Skills -عندما تكون هناك Skills مؤهلة، يحقن OpenClaw **قائمة Skills متاحة** مضغوطة +عندما توجد Skills مؤهلة، يحقن OpenClaw **قائمة Skills متاحة** مضغوطة (`formatSkillsForPrompt`) تتضمن **مسار الملف** لكل Skill. وتوجّه -الموجه النموذج لاستخدام `read` لتحميل ملف SKILL.md في الموقع المدرج -(مساحة العمل، أو المُدار، أو المضمّن). وإذا لم توجد Skills مؤهلة، فيُحذف قسم +المطالبة النموذج إلى استخدام `read` لتحميل SKILL.md من الموقع المدرج +(مساحة العمل، أو المدار، أو المضمَّن). وإذا لم توجد Skills مؤهلة، يُحذف قسم Skills. -تشمل الأهلية بوابات بيانات تعريف Skill، وفحوصات بيئة التشغيل/الإعدادات، -وقائمة السماح الفعلية لمهارات الوكيل عند ضبط `agents.defaults.skills` أو -`agents.list[].skills`. +تشمل الأهلية بوابات بيانات Skill الوصفية، وفحوصات بيئة/إعدادات وقت التشغيل، +وقائمة السماح الفعلية لـ Skills الخاصة بالوكيل عندما تكون +`agents.defaults.skills` أو +`agents.list[].skills` مضبوطة. ``` @@ -182,26 +180,26 @@ Skills. ``` -يبقي هذا الموجه الأساسي صغيرًا مع الاستمرار في تمكين استخدام Skills المستهدفة. +يحافظ ذلك على صغر المطالبة الأساسية مع الاستمرار في تمكين استخدام Skills بشكل مستهدف. -تعود ملكية ميزانية قائمة Skills إلى نظام Skills الفرعي: +تملك المنظومة الفرعية لـ Skills ميزانية قائمة Skills: - الافتراضي العام: `skills.limits.maxSkillsPromptChars` -- تجاوز لكل وكيل: `agents.list[].skillsLimits.maxSkillsPromptChars` +- التجاوز لكل وكيل: `agents.list[].skillsLimits.maxSkillsPromptChars` -تستخدم المقاطع المحدودة العامة لوقت التشغيل سطحًا مختلفًا: +أما المقاطع العامة المقيّدة في وقت التشغيل فتستخدم سطحًا مختلفًا: - `agents.defaults.contextLimits.*` - `agents.list[].contextLimits.*` -يبقي هذا الفصل تحديد حجم Skills منفصلًا عن تحديد حجم القراءة/الحقن في وقت التشغيل مثل -`memory_get`، ونتائج الأدوات الحية، وتحديثات AGENTS.md بعد Compaction. +يبقي هذا الفصل حجم Skills منفصلًا عن حجم القراءة/الحقن في وقت التشغيل مثل +`memory_get`، ونتائج الأدوات الحية، وتحديثات `AGENTS.md` بعد Compaction. ## التوثيق -عند توفره، يتضمن موجه النظام قسم **التوثيق** الذي يشير إلى +عند توفره، تتضمن مطالبة النظام قسم **التوثيق** الذي يشير إلى دليل وثائق OpenClaw المحلي (إما `docs/` في مساحة عمل المستودع أو وثائق حزمة npm -المضمنة)، كما يذكر أيضًا النسخة العامة المطابقة، ومستودع المصدر، وDiscord المجتمع، -وClawHub ([https://clawhub.ai](https://clawhub.ai)) لاكتشاف Skills. ويوجه الموجه النموذج إلى الرجوع إلى -الوثائق المحلية أولًا فيما يخص سلوك OpenClaw، أو الأوامر، أو الإعدادات، أو -البنية، وأن يشغّل `openclaw status` بنفسه عندما يكون ذلك ممكنًا (ولا يسأل المستخدم إلا عند عدم توفر الوصول). +المضمَّنة)، ويذكر أيضًا المرآة العامة، ومستودع المصدر، وDiscord الخاص بالمجتمع، +وClawHub ([https://clawhub.ai](https://clawhub.ai)) لاكتشاف Skills. وتوجّه المطالبة النموذج إلى الرجوع إلى الوثائق المحلية أولًا +لسلوك OpenClaw أو الأوامر أو الإعدادات أو البنية، وإلى تشغيل +`openclaw status` بنفسه متى أمكن (وسؤال المستخدم فقط عندما يفتقر إلى إمكانية الوصول). diff --git a/docs/ar/gateway/configuration-reference.md b/docs/ar/gateway/configuration-reference.md index 4f849de4b..7ab8415a5 100644 --- a/docs/ar/gateway/configuration-reference.md +++ b/docs/ar/gateway/configuration-reference.md @@ -1,43 +1,43 @@ --- read_when: - - تحتاج إلى دلالات الإعدادات الدقيقة على مستوى الحقول أو القيم الافتراضية. - - أنت تتحقق من صحة كتل إعدادات القنوات أو النماذج أو Gateway أو الأدوات. -summary: مرجع إعدادات Gateway لمفاتيح OpenClaw الأساسية، والقيم الافتراضية، وروابط إلى مراجع الأنظمة الفرعية المخصصة + - تحتاج إلى دلالات إعدادات دقيقة على مستوى الحقول أو إلى القيم الافتراضية. + - أنت تتحقق من كتل إعدادات القناة أو النموذج أو Gateway أو الأداة. +summary: مرجع إعدادات Gateway لمفاتيح OpenClaw الأساسية والقيم الافتراضية والروابط إلى مراجع الأنظمة الفرعية المخصصة title: مرجع الإعدادات x-i18n: - generated_at: "2026-04-15T19:41:37Z" + generated_at: "2026-04-18T07:14:54Z" model: gpt-5.4 provider: openai - source_hash: 2bdb0f3e56e4a4d767fb4d6150526ae9b3926ef5b213b458001f41d02762436d + source_hash: 4b504c9c6b47d7a327a0acf6934561c9b2606c01cc8ebe5526ccde73033d759f source_path: gateway/configuration-reference.md workflow: 15 --- # مرجع الإعدادات -مرجع الإعدادات الأساسي لملف `~/.openclaw/openclaw.json`. للحصول على نظرة عامة موجّهة حسب المهام، راجع [الإعدادات](/ar/gateway/configuration). +مرجع الإعدادات الأساسية لملف `~/.openclaw/openclaw.json`. للحصول على نظرة عامة موجّهة للمهام، راجع [الإعدادات](/ar/gateway/configuration). -تغطي هذه الصفحة أسطح إعدادات OpenClaw الرئيسية وتضع روابط خارجية عندما يكون لنظام فرعي مرجع أعمق خاص به. وهي **لا** تحاول تضمين كل فهرس أوامر مملوك للقنوات/Plugin أو كل إعداد عميق للذاكرة/QMD في صفحة واحدة. +تغطي هذه الصفحة أسطح إعدادات OpenClaw الرئيسية وتضع روابط خارجية عندما يكون لأحد الأنظمة الفرعية مرجع أعمق خاص به. وهي **لا** تحاول تضمين كل فهرس أوامر مملوك للقنوات/Plugin أو كل خيار تفصيلي عميق للذاكرة/QMD في صفحة واحدة. مصدر الحقيقة في الشيفرة: -- يطبع `openclaw config schema` مخطط JSON Schema الفعلي المستخدم للتحقق وواجهة Control UI، مع دمج بيانات التعريف الخاصة بالحِزم المضمّنة/Plugin/القنوات عند توفرها -- يعيد `config.schema.lookup` عقدة مخطط واحدة ضمن نطاق مسار محدد لأدوات الاستكشاف التفصيلي -- يتحقق `pnpm config:docs:check` / `pnpm config:docs:gen` من تجزئة خط الأساس لوثائق الإعدادات مقابل سطح المخطط الحالي +- يطبع `openclaw config schema` مخطط JSON Schema الفعلي المستخدم للتحقق وواجهة Control UI، مع دمج بيانات التعريف الخاصة بالحزم المضمّنة/Plugin/القنوات عند توفرها +- يعيد `config.schema.lookup` عقدة مخطط واحدة محددة بالمسار لأدوات الاستكشاف التفصيلي +- يتحقق `pnpm config:docs:check` / `pnpm config:docs:gen` من تجزئة خط الأساس لوثائق الإعدادات مقارنةً بسطح المخطط الحالي -المراجع العميقة المخصصة: +المراجع التفصيلية المخصصة: -- [مرجع إعدادات الذاكرة](/ar/reference/memory-config) لـ `agents.defaults.memorySearch.*` و`memory.qmd.*` و`memory.citations` وإعدادات Dreaming ضمن `plugins.entries.memory-core.config.dreaming` -- [أوامر الشرطة المائلة](/ar/tools/slash-commands) لفهرس الأوامر الحالي المدمج + المضمّن +- [مرجع إعدادات الذاكرة](/ar/reference/memory-config) لـ `agents.defaults.memorySearch.*` و`memory.qmd.*` و`memory.citations` وإعدادات Dreaming تحت `plugins.entries.memory-core.config.dreaming` +- [Slash Commands](/ar/tools/slash-commands) لفهرس الأوامر الحالي المضمن + المجمّع - صفحات القنوات/Plugin المالكة لأسطح الأوامر الخاصة بكل قناة -تنسيق الإعدادات هو **JSON5** (مسموح بالتعليقات والفواصل اللاحقة). جميع الحقول اختيارية — يستخدم OpenClaw قيماً افتراضية آمنة عند حذفها. +تنسيق الإعدادات هو **JSON5** (تُسمح التعليقات والفواصل اللاحقة). جميع الحقول اختيارية — يستخدم OpenClaw قيمًا افتراضية آمنة عند حذفها. --- ## القنوات -تبدأ كل قناة تلقائياً عندما يوجد قسم إعداداتها (إلا إذا كان `enabled: false`). +تبدأ كل قناة تلقائيًا عند وجود قسم إعداداتها (ما لم يكن `enabled: false`). ### الوصول إلى الرسائل المباشرة والمجموعات @@ -52,19 +52,19 @@ x-i18n: | سياسة المجموعات | السلوك | | --------------------- | ------------------------------------------------------ | -| `allowlist` (الافتراضي) | فقط المجموعات المطابقة لقائمة السماح المضبوطة | -| `open` | تجاوز قوائم السماح للمجموعات (مع بقاء تقييد الإشارة مطبقاً) | +| `allowlist` (الافتراضي) | فقط المجموعات المطابقة لقائمة السماح المُعدّة | +| `open` | تجاوز قوائم السماح الخاصة بالمجموعات (مع استمرار تطبيق اشتراط الإشارة) | | `disabled` | حظر جميع رسائل المجموعات/الغرف | -يضبط `channels.defaults.groupPolicy` السياسة الافتراضية عندما لا تكون قيمة `groupPolicy` لموفّر ما معيّنة. -تنتهي صلاحية رموز الاقتران بعد ساعة واحدة. ويُحدّ عدد طلبات اقتران الرسائل المباشرة المعلّقة عند **3 لكل قناة**. -إذا كانت كتلة الموفّر مفقودة بالكامل (عدم وجود `channels.`)، تعود سياسة المجموعات وقت التشغيل إلى `allowlist` (فشل مغلق) مع تحذير عند بدء التشغيل. +يضبط `channels.defaults.groupPolicy` القيمة الافتراضية عندما لا تكون `groupPolicy` الخاصة بالمزوّد معيّنة. +تنتهي صلاحية رموز الاقتران بعد ساعة واحدة. ويُحدَّد الحد الأقصى لطلبات اقتران الرسائل المباشرة المعلقة عند **3 لكل قناة**. +إذا كانت كتلة المزوّد مفقودة بالكامل (`channels.` غير موجودة)، فإن سياسة المجموعات أثناء التشغيل تعود إلى `allowlist` (إغلاق افتراضي) مع تحذير عند بدء التشغيل. ### تجاوزات نموذج القناة -استخدم `channels.modelByChannel` لتثبيت معرّفات قنوات محددة على نموذج معيّن. تقبل القيم `provider/model` أو الأسماء المستعارة للنماذج المضبوطة. يُطبَّق ربط القناة عندما لا تكون للجلسة بالفعل قيمة تجاوز للنموذج (على سبيل المثال، مضبوطة عبر `/model`). +استخدم `channels.modelByChannel` لتثبيت معرّفات قنوات محددة على نموذج معيّن. تقبل القيم `provider/model` أو الأسماء المستعارة للنماذج المهيأة. يُطبَّق تعيين القناة عندما لا تكون الجلسة تملك بالفعل تجاوزًا للنموذج (على سبيل المثال، تم تعيينه عبر `/model`). ```json5 { @@ -85,9 +85,9 @@ x-i18n: } ``` -### القيم الافتراضية للقنوات وHeartbeat +### الإعدادات الافتراضية للقنوات وHeartbeat -استخدم `channels.defaults` للسلوك المشترك لسياسة المجموعات وHeartbeat عبر الموفّرين: +استخدم `channels.defaults` للسلوك المشترك الخاص بسياسة المجموعات وHeartbeat عبر المزوّدين: ```json5 { @@ -105,15 +105,15 @@ x-i18n: } ``` -- `channels.defaults.groupPolicy`: سياسة المجموعات الاحتياطية عندما لا تكون قيمة `groupPolicy` على مستوى الموفّر معيّنة. -- `channels.defaults.contextVisibility`: وضع رؤية السياق التكميلي الافتراضي لجميع القنوات. القيم: `all` (الافتراضي، تضمين كل سياق الاقتباس/الخيط/السجل)، `allowlist` (تضمين السياق من المرسلين الموجودين في قائمة السماح فقط)، `allowlist_quote` (مثل allowlist لكن مع الاحتفاظ بسياق الاقتباس/الرد الصريح). التجاوز لكل قناة: `channels..contextVisibility`. +- `channels.defaults.groupPolicy`: سياسة المجموعات الاحتياطية عندما لا تكون `groupPolicy` على مستوى المزوّد معيّنة. +- `channels.defaults.contextVisibility`: وضع إظهار السياق التكميلي الافتراضي لجميع القنوات. القيم: `all` (الافتراضي، تضمين كل سياق الاقتباس/المواضيع/السجل)، و`allowlist` (تضمين السياق فقط من المرسلين الموجودين في قائمة السماح)، و`allowlist_quote` (مثل allowlist لكن مع الاحتفاظ بسياق الاقتباس/الرد الصريح). تجاوز لكل قناة: `channels..contextVisibility`. - `channels.defaults.heartbeat.showOk`: تضمين حالات القنوات السليمة في مخرجات Heartbeat. - `channels.defaults.heartbeat.showAlerts`: تضمين الحالات المتدهورة/حالات الخطأ في مخرجات Heartbeat. -- `channels.defaults.heartbeat.useIndicator`: عرض مخرجات Heartbeat مضغوطة بأسلوب المؤشر. +- `channels.defaults.heartbeat.useIndicator`: عرض مخرجات Heartbeat بأسلوب مؤشرات مضغوط. ### WhatsApp -يعمل WhatsApp من خلال قناة الويب الخاصة بـ Gateway ‏(Baileys Web). يبدأ تلقائياً عندما توجد جلسة مرتبطة. +يعمل WhatsApp عبر قناة الويب الخاصة بـ Gateway ‏(Baileys Web). ويبدأ تلقائيًا عند وجود جلسة مرتبطة. ```json5 { @@ -124,7 +124,7 @@ x-i18n: textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // blue ticks (false in self-chat mode) + sendReadReceipts: true, // علامتا الصح الزرقاوان (false في وضع الدردشة الذاتية) groups: { "*": { requireMention: true }, }, @@ -164,10 +164,10 @@ x-i18n: } ``` -- تفترض الأوامر الصادرة الحساب `default` إذا كان موجوداً؛ وإلا فسيُستخدم أول معرّف حساب مضبوط (بعد الفرز). -- يتجاوز `channels.whatsapp.defaultAccount` الاختياري اختيار الحساب الافتراضي الاحتياطي ذلك عندما يطابق معرّف حساب مضبوطاً. -- ينقل `openclaw doctor` دليل المصادقة القديم أحادي الحساب لـ Baileys إلى `whatsapp/default`. -- التجاوزات لكل حساب: `channels.whatsapp.accounts..sendReadReceipts` و`channels.whatsapp.accounts..dmPolicy` و`channels.whatsapp.accounts..allowFrom`. +- تستخدم الأوامر الصادرة الحساب `default` افتراضيًا إذا كان موجودًا؛ وإلا فسيُستخدم أول معرّف حساب مُهيأ (بعد الفرز). +- يتجاوز `channels.whatsapp.defaultAccount` الاختياري هذا اختيار الحساب الافتراضي الاحتياطي عندما يطابق معرّف حساب مُهيأ. +- ينقل `openclaw doctor` دليل مصادقة Baileys القديم أحادي الحساب إلى `whatsapp/default`. +- تجاوزات لكل حساب: `channels.whatsapp.accounts..sendReadReceipts` و`channels.whatsapp.accounts..dmPolicy` و`channels.whatsapp.accounts..allowFrom`. @@ -202,7 +202,7 @@ x-i18n: historyLimit: 50, replyToMode: "first", // off | first | all | batched linkPreview: true, - streaming: "partial", // off | partial | block | progress (default: off; opt in explicitly to avoid preview-edit rate limits) + streaming: "partial", // off | partial | block | progress (الافتراضي: off؛ فعّله صراحةً لتجنب حدود معدل تعديل المعاينة) actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -226,11 +226,11 @@ x-i18n: ``` - رمز البوت: `channels.telegram.botToken` أو `channels.telegram.tokenFile` (ملف عادي فقط؛ تُرفض الروابط الرمزية)، مع `TELEGRAM_BOT_TOKEN` كقيمة احتياطية للحساب الافتراضي. -- يتجاوز `channels.telegram.defaultAccount` الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مضبوطاً. -- في إعدادات الحسابات المتعددة (معرّفا حسابين أو أكثر)، عيّن قيمة افتراضية صريحة (`channels.telegram.defaultAccount` أو `channels.telegram.accounts.default`) لتجنب التوجيه الاحتياطي؛ ويحذّر `openclaw doctor` عندما تكون هذه القيمة مفقودة أو غير صالحة. -- يحظر `configWrites: false` عمليات كتابة الإعدادات التي تبدأ من Telegram ‏(ترحيلات معرّف supergroup، و`/config set|unset`). -- تضبط إدخالات `bindings[]` ذات المستوى الأعلى مع `type: "acp"` ارتباطات ACP دائمة لمواضيع المنتدى (استخدم الصيغة القياسية `chatId:topic:topicId` في `match.peer.id`). دلالات الحقول مشتركة في [وكلاء ACP](/ar/tools/acp-agents#channel-specific-settings). -- تستخدم معاينات البث في Telegram ‏`sendMessage` + `editMessageText` (وتعمل في المحادثات المباشرة والجماعية). +- يتجاوز `channels.telegram.defaultAccount` الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مُهيأ. +- في إعدادات الحسابات المتعددة (معرّفا حساب أو أكثر)، عيّن افتراضيًا صريحًا (`channels.telegram.defaultAccount` أو `channels.telegram.accounts.default`) لتجنب التوجيه الاحتياطي؛ ويحذّر `openclaw doctor` عندما يكون هذا مفقودًا أو غير صالح. +- يؤدي `configWrites: false` إلى حظر عمليات كتابة الإعدادات التي يبدؤها Telegram (ترحيل معرّفات supergroup، و`/config set|unset`). +- تُهيّئ إدخالات `bindings[]` ذات المستوى الأعلى مع `type: "acp"` ارتباطات ACP دائمة لموضوعات المنتدى (استخدم الصيغة القانونية `chatId:topic:topicId` في `match.peer.id`). دلالات الحقول مشتركة في [ACP Agents](/ar/tools/acp-agents#channel-specific-settings). +- تستخدم معاينات البث في Telegram كلًا من `sendMessage` و`editMessageText` (وتعمل في الدردشات المباشرة والجماعية). - سياسة إعادة المحاولة: راجع [سياسة إعادة المحاولة](/ar/concepts/retry). ### Discord @@ -286,7 +286,7 @@ x-i18n: historyLimit: 20, textChunkLimit: 2000, chunkMode: "length", // length | newline - streaming: "off", // off | partial | block | progress (progress maps to partial on Discord) + streaming: "off", // off | partial | block | progress (تُطابق progress مع partial على Discord) maxLinesPerMessage: 17, ui: { components: { @@ -297,7 +297,7 @@ x-i18n: enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true }) + spawnSubagentSessions: false, // تفعيل اختياري لـ sessions_spawn({ thread: true }) }, voice: { enabled: true, @@ -333,36 +333,36 @@ x-i18n: } ``` -- الرمز المميّز: `channels.discord.token`، مع `DISCORD_BOT_TOKEN` كقيمة احتياطية للحساب الافتراضي. -- تستخدم الاستدعاءات الصادرة المباشرة التي توفّر `token` صريحاً لـ Discord ذلك الرمز المميّز في الاستدعاء؛ بينما تظل إعدادات إعادة المحاولة/السياسة الخاصة بالحساب مأخوذة من الحساب المحدد في اللقطة النشطة لوقت التشغيل. -- يتجاوز `channels.discord.defaultAccount` الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مضبوطاً. -- استخدم `user:` ‏(رسالة مباشرة) أو `channel:` ‏(قناة guild) لأهداف التسليم؛ تُرفض المعرّفات الرقمية الخام. -- تكون أسماء slug الخاصة بـ guild بأحرف صغيرة مع استبدال المسافات بـ `-`؛ وتستخدم مفاتيح القنوات الاسم المحوّل إلى slug ‏(من دون `#`). يُفضَّل استخدام معرّفات guild. -- تُتجاهل الرسائل التي ينشئها البوت افتراضياً. يفعّل `allowBots: true` قبولها؛ واستخدم `allowBots: "mentions"` لقبول رسائل البوت التي تذكر البوت فقط (مع الاستمرار في تصفية رسائل البوت نفسه). -- تُسقط `channels.discord.guilds..ignoreOtherMentions` ‏(وتجاوزات القنوات) الرسائل التي تذكر مستخدماً آخر أو دوراً آخر ولكن لا تذكر البوت (باستثناء @everyone/@here). -- يقوم `maxLinesPerMessage` ‏(الافتراضي 17) بتقسيم الرسائل الطويلة عمودياً حتى عندما تكون أقل من 2000 حرف. -- يتحكم `channels.discord.threadBindings` في التوجيه المرتبط بخيوط Discord: - - `enabled`: تجاوز Discord لميزات الجلسات المرتبطة بالخيوط (`/focus` و`/unfocus` و`/agents` و`/session idle` و`/session max-age`، بالإضافة إلى التسليم/التوجيه المرتبط) - - `idleHours`: تجاوز Discord لإلغاء التركيز التلقائي بسبب عدم النشاط بالساعات (`0` للتعطيل) - - `maxAgeHours`: تجاوز Discord للحد الأقصى الصارم للعمر بالساعات (`0` للتعطيل) - - `spawnSubagentSessions`: مفتاح اشتراك اختياري لإنشاء/ربط الخيوط تلقائياً عبر `sessions_spawn({ thread: true })` -- تضبط إدخالات `bindings[]` ذات المستوى الأعلى مع `type: "acp"` ارتباطات ACP دائمة للقنوات والخيوط (استخدم معرّف القناة/الخيط في `match.peer.id`). دلالات الحقول مشتركة في [وكلاء ACP](/ar/tools/acp-agents#channel-specific-settings). -- يضبط `channels.discord.ui.components.accentColor` لون التمييز لحاويات Discord components v2. -- يفعّل `channels.discord.voice` محادثات قنوات Discord الصوتية، مع تجاوزات اختيارية للانضمام التلقائي + TTS. -- تمرِّر `channels.discord.voice.daveEncryption` و`channels.discord.voice.decryptionFailureTolerance` إلى خيارات DAVE في `@discordjs/voice` ‏(`true` و`24` افتراضياً). -- يحاول OpenClaw أيضاً استعادة استقبال الصوت عبر مغادرة جلسة الصوت ثم إعادة الانضمام إليها بعد تكرار حالات فشل فك التشفير. -- يُعد `channels.discord.streaming` مفتاح وضع البث القياسي. وتُرحَّل تلقائياً القيم القديمة `streamMode` وقيم `streaming` المنطقية. -- يربط `channels.discord.autoPresence` حالة التوفّر وقت التشغيل بحضور البوت (سليم => online، متدهور => idle، exhausted => dnd) ويسمح بتجاوزات اختيارية لنص الحالة. -- يعيد `channels.discord.dangerouslyAllowNameMatching` تفعيل المطابقة بالأسماء/الوسوم القابلة للتغيير (وضع توافق طارئ). +- الرمز المميز: `channels.discord.token`، مع `DISCORD_BOT_TOKEN` كقيمة احتياطية للحساب الافتراضي. +- تستخدم الاستدعاءات الصادرة المباشرة التي توفّر `token` صريحًا لـ Discord ذلك الرمز المميز لهذا الاستدعاء؛ بينما تستمر إعدادات إعادة المحاولة/السياسة الخاصة بالحساب في الاعتماد على الحساب المحدد في اللقطة النشطة أثناء التشغيل. +- يتجاوز `channels.discord.defaultAccount` الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مُهيأ. +- استخدم `user:` (رسالة مباشرة) أو `channel:` (قناة guild) كأهداف للتسليم؛ وتُرفض المعرّفات الرقمية المجردة. +- تكون الأسماء المختصرة لـ guild بأحرف صغيرة مع استبدال المسافات بـ `-`؛ وتستخدم مفاتيح القنوات الاسم المختصر (من دون `#`). ويُفضّل استخدام معرّفات guild. +- تُتجاهل الرسائل التي ينشئها البوت افتراضيًا. يفعّل `allowBots: true` قبولها؛ واستخدم `allowBots: "mentions"` لقبول رسائل البوت التي تذكر البوت فقط (مع استمرار تصفية رسائله الذاتية). +- يؤدي `channels.discord.guilds..ignoreOtherMentions` (وتجاوزات القنوات) إلى إسقاط الرسائل التي تذكر مستخدمًا آخر أو دورًا آخر ولكنها لا تذكر البوت (باستثناء @everyone/@here). +- يقسم `maxLinesPerMessage` (الافتراضي 17) الرسائل الطويلة عموديًا حتى عندما تكون أقل من 2000 حرف. +- يتحكم `channels.discord.threadBindings` في التوجيه المرتبط بسلاسل Discord: + - `enabled`: تجاوز Discord لميزات الجلسات المرتبطة بالسلاسل (`/focus` و`/unfocus` و`/agents` و`/session idle` و`/session max-age`، والتسليم/التوجيه المرتبط) + - `idleHours`: تجاوز Discord لإلغاء التركيز التلقائي بعد عدم النشاط، بالساعات (`0` للتعطيل) + - `maxAgeHours`: تجاوز Discord للحد الأقصى الصارم للعمر، بالساعات (`0` للتعطيل) + - `spawnSubagentSessions`: مفتاح تفعيل اختياري لإنشاء/ربط السلاسل تلقائيًا بواسطة `sessions_spawn({ thread: true })` +- تُهيّئ إدخالات `bindings[]` ذات المستوى الأعلى مع `type: "acp"` ارتباطات ACP دائمة للقنوات والسلاسل (استخدم معرّف القناة/السلسلة في `match.peer.id`). دلالات الحقول مشتركة في [ACP Agents](/ar/tools/acp-agents#channel-specific-settings). +- يضبط `channels.discord.ui.components.accentColor` لون التمييز لحاويات مكونات Discord v2. +- يفعّل `channels.discord.voice` محادثات القنوات الصوتية في Discord وتجاوزات الانضمام التلقائي وTTS الاختيارية. +- يُمرَّر `channels.discord.voice.daveEncryption` و`channels.discord.voice.decryptionFailureTolerance` إلى خيارات DAVE في `@discordjs/voice` (القيم الافتراضية `true` و`24`). +- يحاول OpenClaw أيضًا استعادة استقبال الصوت عبر مغادرة الجلسة الصوتية وإعادة الانضمام إليها بعد تكرار إخفاقات فك التشفير. +- يُعد `channels.discord.streaming` مفتاح وضع البث القانوني. وتُرحَّل تلقائيًا القيم القديمة `streamMode` وقيم `streaming` المنطقية. +- يربط `channels.discord.autoPresence` حالة التوفر أثناء التشغيل بحضور البوت (سليم => online، متدهور => idle، مستنفد => dnd)، ويسمح بتجاوزات اختيارية لنص الحالة. +- يعيد `channels.discord.dangerouslyAllowNameMatching` تفعيل المطابقة القابلة للتغيير للاسم/الوسم (وضع توافق طارئ). - `channels.discord.execApprovals`: تسليم موافقات exec الأصلية في Discord وتفويض الموافقين. - - `enabled`: ‏`true` أو `false` أو `"auto"` ‏(الافتراضي). في الوضع التلقائي، تُفعَّل موافقات exec عندما يمكن حل الموافقين من `approvers` أو `commands.ownerAllowFrom`. - - `approvers`: معرّفات مستخدمي Discord المسموح لهم بالموافقة على طلبات exec. وتعود القيمة إلى `commands.ownerAllowFrom` عند حذفها. + - `enabled`: القيم `true` أو `false` أو `"auto"` (الافتراضي). في وضع auto، تُفعَّل موافقات exec عندما يمكن حلّ الموافقين من `approvers` أو `commands.ownerAllowFrom`. + - `approvers`: معرّفات مستخدمي Discord المسموح لهم بالموافقة على طلبات exec. ويُستخدم `commands.ownerAllowFrom` كقيمة احتياطية عند حذفه. - `agentFilter`: قائمة سماح اختيارية لمعرّفات الوكلاء. احذفها لتمرير الموافقات لجميع الوكلاء. - - `sessionFilter`: أنماط مفاتيح الجلسات الاختيارية (substring أو regex). - - `target`: مكان إرسال مطالبات الموافقة. يرسل `"dm"` ‏(الافتراضي) إلى الرسائل المباشرة للموافق، ويرسل `"channel"` إلى القناة الأصلية، ويرسل `"both"` إلى الاثنين معاً. وعندما يتضمن الهدف `"channel"`، لا تكون الأزرار قابلة للاستخدام إلا من قبل الموافقين الذين تم حلهم. - - `cleanupAfterResolve`: عند ضبطه على `true`، يحذف رسائل الموافقة المباشرة بعد الموافقة أو الرفض أو انتهاء المهلة. + - `sessionFilter`: أنماط مفاتيح جلسات اختيارية (سلسلة فرعية أو regex). + - `target`: مكان إرسال مطالبات الموافقة. ترسل `"dm"` (الافتراضي) إلى الرسائل المباشرة للموافقين، وترسل `"channel"` إلى القناة الأصلية، وترسل `"both"` إلى كليهما. وعندما يتضمن الهدف `"channel"`، لا تكون الأزرار قابلة للاستخدام إلا من قبل الموافقين الذين تم حلّهم. + - `cleanupAfterResolve`: عند تعيينه إلى `true`، يحذف رسائل الموافقة المباشرة بعد الموافقة أو الرفض أو انتهاء المهلة. -**أوضاع إشعارات التفاعل:** `off` ‏(لا شيء)، `own` ‏(رسائل البوت، الافتراضي)، `all` ‏(كل الرسائل)، `allowlist` ‏(من `guilds..users` على جميع الرسائل). +**أوضاع إشعارات التفاعلات:** `off` (بدون)، `own` (رسائل البوت، الافتراضي)، `all` (كل الرسائل)، `allowlist` (من `guilds..users` على جميع الرسائل). ### Google Chat @@ -393,11 +393,11 @@ x-i18n: } ``` -- JSON لحساب الخدمة: مضمن (`serviceAccount`) أو معتمد على ملف (`serviceAccountFile`). -- كما أن SecretRef لحساب الخدمة مدعوم أيضاً (`serviceAccountRef`). +- JSON لحساب الخدمة: مضمّن (`serviceAccount`) أو مستند إلى ملف (`serviceAccountFile`). +- كما أن SecretRef لحساب الخدمة مدعوم أيضًا (`serviceAccountRef`). - القيم الاحتياطية من البيئة: `GOOGLE_CHAT_SERVICE_ACCOUNT` أو `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. -- استخدم `spaces/` أو `users/` لأهداف التسليم. -- يعيد `channels.googlechat.dangerouslyAllowNameMatching` تفعيل المطابقة بعناوين البريد الإلكتروني القابلة للتغيير (وضع توافق طارئ). +- استخدم `spaces/` أو `users/` كأهداف للتسليم. +- يعيد `channels.googlechat.dangerouslyAllowNameMatching` تفعيل مطابقة كيان البريد الإلكتروني القابلة للتغيير (وضع توافق طارئ). ### Slack @@ -449,7 +449,7 @@ x-i18n: chunkMode: "length", streaming: { mode: "partial", // off | partial | block | progress - nativeTransport: true, // use Slack native streaming API when mode=partial + nativeTransport: true, // استخدم واجهة Slack الأصلية للبث عندما يكون mode=partial }, mediaMaxMb: 20, execApprovals: { @@ -464,39 +464,34 @@ x-i18n: } ``` -- يتطلب **Socket mode** كلاً من `botToken` و`appToken` ‏(`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` كقيمة احتياطية من البيئة للحساب الافتراضي). -- يتطلب **HTTP mode** ‏`botToken` بالإضافة إلى `signingSecret` ‏(على المستوى الجذري أو لكل حساب). -- تقبل `botToken` و`appToken` و`signingSecret` و`userToken` سلاسل نصية صريحة - أو كائنات SecretRef. -- تعرض لقطات حساب Slack حقول مصدر/حالة لكل بيانات اعتماد مثل - `botTokenSource` و`botTokenStatus` و`appTokenStatus`، وفي وضع HTTP، - `signingSecretStatus`. وتعني `configured_unavailable` أن الحساب - مضبوط عبر SecretRef لكن مسار الأمر/وقت التشغيل الحالي لم يتمكن - من حل قيمة السر. -- يحظر `configWrites: false` عمليات كتابة الإعدادات التي تبدأ من Slack. -- يتجاوز `channels.slack.defaultAccount` الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مضبوطاً. -- يُعد `channels.slack.streaming.mode` مفتاح وضع بث Slack القياسي. ويتحكم `channels.slack.streaming.nativeTransport` في ناقل البث الأصلي لـ Slack. وتُرحَّل تلقائياً القيم القديمة `streamMode` وقيم `streaming` المنطقية و`nativeStreaming`. -- استخدم `user:` ‏(رسالة مباشرة) أو `channel:` لأهداف التسليم. +- يتطلب **وضع Socket** كلًا من `botToken` و`appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` كقيمة احتياطية من البيئة للحساب الافتراضي). +- يتطلب **وضع HTTP** `botToken` بالإضافة إلى `signingSecret` (على المستوى الجذري أو لكل حساب). +- تقبل `botToken` و`appToken` و`signingSecret` و`userToken` سلاسل نصية صريحة أو كائنات SecretRef. +- تعرض لقطات حساب Slack حقول المصدر/الحالة لكل اعتماد مثل `botTokenSource` و`botTokenStatus` و`appTokenStatus`، وفي وضع HTTP، `signingSecretStatus`. وتعني `configured_unavailable` أن الحساب مهيأ عبر SecretRef لكن مسار الأمر/التشغيل الحالي لم يتمكن من حل قيمة السر. +- يؤدي `configWrites: false` إلى حظر عمليات كتابة الإعدادات التي يبدؤها Slack. +- يتجاوز `channels.slack.defaultAccount` الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مُهيأ. +- يُعد `channels.slack.streaming.mode` مفتاح وضع بث Slack القانوني. ويتحكم `channels.slack.streaming.nativeTransport` في وسيلة النقل الأصلية للبث في Slack. وتُرحَّل تلقائيًا القيم القديمة `streamMode` وقيم `streaming` المنطقية و`nativeStreaming`. +- استخدم `user:` (رسالة مباشرة) أو `channel:` كأهداف للتسليم. -**أوضاع إشعارات التفاعل:** `off` و`own` ‏(الافتراضي) و`all` و`allowlist` ‏(من `reactionAllowlist`). +**أوضاع إشعارات التفاعلات:** `off` و`own` (الافتراضي) و`all` و`allowlist` (من `reactionAllowlist`). -**عزل جلسة الخيط:** يكون `thread.historyScope` لكل خيط على حدة (الافتراضي) أو مشتركاً على مستوى القناة. ينسخ `thread.inheritParent` سجل القناة الأصلية إلى الخيوط الجديدة. +**عزل جلسات السلاسل:** يكون `thread.historyScope` لكل سلسلة على حدة (الافتراضي) أو مشتركًا عبر القناة. ويؤدي `thread.inheritParent` إلى نسخ سجل القناة الأم إلى السلاسل الجديدة. -- يتطلب كل من البث الأصلي في Slack وحالة الخيط بأسلوب مساعد Slack ‏"is typing..." هدف رد ضمن خيط. تبقى الرسائل المباشرة ذات المستوى الأعلى خارج الخيوط افتراضياً، لذلك تستخدم `typingReaction` أو التسليم العادي بدلاً من المعاينة بأسلوب الخيط. -- تضيف `typingReaction` تفاعلاً مؤقتاً إلى رسالة Slack الواردة أثناء تنفيذ الرد، ثم تزيله عند الاكتمال. استخدم shortcode لرمز Slack التعبيري مثل `"hourglass_flowing_sand"`. -- `channels.slack.execApprovals`: تسليم موافقات exec الأصلية في Slack وتفويض الموافقين. نفس المخطط كما في Discord: ‏`enabled` ‏(`true`/`false`/`"auto"`)، و`approvers` ‏(معرّفات مستخدمي Slack)، و`agentFilter`، و`sessionFilter`، و`target` ‏(`"dm"` أو `"channel"` أو `"both"`). +- يتطلب البث الأصلي في Slack بالإضافة إلى حالة السلسلة بأسلوب Slack assistant "is typing..." هدف ردّ داخل سلسلة. وتبقى الرسائل المباشرة ذات المستوى الأعلى خارج السلاسل افتراضيًا، لذلك تستخدم `typingReaction` أو التسليم العادي بدلًا من المعاينة بأسلوب السلسلة. +- تضيف `typingReaction` تفاعلًا مؤقتًا إلى رسالة Slack الواردة أثناء تشغيل الرد، ثم تزيله عند الاكتمال. استخدم اختصار emoji في Slack مثل `"hourglass_flowing_sand"`. +- `channels.slack.execApprovals`: تسليم موافقات exec الأصلية في Slack وتفويض الموافقين. نفس مخطط Discord: `enabled` (`true`/`false`/`"auto"`)، و`approvers` (معرّفات مستخدمي Slack)، و`agentFilter`، و`sessionFilter`، و`target` (`"dm"` أو `"channel"` أو `"both"`). | مجموعة الإجراءات | الافتراضي | ملاحظات | | ------------ | ------- | ---------------------- | | reactions | مفعّل | التفاعل + سرد التفاعلات | -| messages | مفعّل | قراءة/إرسال/تحرير/حذف | -| pins | مفعّل | تثبيت/إلغاء تثبيت/سرد | -| memberInfo | مفعّل | معلومات العضو | -| emojiList | مفعّل | قائمة الرموز التعبيرية المخصصة | +| messages | مفعّل | قراءة/إرسال/تعديل/حذف | +| pins | مفعّل | تثبيت/إلغاء تثبيت/سرد | +| memberInfo | مفعّل | معلومات العضو | +| emojiList | مفعّل | قائمة emoji المخصصة | ### Mattermost -يأتي Mattermost كـ Plugin: ‏`openclaw plugins install @openclaw/mattermost`. +يُشحن Mattermost كـ Plugin: ‏`openclaw plugins install @openclaw/mattermost`. ```json5 { @@ -513,10 +508,10 @@ x-i18n: "team-channel-id": { requireMention: false }, }, commands: { - native: true, // opt-in + native: true, // تفعيل اختياري nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // Optional explicit URL for reverse-proxy/public deployments + // عنوان URL صريح اختياري لعمليات النشر العامة/خلف وكيل عكسي callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -526,23 +521,18 @@ x-i18n: } ``` -أوضاع الدردشة: `oncall` ‏(الرد عند @-mention، الافتراضي)، و`onmessage` ‏(كل رسالة)، و`onchar` ‏(الرسائل التي تبدأ ببادئة المشغّل). +أوضاع الدردشة: `oncall` (الرد عند @-mention، الافتراضي)، و`onmessage` (كل رسالة)، و`onchar` (الرسائل التي تبدأ ببادئة التشغيل). عند تفعيل الأوامر الأصلية في Mattermost: -- يجب أن يكون `commands.callbackPath` مساراً (على سبيل المثال `/api/channels/mattermost/command`) وليس عنوان URL كاملاً. -- يجب أن يُحل `commands.callbackUrl` إلى نقطة نهاية Gateway الخاصة بـ OpenClaw وأن يكون قابلاً للوصول من خادم Mattermost. -- تتم مصادقة استدعاءات slash الأصلية باستخدام الرموز المميزة لكل أمر التي يعيدها - Mattermost أثناء تسجيل أوامر slash. إذا فشل التسجيل أو لم تُفعَّل أي - أوامر، يرفض OpenClaw الاستدعاءات مع - `Unauthorized: invalid command token.` -- بالنسبة لمضيفي الاستدعاء الخاصين/الداخليين/ضمن tailnet، قد يتطلب Mattermost - أن تتضمن `ServiceSettings.AllowedUntrustedInternalConnections` المضيف/النطاق الخاص بالاستدعاء. - استخدم قيم المضيف/النطاق، وليس عناوين URL كاملة. -- `channels.mattermost.configWrites`: السماح أو الرفض لعمليات كتابة الإعدادات التي تبدأ من Mattermost. -- `channels.mattermost.requireMention`: يتطلب `@mention` قبل الرد في القنوات. -- `channels.mattermost.groups..requireMention`: تجاوز تقييد الإشارة لكل قناة (`"*"` كافتراضي). -- يتجاوز `channels.mattermost.defaultAccount` الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مضبوطاً. +- يجب أن يكون `commands.callbackPath` مسارًا (على سبيل المثال `/api/channels/mattermost/command`)، وليس عنوان URL كاملًا. +- يجب أن يشير `commands.callbackUrl` إلى نقطة نهاية Gateway الخاصة بـ OpenClaw وأن يكون قابلاً للوصول من خادم Mattermost. +- تُصادَق عمليات الاستدعاء العكسي الأصلية لـ slash بواسطة الرموز المميزة الخاصة بكل أمر التي يعيدها Mattermost أثناء تسجيل slash command. وإذا فشل التسجيل أو لم تُفعَّل أي أوامر، يرفض OpenClaw عمليات الاستدعاء العكسي بالرسالة `Unauthorized: invalid command token.` +- بالنسبة إلى مستضيفي الاستدعاء العكسي الخاصين/داخليي tailnet/الداخليين، قد يتطلب Mattermost أن يتضمن `ServiceSettings.AllowedUntrustedInternalConnections` مستضيف/نطاق الاستدعاء العكسي. استخدم قيم المستضيف/النطاق، وليس عناوين URL كاملة. +- `channels.mattermost.configWrites`: السماح أو الرفض لعمليات كتابة الإعدادات التي يبدؤها Mattermost. +- `channels.mattermost.requireMention`: طلب `@mention` قبل الرد في القنوات. +- `channels.mattermost.groups..requireMention`: تجاوز اشتراط الإشارة لكل قناة (`"*"` للافتراضي). +- يتجاوز `channels.mattermost.defaultAccount` الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مُهيأ. ### Signal @@ -551,7 +541,7 @@ x-i18n: channels: { signal: { enabled: true, - account: "+15555550123", // optional account binding + account: "+15555550123", // ربط حساب اختياري dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -563,15 +553,15 @@ x-i18n: } ``` -**أوضاع إشعارات التفاعل:** `off` و`own` ‏(الافتراضي) و`all` و`allowlist` ‏(من `reactionAllowlist`). +**أوضاع إشعارات التفاعلات:** `off` و`own` (الافتراضي) و`all` و`allowlist` (من `reactionAllowlist`). - `channels.signal.account`: تثبيت بدء تشغيل القناة على هوية حساب Signal محددة. -- `channels.signal.configWrites`: السماح أو الرفض لعمليات كتابة الإعدادات التي تبدأ من Signal. -- يتجاوز `channels.signal.defaultAccount` الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مضبوطاً. +- `channels.signal.configWrites`: السماح أو الرفض لعمليات كتابة الإعدادات التي يبدؤها Signal. +- يتجاوز `channels.signal.defaultAccount` الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مُهيأ. ### BlueBubbles -يُعد BlueBubbles المسار الموصى به لـ iMessage ‏(مدعوماً عبر Plugin، ويُضبط ضمن `channels.bluebubbles`). +يُعد BlueBubbles المسار الموصى به لـ iMessage (مدعومًا بواسطة Plugin، ويُضبط تحت `channels.bluebubbles`). ```json5 { @@ -580,20 +570,20 @@ x-i18n: enabled: true, dmPolicy: "pairing", // serverUrl, password, webhookPath, group controls, and advanced actions: - // see /channels/bluebubbles + // راجع /channels/bluebubbles }, }, } ``` - مسارات المفاتيح الأساسية المغطاة هنا: `channels.bluebubbles` و`channels.bluebubbles.dmPolicy`. -- يتجاوز `channels.bluebubbles.defaultAccount` الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مضبوطاً. -- يمكن لإدخالات `bindings[]` ذات المستوى الأعلى مع `type: "acp"` ربط محادثات BlueBubbles بجلسات ACP دائمة. استخدم BlueBubbles handle أو سلسلة target ‏(`chat_id:*` أو `chat_guid:*` أو `chat_identifier:*`) في `match.peer.id`. دلالات الحقول المشتركة: [وكلاء ACP](/ar/tools/acp-agents#channel-specific-settings). -- إعداد قناة BlueBubbles الكامل موثّق في [BlueBubbles](/ar/channels/bluebubbles). +- يتجاوز `channels.bluebubbles.defaultAccount` الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مُهيأ. +- يمكن لإدخالات `bindings[]` ذات المستوى الأعلى مع `type: "acp"` ربط محادثات BlueBubbles بجلسات ACP دائمة. استخدم مقبض BlueBubbles أو سلسلة الهدف (`chat_id:*` أو `chat_guid:*` أو `chat_identifier:*`) في `match.peer.id`. دلالات الحقول المشتركة: [ACP Agents](/ar/tools/acp-agents#channel-specific-settings). +- إعداد قناة BlueBubbles الكامل موثق في [BlueBubbles](/ar/channels/bluebubbles). ### iMessage -يقوم OpenClaw بتشغيل `imsg rpc` ‏(JSON-RPC عبر stdio). لا حاجة إلى daemon أو منفذ. +يشغّل OpenClaw الأمر `imsg rpc` ‏(JSON-RPC عبر stdio). لا حاجة إلى daemon أو منفذ. ```json5 { @@ -617,17 +607,17 @@ x-i18n: } ``` -- يتجاوز `channels.imessage.defaultAccount` الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مضبوطاً. +- يتجاوز `channels.imessage.defaultAccount` الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مُهيأ. - يتطلب Full Disk Access إلى قاعدة بيانات Messages. -- يُفضَّل استخدام أهداف `chat_id:`. استخدم `imsg chats --limit 20` لسرد الدردشات. -- يمكن أن يشير `cliPath` إلى SSH wrapper؛ اضبط `remoteHost` ‏(`host` أو `user@host`) لجلب المرفقات عبر SCP. +- يُفضل استخدام أهداف `chat_id:`. استخدم `imsg chats --limit 20` لسرد الدردشات. +- يمكن أن يشير `cliPath` إلى غلاف SSH؛ اضبط `remoteHost` (`host` أو `user@host`) لجلب المرفقات عبر SCP. - يقيّد `attachmentRoots` و`remoteAttachmentRoots` مسارات المرفقات الواردة (الافتراضي: `/Users/*/Library/Messages/Attachments`). -- يستخدم SCP التحقق الصارم من مفتاح المضيف، لذا تأكد من أن مفتاح مضيف relay موجود مسبقاً في `~/.ssh/known_hosts`. -- `channels.imessage.configWrites`: السماح أو الرفض لعمليات كتابة الإعدادات التي تبدأ من iMessage. -- يمكن لإدخالات `bindings[]` ذات المستوى الأعلى مع `type: "acp"` ربط محادثات iMessage بجلسات ACP دائمة. استخدم handle مطبعاً أو هدف دردشة صريحاً (`chat_id:*` أو `chat_guid:*` أو `chat_identifier:*`) في `match.peer.id`. دلالات الحقول المشتركة: [وكلاء ACP](/ar/tools/acp-agents#channel-specific-settings). +- يستخدم SCP التحقق الصارم من مفتاح المستضيف، لذا تأكد من أن مفتاح مستضيف الترحيل موجود مسبقًا في `~/.ssh/known_hosts`. +- `channels.imessage.configWrites`: السماح أو الرفض لعمليات كتابة الإعدادات التي يبدؤها iMessage. +- يمكن لإدخالات `bindings[]` ذات المستوى الأعلى مع `type: "acp"` ربط محادثات iMessage بجلسات ACP دائمة. استخدم مقبضًا مُطبَّعًا أو هدف دردشة صريحًا (`chat_id:*` أو `chat_guid:*` أو `chat_identifier:*`) في `match.peer.id`. دلالات الحقول المشتركة: [ACP Agents](/ar/tools/acp-agents#channel-specific-settings). - + ```bash #!/usr/bin/env bash @@ -638,7 +628,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -يعمل Matrix عبر extension ويُضبط ضمن `channels.matrix`. +تأتي Matrix مدعومة بواسطة extension وتُضبط تحت `channels.matrix`. ```json5 { @@ -668,25 +658,25 @@ exec ssh -T gateway-host imsg "$@" } ``` -- تستخدم مصادقة الرمز المميز `accessToken`؛ وتستخدم مصادقة كلمة المرور `userId` + `password`. -- يمرّر `channels.matrix.proxy` حركة HTTP الخاصة بـ Matrix عبر HTTP(S) proxy صريح. ويمكن للحسابات المسمّاة تجاوزه عبر `channels.matrix.accounts..proxy`. -- يسمح `channels.matrix.network.dangerouslyAllowPrivateNetwork` بخوادم homeserver الخاصة/الداخلية. ويُعد `proxy` وهذا الاشتراك الشبكي تحكمين مستقلين. +- تستخدم مصادقة الرمز `accessToken`؛ وتستخدم مصادقة كلمة المرور `userId` + `password`. +- يوجّه `channels.matrix.proxy` حركة HTTP الخاصة بـ Matrix عبر وكيل HTTP(S) صريح. ويمكن للحسابات المسماة تجاوزه باستخدام `channels.matrix.accounts..proxy`. +- يسمح `channels.matrix.network.dangerouslyAllowPrivateNetwork` بخوادم homeserver الخاصة/الداخلية. ويُعد كل من `proxy` وخيار الشبكة هذا عنصرَي تحكم مستقلين. - يحدد `channels.matrix.defaultAccount` الحساب المفضل في إعدادات الحسابات المتعددة. -- القيمة الافتراضية لـ `channels.matrix.autoJoin` هي `off`، لذا تُتجاهل الغرف المدعوّة ودعوات الرسائل المباشرة الجديدة حتى تضبط `autoJoin: "allowlist"` مع `autoJoinAllowlist` أو `autoJoin: "always"`. +- تكون القيمة الافتراضية لـ `channels.matrix.autoJoin` هي `off`، لذا تُتجاهل الغرف المدعوّة ودعوات الرسائل المباشرة الجديدة حتى تعيّن `autoJoin: "allowlist"` مع `autoJoinAllowlist` أو `autoJoin: "always"`. - `channels.matrix.execApprovals`: تسليم موافقات exec الأصلية في Matrix وتفويض الموافقين. - - `enabled`: ‏`true` أو `false` أو `"auto"` ‏(الافتراضي). في الوضع التلقائي، تُفعَّل موافقات exec عندما يمكن حل الموافقين من `approvers` أو `commands.ownerAllowFrom`. + - `enabled`: القيم `true` أو `false` أو `"auto"` (الافتراضي). في وضع auto، تُفعَّل موافقات exec عندما يمكن حلّ الموافقين من `approvers` أو `commands.ownerAllowFrom`. - `approvers`: معرّفات مستخدمي Matrix ‏(مثل `@owner:example.org`) المسموح لهم بالموافقة على طلبات exec. - `agentFilter`: قائمة سماح اختيارية لمعرّفات الوكلاء. احذفها لتمرير الموافقات لجميع الوكلاء. - - `sessionFilter`: أنماط مفاتيح الجلسات الاختيارية (substring أو regex). - - `target`: مكان إرسال مطالبات الموافقة. `"dm"` ‏(الافتراضي) أو `"channel"` ‏(الغرفة الأصلية) أو `"both"`. + - `sessionFilter`: أنماط مفاتيح جلسات اختيارية (سلسلة فرعية أو regex). + - `target`: مكان إرسال مطالبات الموافقة. `"dm"` (الافتراضي) أو `"channel"` (الغرفة الأصلية) أو `"both"`. - تجاوزات لكل حساب: `channels.matrix.accounts..execApprovals`. -- يتحكم `channels.matrix.dm.sessionScope` في كيفية تجميع الرسائل المباشرة في Matrix ضمن الجلسات: `per-user` ‏(الافتراضي) يشارك حسب النظير الموجّه، بينما `per-room` يعزل كل غرفة رسالة مباشرة. -- تستخدم مجسات حالة Matrix وعمليات البحث الحية في الدليل سياسة proxy نفسها الخاصة بحركة وقت التشغيل. +- يتحكم `channels.matrix.dm.sessionScope` في كيفية تجميع الرسائل المباشرة في Matrix ضمن الجلسات: يشارك `per-user` (الافتراضي) حسب النظير الموجّه، بينما يعزل `per-room` كل غرفة رسائل مباشرة على حدة. +- تستخدم مجسات الحالة في Matrix وعمليات بحث الدليل الحية سياسة الوكيل نفسها المستخدمة في حركة التشغيل. - إعداد Matrix الكامل وقواعد الاستهداف وأمثلة الإعداد موثقة في [Matrix](/ar/channels/matrix). ### Microsoft Teams -يعمل Microsoft Teams عبر extension ويُضبط ضمن `channels.msteams`. +تأتي Microsoft Teams مدعومة بواسطة extension وتُضبط تحت `channels.msteams`. ```json5 { @@ -695,18 +685,18 @@ exec ssh -T gateway-host imsg "$@" enabled: true, configWrites: true, // appId, appPassword, tenantId, webhook, team/channel policies: - // see /channels/msteams + // راجع /channels/msteams }, }, } ``` - مسارات المفاتيح الأساسية المغطاة هنا: `channels.msteams` و`channels.msteams.configWrites`. -- إعداد Teams الكامل (بيانات الاعتماد، وWebhook، وسياسة الرسائل المباشرة/المجموعات، والتجاوزات لكل فريق/قناة) موثّق في [Microsoft Teams](/ar/channels/msteams). +- إعداد Teams الكامل (بيانات الاعتماد وWebhook وسياسة الرسائل المباشرة/المجموعات والتجاوزات لكل فريق/قناة) موثق في [Microsoft Teams](/ar/channels/msteams). ### IRC -يعمل IRC عبر extension ويُضبط ضمن `channels.irc`. +تأتي IRC مدعومة بواسطة extension وتُضبط تحت `channels.irc`. ```json5 { @@ -728,10 +718,10 @@ exec ssh -T gateway-host imsg "$@" ``` - مسارات المفاتيح الأساسية المغطاة هنا: `channels.irc` و`channels.irc.dmPolicy` و`channels.irc.configWrites` و`channels.irc.nickserv.*`. -- يتجاوز `channels.irc.defaultAccount` الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مضبوطاً. -- إعداد قناة IRC الكامل (host/port/TLS/channels/allowlists/mention gating) موثّق في [IRC](/ar/channels/irc). +- يتجاوز `channels.irc.defaultAccount` الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مُهيأ. +- إعداد قناة IRC الكامل (المستضيف/المنفذ/TLS/القنوات/قوائم السماح/اشتراط الإشارة) موثق في [IRC](/ar/channels/irc). -### تعدد الحسابات (جميع القنوات) +### تعدد الحسابات (كل القنوات) شغّل عدة حسابات لكل قناة (لكل منها `accountId` خاص بها): @@ -754,28 +744,28 @@ exec ssh -T gateway-host imsg "$@" } ``` -- يُستخدم `default` عند حذف `accountId` ‏(CLI + التوجيه). -- تنطبق رموز البيئة فقط على الحساب **الافتراضي**. -- تنطبق إعدادات القناة الأساسية على جميع الحسابات ما لم يتم تجاوزها لكل حساب. +- يُستخدم `default` عند حذف `accountId` (في CLI والتوجيه). +- لا تنطبق الرموز المميزة من البيئة إلا على الحساب **default**. +- تنطبق إعدادات القناة الأساسية على جميع الحسابات ما لم تُتجاوز لكل حساب. - استخدم `bindings[].match.accountId` لتوجيه كل حساب إلى وكيل مختلف. -- إذا أضفت حساباً غير افتراضي عبر `openclaw channels add` ‏(أو onboarding للقناة) بينما لا تزال على إعداد قناة أحادي الحساب على المستوى الأعلى، فإن OpenClaw يرقّي أولاً القيم أحادية الحساب على المستوى الأعلى ذات النطاق الحسابي إلى خريطة حسابات القناة بحيث يستمر الحساب الأصلي في العمل. تنقل معظم القنوات هذه القيم إلى `channels..accounts.default`؛ ويمكن لـ Matrix بدلاً من ذلك الاحتفاظ بهدف مسمّى/افتراضي موجود ومطابق. -- تستمر ارتباطات القنوات الحالية فقط (من دون `accountId`) في مطابقة الحساب الافتراضي؛ وتظل الارتباطات ذات النطاق الحسابي اختيارية. -- يقوم `openclaw doctor --fix` أيضاً بإصلاح الأشكال المختلطة عبر نقل القيم أحادية الحساب على المستوى الأعلى ذات النطاق الحسابي إلى الحساب المُرقّى المختار لتلك القناة. تستخدم معظم القنوات `accounts.default`؛ ويمكن لـ Matrix بدلاً من ذلك الاحتفاظ بهدف مسمّى/افتراضي موجود ومطابق. +- إذا أضفت حسابًا غير افتراضي عبر `openclaw channels add` (أو إعداد القناة) بينما لا تزال تستخدم إعداد قناة أحادي الحساب على المستوى الأعلى، فسيقوم OpenClaw أولًا بترقية قيم الحساب الأحادي على المستوى الأعلى والمحددة بنطاق الحساب إلى خريطة حسابات القناة لكي يستمر الحساب الأصلي في العمل. تنقلها معظم القنوات إلى `channels..accounts.default`؛ ويمكن لـ Matrix بدلًا من ذلك الحفاظ على هدف مسمّى/افتراضي مطابق موجود. +- تظل ارتباطات القناة فقط الحالية (من دون `accountId`) تطابق الحساب الافتراضي؛ وتبقى الارتباطات المحددة بنطاق الحساب اختيارية. +- يقوم `openclaw doctor --fix` أيضًا بإصلاح الأشكال المختلطة عبر نقل قيم الحساب الأحادي على المستوى الأعلى والمحددة بنطاق الحساب إلى الحساب المُرقّى المختار لتلك القناة. تستخدم معظم القنوات `accounts.default`؛ ويمكن لـ Matrix بدلًا من ذلك الحفاظ على هدف مسمّى/افتراضي مطابق موجود. -### قنوات extension أخرى +### قنوات extension الأخرى -تُضبط العديد من قنوات extension كـ `channels.` وتوثَّق في صفحات القنوات المخصصة لها (على سبيل المثال Feishu وMatrix وLINE وNostr وZalo وNextcloud Talk وSynology Chat وTwitch). +تُضبط العديد من قنوات extension على شكل `channels.` وتُوثق في صفحات القنوات المخصصة لها (على سبيل المثال Feishu وMatrix وLINE وNostr وZalo وNextcloud Talk وSynology Chat وTwitch). راجع فهرس القنوات الكامل: [القنوات](/ar/channels). -### تقييد الإشارة في الدردشات الجماعية +### اشتراط الإشارة في الدردشة الجماعية -تتطلب رسائل المجموعات افتراضياً **وجود إشارة** (إشارة ضمن البيانات الوصفية أو أنماط regex آمنة). ينطبق ذلك على دردشات المجموعات في WhatsApp وTelegram وDiscord وGoogle Chat وiMessage. +تستخدم الرسائل الجماعية افتراضيًا **require mention** (إشارة في بيانات التعريف أو أنماط regex آمنة). ينطبق ذلك على دردشات المجموعات في WhatsApp وTelegram وDiscord وGoogle Chat وiMessage. -**أنواع الإشارات:** +**أنواع الإشارة:** -- **إشارات البيانات الوصفية**: إشارات @-mention الأصلية للمنصة. يتم تجاهلها في وضع الدردشة الذاتية في WhatsApp. -- **أنماط النص**: أنماط regex آمنة في `agents.list[].groupChat.mentionPatterns`. يتم تجاهل الأنماط غير الصالحة والتكرار المتداخل غير الآمن. -- لا يُفرض تقييد الإشارة إلا عندما يكون الاكتشاف ممكناً (إشارات أصلية أو وجود نمط واحد على الأقل). +- **الإشارات في بيانات التعريف**: إشارات @-mention الأصلية للمنصة. تُتجاهل في وضع الدردشة الذاتية في WhatsApp. +- **أنماط النص**: أنماط regex آمنة في `agents.list[].groupChat.mentionPatterns`. تُتجاهل الأنماط غير الصالحة والتكرار المتداخل غير الآمن. +- لا يُفرض اشتراط الإشارة إلا عندما يكون الاكتشاف ممكنًا (إشارات أصلية أو نمط واحد على الأقل). ```json5 { @@ -788,7 +778,7 @@ exec ssh -T gateway-host imsg "$@" } ``` -يضبط `messages.groupChat.historyLimit` القيمة الافتراضية العامة. ويمكن للقنوات تجاوزها عبر `channels..historyLimit` ‏(أو لكل حساب). اضبط `0` للتعطيل. +يضبط `messages.groupChat.historyLimit` القيمة الافتراضية العامة. ويمكن للقنوات تجاوزها باستخدام `channels..historyLimit` (أو لكل حساب). عيّن القيمة `0` للتعطيل. #### حدود سجل الرسائل المباشرة @@ -805,13 +795,13 @@ exec ssh -T gateway-host imsg "$@" } ``` -آلية الحل: تجاوز لكل رسالة مباشرة → افتراضي الموفّر → بلا حد (الاحتفاظ بكل شيء). +آلية الحل: تجاوز لكل رسالة مباشرة → افتراضي المزوّد → بلا حد (يُحتفَظ بكل شيء). المدعوم: `telegram` و`whatsapp` و`discord` و`slack` و`signal` و`imessage` و`msteams`. #### وضع الدردشة الذاتية -ضمّن رقمك الخاص في `allowFrom` لتفعيل وضع الدردشة الذاتية (يتجاهل إشارات @-mention الأصلية، ويستجيب فقط لأنماط النص): +أدرج رقمك الخاص في `allowFrom` لتفعيل وضع الدردشة الذاتية (يتجاهل إشارات @ الأصلية، ويرد فقط على أنماط النص): ```json5 { @@ -837,16 +827,16 @@ exec ssh -T gateway-host imsg "$@" ```json5 { commands: { - native: "auto", // register native commands when supported - nativeSkills: "auto", // register native skill commands when supported - text: true, // parse /commands in chat messages - bash: false, // allow ! (alias: /bash) + native: "auto", // سجّل الأوامر الأصلية عندما تكون مدعومة + nativeSkills: "auto", // سجّل أوامر Skills الأصلية عندما تكون مدعومة + text: true, // حلّل /commands في رسائل الدردشة + bash: false, // السماح بـ ! (الاسم البديل: /bash) bashForegroundMs: 2000, - config: false, // allow /config - mcp: false, // allow /mcp - plugins: false, // allow /plugins - debug: false, // allow /debug - restart: true, // allow /restart + gateway restart tool + config: false, // السماح بـ /config + mcp: false, // السماح بـ /mcp + plugins: false, // السماح بـ /plugins + debug: false, // السماح بـ /debug + restart: true, // السماح بـ /restart + أداة إعادة تشغيل gateway ownerAllowFrom: ["discord:123456789012345678"], ownerDisplay: "raw", // raw | hash ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", @@ -861,38 +851,38 @@ exec ssh -T gateway-host imsg "$@" -- تضبط هذه الكتلة أسطح الأوامر. لفهرس الأوامر الحالي المدمج + المضمّن، راجع [أوامر الشرطة المائلة](/ar/tools/slash-commands). -- هذه الصفحة هي **مرجع لمفاتيح الإعدادات**، وليست فهرس الأوامر الكامل. الأوامر المملوكة للقنوات/Plugin مثل `/bot-ping` و`/bot-help` و`/bot-logs` في QQ Bot، و`/card` في LINE، و`/pair` في device-pair، و`/dreaming` في الذاكرة، و`/phone` في phone-control، و`/voice` في Talk موثقة في صفحات القنوات/Plugin الخاصة بها بالإضافة إلى [أوامر الشرطة المائلة](/ar/tools/slash-commands). -- يجب أن تكون الأوامر النصية رسائل **مستقلة** مع `/` في البداية. -- يقوم `native: "auto"` بتشغيل الأوامر الأصلية في Discord/Telegram، ويُبقي Slack معطلاً. -- يقوم `nativeSkills: "auto"` بتشغيل أوامر Skills الأصلية في Discord/Telegram، ويُبقي Slack معطلاً. -- التجاوز لكل قناة: `channels.discord.commands.native` ‏(قيمة منطقية أو `"auto"`). تؤدي القيمة `false` إلى مسح الأوامر المسجّلة مسبقاً. -- تجاوز تسجيل Skills الأصلية لكل قناة عبر `channels..commands.nativeSkills`. +- تهيّئ هذه الكتلة أسطح الأوامر. لفهرس الأوامر الحالي المضمن + المجمّع، راجع [Slash Commands](/ar/tools/slash-commands). +- هذه الصفحة هي **مرجع لمفاتيح الإعدادات**، وليست فهرس الأوامر الكامل. الأوامر المملوكة للقنوات/Plugin مثل QQ Bot ‏`/bot-ping` و`/bot-help` و`/bot-logs`، وLINE ‏`/card`، وdevice-pair ‏`/pair`، وmemory ‏`/dreaming`، وphone-control ‏`/phone`، وTalk ‏`/voice` موثقة في صفحات القنوات/Plugin الخاصة بها بالإضافة إلى [Slash Commands](/ar/tools/slash-commands). +- يجب أن تكون الأوامر النصية رسائل **مستقلة** تبدأ بـ `/`. +- يؤدي `native: "auto"` إلى تشغيل الأوامر الأصلية لـ Discord/Telegram، ويترك Slack معطّلًا. +- يؤدي `nativeSkills: "auto"` إلى تشغيل أوامر Skills الأصلية لـ Discord/Telegram، ويترك Slack معطّلًا. +- تجاوز لكل قناة: `channels.discord.commands.native` ‏(قيمة منطقية أو `"auto"`). تؤدي القيمة `false` إلى مسح الأوامر المسجلة سابقًا. +- تجاوز تسجيل Skills الأصلية لكل قناة باستخدام `channels..commands.nativeSkills`. - يضيف `channels.telegram.customCommands` إدخالات إضافية إلى قائمة بوت Telegram. -- يفعّل `bash: true` الأمر `! ` لصدفة المضيف. ويتطلب `tools.elevated.enabled` وأن يكون المرسل ضمن `tools.elevated.allowFrom.`. -- يفعّل `config: true` الأمر `/config` ‏(لقراءة/كتابة `openclaw.json`). وبالنسبة إلى عملاء Gateway ‏`chat.send`، تتطلب أيضاً عمليات الكتابة الدائمة عبر `/config set|unset` وجود `operator.admin`؛ بينما يبقى الأمر `config show/` للقراءة فقط متاحاً لعملاء المشغّل ذوي نطاق الكتابة العادي. -- يفعّل `mcp: true` الأمر `/mcp` لإعداد خوادم MCP التي يديرها OpenClaw ضمن `mcp.servers`. -- يفعّل `plugins: true` الأمر `/plugins` لاكتشاف Plugin وتثبيتها والتحكم في تمكينها/تعطيلها. -- تضبط `channels..configWrites` بوابة تعديلات الإعدادات لكل قناة (الافتراضي: true). -- بالنسبة إلى القنوات متعددة الحسابات، تضبط `channels..accounts..configWrites` أيضاً عمليات الكتابة التي تستهدف ذلك الحساب (على سبيل المثال `/allowlist --config --account ` أو `/config set channels..accounts....`). -- يؤدي `restart: false` إلى تعطيل `/restart` وإجراءات أداة إعادة تشغيل Gateway. الافتراضي: `true`. -- `ownerAllowFrom` هي قائمة السماح الصريحة للمالك لأوامر/أدوات المالك فقط. وهي منفصلة عن `allowFrom`. -- يقوم `ownerDisplay: "hash"` بتجزئة معرّفات المالك في system prompt. اضبط `ownerDisplaySecret` للتحكم في التجزئة. -- `allowFrom` خاص بكل موفّر. عند ضبطه، يكون هو **مصدر التفويض الوحيد** (ويتم تجاهل قوائم السماح/الاقتران الخاصة بالقنوات و`useAccessGroups`). -- يسمح `useAccessGroups: false` للأوامر بتجاوز سياسات مجموعات الوصول عندما لا يكون `allowFrom` مضبوطاً. +- يفعّل `bash: true` الأمر `! ` لصدفة المستضيف. ويتطلب `tools.elevated.enabled` وأن يكون المرسل ضمن `tools.elevated.allowFrom.`. +- يفعّل `config: true` الأمر `/config` (لقراءة/كتابة `openclaw.json`). وبالنسبة إلى عملاء `chat.send` في Gateway، تتطلب عمليات الكتابة الدائمة عبر `/config set|unset` أيضًا `operator.admin`؛ بينما يبقى `/config show` للقراءة فقط متاحًا لعملاء operator العاديين ذوي نطاق الكتابة. +- يفعّل `mcp: true` الأمر `/mcp` لإعداد خادم MCP الذي يديره OpenClaw تحت `mcp.servers`. +- يفعّل `plugins: true` الأمر `/plugins` لاكتشاف Plugin وتثبيتها وعناصر التحكم في التفعيل/التعطيل. +- يتحكم `channels..configWrites` في تعديلات الإعدادات لكل قناة (الافتراضي: true). +- بالنسبة إلى القنوات متعددة الحسابات، يتحكم `channels..accounts..configWrites` أيضًا في عمليات الكتابة التي تستهدف ذلك الحساب (على سبيل المثال `/allowlist --config --account ` أو `/config set channels..accounts....`). +- يؤدي `restart: false` إلى تعطيل `/restart` وإجراءات أداة إعادة تشغيل gateway. الافتراضي: `true`. +- `ownerAllowFrom` هي قائمة السماح الصريحة للمالك الخاصة بالأوامر/الأدوات المخصصة للمالك فقط. وهي منفصلة عن `allowFrom`. +- يؤدي `ownerDisplay: "hash"` إلى تجزئة معرّفات المالك في system prompt. اضبط `ownerDisplaySecret` للتحكم في التجزئة. +- `allowFrom` يكون لكل مزوّد. وعند تعيينه، يصبح **مصدر التفويض الوحيد** (ويتم تجاهل قوائم السماح/الاقتران الخاصة بالقناة و`useAccessGroups`). +- يتيح `useAccessGroups: false` للأوامر تجاوز سياسات مجموعات الوصول عندما لا يكون `allowFrom` معيّنًا. - خريطة وثائق الأوامر: - - الفهرس المدمج + المضمّن: [أوامر الشرطة المائلة](/ar/tools/slash-commands) - - أسطح الأوامر الخاصة بالقنوات: [القنوات](/ar/channels) - - أوامر QQ Bot: ‏[QQ Bot](/ar/channels/qqbot) - - أوامر الاقتران: [الاقتران](/ar/channels/pairing) - - أمر البطاقة في LINE: ‏[LINE](/ar/channels/line) + - الفهرس المضمن + المجمّع: [Slash Commands](/ar/tools/slash-commands) + - أسطح الأوامر الخاصة بكل قناة: [القنوات](/ar/channels) + - أوامر QQ Bot: [QQ Bot](/ar/channels/qqbot) + - أوامر الاقتران: [Pairing](/ar/channels/pairing) + - أمر البطاقة في LINE: [LINE](/ar/channels/line) - Dreaming للذاكرة: [Dreaming](/ar/concepts/dreaming) --- -## القيم الافتراضية للوكلاء +## الإعدادات الافتراضية للوكلاء ### `agents.defaults.workspace` @@ -906,7 +896,7 @@ exec ssh -T gateway-host imsg "$@" ### `agents.defaults.repoRoot` -جذر المستودع الاختياري المعروض في سطر Runtime ضمن system prompt. إذا لم يُضبط، يكتشفه OpenClaw تلقائياً عبر الصعود من مساحة العمل. +جذر المستودع الاختياري المعروض في سطر Runtime داخل system prompt. وإذا لم يُعيَّن، يكتشفه OpenClaw تلقائيًا عبر الصعود من مساحة العمل. ```json5 { @@ -916,7 +906,7 @@ exec ssh -T gateway-host imsg "$@" ### `agents.defaults.skills` -قائمة السماح الافتراضية الاختيارية لـ Skills للوكلاء الذين لا يضبطون +قائمة السماح الافتراضية الاختيارية لـ Skills للوكلاء الذين لا يعيّنون `agents.list[].skills`. ```json5 @@ -932,11 +922,11 @@ exec ssh -T gateway-host imsg "$@" } ``` -- احذف `agents.defaults.skills` للحصول على Skills غير مقيّدة افتراضياً. +- احذف `agents.defaults.skills` للحصول على Skills غير مقيّدة افتراضيًا. - احذف `agents.list[].skills` لوراثة القيم الافتراضية. -- اضبط `agents.list[].skills: []` لعدم استخدام أي Skills. -- تمثل القائمة غير الفارغة في `agents.list[].skills` المجموعة النهائية لذلك الوكيل؛ - ولا تُدمج مع القيم الافتراضية. +- عيّن `agents.list[].skills: []` لعدم استخدام أي Skills. +- تمثل قائمة `agents.list[].skills` غير الفارغة المجموعة النهائية لذلك الوكيل؛ + وهي لا تندمج مع القيم الافتراضية. ### `agents.defaults.skipBootstrap` @@ -950,9 +940,9 @@ exec ssh -T gateway-host imsg "$@" ### `agents.defaults.contextInjection` -يتحكم في وقت حقن ملفات bootstrap الخاصة بمساحة العمل في system prompt. الافتراضي: `"always"`. +يتحكم في وقت حقن ملفات bootstrap الخاصة بمساحة العمل داخل system prompt. الافتراضي: `"always"`. -- `"continuation-skip"`: تتخطى أدوار المتابعة الآمنة (بعد اكتمال رد من المساعد) إعادة حقن bootstrap الخاص بمساحة العمل، مما يقلل حجم prompt. تظل عمليات Heartbeat وعمليات إعادة المحاولة بعد Compaction تعيد بناء السياق. +- `"continuation-skip"`: تتجاوز أدوار المتابعة الآمنة (بعد اكتمال استجابة المساعد) إعادة حقن bootstrap الخاص بمساحة العمل، مما يقلل حجم prompt. وتستمر تشغيلات Heartbeat وإعادات المحاولة بعد Compaction في إعادة بناء السياق. ```json5 { @@ -962,21 +952,21 @@ exec ssh -T gateway-host imsg "$@" ### `agents.defaults.bootstrapMaxChars` -الحد الأقصى لعدد الأحرف لكل ملف bootstrap في مساحة العمل قبل الاقتطاع. الافتراضي: `20000`. +الحد الأقصى لعدد الأحرف لكل ملف bootstrap في مساحة العمل قبل الاقتطاع. الافتراضي: `12000`. ```json5 { - agents: { defaults: { bootstrapMaxChars: 20000 } }, + agents: { defaults: { bootstrapMaxChars: 12000 } }, } ``` ### `agents.defaults.bootstrapTotalMaxChars` -الحد الأقصى لإجمالي الأحرف المحقونة عبر جميع ملفات bootstrap في مساحة العمل. الافتراضي: `150000`. +الحد الأقصى لإجمالي الأحرف المحقونة عبر جميع ملفات bootstrap الخاصة بمساحة العمل. الافتراضي: `60000`. ```json5 { - agents: { defaults: { bootstrapTotalMaxChars: 150000 } }, + agents: { defaults: { bootstrapTotalMaxChars: 60000 } }, } ``` @@ -985,9 +975,9 @@ exec ssh -T gateway-host imsg "$@" يتحكم في نص التحذير المرئي للوكيل عند اقتطاع سياق bootstrap. الافتراضي: `"once"`. -- `"off"`: عدم حقن نص التحذير في system prompt مطلقاً. -- `"once"`: حقن التحذير مرة واحدة لكل توقيع اقتطاع فريد (مستحسن). -- `"always"`: حقن التحذير في كل تشغيل عند وجود اقتطاع. +- `"off"`: لا تحقن نص التحذير مطلقًا في system prompt. +- `"once"`: احقن التحذير مرة واحدة لكل توقيع اقتطاع فريد (موصى به). +- `"always"`: احقن التحذير في كل تشغيل عندما يوجد اقتطاع. ```json5 { @@ -998,21 +988,21 @@ exec ssh -T gateway-host imsg "$@" ### خريطة ملكية ميزانية السياق يحتوي OpenClaw على عدة ميزانيات كبيرة الحجم لـ prompt/السياق، وهي -مقسّمة عمداً حسب النظام الفرعي بدلاً من تمريرها جميعاً عبر إعداد -عام واحد. +مقسمة عمدًا حسب النظام الفرعي بدلًا من مرورها كلها عبر +مفتاح ضبط عام واحد. - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`: حقن bootstrap العادي لمساحة العمل. - `agents.defaults.startupContext.*`: - التمهيد الأولي لمرة واحدة في `/new` و`/reset`، بما في ذلك ملفات - `memory/*.md` اليومية الحديثة. + تمهيد بدء التشغيل لمرة واحدة لأوامر `/new` و`/reset`، + بما في ذلك ملفات `memory/*.md` اليومية الحديثة. - `skills.limits.*`: - قائمة Skills المضغوطة المحقونة في system prompt. + قائمة Skills المدمجة المحقونة في system prompt. - `agents.defaults.contextLimits.*`: - مقتطفات وقت التشغيل المحدودة والكتل المملوكة لوقت التشغيل المحقونة. + مقتطفات التشغيل المحدودة والكتل المملوكة لوقت التشغيل والمحقونة. - `memory.qmd.limits.*`: - حجم مقتطفات البحث المفهرس في الذاكرة والحقن. + مقتطفات البحث في الذاكرة المفهرسة وتحجيم الحقن. استخدم التجاوز المطابق لكل وكيل فقط عندما يحتاج وكيل واحد إلى ميزانية مختلفة: @@ -1022,7 +1012,7 @@ exec ssh -T gateway-host imsg "$@" #### `agents.defaults.startupContext` -يتحكم في التمهيد الأولي عند أول دور، والمحقون في تشغيلات `/new` و`/reset` +يتحكم في تمهيد بدء التشغيل لأول دور، والذي يُحقن في تشغيلات `/new` و`/reset` العادية. ```json5 @@ -1044,7 +1034,7 @@ exec ssh -T gateway-host imsg "$@" #### `agents.defaults.contextLimits` -القيم الافتراضية المشتركة لأسطح سياق وقت التشغيل المحدودة. +إعدادات افتراضية مشتركة لأسطح سياق التشغيل المحدودة. ```json5 { @@ -1062,17 +1052,16 @@ exec ssh -T gateway-host imsg "$@" ``` - `memoryGetMaxChars`: الحد الافتراضي لمقتطف `memory_get` قبل إضافة - بيانات وصفية للاقتطاع وإشعار المتابعة. -- `memoryGetDefaultLines`: نافذة الأسطر الافتراضية لـ `memory_get` عند - حذف `lines`. -- `toolResultMaxChars`: الحد المستخدم لنتائج الأدوات الحية للنتائج - المحفوظة واستعادة الفائض. -- `postCompactionMaxChars`: حد مقتطف `AGENTS.md` المستخدم أثناء حقن - التحديث بعد Compaction. + بيانات وصفية للاقتطاع وإشعار بالمتابعة. +- `memoryGetDefaultLines`: نافذة الأسطر الافتراضية لـ `memory_get` عند حذف `lines`. +- `toolResultMaxChars`: الحد الأقصى لنتائج الأدوات أثناء التشغيل والمستخدم للنتائج + المحفوظة ومعالجة الفائض. +- `postCompactionMaxChars`: الحد الأقصى لمقتطفات AGENTS.md المستخدمة أثناء + حقن التحديث بعد Compaction. #### `agents.list[].contextLimits` -تجاوز لكل وكيل لإعدادات `contextLimits` المشتركة. ترث الحقول المحذوفة +تجاوز لكل وكيل لمفاتيح `contextLimits` المشتركة. وترث الحقول المحذوفة من `agents.defaults.contextLimits`. ```json5 @@ -1099,8 +1088,8 @@ exec ssh -T gateway-host imsg "$@" #### `skills.limits.maxSkillsPromptChars` -الحد العام لقائمة Skills المضغوطة المحقونة في system prompt. لا -يؤثر هذا في قراءة ملفات `SKILL.md` عند الطلب. +الحد الأقصى العام لقائمة Skills المدمجة المحقونة في system prompt. هذا +لا يؤثر في قراءة ملفات `SKILL.md` عند الطلب. ```json5 { @@ -1133,11 +1122,11 @@ exec ssh -T gateway-host imsg "$@" ### `agents.defaults.imageMaxDimensionPx` -أقصى حجم بالبكسل لأطول ضلع في الصورة ضمن كتل الصور في السجل/الأدوات قبل استدعاءات الموفّر. +الحد الأقصى لحجم البكسل لأطول ضلع في الصورة ضمن كتل صور السجل/الأدوات قبل استدعاءات المزوّد. الافتراضي: `1200`. -تؤدي القيم الأقل عادةً إلى تقليل استخدام vision-token وحجم حمولة الطلب في التشغيلات التي تكثر فيها لقطات الشاشة. -وتحافظ القيم الأعلى على قدر أكبر من التفاصيل البصرية. +تقلل القيم المنخفضة عادةً من استخدام رموز الرؤية وحجم حمولة الطلب في التشغيلات التي تحتوي على الكثير من لقطات الشاشة. +وتحافظ القيم الأعلى على قدر أكبر من التفاصيل المرئية. ```json5 { @@ -1147,7 +1136,7 @@ exec ssh -T gateway-host imsg "$@" ### `agents.defaults.userTimezone` -المنطقة الزمنية لسياق system prompt ‏(وليست للطوابع الزمنية للرسائل). وتعود إلى المنطقة الزمنية للمضيف عند عدم ضبطها. +المنطقة الزمنية لسياق system prompt (وليس الطوابع الزمنية للرسائل). وتعود إلى المنطقة الزمنية الخاصة بالمستضيف عند عدم التعيين. ```json5 { @@ -1157,7 +1146,7 @@ exec ssh -T gateway-host imsg "$@" ### `agents.defaults.timeFormat` -تنسيق الوقت في system prompt. الافتراضي: `auto` ‏(تفضيل نظام التشغيل). +تنسيق الوقت في system prompt. الافتراضي: `auto` (تفضيل نظام التشغيل). ```json5 { @@ -1195,7 +1184,7 @@ exec ssh -T gateway-host imsg "$@" primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // global default provider params + params: { cacheRetention: "long" }, // معاملات المزوّد الافتراضية العامة embeddedHarness: { runtime: "auto", // auto | pi | registered harness id, e.g. codex fallback: "pi", // pi | none @@ -1214,49 +1203,49 @@ exec ssh -T gateway-host imsg "$@" } ``` -- `model`: يقبل إما سلسلة (`"provider/model"`) أو كائناً (`{ primary, fallbacks }`). +- `model`: يقبل إما سلسلة (`"provider/model"`) أو كائنًا (`{ primary, fallbacks }`). - يضبط نموذج السلسلة النموذج الأساسي فقط. - يضبط نموذج الكائن النموذج الأساسي بالإضافة إلى نماذج التحويل الاحتياطي المرتبة. -- `imageModel`: يقبل إما سلسلة (`"provider/model"`) أو كائناً (`{ primary, fallbacks }`). - - يُستخدم بواسطة مسار أداة `image` بوصفه إعداد نموذج الرؤية. - - ويُستخدم أيضاً كتوجيه احتياطي عندما لا يستطيع النموذج المحدد/الافتراضي قبول إدخال الصور. -- `imageGenerationModel`: يقبل إما سلسلة (`"provider/model"`) أو كائناً (`{ primary, fallbacks }`). - - يُستخدم بواسطة إمكانية توليد الصور المشتركة وأي سطح أداة/Plugin مستقبلي يولّد الصور. - - القيم النموذجية: `google/gemini-3.1-flash-image-preview` لتوليد الصور الأصلي في Gemini، أو `fal/fal-ai/flux/dev` لـ fal، أو `openai/gpt-image-1` لـ OpenAI Images. - - إذا حددت موفّراً/نموذجاً مباشرة، فاضبط أيضاً المصادقة/مفتاح API المطابق للموفّر (على سبيل المثال `GEMINI_API_KEY` أو `GOOGLE_API_KEY` لـ `google/*`، و`OPENAI_API_KEY` لـ `openai/*`، و`FAL_KEY` لـ `fal/*`). - - إذا حُذف، فلا يزال `image_generate` قادراً على استنتاج موفّر افتراضي مدعوم بالمصادقة. حيث يجرّب أولاً الموفّر الافتراضي الحالي، ثم بقية موفّري توليد الصور المسجلين بترتيب معرّف الموفّر. -- `musicGenerationModel`: يقبل إما سلسلة (`"provider/model"`) أو كائناً (`{ primary, fallbacks }`). - - يُستخدم بواسطة إمكانية توليد الموسيقى المشتركة وأداة `music_generate` المدمجة. +- `imageModel`: يقبل إما سلسلة (`"provider/model"`) أو كائنًا (`{ primary, fallbacks }`). + - يُستخدم في مسار أداة `image` كإعداد لنموذج الرؤية الخاص بها. + - ويُستخدم أيضًا كتوجيه احتياطي عندما لا يستطيع النموذج المحدد/الافتراضي قبول مدخلات الصور. +- `imageGenerationModel`: يقبل إما سلسلة (`"provider/model"`) أو كائنًا (`{ primary, fallbacks }`). + - يُستخدم في إمكانية توليد الصور المشتركة وأي سطح أداة/Plugin مستقبلي يولد صورًا. + - القيم النموذجية: `google/gemini-3.1-flash-image-preview` لتوليد صور Gemini الأصلي، أو `fal/fal-ai/flux/dev` لـ fal، أو `openai/gpt-image-1` لـ OpenAI Images. + - إذا اخترت مزودًا/نموذجًا مباشرةً، فاضبط أيضًا مصادقة المزوّد/مفتاح API المطابق (على سبيل المثال `GEMINI_API_KEY` أو `GOOGLE_API_KEY` لـ `google/*`، و`OPENAI_API_KEY` لـ `openai/*`، و`FAL_KEY` لـ `fal/*`). + - إذا لم يُعيَّن، يمكن لـ `image_generate` مع ذلك استنتاج افتراضي مزوّد مدعوم بالمصادقة. إذ يحاول أولًا المزوّد الافتراضي الحالي، ثم بقية مزوّدي توليد الصور المسجلين حسب ترتيب معرّف المزوّد. +- `musicGenerationModel`: يقبل إما سلسلة (`"provider/model"`) أو كائنًا (`{ primary, fallbacks }`). + - يُستخدم في إمكانية توليد الموسيقى المشتركة وفي الأداة المضمنة `music_generate`. - القيم النموذجية: `google/lyria-3-clip-preview` أو `google/lyria-3-pro-preview` أو `minimax/music-2.5+`. - - إذا حُذف، فلا يزال `music_generate` قادراً على استنتاج موفّر افتراضي مدعوم بالمصادقة. حيث يجرّب أولاً الموفّر الافتراضي الحالي، ثم بقية موفّري توليد الموسيقى المسجلين بترتيب معرّف الموفّر. - - إذا حددت موفّراً/نموذجاً مباشرة، فاضبط أيضاً المصادقة/مفتاح API المطابق للموفّر. -- `videoGenerationModel`: يقبل إما سلسلة (`"provider/model"`) أو كائناً (`{ primary, fallbacks }`). - - يُستخدم بواسطة إمكانية توليد الفيديو المشتركة وأداة `video_generate` المدمجة. + - إذا لم يُعيَّن، يمكن لـ `music_generate` مع ذلك استنتاج افتراضي مزوّد مدعوم بالمصادقة. إذ يحاول أولًا المزوّد الافتراضي الحالي، ثم بقية مزوّدي توليد الموسيقى المسجلين حسب ترتيب معرّف المزوّد. + - إذا اخترت مزودًا/نموذجًا مباشرةً، فاضبط أيضًا مصادقة المزوّد/مفتاح API المطابق. +- `videoGenerationModel`: يقبل إما سلسلة (`"provider/model"`) أو كائنًا (`{ primary, fallbacks }`). + - يُستخدم في إمكانية توليد الفيديو المشتركة وفي الأداة المضمنة `video_generate`. - القيم النموذجية: `qwen/wan2.6-t2v` أو `qwen/wan2.6-i2v` أو `qwen/wan2.6-r2v` أو `qwen/wan2.6-r2v-flash` أو `qwen/wan2.7-r2v`. - - إذا حُذف، فلا يزال `video_generate` قادراً على استنتاج موفّر افتراضي مدعوم بالمصادقة. حيث يجرّب أولاً الموفّر الافتراضي الحالي، ثم بقية موفّري توليد الفيديو المسجلين بترتيب معرّف الموفّر. - - إذا حددت موفّراً/نموذجاً مباشرة، فاضبط أيضاً المصادقة/مفتاح API المطابق للموفّر. - - يدعم موفّر توليد الفيديو المضمّن Qwen حتى فيديو خرج واحد، وصورة دخل واحدة، و4 مقاطع فيديو دخل، ومدة 10 ثوانٍ، وخيارات على مستوى الموفّر لـ `size` و`aspectRatio` و`resolution` و`audio` و`watermark`. -- `pdfModel`: يقبل إما سلسلة (`"provider/model"`) أو كائناً (`{ primary, fallbacks }`). + - إذا لم يُعيَّن، يمكن لـ `video_generate` مع ذلك استنتاج افتراضي مزوّد مدعوم بالمصادقة. إذ يحاول أولًا المزوّد الافتراضي الحالي، ثم بقية مزوّدي توليد الفيديو المسجلين حسب ترتيب معرّف المزوّد. + - إذا اخترت مزودًا/نموذجًا مباشرةً، فاضبط أيضًا مصادقة المزوّد/مفتاح API المطابق. + - يدعم مزود توليد الفيديو المضمّن Qwen ما يصل إلى فيديو مخرج واحد، وصورة إدخال واحدة، و4 فيديوهات إدخال، ومدة 10 ثوانٍ، وخيارات على مستوى المزوّد مثل `size` و`aspectRatio` و`resolution` و`audio` و`watermark`. +- `pdfModel`: يقبل إما سلسلة (`"provider/model"`) أو كائنًا (`{ primary, fallbacks }`). - يُستخدم بواسطة أداة `pdf` لتوجيه النموذج. - - إذا حُذف، تعود أداة PDF إلى `imageModel`، ثم إلى نموذج الجلسة/النموذج الافتراضي الذي تم حله. -- `pdfMaxBytesMb`: حد حجم PDF الافتراضي لأداة `pdf` عندما لا يتم تمرير `maxBytesMb` وقت الاستدعاء. -- `pdfMaxPages`: الحد الأقصى الافتراضي للصفحات التي يأخذها وضع الاستخراج الاحتياطي بعين الاعتبار في أداة `pdf`. + - إذا لم يُعيَّن، تعود أداة PDF إلى `imageModel`، ثم إلى النموذج المحلول للجلسة/الافتراضي. +- `pdfMaxBytesMb`: حد حجم PDF الافتراضي لأداة `pdf` عندما لا يُمرَّر `maxBytesMb` وقت الاستدعاء. +- `pdfMaxPages`: الحد الأقصى الافتراضي للصفحات التي ينظر فيها وضع الاستخراج الاحتياطي في أداة `pdf`. - `verboseDefault`: مستوى verbose الافتراضي للوكلاء. القيم: `"off"` و`"on"` و`"full"`. الافتراضي: `"off"`. - `elevatedDefault`: مستوى المخرجات المرتفعة الافتراضي للوكلاء. القيم: `"off"` و`"on"` و`"ask"` و`"full"`. الافتراضي: `"on"`. -- `model.primary`: بالتنسيق `provider/model` ‏(مثل `openai/gpt-5.4`). إذا حذفت الموفّر، يحاول OpenClaw أولاً اسماً مستعاراً، ثم مطابقة فريدة لموفّر مضبوط لذلك المعرّف الدقيق للنموذج، وبعدها فقط يعود إلى الموفّر الافتراضي المضبوط (سلوك توافق قديم، لذا يُفضَّل `provider/model` الصريح). إذا لم يعد ذلك الموفّر يوفّر النموذج الافتراضي المضبوط، يعود OpenClaw إلى أول موفّر/نموذج مضبوط بدلاً من إظهار افتراضي قديم لموفّر تمت إزالته. -- `models`: فهرس النماذج المضبوطة وقائمة السماح الخاصة بـ `/model`. يمكن أن يتضمن كل إدخال `alias` ‏(اختصار) و`params` ‏(خاصة بالموفّر، مثل `temperature` و`maxTokens` و`cacheRetention` و`context1m`). -- `params`: معلمات الموفّر الافتراضية العامة المطبقة على جميع النماذج. تُضبط عند `agents.defaults.params` ‏(مثل `{ cacheRetention: "long" }`). -- أسبقية دمج `params` ‏(في الإعدادات): يتم تجاوز `agents.defaults.params` ‏(الأساس العام) بواسطة `agents.defaults.models["provider/model"].params` ‏(لكل نموذج)، ثم تتجاوزها `agents.list[].params` ‏(لدى معرّف الوكيل المطابق) حسب المفتاح. راجع [Prompt Caching](/ar/reference/prompt-caching) للتفاصيل. -- `embeddedHarness`: سياسة وقت التشغيل الافتراضية منخفضة المستوى للوكلاء المضمّنين. استخدم `runtime: "auto"` للسماح لـ harnesses المسجلة من Plugin بالمطالبة بالنماذج المدعومة، أو `runtime: "pi"` لفرض harness ‏PI المدمج، أو معرّف harness مسجّل مثل `runtime: "codex"`. اضبط `fallback: "none"` لتعطيل الرجوع التلقائي إلى PI. -- تحفظ أدوات كتابة الإعدادات التي تعدّل هذه الحقول (على سبيل المثال `/models set` و`/models set-image` وأوامر إضافة/إزالة الاحتياطي) نموذج الكائن القياسي وتحافظ على قوائم الاحتياطي الحالية متى أمكن. -- `maxConcurrent`: الحد الأقصى لتشغيلات الوكلاء المتوازية عبر الجلسات (مع بقاء كل جلسة متسلسلة). الافتراضي: 4. +- `model.primary`: التنسيق `provider/model` (مثل `openai/gpt-5.4`). إذا حذفت المزوّد، يحاول OpenClaw أولًا اسمًا مستعارًا، ثم تطابقًا فريدًا لمزوّد مهيأ لذلك المعرّف الدقيق للنموذج، وبعدها فقط يعود إلى المزوّد الافتراضي المهيأ (سلوك توافق قديم ومهجور، لذا يُفضّل استخدام `provider/model` الصريح). وإذا لم يعد ذلك المزوّد يوفّر النموذج الافتراضي المهيأ، يعود OpenClaw إلى أول مزوّد/نموذج مهيأ بدلًا من إظهار افتراضي قديم لمزوّد تمت إزالته. +- `models`: فهرس النماذج المهيأ وقائمة السماح الخاصة بـ `/model`. يمكن أن يتضمن كل إدخال `alias` (اختصارًا) و`params` (خاصة بالمزوّد، مثل `temperature` و`maxTokens` و`cacheRetention` و`context1m`). +- `params`: معاملات المزوّد الافتراضية العامة المطبقة على جميع النماذج. تُضبط في `agents.defaults.params` (مثل `{ cacheRetention: "long" }`). +- أولوية دمج `params` (في الإعدادات): يتم تجاوز `agents.defaults.params` (الأساس العام) بواسطة `agents.defaults.models["provider/model"].params` (لكل نموذج)، ثم يتجاوز `agents.list[].params` (لمعرّف الوكيل المطابق) بالمفتاح. راجع [Prompt Caching](/ar/reference/prompt-caching) للتفاصيل. +- `embeddedHarness`: سياسة وقت التشغيل المضمن منخفضة المستوى الافتراضية للوكيل. استخدم `runtime: "auto"` للسماح لـ harnesses الخاصة بـ Plugin المسجلة بادعاء النماذج المدعومة، أو `runtime: "pi"` لفرض harness المضمن PI، أو معرّف harness مسجل مثل `runtime: "codex"`. عيّن `fallback: "none"` لتعطيل الرجوع التلقائي إلى PI. +- تقوم كاتبات الإعدادات التي تعدّل هذه الحقول (مثل `/models set` و`/models set-image` وأوامر إضافة/إزالة الاحتياطي) بحفظ صيغة الكائن القانونية مع الحفاظ على قوائم fallback الموجودة متى أمكن. +- `maxConcurrent`: الحد الأقصى لتشغيلات الوكلاء المتوازية عبر الجلسات (مع بقاء كل جلسة متسلسلة داخليًا). الافتراضي: 4. ### `agents.defaults.embeddedHarness` -يتحكم `embeddedHarness` في أي منفّذ منخفض المستوى يشغّل أدوار الوكيل المضمّن. -يجب أن تحتفظ معظم البيئات بالقيمة الافتراضية `{ runtime: "auto", fallback: "pi" }`. -استخدمه عندما يوفّر Plugin موثوق harness أصلياً، مثل harness -خادم تطبيق Codex المضمّن. +يتحكم `embeddedHarness` في المنفّذ منخفض المستوى الذي يشغّل أدوار الوكيل المضمنة. +ينبغي لمعظم عمليات النشر الإبقاء على الإعداد الافتراضي `{ runtime: "auto", fallback: "pi" }`. +استخدمه عندما يوفّر Plugin موثوق harness أصليًا، مثل +harness خادم التطبيق Codex المضمّن. ```json5 { @@ -1272,15 +1261,15 @@ exec ssh -T gateway-host imsg "$@" } ``` -- `runtime`: ‏`"auto"` أو `"pi"` أو معرّف harness مسجّل من Plugin. يسجّل Plugin ‏Codex المضمّن `codex`. -- `fallback`: ‏`"pi"` أو `"none"`. تُبقي `"pi"` harness ‏PI المدمج كخيار احتياطي للتوافق. وتجعل `"none"` اختيار harness المفقود أو غير المدعوم يفشل بدلاً من استخدام PI بصمت. -- تجاوزات البيئة: يقوم `OPENCLAW_AGENT_RUNTIME=` بتجاوز `runtime`؛ ويعطّل `OPENCLAW_AGENT_HARNESS_FALLBACK=none` الرجوع إلى PI لتلك العملية. -- لبيئات Codex فقط، اضبط `model: "codex/gpt-5.4"` و`embeddedHarness.runtime: "codex"` و`embeddedHarness.fallback: "none"`. -- يتحكم هذا فقط في harness الدردشة المضمّنة. بينما تظل توليد الوسائط والرؤية وPDF والموسيقى والفيديو وTTS تستخدم إعدادات الموفّر/النموذج الخاصة بها. +- `runtime`: القيم `"auto"` أو `"pi"` أو معرّف harness مسجل لأحد Plugin. يسجل Plugin Codex المضمّن المعرف `codex`. +- `fallback`: القيم `"pi"` أو `"none"`. تبقي `"pi"` harness PI المضمن كاحتياطي توافق. وتؤدي `"none"` إلى فشل اختيار harness الخاص بـ Plugin عندما يكون مفقودًا أو غير مدعوم بدلًا من استخدام PI بصمت. +- تجاوزات البيئة: يتجاوز `OPENCLAW_AGENT_RUNTIME=` القيمة `runtime`؛ ويعطّل `OPENCLAW_AGENT_HARNESS_FALLBACK=none` الرجوع إلى PI لتلك العملية. +- لعمليات النشر الخاصة بـ Codex فقط، اضبط `model: "codex/gpt-5.4"` و`embeddedHarness.runtime: "codex"` و`embeddedHarness.fallback: "none"`. +- يتحكم هذا فقط في harness الدردشة المضمن. أما توليد الوسائط والرؤية وPDF والموسيقى والفيديو وTTS فما زالت تستخدم إعدادات المزوّد/النموذج الخاصة بها. -**اختصارات alias المدمجة** (تنطبق فقط عندما يكون النموذج موجوداً في `agents.defaults.models`): +**الاختصارات المستعارة المضمنة** (تنطبق فقط عندما يكون النموذج موجودًا في `agents.defaults.models`): -| Alias | النموذج | +| الاسم المستعار | النموذج | | ------------------- | -------------------------------------- | | `opus` | `anthropic/claude-opus-4-6` | | `sonnet` | `anthropic/claude-sonnet-4-6` | @@ -1291,15 +1280,15 @@ exec ssh -T gateway-host imsg "$@" | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -تتغلب الأسماء المستعارة التي تضبطها دائماً على القيم الافتراضية. +تفوز الأسماء المستعارة التي تضبطها أنت دائمًا على القيم الافتراضية. -تفعّل نماذج Z.AI GLM-4.x وضع التفكير تلقائياً ما لم تضبط `--thinking off` أو تعرّف `agents.defaults.models["zai/"].params.thinking` بنفسك. -وتفعّل نماذج Z.AI القيمة `tool_stream` افتراضياً لبث استدعاءات الأدوات. اضبط `agents.defaults.models["zai/"].params.tool_stream` على `false` لتعطيله. -وتستخدم نماذج Anthropic Claude 4.6 التفكير `adaptive` افتراضياً عندما لا يكون هناك مستوى تفكير صريح مضبوط. +تفعّل نماذج Z.AI GLM-4.x وضع التفكير تلقائيًا ما لم تعيّن `--thinking off` أو تعرّف `agents.defaults.models["zai/"].params.thinking` بنفسك. +وتفعّل نماذج Z.AI القيمة `tool_stream` افتراضيًا لبث استدعاءات الأدوات. عيّن `agents.defaults.models["zai/"].params.tool_stream` إلى `false` لتعطيلها. +وتستخدم نماذج Anthropic Claude 4.6 افتراضيًا التفكير `adaptive` عندما لا يكون هناك مستوى تفكير صريح محدد. ### `agents.defaults.cliBackends` -واجهات CLI اختيارية للتشغيلات الاحتياطية النصية فقط (من دون استدعاءات أدوات). مفيدة كخيار احتياطي عند فشل موفّري API. +واجهات CLI خلفية اختيارية لتشغيلات الاحتياط النصية فقط (من دون استدعاءات أدوات). وهي مفيدة كنسخة احتياطية عند تعطل مزوّدي API. ```json5 { @@ -1327,13 +1316,13 @@ exec ssh -T gateway-host imsg "$@" } ``` -- واجهات CLI الخلفية موجّهة للنص أولاً؛ وتكون الأدوات معطلة دائماً. -- تكون الجلسات مدعومة عند ضبط `sessionArg`. -- تمرير الصور مدعوم عندما يقبل `imageArg` مسارات الملفات. +- الواجهات الخلفية CLI موجهة للنص أولًا؛ وتكون الأدوات معطلة دائمًا. +- تُدعَم الجلسات عندما يكون `sessionArg` معيّنًا. +- يُدعَم تمرير الصور عندما يقبل `imageArg` مسارات الملفات. ### `agents.defaults.systemPromptOverride` -استبدل system prompt الكامل الذي يجمعه OpenClaw بسلسلة ثابتة. يُضبط على المستوى الافتراضي (`agents.defaults.systemPromptOverride`) أو لكل وكيل (`agents.list[].systemPromptOverride`). تكون القيم لكل وكيل ذات أولوية؛ ويتم تجاهل القيمة الفارغة أو التي تحتوي على مسافات فقط. وهو مفيد لتجارب prompt المضبوطة. +استبدل system prompt الكامل الذي يجمعه OpenClaw بسلسلة ثابتة. يُضبط على المستوى الافتراضي (`agents.defaults.systemPromptOverride`) أو لكل وكيل (`agents.list[].systemPromptOverride`). وتأخذ القيم لكل وكيل الأولوية؛ وتُتجاهل القيم الفارغة أو التي تحتوي على مسافات بيضاء فقط. وهذا مفيد لتجارب prompt المنضبطة. ```json5 { @@ -1354,16 +1343,16 @@ exec ssh -T gateway-host imsg "$@" agents: { defaults: { heartbeat: { - every: "30m", // 0m disables + every: "30m", // 0m للتعطيل model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt - lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files - isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history) + includeSystemPromptSection: true, // الافتراضي: true؛ false يحذف قسم Heartbeat من system prompt + lightContext: false, // الافتراضي: false؛ true يُبقي فقط HEARTBEAT.md من ملفات bootstrap الخاصة بمساحة العمل + isolatedSession: false, // الافتراضي: false؛ true يشغّل كل Heartbeat في جلسة جديدة (بلا سجل محادثة) session: "main", to: "+15555550123", - directPolicy: "allow", // allow (default) | block - target: "none", // default: none | options: last | whatsapp | telegram | discord | ... + directPolicy: "allow", // allow (الافتراضي) | block + target: "none", // الافتراضي: none | الخيارات: last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, @@ -1374,15 +1363,15 @@ exec ssh -T gateway-host imsg "$@" } ``` -- `every`: سلسلة مدة (`ms/s/m/h`). الافتراضي: `30m` ‏(مصادقة مفتاح API) أو `1h` ‏(مصادقة OAuth). اضبطها على `0m` للتعطيل. -- `includeSystemPromptSection`: عند ضبطه على false، يحذف قسم Heartbeat من system prompt ويتخطى حقن `HEARTBEAT.md` في سياق bootstrap. الافتراضي: `true`. -- `suppressToolErrorWarnings`: عند ضبطه على true، يمنع حمولات تحذير أخطاء الأدوات أثناء تشغيلات Heartbeat. -- `timeoutSeconds`: الحد الأقصى للوقت بالثواني المسموح به لدور وكيل Heartbeat قبل إيقافه. اتركه غير مضبوط لاستخدام `agents.defaults.timeoutSeconds`. -- `directPolicy`: سياسة التسليم المباشر/الرسائل المباشرة. تسمح `allow` ‏(الافتراضي) بالتسليم المباشر المستهدف. بينما تمنع `block` التسليم المباشر المستهدف وتنتج `reason=dm-blocked`. -- `lightContext`: عند ضبطه على true، تستخدم تشغيلات Heartbeat سياق bootstrap خفيفاً وتحتفظ فقط بـ `HEARTBEAT.md` من ملفات bootstrap الخاصة بمساحة العمل. -- `isolatedSession`: عند ضبطه على true، يعمل كل Heartbeat في جلسة جديدة من دون أي سجل محادثة سابق. وهو نفس نمط العزل في Cron ‏`sessionTarget: "isolated"`. يقلل كلفة الرموز لكل Heartbeat من نحو 100 ألف إلى 2-5 آلاف رمز. -- لكل وكيل: اضبط `agents.list[].heartbeat`. عندما يعرّف أي وكيل `heartbeat`، **يشغَّل Heartbeat لهؤلاء الوكلاء فقط**. -- تشغّل Heartbeat أدوار وكلاء كاملة — لذا تؤدي الفواصل الأقصر إلى استهلاك مزيد من الرموز. +- `every`: سلسلة مدة (ms/s/m/h). الافتراضي: `30m` (مصادقة مفتاح API) أو `1h` (مصادقة OAuth). عيّنها إلى `0m` للتعطيل. +- `includeSystemPromptSection`: عند تعيينها إلى false، تُحذف فقرة Heartbeat من system prompt ويُتخطى حقن `HEARTBEAT.md` في سياق bootstrap. الافتراضي: `true`. +- `suppressToolErrorWarnings`: عند تعيينه إلى true، ي suppress حمولة تحذيرات أخطاء الأدوات أثناء تشغيلات Heartbeat. +- `timeoutSeconds`: الحد الأقصى بالثواني المسموح به لدور وكيل Heartbeat قبل إيقافه. اتركه غير معيّن لاستخدام `agents.defaults.timeoutSeconds`. +- `directPolicy`: سياسة التسليم المباشر/للرسائل المباشرة. تسمح `allow` (الافتراضي) بالتسليم المباشر إلى الهدف. وتؤدي `block` إلى منع التسليم المباشر إلى الهدف وإخراج `reason=dm-blocked`. +- `lightContext`: عند تعيينه إلى true، تستخدم تشغيلات Heartbeat سياق bootstrap خفيفًا وتُبقي فقط `HEARTBEAT.md` من ملفات bootstrap الخاصة بمساحة العمل. +- `isolatedSession`: عند تعيينه إلى true، تعمل كل Heartbeat في جلسة جديدة من دون أي سجل محادثة سابق. وهو نفس نمط العزل في Cron مع `sessionTarget: "isolated"`. ويقلل تكلفة الرموز لكل Heartbeat من نحو ~100K إلى ~2-5K رمز. +- لكل وكيل: اضبط `agents.list[].heartbeat`. وعندما يعرّف أي وكيل `heartbeat`، تعمل **هؤلاء الوكلاء فقط** على تشغيل Heartbeat. +- تشغّل Heartbeat أدوار وكلاء كاملة — والفواصل الأقصر تستهلك مزيدًا من الرموز. ### `agents.defaults.compaction` @@ -1392,14 +1381,14 @@ exec ssh -T gateway-host imsg "$@" defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // id of a registered compaction provider plugin (optional) + provider: "my-provider", // معرّف Plugin مزوّد Compaction مسجل (اختياري) timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom - postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection - model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override - notifyUser: true, // send a brief notice when compaction starts (default: false) + identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // يُستخدم عندما يكون identifierPolicy=custom + postCompactionSections: ["Session Startup", "Red Lines"], // تؤدي [] إلى تعطيل إعادة الحقن + model: "openrouter/anthropic/claude-sonnet-4-6", // تجاوز اختياري للنموذج خاص بـ Compaction فقط + notifyUser: true, // أرسل إشعارًا موجزًا عند بدء Compaction (الافتراضي: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, @@ -1412,19 +1401,19 @@ exec ssh -T gateway-host imsg "$@" } ``` -- `mode`: ‏`default` أو `safeguard` ‏(تلخيص مجزأ للسجلات الطويلة). راجع [Compaction](/ar/concepts/compaction). -- `provider`: معرّف Plugin موفّر Compaction مسجّل. عند ضبطه، يُستدعى `summarize()` الخاص بالموفّر بدلاً من التلخيص المدمج المعتمد على LLM. ويعود إلى السلوك المدمج عند الفشل. يؤدي ضبط موفّر إلى فرض `mode: "safeguard"`. راجع [Compaction](/ar/concepts/compaction). -- `timeoutSeconds`: الحد الأقصى بالثواني المسموح به لعملية Compaction واحدة قبل أن يوقفها OpenClaw. الافتراضي: `900`. -- `identifierPolicy`: ‏`strict` ‏(الافتراضي) أو `off` أو `custom`. تقوم `strict` بإضافة إرشادات مدمجة للاحتفاظ بالمعرّفات غير الشفافة أثناء تلخيص Compaction. -- `identifierInstructions`: نص اختياري مخصص للحفاظ على المعرّفات يُستخدم عندما تكون `identifierPolicy=custom`. -- `postCompactionSections`: أسماء أقسام H2/H3 اختيارية من `AGENTS.md` لإعادة حقنها بعد Compaction. القيمة الافتراضية هي `["Session Startup", "Red Lines"]`؛ اضبط `[]` لتعطيل إعادة الحقن. وعند عدم ضبطه أو عند ضبطه صراحةً على هذا الزوج الافتراضي، تُقبل أيضاً العناوين القديمة `Every Session`/`Safety` كاحتياط للتوافق القديم. -- `model`: تجاوز اختياري بصيغة `provider/model-id` لتلخيص Compaction فقط. استخدم هذا عندما يجب أن تحتفظ الجلسة الرئيسية بنموذج معيّن بينما تعمل ملخصات Compaction على نموذج آخر؛ وعند عدم ضبطه، يستخدم Compaction النموذج الأساسي للجلسة. -- `notifyUser`: عند ضبطه على `true`، يرسل إشعاراً موجزاً إلى المستخدم عند بدء Compaction ‏(على سبيل المثال "Compacting context..."). وهو معطّل افتراضياً للحفاظ على صمت Compaction. -- `memoryFlush`: دور وكيل صامت قبل Compaction التلقائي لتخزين الذكريات الدائمة. يتم تخطيه عندما تكون مساحة العمل للقراءة فقط. +- `mode`: ‏`default` أو `safeguard` (تلخيص مجزأ للسجلات الطويلة). راجع [Compaction](/ar/concepts/compaction). +- `provider`: معرّف Plugin مزوّد Compaction مسجل. عند تعيينه، يُستدعى `summarize()` الخاص بالمزوّد بدلًا من التلخيص المضمن في LLM. ويعود إلى المضمن عند الفشل. ويؤدي تعيين مزوّد إلى فرض `mode: "safeguard"`. راجع [Compaction](/ar/concepts/compaction). +- `timeoutSeconds`: الحد الأقصى بالثواني المسموح به لعملية Compaction واحدة قبل أن يقوم OpenClaw بإيقافها. الافتراضي: `900`. +- `identifierPolicy`: ‏`strict` (الافتراضي) أو `off` أو `custom`. تضيف `strict` تلقائيًا إرشادات مضمنة للحفاظ على المعرّفات المعتمة أثناء تلخيص Compaction. +- `identifierInstructions`: نص اختياري مخصص للحفاظ على المعرّفات يُستخدم عندما يكون `identifierPolicy=custom`. +- `postCompactionSections`: أسماء أقسام H2/H3 اختيارية من AGENTS.md لإعادة حقنها بعد Compaction. القيمة الافتراضية `["Session Startup", "Red Lines"]`؛ عيّن `[]` لتعطيل إعادة الحقن. وعندما لا تكون معيّنة أو تكون معيّنة صراحةً إلى هذا الزوج الافتراضي، تُقبل أيضًا العناوين الأقدم `Every Session`/`Safety` كقيمة احتياطية قديمة. +- `model`: تجاوز اختياري `provider/model-id` لتلخيص Compaction فقط. استخدم هذا عندما يجب أن تبقي الجلسة الرئيسية نموذجًا معينًا بينما تعمل ملخصات Compaction على نموذج آخر؛ وعند عدم تعيينه، يستخدم Compaction النموذج الأساسي للجلسة. +- `notifyUser`: عند تعيينه إلى `true`، يرسل إشعارًا موجزًا إلى المستخدم عند بدء Compaction (على سبيل المثال: "Compacting context..."). وهو معطّل افتراضيًا لإبقاء Compaction صامتًا. +- `memoryFlush`: دور وكيلي صامت قبل Compaction التلقائي لتخزين الذكريات الدائمة. ويُتخطى عندما تكون مساحة العمل للقراءة فقط. ### `agents.defaults.contextPruning` -يقوم بتقليم **نتائج الأدوات القديمة** من السياق الموجود في الذاكرة قبل إرسالها إلى LLM. ولا **يعدّل** سجل الجلسة على القرص. +يقص **نتائج الأدوات القديمة** من السياق الموجود في الذاكرة قبل إرسالها إلى LLM. ولا **يعدّل** سجل الجلسة على القرص. ```json5 { @@ -1432,7 +1421,7 @@ exec ssh -T gateway-host imsg "$@" defaults: { contextPruning: { mode: "cache-ttl", // off | cache-ttl - ttl: "1h", // duration (ms/s/m/h), default unit: minutes + ttl: "1h", // مدة (ms/s/m/h)، وحدة القياس الافتراضية: الدقائق keepLastAssistants: 3, softTrimRatio: 0.3, hardClearRatio: 0.5, @@ -1448,25 +1437,25 @@ exec ssh -T gateway-host imsg "$@" -- يؤدي `mode: "cache-ttl"` إلى تفعيل تمريرات التقليم. -- يتحكم `ttl` في عدد المرات التي يمكن بعدها تشغيل التقليم مجدداً (بعد آخر لمسة للذاكرة المؤقتة). -- يقوم التقليم أولاً باقتطاع نتائج الأدوات الكبيرة اقتطاعاً ليناً، ثم بمسح نتائج الأدوات الأقدم مسحاً صارماً عند الحاجة. +- يفعّل `mode: "cache-ttl"` عمليات القص. +- يتحكم `ttl` في عدد المرات التي يمكن فيها تشغيل القص مرة أخرى (بعد آخر لمسة cache). +- تقوم عملية القص أولًا باقتطاع نتائج الأدوات المتضخمة بشكل جزئي، ثم تمسح نتائج الأدوات الأقدم بالكامل إذا لزم الأمر. -**الاقتطاع اللين** يحتفظ بالبداية + النهاية ويُدرج `...` في الوسط. +**الاقتطاع الجزئي** يحتفظ بالبداية + النهاية ويُدرج `...` في المنتصف. -**المسح الصارم** يستبدل نتيجة الأداة بالكامل بالعنصر النائب. +**المسح الكامل** يستبدل نتيجة الأداة بالكامل بالنص النائب. ملاحظات: -- لا يتم اقتطاع/مسح كتل الصور أبداً. -- تعتمد النِّسب على عدد الأحرف (تقريبياً)، وليس على أعداد الرموز الدقيقة. -- إذا وُجدت رسائل مساعد أقل من `keepLastAssistants`، يتم تخطي التقليم. +- لا تُقتطع/تُمسح كتل الصور مطلقًا. +- تستند النِّسب إلى عدد الأحرف (تقريبيًا)، وليس إلى أعداد الرموز الدقيقة. +- إذا كان عدد رسائل المساعد أقل من `keepLastAssistants`، تُتخطى عملية القص. -راجع [Session Pruning](/ar/concepts/session-pruning) للحصول على تفاصيل السلوك. +راجع [Session Pruning](/ar/concepts/session-pruning) لتفاصيل السلوك. -### بث الكتل +### البث على شكل كتل ```json5 { @@ -1476,17 +1465,17 @@ exec ssh -T gateway-host imsg "$@" blockStreamingBreak: "text_end", // text_end | message_end blockStreamingChunk: { minChars: 800, maxChars: 1200 }, blockStreamingCoalesce: { idleMs: 1000 }, - humanDelay: { mode: "natural" }, // off | natural | custom (use minMs/maxMs) + humanDelay: { mode: "natural" }, // off | natural | custom (استخدم minMs/maxMs) }, }, } ``` -- تتطلب القنوات غير Telegram ضبط `*.blockStreaming: true` صراحةً لتمكين الردود على شكل كتل. -- تجاوزات القناة: `channels..blockStreamingCoalesce` ‏(ومتغيرات كل حساب). تستخدم Signal/Slack/Discord/Google Chat افتراضياً `minChars: 1500`. -- `humanDelay`: توقف عشوائي بين ردود الكتل. وتعني `natural` = ‏800–2500ms. التجاوز لكل وكيل: `agents.list[].humanDelay`. +- تتطلب القنوات غير Telegram تعيين `*.blockStreaming: true` صراحةً لتفعيل الردود على شكل كتل. +- تجاوزات القنوات: `channels..blockStreamingCoalesce` (ومتغيرات كل حساب). تستخدم Signal/Slack/Discord/Google Chat افتراضيًا `minChars: 1500`. +- `humanDelay`: توقف عشوائي بين الردود على شكل كتل. تعني `natural` = ‏800–2500ms. تجاوز لكل وكيل: `agents.list[].humanDelay`. -راجع [Streaming](/ar/concepts/streaming) لمعرفة تفاصيل السلوك + التجزئة. +راجع [Streaming](/ar/concepts/streaming) لمعرفة تفاصيل السلوك والتقسيم. ### مؤشرات الكتابة @@ -1501,8 +1490,8 @@ exec ssh -T gateway-host imsg "$@" } ``` -- القيم الافتراضية: `instant` للدردشات المباشرة/الإشارات، و`message` للدردشات الجماعية غير المذكور فيها البوت. -- تجاوزات كل جلسة: `session.typingMode` و`session.typingIntervalSeconds`. +- القيم الافتراضية: `instant` للدردشات المباشرة/الإشارات، و`message` للدردشات الجماعية غير المشار فيها. +- تجاوزات لكل جلسة: `session.typingMode` و`session.typingIntervalSeconds`. راجع [Typing Indicators](/ar/concepts/typing-indicators). @@ -1510,7 +1499,7 @@ exec ssh -T gateway-host imsg "$@" ### `agents.defaults.sandbox` -العزل الاختياري للوكيل المضمّن. راجع [Sandboxing](/ar/gateway/sandboxing) للحصول على الدليل الكامل. +إعداد اختياري لـ sandbox للوكيل المضمن. راجع [Sandboxing](/ar/gateway/sandboxing) للحصول على الدليل الكامل. ```json5 { @@ -1556,7 +1545,7 @@ exec ssh -T gateway-host imsg "$@" identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // SecretRefs / inline contents also supported: + // كما أن SecretRefs / المحتويات المضمنة مدعومة أيضًا: // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, @@ -1605,46 +1594,46 @@ exec ssh -T gateway-host imsg "$@" } ``` - + **الواجهة الخلفية:** - `docker`: وقت تشغيل Docker محلي (الافتراضي) -- `ssh`: وقت تشغيل بعيد عام مدعوم بـ SSH +- `ssh`: وقت تشغيل بعيد عام مدعوم بواسطة SSH - `openshell`: وقت تشغيل OpenShell -عند تحديد `backend: "openshell"`، تنتقل الإعدادات الخاصة بوقت التشغيل إلى +عند اختيار `backend: "openshell"`، تنتقل الإعدادات الخاصة بوقت التشغيل إلى `plugins.entries.openshell.config`. -**إعداد الواجهة الخلفية SSH:** +**إعداد SSH backend:** - `target`: هدف SSH بصيغة `user@host[:port]` - `command`: أمر عميل SSH ‏(الافتراضي: `ssh`) -- `workspaceRoot`: الجذر البعيد المطلق المستخدم لمساحات العمل بحسب النطاق -- `identityFile` / `certificateFile` / `knownHostsFile`: ملفات محلية موجودة تُمرَّر إلى OpenSSH -- `identityData` / `certificateData` / `knownHostsData`: محتويات مضمنة أو SecretRefs يقوم OpenClaw بتحويلها إلى ملفات مؤقتة وقت التشغيل -- `strictHostKeyChecking` / `updateHostKeys`: إعدادات سياسة مفاتيح المضيف في OpenSSH +- `workspaceRoot`: جذر بعيد مطلق يُستخدم لمساحات العمل لكل نطاق +- `identityFile` / `certificateFile` / `knownHostsFile`: ملفات محلية موجودة مسبقًا تُمرَّر إلى OpenSSH +- `identityData` / `certificateData` / `knownHostsData`: محتويات مضمنة أو SecretRefs يقوم OpenClaw بتحويلها إلى ملفات مؤقتة أثناء التشغيل +- `strictHostKeyChecking` / `updateHostKeys`: مفاتيح سياسة مفاتيح المستضيف في OpenSSH -**أسبقية مصادقة SSH:** +**أولوية مصادقة SSH:** -- تتغلب `identityData` على `identityFile` -- تتغلب `certificateData` على `certificateFile` -- تتغلب `knownHostsData` على `knownHostsFile` -- تُحل القيم `*Data` المدعومة بـ SecretRef من لقطة وقت التشغيل النشطة للأسرار قبل بدء جلسة Sandbox +- `identityData` يتغلب على `identityFile` +- `certificateData` يتغلب على `certificateFile` +- `knownHostsData` يتغلب على `knownHostsFile` +- تُحل قيم `*Data` المدعومة بواسطة SecretRef من اللقطة النشطة لوقت تشغيل الأسرار قبل بدء جلسة sandbox -**سلوك الواجهة الخلفية SSH:** +**سلوك SSH backend:** - يزرع مساحة العمل البعيدة مرة واحدة بعد الإنشاء أو إعادة الإنشاء -- ثم يحافظ على مساحة عمل SSH البعيدة بوصفها الحالة القياسية -- يوجّه `exec` وأدوات الملفات ومسارات الوسائط عبر SSH -- لا يزامن التغييرات البعيدة تلقائياً إلى المضيف -- لا يدعم حاويات متصفح Sandbox +- ثم يُبقي مساحة عمل SSH البعيدة هي القانونية +- ويوجّه `exec` وأدوات الملفات ومسارات الوسائط عبر SSH +- ولا يزامن التغييرات البعيدة إلى المستضيف تلقائيًا +- ولا يدعم حاويات متصفح sandbox **وصول مساحة العمل:** -- `none`: مساحة عمل Sandbox بحسب النطاق تحت `~/.openclaw/sandboxes` -- `ro`: مساحة عمل Sandbox عند `/workspace`، مع تركيب مساحة عمل الوكيل للقراءة فقط عند `/agent` -- `rw`: تُركَّب مساحة عمل الوكيل للقراءة والكتابة عند `/workspace` +- `none`: مساحة عمل sandbox لكل نطاق تحت `~/.openclaw/sandboxes` +- `ro`: مساحة عمل sandbox عند `/workspace`، مع تركيب مساحة عمل الوكيل للقراءة فقط عند `/agent` +- `rw`: تركيب مساحة عمل الوكيل للقراءة/الكتابة عند `/workspace` **النطاق:** @@ -1652,7 +1641,7 @@ exec ssh -T gateway-host imsg "$@" - `agent`: حاوية + مساحة عمل واحدة لكل وكيل (الافتراضي) - `shared`: حاوية ومساحة عمل مشتركتان (من دون عزل بين الجلسات) -**إعداد Plugin ‏OpenShell:** +**إعداد Plugin OpenShell:** ```json5 { @@ -1665,10 +1654,10 @@ exec ssh -T gateway-host imsg "$@" from: "openclaw", remoteWorkspaceDir: "/sandbox", remoteAgentWorkspaceDir: "/agent", - gateway: "lab", // optional - gatewayEndpoint: "https://lab.example", // optional - policy: "strict", // optional OpenShell policy id - providers: ["openai"], // optional + gateway: "lab", // اختياري + gatewayEndpoint: "https://lab.example", // اختياري + policy: "strict", // معرّف سياسة OpenShell اختياري + providers: ["openai"], // اختياري autoProviders: true, timeoutSeconds: 120, }, @@ -1680,30 +1669,30 @@ exec ssh -T gateway-host imsg "$@" **وضع OpenShell:** -- `mirror`: يزرع البعيد من المحلي قبل `exec`، ثم يزامن العودة بعد `exec`؛ وتبقى مساحة العمل المحلية هي الحالة القياسية -- `remote`: يزرع البعيد مرة واحدة عند إنشاء Sandbox، ثم يحافظ على مساحة العمل البعيدة بوصفها الحالة القياسية +- `mirror`: زرع البعيد من المحلي قبل التنفيذ، ثم المزامنة عكسيًا بعد التنفيذ؛ وتبقى مساحة العمل المحلية هي القانونية +- `remote`: زرع البعيد مرة واحدة عند إنشاء sandbox، ثم إبقاء مساحة العمل البعيدة هي القانونية -في وضع `remote`، لا تُزامن تعديلات المضيف المحلية التي تتم خارج OpenClaw تلقائياً إلى Sandbox بعد خطوة الزرع. -يكون النقل عبر SSH إلى Sandbox الخاص بـ OpenShell، لكن Plugin يمتلك دورة حياة Sandbox ومزامنة mirror الاختيارية. +في وضع `remote`، لا تُزامَن تعديلات المستضيف المحلية التي تُجرى خارج OpenClaw إلى sandbox تلقائيًا بعد خطوة الزرع. +تكون وسيلة النقل عبر SSH إلى sandbox الخاص بـ OpenShell، لكن Plugin يملك دورة حياة sandbox والمزامنة العكسية الاختيارية. -يعمل **`setupCommand`** مرة واحدة بعد إنشاء الحاوية (عبر `sh -lc`). ويحتاج إلى خروج شبكي وجذر قابل للكتابة ومستخدم root. +**`setupCommand`** يعمل مرة واحدة بعد إنشاء الحاوية (عبر `sh -lc`). ويحتاج إلى خروج شبكي، وجذر قابل للكتابة، ومستخدم root. -**تستخدم الحاويات افتراضياً `network: "none"`** — اضبطها على `"bridge"` ‏(أو شبكة bridge مخصصة) إذا كان الوكيل يحتاج إلى وصول صادر. -يُحظر `"host"`. ويُحظر `"container:"` افتراضياً ما لم تضبط صراحةً -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` ‏(وضع طارئ). +**تستخدم الحاويات افتراضيًا `network: "none"`** — عيّنها إلى `"bridge"` (أو شبكة bridge مخصصة) إذا كان الوكيل يحتاج إلى وصول صادر. +تكون `"host"` محظورة. وتكون `"container:"` محظورة افتراضيًا ما لم تعيّن صراحةً +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (وضع طارئ). -تُجهَّز **المرفقات الواردة** ضمن `media/inbound/*` في مساحة العمل النشطة. +**تُجهَّز المرفقات الواردة** ضمن `media/inbound/*` في مساحة العمل النشطة. -يقوم **`docker.binds`** بتركيب أدلة مضيف إضافية؛ ويتم دمج bind العامة وتلك الخاصة بكل وكيل. +**`docker.binds`** يركّب أدلة إضافية من المستضيف؛ ويتم دمج الروابط العامة وتلك الخاصة بكل وكيل. -**متصفح Sandbox** ‏(`sandbox.browser.enabled`): ‏Chromium + CDP داخل حاوية. يتم حقن عنوان URL الخاص بـ noVNC في system prompt. ولا يتطلب `browser.enabled` في `openclaw.json`. -يستخدم وصول المراقبة عبر noVNC مصادقة VNC افتراضياً، ويصدر OpenClaw عنوان URL برمز مميز قصير العمر (بدلاً من كشف كلمة المرور في عنوان URL المشترك). +**المتصفح داخل sandbox** (`sandbox.browser.enabled`): ‏Chromium + CDP داخل حاوية. يتم حقن عنوان noVNC URL في system prompt. ولا يتطلب `browser.enabled` في `openclaw.json`. +يستخدم وصول المراقبة عبر noVNC مصادقة VNC افتراضيًا، ويصدر OpenClaw عنوان URL برمز مميز قصير العمر (بدلًا من كشف كلمة المرور في عنوان URL المشترك). -- يؤدي `allowHostControl: false` ‏(الافتراضي) إلى حظر الجلسات المعزولة من استهداف متصفح المضيف. -- القيمة الافتراضية لـ `network` هي `openclaw-sandbox-browser` ‏(شبكة bridge مخصصة). اضبطها على `bridge` فقط عندما تريد صراحةً اتصال bridge عاماً. -- يقيّد `cdpSourceRange` اختيارياً دخول CDP عند حافة الحاوية إلى نطاق CIDR ‏(على سبيل المثال `172.21.0.1/32`). -- يقوم `sandbox.browser.binds` بتركيب أدلة مضيف إضافية في حاوية متصفح Sandbox فقط. وعند ضبطه (بما في ذلك `[]`) فإنه يستبدل `docker.binds` لحاوية المتصفح. -- تُعرّف إعدادات التشغيل الافتراضية في `scripts/sandbox-browser-entrypoint.sh` وتُضبط لبيئات الحاويات: +- يؤدي `allowHostControl: false` (الافتراضي) إلى حظر استهداف جلسات sandbox للمستعرض الموجود على المستضيف. +- تكون القيمة الافتراضية لـ `network` هي `openclaw-sandbox-browser` (شبكة bridge مخصصة). اضبطها على `bridge` فقط عندما تريد صراحةً اتصال bridge عامًا. +- يقيّد `cdpSourceRange` اختياريًا حركة CDP الواردة عند حافة الحاوية إلى نطاق CIDR ‏(على سبيل المثال `172.21.0.1/32`). +- يقوم `sandbox.browser.binds` بتركيب أدلة إضافية من المستضيف داخل حاوية متصفح sandbox فقط. وعند تعيينه (بما في ذلك `[]`)، فإنه يستبدل `docker.binds` لحاوية المتصفح. +- تُعرَّف افتراضيات التشغيل في `scripts/sandbox-browser-entrypoint.sh` وتُضبط لمستضيفي الحاويات: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1720,18 +1709,18 @@ exec ssh -T gateway-host imsg "$@" - `--renderer-process-limit=2` - `--no-zygote` - `--metrics-recording-only` - - `--disable-extensions` ‏(مفعّل افتراضياً) + - `--disable-extensions` (مفعّل افتراضيًا) - تكون `--disable-3d-apis` و`--disable-software-rasterizer` و`--disable-gpu` - مفعّلة افتراضياً، ويمكن تعطيلها عبر - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` إذا كان استخدام WebGL/3D يتطلب ذلك. + مفعّلة افتراضيًا، ويمكن تعطيلها عبر + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` إذا كان استخدام WebGL/‏3D يتطلب ذلك. - يعيد `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` تفعيل الإضافات إذا كان سير عملك يعتمد عليها. - يمكن تغيير `--renderer-process-limit=2` عبر - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`؛ اضبطه على `0` لاستخدام + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`؛ اضبطه إلى `0` لاستخدام حد العمليات الافتراضي في Chromium. - - بالإضافة إلى `--no-sandbox` و`--disable-setuid-sandbox` عند تفعيل `noSandbox`. + - بالإضافة إلى `--no-sandbox` و`--disable-setuid-sandbox` عندما يكون `noSandbox` مفعّلًا. - تمثل القيم الافتراضية خط الأساس لصورة الحاوية؛ استخدم صورة متصفح مخصصة مع - entrypoint مخصص لتغيير القيم الافتراضية للحاوية. + entrypoint مخصص لتغيير افتراضيات الحاوية. @@ -1740,11 +1729,11 @@ exec ssh -T gateway-host imsg "$@" أنشئ الصور: ```bash -scripts/sandbox-setup.sh # main sandbox image -scripts/sandbox-browser-setup.sh # optional browser image +scripts/sandbox-setup.sh # صورة sandbox الرئيسية +scripts/sandbox-browser-setup.sh # صورة المتصفح الاختيارية ``` -### `agents.list` ‏(تجاوزات لكل وكيل) +### `agents.list` (تجاوزات لكل وكيل) ```json5 { @@ -1756,13 +1745,13 @@ scripts/sandbox-browser-setup.sh # optional browser image name: "Main Agent", workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", - model: "anthropic/claude-opus-4-6", // or { primary, fallbacks } - thinkingDefault: "high", // per-agent thinking level override - reasoningDefault: "on", // per-agent reasoning visibility override - fastModeDefault: false, // per-agent fast mode override + model: "anthropic/claude-opus-4-6", // أو { primary, fallbacks } + thinkingDefault: "high", // تجاوز مستوى التفكير الافتراضي لكل وكيل + reasoningDefault: "on", // تجاوز إظهار الاستدلال الافتراضي لكل وكيل + fastModeDefault: false, // تجاوز الوضع السريع الافتراضي لكل وكيل embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // overrides matching defaults.models params by key - skills: ["docs-search"], // replaces agents.defaults.skills when set + params: { cacheRetention: "none" }, // يتجاوز قيم defaults.models.params المطابقة حسب المفتاح + skills: ["docs-search"], // يستبدل agents.defaults.skills عند التعيين identity: { name: "Samantha", theme: "helpful sloth", @@ -1794,26 +1783,26 @@ scripts/sandbox-browser-setup.sh # optional browser image ``` - `id`: معرّف وكيل ثابت (مطلوب). -- `default`: عند ضبط أكثر من واحد، يفوز الأول (مع تسجيل تحذير). وإذا لم يُضبط أيٌّ منها، يكون أول إدخال في القائمة هو الافتراضي. -- `model`: يتجاوز نموذج السلسلة `primary` فقط؛ بينما يتجاوز نموذج الكائن `{ primary, fallbacks }` كليهما (`[]` يعطّل القيم الاحتياطية العامة). وتظل مهام Cron التي تتجاوز `primary` فقط ترث القيم الاحتياطية الافتراضية ما لم تضبط `fallbacks: []`. -- `params`: معلمات بث لكل وكيل تُدمج فوق إدخال النموذج المحدد في `agents.defaults.models`. استخدم هذا لتجاوزات خاصة بالوكيل مثل `cacheRetention` أو `temperature` أو `maxTokens` من دون تكرار فهرس النماذج بالكامل. -- `skills`: قائمة سماح اختيارية لـ Skills لكل وكيل. إذا حُذفت، يرث الوكيل `agents.defaults.skills` عند ضبطها؛ وتحل القائمة الصريحة محل القيم الافتراضية بدلاً من الدمج، وتعني `[]` عدم وجود أي Skills. +- `default`: عند تعيين عدة قيم، يفوز الأول (مع تسجيل تحذير). وإذا لم تُعيَّن أي قيمة، يكون أول إدخال في القائمة هو الافتراضي. +- `model`: يتجاوز نموذج السلسلة القيمة `primary` فقط؛ أما نموذج الكائن `{ primary, fallbacks }` فيتجاوز كليهما (`[]` يعطّل القيم الاحتياطية العامة). وتظل مهام Cron التي تتجاوز `primary` فقط ترث القيم الاحتياطية الافتراضية ما لم تعيّن `fallbacks: []`. +- `params`: معاملات البث لكل وكيل، وتُدمج فوق إدخال النموذج المحدد في `agents.defaults.models`. استخدم هذا لتجاوزات خاصة بالوكيل مثل `cacheRetention` أو `temperature` أو `maxTokens` من دون تكرار فهرس النماذج بالكامل. +- `skills`: قائمة سماح اختيارية لـ Skills لكل وكيل. إذا حُذفت، يرث الوكيل `agents.defaults.skills` عند تعيينها؛ وتستبدل القائمة الصريحة القيم الافتراضية بدلًا من دمجها، وتعني `[]` عدم وجود Skills. - `thinkingDefault`: مستوى التفكير الافتراضي الاختياري لكل وكيل (`off | minimal | low | medium | high | xhigh | adaptive`). ويتجاوز `agents.defaults.thinkingDefault` لهذا الوكيل عندما لا يكون هناك تجاوز لكل رسالة أو جلسة. -- `reasoningDefault`: مستوى رؤية reasoning الافتراضي الاختياري لكل وكيل (`on | off | stream`). ويُطبّق عندما لا يكون هناك تجاوز reasoning لكل رسالة أو جلسة. -- `fastModeDefault`: القيمة الافتراضية الاختيارية لكل وكيل للوضع السريع (`true | false`). وتُطبّق عندما لا يكون هناك تجاوز للوضع السريع لكل رسالة أو جلسة. -- `embeddedHarness`: تجاوز اختياري لسياسة harness منخفضة المستوى لكل وكيل. استخدم `{ runtime: "codex", fallback: "none" }` لجعل وكيل واحد يعمل مع Codex فقط بينما يحتفظ الوكلاء الآخرون بالرجوع الافتراضي إلى PI. -- `runtime`: واصف وقت تشغيل اختياري لكل وكيل. استخدم `type: "acp"` مع القيم الافتراضية لـ `runtime.acp` ‏(`agent` و`backend` و`mode` و`cwd`) عندما يجب أن يستخدم الوكيل جلسات ACP harness افتراضياً. -- `identity.avatar`: مسار نسبي لمساحة العمل، أو عنوان URL ‏`http(s)`، أو URI من نوع `data:`. -- تستخلص `identity` القيم الافتراضية: `ackReaction` من `emoji`، و`mentionPatterns` من `name`/`emoji`. -- `subagents.allowAgents`: قائمة سماح لمعرّفات الوكلاء من أجل `sessions_spawn` ‏(`["*"]` = أي وكيل؛ والافتراضي: الوكيل نفسه فقط). -- حاجز وراثة Sandbox: إذا كانت جلسة الطالب داخل Sandbox، فإن `sessions_spawn` يرفض الأهداف التي ستعمل من دون Sandbox. -- `subagents.requireAgentId`: عند ضبطه على true، يحظر استدعاءات `sessions_spawn` التي تحذف `agentId` ‏(يفرض اختيار ملف تعريف صريح؛ الافتراضي: false). +- `reasoningDefault`: إظهار الاستدلال الافتراضي الاختياري لكل وكيل (`on | off | stream`). ويُطبَّق عندما لا يكون هناك تجاوز للاستدلال لكل رسالة أو جلسة. +- `fastModeDefault`: القيمة الافتراضية الاختيارية لكل وكيل للوضع السريع (`true | false`). وتُطبَّق عندما لا يكون هناك تجاوز للوضع السريع لكل رسالة أو جلسة. +- `embeddedHarness`: تجاوز اختياري لسياسة harness منخفضة المستوى لكل وكيل. استخدم `{ runtime: "codex", fallback: "none" }` لجعل أحد الوكلاء يعمل بـ Codex فقط بينما يحتفظ الآخرون بالقيمة الاحتياطية الافتراضية PI. +- `runtime`: واصف وقت تشغيل اختياري لكل وكيل. استخدم `type: "acp"` مع القيم الافتراضية `runtime.acp` ‏(`agent` و`backend` و`mode` و`cwd`) عندما يجب أن يستخدم الوكيل افتراضيًا جلسات ACP harness. +- `identity.avatar`: مسار نسبي إلى مساحة العمل، أو عنوان URL من نوع `http(s)`، أو معرّف URI من نوع `data:`. +- تستمد `identity` القيم الافتراضية: `ackReaction` من `emoji`، و`mentionPatterns` من `name`/`emoji`. +- `subagents.allowAgents`: قائمة سماح لمعرّفات الوكلاء لـ `sessions_spawn` ‏(`["*"]` = أي وكيل؛ الافتراضي: الوكيل نفسه فقط). +- حماية وراثة sandbox: إذا كانت جلسة الطالب داخل sandbox، فإن `sessions_spawn` يرفض الأهداف التي ستعمل خارج sandbox. +- `subagents.requireAgentId`: عند تعيينه إلى true، يحظر استدعاءات `sessions_spawn` التي تحذف `agentId` (يفرض اختيار ملف تعريف صريح؛ الافتراضي: false). --- -## التوجيه متعدد الوكلاء +## توجيه الوكلاء المتعددين -شغّل عدة وكلاء معزولين داخل Gateway واحد. راجع [متعدد الوكلاء](/ar/concepts/multi-agent). +شغّل عدة وكلاء معزولين داخل Gateway واحد. راجع [Multi-Agent](/ar/concepts/multi-agent). ```json5 { @@ -1830,31 +1819,31 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -### حقول مطابقة الارتباط +### حقول المطابقة في Binding -- `type` ‏(اختياري): ‏`route` للتوجيه العادي (والنوع المفقود يعود افتراضياً إلى route)، و`acp` لارتباطات محادثات ACP الدائمة. -- `match.channel` ‏(مطلوب) -- `match.accountId` ‏(اختياري؛ `*` = أي حساب؛ والحذف = الحساب الافتراضي) -- `match.peer` ‏(اختياري؛ `{ kind: direct|group|channel, id }`) -- `match.guildId` / `match.teamId` ‏(اختياري؛ خاص بالقناة) -- `acp` ‏(اختياري؛ فقط لـ `type: "acp"`): ‏`{ mode, label, cwd, backend }` +- `type` (اختياري): `route` للتوجيه العادي (وعند غياب النوع تكون القيمة الافتراضية route)، و`acp` لارتباطات المحادثات الدائمة الخاصة بـ ACP. +- `match.channel` (مطلوب) +- `match.accountId` (اختياري؛ `*` = أي حساب؛ والحذف = الحساب الافتراضي) +- `match.peer` (اختياري؛ `{ kind: direct|group|channel, id }`) +- `match.guildId` / `match.teamId` (اختياري؛ خاص بالقناة) +- `acp` (اختياري؛ فقط لإدخالات `type: "acp"`): ‏`{ mode, label, cwd, backend }` **ترتيب المطابقة الحتمي:** 1. `match.peer` 2. `match.guildId` 3. `match.teamId` -4. `match.accountId` ‏(مطابقة تامة، من دون peer/guild/team) -5. `match.accountId: "*"` ‏(على مستوى القناة) +4. `match.accountId` (مطابقة تامة، بلا peer/guild/team) +5. `match.accountId: "*"` (على مستوى القناة) 6. الوكيل الافتراضي -ضمن كل مستوى، يفوز أول إدخال مطابق في `bindings`. +داخل كل مستوى، يفوز أول إدخال مطابق في `bindings`. -بالنسبة إلى إدخالات `type: "acp"`، يحل OpenClaw حسب هوية المحادثة الدقيقة (`match.channel` + الحساب + `match.peer.id`) ولا يستخدم ترتيب مستويات route binding أعلاه. +بالنسبة إلى إدخالات `type: "acp"`، يحل OpenClaw بالاعتماد على هوية المحادثة الدقيقة (`match.channel` + الحساب + `match.peer.id`) ولا يستخدم ترتيب مستويات route binding المذكور أعلاه. -### ملفات تعريف الوصول لكل وكيل +### ملفات الوصول لكل وكيل - + ```json5 { @@ -1947,7 +1936,7 @@ scripts/sandbox-browser-setup.sh # optional browser image -راجع [Sandbox والأدوات في بيئة متعددة الوكلاء](/ar/tools/multi-agent-sandbox-tools) لمعرفة تفاصيل الأسبقية. +راجع [Multi-Agent Sandbox & Tools](/ar/tools/multi-agent-sandbox-tools) لمعرفة تفاصيل الأولوية. --- @@ -1973,22 +1962,22 @@ scripts/sandbox-browser-setup.sh # optional browser image }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables) + parentForkMaxTokens: 100000, // تخطَّ fork السلسلة الأم فوق هذا العدد من الرموز (0 للتعطيل) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, rotateBytes: "10mb", - resetArchiveRetention: "30d", // duration or false - maxDiskBytes: "500mb", // optional hard budget - highWaterBytes: "400mb", // optional cleanup target + resetArchiveRetention: "30d", // مدة أو false + maxDiskBytes: "500mb", // ميزانية قصوى صلبة اختيارية + highWaterBytes: "400mb", // هدف تنظيف اختياري }, threadBindings: { enabled: true, - idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables) - maxAgeHours: 0, // default hard max age in hours (`0` disables) + idleHours: 24, // القيمة الافتراضية لإلغاء التركيز التلقائي بعد عدم النشاط، بالساعات (`0` للتعطيل) + maxAgeHours: 0, // القيمة الافتراضية للحد الأقصى الصارم للعمر، بالساعات (`0` للتعطيل) }, - mainKey: "main", // legacy (runtime always uses "main") + mainKey: "main", // قديم (يستخدم وقت التشغيل دائمًا "main") agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -2001,34 +1990,34 @@ scripts/sandbox-browser-setup.sh # optional browser image - **`scope`**: استراتيجية تجميع الجلسات الأساسية لسياقات الدردشة الجماعية. - - `per-sender` ‏(الافتراضي): يحصل كل مرسل على جلسة معزولة ضمن سياق القناة. - - `global`: يشارك جميع المشاركين في سياق القناة جلسة واحدة (استخدمه فقط عندما يكون السياق المشترك مقصوداً). + - `per-sender` (الافتراضي): يحصل كل مرسل على جلسة معزولة ضمن سياق القناة. + - `global`: يشارك جميع المشاركين في سياق القناة جلسة واحدة (استخدمه فقط عندما يكون المقصود سياقًا مشتركًا). - **`dmScope`**: كيفية تجميع الرسائل المباشرة. - `main`: تشترك جميع الرسائل المباشرة في الجلسة الرئيسية. - `per-peer`: العزل حسب معرّف المرسل عبر القنوات. - - `per-channel-peer`: العزل لكل قناة + مرسل (مستحسن لصناديق الوارد متعددة المستخدمين). - - `per-account-channel-peer`: العزل لكل حساب + قناة + مرسل (مستحسن لتعدد الحسابات). -- **`identityLinks`**: يربط المعرّفات القياسية بالنظراء ذوي بادئة الموفّر لمشاركة الجلسات عبر القنوات. -- **`reset`**: سياسة إعادة التعيين الأساسية. تعيد `daily` التعيين عند `atHour` حسب التوقيت المحلي؛ وتعاد `idle` بعد `idleMinutes`. وعند ضبط الاثنين معاً، يفوز ما تنتهي صلاحيته أولاً. -- **`resetByType`**: تجاوزات حسب النوع (`direct` و`group` و`thread`). ويُقبل `dm` القديم كاسم بديل لـ `direct`. -- **`parentForkMaxTokens`**: الحد الأقصى المسموح به لـ `totalTokens` في الجلسة الأصل عند إنشاء جلسة خيط متشعبة (الافتراضي `100000`). - - إذا كانت قيمة `totalTokens` في الأصل أعلى من هذه القيمة، يبدأ OpenClaw جلسة خيط جديدة بدلاً من وراثة سجل transcript الخاص بالأصل. - - اضبط `0` لتعطيل هذا الحاجز والسماح دائماً بالتشعب من الأصل. -- **`mainKey`**: حقل قديم. يستخدم وقت التشغيل دائماً `"main"` لدلو الدردشة المباشرة الرئيسي. -- **`agentToAgent.maxPingPongTurns`**: الحد الأقصى لأدوار الرد المتبادل بين الوكلاء أثناء تبادلات وكيل-إلى-وكيل (عدد صحيح، المجال: `0`–`5`). تؤدي القيمة `0` إلى تعطيل تسلسل ping-pong. -- **`sendPolicy`**: المطابقة حسب `channel` أو `chatType` ‏(`direct|group|channel`، مع الاسم البديل القديم `dm`) أو `keyPrefix` أو `rawKeyPrefix`. ويفوز أول رفض. -- **`maintenance`**: عناصر تحكم تنظيف + الاحتفاظ بمخزن الجلسات. - - `mode`: تؤدي `warn` إلى إطلاق تحذيرات فقط؛ بينما تطبق `enforce` التنظيف. + - `per-channel-peer`: العزل لكل قناة + مرسل (موصى به لصناديق الوارد متعددة المستخدمين). + - `per-account-channel-peer`: العزل لكل حساب + قناة + مرسل (موصى به لتعدد الحسابات). +- **`identityLinks`**: يربط المعرّفات القانونية بالنظراء ذوي بادئة المزوّد لمشاركة الجلسات عبر القنوات. +- **`reset`**: سياسة إعادة التعيين الأساسية. يعيد `daily` التعيين عند `atHour` بالتوقيت المحلي؛ ويعيد `idle` التعيين بعد `idleMinutes`. وعند ضبط كليهما، يفوز الذي تنتهي مدته أولًا. +- **`resetByType`**: تجاوزات حسب النوع (`direct` و`group` و`thread`). وتُقبل `dm` القديمة كاسم بديل لـ `direct`. +- **`parentForkMaxTokens`**: الحد الأقصى لـ `totalTokens` المسموح به في الجلسة الأم عند إنشاء جلسة سلسلة متفرعة (الافتراضي `100000`). + - إذا كانت قيمة `totalTokens` في الجلسة الأم أعلى من هذا الحد، يبدأ OpenClaw جلسة سلسلة جديدة بدلًا من وراثة سجل الجلسة الأم. + - عيّن القيمة `0` لتعطيل هذه الحماية والسماح دائمًا بالتفرع من الجلسة الأم. +- **`mainKey`**: حقل قديم. يستخدم وقت التشغيل دائمًا `"main"` كحاوية الدردشة المباشرة الرئيسية. +- **`agentToAgent.maxPingPongTurns`**: الحد الأقصى لعدد أدوار الرد المتبادل بين الوكلاء أثناء تبادلات وكيل إلى وكيل (عدد صحيح، النطاق: `0`–`5`). تؤدي `0` إلى تعطيل تسلسل ping-pong. +- **`sendPolicy`**: المطابقة حسب `channel`، و`chatType` ‏(`direct|group|channel`، مع الاسم البديل القديم `dm`)، أو `keyPrefix`، أو `rawKeyPrefix`. يفوز أول رفض. +- **`maintenance`**: عناصر التحكم في تنظيف مخزن الجلسات والاحتفاظ بها. + - `mode`: يؤدي `warn` إلى إصدار تحذيرات فقط؛ ويطبق `enforce` التنظيف. - `pruneAfter`: حد العمر للإدخالات القديمة (الافتراضي `30d`). - - `maxEntries`: الحد الأقصى لعدد الإدخالات في `sessions.json` ‏(الافتراضي `500`). + - `maxEntries`: الحد الأقصى لعدد الإدخالات في `sessions.json` (الافتراضي `500`). - `rotateBytes`: تدوير `sessions.json` عندما يتجاوز هذا الحجم (الافتراضي `10mb`). - - `resetArchiveRetention`: مدة الاحتفاظ بأرشيفات transcript ذات الصيغة `*.reset.`. وتعود افتراضياً إلى `pruneAfter`؛ واضبط `false` لتعطيلها. - - `maxDiskBytes`: ميزانية قرص اختيارية لدليل الجلسات. في وضع `warn` تسجل تحذيرات؛ وفي وضع `enforce` تزيل أقدم العناصر/الجلسات أولاً. - - `highWaterBytes`: هدف اختياري بعد تنظيف الميزانية. وتعود افتراضياً إلى `80%` من `maxDiskBytes`. -- **`threadBindings`**: القيم الافتراضية العامة لميزات الجلسات المرتبطة بالخيوط. - - `enabled`: مفتاح افتراضي رئيسي (يمكن للموفّرين تجاوزه؛ ويستخدم Discord القيمة `channels.discord.threadBindings.enabled`) - - `idleHours`: القيمة الافتراضية لإلغاء التركيز التلقائي بسبب عدم النشاط بالساعات (`0` للتعطيل؛ ويمكن للموفّرين تجاوزها) - - `maxAgeHours`: القيمة الافتراضية للحد الأقصى الصارم للعمر بالساعات (`0` للتعطيل؛ ويمكن للموفّرين تجاوزها) + - `resetArchiveRetention`: مدة الاحتفاظ بأرشيفات النصوص `*.reset.`. وتكون افتراضيًا مساوية لـ `pruneAfter`؛ اضبطها على `false` للتعطيل. + - `maxDiskBytes`: ميزانية قرص اختيارية لدليل الجلسات. في وضع `warn` تسجَّل تحذيرات؛ وفي وضع `enforce` تُزال أقدم الملفات/الجلسات أولًا. + - `highWaterBytes`: هدف اختياري بعد تنظيف الميزانية. ويكون افتراضيًا `80%` من `maxDiskBytes`. +- **`threadBindings`**: القيم الافتراضية العامة لميزات الجلسات المرتبطة بالسلاسل. + - `enabled`: مفتاح افتراضي رئيسي (يمكن للمزوّدين تجاوزه؛ يستخدم Discord القيمة `channels.discord.threadBindings.enabled`) + - `idleHours`: القيمة الافتراضية لإلغاء التركيز التلقائي بعد عدم النشاط، بالساعات (`0` للتعطيل؛ ويمكن للمزوّدين تجاوزها) + - `maxAgeHours`: القيمة الافتراضية للحد الأقصى الصارم للعمر، بالساعات (`0` للتعطيل؛ ويمكن للمزوّدين تجاوزها) @@ -2039,7 +2028,7 @@ scripts/sandbox-browser-setup.sh # optional browser image ```json5 { messages: { - responsePrefix: "🦞", // or "auto" + responsePrefix: "🦞", // أو "auto" ackReaction: "👀", ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all removeAckAfterReply: false, @@ -2054,7 +2043,7 @@ scripts/sandbox-browser-setup.sh # optional browser image }, }, inbound: { - debounceMs: 2000, // 0 disables + debounceMs: 2000, // 0 للتعطيل byChannel: { whatsapp: 5000, slack: 1500, @@ -2064,40 +2053,40 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -### بادئة الرد +### بادئة الاستجابة -التجاوزات لكل قناة/حساب: `channels..responsePrefix` و`channels..accounts..responsePrefix`. +تجاوزات لكل قناة/حساب: `channels..responsePrefix` و`channels..accounts..responsePrefix`. -آلية الحل (الأكثر تحديداً يفوز): الحساب → القناة → العام. تؤدي `""` إلى التعطيل وإيقاف التسلسل. وتستخرج `"auto"` القيمة `[{identity.name}]`. +آلية الحل (الأكثر تحديدًا يفوز): الحساب → القناة → العام. تؤدي `""` إلى التعطيل وإيقاف التسلسل. وتشتق `"auto"` القيمة `[{identity.name}]`. **متغيرات القالب:** -| المتغير | الوصف | المثال | +| المتغير | الوصف | مثال | | ----------------- | ---------------------- | --------------------------- | -| `{model}` | اسم النموذج المختصر | `claude-opus-4-6` | -| `{modelFull}` | معرّف النموذج الكامل | `anthropic/claude-opus-4-6` | -| `{provider}` | اسم الموفّر | `anthropic` | -| `{thinkingLevel}` | مستوى التفكير الحالي | `high`, `low`, `off` | -| `{identity.name}` | اسم هوية الوكيل | (مثل `"auto"`) | +| `{model}` | الاسم المختصر للنموذج | `claude-opus-4-6` | +| `{modelFull}` | معرّف النموذج الكامل | `anthropic/claude-opus-4-6` | +| `{provider}` | اسم المزوّد | `anthropic` | +| `{thinkingLevel}` | مستوى التفكير الحالي | `high`، `low`، `off` | +| `{identity.name}` | اسم هوية الوكيل | (مثل `"auto"`) | -المتغيرات غير حساسة لحالة الأحرف. ويُعد `{think}` اسماً بديلاً لـ `{thinkingLevel}`. +المتغيرات غير حساسة لحالة الأحرف. وتُعد `{think}` اسمًا بديلًا لـ `{thinkingLevel}`. ### تفاعل التأكيد -- يعود افتراضياً إلى `identity.emoji` الخاص بالوكيل النشط، وإلا إلى `"👀"`. اضبط `""` لتعطيله. -- التجاوزات لكل قناة: `channels..ackReaction` و`channels..accounts..ackReaction`. -- ترتيب الحل: الحساب → القناة → `messages.ackReaction` → الاحتياطي من الهوية. -- النطاق: `group-mentions` ‏(الافتراضي) أو `group-all` أو `direct` أو `all`. -- يزيل `removeAckAfterReply` تفاعل التأكيد بعد الرد في Slack وDiscord وTelegram. -- يؤدي `messages.statusReactions.enabled` إلى تفعيل تفاعلات الحالة الدورية في Slack وDiscord وTelegram. - في Slack وDiscord، يؤدي عدم الضبط إلى إبقاء تفاعلات الحالة مفعّلة عندما تكون تفاعلات التأكيد نشطة. - وفي Telegram، اضبطه صراحةً على `true` لتفعيل تفاعلات الحالة الدورية. +- تكون القيمة الافتراضية هي `identity.emoji` الخاصة بالوكيل النشط، وإلا `"👀"`. عيّن `""` للتعطيل. +- تجاوزات لكل قناة: `channels..ackReaction` و`channels..accounts..ackReaction`. +- ترتيب الحل: الحساب → القناة → `messages.ackReaction` → الاحتياط المستند إلى الهوية. +- النطاق: `group-mentions` (الافتراضي) و`group-all` و`direct` و`all`. +- يؤدي `removeAckAfterReply` إلى إزالة التأكيد بعد الرد في Slack وDiscord وTelegram. +- يفعّل `messages.statusReactions.enabled` تفاعلات الحالة خلال دورة الحياة في Slack وDiscord وTelegram. + وفي Slack وDiscord، يؤدي عدم التعيين إلى إبقاء تفاعلات الحالة مفعّلة عندما تكون تفاعلات التأكيد نشطة. + وفي Telegram، عيّنه صراحةً إلى `true` لتفعيل تفاعلات الحالة خلال دورة الحياة. ### إزالة الارتداد للرسائل الواردة -يجمع الرسائل النصية السريعة من المرسل نفسه في دور وكيل واحد. وتؤدي الوسائط/المرفقات إلى التفريغ فوراً. وتتجاوز أوامر التحكم إزالة الارتداد. +تجمع الرسائل النصية السريعة من المرسل نفسه في دور وكيل واحد. وتؤدي الوسائط/المرفقات إلى التفريغ فورًا. وتتجاوز أوامر التحكم إزالة الارتداد. -### TTS ‏(تحويل النص إلى كلام) +### TTS (تحويل النص إلى كلام) ```json5 { @@ -2138,18 +2127,18 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- يتحكم `auto` في وضع TTS التلقائي الافتراضي: `off` أو `always` أو `inbound` أو `tagged`. ويمكن للأمر `/tts on|off` تجاوز التفضيلات المحلية، ويعرض `/tts status` الحالة الفعلية. -- يتجاوز `summaryModel` القيمة `agents.defaults.model.primary` للملخص التلقائي. -- يكون `modelOverrides` مفعّلاً افتراضياً؛ وتعود القيمة الافتراضية لـ `modelOverrides.allowProvider` إلى `false` ‏(اشتراك اختياري). +- يتحكم `auto` في وضع TTS التلقائي الافتراضي: `off` أو `always` أو `inbound` أو `tagged`. ويمكن أن يتجاوز `/tts on|off` التفضيلات المحلية، بينما يعرض `/tts status` الحالة الفعلية. +- يتجاوز `summaryModel` القيمة `agents.defaults.model.primary` للتلخيص التلقائي. +- يكون `modelOverrides` مفعّلًا افتراضيًا؛ وتكون القيمة الافتراضية لـ `modelOverrides.allowProvider` هي `false` (تفعيل اختياري). - تعود مفاتيح API إلى `ELEVENLABS_API_KEY`/`XI_API_KEY` و`OPENAI_API_KEY`. -- يتجاوز `openai.baseUrl` نقطة نهاية OpenAI الخاصة بـ TTS. وترتيب الحل هو: الإعدادات، ثم `OPENAI_TTS_BASE_URL`، ثم `https://api.openai.com/v1`. -- عندما يشير `openai.baseUrl` إلى نقطة نهاية ليست تابعة لـ OpenAI، يتعامل OpenClaw معها كخادم TTS متوافق مع OpenAI ويخفف التحقق من النموذج/الصوت. +- يتجاوز `openai.baseUrl` نقطة نهاية OpenAI TTS. ترتيب الحل هو: الإعدادات، ثم `OPENAI_TTS_BASE_URL`، ثم `https://api.openai.com/v1`. +- عندما يشير `openai.baseUrl` إلى نقطة نهاية غير تابعة لـ OpenAI، يتعامل OpenClaw معها على أنها خادم TTS متوافق مع OpenAI ويخفف التحقق من النموذج/الصوت. --- ## Talk -القيم الافتراضية لوضع Talk ‏(macOS/iOS/Android). +الإعدادات الافتراضية لوضع Talk ‏(macOS/iOS/Android). ```json5 { @@ -2173,13 +2162,13 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- يجب أن تطابق `talk.provider` مفتاحاً في `talk.providers` عند ضبط عدة موفّرين لـ Talk. -- مفاتيح Talk القديمة المسطحة (`talk.voiceId` و`talk.voiceAliases` و`talk.modelId` و`talk.outputFormat` و`talk.apiKey`) مخصّصة للتوافق فقط، وتُرحّل تلقائياً إلى `talk.providers.`. -- تعود معرّفات الأصوات احتياطياً إلى `ELEVENLABS_VOICE_ID` أو `SAG_VOICE_ID`. -- تقبل `providers.*.apiKey` سلاسل نصية صريحة أو كائنات SecretRef. -- ينطبق الاحتياطي `ELEVENLABS_API_KEY` فقط عندما لا يكون مفتاح API الخاص بـ Talk مضبوطاً. -- يتيح `providers.*.voiceAliases` لتوجيهات Talk استخدام أسماء ودية. -- يتحكم `silenceTimeoutMs` في المدة التي ينتظرها وضع Talk بعد صمت المستخدم قبل أن يرسل transcript. وعند عدم ضبطه، يحتفظ بنافذة التوقف الافتراضية للمنصة (`700 ms على macOS وAndroid، و900 ms على iOS`). +- يجب أن يطابق `talk.provider` مفتاحًا في `talk.providers` عند إعداد عدة مزوّدين لـ Talk. +- مفاتيح Talk القديمة المسطحة (`talk.voiceId` و`talk.voiceAliases` و`talk.modelId` و`talk.outputFormat` و`talk.apiKey`) مخصصة للتوافق فقط، وتُرحَّل تلقائيًا إلى `talk.providers.`. +- تعود معرّفات الأصوات إلى `ELEVENLABS_VOICE_ID` أو `SAG_VOICE_ID`. +- يقبل `providers.*.apiKey` سلاسل نصية صريحة أو كائنات SecretRef. +- لا يُطبَّق الاحتياطي `ELEVENLABS_API_KEY` إلا عندما لا يكون مفتاح API الخاص بـ Talk مُعدًّا. +- يتيح `providers.*.voiceAliases` لتوجيهات Talk استخدام أسماء سهلة. +- يتحكم `silenceTimeoutMs` في مدة انتظار وضع Talk بعد صمت المستخدم قبل إرسال النص المفرغ. وعند عدم تعيينه، تُستخدم نافذة التوقف الافتراضية الخاصة بالمنصة (`700 ms على macOS وAndroid، و900 ms على iOS`). --- @@ -2189,20 +2178,20 @@ scripts/sandbox-browser-setup.sh # optional browser image يضبط `tools.profile` قائمة سماح أساسية قبل `tools.allow`/`tools.deny`: -تضبط عملية onboarding المحلية الإعدادات المحلية الجديدة افتراضياً على `tools.profile: "coding"` عند عدم الضبط (مع الحفاظ على ملفات التعريف الصريحة الحالية). +تضبط عملية الإعداد المحلية الافتراضية للإعدادات المحلية الجديدة `tools.profile: "coding"` عندما لا يكون معينًا (وتُحفَظ ملفات التعريف الصريحة الحالية). -| ملف التعريف | يتضمن | +| ملف التعريف | يتضمن | | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | | `minimal` | `session_status` فقط | | `coding` | `group:fs` و`group:runtime` و`group:web` و`group:sessions` و`group:memory` و`cron` و`image` و`image_generate` و`video_generate` | | `messaging` | `group:messaging` و`sessions_list` و`sessions_history` و`sessions_send` و`session_status` | -| `full` | بلا تقييد (مثل عدم الضبط) | +| `full` | بلا قيود (مثل عدم التعيين) | ### مجموعات الأدوات -| المجموعة | الأدوات | +| المجموعة | الأدوات | | ------------------ | ----------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec` و`process` و`code_execution` ‏(`bash` مقبول كاسم بديل لـ `exec`) | +| `group:runtime` | `exec` و`process` و`code_execution` (`bash` مقبول كاسم بديل لـ `exec`) | | `group:fs` | `read` و`write` و`edit` و`apply_patch` | | `group:sessions` | `sessions_list` و`sessions_history` و`sessions_send` و`sessions_spawn` و`sessions_yield` و`subagents` و`session_status` | | `group:memory` | `memory_search` و`memory_get` | @@ -2213,11 +2202,11 @@ scripts/sandbox-browser-setup.sh # optional browser image | `group:nodes` | `nodes` | | `group:agents` | `agents_list` | | `group:media` | `image` و`image_generate` و`video_generate` و`tts` | -| `group:openclaw` | جميع الأدوات المدمجة (باستثناء إضافات الموفّر) | +| `group:openclaw` | جميع الأدوات المضمنة (باستثناء Plugin الخاصة بالمزوّد) | ### `tools.allow` / `tools.deny` -سياسة السماح/الرفض العامة للأدوات (الرفض يفوز). غير حساسة لحالة الأحرف، وتدعم محارف البدل `*`. وتُطبّق حتى عندما يكون Docker sandbox معطلاً. +سياسة السماح/المنع العامة للأدوات (المنع يفوز). غير حساسة لحالة الأحرف، وتدعم أحرف البدل `*`. وتُطبَّق حتى عندما يكون Docker sandbox معطّلًا. ```json5 { @@ -2227,7 +2216,7 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.byProvider` -تقيّد الأدوات أكثر لموفّرين أو نماذج محددة. الترتيب: ملف التعريف الأساسي → ملف تعريف الموفّر → السماح/الرفض. +تقييد إضافي للأدوات لمزوّدين أو نماذج محددة. الترتيب: ملف التعريف الأساسي → ملف تعريف المزوّد → السماح/المنع. ```json5 { @@ -2243,7 +2232,7 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.elevated` -يتحكم في وصول exec المرتفع خارج Sandbox: +يتحكم في وصول `exec` المرتفع خارج sandbox: ```json5 { @@ -2259,9 +2248,9 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- لا يمكن للتجاوز لكل وكيل (`agents.list[].tools.elevated`) إلا أن يفرض مزيداً من التقييد. -- يخزّن `/elevated on|off|ask|full` الحالة لكل جلسة؛ بينما تنطبق التوجيهات المضمنة على رسالة واحدة. -- يتجاوز `exec` المرتفع العزل ويستخدم مسار الهروب المضبوط (`gateway` افتراضياً، أو `node` عندما يكون هدف exec هو `node`). +- لا يمكن لتجاوز كل وكيل (`agents.list[].tools.elevated`) إلا أن يضيف مزيدًا من التقييد. +- يخزن `/elevated on|off|ask|full` الحالة لكل جلسة؛ وتُطبَّق التوجيهات المضمنة على رسالة واحدة فقط. +- يتجاوز `exec` المرتفع العزل في sandbox ويستخدم مسار الهروب المهيأ (`gateway` افتراضيًا، أو `node` عندما يكون هدف exec هو `node`). ### `tools.exec` @@ -2285,8 +2274,8 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.loopDetection` -فحوصات الأمان الخاصة بحلقات الأدوات تكون **معطلة افتراضياً**. اضبط `enabled: true` لتفعيل الاكتشاف. -يمكن تعريف الإعدادات على المستوى العام في `tools.loopDetection` وتجاوزها لكل وكيل في `agents.list[].tools.loopDetection`. +تكون فحوصات أمان حلقات الأدوات **معطلة افتراضيًا**. عيّن `enabled: true` لتفعيل الاكتشاف. +يمكن تعريف الإعدادات عالميًا في `tools.loopDetection` وتجاوزها لكل وكيل في `agents.list[].tools.loopDetection`. ```json5 { @@ -2307,14 +2296,14 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `historySize`: الحد الأقصى لسجل استدعاءات الأدوات المحتفَظ به لتحليل الحلقات. -- `warningThreshold`: عتبة نمط التكرار من دون تقدم لإطلاق التحذيرات. -- `criticalThreshold`: عتبة تكرار أعلى لحظر الحلقات الحرجة. -- `globalCircuitBreakerThreshold`: عتبة إيقاف صارمة لأي تشغيل من دون تقدم. -- `detectors.genericRepeat`: التحذير من تكرار استدعاءات الأداة نفسها/الوسائط نفسها. -- `detectors.knownPollNoProgress`: التحذير/الحظر لأدوات الاستطلاع المعروفة (`process.poll` و`command_status` وما إلى ذلك). -- `detectors.pingPong`: التحذير/الحظر لأنماط الأزواج المتناوبة من دون تقدم. -- إذا كانت `warningThreshold >= criticalThreshold` أو `criticalThreshold >= globalCircuitBreakerThreshold`، يفشل التحقق. +- `historySize`: الحد الأقصى لسجل استدعاءات الأدوات المحتفظ به لتحليل الحلقات. +- `warningThreshold`: حد نمط التكرار بلا تقدم لإصدار التحذيرات. +- `criticalThreshold`: حد تكرار أعلى لحظر الحلقات الحرجة. +- `globalCircuitBreakerThreshold`: حد إيقاف صارم لأي تشغيل بلا تقدم. +- `detectors.genericRepeat`: يحذر من الاستدعاءات المتكررة للأداة نفسها/المعاملات نفسها. +- `detectors.knownPollNoProgress`: يحذر/يحظر أدوات الاستطلاع المعروفة (`process.poll` و`command_status` وما إلى ذلك). +- `detectors.pingPong`: يحذر/يحظر أنماط الأزواج المتناوبة بلا تقدم. +- إذا كان `warningThreshold >= criticalThreshold` أو `criticalThreshold >= globalCircuitBreakerThreshold`، يفشل التحقق. ### `tools.web` @@ -2324,14 +2313,14 @@ scripts/sandbox-browser-setup.sh # optional browser image web: { search: { enabled: true, - apiKey: "brave_api_key", // or BRAVE_API_KEY env + apiKey: "brave_api_key", // أو BRAVE_API_KEY في البيئة maxResults: 5, timeoutSeconds: 30, cacheTtlMinutes: 15, }, fetch: { enabled: true, - provider: "firecrawl", // optional; omit for auto-detect + provider: "firecrawl", // اختياري؛ احذفه للاكتشاف التلقائي maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2348,7 +2337,7 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.media` -يضبط فهم الوسائط الواردة (الصورة/الصوت/الفيديو): +يضبط فهم الوسائط الواردة (صورة/صوت/فيديو): ```json5 { @@ -2356,7 +2345,7 @@ scripts/sandbox-browser-setup.sh # optional browser image media: { concurrency: 2, asyncCompletion: { - directSend: false, // opt-in: send finished async music/video directly to the channel + directSend: false, // تفعيل اختياري: أرسل الموسيقى/الفيديو غير المتزامنين المكتملين مباشرة إلى القناة }, audio: { enabled: true, @@ -2382,30 +2371,30 @@ scripts/sandbox-browser-setup.sh # optional browser image -**إدخال الموفّر** (`type: "provider"` أو عند الحذف): +**إدخال المزوّد** (`type: "provider"` أو عند الحذف): -- `provider`: معرّف موفّر API ‏(`openai` أو `anthropic` أو `google`/`gemini` أو `groq`، وما إلى ذلك) +- `provider`: معرّف مزوّد API ‏(`openai` أو `anthropic` أو `google`/`gemini` أو `groq` وما إلى ذلك) - `model`: تجاوز معرّف النموذج -- `profile` / `preferredProfile`: اختيار ملف `auth-profiles.json` +- `profile` / `preferredProfile`: اختيار ملف تعريف من `auth-profiles.json` **إدخال CLI** (`type: "cli"`): - `command`: الملف التنفيذي المطلوب تشغيله -- `args`: وسائط قالبية (تدعم `{{MediaPath}}` و`{{Prompt}}` و`{{MaxChars}}`، وما إلى ذلك) +- `args`: معاملات ذات قوالب (تدعم `{{MediaPath}}` و`{{Prompt}}` و`{{MaxChars}}` وما إلى ذلك) -**الحقول المشتركة:** +**حقول مشتركة:** -- `capabilities`: قائمة اختيارية (`image` و`audio` و`video`). القيم الافتراضية: `openai`/`anthropic`/`minimax` → صورة، و`google` → صورة+صوت+فيديو، و`groq` → صوت. +- `capabilities`: قائمة اختيارية (`image` أو `audio` أو `video`). القيم الافتراضية: `openai`/`anthropic`/`minimax` ← صورة، و`google` ← صورة+صوت+فيديو، و`groq` ← صوت. - `prompt` و`maxChars` و`maxBytes` و`timeoutSeconds` و`language`: تجاوزات لكل إدخال. -- تعود حالات الفشل إلى الإدخال التالي. +- تؤدي الإخفاقات إلى الرجوع إلى الإدخال التالي. -تتبع مصادقة الموفّر الترتيب القياسي: `auth-profiles.json` → متغيرات البيئة → `models.providers.*.apiKey`. +تتبع مصادقة المزوّد الترتيب القياسي: `auth-profiles.json` → متغيرات البيئة → `models.providers.*.apiKey`. **حقول الإكمال غير المتزامن:** -- `asyncCompletion.directSend`: عند ضبطه على `true`، تحاول مهام - `music_generate` و`video_generate` غير المتزامنة المكتملة التسليم المباشر إلى القناة أولاً. الافتراضي: `false` - (مسار التنبيه/تسليم النموذج القديم لجلسة الطالب). +- `asyncCompletion.directSend`: عند تعيينه إلى `true`، تحاول مهام + `music_generate` و`video_generate` غير المتزامنة المكتملة التسليم المباشر إلى القناة أولًا. الافتراضي: `false` + (مسار wake/model-delivery القديم المعتمد على جلسة الطالب). @@ -2424,9 +2413,9 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.sessions` -يتحكم في الجلسات التي يمكن استهدافها بواسطة أدوات الجلسات (`sessions_list` و`sessions_history` و`sessions_send`). +يتحكم في الجلسات التي يمكن استهدافها بواسطة أدوات الجلسة (`sessions_list` و`sessions_history` و`sessions_send`). -الافتراضي: `tree` ‏(الجلسة الحالية + الجلسات التي أنشأتها، مثل الوكلاء الفرعيين). +الافتراضي: `tree` (الجلسة الحالية + الجلسات التي أنشأتها، مثل الوكلاء الفرعيين). ```json5 { @@ -2443,9 +2432,9 @@ scripts/sandbox-browser-setup.sh # optional browser image - `self`: مفتاح الجلسة الحالية فقط. - `tree`: الجلسة الحالية + الجلسات التي أنشأتها الجلسة الحالية (الوكلاء الفرعيون). -- `agent`: أي جلسة تنتمي إلى معرّف الوكيل الحالي (قد يشمل مستخدمين آخرين إذا كنت تشغّل جلسات لكل مرسل تحت معرّف الوكيل نفسه). -- `all`: أي جلسة. وما زال الاستهداف عبر الوكلاء يتطلب `tools.agentToAgent`. -- قيد Sandbox: عندما تكون الجلسة الحالية داخل Sandbox وتكون `agents.defaults.sandbox.sessionToolsVisibility="spawned"`، تُفرض القيمة `tree` على الرؤية حتى لو كانت `tools.sessions.visibility="all"`. +- `agent`: أي جلسة تنتمي إلى معرّف الوكيل الحالي (وقد يشمل ذلك مستخدمين آخرين إذا كنت تستخدم جلسات per-sender تحت معرّف الوكيل نفسه). +- `all`: أي جلسة. وما يزال الاستهداف عبر الوكلاء يتطلب `tools.agentToAgent`. +- تقييد sandbox: عندما تكون الجلسة الحالية داخل sandbox ويكون `agents.defaults.sandbox.sessionToolsVisibility="spawned"`، تُفرض القيمة `tree` على مستوى الرؤية حتى لو كان `tools.sessions.visibility="all"`. ### `tools.sessions_spawn` @@ -2456,11 +2445,11 @@ scripts/sandbox-browser-setup.sh # optional browser image tools: { sessions_spawn: { attachments: { - enabled: false, // opt-in: set true to allow inline file attachments - maxTotalBytes: 5242880, // 5 MB total across all files + enabled: false, // تفعيل اختياري: عيّنه إلى true للسماح بمرفقات ملفات مضمنة + maxTotalBytes: 5242880, // 5 MB إجمالًا عبر جميع الملفات maxFiles: 50, - maxFileBytes: 1048576, // 1 MB per file - retainOnSessionKeep: false, // keep attachments when cleanup="keep" + maxFileBytes: 1048576, // 1 MB لكل ملف + retainOnSessionKeep: false, // الاحتفاظ بالمرفقات عندما يكون cleanup="keep" }, }, }, @@ -2469,22 +2458,22 @@ scripts/sandbox-browser-setup.sh # optional browser image ملاحظات: -- المرفقات مدعومة فقط لـ `runtime: "subagent"`. ويرفض وقت تشغيل ACP هذه المرفقات. -- تُجسّد الملفات في مساحة العمل الفرعية عند `.openclaw/attachments//` مع ملف `.manifest.json`. -- يُحجب محتوى المرفقات تلقائياً من حفظ transcript. -- يتم التحقق من مدخلات Base64 بفحوصات صارمة للأبجدية/الحشو مع حاجز لحجم ما قبل فك الترميز. -- تكون أذونات الملفات `0700` للأدلة و`0600` للملفات. -- يتبع التنظيف سياسة `cleanup`: حيث يؤدي `delete` دائماً إلى إزالة المرفقات؛ بينما يحتفظ `keep` بها فقط عندما تكون `retainOnSessionKeep: true`. +- لا تُدعَم المرفقات إلا مع `runtime: "subagent"`. ويرفض وقت تشغيل ACP هذه المرفقات. +- تُحوَّل الملفات إلى مساحة عمل الابن في `.openclaw/attachments//` مع `.manifest.json`. +- يُحجَب محتوى المرفقات تلقائيًا من حفظ السجل. +- تُتحقق مدخلات Base64 باستخدام فحوص صارمة للأبجدية/الحشو وحارس حجم قبل فك الترميز. +- تكون صلاحيات الملفات `0700` للأدلة و`0600` للملفات. +- يتبع التنظيف سياسة `cleanup`: يزيل `delete` المرفقات دائمًا؛ بينما يحتفظ `keep` بها فقط عندما يكون `retainOnSessionKeep: true`. ### `tools.experimental` -إشارات الأدوات المدمجة التجريبية. تكون معطلة افتراضياً ما لم تُطبّق قاعدة تمكين تلقائي صارمة للوكيل في GPT-5. +أعلام الأدوات المضمنة التجريبية. تكون معطلة افتراضيًا ما لم تنطبق قاعدة تفعيل تلقائي صارمة لوضع GPT-5 الوكيلي. ```json5 { tools: { experimental: { - planTool: true, // enable experimental update_plan + planTool: true, // تفعيل update_plan التجريبية }, }, } @@ -2492,9 +2481,9 @@ scripts/sandbox-browser-setup.sh # optional browser image ملاحظات: -- `planTool`: يفعّل أداة `update_plan` المهيكلة التجريبية لتتبع الأعمال غير البسيطة متعددة الخطوات. -- الافتراضي: `false` ما لم تكن `agents.defaults.embeddedPi.executionContract` ‏(أو تجاوز لكل وكيل) مضبوطة على `"strict-agentic"` لتشغيل OpenAI أو OpenAI Codex من عائلة GPT-5. اضبط `true` لفرض تشغيل الأداة خارج هذا النطاق، أو `false` لإبقائها معطلة حتى في تشغيلات GPT-5 الصارمة الوكيلية. -- عند التفعيل، يضيف system prompt أيضاً إرشادات استخدام حتى لا يستخدمها النموذج إلا للأعمال الجوهرية، مع الإبقاء على خطوة واحدة فقط بحالة `in_progress` كحد أقصى. +- `planTool`: يفعّل الأداة المهيكلة `update_plan` لتتبع العمل غير البسيط متعدد الخطوات. +- الافتراضي: `false` ما لم تكن `agents.defaults.embeddedPi.executionContract` (أو تجاوز لكل وكيل) مضبوطة على `"strict-agentic"` في تشغيل OpenAI أو OpenAI Codex من عائلة GPT-5. عيّنه إلى `true` لفرض تشغيل الأداة خارج ذلك النطاق، أو إلى `false` لإبقائها معطلة حتى في تشغيلات GPT-5 الصارمة الوكيلية. +- عند التفعيل، تضيف system prompt أيضًا إرشادات استخدام بحيث يستخدمها النموذج فقط للأعمال الكبيرة ويحافظ على خطوة واحدة فقط كحد أقصى في حالة `in_progress`. ### `agents.defaults.subagents` @@ -2514,21 +2503,21 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `model`: النموذج الافتراضي للوكلاء الفرعيين المنشأين. وإذا حُذف، يرث الوكلاء الفرعيون نموذج المستدعي. -- `allowAgents`: قائمة السماح الافتراضية لمعرّفات الوكلاء الهدف لـ `sessions_spawn` عندما لا يضبط وكيل الطالب قيمة `subagents.allowAgents` الخاصة به (`["*"]` = أي وكيل؛ والافتراضي: الوكيل نفسه فقط). +- `model`: النموذج الافتراضي للوكلاء الفرعيين الذين تم إنشاؤهم. وإذا حُذف، يرث الوكلاء الفرعيون نموذج المستدعي. +- `allowAgents`: قائمة السماح الافتراضية لمعرّفات الوكلاء المستهدفة في `sessions_spawn` عندما لا يعيّن الوكيل الطالب قيمة `subagents.allowAgents` الخاصة به (`["*"]` = أي وكيل؛ الافتراضي: الوكيل نفسه فقط). - `runTimeoutSeconds`: المهلة الافتراضية (بالثواني) لـ `sessions_spawn` عندما يحذف استدعاء الأداة `runTimeoutSeconds`. وتعني `0` عدم وجود مهلة. - سياسة الأدوات لكل وكيل فرعي: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- -## الموفّرون المخصصون وعناوين URL الأساسية +## المزوّدون المخصصون وعناوين URL الأساسية -يستخدم OpenClaw فهرس النماذج المدمج. أضف موفّرين مخصصين عبر `models.providers` في الإعدادات أو `~/.openclaw/agents//agent/models.json`. +يستخدم OpenClaw فهرس النماذج المضمن. أضف مزوّدين مخصصين عبر `models.providers` في الإعدادات أو `~/.openclaw/agents//agent/models.json`. ```json5 { models: { - mode: "merge", // merge (default) | replace + mode: "merge", // merge (الافتراضي) | replace providers: { "custom-proxy": { baseUrl: "http://localhost:4000/v1", @@ -2553,49 +2542,49 @@ scripts/sandbox-browser-setup.sh # optional browser image ``` - استخدم `authHeader: true` + `headers` لاحتياجات المصادقة المخصصة. -- تجاوز جذر إعدادات الوكيل عبر `OPENCLAW_AGENT_DIR` ‏(أو `PI_CODING_AGENT_DIR`، وهو اسم بديل قديم لمتغير بيئة). -- أسبقية الدمج لمعرّفات الموفّرين المتطابقة: +- تجاوز جذر إعداد الوكيل باستخدام `OPENCLAW_AGENT_DIR` (أو `PI_CODING_AGENT_DIR`، وهو اسم قديم بديل لمتغير البيئة). +- أولوية الدمج لمعرّفات المزوّد المطابقة: - تفوز قيم `baseUrl` غير الفارغة في `models.json` الخاصة بالوكيل. - - تفوز قيم `apiKey` غير الفارغة الخاصة بالوكيل فقط عندما لا يكون ذلك الموفّر مُداراً عبر SecretRef في سياق الإعدادات/ملف المصادقة الحالي. - - تُحدَّث قيم `apiKey` الخاصة بالموفّرين المُدارين عبر SecretRef من علامات المصدر (`ENV_VAR_NAME` لمراجع البيئة، و`secretref-managed` لمراجع الملف/exec) بدلاً من حفظ الأسرار المحلولة. - - تُحدَّث قيم رؤوس الموفّرين المُدارة عبر SecretRef من علامات المصدر (`secretref-env:ENV_VAR_NAME` لمراجع البيئة، و`secretref-managed` لمراجع الملف/exec). - - تعود قيم `apiKey`/`baseUrl` الفارغة أو المفقودة الخاصة بالوكيل إلى `models.providers` في الإعدادات. - - تستخدم القيم المتطابقة للنموذج `contextWindow`/`maxTokens` القيمة الأعلى بين الإعدادات الصريحة وقيم الفهرس الضمنية. - - يحافظ `contextTokens` للنموذج المتطابق على حد وقت تشغيل صريح عند وجوده؛ استخدمه لتقييد السياق الفعلي من دون تغيير بيانات النموذج الأصلية. - - استخدم `models.mode: "replace"` عندما تريد أن تعيد الإعدادات كتابة `models.json` بالكامل. - - حفظ العلامات يعتمد على المصدر بوصفه صاحب الحقيقة: تُكتب العلامات من لقطة إعدادات المصدر النشطة (قبل الحل)، وليس من قيم الأسرار المحلولة وقت التشغيل. + - تفوز قيم `apiKey` غير الفارغة الخاصة بالوكيل فقط عندما لا يكون ذلك المزوّد مُدارًا بواسطة SecretRef في سياق الإعداد/ملف تعريف المصادقة الحالي. + - تُحدَّث قيم `apiKey` الخاصة بالمزوّد المُدار بواسطة SecretRef من علامات المصدر (`ENV_VAR_NAME` لإحالات البيئة، و`secretref-managed` لإحالات الملف/التنفيذ) بدلًا من حفظ الأسرار المحلولة. + - تُحدَّث قيم الرؤوس الخاصة بالمزوّد المُدار بواسطة SecretRef من علامات المصدر (`secretref-env:ENV_VAR_NAME` لإحالات البيئة، و`secretref-managed` لإحالات الملف/التنفيذ). + - تعود القيم الفارغة أو المفقودة لـ `apiKey`/`baseUrl` الخاصة بالوكيل إلى `models.providers` في الإعدادات. + - تستخدم القيم المطابقة `contextWindow`/`maxTokens` للنموذج القيمة الأعلى بين الإعداد الصريح وقيم الفهرس الضمنية. + - تحافظ القيم المطابقة `contextTokens` للنموذج على حد تشغيل صريح عندما يكون موجودًا؛ استخدمه لتقييد السياق الفعلي دون تغيير بيانات التعريف الأصلية للنموذج. + - استخدم `models.mode: "replace"` عندما تريد من الإعدادات إعادة كتابة `models.json` بالكامل. + - يكون حفظ العلامات معتمدًا على المصدر: تُكتب العلامات من لقطة إعداد المصدر النشطة (قبل الحل)، وليس من قيم الأسرار المحلولة أثناء التشغيل. -### تفاصيل حقول الموفّر +### تفاصيل حقول المزوّد -- `models.mode`: سلوك فهرس الموفّرين (`merge` أو `replace`). -- `models.providers`: خريطة الموفّرين المخصصين مفهرسة بحسب معرّف الموفّر. -- `models.providers.*.api`: محوّل الطلبات (`openai-completions` أو `openai-responses` أو `anthropic-messages` أو `google-generative-ai`، وما إلى ذلك). -- `models.providers.*.apiKey`: بيانات اعتماد الموفّر (ويُفضَّل استخدام SecretRef/الاستبدال عبر البيئة). +- `models.mode`: سلوك فهرس المزوّد (`merge` أو `replace`). +- `models.providers`: خريطة مزوّدين مخصصين مفهرسة بمعرّف المزوّد. +- `models.providers.*.api`: مهايئ الطلب (`openai-completions` أو `openai-responses` أو `anthropic-messages` أو `google-generative-ai` وما إلى ذلك). +- `models.providers.*.apiKey`: بيانات اعتماد المزوّد (يُفضّل SecretRef/الاستبدال من البيئة). - `models.providers.*.auth`: استراتيجية المصادقة (`api-key` أو `token` أو `oauth` أو `aws-sdk`). - `models.providers.*.injectNumCtxForOpenAICompat`: بالنسبة إلى Ollama + `openai-completions`، يحقن `options.num_ctx` في الطلبات (الافتراضي: `true`). - `models.providers.*.authHeader`: يفرض نقل بيانات الاعتماد في رأس `Authorization` عند الحاجة. -- `models.providers.*.baseUrl`: عنوان URL الأساسي لـ API المصدر. -- `models.providers.*.headers`: رؤوس ثابتة إضافية لتوجيه proxy/المستأجر. -- `models.providers.*.request`: تجاوزات النقل لطلبات HTTP الخاصة بموفّر النموذج. - - `request.headers`: رؤوس إضافية (تُدمج مع القيم الافتراضية للموفّر). وتقبل القيم SecretRef. - - `request.auth`: تجاوز استراتيجية المصادقة. الأوضاع: `"provider-default"` ‏(استخدام المصادقة المدمجة للموفّر)، و`"authorization-bearer"` ‏(مع `token`)، و`"header"` ‏(مع `headerName` و`value` و`prefix` الاختياري). - - `request.proxy`: تجاوز HTTP proxy. الأوضاع: `"env-proxy"` ‏(استخدام متغيرات البيئة `HTTP_PROXY`/`HTTPS_PROXY`) و`"explicit-proxy"` ‏(مع `url`). ويقبل الوضعان كائناً فرعياً اختيارياً `tls`. - - `request.tls`: تجاوز TLS للاتصالات المباشرة. الحقول: `ca` و`cert` و`key` و`passphrase` ‏(كلها تقبل SecretRef)، و`serverName` و`insecureSkipVerify`. - - `request.allowPrivateNetwork`: عند ضبطه على `true`، يسمح باتصالات HTTPS إلى `baseUrl` عندما يُحل DNS إلى نطاقات خاصة أو CGNAT أو نطاقات مشابهة، عبر حاجز جلب HTTP الخاص بالموفّر (اشتراك اختياري من المشغّل لنقاط نهاية OpenAI-compatible ذاتية الاستضافة الموثوقة). ويستخدم WebSocket الكائن `request` نفسه للرؤوس/TLS لكن ليس حاجز SSRF الخاص بالجلب. الافتراضي `false`. -- `models.providers.*.models`: إدخالات فهرس النماذج الصريحة الخاصة بالموفّر. -- `models.providers.*.models.*.contextWindow`: بيانات وصفية لنافذة سياق النموذج الأصلية. -- `models.providers.*.models.*.contextTokens`: حد سياق اختياري لوقت التشغيل. استخدمه عندما تريد ميزانية سياق فعلية أصغر من `contextWindow` الأصلية للنموذج. -- `models.providers.*.models.*.compat.supportsDeveloperRole`: تلميح توافق اختياري. بالنسبة إلى `api: "openai-completions"` مع `baseUrl` غير أصلي وغير فارغ (`host` ليس `api.openai.com`)، يفرض OpenClaw هذه القيمة إلى `false` وقت التشغيل. بينما يُبقي `baseUrl` الفارغ/المحذوف سلوك OpenAI الافتراضي. -- `models.providers.*.models.*.compat.requiresStringContent`: تلميح توافق اختياري لنقاط نهاية الدردشة OpenAI-compatible التي تقبل النصوص فقط. وعند ضبطه على `true`، يقوم OpenClaw بتسطيح مصفوفات `messages[].content` النصية البحتة إلى سلاسل نصية عادية قبل إرسال الطلب. +- `models.providers.*.baseUrl`: عنوان URL الأساسي لواجهة API في المصدر. +- `models.providers.*.headers`: رؤوس ثابتة إضافية لتوجيه الوكيل/المستأجر. +- `models.providers.*.request`: تجاوزات النقل لطلبات HTTP الخاصة بمزوّد النموذج. + - `request.headers`: رؤوس إضافية (تُدمج مع القيم الافتراضية للمزوّد). وتقبل القيم SecretRef. + - `request.auth`: تجاوز استراتيجية المصادقة. الأوضاع: `"provider-default"` (استخدام المصادقة المضمنة الخاصة بالمزوّد)، و`"authorization-bearer"` (مع `token`)، و`"header"` (مع `headerName` و`value` و`prefix` الاختياري). + - `request.proxy`: تجاوز وكيل HTTP. الأوضاع: `"env-proxy"` (استخدام متغيرات البيئة `HTTP_PROXY`/`HTTPS_PROXY`)، و`"explicit-proxy"` (مع `url`). ويقبل كلا الوضعين كائنًا فرعيًا اختياريًا `tls`. + - `request.tls`: تجاوز TLS للاتصالات المباشرة. الحقول: `ca` و`cert` و`key` و`passphrase` (كلها تقبل SecretRef) و`serverName` و`insecureSkipVerify`. + - `request.allowPrivateNetwork`: عند تعيينه إلى `true`، يسمح باتصالات HTTPS إلى `baseUrl` عندما يُحل DNS إلى نطاقات خاصة أو CGNAT أو نطاقات مشابهة، عبر حارس جلب HTTP الخاص بالمزوّد (تفعيل اختياري للمشغّل لنقاط النهاية المتوافقة مع OpenAI والمستضافة ذاتيًا والموثوق بها). وتستخدم WebSocket الكائن `request` نفسه للرؤوس/TLS ولكن ليس بوابة SSRF الخاصة بالجلب. الافتراضي `false`. +- `models.providers.*.models`: إدخالات صريحة لفهرس نماذج المزوّد. +- `models.providers.*.models.*.contextWindow`: بيانات تعريف نافذة السياق الأصلية للنموذج. +- `models.providers.*.models.*.contextTokens`: حد سياق اختياري أثناء التشغيل. استخدمه عندما تريد ميزانية سياق فعلية أصغر من `contextWindow` الأصلية للنموذج. +- `models.providers.*.models.*.compat.supportsDeveloperRole`: تلميح توافق اختياري. بالنسبة إلى `api: "openai-completions"` مع `baseUrl` غير فارغ وغير أصلي (المستضيف ليس `api.openai.com`)، يفرض OpenClaw هذه القيمة إلى `false` أثناء التشغيل. أما `baseUrl` الفارغ/المحذوف فيبقي سلوك OpenAI الافتراضي. +- `models.providers.*.models.*.compat.requiresStringContent`: تلميح توافق اختياري لنقاط نهاية الدردشة المتوافقة مع OpenAI والتي تقبل السلاسل فقط. وعندما تكون `true`، يقوم OpenClaw بتسطيح مصفوفات `messages[].content` النصية الخالصة إلى سلاسل عادية قبل إرسال الطلب. - `plugins.entries.amazon-bedrock.config.discovery`: جذر إعدادات الاكتشاف التلقائي لـ Bedrock. - `plugins.entries.amazon-bedrock.config.discovery.enabled`: تشغيل/إيقاف الاكتشاف الضمني. - `plugins.entries.amazon-bedrock.config.discovery.region`: منطقة AWS للاكتشاف. -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: مرشح اختياري لمعرّف الموفّر من أجل اكتشاف موجّه. +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: مرشح اختياري لمعرّف المزوّد من أجل اكتشاف موجّه. - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: فاصل الاستطلاع لتحديث الاكتشاف. - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: نافذة السياق الاحتياطية للنماذج المكتشفة. -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: الحد الأقصى الاحتياطي لرموز الخرج للنماذج المكتشفة. +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: الحد الاحتياطي الأقصى لرموز المخرجات للنماذج المكتشفة. -### أمثلة على الموفّرين +### أمثلة على المزوّدين @@ -2631,7 +2620,7 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -استخدم `cerebras/zai-glm-4.7` مع Cerebras؛ واستخدم `zai/glm-4.7` مع Z.AI مباشرة. +استخدم `cerebras/zai-glm-4.7` مع Cerebras؛ واستخدم `zai/glm-4.7` مع Z.AI مباشرةً. @@ -2648,7 +2637,7 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -اضبط `OPENCODE_API_KEY` ‏(أو `OPENCODE_ZEN_API_KEY`). استخدم المراجع `opencode/...` لفهرس Zen أو المراجع `opencode-go/...` لفهرس Go. الاختصار: `openclaw onboard --auth-choice opencode-zen` أو `openclaw onboard --auth-choice opencode-go`. +عيّن `OPENCODE_API_KEY` (أو `OPENCODE_ZEN_API_KEY`). استخدم المراجع `opencode/...` لفهرس Zen أو المراجع `opencode-go/...` لفهرس Go. اختصار: `openclaw onboard --auth-choice opencode-zen` أو `openclaw onboard --auth-choice opencode-go`. @@ -2665,11 +2654,11 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -اضبط `ZAI_API_KEY`. ويُقبل كل من `z.ai/*` و`z-ai/*` كأسماء بديلة. الاختصار: `openclaw onboard --auth-choice zai-api-key`. +عيّن `ZAI_API_KEY`. وتُقبل `z.ai/*` و`z-ai/*` كأسماء مستعارة. اختصار: `openclaw onboard --auth-choice zai-api-key`. - نقطة النهاية العامة: `https://api.z.ai/api/paas/v4` - نقطة نهاية البرمجة (الافتراضية): `https://api.z.ai/api/coding/paas/v4` -- بالنسبة إلى نقطة النهاية العامة، عرّف موفّراً مخصصاً مع تجاوز `baseUrl`. +- بالنسبة إلى نقطة النهاية العامة، عرّف مزودًا مخصصًا مع تجاوز `baseUrl`. @@ -2708,11 +2697,11 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -بالنسبة إلى نقطة نهاية الصين: `baseUrl: "https://api.moonshot.cn/v1"` أو `openclaw onboard --auth-choice moonshot-api-key-cn`. +بالنسبة إلى نقطة النهاية في الصين: `baseUrl: "https://api.moonshot.cn/v1"` أو `openclaw onboard --auth-choice moonshot-api-key-cn`. -تعلن نقاط نهاية Moonshot الأصلية توافق استخدام البث على النقل المشترك +تعلن نقاط النهاية الأصلية لـ Moonshot عن توافق استخدام البث على النقل المشترك `openai-completions`، ويعتمد OpenClaw في ذلك على قدرات نقطة النهاية -وليس على معرّف الموفّر المدمج وحده. +وليس على معرّف المزوّد المضمن وحده. @@ -2730,7 +2719,7 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -متوافق مع Anthropic، وهو موفّر مدمج. الاختصار: `openclaw onboard --auth-choice kimi-code-api-key`. +متوافق مع Anthropic، ومزوّد مضمن. اختصار: `openclaw onboard --auth-choice kimi-code-api-key`. @@ -2769,11 +2758,11 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -يجب أن يحذف `baseUrl` المسار `/v1` ‏(لأن عميل Anthropic يضيفه). الاختصار: `openclaw onboard --auth-choice synthetic-api-key`. +يجب أن يحذف عنوان URL الأساسي `/v1` (لأن عميل Anthropic يضيفه). اختصار: `openclaw onboard --auth-choice synthetic-api-key`. - + ```json5 { @@ -2809,12 +2798,12 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -اضبط `MINIMAX_API_KEY`. الاختصارات: +عيّن `MINIMAX_API_KEY`. الاختصارات: `openclaw onboard --auth-choice minimax-global-api` أو `openclaw onboard --auth-choice minimax-cn-api`. يفترض فهرس النماذج القيمة M2.7 فقط. في مسار البث المتوافق مع Anthropic، يعطّل OpenClaw التفكير في MiniMax -افتراضياً ما لم تضبط `thinking` بنفسك صراحةً. ويعيد `/fast on` أو +افتراضيًا ما لم تعيّن `thinking` بنفسك صراحةً. ويعيد `/fast on` أو `params.fastMode: true` كتابة `MiniMax-M2.7` إلى `MiniMax-M2.7-highspeed`. @@ -2822,7 +2811,7 @@ scripts/sandbox-browser-setup.sh # optional browser image -راجع [النماذج المحلية](/ar/gateway/local-models). باختصار: شغّل نموذجاً محلياً كبيراً عبر LM Studio Responses API على عتاد قوي؛ واحتفظ بالنماذج المستضافة مدمجة كاحتياط. +راجع [Local Models](/ar/gateway/local-models). باختصار: شغّل نموذجًا محليًا كبيرًا عبر LM Studio Responses API على عتاد قوي؛ وأبقِ النماذج المستضافة مدمجة من أجل الاحتياط. @@ -2843,7 +2832,7 @@ scripts/sandbox-browser-setup.sh # optional browser image }, entries: { "image-lab": { - apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string + apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // أو سلسلة نصية صريحة env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, @@ -2853,18 +2842,18 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `allowBundled`: قائمة سماح اختيارية لـ Skills المضمّنة فقط (ولا تتأثر Skills المُدارة/الخاصة بمساحة العمل). -- `load.extraDirs`: جذور Skills مشتركة إضافية (أدنى أسبقية). -- `install.preferBrew`: عند ضبطه على true، يفضّل مثبّتات Homebrew عندما تكون `brew` متاحة - قبل الرجوع إلى أنواع المثبّتات الأخرى. -- `install.nodeManager`: تفضيل مثبّت Node لمواصفات `metadata.openclaw.install` +- `allowBundled`: قائمة سماح اختيارية لـ Skills المضمنة فقط (ولا تتأثر Skills المُدارة/الخاصة بمساحة العمل). +- `load.extraDirs`: جذور Skills مشتركة إضافية (أدنى أولوية). +- `install.preferBrew`: عند تعيينه إلى true، يفضّل أدوات التثبيت عبر Homebrew عندما يكون `brew` + متاحًا قبل الرجوع إلى أنواع أدوات التثبيت الأخرى. +- `install.nodeManager`: تفضيل مُثبّت Node لمواصفات `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). - يؤدي `entries..enabled: false` إلى تعطيل Skill حتى لو كانت مضمّنة/مثبّتة. -- `entries..apiKey`: وسيلة مريحة لـ Skills التي تعرّف متغير بيئة أساسي (سلسلة نصية صريحة أو كائن SecretRef). +- `entries..apiKey`: عنصر مناسب لـ Skills التي تعرّف متغير بيئة أساسيًا (سلسلة نصية صريحة أو كائن SecretRef). --- -## Plugin +## Plugins ```json5 { @@ -2889,46 +2878,46 @@ scripts/sandbox-browser-setup.sh # optional browser image ``` - يتم التحميل من `~/.openclaw/extensions` و`/.openclaw/extensions` بالإضافة إلى `plugins.load.paths`. -- يقبل الاكتشاف إضافات OpenClaw الأصلية بالإضافة إلى حزم Codex المتوافقة وحزم Claude، بما في ذلك حزم Claude ذات التخطيط الافتراضي من دون manifest. -- **تتطلب تغييرات الإعدادات إعادة تشغيل Gateway.** -- `allow`: قائمة سماح اختيارية (تُحمَّل فقط الإضافات المدرجة). ويفوز `deny`. -- `plugins.entries..apiKey`: حقل مريح لمفتاح API على مستوى Plugin (عندما يدعمه Plugin). +- يقبل الاكتشاف Plugin الأصلية لـ OpenClaw بالإضافة إلى حزم Codex المتوافقة وحزم Claude، بما في ذلك حزم Claude ذات التخطيط الافتراضي من دون manifest. +- **تتطلب تغييرات الإعدادات إعادة تشغيل gateway.** +- `allow`: قائمة سماح اختيارية (يتم تحميل Plugin المدرجة فقط). ويفوز `deny`. +- `plugins.entries..apiKey`: حقل مناسب لمفتاح API على مستوى Plugin (عندما يكون مدعومًا من Plugin). - `plugins.entries..env`: خريطة متغيرات بيئة ضمن نطاق Plugin. -- `plugins.entries..hooks.allowPromptInjection`: عندما تكون `false`، يمنع core الخطاف `before_prompt_build` ويتجاهل الحقول المعدِّلة للـ prompt من `before_agent_start` القديم، مع الحفاظ على `modelOverride` و`providerOverride` القديمين. وينطبق ذلك على خطافات Plugin الأصلية وأدلة الخطافات التي توفّرها الحزم المدعومة. -- `plugins.entries..subagent.allowModelOverride`: يثق صراحةً في هذا Plugin لطلب تجاوزات `provider` و`model` لكل تشغيل لتشغيلات الوكيل الفرعي في الخلفية. -- `plugins.entries..subagent.allowedModels`: قائمة سماح اختيارية للأهداف القياسية `provider/model` الخاصة بتجاوزات الوكيل الفرعي الموثوقة. استخدم `"*"` فقط عندما تريد عمداً السماح بأي نموذج. -- `plugins.entries..config`: كائن إعدادات يعرّفه Plugin (ويُتحقق منه عبر مخطط Plugin الأصلي لـ OpenClaw عند توفره). -- `plugins.entries.firecrawl.config.webFetch`: إعدادات موفّر جلب الويب Firecrawl. - - `apiKey`: مفتاح API الخاص بـ Firecrawl ‏(يقبل SecretRef). ويعود احتياطياً إلى `plugins.entries.firecrawl.config.webSearch.apiKey` أو `tools.web.fetch.firecrawl.apiKey` القديم أو متغير البيئة `FIRECRAWL_API_KEY`. - - `baseUrl`: عنوان API الأساسي لـ Firecrawl ‏(الافتراضي: `https://api.firecrawl.dev`). +- `plugins.entries..hooks.allowPromptInjection`: عندما تكون القيمة `false`، يحظر core الحدث `before_prompt_build` ويتجاهل الحقول القديمة المعدّلة لـ prompt من `before_agent_start`، مع الحفاظ على `modelOverride` و`providerOverride` القديمين. وينطبق ذلك على hooks الأصلية لـ Plugin وعلى أدلة hooks التي توفّرها الحزم المدعومة. +- `plugins.entries..subagent.allowModelOverride`: وثّق هذه Plugin صراحةً لطلب تجاوزات `provider` و`model` لكل تشغيل بالنسبة إلى تشغيلات الوكلاء الفرعيين في الخلفية. +- `plugins.entries..subagent.allowedModels`: قائمة سماح اختيارية لأهداف `provider/model` القانونية الخاصة بتجاوزات الوكلاء الفرعيين الموثوق بها. استخدم `"*"` فقط عندما تريد عمدًا السماح بأي نموذج. +- `plugins.entries..config`: كائن إعدادات معرّف من Plugin (ويُتحقق منه بواسطة مخطط Plugin الأصلي لـ OpenClaw عندما يكون متاحًا). +- `plugins.entries.firecrawl.config.webFetch`: إعدادات مزوّد Firecrawl لجلب الويب. + - `apiKey`: مفتاح API لـ Firecrawl (يقبل SecretRef). ويعود احتياطيًا إلى `plugins.entries.firecrawl.config.webSearch.apiKey` أو `tools.web.fetch.firecrawl.apiKey` القديم أو متغير البيئة `FIRECRAWL_API_KEY`. + - `baseUrl`: عنوان URL الأساسي لـ Firecrawl API (الافتراضي: `https://api.firecrawl.dev`). - `onlyMainContent`: استخراج المحتوى الرئيسي فقط من الصفحات (الافتراضي: `true`). - - `maxAgeMs`: الحد الأقصى لعمر الذاكرة المؤقتة بالميلي ثانية (الافتراضي: `172800000` / يومان). + - `maxAgeMs`: الحد الأقصى لعمر cache بالميلي ثانية (الافتراضي: `172800000` / يومان). - `timeoutSeconds`: مهلة طلب الكشط بالثواني (الافتراضي: `60`). -- `plugins.entries.xai.config.xSearch`: إعدادات xAI X Search ‏(بحث الويب Grok). - - `enabled`: تفعيل موفّر X Search. - - `model`: نموذج Grok المستخدم للبحث (مثل `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: إعدادات Dreaming الخاصة بالذاكرة. راجع [Dreaming](/ar/concepts/dreaming) لمعرفة المراحل والعتبات. +- `plugins.entries.xai.config.xSearch`: إعدادات xAI X Search ‏(بحث Grok على الويب). + - `enabled`: تفعيل مزوّد X Search. + - `model`: نموذج Grok المطلوب استخدامه للبحث (مثل `"grok-4-1-fast"`). +- `plugins.entries.memory-core.config.dreaming`: إعدادات Dreaming الخاصة بالذاكرة. راجع [Dreaming](/ar/concepts/dreaming) لمعرفة المراحل والحدود. - `enabled`: مفتاح Dreaming الرئيسي (الافتراضي `false`). - - `frequency`: وتيرة Cron لكل عملية Dreaming كاملة (`"0 3 * * *"` افتراضياً). - - سياسة المراحل والعتبات هي تفاصيل تنفيذية (وليست مفاتيح إعدادات موجهة للمستخدم). + - `frequency`: وتيرة Cron لكل عملية Dreaming كاملة (`"0 3 * * *"` افتراضيًا). + - سياسة المراحل والحدود هي تفاصيل تنفيذية (وليست مفاتيح إعدادات موجّهة للمستخدم). - يوجد إعداد الذاكرة الكامل في [مرجع إعدادات الذاكرة](/ar/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- يمكن أيضاً لإضافات حزم Claude المفعّلة أن تساهم في القيم الافتراضية المضمّنة لـ Pi من `settings.json`؛ ويطبّق OpenClaw هذه القيم كإعدادات وكيل مُنقّاة، وليس كتصحيحات إعدادات خام لـ OpenClaw. -- `plugins.slots.memory`: اختر معرّف Plugin الذاكرة النشط، أو `"none"` لتعطيل إضافات الذاكرة. -- `plugins.slots.contextEngine`: اختر معرّف Plugin لمحرك السياق النشط؛ ويكون الافتراضي `"legacy"` ما لم تثبت وتحدد محركاً آخر. -- `plugins.installs`: بيانات تعريف تثبيت يديرها CLI ويستخدمها `openclaw plugins update`. +- يمكن أيضًا لحزم Claude المفعّلة أن تساهم بقيم Pi افتراضية مضمنة من `settings.json`؛ ويطبّق OpenClaw هذه القيم كإعدادات وكيل منقّحة، وليس كتصحيحات خام لإعدادات OpenClaw. +- `plugins.slots.memory`: اختر معرّف Plugin الذاكرة النشطة، أو `"none"` لتعطيل Plugin الذاكرة. +- `plugins.slots.contextEngine`: اختر معرّف Plugin لمحرك السياق النشط؛ وتكون القيمة الافتراضية `"legacy"` ما لم تثبّت وتحدد محركًا آخر. +- `plugins.installs`: بيانات تعريف التثبيت التي يديرها CLI وتستخدمها `openclaw plugins update`. - تتضمن `source` و`spec` و`sourcePath` و`installPath` و`version` و`resolvedName` و`resolvedVersion` و`resolvedSpec` و`integrity` و`shasum` و`resolvedAt` و`installedAt`. - - تعامل مع `plugins.installs.*` بوصفها حالة مُدارة؛ وفضّل أوامر CLI على التعديلات اليدوية. + - تعامل مع `plugins.installs.*` على أنها حالة مُدارة؛ وفضّل أوامر CLI بدلًا من التعديلات اليدوية. راجع [Plugins](/ar/tools/plugin). --- -## Browser +## المتصفح ```json5 { @@ -2937,8 +2926,8 @@ scripts/sandbox-browser-setup.sh # optional browser image evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access - // allowPrivateNetwork: true, // legacy alias + // dangerouslyAllowPrivateNetwork: true, // فعّله فقط للوصول الموثوق إلى الشبكات الخاصة + // allowPrivateNetwork: true, // اسم بديل قديم // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, @@ -2965,28 +2954,28 @@ scripts/sandbox-browser-setup.sh # optional browser image ``` - يؤدي `evaluateEnabled: false` إلى تعطيل `act:evaluate` و`wait --fn`. -- يكون `ssrfPolicy.dangerouslyAllowPrivateNetwork` معطلاً عند عدم ضبطه، لذلك يبقى تنقل Browser صارماً افتراضياً. -- اضبط `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` فقط عندما تثق عمداً في تنقل Browser داخل الشبكة الخاصة. -- في الوضع الصارم، تخضع نقاط نهاية ملفات تعريف CDP البعيدة (`profiles.*.cdpUrl`) للحظر نفسه الخاص بالشبكات الخاصة أثناء فحوصات الوصول/الاكتشاف. -- يظل `ssrfPolicy.allowPrivateNetwork` مدعوماً كاسم بديل قديم. +- يكون `ssrfPolicy.dangerouslyAllowPrivateNetwork` معطّلًا عندما لا يُعيَّن، لذلك يبقى تنقل المتصفح صارمًا افتراضيًا. +- عيّن `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` فقط عندما تثق عمدًا في تنقل المتصفح عبر الشبكات الخاصة. +- في الوضع الصارم، تخضع نقاط نهاية ملفات تعريف CDP البعيدة (`profiles.*.cdpUrl`) لنفس حظر الشبكات الخاصة أثناء فحوصات الوصول/الاكتشاف. +- يظل `ssrfPolicy.allowPrivateNetwork` مدعومًا كاسم بديل قديم. - في الوضع الصارم، استخدم `ssrfPolicy.hostnameAllowlist` و`ssrfPolicy.allowedHostnames` للاستثناءات الصريحة. -- تكون ملفات التعريف البعيدة attach-only ‏(بدء/إيقاف/إعادة تعيين معطلة). -- يقبل `profiles.*.cdpUrl` القيم `http://` و`https://` و`ws://` و`wss://`. +- تكون ملفات التعريف البعيدة بنمط الإرفاق فقط (start/stop/reset معطّلة). +- تقبل `profiles.*.cdpUrl` القيم `http://` و`https://` و`ws://` و`wss://`. استخدم HTTP(S) عندما تريد أن يكتشف OpenClaw المسار `/json/version`؛ واستخدم WS(S) - عندما يوفّر لك المزوّد عنوان DevTools WebSocket مباشراً. -- تكون ملفات تعريف `existing-session` مخصصة للمضيف فقط وتستخدم Chrome MCP بدلاً من CDP. -- يمكن لملفات تعريف `existing-session` ضبط `userDataDir` لاستهداف - ملف تعريف محدد لمتصفح قائم على Chromium مثل Brave أو Edge. -- تحتفظ ملفات تعريف `existing-session` بقيود مسار Chrome MCP الحالية: - إجراءات معتمدة على اللقطة/المرجع بدلاً من الاستهداف عبر CSS selector، وخطافات رفع ملف واحد، - ومن دون تجاوزات لمهلة الحوارات، ومن دون `wait --load networkidle`، - أو `responsebody`، أو تصدير PDF، أو اعتراض التنزيل، أو الإجراءات الدفعية. -- تعيّن ملفات تعريف `openclaw` المحلية المُدارة القيمتين `cdpPort` و`cdpUrl` تلقائياً؛ ولا - تضبط `cdpUrl` صراحةً إلا لـ CDP البعيد. -- ترتيب الاكتشاف التلقائي: المتصفح الافتراضي إذا كان قائماً على Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. + عندما يوفّر لك مزوّدك عنوان DevTools WebSocket مباشرًا. +- تكون ملفات تعريف `existing-session` خاصة بالمستضيف فقط وتستخدم Chrome MCP بدلًا من CDP. +- يمكن لملفات تعريف `existing-session` تعيين `userDataDir` لاستهداف + ملف تعريف محدد لمتصفح مبني على Chromium مثل Brave أو Edge. +- تحتفظ ملفات تعريف `existing-session` بحدود مسار Chrome MCP الحالية: + إجراءات موجّهة باللقطات/المراجع بدلًا من الاستهداف بمحددات CSS، وخطافات رفع ملف واحد، + ومن دون تجاوزات مهلة الحوارات، ومن دون `wait --load networkidle`، ومن دون + `responsebody` أو تصدير PDF أو اعتراض التنزيل أو الإجراءات الدفعية. +- تعيّن ملفات تعريف `openclaw` المحلية المُدارة تلقائيًا `cdpPort` و`cdpUrl`؛ ولا + تعيّن `cdpUrl` صراحةً إلا لـ CDP البعيد. +- ترتيب الاكتشاف التلقائي: المتصفح الافتراضي إذا كان مبنيًا على Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. - خدمة التحكم: loopback فقط (المنفذ مشتق من `gateway.port`، والافتراضي `18791`). -- يضيف `extraArgs` إشارات تشغيل إضافية إلى بدء Chromium المحلي (على سبيل المثال - `--disable-gpu` أو تحديد حجم النافذة أو إشارات التصحيح). +- يضيف `extraArgs` رايات تشغيل إضافية إلى بدء Chromium المحلي (على سبيل المثال + `--disable-gpu` أو تحديد حجم النافذة أو رايات التصحيح). --- @@ -2998,14 +2987,14 @@ scripts/sandbox-browser-setup.sh # optional browser image seamColor: "#FF4500", assistant: { name: "OpenClaw", - avatar: "CB", // emoji, short text, image URL, or data URI + avatar: "CB", // emoji، أو نص قصير، أو عنوان URL لصورة، أو data URI }, }, } ``` - `seamColor`: لون التمييز لعناصر واجهة التطبيق الأصلية (مثل تلوين فقاعة Talk Mode، وما إلى ذلك). -- `assistant`: تجاوز هوية Control UI. ويعود احتياطياً إلى هوية الوكيل النشط. +- `assistant`: تجاوز هوية Control UI. ويعود احتياطيًا إلى هوية الوكيل النشط. --- @@ -3020,8 +3009,8 @@ scripts/sandbox-browser-setup.sh # optional browser image auth: { mode: "token", // none | token | password | trusted-proxy token: "your-token", - // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD - // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth + // password: "your-password", // أو OPENCLAW_GATEWAY_PASSWORD + // trustedProxy: { userHeader: "x-forwarded-user" }, // لوضع mode=trusted-proxy؛ راجع /gateway/trusted-proxy-auth allowTailscale: true, rateLimit: { maxAttempts: 10, @@ -3039,9 +3028,9 @@ scripts/sandbox-browser-setup.sh # optional browser image basePath: "/openclaw", // root: "dist/control-ui", // embedSandbox: "scripts", // strict | scripts | trusted - // allowExternalEmbedUrls: false, // dangerous: allow absolute external http(s) embed URLs - // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI - // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode + // allowExternalEmbedUrls: false, // خطير: السماح بعناوين embed خارجية مطلقة من نوع http(s) + // allowedOrigins: ["https://control.example.com"], // مطلوبة لواجهة Control UI غير loopback + // dangerouslyAllowHostHeaderOriginFallback: false, // وضع خطير للاعتماد على أصل Host-header // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -3052,12 +3041,12 @@ scripts/sandbox-browser-setup.sh # optional browser image // password: "your-password", }, trustedProxies: ["10.0.0.1"], - // Optional. Default false. + // اختياري. الافتراضي false. allowRealIpFallback: false, tools: { - // Additional /tools/invoke HTTP denies + // عناصر رفض HTTP إضافية لـ /tools/invoke deny: ["browser"], - // Remove tools from the default HTTP deny list + // إزالة أدوات من قائمة الرفض الافتراضية لـ HTTP allow: ["gateway"], }, push: { @@ -3074,64 +3063,64 @@ scripts/sandbox-browser-setup.sh # optional browser image -- `mode`: ‏`local` ‏(تشغيل Gateway) أو `remote` ‏(الاتصال بـ Gateway بعيد). ويرفض Gateway البدء ما لم تكن القيمة `local`. -- `port`: منفذ واحد متعدد الإرسال لـ WS + HTTP. الأسبقية: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. -- `bind`: ‏`auto` أو `loopback` ‏(الافتراضي) أو `lan` ‏(`0.0.0.0`) أو `tailnet` ‏(عنوان Tailscale IP فقط) أو `custom`. -- **أسماء bind البديلة القديمة**: استخدم قيم وضع bind في `gateway.bind` ‏(`auto` و`loopback` و`lan` و`tailnet` و`custom`)، وليس أسماء host البديلة (`0.0.0.0` و`127.0.0.1` و`localhost` و`::` و`::1`). -- **ملاحظة Docker**: يستمع bind الافتراضي `loopback` على `127.0.0.1` داخل الحاوية. ومع Docker bridge networking ‏(`-p 18789:18789`) تصل الحركة إلى `eth0`، لذلك يصبح Gateway غير قابل للوصول. استخدم `--network host`، أو اضبط `bind: "lan"` ‏(أو `bind: "custom"` مع `customBindHost: "0.0.0.0"`) للاستماع على جميع الواجهات. -- **المصادقة**: مطلوبة افتراضياً. وتتطلب قيم bind غير loopback مصادقة Gateway. وعملياً يعني ذلك رمزاً مميزاً/كلمة مرور مشتركة أو reverse proxy مدركاً للهوية مع `gateway.auth.mode: "trusted-proxy"`. ويولّد معالج onboarding رمزاً مميزاً افتراضياً. -- إذا كان كل من `gateway.auth.token` و`gateway.auth.password` مضبوطين (بما في ذلك SecretRefs)، فاضبط `gateway.auth.mode` صراحةً على `token` أو `password`. وتفشل عمليات بدء التشغيل وتثبيت/إصلاح الخدمة عندما يكون الاثنان مضبوطين ويكون الوضع غير مضبوط. -- `gateway.auth.mode: "none"`: وضع صريح من دون مصادقة. استخدمه فقط لإعدادات local loopback الموثوقة؛ وهذا الوضع غير معروض عمداً في مطالبات onboarding. -- `gateway.auth.mode: "trusted-proxy"`: فوّض المصادقة إلى reverse proxy مدرك للهوية واثق برؤوس الهوية من `gateway.trustedProxies` ‏(راجع [مصادقة Trusted Proxy](/ar/gateway/trusted-proxy-auth)). ويتوقع هذا الوضع مصدراً proxy **غير loopback**؛ ولا تستوفي reverse proxyات loopback على المضيف نفسه مصادقة trusted-proxy. -- `gateway.auth.allowTailscale`: عند ضبطه على `true`، يمكن لرؤوس هوية Tailscale Serve استيفاء مصادقة Control UI/WebSocket ‏(تم التحقق منها عبر `tailscale whois`). ولا تستخدم نقاط نهاية HTTP API مصادقة رؤوس Tailscale هذه؛ بل تتبع وضع مصادقة HTTP العادي لـ Gateway بدلاً من ذلك. ويفترض هذا التدفق من دون رمز مميز أن مضيف Gateway موثوق. وتكون القيمة الافتراضية `true` عندما تكون `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit`: محدِّد اختياري لمحاولات المصادقة الفاشلة. ويُطبّق لكل عنوان IP عميل ولكل نطاق مصادقة (يتم تتبع السر المشترك ورمز الجهاز بشكل مستقل). وتعيد المحاولات المحظورة `429` + `Retry-After`. - - في مسار Control UI غير المتزامن لـ Tailscale Serve، تُسلسَل المحاولات الفاشلة للقيمة نفسها `{scope, clientIp}` قبل كتابة الفشل. لذلك يمكن للمحاولات السيئة المتزامنة من العميل نفسه أن تفعّل المحدِّد في الطلب الثاني بدلاً من مرور الطلبين كعدم تطابق عادي. - - تعود القيمة الافتراضية لـ `gateway.auth.rateLimit.exemptLoopback` إلى `true`؛ اضبطها على `false` عندما تريد عمداً أيضاً فرض التحديد على حركة localhost (لإعدادات الاختبار أو عمليات نشر proxy الصارمة). -- تُخفَّض دائماً محاولات مصادقة WS ذات الأصل browser-origin مع تعطيل إعفاء loopback (كإجراء دفاعي إضافي ضد هجمات brute force على localhost من المتصفح). -- على loopback، تُعزل حالات القفل ذات الأصل browser-origin لكل قيمة `Origin` - مطبَّعة، لذلك لا تؤدي الإخفاقات المتكررة من أصل localhost واحد تلقائياً +- `mode`: ‏`local` (تشغيل gateway) أو `remote` (الاتصال بـ gateway بعيد). ويرفض Gateway البدء ما لم يكن `local`. +- `port`: منفذ متعدد الإرسال واحد لـ WS + HTTP. الأولوية: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. +- `bind`: ‏`auto` أو `loopback` (الافتراضي) أو `lan` ‏(`0.0.0.0`) أو `tailnet` (عنوان IP لـ Tailscale فقط) أو `custom`. +- **الأسماء البديلة القديمة لـ bind**: استخدم قيم وضع bind في `gateway.bind` ‏(`auto` و`loopback` و`lan` و`tailnet` و`custom`)، وليس أسماء المستضيف البديلة (`0.0.0.0` و`127.0.0.1` و`localhost` و`::` و`::1`). +- **ملاحظة Docker**: يستمع bind الافتراضي `loopback` على `127.0.0.1` داخل الحاوية. ومع شبكات Docker bridge ‏(`-p 18789:18789`)، تصل الحركة إلى `eth0`، لذلك يصبح gateway غير قابل للوصول. استخدم `--network host`، أو عيّن `bind: "lan"` (أو `bind: "custom"` مع `customBindHost: "0.0.0.0"`) للاستماع على جميع الواجهات. +- **المصادقة**: مطلوبة افتراضيًا. تتطلب bind غير loopback مصادقة gateway. وعمليًا، يعني ذلك رمزًا مشتركًا/كلمة مرور مشتركة أو وكيلًا عكسيًا مدركًا للهوية مع `gateway.auth.mode: "trusted-proxy"`. ويولّد معالج الإعداد رمزًا افتراضيًا. +- إذا كان كل من `gateway.auth.token` و`gateway.auth.password` مهيأين (بما في ذلك SecretRefs)، فعيّن `gateway.auth.mode` صراحةً إلى `token` أو `password`. وتفشل تدفقات بدء التشغيل وتثبيت/إصلاح الخدمة عندما يكون كلاهما مهيأين ويكون mode غير معيّن. +- `gateway.auth.mode: "none"`: وضع صريح بلا مصادقة. استخدمه فقط مع إعدادات local loopback الموثوق بها؛ وهذا غير معروض عمدًا في مطالبات الإعداد. +- `gateway.auth.mode: "trusted-proxy"`: فوّض المصادقة إلى وكيل عكسي مدرك للهوية ووثّق رؤوس الهوية من `gateway.trustedProxies` (راجع [Trusted Proxy Auth](/ar/gateway/trusted-proxy-auth)). يتوقع هذا الوضع مصدر وكيل **غير loopback**؛ إذ لا تلبّي الوكلاء العكسية ذات loopback على المستضيف نفسه مصادقة trusted-proxy. +- `gateway.auth.allowTailscale`: عند تعيينه إلى `true`، يمكن لرؤوس هوية Tailscale Serve استيفاء مصادقة Control UI/WebSocket (بعد التحقق عبر `tailscale whois`). ولا تستخدم نقاط نهاية HTTP API مصادقة رؤوس Tailscale تلك؛ بل تتبع وضع مصادقة HTTP العادي الخاص بـ gateway بدلًا من ذلك. ويفترض هذا التدفق من دون رمز أن مستضيف gateway موثوق. وتكون القيمة الافتراضية `true` عندما يكون `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: محدّد اختياري لمحاولات المصادقة الفاشلة. ويُطبَّق لكل IP عميل ولكل نطاق مصادقة (يُتتبَّع السر المشترك ورمز الجهاز مستقلين عن بعضهما). وتعيد المحاولات المحظورة `429` + `Retry-After`. + - في مسار Tailscale Serve غير المتزامن الخاص بـ Control UI، تُسلسل المحاولات الفاشلة لنفس `{scope, clientIp}` قبل كتابة الفشل. لذلك يمكن للمحاولات السيئة المتزامنة من العميل نفسه أن تفعّل المحدِّد عند الطلب الثاني بدلًا من أن يمر الاثنان على أنهما عدم تطابق عادي. + - تكون القيمة الافتراضية لـ `gateway.auth.rateLimit.exemptLoopback` هي `true`؛ عيّنها إلى `false` عندما تريد عمدًا تطبيق تحديد المعدل على حركة localhost أيضًا (لإعدادات الاختبار أو عمليات نشر الوكيل الصارمة). +- تُخفَّض دائمًا محاولات مصادقة WS ذات أصل المتصفح مع تعطيل إعفاء loopback (كإجراء دفاعي إضافي ضد الهجمات بالقوة الغاشمة على localhost انطلاقًا من المتصفح). +- على loopback، تُعزَل حالات القفل ذات الأصل من المتصفح بحسب قيمة `Origin` + المطَبَّعة، بحيث لا تؤدي الإخفاقات المتكررة من أصل localhost واحد تلقائيًا إلى قفل أصل مختلف. -- `tailscale.mode`: ‏`serve` ‏(ضمن tailnet فقط، مع bind loopback) أو `funnel` ‏(عام، ويتطلب مصادقة). -- `controlUi.allowedOrigins`: قائمة سماح صريحة لأصول browser-origin لاتصالات Gateway WebSocket. وهي مطلوبة عندما يُتوقع وجود عملاء متصفح من أصول غير loopback. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: وضع خطير يفعّل الاحتياط إلى أصل Host-header لعمليات النشر التي تعتمد عمداً على سياسة أصل Host-header. -- `remote.transport`: ‏`ssh` ‏(الافتراضي) أو `direct` ‏(ws/wss). وبالنسبة إلى `direct`، يجب أن تكون `remote.url` بصيغة `ws://` أو `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: تجاوز طارئ من جهة العميل يسمح باستخدام `ws://` النصي مع عناوين IP موثوقة ضمن الشبكة الخاصة؛ بينما يبقى الافتراضي مقتصراً على loopback فقط للاتصالات النصية. -- `gateway.remote.token` / `.password` هما حقلا بيانات اعتماد للعميل البعيد. وهما لا يضبطان مصادقة Gateway بحد ذاتهما. -- `gateway.push.apns.relay.baseUrl`: عنوان HTTPS الأساسي لـ APNs relay الخارجي المستخدم من قِبل إصدارات iOS الرسمية/TestFlight بعد أن تنشر تسجيلات مدعومة بـ relay إلى Gateway. ويجب أن يطابق هذا العنوان عنوان relay المضمّن في بنية iOS. -- `gateway.push.apns.relay.timeoutMs`: مهلة الإرسال من Gateway إلى relay بالميلي ثانية. والافتراضي هو `10000`. -- تُفوَّض التسجيلات المدعومة بـ relay إلى هوية Gateway محددة. ويجلب تطبيق iOS المقترن القيمة `gateway.identity.get`، ويضمّن تلك الهوية في تسجيل relay، ويمرّر تفويض إرسال ضمن نطاق التسجيل إلى Gateway. ولا يمكن لـ Gateway آخر إعادة استخدام ذلك التسجيل المخزن. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: تجاوزات بيئة مؤقتة لإعداد relay أعلاه. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: مخرج طوارئ مخصص للتطوير لعناوين relay من نوع loopback HTTP. ويجب أن تبقى عناوين relay الإنتاجية على HTTPS. -- `gateway.channelHealthCheckMinutes`: الفاصل الزمني لمراقبة صحة القناة بالدقائق. اضبط `0` لتعطيل إعادة التشغيل الخاصة بمراقبة الصحة على مستوى العالم. الافتراضي: `5`. -- `gateway.channelStaleEventThresholdMinutes`: عتبة المقبس القديم بالدقائق. حافظ على كونها أكبر من أو مساوية لـ `gateway.channelHealthCheckMinutes`. الافتراضي: `30`. -- `gateway.channelMaxRestartsPerHour`: الحد الأقصى لإعادات تشغيل مراقبة الصحة لكل قناة/حساب خلال ساعة متحركة. الافتراضي: `10`. -- `channels..healthMonitor.enabled`: اشتراك اختياري للإلغاء على مستوى القناة لإعادات تشغيل مراقبة الصحة مع إبقاء المراقب العام مفعلاً. -- `channels..accounts..healthMonitor.enabled`: تجاوز لكل حساب في القنوات متعددة الحسابات. وعند ضبطه، تكون له الأسبقية على التجاوز على مستوى القناة. -- يمكن لمسارات استدعاء Gateway المحلية استخدام `gateway.remote.*` كاحتياط فقط عندما لا تكون `gateway.auth.*` مضبوطة. -- إذا كانت `gateway.auth.token` / `gateway.auth.password` مضبوطة صراحةً عبر SecretRef ولكن لم يتم حلها، يفشل الحل بشكل مغلق (من دون احتياط بعيد يخفي الحالة). -- `trustedProxies`: عناوين IP الخاصة بـ reverse proxy التي تنهي TLS أو تحقن رؤوس العميل المُمرَّر. أدرج فقط الوكلاء الذين تتحكم فيهم. وتظل إدخالات loopback صالحة لإعدادات الوكيل/الاكتشاف المحلي على المضيف نفسه (على سبيل المثال Tailscale Serve أو reverse proxy محلي)، لكنها **لا** تجعل طلبات loopback مؤهلة لـ `gateway.auth.mode: "trusted-proxy"`. -- `allowRealIpFallback`: عند ضبطه على `true`، يقبل Gateway القيمة `X-Real-IP` إذا كانت `X-Forwarded-For` مفقودة. والافتراضي `false` لسلوك فشل مغلق. -- `gateway.tools.deny`: أسماء أدوات إضافية محظورة لاستدعاء HTTP ‏`POST /tools/invoke` ‏(تمدد قائمة الرفض الافتراضية). -- `gateway.tools.allow`: يزيل أسماء الأدوات من قائمة الرفض الافتراضية لـ HTTP. +- `tailscale.mode`: ‏`serve` (tailnet فقط، مع bind loopback) أو `funnel` (عام، ويتطلب مصادقة). +- `controlUi.allowedOrigins`: قائمة سماح صريحة لأصول المتصفح من أجل اتصالات WebSocket بـ Gateway. وهي مطلوبة عندما يُتوقع وجود عملاء متصفح من أصول غير loopback. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: وضع خطير يفعّل الرجوع إلى أصل Host-header لعمليات النشر التي تعتمد عمدًا على سياسة أصل Host-header. +- `remote.transport`: ‏`ssh` (الافتراضي) أو `direct` ‏(ws/wss). وبالنسبة إلى `direct`، يجب أن يكون `remote.url` من النوع `ws://` أو `wss://`. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: تجاوز طارئ من جهة العميل يسمح باستخدام `ws://` النصي الصريح مع عناوين IP موثوق بها على الشبكات الخاصة؛ وتبقى القيمة الافتراضية مقتصرة على loopback فقط بالنسبة إلى الاتصالات النصية الصريحة. +- `gateway.remote.token` / `.password`: حقول بيانات اعتماد للعميل البعيد. وهي لا تهيّئ مصادقة gateway بحد ذاتها. +- `gateway.push.apns.relay.baseUrl`: عنوان HTTPS الأساسي للوكيل الخارجي APNs relay الذي تستخدمه إصدارات iOS الرسمية/TestFlight بعد أن تنشر تسجيلات مدعومة بالوكيل إلى gateway. ويجب أن يطابق هذا العنوان عنوان relay المضمّن في نسخة iOS. +- `gateway.push.apns.relay.timeoutMs`: مهلة الإرسال من gateway إلى relay بالميلي ثانية. الافتراضي `10000`. +- تُفوَّض التسجيلات المدعومة بالوكيل إلى هوية gateway محددة. ويجلب تطبيق iOS المقترن `gateway.identity.get`، ويضمّن تلك الهوية في تسجيل relay، ويمرّر صلاحية إرسال ضمن نطاق التسجيل إلى gateway. ولا يمكن لـ gateway آخر إعادة استخدام ذلك التسجيل المخزَّن. +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: تجاوزات بيئة مؤقتة لإعداد relay المذكور أعلاه. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: مخرج تطويري فقط لعناوين relay من نوع HTTP على loopback. ويجب أن تبقى عناوين relay الإنتاجية على HTTPS. +- `gateway.channelHealthCheckMinutes`: فترة مراقبة صحة القنوات بالدقائق. عيّن القيمة `0` لتعطيل إعادة التشغيل الخاصة بمراقبة الصحة عالميًا. الافتراضي: `5`. +- `gateway.channelStaleEventThresholdMinutes`: حد المقبس القديم بالدقائق. اجعل هذه القيمة أكبر من أو مساوية لـ `gateway.channelHealthCheckMinutes`. الافتراضي: `30`. +- `gateway.channelMaxRestartsPerHour`: الحد الأقصى لإعادات التشغيل بسبب مراقبة الصحة لكل قناة/حساب خلال ساعة متحركة. الافتراضي: `10`. +- `channels..healthMonitor.enabled`: تعطيل اختياري لكل قناة لإعادات التشغيل الخاصة بمراقبة الصحة مع إبقاء المراقب العام مفعّلًا. +- `channels..accounts..healthMonitor.enabled`: تجاوز لكل حساب في القنوات متعددة الحسابات. وعند تعيينه، تكون له الأولوية على التجاوز على مستوى القناة. +- يمكن لمسارات استدعاء gateway المحلية استخدام `gateway.remote.*` كاحتياطي فقط عندما لا تكون `gateway.auth.*` معيّنة. +- إذا كان `gateway.auth.token` / `gateway.auth.password` مهيأين صراحةً عبر SecretRef وكانا غير محلولين، يفشل الحل بإغلاق افتراضي (من دون تمويه عبر احتياطي بعيد). +- `trustedProxies`: عناوين IP للوكلاء العكسيين الذين ينهون TLS أو يحقنون رؤوس العميل المُحوَّلة. أدرج فقط الوكلاء الذين تتحكم بهم. وتظل إدخالات loopback صالحة لإعدادات الاكتشاف المحلي/الوكيل على المستضيف نفسه (مثل Tailscale Serve أو وكيل عكسي محلي)، لكنها **لا** تجعل طلبات loopback مؤهلة لـ `gateway.auth.mode: "trusted-proxy"`. +- `allowRealIpFallback`: عند تعيينه إلى `true`، يقبل gateway القيمة `X-Real-IP` إذا كانت `X-Forwarded-For` مفقودة. الافتراضي `false` لسلوك الإغلاق الافتراضي. +- `gateway.tools.deny`: أسماء أدوات إضافية محظورة لطلب HTTP `POST /tools/invoke` (تمتد فوق قائمة الرفض الافتراضية). +- `gateway.tools.allow`: إزالة أسماء أدوات من قائمة الرفض الافتراضية لـ HTTP. ### نقاط النهاية المتوافقة مع OpenAI -- Chat Completions: معطلة افتراضياً. فعّلها عبر `gateway.http.endpoints.chatCompletions.enabled: true`. +- Chat Completions: معطّلة افتراضيًا. فعّلها عبر `gateway.http.endpoints.chatCompletions.enabled: true`. - Responses API: ‏`gateway.http.endpoints.responses.enabled`. -- تقوية مدخلات URL في Responses: +- تقوية إدخال URL في Responses: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - تُعامل قوائم السماح الفارغة على أنها غير مضبوطة؛ استخدم `gateway.http.endpoints.responses.files.allowUrl=false` + تُعامَل قوائم السماح الفارغة على أنها غير معيّنة؛ استخدم `gateway.http.endpoints.responses.files.allowUrl=false` و/أو `gateway.http.endpoints.responses.images.allowUrl=false` لتعطيل جلب URL. - رأس تقوية اختياري للاستجابة: - - `gateway.http.securityHeaders.strictTransportSecurity` ‏(اضبطه فقط لأصول HTTPS التي تتحكم فيها؛ راجع [مصادقة Trusted Proxy](/ar/gateway/trusted-proxy-auth#tls-termination-and-hsts)) + - `gateway.http.securityHeaders.strictTransportSecurity` (عيّنه فقط لأصول HTTPS التي تتحكم بها؛ راجع [Trusted Proxy Auth](/ar/gateway/trusted-proxy-auth#tls-termination-and-hsts)) -### عزل المثيلات المتعددة +### العزل بين النسخ المتعددة -شغّل عدة Gateway على مضيف واحد مع منافذ وأدلة حالة فريدة: +شغّل عدة Gateways على مستضيف واحد مع منافذ وأدلة حالة فريدة: ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -3139,9 +3128,9 @@ OPENCLAW_STATE_DIR=~/.openclaw-a \ openclaw gateway --port 19001 ``` -إشارات مريحة: `--dev` ‏(تستخدم `~/.openclaw-dev` + المنفذ `19001`) و`--profile ` ‏(تستخدم `~/.openclaw-`). +رايات مناسبة: `--dev` (يستخدم `~/.openclaw-dev` + المنفذ `19001`)، و`--profile ` (يستخدم `~/.openclaw-`). -راجع [Gateway متعددة](/ar/gateway/multiple-gateways). +راجع [Multiple Gateways](/ar/gateway/multiple-gateways). ### `gateway.tls` @@ -3159,11 +3148,11 @@ openclaw gateway --port 19001 } ``` -- `enabled`: يفعّل إنهاء TLS عند مستمع Gateway ‏(HTTPS/WSS) ‏(الافتراضي: `false`). -- `autoGenerate`: يولّد تلقائياً زوج شهادة/مفتاح محلي موقّع ذاتياً عندما لا تكون الملفات الصريحة مضبوطة؛ للاستخدام المحلي/التطويري فقط. +- `enabled`: يفعّل إنهاء TLS عند مستمع gateway ‏(HTTPS/WSS) (الافتراضي: `false`). +- `autoGenerate`: يولّد تلقائيًا زوج cert/key محليًا موقّعًا ذاتيًا عندما لا تكون الملفات الصريحة مهيأة؛ للاستخدام local/dev فقط. - `certPath`: مسار نظام الملفات إلى ملف شهادة TLS. -- `keyPath`: مسار نظام الملفات إلى ملف المفتاح الخاص لـ TLS؛ وحافظ على تقييد أذوناته. -- `caPath`: مسار اختياري إلى حزمة CA للتحقق من العميل أو سلاسل الثقة المخصصة. +- `keyPath`: مسار نظام الملفات إلى ملف المفتاح الخاص لـ TLS؛ ويجب إبقاء الوصول إليه مقيّدًا. +- `caPath`: مسار اختياري إلى حزمة CA من أجل التحقق من العميل أو سلاسل الثقة المخصصة. ### `gateway.reload` @@ -3179,13 +3168,13 @@ openclaw gateway --port 19001 } ``` -- `mode`: يتحكم في كيفية تطبيق تعديلات الإعدادات وقت التشغيل. +- `mode`: يتحكم في كيفية تطبيق تعديلات الإعدادات أثناء التشغيل. - `"off"`: تجاهل التعديلات الحية؛ وتتطلب التغييرات إعادة تشغيل صريحة. - - `"restart"`: أعد تشغيل عملية Gateway دائماً عند تغيير الإعدادات. + - `"restart"`: أعد تشغيل عملية gateway دائمًا عند تغيير الإعدادات. - `"hot"`: طبّق التغييرات داخل العملية من دون إعادة تشغيل. - - `"hybrid"` ‏(الافتراضي): حاول أولاً إعادة التحميل السريع؛ ثم ارجع إلى إعادة التشغيل عند الحاجة. -- `debounceMs`: نافذة إزالة الارتداد بالميلي ثانية قبل تطبيق تغييرات الإعدادات (عدد صحيح غير سالب). -- `deferralTimeoutMs`: الحد الأقصى للوقت بالميلي ثانية لانتظار العمليات الجارية قبل فرض إعادة التشغيل (الافتراضي: `300000` = 5 دقائق). + - `"hybrid"` (الافتراضي): حاول أولًا إعادة التحميل الحية؛ وعُد إلى إعادة التشغيل إذا لزم الأمر. +- `debounceMs`: نافذة إزالة ارتداد بالميلي ثانية قبل تطبيق تغييرات الإعدادات (عدد صحيح غير سالب). +- `deferralTimeoutMs`: الحد الأقصى بالميلي ثانية لانتظار العمليات الجارية قبل فرض إعادة التشغيل (الافتراضي: `300000` = 5 دقائق). --- @@ -3223,36 +3212,36 @@ openclaw gateway --port 19001 ``` المصادقة: `Authorization: Bearer ` أو `x-openclaw-token: `. -تُرفض رموز hook المميزة في سلسلة الاستعلام. +تُرفض رموز hook في سلسلة الاستعلام. -ملاحظات التحقق والأمان: +ملاحظات التحقق والسلامة: -- يتطلب `hooks.enabled=true` قيمة `hooks.token` غير فارغة. -- يجب أن تكون `hooks.token` **مختلفة** عن `gateway.auth.token`؛ ويُرفض إعادة استخدام رمز Gateway المميز. -- لا يمكن أن تكون `hooks.path` هي `/`؛ استخدم مساراً فرعياً مخصصاً مثل `/hooks`. -- إذا كانت `hooks.allowRequestSessionKey=true`، فقيد `hooks.allowedSessionKeyPrefixes` (على سبيل المثال `["hook:"]`). +- يتطلب `hooks.enabled=true` قيمة غير فارغة لـ `hooks.token`. +- يجب أن تكون `hooks.token` **مختلفة** عن `gateway.auth.token`؛ ويُرفض إعادة استخدام رمز Gateway. +- لا يمكن أن يكون `hooks.path` مساويًا لـ `/`؛ استخدم مسارًا فرعيًا مخصصًا مثل `/hooks`. +- إذا كان `hooks.allowRequestSessionKey=true`، فقيد `hooks.allowedSessionKeyPrefixes` (مثل `["hook:"]`). **نقاط النهاية:** -- `POST /hooks/wake` ← `{ text, mode?: "now"|"next-heartbeat" }` -- `POST /hooks/agent` ← `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - - لا تُقبل القيمة `sessionKey` من حمولة الطلب إلا عندما تكون `hooks.allowRequestSessionKey=true` ‏(الافتراضي: `false`). -- `POST /hooks/` ← يتم حله عبر `hooks.mappings` +- `POST /hooks/wake` → ‏`{ text, mode?: "now"|"next-heartbeat" }` +- `POST /hooks/agent` → ‏`{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` + - لا تُقبل `sessionKey` من حمولة الطلب إلا عندما يكون `hooks.allowRequestSessionKey=true` (الافتراضي: `false`). +- `POST /hooks/` → يُحل عبر `hooks.mappings` -- يطابق `match.path` المسار الفرعي بعد `/hooks` ‏(مثل `/hooks/gmail` ← `gmail`). -- يطابق `match.source` حقلاً في الحمولة للمسارات العامة. +- يطابق `match.path` المسار الفرعي بعد `/hooks` (مثل `/hooks/gmail` ← `gmail`). +- يطابق `match.source` حقلًا من الحمولة بالنسبة إلى المسارات العامة. - تقرأ القوالب مثل `{{messages[0].subject}}` من الحمولة. -- يمكن أن يشير `transform` إلى وحدة JS/TS تعيد إجراء hook. - - يجب أن يكون `transform.module` مساراً نسبياً ويبقى ضمن `hooks.transformsDir` (وتُرفض المسارات المطلقة وعمليات الاجتياز). +- يمكن لـ `transform` الإشارة إلى وحدة JS/TS تُرجع إجراء hook. + - يجب أن يكون `transform.module` مسارًا نسبيًا ويبقى ضمن `hooks.transformsDir` (وتُرفض المسارات المطلقة وعمليات العبور). - يوجّه `agentId` إلى وكيل محدد؛ وتعود المعرّفات غير المعروفة إلى الوكيل الافتراضي. - `allowedAgentIds`: يقيّد التوجيه الصريح (`*` أو الحذف = السماح للجميع، و`[]` = رفض الجميع). -- `defaultSessionKey`: مفتاح جلسة ثابت اختياري لتشغيلات وكيل hook من دون `sessionKey` صريح. -- `allowRequestSessionKey`: يسمح لمتصلّي `/hooks/agent` بتعيين `sessionKey` ‏(الافتراضي: `false`). -- `allowedSessionKeyPrefixes`: قائمة سماح اختيارية للبادئات الخاصة بقيم `sessionKey` الصريحة (في الطلب + التعيين)، مثل `["hook:"]`. +- `defaultSessionKey`: مفتاح جلسة ثابت اختياري لتشغيلات hook agent التي لا تحتوي على `sessionKey` صريح. +- `allowRequestSessionKey`: يسمح لمستدعي `/hooks/agent` بتعيين `sessionKey` (الافتراضي: `false`). +- `allowedSessionKeyPrefixes`: قائمة سماح اختيارية للبادئات الخاصة بقيم `sessionKey` الصريحة (الطلب + التعيين)، مثل `["hook:"]`. - يؤدي `deliver: true` إلى إرسال الرد النهائي إلى قناة؛ وتكون القيمة الافتراضية لـ `channel` هي `last`. -- يتجاوز `model` قيمة LLM لهذا التشغيل من hook ‏(ويجب أن يكون مسموحاً به إذا كان فهرس النموذج مضبوطاً). +- يتجاوز `model` قيمة LLM لهذا التشغيل الخاص بـ hook (ويجب أن يكون مسموحًا به إذا كان فهرس النماذج معيّنًا). @@ -3279,35 +3268,35 @@ openclaw gateway --port 19001 } ``` -- يبدأ Gateway تلقائياً تشغيل `gog gmail watch serve` عند الإقلاع عندما يكون مضبوطاً. اضبط `OPENCLAW_SKIP_GMAIL_WATCHER=1` لتعطيله. -- لا تشغّل `gog gmail watch serve` منفصلاً إلى جانب Gateway. +- يبدأ Gateway تلقائيًا تشغيل `gog gmail watch serve` عند الإقلاع عندما يكون مهيأً. عيّن `OPENCLAW_SKIP_GMAIL_WATCHER=1` لتعطيله. +- لا تشغّل `gog gmail watch serve` منفصلًا إلى جانب Gateway. --- -## Canvas host +## مستضيف Canvas ```json5 { canvasHost: { root: "~/.openclaw/workspace/canvas", liveReload: true, - // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1 + // enabled: false, // أو OPENCLAW_SKIP_CANVAS_HOST=1 }, } ``` -- يقدّم HTML/CSS/JS القابلة للتحرير بواسطة الوكيل وA2UI عبر HTTP تحت منفذ Gateway: +- يقدّم HTML/CSS/JS القابلة للتعديل من الوكيل وA2UI عبر HTTP تحت منفذ Gateway: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` -- محلي فقط: احتفظ بـ `gateway.bind: "loopback"` ‏(الافتراضي). -- مع قيم bind غير loopback: تتطلب مسارات canvas مصادقة Gateway ‏(token/password/trusted-proxy)، مثل بقية أسطح HTTP الخاصة بـ Gateway. -- لا ترسل Node WebViews عادةً رؤوس المصادقة؛ وبعد إقران node واتصاله، يعلن Gateway عناوين URL لقدرات ضمن نطاق node للوصول إلى canvas/A2UI. -- ترتبط عناوين URL الخاصة بالقدرات بجلسة WS النشطة لـ node وتنتهي صلاحيتها بسرعة. ولا يُستخدم الاحتياط المعتمد على IP. -- يحقن عميل live-reload في HTML المقدمة. -- ينشئ تلقائياً ملف `index.html` ابتدائياً عند الفراغ. -- يقدّم أيضاً A2UI عند `/__openclaw__/a2ui/`. -- تتطلب التغييرات إعادة تشغيل Gateway. -- عطّل live reload للأدلة الكبيرة أو عند ظهور أخطاء `EMFILE`. +- محلي فقط: أبقِ `gateway.bind: "loopback"` (الافتراضي). +- في bind غير loopback: تتطلب مسارات canvas مصادقة Gateway (token/password/trusted-proxy)، مثل بقية أسطح HTTP في Gateway. +- لا ترسل WebViews الخاصة بـ Node عادةً رؤوس مصادقة؛ وبعد إقران Node واتصالها، يعلن Gateway عناوين capability URL ضمن نطاق node للوصول إلى canvas/A2UI. +- ترتبط عناوين capability URL بجلسة WS النشطة الخاصة بـ node وتنتهي بسرعة. ولا يُستخدم احتياطي يعتمد على IP. +- يحقن عميل إعادة التحميل الحية في HTML المقدّم. +- ينشئ تلقائيًا ملف `index.html` ابتدائيًا عند الفراغ. +- كما يقدّم A2UI عند `/__openclaw__/a2ui/`. +- تتطلب التغييرات إعادة تشغيل gateway. +- عطّل إعادة التحميل الحية بالنسبة إلى الأدلة الكبيرة أو أخطاء `EMFILE`. --- @@ -3325,11 +3314,11 @@ openclaw gateway --port 19001 } ``` -- `minimal` ‏(الافتراضي): يحذف `cliPath` + `sshPort` من سجلات TXT. +- `minimal` (الافتراضي): يحذف `cliPath` + `sshPort` من سجلات TXT. - `full`: يتضمن `cliPath` + `sshPort`. -- يعود اسم المضيف افتراضياً إلى `openclaw`. وتجاوزه عبر `OPENCLAW_MDNS_HOSTNAME`. +- يكون اسم المستضيف افتراضيًا `openclaw`. ويمكن تجاوزه عبر `OPENCLAW_MDNS_HOSTNAME`. -### واسع النطاق (DNS-SD) +### النطاق الواسع (DNS-SD) ```json5 { @@ -3339,7 +3328,7 @@ openclaw gateway --port 19001 } ``` -يكتب منطقة DNS-SD أحادية الإرسال ضمن `~/.openclaw/dns/`. ولاكتشاف عبر الشبكات، اقترنه مع خادم DNS ‏(ويُوصى بـ CoreDNS) + DNS مجزأ في Tailscale. +يكتب منطقة unicast DNS-SD تحت `~/.openclaw/dns/`. وبالنسبة إلى الاكتشاف عبر الشبكات، اجمعه مع خادم DNS ‏(ويُوصى بـ CoreDNS) + ‏Tailscale split DNS. الإعداد: `openclaw dns setup --apply`. @@ -3347,7 +3336,7 @@ openclaw gateway --port 19001 ## البيئة -### `env` ‏(متغيرات البيئة المضمّنة) +### `env` (متغيرات بيئة مضمنة) ```json5 { @@ -3364,14 +3353,14 @@ openclaw gateway --port 19001 } ``` -- لا تُطبّق متغيرات البيئة المضمنة إلا إذا كانت بيئة العملية تفتقد المفتاح. -- ملفات `.env`: ملف `.env` في CWD + `~/.openclaw/.env` ‏(ولا يطغى أي منهما على المتغيرات الموجودة). -- `shellEnv`: يستورد المفاتيح المتوقعة المفقودة من ملف profile الخاص بصدفة تسجيل الدخول. -- راجع [البيئة](/ar/help/environment) لمعرفة الأسبقية الكاملة. +- لا تُطبَّق متغيرات البيئة المضمنة إلا إذا كانت بيئة العملية تفتقد المفتاح. +- ملفات `.env`: ملف `.env` في CWD + الملف `~/.openclaw/.env` (ولا يتجاوز أي منهما المتغيرات الموجودة). +- `shellEnv`: يستورد المفاتيح المتوقعة المفقودة من ملف تعريف صدفة تسجيل الدخول لديك. +- راجع [Environment](/ar/help/environment) لمعرفة الأولوية الكاملة. -### استبدال متغيرات البيئة +### الاستبدال بمتغيرات البيئة -أشِر إلى متغيرات البيئة في أي سلسلة إعدادات باستخدام `${VAR_NAME}`: +أشر إلى متغيرات البيئة في أي سلسلة إعدادات باستخدام `${VAR_NAME}`: ```json5 { @@ -3381,20 +3370,20 @@ openclaw gateway --port 19001 } ``` -- تتم مطابقة الأسماء الكبيرة فقط: `[A-Z_][A-Z0-9_]*`. -- تؤدي المتغيرات المفقودة/الفارغة إلى إطلاق خطأ عند تحميل الإعدادات. -- استخدم `$${VAR}` للهروب إلى `${VAR}` حرفياً. +- تُطابق الأسماء المكتوبة بأحرف كبيرة فقط: `[A-Z_][A-Z0-9_]*`. +- تؤدي المتغيرات المفقودة/الفارغة إلى خطأ عند تحميل الإعدادات. +- استخدم `$${VAR}` لتمثيل `${VAR}` حرفيًا. - يعمل ذلك مع `$include`. --- ## الأسرار -تُعد مراجع الأسرار إضافةً تراكمية: ما زالت القيم النصية الصريحة تعمل. +تكون مراجع الأسرار إضافية: ما تزال القيم النصية الصريحة تعمل. ### `SecretRef` -استخدم شكلاً واحداً للكائن: +استخدم شكل كائن واحد: ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } @@ -3403,24 +3392,24 @@ openclaw gateway --port 19001 التحقق: - نمط `provider`: ‏`^[a-z][a-z0-9_-]{0,63}$` -- نمط `id` مع `source: "env"`: ‏`^[A-Z][A-Z0-9_]{0,127}$` -- `source: "file"` ‏`id`: مؤشر JSON مطلق (على سبيل المثال `"/providers/openai/apiKey"`) -- نمط `id` مع `source: "exec"`: ‏`^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- يجب ألا تحتوي معرفات `source: "exec"` على مقاطع مسار محددة بشرطة مائلة من نوع `.` أو `..` ‏(على سبيل المثال يُرفض `a/../b`) +- نمط `id` عند `source: "env"`: ‏`^[A-Z][A-Z0-9_]{0,127}$` +- `source: "file"` مع `id`: مؤشر JSON مطلق (مثل `"/providers/openai/apiKey"`) +- نمط `id` عند `source: "exec"`: ‏`^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` +- يجب ألا تحتوي معرّفات `source: "exec"` على مقاطع مسار `.` أو `..` مفصولة بشرطة مائلة (مثل `a/../b` وهو مرفوض) ### سطح بيانات الاعتماد المدعوم -- المصفوفة القياسية: [سطح بيانات اعتماد SecretRef](/ar/reference/secretref-credential-surface) +- المصفوفة القانونية: [SecretRef Credential Surface](/ar/reference/secretref-credential-surface) - تستهدف `secrets apply` مسارات بيانات الاعتماد المدعومة في `openclaw.json`. -- تُدرج مراجع `auth-profiles.json` في حل وقت التشغيل وتغطية التدقيق. +- تُدرج مراجع `auth-profiles.json` في الحل أثناء التشغيل وفي تغطية التدقيق. -### إعداد موفّري الأسرار +### إعداد موفري الأسرار ```json5 { secrets: { providers: { - default: { source: "env" }, // optional explicit env provider + default: { source: "env" }, // موفّر env صريح اختياري filemain: { source: "file", path: "~/.openclaw/secrets.json", @@ -3444,13 +3433,13 @@ openclaw gateway --port 19001 ملاحظات: -- يدعم موفّر `file` الوضعين `mode: "json"` و`mode: "singleValue"` ‏(ويجب أن تكون `id` هي `"value"` في وضع singleValue). -- يتطلب موفّر `exec` مسار `command` مطلقاً ويستخدم حمولات البروتوكول على stdin/stdout. -- تُرفض مسارات الأوامر الرمزية افتراضياً. اضبط `allowSymlinkCommand: true` للسماح بمسارات الروابط الرمزية مع التحقق من مسار الهدف المحلول. -- إذا كان `trustedDirs` مضبوطاً، فسيُطبّق فحص الدليل الموثوق على مسار الهدف المحلول. -- تكون بيئة الابن في `exec` محدودة افتراضياً؛ ومرّر المتغيرات المطلوبة صراحةً عبر `passEnv`. -- تُحل مراجع الأسرار وقت التفعيل إلى لقطة داخل الذاكرة، ثم تقرأ مسارات الطلب اللقطة فقط. -- يُطبّق ترشيح السطح النشط أثناء التفعيل: تؤدي المراجع غير المحلولة على الأسطح المفعّلة إلى فشل بدء التشغيل/إعادة التحميل، بينما يتم تخطي الأسطح غير النشطة مع تشخيصات. +- يدعم موفّر `file` الوضعين `mode: "json"` و`mode: "singleValue"` (ويجب أن يكون `id` مساويًا لـ `"value"` في وضع singleValue). +- يتطلب موفّر `exec` مسار `command` مطلقًا ويستخدم حمولات البروتوكول على stdin/stdout. +- تُرفض مسارات الأوامر الرمزية افتراضيًا. عيّن `allowSymlinkCommand: true` للسماح بمسارات الروابط الرمزية مع التحقق من مسار الهدف المحلول. +- إذا كان `trustedDirs` معيّنًا، فيُطبَّق فحص الدليل الموثوق على مسار الهدف المحلول. +- تكون بيئة العملية الابنة لـ `exec` محدودة افتراضيًا؛ ومرّر المتغيرات المطلوبة صراحةً عبر `passEnv`. +- تُحل مراجع الأسرار وقت التفعيل إلى لقطة موجودة في الذاكرة، ثم تقرأ مسارات الطلب تلك اللقطة فقط. +- يُطبَّق ترشيح السطح النشط أثناء التفعيل: تؤدي المراجع غير المحلولة على الأسطح المفعّلة إلى فشل بدء التشغيل/إعادة التحميل، بينما تُتخطى الأسطح غير النشطة مع بيانات تشخيصية. --- @@ -3473,12 +3462,12 @@ openclaw gateway --port 19001 ``` - تُخزَّن ملفات التعريف لكل وكيل في `/auth-profiles.json`. -- يدعم `auth-profiles.json` مراجع على مستوى القيمة (`keyRef` لـ `api_key`، و`tokenRef` لـ `token`) لأوضاع بيانات الاعتماد الثابتة. -- لا تدعم ملفات تعريف وضع OAuth ‏(`auth.profiles..mode = "oauth"`) بيانات اعتماد ملفات تعريف المصادقة المدعومة بـ SecretRef. -- تأتي بيانات الاعتماد الثابتة وقت التشغيل من لقطات محلولة داخل الذاكرة؛ وتُنظَّف إدخالات `auth.json` الثابتة القديمة عند اكتشافها. -- عمليات استيراد OAuth القديمة تأتي من `~/.openclaw/credentials/oauth.json`. +- يدعم `auth-profiles.json` مراجع على مستوى القيمة (`keyRef` للوضع `api_key`، و`tokenRef` للوضع `token`) لأنماط بيانات الاعتماد الثابتة. +- لا تدعم ملفات تعريف وضع OAuth ‏(`auth.profiles..mode = "oauth"`) بيانات اعتماد ملفات التعريف المدعومة بواسطة SecretRef. +- تأتي بيانات الاعتماد الثابتة أثناء التشغيل من لقطات محلولة في الذاكرة؛ وتُنظَّف إدخالات `auth.json` الثابتة القديمة عند اكتشافها. +- استيرادات OAuth القديمة من `~/.openclaw/credentials/oauth.json`. - راجع [OAuth](/ar/concepts/oauth). -- سلوك وقت تشغيل الأسرار وأدوات `audit/configure/apply`: ‏[إدارة الأسرار](/ar/gateway/secrets). +- سلوك وقت تشغيل الأسرار وأدوات `audit/configure/apply`: ‏[Secrets Management](/ar/gateway/secrets). ### `auth.cooldowns` @@ -3500,21 +3489,21 @@ openclaw gateway --port 19001 } ``` -- `billingBackoffHours`: مدة التراجع الأساسية بالساعات عندما يفشل ملف التعريف بسبب أخطاء حقيقية - في الفوترة/عدم كفاية الرصيد (الافتراضي: `5`). ولا يزال من الممكن أن - يقع نص الفوترة الصريح هنا حتى في استجابات `401`/`403`، لكن - تبقى مطابقات النص الخاصة بكل موفّر ضمن نطاق الموفّر الذي يملكها (على سبيل المثال OpenRouter - ‏`Key limit exceeded`). وتبقى رسائل نوافذ الاستخدام القابلة لإعادة المحاولة عبر HTTP `402` - أو رسائل حدود الإنفاق على المؤسسة/مساحة العمل ضمن مسار `rate_limit` - بدلاً من ذلك. -- `billingBackoffHoursByProvider`: تجاوزات اختيارية لكل موفّر لساعات التراجع الخاصة بالفوترة. +- `billingBackoffHours`: فترة التراجع الأساسية بالساعات عندما يفشل ملف التعريف بسبب أخطاء فوترة/رصيد غير كافٍ حقيقية + (الافتراضي: `5`). ويمكن أن تصل نصوص الفوترة الصريحة + إلى هنا حتى على استجابات `401`/`403`، لكن + مطابِقات النصوص الخاصة بكل مزوّد تظل محصورة بالمزوّد الذي يملكها (مثل OpenRouter + `Key limit exceeded`). وتبقى رسائل نافذة الاستخدام القابلة لإعادة المحاولة في HTTP `402` أو + رسائل حدود الإنفاق الخاصة بالمؤسسة/مساحة العمل ضمن مسار `rate_limit` + بدلًا من ذلك. +- `billingBackoffHoursByProvider`: تجاوزات اختيارية حسب المزوّد لساعات تراجع الفوترة. - `billingMaxHours`: الحد الأقصى بالساعات للنمو الأسي لتراجع الفوترة (الافتراضي: `24`). -- `authPermanentBackoffMinutes`: مدة التراجع الأساسية بالدقائق لإخفاقات `auth_permanent` عالية الثقة (الافتراضي: `10`). +- `authPermanentBackoffMinutes`: فترة التراجع الأساسية بالدقائق لإخفاقات `auth_permanent` عالية الثقة (الافتراضي: `10`). - `authPermanentMaxMinutes`: الحد الأقصى بالدقائق لنمو تراجع `auth_permanent` (الافتراضي: `60`). - `failureWindowHours`: النافذة المتحركة بالساعات المستخدمة لعدادات التراجع (الافتراضي: `24`). -- `overloadedProfileRotations`: الحد الأقصى لتدويرات ملفات تعريف المصادقة ضمن الموفّر نفسه لأخطاء الحمل الزائد قبل الانتقال إلى الاحتياطي على مستوى النموذج (الافتراضي: `1`). وتقع هنا أشكال انشغال الموفّر مثل `ModelNotReadyException`. -- `overloadedBackoffMs`: تأخير ثابت قبل إعادة محاولة تدوير ملف تعريف/موفّر محمّل أكثر من اللازم (الافتراضي: `0`). -- `rateLimitedProfileRotations`: الحد الأقصى لتدويرات ملفات تعريف المصادقة ضمن الموفّر نفسه لأخطاء تحديد المعدل قبل الانتقال إلى الاحتياطي على مستوى النموذج (الافتراضي: `1`). ويتضمن ذلك مستودع تحديد المعدل نصوصاً على شكل موفّر مثل `Too many concurrent requests` و`ThrottlingException` و`concurrency limit reached` و`workers_ai ... quota limit exceeded` و`resource exhausted`. +- `overloadedProfileRotations`: الحد الأقصى لعمليات تدوير ملفات تعريف المصادقة للمزوّد نفسه في حالات الحمل الزائد قبل التحويل إلى fallback للنموذج (الافتراضي: `1`). وتدخل هنا أشكال انشغال المزوّد مثل `ModelNotReadyException`. +- `overloadedBackoffMs`: تأخير ثابت قبل إعادة محاولة تدوير ملف تعريف/مزوّد مثقل (الافتراضي: `0`). +- `rateLimitedProfileRotations`: الحد الأقصى لعمليات تدوير ملفات تعريف المصادقة للمزوّد نفسه في حالات تحديد المعدل قبل التحويل إلى fallback للنموذج (الافتراضي: `1`). وتتضمن سلة تحديد المعدل تلك نصوصًا بصياغة المزوّد مثل `Too many concurrent requests` و`ThrottlingException` و`concurrency limit reached` و`workers_ai ... quota limit exceeded` و`resource exhausted`. --- @@ -3534,9 +3523,9 @@ openclaw gateway --port 19001 ``` - ملف السجل الافتراضي: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. -- اضبط `logging.file` لمسار ثابت. -- ترتفع قيمة `consoleLevel` إلى `debug` عند استخدام `--verbose`. -- `maxFileBytes`: الحد الأقصى لحجم ملف السجل بالبايت قبل كبح عمليات الكتابة (عدد صحيح موجب؛ الافتراضي: `524288000` = ‏500 ميغابايت). استخدم تدوير السجلات الخارجي لعمليات النشر الإنتاجية. +- عيّن `logging.file` للحصول على مسار ثابت. +- يرتفع `consoleLevel` إلى `debug` عند استخدام `--verbose`. +- `maxFileBytes`: الحد الأقصى لحجم ملف السجل بالبايت قبل كبح الكتابة (عدد صحيح موجب؛ الافتراضي: `524288000` = 500 MB). استخدم تدوير السجلات الخارجي لعمليات النشر الإنتاجية. --- @@ -3573,20 +3562,20 @@ openclaw gateway --port 19001 } ``` -- `enabled`: المفتاح الرئيسي لإخراج أدوات القياس (الافتراضي: `true`). -- `flags`: مصفوفة من سلاسل الإشارات التي تفعّل مخرجات السجل الموجّهة (وتدعم محارف البدل مثل `"telegram.*"` أو `"*"`). -- `stuckSessionWarnMs`: عتبة العمر بالميلي ثانية لإصدار تحذيرات الجلسات العالقة بينما تبقى الجلسة في حالة المعالجة. -- `otel.enabled`: يفعّل خط تصدير OpenTelemetry ‏(الافتراضي: `false`). -- `otel.endpoint`: عنوان URL الخاص بالمجمّع لتصدير OTel. -- `otel.protocol`: ‏`"http/protobuf"` ‏(الافتراضي) أو `"grpc"`. -- `otel.headers`: رؤوس بيانات وصفية إضافية لـ HTTP/gRPC تُرسَل مع طلبات تصدير OTel. +- `enabled`: المفتاح الرئيسي لمخرجات القياس (الافتراضي: `true`). +- `flags`: مصفوفة من سلاسل الرايات التي تفعّل مخرجات سجل موجّهة (وتدعم أحرف البدل مثل `"telegram.*"` أو `"*"`). +- `stuckSessionWarnMs`: حد العمر بالميلي ثانية لإصدار تحذيرات الجلسة العالقة بينما تبقى الجلسة في حالة معالجة. +- `otel.enabled`: يفعّل مسار تصدير OpenTelemetry (الافتراضي: `false`). +- `otel.endpoint`: عنوان URL للمجمّع من أجل تصدير OTel. +- `otel.protocol`: ‏`"http/protobuf"` (الافتراضي) أو `"grpc"`. +- `otel.headers`: رؤوس بيانات تعريف HTTP/gRPC إضافية تُرسل مع طلبات تصدير OTel. - `otel.serviceName`: اسم الخدمة لسمات المورد. - `otel.traces` / `otel.metrics` / `otel.logs`: تفعيل تصدير الأثر أو المقاييس أو السجلات. -- `otel.sampleRate`: معدل أخذ العينات للأثر من `0` إلى `1`. -- `otel.flushIntervalMs`: فاصل تفريغ telemetry الدوري بالميلي ثانية. -- `cacheTrace.enabled`: يسجل لقطات تتبع الذاكرة المؤقتة للتشغيلات المضمّنة (الافتراضي: `false`). -- `cacheTrace.filePath`: مسار الخرج لملف JSONL الخاص بتتبع الذاكرة المؤقتة (الافتراضي: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: تتحكم في ما يُضمَّن في خرج تتبع الذاكرة المؤقتة (جميعها افتراضياً: `true`). +- `otel.sampleRate`: معدل أخذ عينات الأثر من `0` إلى `1`. +- `otel.flushIntervalMs`: فترة التفريغ الدورية للقياسات بالميلي ثانية. +- `cacheTrace.enabled`: تسجيل لقطات تتبع cache للتشغيلات المضمنة (الافتراضي: `false`). +- `cacheTrace.filePath`: مسار الإخراج لملف JSONL الخاص بتتبع cache (الافتراضي: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: تتحكم في ما يُضمَّن في مخرجات تتبع cache (وجميعها افتراضيًا: `true`). --- @@ -3608,12 +3597,12 @@ openclaw gateway --port 19001 } ``` -- `channel`: قناة الإصدار لعمليات تثبيت npm/git — ‏`"stable"` أو `"beta"` أو `"dev"`. -- `checkOnStart`: التحقق من تحديثات npm عند بدء Gateway ‏(الافتراضي: `true`). -- `auto.enabled`: تفعيل التحديث التلقائي في الخلفية لعمليات تثبيت الحِزم (الافتراضي: `false`). -- `auto.stableDelayHours`: الحد الأدنى للتأخير بالساعات قبل التطبيق التلقائي لقناة stable ‏(الافتراضي: `6`؛ الحد الأقصى: `168`). -- `auto.stableJitterHours`: نافذة توزيع إضافية لقناة stable بالساعات (الافتراضي: `12`؛ الحد الأقصى: `168`). -- `auto.betaCheckIntervalHours`: عدد مرات تشغيل فحوصات قناة beta بالساعات (الافتراضي: `1`؛ الحد الأقصى: `24`). +- `channel`: قناة الإصدار لتثبيتات npm/git — ‏`"stable"` أو `"beta"` أو `"dev"`. +- `checkOnStart`: التحقق من تحديثات npm عند بدء gateway (الافتراضي: `true`). +- `auto.enabled`: تفعيل التحديث التلقائي في الخلفية لتثبيتات الحزم (الافتراضي: `false`). +- `auto.stableDelayHours`: الحد الأدنى للتأخير بالساعات قبل التطبيق التلقائي لقناة stable (الافتراضي: `6`؛ الحد الأقصى: `168`). +- `auto.stableJitterHours`: نافذة توزيع إضافية بالساعات لتطبيقات قناة stable (الافتراضي: `12`؛ الحد الأقصى: `168`). +- `auto.betaCheckIntervalHours`: عدد المرات التي تُجرى فيها فحوص قناة beta بالساعات (الافتراضي: `1`؛ الحد الأقصى: `24`). --- @@ -3646,22 +3635,22 @@ openclaw gateway --port 19001 } ``` -- `enabled`: بوابة ميزة ACP العامة (الافتراضي: `false`). -- `dispatch.enabled`: بوابة مستقلة لإرسال أدوار جلسات ACP ‏(الافتراضي: `true`). اضبطها على `false` للإبقاء على أوامر ACP متاحة مع حظر التنفيذ. -- `backend`: معرّف الواجهة الخلفية الافتراضية لوقت تشغيل ACP ‏(ويجب أن يطابق Plugin وقت تشغيل ACP مسجلاً). -- `defaultAgent`: معرّف وكيل هدف احتياطي لـ ACP عندما لا تحدد عمليات الإنشاء هدفاً صريحاً. +- `enabled`: بوابة الميزات العامة لـ ACP (الافتراضي: `false`). +- `dispatch.enabled`: بوابة مستقلة لإرسال أدوار جلسات ACP (الافتراضي: `true`). عيّنها إلى `false` للإبقاء على أوامر ACP متاحة مع حظر التنفيذ. +- `backend`: معرّف الواجهة الخلفية الافتراضية لوقت تشغيل ACP (ويجب أن يطابق Plugin وقت تشغيل ACP مسجلة). +- `defaultAgent`: معرّف وكيل ACP الاحتياطي المستهدف عندما لا تحدد عمليات spawn هدفًا صريحًا. - `allowedAgents`: قائمة سماح لمعرّفات الوكلاء المسموح بها لجلسات وقت تشغيل ACP؛ وتعني القيمة الفارغة عدم وجود تقييد إضافي. - `maxConcurrentSessions`: الحد الأقصى لعدد جلسات ACP النشطة بالتوازي. - `stream.coalesceIdleMs`: نافذة التفريغ عند الخمول بالميلي ثانية للنص المتدفق. -- `stream.maxChunkChars`: الحد الأقصى لحجم الكتلة قبل تقسيم إسقاط الكتلة المتدفقة. -- `stream.repeatSuppression`: يمنع تكرار أسطر الحالة/الأداة لكل دور (الافتراضي: `true`). -- `stream.deliveryMode`: يقوم `"live"` بالبث تدريجياً؛ بينما يقوم `"final_only"` بالتخزين المؤقت حتى أحداث إنهاء الدور. +- `stream.maxChunkChars`: الحد الأقصى لحجم القطعة قبل تقسيم إسقاط الكتل المتدفقة. +- `stream.repeatSuppression`: كبح أسطر الحالة/الأدوات المتكررة لكل دور (الافتراضي: `true`). +- `stream.deliveryMode`: تؤدي `"live"` إلى البث التدريجي؛ بينما تقوم `"final_only"` بالتخزين المؤقت حتى أحداث نهاية الدور. - `stream.hiddenBoundarySeparator`: الفاصل قبل النص المرئي بعد أحداث الأدوات المخفية (الافتراضي: `"paragraph"`). -- `stream.maxOutputChars`: الحد الأقصى لأحرف خرج المساعد المعروضة لكل دور ACP. -- `stream.maxSessionUpdateChars`: الحد الأقصى للأحرف لأسطر الحالة/التحديث المعروضة الخاصة بـ ACP. -- `stream.tagVisibility`: سجل يربط أسماء الوسوم بتجاوزات رؤية منطقية للأحداث المتدفقة. -- `runtime.ttlMinutes`: مدة TTL للخمول بالدقائق لعُمّال جلسات ACP قبل أن يصبحوا مؤهلين للتنظيف. -- `runtime.installCommand`: أمر تثبيت اختياري للتشغيل عند تهيئة بيئة وقت تشغيل ACP. +- `stream.maxOutputChars`: الحد الأقصى لأحرف مخرجات المساعد المسقطة لكل دور ACP. +- `stream.maxSessionUpdateChars`: الحد الأقصى لأحرف أسطر الحالة/التحديث المسقطة الخاصة بـ ACP. +- `stream.tagVisibility`: سجل بأسماء الوسوم إلى تجاوزات إظهار منطقية للأحداث المتدفقة. +- `runtime.ttlMinutes`: قيمة TTL للخمول بالدقائق لعمّال جلسات ACP قبل أن يصبحوا مؤهلين للتنظيف. +- `runtime.installCommand`: أمر تثبيت اختياري يُشغَّل عند تهيئة بيئة وقت تشغيل ACP. --- @@ -3677,17 +3666,17 @@ openclaw gateway --port 19001 } ``` -- يتحكم `cli.banner.taglineMode` في نمط الشعار الفرعي: - - `"random"` ‏(الافتراضي): عبارات فرعية دوّارة مضحكة/موسمية. - - `"default"`: عبارة فرعية محايدة ثابتة (`All your chats, one OpenClaw.`). - - `"off"`: من دون نص عبارة فرعية (مع استمرار عرض عنوان الشعار/الإصدار). -- لإخفاء الشعار بالكامل (وليس العبارات الفرعية فقط)، اضبط متغير البيئة `OPENCLAW_HIDE_BANNER=1`. +- يتحكم `cli.banner.taglineMode` في نمط الشعار النصي: + - `"random"` (الافتراضي): شعارات نصية متداولة طريفة/موسمية. + - `"default"`: شعار نصي محايد ثابت (`All your chats, one OpenClaw.`). + - `"off"`: بدون نص شعار (مع بقاء عنوان/إصدار الشعار ظاهرين). +- لإخفاء الشعار بالكامل (وليس الشعارات النصية فقط)، عيّن متغير البيئة `OPENCLAW_HIDE_BANNER=1`. --- ## Wizard -بيانات وصفية يكتبها CLI في تدفقات الإعداد الموجّهة (`onboard` و`configure` و`doctor`): +بيانات تعريف يكتبها تدفق الإعداد الموجّه في CLI ‏(`onboard` و`configure` و`doctor`): ```json5 { @@ -3705,15 +3694,15 @@ openclaw gateway --port 19001 ## الهوية -راجع حقول الهوية في `agents.list` ضمن [القيم الافتراضية للوكلاء](#agent-defaults). +راجع حقول الهوية في `agents.list` تحت [الإعدادات الافتراضية للوكلاء](#agent-defaults). --- -## Bridge ‏(قديم، أُزيل) +## Bridge (قديم، أُزيل) -لم تعد الإصدارات الحالية تتضمن TCP bridge. وتتصل Nodes عبر Gateway WebSocket. ولم تعد مفاتيح `bridge.*` جزءاً من مخطط الإعدادات (وسيفشل التحقق حتى تُزال؛ ويمكن لـ `openclaw doctor --fix` إزالة المفاتيح غير المعروفة). +لم تعد الإصدارات الحالية تتضمن TCP bridge. تتصل Nodes عبر Gateway WebSocket. ولم تعد مفاتيح `bridge.*` جزءًا من مخطط الإعدادات (ويفشل التحقق حتى إزالتها؛ ويمكن لـ `openclaw doctor --fix` إزالة المفاتيح غير المعروفة). - + ```json { @@ -3740,22 +3729,22 @@ openclaw gateway --port 19001 cron: { enabled: true, maxConcurrentRuns: 2, - webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs - webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth - sessionRetention: "24h", // duration string or false + webhook: "https://example.invalid/legacy", // قيمة احتياطية قديمة ومهجورة للوظائف المخزنة ذات notify:true + webhookToken: "replace-with-dedicated-token", // رمز bearer اختياري لمصادقة Webhook الصادر + sessionRetention: "24h", // سلسلة مدة أو false runLog: { - maxBytes: "2mb", // default 2_000_000 bytes - keepLines: 2000, // default 2000 + maxBytes: "2mb", // الافتراضي 2_000_000 بايت + keepLines: 2000, // الافتراضي 2000 }, }, } ``` -- `sessionRetention`: المدة التي يجب الاحتفاظ خلالها بجلسات تشغيل Cron المعزولة المكتملة قبل تقليمها من `sessions.json`. وتتحكم أيضاً في تنظيف أرشيفات نصوص Cron المحذوفة. الافتراضي: `24h`؛ اضبط `false` لتعطيله. -- `runLog.maxBytes`: الحجم الأقصى لكل ملف سجل تشغيل (`cron/runs/.jsonl`) قبل التقليم. الافتراضي: `2_000_000` بايت. -- `runLog.keepLines`: أحدث الأسطر المحتفَظ بها عند تفعيل تقليم سجل التشغيل. الافتراضي: `2000`. -- `webhookToken`: رمز bearer يُستخدم لتسليم POST إلى Cron Webhook ‏(`delivery.mode = "webhook"`)، وإذا حُذف فلن يُرسل أي رأس مصادقة. -- `webhook`: عنوان URL احتياطي قديم ومهمل لـ Webhook ‏(http/https) يُستخدم فقط للمهام المخزّنة التي لا تزال تحتوي على `notify: true`. +- `sessionRetention`: المدة التي تُحفَظ خلالها جلسات تشغيل Cron المعزولة المكتملة قبل قصّها من `sessions.json`. كما تتحكم أيضًا في تنظيف أرشيفات نصوص Cron المحذوفة. الافتراضي: `24h`؛ عيّن `false` للتعطيل. +- `runLog.maxBytes`: الحد الأقصى للحجم لكل ملف سجل تشغيل (`cron/runs/.jsonl`) قبل القص. الافتراضي: `2_000_000` بايت. +- `runLog.keepLines`: أحدث الأسطر التي يُحتفَظ بها عند تفعيل قص سجل التشغيل. الافتراضي: `2000`. +- `webhookToken`: رمز bearer المستخدم في تسليم POST الخاص بـ Cron webhook ‏(`delivery.mode = "webhook"`)، وإذا حُذف فلن يُرسَل رأس مصادقة. +- `webhook`: عنوان URL احتياطي قديم ومهجور لـ webhook ‏(http/https) يُستخدم فقط للوظائف المخزنة التي ما زالت تحتوي على `notify: true`. ### `cron.retry` @@ -3771,11 +3760,11 @@ openclaw gateway --port 19001 } ``` -- `maxAttempts`: الحد الأقصى لإعادات المحاولة للمهام أحادية التنفيذ عند حدوث أخطاء عابرة (الافتراضي: `3`؛ المجال: `0`–`10`). +- `maxAttempts`: الحد الأقصى لإعادات المحاولة للوظائف أحادية التشغيل عند حدوث أخطاء عابرة (الافتراضي: `3`؛ النطاق: `0`–`10`). - `backoffMs`: مصفوفة تأخيرات التراجع بالميلي ثانية لكل محاولة إعادة (الافتراضي: `[30000, 60000, 300000]`؛ من 1 إلى 10 إدخالات). -- `retryOn`: أنواع الأخطاء التي تفعّل إعادة المحاولة — ‏`"rate_limit"` و`"overloaded"` و`"network"` و`"timeout"` و`"server_error"`. احذفها لإعادة المحاولة مع جميع الأنواع العابرة. +- `retryOn`: أنواع الأخطاء التي تؤدي إلى إعادة المحاولة — `"rate_limit"` و`"overloaded"` و`"network"` و`"timeout"` و`"server_error"`. احذفها لإعادة محاولة جميع الأنواع العابرة. -ينطبق هذا فقط على مهام Cron أحادية التنفيذ. أما المهام المتكررة فتستخدم معالجة فشل منفصلة. +ينطبق ذلك فقط على وظائف Cron أحادية التشغيل. أما الوظائف المتكررة فتستخدم معالجة فشل منفصلة. ### `cron.failureAlert` @@ -3793,10 +3782,10 @@ openclaw gateway --port 19001 } ``` -- `enabled`: تفعيل تنبيهات الفشل لمهام Cron ‏(الافتراضي: `false`). +- `enabled`: تفعيل تنبيهات فشل وظائف Cron (الافتراضي: `false`). - `after`: عدد الإخفاقات المتتالية قبل إطلاق التنبيه (عدد صحيح موجب، الحد الأدنى: `1`). -- `cooldownMs`: الحد الأدنى بالميلي ثانية بين التنبيهات المتكررة لنفس المهمة (عدد صحيح غير سالب). -- `mode`: وضع التسليم — تقوم `"announce"` بالإرسال عبر رسالة قناة؛ بينما تقوم `"webhook"` بالنشر إلى Webhook المضبوط. +- `cooldownMs`: الحد الأدنى بالميلي ثانية بين التنبيهات المتكررة للوظيفة نفسها (عدد صحيح غير سالب). +- `mode`: وضع التسليم — ترسل `"announce"` عبر رسالة قناة؛ بينما تنشر `"webhook"` إلى Webhook المهيأ. - `accountId`: معرّف حساب أو قناة اختياري لتحديد نطاق تسليم التنبيه. ### `cron.failureDestination` @@ -3814,45 +3803,45 @@ openclaw gateway --port 19001 } ``` -- الوجهة الافتراضية لإشعارات فشل Cron عبر جميع المهام. +- الوجهة الافتراضية لإشعارات فشل Cron عبر جميع الوظائف. - `mode`: ‏`"announce"` أو `"webhook"`؛ وتكون القيمة الافتراضية `"announce"` عندما تتوفر بيانات هدف كافية. -- `channel`: تجاوز القناة لتسليم announce. وتقوم `"last"` بإعادة استخدام آخر قناة تسليم معروفة. +- `channel`: تجاوز القناة لتسليم announce. وتعيد `"last"` استخدام آخر قناة تسليم معروفة. - `to`: هدف announce صريح أو عنوان URL لـ Webhook. وهو مطلوب لوضع webhook. -- `accountId`: تجاوز حساب اختياري للتسليم. -- تتجاوز `delivery.failureDestination` الخاصة بكل مهمة هذا الافتراضي العام. -- عندما لا تكون وجهة الفشل العامة ولا وجهة الفشل الخاصة بكل مهمة مضبوطة، تعود المهام التي تسلّم بالفعل عبر `announce` عند الفشل إلى هدف announce الأساسي نفسه. -- لا تكون `delivery.failureDestination` مدعومة إلا للمهام ذات `sessionTarget="isolated"` ما لم يكن `delivery.mode` الأساسي للمهمة هو `"webhook"`. +- `accountId`: تجاوز اختياري للحساب من أجل التسليم. +- يتجاوز `delivery.failureDestination` لكل وظيفة هذا الافتراضي العام. +- عندما لا تكون هناك وجهة فشل عامة أو خاصة بالوظيفة، فإن الوظائف التي تُسلِّم أصلًا عبر `announce` تعود احتياطيًا إلى هدف announce الأساسي نفسه عند الفشل. +- لا يُدعم `delivery.failureDestination` إلا للوظائف ذات `sessionTarget="isolated"` ما لم يكن `delivery.mode` الأساسي للوظيفة هو `"webhook"`. -راجع [مهام Cron](/ar/automation/cron-jobs). وتُتتبّع عمليات تنفيذ Cron المعزولة كـ [مهام خلفية](/ar/automation/tasks). +راجع [Cron Jobs](/ar/automation/cron-jobs). وتُتتبَّع عمليات تنفيذ Cron المعزولة كـ [background tasks](/ar/automation/tasks). --- -## متغيرات قوالب نماذج الوسائط +## متغيرات قالب نموذج الوسائط -العناصر النائبة للقوالب التي يتم توسيعها في `tools.media.models[].args`: +العناصر النائبة في القالب التي تُوسَّع في `tools.media.models[].args`: -| المتغير | الوصف | +| المتغير | الوصف | | ------------------ | ------------------------------------------------- | -| `{{Body}}` | نص الرسالة الواردة الكامل | -| `{{RawBody}}` | النص الخام (من دون أغلفة السجل/المرسل) | -| `{{BodyStripped}}` | النص بعد إزالة إشارات المجموعة | +| `{{Body}}` | متن الرسالة الواردة بالكامل | +| `{{RawBody}}` | المتن الخام (من دون أغلفة السجل/المرسل) | +| `{{BodyStripped}}` | المتن بعد إزالة إشارات المجموعات منه | | `{{From}}` | معرّف المرسل | | `{{To}}` | معرّف الوجهة | | `{{MessageSid}}` | معرّف رسالة القناة | | `{{SessionId}}` | UUID الجلسة الحالية | -| `{{IsNewSession}}` | `"true"` عند إنشاء جلسة جديدة | -| `{{MediaUrl}}` | pseudo-URL للوسائط الواردة | +| `{{IsNewSession}}` | القيمة `"true"` عند إنشاء جلسة جديدة | +| `{{MediaUrl}}` | عنوان pseudo-URL للوسائط الواردة | | `{{MediaPath}}` | مسار الوسائط المحلي | | `{{MediaType}}` | نوع الوسائط (صورة/صوت/مستند/…) | | `{{Transcript}}` | النص المفرغ للصوت | -| `{{Prompt}}` | Prompt الوسائط المحلول لإدخالات CLI | -| `{{MaxChars}}` | الحد الأقصى المحلول لأحرف الخرج لإدخالات CLI | +| `{{Prompt}}` | prompt الوسائط المحلول لإدخالات CLI | +| `{{MaxChars}}` | الحد الأقصى المحلول لأحرف المخرجات لإدخالات CLI | | `{{ChatType}}` | `"direct"` أو `"group"` | -| `{{GroupSubject}}` | موضوع المجموعة (أفضل جهد) | -| `{{GroupMembers}}` | معاينة أعضاء المجموعة (أفضل جهد) | -| `{{SenderName}}` | الاسم المعروض للمرسل (أفضل جهد) | -| `{{SenderE164}}` | رقم هاتف المرسل (أفضل جهد) | -| `{{Provider}}` | تلميح الموفّر (whatsapp أو telegram أو discord، إلخ.) | +| `{{GroupSubject}}` | موضوع المجموعة (بأفضل جهد) | +| `{{GroupMembers}}` | معاينة أعضاء المجموعة (بأفضل جهد) | +| `{{SenderName}}` | اسم العرض للمرسل (بأفضل جهد) | +| `{{SenderE164}}` | رقم هاتف المرسل (بأفضل جهد) | +| `{{Provider}}` | تلميح المزوّد (whatsapp أو telegram أو discord، إلخ.) | --- @@ -3874,12 +3863,12 @@ openclaw gateway --port 19001 **سلوك الدمج:** - ملف واحد: يستبدل الكائن الحاوي. -- مصفوفة ملفات: تُدمج بعمق حسب الترتيب (اللاحق يتجاوز السابق). -- المفاتيح الشقيقة: تُدمج بعد التضمينات (وتتجاوز القيم المضمنة). +- مصفوفة ملفات: تُدمَج عميقًا بالترتيب (واللاحق يتجاوز السابق). +- المفاتيح الشقيقة: تُدمَج بعد التضمينات (وتتجاوز القيم المضمَّنة). - التضمينات المتداخلة: حتى 10 مستويات عمق. -- المسارات: تُحل نسبةً إلى الملف الذي يتضمنها، لكن يجب أن تبقى داخل دليل الإعدادات ذي المستوى الأعلى (`dirname` الخاص بـ `openclaw.json`). وتُسمح الصيغ المطلقة/`../` فقط عندما تظل تُحل داخل ذلك الحد. +- المسارات: تُحل نسبةً إلى الملف المتضمِّن، لكن يجب أن تبقى داخل دليل الإعدادات ذي المستوى الأعلى (`dirname` الخاص بـ `openclaw.json`). وتُسمح الصيغ المطلقة/`../` فقط عندما تظل تُحل داخل ذلك الحد. - الأخطاء: رسائل واضحة للملفات المفقودة، وأخطاء التحليل، والتضمينات الدائرية. --- -_ذو صلة: [الإعدادات](/ar/gateway/configuration) · [أمثلة الإعدادات](/ar/gateway/configuration-examples) · [Doctor](/ar/gateway/doctor)_ +_ذو صلة: [الإعدادات](/ar/gateway/configuration) · [أمثلة على الإعدادات](/ar/gateway/configuration-examples) · [Doctor](/ar/gateway/doctor)_ diff --git a/docs/ar/gateway/protocol.md b/docs/ar/gateway/protocol.md index ed8c75530..61e1feb83 100644 --- a/docs/ar/gateway/protocol.md +++ b/docs/ar/gateway/protocol.md @@ -1,34 +1,34 @@ --- read_when: - - تنفيذ عملاء WS لـ Gateway أو تحديثهم - - تصحيح أخطاء عدم تطابق البروتوكول أو حالات فشل الاتصال + - تنفيذ عملاء Gateway WS أو تحديثهم + - تصحيح حالات عدم تطابق البروتوكول أو حالات فشل الاتصال - إعادة توليد مخطط/نماذج البروتوكول -summary: 'بروتوكول WebSocket لـ Gateway: المصافحة، الإطارات، إدارة الإصدارات' +summary: 'بروتوكول Gateway WebSocket: المصافحة، الإطارات، إصدار النسخ' title: بروتوكول Gateway x-i18n: - generated_at: "2026-04-16T07:18:16Z" + generated_at: "2026-04-18T07:14:59Z" model: gpt-5.4 provider: openai - source_hash: 683e61ebe993a2d739bc34860060b0e3eda36b5c57267a2bcc03d177ec612fb3 + source_hash: 4f0eebcfdd8c926c90b4753a6d96c59e3134ddb91740f65478f11eb75be85e41 source_path: gateway/protocol.md workflow: 15 --- # بروتوكول Gateway ‏(WebSocket) -يُعد بروتوكول WS الخاص بـ Gateway **مستوى التحكم الوحيد + ناقل العقد** لـ +يُعد بروتوكول Gateway WS **مستوى التحكم الوحيد + ناقل العقد** في OpenClaw. تتصل جميع العملاء (CLI، وواجهة الويب، وتطبيق macOS، وعقد iOS/Android، -والعقد عديمة الواجهة) عبر WebSocket وتُعلن **الدور** + **النطاق** الخاصين بها وقت -المصافحة. +والعقد عديمة الواجهة) عبر WebSocket وتُصرّح عن **الدور** + **النطاق** +في وقت المصافحة. ## النقل -- WebSocket، وإطارات نصية بحمولة JSON. +- WebSocket، بإطارات نصية تحتوي على حمولات JSON. - يجب أن يكون الإطار الأول **بالضرورة** طلب `connect`. ## المصافحة (`connect`) -Gateway → العميل (تحدي ما قبل الاتصال): +Gateway ← العميل (تحدي ما قبل الاتصال): ```json { @@ -38,7 +38,7 @@ Gateway → العميل (تحدي ما قبل الاتصال): } ``` -العميل → Gateway: +العميل ← Gateway: ```json { @@ -73,7 +73,7 @@ Gateway → العميل (تحدي ما قبل الاتصال): } ``` -Gateway → العميل: +Gateway ← العميل: ```json { @@ -95,10 +95,23 @@ Gateway → العميل: } ``` -`server` و`features` و`snapshot` و`policy` كلها مطلوبة بحسب المخطط -(`src/gateway/protocol/schema/frames.ts`). ويُعد كل من `auth` و`canvasHostUrl` اختياريًا. +تُعد الحقول `server` و`features` و`snapshot` و`policy` مطلوبة جميعًا بحسب المخطط +(`src/gateway/protocol/schema/frames.ts`). ويُعد `canvasHostUrl` اختياريًا. وتعرض +`auth` الدور/النطاقات التي تم التفاوض عليها عند توفرها، وتتضمن `deviceToken` +عندما يصدر الـ gateway واحدًا. -عند إصدار رمز جهاز مميز، يتضمن `hello-ok` أيضًا: +عند عدم إصدار رمز جهاز مميز، يمكن أن تعرض `hello-ok.auth` الأذونات التي تم التفاوض عليها رغم ذلك: + +```json +{ + "auth": { + "role": "operator", + "scopes": ["operator.read", "operator.write"] + } +} +``` + +عند إصدار رمز جهاز مميز، تتضمن `hello-ok` أيضًا: ```json { @@ -110,8 +123,7 @@ Gateway → العميل: } ``` -أثناء تسليم bootstrap الموثوق، قد يتضمن `hello-ok.auth` أيضًا إدخالات أدوار إضافية -مقيدة ضمن `deviceTokens`: +أثناء تسليم التمهيد الموثوق، قد تتضمن `hello-ok.auth` أيضًا إدخالات أدوار إضافية مقيّدة في `deviceTokens`: ```json { @@ -130,14 +142,14 @@ Gateway → العميل: } ``` -في تدفق bootstrap المدمج للعقدة/المشغّل، يبقى الرمز المميز الأساسي للعقدة -`scopes: []`، وأي رمز مميز للمشغّل يتم تسليمه يبقى مقيدًا بقائمة السماح الخاصة -بمشغّل bootstrap (`operator.approvals` و`operator.read` و`operator.talk.secrets` -و`operator.write`). وتظل فحوصات النطاق في bootstrap ذات بادئة مرتبطة بالدور: -إدخالات المشغّل تلبّي فقط طلبات المشغّل، بينما لا تزال الأدوار غير التابعة -للمشغّل تحتاج إلى نطاقات ضمن بادئة الدور الخاصة بها. +في تدفق التمهيد المضمن للعقدة/المشغّل، يبقى رمز العقدة الأساسي +`scopes: []` وأي رمز مشغّل مُسلَّم يظل مقيّدًا بقائمة سماح مشغّل التمهيد +(`operator.approvals`, `operator.read`, +`operator.talk.secrets`, `operator.write`). وتظل عمليات التحقق من نطاقات التمهيد +مسبوقة بالدور: لا تلبّي إدخالات المشغّل إلا طلبات المشغّل، وما زالت الأدوار غير المشغّلة +تحتاج إلى نطاقات تحت بادئة دورها الخاصة. -### مثال للعقدة +### مثال على عقدة ```json { @@ -174,18 +186,18 @@ Gateway → العميل: ## التأطير -- **الطلب**: `{type:"req", id, method, params}` -- **الاستجابة**: `{type:"res", id, ok, payload|error}` -- **الحدث**: `{type:"event", event, payload, seq?, stateVersion?}` +- **طلب**: `{type:"req", id, method, params}` +- **استجابة**: `{type:"res", id, ok, payload|error}` +- **حدث**: `{type:"event", event, payload, seq?, stateVersion?}` -تتطلب الطرق ذات الآثار الجانبية **مفاتيح idempotency** (راجع المخطط). +تتطلب الأساليب ذات الآثار الجانبية **مفاتيح idempotency** (راجع المخطط). ## الأدوار + النطاقات ### الأدوار - `operator` = عميل مستوى التحكم (CLI/UI/الأتمتة). -- `node` = مضيف القدرات (camera/screen/canvas/system.run). +- `node` = مضيف الإمكانات (camera/screen/canvas/system.run). ### النطاقات (`operator`) @@ -201,321 +213,320 @@ Gateway → العميل: يتطلب `talk.config` مع `includeSecrets: true` النطاق `operator.talk.secrets` (أو `operator.admin`). -قد تطلب طرق Gateway RPC المسجلة من Plugin نطاق مشغّل خاصًا بها، لكن بادئات -الإدارة الأساسية المحجوزة (`config.*` و`exec.approvals.*` و`wizard.*` و`update.*`) -تُحل دائمًا إلى `operator.admin`. +قد تطلب أساليب Gateway RPC المسجّلة بواسطة Plugin نطاق مشغّل خاصًا بها، لكن +بادئات الإدارة الأساسية المحجوزة (`config.*`, `exec.approvals.*`, `wizard.*`, +`update.*`) تُحل دائمًا إلى `operator.admin`. -نطاق الطريقة ليس سوى البوابة الأولى. بعض أوامر الشرطة المائلة التي يتم الوصول -إليها عبر `chat.send` تطبق فحوصات أكثر صرامة على مستوى الأمر فوق ذلك. على سبيل -المثال، تتطلب عمليات الكتابة الدائمة لـ `/config set` و`/config unset` -النطاق `operator.admin`. +يُعد نطاق الأسلوب هو بوابة التحقق الأولى فقط. فبعض أوامر الشرطة المائلة التي يتم الوصول إليها +عبر `chat.send` تطبّق عمليات تحقق أكثر صرامة على مستوى الأمر فوق ذلك. على سبيل المثال، +تتطلب عمليات الكتابة الدائمة في `/config set` و`/config unset` النطاق `operator.admin`. -يحتوي `node.pair.approve` أيضًا على فحص نطاق إضافي وقت الموافقة فوق نطاق الطريقة -الأساسي: +ويمتلك `node.pair.approve` أيضًا تحقق نطاق إضافيًا في وقت الموافقة فوق نطاق الأسلوب الأساسي: -- الطلبات من دون أوامر: `operator.pairing` -- الطلبات التي تتضمن أوامر عقدة غير تنفيذية: `operator.pairing` + `operator.write` +- الطلبات بلا أوامر: `operator.pairing` +- الطلبات التي تحتوي على أوامر عقدة غير تنفيذية: `operator.pairing` + `operator.write` - الطلبات التي تتضمن `system.run` أو `system.run.prepare` أو `system.which`: `operator.pairing` + `operator.admin` ### `caps`/`commands`/`permissions` (`node`) -تعلن العقد مطالبات القدرات عند وقت الاتصال: +تُصرّح العقد بادعاءات الإمكانات عند وقت الاتصال: -- `caps`: فئات القدرات عالية المستوى. -- `commands`: قائمة سماح الأوامر للاستدعاء. +- `caps`: فئات إمكانات عالية المستوى. +- `commands`: قائمة سماح الأوامر لعملية invoke. - `permissions`: مفاتيح تبديل دقيقة (مثل `screen.record` و`camera.capture`). -يتعامل Gateway مع هذه القيم على أنها **مطالبات** ويفرض قوائم السماح على جانب الخادم. +يتعامل Gateway مع هذه على أنها **ادعاءات** ويفرض قوائم سماح من جهة الخادم. ## الحضور - يعيد `system-presence` إدخالات مفهرسة بحسب هوية الجهاز. -- تتضمن إدخالات الحضور `deviceId` و`roles` و`scopes` لكي تتمكن واجهات المستخدم من عرض صف واحد لكل جهاز +- تتضمن إدخالات الحضور `deviceId` و`roles` و`scopes` بحيث يمكن لواجهات المستخدم عرض صف واحد لكل جهاز حتى عندما يتصل بصفته **operator** و**node** معًا. -## عائلات طرق RPC الشائعة +## عائلات أساليب RPC الشائعة -هذه الصفحة ليست تفريغًا مولدًا كاملًا، لكن سطح WS العام أوسع من أمثلة -المصافحة/المصادقة الواردة أعلاه. وهذه هي عائلات الطرق الرئيسية التي يعرّضها -Gateway اليوم. +هذه الصفحة ليست تفريغًا كاملًا مُولّدًا، لكن سطح WS العام أوسع +من أمثلة المصافحة/المصادقة أعلاه. وهذه هي عائلات الأساليب الرئيسية التي +يعرّضها Gateway اليوم. -تُعد `hello-ok.features.methods` قائمة اكتشاف محافظة مبنية من -`src/gateway/server-methods-list.ts` إضافةً إلى صادرات الطرق المحمّلة من -Plugin/channel. تعامل معها على أنها لاكتشاف الميزات، لا على أنها تفريغ مولد -لكل مساعد قابل للاستدعاء مُنفّذ في `src/gateway/server-methods/*.ts`. +تُعد `hello-ok.features.methods` قائمة اكتشاف متحفظة مبنية من +`src/gateway/server-methods-list.ts` بالإضافة إلى صادرات أساليب Plugins/القنوات المحمّلة. +تعامل معها على أنها لاكتشاف الميزات، لا كتفريغ مُولّد لكل مساعد قابل للاستدعاء +ومنفذ في `src/gateway/server-methods/*.ts`. ### النظام والهوية -- يعيد `health` لقطة الحالة الصحية المخزنة مؤقتًا لـ gateway أو التي جرى فحصها حديثًا. -- يعيد `status` ملخص gateway بأسلوب `/status`؛ وتُضمَّن الحقول الحساسة فقط - لعملاء المشغّل ذوي نطاق الإدارة. -- يعيد `gateway.identity.get` هوية جهاز gateway المستخدمة في تدفقات relay - والإقران. -- يعيد `system-presence` لقطة الحضور الحالية للأجهزة المتصلة من نوع - operator/node. -- يضيف `system-event` حدث نظام ويمكنه تحديث/بث سياق الحضور. +- يعيد `health` لقطة صحة الـ gateway المخبأة أو التي جرى فحصها حديثًا. +- يعيد `status` ملخص الـ gateway على نمط `/status`؛ وتُضمَّن الحقول الحساسة + فقط لعملاء المشغّل ذوي النطاق الإداري. +- يعيد `gateway.identity.get` هوية جهاز الـ gateway المستخدمة في تدفقات relay + والاقتران. +- يعيد `system-presence` لقطة الحضور الحالية للأجهزة المتصلة + من نوع operator/node. +- يضيف `system-event` حدث نظام ويمكنه تحديث/بث سياق + الحضور. - يعيد `last-heartbeat` أحدث حدث Heartbeat محفوظ. - يبدّل `set-heartbeats` معالجة Heartbeat على الـ gateway. ### النماذج والاستخدام - يعيد `models.list` فهرس النماذج المسموح بها وقت التشغيل. -- يعيد `usage.status` نوافذ استخدام المزوّد/ملخصات الحصة المتبقية. +- يعيد `usage.status` ملخصات نوافذ استخدام المزوّد/الحصة المتبقية. - يعيد `usage.cost` ملخصات تكلفة الاستخدام المجمعة لنطاق زمني. -- يعيد `doctor.memory.status` جاهزية الذاكرة المتجهية / التضمين لمساحة عمل - الوكيل الافتراضية النشطة. +- يعيد `doctor.memory.status` جاهزية الذاكرة المتجهية / التضمينات + لمساحة عمل الوكيل الافتراضي النشطة. - يعيد `sessions.usage` ملخصات الاستخدام لكل جلسة. - يعيد `sessions.usage.timeseries` سلسلة زمنية للاستخدام لجلسة واحدة. - يعيد `sessions.usage.logs` إدخالات سجل الاستخدام لجلسة واحدة. ### القنوات ومساعدات تسجيل الدخول -- يعيد `channels.status` ملخصات حالة القنوات/Plugin المدمجة والمجمعة. -- يسجّل `channels.logout` الخروج من قناة/حساب محدد حيث تدعم القناة - تسجيل الخروج. -- يبدأ `web.login.start` تدفق تسجيل دخول QR/الويب لمزوّد قناة الويب الحالي - القادر على QR. -- ينتظر `web.login.wait` اكتمال تدفق تسجيل دخول QR/الويب هذا ويبدأ القناة - عند النجاح. -- يرسل `push.test` دفعة APNs اختبارية إلى عقدة iOS مسجلة. -- يعيد `voicewake.get` مشغلات كلمة التنبيه المخزنة. -- يحدّث `voicewake.set` مشغلات كلمة التنبيه ويبث التغيير. +- يعيد `channels.status` ملخصات حالة القنوات/Plugins المضمنة والمجمعة. +- يسجّل `channels.logout` الخروج من قناة/حساب محدد حيثما كانت القناة + تدعم تسجيل الخروج. +- يبدأ `web.login.start` تدفق تسجيل دخول QR/ويب لمزوّد قناة الويب + القادر على QR الحالي. +- ينتظر `web.login.wait` اكتمال تدفق تسجيل دخول QR/ويب هذا ويبدأ + القناة عند النجاح. +- يرسل `push.test` إشعار APNs تجريبيًا إلى عقدة iOS مسجلة. +- يعيد `voicewake.get` محفزات كلمات التنبيه المخزنة. +- يحدّث `voicewake.set` محفزات كلمات التنبيه ويبث التغيير. ### المراسلة والسجلات -- يُعد `send` RPC التسليم الصادر المباشر لعمليات الإرسال المستهدفة إلى - القناة/الحساب/المحادثة خارج مشغّل الدردشة. -- يعيد `logs.tail` ذيل سجل ملفات gateway المهيأ مع عناصر التحكم - cursor/limit والحد الأقصى للبايتات. +- يُعد `send` أسلوب RPC للتسليم الصادر المباشر لعمليات الإرسال + الموجّهة إلى قناة/حساب/محادثة خارج مشغّل الدردشة. +- يعيد `logs.tail` ذيل سجل ملفات الـ gateway المُهيأ مع المؤشر/الحد + وعناصر التحكم في الحد الأقصى للبايتات. ### Talk وTTS -- يعيد `talk.config` حمولة تهيئة Talk الفعالة؛ ويتطلب `includeSecrets` +- يعيد `talk.config` حمولة إعدادات Talk الفعالة؛ ويتطلب `includeSecrets` النطاق `operator.talk.secrets` (أو `operator.admin`). -- يضبط `talk.mode` حالة وضع Talk الحالية لعملاء WebChat/Control UI - ويقوم ببثها. -- يقوم `talk.speak` بتوليف الكلام عبر مزود كلام Talk النشط. -- يعيد `tts.status` حالة تمكين TTS، والمزوّد النشط، ومزوّدي الاحتياط، - وحالة تهيئة المزوّد. -- يعيد `tts.providers` قائمة مزوّدي TTS الظاهرين. +- يضبط `talk.mode` حالة وضع Talk الحالية ويبثها لعملاء WebChat/Control UI. +- يُركّب `talk.speak` الكلام عبر مزوّد الكلام النشط لـ Talk. +- يعيد `tts.status` حالة تمكين TTS، والمزوّد النشط، ومزوّدي الرجوع الاحتياطي، + وحالة إعدادات المزوّد. +- يعيد `tts.providers` جرد مزوّدي TTS المرئيين. - يبدّل `tts.enable` و`tts.disable` حالة تفضيلات TTS. - يحدّث `tts.setProvider` مزوّد TTS المفضل. -- ينفّذ `tts.convert` تحويل نص إلى كلام لمرة واحدة. +- يشغّل `tts.convert` تحويل نص إلى كلام لمرة واحدة. -### الأسرار والتهيئة والتحديث والمعالج +### الأسرار والإعدادات والتحديث والمعالج -- يعيد `secrets.reload` حل SecretRefs النشطة ويستبدل حالة الأسرار وقت التشغيل +- يعيد `secrets.reload` حل SecretRefs النشطة ويبدّل حالة الأسرار وقت التشغيل فقط عند النجاح الكامل. -- يحل `secrets.resolve` تعيينات الأسرار المستهدفة بالأوامر لمجموعة +- يعيد `secrets.resolve` حل تعيينات الأسرار المستهدفة للأوامر لمجموعة أوامر/أهداف محددة. -- يعيد `config.get` لقطة التهيئة الحالية وقيمة hash. -- يكتب `config.set` حمولة تهيئة تم التحقق منها. -- يدمج `config.patch` تحديث تهيئة جزئيًا. -- يتحقق `config.apply` من حمولة التهيئة الكاملة ويستبدلها. -- يعيد `config.schema` حمولة مخطط التهيئة الحي المستخدم من Control UI وأدوات +- يعيد `config.get` لقطة الإعدادات الحالية وhash الخاص بها. +- يكتب `config.set` حمولة إعدادات تم التحقق من صحتها. +- يدمج `config.patch` تحديث إعدادات جزئيًا. +- يتحقق `config.apply` من حمولة الإعدادات الكاملة ويستبدلها. +- يعيد `config.schema` حمولة مخطط الإعدادات الحية التي تستخدمها Control UI وأدوات CLI: المخطط، و`uiHints`، والإصدار، وبيانات التوليد الوصفية، بما في ذلك - بيانات مخطط Plugin + channel الوصفية عندما يتمكن وقت التشغيل من تحميلها. يتضمن - المخطط بيانات الحقول `title` / `description` المشتقة من نفس التسميات - ونصوص المساعدة التي تستخدمها واجهة المستخدم، بما في ذلك الفروع المتداخلة - للكائنات، والرموز العامة، وعناصر المصفوفات، وتركيبات - `anyOf` / `oneOf` / `allOf` عندما تتوفر وثائق مطابقة للحقول. -- يعيد `config.schema.lookup` حمولة بحث محددة بالمسار لمسار تهيئة واحد: - المسار المطبّع، وعقدة مخطط سطحية، و`hint` المطابق + `hintPath`، - وملخصات الأبناء المباشرين للتنقل التفصيلي في UI/CLI. - - تحتفظ عقد مخطط البحث بالوثائق المواجهة للمستخدم وحقول التحقق الشائعة: + بيانات مخطط Plugin + القناة عندما يستطيع وقت التشغيل تحميلها. ويتضمن المخطط + بيانات `title` / `description` للحقل المستمدة من نفس التسميات + ونصوص المساعدة المستخدمة في واجهة المستخدم، بما في ذلك الكائنات المتداخلة، + وعناصر wildcard، وعناصر المصفوفات، وفروع التركيب `anyOf` / `oneOf` / `allOf` + عندما توجد وثائق حقل مطابقة. +- يعيد `config.schema.lookup` حمولة بحث مقيّدة بالمسار لمسار إعدادات + واحد: المسار الموحّد، وعقدة مخطط سطحية، و`hint` المطابق + `hintPath`، + وملخصات الأبناء المباشرين للتنقل المتدرج في UI/CLI. + - تحتفظ عقد مخطط البحث بالتوثيق المواجه للمستخدم وحقول التحقق الشائعة: `title` و`description` و`type` و`enum` و`const` و`format` و`pattern`، وحدود الأرقام/السلاسل/المصفوفات/الكائنات، وأعلام منطقية مثل `additionalProperties` و`deprecated` و`readOnly` و`writeOnly`. - - تعرض ملخصات الأبناء `key` و`path` المطبّع و`type` و`required` و`hasChildren`، + - تعرض ملخصات الأبناء `key` و`path` الموحّد و`type` و`required` و`hasChildren`، بالإضافة إلى `hint` / `hintPath` المطابقين. -- يشغّل `update.run` تدفق تحديث gateway ويجدول إعادة تشغيل فقط عندما +- يشغّل `update.run` تدفق تحديث الـ gateway ويجدول إعادة تشغيل فقط عندما ينجح التحديث نفسه. -- توفّر `wizard.start` و`wizard.next` و`wizard.status` و`wizard.cancel` - معالج الإعداد الأولي عبر WS RPC. +- تعرض `wizard.start` و`wizard.next` و`wizard.status` و`wizard.cancel` + معالج الإعداد الأوّلي عبر WS RPC. ### العائلات الرئيسية الحالية #### مساعدات الوكيل ومساحة العمل -- يعيد `agents.list` إدخالات الوكلاء المهيأة. +- يعيد `agents.list` إدخالات الوكلاء المُهيأة. - تدير `agents.create` و`agents.update` و`agents.delete` سجلات الوكلاء وربط مساحة العمل. - تدير `agents.files.list` و`agents.files.get` و`agents.files.set` ملفات - مساحة عمل bootstrap المكشوفة لوكيل. -- يعيد `agent.identity.get` هوية المساعد الفعالة لوكيل أو جلسة. -- ينتظر `agent.wait` انتهاء التشغيل ويعيد اللقطة الطرفية عند توفرها. + مساحة العمل الخاصة بالتمهيد المعروضة لوكيل. +- يعيد `agent.identity.get` هوية المساعد الفعالة لوكيل أو + جلسة. +- ينتظر `agent.wait` اكتمال التشغيل ويعيد اللقطة النهائية عند + توفرها. #### التحكم في الجلسة - يعيد `sessions.list` فهرس الجلسات الحالي. -- يبدّل `sessions.subscribe` و`sessions.unsubscribe` اشتراكات أحداث تغيّر الجلسة +- يبدّل `sessions.subscribe` و`sessions.unsubscribe` اشتراكات أحداث تغيّر الجلسات لعميل WS الحالي. - يبدّل `sessions.messages.subscribe` و`sessions.messages.unsubscribe` اشتراكات أحداث النصوص/الرسائل لجلسة واحدة. -- يعيد `sessions.preview` معاينات نصوص مقيدة لمفاتيح جلسات محددة. -- يقوم `sessions.resolve` بحل هدف جلسة أو جعله بالشكل القياسي. +- يعيد `sessions.preview` معاينات نصوص محصورة لمفاتيح جلسات + محددة. +- يحل `sessions.resolve` هدف جلسة أو يوحّده. - ينشئ `sessions.create` إدخال جلسة جديدًا. - يرسل `sessions.send` رسالة إلى جلسة موجودة. - يُعد `sessions.steer` صيغة المقاطعة وإعادة التوجيه لجلسة نشطة. - يوقف `sessions.abort` العمل النشط لجلسة ما. -- يحدّث `sessions.patch` بيانات تعريف الجلسة/التجاوزات. -- تنفّذ `sessions.reset` و`sessions.delete` و`sessions.compact` - صيانة الجلسة. -- يعيد `sessions.get` صف الجلسة المخزّن الكامل. -- لا يزال تنفيذ الدردشة يستخدم `chat.history` و`chat.send` و`chat.abort` و +- يحدّث `sessions.patch` بيانات الجلسة الوصفية/التجاوزات. +- تنفّذ `sessions.reset` و`sessions.delete` و`sessions.compact` صيانة + الجلسة. +- يعيد `sessions.get` صف الجلسة المخزن كاملًا. +- ما زال تنفيذ الدردشة يستخدم `chat.history` و`chat.send` و`chat.abort` و `chat.inject`. -- جرى تطبيع `chat.history` للعرض لعملاء UI: تُزال وسوم التوجيه المضمنة من - النص المرئي، وتُزال حمولات XML النصية العادية لاستدعاء الأدوات (بما في ذلك - `...` و`...` و - `...` و`...` و - كتل استدعاء الأدوات المقتطعة)، كما تُزال رموز التحكم بالنموذج المتسربة - بنمط ASCII/العرض الكامل، وتُحذف صفوف المساعد التي تتكون فقط من رموز صامتة - مثل `NO_REPLY` / `no_reply` تمامًا، ويمكن استبدال الصفوف كبيرة الحجم - بعناصر نائبة. +- يُطبَّع `chat.history` للعرض لعملاء UI: تُزال وسوم التوجيه المضمنة من + النص المرئي، وتُزال حمولات XML الخاصة باستدعاء الأدوات بالنص العادي (بما في ذلك + `...` و`...`، + و`...` و`...`، + وكتل استدعاء الأدوات المبتورة) ورموز التحكم الخاصة بالنموذج المتسربة بصيغة ASCII/العرض الكامل، + وتُحذف صفوف المساعد التي تحتوي فقط على رموز صامتة مثل `NO_REPLY` / + `no_reply` تمامًا، ويمكن استبدال الصفوف كبيرة الحجم بعناصر نائبة. -#### إقران الأجهزة ورموز الأجهزة المميزة +#### اقتران الأجهزة ورموز الأجهزة - يعيد `device.pair.list` الأجهزة المقترنة المعلقة والموافق عليها. - تدير `device.pair.approve` و`device.pair.reject` و`device.pair.remove` - سجلات إقران الأجهزة. -- يقوم `device.token.rotate` بتدوير رمز جهاز مقترن ضمن حدود الدور - والنطاق الموافق عليهما. -- يلغي `device.token.revoke` رمز جهاز مقترن. + سجلات اقتران الأجهزة. +- يدوّر `device.token.rotate` رمز جهاز مقترن ضمن حدود + الدور والنطاق الموافق عليهما. +- يلغي `device.token.revoke` رمز جهاز مقترنًا. -#### إقران العقد والاستدعاء والعمل المعلّق +#### اقتران العقدة والاستدعاء والعمل المعلّق - تغطي `node.pair.request` و`node.pair.list` و`node.pair.approve` و - `node.pair.reject` و`node.pair.verify` إقران العقد والتحقق من bootstrap. -- يعيد `node.list` و`node.describe` حالة العقد المعروفة/المتصلة. + `node.pair.reject` و`node.pair.verify` اقتران العقدة والتحقق من + التمهيد. +- يعيد `node.list` و`node.describe` حالة العقدة المعروفة/المتصلة. - يحدّث `node.rename` تسمية عقدة مقترنة. - يمرر `node.invoke` أمرًا إلى عقدة متصلة. - يعيد `node.invoke.result` نتيجة طلب استدعاء. -- يحمل `node.event` الأحداث الصادرة من العقدة عائدًا إلى gateway. -- يحدّث `node.canvas.capability.refresh` رموز canvas المميزة ذات النطاق المحدد. -- تُعد `node.pending.pull` و`node.pending.ack` واجهات API لطابور - العقدة المتصلة. -- تدير `node.pending.enqueue` و`node.pending.drain` العمل المعلق الدائم - للعقد غير المتصلة/غير المتاحة. +- يحمل `node.event` الأحداث الصادرة من العقدة إلى الـ gateway. +- يجدّد `node.canvas.capability.refresh` رموز إمكانات canvas + المقيّدة. +- تُعد `node.pending.pull` و`node.pending.ack` واجهات API لطابور العقدة + المتصلة. +- تدير `node.pending.enqueue` و`node.pending.drain` العمل المعلّق المتين + للعقد غير المتصلة/غير المتصلة حاليًا. #### عائلات الموافقات - تغطي `exec.approval.request` و`exec.approval.get` و`exec.approval.list` و - `exec.approval.resolve` طلبات موافقة exec لمرة واحدة إضافةً إلى + `exec.approval.resolve` طلبات موافقة التنفيذ لمرة واحدة بالإضافة إلى البحث/إعادة التشغيل للموافقات المعلقة. -- ينتظر `exec.approval.waitDecision` قرار موافقة exec واحدًا معلقًا ويعيد +- ينتظر `exec.approval.waitDecision` قرار موافقة تنفيذ واحدة معلقة ويعيد القرار النهائي (أو `null` عند انتهاء المهلة). -- تدير `exec.approvals.get` و`exec.approvals.set` لقطات سياسة موافقة exec - الخاصة بـ gateway. -- تدير `exec.approvals.node.get` و`exec.approvals.node.set` سياسة موافقة exec +- تدير `exec.approvals.get` و`exec.approvals.set` لقطات سياسة موافقات + التنفيذ في الـ gateway. +- تدير `exec.approvals.node.get` و`exec.approvals.node.set` سياسة موافقات التنفيذ المحلية للعقدة عبر أوامر relay الخاصة بالعقدة. - تغطي `plugin.approval.request` و`plugin.approval.list` و `plugin.approval.waitDecision` و`plugin.approval.resolve` - تدفقات الموافقة المعرّفة من Plugin. + تدفقات الموافقات التي يعرّفها Plugin. #### عائلات رئيسية أخرى - الأتمتة: - - يجدول `wake` حقن نص تنبيه فوريًا أو عند Heartbeat التالي - - `cron.list` و`cron.status` و`cron.add` و`cron.update` و`cron.remove` و - `cron.run` و`cron.runs` + - يجدول `wake` إدخال نص تنبيه فوري أو عند Heartbeat التالي + - `cron.list` و`cron.status` و`cron.add` و`cron.update` و`cron.remove`، + و`cron.run` و`cron.runs` - Skills/الأدوات: `commands.list` و`skills.*` و`tools.catalog` و`tools.effective` ### عائلات الأحداث الشائعة -- `chat`: تحديثات دردشة UI مثل `chat.inject` وأحداث الدردشة الأخرى الخاصة - بالنص فقط. -- `session.message` و`session.tool`: تحديثات النص/تدفق الأحداث لجلسة - مشترَك فيها. +- `chat`: تحديثات دردشة UI مثل `chat.inject` وغيرها من + أحداث الدردشة الخاصة بالنص فقط. +- `session.message` و`session.tool`: تحديثات النص/دفق الأحداث لجلسة + مشترَك بها. - `sessions.changed`: تغيّر فهرس الجلسات أو بياناتها الوصفية. - `presence`: تحديثات لقطة حضور النظام. -- `tick`: حدث keepalive / liveliness دوري. -- `health`: تحديث لقطة سلامة gateway. -- `heartbeat`: تحديث تدفق أحداث Heartbeat. +- `tick`: حدث keepalive / حيوية دوري. +- `health`: تحديث لقطة صحة الـ gateway. +- `heartbeat`: تحديث دفق أحداث Heartbeat. - `cron`: حدث تغيّر تشغيل/مهمة Cron. -- `shutdown`: إشعار إيقاف تشغيل gateway. -- `node.pair.requested` / `node.pair.resolved`: دورة حياة إقران العقدة. -- `node.invoke.request`: بث طلب استدعاء العقدة. +- `shutdown`: إشعار إيقاف الـ gateway. +- `node.pair.requested` / `node.pair.resolved`: دورة حياة اقتران العقدة. +- `node.invoke.request`: بث طلب استدعاء عقدة. - `device.pair.requested` / `device.pair.resolved`: دورة حياة الجهاز المقترن. -- `voicewake.changed`: تغيّرت تهيئة مشغّل كلمة التنبيه. +- `voicewake.changed`: تغيّر إعدادات محفز كلمات التنبيه. - `exec.approval.requested` / `exec.approval.resolved`: دورة حياة - موافقة exec. + موافقة التنفيذ. - `plugin.approval.requested` / `plugin.approval.resolved`: دورة حياة موافقة Plugin. -### طرق مساعدة العقدة +### أساليب مساعدة العقدة - يمكن للعقد استدعاء `skills.bins` لجلب القائمة الحالية للملفات التنفيذية الخاصة بـ Skills - للتحقق من السماح التلقائي. + من أجل عمليات التحقق التلقائية من السماح. -### طرق مساعدة المشغّل +### أساليب مساعدة المشغّل -- يمكن للمشغّلين استدعاء `commands.list` (`operator.read`) لجلب قائمة الأوامر - وقت التشغيل لوكيل. +- يمكن للمشغّلين استدعاء `commands.list` (`operator.read`) لجلب مخزون الأوامر وقت التشغيل + لوكيل ما. - `agentId` اختياري؛ احذفه لقراءة مساحة عمل الوكيل الافتراضية. - يتحكم `scope` في السطح الذي يستهدفه `name` الأساسي: - - يعيد `text` رمز الأمر النصي الأساسي من دون الشرطة المائلة `/` - - يعيد `native` ومسار `both` الافتراضي أسماء أصلية مدركة للمزوّد + - يعيد `text` رمز أمر النص الأساسي دون الشرطة المائلة البادئة `/` + - يعيد `native` ومسار `both` الافتراضي أسماء native المدركة للمزوّد عند توفرها - - يحمل `textAliases` الأسماء المستعارة الدقيقة ذات الشرطة المائلة مثل - `/model` و`/m`. - - يحمل `nativeName` اسم الأمر الأصلي المدرك للمزوّد عندما يكون موجودًا. - - `provider` اختياري ولا يؤثر إلا في التسمية الأصلية وإتاحة أوامر Plugin - الأصلية. - - يؤدي `includeArgs=false` إلى حذف بيانات الوسائط التسلسلية من الاستجابة. -- يمكن للمشغّلين استدعاء `tools.catalog` (`operator.read`) لجلب فهرس الأدوات وقت التشغيل لوكيل. - تتضمن الاستجابة أدوات مجمعة وبيانات تعريف المصدر: + - يحمل `textAliases` الأسماء المستعارة الدقيقة ذات الشرطة المائلة مثل `/model` و`/m`. + - يحمل `nativeName` اسم الأمر native المدرك للمزوّد عندما يوجد. + - `provider` اختياري ويؤثر فقط في التسمية native وتوفر أوامر Plugin + native. + - يؤدي `includeArgs=false` إلى حذف بيانات الوسائط المسلسلة من الاستجابة. +- يمكن للمشغّلين استدعاء `tools.catalog` (`operator.read`) لجلب فهرس الأدوات وقت التشغيل لوكيل + ما. وتتضمن الاستجابة أدوات مجمّعة وبيانات وصفية للمصدر: - `source`: `core` أو `plugin` - - `pluginId`: مالك Plugin عندما تكون `source="plugin"` + - `pluginId`: مالك Plugin عندما يكون `source="plugin"` - `optional`: ما إذا كانت أداة Plugin اختيارية -- يمكن للمشغّلين استدعاء `tools.effective` (`operator.read`) لجلب فهرس الأدوات الفعّال - وقت التشغيل لجلسة. +- يمكن للمشغّلين استدعاء `tools.effective` (`operator.read`) لجلب + مخزون الأدوات الفعّال وقت التشغيل لجلسة ما. - `sessionKey` مطلوب. - - يستخلص gateway سياق وقت تشغيل موثوقًا من الجلسة على جانب الخادم بدلًا من قبول - سياق المصادقة أو التسليم المزوَّد من المستدعي. - - تكون الاستجابة ذات نطاق جلسة وتعكس ما يمكن للمحادثة النشطة استخدامه الآن، - بما في ذلك أدوات core وPlugin وchannel. -- يمكن للمشغّلين استدعاء `skills.status` (`operator.read`) لجلب قائمة - Skills المرئية لوكيل. + - يستمد الـ gateway سياق وقت تشغيل موثوقًا من الجلسة من جهة الخادم بدلًا من قبول + سياق مصادقة أو تسليم يزوّده المستدعي. + - تكون الاستجابة مقيّدة بالجلسة وتعكس ما يمكن للمحادثة النشطة استخدامه الآن، + بما في ذلك أدوات core وPlugin والقناة. +- يمكن للمشغّلين استدعاء `skills.status` (`operator.read`) لجلب + مخزون Skills المرئي لوكيل. - `agentId` اختياري؛ احذفه لقراءة مساحة عمل الوكيل الافتراضية. - - تتضمن الاستجابة الأهلية، والمتطلبات الناقصة، وفحوصات التهيئة، - وخيارات التثبيت المنقحة من دون كشف قيم الأسرار الخام. -- يمكن للمشغّلين استدعاء `skills.search` و`skills.detail` (`operator.read`) لبيانات - اكتشاف ClawHub الوصفية. + - تتضمن الاستجابة الأهلية، والمتطلبات المفقودة، وعمليات تحقق الإعدادات، + وخيارات التثبيت المنقحة دون كشف القيم السرية الخام. +- يمكن للمشغّلين استدعاء `skills.search` و`skills.detail` (`operator.read`) للحصول على + بيانات الاكتشاف الوصفية لـ ClawHub. - يمكن للمشغّلين استدعاء `skills.install` (`operator.admin`) في وضعين: - - وضع ClawHub: يثبّت `{ source: "clawhub", slug, version?, force? }` - مجلد skill في دليل `skills/` الخاص بمساحة عمل الوكيل الافتراضية. - - وضع مُثبّت Gateway: يشغّل `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }` - إجراء `metadata.openclaw.install` مُعلنًا على مضيف gateway. + - وضع ClawHub: `{ source: "clawhub", slug, version?, force? }` يثبّت + مجلد Skill في دليل `skills/` الخاص بمساحة عمل الوكيل الافتراضية. + - وضع مُثبّت Gateway: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }` + يشغّل إجراء `metadata.openclaw.install` مُعلَنًا على مضيف الـ gateway. - يمكن للمشغّلين استدعاء `skills.update` (`operator.admin`) في وضعين: - - يحدّث وضع ClawHub معرّف slug متتبعًا واحدًا أو جميع تثبيتات ClawHub - المتتبعة في مساحة عمل الوكيل الافتراضية. - - يقوم وضع التهيئة بترقيع قيم `skills.entries.` مثل `enabled` - و`apiKey` و`env`. + - يحدّث وضع ClawHub slug واحدًا متتبَّعًا أو جميع عمليات تثبيت ClawHub المتتبعة في + مساحة عمل الوكيل الافتراضية. + - يقوم وضع الإعدادات بترقيع قيم `skills.entries.` مثل `enabled`، + و`apiKey`، و`env`. -## موافقات Exec +## موافقات التنفيذ -- عندما يحتاج طلب exec إلى موافقة، يبث gateway الحدث `exec.approval.requested`. -- يحل عملاء المشغّل ذلك عبر استدعاء `exec.approval.resolve` (ويتطلب النطاق `operator.approvals`). -- بالنسبة إلى `host=node`، يجب أن يتضمن `exec.approval.request` القيمة `systemRunPlan` - (القيَم القياسية `argv`/`cwd`/`rawCommand`/بيانات تعريف الجلسة). وتُرفض الطلبات - التي تفتقد `systemRunPlan`. +- عندما يحتاج طلب تنفيذ إلى موافقة، يبث الـ gateway `exec.approval.requested`. +- يحل عملاء المشغّل ذلك عبر استدعاء `exec.approval.resolve` (يتطلب النطاق `operator.approvals`). +- بالنسبة إلى `host=node`، يجب أن يتضمن `exec.approval.request` الحقل `systemRunPlan` (الحقول القياسية `argv`/`cwd`/`rawCommand`/بيانات الجلسة الوصفية). وتُرفض الطلبات التي تفتقد `systemRunPlan`. - بعد الموافقة، تعيد استدعاءات `node.invoke system.run` الممررة استخدام - `systemRunPlan` القياسي هذا بوصفه السياق المرجعي للأمر/`cwd`/الجلسة. + `systemRunPlan` القياسي هذا باعتباره السياق المعتمد للأمر/‏`cwd`/الجلسة. - إذا عدّل مستدعٍ `command` أو`rawCommand` أو`cwd` أو`agentId` أو - `sessionKey` بين التحضير وتمرير `system.run` الموافق عليه نهائيًا، - يرفض gateway التشغيل بدلًا من الوثوق بالحمولة المعدلة. + `sessionKey` بين التحضير والتمرير النهائي الموافق عليه لـ `system.run`، فإن + الـ gateway يرفض التشغيل بدلًا من الثقة بالحمولة المعدّلة. -## بديل تسليم الوكيل +## الرجوع الاحتياطي لتسليم الوكيل -- يمكن أن تتضمن طلبات `agent` القيمة `deliver=true` لطلب تسليم صادر. -- يحافظ `bestEffortDeliver=false` على السلوك الصارم: تعيد أهداف التسليم غير المحلولة أو الداخلية فقط القيمة `INVALID_REQUEST`. -- يسمح `bestEffortDeliver=true` بالرجوع إلى التنفيذ ضمن الجلسة فقط عندما يتعذر حل مسار خارجي قابل للتسليم (على سبيل المثال جلسات internal/webchat أو إعدادات متعددة القنوات ملتبسة). +- يمكن أن تتضمن طلبات `agent` الحقل `deliver=true` لطلب التسليم الصادر. +- يُبقي `bestEffortDeliver=false` السلوك الصارم: إذ تُرجع أهداف التسليم غير المحلولة أو الداخلية فقط `INVALID_REQUEST`. +- يسمح `bestEffortDeliver=true` بالرجوع الاحتياطي إلى التنفيذ على مستوى الجلسة عندما لا يمكن حل أي مسار تسليم خارجي قابل للتسليم (مثلًا جلسات internal/webchat أو إعدادات متعددة القنوات ملتبسة). -## إدارة الإصدارات +## إصدار النسخ - يوجد `PROTOCOL_VERSION` في `src/gateway/protocol/schema/protocol-schemas.ts`. -- يرسل العملاء `minProtocol` + `maxProtocol`؛ ويرفض الخادم حالات عدم التطابق. +- يرسل العملاء `minProtocol` و`maxProtocol`؛ ويرفض الخادم حالات عدم التطابق. - تُولَّد المخططات + النماذج من تعريفات TypeBox: - `pnpm protocol:gen` - `pnpm protocol:gen:swift` @@ -524,116 +535,116 @@ Plugin/channel. تعامل معها على أنها لاكتشاف الميزا ### ثوابت العميل يستخدم العميل المرجعي في `src/gateway/client.ts` هذه القيم الافتراضية. وهذه القيم -مستقرة عبر البروتوكول v3 وهي خط الأساس المتوقع لعملاء الجهات الخارجية. +مستقرة عبر البروتوكول v3 وهي خط الأساس المتوقع للعملاء من الجهات الخارجية. | الثابت | الافتراضي | المصدر | | --- | --- | --- | | `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` | | مهلة الطلب (لكل RPC) | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) | | مهلة ما قبل المصادقة / تحدي الاتصال | `10_000` ms | `src/gateway/handshake-timeouts.ts` (التقييد `250`–`10_000`) | -| مهلة التراجع الأولية لإعادة الاتصال | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) | -| الحد الأقصى لمهلة التراجع لإعادة الاتصال | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) | -| تقييد إعادة المحاولة السريعة بعد إغلاق رمز الجهاز المميز | `250` ms | `src/gateway/client.ts` | +| التراجع الأولي لإعادة الاتصال | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) | +| الحد الأقصى للتراجع لإعادة الاتصال | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) | +| تقييد إعادة المحاولة السريعة بعد إغلاق رمز الجهاز | `250` ms | `src/gateway/client.ts` | | مهلة السماح قبل `terminate()` في الإيقاف القسري | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` | | المهلة الافتراضية لـ `stopAndWait()` | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` | | الفاصل الزمني الافتراضي لـ tick (قبل `hello-ok`) | `30_000` ms | `src/gateway/client.ts` | | إغلاق مهلة tick | الرمز `4000` عندما يتجاوز الصمت `tickIntervalMs * 2` | `src/gateway/client.ts` | -| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024` (25 MB) | `src/gateway/server-constants.ts` | +| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024` ‏(25 MB) | `src/gateway/server-constants.ts` | -يعلن الخادم عن القيم الفعالة `policy.tickIntervalMs` و`policy.maxPayload` -و`policy.maxBufferedBytes` في `hello-ok`؛ ويجب على العملاء الالتزام بهذه القيم +يعلن الخادم عن القيم الفعالة لـ `policy.tickIntervalMs` و`policy.maxPayload` +و`policy.maxBufferedBytes` في `hello-ok`؛ ويجب على العملاء احترام هذه القيم بدلًا من القيم الافتراضية السابقة للمصافحة. ## المصادقة -- تستخدم مصادقة Gateway ذات السر المشترك `connect.params.auth.token` أو - `connect.params.auth.password`، بحسب وضع المصادقة المهيأ. -- الأوضاع الحاملة للهوية مثل Tailscale Serve +- تستخدم مصادقة الـ gateway ذات السر المشترك `connect.params.auth.token` أو + `connect.params.auth.password`، بحسب وضع المصادقة المُهيأ. +- أوضاع حمل الهوية مثل Tailscale Serve (`gateway.auth.allowTailscale: true`) أو `gateway.auth.mode: "trusted-proxy"` غير المعتمد على loopback - تستوفي فحص مصادقة الاتصال من ترويسات الطلب بدلًا من `connect.params.auth.*`. -- يتجاوز `gateway.auth.mode: "none"` الخاص بالإدخال الخاص مصادقة الاتصال - ذات السر المشترك بالكامل؛ لا تعرّض هذا الوضع على إدخال عام/غير موثوق. -- بعد الإقران، يُصدر Gateway **رمز جهاز مميزًا** ذا نطاق محدد بحسب دور الاتصال + نطاقاته. - ويُعاد ضمن `hello-ok.auth.deviceToken` ويجب أن يحتفظ به العميل - للاتصالات المستقبلية. -- يجب على العملاء حفظ `hello-ok.auth.deviceToken` الأساسي بعد أي + تستوفي فحص مصادقة الاتصال من + ترويسات الطلب بدلًا من `connect.params.auth.*`. +- يتجاوز `gateway.auth.mode: "none"` على ingress الخاص مصادقة الاتصال ذات السر المشترك + بالكامل؛ لا تعرض هذا الوضع على ingress عام/غير موثوق. +- بعد الاقتران، يصدر Gateway **رمز جهاز** مقيّدًا بدور الاتصال + + النطاقات. ويُعاد في `hello-ok.auth.deviceToken` ويجب على العميل + الاحتفاظ به للاتصالات المستقبلية. +- يجب على العملاء الاحتفاظ بالرمز الأساسي `hello-ok.auth.deviceToken` بعد أي اتصال ناجح. -- يجب أن تؤدي إعادة الاتصال باستخدام رمز الجهاز المميز **المحفوظ** هذا أيضًا إلى إعادة استخدام - مجموعة النطاقات الموافق عليها والمحفوظة لهذا الرمز. يحافظ ذلك على صلاحيات - الوصول للقراءة/الفحص/الحالة التي مُنحت سابقًا ويتجنب تقليص عمليات - إعادة الاتصال بصمت إلى نطاق إدارة ضمني أضيق فقط. -- تجميع مصادقة الاتصال على جانب العميل (`selectConnectAuth` في +- يجب أن تؤدي إعادة الاتصال باستخدام رمز الجهاز **المحفوظ** هذا أيضًا إلى إعادة استخدام + مجموعة النطاقات الموافق عليها والمحفوظة لذلك الرمز. وهذا يحافظ على وصول + القراءة/الفحص/الحالة الذي مُنح مسبقًا ويتجنب تقليص عمليات إعادة الاتصال بصمت إلى + نطاق إداري ضمني أضيق فقط. +- تجميع مصادقة الاتصال من جهة العميل (`selectConnectAuth` في `src/gateway/client.ts`): - `auth.password` مستقل ويُمرَّر دائمًا عند ضبطه. - - يُملأ `auth.token` وفق ترتيب أولوية: الرمز المشترك الصريح أولًا، - ثم `deviceToken` صريح، ثم رمز محفوظ لكل جهاز (مفهرس حسب + - يُملأ `auth.token` بحسب أولوية الترتيب التالية: الرمز المشترك الصريح أولًا، + ثم `deviceToken` صريح، ثم رمز محفوظ لكل جهاز (مفهرس بواسطة `deviceId` + `role`). - - لا يُرسل `auth.bootstrapToken` إلا عندما لا يحل أي مما سبق قيمة - `auth.token`. ويؤدي الرمز المشترك أو أي رمز جهاز مميز محلول إلى منعه. - - الترقية التلقائية لرمز جهاز محفوظ في إعادة المحاولة الوحيدة - `AUTH_TOKEN_MISMATCH` مقيّدة **بنقاط النهاية الموثوقة فقط** — - loopback، أو `wss://` مع `tlsFingerprint` مثبت. ولا يُعد `wss://` العام - من دون تثبيت مؤهلًا. -- تُعد إدخالات `hello-ok.auth.deviceTokens` الإضافية رموز تسليم bootstrap. - احتفظ بها فقط عندما يكون الاتصال قد استخدم مصادقة bootstrap على نقل موثوق - مثل `wss://` أو loopback/local pairing. -- إذا قدّم عميل `deviceToken` **صريحًا** أو `scopes` صريحة، فإن - مجموعة النطاقات المطلوبة من المستدعي تبقى هي المرجع؛ ولا يُعاد استخدام + - لا يُرسل `auth.bootstrapToken` إلا عندما لا يحل أي مما سبق + قيمة `auth.token`. ويؤدي الرمز المشترك أو أي رمز جهاز محلول إلى منعه. + - يخضع الترفيع التلقائي لرمز جهاز محفوظ في إعادة المحاولة الوحيدة + `AUTH_TOKEN_MISMATCH` إلى **نقاط نهاية موثوقة فقط** — + loopback، أو `wss://` مع `tlsFingerprint` مثبّت. ولا يُعد `wss://` العام + دون تثبيت مؤهلًا. +- تُعد الإدخالات الإضافية `hello-ok.auth.deviceTokens` رموز تسليم تمهيد. + احتفظ بها فقط عندما يكون الاتصال قد استخدم مصادقة التمهيد على نقل موثوق + مثل `wss://` أو الاقتران المحلي/loopback. +- إذا زوّد العميل `deviceToken` **صريحًا** أو `scopes` صريحة، فإن + مجموعة النطاقات التي طلبها المستدعي تبقى هي المعتمدة؛ ولا يُعاد استخدام النطاقات المخبأة إلا عندما يعيد العميل استخدام الرمز المحفوظ لكل جهاز. -- يمكن تدوير/إبطال رموز الأجهزة عبر `device.token.rotate` و - `device.token.revoke` (ويتطلب ذلك النطاق `operator.pairing`). -- يظل إصدار/تدوير الرموز محصورًا ضمن مجموعة الأدوار الموافق عليها والمسجلة - في إدخال إقران ذلك الجهاز؛ ولا يمكن لتدوير رمز أن يوسّع الجهاز إلى - دور لم تمنحه موافقة الإقران أصلًا. -- بالنسبة إلى جلسات رموز الأجهزة المقترنة، تكون إدارة الأجهزة محصورة ذاتيًا ما لم يكن - لدى المستدعي أيضًا `operator.admin`: لا يمكن للمستدعين غير الإداريين - إزالة/إبطال/تدوير إلا إدخال أجهزتهم **هم فقط**. -- يتحقق `device.token.rotate` أيضًا من مجموعة نطاقات المشغّل المطلوبة مقارنةً بـ +- يمكن تدوير/إلغاء رموز الأجهزة عبر `device.token.rotate` و + `device.token.revoke` (يتطلب ذلك النطاق `operator.pairing`). +- يبقى إصدار/تدوير الرموز مقيّدًا بمجموعة الأدوار الموافق عليها والمُسجّلة في + إدخال اقتران ذلك الجهاز؛ ولا يمكن أن يؤدي تدوير رمز إلى توسيع الجهاز إلى + دور لم تمنحه موافقة الاقتران أصلًا. +- بالنسبة إلى جلسات رموز الأجهزة المقترنة، تكون إدارة الجهاز مقيّدة بالذات ما لم يكن لدى + المستدعي أيضًا `operator.admin`: إذ لا يمكن للمستدعين غير الإداريين إزالة/إلغاء/تدوير + إلا إدخال جهازهم **الخاص**. +- يتحقق `device.token.rotate` أيضًا من مجموعة نطاقات المشغّل المطلوبة مقارنةً مع نطاقات جلسة المستدعي الحالية. ولا يمكن للمستدعين غير الإداريين تدوير رمز إلى مجموعة نطاقات مشغّل أوسع مما يملكونه بالفعل. -- تتضمن حالات فشل المصادقة `error.details.code` إضافةً إلى تلميحات الاسترداد: - - `error.details.canRetryWithDeviceToken` (قيمة منطقية) - - `error.details.recommendedNextStep` (`retry_with_device_token`، `update_auth_configuration`، `update_auth_credentials`، `wait_then_retry`، `review_auth_configuration`) +- تتضمن حالات فشل المصادقة `error.details.code` بالإضافة إلى تلميحات للاسترداد: + - `error.details.canRetryWithDeviceToken` (منطقي) + - `error.details.recommendedNextStep` (`retry_with_device_token`, `update_auth_configuration`, `update_auth_credentials`, `wait_then_retry`, `review_auth_configuration`) - سلوك العميل عند `AUTH_TOKEN_MISMATCH`: - - يمكن للعملاء الموثوقين محاولة إعادة واحدة محدودة باستخدام رمز محفوظ لكل جهاز. - - إذا فشلت إعادة المحاولة هذه، يجب على العملاء إيقاف حلقات إعادة الاتصال التلقائية - وإظهار إرشادات للإجراء المطلوب من المشغّل. + - يمكن للعملاء الموثوقين محاولة إعادة محاولة واحدة مقيّدة باستخدام رمز محفوظ لكل جهاز. + - إذا فشلت إعادة المحاولة هذه، يجب على العملاء إيقاف حلقات إعادة الاتصال التلقائي وعرض إرشادات لاتخاذ إجراء من المشغّل. -## هوية الجهاز + الإقران +## هوية الجهاز + الاقتران -- يجب أن تتضمن العقد هوية جهاز ثابتة (`device.id`) مشتقة من +- يجب أن تتضمن العقد هوية جهاز مستقرة (`device.id`) مشتقة من بصمة زوج مفاتيح. -- تُصدر Gateways رموزًا مميزة لكل جهاز + دور. -- تتطلب معرّفات الأجهزة الجديدة موافقات إقران ما لم يكن التفعيل المحلي التلقائي - للموافقة ممكّنًا. -- تتمحور الموافقة التلقائية على الإقران حول اتصالات loopback المحلية المباشرة. -- يوفّر OpenClaw أيضًا مسار self-connect ضيقًا محليًا للخلفية/الحاوية - لتدفقات المساعد الموثوق ذات السر المشترك. -- لا تزال اتصالات tailnet أو LAN على نفس المضيف تُعامل على أنها بعيدة للإقران +- تصدر الـ gateways رموزًا لكل جهاز + دور. +- تتطلب معرفات الأجهزة الجديدة موافقات اقتران ما لم يكن + القبول التلقائي المحلي مفعّلًا. +- يتمحور القبول التلقائي للاقتران حول اتصالات loopback المحلية المباشرة. +- يمتلك OpenClaw أيضًا مسار اتصال ذاتي ضيقًا محليًا على الخلفية/الحاوية + لتدفقات المساعدات الموثوقة ذات السر المشترك. +- تظل اتصالات tailnet أو LAN على نفس المضيف تُعامل على أنها بعيدة بالنسبة إلى الاقتران وتتطلب موافقة. -- يجب أن تتضمن جميع عملاء WS هوية `device` أثناء `connect` (operator + node). +- يجب على جميع عملاء WS تضمين هوية `device` أثناء `connect` (operator + node). يمكن لـ Control UI حذفها فقط في هذه الأوضاع: - - `gateway.controlUi.allowInsecureAuth=true` للتوافق مع HTTP غير الآمن على localhost فقط. - - نجاح مصادقة operator في `gateway.auth.mode: "trusted-proxy"` لـ Control UI. - - `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (وضع طوارئ، خفض أمني شديد). -- يجب أن توقّع جميع الاتصالات قيمة nonce الخاصة بـ `connect.challenge` التي يوفرها الخادم. + - `gateway.controlUi.allowInsecureAuth=true` من أجل توافق HTTP غير الآمن الخاص بـ localhost فقط. + - نجاح مصادقة مشغّل Control UI في `gateway.auth.mode: "trusted-proxy"`. + - `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (خيار طوارئ، تخفيض أمني شديد). +- يجب على جميع الاتصالات توقيع nonce الخاص بـ `connect.challenge` الذي يوفّره الخادم. ### تشخيصات ترحيل مصادقة الجهاز -بالنسبة إلى العملاء القدامى الذين لا يزالون يستخدمون سلوك التوقيع السابق للتحدي، يعيد `connect` الآن -رموز التفاصيل `DEVICE_AUTH_*` ضمن `error.details.code` مع `error.details.reason` ثابتة. +بالنسبة إلى العملاء القدامى الذين ما زالوا يستخدمون سلوك التوقيع السابق للتحدي، يعيد `connect` الآن +رموز تفاصيل `DEVICE_AUTH_*` تحت `error.details.code` مع قيمة `error.details.reason` مستقرة. أعطال الترحيل الشائعة: | الرسالة | details.code | details.reason | المعنى | | --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- | -| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | لم يرسل العميل `device.nonce` (أو أرسله فارغًا). | +| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | أغفل العميل `device.nonce` (أو أرسله فارغًا). | | `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | وقّع العميل باستخدام nonce قديم/خاطئ. | -| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | لا تطابق حمولة التوقيع حمولة v2. | -| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | الطابع الزمني الموقّع خارج مقدار الانحراف المسموح. | +| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | حمولة التوقيع لا تطابق حمولة v2. | +| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | الطابع الزمني الموقّع خارج نطاق الانحراف المسموح. | | `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | لا يطابق `device.id` بصمة المفتاح العام. | -| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | فشل تنسيق/تطبيع المفتاح العام. | +| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | فشل تنسيق/توحيد المفتاح العام. | هدف الترحيل: @@ -642,17 +653,17 @@ Plugin/channel. تعامل معها على أنها لاكتشاف الميزا - أرسل nonce نفسه في `connect.params.device.nonce`. - حمولة التوقيع المفضلة هي `v3`، التي تربط `platform` و`deviceFamily` بالإضافة إلى حقول device/client/role/scopes/token/nonce. -- لا تزال توقيعات `v2` القديمة مقبولة للتوافق، لكن تثبيت بيانات - الأجهزة المقترنة الوصفية ما يزال يتحكم في سياسة الأوامر عند إعادة الاتصال. +- تظل تواقيع `v2` القديمة مقبولة للتوافق، لكن تثبيت البيانات الوصفية للأجهزة + المقترنة ما زال يتحكم في سياسة الأوامر عند إعادة الاتصال. ## TLS + التثبيت -- يدعم TLS اتصالات WS. -- يمكن للعملاء اختياريًا تثبيت بصمة شهادة gateway (راجع تهيئة `gateway.tls` - إضافةً إلى `gateway.remote.tlsFingerprint` أو خيار CLI ‏`--tls-fingerprint`). +- يدعم البروتوكول TLS لاتصالات WS. +- يمكن للعملاء اختياريًا تثبيت بصمة شهادة الـ gateway (راجع إعدادات `gateway.tls` + بالإضافة إلى `gateway.remote.tlsFingerprint` أو خيار CLI `--tls-fingerprint`). ## النطاق -يعرض هذا البروتوكول **واجهة API الكاملة لـ gateway** (الحالة، والقنوات، والنماذج، والدردشة، -والوكيل، والجلسات، والعقد، والموافقات، وغير ذلك). ويُعرَّف السطح الدقيق بواسطة +يكشف هذا البروتوكول **واجهة API الكاملة للـ gateway** (الحالة، والقنوات، والنماذج، والدردشة، +والوكيل، والجلسات، والعقد، والموافقات، وما إلى ذلك). ويُعرَّف السطح الدقيق بواسطة مخططات TypeBox في `src/gateway/protocol/schema.ts`. diff --git a/docs/ar/help/testing.md b/docs/ar/help/testing.md index e6a34d7a9..3195be4ef 100644 --- a/docs/ar/help/testing.md +++ b/docs/ar/help/testing.md @@ -1,110 +1,109 @@ --- read_when: - تشغيل الاختبارات محليًا أو في CI - - إضافة اختبارات تراجعية لأخطاء النموذج/موفّر الخدمة - - تصحيح سلوك Gateway والوكيل -summary: 'مجموعة الاختبارات: أجنحة unit/e2e/live، ومشغّلات Docker، وما الذي يغطيه كل اختبار' + - إضافة اختبارات انحدار لأخطاء النموذج/المزوّد + - تصحيح سلوك Gateway + الوكيل +summary: 'مجموعة الاختبار: أجنحة unit/e2e/live، ومشغّلات Docker، وما الذي يغطيه كل اختبار' title: الاختبار x-i18n: - generated_at: "2026-04-17T07:17:54Z" + generated_at: "2026-04-18T07:14:52Z" model: gpt-5.4 provider: openai - source_hash: 55483bc68d3b24daca3189fba3af1e896f39b8e83068d102fed06eac05b36102 + source_hash: 7cdd2048ba58e606fd68703977c2b33000abdb1826b6589ce25a35c53468726a source_path: help/testing.md workflow: 15 --- # الاختبار -يحتوي OpenClaw على ثلاث أجنحة Vitest (unit/integration وe2e وlive) ومجموعة صغيرة من مشغّلات Docker. +يحتوي OpenClaw على ثلاثة أجنحة Vitest (unit/integration وe2e وlive) ومجموعة صغيرة من مشغّلات Docker. -هذا المستند هو دليل "كيف نختبر": +هذا المستند هو دليل «كيف نختبر»: - ما الذي يغطيه كل جناح (وما الذي لا يغطيه عمدًا) -- ما الأوامر التي يجب تشغيلها لسيناريوهات العمل الشائعة (محليًا، قبل الدفع، تصحيح الأخطاء) -- كيف تكتشف الاختبارات الحية بيانات الاعتماد وتختار النماذج/موفّري الخدمة -- كيفية إضافة اختبارات تراجعية لمشكلات النماذج/موفّري الخدمة في العالم الحقيقي +- ما الأوامر التي يجب تشغيلها لسير العمل الشائع (محليًا، قبل الدفع، تصحيح الأخطاء) +- كيف تكتشف الاختبارات الحية بيانات الاعتماد وتحدد النماذج/المزوّدين +- كيفية إضافة اختبارات انحدار لمشكلات النموذج/المزوّد في العالم الحقيقي ## البدء السريع في معظم الأيام: - البوابة الكاملة (متوقعة قبل الدفع): `pnpm build && pnpm check && pnpm test` -- تشغيل أسرع محليًا للجناح الكامل على جهاز بموارد جيدة: `pnpm test:max` +- تشغيل أسرع كامل الأجنحة محليًا على جهاز ذي موارد جيدة: `pnpm test:max` - حلقة مراقبة Vitest مباشرة: `pnpm test:watch` -- استهداف الملفات مباشرة يوجّه الآن أيضًا مسارات extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- فضّل التشغيلات المستهدفة أولًا عندما تكون تعمل على تكرار إصلاح فشل واحد. +- استهداف الملفات مباشرة يوجّه الآن أيضًا مسارات الإضافات/القنوات: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- فضّل التشغيلات المستهدفة أولًا عندما تكون تعمل على فشل واحد. - موقع QA مدعوم بـ Docker: `pnpm qa:lab:up` -- مسار QA مدعوم بآلة Linux افتراضية: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- مسار QA مدعوم بـ Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` عندما تلمس الاختبارات أو تريد ثقة إضافية: - بوابة التغطية: `pnpm test:coverage` - جناح E2E: `pnpm test:e2e` -عند تصحيح موفّري الخدمة/النماذج الحقيقية (يتطلب بيانات اعتماد حقيقية): +عند تصحيح مزوّدين/نماذج حقيقية (يتطلب بيانات اعتماد حقيقية): -- الجناح الحي (النماذج + مجسات الأدوات/الصور في Gateway): `pnpm test:live` -- استهداف ملف حي واحد بهدوء: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- الجناح الحي (فحوصات النماذج + Gateway للأدوات/الصور): `pnpm test:live` +- استهدف ملفًا حيًا واحدًا بهدوء: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -نصيحة: عندما تحتاج فقط إلى حالة فاشلة واحدة، فالأفضل تضييق الاختبارات الحية عبر متغيرات البيئة الخاصة بقائمة السماح الموضحة أدناه. +نصيحة: عندما تحتاج فقط إلى حالة فاشلة واحدة، ففضّل تضييق الاختبارات الحية عبر متغيرات البيئة allowlist الموصوفة أدناه. ## المشغّلات الخاصة بـ QA -تأتي هذه الأوامر إلى جانب أجنحة الاختبار الرئيسية عندما تحتاج إلى واقعية QA-lab: +توجد هذه الأوامر بجانب أجنحة الاختبار الرئيسية عندما تحتاج إلى واقعية qa-lab: - `pnpm openclaw qa suite` - يشغّل سيناريوهات QA المعتمدة على المستودع مباشرة على المضيف. - يشغّل عدة سيناريوهات محددة بالتوازي افتراضيًا مع عمّال Gateway معزولين، حتى 64 عاملًا أو عدد السيناريوهات المحدد. استخدم `--concurrency ` لضبط عدد العمّال، أو `--concurrency 1` للمسار التسلسلي الأقدم. - - يدعم أوضاع موفّري الخدمة `live-frontier` و`mock-openai` و`aimock`. - يبدأ `aimock` خادم موفّر خدمة محليًا مدعومًا بـ AIMock لتغطية تجريبية للتهيئات والبروتوكول الوهمي دون استبدال مسار `mock-openai` الواعي بالسيناريوهات. + - يدعم أوضاع المزوّد `live-frontier` و`mock-openai` و`aimock`. + يبدأ `aimock` خادم مزوّد محليًا مدعومًا بـ AIMock لتغطية تجريبية للتركيبات الثابتة ومحاكاة البروتوكول دون استبدال مسار `mock-openai` الواعي بالسيناريوهات. - `pnpm openclaw qa suite --runner multipass` - - يشغّل جناح QA نفسه داخل آلة Linux افتراضية مؤقتة من Multipass. - - يحتفظ بسلوك اختيار السيناريو نفسه الموجود في `qa suite` على المضيف. - - يعيد استخدام علامات اختيار الموفّر/النموذج نفسها الخاصة بـ `qa suite`. + - يشغّل جناح QA نفسه داخل Linux VM مؤقتة عبر Multipass. + - يحافظ على سلوك اختيار السيناريو نفسه الذي يقدمه `qa suite` على المضيف. + - يعيد استخدام علامات اختيار المزوّد/النموذج نفسها التي يستخدمها `qa suite`. - التشغيلات الحية تمرّر مدخلات مصادقة QA المدعومة والعملية للضيف: - مفاتيح الموفّرين المعتمدة على البيئة، ومسار إعداد موفّر QA الحي، و`CODEX_HOME` عند وجوده. - - يجب أن تبقى مجلدات الإخراج تحت جذر المستودع حتى يتمكن الضيف من الكتابة مجددًا عبر مساحة العمل المركّبة. + مفاتيح المزوّد المعتمدة على env، ومسار إعداد مزوّد QA الحي، و`CODEX_HOME` عند وجوده. + - يجب أن تبقى أدلة المخرجات ضمن جذر المستودع حتى يتمكن الضيف من الكتابة مرة أخرى عبر مساحة العمل الموصولة. - يكتب تقرير QA والملخص المعتادين بالإضافة إلى سجلات Multipass تحت `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - يبدأ موقع QA المدعوم بـ Docker لأعمال QA بأسلوب المشغّل. + - يبدأ موقع QA المدعوم بـ Docker لعمل QA بأسلوب المشغّل. - `pnpm openclaw qa aimock` - - يبدأ فقط خادم موفّر AIMock المحلي لاختبار البروتوكول الدخاني مباشرة. + - يبدأ فقط خادم مزوّد AIMock المحلي لاختبار Smoke مباشر للبروتوكول. - `pnpm openclaw qa matrix` - - يشغّل مسار Matrix QA الحي مقابل خادم Tuwunel homeserver مؤقت ومدعوم بـ Docker. - - هذا مضيف QA مخصص للمستودع/التطوير فقط حاليًا. تثبيتات OpenClaw المعبأة لا تتضمن - `qa-lab`، لذلك لا تعرض `openclaw qa`. - - نسخ المستودع تحمّل المشغّل المضمّن مباشرة؛ لا حاجة إلى خطوة تثبيت Plugin منفصلة. - - يجهّز ثلاثة مستخدمي Matrix مؤقتين (`driver` و`sut` و`observer`) بالإضافة إلى غرفة خاصة واحدة، ثم يبدأ عملية فرعية لـ QA gateway مع Matrix plugin الحقيقي كوسيلة نقل SUT. - - يستخدم صورة Tuwunel المستقرة المثبتة `ghcr.io/matrix-construct/tuwunel:v1.5.1` افتراضيًا. تجاوز ذلك باستخدام `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` عندما تحتاج إلى اختبار صورة مختلفة. - - لا يعرّض Matrix علامات مصادر بيانات اعتماد مشتركة لأن المسار يجهّز مستخدمين مؤقتين محليًا. - - يكتب تقرير Matrix QA وملخصًا وقطعة أثر observed-events وسجل إخراج stdout/stderr المجمّع تحت `.artifacts/qa-e2e/...`. + - يشغّل مسار QA الحي لـ Matrix مقابل خادم Tuwunel منزلي مؤقت ومدعوم بـ Docker. + - هذا المضيف QA مخصص حاليًا للمستودع/التطوير فقط. تثبيتات OpenClaw المعبأة لا تشحن `qa-lab`، لذلك لا تعرض `openclaw qa`. + - نسخ المستودع تستخدم المشغّل المضمّن مباشرة؛ لا حاجة إلى خطوة تثبيت Plugin منفصلة. + - يوفّر ثلاثة مستخدمين مؤقتين لـ Matrix (`driver` و`sut` و`observer`) بالإضافة إلى غرفة خاصة واحدة، ثم يبدأ عملية فرعية لـ QA gateway مع Plugin Matrix الحقيقي باعتباره نقل SUT. + - يستخدم صورة Tuwunel المستقرة المثبتة `ghcr.io/matrix-construct/tuwunel:v1.5.1` افتراضيًا. استبدلها باستخدام `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` عندما تحتاج إلى اختبار صورة مختلفة. + - لا يوفّر Matrix علامات مشتركة لمصادر بيانات الاعتماد لأن المسار يوفّر مستخدمين مؤقتين محليًا. + - يكتب تقرير QA لـ Matrix، والملخص، وartifact للأحداث المرصودة، وسجل مخرجات stdout/stderr المدمج تحت `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - - يشغّل مسار Telegram QA الحي مقابل مجموعة خاصة حقيقية باستخدام رموز driver وSUT bot المأخوذة من البيئة. + - يشغّل مسار QA الحي لـ Telegram مقابل مجموعة خاصة حقيقية باستخدام رمزي bot الخاصين بـ driver وSUT من env. - يتطلب `OPENCLAW_QA_TELEGRAM_GROUP_ID` و`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` و`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. يجب أن يكون معرّف المجموعة هو معرّف دردشة Telegram الرقمي. - - يدعم `--credential-source convex` لبيانات الاعتماد المشتركة المجمّعة. استخدم وضع البيئة افتراضيًا، أو عيّن `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` لاختيار عقود الإيجار المجمّعة. - - يتطلب روبوتين مختلفين في المجموعة الخاصة نفسها، مع كشف SUT bot عن اسم مستخدم Telegram. - - لضمان ملاحظة مستقرة بين الروبوتات، فعّل وضع Bot-to-Bot Communication Mode في `@BotFather` لكلا الروبوتين وتأكد من أن driver bot يستطيع ملاحظة حركة مرور الروبوتات في المجموعة. - - يكتب تقرير Telegram QA وملخصًا وقطعة أثر observed-messages تحت `.artifacts/qa-e2e/...`. + - يدعم `--credential-source convex` لبيانات الاعتماد المشتركة المجمّعة. استخدم وضع env افتراضيًا، أو اضبط `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` للاشتراك في التأجير المجمّع. + - يتطلب botين مختلفين في المجموعة الخاصة نفسها، مع قيام bot الخاص بـ SUT بعرض اسم مستخدم Telegram. + - للحصول على مراقبة مستقرة بين bot وآخر، فعّل وضع Bot-to-Bot Communication Mode في `@BotFather` لكلا botين وتأكد من أن bot الخاص بـ driver يستطيع مراقبة حركة bot في المجموعة. + - يكتب تقرير QA لـ Telegram، والملخص، وartifact للرسائل المرصودة تحت `.artifacts/qa-e2e/...`. -تشترك مسارات النقل الحية في عقد قياسي واحد حتى لا تنحرف وسائل النقل الجديدة: +تتشارك مسارات النقل الحية عقدًا قياسيًا واحدًا حتى لا تنحرف وسائل النقل الجديدة: -يبقى `qa-channel` جناح QA الاصطناعي الواسع وليس جزءًا من مصفوفة تغطية -النقل الحية. +يبقى `qa-channel` جناح QA التركيبي الواسع وليس جزءًا من مصفوفة تغطية +النقل الحي. -| المسار | Canary | بوابة الإشارة | حظر قائمة السماح | رد على المستوى الأعلى | استئناف بعد إعادة التشغيل | متابعة السلسلة | عزل السلسلة | ملاحظة التفاعلات | أمر المساعدة | -| ------ | ------ | -------------- | ----------------- | ---------------------- | -------------------------- | -------------- | ------------ | ----------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| المسار | Canary | تقييد الإشارة | حظر allowlist | الرد الأعلى مستوى | الاستئناف بعد إعادة التشغيل | متابعة الخيط | عزل الخيط | مراقبة التفاعل | أمر المساعدة | +| -------- | ------ | -------------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | ### بيانات اعتماد Telegram المشتركة عبر Convex (v1) -عند تفعيل `--credential-source convex` (أو `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) لـ -`openclaw qa telegram`، يحصل QA lab على عقد إيجار حصري من مجموعة مدعومة بـ Convex، ويرسل -Heartbeat لهذا العقد أثناء تشغيل المسار، ويحرّر العقد عند الإيقاف. +عند تفعيل `--credential-source convex` (أو `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) لأمر +`openclaw qa telegram`، يحصل QA lab على تأجير حصري من تجمّع مدعوم بـ Convex، ويرسل Heartbeat +لهذا التأجير أثناء تشغيل المسار، ويطلق التأجير عند الإيقاف. -مرجع هيكل مشروع Convex: +هيكل مشروع Convex المرجعي: - `qa/convex-credential-broker/` @@ -112,25 +111,25 @@ Heartbeat لهذا العقد أثناء تشغيل المسار، ويحرّر - `OPENCLAW_QA_CONVEX_SITE_URL` (على سبيل المثال `https://your-deployment.convex.site`) - سر واحد للدور المحدد: - - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` للدور `maintainer` - - `OPENCLAW_QA_CONVEX_SECRET_CI` للدور `ci` + - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` من أجل `maintainer` + - `OPENCLAW_QA_CONVEX_SECRET_CI` من أجل `ci` - اختيار دور بيانات الاعتماد: - CLI: `--credential-role maintainer|ci` - - القيمة الافتراضية من البيئة: `OPENCLAW_QA_CREDENTIAL_ROLE` (القيمة الافتراضية هي `maintainer`) + - env الافتراضي: `OPENCLAW_QA_CREDENTIAL_ROLE` (الافتراضي هو `maintainer`) متغيرات البيئة الاختيارية: -- `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (القيمة الافتراضية `1200000`) -- `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (القيمة الافتراضية `30000`) -- `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (القيمة الافتراضية `90000`) -- `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (القيمة الافتراضية `15000`) -- `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (القيمة الافتراضية `/qa-credentials/v1`) +- `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (الافتراضي `1200000`) +- `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (الافتراضي `30000`) +- `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (الافتراضي `90000`) +- `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (الافتراضي `15000`) +- `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (الافتراضي `/qa-credentials/v1`) - `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (معرّف تتبع اختياري) - `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` يسمح بعناوين Convex من نوع `http://` على loopback للتطوير المحلي فقط. -يجب أن يستخدم `OPENCLAW_QA_CONVEX_SITE_URL` البروتوكول `https://` في التشغيل العادي. +يجب أن يستخدم `OPENCLAW_QA_CONVEX_SITE_URL` الصيغة `https://` في التشغيل العادي. -تتطلب أوامر الإدارة الخاصة بالمشرفين (إضافة/إزالة/عرض المجموعة) المتغير +أوامر الإدارة الخاصة بالمشرفين (إضافة/إزالة/عرض التجمّع) تتطلب `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` تحديدًا. مساعدات CLI للمشرفين: @@ -141,86 +140,86 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -استخدم `--json` للحصول على مخرجات قابلة للقراءة الآلية في السكربتات وأدوات CI. +استخدم `--json` للحصول على مخرجات قابلة للقراءة آليًا في السكربتات وأدوات CI. عقد نقاط النهاية الافتراضي (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - `POST /acquire` - الطلب: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` - النجاح: `{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }` - - نفاد/قابل لإعادة المحاولة: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` + - الاستنفاد/القابل لإعادة المحاولة: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` - `POST /heartbeat` - الطلب: `{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` - - النجاح: `{ status: "ok" }` (أو `2xx` فارغ) + - النجاح: `{ status: "ok" }` (أو `2xx` فارغة) - `POST /release` - الطلب: `{ kind, ownerId, actorRole, credentialId, leaseToken }` - - النجاح: `{ status: "ok" }` (أو `2xx` فارغ) -- `POST /admin/add` (سر المشرف فقط) + - النجاح: `{ status: "ok" }` (أو `2xx` فارغة) +- `POST /admin/add` (سر maintainer فقط) - الطلب: `{ kind, actorId, payload, note?, status? }` - النجاح: `{ status: "ok", credential }` -- `POST /admin/remove` (سر المشرف فقط) +- `POST /admin/remove` (سر maintainer فقط) - الطلب: `{ credentialId, actorId }` - النجاح: `{ status: "ok", changed, credential }` - - حماية عقد إيجار نشط: `{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list` (سر المشرف فقط) + - حماية التأجير النشط: `{ status: "error", code: "LEASE_ACTIVE", ... }` +- `POST /admin/list` (سر maintainer فقط) - الطلب: `{ kind?, status?, includePayload?, limit? }` - النجاح: `{ status: "ok", credentials, count }` شكل الحمولة لنوع Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` -- يجب أن يكون `groupId` سلسلة تمثل معرّف دردشة Telegram رقمي. -- يتحقق `admin/add` من هذا الشكل عند `kind: "telegram"` ويرفض الحمولة غير الصحيحة. +- يجب أن يكون `groupId` سلسلة معرّف دردشة Telegram رقمي. +- يتحقق `admin/add` من هذا الشكل عند `kind: "telegram"` ويرفض الحمولات غير الصحيحة. ### إضافة قناة إلى QA -تتطلب إضافة قناة إلى نظام QA المعتمد على Markdown أمرين بالضبط: +إضافة قناة إلى نظام QA المعتمد على Markdown تتطلب أمرين فقط بالضبط: -1. محوّل نقل للقناة. +1. مكيّف نقل للقناة. 2. حزمة سيناريوهات تمارس عقد القناة. -لا تضف جذر أوامر QA جديدًا على المستوى الأعلى عندما يمكن للمضيف المشترك `qa-lab` -أن يمتلك هذا التدفق. +لا تضف جذر أوامر QA جديدًا على المستوى الأعلى عندما يكون بإمكان المضيف المشترك `qa-lab` +امتلاك هذا التدفق. يمتلك `qa-lab` آليات المضيف المشتركة: - جذر الأمر `openclaw qa` - بدء الجناح وإنهاؤه - توازي العمّال -- كتابة القطع الأثرية -- توليد التقارير +- كتابة الـ artifacts +- إنشاء التقارير - تنفيذ السيناريوهات - أسماء التوافق البديلة لسيناريوهات `qa-channel` الأقدم -تمتلك Runner plugins عقد النقل: +تمتلك إضافات المشغّل عقد النقل: - كيف يتم تركيب `openclaw qa ` تحت الجذر المشترك `qa` -- كيف يُضبط Gateway لهذا النقل +- كيف تتم تهيئة Gateway من أجل هذا النقل - كيف يتم التحقق من الجاهزية -- كيف تُحقن الأحداث الواردة -- كيف تتم ملاحظة الرسائل الصادرة -- كيف تُعرَض النصوص وسجل حالة النقل الموحّد -- كيف تُنفذ الإجراءات المدعومة بالنقل +- كيف يتم حقن الأحداث الواردة +- كيف تتم مراقبة الرسائل الصادرة +- كيف يتم عرض النصوص المنسوخة transcript وحالة النقل المطبّعة +- كيف يتم تنفيذ الإجراءات المدعومة بالنقل - كيف تتم معالجة إعادة الضبط أو التنظيف الخاصة بالنقل -الحد الأدنى لاعتماد قناة جديدة هو: +الحد الأدنى المطلوب لاعتماد قناة جديدة هو: -1. إبقاء `qa-lab` مالكًا لجذر `qa` المشترك. -2. تنفيذ مشغّل النقل على وصلة المضيف المشتركة `qa-lab`. -3. إبقاء الآليات الخاصة بالنقل داخل runner plugin أو حزام القناة. -4. تركيب المشغّل كـ `openclaw qa ` بدلًا من تسجيل أمر جذري منافس. - يجب أن تعلن Runner plugins عن `qaRunners` في `openclaw.plugin.json` وتصدّر مصفوفة `qaRunnerCliRegistrations` مطابقة من `runtime-api.ts`. - أبقِ `runtime-api.ts` خفيفًا؛ يجب أن يبقى تنفيذ CLI والمشغّل الكسول خلف نقاط دخول منفصلة. -5. كتابة أو تكييف سيناريوهات Markdown تحت `qa/scenarios/`. +1. إبقاء `qa-lab` مالكًا للجذر المشترك `qa`. +2. تنفيذ مشغّل النقل على واجهة المضيف المشتركة `qa-lab`. +3. إبقاء الآليات الخاصة بالنقل داخل Plugin المشغّل أو حزمة القناة. +4. تركيب المشغّل على هيئة `openclaw qa ` بدلًا من تسجيل أمر جذر منافس. + يجب أن تعلن إضافات المشغّل عن `qaRunners` في `openclaw.plugin.json` وأن تصدّر مصفوفة `qaRunnerCliRegistrations` مطابقة من `runtime-api.ts`. + اجعل `runtime-api.ts` خفيفًا؛ يجب أن يبقى تنفيذ CLI والمشغّل الكسول خلف نقاط دخول منفصلة. +5. تأليف أو تكييف سيناريوهات Markdown تحت أدلة `qa/scenarios/` الموضوعية. 6. استخدام مساعدات السيناريو العامة للسيناريوهات الجديدة. -7. إبقاء أسماء التوافق البديلة الحالية تعمل ما لم يكن المستودع يجري ترحيلًا مقصودًا. +7. إبقاء أسماء التوافق البديلة الحالية عاملة ما لم يكن المستودع ينفّذ ترحيلًا مقصودًا. قاعدة القرار صارمة: - إذا كان يمكن التعبير عن السلوك مرة واحدة في `qa-lab`، فضعه في `qa-lab`. -- إذا كان السلوك يعتمد على نقل قناة واحدة، فأبقِه في runner plugin أو حزام الـ plugin الخاص به. -- إذا احتاج سيناريو إلى قدرة جديدة يمكن أن تستخدمها أكثر من قناة واحدة، فأضف مساعدًا عامًا بدل فرع خاص بالقناة في `suite.ts`. -- إذا كان السلوك ذا معنى فقط لنقل واحد، فأبقِ السيناريو خاصًا بهذا النقل وصرّح بذلك بوضوح في عقد السيناريو. +- إذا كان السلوك يعتمد على نقل قناة واحدة، فأبقِه في Plugin المشغّل أو حزمة Plugin تلك. +- إذا كان السيناريو يحتاج إلى قدرة جديدة يمكن أن تستخدمها أكثر من قناة واحدة، فأضف مساعدًا عامًا بدلًا من فرع خاص بقناة داخل `suite.ts`. +- إذا كان السلوك ذا معنى لنقل واحد فقط، فأبقِ السيناريو خاصًا بذلك النقل وصرّح بذلك بوضوح في عقد السيناريو. أسماء المساعدات العامة المفضلة للسيناريوهات الجديدة هي: @@ -245,245 +244,245 @@ pnpm openclaw qa credentials remove --credential-id - `formatConversationTranscript` - `resetBus` -يجب أن تستخدم الأعمال الجديدة على القنوات أسماء المساعدات العامة. -توجد أسماء التوافق البديلة لتجنب ترحيل شامل في يوم واحد، وليس كنموذج +يجب أن تستخدم الأعمال الجديدة الخاصة بالقنوات أسماء المساعدات العامة. +توجد أسماء التوافق البديلة لتجنب ترحيل شامل في يوم واحد، لا لتكون النموذج لتأليف السيناريوهات الجديدة. ## أجنحة الاختبار (ما الذي يعمل وأين) -فكّر في الأجنحة على أنها "تزداد واقعية" (وتزداد معها الهشاشة/الكلفة): +اعتبر الأجنحة على أنها «زيادة في الواقعية» (وزيادة في عدم الاستقرار/التكلفة): ### Unit / integration (الافتراضي) - الأمر: `pnpm test` -- الإعداد: عشر تشغيلات شظايا متسلسلة (`vitest.full-*.config.ts`) عبر مشاريع Vitest المحددة الموجودة -- الملفات: قوائم جرد core/unit تحت `src/**/*.test.ts` و`packages/**/*.test.ts` و`test/**/*.test.ts` واختبارات node المسموح بها في `ui` والمغطاة بواسطة `vitest.unit.config.ts` +- الإعداد: عشر تشغيلات shard متسلسلة (`vitest.full-*.config.ts`) عبر مشاريع Vitest المحددة الحالية +- الملفات: مخزونات core/unit تحت `src/**/*.test.ts` و`packages/**/*.test.ts` و`test/**/*.test.ts` واختبارات node المدرجة ضمن allowlist في `ui` والمغطاة بواسطة `vitest.unit.config.ts` - النطاق: - اختبارات unit خالصة - - اختبارات تكامل داخل العملية (مصادقة Gateway، والتوجيه، والأدوات، والتحليل، والإعداد) - - اختبارات تراجعية حتمية للأخطاء المعروفة + - اختبارات تكامل داخل العملية (مصادقة gateway، التوجيه، الأدوات، التحليل، الإعداد) + - اختبارات انحدار حتمية للأخطاء المعروفة - التوقعات: - - يعمل في CI - - لا يتطلب مفاتيح حقيقية - - يجب أن يكون سريعًا ومستقرًا -- ملاحظة المشاريع: - - أصبح `pnpm test` غير المستهدف يشغّل الآن أحد عشر إعداد شظايا أصغر (`core-unit-src` و`core-unit-security` و`core-unit-ui` و`core-unit-support` و`core-support-boundary` و`core-contracts` و`core-bundled` و`core-runtime` و`agentic` و`auto-reply` و`extensions`) بدلًا من عملية root-project أصلية ضخمة واحدة. هذا يقلل ذروة RSS على الأجهزة المحمّلة ويمنع أعمال auto-reply/extension من تجويع الأجنحة غير المرتبطة. - - ما يزال `pnpm test --watch` يستخدم مخطط المشاريع الأصلي للجذر `vitest.config.ts`، لأن حلقة مراقبة متعددة الشظايا غير عملية. - - تقوم `pnpm test` و`pnpm test:watch` و`pnpm test:perf:imports` بتمرير أهداف الملفات/المجلدات الصريحة عبر مسارات محددة أولًا، لذلك يتجنب `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` تكلفة بدء تشغيل مشروع الجذر الكامل. - - يوسّع `pnpm test:changed` مسارات git المتغيرة إلى هذه المسارات المحددة نفسها عندما يلمس الفرق فقط ملفات source/test القابلة للتوجيه؛ أما تعديلات config/setup فتعيد الرجوع إلى إعادة تشغيل أوسع لمشروع الجذر. - - تُمرَّر اختبارات unit الخفيفة من حيث الاستيراد من agents وcommands وplugins ومساعدات auto-reply و`plugin-sdk` والمناطق النفعية الخالصة المشابهة عبر مسار `unit-fast`، الذي يتخطى `test/setup-openclaw-runtime.ts`؛ بينما تبقى الملفات الثقيلة من حيث الحالة/وقت التشغيل على المسارات الحالية. - - تُطابِق بعض ملفات المصدر المساعدة المحددة في `plugin-sdk` و`commands` أيضًا تشغيلات وضع changed مع اختبارات شقيقة صريحة في تلك المسارات الخفيفة، بحيث تتجنب تعديلات المساعدات إعادة تشغيل الجناح الثقيل الكامل لذلك الدليل. - - أصبح لدى `auto-reply` الآن ثلاثة أقسام مخصصة: مساعدات core ذات المستوى الأعلى، واختبارات التكامل `reply.*` ذات المستوى الأعلى، والشجرة الفرعية `src/auto-reply/reply/**`. هذا يُبقي أعمال حزام reply الأثقل بعيدًا عن اختبارات status/chunk/token الرخيصة. -- ملاحظة المشغّل المضمّن: - - عندما تغيّر مدخلات اكتشاف message-tool أو سياق وقت تشغيل Compaction، + - تعمل في CI + - لا تتطلب مفاتيح حقيقية + - يجب أن تكون سريعة ومستقرة +- ملاحظة حول المشاريع: + - أصبح `pnpm test` غير المستهدف يشغّل الآن أحد عشر إعداد shard أصغر (`core-unit-src` و`core-unit-security` و`core-unit-ui` و`core-unit-support` و`core-support-boundary` و`core-contracts` و`core-bundled` و`core-runtime` و`agentic` و`auto-reply` و`extensions`) بدلًا من عملية root-project أصلية ضخمة واحدة. هذا يقلّل ذروة RSS على الأجهزة المزدحمة ويمنع أعمال auto-reply/extension من تجويع الأجنحة غير ذات الصلة. + - لا يزال `pnpm test --watch` يستخدم مخطط المشاريع الأصلي في الجذر `vitest.config.ts`، لأن حلقة watch متعددة الـ shard ليست عملية. + - يوجّه `pnpm test` و`pnpm test:watch` و`pnpm test:perf:imports` أهداف الملفات/الأدلة الصريحة عبر المسارات المحددة أولًا، لذلك فإن `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` يتجنب تكلفة بدء تشغيل مشروع الجذر الكامل. + - يوسّع `pnpm test:changed` مسارات git المتغيرة إلى المسارات المحددة نفسها عندما يلمس الفرق فقط ملفات المصدر/الاختبار القابلة للتوجيه؛ أما تعديلات config/setup فتعود إلى إعادة التشغيل الواسعة لمشروع الجذر. + - تُوجَّه اختبارات unit الخفيفة من حيث الاستيراد من الوكلاء والأوامر والإضافات ومساعدات auto-reply و`plugin-sdk` ومناطق الأدوات الخالصة المشابهة عبر مسار `unit-fast`، الذي يتخطى `test/setup-openclaw-runtime.ts`؛ وتبقى الملفات ذات الحالة/الثقيلة وقت التشغيل على المسارات الحالية. + - كذلك تربط بعض ملفات المصدر المساعدة المختارة في `plugin-sdk` و`commands` تشغيلات وضع changed باختبارات شقيقة صريحة في تلك المسارات الخفيفة، بحيث تتجنب تعديلات المساعدات إعادة تشغيل الجناح الثقيل الكامل لذلك الدليل. + - أصبح لدى `auto-reply` الآن ثلاث حاويات مخصصة: مساعدات core العليا، واختبارات التكامل العليا `reply.*`، والشجرة الفرعية `src/auto-reply/reply/**`. وهذا يبقي أعمال حزمة reply الأثقل بعيدًا عن اختبارات status/chunk/token الرخيصة. +- ملاحظة حول المشغّل المضمن: + - عندما تغيّر مدخلات اكتشاف message-tool أو سياق تشغيل Compaction، حافظ على مستويي التغطية معًا. - - أضف اختبارات تراجعية مركزة للمساعدات عند حدود التوجيه/التطبيع الخالصة. - - واحرص أيضًا على بقاء أجنحة تكامل المشغّل المضمّن سليمة: + - أضف اختبارات انحدار مركزة للمساعدات لحدود التوجيه/التطبيع الخالصة. + - واحرص أيضًا على بقاء أجنحة تكامل المشغّل المضمن سليمة: `src/agents/pi-embedded-runner/compact.hooks.test.ts`، - و`src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`، و + `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`، و `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - تتحقق هذه الأجنحة من أن المعرفات المحددة وسلوك Compaction ما زالا يتدفقان - عبر المسارات الحقيقية `run.ts` / `compact.ts`؛ واختبارات المساعدات وحدها ليست - بديلًا كافيًا عن مسارات التكامل هذه. -- ملاحظة المجمع: - - أصبح إعداد Vitest الأساسي يستخدم `threads` افتراضيًا. - - يثبّت إعداد Vitest المشترك أيضًا `isolate: false` ويستخدم المشغّل غير المعزول عبر مشاريع الجذر وتهيئات e2e وlive. - - يحتفظ مسار UI الجذري بإعداد `jsdom` والمُحسِّن الخاص به، لكنه يعمل الآن أيضًا على المشغّل المشترك غير المعزول. - - ترث كل شظية من شظايا `pnpm test` القيم الافتراضية نفسها `threads` + `isolate: false` من إعداد Vitest المشترك. - - يضيف المشغّل المشترك `scripts/run-vitest.mjs` الآن أيضًا `--no-maglev` لعمليات Node الفرعية الخاصة بـ Vitest افتراضيًا لتقليل تقلبات ترجمة V8 أثناء التشغيلات المحلية الكبيرة. عيّن `OPENCLAW_VITEST_ENABLE_MAGLEV=1` إذا كنت تحتاج إلى المقارنة مع سلوك V8 القياسي. -- ملاحظة التكرار المحلي السريع: - - يمرر `pnpm test:changed` عبر مسارات محددة عندما تُطابِق المسارات المتغيرة جناحًا أصغر بشكل واضح. - - يحتفظ `pnpm test:max` و`pnpm test:changed:max` بالسلوك التوجيهي نفسه، ولكن مع حد أعلى أكبر للعمّال. - - أصبح التوسع التلقائي المحلي للعمّال متحفظًا عمدًا الآن ويتراجع أيضًا عندما يكون متوسط حمل المضيف مرتفعًا بالفعل، بحيث تُحدث تشغيلات Vitest المتعددة المتزامنة ضررًا أقل افتراضيًا. - - يضع إعداد Vitest الأساسي علامة على المشاريع/ملفات الإعداد باعتبارها `forceRerunTriggers` بحيث تبقى إعادة التشغيل في وضع changed صحيحة عندما تتغير أسلاك الاختبار. - - يُبقي الإعداد `OPENCLAW_VITEST_FS_MODULE_CACHE` مفعّلًا على المضيفين المدعومين؛ عيّن `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` إذا كنت تريد موقع cache صريحًا واحدًا لأغراض التحليل المباشر. -- ملاحظة تصحيح الأداء: - - يفعّل `pnpm test:perf:imports` تقارير مدة الاستيراد في Vitest بالإضافة إلى إخراج تفصيلي للاستيراد. - - يقيّد `pnpm test:perf:imports:changed` عرض التحليل نفسه على الملفات المتغيرة منذ `origin/main`. -- يقارن `pnpm test:perf:changed:bench -- --ref ` بين `test:changed` الموجّه وبين مسار root-project الأصلي لذلك الفرق الملتزم، ويطبع الزمن المنقضي بالإضافة إلى macOS max RSS. -- يقوم `pnpm test:perf:changed:bench -- --worktree` بقياس الشجرة المتسخة الحالية عبر تمرير قائمة الملفات المتغيرة من خلال `scripts/test-projects.mjs` وإعداد Vitest الجذري. - - يكتب `pnpm test:perf:profile:main` ملف تعريف CPU للخيط الرئيسي لوقت بدء تشغيل Vitest/Vite وتحويله. - - يكتب `pnpm test:perf:profile:runner` ملفات تعريف CPU+heap للمشغّل لجناح unit مع تعطيل توازي الملفات. + - تتحقق هذه الأجنحة من أن المعرّفات المحددة وسلوك Compaction لا يزالان يمران + عبر المسارات الحقيقية `run.ts` / `compact.ts`؛ ولا تكفي اختبارات المساعدات + وحدها كبديل لهذه مسارات التكامل. +- ملاحظة حول الـ pool: + - أصبح الإعداد الأساسي لـ Vitest يستخدم `threads` افتراضيًا. + - كما يثبت إعداد Vitest المشترك `isolate: false` ويستخدم المشغّل غير المعزول عبر مشاريع الجذر وتهيئات e2e وlive. + - يحتفظ مسار UI في الجذر بإعداد `jsdom` والمحسّن الخاص به، لكنه يعمل الآن على المشغّل المشترك غير المعزول أيضًا. + - يرث كل shard في `pnpm test` افتراضيات `threads` + `isolate: false` نفسها من إعداد Vitest المشترك. + - يضيف مشغّل `scripts/run-vitest.mjs` المشترك الآن أيضًا `--no-maglev` لعمليات Node الفرعية الخاصة بـ Vitest افتراضيًا لتقليل churn في ترجمة V8 أثناء التشغيلات المحلية الكبيرة. اضبط `OPENCLAW_VITEST_ENABLE_MAGLEV=1` إذا كنت بحاجة إلى المقارنة مع سلوك V8 الافتراضي. +- ملاحظة حول التكرار المحلي السريع: + - يوجّه `pnpm test:changed` عبر المسارات المحددة عندما تطابق المسارات المتغيرة جناحًا أصغر بوضوح. + - يحتفظ `pnpm test:max` و`pnpm test:changed:max` بسلوك التوجيه نفسه، فقط مع حد أعلى أكبر للعمّال. + - أصبح التوسيع التلقائي لعدد العمّال محليًا محافظًا عمدًا الآن ويتراجع أيضًا عندما يكون متوسط حمل المضيف مرتفعًا بالفعل، بحيث تسبب عدة تشغيلات Vitest متزامنة ضررًا أقل افتراضيًا. + - يعلّم إعداد Vitest الأساسي ملفات المشاريع/الإعدادات على أنها `forceRerunTriggers` حتى تظل إعادة التشغيل في وضع changed صحيحة عندما تتغير توصيلات الاختبار. + - يبقي الإعداد `OPENCLAW_VITEST_FS_MODULE_CACHE` مفعّلًا على المضيفات المدعومة؛ اضبط `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` إذا أردت موقع cache صريحًا واحدًا لإجراء profiling مباشر. +- ملاحظة حول تصحيح الأداء: + - يفعّل `pnpm test:perf:imports` تقارير مدة الاستيراد في Vitest بالإضافة إلى مخرجات تفصيل الاستيراد. + - يحدد `pnpm test:perf:imports:changed` عرض profiling نفسه للملفات المتغيرة منذ `origin/main`. +- يقارن `pnpm test:perf:changed:bench -- --ref ` بين `test:changed` الموجّه ومسار root-project الأصلي لذلك الفرق الملتزم ويطبع زمن التنفيذ بالإضافة إلى أقصى RSS على macOS. +- يقيس `pnpm test:perf:changed:bench -- --worktree` الشجرة المتسخة الحالية عبر توجيه قائمة الملفات المتغيرة من خلال `scripts/test-projects.mjs` وإعداد Vitest في الجذر. + - يكتب `pnpm test:perf:profile:main` ملف CPU profile للخيط الرئيسي لكلفة بدء تشغيل Vitest/Vite والتحويل. + - يكتب `pnpm test:perf:profile:runner` ملفات CPU+heap profile للمشغّل لجناح unit مع تعطيل التوازي على مستوى الملفات. -### E2E (اختبار Gateway الدخاني) +### E2E (gateway smoke) - الأمر: `pnpm test:e2e` - الإعداد: `vitest.e2e.config.ts` -- الملفات: `src/**/*.e2e.test.ts` و`test/**/*.e2e.test.ts` -- القيم الافتراضية لوقت التشغيل: - - يستخدم Vitest `threads` مع `isolate: false`، بما يتوافق مع بقية المستودع. +- الملفات: `src/**/*.e2e.test.ts`، `test/**/*.e2e.test.ts` +- افتراضيات وقت التشغيل: + - يستخدم Vitest `threads` مع `isolate: false`، بما يطابق بقية المستودع. - يستخدم عمّالًا تكيفيين (CI: حتى 2، محليًا: 1 افتراضيًا). - - يعمل في الوضع الصامت افتراضيًا لتقليل تكلفة I/O الخاصة بوحدة التحكم. -- تجاوزات مفيدة: + - يعمل في الوضع الصامت افتراضيًا لتقليل حمل إدخال/إخراج الطرفية. +- بدائل مفيدة: - `OPENCLAW_E2E_WORKERS=` لفرض عدد العمّال (بحد أقصى 16). - - `OPENCLAW_E2E_VERBOSE=1` لإعادة تفعيل إخراج وحدة التحكم المفصل. + - `OPENCLAW_E2E_VERBOSE=1` لإعادة تفعيل مخرجات الطرفية التفصيلية. - النطاق: - - سلوك Gateway من طرف إلى طرف عبر عدة مثيلات - - أسطح WebSocket/HTTP، واقتران Node، والشبكات الأثقل + - سلوك Gateway من طرف إلى طرف مع عدة مثيلات + - أسطح WebSocket/HTTP، وإقران Node، والشبكات الأثقل - التوقعات: - - يعمل في CI (عند تفعيله في المسار) + - يعمل في CI (عند تفعيله في خط الأنابيب) - لا يتطلب مفاتيح حقيقية - يحتوي على أجزاء متحركة أكثر من اختبارات unit (وقد يكون أبطأ) -### E2E: اختبار OpenShell الخلفي الدخاني +### E2E: OpenShell backend smoke - الأمر: `pnpm test:e2e:openshell` - الملف: `test/openshell-sandbox.e2e.test.ts` - النطاق: - يبدأ OpenShell gateway معزولًا على المضيف عبر Docker - ينشئ sandbox من Dockerfile محلي مؤقت - - يختبر الواجهة الخلفية OpenShell في OpenClaw عبر `sandbox ssh-config` حقيقي وتنفيذ SSH - - يتحقق من سلوك نظام الملفات القياسي البعيد عبر جسر sandbox fs + - يمارس OpenShell backend في OpenClaw عبر `sandbox ssh-config` حقيقي + تنفيذ SSH + - يتحقق من سلوك نظام الملفات canonical البعيد عبر جسر sandbox fs - التوقعات: - - يعمل عند الاختيار فقط؛ وليس جزءًا من تشغيل `pnpm test:e2e` الافتراضي + - تفعيل اختياري فقط؛ ليس جزءًا من التشغيل الافتراضي `pnpm test:e2e` - يتطلب CLI محليًا لـ `openshell` بالإضافة إلى Docker daemon عامل - يستخدم `HOME` / `XDG_CONFIG_HOME` معزولين، ثم يدمّر test gateway وsandbox -- تجاوزات مفيدة: +- بدائل مفيدة: - `OPENCLAW_E2E_OPENSHELL=1` لتفعيل الاختبار عند تشغيل جناح e2e الأوسع يدويًا - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` للإشارة إلى ملف CLI binary أو wrapper script غير افتراضي + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` للإشارة إلى ملف CLI binary غير افتراضي أو wrapper script -### Live (موفّرو خدمة حقيقيون + نماذج حقيقية) +### Live (مزوّدون حقيقيون + نماذج حقيقية) - الأمر: `pnpm test:live` - الإعداد: `vitest.live.config.ts` - الملفات: `src/**/*.live.test.ts` - الافتراضي: **مفعّل** بواسطة `pnpm test:live` (يضبط `OPENCLAW_LIVE_TEST=1`) - النطاق: - - "هل يعمل هذا الموفّر/النموذج فعلًا _اليوم_ باستخدام بيانات اعتماد حقيقية؟" - - التقاط تغييرات تنسيق الموفّر، وخصوصيات استدعاء الأدوات، ومشكلات المصادقة، وسلوك حدود المعدل + - «هل يعمل هذا المزوّد/النموذج فعليًا _اليوم_ باستخدام بيانات اعتماد حقيقية؟» + - التقاط تغييرات تنسيق المزوّد، وخصوصيات استدعاء الأدوات، ومشكلات المصادقة، وسلوك حدود المعدل - التوقعات: - - غير مستقر في CI بطبيعته (شبكات حقيقية، وسياسات موفّر حقيقية، وحصص، وانقطاعات) + - غير مستقر في CI بطبيعته (شبكات حقيقية، وسياسات مزوّد حقيقية، وحصص، وانقطاعات) - يكلّف مالًا / يستهلك حدود المعدل - - يُفضَّل تشغيل مجموعات فرعية ضيقة بدلًا من "كل شيء" + - يُفضّل تشغيل مجموعات فرعية مضيقة بدلًا من «كل شيء» - تستورد التشغيلات الحية `~/.profile` لالتقاط مفاتيح API الناقصة. -- افتراضيًا، ما تزال التشغيلات الحية تعزل `HOME` وتنسخ مواد config/auth إلى منزل اختبار مؤقت حتى لا تتمكن تجهيزات unit من تعديل `~/.openclaw` الحقيقي لديك. -- عيّن `OPENCLAW_LIVE_USE_REAL_HOME=1` فقط عندما تحتاج عمدًا إلى أن تستخدم الاختبارات الحية دليلك المنزلي الحقيقي. -- أصبح `pnpm test:live` الآن يستخدم وضعًا أكثر هدوءًا افتراضيًا: فهو يُبقي إخراج التقدّم `[live] ...`، لكنه يخفي إشعار `~/.profile` الإضافي ويكتم سجلات إقلاع Gateway وضجيج Bonjour. عيّن `OPENCLAW_LIVE_TEST_QUIET=0` إذا كنت تريد استعادة سجلات بدء التشغيل الكاملة. -- تدوير مفاتيح API (خاص بكل موفّر): عيّن `*_API_KEYS` بصيغة فاصلة/فاصلة منقوطة أو `*_API_KEY_1` و`*_API_KEY_2` (على سبيل المثال `OPENAI_API_KEYS` و`ANTHROPIC_API_KEYS` و`GEMINI_API_KEYS`) أو تجاوزًا حيًا لكل حالة عبر `OPENCLAW_LIVE_*_KEY`؛ وتعيد الاختبارات المحاولة عند استجابات حدود المعدل. -- إخراج التقدّم/Heartbeat: - - أصبحت الأجنحة الحية الآن تُصدر أسطر التقدّم إلى stderr بحيث تبقى استدعاءات الموفّر الطويلة ظاهرة النشاط حتى عندما يكون التقاط وحدة تحكم Vitest هادئًا. - - يعطّل `vitest.live.config.ts` اعتراض وحدة التحكم في Vitest بحيث تتدفق أسطر تقدّم الموفّر/ Gateway فورًا أثناء التشغيلات الحية. - - اضبط Heartbeat النماذج المباشرة باستخدام `OPENCLAW_LIVE_HEARTBEAT_MS`. - - اضبط Heartbeat الـ Gateway/المجسات باستخدام `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. +- افتراضيًا، لا تزال التشغيلات الحية تعزل `HOME` وتنسخ مواد config/auth إلى test home مؤقت حتى لا تتمكن تركيبات unit الثابتة من تعديل `~/.openclaw` الحقيقي لديك. +- اضبط `OPENCLAW_LIVE_USE_REAL_HOME=1` فقط عندما تحتاج عمدًا إلى أن تستخدم الاختبارات الحية دليل المنزل الحقيقي لديك. +- أصبح `pnpm test:live` افتراضيًا يعمل في وضع أهدأ: فهو يحتفظ بمخرجات التقدم `[live] ...`، لكنه يخفي إشعار `~/.profile` الإضافي ويكتم سجلات bootstrap الخاصة بـ gateway وضجيج Bonjour. اضبط `OPENCLAW_LIVE_TEST_QUIET=0` إذا أردت سجلات البدء الكاملة مجددًا. +- تدوير مفاتيح API (خاص بالمزوّد): اضبط `*_API_KEYS` باستخدام صيغة الفاصلة/الفاصلة المنقوطة أو `*_API_KEY_1` و`*_API_KEY_2` (على سبيل المثال `OPENAI_API_KEYS` و`ANTHROPIC_API_KEYS` و`GEMINI_API_KEYS`) أو استخدم override لكل live عبر `OPENCLAW_LIVE_*_KEY`؛ تعيد الاختبارات المحاولة عند استجابات rate limit. +- مخرجات التقدم/Heartbeat: + - تصدر الأجنحة الحية الآن أسطر التقدم إلى stderr بحيث يظهر أن استدعاءات المزوّد الطويلة نشطة حتى عندما يكون التقاط الطرفية في Vitest هادئًا. + - يعطّل `vitest.live.config.ts` اعتراض الطرفية في Vitest بحيث تتدفق أسطر تقدم المزوّد/gateway فورًا أثناء التشغيلات الحية. + - اضبط Heartbeat للنموذج المباشر باستخدام `OPENCLAW_LIVE_HEARTBEAT_MS`. + - اضبط Heartbeat الخاص بـ gateway/probe باستخدام `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. -## أي جناح يجب أن أشغّل؟ +## ما الجناح الذي يجب أن أشغّله؟ استخدم جدول القرار هذا: -- تعديل المنطق/الاختبارات: شغّل `pnpm test` (و`pnpm test:coverage` إذا غيّرت كثيرًا) -- لمس شبكات Gateway / بروتوكول WS / الاقتران: أضف `pnpm test:e2e` -- تصحيح "الروبوت الخاص بي متعطل" / الإخفاقات الخاصة بالموفّر / استدعاء الأدوات: شغّل `pnpm test:live` بشكل مقيّد +- عند تعديل المنطق/الاختبارات: شغّل `pnpm test` (و`pnpm test:coverage` إذا غيّرت الكثير) +- عند لمس شبكات gateway / بروتوكول WS / الإقران: أضف `pnpm test:e2e` +- عند تصحيح «تعطل bot الخاص بي» / الأعطال الخاصة بالمزوّد / استدعاء الأدوات: شغّل `pnpm test:live` بعد تضييقه ## Live: مسح قدرات Android Node - الاختبار: `src/gateway/android-node.capabilities.live.test.ts` - السكربت: `pnpm android:test:integration` -- الهدف: استدعاء **كل أمر مُعلَن عنه حاليًا** بواسطة Android Node متصل والتحقق من سلوك عقد الأوامر. +- الهدف: استدعاء **كل أمر مُعلن عنه حاليًا** من Android Node متصل والتحقق من سلوك عقد الأمر. - النطاق: - إعداد مسبق/يدوي (لا يقوم الجناح بتثبيت التطبيق أو تشغيله أو إقرانه). - التحقق من `node.invoke` في Gateway أمرًا بأمر لـ Android Node المحدد. - الإعداد المسبق المطلوب: - - تطبيق Android متصل ومقترن بالفعل مع Gateway. + - أن يكون تطبيق Android متصلًا ومقترنًا بالفعل مع gateway. - إبقاء التطبيق في الواجهة الأمامية. - - منح الأذونات/موافقة الالتقاط للقدرات التي تتوقع أن تنجح. -- تجاوزات الهدف الاختيارية: + - منح الأذونات/موافقة الالتقاط للقدرات التي تتوقع نجاحها. +- بدائل الهدف الاختيارية: - `OPENCLAW_ANDROID_NODE_ID` أو `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. - تفاصيل إعداد Android الكاملة: [تطبيق Android](/ar/platforms/android) -## Live: اختبار النموذج الدخاني (مفاتيح الملف الشخصي) +## Live: فحص Smoke للنموذج (مفاتيح profile) تنقسم الاختبارات الحية إلى طبقتين حتى نتمكن من عزل الإخفاقات: -- يوضح "النموذج المباشر" ما إذا كان الموفّر/النموذج يستطيع الرد أصلًا بالمفتاح المعطى. -- يوضح "اختبار Gateway الدخاني" ما إذا كان مسار Gateway+agent الكامل يعمل لهذا النموذج (الجلسات، والسجل، والأدوات، وسياسة sandbox، وما إلى ذلك). +- «النموذج المباشر» يخبرنا ما إذا كان المزوّد/النموذج قادرًا على الاستجابة أصلًا باستخدام المفتاح المعطى. +- «فحص Smoke للـ Gateway» يخبرنا ما إذا كان خط gateway+agent الكامل يعمل لهذا النموذج (الجلسات، السجل، الأدوات، سياسة sandbox، إلخ). -### الطبقة 1: إكمال النموذج المباشر (من دون Gateway) +### الطبقة 1: إكمال النموذج المباشر (بدون gateway) - الاختبار: `src/agents/models.profiles.live.test.ts` - الهدف: - تعداد النماذج المكتشفة - - استخدام `getApiKeyForModel` لاختيار النماذج التي تملك بيانات اعتماد لها - - تشغيل إكمال صغير لكل نموذج (واختبارات تراجعية مستهدفة عند الحاجة) + - استخدام `getApiKeyForModel` لاختيار النماذج التي لديك بيانات اعتماد لها + - تشغيل إكمال صغير لكل نموذج (واختبارات انحدار مستهدفة عند الحاجة) - كيفية التفعيل: - `pnpm test:live` (أو `OPENCLAW_LIVE_TEST=1` إذا كنت تستدعي Vitest مباشرة) -- عيّن `OPENCLAW_LIVE_MODELS=modern` (أو `all`، وهو اسم بديل لـ modern) لتشغيل هذا الجناح فعليًا؛ وإلا فسيتخطاه للحفاظ على تركيز `pnpm test:live` على اختبار Gateway الدخاني +- اضبط `OPENCLAW_LIVE_MODELS=modern` (أو `all`، وهو اسم بديل لـ modern) لتشغيل هذا الجناح فعليًا؛ وإلا فسيتخطاه للحفاظ على تركيز `pnpm test:live` على فحص Gateway smoke - كيفية اختيار النماذج: - - `OPENCLAW_LIVE_MODELS=modern` لتشغيل قائمة السماح الحديثة (`Opus/Sonnet 4.6+` و`GPT-5.x + Codex` و`Gemini 3` و`GLM 4.7` و`MiniMax M2.7` و`Grok 4`) - - `OPENCLAW_LIVE_MODELS=all` هو اسم بديل لقائمة السماح الحديثة - - أو `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (قائمة سماح مفصولة بفواصل) - - تستخدم عمليات المسح modern/all افتراضيًا حدًا منسقًا عالي الإشارة؛ عيّن `OPENCLAW_LIVE_MAX_MODELS=0` لمسح حديث شامل أو رقمًا موجبًا لحد أصغر. -- كيفية اختيار موفّري الخدمة: - - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (قائمة سماح مفصولة بفواصل) + - `OPENCLAW_LIVE_MODELS=modern` لتشغيل allowlist الحديث (Opus/Sonnet 4.6+، وGPT-5.x + Codex، وGemini 3، وGLM 4.7، وMiniMax M2.7، وGrok 4) + - `OPENCLAW_LIVE_MODELS=all` هو اسم بديل لـ allowlist الحديث + - أو `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist مفصول بفواصل) + - تستخدم عمليات المسح modern/all افتراضيًا حدًا منسقًا عالي الإشارة؛ اضبط `OPENCLAW_LIVE_MAX_MODELS=0` لإجراء مسح حديث شامل أو قيمة موجبة لحد أصغر. +- كيفية اختيار المزوّدين: + - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist مفصول بفواصل) - من أين تأتي المفاتيح: - - افتراضيًا: مخزن الملفات الشخصية وبدائل البيئة - - عيّن `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` لفرض **مخزن الملفات الشخصية** فقط + - افتراضيًا: مخزن profile وبدائل env + - اضبط `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` لفرض **مخزن profile** فقط - سبب وجود هذا: - - يفصل بين "واجهة API الخاصة بالموفّر معطلة / المفتاح غير صالح" و"مسار Gateway agent معطل" - - يحتوي اختبارات تراجعية صغيرة ومعزولة (مثال: تدفق reasoning replay + tool-call في OpenAI Responses/Codex Responses) + - يفصل بين «واجهة API الخاصة بالمزوّد معطلة / المفتاح غير صالح» و«مسار gateway agent معطل» + - يحتوي اختبارات انحدار صغيرة ومعزولة (مثال: OpenAI Responses/Codex Responses reasoning replay + تدفقات tool-call) -### الطبقة 2: اختبار Gateway + dev agent الدخاني (ما الذي يفعله "@openclaw" فعليًا) +### الطبقة 2: Gateway + فحص Smoke لوكيل dev (ما الذي يفعله "@openclaw" فعليًا) - الاختبار: `src/gateway/gateway-models.profiles.live.test.ts` - الهدف: - - تشغيل Gateway داخل العملية - - إنشاء/ترقيع جلسة `agent:dev:*` (مع تجاوز النموذج لكل تشغيل) - - تكرار النماذج التي لديها مفاتيح والتحقق من: - - استجابة "ذات معنى" (من دون أدوات) - - أن استدعاء أداة حقيقي يعمل (مجس `read`) - - مجسات أدوات إضافية اختيارية (مجس `exec+read`) - - استمرار عمل مسارات OpenAI التراجعية (استدعاء-أداة-فقط ← متابعة) -- تفاصيل المجسات (حتى تتمكن من شرح الإخفاقات بسرعة): - - مجس `read`: يكتب الاختبار ملف nonce في مساحة العمل ويطلب من الوكيل أن يقرأه عبر `read` ثم يعيد nonce. - - مجس `exec+read`: يطلب الاختبار من الوكيل أن يكتب nonce عبر `exec` داخل ملف مؤقت، ثم يقرأه مجددًا. - - مجس الصورة: يرفق الاختبار صورة PNG مولّدة (قط + رمز عشوائي) ويتوقع من النموذج أن يعيد `cat `. + - تشغيل gateway داخل العملية + - إنشاء/ترقيع جلسة `agent:dev:*` (مع override للنموذج في كل تشغيل) + - تكرار models-with-keys والتحقق من: + - استجابة «ذات معنى» (بدون أدوات) + - نجاح استدعاء أداة حقيقي (فحص `read`) + - فحوصات أدوات إضافية اختيارية (فحص `exec+read`) + - استمرار عمل مسارات انحدار OpenAI (tool-call-only → follow-up) +- تفاصيل الفحص (حتى تتمكن من شرح الإخفاقات بسرعة): + - فحص `read`: يكتب الاختبار ملف nonce في مساحة العمل ويطلب من الوكيل `read` له وإرجاع nonce. + - فحص `exec+read`: يطلب الاختبار من الوكيل كتابة nonce عبر `exec` في ملف مؤقت، ثم `read` له مجددًا. + - فحص الصورة: يرفق الاختبار ملف PNG مولدًا (قطة + رمز عشوائي) ويتوقع من النموذج إرجاع `cat `. - مرجع التنفيذ: `src/gateway/gateway-models.profiles.live.test.ts` و`src/gateway/live-image-probe.ts`. - كيفية التفعيل: - `pnpm test:live` (أو `OPENCLAW_LIVE_TEST=1` إذا كنت تستدعي Vitest مباشرة) - كيفية اختيار النماذج: - - الافتراضي: قائمة السماح الحديثة (`Opus/Sonnet 4.6+` و`GPT-5.x + Codex` و`Gemini 3` و`GLM 4.7` و`MiniMax M2.7` و`Grok 4`) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` هو اسم بديل لقائمة السماح الحديثة - - أو عيّن `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (أو قائمة مفصولة بفواصل) للتضييق - - تستخدم عمليات المسح الحديثة/`all` الخاصة بـ Gateway افتراضيًا حدًا منسقًا عالي الإشارة؛ عيّن `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` لمسح حديث شامل أو رقمًا موجبًا لحد أصغر. -- كيفية اختيار موفّري الخدمة (لتجنب "كل شيء عبر OpenRouter"): - - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (قائمة سماح مفصولة بفواصل) -- مجسات الأدوات + الصور مفعّلة دائمًا في هذا الاختبار الحي: - - مجس `read` + مجس `exec+read` (ضغط على الأدوات) - - يعمل مجس الصورة عندما يعلن النموذج دعمه لمدخلات الصور + - الافتراضي: allowlist الحديث (Opus/Sonnet 4.6+، وGPT-5.x + Codex، وGemini 3، وGLM 4.7، وMiniMax M2.7، وGrok 4) + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` هو اسم بديل لـ allowlist الحديث + - أو اضبط `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (أو قائمة مفصولة بفواصل) للتضييق + - تستخدم عمليات مسح gateway modern/all افتراضيًا حدًا منسقًا عالي الإشارة؛ اضبط `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` لإجراء مسح حديث شامل أو قيمة موجبة لحد أصغر. +- كيفية اختيار المزوّدين (تجنب «كل شيء عبر OpenRouter»): + - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist مفصول بفواصل) +- فحوصات الأدوات + الصور مفعلة دائمًا في هذا الاختبار الحي: + - فحص `read` + فحص `exec+read` (إجهاد الأدوات) + - يعمل فحص الصورة عندما يعلن النموذج دعم إدخال الصور - التدفق (على مستوى عالٍ): - - يولّد الاختبار PNG صغيرة تحتوي على "CAT" + رمز عشوائي (`src/gateway/live-image-probe.ts`) - - يرسلها عبر `agent` باستخدام `attachments: [{ mimeType: "image/png", content: "" }]` - - يحلّل Gateway المرفقات إلى `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - يمرر الوكيل المضمّن رسالة مستخدم متعددة الوسائط إلى النموذج - - التحقق: يحتوي الرد على `cat` + الرمز (سماحية OCR: الأخطاء البسيطة مسموح بها) + - يولد الاختبار ملف PNG صغيرًا يحتوي على “CAT” + رمز عشوائي (`src/gateway/live-image-probe.ts`) + - يرسله عبر `agent` `attachments: [{ mimeType: "image/png", content: "" }]` + - يحلل Gateway المرفقات إلى `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - يمرر الوكيل المضمن رسالة مستخدم متعددة الوسائط إلى النموذج + - التحقق: تحتوي الاستجابة على `cat` + الرمز (سماحية OCR: تُسمح الأخطاء الطفيفة) -نصيحة: لمعرفة ما يمكنك اختباره على جهازك (ومعرّفات `provider/model` الدقيقة)، شغّل: +نصيحة: لمعرفة ما الذي يمكنك اختباره على جهازك (ومعرفات `provider/model` الدقيقة)، شغّل: ```bash openclaw models list openclaw models list --json ``` -## Live: اختبار الواجهة الخلفية CLI الدخاني (Claude أو Codex أو Gemini أو CLIات محلية أخرى) +## Live: فحص Smoke للواجهة الخلفية CLI (Claude أو Codex أو Gemini أو غيرها من CLI المحلية) - الاختبار: `src/gateway/gateway-cli-backend.live.test.ts` -- الهدف: التحقق من مسار Gateway + agent باستخدام واجهة خلفية CLI محلية، من دون لمس إعدادك الافتراضي. -- القيم الافتراضية للاختبار الدخاني الخاصة بكل واجهة خلفية موجودة مع تعريف `cli-backend.ts` الخاص بالـ extension المالكة. +- الهدف: التحقق من مسار Gateway + الوكيل باستخدام واجهة خلفية CLI محلية، دون المساس بإعدادك الافتراضي. +- توجد افتراضيات فحص Smoke الخاصة بكل واجهة خلفية مع تعريف `cli-backend.ts` الذي تملكه الإضافة المعنية. - التفعيل: - `pnpm test:live` (أو `OPENCLAW_LIVE_TEST=1` إذا كنت تستدعي Vitest مباشرة) - `OPENCLAW_LIVE_CLI_BACKEND=1` -- القيم الافتراضية: - - الموفّر/النموذج الافتراضي: `claude-cli/claude-sonnet-4-6` - - يأتي سلوك الأمر/الوسائط/الصور من بيانات تعريف Plugin الواجهة الخلفية CLI المالكة. -- التجاوزات (اختيارية): +- الافتراضيات: + - المزوّد/النموذج الافتراضي: `claude-cli/claude-sonnet-4-6` + - يأتي سلوك الأمر/الوسائط/الصور من metadata الخاصة بـ Plugin الواجهة الخلفية CLI المالكة. +- التبديلات الاختيارية: - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` لإرسال مرفق صورة حقيقي (تُحقن المسارات في الموجّه). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` لتمرير مسارات ملفات الصور كوسائط CLI بدلًا من حقنها في الموجّه. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (أو `"list"`) للتحكم في كيفية تمرير وسائط الصور عند تعيين `IMAGE_ARG`. - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` لإرسال دور ثانٍ والتحقق من تدفق الاستئناف. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` لتعطيل مجس الاستمرارية الافتراضي داخل الجلسة نفسها من Claude Sonnet إلى Opus (عيّنه إلى `1` لفرض تفعيله عندما يدعم النموذج المحدد هدف تبديل). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` لإرسال مرفق صورة حقيقي (تُحقن المسارات في prompt). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` لتمرير مسارات ملفات الصور بوصفها وسائط CLI بدلًا من حقنها في prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (أو `"list"`) للتحكم في كيفية تمرير وسائط الصور عند ضبط `IMAGE_ARG`. + - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` لإرسال دورة ثانية والتحقق من تدفق الاستئناف. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` لتعطيل فحص الاستمرارية الافتراضي للجلسة نفسها من Claude Sonnet إلى Opus (اضبطه إلى `1` لفرض تفعيله عندما يدعم النموذج المحدد هدف تبديل). مثال: @@ -499,7 +498,7 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \ pnpm test:docker:live-cli-backend ``` -وصفات Docker لموفّر واحد: +وصفات Docker لمزوّد واحد: ```bash pnpm test:docker:live-cli-backend:claude @@ -511,37 +510,37 @@ pnpm test:docker:live-cli-backend:gemini ملاحظات: - يوجد مشغّل Docker في `scripts/test-live-cli-backend-docker.sh`. -- يشغّل اختبار CLI-backend الحي داخل صورة Docker الخاصة بالمستودع كمستخدم `node` غير الجذر. -- يحل بيانات تعريف اختبار CLI الدخاني من الـ extension المالكة، ثم يثبّت حزمة Linux CLI المطابقة (`@anthropic-ai/claude-code` أو `@openai/codex` أو `@google/gemini-cli`) في بادئة قابلة للكتابة ومخزّنة مؤقتًا عند `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (الافتراضي: `~/.cache/openclaw/docker-cli-tools`). -- يتطلب `pnpm test:docker:live-cli-backend:claude-subscription` مصادقة OAuth محمولة لاشتراك Claude Code عبر أحد الخيارين: `~/.claude/.credentials.json` مع `claudeAiOauth.subscriptionType` أو `CLAUDE_CODE_OAUTH_TOKEN` من `claude setup-token`. يثبت أولًا عمل `claude -p` مباشرة داخل Docker، ثم يشغّل دورين لـ Gateway CLI-backend من دون الاحتفاظ بمتغيرات البيئة الخاصة بمفتاح Anthropic API. يعطّل هذا المسار المعتمد على الاشتراك مجسات Claude MCP/tool والصور افتراضيًا لأن Claude يوجّه حاليًا استخدام التطبيقات الخارجية عبر فوترة استخدام إضافي بدل حدود خطة الاشتراك العادية. -- يختبر اختبار CLI-backend الحي الآن التدفق الكامل نفسه من طرف إلى طرف لكل من Claude وCodex وGemini: دور نصي، ثم دور تصنيف صورة، ثم استدعاء أداة MCP `cron` يتم التحقق منه عبر Gateway CLI. -- يقوم الاختبار الدخاني الافتراضي لـ Claude أيضًا بترقيع الجلسة من Sonnet إلى Opus ويتحقق من أن الجلسة المستأنفة ما تزال تتذكر ملاحظة سابقة. +- يشغّل فحص Smoke للواجهة الخلفية CLI الحي داخل صورة Docker الخاصة بالمستودع باعتبار المستخدم غير الجذر `node`. +- يحل metadata الخاصة بفحص Smoke من الإضافة المالكة، ثم يثبّت حزمة Linux CLI المطابقة (`@anthropic-ai/claude-code` أو `@openai/codex` أو `@google/gemini-cli`) في prefix قابل للكتابة ومخزن مؤقتًا عند `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (الافتراضي: `~/.cache/openclaw/docker-cli-tools`). +- يتطلب `pnpm test:docker:live-cli-backend:claude-subscription` مصادقة OAuth محمولة لاشتراك Claude Code عبر أحد الخيارين `~/.claude/.credentials.json` مع `claudeAiOauth.subscriptionType` أو `CLAUDE_CODE_OAUTH_TOKEN` من `claude setup-token`. وهو يثبت أولًا نجاح `claude -p` المباشر في Docker، ثم يشغّل دورتين للواجهة الخلفية CLI في Gateway من دون الاحتفاظ بمتغيرات بيئة مفتاح Anthropic API. يعطّل هذا المسار الخاص بالاشتراك فحوصات Claude MCP/tool والصور افتراضيًا لأن Claude يوجّه حاليًا استخدام التطبيقات الخارجية عبر فوترة استخدام إضافي بدلًا من حدود خطة الاشتراك المعتادة. +- أصبح فحص Smoke للواجهة الخلفية CLI الحي الآن يمارس التدفق الكامل نفسه من طرف إلى طرف لكل من Claude وCodex وGemini: دورة نصية، ثم دورة تصنيف صورة، ثم استدعاء أداة MCP `cron` يتم التحقق منه عبر Gateway CLI. +- يقوم فحص Smoke الافتراضي لـ Claude أيضًا بترقيع الجلسة من Sonnet إلى Opus ويتحقق من أن الجلسة المستأنفة لا تزال تتذكر ملاحظة سابقة. -## Live: اختبار ACP bind الدخاني (`/acp spawn ... --bind here`) +## Live: فحص Smoke لربط ACP (`/acp spawn ... --bind here`) - الاختبار: `src/gateway/gateway-acp-bind.live.test.ts` -- الهدف: التحقق من تدفق ربط المحادثة ACP الحقيقي باستخدام ACP agent حي: +- الهدف: التحقق من تدفق ربط المحادثة ACP الحقيقي باستخدام وكيل ACP حي: - إرسال `/acp spawn --bind here` - - ربط محادثة synthetic message-channel في مكانها + - ربط محادثة قناة رسائل تركيبية في مكانها - إرسال متابعة عادية على نفس المحادثة - - التحقق من وصول المتابعة إلى transcript جلسة ACP المرتبطة + - التحقق من أن المتابعة تصل إلى transcript جلسة ACP المرتبطة - التفعيل: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` -- القيم الافتراضية: - - ACP agents في Docker: `claude,codex,gemini` - - ACP agent لـ `pnpm test:live ...` المباشر: `claude` - - القناة الاصطناعية: سياق محادثة بأسلوب Slack DM - - الواجهة الخلفية ACP: `acpx` -- التجاوزات: +- الافتراضيات: + - وكلاء ACP في Docker: `claude,codex,gemini` + - وكيل ACP لتشغيل `pnpm test:live ...` المباشر: `claude` + - القناة التركيبية: سياق محادثة بأسلوب Slack DM + - الواجهة الخلفية لـ ACP: `acpx` +- التبديلات: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` - `OPENCLAW_LIVE_ACP_BIND_AGENT=gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - ملاحظات: - - يستخدم هذا المسار سطح Gateway `chat.send` مع حقول originating-route اصطناعية للمشرف فقط حتى تتمكن الاختبارات من إرفاق سياق message-channel من دون التظاهر بالتسليم الخارجي. - - عندما لا يكون `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` معيّنًا، يستخدم الاختبار سجل الوكلاء المضمّن في Plugin `acpx` المضمّنة لوكيل ACP harness المحدد. + - يستخدم هذا المسار سطح Gateway `chat.send` مع حقول originating-route تركيبية مخصصة للمشرف فقط حتى تتمكن الاختبارات من إرفاق سياق قناة الرسائل من دون التظاهر بالتسليم الخارجي. + - عندما لا يتم ضبط `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND`، يستخدم الاختبار سجل الوكلاء المضمن في Plugin `acpx` لاختيار وكيل harness ACP المحدد. مثال: @@ -568,30 +567,31 @@ pnpm test:docker:live-acp-bind:gemini ملاحظات Docker: - يوجد مشغّل Docker في `scripts/test-live-acp-bind-docker.sh`. -- افتراضيًا، يشغّل اختبار ACP bind الدخاني على جميع وكلاء CLI الحية المدعومة بالتتابع: `claude` ثم `codex` ثم `gemini`. +- افتراضيًا، يشغّل فحص Smoke لربط ACP مقابل جميع وكلاء CLI الأحياء المدعومين بالتسلسل: `claude` ثم `codex` ثم `gemini`. - استخدم `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude` أو `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` أو `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` لتضييق المصفوفة. -- يستورد `~/.profile`، ويجهّز مواد مصادقة CLI المطابقة داخل الحاوية، ويثبّت `acpx` في بادئة npm قابلة للكتابة، ثم يثبّت CLI الحي المطلوب (`@anthropic-ai/claude-code` أو `@openai/codex` أو `@google/gemini-cli`) إذا كان مفقودًا. -- داخل Docker، يضبط المشغّل `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` بحيث يُبقي acpx متغيرات بيئة الموفّر من الملف الشخصي المستورَد متاحة لـ harness CLI الفرعي. +- يقوم بتحميل `~/.profile`، وتجهيز مواد مصادقة CLI المطابقة داخل الحاوية، وتثبيت `acpx` في npm prefix قابل للكتابة، ثم يثبّت CLI الحي المطلوب (`@anthropic-ai/claude-code` أو `@openai/codex` أو `@google/gemini-cli`) إذا كان مفقودًا. +- داخل Docker، يضبط المشغّل `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` حتى يحتفظ acpx بمتغيرات بيئة المزوّد من profile المحمّل متاحةً لـ harness CLI الفرعي. -## Live: اختبار Codex app-server harness الدخاني +## Live: فحص Smoke لحزمة Codex app-server -- الهدف: التحقق من Codex harness المملوكة للـ Plugin عبر الأسلوب الطبيعي - `agent` في Gateway: - - تحميل Plugin `codex` المضمّنة +- الهدف: التحقق من Codex harness المملوك للإضافة عبر الطريقة + العادية `agent` في gateway: + - تحميل Plugin `codex` المضمّن - اختيار `OPENCLAW_AGENT_RUNTIME=codex` - - إرسال أول دور Gateway agent إلى `codex/gpt-5.4` - - إرسال دور ثانٍ إلى جلسة OpenClaw نفسها والتحقق من أن سلسلة app-server - يمكنها الاستئناف - - تشغيل `/codex status` و`/codex models` عبر مسار أمر Gateway نفسه + - إرسال أول دورة وكيل عبر gateway إلى `codex/gpt-5.4` + - إرسال دورة ثانية إلى جلسة OpenClaw نفسها والتحقق من أن + thread الخاص بـ app-server يمكنه الاستئناف + - تشغيل `/codex status` و`/codex models` عبر مسار + أوامر gateway نفسه - الاختبار: `src/gateway/gateway-codex-harness.live.test.ts` - التفعيل: `OPENCLAW_LIVE_CODEX_HARNESS=1` - النموذج الافتراضي: `codex/gpt-5.4` -- مجس صورة اختياري: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- مجس MCP/tool اختياري: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- يضبط الاختبار الدخاني `OPENCLAW_AGENT_HARNESS_FALLBACK=none` حتى لا يتمكن - Codex harness المعطوب من النجاح عبر الرجوع الصامت إلى PI. -- المصادقة: `OPENAI_API_KEY` من الصدفة/الملف الشخصي، بالإضافة إلى - `~/.codex/auth.json` و`~/.codex/config.toml` المنسوخين اختياريًا +- فحص صورة اختياري: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- فحص MCP/tool اختياري: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- يضبط فحص Smoke هذا `OPENCLAW_AGENT_HARNESS_FALLBACK=none` حتى لا يتمكن + Codex harness المعطل من النجاح عبر الرجوع الصامت إلى PI. +- المصادقة: `OPENAI_API_KEY` من shell/profile، بالإضافة إلى نسخ اختيارية من + `~/.codex/auth.json` و`~/.codex/config.toml` وصفة محلية: @@ -614,111 +614,113 @@ pnpm test:docker:live-codex-harness ملاحظات Docker: - يوجد مشغّل Docker في `scripts/test-live-codex-harness-docker.sh`. -- يستورد `~/.profile` المركّب، ويمرر `OPENAI_API_KEY`، وينسخ ملفات مصادقة Codex CLI - عند وجودها، ويثبّت `@openai/codex` في بادئة npm مركّبة قابلة للكتابة، - ويجهّز شجرة المصدر، ثم يشغّل فقط الاختبار الحي الخاص بـ Codex-harness. -- يفعّل Docker مجسات الصورة وMCP/tool افتراضيًا. عيّن +- يقوم بتحميل `~/.profile` الموصّل، ويمرّر `OPENAI_API_KEY`، وينسخ ملفات + مصادقة Codex CLI عند وجودها، ويثبّت `@openai/codex` في npm prefix + موصول وقابل للكتابة، ويجهّز شجرة المصدر، ثم يشغّل فقط الاختبار الحي + لـ Codex-harness. +- يفعّل Docker فحوصات الصورة وMCP/tool افتراضيًا. اضبط `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` أو - `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` عندما تحتاج إلى تشغيل تصحيح أضيق. + `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` عندما تحتاج إلى تشغيل تصحيح + أضيق. - يصدّر Docker أيضًا `OPENCLAW_AGENT_HARNESS_FALLBACK=none`، بما يطابق إعداد - الاختبار الحي بحيث لا يتمكن الرجوع إلى `openai-codex/*` أو PI من إخفاء - تراجع في Codex harness. + الاختبار الحي بحيث لا يمكن لـ `openai-codex/*` أو fallback إلى PI + إخفاء اختبار انحدار في Codex harness. ### الوصفات الحية الموصى بها -قوائم السماح الضيقة والصريحة هي الأسرع والأقل عرضة للهشاشة: +تعد allowlist الضيقة والصريحة الأسرع والأقل عرضة لعدم الاستقرار: -- نموذج واحد، مباشر (من دون Gateway): +- نموذج واحد، مباشر (بدون gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- نموذج واحد، اختبار Gateway دخاني: +- نموذج واحد، فحص Gateway smoke: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- استدعاء الأدوات عبر عدة موفّري خدمة: +- استدعاء الأدوات عبر عدة مزوّدين: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- تركيز Google (مفتاح Gemini API + Antigravity): +- التركيز على Google (مفتاح Gemini API + Antigravity): - Gemini (مفتاح API): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` ملاحظات: -- يستخدم `google/...` واجهة Gemini API (مفتاح API). -- يستخدم `google-antigravity/...` جسر Antigravity OAuth (نقطة نهاية وكيل بأسلوب Cloud Code Assist). -- يستخدم `google-gemini-cli/...` Gemini CLI المحلي على جهازك (مصادقة منفصلة وخصوصيات مختلفة للأدوات). +- `google/...` يستخدم Gemini API (مفتاح API). +- `google-antigravity/...` يستخدم جسر Antigravity OAuth (نقطة نهاية وكيل بأسلوب Cloud Code Assist). +- `google-gemini-cli/...` يستخدم Gemini CLI المحلي على جهازك (مصادقة منفصلة وخصائص أدوات مختلفة). - Gemini API مقابل Gemini CLI: - - API: يستدعي OpenClaw واجهة Gemini API المستضافة من Google عبر HTTP (مصادقة مفتاح API / الملف الشخصي)؛ وهذا هو ما يقصده معظم المستخدمين عندما يقولون "Gemini". - - CLI: ينفّذ OpenClaw أمر `gemini` binary محلي؛ وله مصادقة خاصة به وقد يتصرف بشكل مختلف (البث، ودعم الأدوات، واختلافات الإصدارات). + - API: يستدعي OpenClaw واجهة Gemini API المستضافة من Google عبر HTTP (بمصادقة مفتاح API / profile)؛ وهذا ما يقصده معظم المستخدمين عندما يقولون “Gemini”. + - CLI: يستدعي OpenClaw ملف `gemini` المحلي؛ وله مصادقته الخاصة وقد يتصرف بشكل مختلف (البث، ودعم الأدوات، واختلاف الإصدارات). ## Live: مصفوفة النماذج (ما الذي نغطيه) -لا توجد "قائمة نماذج CI" ثابتة (الاختبارات الحية تعمل عند الاختيار فقط)، لكن هذه هي النماذج **الموصى بها** للتغطية بانتظام على جهاز تطوير يملك مفاتيح. +لا توجد «قائمة نماذج CI» ثابتة (لأن live اختياري)، لكن هذه هي النماذج **الموصى بها** للتغطية بانتظام على جهاز تطوير يملك مفاتيح. -### مجموعة الاختبار الدخاني الحديثة (استدعاء الأدوات + الصور) +### مجموعة الفحص الحديثة (استدعاء الأدوات + الصورة) -هذا هو تشغيل "النماذج الشائعة" الذي نتوقع أن يستمر في العمل: +هذا هو تشغيل «النماذج الشائعة» الذي نتوقع أن يظل يعمل: - OpenAI (غير Codex): `openai/gpt-5.4` (اختياري: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` - Anthropic: `anthropic/claude-opus-4-6` (أو `anthropic/claude-sonnet-4-6`) -- Google (Gemini API): `google/gemini-3.1-pro-preview` و`google/gemini-3-flash-preview` (تجنب نماذج Gemini 2.x الأقدم) -- Google (Antigravity): `google-antigravity/claude-opus-4-6-thinking` و`google-antigravity/gemini-3-flash` -- Z.AI (GLM): `zai/glm-4.7` -- MiniMax: `minimax/MiniMax-M2.7` +- Google (Gemini API): ‏`google/gemini-3.1-pro-preview` و`google/gemini-3-flash-preview` (تجنب نماذج Gemini 2.x الأقدم) +- Google (Antigravity): ‏`google-antigravity/claude-opus-4-6-thinking` و`google-antigravity/gemini-3-flash` +- Z.AI (GLM): ‏`zai/glm-4.7` +- MiniMax: ‏`minimax/MiniMax-M2.7` -شغّل اختبار Gateway الدخاني مع الأدوات + الصور: +شغّل فحص Gateway smoke مع الأدوات + الصورة: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### الخط الأساسي: استدعاء الأدوات (`Read` + `Exec` اختياري) +### الأساس: استدعاء الأدوات (Read + Exec اختياري) -اختر واحدًا على الأقل من كل عائلة موفّري خدمة: +اختر واحدًا على الأقل لكل عائلة مزوّدين: - OpenAI: `openai/gpt-5.4` (أو `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (أو `anthropic/claude-sonnet-4-6`) - Google: `google/gemini-3-flash-preview` (أو `google/gemini-3.1-pro-preview`) -- Z.AI (GLM): `zai/glm-4.7` -- MiniMax: `minimax/MiniMax-M2.7` +- Z.AI (GLM): ‏`zai/glm-4.7` +- MiniMax: ‏`minimax/MiniMax-M2.7` تغطية إضافية اختيارية (من الجيد توفرها): -- xAI: `xai/grok-4` (أو أحدث إصدار متاح) -- Mistral: `mistral/`… (اختر نموذجًا واحدًا يدعم "الأدوات" ومفعّلًا لديك) -- Cerebras: `cerebras/`… (إذا كان لديك وصول) -- LM Studio: `lmstudio/`… (محلي؛ يعتمد استدعاء الأدوات على وضع API) +- xAI: ‏`xai/grok-4` (أو أحدث إصدار متاح) +- Mistral: ‏`mistral/`… (اختر نموذجًا واحدًا قادرًا على “tools” لديك) +- Cerebras: ‏`cerebras/`… (إذا كان لديك وصول) +- LM Studio: ‏`lmstudio/`… (محلي؛ يعتمد استدعاء الأدوات على وضع API) -### الرؤية: إرسال صورة (مرفق ← رسالة متعددة الوسائط) +### Vision: إرسال صورة (مرفق ← رسالة متعددة الوسائط) -ضمّن نموذجًا واحدًا على الأقل قادرًا على الصور في `OPENCLAW_LIVE_GATEWAY_MODELS` (مثل Claude أو Gemini أو متغيرات OpenAI القادرة على الرؤية، إلخ) لتجربة مجس الصورة. +ضمّن نموذجًا واحدًا على الأقل قادرًا على التعامل مع الصور داخل `OPENCLAW_LIVE_GATEWAY_MODELS` (مثل Claude/Gemini/OpenAI بالإصدارات القادرة على Vision، إلخ) لتمرير فحص الصورة. -### المجمّعات / Gateways البديلة +### المجمّعات / بوابات بديلة -إذا كانت لديك مفاتيح مفعّلة، فنحن ندعم أيضًا الاختبار عبر: +إذا كانت لديك مفاتيح مفعلة، فنحن ندعم أيضًا الاختبار عبر: -- OpenRouter: `openrouter/...` (مئات النماذج؛ استخدم `openclaw models scan` للعثور على مرشحين يدعمون الأدوات + الصور) -- OpenCode: `opencode/...` لـ Zen و`opencode-go/...` لـ Go (المصادقة عبر `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) +- OpenRouter: ‏`openrouter/...` (مئات النماذج؛ استخدم `openclaw models scan` للعثور على مرشحين قادرين على الأدوات+الصور) +- OpenCode: ‏`opencode/...` من أجل Zen و`opencode-go/...` من أجل Go (المصادقة عبر `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -مزيد من موفّري الخدمة الذين يمكنك تضمينهم في المصفوفة الحية (إذا كانت لديك بيانات الاعتماد/الإعداد): +مزيد من المزوّدين الذين يمكنك تضمينهم في مصفوفة live (إذا كانت لديك بيانات اعتماد/إعدادات): -- المضمّنون: `openai` و`openai-codex` و`anthropic` و`google` و`google-vertex` و`google-antigravity` و`google-gemini-cli` و`zai` و`openrouter` و`opencode` و`opencode-go` و`xai` و`groq` و`cerebras` و`mistral` و`github-copilot` -- عبر `models.providers` (نقاط نهاية مخصصة): `minimax` (سحابي/API)، بالإضافة إلى أي وكيل متوافق مع OpenAI/Anthropic (مثل LM Studio أو vLLM أو LiteLLM، إلخ) +- مضمّنة: `openai` و`openai-codex` و`anthropic` و`google` و`google-vertex` و`google-antigravity` و`google-gemini-cli` و`zai` و`openrouter` و`opencode` و`opencode-go` و`xai` و`groq` و`cerebras` و`mistral` و`github-copilot` +- عبر `models.providers` (نقاط نهاية مخصصة): `minimax` (سحابي/API)، بالإضافة إلى أي proxy متوافق مع OpenAI/Anthropic (مثل LM Studio وvLLM وLiteLLM، إلخ) -نصيحة: لا تحاول ترميز "كل النماذج" ترميزًا ثابتًا في المستندات. القائمة المرجعية هي كل ما ترجعه `discoverModels(...)` على جهازك + كل المفاتيح المتاحة. +نصيحة: لا تحاول ترميز «كل النماذج» بشكل ثابت في المستندات. القائمة الموثوقة هي ما يعيده `discoverModels(...)` على جهازك + أي مفاتيح متاحة. -## بيانات الاعتماد (لا تقم بعمل commit لها مطلقًا) +## بيانات الاعتماد (لا تُضمَّن في commit أبدًا) -تكتشف الاختبارات الحية بيانات الاعتماد بالطريقة نفسها التي تعمل بها CLI. الآثار العملية: +تكتشف الاختبارات الحية بيانات الاعتماد بالطريقة نفسها التي تعمل بها CLI. والنتائج العملية لذلك: - إذا كانت CLI تعمل، فيجب أن تعثر الاختبارات الحية على المفاتيح نفسها. -- إذا قال اختبار حي "لا توجد بيانات اعتماد"، فقم بالتصحيح بالطريقة نفسها التي ستصحح بها `openclaw models list` / اختيار النموذج. +- إذا قال اختبار حي «لا توجد بيانات اعتماد»، فقم بتصحيح المشكلة بالطريقة نفسها التي ستصحح بها `openclaw models list` / اختيار النموذج. -- ملفات المصادقة الشخصية لكل وكيل: `~/.openclaw/agents//agent/auth-profiles.json` (هذا هو المقصود بـ "مفاتيح الملف الشخصي" في الاختبارات الحية) +- ملفات auth profiles لكل وكيل: `~/.openclaw/agents//agent/auth-profiles.json` (وهذا ما تعنيه «profile keys» في الاختبارات الحية) - الإعداد: `~/.openclaw/openclaw.json` (أو `OPENCLAW_CONFIG_PATH`) -- دليل الحالة القديم: `~/.openclaw/credentials/` (يُنسخ إلى المنزل الحي المرحلي عند وجوده، لكنه ليس مخزن مفاتيح الملف الشخصي الرئيسي) -- تنسخ التشغيلات المحلية الحية الإعداد النشط وملفات `auth-profiles.json` الخاصة بكل وكيل و`credentials/` القديمة وأدلة مصادقة CLI الخارجية المدعومة إلى منزل اختبار مؤقت افتراضيًا؛ وتتخطى المنازل الحية المرحلية `workspace/` و`sandboxes/`، كما تُزال تجاوزات المسار `agents.*.workspace` و`agentDir` حتى تبقى المجسات بعيدة عن مساحة العمل الحقيقية على المضيف. +- دليل الحالة القديم: `~/.openclaw/credentials/` (يُنسخ إلى المنزل الحي المجهز عند وجوده، لكنه ليس مخزن مفاتيح profile الرئيسي) +- تقوم تشغيلات live المحلية بنسخ الإعداد النشط وملفات `auth-profiles.json` لكل وكيل و`credentials/` القديمة وأدلة مصادقة CLI الخارجية المدعومة إلى منزل اختبار مؤقت افتراضيًا؛ وتتخطى المنازل الحية المجهزة `workspace/` و`sandboxes/`، وتُزال تجاوزات المسار في `agents.*.workspace` و`agentDir` حتى تبقى الفحوصات بعيدة عن مساحة العمل الحقيقية على المضيف. -إذا كنت تريد الاعتماد على مفاتيح البيئة (مثلًا المُصدّرة في `~/.profile`)، فشغّل الاختبارات المحلية بعد `source ~/.profile`، أو استخدم مشغّلات Docker أدناه (يمكنها تركيب `~/.profile` داخل الحاوية). +إذا كنت تريد الاعتماد على مفاتيح env (على سبيل المثال المصدّرة في `~/.profile`)، فشغّل الاختبارات المحلية بعد `source ~/.profile`، أو استخدم مشغّلات Docker أدناه (يمكنها وصل `~/.profile` داخل الحاوية). -## Deepgram live (نسخ الصوت) +## Deepgram live (نسخ الصوت إلى نص) - الاختبار: `src/media-understanding/providers/deepgram/audio.live.test.ts` - التفعيل: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` @@ -734,26 +736,26 @@ pnpm test:docker:live-codex-harness - الاختبار: `extensions/comfy/comfy.live.test.ts` - التفعيل: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - النطاق: - - يختبر مسارات الصور والفيديو و`music_generate` المضمّنة في comfy - - يتخطى كل قدرة ما لم يكن `models.providers.comfy.` مضبوطًا - - مفيد بعد تغيير إرسال workflow في comfy أو polling أو التنزيلات أو تسجيل Plugin + - يمارس مسارات الصورة والفيديو و`music_generate` المضمّنة الخاصة بـ comfy + - يتخطى كل قدرة ما لم يتم ضبط `models.providers.comfy.` + - مفيد بعد تعديل إرسال سير العمل في comfy أو polling أو التنزيلات أو تسجيل Plugin ## Image generation live - الاختبار: `src/image-generation/runtime.live.test.ts` - الأمر: `pnpm test:live src/image-generation/runtime.live.test.ts` -- الحزام: `pnpm test:live:media image` +- الـ harness: `pnpm test:live:media image` - النطاق: - - يعدّد كل Provider Plugin مسجّل لتوليد الصور - - يحمّل متغيرات بيئة الموفّر الناقصة من صدفة تسجيل الدخول (`~/.profile`) قبل تنفيذ المجسات - - يستخدم مفاتيح API الحية/البيئية قبل ملفات المصادقة الشخصية المخزنة افتراضيًا، حتى لا تحجب مفاتيح الاختبار القديمة في `auth-profiles.json` بيانات اعتماد الصدفة الحقيقية - - يتخطى موفّري الخدمة الذين لا يملكون مصادقة/ملفًا شخصيًا/نموذجًا صالحًا - - يشغّل متغيرات توليد الصور القياسية عبر قدرة وقت التشغيل المشتركة: + - يعدّد كل Plugin مزوّد image-generation مسجل + - يحمّل متغيرات بيئة المزوّد الناقصة من shell تسجيل الدخول لديك (`~/.profile`) قبل الفحص + - يستخدم مفاتيح API الحية/من env قبل auth profiles المخزنة افتراضيًا، حتى لا تحجب مفاتيح الاختبار القديمة في `auth-profiles.json` بيانات اعتماد shell الحقيقية + - يتخطى المزوّدين الذين لا يملكون مصادقة/‏profile/نموذجًا صالحًا + - يشغّل متغيرات image-generation القياسية عبر قدرة وقت التشغيل المشتركة: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- موفّرو الخدمة المضمّنون المغطّون حاليًا: +- المزوّدون المضمّنون الحاليون المشمولون: - `openai` - `google` - التضييق الاختياري: @@ -761,262 +763,262 @@ pnpm test:docker:live-codex-harness - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` - سلوك المصادقة الاختياري: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` لفرض مصادقة مخزن الملفات الشخصية وتجاهل تجاوزات البيئة فقط + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` لفرض مصادقة مخزن profile وتجاهل overrides المعتمدة على env فقط ## Music generation live - الاختبار: `extensions/music-generation-providers.live.test.ts` - التفعيل: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` -- الحزام: `pnpm test:live:media music` +- الـ harness: `pnpm test:live:media music` - النطاق: - - يختبر مسار موفّر توليد الموسيقى المشترك المضمّن + - يمارس مسار مزوّد music-generation المضمّن المشترك - يغطي حاليًا Google وMiniMax - - يحمّل متغيرات بيئة الموفّر من صدفة تسجيل الدخول (`~/.profile`) قبل تنفيذ المجسات - - يستخدم مفاتيح API الحية/البيئية قبل ملفات المصادقة الشخصية المخزنة افتراضيًا، حتى لا تحجب مفاتيح الاختبار القديمة في `auth-profiles.json` بيانات اعتماد الصدفة الحقيقية - - يتخطى موفّري الخدمة الذين لا يملكون مصادقة/ملفًا شخصيًا/نموذجًا صالحًا - - يشغّل كلا وضعي وقت التشغيل المعلنين عند توفرهما: - - `generate` مع إدخال يعتمد على الموجّه فقط - - `edit` عندما يعلن الموفّر أن `capabilities.edit.enabled` مفعّل - - التغطية الحالية للمسار المشترك: - - `google`: ‏`generate`، ‏`edit` + - يحمّل متغيرات بيئة المزوّد من shell تسجيل الدخول لديك (`~/.profile`) قبل الفحص + - يستخدم مفاتيح API الحية/من env قبل auth profiles المخزنة افتراضيًا، حتى لا تحجب مفاتيح الاختبار القديمة في `auth-profiles.json` بيانات اعتماد shell الحقيقية + - يتخطى المزوّدين الذين لا يملكون مصادقة/‏profile/نموذجًا صالحًا + - يشغّل وضعي وقت التشغيل المعلنين كليهما عند توفرهما: + - `generate` مع إدخال يعتمد على prompt فقط + - `edit` عندما يعلن المزوّد `capabilities.edit.enabled` + - التغطية الحالية في المسار المشترك: + - `google`: ‏`generate`، `edit` - `minimax`: ‏`generate` - - `comfy`: ملف Comfy حي منفصل، وليس ضمن هذا المسح المشترك + - `comfy`: ملف Comfy حي منفصل، وليس هذا المسح المشترك - التضييق الاختياري: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` - سلوك المصادقة الاختياري: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` لفرض مصادقة مخزن الملفات الشخصية وتجاهل تجاوزات البيئة فقط + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` لفرض مصادقة مخزن profile وتجاهل overrides المعتمدة على env فقط ## Video generation live - الاختبار: `extensions/video-generation-providers.live.test.ts` - التفعيل: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` -- الحزام: `pnpm test:live:media video` +- الـ harness: `pnpm test:live:media video` - النطاق: - - يختبر مسار موفّر توليد الفيديو المشترك المضمّن - - يستخدم افتراضيًا مسار الاختبار الدخاني الآمن للإصدار: موفّرو خدمة غير FAL، وطلب text-to-video واحد لكل موفّر، وموجّه lobster مدته ثانية واحدة، وحد عملية لكل موفّر مأخوذ من `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (الافتراضي `180000`) - - يتخطى FAL افتراضيًا لأن زمن الانتظار في طوابير الموفّر قد يهيمن على وقت الإصدار؛ مرّر `--video-providers fal` أو `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` لتشغيله صراحة - - يحمّل متغيرات بيئة الموفّر من صدفة تسجيل الدخول (`~/.profile`) قبل تنفيذ المجسات - - يستخدم مفاتيح API الحية/البيئية قبل ملفات المصادقة الشخصية المخزنة افتراضيًا، حتى لا تحجب مفاتيح الاختبار القديمة في `auth-profiles.json` بيانات اعتماد الصدفة الحقيقية - - يتخطى موفّري الخدمة الذين لا يملكون مصادقة/ملفًا شخصيًا/نموذجًا صالحًا + - يمارس مسار مزوّد video-generation المضمّن المشترك + - يستخدم افتراضيًا مسار فحص smoke آمنًا للإصدارات: مزوّدات غير FAL، وطلب text-to-video واحد لكل مزوّد، وprompt لوبستر لمدة ثانية واحدة، وحد عملية لكل مزوّد من `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (الافتراضي `180000`) + - يتخطى FAL افتراضيًا لأن زمن الانتظار في طابور المزوّد قد يهيمن على وقت الإصدار؛ مرّر `--video-providers fal` أو `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` لتشغيله صراحةً + - يحمّل متغيرات بيئة المزوّد من shell تسجيل الدخول لديك (`~/.profile`) قبل الفحص + - يستخدم مفاتيح API الحية/من env قبل auth profiles المخزنة افتراضيًا، حتى لا تحجب مفاتيح الاختبار القديمة في `auth-profiles.json` بيانات اعتماد shell الحقيقية + - يتخطى المزوّدين الذين لا يملكون مصادقة/‏profile/نموذجًا صالحًا - يشغّل `generate` فقط افتراضيًا - - عيّن `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` لتشغيل أوضاع التحويل المعلنة أيضًا عند توفرها: - - `imageToVideo` عندما يعلن الموفّر أن `capabilities.imageToVideo.enabled` مفعّل ويقبل الموفّر/النموذج المحدد إدخال صورة محليًا مدعومًا بمخزن مؤقت في المسح المشترك - - `videoToVideo` عندما يعلن الموفّر أن `capabilities.videoToVideo.enabled` مفعّل ويقبل الموفّر/النموذج المحدد إدخال فيديو محليًا مدعومًا بمخزن مؤقت في المسح المشترك - - موفّرو `imageToVideo` المعلَن عنهم لكن المتخطَّون حاليًا في المسح المشترك: - - `vydra` لأن `veo3` المضمّن نصي فقط و`kling` المضمّن يتطلب عنوان URL لصورة بعيدة - - التغطية الخاصة بموفّر Vydra: + - اضبط `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` لتشغيل أوضاع التحويل المعلنة أيضًا عند توفرها: + - `imageToVideo` عندما يعلن المزوّد `capabilities.imageToVideo.enabled` ويقبل المزوّد/النموذج المحدد إدخال الصور المحلية المعتمد على buffer في المسح المشترك + - `videoToVideo` عندما يعلن المزوّد `capabilities.videoToVideo.enabled` ويقبل المزوّد/النموذج المحدد إدخال الفيديو المحلي المعتمد على buffer في المسح المشترك + - مزوّدو `imageToVideo` المعلن عنهم حاليًا لكن المتخطَّون في المسح المشترك: + - `vydra` لأن `veo3` المضمّن نصي فقط و`kling` المضمّن يتطلب URL صورة بعيدًا + - تغطية Vydra الخاصة بالمزوّد: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - يشغّل هذا الملف `veo3` لتحويل النص إلى فيديو بالإضافة إلى مسار `kling` يستخدم تجهيز عنوان URL لصورة بعيدة افتراضيًا + - يشغّل هذا الملف `veo3` من text-to-video بالإضافة إلى مسار `kling` يستخدم افتراضيًا تركيبة URL صورة بعيدة - التغطية الحية الحالية لـ `videoToVideo`: - `runway` فقط عندما يكون النموذج المحدد هو `runway/gen4_aleph` - - موفّرو `videoToVideo` المعلَن عنهم لكن المتخطَّون حاليًا في المسح المشترك: - - `alibaba` و`qwen` و`xai` لأن هذه المسارات تتطلب حاليًا عناوين URL مرجعية بعيدة من نوع `http(s)` / MP4 - - `google` لأن مسار Gemini/Veo المشترك الحالي يستخدم إدخالًا محليًا مدعومًا بمخزن مؤقت وهذا المسار غير مقبول في المسح المشترك - - `openai` لأن المسار المشترك الحالي يفتقر إلى ضمانات الوصول الخاصة بالمؤسسة لتلوين/إعادة مزج الفيديو + - مزوّدو `videoToVideo` المعلن عنهم حاليًا لكن المتخطَّون في المسح المشترك: + - `alibaba` و`qwen` و`xai` لأن هذه المسارات تتطلب حاليًا URLs مرجعية بعيدة من نوع `http(s)` / MP4 + - `google` لأن مسار Gemini/Veo المشترك الحالي يستخدم إدخالًا محليًا معتمدًا على buffer وهذا المسار غير مقبول في المسح المشترك + - `openai` لأن المسار المشترك الحالي يفتقر إلى ضمانات وصول خاصة بالمؤسسة لـ video inpaint/remix - التضييق الاختياري: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` لتضمين كل موفّر خدمة في المسح الافتراضي، بما في ذلك FAL - - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` لتقليل حد العملية لكل موفّر من أجل تشغيل دخاني أكثر شدة + - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` لتضمين كل مزوّد في المسح الافتراضي، بما في ذلك FAL + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` لتقليل الحد الأقصى لعملية كل مزوّد من أجل تشغيل smoke صارم - سلوك المصادقة الاختياري: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` لفرض مصادقة مخزن الملفات الشخصية وتجاهل تجاوزات البيئة فقط + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` لفرض مصادقة مخزن profile وتجاهل overrides المعتمدة على env فقط -## حزام media live +## Media live harness - الأمر: `pnpm test:live:media` - الغرض: - - يشغّل أجنحة image وmusic وvideo الحية المشتركة عبر نقطة دخول أصلية واحدة للمستودع - - يحمّل تلقائيًا متغيرات بيئة الموفّر الناقصة من `~/.profile` - - يضيّق تلقائيًا كل جناح إلى موفّري الخدمة الذين يملكون حاليًا مصادقة صالحة افتراضيًا - - يعيد استخدام `scripts/test-live.mjs`، حتى يبقى سلوك Heartbeat والوضع الهادئ متسقًا + - يشغّل أجنحة live المشتركة الخاصة بالصور والموسيقى والفيديو عبر نقطة دخول أصلية واحدة للمستودع + - يحمّل تلقائيًا متغيرات بيئة المزوّد الناقصة من `~/.profile` + - يضيّق تلقائيًا كل جناح إلى المزوّدين الذين لديهم حاليًا مصادقة صالحة افتراضيًا + - يعيد استخدام `scripts/test-live.mjs`، بحيث يبقى سلوك Heartbeat والوضع الهادئ متسقًا - أمثلة: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## مشغّلات Docker (اختياري: تحقق "يعمل على Linux") +## مشغّلات Docker (فحوصات اختيارية من نوع "يعمل على Linux") تنقسم مشغّلات Docker هذه إلى فئتين: -- مشغّلات النماذج الحية: `test:docker:live-models` و`test:docker:live-gateway` يشغّلان فقط ملف الاختبار الحي المطابق ذي مفاتيح الملف الشخصي داخل صورة Docker الخاصة بالمستودع (`src/agents/models.profiles.live.test.ts` و`src/gateway/gateway-models.profiles.live.test.ts`)، مع تركيب دليل الإعداد المحلي ومساحة العمل الخاصة بك (واستيراد `~/.profile` إذا كان مركّبًا). ونقاط الدخول المحلية المطابقة هي `test:live:models-profiles` و`test:live:gateway-profiles`. -- تستخدم مشغّلات Docker الحية افتراضيًا حدًا أصغر للاختبار الدخاني حتى يبقى المسح الكامل في Docker عمليًا: +- مشغّلات live-model: ‏`test:docker:live-models` و`test:docker:live-gateway` يشغّلان فقط ملف live المطابق الخاص بمفاتيح profile داخل صورة Docker الخاصة بالمستودع (`src/agents/models.profiles.live.test.ts` و`src/gateway/gateway-models.profiles.live.test.ts`)، مع وصل دليل config ومساحة العمل المحليين لديك (ومع تحميل `~/.profile` إن كان موصولًا). نقاط الدخول المحلية المطابقة هي `test:live:models-profiles` و`test:live:gateway-profiles`. +- تستخدم مشغّلات Docker الحية افتراضيًا حد smoke أصغر حتى يبقى المسح الكامل عبر Docker عمليًا: يستخدم `test:docker:live-models` افتراضيًا `OPENCLAW_LIVE_MAX_MODELS=12`، ويستخدم `test:docker:live-gateway` افتراضيًا `OPENCLAW_LIVE_GATEWAY_SMOKE=1`، و`OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`، و`OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000`، و `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. تجاوز متغيرات البيئة هذه عندما - تريد صراحة المسح الأكبر والأشمل. -- يبني `test:docker:all` صورة Docker الحية مرة واحدة عبر `test:docker:live-build`، ثم يعيد استخدامها لمساري Docker الحيين. -- مشغّلات الاختبار الدخاني للحاويات: `test:docker:openwebui` و`test:docker:onboard` و`test:docker:gateway-network` و`test:docker:mcp-channels` و`test:docker:plugins` تُقلع حاوية أو أكثر حقيقية وتتحقق من مسارات تكامل أعلى مستوى. + تريد صراحةً المسح الشامل الأكبر. +- يقوم `test:docker:all` ببناء صورة Docker الحية مرة واحدة عبر `test:docker:live-build`، ثم يعيد استخدامها للمسارين الحيين عبر Docker. +- مشغّلات smoke للحاويات: ‏`test:docker:openwebui` و`test:docker:onboard` و`test:docker:gateway-network` و`test:docker:mcp-channels` و`test:docker:plugins` تقلع حاوية واحدة أو أكثر حقيقية وتتحقق من مسارات تكامل أعلى مستوى. -تقوم مشغّلات Docker الخاصة بالنماذج الحية أيضًا بتركيب أدلة مصادقة CLI المنزلية المطلوبة فقط (أو كلها عندما لا يكون التشغيل مضيقًا)، ثم تنسخها إلى منزل الحاوية قبل التشغيل حتى تتمكن مصادقة OAuth الخاصة بـ CLI الخارجي من تحديث الرموز دون تعديل مخزن المصادقة على المضيف: +تقوم مشغّلات Docker الخاصة بـ live-model أيضًا بوصل منازل مصادقة CLI المطلوبة فقط (أو جميع المنازل المدعومة عندما لا يكون التشغيل مضيقًا)، ثم تنسخها إلى منزل الحاوية قبل التشغيل حتى تتمكن OAuth الخاصة بـ CLI الخارجي من تحديث الرموز دون تعديل مخزن المصادقة على المضيف: -- النماذج المباشرة: `pnpm test:docker:live-models` (السكربت: `scripts/test-live-models-docker.sh`) -- اختبار ACP bind الدخاني: `pnpm test:docker:live-acp-bind` (السكربت: `scripts/test-live-acp-bind-docker.sh`) -- اختبار CLI backend الدخاني: `pnpm test:docker:live-cli-backend` (السكربت: `scripts/test-live-cli-backend-docker.sh`) -- اختبار Codex app-server harness الدخاني: `pnpm test:docker:live-codex-harness` (السكربت: `scripts/test-live-codex-harness-docker.sh`) -- Gateway + dev agent: `pnpm test:docker:live-gateway` (السكربت: `scripts/test-live-gateway-models-docker.sh`) -- اختبار Open WebUI الحي الدخاني: `pnpm test:docker:openwebui` (السكربت: `scripts/e2e/openwebui-docker.sh`) -- معالج Onboarding (TTY، مع البنية الكاملة): `pnpm test:docker:onboard` (السكربت: `scripts/e2e/onboard-docker.sh`) -- شبكات Gateway (حاويتان، مصادقة WS + الصحة): `pnpm test:docker:gateway-network` (السكربت: `scripts/e2e/gateway-network-docker.sh`) -- جسر قناة MCP (Gateway مُجهّز مسبقًا + جسر stdio + اختبار دخاني خام لإطارات إشعارات Claude): `pnpm test:docker:mcp-channels` (السكربت: `scripts/e2e/mcp-channels-docker.sh`) -- Plugins (اختبار التثبيت الدخاني + الاسم البديل `/plugin` + دلالات إعادة تشغيل حزمة Claude): `pnpm test:docker:plugins` (السكربت: `scripts/e2e/plugins-docker.sh`) +- النماذج المباشرة: `pnpm test:docker:live-models` (السكريبت: `scripts/test-live-models-docker.sh`) +- ACP bind smoke: `pnpm test:docker:live-acp-bind` (السكريبت: `scripts/test-live-acp-bind-docker.sh`) +- CLI backend smoke: `pnpm test:docker:live-cli-backend` (السكريبت: `scripts/test-live-cli-backend-docker.sh`) +- Codex app-server harness smoke: `pnpm test:docker:live-codex-harness` (السكريبت: `scripts/test-live-codex-harness-docker.sh`) +- Gateway + وكيل dev: `pnpm test:docker:live-gateway` (السكريبت: `scripts/test-live-gateway-models-docker.sh`) +- Open WebUI live smoke: `pnpm test:docker:openwebui` (السكريبت: `scripts/e2e/openwebui-docker.sh`) +- معالج onboarding (TTY، بناء كامل): `pnpm test:docker:onboard` (السكريبت: `scripts/e2e/onboard-docker.sh`) +- شبكات Gateway (حاويتان، مصادقة WS + health): `pnpm test:docker:gateway-network` (السكريبت: `scripts/e2e/gateway-network-docker.sh`) +- جسر قناة MCP (Gateway مبدوء مسبقًا + جسر stdio + smoke خام لإطار إشعار Claude): `pnpm test:docker:mcp-channels` (السكريبت: `scripts/e2e/mcp-channels-docker.sh`) +- Plugins (install smoke + الاسم البديل `/plugin` + دلالات إعادة تشغيل Claude-bundle): `pnpm test:docker:plugins` (السكريبت: `scripts/e2e/plugins-docker.sh`) -تقوم مشغّلات Docker الخاصة بالنماذج الحية أيضًا بتركيب نسخة العمل الحالية بوضع القراءة فقط -وتجهيزها في دليل عمل مؤقت داخل الحاوية. هذا يُبقي صورة وقت التشغيل -نحيفة مع الاستمرار في تشغيل Vitest مقابل المصدر/الإعداد المحليين لديك تمامًا. -تتخطى خطوة التجهيز الذاكرات المؤقتة المحلية الكبيرة فقط وبنى التطبيق الناتجة مثل -`.pnpm-store` و`.worktrees` و`__openclaw_vitest__` ودلائل -`.build` أو Gradle المحلية للتطبيق، حتى لا تقضي تشغيلات Docker الحية دقائق في نسخ -قطع أثرية خاصة بالجهاز. -كما تضبط `OPENCLAW_SKIP_CHANNELS=1` حتى لا تبدأ مجسات Gateway الحية +تقوم مشغّلات Docker الخاصة بـ live-model أيضًا بوصل نسخة checkout الحالية للقراءة فقط +وتجهيزها داخل workdir مؤقت داخل الحاوية. هذا يُبقي صورة وقت التشغيل +نحيفة، مع الاستمرار في تشغيل Vitest على المصدر/الإعداد المحلي المطابق تمامًا. +تتخطى خطوة التجهيز الذاكرات المؤقتة المحلية الكبيرة فقط ومخرجات بناء التطبيق مثل +`.pnpm-store` و`.worktrees` و`__openclaw_vitest__` وأدلة `.build` المحلية للتطبيق أو +مخرجات Gradle، حتى لا تقضي تشغيلات Docker الحية دقائق في نسخ +artifacts خاصة بالجهاز. +كما أنها تضبط `OPENCLAW_SKIP_CHANNELS=1` حتى لا تبدأ فحوصات Gateway الحية عمّال قنوات حقيقية مثل Telegram/Discord وغيرها داخل الحاوية. لا يزال `test:docker:live-models` يشغّل `pnpm test:live`، لذلك مرّر `OPENCLAW_LIVE_GATEWAY_*` أيضًا عندما تحتاج إلى تضييق أو استبعاد تغطية Gateway الحية من مسار Docker هذا. -`test:docker:openwebui` هو اختبار توافق أعلى مستوى: إذ يبدأ -حاوية OpenClaw Gateway مع تفعيل نقاط نهاية HTTP المتوافقة مع OpenAI، -ثم يبدأ حاوية Open WebUI مثبتة مقابل ذلك Gateway، ويسجّل الدخول عبر -Open WebUI، ويتحقق من أن `/api/models` يعرّض `openclaw/default`، ثم يرسل -طلب دردشة حقيقيًا عبر وكيل `/api/chat/completions` في Open WebUI. +يُعد `test:docker:openwebui` فحص توافق أعلى مستوى: فهو يبدأ +حاوية OpenClaw gateway مع تفعيل نقاط نهاية HTTP المتوافقة مع OpenAI، +ويبدأ حاوية Open WebUI مثبتة مقابل ذلك gateway، ويسجل الدخول من خلال +Open WebUI، ويتحقق من أن `/api/models` يعرض `openclaw/default`، ثم يرسل +طلب دردشة حقيقيًا عبر proxy ‏`/api/chat/completions` في Open WebUI. قد يكون التشغيل الأول أبطأ بشكل ملحوظ لأن Docker قد يحتاج إلى سحب صورة Open WebUI وقد يحتاج Open WebUI إلى إكمال إعداد البدء البارد الخاص به. -يتطلب هذا المسار مفتاح نموذج حي صالحًا، ويُعد `OPENCLAW_PROFILE_FILE` -(الافتراضي: `~/.profile`) الطريقة الأساسية لتوفيره في التشغيلات داخل Docker. +يتوقع هذا المسار مفتاح نموذج حي صالحًا، ويُعد `OPENCLAW_PROFILE_FILE` +(الافتراضي `~/.profile`) الطريقة الأساسية لتوفيره في تشغيلات Docker. تطبع التشغيلات الناجحة حمولة JSON صغيرة مثل `{ "ok": true, "model": "openclaw/default", ... }`. -يكون `test:docker:mcp-channels` حتميًا عمدًا ولا يحتاج إلى +يعد `test:docker:mcp-channels` حتميًا عمدًا ولا يحتاج إلى حساب Telegram أو Discord أو iMessage حقيقي. فهو يقلع حاوية Gateway -مُجهّزة مسبقًا، ويبدأ حاوية ثانية تشغّل `openclaw mcp serve`، ثم -يتحقق من اكتشاف المحادثات الموجّهة، وقراءة النصوص، وبيانات تعريف المرفقات، +مبدوءة مسبقًا، ثم يبدأ حاوية ثانية تشغّل `openclaw mcp serve`، ثم +يتحقق من اكتشاف المحادثات الموجّهة، وقراءة transcript، وmetadata الخاصة بالمرفقات، وسلوك طابور الأحداث الحية، وتوجيه الإرسال الصادر، وإشعارات القنوات + -الأذونات بأسلوب Claude عبر جسر stdio MCP الحقيقي. ويفحص تحقق الإشعارات -إطارات stdio MCP الخام مباشرة حتى يثبت الاختبار الدخاني ما الذي يصدره -الجسر فعليًا، وليس فقط ما الذي يعرضه SDK لعميل معين بالمصادفة. +الأذونات بأسلوب Claude عبر جسر MCP الحقيقي المعتمد على stdio. وتفحص عملية +التحقق من الإشعارات إطارات MCP الخام على stdio مباشرةً حتى يتحقق smoke مما +يبثه الجسر فعلًا، لا فقط مما تعرضه مجموعة SDK عميل معينة بالمصادفة. -اختبار ACP اليدوي بلغة طبيعية للسلاسل (ليس في CI): +فحص Smoke يدوي لخيط ACP باللغة الطبيعية (ليس في CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- احتفظ بهذا السكربت لتدفقات العمل الخاصة بالاختبارات التراجعية/تصحيح الأخطاء. قد نحتاج إليه مرة أخرى للتحقق من توجيه سلاسل ACP، لذلك لا تحذفه. +- احتفظ بهذا السكريبت من أجل سير عمل اختبار الانحدار/تصحيح الأخطاء. قد يلزم مجددًا للتحقق من توجيه خيوط ACP، لذلك لا تحذفه. -متغيرات بيئة مفيدة: +متغيرات البيئة المفيدة: -- `OPENCLAW_CONFIG_DIR=...` (الافتراضي: `~/.openclaw`) يُركّب إلى `/home/node/.openclaw` -- `OPENCLAW_WORKSPACE_DIR=...` (الافتراضي: `~/.openclaw/workspace`) يُركّب إلى `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (الافتراضي: `~/.profile`) يُركّب إلى `/home/node/.profile` ويُستورد قبل تشغيل الاختبارات -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` للتحقق من متغيرات البيئة فقط المستوردة من `OPENCLAW_PROFILE_FILE`، باستخدام دلائل إعداد/مساحة عمل مؤقتة ومن دون أي عمليات تركيب لمصادقة CLI الخارجية -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (الافتراضي: `~/.cache/openclaw/docker-cli-tools`) يُركّب إلى `/home/node/.npm-global` لتثبيتات CLI المخزنة مؤقتًا داخل Docker -- تُركّب أدلة/ملفات مصادقة CLI الخارجية تحت `$HOME` للقراءة فقط ضمن `/host-auth...`، ثم تُنسخ إلى `/home/node/...` قبل بدء الاختبارات +- `OPENCLAW_CONFIG_DIR=...` (الافتراضي: `~/.openclaw`) يُوصَل إلى `/home/node/.openclaw` +- `OPENCLAW_WORKSPACE_DIR=...` (الافتراضي: `~/.openclaw/workspace`) يُوصَل إلى `/home/node/.openclaw/workspace` +- `OPENCLAW_PROFILE_FILE=...` (الافتراضي: `~/.profile`) يُوصَل إلى `/home/node/.profile` ويُحمّل قبل تشغيل الاختبارات +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` للتحقق من متغيرات البيئة المحمّلة فقط من `OPENCLAW_PROFILE_FILE`، باستخدام أدلة config/workspace مؤقتة ومن دون أي وصل لمصادقة CLI خارجية +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (الافتراضي: `~/.cache/openclaw/docker-cli-tools`) يُوصَل إلى `/home/node/.npm-global` لتثبيتات CLI المخزنة مؤقتًا داخل Docker +- تُوصَل أدلة/ملفات مصادقة CLI الخارجية تحت `$HOME` للقراءة فقط ضمن `/host-auth...`، ثم تُنسخ إلى `/home/node/...` قبل بدء الاختبارات - الأدلة الافتراضية: `.minimax` - الملفات الافتراضية: `~/.codex/auth.json` و`~/.codex/config.toml` و`.claude.json` و`~/.claude/.credentials.json` و`~/.claude/settings.json` و`~/.claude/settings.local.json` - - تشغّل الموفّرات المضيقة فقط الأدلة/الملفات المطلوبة المستنتجة من `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - تجاوز يدويًا باستخدام `OPENCLAW_DOCKER_AUTH_DIRS=all` أو `OPENCLAW_DOCKER_AUTH_DIRS=none` أو قائمة مفصولة بفواصل مثل `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` + - التشغيلات المضيقة حسب المزوّد توصل فقط الأدلة/الملفات اللازمة المستنتجة من `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - يمكنك التجاوز يدويًا باستخدام `OPENCLAW_DOCKER_AUTH_DIRS=all` أو `OPENCLAW_DOCKER_AUTH_DIRS=none` أو قائمة مفصولة بفواصل مثل `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` لتضييق التشغيل -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` لتصفية موفّري الخدمة داخل الحاوية -- `OPENCLAW_SKIP_DOCKER_BUILD=1` لإعادة استخدام صورة `openclaw:local-live` موجودة مسبقًا لعمليات إعادة التشغيل التي لا تحتاج إلى إعادة بناء -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` لضمان أن تأتي بيانات الاعتماد من مخزن الملفات الشخصية (وليس من البيئة) -- `OPENCLAW_OPENWEBUI_MODEL=...` لاختيار النموذج الذي يعرّضه Gateway لاختبار Open WebUI الدخاني -- `OPENCLAW_OPENWEBUI_PROMPT=...` لتجاوز موجّه التحقق من nonce المستخدم في اختبار Open WebUI الدخاني +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` لتصفية المزوّدين داخل الحاوية +- `OPENCLAW_SKIP_DOCKER_BUILD=1` لإعادة استخدام صورة `openclaw:local-live` موجودة لتشغيلات الإعادة التي لا تحتاج إلى إعادة بناء +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` لضمان أن بيانات الاعتماد تأتي من مخزن profile (وليس من env) +- `OPENCLAW_OPENWEBUI_MODEL=...` لاختيار النموذج الذي يعرِضه gateway لفحص Open WebUI smoke +- `OPENCLAW_OPENWEBUI_PROMPT=...` لتجاوز prompt التحقق من nonce المستخدم بواسطة Open WebUI smoke - `OPENWEBUI_IMAGE=...` لتجاوز وسم صورة Open WebUI المثبت -## سلامة المستندات +## التحقق من سلامة المستندات شغّل فحوصات المستندات بعد تعديلها: `pnpm check:docs`. -وشغّل التحقق الكامل من روابط Mintlify والروابط الداخلية عندما تحتاج أيضًا إلى فحوصات عناوين الصفحات: `pnpm docs:check-links:anchors`. +وشغّل التحقق الكامل لروابط Mintlify عندما تحتاج أيضًا إلى فحص العناوين داخل الصفحة: `pnpm docs:check-links:anchors`. -## اختبار تراجعي دون اتصال (آمن لـ CI) +## اختبار الانحدار دون اتصال (آمن لـ CI) -هذه اختبارات تراجعية لخط أنابيب "حقيقي" من دون موفّري خدمة حقيقيين: +هذه اختبارات انحدار لـ «مسار حقيقي» دون مزوّدين حقيقيين: -- استدعاء أدوات Gateway (OpenAI وهمي، مع Gateway + حلقة agent حقيقيين): `src/gateway/gateway.test.ts` (الحالة: `"runs a mock OpenAI tool call end-to-end via gateway agent loop"`) -- معالج Gateway (‏WS `wizard.start`/`wizard.next`، يكتب الإعداد + يفرض المصادقة): `src/gateway/gateway.test.ts` (الحالة: `"runs wizard over ws and writes auth token config"`) +- استدعاء أدوات Gateway (‏OpenAI وهمي، Gateway + حلقة وكيل حقيقية): `src/gateway/gateway.test.ts` (الحالة: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- معالج Gateway (‏WS `wizard.start`/`wizard.next`، يكتب config + auth مع فرضهما): `src/gateway/gateway.test.ts` (الحالة: "runs wizard over ws and writes auth token config") -## تقييمات موثوقية agent (Skills) +## تقييمات موثوقية الوكيل (Skills) -لدينا بالفعل بعض الاختبارات الآمنة لـ CI التي تتصرف مثل "تقييمات موثوقية agent": +لدينا بالفعل بعض الاختبارات الآمنة لـ CI التي تتصرف مثل «تقييمات موثوقية الوكيل»: -- استدعاء أدوات وهمي عبر Gateway + حلقة agent الحقيقيين (`src/gateway/gateway.test.ts`). -- تدفقات معالج كاملة من طرف إلى طرف تتحقق من ربط الجلسات وتأثيرات الإعداد (`src/gateway/gateway.test.ts`). +- استدعاء أدوات وهمية عبر Gateway الحقيقي + حلقة الوكيل (`src/gateway/gateway.test.ts`). +- تدفقات المعالج الكاملة من طرف إلى طرف التي تتحقق من توصيل الجلسة وتأثيرات config (`src/gateway/gateway.test.ts`). -ما الذي لا يزال مفقودًا لـ Skills (انظر [Skills](/ar/tools/skills)): +ما الذي لا يزال مفقودًا بالنسبة إلى Skills (راجع [Skills](/ar/tools/skills)): -- **اتخاذ القرار:** عندما تُدرج Skills في الموجّه، هل يختار agent المهارة الصحيحة (أو يتجنب غير المرتبطة)؟ -- **الامتثال:** هل يقرأ agent ملف `SKILL.md` قبل الاستخدام ويتبع الخطوات/الوسائط المطلوبة؟ -- **عقود تدفق العمل:** سيناريوهات متعددة الأدوار تتحقق من ترتيب الأدوات، واستمرار سجل الجلسة، وحدود sandbox. +- **اتخاذ القرار:** عندما تُدرج Skills في prompt، هل يختار الوكيل Skill الصحيحة (أو يتجنب غير ذات الصلة)؟ +- **الامتثال:** هل يقرأ الوكيل `SKILL.md` قبل الاستخدام ويتبع الخطوات/الوسائط المطلوبة؟ +- **عقود سير العمل:** سيناريوهات متعددة الأدوار تتحقق من ترتيب الأدوات، واستمرار سجل الجلسة، وحدود sandbox. -يجب أن تبقى التقييمات المستقبلية حتمية أولًا: +يجب أن تظل التقييمات المستقبلية حتمية أولًا: -- مشغّل سيناريوهات يستخدم موفّري خدمة وهميين للتحقق من استدعاءات الأدوات + ترتيبها وقراءات ملفات المهارات وربط الجلسات. -- جناح صغير من السيناريوهات المركزة على Skills (الاستخدام مقابل التجنب، والبوابات، وحقن الموجّه). -- تقييمات حية اختيارية (مفعّلة بالبيئة وعند الاختيار) فقط بعد وجود الجناح الآمن لـ CI. +- مشغّل سيناريوهات يستخدم مزوّدين وهميين للتحقق من استدعاءات الأدوات + ترتيبها، وقراءة ملفات Skill، وتوصيل الجلسات. +- جناح صغير من السيناريوهات المركزة على Skills (الاستخدام مقابل التجنب، والبوابات، وحقن prompt). +- تقييمات حية اختيارية (opt-in، ومقيدة عبر env) فقط بعد وضع الجناح الآمن لـ CI. -## اختبارات العقود (شكل Plugin والقناة) +## اختبارات العقد (شكل Plugin والقناة) -تتحقق اختبارات العقود من أن كل Plugin وقناة مسجلين يطابقان -عقد الواجهة الخاص بهما. فهي تكرّر المرور على كل Plugins المكتشفة وتشغّل مجموعة من -التحققات المتعلقة بالشكل والسلوك. يتخطى مسار unit الافتراضي `pnpm test` -عمدًا هذه الملفات المشتركة الخاصة بالوصلات والاختبارات الدخانية؛ شغّل أوامر العقود صراحة -عندما تلمس أسطح القنوات أو موفّري الخدمة المشتركة. +تتحقق اختبارات العقد من أن كل Plugin وقناة مسجلين يطابقان +عقد الواجهة الخاص بهما. فهي تكرر عبر جميع Plugins المكتشفة وتشغّل مجموعة من +التحققات الخاصة بالشكل والسلوك. يتخطى مسار unit الافتراضي `pnpm test` +عمدًا هذه الملفات المشتركة الخاصة بالواجهات وفحوص smoke؛ شغّل أوامر العقد صراحةً +عندما تلمس أسطح القنوات أو المزوّدين المشتركة. ### الأوامر -- كل العقود: `pnpm test:contracts` +- جميع العقود: `pnpm test:contracts` - عقود القنوات فقط: `pnpm test:contracts:channels` -- عقود موفّري الخدمة فقط: `pnpm test:contracts:plugins` +- عقود المزوّدات فقط: `pnpm test:contracts:plugins` ### عقود القنوات تقع في `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - الشكل الأساسي للـ Plugin (المعرّف، الاسم، القدرات) +- **plugin** - شكل Plugin الأساسي (id، الاسم، القدرات) - **setup** - عقد معالج الإعداد - **session-binding** - سلوك ربط الجلسة - **outbound-payload** - بنية حمولة الرسالة -- **inbound** - معالجة الرسائل الواردة +- **inbound** - التعامل مع الرسائل الواردة - **actions** - معالجات إجراءات القناة -- **threading** - معالجة معرّف السلسلة -- **directory** - API الدليل/القائمة +- **threading** - التعامل مع معرّف الخيط +- **directory** - واجهة API للدليل/القائمة - **group-policy** - فرض سياسة المجموعة -### عقود حالة موفّر الخدمة +### عقود حالة المزوّد تقع في `src/plugins/contracts/*.contract.test.ts`. -- **status** - مجسات حالة القناة +- **status** - فحوصات حالة القناة - **registry** - شكل سجل Plugin -### عقود موفّر الخدمة +### عقود المزوّد تقع في `src/plugins/contracts/*.contract.test.ts`: - **auth** - عقد تدفق المصادقة - **auth-choice** - اختيار/تحديد المصادقة -- **catalog** - API فهرس النماذج +- **catalog** - واجهة API لفهرس النماذج - **discovery** - اكتشاف Plugin - **loader** - تحميل Plugin -- **runtime** - وقت تشغيل موفّر الخدمة +- **runtime** - وقت تشغيل المزوّد - **shape** - شكل/واجهة Plugin - **wizard** - معالج الإعداد -### متى تُشغَّل +### متى يجب تشغيلها -- بعد تغيير صادرات أو مسارات `plugin-sdk` الفرعية -- بعد إضافة أو تعديل قناة أو Provider Plugin -- بعد إعادة هيكلة تسجيل Plugin أو اكتشافها +- بعد تغيير صادرات `plugin-sdk` أو المسارات الفرعية الخاصة بها +- بعد إضافة Plugin قناة أو مزوّد أو تعديل أحدهما +- بعد إعادة هيكلة تسجيل Plugin أو اكتشافه -تعمل اختبارات العقود في CI ولا تتطلب مفاتيح API حقيقية. +تعمل اختبارات العقد في CI ولا تتطلب مفاتيح API حقيقية. -## إضافة اختبارات تراجعية (إرشادات) +## إضافة اختبارات الانحدار (إرشادات) -عندما تصلح مشكلة موفّر/نموذج اكتُشفت في الاختبارات الحية: +عندما تصلح مشكلة في مزوّد/نموذج اكتُشفت في live: -- أضف اختبارًا تراجعيًا آمنًا لـ CI إن أمكن (موفّر وهمي/بديل، أو التقاط التحويل الدقيق لشكل الطلب) -- إذا كانت المشكلة حية فقط بطبيعتها (حدود المعدل، سياسات المصادقة)، فأبقِ الاختبار الحي ضيقًا واختياريًا عبر متغيرات البيئة +- أضف اختبار انحدار آمنًا لـ CI إن أمكن (مزوّد وهمي/بديل stub، أو التقط تحويل شكل الطلب الدقيق) +- إذا كانت المشكلة حية فقط بطبيعتها (حدود المعدل، سياسات المصادقة)، فأبقِ الاختبار الحي ضيقًا واختياريًا عبر متغيرات env - فضّل استهداف أصغر طبقة تلتقط الخطأ: - - خطأ في تحويل/إعادة تشغيل طلب الموفّر → اختبار النماذج المباشرة - - خطأ في مسار جلسة/سجل/أداة Gateway → اختبار Gateway حي دخاني أو اختبار Gateway وهمي وآمن لـ CI -- حاجز حماية اجتياز SecretRef: - - يقوم `src/secrets/exec-secret-ref-id-parity.test.ts` باشتقاق هدف نموذجي واحد لكل فئة SecretRef من بيانات تعريف السجل (`listSecretTargetRegistryEntries()`)، ثم يتحقق من رفض معرّفات exec الخاصة بمقاطع الاجتياز. + - خطأ في تحويل/إعادة تشغيل طلب المزوّد → اختبار النماذج المباشرة + - خطأ في مسار الجلسة/السجل/الأدوات في gateway → اختبار Gateway live smoke أو اختبار Gateway وهمي آمن لـ CI +- حاجز حماية لاجتياز SecretRef: + - يقوم `src/secrets/exec-secret-ref-id-parity.test.ts` باشتقاق هدف نموذجي واحد لكل فئة SecretRef من metadata السجل (`listSecretTargetRegistryEntries()`)، ثم يتحقق من رفض معرّفات exec الخاصة بمقاطع الاجتياز. - إذا أضفت عائلة أهداف SecretRef جديدة من نوع `includeInPlan` في `src/secrets/target-registry-data.ts`، فحدّث `classifyTargetClass` في ذلك الاختبار. يفشل الاختبار عمدًا عند وجود معرّفات أهداف غير مصنفة حتى لا يمكن تخطي الفئات الجديدة بصمت. diff --git a/docs/ar/platforms/macos.md b/docs/ar/platforms/macos.md index fe6208e7a..959b1e562 100644 --- a/docs/ar/platforms/macos.md +++ b/docs/ar/platforms/macos.md @@ -1,76 +1,76 @@ --- read_when: - تنفيذ ميزات تطبيق macOS - - تغيير دورة حياة البوابة أو جسر العقدة على macOS -summary: التطبيق المصاحب لـ OpenClaw على macOS (شريط القوائم + وسيط البوابة) + - تغيير دورة حياة Gateway أو ربط Node على macOS +summary: تطبيق OpenClaw المرافق لنظام macOS (شريط القوائم + وسيط Gateway) title: تطبيق macOS x-i18n: - generated_at: "2026-04-05T12:50:52Z" + generated_at: "2026-04-18T07:14:53Z" model: gpt-5.4 provider: openai - source_hash: bfac937e352ede495f60af47edf3b8e5caa5b692ba0ea01d9fb0de9a44bbc135 + source_hash: d637df2f73ced110223c48ea3c934045d782e150a46495f434cf924a6a00baf0 source_path: platforms/macos.md workflow: 15 --- -# التطبيق المصاحب لـ OpenClaw على macOS ‏(شريط القوائم + وسيط البوابة) +# تطبيق OpenClaw المرافق لنظام macOS (شريط القوائم + وسيط Gateway) -تطبيق macOS هو **الرفيق الموجود في شريط القوائم** لـ OpenClaw. وهو يملك الأذونات، -ويدير/يرتبط بالبوابة محليًا (launchd أو يدويًا)، ويكشف إمكانات macOS -للوكيل باعتبارها عقدة. +تطبيق macOS هو **التطبيق المرافق في شريط القوائم** لـ OpenClaw. وهو يتولى الأذونات، +ويدير/يرتبط بـ Gateway محليًا (launchd أو يدويًا)، ويعرض إمكانات macOS +للوكيل كعقدة. ## ما الذي يفعله -- يعرض إشعارات أصلية وحالة في شريط القوائم. -- يملك مطالبات TCC ‏(الإشعارات، وإمكانية الوصول، وتسجيل الشاشة، والميكروفون، - والتعرّف على الكلام، وAutomation/AppleScript). -- يشغّل البوابة أو يتصل بها (محليًا أو عن بُعد). -- يكشف الأدوات الخاصة بـ macOS فقط (Canvas، والكاميرا، وتسجيل الشاشة، و`system.run`). -- يبدأ خدمة مضيف العقدة المحلي في الوضع **Remote** ‏(launchd)، ويوقفها في الوضع **Local**. -- يمكنه استضافة **PeekabooBridge** اختياريًا لأتمتة واجهة المستخدم. -- يثبت CLI العالمي (`openclaw`) عند الطلب عبر npm أو pnpm أو bun (يفضّل التطبيق npm، ثم pnpm، ثم bun؛ ويظل Node هو وقت تشغيل البوابة الموصى به). +- يعرض الإشعارات الأصلية والحالة في شريط القوائم. +- يتولى مطالبات TCC ‏(الإشعارات، تسهيلات الاستخدام، تسجيل الشاشة، الميكروفون، + التعرّف على الكلام، الأتمتة/AppleScript). +- يشغّل Gateway أو يتصل به (محليًا أو عن بُعد). +- يعرّض أدوات macOS فقط ‏(Canvas، الكاميرا، تسجيل الشاشة، `system.run`). +- يبدأ خدمة استضافة العقدة المحلية في وضع **remote** ‏(launchd)، ويوقفها في وضع **local**. +- يمكنه اختياريًا استضافة **PeekabooBridge** لأتمتة واجهة المستخدم. +- يثبّت CLI العام (`openclaw`) عند الطلب عبر npm أو pnpm أو bun (يفضّل التطبيق npm، ثم pnpm، ثم bun؛ ويظل Node بيئة تشغيل Gateway الموصى بها). -## الوضع المحلي مقابل الوضع البعيد +## وضع local مقابل remote -- **Local** ‏(الافتراضي): يرتبط التطبيق ببوابة محلية قيد التشغيل إذا كانت موجودة؛ +- **Local** ‏(الافتراضي): يرتبط التطبيق بـ Gateway محلي قيد التشغيل إذا كان موجودًا؛ وإلا فإنه يفعّل خدمة launchd عبر `openclaw gateway install`. -- **Remote**: يتصل التطبيق ببوابة عبر SSH/Tailscale ولا يبدأ - عملية محلية أبدًا. - ويبدأ التطبيق **خدمة مضيف العقدة** المحلية حتى تتمكن البوابة البعيدة من الوصول إلى هذا الـ Mac. - ولا يقوم التطبيق بتشغيل البوابة كعملية فرعية. - يفضّل اكتشاف البوابة الآن أسماء Tailscale MagicDNS على عناوين tailnet IP الخام، - لذلك يتعافى تطبيق Mac بشكل أكثر موثوقية عندما تتغير عناوين tailnet IP. +- **Remote**: يتصل التطبيق بـ Gateway عبر SSH/Tailscale ولا يبدأ أبدًا + عملية محلية. + يبدأ التطبيق **خدمة استضافة العقدة** المحلية حتى يتمكن Gateway البعيد من الوصول إلى هذا الـ Mac. + لا يشغّل التطبيق Gateway كعملية فرعية. + يفضّل اكتشاف Gateway الآن أسماء Tailscale MagicDNS بدلًا من عناوين tailnet IP الخام، + لذا يستعيد تطبيق Mac عمله بشكل أكثر موثوقية عند تغيّر عناوين tailnet IP. ## التحكم في Launchd -يدير التطبيق LaunchAgent لكل مستخدم بالتصنيف `ai.openclaw.gateway` -(أو `ai.openclaw.` عند استخدام `--profile`/`OPENCLAW_PROFILE`؛ ولا يزال الاسم القديم `com.openclaw.*` يُزال من التحميل). +يدير التطبيق LaunchAgent لكل مستخدم يحمل التسمية `ai.openclaw.gateway` +(أو `ai.openclaw.` عند استخدام `--profile`/`OPENCLAW_PROFILE`؛ ولا يزال `com.openclaw.*` القديم يُفرَّغ). ```bash launchctl kickstart -k gui/$UID/ai.openclaw.gateway launchctl bootout gui/$UID/ai.openclaw.gateway ``` -استبدل التصنيف بـ `ai.openclaw.` عند تشغيل ملف تعريف مسمى. +استبدل التسمية بـ `ai.openclaw.` عند تشغيل ملف تعريف مُسمّى. -إذا لم يتم تثبيت LaunchAgent، فقم بتفعيله من التطبيق أو شغّل +إذا لم يكن LaunchAgent مثبتًا، فقم بتمكينه من التطبيق أو شغّل `openclaw gateway install`. -## إمكانات العقدة (mac) +## إمكانات Node ‏(mac) -يعرض تطبيق macOS نفسه كعقدة. الأوامر الشائعة: +يقدّم تطبيق macOS نفسه كعقدة. الأوامر الشائعة: -- Canvas: ‏`canvas.present`, `canvas.navigate`, `canvas.eval`, `canvas.snapshot`, `canvas.a2ui.*` -- الكاميرا: ‏`camera.snap`, `camera.clip` -- الشاشة: ‏`screen.record` -- النظام: ‏`system.run`, `system.notify` +- Canvas: `canvas.present`, `canvas.navigate`, `canvas.eval`, `canvas.snapshot`, `canvas.a2ui.*` +- الكاميرا: `camera.snap`, `camera.clip` +- الشاشة: `screen.snapshot`, `screen.record` +- النظام: `system.run`, `system.notify` -تبلّغ العقدة عن خريطة `permissions` حتى تتمكن الوكلاء من تحديد المسموح. +تبلّغ العقدة عن خريطة `permissions` حتى تتمكن الوكلاء من تحديد المسموح به. -خدمة العقدة + IPC في التطبيق: +خدمة Node + ‏IPC للتطبيق: -- عندما تكون خدمة مضيف العقدة headless قيد التشغيل (الوضع البعيد)، فإنها تتصل بـ Gateway WS كعقدة. -- يتم تنفيذ `system.run` داخل تطبيق macOS ‏(سياق UI/TCC) عبر مقبس Unix محلي؛ وتبقى المطالبات + المخرجات داخل التطبيق. +- عند تشغيل خدمة استضافة العقدة بدون واجهة (وضع remote)، فإنها تتصل بـ Gateway WS كعقدة. +- يُنفَّذ `system.run` في تطبيق macOS ‏(سياق UI/TCC) عبر مقبس Unix محلي؛ وتبقى المطالبات والمخرجات داخل التطبيق. المخطط (SCI): @@ -81,10 +81,10 @@ Gateway -> Node Service (WS) Mac App (UI + TCC + system.run) ``` -## موافقات Exec ‏(system.run) +## موافقات التنفيذ (`system.run`) -يتم التحكم في `system.run` بواسطة **Exec approvals** في تطبيق macOS ‏(Settings → Exec approvals). -وتُخزَّن إعدادات Security + ask + allowlist محليًا على الـ Mac في: +يخضع `system.run` إلى **Exec approvals** في تطبيق macOS ‏(الإعدادات ← Exec approvals). +ويتم تخزين الأمان + السؤال + قائمة السماح محليًا على جهاز Mac في: ``` ~/.openclaw/exec-approvals.json @@ -111,12 +111,12 @@ Gateway -> Node Service (WS) ملاحظات: -- إدخالات `allowlist` هي أنماط glob لمسارات الملفات التنفيذية المحلولة. -- يُعامل نص أمر shell الخام الذي يحتوي على صيغة تحكم أو توسيع خاصة بـ shell (`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) على أنه فشل في allowlist ويتطلب موافقة صريحة (أو إدراج الملف التنفيذي الخاص بالـ shell في allowlist). -- يؤدي اختيار “Always Allow” في المطالبة إلى إضافة ذلك الأمر إلى allowlist. -- تتم تصفية تجاوزات البيئة في `system.run` (بحذف `PATH`, `DYLD_*`, `LD_*`, `NODE_OPTIONS`, `PYTHON*`, `PERL*`, `RUBYOPT`, `SHELLOPTS`, `PS4`) ثم دمجها مع بيئة التطبيق. -- بالنسبة إلى مغلفات shell ‏(`bash|sh|zsh ... -c/-lc`)، يتم تقليص تجاوزات البيئة الخاصة بالطلب إلى allowlist صغيرة وصريحة (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`). -- بالنسبة إلى قرارات allow-always في وضع allowlist، تقوم مغلفات الإرسال المعروفة (`env`, `nice`, `nohup`, `stdbuf`, `timeout`) بحفظ مسارات الملفات التنفيذية الداخلية بدلًا من مسارات المغلفات. وإذا لم يكن فك الالتفاف آمنًا، فلن يتم حفظ أي إدخال allowlist تلقائيًا. +- إدخالات `allowlist` هي أنماط glob لمسارات الملفات الثنائية المحلولة. +- يُعامل نص أمر shell الخام الذي يحتوي على صيغة تحكم أو توسيع shell (`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) على أنه عدم تطابق مع قائمة السماح ويتطلب موافقة صريحة (أو إضافة الملف الثنائي الخاص بالـ shell إلى قائمة السماح). +- يؤدي اختيار “السماح دائمًا” في المطالبة إلى إضافة ذلك الأمر إلى قائمة السماح. +- تُرشَّح تجاوزات البيئة الخاصة بـ `system.run` ‏(مع إسقاط `PATH`, `DYLD_*`, `LD_*`, `NODE_OPTIONS`, `PYTHON*`, `PERL*`, `RUBYOPT`, `SHELLOPTS`, `PS4`) ثم تُدمج مع بيئة التطبيق. +- بالنسبة إلى أغلفة shell ‏(`bash|sh|zsh ... -c/-lc`)، تُختزل تجاوزات البيئة على مستوى الطلب إلى قائمة سماح صريحة صغيرة (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`). +- بالنسبة إلى قرارات السماح الدائم في وضع قائمة السماح، فإن مغلفات التوجيه المعروفة (`env`, `nice`, `nohup`, `stdbuf`, `timeout`) تحفظ مسارات الملفات التنفيذية الداخلية بدلًا من مسارات المغلفات. وإذا لم يكن فكّ التغليف آمنًا، فلن يتم حفظ أي إدخال في قائمة السماح تلقائيًا. ## الروابط العميقة @@ -124,99 +124,99 @@ Gateway -> Node Service (WS) ### `openclaw://agent` -يشغّل طلب Gateway ‏`agent`. +يحفّز طلب `agent` إلى Gateway. __OC_I18N_900004__ معلمات الاستعلام: - `message` ‏(مطلوب) - `sessionKey` ‏(اختياري) - `thinking` ‏(اختياري) -- `deliver` / `to` / `channel` ‏(اختيارية) +- `deliver` / `to` / `channel` ‏(اختياري) - `timeoutSeconds` ‏(اختياري) -- `key` ‏(اختياري، مفتاح الوضع غير المراقب) +- `key` ‏(اختياري، مفتاح وضع التشغيل غير المراقب) -السلامة: +الأمان: -- من دون `key`، يطلب التطبيق تأكيدًا. -- من دون `key`، يفرض التطبيق حدًا قصيرًا للرسالة في مطالبة التأكيد ويتجاهل `deliver` / `to` / `channel`. -- مع `key` صالح، يكون التشغيل غير مراقب (مقصود للأتمتة الشخصية). +- بدون `key`، يطلب التطبيق التأكيد. +- بدون `key`، يفرض التطبيق حدًا قصيرًا لطول الرسالة في مطالبة التأكيد ويتجاهل `deliver` / `to` / `channel`. +- مع `key` صالح، يكون التشغيل غير مراقب (وهو مخصّص للأتمتة الشخصية). -## تدفق الإعداد الأولي (النموذجي) +## تدفق الإعداد الأولي (نموذجي) -1. ثبّت وشغّل **OpenClaw.app**. -2. أكمل قائمة التحقق الخاصة بالأذونات (مطالبات TCC). -3. تأكد من أن وضع **Local** نشط وأن البوابة قيد التشغيل. +1. ثبّت **OpenClaw.app** وشغّله. +2. أكمل قائمة التحقق من الأذونات (مطالبات TCC). +3. تأكد من أن وضع **Local** نشط وأن Gateway قيد التشغيل. 4. ثبّت CLI إذا كنت تريد الوصول عبر الطرفية. ## موضع دليل الحالة (macOS) -تجنب وضع دليل حالة OpenClaw في iCloud أو مجلدات أخرى متزامنة مع السحابة. -فالمسارات المدعومة بالمزامنة قد تضيف زمن انتقال وقد تسبب أحيانًا سباقات قفل/مزامنة للملفات في -الجلسات وبيانات الاعتماد. +تجنب وضع دليل حالة OpenClaw في iCloud أو أي مجلدات أخرى متزامنة عبر السحابة. +قد تضيف المسارات المدعومة بالمزامنة زمن انتقال، وقد تتسبب أحيانًا في سباقات قفل الملفات/المزامنة +للجلسات وبيانات الاعتماد. -فضّل مسار حالة محليًا غير متزامن مثل: +يفضَّل استخدام مسار حالة محلي غير متزامن مثل: __OC_I18N_900005__ -إذا اكتشف `openclaw doctor` أن الحالة موجودة تحت: +إذا اكتشف `openclaw doctor` حالة ضمن: - `~/Library/Mobile Documents/com~apple~CloudDocs/...` - `~/Library/CloudStorage/...` -فسيصدر تحذيرًا ويوصي بالعودة إلى مسار محلي. +فسوف يعرض تحذيرًا ويوصي بالعودة إلى مسار محلي. ## سير عمل البناء والتطوير (أصلي) - `cd apps/macos && swift build` - `swift run OpenClaw` ‏(أو Xcode) -- تغليف التطبيق: `scripts/package-mac-app.sh` +- تحزيم التطبيق: `scripts/package-mac-app.sh` -## تصحيح اتصال البوابة (CLI على macOS) +## تصحيح اتصال gateway ‏(CLI على macOS) -استخدم CLI الخاصة بالتصحيح لتجربة مصافحة Gateway WebSocket ومنطق الاكتشاف نفسيهما -اللذين يستخدمهما تطبيق macOS، من دون تشغيل التطبيق. +استخدم CLI الخاص بالتصحيح لاختبار المنطق نفسه الخاص بمصافحة Gateway WebSocket والاكتشاف +الذي يستخدمه تطبيق macOS، من دون تشغيل التطبيق. __OC_I18N_900006__ خيارات الاتصال: -- `--url `: تجاوز الإعداد -- `--mode `: التحليل من الإعداد (الافتراضي: الإعداد أو local) +- `--url `: تجاوز الإعدادات +- `--mode `: الحل من الإعدادات (الافتراضي: الإعدادات أو local) - `--probe`: فرض فحص سلامة جديد - `--timeout `: مهلة الطلب (الافتراضي: `15000`) -- `--json`: إخراج منظم للمقارنة +- `--json`: مخرجات منظَّمة للمقارنة خيارات الاكتشاف: -- `--include-local`: تضمين البوابات التي كان سيتم تصفيتها على أنها “local” +- `--include-local`: تضمين Gateways التي كانت ستُصفّى باعتبارها “محلية” - `--timeout `: نافذة الاكتشاف الإجمالية (الافتراضي: `2000`) -- `--json`: إخراج منظم للمقارنة +- `--json`: مخرجات منظَّمة للمقارنة نصيحة: قارن مع `openclaw gateway discover --json` لمعرفة ما إذا كان -خط اكتشاف تطبيق macOS ‏(`local.` بالإضافة إلى النطاق الواسع المُعد، مع -الرجوع إلى wide-area وTailscale Serve) يختلف عن -اكتشاف Node CLI المعتمد على `dns-sd`. +مسار اكتشاف تطبيق macOS ‏(`local.` بالإضافة إلى النطاق الواسع المُعدّ، مع +بدائل wide-area وTailscale Serve) يختلف عن +اكتشاف CLI الخاص بـ Node المعتمد على `dns-sd`. -## بنية الاتصال البعيد (أنفاق SSH) +## البنية الداخلية للاتصال البعيد (أنفاق SSH) -عندما يعمل تطبيق macOS في وضع **Remote**، فإنه يفتح نفق SSH حتى تتمكن مكونات -واجهة المستخدم المحلية من التحدث إلى البوابة البعيدة وكأنها موجودة على localhost. +عندما يعمل تطبيق macOS في وضع **Remote**، فإنه يفتح نفق SSH حتى تتمكن مكونات واجهة المستخدم المحلية +من التحدث إلى Gateway بعيد كما لو كان على localhost. ### نفق التحكم (منفذ Gateway WebSocket) -- **الغرض:** فحوصات السلامة، والحالة، وWeb Chat، والإعداد، وغيرها من استدعاءات control-plane. -- **المنفذ المحلي:** منفذ البوابة (الافتراضي `18789`) وهو دائم الثبات. -- **المنفذ البعيد:** منفذ البوابة نفسه على المضيف البعيد. +- **الغرض:** فحوصات السلامة، الحالة، Web Chat، الإعدادات، واستدعاءات مستوى التحكم الأخرى. +- **المنفذ المحلي:** منفذ Gateway ‏(الافتراضي `18789`) وهو ثابت دائمًا. +- **المنفذ البعيد:** منفذ Gateway نفسه على المضيف البعيد. - **السلوك:** لا يوجد منفذ محلي عشوائي؛ يعيد التطبيق استخدام نفق سليم موجود أو يعيد تشغيله إذا لزم الأمر. -- **شكل SSH:** ‏`ssh -N -L :127.0.0.1:` مع BatchMode + - ExitOnForwardFailure + خيارات keepalive. -- **الإبلاغ عن IP:** يستخدم نفق SSH ‏loopback، لذلك سترى البوابة عنوان IP الخاص بالعقدة - على أنه `127.0.0.1`. استخدم النقل **Direct (ws/wss)** إذا كنت تريد ظهور عنوان IP الحقيقي للعميل - (راجع [الوصول البعيد على macOS](/platforms/mac/remote)). +- **صيغة SSH:** ‏`ssh -N -L :127.0.0.1:` مع خيارات BatchMode + + ExitOnForwardFailure + keepalive. +- **الإبلاغ عن IP:** يستخدم نفق SSH عنوان loopback، لذلك سيرى الـ gateway عنوان IP + الخاص بالعقدة على أنه `127.0.0.1`. استخدم نقل **Direct (ws/wss)** إذا كنت تريد ظهور + عنوان IP الحقيقي للعميل (راجع [الوصول البعيد على macOS](/ar/platforms/mac/remote)). -للحصول على خطوات الإعداد، راجع [الوصول البعيد على macOS](/platforms/mac/remote). وبالنسبة إلى تفاصيل -البروتوكول، راجع [بروتوكول البوابة](/gateway/protocol). +لخطوات الإعداد، راجع [الوصول البعيد على macOS](/ar/platforms/mac/remote). ولتفاصيل +البروتوكول، راجع [بروتوكول Gateway](/ar/gateway/protocol). -## مستندات ذات صلة +## المستندات ذات الصلة -- [دليل تشغيل البوابة](/gateway) -- [البوابة (macOS)](/platforms/mac/bundled-gateway) -- [أذونات macOS](/platforms/mac/permissions) -- [Canvas](/platforms/mac/canvas) +- [دليل تشغيل Gateway](/ar/gateway) +- [Gateway ‏(macOS)](/ar/platforms/mac/bundled-gateway) +- [أذونات macOS](/ar/platforms/mac/permissions) +- [Canvas](/ar/platforms/mac/canvas) diff --git a/docs/ar/plugins/sdk-channel-plugins.md b/docs/ar/plugins/sdk-channel-plugins.md index c9db5d259..9a9bdc193 100644 --- a/docs/ar/plugins/sdk-channel-plugins.md +++ b/docs/ar/plugins/sdk-channel-plugins.md @@ -5,112 +5,108 @@ read_when: - تحتاج إلى فهم واجهة المهايئ ChannelPlugin sidebarTitle: Channel Plugins summary: دليل خطوة بخطوة لبناء Plugin لقناة مراسلة لـ OpenClaw -title: بناء Plugins للقنوات +title: بناء Plugins القنوات x-i18n: - generated_at: "2026-04-15T19:41:41Z" + generated_at: "2026-04-18T07:15:28Z" model: gpt-5.4 provider: openai - source_hash: 80e47e61d1e47738361692522b79aff276544446c58a7b41afe5296635dfad4b + source_hash: 3dda53c969bc7356a450c2a5bf49fb82bf1283c23e301dec832d8724b11e724b source_path: plugins/sdk-channel-plugins.md workflow: 15 --- -# بناء Plugins للقنوات +# بناء Plugins القنوات -يوضح هذا الدليل كيفية بناء Plugin لقناة يربط OpenClaw بمنصة -مراسلة. بنهاية هذا الدليل، سيكون لديك قناة عاملة تتضمن أمان الرسائل -المباشرة، والاقتران، وتسلسل الردود، والمراسلة الصادرة. +يوضح هذا الدليل كيفية بناء Plugin قناة يربط OpenClaw بمنصة مراسلة. وبنهاية هذا الدليل سيكون لديك قناة عاملة تتضمن أمان الرسائل الخاصة، والاقتران، وترابط الردود، والرسائل الصادرة. - إذا لم تكن قد بنيت أي Plugin لـ OpenClaw من قبل، فاقرأ - [البدء](/ar/plugins/building-plugins) أولًا للتعرّف على بنية - الحزمة الأساسية وإعداد ملف البيان. + إذا لم تكن قد أنشأت أي Plugin لـ OpenClaw من قبل، فاقرأ + [البدء](/ar/plugins/building-plugins) أولًا للتعرف على بنية الحزمة الأساسية + وإعداد manifest. ## كيف تعمل Plugins القنوات لا تحتاج Plugins القنوات إلى أدوات send/edit/react خاصة بها. يحتفظ OpenClaw -بأداة `message` واحدة مشتركة في النواة. ويتولى Plugin الخاص بك ما يلي: +بأداة `message` مشتركة واحدة في النواة. ويتولى Plugin الخاص بك ما يلي: -- **الإعداد** — حلّ الحسابات ومعالج الإعداد -- **الأمان** — سياسة الرسائل المباشرة وقوائم السماح -- **الاقتران** — تدفق الموافقة على الرسائل المباشرة -- **بنية الجلسة** — كيفية تعيين معرّفات المحادثات الخاصة بالموفّر إلى الدردشات الأساسية، ومعرّفات السلاسل، وبدائل الأصل +- **الإعداد** — تحليل الحسابات ومعالج الإعداد +- **الأمان** — سياسة الرسائل الخاصة وقوائم السماح +- **الاقتران** — تدفق الموافقة على الرسائل الخاصة +- **صياغة الجلسة** — كيفية ربط معرّفات المحادثات الخاصة بالمزوّد بالمحادثات الأساسية، ومعرّفات السلاسل، وبدائل الأصل - **الصادر** — إرسال النصوص والوسائط والاستطلاعات إلى المنصة -- **التسلسل** — كيفية تنظيم الردود ضمن سلاسل +- **التسلسل** — كيفية ربط الردود ضمن السلاسل -تتولى النواة أداة الرسائل المشتركة، وتوصيل المطالبات، وشكل مفتاح الجلسة -الخارجي، وآلية `:thread:` العامة، والتوجيه. +تتولى النواة أداة الرسائل المشتركة، وربط prompt، وشكل مفتاح الجلسة الخارجي، +ومسك الدفاتر العام لـ `:thread:`، والإرسال. -إذا كانت قناتك تضيف معاملات إلى أداة الرسائل تحمل مصادر وسائط، فاكشف عن -أسماء هذه المعاملات عبر `describeMessageTool(...).mediaSourceParams`. تستخدم -النواة هذه القائمة الصريحة لتطبيع مسارات sandbox وسياسة الوصول إلى الوسائط -الصادرة، لذلك لا تحتاج Plugins إلى حالات خاصة مشتركة في النواة لمعلمات -الصورة الرمزية أو المرفقات أو صورة الغلاف الخاصة بموفّرين محددين. -يُفضَّل إرجاع خريطة مرتبطة بالإجراءات مثل +إذا كانت قناتك تضيف معاملات message-tool تحمل مصادر وسائط، فاكشف أسماء هذه +المعاملات عبر `describeMessageTool(...).mediaSourceParams`. تستخدم النواة +هذه القائمة الصريحة لتطبيع مسارات sandbox وسياسة الوصول إلى الوسائط الصادرة، +بحيث لا تحتاج Plugins إلى حالات خاصة في النواة المشتركة لمعلمات الصورة +الرمزية أو المرفقات أو صورة الغلاف الخاصة بكل مزوّد. +ويُفضَّل إرجاع خريطة مفاتيحها هي الإجراءات مثل `{ "set-profile": ["avatarUrl", "avatarPath"] }` حتى لا ترث الإجراءات غير -ذات الصلة معاملات الوسائط الخاصة بإجراء آخر. ولا يزال استخدام مصفوفة -مسطحة يعمل مع المعاملات التي يُقصَد مشاركتها عمدًا عبر كل إجراء مكشوف. +المرتبطة معاملات الوسائط الخاصة بإجراء آخر. ولا تزال المصفوفة المسطحة تعمل +للمعاملات التي تكون مشتركة عمدًا بين جميع الإجراءات المكشوفة. -إذا كانت منصتك تخزّن نطاقًا إضافيًا داخل معرّفات المحادثات، فأبقِ هذا -التحليل داخل Plugin باستخدام `messaging.resolveSessionConversation(...)`. -هذا هو الخطاف القياسي لتعيين `rawId` إلى معرّف المحادثة الأساسي، ومعرّف -السلسلة الاختياري، و`baseConversationId` الصريح، وأي -`parentConversationCandidates`. -وعند إرجاع `parentConversationCandidates`، احرص على ترتيبها من الأصل الأكثر -تحديدًا إلى الأصل الأوسع/المحادثة الأساسية. +إذا كانت منصتك تخزن نطاقًا إضافيًا داخل معرّفات المحادثات، فأبقِ هذا التحليل +داخل Plugin باستخدام `messaging.resolveSessionConversation(...)`. فهذا هو +الخطاف القياسي لربط `rawId` بمعرّف المحادثة الأساسي، ومعرّف السلسلة الاختياري، +و`baseConversationId` الصريح، وأي `parentConversationCandidates`. +عند إرجاع `parentConversationCandidates`، احرص على ترتيبها من الأصل الأضيق +إلى المحادثة الأوسع/الأساسية. يمكن أيضًا لـ Plugins المضمّنة التي تحتاج إلى التحليل نفسه قبل إقلاع سجل -القنوات أن تكشف عن ملف `session-key-api.ts` على المستوى الأعلى مع -تصدير مطابق لـ `resolveSessionConversation(...)`. تستخدم النواة هذا السطح -الآمن لمرحلة الإقلاع فقط عندما لا يكون سجل Plugins وقت التشغيل متاحًا بعد. +القنوات أن تكشف ملفًا علوي المستوى باسم `session-key-api.ts` مع تصدير مطابق +لـ `resolveSessionConversation(...)`. وتستخدم النواة هذا السطح الآمن للتهيئة +فقط عندما لا يكون سجل Plugins وقت التشغيل متاحًا بعد. -يبقى `messaging.resolveParentConversationCandidates(...)` متاحًا كبديل -توافقي قديم عندما يحتاج Plugin فقط إلى بدائل الأصل فوق المعرّف الخام/العام. -إذا وُجد الخطافان معًا، تستخدم النواة -`resolveSessionConversation(...).parentConversationCandidates` أولًا، ثم -تعود إلى `resolveParentConversationCandidates(...)` فقط عندما يتجاهل -الخطاف القياسي إرجاعها. +يبقى `messaging.resolveParentConversationCandidates(...)` متاحًا كبديل توافق +قديم عندما يحتاج Plugin فقط إلى بدائل أصل فوق المعرّف العام/الخام. وإذا +وُجد الخطافان معًا، تستخدم النواة +`resolveSessionConversation(...).parentConversationCandidates` أولًا، ولا +تعود إلى `resolveParentConversationCandidates(...)` إلا إذا أغفلها الخطاف +القياسي. -## الموافقات وإمكانات القنوات +## الموافقات وقدرات القنوات -معظم Plugins القنوات لا تحتاج إلى شيفرة خاصة بالموافقات. +لا تحتاج معظم Plugins القنوات إلى شيفرة خاصة بالموافقات. - تتولى النواة `/approve` داخل المحادثة نفسها، وحمولات أزرار الموافقة المشتركة، والتسليم الاحتياطي العام. -- فضّل استخدام كائن `approvalCapability` واحد على Plugin القناة عندما تحتاج القناة إلى سلوك خاص بالموافقة. -- أُزيل `ChannelPlugin.approvals`. ضع حقائق تسليم/أصلي/عرض/مصادقة الموافقة ضمن `approvalCapability`. -- يقتصر `plugin.auth` على login/logout فقط؛ لم تعد النواة تقرأ خطافات مصادقة الموافقة من هذا الكائن. -- يُعدّ `approvalCapability.authorizeActorAction` و`approvalCapability.getActionAvailabilityState` الواجهة القياسية لمصادقة الموافقات. -- استخدم `approvalCapability.getActionAvailabilityState` لإتاحة مصادقة الموافقة داخل المحادثة نفسها. -- إذا كانت قناتك تكشف عن موافقات exec أصلية، فاستخدم `approvalCapability.getExecInitiatingSurfaceState` لحالة سطح البدء/العميل الأصلي عندما تختلف عن مصادقة الموافقة داخل المحادثة نفسها. تستخدم النواة هذا الخطاف الخاص بـ exec للتمييز بين `enabled` و`disabled`، وتحديد ما إذا كانت قناة البدء تدعم موافقات exec الأصلية، وإدراج القناة في إرشادات الرجوع إلى العميل الأصلي. يملأ `createApproverRestrictedNativeApprovalCapability(...)` هذا الجزء للحالة الشائعة. -- استخدم `outbound.shouldSuppressLocalPayloadPrompt` أو `outbound.beforeDeliverPayload` لسلوك دورة حياة الحمولة الخاص بالقناة، مثل إخفاء مطالبات الموافقة المحلية المكررة أو إرسال مؤشرات الكتابة قبل التسليم. -- استخدم `approvalCapability.delivery` فقط لتوجيه الموافقة الأصلي أو منع الرجوع الاحتياطي. -- استخدم `approvalCapability.nativeRuntime` للحقائق الأصلية الخاصة بالموافقة التي تملكها القناة. أبقه كسول التحميل في نقاط دخول القنوات الساخنة باستخدام `createLazyChannelApprovalNativeRuntimeAdapter(...)`، والذي يمكنه استيراد وحدة وقت التشغيل عند الطلب مع السماح للنواة بتجميع دورة حياة الموافقة. +- فضّل كائن `approvalCapability` واحدًا على Plugin القناة عندما تحتاج القناة إلى سلوك خاص بالموافقة. +- تمت إزالة `ChannelPlugin.approvals`. ضع حقائق التسليم/الأصلي/العرض/المصادقة الخاصة بالموافقة على `approvalCapability`. +- يقتصر `plugin.auth` على login/logout فقط؛ ولم تعد النواة تقرأ خطافات مصادقة الموافقة من ذلك الكائن. +- يمثل `approvalCapability.authorizeActorAction` و`approvalCapability.getActionAvailabilityState` نقطة الربط القياسية لمصادقة الموافقات. +- استخدم `approvalCapability.getActionAvailabilityState` لتوفر مصادقة الموافقة داخل المحادثة نفسها. +- إذا كانت قناتك تكشف عن موافقات exec أصلية، فاستخدم `approvalCapability.getExecInitiatingSurfaceState` لحالة السطح البادئ/العميل الأصلي عندما تختلف عن مصادقة الموافقة داخل المحادثة نفسها. تستخدم النواة هذا الخطاف الخاص بـ exec للتمييز بين `enabled` و`disabled`، وتقرير ما إذا كانت القناة البادئة تدعم موافقات exec الأصلية، وضم القناة إلى إرشادات fallback الخاصة بالعميل الأصلي. تملأ `createApproverRestrictedNativeApprovalCapability(...)` هذا الجزء للحالة الشائعة. +- استخدم `outbound.shouldSuppressLocalPayloadPrompt` أو `outbound.beforeDeliverPayload` لسلوك دورة حياة الحمولات الخاص بالقناة مثل إخفاء مطالبات الموافقة المحلية المكررة أو إرسال مؤشرات الكتابة قبل التسليم. +- استخدم `approvalCapability.delivery` فقط لتوجيه الموافقة الأصلية أو تعطيل fallback. +- استخدم `approvalCapability.nativeRuntime` للحقائق الأصلية الخاصة بالموافقة التي تملكها القناة. أبقه كسول التحميل على نقاط دخول القنوات الساخنة باستخدام `createLazyChannelApprovalNativeRuntimeAdapter(...)`، الذي يمكنه استيراد وحدة وقت التشغيل لديك عند الطلب مع الاستمرار في تمكين النواة من تجميع دورة حياة الموافقة. - استخدم `approvalCapability.render` فقط عندما تحتاج القناة فعلًا إلى حمولات موافقة مخصصة بدلًا من العارض المشترك. -- استخدم `approvalCapability.describeExecApprovalSetup` عندما تريد القناة أن يشرح رد المسار المعطّل مقابض الإعداد الدقيقة اللازمة لتمكين موافقات exec الأصلية. يستقبل الخطاف `{ channel, channelLabel, accountId }`؛ ويجب على القنوات ذات الحسابات المسماة عرض مسارات بنطاق الحساب مثل `channels..accounts..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` — إعداد الأهداف بالإضافة إلى إرسال/تحديث/حذف رسائل الموافقة الأصلية +- استخدم `approvalCapability.describeExecApprovalSetup` عندما تريد القناة أن يشرح رد مسار التعطيل مفاتيح الإعداد الدقيقة اللازمة لتمكين موافقات exec الأصلية. يتلقى الخطاف `{ channel, channelLabel, accountId }`؛ ويجب على القنوات ذات الحسابات المسماة عرض مسارات ضمن نطاق الحساب مثل `channels..accounts..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`. يتيح سجل runtime-context العام للنواة إقلاع معالجات مدفوعة بالإمكانات من حالة بدء تشغيل القناة دون إضافة غراء تغليف خاص بالموافقة. -- لا تلجأ إلى `createChannelApprovalHandler` أو `createChannelNativeApprovalRuntime` منخفضي المستوى إلا عندما لا تكون الواجهة المدفوعة بالإمكانات معبّرة بما يكفي بعد. -- يجب أن تمرّر قنوات الموافقة الأصلية كِلا `accountId` و`approvalKind` عبر هذه المساعدات. يُبقي `accountId` سياسة الموافقة متعددة الحسابات ضمن نطاق حساب البوت الصحيح، ويُبقي `approvalKind` سلوك exec مقابل موافقة Plugin متاحًا للقناة دون تفرعات مشفّرة مسبقًا في النواة. -- تتولى النواة الآن أيضًا إشعارات إعادة توجيه الموافقات. يجب ألا ترسل Plugins القنوات رسائل متابعة خاصة بها من نوع "تم إرسال الموافقة إلى الرسائل المباشرة / قناة أخرى" من `createChannelNativeApprovalRuntime`; وبدلًا من ذلك، اكشف عن توجيه دقيق للأصل + الرسائل المباشرة للموافق عبر مساعدات إمكانات الموافقة المشتركة، ودع النواة تجمع عمليات التسليم الفعلية قبل نشر أي إشعار مرة أخرى إلى محادثة البدء. -- حافظ على نوع معرّف الموافقة الذي تم تسليمه من البداية إلى النهاية. يجب ألا - تخمّن العملاء الأصلية أو تعيد كتابة توجيه موافقة exec مقابل Plugin من حالة - محلية خاصة بالقناة. -- يمكن لأنواع الموافقات المختلفة عمدًا أن تكشف عن أسطح أصلية مختلفة. - الأمثلة المضمّنة الحالية: - - يحتفظ Slack بإتاحة توجيه الموافقة الأصلي لكل من معرّفات exec وPlugin. - - يحتفظ Matrix بالتوجيه الأصلي نفسه للرسائل المباشرة/القناة وتجربة التفاعل لـ exec - وموافقات Plugin، مع الاستمرار في السماح لاختلاف المصادقة حسب نوع الموافقة. -- لا يزال `createApproverRestrictedNativeApprovalAdapter` موجودًا كغلاف توافقي، لكن الشيفرة الجديدة يجب أن تفضّل مُنشئ الإمكانات وتكشف عن `approvalCapability` على Plugin. +- `observe` — خطافات تشخيص اختيارية للتسليم +- إذا كانت القناة تحتاج إلى كائنات يملكها وقت التشغيل مثل عميل أو token أو تطبيق Bolt أو مستقبِل Webhook، فسجّلها عبر `openclaw/plugin-sdk/channel-runtime-context`. يتيح سجل runtime-context العام للنواة تهيئة المعالجات المدفوعة بالقدرات من حالة بدء تشغيل القناة من دون إضافة تعليمات ربط خاصة بالموافقة. +- لا تلجأ إلى `createChannelApprovalHandler` أو `createChannelNativeApprovalRuntime` ذوي المستوى الأدنى إلا عندما لا تكون نقطة الربط المدفوعة بالقدرات معبّرة بما يكفي بعد. +- يجب على قنوات الموافقات الأصلية تمرير كل من `accountId` و`approvalKind` عبر تلك الأدوات المساعدة. إذ يُبقي `accountId` سياسة الموافقات متعددة الحسابات ضمن نطاق حساب bot الصحيح، بينما يُبقي `approvalKind` سلوك exec مقابل موافقة Plugin متاحًا للقناة من دون فروع مضمّنة في النواة. +- تتولى النواة الآن أيضًا إشعارات إعادة توجيه الموافقات. يجب ألا ترسل Plugins القنوات رسائل متابعة خاصة بها من نوع "تم إرسال الموافقة إلى الرسائل الخاصة / إلى قناة أخرى" من `createChannelNativeApprovalRuntime`؛ وبدلًا من ذلك، اكشف عن توجيه origin + الرسائل الخاصة للموافق عبر أدوات المساعدة المشتركة لقدرات الموافقة، ودع النواة تجمع عمليات التسليم الفعلية قبل نشر أي إشعار إلى المحادثة البادئة. +- حافظ على نوع معرّف الموافقة المُسلَّمة من البداية إلى النهاية. يجب ألا تقوم العملاء الأصلية + بتخمين أو إعادة كتابة توجيه موافقة exec مقابل موافقة Plugin بالاعتماد على حالة محلية للقناة. +- يمكن لأنواع الموافقات المختلفة أن تكشف عمدًا عن أسطح أصلية مختلفة. + أمثلة حالية من Plugins المضمّنة: + - يحتفظ Slack بتوجيه الموافقات الأصلية متاحًا لكل من معرّفات exec وPlugin. + - يحتفظ Matrix بالتوجيه الأصلي نفسه للرسائل الخاصة/القناة وتجربة التفاعلات لموافقات exec + وPlugin، مع السماح مع ذلك باختلاف المصادقة حسب نوع الموافقة. +- لا يزال `createApproverRestrictedNativeApprovalAdapter` موجودًا كغلاف توافق، لكن يجب أن تفضّل الشيفرة الجديدة منشئ القدرات وأن تكشف `approvalCapability` على Plugin. -لنقاط دخول القنوات الساخنة، فضّل المسارات الفرعية الأضيق لوقت التشغيل عندما -تحتاج فقط إلى جزء واحد من هذه المجموعة: +بالنسبة إلى نقاط دخول القنوات الساخنة، فضّل المسارات الفرعية الأضيق لوقت التشغيل عندما +تحتاج إلى جزء واحد فقط من تلك المجموعة: - `openclaw/plugin-sdk/approval-auth-runtime` - `openclaw/plugin-sdk/approval-client-runtime` @@ -122,89 +118,90 @@ 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` مساعدات الإعداد الآمنة لوقت التشغيل: +- يغطي `openclaw/plugin-sdk/setup-runtime` أدوات الإعداد الآمنة لوقت التشغيل: مهايئات ترقيع الإعداد الآمنة للاستيراد (`createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, - `createSetupInputPresenceValidator`)، ومخرجات - ملاحظات البحث، و`promptResolvedAllowFrom`، و`splitSetupEntries`، ومنشئات - وكيل الإعداد المفوّض -- يُعد `openclaw/plugin-sdk/setup-adapter-runtime` الواجهة الضيقة الواعية بالبيئة - لـ `createEnvPatchedAccountSetupAdapter` -- يغطي `openclaw/plugin-sdk/channel-setup` منشئات الإعداد ذات التثبيت الاختياري - بالإضافة إلى بعض البدائيات الآمنة للإعداد: - `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`، + `createSetupInputPresenceValidator`)، وإخراج ملاحظات البحث، + و`promptResolvedAllowFrom`، و`splitSetupEntries`، وبناة + setup-proxy المفوضة +- يمثل `openclaw/plugin-sdk/setup-adapter-runtime` نقطة الربط الضيقة + الواعية بالبيئة لـ `createEnvPatchedAccountSetupAdapter` +- يغطي `openclaw/plugin-sdk/channel-setup` بناة الإعداد ذي التثبيت الاختياري + بالإضافة إلى بعض الأساسيات الآمنة للإعداد: + `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, -إذا كانت قناتك تدعم إعدادًا أو مصادقة مدفوعين بالبيئة، وكان ينبغي أن تعرف -تدفقات البدء/الإعداد العامة أسماء متغيرات البيئة تلك قبل تحميل وقت التشغيل، -فصرّح عنها في ملف بيان Plugin باستخدام `channelEnvVars`. واحتفظ بمتغيرات -البيئة `envVars` وقت تشغيل القناة أو الثوابت المحلية فقط لنسخة النص -الموجّهة للمشغّل. +إذا كانت قناتك تدعم الإعداد أو المصادقة المدفوعين بالبيئة وكان ينبغي لتدفقات +بدء التشغيل/الإعداد العامة معرفة أسماء متغيرات البيئة هذه قبل تحميل وقت التشغيل، +فصرّح بها في manifest الخاص بـ Plugin باستخدام `channelEnvVars`. واحتفظ +بـ `envVars` في وقت تشغيل القناة أو الثوابت المحلية فقط للنصوص الموجّهة +للمشغّل. `createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`, -`createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, و +`createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`، و `splitSetupEntries` -- استخدم واجهة `openclaw/plugin-sdk/setup` الأوسع فقط عندما تحتاج أيضًا إلى - مساعدات الإعداد/التهيئة المشتركة الأثقل مثل +- استخدم نقطة الربط الأوسع `openclaw/plugin-sdk/setup` فقط عندما تحتاج أيضًا إلى + أدوات الإعداد/التهيئة المشتركة الأثقل مثل `moveSingleAccountChannelSectionToDefaultAccount(...)` -إذا كانت قناتك تريد فقط الإعلان عن "ثبّت هذا Plugin أولًا" في -أسطح الإعداد، ففضّل `createOptionalChannelSetupSurface(...)`. يفشل -المهايئ/المعالج المُولَّدان بشكل مغلق عند عمليات كتابة الإعداد والإنهاء، -ويعيدان استخدام الرسالة نفسها التي تفيد بضرورة التثبيت عبر التحقق والإنهاء -ونص رابط الوثائق. +إذا كانت قناتك تريد فقط الإعلان عن "ثبّت هذا Plugin أولًا" في أسطح الإعداد، +ففضّل `createOptionalChannelSetupSurface(...)`. إذ يفشل المهايئ/المعالج +المولدان على نحو مغلق عند عمليات كتابة الإعداد والإنهاء، ويعيدان استخدام +رسالة التثبيت المطلوبة نفسها عبر التحقق والإنهاء ونص رابط التوثيق. -وبالنسبة لمسارات القنوات الساخنة الأخرى، فضّل المساعدات الضيقة على الأسطح -القديمة الأوسع: +وبالنسبة إلى المسارات الساخنة الأخرى للقنوات، فضّل الأدوات المساعدة الضيقة على +الأسطح القديمة الأوسع: - `openclaw/plugin-sdk/account-core`, و`openclaw/plugin-sdk/account-id`, و`openclaw/plugin-sdk/account-resolution`، و - `openclaw/plugin-sdk/account-helpers` لإعداد الحسابات المتعددة و - الرجوع إلى الحساب الافتراضي + `openclaw/plugin-sdk/account-helpers` لإعدادات الحسابات المتعددة + وfallback الحساب الافتراضي - `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` فقط عندما يكون تخطيط حقول - حمولة الوكيل/الوسائط القديم لا يزال مطلوبًا -- `openclaw/plugin-sdk/telegram-command-config` لتطبيع أوامر Telegram المخصصة، - والتحقق من التكرار/التعارض، وعقد إعداد الأوامر المستقر عند الرجوع الاحتياطي + الحمولات القديمة للوكيل/الوسائط لا يزال مطلوبًا +- `openclaw/plugin-sdk/telegram-command-config` لتطبيع الأوامر المخصصة في Telegram، + والتحقق من التكرارات/التعارضات، وعقد إعدادات الأوامر الثابت في fallback -يمكن للقنوات التي تعتمد على المصادقة فقط عادةً الاكتفاء بالمسار الافتراضي: تتولى النواة الموافقات، ويكشف Plugin فقط عن إمكانات الصادر/المصادقة. يجب على قنوات الموافقة الأصلية مثل Matrix وSlack وTelegram ووسائط نقل الدردشة المخصصة استخدام المساعدات الأصلية المشتركة بدلًا من بناء دورة حياة الموافقة الخاصة بها. +يمكن للقنوات التي تقتصر على المصادقة فقط أن تتوقف عادة عند المسار الافتراضي: تتولى النواة الموافقات، ويكشف Plugin فقط عن قدرات الصادر/المصادقة. أما قنوات الموافقات الأصلية مثل Matrix وSlack وTelegram ووسائط الدردشة المخصصة، فيجب أن تستخدم الأدوات المساعدة الأصلية المشتركة بدلًا من بناء دورة حياة الموافقة الخاصة بها. ## سياسة الإشارات الواردة -احرص على إبقاء معالجة الإشارات الواردة مقسّمة إلى طبقتين: +أبقِ معالجة الإشارات الواردة مقسمة إلى طبقتين: -- جمع الأدلة المملوك لـ Plugin +- جمع الأدلة الذي يملكه Plugin - تقييم السياسة المشتركة -استخدم `openclaw/plugin-sdk/channel-inbound` للطبقة المشتركة. +استخدم `openclaw/plugin-sdk/channel-mention-gating` لقرارات سياسة الإشارات. +واستخدم `openclaw/plugin-sdk/channel-inbound` فقط عندما تحتاج إلى +شريط أدوات inbound الأوسع. -ما يناسب المنطق المحلي في Plugin: +حالات مناسبة للمنطق المحلي داخل Plugin: -- اكتشاف الرد على البوت -- اكتشاف الاقتباس من البوت +- اكتشاف الرد على bot +- اكتشاف الاقتباس من bot - التحقق من المشاركة في السلسلة - استبعاد رسائل الخدمة/النظام -- الذاكرات المؤقتة الأصلية للمنصة اللازمة لإثبات مشاركة البوت +- ذاكرات تخزين أصلية للمنصة لازمة لإثبات مشاركة bot -ما يناسب المساعد المشترك: +حالات مناسبة للأداة المساعدة المشتركة: - `requireMention` - نتيجة الإشارة الصريحة @@ -212,11 +209,11 @@ x-i18n: - تجاوز الأوامر - قرار التخطي النهائي -التدفق المفضّل: +التدفق المفضل: 1. احسب حقائق الإشارة المحلية. -2. مرّر هذه الحقائق إلى `resolveInboundMentionDecision({ facts, policy })`. -3. استخدم `decision.effectiveWasMentioned` و`decision.shouldBypassMention` و`decision.shouldSkip` في بوابة الوارد الخاصة بك. +2. مرر هذه الحقائق إلى `resolveInboundMentionDecision({ facts, policy })`. +3. استخدم `decision.effectiveWasMentioned` و`decision.shouldBypassMention` و`decision.shouldSkip` في بوابة inbound الخاصة بك. ```typescript import { @@ -255,8 +252,8 @@ const decision = resolveInboundMentionDecision({ if (decision.shouldSkip) return; ``` -يكشف `api.runtime.channel.mentions` عن مساعدات الإشارة المشتركة نفسها من أجل -Plugins القنوات المضمّنة التي تعتمد بالفعل على حقن وقت التشغيل: +يكشف `api.runtime.channel.mentions` عن أدوات الإشارات المشتركة نفسها +لـ Plugins القنوات المضمّنة التي تعتمد بالفعل على حقن وقت التشغيل: - `buildMentionRegexes` - `matchesMentionPatterns` @@ -264,18 +261,23 @@ Plugins القنوات المضمّنة التي تعتمد بالفعل على - `implicitMentionKindWhen` - `resolveInboundMentionDecision` -تبقى مساعدات `resolveMentionGating*` الأقدم على -`openclaw/plugin-sdk/channel-inbound` كتصديرات توافقية فقط. يجب أن تستخدم +إذا كنت تحتاج فقط إلى `implicitMentionKindWhen` و +`resolveInboundMentionDecision`، فاستورد من +`openclaw/plugin-sdk/channel-mention-gating` لتجنب تحميل أدوات +وقت تشغيل inbound غير المرتبطة. + +تبقى أدوات `resolveMentionGating*` الأقدم موجودة على +`openclaw/plugin-sdk/channel-inbound` كتصديرات توافق فقط. ويجب أن تستخدم الشيفرة الجديدة `resolveInboundMentionDecision({ facts, policy })`. ## شرح عملي - - أنشئ ملفات Plugin القياسية. الحقل `channel` في `package.json` هو - ما يجعل هذا Plugin قناة. وللاطلاع على سطح بيانات وصف الحزمة الكامل، - راجع [إعداد Plugin والتهيئة](/ar/plugins/sdk-setup#openclaw-channel): + + أنشئ ملفات Plugin القياسية. إن الحقل `channel` في `package.json` هو + ما يجعل هذا Plugin قناة. وللاطلاع على سطح بيانات الحزمة الوصفية الكامل، + راجع [إعداد Plugin وConfig](/ar/plugins/sdk-setup#openclaw-channel): ```json package.json @@ -324,7 +326,7 @@ Plugins القنوات المضمّنة التي تعتمد بالفعل على - + تحتوي الواجهة `ChannelPlugin` على العديد من أسطح المهايئات الاختيارية. ابدأ بالحد الأدنى — `id` و`setup` — ثم أضف المهايئات حسب حاجتك. @@ -336,7 +338,7 @@ Plugins القنوات المضمّنة التي تعتمد بالفعل على createChannelPluginBase, } from "openclaw/plugin-sdk/channel-core"; import type { OpenClawConfig } from "openclaw/plugin-sdk/channel-core"; - import { acmeChatApi } from "./client.js"; // عميل API الخاص بمنصتك + import { acmeChatApi } from "./client.js"; // your platform API client type ResolvedAccount = { accountId: string | null; @@ -377,7 +379,7 @@ Plugins القنوات المضمّنة التي تعتمد بالفعل على }, }), - // أمان الرسائل المباشرة: من يمكنه مراسلة البوت + // DM security: who can message the bot security: { dm: { channelKey: "acme-chat", @@ -387,21 +389,21 @@ Plugins القنوات المضمّنة التي تعتمد بالفعل على }, }, - // الاقتران: تدفق الموافقة لجهات الاتصال الجديدة في الرسائل المباشرة + // Pairing: approval flow for new DM contacts pairing: { text: { - idLabel: "اسم مستخدم Acme Chat", - message: "أرسل هذا الرمز للتحقق من هويتك:", + idLabel: "Acme Chat username", + message: "Send this code to verify your identity:", notify: async ({ target, code }) => { await acmeChatApi.sendDm(target, `Pairing code: ${code}`); }, }, }, - // التسلسل: كيفية تسليم الردود + // Threading: how replies are delivered threading: { topLevelReplyToMode: "reply" }, - // الصادر: إرسال الرسائل إلى المنصة + // Outbound: send messages to the platform outbound: { attachedResults: { sendText: async (params) => { @@ -421,16 +423,16 @@ Plugins القنوات المضمّنة التي تعتمد بالفعل على }); ``` - - بدلًا من تنفيذ واجهات المهايئات منخفضة المستوى يدويًا، فإنك تمرّر - خيارات تصريحية ويتولى المُنشئ تركيبها: + + بدلًا من تنفيذ واجهات مهايئات منخفضة المستوى يدويًا، تمرر + خيارات تصريحية ويقوم البنّاء بتجميعها: - | الخيار | ما الذي يوصله | + | الخيار | ما الذي يربطه | | --- | --- | - | `security.dm` | محلّل أمان الرسائل المباشرة المقيّد بنطاق حقول التهيئة | - | `pairing.text` | تدفق اقتران رسائل مباشرة قائم على النص مع تبادل الرمز | - | `threading` | محلّل وضع الرد (ثابت أو مقيّد بالحساب أو مخصص) | - | `outbound.attachedResults` | دوال إرسال تُرجع بيانات وصفية للنتيجة (معرّفات الرسائل) | + | `security.dm` | محلل أمان رسائل خاصة محدد النطاق من حقول config | + | `pairing.text` | تدفق اقتران رسائل خاصة قائم على النص مع تبادل رمز | + | `threading` | محلل وضع reply-to (ثابت، أو ضمن نطاق الحساب، أو مخصص) | + | `outbound.attachedResults` | دوال send تُرجع بيانات وصفية للنتيجة (معرّفات الرسائل) | يمكنك أيضًا تمرير كائنات مهايئات خام بدلًا من الخيارات التصريحية إذا كنت بحاجة إلى تحكم كامل. @@ -438,7 +440,7 @@ Plugins القنوات المضمّنة التي تعتمد بالفعل على - + أنشئ `index.ts`: ```typescript index.ts @@ -474,22 +476,22 @@ Plugins القنوات المضمّنة التي تعتمد بالفعل على }); ``` - ضع واصفات CLI المملوكة للقناة في `registerCliMetadata(...)` حتى يتمكن OpenClaw + ضع واصفات CLI التي تملكها القناة في `registerCliMetadata(...)` حتى يتمكن OpenClaw من عرضها في المساعدة الجذرية دون تفعيل وقت تشغيل القناة الكامل، - بينما تستمر التحميلات الكاملة العادية في التقاط الواصفات نفسها لتسجيل - الأوامر الفعلي. أبقِ `registerFull(...)` للأعمال الخاصة بوقت التشغيل فقط. - وإذا كان `registerFull(...)` يسجّل أساليب Gateway RPC، فاستخدم - بادئة خاصة بـ Plugin. تبقى مساحات أسماء الإدارة في النواة (`config.*`, - و`exec.approvals.*`، و`wizard.*`، و`update.*`) محجوزة وتُحل دائمًا إلى - `operator.admin`. - يتولى `defineChannelPluginEntry` معالجة فصل أوضاع التسجيل تلقائيًا. راجع - [نقاط الإدخال](/ar/plugins/sdk-entrypoints#definechannelpluginentry) لجميع - الخيارات. + بينما تلتقط التحميلات الكاملة العادية الواصفات نفسها أيضًا من أجل التسجيل + الفعلي للأوامر. وأبقِ `registerFull(...)` للأعمال الخاصة بوقت التشغيل فقط. + إذا كان `registerFull(...)` يسجل أساليب Gateway RPC، فاستخدم + بادئة خاصة بـ Plugin. تظل مساحات أسماء الإدارة في النواة (`config.*`, + و`exec.approvals.*`, و`wizard.*`, و`update.*`) محجوزة وتُحل دائمًا + إلى `operator.admin`. + يتولى `defineChannelPluginEntry` فصل أوضاع التسجيل تلقائيًا. راجع + [نقاط الإدخال](/ar/plugins/sdk-entrypoints#definechannelpluginentry) لمعرفة + جميع الخيارات. - - أنشئ `setup-entry.ts` للتحميل الخفيف أثناء الإعداد الأولي: + + أنشئ `setup-entry.ts` للتحميل الخفيف أثناء الإلحاق الأولي: ```typescript setup-entry.ts import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core"; @@ -498,33 +500,33 @@ Plugins القنوات المضمّنة التي تعتمد بالفعل على export default defineSetupPluginEntry(acmeChatPlugin); ``` - يحمّل OpenClaw هذا بدلًا من نقطة الإدخال الكاملة عندما تكون القناة معطّلة - أو غير مهيأة. وهذا يتجنب سحب شيفرة وقت تشغيل ثقيلة أثناء تدفقات الإعداد. - راجع [الإعداد والتهيئة](/ar/plugins/sdk-setup#setup-entry) لمزيد من التفاصيل. + يحمّل OpenClaw هذا بدلًا من نقطة الإدخال الكاملة عندما تكون القناة معطلة + أو غير مضبوطة. وهذا يتجنب سحب شيفرة وقت تشغيل ثقيلة أثناء تدفقات الإعداد. + راجع [الإعداد وConfig](/ar/plugins/sdk-setup#setup-entry) للحصول على التفاصيل. - يمكن لقنوات مساحة العمل المضمّنة التي تفصل التصديرات الآمنة للإعداد في - وحدات جانبية أن تستخدم `defineBundledChannelSetupEntry(...)` من + يمكن لقنوات مساحة العمل المضمّنة التي تقسم الصادرات الآمنة للإعداد إلى وحدات + جانبية أن تستخدم `defineBundledChannelSetupEntry(...)` من `openclaw/plugin-sdk/channel-entry-contract` عندما تحتاج أيضًا إلى - مُعيّن صريح لوقت التشغيل في وقت الإعداد. + محدد صريح لوقت تشغيل الإعداد. - - يحتاج Plugin الخاص بك إلى تلقي الرسائل من المنصة وتمريرها إلى - OpenClaw. النمط المعتاد هو Webhook يتحقق من الطلب ويقوم - بإرساله عبر معالج الوارد الخاص بقناتك: + + يحتاج Plugin الخاص بك إلى استقبال الرسائل من المنصة وتمريرها إلى + OpenClaw. والنمط المعتاد هو Webhook يتحقق من الطلب ويقوم + بإرساله عبر معالج inbound الخاص بقناتك: ```typescript registerFull(api) { api.registerHttpRoute({ path: "/acme-chat/webhook", - auth: "plugin", // مصادقة يديرها Plugin (تحقق من التواقيع بنفسك) + auth: "plugin", // plugin-managed auth (verify signatures yourself) handler: async (req, res) => { const event = parseWebhookPayload(req); - // يقوم معالج الوارد الخاص بك بإرسال الرسالة إلى OpenClaw. - // يعتمد التوصيل الدقيق على SDK الخاص بمنصتك — - // راجع مثالًا حقيقيًا في حزمة Plugin المضمّنة الخاصة بـ Microsoft Teams أو Google Chat. + // 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. await handleAcmeChatInbound(api, event); res.statusCode = 200; @@ -536,23 +538,23 @@ Plugins القنوات المضمّنة التي تعتمد بالفعل على ``` - معالجة الرسائل الواردة خاصة بكل قناة. كل Plugin قناة يملك - مسار الوارد الخاص به. انظر إلى Plugins القنوات المضمّنة + إن معالجة الرسائل الواردة خاصة بكل قناة. يمتلك كل Plugin قناة + مسار inbound الخاص به. انظر إلى Plugins القنوات المضمّنة (مثل حزمة Plugin الخاصة بـ Microsoft Teams أو Google Chat) للاطلاع على أنماط حقيقية. - + اكتب اختبارات موضوعة بجوار الشيفرة في `src/channel.test.ts`: ```typescript src/channel.test.ts import { describe, it, expect } from "vitest"; import { acmeChatPlugin } from "./channel.js"; - describe("acme-chat plugin", () => { - it("resolves account from config", () => { + describe("plugin acme-chat", () => { + it("يحل الحساب من الإعدادات", () => { const cfg = { channels: { "acme-chat": { token: "test-token", allowFrom: ["user1"] }, @@ -562,7 +564,7 @@ Plugins القنوات المضمّنة التي تعتمد بالفعل على expect(account.token).toBe("test-token"); }); - it("inspects account without materializing secrets", () => { + it("يفحص الحساب دون إظهار الأسرار", () => { const cfg = { channels: { "acme-chat": { token: "test-token" } }, } as any; @@ -571,7 +573,7 @@ Plugins القنوات المضمّنة التي تعتمد بالفعل على expect(result.tokenStatus).toBe("available"); }); - it("reports missing config", () => { + it("يبلّغ عن الإعدادات المفقودة", () => { const cfg = { channels: {} } as any; const result = acmeChatPlugin.setup!.inspectAccount!(cfg, undefined); expect(result.configured).toBe(false); @@ -583,7 +585,7 @@ Plugins القنوات المضمّنة التي تعتمد بالفعل على pnpm test -- /acme-chat/ ``` - بالنسبة إلى مساعدات الاختبار المشتركة، راجع [الاختبار](/ar/plugins/sdk-testing). + للاطلاع على أدوات الاختبار المساعدة المشتركة، راجع [الاختبار](/ar/plugins/sdk-testing). @@ -593,45 +595,45 @@ Plugins القنوات المضمّنة التي تعتمد بالفعل على ``` /acme-chat/ ├── package.json # بيانات openclaw.channel الوصفية -├── openclaw.plugin.json # ملف البيان مع مخطط التهيئة +├── openclaw.plugin.json # Manifest مع مخطط config ├── index.ts # defineChannelPluginEntry ├── setup-entry.ts # defineSetupPluginEntry -├── api.ts # التصديرات العامة (اختياري) -├── runtime-api.ts # تصديرات وقت التشغيل الداخلية (اختياري) +├── api.ts # الصادرات العامة (اختياري) +├── runtime-api.ts # صادرات وقت التشغيل الداخلية (اختياري) └── src/ ├── channel.ts # ChannelPlugin عبر createChatChannelPlugin ├── channel.test.ts # الاختبارات - ├── client.ts # عميل API الخاص بالمنصة + ├── client.ts # عميل API للمنصة └── runtime.ts # مخزن وقت التشغيل (عند الحاجة) ``` -## موضوعات متقدمة +## مواضيع متقدمة - أوضاع رد ثابتة، أو مقيّدة بالحساب، أو مخصصة + أوضاع رد ثابتة، أو ضمن نطاق الحساب، أو مخصصة - + describeMessageTool واكتشاف الإجراءات - + inferTargetChatType, looksLikeId, resolveTarget - + TTS وSTT والوسائط وsubagent عبر api.runtime -لا تزال بعض واجهات المساعدة المضمّنة موجودة لصيانة Plugins المضمّنة -والتوافق. وهي ليست النمط الموصى به لـ Plugins القنوات الجديدة؛ -فضّل المسارات الفرعية العامة للقناة/الإعداد/الرد/وقت التشغيل من سطح SDK -المشترك ما لم تكن تصون تلك العائلة من Plugins المضمّنة مباشرةً. +لا تزال بعض نقاط الربط الخاصة بالأدوات المساعدة المضمّنة موجودة لصيانة Plugins +المضمّنة ولأغراض التوافق. لكنها ليست النمط الموصى به لـ Plugins القنوات الجديدة؛ +بل يُفضّل استخدام المسارات الفرعية العامة للقنوات/الإعداد/الرد/وقت التشغيل من سطح +SDK المشترك، إلا إذا كنت تصون عائلة Plugin المضمّنة تلك مباشرة. ## الخطوات التالية -- [Plugins الموفّرين](/ar/plugins/sdk-provider-plugins) — إذا كان Plugin الخاص بك يوفّر أيضًا نماذج +- [Plugins المزودين](/ar/plugins/sdk-provider-plugins) — إذا كان Plugin الخاص بك يوفر أيضًا نماذج - [نظرة عامة على SDK](/ar/plugins/sdk-overview) — المرجع الكامل لاستيراد المسارات الفرعية -- [اختبار SDK](/ar/plugins/sdk-testing) — أدوات الاختبار واختبارات العقود -- [ملف بيان Plugin](/ar/plugins/manifest) — مخطط ملف البيان الكامل +- [اختبار SDK](/ar/plugins/sdk-testing) — أدوات الاختبار المساعدة واختبارات العقود +- [Plugin Manifest](/ar/plugins/manifest) — مخطط manifest الكامل diff --git a/docs/ar/plugins/sdk-overview.md b/docs/ar/plugins/sdk-overview.md index cbef9561c..c3a75cdaf 100644 --- a/docs/ar/plugins/sdk-overview.md +++ b/docs/ar/plugins/sdk-overview.md @@ -1,30 +1,30 @@ --- read_when: - تحتاج إلى معرفة أي مسار فرعي من SDK يجب الاستيراد منه - - تريد مرجعًا لجميع أساليب التسجيل في `OpenClawPluginApi` + - تريد مرجعًا لجميع أساليب التسجيل في OpenClawPluginApi - أنت تبحث عن تصدير محدد في SDK sidebarTitle: SDK Overview -summary: خريطة الاستيراد، مرجع API للتسجيل، وبنية SDK +summary: مرجع Import map وواجهة برمجة تطبيقات التسجيل وبنية SDK title: نظرة عامة على Plugin SDK x-i18n: - generated_at: "2026-04-17T07:17:56Z" + generated_at: "2026-04-18T07:15:30Z" model: gpt-5.4 provider: openai - source_hash: b177fdb6830f415d998a24812bc2c7db8124d3ba77b0174c9a67ac7d747f7e5a + source_hash: 05d3d0022cca32d29c76f6cea01cdf4f88ac69ef0ef3d7fb8a60fbf9a6b9b331 source_path: plugins/sdk-overview.md workflow: 15 --- # نظرة عامة على Plugin SDK -يمثل Plugin SDK العقد المطبوع بين المكونات الإضافية والنواة. تُعد هذه الصفحة +يمثل Plugin SDK العقد المطبوع بين Plugins والنواة. وهذه الصفحة هي المرجع الخاص بـ **ما الذي يجب استيراده** و**ما الذي يمكنك تسجيله**. **هل تبحث عن دليل إرشادي؟** - - أول مكوّن إضافي؟ ابدأ من [البدء](/ar/plugins/building-plugins) - - مكوّن إضافي للقنوات؟ راجع [المكونات الإضافية للقنوات](/ar/plugins/sdk-channel-plugins) - - مكوّن إضافي للموفّر؟ راجع [المكونات الإضافية للموفّر](/ar/plugins/sdk-provider-plugins) + - أول Plugin؟ ابدأ من [البدء](/ar/plugins/building-plugins) + - Plugin قناة؟ راجع [Plugins القنوات](/ar/plugins/sdk-channel-plugins) + - Plugin موفّر؟ راجع [Plugins الموفّرين](/ar/plugins/sdk-provider-plugins) ## اصطلاح الاستيراد @@ -36,39 +36,39 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` -كل مسار فرعي هو وحدة صغيرة مستقلة بذاتها. يساعد ذلك في إبقاء بدء التشغيل سريعًا -ويمنع مشكلات التبعيات الدائرية. بالنسبة إلى مساعدات الإدخال/البناء الخاصة بالقنوات، -فإن المسار المفضّل هو `openclaw/plugin-sdk/channel-core`؛ واحتفظ بـ `openclaw/plugin-sdk/core` -للسطح الأشمل والمساعدات المشتركة مثل +كل مسار فرعي هو وحدة صغيرة مستقلة بذاتها. وهذا يحافظ على سرعة بدء التشغيل +ويمنع مشكلات التبعيات الدائرية. وبالنسبة إلى مساعدات إدخال/بناء القنوات الخاصة، +فإن المسار المفضل هو `openclaw/plugin-sdk/channel-core`؛ واحتفظ بـ `openclaw/plugin-sdk/core` من أجل +السطح الأشمل الجامع والمساعدات المشتركة مثل `buildChannelConfigSchema`. -لا تُضف أو تعتمد على مسارات ربط مريحة تحمل أسماء موفّرين مثل -`openclaw/plugin-sdk/slack` أو `openclaw/plugin-sdk/discord` أو -`openclaw/plugin-sdk/signal` أو `openclaw/plugin-sdk/whatsapp` أو -مسارات المساعدات ذات العلامات الخاصة بالقنوات. يجب على المكونات الإضافية المضمّنة -تجميع المسارات الفرعية العامة من SDK داخل ملفات `api.ts` أو `runtime-api.ts` -الخاصة بها، ويجب على النواة إما استخدام هذه الملفات المحلية الخاصة بالمكوّن الإضافي -أو إضافة عقد عام ضيق في SDK عندما تكون الحاجة فعلًا عابرة للقنوات. +لا تضف أو تعتمد على طبقات تسهيلية مسماة باسم الموفّر مثل +`openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, +`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`، أو +طبقات مساعدة موسومة باسم القناة. يجب أن تقوم Plugins المجمّعة بتركيب +المسارات الفرعية العامة لـ SDK داخل ملفات `api.ts` أو `runtime-api.ts` الخاصة بها، ويجب على النواة +إما استخدام هذه الملفات المحلية الخاصة بالـ Plugin أو إضافة عقد SDK عام ضيق +عندما تكون الحاجة فعلًا عابرة للقنوات. -لا تزال خريطة التصدير المُولَّدة تحتوي على مجموعة صغيرة من مسارات المساعدات الخاصة -بالمكونات الإضافية المضمّنة مثل `plugin-sdk/feishu` و`plugin-sdk/feishu-setup` -و`plugin-sdk/zalo` و`plugin-sdk/zalo-setup` و`plugin-sdk/matrix*`. توجد هذه -المسارات الفرعية فقط لصيانة المكونات الإضافية المضمّنة والتوافق، ولذلك أُزيلت عمدًا -من الجدول الشائع أدناه وليست مسار الاستيراد الموصى به للمكونات الإضافية الجديدة من -جهات خارجية. +لا تزال خريطة التصدير المولدة تحتوي على مجموعة صغيرة من +طبقات المساعدة الخاصة بالـ Plugins المجمّعة مثل `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, +`plugin-sdk/zalo`, `plugin-sdk/zalo-setup`, و `plugin-sdk/matrix*`. هذه +المسارات الفرعية موجودة فقط لصيانة Plugins المجمّعة والتوافق؛ وهي +مستبعدة عمدًا من الجدول الشائع أدناه وليست مسار الاستيراد الموصى به +لـ Plugins الخارجية الجديدة. ## مرجع المسارات الفرعية -أكثر المسارات الفرعية استخدامًا، مجمّعة حسب الغرض. توجد القائمة الكاملة -المُولَّدة التي تضم أكثر من 200 مسار فرعي في `scripts/lib/plugin-sdk-entrypoints.json`. +أكثر المسارات الفرعية استخدامًا، مجمعة حسب الغرض. وتوجد القائمة الكاملة المولدة التي تضم +أكثر من 200 مسار فرعي في `scripts/lib/plugin-sdk-entrypoints.json`. -لا تزال مسارات المساعدات المحجوزة الخاصة بالمكونات الإضافية المضمّنة تظهر في تلك -القائمة المُولَّدة. تعامل معها على أنها أسطح تنفيذ داخلية/توافقية ما لم تروّج لها -صفحة توثيق صراحةً باعتبارها عامة. +لا تزال المسارات الفرعية المحجوزة لمساعدات Plugins المجمّعة تظهر في تلك القائمة المولدة. +تعامل معها على أنها تفاصيل تنفيذ/أسطح توافق ما لم تقم صفحة توثيق +بترقية أحدها صراحةً إلى سطح عام. -### إدخال المكوّن الإضافي +### إدخال Plugin -| المسار الفرعي | أهم التصديرات | +| Subpath | Key exports | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `plugin-sdk/plugin-entry` | `definePluginEntry` | | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | @@ -77,188 +77,202 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; - | المسار الفرعي | أهم التصديرات | + | Subpath | Key exports | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | | `plugin-sdk/config-schema` | تصدير مخطط Zod الجذري لـ `openclaw.json` (`OpenClawSchema`) | | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`، بالإضافة إلى `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | مساعدات معالج الإعداد المشتركة، ومطالبات قائمة السماح، وبناة حالة الإعداد | + | `plugin-sdk/setup` | مساعدات معالج الإعداد المشتركة، ومطالبات قائمة السماح، ومنشئات حالة الإعداد | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | مساعدات تهيئة/بوابة إجراءات متعددة الحسابات، ومساعدات الرجوع إلى الحساب الافتراضي | + | `plugin-sdk/account-core` | مساعدات إعدادات/بوابة إجراءات متعددة الحسابات، ومساعدات الرجوع إلى الحساب الافتراضي | | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`، ومساعدات تطبيع معرّف الحساب | - | `plugin-sdk/account-resolution` | مساعدات البحث عن الحساب + الرجوع الافتراضي | + | `plugin-sdk/account-resolution` | البحث عن الحساب + مساعدات الرجوع إلى الافتراضي | | `plugin-sdk/account-helpers` | مساعدات ضيقة لقائمة الحسابات/إجراءات الحساب | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | أنواع مخطط تهيئة القناة | - | `plugin-sdk/telegram-command-config` | مساعدات تطبيع/تحقق الأوامر المخصصة في Telegram مع الرجوع إلى العقد المضمّن | + | `plugin-sdk/channel-config-schema` | أنواع مخطط إعدادات القناة | + | `plugin-sdk/telegram-command-config` | مساعدات تطبيع/تحقق الأوامر المخصصة لـ Telegram مع الرجوع إلى العقد المجمّع | + | `plugin-sdk/command-gating` | مساعدات ضيقة لبوابة تفويض الأوامر | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | مساعدات مشتركة لتوجيه الوارد + بناء الغلاف | + | `plugin-sdk/inbound-envelope` | مساعدات مشتركة لبناء المسار الوارد + الغلاف | | `plugin-sdk/inbound-reply-dispatch` | مساعدات مشتركة لتسجيل الوارد وإرساله | | `plugin-sdk/messaging-targets` | مساعدات تحليل/مطابقة الأهداف | | `plugin-sdk/outbound-media` | مساعدات مشتركة لتحميل الوسائط الصادرة | - | `plugin-sdk/outbound-runtime` | مساعدات هوية الإرسال/مفوّض الإرسال الصادر | + | `plugin-sdk/outbound-runtime` | مساعدات هوية/إرسال الصادر | + | `plugin-sdk/poll-runtime` | مساعدات ضيقة لتطبيع الاستطلاعات | | `plugin-sdk/thread-bindings-runtime` | دورة حياة ربط الخيوط ومساعدات المهايئ | - | `plugin-sdk/agent-media-payload` | بانٍ قديم لحمولة وسائط الوكيل | - | `plugin-sdk/conversation-runtime` | مساعدات ربط المحادثة/الخيط، والاقتران، والربط المهيأ | - | `plugin-sdk/runtime-config-snapshot` | مساعد لقطة تهيئة وقت التشغيل | - | `plugin-sdk/runtime-group-policy` | مساعدات حل سياسة المجموعة في وقت التشغيل | - | `plugin-sdk/channel-status` | مساعدات مشتركة للقطات/ملخصات حالة القناة | - | `plugin-sdk/channel-config-primitives` | أوليات ضيقة لمخطط تهيئة القناة | - | `plugin-sdk/channel-config-writes` | مساعدات تفويض كتابة تهيئة القناة | - | `plugin-sdk/channel-plugin-common` | تصديرات تمهيدية مشتركة للمكونات الإضافية للقنوات | - | `plugin-sdk/allowlist-config-edit` | مساعدات قراءة/تحرير تهيئة قائمة السماح | - | `plugin-sdk/group-access` | مساعدات مشتركة لقرارات الوصول إلى المجموعات | - | `plugin-sdk/direct-dm` | مساعدات مشتركة للمصادقة/الحماية الخاصة بالرسائل المباشرة | + | `plugin-sdk/agent-media-payload` | منشئ حمولة وسائط الوكيل القديم | + | `plugin-sdk/conversation-runtime` | مساعدات المحادثة/ربط الخيوط، والاقتران، والربط المهيأ | + | `plugin-sdk/runtime-config-snapshot` | مساعد لقطة إعدادات وقت التشغيل | + | `plugin-sdk/runtime-group-policy` | مساعدات حل سياسة المجموعات في وقت التشغيل | + | `plugin-sdk/channel-status` | مساعدات مشتركة لملخص/لقطة حالة القناة | + | `plugin-sdk/channel-config-primitives` | العناصر الأولية الضيقة لمخطط إعدادات القناة | + | `plugin-sdk/channel-config-writes` | مساعدات تفويض كتابة إعدادات القناة | + | `plugin-sdk/channel-plugin-common` | تصديرات تمهيد Plugin القناة المشتركة | + | `plugin-sdk/allowlist-config-edit` | مساعدات قراءة/تعديل إعدادات قائمة السماح | + | `plugin-sdk/group-access` | مساعدات مشتركة لقرارات وصول المجموعات | + | `plugin-sdk/direct-dm` | مساعدات مشتركة لمصادقة/حماية الرسائل المباشرة | | `plugin-sdk/interactive-runtime` | مساعدات تطبيع/اختزال حمولة الرد التفاعلي | - | `plugin-sdk/channel-inbound` | مساعدات إلغاء الارتداد للوارد، ومطابقة الإشارات، وسياسات الإشارة، ومساعدات الغلاف | - | `plugin-sdk/channel-send-result` | أنواع نتائج الرد | + | `plugin-sdk/channel-inbound` | حاوية توافق لمساعدات إزالة ارتداد الوارد، ومطابقة الإشارة، ومساعدات سياسة الإشارة، ومساعدات الغلاف | + | `plugin-sdk/channel-mention-gating` | مساعدات ضيقة لسياسة الإشارة من دون سطح وقت التشغيل الوارد الأوسع | + | `plugin-sdk/channel-location` | سياق موقع القناة ومساعدات التنسيق | + | `plugin-sdk/channel-logging` | مساعدات تسجيل القناة لحالات إسقاط الوارد وإخفاقات الكتابة/التأكيد | + | `plugin-sdk/channel-send-result` | أنواع نتيجة الرد | | `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` | | `plugin-sdk/channel-targets` | مساعدات تحليل/مطابقة الأهداف | | `plugin-sdk/channel-contract` | أنواع عقد القناة | - | `plugin-sdk/channel-feedback` | ربط الملاحظات/التفاعلات | + | `plugin-sdk/channel-feedback` | توصيل التغذية الراجعة/التفاعلات | | `plugin-sdk/channel-secret-runtime` | مساعدات ضيقة لعقد الأسرار مثل `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`، وأنواع أهداف الأسرار | - - | المسار الفرعي | أهم التصديرات | + + | Subpath | Key exports | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/provider-setup` | مساعدات إعداد منسّقة للموفّرين المحليين/المستضافين ذاتيًا | - | `plugin-sdk/self-hosted-provider-setup` | مساعدات إعداد مركزة للموفّر المستضاف ذاتيًا والمتوافق مع OpenAI | - | `plugin-sdk/cli-backend` | إعدادات CLI الخلفية الافتراضية + ثوابت المراقبة | - | `plugin-sdk/provider-auth-runtime` | مساعدات حل مفتاح API وقت التشغيل للمكونات الإضافية للموفّرين | - | `plugin-sdk/provider-auth-api-key` | مساعدات إعداد/كتابة ملف تعريف مفتاح API مثل `upsertApiKeyProfile` | - | `plugin-sdk/provider-auth-result` | بانٍ قياسي لنتائج مصادقة OAuth | - | `plugin-sdk/provider-auth-login` | مساعدات تسجيل الدخول التفاعلي المشتركة للمكونات الإضافية للموفّرين | + | `plugin-sdk/provider-setup` | مساعدات منسقة لإعداد الموفّرين المحليين/المستضافين ذاتيًا | + | `plugin-sdk/self-hosted-provider-setup` | مساعدات مركزة لإعداد موفّرين مستضافين ذاتيًا متوافقين مع OpenAI | + | `plugin-sdk/cli-backend` | افتراضيات CLI backend + ثوابت watchdog | + | `plugin-sdk/provider-auth-runtime` | مساعدات وقت التشغيل لحل مفاتيح API في Plugins الموفّرين | + | `plugin-sdk/provider-auth-api-key` | مساعدات إعداد/كتابة ملفات تعريف مفاتيح API مثل `upsertApiKeyProfile` | + | `plugin-sdk/provider-auth-result` | منشئ موحد لنتيجة مصادقة OAuth | + | `plugin-sdk/provider-auth-login` | مساعدات تسجيل الدخول التفاعلي المشتركة لـ Plugins الموفّرين | | `plugin-sdk/provider-env-vars` | مساعدات البحث عن متغيرات البيئة لمصادقة الموفّر | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`، وبناة سياسات إعادة التشغيل المشتركة، ومساعدات نقاط نهاية الموفّر، ومساعدات تطبيع معرّف النموذج مثل `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`، ومنشئات سياسة الإعادة المشتركة، ومساعدات نقاط نهاية الموفّر، ومساعدات تطبيع معرّفات النماذج مثل `normalizeNativeXaiModelId` | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | مساعدات عامة لإمكانات HTTP/نقاط نهاية الموفّر | - | `plugin-sdk/provider-web-fetch-contract` | مساعدات ضيقة لعقد تهيئة/اختيار الجلب عبر الويب مثل `enablePluginInConfig` و`WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | مساعدات تسجيل/تخزين مؤقت لموفّر الجلب عبر الويب | - | `plugin-sdk/provider-web-search-config-contract` | مساعدات ضيقة لتهيئة/اعتماد البحث عبر الويب للموفّرين الذين لا يحتاجون إلى ربط تمكين المكوّن الإضافي | - | `plugin-sdk/provider-web-search-contract` | مساعدات ضيقة لعقد تهيئة/اعتماد البحث عبر الويب مثل `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`، وضبط/جلب بيانات الاعتماد ضمن النطاق | - | `plugin-sdk/provider-web-search` | مساعدات وقت التشغيل/التخزين المؤقت/التسجيل لموفّر البحث عبر الويب | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`، وتنظيف مخطط Gemini + التشخيصات، ومساعدات التوافق الخاصة بـ xAI مثل `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-http` | مساعدات عامة لقدرات HTTP/نقطة النهاية الخاصة بالموفّر | + | `plugin-sdk/provider-web-fetch-contract` | مساعدات ضيقة لعقد إعدادات/اختيار web-fetch مثل `enablePluginInConfig` و `WebFetchProviderPlugin` | + | `plugin-sdk/provider-web-fetch` | مساعدات تسجيل/تخزين مؤقت لموفّر web-fetch | + | `plugin-sdk/provider-web-search-config-contract` | مساعدات ضيقة لإعدادات/بيانات اعتماد web-search للموفّرين الذين لا يحتاجون إلى توصيل تمكين Plugin | + | `plugin-sdk/provider-web-search-contract` | مساعدات ضيقة لعقد إعدادات/بيانات اعتماد web-search مثل `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`، وواضعات/قارئات بيانات اعتماد ذات نطاق محدد | + | `plugin-sdk/provider-web-search` | مساعدات وقت التشغيل/التسجيل/التخزين المؤقت لموفّر web-search | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`، وتنظيف مخطط Gemini + التشخيصات، ومساعدات توافق xAI مثل `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | | `plugin-sdk/provider-usage` | `fetchClaudeUsage` وما شابه | | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`، وأنواع مغلفات التدفق، ومساعدات المغلفات المشتركة لـ Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-onboard` | مساعدات تصحيح تهيئة الإعداد الأولي | - | `plugin-sdk/global-singleton` | مساعدات العملية المحلية للمفردات/الخرائط/التخزين المؤقت | + | `plugin-sdk/provider-onboard` | مساعدات تصحيح إعدادات الإعداد الأولي | + | `plugin-sdk/global-singleton` | مساعدات singleton/map/cache محلية على مستوى العملية | - | المسار الفرعي | أهم التصديرات | + | Subpath | Key exports | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`، ومساعدات سجل الأوامر، ومساعدات تفويض المرسل | - | `plugin-sdk/command-status` | بُناة رسائل الأوامر/المساعدة مثل `buildCommandsMessagePaginated` و`buildHelpMessage` | - | `plugin-sdk/approval-auth-runtime` | مساعدات حلّ المعتمِد ومصادقة الإجراءات داخل نفس الدردشة | - | `plugin-sdk/approval-client-runtime` | مساعدات ملف التعريف/المرشّح للموافقة على التنفيذ الأصلي | - | `plugin-sdk/approval-delivery-runtime` | مهايئات إمكانات/تسليم الموافقة الأصلية | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`، ومساعدات سجل الأوامر، ومساعدات تفويض المُرسِل | + | `plugin-sdk/command-status` | منشئات رسائل الأوامر/المساعدة مثل `buildCommandsMessagePaginated` و `buildHelpMessage` | + | `plugin-sdk/approval-auth-runtime` | مساعدات حل الموافقين ومصادقة الإجراءات داخل الدردشة نفسها | + | `plugin-sdk/approval-client-runtime` | مساعدات ملفات تعريف/تصفية موافقات التنفيذ الأصلية | + | `plugin-sdk/approval-delivery-runtime` | مهايئات قدرات/تسليم الموافقات الأصلية | | `plugin-sdk/approval-gateway-runtime` | مساعد مشترك لحل Gateway الخاص بالموافقات | - | `plugin-sdk/approval-handler-adapter-runtime` | مساعدات خفيفة لتحميل مهايئ الموافقة الأصلية لنقاط إدخال القنوات السريعة | - | `plugin-sdk/approval-handler-runtime` | مساعدات أشمل لوقت تشغيل معالج الموافقة؛ يُفضَّل استخدام مسارات المهايئ/Gateway الأضيق عندما تكون كافية | - | `plugin-sdk/approval-native-runtime` | مساعدات الهدف الأصلي للموافقة + ربط الحساب | - | `plugin-sdk/approval-reply-runtime` | مساعدات حمولة الرد الخاصة بموافقات التنفيذ/Plugin | - | `plugin-sdk/command-auth-native` | مساعدات المصادقة الأصلية للأوامر + هدف الجلسة الأصلي | + | `plugin-sdk/approval-handler-adapter-runtime` | مساعدات خفيفة لتحميل مهايئات الموافقات الأصلية لنقاط إدخال القنوات السريعة | + | `plugin-sdk/approval-handler-runtime` | مساعدات أوسع لوقت تشغيل معالج الموافقات؛ فضّل طبقات المهايئ/‏Gateway الأضيق عندما تكون كافية | + | `plugin-sdk/approval-native-runtime` | مساعدات الهدف الأصلي للموافقات + ربط الحساب | + | `plugin-sdk/approval-reply-runtime` | مساعدات حمولة رد موافقات التنفيذ/Plugin | + | `plugin-sdk/command-auth-native` | مساعدات مصادقة الأوامر الأصلية + هدف الجلسة الأصلي | | `plugin-sdk/command-detection` | مساعدات مشتركة لاكتشاف الأوامر | | `plugin-sdk/command-surface` | مساعدات تطبيع جسم الأمر وسطح الأمر | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | مساعدات ضيقة لتجميع عقود الأسرار لأسطح أسرار القنوات/Plugin | - | `plugin-sdk/secret-ref-runtime` | `coerceSecretRef` الضيق ومساعدات كتابة SecretRef لتحليل عقود الأسرار/التهيئة | - | `plugin-sdk/security-runtime` | مساعدات مشتركة للثقة، وتقييد الرسائل المباشرة، والمحتوى الخارجي، وتجميع الأسرار | - | `plugin-sdk/ssrf-policy` | مساعدات سياسة SSRF لقائمة السماح بالمضيفين والشبكات الخاصة | - | `plugin-sdk/ssrf-runtime` | مساعدات المرسِل المثبّت، وfetch المحمي من SSRF، وسياسات SSRF | - | `plugin-sdk/secret-input` | مساعدات تحليل إدخال الأسرار | - | `plugin-sdk/webhook-ingress` | مساعدات الطلب/الهدف الخاصة بـ Webhook | - | `plugin-sdk/webhook-request-guards` | مساعدات حجم جسم الطلب/المهلة الزمنية | + | `plugin-sdk/channel-secret-runtime` | مساعدات ضيقة لتجميع عقود الأسرار لأسطح أسرار القنوات/Plugins | + | `plugin-sdk/secret-ref-runtime` | مساعدات ضيقة لـ `coerceSecretRef` وأنواع SecretRef لتحليل عقود الأسرار/الإعدادات | + | `plugin-sdk/security-runtime` | مساعدات مشتركة للثقة، وبوابة الرسائل المباشرة، والمحتوى الخارجي، وتجميع الأسرار | + | `plugin-sdk/ssrf-policy` | مساعدات سياسة SSRF الخاصة بقائمة سماح المضيف والشبكة الخاصة | + | `plugin-sdk/ssrf-dispatcher` | مساعدات ضيقة لـ pinned-dispatcher من دون سطح وقت تشغيل البنية الأوسع | + | `plugin-sdk/ssrf-runtime` | مساعدات pinned-dispatcher وfetch المحمي بـ SSRF وسياسة SSRF | + | `plugin-sdk/secret-input` | مساعدات تحليل مدخلات الأسرار | + | `plugin-sdk/webhook-ingress` | مساعدات طلب/هدف Webhook | + | `plugin-sdk/webhook-request-guards` | مساعدات حجم جسم الطلب/المهلة | - | المسار الفرعي | أهم التصديرات | + | Subpath | Key exports | | --- | --- | - | `plugin-sdk/runtime` | مساعدات عامة لوقت التشغيل/التسجيل/النسخ الاحتياطي/تثبيت المكونات الإضافية | - | `plugin-sdk/runtime-env` | مساعدات ضيقة لبيئة وقت التشغيل، والمسجل، والمهلة الزمنية، وإعادة المحاولة، والتراجع التدريجي | + | `plugin-sdk/runtime` | مساعدات واسعة لوقت التشغيل/التسجيل/النسخ الاحتياطي/تثبيت Plugins | + | `plugin-sdk/runtime-env` | مساعدات ضيقة لبيئة وقت التشغيل، والمسجل، والمهلة، وإعادة المحاولة، والتراجع التدريجي | | `plugin-sdk/channel-runtime-context` | مساعدات عامة لتسجيل سياق وقت تشغيل القناة والبحث عنه | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | مساعدات مشتركة للأوامر/الخطافات/HTTP/التفاعل الخاصة بـ Plugin | - | `plugin-sdk/hook-runtime` | مساعدات مشتركة لخط أنابيب Webhook/الخطافات الداخلية | - | `plugin-sdk/lazy-runtime` | مساعدات الاستيراد/الربط الكسول لوقت التشغيل مثل `createLazyRuntimeModule` و`createLazyRuntimeMethod` و`createLazyRuntimeSurface` | + | `plugin-sdk/plugin-runtime` | مساعدات مشتركة للأوامر/الخطافات/HTTP/التفاعل الخاصة بالـ Plugin | + | `plugin-sdk/hook-runtime` | مساعدات مشتركة لخطافات Webhook/الخطافات الداخلية | + | `plugin-sdk/lazy-runtime` | مساعدات الاستيراد/الربط الكسول لوقت التشغيل مثل `createLazyRuntimeModule` و `createLazyRuntimeMethod` و `createLazyRuntimeSurface` | | `plugin-sdk/process-runtime` | مساعدات تنفيذ العمليات | | `plugin-sdk/cli-runtime` | مساعدات تنسيق CLI والانتظار والإصدار | | `plugin-sdk/gateway-runtime` | مساعدات عميل Gateway وتصحيح حالة القناة | - | `plugin-sdk/config-runtime` | مساعدات تحميل/كتابة التهيئة | - | `plugin-sdk/telegram-command-config` | تطبيع اسم/وصف أوامر Telegram وفحوصات التكرار/التعارض، حتى عندما لا يكون سطح عقد Telegram المضمّن متاحًا | - | `plugin-sdk/approval-runtime` | مساعدات موافقات التنفيذ/Plugin، وبناة إمكانات الموافقة، ومساعدات المصادقة/الملف التعريفي، ومساعدات التوجيه/وقت التشغيل الأصلية | - | `plugin-sdk/reply-runtime` | مساعدات مشتركة لوقت تشغيل الوارد/الرد، والتجزئة، والإرسال، وHeartbeat، ومخطط الرد | + | `plugin-sdk/config-runtime` | مساعدات تحميل/كتابة الإعدادات | + | `plugin-sdk/telegram-command-config` | تطبيع اسم/وصف أوامر Telegram والتحقق من التكرار/التعارض، حتى عندما لا يكون سطح عقد Telegram المجمّع متاحًا | + | `plugin-sdk/text-autolink-runtime` | اكتشاف الروابط التلقائية لمراجع الملفات من دون حاوية text-runtime الأوسع | + | `plugin-sdk/approval-runtime` | مساعدات موافقات التنفيذ/Plugin، ومنشئات قدرات الموافقة، ومساعدات المصادقة/الملف التعريفي، ومساعدات التوجيه/وقت التشغيل الأصلية | + | `plugin-sdk/reply-runtime` | مساعدات مشتركة لوقت تشغيل الوارد/الرد، والتقسيم، والإرسال، وHeartbeat، ومخطط الرد | | `plugin-sdk/reply-dispatch-runtime` | مساعدات ضيقة لإرسال/إنهاء الرد | - | `plugin-sdk/reply-history` | مساعدات مشتركة لسجل الرد ضمن نافذة قصيرة مثل `buildHistoryContext` و`recordPendingHistoryEntry` و`clearHistoryEntriesIfEnabled` | + | `plugin-sdk/reply-history` | مساعدات مشتركة لسجل الردود ضمن نافذة قصيرة مثل `buildHistoryContext` و `recordPendingHistoryEntry` و `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | مساعدات ضيقة لتجزئة النص/Markdown | + | `plugin-sdk/reply-chunking` | مساعدات ضيقة لتقسيم النص/Markdown | | `plugin-sdk/session-store-runtime` | مساعدات مسار مخزن الجلسة + `updated-at` | - | `plugin-sdk/state-paths` | مساعدات مسارات دليل الحالة/OAuth | - | `plugin-sdk/routing` | مساعدات التوجيه/مفتاح الجلسة/ربط الحساب مثل `resolveAgentRoute` و`buildAgentSessionKey` و`resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | مساعدات مشتركة لملخص حالة القناة/الحساب، والقيم الافتراضية لحالة وقت التشغيل، ومساعدات بيانات التعريف الخاصة بالمشكلات | - | `plugin-sdk/target-resolver-runtime` | مساعدات مشتركة لحلّ الأهداف | - | `plugin-sdk/string-normalization-runtime` | مساعدات تطبيع slug/السلاسل النصية | + | `plugin-sdk/state-paths` | مساعدات مسارات الحالة/دليل OAuth | + | `plugin-sdk/routing` | مساعدات ربط المسار/مفتاح الجلسة/الحساب مثل `resolveAgentRoute` و `buildAgentSessionKey` و `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | مساعدات مشتركة لملخص حالة القناة/الحساب، وافتراضيات حالة وقت التشغيل، ومساعدات بيانات تعريف المشكلات | + | `plugin-sdk/target-resolver-runtime` | مساعدات مشتركة لحل الأهداف | + | `plugin-sdk/string-normalization-runtime` | مساعدات تطبيع slug/السلاسل | | `plugin-sdk/request-url` | استخراج عناوين URL النصية من مدخلات شبيهة بـ fetch/request | - | `plugin-sdk/run-command` | مشغّل أوامر مؤقّت بنتائج `stdout`/`stderr` مطبّعة | - | `plugin-sdk/param-readers` | قارئات معلمات شائعة للأدوات/CLI | + | `plugin-sdk/run-command` | مشغّل أوامر موقّت مع نتائج stdout/stderr مطبّعة | + | `plugin-sdk/param-readers` | قارئات المعلمات الشائعة للأدوات/CLI | | `plugin-sdk/tool-payload` | استخراج الحمولات المطبّعة من كائنات نتائج الأدوات | - | `plugin-sdk/tool-send` | استخراج حقول هدف الإرسال القياسية من وسائط الأدوات | + | `plugin-sdk/tool-send` | استخراج حقول هدف الإرسال القياسية من وسائط الأداة | | `plugin-sdk/temp-path` | مساعدات مشتركة لمسارات التنزيل المؤقت | - | `plugin-sdk/logging-core` | مساعدات مسجل النظام الفرعي والتنقيح | + | `plugin-sdk/logging-core` | مساعدات مسجل النظام الفرعي وإخفاء البيانات الحساسة | | `plugin-sdk/markdown-table-runtime` | مساعدات أوضاع جداول Markdown | | `plugin-sdk/json-store` | مساعدات صغيرة لقراءة/كتابة حالة JSON | - | `plugin-sdk/file-lock` | مساعدات إعادة الدخول لقفل الملفات | - | `plugin-sdk/persistent-dedupe` | مساعدات ذاكرة التخزين المؤقت لإزالة التكرار المدعومة بالقرص | - | `plugin-sdk/acp-runtime` | مساعدات وقت تشغيل ACP/الجلسة وإرسال الرد | - | `plugin-sdk/agent-config-primitives` | أوليات ضيقة لمخطط تهيئة وقت تشغيل الوكيل | + | `plugin-sdk/file-lock` | مساعدات قفل الملفات القابلة لإعادة الدخول | + | `plugin-sdk/persistent-dedupe` | مساعدات ذاكرة التخزين المؤقت لإزالة التكرار المعتمدة على القرص | + | `plugin-sdk/acp-runtime` | مساعدات ACP لوقت التشغيل/الجلسة وإرسال الردود | + | `plugin-sdk/acp-binding-resolve-runtime` | حل ربط ACP للقراءة فقط من دون استيرادات بدء دورة الحياة | + | `plugin-sdk/agent-config-primitives` | عناصر أولية ضيقة لمخطط إعدادات وقت تشغيل الوكيل | | `plugin-sdk/boolean-param` | قارئ مرن لمعلمات boolean | - | `plugin-sdk/dangerous-name-runtime` | مساعدات حل مطابقة الأسماء الخطرة | - | `plugin-sdk/device-bootstrap` | مساعدات تهيئة الجهاز ورمز الاقتران | - | `plugin-sdk/extension-shared` | أوليات مساعدة مشتركة للقناة السلبية، والحالة، والوكيل المحيطي | - | `plugin-sdk/models-provider-runtime` | مساعدات الرد الخاصة بأمر `/models`/الموفّر | - | `plugin-sdk/skill-commands-runtime` | مساعدات عرض أوامر Skills | - | `plugin-sdk/native-command-registry` | مساعدات السجل/البناء/التسلسل للأوامر الأصلية | - | `plugin-sdk/agent-harness` | سطح تجريبي موثوق لـ Plugin لأحزمة الوكيل منخفضة المستوى: أنواع الحزام، ومساعدات التوجيه/الإيقاف للتشغيل النشط، وجسر أدوات OpenClaw، وأدوات نتائج المحاولات | + | `plugin-sdk/dangerous-name-runtime` | مساعدات حل مطابقة الأسماء الخطِرة | + | `plugin-sdk/device-bootstrap` | مساعدات التمهيد للجهاز ورمز الاقتران | + | `plugin-sdk/extension-shared` | عناصر أولية مشتركة لمساعدات القنوات السلبية والحالة والوكيل المحيط | + | `plugin-sdk/models-provider-runtime` | مساعدات الرد الخاصة بالأمر `/models`/الموفّر | + | `plugin-sdk/skill-commands-runtime` | مساعدات سرد أوامر Skills | + | `plugin-sdk/native-command-registry` | مساعدات بناء/تسلسل/سجل الأوامر الأصلية | + | `plugin-sdk/agent-harness` | سطح تجريبي لـ Plugin موثوق للحزم منخفضة المستوى الخاصة بالوكيل: أنواع الحزم، ومساعدات توجيه/إيقاف التشغيل النشط، ومساعدات جسر أدوات OpenClaw، وأدوات نتائج المحاولات | | `plugin-sdk/provider-zai-endpoint` | مساعدات اكتشاف نقاط نهاية Z.A.I | | `plugin-sdk/infra-runtime` | مساعدات أحداث النظام/Heartbeat | | `plugin-sdk/collection-runtime` | مساعدات صغيرة لذاكرة تخزين مؤقت محدودة | - | `plugin-sdk/diagnostic-runtime` | مساعدات الأعلام والأحداث التشخيصية | - | `plugin-sdk/error-runtime` | مساعدات رسم الأخطاء، والتنسيق، وتصنيف الأخطاء المشتركة، و`isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | مساعدات fetch المغلف، والوكيل، والبحث المثبّت | + | `plugin-sdk/diagnostic-runtime` | مساعدات العلامات والأحداث التشخيصية | + | `plugin-sdk/error-runtime` | مساعدات مخطط الأخطاء والتنسيق وتصنيف الأخطاء المشتركة، و `isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | مساعدات fetch الملتفة والوكيل والبحث المثبّت | + | `plugin-sdk/runtime-fetch` | fetch خاص بوقت التشغيل ومدرك للـ dispatcher من دون استيرادات proxy/guarded-fetch | + | `plugin-sdk/response-limit-runtime` | قارئ محدود لجسم الاستجابة من دون سطح وقت تشغيل الوسائط الأوسع | + | `plugin-sdk/session-binding-runtime` | حالة ربط المحادثة الحالية من دون توجيه الربط المهيأ أو مخازن الاقتران | + | `plugin-sdk/session-store-runtime` | مساعدات قراءة مخزن الجلسة من دون استيرادات واسعة لكتابة/صيانة الإعدادات | + | `plugin-sdk/context-visibility-runtime` | حل رؤية السياق وتصفية السياق الإضافي من دون استيرادات إعدادات/أمان واسعة | + | `plugin-sdk/string-coerce-runtime` | مساعدات ضيقة لإجبار/تطبيع السجلات البدائية والسلاسل من دون استيرادات Markdown/التسجيل | | `plugin-sdk/host-runtime` | مساعدات تطبيع اسم المضيف ومضيف SCP | - | `plugin-sdk/retry-runtime` | مساعدات تهيئة إعادة المحاولة ومشغّل إعادة المحاولة | - | `plugin-sdk/agent-runtime` | مساعدات دليل الوكيل/الهوية/مساحة العمل | - | `plugin-sdk/directory-runtime` | الاستعلام عن الدليل المعتمد على التهيئة/إزالة التكرار | + | `plugin-sdk/retry-runtime` | مساعدات إعدادات إعادة المحاولة ومشغّل إعادة المحاولة | + | `plugin-sdk/agent-runtime` | مساعدات دليل/هوية/مساحة عمل الوكيل | + | `plugin-sdk/directory-runtime` | استعلام/إزالة تكرار الأدلة المعتمد على الإعدادات | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | - | المسار الفرعي | أهم التصديرات | + | Subpath | Key exports | | --- | --- | - | `plugin-sdk/media-runtime` | مساعدات مشتركة لجلب/تحويل/تخزين الوسائط بالإضافة إلى بُناة حمولات الوسائط | - | `plugin-sdk/media-generation-runtime` | مساعدات مشتركة للتجاوز عند الفشل في توليد الوسائط، واختيار المرشحين، ورسائل النماذج المفقودة | - | `plugin-sdk/media-understanding` | أنواع موفّر فهم الوسائط بالإضافة إلى تصديرات المساعدات الخاصة بالصور/الصوت الموجّهة للموفّرين | - | `plugin-sdk/text-runtime` | مساعدات مشتركة للنص/Markdown/التسجيل مثل إزالة النص المرئي للمساعد، ومساعدات العرض/التجزئة/الجداول في Markdown، ومساعدات التنقيح، ومساعدات وسم التوجيهات، وأدوات النص الآمن | - | `plugin-sdk/text-chunking` | مساعد تجزئة النص الصادر | - | `plugin-sdk/speech` | أنواع موفّر الكلام بالإضافة إلى التوجيهات، والسجل، ومساعدات التحقق الموجّهة للموفّرين | - | `plugin-sdk/speech-core` | أنواع موفّر الكلام المشتركة، والسجل، والتوجيهات، ومساعدات التطبيع | - | `plugin-sdk/realtime-transcription` | أنواع موفّر النسخ الفوري ومساعدات السجل | - | `plugin-sdk/realtime-voice` | أنواع موفّر الصوت الفوري ومساعدات السجل | - | `plugin-sdk/image-generation` | أنواع موفّر توليد الصور | - | `plugin-sdk/image-generation-core` | الأنواع المشتركة لتوليد الصور، ومساعدات التجاوز عند الفشل، والمصادقة، والسجل | + | `plugin-sdk/media-runtime` | مساعدات مشتركة لجلب/تحويل/تخزين الوسائط بالإضافة إلى منشئات حمولة الوسائط | + | `plugin-sdk/media-generation-runtime` | مساعدات مشتركة للتعامل مع الإخفاق البديل في توليد الوسائط، واختيار المرشحين، ورسائل النماذج المفقودة | + | `plugin-sdk/media-understanding` | أنواع موفّري فهم الوسائط بالإضافة إلى تصديرات المساعدات الخاصة بالصور/الصوت للموجّهة إلى الموفّرين | + | `plugin-sdk/text-runtime` | مساعدات مشتركة للنص/Markdown/التسجيل مثل إزالة النص المرئي للمساعد، ومساعدات عرض/تقسيم/جداول Markdown، ومساعدات إخفاء البيانات الحساسة، ومساعدات وسوم التوجيه، وأدوات النص الآمن | + | `plugin-sdk/text-chunking` | مساعد تقسيم النص الصادر | + | `plugin-sdk/speech` | أنواع موفّري الكلام بالإضافة إلى المساعدات الخاصة بالموجّهة إلى الموفّرين للتوجيه والسجل والتحقق | + | `plugin-sdk/speech-core` | مساعدات مشتركة لأنواع موفّري الكلام والسجل والتوجيه والتطبيع | + | `plugin-sdk/realtime-transcription` | أنواع موفّري النسخ الفوري ومساعدات السجل | + | `plugin-sdk/realtime-voice` | أنواع موفّري الصوت الفوري ومساعدات السجل | + | `plugin-sdk/image-generation` | أنواع موفّري توليد الصور | + | `plugin-sdk/image-generation-core` | مساعدات مشتركة لأنواع توليد الصور، والإخفاق البديل، والمصادقة، والسجل | | `plugin-sdk/music-generation` | أنواع موفّر/طلب/نتيجة توليد الموسيقى | - | `plugin-sdk/music-generation-core` | الأنواع المشتركة لتوليد الموسيقى، ومساعدات التجاوز عند الفشل، والبحث عن الموفّر، وتحليل مرجع النموذج | + | `plugin-sdk/music-generation-core` | مساعدات مشتركة لأنواع توليد الموسيقى، والإخفاق البديل، والبحث عن الموفّر، وتحليل مرجع النموذج | | `plugin-sdk/video-generation` | أنواع موفّر/طلب/نتيجة توليد الفيديو | - | `plugin-sdk/video-generation-core` | الأنواع المشتركة لتوليد الفيديو، ومساعدات التجاوز عند الفشل، والبحث عن الموفّر، وتحليل مرجع النموذج | - | `plugin-sdk/webhook-targets` | سجل أهداف Webhook ومساعدات تثبيت المسارات | + | `plugin-sdk/video-generation-core` | مساعدات مشتركة لأنواع توليد الفيديو، والإخفاق البديل، والبحث عن الموفّر، وتحليل مرجع النموذج | + | `plugin-sdk/webhook-targets` | مساعدات سجل أهداف Webhook وتثبيت المسارات | | `plugin-sdk/webhook-path` | مساعدات تطبيع مسار Webhook | | `plugin-sdk/web-media` | مساعدات مشتركة لتحميل الوسائط البعيدة/المحلية | | `plugin-sdk/zod` | إعادة تصدير `zod` لمستهلكي Plugin SDK | @@ -266,102 +280,101 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; - | المسار الفرعي | أهم التصديرات | + | Subpath | Key exports | | --- | --- | - | `plugin-sdk/memory-core` | سطح مساعد memory-core المضمّن لمساعدات المدير/التهيئة/الملف/CLI | - | `plugin-sdk/memory-core-engine-runtime` | واجهة وقت تشغيل لفهرسة/بحث الذاكرة | + | `plugin-sdk/memory-core` | سطح مساعد memory-core المجمّع لمساعدات المدير/الإعدادات/الملفات/CLI | + | `plugin-sdk/memory-core-engine-runtime` | واجهة وقت التشغيل لفهرسة/بحث الذاكرة | | `plugin-sdk/memory-core-host-engine-foundation` | تصديرات محرك الأساس لمضيف الذاكرة | - | `plugin-sdk/memory-core-host-engine-embeddings` | عقود تضمينات مضيف الذاكرة، والوصول إلى السجل، والموفّر المحلي، ومساعدات الدفعات/المهام البعيدة العامة | + | `plugin-sdk/memory-core-host-engine-embeddings` | عقود تضمين مضيف الذاكرة، والوصول إلى السجل، والموفّر المحلي، والمساعدات العامة للدُفعات/البعيد | | `plugin-sdk/memory-core-host-engine-qmd` | تصديرات محرك QMD لمضيف الذاكرة | | `plugin-sdk/memory-core-host-engine-storage` | تصديرات محرك التخزين لمضيف الذاكرة | - | `plugin-sdk/memory-core-host-multimodal` | مساعدات متعددة الوسائط لمضيف الذاكرة | + | `plugin-sdk/memory-core-host-multimodal` | مساعدات الوسائط المتعددة لمضيف الذاكرة | | `plugin-sdk/memory-core-host-query` | مساعدات الاستعلام لمضيف الذاكرة | | `plugin-sdk/memory-core-host-secret` | مساعدات الأسرار لمضيف الذاكرة | - | `plugin-sdk/memory-core-host-events` | مساعدات دفتر يوميات الأحداث لمضيف الذاكرة | + | `plugin-sdk/memory-core-host-events` | مساعدات سجل أحداث مضيف الذاكرة | | `plugin-sdk/memory-core-host-status` | مساعدات حالة مضيف الذاكرة | | `plugin-sdk/memory-core-host-runtime-cli` | مساعدات وقت تشغيل CLI لمضيف الذاكرة | | `plugin-sdk/memory-core-host-runtime-core` | مساعدات وقت التشغيل الأساسية لمضيف الذاكرة | | `plugin-sdk/memory-core-host-runtime-files` | مساعدات الملفات/وقت التشغيل لمضيف الذاكرة | - | `plugin-sdk/memory-host-core` | اسم بديل محايد تجاه المورّد لمساعدات وقت التشغيل الأساسية لمضيف الذاكرة | - | `plugin-sdk/memory-host-events` | اسم بديل محايد تجاه المورّد لمساعدات دفتر يوميات الأحداث لمضيف الذاكرة | - | `plugin-sdk/memory-host-files` | اسم بديل محايد تجاه المورّد لمساعدات الملفات/وقت التشغيل لمضيف الذاكرة | - | `plugin-sdk/memory-host-markdown` | مساعدات Markdown المُدار المشتركة للمكونات الإضافية المرتبطة بالذاكرة | - | `plugin-sdk/memory-host-search` | واجهة Active Memory لوقت التشغيل للوصول إلى مدير البحث | - | `plugin-sdk/memory-host-status` | اسم بديل محايد تجاه المورّد لمساعدات حالة مضيف الذاكرة | - | `plugin-sdk/memory-lancedb` | سطح مساعد memory-lancedb المضمّن | + | `plugin-sdk/memory-host-core` | اسم بديل مستقل عن المورّد لمساعدات وقت التشغيل الأساسية لمضيف الذاكرة | + | `plugin-sdk/memory-host-events` | اسم بديل مستقل عن المورّد لمساعدات سجل أحداث مضيف الذاكرة | + | `plugin-sdk/memory-host-files` | اسم بديل مستقل عن المورّد لمساعدات الملفات/وقت التشغيل لمضيف الذاكرة | + | `plugin-sdk/memory-host-markdown` | مساعدات managed-markdown المشتركة للـ Plugins المجاورة للذاكرة | + | `plugin-sdk/memory-host-search` | واجهة وقت تشغيل Active Memory للوصول إلى مدير البحث | + | `plugin-sdk/memory-host-status` | اسم بديل مستقل عن المورّد لمساعدات حالة مضيف الذاكرة | + | `plugin-sdk/memory-lancedb` | سطح مساعد memory-lancedb المجمّع | - - | العائلة | المسارات الفرعية الحالية | الاستخدام المقصود | + + | Family | Current subpaths | Intended use | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | مساعدات دعم Plugin المضمّن للمتصفح (`browser-support` يبقى حزمة التوافق) | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | سطح المساعدة/وقت التشغيل المضمّن لـ Matrix | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | سطح المساعدة/وقت التشغيل المضمّن لـ LINE | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | سطح المساعدة المضمّن لـ IRC | - | مساعدات خاصة بالقنوات | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | مسارات توافق/مساعدة مضمّنة للقنوات | - | مساعدات خاصة بالمصادقة/Plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | مسارات مساعدة مضمّنة للميزات/Plugin؛ يصدّر `plugin-sdk/github-copilot-token` حاليًا `DEFAULT_COPILOT_API_BASE_URL` و`deriveCopilotApiBaseUrlFromToken` و`resolveCopilotApiToken` | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | مساعدات دعم Plugin Browser المجمّع (`browser-support` تبقى حاوية التوافق) | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | سطح المساعد/وقت التشغيل المجمّع لـ Matrix | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | سطح المساعد/وقت التشغيل المجمّع لـ LINE | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | سطح المساعد المجمّع لـ IRC | + | مساعدات خاصة بالقنوات | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | طبقات توافق/مساعدة القنوات المجمّعة | + | مساعدات خاصة بالمصادقة/Plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | طبقات مساعدات الميزات/Plugins المجمّعة؛ يصدّر `plugin-sdk/github-copilot-token` حاليًا `DEFAULT_COPILOT_API_BASE_URL` و `deriveCopilotApiBaseUrlFromToken` و `resolveCopilotApiToken` | -## API التسجيل +## واجهة برمجة تطبيقات التسجيل يتلقى رد النداء `register(api)` كائن `OpenClawPluginApi` بهذه الأساليب: ### تسجيل القدرات -| الأسلوب | ما الذي يسجله | -| ------------------------------------------------ | -------------------------------- | -| `api.registerProvider(...)` | استدلال النص (LLM) | -| `api.registerAgentHarness(...)` | منفّذ وكيل منخفض المستوى تجريبي | -| `api.registerCliBackend(...)` | واجهة CLI خلفية محلية للاستدلال | -| `api.registerChannel(...)` | قناة مراسلة | -| `api.registerSpeechProvider(...)` | تحويل النص إلى كلام / توليف STT | -| `api.registerRealtimeTranscriptionProvider(...)` | نسخ فوري متدفق | -| `api.registerRealtimeVoiceProvider(...)` | جلسات صوت فوري ثنائية الاتجاه | -| `api.registerMediaUnderstandingProvider(...)` | تحليل الصور/الصوت/الفيديو | +| Method | What it registers | +| ------------------------------------------------ | ------------------------------------- | +| `api.registerProvider(...)` | الاستدلال النصي (LLM) | +| `api.registerAgentHarness(...)` | مُنفّذ وكيل منخفض المستوى تجريبي | +| `api.registerCliBackend(...)` | CLI backend محلي للاستدلال | +| `api.registerChannel(...)` | قناة مراسلة | +| `api.registerSpeechProvider(...)` | تحويل النص إلى كلام / تركيب STT | +| `api.registerRealtimeTranscriptionProvider(...)` | النسخ الفوري المتدفق | +| `api.registerRealtimeVoiceProvider(...)` | جلسات الصوت الفوري ثنائية الاتجاه | +| `api.registerMediaUnderstandingProvider(...)` | تحليل الصور/الصوت/الفيديو | | `api.registerImageGenerationProvider(...)` | توليد الصور | -| `api.registerMusicGenerationProvider(...)` | توليد الموسيقى | -| `api.registerVideoGenerationProvider(...)` | توليد الفيديو | -| `api.registerWebFetchProvider(...)` | موفّر جلب / كشط الويب | -| `api.registerWebSearchProvider(...)` | البحث على الويب | +| `api.registerMusicGenerationProvider(...)` | توليد الموسيقى | +| `api.registerVideoGenerationProvider(...)` | توليد الفيديو | +| `api.registerWebFetchProvider(...)` | موفّر جلب / كشط الويب | +| `api.registerWebSearchProvider(...)` | بحث الويب | ### الأدوات والأوامر -| الأسلوب | ما الذي يسجله | +| Method | What it registers | | ------------------------------- | --------------------------------------------- | -| `api.registerTool(tool, opts?)` | أداة وكيل (مطلوبة أو `{ optional: true }`) | -| `api.registerCommand(def)` | أمر مخصص (يتجاوز LLM) | +| `api.registerTool(tool, opts?)` | أداة وكيل (مطلوبة أو `{ optional: true }`) | +| `api.registerCommand(def)` | أمر مخصص (يتجاوز LLM) | ### البنية التحتية -| الأسلوب | ما الذي يسجله | -| ---------------------------------------------- | ----------------------------------- | -| `api.registerHook(events, handler, opts?)` | خطاف أحداث | -| `api.registerHttpRoute(params)` | نقطة نهاية HTTP لـ Gateway | -| `api.registerGatewayMethod(name, handler)` | أسلوب RPC لـ Gateway | -| `api.registerCli(registrar, opts?)` | أمر فرعي في CLI | -| `api.registerService(service)` | خدمة في الخلفية | -| `api.registerInteractiveHandler(registration)` | معالج تفاعلي | +| Method | What it registers | +| ---------------------------------------------- | --------------------------------------- | +| `api.registerHook(events, handler, opts?)` | خطاف أحداث | +| `api.registerHttpRoute(params)` | نقطة نهاية HTTP لـ Gateway | +| `api.registerGatewayMethod(name, handler)` | أسلوب Gateway RPC | +| `api.registerCli(registrar, opts?)` | أمر فرعي في CLI | +| `api.registerService(service)` | خدمة في الخلفية | +| `api.registerInteractiveHandler(registration)` | معالج تفاعلي | | `api.registerMemoryPromptSupplement(builder)` | قسم إضافي في المطالبة مجاور للذاكرة | -| `api.registerMemoryCorpusSupplement(adapter)` | متن إضافي للبحث/القراءة في الذاكرة | +| `api.registerMemoryCorpusSupplement(adapter)` | Corpus إضافي لبحث/قراءة الذاكرة | تظل مساحات أسماء الإدارة الأساسية المحجوزة (`config.*`, `exec.approvals.*`, `wizard.*`, -`update.*`) دائمًا `operator.admin` حتى إذا حاول Plugin تعيين نطاق أضيق -لأسلوب Gateway. استخدم بادئات خاصة بـ Plugin -للأساليب التي يملكها Plugin. +`update.*`) دائمًا `operator.admin`، حتى إذا حاول Plugin تعيين +نطاق أضيق لأسلوب Gateway. ويفضَّل استخدام بادئات خاصة بالـ Plugin من أجل +الأساليب المملوكة للـ Plugin. ### بيانات تعريف تسجيل CLI -يقبل `api.registerCli(registrar, opts?)` نوعين من بيانات التعريف عالية المستوى: +يقبل `api.registerCli(registrar, opts?)` نوعين من بيانات التعريف العليا: -- `commands`: جذور أوامر صريحة يملكها المسجِّل -- `descriptors`: واصفات أوامر وقت التحليل المستخدمة لمساعدة CLI الجذرية، - والتوجيه، وتسجيل CLI الكسول للمكوّنات الإضافية +- `commands`: جذور أوامر صريحة يملكها المسجل +- `descriptors`: واصفات أوامر وقت التحليل المستخدمة في مساعدة CLI الجذرية، + والتوجيه، وتسجيل CLI الكسول للـ Plugin -إذا كنت تريد أن يبقى أمر Plugin محمّلًا بكسل في مسار CLI الجذري العادي، -فقدّم `descriptors` تغطي كل جذر أمر عالي المستوى يكشفه -ذلك المسجِّل. +إذا كنت تريد أن يظل أمر Plugin محمّلًا بشكل كسول في مسار CLI الجذري العادي، +فقدّم `descriptors` تغطي كل جذر أمر علوي يعرّضه ذلك المسجل. ```typescript api.registerCli( @@ -373,7 +386,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "إدارة حسابات Matrix، والتحقق، والأجهزة، وحالة الملف الشخصي", + description: "إدارة حسابات Matrix والتحقق والأجهزة وحالة الملف التعريفي", hasSubcommands: true, }, ], @@ -382,136 +395,133 @@ api.registerCli( ``` استخدم `commands` بمفرده فقط عندما لا تحتاج إلى تسجيل CLI جذري كسول. -لا يزال مسار التوافق المتعجل هذا مدعومًا، لكنه لا يثبت -عناصر نائبة مدعومة بواصفات للتحميل الكسول في وقت التحليل. +لا يزال مسار التوافق eager هذا مدعومًا، لكنه لا يثبت +عناصر نائبة مدعومة بالواصفات للتحميل الكسول في وقت التحليل. -### تسجيل الواجهة الخلفية لـ CLI +### تسجيل CLI backend -يتيح `api.registerCliBackend(...)` لـ Plugin امتلاك التهيئة الافتراضية -لواجهة CLI خلفية محلية للذكاء الاصطناعي مثل `codex-cli`. +يتيح `api.registerCliBackend(...)` لـ Plugin امتلاك الإعداد الافتراضي +لـ CLI backend محلي للذكاء الاصطناعي مثل `codex-cli`. -- يصبح `id` الخاص بالواجهة الخلفية بادئة الموفّر في مراجع النماذج مثل `codex-cli/gpt-5`. -- تستخدم `config` الخاصة بالواجهة الخلفية البنية نفسها مثل `agents.defaults.cliBackends.`. -- تظل تهيئة المستخدم لها الأولوية. يدمج OpenClaw `agents.defaults.cliBackends.` فوق - القيمة الافتراضية الخاصة بـ Plugin قبل تشغيل CLI. -- استخدم `normalizeConfig` عندما تحتاج واجهة خلفية إلى إعادة كتابة توافقية بعد الدمج - (على سبيل المثال تطبيع الأشكال القديمة للأعلام). +- يصبح `id` الخاص بالـ backend هو بادئة الموفّر في مراجع النماذج مثل `codex-cli/gpt-5`. +- يستخدم `config` الخاص بالـ backend البنية نفسها الموجودة في `agents.defaults.cliBackends.`. +- يظل إعداد المستخدم هو الغالب. يدمج OpenClaw القيمة `agents.defaults.cliBackends.` فوق + الإعداد الافتراضي للـ Plugin قبل تشغيل CLI. +- استخدم `normalizeConfig` عندما يحتاج backend إلى إعادة كتابة للتوافق بعد الدمج + (على سبيل المثال تطبيع أشكال العلامات القديمة). -### الخانات الحصرية +### الفتحات الحصرية -| الأسلوب | ما الذي يسجله | -| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerContextEngine(id, factory)` | محرك السياق (واحد فقط نشط في كل مرة). يتلقى رد النداء `assemble()` القيمتين `availableTools` و`citationsMode` حتى يتمكن المحرك من تكييف إضافات المطالبة. | -| `api.registerMemoryCapability(capability)` | قدرة ذاكرة موحّدة | -| `api.registerMemoryPromptSection(builder)` | بانٍ لقسم مطالبة الذاكرة | -| `api.registerMemoryFlushPlan(resolver)` | محلّل خطة تفريغ الذاكرة | -| `api.registerMemoryRuntime(runtime)` | مهايئ وقت تشغيل الذاكرة | +| Method | What it registers | +| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `api.registerContextEngine(id, factory)` | محرك السياق (واحد فقط يكون نشطًا في كل مرة). تتلقى دالة `assemble()` الراجعة `availableTools` و `citationsMode` حتى يتمكن المحرك من تفصيل الإضافات إلى المطالبة. | +| `api.registerMemoryCapability(capability)` | قدرة الذاكرة الموحدة | +| `api.registerMemoryPromptSection(builder)` | منشئ قسم مطالبة الذاكرة | +| `api.registerMemoryFlushPlan(resolver)` | محلّل خطة تفريغ الذاكرة | +| `api.registerMemoryRuntime(runtime)` | مهايئ وقت تشغيل الذاكرة | ### مهايئات تضمين الذاكرة -| الأسلوب | ما الذي يسجله | -| ---------------------------------------------- | --------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | مهايئ تضمين الذاكرة الخاص بـ Plugin النشط | +| Method | What it registers | +| ---------------------------------------------- | ---------------------------------------------- | +| `api.registerMemoryEmbeddingProvider(adapter)` | مهايئ تضمين الذاكرة للـ Plugin النشط | -- `registerMemoryCapability` هو API الذاكرة الحصري المفضّل لـ Plugin. -- قد يكشف `registerMemoryCapability` أيضًا `publicArtifacts.listArtifacts(...)` - بحيث يمكن للمكونات الإضافية المصاحبة استهلاك عناصر الذاكرة المُصدّرة عبر - `openclaw/plugin-sdk/memory-host-core` بدلًا من الوصول إلى التخطيط الخاص - الداخلي لمكوّن ذاكرة إضافي محدد. -- إن `registerMemoryPromptSection` و`registerMemoryFlushPlan` و - `registerMemoryRuntime` هي واجهات API حصرية للمكوّنات الإضافية الخاصة بالذاكرة - ومتوافقة مع الأنظمة القديمة. -- يتيح `registerMemoryEmbeddingProvider` لمكوّن الذاكرة الإضافي النشط تسجيل - معرّف مهايئ تضمين واحد أو أكثر (مثل `openai` أو `gemini` أو معرّف - مخصص يعرّفه Plugin). +- تُعد `registerMemoryCapability` واجهة Plugin الذاكرة الحصرية المفضلة. +- يمكن أيضًا لـ `registerMemoryCapability` كشف `publicArtifacts.listArtifacts(...)` + حتى تتمكن Plugins المصاحبة من استهلاك عناصر الذاكرة المصدّرة عبر + `openclaw/plugin-sdk/memory-host-core` بدلًا من الوصول إلى تخطيط خاص + لـ Plugin ذاكرة محدد. +- تُعد `registerMemoryPromptSection` و `registerMemoryFlushPlan` و + `registerMemoryRuntime` واجهات Plugin ذاكرة حصرية متوافقة مع الإصدارات القديمة. +- تتيح `registerMemoryEmbeddingProvider` للـ Plugin النشط للذاكرة تسجيل + معرّف مهايئ تضمين واحد أو أكثر (مثل `openai` أو `gemini` أو معرّف مخصص + يعرّفه Plugin). - تُحل إعدادات المستخدم مثل `agents.defaults.memorySearch.provider` و - `agents.defaults.memorySearch.fallback` في مقابل معرّفات المهايئات - المسجّلة تلك. + `agents.defaults.memorySearch.fallback` وفقًا لمعرّفات المهايئات المسجلة هذه. ### الأحداث ودورة الحياة -| الأسلوب | ما الذي يفعله | -| -------------------------------------------- | ------------------------ | -| `api.on(hookName, handler, opts?)` | خطاف دورة حياة مضبوط الأنواع | -| `api.onConversationBindingResolved(handler)` | رد نداء ربط المحادثة | +| Method | What it does | +| -------------------------------------------- | ----------------------------- | +| `api.on(hookName, handler, opts?)` | خطاف دورة حياة مطبوع | +| `api.onConversationBindingResolved(handler)` | رد نداء ربط المحادثة | ### دلالات قرار الخطاف -- `before_tool_call`: إن إرجاع `{ block: true }` نهائي. بمجرد أن يضبط أي معالج هذه القيمة، يتم تخطي المعالجات ذات الأولوية الأقل. -- `before_tool_call`: إن إرجاع `{ block: false }` يُعامل على أنه بلا قرار (مثل حذف `block`)، وليس كتجاوز. -- `before_install`: إن إرجاع `{ block: true }` نهائي. بمجرد أن يضبط أي معالج هذه القيمة، يتم تخطي المعالجات ذات الأولوية الأقل. -- `before_install`: إن إرجاع `{ block: false }` يُعامل على أنه بلا قرار (مثل حذف `block`)، وليس كتجاوز. -- `reply_dispatch`: إن إرجاع `{ handled: true, ... }` نهائي. بمجرد أن يعلن أي معالج أنه تولى الإرسال، يتم تخطي المعالجات ذات الأولوية الأقل ومسار إرسال النموذج الافتراضي. -- `message_sending`: إن إرجاع `{ cancel: true }` نهائي. بمجرد أن يضبط أي معالج هذه القيمة، يتم تخطي المعالجات ذات الأولوية الأقل. -- `message_sending`: إن إرجاع `{ cancel: false }` يُعامل على أنه بلا قرار (مثل حذف `cancel`)، وليس كتجاوز. +- `before_tool_call`: تؤدي إعادة `{ block: true }` إلى إنهاء المعالجة. وبمجرد أن يضبط أي معالج هذه القيمة، يتم تخطي المعالجات ذات الأولوية الأدنى. +- `before_tool_call`: تُعامل إعادة `{ block: false }` على أنها عدم اتخاذ قرار (مثل حذف `block`)، وليس كتجاوز. +- `before_install`: تؤدي إعادة `{ block: true }` إلى إنهاء المعالجة. وبمجرد أن يضبط أي معالج هذه القيمة، يتم تخطي المعالجات ذات الأولوية الأدنى. +- `before_install`: تُعامل إعادة `{ block: false }` على أنها عدم اتخاذ قرار (مثل حذف `block`)، وليس كتجاوز. +- `reply_dispatch`: تؤدي إعادة `{ handled: true, ... }` إلى إنهاء المعالجة. وبمجرد أن يطالب أي معالج بعملية الإرسال، يتم تخطي المعالجات ذات الأولوية الأدنى ومسار إرسال النموذج الافتراضي. +- `message_sending`: تؤدي إعادة `{ cancel: true }` إلى إنهاء المعالجة. وبمجرد أن يضبط أي معالج هذه القيمة، يتم تخطي المعالجات ذات الأولوية الأدنى. +- `message_sending`: تُعامل إعادة `{ cancel: false }` على أنها عدم اتخاذ قرار (مثل حذف `cancel`)، وليس كتجاوز. ### حقول كائن API -| الحقل | النوع | الوصف | -| ------------------------ | ------------------------- | ----------------------------------------------------------------------------------------- | -| `api.id` | `string` | معرّف Plugin | -| `api.name` | `string` | اسم العرض | -| `api.version` | `string?` | إصدار Plugin (اختياري) | -| `api.description` | `string?` | وصف Plugin (اختياري) | +| Field | Type | Description | +| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | +| `api.id` | `string` | معرّف Plugin | +| `api.name` | `string` | اسم العرض | +| `api.version` | `string?` | إصدار Plugin ‏(اختياري) | +| `api.description` | `string?` | وصف Plugin ‏(اختياري) | | `api.source` | `string` | مسار مصدر Plugin | -| `api.rootDir` | `string?` | الدليل الجذري لـ Plugin (اختياري) | -| `api.config` | `OpenClawConfig` | لقطة التهيئة الحالية (لقطة وقت التشغيل النشطة داخل الذاكرة عند توفرها) | -| `api.pluginConfig` | `Record` | تهيئة خاصة بـ Plugin من `plugins.entries..config` | -| `api.runtime` | `PluginRuntime` | [مساعدات وقت التشغيل](/ar/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | مسجل ضمن النطاق (`debug`, `info`, `warn`, `error`) | -| `api.registrationMode` | `PluginRegistrationMode` | وضع التحميل الحالي؛ تشير `"setup-runtime"` إلى نافذة البدء/الإعداد الخفيفة قبل الإدخال الكامل | -| `api.resolvePath(input)` | `(string) => string` | حل المسار بالنسبة إلى جذر Plugin | +| `api.rootDir` | `string?` | الدليل الجذري للـ Plugin ‏(اختياري) | +| `api.config` | `OpenClawConfig` | لقطة الإعدادات الحالية (لقطة وقت التشغيل النشطة داخل الذاكرة عند توفرها) | +| `api.pluginConfig` | `Record` | إعدادات خاصة بالـ Plugin من `plugins.entries..config` | +| `api.runtime` | `PluginRuntime` | [مساعدات وقت التشغيل](/ar/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | مسجل ذو نطاق محدد (`debug`, `info`, `warn`, `error`) | +| `api.registrationMode` | `PluginRegistrationMode` | وضع التحميل الحالي؛ `"setup-runtime"` هي نافذة البدء/الإعداد الخفيفة قبل الإدخال الكامل | +| `api.resolvePath(input)` | `(string) => string` | حل المسار نسبةً إلى جذر Plugin | -## اصطلاح الوحدات الداخلية +## اصطلاح الوحدة الداخلية -داخل Plugin الخاص بك، استخدم ملفات barrel محلية للاستيراد الداخلي: +داخل Plugin الخاص بك، استخدم ملفات barrel محلية للاستيرادات الداخلية: ``` my-plugin/ - api.ts # تصديرات عامة للمستهلكين الخارجيين + api.ts # التصديرات العامة للمستهلكين الخارجيين runtime-api.ts # تصديرات داخلية فقط لوقت التشغيل index.ts # نقطة إدخال Plugin setup-entry.ts # إدخال خفيف للإعداد فقط (اختياري) ``` - لا تستورد Plugin الخاص بك أبدًا عبر `openclaw/plugin-sdk/` + لا تستورد Plugin الخاص بك عبر `openclaw/plugin-sdk/` من كود الإنتاج. وجّه الاستيرادات الداخلية عبر `./api.ts` أو `./runtime-api.ts`. مسار SDK هو العقد الخارجي فقط. -تفضّل الآن الأسطح العامة للمكونات الإضافية المضمّنة المحمّلة عبر الواجهة (`api.ts` و`runtime-api.ts` -و`index.ts` و`setup-entry.ts` وملفات الإدخال العامة المشابهة) -لقطة تهيئة وقت التشغيل النشطة عندما يكون OpenClaw قيد التشغيل بالفعل. وإذا لم تكن -لقطة وقت التشغيل موجودة بعد، فإنها ترجع إلى ملف التهيئة المحلول على القرص. +تفضّل الآن الأسطح العامة لPlugin المجمّع المحمّلة عبر Facade (`api.ts`, `runtime-api.ts`, +`index.ts`, `setup-entry.ts`، وملفات الإدخال العامة المماثلة) +لقطة إعدادات وقت التشغيل النشطة عندما يكون OpenClaw قيد التشغيل بالفعل. وإذا لم تكن هناك +لقطة وقت تشغيل بعد، فإنها تعود إلى ملف الإعدادات المحلول على القرص. -يمكن لمكونات الموفّر الإضافية أيضًا كشف حزمة عقد محلية ضيقة خاصة بـ Plugin عندما -يكون أحد المساعدات خاصًا بالموفّر عمدًا ولا ينتمي بعد إلى مسار فرعي عام في SDK. -المثال المضمّن الحالي: يحتفظ موفّر Anthropic بمساعدات تدفق Claude -في مساره العام الخاص `api.ts` / `contract-api.ts` بدلًا من -ترقية منطق رأس Anthropic التجريبي و`service_tier` إلى عقد عام +يمكن Plugins الموفّرين أيضًا كشف ملف contract barrel محلي ضيق خاص بالـ Plugin عندما تكون +إحدى المساعدات خاصة بالموفّر عمدًا ولا تنتمي بعد إلى مسار فرعي عام +في SDK. المثال المجمّع الحالي: يحتفظ موفّر Anthropic بمساعدات تدفق Claude +داخل الطبقة العامة الخاصة به `api.ts` / `contract-api.ts` بدلًا من +ترقية منطق ترويسة Anthropic التجريبية و`service_tier` إلى عقد عام `plugin-sdk/*`. -أمثلة مضمّنة حالية أخرى: +أمثلة مجمّعة حالية أخرى: -- `@openclaw/openai-provider`: يصدّر `api.ts` بُناة الموفّر، - ومساعدات النموذج الافتراضي، وبُناة الموفّر الفوري -- `@openclaw/openrouter-provider`: يصدّر `api.ts` باني الموفّر بالإضافة إلى - مساعدات الإعداد الأولي/التهيئة +- `@openclaw/openai-provider`: يصدّر `api.ts` أدوات بناء الموفّر، + ومساعدات النموذج الافتراضي، وأدوات بناء الموفّر الفوري +- `@openclaw/openrouter-provider`: يصدّر `api.ts` أداة بناء الموفّر بالإضافة إلى + مساعدات الإعداد الأولي/الإعدادات - يجب على كود الإنتاج الخاص بالامتدادات أيضًا تجنّب استيرادات - `openclaw/plugin-sdk/`. - إذا كان أحد المساعدات مشتركًا فعلًا، فارفعه إلى مسار فرعي محايد في SDK - مثل `openclaw/plugin-sdk/speech` أو `.../provider-model-shared` أو سطح آخر - موجّه حسب القدرة بدلًا من ربط مكوّنين إضافيين معًا. + يجب أن يتجنب كود الإنتاج الخاص بالامتداد أيضًا استيراد `openclaw/plugin-sdk/`. + إذا كانت إحدى المساعدات مشتركة فعلًا، فقم بترقيتها إلى مسار فرعي محايد في SDK + مثل `openclaw/plugin-sdk/speech` أو `.../provider-model-shared` أو أي سطح آخر + موجّه إلى القدرات بدلًا من ربط Pluginين معًا. ## ذو صلة -- [نقاط الإدخال](/ar/plugins/sdk-entrypoints) — خيارات `definePluginEntry` و`defineChannelPluginEntry` +- [نقاط الإدخال](/ar/plugins/sdk-entrypoints) — خيارات `definePluginEntry` و `defineChannelPluginEntry` - [مساعدات وقت التشغيل](/ar/plugins/sdk-runtime) — المرجع الكامل لمساحة الأسماء `api.runtime` -- [الإعداد والتهيئة](/ar/plugins/sdk-setup) — التغليف، والبيانات الوصفية، ومخططات التهيئة +- [الإعداد والإعدادات](/ar/plugins/sdk-setup) — التحزيم، وmanifestات، ومخططات الإعدادات - [الاختبار](/ar/plugins/sdk-testing) — أدوات الاختبار وقواعد lint - [ترحيل SDK](/ar/plugins/sdk-migration) — الترحيل من الأسطح المهجورة -- [الخصائص الداخلية لـ Plugin](/ar/plugins/architecture) — البنية العميقة ونموذج القدرات +- [البنية الداخلية للـ Plugin](/ar/plugins/architecture) — البنية العميقة ونموذج القدرات diff --git a/docs/ar/refactor/qa.md b/docs/ar/refactor/qa.md index 3802e9127..1838186f1 100644 --- a/docs/ar/refactor/qa.md +++ b/docs/ar/refactor/qa.md @@ -1,168 +1,168 @@ --- x-i18n: - generated_at: "2026-04-08T06:02:17Z" + generated_at: "2026-04-18T07:15:28Z" model: gpt-5.4 provider: openai - source_hash: 4a9066b2a939c5a9ba69141d75405f0e8097997b523164340e2f0e9a0d5060dd + source_hash: dbb2c70c82da7f6f12d90e25666635ff4147c52e8a94135e902d1de4f5cbccca source_path: refactor/qa.md workflow: 15 --- # إعادة هيكلة QA -الحالة: تم إرساء الترحيل التأسيسي. +الحالة: تم إنجاز الترحيل التأسيسي. ## الهدف -نقل QA في OpenClaw من نموذج تعريف منقسم إلى مصدر حقيقة واحد: +نقل QA في OpenClaw من نموذج تعريف منقسم إلى مصدر وحيد للحقيقة: -- بيانات تعريف السيناريو +- بيانات وصفية للسيناريو - المطالبات المرسلة إلى النموذج -- الإعداد والتنظيف -- منطق الـ harness +- الإعداد والإنهاء +- منطق الحزام - التأكيدات ومعايير النجاح -- العناصر الناتجة وتلميحات التقرير +- الآثار وتلميحات التقرير -الحالة النهائية المطلوبة هي harness عام لـ QA يحمّل ملفات تعريف سيناريوهات قوية بدلًا من ترميز معظم السلوك بشكل ثابت في TypeScript. +الحالة النهائية المطلوبة هي حزام QA عام يحمّل ملفات تعريف سيناريوهات قوية بدلًا من ترميز معظم السلوك بشكل ثابت في TypeScript. ## الحالة الحالية -يوجد مصدر الحقيقة الأساسي الآن في `qa/scenarios/index.md` بالإضافة إلى ملف واحد لكل -سيناريو ضمن `qa/scenarios/*.md`. +المصدر الأساسي للحقيقة موجود الآن في `qa/scenarios/index.md` بالإضافة إلى ملف واحد لكل +سيناريو ضمن `qa/scenarios//*.md`. -ما تم تنفيذه: +تم تنفيذ ما يلي: - `qa/scenarios/index.md` - - بيانات تعريف حزمة QA القياسية + - بيانات وصفية قانونية لحزمة QA - هوية المشغّل - مهمة الانطلاق -- `qa/scenarios/*.md` +- `qa/scenarios//*.md` - ملف Markdown واحد لكل سيناريو - - بيانات تعريف السيناريو - - ربط المعالجات - - إعدادات التنفيذ الخاصة بالسيناريو + - بيانات وصفية للسيناريو + - ارتباطات المعالِجات + - ضبط تنفيذ خاص بالسيناريو - `extensions/qa-lab/src/scenario-catalog.ts` - محلل حزمة Markdown + تحقق `zod` - `extensions/qa-lab/src/qa-agent-bootstrap.ts` - تصيير الخطة من حزمة Markdown - `extensions/qa-lab/src/qa-agent-workspace.ts` - - يهيئ ملفات توافق مولدة بالإضافة إلى `QA_SCENARIOS.md` + - يزرع ملفات توافق مولدة بالإضافة إلى `QA_SCENARIOS.md` - `extensions/qa-lab/src/suite.ts` - - يحدد السيناريوهات القابلة للتنفيذ عبر روابط معالجات معرّفة في Markdown -- بروتوكول حافلة QA + واجهة المستخدم + - يختار السيناريوهات القابلة للتنفيذ عبر ارتباطات معالِجات معرّفة في Markdown +- بروتوكول ناقل QA + واجهة المستخدم - مرفقات مضمنة عامة لعرض الصور/الفيديو/الصوت/الملفات الأسطح المنقسمة المتبقية: - `extensions/qa-lab/src/suite.ts` - - لا يزال يملك معظم منطق المعالجات المخصصة القابلة للتنفيذ + - لا يزال يملك معظم منطق المعالِجات المخصصة القابلة للتنفيذ - `extensions/qa-lab/src/report.ts` - - لا يزال يستمد بنية التقرير من مخرجات وقت التشغيل + - لا يزال يشتق بنية التقرير من مخرجات وقت التشغيل -لذا تم إصلاح انقسام مصدر الحقيقة، لكن التنفيذ لا يزال في الغالب معتمدًا على المعالجات بدلًا من أن يكون تصريحيًا بالكامل. +لذا فقد تم إصلاح انقسام مصدر الحقيقة، لكن التنفيذ لا يزال في معظمه مدعومًا بالمعالِجات بدلًا من أن يكون تصريحيًا بالكامل. ## كيف يبدو سطح السيناريو الحقيقي -تُظهر قراءة الحزمة الحالية عدة فئات مميزة من السيناريوهات. +تُظهر قراءة المجموعة الحالية عدة فئات مميزة من السيناريوهات. ### تفاعل بسيط - خط أساس القناة -- خط أساس الرسائل الخاصة -- متابعة ضمن خيط +- خط أساس DM +- متابعة ضمن سلسلة - تبديل النموذج -- استكمال الموافقة -- التفاعل/التعديل/الحذف +- متابعة الموافقة +- التفاعل/التحرير/الحذف -### تعديل الإعدادات ووقت التشغيل +### تعديل الإعداد ووقت التشغيل -- تعطيل skill عبر ترقيع الإعدادات -- إيقاظ إعادة تشغيل تطبيق الإعدادات -- قلب قدرة إعادة تشغيل الإعدادات +- تعطيل مهارة تصحيح الإعداد +- تطبيق الإعداد وإعادة التشغيل والاستيقاظ +- قلب قدرة إعادة تشغيل الإعداد - فحص انجراف مخزون وقت التشغيل ### تأكيدات نظام الملفات والمستودع - تقرير اكتشاف المصدر/الوثائق - بناء Lobster Invaders -- البحث عن عنصر صورة مولد +- البحث عن أثر صورة مولدة ### تنسيق الذاكرة - استدعاء الذاكرة - أدوات الذاكرة في سياق القناة -- احتياط فشل الذاكرة +- الرجوع الاحتياطي عند فشل الذاكرة - ترتيب ذاكرة الجلسة -- عزل ذاكرة الخيط -- اجتياح حلم الذاكرة +- عزل ذاكرة السلسلة +- مسح Dreaming للذاكرة -### تكامل الأدوات والـ plugin +### تكامل الأدوات وPlugin -- استدعاء MCP plugin-tools -- ظهور Skills -- التثبيت السريع للـ skill +- استدعاء أدوات MCP Plugin +- رؤية المهارات +- تثبيت المهارة السريع - توليد الصور الأصلي -- رحلة الصورة الكاملة -- فهم الصورة من مرفق +- دورة ذهاب وإياب للصورة +- فهم الصورة من المرفق -### تعدد الأدوار وتعدد الأدوار الفاعلة +### متعدد الأدوار ومتعدد المنعطفات -- تسليم العمل إلى وكيل فرعي -- تركيب التوزيع المتوازي لوكلاء فرعيين +- تسليم وكيل فرعي +- تجميع مخرجات الوكلاء الفرعيين - تدفقات بأسلوب التعافي بعد إعادة التشغيل -هذه الفئات مهمة لأنها تحدد متطلبات DSL. فقائمة مسطحة من المطالبات + النص المتوقع ليست كافية. +هذه الفئات مهمة لأنها تحدد متطلبات DSL. فالقائمة المسطحة التي تحتوي على مطالبة + نص متوقع لا تكفي. ## الاتجاه -### مصدر حقيقة واحد +### مصدر وحيد للحقيقة -استخدم `qa/scenarios/index.md` بالإضافة إلى `qa/scenarios/*.md` كمصدر -الحقيقة المؤلف. +استخدم `qa/scenarios/index.md` بالإضافة إلى `qa/scenarios//*.md` بوصفها +المصدر المؤلف للحقيقة. -يجب أن تظل الحزمة: +ينبغي أن تظل الحزمة: - قابلة للقراءة البشرية أثناء المراجعة - قابلة للتحليل آليًا -- غنية بما يكفي لتشغيل: - - تنفيذ الحزمة - - تهيئة مساحة عمل QA - - بيانات تعريف واجهة مستخدم QA Lab +- غنية بما يكفي لقيادة: + - تنفيذ المجموعة + - تمهيد مساحة عمل QA + - بيانات وصفية لواجهة QA Lab - مطالبات الوثائق/الاكتشاف - توليد التقارير -### تنسيق التأليف المفضل +### صيغة التأليف المفضلة -استخدم Markdown كتنسيق علوي، مع YAML منظّم بداخله. +استخدم Markdown كصيغة عليا، مع YAML منظَّم داخله. -الشكل الموصى به: +البنية الموصى بها: - YAML frontmatter - id - title - surface - tags - - docs refs - - code refs - - تجاوزات النموذج/الموفر - - prerequisites + - مراجع الوثائق + - مراجع الشيفرة + - تجاوزات النموذج/المزوّد + - المتطلبات المسبقة - أقسام نثرية - - objective - - notes - - debugging hints + - الهدف + - ملاحظات + - تلميحات تصحيح - كتل YAML مسيجة - - setup - - steps - - assertions - - cleanup + - الإعداد + - الخطوات + - التأكيدات + - التنظيف -وهذا يوفّر: +يوفر هذا: -- قابلية قراءة أفضل في طلبات السحب من JSON ضخم -- سياقًا أغنى من YAML الخالص +- قابلية قراءة أفضل في طلبات السحب من JSON الضخم +- سياقًا أغنى من YAML الصرف - تحليلًا صارمًا وتحقق `zod` -يُقبل JSON الخام فقط كصيغة وسيطة مولدة. +يُقبل JSON الخام فقط بوصفه صيغة وسيطة مولدة. ## الشكل المقترح لملف السيناريو @@ -189,7 +189,7 @@ codeRefs: # الهدف -تحقق من إعادة إرفاق الوسائط المولدة في الدور اللاحق. +تحقق من إعادة إرفاق الوسائط المولدة في المنعطف التالي. # الإعداد @@ -223,7 +223,7 @@ codeRefs: - fromArtifact: lighthouseImage ``` -# التوقع +# المتوقع ```yaml scenario.expect - assert: outbound.textIncludes @@ -237,9 +237,9 @@ codeRefs: ``` ```` -## قدرات المشغّل التي يجب أن يغطيها DSL +## قدرات المشغل التي يجب أن تغطيها DSL -استنادًا إلى الحزمة الحالية، يحتاج المشغّل العام إلى أكثر من مجرد تنفيذ المطالبات. +استنادًا إلى المجموعة الحالية، يحتاج المشغل العام إلى أكثر من مجرد تنفيذ المطالبات. ### إجراءات البيئة والإعداد @@ -250,7 +250,7 @@ codeRefs: - `thread.create` - `workspace.writeSkill` -### إجراءات دور الوكيل +### إجراءات منعطفات الوكيل - `agent.send` - `agent.wait` @@ -266,7 +266,7 @@ codeRefs: - `tools.effective` - `skills.status` -### إجراءات الملفات والعناصر الناتجة +### إجراءات الملفات والآثار - `file.write` - `file.read` @@ -275,7 +275,7 @@ codeRefs: - `artifact.captureGeneratedImage` - `artifact.capturePath` -### إجراءات الذاكرة وcron +### إجراءات الذاكرة وCron - `memory.indexForce` - `memory.searchCli` @@ -305,76 +305,76 @@ codeRefs: - `cron.managedPresent` - `artifact.exists` -## المتغيرات ومراجع العناصر الناتجة +## المتغيرات ومراجع الآثار -يجب أن يدعم DSL المخرجات المحفوظة والمراجع اللاحقة إليها. +يجب أن تدعم DSL المخرجات المحفوظة والمراجع اللاحقة إليها. -أمثلة من الحزمة الحالية: +أمثلة من المجموعة الحالية: -- إنشاء خيط، ثم إعادة استخدام `threadId` +- إنشاء سلسلة، ثم إعادة استخدام `threadId` - إنشاء جلسة، ثم إعادة استخدام `sessionKey` -- توليد صورة، ثم إرفاق الملف في الدور التالي -- توليد سلسلة وسم إيقاظ، ثم التأكد من ظهورها لاحقًا +- توليد صورة، ثم إرفاق الملف في المنعطف التالي +- توليد سلسلة علامة استيقاظ، ثم التأكد من ظهورها لاحقًا القدرات المطلوبة: - `saveAs` - `${vars.name}` - `${artifacts.name}` -- مراجع typed للمسارات، ومفاتيح الجلسات، ومعرّفات الخيوط، والواسمات، ومخرجات الأدوات +- مراجع مكتوبة للأنواع للمسارات، ومفاتيح الجلسات، ومعرفات السلاسل، والعلامات، ومخرجات الأدوات -من دون دعم المتغيرات، سيستمر الـ harness في تسريب منطق السيناريو مرة أخرى إلى TypeScript. +من دون دعم المتغيرات، سيظل الحزام يعيد تسريب منطق السيناريو إلى TypeScript. -## ما الذي يجب أن يبقى كمخارج طوارئ +## ما الذي ينبغي أن يبقى كمنافذ هروب -المشغّل التصريحي الخالص بالكامل غير واقعي في المرحلة 1. +المشغل التصريحي النقي بالكامل غير واقعي في المرحلة 1. بعض السيناريوهات بطبيعتها كثيفة التنسيق: -- اجتياح حلم الذاكرة -- إيقاظ إعادة تشغيل تطبيق الإعدادات -- قلب قدرة إعادة تشغيل الإعدادات -- حل عنصر الصورة المولد حسب الطابع الزمني/المسار +- مسح Dreaming للذاكرة +- تطبيق الإعداد وإعادة التشغيل والاستيقاظ +- قلب قدرة إعادة تشغيل الإعداد +- حل أثر الصورة المولدة حسب الطابع الزمني/المسار - تقييم تقرير الاكتشاف -ينبغي أن تستخدم هذه السيناريوهات معالجات مخصصة صريحة في الوقت الحالي. +ينبغي أن تستخدم هذه السيناريوهات معالِجات مخصصة صريحة في الوقت الحالي. القاعدة الموصى بها: - 85-90% تصريحي - خطوات `customHandler` صريحة للباقي الصعب -- معالجات مخصصة مسماة وموثقة فقط -- لا يوجد كود مضمن مجهول داخل ملف السيناريو +- معالِجات مخصصة مسماة وموثقة فقط +- لا شيفرة مضمنة مجهولة داخل ملف السيناريو -يحافظ ذلك على نظافة المحرك العام مع السماح بإحراز التقدم. +هذا يُبقي المحرك العام نظيفًا مع السماح بإحراز تقدم. ## التغيير المعماري ### الحالي -أصبح Markdown الخاص بالسيناريو الآن مصدر الحقيقة لكل من: +أصبح Markdown الخاص بالسيناريو الآن هو مصدر الحقيقة من أجل: -- تنفيذ الحزمة -- ملفات تهيئة مساحة العمل -- فهرس سيناريوهات واجهة مستخدم QA Lab -- بيانات تعريف التقرير +- تنفيذ المجموعة +- ملفات تمهيد مساحة العمل +- فهرس سيناريوهات واجهة QA Lab +- بيانات التقرير الوصفية - مطالبات الاكتشاف التوافق المولد: -- لا تزال مساحة العمل المهيأة تتضمن `QA_KICKOFF_TASK.md` -- لا تزال مساحة العمل المهيأة تتضمن `QA_SCENARIO_PLAN.md` -- تتضمن مساحة العمل المهيأة الآن أيضًا `QA_SCENARIOS.md` +- لا تزال مساحة العمل المزروعة تتضمن `QA_KICKOFF_TASK.md` +- لا تزال مساحة العمل المزروعة تتضمن `QA_SCENARIO_PLAN.md` +- كما أصبحت مساحة العمل المزروعة تتضمن أيضًا `QA_SCENARIOS.md` ## خطة إعادة الهيكلة -### المرحلة 1: المُحمّل والمخطط +### المرحلة 1: المُحمِّل والمخطط تمت. - تمت إضافة `qa/scenarios/index.md` -- تم تقسيم السيناريوهات إلى `qa/scenarios/*.md` -- تمت إضافة محلل لمحتوى حزمة YAML المسمى في Markdown +- تم تقسيم السيناريوهات إلى `qa/scenarios//*.md` +- تمت إضافة محلل لمحتوى حزمة Markdown YAML المسمّى - تم التحقق باستخدام `zod` - تم تحويل المستهلكين إلى الحزمة المحللة - تمت إزالة `qa/seed-scenarios.json` و`qa/QA_KICKOFF_TASK.md` على مستوى المستودع @@ -382,60 +382,60 @@ codeRefs: ### المرحلة 2: المحرك العام - تقسيم `extensions/qa-lab/src/suite.ts` إلى: - - loader - - engine - - action registry - - assertion registry - - custom handlers + - مُحمِّل + - محرك + - سجل إجراءات + - سجل تأكيدات + - معالِجات مخصصة - الإبقاء على دوال المساعدة الحالية كعمليات للمحرك -الناتج القابل للتسليم: +الناتج المطلوب: -- ينفذ المحرك سيناريوهات تصريحية بسيطة +- ينفّذ المحرك سيناريوهات تصريحية بسيطة -ابدأ بالسيناريوهات التي تكون في الغالب مطالبة + انتظار + تأكيد: +ابدأ بالسيناريوهات التي هي غالبًا مطالبة + انتظار + تأكيد: -- متابعة ضمن خيط -- فهم الصورة من مرفق -- ظهور الـ skill واستدعاؤه +- متابعة ضمن سلسلة +- فهم الصورة من المرفق +- رؤية المهارة واستدعاؤها - خط أساس القناة -الناتج القابل للتسليم: +الناتج المطلوب: - أول سيناريوهات حقيقية معرّفة في Markdown تُشحن عبر المحرك العام ### المرحلة 4: ترحيل السيناريوهات المتوسطة -- رحلة توليد الصورة الكاملة +- دورة ذهاب وإياب لتوليد الصور - أدوات الذاكرة في سياق القناة - ترتيب ذاكرة الجلسة -- تسليم العمل إلى وكيل فرعي -- تركيب التوزيع المتوازي لوكلاء فرعيين +- تسليم وكيل فرعي +- تجميع مخرجات الوكلاء الفرعيين -الناتج القابل للتسليم: +الناتج المطلوب: -- إثبات المتغيرات والعناصر الناتجة وتأكيدات الأدوات وتأكيدات سجل الطلبات +- إثبات المتغيرات، والآثار، وتأكّدات الأدوات، وتأكّدات سجل الطلبات -### المرحلة 5: إبقاء السيناريوهات الصعبة على المعالجات المخصصة +### المرحلة 5: إبقاء السيناريوهات الصعبة على المعالِجات المخصصة -- اجتياح حلم الذاكرة -- إيقاظ إعادة تشغيل تطبيق الإعدادات -- قلب قدرة إعادة تشغيل الإعدادات +- مسح Dreaming للذاكرة +- تطبيق الإعداد وإعادة التشغيل والاستيقاظ +- قلب قدرة إعادة تشغيل الإعداد - انجراف مخزون وقت التشغيل -الناتج القابل للتسليم: +الناتج المطلوب: -- نفس تنسيق التأليف، ولكن مع كتل خطوات مخصصة صريحة عند الحاجة +- نفس صيغة التأليف، ولكن مع كتل خطوات مخصصة صريحة عند الحاجة -### المرحلة 6: حذف خريطة السيناريوهات المرمزة بشكل ثابت +### المرحلة 6: حذف خريطة السيناريوهات المرمزة بمجرد أن تصبح تغطية الحزمة جيدة بما يكفي: -- أزل معظم التفرعات الخاصة بالسيناريو في TypeScript من `extensions/qa-lab/src/suite.ts` +- إزالة معظم التفرعات الخاصة بكل سيناريو في TypeScript من `extensions/qa-lab/src/suite.ts` ## دعم Slack المزيف / الوسائط الغنية -حافلة QA الحالية تعتمد النص أولًا. +ناقل QA الحالي يركّز على النص أولًا. الملفات ذات الصلة: @@ -445,17 +445,17 @@ codeRefs: - `extensions/qa-lab/src/bus-server.ts` - `extensions/qa-lab/web/src/ui-render.ts` -اليوم تدعم حافلة QA: +اليوم يدعم ناقل QA ما يلي: - النص - التفاعلات -- الخيوط +- السلاسل -وهي لا تصمم بعد مرفقات وسائط مضمنة. +لكنه لا يصمّم بعد مرفقات الوسائط المضمنة. ### عقد النقل المطلوب -أضف نموذج مرفقات عام لحافلة QA: +أضف نموذج مرفقات عام لناقل QA: ```ts type QaBusAttachment = { @@ -480,61 +480,61 @@ type QaBusAttachment = { - `QaBusInboundMessageInput` - `QaBusOutboundMessageInput` -### لماذا البدء بشكل عام أولًا +### لماذا العام أولًا لا تبنِ نموذج وسائط خاصًا بـ Slack فقط. بدلًا من ذلك: - نموذج نقل QA عام واحد -- عدة مصيّرات فوقه +- عدة مُصيّرات فوقه - دردشة QA Lab الحالية - - واجهة Slack ويب مزيفة مستقبلية + - ويب Slack مزيف مستقبلًا - أي عروض نقل مزيفة أخرى -هذا يمنع تكرار المنطق ويجعل سيناريوهات الوسائط غير مرتبطة بوسيلة نقل محددة. +هذا يمنع تكرار المنطق ويجعل سيناريوهات الوسائط مستقلة عن وسيلة النقل. ### أعمال واجهة المستخدم المطلوبة -حدّث واجهة مستخدم QA لتصيير: +حدّث واجهة QA لعرض: - معاينة صورة مضمنة - مشغل صوت مضمن - مشغل فيديو مضمن - شارة مرفق ملف -يمكن لواجهة المستخدم الحالية بالفعل تصيير الخيوط والتفاعلات، لذا يجب أن يُضاف تصيير المرفقات فوق نموذج بطاقة الرسالة نفسه. +يمكن للواجهة الحالية بالفعل عرض السلاسل والتفاعلات، لذا ينبغي أن يندمج عرض المرفقات فوق نموذج بطاقة الرسالة نفسه. ### أعمال السيناريو التي يتيحها نقل الوسائط -بمجرد أن تمر المرفقات عبر حافلة QA، يمكننا إضافة سيناريوهات دردشة مزيفة أكثر غنى: +بمجرد أن تتدفق المرفقات عبر ناقل QA، يمكننا إضافة سيناريوهات دردشة مزيفة أغنى: -- رد بصورة مضمنة في Slack المزيف +- رد صورة مضمنة في Slack مزيف - فهم مرفق صوتي - فهم مرفق فيديو - ترتيب مختلط للمرفقات -- رد ضمن خيط مع الاحتفاظ بالوسائط +- رد ضمن سلسلة مع الاحتفاظ بالوسائط ## التوصية يجب أن تكون الدفعة التالية من التنفيذ كما يلي: -1. إضافة مُحمّل سيناريو Markdown + مخطط `zod` +1. إضافة مُحمِّل سيناريو Markdown + مخطط `zod` 2. توليد الفهرس الحالي من Markdown 3. ترحيل بعض السيناريوهات البسيطة أولًا -4. إضافة دعم مرفقات حافلة QA العامة -5. تصيير صورة مضمنة في واجهة مستخدم QA +4. إضافة دعم مرفقات ناقل QA عام +5. تصيير صورة مضمنة في واجهة QA 6. ثم التوسع إلى الصوت والفيديو هذا هو أصغر مسار يثبت كلا الهدفين: -- QA عام معرّف عبر Markdown -- أسطح مراسلة مزيفة أكثر غنى +- QA عام معرّف في Markdown +- أسطح مراسلة مزيفة أغنى ## أسئلة مفتوحة -- ما إذا كان ينبغي أن تسمح ملفات السيناريو بقوالب مطالبات Markdown مضمنة مع استيفاء المتغيرات +- ما إذا كان ينبغي أن تسمح ملفات السيناريو بقوالب مطالبات Markdown مضمنة مع إقحام المتغيرات - ما إذا كان ينبغي أن يكون الإعداد/التنظيف أقسامًا مسماة أو مجرد قوائم إجراءات مرتبة -- ما إذا كان ينبغي أن تكون مراجع العناصر الناتجة typed بقوة في المخطط أو معتمدة على السلاسل -- ما إذا كان ينبغي أن تعيش المعالجات المخصصة في سجل واحد أو في سجلات حسب السطح -- ما إذا كان ينبغي أن يظل ملف التوافق JSON المولد محفوظًا في git أثناء الترحيل +- ما إذا كان ينبغي أن تكون مراجع الآثار مكتوبة بقوة في المخطط أو معتمدة على سلاسل نصية +- ما إذا كان ينبغي أن تعيش المعالِجات المخصصة في سجل واحد أو في سجلات لكل سطح +- ما إذا كان ينبغي أن يظل ملف توافق JSON المولَّد محفوظًا في المستودع أثناء الترحيل