From 66b61bda2e72c67604f78b9585ba23ae5be46d92 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Thu, 16 Apr 2026 07:20:39 +0000 Subject: [PATCH] chore(i18n): refresh ar translations --- docs/ar/concepts/active-memory.md | 553 +++++++++------- docs/ar/gateway/protocol.md | 592 ++++++++++-------- docs/ar/providers/google.md | 185 +++--- ...exec-duplicate-completion-investigation.md | 132 ++++ docs/ar/tools/tts.md | 254 ++++---- 5 files changed, 1027 insertions(+), 689 deletions(-) create mode 100644 docs/ar/refactor/async-exec-duplicate-completion-investigation.md diff --git a/docs/ar/concepts/active-memory.md b/docs/ar/concepts/active-memory.md index 93b76a16a..a186f32e5 100644 --- a/docs/ar/concepts/active-memory.md +++ b/docs/ar/concepts/active-memory.md @@ -1,36 +1,36 @@ --- read_when: - - أنت تريد أن تفهم الغرض من Active Memory + - تريد أن تفهم الغرض من Active Memory - تريد تشغيل Active Memory لوكيل محادثة - - تريد ضبط سلوك Active Memory بدون تمكينه في كل مكان -summary: وكيل فرعي لحظر الذاكرة مملوك للـ Plugin يحقن الذاكرة ذات الصلة في جلسات الدردشة التفاعلية + - تريد ضبط سلوك Active Memory من دون تمكينه في كل مكان +summary: وكيل فرعي لحظر الذاكرة مملوك لـ Plugin يحقن الذاكرة ذات الصلة في جلسات الدردشة التفاعلية title: Active Memory x-i18n: - generated_at: "2026-04-14T02:08:42Z" + generated_at: "2026-04-16T07:17:54Z" model: gpt-5.4 provider: openai - source_hash: b151e9eded7fc5c37e00da72d95b24c1dc94be22e855c8875f850538392b0637 + source_hash: ab36c5fea1578348cc2258ea3b344cc7bdc814f337d659cdb790512b3ea45473 source_path: concepts/active-memory.md workflow: 15 --- # Active Memory -‏Active Memory هو وكيل فرعي اختياري لحظر الذاكرة مملوك للـ Plugin ويعمل +تُعد Active Memory وكيلًا فرعيًا اختياريًا لحظر الذاكرة مملوكًا لـ Plugin ويعمل قبل الرد الرئيسي للجلسات الحوارية المؤهلة. -يوجد لأنه في حين أن معظم أنظمة الذاكرة قادرة، فإنها تفاعلية. فهي تعتمد على -الوكيل الرئيسي ليقرر متى يبحث في الذاكرة، أو على المستخدم ليقول أشياء -مثل "تذكر هذا" أو "ابحث في الذاكرة". وبحلول ذلك الوقت، تكون اللحظة التي كان -من الممكن أن تجعل فيها الذاكرة الرد يبدو طبيعيًا قد فاتت بالفعل. +وُجدت لأنها تعالج مشكلة أن معظم أنظمة الذاكرة قوية لكنها تفاعلية. فهي تعتمد على +أن يقرر الوكيل الرئيسي متى يبحث في الذاكرة، أو على أن يقول المستخدم أشياء مثل +"تذكّر هذا" أو "ابحث في الذاكرة". وعند تلك اللحظة، تكون الفرصة التي كان يمكن أن +تجعل الذاكرة الرد يبدو طبيعيًا قد فاتت بالفعل. -يمنح Active Memory النظام فرصة واحدة محدودة لإظهار الذاكرة ذات الصلة +تمنح Active Memory النظام فرصة محدودة واحدة لإظهار ذاكرة ذات صلة قبل إنشاء الرد الرئيسي. ## الصق هذا في وكيلك -الصق هذا في وكيلك إذا كنت تريد منه تمكين Active Memory بإعداد -ذاتي الاحتواء وآمن افتراضيًا: +الصق هذا في وكيلك إذا أردت تمكين Active Memory بإعداد +مكتفٍ ذاتيًا وآمن افتراضيًا: ```json5 { @@ -56,10 +56,9 @@ x-i18n: } ``` -يؤدي هذا إلى تشغيل الـ Plugin للوكيل `main`، ويبقيه مقصورًا افتراضيًا على -الجلسات بأسلوب الرسائل المباشرة، ويسمح له أولًا بوراثة نموذج الجلسة الحالي، -ويستخدم نموذج الرجوع الاحتياطي المكوَّن فقط إذا لم يكن هناك نموذج صريح أو -موروث متاح. +يؤدي هذا إلى تشغيل Plugin للوكيل `main`، مع إبقائه مقصورًا على جلسات +نمط الرسائل المباشرة افتراضيًا، ويسمح له أولًا بوراثة نموذج الجلسة الحالي، +ويستخدم نموذج الاحتياط المُعد فقط إذا لم يكن هناك نموذج صريح أو موروث متاح. بعد ذلك، أعد تشغيل Gateway: @@ -76,9 +75,9 @@ openclaw gateway ## تشغيل Active Memory -الإعداد الأكثر أمانًا هو: +أكثر إعدادات الأمان هي: -1. تمكين الـ Plugin +1. تمكين Plugin 2. استهداف وكيل حواري واحد 3. إبقاء التسجيل مفعّلًا فقط أثناء الضبط @@ -115,24 +114,109 @@ openclaw gateway ما يعنيه هذا: -- `plugins.entries.active-memory.enabled: true` يشغّل الـ Plugin +- `plugins.entries.active-memory.enabled: true` يشغّل Plugin - `config.agents: ["main"]` يفعّل Active Memory للوكيل `main` فقط -- `config.allowedChatTypes: ["direct"]` يُبقي Active Memory مفعّلًا افتراضيًا لجلسات أسلوب الرسائل المباشرة فقط -- إذا لم يتم تعيين `config.model`، فإن Active Memory يرث أولًا نموذج الجلسة الحالي -- يوفّر `config.modelFallback` اختياريًا مزوّد/نموذج رجوع احتياطي خاصًا بك للاستدعاء -- يستخدم `config.promptStyle: "balanced"` نمط المطالبة الافتراضي متعدد الأغراض لوضع `recent` -- لا يزال Active Memory يعمل فقط على جلسات الدردشة التفاعلية الدائمة المؤهلة +- `config.allowedChatTypes: ["direct"]` يُبقي Active Memory مفعّلًا لجلسات نمط الرسائل المباشرة فقط افتراضيًا +- إذا كان `config.model` غير مضبوط، فإن Active Memory يرث أولًا نموذج الجلسة الحالي +- يوفّر `config.modelFallback` اختياريًا موفرًا/نموذجًا احتياطيًا خاصًا بك للاسترجاع +- يستخدم `config.promptStyle: "balanced"` نمط الموجّه الافتراضي للأغراض العامة لوضع `recent` +- ما تزال Active Memory تعمل فقط في جلسات الدردشة التفاعلية الدائمة المؤهلة + +## توصيات السرعة + +أبسط إعداد هو ترك `config.model` غير مضبوط وترك Active Memory تستخدم +النموذج نفسه الذي تستخدمه أصلًا للردود العادية. وهذا هو الإعداد الافتراضي الأكثر أمانًا +لأنه يتبع تفضيلاتك الحالية للموفر والمصادقة والنموذج. + +إذا أردت أن تبدو Active Memory أسرع، فاستخدم نموذج استدلال مخصصًا +بدلًا من استعارة نموذج الدردشة الرئيسي. + +مثال على إعداد موفر سريع: + +```json5 +models: { + providers: { + cerebras: { + baseUrl: "https://api.cerebras.ai/v1", + apiKey: "${CEREBRAS_API_KEY}", + api: "openai-completions", + models: [{ id: "gpt-oss-120b", name: "GPT OSS 120B (Cerebras)" }], + }, + }, +}, +plugins: { + entries: { + "active-memory": { + enabled: true, + config: { + model: "cerebras/gpt-oss-120b", + }, + }, + }, +} +``` + +خيارات النماذج السريعة الجديرة بالنظر: + +- `cerebras/gpt-oss-120b` لنموذج استرجاع مخصص سريع بسطح أدوات محدود +- نموذج الجلسة العادي لديك، عبر ترك `config.model` غير مضبوط +- نموذج احتياطي منخفض الكمون مثل `google/gemini-3-flash` عندما تريد نموذج استرجاع منفصلًا من دون تغيير نموذج الدردشة الأساسي + +لماذا يُعد Cerebras خيارًا قويًا يركّز على السرعة في Active Memory: + +- سطح أدوات Active Memory محدود: فهو يستدعي فقط `memory_search` و`memory_get` +- جودة الاسترجاع مهمة، لكن الكمون أهم مما هو عليه في مسار الإجابة الرئيسي +- يجنّبك الموفّر السريع المخصص ربط كمون استرجاع الذاكرة بموفر الدردشة الأساسي لديك + +إذا كنت لا تريد نموذجًا منفصلًا محسّنًا للسرعة، فاترك `config.model` غير مضبوط +ودع Active Memory ترث نموذج الجلسة الحالي. + +### إعداد Cerebras + +أضف إدخال موفر مثل هذا: + +```json5 +models: { + providers: { + cerebras: { + baseUrl: "https://api.cerebras.ai/v1", + apiKey: "${CEREBRAS_API_KEY}", + api: "openai-completions", + models: [{ id: "gpt-oss-120b", name: "GPT OSS 120B (Cerebras)" }], + }, + }, +} +``` + +ثم وجّه Active Memory إليه: + +```json5 +plugins: { + entries: { + "active-memory": { + enabled: true, + config: { + model: "cerebras/gpt-oss-120b", + }, + }, + }, +} +``` + +تنبيه: + +- تأكد من أن مفتاح Cerebras API لديه بالفعل صلاحية الوصول إلى النموذج الذي تختاره، لأن ظهور `/v1/models` وحده لا يضمن الوصول إلى `chat/completions` ## كيفية رؤيته -يحقن Active Memory بادئة مطالبة مخفية وغير موثوقة للنموذج. وهو -لا يكشف وسوم `...` الخام في +تحقن Active Memory بادئة موجّه خفية غير موثوقة للنموذج. وهي +لا تعرض وسوم `...` الخام في الرد العادي المرئي للعميل. ## تبديل الجلسة -استخدم أمر الـ Plugin عندما تريد إيقاف Active Memory مؤقتًا أو استئنافه -لجلسة الدردشة الحالية بدون تعديل الإعدادات: +استخدم أمر Plugin عندما تريد إيقاف Active Memory مؤقتًا أو استئنافها +لجلسة الدردشة الحالية من دون تعديل الإعدادات: ```text /active-memory status @@ -144,7 +228,7 @@ openclaw gateway `plugins.entries.active-memory.enabled` أو استهداف الوكيل أو أي إعداد عام آخر. -إذا كنت تريد أن يكتب الأمر الإعدادات ويوقف Active Memory مؤقتًا أو يستأنفه +إذا أردت أن يكتب الأمر الإعدادات ويوقف Active Memory مؤقتًا أو يستأنفها لكل الجلسات، فاستخدم الصيغة العامة الصريحة: ```text @@ -153,30 +237,30 @@ openclaw gateway /active-memory on --global ``` -تكتب الصيغة العامة `plugins.entries.active-memory.config.enabled`. وهي تُبقي +تكتب الصيغة العامة `plugins.entries.active-memory.config.enabled`. وتُبقي `plugins.entries.active-memory.enabled` مفعّلًا حتى يظل الأمر متاحًا -لتشغيل Active Memory مجددًا لاحقًا. +لتشغيل Active Memory مرة أخرى لاحقًا. -إذا كنت تريد رؤية ما يفعله Active Memory في جلسة مباشرة، فشغّل -مفاتيح تبديل الجلسة المطابقة للمخرجات التي تريدها: +إذا أردت رؤية ما تفعله Active Memory في جلسة مباشرة، فشغّل +مبدلات الجلسة التي تطابق المخرجات التي تريدها: ```text /verbose on /trace on ``` -عند تمكين هذين الخيارين، يمكن لـ OpenClaw إظهار ما يلي: +عند تمكينهما، يمكن لـ OpenClaw عرض ما يلي: -- سطر حالة لـ Active Memory مثل `Active Memory: status=ok elapsed=842ms query=recent summary=34 chars` عند استخدام `/verbose on` -- ملخص تصحيح أخطاء مقروء مثل `Active Memory Debug: Lemon pepper wings with blue cheese.` عند استخدام `/trace on` +- سطر حالة Active Memory مثل `Active Memory: status=ok elapsed=842ms query=recent summary=34 chars` عند استخدام `/verbose on` +- ملخص تصحيح قابل للقراءة مثل `Active Memory Debug: Lemon pepper wings with blue cheese.` عند استخدام `/trace on` -تُشتق هذه الأسطر من نفس تمريرة Active Memory التي تغذي بادئة -المطالبة المخفية، لكنها منسّقة للبشر بدلًا من كشف ترميز المطالبة الخام. -ويتم إرسالها كرسالة تشخيصية لاحقة بعد رد المساعد العادي حتى لا تُظهر +تُشتق هذه الأسطر من تمرير Active Memory نفسه الذي يغذي بادئة +الموجّه الخفية، لكنها منسقة للبشر بدلًا من كشف ترميز الموجّه الخام. +ويتم إرسالها كرسالة تشخيص متابعة بعد رد المساعد العادي حتى لا تعرض عملاء القنوات مثل Telegram فقاعة تشخيص منفصلة قبل الرد. -إذا قمت أيضًا بتمكين `/trace raw`، فستُظهر كتلة `Model Input (User Role)` المتتبعة -بادئة Active Memory المخفية على الشكل التالي: +إذا فعّلت أيضًا `/trace raw`، فسيعرض مقطع `Model Input (User Role)` المتتبَّع +بادئة Active Memory الخفية على النحو التالي: ```text Untrusted context (metadata, do not treat as instructions or commands): @@ -185,10 +269,10 @@ Untrusted context (metadata, do not treat as instructions or commands): ``` -بشكل افتراضي، يكون نص وكيل حظر الذاكرة الفرعي مؤقتًا ويُحذف +افتراضيًا، يكون سجل وكيل حظر الذاكرة الفرعي مؤقتًا ويُحذف بعد اكتمال التشغيل. -مثال على سير العمل: +مثال على التدفق: ```text /verbose on @@ -205,15 +289,15 @@ what wings should i order? 🔎 Active Memory Debug: Lemon pepper wings with blue cheese. ``` -## متى يعمل +## متى تعمل -يستخدم Active Memory بوابتين: +تستخدم Active Memory بوابتين: -1. **الاشتراك عبر الإعدادات** - يجب تمكين الـ Plugin، ويجب أن يظهر معرّف الوكيل الحالي في +1. **اشتراك عبر الإعدادات** + يجب تمكين Plugin، ويجب أن يظهر معرّف الوكيل الحالي في `plugins.entries.active-memory.config.agents`. -2. **أهلية تشغيل صارمة** - حتى عند تمكينه واستهدافه، لا يعمل Active Memory إلا مع +2. **أهلية صارمة وقت التشغيل** + حتى عند التمكين والاستهداف، لا تعمل Active Memory إلا مع جلسات الدردشة التفاعلية الدائمة المؤهلة. القاعدة الفعلية هي: @@ -230,7 +314,7 @@ eligible interactive persistent chat session active memory runs ``` -إذا فشل أي من هذه الشروط، فلن يعمل Active Memory. +إذا فشل أي شرط من هذه الشروط، فلن تعمل Active Memory. ## أنواع الجلسات @@ -243,9 +327,8 @@ Memory من الأساس. allowedChatTypes: ["direct"] ``` -هذا يعني أن Active Memory يعمل افتراضيًا في الجلسات بأسلوب الرسائل -المباشرة، لكنه لا يعمل في جلسات المجموعات أو القنوات إلا إذا قمت -بالاشتراك فيها صراحةً. +وهذا يعني أن Active Memory تعمل افتراضيًا في جلسات نمط الرسائل المباشرة، +لكن ليس في جلسات المجموعات أو القنوات إلا إذا قمت بضمّها صراحةً. أمثلة: @@ -261,44 +344,44 @@ allowedChatTypes: ["direct", "group"] allowedChatTypes: ["direct", "group", "channel"] ``` -## أين يعمل +## أين تعمل -‏Active Memory ميزة لإثراء المحادثة، وليست ميزة استدلال على مستوى -المنصة بالكامل. +تُعد Active Memory ميزة إثراء حوارية، وليست ميزة استدلال +على مستوى المنصة بالكامل. -| السطح | هل يعمل Active Memory؟ | -| ------------------------------------------------------------------- | ------------------------------------------------------- | -| جلسات Control UI / دردشة الويب الدائمة | نعم، إذا كان الـ Plugin مفعّلًا وكان الوكيل مستهدفًا | -| جلسات القنوات التفاعلية الأخرى على مسار الدردشة الدائمة نفسه | نعم، إذا كان الـ Plugin مفعّلًا وكان الوكيل مستهدفًا | -| عمليات التشغيل الرأسية ذات اللقطة الواحدة | لا | -| عمليات Heartbeat/الخلفية | لا | -| مسارات `agent-command` الداخلية العامة | لا | -| تنفيذ الوكيل الفرعي/المساعد الداخلي | لا | +| السطح | هل تعمل Active Memory؟ | +| ----------------------------------------------------------------- | ------------------------------------------------------ | +| جلسات Control UI / دردشة الويب الدائمة | نعم، إذا كان Plugin مفعّلًا وكان الوكيل مستهدفًا | +| جلسات القنوات التفاعلية الأخرى على مسار الدردشة الدائمة نفسه | نعم، إذا كان Plugin مفعّلًا وكان الوكيل مستهدفًا | +| التشغيلات أحادية اللقطة من دون واجهة | لا | +| تشغيلات Heartbeat/الخلفية | لا | +| مسارات `agent-command` الداخلية العامة | لا | +| تنفيذ الوكلاء الفرعيين/المساعدات الداخلية | لا | -## لماذا تستخدمه +## لماذا تستخدمها استخدم Active Memory عندما: -- تكون الجلسة دائمة وموجهة للمستخدم -- يملك الوكيل ذاكرة طويلة الأمد ذات معنى للبحث فيها -- تكون الاستمرارية والتخصيص أهم من حتمية المطالبة الخام +- تكون الجلسة دائمة ومواجهة للمستخدم +- يكون لدى الوكيل ذاكرة طويلة الأمد ذات معنى للبحث فيها +- تكون الاستمرارية والتخصيص أهم من الحتمية الخام للموجّه -وهو يعمل بشكل جيد خصوصًا مع: +وهي تعمل جيدًا خصوصًا مع: - التفضيلات المستقرة - العادات المتكررة -- سياق المستخدم طويل الأمد الذي ينبغي أن يظهر بشكل طبيعي +- سياق المستخدم طويل الأمد الذي ينبغي أن يظهر بصورة طبيعية -وهو غير مناسب لـ: +وهي غير مناسبة لـ: - الأتمتة -- العمال الداخليين -- مهام API ذات اللقطة الواحدة -- الأماكن التي سيكون فيها التخصيص الخفي مفاجئًا +- العاملين الداخليين +- مهام API أحادية اللقطة +- الأماكن التي يكون فيها التخصيص الخفي مفاجئًا -## كيف يعمل +## كيف تعمل -شكل التشغيل هو: +شكل وقت التشغيل هو: ```mermaid flowchart LR @@ -309,32 +392,33 @@ flowchart LR I --> M["Main Reply"] ``` -يمكن لوكيل حظر الذاكرة الفرعي استخدام ما يلي فقط: +يمكن لوكيل حظر الذاكرة الفرعي استخدام الأداتين التاليتين فقط: - `memory_search` - `memory_get` -إذا كان الاتصال ضعيفًا، فيجب عليه إرجاع `NONE`. +إذا كان الاتصال ضعيفًا، فيجب أن يعيد `NONE`. ## أوضاع الاستعلام -يتحكم `config.queryMode` في مقدار المحادثة التي يراها وكيل حظر الذاكرة الفرعي. +يتحكم `config.queryMode` في مقدار المحادثة الذي يراه +وكيل حظر الذاكرة الفرعي. -## أنماط المطالبة +## أنماط الموجّه -يتحكم `config.promptStyle` في مدى اندفاع أو صرامة وكيل حظر الذاكرة الفرعي -عند اتخاذ قرار بشأن ما إذا كان سيُرجع ذاكرة. +يتحكم `config.promptStyle` في مقدار الحماس أو الصرامة لدى وكيل حظر الذاكرة الفرعي +عند تقرير ما إذا كان سيعيد ذاكرة أم لا. الأنماط المتاحة: - `balanced`: الإعداد الافتراضي العام لوضع `recent` -- `strict`: الأقل اندفاعًا؛ الأفضل عندما تريد أقل قدر ممكن من التسرب من السياق القريب -- `contextual`: الأكثر ملاءمة للاستمرارية؛ الأفضل عندما يكون لسجل المحادثة أهمية أكبر -- `recall-heavy`: أكثر استعدادًا لإظهار الذاكرة في حالات التطابق الأضعف ولكن المعقولة -- `precision-heavy`: يفضّل `NONE` بقوة ما لم يكن التطابق واضحًا -- `preference-only`: مُحسّن للمفضلات والعادات والروتين والذوق والحقائق الشخصية المتكررة +- `strict`: الأقل حماسًا؛ الأفضل عندما تريد أقل قدر ممكن من التأثر بالسياق القريب +- `contextual`: الأكثر ملاءمة للاستمرارية؛ الأفضل عندما يجب أن يكون لسجل المحادثة أهمية أكبر +- `recall-heavy`: أكثر استعدادًا لإظهار الذاكرة عند وجود تطابقات أضعف لكنها ما تزال معقولة +- `precision-heavy`: يفضّل `NONE` بشدة ما لم يكن التطابق واضحًا +- `preference-only`: محسّن للمفضلات والعادات والروتينات والذوق والحقائق الشخصية المتكررة -التعيين الافتراضي عندما لا يتم تعيين `config.promptStyle`: +التعيين الافتراضي عندما يكون `config.promptStyle` غير مضبوط: ```text message -> strict @@ -342,7 +426,7 @@ recent -> balanced full -> contextual ``` -إذا قمت بتعيين `config.promptStyle` صراحةً، فستكون لتلك القيمة الأولوية. +إذا ضبطت `config.promptStyle` صراحةً، فستُطبّق هذه القيمة المتجاوزة. مثال: @@ -352,7 +436,7 @@ promptStyle: "preference-only" ## سياسة النموذج الاحتياطي -إذا لم يتم تعيين `config.model`، يحاول Active Memory حل نموذج بهذا الترتيب: +إذا كان `config.model` غير مضبوط، تحاول Active Memory تحديد نموذج بهذا الترتيب: ```text explicit plugin model @@ -361,23 +445,23 @@ explicit plugin model -> optional configured fallback model ``` -يتحكم `config.modelFallback` في خطوة الرجوع الاحتياطي المكوّنة. +يتحكم `config.modelFallback` في خطوة الاحتياط المُعدّة. -رجوع احتياطي مخصص اختياري: +احتياط مخصص اختياري: ```json5 modelFallback: "google/gemini-3-flash" ``` -إذا لم يتم حل أي نموذج صريح أو موروث أو احتياطي مكوَّن، فإن Active Memory -يتخطى الاستدعاء في تلك الدورة. +إذا لم يُحدَّد أي نموذج صريح أو موروث أو احتياطي مُعد، فإن Active Memory +تتجاوز الاسترجاع في تلك الدورة. -يتم الاحتفاظ بـ `config.modelFallbackPolicy` فقط كحقل توافق قديم -للإعدادات الأقدم. ولم يعد يغيّر سلوك التشغيل. +يُحتفَظ بـ `config.modelFallbackPolicy` فقط كحقل توافق مهمل +للإعدادات الأقدم. ولم يعد يغيّر سلوك وقت التشغيل. -## مخارج متقدمة +## مسارات الهروب المتقدمة -هذه الخيارات ليست جزءًا من الإعداد الموصى به عمدًا. +هذه الخيارات ليست جزءًا من الإعداد الموصى به عن قصد. يمكن لـ `config.thinking` تجاوز مستوى التفكير لوكيل حظر الذاكرة الفرعي: @@ -385,36 +469,36 @@ modelFallback: "google/gemini-3-flash" thinking: "medium" ``` -القيمة الافتراضية: +الافتراضي: ```json5 thinking: "off" ``` -لا تقم بتمكين هذا افتراضيًا. يعمل Active Memory في مسار الرد، لذا فإن -وقت التفكير الإضافي يزيد مباشرة من زمن التأخير المرئي للمستخدم. +لا تفعّل هذا افتراضيًا. تعمل Active Memory ضمن مسار الرد، لذا فإن +وقت التفكير الإضافي يزيد مباشرةً من الكمون المرئي للمستخدم. -يضيف `config.promptAppend` تعليمات إضافية للمشغّل بعد مطالبة Active -Memory الافتراضية وقبل سياق المحادثة: +يضيف `config.promptAppend` تعليمات تشغيل إضافية بعد موجّه Active +Memory الافتراضي وقبل سياق المحادثة: ```json5 promptAppend: "Prefer stable long-term preferences over one-off events." ``` -يستبدل `config.promptOverride` مطالبة Active Memory الافتراضية. ولا يزال OpenClaw +يستبدل `config.promptOverride` موجّه Active Memory الافتراضي. وما يزال OpenClaw يضيف سياق المحادثة بعد ذلك: ```json5 promptOverride: "You are a memory search agent. Return NONE or one compact user fact." ``` -لا يُنصح بتخصيص المطالبة إلا إذا كنت تختبر عمدًا -عقد استدعاء مختلفًا. تمت معايرة المطالبة الافتراضية لإرجاع `NONE` -أو سياق موجز لحقائق المستخدم من أجل النموذج الرئيسي. +لا يُنصح بتخصيص الموجّه إلا إذا كنت تختبر عمدًا +عقد استرجاع مختلفًا. فقد جرى ضبط الموجّه الافتراضي لإرجاع `NONE` +أو سياق حقائق مستخدم مضغوط للنموذج الرئيسي. ### `message` -يتم إرسال أحدث رسالة مستخدم فقط. +يُرسَل أحدث رسالة مستخدم فقط. ```text Latest user message only @@ -423,16 +507,16 @@ Latest user message only استخدم هذا عندما: - تريد أسرع سلوك -- تريد أقوى انحياز نحو استدعاء التفضيلات المستقرة -- لا تحتاج الأدوار اللاحقة إلى سياق المحادثة +- تريد أقوى انحياز نحو استرجاع التفضيلات المستقرة +- لا تحتاج جولات المتابعة إلى سياق المحادثة المهلة الموصى بها: -- ابدأ بحوالي `3000` إلى `5000` مللي ثانية +- ابدأ بحوالي `3000` إلى `5000` ملّي ثانية ### `recent` -يتم إرسال أحدث رسالة مستخدم مع ذيل حديث صغير من المحادثة. +تُرسَل أحدث رسالة مستخدم مع ذيل صغير حديث من المحادثة. ```text Recent conversation tail: @@ -446,16 +530,16 @@ Latest user message: استخدم هذا عندما: -- تريد توازنًا أفضل بين السرعة والارتكاز الحواري -- تعتمد الأسئلة اللاحقة كثيرًا على الأدوار القليلة الأخيرة +- تريد توازنًا أفضل بين السرعة والارتكاز إلى المحادثة +- تعتمد أسئلة المتابعة غالبًا على آخر بضع جولات المهلة الموصى بها: -- ابدأ بحوالي `15000` مللي ثانية +- ابدأ بحوالي `15000` ملّي ثانية ### `full` -يتم إرسال المحادثة الكاملة إلى وكيل حظر الذاكرة الفرعي. +تُرسَل المحادثة الكاملة إلى وكيل حظر الذاكرة الفرعي. ```text Full conversation context: @@ -467,33 +551,33 @@ user: ... استخدم هذا عندما: -- تكون أعلى جودة للاستدعاء أهم من زمن التأخير -- تحتوي المحادثة على إعداد مهم يقع بعيدًا في سلسلة المحادثة +- تكون أقوى جودة استرجاع أهم من الكمون +- تحتوي المحادثة على إعداد مهم يعود إلى موضع بعيد في السلسلة المهلة الموصى بها: -- زدها بشكل ملحوظ مقارنةً بـ `message` أو `recent` -- ابدأ بحوالي `15000` مللي ثانية أو أكثر حسب حجم السلسلة +- زدها كثيرًا مقارنةً بـ `message` أو `recent` +- ابدأ بحوالي `15000` ملّي ثانية أو أكثر بحسب حجم السلسلة -بوجه عام، ينبغي أن تزداد المهلة مع حجم السياق: +عمومًا، يجب أن تزيد المهلة مع حجم السياق: ```text message < recent < full ``` -## الاحتفاظ بالنصوص +## استمرارية السجل -تؤدي عمليات تشغيل وكيل Active Memory الفرعي لحظر الذاكرة إلى إنشاء نص -`session.jsonl` حقيقي أثناء استدعاء وكيل حظر الذاكرة الفرعي. +تنشئ تشغيلات وكيل حظر الذاكرة الفرعي الخاصة بـ Active memory سجل `session.jsonl` +حقيقيًا أثناء استدعاء وكيل حظر الذاكرة الفرعي. -بشكل افتراضي، يكون هذا النص مؤقتًا: +افتراضيًا، يكون هذا السجل مؤقتًا: -- يُكتب إلى دليل مؤقت +- يُكتَب في دليل مؤقت - يُستخدم فقط لتشغيل وكيل حظر الذاكرة الفرعي -- يُحذف فورًا بعد انتهاء التشغيل +- يُحذف مباشرةً بعد انتهاء التشغيل -إذا كنت تريد الاحتفاظ بنصوص وكيل حظر الذاكرة الفرعي هذه على القرص لأغراض التصحيح أو -الفحص، فقم بتمكين الاحتفاظ صراحةً: +إذا أردت الاحتفاظ بسجلات وكيل حظر الذاكرة الفرعي هذه على القرص لأغراض التصحيح أو +الفحص، ففعّل الاستمرارية صراحةً: ```json5 { @@ -512,26 +596,26 @@ message < recent < full } ``` -عند التمكين، يخزّن Active Memory النصوص في دليل منفصل تحت -مجلد جلسات الوكيل المستهدف، وليس في مسار نص محادثة المستخدم الرئيسي. +عند التمكين، تخزّن active memory السجلات في دليل منفصل داخل +مجلد جلسات الوكيل المستهدف، وليس ضمن مسار سجل محادثة المستخدم الرئيسي. -يكون التخطيط الافتراضي من حيث المفهوم كما يلي: +يكون التخطيط الافتراضي من حيث المفهوم كالتالي: ```text agents//sessions/active-memory/.jsonl ``` -يمكنك تغيير الدليل الفرعي النسبي باستخدام `config.transcriptDir`. +يمكنك تغيير الدليل الفرعي النسبي عبر `config.transcriptDir`. استخدم هذا بحذر: -- يمكن أن تتراكم نصوص وكيل حظر الذاكرة الفرعي بسرعة في الجلسات النشطة -- يمكن لوضع الاستعلام `full` أن يكرر قدرًا كبيرًا من سياق المحادثة -- تحتوي هذه النصوص على سياق مطالبة مخفي وذكريات مستدعاة +- قد تتراكم سجلات وكيل حظر الذاكرة الفرعي بسرعة في الجلسات المزدحمة +- قد يكرر وضع الاستعلام `full` قدرًا كبيرًا من سياق المحادثة +- تحتوي هذه السجلات على سياق موجّه خفي وذكريات مسترجعة ## الإعدادات -توجد جميع إعدادات Active Memory تحت: +توجد جميع إعدادات active memory ضمن: ```text plugins.entries.active-memory @@ -539,32 +623,32 @@ plugins.entries.active-memory أهم الحقول هي: -| المفتاح | النوع | المعنى | -| --------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | -| `enabled` | `boolean` | يفعّل الـ Plugin نفسه | -| `config.agents` | `string[]` | معرّفات الوكلاء التي يمكنها استخدام Active Memory | -| `config.model` | `string` | مرجع نموذج اختياري لوكيل حظر الذاكرة الفرعي؛ وعند عدم تعيينه، يستخدم Active Memory نموذج الجلسة الحالي | -| `config.queryMode` | `"message" \| "recent" \| "full"` | يتحكم في مقدار المحادثة التي يراها وكيل حظر الذاكرة الفرعي | -| `config.promptStyle` | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | يتحكم في مدى اندفاع أو صرامة وكيل حظر الذاكرة الفرعي عند اتخاذ قرار بشأن إرجاع الذاكرة | -| `config.thinking` | `"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive"` | تجاوز متقدم لمستوى التفكير لوكيل حظر الذاكرة الفرعي؛ والقيمة الافتراضية `off` للسرعة | -| `config.promptOverride` | `string` | استبدال متقدم كامل للمطالبة؛ غير موصى به للاستخدام العادي | -| `config.promptAppend` | `string` | تعليمات إضافية متقدمة تُلحق بالمطالبة الافتراضية أو المستبدلة | -| `config.timeoutMs` | `number` | مهلة قصوى لوكيل حظر الذاكرة الفرعي | -| `config.maxSummaryChars` | `number` | الحد الأقصى لإجمالي الأحرف المسموح بها في ملخص active-memory | -| `config.logging` | `boolean` | يُصدر سجلات Active Memory أثناء الضبط | -| `config.persistTranscripts` | `boolean` | يحتفظ بنصوص وكيل حظر الذاكرة الفرعي على القرص بدلًا من حذف الملفات المؤقتة | -| `config.transcriptDir` | `string` | دليل نصوص نسبي لوكيل حظر الذاكرة الفرعي تحت مجلد جلسات الوكيل | +| المفتاح | النوع | المعنى | +| -------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| `enabled` | `boolean` | يفعّل Plugin نفسه | +| `config.agents` | `string[]` | معرّفات الوكلاء التي يمكنها استخدام active memory | +| `config.model` | `string` | مرجع نموذج اختياري لوكيل حظر الذاكرة الفرعي؛ وعند عدم ضبطه تستخدم active memory نموذج الجلسة الحالي | +| `config.queryMode` | `"message" \| "recent" \| "full"` | يتحكم في مقدار المحادثة الذي يراه وكيل حظر الذاكرة الفرعي | +| `config.promptStyle` | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | يتحكم في مدى حماس أو صرامة وكيل حظر الذاكرة الفرعي عند تقرير ما إذا كان سيعيد ذاكرة | +| `config.thinking` | `"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive"` | تجاوز تفكير متقدم لوكيل حظر الذاكرة الفرعي؛ والافتراضي `off` لأجل السرعة | +| `config.promptOverride` | `string` | استبدال كامل متقدم للموجّه؛ غير موصى به للاستخدام العادي | +| `config.promptAppend` | `string` | تعليمات إضافية متقدمة تُلحَق بالموجّه الافتراضي أو المتجاوز | +| `config.timeoutMs` | `number` | مهلة قصوى ثابتة لوكيل حظر الذاكرة الفرعي | +| `config.maxSummaryChars` | `number` | الحد الأقصى لإجمالي الأحرف المسموح بها في ملخص active-memory | +| `config.logging` | `boolean` | يخرج سجلات active memory أثناء الضبط | +| `config.persistTranscripts` | `boolean` | يحتفظ بسجلات وكيل حظر الذاكرة الفرعي على القرص بدل حذف الملفات المؤقتة | +| `config.transcriptDir` | `string` | دليل سجلات نسبي لوكيل حظر الذاكرة الفرعي داخل مجلد جلسات الوكيل | -حقول مفيدة للضبط: +حقول ضبط مفيدة: -| المفتاح | النوع | المعنى | -| ----------------------------- | -------- | ------------------------------------------------------------- | -| `config.maxSummaryChars` | `number` | الحد الأقصى لإجمالي الأحرف المسموح بها في ملخص active-memory | -| `config.recentUserTurns` | `number` | الأدوار السابقة للمستخدم التي تُضمَّن عندما يكون `queryMode` هو `recent` | -| `config.recentAssistantTurns` | `number` | الأدوار السابقة للمساعد التي تُضمَّن عندما يكون `queryMode` هو `recent` | -| `config.recentUserChars` | `number` | الحد الأقصى للأحرف لكل دور مستخدم حديث | -| `config.recentAssistantChars` | `number` | الحد الأقصى للأحرف لكل دور مساعد حديث | -| `config.cacheTtlMs` | `number` | إعادة استخدام الذاكرة المؤقتة للاستعلامات المتطابقة المتكررة | +| المفتاح | النوع | المعنى | +| ---------------------------- | -------- | ----------------------------------------------------------- | +| `config.maxSummaryChars` | `number` | الحد الأقصى لإجمالي الأحرف المسموح بها في ملخص active-memory | +| `config.recentUserTurns` | `number` | جولات المستخدم السابقة التي تُضمَّن عندما يكون `queryMode` هو `recent` | +| `config.recentAssistantTurns` | `number` | جولات المساعد السابقة التي تُضمَّن عندما يكون `queryMode` هو `recent` | +| `config.recentUserChars` | `number` | الحد الأقصى للأحرف لكل جولة مستخدم حديثة | +| `config.recentAssistantChars` | `number` | الحد الأقصى للأحرف لكل جولة مساعد حديثة | +| `config.cacheTtlMs` | `number` | إعادة استخدام التخزين المؤقت للاستعلامات المتطابقة المتكررة | ## الإعداد الموصى به @@ -590,89 +674,90 @@ plugins.entries.active-memory } ``` -إذا كنت تريد فحص السلوك المباشر أثناء الضبط، فاستخدم `/verbose on` من أجل +إذا أردت فحص السلوك المباشر أثناء الضبط، فاستخدم `/verbose on` من أجل سطر الحالة العادي و`/trace on` من أجل ملخص تصحيح active-memory بدلًا -من البحث عن أمر تصحيح منفصل لـ active-memory. في قنوات الدردشة، تُرسل هذه -الأسطر التشخيصية بعد رد المساعد الرئيسي بدلًا من قبله. +من البحث عن أمر تصحيح منفصل لـ active-memory. وفي قنوات الدردشة، تُرسَل +هذه الأسطر التشخيصية بعد رد المساعد الرئيسي لا قبله. ثم انتقل إلى: -- `message` إذا كنت تريد زمن تأخير أقل -- `full` إذا قررت أن السياق الإضافي يستحق وكيل حظر الذاكرة الفرعي الأبطأ +- `message` إذا أردت كمونًا أقل +- `full` إذا قررت أن السياق الإضافي يستحق وكيل حظر ذاكرة فرعيًا أبطأ ## تصحيح الأخطاء -إذا لم يظهر Active Memory في المكان الذي تتوقعه: +إذا لم تظهر active memory في الموضع الذي تتوقعه: -1. تأكد من أن الـ Plugin مفعّل تحت `plugins.entries.active-memory.enabled`. -2. تأكد من أن معرّف الوكيل الحالي مدرج في `config.agents`. -3. تأكد من أنك تختبر من خلال جلسة دردشة تفاعلية دائمة. +1. أكّد أن Plugin مفعّل ضمن `plugins.entries.active-memory.enabled`. +2. أكّد أن معرّف الوكيل الحالي مدرج في `config.agents`. +3. أكّد أنك تختبر من خلال جلسة دردشة تفاعلية دائمة. 4. فعّل `config.logging: true` وراقب سجلات Gateway. -5. تحقّق من أن البحث في الذاكرة نفسه يعمل باستخدام `openclaw memory status --deep`. +5. تحقّق من أن بحث الذاكرة نفسه يعمل عبر `openclaw memory status --deep`. -إذا كانت نتائج الذاكرة مزعجة، فشدّد: +إذا كانت نتائج الذاكرة كثيرة التشويش، فشدّد هذا الإعداد: - `maxSummaryChars` -إذا كان Active Memory بطيئًا جدًا: +إذا كانت active memory بطيئة جدًا: - خفّض `queryMode` - خفّض `timeoutMs` -- قلّل عدد الأدوار الحديثة -- قلّل حدود الأحرف لكل دور +- قلّل عدد الجولات الحديثة +- قلّل حدود الأحرف لكل جولة -## مشكلات شائعة +## المشكلات الشائعة -### تغيّر مزوّد التضمين بشكل غير متوقع +### تغيّر موفر التضمين بشكل غير متوقع -يستخدم Active Memory مسار `memory_search` العادي تحت -`agents.defaults.memorySearch`. وهذا يعني أن إعداد مزوّد التضمين يكون -مطلوبًا فقط عندما يتطلب إعداد `memorySearch` لديك تضمينات للسلوك الذي تريده. +تستخدم Active Memory مسار `memory_search` العادي ضمن +`agents.defaults.memorySearch`. وهذا يعني أن إعداد موفر التضمين يكون فقط +مطلبًا عندما يتطلب إعداد `memorySearch` لديك تضمينات للسلوك +الذي تريده. عمليًا: -- إعداد المزوّد الصريح **مطلوب** إذا كنت تريد مزوّدًا غير - مكتشف تلقائيًا، مثل `ollama` -- إعداد المزوّد الصريح **مطلوب** إذا لم يحل الاكتشاف التلقائي - أي مزوّد تضمين قابل للاستخدام لبيئتك -- إعداد المزوّد الصريح **موصى به بشدة** إذا كنت تريد - اختيار مزوّد حتمي بدلًا من "أول متاح يفوز" -- إعداد المزوّد الصريح عادةً **غير مطلوب** إذا كان الاكتشاف التلقائي يحل بالفعل - المزوّد الذي تريده وكان هذا المزوّد مستقرًا في بيئة النشر لديك +- يكون إعداد الموفر الصريح **مطلوبًا** إذا كنت تريد موفرًا لا يُكتشَف + تلقائيًا، مثل `ollama` +- يكون إعداد الموفر الصريح **مطلوبًا** إذا لم يحلّ الاكتشاف التلقائي + أي موفر تضمين صالح للاستخدام في بيئتك +- يكون إعداد الموفر الصريح **موصى به بشدة** إذا كنت تريد اختيارًا + حتميًا للموفر بدلًا من "أول متاح يفوز" +- لا يكون إعداد الموفر الصريح **مطلوبًا عادةً** إذا كان الاكتشاف التلقائي + يحلّ بالفعل الموفّر الذي تريده وكان هذا الموفّر مستقرًا في بيئة نشرِك -إذا لم يتم تعيين `memorySearch.provider`، فسيكتشف OpenClaw أول -مزوّد تضمين متاح تلقائيًا. +إذا لم يكن `memorySearch.provider` مضبوطًا، فإن OpenClaw يكتشف تلقائيًا +أول موفر تضمين متاح. -قد يكون ذلك مربكًا في عمليات النشر الفعلية: +وقد يكون هذا مربكًا في عمليات النشر الفعلية: -- قد يؤدي توفر مفتاح API جديد إلى تغيير المزوّد الذي يستخدمه البحث في الذاكرة -- قد يجعل أمر واحد أو سطح تشخيصات المزوّد المحدد يبدو - مختلفًا عن المسار الذي تستخدمه فعلًا أثناء مزامنة الذاكرة المباشرة أو +- قد يؤدي مفتاح API أصبح متاحًا حديثًا إلى تغيير الموفّر الذي يستخدمه بحث الذاكرة +- قد يجعل أحد الأوامر أو أسطح التشخيص الموفّر المحدد يبدو + مختلفًا عن المسار الذي تضربه فعليًا أثناء مزامنة الذاكرة المباشرة أو تهيئة البحث -- قد تفشل المزوّدات المستضافة بسبب أخطاء الحصة أو حد المعدل التي لا تظهر - إلا عندما يبدأ Active Memory في إصدار عمليات بحث الاستدعاء قبل كل رد +- قد تفشل الموفرات المستضافة بسبب تجاوز الحصة أو أخطاء حد المعدل التي لا تظهر + إلا عندما تبدأ Active Memory بإصدار عمليات بحث استرجاع قبل كل رد -يمكن لـ Active Memory أن يعمل أيضًا بدون تضمينات عندما يستطيع `memory_search` -العمل في وضع متدهور يعتمد على المطابقة اللفظية فقط، وهذا يحدث عادةً عندما لا يمكن -حل أي مزوّد تضمين. +ما تزال Active Memory قادرة على العمل من دون تضمينات عندما يكون `memory_search` +قادرًا على العمل في وضع متدهور يعتمد على المطابقة اللفظية فقط، وهو ما يحدث عادةً +عندما يتعذر تحديد أي موفر تضمين. -لا تفترض وجود نفس الرجوع الاحتياطي عند فشل تشغيل المزوّد مثل استنفاد -الحصة أو حدود المعدل أو أخطاء الشبكة/المزوّد أو غياب النماذج المحلية/البعيدة -بعد أن يكون قد تم بالفعل اختيار المزوّد. +لا تفترض وجود البديل الاحتياطي نفسه عند فشل وقت تشغيل الموفّر مثل نفاد +الحصة أو حدود المعدل أو أخطاء الشبكة/الموفّر أو غياب النماذج المحلية/البعيدة +بعد أن يكون قد جرى بالفعل اختيار موفّر. عمليًا: -- إذا تعذر حل أي مزوّد تضمين، فقد يتدهور `memory_search` إلى - استرجاع لفظي فقط -- إذا تم حل مزوّد تضمين ثم فشل أثناء التشغيل، فإن OpenClaw لا - يضمن حاليًا رجوعًا احتياطيًا لفظيًا لهذا الطلب -- إذا كنت تحتاج إلى اختيار مزوّد حتمي، فقم بتثبيت +- إذا تعذر تحديد أي موفر تضمين، فقد يتدهور `memory_search` إلى + استرجاع يعتمد على المطابقة اللفظية فقط +- إذا جرى تحديد موفر تضمين ثم فشل وقت التشغيل لديه، فإن OpenClaw + لا يضمن حاليًا بديلًا احتياطيًا لفظيًا لذلك الطلب +- إذا كنت بحاجة إلى اختيار حتمي للموفر، فثبّت `agents.defaults.memorySearch.provider` -- إذا كنت تحتاج إلى تجاوز فشل المزوّد عند أخطاء التشغيل، فقم بتهيئة +- إذا كنت بحاجة إلى تجاوز فشل الموفّر عند أخطاء وقت التشغيل، فاضبط `agents.defaults.memorySearch.fallback` صراحةً -إذا كنت تعتمد على استدعاء مدعوم بالتضمين أو فهرسة متعددة الوسائط أو مزوّد -محلي/بعيد محدد، فثبّت المزوّد صراحةً بدلًا من الاعتماد على +إذا كنت تعتمد على استرجاع مدعوم بالتضمينات، أو فهرسة متعددة الوسائط، أو موفر +محلي/بعيد محدد، فثبّت الموفّر صراحةً بدلًا من الاعتماد على الاكتشاف التلقائي. أمثلة شائعة على التثبيت: @@ -722,8 +807,8 @@ Ollama: } ``` -إذا كنت تتوقع تجاوز فشل المزوّد عند أخطاء التشغيل مثل استنفاد الحصة، -فإن تثبيت مزوّد وحده لا يكفي. قم بتهيئة رجوع احتياطي صريح أيضًا: +إذا كنت تتوقع تجاوز فشل الموفّر عند أخطاء وقت التشغيل مثل نفاد الحصة، +فإن تثبيت موفّر وحده لا يكفي. اضبط أيضًا بديلًا احتياطيًا صريحًا: ```json5 { @@ -738,32 +823,32 @@ Ollama: } ``` -### تصحيح مشكلات المزوّد +### تصحيح مشكلات الموفّر -إذا كان Active Memory بطيئًا أو فارغًا أو يبدو أنه يبدّل المزوّدات بشكل غير متوقع: +إذا كانت Active Memory بطيئة أو فارغة أو بدا أنها تغيّر الموفّرات بشكل غير متوقع: - راقب سجلات Gateway أثناء إعادة إنتاج المشكلة؛ وابحث عن أسطر مثل `active-memory: ... start|done` أو `memory sync failed (search-bootstrap)` أو - أخطاء التضمين الخاصة بالمزوّد -- فعّل `/trace on` لإظهار ملخص تصحيح Active Memory المملوك للـ Plugin داخل + أخطاء التضمين الخاصة بموفّر معين +- فعّل `/trace on` لإظهار ملخص تصحيح Active Memory المملوك لـ Plugin داخل الجلسة -- فعّل `/verbose on` إذا كنت تريد أيضًا سطر الحالة العادي - `🧩 Active Memory: ...` بعد كل رد -- شغّل `openclaw memory status --deep` لفحص الواجهة الخلفية الحالية - للبحث في الذاكرة وصحة الفهرس -- تحقّق من `agents.defaults.memorySearch.provider` وما يتعلق به من إعدادات auth/config للتأكد - من أن المزوّد الذي تتوقعه هو بالفعل المزوّد الذي يمكن حله وقت التشغيل -- إذا كنت تستخدم `ollama`، فتحقّق من أن نموذج التضمين المكوّن مثبّت، على - سبيل المثال `ollama list` +- فعّل `/verbose on` إذا كنت تريد أيضًا سطر الحالة العادي `🧩 Active Memory: ...` + بعد كل رد +- شغّل `openclaw memory status --deep` لفحص الواجهة الخلفية الحالية لبحث الذاكرة + وصحة الفهرس +- تحقّق من `agents.defaults.memorySearch.provider` وما يتصل به من مصادقة/إعدادات للتأكد + من أن الموفّر الذي تتوقعه هو فعلًا القادر على التحديد وقت التشغيل +- إذا كنت تستخدم `ollama`، فتحقّق من أن نموذج التضمين المضبوط مثبّت، مثلًا + `ollama list` -مثال على حلقة تصحيح الأخطاء: +مثال على دورة تصحيح: ```text -1. ابدأ Gateway وراقب سجلاته -2. في جلسة الدردشة، شغّل /trace on -3. أرسل رسالة واحدة من المفترض أن تؤدي إلى تشغيل Active Memory -4. قارن سطر التصحيح المرئي في الدردشة بأسطر سجل Gateway -5. إذا كان اختيار المزوّد ملتبسًا، فثبّت agents.defaults.memorySearch.provider صراحةً +1. Start the gateway and watch its logs +2. In the chat session, run /trace on +3. Send one message that should trigger Active Memory +4. Compare the chat-visible debug line with the gateway log lines +5. If provider choice is ambiguous, pin agents.defaults.memorySearch.provider explicitly ``` مثال: @@ -781,7 +866,7 @@ Ollama: } ``` -أو، إذا كنت تريد تضمينات Gemini: +أو إذا كنت تريد تضمينات Gemini: ```json5 { @@ -795,11 +880,11 @@ Ollama: } ``` -بعد تغيير المزوّد، أعد تشغيل Gateway ونفّذ اختبارًا جديدًا مع +بعد تغيير الموفّر، أعد تشغيل Gateway وأجرِ اختبارًا جديدًا باستخدام `/trace on` حتى يعكس سطر تصحيح Active Memory مسار التضمين الجديد. ## الصفحات ذات الصلة -- [البحث في الذاكرة](/ar/concepts/memory-search) +- [بحث الذاكرة](/ar/concepts/memory-search) - [مرجع إعدادات الذاكرة](/ar/reference/memory-config) - [إعداد Plugin SDK](/ar/plugins/sdk-setup) diff --git a/docs/ar/gateway/protocol.md b/docs/ar/gateway/protocol.md index 52d8353a4..ed8c75530 100644 --- a/docs/ar/gateway/protocol.md +++ b/docs/ar/gateway/protocol.md @@ -1,30 +1,30 @@ --- read_when: - - تنفيذ عملاء Gateway WS أو تحديثهم - - تصحيح عدم تطابق البروتوكول أو حالات فشل الاتصال + - تنفيذ عملاء WS لـ Gateway أو تحديثهم + - تصحيح أخطاء عدم تطابق البروتوكول أو حالات فشل الاتصال - إعادة توليد مخطط/نماذج البروتوكول -summary: 'بروتوكول Gateway WebSocket: المصافحة، الإطارات، وإدارة الإصدارات' +summary: 'بروتوكول WebSocket لـ Gateway: المصافحة، الإطارات، إدارة الإصدارات' title: بروتوكول Gateway x-i18n: - generated_at: "2026-04-10T07:17:27Z" + generated_at: "2026-04-16T07:18:16Z" model: gpt-5.4 provider: openai - source_hash: 83c820c46d4803d571c770468fd6782619eaa1dca253e156e8087dec735c127f + source_hash: 683e61ebe993a2d739bc34860060b0e3eda36b5c57267a2bcc03d177ec612fb3 source_path: gateway/protocol.md workflow: 15 --- # بروتوكول Gateway ‏(WebSocket) -بروتوكول Gateway WS هو **مستوى التحكم الوحيد + نقل العقد** في +يُعد بروتوكول WS الخاص بـ Gateway **مستوى التحكم الوحيد + ناقل العقد** لـ OpenClaw. تتصل جميع العملاء (CLI، وواجهة الويب، وتطبيق macOS، وعقد iOS/Android، -والعقد عديمة الواجهة) عبر WebSocket وتُعلن **الدور** + **النطاق** -في وقت المصافحة. +والعقد عديمة الواجهة) عبر WebSocket وتُعلن **الدور** + **النطاق** الخاصين بها وقت +المصافحة. ## النقل -- WebSocket، إطارات نصية مع حمولات JSON. -- **يجب** أن يكون الإطار الأول طلب `connect`. +- WebSocket، وإطارات نصية بحمولة JSON. +- يجب أن يكون الإطار الأول **بالضرورة** طلب `connect`. ## المصافحة (`connect`) @@ -80,10 +80,24 @@ Gateway → العميل: "type": "res", "id": "…", "ok": true, - "payload": { "type": "hello-ok", "protocol": 3, "policy": { "tickIntervalMs": 15000 } } + "payload": { + "type": "hello-ok", + "protocol": 3, + "server": { "version": "…", "connId": "…" }, + "features": { "methods": ["…"], "events": ["…"] }, + "snapshot": { "…": "…" }, + "policy": { + "maxPayload": 26214400, + "maxBufferedBytes": 52428800, + "tickIntervalMs": 15000 + } + } } ``` +`server` و`features` و`snapshot` و`policy` كلها مطلوبة بحسب المخطط +(`src/gateway/protocol/schema/frames.ts`). ويُعد كل من `auth` و`canvasHostUrl` اختياريًا. + عند إصدار رمز جهاز مميز، يتضمن `hello-ok` أيضًا: ```json @@ -96,7 +110,7 @@ Gateway → العميل: } ``` -أثناء تسليم التمهيد الموثوق، قد يتضمن `hello-ok.auth` أيضًا إدخالات دور إضافية +أثناء تسليم bootstrap الموثوق، قد يتضمن `hello-ok.auth` أيضًا إدخالات أدوار إضافية مقيدة ضمن `deviceTokens`: ```json @@ -116,14 +130,14 @@ Gateway → العميل: } ``` -في تدفق التمهيد المدمج للعقدة/المشغّل، يظل رمز العقدة الأساسي -`scopes: []` وأي رمز مشغّل يتم تسليمه يظل مقيدًا بقائمة السماح الخاصة -بمشغّل التمهيد (`operator.approvals`، `operator.read`، -`operator.talk.secrets`، `operator.write`). تظل فحوصات نطاق التمهيد -مسبوقة بالدور: إدخالات المشغّل تلبّي فقط طلبات المشغّل، والأدوار غير المشغّل -تظل بحاجة إلى نطاقات ضمن بادئة دورها الخاصة. +في تدفق bootstrap المدمج للعقدة/المشغّل، يبقى الرمز المميز الأساسي للعقدة +`scopes: []`، وأي رمز مميز للمشغّل يتم تسليمه يبقى مقيدًا بقائمة السماح الخاصة +بمشغّل bootstrap (`operator.approvals` و`operator.read` و`operator.talk.secrets` +و`operator.write`). وتظل فحوصات النطاق في bootstrap ذات بادئة مرتبطة بالدور: +إدخالات المشغّل تلبّي فقط طلبات المشغّل، بينما لا تزال الأدوار غير التابعة +للمشغّل تحتاج إلى نطاقات ضمن بادئة الدور الخاصة بها. -### مثال عقدة +### مثال للعقدة ```json { @@ -160,18 +174,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/واجهة المستخدم/الأتمتة). -- `node` = مضيف الإمكانات (camera/screen/canvas/system.run). +- `operator` = عميل مستوى التحكم (CLI/UI/الأتمتة). +- `node` = مضيف القدرات (camera/screen/canvas/system.run). ### النطاقات (`operator`) @@ -187,430 +201,458 @@ Gateway → العميل: يتطلب `talk.config` مع `includeSecrets: true` النطاق `operator.talk.secrets` (أو `operator.admin`). -قد تطلب أساليب Gateway RPC المسجلة من الإضافات نطاق مشغّل خاصًا بها، لكن -البوادئ الإدارية الأساسية المحجوزة (`config.*`، `exec.approvals.*`، `wizard.*`، -`update.*`) تُحل دائمًا إلى `operator.admin`. +قد تطلب طرق Gateway RPC المسجلة من Plugin نطاق مشغّل خاصًا بها، لكن بادئات +الإدارة الأساسية المحجوزة (`config.*` و`exec.approvals.*` و`wizard.*` و`update.*`) +تُحل دائمًا إلى `operator.admin`. -نطاق الأسلوب هو البوابة الأولى فقط. بعض أوامر الشرطة المائلة التي يتم الوصول إليها عبر -`chat.send` تطبق فحوصات أكثر صرامة على مستوى الأمر فوق ذلك. على سبيل المثال، -تتطلب عمليات الكتابة المستمرة في `/config set` و`/config unset` +نطاق الطريقة ليس سوى البوابة الأولى. بعض أوامر الشرطة المائلة التي يتم الوصول +إليها عبر `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`: فئات إمكانات عالية المستوى. +- `caps`: فئات القدرات عالية المستوى. - `commands`: قائمة سماح الأوامر للاستدعاء. - `permissions`: مفاتيح تبديل دقيقة (مثل `screen.record` و`camera.capture`). -يتعامل Gateway مع هذه القيم على أنها **مطالبات** ويفرض قوائم السماح من جهة الخادم. +يتعامل Gateway مع هذه القيم على أنها **مطالبات** ويفرض قوائم السماح على جانب الخادم. -## الوجود +## الحضور - يعيد `system-presence` إدخالات مفهرسة بحسب هوية الجهاز. -- تتضمن إدخالات الوجود `deviceId` و`roles` و`scopes` حتى تتمكن واجهات المستخدم من عرض صف واحد لكل جهاز +- تتضمن إدخالات الحضور `deviceId` و`roles` و`scopes` لكي تتمكن واجهات المستخدم من عرض صف واحد لكل جهاز حتى عندما يتصل بصفته **operator** و**node** معًا. -## عائلات أساليب RPC الشائعة +## عائلات طرق RPC الشائعة -هذه الصفحة ليست تفريغًا مولدًا كاملًا، لكن سطح WS العام أوسع -من أمثلة المصافحة/المصادقة أعلاه. هذه هي عائلات الأساليب الرئيسية التي يعرضها +هذه الصفحة ليست تفريغًا مولدًا كاملًا، لكن سطح WS العام أوسع من أمثلة +المصافحة/المصادقة الواردة أعلاه. وهذه هي عائلات الطرق الرئيسية التي يعرّضها Gateway اليوم. -`hello-ok.features.methods` هي قائمة اكتشاف متحفظة مبنية من -`src/gateway/server-methods-list.ts` بالإضافة إلى صادرات أساليب الإضافات/القنوات المحملة. -تعامل معها على أنها لاكتشاف الميزات، وليس كتفريغ مولد لكل مساعد قابل للاستدعاء -منفذ في `src/gateway/server-methods/*.ts`. +تُعد `hello-ok.features.methods` قائمة اكتشاف محافظة مبنية من +`src/gateway/server-methods-list.ts` إضافةً إلى صادرات الطرق المحمّلة من +Plugin/channel. تعامل معها على أنها لاكتشاف الميزات، لا على أنها تفريغ مولد +لكل مساعد قابل للاستدعاء مُنفّذ في `src/gateway/server-methods/*.ts`. ### النظام والهوية -- يعيد `health` لقطة سلامة Gateway المخزنة مؤقتًا أو التي تم فحصها حديثًا. -- يعيد `status` ملخص Gateway بأسلوب `/status`؛ وتُضمن الحقول الحساسة - فقط لعملاء المشغّل ذوي نطاق الإدارة. -- يعيد `gateway.identity.get` هوية جهاز Gateway المستخدمة في تدفقات - الترحيل والاقتران. -- يعيد `system-presence` لقطة الوجود الحالية للأجهزة المتصلة من نوع +- يعيد `health` لقطة الحالة الصحية المخزنة مؤقتًا لـ gateway أو التي جرى فحصها حديثًا. +- يعيد `status` ملخص gateway بأسلوب `/status`؛ وتُضمَّن الحقول الحساسة فقط + لعملاء المشغّل ذوي نطاق الإدارة. +- يعيد `gateway.identity.get` هوية جهاز gateway المستخدمة في تدفقات relay + والإقران. +- يعيد `system-presence` لقطة الحضور الحالية للأجهزة المتصلة من نوع operator/node. -- يُلحق `system-event` حدث نظام ويمكنه تحديث/بث سياق الوجود. -- يعيد `last-heartbeat` أحدث حدث نبضة قلب محفوظ. -- يبدّل `set-heartbeats` معالجة نبضات القلب على Gateway. +- يضيف `system-event` حدث نظام ويمكنه تحديث/بث سياق الحضور. +- يعيد `last-heartbeat` أحدث حدث Heartbeat محفوظ. +- يبدّل `set-heartbeats` معالجة Heartbeat على الـ gateway. ### النماذج والاستخدام - يعيد `models.list` فهرس النماذج المسموح بها وقت التشغيل. -- يعيد `usage.status` نوافذ استخدام المزود/ملخصات الحصة المتبقية. -- يعيد `usage.cost` ملخصات تكلفة الاستخدام المجمعة لنطاق تاريخ. +- يعيد `usage.status` نوافذ استخدام المزوّد/ملخصات الحصة المتبقية. +- يعيد `usage.cost` ملخصات تكلفة الاستخدام المجمعة لنطاق زمني. - يعيد `doctor.memory.status` جاهزية الذاكرة المتجهية / التضمين لمساحة عمل - الوكيل الافتراضي النشطة. + الوكيل الافتراضية النشطة. - يعيد `sessions.usage` ملخصات الاستخدام لكل جلسة. -- يعيد `sessions.usage.timeseries` استخدامًا كسلسلة زمنية لجلسة واحدة. +- يعيد `sessions.usage.timeseries` سلسلة زمنية للاستخدام لجلسة واحدة. - يعيد `sessions.usage.logs` إدخالات سجل الاستخدام لجلسة واحدة. ### القنوات ومساعدات تسجيل الدخول -- يعيد `channels.status` ملخصات حالة القنوات/الإضافات المدمجة والمجمعة. -- يسجل `channels.logout` الخروج من قناة/حساب محدد حيث تدعم القناة +- يعيد `channels.status` ملخصات حالة القنوات/Plugin المدمجة والمجمعة. +- يسجّل `channels.logout` الخروج من قناة/حساب محدد حيث تدعم القناة تسجيل الخروج. -- يبدأ `web.login.start` تدفق تسجيل دخول QR/الويب لمزود قناة الويب الحالي +- يبدأ `web.login.start` تدفق تسجيل دخول QR/الويب لمزوّد قناة الويب الحالي القادر على QR. -- ينتظر `web.login.wait` اكتمال تدفق تسجيل دخول QR/الويب هذا ويبدأ - القناة عند النجاح. -- يرسل `push.test` إشعار APNs تجريبيًا إلى عقدة iOS مسجلة. -- يعيد `voicewake.get` محفزات كلمة التنبيه المخزنة. -- يحدّث `voicewake.set` محفزات كلمة التنبيه ويبث التغيير. +- ينتظر `web.login.wait` اكتمال تدفق تسجيل دخول QR/الويب هذا ويبدأ القناة + عند النجاح. +- يرسل `push.test` دفعة APNs اختبارية إلى عقدة iOS مسجلة. +- يعيد `voicewake.get` مشغلات كلمة التنبيه المخزنة. +- يحدّث `voicewake.set` مشغلات كلمة التنبيه ويبث التغيير. ### المراسلة والسجلات -- `send` هو RPC التسليم الصادر المباشر لعمليات الإرسال الموجهة إلى - قناة/حساب/سلسلة محادثة خارج مشغّل الدردشة. -- يعيد `logs.tail` ذيل سجل ملفات Gateway المكوّن مع عناصر تحكم - بالمؤشر/الحد والحد الأقصى للبايتات. +- يُعد `send` RPC التسليم الصادر المباشر لعمليات الإرسال المستهدفة إلى + القناة/الحساب/المحادثة خارج مشغّل الدردشة. +- يعيد `logs.tail` ذيل سجل ملفات gateway المهيأ مع عناصر التحكم + cursor/limit والحد الأقصى للبايتات. ### 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.speak` بتوليف الكلام عبر مزود كلام Talk النشط. +- يعيد `tts.status` حالة تمكين TTS، والمزوّد النشط، ومزوّدي الاحتياط، + وحالة تهيئة المزوّد. +- يعيد `tts.providers` قائمة مزوّدي TTS الظاهرين. - يبدّل `tts.enable` و`tts.disable` حالة تفضيلات TTS. -- يحدّث `tts.setProvider` مزود TTS المفضل. -- يشغّل `tts.convert` تحويل نص إلى كلام لمرة واحدة. +- يحدّث `tts.setProvider` مزوّد TTS المفضل. +- ينفّذ `tts.convert` تحويل نص إلى كلام لمرة واحدة. -### الأسرار والإعداد والتحديث والمعالج +### الأسرار والتهيئة والتحديث والمعالج -- يعيد `secrets.reload` حل SecretRefs النشطة ويبدّل حالة الأسرار وقت التشغيل +- يعيد `secrets.reload` حل SecretRefs النشطة ويستبدل حالة الأسرار وقت التشغيل فقط عند النجاح الكامل. - يحل `secrets.resolve` تعيينات الأسرار المستهدفة بالأوامر لمجموعة أوامر/أهداف محددة. -- يعيد `config.get` لقطة الإعداد الحالية وتجزئتها. -- يكتب `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`، والإصدار، وبيانات التوليد الوصفية، بما في ذلك - بيانات مخطط الإضافات + القنوات الوصفية عندما يكون وقت التشغيل قادرًا على تحميلها. يتضمن المخطط - بيانات `title` / `description` الوصفية للحقول المشتقة من نفس التسميات + بيانات مخطط Plugin + channel الوصفية عندما يتمكن وقت التشغيل من تحميلها. يتضمن + المخطط بيانات الحقول `title` / `description` المشتقة من نفس التسميات ونصوص المساعدة التي تستخدمها واجهة المستخدم، بما في ذلك الفروع المتداخلة للكائنات، والرموز العامة، وعناصر المصفوفات، وتركيبات - `anyOf` / `oneOf` / `allOf` عندما تكون وثائق الحقول المطابقة موجودة. -- يعيد `config.schema.lookup` حمولة بحث مقيّدة بالمسار لمسار إعداد واحد: - المسار الموحّد، وعقدة مخطط سطحية، و`hint` + `hintPath` المطابقين، - وملخصات الأبناء المباشرين للتعمق في واجهة المستخدم/CLI. - - تحتفظ عقد مخطط البحث بوثائق المستخدم والحقول الشائعة للتحقق: + `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`، بالإضافة إلى `hint` / `hintPath` المطابقين. -- يشغّل `update.run` تدفق تحديث Gateway ويجدول إعادة تشغيل فقط عندما + - تعرض ملخصات الأبناء `key` و`path` المطبّع و`type` و`required` و`hasChildren`، + بالإضافة إلى `hint` / `hintPath` المطابقين. +- يشغّل `update.run` تدفق تحديث gateway ويجدول إعادة تشغيل فقط عندما ينجح التحديث نفسه. -- تعرض `wizard.start` و`wizard.next` و`wizard.status` و`wizard.cancel` +- توفّر `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` - ملفات مساحة العمل الأولية المعروضة لوكيل. -- يعيد `agent.identity.get` هوية المساعد الفعالة لوكيل أو - جلسة. -- ينتظر `agent.wait` انتهاء التشغيل ويعيد اللقطة النهائية عند - توفرها. - -#### التحكم في الجلسة +- تدير `agents.files.list` و`agents.files.get` و`agents.files.set` ملفات + مساحة عمل bootstrap المكشوفة لوكيل. +- يعيد `agent.identity.get` هوية المساعد الفعالة لوكيل أو جلسة. +- ينتظر `agent.wait` انتهاء التشغيل ويعيد اللقطة الطرفية عند توفرها. #### التحكم في الجلسة - يعيد `sessions.list` فهرس الجلسات الحالي. -- يبدّل `sessions.subscribe` و`sessions.unsubscribe` اشتراكات - أحداث تغيّر الجلسة لعميل WS الحالي. +- يبدّل `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.steer` صيغة المقاطعة وإعادة التوجيه لجلسة نشطة. +- يوقف `sessions.abort` العمل النشط لجلسة ما. +- يحدّث `sessions.patch` بيانات تعريف الجلسة/التجاوزات. +- تنفّذ `sessions.reset` و`sessions.delete` و`sessions.compact` صيانة الجلسة. -- يعيد `sessions.get` صف الجلسة المخزن بالكامل. +- يعيد `sessions.get` صف الجلسة المخزّن الكامل. - لا يزال تنفيذ الدردشة يستخدم `chat.history` و`chat.send` و`chat.abort` و `chat.inject`. -- يتم تطبيع `chat.history` للعرض لعملاء واجهة المستخدم: تُزال وسوم التوجيه المضمّنة من - النص المرئي، وتُزال حمولات 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` اقتران العقدة والتحقق من - التمهيد. -- يعيد `node.list` و`node.describe` حالة العقدة المعروفة/المتصلة. + `node.pair.reject` و`node.pair.verify` إقران العقد والتحقق من bootstrap. +- يعيد `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.invoke.result` نتيجة طلب استدعاء. +- يحمل `node.event` الأحداث الصادرة من العقدة عائدًا إلى gateway. +- يحدّث `node.canvas.capability.refresh` رموز canvas المميزة ذات النطاق المحدد. +- تُعد `node.pending.pull` و`node.pending.ack` واجهات API لطابور العقدة المتصلة. -- تدير `node.pending.enqueue` و`node.pending.drain` العمل المعلّق الدائم +- تدير `node.pending.enqueue` و`node.pending.drain` العمل المعلق الدائم للعقد غير المتصلة/غير المتاحة. #### عائلات الموافقات - تغطي `exec.approval.request` و`exec.approval.get` و`exec.approval.list` و - `exec.approval.resolve` طلبات موافقة التنفيذ لمرة واحدة بالإضافة إلى + `exec.approval.resolve` طلبات موافقة exec لمرة واحدة إضافةً إلى البحث/إعادة التشغيل للموافقات المعلقة. -- ينتظر `exec.approval.waitDecision` موافقة تنفيذ معلقة واحدة ويعيد +- ينتظر `exec.approval.waitDecision` قرار موافقة exec واحدًا معلقًا ويعيد القرار النهائي (أو `null` عند انتهاء المهلة). -- تدير `exec.approvals.get` و`exec.approvals.set` لقطات سياسة موافقة - التنفيذ في Gateway. -- تدير `exec.approvals.node.get` و`exec.approvals.node.set` سياسة موافقة - التنفيذ المحلية للعقدة عبر أوامر ترحيل العقدة. +- تدير `exec.approvals.get` و`exec.approvals.set` لقطات سياسة موافقة exec + الخاصة بـ gateway. +- تدير `exec.approvals.node.get` و`exec.approvals.node.set` سياسة موافقة exec + المحلية للعقدة عبر أوامر relay الخاصة بالعقدة. - تغطي `plugin.approval.request` و`plugin.approval.list` و `plugin.approval.waitDecision` و`plugin.approval.resolve` - تدفقات الموافقة المعرفة بواسطة الإضافات. + تدفقات الموافقة المعرّفة من Plugin. #### عائلات رئيسية أخرى - الأتمتة: - - يجدول `wake` حقن نص استيقاظ فوري أو عند نبضة القلب التالية - - `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`: تحديثات دردشة واجهة المستخدم مثل `chat.inject` وأحداث - الدردشة الأخرى الخاصة بالنص فقط. -- `session.message` و`session.tool`: تحديثات النص/تدفق الأحداث - لجلسة مشترَك فيها. +- `chat`: تحديثات دردشة UI مثل `chat.inject` وأحداث الدردشة الأخرى الخاصة + بالنص فقط. +- `session.message` و`session.tool`: تحديثات النص/تدفق الأحداث لجلسة + مشترَك فيها. - `sessions.changed`: تغيّر فهرس الجلسات أو بياناتها الوصفية. -- `presence`: تحديثات لقطة وجود النظام. -- `tick`: حدث دوري للإبقاء على النشاط / التحقق من الحيوية. -- `health`: تحديث لقطة سلامة Gateway. -- `heartbeat`: تحديث تدفق أحداث نبضات القلب. -- `cron`: حدث تغيير تشغيل/مهمة cron. -- `shutdown`: إشعار إيقاف Gateway. -- `node.pair.requested` / `node.pair.resolved`: دورة حياة اقتران العقدة. +- `presence`: تحديثات لقطة حضور النظام. +- `tick`: حدث keepalive / liveliness دوري. +- `health`: تحديث لقطة سلامة gateway. +- `heartbeat`: تحديث تدفق أحداث Heartbeat. +- `cron`: حدث تغيّر تشغيل/مهمة Cron. +- `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`: دورة حياة - موافقة التنفيذ. -- `plugin.approval.requested` / `plugin.approval.resolved`: دورة حياة - موافقة الإضافة. + موافقة exec. +- `plugin.approval.requested` / `plugin.approval.resolved`: دورة حياة موافقة + Plugin. -### أساليب مساعدة العقدة +### طرق مساعدة العقدة -- يمكن للعقد استدعاء `skills.bins` لجلب القائمة الحالية لملفات Skills التنفيذية - لفحوصات السماح التلقائي. +- يمكن للعقد استدعاء `skills.bins` لجلب القائمة الحالية للملفات التنفيذية الخاصة بـ Skills + للتحقق من السماح التلقائي. -### أساليب مساعدة المشغّل +### طرق مساعدة المشغّل -- يمكن للمشغّلين استدعاء `commands.list` (`operator.read`) لجلب - مخزون الأوامر وقت التشغيل لوكيل. - - `agentId` اختياري؛ احذفه لقراءة مساحة عمل الوكيل الافتراضي. +- يمكن للمشغّلين استدعاء `commands.list` (`operator.read`) لجلب قائمة الأوامر + وقت التشغيل لوكيل. + - `agentId` اختياري؛ احذفه لقراءة مساحة عمل الوكيل الافتراضية. - يتحكم `scope` في السطح الذي يستهدفه `name` الأساسي: - - يعيد `text` رمز أمر النص الأساسي بدون `/` البادئة + - يعيد `text` رمز الأمر النصي الأساسي من دون الشرطة المائلة `/` - يعيد `native` ومسار `both` الافتراضي أسماء أصلية مدركة للمزوّد عند توفرها - - يحمل `textAliases` الأسماء المستعارة الدقيقة للشرطة المائلة مثل `/model` و`/m`. - - يحمل `nativeName` اسم الأمر الأصلي المدرك للمزوّد عند وجوده. - - `provider` اختياري ويؤثر فقط في التسمية الأصلية بالإضافة إلى - توفر أوامر الإضافات الأصلية. - - يحذف `includeArgs=false` بيانات الوسائط التسلسلية من الاستجابة. + - يحمل `textAliases` الأسماء المستعارة الدقيقة ذات الشرطة المائلة مثل + `/model` و`/m`. + - يحمل `nativeName` اسم الأمر الأصلي المدرك للمزوّد عندما يكون موجودًا. + - `provider` اختياري ولا يؤثر إلا في التسمية الأصلية وإتاحة أوامر Plugin + الأصلية. + - يؤدي `includeArgs=false` إلى حذف بيانات الوسائط التسلسلية من الاستجابة. - يمكن للمشغّلين استدعاء `tools.catalog` (`operator.read`) لجلب فهرس الأدوات وقت التشغيل لوكيل. - تتضمن الاستجابة أدوات مجمعة وبيانات وصفية لمصدرها: + تتضمن الاستجابة أدوات مجمعة وبيانات تعريف المصدر: - `source`: `core` أو `plugin` - - `pluginId`: مالك الإضافة عندما يكون `source="plugin"` - - `optional`: ما إذا كانت أداة الإضافة اختيارية -- يمكن للمشغّلين استدعاء `tools.effective` (`operator.read`) لجلب - مخزون الأدوات الفعّال وقت التشغيل لجلسة. + - `pluginId`: مالك Plugin عندما تكون `source="plugin"` + - `optional`: ما إذا كانت أداة Plugin اختيارية +- يمكن للمشغّلين استدعاء `tools.effective` (`operator.read`) لجلب فهرس الأدوات الفعّال + وقت التشغيل لجلسة. - `sessionKey` مطلوب. - - يستمد Gateway سياق وقت التشغيل الموثوق من الجلسة من جهة الخادم بدلًا من قبول - سياق المصادقة أو التسليم المورّد من المستدعي. - - تكون الاستجابة مقيّدة بالجلسة وتعكس ما يمكن للمحادثة النشطة استخدامه الآن، - بما في ذلك أدوات core والإضافات والقنوات. -- يمكن للمشغّلين استدعاء `skills.status` (`operator.read`) لجلب - مخزون Skills المرئي لوكيل. - - `agentId` اختياري؛ احذفه لقراءة مساحة عمل الوكيل الافتراضي. - - تتضمن الاستجابة الأهلية، والمتطلبات المفقودة، وفحوصات الإعداد، - وخيارات التثبيت المنقحة دون كشف قيم الأسرار الخام. -- يمكن للمشغّلين استدعاء `skills.search` و`skills.detail` (`operator.read`) - لبيانات اكتشاف ClawHub الوصفية. + - يستخلص gateway سياق وقت تشغيل موثوقًا من الجلسة على جانب الخادم بدلًا من قبول + سياق المصادقة أو التسليم المزوَّد من المستدعي. + - تكون الاستجابة ذات نطاق جلسة وتعكس ما يمكن للمحادثة النشطة استخدامه الآن، + بما في ذلك أدوات core وPlugin وchannel. +- يمكن للمشغّلين استدعاء `skills.status` (`operator.read`) لجلب قائمة + Skills المرئية لوكيل. + - `agentId` اختياري؛ احذفه لقراءة مساحة عمل الوكيل الافتراضية. + - تتضمن الاستجابة الأهلية، والمتطلبات الناقصة، وفحوصات التهيئة، + وخيارات التثبيت المنقحة من دون كشف قيم الأسرار الخام. +- يمكن للمشغّلين استدعاء `skills.search` و`skills.detail` (`operator.read`) لبيانات + اكتشاف ClawHub الوصفية. - يمكن للمشغّلين استدعاء `skills.install` (`operator.admin`) في وضعين: - - وضع ClawHub: يقوم `{ source: "clawhub", slug, version?, force? }` بتثبيت - مجلد Skill في دليل `skills/` لمساحة عمل الوكيل الافتراضية. + - وضع ClawHub: يثبّت `{ source: "clawhub", slug, version?, force? }` + مجلد skill في دليل `skills/` الخاص بمساحة عمل الوكيل الافتراضية. - وضع مُثبّت Gateway: يشغّل `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }` - إجراء `metadata.openclaw.install` معلنًا على مضيف Gateway. + إجراء `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 -- عندما يحتاج طلب تنفيذ إلى موافقة، يبث Gateway الحدث `exec.approval.requested`. -- يحل عملاء المشغّل ذلك عبر استدعاء `exec.approval.resolve` (يتطلب النطاق `operator.approvals`). +- عندما يحتاج طلب exec إلى موافقة، يبث gateway الحدث `exec.approval.requested`. +- يحل عملاء المشغّل ذلك عبر استدعاء `exec.approval.resolve` (ويتطلب النطاق `operator.approvals`). - بالنسبة إلى `host=node`، يجب أن يتضمن `exec.approval.request` القيمة `systemRunPlan` - (`argv`/`cwd`/`rawCommand`/بيانات الجلسة الوصفية بصيغتها القياسية). تُرفض الطلبات + (القيَم القياسية `argv`/`cwd`/`rawCommand`/بيانات تعريف الجلسة). وتُرفض الطلبات التي تفتقد `systemRunPlan`. - بعد الموافقة، تعيد استدعاءات `node.invoke system.run` الممررة استخدام - `systemRunPlan` القياسي هذا بوصفه السياق الموثوق للأمر/دليل العمل/الجلسة. -- إذا غيّر مستدعٍ `command` أو `rawCommand` أو `cwd` أو `agentId` أو - `sessionKey` بين التحضير وتمرير `system.run` النهائي الموافق عليه، - يرفض Gateway التشغيل بدلًا من الوثوق بالحمولة المعدّلة. + `systemRunPlan` القياسي هذا بوصفه السياق المرجعي للأمر/`cwd`/الجلسة. +- إذا عدّل مستدعٍ `command` أو`rawCommand` أو`cwd` أو`agentId` أو + `sessionKey` بين التحضير وتمرير `system.run` الموافق عليه نهائيًا، + يرفض gateway التشغيل بدلًا من الوثوق بالحمولة المعدلة. -## الاحتياط لتسليم الوكيل +## بديل تسليم الوكيل - يمكن أن تتضمن طلبات `agent` القيمة `deliver=true` لطلب تسليم صادر. -- يحافظ `bestEffortDeliver=false` على السلوك الصارم: أهداف التسليم غير المحلولة أو الداخلية فقط تعيد `INVALID_REQUEST`. -- يسمح `bestEffortDeliver=true` بالاحتياط إلى تنفيذ داخل الجلسة فقط عندما يتعذر حل مسار خارجي قابل للتسليم (مثل جلسات webchat الداخلية أو إعدادات القنوات المتعددة الملتبسة). +- يحافظ `bestEffortDeliver=false` على السلوك الصارم: تعيد أهداف التسليم غير المحلولة أو الداخلية فقط القيمة `INVALID_REQUEST`. +- يسمح `bestEffortDeliver=true` بالرجوع إلى التنفيذ ضمن الجلسة فقط عندما يتعذر حل مسار خارجي قابل للتسليم (على سبيل المثال جلسات internal/webchat أو إعدادات متعددة القنوات ملتبسة). ## إدارة الإصدارات -- يوجد `PROTOCOL_VERSION` في `src/gateway/protocol/schema.ts`. -- يرسل العملاء `minProtocol` و`maxProtocol`؛ ويرفض الخادم حالات عدم التطابق. -- تُولد المخططات + النماذج من تعريفات TypeBox: +- يوجد `PROTOCOL_VERSION` في `src/gateway/protocol/schema/protocol-schemas.ts`. +- يرسل العملاء `minProtocol` + `maxProtocol`؛ ويرفض الخادم حالات عدم التطابق. +- تُولَّد المخططات + النماذج من تعريفات TypeBox: - `pnpm protocol:gen` - `pnpm protocol:gen:swift` - `pnpm protocol:check` +### ثوابت العميل + +يستخدم العميل المرجعي في `src/gateway/client.ts` هذه القيم الافتراضية. وهذه القيم +مستقرة عبر البروتوكول 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` | +| مهلة السماح قبل `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` | + +يعلن الخادم عن القيم الفعالة `policy.tickIntervalMs` و`policy.maxPayload` +و`policy.maxBufferedBytes` في `hello-ok`؛ ويجب على العملاء الالتزام بهذه القيم +بدلًا من القيم الافتراضية السابقة للمصافحة. + ## المصادقة - تستخدم مصادقة Gateway ذات السر المشترك `connect.params.auth.token` أو - `connect.params.auth.password`، بحسب وضع المصادقة المُكوَّن. -- أوضاع حمل الهوية مثل Tailscale Serve + `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` ويجب أن يحتفظ به العميل + `gateway.auth.mode: "trusted-proxy"` غير المعتمد على loopback + تستوفي فحص مصادقة الاتصال من ترويسات الطلب بدلًا من `connect.params.auth.*`. +- يتجاوز `gateway.auth.mode: "none"` الخاص بالإدخال الخاص مصادقة الاتصال + ذات السر المشترك بالكامل؛ لا تعرّض هذا الوضع على إدخال عام/غير موثوق. +- بعد الإقران، يُصدر Gateway **رمز جهاز مميزًا** ذا نطاق محدد بحسب دور الاتصال + نطاقاته. + ويُعاد ضمن `hello-ok.auth.deviceToken` ويجب أن يحتفظ به العميل للاتصالات المستقبلية. -- يجب على العملاء الاحتفاظ برمز الجهاز المميز الأساسي `hello-ok.auth.deviceToken` بعد - أي اتصال ناجح. -- يجب أن تؤدي إعادة الاتصال باستخدام **رمز الجهاز المميز المخزن** هذا أيضًا إلى إعادة استخدام - مجموعة النطاقات الموافق عليها المخزنة لهذا الرمز. يحافظ هذا على وصول - القراءة/الفحص/الحالة الذي مُنح بالفعل ويتجنب تضييق إعادة الاتصال - بصمت إلى نطاق إداري ضمني أضيق فقط. -- أولوية مصادقة الاتصال العادية هي أولًا الرمز/كلمة المرور المشتركة الصريحة، ثم - `deviceToken` الصريح، ثم الرمز المخزن لكل جهاز، ثم رمز التمهيد. -- الإدخالات الإضافية في `hello-ok.auth.deviceTokens` هي رموز تسليم تمهيد. - احتفظ بها فقط عندما يستخدم الاتصال مصادقة التمهيد على نقل موثوق - مثل `wss://` أو loopback/الاقتران المحلي. -- إذا قدّم عميل **`deviceToken` صريحًا** أو `scopes` صريحة، فستظل - مجموعة النطاقات التي طلبها المستدعي هي المعتمدة؛ لا يُعاد استخدام النطاقات المخزنة - إلا عندما يعيد العميل استخدام الرمز المخزن لكل جهاز. -- يمكن تدوير/إلغاء رموز الأجهزة المميزة عبر `device.token.rotate` و - `device.token.revoke` (يتطلب النطاق `operator.pairing`). -- يظل إصدار/تدوير الرموز المميزة مقيّدًا بمجموعة الأدوار الموافق عليها والمُسجَّلة في - إدخال اقتران ذلك الجهاز؛ ولا يمكن أن يؤدي تدوير رمز مميز إلى توسيع الجهاز إلى - دور لم تمنحه موافقة الاقتران أصلًا. -- بالنسبة إلى جلسات رموز الأجهزة المميزة للأجهزة المقترنة، تكون إدارة الأجهزة مقيّدة - ذاتيًا ما لم يكن لدى المستدعي أيضًا `operator.admin`: لا يمكن للمستدعين غير الإداريين - الإزالة/الإلغاء/التدوير إلا لإدخال أجهزتهم **هم** فقط. -- يتحقق `device.token.rotate` أيضًا من مجموعة نطاقات المشغّل المطلوبة مقابل - نطاقات جلسة المستدعي الحالية. لا يمكن للمستدعين غير الإداريين تدوير رمز مميز إلى - مجموعة نطاقات مشغّل أوسع مما لديهم بالفعل. -- تتضمن حالات فشل المصادقة `error.details.code` بالإضافة إلى تلميحات - للاسترداد: +- يجب على العملاء حفظ `hello-ok.auth.deviceToken` الأساسي بعد أي + اتصال ناجح. +- يجب أن تؤدي إعادة الاتصال باستخدام رمز الجهاز المميز **المحفوظ** هذا أيضًا إلى إعادة استخدام + مجموعة النطاقات الموافق عليها والمحفوظة لهذا الرمز. يحافظ ذلك على صلاحيات + الوصول للقراءة/الفحص/الحالة التي مُنحت سابقًا ويتجنب تقليص عمليات + إعادة الاتصال بصمت إلى نطاق إدارة ضمني أضيق فقط. +- تجميع مصادقة الاتصال على جانب العميل (`selectConnectAuth` في + `src/gateway/client.ts`): + - `auth.password` مستقل ويُمرَّر دائمًا عند ضبطه. + - يُملأ `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` صريحة، فإن + مجموعة النطاقات المطلوبة من المستدعي تبقى هي المرجع؛ ولا يُعاد استخدام + النطاقات المخبأة إلا عندما يعيد العميل استخدام الرمز المحفوظ لكل جهاز. +- يمكن تدوير/إبطال رموز الأجهزة عبر `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`) - سلوك العميل عند `AUTH_TOKEN_MISMATCH`: - - يمكن للعملاء الموثوقين محاولة إعادة واحدة مقيّدة باستخدام رمز مميز مخزن لكل جهاز. - - إذا فشلت إعادة المحاولة تلك، فيجب على العملاء إيقاف حلقات إعادة الاتصال التلقائية وعرض إرشادات إجراء المشغّل. + - يمكن للعملاء الموثوقين محاولة إعادة واحدة محدودة باستخدام رمز محفوظ لكل جهاز. + - إذا فشلت إعادة المحاولة هذه، يجب على العملاء إيقاف حلقات إعادة الاتصال التلقائية + وإظهار إرشادات للإجراء المطلوب من المشغّل. -## هوية الجهاز + الاقتران +## هوية الجهاز + الإقران -- يجب أن تتضمن العقد هوية جهاز مستقرة (`device.id`) مشتقة من +- يجب أن تتضمن العقد هوية جهاز ثابتة (`device.id`) مشتقة من بصمة زوج مفاتيح. -- تصدر بوابات Gateway رموزًا مميزة لكل جهاز + دور. -- يلزم الحصول على موافقات الاقتران لمعرّفات الأجهزة الجديدة ما لم يكن - القبول التلقائي المحلي مفعّلًا. -- يتركز القبول التلقائي للاقتران على اتصالات local loopback المباشرة. -- يحتوي OpenClaw أيضًا على مسار اتصال ذاتي ضيق على مستوى الخلفية/الحاوية +- تُصدر Gateways رموزًا مميزة لكل جهاز + دور. +- تتطلب معرّفات الأجهزة الجديدة موافقات إقران ما لم يكن التفعيل المحلي التلقائي + للموافقة ممكّنًا. +- تتمحور الموافقة التلقائية على الإقران حول اتصالات loopback المحلية المباشرة. +- يوفّر OpenClaw أيضًا مسار self-connect ضيقًا محليًا للخلفية/الحاوية لتدفقات المساعد الموثوق ذات السر المشترك. -- لا تزال اتصالات tailnet أو LAN على المضيف نفسه تُعامَل على أنها بعيدة لأغراض الاقتران +- لا تزال اتصالات tailnet أو LAN على نفس المضيف تُعامل على أنها بعيدة للإقران وتتطلب موافقة. -- يجب على جميع عملاء WS تضمين هوية `device` أثناء `connect` (operator + node). +- يجب أن تتضمن جميع عملاء WS هوية `device` أثناء `connect` (operator + node). يمكن لـ Control UI حذفها فقط في هذه الأوضاع: - `gateway.controlUi.allowInsecureAuth=true` للتوافق مع HTTP غير الآمن على localhost فقط. - - نجاح مصادقة Control UI للمشغّل عبر `gateway.auth.mode: "trusted-proxy"`. - - `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (خيار طارئ، تخفيض أمني شديد). -- يجب على جميع الاتصالات توقيع قيمة `connect.challenge` nonce التي يوفّرها الخادم. + - نجاح مصادقة operator في `gateway.auth.mode: "trusted-proxy"` لـ Control UI. + - `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 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` | فشل تنسيق/تطبيع المفتاح العام. | هدف الترحيل: - انتظر دائمًا `connect.challenge`. -- وقّع حمولة v2 التي تتضمن nonce الخادم. +- وقّع حمولة v2 التي تتضمن nonce الخاص بالخادم. - أرسل 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`). +- يمكن للعملاء اختياريًا تثبيت بصمة شهادة gateway (راجع تهيئة `gateway.tls` + إضافةً إلى `gateway.remote.tlsFingerprint` أو خيار CLI ‏`--tls-fingerprint`). ## النطاق -يكشف هذا البروتوكول **واجهة API الكاملة لـ Gateway** (الحالة، والقنوات، والنماذج، والدردشة، +يعرض هذا البروتوكول **واجهة API الكاملة لـ gateway** (الحالة، والقنوات، والنماذج، والدردشة، والوكيل، والجلسات، والعقد، والموافقات، وغير ذلك). ويُعرَّف السطح الدقيق بواسطة مخططات TypeBox في `src/gateway/protocol/schema.ts`. diff --git a/docs/ar/providers/google.md b/docs/ar/providers/google.md index 24db0ee7c..f4313b9c2 100644 --- a/docs/ar/providers/google.md +++ b/docs/ar/providers/google.md @@ -1,28 +1,28 @@ --- read_when: - تريد استخدام نماذج Google Gemini مع OpenClaw - - تحتاج إلى مسار مصادقة مفتاح API أو OAuth -summary: إعداد Google Gemini ‏(مفتاح API + OAuth، وتوليد الصور، وفهم الوسائط، والبحث على الويب) + - تحتاج إلى مفتاح API أو تدفق مصادقة OAuth +summary: إعداد Google Gemini (مفتاح API + OAuth، إنشاء الصور، فهم الوسائط، TTS، البحث على الويب) title: Google (Gemini) x-i18n: - generated_at: "2026-04-12T23:30:52Z" + generated_at: "2026-04-16T07:17:53Z" model: gpt-5.4 provider: openai - source_hash: 64b848add89061b208a5d6b19d206c433cace5216a0ca4b63d56496aecbde452 + source_hash: ec2d62855f5e80efda758aad71bcaa95c38b1e41761fa1100d47a06c62881419 source_path: providers/google.md workflow: 15 --- # Google (Gemini) -يوفّر Plugin Google الوصول إلى نماذج Gemini عبر Google AI Studio، بالإضافة إلى -توليد الصور، وفهم الوسائط (الصور/الصوت/الفيديو)، والبحث على الويب عبر +يوفر Plugin Google إمكانية الوصول إلى نماذج Gemini عبر Google AI Studio، بالإضافة إلى +إنشاء الصور، وفهم الوسائط (الصور/الصوت/الفيديو)، وتحويل النص إلى كلام، والبحث على الويب عبر Gemini Grounding. - المزوّد: `google` - المصادقة: `GEMINI_API_KEY` أو `GOOGLE_API_KEY` - API: Google Gemini API -- مزوّد بديل: `google-gemini-cli` ‏(OAuth) +- مزوّد بديل: `google-gemini-cli` (OAuth) ## البدء @@ -33,7 +33,7 @@ Gemini Grounding. **الأفضل لـ:** الوصول القياسي إلى Gemini API عبر Google AI Studio. - + ```bash openclaw onboard --auth-choice gemini-api-key ``` @@ -47,7 +47,7 @@ Gemini Grounding. --gemini-api-key "$GEMINI_API_KEY" ``` - + ```json5 { agents: { @@ -58,7 +58,7 @@ Gemini Grounding. } ``` - + ```bash openclaw models list --provider google ``` @@ -66,7 +66,7 @@ Gemini Grounding. - يُقبل كل من متغيري البيئة `GEMINI_API_KEY` و`GOOGLE_API_KEY`. استخدم أيًّا منهما لديك مضبوطًا بالفعل. + يُقبل متغيرا البيئة `GEMINI_API_KEY` و`GOOGLE_API_KEY` كلاهما. استخدم أيًّا منهما لديك مُعدًّا بالفعل. @@ -75,12 +75,12 @@ Gemini Grounding. **الأفضل لـ:** إعادة استخدام تسجيل دخول Gemini CLI موجود عبر PKCE OAuth بدلًا من مفتاح API منفصل. - إن المزوّد `google-gemini-cli` تكامل غير رسمي. أفاد بعض المستخدمين + يُعد المزوّد `google-gemini-cli` تكاملًا غير رسمي. يفيد بعض المستخدمين بوجود قيود على الحساب عند استخدام OAuth بهذه الطريقة. استخدمه على مسؤوليتك الخاصة. - + يجب أن يكون الأمر المحلي `gemini` متاحًا على `PATH`. ```bash @@ -91,15 +91,15 @@ Gemini Grounding. npm install -g @google/gemini-cli ``` - يدعم OpenClaw كلاً من تثبيتات Homebrew والتثبيتات العامة عبر npm، بما في ذلك - التخطيطات الشائعة على Windows/npm. + يدعم OpenClaw كلاً من تثبيتات Homebrew وتثبيتات npm العامة، بما في ذلك + تخطيطات Windows/npm الشائعة. - + ```bash openclaw models auth login --provider google-gemini-cli --set-default ``` - + ```bash openclaw models list --provider google-gemini-cli ``` @@ -117,17 +117,17 @@ Gemini Grounding. (أو صيغ `GEMINI_CLI_*`.) - إذا فشلت طلبات Gemini CLI OAuth بعد تسجيل الدخول، فعيّن `GOOGLE_CLOUD_PROJECT` أو + إذا فشلت طلبات Gemini CLI OAuth بعد تسجيل الدخول، فاضبط `GOOGLE_CLOUD_PROJECT` أو `GOOGLE_CLOUD_PROJECT_ID` على مضيف Gateway ثم أعد المحاولة. إذا فشل تسجيل الدخول قبل بدء تدفق المتصفح، فتأكد من أن الأمر المحلي `gemini` - مثبّت وموجود على `PATH`. + مُثبّت وموجود على `PATH`. - إن المزوّد `google-gemini-cli` المعتمد على OAuth فقط هو - سطح منفصل للاستدلال النصي. ويبقى توليد الصور، وفهم الوسائط، وGemini Grounding على + يمثّل المزوّد `google-gemini-cli` المعتمد على OAuth فقط سطحًا منفصلًا + للاستدلال النصي. بينما يبقى إنشاء الصور، وفهم الوسائط، وGemini Grounding على معرّف المزوّد `google`. @@ -135,34 +135,35 @@ Gemini Grounding. ## الإمكانات -| الإمكانية | مدعومة | -| ---------------------- | ----------------- | +| الإمكانية | مدعومة | +| --------------------- | ----------------- | | إكمالات الدردشة | نعم | -| توليد الصور | نعم | -| توليد الموسيقى | نعم | -| فهم الصور | نعم | -| نسخ الصوت إلى نص | نعم | -| فهم الفيديو | نعم | -| البحث على الويب (Grounding) | نعم | +| إنشاء الصور | نعم | +| إنشاء الموسيقى | نعم | +| تحويل النص إلى كلام | نعم | +| فهم الصور | نعم | +| نسخ الصوت إلى نص | نعم | +| فهم الفيديو | نعم | +| البحث على الويب (Grounding) | نعم | | التفكير/الاستدلال | نعم (Gemini 3.1+) | | نماذج Gemma 4 | نعم | -تدعم نماذج Gemma 4 (على سبيل المثال `gemma-4-26b-a4b-it`) وضع التفكير. يقوم OpenClaw -بإعادة كتابة `thinkingBudget` إلى `thinkingLevel` مدعوم من Google في نماذج Gemma 4. -ويؤدي ضبط التفكير إلى `off` إلى إبقاء التفكير معطّلًا بدلًا من ربطه بـ +تدعم نماذج Gemma 4 (مثل `gemma-4-26b-a4b-it`) وضع التفكير. يعيد OpenClaw +كتابة `thinkingBudget` إلى قيمة Google `thinkingLevel` مدعومة لـ Gemma 4. +ويؤدي ضبط التفكير على `off` إلى إبقاء التفكير معطّلًا بدلًا من تعيينه إلى `MINIMAL`. -## توليد الصور +## إنشاء الصور -يستخدم مزوّد توليد الصور المضمّن `google` افتراضيًا +يستخدم مزوّد إنشاء الصور المضمّن `google` افتراضيًا `google/gemini-3.1-flash-image-preview`. - يدعم أيضًا `google/gemini-3-pro-image-preview` -- التوليد: حتى 4 صور لكل طلب -- وضع التحرير: مفعّل، حتى 5 صور إدخال -- عناصر التحكم الهندسية: `size` و`aspectRatio` و`resolution` +- الإنشاء: حتى 4 صور لكل طلب +- وضع التحرير: مفعّل، مع ما يصل إلى 5 صور إدخال +- عناصر التحكّم في الأبعاد: `size` و`aspectRatio` و`resolution` لاستخدام Google كمزوّد الصور الافتراضي: @@ -179,12 +180,12 @@ Gemini Grounding. ``` -راجع [Image Generation](/ar/tools/image-generation) لمعلمات الأداة المشتركة، واختيار المزوّد، وسلوك التبديل الاحتياطي. +راجع [إنشاء الصور](/ar/tools/image-generation) للاطلاع على معاملات الأداة المشتركة، واختيار المزوّد، وسلوك تجاوز الفشل. -## توليد الفيديو +## إنشاء الفيديو -يسجّل Plugin ‏`google` المضمّن أيضًا توليد الفيديو عبر الأداة المشتركة +يسجّل Plugin ‏`google` المضمّن أيضًا إنشاء الفيديو عبر الأداة المشتركة `video_generate`. - نموذج الفيديو الافتراضي: `google/veo-3.1-fast-generate-preview` @@ -207,20 +208,20 @@ Gemini Grounding. ``` -راجع [Video Generation](/ar/tools/video-generation) لمعلمات الأداة المشتركة، واختيار المزوّد، وسلوك التبديل الاحتياطي. +راجع [إنشاء الفيديو](/ar/tools/video-generation) للاطلاع على معاملات الأداة المشتركة، واختيار المزوّد، وسلوك تجاوز الفشل. -## توليد الموسيقى +## إنشاء الموسيقى -يسجّل Plugin ‏`google` المضمّن أيضًا توليد الموسيقى عبر الأداة المشتركة +يسجّل Plugin ‏`google` المضمّن أيضًا إنشاء الموسيقى عبر الأداة المشتركة `music_generate`. - نموذج الموسيقى الافتراضي: `google/lyria-3-clip-preview` - يدعم أيضًا `google/lyria-3-pro-preview` -- عناصر تحكم الموجّه: `lyrics` و`instrumental` +- عناصر التحكّم في الطلب: `lyrics` و`instrumental` - تنسيق الإخراج: `mp3` افتراضيًا، بالإضافة إلى `wav` على `google/lyria-3-pro-preview` -- المدخلات المرجعية: حتى 10 صور -- تفصل التشغيلات المدعومة بالجلسات عبر تدفق المهام/الحالة المشترك، بما في ذلك `action: "status"` +- مدخلات مرجعية: حتى 10 صور +- يتم فصل التشغيلات المعتمدة على الجلسات عبر تدفق المهمة/الحالة المشترك، بما في ذلك `action: "status"` لاستخدام Google كمزوّد الموسيقى الافتراضي: @@ -237,22 +238,66 @@ Gemini Grounding. ``` -راجع [Music Generation](/ar/tools/music-generation) لمعلمات الأداة المشتركة، واختيار المزوّد، وسلوك التبديل الاحتياطي. +راجع [إنشاء الموسيقى](/ar/tools/music-generation) للاطلاع على معاملات الأداة المشتركة، واختيار المزوّد، وسلوك تجاوز الفشل. -## الإعداد المتقدم +## تحويل النص إلى كلام + +يستخدم مزوّد الكلام المضمّن `google` مسار Gemini API لتحويل النص إلى كلام مع +`gemini-3.1-flash-tts-preview`. + +- الصوت الافتراضي: `Kore` +- المصادقة: `messages.tts.providers.google.apiKey` أو `models.providers.google.apiKey` أو `GEMINI_API_KEY` أو `GOOGLE_API_KEY` +- الإخراج: WAV لمرفقات TTS العادية، وPCM لـ Talk/الهاتف +- إخراج الملاحظات الصوتية الأصلي: غير مدعوم على مسار Gemini API هذا لأن API يعيد PCM بدلًا من Opus + +لاستخدام Google كمزوّد TTS الافتراضي: + +```json5 +{ + messages: { + tts: { + auto: "always", + provider: "google", + providers: { + google: { + model: "gemini-3.1-flash-tts-preview", + voiceName: "Kore", + }, + }, + }, + }, +} +``` + +يقبل Gemini API TTS وسومًا صوتية تعبيرية بين أقواس مربعة في النص، مثل +`[whispers]` أو `[laughs]`. ولإبقاء الوسوم خارج رد الدردشة المرئي مع +إرسالها إلى TTS، ضعها داخل كتلة `[[tts:text]]...[[/tts:text]]`: + +```text +إليك نص الرد النظيف. + +[[tts:text]][whispers] إليك النسخة المنطوقة.[[/tts:text]] +``` + + +يُعد مفتاح API من Google Cloud Console والمقيّد بـ Gemini API صالحًا لهذا +المزوّد. هذا ليس مسار Cloud Text-to-Speech API المنفصل. + + +## الإعدادات المتقدمة - - في تشغيلات Gemini API المباشرة (`api: "google-generative-ai"`)، يمرّر OpenClaw - معرّف `cachedContent` مضبوطًا إلى طلبات Gemini. + + بالنسبة لتشغيلات Gemini API المباشرة (`api: "google-generative-ai"`)، يقوم OpenClaw + بتمرير معرّف `cachedContent` مضبوط إلى طلبات Gemini. - - اضبط معلمات على مستوى النموذج أو بشكل عام باستخدام - `cachedContent` أو الشكل القديم `cached_content` - - إذا وُجد الاثنان، تكون الأولوية لـ `cachedContent` + - اضبط معاملات لكل نموذج أو معاملات عامة باستخدام + `cachedContent` أو الصيغة القديمة `cached_content` + - إذا وُجد الاثنان، فستكون الأولوية لـ `cachedContent` - مثال على القيمة: `cachedContents/prebuilt-context` - - يتم تطبيع استخدام إصابة التخزين المؤقت في Gemini إلى `cacheRead` في OpenClaw انطلاقًا من - القيمة العليا `cachedContentTokenCount` + - يتم توحيد استخدام إصابة الذاكرة المؤقتة في Gemini إلى `cacheRead` في OpenClaw من + قيمة `cachedContentTokenCount` القادمة من المصدر ```json5 { @@ -273,20 +318,20 @@ Gemini Grounding. - عند استخدام مزوّد OAuth ‏`google-gemini-cli`، يقوم OpenClaw بتطبيع - خرج JSON من CLI على النحو التالي: + عند استخدام مزوّد OAuth ‏`google-gemini-cli`، يقوم OpenClaw بتوحيد + مخرجات JSON من CLI كما يلي: - يأتي نص الرد من الحقل `response` في JSON الخاص بـ CLI. - - تعود معلومات الاستخدام إلى `stats` عندما يترك CLI الحقل `usage` فارغًا. - - يتم تطبيع `stats.cached` إلى `cacheRead` في OpenClaw. + - يعود الاستخدام إلى `stats` عندما يترك CLI الحقل `usage` فارغًا. + - يتم توحيد `stats.cached` إلى `cacheRead` في OpenClaw. - إذا كان `stats.input` مفقودًا، يستنتج OpenClaw رموز الإدخال من `stats.input_tokens - stats.cached`. - - إذا كان Gateway يعمل كخدمة daemon (`launchd`/`systemd`)، فتأكد من أن `GEMINI_API_KEY` - متاح لتلك العملية (على سبيل المثال، في `~/.openclaw/.env` أو عبر + + إذا كان Gateway يعمل كخدمة daemon ‏(launchd/systemd)، فتأكد من أن `GEMINI_API_KEY` + متاح لتلك العملية (على سبيل المثال في `~/.openclaw/.env` أو عبر `env.shellEnv`). @@ -295,15 +340,15 @@ Gemini Grounding. - اختيار المزوّدين، ومراجع النماذج، وسلوك التبديل الاحتياطي. + اختيار المزوّدين، ومراجع النماذج، وسلوك تجاوز الفشل. - - معلمات أداة الصور المشتركة واختيار المزوّد. + + معاملات أداة الصور المشتركة واختيار المزوّد. - - معلمات أداة الفيديو المشتركة واختيار المزوّد. + + معاملات أداة الفيديو المشتركة واختيار المزوّد. - - معلمات أداة الموسيقى المشتركة واختيار المزوّد. + + معاملات أداة الموسيقى المشتركة واختيار المزوّد. diff --git a/docs/ar/refactor/async-exec-duplicate-completion-investigation.md b/docs/ar/refactor/async-exec-duplicate-completion-investigation.md new file mode 100644 index 000000000..2fde05dcb --- /dev/null +++ b/docs/ar/refactor/async-exec-duplicate-completion-investigation.md @@ -0,0 +1,132 @@ +--- +x-i18n: + generated_at: "2026-04-16T07:17:43Z" + model: gpt-5.4 + provider: openai + source_hash: 95e56c5411204363676f002059c942201503e2359515d1a4b409882cc2e04920 + source_path: refactor/async-exec-duplicate-completion-investigation.md + workflow: 15 +--- + +# التحقيق في التكرار في إكمال التنفيذ غير المتزامن + +## النطاق + +- الجلسة: `agent:main:telegram:group:-1003774691294:topic:1` +- العرض: تم تسجيل نفس إكمال التنفيذ غير المتزامن للجلسة/التشغيل `keen-nexus` مرتين في LCM على أنه دور مستخدم. +- الهدف: تحديد ما إذا كان هذا على الأرجح حقن جلسة مكررًا أم مجرد إعادة محاولة تسليم صادرة. + +## الاستنتاج + +الأرجح أن هذا **حقن جلسة مكرر**، وليس مجرد إعادة محاولة تسليم صادرة فقط. + +أقوى فجوة على جانب Gateway موجودة في **مسار إكمال تنفيذ Node**: + +1. عند انتهاء تنفيذ من جانب Node، يتم إصدار `exec.finished` مع `runId` الكامل. +2. يقوم Gateway في `server-node-events` بتحويل ذلك إلى حدث نظام ويطلب Heartbeat. +3. تقوم عملية Heartbeat بحقن كتلة أحداث النظام المصروفة في موجه الوكيل. +4. يقوم المشغّل المضمّن بحفظ هذا الموجه كدور مستخدم جديد في سجل الجلسة. + +إذا وصل نفس `exec.finished` إلى Gateway مرتين لنفس `runId` لأي سبب كان (إعادة تشغيل، تكرار بعد إعادة الاتصال، إعادة إرسال من المصدر، أو مُنتِج مكرر)، فإن OpenClaw لا يملك حاليًا **تحقق idempotency مقيّدًا بـ `runId`/`contextKey`** على هذا المسار. ستتحول النسخة الثانية إلى رسالة مستخدم ثانية بالمحتوى نفسه. + +## مسار الشيفرة الدقيق + +### 1. المُنتِج: حدث إكمال تنفيذ Node + +- `src/node-host/invoke.ts:340-360` + - تقوم `sendExecFinishedEvent(...)` بإصدار `node.event` مع الحدث `exec.finished`. + - تتضمن الحمولة `sessionKey` و`runId` الكامل. + +### 2. استيعاب الحدث في Gateway + +- `src/gateway/server-node-events.ts:574-640` + - يتعامل مع `exec.finished`. + - يبني النص: + - `Exec finished (node=..., id=, code ...)` + - ويضعه في الطابور عبر: + - `enqueueSystemEvent(text, { sessionKey, contextKey: runId ? \`exec:${runId}\` : "exec", trusted: false })` + - ويطلب فورًا عملية إيقاظ: + - `requestHeartbeatNow(scopedHeartbeatWakeOptions(sessionKey, { reason: "exec-event" }))` + +### 3. نقطة ضعف إزالة التكرار في أحداث النظام + +- `src/infra/system-events.ts:90-115` + - تقوم `enqueueSystemEvent(...)` فقط بقمع **النص المكرر المتتالي**: + - `if (entry.lastText === cleaned) return false` + - وهي تخزن `contextKey`، لكنها **لا** تستخدم `contextKey` لتحقيق idempotency. + - بعد التصريف، تتم إعادة تعيين قمع التكرار. + +هذا يعني أن إعادة وصول `exec.finished` بنفس `runId` يمكن قبولها مرة أخرى لاحقًا، رغم أن الشيفرة لديها أصلًا مرشح ثابت مناسب لـ idempotency وهو (`exec:`). + +### 4. التعامل مع الإيقاظ ليس هو المسبّب الأساسي للتكرار + +- `src/infra/heartbeat-wake.ts:79-117` + - يتم دمج عمليات الإيقاظ حسب `(agentId, sessionKey)`. + - طلبات الإيقاظ المكررة للهدف نفسه تنهار إلى إدخال إيقاظ واحد معلّق. + +هذا يجعل **التكرار في التعامل مع الإيقاظ وحده** تفسيرًا أضعف من استيعاب الحدث بشكل مكرر. + +### 5. يقوم Heartbeat باستهلاك الحدث وتحويله إلى دخل للموجه + +- `src/infra/heartbeat-runner.ts:535-574` + - تقوم مرحلة ما قبل التنفيذ بمعاينة أحداث النظام المعلقة وتصنيف عمليات تشغيل exec-event. +- `src/auto-reply/reply/session-system-events.ts:86-90` + - تقوم `drainFormattedSystemEvents(...)` بتصريف الطابور للجلسة. +- `src/auto-reply/reply/get-reply-run.ts:400-427` + - تُضاف كتلة أحداث النظام المصروفة في بداية جسم موجه الوكيل. + +### 6. نقطة الحقن في السجل + +- `src/agents/pi-embedded-runner/run/attempt.ts:2000-2017` + - تستدعي `activeSession.prompt(effectivePrompt)` لإرسال الموجه الكامل إلى جلسة PI المضمّنة. + - هذه هي النقطة التي يصبح فيها الموجه المشتق من الإكمال دور مستخدم محفوظًا. + +لذلك، بمجرد إعادة بناء نفس حدث النظام داخل الموجه مرتين، تصبح رسائل المستخدم المكررة في LCM متوقعة. + +## لماذا تكون إعادة محاولة التسليم الصادر فقط أقل احتمالًا + +يوجد مسار فشل حقيقي في الإرسال الصادر داخل مشغّل Heartbeat: + +- `src/infra/heartbeat-runner.ts:1194-1242` + - يتم توليد الرد أولًا. + - يحدث التسليم الصادر لاحقًا عبر `deliverOutboundPayloads(...)`. + - الفشل هناك يعيد `{ status: "failed" }`. + +لكن بالنسبة إلى نفس إدخال طابور حدث النظام، فهذا وحده **لا يكفي** لتفسير أدوار المستخدم المكررة: + +- `src/auto-reply/reply/session-system-events.ts:86-90` + - يكون قد تم بالفعل تصريف طابور أحداث النظام قبل التسليم الصادر. + +لذلك، فإن إعادة محاولة الإرسال من القناة وحدها لن تعيد إنشاء نفس الحدث الموضوع في الطابور. قد يفسر ذلك غياب/فشل التسليم الخارجي، لكنه لا يفسر بمفرده رسالة مستخدم ثانية متطابقة في الجلسة. + +## احتمال ثانوي أقل ثقة + +يوجد حلقة إعادة محاولة للتشغيل الكامل في مشغّل الوكيل: + +- `src/auto-reply/reply/agent-runner-execution.ts:741-1473` + - بعض الإخفاقات العابرة قد تعيد محاولة التشغيل بالكامل وتعيد إرسال `commandBody` نفسه. + +يمكن أن يؤدي هذا إلى تكرار موجه مستخدم محفوظ **ضمن نفس تنفيذ الرد** إذا كان قد تم إلحاق الموجه بالفعل قبل تحقق شرط إعادة المحاولة. + +أصنّف هذا الاحتمال أدنى من احتمال الاستيعاب المكرر لـ `exec.finished` لأن: + +- الفاصل الملحوظ كان نحو 51 ثانية، وهذا يبدو أكثر كأنه دور/إيقاظ ثانٍ لا إعادة محاولة داخل العملية نفسها؛ +- التقرير يذكر بالفعل إخفاقات متكررة في إرسال الرسائل، ما يشير أكثر إلى دور منفصل لاحق بدلًا من إعادة محاولة فورية في النموذج/بيئة التشغيل. + +## فرضية السبب الجذري + +الفرضية الأعلى ثقة: + +- وصل إكمال `keen-nexus` عبر **مسار حدث تنفيذ Node**. +- تم تسليم `exec.finished` نفسه إلى `server-node-events` مرتين. +- قبل Gateway النسختين لأن `enqueueSystemEvent(...)` لا يزيل التكرار اعتمادًا على `contextKey` / `runId`. +- كل حدث مقبول أدى إلى Heartbeat وتم حقنه كدور مستخدم في سجل PI. + +## إصلاح جراحي صغير مقترح + +إذا كان المطلوب إصلاحًا، فأصغر تغيير عالي القيمة هو: + +- جعل idempotency لأحداث exec/النظام يراعي `contextKey` ضمن نافذة زمنية قصيرة، على الأقل لحالات التكرار المطابق تمامًا لـ `(sessionKey, contextKey, text)`؛ +- أو إضافة إزالة تكرار مخصصة في `server-node-events` لـ `exec.finished` تعتمد على `(sessionKey, runId, event kind)`. + +سيمنع هذا مباشرةً تكرارات `exec.finished` المعاد إرسالها قبل أن تتحول إلى أدوار داخل الجلسة. diff --git a/docs/ar/tools/tts.md b/docs/ar/tools/tts.md index acae4b944..18804f717 100644 --- a/docs/ar/tools/tts.md +++ b/docs/ar/tools/tts.md @@ -1,82 +1,84 @@ --- read_when: - تمكين تحويل النص إلى كلام للردود - - إعداد مزودي TTS أو الحدود + - تهيئة موفري TTS أو الحدود - استخدام أوامر `/tts` summary: تحويل النص إلى كلام (TTS) للردود الصادرة title: تحويل النص إلى كلام x-i18n: - generated_at: "2026-04-12T23:34:02Z" + generated_at: "2026-04-16T07:17:55Z" model: gpt-5.4 provider: openai - source_hash: ad79a6be34879347dc73fdab1bd219823cd7c6aa8504e3e4c73e1a0554c837c5 + source_hash: de7c1dc8831c1ba307596afd48cb4d36f844724887a13b17e35f41ef5174a86f source_path: tools/tts.md workflow: 15 --- # تحويل النص إلى كلام (TTS) -يمكن لـ OpenClaw تحويل الردود الصادرة إلى صوت باستخدام ElevenLabs أو Microsoft أو MiniMax أو OpenAI. -ويعمل هذا في أي مكان يستطيع OpenClaw إرسال الصوت إليه. +يمكن لـ OpenClaw تحويل الردود الصادرة إلى صوت باستخدام ElevenLabs أو Google Gemini أو Microsoft أو MiniMax أو OpenAI. +ويعمل ذلك في أي مكان يستطيع OpenClaw فيه إرسال صوت. ## الخدمات المدعومة -- **ElevenLabs** (كمزود أساسي أو احتياطي) -- **Microsoft** (كمزود أساسي أو احتياطي؛ يستخدم التنفيذ المدمج الحالي `node-edge-tts`) -- **MiniMax** (كمزود أساسي أو احتياطي؛ يستخدم T2A v2 API) -- **OpenAI** (كمزود أساسي أو احتياطي؛ ويُستخدم أيضًا للملخصات) +- **ElevenLabs** (موفر أساسي أو احتياطي) +- **Google Gemini** (موفر أساسي أو احتياطي؛ يستخدم Gemini API TTS) +- **Microsoft** (موفر أساسي أو احتياطي؛ يستخدم التنفيذ المضمّن الحالي `node-edge-tts`) +- **MiniMax** (موفر أساسي أو احتياطي؛ يستخدم واجهة T2A v2 API) +- **OpenAI** (موفر أساسي أو احتياطي؛ ويُستخدم أيضًا للملخصات) ### ملاحظات حول Microsoft speech -يستخدم مزود Microsoft speech المدمج حاليًا خدمة TTS العصبية عبر الإنترنت من Microsoft Edge +يستخدم موفر Microsoft speech المضمّن حاليًا خدمة TTS العصبية عبر الإنترنت من Microsoft Edge من خلال مكتبة `node-edge-tts`. وهي خدمة مستضافة (وليست محلية)، وتستخدم نقاط نهاية Microsoft، ولا تتطلب مفتاح API. -يوفّر `node-edge-tts` خيارات إعدادات للكلام وتنسيقات للإخراج، لكن -ليست كل الخيارات مدعومة من الخدمة. ولا يزال الإدخال الخاص بالإعدادات القديمة وتوجيهات -`edge` يعمل ويتم تطبيعه إلى `microsoft`. +يتيح `node-edge-tts` خيارات لتهيئة النطق وتنسيقات الإخراج، لكن +ليست كل الخيارات مدعومة من الخدمة. ولا يزال الإدخال الخاص +بالتهيئة القديمة والتوجيهات الذي يستخدم `edge` يعمل، ويجري تطبيعه إلى `microsoft`. -ولأن هذا المسار عبارة عن خدمة ويب عامة من دون SLA أو حصة منشورة، -فتعامل معه على أنه أفضل جهد. وإذا كنت تحتاج إلى حدود مضمونة ودعم، فاستخدم OpenAI +نظرًا لأن هذا المسار يعتمد على خدمة ويب عامة من دون SLA أو حصة منشورة، +فتعامل معه على أنه أفضل جهد. إذا كنت بحاجة إلى حدود مضمونة ودعم، فاستخدم OpenAI أو ElevenLabs. ## المفاتيح الاختيارية -إذا كنت تريد OpenAI أو ElevenLabs أو MiniMax: +إذا كنت تريد OpenAI أو ElevenLabs أو Google Gemini أو MiniMax: - `ELEVENLABS_API_KEY` (أو `XI_API_KEY`) +- `GEMINI_API_KEY` (أو `GOOGLE_API_KEY`) - `MINIMAX_API_KEY` - `OPENAI_API_KEY` -لا يتطلب Microsoft speech **مفتاح API**. +لا تتطلب Microsoft speech **مفتاح API**. -إذا تم إعداد عدة مزودين، فسيُستخدم المزود المحدد أولًا وسيكون الآخرون خيارات احتياطية. -ويستخدم التلخيص التلقائي `summaryModel` المُعد (أو `agents.defaults.model.primary`)، -لذلك يجب أيضًا مصادقة ذلك المزود إذا قمت بتمكين الملخصات. +إذا جرى إعداد عدة موفرين، فسيُستخدم الموفر المحدد أولًا وستكون الموفرات الأخرى خيارات احتياطية. +يستخدم التلخيص التلقائي `summaryModel` المُعدّ (أو `agents.defaults.model.primary`)، +لذلك يجب أيضًا أن يكون هذا الموفر موثّقًا إذا فعّلت الملخصات. -## روابط الخدمة +## روابط الخدمات - [دليل OpenAI لتحويل النص إلى كلام](https://platform.openai.com/docs/guides/text-to-speech) - [مرجع OpenAI Audio API](https://platform.openai.com/docs/api-reference/audio) - [تحويل النص إلى كلام في ElevenLabs](https://elevenlabs.io/docs/api-reference/text-to-speech) - [المصادقة في ElevenLabs](https://elevenlabs.io/docs/api-reference/authentication) -- [MiniMax T2A v2 API](https://platform.minimaxi.com/document/T2A%20V2) +- [واجهة MiniMax T2A v2 API](https://platform.minimaxi.com/document/T2A%20V2) - [node-edge-tts](https://github.com/SchneeHertz/node-edge-tts) - [تنسيقات إخراج Microsoft Speech](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs) ## هل هو مفعّل افتراضيًا؟ -لا. إن Auto‑TTS **معطّل** افتراضيًا. قم بتمكينه في الإعدادات باستخدام +لا. يكون Auto‑TTS **متوقفًا** افتراضيًا. فعّله في الإعدادات باستخدام `messages.tts.auto` أو محليًا باستخدام `/tts on`. -عندما لا يتم تعيين `messages.tts.provider`، يختار OpenClaw أول -مزود speech مُعد وفق ترتيب الاختيار التلقائي في السجل. +عندما لا تكون `messages.tts.provider` معيّنة، يختار OpenClaw أول +موفر speech مُعدّ وفق ترتيب الاختيار التلقائي في السجل. -## الإعدادات +## التهيئة -توجد إعدادات TTS ضمن `messages.tts` في `openclaw.json`. -المخطط الكامل موجود في [إعدادات Gateway](/ar/gateway/configuration). +توجد تهيئة TTS ضمن `messages.tts` في `openclaw.json`. +المخطط الكامل موجود في [تهيئة Gateway](/ar/gateway/configuration). -### الحد الأدنى من الإعدادات (التمكين + المزود) +### الحد الأدنى من التهيئة (تمكين + موفر) ```json5 { @@ -89,7 +91,7 @@ x-i18n: } ``` -### OpenAI أساسي مع ElevenLabs احتياطي +### OpenAI كأساسي مع ElevenLabs كاحتياطي ```json5 { @@ -130,7 +132,7 @@ x-i18n: } ``` -### Microsoft أساسي (من دون مفتاح API) +### Microsoft كأساسي (من دون مفتاح API) ```json5 { @@ -153,7 +155,7 @@ x-i18n: } ``` -### MiniMax أساسي +### MiniMax كأساسي ```json5 { @@ -177,6 +179,32 @@ x-i18n: } ``` +### Google Gemini كأساسي + +```json5 +{ + messages: { + tts: { + auto: "always", + provider: "google", + providers: { + google: { + apiKey: "gemini_api_key", + model: "gemini-3.1-flash-tts-preview", + voiceName: "Kore", + }, + }, + }, + }, +} +``` + +يستخدم Google Gemini TTS مسار مفتاح Gemini API. يكون مفتاح API من Google Cloud Console +المقيّد على Gemini API صالحًا هنا، وهو نفس نمط المفتاح المستخدم +من قبل موفر إنشاء الصور المضمّن من Google. ترتيب الاستيفاء هو +`messages.tts.providers.google.apiKey` -> `models.providers.google.apiKey` -> +`GEMINI_API_KEY` -> `GOOGLE_API_KEY`. + ### تعطيل Microsoft speech ```json5 @@ -240,65 +268,69 @@ x-i18n: ### ملاحظات حول الحقول -- `auto`: وضع Auto‑TTS (`off`، `always`، `inbound`، `tagged`). +- `auto`: وضع Auto‑TTS (`off` أو `always` أو `inbound` أو `tagged`). - يرسل `inbound` الصوت فقط بعد رسالة صوتية واردة. - يرسل `tagged` الصوت فقط عندما يتضمن الرد توجيهات `[[tts:key=value]]` أو كتلة `[[tts:text]]...[[/tts:text]]`. - `enabled`: مفتاح تبديل قديم (يقوم doctor بترحيله إلى `auto`). -- `mode`: ‏`"final"` (الافتراضي) أو `"all"` (يتضمن ردود الأدوات/الكتل). -- `provider`: معرّف مزود speech مثل `"elevenlabs"` أو `"microsoft"` أو `"minimax"` أو `"openai"` (ويكون الاحتياطي تلقائيًا). -- إذا لم يتم تعيين `provider`، يستخدم OpenClaw أول مزود speech مُعد وفق ترتيب الاختيار التلقائي في السجل. -- لا يزال `provider: "edge"` القديم يعمل ويتم تطبيعه إلى `microsoft`. +- `mode`: `"final"` (الافتراضي) أو `"all"` (يتضمن ردود الأدوات/الكتل). +- `provider`: معرّف موفر speech مثل `"elevenlabs"` أو `"google"` أو `"microsoft"` أو `"minimax"` أو `"openai"` (يكون الاحتياطي تلقائيًا). +- إذا لم يتم تعيين `provider`، يستخدم OpenClaw أول موفر speech مُعدّ وفق ترتيب الاختيار التلقائي في السجل. +- لا يزال `provider: "edge"` القديم يعمل ويُطبَّع إلى `microsoft`. - `summaryModel`: نموذج منخفض التكلفة اختياري للتلخيص التلقائي؛ والقيمة الافتراضية هي `agents.defaults.model.primary`. - - يقبل `provider/model` أو اسمًا مستعارًا لنموذج مُعد. -- `modelOverrides`: السماح للنموذج بإصدار توجيهات TTS (مفعّل افتراضيًا). - - تكون القيمة الافتراضية لـ `allowProvider` هي `false` (تبديل المزود اشتراك اختياري). -- `providers.`: إعدادات مملوكة للمزود ومفهرسة بمعرّف مزود speech. -- يتم ترحيل كتل المزود المباشرة القديمة (`messages.tts.openai`، و`messages.tts.elevenlabs`، و`messages.tts.microsoft`، و`messages.tts.edge`) تلقائيًا إلى `messages.tts.providers.` عند التحميل. + - يقبل `provider/model` أو اسمًا مستعارًا لنموذج مُعدّ. +- `modelOverrides`: السماح للنموذج بإخراج توجيهات TTS (مفعّل افتراضيًا). + - تكون القيمة الافتراضية لـ `allowProvider` هي `false` (التبديل بين الموفرين يتطلب التفعيل صراحةً). +- `providers.`: إعدادات خاصة بالموفر ومفهرسة بمعرّف موفر speech. +- كتل الموفر القديمة المباشرة (`messages.tts.openai` و`messages.tts.elevenlabs` و`messages.tts.microsoft` و`messages.tts.edge`) تُرحَّل تلقائيًا إلى `messages.tts.providers.` عند التحميل. - `maxTextLength`: حد أقصى صارم لإدخال TTS (أحرف). يفشل `/tts audio` إذا تم تجاوزه. -- `timeoutMs`: مهلة الطلب (مللي ثانية). -- `prefsPath`: تجاوز مسار JSON المحلي للتفضيلات (المزود/الحد/الملخص). -- تعود قيم `apiKey` إلى متغيرات البيئة (`ELEVENLABS_API_KEY`/`XI_API_KEY`، و`MINIMAX_API_KEY`، و`OPENAI_API_KEY`). -- `providers.elevenlabs.baseUrl`: تجاوز عنوان ElevenLabs API الأساسي. +- `timeoutMs`: مهلة انتهاء الطلب (مللي ثانية). +- `prefsPath`: تجاوز مسار JSON المحلي للتفضيلات (الموفر/الحد/الملخص). +- تعود قيم `apiKey` إلى متغيرات البيئة (`ELEVENLABS_API_KEY`/`XI_API_KEY` و`GEMINI_API_KEY`/`GOOGLE_API_KEY` و`MINIMAX_API_KEY` و`OPENAI_API_KEY`). +- `providers.elevenlabs.baseUrl`: تجاوز عنوان URL الأساسي لـ ElevenLabs API. - `providers.openai.baseUrl`: تجاوز نقطة نهاية OpenAI TTS. - - ترتيب الحل: `messages.tts.providers.openai.baseUrl` -> `OPENAI_TTS_BASE_URL` -> `https://api.openai.com/v1` + - ترتيب الاستيفاء: `messages.tts.providers.openai.baseUrl` -> `OPENAI_TTS_BASE_URL` -> `https://api.openai.com/v1` - تُعامل القيم غير الافتراضية على أنها نقاط نهاية TTS متوافقة مع OpenAI، لذلك تُقبل أسماء النماذج والأصوات المخصصة. - `providers.elevenlabs.voiceSettings`: - - `stability`، و`similarityBoost`، و`style`: ‏`0..1` - - `useSpeakerBoost`: ‏`true|false` - - `speed`: ‏`0.5..2.0` ‏(`1.0` = عادي) + - `stability` و`similarityBoost` و`style`: `0..1` + - `useSpeakerBoost`: `true|false` + - `speed`: `0.5..2.0` (1.0 = عادي) - `providers.elevenlabs.applyTextNormalization`: ‏`auto|on|off` -- `providers.elevenlabs.languageCode`: رمز ISO 639-1 من حرفين (مثل `en`، `de`) +- `providers.elevenlabs.languageCode`: رمز ISO 639-1 من حرفين (مثل `en` أو `de`) - `providers.elevenlabs.seed`: عدد صحيح `0..4294967295` (حتمية بأفضل جهد) -- `providers.minimax.baseUrl`: تجاوز عنوان MiniMax API الأساسي (الافتراضي `https://api.minimax.io`، ومتغير البيئة: `MINIMAX_API_HOST`). +- `providers.minimax.baseUrl`: تجاوز عنوان URL الأساسي لـ MiniMax API (الافتراضي `https://api.minimax.io`، ومتغير البيئة: `MINIMAX_API_HOST`). - `providers.minimax.model`: نموذج TTS (الافتراضي `speech-2.8-hd`، ومتغير البيئة: `MINIMAX_TTS_MODEL`). - `providers.minimax.voiceId`: معرّف الصوت (الافتراضي `English_expressive_narrator`، ومتغير البيئة: `MINIMAX_TTS_VOICE_ID`). - `providers.minimax.speed`: سرعة التشغيل `0.5..2.0` (الافتراضي 1.0). -- `providers.minimax.vol`: مستوى الصوت `(0, 10]` (الافتراضي 1.0؛ يجب أن يكون أكبر من 0). -- `providers.minimax.pitch`: إزاحة النغمة `-12..12` (الافتراضي 0). -- `providers.microsoft.enabled`: السماح باستخدام Microsoft speech (الافتراضي `true`؛ من دون مفتاح API). +- `providers.minimax.vol`: مستوى الصوت `(0, 10]` (الافتراضي 1.0؛ ويجب أن يكون أكبر من 0). +- `providers.minimax.pitch`: تغيير النغمة `-12..12` (الافتراضي 0). +- `providers.google.model`: نموذج Gemini TTS (الافتراضي `gemini-3.1-flash-tts-preview`). +- `providers.google.voiceName`: اسم صوت Gemini المضمّن مسبقًا (الافتراضي `Kore`؛ كما يُقبل `voice` أيضًا). +- `providers.google.baseUrl`: تجاوز عنوان URL الأساسي لـ Gemini API. لا يُقبل إلا `https://generativelanguage.googleapis.com`. + - إذا تم حذف `messages.tts.providers.google.apiKey`، يمكن لـ TTS إعادة استخدام `models.providers.google.apiKey` قبل الرجوع إلى متغيرات البيئة. +- `providers.microsoft.enabled`: السماح باستخدام Microsoft speech (الافتراضي `true`؛ بدون مفتاح API). - `providers.microsoft.voice`: اسم الصوت العصبي من Microsoft (مثل `en-US-MichelleNeural`). - `providers.microsoft.lang`: رمز اللغة (مثل `en-US`). - `providers.microsoft.outputFormat`: تنسيق إخراج Microsoft (مثل `audio-24khz-48kbitrate-mono-mp3`). - - راجع تنسيقات إخراج Microsoft Speech للقيم الصالحة؛ ليست كل التنسيقات مدعومة من النقل المدمج المعتمد على Edge. -- `providers.microsoft.rate` / `providers.microsoft.pitch` / `providers.microsoft.volume`: سلاسل نسب مئوية (مثل `+10%`، `-5%`). -- `providers.microsoft.saveSubtitles`: كتابة ترجمات JSON إلى جانب الملف الصوتي. -- `providers.microsoft.proxy`: عنوان URL لـ proxy لطلبات Microsoft speech. -- `providers.microsoft.timeoutMs`: تجاوز مهلة الطلب (مللي ثانية). -- `edge.*`: اسم بديل قديم لإعدادات Microsoft نفسها. + - راجع تنسيقات إخراج Microsoft Speech لمعرفة القيم الصالحة؛ فليست كل التنسيقات مدعومة من النقل المضمّن المعتمد على Edge. +- `providers.microsoft.rate` / `providers.microsoft.pitch` / `providers.microsoft.volume`: سلاسل نسب مئوية (مثل `+10%` و`-5%`). +- `providers.microsoft.saveSubtitles`: كتابة ترجمات JSON إلى جانب ملف الصوت. +- `providers.microsoft.proxy`: عنوان URL للوكيل لطلبات Microsoft speech. +- `providers.microsoft.timeoutMs`: تجاوز مهلة انتهاء الطلب (مللي ثانية). +- `edge.*`: اسم مستعار قديم لإعدادات Microsoft نفسها. ## تجاوزات يقودها النموذج (مفعّلة افتراضيًا) -افتراضيًا، **يمكن** للنموذج إصدار توجيهات TTS لرد واحد. -عندما تكون `messages.tts.auto` هي `tagged`، تكون هذه التوجيهات مطلوبة لتشغيل الصوت. +افتراضيًا، **يمكن** للنموذج إخراج توجيهات TTS لرد واحد. +عندما تكون `messages.tts.auto` مضبوطة على `tagged`، تكون هذه التوجيهات مطلوبة لتفعيل الصوت. -عند التمكين، يمكن للنموذج إصدار توجيهات `[[tts:...]]` لتجاوز الصوت +عند التفعيل، يمكن للنموذج إخراج توجيهات `[[tts:...]]` لتجاوز إعداد الصوت لرد واحد، بالإضافة إلى كتلة اختيارية `[[tts:text]]...[[/tts:text]]` -لتوفير وسوم تعبيرية (ضحك، وإشارات غناء، وما إلى ذلك) ينبغي أن تظهر في -الصوت فقط. +لتوفير وسوم تعبيرية (ضحك، إشارات غناء، وما إلى ذلك) يجب أن تظهر فقط في +الصوت. يتم تجاهل توجيهات `provider=...` ما لم تكن `modelOverrides.allowProvider: true`. -مثال على حمولة الرد: +مثال على حمولة رد: ``` Here you go. @@ -307,15 +339,15 @@ Here you go. [[tts:text]](laughs) Read the song once more.[[/tts:text]] ``` -مفاتيح التوجيه المتاحة (عند التمكين): +مفاتيح التوجيه المتاحة (عند التفعيل): -- `provider` (معرّف مزود speech مسجل، مثل `openai` أو `elevenlabs` أو `minimax` أو `microsoft`؛ ويتطلب `allowProvider: true`) -- `voice` (صوت OpenAI) أو `voiceId` ‏(ElevenLabs / MiniMax) -- `model` (نموذج OpenAI TTS، أو معرّف نموذج ElevenLabs، أو نموذج MiniMax) -- `stability`، و`similarityBoost`، و`style`، و`speed`، و`useSpeakerBoost` -- `vol` / `volume` (مستوى صوت MiniMax، ‏0-10) -- `pitch` (نغمة MiniMax، ‏-12 إلى 12) -- `applyTextNormalization` ‏(`auto|on|off`) +- `provider` (معرّف موفر speech مسجّل، مثل `openai` أو `elevenlabs` أو `google` أو `minimax` أو `microsoft`؛ ويتطلب `allowProvider: true`) +- `voice` (صوت OpenAI)، أو `voiceName` / `voice_name` / `google_voice` (صوت Google)، أو `voiceId` (ElevenLabs / MiniMax) +- `model` (نموذج OpenAI TTS أو معرّف نموذج ElevenLabs أو نموذج MiniMax) أو `google_model` (نموذج Google TTS) +- `stability` و`similarityBoost` و`style` و`speed` و`useSpeakerBoost` +- `vol` / `volume` (مستوى صوت MiniMax، من 0 إلى 10) +- `pitch` (نغمة MiniMax، من -12 إلى 12) +- `applyTextNormalization` (`auto|on|off`) - `languageCode` (ISO 639-1) - `seed` @@ -333,7 +365,7 @@ Here you go. } ``` -قائمة سماح اختيارية (تمكين تبديل المزود مع إبقاء الإعدادات الأخرى قابلة للضبط): +قائمة سماح اختيارية (تمكين التبديل بين الموفرين مع الإبقاء على بقية عناصر الضبط قابلة للتهيئة): ```json5 { @@ -349,48 +381,50 @@ Here you go. } ``` -## التفضيلات لكل مستخدم +## تفضيلات لكل مستخدم -تكتب أوامر الشرطة المائلة التجاوزات المحلية إلى `prefsPath` (الافتراضي: -`~/.openclaw/settings/tts.json`، أو تجاوزه باستخدام `OPENCLAW_TTS_PREFS` أو +تكتب أوامر الشرطة المائلة تجاوزات محلية إلى `prefsPath` (الافتراضي: +`~/.openclaw/settings/tts.json`، ويمكن التجاوز باستخدام `OPENCLAW_TTS_PREFS` أو `messages.tts.prefsPath`). الحقول المخزنة: - `enabled` - `provider` -- `maxLength` (عتبة التلخيص؛ الافتراضي 1500 حرف) +- `maxLength` (حد التلخيص؛ الافتراضي 1500 حرفًا) - `summarize` (الافتراضي `true`) -تتجاوز هذه الحقول `messages.tts.*` لذلك المضيف. +تتجاوز هذه الحقول `messages.tts.*` على ذلك المضيف. ## تنسيقات الإخراج (ثابتة) -- **Feishu / Matrix / Telegram / WhatsApp**: رسالة صوتية Opus ‏(`opus_48000_64` من ElevenLabs، و`opus` من OpenAI). +- **Feishu / Matrix / Telegram / WhatsApp**: رسالة صوتية Opus (`opus_48000_64` من ElevenLabs، و`opus` من OpenAI). - يُعد 48kHz / 64kbps توازنًا جيدًا للرسائل الصوتية. -- **القنوات الأخرى**: MP3 ‏(`mp3_44100_128` من ElevenLabs، و`mp3` من OpenAI). +- **القنوات الأخرى**: MP3 (`mp3_44100_128` من ElevenLabs، و`mp3` من OpenAI). - يُعد 44.1kHz / 128kbps التوازن الافتراضي لوضوح الكلام. -- **MiniMax**: ‏MP3 (نموذج `speech-2.8-hd`، ومعدل عينة 32kHz). لا يتم دعم تنسيق الملاحظات الصوتية أصليًا؛ استخدم OpenAI أو ElevenLabs للحصول على رسائل صوتية Opus مضمونة. +- **MiniMax**: ‏MP3 (نموذج `speech-2.8-hd`، ومعدل عينات 32kHz). لا يدعم تنسيق الملاحظات الصوتية أصلاً؛ استخدم OpenAI أو ElevenLabs إذا كنت بحاجة إلى رسائل صوتية Opus مضمونة. +- **Google Gemini**: يعيد Gemini API TTS بيانات PCM خام بمعدل 24kHz. يغلّفها OpenClaw بصيغة WAV لمرفقات الصوت، ويعيد PCM مباشرةً لـ Talk/telephony. لا يدعم هذا المسار تنسيق ملاحظات Opus الصوتية الأصلي. - **Microsoft**: يستخدم `microsoft.outputFormat` (الافتراضي `audio-24khz-48kbitrate-mono-mp3`). - - يقبل النقل المدمج `outputFormat`، لكن ليست كل التنسيقات متاحة من الخدمة. + - يقبل النقل المضمّن قيمة `outputFormat`، لكن ليست كل التنسيقات متاحة من الخدمة. - تتبع قيم تنسيق الإخراج تنسيقات إخراج Microsoft Speech (بما في ذلك Ogg/WebM Opus). - - يقبل Telegram `sendVoice` تنسيقات OGG/MP3/M4A؛ استخدم OpenAI/ElevenLabs إذا كنت تحتاج إلى رسائل صوتية Opus مضمونة. - - إذا فشل تنسيق إخراج Microsoft المُعد، فسيعيد OpenClaw المحاولة باستخدام MP3. + - يقبل Telegram `sendVoice` تنسيقات OGG/MP3/M4A؛ استخدم OpenAI/ElevenLabs إذا كنت بحاجة + إلى رسائل صوتية Opus مضمونة. + - إذا فشل تنسيق إخراج Microsoft المُعدّ، يعيد OpenClaw المحاولة باستخدام MP3. -تنسيقات إخراج OpenAI/ElevenLabs ثابتة لكل قناة (انظر أعلاه). +تكون تنسيقات إخراج OpenAI/ElevenLabs ثابتة بحسب القناة (انظر أعلاه). ## سلوك Auto-TTS -عند التمكين، يقوم OpenClaw بما يلي: +عند التفعيل، يقوم OpenClaw بما يلي: - يتخطى TTS إذا كان الرد يحتوي بالفعل على وسائط أو توجيه `MEDIA:`. -- يتخطى الردود القصيرة جدًا (< 10 أحرف). -- يلخّص الردود الطويلة عند التمكين باستخدام `agents.defaults.model.primary` (أو `summaryModel`). +- يتخطى الردود القصيرة جدًا (أقل من 10 أحرف). +- يلخّص الردود الطويلة عند التفعيل باستخدام `agents.defaults.model.primary` (أو `summaryModel`). - يرفق الصوت المُنشأ بالرد. -إذا تجاوز الرد `maxLength` وكان التلخيص معطّلًا (أو لا يوجد مفتاح API -لنموذج التلخيص)، فسيتم -تخطي الصوت وإرسال الرد النصي العادي. +إذا تجاوز الرد `maxLength` وكان التلخيص متوقفًا (أو لم يوجد مفتاح API لـ +نموذج التلخيص)، +فسيتم تخطي الصوت وسيُرسل الرد النصي العادي. ## مخطط التدفق @@ -410,10 +444,10 @@ Reply -> TTS enabled? ## استخدام أوامر الشرطة المائلة يوجد أمر واحد فقط: `/tts`. -راجع [أوامر الشرطة المائلة](/ar/tools/slash-commands) لمعرفة تفاصيل التمكين. +راجع [أوامر الشرطة المائلة](/ar/tools/slash-commands) لمعرفة تفاصيل التفعيل. -ملاحظة Discord: ‏`/tts` هو أمر Discord مدمج، لذا يسجل OpenClaw -`/voice` كأمر أصلي هناك. ولا يزال النص `/tts ...` يعمل. +ملاحظة Discord: الأمر `/tts` هو أمر مضمّن في Discord، لذلك يسجّل OpenClaw +`/voice` باعتباره الأمر الأصلي هناك. وما يزال النص `/tts ...` يعمل. ``` /tts off @@ -427,28 +461,28 @@ Reply -> TTS enabled? ملاحظات: -- تتطلب الأوامر مُرسِلًا مخوّلًا (ولا تزال قواعد allowlist/المالك سارية). -- يجب تمكين `commands.text` أو تسجيل الأوامر الأصلية. -- تقبل الإعدادات `messages.tts.auto` القيم `off|always|inbound|tagged`. +- تتطلب الأوامر مُرسِلًا مخوّلًا (وما تزال قواعد allowlist/owner سارية). +- يجب تفعيل `commands.text` أو تسجيل الأوامر الأصلية. +- تقبل تهيئة `messages.tts.auto` القيم `off|always|inbound|tagged`. - يكتب `/tts on` تفضيل TTS المحلي إلى `always`؛ ويكتب `/tts off` إلى `off`. -- استخدم الإعدادات عندما تريد القيم الافتراضية `inbound` أو `tagged`. -- يتم تخزين `limit` و`summary` في التفضيلات المحلية، وليس في الإعدادات الرئيسية. -- يقوم `/tts audio` بإنشاء رد صوتي لمرة واحدة (ولا يفعّل TTS). -- يتضمن `/tts status` عرضًا للاحتياطي لأحدث محاولة: - - احتياطي ناجح: `Fallback: -> ` بالإضافة إلى `Attempts: ...` +- استخدم التهيئة عندما تريد القيم الافتراضية `inbound` أو `tagged`. +- يتم تخزين `limit` و`summary` في التفضيلات المحلية، وليس في التهيئة الرئيسية. +- ينشئ `/tts audio` ردًا صوتيًا لمرة واحدة (ولا يفعّل TTS). +- يتضمن `/tts status` إظهارًا للاحتياطي في آخر محاولة: + - نجاح مع احتياطي: `Fallback: -> ` بالإضافة إلى `Attempts: ...` - فشل: `Error: ...` بالإضافة إلى `Attempts: ...` - - تشخيصات تفصيلية: `Attempt details: provider:outcome(reasonCode) latency` -- تتضمن إخفاقات OpenAI وElevenLabs في API الآن تفاصيل خطأ المزود المحللة ومعرّف الطلب (عند إرجاعه من المزود)، ويتم إظهار ذلك في أخطاء/سجلات TTS. + - تشخيصات مفصلة: `Attempt details: provider:outcome(reasonCode) latency` +- تتضمن حالات فشل OpenAI وElevenLabs API الآن تفاصيل خطأ الموفر المُحللة ومعرّف الطلب (عند إرجاعه من الموفر)، ويظهر ذلك في أخطاء/سجلات TTS. ## أداة الوكيل -تقوم أداة `tts` بتحويل النص إلى كلام وتعيد مرفقًا صوتيًا من أجل +تقوم أداة `tts` بتحويل النص إلى كلام وتُرجع مرفقًا صوتيًا من أجل تسليم الرد. عندما تكون القناة Feishu أو Matrix أو Telegram أو WhatsApp، -يتم تسليم الصوت كرسالة صوتية بدلًا من مرفق ملف. +يُسلَّم الصوت كرسالة صوتية بدلًا من مرفق ملف. ## Gateway RPC -طرق Gateway: +طرائق Gateway: - `tts.status` - `tts.enable`