From 7abbb6caf6bcce4c8f4dac3e33bc75d7be7b4619 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Wed, 8 Apr 2026 02:26:47 +0000 Subject: [PATCH] chore(i18n): refresh ar translations --- docs/ar/channels/matrix.md | 702 +++---- docs/ar/concepts/compaction.md | 149 +- docs/ar/concepts/context-engine.md | 216 +- docs/ar/concepts/model-providers.md | 797 ++++---- docs/ar/concepts/qa-e2e-automation.md | 81 +- docs/ar/concepts/system-prompt.md | 192 +- docs/ar/gateway/cli-backends.md | 195 +- docs/ar/gateway/configuration-reference.md | 1221 ++++++------ docs/ar/gateway/doctor.md | 482 ++--- docs/ar/gateway/heartbeat.md | 346 ++-- docs/ar/gateway/local-models.md | 85 +- docs/ar/gateway/protocol.md | 622 +++--- docs/ar/gateway/troubleshooting.md | 350 ++-- docs/ar/help/faq.md | 1645 ++++++++-------- docs/ar/help/scripts.md | 58 +- docs/ar/help/testing.md | 748 +++---- docs/ar/help/troubleshooting.md | 319 +-- docs/ar/plugins/architecture.md | 1742 +++++++++-------- docs/ar/plugins/sdk-channel-plugins.md | 366 ++-- docs/ar/plugins/sdk-migration.md | 514 ++--- docs/ar/plugins/sdk-overview.md | 603 +++--- docs/ar/providers/google.md | 142 +- docs/ar/providers/index.md | 45 +- docs/ar/providers/inferrs.md | 180 ++ docs/ar/providers/mistral.md | 61 +- docs/ar/providers/models.md | 34 +- docs/ar/providers/nvidia.md | 39 +- docs/ar/providers/ollama.md | 162 +- docs/ar/refactor/qa.md | 534 +++++ .../session-management-compaction.md | 293 +-- docs/ar/reference/test.md | 108 +- docs/ar/tools/acp-agents.md | 594 +++--- docs/ar/tools/exec-approvals.md | 545 +++--- 33 files changed, 7640 insertions(+), 6530 deletions(-) create mode 100644 docs/ar/providers/inferrs.md create mode 100644 docs/ar/refactor/qa.md diff --git a/docs/ar/channels/matrix.md b/docs/ar/channels/matrix.md index 0bbc1ac35..5e5ff6bdf 100644 --- a/docs/ar/channels/matrix.md +++ b/docs/ar/channels/matrix.md @@ -1,29 +1,29 @@ --- read_when: - إعداد Matrix في OpenClaw - - تهيئة التشفير التام بين الطرفين E2EE والتحقق في Matrix -summary: حالة دعم Matrix وإعدادها وأمثلة التهيئة + - تكوين E2EE والتحقق في Matrix +summary: حالة دعم Matrix وإعداده وأمثلة التكوين title: Matrix x-i18n: - generated_at: "2026-04-07T07:18:58Z" + generated_at: "2026-04-08T02:16:33Z" model: gpt-5.4 provider: openai - source_hash: d53baa2ea5916cd00a99cae0ded3be41ffa13c9a69e8ea8461eb7baa6a99e13c + source_hash: ec926df79a41fa296d63f0ec7219d0f32e075628d76df9ea490e93e4c5030f83 source_path: channels/matrix.md workflow: 15 --- # Matrix -Matrix هي plugin القناة المضمّنة Matrix لـ OpenClaw. -تستخدم `matrix-js-sdk` الرسمية وتدعم الرسائل الخاصة، والغرف، وسلاسل الرسائل، والوسائط، والتفاعلات، واستطلاعات الرأي، والموقع، وE2EE. +Matrix هو إضافة القناة المضمّنة Matrix في OpenClaw. +يستخدم `matrix-js-sdk` الرسمي ويدعم الرسائل المباشرة، والغرف، والخيوط، والوسائط، والتفاعلات، والاستطلاعات، والموقع، وE2EE. -## plugin مضمّنة +## الإضافة المضمّنة -تأتي Matrix كـ plugin مضمّنة في إصدارات OpenClaw الحالية، لذلك لا تحتاج -البنيات المجمّعة العادية إلى تثبيت منفصل. +يأتي Matrix كإضافة مضمّنة في إصدارات OpenClaw الحالية، لذلك لا تحتاج +الإصدارات المعبأة العادية إلى تثبيت منفصل. -إذا كنت تستخدم إصدارًا أقدم أو تثبيتًا مخصصًا يستبعد Matrix، فقم بتثبيتها +إذا كنت تستخدم إصدارًا أقدم أو تثبيتًا مخصصًا يستثني Matrix، فقم بتثبيته يدويًا: التثبيت من npm: @@ -32,67 +32,67 @@ Matrix هي plugin القناة المضمّنة Matrix لـ OpenClaw. openclaw plugins install @openclaw/matrix ``` -التثبيت من نسخة محلية: +التثبيت من نسخة سحب محلية: ```bash openclaw plugins install ./path/to/local/matrix-plugin ``` -راجع [Plugins](/ar/tools/plugin) لمعرفة سلوك plugin وقواعد التثبيت. +راجع [الإضافات](/ar/tools/plugin) للاطلاع على سلوك الإضافات وقواعد التثبيت. ## الإعداد -1. تأكد من أن plugin Matrix متاحة. - - إصدارات OpenClaw المجمّعة الحالية تتضمنها بالفعل. +1. تأكد من أن إضافة Matrix متاحة. + - إصدارات OpenClaw المعبأة الحالية تتضمنها بالفعل. - يمكن للتثبيتات الأقدم/المخصصة إضافتها يدويًا باستخدام الأوامر أعلاه. -2. أنشئ حساب Matrix على خادمك المنزلي. -3. هيّئ `channels.matrix` باستخدام أحد الخيارين: +2. أنشئ حساب Matrix على الخادم المنزلي الخاص بك. +3. قم بتكوين `channels.matrix` باستخدام أحد الخيارين التاليين: - `homeserver` + `accessToken`، أو - `homeserver` + `userId` + `password`. 4. أعد تشغيل البوابة. -5. ابدأ رسالة خاصة مع الروبوت أو قم بدعوته إلى غرفة. - - لا تعمل دعوات Matrix الجديدة إلا عندما يسمح `channels.matrix.autoJoin` بذلك. +5. ابدأ رسالة مباشرة مع الروبوت أو ادعه إلى غرفة. + - لا تعمل دعوات Matrix الجديدة إلا عندما يسمح `channels.matrix.autoJoin` بها. -مسارات الإعداد التفاعلي: +مسارات الإعداد التفاعلية: ```bash openclaw channels add openclaw configure --section channels ``` -ما الذي يطلبه معالج Matrix فعليًا: +ما الذي يسأل عنه معالج Matrix فعليًا: -- عنوان URL لـ homeserver -- طريقة المصادقة: access token أو كلمة مرور -- معرّف المستخدم فقط عند اختيار مصادقة كلمة المرور +- عنوان URL للخادم المنزلي +- طريقة المصادقة: رمز وصول أو كلمة مرور +- معرّف المستخدم فقط عند اختيار المصادقة بكلمة المرور - اسم جهاز اختياري - ما إذا كان يجب تمكين E2EE -- ما إذا كان يجب تهيئة الوصول إلى غرف Matrix الآن -- ما إذا كان يجب تهيئة الانضمام التلقائي إلى دعوات Matrix الآن +- ما إذا كان يجب تكوين وصول غرفة Matrix الآن +- ما إذا كان يجب تكوين الانضمام التلقائي لدعوات Matrix الآن - عند تمكين الانضمام التلقائي للدعوات، ما إذا كان يجب أن يكون `allowlist` أو `always` أو `off` -سلوك المعالج الذي يهمك: +سلوك المعالج المهم: -- إذا كانت متغيرات بيئة مصادقة Matrix موجودة بالفعل للحساب المحدد، ولم يكن لهذا الحساب مصادقة محفوظة بالفعل في التهيئة، فسيعرض المعالج اختصارًا لمتغيرات البيئة حتى يحتفظ الإعداد بالمصادقة في متغيرات البيئة بدلًا من نسخ الأسرار إلى التهيئة. -- عند إضافة حساب Matrix آخر بشكل تفاعلي، يُطبَّع اسم الحساب المُدخل إلى معرّف الحساب المستخدم في التهيئة ومتغيرات البيئة. على سبيل المثال، يتحول `Ops Bot` إلى `ops-bot`. -- تقبل مطالبات allowlist للرسائل الخاصة قيم `@user:server` الكاملة مباشرةً. تعمل أسماء العرض فقط عندما يعثر البحث الحي في الدليل على تطابق واحد دقيق؛ وإلا يطلب منك المعالج إعادة المحاولة باستخدام معرّف Matrix كامل. -- تقبل مطالبات allowlist للغرف معرّفات الغرف والأسماء المستعارة مباشرةً. ويمكنها أيضًا تحليل أسماء الغرف المنضم إليها مباشرة، لكن الأسماء التي لا يمكن تحليلها تُحتفظ بها كما أُدخلت أثناء الإعداد فقط ويتم تجاهلها لاحقًا بواسطة تحليل allowlist أثناء التشغيل. يفضَّل استخدام `!room:server` أو `#alias:server`. -- يعرض المعالج الآن تحذيرًا صريحًا قبل خطوة الانضمام التلقائي للدعوات لأن `channels.matrix.autoJoin` تكون افتراضيًا `off`؛ ولن تنضم الوكلاء إلى الغرف المدعوة أو دعوات الرسائل الخاصة الجديدة ما لم تقم بتعيينها. -- في وضع allowlist للانضمام التلقائي للدعوات، استخدم فقط أهداف الدعوات الثابتة: `!roomId:server` أو `#alias:server` أو `*`. تُرفض أسماء الغرف العادية. -- تستخدم هوية الغرفة/الجلسة أثناء التشغيل معرّف غرفة Matrix الثابت. تُستخدم الأسماء المستعارة المعلنة للغرفة فقط كمدخلات للبحث، وليس كمفتاح جلسة طويل الأمد أو هوية مجموعة ثابتة. -- لتحليل أسماء الغرف قبل حفظها، استخدم `openclaw channels resolve --channel matrix "Project Room"`. +- إذا كانت متغيرات البيئة الخاصة بمصادقة Matrix موجودة بالفعل للحساب المحدد، ولم يكن هذا الحساب محفوظًا له مصادقة في التكوين بعد، فسيعرض المعالج اختصارًا للبيئة بحيث يمكن للإعداد إبقاء المصادقة في متغيرات البيئة بدلًا من نسخ الأسرار إلى التكوين. +- عند إضافة حساب Matrix آخر بشكل تفاعلي، يُطبَّع اسم الحساب المُدخل إلى معرّف الحساب المستخدم في التكوين ومتغيرات البيئة. على سبيل المثال، يتحول `Ops Bot` إلى `ops-bot`. +- تقبل مطالبات قائمة السماح للرسائل المباشرة قيم `@user:server` الكاملة مباشرة. تعمل أسماء العرض فقط عندما يعثر البحث المباشر في الدليل على تطابق واحد دقيق؛ وإلا فسيطلب منك المعالج إعادة المحاولة باستخدام معرّف Matrix كامل. +- تقبل مطالبات قائمة السماح للغرف معرّفات الغرف والأسماء المستعارة مباشرة. ويمكنها أيضًا حل أسماء الغرف المنضم إليها بشكل مباشر، لكن الأسماء غير المحلولة تُحتفظ بها كما أُدخلت أثناء الإعداد فقط ويتم تجاهلها لاحقًا بواسطة حل قائمة السماح وقت التشغيل. فضّل استخدام `!room:server` أو `#alias:server`. +- يعرض المعالج الآن تحذيرًا صريحًا قبل خطوة الانضمام التلقائي للدعوات لأن القيمة الافتراضية لـ `channels.matrix.autoJoin` هي `off`؛ لن تنضم الوكلاء إلى الغرف المدعوّة أو الدعوات الجديدة الشبيهة بالرسائل المباشرة ما لم تقم بتعيينه. +- في وضع قائمة السماح للانضمام التلقائي للدعوات، استخدم فقط أهداف دعوات مستقرة: `!roomId:server` أو `#alias:server` أو `*`. تُرفض أسماء الغرف العادية. +- تستخدم هوية الغرفة/الجلسة وقت التشغيل معرّف غرفة Matrix المستقر. لا تُستخدم الأسماء المستعارة المعلنة في الغرفة إلا كمدخلات للبحث، وليس كمفتاح جلسة طويل الأمد أو هوية مجموعة مستقرة. +- لحل أسماء الغرف قبل حفظها، استخدم `openclaw channels resolve --channel matrix "Project Room"`. القيمة الافتراضية لـ `channels.matrix.autoJoin` هي `off`. -إذا تركتها دون تعيين، فلن ينضم الروبوت إلى الغرف المدعوة أو دعوات الرسائل الخاصة الجديدة، ولذلك لن يظهر في المجموعات الجديدة أو الرسائل الخاصة المدعوة ما لم تنضم يدويًا أولًا. +إذا تركته غير معيّن، فلن ينضم الروبوت إلى الغرف المدعوّة أو الدعوات الجديدة الشبيهة بالرسائل المباشرة، لذلك لن يظهر في المجموعات الجديدة أو الرسائل المباشرة المدعو إليها ما لم تنضم يدويًا أولًا. -عيّن `autoJoin: "allowlist"` مع `autoJoinAllowlist` لتقييد الدعوات التي يقبلها، أو عيّن `autoJoin: "always"` إذا كنت تريده أن ينضم إلى كل دعوة. +عيّن `autoJoin: "allowlist"` مع `autoJoinAllowlist` لتقييد الدعوات التي يقبلها، أو عيّن `autoJoin: "always"` إذا كنت تريد منه الانضمام إلى كل دعوة. في وضع `allowlist`، لا يقبل `autoJoinAllowlist` إلا `!roomId:server` أو `#alias:server` أو `*`. -مثال allowlist: +مثال على قائمة السماح: ```json5 { @@ -122,7 +122,7 @@ openclaw configure --section channels } ``` -إعداد أدنى يعتمد على token: +إعداد أدنى يعتمد على الرمز: ```json5 { @@ -137,7 +137,7 @@ openclaw configure --section channels } ``` -إعداد يعتمد على كلمة المرور (يُخزَّن token مؤقتًا بعد تسجيل الدخول): +إعداد يعتمد على كلمة المرور (يتم تخزين الرمز مؤقتًا بعد تسجيل الدخول): ```json5 { @@ -153,11 +153,11 @@ openclaw configure --section channels } ``` -تخزّن Matrix بيانات الاعتماد المؤقتة في `~/.openclaw/credentials/matrix/`. +يخزن Matrix بيانات الاعتماد المخزنة مؤقتًا في `~/.openclaw/credentials/matrix/`. يستخدم الحساب الافتراضي `credentials.json`؛ وتستخدم الحسابات المسماة `credentials-.json`. -عند وجود بيانات اعتماد مؤقتة هناك، يتعامل OpenClaw مع Matrix على أنها مُهيأة لأغراض الإعداد وdoctor واكتشاف حالة القناة حتى إذا لم تُضبط المصادقة الحالية مباشرة في التهيئة. +عند وجود بيانات اعتماد مخزنة مؤقتًا هناك، يتعامل OpenClaw مع Matrix على أنه مُكوَّن من أجل الإعداد، وdoctor، واكتشاف حالة القناة حتى إذا لم تكن المصادقة الحالية معيّنة مباشرة في التكوين. -مكافئات متغيرات البيئة (تُستخدم عندما لا يكون مفتاح التهيئة مضبوطًا): +مكافئات متغيرات البيئة (تُستخدم عندما لا يكون مفتاح التكوين معيّنًا): - `MATRIX_HOMESERVER` - `MATRIX_ACCESS_TOKEN` @@ -166,7 +166,7 @@ openclaw configure --section channels - `MATRIX_DEVICE_ID` - `MATRIX_DEVICE_NAME` -للحسابات غير الافتراضية، استخدم متغيرات بيئة بنطاق الحساب: +للحسابات غير الافتراضية، استخدم متغيرات البيئة ذات النطاق الخاص بالحساب: - `MATRIX__HOMESERVER` - `MATRIX__ACCESS_TOKEN` @@ -180,19 +180,19 @@ openclaw configure --section channels - `MATRIX_OPS_HOMESERVER` - `MATRIX_OPS_ACCESS_TOKEN` -بالنسبة إلى معرّف الحساب المطبع `ops-bot`، استخدم: +بالنسبة إلى معرّف الحساب المُطبّع `ops-bot`، استخدم: - `MATRIX_OPS_X2D_BOT_HOMESERVER` - `MATRIX_OPS_X2D_BOT_ACCESS_TOKEN` -تقوم Matrix بتهريب علامات الترقيم في معرّفات الحسابات للحفاظ على خلو متغيرات البيئة ذات النطاق المحدد من التصادمات. -فعلى سبيل المثال، يتحول `-` إلى `_X2D_`، لذلك يتحول `ops-prod` إلى `MATRIX_OPS_X2D_PROD_*`. +يهرب Matrix علامات الترقيم في معرّفات الحسابات للحفاظ على متغيرات البيئة ذات النطاق الخاص خالية من التعارضات. +على سبيل المثال، تتحول `-` إلى `_X2D_`، لذا يُطابق `ops-prod` النمط `MATRIX_OPS_X2D_PROD_*`. -لا يعرض المعالج التفاعلي اختصار متغيرات البيئة إلا عندما تكون متغيرات بيئة المصادقة تلك موجودة بالفعل، ولا يكون للحساب المحدد مصادقة Matrix محفوظة بالفعل في التهيئة. +لا يعرض المعالج التفاعلي اختصار متغيرات البيئة إلا عندما تكون متغيرات بيئة المصادقة هذه موجودة بالفعل ولا تكون مصادقة Matrix للحساب المحدد محفوظة بالفعل في التكوين. -## مثال على التهيئة +## مثال على التكوين -هذه تهيئة أساسية عملية تتضمن pairing للرسائل الخاصة، وallowlist للغرف، وتمكين E2EE: +هذا تكوين أساسي عملي يتضمن إقران الرسائل المباشرة، وقائمة سماح للغرف، وتمكين E2EE: ```json5 { @@ -228,19 +228,19 @@ openclaw configure --section channels ``` ينطبق `autoJoin` على دعوات Matrix عمومًا، وليس فقط على دعوات الغرف/المجموعات. -ويشمل ذلك دعوات الرسائل الخاصة الجديدة. في وقت الدعوة، لا يعرف OpenClaw بشكل موثوق ما إذا كانت -الغرفة المدعوة ستُعامل في النهاية كرسالة خاصة أو كمجموعة، لذلك تمر جميع الدعوات عبر قرار -`autoJoin` نفسه أولًا. يظل `dm.policy` مطبقًا بعد انضمام الروبوت وتصنيف الغرفة -كرسالة خاصة، لذلك يتحكم `autoJoin` في سلوك الانضمام بينما يتحكم `dm.policy` في سلوك +ويشمل ذلك الدعوات الجديدة الشبيهة بالرسائل المباشرة. في وقت الدعوة، لا يعرف OpenClaw بشكل موثوق ما إذا كانت +الغرفة المدعو إليها ستُعامل في النهاية كرسالة مباشرة أم كمجموعة، لذلك تمر جميع الدعوات عبر نفس +قرار `autoJoin` أولًا. يظل `dm.policy` مطبقًا بعد انضمام الروبوت وتصنيف الغرفة +كرسالة مباشرة، لذا يتحكم `autoJoin` في سلوك الانضمام بينما يتحكم `dm.policy` في سلوك الرد/الوصول. ## معاينات البث -بث الردود في Matrix ميزة اختيارية. +بث الردود في Matrix اختياري. عيّن `channels.matrix.streaming` إلى `"partial"` عندما تريد من OpenClaw إرسال -رد معاينة مباشر واحد، وتحرير هذه المعاينة في مكانها أثناء توليد النص من النموذج، ثم إنهاءها عند -اكتمال الرد: +رد معاينة مباشر واحد، وتحرير هذه المعاينة في مكانها بينما يولد النموذج النص، ثم إنهاءها عندما +يكتمل الرد: ```json5 { @@ -252,38 +252,38 @@ openclaw configure --section channels } ``` -- `streaming: "off"` هو الإعداد الافتراضي. ينتظر OpenClaw الرد النهائي ويرسله مرة واحدة. -- `streaming: "partial"` ينشئ رسالة معاينة واحدة قابلة للتحرير لكتلة المساعد الحالية باستخدام رسائل Matrix النصية العادية. يحافظ هذا على سلوك الإشعارات القديم في Matrix القائم على المعاينة أولًا، لذلك قد تُرسل التطبيقات القياسية إشعارًا عند نص المعاينة الأول المتدفق بدلًا من الكتلة النهائية. -- `streaming: "quiet"` ينشئ إشعار معاينة هادئًا واحدًا قابلًا للتحرير لكتلة المساعد الحالية. استخدم هذا فقط عندما تهيئ أيضًا قواعد push للمستلمين من أجل تعديلات المعاينة النهائية. -- `blockStreaming: true` يمكّن رسائل تقدم Matrix المنفصلة. عند تمكين بث المعاينة، تحتفظ Matrix بالمسودة المباشرة للكتلة الحالية وتحافظ على الكتل المكتملة كرسائل منفصلة. -- عند تشغيل بث المعاينة وإيقاف `blockStreaming`، تقوم Matrix بتحرير المسودة المباشرة في مكانها وتُنهي الحدث نفسه عند اكتمال الكتلة أو الدورة. -- إذا لم تعد المعاينة مناسبة لحدث Matrix واحد، يوقف OpenClaw بث المعاينة ويعود إلى التسليم النهائي العادي. -- تظل ردود الوسائط ترسل المرفقات بشكل طبيعي. وإذا تعذّر إعادة استخدام معاينة قديمة بأمان، يقوم OpenClaw بحذفها قبل إرسال رد الوسائط النهائي. -- تتطلب تعديلات المعاينة استدعاءات إضافية إلى Matrix API. اترك البث معطلًا إذا كنت تريد أكثر سلوك تحفظًا من ناحية حدود المعدل. +- `streaming: "off"` هو الافتراضي. ينتظر OpenClaw الرد النهائي ويرسله مرة واحدة. +- ينشئ `streaming: "partial"` رسالة معاينة واحدة قابلة للتحرير للكتلة الحالية من رد المساعد باستخدام رسائل Matrix النصية العادية. يحافظ هذا على سلوك الإشعارات القديم في Matrix القائم على المعاينة أولًا، لذا قد ترسل البرامج العميلة القياسية إشعارًا عند نص المعاينة الأول المبثوث بدلًا من الكتلة النهائية. +- ينشئ `streaming: "quiet"` إشعار معاينة هادئ واحد قابل للتحرير للكتلة الحالية من رد المساعد. استخدم هذا فقط عندما تضبط أيضًا قواعد دفع للمستلمين من أجل تعديلات المعاينة النهائية. +- يفعّل `blockStreaming: true` رسائل تقدم منفصلة في Matrix. عند تمكين بث المعاينة، يحتفظ Matrix بالمسودة المباشرة للكتلة الحالية ويحافظ على الكتل المكتملة كرسائل منفصلة. +- عندما يكون بث المعاينة قيد التشغيل ويكون `blockStreaming` معطّلًا، يحرر Matrix المسودة المباشرة في مكانها وينهي نفس الحدث عند اكتمال الكتلة أو الدور. +- إذا لم تعد المعاينة تتسع لحدث Matrix واحد، يوقف OpenClaw بث المعاينة ويعود إلى التسليم النهائي العادي. +- لا تزال ردود الوسائط ترسل المرفقات بشكل طبيعي. إذا تعذر إعادة استخدام معاينة قديمة بأمان، يقوم OpenClaw بحذفها قبل إرسال رد الوسائط النهائي. +- تكلف تعديلات المعاينة استدعاءات إضافية إلى Matrix API. اترك البث معطّلًا إذا كنت تريد أكثر سلوك محافظ فيما يتعلق بحدود المعدل. -لا يقوم `blockStreaming` بتمكين معاينات المسودات بمفرده. -استخدم `streaming: "partial"` أو `streaming: "quiet"` لتعديلات المعاينة؛ ثم أضف `blockStreaming: true` فقط إذا كنت تريد أيضًا أن تبقى كتل المساعد المكتملة مرئية كرسائل تقدم منفصلة. +لا يفعّل `blockStreaming` معاينات المسودة بحد ذاته. +استخدم `streaming: "partial"` أو `streaming: "quiet"` من أجل تعديلات المعاينة؛ ثم أضف `blockStreaming: true` فقط إذا كنت تريد أيضًا أن تظل كتل المساعد المكتملة مرئية كرسائل تقدم منفصلة. -إذا كنت تحتاج إلى إشعارات Matrix القياسية دون قواعد push مخصصة، فاستخدم `streaming: "partial"` لسلوك المعاينة أولًا أو اترك `streaming` معطلًا للتسليم النهائي فقط. مع `streaming: "off"`: +إذا كنت تحتاج إلى إشعارات Matrix القياسية دون قواعد دفع مخصصة، فاستخدم `streaming: "partial"` لسلوك المعاينة أولًا أو اترك `streaming` معطّلًا للتسليم النهائي فقط. مع `streaming: "off"`: -- `blockStreaming: true` يرسل كل كتلة مكتملة كرسالة Matrix عادية تُرسل إشعارًا. -- `blockStreaming: false` يرسل فقط الرد النهائي المكتمل كرسالة Matrix عادية تُرسل إشعارًا. +- يرسل `blockStreaming: true` كل كتلة مكتملة كرسالة Matrix عادية ترسل إشعارًا. +- يرسل `blockStreaming: false` الرد النهائي المكتمل فقط كرسالة Matrix عادية ترسل إشعارًا. -### قواعد push مستضافة ذاتيًا للمعاينات النهائية الهادئة +### قواعد دفع مستضافة ذاتيًا للمعاينات النهائية الهادئة -إذا كنت تشغّل بنية Matrix التحتية الخاصة بك وتريد أن ترسل المعاينات الهادئة إشعارًا فقط عند اكتمال كتلة أو -الرد النهائي، فعيّن `streaming: "quiet"` وأضف قاعدة push لكل مستخدم من أجل تعديلات المعاينة النهائية. +إذا كنت تشغّل بنية Matrix الخاصة بك وتريد أن ترسل المعاينات الهادئة إشعارًا فقط عند اكتمال كتلة أو +الرد النهائي، فعيّن `streaming: "quiet"` وأضف قاعدة دفع لكل مستخدم لمعاينات التعديل النهائية. -يكون هذا عادة إعدادًا على مستوى المستخدم المستلم، وليس تغييرًا عامًا في تهيئة homeserver: +يكون هذا عادة إعدادًا على مستوى المستخدم المستلم، وليس تغييرًا عامًا في تكوين الخادم المنزلي: -خريطة سريعة قبل البدء: +خريطة سريعة قبل أن تبدأ: - المستخدم المستلم = الشخص الذي يجب أن يتلقى الإشعار -- مستخدم الروبوت = حساب Matrix الخاص بـ OpenClaw الذي يرسل الرد -- استخدم access token الخاص بالمستخدم المستلم لطلبات API أدناه -- طابق `sender` في قاعدة push مع MXID الكامل لمستخدم الروبوت +- مستخدم الروبوت = حساب OpenClaw Matrix الذي يرسل الرد +- استخدم رمز وصول المستخدم المستلم في استدعاءات API أدناه +- طابق `sender` في قاعدة الدفع مع MXID الكامل لمستخدم الروبوت -1. هيّئ OpenClaw لاستخدام المعاينات الهادئة: +1. قم بتكوين OpenClaw لاستخدام المعاينات الهادئة: ```json5 { @@ -295,13 +295,13 @@ openclaw configure --section channels } ``` -2. تأكد من أن حساب المستلم يتلقى بالفعل إشعارات push العادية من Matrix. تعمل قواعد المعاينة الهادئة - فقط إذا كان لدى هذا المستخدم بالفعل pushers/أجهزة عاملة. +2. تأكد من أن حساب المستلم يتلقى بالفعل إشعارات دفع Matrix العادية. قواعد المعاينة الهادئة + لا تعمل إلا إذا كان لدى هذا المستخدم بالفعل أجهزة/خدمات دفع عاملة. -3. احصل على access token الخاص بالمستخدم المستلم. - - استخدم token المستخدم المتلقي، وليس token الروبوت. - - عادةً ما تكون إعادة استخدام token جلسة عميل موجودة هي الأسهل. - - إذا كنت بحاجة إلى إصدار token جديد، يمكنك تسجيل الدخول عبر Matrix Client-Server API القياسية: +3. احصل على رمز وصول المستخدم المستلم. + - استخدم رمز المستخدم المستقبل، وليس رمز الروبوت. + - عادةً ما تكون إعادة استخدام رمز جلسة عميل موجودة هي الأسهل. + - إذا احتجت إلى إصدار رمز جديد، يمكنك تسجيل الدخول عبر Matrix Client-Server API القياسي: ```bash curl -sS -X POST \ @@ -317,7 +317,7 @@ curl -sS -X POST \ }' ``` -4. تحقق من أن حساب المستلم لديه pushers بالفعل: +4. تحقق من أن حساب المستلم يحتوي بالفعل على pushers: ```bash curl -sS \ @@ -325,10 +325,10 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushers" ``` -إذا أعاد هذا الاستعلام عدم وجود pushers/أجهزة نشطة، فأصلح إشعارات Matrix العادية أولًا قبل إضافة +إذا لم يُرجع هذا أي pushers/أجهزة نشطة، فأصلح إشعارات Matrix العادية أولًا قبل إضافة قاعدة OpenClaw أدناه. -تضع OpenClaw علامة على تعديلات معاينات النص النهائي فقط بالقيمة التالية: +يضع OpenClaw علامة على تعديلات المعاينة النهائية النصية فقط باستخدام: ```json { @@ -336,7 +336,7 @@ curl -sS \ } ``` -5. أنشئ قاعدة push من نوع override لكل حساب مستلم يجب أن يتلقى هذه الإشعارات: +5. أنشئ قاعدة دفع override لكل حساب مستلم يجب أن يتلقى هذه الإشعارات: ```bash curl -sS -X PUT \ @@ -368,21 +368,21 @@ curl -sS -X PUT \ استبدل هذه القيم قبل تشغيل الأمر: -- `https://matrix.example.org`: عنوان URL الأساسي لـ homeserver لديك -- `$USER_ACCESS_TOKEN`: access token الخاص بالمستخدم المتلقي -- `openclaw-finalized-preview-botname`: معرّف قاعدة فريد لهذا الروبوت لهذا المستخدم المتلقي -- `@bot:example.org`: معرّف MXID لروبوت Matrix الخاص بـ OpenClaw، وليس MXID الخاص بالمستخدم المتلقي +- `https://matrix.example.org`: عنوان URL الأساسي للخادم المنزلي الخاص بك +- `$USER_ACCESS_TOKEN`: رمز وصول المستخدم المستلم +- `openclaw-finalized-preview-botname`: معرّف قاعدة فريد لهذا الروبوت لهذا المستخدم المستلم +- `@bot:example.org`: MXID روبوت OpenClaw Matrix لديك، وليس MXID المستخدم المستلم -مهم لعمليات إعداد الروبوتات المتعددة: +مهم لإعدادات الروبوتات المتعددة: -- تُفهرس قواعد push بواسطة `ruleId`. تؤدي إعادة تشغيل `PUT` على معرّف القاعدة نفسه إلى تحديث تلك القاعدة. -- إذا كان يجب على مستخدم متلقٍ واحد تلقي إشعارات من عدة حسابات روبوت Matrix تابعة لـ OpenClaw، فأنشئ قاعدة واحدة لكل روبوت مع معرّف قاعدة فريد لكل تطابق `sender`. -- نمط بسيط لذلك هو `openclaw-finalized-preview-`، مثل `openclaw-finalized-preview-ops` أو `openclaw-finalized-preview-support`. +- تُفهرس قواعد الدفع بواسطة `ruleId`. تؤدي إعادة تشغيل `PUT` على نفس معرّف القاعدة إلى تحديث تلك القاعدة. +- إذا كان يجب على مستخدم مستلم واحد تلقي إشعارات من عدة حسابات روبوت OpenClaw Matrix، فأنشئ قاعدة واحدة لكل روبوت مع معرّف قاعدة فريد لكل مطابقة `sender`. +- نمط بسيط هو `openclaw-finalized-preview-`، مثل `openclaw-finalized-preview-ops` أو `openclaw-finalized-preview-support`. -تُقيَّم القاعدة مقابل مرسل الحدث: +يتم تقييم القاعدة مقابل مُرسل الحدث: -- قم بالمصادقة باستخدام token المستخدم المتلقي -- طابق `sender` مع MXID الخاص بروبوت OpenClaw +- قم بالمصادقة باستخدام رمز المستخدم المستلم +- طابق `sender` مع MXID روبوت OpenClaw 6. تحقق من وجود القاعدة: @@ -392,10 +392,10 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" ``` -7. اختبر ردًا متدفقًا. في الوضع الهادئ، يجب أن تعرض الغرفة معاينة مسودة هادئة وأن - يرسل التعديل النهائي في مكانه إشعارًا واحدًا عند اكتمال الكتلة أو الدورة. +7. اختبر ردًا مبثوثًا. في الوضع الهادئ، يجب أن تعرض الغرفة معاينة مسودة هادئة وأن + يرسل التعديل النهائي في المكان إشعارًا واحدًا عند اكتمال الكتلة أو الدور. -إذا احتجت إلى إزالة القاعدة لاحقًا، فاحذف معرّف القاعدة نفسه باستخدام token المستخدم المتلقي: +إذا احتجت إلى إزالة القاعدة لاحقًا، فاحذف معرّف القاعدة نفسه باستخدام رمز المستخدم المستلم: ```bash curl -sS -X DELETE \ @@ -405,35 +405,35 @@ curl -sS -X DELETE \ ملاحظات: -- أنشئ القاعدة باستخدام access token الخاص بالمستخدم المتلقي، وليس token الروبوت. -- تُدرج قواعد `override` الجديدة المعرّفة من المستخدم قبل قواعد الكبت الافتراضية، لذلك لا حاجة إلى معامل ترتيب إضافي. -- يؤثر هذا فقط في تعديلات معاينة النص النهائي التي يمكن لـ OpenClaw إنهاؤها بأمان في مكانها. أما بدائل الوسائط وبدائل المعاينات القديمة فما زالت تستخدم تسليم Matrix العادي. -- إذا أظهر `GET /_matrix/client/v3/pushers` عدم وجود pushers، فهذا يعني أن المستخدم لا يملك بعد تسليم push من Matrix يعمل لهذا الحساب/الجهاز. +- أنشئ القاعدة باستخدام رمز وصول المستخدم المستلم، وليس رمز الروبوت. +- تُدرج قواعد `override` الجديدة المعرفة من قبل المستخدم قبل قواعد الكتم الافتراضية، لذلك لا حاجة إلى معلمة ترتيب إضافية. +- يؤثر هذا فقط في تعديلات المعاينة النصية فقط التي يستطيع OpenClaw إنهاءها بأمان في مكانها. ما تزال بدائل الوسائط وبدائل المعاينة القديمة تستخدم تسليم Matrix العادي. +- إذا أظهر `GET /_matrix/client/v3/pushers` عدم وجود pushers، فهذا يعني أن المستخدم لا يملك بعد تسليم دفع Matrix عاملًا لهذا الحساب/الجهاز. #### Synapse -بالنسبة إلى Synapse، يكون الإعداد أعلاه كافيًا عادةً بمفرده: +بالنسبة إلى Synapse، يكون الإعداد أعلاه كافيًا عادةً بحد ذاته: -- لا يلزم أي تغيير خاص في `homeserver.yaml` لإشعارات معاينات OpenClaw النهائية. -- إذا كان نشر Synapse لديك يرسل بالفعل إشعارات Matrix العادية، فإن token المستخدم + استدعاء `pushrules` أعلاه هما خطوة الإعداد الأساسية. -- إذا كنت تشغّل Synapse خلف reverse proxy أو workers، فتأكد من أن `/_matrix/client/.../pushrules/` يصل إلى Synapse بشكل صحيح. -- إذا كنت تشغّل Synapse workers، فتأكد من أن pushers سليمة. تتم معالجة تسليم push بواسطة العملية الرئيسية أو `synapse.app.pusher` / عمال pusher المهيئين. +- لا يلزم إجراء تغيير خاص في `homeserver.yaml` لإشعارات معاينة OpenClaw النهائية. +- إذا كانت عملية نشر Synapse لديك ترسل بالفعل إشعارات دفع Matrix العادية، فإن رمز المستخدم + استدعاء `pushrules` أعلاه هما خطوة الإعداد الأساسية. +- إذا كنت تشغّل Synapse خلف وكيل عكسي أو workers، فتأكد من أن `/_matrix/client/.../pushrules/` يصل إلى Synapse بشكل صحيح. +- إذا كنت تشغّل Synapse workers، فتأكد من سلامة pushers. تتم معالجة تسليم الدفع بواسطة العملية الرئيسية أو `synapse.app.pusher` / عمال pusher المهيئين. #### Tuwunel -بالنسبة إلى Tuwunel، استخدم مسار الإعداد نفسه واستدعاء API الخاص بـ push-rule المبيّن أعلاه: +بالنسبة إلى Tuwunel، استخدم نفس تدفق الإعداد واستدعاء Push-rule API الموضح أعلاه: -- لا يلزم أي إعداد خاص بـ Tuwunel لعلامة المعاينة النهائية نفسها. -- إذا كانت إشعارات Matrix العادية تعمل بالفعل لهذا المستخدم، فإن token المستخدم + استدعاء `pushrules` أعلاه هما خطوة الإعداد الأساسية. -- إذا بدت الإشعارات وكأنها تختفي بينما يكون المستخدم نشطًا على جهاز آخر، فتحقق مما إذا كان `suppress_push_when_active` مفعّلًا. أضاف Tuwunel هذا الخيار في Tuwunel 1.4.2 بتاريخ 12 سبتمبر 2025، ويمكنه عمدًا كبت إشعارات push إلى الأجهزة الأخرى أثناء نشاط أحد الأجهزة. +- لا يلزم تكوين خاص بـ Tuwunel لعلامة المعاينة النهائية نفسها. +- إذا كانت إشعارات Matrix العادية تعمل بالفعل لذلك المستخدم، فإن رمز المستخدم + استدعاء `pushrules` أعلاه هما خطوة الإعداد الأساسية. +- إذا بدا أن الإشعارات تختفي بينما يكون المستخدم نشطًا على جهاز آخر، فتحقق مما إذا كان `suppress_push_when_active` ممكّنًا. أضاف Tuwunel هذا الخيار في Tuwunel 1.4.2 بتاريخ 12 سبتمبر 2025، ويمكنه عمدًا كتم الإشعارات إلى الأجهزة الأخرى بينما يكون أحد الأجهزة نشطًا. ## التشفير والتحقق -في الغرف المشفرة (E2EE)، تستخدم أحداث الصور الصادرة `thumbnail_file` بحيث تُشفّر معاينات الصور إلى جانب المرفق الكامل. أما الغرف غير المشفرة فما تزال تستخدم `thumbnail_url` العادي. لا حاجة إلى أي تهيئة — إذ تكتشف plugin حالة E2EE تلقائيًا. +في الغرف المشفرة (E2EE)، تستخدم أحداث الصور الصادرة `thumbnail_file` بحيث تُشفَّر معاينات الصور إلى جانب المرفق الكامل. ولا تزال الغرف غير المشفرة تستخدم `thumbnail_url` العادي. لا حاجة إلى أي تكوين — تكتشف الإضافة حالة E2EE تلقائيًا. -### غرف الروبوت إلى الروبوت +### غرف روبوت إلى روبوت -افتراضيًا، يتم تجاهل رسائل Matrix الواردة من حسابات OpenClaw Matrix الأخرى المهيأة. +بشكل افتراضي، يتم تجاهل رسائل Matrix الواردة من حسابات OpenClaw Matrix الأخرى المكوّنة. استخدم `allowBots` عندما تريد عمدًا حركة مرور Matrix بين الوكلاء: @@ -452,13 +452,13 @@ curl -sS -X DELETE \ } ``` -- `allowBots: true` يقبل الرسائل من حسابات Matrix bot الأخرى المهيأة في الغرف والرسائل الخاصة المسموح بها. -- `allowBots: "mentions"` يقبل تلك الرسائل فقط عندما تذكر هذا الروبوت صراحةً في الغرف. تظل الرسائل الخاصة مسموحًا بها. +- يقبل `allowBots: true` الرسائل من حسابات روبوت Matrix الأخرى المكوّنة في الغرف والرسائل المباشرة المسموح بها. +- يقبل `allowBots: "mentions"` هذه الرسائل فقط عندما تذكر هذا الروبوت بوضوح في الغرف. ولا تزال الرسائل المباشرة مسموحًا بها. - يتجاوز `groups..allowBots` الإعداد على مستوى الحساب لغرفة واحدة. -- ما يزال OpenClaw يتجاهل الرسائل من معرّف مستخدم Matrix نفسه لتجنب حلقات الرد الذاتي. -- لا تكشف Matrix هنا عن علامة روبوت أصلية؛ ويتعامل OpenClaw مع "صادر عن روبوت" على أنه "أُرسل من حساب Matrix مهيأ آخر على بوابة OpenClaw هذه". +- لا يزال OpenClaw يتجاهل الرسائل من نفس معرّف مستخدم Matrix لتجنب حلقات الرد الذاتي. +- لا يوفّر Matrix هنا علامة روبوت أصلية؛ يتعامل OpenClaw مع "المرسل من روبوت" على أنه "مرسل بواسطة حساب Matrix مكوَّن آخر على بوابة OpenClaw هذه". -استخدم allowlistات غرف صارمة ومتطلبات الذكر عند تمكين حركة المرور بين الروبوتات في الغرف المشتركة. +استخدم قوائم سماح صارمة للغرف ومتطلبات الذكر عند تمكين حركة المرور من روبوت إلى روبوت في الغرف المشتركة. تمكين التشفير: @@ -476,7 +476,7 @@ curl -sS -X DELETE \ } ``` -التحقق من حالة التحقق: +تحقق من حالة التحقق: ```bash openclaw matrix verify status @@ -488,19 +488,19 @@ openclaw matrix verify status openclaw matrix verify status --verbose ``` -تضمين مفتاح الاسترداد المخزّن في مخرجات قابلة للقراءة آليًا: +تضمين مفتاح الاسترداد المخزن في المخرجات القابلة للقراءة آليًا: ```bash openclaw matrix verify status --include-recovery-key --json ``` -تهيئة حالة cross-signing والتحقق: +تهيئة cross-signing وحالة التحقق: ```bash openclaw matrix verify bootstrap ``` -دعم الحسابات المتعددة: استخدم `channels.matrix.accounts` مع بيانات اعتماد لكل حساب و`name` اختياري. راجع [مرجع التهيئة](/ar/gateway/configuration-reference#multi-account-all-channels) للنمط المشترك. +دعم الحسابات المتعددة: استخدم `channels.matrix.accounts` مع بيانات اعتماد لكل حساب و`name` اختياري. راجع [مرجع التكوين](/ar/gateway/configuration-reference#multi-account-all-channels) للاطلاع على النمط المشترك. تشخيصات bootstrap مفصلة: @@ -508,7 +508,7 @@ openclaw matrix verify bootstrap openclaw matrix verify bootstrap --verbose ``` -فرض إعادة تعيين هوية cross-signing جديدة قبل bootstrap: +فرض إعادة تعيين جديدة لهوية cross-signing قبل التهيئة: ```bash openclaw matrix verify bootstrap --force-reset-cross-signing @@ -520,50 +520,50 @@ openclaw matrix verify bootstrap --force-reset-cross-signing openclaw matrix verify device "" ``` -تفاصيل مفصلة للتحقق من الجهاز: +تفاصيل التحقق من الجهاز بشكل مفصل: ```bash openclaw matrix verify device "" --verbose ``` -التحقق من سلامة النسخ الاحتياطي لمفاتيح الغرفة: +تحقق من سلامة النسخ الاحتياطي لمفاتيح الغرف: ```bash openclaw matrix verify backup status ``` -تشخيصات مفصلة لسلامة النسخ الاحتياطي: +تشخيصات سلامة النسخ الاحتياطي بشكل مفصل: ```bash openclaw matrix verify backup status --verbose ``` -استعادة مفاتيح الغرفة من النسخة الاحتياطية على الخادم: +استعادة مفاتيح الغرف من النسخة الاحتياطية على الخادم: ```bash openclaw matrix verify backup restore ``` -تشخيصات مفصلة للاستعادة: +تشخيصات الاستعادة بشكل مفصل: ```bash openclaw matrix verify backup restore --verbose ``` احذف النسخة الاحتياطية الحالية على الخادم وأنشئ خط أساس جديدًا للنسخ الاحتياطي. إذا تعذر تحميل -مفتاح النسخ الاحتياطي المخزّن بشكل سليم، فقد تؤدي إعادة التعيين هذه أيضًا إلى إعادة إنشاء التخزين السري بحيث -تتمكن عمليات التشغيل البارد المستقبلية من تحميل مفتاح النسخ الاحتياطي الجديد: +مفتاح النسخة الاحتياطية المخزّن بشكل نظيف، فإن إعادة التعيين هذه يمكنها أيضًا إعادة إنشاء التخزين السري بحيث +تتمكن عمليات البدء البارد المستقبلية من تحميل مفتاح النسخة الاحتياطية الجديد: ```bash openclaw matrix verify backup reset --yes ``` تكون جميع أوامر `verify` موجزة افتراضيًا (بما في ذلك تسجيل SDK الداخلي الهادئ) وتعرض تشخيصات مفصلة فقط مع `--verbose`. -استخدم `--json` للحصول على مخرجات كاملة قابلة للقراءة آليًا عند كتابة السكربتات. +استخدم `--json` للحصول على مخرجات كاملة قابلة للقراءة آليًا عند كتابة البرامج النصية. -في إعدادات الحسابات المتعددة، تستخدم أوامر Matrix CLI الحساب الافتراضي الضمني لـ Matrix ما لم تمرر `--account `. -إذا هيأت عدة حسابات مسماة، فقم أولًا بتعيين `channels.matrix.defaultAccount` وإلا ستتوقف عمليات CLI الضمنية تلك وتطلب منك اختيار حساب صراحةً. -استخدم `--account` كلما أردت أن تستهدف عمليات التحقق أو عمليات الجهاز حسابًا مسمىً صراحةً: +في إعدادات الحسابات المتعددة، تستخدم أوامر Matrix CLI حساب Matrix الافتراضي الضمني ما لم تمرر `--account `. +إذا قمت بتكوين عدة حسابات مسماة، فاضبط `channels.matrix.defaultAccount` أولًا وإلا فستتوقف عمليات CLI الضمنية هذه وتطلب منك اختيار حساب بشكل صريح. +استخدم `--account` كلما أردت أن تستهدف عمليات التحقق أو الجهاز حسابًا مسمّى بشكل صريح: ```bash openclaw matrix verify status --account assistant @@ -571,43 +571,43 @@ openclaw matrix verify backup restore --account assistant openclaw matrix devices list --account assistant ``` -عندما يكون التشفير معطلًا أو غير متاح لحساب مسمى، تشير تحذيرات Matrix وأخطاء التحقق إلى مفتاح تهيئة ذلك الحساب، مثل `channels.matrix.accounts.assistant.encryption`. +عندما يكون التشفير معطّلًا أو غير متاح لحساب مسمّى، تشير تحذيرات Matrix وأخطاء التحقق إلى مفتاح تكوين ذلك الحساب، مثل `channels.matrix.accounts.assistant.encryption`. ### ما معنى "تم التحقق" -يعامل OpenClaw جهاز Matrix هذا على أنه تم التحقق منه فقط عندما يتم التحقق منه بواسطة هوية cross-signing الخاصة بك. -عمليًا، يكشف `openclaw matrix verify status --verbose` ثلاث إشارات ثقة: +يعتبر OpenClaw جهاز Matrix هذا متحققًا منه فقط عندما يتم التحقق منه بواسطة هوية cross-signing الخاصة بك. +عمليًا، يكشف `openclaw matrix verify status --verbose` عن ثلاث إشارات ثقة: -- `Locally trusted`: هذا الجهاز موثوق من قبل العميل الحالي فقط -- `Cross-signing verified`: تُبلغ SDK أن الجهاز تم التحقق منه عبر cross-signing -- `Signed by owner`: الجهاز موقّع بواسطة مفتاح self-signing الخاص بك +- `Locally trusted`: هذا الجهاز موثوق به من قبل العميل الحالي فقط +- `Cross-signing verified`: يفيد SDK بأن الجهاز تم التحقق منه عبر cross-signing +- `Signed by owner`: هذا الجهاز موقّع بواسطة مفتاح self-signing الخاص بك -تصبح `Verified by owner` مساوية لـ `yes` فقط عند وجود تحقق عبر cross-signing أو توقيع المالك. -الثقة المحلية وحدها لا تكفي لكي يعامل OpenClaw الجهاز على أنه موثوق بالكامل. +تصبح `Verified by owner` مساوية لـ `yes` فقط عند وجود تحقق cross-signing أو توقيع المالك. +الثقة المحلية وحدها ليست كافية لكي يعامل OpenClaw الجهاز على أنه متحقق بالكامل. -### ما الذي يفعله bootstrap +### ماذا يفعل bootstrap الأمر `openclaw matrix verify bootstrap` هو أمر الإصلاح والإعداد لحسابات Matrix المشفرة. -وهو ينفذ جميع ما يلي بالترتيب: +ويقوم بكل ما يلي بالترتيب: -- يهيئ التخزين السري، مع إعادة استخدام مفتاح استرداد موجود إن أمكن +- يهيئ التخزين السري، مع إعادة استخدام مفتاح استرداد موجود عندما يكون ذلك ممكنًا - يهيئ cross-signing ويرفع مفاتيح cross-signing العامة المفقودة -- يحاول تعليم الجهاز الحالي والتوقيع عليه عبر cross-signing -- ينشئ نسخة احتياطية جديدة لمفاتيح الغرف على الخادم إذا لم تكن موجودة بالفعل +- يحاول تعليم الجهاز الحالي وتوقيعه عبر cross-signing +- ينشئ نسخة احتياطية جديدة على جانب الخادم لمفاتيح الغرف إذا لم تكن موجودة بالفعل -إذا كان homeserver يتطلب مصادقة تفاعلية لرفع مفاتيح cross-signing، يحاول OpenClaw الرفع أولًا بدون مصادقة، ثم باستخدام `m.login.dummy`، ثم باستخدام `m.login.password` عندما يكون `channels.matrix.password` مهيأً. +إذا كان الخادم المنزلي يتطلب مصادقة تفاعلية لرفع مفاتيح cross-signing، فسيحاول OpenClaw الرفع أولًا دون مصادقة، ثم باستخدام `m.login.dummy`، ثم باستخدام `m.login.password` عندما يكون `channels.matrix.password` مُكوَّنًا. -استخدم `--force-reset-cross-signing` فقط عندما تريد عمدًا تجاهل هوية cross-signing الحالية وإنشاء واحدة جديدة. +استخدم `--force-reset-cross-signing` فقط عندما تريد عمدًا تجاهل هوية cross-signing الحالية وإنشاء هوية جديدة. إذا كنت تريد عمدًا تجاهل النسخة الاحتياطية الحالية لمفاتيح الغرف والبدء بخط أساس جديد للنسخ الاحتياطي للرسائل المستقبلية، فاستخدم `openclaw matrix verify backup reset --yes`. -افعل ذلك فقط عندما تقبل بأن السجل المشفر القديم غير القابل للاسترداد سيبقى -غير متاح، وأن OpenClaw قد يعيد إنشاء التخزين السري إذا تعذر تحميل سر النسخ الاحتياطي -الحالي بأمان. +افعل هذا فقط عندما تقبل أن يظل السجل القديم المشفر غير القابل للاسترداد +غير متاح وأن OpenClaw قد يعيد إنشاء التخزين السري إذا تعذر تحميل +سر النسخة الاحتياطية الحالي بأمان. ### خط أساس جديد للنسخ الاحتياطي -إذا كنت تريد الإبقاء على عمل الرسائل المشفرة المستقبلية وتقبل فقدان السجل القديم غير القابل للاسترداد، فشغّل هذه الأوامر بالترتيب: +إذا كنت تريد الإبقاء على الرسائل المشفرة المستقبلية تعمل وتقبل فقدان السجل القديم غير القابل للاسترداد، فشغّل هذه الأوامر بالترتيب: ```bash openclaw matrix verify backup reset --yes @@ -615,96 +615,96 @@ openclaw matrix verify backup status --verbose openclaw matrix verify status ``` -أضف `--account ` إلى كل أمر عندما تريد استهداف حساب Matrix مسمىً صراحةً. +أضف `--account ` إلى كل أمر عندما تريد استهداف حساب Matrix مسمى بشكل صريح. ### سلوك بدء التشغيل -عندما تكون `encryption: true`، تضبط Matrix قيمة `startupVerification` افتراضيًا على `"if-unverified"`. -عند بدء التشغيل، إذا كان هذا الجهاز لا يزال غير متحقق منه، فستطلب Matrix التحقق الذاتي في عميل Matrix آخر، -وستتخطى الطلبات المكررة ما دام هناك طلب معلّق بالفعل، وتطبّق فترة تهدئة محلية قبل إعادة المحاولة بعد إعادة التشغيل. -تُعاد محاولة الطلبات الفاشلة بشكل أسرع افتراضيًا من إنشاء الطلبات الناجحة. +عندما يكون `encryption: true`، يضبط Matrix القيمة الافتراضية لـ `startupVerification` على `"if-unverified"`. +عند بدء التشغيل، إذا كان هذا الجهاز لا يزال غير متحقق منه، فسيطلب Matrix التحقق الذاتي في عميل Matrix آخر، +ويتخطى الطلبات المكررة طالما أن أحدها قيد الانتظار بالفعل، ويطبق فترة تهدئة محلية قبل إعادة المحاولة بعد عمليات إعادة التشغيل. +تحاول الطلبات الفاشلة مرة أخرى في وقت أقرب من إنشاء الطلبات الناجح افتراضيًا. عيّن `startupVerification: "off"` لتعطيل طلبات بدء التشغيل التلقائية، أو اضبط `startupVerificationCooldownHours` -إذا كنت تريد نافذة إعادة محاولة أقصر أو أطول. +إذا أردت نافذة إعادة محاولة أقصر أو أطول. -ينفذ بدء التشغيل أيضًا مرور bootstrap محافظًا للتشفير تلقائيًا. -يحاول هذا المرور أولًا إعادة استخدام التخزين السري الحالي وهوية cross-signing الحالية، ويتجنب إعادة تعيين cross-signing ما لم تشغّل مسار إصلاح bootstrap صريحًا. +ينفذ بدء التشغيل أيضًا بشكل تلقائي تمريرة bootstrap محافظة للتشفير. +تحاول هذه التمريرة أولًا إعادة استخدام التخزين السري الحالي وهوية cross-signing الحالية، وتتجنب إعادة تعيين cross-signing ما لم تُشغِّل تدفق إصلاح bootstrap صريحًا. -إذا اكتشف بدء التشغيل حالة bootstrap معطلة وكان `channels.matrix.password` مهيأً، فيمكن لـ OpenClaw محاولة مسار إصلاح أكثر صرامة. -إذا كان الجهاز الحالي موقّعًا بالفعل من المالك، فيحافظ OpenClaw على تلك الهوية بدلًا من إعادة تعيينها تلقائيًا. +إذا وجد بدء التشغيل حالة bootstrap تالفة وكان `channels.matrix.password` مُكوَّنًا، فيمكن لـ OpenClaw محاولة مسار إصلاح أكثر صرامة. +إذا كان الجهاز الحالي موقّعًا بالفعل من قبل المالك، فسيحافظ OpenClaw على تلك الهوية بدلًا من إعادة تعيينها تلقائيًا. -الترقية من plugin Matrix العامة السابقة: +الترقية من إضافة Matrix العامة السابقة: -- يعيد OpenClaw تلقائيًا استخدام حساب Matrix نفسه وaccess token وهوية الجهاز نفسها متى أمكن. +- يعيد OpenClaw تلقائيًا استخدام نفس حساب Matrix، ورمز الوصول، وهوية الجهاز متى أمكن. - قبل تشغيل أي تغييرات ترحيل Matrix قابلة للتنفيذ، ينشئ OpenClaw أو يعيد استخدام لقطة استرداد ضمن `~/Backups/openclaw-migrations/`. -- إذا كنت تستخدم عدة حسابات Matrix، فقم بتعيين `channels.matrix.defaultAccount` قبل الترقية من تخطيط التخزين القديم المسطح حتى يعرف OpenClaw أي حساب يجب أن يستقبل هذه الحالة القديمة المشتركة. -- إذا كانت plugin السابقة تخزن مفتاح فك تشفير نسخة Matrix الاحتياطية لمفاتيح الغرف محليًا، فسيقوم بدء التشغيل أو `openclaw doctor --fix` باستيراده إلى تدفق مفتاح الاسترداد الجديد تلقائيًا. -- إذا تغيّر access token الخاص بـ Matrix بعد إعداد الترحيل، فإن بدء التشغيل يفحص الآن جذور تخزين sibling token-hash بحثًا عن حالة استعادة قديمة معلّقة قبل التخلي عن الاستعادة التلقائية للنسخ الاحتياطي. -- إذا تغيّر access token الخاص بـ Matrix لاحقًا لنفس الحساب وhomeserver والمستخدم، فإن OpenClaw يفضّل الآن إعادة استخدام جذر token-hash الموجود الأكثر اكتمالًا بدلًا من البدء من دليل حالة Matrix فارغ. +- إذا كنت تستخدم عدة حسابات Matrix، فاضبط `channels.matrix.defaultAccount` قبل الترقية من تخطيط التخزين المسطح القديم حتى يعرف OpenClaw أي حساب يجب أن يتلقى تلك الحالة القديمة المشتركة. +- إذا كانت الإضافة السابقة تخزّن مفتاح فك تشفير نسخة احتياطية لمفاتيح غرف Matrix محليًا، فسيقوم بدء التشغيل أو `openclaw doctor --fix` باستيراده تلقائيًا إلى تدفق مفتاح الاسترداد الجديد. +- إذا تغيّر رمز وصول Matrix بعد تحضير الترحيل، فإن بدء التشغيل يفحص الآن جذور تخزين تجزئة الرمز الشقيقة بحثًا عن حالة استعادة قديمة معلّقة قبل التخلي عن الاستعادة التلقائية للنسخ الاحتياطي. +- إذا تغيّر رمز وصول Matrix لاحقًا لنفس الحساب والخادم المنزلي والمستخدم، فإن OpenClaw يفضّل الآن إعادة استخدام جذر تخزين تجزئة الرمز الأكثر اكتمالًا بدلًا من البدء من دليل حالة Matrix فارغ. - عند بدء تشغيل البوابة التالي، تُستعاد مفاتيح الغرف المنسوخة احتياطيًا تلقائيًا إلى مخزن التشفير الجديد. -- إذا كانت plugin القديمة تحتوي على مفاتيح غرف محلية فقط لم تُنسخ احتياطيًا مطلقًا، فسيحذر OpenClaw بوضوح. لا يمكن تصدير تلك المفاتيح تلقائيًا من مخزن rust crypto السابق، لذلك قد يظل بعض السجل المشفر القديم غير متاح حتى يُستعاد يدويًا. -- راجع [ترحيل Matrix](/ar/install/migrating-matrix) لمعرفة تدفق الترقية الكامل والقيود وأوامر الاسترداد ورسائل الترحيل الشائعة. +- إذا كانت الإضافة القديمة تحتوي على مفاتيح غرف محلية فقط لم تُنسخ احتياطيًا مطلقًا، فسيحذر OpenClaw بوضوح. لا يمكن تصدير هذه المفاتيح تلقائيًا من مخزن التشفير rust السابق، لذا قد يظل بعض السجل القديم المشفر غير متاح حتى تتم استعادته يدويًا. +- راجع [ترحيل Matrix](/ar/install/migrating-matrix) للاطلاع على تدفق الترقية الكامل، والقيود، وأوامر الاسترداد، ورسائل الترحيل الشائعة. -تُنظَّم حالة التشغيل المشفرة ضمن جذور token-hash لكل حساب ولكل مستخدم في +تُنظَّم حالة وقت التشغيل المشفرة ضمن جذور تجزئة رموز لكل حساب ولكل مستخدم في `~/.openclaw/matrix/accounts//__//`. -يحتوي هذا الدليل على مخزن المزامنة (`bot-storage.json`) ومخزن التشفير (`crypto/`) وملف -مفتاح الاسترداد (`recovery-key.json`) ولقطة IndexedDB (`crypto-idb-snapshot.json`) وروابط -سلاسل الرسائل (`thread-bindings.json`) وحالة التحقق عند بدء التشغيل (`startup-verification.json`) +يحتوي هذا الدليل على مخزن المزامنة (`bot-storage.json`)، ومخزن التشفير (`crypto/`)، +وملف مفتاح الاسترداد (`recovery-key.json`)، ولقطة IndexedDB (`crypto-idb-snapshot.json`)، +وروابط الخيوط (`thread-bindings.json`)، وحالة التحقق عند بدء التشغيل (`startup-verification.json`) عندما تكون هذه الميزات قيد الاستخدام. -عندما يتغير token لكن تبقى هوية الحساب نفسها، يعيد OpenClaw استخدام أفضل -جذر موجود لذلك الثلاثي account/homeserver/user بحيث تبقى حالة المزامنة السابقة وحالة التشفير وروابط سلاسل الرسائل +عندما يتغير الرمز لكن تبقى هوية الحساب نفسها، يعيد OpenClaw استخدام أفضل +جذر موجود لذلك الثلاثي الحساب/الخادم المنزلي/المستخدم بحيث تظل حالة المزامنة السابقة، وحالة التشفير، وروابط الخيوط، وحالة التحقق عند بدء التشغيل مرئية. -### نموذج مخزن Node crypto +### نموذج مخزن تشفير Node -يستخدم E2EE في Matrix ضمن هذه plugin مسار Rust crypto الرسمي من `matrix-js-sdk` في Node. -ويتوقع هذا المسار وجود تخزين دائم قائم على IndexedDB إذا كنت تريد بقاء حالة التشفير بعد إعادة التشغيل. +تستخدم E2EE الخاصة بـ Matrix في هذه الإضافة مسار تشفير Rust الرسمي من `matrix-js-sdk` في Node. +ويتوقع هذا المسار وجود استمرارية مدعومة بـ IndexedDB عندما تريد لحالة التشفير أن تبقى بعد إعادة التشغيل. -يوفر OpenClaw ذلك حاليًا في Node من خلال: +يوفّر OpenClaw ذلك حاليًا في Node من خلال: -- استخدام `fake-indexeddb` بوصفه واجهة IndexedDB shim التي تتوقعها SDK +- استخدام `fake-indexeddb` كطبقة API لـ IndexedDB المتوقعة من قبل SDK - استعادة محتويات Rust crypto IndexedDB من `crypto-idb-snapshot.json` قبل `initRustCrypto` -- حفظ محتويات IndexedDB المحدثة مرة أخرى إلى `crypto-idb-snapshot.json` بعد التهيئة وأثناء التشغيل -- تسلسل استعادة اللقطة وحفظها مقابل `crypto-idb-snapshot.json` باستخدام قفل ملف استشاري حتى لا تتسابق استمرارية تشغيل البوابة وصيانة CLI على ملف اللقطة نفسه +- حفظ محتويات IndexedDB المحدّثة مرة أخرى إلى `crypto-idb-snapshot.json` بعد التهيئة وأثناء وقت التشغيل +- تسلسل استعادة اللقطة والحفظ مقابل `crypto-idb-snapshot.json` باستخدام قفل ملف استشاري بحيث لا يتسابق حفظ وقت تشغيل البوابة وصيانة CLI على ملف اللقطة نفسه -هذا مجرد توافق/بنية تخزين، وليس تنفيذًا مخصصًا للتشفير. -ملف اللقطة حالة تشغيل حساسة ويُخزن بأذونات ملفات مقيدة. -وبموجب نموذج الأمان في OpenClaw، يكون مضيف البوابة ودليل الحالة المحلي لـ OpenClaw داخل حدود المشغّل الموثوقة بالفعل، لذلك فهذه مسألة متانة تشغيلية بالدرجة الأولى وليست حد ثقة بعيد منفصل. +هذا تكييف للتوافق/التخزين، وليس تنفيذ تشفير مخصصًا. +ملف اللقطة هو حالة وقت تشغيل حساسة ويتم تخزينه بأذونات ملفات مقيدة. +في نموذج أمان OpenClaw، يكون مضيف البوابة ودليل حالة OpenClaw المحلي داخل حدود المشغّل الموثوق بها بالفعل، لذا فهذه في المقام الأول مسألة متانة تشغيلية وليست حد ثقة بعيد منفصل. تحسين مخطط له: -- إضافة دعم SecretRef لمواد مفاتيح Matrix الدائمة بحيث يمكن جلب مفاتيح الاسترداد وأسرار تشفير المخزن المرتبطة بها من مزودي الأسرار في OpenClaw بدلًا من الملفات المحلية فقط +- إضافة دعم SecretRef لمواد مفاتيح Matrix المستمرة بحيث يمكن توفير مفاتيح الاسترداد وأسرار تشفير المخزن ذات الصلة من مزودي أسرار OpenClaw بدلًا من الملفات المحلية فقط ## إدارة الملف الشخصي -حدّث الملف الشخصي الذاتي لـ Matrix للحساب المحدد باستخدام: +حدّث الملف الشخصي الذاتي في Matrix للحساب المحدد باستخدام: ```bash openclaw matrix profile set --name "OpenClaw Assistant" openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png ``` -أضف `--account ` عندما تريد استهداف حساب Matrix مسمىً صراحةً. +أضف `--account ` عندما تريد استهداف حساب Matrix مسمى بشكل صريح. -تقبل Matrix عناوين URL للصورة الرمزية من نوع `mxc://` مباشرةً. وعندما تمرر عنوان URL للصورة الرمزية من نوع `http://` أو `https://`، يقوم OpenClaw أولًا برفعه إلى Matrix ثم يخزن عنوان `mxc://` الناتج مرة أخرى في `channels.matrix.avatarUrl` (أو في تجاوز الحساب المحدد). +يقبل Matrix عناوين URL للصورة الرمزية `mxc://` مباشرة. عندما تمرر عنوان URL للصورة الرمزية من نوع `http://` أو `https://`، يرفعها OpenClaw إلى Matrix أولًا ثم يخزن عنوان `mxc://` المحلول مرة أخرى في `channels.matrix.avatarUrl` (أو التجاوز المحدد للحساب). ## إشعارات التحقق التلقائية -تنشر Matrix الآن إشعارات دورة حياة التحقق مباشرة داخل غرفة الرسائل الخاصة الصارمة الخاصة بالتحقق بوصفها رسائل `m.notice`. +ينشر Matrix الآن إشعارات دورة حياة التحقق مباشرة داخل غرفة التحقق الصارمة للرسائل المباشرة كرسائل `m.notice`. ويشمل ذلك: - إشعارات طلب التحقق -- إشعارات جاهزية التحقق (مع إرشادات صريحة "التحقق عبر الرموز التعبيرية") +- إشعارات جاهزية التحقق (مع إرشاد صريح "تحقق بواسطة emoji") - إشعارات بدء التحقق واكتماله -- تفاصيل SAS (الرموز التعبيرية والأرقام) عند توفرها +- تفاصيل SAS (emoji والأرقام العشرية) عندما تكون متاحة -تُتتبَّع طلبات التحقق الواردة من عميل Matrix آخر وتُقبل تلقائيًا بواسطة OpenClaw. -وبالنسبة إلى تدفقات التحقق الذاتي، يبدأ OpenClaw أيضًا تدفق SAS تلقائيًا عندما يصبح التحقق بالرموز التعبيرية متاحًا ويؤكد جانبه الخاص. -أما بالنسبة إلى طلبات التحقق من مستخدم/جهاز Matrix آخر، فيقبل OpenClaw الطلب تلقائيًا ثم ينتظر متابعة تدفق SAS بشكل طبيعي. -ما يزال عليك مقارنة SAS بالرموز التعبيرية أو الأرقام في عميل Matrix لديك وتأكيد "They match" هناك لإكمال التحقق. +تتم متابعة طلبات التحقق الواردة من عميل Matrix آخر وقبولها تلقائيًا بواسطة OpenClaw. +وبالنسبة إلى تدفقات التحقق الذاتي، يبدأ OpenClaw أيضًا تدفق SAS تلقائيًا عندما يصبح التحقق بواسطة emoji متاحًا ويؤكد جانبه الخاص. +أما بالنسبة إلى طلبات التحقق من مستخدم/جهاز Matrix آخر، فيقبل OpenClaw الطلب تلقائيًا ثم ينتظر استمرار تدفق SAS بشكل طبيعي. +لا يزال يتعين عليك مقارنة emoji أو SAS العشري في عميل Matrix لديك وتأكيد "إنها متطابقة" هناك لإكمال التحقق. -لا يقبل OpenClaw تلقائيًا التدفقات المكررة التي بدأها ذاتيًا بشكل أعمى. يتخطى بدء التشغيل إنشاء طلب جديد عندما يكون طلب التحقق الذاتي معلّقًا بالفعل. +لا يقبل OpenClaw تلقائيًا التدفقات الذاتية المكررة التي تم بدؤها ذاتيًا بشكل أعمى. يتخطى بدء التشغيل إنشاء طلب جديد عندما يكون طلب التحقق الذاتي معلقًا بالفعل. -لا تُمرَّر إشعارات البروتوكول/النظام الخاصة بالتحقق إلى مسار دردشة الوكيل، لذلك لا تنتج `NO_REPLY`. +لا تُمرَّر إشعارات بروتوكول/نظام التحقق إلى مسار دردشة الوكيل، لذلك لا تنتج `NO_REPLY`. ### نظافة الأجهزة @@ -715,7 +715,7 @@ openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png openclaw matrix devices list ``` -أزل أجهزة OpenClaw-managed القديمة باستخدام: +أزل أجهزة OpenClaw Matrix القديمة غير المستخدمة باستخدام: ```bash openclaw matrix devices prune-stale @@ -723,65 +723,65 @@ openclaw matrix devices prune-stale ### إصلاح الغرفة المباشرة -إذا خرجت حالة الرسائل الخاصة عن المزامنة، فقد ينتهي الأمر بـ OpenClaw إلى الحصول على تعيينات `m.direct` قديمة تشير إلى غرف منفردة قديمة بدلًا من الرسالة الخاصة الحية. افحص التعيين الحالي لنظير باستخدام: +إذا أصبحت حالة الرسائل المباشرة غير متزامنة، فقد ينتهي الأمر بـ OpenClaw إلى امتلاك تعيينات `m.direct` قديمة تشير إلى غرف فردية قديمة بدلًا من الرسالة المباشرة النشطة. افحص التعيين الحالي لنظير باستخدام: ```bash openclaw matrix direct inspect --user-id @alice:example.org ``` -وأصلحه باستخدام: +أصلحه باستخدام: ```bash openclaw matrix direct repair --user-id @alice:example.org ``` -يبقي الإصلاح منطق Matrix الخاص داخل plugin: +يبقي الإصلاح المنطق الخاص بـ Matrix داخل الإضافة: -- يفضّل رسالة خاصة صارمة 1:1 تكون معيّنة بالفعل في `m.direct` -- وإلا فيعود إلى أي رسالة خاصة صارمة 1:1 منضم إليها حاليًا مع ذلك المستخدم -- وإذا لم توجد رسالة خاصة سليمة، ينشئ غرفة direct جديدة ويعيد كتابة `m.direct` للإشارة إليها +- يفضّل رسالة مباشرة صارمة 1:1 معيّنة بالفعل في `m.direct` +- وإلا فإنه يعود إلى أي رسالة مباشرة صارمة 1:1 منضم إليها حاليًا مع ذلك المستخدم +- إذا لم توجد رسالة مباشرة سليمة، فإنه ينشئ غرفة مباشرة جديدة ويعيد كتابة `m.direct` لتشير إليها -لا يحذف تدفق الإصلاح الغرف القديمة تلقائيًا. بل يختار فقط الرسالة الخاصة السليمة ويحدّث التعيين بحيث تستهدف عمليات إرسال Matrix الجديدة وإشعارات التحقق والتدفقات الأخرى للرسائل الخاصة الغرفة الصحيحة مرة أخرى. +لا يحذف تدفق الإصلاح الغرف القديمة تلقائيًا. فهو يختار فقط الرسالة المباشرة السليمة ويحدّث التعيين بحيث تستهدف عمليات الإرسال الجديدة في Matrix، وإشعارات التحقق، وتدفقات الرسائل المباشرة الأخرى الغرفة الصحيحة مرة أخرى. -## سلاسل الرسائل +## الخيوط -تدعم Matrix سلاسل Matrix الأصلية لكل من الردود التلقائية وعمليات الإرسال عبر أداة الرسائل. +يدعم Matrix خيوط Matrix الأصلية لكل من الردود التلقائية وعمليات الإرسال بأداة الرسائل. -- `dm.sessionScope: "per-user"` (الافتراضي) يبقي توجيه الرسائل الخاصة في Matrix ضمن نطاق المرسل، لذلك يمكن لعدة غرف رسائل خاصة مشاركة جلسة واحدة عندما تُحل إلى النظير نفسه. -- `dm.sessionScope: "per-room"` يعزل كل غرفة رسائل خاصة في Matrix ضمن مفتاح جلسة خاص بها مع الاستمرار في استخدام فحوصات المصادقة وallowlist العادية للرسائل الخاصة. -- لا تزال روابط محادثات Matrix الصريحة تتقدم على `dm.sessionScope`، لذلك تحتفظ الغرف وسلاسل الرسائل المرتبطة بجلساتها الهدف المحددة. -- `threadReplies: "off"` يبقي الردود على المستوى الأعلى ويبقي الرسائل الواردة ضمن سلاسل الرسائل على جلسة الأصل. -- `threadReplies: "inbound"` يرد داخل سلسلة رسائل فقط عندما تكون الرسالة الواردة أصلًا ضمن تلك السلسلة. -- `threadReplies: "always"` يبقي ردود الغرف ضمن سلسلة رسائل متجذرة عند الرسالة المحفزة ويوجه تلك المحادثة عبر الجلسة ذات النطاق الخاص بسلسلة الرسائل المطابقة ابتداءً من أول رسالة محفزة. -- `dm.threadReplies` يتجاوز الإعداد الأعلى مستوى للرسائل الخاصة فقط. على سبيل المثال، يمكنك إبقاء سلاسل رسائل الغرف معزولة مع إبقاء الرسائل الخاصة مسطحة. -- تتضمن الرسائل الواردة ضمن سلاسل الرسائل الرسالة الجذرية للسلسلة كسياق إضافي للوكيل. -- ترث عمليات الإرسال عبر أداة الرسائل الآن سلسلة Matrix الحالية تلقائيًا عندما يكون الهدف هو الغرفة نفسها، أو الهدف نفسه لمستخدم الرسائل الخاصة، ما لم يُوفَّر `threadId` صريح. -- لا يُفعَّل إعادة استخدام هدف مستخدم الرسائل الخاصة للجلسة نفسها إلا عندما تثبت بيانات تعريف الجلسة الحالية أنه نفس نظير الرسائل الخاصة على حساب Matrix نفسه؛ وإلا يعود OpenClaw إلى التوجيه العادي ضمن نطاق المستخدم. -- عندما يرى OpenClaw أن غرفة رسائل خاصة في Matrix تتصادم مع غرفة رسائل خاصة أخرى على جلسة Matrix DM مشتركة نفسها، فإنه ينشر `m.notice` لمرة واحدة في تلك الغرفة مع مخرج الهروب `/focus` عندما تكون روابط سلاسل الرسائل مفعّلة ومع تلميح `dm.sessionScope`. -- تُدعَم روابط سلاسل الرسائل أثناء التشغيل لـ Matrix. تعمل الآن `/focus` و`/unfocus` و`/agents` و`/session idle` و`/session max-age` و`/acp spawn` المرتبط بسلسلة الرسائل في غرف Matrix والرسائل الخاصة. -- يؤدي `/focus` على مستوى أعلى لغرفة/رسالة خاصة Matrix إلى إنشاء سلسلة Matrix جديدة وربطها بالجلسة الهدف عندما تكون `threadBindings.spawnSubagentSessions=true`. -- يؤدي تشغيل `/focus` أو `/acp spawn --thread here` داخل سلسلة Matrix موجودة إلى ربط هذه السلسلة الحالية بدلًا من ذلك. +- يحافظ `dm.sessionScope: "per-user"` (الافتراضي) على توجيه الرسائل المباشرة في Matrix في نطاق المرسل، بحيث يمكن لعدة غرف رسائل مباشرة مشاركة جلسة واحدة عندما تُحل إلى النظير نفسه. +- يعزل `dm.sessionScope: "per-room"` كل غرفة رسائل مباشرة في Matrix في مفتاح جلسة خاص بها مع الاستمرار في استخدام فحوصات المصادقة وقائمة السماح العادية الخاصة بالرسائل المباشرة. +- تظل روابط محادثات Matrix الصريحة لها الأولوية على `dm.sessionScope`، لذلك تحتفظ الغرف والخيوط المرتبطة بجلسة الهدف المختارة. +- يبقي `threadReplies: "off"` الردود على المستوى الأعلى ويبقي الرسائل الواردة داخل الخيوط على جلسة الأصل. +- يرد `threadReplies: "inbound"` داخل خيط فقط عندما تكون الرسالة الواردة موجودة بالفعل في ذلك الخيط. +- يحافظ `threadReplies: "always"` على ردود الغرف داخل خيط متجذر في الرسالة المُحفِّزة ويوجه تلك المحادثة عبر الجلسة المطابقة ذات النطاق الخاص بالخيط من أول رسالة محفِّزة. +- يتجاوز `dm.threadReplies` الإعداد الأعلى مستوى للرسائل المباشرة فقط. على سبيل المثال، يمكنك إبقاء خيوط الغرف معزولة مع إبقاء الرسائل المباشرة مسطحة. +- تتضمن الرسائل الواردة داخل الخيوط الرسالة الجذرية للخيط كسياق إضافي للوكيل. +- ترث عمليات الإرسال بأداة الرسائل الآن خيط Matrix الحالي تلقائيًا عندما يكون الهدف هو الغرفة نفسها أو هدف مستخدم الرسالة المباشرة نفسه، ما لم يتم توفير `threadId` صراحةً. +- لا يُفعَّل إعادة استخدام هدف مستخدم الرسالة المباشرة في الجلسة نفسها إلا عندما تثبت بيانات تعريف الجلسة الحالية النظير نفسه في الرسالة المباشرة على حساب Matrix نفسه؛ وإلا يعود OpenClaw إلى التوجيه العادي في نطاق المستخدم. +- عندما يرى OpenClaw أن غرفة رسالة مباشرة في Matrix تتصادم مع غرفة رسالة مباشرة أخرى على جلسة Matrix DM المشتركة نفسها، فإنه ينشر `m.notice` لمرة واحدة في تلك الغرفة مع مخرج الهروب `/focus` عندما تكون روابط الخيوط ممكّنة ومع تلميح `dm.sessionScope`. +- تُدعَم روابط الخيوط وقت التشغيل في Matrix. تعمل الآن `/focus` و`/unfocus` و`/agents` و`/session idle` و`/session max-age` و`/acp spawn` المرتبط بالخيط في غرف Matrix ورسائلها المباشرة. +- ينشئ `/focus` على مستوى الغرفة/الرسالة المباشرة الأعلى في Matrix خيط Matrix جديدًا ويربطه بالجلسة المستهدفة عندما يكون `threadBindings.spawnSubagentSessions=true`. +- يؤدي تشغيل `/focus` أو `/acp spawn --thread here` داخل خيط Matrix موجود إلى ربط ذلك الخيط الحالي بدلًا من ذلك. ## روابط محادثات ACP -يمكن تحويل غرف Matrix والرسائل الخاصة وسلاسل Matrix الموجودة إلى مساحات عمل ACP دائمة دون تغيير سطح الدردشة. +يمكن تحويل غرف Matrix والرسائل المباشرة وخيوط Matrix الموجودة إلى مساحات عمل ACP دائمة دون تغيير سطح الدردشة. -تدفق المشغّل السريع: +تدفق سريع للمشغّل: -- شغّل `/acp spawn codex --bind here` داخل الرسالة الخاصة أو الغرفة أو سلسلة الرسائل الموجودة في Matrix التي تريد الاستمرار في استخدامها. -- في رسالة خاصة أو غرفة Matrix على المستوى الأعلى، تبقى الرسالة الخاصة/الغرفة الحالية هي سطح الدردشة وتُوجَّه الرسائل المستقبلية إلى جلسة ACP التي تم إنشاؤها. -- داخل سلسلة Matrix موجودة، يربط `--bind here` تلك السلسلة الحالية في مكانها. +- شغّل `/acp spawn codex --bind here` داخل رسالة Matrix المباشرة أو الغرفة أو الخيط الموجود الذي تريد الاستمرار في استخدامه. +- في رسالة Matrix مباشرة أو غرفة على المستوى الأعلى، يبقى سطح الدردشة هو الرسالة المباشرة/الغرفة الحالية، وتُوجَّه الرسائل المستقبلية إلى جلسة ACP التي تم إنشاؤها. +- داخل خيط Matrix موجود، يربط `--bind here` ذلك الخيط الحالي في مكانه. - يعيد `/new` و`/reset` تعيين جلسة ACP المرتبطة نفسها في مكانها. -- يغلق `/acp close` جلسة ACP ويزيل الربط. +- يغلق `/acp close` جلسة ACP ويزيل الرابط. ملاحظات: -- لا يؤدي `--bind here` إلى إنشاء سلسلة Matrix فرعية. -- لا تكون `threadBindings.spawnAcpSessions` مطلوبة إلا لـ `/acp spawn --thread auto|here`، حيث يحتاج OpenClaw إلى إنشاء سلسلة Matrix فرعية أو ربطها. +- لا ينشئ `--bind here` خيط Matrix فرعيًا. +- لا يكون `threadBindings.spawnAcpSessions` مطلوبًا إلا مع `/acp spawn --thread auto|here`، عندما يحتاج OpenClaw إلى إنشاء خيط Matrix فرعي أو ربطه. -### تهيئة ربط سلاسل الرسائل +### تكوين ربط الخيط -ترث Matrix القيم الافتراضية العامة من `session.threadBindings`، كما تدعم أيضًا تجاوزات لكل قناة: +يرث Matrix القيم الافتراضية العامة من `session.threadBindings`، ويدعم أيضًا تجاوزات لكل قناة: - `threadBindings.enabled` - `threadBindings.idleHours` @@ -789,29 +789,29 @@ openclaw matrix direct repair --user-id @alice:example.org - `threadBindings.spawnSubagentSessions` - `threadBindings.spawnAcpSessions` -علامات إنشاء الروابط الخاصة بسلاسل Matrix اختيارية: +إشارات إنشاء الجلسات المرتبطة بالخيط في Matrix اختيارية: -- عيّن `threadBindings.spawnSubagentSessions: true` للسماح لـ `/focus` على المستوى الأعلى بإنشاء سلاسل Matrix جديدة وربطها. -- عيّن `threadBindings.spawnAcpSessions: true` للسماح لـ `/acp spawn --thread auto|here` بربط جلسات ACP بسلاسل Matrix. +- عيّن `threadBindings.spawnSubagentSessions: true` للسماح للأمر `/focus` على المستوى الأعلى بإنشاء خيوط Matrix جديدة وربطها. +- عيّن `threadBindings.spawnAcpSessions: true` للسماح للأمر `/acp spawn --thread auto|here` بربط جلسات ACP بخيوط Matrix. ## التفاعلات -تدعم Matrix إجراءات التفاعل الصادرة، وإشعارات التفاعل الواردة، وتفاعلات الإقرار الواردة. +يدعم Matrix إجراءات التفاعل الصادرة، وإشعارات التفاعل الواردة، وتفاعلات الإقرار الواردة. -- تخضع أدوات التفاعل الصادرة إلى `channels["matrix"].actions.reactions`. -- يضيف `react` تفاعلًا إلى حدث Matrix محدد. -- يعرض `reactions` ملخص التفاعلات الحالي لحدث Matrix محدد. +- يتم تقييد أدوات التفاعل الصادرة بواسطة `channels["matrix"].actions.reactions`. +- تضيف `react` تفاعلًا إلى حدث Matrix محدد. +- تسرد `reactions` الملخص الحالي للتفاعلات لحدث Matrix محدد. - يؤدي `emoji=""` إلى إزالة تفاعلات حساب الروبوت نفسه على ذلك الحدث. -- يؤدي `remove: true` إلى إزالة تفاعل الرمز التعبيري المحدد فقط من حساب الروبوت. +- يؤدي `remove: true` إلى إزالة تفاعل emoji المحدد فقط من حساب الروبوت. يُحل نطاق تفاعلات الإقرار وفق ترتيب OpenClaw القياسي: - `channels["matrix"].accounts..ackReaction` - `channels["matrix"].ackReaction` - `messages.ackReaction` -- الرجوع إلى الرمز التعبيري لهوية الوكيل +- الرجوع إلى emoji هوية الوكيل -يُحل نطاق تفاعلات الإقرار بهذا الترتيب: +يُحل نطاق تفاعل الإقرار بهذا الترتيب: - `channels["matrix"].accounts..ackReactionScope` - `channels["matrix"].ackReactionScope` @@ -825,31 +825,31 @@ openclaw matrix direct repair --user-id @alice:example.org السلوك الحالي: -- `reactionNotifications: "own"` يمرر أحداث `m.reaction` المضافة عندما تستهدف رسائل Matrix التي ألّفها الروبوت. -- `reactionNotifications: "off"` يعطل أحداث نظام التفاعل. -- لا تزال إزالة التفاعلات لا تُركَّب كأحداث نظام لأن Matrix تعرضها كعمليات حذف، وليس كعمليات إزالة `m.reaction` مستقلة. +- يمرر `reactionNotifications: "own"` أحداث `m.reaction` المضافة عندما تستهدف رسائل Matrix التي أنشأها الروبوت. +- يعطّل `reactionNotifications: "off"` أحداث نظام التفاعل. +- لا تزال عمليات إزالة التفاعل غير مُصنَّعة كأحداث نظام لأن Matrix يعرضها كعمليات حذف redactions، وليس كإزالات مستقلة لـ `m.reaction`. ## سياق السجل -- يتحكم `channels.matrix.historyLimit` في عدد رسائل الغرفة الحديثة التي تُضمَّن بوصفها `InboundHistory` عندما تحفز رسالة غرفة Matrix الوكيل. -- ويرجع إلى `messages.groupChat.historyLimit`. وإذا لم يُضبط أي منهما، تكون القيمة الافتراضية الفعلية `0`، لذلك لا تُخزَّن رسائل الغرف المقيدة بالذكر مؤقتًا. اضبط `0` للتعطيل. -- يكون سجل غرف Matrix خاصًا بالغرف فقط. وتستمر الرسائل الخاصة باستخدام سجل الجلسات العادي. -- سجل غرف Matrix خاص بالعناصر المعلّقة فقط: يخزّن OpenClaw رسائل الغرف التي لم تحفز ردًا بعد، ثم يلتقط تلك النافذة عندما يصل ذكر أو محفز آخر. -- لا تُضمَّن رسالة التحفيز الحالية في `InboundHistory`؛ بل تبقى في متن الإدخال الرئيسي لتلك الدورة. +- يتحكم `channels.matrix.historyLimit` في عدد رسائل الغرف الأخيرة المضمّنة كـ `InboundHistory` عندما تؤدي رسالة غرفة Matrix إلى تشغيل الوكيل. +- يرجع إلى `messages.groupChat.historyLimit`. إذا لم يكن أي منهما معيّنًا، فالقيمة الافتراضية الفعالة هي `0`، لذلك لا يتم تخزين رسائل الغرف المقيّدة بالذكر مؤقتًا. عيّن `0` للتعطيل. +- يقتصر سجل غرف Matrix على الغرف فقط. وتستمر الرسائل المباشرة في استخدام سجل الجلسة العادي. +- سجل غرف Matrix هو سجل معلق فقط: يخزن OpenClaw رسائل الغرف التي لم تفعّل ردًا بعد، ثم يلتقط تلك النافذة عندما يصل ذكر أو مُشغِّل آخر. +- لا تُضمَّن رسالة التشغيل الحالية في `InboundHistory`؛ بل تبقى في الجسم الرئيسي الوارد لذلك الدور. - تعيد محاولات الحدث نفسه في Matrix استخدام لقطة السجل الأصلية بدلًا من الانجراف إلى رسائل غرف أحدث. ## رؤية السياق -تدعم Matrix عنصر التحكم المشترك `contextVisibility` لسياق الغرفة التكميلي مثل نص الرد المستجلب وجذور سلاسل الرسائل والسجل المعلّق. +يدعم Matrix عنصر التحكم المشترك `contextVisibility` للسياق الإضافي للغرفة مثل نصوص الردود المجلبة، وجذور الخيوط، والسجل المعلّق. -- `contextVisibility: "all"` هو الافتراضي. يُحتفظ بالسياق التكميلي كما وصل. -- `contextVisibility: "allowlist"` يرشّح السياق التكميلي إلى المرسلين المسموح لهم بموجب فحوصات allowlist النشطة للغرفة/المستخدم. -- `contextVisibility: "allowlist_quote"` يعمل مثل `allowlist`، لكنه يحتفظ مع ذلك برد مقتبس صريح واحد. +- `contextVisibility: "all"` هو الافتراضي. يتم الاحتفاظ بالسياق الإضافي كما تم استلامه. +- يرشح `contextVisibility: "allowlist"` السياق الإضافي إلى المرسلين المسموح بهم بواسطة فحوصات قائمة السماح النشطة للغرفة/المستخدم. +- يتصرف `contextVisibility: "allowlist_quote"` مثل `allowlist`، لكنه يحتفظ أيضًا برد مقتبس صريح واحد. -يؤثر هذا الإعداد في رؤية السياق التكميلي، وليس في ما إذا كانت الرسالة الواردة نفسها يمكن أن تحفز ردًا. -ولا يزال ترخيص التحفيز يأتي من `groupPolicy` و`groups` و`groupAllowFrom` وإعدادات سياسة الرسائل الخاصة. +يؤثر هذا الإعداد في رؤية السياق الإضافي، وليس في ما إذا كانت الرسالة الواردة نفسها يمكن أن تؤدي إلى رد. +ولا يزال تفويض التشغيل يأتي من `groupPolicy` و`groups` و`groupAllowFrom` وإعدادات سياسة الرسائل المباشرة. -## مثال على سياسة الرسائل الخاصة والغرف +## مثال على سياسة الرسائل المباشرة والغرف ```json5 { @@ -872,22 +872,23 @@ openclaw matrix direct repair --user-id @alice:example.org } ``` -راجع [Groups](/ar/channels/groups) لمعرفة سلوك التقييد بالذكر وallowlist. +راجع [المجموعات](/ar/channels/groups) لمعرفة سلوك تقييد الذكر وقائمة السماح. -مثال pairing لرسائل Matrix الخاصة: +مثال على الإقران لرسائل Matrix المباشرة: ```bash openclaw pairing list matrix openclaw pairing approve matrix ``` -إذا استمر مستخدم Matrix غير معتمد في مراسلتك قبل الموافقة، يعيد OpenClaw استخدام رمز pairing المعلّق نفسه وقد يرسل رد تذكير مرة أخرى بعد فترة تهدئة قصيرة بدلًا من إصدار رمز جديد. +إذا استمر مستخدم Matrix غير معتمد في مراسلتك قبل الموافقة، فسيعيد OpenClaw استخدام رمز الإقران المعلّق نفسه وقد يرسل رد تذكير مرة أخرى بعد فترة تهدئة قصيرة بدلًا من إصدار رمز جديد. -راجع [Pairing](/ar/channels/pairing) لمعرفة تدفق pairing المشترك للرسائل الخاصة وتخطيط التخزين. +راجع [الإقران](/ar/channels/pairing) لمعرفة تدفق إقران الرسائل المباشرة المشترك وتخطيط التخزين. -## موافقات exec +## موافقات Exec -يمكن لـ Matrix أن تعمل كعميل موافقات exec لحساب Matrix. +يمكن أن يعمل Matrix كعميل موافقة أصلي لحساب Matrix. ولا تزال +عناصر التحكم الأصلية في توجيه الرسائل المباشرة/القنوات موجودة ضمن تكوين موافقة exec: - `channels.matrix.execApprovals.enabled` - `channels.matrix.execApprovals.approvers` (اختياري؛ يرجع إلى `channels.matrix.dm.allowFrom`) @@ -895,37 +896,38 @@ openclaw pairing approve matrix - `channels.matrix.execApprovals.agentFilter` - `channels.matrix.execApprovals.sessionFilter` -يجب أن يكون الموافقون معرّفات مستخدمي Matrix مثل `@owner:example.org`. تفعّل Matrix موافقات exec الأصلية تلقائيًا عندما تكون `enabled` غير مضبوطة أو تساوي `"auto"` ويمكن تحليل موافق واحد على الأقل، إما من `execApprovals.approvers` أو من `channels.matrix.dm.allowFrom`. عيّن `enabled: false` لتعطيل Matrix كعميل موافقة أصلي صراحةً. وبخلاف ذلك، تعود طلبات الموافقة إلى مسارات الموافقة المهيأة الأخرى أو إلى سياسة الموافقة الاحتياطية لـ exec. +يجب أن يكون الموافقون معرّفات مستخدمي Matrix مثل `@owner:example.org`. يفعّل Matrix الموافقات الأصلية تلقائيًا عندما تكون `enabled` غير معيّنة أو تساوي `"auto"` ويمكن حل موافق واحد على الأقل. تستخدم موافقات Exec أولًا مجموعة الموافقين من `execApprovals.approvers` ويمكن أن ترجع إلى `channels.matrix.dm.allowFrom`. وتفوّض موافقات الإضافة عبر `channels.matrix.dm.allowFrom`. عيّن `enabled: false` لتعطيل Matrix كعميل موافقة أصلي بشكل صريح. وإلا فسترجع طلبات الموافقة إلى مسارات الموافقة المكوّنة الأخرى أو إلى سياسة الرجوع للموافقة. -التوجيه الأصلي لـ Matrix خاص بـ exec فقط حاليًا: +يدعم التوجيه الأصلي في Matrix الآن نوعي الموافقة: -- يتحكم `channels.matrix.execApprovals.*` في التوجيه الأصلي للرسائل الخاصة/القنوات لموافقات exec فقط. -- ما تزال موافقات plugin تستخدم `/approve` المشترك في المحادثة نفسها بالإضافة إلى أي توجيه `approvals.plugin` مهيأ. -- ما تزال Matrix قادرة على إعادة استخدام `channels.matrix.dm.allowFrom` لتفويض موافقات plugin عندما تتمكن من استنتاج الموافقين بأمان، لكنها لا تعرض مسار توزيع أصلي منفصل لموافقات plugin عبر الرسائل الخاصة/القنوات. +- تتحكم `channels.matrix.execApprovals.*` في وضع التوزيع الأصلي للرسائل المباشرة/القنوات لمطالبات موافقة Matrix. +- تستخدم موافقات Exec مجموعة الموافقين الخاصة بالتنفيذ من `execApprovals.approvers` أو `channels.matrix.dm.allowFrom`. +- تستخدم موافقات الإضافة قائمة سماح الرسائل المباشرة في Matrix من `channels.matrix.dm.allowFrom`. +- تنطبق اختصارات التفاعل في Matrix وتحديثات الرسائل على كل من موافقات exec وموافقات الإضافة. قواعد التسليم: -- `target: "dm"` يرسل مطالبات الموافقة إلى الرسائل الخاصة للموافقين -- `target: "channel"` يعيد إرسال المطالبة إلى غرفة أو رسالة Matrix الأصلية -- `target: "both"` يرسل إلى الرسائل الخاصة للموافقين وإلى غرفة أو رسالة Matrix الأصلية +- يرسل `target: "dm"` مطالبات الموافقة إلى الرسائل المباشرة للموافقين +- يرسل `target: "channel"` المطالبة مرة أخرى إلى غرفة Matrix أو الرسالة المباشرة الأصلية +- يرسل `target: "both"` إلى الرسائل المباشرة للموافقين وإلى غرفة Matrix أو الرسالة المباشرة الأصلية تزرع مطالبات الموافقة في Matrix اختصارات التفاعل على رسالة الموافقة الأساسية: - `✅` = السماح مرة واحدة - `❌` = الرفض -- `♾️` = السماح دائمًا عندما يكون هذا القرار مسموحًا بموجب سياسة exec الفعلية +- `♾️` = السماح دائمًا عندما يكون هذا القرار مسموحًا به بواسطة سياسة exec الفعالة يمكن للموافقين التفاعل على تلك الرسالة أو استخدام أوامر الشرطة المائلة الاحتياطية: `/approve allow-once` أو `/approve allow-always` أو `/approve deny`. -لا يمكن الموافقة أو الرفض إلا من قبل الموافقين الذين تم تحليلهم. ويتضمن التسليم عبر القناة نص الأمر، لذلك فعّل `channel` أو `both` فقط في الغرف الموثوقة. +لا يمكن سوى للموافقين الذين تم حلهم أن يوافقوا أو يرفضوا. بالنسبة إلى موافقات exec، يتضمن التسليم عبر القناة نص الأمر، لذا فعّل `channel` أو `both` فقط في الغرف الموثوق بها. -تعيد مطالبات الموافقة في Matrix استخدام مخطط الموافقة الأساسي المشترك. والسطح الأصلي الخاص بـ Matrix هو مجرد وسيلة نقل لموافقات exec: توجيه الغرف/الرسائل الخاصة وسلوك إرسال/تحديث/حذف الرسائل. +تعيد مطالبات الموافقة في Matrix استخدام مخطط الموافقة الأساسي المشترك. ويتولى السطح الأصلي الخاص بـ Matrix التوجيه بين الغرف/الرسائل المباشرة، والتفاعلات، وسلوك إرسال/تحديث/حذف الرسائل لكل من موافقات exec وموافقات الإضافة. تجاوز لكل حساب: - `channels.matrix.accounts..execApprovals` -المستندات ذات الصلة: [Exec approvals](/ar/tools/exec-approvals) +المستندات ذات الصلة: [موافقات Exec](/ar/tools/exec-approvals) ## مثال على الحسابات المتعددة @@ -958,20 +960,20 @@ openclaw pairing approve matrix ``` تعمل قيم `channels.matrix` ذات المستوى الأعلى كقيم افتراضية للحسابات المسماة ما لم يتجاوزها الحساب. -يمكنك تحديد إدخالات الغرف الموروثة لحساب Matrix واحد باستخدام `groups..account` (أو `rooms..account` القديم). -تبقى الإدخالات التي لا تحتوي على `account` مشتركة عبر جميع حسابات Matrix، ولا تزال الإدخالات التي تحتوي على `account: "default"` تعمل عندما يكون الحساب الافتراضي مهيأً مباشرة على `channels.matrix.*` الأعلى مستوى. -لا تؤدي القيم الافتراضية المشتركة الجزئية للمصادقة إلى إنشاء حساب افتراضي ضمني منفصل بمفردها. لا يقوم OpenClaw بتركيب الحساب `default` الأعلى مستوى إلا عندما تكون لهذا الافتراضي مصادقة حديثة (`homeserver` مع `accessToken`، أو `homeserver` مع `userId` و`password`)؛ ويمكن للحسابات المسماة أن تبقى قابلة للاكتشاف من `homeserver` مع `userId` عندما تلبي بيانات الاعتماد المؤقتة المصادقة لاحقًا. -إذا كان لدى Matrix بالفعل حساب مسمى واحد فقط بالضبط، أو كان `defaultAccount` يشير إلى مفتاح حساب مسمى موجود، فإن ترقية الإصلاح/الإعداد من حساب واحد إلى عدة حسابات تحافظ على ذلك الحساب بدلًا من إنشاء إدخال `accounts.default` جديد. تنتقل فقط مفاتيح مصادقة/bootstrap الخاصة بـ Matrix إلى ذلك الحساب المُرقّى؛ أما مفاتيح سياسة التسليم المشتركة فتبقى على المستوى الأعلى. -عيّن `defaultAccount` عندما تريد أن يفضّل OpenClaw حساب Matrix مسمىً واحدًا للتوجيه الضمني والفحص وعمليات CLI. -إذا هيأت عدة حسابات مسماة، فقم بتعيين `defaultAccount` أو مرر `--account ` لأوامر CLI التي تعتمد على اختيار الحساب الضمني. -مرر `--account ` إلى `openclaw matrix verify ...` و`openclaw matrix devices ...` عندما تريد تجاوز هذا الاختيار الضمني لأمر واحد. +يمكنك تحديد نطاق إدخالات الغرف الموروثة لحساب Matrix واحد باستخدام `groups..account` (أو `rooms..account` القديم). +تبقى الإدخالات التي لا تحتوي على `account` مشتركة بين جميع حسابات Matrix، ولا تزال الإدخالات التي تحتوي على `account: "default"` تعمل عندما يكون الحساب الافتراضي مُكوَّنًا مباشرة في `channels.matrix.*` ذات المستوى الأعلى. +لا تنشئ قيم المصادقة الافتراضية الجزئية المشتركة حسابًا افتراضيًا ضمنيًا منفصلًا بحد ذاتها. لا يقوم OpenClaw بتركيب الحساب `default` ذي المستوى الأعلى إلا عندما يملك ذلك الافتراضي مصادقة حديثة (`homeserver` مع `accessToken`، أو `homeserver` مع `userId` و`password`)؛ ويمكن للحسابات المسماة أن تظل قابلة للاكتشاف من `homeserver` مع `userId` عندما تلبّي بيانات الاعتماد المخزنة مؤقتًا المصادقة لاحقًا. +إذا كان Matrix يحتوي بالفعل على حساب مسمى واحد فقط تمامًا، أو كان `defaultAccount` يشير إلى مفتاح حساب مسمى موجود، فإن ترقية الإصلاح/الإعداد من حساب واحد إلى حسابات متعددة تحافظ على ذلك الحساب بدلًا من إنشاء إدخال `accounts.default` جديد. لا تنتقل إلى ذلك الحساب المُرقّى إلا مفاتيح مصادقة/تهيئة Matrix؛ وتبقى مفاتيح سياسات التسليم المشتركة في المستوى الأعلى. +عيّن `defaultAccount` عندما تريد من OpenClaw أن يفضّل حساب Matrix مسمى واحدًا للتوجيه الضمني، والفحص، وعمليات CLI. +إذا قمت بتكوين عدة حسابات مسماة، فعيّن `defaultAccount` أو مرر `--account ` لأوامر CLI التي تعتمد على اختيار الحساب الضمني. +مرر `--account ` إلى `openclaw matrix verify ...` و`openclaw matrix devices ...` عندما تريد تجاوز ذلك الاختيار الضمني لأمر واحد. -## homeserverات الخاصة/ضمن LAN +## الخوادم المنزلية الخاصة/الشبكة المحلية -افتراضيًا، يحظر OpenClaw homeserverات Matrix الخاصة/الداخلية للحماية من SSRF ما لم -تقم بالاشتراك الصريح لكل حساب. +بشكل افتراضي، يمنع OpenClaw الخوادم المنزلية الخاصة/الداخلية لـ Matrix للحماية من SSRF ما لم +توافق صراحةً على ذلك لكل حساب. -إذا كان homeserver لديك يعمل على localhost أو عنوان LAN/Tailscale IP أو اسم مضيف داخلي، فقم بتمكين +إذا كان الخادم المنزلي يعمل على localhost أو عنوان IP لشبكة LAN/Tailscale أو اسم مضيف داخلي، فقم بتمكين `network.dangerouslyAllowPrivateNetwork` لذلك الحساب في Matrix: ```json5 @@ -988,7 +990,7 @@ openclaw pairing approve matrix } ``` -مثال إعداد CLI: +مثال إعداد عبر CLI: ```bash openclaw matrix account add \ @@ -998,12 +1000,12 @@ openclaw matrix account add \ --access-token syt_ops_xxx ``` -يسمح هذا الاشتراك الاختياري فقط بالأهداف الخاصة/الداخلية الموثوقة. أما homeserverات -النص الواضح العامة مثل `http://matrix.example.org:8008` فتبقى محظورة. ويفضَّل استخدام `https://` كلما أمكن. +يسمح هذا الاختيار فقط بالأهداف الخاصة/الداخلية الموثوق بها. أما الخوادم المنزلية العامة غير المشفرة مثل +`http://matrix.example.org:8008` فتبقى محظورة. فضّل `https://` كلما أمكن. -## تمرير حركة Matrix عبر proxy +## تمرير حركة مرور Matrix عبر وكيل -إذا كان نشر Matrix لديك يحتاج إلى proxy HTTP(S) صريح للخروج، فعيّن `channels.matrix.proxy`: +إذا كانت عملية نشر Matrix لديك تحتاج إلى وكيل HTTP(S) صادر صريح، فعيّن `channels.matrix.proxy`: ```json5 { @@ -1017,79 +1019,79 @@ openclaw matrix account add \ } ``` -يمكن للحسابات المسماة تجاوز القيمة الافتراضية الأعلى مستوى باستخدام `channels.matrix.accounts..proxy`. -ويستخدم OpenClaw إعداد proxy نفسه لحركة Matrix أثناء التشغيل ولفحوصات حالة الحساب. +يمكن للحسابات المسماة تجاوز الافتراضي ذي المستوى الأعلى باستخدام `channels.matrix.accounts..proxy`. +يستخدم OpenClaw إعداد الوكيل نفسه لكل من حركة مرور Matrix وقت التشغيل وفحوصات حالة الحساب. -## تحليل الأهداف +## حل الأهداف -تقبل Matrix أشكال الأهداف التالية في أي موضع يطلب منك فيه OpenClaw هدف غرفة أو مستخدم: +يقبل Matrix صيغ الأهداف التالية في أي مكان يطلب منك OpenClaw فيه هدف غرفة أو مستخدم: - المستخدمون: `@user:server` أو `user:@user:server` أو `matrix:user:@user:server` - الغرف: `!room:server` أو `room:!room:server` أو `matrix:room:!room:server` - الأسماء المستعارة: `#alias:server` أو `channel:#alias:server` أو `matrix:channel:#alias:server` -يستخدم البحث الحي في الدليل حساب Matrix المسجل دخوله: +يستخدم البحث المباشر في الدليل حساب Matrix الذي تم تسجيل الدخول به: -- تستعلم عمليات البحث عن المستخدمين دليل مستخدمي Matrix على ذلك homeserver. -- تقبل عمليات البحث عن الغرف معرّفات الغرف والأسماء المستعارة الصريحة مباشرة، ثم تعود إلى البحث في أسماء الغرف المنضم إليها لذلك الحساب. -- إن البحث في أسماء الغرف المنضم إليها هو أفضل جهد. وإذا تعذر تحليل اسم غرفة إلى معرّف أو اسم مستعار، فسيُتجاهل في تحليل allowlist أثناء التشغيل. +- تستعلم عمليات البحث عن المستخدمين دليل مستخدمي Matrix على ذلك الخادم المنزلي. +- تقبل عمليات البحث عن الغرف معرّفات الغرف والأسماء المستعارة الصريحة مباشرة، ثم ترجع إلى البحث في أسماء الغرف المنضم إليها لذلك الحساب. +- البحث في أسماء الغرف المنضم إليها هو أفضل جهد. إذا تعذر حل اسم الغرفة إلى معرّف أو اسم مستعار، يتم تجاهله بواسطة حل قائمة السماح وقت التشغيل. -## مرجع التهيئة +## مرجع التكوين - `enabled`: تمكين القناة أو تعطيلها. - `name`: تسمية اختيارية للحساب. -- `defaultAccount`: معرّف الحساب المفضل عند تهيئة عدة حسابات Matrix. -- `homeserver`: عنوان URL لـ homeserver، مثل `https://matrix.example.org`. -- `network.dangerouslyAllowPrivateNetwork`: السماح لهذا الحساب في Matrix بالاتصال بـ homeserverات خاصة/داخلية. فعّل هذا عندما يُحل homeserver إلى `localhost` أو عنوان LAN/Tailscale IP أو مضيف داخلي مثل `matrix-synapse`. -- `proxy`: عنوان URL اختياري لـ proxy HTTP(S) لحركة Matrix. ويمكن للحسابات المسماة تجاوز القيمة الافتراضية الأعلى مستوى باستخدام `proxy` الخاص بها. -- `userId`: معرّف مستخدم Matrix الكامل، مثل `@bot:example.org`. -- `accessToken`: access token للمصادقة المعتمدة على token. القيم النصية الصريحة وقيم SecretRef مدعومة في `channels.matrix.accessToken` و`channels.matrix.accounts..accessToken` عبر مزودي env/file/exec. راجع [إدارة الأسرار](/ar/gateway/secrets). -- `password`: كلمة المرور لتسجيل الدخول المعتمد على كلمة المرور. القيم النصية الصريحة وقيم SecretRef مدعومة. +- `defaultAccount`: معرّف الحساب المفضل عند تكوين عدة حسابات Matrix. +- `homeserver`: عنوان URL للخادم المنزلي، على سبيل المثال `https://matrix.example.org`. +- `network.dangerouslyAllowPrivateNetwork`: يسمح لهذا الحساب في Matrix بالاتصال بالخوادم المنزلية الخاصة/الداخلية. قم بتمكين هذا عندما يُحل الخادم المنزلي إلى `localhost` أو عنوان IP لشبكة LAN/Tailscale أو مضيف داخلي مثل `matrix-synapse`. +- `proxy`: عنوان URL اختياري لوكيل HTTP(S) لحركة مرور Matrix. يمكن للحسابات المسماة تجاوز الافتراضي ذي المستوى الأعلى باستخدام `proxy` خاص بها. +- `userId`: معرّف مستخدم Matrix الكامل، على سبيل المثال `@bot:example.org`. +- `accessToken`: رمز وصول للمصادقة المعتمدة على الرموز. تُدعم القيم النصية الصريحة وقيم SecretRef لكل من `channels.matrix.accessToken` و`channels.matrix.accounts..accessToken` عبر مزودي env/file/exec. راجع [إدارة الأسرار](/ar/gateway/secrets). +- `password`: كلمة مرور لتسجيل الدخول المعتمد على كلمة المرور. تُدعم القيم النصية الصريحة وقيم SecretRef. - `deviceId`: معرّف جهاز Matrix صريح. - `deviceName`: اسم عرض الجهاز لتسجيل الدخول بكلمة المرور. -- `avatarUrl`: عنوان URL مخزّن للصورة الذاتية لمزامنة الملف الشخصي وتحديثات `set-profile`. +- `avatarUrl`: عنوان URL للصورة الرمزية الذاتية المخزّن لمزامنة الملف الشخصي وتحديثات `set-profile`. - `initialSyncLimit`: حد أحداث المزامنة عند بدء التشغيل. - `encryption`: تمكين E2EE. -- `allowlistOnly`: فرض سلوك allowlist فقط للرسائل الخاصة والغرف. -- `allowBots`: السماح بالرسائل من حسابات OpenClaw Matrix الأخرى المهيأة (`true` أو `"mentions"`). -- `groupPolicy`: `open` أو `allowlist` أو `disabled`. -- `contextVisibility`: وضع رؤية سياق الغرفة التكميلي (`all` أو `allowlist` أو `allowlist_quote`). -- `groupAllowFrom`: allowlist لمعرّفات المستخدمين لحركة الغرف. -- يجب أن تكون إدخالات `groupAllowFrom` معرّفات مستخدمي Matrix كاملة. وتُتجاهل الأسماء غير المحللة أثناء التشغيل. -- `historyLimit`: الحد الأقصى لرسائل الغرفة التي تُضمَّن كسياق سجل للمجموعة. ويرجع إلى `messages.groupChat.historyLimit`؛ وإذا لم يُضبط أي منهما، تكون القيمة الافتراضية الفعلية `0`. اضبط `0` للتعطيل. -- `replyToMode`: `off` أو `first` أو `all` أو `batched`. -- `markdown`: تهيئة اختيارية لتصيير Markdown في نص Matrix الصادر. -- `streaming`: `off` (الافتراضي) أو `partial` أو `quiet` أو `true` أو `false`. يعمل `partial` و`true` على تمكين تحديثات المسودة القائمة على المعاينة أولًا باستخدام رسائل Matrix النصية العادية. ويستخدم `quiet` إشعارات معاينة غير مُرسِلة للإشعار من أجل إعدادات push-rule المستضافة ذاتيًا. -- `blockStreaming`: تؤدي القيمة `true` إلى تمكين رسائل تقدم منفصلة لكتل المساعد المكتملة أثناء نشاط بث معاينة المسودة. -- `threadReplies`: `off` أو `inbound` أو `always`. -- `threadBindings`: تجاوزات لكل قناة لتوجيه الجلسات المرتبطة بسلاسل الرسائل ودورة حياتها. +- `allowlistOnly`: فرض سلوك قائمة السماح فقط للرسائل المباشرة والغرف. +- `allowBots`: السماح برسائل من حسابات OpenClaw Matrix الأخرى المكوّنة (`true` أو `"mentions"`). +- `groupPolicy`: ‏`open` أو `allowlist` أو `disabled`. +- `contextVisibility`: وضع رؤية سياق الغرفة الإضافي (`all` أو `allowlist` أو `allowlist_quote`). +- `groupAllowFrom`: قائمة سماح لمعرّفات المستخدمين لحركة مرور الغرف. +- يجب أن تكون إدخالات `groupAllowFrom` معرّفات مستخدمي Matrix كاملة. تُتجاهل الأسماء غير المحلولة وقت التشغيل. +- `historyLimit`: الحد الأقصى لرسائل الغرف التي تُضمَّن كسياق سجل للمجموعة. يرجع إلى `messages.groupChat.historyLimit`؛ وإذا لم يكن أي منهما معيّنًا، فالقيمة الافتراضية الفعالة هي `0`. عيّن `0` للتعطيل. +- `replyToMode`: ‏`off` أو `first` أو `all` أو `batched`. +- `markdown`: تكوين اختياري لعرض Markdown للنص الصادر في Matrix. +- `streaming`: ‏`off` (الافتراضي) أو `partial` أو `quiet` أو `true` أو `false`. يفعّل `partial` و`true` تحديثات المسودة بنمط المعاينة أولًا باستخدام رسائل Matrix النصية العادية. ويستخدم `quiet` إشعارات معاينة غير مُنبِّهة لإعدادات قواعد الدفع المستضافة ذاتيًا. +- `blockStreaming`: يفعّل `true` رسائل تقدم منفصلة للكتل المكتملة من المساعد بينما يكون بث مسودة المعاينة نشطًا. +- `threadReplies`: ‏`off` أو `inbound` أو `always`. +- `threadBindings`: تجاوزات لكل قناة لتوجيه الجلسات المرتبطة بالخيط ودورة حياتها. - `startupVerification`: وضع طلب التحقق الذاتي التلقائي عند بدء التشغيل (`if-unverified` أو `off`). -- `startupVerificationCooldownHours`: فترة التهدئة قبل إعادة محاولة طلبات التحقق التلقائي عند بدء التشغيل. +- `startupVerificationCooldownHours`: فترة التهدئة قبل إعادة محاولة طلبات التحقق التلقائية عند بدء التشغيل. - `textChunkLimit`: حجم تجزئة الرسائل الصادرة. -- `chunkMode`: `length` أو `newline`. -- `responsePrefix`: بادئة رسائل اختيارية للردود الصادرة. +- `chunkMode`: ‏`length` أو `newline`. +- `responsePrefix`: بادئة رسالة اختيارية للردود الصادرة. - `ackReaction`: تجاوز اختياري لتفاعل الإقرار لهذه القناة/الحساب. - `ackReactionScope`: تجاوز اختياري لنطاق تفاعل الإقرار (`group-mentions` أو `group-all` أو `direct` أو `all` أو `none` أو `off`). - `reactionNotifications`: وضع إشعارات التفاعل الواردة (`own` أو `off`). - `mediaMaxMb`: حد حجم الوسائط بالميغابايت لمعالجة وسائط Matrix. ينطبق على الإرسال الصادر ومعالجة الوسائط الواردة. -- `autoJoin`: سياسة الانضمام التلقائي للدعوات (`always` أو `allowlist` أو `off`). الافتراضي: `off`. ينطبق هذا على دعوات Matrix عمومًا، بما في ذلك دعوات الرسائل الخاصة، وليس فقط دعوات الغرف/المجموعات. يتخذ OpenClaw هذا القرار وقت الدعوة، قبل أن يتمكن من تصنيف الغرفة المنضم إليها بشكل موثوق على أنها رسالة خاصة أو مجموعة. -- `autoJoinAllowlist`: الغرف/الأسماء المستعارة المسموح بها عندما تكون `autoJoin` مساوية لـ `allowlist`. تُحل إدخالات الأسماء المستعارة إلى معرّفات غرف أثناء التعامل مع الدعوة؛ ولا يثق OpenClaw بحالة الاسم المستعار التي تدّعيها الغرفة المدعوة. -- `dm`: كتلة سياسة الرسائل الخاصة (`enabled` أو `policy` أو `allowFrom` أو `sessionScope` أو `threadReplies`). -- `dm.policy`: يتحكم في الوصول إلى الرسائل الخاصة بعد أن ينضم OpenClaw إلى الغرفة ويصنفها على أنها رسالة خاصة. ولا يغيّر ما إذا كانت الدعوة تُضم تلقائيًا. -- يجب أن تكون إدخالات `dm.allowFrom` معرّفات مستخدمي Matrix كاملة ما لم تكن قد حللتها بالفعل عبر البحث الحي في الدليل. -- `dm.sessionScope`: `per-user` (الافتراضي) أو `per-room`. استخدم `per-room` عندما تريد أن تحتفظ كل غرفة رسائل خاصة في Matrix بسياق منفصل حتى لو كان النظير نفسه. -- `dm.threadReplies`: تجاوز سياسة سلاسل الرسائل الخاص بالرسائل الخاصة فقط (`off` أو `inbound` أو `always`). وهو يتجاوز إعداد `threadReplies` الأعلى مستوى لكل من موضع الرد وعزل الجلسة في الرسائل الخاصة. +- `autoJoin`: سياسة الانضمام التلقائي للدعوات (`always` أو `allowlist` أو `off`). الافتراضي: `off`. ينطبق هذا على دعوات Matrix عمومًا، بما في ذلك الدعوات الشبيهة بالرسائل المباشرة، وليس فقط دعوات الغرف/المجموعات. يتخذ OpenClaw هذا القرار في وقت الدعوة، قبل أن يتمكن من تصنيف الغرفة المنضم إليها بشكل موثوق كرسالة مباشرة أو مجموعة. +- `autoJoinAllowlist`: الغرف/الأسماء المستعارة المسموح بها عندما يكون `autoJoin` هو `allowlist`. تُحل إدخالات الأسماء المستعارة إلى معرّفات غرف أثناء معالجة الدعوة؛ ولا يثق OpenClaw في حالة الاسم المستعار التي تدّعيها الغرفة المدعو إليها. +- `dm`: كتلة سياسة الرسائل المباشرة (`enabled` أو `policy` أو `allowFrom` أو `sessionScope` أو `threadReplies`). +- `dm.policy`: يتحكم في وصول الرسائل المباشرة بعد انضمام OpenClaw إلى الغرفة وتصنيفها كرسالة مباشرة. ولا يغير ما إذا كانت الدعوة ستنضم تلقائيًا. +- يجب أن تكون إدخالات `dm.allowFrom` معرّفات مستخدمي Matrix كاملة ما لم تكن قد حللتها بالفعل عبر البحث المباشر في الدليل. +- `dm.sessionScope`: ‏`per-user` (الافتراضي) أو `per-room`. استخدم `per-room` عندما تريد أن تحتفظ كل غرفة رسائل مباشرة في Matrix بسياق منفصل حتى لو كان النظير هو نفسه. +- `dm.threadReplies`: تجاوز لسياسة الخيوط خاص بالرسائل المباشرة (`off` أو `inbound` أو `always`). وهو يتجاوز إعداد `threadReplies` ذي المستوى الأعلى لكل من موضع الرد وعزل الجلسة في الرسائل المباشرة. - `execApprovals`: تسليم موافقات exec الأصلية في Matrix (`enabled` أو `approvers` أو `target` أو `agentFilter` أو `sessionFilter`). -- `execApprovals.approvers`: معرّفات مستخدمي Matrix المسموح لهم بالموافقة على طلبات exec. وهو اختياري عندما يحدد `dm.allowFrom` الموافقين بالفعل. -- `execApprovals.target`: `dm | channel | both` (الافتراضي: `dm`). -- `accounts`: تجاوزات مسماة لكل حساب. تعمل قيم `channels.matrix` الأعلى مستوى كقيم افتراضية لهذه الإدخالات. -- `groups`: خريطة سياسة لكل غرفة. يفضَّل استخدام معرّفات الغرف أو الأسماء المستعارة؛ وتُتجاهل أسماء الغرف غير المحللة أثناء التشغيل. تستخدم هوية الجلسة/المجموعة معرّف الغرفة الثابت بعد التحليل، بينما تستمر التسميات المقروءة للبشر في القدوم من أسماء الغرف. -- `groups..account`: تقييد إدخال غرفة موروث واحد إلى حساب Matrix محدد في إعدادات الحسابات المتعددة. -- `groups..allowBots`: تجاوز على مستوى الغرفة للمرسلين من الروبوتات المهيأة (`true` أو `"mentions"`). -- `groups..users`: allowlist للمرسلين على مستوى الغرفة. -- `groups..tools`: تجاوزات السماح/المنع للأدوات على مستوى الغرفة. -- `groups..autoReply`: تجاوز التقييد بالذكر على مستوى الغرفة. تعني `true` تعطيل متطلبات الذكر لتلك الغرفة؛ وتعني `false` فرضها مرة أخرى. -- `groups..skills`: عامل تصفية Skills اختياري على مستوى الغرفة. +- `execApprovals.approvers`: معرّفات مستخدمي Matrix المسموح لهم بالموافقة على طلبات exec. وهو اختياري عندما تكون `dm.allowFrom` تحدد الموافقين بالفعل. +- `execApprovals.target`: ‏`dm | channel | both` (الافتراضي: `dm`). +- `accounts`: تجاوزات مسماة لكل حساب. تعمل قيم `channels.matrix` ذات المستوى الأعلى كقيم افتراضية لهذه الإدخالات. +- `groups`: خريطة سياسة لكل غرفة. فضّل معرّفات الغرف أو الأسماء المستعارة؛ تُتجاهل أسماء الغرف غير المحلولة وقت التشغيل. تستخدم هوية الجلسة/المجموعة معرّف الغرفة المستقر بعد الحل، بينما تستمر التسميات المقروءة بشريًا في المجيء من أسماء الغرف. +- `groups..account`: يقصر إدخال غرفة موروث واحدًا على حساب Matrix محدد في إعدادات الحسابات المتعددة. +- `groups..allowBots`: تجاوز على مستوى الغرفة للمرسلين من الروبوتات المكوّنة (`true` أو `"mentions"`). +- `groups..users`: قائمة سماح للمرسلين لكل غرفة. +- `groups..tools`: تجاوزات السماح/الرفض للأدوات لكل غرفة. +- `groups..autoReply`: تجاوز على مستوى الغرفة لتقييد الذكر. يؤدي `true` إلى تعطيل متطلبات الذكر لتلك الغرفة؛ ويعيد `false` فرضها. +- `groups..skills`: مرشح Skills اختياري على مستوى الغرفة. - `groups..systemPrompt`: مقتطف system prompt اختياري على مستوى الغرفة. - `rooms`: اسم مستعار قديم لـ `groups`. - `actions`: تقييد الأدوات لكل إجراء (`messages` أو `reactions` أو `pins` أو `profile` أو `memberInfo` أو `channelInfo` أو `verification`). @@ -1097,7 +1099,7 @@ openclaw matrix account add \ ## ذو صلة - [نظرة عامة على القنوات](/ar/channels) — جميع القنوات المدعومة -- [Pairing](/ar/channels/pairing) — مصادقة الرسائل الخاصة وتدفق pairing -- [Groups](/ar/channels/groups) — سلوك الدردشة الجماعية والتقييد بالذكر +- [الإقران](/ar/channels/pairing) — مصادقة الرسائل المباشرة وتدفق الإقران +- [المجموعات](/ar/channels/groups) — سلوك الدردشة الجماعية وتقييد الذكر - [توجيه القنوات](/ar/channels/channel-routing) — توجيه الجلسات للرسائل - [الأمان](/ar/gateway/security) — نموذج الوصول والتقوية diff --git a/docs/ar/concepts/compaction.md b/docs/ar/concepts/compaction.md index be249a207..496067305 100644 --- a/docs/ar/concepts/compaction.md +++ b/docs/ar/concepts/compaction.md @@ -1,23 +1,23 @@ --- read_when: - تريد فهم الضغط التلقائي والأمر /compact - - أنت تصحح جلسات طويلة تصطدم بحدود السياق -summary: كيف يلخّص OpenClaw المحادثات الطويلة للبقاء ضمن حدود النموذج + - أنت تصحح أخطاء الجلسات الطويلة التي تصطدم بحدود السياق +summary: كيف يلخص OpenClaw المحادثات الطويلة للبقاء ضمن حدود النموذج title: الضغط x-i18n: - generated_at: "2026-04-05T12:39:54Z" + generated_at: "2026-04-08T02:14:14Z" model: gpt-5.4 provider: openai - source_hash: 4c6dbd6ebdcd5f918805aafdc153925efef3e130faa3fab3c630832e938219fc + source_hash: e6590b82a8c3a9c310998d653459ca4d8612495703ca0a8d8d306d7643142fd1 source_path: concepts/compaction.md workflow: 15 --- # الضغط -لكل نموذج نافذة سياق — وهي الحد الأقصى لعدد الرموز التي يمكنه معالجتها. +لكل نموذج نافذة سياق -- وهي الحد الأقصى لعدد الرموز التي يمكنه معالجتها. عندما تقترب المحادثة من هذا الحد، يقوم OpenClaw **بضغط** الرسائل الأقدم -إلى ملخص حتى يمكن أن تستمر الدردشة. +في ملخص حتى تتمكن الدردشة من الاستمرار. ## كيف يعمل @@ -25,42 +25,107 @@ x-i18n: 2. يُحفَظ الملخص في نص الجلسة. 3. تُحفَظ الرسائل الحديثة كما هي. -عندما يقسم OpenClaw السجل إلى مقاطع ضغط، فإنه يُبقي استدعاءات أدوات المساعد -مقترنة بإدخالات `toolResult` المطابقة لها. وإذا وقعت نقطة التقسيم -داخل كتلة أداة، ينقل OpenClaw الحد بحيث يبقى الزوج معًا -ويُحفَظ الذيل الحالي غير الملخّص. +عندما يقسم OpenClaw السجل إلى مقاطع ضغط، فإنه يبقي استدعاءات أدوات المساعد +مقترنة بإدخالات `toolResult` المطابقة لها. إذا وقعت نقطة التقسيم +داخل كتلة أداة، ينقل OpenClaw الحد الفاصل بحيث يبقى الزوج معًا +ويُحفَظ الذيل الحالي غير المُلخَّص. -يبقى السجل الكامل للمحادثة محفوظًا على القرص. ولا يغيّر الضغط إلا ما +يبقى سجل المحادثة الكامل محفوظًا على القرص. يغيّر الضغط فقط ما يراه النموذج في الدورة التالية. ## الضغط التلقائي -يكون الضغط التلقائي مفعّلًا افتراضيًا. ويعمل عندما تقترب الجلسة من حد +الضغط التلقائي مفعّل افتراضيًا. يعمل عندما تقترب الجلسة من حد السياق، أو عندما يعيد النموذج خطأ تجاوز السياق (وفي هذه الحالة -يضغط OpenClaw ثم يعيد المحاولة). وتتضمن تواقيع التجاوز الشائعة +يقوم OpenClaw بالضغط ثم يعيد المحاولة). تتضمن تواقيع التجاوز الشائعة `request_too_large` و`context length exceeded` و`input exceeds the maximum number of tokens` و`input token count exceeds the maximum number of input tokens` و`input is too long for the model` و`ollama error: context length exceeded`. -قبل الضغط، يذكّر OpenClaw الوكيل تلقائيًا بحفظ الملاحظات المهمة في ملفات -[memory](/concepts/memory). وهذا يمنع فقدان السياق. +قبل الضغط، يذكّر OpenClaw الوكيل تلقائيًا بحفظ الملاحظات المهمة +في ملفات [memory](/ar/concepts/memory). هذا يمنع فقدان السياق. +استخدم الإعداد `agents.defaults.compaction` في ملف `openclaw.json` لتكوين سلوك الضغط (الوضع، والرموز المستهدفة، وغير ذلك). +يحافظ تلخيص الضغط افتراضيًا على المعرّفات المعتمة (`identifierPolicy: "strict"`). يمكنك تجاوز ذلك باستخدام `identifierPolicy: "off"` أو توفير نص مخصص باستخدام `identifierPolicy: "custom"` و`identifierInstructions`. + +يمكنك اختياريًا تحديد نموذج مختلف لتلخيص الضغط عبر `agents.defaults.compaction.model`. يكون هذا مفيدًا عندما يكون نموذجك الأساسي نموذجًا محليًا أو صغيرًا وتريد أن تُنتَج ملخصات الضغط بواسطة نموذج أكثر قدرة. يقبل هذا التجاوز أي سلسلة `provider/model-id`: + +```json +{ + "agents": { + "defaults": { + "compaction": { + "model": "openrouter/anthropic/claude-sonnet-4-6" + } + } + } +} +``` + +يعمل هذا أيضًا مع النماذج المحلية، على سبيل المثال نموذج Ollama ثانٍ مخصص للتلخيص أو نموذج متخصص مضبوط بدقة للضغط: + +```json +{ + "agents": { + "defaults": { + "compaction": { + "model": "ollama/llama3.1:8b" + } + } + } +} +``` + +عند عدم ضبطه، يستخدم الضغط النموذج الأساسي للوكيل. + +## موفرو الضغط القابلون للتوصيل + +يمكن للمكونات الإضافية تسجيل موفر ضغط مخصص عبر `registerCompactionProvider()` على واجهة API الخاصة بالمكون الإضافي. عند تسجيل موفر وتكوينه، يفوض OpenClaw التلخيص إليه بدلًا من مسار LLM المدمج. + +لاستخدام موفر مسجل، عيّن معرّف الموفر في إعداداتك: + +```json +{ + "agents": { + "defaults": { + "compaction": { + "provider": "my-provider" + } + } + } +} +``` + +يؤدي تعيين `provider` تلقائيًا إلى فرض `mode: "safeguard"`. تتلقى الموفرات تعليمات الضغط نفسها وسياسة الحفاظ على المعرّفات نفسها المستخدمة في المسار المدمج، ويستمر OpenClaw أيضًا في الحفاظ على سياق لاحقة الأدوار الحديثة والأدوار المقسومة بعد مخرجات الموفر. إذا فشل الموفر أو أعاد نتيجة فارغة، يعود OpenClaw إلى تلخيص LLM المدمج. + +## الضغط التلقائي (مفعّل افتراضيًا) + +عندما تقترب الجلسة من نافذة سياق النموذج أو تتجاوزها، يشغّل OpenClaw الضغط التلقائي وقد يعيد محاولة الطلب الأصلي باستخدام السياق المضغوط. + +سترى: + +- `🧹 Auto-compaction complete` في الوضع المفصل +- يعرض `/status` القيمة `🧹 Compactions: ` + +قبل الضغط، يمكن لـ OpenClaw تشغيل دورة **تفريغ ذاكرة صامتة** لتخزين +الملاحظات الدائمة على القرص. راجع [Memory](/ar/concepts/memory) للحصول على التفاصيل والإعدادات. + ## الضغط اليدوي -اكتب `/compact` في أي دردشة لفرض عملية ضغط. وأضف تعليمات لتوجيه +اكتب `/compact` في أي دردشة لفرض الضغط. أضف تعليمات لتوجيه الملخص: ``` -/compact ركّز على قرارات تصميم API +/compact Focus on the API design decisions ``` ## استخدام نموذج مختلف -افتراضيًا، يستخدم الضغط النموذج الأساسي لوكيلك. ويمكنك استخدام نموذج أكثر -قدرة للحصول على ملخصات أفضل: +افتراضيًا، يستخدم الضغط النموذج الأساسي لوكيلك. يمكنك استخدام نموذج +أكثر قدرة للحصول على ملخصات أفضل: ```json5 { @@ -76,8 +141,8 @@ exceeded`. ## إشعار بدء الضغط -افتراضيًا، يعمل الضغط بصمت. ولعرض إشعار موجز عند بدء -الضغط، فعّل `notifyUser`: +افتراضيًا، يعمل الضغط بصمت. لإظهار إشعار موجز عند بدء الضغط، +فعّل `notifyUser`: ```json5 { @@ -91,39 +156,39 @@ exceeded`. } ``` -عند التمكين، يرى المستخدم رسالة قصيرة (على سبيل المثال، "جارٍ ضغط -السياق...") في بداية كل تشغيل لعملية الضغط. +عند تفعيله، يرى المستخدم رسالة قصيرة (على سبيل المثال، "جاري ضغط +السياق...") عند بداية كل عملية ضغط. -## الضغط مقابل التقليم +## الضغط مقابل التقليص -| | الضغط | التقليم | +| | الضغط | التقليص | | ---------------- | ----------------------------- | -------------------------------- | -| **ما الذي يفعله** | يلخّص المحادثة الأقدم | يقتطع نتائج الأدوات القديمة | -| **هل يُحفَظ؟** | نعم (في نص الجلسة) | لا (في الذاكرة فقط، لكل طلب) | -| **النطاق** | المحادثة بأكملها | نتائج الأدوات فقط | +| **ما الذي يفعله** | يلخص المحادثة الأقدم | يقتطع نتائج الأدوات القديمة | +| **هل يُحفَظ؟** | نعم (في نص الجلسة) | لا (في الذاكرة فقط، لكل طلب) | +| **النطاق** | المحادثة بالكامل | نتائج الأدوات فقط | -يُعد [Session pruning](/concepts/session-pruning) مكمّلًا أخف وزنًا -يقوم بتقليم مخرجات الأدوات من دون تلخيص. +يُعد [تقليص الجلسة](/ar/concepts/session-pruning) مكمّلًا أخف وزنًا +يقتطع مخرجات الأدوات دون تلخيصها. ## استكشاف الأخطاء وإصلاحها **هل يحدث الضغط كثيرًا جدًا؟** قد تكون نافذة سياق النموذج صغيرة، أو قد تكون -مخرجات الأدوات كبيرة. جرّب تمكين -[Session pruning](/concepts/session-pruning). +مخرجات الأدوات كبيرة. جرّب تفعيل +[تقليص الجلسة](/ar/concepts/session-pruning). -**هل يبدو السياق قديمًا بعد الضغط؟** استخدم `/compact ركّز على ` لتوجيه -الملخص، أو فعّل [memory flush](/concepts/memory) حتى تبقى الملاحظات -محفوظة. +**هل يبدو السياق قديمًا بعد الضغط؟** استخدم `/compact Focus on ` من أجل +توجيه الملخص، أو فعّل [تفريغ الذاكرة](/ar/concepts/memory) حتى تبقى +الملاحظات محفوظة. -**هل تحتاج إلى بداية نظيفة؟** يبدأ `/new` جلسة جديدة من دون ضغط. +**هل تحتاج إلى بداية نظيفة؟** يبدأ `/new` جلسة جديدة دون ضغط. -للحصول على تهيئة متقدمة (الرموز المحجوزة، والحفاظ على المعرّفات، ومحركات +للحصول على إعدادات متقدمة (الرموز المحجوزة، والحفاظ على المعرّفات، ومحركات السياق المخصصة، والضغط من جهة الخادم في OpenAI)، راجع -[التعمق في إدارة الجلسات](/reference/session-management-compaction). +[التعمق في إدارة الجلسات](/ar/reference/session-management-compaction). ## ذو صلة -- [Session](/concepts/session) — إدارة الجلسات ودورة حياتها -- [Session Pruning](/concepts/session-pruning) — تقليم نتائج الأدوات -- [Context](/concepts/context) — كيف يُبنى السياق لأدوار الوكيل -- [Hooks](/automation/hooks) — hooks دورة حياة الضغط (`before_compaction` و`after_compaction`) +- [الجلسة](/ar/concepts/session) — إدارة الجلسات ودورة حياتها +- [تقليص الجلسة](/ar/concepts/session-pruning) — اقتطاع نتائج الأدوات +- [السياق](/ar/concepts/context) — كيفية بناء السياق لأدوار الوكيل +- [Hooks](/ar/automation/hooks) — خطافات دورة حياة الضغط (`before_compaction`, `after_compaction`) diff --git a/docs/ar/concepts/context-engine.md b/docs/ar/concepts/context-engine.md index 903293b05..6b7670676 100644 --- a/docs/ar/concepts/context-engine.md +++ b/docs/ar/concepts/context-engine.md @@ -3,71 +3,71 @@ read_when: - تريد فهم كيفية قيام OpenClaw بتجميع سياق النموذج - أنت تنتقل بين المحرك القديم ومحرك plugin - أنت تبني plugin لمحرك سياق -summary: 'محرك السياق: تجميع سياق قابل للتوصيل، والضغط، ودورة حياة الوكلاء الفرعيين' -title: Context Engine +summary: 'محرك السياق: تجميع سياق قابل للتوصيل، والضغط، ودورة حياة الوكيل الفرعي' +title: محرك السياق x-i18n: - generated_at: "2026-04-05T12:40:19Z" + generated_at: "2026-04-08T02:14:24Z" model: gpt-5.4 provider: openai - source_hash: 19fd8cbb0e953f58fd84637fc4ceefc65984312cf2896d338318bc8cf860e6d9 + source_hash: e8290ac73272eee275bce8e481ac7959b65386752caa68044d0c6f3e450acfb1 source_path: concepts/context-engine.md workflow: 15 --- -# Context Engine +# محرك السياق يتحكم **محرك السياق** في كيفية بناء OpenClaw لسياق النموذج لكل تشغيل. -فهو يحدد الرسائل التي يجب تضمينها، وكيفية تلخيص السجل الأقدم، وكيفية +ويقرر الرسائل التي يجب تضمينها، وكيفية تلخيص السجل الأقدم، وكيفية إدارة السياق عبر حدود الوكلاء الفرعيين. -يوفر OpenClaw محركًا مدمجًا باسم `legacy`. ويمكن لـ Plugins تسجيل -محركات بديلة تستبدل دورة حياة محرك السياق النشط. +يأتي OpenClaw مزودًا بمحرك `legacy` مدمج. ويمكن لـ plugins تسجيل +محركات بديلة تحل محل دورة حياة محرك السياق النشطة. ## البدء السريع -تحقق من المحرك النشط: +تحقق من المحرك النشط حاليًا: ```bash openclaw doctor -# أو افحص التكوين مباشرة: +# or inspect config directly: cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine' ``` ### تثبيت plugin لمحرك سياق -يتم تثبيت Plugins الخاصة بمحرك السياق مثل أي plugin آخر في OpenClaw. قم بالتثبيت -أولًا، ثم حدد المحرك في الـ slot: +يتم تثبيت plugins الخاصة بمحرك السياق مثل أي plugin أخرى في OpenClaw. ثبّت +plugin أولًا، ثم حدّد المحرك في slot: ```bash -# التثبيت من npm +# Install from npm openclaw plugins install @martian-engineering/lossless-claw -# أو التثبيت من مسار محلي (للتطوير) +# Or install from a local path (for development) openclaw plugins install -l ./my-context-engine ``` -ثم قم بتمكين plugin وحدده كمحرك نشط في التكوين: +بعد ذلك، فعّل plugin وحددها كمحرك نشط في الإعدادات: ```json5 // openclaw.json { plugins: { slots: { - contextEngine: "lossless-claw", // يجب أن يطابق معرّف المحرك المسجل في plugin + contextEngine: "lossless-claw", // must match the plugin's registered engine id }, entries: { "lossless-claw": { enabled: true, - // يذهب هنا التكوين الخاص بـ plugin (راجع وثائق plugin) + // Plugin-specific config goes here (see the plugin's docs) }, }, }, } ``` -أعد تشغيل gateway بعد التثبيت والتكوين. +أعد تشغيل البوابة بعد التثبيت والإعداد. -للعودة إلى المحرك المدمج، اضبط `contextEngine` على `"legacy"` (أو +للرجوع إلى المحرك المدمج، اضبط `contextEngine` على `"legacy"` (أو احذف المفتاح بالكامل — إذ إن `"legacy"` هو الافتراضي). ## كيف يعمل @@ -75,53 +75,55 @@ openclaw plugins install -l ./my-context-engine في كل مرة يشغّل فيها OpenClaw مطالبة نموذج، يشارك محرك السياق في أربع نقاط في دورة الحياة: -1. **Ingest** — يُستدعى عند إضافة رسالة جديدة إلى الجلسة. يمكن للمحرك +1. **الاستيعاب** — يُستدعى عند إضافة رسالة جديدة إلى الجلسة. ويمكن للمحرك تخزين الرسالة أو فهرستها في مخزن البيانات الخاص به. -2. **Assemble** — يُستدعى قبل كل تشغيل للنموذج. يعيد المحرك مجموعة - مرتبة من الرسائل (و`systemPromptAddition` اختياريًا) تتلاءم مع +2. **التجميع** — يُستدعى قبل كل تشغيل للنموذج. ويعيد المحرك مجموعة + مرتبة من الرسائل (و`systemPromptAddition` اختياري) تتناسب مع ميزانية الرموز. -3. **Compact** — يُستدعى عندما تمتلئ نافذة السياق، أو عندما يشغّل المستخدم - `/compact`. يقوم المحرك بتلخيص السجل الأقدم لتحرير مساحة. -4. **After turn** — يُستدعى بعد اكتمال التشغيل. يمكن للمحرك حفظ الحالة، +3. **الضغط** — يُستدعى عندما تمتلئ نافذة السياق، أو عندما يشغّل المستخدم + `/compact`. ويلخّص المحرك السجل الأقدم لتحرير مساحة. +4. **بعد الدور** — يُستدعى بعد اكتمال التشغيل. ويمكن للمحرك حفظ الحالة، أو تشغيل ضغط في الخلفية، أو تحديث الفهارس. ### دورة حياة الوكيل الفرعي (اختياري) -يستدعي OpenClaw حاليًا hook واحدة فقط لدورة حياة الوكيل الفرعي: +يستدعي OpenClaw حاليًا خطافًا واحدًا لدورة حياة الوكيل الفرعي: -- **onSubagentEnded** — تنظيف عند اكتمال جلسة وكيل فرعي أو عند إزالتها. +- **onSubagentEnded** — للتنظيف عند اكتمال جلسة وكيل فرعي أو اكتساحها. -تُعد hook ‏`prepareSubagentSpawn` جزءًا من الواجهة لاستخدام مستقبلي، لكن -وقت التشغيل لا يستدعيها بعد. +خطاف `prepareSubagentSpawn` جزء من الواجهة لاستخدام مستقبلي، لكن +بيئة التشغيل لا تستدعيه بعد. ### إضافة مطالبة النظام -يمكن لطريقة `assemble` أن تعيد سلسلة `systemPromptAddition`. يقوم OpenClaw -بإضافتها في مقدمة مطالبة النظام لذلك التشغيل. يتيح ذلك للمحركات حقن -إرشادات استرجاع ديناميكية، أو تعليمات استدعاء، أو تلميحات -مدركة للسياق من دون الحاجة إلى ملفات مساحة عمل ثابتة. +يمكن للطريقة `assemble` أن تعيد سلسلة `systemPromptAddition`. ويقوم OpenClaw +بإضافتها في بداية مطالبة النظام الخاصة بالتشغيل. ويتيح هذا للمحركات حقن +إرشادات استدعاء ديناميكية، أو تعليمات استرجاع، أو تلميحات +مدركة للسياق دون الحاجة إلى ملفات مساحة عمل ثابتة. ## المحرك القديم -يحافظ المحرك المدمج `legacy` على السلوك الأصلي لـ OpenClaw: +يحافظ المحرك `legacy` المدمج على السلوك الأصلي لـ OpenClaw: -- **Ingest**: لا عملية (إذ يتولى مدير الجلسة حفظ الرسائل مباشرة). -- **Assemble**: تمرير مباشر (يتولى المسار الحالي sanitize → validate → limit - في وقت التشغيل تجميع السياق). -- **Compact**: يفوض إلى ضغط التلخيص المدمج، والذي ينشئ - ملخصًا واحدًا للرسائل الأقدم ويُبقي الرسائل الحديثة كما هي. -- **After turn**: لا عملية. +- **الاستيعاب**: لا إجراء (يتولى مدير الجلسة حفظ الرسائل مباشرة). +- **التجميع**: تمرير مباشر (يتولى خط الأنابيب الحالي sanitize → validate → limit + في بيئة التشغيل تجميع السياق). +- **الضغط**: يفوّض إلى ضغط التلخيص المدمج، الذي ينشئ + ملخصًا واحدًا للرسائل الأقدم ويحافظ على الرسائل الحديثة كما هي. +- **بعد الدور**: لا إجراء. لا يسجل المحرك القديم أدوات ولا يوفّر `systemPromptAddition`. -عندما لا تكون `plugins.slots.contextEngine` مضبوطة (أو تكون مضبوطة على `"legacy"`)، +عندما لا يكون `plugins.slots.contextEngine` مضبوطًا (أو يكون مضبوطًا على `"legacy"`)، يُستخدم هذا المحرك تلقائيًا. ## محركات plugin -يمكن لأي plugin تسجيل محرك سياق باستخدام API الخاصة بـ plugin: +يمكن لـ plugin تسجيل محرك سياق باستخدام plugin API: ```ts +import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; + export default function register(api) { api.registerContextEngine("my-engine", () => ({ info: { @@ -135,12 +137,15 @@ export default function register(api) { return { ingested: true }; }, - async assemble({ sessionId, messages, tokenBudget }) { + async assemble({ sessionId, messages, tokenBudget, availableTools, citationsMode }) { // Return messages that fit the budget return { messages: buildContext(messages, tokenBudget), estimatedTokens: countTokens(messages), - systemPromptAddition: "Use lcm_grep to search history...", + systemPromptAddition: buildMemorySystemPromptAddition({ + availableTools: availableTools ?? new Set(), + citationsMode, + }), }; }, @@ -152,7 +157,7 @@ export default function register(api) { } ``` -ثم قم بتمكينه في التكوين: +ثم فعّله في الإعدادات: ```json5 { @@ -173,49 +178,49 @@ export default function register(api) { الأعضاء المطلوبة: -| العضو | النوع | الغرض | -| ------------------ | -------- | ------------------------------------------------------ | -| `info` | خاصية | معرّف المحرك واسمه وإصداره وما إذا كان يملك الضغط | -| `ingest(params)` | طريقة | تخزين رسالة واحدة | -| `assemble(params)` | طريقة | بناء سياق لتشغيل نموذج (تعيد `AssembleResult`) | -| `compact(params)` | طريقة | تلخيص/تقليل السياق | +| العضو | النوع | الغرض | +| ------------------ | -------- | -------------------------------------------------------- | +| `info` | خاصية | معرّف المحرك واسمه وإصداره وما إذا كان يملك الضغط | +| `ingest(params)` | طريقة | تخزين رسالة واحدة | +| `assemble(params)` | طريقة | بناء السياق لتشغيل نموذج (يعيد `AssembleResult`) | +| `compact(params)` | طريقة | تلخيص/تقليل السياق | تعيد `assemble` قيمة `AssembleResult` تحتوي على: -- `messages` — الرسائل المرتبة التي سيتم إرسالها إلى النموذج. -- `estimatedTokens` ‏(مطلوب، `number`) — تقدير المحرك لإجمالي - الرموز في السياق المجمع. يستخدم OpenClaw هذا لاتخاذ قرارات حدود الضغط - ولإعداد تقارير التشخيص. -- `systemPromptAddition` ‏(اختياري، `string`) — يُضاف في مقدمة مطالبة النظام. +- `messages` — الرسائل المرتبة التي ستُرسل إلى النموذج. +- `estimatedTokens` (مطلوب، `number`) — تقدير المحرك لإجمالي + الرموز في السياق المجمّع. ويستخدم OpenClaw هذا لاتخاذ قرارات + حدّ الضغط وللتقارير التشخيصية. +- `systemPromptAddition` (اختياري، `string`) — تُضاف في بداية مطالبة النظام. الأعضاء الاختيارية: -| العضو | النوع | الغرض | -| ----------------------------- | ------ | --------------------------------------------------------------------------------------------------------------- | -| `bootstrap(params)` | طريقة | تهيئة حالة المحرك لجلسة. تُستدعى مرة واحدة عندما يرى المحرك جلسة لأول مرة (مثل استيراد السجل). | -| `ingestBatch(params)` | طريقة | استيعاب دور مكتمل على شكل دفعة. تُستدعى بعد اكتمال تشغيل، مع جميع رسائل ذلك الدور دفعة واحدة. | -| `afterTurn(params)` | طريقة | أعمال ما بعد التشغيل في دورة الحياة (حفظ الحالة، تشغيل ضغط في الخلفية). | -| `prepareSubagentSpawn(params)`| طريقة | إعداد الحالة المشتركة لجلسة فرعية. | -| `onSubagentEnded(params)` | طريقة | التنظيف بعد انتهاء وكيل فرعي. | -| `dispose()` | طريقة | تحرير الموارد. تُستدعى أثناء إيقاف gateway أو إعادة تحميل plugin — وليس لكل جلسة. | +| العضو | النوع | الغرض | +| ------------------------------ | ------ | --------------------------------------------------------------------------------------------------------------- | +| `bootstrap(params)` | طريقة | تهيئة حالة المحرك لجلسة. تُستدعى مرة واحدة عندما يرى المحرك جلسة لأول مرة (مثل استيراد السجل). | +| `ingestBatch(params)` | طريقة | استيعاب دور مكتمل كدفعة. تُستدعى بعد اكتمال التشغيل، مع جميع رسائل ذلك الدور دفعة واحدة. | +| `afterTurn(params)` | طريقة | أعمال دورة الحياة بعد التشغيل (حفظ الحالة، تشغيل ضغط في الخلفية). | +| `prepareSubagentSpawn(params)` | طريقة | إعداد حالة مشتركة لجلسة فرعية. | +| `onSubagentEnded(params)` | طريقة | التنظيف بعد انتهاء وكيل فرعي. | +| `dispose()` | طريقة | تحرير الموارد. تُستدعى أثناء إيقاف تشغيل البوابة أو إعادة تحميل plugin — وليس لكل جلسة. | ### ownsCompaction -يتحكم `ownsCompaction` فيما إذا كان الضغط التلقائي المدمج داخل المحاولة في Pi +يتحكم `ownsCompaction` فيما إذا كان الضغط التلقائي المدمج أثناء المحاولة في Pi يبقى مفعّلًا أثناء التشغيل: -- `true` — يمتلك المحرك سلوك الضغط. يعطّل OpenClaw الضغط التلقائي المدمج في Pi +- `true` — يملك المحرك سلوك الضغط. يعطّل OpenClaw الضغط التلقائي المدمج في Pi لذلك التشغيل، ويصبح تنفيذ `compact()` الخاص بالمحرك مسؤولًا عن `/compact`، - وضغط استعادة تجاوز السعة، وأي ضغط استباقي + وضغط الاسترداد من تجاوز السعة، وأي ضغط استباقي يريد تنفيذه في `afterTurn()`. -- `false` أو غير معيّن — قد يستمر الضغط التلقائي المدمج في Pi أثناء - تنفيذ المطالبة، لكن تظل طريقة `compact()` الخاصة بالمحرك النشط تُستدعى - من أجل `/compact` واستعادة تجاوز السعة. +- `false` أو غير مضبوط — قد يستمر تشغيل الضغط التلقائي المدمج في Pi أثناء + تنفيذ المطالبة، لكن تظل طريقة `compact()` الخاصة بالمحرك النشط + مستدعاة من أجل `/compact` والاسترداد من تجاوز السعة. -لا تعني `ownsCompaction: false` أن OpenClaw يعود تلقائيًا -إلى مسار الضغط الخاص بالمحرك القديم. +لا يعني `ownsCompaction: false` أن OpenClaw يعود تلقائيًا إلى +مسار الضغط الخاص بالمحرك القديم. -وهذا يعني وجود نمطين صالحين لـ plugin: +وهذا يعني أن هناك نمطين صالحين لـ plugin: - **وضع التملك** — نفّذ خوارزمية الضغط الخاصة بك واضبط `ownsCompaction: true`. @@ -223,58 +228,65 @@ export default function register(api) { `delegateCompactionToRuntime(...)` من `openclaw/plugin-sdk/core` لاستخدام سلوك الضغط المدمج في OpenClaw. -إن `compact()` التي لا تقوم بأي شيء غير آمنة لمحرك نشط غير مالك لأنها -تعطّل المسار العادي لـ `/compact` وضغط استعادة تجاوز السعة لذلك الـ engine slot. +إن `compact()` التي لا تنفّذ أي شيء غير آمنة لمحرك نشط غير مالك لأن ذلك +يعطّل مسار `/compact` العادي ومسار ضغط الاسترداد من تجاوز السعة +لـ slot ذلك المحرك. -## مرجع التكوين +## مرجع الإعدادات ```json5 { plugins: { slots: { - // حدد محرك السياق النشط. الافتراضي: "legacy". - // اضبطه على معرّف plugin لاستخدام محرك plugin. + // Select the active context engine. Default: "legacy". + // Set to a plugin id to use a plugin engine. contextEngine: "legacy", }, }, } ``` -يكون الـ slot حصريًا في وقت التشغيل — لا يتم -حل سوى محرك سياق مسجل واحد لتشغيل معيّن أو عملية ضغط. أما بقية -Plugins من النوع `kind: "context-engine"` والمفعلة فيمكنها أن تُحمّل وتنفّذ -شفرة التسجيل الخاصة بها؛ إذ يحدد `plugins.slots.contextEngine` فقط أي معرّف محرك مسجل -يحلّه OpenClaw عندما يحتاج إلى محرك سياق. +يكون الـ slot حصريًا في وقت التشغيل — إذ لا يُحل سوى محرك سياق مسجل واحد +لتشغيل أو عملية ضغط معينة. ويمكن لبقية plugins المفعّلة +من النوع `kind: "context-engine"` أن تُحمّل وتنفّذ +شيفرة التسجيل الخاصة بها؛ إذ يحدد `plugins.slots.contextEngine` فقط +معرّف المحرك المسجل الذي يحله OpenClaw عندما يحتاج إلى محرك سياق. ## العلاقة مع الضغط والذاكرة -- **الضغط** هو إحدى مسؤوليات محرك السياق. يفوض المحرك القديم +- **الضغط** هو إحدى مسؤوليات محرك السياق. يفوّض المحرك القديم إلى التلخيص المدمج في OpenClaw. ويمكن لمحركات plugin تنفيذ - أي استراتيجية ضغط (ملخصات DAG، أو استدعاء vector، وما إلى ذلك). -- **Plugins الذاكرة** (`plugins.slots.memory`) منفصلة عن محركات السياق. - توفر Plugins الذاكرة البحث/الاستدعاء؛ بينما تتحكم محركات السياق فيما - يراه النموذج. ويمكنهما العمل معًا — فقد يستخدم محرك السياق بيانات - plugin الذاكرة أثناء التجميع. -- يظل **تشذيب الجلسة** (قص نتائج الأدوات القديمة في الذاكرة) - يعمل بغض النظر عن محرك السياق النشط. + أي استراتيجية ضغط (ملخصات DAG، أو استرجاع متجهي، وما إلى ذلك). +- **plugins الذاكرة** (`plugins.slots.memory`) منفصلة عن محركات السياق. + توفّر plugins الذاكرة البحث/الاسترجاع؛ بينما تتحكم محركات السياق فيما + يراه النموذج. ويمكنهما العمل معًا — فقد يستخدم محرك سياق + بيانات plugin الذاكرة أثناء التجميع. ويُفضّل أن تستخدم محركات plugin التي تريد + مسار مطالبة الذاكرة النشط `buildMemorySystemPromptAddition(...)` من + `openclaw/plugin-sdk/core`، إذ يحوّل مقاطع مطالبة الذاكرة النشطة + إلى `systemPromptAddition` جاهزة للإضافة في البداية. وإذا احتاج المحرك إلى + تحكم على مستوى أدنى، فلا يزال بإمكانه سحب الأسطر الخام من + `openclaw/plugin-sdk/memory-host-core` عبر + `buildActiveMemoryPromptSection(...)`. +- **تهذيب الجلسة** (قص نتائج الأدوات القديمة داخل الذاكرة) يظل يعمل + بغض النظر عن محرك السياق النشط. ## نصائح -- استخدم `openclaw doctor` للتحقق من أن محركك يتم تحميله بشكل صحيح. -- إذا قمت بالتبديل بين المحركات، فستستمر الجلسات الحالية بسجلها الحالي. +- استخدم `openclaw doctor` للتحقق من أن محركك يُحمَّل بشكل صحيح. +- إذا كنت تبدّل بين المحركات، فستستمر الجلسات الحالية بسجلها الحالي. وسيتولى المحرك الجديد التشغيلات المستقبلية. -- يتم تسجيل أخطاء المحرك وعرضها في التشخيصات. إذا فشل محرك plugin - في التسجيل أو تعذر حل معرّف المحرك المحدد، فلن يعود OpenClaw تلقائيًا؛ - بل ستفشل التشغيلات حتى تصلح plugin أو +- تُسجّل أخطاء المحرك وتظهر في التشخيصات. وإذا فشل محرك plugin + في التسجيل أو تعذر حل معرّف المحرك المحدد، فلن يعود OpenClaw + تلقائيًا؛ بل ستفشل التشغيلات حتى تصلح plugin أو تعيد `plugins.slots.contextEngine` إلى `"legacy"`. - لأغراض التطوير، استخدم `openclaw plugins install -l ./my-engine` لربط - دليل plugin محلي من دون نسخه. + دليل plugin محليًا من دون نسخه. -راجع أيضًا: [الضغط](/concepts/compaction)، [السياق](/concepts/context)، -[Plugins](/tools/plugin)، [بيان plugin](/plugins/manifest). +راجع أيضًا: [الضغط](/ar/concepts/compaction)، [السياق](/ar/concepts/context), +[Plugins](/ar/tools/plugin)، [بيان plugin](/ar/plugins/manifest). ## ذو صلة -- [السياق](/concepts/context) — كيفية بناء السياق لأدوار الوكيل -- [بنية plugin](/plugins/architecture) — تسجيل Plugins لمحركات السياق -- [الضغط](/concepts/compaction) — تلخيص المحادثات الطويلة +- [السياق](/ar/concepts/context) — كيف يُبنى السياق لأدوار الوكيل +- [معمارية Plugin](/ar/plugins/architecture) — تسجيل plugins لمحرك السياق +- [الضغط](/ar/concepts/compaction) — تلخيص المحادثات الطويلة diff --git a/docs/ar/concepts/model-providers.md b/docs/ar/concepts/model-providers.md index 5113eddfe..a75ebcf2c 100644 --- a/docs/ar/concepts/model-providers.md +++ b/docs/ar/concepts/model-providers.md @@ -1,266 +1,266 @@ --- read_when: - - تحتاج إلى مرجع لإعداد النماذج مزوّدًا بمزوّد - - تريد إعدادات نموذجية أو أوامر تهيئة عبر CLI لمزوّدي النماذج -summary: نظرة عامة على مزوّدي النماذج مع إعدادات نموذجية + تدفقات CLI -title: مزوّدو النماذج + - تحتاج إلى مرجع لإعداد النماذج لكل موفر على حدة + - تريد إعدادات تكوين نموذجية أو أوامر تهيئة CLI لموفري النماذج +summary: نظرة عامة على موفري النماذج مع إعدادات تكوين نموذجية + تدفقات CLI +title: موفرو النماذج x-i18n: - generated_at: "2026-04-07T07:18:06Z" + generated_at: "2026-04-08T02:16:27Z" model: gpt-5.4 provider: openai - source_hash: a9c1f7f8cf09b6047a64189f7440811aafc93d01335f76969afd387cc54c7ab5 + source_hash: 26b36a2bc19a28a7ef39aa8e81a0050fea1d452ac4969122e5cdf8755e690258 source_path: concepts/model-providers.md workflow: 15 --- -# مزوّدو النماذج +# موفرو النماذج -تغطي هذه الصفحة **مزوّدي LLM/النماذج** (وليس قنوات الدردشة مثل WhatsApp/Telegram). -للاطلاع على قواعد اختيار النموذج، راجع [/concepts/models](/ar/concepts/models). +تغطي هذه الصفحة **موفري LLM/النماذج** (وليس قنوات الدردشة مثل WhatsApp/Telegram). +للاطلاع على قواعد اختيار النماذج، راجع [/concepts/models](/ar/concepts/models). ## قواعد سريعة - تستخدم مراجع النماذج الصيغة `provider/model` (مثال: `opencode/claude-opus-4-6`). -- إذا قمت بتعيين `agents.defaults.models`، فسيصبح قائمة السماح. -- أدوات CLI المساعدة: `openclaw onboard` و `openclaw models list` و `openclaw models set `. -- قواعد وقت التشغيل الاحتياطية، وفحوصات التهدئة، واستمرارية تجاوزات الجلسة موثقة - في [/concepts/model-failover](/ar/concepts/model-failover). +- إذا قمت بتعيين `agents.defaults.models`، فستصبح هي قائمة السماح. +- مساعدات CLI: ‏`openclaw onboard`، ‏`openclaw models list`، ‏`openclaw models set `. +- قواعد وقت التشغيل الاحتياطية، ومجسات التهدئة، واستمرارية تجاوز الجلسة + موثقة في [/concepts/model-failover](/ar/concepts/model-failover). - `models.providers.*.models[].contextWindow` هي بيانات تعريف أصلية للنموذج؛ - أما `models.providers.*.models[].contextTokens` فهو الحد الفعّال في وقت التشغيل. -- يمكن لإضافات المزوّدين حقن فهارس النماذج عبر `registerProvider({ catalog })`; - ويقوم OpenClaw بدمج هذا الخرج في `models.providers` قبل كتابة + و`models.providers.*.models[].contextTokens` هو الحد الفعّال في وقت التشغيل. +- يمكن لإضافات الموفر حقن فهارس النماذج عبر `registerProvider({ catalog })`؛ + ويقوم OpenClaw بدمج هذا الناتج في `models.providers` قبل كتابة `models.json`. -- يمكن لبيانات تعريف المزوّدين التصريحية الإعلان عن `providerAuthEnvVars` بحيث لا تحتاج - فحوصات المصادقة العامة المعتمدة على متغيرات البيئة إلى تحميل وقت تشغيل الإضافة. أصبحت - خريطة متغيرات البيئة الأساسية المتبقية الآن فقط للمزوّدين غير المعتمدين على الإضافات/الأساسيين - وبعض حالات أسبقية عامة، مثل تهيئة Anthropic التي تبدأ بمفتاح API. -- يمكن لإضافات المزوّدين أيضًا امتلاك سلوك وقت تشغيل المزوّد عبر - `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, - `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, - `resolveSyntheticAuth`, `shouldDeferSyntheticProfileAuth`, - `resolveDynamicModel`, `prepareDynamicModel`, - `normalizeResolvedModel`, `contributeResolvedModelCompat`, - `capabilities`, `normalizeToolSchemas`, - `inspectToolSchemas`, `resolveReasoningOutputMode`, - `prepareExtraParams`, `createStreamFn`, `wrapStreamFn`, - `resolveTransportTurnState`, `resolveWebSocketSessionPolicy`, - `createEmbeddingProvider`, `formatApiKey`, `refreshOAuth`, - `buildAuthDoctorHint`, - `matchesContextOverflowError`, `classifyFailoverReason`, - `isCacheTtlEligible`, `buildMissingAuthMessage`, `suppressBuiltInModel`, - `augmentModelCatalog`, `isBinaryThinking`, `supportsXHighThinking`, - `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`, - `prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`, and - `onModelSelected`. -- ملاحظة: `capabilities` الخاصة بوقت تشغيل المزوّد هي بيانات تعريف مشتركة للمشغّل (عائلة المزوّد، - وخصائص النصوص/الأدوات، وتلميحات النقل/التخزين المؤقت). وهي ليست - نفسها [لنموذج القدرات العامة](/ar/plugins/architecture#public-capability-model) - الذي يصف ما الذي تسجله الإضافة (استدلال نصي، كلام، إلخ). +- يمكن لبيانات تعريف الموفر أن تصرح بـ `providerAuthEnvVars` بحيث لا تحتاج + مجسات المصادقة العامة المعتمدة على متغيرات البيئة إلى تحميل وقت تشغيل الإضافة. أما خريطة + متغيرات البيئة الأساسية المتبقية فهي الآن فقط لموفري النواة/غير الإضافات + وبعض حالات الأسبقية العامة مثل تهيئة Anthropic مع تفضيل مفتاح API أولًا. +- يمكن لإضافات الموفر أيضًا امتلاك سلوك وقت تشغيل الموفر عبر + `normalizeModelId`، ‏`normalizeTransport`، ‏`normalizeConfig`، + ‏`applyNativeStreamingUsageCompat`، ‏`resolveConfigApiKey`، + ‏`resolveSyntheticAuth`، ‏`shouldDeferSyntheticProfileAuth`، + ‏`resolveDynamicModel`، ‏`prepareDynamicModel`، + ‏`normalizeResolvedModel`، ‏`contributeResolvedModelCompat`، + ‏`capabilities`، ‏`normalizeToolSchemas`، + ‏`inspectToolSchemas`، ‏`resolveReasoningOutputMode`، + ‏`prepareExtraParams`، ‏`createStreamFn`، ‏`wrapStreamFn`، + ‏`resolveTransportTurnState`، ‏`resolveWebSocketSessionPolicy`، + ‏`createEmbeddingProvider`، ‏`formatApiKey`، ‏`refreshOAuth`، + ‏`buildAuthDoctorHint`، + ‏`matchesContextOverflowError`، ‏`classifyFailoverReason`، + ‏`isCacheTtlEligible`، ‏`buildMissingAuthMessage`، ‏`suppressBuiltInModel`، + ‏`augmentModelCatalog`، ‏`isBinaryThinking`، ‏`supportsXHighThinking`، + ‏`resolveDefaultThinkingLevel`، ‏`applyConfigDefaults`، ‏`isModernModelRef`، + ‏`prepareRuntimeAuth`، ‏`resolveUsageAuth`، ‏`fetchUsageSnapshot`، و + ‏`onModelSelected`. +- ملاحظة: ‏`capabilities` في وقت تشغيل الموفر هي بيانات تعريف مشتركة للمشغّل (عائلة الموفر، وخصائص النصوص والأدوات، وتلميحات النقل/التخزين المؤقت). وهي ليست + نفسها [نموذج القدرات العام](/ar/plugins/architecture#public-capability-model) + الذي يصف ما الذي تسجله الإضافة (الاستدلال النصي، والكلام، وما إلى ذلك). -## سلوك المزوّد المملوك للإضافة +## السلوك المملوك لإضافة الموفر -يمكن لإضافات المزوّدين الآن امتلاك معظم المنطق الخاص بكل مزوّد، بينما يحافظ OpenClaw -على حلقة الاستدلال العامة. +يمكن لإضافات الموفر الآن امتلاك معظم المنطق الخاص بالموفر بينما يحتفظ OpenClaw +بحلقة الاستدلال العامة. التقسيم المعتاد: -- `auth[].run` / `auth[].runNonInteractive`: يمتلك المزوّد تدفقات التهيئة/تسجيل الدخول - الخاصة بـ `openclaw onboard` و `openclaw models auth` والإعداد غير التفاعلي -- `wizard.setup` / `wizard.modelPicker`: يمتلك المزوّد تسميات خيارات المصادقة، - والأسماء المستعارة القديمة، وتلميحات قائمة السماح أثناء التهيئة، وإدخالات - الإعداد في منتقيات التهيئة/النموذج -- `catalog`: يظهر المزوّد في `models.providers` -- `normalizeModelId`: يقوم المزوّد بتطبيع معرّفات النماذج القديمة/المعاينة قبل - البحث أو جعلها معيارية -- `normalizeTransport`: يقوم المزوّد بتطبيع `api` / `baseUrl` الخاصة بعائلة النقل - قبل التجميع العام للنموذج؛ يتحقق OpenClaw أولًا من المزوّد المطابق، - ثم من إضافات المزوّد الأخرى القادرة على الخطافات حتى تغيّر إحداها - النقل فعليًا -- `normalizeConfig`: يقوم المزوّد بتطبيع إعدادات `models.providers.` قبل - أن يستخدمها وقت التشغيل؛ يتحقق OpenClaw أولًا من المزوّد المطابق، ثم من إضافات المزوّد - الأخرى القادرة على الخطافات حتى تغيّر إحداها الإعدادات فعليًا. إذا لم - تعد كتابة الإعدادات أي خطافات مزوّد، فإن مساعدات Google-family المضمّنة - ستظل تطبّع إدخالات مزوّدي Google المدعومة. -- `applyNativeStreamingUsageCompat`: يطبّق المزوّد إعادة كتابة توافق استخدام البث الأصلي المعتمدة على نقطة النهاية لمزوّدي الإعدادات -- `resolveConfigApiKey`: يحل المزوّد مصادقة علامات البيئة لمزوّدي الإعدادات - من دون فرض تحميل مصادقة وقت التشغيل الكاملة. يمتلك `amazon-bedrock` أيضًا - محلّلًا مضمّنًا لعلامات بيئة AWS هنا، رغم أن مصادقة وقت تشغيل Bedrock تستخدم +- `auth[].run` / `auth[].runNonInteractive`: يمتلك الموفر تدفقات التهيئة/تسجيل الدخول + الخاصة بـ `openclaw onboard` و`openclaw models auth` والإعداد بدون واجهة +- `wizard.setup` / `wizard.modelPicker`: يمتلك الموفر تسميات خيارات المصادقة، + والأسماء المستعارة القديمة، وتلميحات قائمة السماح الخاصة بالتهيئة، وإدخالات الإعداد في أدوات اختيار التهيئة/النموذج +- `catalog`: يظهر الموفر في `models.providers` +- `normalizeModelId`: يقوم الموفر بتطبيع معرّفات النماذج القديمة/المعاينة قبل + البحث أو تحويلها إلى الشكل القياسي +- `normalizeTransport`: يقوم الموفر بتطبيع `api` / `baseUrl` الخاصة بعائلة النقل + قبل التجميع العام للنموذج؛ ويتحقق OpenClaw من الموفر المطابق أولًا، + ثم من إضافات الموفر الأخرى القادرة على الخطافات حتى تغيّر إحداها + النقل فعلًا +- `normalizeConfig`: يقوم الموفر بتطبيع إعداد `models.providers.` قبل + أن يستخدمه وقت التشغيل؛ ويتحقق OpenClaw من الموفر المطابق أولًا، ثم من + إضافات الموفر الأخرى القادرة على الخطافات حتى تغيّر إحداها الإعداد فعلًا. إذا لم + تعِد أي خطافة موفر كتابة الإعداد، فإن مساعدات Google المجمعة للعائلة ما تزال + تطبع إدخالات موفر Google المدعومة. +- `applyNativeStreamingUsageCompat`: يطبق الموفر إعادة كتابة توافق استخدام البث الأصلية المدفوعة بنقطة النهاية لموفري الإعداد +- `resolveConfigApiKey`: يقوم الموفر بحل مصادقة علامة البيئة لموفري الإعداد + بدون فرض تحميل كامل لمصادقة وقت التشغيل. ويحتوي `amazon-bedrock` أيضًا على + محلل مدمج لعلامات بيئة AWS هنا، رغم أن مصادقة وقت تشغيل Bedrock تستخدم سلسلة AWS SDK الافتراضية. -- `resolveSyntheticAuth`: يمكن للمزوّد عرض توفّر المصادقة المحلية/المستضافة ذاتيًا أو - المصادقة الأخرى المعتمدة على الإعدادات دون تخزين أسرار نصية صريحة -- `shouldDeferSyntheticProfileAuth`: يمكن للمزوّد تعليم عناصر نائبة محفوظة لملفات تعريف تركيبية - على أنها أقل أسبقية من المصادقة المعتمدة على البيئة/الإعدادات -- `resolveDynamicModel`: يقبل المزوّد معرّفات نماذج غير موجودة بعد في +- `resolveSyntheticAuth`: يمكن للموفر إتاحة توفر المصادقة المحلية/المستضافة ذاتيًا أو غيرها من + المصادقات المعتمدة على الإعداد بدون حفظ أسرار نصية صريحة +- `shouldDeferSyntheticProfileAuth`: يمكن للموفر وسم عناصر نائبة للمِلَفات التعريفية الاصطناعية المخزنة + على أنها أقل أسبقية من المصادقة المستندة إلى البيئة/الإعداد +- `resolveDynamicModel`: يقبل الموفر معرّفات نماذج غير موجودة بعد في الفهرس الثابت المحلي -- `prepareDynamicModel`: يحتاج المزوّد إلى تحديث البيانات التعريفية قبل إعادة محاولة - الحل الديناميكي -- `normalizeResolvedModel`: يحتاج المزوّد إلى إعادة كتابة النقل أو عنوان URL الأساسي -- `contributeResolvedModelCompat`: يساهم المزوّد بعلامات توافق لنماذجه - التابعة للمورّد حتى عندما تصل عبر نقل متوافق آخر -- `capabilities`: ينشر المزوّد خصائص النصوص/الأدوات/عائلة المزوّد -- `normalizeToolSchemas`: ينظف المزوّد مخططات الأدوات قبل أن يراها - المشغّل المضمّن -- `inspectToolSchemas`: يعرض المزوّد تحذيرات مخطط خاصة بالنقل +- `prepareDynamicModel`: يحتاج الموفر إلى تحديث البيانات التعريفية قبل إعادة + محاولة الحل الديناميكي +- `normalizeResolvedModel`: يحتاج الموفر إلى إعادة كتابة النقل أو عنوان URL الأساسي +- `contributeResolvedModelCompat`: يضيف الموفر علامات توافق لنماذجه + الخاصة بالمورّد حتى عندما تصل عبر نقل متوافق آخر +- `capabilities`: ينشر الموفر خصائص quirks للنصوص/الأدوات/عائلة الموفر +- `normalizeToolSchemas`: ينظف الموفر مخططات الأدوات قبل أن يراها + المشغّل المضمن +- `inspectToolSchemas`: يعرض الموفر تحذيرات المخططات الخاصة بالنقل بعد التطبيع -- `resolveReasoningOutputMode`: يختار المزوّد عقود مخرجات التفكير الأصلية أو الموسومة -- `prepareExtraParams`: يضع المزوّد قيمًا افتراضية أو يطبّع معلمات الطلب لكل نموذج -- `createStreamFn`: يستبدل المزوّد مسار البث المعتاد بنقل مخصص بالكامل -- `wrapStreamFn`: يطبّق المزوّد أغلفة توافق لروؤس/جسم/نموذج الطلب -- `resolveTransportTurnState`: يوفّر المزوّد روؤسًا أو بيانات تعريفية - أصلية للنقل لكل دور -- `resolveWebSocketSessionPolicy`: يوفّر المزوّد روؤس جلسة WebSocket أصلية - أو سياسة تهدئة الجلسة -- `createEmbeddingProvider`: يمتلك المزوّد سلوك تضمين الذاكرة عندما - يكون من الأنسب أن يكون داخل إضافة المزوّد بدلًا من لوحة تحويل التضمين الأساسية -- `formatApiKey`: ينسّق المزوّد ملفات تعريف المصادقة المخزنة إلى - سلسلة `apiKey` الخاصة بوقت التشغيل التي يتوقعها النقل -- `refreshOAuth`: يمتلك المزوّد تحديث OAuth عندما لا تكون أدوات التحديث - المشتركة `pi-ai` كافية -- `buildAuthDoctorHint`: يضيف المزوّد إرشادات إصلاح عندما يفشل تحديث OAuth -- `matchesContextOverflowError`: يتعرّف المزوّد على - أخطاء تجاوز نافذة السياق الخاصة بالمزوّد التي قد تفوتها الإرشادات العامة -- `classifyFailoverReason`: يربط المزوّد أخطاء النقل/API الخام الخاصة بالمزوّد - بأسباب التحويل الاحتياطي مثل حد المعدل أو زيادة الحمل -- `isCacheTtlEligible`: يحدد المزوّد معرّفات النماذج upstream التي تدعم مدة صلاحية التخزين المؤقت للمطالبات -- `buildMissingAuthMessage`: يستبدل المزوّد خطأ مخزن المصادقة العام - بتلميح استرداد خاص بالمزوّد -- `suppressBuiltInModel`: يخفي المزوّد الصفوف upstream القديمة ويمكنه إرجاع +- `resolveReasoningOutputMode`: يختار الموفر بين عقود إخراج الاستدلال + الأصلية أو الموسومة +- `prepareExtraParams`: يضبط الموفر افتراضيًا أو يطبع معاملات الطلب لكل نموذج +- `createStreamFn`: يستبدل الموفر مسار البث العادي بنقل + مخصص بالكامل +- `wrapStreamFn`: يطبّق الموفر أغلفة توافق الطلب/الجسم/النموذج +- `resolveTransportTurnState`: يوفّر الموفر رؤوسًا أو بيانات تعريف + خاصة بكل دورة للنقل الأصلي +- `resolveWebSocketSessionPolicy`: يوفّر الموفر رؤوس جلسة WebSocket أصلية + أو سياسة تبريد الجلسة +- `createEmbeddingProvider`: يمتلك الموفر سلوك تضمين الذاكرة عندما + يكون من الأنسب أن يكون ضمن إضافة الموفر بدلًا من لوحة توزيع التضمين الأساسية +- `formatApiKey`: يقوم الموفر بتنسيق ملفات تعريف المصادقة المخزنة إلى سلسلة + `apiKey` الخاصة بوقت التشغيل كما يتوقعها النقل +- `refreshOAuth`: يمتلك الموفر تحديث OAuth عندما لا تكون مجددات + `pi-ai` المشتركة كافية +- `buildAuthDoctorHint`: يضيف الموفر إرشادات إصلاح عندما يفشل تحديث OAuth +- `matchesContextOverflowError`: يتعرف الموفر على أخطاء تجاوز نافذة السياق الخاصة بالموفر + التي قد تفوتها الاستدلالات العامة +- `classifyFailoverReason`: يربط الموفر أخطاء النقل/API الخام الخاصة بالموفر + بأسباب التحويل الاحتياطي مثل حد المعدل أو التحميل الزائد +- `isCacheTtlEligible`: يحدد الموفر أي معرّفات النماذج لدى المصدر تدعم مدة صلاحية التخزين المؤقت للمطالبة +- `buildMissingAuthMessage`: يستبدل الموفر خطأ مخزن المصادقة العام + بتلميح استعادة خاص بالموفر +- `suppressBuiltInModel`: يخفي الموفر الصفوف القديمة لدى المصدر ويمكنه إرجاع خطأ مملوكًا للمورّد عند فشل الحل المباشر -- `augmentModelCatalog`: يضيف المزوّد صفوفًا تركيبية/نهائية إلى الفهرس بعد - الاكتشاف ودمج الإعدادات -- `isBinaryThinking`: يمتلك المزوّد تجربة استخدام التفكير الثنائي تشغيل/إيقاف -- `supportsXHighThinking`: يضمّن المزوّد نماذج محددة ضمن `xhigh` -- `resolveDefaultThinkingLevel`: يمتلك المزوّد سياسة `/think` الافتراضية - لعائلة نماذج -- `applyConfigDefaults`: يطبّق المزوّد قيمًا افتراضية عامة خاصة بالمزوّد - أثناء إنشاء الإعدادات استنادًا إلى وضع المصادقة أو البيئة أو عائلة النموذج -- `isModernModelRef`: يمتلك المزوّد مطابقة النموذج المفضّل في الوضعين المباشر/الاختباري -- `prepareRuntimeAuth`: يحوّل المزوّد بيانات الاعتماد المهيأة إلى رمز وقت تشغيل +- `augmentModelCatalog`: يضيف الموفر صفوف فهرس اصطناعية/نهائية بعد + الاكتشاف ودمج الإعداد +- `isBinaryThinking`: يمتلك الموفر تجربة استخدام التفكير الثنائي تشغيل/إيقاف +- `supportsXHighThinking`: يفعّل الموفر `xhigh` لنماذج محددة +- `resolveDefaultThinkingLevel`: يمتلك الموفر سياسة `/think` الافتراضية لعائلة + النماذج +- `applyConfigDefaults`: يطبق الموفر إعدادات افتراضية عامة خاصة بالموفر + أثناء إنشاء الإعداد استنادًا إلى وضع المصادقة أو البيئة أو عائلة النموذج +- `isModernModelRef`: يمتلك الموفر مطابقة النموذج المفضل للبث الحي/الاختبار الدخاني +- `prepareRuntimeAuth`: يحول الموفر بيانات الاعتماد المكوّنة إلى رمز وقت تشغيل قصير العمر -- `resolveUsageAuth`: يحل المزوّد بيانات اعتماد الاستخدام/الحصص الخاصة بـ `/usage` - والأسطح ذات الصلة للحالة/التقارير -- `fetchUsageSnapshot`: يمتلك المزوّد جلب/تحليل نقطة نهاية الاستخدام بينما - يظل الأساس مسؤولًا عن غلاف الملخص والتنسيق -- `onModelSelected`: ينفّذ المزوّد آثارًا جانبية بعد الاختيار مثل - القياس عن بُعد أو مسك دفاتر الجلسات المملوك للمزوّد +- `resolveUsageAuth`: يحل الموفر بيانات اعتماد الاستخدام/الحصة لأجل `/usage` + والواجهات ذات الصلة بالحالة/التقارير +- `fetchUsageSnapshot`: يمتلك الموفر جلب/تحليل نقطة نهاية الاستخدام بينما + لا تزال النواة تمتلك الغلاف والتهيئة الملخصة +- `onModelSelected`: يشغّل الموفر آثارًا جانبية بعد الاختيار مثل + telemetry أو حفظ الجلسة المملوك للموفر -الأمثلة المضمّنة الحالية: +أمثلة الحِزم الحالية: -- `anthropic`: توافق احتياطي مستقبلي لـ Claude 4.6، وتلميحات إصلاح المصادقة، وجلب - نقطة نهاية الاستخدام، وبيانات تعريف مدة صلاحية التخزين المؤقت/عائلة المزوّد، وقيم افتراضية عامة - للإعدادات مدركة للمصادقة +- `anthropic`: بديل توافق أمامي لـ Claude 4.6، وتلميحات إصلاح المصادقة، وجلب + نقطة نهاية الاستخدام، وبيانات تعريف TTL التخزين المؤقت/عائلة الموفر، وإعدادات + افتراضية عامة تراعي المصادقة - `amazon-bedrock`: مطابقة تجاوز السياق وتصنيف أسباب - التحويل الاحتياطي الخاصتين بـ Bedrock للأخطاء الخاصة بالاختناق/عدم الجاهزية، بالإضافة إلى - عائلة إعادة التشغيل المشتركة `anthropic-by-model` لحراس سياسة إعادة التشغيل الخاصة بـ Claude فقط + التحويل الاحتياطي المملوكان للموفر لأخطاء Bedrock الخاصة بالخنق/عدم الجاهزية، إضافة إلى + عائلة الإعادة المشتركة `anthropic-by-model` لحمايات سياسة الإعادة الخاصة بـ Claude فقط على حركة Anthropic -- `anthropic-vertex`: حراس سياسة إعادة التشغيل الخاصة بـ Claude فقط على حركة - رسائل Anthropic -- `openrouter`: معرّفات نماذج تمريرية، وأغلفة طلبات، وتلميحات قدرات المزوّد، - وتنظيف توقيعات أفكار Gemini على حركة Gemini الوكيلة، وحقن التفكير الوكيلي - عبر عائلة البث `openrouter-thinking`، وتمرير بيانات التوجيه - التعريفية، وسياسة مدة صلاحية التخزين المؤقت -- `github-copilot`: التهيئة/تسجيل الدخول بالجهاز، والتوافق الاحتياطي المستقبلي للنموذج، - وتلميحات نصوص تفكير Claude، وتبادل رمز وقت التشغيل، وجلب نقطة نهاية - الاستخدام -- `openai`: توافق احتياطي مستقبلي لـ GPT-5.4، وتطبيع - نقل OpenAI المباشر، وتلميحات فقدان المصادقة المدركة لـ Codex، وقمع Spark، - وصفوف فهرس OpenAI/Codex التركيبية، وسياسة التفكير/النموذج المباشر، وتطبيع - الأسماء المستعارة لرموز الاستخدام (`input` / `output` وعائلتي `prompt` / `completion`)، و - عائلة البث المشتركة `openai-responses-defaults` لأغلفة OpenAI/Codex الأصلية، - وبيانات تعريف عائلة المزوّد، وتسجيل مزوّد - توليد الصور المضمّن لـ `gpt-image-1`، وتسجيل مزوّد - توليد الفيديو المضمّن لـ `sora-2` -- `google` و `google-gemini-cli`: توافق احتياطي مستقبلي لـ Gemini 3.1، - والتحقق الأصلي من إعادة تشغيل Gemini، وتنظيف إعادة التشغيل عند التمهيد، ووضع - مخرجات التفكير الموسومة، ومطابقة النماذج الحديثة، وتسجيل مزوّد - توليد الصور المضمّن لنماذج معاينة الصور Gemini، وتسجيل - مزوّد توليد الفيديو المضمّن لنماذج Veo؛ كما تمتلك Gemini CLI OAuth أيضًا - تنسيق رموز ملفات تعريف المصادقة، وتحليل رموز الاستخدام، وجلب - نقطة نهاية الحصة لأسطح الاستخدام -- `moonshot`: نقل مشترك، وتطبيع حمولة التفكير مملوك للإضافة -- `kilocode`: نقل مشترك، وروؤس طلبات مملوكة للإضافة، وتطبيع حمولة التفكير، - وتنظيف توقيع أفكار Gemini الوكيل، وسياسة مدة صلاحية التخزين المؤقت -- `zai`: توافق احتياطي مستقبلي لـ GLM-5، وقيم افتراضية لـ `tool_stream`، وسياسة مدة صلاحية التخزين المؤقت، - وسياسة التفكير الثنائي/النموذج المباشر، ومصادقة الاستخدام + جلب الحصة؛ - وتُنشأ معرّفات `glm-5*` غير المعروفة تركيبيًا من القالب المضمّن `glm-4.7` +- `anthropic-vertex`: حمايات سياسة الإعادة الخاصة بـ Claude فقط على + حركة رسائل Anthropic +- `openrouter`: معرّفات نماذج تمريرية، وأغلفة طلبات، وتلميحات قدرات الموفر، + وتنقية توقيع أفكار Gemini على حركة Gemini الوكيلة، وحقن الاستدلال + الوكيلي عبر عائلة البث `openrouter-thinking`، وتمرير بيانات + التوجيه، وسياسة TTL للتخزين المؤقت +- `github-copilot`: تهيئة/تسجيل دخول الجهاز، وبديل نموذج بتوافق أمامي، + وتلميحات نصية لتفكير Claude، وتبادل رمز وقت التشغيل، وجلب نقطة + نهاية الاستخدام +- `openai`: بديل توافق أمامي لـ GPT-5.4، وتطبيع مباشر لنقل OpenAI، + وتلميحات فقدان مصادقة تراعي Codex، وكبت Spark، وصفوف فهرس + اصطناعية لـ OpenAI/Codex، وسياسة التفكير/النموذج الحي، وتطبيع أسماء رموز الاستخدام المستعارة + (`input` / `output` و`prompt` / `completion`)، وعائلة البث المشتركة + `openai-responses-defaults` لأغلفة OpenAI/Codex الأصلية، + وبيانات تعريف عائلة الموفر، وتسجيل موفر توليد الصور المجمّع + لـ `gpt-image-1`، وتسجيل موفر توليد الفيديو المجمّع + لـ `sora-2` +- `google` و`google-gemini-cli`: بديل توافق أمامي لـ Gemini 3.1، + والتحقق الأصلي من إعادة Gemini، وتنقية إعادة التشغيل عند الإقلاع، ونمط + إخراج استدلال موسوم، ومطابقة النماذج الحديثة، وتسجيل موفر + توليد الصور المجمّع لنماذج Gemini image-preview، وتسجيل + موفر توليد الفيديو المجمّع لنماذج Veo؛ كما أن Gemini CLI OAuth + يمتلك أيضًا تنسيق رموز ملفات تعريف المصادقة، وتحليل رموز الاستخدام، وجلب + نقطة نهاية الحصة لواجهات الاستخدام +- `moonshot`: نقل مشترك، وتطبيع حمولة التفكير المملوك للإضافة +- `kilocode`: نقل مشترك، ورؤوس طلبات مملوكة للإضافة، وتطبيع حمولة الاستدلال، + وتنقية توقيع أفكار Gemini الوكيل، وسياسة TTL للتخزين المؤقت +- `zai`: بديل توافق أمامي لـ GLM-5، وافتراضات `tool_stream`، وسياسة TTL للتخزين المؤقت، + وسياسة التفكير الثنائي/النموذج الحي، ومصادقة الاستخدام + جلب الحصة؛ + وتُنشأ معرّفات `glm-5*` غير المعروفة اصطناعيًا من قالب `glm-4.7` المجمّع - `xai`: تطبيع نقل Responses الأصلي، وإعادة كتابة الأسماء المستعارة `/fast` لنسخ - Grok السريعة، و`tool_stream` الافتراضي، وتنظيف مخطط الأدوات / - حمولة التفكير الخاصة بـ xAI، وتسجيل مزوّد توليد الفيديو - المضمّن لـ `grok-imagine-video` + Grok السريعة، و`tool_stream` افتراضيًا، وتنظيف + مخطط الأدوات/حمولة الاستدلال الخاص بـ xAI، وتسجيل موفر + توليد الفيديو المجمّع لـ `grok-imagine-video` - `mistral`: بيانات تعريف قدرات مملوكة للإضافة -- `opencode` و `opencode-go`: بيانات تعريف قدرات مملوكة للإضافة بالإضافة إلى - تنظيف توقيع أفكار Gemini الوكيل +- `opencode` و`opencode-go`: بيانات تعريف قدرات مملوكة للإضافة بالإضافة إلى + تنقية توقيع أفكار Gemini الوكيل - `alibaba`: فهرس توليد فيديو مملوك للإضافة لمراجع نماذج Wan المباشرة مثل `alibaba/wan2.6-t2v` -- `byteplus`: فهارس مملوكة للإضافة بالإضافة إلى تسجيل مزوّد - توليد الفيديو المضمّن لنماذج Seedance لتحويل النص إلى فيديو/الصورة إلى فيديو -- `fal`: تسجيل مزوّد توليد الفيديو المضمّن لنماذج طرف ثالث مستضافة - وتسجيل مزوّد توليد الصور لنماذج صور FLUX بالإضافة إلى تسجيل مزوّد - توليد الفيديو المضمّن لنماذج فيديو طرف ثالث مستضافة -- `cloudflare-ai-gateway`, `huggingface`, `kimi`, `nvidia`, `qianfan`, - `stepfun`, `synthetic`, `venice`, `vercel-ai-gateway`, و `volcengine`: +- `byteplus`: فهارس مملوكة للإضافة بالإضافة إلى تسجيل موفر توليد الفيديو المجمّع + لنماذج Seedance لتحويل النص إلى فيديو/الصورة إلى فيديو +- `fal`: تسجيل موفر توليد الفيديو المجمّع لاستضافة خارجية + وتسجيل موفر توليد الصور لاستضافة خارجية لنماذج صور FLUX بالإضافة إلى + تسجيل موفر توليد الفيديو المجمّع لنماذج الفيديو المستضافة من جهات خارجية +- `cloudflare-ai-gateway` و`huggingface` و`kimi` و`nvidia` و`qianfan`، + و`stepfun` و`synthetic` و`venice` و`vercel-ai-gateway` و`volcengine`: فهارس مملوكة للإضافة فقط -- `qwen`: فهارس مملوكة للإضافة للنماذج النصية بالإضافة إلى تسجيلات مزوّدي - فهم الوسائط وتوليد الفيديو المشتركة لأسطحه متعددة الوسائط؛ يستخدم - توليد الفيديو في Qwen نقاط نهاية فيديو DashScope القياسية مع نماذج Wan - مضمّنة مثل `wan2.6-t2v` و `wan2.7-r2v` -- `runway`: تسجيل مزوّد توليد فيديو مملوك للإضافة للنماذج الأصلية المعتمدة على المهام في Runway - مثل `gen4.5` -- `minimax`: فهارس مملوكة للإضافة، وتسجيل مزوّد - توليد الفيديو المضمّن لنماذج فيديو Hailuo، وتسجيل مزوّد توليد الصور - المضمّن لـ `image-01`، واختيار سياسة إعادة تشغيل هجينة Anthropic/OpenAI، +- `qwen`: فهارس مملوكة للإضافة للنماذج النصية بالإضافة إلى تسجيلات + مشتركة لموفري فهم الوسائط وتوليد الفيديو لواجهاته متعددة الوسائط؛ ويستخدم + توليد الفيديو في Qwen نقاط نهاية الفيديو القياسية لـ DashScope مع + نماذج Wan المجمّعة مثل `wan2.6-t2v` و`wan2.7-r2v` +- `runway`: تسجيل موفر توليد فيديو مملوك للإضافة لنماذج Runway + الأصلية المعتمدة على المهام مثل `gen4.5` +- `minimax`: فهارس مملوكة للإضافة، وتسجيل موفر توليد فيديو مجمّع + لنماذج فيديو Hailuo، وتسجيل موفر توليد صور مجمّع + لـ `image-01`، واختيار هجين لسياسة إعادة Anthropic/OpenAI، ومنطق مصادقة/لقطة الاستخدام -- `together`: فهارس مملوكة للإضافة بالإضافة إلى تسجيل مزوّد توليد الفيديو - المضمّن لنماذج فيديو Wan +- `together`: فهارس مملوكة للإضافة بالإضافة إلى تسجيل موفر توليد الفيديو المجمّع + لنماذج فيديو Wan - `xiaomi`: فهارس مملوكة للإضافة بالإضافة إلى منطق مصادقة/لقطة الاستخدام -تمتلك الإضافة المضمّنة `openai` الآن معرّفي المزوّدين كليهما: `openai` و +تمتلك الإضافة المجمّعة `openai` الآن كلا معرّفي الموفر: `openai` و `openai-codex`. -يغطي ذلك المزوّدين الذين ما زالوا يلائمون وسائل النقل العادية في OpenClaw. أمّا المزوّد -الذي يحتاج إلى منفّذ طلبات مخصص بالكامل فهو سطح إضافة منفصل وأعمق. +يغطي هذا الموفرين الذين ما زالوا يلائمون وسائل النقل العادية في OpenClaw. أما الموفر +الذي يحتاج إلى منفذ طلبات مخصص بالكامل فهو سطح توسعة منفصل وأعمق. ## تدوير مفاتيح API -- يدعم تدويرًا عامًا للمزوّد لمزوّدين محددين. -- قم بتهيئة مفاتيح متعددة عبر: - - `OPENCLAW_LIVE__KEY` (تجاوز مباشر واحد، أعلى أولوية) +- يدعم تدويرًا عامًا للموفر لموفري محددين. +- قم بتكوين عدة مفاتيح عبر: + - `OPENCLAW_LIVE__KEY` (تجاوز حي مفرد، بأعلى أولوية) - `_API_KEYS` (قائمة مفصولة بفواصل أو فاصلة منقوطة) - `_API_KEY` (المفتاح الأساسي) - `_API_KEY_*` (قائمة مرقمة، مثل `_API_KEY_1`) -- بالنسبة إلى مزوّدي Google، يتم أيضًا تضمين `GOOGLE_API_KEY` كخيار احتياطي. +- بالنسبة إلى موفري Google، يتم تضمين `GOOGLE_API_KEY` أيضًا كخيار احتياطي. - يحافظ ترتيب اختيار المفاتيح على الأولوية ويزيل القيم المكررة. -- لا تُعاد محاولة الطلبات بالمفتاح التالي إلا عند استجابات حد المعدل (على +- تتم إعادة محاولة الطلبات باستخدام المفتاح التالي فقط عند استجابات حد المعدل (على سبيل المثال `429` أو `rate_limit` أو `quota` أو `resource exhausted` أو `Too many concurrent requests` أو `ThrottlingException` أو `concurrency limit reached`، - أو `workers_ai ... quota limit exceeded`، أو رسائل حدود الاستخدام الدورية). -- تفشل الإخفاقات غير المرتبطة بحد المعدل فورًا؛ لا تتم محاولة تدوير المفاتيح. -- عند فشل كل المفاتيح المرشحة، يُعاد الخطأ النهائي من آخر محاولة. + أو `workers_ai ... quota limit exceeded`، أو رسائل حد الاستخدام الدورية). +- تفشل الحالات غير المرتبطة بحد المعدل فورًا؛ ولا تتم محاولة تدوير المفاتيح. +- عند فشل جميع المفاتيح المرشحة، يتم إرجاع الخطأ النهائي من آخر محاولة. -## المزوّدون المضمّنون (فهرس pi-ai) +## الموفّرون المدمجون (فهرس pi-ai) -يأتي OpenClaw مع فهرس pi‑ai. لا تتطلب هذه المزوّدات **أي** -إعدادات `models.providers`; يكفي فقط تعيين المصادقة + اختيار نموذج. +يأتي OpenClaw مع فهرس pi‑ai. لا تتطلب هذه الموفّرات أي إعداد +`models.providers`؛ فقط قم بتعيين المصادقة + اختر نموذجًا. ### OpenAI -- المزوّد: `openai` +- الموفّر: `openai` - المصادقة: `OPENAI_API_KEY` -- التدوير الاختياري: `OPENAI_API_KEYS` و `OPENAI_API_KEY_1` و `OPENAI_API_KEY_2`، بالإضافة إلى `OPENCLAW_LIVE_OPENAI_KEY` (تجاوز واحد) -- أمثلة للنماذج: `openai/gpt-5.4`, `openai/gpt-5.4-pro` -- CLI: `openclaw onboard --auth-choice openai-api-key` +- التدوير الاختياري: `OPENAI_API_KEYS` و`OPENAI_API_KEY_1` و`OPENAI_API_KEY_2`، بالإضافة إلى `OPENCLAW_LIVE_OPENAI_KEY` (تجاوز مفرد) +- نماذج مثال: `openai/gpt-5.4`، `openai/gpt-5.4-pro` +- CLI: ‏`openclaw onboard --auth-choice openai-api-key` - النقل الافتراضي هو `auto` (WebSocket أولًا، ثم SSE كخيار احتياطي) -- يمكنك التجاوز لكل نموذج عبر `agents.defaults.models["openai/"].params.transport` (`"sse"` أو `"websocket"` أو `"auto"`) +- تجاوز لكل نموذج عبر `agents.defaults.models["openai/"].params.transport` (`"sse"` أو `"websocket"` أو `"auto"`) - يتم تفعيل الإحماء المسبق لـ OpenAI Responses WebSocket افتراضيًا عبر `params.openaiWsWarmup` (`true`/`false`) -- يمكن تفعيل المعالجة ذات الأولوية في OpenAI عبر `agents.defaults.models["openai/"].params.serviceTier` -- يقوم `/fast` و `params.fastMode` بربط طلبات Responses المباشرة `openai/*` إلى `service_tier=priority` على `api.openai.com` -- استخدم `params.serviceTier` عندما تريد مستوى صريحًا بدلًا من زر التبديل المشترك `/fast` -- تُطبَّق روؤس الإسناد المخفية الخاصة بـ OpenClaw (`originator`, `version`, - `User-Agent`) فقط على حركة OpenAI الأصلية إلى `api.openai.com`، وليس على - الوكلاء العموميين المتوافقين مع OpenAI -- تحتفظ مسارات OpenAI الأصلية أيضًا بقيم Responses `store` وتلميحات التخزين المؤقت للمطالبات - وتشكيل الحمولة المتوافق مع تفكير OpenAI؛ أما المسارات الوكيلة فلا -- تم حجب `openai/gpt-5.3-codex-spark` عمدًا في OpenClaw لأن OpenAI API المباشر يرفضه؛ ويُعامل Spark على أنه مخصص لـ Codex فقط +- يمكن تمكين المعالجة ذات الأولوية في OpenAI عبر `agents.defaults.models["openai/"].params.serviceTier` +- يقوم `/fast` و`params.fastMode` بربط طلبات Responses المباشرة `openai/*` إلى `service_tier=priority` على `api.openai.com` +- استخدم `params.serviceTier` عندما تريد طبقة صريحة بدلًا من مفتاح `/fast` المشترك +- تُطبَّق رؤوس الإسناد المخفية الخاصة بـ OpenClaw (`originator`، و`version`، + و`User-Agent`) فقط على حركة OpenAI الأصلية إلى `api.openai.com`، وليس على + الوكلاء العامة المتوافقة مع OpenAI +- تحتفظ مسارات OpenAI الأصلية أيضًا بخيار Responses `store`، وتلميحات التخزين المؤقت للمطالبة، + وتهيئة حمولة توافق الاستدلال في OpenAI؛ أما مسارات الوكلاء فلا تحتفظ بذلك +- تم كبت `openai/gpt-5.3-codex-spark` عمدًا في OpenClaw لأن واجهة OpenAI الحية ترفضه؛ ويتم التعامل مع Spark على أنه خاص بـ Codex فقط ```json5 { @@ -270,14 +270,14 @@ concurrent requests` أو `ThrottlingException` أو `concurrency limit reached` ### Anthropic -- المزوّد: `anthropic` +- الموفّر: `anthropic` - المصادقة: `ANTHROPIC_API_KEY` -- التدوير الاختياري: `ANTHROPIC_API_KEYS` و `ANTHROPIC_API_KEY_1` و `ANTHROPIC_API_KEY_2`، بالإضافة إلى `OPENCLAW_LIVE_ANTHROPIC_KEY` (تجاوز واحد) -- مثال للنموذج: `anthropic/claude-opus-4-6` -- CLI: `openclaw onboard --auth-choice apiKey` -- تدعم طلبات Anthropic العامة المباشرة زر التبديل المشترك `/fast` و `params.fastMode`، بما في ذلك الحركة الموثقة بمفتاح API وOAuth المرسلة إلى `api.anthropic.com`; ويربط OpenClaw ذلك بـ Anthropic `service_tier` (`auto` مقابل `standard_only`) -- ملاحظة Anthropic: أخبرنا موظفو Anthropic أن استخدام Claude CLI بأسلوب OpenClaw مسموح به مرة أخرى، لذلك يتعامل OpenClaw مع إعادة استخدام Claude CLI واستخدام `claude -p` على أنهما مصرح بهما لهذا التكامل ما لم تنشر Anthropic سياسة جديدة. -- ما يزال رمز إعداد Anthropic متاحًا كمسار رمز مدعوم في OpenClaw، لكن OpenClaw يفضّل الآن إعادة استخدام Claude CLI و `claude -p` عند توفرهما. +- التدوير الاختياري: `ANTHROPIC_API_KEYS` و`ANTHROPIC_API_KEY_1` و`ANTHROPIC_API_KEY_2`، بالإضافة إلى `OPENCLAW_LIVE_ANTHROPIC_KEY` (تجاوز مفرد) +- نموذج مثال: `anthropic/claude-opus-4-6` +- CLI: ‏`openclaw onboard --auth-choice apiKey` +- تدعم طلبات Anthropic العامة المباشرة مفتاح `/fast` المشترك و`params.fastMode`، بما في ذلك حركة المرور المصادق عليها بمفتاح API وOAuth المرسلة إلى `api.anthropic.com`؛ ويقوم OpenClaw بربط ذلك إلى `service_tier` الخاص بـ Anthropic (`auto` مقابل `standard_only`) +- ملاحظة Anthropic: أخبرنا موظفو Anthropic أن استخدام Claude CLI بأسلوب OpenClaw مسموح به مرة أخرى، لذلك يتعامل OpenClaw مع إعادة استخدام Claude CLI واستخدام `claude -p` على أنهما معتمدان لهذا التكامل ما لم تنشر Anthropic سياسة جديدة. +- يظل رمز إعداد Anthropic متاحًا كمسار رمز مدعوم في OpenClaw، لكن OpenClaw يفضّل الآن إعادة استخدام Claude CLI و`claude -p` عند توفرهما. ```json5 { @@ -287,20 +287,20 @@ concurrent requests` أو `ThrottlingException` أو `concurrency limit reached` ### OpenAI Code (Codex) -- المزوّد: `openai-codex` +- الموفّر: `openai-codex` - المصادقة: OAuth (ChatGPT) -- مثال للنموذج: `openai-codex/gpt-5.4` -- CLI: `openclaw onboard --auth-choice openai-codex` أو `openclaw models auth login --provider openai-codex` +- نموذج مثال: `openai-codex/gpt-5.4` +- CLI: ‏`openclaw onboard --auth-choice openai-codex` أو `openclaw models auth login --provider openai-codex` - النقل الافتراضي هو `auto` (WebSocket أولًا، ثم SSE كخيار احتياطي) -- يمكنك التجاوز لكل نموذج عبر `agents.defaults.models["openai-codex/"].params.transport` (`"sse"` أو `"websocket"` أو `"auto"`) +- تجاوز لكل نموذج عبر `agents.defaults.models["openai-codex/"].params.transport` (`"sse"` أو `"websocket"` أو `"auto"`) - يتم أيضًا تمرير `params.serviceTier` على طلبات Codex Responses الأصلية (`chatgpt.com/backend-api`) -- لا تُرفق روؤس الإسناد المخفية الخاصة بـ OpenClaw (`originator`, `version`, - `User-Agent`) إلا على حركة Codex الأصلية إلى - `chatgpt.com/backend-api`، وليس على الوكلاء العموميين المتوافقين مع OpenAI -- يشترك في زر التبديل `/fast` نفسه وإعداد `params.fastMode` نفسه مثل `openai/*` المباشر؛ ويربط OpenClaw ذلك بـ `service_tier=priority` -- يظل `openai-codex/gpt-5.3-codex-spark` متاحًا عندما يكشف فهرس Codex OAuth عنه؛ وذلك يعتمد على الاستحقاق -- يحتفظ `openai-codex/gpt-5.4` بالقيمة الأصلية `contextWindow = 1050000` وحد وقت تشغيل افتراضي `contextTokens = 272000`؛ يمكنك تجاوز حد وقت التشغيل عبر `models.providers.openai-codex.models[].contextTokens` -- ملاحظة سياسة: يدعم OpenAI Codex OAuth صراحةً الأدوات/سير العمل الخارجية مثل OpenClaw. +- تُرفق رؤوس الإسناد المخفية الخاصة بـ OpenClaw (`originator` و`version`، + و`User-Agent`) فقط على حركة Codex الأصلية إلى + `chatgpt.com/backend-api`، وليس على الوكلاء العامة المتوافقة مع OpenAI +- يشترك في مفتاح `/fast` نفسه وإعداد `params.fastMode` نفسه كما في `openai/*` المباشر؛ ويقوم OpenClaw بربط ذلك إلى `service_tier=priority` +- يظل `openai-codex/gpt-5.3-codex-spark` متاحًا عندما يعرِضه فهرس Codex OAuth؛ ويعتمد على الاستحقاق +- يحتفظ `openai-codex/gpt-5.4` بالقيم الأصلية `contextWindow = 1050000` وحد وقت تشغيل افتراضي `contextTokens = 272000`؛ ويمكنك تجاوز حد وقت التشغيل عبر `models.providers.openai-codex.models[].contextTokens` +- ملاحظة السياسة: يتم دعم OpenAI Codex OAuth صراحةً للأدوات/سير العمل الخارجية مثل OpenClaw. ```json5 { @@ -320,19 +320,19 @@ concurrent requests` أو `ThrottlingException` أو `concurrency limit reached` } ``` -### خيارات أخرى مستضافة بنمط الاشتراك +### خيارات مستضافة أخرى على نمط الاشتراك -- [Qwen Cloud](/ar/providers/qwen): سطح مزوّد Qwen Cloud بالإضافة إلى ربط نقاط نهاية Alibaba DashScope وCoding Plan +- [Qwen Cloud](/ar/providers/qwen): واجهة موفر Qwen Cloud بالإضافة إلى ربط نقاط نهاية Alibaba DashScope وCoding Plan - [MiniMax](/ar/providers/minimax): وصول MiniMax Coding Plan عبر OAuth أو مفتاح API -- [GLM Models](/ar/providers/glm): نقاط نهاية Z.AI Coding Plan أو API العامة +- [GLM Models](/ar/providers/glm): نقاط نهاية Z.AI Coding Plan أو نقاط نهاية API العامة ### OpenCode - المصادقة: `OPENCODE_API_KEY` (أو `OPENCODE_ZEN_API_KEY`) -- مزوّد وقت تشغيل Zen: `opencode` -- مزوّد وقت تشغيل Go: `opencode-go` -- أمثلة للنماذج: `opencode/claude-opus-4-6`, `opencode-go/kimi-k2.5` -- CLI: `openclaw onboard --auth-choice opencode-zen` أو `openclaw onboard --auth-choice opencode-go` +- موفر وقت تشغيل Zen: ‏`opencode` +- موفر وقت تشغيل Go: ‏`opencode-go` +- نماذج مثال: `opencode/claude-opus-4-6`، `opencode-go/kimi-k2.5` +- CLI: ‏`openclaw onboard --auth-choice opencode-zen` أو `openclaw onboard --auth-choice opencode-go` ```json5 { @@ -342,145 +342,148 @@ concurrent requests` أو `ThrottlingException` أو `concurrency limit reached` ### Google Gemini (مفتاح API) -- المزوّد: `google` +- الموفّر: `google` - المصادقة: `GEMINI_API_KEY` -- التدوير الاختياري: `GEMINI_API_KEYS` و `GEMINI_API_KEY_1` و `GEMINI_API_KEY_2`، وخيار `GOOGLE_API_KEY` الاحتياطي، و `OPENCLAW_LIVE_GEMINI_KEY` (تجاوز واحد) -- أمثلة للنماذج: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview` +- التدوير الاختياري: `GEMINI_API_KEYS` و`GEMINI_API_KEY_1` و`GEMINI_API_KEY_2`، وخيار احتياطي `GOOGLE_API_KEY`، و`OPENCLAW_LIVE_GEMINI_KEY` (تجاوز مفرد) +- نماذج مثال: `google/gemini-3.1-pro-preview`، `google/gemini-3-flash-preview` - التوافق: يتم تطبيع إعداد OpenClaw القديم الذي يستخدم `google/gemini-3.1-flash-preview` إلى `google/gemini-3-flash-preview` -- CLI: `openclaw onboard --auth-choice gemini-api-key` -- تقبل تشغيلات Gemini المباشرة أيضًا `agents.defaults.models["google/"].params.cachedContent` - (أو الاسم القديم `cached_content`) لتمرير معرّف أصلي من المزوّد - `cachedContents/...`; وتظهر إصابات التخزين المؤقت في Gemini على شكل OpenClaw `cacheRead` +- CLI: ‏`openclaw onboard --auth-choice gemini-api-key` +- تقبل عمليات Gemini المباشرة أيضًا `agents.defaults.models["google/"].params.cachedContent` + (أو الصيغة القديمة `cached_content`) لتمرير + مقبض `cachedContents/...` أصلي خاص بالموفر؛ وتظهر إصابات ذاكرة التخزين المؤقت في Gemini على هيئة `cacheRead` في OpenClaw -### Google Vertex و Gemini CLI +### Google Vertex وGemini CLI -- المزوّدان: `google-vertex`, `google-gemini-cli` -- المصادقة: يستخدم Vertex gcloud ADC؛ ويستخدم Gemini CLI تدفق OAuth الخاص به -- تحذير: تكامل Gemini CLI OAuth في OpenClaw غير رسمي. أبلغ بعض المستخدمين عن قيود على حسابات Google بعد استخدام عملاء من أطراف ثالثة. راجع شروط Google واستخدم حسابًا غير حرج إذا اخترت المتابعة. -- يتم شحن Gemini CLI OAuth كجزء من الإضافة المضمّنة `google`. - - ثبّت Gemini CLI أولًا: +- الموفّرون: `google-vertex`، ‏`google-gemini-cli` +- المصادقة: يستخدم Vertex آلية gcloud ADC؛ ويستخدم Gemini CLI تدفق OAuth الخاص به +- تنبيه: تكامل Gemini CLI OAuth في OpenClaw غير رسمي. أبلغ بعض المستخدمين عن فرض قيود على حسابات Google بعد استخدام عملاء من جهات خارجية. راجع شروط Google واستخدم حسابًا غير حرج إذا اخترت المتابعة. +- يتم شحن Gemini CLI OAuth كجزء من إضافة `google` المجمّعة. + - قم بتثبيت Gemini CLI أولًا: - `brew install gemini-cli` - أو `npm install -g @google/gemini-cli` - التمكين: `openclaw plugins enable google` - تسجيل الدخول: `openclaw models auth login --provider google-gemini-cli --set-default` - - النموذج الافتراضي: `google-gemini-cli/gemini-3.1-pro-preview` - - ملاحظة: **لا** تقوم بلصق معرّف عميل أو سر في `openclaw.json`. يقوم تدفق تسجيل الدخول في CLI بتخزين + - النموذج الافتراضي: `google-gemini-cli/gemini-3-flash-preview` + - ملاحظة: **لا** تقوم بلصق client id أو secret في `openclaw.json`. يقوم تدفق تسجيل دخول CLI بتخزين الرموز في ملفات تعريف المصادقة على مضيف البوابة. - - إذا فشلت الطلبات بعد تسجيل الدخول، فعيّن `GOOGLE_CLOUD_PROJECT` أو `GOOGLE_CLOUD_PROJECT_ID` على مضيف البوابة. - - يتم تحليل ردود Gemini CLI بصيغة JSON من `response`؛ ويعود الاستخدام إلى - `stats`، مع تطبيع `stats.cached` إلى OpenClaw `cacheRead`. + - إذا فشلت الطلبات بعد تسجيل الدخول، فاضبط `GOOGLE_CLOUD_PROJECT` أو `GOOGLE_CLOUD_PROJECT_ID` على مضيف البوابة. + - يتم تحليل ردود JSON الخاصة بـ Gemini CLI من `response`؛ ويعود الاستخدام احتياطيًا إلى + `stats`، مع تطبيع `stats.cached` إلى `cacheRead` في OpenClaw. ### Z.AI (GLM) -- المزوّد: `zai` +- الموفّر: `zai` - المصادقة: `ZAI_API_KEY` -- مثال للنموذج: `zai/glm-5` -- CLI: `openclaw onboard --auth-choice zai-api-key` - - الأسماء المستعارة: يتم تطبيع `z.ai/*` و `z-ai/*` إلى `zai/*` - - يكتشف `zai-api-key` نقطة نهاية Z.AI المطابقة تلقائيًا؛ بينما تفرض `zai-coding-global` و `zai-coding-cn` و `zai-global` و `zai-cn` سطحًا محددًا +- نموذج مثال: `zai/glm-5` +- CLI: ‏`openclaw onboard --auth-choice zai-api-key` + - الأسماء المستعارة: يتم تطبيع `z.ai/*` و`z-ai/*` إلى `zai/*` + - يقوم `zai-api-key` بالكشف التلقائي عن نقطة نهاية Z.AI المطابقة؛ بينما يفرض `zai-coding-global` و`zai-coding-cn` و`zai-global` و`zai-cn` واجهة محددة ### Vercel AI Gateway -- المزوّد: `vercel-ai-gateway` +- الموفّر: `vercel-ai-gateway` - المصادقة: `AI_GATEWAY_API_KEY` -- مثال للنموذج: `vercel-ai-gateway/anthropic/claude-opus-4.6` -- CLI: `openclaw onboard --auth-choice ai-gateway-api-key` +- نموذج مثال: `vercel-ai-gateway/anthropic/claude-opus-4.6` +- CLI: ‏`openclaw onboard --auth-choice ai-gateway-api-key` ### Kilo Gateway -- المزوّد: `kilocode` +- الموفّر: `kilocode` - المصادقة: `KILOCODE_API_KEY` -- مثال للنموذج: `kilocode/kilo/auto` -- CLI: `openclaw onboard --auth-choice kilocode-api-key` +- نموذج مثال: `kilocode/kilo/auto` +- CLI: ‏`openclaw onboard --auth-choice kilocode-api-key` - عنوان URL الأساسي: `https://api.kilo.ai/api/gateway/` -- يشحن الفهرس الاحتياطي الثابت `kilocode/kilo/auto`; ويمكن لاكتشاف - `https://api.kilo.ai/api/gateway/models` المباشر توسيع فهرس وقت التشغيل أكثر. -- يمتلك Kilo Gateway التوجيه upstream الدقيق خلف `kilocode/kilo/auto`، - وليس مشفّرًا بشكل ثابت في OpenClaw. +- يشحن فهرس احتياطي ثابت `kilocode/kilo/auto`؛ ويمكن أن يوسّع + الاكتشاف الحي لـ `https://api.kilo.ai/api/gateway/models` فهرس + وقت التشغيل أكثر. +- التوجيه الدقيق لدى المصدر خلف `kilocode/kilo/auto` مملوك لـ Kilo Gateway، + وليس مُرمَّزًا بشكل ثابت في OpenClaw. -راجع [/providers/kilocode](/ar/providers/kilocode) للاطلاع على تفاصيل الإعداد. +راجع [/providers/kilocode](/ar/providers/kilocode) للحصول على تفاصيل الإعداد. -### إضافات مزوّدين مضمّنة أخرى +### إضافات موفّرين مدمجة أخرى -- OpenRouter: `openrouter` (`OPENROUTER_API_KEY`) -- مثال للنموذج: `openrouter/auto` -- يطبّق OpenClaw روؤس إسناد التطبيق الموثقة في OpenRouter فقط عندما +- OpenRouter: ‏`openrouter` ‏(`OPENROUTER_API_KEY`) +- نموذج مثال: `openrouter/auto` +- يطبق OpenClaw رؤوس إسناد التطبيق الموثقة في OpenRouter فقط عندما يستهدف الطلب فعليًا `openrouter.ai` -- كما تُقيّد علامات `cache_control` الخاصة بـ Anthropic في OpenRouter - على مسارات OpenRouter المتحقق منها، وليس على عناوين URL الوكيلة العشوائية -- يظل OpenRouter على المسار الوكيلي المتوافق مع OpenAI، لذا لا يتم - تمرير تشكيل الطلبات الأصلي الخاص بـ OpenAI فقط (`serviceTier`, Responses `store`, - تلميحات التخزين المؤقت للمطالبات، حمولات التوافق مع التفكير في OpenAI) -- تحتفظ مراجع OpenRouter المدعومة بـ Gemini فقط بمسار تنظيف توقيع أفكار Gemini الوكيل؛ أما التحقق الأصلي من إعادة تشغيل Gemini وإعادة كتابة التمهيد فيظلان معطلين -- Kilo Gateway: `kilocode` (`KILOCODE_API_KEY`) -- مثال للنموذج: `kilocode/kilo/auto` -- تحتفظ مراجع Kilo المدعومة بـ Gemini بمسار تنظيف توقيع أفكار Gemini الوكيل نفسه؛ وتتخطى تلميحات `kilocode/kilo/auto` وغيرها من التلميحات الوكيلة غير الداعمة للتفكير الوكيلي حقن التفكير الوكيلي -- MiniMax: ‏`minimax` (مفتاح API) و `minimax-portal` (OAuth) +- يتم كذلك تقييد علامات `cache_control` الخاصة بـ Anthropic في OpenRouter إلى + مسارات OpenRouter المتحقق منها، وليس عناوين URL وكيلة عشوائية +- يظل OpenRouter على المسار الوكيلي المتوافق مع OpenAI، لذلك لا يتم تمرير + تهيئة الطلب الأصلية الخاصة بـ OpenAI فقط (`serviceTier`، وخيار Responses `store`، + وتلميحات التخزين المؤقت للمطالبة، وحمولات توافق الاستدلال في OpenAI) +- تحتفظ مراجع OpenRouter المستندة إلى Gemini فقط بمسار + تنقية توقيع أفكار Gemini الوكيل؛ وتظل إعادة التحقق الأصلية في Gemini وإعادة كتابة الإقلاع معطلتين +- Kilo Gateway: ‏`kilocode` ‏(`KILOCODE_API_KEY`) +- نموذج مثال: `kilocode/kilo/auto` +- تحتفظ مراجع Kilo المعتمدة على Gemini بمسار تنقية + توقيع أفكار Gemini الوكيل نفسه؛ وتتجاوز التلميحات مثل `kilocode/kilo/auto` وغيرها من التلميحات غير المدعومة للاستدلال الوكيلي حقن الاستدلال الوكيلي +- MiniMax: ‏`minimax` (مفتاح API) و`minimax-portal` (OAuth) - المصادقة: `MINIMAX_API_KEY` لـ `minimax`؛ و`MINIMAX_OAUTH_TOKEN` أو `MINIMAX_API_KEY` لـ `minimax-portal` -- مثال للنموذج: `minimax/MiniMax-M2.7` أو `minimax-portal/MiniMax-M2.7` +- نموذج مثال: `minimax/MiniMax-M2.7` أو `minimax-portal/MiniMax-M2.7` - تكتب تهيئة MiniMax/إعداد مفتاح API تعريفات صريحة لنموذج M2.7 مع - `input: ["text", "image"]`; بينما يبقي فهرس المزوّد المضمّن مراجع الدردشة - نصية فقط إلى أن تتم تهيئة إعدادات ذلك المزوّد -- Moonshot: ‏`moonshot` (`MOONSHOT_API_KEY`) -- مثال للنموذج: `moonshot/kimi-k2.5` -- Kimi Coding: ‏`kimi` (`KIMI_API_KEY` أو `KIMICODE_API_KEY`) -- مثال للنموذج: `kimi/kimi-code` -- Qianfan: ‏`qianfan` (`QIANFAN_API_KEY`) -- مثال للنموذج: `qianfan/deepseek-v3.2` -- Qwen Cloud: ‏`qwen` (`QWEN_API_KEY`, `MODELSTUDIO_API_KEY`, أو `DASHSCOPE_API_KEY`) -- مثال للنموذج: `qwen/qwen3.5-plus` -- NVIDIA: ‏`nvidia` (`NVIDIA_API_KEY`) -- مثال للنموذج: `nvidia/nvidia/llama-3.1-nemotron-70b-instruct` -- StepFun: ‏`stepfun` / `stepfun-plan` (`STEPFUN_API_KEY`) -- أمثلة للنماذج: `stepfun/step-3.5-flash`, `stepfun-plan/step-3.5-flash-2603` -- Together: ‏`together` (`TOGETHER_API_KEY`) -- مثال للنموذج: `together/moonshotai/Kimi-K2.5` -- Venice: ‏`venice` (`VENICE_API_KEY`) -- Xiaomi: ‏`xiaomi` (`XIAOMI_API_KEY`) -- مثال للنموذج: `xiaomi/mimo-v2-flash` -- Vercel AI Gateway: ‏`vercel-ai-gateway` (`AI_GATEWAY_API_KEY`) -- Hugging Face Inference: ‏`huggingface` (`HUGGINGFACE_HUB_TOKEN` أو `HF_TOKEN`) -- Cloudflare AI Gateway: ‏`cloudflare-ai-gateway` (`CLOUDFLARE_AI_GATEWAY_API_KEY`) -- Volcengine: ‏`volcengine` (`VOLCANO_ENGINE_API_KEY`) -- مثال للنموذج: `volcengine-plan/ark-code-latest` -- BytePlus: ‏`byteplus` (`BYTEPLUS_API_KEY`) -- مثال للنموذج: `byteplus-plan/ark-code-latest` -- xAI: ‏`xai` (`XAI_API_KEY`) - - تستخدم طلبات xAI الأصلية المضمّنة مسار xAI Responses - - يقوم `/fast` أو `params.fastMode: true` بإعادة كتابة `grok-3` و `grok-3-mini`، - و `grok-4`، و `grok-4-0709` إلى النسخ `*-fast` الخاصة بها - - يكون `tool_stream` مفعّلًا افتراضيًا؛ عيّن - `agents.defaults.models["xai/"].params.tool_stream` إلى `false` - لتعطيله -- Mistral: ‏`mistral` (`MISTRAL_API_KEY`) -- مثال للنموذج: `mistral/mistral-large-latest` -- CLI: `openclaw onboard --auth-choice mistral-api-key` -- Groq: ‏`groq` (`GROQ_API_KEY`) -- Cerebras: ‏`cerebras` (`CEREBRAS_API_KEY`) - - تستخدم نماذج GLM على Cerebras المعرّفات `zai-glm-4.7` و `zai-glm-4.6`. - - عنوان URL الأساسي المتوافق مع OpenAI: `https://api.cerebras.ai/v1`. -- GitHub Copilot: ‏`github-copilot` (`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`) -- مثال نموذج Hugging Face Inference: ‏`huggingface/deepseek-ai/DeepSeek-R1`; ‏CLI: `openclaw onboard --auth-choice huggingface-api-key`. راجع [Hugging Face (Inference)](/ar/providers/huggingface). + `input: ["text", "image"]`؛ بينما يحتفظ فهرس الموفر المجمّع بمراجع الدردشة + على أنها نصية فقط حتى يتم إنشاء إعداد هذا الموفر +- Moonshot: ‏`moonshot` ‏(`MOONSHOT_API_KEY`) +- نموذج مثال: `moonshot/kimi-k2.5` +- Kimi Coding: ‏`kimi` ‏(`KIMI_API_KEY` أو `KIMICODE_API_KEY`) +- نموذج مثال: `kimi/kimi-code` +- Qianfan: ‏`qianfan` ‏(`QIANFAN_API_KEY`) +- نموذج مثال: `qianfan/deepseek-v3.2` +- Qwen Cloud: ‏`qwen` ‏(`QWEN_API_KEY` أو `MODELSTUDIO_API_KEY` أو `DASHSCOPE_API_KEY`) +- نموذج مثال: `qwen/qwen3.5-plus` +- NVIDIA: ‏`nvidia` ‏(`NVIDIA_API_KEY`) +- نموذج مثال: `nvidia/nvidia/llama-3.1-nemotron-70b-instruct` +- StepFun: ‏`stepfun` / `stepfun-plan` ‏(`STEPFUN_API_KEY`) +- نماذج مثال: `stepfun/step-3.5-flash`، `stepfun-plan/step-3.5-flash-2603` +- Together: ‏`together` ‏(`TOGETHER_API_KEY`) +- نموذج مثال: `together/moonshotai/Kimi-K2.5` +- Venice: ‏`venice` ‏(`VENICE_API_KEY`) +- Xiaomi: ‏`xiaomi` ‏(`XIAOMI_API_KEY`) +- نموذج مثال: `xiaomi/mimo-v2-flash` +- Vercel AI Gateway: ‏`vercel-ai-gateway` ‏(`AI_GATEWAY_API_KEY`) +- Hugging Face Inference: ‏`huggingface` ‏(`HUGGINGFACE_HUB_TOKEN` أو `HF_TOKEN`) +- Cloudflare AI Gateway: ‏`cloudflare-ai-gateway` ‏(`CLOUDFLARE_AI_GATEWAY_API_KEY`) +- Volcengine: ‏`volcengine` ‏(`VOLCANO_ENGINE_API_KEY`) +- نموذج مثال: `volcengine-plan/ark-code-latest` +- BytePlus: ‏`byteplus` ‏(`BYTEPLUS_API_KEY`) +- نموذج مثال: `byteplus-plan/ark-code-latest` +- xAI: ‏`xai` ‏(`XAI_API_KEY`) + - تستخدم طلبات xAI الأصلية المجمعة مسار xAI Responses + - يعيد `/fast` أو `params.fastMode: true` كتابة `grok-3` و`grok-3-mini`، + و`grok-4` و`grok-4-0709` إلى متغيراتها `*-fast` + - يتم تفعيل `tool_stream` افتراضيًا؛ اضبط + `agents.defaults.models["xai/"].params.tool_stream` على `false` من + أجل تعطيله +- Mistral: ‏`mistral` ‏(`MISTRAL_API_KEY`) +- نموذج مثال: `mistral/mistral-large-latest` +- CLI: ‏`openclaw onboard --auth-choice mistral-api-key` +- Groq: ‏`groq` ‏(`GROQ_API_KEY`) +- Cerebras: ‏`cerebras` ‏(`CEREBRAS_API_KEY`) + - تستخدم نماذج GLM على Cerebras المعرّفين `zai-glm-4.7` و`zai-glm-4.6`. + - عنوان URL الأساسي المتوافق مع OpenAI: ‏`https://api.cerebras.ai/v1`. +- GitHub Copilot: ‏`github-copilot` ‏(`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`) +- نموذج مثال لـ Hugging Face Inference: ‏`huggingface/deepseek-ai/DeepSeek-R1`؛ CLI: ‏`openclaw onboard --auth-choice huggingface-api-key`. راجع [Hugging Face (Inference)](/ar/providers/huggingface). -## المزوّدون عبر `models.providers` ‏(مخصص/عنوان URL أساسي) +## الموفّرون عبر `models.providers` (مخصص/عنوان URL أساسي) -استخدم `models.providers` (أو `models.json`) لإضافة **مزوّدين مخصصين** أو +استخدم `models.providers` (أو `models.json`) لإضافة موفّرين **مخصصين** أو وكلاء متوافقين مع OpenAI/Anthropic. -تنشر كثير من إضافات المزوّدين المضمّنة أدناه بالفعل فهرسًا افتراضيًا. +تنشر العديد من إضافات الموفّرين المجمّعة أدناه بالفعل فهرسًا افتراضيًا. استخدم إدخالات `models.providers.` الصريحة فقط عندما تريد تجاوز -عنوان URL الأساسي أو الروؤس أو قائمة النماذج الافتراضية. +عنوان URL الأساسي الافتراضي أو الرؤوس أو قائمة النماذج. ### Moonshot AI (Kimi) -يأتي Moonshot كإضافة مزوّد مضمّنة. استخدم المزوّد المضمّن افتراضيًا، +يأتي Moonshot كإضافة موفر مجمّعة. استخدم الموفّر المدمج افتراضيًا، وأضف إدخال `models.providers.moonshot` صريحًا فقط عندما تحتاج إلى تجاوز عنوان URL الأساسي أو بيانات تعريف النموذج: -- المزوّد: `moonshot` +- الموفّر: `moonshot` - المصادقة: `MOONSHOT_API_KEY` -- مثال للنموذج: `moonshot/kimi-k2.5` -- CLI: `openclaw onboard --auth-choice moonshot-api-key` أو `openclaw onboard --auth-choice moonshot-api-key-cn` +- نموذج مثال: `moonshot/kimi-k2.5` +- CLI: ‏`openclaw onboard --auth-choice moonshot-api-key` أو `openclaw onboard --auth-choice moonshot-api-key-cn` معرّفات نموذج Kimi K2: @@ -516,9 +519,9 @@ concurrent requests` أو `ThrottlingException` أو `concurrency limit reached` يستخدم Kimi Coding نقطة النهاية المتوافقة مع Anthropic الخاصة بـ Moonshot AI: -- المزوّد: `kimi` +- الموفّر: `kimi` - المصادقة: `KIMI_API_KEY` -- مثال للنموذج: `kimi/kimi-code` +- نموذج مثال: `kimi/kimi-code` ```json5 { @@ -533,12 +536,12 @@ concurrent requests` أو `ThrottlingException` أو `concurrency limit reached` ### Volcano Engine (Doubao) -يوفر Volcano Engine (火山引擎) الوصول إلى Doubao ونماذج أخرى في الصين. +يوفر Volcano Engine (火山引擎) الوصول إلى Doubao ونماذج أخرى داخل الصين. -- المزوّد: `volcengine` (الترميز: `volcengine-plan`) +- الموفّر: `volcengine` (الترميز: `volcengine-plan`) - المصادقة: `VOLCANO_ENGINE_API_KEY` -- مثال للنموذج: `volcengine-plan/ark-code-latest` -- CLI: `openclaw onboard --auth-choice volcengine-api-key` +- نموذج مثال: `volcengine-plan/ark-code-latest` +- CLI: ‏`openclaw onboard --auth-choice volcengine-api-key` ```json5 { @@ -548,13 +551,13 @@ concurrent requests` أو `ThrottlingException` أو `concurrency limit reached` } ``` -تستخدم التهيئة سطح الترميز افتراضيًا، لكن يتم تسجيل فهرس `volcengine/*` -العام في الوقت نفسه. +تستخدم التهيئة سطح الترميز افتراضيًا، لكن فهرس `volcengine/*` +العام يتم تسجيله في الوقت نفسه. -في منتقيات النماذج الخاصة بالتهيئة/الإعداد، يفضّل خيار مصادقة Volcengine كلا -الصفّين `volcengine/*` و `volcengine-plan/*`. وإذا لم تكن هذه النماذج محملة بعد، -فإن OpenClaw يعود إلى الفهرس غير المصفّى بدلًا من إظهار منتقٍ فارغ -محصور بالمزوّد. +في أدوات اختيار نموذج التهيئة/الضبط، يفضّل خيار مصادقة Volcengine كِلَا +صفَّي `volcengine/*` و`volcengine-plan/*`. وإذا لم تكن هذه النماذج محمّلة بعد، +فإن OpenClaw يعود إلى الفهرس غير المصفّى بدلًا من عرض أداة اختيار فارغة +مقيدة بالموفّر. النماذج المتاحة: @@ -574,12 +577,12 @@ concurrent requests` أو `ThrottlingException` أو `concurrency limit reached` ### BytePlus (دولي) -يوفر BytePlus ARK الوصول إلى النماذج نفسها التي يوفرها Volcano Engine للمستخدمين الدوليين. +يوفر BytePlus ARK الوصول إلى النماذج نفسها الموجودة في Volcano Engine للمستخدمين الدوليين. -- المزوّد: `byteplus` (الترميز: `byteplus-plan`) +- الموفّر: `byteplus` (الترميز: `byteplus-plan`) - المصادقة: `BYTEPLUS_API_KEY` -- مثال للنموذج: `byteplus-plan/ark-code-latest` -- CLI: `openclaw onboard --auth-choice byteplus-api-key` +- نموذج مثال: `byteplus-plan/ark-code-latest` +- CLI: ‏`openclaw onboard --auth-choice byteplus-api-key` ```json5 { @@ -589,13 +592,13 @@ concurrent requests` أو `ThrottlingException` أو `concurrency limit reached` } ``` -تستخدم التهيئة سطح الترميز افتراضيًا، لكن يتم تسجيل فهرس `byteplus/*` -العام في الوقت نفسه. +تستخدم التهيئة سطح الترميز افتراضيًا، لكن فهرس `byteplus/*` +العام يتم تسجيله في الوقت نفسه. -في منتقيات النماذج الخاصة بالتهيئة/الإعداد، يفضّل خيار مصادقة BytePlus كلا -الصفّين `byteplus/*` و `byteplus-plan/*`. وإذا لم تكن هذه النماذج محملة بعد، -فإن OpenClaw يعود إلى الفهرس غير المصفّى بدلًا من إظهار منتقٍ فارغ -محصور بالمزوّد. +في أدوات اختيار نموذج التهيئة/الضبط، يفضّل خيار مصادقة BytePlus كِلَا +صفَّي `byteplus/*` و`byteplus-plan/*`. وإذا لم تكن هذه النماذج محمّلة بعد، +فإن OpenClaw يعود إلى الفهرس غير المصفّى بدلًا من عرض أداة اختيار فارغة +مقيدة بالموفّر. النماذج المتاحة: @@ -613,12 +616,12 @@ concurrent requests` أو `ThrottlingException` أو `concurrency limit reached` ### Synthetic -يوفر Synthetic نماذج متوافقة مع Anthropic خلف المزوّد `synthetic`: +يوفر Synthetic نماذج متوافقة مع Anthropic خلف الموفّر `synthetic`: -- المزوّد: `synthetic` +- الموفّر: `synthetic` - المصادقة: `SYNTHETIC_API_KEY` -- مثال للنموذج: `synthetic/hf:MiniMaxAI/MiniMax-M2.5` -- CLI: `openclaw onboard --auth-choice synthetic-api-key` +- نموذج مثال: `synthetic/hf:MiniMaxAI/MiniMax-M2.5` +- CLI: ‏`openclaw onboard --auth-choice synthetic-api-key` ```json5 { @@ -641,35 +644,35 @@ concurrent requests` أو `ThrottlingException` أو `concurrency limit reached` ### MiniMax -يتم إعداد MiniMax عبر `models.providers` لأنه يستخدم نقاط نهاية مخصصة: +يتم تكوين MiniMax عبر `models.providers` لأنه يستخدم نقاط نهاية مخصصة: - MiniMax OAuth (عالمي): `--auth-choice minimax-global-oauth` - MiniMax OAuth (الصين): `--auth-choice minimax-cn-oauth` - مفتاح API لـ MiniMax (عالمي): `--auth-choice minimax-global-api` - مفتاح API لـ MiniMax (الصين): `--auth-choice minimax-cn-api` -- المصادقة: `MINIMAX_API_KEY` لـ `minimax`; و`MINIMAX_OAUTH_TOKEN` أو +- المصادقة: `MINIMAX_API_KEY` لـ `minimax`؛ و`MINIMAX_OAUTH_TOKEN` أو `MINIMAX_API_KEY` لـ `minimax-portal` -راجع [/providers/minimax](/ar/providers/minimax) للحصول على تفاصيل الإعداد وخيارات النماذج ومقاطع الإعداد. +راجع [/providers/minimax](/ar/providers/minimax) للحصول على تفاصيل الإعداد وخيارات النماذج ومقاطع التكوين. -على مسار البث المتوافق مع Anthropic في MiniMax، يقوم OpenClaw بتعطيل التفكير -افتراضيًا ما لم تقم بتعيينه صراحةً، ويقوم `/fast on` بإعادة كتابة +على مسار البث المتوافق مع Anthropic في MiniMax، يعطّل OpenClaw التفكير +افتراضيًا ما لم تقم بتعيينه صراحةً، ويعيد `/fast on` كتابة `MiniMax-M2.7` إلى `MiniMax-M2.7-highspeed`. تقسيم القدرات المملوك للإضافة: -- تظل إعدادات النص/الدردشة الافتراضية على `minimax/MiniMax-M2.7` -- يكون توليد الصور هو `minimax/image-01` أو `minimax-portal/image-01` -- يكون فهم الصور هو `MiniMax-VL-01` المملوك للإضافة على مساري مصادقة MiniMax كليهما -- يظل البحث على الويب على معرّف المزوّد `minimax` +- تظل الإعدادات الافتراضية للنص/الدردشة على `minimax/MiniMax-M2.7` +- توليد الصور هو `minimax/image-01` أو `minimax-portal/image-01` +- فهم الصور هو `MiniMax-VL-01` مملوك للإضافة على كلا مساري مصادقة MiniMax +- يبقى البحث على الويب على معرّف الموفّر `minimax` ### Ollama -يأتي Ollama كإضافة مزوّد مضمّنة ويستخدم API الأصلي الخاص بـ Ollama: +يأتي Ollama كإضافة موفر مجمّعة ويستخدم API الأصلي الخاص بـ Ollama: -- المزوّد: `ollama` -- المصادقة: لا شيء مطلوب (خادم محلي) -- مثال للنموذج: `ollama/llama3.3` +- الموفّر: `ollama` +- المصادقة: غير مطلوبة (خادم محلي) +- نموذج مثال: `ollama/llama3.3` - التثبيت: [https://ollama.com/download](https://ollama.com/download) ```bash @@ -685,26 +688,27 @@ ollama pull llama3.3 } ``` -يتم اكتشاف Ollama محليًا على `http://127.0.0.1:11434` عندما تختار الاشتراك -باستخدام `OLLAMA_API_KEY`، وتضيف إضافة المزوّد المضمّنة Ollama مباشرةً إلى -`openclaw onboard` ومنتقي النموذج. راجع [/providers/ollama](/ar/providers/ollama) -للاطلاع على التهيئة ووضع السحابة/الوضع المحلي والإعداد المخصص. +يتم اكتشاف Ollama محليًا على `http://127.0.0.1:11434` عند الاشتراك +عبر `OLLAMA_API_KEY`، وتضيف إضافة الموفر المجمّعة Ollama مباشرةً إلى +`openclaw onboard` وأداة اختيار النموذج. راجع [/providers/ollama](/ar/providers/ollama) +للاطلاع على التهيئة ووضع السحابة/المحلي والإعداد المخصص. ### vLLM -يأتي vLLM كإضافة مزوّد مضمّنة للخوادم المحلية/المستضافة ذاتيًا المتوافقة مع OpenAI: +يأتي vLLM كإضافة موفر مجمّعة للخوادم المحلية/المستضافة ذاتيًا +المتوافقة مع OpenAI: -- المزوّد: `vllm` +- الموفّر: `vllm` - المصادقة: اختيارية (بحسب خادمك) - عنوان URL الأساسي الافتراضي: `http://127.0.0.1:8000/v1` -للاشتراك في الاكتشاف التلقائي محليًا (أي قيمة تكفي إذا كان خادمك لا يفرض المصادقة): +للاشتراك في الاكتشاف التلقائي محليًا (أي قيمة تعمل إذا كان خادمك لا يفرض المصادقة): ```bash export VLLM_API_KEY="vllm-local" ``` -ثم عيّن نموذجًا (استبدله بأحد المعرّفات التي يعيدها `/v1/models`): +ثم قم بتعيين نموذج (استبدله بأحد المعرّفات المعادة من `/v1/models`): ```json5 { @@ -718,20 +722,21 @@ export VLLM_API_KEY="vllm-local" ### SGLang -يأتي SGLang كإضافة مزوّد مضمّنة للخوادم السريعة المتوافقة مع OpenAI والمستضافة ذاتيًا: +يأتي SGLang كإضافة موفر مجمّعة للخوادم السريعة المستضافة ذاتيًا +المتوافقة مع OpenAI: -- المزوّد: `sglang` +- الموفّر: `sglang` - المصادقة: اختيارية (بحسب خادمك) - عنوان URL الأساسي الافتراضي: `http://127.0.0.1:30000/v1` -للاشتراك في الاكتشاف التلقائي محليًا (أي قيمة تكفي إذا كان خادمك لا +للاشتراك في الاكتشاف التلقائي محليًا (أي قيمة تعمل إذا كان خادمك لا يفرض المصادقة): ```bash export SGLANG_API_KEY="sglang-local" ``` -ثم عيّن نموذجًا (استبدله بأحد المعرّفات التي يعيدها `/v1/models`): +ثم قم بتعيين نموذج (استبدله بأحد المعرّفات المعادة من `/v1/models`): ```json5 { @@ -743,7 +748,7 @@ export SGLANG_API_KEY="sglang-local" راجع [/providers/sglang](/ar/providers/sglang) للتفاصيل. -### الوكلاء المحليون (LM Studio و vLLM و LiteLLM وما إلى ذلك) +### الوكلاء المحليون (LM Studio وvLLM وLiteLLM وما إلى ذلك) مثال (متوافق مع OpenAI): @@ -780,20 +785,20 @@ export SGLANG_API_KEY="sglang-local" ملاحظات: -- بالنسبة إلى المزوّدين المخصصين، تكون `reasoning` و `input` و `cost` و `contextWindow` و `maxTokens` اختيارية. - وعند حذفها، يستخدم OpenClaw افتراضيًا: +- بالنسبة إلى الموفّرين المخصصين، تكون `reasoning` و`input` و`cost` و`contextWindow` و`maxTokens` اختيارية. + وعند حذفها، يستخدم OpenClaw الإعدادات الافتراضية التالية: - `reasoning: false` - `input: ["text"]` - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }` - `contextWindow: 200000` - `maxTokens: 8192` -- الموصى به: عيّن قيمًا صريحة تطابق حدود الوكيل/النموذج لديك. -- بالنسبة إلى `api: "openai-completions"` على نقاط النهاية غير الأصلية (أي `baseUrl` غير فارغ يكون مضيفه غير `api.openai.com`)، يفرض OpenClaw القيمة `compat.supportsDeveloperRole: false` لتجنب أخطاء 400 من المزوّد بسبب أدوار `developer` غير المدعومة. -- تتخطى أيضًا المسارات الوكيلة المتوافقة مع OpenAI تشكيل الطلبات الأصلي الخاص بـ OpenAI فقط: - لا `service_tier`، ولا Responses `store`، ولا تلميحات التخزين المؤقت للمطالبات، ولا - تشكيل الحمولة المتوافق مع تفكير OpenAI، ولا روؤس الإسناد المخفية الخاصة بـ OpenClaw. -- إذا كان `baseUrl` فارغًا/محذوفًا، فسيحتفظ OpenClaw بسلوك OpenAI الافتراضي (الذي يُحل إلى `api.openai.com`). -- لأسباب تتعلق بالأمان، ما تزال قيمة `compat.supportsDeveloperRole: true` الصريحة تُتجاوز على نقاط النهاية غير الأصلية `openai-completions`. +- الموصى به: تعيين قيم صريحة تطابق حدود الوكيل/النموذج لديك. +- بالنسبة إلى `api: "openai-completions"` على نقاط نهاية غير أصلية (أي `baseUrl` غير فارغ يكون مضيفه ليس `api.openai.com`)، يفرض OpenClaw القيمة `compat.supportsDeveloperRole: false` لتجنب أخطاء الموفّر 400 الخاصة بأدوار `developer` غير المدعومة. +- تتجاوز المسارات الوكيلة المتوافقة مع OpenAI أيضًا تهيئة الطلب الأصلية الخاصة بـ OpenAI فقط: + لا يوجد `service_tier`، ولا `store` في Responses، ولا تلميحات للتخزين المؤقت للمطالبة، ولا + تهيئة لحمولات توافق الاستدلال في OpenAI، ولا رؤوس إسناد مخفية خاصة بـ OpenClaw. +- إذا كان `baseUrl` فارغًا/غير محدد، يحتفظ OpenClaw بسلوك OpenAI الافتراضي (الذي يُحل إلى `api.openai.com`). +- من أجل الأمان، ما تزال القيمة الصريحة `compat.supportsDeveloperRole: true` تُتجاهل على نقاط النهاية غير الأصلية `openai-completions`. ## أمثلة CLI @@ -803,11 +808,11 @@ openclaw models set opencode/claude-opus-4-6 openclaw models list ``` -راجع أيضًا: [/gateway/configuration](/ar/gateway/configuration) للاطلاع على أمثلة الإعداد الكاملة. +راجع أيضًا: [/gateway/configuration](/ar/gateway/configuration) للحصول على أمثلة تكوين كاملة. ## ذو صلة -- [النماذج](/ar/concepts/models) — إعداد النموذج والأسماء المستعارة -- [التحويل الاحتياطي للنموذج](/ar/concepts/model-failover) — سلاسل الاحتياط وسلوك إعادة المحاولة -- [مرجع الإعدادات](/ar/gateway/configuration-reference#agent-defaults) — مفاتيح إعداد النموذج -- [المزوّدون](/ar/providers) — أدلة الإعداد لكل مزوّد +- [Models](/ar/concepts/models) — تكوين النموذج والأسماء المستعارة +- [Model Failover](/ar/concepts/model-failover) — سلاسل الاحتياط وسلوك إعادة المحاولة +- [Configuration Reference](/ar/gateway/configuration-reference#agent-defaults) — مفاتيح تكوين النموذج +- [Providers](/ar/providers) — أدلة الإعداد الخاصة بكل موفّر diff --git a/docs/ar/concepts/qa-e2e-automation.md b/docs/ar/concepts/qa-e2e-automation.md index e39c29a1e..d19e34002 100644 --- a/docs/ar/concepts/qa-e2e-automation.md +++ b/docs/ar/concepts/qa-e2e-automation.md @@ -1,37 +1,37 @@ --- read_when: - - تقوم بتوسيع qa-lab أو qa-channel - - تضيف سيناريوهات QA مدعومة من المستودع - - تبني أتمتة QA أكثر واقعية حول لوحة Gateway -summary: بنية أتمتة QA الخاصة لـ qa-lab وqa-channel والسيناريوهات المزروعة وتقارير البروتوكول -title: أتمتة QA الشاملة من الطرف إلى الطرف + - عند توسيع qa-lab أو qa-channel + - عند إضافة سيناريوهات QA مدعومة بالمستودع + - عند بناء أتمتة QA أكثر واقعية حول لوحة تحكم Gateway +summary: شكل أتمتة QA الخاص لـ qa-lab وqa-channel والسيناريوهات المُهيأة مسبقًا وتقارير البروتوكول +title: أتمتة QA من طرف إلى طرف x-i18n: - generated_at: "2026-04-07T07:16:41Z" + generated_at: "2026-04-08T02:14:02Z" model: gpt-5.4 provider: openai - source_hash: 113e89d8d3ee8ef3058d95b9aea9a1c2335b07794446be2d231c0faeb044b23b + source_hash: 3b4aa5acc8e77303f4045d4f04372494cae21b89d2fdaba856dbb4855ced9d27 source_path: concepts/qa-e2e-automation.md workflow: 15 --- -# أتمتة QA الشاملة من الطرف إلى الطرف +# أتمتة QA من طرف إلى طرف -تهدف حزمة QA الخاصة إلى اختبار OpenClaw بطريقة أكثر واقعية، -وأقرب إلى شكل القنوات، مما يمكن أن يحققه اختبار وحدة واحد. +تهدف حزمة QA الخاصة إلى اختبار OpenClaw بطريقة أكثر واقعية +ومشابهة للقنوات مما يمكن أن يقدمه اختبار وحدة واحد. المكونات الحالية: -- `extensions/qa-channel`: قناة رسائل اصطناعية بواجهات للرسائل الخاصة، والقنوات، وسلاسل المحادثة، - والتفاعلات، والتعديل، والحذف. -- `extensions/qa-lab`: واجهة تصحيح وحافلة QA لمراقبة النص، - وحقن الرسائل الواردة، وتصدير تقرير Markdown. -- `qa/`: أصول زرع مدعومة من المستودع لمهمة الانطلاق وسيناريوهات QA +- `extensions/qa-channel`: قناة رسائل اصطناعية مع أسطح DM والقناة والخيط + والتفاعل والتعديل والحذف. +- `extensions/qa-lab`: واجهة مستخدم للتصحيح وناقل QA لمراقبة السجل، + وإدخال الرسائل الواردة، وتصدير تقرير Markdown. +- `qa/`: أصول تهيئة مدعومة بالمستودع لمهمة البداية وسيناريوهات QA الأساسية. -التدفق الحالي لمشغل QA هو موقع QA ذو لوحتين: +مسار عمل مشغل QA الحالي هو موقع QA بلوحتين: -- اليسار: لوحة Gateway (واجهة التحكم) مع العامل. -- اليمين: QA Lab، وتعرض النص الشبيه بـ Slack وخطة السيناريو. +- اليسار: لوحة تحكم Gateway (Control UI) مع الوكيل. +- اليمين: QA Lab، يعرض السجل الشبيه بـ Slack وخطة السيناريو. شغّله باستخدام: @@ -39,44 +39,57 @@ x-i18n: pnpm qa:lab:up ``` -يقوم ذلك ببناء موقع QA، وبدء مسار Gateway المدعوم بـ Docker، وإتاحة -صفحة QA Lab حيث يمكن لمشغل أو لحلقة أتمتة إعطاء العامل +يقوم ذلك ببناء موقع QA، وبدء مسار Gateway المعتمد على Docker، وإتاحة +صفحة QA Lab حيث يمكن لمشغل أو حلقة أتمتة إعطاء الوكيل مهمة QA، ومراقبة سلوك القناة الفعلي، وتسجيل ما نجح، وما فشل، وما -ظل معطّلًا. +بقي معطّلًا. -## البذور المدعومة من المستودع +لتحسين سرعة التكرار على واجهة QA Lab دون إعادة بناء صورة Docker في كل مرة، +ابدأ الحزمة باستخدام حزمة QA Lab مركّبة عبر bind mount: -توجد أصول البذور في `qa/`: +```bash +pnpm openclaw qa docker-build-image +pnpm qa:lab:build +pnpm qa:lab:up:fast +pnpm qa:lab:watch +``` -- `qa/QA_KICKOFF_TASK.md` -- `qa/seed-scenarios.json` +يبقي `qa:lab:up:fast` خدمات Docker على صورة مبنية مسبقًا ويستخدم bind mount +للدليل `extensions/qa-lab/web/dist` داخل حاوية `qa-lab`. ويقوم `qa:lab:watch` +بإعادة بناء تلك الحزمة عند التغيير، ويُعاد تحميل المتصفح تلقائيًا عندما تتغير +بصمة أصول QA Lab. + +## التهيئات المدعومة بالمستودع + +توجد أصول التهيئة في `qa/`: + +- `qa/scenarios.md` هذه الملفات موجودة عمدًا في git بحيث تكون خطة QA مرئية لكل من البشر -والعامل. يجب أن تبقى القائمة الأساسية واسعة بما يكفي لتغطية: +والوكيل. يجب أن تظل القائمة الأساسية واسعة بما يكفي لتغطية: -- المحادثات الخاصة ومحادثات القنوات -- سلوك سلاسل المحادثة +- محادثات DM والقنوات +- سلوك الخيوط - دورة حياة إجراءات الرسائل - استدعاءات cron - استرجاع الذاكرة - تبديل النماذج -- تسليم المهام إلى عامل فرعي +- تمرير العمل إلى وكيل فرعي - قراءة المستودع وقراءة الوثائق - مهمة بناء صغيرة مثل Lobster Invaders ## إعداد التقارير -يصدر `qa-lab` تقرير بروتوكول بصيغة Markdown من الخط الزمني -للحافلة التي تمت ملاحظتها. +يصدر `qa-lab` تقرير بروتوكول Markdown من المخطط الزمني للناقل المرصود. يجب أن يجيب التقرير عن: - ما الذي نجح - ما الذي فشل -- ما الذي ظل معطّلًا +- ما الذي بقي معطّلًا - ما سيناريوهات المتابعة التي تستحق الإضافة -## وثائق ذات صلة +## الوثائق ذات الصلة - [الاختبار](/ar/help/testing) -- [QA Channel](/ar/channels/qa-channel) +- [قناة QA](/ar/channels/qa-channel) - [لوحة التحكم](/web/dashboard) diff --git a/docs/ar/concepts/system-prompt.md b/docs/ar/concepts/system-prompt.md index 7f493ba46..08ab56f94 100644 --- a/docs/ar/concepts/system-prompt.md +++ b/docs/ar/concepts/system-prompt.md @@ -1,104 +1,104 @@ --- read_when: - - تحرير نص system prompt، أو قائمة الأدوات، أو أقسام الوقت/Heartbeat - - تغيير سلوك تهيئة مساحة العمل أو حقن Skills -summary: ما الذي يحتويه system prompt في OpenClaw وكيفية تجميعه -title: System Prompt + - عند تحرير نص موجّه النظام أو قائمة الأدوات أو أقسام الوقت/النبضات + - عند تغيير سلوك تهيئة مساحة العمل أو حقن Skills +summary: ما الذي يتضمنه موجّه نظام OpenClaw وكيفية تجميعه +title: موجّه النظام x-i18n: - generated_at: "2026-04-06T03:07:26Z" + generated_at: "2026-04-08T02:14:45Z" model: gpt-5.4 provider: openai - source_hash: f14ba7f16dda81ac973d72be05931fa246bdfa0e1068df1a84d040ebd551c236 + source_hash: e55fc886bc8ec47584d07c9e60dfacd964dc69c7db976ea373877dc4fe09a79a source_path: concepts/system-prompt.md workflow: 15 --- -# System Prompt +# موجّه النظام -يبني OpenClaw system prompt مخصصًا لكل تشغيل وكيل. ويكون prompt **مملوكًا لـ OpenClaw** ولا يستخدم prompt الافتراضي الخاص بـ pi-coding-agent. +يبني OpenClaw موجّه نظام مخصصًا لكل تشغيل وكيل. هذا الموجّه **مملوك لـ OpenClaw** ولا يستخدم الموجّه الافتراضي لـ pi-coding-agent. -يُجمَّع prompt بواسطة OpenClaw ويُحقن في كل تشغيل وكيل. +يتم تجميع الموجّه بواسطة OpenClaw وحقنه في كل تشغيل وكيل. -يمكن لإضافات المزوّدين المساهمة بإرشادات prompt واعية بالتخزين المؤقت من دون استبدال -prompt الكامل المملوك لـ OpenClaw. ويمكن لوقت تشغيل المزوّد: +يمكن لإضافات المزوّدين المساهمة بإرشادات موجّه تراعي الذاكرة المؤقتة دون استبدال +موجّه OpenClaw الكامل المملوك له. ويمكن لوقت تشغيل المزوّد أن يقوم بما يلي: -- استبدال مجموعة صغيرة من الأقسام الأساسية المسمّاة (`interaction_style`, +- استبدال مجموعة صغيرة من الأقسام الأساسية المسماة (`interaction_style`, `tool_call_style`, `execution_bias`) -- حقن **بادئة مستقرة** فوق حد التخزين المؤقت للـ prompt -- حقن **لاحقة ديناميكية** تحت حد التخزين المؤقت للـ prompt +- حقن **بادئة ثابتة** فوق حد الذاكرة المؤقتة للموجّه +- حقن **لاحقة ديناميكية** أسفل حد الذاكرة المؤقتة للموجّه -استخدم المساهمات المملوكة للمزوّد من أجل الضبط الخاص بعائلات النماذج. وأبقِ -تعديل prompt القديم `before_prompt_build` للتوافق أو لتغييرات prompt -العالمية فعلًا، لا لسلوك المزوّد المعتاد. +استخدم المساهمات المملوكة للمزوّد لضبط السلوك الخاص بعائلة النموذج. واحتفِظ +بتعديل الموجّه القديم `before_prompt_build` من أجل التوافق أو التغييرات العامة +الحقيقية على الموجّه، وليس لسلوك المزوّد العادي. ## البنية -يُبنى prompt ليكون مضغوطًا عمدًا ويستخدم أقسامًا ثابتة: +الموجّه مضغوط عمدًا ويستخدم أقسامًا ثابتة: -- **الأدوات**: تذكير بالمصدر المرجعي للحقيقة للأدوات المهيكلة، بالإضافة إلى إرشادات وقت التشغيل لاستخدام الأدوات. -- **السلامة**: تذكير قصير بالضوابط لتجنب سلوك السعي إلى السلطة أو تجاوز الإشراف. -- **Skills** (عند توفرها): يوضح للنموذج كيفية تحميل تعليمات Skill عند الطلب. -- **التحديث الذاتي لـ OpenClaw**: كيفية فحص config بأمان باستخدام - `config.schema.lookup`، وتصحيح config باستخدام `config.patch`، واستبدال - config كاملًا باستخدام `config.apply`، وتشغيل `update.run` فقط عند طلب - صريح من المستخدم. كما أن أداة `gateway` الخاصة بالمالك فقط ترفض أيضًا +- **الأدوات**: تذكير منظّم بمصدر الحقيقة للأدوات المنظمة بالإضافة إلى إرشادات وقت التشغيل لاستخدام الأدوات. +- **السلامة**: تذكير قصير بالضوابط لتجنب السلوك الساعي إلى القوة أو تجاوز الإشراف. +- **Skills**: (عند توفرها): يوضح للنموذج كيفية تحميل تعليمات المهارة عند الطلب. +- **التحديث الذاتي لـ OpenClaw**: كيفية فحص الإعدادات بأمان باستخدام + `config.schema.lookup`، وتصحيح الإعدادات باستخدام `config.patch`، واستبدال + الإعدادات كاملة باستخدام `config.apply`، وتشغيل `update.run` فقط عند طلب + المستخدم بشكل صريح. كما أن أداة `gateway` المخصّصة للمالك فقط ترفض أيضًا إعادة كتابة `tools.exec.ask` / `tools.exec.security`، بما في ذلك الأسماء - البديلة القديمة `tools.bash.*` التي تُطبَّع إلى مسارات exec المحمية تلك. + المستعارة القديمة `tools.bash.*` التي تُطبّع إلى مسارات exec المحمية تلك. - **مساحة العمل**: دليل العمل (`agents.defaults.workspace`). -- **التوثيق**: المسار المحلي إلى مستندات OpenClaw (في المستودع أو حزمة npm) ومتى يجب قراءتها. +- **الوثائق**: المسار المحلي إلى وثائق OpenClaw (المستودع أو حزمة npm) ومتى يجب قراءتها. - **ملفات مساحة العمل (محقونة)**: تشير إلى أن ملفات التهيئة الأولية مضمنة أدناه. -- **Sandbox** (عند التمكين): يشير إلى وقت تشغيل معزول، ومسارات sandbox، وما إذا كان exec المرتفع الصلاحيات متاحًا. +- **Sandbox**: (عند التمكين): تشير إلى بيئة تشغيل معزولة، ومسارات sandbox، وما إذا كان exec المرتفع الصلاحيات متاحًا. - **التاريخ والوقت الحاليان**: الوقت المحلي للمستخدم، والمنطقة الزمنية، وتنسيق الوقت. -- **وسوم الرد**: صياغة وسوم الرد الاختيارية للمزوّدين المدعومين. -- **Heartbeats**: prompt الخاص بـ heartbeat وسلوك الإقرار. +- **وسوم الرد**: صيغة وسوم الرد الاختيارية للمزوّدين المدعومين. +- **النبضات**: موجّه النبضات وسلوك الإقرار، عند تمكين النبضات للوكيل الافتراضي. - **وقت التشغيل**: المضيف، ونظام التشغيل، وnode، والنموذج، وجذر المستودع (عند اكتشافه)، ومستوى التفكير (سطر واحد). -- **الاستدلال**: مستوى الظهور الحالي + تلميح تبديل `/reasoning`. +- **الاستدلال**: مستوى الرؤية الحالي + تلميح تبديل `/reasoning`. -يتضمن قسم الأدوات أيضًا إرشادات وقت التشغيل للأعمال طويلة التنفيذ: +يتضمن قسم الأدوات أيضًا إرشادات وقت التشغيل للأعمال طويلة التشغيل: - استخدم cron للمتابعة المستقبلية (`check back later`، والتذكيرات، والعمل المتكرر) - بدلًا من حلقات النوم عبر `exec`، أو حيل التأخير `yieldMs`، أو الاستطلاع المتكرر - لـ `process` + بدلًا من حلقات السكون عبر `exec`، أو حيل التأخير `yieldMs`، أو الاستطلاع + المتكرر لـ `process` - استخدم `exec` / `process` فقط للأوامر التي تبدأ الآن وتستمر في العمل في الخلفية -- عندما يكون إيقاظ الإكمال التلقائي ممكّنًا، ابدأ الأمر مرة واحدة واعتمد على - مسار الإيقاظ القائم على الدفع عندما يُخرج مخرجات أو يفشل +- عند تمكين تنبيه الإكمال التلقائي، ابدأ الأمر مرة واحدة واعتمد على + مسار التنبيه المعتمد على الدفع عندما يصدر مخرجات أو يفشل - استخدم `process` للسجلات، أو الحالة، أو الإدخال، أو التدخل عندما تحتاج إلى فحص أمر قيد التشغيل -- إذا كانت المهمة أكبر، ففضّل `sessions_spawn`; إذ إن إكمال الوكيل الفرعي - قائم على الدفع ويُعلَن تلقائيًا إلى الطالب -- لا تستطلع `subagents list` / `sessions_list` في حلقة لمجرد انتظار - الإكمال +- إذا كانت المهمة أكبر، ففضّل `sessions_spawn`؛ إذ إن إكمال الوكيل الفرعي + يعتمد على الدفع ويُعلن تلقائيًا إلى الجهة الطالبة +- لا تستطلع `subagents list` / `sessions_list` ضمن حلقة لمجرد انتظار + الاكتمال -عند تمكين أداة `update_plan` التجريبية، يخبر قسم الأدوات أيضًا -النموذج باستخدامها فقط للأعمال متعددة الخطوات غير التافهة، مع الإبقاء على -خطوة واحدة `in_progress` بالضبط، وتجنب تكرار الخطة كاملة بعد كل تحديث. +عند تمكين الأداة التجريبية `update_plan`، يوضح قسم الأدوات أيضًا +للنموذج أن يستخدمها فقط للأعمال متعددة الخطوات غير البسيطة، وأن يُبقي +خطوة واحدة فقط بحالة `in_progress`، وأن يتجنب تكرار الخطة كاملة بعد كل تحديث. -إن ضوابط السلامة في system prompt إرشادية. فهي توجه سلوك النموذج لكنها لا تفرض سياسة. استخدم سياسة الأدوات، وموافقات exec، وsandboxing، وقوائم السماح الخاصة بالقنوات لفرض القيود الصارمة؛ ويمكن للمشغّلين تعطيل هذه الأمور عمدًا. +ضوابط السلامة في موجّه النظام إرشادية. فهي توجه سلوك النموذج لكنها لا تفرض سياسة. استخدم سياسة الأدوات، وموافقات exec، وsandboxing، وقوائم السماح للقنوات من أجل فرض صارم؛ ويمكن للمشغلين تعطيل هذه الأشياء عمدًا. -في القنوات التي تحتوي على بطاقات/أزرار موافقة أصلية، يوجّه prompt وقت التشغيل الآن -الوكيل إلى الاعتماد أولًا على واجهة الموافقة الأصلية تلك. ولا ينبغي له تضمين -أمر `/approve` يدوي إلا عندما تشير نتيجة الأداة إلى أن موافقات الدردشة غير متاحة أو +في القنوات التي تحتوي على بطاقات/أزرار موافقة أصلية، يخبر موجّه وقت التشغيل الآن +الوكيل بالاعتماد أولًا على واجهة الموافقة الأصلية تلك. ويجب عليه تضمين +أمر `/approve` يدوي فقط عندما تشير نتيجة الأداة إلى أن موافقات الدردشة غير متاحة أو أن الموافقة اليدوية هي المسار الوحيد. -## أوضاع prompt +## أوضاع الموجّه -يمكن لـ OpenClaw توليد system prompt أصغر للوكلاء الفرعيين. ويضبط وقت التشغيل -`promptMode` لكل تشغيل (وليس إعدادًا ظاهرًا للمستخدم): +يمكن لـ OpenClaw عرض موجّهات نظام أصغر للوكلاء الفرعيين. ويضبط وقت التشغيل +`promptMode` لكل تشغيل (وليس إعدادًا موجّهًا للمستخدم): - `full` (الافتراضي): يتضمن جميع الأقسام أعلاه. -- `minimal`: يُستخدم للوكلاء الفرعيين؛ ويُسقط **Skills**، و**استدعاء الذاكرة**، و**التحديث الذاتي لـ OpenClaw**، و**أسماء النماذج البديلة**، و**هوية المستخدم**، و**وسوم الرد**، - و**المراسلة**، و**الردود الصامتة**، و**Heartbeats**. وتبقى الأدوات، و**السلامة**، - ومساحة العمل، وSandbox، و**التاريخ والوقت الحاليان** (عند المعرفة)، ووقت التشغيل، والسياق +- `minimal`: يُستخدم للوكلاء الفرعيين؛ ويحذف **Skills**، و**استدعاء الذاكرة**، و**التحديث الذاتي لـ OpenClaw**، و**الأسماء المستعارة للنماذج**، و**هوية المستخدم**، و**وسوم الرد**، + و**المراسلة**، و**الردود الصامتة**، و**النبضات**. وتبقى الأدوات، و**السلامة**، + ومساحة العمل، وSandbox، والتاريخ والوقت الحاليان (عند معرفتهما)، ووقت التشغيل، والسياق المحقون متاحة. - `none`: يعيد فقط سطر الهوية الأساسي. -عندما يكون `promptMode=minimal`، تُسمّى الـ prompts المحقونة الإضافية **سياق الوكيل الفرعي** +عندما يكون `promptMode=minimal`، تُوسم الموجّهات الإضافية المحقونة باسم **سياق الوكيل الفرعي** بدلًا من **سياق الدردشة الجماعية**. -## حقن تهيئة مساحة العمل +## حقن تهيئة مساحة العمل الأولية -تُقص ملفات التهيئة الأولية وتُلحَق تحت **سياق المشروع** حتى يرى النموذج سياق الهوية والملف الشخصي من دون الحاجة إلى قراءات صريحة: +تُقص ملفات التهيئة الأولية وتُلحق ضمن **سياق المشروع** حتى يرى النموذج سياق الهوية والملف الشخصي من دون الحاجة إلى قراءات صريحة: - `AGENTS.md` - `SOUL.md` @@ -106,63 +106,67 @@ prompt الكامل المملوك لـ OpenClaw. ويمكن لوقت تشغيل - `IDENTITY.md` - `USER.md` - `HEARTBEAT.md` -- `BOOTSTRAP.md` (في مساحات العمل الجديدة تمامًا فقط) +- `BOOTSTRAP.md` (فقط في مساحات العمل الجديدة تمامًا) - `MEMORY.md` عند وجوده، وإلا `memory.md` كبديل بأحرف صغيرة -تُحقن كل هذه الملفات **في نافذة السياق** في كل دورة، ما -يعني أنها تستهلك tokens. أبقِها موجزة — خصوصًا `MEMORY.md`، الذي يمكن أن -يكبر مع الوقت ويؤدي إلى استخدام سياق أعلى من المتوقع وإلى ضغط أكثر تكرارًا. +تُحقن جميع هذه الملفات **في نافذة السياق** في كل دور ما لم +ينطبق قيد خاص بملف معين. ويتم حذف `HEARTBEAT.md` في التشغيلات العادية عندما +تكون النبضات معطلة للوكيل الافتراضي أو عندما يكون +`agents.defaults.heartbeat.includeSystemPromptSection` مضبوطًا على false. احرص على أن تبقى الملفات +المحقونة موجزة — وخاصة `MEMORY.md`، الذي يمكن أن ينمو بمرور الوقت ويؤدي إلى +استخدام مرتفع للسياق بشكل غير متوقع وتكثيف أكثر تكرارًا. -> **ملاحظة:** لا تُحقن ملفات `memory/*.md` اليومية **تلقائيًا**. بل -> يُوصَل إليها عند الطلب عبر الأداتين `memory_search` و`memory_get`، لذلك فهي -> لا تُحتسب ضمن نافذة السياق ما لم يقرأها النموذج صراحةً. +> **ملاحظة:** لا تُحقن الملفات اليومية `memory/*.md` **تلقائيًا**. بل +> يتم الوصول إليها عند الطلب عبر الأداتين `memory_search` و `memory_get`، لذلك فهي +> لا تُحتسب ضمن نافذة السياق ما لم يقم النموذج بقراءتها صراحة. -تُقتطع الملفات الكبيرة مع واسم. ويُتحكَّم في الحد الأقصى لحجم كل ملف عبر -`agents.defaults.bootstrapMaxChars` (الافتراضي: 20000). كما أن إجمالي محتوى التهيئة الأولية -المحقون عبر الملفات مقيّد بواسطة `agents.defaults.bootstrapTotalMaxChars` -(الافتراضي: 150000). وتحقن الملفات المفقودة واسمًا قصيرًا يدل على غياب الملف. وعند حدوث الاقتطاع، -يمكن لـ OpenClaw حقن كتلة تحذير في سياق المشروع؛ تحكم في ذلك باستخدام -`agents.defaults.bootstrapPromptTruncationWarning` ‏(`off` أو `once` أو `always`؛ +تُقتطع الملفات الكبيرة مع علامة. ويتم التحكم في الحد الأقصى لحجم كل ملف عبر +`agents.defaults.bootstrapMaxChars` (الافتراضي: 20000). كما يُحدَّد إجمالي +محتوى التهيئة الأولية المحقون عبر الملفات بواسطة `agents.defaults.bootstrapTotalMaxChars` +(الافتراضي: 150000). وتحقن الملفات المفقودة علامة قصيرة تدل على غياب الملف. وعند حدوث الاقتطاع، +يمكن لـ OpenClaw حقن كتلة تحذير ضمن سياق المشروع؛ ويمكن التحكم في ذلك عبر +`agents.defaults.bootstrapPromptTruncationWarning` (`off`، `once`، `always`؛ الافتراضي: `once`). -لا تحقن جلسات الوكلاء الفرعيين إلا `AGENTS.md` و`TOOLS.md` (أما بقية ملفات التهيئة الأولية -فتُستبعد للحفاظ على صغر سياق الوكيل الفرعي). +تقوم جلسات الوكيل الفرعي بحقن `AGENTS.md` و`TOOLS.md` فقط (وتتم +تصفية ملفات التهيئة الأولية الأخرى للحفاظ على صغر سياق الوكيل الفرعي). -يمكن للـ hooks الداخلية اعتراض هذه الخطوة عبر `agent:bootstrap` لتعديل أو استبدال +يمكن للخطافات الداخلية اعتراض هذه الخطوة عبر `agent:bootstrap` لتعديل أو استبدال ملفات التهيئة الأولية المحقونة (على سبيل المثال استبدال `SOUL.md` بشخصية بديلة). -إذا كنت تريد أن تجعل الوكيل يبدو أقل عمومية، فابدأ من +إذا كنت تريد أن تجعل الوكيل يبدو أقل عمومية، فابدأ بـ [دليل شخصية SOUL.md](/ar/concepts/soul). لفحص مقدار مساهمة كل ملف محقون (الخام مقابل المحقون، والاقتطاع، بالإضافة إلى الحمل الزائد لمخطط الأداة)، استخدم `/context list` أو `/context detail`. راجع [السياق](/ar/concepts/context). ## التعامل مع الوقت -يتضمن system prompt قسم **التاريخ والوقت الحاليان** مخصصًا عندما تكون -المنطقة الزمنية للمستخدم معروفة. وللحفاظ على استقرار التخزين المؤقت للـ prompt، فهو الآن يتضمن -**المنطقة الزمنية** فقط (من دون ساعة ديناميكية أو تنسيق وقت). +يتضمن موجّه النظام قسم **التاريخ والوقت الحاليان** مخصصًا عندما تكون +المنطقة الزمنية للمستخدم معروفة. وللحفاظ على ثبات الذاكرة المؤقتة للموجّه، فإنه الآن يتضمن فقط +**المنطقة الزمنية** (من دون ساعة ديناميكية أو تنسيق وقت). -استخدم `session_status` عندما يحتاج الوكيل إلى الوقت الحالي؛ إذ تتضمن بطاقة الحالة سطر طابع زمني. ويمكن للأداة نفسها أيضًا تعيين تجاوز نموذج لكل جلسة -(`model=default` يمسحه). +استخدم `session_status` عندما يحتاج الوكيل إلى الوقت الحالي؛ إذ تتضمن +بطاقة الحالة سطرًا زمنيًا. ويمكن للأداة نفسها اختياريًا تعيين تجاوز نموذج +لكل جلسة (`model=default` يمسحه). اضبط ذلك باستخدام: - `agents.defaults.userTimezone` -- `agents.defaults.timeFormat` ‏(`auto` | `12` | `24`) +- `agents.defaults.timeFormat` (`auto` | `12` | `24`) -راجع [التاريخ والوقت](/ar/date-time) للحصول على التفاصيل الكاملة للسلوك. +راجع [التاريخ والوقت](/ar/date-time) للحصول على تفاصيل السلوك الكاملة. ## Skills -عندما توجد Skills مؤهلة، يحقن OpenClaw **قائمة Skills متاحة مضغوطة** +عند وجود Skills مؤهلة، يحقن OpenClaw **قائمة Skills متاحة** مضغوطة (`formatSkillsForPrompt`) تتضمن **مسار الملف** لكل Skill. ويوجه -prompt النموذج إلى استخدام `read` لتحميل ملف SKILL.md من الموقع المدرج -(مساحة العمل، أو المُدارة، أو المجمّعة). وإذا لم تكن هناك Skills مؤهلة، فسيُحذف +الموجّه النموذج إلى استخدام `read` لتحميل ملف SKILL.md في الموقع المدرج +(مساحة العمل، أو المُدار، أو المضمَّن). وإذا لم توجد Skills مؤهلة، فسيتم حذف قسم Skills. -تشمل الأهلية بوابات بيانات Skill الوصفية، وفحوصات بيئة/إعداد وقت التشغيل، -وقائمة السماح الفعلية لـ Skills الخاصة بالوكيل عندما يكون `agents.defaults.skills` أو -`agents.list[].skills` مُكوَّنًا. +تتضمن الأهلية بوابات بيانات تعريف المهارة، وفحوصات بيئة/إعدادات وقت التشغيل، +وقائمة السماح الفعالة لـ Skills الخاصة بالوكيل عندما يكون `agents.defaults.skills` أو +`agents.list[].skills` مضبوطًا. ``` @@ -174,13 +178,13 @@ prompt النموذج إلى استخدام `read` لتحميل ملف SKILL.md ``` -يُبقي هذا prompt الأساسي صغيرًا مع الاستمرار في تمكين استخدام Skill المستهدف. +يحافظ هذا على صغر الموجّه الأساسي مع الاستمرار في تمكين استخدام مستهدف للمهارات. -## التوثيق +## الوثائق -عند توفره، يتضمن system prompt قسم **التوثيق** الذي يشير إلى -دليل مستندات OpenClaw المحلي (إما `docs/` في مساحة عمل المستودع أو مستندات حزمة npm -المجمّعة) ويذكر أيضًا النسخة العامة المطابقة، ومستودع المصدر، وDiscord الخاص بالمجتمع، -وClawHub ([https://clawhub.ai](https://clawhub.ai)) لاكتشاف Skills. ويوجه prompt النموذج إلى الرجوع إلى المستندات المحلية أولًا -لفهم سلوك OpenClaw، أو الأوامر، أو الإعدادات، أو البنية، وإلى تشغيل -`openclaw status` بنفسه عند الإمكان (وسؤال المستخدم فقط عندما لا يملك الوصول). +عند توفرها، يتضمن موجّه النظام قسم **الوثائق** الذي يشير إلى +دليل وثائق OpenClaw المحلي (إما `docs/` في مساحة عمل المستودع أو وثائق حزمة npm +المضمَّنة) ويشير أيضًا إلى النسخة العامة، ومستودع المصدر، وDiscord الخاص بالمجتمع، و +ClawHub ([https://clawhub.ai](https://clawhub.ai)) لاكتشاف Skills. ويوجه الموجّه النموذج إلى الرجوع إلى الوثائق المحلية أولًا +لسلوك OpenClaw، أو الأوامر، أو الإعدادات، أو البنية، وأن يشغّل +`openclaw status` بنفسه عندما يكون ذلك ممكنًا (وألا يسأل المستخدم إلا عندما يفتقر إلى الوصول). diff --git a/docs/ar/gateway/cli-backends.md b/docs/ar/gateway/cli-backends.md index 3418100a5..086693f92 100644 --- a/docs/ar/gateway/cli-backends.md +++ b/docs/ar/gateway/cli-backends.md @@ -2,46 +2,46 @@ read_when: - تريد بديلًا موثوقًا عندما يفشل موفرو API - أنت تشغّل Codex CLI أو غيره من واجهات AI CLI المحلية وتريد إعادة استخدامها - - تريد فهم جسر local loopback MCP لوصول أدوات الواجهة الخلفية CLI -summary: 'واجهات CLI الخلفية: بديل محلي لـ AI CLI مع جسر أدوات MCP اختياري' + - تريد فهم جسر MCP المحلي loopback للوصول إلى أدوات الواجهة الخلفية لـ CLI +summary: 'واجهات CLI الخلفية: بديل محلي لـ AI CLI مع جسر أداة MCP اختياري' title: واجهات CLI الخلفية x-i18n: - generated_at: "2026-04-07T07:17:29Z" + generated_at: "2026-04-08T02:14:26Z" model: gpt-5.4 provider: openai - source_hash: f061357f420455ad6ffaabe7fe28f1fb1b1769d73a4eb2e6f45c6eb3c2e36667 + source_hash: b0e8c41f5f5a8e34466f6b765e5c08585ef1788fa9e9d953257324bcc6cbc414 source_path: gateway/cli-backends.md workflow: 15 --- -# واجهات CLI الخلفية (بيئة تشغيل احتياطية) +# واجهات CLI الخلفية (بيئة تشغيل بديلة) -يمكن لـ OpenClaw تشغيل **واجهات AI CLI محلية** كـ **بديل نصي فقط** عندما تتعطل موفرو API، -أو تُقيَّد بالمعدل، أو تسيء التصرف مؤقتًا. هذا النهج متحفظ عمدًا: +يمكن لـ OpenClaw تشغيل **واجهات AI CLI المحلية** كـ **بديل نصي فقط** عندما تتعطل موفرو API، +أو تُفرض عليها حدود معدلات، أو تتصرف بشكل غير سليم مؤقتًا. هذا النهج محافظ عن قصد: -- **لا يتم حقن أدوات OpenClaw مباشرة**، لكن الواجهات الخلفية التي تحتوي على `bundleMcp: true` - يمكنها تلقي أدوات gateway عبر جسر MCP من نوع local loopback. +- **لا يتم حقن أدوات OpenClaw مباشرةً**، لكن يمكن للواجهات الخلفية التي تستخدم `bundleMcp: true` + أن تتلقى أدوات البوابة عبر جسر MCP محلي loopback. - **بث JSONL** لواجهات CLI التي تدعمه. -- **الجلسات مدعومة** (بحيث تبقى المنعطفات اللاحقة متماسكة). -- **يمكن تمرير الصور** إذا كانت واجهة CLI تقبل مسارات الصور. +- **الجلسات مدعومة** (حتى تظل المنعطفات اللاحقة مترابطة). +- **يمكن تمرير الصور** إذا كانت CLI تقبل مسارات الصور. -تم تصميم ذلك ليكون **شبكة أمان** بدلًا من كونه مسارًا أساسيًا. استخدمه عندما -تريد ردودًا نصية "تعمل دائمًا" من دون الاعتماد على API خارجية. +هذا مصمم ليكون **شبكة أمان** بدلًا من أن يكون مسارًا أساسيًا. استخدمه عندما +تريد ردودًا نصية "تعمل دائمًا" من دون الاعتماد على واجهات API خارجية. -إذا كنت تريد بيئة تشغيل كاملة مع عناصر تحكم جلسات ACP، والمهام الخلفية، -وربط الخيوط/المحادثات، وجلسات ترميز خارجية دائمة، فاستخدم -[ACP Agents](/ar/tools/acp-agents) بدلًا من ذلك. واجهات CLI الخلفية ليست ACP. +إذا كنت تريد بيئة تشغيل كاملة مع عناصر تحكم جلسات ACP، والمهام في الخلفية، +وربط السلاسل/المحادثات، وجلسات برمجة خارجية دائمة، فاستخدم +[وكلاء ACP](/ar/tools/acp-agents) بدلًا من ذلك. واجهات CLI الخلفية ليست ACP. ## بداية سريعة مناسبة للمبتدئين -يمكنك استخدام Codex CLI **من دون أي إعدادات** (يسجل plugin OpenAI -المضمن واجهة خلفية افتراضية): +يمكنك استخدام Codex CLI **من دون أي إعداد** (إذ إن إضافة OpenAI المضمّنة +تسجّل واجهة خلفية افتراضية): ```bash openclaw agent --message "hi" --model codex-cli/gpt-5.4 ``` -إذا كانت gateway تعمل تحت launchd/systemd وكان PATH محدودًا، فأضف فقط +إذا كانت بوابتك تعمل تحت launchd/systemd وكان PATH محدودًا، فأضف فقط مسار الأمر: ```json5 @@ -58,16 +58,16 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4 } ``` -هذا كل شيء. لا مفاتيح، ولا حاجة إلى إعدادات مصادقة إضافية تتجاوز ما تتطلبه CLI نفسها. +هذا كل شيء. لا حاجة إلى مفاتيح أو إعدادات مصادقة إضافية خارج ما تتطلبه CLI نفسها. -إذا كنت تستخدم واجهة CLI خلفية مضمنة باعتبارها **موفر الرسائل الأساسي** على -مضيف gateway، فإن OpenClaw يحمّل الآن تلقائيًا plugin المضمن المالك عندما -تشير إعداداتك صراحةً إلى تلك الواجهة الخلفية في مرجع نموذج أو تحت +إذا كنت تستخدم واجهة CLI خلفية مضمّنة باعتبارها **موفر الرسائل الأساسي** على +مضيف بوابة، فإن OpenClaw يحمّل الآن الإضافة المضمّنة المالكة تلقائيًا عندما يشير إعدادك +صراحةً إلى تلك الواجهة الخلفية في مرجع نموذج أو تحت `agents.defaults.cliBackends`. ## استخدامه كبديل احتياطي -أضف واجهة CLI خلفية إلى قائمة البدائل الاحتياطية لديك بحيث تعمل فقط عند فشل النماذج الأساسية: +أضف واجهة CLI خلفية إلى قائمة البدائل لديك بحيث لا تعمل إلا عندما تفشل النماذج الأساسية: ```json5 { @@ -88,11 +88,11 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4 ملاحظات: -- إذا كنت تستخدم `agents.defaults.models` (قائمة السماح)، فيجب أن تتضمن نماذج واجهات CLI الخلفية هناك أيضًا. -- إذا فشل الموفر الأساسي (المصادقة، أو حدود المعدل، أو انتهاء المهلة)، فسيحاول OpenClaw - استخدام واجهة CLI الخلفية بعد ذلك. +- إذا كنت تستخدم `agents.defaults.models` (قائمة سماح)، فيجب تضمين نماذج واجهة CLI الخلفية هناك أيضًا. +- إذا فشل الموفر الأساسي (المصادقة أو حدود المعدلات أو المهلات)، فسيحاول OpenClaw + استخدام واجهة CLI الخلفية بعده. -## نظرة عامة على الإعدادات +## نظرة عامة على الإعداد توجد جميع واجهات CLI الخلفية تحت: @@ -100,14 +100,14 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4 agents.defaults.cliBackends ``` -يُفهرس كل إدخال بواسطة **معرّف موفر** (مثل `codex-cli` أو `my-cli`). -ويصبح معرّف الموفر هو الجزء الأيسر من مرجع النموذج: +كل إدخال يُعرَّف بواسطة **معرّف موفر** (مثل `codex-cli` أو `my-cli`). +ويصبح معرّف الموفر هو الطرف الأيسر من مرجع النموذج لديك: ``` / ``` -### مثال على الإعدادات +### مثال على الإعداد ```json5 { @@ -144,50 +144,50 @@ agents.defaults.cliBackends ## كيف يعمل -1. **يختار واجهة خلفية** بناءً على بادئة الموفر (`codex-cli/...`). -2. **يبني توجيه نظام** باستخدام توجيه OpenClaw نفسه + سياق مساحة العمل. -3. **ينفذ CLI** باستخدام معرّف جلسة (إذا كان مدعومًا) حتى يبقى السجل متسقًا. -4. **يحلل المخرجات** (JSON أو نص عادي) ويعيد النص النهائي. -5. **يحفظ معرّفات الجلسات** لكل واجهة خلفية، بحيث تعيد المتابعات استخدام جلسة CLI نفسها. +1. **يختار واجهة خلفية** استنادًا إلى بادئة الموفر (`codex-cli/...`). +2. **يبني موجّه نظام** باستخدام موجّه OpenClaw نفسه + سياق مساحة العمل. +3. **ينفّذ CLI** باستخدام معرّف جلسة (إذا كان مدعومًا) حتى يظل السجل متسقًا. +4. **يحلّل المخرجات** (`JSON` أو نص عادي) ويعيد النص النهائي. +5. **يحفظ معرّفات الجلسات** لكل واجهة خلفية، بحيث تعيد المنعطفات اللاحقة استخدام جلسة CLI نفسها. -واجهة `claude-cli` الخلفية المضمنة الخاصة بـ Anthropic مدعومة مرة أخرى. أخبرنا -موظفو Anthropic أن استخدام Claude CLI بأسلوب OpenClaw مسموح به مجددًا، لذا -يتعامل OpenClaw مع استخدام `claude -p` على أنه معتمد لهذا التكامل ما لم تنشر -Anthropic سياسة جديدة. +أصبحت الواجهة الخلفية المضمّنة `claude-cli` الخاصة بـ Anthropic مدعومة مجددًا. وقد أخبرنا +موظفو Anthropic أن استخدام Claude CLI بأسلوب OpenClaw مسموح مجددًا، لذلك يتعامل OpenClaw مع +استخدام `claude -p` على أنه معتمد لهذا التكامل ما لم تنشر Anthropic +سياسة جديدة. ## الجلسات - إذا كانت CLI تدعم الجلسات، فاضبط `sessionArg` (مثل `--session-id`) أو - `sessionArgs` (العنصر النائب `{sessionId}`) عندما يلزم إدراج - المعرّف في عدة علامات. -- إذا كانت CLI تستخدم **أمرًا فرعيًا للاستئناف** بعلامات مختلفة، فاضبط - `resumeArgs` (يستبدل `args` عند الاستئناف) ويمكنك اختياريًا ضبط `resumeOutput` - (للاستئنافات غير المعتمدة على JSON). + `sessionArgs` (العنصر النائب `{sessionId}`) عندما يلزم إدراج المعرّف + في عدة أعلام. +- إذا كانت CLI تستخدم **أمرًا فرعيًا للاستئناف** مع أعلام مختلفة، فاضبط + `resumeArgs` (يستبدل `args` عند الاستئناف) و`resumeOutput` اختياريًا + (لحالات الاستئناف غير المعتمدة على JSON). - `sessionMode`: - - `always`: أرسل دائمًا معرّف جلسة (UUID جديد إذا لم يكن هناك معرّف مخزن). - - `existing`: أرسل معرّف جلسة فقط إذا كان قد تم تخزينه مسبقًا. - - `none`: لا ترسل أبدًا معرّف جلسة. + - `always`: أرسل معرّف جلسة دائمًا (UUID جديد إذا لم يكن هناك معرّف مخزّن). + - `existing`: أرسل معرّف جلسة فقط إذا كان قد تم تخزينه من قبل. + - `none`: لا ترسل معرّف جلسة أبدًا. ملاحظات حول التسلسل: -- `serialize: true` يُبقي عمليات التشغيل في المسار نفسه مرتبة. -- تسلسل معظم واجهات CLI يتم على مسار موفر واحد. -- يسقط OpenClaw إعادة استخدام جلسة CLI المخزنة عندما تتغير حالة مصادقة الواجهة الخلفية، بما في ذلك إعادة تسجيل الدخول، أو تدوير الرموز، أو تغيير بيانات اعتماد ملف تعريف المصادقة. +- `serialize: true` يحافظ على ترتيب التشغيلات ضمن المسار نفسه. +- معظم واجهات CLI تُسلسل على مسار موفر واحد. +- يسقط OpenClaw إعادة استخدام جلسة CLI المخزّنة عندما تتغير حالة مصادقة الواجهة الخلفية، بما في ذلك إعادة تسجيل الدخول، أو تدوير الرموز، أو تغيير بيانات اعتماد ملف تعريف المصادقة. ## الصور (تمرير مباشر) -إذا كانت CLI تقبل مسارات الصور، فاضبط `imageArg`: +إذا كانت CLI لديك تقبل مسارات الصور، فاضبط `imageArg`: ```json5 imageArg: "--image", imageMode: "repeat" ``` -سيكتب OpenClaw الصور المشفرة بصيغة base64 إلى ملفات مؤقتة. إذا تم ضبط `imageArg`، -فسيتم تمرير تلك المسارات كوسائط CLI. وإذا لم يكن `imageArg` موجودًا، فسيُلحق OpenClaw -مسارات الملفات بالتوجيه (حقن المسار)، وهذا يكفي لواجهات CLI التي تحمّل +سيكتب OpenClaw الصور المرمّزة base64 إلى ملفات مؤقتة. إذا تم ضبط `imageArg`، فسيتم +تمرير تلك المسارات كوسائط CLI. وإذا لم يكن `imageArg` موجودًا، فسيضيف OpenClaw +مسارات الملفات إلى الموجّه (حقن المسار)، وهذا يكفي لواجهات CLI التي تقوم بتحميل الملفات المحلية تلقائيًا من المسارات النصية العادية. ## المدخلات / المخرجات @@ -195,19 +195,19 @@ imageMode: "repeat" - `output: "json"` (الافتراضي) يحاول تحليل JSON واستخراج النص + معرّف الجلسة. - بالنسبة إلى مخرجات JSON الخاصة بـ Gemini CLI، يقرأ OpenClaw نص الرد من `response` و الاستخدام من `stats` عندما يكون `usage` مفقودًا أو فارغًا. -- `output: "jsonl"` يحلل تدفقات JSONL (مثل Codex CLI `--json`) ويستخرج رسالة العامل النهائية بالإضافة إلى +- `output: "jsonl"` يحلل تدفقات JSONL (على سبيل المثال Codex CLI `--json`) ويستخرج رسالة الوكيل النهائية بالإضافة إلى معرّفات الجلسة عند وجودها. -- `output: "text"` يتعامل مع stdout باعتباره الاستجابة النهائية. +- `output: "text"` يتعامل مع stdout على أنه الاستجابة النهائية. -أنماط الإدخال: +أوضاع الإدخال: -- `input: "arg"` (الافتراضي) يمرر التوجيه باعتباره آخر وسيط CLI. -- `input: "stdin"` يرسل التوجيه عبر stdin. -- إذا كان التوجيه طويلًا جدًا وكان `maxPromptArgChars` مضبوطًا، فسيتم استخدام stdin. +- `input: "arg"` (الافتراضي) يمرر الموجّه باعتباره الوسيط الأخير لـ CLI. +- `input: "stdin"` يرسل الموجّه عبر stdin. +- إذا كان الموجّه طويلًا جدًا وتم ضبط `maxPromptArgChars`، فسيتم استخدام stdin. -## القيم الافتراضية (مملوكة لـ plugin) +## القيم الافتراضية (مملوكة للإضافة) -يسجل plugin OpenAI المضمن أيضًا قيمة افتراضية لـ `codex-cli`: +تسجّل إضافة OpenAI المضمّنة أيضًا قيمة افتراضية لـ `codex-cli`: - `command: "codex"` - `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]` @@ -218,77 +218,80 @@ imageMode: "repeat" - `imageArg: "--image"` - `sessionMode: "existing"` -يسجل plugin Google المضمن أيضًا قيمة افتراضية لـ `google-gemini-cli`: +وتسجّل إضافة Google المضمّنة أيضًا قيمة افتراضية لـ `google-gemini-cli`: - `command: "gemini"` -- `args: ["--prompt", "--output-format", "json"]` -- `resumeArgs: ["--resume", "{sessionId}", "--prompt", "--output-format", "json"]` +- `args: ["--output-format", "json", "--prompt", "{prompt}"]` +- `resumeArgs: ["--resume", "{sessionId}", "--output-format", "json", "--prompt", "{prompt}"]` +- `imageArg: "@"` +- `imagePathScope: "workspace"` - `modelArg: "--model"` - `sessionMode: "existing"` - `sessionIdFields: ["session_id", "sessionId"]` -المتطلب المسبق: يجب أن تكون Gemini CLI المحلية مثبتة ومتاحة باسم +المتطلب المسبق: يجب أن تكون Gemini CLI المحلية مثبّتة ومتاحة باسم `gemini` على `PATH` (`brew install gemini-cli` أو `npm install -g @google/gemini-cli`). ملاحظات JSON الخاصة بـ Gemini CLI: -- يُقرأ نص الرد من حقل JSON `response`. +- يُقرأ نص الرد من الحقل `response` في JSON. - يعود الاستخدام إلى `stats` عندما يكون `usage` غائبًا أو فارغًا. - تتم تسوية `stats.cached` إلى OpenClaw `cacheRead`. -- إذا كان `stats.input` مفقودًا، يشتق OpenClaw رموز الإدخال من +- إذا كان `stats.input` مفقودًا، يستنتج OpenClaw رموز الإدخال من `stats.input_tokens - stats.cached`. -لا تُجرِ تجاوزًا إلا عند الحاجة (الأكثر شيوعًا: مسار `command` المطلق). +قم بالتجاوز فقط عند الحاجة (والأكثر شيوعًا: مسار `command` مطلق). -## القيم الافتراضية المملوكة لـ plugin +## القيم الافتراضية المملوكة للإضافة -أصبحت القيم الافتراضية لواجهات CLI الخلفية الآن جزءًا من سطح plugin: +أصبحت القيم الافتراضية لواجهات CLI الخلفية الآن جزءًا من سطح الإضافة: -- تسجلها Plugins باستخدام `api.registerCliBackend(...)`. -- يصبح `id` الخاص بالواجهة الخلفية هو بادئة الموفر في مراجع النماذج. -- تظل إعدادات المستخدم في `agents.defaults.cliBackends.` تتجاوز القيمة الافتراضية الخاصة بـ plugin. -- تبقى تنقية الإعدادات الخاصة بالواجهة الخلفية مملوكة لـ plugin من خلال الخطاف الاختياري - `normalizeConfig`. +- تسجّلها الإضافات باستخدام `api.registerCliBackend(...)`. +- يصبح `id` الخاص بالواجهة الخلفية بادئة الموفر في مراجع النماذج. +- يظل إعداد المستخدم في `agents.defaults.cliBackends.` يتجاوز القيمة الافتراضية للإضافة. +- تظل عملية تنظيف الإعداد الخاصة بالواجهة الخلفية مملوكة للإضافة من خلال + الخطاف الاختياري `normalizeConfig`. -## تراكبات bundle MCP +## تراكبات Bundle MCP لا تتلقى واجهات CLI الخلفية **استدعاءات أدوات OpenClaw مباشرة**، لكن يمكن لواجهة خلفية -أن تشترك في تراكب إعداد MCP مُولَّد عبر `bundleMcp: true`. +الاشتراك في تراكب إعداد MCP مُولَّد باستخدام `bundleMcp: true`. -السلوك المضمن الحالي: +السلوك المضمّن الحالي: -- `codex-cli`: لا يوجد تراكب bundle MCP -- `google-gemini-cli`: لا يوجد تراكب bundle MCP +- `claude-cli`: ملف إعداد MCP صارم مُولَّد +- `codex-cli`: تجاوزات إعدادات مضمنة لـ `mcp_servers` +- `google-gemini-cli`: ملف إعدادات نظام Gemini مُولَّد عند تمكين bundle MCP، يقوم OpenClaw بما يلي: -- يشغّل خادم HTTP MCP من نوع loopback يعرّض أدوات gateway لعملية CLI +- يشغّل خادم HTTP MCP محلي loopback يعرّض أدوات البوابة لعملية CLI - يصادق الجسر باستخدام رمز مميز لكل جلسة (`OPENCLAW_MCP_TOKEN`) -- يقيّد وصول الأدوات بسياق الجلسة والحساب والقناة الحالية +- يقيّد الوصول إلى الأدوات ضمن نطاق الجلسة الحالية والحساب وسياق القناة - يحمّل خوادم bundle-MCP الممكّنة لمساحة العمل الحالية -- يدمجها مع أي `--mcp-config` موجود للواجهة الخلفية -- يعيد كتابة وسائط CLI لتمرير `--strict-mcp-config --mcp-config ` +- يدمجها مع أي شكل إعداد/إعدادات MCP موجود للواجهة الخلفية +- يعيد كتابة إعدادات التشغيل باستخدام وضع التكامل المملوك للواجهة الخلفية من الامتداد المالك -إذا لم تكن أي خوادم MCP مفعّلة، فسيظل OpenClaw يحقن إعدادًا صارمًا عندما -تشترك واجهة خلفية في bundle MCP حتى تظل عمليات التشغيل الخلفية معزولة. +إذا لم تكن أي خوادم MCP ممكّنة، فسيظل OpenClaw يحقن إعدادًا صارمًا عندما +تشترك واجهة خلفية في bundle MCP حتى تظل عمليات الخلفية معزولة. ## القيود -- **لا توجد استدعاءات مباشرة لأدوات OpenClaw.** لا يحقن OpenClaw استدعاءات الأدوات ضمن - بروتوكول واجهة CLI الخلفية. لا ترى الواجهات الخلفية أدوات gateway إلا عندما تشترك في +- **لا توجد استدعاءات مباشرة لأدوات OpenClaw.** لا يحقن OpenClaw استدعاءات أدوات في + بروتوكول واجهة CLI الخلفية. لا ترى الواجهات الخلفية أدوات البوابة إلا عندما تشترك في `bundleMcp: true`. -- **البث خاص بالواجهة الخلفية.** بعض الواجهات الخلفية تبث JSONL؛ بينما تخزن أخرى - كل شيء مؤقتًا حتى الخروج. -- **المخرجات المنظمة** تعتمد على تنسيق JSON الخاص بـ CLI. -- **جلسات Codex CLI** تُستأنف عبر مخرجات نصية (وليس JSONL)، وهو ما يجعلها أقل +- **البث خاص بكل واجهة خلفية.** بعض الواجهات الخلفية تبث JSONL؛ بينما يقوم بعضها الآخر + بالتجميع حتى الخروج. +- **المخرجات المنظَّمة** تعتمد على تنسيق JSON الخاص بـ CLI. +- **جلسات Codex CLI** تُستأنف عبر مخرجات نصية (من دون JSONL)، وهذا أقل تنظيمًا من تشغيل `--json` الأولي. ومع ذلك، تظل جلسات OpenClaw تعمل بشكل طبيعي. ## استكشاف الأخطاء وإصلاحها - **لم يتم العثور على CLI**: اضبط `command` على مسار كامل. -- **اسم نموذج غير صحيح**: استخدم `modelAliases` لربط `provider/model` → نموذج CLI. +- **اسم النموذج غير صحيح**: استخدم `modelAliases` لربط `provider/model` → نموذج CLI. - **لا يوجد استمرارية للجلسة**: تأكد من ضبط `sessionArg` وأن `sessionMode` ليس `none` (لا يمكن لـ Codex CLI حاليًا الاستئناف بمخرجات JSON). -- **تم تجاهل الصور**: اضبط `imageArg` (وتأكد من أن CLI تدعم مسارات الملفات). +- **يتم تجاهل الصور**: اضبط `imageArg` (وتحقق من أن CLI تدعم مسارات الملفات). diff --git a/docs/ar/gateway/configuration-reference.md b/docs/ar/gateway/configuration-reference.md index 05f99817a..4800fb2e2 100644 --- a/docs/ar/gateway/configuration-reference.md +++ b/docs/ar/gateway/configuration-reference.md @@ -1,56 +1,56 @@ --- read_when: - - تحتاج إلى دلالات إعداد دقيقة على مستوى الحقل أو إلى القيم الافتراضية + - تحتاج إلى دلالات إعدادات دقيقة على مستوى الحقول أو القيم الافتراضية - أنت تتحقق من كتل إعدادات القناة أو النموذج أو البوابة أو الأدوات -summary: المرجع الكامل لكل مفتاح إعداد في OpenClaw، والقيم الافتراضية، وإعدادات القنوات +summary: مرجع كامل لكل مفتاح إعدادات في OpenClaw، والقيم الافتراضية، وإعدادات القنوات title: مرجع الإعدادات x-i18n: - generated_at: "2026-04-07T07:23:34Z" + generated_at: "2026-04-08T02:19:36Z" model: gpt-5.4 provider: openai - source_hash: 7768cb77e1d3fc483c66f655ea891d2c32f21b247e3c1a56a919b28a37f9b128 + source_hash: 2c7991b948cbbb7954a3e26280089ab00088e7f4878ec0b0540c3c9acf222ebb source_path: gateway/configuration-reference.md workflow: 15 --- # مرجع الإعدادات -كل حقل متاح في `~/.openclaw/openclaw.json`. للاطلاع على نظرة عامة موجّهة بالمهام، انظر [الإعدادات](/ar/gateway/configuration). +كل الحقول المتاحة في `~/.openclaw/openclaw.json`. للحصول على نظرة عامة موجهة حسب المهام، راجع [الإعدادات](/ar/gateway/configuration). -تنسيق الإعداد هو **JSON5** (يُسمح بالتعليقات والفواصل اللاحقة). جميع الحقول اختيارية — يستخدم OpenClaw قيمًا افتراضية آمنة عند حذفها. +تنسيق الإعدادات هو **JSON5** (يُسمح بالتعليقات + الفواصل اللاحقة). جميع الحقول اختيارية — يستخدم OpenClaw قيمًا افتراضية آمنة عند حذفها. --- ## القنوات -تبدأ كل قناة تلقائيًا عند وجود قسم إعدادها (ما لم يكن `enabled: false`). +تبدأ كل قناة تلقائيًا عندما يكون قسم إعداداتها موجودًا (ما لم يكن `enabled: false`). ### الوصول إلى الرسائل الخاصة والمجموعات تدعم جميع القنوات سياسات الرسائل الخاصة وسياسات المجموعات: -| سياسة الرسائل الخاصة | السلوك | -| -------------------- | ------------------------------------------------------------- | -| `pairing` (الافتراضي) | يحصل المرسلون غير المعروفين على رمز اقتران لمرة واحدة؛ ويجب أن يوافق المالك | -| `allowlist` | فقط المرسلون الموجودون في `allowFrom` (أو مخزن السماح المقترن) | -| `open` | السماح بجميع الرسائل الخاصة الواردة (يتطلب `allowFrom: ["*"]`) | -| `disabled` | تجاهل جميع الرسائل الخاصة الواردة | +| سياسة الرسائل الخاصة | السلوك | +| -------------------- | --------------------------------------------------------------- | +| `pairing` (افتراضي) | يحصل المرسلون غير المعروفين على رمز إقران لمرة واحدة؛ يجب أن يوافق المالك | +| `allowlist` | فقط المرسلون الموجودون في `allowFrom` (أو مخزن السماح المقترن) | +| `open` | السماح بجميع الرسائل الخاصة الواردة (يتطلب `allowFrom: ["*"]`) | +| `disabled` | تجاهل جميع الرسائل الخاصة الواردة | -| سياسة المجموعة | السلوك | -| --------------------- | ---------------------------------------------------- | -| `allowlist` (الافتراضي) | فقط المجموعات المطابقة لقائمة السماح المكوّنة | -| `open` | تجاوز قوائم السماح الخاصة بالمجموعات (مع استمرار تطبيق بوابة الإشارة) | -| `disabled` | حظر جميع رسائل المجموعات/الغرف | +| سياسة المجموعة | السلوك | +| ---------------------- | ------------------------------------------------------ | +| `allowlist` (افتراضي) | فقط المجموعات المطابقة لقائمة السماح المكوّنة | +| `open` | تجاوز قوائم السماح للمجموعات (مع استمرار تطبيق تقييد الإشارات) | +| `disabled` | حظر جميع رسائل المجموعات/الغرف | -يضبط `channels.defaults.groupPolicy` السياسة الافتراضية عندما لا يكون `groupPolicy` الخاص بالمزوّد معيّنًا. -تنتهي صلاحية رموز الاقتران بعد ساعة واحدة. ويكون الحد الأقصى لطلبات اقتران الرسائل الخاصة المعلّقة **3 لكل قناة**. -إذا كانت كتلة المزوّد مفقودة بالكامل (`channels.` غير موجودة)، فإن سياسة المجموعات أثناء التشغيل تعود إلى `allowlist` (إغلاق آمن عند الفشل) مع تحذير عند بدء التشغيل. +يضبط `channels.defaults.groupPolicy` القيمة الافتراضية عندما تكون `groupPolicy` الخاصة بالمزوّد غير معيّنة. +تنتهي صلاحية رموز الإقران بعد ساعة واحدة. يتم تحديد الحد الأقصى لطلبات إقران الرسائل الخاصة المعلقة إلى **3 لكل قناة**. +إذا كانت كتلة المزوّد مفقودة بالكامل (`channels.` غير موجودة)، فإن سياسة المجموعة وقت التشغيل تعود إلى `allowlist` (إغلاق افتراضي آمن) مع تحذير عند بدء التشغيل. ### تجاوزات نموذج القناة -استخدم `channels.modelByChannel` لتثبيت معرّفات قنوات محددة على نموذج بعينه. تقبل القيم `provider/model` أو الأسماء المستعارة للنماذج المكوّنة. ويُطبّق تعيين القناة عندما لا تكون الجلسة تمتلك بالفعل تجاوزًا للنموذج (على سبيل المثال، تم تعيينه عبر `/model`). +استخدم `channels.modelByChannel` لتثبيت معرّفات قنوات محددة على نموذج معيّن. تقبل القيم `provider/model` أو الأسماء المستعارة للنماذج المكوّنة. يتم تطبيق تعيين القناة عندما لا تكون الجلسة تملك بالفعل تجاوزًا للنموذج (على سبيل المثال، تم تعيينه عبر `/model`). ```json5 { @@ -71,9 +71,9 @@ x-i18n: } ``` -### الإعدادات الافتراضية للقنوات ونبض الحياة +### القيم الافتراضية للقنوات والنبض الصحي -استخدم `channels.defaults` للسلوك المشترك الخاص بسياسة المجموعات ونبض الحياة عبر المزوّدين: +استخدم `channels.defaults` لسلوك سياسة المجموعة والنبض الصحي المشترك بين المزوّدين: ```json5 { @@ -91,15 +91,15 @@ x-i18n: } ``` -- `channels.defaults.groupPolicy`: سياسة المجموعات الاحتياطية عندما لا يكون `groupPolicy` على مستوى المزوّد معيّنًا. -- `channels.defaults.contextVisibility`: وضع الرؤية الافتراضي للسياق التكميلي لجميع القنوات. القيم: `all` (الافتراضي، تضمين كل سياق الاقتباس/الخيط/السجل)، و`allowlist` (تضمين السياق من المرسلين الموجودين في قائمة السماح فقط)، و`allowlist_quote` (مثل allowlist ولكن مع الاحتفاظ بسياق الاقتباس/الرد الصريح). تجاوز لكل قناة: `channels..contextVisibility`. -- `channels.defaults.heartbeat.showOk`: تضمين حالات القنوات السليمة في مخرجات نبض الحياة. -- `channels.defaults.heartbeat.showAlerts`: تضمين حالات التدهور/الخطأ في مخرجات نبض الحياة. -- `channels.defaults.heartbeat.useIndicator`: عرض مخرجات نبض الحياة بنمط مؤشرات مدمج. +- `channels.defaults.groupPolicy`: سياسة المجموعة الاحتياطية عندما لا تكون `groupPolicy` على مستوى المزوّد معيّنة. +- `channels.defaults.contextVisibility`: وضع رؤية السياق الإضافي الافتراضي لجميع القنوات. القيم: `all` (افتراضي، تضمين كل سياق الاقتباس/الخيط/السجل)، `allowlist` (تضمين السياق فقط من المرسلين المسموح لهم)، `allowlist_quote` (مثل allowlist لكن مع الاحتفاظ بسياق الاقتباس/الرد الصريح). تجاوز لكل قناة: `channels..contextVisibility`. +- `channels.defaults.heartbeat.showOk`: تضمين حالات القنوات السليمة في مخرجات النبض الصحي. +- `channels.defaults.heartbeat.showAlerts`: تضمين حالات التدهور/الأخطاء في مخرجات النبض الصحي. +- `channels.defaults.heartbeat.useIndicator`: عرض مخرجات النبض الصحي بأسلوب مؤشر مدمج. ### WhatsApp -يعمل WhatsApp من خلال قناة الويب الخاصة بالبوابة (Baileys Web). ويبدأ تلقائيًا عند وجود جلسة مرتبطة. +يعمل WhatsApp عبر قناة الويب الخاصة بالبوابة (Baileys Web). يبدأ تلقائيًا عندما توجد جلسة مرتبطة. ```json5 { @@ -110,7 +110,7 @@ x-i18n: textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // علامات القراءة الزرقاء (false في وضع الدردشة الذاتية) + sendReadReceipts: true, // blue ticks (false in self-chat mode) groups: { "*": { requireMention: true }, }, @@ -150,10 +150,10 @@ x-i18n: } ``` -- تستخدم الأوامر الصادرة الحساب `default` افتراضيًا إذا كان موجودًا؛ وإلا فسيتم استخدام أول معرّف حساب مكوَّن (بعد الفرز). -- يجاوز `channels.whatsapp.defaultAccount` الاختياري اختيار الحساب الافتراضي الاحتياطي هذا عندما يطابق معرّف حساب مكوَّن. +- تستخدم الأوامر الصادرة الحساب `default` افتراضيًا إن كان موجودًا؛ وإلا فمعرّف الحساب الأول المكوَّن (بعد الفرز). +- يجاوز `channels.whatsapp.defaultAccount` الاختياري هذا الحساب الافتراضي الاحتياطي عندما يطابق معرّف حساب مكوَّن. - يتم ترحيل دليل مصادقة Baileys القديم أحادي الحساب بواسطة `openclaw doctor` إلى `whatsapp/default`. -- تجاوزات لكل حساب: `channels.whatsapp.accounts..sendReadReceipts` و`channels.whatsapp.accounts..dmPolicy` و`channels.whatsapp.accounts..allowFrom`. +- تجاوزات لكل حساب: `channels.whatsapp.accounts..sendReadReceipts`، و`channels.whatsapp.accounts..dmPolicy`، و`channels.whatsapp.accounts..allowFrom`. @@ -188,7 +188,7 @@ x-i18n: historyLimit: 50, replyToMode: "first", // off | first | all | batched linkPreview: true, - streaming: "partial", // off | partial | block | progress (default: off; فعّله صراحة لتجنب حدود معدل تعديل المعاينة) + streaming: "partial", // off | partial | block | progress (default: off; opt in explicitly to avoid preview-edit rate limits) actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -211,12 +211,12 @@ x-i18n: } ``` -- رمز الروبوت: `channels.telegram.botToken` أو `channels.telegram.tokenFile` (ملف عادي فقط؛ تُرفض الروابط الرمزية)، مع `TELEGRAM_BOT_TOKEN` كبديل للحساب الافتراضي. +- رمز البوت: `channels.telegram.botToken` أو `channels.telegram.tokenFile` (ملف عادي فقط؛ تُرفض الروابط الرمزية)، مع `TELEGRAM_BOT_TOKEN` كخيار احتياطي للحساب الافتراضي. - يجاوز `channels.telegram.defaultAccount` الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مكوَّن. -- في إعدادات الحسابات المتعددة (معرّفا حساب أو أكثر)، اضبط قيمة افتراضية صريحة (`channels.telegram.defaultAccount` أو `channels.telegram.accounts.default`) لتجنب التوجيه الاحتياطي؛ ويحذّر `openclaw doctor` عند غياب ذلك أو عدم صحته. -- يمنع `configWrites: false` عمليات كتابة الإعدادات التي يبدأها Telegram (ترحيل معرّفات المجموعات الخارقة، و`/config set|unset`). -- تضبط إدخالات `bindings[]` على المستوى الأعلى مع `type: "acp"` ارتباطات ACP دائمة لموضوعات المنتدى (استخدم `chatId:topic:topicId` القياسي في `match.peer.id`). تتم مشاركة دلالات الحقول في [وكلاء ACP](/ar/tools/acp-agents#channel-specific-settings). -- تستخدم معاينات البث في Telegram `sendMessage` و`editMessageText` (وتعمل في المحادثات المباشرة والجماعية). +- في إعدادات تعدد الحسابات (معرّفان أو أكثر)، عيّن افتراضيًا صريحًا (`channels.telegram.defaultAccount` أو `channels.telegram.accounts.default`) لتجنب التوجيه الاحتياطي؛ ويُظهر `openclaw doctor` تحذيرًا عندما يكون هذا مفقودًا أو غير صالح. +- `configWrites: false` يمنع عمليات كتابة الإعدادات التي يبدؤها Telegram (ترحيلات معرّف supergroup و`/config set|unset`). +- تُكوّن إدخالات `bindings[]` ذات المستوى الأعلى مع `type: "acp"` روابط ACP دائمة لموضوعات المنتدى (استخدم الصيغة القياسية `chatId:topic:topicId` في `match.peer.id`). تُشارك دلالات الحقول في [وكلاء ACP](/ar/tools/acp-agents#channel-specific-settings). +- تستخدم معاينات البث في Telegram `sendMessage` + `editMessageText` (وتعمل في الدردشات المباشرة والجماعية). - سياسة إعادة المحاولة: راجع [سياسة إعادة المحاولة](/ar/concepts/retry). ### Discord @@ -272,7 +272,7 @@ x-i18n: historyLimit: 20, textChunkLimit: 2000, chunkMode: "length", // length | newline - streaming: "off", // off | partial | block | progress (progress تُطابق partial على Discord) + streaming: "off", // off | partial | block | progress (progress maps to partial on Discord) maxLinesPerMessage: 17, ui: { components: { @@ -283,7 +283,7 @@ x-i18n: enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // تفعيل اختياري لـ sessions_spawn({ thread: true }) + spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true }) }, voice: { enabled: true, @@ -319,36 +319,36 @@ x-i18n: } ``` -- الرمز: `channels.discord.token`، مع `DISCORD_BOT_TOKEN` كبديل للحساب الافتراضي. -- تستخدم الاستدعاءات الصادرة المباشرة التي توفّر `token` صريحًا لـ Discord ذلك الرمز في الاستدعاء؛ بينما تظل إعدادات إعادة المحاولة/السياسة للحساب مأخوذة من الحساب المحدد في اللقطة النشطة لوقت التشغيل. +- الرمز: `channels.discord.token`، مع `DISCORD_BOT_TOKEN` كخيار احتياطي للحساب الافتراضي. +- تستخدم الاستدعاءات الصادرة المباشرة التي توفر `token` صريحًا لـ Discord ذلك الرمز لهذا الاستدعاء؛ بينما تظل إعدادات إعادة المحاولة/السياسة الخاصة بالحساب آتية من الحساب المحدد في اللقطة النشطة وقت التشغيل. - يجاوز `channels.discord.defaultAccount` الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مكوَّن. - استخدم `user:` (رسالة خاصة) أو `channel:` (قناة guild) كأهداف للتسليم؛ ويتم رفض المعرّفات الرقمية المجردة. -- تكون slugs الخاصة بـ guild بأحرف صغيرة مع استبدال المسافات بـ `-`؛ وتستخدم مفاتيح القنوات الاسم المحوّل إلى slug (من دون `#`). ويفضَّل استخدام معرّفات guild. -- يتم تجاهل الرسائل التي يكتبها الروبوت افتراضيًا. يفعّل `allowBots: true` قبولها؛ واستخدم `allowBots: "mentions"` لقبول رسائل الروبوت التي تشير إلى الروبوت فقط (مع استمرار تصفية رسائل الروبوت نفسه). -- يقوم `channels.discord.guilds..ignoreOtherMentions` (وتجاوزات القنوات) بإسقاط الرسائل التي تشير إلى مستخدم أو دور آخر ولكن ليس الروبوت (باستثناء @everyone/@here). -- يقوم `maxLinesPerMessage` (الافتراضي 17) بتقسيم الرسائل الطويلة رأسيًا حتى لو كانت أقل من 2000 حرف. +- تكون Slugات الـ Guild بحروف صغيرة مع استبدال المسافات بـ `-`؛ وتستخدم مفاتيح القنوات الاسم المُحوّل إلى slug (من دون `#`). يفضَّل استخدام معرّفات الـ Guild. +- يتم تجاهل الرسائل التي يكتبها البوت افتراضيًا. يفعّل `allowBots: true` استقبالها؛ واستخدم `allowBots: "mentions"` لقبول رسائل البوت التي تذكر البوت فقط (مع استمرار تصفية رسائل البوت نفسه). +- `channels.discord.guilds..ignoreOtherMentions` (وتجاوزات القنوات) يُسقط الرسائل التي تذكر مستخدمًا أو دورًا آخر لكن لا تذكر البوت (باستثناء @everyone/@here). +- `maxLinesPerMessage` (الافتراضي 17) يقسم الرسائل الطويلة رأسيًا حتى لو كانت أقل من 2000 حرف. - يتحكم `channels.discord.threadBindings` في التوجيه المرتبط بخيوط Discord: - - `enabled`: تجاوز Discord لميزات الجلسات المرتبطة بالخيط (`/focus` و`/unfocus` و`/agents` و`/session idle` و`/session max-age` والتسليم/التوجيه المرتبط) - - `idleHours`: تجاوز Discord لإلغاء التركيز التلقائي بعد الخمول بالساعات (`0` للتعطيل) - - `maxAgeHours`: تجاوز Discord للحد الأقصى الصارم للعمر بالساعات (`0` للتعطيل) - - `spawnSubagentSessions`: مفتاح تفعيل اختياري للإنشاء/الربط التلقائي للخيط بواسطة `sessions_spawn({ thread: true })` -- تضبط إدخالات `bindings[]` على المستوى الأعلى مع `type: "acp"` ارتباطات ACP دائمة للقنوات والخيوط (استخدم معرّف القناة/الخيط في `match.peer.id`). تتم مشاركة دلالات الحقول في [وكلاء ACP](/ar/tools/acp-agents#channel-specific-settings). -- يحدد `channels.discord.ui.components.accentColor` لون التمييز لحاويات Discord components v2. -- يفعّل `channels.discord.voice` محادثات القنوات الصوتية في Discord مع تجاوزات اختيارية للانضمام التلقائي وTTS. -- يتم تمرير `channels.discord.voice.daveEncryption` و`channels.discord.voice.decryptionFailureTolerance` إلى خيارات DAVE في `@discordjs/voice` (القيم الافتراضية `true` و`24`). -- يحاول OpenClaw أيضًا استرداد استقبال الصوت عبر مغادرة جلسة الصوت ثم إعادة الانضمام إليها بعد تكرار فشل فك التشفير. -- يعدّ `channels.discord.streaming` مفتاح وضع البث القياسي. وتتم ترقية القيم القديمة `streamMode` والقيم المنطقية `streaming` تلقائيًا. -- يربط `channels.discord.autoPresence` التوفر أثناء التشغيل بحالة وجود الروبوت (سليم => online، متدهور => idle، منهك => dnd) ويسمح بتجاوزات اختيارية لنص الحالة. + - `enabled`: تجاوز Discord لميزات الجلسات المرتبطة بالخيوط (`/focus`، `/unfocus`، `/agents`، `/session idle`، `/session max-age`، والتسليم/التوجيه المرتبط) + - `idleHours`: تجاوز Discord لإلغاء التركيز التلقائي بعد عدم النشاط بالساعات (`0` للتعطيل) + - `maxAgeHours`: تجاوز Discord للعمر الأقصى الصارم بالساعات (`0` للتعطيل) + - `spawnSubagentSessions`: مفتاح اشتراك اختياري لإنشاء/ربط الخيط تلقائيًا عبر `sessions_spawn({ thread: true })` +- تُكوّن إدخالات `bindings[]` ذات المستوى الأعلى مع `type: "acp"` روابط ACP دائمة للقنوات والخيوط (استخدم معرّف القناة/الخيط في `match.peer.id`). تُشارك دلالات الحقول في [وكلاء ACP](/ar/tools/acp-agents#channel-specific-settings). +- يضبط `channels.discord.ui.components.accentColor` لون التمييز لحاويات Discord components v2. +- يفعّل `channels.discord.voice` محادثات قنوات الصوت في Discord مع الانضمام التلقائي الاختياري + تجاوزات TTS. +- يمرّر `channels.discord.voice.daveEncryption` و`channels.discord.voice.decryptionFailureTolerance` إلى خيارات DAVE في `@discordjs/voice` (افتراضيًا `true` و`24`). +- يحاول OpenClaw أيضًا استعادة استقبال الصوت بمغادرة/إعادة الانضمام إلى جلسة صوتية بعد تكرار فشل فك التشفير. +- `channels.discord.streaming` هو مفتاح وضع البث القياسي. يتم ترحيل `streamMode` القديم وقيم `streaming` المنطقية تلقائيًا. +- يربط `channels.discord.autoPresence` حالة التوفّر وقت التشغيل بحالة حضور البوت (سليم => online، متدهور => idle، منهك => dnd) ويسمح بتجاوزات نص الحالة الاختيارية. - يعيد `channels.discord.dangerouslyAllowNameMatching` تمكين مطابقة الاسم/الوسم القابلة للتغيير (وضع توافق لكسر الزجاج). - `channels.discord.execApprovals`: تسليم موافقات exec الأصلية في Discord وتفويض الموافقين. - - `enabled`: إما `true` أو `false` أو `"auto"` (الافتراضي). في الوضع التلقائي، تُفعَّل موافقات exec عندما يمكن حل الموافقين من `approvers` أو `commands.ownerAllowFrom`. - - `approvers`: معرّفات مستخدمي Discord المسموح لهم بالموافقة على طلبات exec. وتعود إلى `commands.ownerAllowFrom` عند الحذف. + - `enabled`: `true` أو `false` أو `"auto"` (افتراضي). في الوضع التلقائي، تُفعَّل موافقات exec عندما يمكن حل الموافقين من `approvers` أو `commands.ownerAllowFrom`. + - `approvers`: معرّفات مستخدمي Discord المسموح لهم بالموافقة على طلبات exec. تعود إلى `commands.ownerAllowFrom` عند حذفها. - `agentFilter`: قائمة سماح اختيارية لمعرّفات الوكلاء. احذفها لتمرير الموافقات لجميع الوكلاء. - `sessionFilter`: أنماط اختيارية لمفاتيح الجلسات (substring أو regex). - - `target`: أين تُرسل مطالبات الموافقة. ترسل `"dm"` (الافتراضي) إلى الرسائل الخاصة للموافقين، وترسل `"channel"` إلى القناة الأصلية، وترسل `"both"` إلى كليهما. وعندما يتضمن الهدف `"channel"`، لا تكون الأزرار قابلة للاستخدام إلا من قِبل الموافقين المحلولين. - - `cleanupAfterResolve`: عندما تكون `true`، تحذف رسائل الموافقة الخاصة بعد الموافقة أو الرفض أو انتهاء المهلة. + - `target`: مكان إرسال مطالبات الموافقة. `"dm"` (افتراضي) يرسل إلى الرسائل الخاصة للموافقين، `"channel"` يرسل إلى القناة الأصلية، `"both"` يرسل إلى الاثنين. عندما يتضمن الهدف `"channel"`، لا يمكن استخدام الأزرار إلا من قبل الموافقين الذين تم حلهم. + - `cleanupAfterResolve`: عندما يكون `true`، يحذف رسائل الموافقة الخاصة بعد الموافقة أو الرفض أو انتهاء المهلة. -**أوضاع إشعارات التفاعل:** `off` (لا شيء)، و`own` (رسائل الروبوت، الافتراضي)، و`all` (كل الرسائل)، و`allowlist` (من `guilds..users` على جميع الرسائل). +**أوضاع إشعارات التفاعلات:** `off` (بلا شيء)، `own` (رسائل البوت، افتراضي)، `all` (كل الرسائل)، `allowlist` (من `guilds..users` على كل الرسائل). ### Google Chat @@ -379,11 +379,11 @@ x-i18n: } ``` -- JSON الخاص بحساب الخدمة: مضمّن (`serviceAccount`) أو معتمد على ملف (`serviceAccountFile`). -- يُدعَم أيضًا SecretRef لحساب الخدمة (`serviceAccountRef`). -- البدائل من البيئة: `GOOGLE_CHAT_SERVICE_ACCOUNT` أو `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. +- JSON لحساب الخدمة: مضمّن (`serviceAccount`) أو قائم على ملف (`serviceAccountFile`). +- كما أن SecretRef لحساب الخدمة مدعوم أيضًا (`serviceAccountRef`). +- بدائل البيئة: `GOOGLE_CHAT_SERVICE_ACCOUNT` أو `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. - استخدم `spaces/` أو `users/` كأهداف للتسليم. -- يعيد `channels.googlechat.dangerouslyAllowNameMatching` تمكين مطابقة البريد الإلكتروني القابلة للتغيير (وضع توافق لكسر الزجاج). +- يعيد `channels.googlechat.dangerouslyAllowNameMatching` تمكين مطابقة principal البريد الإلكتروني القابلة للتغيير (وضع توافق لكسر الزجاج). ### Slack @@ -433,8 +433,8 @@ x-i18n: typingReaction: "hourglass_flowing_sand", textChunkLimit: 4000, chunkMode: "length", - streaming: "partial", // off | partial | block | progress (وضع معاينة) - nativeStreaming: true, // استخدم Slack native streaming API عندما streaming=partial + streaming: "partial", // off | partial | block | progress (preview mode) + nativeStreaming: true, // use Slack native streaming API when streaming=partial mediaMaxMb: 20, execApprovals: { enabled: "auto", // true | false | "auto" @@ -448,38 +448,33 @@ x-i18n: } ``` -- **وضع Socket** يتطلب كِلا `botToken` و`appToken` (`SLACK_BOT_TOKEN` و`SLACK_APP_TOKEN` كبدائل بيئية للحساب الافتراضي). +- **وضع Socket** يتطلب كلاً من `botToken` و`appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` كبديل بيئي للحساب الافتراضي). - **وضع HTTP** يتطلب `botToken` بالإضافة إلى `signingSecret` (على الجذر أو لكل حساب). -- تقبل `botToken` و`appToken` و`signingSecret` و`userToken` سلاسل نصية - صريحة أو كائنات SecretRef. -- تعرض لقطات حسابات Slack حقول المصدر/الحالة لكل بيانات اعتماد، مثل - `botTokenSource` و`botTokenStatus` و`appTokenStatus` و، في وضع HTTP، - `signingSecretStatus`. تعني `configured_unavailable` أن الحساب - مكوَّن من خلال SecretRef لكن مسار الأمر/وقت التشغيل الحالي لم يتمكن - من حل قيمة السر. -- يمنع `configWrites: false` عمليات كتابة الإعدادات التي يبدأها Slack. +- تقبل `botToken` و`appToken` و`signingSecret` و`userToken` سلاسل نصية صريحة أو كائنات SecretRef. +- تعرض لقطات حساب Slack حقول مصدر/حالة لكل اعتماد مثل `botTokenSource` و`botTokenStatus` و`appTokenStatus`، وفي وضع HTTP أيضًا `signingSecretStatus`. تعني `configured_unavailable` أن الحساب مكوَّن عبر SecretRef لكن مسار الأمر/وقت التشغيل الحالي لم يتمكن من حل قيمة السر. +- `configWrites: false` يمنع عمليات كتابة الإعدادات التي يبدؤها Slack. - يجاوز `channels.slack.defaultAccount` الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مكوَّن. -- يعدّ `channels.slack.streaming` مفتاح وضع البث القياسي. وتتم ترقية القيم القديمة `streamMode` والقيم المنطقية `streaming` تلقائيًا. +- `channels.slack.streaming` هو مفتاح وضع البث القياسي. يتم ترحيل `streamMode` القديم وقيم `streaming` المنطقية تلقائيًا. - استخدم `user:` (رسالة خاصة) أو `channel:` كأهداف للتسليم. -**أوضاع إشعارات التفاعل:** `off` و`own` (الافتراضي) و`all` و`allowlist` (من `reactionAllowlist`). +**أوضاع إشعارات التفاعلات:** `off`، `own` (افتراضي)، `all`، `allowlist` (من `reactionAllowlist`). -**عزل جلسة الخيط:** يكون `thread.historyScope` لكل خيط على حدة (الافتراضي) أو مشتركًا عبر القناة. يقوم `thread.inheritParent` بنسخ سجل القناة الأصلية إلى الخيوط الجديدة. +**عزل جلسة الخيط:** يكون `thread.historyScope` لكل خيط على حدة (افتراضي) أو مشتركًا عبر القناة. ينسخ `thread.inheritParent` سجل القناة الأصلية إلى الخيوط الجديدة. -- تضيف `typingReaction` تفاعلًا مؤقتًا إلى رسالة Slack الواردة أثناء تنفيذ الرد، ثم تزيله عند الاكتمال. استخدم رمز emoji مختصر لـ Slack مثل `"hourglass_flowing_sand"`. -- `channels.slack.execApprovals`: تسليم موافقات exec الأصلية في Slack وتفويض الموافقين. نفس مخطط Discord: `enabled` (`true`/`false`/`"auto"`)، و`approvers` (معرّفات مستخدمي Slack)، و`agentFilter` و`sessionFilter` و`target` (`"dm"` أو `"channel"` أو `"both"`). +- يضيف `typingReaction` تفاعلًا مؤقتًا إلى رسالة Slack الواردة أثناء تشغيل الرد، ثم يزيله عند الاكتمال. استخدم shortcode لرمز Slack التعبيري مثل `"hourglass_flowing_sand"`. +- `channels.slack.execApprovals`: تسليم موافقات exec الأصلية في Slack وتفويض الموافقين. نفس مخطط Discord: `enabled` (`true`/`false`/`"auto"`)، و`approvers` (معرّفات مستخدمي Slack)، و`agentFilter`، و`sessionFilter`، و`target` (`"dm"` أو `"channel"` أو `"both"`). -| مجموعة الإجراءات | الافتراضي | الملاحظات | -| ---------------- | --------- | ------------------------- | -| reactions | مفعّلة | تفاعل + سرد التفاعلات | -| messages | مفعّلة | قراءة/إرسال/تحرير/حذف | -| pins | مفعّلة | تثبيت/إلغاء تثبيت/سرد | -| memberInfo | مفعّلة | معلومات العضو | -| emojiList | مفعّلة | قائمة emoji المخصصة | +| مجموعة الإجراءات | الافتراضي | الملاحظات | +| ---------------- | --------- | ---------------------- | +| reactions | مفعّل | التفاعل + عرض التفاعلات | +| messages | مفعّل | قراءة/إرسال/تحرير/حذف | +| pins | مفعّل | تثبيت/إلغاء تثبيت/عرض | +| memberInfo | مفعّل | معلومات العضو | +| emojiList | مفعّل | قائمة الإيموجي المخصصة | ### Mattermost -يُشحن Mattermost كإضافة: `openclaw plugins install @openclaw/mattermost`. +يأتي Mattermost كإضافة plugin: `openclaw plugins install @openclaw/mattermost`. ```json5 { @@ -496,10 +491,10 @@ x-i18n: "team-channel-id": { requireMention: false }, }, commands: { - native: true, // تفعيل اختياري + native: true, // opt-in nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // عنوان URL صريح اختياري لعمليات النشر ذات الوكيل العكسي/العامة + // Optional explicit URL for reverse-proxy/public deployments callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -509,22 +504,20 @@ x-i18n: } ``` -أوضاع الدردشة: `oncall` (الرد عند @-mention، الافتراضي)، و`onmessage` (كل رسالة)، و`onchar` (الرسائل التي تبدأ ببادئة تشغيل). +أوضاع الدردشة: `oncall` (الرد عند @-mention، افتراضي)، `onmessage` (كل رسالة)، `onchar` (الرسائل التي تبدأ ببادئة التشغيل). -عند تفعيل الأوامر الأصلية في Mattermost: +عندما تكون الأوامر الأصلية لـ Mattermost مفعلة: -- يجب أن تكون `commands.callbackPath` مسارًا (على سبيل المثال `/api/channels/mattermost/command`)، لا عنوان URL كاملًا. -- يجب أن تُحل `commands.callbackUrl` إلى نقطة نهاية بوابة OpenClaw وأن يكون خادم Mattermost قادرًا على الوصول إليها. -- تتم مصادقة استدعاءات slash الأصلية بواسطة الرموز المميزة لكل أمر التي يعيدها - Mattermost أثناء تسجيل أوامر slash. وإذا فشل التسجيل أو لم يتم - تفعيل أي أوامر، يرفض OpenClaw الاستدعاءات برسالة +- يجب أن يكون `commands.callbackPath` مسارًا (مثل `/api/channels/mattermost/command`)، وليس URL كاملًا. +- يجب أن يحل `commands.callbackUrl` إلى نقطة نهاية بوابة OpenClaw وأن يكون قابلًا للوصول من خادم Mattermost. +- تتم مصادقة callbacks الخاصة بأوامر slash الأصلية باستخدام الرموز الخاصة بكل أمر التي يعيدها Mattermost أثناء تسجيل أوامر slash. إذا فشل التسجيل أو لم يتم تفعيل أي أوامر، يرفض OpenClaw الاستدعاءات الراجعة بالرسالة `Unauthorized: invalid command token.` -- بالنسبة إلى مضيفات الاستدعاء الخاصة/الداخلية/ذات tailnet، قد يتطلب Mattermost - أن تتضمن `ServiceSettings.AllowedUntrustedInternalConnections` المضيف/النطاق الخاص بالاستدعاء. - استخدم قيم المضيف/النطاق، وليس عناوين URL كاملة. -- `channels.mattermost.configWrites`: السماح أو المنع لعمليات كتابة الإعدادات التي يبدأها Mattermost. -- `channels.mattermost.requireMention`: يتطلب `@mention` قبل الرد في القنوات. -- `channels.mattermost.groups..requireMention`: تجاوز بوابة الإشارة لكل قناة (`"*"` للقيمة الافتراضية). +- بالنسبة لمضيفي callbacks الخاصين/الداخليين/على tailnet، قد يتطلب Mattermost + `ServiceSettings.AllowedUntrustedInternalConnections` أن يتضمن مضيف/نطاق callback. + استخدم قيم المضيف/النطاق، وليس عناوين URL الكاملة. +- `channels.mattermost.configWrites`: السماح أو المنع لعمليات كتابة الإعدادات التي يبدؤها Mattermost. +- `channels.mattermost.requireMention`: يشترط `@mention` قبل الرد في القنوات. +- `channels.mattermost.groups..requireMention`: تجاوز تقييد الإشارات لكل قناة (`"*"` للافتراضي). - يجاوز `channels.mattermost.defaultAccount` الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مكوَّن. ### Signal @@ -534,7 +527,7 @@ x-i18n: channels: { signal: { enabled: true, - account: "+15555550123", // ربط حساب اختياري + account: "+15555550123", // optional account binding dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -546,15 +539,15 @@ x-i18n: } ``` -**أوضاع إشعارات التفاعل:** `off` و`own` (الافتراضي) و`all` و`allowlist` (من `reactionAllowlist`). +**أوضاع إشعارات التفاعلات:** `off`، `own` (افتراضي)، `all`، `allowlist` (من `reactionAllowlist`). -- `channels.signal.account`: يثبّت بدء تشغيل القناة على هوية حساب Signal محددة. -- `channels.signal.configWrites`: السماح أو المنع لعمليات كتابة الإعدادات التي يبدأها Signal. +- `channels.signal.account`: يثبت بدء تشغيل القناة على هوية حساب Signal محددة. +- `channels.signal.configWrites`: السماح أو المنع لعمليات كتابة الإعدادات التي يبدؤها Signal. - يجاوز `channels.signal.defaultAccount` الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مكوَّن. ### BlueBubbles -BlueBubbles هو المسار الموصى به لـ iMessage (مدعوم بإضافة، ومكوَّن ضمن `channels.bluebubbles`). +BlueBubbles هو مسار iMessage الموصى به (مدعوم بإضافة plugin، ويُضبط تحت `channels.bluebubbles`). ```json5 { @@ -562,21 +555,21 @@ BlueBubbles هو المسار الموصى به لـ iMessage (مدعوم بإض bluebubbles: { enabled: true, dmPolicy: "pairing", - // serverUrl، وpassword، وwebhookPath، وعناصر التحكم في المجموعة، والإجراءات المتقدمة: - // راجع /channels/bluebubbles + // serverUrl, password, webhookPath, group controls, and advanced actions: + // see /channels/bluebubbles }, }, } ``` -- مسارات المفاتيح الأساسية المغطاة هنا: `channels.bluebubbles` و`channels.bluebubbles.dmPolicy`. +- مسارات المفاتيح الأساسية المشمولة هنا: `channels.bluebubbles` و`channels.bluebubbles.dmPolicy`. - يجاوز `channels.bluebubbles.defaultAccount` الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مكوَّن. -- يمكن لإدخالات `bindings[]` على المستوى الأعلى مع `type: "acp"` ربط محادثات BlueBubbles بجلسات ACP دائمة. استخدم مقبض BlueBubbles أو سلسلة الهدف (`chat_id:*` أو `chat_guid:*` أو `chat_identifier:*`) في `match.peer.id`. دلالات الحقول المشتركة: [وكلاء ACP](/ar/tools/acp-agents#channel-specific-settings). -- تم توثيق إعداد قناة BlueBubbles الكامل في [BlueBubbles](/ar/channels/bluebubbles). +- يمكن لإدخالات `bindings[]` ذات المستوى الأعلى مع `type: "acp"` ربط محادثات BlueBubbles بجلسات ACP دائمة. استخدم مقبض BlueBubbles أو سلسلة الهدف (`chat_id:*` أو `chat_guid:*` أو `chat_identifier:*`) في `match.peer.id`. دلالات الحقول المشتركة: [وكلاء ACP](/ar/tools/acp-agents#channel-specific-settings). +- تم توثيق الإعداد الكامل لقناة BlueBubbles في [BlueBubbles](/ar/channels/bluebubbles). ### iMessage -يقوم OpenClaw بتشغيل `imsg rpc` ‏(JSON-RPC عبر stdio). لا حاجة إلى daemon أو منفذ. +يشغّل OpenClaw الأمر `imsg rpc` (JSON-RPC عبر stdio). لا يلزم daemon أو منفذ. ```json5 { @@ -602,13 +595,13 @@ BlueBubbles هو المسار الموصى به لـ iMessage (مدعوم بإض - يجاوز `channels.imessage.defaultAccount` الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مكوَّن. -- يتطلب Full Disk Access إلى قاعدة بيانات Messages. -- يُفضَّل استخدام أهداف `chat_id:`. استخدم `imsg chats --limit 20` لسرد المحادثات. +- يتطلب Full Disk Access لقاعدة بيانات Messages. +- يفضَّل استخدام أهداف `chat_id:`. استخدم `imsg chats --limit 20` لعرض الدردشات. - يمكن أن يشير `cliPath` إلى غلاف SSH؛ اضبط `remoteHost` (`host` أو `user@host`) لجلب المرفقات عبر SCP. -- تقيد `attachmentRoots` و`remoteAttachmentRoots` مسارات المرفقات الواردة (الافتراضي: `/Users/*/Library/Messages/Attachments`). +- يقيّد `attachmentRoots` و`remoteAttachmentRoots` مسارات المرفقات الواردة (الافتراضي: `/Users/*/Library/Messages/Attachments`). - يستخدم SCP تحققًا صارمًا من مفتاح المضيف، لذا تأكد من أن مفتاح مضيف relay موجود بالفعل في `~/.ssh/known_hosts`. -- `channels.imessage.configWrites`: السماح أو المنع لعمليات كتابة الإعدادات التي يبدأها iMessage. -- يمكن لإدخالات `bindings[]` على المستوى الأعلى مع `type: "acp"` ربط محادثات iMessage بجلسات ACP دائمة. استخدم مقبضًا مسوّى أو هدف محادثة صريحًا (`chat_id:*` أو `chat_guid:*` أو `chat_identifier:*`) في `match.peer.id`. دلالات الحقول المشتركة: [وكلاء ACP](/ar/tools/acp-agents#channel-specific-settings). +- `channels.imessage.configWrites`: السماح أو المنع لعمليات كتابة الإعدادات التي يبدؤها iMessage. +- يمكن لإدخالات `bindings[]` ذات المستوى الأعلى مع `type: "acp"` ربط محادثات iMessage بجلسات ACP دائمة. استخدم مقبضًا مُطبّعًا أو هدف دردشة صريحًا (`chat_id:*` أو `chat_guid:*` أو `chat_identifier:*`) في `match.peer.id`. دلالات الحقول المشتركة: [وكلاء ACP](/ar/tools/acp-agents#channel-specific-settings). @@ -621,7 +614,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix مدعوم بإضافة ويُكوَّن ضمن `channels.matrix`. +Matrix مدعوم بإضافة extension ويتم ضبطه تحت `channels.matrix`. ```json5 { @@ -652,24 +645,24 @@ Matrix مدعوم بإضافة ويُكوَّن ضمن `channels.matrix`. ``` - تستخدم مصادقة الرمز `accessToken`؛ وتستخدم مصادقة كلمة المرور `userId` + `password`. -- يقوم `channels.matrix.proxy` بتوجيه حركة HTTP الخاصة بـ Matrix عبر وكيل HTTP(S) صريح. ويمكن للحسابات المسماة تجاوزه عبر `channels.matrix.accounts..proxy`. -- يسمح `channels.matrix.network.dangerouslyAllowPrivateNetwork` بخوادم homeserver الخاصة/الداخلية. ويُعد `proxy` وهذا التفعيل الشبكي عنصرَي تحكم مستقلين. -- يحدد `channels.matrix.defaultAccount` الحساب المفضل في إعدادات الحسابات المتعددة. -- تكون القيمة الافتراضية لـ `channels.matrix.autoJoin` هي `off`، لذا يتم تجاهل الغرف المدعو إليها والدعوات الجديدة ذات نمط الرسائل الخاصة حتى تضبط `autoJoin: "allowlist"` مع `autoJoinAllowlist` أو `autoJoin: "always"`. +- يوجّه `channels.matrix.proxy` حركة HTTP الخاصة بـ Matrix عبر وكيل HTTP(S) صريح. ويمكن للحسابات المسماة تجاوزه عبر `channels.matrix.accounts..proxy`. +- يسمح `channels.matrix.network.dangerouslyAllowPrivateNetwork` بخوادم homeserver الخاصة/الداخلية. إن `proxy` وهذا الاشتراك في الشبكة هما عنصران مستقلان. +- يحدد `channels.matrix.defaultAccount` الحساب المفضل في إعدادات تعدد الحسابات. +- يكون `channels.matrix.autoJoin` افتراضيًا `off`، لذا يتم تجاهل الغرف المدعو إليها ودعوات الرسائل الخاصة الجديدة حتى تضبط `autoJoin: "allowlist"` مع `autoJoinAllowlist` أو `autoJoin: "always"`. - `channels.matrix.execApprovals`: تسليم موافقات exec الأصلية في Matrix وتفويض الموافقين. - - `enabled`: إما `true` أو `false` أو `"auto"` (الافتراضي). في الوضع التلقائي، تُفعَّل موافقات exec عندما يمكن حل الموافقين من `approvers` أو `commands.ownerAllowFrom`. + - `enabled`: `true` أو `false` أو `"auto"` (افتراضي). في الوضع التلقائي، تُفعَّل موافقات exec عندما يمكن حل الموافقين من `approvers` أو `commands.ownerAllowFrom`. - `approvers`: معرّفات مستخدمي Matrix (مثل `@owner:example.org`) المسموح لهم بالموافقة على طلبات exec. - `agentFilter`: قائمة سماح اختيارية لمعرّفات الوكلاء. احذفها لتمرير الموافقات لجميع الوكلاء. - `sessionFilter`: أنماط اختيارية لمفاتيح الجلسات (substring أو regex). - - `target`: أين تُرسل مطالبات الموافقة. `"dm"` (الافتراضي)، أو `"channel"` (الغرفة الأصلية)، أو `"both"`. + - `target`: مكان إرسال مطالبات الموافقة. `"dm"` (افتراضي)، أو `"channel"` (الغرفة الأصلية)، أو `"both"`. - تجاوزات لكل حساب: `channels.matrix.accounts..execApprovals`. -- يتحكم `channels.matrix.dm.sessionScope` في كيفية تجميع الرسائل الخاصة في Matrix ضمن الجلسات: `per-user` (الافتراضي) يشارك بحسب النظير الموجَّه، بينما `per-room` يعزل كل غرفة رسائل خاصة. -- تستخدم فحوصات الحالة في Matrix وعمليات البحث المباشر في الدليل نفس سياسة الوكيل الخاصة بحركة وقت التشغيل. -- تم توثيق إعداد Matrix الكامل وقواعد الاستهداف وأمثلة الإعداد في [Matrix](/ar/channels/matrix). +- يتحكم `channels.matrix.dm.sessionScope` في كيفية تجميع رسائل Matrix الخاصة داخل الجلسات: `per-user` (افتراضي) يشارك حسب النظير الموجَّه، بينما `per-room` يعزل كل غرفة DM. +- تستخدم فحوصات حالة Matrix وعمليات البحث المباشر في الدليل نفس سياسة الوكيل المستخدمة لحركة وقت التشغيل. +- تم توثيق إعدادات Matrix الكاملة وقواعد الاستهداف وأمثلة الإعداد في [Matrix](/ar/channels/matrix). ### Microsoft Teams -Microsoft Teams مدعوم بإضافة ويُكوَّن ضمن `channels.msteams`. +Microsoft Teams مدعوم بإضافة extension ويتم ضبطه تحت `channels.msteams`. ```json5 { @@ -677,19 +670,19 @@ Microsoft Teams مدعوم بإضافة ويُكوَّن ضمن `channels.msteam msteams: { enabled: true, configWrites: true, - // appId، وappPassword، وtenantId، وwebhook، وسياسات الفريق/القناة: - // راجع /channels/msteams + // appId, appPassword, tenantId, webhook, team/channel policies: + // see /channels/msteams }, }, } ``` -- مسارات المفاتيح الأساسية المغطاة هنا: `channels.msteams` و`channels.msteams.configWrites`. -- تم توثيق إعداد Teams الكامل (بيانات الاعتماد، وwebhook، وسياسة الرسائل الخاصة/المجموعات، والتجاوزات لكل فريق/قناة) في [Microsoft Teams](/ar/channels/msteams). +- مسارات المفاتيح الأساسية المشمولة هنا: `channels.msteams` و`channels.msteams.configWrites`. +- تم توثيق إعدادات Teams الكاملة (الاعتمادات، webhook، سياسة الرسائل الخاصة/المجموعات، وتجاوزات كل فريق/قناة) في [Microsoft Teams](/ar/channels/msteams). ### IRC -IRC مدعوم بإضافة ويُكوَّن ضمن `channels.irc`. +IRC مدعوم بإضافة extension ويتم ضبطه تحت `channels.irc`. ```json5 { @@ -710,13 +703,13 @@ IRC مدعوم بإضافة ويُكوَّن ضمن `channels.irc`. } ``` -- مسارات المفاتيح الأساسية المغطاة هنا: `channels.irc` و`channels.irc.dmPolicy` و`channels.irc.configWrites` و`channels.irc.nickserv.*`. +- مسارات المفاتيح الأساسية المشمولة هنا: `channels.irc` و`channels.irc.dmPolicy` و`channels.irc.configWrites` و`channels.irc.nickserv.*`. - يجاوز `channels.irc.defaultAccount` الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مكوَّن. -- تم توثيق إعداد قناة IRC الكامل (المضيف/المنفذ/TLS/القنوات/قوائم السماح/بوابة الإشارة) في [IRC](/ar/channels/irc). +- تم توثيق إعداد قناة IRC الكامل (المضيف/المنفذ/TLS/القنوات/قوائم السماح/تقييد الإشارات) في [IRC](/ar/channels/irc). -### متعدد الحسابات (كل القنوات) +### تعدد الحسابات (كل القنوات) -شغّل عدة حسابات لكل قناة (كل منها مع `accountId` خاص به): +شغّل عدة حسابات لكل قناة (لكل منها `accountId` خاص بها): ```json5 { @@ -737,28 +730,28 @@ IRC مدعوم بإضافة ويُكوَّن ضمن `channels.irc`. } ``` -- يُستخدم `default` عندما يتم حذف `accountId` (في CLI + التوجيه). -- تنطبق رموز البيئة فقط على الحساب **الافتراضي**. +- يُستخدم `default` عند حذف `accountId` (في CLI + التوجيه). +- لا تنطبق رموز البيئة إلا على الحساب **الافتراضي**. - تنطبق إعدادات القناة الأساسية على جميع الحسابات ما لم يتم تجاوزها لكل حساب. - استخدم `bindings[].match.accountId` لتوجيه كل حساب إلى وكيل مختلف. -- إذا أضفت حسابًا غير افتراضي عبر `openclaw channels add` (أو عبر إعداد القناة) بينما لا تزال تستخدم إعداد قناة أحادي الحساب على المستوى الأعلى، فسيقوم OpenClaw أولًا بترقية القيم أحادية الحساب الموجودة على المستوى الأعلى والمحددة نطاقًا بالحساب إلى خريطة حسابات القناة حتى يستمر الحساب الأصلي في العمل. تنقل معظم القنوات هذه القيم إلى `channels..accounts.default`؛ بينما يمكن لـ Matrix الاحتفاظ بهدف مسمى/افتراضي قائم ومطابق بدلًا من ذلك. -- تستمر ارتباطات القناة فقط الموجودة (من دون `accountId`) في مطابقة الحساب الافتراضي؛ وتظل الارتباطات المقيّدة بالحساب اختيارية. -- يقوم `openclaw doctor --fix` أيضًا بإصلاح الأشكال المختلطة عبر نقل القيم أحادية الحساب على المستوى الأعلى والمقيدة بالحساب إلى الحساب المُرقّى المختار لتلك القناة. تستخدم معظم القنوات `accounts.default`؛ بينما يمكن لـ Matrix الاحتفاظ بهدف مسمى/افتراضي قائم ومطابق بدلًا من ذلك. +- إذا أضفت حسابًا غير افتراضي عبر `openclaw channels add` (أو إعداد القناة) بينما ما زلت على إعداد قناة أحادي الحساب في المستوى الأعلى، يقوم OpenClaw أولاً بترقية القيم أحادية الحساب على المستوى الأعلى ذات النطاق الحسابي إلى خريطة حسابات القناة حتى يستمر الحساب الأصلي في العمل. تنقل معظم القنوات هذه القيم إلى `channels..accounts.default`؛ ويمكن لـ Matrix بدلًا من ذلك الحفاظ على هدف موجود مطابق باسم/default. +- تستمر الروابط الحالية الخاصة بالقناة فقط (من دون `accountId`) في مطابقة الحساب الافتراضي؛ وتظل الروابط محددة النطاق بالحساب اختيارية. +- يقوم `openclaw doctor --fix` أيضًا بإصلاح الأشكال المختلطة بنقل القيم أحادية الحساب على المستوى الأعلى ذات النطاق الحسابي إلى الحساب المُرقّى المختار لتلك القناة. تستخدم معظم القنوات `accounts.default`؛ ويمكن لـ Matrix الحفاظ على هدف موجود مطابق باسم/default بدلًا من ذلك. -### قنوات الإضافات الأخرى +### قنوات extension أخرى -تُكوَّن العديد من قنوات الإضافات على شكل `channels.` ويتم توثيقها في صفحات القنوات المخصصة لها (على سبيل المثال Feishu وMatrix وLINE وNostr وZalo وNextcloud Talk وSynology Chat وTwitch). +تُضبط العديد من قنوات extension كـ `channels.` ويتم توثيقها في صفحات القنوات المخصصة لها (مثل Feishu وMatrix وLINE وNostr وZalo وNextcloud Talk وSynology Chat وTwitch). راجع فهرس القنوات الكامل: [القنوات](/ar/channels). -### بوابة الإشارة في الدردشة الجماعية +### تقييد الإشارات في الدردشة الجماعية -تتطلب رسائل المجموعات افتراضيًا **الإشارة** (إشارة metadata أو أنماط regex آمنة). وينطبق ذلك على الدردشات الجماعية في WhatsApp وTelegram وDiscord وGoogle Chat وiMessage. +تفترض رسائل المجموعات افتراضيًا **اشتراط الإشارة** (إشارة ضمنية في البيانات الوصفية أو أنماط regex آمنة). ينطبق هذا على مجموعات WhatsApp وTelegram وDiscord وGoogle Chat وiMessage. -**أنواع الإشارة:** +**أنواع الإشارات:** -- **إشارات metadata**: إشارات @-mentions الأصلية للمنصة. ويتم تجاهلها في وضع الدردشة الذاتية لـ WhatsApp. -- **أنماط النص**: أنماط regex آمنة في `agents.list[].groupChat.mentionPatterns`. ويتم تجاهل الأنماط غير الصالحة والتكرار المتداخل غير الآمن. -- يتم فرض بوابة الإشارة فقط عندما يكون الاكتشاف ممكنًا (إشارات أصلية أو نمط واحد على الأقل). +- **إشارات البيانات الوصفية**: إشارات @ الأصلية للمنصة. يتم تجاهلها في وضع الدردشة الذاتية لـ WhatsApp. +- **أنماط النص**: أنماط regex آمنة في `agents.list[].groupChat.mentionPatterns`. يتم تجاهل الأنماط غير الصالحة والتكرار المتداخل غير الآمن. +- يتم فرض تقييد الإشارات فقط عندما يكون الاكتشاف ممكنًا (إشارات أصلية أو نمط واحد على الأقل). ```json5 { @@ -771,7 +764,7 @@ IRC مدعوم بإضافة ويُكوَّن ضمن `channels.irc`. } ``` -يضبط `messages.groupChat.historyLimit` القيمة الافتراضية العامة. ويمكن للقنوات التجاوز عبر `channels..historyLimit` (أو لكل حساب). اضبط `0` للتعطيل. +يضبط `messages.groupChat.historyLimit` القيمة الافتراضية العامة. ويمكن للقنوات تجاوزها عبر `channels..historyLimit` (أو لكل حساب). اضبطها إلى `0` للتعطيل. #### حدود سجل الرسائل الخاصة @@ -788,13 +781,13 @@ IRC مدعوم بإضافة ويُكوَّن ضمن `channels.irc`. } ``` -آلية الحل: تجاوز لكل رسالة خاصة → القيمة الافتراضية للمزوّد → بلا حد (يتم الاحتفاظ بكل شيء). +آلية الحل: تجاوز لكل DM → افتراضي المزوّد → لا حد (الاحتفاظ بكل شيء). -المدعوم: `telegram` و`whatsapp` و`discord` و`slack` و`signal` و`imessage` و`msteams`. +المدعوم: `telegram`، `whatsapp`، `discord`، `slack`، `signal`، `imessage`، `msteams`. #### وضع الدردشة الذاتية -ضمّن رقمك الخاص في `allowFrom` لتفعيل وضع الدردشة الذاتية (يتجاهل إشارات @ الأصلية، ويرد فقط على أنماط النص): +أدرج رقمك الخاص في `allowFrom` لتفعيل وضع الدردشة الذاتية (يتجاهل إشارات @ الأصلية ويرد فقط على الأنماط النصية): ```json5 { @@ -820,13 +813,13 @@ IRC مدعوم بإضافة ويُكوَّن ضمن `channels.irc`. ```json5 { commands: { - native: "auto", // تسجيل الأوامر الأصلية عندما تكون مدعومة - text: true, // تحليل /commands في رسائل الدردشة - bash: false, // السماح بـ ! (اسم بديل: /bash) + native: "auto", // register native commands when supported + text: true, // parse /commands in chat messages + bash: false, // allow ! (alias: /bash) bashForegroundMs: 2000, - config: false, // السماح بـ /config - debug: false, // السماح بـ /debug - restart: false, // السماح بـ /restart + أداة إعادة تشغيل البوابة + config: false, // allow /config + debug: false, // allow /debug + restart: false, // allow /restart + gateway restart tool allowFrom: { "*": ["user1"], discord: ["user:123"], @@ -838,22 +831,22 @@ IRC مدعوم بإضافة ويُكوَّن ضمن `channels.irc`. -- يجب أن تكون الأوامر النصية رسائل **مستقلة** مع `/` في البداية. -- يقوم `native: "auto"` بتشغيل الأوامر الأصلية لـ Discord/Telegram، ويترك Slack معطّلًا. -- تجاوز لكل قناة: `channels.discord.commands.native` (قيمة منطقية أو `"auto"`). تقوم `false` بمسح الأوامر المسجلة سابقًا. -- يضيف `channels.telegram.customCommands` إدخالات إضافية إلى قائمة روبوت Telegram. -- يفعّل `bash: true` الأمر `! ` لصدفة المضيف. ويتطلب `tools.elevated.enabled` وأن يكون المرسل موجودًا في `tools.elevated.allowFrom.`. -- يفعّل `config: true` الأمر `/config` (قراءة/كتابة `openclaw.json`). بالنسبة إلى عملاء البوابة `chat.send`، تتطلب أيضًا عمليات الكتابة المستمرة عبر `/config set|unset` صلاحية `operator.admin`؛ بينما يظل `/config show` للقراءة فقط متاحًا لعملاء المشغّل العاديين ذوي نطاق الكتابة. -- تتحكم `channels..configWrites` في طفرات الإعدادات لكل قناة (الافتراضي: true). -- بالنسبة إلى القنوات متعددة الحسابات، تتحكم أيضًا `channels..accounts..configWrites` في عمليات الكتابة التي تستهدف ذلك الحساب (على سبيل المثال `/allowlist --config --account ` أو `/config set channels..accounts....`). -- تكون `allowFrom` لكل مزوّد. وعند تعيينها، فإنها تكون **المصدر الوحيد** للتفويض (ويتم تجاهل قوائم سماح القناة/الاقتران و`useAccessGroups`). -- يسمح `useAccessGroups: false` للأوامر بتجاوز سياسات مجموعات الوصول عندما لا تكون `allowFrom` معيّنة. +- يجب أن تكون الأوامر النصية رسائل **مستقلة** تبدأ بـ `/`. +- `native: "auto"` يفعّل الأوامر الأصلية لـ Discord/Telegram ويُبقي Slack معطلاً. +- تجاوز لكل قناة: `channels.discord.commands.native` (قيمة منطقية أو `"auto"`). تؤدي `false` إلى مسح الأوامر المسجلة سابقًا. +- يضيف `channels.telegram.customCommands` إدخالات إضافية إلى قائمة بوت Telegram. +- يفعّل `bash: true` الأمر `! ` لصدفة المضيف. يتطلب `tools.elevated.enabled` وأن يكون المرسل ضمن `tools.elevated.allowFrom.`. +- يفعّل `config: true` الأمر `/config` (قراءة/كتابة `openclaw.json`). بالنسبة لعملاء `chat.send` في البوابة، تتطلب الكتابات الدائمة عبر `/config set|unset` أيضًا `operator.admin`؛ بينما يبقى `/config show` للقراءة فقط متاحًا للعملاء العاديين ذوي نطاق الكتابة. +- يقيّد `channels..configWrites` عمليات تعديل الإعدادات لكل قناة (الافتراضي: true). +- بالنسبة للقنوات متعددة الحسابات، يقيّد `channels..accounts..configWrites` أيضًا عمليات الكتابة التي تستهدف ذلك الحساب (مثل `/allowlist --config --account ` أو `/config set channels..accounts....`). +- يكون `allowFrom` لكل مزوّد. عند تعيينه، يصبح هو **مصدر التفويض الوحيد** (ويتم تجاهل قوائم السماح/الإقران الخاصة بالقناة و`useAccessGroups`). +- يسمح `useAccessGroups: false` للأوامر بتجاوز سياسات مجموعات الوصول عندما لا يكون `allowFrom` معيّنًا. --- -## الإعدادات الافتراضية للوكلاء +## القيم الافتراضية للوكلاء ### `agents.defaults.workspace` @@ -867,7 +860,7 @@ IRC مدعوم بإضافة ويُكوَّن ضمن `channels.irc`. ### `agents.defaults.repoRoot` -جذر مستودع اختياري يظهر في سطر Runtime ضمن system prompt. وإذا لم يُعيّن، يكتشفه OpenClaw تلقائيًا من خلال الصعود من مساحة العمل. +جذر مستودع اختياري يُعرض في سطر Runtime ضمن system prompt. إذا لم يُعيَّن، يكتشفه OpenClaw تلقائيًا عبر الصعود من مساحة العمل. ```json5 { @@ -877,7 +870,7 @@ IRC مدعوم بإضافة ويُكوَّن ضمن `channels.irc`. ### `agents.defaults.skills` -قائمة سماح افتراضية اختيارية لـ Skills للوكلاء الذين لا يضبطون +قائمة سماح افتراضية اختيارية لـ Skills للوكلاء الذين لا يعيّنون `agents.list[].skills`. ```json5 @@ -885,23 +878,23 @@ IRC مدعوم بإضافة ويُكوَّن ضمن `channels.irc`. agents: { defaults: { skills: ["github", "weather"] }, list: [ - { id: "writer" }, // يرث github, weather - { id: "docs", skills: ["docs-search"] }, // يستبدل الإعدادات الافتراضية - { id: "locked-down", skills: [] }, // بلا Skills + { id: "writer" }, // inherits github, weather + { id: "docs", skills: ["docs-search"] }, // replaces defaults + { id: "locked-down", skills: [] }, // no skills ], }, } ``` - احذف `agents.defaults.skills` للحصول على Skills غير مقيّدة افتراضيًا. -- احذف `agents.list[].skills` لوراثة الإعدادات الافتراضية. -- اضبط `agents.list[].skills: []` لعدم استخدام أي Skills. -- تكون القائمة غير الفارغة في `agents.list[].skills` هي المجموعة النهائية لذلك الوكيل؛ - ولا يتم دمجها مع الإعدادات الافتراضية. +- احذف `agents.list[].skills` لوراثة القيم الافتراضية. +- عيّن `agents.list[].skills: []` لعدم وجود أي Skills. +- قائمة `agents.list[].skills` غير الفارغة هي المجموعة النهائية لذلك الوكيل؛ + ولا يتم دمجها مع القيم الافتراضية. ### `agents.defaults.skipBootstrap` -يعطّل الإنشاء التلقائي لملفات bootstrap في مساحة العمل (`AGENTS.md` و`SOUL.md` و`TOOLS.md` و`IDENTITY.md` و`USER.md` و`HEARTBEAT.md` و`BOOTSTRAP.md`). +يعطّل الإنشاء التلقائي لملفات bootstrap الخاصة بمساحة العمل (`AGENTS.md`، `SOUL.md`، `TOOLS.md`، `IDENTITY.md`، `USER.md`، `HEARTBEAT.md`، `BOOTSTRAP.md`). ```json5 { @@ -911,9 +904,9 @@ IRC مدعوم بإضافة ويُكوَّن ضمن `channels.irc`. ### `agents.defaults.contextInjection` -يتحكم في وقت حقن ملفات bootstrap الخاصة بمساحة العمل في system prompt. القيمة الافتراضية: `"always"`. +يتحكم في وقت حقن ملفات bootstrap الخاصة بمساحة العمل في system prompt. الافتراضي: `"always"`. -- `"continuation-skip"`: تتخطى أدوار المتابعة الآمنة (بعد رد مساعد مكتمل) إعادة حقن bootstrap الخاص بمساحة العمل، مما يقلل حجم prompt. وتعيد تشغيلات نبض الحياة وإعادة المحاولة بعد الضغط بناء السياق. +- `"continuation-skip"`: في أدوار المتابعة الآمنة (بعد اكتمال رد المساعد) يتم تخطي إعادة حقن bootstrap الخاص بمساحة العمل، مما يقلل حجم prompt. تظل تشغيلات heartbeat وإعادات المحاولة بعد الضغط تعيد بناء السياق. ```json5 { @@ -923,7 +916,7 @@ IRC مدعوم بإضافة ويُكوَّن ضمن `channels.irc`. ### `agents.defaults.bootstrapMaxChars` -الحد الأقصى لعدد الأحرف لكل ملف bootstrap في مساحة العمل قبل الاقتصاص. الافتراضي: `20000`. +الحد الأقصى لعدد الأحرف لكل ملف bootstrap في مساحة العمل قبل الاقتطاع. الافتراضي: `20000`. ```json5 { @@ -943,10 +936,10 @@ IRC مدعوم بإضافة ويُكوَّن ضمن `channels.irc`. ### `agents.defaults.bootstrapPromptTruncationWarning` -يتحكم في نص التحذير المرئي للوكيل عندما يتم اقتطاع سياق bootstrap. +يتحكم في نص التحذير الظاهر للوكيل عندما يتم اقتطاع سياق bootstrap. الافتراضي: `"once"`. -- `"off"`: لا يحقن نص تحذير في system prompt مطلقًا. +- `"off"`: لا يحقن نص تحذير في system prompt أبدًا. - `"once"`: يحقن التحذير مرة واحدة لكل توقيع اقتطاع فريد (موصى به). - `"always"`: يحقن التحذير في كل تشغيل عندما يوجد اقتطاع. @@ -958,11 +951,11 @@ IRC مدعوم بإضافة ويُكوَّن ضمن `channels.irc`. ### `agents.defaults.imageMaxDimensionPx` -الحد الأقصى لحجم البكسل لأطول ضلع في الصور ضمن كتل الصور الخاصة بالسجل/الأدوات قبل استدعاءات المزوّد. +أقصى حجم بكسلي لأطول ضلع في الصورة داخل كتل صور transcript/tool قبل استدعاءات المزوّد. الافتراضي: `1200`. -تقلل القيم الأقل عادة من استخدام vision-token وحجم حمولة الطلب في التشغيلات الثقيلة لصور الشاشة. -وتحافظ القيم الأعلى على مزيد من التفاصيل المرئية. +القيم الأقل تقلل عادةً من استخدام vision-token وحجم حمولة الطلب في التشغيلات الثقيلة باللقطات. +والقيم الأعلى تحافظ على مزيد من التفاصيل البصرية. ```json5 { @@ -972,7 +965,7 @@ IRC مدعوم بإضافة ويُكوَّن ضمن `channels.irc`. ### `agents.defaults.userTimezone` -المنطقة الزمنية لسياق system prompt (وليس طوابع وقت الرسائل). وتعود إلى المنطقة الزمنية للمضيف. +المنطقة الزمنية لسياق system prompt (وليس الطوابع الزمنية للرسائل). تعود إلى المنطقة الزمنية للمضيف. ```json5 { @@ -1020,7 +1013,7 @@ IRC مدعوم بإضافة ويُكوَّن ضمن `channels.irc`. primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // معاملات المزوّد الافتراضية العامة + params: { cacheRetention: "long" }, // global default provider params pdfMaxBytesMb: 10, pdfMaxPages: 20, thinkingDefault: "low", @@ -1035,64 +1028,64 @@ IRC مدعوم بإضافة ويُكوَّن ضمن `channels.irc`. } ``` -- يقبل `model` إما سلسلة (`"provider/model"`) أو كائنًا (`{ primary, fallbacks }`). - - يضبط الشكل النصي النموذج الأساسي فقط. - - يضبط شكل الكائن النموذج الأساسي بالإضافة إلى نماذج الفشل الاحتياطية المرتّبة. -- يقبل `imageModel` إما سلسلة (`"provider/model"`) أو كائنًا (`{ primary, fallbacks }`). - - يُستخدم بواسطة مسار أداة `image` كإعداد نموذج الرؤية الخاص بها. - - ويُستخدم أيضًا كتوجيه احتياطي عندما لا يستطيع النموذج المحدد/الافتراضي قبول إدخال صور. -- يقبل `imageGenerationModel` إما سلسلة (`"provider/model"`) أو كائنًا (`{ primary, fallbacks }`). - - يُستخدم بواسطة قدرة توليد الصور المشتركة وأي سطح أداة/إضافة مستقبلي يولّد الصور. - - القيم النموذجية: `google/gemini-3.1-flash-image-preview` لتوليد صور Gemini الأصلي، أو `fal/fal-ai/flux/dev` لـ fal، أو `openai/gpt-image-1` لـ OpenAI Images. - - إذا حددت مزوّدًا/نموذجًا مباشرة، فاضبط أيضًا مصادقة/مفتاح API للمزوّد المطابق (على سبيل المثال `GEMINI_API_KEY` أو `GOOGLE_API_KEY` لـ `google/*`، و`OPENAI_API_KEY` لـ `openai/*`، و`FAL_KEY` لـ `fal/*`). - - إذا تم حذفها، فلا يزال بإمكان `image_generate` استنتاج قيمة افتراضية لمزوّد مدعوم بالمصادقة. وهو يجرّب أولًا المزوّد الافتراضي الحالي، ثم بقية مزوّدي توليد الصور المسجلين بترتيب معرّف المزوّد. -- يقبل `musicGenerationModel` إما سلسلة (`"provider/model"`) أو كائنًا (`{ primary, fallbacks }`). - - يُستخدم بواسطة قدرة توليد الموسيقى المشتركة والأداة المضمّنة `music_generate`. - - القيم النموذجية: `google/lyria-3-clip-preview` أو `google/lyria-3-pro-preview` أو `minimax/music-2.5+`. - - إذا تم حذفها، فلا يزال بإمكان `music_generate` استنتاج قيمة افتراضية لمزوّد مدعوم بالمصادقة. وهو يجرّب أولًا المزوّد الافتراضي الحالي، ثم بقية مزوّدي توليد الموسيقى المسجلين بترتيب معرّف المزوّد. - - إذا حددت مزوّدًا/نموذجًا مباشرة، فاضبط أيضًا مصادقة/مفتاح API للمزوّد المطابق. -- يقبل `videoGenerationModel` إما سلسلة (`"provider/model"`) أو كائنًا (`{ primary, fallbacks }`). - - يُستخدم بواسطة قدرة توليد الفيديو المشتركة والأداة المضمّنة `video_generate`. - - القيم النموذجية: `qwen/wan2.6-t2v` أو `qwen/wan2.6-i2v` أو `qwen/wan2.6-r2v` أو `qwen/wan2.6-r2v-flash` أو `qwen/wan2.7-r2v`. - - إذا تم حذفها، فلا يزال بإمكان `video_generate` استنتاج قيمة افتراضية لمزوّد مدعوم بالمصادقة. وهو يجرّب أولًا المزوّد الافتراضي الحالي، ثم بقية مزوّدي توليد الفيديو المسجلين بترتيب معرّف المزوّد. - - إذا حددت مزوّدًا/نموذجًا مباشرة، فاضبط أيضًا مصادقة/مفتاح API للمزوّد المطابق. - - يدعم مزوّد توليد الفيديو المضمّن Qwen حاليًا حتى فيديو خرج واحد، وصورة دخل واحدة، و4 فيديوهات دخل، ومدة 10 ثوانٍ، وخيارات على مستوى المزوّد مثل `size` و`aspectRatio` و`resolution` و`audio` و`watermark`. -- يقبل `pdfModel` إما سلسلة (`"provider/model"`) أو كائنًا (`{ primary, fallbacks }`). +- `model`: يقبل إما سلسلة نصية (`"provider/model"`) أو كائنًا (`{ primary, fallbacks }`). + - صيغة السلسلة تضبط النموذج الأساسي فقط. + - صيغة الكائن تضبط النموذج الأساسي بالإضافة إلى نماذج الفشل الاحتياطي بالترتيب. +- `imageModel`: يقبل إما سلسلة نصية (`"provider/model"`) أو كائنًا (`{ primary, fallbacks }`). + - يُستخدم بواسطة مسار أداة `image` بوصفه إعداد نموذج الرؤية. + - ويُستخدم أيضًا كتوجيه احتياطي عندما لا يستطيع النموذج المحدد/الافتراضي قبول إدخال الصور. +- `imageGenerationModel`: يقبل إما سلسلة نصية (`"provider/model"`) أو كائنًا (`{ primary, fallbacks }`). + - يُستخدم بواسطة قدرة توليد الصور المشتركة وأي سطح أداة/إضافة plugin مستقبلي يولد صورًا. + - القيم المعتادة: `google/gemini-3.1-flash-image-preview` لتوليد صور Gemini الأصلي، أو `fal/fal-ai/flux/dev` لـ fal، أو `openai/gpt-image-1` لصور OpenAI. + - إذا اخترت مزودًا/نموذجًا مباشرة، فقم أيضًا بضبط مصادقة/مفتاح API للمزوّد المطابق (مثل `GEMINI_API_KEY` أو `GOOGLE_API_KEY` لـ `google/*`، أو `OPENAI_API_KEY` لـ `openai/*`، أو `FAL_KEY` لـ `fal/*`). + - إذا تم حذفه، فلا يزال بإمكان `image_generate` استنتاج مزود افتراضي مدعوم بالمصادقة. يحاول أولاً المزوّد الافتراضي الحالي، ثم مزوّدي توليد الصور الآخرين المسجلين حسب ترتيب معرّف المزوّد. +- `musicGenerationModel`: يقبل إما سلسلة نصية (`"provider/model"`) أو كائنًا (`{ primary, fallbacks }`). + - يُستخدم بواسطة قدرة توليد الموسيقى المشتركة وأداة `music_generate` المضمّنة. + - القيم المعتادة: `google/lyria-3-clip-preview` أو `google/lyria-3-pro-preview` أو `minimax/music-2.5+`. + - إذا تم حذفه، فلا يزال بإمكان `music_generate` استنتاج مزود افتراضي مدعوم بالمصادقة. يحاول أولاً المزوّد الافتراضي الحالي، ثم مزوّدي توليد الموسيقى الآخرين المسجلين حسب ترتيب معرّف المزوّد. + - إذا اخترت مزودًا/نموذجًا مباشرة، فقم أيضًا بضبط مصادقة/مفتاح API للمزوّد المطابق. +- `videoGenerationModel`: يقبل إما سلسلة نصية (`"provider/model"`) أو كائنًا (`{ primary, fallbacks }`). + - يُستخدم بواسطة قدرة توليد الفيديو المشتركة وأداة `video_generate` المضمّنة. + - القيم المعتادة: `qwen/wan2.6-t2v` أو `qwen/wan2.6-i2v` أو `qwen/wan2.6-r2v` أو `qwen/wan2.6-r2v-flash` أو `qwen/wan2.7-r2v`. + - إذا تم حذفه، فلا يزال بإمكان `video_generate` استنتاج مزود افتراضي مدعوم بالمصادقة. يحاول أولاً المزوّد الافتراضي الحالي، ثم مزوّدي توليد الفيديو الآخرين المسجلين حسب ترتيب معرّف المزوّد. + - إذا اخترت مزودًا/نموذجًا مباشرة، فقم أيضًا بضبط مصادقة/مفتاح API للمزوّد المطابق. + - يدعم مزوّد Qwen المضمّن لتوليد الفيديو حاليًا حتى 1 فيديو خرج، و1 صورة إدخال، و4 فيديوهات إدخال، ومدة 10 ثوانٍ، وخيارات على مستوى المزوّد مثل `size` و`aspectRatio` و`resolution` و`audio` و`watermark`. +- `pdfModel`: يقبل إما سلسلة نصية (`"provider/model"`) أو كائنًا (`{ primary, fallbacks }`). - يُستخدم بواسطة أداة `pdf` لتوجيه النموذج. - - إذا تم حذفها، تعود أداة PDF إلى `imageModel`، ثم إلى النموذج المحلول للجلسة/الافتراضي. -- `pdfMaxBytesMb`: الحد الافتراضي لحجم PDF لأداة `pdf` عندما لا يتم تمرير `maxBytesMb` وقت الاستدعاء. -- `pdfMaxPages`: الحد الأقصى الافتراضي للصفحات التي ينظر إليها وضع الاستخراج الاحتياطي في أداة `pdf`. -- `verboseDefault`: مستوى verbose الافتراضي للوكلاء. القيم: `"off"` و`"on"` و`"full"`. الافتراضي: `"off"`. -- `elevatedDefault`: مستوى المخرجات المرتفعة الافتراضي للوكلاء. القيم: `"off"` و`"on"` و`"ask"` و`"full"`. الافتراضي: `"on"`. -- `model.primary`: التنسيق `provider/model` (مثل `openai/gpt-5.4`). إذا حذفت المزوّد، يحاول OpenClaw أولًا اسمًا مستعارًا، ثم مطابقة فريدة لمزوّد مكوَّن لهذا المعرّف الدقيق للنموذج، وبعدها فقط يعود إلى المزوّد الافتراضي المكوَّن (سلوك توافق قديم، لذا يفضَّل `provider/model` الصريح). وإذا لم يعد ذلك المزوّد يوفّر النموذج الافتراضي المكوَّن، يعود OpenClaw إلى أول مزوّد/نموذج مكوَّن بدلًا من إظهار قيمة افتراضية قديمة لمزوّد تمت إزالته. -- `models`: كتالوج النماذج المكوَّن وقائمة السماح الخاصة بـ `/model`. يمكن أن يتضمن كل إدخال `alias` (اختصارًا) و`params` (خاصة بالمزوّد، مثل `temperature` و`maxTokens` و`cacheRetention` و`context1m`). -- `params`: معاملات المزوّد الافتراضية العامة المطبقة على جميع النماذج. وتُضبط عند `agents.defaults.params` (مثل `{ cacheRetention: "long" }`). -- أسبقية دمج `params` (في الإعداد): يتم تجاوز `agents.defaults.params` (القاعدة العامة) بواسطة `agents.defaults.models["provider/model"].params` (لكل نموذج)، ثم تتجاوزها `agents.list[].params` (لمعرّف الوكيل المطابق) حسب المفتاح. راجع [Prompt Caching](/ar/reference/prompt-caching) للتفاصيل. -- يقوم كتّاب الإعداد الذين يغيّرون هذه الحقول (على سبيل المثال `/models set` و`/models set-image` وأوامر إضافة/إزالة fallback) بحفظ الشكل القياسي للكائن والحفاظ على قوائم fallback الموجودة عندما يكون ذلك ممكنًا. -- `maxConcurrent`: الحد الأقصى لتشغيلات الوكلاء المتوازية عبر الجلسات (مع بقاء كل جلسة مسلسلة). الافتراضي: 4. + - إذا تم حذفه، تعود أداة PDF إلى `imageModel` ثم إلى النموذج المحلول للجلسة/الافتراضي. +- `pdfMaxBytesMb`: حد حجم PDF الافتراضي لأداة `pdf` عندما لا يتم تمرير `maxBytesMb` وقت الاستدعاء. +- `pdfMaxPages`: الحد الأقصى الافتراضي للصفحات التي تؤخذ بعين الاعتبار في وضع الاسترجاع الاحتياطي داخل أداة `pdf`. +- `verboseDefault`: مستوى verbose الافتراضي للوكلاء. القيم: `"off"`، `"on"`، `"full"`. الافتراضي: `"off"`. +- `elevatedDefault`: مستوى المخرجات elevated الافتراضي للوكلاء. القيم: `"off"`، `"on"`، `"ask"`، `"full"`. الافتراضي: `"on"`. +- `model.primary`: التنسيق `provider/model` (مثلاً `openai/gpt-5.4`). إذا حذفت المزوّد، يحاول OpenClaw أولاً اسمًا مستعارًا، ثم مطابقة مزوّد مكوَّن فريدة لذلك معرّف النموذج الدقيق، وبعدها فقط يعود إلى المزوّد الافتراضي المكوَّن (سلوك توافق قديم، لذا يُفضّل استخدام `provider/model` صريحًا). إذا لم يعد ذلك المزوّد يوفّر النموذج الافتراضي المكوَّن، يعود OpenClaw إلى أول مزوّد/نموذج مكوَّن بدلًا من إظهار افتراضي قديم لمزوّد تمت إزالته. +- `models`: فهرس النماذج المكوَّن وقائمة السماح الخاصة بـ `/model`. يمكن أن يتضمن كل إدخال `alias` (اختصار) و`params` (خاصة بالمزوّد، مثل `temperature` أو `maxTokens` أو `cacheRetention` أو `context1m`). +- `params`: معلمات المزوّد الافتراضية العامة المطبقة على جميع النماذج. يتم ضبطها في `agents.defaults.params` (مثل `{ cacheRetention: "long" }`). +- أولوية دمج `params` (في الإعدادات): يتم تجاوز `agents.defaults.params` (الأساس العام) بواسطة `agents.defaults.models["provider/model"].params` (لكل نموذج)، ثم تتجاوز `agents.list[].params` (لـ agent id المطابق) حسب المفتاح. راجع [Prompt Caching](/ar/reference/prompt-caching) للتفاصيل. +- تحفظ كاتبات الإعدادات التي تعدل هذه الحقول (مثل `/models set` و`/models set-image` وأوامر إضافة/إزالة fallback) صيغة الكائن القياسية وتحافظ على قوائم fallback الحالية متى أمكن. +- `maxConcurrent`: الحد الأقصى للتشغيلات المتوازية للوكلاء عبر الجلسات (مع بقاء كل جلسة متسلسلة). الافتراضي: 4. -**اختصارات الأسماء المستعارة المضمّنة** (لا تُطبّق إلا عندما يكون النموذج موجودًا في `agents.defaults.models`): +**اختصارات الأسماء المستعارة المضمّنة** (تنطبق فقط عندما يكون النموذج موجودًا في `agents.defaults.models`): -| الاسم المستعار | النموذج | -| ------------------- | -------------------------------------- | -| `opus` | `anthropic/claude-opus-4-6` | -| `sonnet` | `anthropic/claude-sonnet-4-6` | -| `gpt` | `openai/gpt-5.4` | -| `gpt-mini` | `openai/gpt-5.4-mini` | -| `gpt-nano` | `openai/gpt-5.4-nano` | -| `gemini` | `google/gemini-3.1-pro-preview` | -| `gemini-flash` | `google/gemini-3-flash-preview` | -| `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | +| الاسم المستعار | النموذج | +| ------------------- | --------------------------------------- | +| `opus` | `anthropic/claude-opus-4-6` | +| `sonnet` | `anthropic/claude-sonnet-4-6` | +| `gpt` | `openai/gpt-5.4` | +| `gpt-mini` | `openai/gpt-5.4-mini` | +| `gpt-nano` | `openai/gpt-5.4-nano` | +| `gemini` | `google/gemini-3.1-pro-preview` | +| `gemini-flash` | `google/gemini-3-flash-preview` | +| `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | تتغلب الأسماء المستعارة التي تضبطها أنت دائمًا على القيم الافتراضية. -تفعّل نماذج Z.AI GLM-4.x وضع التفكير تلقائيًا ما لم تضبط `--thinking off` أو تعرّف `agents.defaults.models["zai/"].params.thinking` بنفسك. -وتفعّل نماذج Z.AI القيمة `tool_stream` افتراضيًا لبث استدعاءات الأدوات. اضبط `agents.defaults.models["zai/"].params.tool_stream` إلى `false` لتعطيلها. -وتستخدم نماذج Anthropic Claude 4.6 القيمة الافتراضية `adaptive` للتفكير عندما لا يكون هناك مستوى تفكير صريح. +تفعّل نماذج Z.AI GLM-4.x وضع التفكير تلقائيًا ما لم تضبط `--thinking off` أو تعرّف بنفسك `agents.defaults.models["zai/"].params.thinking`. +وتفعّل نماذج Z.AI `tool_stream` افتراضيًا لبث استدعاءات الأدوات. اضبط `agents.defaults.models["zai/"].params.tool_stream` إلى `false` لتعطيله. +وتستخدم نماذج Anthropic Claude 4.6 افتراضيًا التفكير `adaptive` عندما لا يكون مستوى التفكير معيّنًا صراحة. ### `agents.defaults.cliBackends` -واجهات CLI خلفية اختيارية لتشغيلات النص فقط الاحتياطية (من دون استدعاءات أدوات). وهي مفيدة كنسخة احتياطية عندما تفشل مزوّدات API. +خلفيات CLI اختيارية لتشغيلات الاحتياط النصية فقط (من دون استدعاءات أدوات). مفيدة كنسخة احتياطية عندما تفشل مزوّدو API. ```json5 { @@ -1120,28 +1113,28 @@ IRC مدعوم بإضافة ويُكوَّن ضمن `channels.irc`. } ``` -- الواجهات الخلفية لـ CLI موجهة للنص أولًا؛ وتكون الأدوات معطّلة دائمًا. -- تُدعَم الجلسات عندما يكون `sessionArg` معيّنًا. -- يُدعَم تمرير الصور عندما يقبل `imageArg` مسارات الملفات. +- خلفيات CLI موجهة للنص أولاً؛ يتم دائمًا تعطيل الأدوات. +- الجلسات مدعومة عندما يكون `sessionArg` معيّنًا. +- تمرير الصور مدعوم عندما يقبل `imageArg` مسارات الملفات. ### `agents.defaults.heartbeat` -تشغيلات نبض حياة دورية. +تشغيلات heartbeat دورية. ```json5 { agents: { defaults: { heartbeat: { - every: "30m", // 0m للتعطيل + every: "30m", // 0m disables model: "openai/gpt-5.4-mini", includeReasoning: false, - lightContext: false, // الافتراضي: false؛ تجعل true الإبقاء على HEARTBEAT.md فقط من ملفات bootstrap الخاصة بمساحة العمل - isolatedSession: false, // الافتراضي: false؛ تجعل true كل نبضة تعمل في جلسة جديدة (من دون سجل محادثة) + lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files + isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history) session: "main", to: "+15555550123", - directPolicy: "allow", // allow (الافتراضي) | block - target: "none", // الافتراضي: none | الخيارات: last | whatsapp | telegram | discord | ... + directPolicy: "allow", // allow (default) | block + target: "none", // default: none | options: last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, @@ -1152,12 +1145,12 @@ IRC مدعوم بإضافة ويُكوَّن ضمن `channels.irc`. ``` - `every`: سلسلة مدة (ms/s/m/h). الافتراضي: `30m` (مصادقة API-key) أو `1h` (مصادقة OAuth). اضبطها إلى `0m` للتعطيل. -- `suppressToolErrorWarnings`: عندما تكون true، تكبت حمولات تحذير أخطاء الأدوات أثناء تشغيلات نبض الحياة. -- `directPolicy`: سياسة التسليم المباشر/الرسائل الخاصة. تسمح `allow` (الافتراضي) بالتسليم إلى هدف مباشر. وتمنع `block` التسليم إلى هدف مباشر وتصدر `reason=dm-blocked`. -- `lightContext`: عندما تكون true، تستخدم تشغيلات نبض الحياة سياق bootstrap خفيفًا وتحتفظ فقط بـ `HEARTBEAT.md` من ملفات bootstrap الخاصة بمساحة العمل. -- `isolatedSession`: عندما تكون true، تعمل كل نبضة في جلسة جديدة من دون أي سجل محادثة سابق. نفس نمط العزل المستخدم في cron `sessionTarget: "isolated"`. ويقلل تكلفة tokens لكل نبضة من نحو 100K إلى 2-5K tokens. -- لكل وكيل: اضبط `agents.list[].heartbeat`. وعندما يعرّف أي وكيل `heartbeat`، **فإن هؤلاء الوكلاء فقط** هم الذين ينفذون نبضات الحياة. -- تنفذ نبضات الحياة أدوار وكيل كاملة — والفترات الأقصر تستهلك tokens أكثر. +- `suppressToolErrorWarnings`: عندما تكون true، تُخفي حمولات تحذير أخطاء الأدوات أثناء تشغيلات heartbeat. +- `directPolicy`: سياسة التسليم المباشر/الخاص. `allow` (افتراضي) يسمح بالتسليم المباشر المستهدف. `block` يمنع التسليم المباشر المستهدف ويصدر `reason=dm-blocked`. +- `lightContext`: عندما تكون true، تستخدم تشغيلات heartbeat سياق bootstrap خفيف الوزن وتحتفظ فقط بـ `HEARTBEAT.md` من ملفات bootstrap الخاصة بمساحة العمل. +- `isolatedSession`: عندما تكون true، يعمل كل heartbeat في جلسة جديدة من دون سجل محادثة سابق. نفس نمط العزل المستخدم في cron مع `sessionTarget: "isolated"`. يقلل كلفة الرموز لكل heartbeat من حوالي ~100K إلى ~2-5K token. +- لكل وكيل: عيّن `agents.list[].heartbeat`. عندما يعرّف أي وكيل `heartbeat`، **تعمل heartbeat فقط لهؤلاء الوكلاء**. +- تشغّل heartbeat أدوار الوكيل كاملة — الفترات الأقصر تستهلك مزيدًا من الرموز. ### `agents.defaults.compaction` @@ -1167,13 +1160,14 @@ IRC مدعوم بإضافة ويُكوَّن ضمن `channels.irc`. defaults: { compaction: { mode: "safeguard", // default | safeguard + provider: "my-provider", // id of a registered compaction provider plugin (optional) timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // تُستخدم عندما identifierPolicy=custom - postCompactionSections: ["Session Startup", "Red Lines"], // [] للتعطيل - model: "openrouter/anthropic/claude-sonnet-4-6", // تجاوز اختياري للنموذج الخاص بالضغط فقط - notifyUser: true, // أرسل إشعارًا موجزًا عند بدء الضغط (الافتراضي: false) + identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom + postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection + model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override + notifyUser: true, // send a brief notice when compaction starts (default: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, @@ -1186,18 +1180,19 @@ IRC مدعوم بإضافة ويُكوَّن ضمن `channels.irc`. } ``` -- `mode`: إما `default` أو `safeguard` (تلخيص مجزأ للسجلات الطويلة). راجع [الضغط](/ar/concepts/compaction). -- `timeoutSeconds`: الحد الأقصى للثواني المسموح بها لعملية ضغط واحدة قبل أن يقوم OpenClaw بإلغائها. الافتراضي: `900`. -- `identifierPolicy`: إما `strict` (الافتراضي) أو `off` أو `custom`. تقوم `strict` بإضافة إرشادات مضمّنة للاحتفاظ بالمعرّفات غير الشفافة أثناء تلخيص الضغط. -- `identifierInstructions`: نص اختياري مخصص للحفاظ على المعرّفات يُستخدم عندما `identifierPolicy=custom`. -- `postCompactionSections`: أسماء أقسام H2/H3 اختيارية من AGENTS.md لإعادة حقنها بعد الضغط. والقيمة الافتراضية هي `["Session Startup", "Red Lines"]`؛ اضبط `[]` للتعطيل. وعندما لا تكون معيّنة أو عندما تُضبط صراحة على هذا الزوج الافتراضي، تُقبل أيضًا العناوين القديمة `Every Session`/`Safety` كبديل قديم. -- `model`: تجاوز اختياري بصيغة `provider/model-id` للتلخيص الخاص بالضغط فقط. استخدمه عندما يجب أن تبقى الجلسة الرئيسية على نموذج معيّن بينما تعمل ملخصات الضغط على نموذج آخر؛ وعند حذفه، يستخدم الضغط النموذج الأساسي للجلسة. -- `notifyUser`: عندما تكون `true`، يرسل إشعارًا موجزًا إلى المستخدم عند بدء الضغط (على سبيل المثال، "Compacting context..."). وهو معطل افتراضيًا لإبقاء الضغط صامتًا. -- `memoryFlush`: دور وكيل صامت قبل الضغط التلقائي لتخزين الذكريات الدائمة. ويتم تخطيه عندما تكون مساحة العمل للقراءة فقط. +- `mode`: `default` أو `safeguard` (تلخيص مقسم لسجلات طويلة). راجع [الضغط](/ar/concepts/compaction). +- `provider`: معرّف إضافة plugin مسجلة لمزوّد compaction. عند تعيينه، يتم استدعاء `summarize()` الخاص بالمزوّد بدلًا من التلخيص المضمّن المعتمد على LLM. ويعود إلى المضمن عند الفشل. يؤدي تعيين مزوّد إلى فرض `mode: "safeguard"`. راجع [الضغط](/ar/concepts/compaction). +- `timeoutSeconds`: الحد الأقصى بالثواني المسموح به لعملية compaction واحدة قبل أن يوقفها OpenClaw. الافتراضي: `900`. +- `identifierPolicy`: `strict` (افتراضي) أو `off` أو `custom`. تضيف `strict` إرشادات مضمّنة للحفاظ على المعرفات المعتمة قبل تلخيص compaction. +- `identifierInstructions`: نص مخصص اختياري للحفاظ على المعرفات يُستخدم عندما يكون `identifierPolicy=custom`. +- `postCompactionSections`: أسماء أقسام H2/H3 اختيارية من AGENTS.md لإعادة حقنها بعد compaction. افتراضيًا `["Session Startup", "Red Lines"]`؛ اضبطها إلى `[]` لتعطيل إعادة الحقن. عندما تكون غير معيّنة أو معيّنة صراحةً إلى هذا الزوج الافتراضي، تُقبل أيضًا العناوين القديمة `Every Session`/`Safety` كحل احتياطي قديم. +- `model`: تجاوز اختياري `provider/model-id` لعمليات تلخيص compaction فقط. استخدمه عندما ينبغي أن تبقى الجلسة الرئيسية على نموذج معيّن لكن تعمل ملخصات compaction على نموذج آخر؛ وعند حذفه، يستخدم compaction النموذج الأساسي للجلسة. +- `notifyUser`: عندما تكون `true`، يرسل إشعارًا مختصرًا للمستخدم عند بدء compaction (مثل "Compacting context..."). يكون معطلًا افتراضيًا لإبقاء compaction صامتًا. +- `memoryFlush`: دور وكيل صامت قبل compaction التلقائي لتخزين الذكريات الدائمة. يتم تجاوزه عندما تكون مساحة العمل للقراءة فقط. ### `agents.defaults.contextPruning` -يقوم بتقليم **نتائج الأدوات القديمة** من السياق الموجود في الذاكرة قبل إرسالها إلى LLM. وهو **لا** يغيّر سجل الجلسة على القرص. +يقتطع **نتائج الأدوات القديمة** من السياق داخل الذاكرة قبل إرسالها إلى LLM. ولا يعدّل سجل الجلسة المخزّن على القرص. ```json5 { @@ -1205,7 +1200,7 @@ IRC مدعوم بإضافة ويُكوَّن ضمن `channels.irc`. defaults: { contextPruning: { mode: "cache-ttl", // off | cache-ttl - ttl: "1h", // مدة (ms/s/m/h)، الوحدة الافتراضية: دقائق + ttl: "1h", // duration (ms/s/m/h), default unit: minutes keepLastAssistants: 3, softTrimRatio: 0.3, hardClearRatio: 0.5, @@ -1221,25 +1216,25 @@ IRC مدعوم بإضافة ويُكوَّن ضمن `channels.irc`. -- يفعّل `mode: "cache-ttl"` تمريرات التقليم. -- يتحكم `ttl` في عدد المرات التي يمكن بعدها تشغيل التقليم مجددًا (بعد آخر لمسة على cache). -- يقوم التقليم أولًا باقتطاع نتائج الأدوات كبيرة الحجم اقتطاعًا ناعمًا، ثم يمسح نتائج الأدوات الأقدم مسحًا كاملًا إذا لزم الأمر. +- يفعّل `mode: "cache-ttl"` تمريرات الاقتطاع. +- يتحكم `ttl` في عدد المرات التي يمكن أن يعمل فيها الاقتطاع مجددًا (بعد آخر لمسة للذاكرة المؤقتة). +- يقوم الاقتطاع أولًا باقتطاعٍ ناعم لنتائج الأدوات كبيرة الحجم، ثم يزيل النتائج الأقدم إزالةً كاملة إذا لزم الأمر. **الاقتطاع الناعم** يحتفظ بالبداية + النهاية ويُدرج `...` في الوسط. -**المسح الكامل** يستبدل نتيجة الأداة بالكامل بالنص البديل. +**الإزالة الكاملة** تستبدل نتيجة الأداة بأكملها بالعنصر النائب. ملاحظات: -- لا يتم أبدًا اقتطاع/مسح كتل الصور. -- تستند النِّسب إلى الأحرف (تقريبية)، وليست إلى أعداد tokens الدقيقة. -- إذا كان عدد رسائل المساعد أقل من `keepLastAssistants`، يتم تخطي التقليم. +- لا يتم اقتطاع/إزالة كتل الصور أبدًا. +- النسب مبنية على الأحرف (تقريبية)، وليست على عدد الرموز بدقة. +- إذا وُجد عدد أقل من `keepLastAssistants` من رسائل المساعد، يتم تجاوز الاقتطاع. -راجع [تقليم الجلسة](/ar/concepts/session-pruning) لتفاصيل السلوك. +راجع [اقتطاع الجلسة](/ar/concepts/session-pruning) لتفاصيل السلوك. -### البث الكتلي +### البث على شكل كتل ```json5 { @@ -1249,17 +1244,17 @@ IRC مدعوم بإضافة ويُكوَّن ضمن `channels.irc`. blockStreamingBreak: "text_end", // text_end | message_end blockStreamingChunk: { minChars: 800, maxChars: 1200 }, blockStreamingCoalesce: { idleMs: 1000 }, - humanDelay: { mode: "natural" }, // off | natural | custom (استخدم minMs/maxMs) + humanDelay: { mode: "natural" }, // off | natural | custom (use minMs/maxMs) }, }, } ``` -- تتطلب القنوات غير Telegram تعيين `*.blockStreaming: true` صراحة لتفعيل الردود الكتلية. -- تجاوزات القنوات: `channels..blockStreamingCoalesce` (وتغايرات كل حساب). تستخدم Signal/Slack/Discord/Google Chat افتراضيًا `minChars: 1500`. -- `humanDelay`: توقف عشوائي بين الردود الكتلية. وتعني `natural` ‏800–2500ms. تجاوز لكل وكيل: `agents.list[].humanDelay`. +- تتطلب القنوات غير Telegram تفعيل `*.blockStreaming: true` صراحةً لتمكين الردود الكتلية. +- تجاوزات القنوات: `channels..blockStreamingCoalesce` (ومتغيراتها لكل حساب). تفترض Signal/Slack/Discord/Google Chat افتراضيًا `minChars: 1500`. +- `humanDelay`: توقف عشوائي بين الردود الكتلية. `natural` = 800–2500ms. تجاوز لكل وكيل: `agents.list[].humanDelay`. -راجع [البث](/ar/concepts/streaming) لمعرفة السلوك وتفاصيل التقسيم. +راجع [البث](/ar/concepts/streaming) للحصول على السلوك + تفاصيل تقسيم الكتل. ### مؤشرات الكتابة @@ -1274,8 +1269,8 @@ IRC مدعوم بإضافة ويُكوَّن ضمن `channels.irc`. } ``` -- القيم الافتراضية: `instant` للمحادثات المباشرة/الإشارات، و`message` للمحادثات الجماعية غير المشار فيها. -- تجاوزات لكل جلسة: `session.typingMode` و`session.typingIntervalSeconds`. +- القيم الافتراضية: `instant` للدردشات المباشرة/الإشارات، و`message` لمجموعات الدردشة غير المشار فيها. +- تجاوزات لكل جلسة: `session.typingMode`، `session.typingIntervalSeconds`. راجع [مؤشرات الكتابة](/ar/concepts/typing-indicators). @@ -1283,7 +1278,7 @@ IRC مدعوم بإضافة ويُكوَّن ضمن `channels.irc`. ### `agents.defaults.sandbox` -العزل الاختياري للوكيل المضمّن. راجع [العزل](/ar/gateway/sandboxing) للدليل الكامل. +الحماية الاختيارية داخل sandbox للوكيل المضمّن. راجع [الحماية داخل sandbox](/ar/gateway/sandboxing) للحصول على الدليل الكامل. ```json5 { @@ -1329,7 +1324,7 @@ IRC مدعوم بإضافة ويُكوَّن ضمن `channels.irc`. identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // SecretRefs / المحتويات المضمّنة مدعومة أيضًا: + // SecretRefs / inline contents also supported: // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, @@ -1380,52 +1375,52 @@ IRC مدعوم بإضافة ويُكوَّن ضمن `channels.irc`. -**الواجهة الخلفية:** +**الخلفية:** -- `docker`: بيئة Docker محلية (الافتراضية) -- `ssh`: بيئة بعيدة عامة مدعومة بـ SSH -- `openshell`: بيئة OpenShell +- `docker`: وقت تشغيل Docker محلي (افتراضي) +- `ssh`: وقت تشغيل بعيد عام معتمد على SSH +- `openshell`: وقت تشغيل OpenShell -عند تحديد `backend: "openshell"`، تنتقل الإعدادات الخاصة بالبيئة إلى +عند اختيار `backend: "openshell"`، تنتقل الإعدادات الخاصة بوقت التشغيل إلى `plugins.entries.openshell.config`. -**إعداد الواجهة الخلفية SSH:** +**إعدادات خلفية SSH:** - `target`: هدف SSH بصيغة `user@host[:port]` - `command`: أمر عميل SSH (الافتراضي: `ssh`) -- `workspaceRoot`: جذر بعيد مطلق يُستخدم لمساحات العمل بحسب النطاق -- `identityFile` / `certificateFile` / `knownHostsFile`: ملفات محلية موجودة تُمرَّر إلى OpenSSH +- `workspaceRoot`: الجذر البعيد المطلق المستخدم لمساحات العمل حسب النطاق +- `identityFile` / `certificateFile` / `knownHostsFile`: ملفات محلية موجودة يتم تمريرها إلى OpenSSH - `identityData` / `certificateData` / `knownHostsData`: محتويات مضمّنة أو SecretRefs يقوم OpenClaw بتحويلها إلى ملفات مؤقتة وقت التشغيل -- `strictHostKeyChecking` / `updateHostKeys`: مفاتيح سياسة مفتاح المضيف في OpenSSH +- `strictHostKeyChecking` / `updateHostKeys`: مفاتيح سياسة مفاتيح المضيف في OpenSSH -**أسبقية مصادقة SSH:** +**أولوية مصادقة SSH:** -- تتفوق `identityData` على `identityFile` -- تتفوق `certificateData` على `certificateFile` -- تتفوق `knownHostsData` على `knownHostsFile` -- يتم حل قيم `*Data` المدعومة بـ SecretRef من لقطة secrets النشطة وقت التشغيل قبل بدء جلسة sandbox +- `identityData` يتغلب على `identityFile` +- `certificateData` يتغلب على `certificateFile` +- `knownHostsData` يتغلب على `knownHostsFile` +- يتم حل قيم `*Data` المدعومة بـ SecretRef من اللقطة النشطة لوقت تشغيل الأسرار قبل بدء جلسة sandbox -**سلوك الواجهة الخلفية SSH:** +**سلوك خلفية SSH:** - يزرع مساحة العمل البعيدة مرة واحدة بعد الإنشاء أو إعادة الإنشاء -- ثم يُبقي مساحة العمل البعيدة عبر SSH هي المرجع -- يوجّه `exec` وأدوات الملفات ومسارات الوسائط عبر SSH -- لا يزامن التغييرات البعيدة مرة أخرى إلى المضيف تلقائيًا -- لا يدعم حاويات متصفح sandbox +- ثم يُبقي مساحة عمل SSH البعيدة هي المرجع الأساسي +- يمرّر `exec` وأدوات الملفات ومسارات الوسائط عبر SSH +- لا يزامن التغييرات البعيدة تلقائيًا إلى المضيف +- لا يدعم حاويات المتصفح داخل sandbox -**الوصول إلى مساحة العمل:** +**وصول مساحة العمل:** -- `none`: مساحة عمل sandbox لكل نطاق ضمن `~/.openclaw/sandboxes` -- `ro`: مساحة عمل sandbox عند `/workspace`، ومساحة عمل الوكيل مركّبة للقراءة فقط عند `/agent` -- `rw`: مساحة عمل الوكيل مركّبة للقراءة/الكتابة عند `/workspace` +- `none`: مساحة عمل sandbox لكل نطاق تحت `~/.openclaw/sandboxes` +- `ro`: مساحة عمل sandbox عند `/workspace`، مع تركيب مساحة عمل الوكيل للقراءة فقط عند `/agent` +- `rw`: تركيب مساحة عمل الوكيل قراءة/كتابة عند `/workspace` **النطاق:** - `session`: حاوية + مساحة عمل لكل جلسة -- `agent`: حاوية + مساحة عمل واحدة لكل وكيل (الافتراضي) +- `agent`: حاوية + مساحة عمل واحدة لكل وكيل (افتراضي) - `shared`: حاوية ومساحة عمل مشتركتان (من دون عزل بين الجلسات) -**إعداد إضافة OpenShell:** +**إعدادات إضافة OpenShell:** ```json5 { @@ -1438,10 +1433,10 @@ IRC مدعوم بإضافة ويُكوَّن ضمن `channels.irc`. from: "openclaw", remoteWorkspaceDir: "/sandbox", remoteAgentWorkspaceDir: "/agent", - gateway: "lab", // اختياري - gatewayEndpoint: "https://lab.example", // اختياري - policy: "strict", // معرّف سياسة OpenShell اختياري - providers: ["openai"], // اختياري + gateway: "lab", // optional + gatewayEndpoint: "https://lab.example", // optional + policy: "strict", // optional OpenShell policy id + providers: ["openai"], // optional autoProviders: true, timeoutSeconds: 120, }, @@ -1453,30 +1448,30 @@ IRC مدعوم بإضافة ويُكوَّن ضمن `channels.irc`. **وضع OpenShell:** -- `mirror`: زرع البعيد من المحلي قبل exec، ثم المزامنة بعد exec؛ وتبقى مساحة العمل المحلية هي المرجع -- `remote`: زرع البعيد مرة واحدة عند إنشاء sandbox، ثم تصبح مساحة العمل البعيدة هي المرجع +- `mirror`: زرع البعيد من المحلي قبل exec، ثم المزامنة العكسية بعد exec؛ تبقى مساحة العمل المحلية هي المرجع الأساسي +- `remote`: زرع البعيد مرة واحدة عند إنشاء sandbox، ثم إبقاء مساحة العمل البعيدة هي المرجع الأساسي -في وضع `remote`، لا تتم مزامنة التعديلات المحلية على المضيف التي تُجرى خارج OpenClaw إلى sandbox تلقائيًا بعد خطوة الزرع. -تتم عملية النقل عبر SSH إلى sandbox الخاص بـ OpenShell، لكن الإضافة تمتلك دورة حياة sandbox ومزامنة mirror الاختيارية. +في وضع `remote`، لا تتم مزامنة التعديلات المحلية على المضيف التي تتم خارج OpenClaw إلى sandbox تلقائيًا بعد خطوة الزرع. +يتم النقل عبر SSH إلى sandbox الخاص بـ OpenShell، لكن الإضافة تملك دورة حياة sandbox والمزامنة المرآتية الاختيارية. -**`setupCommand`** يعمل مرة واحدة بعد إنشاء الحاوية (عبر `sh -lc`). ويتطلب وصول شبكة صادرة وجذرًا قابلًا للكتابة ومستخدم root. +**`setupCommand`** يعمل مرة واحدة بعد إنشاء الحاوية (عبر `sh -lc`). ويتطلب خروجًا للشبكة، وجذرًا قابلاً للكتابة، ومستخدم root. -**تستخدم الحاويات افتراضيًا `network: "none"`** — اضبطها على `"bridge"` (أو شبكة bridge مخصصة) إذا كان الوكيل يحتاج إلى وصول صادر. -يتم حظر `"host"`. ويتم حظر `"container:"` افتراضيًا ما لم تضبط صراحة -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (كسر الزجاج). +**تكون الحاويات افتراضيًا على `network: "none"`** — اضبطها على `"bridge"` (أو شبكة bridge مخصصة) إذا كان الوكيل يحتاج إلى وصول صادر. +يتم حظر `"host"`. ويتم حظر `"container:"` افتراضيًا ما لم تعيّن صراحة +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (كسر زجاج). -**المرفقات الواردة** تُوضَع مرحليًا في `media/inbound/*` داخل مساحة العمل النشطة. +**المرفقات الواردة** يتم تجهيزها داخل `media/inbound/*` في مساحة العمل النشطة. -**`docker.binds`** يركّب أدلة مضيف إضافية؛ ويتم دمج التركيبات العامة وتلك الخاصة بكل وكيل. +**`docker.binds`** يركّب أدلة مضيف إضافية؛ ويتم دمج التركيبات العامة والتركيبات لكل وكيل. -**المتصفح المعزول** (`sandbox.browser.enabled`): Chromium + CDP داخل حاوية. ويتم حقن عنوان noVNC في system prompt. ولا يتطلب `browser.enabled` في `openclaw.json`. -يستخدم الوصول للمراقبة عبر noVNC مصادقة VNC افتراضيًا، ويصدر OpenClaw عنوان URL مميزًا قصير العمر (بدلًا من كشف كلمة المرور في الرابط المشترك). +**المتصفح داخل sandbox** (`sandbox.browser.enabled`): Chromium + CDP في حاوية. يتم حقن عنوان noVNC في system prompt. ولا يتطلب `browser.enabled` في `openclaw.json`. +يستخدم وصول المراقب إلى noVNC مصادقة VNC افتراضيًا ويصدر OpenClaw رابط token قصير العمر (بدلاً من كشف كلمة المرور في الرابط المشترك). -- `allowHostControl: false` (الافتراضي) يمنع الجلسات المعزولة من استهداف متصفح المضيف. -- تكون القيمة الافتراضية لـ `network` هي `openclaw-sandbox-browser` (شبكة bridge مخصصة). واضبطها على `bridge` فقط عندما تريد صراحة اتصال bridge عامًا. -- تقوم `cdpSourceRange` اختياريًا بتقييد دخول CDP على حافة الحاوية إلى مدى CIDR (على سبيل المثال `172.21.0.1/32`). -- تقوم `sandbox.browser.binds` بتركيب أدلة مضيف إضافية داخل حاوية متصفح sandbox فقط. وعند تعيينها (بما في ذلك `[]`)، فإنها تستبدل `docker.binds` بالنسبة إلى حاوية المتصفح. -- يتم تعريف القيم الافتراضية للتشغيل في `scripts/sandbox-browser-entrypoint.sh` ومواءمتها لمضيفي الحاويات: +- `allowHostControl: false` (افتراضي) يمنع الجلسات الموجودة داخل sandbox من استهداف متصفح المضيف. +- تكون `network` افتراضيًا `openclaw-sandbox-browser` (شبكة bridge مخصصة). اضبطها على `bridge` فقط عندما تريد صراحةً اتصال bridge عالمي. +- يقيّد `cdpSourceRange` اختياريًا دخول CDP على حافة الحاوية إلى نطاق CIDR (مثل `172.21.0.1/32`). +- يركّب `sandbox.browser.binds` أدلة مضيف إضافية داخل حاوية متصفح sandbox فقط. عند تعيينه (بما في ذلك `[]`)، فإنه يستبدل `docker.binds` لحاوية المتصفح. +- تُعرّف الإعدادات الافتراضية للتشغيل في `scripts/sandbox-browser-entrypoint.sh` وتم ضبطها لمضيفي الحاويات: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1493,28 +1488,27 @@ IRC مدعوم بإضافة ويُكوَّن ضمن `channels.irc`. - `--renderer-process-limit=2` - `--no-zygote` - `--metrics-recording-only` - - `--disable-extensions` (مفعّلة افتراضيًا) + - `--disable-extensions` (مفعّل افتراضيًا) - تكون `--disable-3d-apis` و`--disable-software-rasterizer` و`--disable-gpu` مفعّلة افتراضيًا ويمكن تعطيلها عبر `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` إذا كان استخدام WebGL/3D يتطلب ذلك. - - يعيد `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` تمكين الإضافات إذا كان سير عملك - يعتمد عليها. + - يعيد `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` تفعيل الإضافات إذا كان سير عملك يعتمد عليها. - يمكن تغيير `--renderer-process-limit=2` عبر `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`؛ واضبطه إلى `0` لاستخدام - الحد الافتراضي لعمليات Chromium. - - بالإضافة إلى `--no-sandbox` و`--disable-setuid-sandbox` عندما تكون `noSandbox` مفعّلة. - - تعد القيم الافتراضية خط الأساس لصورة الحاوية؛ استخدم صورة متصفح مخصصة مع - entrypoint مخصص لتغيير القيم الافتراضية للحاوية. + حد العمليات الافتراضي لـ Chromium. + - بالإضافة إلى `--no-sandbox` و`--disable-setuid-sandbox` عندما يكون `noSandbox` مفعلاً. + - هذه الإعدادات الافتراضية هي خط الأساس لصورة الحاوية؛ استخدم صورة متصفح مخصصة مع نقطة + دخول مخصصة لتغيير افتراضيات الحاوية. -يقتصر Browser sandboxing و`sandbox.docker.binds` حاليًا على Docker فقط. +حماية المتصفح داخل sandbox و`sandbox.docker.binds` مدعومتان حاليًا فقط مع Docker. أنشئ الصور: ```bash -scripts/sandbox-setup.sh # صورة sandbox الرئيسية -scripts/sandbox-browser-setup.sh # صورة المتصفح الاختيارية +scripts/sandbox-setup.sh # main sandbox image +scripts/sandbox-browser-setup.sh # optional browser image ``` ### `agents.list` (تجاوزات لكل وكيل) @@ -1529,12 +1523,12 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري name: "Main Agent", workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", - model: "anthropic/claude-opus-4-6", // أو { primary, fallbacks } - thinkingDefault: "high", // تجاوز مستوى التفكير الافتراضي لكل وكيل - reasoningDefault: "on", // تجاوز رؤية الاستدلال الافتراضية لكل وكيل - fastModeDefault: false, // تجاوز الوضع السريع الافتراضي لكل وكيل - params: { cacheRetention: "none" }, // تتجاوز defaults.models.params المطابقة حسب المفتاح - skills: ["docs-search"], // تستبدل agents.defaults.skills عندما تُضبط + model: "anthropic/claude-opus-4-6", // or { primary, fallbacks } + thinkingDefault: "high", // per-agent thinking level override + reasoningDefault: "on", // per-agent reasoning visibility override + fastModeDefault: false, // per-agent fast mode override + params: { cacheRetention: "none" }, // overrides matching defaults.models params by key + skills: ["docs-search"], // replaces agents.defaults.skills when set identity: { name: "Samantha", theme: "helpful sloth", @@ -1566,25 +1560,25 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري ``` - `id`: معرّف وكيل ثابت (مطلوب). -- `default`: عند ضبط أكثر من واحد، يفوز الأول (مع تسجيل تحذير). وإذا لم يُضبط أيٌّ منها، يكون أول إدخال في القائمة هو الافتراضي. -- `model`: الشكل النصي يتجاوز `primary` فقط؛ ويقوم شكل الكائن `{ primary, fallbacks }` بتجاوز الاثنين معًا (`[]` يعطّل fallbacks العامة). تظل مهام Cron التي تتجاوز `primary` فقط ترث fallbacks الافتراضية ما لم تضبط `fallbacks: []`. -- `params`: معاملات stream لكل وكيل تُدمج فوق إدخال النموذج المحدد في `agents.defaults.models`. استخدم هذا للتجاوزات الخاصة بالوكيل مثل `cacheRetention` أو `temperature` أو `maxTokens` من دون تكرار كتالوج النماذج بأكمله. -- `skills`: قائمة سماح اختيارية لـ Skills لكل وكيل. وإذا حُذفت، يرث الوكيل `agents.defaults.skills` عندما تكون معيّنة؛ وتستبدل القائمة الصريحة القيم الافتراضية بدلًا من دمجها، و`[]` تعني عدم استخدام أي Skills. -- `thinkingDefault`: مستوى التفكير الافتراضي الاختياري لكل وكيل (`off | minimal | low | medium | high | xhigh | adaptive`). ويتجاوز `agents.defaults.thinkingDefault` لهذا الوكيل عندما لا يكون هناك تجاوز لكل رسالة أو جلسة. -- `reasoningDefault`: تجاوز اختياري لكل وكيل لرؤية الاستدلال (`on | off | stream`). ويُطبّق عندما لا يكون هناك تجاوز للاستدلال لكل رسالة أو جلسة. -- `fastModeDefault`: تجاوز اختياري لكل وكيل للوضع السريع (`true | false`). ويُطبّق عندما لا يكون هناك تجاوز للوضع السريع لكل رسالة أو جلسة. -- `runtime`: واصف runtime اختياري لكل وكيل. استخدم `type: "acp"` مع الإعدادات الافتراضية لـ `runtime.acp` ‏(`agent` و`backend` و`mode` و`cwd`) عندما يجب أن يستخدم الوكيل جلسات ACP harness افتراضيًا. -- `identity.avatar`: مسار نسبي لمساحة العمل، أو عنوان URL ‏`http(s)`، أو `data:` URI. -- تستمد `identity` القيم الافتراضية: `ackReaction` من `emoji`، و`mentionPatterns` من `name`/`emoji`. -- `subagents.allowAgents`: قائمة سماح لمعرّفات الوكلاء لأداة `sessions_spawn` (`["*"]` = أي وكيل؛ الافتراضي: نفس الوكيل فقط). -- حاجز وراثة sandbox: إذا كانت جلسة الطالب داخل sandbox، ترفض `sessions_spawn` الأهداف التي ستعمل من دون sandbox. -- `subagents.requireAgentId`: عندما تكون true، تمنع استدعاءات `sessions_spawn` التي تحذف `agentId` (تفرض اختيار ملف تعريف صريح؛ الافتراضي: false). +- `default`: عند تعيين عدة وكلاء، يفوز الأول (مع تسجيل تحذير). وإذا لم يُعيَّن أي منها، يكون أول إدخال في القائمة هو الافتراضي. +- `model`: صيغة السلسلة تتجاوز `primary` فقط؛ وصيغة الكائن `{ primary, fallbacks }` تتجاوز كليهما (`[]` تعطل fallback العام). تبقى مهام cron التي تتجاوز `primary` فقط ترث fallback الافتراضي ما لم تعيّن `fallbacks: []`. +- `params`: معلمات بث لكل وكيل تُدمج فوق إدخال النموذج المحدد في `agents.defaults.models`. استخدمها لتجاوزات خاصة بالوكيل مثل `cacheRetention` أو `temperature` أو `maxTokens` دون تكرار فهرس النماذج بالكامل. +- `skills`: قائمة سماح اختيارية لـ Skills لكل وكيل. إذا حُذفت، يرث الوكيل `agents.defaults.skills` عند تعيينها؛ وتستبدل القائمة الصريحة القيم الافتراضية بدلًا من دمجها، وتعني `[]` عدم وجود Skills. +- `thinkingDefault`: مستوى التفكير الافتراضي الاختياري لكل وكيل (`off | minimal | low | medium | high | xhigh | adaptive`). يتجاوز `agents.defaults.thinkingDefault` لهذا الوكيل عندما لا يكون هناك تجاوز لكل رسالة أو جلسة. +- `reasoningDefault`: تجاوز اختياري لرؤية الاستدلال الافتراضية لكل وكيل (`on | off | stream`). يُطبّق عندما لا يكون هناك تجاوز للاستدلال لكل رسالة أو جلسة. +- `fastModeDefault`: افتراضي اختياري لكل وكيل لوضع fast (`true | false`). يُطبّق عندما لا يكون هناك تجاوز لوضع fast لكل رسالة أو جلسة. +- `runtime`: واصف وقت تشغيل اختياري لكل وكيل. استخدم `type: "acp"` مع الإعدادات الافتراضية في `runtime.acp` (`agent`، `backend`، `mode`، `cwd`) عندما ينبغي أن يستخدم الوكيل افتراضيًا جلسات ACP harness. +- `identity.avatar`: مسار نسبي لمساحة العمل، أو URL من نوع `http(s)`، أو `data:` URI. +- يستنتج `identity` القيم الافتراضية: `ackReaction` من `emoji`، و`mentionPatterns` من `name`/`emoji`. +- `subagents.allowAgents`: قائمة سماح لمعرّفات الوكلاء في `sessions_spawn` (`["*"]` = أي وكيل؛ الافتراضي: نفس الوكيل فقط). +- حارس وراثة sandbox: إذا كانت جلسة الطالب داخل sandbox، يرفض `sessions_spawn` الأهداف التي ستعمل خارج sandbox. +- `subagents.requireAgentId`: عندما تكون true، يحظر استدعاءات `sessions_spawn` التي تحذف `agentId` (يفرض اختيار ملف تعريف صريح؛ الافتراضي: false). --- ## التوجيه متعدد الوكلاء -شغّل عدة وكلاء معزولين داخل بوابة واحدة. راجع [تعدد الوكلاء](/ar/concepts/multi-agent). +شغّل عدة وكلاء معزولين داخل بوابة واحدة. راجع [Multi-Agent](/ar/concepts/multi-agent). ```json5 { @@ -1601,29 +1595,29 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري } ``` -### حقول مطابقة الارتباط +### حقول مطابقة الربط -- `type` (اختياري): `route` للتوجيه العادي (وغيابه يعني route افتراضيًا)، و`acp` لارتباطات محادثات ACP الدائمة. +- `type` (اختياري): `route` للتوجيه العادي (والنوع المفقود يفترض route)، و`acp` لروابط محادثة ACP الدائمة. - `match.channel` (مطلوب) -- `match.accountId` (اختياري؛ `*` = أي حساب؛ وحذفه = الحساب الافتراضي) +- `match.accountId` (اختياري؛ `*` = أي حساب؛ المحذوف = الحساب الافتراضي) - `match.peer` (اختياري؛ `{ kind: direct|group|channel, id }`) -- `match.guildId` / `match.teamId` (اختياري؛ بحسب القناة) -- `acp` (اختياري؛ فقط للإدخالات ذات `type: "acp"`): ‏`{ mode, label, cwd, backend }` +- `match.guildId` / `match.teamId` (اختياري؛ خاصة بقناة معينة) +- `acp` (اختياري؛ فقط لـ `type: "acp"`): `{ mode, label, cwd, backend }` **ترتيب المطابقة الحتمي:** 1. `match.peer` 2. `match.guildId` 3. `match.teamId` -4. `match.accountId` (مطابقة تامة، من دون peer/guild/team) +4. `match.accountId` (مطابقة تامة، بلا peer/guild/team) 5. `match.accountId: "*"` (على مستوى القناة) 6. الوكيل الافتراضي -داخل كل طبقة، يفوز أول إدخال مطابق في `bindings`. +ضمن كل مستوى، يفوز أول إدخال مطابق في `bindings`. -بالنسبة إلى إدخالات `type: "acp"`، يقوم OpenClaw بالحل باستخدام هوية المحادثة الدقيقة (`match.channel` + الحساب + `match.peer.id`) ولا يستخدم ترتيب طبقات route binding المذكور أعلاه. +بالنسبة لإدخالات `type: "acp"`، يحل OpenClaw حسب هوية المحادثة الدقيقة (`match.channel` + الحساب + `match.peer.id`) ولا يستخدم ترتيب مستويات route أعلاه. -### ملفات تعريف الوصول لكل وكيل +### ملفات الوصول لكل وكيل @@ -1718,7 +1712,7 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري -راجع [Sandbox والأدوات متعددة الوكلاء](/ar/tools/multi-agent-sandbox-tools) لمعرفة تفاصيل الأسبقية. +راجع [Multi-Agent Sandbox & Tools](/ar/tools/multi-agent-sandbox-tools) للحصول على تفاصيل الأولوية. --- @@ -1744,22 +1738,22 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // تخطّي fork من الخيط الأصل فوق هذا العدد من tokens (0 للتعطيل) + parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, rotateBytes: "10mb", - resetArchiveRetention: "30d", // مدة أو false - maxDiskBytes: "500mb", // اختياري، ميزانية صارمة - highWaterBytes: "400mb", // اختياري، هدف التنظيف + resetArchiveRetention: "30d", // duration or false + maxDiskBytes: "500mb", // optional hard budget + highWaterBytes: "400mb", // optional cleanup target }, threadBindings: { enabled: true, - idleHours: 24, // الإلغاء التلقائي للتركيز بعد الخمول افتراضيًا بالساعات (`0` للتعطيل) - maxAgeHours: 0, // الحد الأقصى الصارم للعمر افتراضيًا بالساعات (`0` للتعطيل) + idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables) + maxAgeHours: 0, // default hard max age in hours (`0` disables) }, - mainKey: "main", // قديم (وقت التشغيل يستخدم دائمًا "main") + mainKey: "main", // legacy (runtime always uses "main") agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -1772,34 +1766,34 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري - **`scope`**: استراتيجية تجميع الجلسات الأساسية لسياقات الدردشة الجماعية. - - `per-sender` (الافتراضي): يحصل كل مرسل على جلسة معزولة داخل سياق القناة. - - `global`: يشترك جميع المشاركين في سياق القناة في جلسة واحدة (يُستخدم فقط عندما يكون المقصود سياقًا مشتركًا). + - `per-sender` (افتراضي): يحصل كل مرسل على جلسة معزولة داخل سياق القناة. + - `global`: يشارك جميع المشاركين في سياق القناة جلسة واحدة (استخدمه فقط عندما يكون السياق المشترك مقصودًا). - **`dmScope`**: كيفية تجميع الرسائل الخاصة. - `main`: تشترك جميع الرسائل الخاصة في الجلسة الرئيسية. - - `per-peer`: عزل حسب معرّف المرسل عبر القنوات. - - `per-channel-peer`: عزل لكل قناة + مرسل (موصى به لصناديق الوارد متعددة المستخدمين). - - `per-account-channel-peer`: عزل لكل حساب + قناة + مرسل (موصى به للتعدد الحسابي). -- **`identityLinks`**: تربط المعرّفات القياسية بنظراء ذوي بادئة مزوّد لمشاركة الجلسات عبر القنوات. -- **`reset`**: سياسة إعادة التعيين الأساسية. تقوم `daily` بإعادة التعيين عند `atHour` حسب التوقيت المحلي؛ وتقوم `idle` بإعادة التعيين بعد `idleMinutes`. وعند تهيئة الاثنين، يفوز أول ما تنتهي صلاحيته. -- **`resetByType`**: تجاوزات حسب النوع (`direct` و`group` و`thread`). وتُقبل `dm` القديمة كاسم بديل لـ `direct`. -- **`parentForkMaxTokens`**: الحد الأقصى لـ `totalTokens` في الجلسة الأصلية المسموح به عند إنشاء جلسة خيط forked (الافتراضي `100000`). - - إذا كانت قيمة `totalTokens` في الأصل أعلى من هذا، يبدأ OpenClaw جلسة خيط جديدة بدلًا من وراثة سجل transcript الخاص بالأصل. - - اضبط `0` لتعطيل هذا الحاجز والسماح دائمًا بعمل fork من الأصل. -- **`mainKey`**: حقل قديم. ويستخدم وقت التشغيل الآن دائمًا `"main"` لدلو الدردشة المباشرة الرئيسي. -- **`agentToAgent.maxPingPongTurns`**: العدد الأقصى لأدوار الرد المتبادل بين الوكلاء أثناء تبادلات وكيل إلى وكيل (عدد صحيح، المجال: `0`–`5`). وتعطّل `0` تسلسل ping-pong. -- **`sendPolicy`**: المطابقة حسب `channel` أو `chatType` (`direct|group|channel`، مع الاسم القديم `dm`) أو `keyPrefix` أو `rawKeyPrefix`. ويفوز أول deny. -- **`maintenance`**: عناصر التحكم في تنظيف مخزن الجلسة والاحتفاظ بها. - - `mode`: تقوم `warn` بإصدار تحذيرات فقط؛ وتقوم `enforce` بتطبيق التنظيف. - - `pruneAfter`: حد عمر الإدخالات القديمة (الافتراضي `30d`). - - `maxEntries`: العدد الأقصى للإدخالات في `sessions.json` (الافتراضي `500`). + - `per-peer`: يعزل حسب معرّف المرسل عبر القنوات. + - `per-channel-peer`: يعزل لكل قناة + مرسل (موصى به لصناديق الوارد متعددة المستخدمين). + - `per-account-channel-peer`: يعزل لكل حساب + قناة + مرسل (موصى به لتعدد الحسابات). +- **`identityLinks`**: يربط المعرّفات القياسية بالنظراء مسبوقي المزوّد لمشاركة الجلسات عبر القنوات. +- **`reset`**: سياسة إعادة التعيين الأساسية. يعيد `daily` التعيين عند `atHour` بالتوقيت المحلي؛ ويعيد `idle` التعيين بعد `idleMinutes`. عند ضبط الاثنين، يفوز أول ما تنتهي صلاحيته. +- **`resetByType`**: تجاوزات حسب النوع (`direct` و`group` و`thread`). ويُقبل `dm` القديم كاسم مستعار لـ `direct`. +- **`parentForkMaxTokens`**: الحد الأقصى لـ `totalTokens` في الجلسة الأصلية المسموح به عند إنشاء جلسة خيط متفرعة (الافتراضي `100000`). + - إذا كانت قيمة `totalTokens` في الجلسة الأصلية أعلى من هذه القيمة، يبدأ OpenClaw جلسة خيط جديدة بدلًا من وراثة سجل الجلسة الأصلية. + - اضبطه إلى `0` لتعطيل هذا الحارس والسماح دائمًا بالتفرع من الأصل. +- **`mainKey`**: حقل قديم. يستخدم وقت التشغيل الآن دائمًا `"main"` لحاوية الدردشة المباشرة الرئيسية. +- **`agentToAgent.maxPingPongTurns`**: الحد الأقصى لأدوار الرد المتبادل بين الوكلاء أثناء تبادلات وكيل-إلى-وكيل (عدد صحيح، النطاق: `0`–`5`). تؤدي `0` إلى تعطيل سلسلة ping-pong. +- **`sendPolicy`**: المطابقة حسب `channel` أو `chatType` (`direct|group|channel`، مع الاسم المستعار القديم `dm`) أو `keyPrefix` أو `rawKeyPrefix`. يفوز أول منع. +- **`maintenance`**: تحكمات تنظيف مخزن الجلسات + الاحتفاظ. + - `mode`: `warn` يصدر تحذيرات فقط؛ و`enforce` يطبق التنظيف. + - `pruneAfter`: حد عمر لإزالة الإدخالات القديمة (الافتراضي `30d`). + - `maxEntries`: الحد الأقصى لعدد الإدخالات في `sessions.json` (الافتراضي `500`). - `rotateBytes`: تدوير `sessions.json` عندما يتجاوز هذا الحجم (الافتراضي `10mb`). - - `resetArchiveRetention`: مدة الاحتفاظ بأرشيفات transcript من نوع `*.reset.`. وتكون افتراضيًا مساوية لـ `pruneAfter`؛ اضبط `false` للتعطيل. - - `maxDiskBytes`: ميزانية قرص اختيارية لدليل الجلسات. في وضع `warn` تقوم بتسجيل التحذيرات؛ وفي وضع `enforce` تزيل أقدم العناصر/الجلسات أولًا. - - `highWaterBytes`: الهدف الاختياري بعد تنظيف الميزانية. والقيمة الافتراضية هي `80%` من `maxDiskBytes`. + - `resetArchiveRetention`: مدة الاحتفاظ بأرشيفات transcript من نوع `*.reset.`. افتراضيًا تساوي `pruneAfter`؛ واضبطها إلى `false` لتعطيلها. + - `maxDiskBytes`: ميزانية قرص اختيارية لدليل الجلسات. في وضع `warn` تسجل تحذيرات؛ وفي وضع `enforce` تزيل أقدم العناصر/الجلسات أولًا. + - `highWaterBytes`: الهدف الاختياري بعد تنظيف الميزانية. افتراضيًا `80%` من `maxDiskBytes`. - **`threadBindings`**: القيم الافتراضية العامة لميزات الجلسات المرتبطة بالخيوط. - - `enabled`: مفتاح افتراضي رئيسي (يمكن للمزوّدين تجاوزه؛ يستخدم Discord القيمة `channels.discord.threadBindings.enabled`) - - `idleHours`: القيمة الافتراضية لإلغاء التركيز التلقائي بعد الخمول بالساعات (`0` للتعطيل؛ ويمكن للمزوّدين التجاوز) - - `maxAgeHours`: القيمة الافتراضية للحد الأقصى الصارم للعمر بالساعات (`0` للتعطيل؛ ويمكن للمزوّدين التجاوز) + - `enabled`: مفتاح افتراضي رئيسي (يمكن للمزوّدين تجاوزه؛ ويستخدم Discord `channels.discord.threadBindings.enabled`) + - `idleHours`: الافتراضي العام لإلغاء التركيز التلقائي بعد عدم النشاط بالساعات (`0` للتعطيل؛ ويمكن للمزوّدين تجاوزه) + - `maxAgeHours`: الافتراضي العام للعمر الأقصى الصارم بالساعات (`0` للتعطيل؛ ويمكن للمزوّدين تجاوزه) @@ -1810,7 +1804,7 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري ```json5 { messages: { - responsePrefix: "🦞", // أو "auto" + responsePrefix: "🦞", // or "auto" ackReaction: "👀", ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all removeAckAfterReply: false, @@ -1825,7 +1819,7 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري }, }, inbound: { - debounceMs: 2000, // 0 للتعطيل + debounceMs: 2000, // 0 disables byChannel: { whatsapp: 5000, slack: 1500, @@ -1837,36 +1831,36 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري ### بادئة الرد -تجاوزات لكل قناة/حساب: `channels..responsePrefix` و`channels..accounts..responsePrefix`. +تجاوزات لكل قناة/حساب: `channels..responsePrefix`، و`channels..accounts..responsePrefix`. -آلية الحل (الأكثر تحديدًا يفوز): الحساب → القناة → العام. تؤدي `""` إلى التعطيل وإيقاف التدرج. ويشتق `"auto"` القيمة `[{identity.name}]`. +آلية الحل (الأكثر تحديدًا يفوز): الحساب → القناة → العام. يؤدي `""` إلى التعطيل وإيقاف التسلسل. ويستنتج `"auto"` القيمة `[{identity.name}]`. **متغيرات القالب:** -| المتغير | الوصف | المثال | -| ----------------- | --------------------- | -------------------------- | -| `{model}` | اسم النموذج المختصر | `claude-opus-4-6` | +| المتغير | الوصف | المثال | +| ----------------- | --------------------- | --------------------------- | +| `{model}` | اسم النموذج المختصر | `claude-opus-4-6` | | `{modelFull}` | معرّف النموذج الكامل | `anthropic/claude-opus-4-6` | -| `{provider}` | اسم المزوّد | `anthropic` | -| `{thinkingLevel}` | مستوى التفكير الحالي | `high`, `low`, `off` | -| `{identity.name}` | اسم هوية الوكيل | (نفس `"auto"`) | +| `{provider}` | اسم المزوّد | `anthropic` | +| `{thinkingLevel}` | مستوى التفكير الحالي | `high`، `low`، `off` | +| `{identity.name}` | اسم هوية الوكيل | (مثل `"auto"`) | -المتغيرات غير حساسة لحالة الأحرف. ويعد `{think}` اسمًا بديلًا لـ `{thinkingLevel}`. +المتغيرات غير حساسة لحالة الأحرف. ويُعد `{think}` اسمًا مستعارًا لـ `{thinkingLevel}`. ### تفاعل الإقرار -- يكون افتراضيًا هو `identity.emoji` الخاص بالوكيل النشط، وإلا `"👀"`. اضبط `""` للتعطيل. -- تجاوزات لكل قناة: `channels..ackReaction` و`channels..accounts..ackReaction`. -- ترتيب الحل: الحساب → القناة → `messages.ackReaction` → بديل الهوية. -- النطاق: `group-mentions` (الافتراضي) و`group-all` و`direct` و`all`. -- تقوم `removeAckAfterReply` بإزالة الإقرار بعد الرد على Slack وDiscord وTelegram. -- تقوم `messages.statusReactions.enabled` بتمكين تفاعلات حالة دورة الحياة على Slack وDiscord وTelegram. - وفي Slack وDiscord، يؤدي عدم تعيينها إلى إبقاء تفاعلات الحالة مفعّلة عندما تكون تفاعلات الإقرار نشطة. - وفي Telegram، اضبطها صراحة على `true` لتمكين تفاعلات حالة دورة الحياة. +- يكون افتراضيًا `identity.emoji` للوكيل النشط، وإلا `"👀"`. اضبطه إلى `""` للتعطيل. +- تجاوزات لكل قناة: `channels..ackReaction`، و`channels..accounts..ackReaction`. +- ترتيب الحل: الحساب → القناة → `messages.ackReaction` → هوية احتياطية. +- النطاق: `group-mentions` (افتراضي)، أو `group-all`، أو `direct`، أو `all`. +- يزيل `removeAckAfterReply` تفاعل الإقرار بعد الرد في Slack وDiscord وTelegram. +- يفعّل `messages.statusReactions.enabled` تفاعلات الحالة عبر دورة الحياة في Slack وDiscord وTelegram. + في Slack وDiscord، يؤدي تركه غير معيّن إلى بقاء تفاعلات الحالة مفعلة عندما تكون تفاعلات الإقرار نشطة. + وفي Telegram، اضبطه صراحةً إلى `true` لتمكين تفاعلات الحالة عبر دورة الحياة. -### إلغاء الارتداد للوارد +### إزالة الارتداد للرسائل الواردة -يجمع الرسائل النصية السريعة المتتالية من المرسل نفسه في دور وكيل واحد. وتؤدي الوسائط/المرفقات إلى التفريغ الفوري. وتتجاوز أوامر التحكم آلية إلغاء الارتداد. +يجمع الرسائل النصية السريعة المتتابعة من المرسل نفسه في دور وكيل واحد. تؤدي الوسائط/المرفقات إلى التفريغ فورًا. تتجاوز أوامر التحكم إزالة الارتداد. ### TTS (تحويل النص إلى كلام) @@ -1909,18 +1903,18 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري } ``` -- يتحكم `auto` في TTS التلقائي. ويقوم `/tts off|always|inbound|tagged` بالتجاوز لكل جلسة. -- يتجاوز `summaryModel` قيمة `agents.defaults.model.primary` للملخص التلقائي. -- تكون `modelOverrides` مفعّلة افتراضيًا؛ وتكون القيمة الافتراضية لـ `modelOverrides.allowProvider` هي `false` (تفعيل اختياري). +- يتحكم `auto` في TTS التلقائي. ويجاوز `/tts off|always|inbound|tagged` ذلك لكل جلسة. +- يجاوز `summaryModel` القيمة `agents.defaults.model.primary` للملخص التلقائي. +- يكون `modelOverrides` مفعّلًا افتراضيًا؛ وتكون `modelOverrides.allowProvider` افتراضيًا `false` (اشتراك اختياري). - تعود مفاتيح API إلى `ELEVENLABS_API_KEY`/`XI_API_KEY` و`OPENAI_API_KEY`. -- تتجاوز `openai.baseUrl` نقطة نهاية OpenAI TTS. ويكون ترتيب الحل: الإعداد، ثم `OPENAI_TTS_BASE_URL`، ثم `https://api.openai.com/v1`. -- عندما تشير `openai.baseUrl` إلى نقطة نهاية غير OpenAI، يتعامل OpenClaw معها على أنها خادم TTS متوافق مع OpenAI ويخفف التحقق من النموذج/الصوت. +- يجاوز `openai.baseUrl` نقطة نهاية TTS الخاصة بـ OpenAI. ترتيب الحل هو: الإعدادات، ثم `OPENAI_TTS_BASE_URL`، ثم `https://api.openai.com/v1`. +- عندما يشير `openai.baseUrl` إلى نقطة نهاية غير OpenAI، يتعامل OpenClaw معها على أنها خادم TTS متوافق مع OpenAI ويخفف التحقق من النموذج/الصوت. --- ## Talk -القيم الافتراضية لوضع Talk ‏(macOS/iOS/Android). +الإعدادات الافتراضية لوضع Talk (macOS/iOS/Android). ```json5 { @@ -1944,13 +1938,13 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري } ``` -- يجب أن تطابق `talk.provider` مفتاحًا في `talk.providers` عند تكوين عدة مزوّدات Talk. -- مفاتيح Talk القديمة المسطحة (`talk.voiceId` و`talk.voiceAliases` و`talk.modelId` و`talk.outputFormat` و`talk.apiKey`) هي للتوافق فقط ويتم ترحيلها تلقائيًا إلى `talk.providers.`. -- تعود معرّفات الصوت إلى `ELEVENLABS_VOICE_ID` أو `SAG_VOICE_ID`. +- يجب أن يطابق `talk.provider` مفتاحًا في `talk.providers` عندما تكون هناك عدة مزوّدي Talk مكوّنين. +- مفاتيح Talk المسطحة القديمة (`talk.voiceId` و`talk.voiceAliases` و`talk.modelId` و`talk.outputFormat` و`talk.apiKey`) هي للتوافق فقط ويتم ترحيلها تلقائيًا إلى `talk.providers.`. +- تعود معرّفات الأصوات إلى `ELEVENLABS_VOICE_ID` أو `SAG_VOICE_ID`. - تقبل `providers.*.apiKey` سلاسل نصية صريحة أو كائنات SecretRef. -- لا يُستخدم البديل `ELEVENLABS_API_KEY` إلا عندما لا يكون أي مفتاح Talk API مكوَّنًا. -- تسمح `providers.*.voiceAliases` لتوجيهات Talk باستخدام أسماء ودية. -- تتحكم `silenceTimeoutMs` في مدة انتظار وضع Talk بعد صمت المستخدم قبل إرسال transcript. ويؤدي عدم تعيينها إلى الإبقاء على نافذة التوقف الافتراضية للمنصة (`700 ms على macOS وAndroid، و900 ms على iOS`). +- ينطبق البديل `ELEVENLABS_API_KEY` فقط عندما لا يكون مفتاح Talk API مكوّنًا. +- يتيح `providers.*.voiceAliases` لتوجيهات Talk استخدام أسماء ودية. +- يتحكم `silenceTimeoutMs` في مدة انتظار وضع Talk بعد صمت المستخدم قبل إرسال transcript. يؤدي حذفه إلى الإبقاء على نافذة التوقف الافتراضية للمنصة (`700 ms على macOS وAndroid، و900 ms على iOS`). --- @@ -1960,35 +1954,35 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري يضبط `tools.profile` قائمة سماح أساسية قبل `tools.allow`/`tools.deny`: -تضبط عملية الإعداد المحلية الافتراضية التهيئات المحلية الجديدة على `tools.profile: "coding"` عندما لا تكون معيّنة (ويتم الحفاظ على ملفات التعريف الصريحة الموجودة). +تفترض عملية الإعداد المحلي افتراضيًا الإعدادات المحلية الجديدة إلى `tools.profile: "coding"` عندما يكون غير معيّن (مع الحفاظ على الملفات الصريحة الموجودة). -| الملف الشخصي | يتضمن | -| ------------ | ----------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | `session_status` فقط | -| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | -| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | بلا تقييد (مثل الحذف) | +| الملف التعريفي | يتضمن | +| -------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `minimal` | `session_status` فقط | +| `coding` | `group:fs` و`group:runtime` و`group:web` و`group:sessions` و`group:memory` و`cron` و`image` و`image_generate` و`video_generate` | +| `messaging` | `group:messaging` و`sessions_list` و`sessions_history` و`sessions_send` و`session_status` | +| `full` | بلا قيود (مثل غير المعيّن) | ### مجموعات الأدوات -| المجموعة | الأدوات | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash` مقبول كاسم بديل لـ `exec`) | -| `group:fs` | `read`, `write`, `edit`, `apply_patch` | -| `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | -| `group:memory` | `memory_search`, `memory_get` | -| `group:web` | `web_search`, `x_search`, `web_fetch` | -| `group:ui` | `browser`, `canvas` | -| `group:automation` | `cron`, `gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | كل الأدوات المضمّنة (باستثناء إضافات المزوّدين) | +| المجموعة | الأدوات | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------ | +| `group:runtime` | `exec` و`process` و`code_execution` (ويُقبل `bash` كاسم مستعار لـ `exec`) | +| `group:fs` | `read` و`write` و`edit` و`apply_patch` | +| `group:sessions` | `sessions_list` و`sessions_history` و`sessions_send` و`sessions_spawn` و`sessions_yield` و`subagents` و`session_status` | +| `group:memory` | `memory_search` و`memory_get` | +| `group:web` | `web_search` و`x_search` و`web_fetch` | +| `group:ui` | `browser` و`canvas` | +| `group:automation` | `cron` و`gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image` و`image_generate` و`video_generate` و`tts` | +| `group:openclaw` | جميع الأدوات المضمّنة (باستثناء إضافات مزوّدي plugin) | ### `tools.allow` / `tools.deny` -سياسة السماح/المنع العامة للأدوات (المنع يفوز). غير حساسة لحالة الأحرف، وتدعم أحرف البدل `*`. وتُطبق حتى عندما يكون Docker sandbox معطّلًا. +سياسة السماح/المنع العامة للأدوات (المنع يفوز). غير حساسة لحالة الأحرف، وتدعم أحرفًا عامة `*`. تُطبق حتى عند إيقاف Docker sandbox. ```json5 { @@ -1998,7 +1992,7 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري ### `tools.byProvider` -تقيّد الأدوات أكثر لمزوّدين أو نماذج محددة. الترتيب: الملف الشخصي الأساسي → ملف تعريف المزوّد → allow/deny. +تقييد إضافي للأدوات لمزوّدين أو نماذج محددة. الترتيب: الملف التعريفي الأساسي → ملف المزود → السماح/المنع. ```json5 { @@ -2030,9 +2024,9 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري } ``` -- يمكن لتجاوز كل وكيل (`agents.list[].tools.elevated`) فقط أن يقيّد أكثر. -- يخزن `/elevated on|off|ask|full` الحالة لكل جلسة؛ بينما تنطبق التوجيهات المضمنة على رسالة واحدة. -- يتجاوز `exec` المرتفع العزل ويستخدم مسار الهروب المكوّن (`gateway` افتراضيًا، أو `node` عندما يكون هدف exec هو `node`). +- لا يمكن لتجاوز كل وكيل (`agents.list[].tools.elevated`) إلا أن يضيف مزيدًا من التقييد. +- يخزن `/elevated on|off|ask|full` الحالة لكل جلسة؛ وتُطبق التوجيهات المضمنة على رسالة واحدة. +- يتجاوز `exec` المرتفع الحماية داخل sandbox ويستخدم مسار الخروج المكوّن (`gateway` افتراضيًا، أو `node` عندما يكون هدف exec هو `node`). ### `tools.exec` @@ -2056,8 +2050,8 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري ### `tools.loopDetection` -فحوصات أمان حلقات الأدوات تكون **معطّلة افتراضيًا**. اضبط `enabled: true` لتفعيل الاكتشاف. -يمكن تعريف الإعدادات عمومًا في `tools.loopDetection` وتجاوزها لكل وكيل في `agents.list[].tools.loopDetection`. +تكون فحوصات أمان حلقات الأدوات **معطلة افتراضيًا**. اضبط `enabled: true` لتفعيل الاكتشاف. +يمكن تعريف الإعدادات عالميًا في `tools.loopDetection` وتجاوزها لكل وكيل في `agents.list[].tools.loopDetection`. ```json5 { @@ -2078,13 +2072,13 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري } ``` -- `historySize`: الحد الأقصى لسجل استدعاءات الأدوات المحتفظ به لتحليل الحلقات. -- `warningThreshold`: عتبة التحذير للأنماط المتكررة من دون تقدم. -- `criticalThreshold`: عتبة أعلى لحظر الحلقات الحرجة المتكررة. -- `globalCircuitBreakerThreshold`: عتبة توقف صارمة لأي تشغيل من دون تقدم. -- `detectors.genericRepeat`: التحذير من الاستدعاءات المتكررة لنفس الأداة/نفس الوسائط. -- `detectors.knownPollNoProgress`: التحذير/الحظر على أدوات poll المعروفة (`process.poll`, `command_status`, إلخ). -- `detectors.pingPong`: التحذير/الحظر على الأنماط الزوجية المتناوبة من دون تقدم. +- `historySize`: أقصى سجل لاستدعاءات الأدوات محتفَظ به لتحليل الحلقات. +- `warningThreshold`: حد نمط التكرار بلا تقدم لإصدار التحذيرات. +- `criticalThreshold`: حد أعلى للتكرار لحظر الحلقات الحرجة. +- `globalCircuitBreakerThreshold`: حد إيقاف صارم لأي تشغيل بلا تقدم. +- `detectors.genericRepeat`: التحذير عند تكرار نفس الأداة/نفس الوسائط. +- `detectors.knownPollNoProgress`: التحذير/الحظر لأدوات الاستطلاع المعروفة (`process.poll` و`command_status` وغيرهما). +- `detectors.pingPong`: التحذير/الحظر للأنماط الزوجية المتناوبة بلا تقدم. - إذا كانت `warningThreshold >= criticalThreshold` أو `criticalThreshold >= globalCircuitBreakerThreshold`، يفشل التحقق. ### `tools.web` @@ -2095,14 +2089,14 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري web: { search: { enabled: true, - apiKey: "brave_api_key", // أو BRAVE_API_KEY من البيئة + apiKey: "brave_api_key", // or BRAVE_API_KEY env maxResults: 5, timeoutSeconds: 30, cacheTtlMinutes: 15, }, fetch: { enabled: true, - provider: "firecrawl", // اختياري؛ احذفه للاكتشاف التلقائي + provider: "firecrawl", // optional; omit for auto-detect maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2127,7 +2121,7 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري media: { concurrency: 2, asyncCompletion: { - directSend: false, // تفعيل اختياري: أرسل مهام الموسيقى/الفيديو غير المتزامنة المكتملة مباشرة إلى القناة + directSend: false, // opt-in: send finished async music/video directly to the channel }, audio: { enabled: true, @@ -2153,20 +2147,20 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري -**إدخال المزوّد** (`type: "provider"` أو عند الحذف): +**إدخال المزوّد** (`type: "provider"` أو محذوف): -- `provider`: معرّف مزوّد API (`openai` أو `anthropic` أو `google`/`gemini` أو `groq`، إلخ) +- `provider`: معرّف مزود API (`openai` أو `anthropic` أو `google`/`gemini` أو `groq`، إلخ) - `model`: تجاوز معرّف النموذج -- `profile` / `preferredProfile`: اختيار ملف التعريف في `auth-profiles.json` +- `profile` / `preferredProfile`: اختيار ملف `auth-profiles.json` **إدخال CLI** (`type: "cli"`): -- `command`: الملف التنفيذي المطلوب تشغيله +- `command`: البرنامج التنفيذي المراد تشغيله - `args`: وسائط بقوالب (تدعم `{{MediaPath}}` و`{{Prompt}}` و`{{MaxChars}}`، إلخ) **الحقول المشتركة:** -- `capabilities`: قائمة اختيارية (`image`, `audio`, `video`). القيم الافتراضية: `openai`/`anthropic`/`minimax` → صورة، `google` → صورة+صوت+فيديو، `groq` → صوت. +- `capabilities`: قائمة اختيارية (`image`، `audio`، `video`). القيم الافتراضية: `openai`/`anthropic`/`minimax` → image، و`google` → image+audio+video، و`groq` → audio. - `prompt` و`maxChars` و`maxBytes` و`timeoutSeconds` و`language`: تجاوزات لكل إدخال. - تعود الإخفاقات إلى الإدخال التالي. @@ -2176,7 +2170,7 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري - `asyncCompletion.directSend`: عندما تكون `true`، تحاول مهام `music_generate` و`video_generate` غير المتزامنة المكتملة التسليم المباشر إلى القناة أولًا. الافتراضي: `false` - (المسار القديم لإيقاظ جلسة الطالب/التسليم عبر النموذج). + (مسار الإيقاظ/التسليم بالنموذج الخاص بجلسة الطالب القديمة). @@ -2195,7 +2189,7 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري ### `tools.sessions` -يتحكم في الجلسات التي يمكن استهدافها بواسطة أدوات الجلسات (`sessions_list` و`sessions_history` و`sessions_send`). +يتحكم في الجلسات التي يمكن استهدافها بواسطة أدوات الجلسات (`sessions_list`، `sessions_history`، `sessions_send`). الافتراضي: `tree` (الجلسة الحالية + الجلسات التي أنشأتها، مثل الوكلاء الفرعيين). @@ -2214,24 +2208,24 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري - `self`: مفتاح الجلسة الحالية فقط. - `tree`: الجلسة الحالية + الجلسات التي أنشأتها الجلسة الحالية (الوكلاء الفرعيون). -- `agent`: أي جلسة تخص معرّف الوكيل الحالي (قد يشمل ذلك مستخدمين آخرين إذا كنت تشغّل جلسات لكل مرسل تحت نفس معرّف الوكيل). -- `all`: أي جلسة. لا يزال الاستهداف عبر الوكلاء يتطلب `tools.agentToAgent`. -- تقييد sandbox: عندما تكون الجلسة الحالية داخل sandbox وكانت `agents.defaults.sandbox.sessionToolsVisibility="spawned"`، يتم فرض الرؤية على `tree` حتى لو كانت `tools.sessions.visibility="all"`. +- `agent`: أي جلسة تخص معرّف الوكيل الحالي (وقد يشمل مستخدمين آخرين إذا كنت تشغّل جلسات لكل مرسل تحت نفس معرّف الوكيل). +- `all`: أي جلسة. وما يزال الاستهداف عبر الوكلاء يتطلب `tools.agentToAgent`. +- تقييد sandbox: عندما تكون الجلسة الحالية داخل sandbox وكان `agents.defaults.sandbox.sessionToolsVisibility="spawned"`، تُفرض الرؤية إلى `tree` حتى لو كانت `tools.sessions.visibility="all"`. ### `tools.sessions_spawn` -يتحكم في دعم المرفقات المضمّنة لـ `sessions_spawn`. +يتحكم في دعم المرفقات المضمنة لـ `sessions_spawn`. ```json5 { tools: { sessions_spawn: { attachments: { - enabled: false, // تفعيل اختياري: اضبط true للسماح بمرفقات الملفات المضمّنة - maxTotalBytes: 5242880, // 5 MB إجماليًا عبر جميع الملفات + enabled: false, // opt-in: set true to allow inline file attachments + maxTotalBytes: 5242880, // 5 MB total across all files maxFiles: 50, - maxFileBytes: 1048576, // 1 MB لكل ملف - retainOnSessionKeep: false, // احتفظ بالمرفقات عندما cleanup="keep" + maxFileBytes: 1048576, // 1 MB per file + retainOnSessionKeep: false, // keep attachments when cleanup="keep" }, }, }, @@ -2240,22 +2234,22 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري ملاحظات: -- لا تُدعَم المرفقات إلا لـ `runtime: "subagent"`. ويرفض ACP runtime هذه المرفقات. -- تتم مادية الملفات في مساحة عمل الطفل ضمن `.openclaw/attachments//` مع `.manifest.json`. -- يتم تلقائيًا تنقيح محتوى المرفقات من حفظ transcript. -- يتم التحقق من مدخلات Base64 مع تدقيق صارم للأبجدية/الحشو وحاجز حجم قبل فك الترميز. -- تكون أذونات الملفات `0700` للأدلة و`0600` للملفات. +- المرفقات مدعومة فقط مع `runtime: "subagent"`. ويرفض ACP runtime هذه المرفقات. +- يتم إنشاء الملفات داخل مساحة عمل الابن في `.openclaw/attachments//` مع ملف `.manifest.json`. +- يتم إخفاء محتوى المرفقات تلقائيًا من حفظ transcript. +- يتم التحقق من مدخلات Base64 بفحص صارم للأبجدية/الحشو وحارس حجم قبل فك الترميز. +- أذونات الملفات هي `0700` للأدلة و`0600` للملفات. - يتبع التنظيف سياسة `cleanup`: يقوم `delete` دائمًا بإزالة المرفقات؛ بينما يحتفظ `keep` بها فقط عندما تكون `retainOnSessionKeep: true`. ### `tools.experimental` -أعلام الأدوات المضمّنة التجريبية. تكون معطّلة افتراضيًا ما لم تنطبق قاعدة تفعيل تلقائي خاصة بوقت التشغيل. +أعلام الأدوات المضمّنة التجريبية. تكون معطلة افتراضيًا ما لم تنطبق قاعدة تمكين تلقائي خاصة بوقت التشغيل. ```json5 { tools: { experimental: { - planTool: true, // تمكين update_plan التجريبية + planTool: true, // enable experimental update_plan }, }, } @@ -2263,9 +2257,9 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري ملاحظات: -- `planTool`: يفعّل الأداة المهيكلة `update_plan` لتتبع الأعمال غير التافهة متعددة الخطوات. -- الافتراضي: `false` للمزوّدين غير OpenAI. ويتم تفعيلها تلقائيًا في تشغيلات OpenAI وOpenAI Codex. -- عند التفعيل، تضيف system prompt أيضًا إرشادات استخدام حتى لا يستخدمها النموذج إلا للأعمال الجوهرية ويحتفظ بخطوة واحدة فقط في حالة `in_progress`. +- `planTool`: يفعّل أداة `update_plan` التجريبية المنظمة لتتبع الأعمال غير البسيطة متعددة الخطوات. +- الافتراضي: `false` لمزوّدي غير OpenAI. وتقوم تشغيلات OpenAI وOpenAI Codex بتفعيلها تلقائيًا. +- عندما تكون مفعّلة، يضيف system prompt أيضًا إرشادات استخدام بحيث يستخدمها النموذج فقط للأعمال الكبيرة ويحافظ على خطوة واحدة كحد أقصى في حالة `in_progress`. ### `agents.defaults.subagents` @@ -2286,20 +2280,20 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري ``` - `model`: النموذج الافتراضي للوكلاء الفرعيين الذين يتم إنشاؤهم. وإذا حُذف، يرث الوكلاء الفرعيون نموذج المستدعي. -- `allowAgents`: قائمة السماح الافتراضية لمعرّفات الوكلاء الهدف في `sessions_spawn` عندما لا يضبط الوكيل الطالب `subagents.allowAgents` الخاص به (`["*"]` = أي وكيل؛ الافتراضي: نفس الوكيل فقط). +- `allowAgents`: قائمة السماح الافتراضية لمعرّفات الوكلاء الهدف لـ `sessions_spawn` عندما لا يعيّن وكيل الطالب `subagents.allowAgents` الخاص به (`["*"]` = أي وكيل؛ الافتراضي: نفس الوكيل فقط). - `runTimeoutSeconds`: المهلة الافتراضية (بالثواني) لـ `sessions_spawn` عندما يحذف استدعاء الأداة `runTimeoutSeconds`. وتعني `0` عدم وجود مهلة. - سياسة الأدوات لكل وكيل فرعي: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- -## المزوّدون المخصصون وعناوين base URL +## المزوّدون المخصصون وعناوين URL الأساسية -يستخدم OpenClaw كتالوج النماذج المضمّن. أضف مزوّدين مخصصين عبر `models.providers` في الإعداد أو `~/.openclaw/agents//agent/models.json`. +يستخدم OpenClaw فهرس النماذج المضمّن. أضف مزوّدين مخصصين عبر `models.providers` في الإعدادات أو `~/.openclaw/agents//agent/models.json`. ```json5 { models: { - mode: "merge", // merge (الافتراضي) | replace + mode: "merge", // merge (default) | replace providers: { "custom-proxy": { baseUrl: "http://localhost:4000/v1", @@ -2324,47 +2318,48 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري ``` - استخدم `authHeader: true` + `headers` لاحتياجات المصادقة المخصصة. -- تجاوز جذر إعداد الوكيل عبر `OPENCLAW_AGENT_DIR` (أو `PI_CODING_AGENT_DIR`، وهو اسم بديل بيئي قديم). -- أسبقية الدمج لمعرّفات المزوّدات المتطابقة: +- تجاوز جذر إعدادات الوكيل عبر `OPENCLAW_AGENT_DIR` (أو `PI_CODING_AGENT_DIR`، وهو اسم مستعار قديم لمتغير البيئة). +- أولوية الدمج لمعرّفات المزوّد المطابقة: - تفوز قيم `baseUrl` غير الفارغة في `models.json` الخاص بالوكيل. - - تفوز قيم `apiKey` غير الفارغة الخاصة بالوكيل فقط عندما لا يكون ذلك المزوّد مُدارًا عبر SecretRef في سياق الإعداد/ملف المصادقة الحالي. - - يتم تحديث قيم `apiKey` المُدارة عبر SecretRef من علامات المصدر (`ENV_VAR_NAME` لمراجع env، و`secretref-managed` لمراجع file/exec) بدلًا من حفظ الأسرار المحلولة. - - يتم تحديث قيم header الخاصة بالمزوّد والمُدارة عبر SecretRef من علامات المصدر (`secretref-env:ENV_VAR_NAME` لمراجع env، و`secretref-managed` لمراجع file/exec). - - تعود قيم `apiKey`/`baseUrl` الفارغة أو المحذوفة لدى الوكيل إلى `models.providers` في الإعداد. - - تستخدم قيم `contextWindow`/`maxTokens` للنموذج المطابق القيمة الأعلى بين الإعداد الصريح وقيم الكتالوج الضمنية. - - تحتفظ `contextTokens` للنموذج المطابق بسقف وقت تشغيل صريح عند توفره؛ استخدمه لتقييد السياق الفعّال من دون تغيير بيانات النموذج الأصلية. - - استخدم `models.mode: "replace"` عندما تريد من الإعداد إعادة كتابة `models.json` بالكامل. - - يكون حفظ العلامات معتمدًا على المصدر: تُكتب العلامات من لقطة إعداد المصدر النشطة (قبل الحل)، وليس من قيم الأسرار المحلولة وقت التشغيل. + - تفوز قيم `apiKey` غير الفارغة في الوكيل فقط عندما لا يكون ذلك المزوّد مُدارًا عبر SecretRef في سياق الإعدادات/ملف المصادقة الحالي. + - يتم تحديث قيم `apiKey` للمزوّد المُدار عبر SecretRef من علامات المصدر (`ENV_VAR_NAME` لمراجع env، و`secretref-managed` لمراجع file/exec) بدلًا من حفظ الأسرار المحلولة. + - يتم تحديث قيم رؤوس المزوّد المُدارة عبر SecretRef من علامات المصدر (`secretref-env:ENV_VAR_NAME` لمراجع env، و`secretref-managed` لمراجع file/exec). + - تعود قيم `apiKey`/`baseUrl` الفارغة أو المفقودة في الوكيل إلى `models.providers` في الإعدادات. + - تستخدم قيم `contextWindow`/`maxTokens` الأعلى بين الإعداد الصريح وقيم الفهرس الضمنية للنموذج المطابق. + - تحفظ `contextTokens` المطابقة حد وقت التشغيل الصريح عندما يكون موجودًا؛ استخدمها لتقييد السياق الفعّال من دون تغيير بيانات النموذج الأصلية. + - استخدم `models.mode: "replace"` عندما تريد أن تعيد الإعدادات كتابة `models.json` بالكامل. + - يكون حفظ العلامات معتمدًا على المصدر: تُكتب العلامات من لقطة الإعدادات النشطة للمصدر (قبل الحل)، وليس من قيم الأسرار المحلولة وقت التشغيل. ### تفاصيل حقول المزوّد -- `models.mode`: سلوك كتالوج المزوّد (`merge` أو `replace`). -- `models.providers`: خريطة المزوّدات المخصصة مفهرسة بمعرّف المزوّد. -- `models.providers.*.api`: مكيّف الطلب (`openai-completions` أو `openai-responses` أو `anthropic-messages` أو `google-generative-ai`، إلخ). -- `models.providers.*.apiKey`: بيانات اعتماد المزوّد (يُفضَّل SecretRef/استبدال env). +- `models.mode`: سلوك فهرس المزوّد (`merge` أو `replace`). +- `models.providers`: خريطة المزوّدين المخصصين مفهرسة حسب معرّف المزوّد. +- `models.providers.*.api`: محول الطلب (`openai-completions` أو `openai-responses` أو `anthropic-messages` أو `google-generative-ai`، إلخ). +- `models.providers.*.apiKey`: اعتماد المزوّد (يفضَّل SecretRef/استبدال env). - `models.providers.*.auth`: استراتيجية المصادقة (`api-key` أو `token` أو `oauth` أو `aws-sdk`). -- `models.providers.*.injectNumCtxForOpenAICompat`: بالنسبة إلى Ollama + `openai-completions`، يحقن `options.num_ctx` في الطلبات (الافتراضي: `true`). -- `models.providers.*.authHeader`: يفرض نقل بيانات الاعتماد في ترويسة `Authorization` عند الحاجة. -- `models.providers.*.baseUrl`: عنوان API الأساسي للمنبع. -- `models.providers.*.headers`: ترويسات ثابتة إضافية لتوجيه proxy/tenant. +- `models.providers.*.injectNumCtxForOpenAICompat`: بالنسبة إلى Ollama مع `openai-completions`، يحقن `options.num_ctx` في الطلبات (الافتراضي: `true`). +- `models.providers.*.authHeader`: فرض نقل الاعتماد في رأس `Authorization` عند الحاجة. +- `models.providers.*.baseUrl`: عنوان API الأساسي الأعلى. +- `models.providers.*.headers`: رؤوس ثابتة إضافية لتوجيه proxy/المستأجر. - `models.providers.*.request`: تجاوزات النقل لطلبات HTTP الخاصة بمزوّد النموذج. - - `request.headers`: ترويسات إضافية (تُدمج مع القيم الافتراضية للمزوّد). وتقبل القيم SecretRef. - - `request.auth`: تجاوز استراتيجية المصادقة. الأوضاع: `"provider-default"` (استخدام المصادقة المضمّنة للمزوّد)، و`"authorization-bearer"` (مع `token`)، و`"header"` (مع `headerName` و`value` و`prefix` الاختياري). - - `request.proxy`: تجاوز وكيل HTTP. الأوضاع: `"env-proxy"` (استخدام متغيرات `HTTP_PROXY`/`HTTPS_PROXY` من البيئة)، و`"explicit-proxy"` (مع `url`). ويقبل كلا الوضعين عنصر `tls` فرعيًا اختياريًا. - - `request.tls`: تجاوز TLS للاتصالات المباشرة. الحقول: `ca` و`cert` و`key` و`passphrase` (تقبل جميعها SecretRef)، و`serverName` و`insecureSkipVerify`. -- `models.providers.*.models`: إدخالات كتالوج نماذج صريحة للمزوّد. -- `models.providers.*.models.*.contextWindow`: بيانات وصفية لنافذة السياق الأصلية للنموذج. -- `models.providers.*.models.*.contextTokens`: سقف سياق اختياري لوقت التشغيل. استخدمه عندما تريد ميزانية سياق فعّالة أصغر من `contextWindow` الأصلية للنموذج. -- `models.providers.*.models.*.compat.supportsDeveloperRole`: تلميح توافق اختياري. بالنسبة إلى `api: "openai-completions"` مع `baseUrl` غير فارغ وغير أصلي (المضيف ليس `api.openai.com`)، يفرض OpenClaw هذه القيمة إلى `false` وقت التشغيل. ويُبقي `baseUrl` الفارغ/المحذوف السلوك الافتراضي لـ OpenAI. + - `request.headers`: رؤوس إضافية (تُدمج مع افتراضيات المزوّد). القيم تقبل SecretRef. + - `request.auth`: تجاوز لاستراتيجية المصادقة. الأوضاع: `"provider-default"` (استخدام المصادقة المضمنة للمزوّد)، أو `"authorization-bearer"` (مع `token`)، أو `"header"` (مع `headerName` و`value` و`prefix` الاختياري). + - `request.proxy`: تجاوز لوكيل HTTP. الأوضاع: `"env-proxy"` (استخدام متغيري البيئة `HTTP_PROXY`/`HTTPS_PROXY`)، و`"explicit-proxy"` (مع `url`). ويقبل كلا الوضعين كائن `tls` اختياري. + - `request.tls`: تجاوز TLS للاتصالات المباشرة. الحقول: `ca` و`cert` و`key` و`passphrase` (كلها تقبل SecretRef)، و`serverName`، و`insecureSkipVerify`. +- `models.providers.*.models`: إدخالات فهرس نماذج صريحة للمزوّد. +- `models.providers.*.models.*.contextWindow`: بيانات تعريف نافذة السياق الأصلية للنموذج. +- `models.providers.*.models.*.contextTokens`: حد سياق اختياري لوقت التشغيل. استخدمه عندما تريد ميزانية سياق فعّالة أصغر من `contextWindow` الأصلية للنموذج. +- `models.providers.*.models.*.compat.supportsDeveloperRole`: تلميح توافق اختياري. بالنسبة إلى `api: "openai-completions"` مع `baseUrl` غير أصلي وغير فارغ (مضيف ليس `api.openai.com`)، يفرض OpenClaw هذا إلى `false` وقت التشغيل. ويُبقي `baseUrl` الفارغ/المحذوف سلوك OpenAI الافتراضي. +- `models.providers.*.models.*.compat.requiresStringContent`: تلميح توافق اختياري لنقاط نهاية الدردشة المتوافقة مع OpenAI التي تقبل السلاسل فقط. عندما يكون `true`، يسطّح OpenClaw مصفوفات `messages[].content` النصية البحتة إلى سلاسل عادية قبل إرسال الطلب. - `plugins.entries.amazon-bedrock.config.discovery`: جذر إعدادات الاكتشاف التلقائي لـ Bedrock. - `plugins.entries.amazon-bedrock.config.discovery.enabled`: تشغيل/إيقاف الاكتشاف الضمني. - `plugins.entries.amazon-bedrock.config.discovery.region`: منطقة AWS للاكتشاف. -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: عامل تصفية اختياري لمعرّف المزوّد لاكتشاف موجّه. -- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: فترة الاقتراع لتحديث الاكتشاف. -- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: نافذة السياق الاحتياطية للنماذج المكتشفة. -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: الحد الأقصى الاحتياطي لرموز الإخراج للنماذج المكتشفة. +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: مرشح معرّف مزوّد اختياري للاكتشاف الموجّه. +- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: فترة الاستطلاع لتحديث الاكتشاف. +- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: نافذة سياق احتياطية للنماذج المكتشفة. +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: الحد الاحتياطي الأقصى لرموز الخرج للنماذج المكتشفة. -### أمثلة للمزوّدين +### أمثلة على المزوّدين @@ -2417,7 +2412,7 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري } ``` -اضبط `OPENCODE_API_KEY` (أو `OPENCODE_ZEN_API_KEY`). استخدم مراجع `opencode/...` لكتالوج Zen أو مراجع `opencode-go/...` لكتالوج Go. اختصار: `openclaw onboard --auth-choice opencode-zen` أو `openclaw onboard --auth-choice opencode-go`. +اضبط `OPENCODE_API_KEY` (أو `OPENCODE_ZEN_API_KEY`). استخدم مراجع `opencode/...` لفهرس Zen أو مراجع `opencode-go/...` لفهرس Go. اختصار: `openclaw onboard --auth-choice opencode-zen` أو `openclaw onboard --auth-choice opencode-go`. @@ -2434,11 +2429,11 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري } ``` -اضبط `ZAI_API_KEY`. وتُقبل الأسماء البديلة `z.ai/*` و`z-ai/*`. اختصار: `openclaw onboard --auth-choice zai-api-key`. +اضبط `ZAI_API_KEY`. يُقبل `z.ai/*` و`z-ai/*` كأسماء مستعارة. اختصار: `openclaw onboard --auth-choice zai-api-key`. - نقطة النهاية العامة: `https://api.z.ai/api/paas/v4` -- نقطة نهاية البرمجة (الافتراضية): `https://api.z.ai/api/coding/paas/v4` -- بالنسبة إلى نقطة النهاية العامة، عرّف مزوّدًا مخصصًا مع تجاوز base URL. +- نقطة نهاية البرمجة (افتراضية): `https://api.z.ai/api/coding/paas/v4` +- بالنسبة لنقطة النهاية العامة، عرّف مزودًا مخصصًا مع تجاوز `baseUrl`. @@ -2479,9 +2474,9 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري بالنسبة إلى نقطة نهاية الصين: `baseUrl: "https://api.moonshot.cn/v1"` أو `openclaw onboard --auth-choice moonshot-api-key-cn`. -تعلن نقاط النهاية الأصلية لـ Moonshot عن توافق استخدام البث على النقل المشترك -`openai-completions`، ويعتمد OpenClaw الآن ذلك على -قدرات نقطة النهاية بدلًا من معرّف المزوّد المضمّن وحده. +تعلن نقاط نهاية Moonshot الأصلية توافق استخدام البث على مسار النقل المشترك +`openai-completions`، ويعتمد OpenClaw الآن ذلك على قدرات نقطة النهاية +بدلًا من الاكتفاء بمعرّف المزوّد المضمّن وحده. @@ -2499,7 +2494,7 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري } ``` -متوافق مع Anthropic، ومزوّد مضمّن. اختصار: `openclaw onboard --auth-choice kimi-code-api-key`. +متوافق مع Anthropic ومزوّد مضمّن. اختصار: `openclaw onboard --auth-choice kimi-code-api-key`. @@ -2538,7 +2533,7 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري } ``` -يجب أن يحذف base URL القيمة `/v1` (لأن عميل Anthropic يضيفها). اختصار: `openclaw onboard --auth-choice synthetic-api-key`. +يجب أن يحذف `baseUrl` اللاحقة `/v1` (عميل Anthropic يضيفها). اختصار: `openclaw onboard --auth-choice synthetic-api-key`. @@ -2581,17 +2576,17 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري اضبط `MINIMAX_API_KEY`. الاختصارات: `openclaw onboard --auth-choice minimax-global-api` أو `openclaw onboard --auth-choice minimax-cn-api`. -يستخدم كتالوج النماذج الآن M2.7 فقط افتراضيًا. +يفترض فهرس النماذج الآن M2.7 فقط. على مسار البث المتوافق مع Anthropic، يعطّل OpenClaw التفكير في MiniMax -افتراضيًا ما لم تضبط `thinking` صراحة بنفسك. يقوم `/fast on` أو -`params.fastMode: true` بإعادة كتابة `MiniMax-M2.7` إلى +افتراضيًا ما لم تضبط `thinking` بنفسك صراحةً. يعيد `/fast on` أو +`params.fastMode: true` كتابة `MiniMax-M2.7` إلى `MiniMax-M2.7-highspeed`. -راجع [النماذج المحلية](/ar/gateway/local-models). باختصار: شغّل نموذجًا محليًا كبيرًا عبر LM Studio Responses API على عتاد قوي؛ واحتفظ بالنماذج المستضافة مدمجة كخيار احتياطي. +راجع [النماذج المحلية](/ar/gateway/local-models). باختصار: شغّل نموذجًا محليًا كبيرًا عبر LM Studio Responses API على عتاد قوي؛ واحتفظ بالنماذج المستضافة مدمجة من أجل fallback. @@ -2612,7 +2607,7 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري }, entries: { "image-lab": { - apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // أو سلسلة نصية صريحة + apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, @@ -2622,14 +2617,14 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري } ``` -- `allowBundled`: قائمة سماح اختيارية لـ Skills المضمّنة فقط (ولا تتأثر Skills المُدارة/الخاصة بمساحة العمل). -- `load.extraDirs`: جذور Skills مشتركة إضافية (أدنى أسبقية). +- `allowBundled`: قائمة سماح اختيارية لـ Skills المضمنة فقط (ولا تتأثر Skills المُدارة/Skills مساحة العمل). +- `load.extraDirs`: جذور Skills مشتركة إضافية (بأدنى أولوية). - `install.preferBrew`: عندما تكون true، يفضّل مُثبّتات Homebrew عندما يكون `brew` - متاحًا قبل الرجوع إلى أنواع مُثبّتات أخرى. -- `install.nodeManager`: تفضيل مُثبّت node لمواصفات `metadata.openclaw.install` + متاحًا قبل الرجوع إلى أنواع المثبتات الأخرى. +- `install.nodeManager`: تفضيل مُثبّت Node لمواصفات `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). -- تقوم `entries..enabled: false` بتعطيل Skill حتى لو كانت مضمّنة/مثبّتة. -- `entries..apiKey`: وسيلة ملائمة لـ Skills التي تعلن متغير env أساسيًا (سلسلة نصية صريحة أو كائن SecretRef). +- `entries..enabled: false` يعطّل Skill حتى لو كان مضمّنًا/مثبتًا. +- `entries..apiKey`: حقل ملاءمة لمفتاح API للـ Skills التي تعلن متغير env أساسيًا (سلسلة صريحة أو كائن SecretRef). --- @@ -2657,37 +2652,37 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري } ``` -- يتم تحميلها من `~/.openclaw/extensions`، و`/.openclaw/extensions`، بالإضافة إلى `plugins.load.paths`. -- يَقبل الاكتشاف إضافات OpenClaw الأصلية بالإضافة إلى حزم Codex المتوافقة وحزم Claude، بما في ذلك حزم Claude ذات التخطيط الافتراضي من دون manifest. -- **تتطلب تغييرات الإعداد إعادة تشغيل البوابة.** -- `allow`: قائمة سماح اختيارية (تُحمّل الإضافات المدرجة فقط). ويفوز `deny`. -- `plugins.entries..apiKey`: حقل مناسب لمفتاح API على مستوى الإضافة (عندما تدعمه الإضافة). -- `plugins.entries..env`: خريطة متغيرات env بنطاق الإضافة. -- `plugins.entries..hooks.allowPromptInjection`: عندما تكون `false`، يقوم core بحظر `before_prompt_build` ويتجاهل الحقول التي تغيّر prompt من `before_agent_start` القديم، مع الحفاظ على `modelOverride` و`providerOverride` القديمين. وينطبق ذلك على hooks الخاصة بالإضافة الأصلية وعلى أدلة hooks التي توفرها الحزم المدعومة. -- `plugins.entries..subagent.allowModelOverride`: يثق صراحة في هذه الإضافة لطلب تجاوزات `provider` و`model` لكل تشغيل في تشغيلات الوكلاء الفرعيين الخلفية. -- `plugins.entries..subagent.allowedModels`: قائمة سماح اختيارية لأهداف `provider/model` القياسية الخاصة بتجاوزات الوكلاء الفرعيين الموثوق بها. واستخدم `"*"` فقط عندما تريد عمدًا السماح بأي نموذج. -- `plugins.entries..config`: كائن إعداد معرّف من الإضافة (ويتحقق منه مخطط إضافة OpenClaw الأصلية عند توفره). -- `plugins.entries.firecrawl.config.webFetch`: إعدادات مزوّد web-fetch الخاص بـ Firecrawl. - - `apiKey`: مفتاح Firecrawl API (يقبل SecretRef). ويعود إلى `plugins.entries.firecrawl.config.webSearch.apiKey`، أو `tools.web.fetch.firecrawl.apiKey` القديم، أو متغير البيئة `FIRECRAWL_API_KEY`. - - `baseUrl`: عنوان Firecrawl API الأساسي (الافتراضي: `https://api.firecrawl.dev`). +- يتم تحميلها من `~/.openclaw/extensions` و`/.openclaw/extensions` و`plugins.load.paths`. +- يقبل الاكتشاف إضافات OpenClaw الأصلية بالإضافة إلى حزم Codex المتوافقة وحزم Claude، بما في ذلك حزم Claude بلا manifest ذات التخطيط الافتراضي. +- **تتطلب تغييرات الإعدادات إعادة تشغيل للبوابة.** +- `allow`: قائمة سماح اختيارية (يتم تحميل الإضافات المدرجة فقط). يفوز `deny`. +- `plugins.entries..apiKey`: حقل ملاءمة لمفتاح API على مستوى الإضافة (عندما تدعمه الإضافة). +- `plugins.entries..env`: خريطة متغيرات بيئة ضمن نطاق الإضافة. +- `plugins.entries..hooks.allowPromptInjection`: عندما تكون `false`، يمنع core الخطاف `before_prompt_build` ويتجاهل الحقول المعدِّلة للـ prompt من `before_agent_start` القديم، مع الحفاظ على `modelOverride` و`providerOverride` القديمين. ينطبق ذلك على خطافات الإضافات الأصلية وأدلة الخطافات المدعومة التي توفرها الحزم. +- `plugins.entries..subagent.allowModelOverride`: يثق صراحةً في هذه الإضافة لطلب تجاوزات `provider` و`model` لكل تشغيل أثناء تشغيلات الوكلاء الفرعيين في الخلفية. +- `plugins.entries..subagent.allowedModels`: قائمة سماح اختيارية للأهداف القياسية `provider/model` لتجاوزات الوكلاء الفرعيين الموثوقة. استخدم `"*"` فقط عندما تريد عمدًا السماح بأي نموذج. +- `plugins.entries..config`: كائن إعدادات معرَّف بواسطة الإضافة (يتم التحقق منه وفق مخطط إضافة OpenClaw الأصلية عندما يكون متاحًا). +- `plugins.entries.firecrawl.config.webFetch`: إعدادات مزود جلب الويب Firecrawl. + - `apiKey`: مفتاح API لـ Firecrawl (يقبل SecretRef). ويعود إلى `plugins.entries.firecrawl.config.webSearch.apiKey`، أو `tools.web.fetch.firecrawl.apiKey` القديم، أو متغير البيئة `FIRECRAWL_API_KEY`. + - `baseUrl`: عنوان API الأساسي لـ Firecrawl (الافتراضي: `https://api.firecrawl.dev`). - `onlyMainContent`: استخراج المحتوى الرئيسي فقط من الصفحات (الافتراضي: `true`). - - `maxAgeMs`: الحد الأقصى لعمر cache بالمللي ثانية (الافتراضي: `172800000` / يومان). - - `timeoutSeconds`: مهلة طلب scraping بالثواني (الافتراضي: `60`). -- `plugins.entries.xai.config.xSearch`: إعدادات xAI X Search ‏(بحث الويب Grok). - - `enabled`: تمكين مزوّد X Search. + - `maxAgeMs`: الحد الأقصى لعمر الذاكرة المؤقتة بالمللي ثانية (الافتراضي: `172800000` / يومان). + - `timeoutSeconds`: مهلة طلب الاستخراج scrape بالثواني (الافتراضي: `60`). +- `plugins.entries.xai.config.xSearch`: إعدادات xAI X Search (بحث الويب Grok). + - `enabled`: تفعيل مزود X Search. - `model`: نموذج Grok المستخدم للبحث (مثل `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: إعدادات dreaming الخاصة بالذاكرة (تجريبية). راجع [Dreaming](/ar/concepts/dreaming) للمراحل والعتبات. - - `enabled`: مفتاح dreaming الرئيسي (الافتراضي `false`). +- `plugins.entries.memory-core.config.dreaming`: إعدادات dreaming الخاصة بالذاكرة (تجريبية). راجع [Dreaming](/ar/concepts/dreaming) للمراحل والحدود. + - `enabled`: المفتاح الرئيسي لـ dreaming (الافتراضي `false`). - `frequency`: إيقاع cron لكل دورة dreaming كاملة (`"0 3 * * *"` افتراضيًا). - - سياسة المراحل والعتبات هي تفاصيل تنفيذية (وليست مفاتيح إعداد موجّهة للمستخدم). -- يمكن لإضافات Claude bundle المفعّلة أيضًا أن تساهم بقيم Pi الافتراضية المضمّنة من `settings.json`؛ ويطبق OpenClaw هذه القيم كإعدادات وكيل منقّحة، لا كتصحيحات إعداد OpenClaw خام. -- `plugins.slots.memory`: اختر معرّف الإضافة النشطة للذاكرة، أو `"none"` لتعطيل إضافات الذاكرة. -- `plugins.slots.contextEngine`: اختر معرّف الإضافة النشطة لمحرك السياق؛ وتكون القيمة الافتراضية `"legacy"` ما لم تثبت وتحدد محركًا آخر. -- `plugins.installs`: بيانات تثبيت مُدارة عبر CLI يستخدمها `openclaw plugins update`. + - سياسة المراحل والحدود هي تفاصيل تنفيذية (وليست مفاتيح إعدادات موجهة للمستخدم). +- يمكن لإضافات حزم Claude المفعّلة أيضًا المساهمة بافتراضيات Pi مضمّنة من `settings.json`؛ ويطبقها OpenClaw كإعدادات وكيل منقّحة، لا كتصحيحات إعدادات OpenClaw خام. +- `plugins.slots.memory`: اختر معرّف إضافة الذاكرة النشطة، أو `"none"` لتعطيل إضافات الذاكرة. +- `plugins.slots.contextEngine`: اختر معرّف محرك السياق النشط؛ ويكون افتراضيًا `"legacy"` ما لم تثبّت وتحدد محركًا آخر. +- `plugins.installs`: بيانات تعريف التثبيت المُدارة من CLI والمستخدمة بواسطة `openclaw plugins update`. - تتضمن `source` و`spec` و`sourcePath` و`installPath` و`version` و`resolvedName` و`resolvedVersion` و`resolvedSpec` و`integrity` و`shasum` و`resolvedAt` و`installedAt`. - - تعامل مع `plugins.installs.*` على أنها حالة مُدارة؛ ويفضَّل استخدام أوامر CLI بدلًا من التحرير اليدوي. + - تعامل مع `plugins.installs.*` كحالة مُدارة؛ وفضّل أوامر CLI بدل التحرير اليدوي. -راجع [الإضافات](/ar/tools/plugin). +راجع [Plugins](/ar/tools/plugin). --- @@ -2700,8 +2695,8 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - dangerouslyAllowPrivateNetwork: true, // وضع الشبكة الموثوقة الافتراضي - // allowPrivateNetwork: true, // اسم بديل قديم + dangerouslyAllowPrivateNetwork: true, // default trusted-network mode + // allowPrivateNetwork: true, // legacy alias // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, @@ -2727,18 +2722,38 @@ scripts/sandbox-browser-setup.sh # صورة المتصفح الاختياري } ``` -- تقوم `evaluateEnabled: false` بتعطيل `act:evaluate` و`wait --fn`. -- تكون القيمة الافتراضية لـ `ssrfPolicy.dangerouslyAllowPrivateNetwork` هي `true` عندما لا تُعيَّن (نموذج شبكة موثوقة). -- اضبط `ssrfPolicy.dangerouslyAllowPrivateNetwork: false` لتصفح صارم يقتصر على الشبكات العامة. -- في الوضع الصارم، تخضع نقاط نهاية ملفات تعريف CDP البعيدة (`profiles.*.cdpUrl`) لنفس حظر الشبكات الخاصة أثناء فحوصات reachability/discovery. -- يظل `ssrfPolicy.allowPrivateNetwork` مدعومًا كاسم بديل قديم. -- في الوضع الصارم، استخدم `ssrfPolicy.hostnameAllowlist` و`ssrfPolicy.allowedHostnames` للاستثناءات الصريحة. -- تكون الملفات الشخصية البعيدة attach-only (ويتم تعطيل start/stop/reset). -- تقبل `profiles.*.cdpUrl` القيم `http://` و`https://` و`ws://` و`wss://`. - استخدم HTTP(S) عندما تريد أن يكتشف OpenClaw المسار `/json/version`؛ واستخدم WS(S) +- `evaluateEnabled: false` يعطّل `act:evaluate` و`wait --fn`. +- يكون `ssrfPolicy.dangerouslyAllowPrivateNetwork` افتراضيًا `true` عندما لا يُعيّن (نموذج شبكة موثوقة). +- اضبط `ssrfPolicy.dangerouslyAllowPrivateNetwork: false` لتصفح متشدد عام فقط. +- في الوضع المتشدد، تخضع نقاط نهاية ملف CDP البعيد (`profiles.*.cdpUrl`) لنفس حظر الشبكة الخاصة أثناء فحوصات الوصول/الاكتشاف. +- يظل `ssrfPolicy.allowPrivateNetwork` مدعومًا كاسم مستعار قديم. +- في الوضع المتشدد، استخدم `ssrfPolicy.hostnameAllowlist` و`ssrfPolicy.allowedHostnames` للاستثناءات الصريحة. +- تكون الملفات الشخصية البعيدة attach-only (بدء/إيقاف/إعادة تعيين معطلة). +- يقبل `profiles.*.cdpUrl` القيم `http://` و`https://` و`ws://` و`wss://`. + استخدم HTTP(S) عندما تريد من OpenClaw اكتشاف `/json/version`؛ واستخدم WS(S) عندما يوفّر لك المزوّد عنوان DevTools WebSocket مباشرًا. -- تكون ملفات تعريف `existing-session` خاصة بالمضيف فقط وتستخدم Chrome MCP بدلًا من CDP. -- يمكن لملفات تعريف `existing-session` تعيين `userDataDir` لاستهداف ملف تعريف محدد - لمتصفح قائم على Chromium مثل Brave أو Edge. -- تحتفظ ملفات تعريف `existing-session` بقيود مسارات Chrome MCP الحالية: - إجراءات snapshot/ref بدلًا من استهداف محددات \ No newline at end of file +- تكون ملفات `existing-session` محصورة بالمضيف فقط وتستخدم Chrome MCP بدل CDP. +- يمكن لملفات `existing-session` تعيين `userDataDir` لاستهداف ملف + Chromium-based browser محدد مثل Brave أو Edge. +- تحافظ ملفات `existing-session` على قيود مسارات Chrome MCP الحالية: + إجراءات قائمة على snapshot/ref بدل الاستهداف عبر CSS-selector، وخطافات رفع + ملف واحد، ومن دون تجاوزات مهلة مربعات الحوار، ومن دون `wait --load networkidle`، + ومن دون `responsebody` أو تصدير PDF أو اعتراض التنزيلات أو الإجراءات الدفعية. +- تقوم ملفات `openclaw` المحلية المُدارة بتعيين `cdpPort` و`cdpUrl` تلقائيًا؛ لا + تعيّن `cdpUrl` صراحة إلا لـ CDP البعيد. +- ترتيب الاكتشاف التلقائي: المتصفح الافتراضي إذا كان Chromium-based → Chrome → Brave → Edge → Chromium → Chrome Canary. +- خدمة التحكم: loopback فقط (منفذ مشتق من `gateway.port`، الافتراضي `18791`). +- يضيف `extraArgs` رايات تشغيل إضافية إلى بدء Chromium المحلي (على سبيل المثال + `--disable-gpu`، أو تحديد حجم النافذة، أو رايات التصحيح). + +--- + +## واجهة المستخدم + +```json5 +{ + ui: { + seamColor: "#FF4500", + assistant: { + name: "OpenClaw", + avatar: \ No newline at end of file diff --git a/docs/ar/gateway/doctor.md b/docs/ar/gateway/doctor.md index d5bbfc820..938695263 100644 --- a/docs/ar/gateway/doctor.md +++ b/docs/ar/gateway/doctor.md @@ -1,22 +1,22 @@ --- read_when: - - عند إضافة ترحيلات doctor أو تعديلها - - عند تقديم تغييرات كاسرة في الإعدادات + - عند إضافة أو تعديل ترحيلات doctor + - عند إدخال تغييرات جذرية على الإعدادات summary: 'أمر Doctor: فحوصات السلامة، وترحيلات الإعدادات، وخطوات الإصلاح' title: Doctor x-i18n: - generated_at: "2026-04-07T07:18:29Z" + generated_at: "2026-04-08T02:15:41Z" model: gpt-5.4 provider: openai - source_hash: a834dc7aec79c20d17bc23d37fb5f5e99e628d964d55bd8cf24525a7ee57130c + source_hash: 3761a222d9db7088f78215575fa84e5896794ad701aa716e8bf9039a4424dca6 source_path: gateway/doctor.md workflow: 15 --- # Doctor -يُعد `openclaw doctor` أداة الإصلاح + الترحيل في OpenClaw. فهو يصلح -الإعدادات/الحالة القديمة، ويفحص السلامة، ويوفر خطوات إصلاح عملية. +إن `openclaw doctor` هو أداة الإصلاح + الترحيل في OpenClaw. فهو يصلح +الإعدادات/الحالة القديمة، ويتحقق من السلامة، ويوفر خطوات إصلاح قابلة للتنفيذ. ## البدء السريع @@ -30,32 +30,32 @@ openclaw doctor openclaw doctor --yes ``` -اقبل القيم الافتراضية من دون طلب تأكيد (بما في ذلك خطوات إصلاح إعادة التشغيل/الخدمة/sandbox عند الاقتضاء). +اقبل القيم الافتراضية من دون مطالبة (بما في ذلك خطوات إصلاح إعادة التشغيل/الخدمة/العزل عند الاقتضاء). ```bash openclaw doctor --repair ``` -طبّق الإصلاحات الموصى بها من دون طلب تأكيد (الإصلاحات + إعادة التشغيل حيثما كان ذلك آمنًا). +طبّق الإصلاحات الموصى بها من دون مطالبة (الإصلاحات + إعادة التشغيل عندما يكون ذلك آمنًا). ```bash openclaw doctor --repair --force ``` -طبّق أيضًا الإصلاحات المتقدمة (يكتب فوق إعدادات المشرف المخصصة). +طبّق الإصلاحات العدوانية أيضًا (يستبدل إعدادات supervisor المخصصة). ```bash openclaw doctor --non-interactive ``` -شغّل بدون مطالبات وطبّق فقط الترحيلات الآمنة (تطبيع الإعدادات + نقل الحالة على القرص). ويتخطى إجراءات إعادة التشغيل/الخدمة/sandbox التي تتطلب تأكيدًا بشريًا. +شغّل من دون مطالبات وطبّق فقط الترحيلات الآمنة (تطبيع الإعدادات + نقل الحالة على القرص). يتخطى إجراءات إعادة التشغيل/الخدمة/العزل التي تتطلب تأكيدًا بشريًا. تعمل ترحيلات الحالة القديمة تلقائيًا عند اكتشافها. ```bash openclaw doctor --deep ``` -افحص خدمات النظام بحثًا عن تثبيتات Gateway إضافية (launchd/systemd/schtasks). +افحص خدمات النظام لاكتشاف عمليات تثبيت إضافية لـ gateway ‏(launchd/systemd/schtasks). إذا كنت تريد مراجعة التغييرات قبل الكتابة، فافتح ملف الإعدادات أولًا: @@ -65,71 +65,71 @@ cat ~/.openclaw/openclaw.json ## ما الذي يفعله (ملخص) -- تحديث اختياري قبل التشغيل لتثبيتات git (في الوضع التفاعلي فقط). -- فحص حداثة بروتوكول واجهة المستخدم (ويعيد بناء Control UI عندما يكون مخطط البروتوكول أحدث). +- تحديث اختياري قبل التنفيذ لتثبيتات git ‏(تفاعلي فقط). +- فحص حداثة بروتوكول واجهة المستخدم (يعيد بناء Control UI عندما يكون مخطط البروتوكول أحدث). - فحص السلامة + مطالبة بإعادة التشغيل. - ملخص حالة Skills ‏(المؤهلة/المفقودة/المحجوبة) وحالة plugin. - تطبيع الإعدادات للقيم القديمة. - ترحيل إعدادات Talk من حقول `talk.*` القديمة المسطحة إلى `talk.provider` + `talk.providers.`. -- فحوصات ترحيل المتصفح لإعدادات إضافات Chrome القديمة وجاهزية Chrome MCP. -- تحذيرات تجاوز مزود OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). -- فحص متطلبات OAuth TLS الأساسية لملفات تعريف OpenAI Codex OAuth. +- فحوصات ترحيل المتصفح لإعدادات Chrome extension القديمة وجهوزية Chrome MCP. +- تحذيرات تجاوزات موفّر OpenCode ‏(`models.providers.opencode` / `models.providers.opencode-go`). +- تحذيرات حجب Codex OAuth ‏(`models.providers.openai-codex`). +- فحص متطلبات OAuth TLS لملفات OpenAI Codex OAuth الشخصية. - ترحيل الحالة القديمة على القرص (الجلسات/دليل الوكيل/مصادقة WhatsApp). -- ترحيل مفتاح عقد manifest القديم لـ plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). -- ترحيل مخزن cron القديم (`jobId`, `schedule.cron`, حقول delivery/payload ذات المستوى الأعلى، و`provider` في payload، ووظائف webhook الاحتياطية البسيطة `notify: true`). -- فحص ملفات قفل الجلسة وتنظيف الأقفال القديمة. -- فحوصات سلامة الحالة والأذونات (الجلسات، transcripts، دليل الحالة). -- فحوصات أذونات ملف الإعدادات (chmod 600) عند التشغيل محليًا. -- سلامة مصادقة النماذج: يفحص انتهاء صلاحية OAuth، ويمكنه تحديث الرموز التي توشك على الانتهاء، ويعرض حالات التهدئة/التعطيل لملفات تعريف المصادقة. -- اكتشاف دليل workspace إضافي (`~/openclaw`). -- إصلاح صورة sandbox عند تفعيل sandboxing. -- ترحيل الخدمة القديمة واكتشاف Gateway إضافي. -- ترحيل الحالة القديمة لقناة Matrix (في وضع `--fix` / `--repair`). -- فحوصات وقت تشغيل Gateway (الخدمة مثبتة ولكنها لا تعمل؛ ووسم launchd مخزن مؤقتًا). -- تحذيرات حالة القنوات (يتم فحصها من Gateway العامل). -- تدقيق إعدادات المشرف (launchd/systemd/schtasks) مع إصلاح اختياري. +- ترحيل مفتاح عقد plugin manifest القديم (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` ← `contracts`). +- ترحيل مخزن cron القديم (`jobId`, ‏`schedule.cron`, وحقول delivery/payload ذات المستوى الأعلى، و`provider` في payload، ووظائف fallback القديمة البسيطة من نوع `notify: true` webhook). +- فحص ملف قفل الجلسة وتنظيف الأقفال القديمة. +- فحوصات تكامل الحالة والأذونات (الجلسات، والنصوص، ودليل الحالة). +- فحوصات أذونات ملف الإعدادات (`chmod 600`) عند التشغيل محليًا. +- سلامة مصادقة النموذج: يتحقق من انتهاء OAuth، ويمكنه تحديث الرموز الموشكة على الانتهاء، ويبلغ عن حالات auth-profile المهدأة/المعطلة. +- اكتشاف أدلة workspace الإضافية (`~/openclaw`). +- إصلاح صورة sandbox عند تفعيل العزل. +- ترحيل الخدمة القديمة واكتشاف gateway الإضافية. +- ترحيل الحالة القديمة لقناة Matrix ‏(في وضع `--fix` / `--repair`). +- فحوصات وقت تشغيل Gateway ‏(الخدمة مثبتة ولكنها لا تعمل؛ ووسم launchd المخزن مؤقتًا). +- تحذيرات حالة القناة (يتم فحصها من gateway الجاري تشغيله). +- تدقيق إعدادات supervisor ‏(launchd/systemd/schtasks) مع إصلاح اختياري. - فحوصات أفضل الممارسات لوقت تشغيل Gateway ‏(Node مقابل Bun، ومسارات مديري الإصدارات). - تشخيص تعارض منفذ Gateway ‏(الافتراضي `18789`). - تحذيرات أمنية لسياسات DM المفتوحة. -- فحوصات مصادقة Gateway لوضع الرمز المحلي (يوفر إنشاء رمز عند عدم وجود مصدر رمز؛ ولا يكتب فوق إعدادات token SecretRef). +- فحوصات مصادقة Gateway لوضع الرمز المحلي (يعرض توليد رمز عند عدم وجود مصدر للرمز؛ ولا يستبدل إعدادات token SecretRef). - فحص systemd linger على Linux. -- فحص حجم ملف bootstrap في workspace (تحذيرات الاقتطاع/الاقتراب من الحد لملفات السياق). +- فحص حجم ملف bootstrap في workspace ‏(تحذيرات الاقتطاع/الاقتراب من الحد لملفات السياق). - فحص حالة shell completion والتثبيت/الترقية التلقائيين. -- فحص جاهزية مزود embedding الخاص ببحث الذاكرة (نموذج محلي، أو مفتاح API بعيد، أو ملف QMD تنفيذي). +- فحص جهوزية موفّر embedding لبحث الذاكرة (نموذج محلي، أو مفتاح API بعيد، أو ملف QMD تنفيذي). - فحوصات تثبيت المصدر (عدم تطابق pnpm workspace، وغياب أصول UI، وغياب ملف tsx التنفيذي). -- يكتب الإعدادات المحدَّثة + بيانات wizard الوصفية. +- يكتب الإعدادات المحدّثة + بيانات wizard الوصفية. -## السلوك المفصل والمبررات +## السلوك التفصيلي والمبررات ### 0) تحديث اختياري (تثبيتات git) -إذا كان هذا مستودع git checkout وكان doctor يعمل في الوضع التفاعلي، فسيعرض +إذا كان هذا مستخرج git وكان doctor يعمل في وضع تفاعلي، فإنه يعرض التحديث (fetch/rebase/build) قبل تشغيل doctor. ### 1) تطبيع الإعدادات -إذا احتوت الإعدادات على أشكال قيم قديمة (على سبيل المثال `messages.ackReaction` -من دون تجاوز خاص بالقناة)، يقوم doctor بتطبيعها إلى -المخطط الحالي. +إذا كانت الإعدادات تحتوي على أشكال قيم قديمة (مثل `messages.ackReaction` +من دون تجاوز خاص بالقناة)، فإن doctor يطبعها إلى المخطط الحالي. -ويشمل ذلك حقول Talk القديمة المسطحة. إعدادات Talk العامة الحالية هي +ويتضمن ذلك حقول Talk القديمة المسطحة. إعداد Talk العام الحالي هو `talk.provider` + `talk.providers.`. ويعيد doctor كتابة -أشكال `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / -`talk.apiKey` القديمة إلى خريطة المزود. +الأشكال القديمة `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / +`talk.apiKey` إلى خريطة الموفّر. ### 2) ترحيلات مفاتيح الإعدادات القديمة -عندما تحتوي الإعدادات على مفاتيح مهجورة، ترفض الأوامر الأخرى التشغيل وتطلب +عندما تحتوي الإعدادات على مفاتيح متقادمة، ترفض الأوامر الأخرى التشغيل وتطلب منك تشغيل `openclaw doctor`. سيقوم Doctor بما يلي: -- شرح مفاتيح الإعدادات القديمة التي تم العثور عليها. -- عرض الترحيل الذي طبقه. -- إعادة كتابة `~/.openclaw/openclaw.json` بالمخطط المحدّث. +- يشرح أي مفاتيح قديمة تم العثور عليها. +- يعرض الترحيل الذي طبقه. +- يعيد كتابة `~/.openclaw/openclaw.json` بالمخطط المحدّث. -كما يشغّل Gateway ترحيلات doctor تلقائيًا عند بدء التشغيل عندما يكتشف -تنسيق إعدادات قديمًا، بحيث يتم إصلاح الإعدادات القديمة بدون تدخل يدوي. +كما أن Gateway يشغّل ترحيلات doctor تلقائيًا عند بدء التشغيل عندما يكتشف +تنسيق إعدادات قديمًا، بحيث تُصلح الإعدادات القديمة من دون تدخل يدوي. تتم معالجة ترحيلات مخزن وظائف Cron بواسطة `openclaw doctor --fix`. الترحيلات الحالية: @@ -141,7 +141,7 @@ cat ~/.openclaw/openclaw.json - `routing.queue` → `messages.queue` - `routing.bindings` → `bindings` في المستوى الأعلى - `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default` -- `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` القديمة → `talk.provider` + `talk.providers.` +- القديم `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.` - `routing.agentToAgent` → `tools.agentToAgent` - `routing.transcribeAudio` → `tools.media.audio.models` - `messages.tts.` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `messages.tts.providers.` @@ -154,348 +154,356 @@ cat ~/.openclaw/openclaw.json - `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*` - `bindings[].match.accountID` → `bindings[].match.accountId` -- بالنسبة إلى القنوات التي تحتوي على `accounts` مسماة مع بقاء قيم قناة ذات مستوى أعلى مخصصة لحساب واحد، انقل تلك القيم ذات النطاق الخاص بالحساب إلى الحساب المُرقّى المختار لتلك القناة (`accounts.default` لمعظم القنوات؛ ويمكن لـ Matrix الحفاظ على هدف مسمى/افتراضي موجود ومطابق) +- بالنسبة للقنوات التي تحتوي على `accounts` مسماة ولكن لا تزال فيها قيم قنوات ذات حساب واحد على المستوى الأعلى، انقل تلك القيم ذات النطاق الخاص بالحساب إلى الحساب المُرقّى المختار لتلك القناة (`accounts.default` لمعظم القنوات؛ ويمكن لـ Matrix الاحتفاظ بهدف مسمى/افتراضي مطابق موجود) - `identity` → `agents.list[].identity` - `agent.*` → `agents.defaults` + `tools.*` ‏(tools/elevated/exec/sandbox/subagents) - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks` - `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - `browser.profiles.*.driver: "extension"` → `"existing-session"` -- إزالة `browser.relayBindHost` (إعداد relay قديم للإضافة) +- إزالة `browser.relayBindHost` ‏(إعداد relay قديم للامتداد) تتضمن تحذيرات Doctor أيضًا إرشادات حول الحساب الافتراضي للقنوات متعددة الحسابات: -- إذا تم ضبط إدخالين أو أكثر ضمن `channels..accounts` بدون `channels..defaultAccount` أو `accounts.default`، فسيحذر doctor من أن توجيه fallback قد يختار حسابًا غير متوقع. -- إذا تم ضبط `channels..defaultAccount` على معرّف حساب غير معروف، فسيحذر doctor ويعرض معرّفات الحسابات المضبوطة. +- إذا تم إعداد إدخالين أو أكثر في `channels..accounts` من دون `channels..defaultAccount` أو `accounts.default`، فإن doctor يحذر من أن التوجيه الاحتياطي قد يختار حسابًا غير متوقع. +- إذا تم تعيين `channels..defaultAccount` إلى معرّف حساب غير معروف، فإن doctor يحذر ويسرد معرّفات الحسابات المهيأة. -### 2b) تجاوزات مزود OpenCode +### 2b) تجاوزات موفّر OpenCode إذا كنت قد أضفت `models.providers.opencode` أو `opencode-zen` أو `opencode-go` -يدويًا، فإنه يتجاوز كتالوج OpenCode المضمّن من `@mariozechner/pi-ai`. -وقد يؤدي ذلك إلى فرض النماذج على API غير صحيح أو تصفير التكاليف. يحذّر doctor حتى -تتمكن من إزالة التجاوز واستعادة توجيه API والتكاليف لكل نموذج. +يدويًا، فإنه يتجاوز كتالوج OpenCode المدمج القادم من `@mariozechner/pi-ai`. +وقد يفرض ذلك النماذج على API خاطئ أو يصفر التكاليف. ويحذر doctor لكي +تزيل التجاوز وتستعيد توجيه API + التكاليف لكل نموذج. -### 2c) ترحيل المتصفح وجاهزية Chrome MCP +### 2c) ترحيل المتصفح وجهوزية Chrome MCP -إذا كانت إعدادات متصفحك لا تزال تشير إلى مسار إضافة Chrome الذي تمت إزالته، فإن doctor -يقوم بتطبيعها إلى نموذج الإرفاق الحالي لـ Chrome MCP المحلي على المضيف: +إذا كانت إعدادات متصفحك لا تزال تشير إلى مسار Chrome extension الذي تمت إزالته، فإن doctor +يطبعها إلى نموذج الإرفاق الحالي المحلي للمضيف Chrome MCP: - `browser.profiles.*.driver: "extension"` تصبح `"existing-session"` - تتم إزالة `browser.relayBindHost` -كما يدقّق doctor في مسار Chrome MCP المحلي على المضيف عندما تستخدم `defaultProfile: -"user"` أو ملف تعريف `existing-session` مضبوط: +كما يقوم doctor بتدقيق المسار المحلي للمضيف Chrome MCP عندما تستخدم `defaultProfile: +"user"` أو ملف `existing-session` شخصي مهيأ: -- يفحص ما إذا كان Google Chrome مثبتًا على نفس المضيف لملفات التعريف - ذات الاتصال التلقائي الافتراضي -- يفحص إصدار Chrome المكتشف ويحذر إذا كان أقل من Chrome 144 -- يذكّرك بتمكين remote debugging في صفحة inspect الخاصة بالمتصفح (على - سبيل المثال `chrome://inspect/#remote-debugging` أو `brave://inspect/#remote-debugging` +- يتحقق مما إذا كان Google Chrome مثبتًا على المضيف نفسه لملفات + الاتصال التلقائي الافتراضية +- يتحقق من إصدار Chrome المكتشف ويحذر عندما يكون أقل من Chrome 144 +- يذكّرك بتمكين التصحيح عن بُعد في صفحة فحص المتصفح (مثل + `chrome://inspect/#remote-debugging` أو `brave://inspect/#remote-debugging` أو `edge://inspect/#remote-debugging`) -لا يستطيع doctor تمكين الإعداد في Chrome نيابةً عنك. لا يزال Chrome MCP المحلي على المضيف +لا يمكن لـ Doctor تمكين الإعداد من جهة Chrome نيابةً عنك. ولا يزال Chrome MCP المحلي للمضيف يتطلب: - متصفحًا قائمًا على Chromium بإصدار 144+ على مضيف gateway/node -- تشغيل المتصفح محليًا -- تمكين remote debugging في ذلك المتصفح -- الموافقة على مطالبة الإذن الأولى بالإرفاق في المتصفح +- أن يكون المتصفح قيد التشغيل محليًا +- تمكين التصحيح عن بُعد في ذلك المتصفح +- الموافقة على أول مطالبة موافقة على الإرفاق في المتصفح -الجاهزية هنا تتعلق فقط بمتطلبات الإرفاق المحلي. يحتفظ existing-session -بقيود مسار Chrome MCP الحالية؛ أما المسارات المتقدمة مثل `responsebody` وتصدير PDF -واعتراض التنزيلات والإجراءات المجمعة فما تزال تتطلب -متصفحًا مُدارًا أو ملف تعريف CDP خام. +الجهوزية هنا تتعلق فقط بمتطلبات الإرفاق المحلي. ولا يزال existing-session +يحتفظ بحدود مسارات Chrome MCP الحالية؛ أما المسارات المتقدمة مثل `responsebody` وتصدير PDF +واعتراض التنزيلات وإجراءات الدُفعات فلا تزال تتطلب +متصفحًا مُدارًا أو ملف CDP شخصيًا خامًا. -لا ينطبق هذا الفحص على تدفقات Docker أو sandbox أو remote-browser أو غيرها من -التدفقات بدون واجهة. إذ تواصل تلك استخدام CDP الخام. +لا ينطبق هذا الفحص **على** تدفقات Docker أو sandbox أو remote-browser أو التدفقات +الأخرى عديمة الواجهة. فهي تواصل استخدام CDP الخام. -### 2d) متطلبات OAuth TLS الأساسية +### 2d) متطلبات OAuth TLS المسبقة -عندما يتم ضبط ملف تعريف OpenAI Codex OAuth، يقوم doctor بفحص نقطة -تفويض OpenAI للتحقق من أن مكدس TLS المحلي في Node/OpenSSL يمكنه -التحقق من سلسلة الشهادات. إذا فشل الفحص بخطأ في الشهادة (على -سبيل المثال `UNABLE_TO_GET_ISSUER_CERT_LOCALLY` أو شهادة منتهية أو شهادة موقعة ذاتيًا)، -فسيعرض doctor إرشادات إصلاح خاصة بالمنصة. على macOS مع Node من Homebrew، -يكون الإصلاح عادةً `brew postinstall ca-certificates`. ومع `--deep`، يُشغَّل الفحص -حتى لو كانت حالة Gateway سليمة. +عندما يتم إعداد ملف OpenAI Codex OAuth شخصي، يقوم doctor بفحص نقطة نهاية +التفويض الخاصة بـ OpenAI للتحقق من أن مكدس TLS المحلي في Node/OpenSSL يمكنه +التحقق من سلسلة الشهادات. إذا فشل الفحص بسبب خطأ في الشهادة (مثل +`UNABLE_TO_GET_ISSUER_CERT_LOCALLY` أو شهادة منتهية أو شهادة موقعة ذاتيًا)، +فإن doctor يطبع إرشادات إصلاح خاصة بالنظام. على macOS مع Node من Homebrew، +يكون الإصلاح عادةً `brew postinstall ca-certificates`. ومع `--deep`، يعمل +الفحص حتى لو كانت gateway سليمة. -### 3) ترحيلات الحالة القديمة (تخطيط القرص) +### 2c) تجاوزات موفّر Codex OAuth -يمكن لـ Doctor ترحيل تخطيطات القرص القديمة إلى البنية الحالية: +إذا كنت قد أضفت سابقًا إعدادات نقل OpenAI القديمة ضمن +`models.providers.openai-codex`، فقد تحجب مسار +موفّر Codex OAuth المدمج الذي تستخدمه الإصدارات الأحدث تلقائيًا. ويحذر doctor عند رؤيته +هذه الإعدادات القديمة للنقل إلى جانب Codex OAuth لكي تتمكن من إزالة أو إعادة كتابة +تجاوز النقل القديم واستعادة سلوك التوجيه/الاحتياط المدمج. +لا تزال البروكسيات المخصصة وتجاوزات الترويسات فقط مدعومة ولا تؤدي إلى هذا التحذير. -- مخزن الجلسات + transcripts: +### 3) ترحيلات الحالة القديمة (بنية القرص) + +يمكن لـ Doctor ترحيل البُنى القديمة على القرص إلى البنية الحالية: + +- مخزن الجلسات + النصوص: - من `~/.openclaw/sessions/` إلى `~/.openclaw/agents//sessions/` - دليل الوكيل: - من `~/.openclaw/agent/` إلى `~/.openclaw/agents//agent/` - حالة مصادقة WhatsApp ‏(Baileys): - من `~/.openclaw/credentials/*.json` القديمة (باستثناء `oauth.json`) - - إلى `~/.openclaw/credentials/whatsapp//...` (معرّف الحساب الافتراضي: `default`) + - إلى `~/.openclaw/credentials/whatsapp//...` ‏(معرّف الحساب الافتراضي: `default`) -هذه الترحيلات تُنفَّذ بأفضل جهد وهي idempotent؛ وسيصدر doctor تحذيرات عندما -يترك أي مجلدات قديمة كنسخ احتياطية. كما يقوم Gateway/CLI بترحيل -الجلسات القديمة + دليل الوكيل تلقائيًا عند بدء التشغيل لكي تنتقل -السجلات/المصادقة/النماذج إلى مسار كل وكيل من دون تشغيل doctor يدويًا. أما مصادقة WhatsApp -فيتم ترحيلها عمدًا فقط عبر `openclaw doctor`. كما أن تطبيع provider/provider-map لـ Talk -يقارن الآن بالمساواة البنيوية، لذلك لم تعد الفروقات الناتجة فقط عن ترتيب المفاتيح -تسبب تغييرات `doctor --fix` متكررة عديمة الأثر. +هذه الترحيلات تبذل أفضل جهد وهي قابلة للتكرار بأمان؛ وسيُصدر doctor تحذيرات عندما +يترك أي مجلدات قديمة خلفه كنسخ احتياطية. كما أن Gateway/CLI يرحّلان تلقائيًا +الجلسات القديمة + دليل الوكيل عند بدء التشغيل بحيث تهبط السجلات/المصادقة/النماذج في +المسار الخاص بكل وكيل من دون تشغيل doctor يدويًا. أما مصادقة WhatsApp فمقصود +أن تُرحّل فقط عبر `openclaw doctor`. كما أن تطبيع موفّر Talk/خريطة الموفّرين +يقارن الآن بالمساواة البنيوية، لذلك لم تعد الفروق في ترتيب المفاتيح فقط +تؤدي إلى تغييرات متكررة عديمة الأثر في `doctor --fix`. -### 3a) ترحيلات manifest القديمة لـ plugin +### 3a) ترحيلات plugin manifest القديمة -يفحص Doctor جميع manifest الخاصة بالـ plugin المثبتة بحثًا عن مفاتيح -الإمكانات القديمة ذات المستوى الأعلى (`speechProviders`, `realtimeTranscriptionProviders`, +يفحص Doctor جميع plugin manifests المثبتة بحثًا عن مفاتيح +القدرات العلوية المتقادمة (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, -`webSearchProviders`). وعند العثور عليها، يعرض نقلها إلى الكائن `contracts` -وإعادة كتابة ملف manifest في مكانه. هذا الترحيل idempotent؛ -وإذا كان المفتاح `contracts` يحتوي بالفعل على القيم نفسها، تتم إزالة -المفتاح القديم من دون تكرار البيانات. +`webSearchProviders`). وعند العثور عليها، يعرض نقلها إلى كائن `contracts` +وإعادة كتابة ملف manifest في مكانه. هذا الترحيل قابل للتكرار بأمان؛ +إذا كان مفتاح `contracts` يحتوي بالفعل على القيم نفسها، فإن المفتاح القديم يُزال +من دون تكرار البيانات. ### 3b) ترحيلات مخزن cron القديمة -يفحص Doctor أيضًا مخزن وظائف cron ‏(`~/.openclaw/cron/jobs.json` افتراضيًا، -أو `cron.store` عند التجاوز) بحثًا عن أشكال وظائف قديمة ما يزال المجدول +يتحقق Doctor أيضًا من مخزن وظائف cron ‏(`~/.openclaw/cron/jobs.json` افتراضيًا، +أو `cron.store` عند تجاوزه) بحثًا عن أشكال وظائف قديمة لا يزال المجدول يقبلها للتوافق. -تتضمن عمليات تنظيف cron الحالية: +تنظيفات cron الحالية تشمل: - `jobId` → `id` - `schedule.cron` → `schedule.expr` - حقول payload ذات المستوى الأعلى (`message`, `model`, `thinking`, ...) → `payload` - حقول delivery ذات المستوى الأعلى (`deliver`, `channel`, `to`, `provider`, ...) → `delivery` -- الأسماء البديلة للتسليم `provider` في payload → `delivery.channel` صريح -- وظائف webhook الاحتياطية القديمة البسيطة `notify: true` → `delivery.mode="webhook"` صريح مع `delivery.to=cron.webhook` +- أسماء delivery البديلة في `provider` داخل payload → `delivery.channel` صريح +- وظائف fallback القديمة البسيطة من نوع `notify: true` webhook → `delivery.mode="webhook"` صريح مع `delivery.to=cron.webhook` -لا يرحّل Doctor تلقائيًا وظائف `notify: true` إلا عندما يتمكن من ذلك -من دون تغيير السلوك. وإذا جمعت وظيفة ما بين fallback notify قديم ووضع -delivery موجود ليس webhook، فسيحذر doctor ويترك تلك الوظيفة للمراجعة اليدوية. +لا يرحّل Doctor وظائف `notify: true` تلقائيًا إلا عندما يستطيع فعل ذلك من دون +تغيير السلوك. وإذا كانت الوظيفة تجمع بين fallback الإشعار القديم ووضع +delivery موجود غير webhook، فإن doctor يحذر ويترك تلك الوظيفة للمراجعة اليدوية. ### 3c) تنظيف قفل الجلسة -يفحص Doctor كل دليل جلسات وكلاء بحثًا عن ملفات write-lock قديمة — وهي ملفات -تُترك خلفها عندما تنتهي الجلسة بشكل غير طبيعي. ولكل ملف قفل يعثر عليه، يعرض: -المسار وPID وما إذا كان PID ما يزال حيًا وعمر القفل وما إذا كان -يُعتبر قديمًا (PID ميت أو أقدم من 30 دقيقة). في وضع `--fix` / `--repair` -يقوم بإزالة ملفات القفل القديمة تلقائيًا؛ وإلا فإنه يطبع ملاحظة +يفحص Doctor كل دليل جلسات وكلاء بحثًا عن ملفات write-lock قديمة — +أي الملفات التي تُترك خلفها عندما تخرج الجلسة بشكل غير طبيعي. ولكل ملف قفل يعثر عليه يبلغ عن: +المسار، وPID، وما إذا كان PID ما يزال حيًا، وعمر القفل، وما إذا كان +يُعد قديمًا (PID ميت أو أقدم من 30 دقيقة). وفي وضع `--fix` / `--repair` +فإنه يزيل ملفات القفل القديمة تلقائيًا؛ وإلا فإنه يطبع ملاحظة ويطلب منك إعادة التشغيل باستخدام `--fix`. -### 4) فحوصات سلامة الحالة (استمرارية الجلسة، والتوجيه، والسلامة) +### 4) فحوصات تكامل الحالة (استمرارية الجلسة، والتوجيه، والسلامة) -يُعد دليل الحالة بمثابة جذع الدماغ التشغيلي. فإذا اختفى، ستفقد -الجلسات وبيانات الاعتماد والسجلات والإعدادات (ما لم تكن لديك نسخ احتياطية في مكان آخر). +دليل الحالة هو الجذع التشغيلي الأساسي. وإذا اختفى، فستفقد +الجلسات، وبيانات الاعتماد، والسجلات، والإعدادات (ما لم تكن لديك نسخ احتياطية في مكان آخر). -يفحص Doctor ما يلي: +يتحقق Doctor من: -- **دليل الحالة مفقود**: يحذر من فقدان الحالة الكارثي، ويطلب إعادة إنشاء - الدليل، ويذكّرك بأنه لا يستطيع استعادة البيانات المفقودة. -- **أذونات دليل الحالة**: يتحقق من قابلية الكتابة؛ ويعرض إصلاح الأذونات +- **غياب دليل الحالة**: يحذر من فقدان كارثي للحالة، ويطلب إعادة إنشاء + الدليل، ويذكرك بأنه لا يستطيع استعادة البيانات المفقودة. +- **أذونات دليل الحالة**: يتحقق من إمكانية الكتابة؛ ويعرض إصلاح الأذونات (ويصدر تلميح `chown` عند اكتشاف عدم تطابق المالك/المجموعة). -- **دليل حالة macOS المتزامن سحابيًا**: يحذر عندما تُحل الحالة تحت iCloud Drive +- **دليل حالة متزامن عبر السحابة على macOS**: يحذر عندما تُحل الحالة تحت iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) أو - `~/Library/CloudStorage/...` لأن المسارات المدعومة بالمزامنة قد تسبب إدخال/إخراج أبطأ - وسباقات قفل/مزامنة. -- **دليل حالة Linux على SD أو eMMC**: يحذر عندما تُحل الحالة إلى - مصدر تركيب `mmcblk*`، لأن الإدخال/الإخراج العشوائي المدعوم بـ SD أو eMMC قد يكون أبطأ - ويتسبب في اهتراء أسرع مع كتابات الجلسات وبيانات الاعتماد. -- **أدلة الجلسات مفقودة**: مطلوب وجود `sessions/` ودليل مخزن الجلسة من - أجل حفظ السجل وتجنب أعطال `ENOENT`. -- **عدم تطابق transcript**: يحذر عندما تحتوي إدخالات الجلسات الحديثة على - ملفات transcript مفقودة. -- **main session “1-line JSONL”**: يضع علامة عند احتواء transcript الرئيسي على سطر واحد فقط + `~/Library/CloudStorage/...` لأن المسارات المدعومة بالمزامنة قد تسبب بطء I/O + وسباقات في القفل/المزامنة. +- **دليل حالة على SD أو eMMC في Linux**: يحذر عندما تُحل الحالة إلى مصدر ربط `mmcblk*`، + لأن I/O العشوائي المدعوم ببطاقات SD أو eMMC قد يكون أبطأ ويتعرض للتآكل + بشكل أسرع تحت عمليات كتابة الجلسات وبيانات الاعتماد. +- **غياب أدلة الجلسات**: إن `sessions/` ودليل مخزن الجلسات + مطلوبان لحفظ السجل وتجنب أعطال `ENOENT`. +- **عدم تطابق النصوص**: يحذر عندما تكون إدخالات الجلسات الحديثة تفتقد + إلى ملفات النصوص. +- **الجلسة الرئيسية "JSONL من سطر واحد"**: يعلّم عندما يحتوي النص الرئيسي على سطر واحد فقط (السجل لا يتراكم). - **أدلة حالة متعددة**: يحذر عند وجود عدة مجلدات `~/.openclaw` عبر - أدلة home أو عندما يشير `OPENCLAW_STATE_DIR` إلى مكان آخر (قد ينقسم السجل بين التثبيتات). -- **تذكير الوضع البعيد**: إذا كان `gateway.mode=remote`، يذكّرك doctor بتشغيله - على المضيف البعيد (فالحالة موجودة هناك). + الأدلة المنزلية أو عندما يشير `OPENCLAW_STATE_DIR` إلى مكان آخر (قد ينقسم السجل + بين التثبيتات). +- **تذكير الوضع البعيد**: إذا كان `gateway.mode=remote`، يذكرك doctor بتشغيله + على المضيف البعيد (الحالة موجودة هناك). - **أذونات ملف الإعدادات**: يحذر إذا كان `~/.openclaw/openclaw.json` - قابلاً للقراءة من قبل المجموعة/العالم ويعرض تشديده إلى `600`. + قابلاً للقراءة من المجموعة/العالم ويعرض تشديده إلى `600`. -### 5) سلامة مصادقة النماذج (انتهاء OAuth) +### 5) سلامة مصادقة النموذج (انتهاء OAuth) -يفحص Doctor ملفات تعريف OAuth في مخزن المصادقة، ويحذر عندما تكون -الرموز على وشك الانتهاء/منتهية، ويمكنه تحديثها عندما يكون ذلك آمنًا. وإذا كان ملف -تعريف Anthropic OAuth/token قديمًا، فإنه يقترح مفتاح Anthropic API أو -مسار setup-token الخاص بـ Anthropic. +يفحص Doctor ملفات OAuth الشخصية في مخزن المصادقة، ويحذر عندما تكون الرموز +على وشك الانتهاء/منتهية، ويمكنه تحديثها عندما يكون ذلك آمنًا. وإذا كان ملف +Anthropic OAuth/token الشخصي قديمًا، فإنه يقترح مفتاح Anthropic API أو +مسار إعداد رمز Anthropic. لا تظهر مطالبات التحديث إلا عند التشغيل تفاعليًا (TTY)؛ أما `--non-interactive` فيتخطى محاولات التحديث. -كما يعرض Doctor أيضًا ملفات تعريف المصادقة غير القابلة للاستخدام مؤقتًا بسبب: +كما يبلغ Doctor عن ملفات المصادقة الشخصية التي تكون غير قابلة للاستخدام مؤقتًا بسبب: -- فترات تهدئة قصيرة (حدود المعدل/انقضاء المهلة/فشل المصادقة) +- فترات تهدئة قصيرة (حدود المعدل/انتهاء المهلة/فشل المصادقة) - تعطيلات أطول (فشل الفوترة/الرصيد) ### 6) التحقق من نموذج Hooks إذا كان `hooks.gmail.model` مضبوطًا، فإن doctor يتحقق من مرجع النموذج مقابل -الكتالوج وقائمة السماح ويحذر عندما يتعذر حله أو لا يُسمح به. +الكتالوج وقائمة السماح ويحذر عندما لا يمكن حله أو يكون غير مسموح به. ### 7) إصلاح صورة sandbox -عند تفعيل sandboxing، يفحص doctor صور Docker ويعرض بناءها أو +عند تفعيل العزل، يتحقق doctor من صور Docker ويعرض إنشاءها أو التبديل إلى الأسماء القديمة إذا كانت الصورة الحالية مفقودة. -### 7b) تبعيات وقت التشغيل للـ plugin المضمّنة +### 7b) تبعيات وقت تشغيل plugin المضمنة -يتحقق Doctor من وجود تبعيات وقت التشغيل للـ plugin المضمّنة (على سبيل المثال -حزم وقت تشغيل plugin الخاصة بـ Discord) في جذر تثبيت OpenClaw. -إذا كان أي منها مفقودًا، فسيبلغ doctor عن الحزم ويثبتها في -وضع `openclaw doctor --fix` / `openclaw doctor --repair`. +يتحقق Doctor من وجود تبعيات وقت تشغيل plugin المضمنة (مثل +حزم وقت تشغيل Discord plugin) في جذر تثبيت OpenClaw. +إذا كان أي منها مفقودًا، فإن doctor يبلغ عن الحزم ويثبتها في وضع +`openclaw doctor --fix` / `openclaw doctor --repair`. ### 8) ترحيلات خدمة Gateway وتلميحات التنظيف -يكتشف Doctor خدمات Gateway القديمة (launchd/systemd/schtasks) و +يكتشف Doctor خدمات gateway القديمة (launchd/systemd/schtasks) و يعرض إزالتها وتثبيت خدمة OpenClaw باستخدام منفذ gateway الحالي. -كما يمكنه أيضًا فحص الخدمات الإضافية الشبيهة بـ gateway وطباعة تلميحات للتنظيف. -تُعد خدمات OpenClaw gateway المسماة باسم ملف التعريف خدمات من الدرجة الأولى ولا -يتم وضع علامة "إضافية" عليها. +كما يمكنه فحص الخدمات الإضافية الشبيهة بـ gateway وطباعة تلميحات تنظيف. +تُعد خدمات OpenClaw gateway المسماة بحسب الملف الشخصي خدمات من الدرجة الأولى ولا +تُعلَّم على أنها "إضافية". ### 8b) ترحيل Matrix عند بدء التشغيل -عندما يكون لدى حساب قناة Matrix ترحيل حالة قديم معلّق أو قابل للتنفيذ، +عندما يكون لدى حساب قناة Matrix ترحيل حالة قديم معلق أو قابل للتنفيذ، فإن doctor (في وضع `--fix` / `--repair`) ينشئ لقطة قبل الترحيل ثم -يشغّل خطوات الترحيل بأفضل جهد: ترحيل حالة Matrix القديمة وإعداد -الحالة المشفرة القديمة. كلتا الخطوتين غير قاتلتين؛ يتم تسجيل الأخطاء -ويستمر بدء التشغيل. أما في وضع القراءة فقط (`openclaw doctor` بدون `--fix`) فسيتم +يشغّل خطوات الترحيل بأفضل جهد: ترحيل حالة Matrix القديمة وإعداد الحالة المشفرة القديمة. +كلتا الخطوتين غير قاتلتين؛ يتم تسجيل الأخطاء ويستمر بدء التشغيل. أما في وضع القراءة فقط (`openclaw doctor` من دون `--fix`) فيتم تخطي هذا الفحص بالكامل. ### 9) التحذيرات الأمنية -يصدر Doctor تحذيرات عندما يكون أحد الموفرين مفتوحًا على الرسائل الخاصة DM بدون قائمة سماح، أو -عندما تكون إحدى السياسات مضبوطة بطريقة خطرة. +يصدر Doctor تحذيرات عندما يكون موفّر ما مفتوحًا لرسائل DM من دون allowlist، أو +عندما تكون سياسة ما مهيأة بطريقة خطرة. ### 10) systemd linger ‏(Linux) -إذا كان يعمل كخدمة مستخدم systemd، يتأكد doctor من تفعيل lingering حتى -يبقى gateway يعمل بعد تسجيل الخروج. +إذا كان التشغيل يتم كخدمة مستخدم systemd، فإن doctor يضمن تمكين lingering بحيث +تبقى gateway حية بعد تسجيل الخروج. ### 11) حالة workspace ‏(Skills وplugins والأدلة القديمة) -يطبع Doctor ملخصًا لحالة workspace للوكيل الافتراضي: +يطبع Doctor ملخصًا عن حالة workspace للوكيل الافتراضي: -- **حالة Skills**: عدد Skills المؤهلة، وذات المتطلبات المفقودة، والمحجوبة بقائمة السماح. +- **حالة Skills**: يحسب Skills المؤهلة وتلك التي تفتقد المتطلبات وتلك المحجوبة بقائمة السماح. - **أدلة workspace القديمة**: يحذر عند وجود `~/openclaw` أو أدلة workspace قديمة أخرى - إلى جانب workspace الحالية. -- **حالة plugin**: عدد plugins المحملة/المعطلة/التي بها أخطاء؛ ويسرد معرّفات plugin لأي - أخطاء؛ ويعرض إمكانات bundle plugin. -- **تحذيرات توافق plugin**: يضع علامة على plugins التي لديها مشكلات توافق مع + إلى جانب workspace الحالي. +- **حالة plugin**: يحسب plugins المحملة/المعطلة/ذات الأخطاء؛ ويسرد معرفات plugin لأي + أخطاء؛ ويبلغ عن قدرات bundle plugin. +- **تحذيرات توافق plugin**: يعلّم plugins التي لديها مشكلات توافق مع وقت التشغيل الحالي. -- **تشخيصات plugin**: يعرض أي تحذيرات أو أخطاء وقت التحميل صادرة عن - plugin registry. +- **تشخيصات plugin**: يعرض أي تحذيرات أو أخطاء وقت التحميل صادرة من + سجل plugin. ### 11b) حجم ملف Bootstrap -يفحص Doctor ما إذا كانت ملفات bootstrap الخاصة بـ workspace (على سبيل المثال `AGENTS.md`، -أو `CLAUDE.md`، أو ملفات سياق أخرى يتم حقنها) قريبة من -الميزانية المكوّنة للأحرف أو تتجاوزها. ويعرض لكل ملف عدد الأحرف الخام مقابل المحقونة، ونسبة -الاقتطاع، وسبب الاقتطاع (`max/file` أو `max/total`)، وإجمالي الأحرف -المحقونة كنسبة من إجمالي الميزانية. وعندما يتم اقتطاع الملفات أو تكون قريبة من +يتحقق Doctor مما إذا كانت ملفات bootstrap في workspace ‏(مثل `AGENTS.md`, +و`CLAUDE.md`، أو ملفات السياق الأخرى المحقونة) قريبة من حد ميزانية الأحرف +أو متجاوزه. ويبلغ لكل ملف عن عدد الأحرف الخام مقابل المحقون، ونسبة الاقتطاع، +وسبب الاقتطاع (`max/file` أو `max/total`)، وإجمالي الأحرف المحقونة +بوصفها جزءًا من الميزانية الكلية. وعندما تكون الملفات مقتطعة أو قريبة من الحد، يطبع doctor نصائح لضبط `agents.defaults.bootstrapMaxChars` و`agents.defaults.bootstrapTotalMaxChars`. ### 11c) Shell completion -يفحص Doctor ما إذا كان tab completion مثبتًا للـ shell الحالي +يتحقق Doctor مما إذا كان إكمال التبويب مثبتًا للصدفة الحالية (zsh أو bash أو fish أو PowerShell): -- إذا كان ملف تعريف shell يستخدم نمط completion ديناميكيًا بطيئًا - (`source <(openclaw completion ...)`)، فإن doctor يرقّيه إلى - متغير الملف المخزن مؤقتًا والأسرع. -- إذا كان completion مضبوطًا في ملف التعريف لكن ملف cache مفقودًا، - فإن doctor يعيد إنشاء cache تلقائيًا. -- إذا لم يكن completion مضبوطًا على الإطلاق، فسيعرض doctor تثبيته - (في الوضع التفاعلي فقط؛ ويتم التخطي مع `--non-interactive`). +- إذا كان ملف shell الشخصي يستخدم نمط إكمال ديناميكي بطيء + (`source <(openclaw completion ...)`)، فإن doctor يرقّيه إلى الصيغة + الأسرع المعتمدة على الملف المخزن مؤقتًا. +- إذا كان الإكمال مهيأ في الملف الشخصي ولكن ملف التخزين المؤقت مفقودًا، + فإن doctor يعيد توليد التخزين المؤقت تلقائيًا. +- إذا لم يكن هناك أي إكمال مهيأ أصلًا، فإن doctor يطلب تثبيته + (في الوضع التفاعلي فقط؛ ويتم تخطيه مع `--non-interactive`). -شغّل `openclaw completion --write-state` لإعادة إنشاء cache يدويًا. +شغّل `openclaw completion --write-state` لإعادة توليد التخزين المؤقت يدويًا. ### 12) فحوصات مصادقة Gateway ‏(الرمز المحلي) -يفحص Doctor جاهزية مصادقة رمز gateway المحلي. +يتحقق Doctor من جهوزية مصادقة رمز gateway المحلي. -- إذا كان وضع الرمز يحتاج إلى رمز ولا يوجد مصدر له، فسيعرض doctor إنشاء واحد. -- إذا كان `gateway.auth.token` مُدارًا بواسطة SecretRef ولكنه غير متاح، فسيحذر doctor ولن يكتب فوقه بنص صريح. -- يفرض `openclaw doctor --generate-gateway-token` الإنشاء فقط عند عدم ضبط أي token SecretRef. +- إذا كان وضع الرمز يحتاج إلى رمز ولا يوجد مصدر له، فإن doctor يعرض توليد واحد. +- إذا كان `gateway.auth.token` مدارًا بواسطة SecretRef ولكنه غير متاح، فإن doctor يحذر ولا يستبدله بنص صريح. +- يفرض `openclaw doctor --generate-gateway-token` التوليد فقط عندما لا يكون هناك token SecretRef مهيأ. ### 12b) إصلاحات واعية بـ SecretRef للقراءة فقط -تحتاج بعض تدفقات الإصلاح إلى فحص بيانات الاعتماد المضبوطة دون إضعاف -سلوك الفشل السريع في وقت التشغيل. +تحتاج بعض تدفقات الإصلاح إلى فحص بيانات الاعتماد المهيأة دون إضعاف سلوك الفشل السريع في وقت التشغيل. -- يستخدم `openclaw doctor --fix` الآن نموذج ملخص SecretRef نفسه للقراءة فقط كما في أوامر عائلة الحالة لإصلاحات الإعدادات المستهدفة. -- مثال: يحاول إصلاح `allowFrom` / `groupAllowFrom` `@username` في Telegram استخدام بيانات اعتماد البوت المضبوطة عندما تكون متاحة. -- إذا كان رمز Telegram bot مضبوطًا عبر SecretRef لكنه غير متاح في مسار الأمر الحالي، فإن doctor يبلغ أن بيانات الاعتماد مضبوطة لكنها غير متاحة، ويتخطى الحل التلقائي بدلًا من التعطل أو الإبلاغ خطأً عن أن الرمز مفقود. +- يستخدم `openclaw doctor --fix` الآن نموذج الملخص نفسه المعتمد على SecretRef للقراءة فقط كما في أوامر عائلة الحالة، وذلك لإصلاحات إعدادات مستهدفة. +- مثال: يحاول إصلاح Telegram `allowFrom` / `groupAllowFrom` لأسماء `@username` استخدام بيانات اعتماد البوت المهيأة عندما تكون متاحة. +- إذا كان رمز Telegram bot مهيأ عبر SecretRef ولكنه غير متاح في مسار الأمر الحالي، فإن doctor يبلغ أن بيانات الاعتماد مهيأة-لكن-غير-متاحة ويتخطى الحل التلقائي بدلًا من التعطل أو الإبلاغ خطأً عن أن الرمز مفقود. ### 13) فحص سلامة Gateway + إعادة التشغيل -يشغّل Doctor فحص سلامة ويعرض إعادة تشغيل gateway عندما يبدو -غير سليم. +يشغّل Doctor فحص سلامة ويعرض إعادة تشغيل gateway عندما تبدو +غير سليمة. -### 13b) جاهزية بحث الذاكرة +### 13b) جهوزية بحث الذاكرة -يفحص Doctor ما إذا كان مزود embedding المضبوط لبحث الذاكرة جاهزًا -للوكيل الافتراضي. ويعتمد السلوك على backend والمزود المضبوطين: +يتحقق Doctor مما إذا كان موفّر embedding المهيأ لبحث الذاكرة جاهزًا +للوكيل الافتراضي. ويعتمد السلوك على الواجهة الخلفية والموفّر المهيأين: -- **QMD backend**: يفحص ما إذا كان الملف التنفيذي `qmd` متاحًا وقابلًا للتشغيل. - وإذا لم يكن كذلك، يطبع إرشادات الإصلاح بما في ذلك حزمة npm وخيار مسار binary يدوي. -- **مزود محلي صريح**: يفحص وجود ملف نموذج محلي أو عنوان URL - معرَّف لنموذج بعيد/قابل للتنزيل. وإذا كان مفقودًا، يقترح التحويل إلى مزود بعيد. -- **مزود بعيد صريح** (`openai`, `voyage`، إلخ): يتحقق من وجود مفتاح API - في البيئة أو في مخزن المصادقة. ويطبع تلميحات إصلاح عملية إذا كان مفقودًا. -- **مزود تلقائي**: يفحص توفر النموذج المحلي أولًا، ثم يجرب كل مزود بعيد - بترتيب الاختيار التلقائي. +- **واجهة QMD الخلفية**: يفحص ما إذا كان الملف التنفيذي `qmd` متاحًا وقابلًا للتشغيل. + وإذا لم يكن كذلك، يطبع إرشادات إصلاح تتضمن حزمة npm وخيار مسار يدوي للملف التنفيذي. +- **موفّر محلي صريح**: يتحقق من وجود ملف نموذج محلي أو عنوان URL معروف + لنموذج بعيد/قابل للتنزيل. وإذا كان مفقودًا، يقترح التبديل إلى موفّر بعيد. +- **موفّر بعيد صريح** (`openai` أو `voyage` وغيرهما): يتحقق من وجود مفتاح API + في البيئة أو مخزن المصادقة. ويطبع تلميحات إصلاح قابلة للتنفيذ إذا كان مفقودًا. +- **موفّر تلقائي**: يتحقق أولًا من توفر النموذج المحلي، ثم يجرب كل موفّر بعيد + وفق ترتيب الاختيار التلقائي. -عندما تكون نتيجة فحص gateway متاحة (كانت حالة gateway سليمة وقت -الفحص)، فإن doctor يربط نتيجتها مع الإعدادات المرئية من CLI ويشير +عندما تكون نتيجة فحص gateway متاحة (كانت gateway سليمة وقت +الفحص)، فإن doctor يطابق نتيجتها مع الإعدادات المرئية في CLI ويشير إلى أي اختلاف. -استخدم `openclaw memory status --deep` للتحقق من جاهزية embedding في وقت التشغيل. +استخدم `openclaw memory status --deep` للتحقق من جهوزية embedding في وقت التشغيل. -### 14) تحذيرات حالة القنوات +### 14) تحذيرات حالة القناة -إذا كانت حالة gateway سليمة، فسيجري doctor فحصًا لحالة القنوات ويعرض -تحذيرات مع إصلاحات مقترحة. +إذا كانت gateway سليمة، فإن doctor يشغّل فحص حالة القناة ويبلغ +عن التحذيرات مع الإصلاحات المقترحة. -### 15) تدقيق إعدادات المشرف + الإصلاح +### 15) تدقيق إعدادات Supervisor + الإصلاح -يفحص Doctor إعدادات المشرف المثبتة (launchd/systemd/schtasks) بحثًا عن -القيم الافتراضية المفقودة أو القديمة (مثل تبعيات systemd network-online و +يتحقق Doctor من إعدادات supervisor المثبتة (launchd/systemd/schtasks) بحثًا عن +الافتراضيات المفقودة أو القديمة (مثل تبعيات network-online في systemd و تأخير إعادة التشغيل). وعندما يجد عدم تطابق، فإنه يوصي بالتحديث ويمكنه -إعادة كتابة ملف الخدمة/المهمة إلى القيم الافتراضية الحالية. +إعادة كتابة ملف الخدمة/المهمة إلى الافتراضيات الحالية. ملاحظات: -- يطلب `openclaw doctor` التأكيد قبل إعادة كتابة إعدادات المشرف. +- يطلب `openclaw doctor` تأكيدًا قبل إعادة كتابة إعدادات supervisor. - يقبل `openclaw doctor --yes` مطالبات الإصلاح الافتراضية. -- يطبّق `openclaw doctor --repair` الإصلاحات الموصى بها من دون مطالبات. -- يكتب `openclaw doctor --repair --force` فوق إعدادات المشرف المخصصة. -- إذا كانت مصادقة الرمز تتطلب رمزًا وكان `gateway.auth.token` مُدارًا بواسطة SecretRef، فإن تثبيت/إصلاح خدمة doctor يتحقق من SecretRef لكنه لا يحفظ قيم الرمز النصية الصريحة التي تم حلها في بيانات بيئة خدمة المشرف الوصفية. -- إذا كانت مصادقة الرمز تتطلب رمزًا وكان token SecretRef المضبوط غير محلول، فإن doctor يمنع مسار التثبيت/الإصلاح مع إرشادات عملية. -- إذا تم ضبط كل من `gateway.auth.token` و`gateway.auth.password` وكان `gateway.auth.mode` غير مضبوط، فإن doctor يمنع التثبيت/الإصلاح حتى يتم ضبط الوضع صراحةً. -- بالنسبة إلى وحدات Linux user-systemd، تتضمن فحوصات انجراف الرمز في doctor الآن كلاً من مصدري `Environment=` و`EnvironmentFile=` عند مقارنة بيانات مصادقة الخدمة الوصفية. +- يطبق `openclaw doctor --repair` الإصلاحات الموصى بها من دون مطالبات. +- يستبدل `openclaw doctor --repair --force` إعدادات supervisor المخصصة. +- إذا كانت مصادقة الرمز تتطلب رمزًا وكان `gateway.auth.token` مدارًا بواسطة SecretRef، فإن doctor عند تثبيت/إصلاح الخدمة يتحقق من SecretRef لكنه لا يحفظ قيم الرموز الصريحة المحلولة في بيانات البيئة الوصفية لخدمة supervisor. +- إذا كانت مصادقة الرمز تتطلب رمزًا وكان token SecretRef المهيأ غير محلول، فإن doctor يمنع مسار التثبيت/الإصلاح مع إرشادات قابلة للتنفيذ. +- إذا كان كل من `gateway.auth.token` و`gateway.auth.password` مهيأين وكان `gateway.auth.mode` غير مضبوط، فإن doctor يمنع التثبيت/الإصلاح حتى يُضبط الوضع صراحة. +- بالنسبة لوحدات Linux user-systemd، فإن فحوصات انجراف الرمز في doctor تشمل الآن كلا مصدري `Environment=` و`EnvironmentFile=` عند مقارنة بيانات المصادقة الوصفية للخدمة. - يمكنك دائمًا فرض إعادة كتابة كاملة عبر `openclaw gateway install --force`. ### 16) تشخيصات وقت تشغيل Gateway + المنفذ يفحص Doctor وقت تشغيل الخدمة (PID، وآخر حالة خروج) ويحذر عندما تكون -الخدمة مثبتة لكنها لا تعمل فعليًا. كما يفحص تعارضات المنافذ -على منفذ gateway ‏(الافتراضي `18789`) ويعرض الأسباب المحتملة (gateway يعمل بالفعل، +الخدمة مثبتة ولكنها لا تعمل فعليًا. كما يتحقق من تعارضات المنفذ +على منفذ gateway ‏(الافتراضي `18789`) ويبلغ عن الأسباب المحتملة (gateway تعمل بالفعل، أو نفق SSH). ### 17) أفضل ممارسات وقت تشغيل Gateway -يحذر Doctor عندما تعمل خدمة gateway على Bun أو على مسار Node مُدار بإدارة الإصدارات -(`nvm`, `fnm`, `volta`, `asdf`، إلخ). تتطلب قنوات WhatsApp + Telegram وجود Node، -كما يمكن أن تتعطل مسارات مديري الإصدارات بعد الترقيات لأن الخدمة لا -تحمّل تهيئة shell الخاصة بك. يعرض doctor الترحيل إلى تثبيت Node على مستوى النظام عندما -يكون متاحًا (Homebrew/apt/choco). +يحذر Doctor عندما تعمل خدمة gateway على Bun أو على مسار Node مُدار بمدير إصدارات +(`nvm` أو `fnm` أو `volta` أو `asdf` وغيرها). تتطلب قنوات WhatsApp + Telegram استخدام Node، +وقد تتعطل مسارات مديري الإصدارات بعد الترقية لأن الخدمة لا تحمّل +تهيئة الصدفة الخاصة بك. ويعرض doctor الترحيل إلى تثبيت Node على مستوى النظام عند +توفره (Homebrew/apt/choco). ### 18) كتابة الإعدادات + بيانات wizard الوصفية -يحفظ Doctor أي تغييرات في الإعدادات ويضع ختمًا على بيانات wizard الوصفية لتسجيل +يحفظ Doctor أي تغييرات في الإعدادات ويضع بيانات وصفية لـ wizard لتسجيل تشغيل doctor. -### 19) نصائح workspace ‏(النسخ الاحتياطي + نظام الذاكرة) +### 19) تلميحات workspace ‏(النسخ الاحتياطي + نظام الذاكرة) -يقترح Doctor نظام ذاكرة للـ workspace عند غيابه ويطبع تلميحًا للنسخ الاحتياطي -إذا لم تكن workspace تحت git بالفعل. +يقترح Doctor نظام ذاكرة لـ workspace عند غيابه ويطبع تلميح نسخ احتياطي +إذا لم يكن workspace موجودًا أصلًا تحت git. -راجع [/concepts/agent-workspace](/ar/concepts/agent-workspace) للحصول على دليل كامل -لبنية workspace والنسخ الاحتياطي باستخدام git (يُوصى باستخدام GitHub أو GitLab خاص). +راجع [/concepts/agent-workspace](/ar/concepts/agent-workspace) للحصول على دليل كامل حول +بنية workspace والنسخ الاحتياطي عبر git ‏(يوصى باستخدام GitHub أو GitLab خاص). diff --git a/docs/ar/gateway/heartbeat.md b/docs/ar/gateway/heartbeat.md index 4e161be3b..41f82192a 100644 --- a/docs/ar/gateway/heartbeat.md +++ b/docs/ar/gateway/heartbeat.md @@ -1,41 +1,41 @@ --- read_when: - - ضبط وتيرة heartbeat أو الرسائل - - اتخاذ قرار بين heartbeat وcron للمهام المجدولة + - تعديل وتيرة Heartbeat أو رسائله + - اتخاذ قرار بين Heartbeat وcron للمهام المجدولة summary: رسائل استطلاع Heartbeat وقواعد الإشعارات title: Heartbeat x-i18n: - generated_at: "2026-04-05T12:43:47Z" + generated_at: "2026-04-08T02:15:34Z" model: gpt-5.4 provider: openai - source_hash: f417b0d4453bed9022144d364521a59dec919d44cca8f00f0def005cd38b146f + source_hash: a8021d747637060eacb91ec5f75904368a08790c19f4fca32acda8c8c0a25e41 source_path: gateway/heartbeat.md workflow: 15 --- -# Heartbeat ‏(Gateway) +# Heartbeat (البوابة) -> **Heartbeat أم Cron؟** راجع [Automation & Tasks](/automation) للحصول على إرشادات حول وقت استخدام كل منهما. +> **Heartbeat أم Cron؟** راجع [الأتمتة والمهام](/ar/automation) للحصول على إرشادات حول وقت استخدام كل منهما. يشغّل Heartbeat **أدوار وكيل دورية** في الجلسة الرئيسية حتى يتمكن النموذج من -إظهار أي شيء يحتاج إلى انتباه من دون إزعاجك برسائل متكررة. +إبراز أي شيء يحتاج إلى انتباه دون إغراقك بالرسائل. -يُعد Heartbeat دورًا مجدولًا في الجلسة الرئيسية — وهو **لا** ينشئ سجلات [background task](/automation/tasks). -فسجلات المهام مخصصة للعمل المنفصل (تشغيلات ACP، والوكلاء الفرعيون، ومهام cron المعزولة). +Heartbeat هو دور مجدول في الجلسة الرئيسية — وهو **لا** ينشئ سجلات [المهام الخلفية](/ar/automation/tasks). +سجلات المهام مخصصة للعمل المنفصل (تشغيلات ACP، والوكلاء الفرعيون، ووظائف cron المعزولة). -استكشاف الأخطاء وإصلاحها: [Scheduled Tasks](/automation/cron-jobs#troubleshooting) +استكشاف الأخطاء وإصلاحها: [المهام المجدولة](/ar/automation/cron-jobs#troubleshooting) -## البدء السريع (للمبتدئين) +## بداية سريعة (للمبتدئين) -1. اترك heartbeats مفعلة (الافتراضي هو `30m`، أو `1h` لمصادقة Anthropic OAuth/token، بما في ذلك إعادة استخدام Claude CLI) أو عيّن وتيرتك الخاصة. -2. أنشئ قائمة تحقق صغيرة في `HEARTBEAT.md` أو كتلة `tasks:` في مساحة عمل الوكيل (اختياري لكنه موصى به). -3. قرر أين يجب أن تذهب رسائل heartbeat ‏(`target: "none"` هو الافتراضي؛ اضبط `target: "last"` للتوجيه إلى آخر جهة اتصال). -4. اختياري: فعّل تسليم reasoning الخاص بـ heartbeat من أجل الشفافية. -5. اختياري: استخدم سياق bootstrap خفيفًا إذا كانت تشغيلات heartbeat تحتاج فقط إلى `HEARTBEAT.md`. -6. اختياري: فعّل الجلسات المعزولة لتجنب إرسال السجل الكامل للمحادثة في كل heartbeat. -7. اختياري: قيد heartbeats بالساعات النشطة (التوقيت المحلي). +1. اترك Heartbeat مفعّلًا (القيمة الافتراضية هي `30m`، أو `1h` لمصادقة Anthropic OAuth/الرمز، بما في ذلك إعادة استخدام Claude CLI) أو اضبط وتيرتك الخاصة. +2. أنشئ قائمة تحقق صغيرة في `HEARTBEAT.md` أو كتلة `tasks:` في مساحة عمل الوكيل (اختياري لكنه مستحسن). +3. قرر إلى أين يجب أن تذهب رسائل Heartbeat (القيمة الافتراضية هي `target: "none"`؛ اضبط `target: "last"` للتوجيه إلى آخر جهة اتصال). +4. اختياري: فعّل تسليم الاستدلال الخاص بـ Heartbeat لمزيد من الشفافية. +5. اختياري: استخدم سياق تمهيد خفيفًا إذا كانت تشغيلات Heartbeat تحتاج فقط إلى `HEARTBEAT.md`. +6. اختياري: فعّل الجلسات المعزولة لتجنب إرسال سجل المحادثة الكامل في كل Heartbeat. +7. اختياري: قيّد Heartbeats بساعات النشاط (بالتوقيت المحلي). -مثال على التكوين: +مثال على الإعدادات: ```json5 { @@ -43,10 +43,10 @@ x-i18n: defaults: { heartbeat: { every: "30m", - target: "last", // تسليم صريح إلى آخر جهة اتصال (الافتراضي هو "none") - directPolicy: "allow", // الافتراضي: السماح بأهداف direct/DM؛ اضبط "block" لمنعها - lightContext: true, // اختياري: حقن HEARTBEAT.md فقط من ملفات bootstrap - isolatedSession: true, // اختياري: جلسة جديدة لكل تشغيل (من دون سجل المحادثة) + target: "last", // توصيل صريح إلى آخر جهة اتصال (الافتراضي هو "none") + directPolicy: "allow", // الافتراضي: السماح بالجهات المباشرة/الرسائل الخاصة؛ اضبط "block" لمنعها + lightContext: true, // اختياري: حقن `HEARTBEAT.md` فقط من ملفات التمهيد + isolatedSession: true, // اختياري: جلسة جديدة في كل تشغيل (من دون سجل محادثة) // activeHours: { start: "08:00", end: "24:00" }, // includeReasoning: true, // اختياري: إرسال رسالة `Reasoning:` منفصلة أيضًا }, @@ -57,55 +57,58 @@ x-i18n: ## القيم الافتراضية -- الفاصل الزمني: `30m` ‏(أو `1h` عندما يكون وضع مصادقة Anthropic OAuth/token هو وضع المصادقة المكتشف، بما في ذلك إعادة استخدام Claude CLI). اضبط `agents.defaults.heartbeat.every` أو `agents.list[].heartbeat.every` لكل وكيل؛ واستخدم `0m` للتعطيل. -- نص المطالبة (قابل للتكوين عبر `agents.defaults.heartbeat.prompt`): +- الفاصل الزمني: `30m` (أو `1h` عندما تكون مصادقة Anthropic OAuth/الرمز هي وضع المصادقة المكتشف، بما في ذلك إعادة استخدام Claude CLI). اضبط `agents.defaults.heartbeat.every` أو `agents.list[].heartbeat.every` لكل وكيل؛ استخدم `0m` للتعطيل. +- نص الموجّه (قابل للتهيئة عبر `agents.defaults.heartbeat.prompt`): `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.` -- تُرسل مطالبة heartbeat **حرفيًا** كرسالة مستخدم. وتتضمن مطالبة - النظام قسم “Heartbeat” ويتم تعليم التشغيل داخليًا. -- يتم التحقق من الساعات النشطة (`heartbeat.activeHours`) في المنطقة الزمنية المكوّنة. - وخارج هذه النافذة، يتم تخطي heartbeats حتى التوقيت التالي داخل النافذة. +- يُرسَل موجّه Heartbeat **حرفيًا** كرسالة مستخدم. يتضمن + موجّه النظام قسم “Heartbeat” فقط عندما تكون Heartbeats مفعّلة للوكيل + الافتراضي، ويكون التشغيل معلّمًا داخليًا. +- عندما يتم تعطيل Heartbeats باستخدام `0m`، تحذف التشغيلات العادية أيضًا `HEARTBEAT.md` + من سياق التمهيد حتى لا يرى النموذج تعليمات Heartbeat فقط. +- يتم التحقق من ساعات النشاط (`heartbeat.activeHours`) في المنطقة الزمنية المهيأة. + خارج النافذة، يتم تخطي Heartbeats حتى النبضة التالية داخل النافذة. -## الغرض من مطالبة heartbeat +## ما الغرض من موجّه Heartbeat -المطالبة الافتراضية واسعة عمدًا: +الموجّه الافتراضي عام عمدًا: -- **المهام الخلفية**: عبارة “Consider outstanding tasks” تدفع الوكيل إلى مراجعة - المتابعات (البريد الوارد، والتقويم، والتذكيرات، والعمل في قائمة الانتظار) وإظهار أي شيء عاجل. -- **الاطمئنان على الإنسان**: عبارة “Checkup sometimes on your human during day time” تدفع إلى - رسالة خفيفة أحيانًا مثل “هل تحتاج شيئًا؟”، لكنها تتجنب الإزعاج الليلي - باستخدام منطقتك الزمنية المحلية المكوّنة (راجع [/concepts/timezone](/concepts/timezone)). +- **المهام الخلفية**: عبارة “ضع في الاعتبار المهام المعلّقة” تدفع الوكيل إلى مراجعة + المتابعات (البريد الوارد، والتقويم، والتذكيرات، والعمل المصطف في الطابور) وإبراز أي شيء عاجل. +- **التحقق من المستخدم**: عبارة “تحقق من إنسانك أحيانًا أثناء النهار” تدفع إلى + رسالة خفيفة من حين لآخر مثل “هل تحتاج إلى شيء؟”، لكنها تتجنب الإزعاج الليلي + باستخدام منطقتك الزمنية المحلية المهيأة (راجع [/concepts/timezone](/ar/concepts/timezone)). -يمكن لـ Heartbeat التفاعل مع [background tasks](/automation/tasks) المكتملة، لكن تشغيل heartbeat نفسه لا ينشئ سجل مهمة. +يمكن لـ Heartbeat التفاعل مع [المهام الخلفية](/ar/automation/tasks) المكتملة، لكن تشغيل Heartbeat نفسه لا ينشئ سجل مهمة. -إذا كنت تريد من heartbeat أن يقوم بشيء محدد جدًا (مثل “check Gmail PubSub -stats” أو “verify gateway health”)، فاضبط `agents.defaults.heartbeat.prompt` (أو -`agents.list[].heartbeat.prompt`) على نص مخصص (يُرسل حرفيًا). +إذا كنت تريد من Heartbeat أن يفعل شيئًا محددًا جدًا (مثل “تحقق من إحصاءات Gmail PubSub” +أو “تحقق من صحة البوابة”)، فاضبط `agents.defaults.heartbeat.prompt` (أو +`agents.list[].heartbeat.prompt`) على نص مخصص (يُرسَل حرفيًا). ## عقد الاستجابة - إذا لم يكن هناك ما يحتاج إلى انتباه، فردّ بـ **`HEARTBEAT_OK`**. -- أثناء تشغيلات heartbeat، يعامل OpenClaw الرمز `HEARTBEAT_OK` كإقرار عندما يظهر - في **بداية أو نهاية** الرد. تتم إزالة الرمز ويتم إسقاط الرد إذا كان - المحتوى المتبقي **≤ `ackMaxChars`** ‏(الافتراضي: 300). -- إذا ظهر `HEARTBEAT_OK` في **وسط** الرد، فلا تتم معاملته - بشكل خاص. -- بالنسبة إلى التنبيهات، **لا** تضمن `HEARTBEAT_OK`؛ وأعد نص التنبيه فقط. +- أثناء تشغيلات Heartbeat، يتعامل OpenClaw مع `HEARTBEAT_OK` كإقرار عندما يظهر + في **بداية أو نهاية** الرد. تتم إزالة الرمز ويُسقَط الرد + إذا كان المحتوى المتبقي **≤ `ackMaxChars`** (الافتراضي: 300). +- إذا ظهر `HEARTBEAT_OK` في **منتصف** الرد، فلا تتم معاملته + معاملة خاصة. +- للتنبيهات، **لا** تُضمّن `HEARTBEAT_OK`؛ أعد نص التنبيه فقط. -خارج heartbeats، تتم إزالة أي `HEARTBEAT_OK` عارض في بداية/نهاية الرسالة -ويتم تسجيله؛ وتُسقط الرسالة إذا كانت تحتوي فقط على `HEARTBEAT_OK`. +خارج Heartbeats، تتم إزالة أي `HEARTBEAT_OK` عارض في بداية/نهاية الرسالة +ويُسجَّل؛ وتُسقَط الرسالة إذا كانت فقط `HEARTBEAT_OK`. -## التكوين +## الإعدادات ```json5 { agents: { defaults: { heartbeat: { - every: "30m", // الافتراضي: 30m (0m يعطّل) + every: "30m", // الافتراضي: 30m (يعطَّل عند 0m) model: "anthropic/claude-opus-4-6", - includeReasoning: false, // الافتراضي: false (تسليم رسالة Reasoning: منفصلة عندما تكون متاحة) - lightContext: false, // الافتراضي: false؛ قيمة true تُبقي HEARTBEAT.md فقط من ملفات bootstrap لمساحة العمل - isolatedSession: false, // الافتراضي: false؛ قيمة true تشغّل كل heartbeat في جلسة جديدة (من دون سجل محادثة) + includeReasoning: false, // الافتراضي: false (تسليم رسالة Reasoning: منفصلة عند توفرها) + lightContext: false, // الافتراضي: false؛ true يبقي فقط `HEARTBEAT.md` من ملفات تمهيد مساحة العمل + isolatedSession: false, // الافتراضي: false؛ true يشغّل كل Heartbeat في جلسة جديدة (من دون سجل المحادثة) target: "last", // الافتراضي: none | الخيارات: last | none | (أساسي أو plugin، مثل "bluebubbles") to: "+15551234567", // تجاوز اختياري خاص بالقناة accountId: "ops-bot", // معرّف قناة متعدد الحسابات اختياري @@ -117,21 +120,21 @@ stats” أو “verify gateway health”)، فاضبط `agents.defaults.heartbe } ``` -### النطاق والأولوية +### النطاق والأسبقية -- يعيّن `agents.defaults.heartbeat` سلوك heartbeat العام. -- يتم دمج `agents.list[].heartbeat` فوقه؛ وإذا كان لأي وكيل كتلة `heartbeat`، فإن **هؤلاء الوكلاء فقط** هم الذين يشغّلون heartbeats. -- يضبط `channels.defaults.heartbeat` القيم الافتراضية للظهور لكل القنوات. +- يضبط `agents.defaults.heartbeat` سلوك Heartbeat العام. +- يُدمَج `agents.list[].heartbeat` فوقه؛ إذا كان لدى أي وكيل كتلة `heartbeat`، فإن **هؤلاء الوكلاء فقط** هم من يشغّلون Heartbeats. +- يضبط `channels.defaults.heartbeat` القيم الافتراضية للظهور لجميع القنوات. - يتجاوز `channels..heartbeat` القيم الافتراضية للقناة. -- يتجاوز `channels..accounts..heartbeat` ‏(للقنوات متعددة الحسابات) الإعدادات لكل قناة. +- يتجاوز `channels..accounts..heartbeat` (القنوات متعددة الحسابات) إعدادات كل قناة. ### Heartbeats لكل وكيل -إذا تضمّن أي إدخال `agents.list[]` كتلة `heartbeat`، فإن **هؤلاء الوكلاء فقط** -هم من يشغّلون heartbeats. ويتم دمج الكتلة لكل وكيل فوق `agents.defaults.heartbeat` -(بحيث يمكنك تعيين القيم المشتركة مرة واحدة ثم تجاوزها لكل وكيل). +إذا تضمّن أي إدخال في `agents.list[]` كتلة `heartbeat`، فإن **هؤلاء الوكلاء فقط** +هم من يشغّلون Heartbeats. وتُدمَج الكتلة الخاصة بكل وكيل فوق `agents.defaults.heartbeat` +(حتى تتمكن من ضبط القيم المشتركة مرة واحدة ثم تجاوزها لكل وكيل). -مثال: وكيلان، والوكيل الثاني فقط هو الذي يشغّل heartbeats. +مثال: وكيلان، والوكيل الثاني فقط هو من يشغّل Heartbeats. ```json5 { @@ -139,7 +142,7 @@ stats” أو “verify gateway health”)، فاضبط `agents.defaults.heartbe defaults: { heartbeat: { every: "30m", - target: "last", // تسليم صريح إلى آخر جهة اتصال (الافتراضي هو "none") + target: "last", // توصيل صريح إلى آخر جهة اتصال (الافتراضي هو "none") }, }, list: [ @@ -158,9 +161,9 @@ stats” أو “verify gateway health”)، فاضبط `agents.defaults.heartbe } ``` -### مثال على الساعات النشطة +### مثال على ساعات النشاط -قيد heartbeats بساعات العمل في منطقة زمنية محددة: +قيّد Heartbeats بساعات العمل في منطقة زمنية محددة: ```json5 { @@ -168,11 +171,11 @@ stats” أو “verify gateway health”)، فاضبط `agents.defaults.heartbe defaults: { heartbeat: { every: "30m", - target: "last", // تسليم صريح إلى آخر جهة اتصال (الافتراضي هو "none") + target: "last", // توصيل صريح إلى آخر جهة اتصال (الافتراضي هو "none") activeHours: { start: "09:00", end: "22:00", - timezone: "America/New_York", // اختياري؛ يستخدم userTimezone إن كانت معيّنة، وإلا المنطقة الزمنية للمضيف + timezone: "America/New_York", // اختياري؛ يستخدم `userTimezone` إذا كان مضبوطًا، وإلا يستخدم المنطقة الزمنية للمضيف }, }, }, @@ -180,21 +183,21 @@ stats” أو “verify gateway health”)، فاضبط `agents.defaults.heartbe } ``` -خارج هذه النافذة (قبل 9 صباحًا أو بعد 10 مساءً بتوقيت الشرق)، يتم تخطي heartbeats. وسيعمل التوقيت المجدول التالي داخل النافذة بشكل طبيعي. +خارج هذه النافذة (قبل التاسعة صباحًا أو بعد العاشرة مساءً بالتوقيت الشرقي)، يتم تخطي Heartbeats. وستعمل النبضة المجدولة التالية داخل النافذة بشكل طبيعي. ### إعداد 24/7 -إذا كنت تريد تشغيل heartbeats طوال اليوم، فاستخدم أحد هذين النمطين: +إذا كنت تريد تشغيل Heartbeats طوال اليوم، فاستخدم أحد هذين النمطين: - احذف `activeHours` بالكامل (من دون تقييد بنافذة زمنية؛ وهذا هو السلوك الافتراضي). -- عيّن نافذة يوم كامل: `activeHours: { start: "00:00", end: "24:00" }`. +- اضبط نافذة يوم كامل: `activeHours: { start: "00:00", end: "24:00" }`. -لا تعيّن الوقت نفسه لكل من `start` و`end` (مثلًا `08:00` إلى `08:00`). -تُعامل هذه الحالة على أنها نافذة بعرض صفري، لذلك يتم دائمًا تخطي heartbeats. +لا تضبط القيمتين `start` و`end` على الوقت نفسه (مثل `08:00` إلى `08:00`). +تُعامَل هذه الحالة على أنها نافذة بعرض صفري، لذلك يتم دائمًا تخطي Heartbeats. -### مثال متعدد الحسابات +### مثال على الحسابات المتعددة -استخدم `accountId` لاستهداف حساب محدد على القنوات متعددة الحسابات مثل Telegram: +استخدم `accountId` لاستهداف حساب محدد في القنوات متعددة الحسابات مثل Telegram: ```json5 { @@ -223,56 +226,56 @@ stats” أو “verify gateway health”)، فاضبط `agents.defaults.heartbe ### ملاحظات الحقول -- `every`: الفاصل الزمني لـ heartbeat ‏(سلسلة مدة؛ وحدة القياس الافتراضية = دقائق). -- `model`: تجاوز اختياري للنموذج في تشغيلات heartbeat ‏(`provider/model`). -- `includeReasoning`: عند التمكين، يسلّم أيضًا رسالة `Reasoning:` منفصلة عندما تكون متاحة (بنفس شكل `/reasoning on`). -- `lightContext`: عندما تكون القيمة true، تستخدم تشغيلات heartbeat سياق bootstrap خفيفًا وتحتفظ فقط بـ `HEARTBEAT.md` من ملفات bootstrap الخاصة بمساحة العمل. -- `isolatedSession`: عندما تكون القيمة true، تعمل كل heartbeat في جلسة جديدة من دون سجل محادثة سابق. وتستخدم نفس نمط العزل الذي يستخدمه cron مع `sessionTarget: "isolated"`. وهذا يقلل بشكل كبير تكلفة الرموز لكل heartbeat. اجمعها مع `lightContext: true` لتحقيق أقصى توفير. ويظل توجيه التسليم يستخدم سياق الجلسة الرئيسية. -- `session`: مفتاح جلسة اختياري لتشغيلات heartbeat. - - `main` ‏(الافتراضي): الجلسة الرئيسية للوكيل. - - مفتاح جلسة صريح (انسخه من `openclaw sessions --json` أو من [sessions CLI](/cli/sessions)). - - تنسيقات مفاتيح الجلسات: راجع [Sessions](/concepts/session) و[Groups](/channels/groups). +- `every`: الفاصل الزمني لـ Heartbeat (سلسلة مدة؛ وحدة القياس الافتراضية = دقائق). +- `model`: تجاوز اختياري للنموذج في تشغيلات Heartbeat (`provider/model`). +- `includeReasoning`: عند تفعيله، يسلّم أيضًا رسالة `Reasoning:` المنفصلة عند توفرها (بالصيغة نفسها مثل `/reasoning on`). +- `lightContext`: عندما تكون قيمته true، تستخدم تشغيلات Heartbeat سياق تمهيد خفيفًا وتُبقي فقط `HEARTBEAT.md` من ملفات تمهيد مساحة العمل. +- `isolatedSession`: عندما تكون قيمته true، يعمل كل Heartbeat في جلسة جديدة من دون أي سجل محادثة سابق. ويستخدم نمط العزل نفسه مثل cron `sessionTarget: "isolated"`. ويقلل بدرجة كبيرة تكلفة الرموز لكل Heartbeat. اجمعه مع `lightContext: true` لتحقيق أكبر قدر من التوفير. يظل توجيه التسليم يستخدم سياق الجلسة الرئيسية. +- `session`: مفتاح جلسة اختياري لتشغيلات Heartbeat. + - `main` (الافتراضي): الجلسة الرئيسية للوكيل. + - مفتاح جلسة صريح (انسخه من `openclaw sessions --json` أو من [CLI الجلسات](/cli/sessions)). + - صيغ مفاتيح الجلسة: راجع [الجلسات](/ar/concepts/session) و[المجموعات](/ar/channels/groups). - `target`: - `last`: التسليم إلى آخر قناة خارجية مستخدمة. - - قناة صريحة: أي قناة مكوّنة أو معرّف plugin، مثل `discord` أو `matrix` أو `telegram` أو `whatsapp`. - - `none` ‏(الافتراضي): تشغيل heartbeat لكن **من دون تسليم** خارجي. -- `directPolicy`: يتحكم في سلوك التسليم المباشر/DM: - - `allow` ‏(الافتراضي): السماح بتسليم heartbeat إلى direct/DM. - - `block`: منع التسليم إلى direct/DM ‏(`reason=dm-blocked`). -- `to`: تجاوز اختياري للمستلم (معرّف خاص بالقناة، مثل E.164 لـ WhatsApp أو معرّف دردشة Telegram). وبالنسبة إلى Telegram topics/threads، استخدم `:topic:`. -- `accountId`: معرّف حساب اختياري للقنوات متعددة الحسابات. وعندما تكون `target: "last"`، ينطبق معرّف الحساب على آخر قناة محلولة إذا كانت تدعم الحسابات؛ وإلا فيتم تجاهله. وإذا لم يطابق معرّف الحساب حسابًا مكوّنًا للقناة المحلولة، يتم تخطي التسليم. -- `prompt`: يتجاوز نص المطالبة الافتراضي (ولا يتم دمجه). + - قناة صريحة: أي قناة أو معرّف plugin مهيأ، مثل `discord` أو `matrix` أو `telegram` أو `whatsapp`. + - `none` (الافتراضي): شغّل Heartbeat لكن **لا تُسلِّمه** خارجيًا. +- `directPolicy`: يتحكم في سلوك التسليم المباشر/الرسائل الخاصة: + - `allow` (الافتراضي): السماح بتسليم Heartbeat إلى الأهداف المباشرة/الرسائل الخاصة. + - `block`: منع التسليم المباشر/الرسائل الخاصة (`reason=dm-blocked`). +- `to`: تجاوز اختياري للمستلم (معرّف خاص بالقناة، مثل E.164 لـ WhatsApp أو معرّف دردشة Telegram). بالنسبة إلى topics/threads في Telegram، استخدم `:topic:`. +- `accountId`: معرّف حساب اختياري للقنوات متعددة الحسابات. عندما تكون `target: "last"`، يُطبَّق معرّف الحساب على آخر قناة محلولة إذا كانت تدعم الحسابات؛ وإلا يتم تجاهله. وإذا لم يطابق معرّف الحساب حسابًا مهيأً للقناة المحلولة، يتم تخطي التسليم. +- `prompt`: يتجاوز نص الموجّه الافتراضي (من دون دمج). - `ackMaxChars`: الحد الأقصى للأحرف المسموح بها بعد `HEARTBEAT_OK` قبل التسليم. -- `suppressToolErrorWarnings`: عندما تكون القيمة true، يتم إخفاء حمولات تحذير أخطاء الأدوات أثناء تشغيلات heartbeat. -- `activeHours`: تقييد تشغيلات heartbeat بنافذة زمنية. كائن يحتوي على `start` ‏(HH:MM، شامل؛ استخدم `00:00` لبداية اليوم)، و`end` ‏(HH:MM غير شامل؛ ويُسمح بـ `24:00` لنهاية اليوم)، و`timezone` اختيارية. - - إذا حُذفت أو كانت `"user"`: تستخدم `agents.defaults.userTimezone` إن كانت معيّنة، وإلا تعود إلى المنطقة الزمنية لنظام المضيف. - - `"local"`: تستخدم دائمًا المنطقة الزمنية لنظام المضيف. - - أي معرّف IANA ‏(مثل `America/New_York`): يُستخدم مباشرة؛ وإذا كان غير صالح، يعود إلى سلوك `"user"` أعلاه. - - يجب ألا يكون `start` و`end` متساويين لنافذة نشطة؛ فالقيم المتساوية تُعامل على أنها عرض صفري (دائمًا خارج النافذة). - - خارج النافذة النشطة، يتم تخطي heartbeats حتى التوقيت التالي داخل النافذة. +- `suppressToolErrorWarnings`: عندما تكون قيمته true، يمنع حمولات تحذير أخطاء الأدوات أثناء تشغيلات Heartbeat. +- `activeHours`: يقيّد تشغيلات Heartbeat بنافذة زمنية. وهو كائن يحتوي على `start` (HH:MM، شامل؛ استخدم `00:00` لبداية اليوم) و`end` (HH:MM غير شامل؛ ويسمح بـ `24:00` لنهاية اليوم) و`timezone` اختياري. + - إذا حُذف أو كانت قيمته `"user"`: يستخدم `agents.defaults.userTimezone` إذا كان مضبوطًا، وإلا يعود إلى المنطقة الزمنية لنظام المضيف. + - `"local"`: يستخدم دائمًا المنطقة الزمنية لنظام المضيف. + - أي معرّف IANA (مثل `America/New_York`): يُستخدم مباشرة؛ وإذا كان غير صالح، يعود إلى سلوك `"user"` أعلاه. + - يجب ألا تكون `start` و`end` متساويتين في النافذة النشطة؛ إذ تُعامَل القيم المتساوية على أنها عرض صفري (أي دائمًا خارج النافذة). + - خارج النافذة النشطة، يتم تخطي Heartbeats حتى النبضة التالية داخل النافذة. ## سلوك التسليم -- تعمل Heartbeats في الجلسة الرئيسية للوكيل افتراضيًا (`agent::`)، +- تعمل Heartbeats افتراضيًا في الجلسة الرئيسية للوكيل (`agent::`)، أو `global` عندما تكون `session.scope = "global"`. اضبط `session` للتجاوز إلى جلسة قناة محددة (Discord/WhatsApp/إلخ). -- يؤثر `session` في سياق التشغيل فقط؛ أما التسليم فيتحكم فيه `target` و`to`. -- للتسليم إلى قناة/مستلم محدد، اضبط `target` + `to`. ومع +- يؤثر `session` فقط في سياق التشغيل؛ ويتحكم `target` و`to` في التسليم. +- للتسليم إلى قناة/مستلم محدد، اضبط `target` + `to`. مع `target: "last"`، يستخدم التسليم آخر قناة خارجية لتلك الجلسة. -- تسمح عمليات تسليم Heartbeat بأهداف direct/DM افتراضيًا. اضبط `directPolicy: "block"` لمنع الإرسال إلى الأهداف المباشرة مع الاستمرار في تشغيل دور heartbeat. -- إذا كانت الطوابير الرئيسية مشغولة، يتم تخطي heartbeat وإعادة المحاولة لاحقًا. -- إذا جرى حل `target` إلى عدم وجود وجهة خارجية، يظل التشغيل يحدث ولكن لا - يتم إرسال أي رسالة صادرة. -- إذا كانت `showOk` و`showAlerts` و`useIndicator` كلها معطلة، فيتم تخطي التشغيل مسبقًا على أنه `reason=alerts-disabled`. -- إذا كان تسليم التنبيهات فقط معطلًا، فلا يزال بإمكان OpenClaw تشغيل heartbeat، وتحديث الطوابع الزمنية للمهام المستحقة، واستعادة الطابع الزمني للخمول للجلسة، ومنع حمولة التنبيه الخارجية. -- الردود الخاصة بـ heartbeat فقط لا **تبقي الجلسة نشطة**؛ إذ تتم استعادة قيمة `updatedAt` - الأخيرة بحيث يعمل انتهاء الصلاحية عند الخمول بشكل طبيعي. -- يمكن أن تقوم [background tasks](/automation/tasks) المنفصلة بصف نظام حدث وتوقظ heartbeat عندما ينبغي أن تلاحظ الجلسة الرئيسية شيئًا بسرعة. ولا يجعل هذا الإيقاظ تشغيل heartbeat مهمة خلفية. +- تسمح تسليمات Heartbeat بالأهداف المباشرة/الرسائل الخاصة افتراضيًا. اضبط `directPolicy: "block"` لمنع الإرسال إلى الأهداف المباشرة مع الاستمرار في تشغيل دور Heartbeat. +- إذا كان الطابور الرئيسي مشغولًا، يتم تخطي Heartbeat وإعادة المحاولة لاحقًا. +- إذا لم يُحلّ `target` إلى أي وجهة خارجية، فسيحدث التشغيل لكن لن + تُرسَل أي رسالة صادرة. +- إذا كانت `showOk` و`showAlerts` و`useIndicator` كلها معطلة، فيتم تخطي التشغيل مسبقًا بسبب `reason=alerts-disabled`. +- إذا كان تسليم التنبيهات فقط معطلًا، فلا يزال بإمكان OpenClaw تشغيل Heartbeat، وتحديث الطوابع الزمنية للمهام المستحقة، واستعادة الطابع الزمني لخمول الجلسة، ومنع حمولة التنبيه الخارجية. +- الردود الخاصة بـ Heartbeat فقط **لا** تُبقي الجلسة نشطة؛ بل تتم استعادة `updatedAt` + الأخيرة حتى يعمل انتهاء صلاحية الخمول بشكل طبيعي. +- يمكن لـ [المهام الخلفية](/ar/automation/tasks) المنفصلة إدراج حدث نظام وإيقاظ Heartbeat عندما ينبغي أن تلاحظ الجلسة الرئيسية شيئًا بسرعة. وهذا الإيقاظ لا يجعل تشغيل Heartbeat مهمة خلفية. ## عناصر التحكم في الظهور -افتراضيًا، يتم إخفاء إشعارات `HEARTBEAT_OK` بينما يتم -تسليم محتوى التنبيه. يمكنك ضبط ذلك لكل قناة أو لكل حساب: +افتراضيًا، يتم منع إقرارات `HEARTBEAT_OK` بينما يتم +تسليم محتوى التنبيهات. يمكنك ضبط هذا لكل قناة أو لكل حساب: ```yaml channels: @@ -283,7 +286,7 @@ channels: useIndicator: true # إصدار أحداث المؤشر (الافتراضي) telegram: heartbeat: - showOk: true # إظهار إشعارات OK على Telegram + showOk: true # إظهار إقرارات OK على Telegram whatsapp: accounts: work: @@ -291,15 +294,15 @@ channels: showAlerts: false # منع تسليم التنبيهات لهذا الحساب ``` -الأولوية: لكل حساب ← لكل قناة ← القيم الافتراضية للقنوات ← القيم المدمجة الافتراضية. +الأسبقية: لكل حساب ← لكل قناة ← القيم الافتراضية للقناة ← القيم الافتراضية المدمجة. -### ما الذي يفعله كل علم +### ماذا يفعل كل علم -- `showOk`: يرسل إشعار `HEARTBEAT_OK` عندما يعيد النموذج ردًا يتضمن OK فقط. +- `showOk`: يرسل إقرار `HEARTBEAT_OK` عندما يعيد النموذج ردًا يحتوي فقط على OK. - `showAlerts`: يرسل محتوى التنبيه عندما يعيد النموذج ردًا غير OK. -- `useIndicator`: يصدر أحداث مؤشرات لأسطح حالة واجهة المستخدم. +- `useIndicator`: يصدر أحداث مؤشر لواجهات حالة UI. -إذا كانت **الثلاثة كلها** false، فإن OpenClaw يتخطى تشغيل heartbeat بالكامل (من دون استدعاء للنموذج). +إذا كانت **الثلاثة جميعًا** false، يتخطى OpenClaw تشغيل Heartbeat بالكامل (من دون استدعاء للنموذج). ### أمثلة لكل قناة مقابل لكل حساب @@ -312,7 +315,7 @@ channels: useIndicator: true slack: heartbeat: - showOk: true # كل حسابات Slack + showOk: true # جميع حسابات Slack accounts: ops: heartbeat: @@ -324,25 +327,30 @@ channels: ### الأنماط الشائعة -| الهدف | التكوين | -| ---------------------------------------- | ----------------------------------------------------------------------------------------- | -| السلوك الافتراضي (OK صامت، والتنبيهات مفعلة) | _(لا حاجة إلى تكوين)_ | -| صامت بالكامل (لا رسائل، ولا مؤشر) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` | -| مؤشر فقط (من دون رسائل) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }` | -| رسائل OK في قناة واحدة فقط | `channels.telegram.heartbeat: { showOk: true }` | +| الهدف | الإعدادات | +| ----------------------------------------- | ----------------------------------------------------------------------------------------- | +| السلوك الافتراضي (إشعارات OK صامتة، والتنبيهات مفعّلة) | _(لا حاجة إلى إعدادات)_ | +| صامت بالكامل (من دون رسائل، ومن دون مؤشر) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` | +| المؤشر فقط (من دون رسائل) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }` | +| إظهار OK في قناة واحدة فقط | `channels.telegram.heartbeat: { showOk: true }` | -## `HEARTBEAT.md` ‏(اختياري) +## `HEARTBEAT.md` (اختياري) -إذا كان ملف `HEARTBEAT.md` موجودًا في مساحة العمل، فإن المطالبة الافتراضية تطلب من -الوكيل قراءته. فكّر فيه باعتباره “قائمة التحقق الخاصة بـ heartbeat”: صغيرة، وثابتة، +إذا كان ملف `HEARTBEAT.md` موجودًا في مساحة العمل، فإن الموجّه الافتراضي يطلب من +الوكيل قراءته. فكّر فيه باعتباره “قائمة تحقق Heartbeat” الخاصة بك: صغيرة، وثابتة، وآمنة للإدراج كل 30 دقيقة. -إذا كان `HEARTBEAT.md` موجودًا لكنه فارغ فعليًا (أسطر فارغة فقط وعناوين markdown -مثل `# Heading`)، فإن OpenClaw يتخطى تشغيل heartbeat لتوفير استدعاءات API. -ويتم الإبلاغ عن هذا التجاوز على أنه `reason=empty-heartbeat-file`. -أما إذا كان الملف مفقودًا، فسيظل heartbeat يعمل ويقرر النموذج ما يجب فعله. +في التشغيلات العادية، لا يتم حقن `HEARTBEAT.md` إلا عندما تكون إرشادات Heartbeat +مفعّلة للوكيل الافتراضي. ويؤدي تعطيل وتيرة Heartbeat باستخدام `0m` أو +ضبط `includeSystemPromptSection: false` إلى حذفه من سياق التمهيد +العادي. -أبقِه صغيرًا (قائمة تحقق قصيرة أو تذكيرات) لتجنب تضخم المطالبة. +إذا كان `HEARTBEAT.md` موجودًا لكنه فارغ فعليًا (يحتوي فقط على أسطر فارغة وعناوين markdown +مثل `# Heading`)، فإن OpenClaw يتخطى تشغيل Heartbeat لتوفير استدعاءات API. +ويتم الإبلاغ عن هذا التخطي باعتباره `reason=empty-heartbeat-file`. +أما إذا كان الملف مفقودًا، فلا يزال Heartbeat يعمل ويقرر النموذج ما الذي ينبغي فعله. + +اجعله صغيرًا جدًا (قائمة تحقق قصيرة أو تذكيرات) لتجنب تضخم الموجّه. مثال على `HEARTBEAT.md`: @@ -356,8 +364,8 @@ channels: ### كتل `tasks:` -يدعم `HEARTBEAT.md` أيضًا كتلة `tasks:` مهيكلة صغيرة للفحوصات -المعتمدة على الفواصل داخل heartbeat نفسه. +يدعم `HEARTBEAT.md` أيضًا كتلة `tasks:` منظَّمة صغيرة لإجراء +فحوصات قائمة على الفواصل الزمنية داخل Heartbeat نفسه. مثال: @@ -379,72 +387,72 @@ tasks: السلوك: -- يقوم OpenClaw بتحليل كتلة `tasks:` والتحقق من كل مهمة مقابل `interval` الخاص بها. -- يتم تضمين المهام **المستحقة** فقط في مطالبة heartbeat لذلك التوقيت. -- إذا لم تكن هناك مهام مستحقة، يتم تخطي heartbeat بالكامل (`reason=no-tasks-due`) لتجنب استدعاء نموذج بلا فائدة. +- يحلل OpenClaw كتلة `tasks:` ويفحص كل مهمة وفق `interval` الخاص بها. +- لا يتم تضمين سوى المهام **المستحقة** في موجّه Heartbeat لتلك النبضة. +- إذا لم تكن هناك مهام مستحقة، يتم تخطي Heartbeat بالكامل (`reason=no-tasks-due`) لتجنب استدعاء نموذج غير ضروري. - يتم الاحتفاظ بالمحتوى غير المتعلق بالمهام في `HEARTBEAT.md` وإلحاقه كسياق إضافي بعد قائمة المهام المستحقة. -- تُخزَّن الطوابع الزمنية لآخر تشغيل للمهام في حالة الجلسة (`heartbeatTaskState`)، لذا تبقى الفواصل الزمنية محفوظة عبر عمليات إعادة التشغيل العادية. -- لا يتم تقديم الطوابع الزمنية للمهام إلا بعد أن يكمل تشغيل heartbeat مسار الرد الطبيعي. ولا تضع التشغيلات المتخطاة بسبب `empty-heartbeat-file` / `no-tasks-due` علامة على المهام على أنها مكتملة. +- تُخزَّن الطوابع الزمنية لآخر تشغيل للمهمة في حالة الجلسة (`heartbeatTaskState`)، لذلك تظل الفواصل الزمنية محفوظة عبر عمليات إعادة التشغيل العادية. +- لا تُقدَّم الطوابع الزمنية للمهام إلا بعد أن يكمل Heartbeat مسار رده العادي. أما تشغيلات `empty-heartbeat-file` / `no-tasks-due` المتخطاة فلا تضع علامة على المهام باعتبارها مكتملة. -يفيد وضع المهام عندما تريد أن يحتوي ملف heartbeat واحد على عدة فحوصات دورية من دون أن تدفع تكلفة جميعها في كل توقيت. +يفيد وضع المهام عندما تريد أن يحتوي ملف Heartbeat واحد على عدة فحوصات دورية من دون أن تدفع تكلفة جميعها في كل نبضة. ### هل يمكن للوكيل تحديث `HEARTBEAT.md`؟ نعم — إذا طلبت منه ذلك. -إن `HEARTBEAT.md` مجرد ملف عادي في مساحة عمل الوكيل، لذلك يمكنك أن تطلب من +إن `HEARTBEAT.md` مجرد ملف عادي في مساحة عمل الوكيل، لذا يمكنك أن تطلب من الوكيل (في دردشة عادية) شيئًا مثل: - “حدّث `HEARTBEAT.md` لإضافة فحص يومي للتقويم.” -- “أعد كتابة `HEARTBEAT.md` ليكون أقصر وأكثر تركيزًا على متابعات البريد الوارد.” +- “أعد كتابة `HEARTBEAT.md` ليصبح أقصر ويركز على متابعات البريد الوارد.” -إذا كنت تريد أن يحدث ذلك بشكل استباقي، فيمكنك أيضًا تضمين سطر صريح في -مطالبة heartbeat مثل: “If the checklist becomes stale, update HEARTBEAT.md -with a better one.” +إذا كنت تريد أن يحدث هذا بشكل استباقي، فيمكنك أيضًا تضمين سطر صريح في +موجّه Heartbeat مثل: “إذا أصبحت قائمة التحقق قديمة، فحدّث HEARTBEAT.md +بنسخة أفضل.” -ملاحظة أمان: لا تضع أسرارًا (مفاتيح API، أو أرقام هواتف، أو رموزًا خاصة) في -`HEARTBEAT.md` — لأنه يصبح جزءًا من سياق المطالبة. +ملاحظة أمان: لا تضع أسرارًا (مفاتيح API أو أرقام الهواتف أو الرموز الخاصة) داخل +`HEARTBEAT.md` — لأنه يصبح جزءًا من سياق الموجّه. ## إيقاظ يدوي (عند الطلب) -يمكنك صف نظام حدث وتشغيل heartbeat فوري باستخدام: +يمكنك إدراج حدث نظام وتشغيل Heartbeat فوري باستخدام: ```bash openclaw system event --text "Check for urgent follow-ups" --mode now ``` -إذا كان عدة وكلاء لديهم `heartbeat` مكوّنًا، فإن الإيقاظ اليدوي يشغّل heartbeats -الخاصة بكل واحد من هؤلاء الوكلاء فورًا. +إذا كان لدى عدة وكلاء إعداد `heartbeat`، فإن الإيقاظ اليدوي يشغّل Heartbeats الخاصة بكل واحد منهم +فورًا. -استخدم `--mode next-heartbeat` للانتظار حتى التوقيت المجدول التالي. +استخدم `--mode next-heartbeat` للانتظار حتى النبضة المجدولة التالية. -## تسليم Reasoning ‏(اختياري) +## تسليم الاستدلال (اختياري) -افتراضيًا، تسلّم heartbeats حمولة “الإجابة” النهائية فقط. +افتراضيًا، تسلّم Heartbeats حمولة “الإجابة” النهائية فقط. -إذا كنت تريد الشفافية، ففعّل: +إذا كنت تريد مزيدًا من الشفافية، ففعّل: - `agents.defaults.heartbeat.includeReasoning: true` -عند التمكين، ستسلّم heartbeats أيضًا رسالة منفصلة مسبوقة بـ -`Reasoning:` ‏(بنفس شكل `/reasoning on`). وقد يكون هذا مفيدًا عندما يكون الوكيل -يدير جلسات/codexes متعددة وتريد معرفة سبب قراره بتنبيهك — -لكنه قد يكشف أيضًا تفاصيل داخلية أكثر مما تريد. ويفضل إبقاؤه -معطّلًا في الدردشات الجماعية. +عند التفعيل، ستسلّم Heartbeats أيضًا رسالة منفصلة مسبوقة بـ +`Reasoning:` (بالصيغة نفسها مثل `/reasoning on`). وقد يكون هذا مفيدًا عندما يكون الوكيل +يدير عدة جلسات/نسخ Codex وتريد أن ترى لماذا قرر أن ينبهك — +لكنه قد يكشف أيضًا تفاصيل داخلية أكثر مما تريد. لذا يُفضَّل إبقاؤه +معطلًا في الدردشات الجماعية. ## الوعي بالتكلفة -تشغّل Heartbeats أدوار وكيل كاملة. وكلما كانت الفواصل أقصر زادت تكلفة الرموز. لتقليل التكلفة: +تشغّل Heartbeats أدوار وكيل كاملة. الفواصل الأقصر تستهلك رموزًا أكثر. لتقليل التكلفة: -- استخدم `isolatedSession: true` لتجنب إرسال السجل الكامل للمحادثة (تقريبًا من ~100K رمز إلى ~2-5K لكل تشغيل). -- استخدم `lightContext: true` لحصر ملفات bootstrap في `HEARTBEAT.md` فقط. -- عيّن `model` أرخص (مثل `ollama/llama3.2:1b`). -- أبقِ `HEARTBEAT.md` صغيرًا. +- استخدم `isolatedSession: true` لتجنب إرسال سجل المحادثة الكامل (من ~100 ألف رمز إلى ~2-5 آلاف لكل تشغيل). +- استخدم `lightContext: true` لقصر ملفات التمهيد على `HEARTBEAT.md` فقط. +- اضبط `model` أرخص (مثل `ollama/llama3.2:1b`). +- اجعل `HEARTBEAT.md` صغيرًا. - استخدم `target: "none"` إذا كنت تريد فقط تحديثات الحالة الداخلية. ## ذو صلة -- [Automation & Tasks](/automation) — جميع آليات الأتمتة في لمحة -- [Background Tasks](/automation/tasks) — كيفية تتبع العمل المنفصل -- [Timezone](/concepts/timezone) — كيف تؤثر المنطقة الزمنية في جدولة heartbeat -- [Troubleshooting](/automation/cron-jobs#troubleshooting) — تصحيح مشكلات الأتمتة +- [الأتمتة والمهام](/ar/automation) — نظرة عامة على جميع آليات الأتمتة +- [المهام الخلفية](/ar/automation/tasks) — كيفية تتبع العمل المنفصل +- [المنطقة الزمنية](/ar/concepts/timezone) — كيف تؤثر المنطقة الزمنية في جدولة Heartbeat +- [استكشاف الأخطاء وإصلاحها](/ar/automation/cron-jobs#troubleshooting) — تصحيح أخطاء مشكلات الأتمتة diff --git a/docs/ar/gateway/local-models.md b/docs/ar/gateway/local-models.md index cfd5aa1ba..dd71b2ff4 100644 --- a/docs/ar/gateway/local-models.md +++ b/docs/ar/gateway/local-models.md @@ -1,28 +1,28 @@ --- read_when: - تريد تقديم النماذج من جهاز GPU الخاص بك - - أنت توصل LM Studio أو proxy متوافقًا مع OpenAI - - تحتاج إلى أفضل إرشادات أمان للنماذج المحلية -summary: تشغيل OpenClaw على نماذج LLM محلية (LM Studio وvLLM وLiteLLM ونقاط نهاية OpenAI مخصصة) + - أنت تقوم بربط LM Studio أو وكيل متوافق مع OpenAI + - تحتاج إلى أكثر إرشادات النماذج المحلية أمانًا +summary: شغّل OpenClaw على نماذج LLM محلية (LM Studio وvLLM وLiteLLM ونقاط نهاية OpenAI مخصصة) title: النماذج المحلية x-i18n: - generated_at: "2026-04-05T12:43:06Z" + generated_at: "2026-04-08T02:14:58Z" model: gpt-5.4 provider: openai - source_hash: 3b99c8fb57f65c0b765fc75bd36933221b5aeb94c4a3f3428f92640ae064f8b6 + source_hash: d619d72b0e06914ebacb7e9f38b746caf1b9ce8908c9c6638c3acdddbaa025e8 source_path: gateway/local-models.md workflow: 15 --- # النماذج المحلية -النماذج المحلية ممكنة، لكن OpenClaw يتوقع سياقًا كبيرًا + دفاعات قوية ضد حقن المطالبات. البطاقات الصغيرة تقطع السياق وتضعف الأمان. استهدف مستوى عالٍ: **≥2 من أجهزة Mac Studio بمواصفات قصوى أو جهاز GPU مكافئ (~30 ألف دولار فأكثر)**. تعمل وحدة **24 GB** GPU واحدة فقط مع المطالبات الأخف وبزمن استجابة أعلى. استخدم **أكبر / النسخة الكاملة من النموذج التي يمكنك تشغيلها**؛ إذ إن نقاط الفحص المكممة بشدة أو “الصغيرة” ترفع خطر حقن المطالبات (راجع [Security](/gateway/security)). +التشغيل المحلي ممكن، لكن OpenClaw يتوقع سياقًا كبيرًا + وسائل دفاع قوية ضد حقن المطالبات. البطاقات الصغيرة تقتطع السياق وتسرّب الأمان. استهدف مستوى مرتفعًا: **استوديوهين Mac Studio ممتلئين بالمواصفات على الأقل أو جهاز GPU مكافئ (~$30k+)**. تعمل وحدة **24 GB** GPU واحدة فقط مع المطالبات الأخف وزمن استجابة أعلى. استخدم **أكبر / النسخة الكاملة من النموذج التي يمكنك تشغيلها**؛ إذ إن نقاط التحقق المكمّمة بشدة أو “الصغيرة” تزيد من خطر حقن المطالبات (راجع [الأمان](/ar/gateway/security)). -إذا كنت تريد أقل إعداد محلي احتكاكًا، فابدأ بـ [Ollama](/providers/ollama) و`openclaw onboard`. هذه الصفحة هي الدليل العملي الموجّه للحِزم المحلية الأعلى مستوى وخوادم OpenAI-compatible المحلية المخصصة. +إذا كنت تريد أقل إعداد محلي احتكاكًا، فابدأ بـ [Ollama](/ar/providers/ollama) و`openclaw onboard`. هذه الصفحة هي الدليل العملي الموجّه للإعدادات المحلية الأعلى مستوى وخوادم OpenAI المحلية المخصصة المتوافقة. ## الموصى به: LM Studio + نموذج محلي كبير (Responses API) -أفضل حزمة محلية حاليًا. حمّل نموذجًا كبيرًا في LM Studio (مثل إصدار كامل من Qwen أو DeepSeek أو Llama)، وفعّل الخادم المحلي (الافتراضي `http://127.0.0.1:1234`)، واستخدم Responses API لإبقاء الاستدلال منفصلًا عن النص النهائي. +أفضل بنية محلية حالية. حمّل نموذجًا كبيرًا في LM Studio (على سبيل المثال، إصدارًا كامل الحجم من Qwen أو DeepSeek أو Llama)، ثم فعّل الخادم المحلي (الافتراضي `http://127.0.0.1:1234`)، واستخدم Responses API لإبقاء الاستدلال منفصلًا عن النص النهائي. ```json5 { @@ -59,18 +59,18 @@ x-i18n: } ``` -**قائمة التحقق للإعداد** +**قائمة الإعداد** - ثبّت LM Studio: [https://lmstudio.ai](https://lmstudio.ai) -- في LM Studio، نزّل **أكبر إصدار نموذج متاح** (تجنب الإصدارات “الصغيرة”/المكممة بشدة)، وابدأ الخادم، وتأكد من أن `http://127.0.0.1:1234/v1/models` يسرده. +- في LM Studio، نزّل **أكبر إصدار نموذج متاح** (تجنب المتغيرات “الصغيرة”/المكمّمة بشدة)، ثم شغّل الخادم، وتأكد من أن `http://127.0.0.1:1234/v1/models` يعرضه. - استبدل `my-local-model` بمعرّف النموذج الفعلي الظاهر في LM Studio. -- أبقِ النموذج محمّلًا؛ إذ تضيف البداية الباردة زمن تأخير عند بدء التشغيل. -- اضبط `contextWindow`/`maxTokens` إذا كان إصدار LM Studio لديك يختلف. -- بالنسبة إلى WhatsApp، التزم بـ Responses API بحيث يُرسل النص النهائي فقط. +- أبقِ النموذج محمّلًا؛ فالتحميل البارد يضيف زمن تأخير عند البدء. +- عدّل `contextWindow`/`maxTokens` إذا كان إصدار LM Studio لديك مختلفًا. +- بالنسبة إلى WhatsApp، التزم بـ Responses API حتى يُرسَل النص النهائي فقط. -أبقِ النماذج المستضافة مكوّنة حتى عند التشغيل محليًا؛ استخدم `models.mode: "merge"` حتى تظل fallbacks متاحة. +أبقِ النماذج المستضافة مضبوطة حتى عند التشغيل المحلي؛ استخدم `models.mode: "merge"` حتى تبقى خيارات الرجوع الاحتياطي متاحة. -### تكوين هجين: مستضاف كأساسي، ومحلي كرجوع احتياطي +### إعداد هجين: أساسي مستضاف، واحتياطي محلي ```json5 { @@ -113,16 +113,16 @@ x-i18n: ### محلي أولًا مع شبكة أمان مستضافة -بدّل ترتيب الأساسي والرجوع الاحتياطي؛ وأبقِ كتلة providers نفسها و`models.mode: "merge"` حتى تتمكن من الرجوع إلى Sonnet أو Opus عندما يتوقف الجهاز المحلي. +بدّل ترتيب الأساسي والاحتياطي؛ وأبقِ كتلة providers نفسها و`models.mode: "merge"` حتى تتمكن من الرجوع إلى Sonnet أو Opus عندما يتعطل الجهاز المحلي. ### الاستضافة الإقليمية / توجيه البيانات -- توجد أيضًا إصدارات MiniMax/Kimi/GLM المستضافة على OpenRouter مع نقاط نهاية مثبتة على مناطق محددة (مثل الاستضافة في الولايات المتحدة). اختر الإصدار الإقليمي هناك للحفاظ على حركة البيانات ضمن النطاق القضائي الذي تختاره مع الاستمرار في استخدام `models.mode: "merge"` لعمليات الرجوع الاحتياطي إلى Anthropic/OpenAI. -- يظل التشغيل المحلي فقط هو أقوى مسار للخصوصية؛ أما التوجيه الإقليمي المستضاف فهو حل وسط عندما تحتاج إلى ميزات المزوّد ولكنك تريد التحكم في تدفق البيانات. +- تتوفر أيضًا متغيرات MiniMax/Kimi/GLM المستضافة على OpenRouter مع نقاط نهاية مثبّتة على مناطق محددة (مثل الاستضافة داخل الولايات المتحدة). اختر المتغير الإقليمي هناك للحفاظ على حركة المرور ضمن الولاية القضائية التي تختارها مع الاستمرار في استخدام `models.mode: "merge"` لخيارات الرجوع الاحتياطي من Anthropic/OpenAI. +- يظل التشغيل المحلي فقط هو المسار الأقوى للخصوصية؛ أما التوجيه الإقليمي المستضاف فهو الحل الوسط عندما تحتاج إلى ميزات المزوّد لكنك تريد التحكم في تدفق البيانات. -## Proxies محلية أخرى متوافقة مع OpenAI +## وكلاء محليون آخرون متوافقون مع OpenAI -تعمل vLLM وLiteLLM وOAI-proxy أو gateways المخصصة إذا كانت تعرض نقطة نهاية `/v1` بأسلوب OpenAI. استبدل كتلة provider أعلاه بنقطة النهاية ومعرّف النموذج لديك: +تعمل vLLM وLiteLLM وOAI-proxy أو البوابات المخصصة إذا كانت تعرض نقطة نهاية `/v1` بأسلوب OpenAI. استبدل كتلة provider أعلاه بنقطة النهاية ومعرّف النموذج الخاصين بك: ```json5 { @@ -150,21 +150,42 @@ x-i18n: } ``` -أبقِ `models.mode: "merge"` حتى تظل النماذج المستضافة متاحة كخيارات fallback. +أبقِ `models.mode: "merge"` حتى تظل النماذج المستضافة متاحة كخيارات رجوع احتياطي. -ملاحظة سلوكية لخلفيات `/v1` المحلية/الممررة عبر proxy: +ملاحظة سلوكية لواجهات `/v1` المحلية/الوسيطة: -- يتعامل OpenClaw مع هذه المسارات باعتبارها مسارات OpenAI-compatible بنمط proxy، وليس - كنقاط نهاية OpenAI أصلية +- يتعامل OpenClaw مع هذه الواجهات على أنها مسارات وكيل متوافقة مع OpenAI، وليست + نقاط نهاية OpenAI أصلية - لا ينطبق هنا تشكيل الطلبات الخاص بـ OpenAI الأصلية فقط: لا - `service_tier`، ولا `store` الخاصة بـ Responses، ولا تشكيل حمولة - التوافق مع reasoning في OpenAI، ولا تلميحات prompt-cache -- لا يتم حقن رؤوس الإسناد المخفية الخاصة بـ OpenClaw (`originator`, `version`, `User-Agent`) - في عناوين proxy المخصصة هذه + يوجد `service_tier`، ولا `store` الخاص بـ Responses، ولا تشكيل حمولة + التوافق مع الاستدلال الخاص بـ OpenAI، ولا تلميحات لذاكرة التخزين المؤقت للمطالبات +- لا يتم حقن ترويسات الإسناد المخفية الخاصة بـ OpenClaw (`originator` و`version` و`User-Agent`) + على عناوين URL الخاصة بهذه الوكلاء المخصصة + +ملاحظات التوافق لواجهات OpenAI المتوافقة الأكثر صرامة: + +- تقبل بعض الخوادم فقط `messages[].content` كسلسلة نصية في Chat Completions، وليس + مصفوفات أجزاء المحتوى المهيكلة. اضبط + `models.providers..models[].compat.requiresStringContent: true` لهذه + النقاط. +- بعض الواجهات المحلية الأصغر أو الأكثر صرامة تكون غير مستقرة مع الشكل الكامل + لمطالبة بيئة تشغيل الوكيل في OpenClaw، خاصة عند تضمين مخططات الأدوات. إذا كانت + الواجهة تعمل مع استدعاءات `/v1/chat/completions` المباشرة الصغيرة ولكنها تفشل في + الأدوار العادية لوكيل OpenClaw، فجرّب + `models.providers..models[].compat.supportsTools: false` أولًا. +- إذا كانت الواجهة لا تزال تفشل فقط في تشغيلات OpenClaw الأكبر، فعادةً ما تكون + المشكلة المتبقية في سعة النموذج/الخادم upstream أو في خطأ في الواجهة الخلفية، + وليس في طبقة النقل الخاصة بـ OpenClaw. ## استكشاف الأخطاء وإصلاحها -- هل يستطيع gateway الوصول إلى proxy؟ ‏`curl http://127.0.0.1:1234/v1/models`. -- هل تم إلغاء تحميل نموذج LM Studio؟ أعد تحميله؛ فالبداية الباردة سبب شائع لحالة “التعليق”. -- أخطاء السياق؟ خفّض `contextWindow` أو ارفع حد الخادم لديك. -- الأمان: تتجاوز النماذج المحلية عوامل التصفية من جهة المزوّد؛ لذا أبقِ الوكلاء محدودين وشغّل الضغط للحد من نطاق تأثير حقن المطالبات. +- هل تستطيع البوابة الوصول إلى الوكيل؟ `curl http://127.0.0.1:1234/v1/models`. +- هل تم إلغاء تحميل نموذج LM Studio؟ أعد تحميله؛ فالبدء البارد سبب شائع لـ “التعليق”. +- أخطاء في السياق؟ خفّض `contextWindow` أو ارفع حد الخادم. +- هل يعيد الخادم المتوافق مع OpenAI الخطأ `messages[].content ... expected a string`؟ + أضف `compat.requiresStringContent: true` إلى إدخال ذلك النموذج. +- تعمل استدعاءات `/v1/chat/completions` المباشرة الصغيرة، لكن `openclaw infer model run` + يفشل على Gemma أو نموذج محلي آخر؟ عطّل مخططات الأدوات أولًا عبر + `compat.supportsTools: false`، ثم أعد الاختبار. إذا استمر الخادم في التعطل فقط + مع مطالبات OpenClaw الأكبر، فاعتبر ذلك قيدًا في الخادم/النموذج upstream. +- الأمان: تتجاوز النماذج المحلية عوامل التصفية الموجودة لدى المزوّد؛ أبقِ الوكلاء محدودي النطاق وفعّل الضغط لتقليل نطاق تأثير حقن المطالبات. diff --git a/docs/ar/gateway/protocol.md b/docs/ar/gateway/protocol.md index 3ed716b72..3eb482130 100644 --- a/docs/ar/gateway/protocol.md +++ b/docs/ar/gateway/protocol.md @@ -1,32 +1,32 @@ --- read_when: - - تنفيذ أو تحديث عملاء gateway عبر WS - - تصحيح أخطاء عدم تطابق البروتوكول أو فشل الاتصال - - إعادة توليد schema/models الخاصة بالبروتوكول + - تنفيذ عملاء WS للبوابة أو تحديثهم + - تصحيح حالات عدم تطابق البروتوكول أو فشل الاتصال + - إعادة توليد مخطط/نماذج البروتوكول summary: 'بروتوكول Gateway عبر WebSocket: المصافحة، والإطارات، والإصدارات' title: بروتوكول Gateway x-i18n: - generated_at: "2026-04-05T12:44:58Z" + generated_at: "2026-04-08T02:16:02Z" model: gpt-5.4 provider: openai - source_hash: c37f5b686562dda3ba3516ac6982ad87b2f01d8148233284e9917099c6e96d87 + source_hash: 8635e3ac1dd311dbd3a770b088868aa1495a8d53b3ebc1eae0dfda3b2bf4694a source_path: gateway/protocol.md workflow: 15 --- -# بروتوكول Gateway ‏(WebSocket) +# بروتوكول Gateway (WebSocket) -بروتوكول Gateway WS هو **سطح التحكم الوحيد + نقل العقد** لـ -OpenClaw. فجميع العملاء (CLI وواجهة الويب وتطبيق macOS وعقد iOS/Android والعقد -عديمة الرأس) يتصلون عبر WebSocket ويعلنون **الدور** + **النطاق** الخاصين بهم وقت -المصافحة. +يُعد بروتوكول Gateway عبر WS **مستوى التحكم الوحيد + ناقل العقد** في +OpenClaw. جميع العملاء (CLI، وواجهة الويب، وتطبيق macOS، وعقد iOS/Android، والعقد +عديمة الواجهة) يتصلون عبر WebSocket ويعلنون **الدور** + **النطاق** +في وقت المصافحة. ## النقل - WebSocket، وإطارات نصية بحمولات JSON. - **يجب** أن يكون الإطار الأول طلب `connect`. -## المصافحة (`connect`) +## المصافحة (connect) Gateway → العميل (تحدي ما قبل الاتصال): @@ -84,7 +84,7 @@ Gateway → العميل: } ``` -عند إصدار device token، تتضمن `hello-ok` أيضًا: +عند إصدار رمز جهاز، يتضمن `hello-ok` أيضًا: ```json { @@ -96,8 +96,8 @@ Gateway → العميل: } ``` -أثناء تسليم bootstrap الموثوق، قد تتضمن `hello-ok.auth` أيضًا إدخالات -أدوار إضافية محدودة ضمن `deviceTokens`: +أثناء تسليم bootstrap الموثوق، قد يتضمن `hello-ok.auth` أيضًا +إدخالات أدوار إضافية مقيّدة في `deviceTokens`: ```json { @@ -116,14 +116,14 @@ Gateway → العميل: } ``` -في تدفق bootstrap المضمّن للعقدة/المشغّل، يبقى token الأساسي للعقدة -`scopes: []` وتبقى أي token للمشغّل مسلّمة ضمن الحدود -المقيدة بقائمة سماح bootstrap للمشغّل (`operator.approvals`, `operator.read`, -`operator.talk.secrets`, `operator.write`). وتظل فحوصات نطاق bootstrap -مرتبطة ببادئة الدور: إذ لا تلبّي إدخالات المشغّل إلا طلبات المشغّل، وما تزال -الأدوار غير المشغّلة تحتاج إلى نطاقات تحت بادئة دورها الخاصة. +في تدفق bootstrap المضمّن للعقدة/المشغّل، يظل رمز العقدة الأساسي +`scopes: []` وأي رمز مشغّل تم تسليمه يظل مقيّدًا بقائمة السماح الخاصة بمشغّل bootstrap +(`operator.approvals`، و`operator.read`، +و`operator.talk.secrets`، و`operator.write`). تظل فحوصات نطاق bootstrap +مسبوقة بالدور: إدخالات المشغّل لا تلبّي إلا طلبات المشغّل، وما زالت الأدوار +غير المشغّلة تحتاج إلى نطاقات ضمن بادئة دورها الخاصة. -### مثال عقدة +### مثال على عقدة ```json { @@ -164,16 +164,16 @@ Gateway → العميل: - **استجابة**: `{type:"res", id, ok, payload|error}` - **حدث**: `{type:"event", event, payload, seq?, stateVersion?}` -تتطلب الطرق ذات الآثار الجانبية **مفاتيح idempotency** ‏(راجع schema). +تتطلب الأساليب ذات الآثار الجانبية **مفاتيح idempotency** (راجع المخطط). ## الأدوار + النطاقات ### الأدوار -- `operator` = عميل سطح التحكم (CLI/UI/الأتمتة). -- `node` = مضيف الإمكانات (`camera/screen/canvas/system.run`). +- `operator` = عميل مستوى التحكم (CLI/واجهة المستخدم/الأتمتة). +- `node` = مضيف الإمكانات (camera/screen/canvas/system.run). -### النطاقات (`operator`) +### النطاقات (operator) النطاقات الشائعة: @@ -187,407 +187,417 @@ Gateway → العميل: يتطلب `talk.config` مع `includeSecrets: true` النطاق `operator.talk.secrets` (أو `operator.admin`). -قد تطلب طرق Gateway RPC المسجلة من المكونات الإضافية نطاق operator خاصًا بها، لكن -بادئات الإدارة الأساسية المحجوزة (`config.*`, `exec.approvals.*`, `wizard.*`, -`update.*`) تُحل دائمًا إلى `operator.admin`. +يمكن لأساليب RPC الخاصة بالبوابة والمسجَّلة من الإضافات أن تطلب نطاق operator خاصًا بها، لكن +بادئات الإدارة الأساسية المحجوزة (`config.*`، و`exec.approvals.*`، و`wizard.*`، +و`update.*`) تُحل دائمًا إلى `operator.admin`. -يمثل نطاق الطريقة البوابة الأولى فقط. إذ تطبق بعض الأوامر المائلة التي تصل عبر -`chat.send` فحوصات أشد على مستوى الأمر فوق ذلك. فعلى سبيل المثال، تتطلب -عمليات الكتابة الدائمة عبر `/config set` و`/config unset` النطاق `operator.admin`. +نطاق الأسلوب ليس سوى البوابة الأولى. بعض أوامر الشرطة المائلة التي يتم الوصول إليها +عبر `chat.send` تطبق فحوصات على مستوى الأمر أكثر صرامة فوق ذلك. على سبيل المثال، +تتطلب عمليات الكتابة الدائمة في `/config set` و`/config unset` النطاق `operator.admin`. -كما يملك `node.pair.approve` فحص نطاق إضافيًا وقت الموافقة فوق -نطاق الطريقة الأساسي: +يحتوي `node.pair.approve` أيضًا على فحص نطاق إضافي في وقت الموافقة فوق نطاق +الأسلوب الأساسي: -- الطلبات من دون أوامر: `operator.pairing` -- الطلبات التي تحتوي على أوامر عقدة غير `exec`: ‏`operator.pairing` + `operator.write` -- الطلبات التي تتضمن `system.run`, `system.run.prepare`, أو `system.which`: - ‏`operator.pairing` + `operator.admin` +- الطلبات بلا أوامر: `operator.pairing` +- الطلبات التي تتضمن أوامر عقدة غير تنفيذية: `operator.pairing` + `operator.write` +- الطلبات التي تتضمن `system.run` أو `system.run.prepare` أو `system.which`: + `operator.pairing` + `operator.admin` -### `caps`/`commands`/`permissions` ‏(`node`) +### caps/commands/permissions (node) -تعلن العقد مطالبات الإمكانات وقت الاتصال: +تعلن العقد مطالبات الإمكانات في وقت الاتصال: -- `caps`: فئات إمكانات عالية المستوى. +- `caps`: فئات الإمكانات عالية المستوى. - `commands`: قائمة سماح الأوامر للاستدعاء. -- `permissions`: مفاتيح تبديل دقيقة (مثل `screen.record`, `camera.capture`). +- `permissions`: مفاتيح تبديل دقيقة (مثل `screen.record` و`camera.capture`). -يتعامل Gateway مع هذه القيم على أنها **مطالبات** ويفرض قوائم سماح من جانب الخادم. +يتعامل Gateway مع هذه القيم على أنها **مطالبات** ويفرض قوائم سماح من جهة الخادم. ## الحضور -- تعيد `system-presence` إدخالات مفاتيحها حسب هوية الجهاز. -- تتضمن إدخالات الحضور `deviceId`, `roles`, و`scopes` لكي تتمكن واجهات المستخدم من عرض صف واحد لكل جهاز - حتى عندما يتصل بصفته **operator** و**node** معًا. +- يعيد `system-presence` إدخالات مفهرسة بحسب هوية الجهاز. +- تتضمن إدخالات الحضور `deviceId`، و`roles`، و`scopes` حتى تتمكن واجهات المستخدم من عرض صف واحد لكل جهاز + حتى عندما يتصل بوصفه **operator** و**node** معًا. -## عائلات طرق RPC الشائعة +## عائلات أساليب RPC الشائعة -ليست هذه الصفحة تفريغًا مولّدًا كاملًا، لكن السطح العام لـ WS أوسع -من أمثلة المصافحة/المصادقة أعلاه. وهذه هي عائلات الطرق الرئيسية التي يعرضها -Gateway اليوم. +هذه الصفحة ليست تفريغًا كاملاً مولدًا، لكن سطح 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` بالإضافة إلى صادرات أساليب الإضافات/القنوات المحمَّلة. +تعامل معها بوصفها لاكتشاف الميزات، لا بوصفها تفريغًا مولدًا لكل دالة قابلة للاستدعاء +تم تنفيذها في `src/gateway/server-methods/*.ts`. ### النظام والهوية -- تعيد `health` لقطة السلامة المخزنة مؤقتًا أو المفحوصة حديثًا للـ gateway. -- تعيد `status` ملخص gateway بنمط `/status`؛ وتُضمّن الحقول الحساسة - فقط لعملاء operator ذوي النطاق الإداري. -- تعيد `gateway.identity.get` هوية جهاز gateway المستخدمة في relay - وتدفقات الاقتران. -- تعيد `system-presence` لقطة الحضور الحالية للأجهزة المتصلة - operator/node. +- يعيد `health` لقطة صحة البوابة المخزنة مؤقتًا أو التي تم فحصها حديثًا. +- يعيد `status` ملخص البوابة على نمط `/status`؛ ويتم + تضمين الحقول الحساسة فقط لعملاء operator ذوي نطاق الإدارة. +- يعيد `gateway.identity.get` هوية جهاز البوابة المستخدمة في + تدفقات relay والاقتران. +- يعيد `system-presence` لقطة الحضور الحالية للأجهزة المتصلة + بوصفها operator/node. - يضيف `system-event` حدث نظام ويمكنه تحديث/بث سياق الحضور. -- تعيد `last-heartbeat` أحدث حدث heartbeat محفوظ. -- يبدّل `set-heartbeats` معالجة heartbeat على الـ gateway. +- يعيد `last-heartbeat` أحدث حدث heartbeat محفوظ. +- يقوم `set-heartbeats` بتبديل معالجة heartbeat على البوابة. ### النماذج والاستخدام -- تعيد `models.list` فهرس النماذج المسموح بها وقت التشغيل. -- تعيد `usage.status` ملخصات نوافذ استخدام المزوّد/الحصة المتبقية. -- تعيد `usage.cost` ملخصات مجمعة لاستخدام التكلفة لنطاق زمني. -- تعيد `doctor.memory.status` جاهزية الذاكرة المتجهية / embedding لمساحة عمل - الوكيل الافتراضي النشطة. -- تعيد `sessions.usage` ملخصات استخدام لكل جلسة. -- تعيد `sessions.usage.timeseries` سلسلة زمنية للاستخدام لجلسة واحدة. -- تعيد `sessions.usage.logs` إدخالات سجل الاستخدام لجلسة واحدة. +- يعيد `models.list` فهرس النماذج المسموح بها في بيئة التشغيل. +- يعيد `usage.status` ملخصات نوافذ استخدام الموفر/الحصة المتبقية. +- يعيد `usage.cost` ملخصات استخدام التكلفة المجمعة لنطاق تاريخ. +- يعيد `doctor.memory.status` جاهزية الذاكرة المتجهية / التضمين + لمساحة عمل الوكيل الافتراضي النشط. +- يعيد `sessions.usage` ملخصات الاستخدام لكل جلسة. +- يعيد `sessions.usage.timeseries` سلسلة زمنية للاستخدام لجلسة واحدة. +- يعيد `sessions.usage.logs` إدخالات سجل الاستخدام لجلسة واحدة. ### القنوات ومساعدات تسجيل الدخول -- تعيد `channels.status` ملخصات حالة القنوات/المكونات الإضافية - المضمّنة والمجمّعة. -- تسجّل `channels.logout` الخروج من قناة/حساب محدد حيث تدعم القناة - تسجيل الخروج. -- تبدأ `web.login.start` تدفق تسجيل دخول QR/ويب للقناة الحالية - القابلة لتسجيل دخول QR على الويب. -- تنتظر `web.login.wait` اكتمال تدفق تسجيل دخول QR/الويب ذاك وتبدأ +- يعيد `channels.status` ملخصات حالة القنوات/الإضافات المضمّنة والمجمعة. +- يقوم `channels.logout` بتسجيل الخروج من قناة/حساب محدد حيث + تدعم القناة تسجيل الخروج. +- يبدأ `web.login.start` تدفق تسجيل دخول QR/ويب للموفر + الحالي لقناة الويب القادرة على QR. +- ينتظر `web.login.wait` اكتمال تدفق تسجيل دخول QR/ويب ويبدأ القناة عند النجاح. -- ترسل `push.test` دفعة APNs اختبارية إلى عقدة iOS مسجّلة. -- تعيد `voicewake.get` محفزات كلمة التنبيه المخزنة. -- تحدّث `voicewake.set` محفزات كلمة التنبيه وتبث التغيير. +- يرسل `push.test` إشعار APNs تجريبيًا إلى عقدة iOS مسجّلة. +- يعيد `voicewake.get` محفزات كلمة التنبيه المخزنة. +- يحدّث `voicewake.set` محفزات كلمة التنبيه ويبث التغيير. ### المراسلة والسجلات -- `send` هو RPC التسليم الصادر المباشر للإرسال الموجّه إلى قناة/حساب/سلسلة - خارج مشغّل الدردشة. -- تعيد `logs.tail` ذيل سجل ملف gateway المكوَّن مع أدوات - المؤشر/الحدود والتحكم في أقصى عدد من البايتات. +- `send` هو RPC التسليم الصادر المباشر للرسائل + الموجهة إلى قناة/حساب/سلسلة خارج مشغّل الدردشة. +- يعيد `logs.tail` ذيل سجل ملفات البوابة المضبوط مع المؤشر/الحد + وعناصر التحكم في الحد الأقصى للبايتات. ### Talk وTTS -- تعيد `talk.config` حمولة إعداد Talk الفعالة؛ ويتطلب `includeSecrets` - النطاق `operator.talk.secrets` ‏(أو `operator.admin`). -- تضبط `talk.mode`/تبث حالة وضع Talk الحالية لعملاء WebChat/Control UI. -- تولد `talk.speak` كلامًا من خلال مزود الكلام النشط في Talk. -- تعيد `tts.status` حالة تفعيل TTS، والمزوّد النشط، ومزوّدي fallback، - وحالة إعداد المزوّد. -- تعيد `tts.providers` جرد مزوّدي TTS المرئيين. -- تبدّل `tts.enable` و`tts.disable` حالة تفضيلات TTS. -- تحدّث `tts.setProvider` المزوّد المفضّل لـ TTS. -- تشغّل `tts.convert` تحويل text-to-speech لمرة واحدة. +- يعيد `talk.config` حمولة إعداد Talk الفعالة؛ ويتطلب `includeSecrets` + النطاق `operator.talk.secrets` (أو `operator.admin`). +- يضبط `talk.mode` حالة وضع Talk الحالية ويبثها لعملاء + WebChat/Control UI. +- يقوم `talk.speak` بتوليف الكلام عبر موفر كلام Talk النشط. +- يعيد `tts.status` حالة تمكين TTS، والموفر النشط، وموفري البدائل، + وحالة إعداد الموفر. +- يعيد `tts.providers` قائمة موفري TTS المرئية. +- يقوم `tts.enable` و`tts.disable` بتبديل حالة تفضيلات TTS. +- يحدّث `tts.setProvider` موفر TTS المفضل. +- يشغّل `tts.convert` تحويل نص إلى كلام لمرة واحدة. ### الأسرار، والإعداد، والتحديث، والمعالج -- تعيد `secrets.reload` حل SecretRefs النشطة وتبدّل حالة الأسرار وقت التشغيل +- يعيد `secrets.reload` حل SecretRefs النشطة ويبدّل حالة الأسرار في وقت التشغيل فقط عند النجاح الكامل. -- تحل `secrets.resolve` إسنادات الأسرار المستهدفة بالأوامر لمجموعة - أوامر/أهداف محددة. -- تعيد `config.get` لقطة الإعداد الحالية وhash الخاص بها. -- تكتب `config.set` حمولة إعداد مُتحققًا من صحتها. -- تدمج `config.patch` تحديثًا جزئيًا للإعداد. -- تتحقق `config.apply` + تستبدل حمولة الإعداد الكاملة. -- تعيد `config.schema` حمولة schema الحية للإعداد المستخدمة بواسطة Control UI و - أدوات CLI: ‏schema، و`uiHints`، والإصدار، وبيانات التوليد الوصفية، بما في ذلك - بيانات schema الوصفية للمكونات الإضافية + القنوات عندما يستطيع وقت التشغيل تحميلها. وتتضمن schema - بيانات `title` / `description` الوصفية للحقول المشتقة من التسميات نفسها - ونصوص المساعدة المستخدمة في UI، بما في ذلك فروع - التركيب الخاصة بالكائنات المتداخلة، والرمز الشامل، وعناصر المصفوفات، - و`anyOf` / `oneOf` / `allOf` عندما توجد وثائق حقول مطابقة. -- تعيد `config.schema.lookup` حمولة lookup محددة بالمسار لمسار إعداد - واحد: المسار المطبع، وعقدة schema سطحية، وhint مطابق + `hintPath`، و - ملخصات الأبناء المباشرين للتعمق في UI/CLI. - - تحتفظ عقد schema الخاصة بالlookup بالوثائق الموجهة للمستخدم - وحقول التحقق الشائعة: - `title`, `description`, `type`, `enum`, `const`, `format`, `pattern`, - وحدود الأعداد/السلاسل/المصفوفات/الكائنات، والأعلام المنطقية مثل - `additionalProperties`, `deprecated`, `readOnly`, `writeOnly`. - - تعرض ملخصات الأبناء `key`, و`path` المطبع، و`type`, و`required`, +- يقوم `secrets.resolve` بحل تعيينات الأسرار المستهدفة للأوامر لمجموعة + أمر/هدف محددة. +- يعيد `config.get` لقطة الإعداد الحالية وتجزئتها. +- يكتب `config.set` حمولة إعداد تم التحقق من صحتها. +- يدمج `config.patch` تحديث إعداد جزئيًا. +- يتحقق `config.apply` من حمولة الإعداد الكاملة ويستبدلها. +- يعيد `config.schema` حمولة مخطط الإعداد المباشر المستخدمة بواسطة Control UI و + أدوات CLI: المخطط، و`uiHints`، والإصدار، وبيانات التوليد الوصفية، بما في ذلك + بيانات مخطط الإضافات + القنوات الوصفية عندما تستطيع بيئة التشغيل تحميلها. يتضمن + المخطط بيانات الحقل `title` / `description` + المشتقة من التسميات نفسها ونصوص المساعدة التي تستخدمها واجهة المستخدم، بما في ذلك + الكائنات المتداخلة، والبدائل العامة، وعناصر المصفوفات، + وفروع التركيب `anyOf` / `oneOf` / `allOf` عندما توجد + وثائق حقل مطابقة. +- يعيد `config.schema.lookup` حمولة بحث محصورة بمسار لإعداد واحد + لمسار إعداد واحد: مسار مُطبَّع، وعقدة مخطط سطحية، وتلميح مطابق + `hintPath`، + وملخصات الأبناء المباشرين للتعمق عبر واجهة المستخدم/CLI. + - تحتفظ عقد مخطط البحث بوثائق المستخدم والحقول الشائعة للتحقق: + `title`، و`description`، و`type`، و`enum`، و`const`، و`format`، و`pattern`، + وحدود الأرقام/السلاسل/المصفوفات/الكائنات، والأعلام المنطقية مثل + `additionalProperties`، و`deprecated`، و`readOnly`، و`writeOnly`. + - تكشف ملخصات الأبناء `key`، و`path` المُطبَّع، و`type`، و`required`، و`hasChildren`، بالإضافة إلى `hint` / `hintPath` المطابقين. -- تشغّل `update.run` تدفق تحديث gateway وتجدول إعادة التشغيل فقط عندما +- يشغّل `update.run` تدفق تحديث البوابة ويجدول إعادة تشغيل فقط عندما ينجح التحديث نفسه. -- تعرض `wizard.start`, `wizard.next`, `wizard.status`, و`wizard.cancel` +- تكشف `wizard.start`، و`wizard.next`، و`wizard.status`، و`wizard.cancel` معالج الإعداد الأولي عبر WS RPC. ### العائلات الرئيسية الموجودة #### مساعدات الوكيل ومساحة العمل -- تعيد `agents.list` إدخالات الوكلاء المكوّنة. -- تدير `agents.create`, `agents.update`, و`agents.delete` سجلات الوكلاء - وربط مساحة العمل. -- تدير `agents.files.list`, `agents.files.get`, و`agents.files.set` ملفات - bootstrap الخاصة بمساحة العمل المعروضة لوكيل ما. -- تعيد `agent.identity.get` هوية المساعد الفعالة لوكيل أو +- يعيد `agents.list` إدخالات الوكلاء المضبوطة. +- تدير `agents.create`، و`agents.update`، و`agents.delete` سجلات الوكلاء و + ربط مساحة العمل. +- تدير `agents.files.list`، و`agents.files.get`، و`agents.files.set` + ملفات مساحة عمل bootstrap المعروضة لوكيل. +- يعيد `agent.identity.get` هوية المساعد الفعالة لوكيل أو جلسة. -- تنتظر `agent.wait` انتهاء تشغيل ما وتعيد اللقطة النهائية عند +- ينتظر `agent.wait` انتهاء التشغيل ويعيد اللقطة النهائية عند توفرها. -#### التحكم في الجلسة +#### التحكم في الجلسات -- تعيد `sessions.list` فهرس الجلسات الحالي. -- تبدّل `sessions.subscribe` و`sessions.unsubscribe` اشتراكات - تغييرات الجلسات لعميل WS الحالي. -- تبدّل `sessions.messages.subscribe` و`sessions.messages.unsubscribe` - اشتراكات أحداث النصوص/الرسائل لجلسة واحدة. -- تعيد `sessions.preview` معاينات نصوص محدودة لمفاتيح جلسات محددة. -- تحل `sessions.resolve` أو تحول إلى الصيغة القانونية هدف جلسة. +- يعيد `sessions.list` فهرس الجلسات الحالي. +- تقوم `sessions.subscribe` و`sessions.unsubscribe` بتبديل اشتراكات + أحداث تغيّر الجلسات لعميل WS الحالي. +- تقوم `sessions.messages.subscribe` و`sessions.messages.unsubscribe` بتبديل + اشتراكات أحداث السجل/الرسائل لجلسة واحدة. +- يعيد `sessions.preview` معاينات سجلات محصورة لمفاتيح جلسات + محددة. +- يقوم `sessions.resolve` بحل هدف جلسة أو جعله قياسيًا. - تنشئ `sessions.create` إدخال جلسة جديدًا. - ترسل `sessions.send` رسالة إلى جلسة موجودة. -- `sessions.steer` هو متغير المقاطعة والتوجيه لجلسة نشطة. -- توقف `sessions.abort` العمل النشط لجلسة. -- تحدّث `sessions.patch` بيانات الجلسة الوصفية/التجاوزات. -- تنفذ `sessions.reset`, `sessions.delete`, و`sessions.compact` صيانة - الجلسات. -- تعيد `sessions.get` صف الجلسة المخزن كاملًا. -- ما يزال تنفيذ الدردشة يستخدم `chat.history`, `chat.send`, `chat.abort`, و +- تمثل `sessions.steer` نسخة المقاطعة والتوجيه لجلسة نشطة. +- تقوم `sessions.abort` بإلغاء العمل النشط لجلسة. +- تحدّث `sessions.patch` البيانات الوصفية/التجاوزات الخاصة بالجلسة. +- تنفّذ `sessions.reset`، و`sessions.delete`، و`sessions.compact` + صيانة الجلسة. +- يعيد `sessions.get` صف الجلسة المخزَّن بالكامل. +- ما زال تنفيذ الدردشة يستخدم `chat.history`، و`chat.send`، و`chat.abort`، و `chat.inject`. -- يتم تطبيع `chat.history` للعرض لعملاء UI: حيث تُزال وسوم التعليمات المضمنة من النص المرئي، - وتُزال حمولات XML النصية العادية لاستدعاءات الأدوات (بما في ذلك - `...`, `...`, - `...`, `...`, و - كتل استدعاءات الأدوات المقتطعة)، كما تُزال رموز التحكم بالنموذج المسرّبة بصيغة ASCII/العرض الكامل، - وتُحذف صفوف المساعد الصامتة البحتة مثل `NO_REPLY` / - `no_reply` المطابقة تمامًا، ويمكن استبدال الصفوف كبيرة الحجم بعناصر نائبة. +- تمت تهيئة `chat.history` للعرض لعملاء UI: تتم + إزالة وسوم التوجيه المضمنة من النص المرئي، كما تُزال حمولات XML النصية العادية + لاستدعاءات الأدوات (بما في ذلك + `...`، و`...`، + و`...`، و`...`، + وكتل استدعاءات الأدوات المقتطعة) ورموز التحكم بالنموذج المسرّبة بصيغة ASCII/العرض الكامل، + كما تُحذف صفوف المساعد المؤلفة فقط من رموز صامتة مثل `NO_REPLY` / + `no_reply`، ويمكن استبدال الصفوف كبيرة الحجم بعناصر نائبة. -#### اقتران الأجهزة وdevice tokens +#### اقتران الأجهزة ورموز الأجهزة -- تعيد `device.pair.list` الأجهزة المقترنة المعلقة والموافق عليها. -- تدير `device.pair.approve`, `device.pair.reject`, و`device.pair.remove` +- يعيد `device.pair.list` الأجهزة المقترنة المعلقة والمعتمدة. +- تدير `device.pair.approve`، و`device.pair.reject`، و`device.pair.remove` سجلات اقتران الأجهزة. -- تدير `device.token.rotate` تدوير token جهاز مقترن ضمن حدود دوره - ونطاقاته المعتمدة. -- تلغي `device.token.revoke` device token. +- يقوم `device.token.rotate` بتدوير رمز جهاز مقترن ضمن حدود الدور + والنطاق المعتمدة له. +- يقوم `device.token.revoke` بإبطال رمز جهاز مقترن. #### اقتران العقد، والاستدعاء، والعمل المعلّق -- تغطي `node.pair.request`, `node.pair.list`, `node.pair.approve`, - `node.pair.reject`, و`node.pair.verify` اقتران العقد والتحقق من +- تغطي `node.pair.request`، و`node.pair.list`، و`node.pair.approve`، + و`node.pair.reject`، و`node.pair.verify` اقتران العقد والتحقق من bootstrap. - تعيد `node.list` و`node.describe` حالة العقد المعروفة/المتصلة. -- تحدّث `node.rename` تسمية عقدة مقترنة. -- تمرر `node.invoke` أمرًا إلى عقدة متصلة. -- تعيد `node.invoke.result` النتيجة لطلب invoke. -- تحمل `node.event` الأحداث الصادرة من العقدة عودةً إلى الـ gateway. -- تحدّث `node.canvas.capability.refresh` رموز canvas-capability المحددة النطاق. -- تمثل `node.pending.pull` و`node.pending.ack` واجهات queue الخاصة بالعقد المتصلة. -- تدير `node.pending.enqueue` و`node.pending.drain` العمل المعلّق المتين +- يحدّث `node.rename` تسمية عقدة مقترنة. +- يمرّر `node.invoke` أمرًا إلى عقدة متصلة. +- يعيد `node.invoke.result` النتيجة لطلب استدعاء. +- يحمل `node.event` الأحداث الصادرة من العقدة عائدًا إلى البوابة. +- يقوم `node.canvas.capability.refresh` بتحديث رموز إمكانات canvas + المحصورة بالنطاق. +- تمثل `node.pending.pull` و`node.pending.ack` واجهات API الخاصة بطابور + العقد المتصلة. +- تدير `node.pending.enqueue` و`node.pending.drain` العمل المعلّق الدائم للعقد غير المتصلة/المنفصلة. #### عائلات الموافقات -- تغطي `exec.approval.request` و`exec.approval.resolve` طلبات - موافقة exec لمرة واحدة. -- تنتظر `exec.approval.waitDecision` قرار exec pending واحدًا وتعيد +- تغطي `exec.approval.request`، و`exec.approval.get`، و`exec.approval.list`، و + `exec.approval.resolve` طلبات موافقة exec لمرة واحدة بالإضافة إلى + البحث/إعادة التشغيل للموافقات المعلقة. +- ينتظر `exec.approval.waitDecision` قرار موافقة exec واحدًا معلقًا ويعيد القرار النهائي (أو `null` عند انتهاء المهلة). -- تدير `exec.approvals.get` و`exec.approvals.set` لقطات سياسة موافقات exec الخاصة بالـ gateway. -- تدير `exec.approvals.node.get` و`exec.approvals.node.set` سياسة موافقات exec المحلية للعقدة - عبر أوامر relay الخاصة بالعقدة. -- تغطي `plugin.approval.request`, `plugin.approval.waitDecision`, و - `plugin.approval.resolve` تدفقات الموافقات المعرّفة من المكونات الإضافية. +- تدير `exec.approvals.get` و`exec.approvals.set` لقطات سياسة موافقة + exec على البوابة. +- تدير `exec.approvals.node.get` و`exec.approvals.node.set` سياسة موافقة exec + المحلية للعقدة عبر أوامر relay للعقدة. +- تغطي `plugin.approval.request`، و`plugin.approval.list`، + و`plugin.approval.waitDecision`، و`plugin.approval.resolve` + تدفقات الموافقة المعرفة من الإضافات. #### عائلات رئيسية أخرى - الأتمتة: - - تجدول `wake` حقن نص تنبيه فوري أو في heartbeat التالية - - `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`, - `cron.run`, `cron.runs` -- المهارات/الأدوات: `skills.*`, `tools.catalog`, `tools.effective` + - يقوم `wake` بجدولة حقن نص تنبيه فوري أو عند heartbeat التالي + - `cron.list`، و`cron.status`، و`cron.add`، و`cron.update`، و`cron.remove`، + و`cron.run`، و`cron.runs` +- Skills/tools: `skills.*`، و`tools.catalog`، و`tools.effective` ### عائلات الأحداث الشائعة -- `chat`: تحديثات دردشة UI مثل `chat.inject` وغيرها من - أحداث الدردشة الخاصة بالنصوص فقط. -- `session.message` و`session.tool`: تحديثات النصوص/تدفق الأحداث - لجلسة مشتركة. +- `chat`: تحديثات دردشة واجهة المستخدم مثل `chat.inject` وغيرها من + أحداث الدردشة الخاصة بالسجل فقط. +- `session.message` و`session.tool`: تحديثات السجل/تيار الأحداث لجلسة + مشترَك بها. - `sessions.changed`: تغيّر فهرس الجلسات أو بياناتها الوصفية. - `presence`: تحديثات لقطة حضور النظام. -- `tick`: حدث keepalive / liveness دوري. -- `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`: تغيّر إعداد محفزات كلمة التنبيه. +- `tick`: حدث دوري للإبقاء على الحياة / الحيوية. +- `health`: تحديث لقطة صحة البوابة. +- `heartbeat`: تحديث تيار أحداث heartbeat. +- `cron`: حدث تغير تشغيل/مهمة cron. +- `shutdown`: إشعار إيقاف تشغيل البوابة. +- `node.pair.requested` / `node.pair.resolved`: دورة حياة اقتران العقدة. +- `node.invoke.request`: بث طلب استدعاء العقدة. +- `device.pair.requested` / `device.pair.resolved`: دورة حياة الجهاز المقترن. +- `voicewake.changed`: تغيّر إعداد محفز كلمة التنبيه. - `exec.approval.requested` / `exec.approval.resolved`: دورة حياة موافقة exec. - `plugin.approval.requested` / `plugin.approval.resolved`: دورة حياة موافقة - المكون الإضافي. + الإضافة. -### طرق مساعدة العقد +### أساليب مساعدة العقدة -- يمكن للعقد استدعاء `skills.bins` لجلب القائمة الحالية للملفات التنفيذية - الخاصة بالمهارات لفحوصات allow التلقائية. +- يمكن للعقد استدعاء `skills.bins` لجلب القائمة الحالية لملفات Skills التنفيذية + لفحوصات السماح التلقائي. -### طرق مساعدة المشغّل +### أساليب مساعدة operator -- يمكن للمشغّلين استدعاء `tools.catalog` ‏(`operator.read`) لجلب فهرس الأدوات وقت التشغيل لوكيل - ما. وتتضمن الاستجابة أدوات مجمّعة وبيانات وصفية للمصدر: - - `source`: ‏`core` أو `plugin` - - `pluginId`: مالك المكون الإضافي عندما يكون `source="plugin"` - - `optional`: ما إذا كانت أداة المكون الإضافي اختيارية -- يمكن للمشغّلين استدعاء `tools.effective` ‏(`operator.read`) لجلب جرد الأدوات - الفعّال وقت التشغيل لجلسة ما. +- يمكن للمشغّلين استدعاء `tools.catalog` (`operator.read`) لجلب فهرس الأدوات في وقت التشغيل + لوكيل. تتضمن الاستجابة أدوات مجمعة وبيانات وصفية للمصدر: + - `source`: `core` أو `plugin` + - `pluginId`: مالك الإضافة عندما يكون `source="plugin"` + - `optional`: ما إذا كانت أداة الإضافة اختيارية +- يمكن للمشغّلين استدعاء `tools.effective` (`operator.read`) لجلب جرد الأدوات الفعّال في وقت التشغيل + لجلسة. - `sessionKey` مطلوب. - - يستمد gateway سياق وقت التشغيل الموثوق من الجلسة على جانب الخادم بدل قبول - سياق مصادقة أو تسليم يقدمه المستدعي. - - تكون الاستجابة محددة بالجسلة وتعكس ما الذي تستطيع المحادثة النشطة استخدامه الآن، - بما في ذلك الأدوات الأساسية وأدوات المكونات الإضافية وأدوات القنوات. -- يمكن للمشغّلين استدعاء `skills.status` ‏(`operator.read`) لجلب جرد - المهارات المرئي لوكيل ما. - - `agentId` اختياري؛ اتركه فارغًا لقراءة مساحة عمل الوكيل الافتراضي. + - تستخلص البوابة سياق وقت التشغيل الموثوق من الجلسة من جهة الخادم بدلًا من قبول + سياق المصادقة أو التسليم المورَّد من المستدعي. + - تكون الاستجابة محصورة بالجلسة وتعكس ما يمكن للمحادثة النشطة استخدامه الآن، + بما في ذلك أدوات core، وplugin، والقنوات. +- يمكن للمشغّلين استدعاء `skills.status` (`operator.read`) لجلب + جرد Skills المرئي لوكيل. + - `agentId` اختياري؛ احذفه لقراءة مساحة عمل الوكيل الافتراضية. - تتضمن الاستجابة الأهلية، والمتطلبات المفقودة، وفحوصات الإعداد، و - خيارات التثبيت المنقحة من دون كشف القيم السرية الخام. -- يمكن للمشغّلين استدعاء `skills.search` و`skills.detail` ‏(`operator.read`) للحصول على + خيارات التثبيت المنقّحة من دون كشف قيم الأسرار الخام. +- يمكن للمشغّلين استدعاء `skills.search` و`skills.detail` (`operator.read`) للحصول على بيانات اكتشاف ClawHub الوصفية. -- يمكن للمشغّلين استدعاء `skills.install` ‏(`operator.admin`) في وضعين: - - وضع ClawHub: ‏`{ source: "clawhub", slug, version?, force? }` يثبّت - مجلد مهارة داخل دليل `skills/` في مساحة عمل الوكيل الافتراضي. - - وضع مثبّت Gateway: ‏`{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }` - يشغّل إجراء `metadata.openclaw.install` مصرّحًا به على مضيف gateway. -- يمكن للمشغّلين استدعاء `skills.update` ‏(`operator.admin`) في وضعين: - - يحدّث وضع ClawHub slug متتبعًا واحدًا أو جميع عمليات تثبيت ClawHub المتتبعة في - مساحة عمل الوكيل الافتراضي. - - يقوم وضع config بترقيع قيم `skills.entries.` مثل `enabled`, - `apiKey`, و`env`. +- يمكن للمشغّلين استدعاء `skills.install` (`operator.admin`) في وضعين: + - وضع ClawHub: `{ source: "clawhub", slug, version?, force? }` يثبت + مجلد Skill داخل الدليل `skills/` لمساحة عمل الوكيل الافتراضية. + - وضع مُثبّت البوابة: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }` + يشغّل إجراء `metadata.openclaw.install` معلنًا على مضيف البوابة. +- يمكن للمشغّلين استدعاء `skills.update` (`operator.admin`) في وضعين: + - يقوم وضع ClawHub بتحديث slug متعقّب واحد أو جميع تثبيتات ClawHub المتعقبة في + مساحة عمل الوكيل الافتراضية. + - يقوم وضع الإعداد بترقيع قيم `skills.entries.` مثل `enabled`، + و`apiKey`، و`env`. ## موافقات exec -- عندما يحتاج طلب exec إلى موافقة، يبث gateway الحدث `exec.approval.requested`. -- يحل عملاء operator ذلك عبر استدعاء `exec.approval.resolve` ‏(يتطلب النطاق `operator.approvals`). -- بالنسبة إلى `host=node`، يجب أن يتضمن `exec.approval.request` القيمة `systemRunPlan` ‏(`argv`/`cwd`/`rawCommand`/بيانات الجلسة الوصفية القانونية). وتُرفض الطلبات التي تفتقد `systemRunPlan`. -- بعد الموافقة، تعيد استدعاءات `node.invoke system.run` المُمررة استخدام - `systemRunPlan` القانوني ذاك بوصفه السياق الموثوق للأمر/cwd/الجلسة. -- إذا عدّل مستدعٍ القيم `command`, `rawCommand`, `cwd`, `agentId`, أو - `sessionKey` بين التحضير والتمرير النهائي الموافق عليه لـ `system.run`، فإن - gateway يرفض التشغيل بدل الوثوق بالحمولة المعدلة. +- عندما يحتاج طلب exec إلى موافقة، تبث البوابة `exec.approval.requested`. +- يحسم عملاء operator ذلك عبر استدعاء `exec.approval.resolve` (يتطلب النطاق `operator.approvals`). +- بالنسبة إلى `host=node`، يجب أن يتضمن `exec.approval.request` القيمة `systemRunPlan` (الحقول القياسية `argv`/`cwd`/`rawCommand`/بيانات تعريف الجلسة). تُرفض الطلبات التي تفتقد `systemRunPlan`. +- بعد الموافقة، تعيد استدعاءات `node.invoke system.run` المُمرَّرة استخدام + `systemRunPlan` القياسي هذا بوصفه سياق الأمر/`cwd`/الجلسة المعتمد. +- إذا قام مستدعٍ بتعديل `command` أو`rawCommand` أو`cwd` أو`agentId` أو + `sessionKey` بين التحضير وتمرير `system.run` الموافق عليه النهائي، فإن + البوابة ترفض التشغيل بدلًا من الوثوق بالحمولة المعدلة. -## fallback تسليم الوكيل +## بديل تسليم الوكيل -- يمكن لطلبات `agent` أن تتضمن `deliver=true` لطلب تسليم صادر. -- يبقي `bestEffortDeliver=false` السلوك صارمًا: إذ تعيد أهداف التسليم غير المحلولة أو الداخلية فقط الخطأ `INVALID_REQUEST`. -- يسمح `bestEffortDeliver=true` بالرجوع الاحتياطي إلى التنفيذ داخل الجلسة فقط عندما لا يمكن حل أي مسار خارجي قابل للتسليم (مثل جلسات internal/webchat أو إعدادات متعددة القنوات ملتبسة). +- يمكن أن تتضمن طلبات `agent` القيمة `deliver=true` لطلب تسليم صادر. +- يحافظ `bestEffortDeliver=false` على السلوك الصارم: أهداف التسليم غير المحلولة أو الداخلية فقط تعيد `INVALID_REQUEST`. +- يسمح `bestEffortDeliver=true` بالرجوع إلى تنفيذ على مستوى الجلسة فقط عندما لا يمكن حل مسار خارجي قابل للتسليم (على سبيل المثال جلسات داخلية/WebChat أو إعدادات متعددة القنوات ملتبسة). ## الإصدارات -- يعيش `PROTOCOL_VERSION` في `src/gateway/protocol/schema.ts`. -- يرسل العملاء `minProtocol` + `maxProtocol`؛ ويرفض الخادم عدم التطابق. -- تُولَّد schemas + models من تعريفات TypeBox: +- توجد `PROTOCOL_VERSION` في `src/gateway/protocol/schema.ts`. +- يرسل العملاء `minProtocol` + `maxProtocol`؛ ويرفض الخادم حالات عدم التطابق. +- يتم توليد المخططات + النماذج من تعريفات TypeBox: - `pnpm protocol:gen` - `pnpm protocol:gen:swift` - `pnpm protocol:check` ## المصادقة -- تستخدم مصادقة gateway بالسر المشترك إما `connect.params.auth.token` أو - `connect.params.auth.password`، بحسب وضع المصادقة المكوَّن. -- تلبّي الأوضاع الحاملة للهوية مثل Tailscale Serve - (`gateway.auth.allowTailscale: true`) أو `gateway.auth.mode: "trusted-proxy"` - غير المعتمد على loopback فحص مصادقة الاتصال من - ترويسات الطلب بدل `connect.params.auth.*`. -- يتجاوز `gateway.auth.mode: "none"` الخاص بالدخول الخاص فحص المصادقة بالسر المشترك - بالكامل؛ ولا تعرض هذا الوضع على دخول عام/غير موثوق. -- بعد الاقتران، يصدر Gateway **device token** محددة بالدور + النطاقات الخاصة بالاتصال. - وتُعاد في `hello-ok.auth.deviceToken` ويجب أن يحتفظ بها العميل +- تستخدم مصادقة البوابة بالسر المشترك `connect.params.auth.token` أو + `connect.params.auth.password`، حسب وضع المصادقة المضبوط. +- أوضاع حمل الهوية مثل Tailscale Serve + (`gateway.auth.allowTailscale: true`) أو + `gateway.auth.mode: "trusted-proxy"` غير loopback + تحقق فحص مصادقة الاتصال من ترويسات الطلب بدلًا من `connect.params.auth.*`. +- يتجاوز الوضع `gateway.auth.mode: "none"` للولوج الخاص مصادقة الاتصال بالسر المشترك + بالكامل؛ لا تعرّض هذا الوضع على منافذ عامة/غير موثوقة. +- بعد الاقتران، تصدر البوابة **رمز جهاز** محصورًا بدور الاتصال + + النطاقات. ويُعاد في `hello-ok.auth.deviceToken` ويجب أن يحفظه العميل للاتصالات المستقبلية. -- يجب على العملاء الاحتفاظ بالـ `hello-ok.auth.deviceToken` الأساسية بعد أي +- يجب على العملاء حفظ `hello-ok.auth.deviceToken` الأساسي بعد أي اتصال ناجح. -- كما يجب عند إعادة الاتصال باستخدام **device token** هذه المخزنة - إعادة استخدام مجموعة النطاقات المعتمدة المخزنة الخاصة بتلك الـ token. وهذا يحافظ على - وصول read/probe/status الذي مُنح بالفعل ويتجنب انهيار إعادة الاتصال بصمت إلى - نطاق ضمني أضيق خاص بالإدارة فقط. -- تكون أسبقية مصادقة الاتصال العادية: token/password المشتركة الصريحة أولًا، ثم - `deviceToken` الصريحة، ثم token المخزنة لكل جهاز، ثم bootstrap token. -- إن إدخالات `hello-ok.auth.deviceTokens` الإضافية هي tokens مسلّمة ضمن bootstrap. - ولا تحتفظ بها إلا عندما يستخدم الاتصال مصادقة bootstrap عبر نقل موثوق - مثل `wss://` أو loopback/local pairing. -- إذا قدّم عميل **`deviceToken` صريحة** أو `scopes` صريحة، فإن - مجموعة النطاقات المطلوبة من المستدعي تبقى هي المرجع؛ ولا يُعاد استخدام النطاقات المخبأة إلا - عندما يعيد العميل استخدام token المخزنة لكل جهاز. -- يمكن تدوير/إلغاء device tokens عبر `device.token.rotate` و - `device.token.revoke` ‏(يتطلب `operator.pairing`). -- يبقى إصدار/تدوير token مقيدًا بمجموعة الأدوار المعتمدة المسجلة في - إدخال اقتران ذلك الجهاز؛ ولا يمكن لتدوير token توسيع الجهاز إلى +- يجب أن تؤدي إعادة الاتصال باستخدام رمز الجهاز **المخزَّن** هذا أيضًا إلى إعادة استخدام + مجموعة النطاقات المعتمدة والمخزنة لذلك الرمز. وهذا يحافظ على وصول + القراءة/الفحص/الحالة الذي مُنح سابقًا ويمنع تقليص الاتصالات المعاد إنشاؤها + بصمت إلى نطاق إدارة ضمني أضيق. +- تكون أولوية مصادقة الاتصال العادية: الرمز/كلمة المرور المشتركة الصريحة أولًا، ثم + `deviceToken` الصريح، ثم الرمز المخزَّن لكل جهاز، ثم رمز bootstrap. +- تمثل إدخالات `hello-ok.auth.deviceTokens` الإضافية رموز تسليم bootstrap. + احفظها فقط عندما يستخدم الاتصال مصادقة bootstrap على ناقل موثوق + مثل `wss://` أو الاقتران المحلي/loopback. +- إذا قدّم عميل `deviceToken` **صريحًا** أو نطاقات `scopes` صريحة، فإن + مجموعة النطاقات المطلوبة من المستدعي تظل هي المعتمدة؛ ولا يعاد استخدام النطاقات المخزنة + إلا عندما يعيد العميل استخدام الرمز المخزَّن لكل جهاز. +- يمكن تدوير/إبطال رموز الأجهزة عبر `device.token.rotate` و + `device.token.revoke` (يتطلب النطاق `operator.pairing`). +- يظل إصدار/تدوير الرموز محصورًا ضمن مجموعة الأدوار المعتمدة والمسجلة في + إدخال اقتران ذلك الجهاز؛ ولا يمكن لتدوير رمز أن يوسّع الجهاز إلى دور لم تمنحه موافقة الاقتران أصلًا. -- بالنسبة إلى جلسات token الخاصة بالأجهزة المقترنة، تكون إدارة الأجهزة محددة بالذات ما لم يكن - للمستدعي أيضًا `operator.admin`: إذ لا يستطيع غير المسؤولين إزالة/إلغاء/تدوير - إلا إدخال الجهاز **الخاص بهم**. -- كما يتحقق `device.token.rotate` من مجموعة نطاقات operator المطلوبة مقابل - نطاقات جلسة المستدعي الحالية. ولا يستطيع غير المسؤولين تدوير token إلى - مجموعة نطاقات operator أوسع مما يملكونه بالفعل. -- تتضمن إخفاقات المصادقة `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`) +- بالنسبة إلى جلسات رموز الأجهزة المقترنة، تكون إدارة الجهاز محصورة ذاتيًا ما لم + يكن لدى المستدعي أيضًا `operator.admin`: لا يمكن للمستدعين غير الإداريين إزالة/إبطال/تدوير + إلا إدخال جهازهم **الخاص**. +- يتحقق `device.token.rotate` أيضًا من مجموعة نطاقات operator المطلوبة في مقابل + نطاقات جلسة المستدعي الحالية. لا يمكن للمستدعين غير الإداريين تدوير رمز + إلى مجموعة نطاقات operator أوسع مما يملكونه بالفعل. +- تتضمن حالات فشل المصادقة `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`: - - يمكن للعملاء الموثوقين محاولة إعادة محاولة واحدة محدودة باستخدام token مخزنة لكل جهاز. - - إذا فشلت إعادة المحاولة تلك، فيجب على العملاء إيقاف حلقات إعادة الاتصال التلقائية وإظهار إرشادات لاتخاذ إجراء من المشغّل. + - يمكن للعملاء الموثوقين محاولة إعادة واحدة محدودة باستخدام رمز + مخزَّن لكل جهاز. + - إذا فشلت إعادة المحاولة تلك، يجب على العملاء إيقاف حلقات إعادة الاتصال التلقائية + وإظهار إرشادات لإجراء من المشغّل. ## هوية الجهاز + الاقتران -- يجب على العقد تضمين هوية جهاز ثابتة (`device.id`) مشتقة من +- يجب أن تتضمن العقد هوية جهاز مستقرة (`device.id`) مشتقة من بصمة زوج مفاتيح. -- تصدر Gateways tokens لكل جهاز + دور. -- موافقات الاقتران مطلوبة لمعرّفات الأجهزة الجديدة ما لم يكن تفعيل الموافقة التلقائية - المحلية مفعّلًا. -- تتمحور الموافقة التلقائية للاقتران حول اتصالات loopback المحلية المباشرة. -- يملك OpenClaw أيضًا مسار self-connect ضيقًا محليًا على مستوى backend/container - لتدفقات المساعدات الموثوقة ذات الأسرار المشتركة. -- ما تزال اتصالات tailnet أو LAN على المضيف نفسه تُعامل على أنها بعيدة لأغراض الاقتران وتتطلب موافقة. -- يجب أن تتضمن جميع عملاء WS هوية `device` أثناء `connect` ‏(operator + node). - ويمكن لـ Control UI حذفها فقط في هذه الأوضاع: - - `gateway.controlUi.allowInsecureAuth=true` لتوافق HTTP غير الآمن على localhost فقط. - - نجاح مصادقة operator في Control UI ضمن `gateway.auth.mode: "trusted-proxy"`. - - `gateway.controlUi.dangerouslyDisableDeviceAuth=true` ‏(وضع طوارئ، خفض أمني شديد). -- يجب أن توقّع جميع الاتصالات `connect.challenge` nonce التي يوفرها الخادم. +- تصدر البوابات رموزًا لكل جهاز + دور. +- تتطلب معتمَدات الاقتران لمعرّفات الأجهزة الجديدة موافقات اقتران ما لم يكن + التلقائي المحلي مفعّلًا. +- يتمحور الاعتماد التلقائي للاقتران حول اتصالات loopback المحلية المباشرة. +- لدى OpenClaw أيضًا مسار اتصال ذاتي ضيق على مستوى الواجهة الخلفية/الحاوية من أجل + تدفقات المساعد الموثوقة ذات السر المشترك. +- ما تزال اتصالات tailnet أو LAN على المضيف نفسه تُعامل باعتبارها بعيدة من أجل الاقتران + وتتطلب موافقة. +- يجب أن تتضمن جميع عملاء WS هوية `device` أثناء `connect` (operator + node). + يمكن لـ Control UI حذفها فقط في هذه الأوضاع: + - `gateway.controlUi.allowInsecureAuth=true` من أجل توافق HTTP غير الآمن على localhost فقط. + - نجاح مصادقة Control UI الخاصة بـ operator مع `gateway.auth.mode: "trusted-proxy"`. + - `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (وضع طوارئ، خفض أمني شديد). +- يجب على جميع الاتصالات توقيع nonce المقدَّم من الخادم في `connect.challenge`. ### تشخيصات ترحيل مصادقة الجهاز بالنسبة إلى العملاء القدامى الذين ما زالوا يستخدمون سلوك التوقيع السابق للتحدي، يعيد `connect` الآن -رموز تفاصيل `DEVICE_AUTH_*` ضمن `error.details.code` مع قيمة ثابتة `error.details.reason`. +أكواد تفاصيل `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 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 identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | لا يطابق `device.id` بصمة المفتاح العام. | -| `device public key invalid`| `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | فشل تنسيق/تحويل المفتاح العام إلى الصيغة القانونية. | +| الرسالة | details.code | details.reason | المعنى | +| --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- | +| `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 identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | لا يطابق `device.id` بصمة المفتاح العام. | +| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | فشل تنسيق/توحيد المفتاح العام. | هدف الترحيل: - انتظر دائمًا `connect.challenge`. -- وقّع حمولة v2 التي تتضمن server nonce. -- أرسل nonce نفسها ضمن `connect.params.device.nonce`. +- وقّع حمولة v2 التي تتضمن nonce الخاص بالخادم. +- أرسل nonce نفسه في `connect.params.device.nonce`. - حمولة التوقيع المفضلة هي `v3`، التي تربط `platform` و`deviceFamily` - بالإضافة إلى حقول الجهاز/العميل/الدور/النطاقات/token/nonce. -- ما تزال توقيعات `v2` القديمة مقبولة للتوافق، لكن - تثبيت البيانات الوصفية للأجهزة المقترنة ما يزال يتحكم في سياسة الأوامر عند إعادة الاتصال. + بالإضافة إلى حقول الجهاز/العميل/الدور/النطاقات/الرمز/nonce. +- ما تزال توقيعات `v2` القديمة مقبولة من أجل التوافق، لكن تثبيت بيانات + الجهاز المقترن الوصفية ما يزال يتحكم بسياسة الأوامر عند إعادة الاتصال. ## TLS + التثبيت -- TLS مدعوم لاتصالات WS. -- يمكن للعملاء اختياريًا تثبيت بصمة شهادة gateway (راجع إعداد `gateway.tls` - بالإضافة إلى `gateway.remote.tlsFingerprint` أو CLI `--tls-fingerprint`). +- دعم TLS متاح لاتصالات WS. +- يمكن للعملاء تثبيت بصمة شهادة البوابة اختياريًا (راجع إعداد `gateway.tls` + بالإضافة إلى `gateway.remote.tlsFingerprint` أو علم CLI `--tls-fingerprint`). ## النطاق -يعرض هذا البروتوكول **واجهة gateway API الكاملة** (الحالة، والقنوات، والنماذج، والدردشة، -والوكيل، والجلسات، والعقد، والموافقات، وغير ذلك). ويُعرَّف السطح الدقيق بواسطة -TypeBox schemas في `src/gateway/protocol/schema.ts`. +يكشف هذا البروتوكول **واجهة API الكاملة للبوابة** (الحالة، والقنوات، والنماذج، والدردشة، +والوكيل، والجلسات، والعقد، والموافقات، وغير ذلك). ويتم تعريف السطح الدقيق بواسطة +مخططات TypeBox في `src/gateway/protocol/schema.ts`. diff --git a/docs/ar/gateway/troubleshooting.md b/docs/ar/gateway/troubleshooting.md index 4a52c9a1c..761fe2210 100644 --- a/docs/ar/gateway/troubleshooting.md +++ b/docs/ar/gateway/troubleshooting.md @@ -1,22 +1,22 @@ --- read_when: - - أحالَك مركز استكشاف الأخطاء وإصلاحها إلى هنا للحصول على تشخيص أعمق + - أحالَك مركز استكشاف الأخطاء وإصلاحها إلى هنا للتشخيص الأعمق - تحتاج إلى أقسام دليل تشغيل مستقرة قائمة على الأعراض مع أوامر دقيقة -summary: دليل متعمق لاستكشاف الأخطاء وإصلاحها للـ gateway، والقنوات، والأتمتة، والعُقد، والمتصفح +summary: دليل متعمق لاستكشاف الأخطاء وإصلاحها للبوابة والقنوات والأتمتة والعُقد والمتصفح title: استكشاف الأخطاء وإصلاحها x-i18n: - generated_at: "2026-04-07T07:18:21Z" + generated_at: "2026-04-08T02:16:18Z" model: gpt-5.4 provider: openai - source_hash: e0202e8858310a0bfc1c994cd37b01c3b2d6c73c8a74740094e92dc3c4c36729 + source_hash: 02c9537845248db0c9d315bf581338a93215fe6fe3688ed96c7105cbb19fe6ba source_path: gateway/troubleshooting.md workflow: 15 --- -# استكشاف أخطاء Gateway وإصلاحها +# استكشاف أخطاء البوابة وإصلاحها هذه الصفحة هي دليل التشغيل المتعمق. -ابدأ من [/help/troubleshooting](/ar/help/troubleshooting) إذا كنت تريد أولًا مسار الفرز السريع. +ابدأ من [/help/troubleshooting](/ar/help/troubleshooting) إذا كنت تريد تدفق الفرز السريع أولًا. ## تسلسل الأوامر @@ -30,16 +30,16 @@ openclaw doctor openclaw channels status --probe ``` -الإشارات المتوقعة للحالة السليمة: +الإشارات السليمة المتوقعة: -- يعرض `openclaw gateway status` القيمتين `Runtime: running` و`RPC probe: ok`. -- يُبلغ `openclaw doctor` بعدم وجود مشكلات حظر في الإعداد/الخدمة. -- يعرض `openclaw channels status --probe` حالة النقل المباشر لكل حساب، ونتائج - الفحص/التدقيق عند الدعم، مثل `works` أو `audit ok`. +- يعرض `openclaw gateway status` القيمة `Runtime: running` و `RPC probe: ok`. +- يُبلغ `openclaw doctor` عن عدم وجود مشكلات حظر في الإعدادات/الخدمة. +- يعرض `openclaw channels status --probe` حالة النقل المباشرة لكل حساب، + وحيثما كان ذلك مدعومًا، نتائج الفحص/التدقيق مثل `works` أو `audit ok`. -## يتطلب Anthropic 429 استخدامًا إضافيًا للسياق الطويل +## خطأ Anthropic 429: استخدام إضافي مطلوب للسياق الطويل -استخدم هذا القسم عندما تتضمن السجلات/الأخطاء: +استخدم هذا عندما تتضمن السجلات/الأخطاء: `HTTP 429: rate_limit_error: Extra usage is required for long context requests`. ```bash @@ -56,9 +56,9 @@ openclaw config get agents.defaults.models خيارات الإصلاح: -1. عطّل `context1m` لهذا النموذج للعودة إلى نافذة السياق العادية. -2. استخدم بيانات اعتماد Anthropic مؤهلة لطلبات السياق الطويل، أو بدّل إلى Anthropic API key. -3. اضبط نماذج احتياطية حتى تستمر التشغيلات عند رفض طلبات Anthropic للسياق الطويل. +1. عطّل `context1m` لذلك النموذج للرجوع إلى نافذة السياق العادية. +2. استخدم بيانات اعتماد Anthropic مؤهلة لطلبات السياق الطويل، أو انتقل إلى مفتاح Anthropic API. +3. اضبط نماذج بديلة حتى تستمر التشغيلات عندما تُرفض طلبات Anthropic ذات السياق الطويل. ذو صلة: @@ -66,6 +66,60 @@ openclaw config get agents.defaults.models - [/reference/token-use](/ar/reference/token-use) - [/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic](/ar/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic) +## الواجهة الخلفية المحلية المتوافقة مع OpenAI تجتاز الفحوصات المباشرة لكن تشغيلات الوكيل تفشل + +استخدم هذا عندما: + +- ينجح `curl ... /v1/models` +- تنجح استدعاءات `/v1/chat/completions` المباشرة الصغيرة +- تفشل تشغيلات نماذج OpenClaw فقط في أدوار الوكيل العادية + +```bash +curl http://127.0.0.1:1234/v1/models +curl http://127.0.0.1:1234/v1/chat/completions \ + -H 'content-type: application/json' \ + -d '{"model":"","messages":[{"role":"user","content":"hi"}],"stream":false}' +openclaw infer model run --model --prompt "hi" --json +openclaw logs --follow +``` + +ابحث عن: + +- أن الاستدعاءات الصغيرة المباشرة تنجح، لكن تشغيلات OpenClaw تفشل فقط مع الموجّهات الأكبر +- أخطاء في الواجهة الخلفية تشير إلى أن `messages[].content` يتوقع سلسلة نصية +- أعطال الواجهة الخلفية التي تظهر فقط مع أعداد أكبر من رموز الموجّه أو موجّهات + وقت تشغيل الوكيل الكاملة + +الأنماط الشائعة: + +- `messages[...].content: invalid type: sequence, expected a string` ← الواجهة الخلفية + ترفض أجزاء محتوى Chat Completions المهيكلة. الإصلاح: اضبط + `models.providers..models[].compat.requiresStringContent: true`. +- تنجح الطلبات المباشرة الصغيرة، لكن تشغيلات وكيل OpenClaw تفشل مع أعطال + الواجهة الخلفية/النموذج (مثلًا Gemma على بعض إصدارات `inferrs`) ← من + المرجح أن نقل OpenClaw صحيح بالفعل؛ الواجهة الخلفية هي التي تفشل مع شكل + موجّه وقت تشغيل الوكيل الأكبر. +- تتراجع حالات الفشل بعد تعطيل الأدوات لكنها لا تختفي ← كانت مخططات الأدوات + جزءًا من الضغط، لكن المشكلة المتبقية لا تزال في سعة النموذج/الخادم upstream + أو في خطأ بالواجهة الخلفية. + +خيارات الإصلاح: + +1. اضبط `compat.requiresStringContent: true` لواجهات Chat Completions الخلفية التي تقبل السلاسل النصية فقط. +2. اضبط `compat.supportsTools: false` للنماذج/الواجهات الخلفية التي لا تستطيع التعامل + مع سطح مخطط أدوات OpenClaw بشكل موثوق. +3. خفّض ضغط الموجّه حيثما أمكن: تهيئة أولية أصغر لمساحة العمل، وسجل جلسة أقصر، + أو نموذج محلي أخف، أو واجهة خلفية ذات دعم أقوى للسياق الطويل. +4. إذا استمرت الطلبات المباشرة الصغيرة بالنجاح بينما ما زالت أدوار وكيل OpenClaw تتعطل + داخل الواجهة الخلفية، فاعتبر ذلك قيدًا في الخادم/النموذج upstream وقدّم + بلاغ إعادة إنتاج هناك مع شكل الحمولة المقبول. + +ذو صلة: + +- [/gateway/local-models](/ar/gateway/local-models) +- [/gateway/configuration#models](/ar/gateway/configuration#models) +- [/gateway/configuration-reference#openai-compatible-endpoints](/ar/gateway/configuration-reference#openai-compatible-endpoints) + ## لا توجد ردود إذا كانت القنوات تعمل لكن لا يوجد أي رد، فتحقق من التوجيه والسياسة قبل إعادة توصيل أي شيء. @@ -84,11 +138,11 @@ openclaw logs --follow - تقييد الإشارة في المجموعات (`requireMention`، `mentionPatterns`). - عدم تطابق قائمة السماح للقناة/المجموعة. -العلامات الشائعة: +الأنماط الشائعة: -- `drop guild message (mention required` → تم تجاهل رسالة المجموعة حتى حدوث إشارة. -- `pairing request` → يحتاج المرسل إلى موافقة. -- `blocked` / `allowlist` → تمّت تصفية المرسل/القناة بواسطة السياسة. +- `drop guild message (mention required` ← تم تجاهل رسالة المجموعة حتى حدوث إشارة. +- `pairing request` ← يحتاج المرسل إلى موافقة. +- `blocked` / `allowlist` ← تمت تصفية المرسل/القناة بواسطة السياسة. ذو صلة: @@ -96,9 +150,9 @@ openclaw logs --follow - [/channels/pairing](/ar/channels/pairing) - [/channels/groups](/ar/channels/groups) -## اتصال dashboard/control UI +## اتصال واجهة dashboard/control UI -عندما يتعذر على dashboard/control UI الاتصال، تحقّق من عنوان URL، ووضع المصادقة، وافتراضات السياق الآمن. +عندما لا يتصل dashboard/control UI، تحقّق من عنوان URL ووضع المصادقة وافتراضات السياق الآمن. ```bash openclaw gateway status @@ -110,47 +164,49 @@ openclaw gateway status --json ابحث عن: -- عنوان URL الصحيح للفحص وdashboard. -- عدم تطابق وضع المصادقة/الرمز المميز بين العميل وgateway. -- استخدام HTTP في مواضع تتطلب هوية الجهاز. +- عنوان URL الصحيح للفحص ولوحة التحكم. +- عدم تطابق وضع/رمز المصادقة بين العميل والبوابة. +- استخدام HTTP حيث تكون هوية الجهاز مطلوبة. -العلامات الشائعة: +الأنماط الشائعة: -- `device identity required` → سياق غير آمن أو مصادقة جهاز مفقودة. -- `origin not allowed` → `Origin` الخاص بالمتصفح ليس ضمن `gateway.controlUi.allowedOrigins` - (أو أنك تتصل من origin متصفح غير loopback بدون +- `device identity required` ← سياق غير آمن أو مصادقة جهاز مفقودة. +- `origin not allowed` ← قيمة `Origin` في المتصفح غير موجودة في `gateway.controlUi.allowedOrigins` + (أو أنك تتصل من مصدر متصفح غير loopback من دون قائمة سماح صريحة). -- `device nonce required` / `device nonce mismatch` → العميل لا يكمل - تدفق مصادقة الجهاز القائم على التحدي (`connect.challenge` + `device.nonce`). -- `device signature invalid` / `device signature expired` → العميل وقّع الحمولة الخطأ - (أو استخدم طابعًا زمنيًا قديمًا) للمصافحة الحالية. -- `AUTH_TOKEN_MISMATCH` مع `canRetryWithDeviceToken=true` → يمكن للعميل تنفيذ إعادة محاولة موثوقة واحدة باستخدام رمز الجهاز المميز المخزّن مؤقتًا. -- تعيد محاولة الرمز المخزّن مؤقتًا هذه استخدام مجموعة النطاقات المخزّنة مع - رمز الجهاز المميز المقترن. أما المستدعون الذين يستخدمون `deviceToken` صريحًا / `scopes` صريحة فيحتفظون - بمجموعة النطاقات المطلوبة الخاصة بهم. -- خارج مسار إعادة المحاولة هذا، تكون أولوية مصادقة الاتصال هي - الرمز/كلمة المرور المشتركة الصريحة أولًا، ثم `deviceToken` الصريح، ثم رمز الجهاز المخزّن، ثم رمز bootstrap. -- في مسار Control UI غير المتزامن عبر Tailscale Serve، يتم تسلسل المحاولات الفاشلة لنفس - `{scope, ip}` قبل أن يسجل المحدِّد الفشل. لذلك قد تُظهر محاولتان سيئتان - متزامنتان من العميل نفسه الرسالة `retry later` - في المحاولة الثانية بدلًا من عدم تطابقين عاديين. +- `device nonce required` / `device nonce mismatch` ← العميل لا يُكمل + تدفق مصادقة الجهاز المعتمد على التحدي (`connect.challenge` + `device.nonce`). +- `device signature invalid` / `device signature expired` ← وقّع العميل الحمولة الخطأ + (أو بطابع زمني قديم) للمصافحة الحالية. +- `AUTH_TOKEN_MISMATCH` مع `canRetryWithDeviceToken=true` ← يمكن للعميل تنفيذ + إعادة محاولة موثوقة واحدة باستخدام رمز الجهاز المخزن مؤقتًا. +- تعيد إعادة المحاولة باستخدام الرمز المخزن مؤقتًا استخدام مجموعة النطاقات المخزنة مع + رمز الجهاز الموافق عليه. أما مستدعيات `deviceToken` / `scopes` الصريحة فتحافظ على + مجموعة النطاقات المطلوبة بدلًا من ذلك. +- خارج مسار إعادة المحاولة هذا، تكون أولوية مصادقة الاتصال: الرمز + أو كلمة المرور المشتركة الصريحة أولًا، ثم `deviceToken` الصريح، ثم رمز الجهاز المخزن، + ثم رمز التهيئة الأولية. +- في مسار Control UI غير المتزامن عبر Tailscale Serve، تتم + سلسلة المحاولات الفاشلة لنفس `{scope, ip}` قبل أن يسجل المحدِّد الفشل. + لذا قد تظهر في المحاولة الثانية من محاولتين خاطئتين متزامنتين من العميل نفسه رسالة `retry later` + بدلًا من حالتي عدم تطابق عاديتين. - `too many failed authentication attempts (retry later)` من عميل loopback ذي أصل متصفح - → يتم حظر الإخفاقات المتكررة من `Origin` المطبّع نفسه مؤقتًا؛ بينما يستخدم أصل localhost آخر حاوية منفصلة. -- تكرار `unauthorized` بعد إعادة المحاولة تلك → انجراف في الرمز المشترك/رمز الجهاز؛ حدّث إعداد الرمز وأعد الموافقة/تدوير رمز الجهاز عند الحاجة. -- `gateway connect failed:` → هدف host/port/url غير صحيح. + ← تُحظر الإخفاقات المتكررة من `Origin` المُطبَّع نفسه مؤقتًا؛ بينما يستخدم أصل localhost آخر حاوية منفصلة. +- تكرار `unauthorized` بعد إعادة المحاولة تلك ← يوجد انجراف في الرمز المشترك/رمز الجهاز؛ حدّث إعدادات الرمز وأعِد الموافقة/دوّر رمز الجهاز عند الحاجة. +- `gateway connect failed:` ← المضيف/المنفذ/هدف عنوان URL غير صحيح. ### خريطة سريعة لرموز تفاصيل المصادقة استخدم `error.details.code` من استجابة `connect` الفاشلة لاختيار الإجراء التالي: -| رمز التفاصيل | المعنى | الإجراء الموصى به | -| --------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AUTH_TOKEN_MISSING` | لم يرسل العميل الرمز المشترك المطلوب. | الصق/اضبط الرمز في العميل ثم أعد المحاولة. لمسارات dashboard: استخدم `openclaw config get gateway.auth.token` ثم الصقه في إعدادات Control UI. | -| `AUTH_TOKEN_MISMATCH` | الرمز المشترك لا يطابق رمز مصادقة gateway. | إذا كانت `canRetryWithDeviceToken=true`، فاسمح بإعادة محاولة موثوقة واحدة. تعيد محاولات الرمز المخزّن مؤقتًا استخدام النطاقات المعتمدة المخزنة؛ أما المستدعون الذين يستخدمون `deviceToken` / `scopes` صريحة فيحتفظون بالنطاقات المطلوبة. إذا استمر الفشل، فشغّل [قائمة التحقق من استعادة انجراف الرمز](/cli/devices#token-drift-recovery-checklist). | -| `AUTH_DEVICE_TOKEN_MISMATCH` | رمز كل جهاز المخزّن مؤقتًا قديم أو ملغى. | دوّر/أعد الموافقة على رمز الجهاز باستخدام [devices CLI](/cli/devices)، ثم أعد الاتصال. | -| `PAIRING_REQUIRED` | هوية الجهاز معروفة لكنها غير معتمدة لهذا الدور. | وافق على الطلب المعلق: `openclaw devices list` ثم `openclaw devices approve `. | +| رمز التفاصيل | المعنى | الإجراء الموصى به | +| ---------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AUTH_TOKEN_MISSING` | لم يرسل العميل رمزًا مشتركًا مطلوبًا. | الصق/اضبط الرمز في العميل وأعد المحاولة. لمسارات dashboard: `openclaw config get gateway.auth.token` ثم الصقه في إعدادات Control UI. | +| `AUTH_TOKEN_MISMATCH` | لم يطابق الرمز المشترك رمز مصادقة البوابة. | إذا كانت `canRetryWithDeviceToken=true`، اسمح بإعادة محاولة موثوقة واحدة. تعيد محاولات الرمز المخزن مؤقتًا استخدام النطاقات الموافق عليها والمخزنة؛ أما مستدعيات `deviceToken` / `scopes` الصريحة فتحافظ على النطاقات المطلوبة. وإذا استمر الفشل، شغّل [قائمة التحقق من استرداد انجراف الرمز](/cli/devices#token-drift-recovery-checklist). | +| `AUTH_DEVICE_TOKEN_MISMATCH` | رمز كل جهاز المخزن مؤقتًا قديم أو أُلغي. | دوّر/أعِد الموافقة على رمز الجهاز باستخدام [CLI الأجهزة](/cli/devices)، ثم أعد الاتصال. | +| `PAIRING_REQUIRED` | هوية الجهاز معروفة لكنها غير معتمدة لهذا الدور. | وافق على الطلب المعلّق: `openclaw devices list` ثم `openclaw devices approve `. | -فحص ترحيل device auth v2: +فحص ترحيل مصادقة الجهاز v2: ```bash openclaw --version @@ -162,26 +218,26 @@ openclaw gateway status 1. ينتظر `connect.challenge` 2. يوقّع الحمولة المرتبطة بالتحدي -3. يرسل `connect.params.device.nonce` مع nonce التحدي نفسه +3. يرسل `connect.params.device.nonce` باستخدام nonce التحدي نفسه -إذا تم رفض `openclaw devices rotate` / `revoke` / `remove` بشكل غير متوقع: +إذا رُفض `openclaw devices rotate` / `revoke` / `remove` بشكل غير متوقع: -- يمكن لجلسات رموز الأجهزة المقترنة إدارة **أجهزتها الخاصة فقط** إلا إذا - كان لدى المستدعي أيضًا `operator.admin` -- لا يمكن لـ `openclaw devices rotate --scope ...` طلب نطاقات operator - إلا إذا كانت جلسة المستدعي تملكها بالفعل +- يمكن لجلسات رموز الأجهزة المقترنة إدارة **أجهزتها الخاصة فقط** ما لم يكن لدى + الجهة المستدعية أيضًا `operator.admin` +- يمكن للأمر `openclaw devices rotate --scope ...` طلب نطاقات مشغّل فقط + التي تمتلكها جلسة الجهة المستدعية بالفعل ذو صلة: - [/web/control-ui](/web/control-ui) -- [/gateway/configuration](/ar/gateway/configuration) (أوضاع مصادقة gateway) +- [/gateway/configuration](/ar/gateway/configuration) (أوضاع مصادقة البوابة) - [/gateway/trusted-proxy-auth](/ar/gateway/trusted-proxy-auth) - [/gateway/remote](/ar/gateway/remote) - [/cli/devices](/cli/devices) -## خدمة Gateway لا تعمل +## خدمة البوابة لا تعمل -استخدم هذا القسم عندما تكون الخدمة مثبتة لكن العملية لا تظل قيد التشغيل. +استخدم هذا عندما تكون الخدمة مثبتة لكن العملية لا تبقى قيد التشغيل. ```bash openclaw gateway status @@ -193,18 +249,18 @@ openclaw gateway status --deep # يفحص أيضًا الخدمات على م ابحث عن: -- `Runtime: stopped` مع تلميحات الخروج. -- عدم تطابق إعداد الخدمة (`Config (cli)` مقابل `Config (service)`). +- `Runtime: stopped` مع تلميحات عن الخروج. +- عدم تطابق إعدادات الخدمة (`Config (cli)` مقابل `Config (service)`). - تعارضات المنفذ/المستمع. -- عمليات تثبيت launchd/systemd/schtasks إضافية عند استخدام `--deep`. -- تلميحات التنظيف في `Other gateway-like services detected (best effort)`. +- تثبيتات launchd/systemd/schtasks إضافية عند استخدام `--deep`. +- تلميحات تنظيف `Other gateway-like services detected (best effort)`. -العلامات الشائعة: +الأنماط الشائعة: -- `Gateway start blocked: set gateway.mode=local` أو `existing config is missing gateway.mode` → وضع gateway المحلي غير مفعّل، أو تم إفساد ملف الإعداد وفقد `gateway.mode`. الإصلاح: اضبط `gateway.mode="local"` في إعدادك، أو أعد تشغيل `openclaw onboard --mode local` / `openclaw setup` لإعادة ختم إعداد الوضع المحلي المتوقع. إذا كنت تشغّل OpenClaw عبر Podman، فمسار الإعداد الافتراضي هو `~/.openclaw/openclaw.json`. -- `refusing to bind gateway ... without auth` → ربط non-loopback بدون مسار مصادقة صالح للـ gateway (رمز/كلمة مرور، أو trusted-proxy عند ضبطه). -- `another gateway instance is already listening` / `EADDRINUSE` → تعارض منفذ. -- `Other gateway-like services detected (best effort)` → توجد وحدات launchd/systemd/schtasks قديمة أو متوازية. يجب أن تحتفظ معظم الإعدادات بـ gateway واحد لكل جهاز؛ وإذا كنت تحتاج بالفعل إلى أكثر من واحد، فاعزل المنافذ + الإعداد + الحالة + مساحة العمل. راجع [/gateway#multiple-gateways-same-host](/ar/gateway#multiple-gateways-same-host). +- `Gateway start blocked: set gateway.mode=local` أو `existing config is missing gateway.mode` ← لم يتم تمكين وضع البوابة المحلية، أو تم العبث بملف الإعدادات وفقد `gateway.mode`. الإصلاح: اضبط `gateway.mode="local"` في إعداداتك، أو أعد تشغيل `openclaw onboard --mode local` / `openclaw setup` لإعادة ختم إعدادات الوضع المحلي المتوقعة. إذا كنت تشغّل OpenClaw عبر Podman، فمسار الإعدادات الافتراضي هو `~/.openclaw/openclaw.json`. +- `refusing to bind gateway ... without auth` ← ربط غير loopback من دون مسار مصادقة صالح للبوابة (رمز/كلمة مرور، أو trusted-proxy حيث يكون مضبوطًا). +- `another gateway instance is already listening` / `EADDRINUSE` ← تعارض منفذ. +- `Other gateway-like services detected (best effort)` ← توجد وحدات launchd/systemd/schtasks قديمة أو متوازية. معظم الإعدادات يجب أن تحتفظ ببوابة واحدة لكل جهاز؛ وإذا كنت تحتاج فعلًا إلى أكثر من واحدة، فاعزل المنافذ + الإعدادات/الحالة/مساحة العمل. راجع [/gateway#multiple-gateways-same-host](/ar/gateway#multiple-gateways-same-host). ذو صلة: @@ -212,9 +268,9 @@ openclaw gateway status --deep # يفحص أيضًا الخدمات على م - [/gateway/configuration](/ar/gateway/configuration) - [/gateway/doctor](/ar/gateway/doctor) -## تحذيرات فحص Gateway +## تحذيرات فحص البوابة -استخدم هذا القسم عندما يتمكن `openclaw gateway probe` من الوصول إلى شيء ما، لكنه لا يزال يطبع كتلة تحذير. +استخدم هذا عندما يصل `openclaw gateway probe` إلى شيء ما، لكنه لا يزال يطبع كتلة تحذير. ```bash openclaw gateway probe @@ -224,15 +280,15 @@ openclaw gateway probe --ssh user@gateway-host ابحث عن: -- `warnings[].code` و`primaryTargetId` في خرج JSON. -- ما إذا كان التحذير يتعلق ببديل SSH، أو تعدد الـ gateways، أو النطاقات المفقودة، أو مراجع المصادقة غير المحلولة. +- `warnings[].code` و `primaryTargetId` في مخرجات JSON. +- ما إذا كان التحذير متعلقًا بالرجوع إلى SSH، أو بوجود عدة بوابات، أو بنطاقات مفقودة، أو بمراجع مصادقة غير محلولة. -العلامات الشائعة: +الأنماط الشائعة: -- `SSH tunnel failed to start; falling back to direct probes.` → فشل إعداد SSH، لكن الأمر ما زال يجرّب الأهداف المباشرة المضبوطة/loopback. -- `multiple reachable gateways detected` → استجاب أكثر من هدف واحد. عادةً ما يعني هذا إعدادًا مقصودًا متعدد الـ gateways أو مستمعين قديمين/مكررَين. -- `Probe diagnostics are limited by gateway scopes (missing operator.read)` → نجح الاتصال، لكن RPC التفصيلي محدود بالنطاقات؛ قم بإقران هوية الجهاز أو استخدم بيانات اعتماد تحتوي على `operator.read`. -- نص تحذير SecretRef غير المحلول لـ `gateway.auth.*` / `gateway.remote.*` → كانت مواد المصادقة غير متاحة في مسار هذا الأمر للهدف الفاشل. +- `SSH tunnel failed to start; falling back to direct probes.` ← فشل إعداد SSH، لكن الأمر ما زال يحاول الأهداف المباشرة المضبوطة/loopback. +- `multiple reachable gateways detected` ← استجابت أكثر من جهة هدف. عادة يعني ذلك إعدادًا مقصودًا لعدة بوابات أو مستمعين قدامى/مكررين. +- `Probe diagnostics are limited by gateway scopes (missing operator.read)` ← نجح الاتصال، لكن تفاصيل RPC محدودة بالنطاقات؛ قم بإقران هوية الجهاز أو استخدم بيانات اعتماد تحتوي على `operator.read`. +- نص تحذير SecretRef غير المحلول لـ `gateway.auth.*` / `gateway.remote.*` ← لم تكن مواد المصادقة متاحة في مسار هذا الأمر للهدف الفاشل. ذو صلة: @@ -242,7 +298,7 @@ openclaw gateway probe --ssh user@gateway-host ## القناة متصلة لكن الرسائل لا تتدفق -إذا كانت حالة القناة متصلة لكن تدفق الرسائل متوقف، فركّز على السياسة، والأذونات، وقواعد التسليم الخاصة بالقناة. +إذا كانت حالة القناة متصلة لكن تدفق الرسائل متوقف، فركّز على السياسة والأذونات وقواعد التسليم الخاصة بالقناة. ```bash openclaw channels status --probe @@ -256,13 +312,13 @@ openclaw config get channels - سياسة الرسائل المباشرة (`pairing`، `allowlist`، `open`، `disabled`). - قائمة السماح للمجموعة ومتطلبات الإشارة. -- أذونات/نطاقات API الخاصة بالقناة المفقودة. +- أذونات/نطاقات API المفقودة الخاصة بالقناة. -العلامات الشائعة: +الأنماط الشائعة: -- `mention required` → تم تجاهل الرسالة بسبب سياسة الإشارة في المجموعة. -- آثار `pairing` / الموافقة المعلّقة → المرسل غير معتمد. -- `missing_scope`، `not_in_channel`، `Forbidden`، `401/403` → مشكلة في مصادقة/أذونات القناة. +- `mention required` ← تم تجاهل الرسالة بسبب سياسة الإشارة في المجموعة. +- `pairing` / آثار موافقة معلقة ← المرسل غير معتمد. +- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` ← مشكلة في مصادقة/أذونات القناة. ذو صلة: @@ -271,9 +327,9 @@ openclaw config get channels - [/channels/telegram](/ar/channels/telegram) - [/channels/discord](/ar/channels/discord) -## تسليم cron وheartbeat +## تسليم cron والنبضات -إذا لم يتم تشغيل cron أو heartbeat أو لم يتم التسليم، فتحقق أولًا من حالة المجدول، ثم من هدف التسليم. +إذا لم يتم تشغيل cron أو النبضات أو لم يتم تسليمهما، فتحقق أولًا من حالة المجدول، ثم من جهة التسليم المستهدفة. ```bash openclaw cron status @@ -285,19 +341,19 @@ openclaw logs --follow ابحث عن: -- أن cron مفعّل ووقت الاستيقاظ التالي موجود. +- أن cron مفعّل وأن وقت التنبيه التالي موجود. - حالة سجل تشغيل المهمة (`ok`، `skipped`، `error`). -- أسباب تخطي heartbeat (`quiet-hours`، `requests-in-flight`، `alerts-disabled`، `empty-heartbeat-file`، `no-tasks-due`). +- أسباب تخطي النبضات (`quiet-hours`، `requests-in-flight`، `alerts-disabled`، `empty-heartbeat-file`، `no-tasks-due`). -العلامات الشائعة: +الأنماط الشائعة: -- `cron: scheduler disabled; jobs will not run automatically` → تم تعطيل cron. -- `cron: timer tick failed` → فشل نبض المجدول؛ تحقق من أخطاء الملف/السجل/وقت التشغيل. -- `heartbeat skipped` مع `reason=quiet-hours` → خارج نافذة الساعات النشطة. -- `heartbeat skipped` مع `reason=empty-heartbeat-file` → الملف `HEARTBEAT.md` موجود لكنه يحتوي فقط على أسطر فارغة / عناوين markdown، لذلك يتخطى OpenClaw استدعاء النموذج. -- `heartbeat skipped` مع `reason=no-tasks-due` → يحتوي `HEARTBEAT.md` على كتلة `tasks:`، لكن لا توجد مهام مستحقة في هذه النبضة. -- `heartbeat: unknown accountId` → معرّف حساب غير صالح لهدف تسليم heartbeat. -- `heartbeat skipped` مع `reason=dm-blocked` → تم حل هدف heartbeat إلى وجهة على نمط الرسائل المباشرة بينما `agents.defaults.heartbeat.directPolicy` (أو التجاوز لكل وكيل) مضبوط على `block`. +- `cron: scheduler disabled; jobs will not run automatically` ← تم تعطيل cron. +- `cron: timer tick failed` ← فشلت نبضة المؤقت للمجدول؛ تحقق من أخطاء الملفات/السجلات/وقت التشغيل. +- `heartbeat skipped` مع `reason=quiet-hours` ← خارج نافذة الساعات النشطة. +- `heartbeat skipped` مع `reason=empty-heartbeat-file` ← يوجد `HEARTBEAT.md` لكنه يحتوي فقط على أسطر فارغة / عناوين markdown، لذلك يتجاوز OpenClaw استدعاء النموذج. +- `heartbeat skipped` مع `reason=no-tasks-due` ← يحتوي `HEARTBEAT.md` على كتلة `tasks:`، لكن لا توجد مهام مستحقة في هذه النبضة. +- `heartbeat: unknown accountId` ← معرّف حساب غير صالح لجهة تسليم النبضات المستهدفة. +- `heartbeat skipped` مع `reason=dm-blocked` ← تم حل هدف النبضات إلى وجهة بأسلوب الرسائل المباشرة بينما `agents.defaults.heartbeat.directPolicy` (أو تجاوز كل وكيل) مضبوط على `block`. ذو صلة: @@ -307,7 +363,7 @@ openclaw logs --follow ## فشل أداة العقدة المقترنة -إذا كانت العقدة مقترنة لكن الأدوات تفشل، فاعزل حالة الواجهة الأمامية، والأذونات، والموافقة. +إذا كانت العقدة مقترنة لكن الأدوات تفشل، فاعزل حالة المقدمة والأذونات والموافقات. ```bash openclaw nodes status @@ -319,16 +375,16 @@ openclaw status ابحث عن: -- أن العقدة متصلة وبها الإمكانات المتوقعة. -- منح أذونات نظام التشغيل للكاميرا/الميكروفون/الموقع/الشاشة. -- الموافقات التنفيذية وحالة قائمة السماح. +- أن العقدة متصلة بالإنترنت وبالقدرات المتوقعة. +- منح أذونات نظام التشغيل للكاميرا/المايكروفون/الموقع/الشاشة. +- حالة موافقات exec وقائمة السماح. -العلامات الشائعة: +الأنماط الشائعة: -- `NODE_BACKGROUND_UNAVAILABLE` → يجب أن يكون تطبيق العقدة في الواجهة الأمامية. -- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → أذونات نظام التشغيل مفقودة. -- `SYSTEM_RUN_DENIED: approval required` → موافقة التنفيذ معلّقة. -- `SYSTEM_RUN_DENIED: allowlist miss` → تم حظر الأمر بواسطة قائمة السماح. +- `NODE_BACKGROUND_UNAVAILABLE` ← يجب أن يكون تطبيق العقدة في المقدمة. +- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` ← إذن نظام تشغيل مفقود. +- `SYSTEM_RUN_DENIED: approval required` ← موافقة exec معلقة. +- `SYSTEM_RUN_DENIED: allowlist miss` ← تم حظر الأمر بواسطة قائمة السماح. ذو صلة: @@ -338,7 +394,7 @@ openclaw status ## فشل أداة المتصفح -استخدم هذا القسم عندما تفشل إجراءات أداة المتصفح رغم أن gateway نفسه بحالة سليمة. +استخدم هذا عندما تفشل إجراءات أداة المتصفح رغم أن البوابة نفسها سليمة. ```bash openclaw browser status @@ -351,38 +407,38 @@ openclaw doctor ابحث عن: - ما إذا كان `plugins.allow` مضبوطًا ويتضمن `browser`. -- صحة مسار الملف التنفيذي للمتصفح. +- مسار صالح لملف المتصفح التنفيذي. - إمكانية الوصول إلى ملف تعريف CDP. -- توفر Chrome المحلي لملفات التعريف `existing-session` / `user`. +- توفر Chrome محليًا لملفات تعريف `existing-session` / `user`. -العلامات الشائعة: +الأنماط الشائعة: -- `unknown command "browser"` أو `unknown command 'browser'` → تم استبعاد browser plugin المضمّن بواسطة `plugins.allow`. -- غياب أداة المتصفح / عدم توفرها بينما `browser.enabled=true` → يستبعد `plugins.allow` قيمة `browser`، لذلك لم يتم تحميل الـ plugin. -- `Failed to start Chrome CDP on port` → فشلت عملية المتصفح في الإطلاق. -- `browser.executablePath not found` → المسار المضبوط غير صالح. -- `browser.cdpUrl must be http(s) or ws(s)` → يستخدم عنوان CDP المضبوط مخططًا غير مدعوم مثل `file:` أو `ftp:`. -- `browser.cdpUrl has invalid port` → يحتوي عنوان CDP المضبوط على منفذ سيئ أو خارج النطاق. -- `No Chrome tabs found for profile="user"` → لا توجد علامات تبويب Chrome محلية مفتوحة لملف تعريف الإرفاق Chrome MCP. -- `Remote CDP for profile "" is not reachable` → تعذّر الوصول إلى نقطة نهاية CDP البعيدة المضبوطة من مضيف gateway. -- `Browser attachOnly is enabled ... not reachable` أو `Browser attachOnly is enabled and CDP websocket ... is not reachable` → لا يوجد هدف قابل للوصول لملف تعريف attach-only، أو أن نقطة نهاية HTTP استجابت لكن تعذّر مع ذلك فتح CDP WebSocket. -- `Playwright is not available in this gateway build; '' is unsupported.` → لا يحتوي تثبيت gateway الحالي على حزمة Playwright الكاملة؛ لا تزال لقطات ARIA ولقطات الشاشة الأساسية للصفحات تعمل، لكن التنقل ولقطات AI ولقطات العناصر باستخدام محددات CSS وتصدير PDF تظل غير متاحة. -- `fullPage is not supported for element screenshots` → خلط طلب لقطة الشاشة `--full-page` مع `--ref` أو `--element`. -- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → يجب أن تستخدم استدعاءات لقطات الشاشة الخاصة بـ Chrome MCP / `existing-session` التقاط الصفحة أو `--ref` من اللقطة، وليس CSS `--element`. -- `existing-session file uploads do not support element selectors; use ref/inputRef.` → تحتاج خطافات رفع الملفات في Chrome MCP إلى مراجع لقطات، لا إلى محددات CSS. -- `existing-session file uploads currently support one file at a time.` → أرسل عملية رفع واحدة لكل استدعاء في ملفات تعريف Chrome MCP. -- `existing-session dialog handling does not support timeoutMs.` → لا تدعم خطافات الحوار في ملفات تعريف Chrome MCP تجاوزات timeout. -- `response body is not supported for existing-session profiles yet.` → لا يزال `responsebody` يتطلب متصفحًا مُدارًا أو ملف تعريف CDP خامًا. -- تجاوزات viewport / dark-mode / locale / offline القديمة في ملفات تعريف attach-only أو CDP البعيدة → شغّل `openclaw browser stop --browser-profile ` لإغلاق جلسة التحكم النشطة وتحرير حالة المحاكاة Playwright/CDP بدون إعادة تشغيل gateway بالكامل. +- `unknown command "browser"` أو `unknown command 'browser'` ← تم استبعاد إضافة المتصفح المضمّنة بواسطة `plugins.allow`. +- أداة المتصفح مفقودة / غير متاحة بينما `browser.enabled=true` ← يستبعد `plugins.allow` المكوّن `browser`، لذا لم تُحمّل الإضافة أصلًا. +- `Failed to start Chrome CDP on port` ← فشلت عملية المتصفح في التشغيل. +- `browser.executablePath not found` ← المسار المضبوط غير صالح. +- `browser.cdpUrl must be http(s) or ws(s)` ← يستخدم عنوان CDP URL المضبوط مخططًا غير مدعوم مثل `file:` أو `ftp:`. +- `browser.cdpUrl has invalid port` ← يحتوي CDP URL المضبوط على منفذ سيئ أو خارج النطاق. +- `No Chrome tabs found for profile="user"` ← لا توجد علامات تبويب Chrome محلية مفتوحة لملف تعريف إرفاق Chrome MCP. +- `Remote CDP for profile "" is not reachable` ← نقطة نهاية CDP البعيدة المضبوطة غير قابلة للوصول من مضيف البوابة. +- `Browser attachOnly is enabled ... not reachable` أو `Browser attachOnly is enabled and CDP websocket ... is not reachable` ← لا يوجد هدف يمكن الوصول إليه لملف التعريف attach-only، أو أن نقطة نهاية HTTP استجابت لكن لم يمكن بعد ذلك فتح CDP WebSocket. +- `Playwright is not available in this gateway build; '' is unsupported.` ← يفتقر تثبيت البوابة الحالي إلى حزمة Playwright الكاملة؛ ولا تزال لقطات ARIA ولقطات الشاشة الأساسية للصفحات تعمل، لكن يظل التنقل ولقطات AI ولقطات عناصر محددات CSS وتصدير PDF غير متاحة. +- `fullPage is not supported for element screenshots` ← طلب لقطة الشاشة خلط `--full-page` مع `--ref` أو `--element`. +- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` ← يجب أن تستخدم استدعاءات لقطة الشاشة لـ Chrome MCP / `existing-session` التقاط الصفحة أو `--ref` من اللقطة، وليس CSS `--element`. +- `existing-session file uploads do not support element selectors; use ref/inputRef.` ← تحتاج خطافات رفع الملفات في Chrome MCP إلى مراجع لقطات، وليس محددات CSS. +- `existing-session file uploads currently support one file at a time.` ← أرسل ملف رفع واحدًا لكل استدعاء في ملفات تعريف Chrome MCP. +- `existing-session dialog handling does not support timeoutMs.` ← لا تدعم خطافات مربعات الحوار في ملفات تعريف Chrome MCP تجاوزات المهلة. +- `response body is not supported for existing-session profiles yet.` ← ما يزال `responsebody` يتطلب متصفحًا مُدارًا أو ملف تعريف CDP خامًا. +- تجاوزات قديمة لمنفذ العرض / الوضع الداكن / اللغة المحلية / عدم الاتصال في ملفات تعريف attach-only أو CDP البعيدة ← شغّل `openclaw browser stop --browser-profile ` لإغلاق جلسة التحكم النشطة وتحرير حالة محاكاة Playwright/CDP من دون إعادة تشغيل البوابة كاملة. ذو صلة: - [/tools/browser-linux-troubleshooting](/ar/tools/browser-linux-troubleshooting) - [/tools/browser](/ar/tools/browser) -## إذا قمت بالترقية وتوقف شيء ما فجأة +## إذا قمت بالترقية وتعطل شيء فجأة -معظم الأعطال بعد الترقية تكون بسبب انجراف في الإعداد أو فرض إعدادات افتراضية أكثر صرامة. +معظم الأعطال بعد الترقية تكون بسبب انجراف الإعدادات أو فرض إعدادات افتراضية أكثر صرامة الآن. ### 1) تغيّر سلوك المصادقة وتجاوز عنوان URL @@ -395,15 +451,15 @@ openclaw config get gateway.auth.mode ما الذي يجب التحقق منه: -- إذا كانت `gateway.mode=remote`، فقد تكون استدعاءات CLI تستهدف جهة بعيدة بينما خدمتك المحلية سليمة. -- لا تعود الاستدعاءات الصريحة `--url` إلى بيانات الاعتماد المخزنة. +- إذا كان `gateway.mode=remote`، فقد تستهدف استدعاءات CLI البيئة البعيدة بينما تكون خدمتك المحلية سليمة. +- الاستدعاءات الصريحة `--url` لا تعود إلى بيانات الاعتماد المخزنة. -العلامات الشائعة: +الأنماط الشائعة: -- `gateway connect failed:` → هدف URL غير صحيح. -- `unauthorized` → يمكن الوصول إلى نقطة النهاية لكن المصادقة غير صحيحة. +- `gateway connect failed:` ← هدف URL غير صحيح. +- `unauthorized` ← يمكن الوصول إلى نقطة النهاية لكن المصادقة خاطئة. -### 2) أصبحت قيود الربط والمصادقة أكثر صرامة +### 2) أصبحت ضوابط الربط والمصادقة أكثر صرامة ```bash openclaw config get gateway.bind @@ -415,13 +471,13 @@ openclaw logs --follow ما الذي يجب التحقق منه: -- تحتاج عمليات الربط non-loopback (`lan`، `tailnet`، `custom`) إلى مسار مصادقة صالح للـ gateway: مصادقة برمز/كلمة مرور مشتركة، أو نشر `trusted-proxy` مضبوط بشكل صحيح على non-loopback. -- لا تستبدل المفاتيح القديمة مثل `gateway.token` القيمة `gateway.auth.token`. +- تحتاج عمليات الربط غير loopback (`lan`، `tailnet`، `custom`) إلى مسار مصادقة صالح للبوابة: مصادقة برمز/كلمة مرور مشتركة، أو نشر `trusted-proxy` غير loopback مضبوط بشكل صحيح. +- المفاتيح القديمة مثل `gateway.token` لا تحل محل `gateway.auth.token`. -العلامات الشائعة: +الأنماط الشائعة: -- `refusing to bind gateway ... without auth` → ربط non-loopback بدون مسار مصادقة صالح للـ gateway. -- `RPC probe: failed` بينما وقت التشغيل يعمل → الـ gateway حي لكن يتعذر الوصول إليه باستخدام المصادقة/عنوان URL الحاليين. +- `refusing to bind gateway ... without auth` ← ربط غير loopback من دون مسار مصادقة صالح للبوابة. +- `RPC probe: failed` بينما وقت التشغيل يعمل ← البوابة حيّة لكن يتعذر الوصول إليها باستخدام إعدادات المصادقة/URL الحالية. ### 3) تغيّرت حالة الاقتران وهوية الجهاز @@ -434,15 +490,15 @@ openclaw doctor ما الذي يجب التحقق منه: -- طلبات الموافقة المعلقة للأجهزة الخاصة بـ dashboard/nodes. -- طلبات موافقة اقتران الرسائل المباشرة المعلقة بعد تغييرات السياسة أو الهوية. +- موافقات الأجهزة المعلقة لـ dashboard/nodes. +- موافقات اقتران الرسائل المباشرة المعلقة بعد تغييرات السياسة أو الهوية. -العلامات الشائعة: +الأنماط الشائعة: -- `device identity required` → لم يتم استيفاء مصادقة الجهاز. -- `pairing required` → يجب الموافقة على المرسل/الجهاز. +- `device identity required` ← لم تُستوفَ مصادقة الجهاز. +- `pairing required` ← يجب الموافقة على المرسل/الجهاز. -إذا ظل إعداد الخدمة ووقت التشغيل غير متطابقين بعد الفحوصات، فأعد تثبيت بيانات تعريف الخدمة من ملف التعريف/دليل الحالة نفسه: +إذا استمر عدم اتفاق إعدادات الخدمة ووقت التشغيل بعد عمليات التحقق، فأعد تثبيت بيانات تعريف الخدمة من الدليل نفسه للملف الشخصي/الحالة: ```bash openclaw gateway install --force diff --git a/docs/ar/help/faq.md b/docs/ar/help/faq.md index c60de1b90..bd4935966 100644 --- a/docs/ar/help/faq.md +++ b/docs/ar/help/faq.md @@ -1,23 +1,23 @@ --- read_when: - - الإجابة عن الأسئلة الشائعة المتعلقة بالإعداد أو التثبيت أو التهيئة الأولية أو دعم وقت التشغيل - - فرز المشكلات التي يبلغ عنها المستخدمون قبل البدء في تصحيح أعمق للأخطاء -summary: الأسئلة الشائعة حول إعداد OpenClaw وتهيئته واستخدامه + - الإجابة عن الأسئلة الشائعة المتعلقة بالإعداد أو التثبيت أو الإدخال الأولي أو دعم وقت التشغيل + - فرز المشكلات التي يبلغ عنها المستخدمون قبل بدء تصحيح أخطاء أعمق +summary: الأسئلة الشائعة حول إعداد OpenClaw وتكوينه واستخدامه title: الأسئلة الشائعة x-i18n: - generated_at: "2026-04-07T07:23:49Z" + generated_at: "2026-04-08T02:26:46Z" model: gpt-5.4 provider: openai - source_hash: bddcde55cf4bcec4913aadab4c665b235538104010e445e4c99915a1672b1148 + source_hash: 001b4605966b45b08108606f76ae937ec348c2179b04cf6fb34fef94833705e6 source_path: help/faq.md workflow: 15 --- # الأسئلة الشائعة -إجابات سريعة مع استكشاف أعمق للأخطاء في البيئات الواقعية (التطوير المحلي، VPS، تعدد الوكلاء، OAuth/API keys، وفشل النموذج الاحتياطي). لتشخيصات وقت التشغيل، راجع [استكشاف الأخطاء وإصلاحها](/ar/gateway/troubleshooting). وللاطلاع على مرجع الإعداد الكامل، راجع [الإعداد](/ar/gateway/configuration). +إجابات سريعة مع خطوات أعمق لاستكشاف الأخطاء وإصلاحها لعمليات الإعداد الواقعية (التطوير المحلي، VPS، تعدد الوكلاء، مفاتيح OAuth/API، والتبديل الاحتياطي للنماذج). لتشخيصات وقت التشغيل، راجع [استكشاف الأخطاء وإصلاحها](/ar/gateway/troubleshooting). وللمرجع الكامل للإعدادات، راجع [التكوين](/ar/gateway/configuration). -## أول 60 ثانية إذا كان هناك شيء معطل +## أول 60 ثانية إذا كان هناك شيء معطّل 1. **الحالة السريعة (أول فحص)** @@ -25,40 +25,40 @@ x-i18n: openclaw status ``` - ملخص محلي سريع: نظام التشغيل + التحديث، إمكانية الوصول إلى البوابة/الخدمة، الوكلاء/الجلسات، إعداد الموفر + مشكلات وقت التشغيل (عندما تكون البوابة قابلة للوصول). + ملخص محلي سريع: نظام التشغيل + التحديث، إمكانية الوصول إلى gateway/service، الوكلاء/الجلسات، إعدادات المزوّد + مشكلات وقت التشغيل (عند إمكانية الوصول إلى gateway). -2. **تقرير قابل للمشاركة (آمن للمشاركة)** +2. **تقرير قابل للمشاركة والنسخ** ```bash openclaw status --all ``` - تشخيص للقراءة فقط مع ذيل السجل (الرموز المميزة محجوبة). + تشخيص للقراءة فقط مع ذيل السجل (مع إخفاء الرموز المميزة). -3. **حالة الخدمة والمنفذ** +3. **حالة daemon + المنفذ** ```bash openclaw gateway status ``` - يعرض حالة المشرف أثناء التشغيل مقابل إمكانية الوصول عبر RPC، وعنوان URL المستهدف للفحص، وأي إعداد يُحتمل أن الخدمة استخدمته. + يعرض وقت تشغيل المشرف مقابل إمكانية الوصول عبر RPC، وعنوان URL المستهدف للفحص، وأي إعدادات يُرجّح أن الخدمة استخدمتها. -4. **فحوصات عميقة** +4. **فحوصات متعمقة** ```bash openclaw status --deep ``` - يشغّل فحصًا مباشرًا لصحة البوابة، بما في ذلك فحوصات القنوات عند دعمها - (يتطلب بوابة قابلة للوصول). راجع [الصحة](/ar/gateway/health). + يشغّل فحصًا مباشرًا لصحة gateway، بما في ذلك فحوصات القنوات عندما تكون مدعومة + (يتطلب gateway يمكن الوصول إليه). راجع [الصحة](/ar/gateway/health). -5. **تابع أحدث سجل** +5. **اعرض أحدث سجل** ```bash openclaw logs --follow ``` - إذا كان RPC متوقفًا، فارجع إلى: + إذا كان RPC متوقفًا، فاستخدم بدلًا من ذلك: ```bash tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" @@ -66,54 +66,54 @@ x-i18n: سجلات الملفات منفصلة عن سجلات الخدمة؛ راجع [التسجيل](/ar/logging) و[استكشاف الأخطاء وإصلاحها](/ar/gateway/troubleshooting). -6. **شغّل الطبيب (الإصلاحات)** +6. **شغّل أداة doctor (الإصلاحات)** ```bash openclaw doctor ``` - يصلح/يرحّل الإعداد والحالة + يشغّل فحوصات صحية. راجع [الطبيب](/ar/gateway/doctor). + يصلح/يرحّل الإعدادات/الحالة + يشغّل فحوصات الصحة. راجع [Doctor](/ar/gateway/doctor). -7. **لقطة البوابة** +7. **لقطة gateway** ```bash openclaw health --json - openclaw health --verbose # يعرض عنوان URL المستهدف + مسار الإعداد عند حدوث أخطاء + openclaw health --verbose # يعرض عنوان URL المستهدف + مسار الإعدادات عند وجود أخطاء ``` - يطلب من البوابة العاملة لقطة كاملة (WS فقط). راجع [الصحة](/ar/gateway/health). + يطلب من gateway الجاري تشغيله لقطة كاملة (WS فقط). راجع [الصحة](/ar/gateway/health). ## البدء السريع وإعداد التشغيل الأول - استخدم وكيل AI محليًا يمكنه **رؤية جهازك**. هذا أكثر فاعلية بكثير من السؤال - في Discord، لأن معظم حالات "أنا عالق" تكون **مشكلات إعداد أو بيئة محلية** - لا يستطيع المساعدون عن بُعد فحصها. + استخدم وكيل AI محلي يمكنه **رؤية جهازك**. هذا أكثر فاعلية بكثير من السؤال + في Discord، لأن معظم حالات "أنا عالق" تكون **مشكلات إعدادات أو بيئة محلية** + لا يستطيع المساعدون البعيدون فحصها. - **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/) - **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/) - يمكن لهذه الأدوات قراءة المستودع، وتشغيل الأوامر، وفحص السجلات، والمساعدة في إصلاح - الإعداد على مستوى جهازك (PATH، الخدمات، الأذونات، ملفات المصادقة). امنحها **نسخة - المصدر الكاملة** عبر التثبيت القابل للاختراق (git): + تستطيع هذه الأدوات قراءة المستودع، وتشغيل الأوامر، وفحص السجلات، والمساعدة في إصلاح + الإعداد على مستوى الجهاز لديك (PATH، الخدمات، الأذونات، ملفات المصادقة). امنحها + **نسخة المصدر كاملة** عبر تثبيت git القابل للاختراق: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - هذا يثبّت OpenClaw **من نسخة git**، بحيث يتمكن الوكيل من قراءة الشيفرة + الوثائق - والاستدلال على الإصدار الدقيق الذي تشغّله. ويمكنك دائمًا العودة إلى الإصدار المستقر لاحقًا - بإعادة تشغيل المثبّت من دون `--install-method git`. + يثبّت هذا OpenClaw **من نسخة git**، بحيث يتمكن الوكيل من قراءة الشيفرة + المستندات + والاستدلال على الإصدار الدقيق الذي تستخدمه. يمكنك دائمًا العودة إلى الإصدار المستقر لاحقًا + عبر إعادة تشغيل برنامج التثبيت بدون `--install-method git`. - نصيحة: اطلب من الوكيل أن **يخطط ويشرف** على الإصلاح (خطوة بخطوة)، ثم ينفّذ فقط - الأوامر الضرورية. هذا يبقي التغييرات صغيرة وأسهل في المراجعة. + نصيحة: اطلب من الوكيل أن **يخطط للإصلاح ويشرف عليه** (خطوة بخطوة)، ثم ينفذ فقط + الأوامر الضرورية. هذا يُبقي التغييرات صغيرة وأسهل في التدقيق. - إذا اكتشفت خطأ حقيقيًا أو إصلاحًا، فالرجاء فتح GitHub issue أو إرسال PR: + إذا اكتشفت خطأً حقيقيًا أو أصلحت شيئًا، فيرجى فتح issue على GitHub أو إرسال PR: [https://github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues) [https://github.com/openclaw/openclaw/pulls](https://github.com/openclaw/openclaw/pulls) - ابدأ بهذه الأوامر (وشارك المخرجات عند طلب المساعدة): + ابدأ بهذه الأوامر (شارك المخرجات عند طلب المساعدة): ```bash openclaw status @@ -123,42 +123,42 @@ x-i18n: ما الذي تفعله: - - `openclaw status`: لقطة سريعة لصحة البوابة/الوكيل + الإعداد الأساسي. - - `openclaw models status`: يفحص مصادقة الموفر + توفر النماذج. - - `openclaw doctor`: يتحقق من مشكلات الإعداد/الحالة الشائعة ويصلحها. + - `openclaw status`: لقطة سريعة لصحة gateway/agent + الإعدادات الأساسية. + - `openclaw models status`: يتحقق من مصادقة المزوّد + توفر النماذج. + - `openclaw doctor`: يتحقق من مشكلات الإعدادات/الحالة الشائعة ويصلحها. فحوصات CLI أخرى مفيدة: `openclaw status --all`, `openclaw logs --follow`, `openclaw gateway status`, `openclaw health --verbose`. - حلقة تصحيح سريعة: [أول 60 ثانية إذا كان هناك شيء معطل](#first-60-seconds-if-something-is-broken). - وثائق التثبيت: [التثبيت](/ar/install)، [أعلام المثبّت](/ar/install/installer)، [التحديث](/ar/install/updating). + حلقة تصحيح سريعة: [أول 60 ثانية إذا كان هناك شيء معطّل](#أول-60-ثانية-إذا-كان-هناك-شيء-معطّل). + مستندات التثبيت: [التثبيت](/ar/install)، [إشارات برنامج التثبيت](/ar/install/installer)، [التحديث](/ar/install/updating). - أسباب تخطي Heartbeat الشائعة: + أسباب تخطي heartbeat الشائعة: - - `quiet-hours`: خارج نافذة الساعات النشطة المهيأة - - `empty-heartbeat-file`: الملف `HEARTBEAT.md` موجود لكنه يحتوي فقط على هيكل فارغ/عناوين فقط - - `no-tasks-due`: وضع مهام `HEARTBEAT.md` نشط لكن لم يحن موعد أي من فواصل المهام بعد - - `alerts-disabled`: كل إظهار Heartbeat معطّل (`showOk` و`showAlerts` و`useIndicator` كلها متوقفة) + - `quiet-hours`: خارج نافذة active-hours المكوّنة + - `empty-heartbeat-file`: يوجد `HEARTBEAT.md` لكنه يحتوي فقط على هيكل فارغ/عناوين فقط + - `no-tasks-due`: وضع مهام `HEARTBEAT.md` نشط ولكن لم يحن موعد أي من فترات المهام بعد + - `alerts-disabled`: تم تعطيل كل ظهور heartbeat (`showOk` و`showAlerts` و`useIndicator` كلها متوقفة) - في وضع المهام، لا يتم تقديم الطوابع الزمنية المستحقة إلا بعد اكتمال تشغيل Heartbeat - حقيقي. ولا تضع عمليات التشغيل المتخطاة علامة اكتمال على المهام. + في وضع المهام، لا يتم تقديم الطوابع الزمنية المستحقة إلا بعد اكتمال تشغيل heartbeat + فعليًا. عمليات التشغيل المتخطاة لا تضع علامة على المهام بأنها مكتملة. - الوثائق: [Heartbeat](/ar/gateway/heartbeat)، [الأتمتة والمهام](/ar/automation). + المستندات: [Heartbeat](/ar/gateway/heartbeat)، [الأتمتة والمهام](/ar/automation). - يوصي المستودع بالتشغيل من المصدر واستخدام التهيئة الأولية: + يوصي المستودع بالتشغيل من المصدر واستخدام الإدخال الأولي: ```bash curl -fsSL https://openclaw.ai/install.sh | bash openclaw onboard --install-daemon ``` - يمكن للمعالج أيضًا بناء أصول واجهة المستخدم تلقائيًا. بعد التهيئة الأولية، عادةً ما تشغّل Gateway على المنفذ **18789**. + يمكن للمعالج أيضًا بناء أصول UI تلقائيًا. بعد الإدخال الأولي، ستشغّل عادةً Gateway على المنفذ **18789**. من المصدر (للمساهمين/المطورين): @@ -167,94 +167,94 @@ x-i18n: cd openclaw pnpm install pnpm build - pnpm ui:build # يثبّت تبعيات واجهة المستخدم تلقائيًا في أول تشغيل + pnpm ui:build # يثبت تبعيات UI تلقائيًا عند أول تشغيل openclaw onboard ``` - إذا لم يكن لديك تثبيت عام بعد، فشغّله عبر `pnpm openclaw onboard`. + إذا لم يكن لديك تثبيت عام بعد، شغّله عبر `pnpm openclaw onboard`. - - يفتح المعالج متصفحك بعنوان URL نظيف للوحة التحكم (من دون رمز مميز في الرابط) مباشرة بعد التهيئة الأولية، كما يطبع الرابط في الملخص. أبقِ تلك الصفحة مفتوحة؛ وإذا لم تُفتح تلقائيًا، فانسخ/الصق عنوان URL المطبوع على الجهاز نفسه. + + يفتح المعالج متصفحك بعنوان URL نظيف للوحة التحكم (من دون token) مباشرةً بعد الإدخال الأولي، كما يطبع الرابط في الملخص. أبقِ هذا التبويب مفتوحًا؛ وإذا لم يُفتح تلقائيًا، انسخ/ألصق عنوان URL المطبوع على الجهاز نفسه. - - **على localhost (نفس الجهاز):** + + **Localhost (الجهاز نفسه):** - افتح `http://127.0.0.1:18789/`. - - إذا طلبت مصادقة shared-secret، فأدخل الرمز المميز أو كلمة المرور المهيأة في إعدادات Control UI. - - مصدر الرمز المميز: `gateway.auth.token` (أو `OPENCLAW_GATEWAY_TOKEN`). - - مصدر كلمة المرور: `gateway.auth.password` (أو `OPENCLAW_GATEWAY_PASSWORD`). - - إذا لم يكن هناك shared secret مهيأ بعد، فأنشئ رمزًا مميزًا باستخدام `openclaw doctor --generate-gateway-token`. + - إذا طلب مصادقة shared-secret، الصق token أو password المكوّن في إعدادات Control UI. + - مصدر token: `gateway.auth.token` (أو `OPENCLAW_GATEWAY_TOKEN`). + - مصدر password: `gateway.auth.password` (أو `OPENCLAW_GATEWAY_PASSWORD`). + - إذا لم يتم تكوين shared secret بعد، أنشئ token عبر `openclaw doctor --generate-gateway-token`. **ليس على localhost:** - - **Tailscale Serve** (موصى به): أبقِ الربط على loopback، وشغّل `openclaw gateway --tailscale serve`، ثم افتح `https:///`. إذا كانت `gateway.auth.allowTailscale` تساوي `true`، فإن رؤوس الهوية تفي بمصادقة Control UI/WebSocket (من دون لصق shared secret، مع افتراض أن مضيف البوابة موثوق)؛ ولا تزال واجهات HTTP APIs تتطلب مصادقة shared-secret ما لم تستخدم عمدًا `none` في private-ingress أو مصادقة HTTP لموجه موثوق. - تتم تسوية محاولات مصادقة Serve المتزامنة السيئة من العميل نفسه قبل أن يسجّل محدد المصادقة الفاشلة المحاولة، لذلك قد تُظهر المحاولة السيئة الثانية بالفعل `retry later`. - - **ربط Tailnet**: شغّل `openclaw gateway --bind tailnet --token ""` (أو اضبط مصادقة بكلمة مرور)، ثم افتح `http://:18789/`، ثم الصق shared secret المطابق في إعدادات لوحة التحكم. - - **موجه عكسي مدرك للهوية**: أبقِ Gateway خلف موجه موثوق غير loopback، واضبط `gateway.auth.mode: "trusted-proxy"`، ثم افتح عنوان URL الخاص بالموجه. - - **نفق SSH**: `ssh -N -L 18789:127.0.0.1:18789 user@host` ثم افتح `http://127.0.0.1:18789/`. تظل مصادقة shared-secret مطبقة عبر النفق؛ الصق الرمز المميز أو كلمة المرور المهيأة إذا طُلب منك ذلك. + - **Tailscale Serve** (موصى به): أبقِ الربط على loopback، وشغّل `openclaw gateway --tailscale serve`، وافتح `https:///`. إذا كانت `gateway.auth.allowTailscale` تساوي `true`، فإن رؤوس الهوية تفي بمصادقة Control UI/WebSocket (من دون لصق shared secret، مع افتراض الثقة في مضيف gateway)؛ ولا تزال واجهات HTTP APIs تتطلب مصادقة shared-secret ما لم تستخدم عمدًا `none` في private-ingress أو مصادقة HTTP عبر trusted-proxy. + تتم موازنة محاولات Serve السيئة المتزامنة من العميل نفسه قبل أن يسجل محدِّد المصادقة الفاشلة هذه المحاولات، لذلك قد تُظهر المحاولة السيئة الثانية بالفعل `retry later`. + - **ربط tailnet**: شغّل `openclaw gateway --bind tailnet --token ""` (أو اضبط مصادقة password)، وافتح `http://:18789/`، ثم الصق shared secret المطابق في إعدادات لوحة التحكم. + - **وكيل عكسي مدرك للهوية**: أبقِ Gateway خلف trusted proxy غير loopback، واضبط `gateway.auth.mode: "trusted-proxy"`، ثم افتح عنوان URL للوكيل. + - **نفق SSH**: `ssh -N -L 18789:127.0.0.1:18789 user@host` ثم افتح `http://127.0.0.1:18789/`. لا تزال مصادقة shared-secret مطبقة عبر النفق؛ الصق token أو password المكوّن إذا طُلب منك ذلك. - راجع [لوحة التحكم](/web/dashboard) و[أسطح الويب](/web) للاطلاع على أوضاع الربط وتفاصيل المصادقة. + راجع [لوحة التحكم](/web/dashboard) و[أسطح الويب](/web) لمعرفة تفاصيل أوضاع الربط والمصادقة. - - يتحكمان في طبقتين مختلفتين: + + إنهما تتحكمان في طبقتين مختلفتين: - - `approvals.exec`: يوجّه طلبات الموافقة إلى وجهات الدردشة + - `approvals.exec`: يمرر مطالبات الموافقة إلى وجهات الدردشة - `channels..execApprovals`: يجعل تلك القناة تعمل كعميل موافقة أصلي لموافقات exec - تظل سياسة exec على المضيف هي بوابة الموافقة الحقيقية. إعداد الدردشة يتحكم فقط في مكان ظهور - طلبات الموافقة وكيفية رد الأشخاص عليها. + تبقى سياسة exec على المضيف هي بوابة الموافقة الحقيقية. إعدادات الدردشة تتحكم فقط في مكان + ظهور مطالبات الموافقة وكيفية تمكين الأشخاص من الرد عليها. - في معظم الإعدادات **لا** تحتاج إلى كليهما: + في معظم الإعدادات **لا** تحتاج إلى الاثنين معًا: - إذا كانت الدردشة تدعم الأوامر والردود بالفعل، فإن `/approve` في نفس الدردشة يعمل عبر المسار المشترك. - - إذا استطاعت قناة أصلية مدعومة استنتاج الموافقين بأمان، فإن OpenClaw يفعّل الآن الموافقات الأصلية DM-first تلقائيًا عندما تكون `channels..execApprovals.enabled` غير مضبوطة أو مساوية لـ `"auto"`. - - عندما تكون بطاقات/أزرار الموافقة الأصلية متاحة، تكون واجهة المستخدم الأصلية هي المسار الأساسي؛ ولا ينبغي للوكيل أن يتضمن أمر `/approve` يدويًا إلا إذا كانت نتيجة الأداة تشير إلى أن موافقات الدردشة غير متاحة أو أن الموافقة اليدوية هي المسار الوحيد. - - استخدم `approvals.exec` فقط عندما يجب أيضًا إعادة توجيه الطلبات إلى دردشات أخرى أو غرف عمليات صريحة. - - استخدم `channels..execApprovals.target: "channel"` أو `"both"` فقط عندما تريد صراحة نشر طلبات الموافقة مرة أخرى في الغرفة/الموضوع الأصلي. - - موافقات plugin منفصلة مرة أخرى: فهي تستخدم `/approve` في نفس الدردشة افتراضيًا، مع توجيه `approvals.plugin` الاختياري، ولا تحتفظ إلا بعض القنوات الأصلية بمعالجة موافقة plugin الأصلية فوق ذلك. + - إذا كانت قناة أصلية مدعومة تستطيع استنتاج الموافقين بأمان، فإن OpenClaw يفعّل الآن تلقائيًا الموافقات الأصلية بنمط DM-first عندما تكون `channels..execApprovals.enabled` غير مضبوطة أو مضبوطة على `"auto"`. + - عندما تكون بطاقات/أزرار الموافقة الأصلية متاحة، تكون واجهة المستخدم الأصلية هي المسار الأساسي؛ ويجب على الوكيل تضمين أمر `/approve` يدويًا فقط إذا كانت نتيجة الأداة تقول إن موافقات الدردشة غير متاحة أو أن الموافقة اليدوية هي المسار الوحيد. + - استخدم `approvals.exec` فقط عندما يلزم أيضًا تمرير المطالبات إلى دردشات أخرى أو غرف تشغيل مخصصة. + - استخدم `channels..execApprovals.target: "channel"` أو `"both"` فقط عندما تريد صراحةً نشر مطالبات الموافقة مرة أخرى في الغرفة/الموضوع الأصلي. + - موافقات plugin منفصلة مرة أخرى: فهي تستخدم `/approve` في نفس الدردشة افتراضيًا، مع تمرير اختياري عبر `approvals.plugin`، وفقط بعض القنوات الأصلية تُبقي معالجة plugin-approval-native فوق ذلك. - النسخة المختصرة: التوجيه مخصص للمسار، أما إعداد العميل الأصلي فمخصص لتجربة مستخدم أغنى خاصة بالقناة. + باختصار: التمرير مخصص للتوجيه، وإعدادات العميل الأصلي مخصصة لتجربة مستخدم أغنى خاصة بالقناة. راجع [موافقات Exec](/ar/tools/exec-approvals). - - يتطلب Node **>= 22**. ويُنصح باستخدام `pnpm`. ولا يُنصح باستخدام Bun مع Gateway. + + يلزم Node **>= 22**. ويُنصح باستخدام `pnpm`. ولا يُنصح باستخدام Bun مع Gateway. - نعم. Gateway خفيف الوزن - توضح الوثائق أن **512MB-1GB RAM**، و**نواة واحدة**، وحوالي **500MB** - من القرص كافية للاستخدام الشخصي، كما تشير إلى أن **Raspberry Pi 4 يمكنه تشغيله**. + نعم. Gateway خفيفة - وتذكر المستندات أن **512MB-1GB RAM** و**نواة واحدة** وحوالي **500MB** + من مساحة القرص تكفي للاستخدام الشخصي، وتشير إلى أن **Raspberry Pi 4 يمكنه تشغيله**. - إذا أردت هامشًا إضافيًا (للسجلات، والوسائط، والخدمات الأخرى)، فإن **2GB موصى بها**، لكنها + إذا كنت تريد هامشًا إضافيًا (السجلات، الوسائط، خدمات أخرى)، فإن **2GB موصى بها**، لكنها ليست حدًا أدنى صارمًا. - نصيحة: يمكن لجهاز Pi/VPS صغير استضافة Gateway، ويمكنك إقران **nodes** على حاسوبك المحمول/هاتفك - للوصول إلى الشاشة/الكاميرا/Canvas محليًا أو تنفيذ الأوامر. راجع [Nodes](/ar/nodes). + نصيحة: يمكن لجهاز Pi/VPS صغير استضافة Gateway، ويمكنك إقران **nodes** على حاسوبك المحمول/هاتفك من أجل + الشاشة/الكاميرا/الـ canvas المحلية أو تنفيذ الأوامر. راجع [Nodes](/ar/nodes). - النسخة المختصرة: نعم، يعمل، لكن توقّع بعض الحواف الخشنة. + باختصار: يعمل، لكن توقّع بعض الزوايا الخشنة. - استخدم نظام تشغيل **64-bit** وأبقِ Node >= 22. - - فضّل **التثبيت القابل للاختراق (git)** حتى تتمكن من رؤية السجلات والتحديث بسرعة. - - ابدأ من دون channels/Skills، ثم أضفها واحدًا واحدًا. - - إذا واجهت مشكلات غريبة في الثنائيات، فعادةً ما تكون مشكلة **توافق ARM**. + - فضّل **تثبيت git القابل للاختراق** حتى تتمكن من رؤية السجلات والتحديث بسرعة. + - ابدأ بدون قنوات/Skills، ثم أضفها واحدة تلو الأخرى. + - إذا واجهت مشكلات غريبة تتعلق بالثنائيات، فعادةً ما تكون مشكلة **توافق ARM**. - الوثائق: [Linux](/ar/platforms/linux)، [التثبيت](/ar/install). + المستندات: [Linux](/ar/platforms/linux)، [التثبيت](/ar/install). - - تعتمد تلك الشاشة على أن تكون Gateway قابلة للوصول وموثقة. كما أن TUI يرسل - "Wake up, my friend!" تلقائيًا عند أول فتح. إذا رأيت هذا السطر **من دون رد** - وبقيت الرموز عند 0، فهذا يعني أن الوكيل لم يعمل. + + تعتمد هذه الشاشة على أن يكون Gateway قابلاً للوصول ومصادقًا عليه. كما يرسل TUI + "Wake up, my friend!" تلقائيًا عند أول hatch. إذا رأيت هذا السطر **من دون رد** + وبقيت الرموز عند 0، فهذا يعني أن الوكيل لم يعمل مطلقًا. 1. أعد تشغيل Gateway: @@ -262,7 +262,7 @@ x-i18n: openclaw gateway restart ``` - 2. تحقّق من الحالة + المصادقة: + 2. تحقق من الحالة + المصادقة: ```bash openclaw status @@ -270,82 +270,83 @@ x-i18n: openclaw logs --follow ``` - 3. إذا ظل معلقًا، فشغّل: + 3. إذا ظل معلقًا، شغّل: ```bash openclaw doctor ``` - إذا كانت Gateway بعيدة، فتأكد من أن اتصال النفق/Tailscale يعمل وأن واجهة المستخدم - تشير إلى Gateway الصحيحة. راجع [الوصول البعيد](/ar/gateway/remote). + إذا كان Gateway بعيدًا، فتأكد من أن اتصال tunnel/Tailscale قائم وأن UI + يشير إلى Gateway الصحيح. راجع [الوصول البعيد](/ar/gateway/remote). - + نعم. انسخ **دليل الحالة** و**مساحة العمل**، ثم شغّل Doctor مرة واحدة. هذا - يبقي البوت "كما هو تمامًا" (الذاكرة، سجل الجلسات، المصادقة، وحالة القنوات) - طالما أنك تنسخ **الموقعين** معًا: + يُبقي bot لديك "كما هو تمامًا" (الذاكرة، محفوظات الجلسات، المصادقة، وحالة + القناة) طالما أنك تنسخ **الموقعين** معًا: 1. ثبّت OpenClaw على الجهاز الجديد. 2. انسخ `$OPENCLAW_STATE_DIR` (الافتراضي: `~/.openclaw`) من الجهاز القديم. - 3. انسخ مساحة العمل الخاصة بك (الافتراضي: `~/.openclaw/workspace`). + 3. انسخ مساحة العمل لديك (الافتراضي: `~/.openclaw/workspace`). 4. شغّل `openclaw doctor` وأعد تشغيل خدمة Gateway. - يحافظ ذلك على الإعداد، وملفات تعريف المصادقة، وبيانات اعتماد WhatsApp، والجلسات، والذاكرة. وإذا كنت في - الوضع البعيد، فتذكّر أن مضيف البوابة هو من يملك مخزن الجلسات ومساحة العمل. + يحافظ ذلك على الإعدادات وملفات تعريف المصادقة وبيانات اعتماد WhatsApp والجلسات والذاكرة. إذا كنت في + الوضع البعيد، فتذكّر أن مضيف gateway هو الذي يملك مخزن الجلسات ومساحة العمل. **مهم:** إذا كنت فقط تقوم بعمل commit/push لمساحة العمل إلى GitHub، فأنت تنسخ - **الذاكرة + ملفات bootstrap**، لكن **ليس** سجل الجلسات أو المصادقة. فهذه توجد + احتياطيًا **ملفات الذاكرة + ملفات bootstrap**، لكن **ليس** محفوظات الجلسات أو المصادقة. هذه تعيش ضمن `~/.openclaw/` (مثلًا `~/.openclaw/agents//sessions/`). - ذو صلة: [الترحيل](/ar/install/migrating)، [أماكن تخزين الأشياء على القرص](#where-things-live-on-disk)، + ذو صلة: [الترحيل](/ar/install/migrating)، [مكان وجود الأشياء على القرص](#مكان-وجود-الأشياء-على-القرص)، [مساحة عمل الوكيل](/ar/concepts/agent-workspace)، [Doctor](/ar/gateway/doctor)، [الوضع البعيد](/ar/gateway/remote). - - راجع سجل التغييرات على GitHub: + + تحقق من سجل التغييرات على GitHub: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - أحدث الإدخالات تكون في الأعلى. وإذا كان القسم العلوي يحمل علامة **Unreleased**، فالقسم المؤرخ - التالي هو أحدث إصدار تم شحنه. يتم تجميع الإدخالات تحت **Highlights** و**Changes** و - **Fixes** (مع أقسام للوثائق/أخرى عند الحاجة). + أحدث الإدخالات تكون في الأعلى. إذا كان القسم العلوي معنونًا **Unreleased**، فالقسم المؤرخ التالي + هو أحدث إصدار تم شحنه. تُجمع الإدخالات تحت **Highlights** و**Changes** و + **Fixes** (مع أقسام للمستندات/أمور أخرى عند الحاجة). - بعض اتصالات Comcast/Xfinity تحظر `docs.openclaw.ai` بشكل غير صحيح عبر Xfinity - Advanced Security. عطّله أو أضف `docs.openclaw.ai` إلى قائمة السماح ثم أعد المحاولة. - الرجاء مساعدتنا في رفع الحظر بالإبلاغ هنا: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status). + تقوم بعض اتصالات Comcast/Xfinity بحظر `docs.openclaw.ai` بشكل غير صحيح عبر Xfinity + Advanced Security. قم بتعطيله أو أضف `docs.openclaw.ai` إلى allowlist ثم أعد المحاولة. + نرجو مساعدتنا في فك الحظر عبر الإبلاغ هنا: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status). - إذا كنت لا تزال غير قادر على الوصول إلى الموقع، فالوثائق لها مرآة على GitHub: + إذا ظل يتعذر عليك الوصول إلى الموقع، فالمستندات معكوسة على GitHub: [https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs) - - **Stable** و**beta** هما **npm dist-tags**، وليسا خطي شيفرة منفصلين: + + **Stable** و**beta** هما **npm dist-tags**، وليسا خطّي شيفرة منفصلين: - `latest` = مستقر - - `beta` = بناء مبكر للاختبار + - `beta` = إصدار مبكر للاختبار - عادةً، يصل الإصدار المستقر إلى **beta** أولًا، ثم تقوم خطوة - ترقية صريحة بنقل الإصدار نفسه إلى `latest`. ويمكن للمشرفين أيضًا - النشر مباشرة إلى `latest` عند الحاجة. ولهذا يمكن أن يشير beta وstable إلى **الإصدار نفسه** بعد الترقية. + عادةً، يصل الإصدار المستقر إلى **beta** أولًا، ثم تنقل خطوة ترقية + صريحة ذلك الإصدار نفسه إلى `latest`. ويمكن للمشرفين أيضًا + النشر مباشرةً إلى `latest` عند الحاجة. ولهذا قد يشير beta وstable + إلى **الإصدار نفسه** بعد الترقية. - راجع ما الذي تغيّر: + اعرف ما الذي تغيّر: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - وللاطلاع على أوامر التثبيت السريعة والفارق بين beta وdev، راجع القسم القابل للطي أدناه. + لمعرفة أوامر التثبيت المختصرة والفرق بين beta وdev، راجع القسم المطوي أدناه. - - **Beta** هو npm dist-tag باسم `beta` (وقد يطابق `latest` بعد الترقية). - **Dev** هو رأس فرع `main` المتحرك (git)؛ وعند نشره يستخدم npm dist-tag باسم `dev`. + + **Beta** هو npm dist-tag المسمى `beta` (وقد يطابق `latest` بعد الترقية). + **Dev** هو الرأس المتحرك لفرع `main` (git)؛ وعند نشره يستخدم npm dist-tag `dev`. - أوامر سريعة (macOS/Linux): + أوامر مختصرة (macOS/Linux): ```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --beta @@ -355,15 +356,15 @@ x-i18n: curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - مثبّت Windows (PowerShell): + برنامج تثبيت Windows (PowerShell): [https://openclaw.ai/install.ps1](https://openclaw.ai/install.ps1) - مزيد من التفاصيل: [قنوات التطوير](/ar/install/development-channels) و[أعلام المثبّت](/ar/install/installer). + مزيد من التفاصيل: [قنوات التطوير](/ar/install/development-channels) و[إشارات برنامج التثبيت](/ar/install/installer). - - لديك خياران: + + هناك خياران: 1. **قناة Dev (نسخة git):** @@ -371,17 +372,17 @@ x-i18n: openclaw update --channel dev ``` - هذا يبدّل إلى فرع `main` ويحدّث من المصدر. + ينقلك هذا إلى الفرع `main` ويحدّث من المصدر. - 2. **تثبيت قابل للاختراق (من موقع المثبّت):** + 2. **تثبيت قابل للاختراق (من موقع برنامج التثبيت):** ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - يمنحك ذلك مستودعًا محليًا يمكنك تعديله، ثم تحديثه عبر git. + يمنحك هذا مستودعًا محليًا يمكنك تعديله، ثم تحديثه عبر git. - إذا كنت تفضّل نسخة نظيفة يدويًا، فاستخدم: + إذا كنت تفضل نسخة نظيفة يدويًا، فاستخدم: ```bash git clone https://github.com/openclaw/openclaw.git @@ -390,63 +391,63 @@ x-i18n: pnpm build ``` - الوثائق: [التحديث](/cli/update)، [قنوات التطوير](/ar/install/development-channels)، + المستندات: [التحديث](/cli/update)، [قنوات التطوير](/ar/install/development-channels)، [التثبيت](/ar/install). - + دليل تقريبي: - **التثبيت:** 2-5 دقائق - - **التهيئة الأولية:** 5-15 دقيقة بحسب عدد channels/models التي تهيئها + - **الإدخال الأولي:** 5-15 دقيقة بحسب عدد القنوات/النماذج التي تضبطها - إذا علِق، فاستخدم [تعطل المثبّت](#quick-start-and-first-run-setup) - وحلقة التصحيح السريعة في [أنا عالق](#quick-start-and-first-run-setup). + إذا علق، فاستخدم [تعطل برنامج التثبيت](#البدء-السريع-وإعداد-التشغيل-الأول) + وحلقة التصحيح السريعة في [أنا عالق](#البدء-السريع-وإعداد-التشغيل-الأول). - - أعد تشغيل المثبّت مع **مخرجات تفصيلية**: + + أعد تشغيل برنامج التثبيت مع **مخرجات تفصيلية**: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose ``` - تثبيت Beta مع الوضع التفصيلي: + تثبيت beta مع verbose: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose ``` - لتثبيت قابل للاختراق (git): + لتثبيت git قابل للاختراق: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose ``` - ما يعادل ذلك على Windows (PowerShell): + النظير في Windows (PowerShell): ```powershell - # install.ps1 لا يحتوي بعد على علم -Verbose مخصص. + # install.ps1 لا يحتوي بعد على علامة -Verbose مخصصة. Set-PSDebug -Trace 1 & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard Set-PSDebug -Trace 0 ``` - خيارات أكثر: [أعلام المثبّت](/ar/install/installer). + مزيد من الخيارات: [إشارات برنامج التثبيت](/ar/install/installer). - - مشكلتان شائعتان على Windows: + + مشكلتان شائعتان في Windows: - **1) خطأ npm spawn git / git غير موجود** + **1) خطأ npm spawn git / git not found** - ثبّت **Git for Windows** وتأكد من أن `git` موجود على PATH. - - أغلق PowerShell وأعد فتحه، ثم أعد تشغيل المثبّت. + - أغلق PowerShell وافتحه مجددًا، ثم أعد تشغيل برنامج التثبيت. - **2) openclaw غير معروف بعد التثبيت** + **2) openclaw is not recognized بعد التثبيت** - مجلد npm global bin غير موجود على PATH. - تحقق من المسار: @@ -455,21 +456,21 @@ x-i18n: npm config get prefix ``` - - أضف ذلك الدليل إلى PATH الخاص بالمستخدم (لا حاجة إلى اللاحقة `\bin` على Windows؛ وفي معظم الأنظمة يكون `%AppData%\npm`). - - أغلق PowerShell وأعد فتحه بعد تحديث PATH. + - أضف ذلك الدليل إلى PATH الخاص بالمستخدم لديك (لا حاجة إلى اللاحقة `\bin` على Windows؛ في معظم الأنظمة يكون `%AppData%\npm`). + - أغلق PowerShell وافتحه مجددًا بعد تحديث PATH. - إذا أردت أسهل إعداد على Windows، فاستخدم **WSL2** بدل Windows الأصلي. - الوثائق: [Windows](/ar/platforms/windows). + إذا أردت أكثر إعداد Windows سلاسة، فاستخدم **WSL2** بدل Windows الأصلي. + المستندات: [Windows](/ar/platforms/windows). - - يحدث هذا عادةً بسبب عدم تطابق صفحة ترميز وحدة التحكم في صدَفات Windows الأصلية. + + هذا عادةً بسبب عدم تطابق code page في الطرفية على Windows الأصلي. الأعراض: - - يظهر خرج `system.run`/`exec` للنص الصيني بشكل مشوه - - يبدو الأمر نفسه صحيحًا في ملف تعريف طرفية آخر + - مخرجات `system.run`/`exec` تعرض النص الصيني بشكل مشوّه + - الأمر نفسه يبدو جيدًا في ملف تعريف طرفية آخر حل سريع في PowerShell: @@ -486,66 +487,66 @@ x-i18n: openclaw gateway restart ``` - إذا كنت لا تزال ترى هذا على أحدث إصدار من OpenClaw، فتابعه/أبلِغ عنه هنا: + إذا ما زلت تستطيع إعادة إنتاج المشكلة على أحدث إصدار من OpenClaw، فتابعها/أبلغ عنها في: - [Issue #30640](https://github.com/openclaw/openclaw/issues/30640) - - استخدم **التثبيت القابل للاختراق (git)** بحيث تملك المصدر الكامل والوثائق محليًا، ثم اسأل - البوت الخاص بك (أو Claude/Codex) _من داخل ذلك المجلد_ حتى يتمكن من قراءة المستودع والإجابة بدقة. + + استخدم **تثبيت git القابل للاختراق** حتى تكون لديك الشيفرة والمستندات كاملة محليًا، ثم اسأل + bot لديك (أو Claude/Codex) _من ذلك المجلد_ حتى يتمكن من قراءة المستودع والإجابة بدقة. ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - مزيد من التفاصيل: [التثبيت](/ar/install) و[أعلام المثبّت](/ar/install/installer). + مزيد من التفاصيل: [التثبيت](/ar/install) و[إشارات برنامج التثبيت](/ar/install/installer). - - الإجابة المختصرة: اتبع دليل Linux، ثم شغّل التهيئة الأولية. + + الإجابة المختصرة: اتبع دليل Linux، ثم شغّل الإدخال الأولي. - المسار السريع لـ Linux + تثبيت الخدمة: [Linux](/ar/platforms/linux). - - الشرح الكامل: [البدء](/ar/start/getting-started). - - المثبّت + التحديثات: [التثبيت والتحديثات](/ar/install/updating). + - شرح كامل: [البدء](/ar/start/getting-started). + - برنامج التثبيت + التحديثات: [التثبيت والتحديثات](/ar/install/updating). - - أي Linux VPS سيعمل. ثبّته على الخادم، ثم استخدم SSH/Tailscale للوصول إلى Gateway. + + أي Linux VPS يعمل. ثبّت على الخادم، ثم استخدم SSH/Tailscale للوصول إلى Gateway. الأدلة: [exe.dev](/ar/install/exe-dev)، [Hetzner](/ar/install/hetzner)، [Fly.io](/ar/install/fly). - الوصول البعيد: [Gateway remote](/ar/gateway/remote). + الوصول البعيد: [Gateway البعيد](/ar/gateway/remote). - نحتفظ **بمحور استضافة** يضم الموفرين الشائعين. اختر واحدًا واتبع الدليل: + نحتفظ **بمركز استضافة** يضم المزوّدين الشائعين. اختر واحدًا واتبع الدليل: - - [استضافة VPS](/ar/vps) (كل الموفرين في مكان واحد) + - [استضافة VPS](/ar/vps) (كل المزوّدين في مكان واحد) - [Fly.io](/ar/install/fly) - [Hetzner](/ar/install/hetzner) - [exe.dev](/ar/install/exe-dev) - كيف يعمل ذلك في السحابة: **Gateway تعمل على الخادم**، وأنت تصل إليها - من حاسوبك المحمول/هاتفك عبر Control UI (أو Tailscale/SSH). وتوجد حالتك + مساحة العمل - على الخادم، لذا عامل المضيف بوصفه المصدر الأساسي للحقيقة وخذ له نسخًا احتياطية. + كيف يعمل هذا في السحابة: **Gateway يعمل على الخادم**، وتصل إليه + من حاسوبك المحمول/هاتفك عبر Control UI (أو Tailscale/SSH). تعيش حالتك + مساحة العمل + على الخادم، لذا اعتبر المضيف مصدر الحقيقة وقم بنسخه احتياطيًا. - يمكنك إقران **nodes** ‏(Mac/iOS/Android/headless) مع تلك Gateway السحابية للوصول إلى - الشاشة/الكاميرا/Canvas محليًا أو تشغيل أوامر على حاسوبك المحمول مع إبقاء + يمكنك إقران **nodes** (Mac/iOS/Android/headless) مع Gateway السحابي هذا للوصول إلى + الشاشة/الكاميرا/الـ canvas المحلية أو تشغيل الأوامر على حاسوبك المحمول مع إبقاء Gateway في السحابة. - المحور: [المنصات](/ar/platforms). الوصول البعيد: [Gateway remote](/ar/gateway/remote). + المركز: [المنصات](/ar/platforms). الوصول البعيد: [Gateway البعيد](/ar/gateway/remote). Nodes: [Nodes](/ar/nodes)، [CLI الخاص بـ Nodes](/cli/nodes). - الإجابة المختصرة: **ممكن، لكنه غير موصى به**. قد تعيد عملية التحديث تشغيل - Gateway (ما يؤدي إلى إسقاط الجلسة النشطة)، وقد تحتاج إلى نسخة git نظيفة، - وقد تطلب تأكيدًا. والأكثر أمانًا: تشغيل التحديثات من طرفية بصفتك المشغّل. + الإجابة المختصرة: **ممكن، لكنه غير موصى به**. يمكن لتدفق التحديث أن يعيد تشغيل + Gateway (ما يؤدي إلى قطع الجلسة النشطة)، وقد يحتاج إلى نسخة git نظيفة، وقد + يطلب تأكيدًا. الأكثر أمانًا: شغّل التحديثات من shell بصفتك المشغّل. استخدم CLI: @@ -557,230 +558,230 @@ x-i18n: openclaw update --no-restart ``` - إذا كان لا بد من أتمتته من وكيل: + إذا كان لا بد من الأتمتة من agent: ```bash openclaw update --yes --no-restart openclaw gateway restart ``` - الوثائق: [التحديث](/cli/update)، [التحديث](/ar/install/updating). + المستندات: [التحديث](/cli/update)، [التحديث](/ar/install/updating). - - يعد `openclaw onboard` مسار الإعداد الموصى به. في **الوضع المحلي** يرشدك خلال: + + `openclaw onboard` هو مسار الإعداد الموصى به. في **الوضع المحلي** يرشدك خلال: - - **إعداد النموذج/المصادقة** (OAuth للموفر، وAPI keys، وAnthropic setup-token، بالإضافة إلى خيارات النماذج المحلية مثل LM Studio) - - موقع **مساحة العمل** + ملفات bootstrap - - **إعدادات Gateway** ‏(bind/port/auth/tailscale) - - **Channels** ‏(WhatsApp، Telegram، Discord، Mattermost، Signal، iMessage، بالإضافة إلى channel plugins المجمعة مثل QQ Bot) - - **تثبيت daemon** ‏(LaunchAgent على macOS؛ ووحدة مستخدم systemd على Linux/WSL2) + - **إعداد النموذج/المصادقة** (OAuth للمزوّد، مفاتيح API، Anthropic setup-token، إضافةً إلى خيارات النماذج المحلية مثل LM Studio) + - موقع **Workspace** + ملفات bootstrap + - **إعدادات Gateway** (bind/port/auth/tailscale) + - **القنوات** (WhatsApp وTelegram وDiscord وMattermost وSignal وiMessage، إضافةً إلى channel plugins المضمّنة مثل QQ Bot) + - **تثبيت daemon** (LaunchAgent على macOS؛ ووحدة systemd للمستخدم على Linux/WSL2) - **فحوصات الصحة** واختيار **Skills** - كما يحذرك إذا كان النموذج المهيأ غير معروف أو تنقصه المصادقة. + كما يحذّر إذا كان النموذج الذي قمت بتكوينه غير معروف أو يفتقد إلى المصادقة. - لا. يمكنك تشغيل OpenClaw باستخدام **API keys** ‏(Anthropic/OpenAI/غيرهما) أو باستخدام - **نماذج محلية فقط** بحيث تبقى بياناتك على جهازك. والاشتراكات (Claude - Pro/Max أو OpenAI Codex) هي طرق اختيارية لمصادقة هؤلاء الموفّرين. + لا. يمكنك تشغيل OpenClaw باستخدام **مفاتيح API** (Anthropic/OpenAI/وغيرهما) أو باستخدام + **نماذج محلية فقط** بحيث تبقى بياناتك على جهازك. الاشتراكات (Claude + Pro/Max أو OpenAI Codex) هي طرق اختيارية للمصادقة مع هؤلاء المزوّدين. بالنسبة إلى Anthropic في OpenClaw، فالتقسيم العملي هو: - - **Anthropic API key**: فوترة Anthropic API العادية - - **Claude CLI / مصادقة اشتراك Claude في OpenClaw**: أخبرنا موظفو Anthropic - بأن هذا الاستخدام مسموح به مجددًا، ويتعامل OpenClaw مع استخدام `claude -p` - على أنه معتمد لهذا التكامل ما لم تنشر Anthropic سياسة جديدة + - **Anthropic API key**: فوترة عادية عبر Anthropic API + - **Claude CLI / Claude subscription auth في OpenClaw**: أخبرنا موظفو Anthropic + أن هذا الاستخدام مسموح به مجددًا، ويتعامل OpenClaw مع استخدام `claude -p` + على أنه معتمد لهذا التكامل ما لم تنشر Anthropic + سياسة جديدة - بالنسبة إلى مضيفي gateway طويلة العمر، تظل Anthropic API keys هي + بالنسبة إلى مضيفي gateway طويلة الأمد، تظل مفاتيح Anthropic API الإعداد الأكثر قابلية للتنبؤ. كما أن OpenAI Codex OAuth مدعوم صراحةً للأدوات الخارجية مثل OpenClaw. - كما يدعم OpenClaw خيارات أخرى مستضافة على نمط الاشتراك، بما في ذلك - **Qwen Cloud Coding Plan**، و**MiniMax Coding Plan**، و + يدعم OpenClaw أيضًا خيارات اشتراك مستضافة أخرى، منها + **Qwen Cloud Coding Plan** و**MiniMax Coding Plan** و **Z.AI / GLM Coding Plan**. - الوثائق: [Anthropic](/ar/providers/anthropic)، [OpenAI](/ar/providers/openai)، + المستندات: [Anthropic](/ar/providers/anthropic)، [OpenAI](/ar/providers/openai)، [Qwen Cloud](/ar/providers/qwen)، - [MiniMax](/ar/providers/minimax)، [GLM Models](/ar/providers/glm)، + [MiniMax](/ar/providers/minimax)، [نماذج GLM](/ar/providers/glm)، [النماذج المحلية](/ar/gateway/local-models)، [النماذج](/ar/concepts/models). - + نعم. - أخبرنا موظفو Anthropic أن استخدام Claude CLI بأسلوب OpenClaw مسموح به مجددًا، لذا + أخبرنا موظفو Anthropic أن استخدام Claude CLI بنمط OpenClaw مسموح به مجددًا، لذا يتعامل OpenClaw مع مصادقة اشتراك Claude واستخدام `claude -p` على أنهما معتمدان لهذا التكامل ما لم تنشر Anthropic سياسة جديدة. وإذا أردت - إعدادًا أكثر قابلية للتنبؤ على جانب الخادم، فاستخدم Anthropic API key بدلًا من ذلك. + أكثر إعداد جانب خادم قابلية للتنبؤ، فاستخدم مفتاح Anthropic API بدلًا من ذلك. نعم. - أخبرنا موظفو Anthropic أن هذا الاستخدام مسموح به مجددًا، لذلك يتعامل OpenClaw مع + أخبرنا موظفو Anthropic أن هذا الاستخدام مسموح به مجددًا، لذا يتعامل OpenClaw مع إعادة استخدام Claude CLI واستخدام `claude -p` على أنهما معتمدان لهذا التكامل ما لم تنشر Anthropic سياسة جديدة. - لا يزال Anthropic setup-token متاحًا كمسار رمز مميز مدعوم في OpenClaw، لكن OpenClaw يفضّل الآن إعادة استخدام Claude CLI واستخدام `claude -p` عند توفرهما. - وبالنسبة إلى أحمال العمل الإنتاجية أو متعددة المستخدمين، تظل مصادقة Anthropic API key - الخيار الأكثر أمانًا وقابلية للتنبؤ. وإذا أردت خيارات مستضافة أخرى - على نمط الاشتراك داخل OpenClaw، فراجع [OpenAI](/ar/providers/openai)، و[Qwen / Model - Cloud](/ar/providers/qwen)، و[MiniMax](/ar/providers/minimax)، و[GLM - Models](/ar/providers/glm). + لا يزال Anthropic setup-token متاحًا كمسار token مدعوم في OpenClaw، لكن OpenClaw يفضّل الآن إعادة استخدام Claude CLI و`claude -p` عند توفرهما. + أما لأحمال الإنتاج أو متعددة المستخدمين، فلا تزال مصادقة مفتاح Anthropic API + الخيار الأكثر أمانًا وقابلية للتنبؤ. وإذا كنت تريد خيارات مستضافة + أخرى بنمط الاشتراك داخل OpenClaw، فراجع [OpenAI](/ar/providers/openai)، [Qwen / Model + Cloud](/ar/providers/qwen)، [MiniMax](/ar/providers/minimax)، و[نماذج GLM](/ar/providers/glm). -هذا يعني أن **حصة/حد المعدل لدى Anthropic** قد استُنفدت في النافذة الحالية. إذا كنت -تستخدم **Claude CLI**، فانتظر حتى تُعاد تهيئة النافذة أو قم بترقية خطتك. وإذا كنت +هذا يعني أن **حصة/حد المعدل لدى Anthropic** قد استُنفدت للفترة الحالية. إذا كنت +تستخدم **Claude CLI**، فانتظر حتى تُعاد تهيئة الفترة أو قم بترقية خطتك. وإذا كنت تستخدم **Anthropic API key**، فتحقق من Anthropic Console -من الاستخدام/الفوترة وارفع الحدود عند الحاجة. +بالنسبة للاستخدام/الفوترة وارفع الحدود عند الحاجة. إذا كانت الرسالة تحديدًا: `Extra usage is required for long context requests`، فهذا يعني أن الطلب يحاول استخدام - إصدار Anthropic التجريبي لسياق 1M (`context1m: true`). وهذا لا يعمل إلا عندما تكون - بيانات اعتمادك مؤهلة لفوترة السياق الطويل (فوترة API key أو - مسار تسجيل دخول Claude في OpenClaw مع تفعيل Extra Usage). + النسخة التجريبية لسياق 1M لدى Anthropic (`context1m: true`). وهذا لا يعمل إلا عندما تكون + بيانات الاعتماد لديك مؤهلة لفوترة السياق الطويل (فوترة عبر API key أو + مسار Claude-login في OpenClaw مع تفعيل Extra Usage). - نصيحة: اضبط **نموذجًا احتياطيًا** حتى يتمكن OpenClaw من الاستمرار في الرد بينما يكون أحد الموفّرين مقيدًا بالمعدل. - راجع [النماذج](/cli/models)، و[OAuth](/ar/concepts/oauth)، و + نصيحة: اضبط **نموذجًا احتياطيًا** حتى يتمكن OpenClaw من الاستمرار في الرد أثناء تقييد مزوّد ما بالمعدل. + راجع [النماذج](/cli/models)، [OAuth](/ar/concepts/oauth)، و [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/ar/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context). - نعم. يحتوي OpenClaw على موفر مجمّع **Amazon Bedrock (Converse)**. وعند وجود علامات بيئة AWS، يستطيع OpenClaw اكتشاف فهرس Bedrock للبث/النص تلقائيًا ودمجه كموفر ضمني باسم `amazon-bedrock`؛ وإلا يمكنك تفعيل `plugins.entries.amazon-bedrock.config.discovery.enabled` صراحةً أو إضافة إدخال موفر يدويًا. راجع [Amazon Bedrock](/ar/providers/bedrock) و[موفرو النماذج](/ar/providers/models). وإذا كنت تفضّل مسار مفاتيح مُدارًا، فسيظل وجود موجه متوافق مع OpenAI أمام Bedrock خيارًا صالحًا. + نعم. يحتوي OpenClaw على مزوّد **Amazon Bedrock (Converse)** مضمّن. عند وجود محددات AWS env، يستطيع OpenClaw اكتشاف كتالوج Bedrock النصي/المتدفق ودمجه كمزوّد ضمني `amazon-bedrock`؛ وإلا يمكنك تفعيل `plugins.entries.amazon-bedrock.config.discovery.enabled` صراحةً أو إضافة إدخال مزوّد يدوي. راجع [Amazon Bedrock](/ar/providers/bedrock) و[مزودو النماذج](/ar/providers/models). وإذا كنت تفضّل تدفق مفاتيح مُدارًا، فما يزال الوكيل المتوافق مع OpenAI أمام Bedrock خيارًا صالحًا. - يدعم OpenClaw **OpenAI Code (Codex)** عبر OAuth (تسجيل دخول ChatGPT). ويمكن للتهيئة الأولية تشغيل تدفق OAuth وستضبط النموذج الافتراضي إلى `openai-codex/gpt-5.4` عند الاقتضاء. راجع [موفرو النماذج](/ar/concepts/model-providers) و[التهيئة الأولية (CLI)](/ar/start/wizard). + يدعم OpenClaw **OpenAI Code (Codex)** عبر OAuth (تسجيل الدخول عبر ChatGPT). يمكن للإدخال الأولي تشغيل تدفق OAuth وسيضبط النموذج الافتراضي على `openai-codex/gpt-5.4` عندما يكون ذلك مناسبًا. راجع [مزودو النماذج](/ar/concepts/model-providers) و[الإدخال الأولي (CLI)](/ar/start/wizard). - + يتعامل OpenClaw مع المسارين بشكل منفصل: - - `openai-codex/gpt-5.4` = OAuth الخاص بـ ChatGPT/Codex - - `openai/gpt-5.4` = OpenAI Platform API مباشر + - `openai-codex/gpt-5.4` = ChatGPT/Codex OAuth + - `openai/gpt-5.4` = OpenAI Platform API مباشرةً - في OpenClaw، يتم توصيل تسجيل دخول ChatGPT/Codex بمسار `openai-codex/*`، - وليس بمسار `openai/*` المباشر. وإذا أردت مسار API المباشر في - OpenClaw، فاضبط `OPENAI_API_KEY` (أو إعداد موفر OpenAI المكافئ). - وإذا أردت تسجيل دخول ChatGPT/Codex داخل OpenClaw، فاستخدم `openai-codex/*`. + في OpenClaw، يتم توصيل تسجيل الدخول عبر ChatGPT/Codex إلى مسار `openai-codex/*`, + وليس إلى المسار المباشر `openai/*`. إذا كنت تريد المسار المباشر عبر API في + OpenClaw، فاضبط `OPENAI_API_KEY` (أو إعدادات مزوّد OpenAI المكافئة). + وإذا كنت تريد تسجيل الدخول عبر ChatGPT/Codex في OpenClaw، فاستخدم `openai-codex/*`. - - يستخدم `openai-codex/*` مسار Codex OAuth، وتدير OpenAI نوافذ الحصة القابلة للاستخدام فيه - وتعتمد على الخطة. وعمليًا، قد تختلف هذه الحدود عن - تجربة موقع/تطبيق ChatGPT، حتى عندما يكون كلاهما مرتبطًا بالحساب نفسه. + + يستخدم `openai-codex/*` مسار Codex OAuth، ونوافذ الحصص القابلة للاستخدام فيه + تُدار من OpenAI وتعتمد على الخطة. عمليًا، قد تختلف هذه الحدود عن + تجربة موقع/تطبيق ChatGPT، حتى عندما يكون الاثنان مرتبطين بالحساب نفسه. - يمكن لـ OpenClaw عرض نوافذ الاستخدام/الحصة المرئية حاليًا لدى الموفر في - `openclaw models status`، لكنه لا يخترع أو يطبّع استحقاقات ChatGPT-web - إلى وصول مباشر إلى API. وإذا أردت مسار الفوترة/الحدود المباشر في OpenAI Platform، - فاستخدم `openai/*` مع API key. + يمكن لـ OpenClaw عرض نوافذ الاستخدام/الحصة المرئية حاليًا لدى المزوّد في + `openclaw models status`، لكنه لا يخترع ولا يوحّد استحقاقات ChatGPT على الويب + ضمن الوصول المباشر إلى API. إذا كنت تريد مسار الفوترة/الحدود المباشر عبر OpenAI Platform، + فاستخدم `openai/*` مع مفتاح API. - نعم. يدعم OpenClaw بالكامل **OAuth اشتراك OpenAI Code (Codex)**. - وتسمح OpenAI صراحةً باستخدام OAuth للاشتراك في الأدوات/سير العمل - الخارجية مثل OpenClaw. ويمكن للتهيئة الأولية تشغيل تدفق OAuth بالنيابة عنك. + نعم. يدعم OpenClaw بالكامل **OpenAI Code (Codex) subscription OAuth**. + تسمح OpenAI صراحةً باستخدام subscription OAuth في الأدوات/سير العمل الخارجية + مثل OpenClaw. ويمكن للإدخال الأولي تشغيل تدفق OAuth نيابةً عنك. - راجع [OAuth](/ar/concepts/oauth)، و[موفرو النماذج](/ar/concepts/model-providers)، و[التهيئة الأولية (CLI)](/ar/start/wizard). + راجع [OAuth](/ar/concepts/oauth)، [مزودو النماذج](/ar/concepts/model-providers)، و[الإدخال الأولي (CLI)](/ar/start/wizard). - + يستخدم Gemini CLI **تدفق مصادقة plugin**، وليس client id أو secret في `openclaw.json`. الخطوات: - 1. ثبّت Gemini CLI محليًا بحيث يكون `gemini` على `PATH` + 1. ثبّت Gemini CLI محليًا بحيث يكون `gemini` موجودًا على `PATH` - Homebrew: `brew install gemini-cli` - npm: `npm install -g @google/gemini-cli` 2. فعّل plugin: `openclaw plugins enable google` 3. سجّل الدخول: `openclaw models auth login --provider google-gemini-cli --set-default` - 4. النموذج الافتراضي بعد تسجيل الدخول: `google-gemini-cli/gemini-3.1-pro-preview` + 4. النموذج الافتراضي بعد تسجيل الدخول: `google-gemini-cli/gemini-3-flash-preview` 5. إذا فشلت الطلبات، فاضبط `GOOGLE_CLOUD_PROJECT` أو `GOOGLE_CLOUD_PROJECT_ID` على مضيف gateway - يؤدي هذا إلى تخزين OAuth tokens في ملفات تعريف المصادقة على مضيف gateway. التفاصيل: [موفرو النماذج](/ar/concepts/model-providers). + يخزن هذا رموز OAuth في ملفات تعريف المصادقة على مضيف gateway. التفاصيل: [مزودو النماذج](/ar/concepts/model-providers). - عادةً لا. يحتاج OpenClaw إلى سياق كبير + أمان قوي؛ والبطاقات الصغيرة تقطع السياق وتسرّبه. وإذا كان لا بد، فشغّل **أكبر** بناء نموذج تستطيع تشغيله محليًا (LM Studio) وراجع [/gateway/local-models](/ar/gateway/local-models). فالنماذج الأصغر/المكمّاة تزيد خطر prompt-injection - راجع [الأمان](/ar/gateway/security). + غالبًا لا. يحتاج OpenClaw إلى سياق كبير + أمان قوي؛ البطاقات الصغيرة تقطع السياق وتسرّب. وإذا اضطررت، فشغّل **أكبر** بنية نموذج يمكنك تشغيلها محليًا (LM Studio) وراجع [/gateway/local-models](/ar/gateway/local-models). النماذج الأصغر/الأكثر كمّية تزيد من خطر prompt injection - راجع [الأمان](/ar/gateway/security). - - اختر نقاط نهاية مثبتة على منطقة معينة. يوفّر OpenRouter خيارات مستضافة في الولايات المتحدة لكل من MiniMax وKimi وGLM؛ اختر النسخة المستضافة في الولايات المتحدة للإبقاء على البيانات ضمن المنطقة. ولا يزال بإمكانك إدراج Anthropic/OpenAI إلى جانب هذه الخيارات باستخدام `models.mode: "merge"` حتى تبقى النماذج الاحتياطية متاحة مع احترام الموفر الإقليمي الذي تختاره. + + اختر نقاط نهاية مثبّتة على المنطقة. يوفّر OpenRouter خيارات مستضافة في الولايات المتحدة لـ MiniMax وKimi وGLM؛ اختر المتغير المستضاف في الولايات المتحدة لإبقاء البيانات داخل المنطقة. ولا يزال بإمكانك إدراج Anthropic/OpenAI إلى جانب هذه الخيارات باستخدام `models.mode: "merge"` بحيث تبقى النماذج الاحتياطية متاحة مع احترام المزوّد الإقليمي الذي تختاره. - لا. يعمل OpenClaw على macOS أو Linux (وعلى Windows عبر WSL2). وMac mini اختياري - - فبعض الأشخاص يشترونه كمضيف دائم التشغيل، لكن VPS صغيرًا أو خادمًا منزليًا أو جهازًا من فئة Raspberry Pi يصلح أيضًا. + لا. يعمل OpenClaw على macOS أو Linux (وWindows عبر WSL2). إن Mac mini اختياري - + فبعض الأشخاص يشترونه كمضيف يعمل دائمًا، لكن VPS صغيرًا أو خادمًا منزليًا أو جهازًا من فئة Raspberry Pi يعمل أيضًا. - أنت تحتاج إلى Mac **فقط للأدوات الخاصة بـ macOS فقط**. وبالنسبة إلى iMessage، استخدم [BlueBubbles](/ar/channels/bluebubbles) (موصى به) - يعمل خادم BlueBubbles على أي Mac، ويمكن أن تعمل Gateway على Linux أو في مكان آخر. وإذا أردت أدوات أخرى خاصة بـ macOS فقط، فشغّل Gateway على جهاز Mac أو أقرِن macOS node. + أنت تحتاج إلى Mac فقط **لأدوات macOS فقط**. بالنسبة إلى iMessage، استخدم [BlueBubbles](/ar/channels/bluebubbles) (موصى به) - يعمل خادم BlueBubbles على أي جهاز Mac، بينما يمكن لـ Gateway أن يعمل على Linux أو في مكان آخر. وإذا كنت تريد أدوات أخرى خاصة بـ macOS فقط، فشغّل Gateway على Mac أو اقترن بعقدة macOS. - الوثائق: [BlueBubbles](/ar/channels/bluebubbles)، [Nodes](/ar/nodes)، [الوضع البعيد على Mac](/ar/platforms/mac/remote). + المستندات: [BlueBubbles](/ar/channels/bluebubbles)، [Nodes](/ar/nodes)، [الوضع البعيد على Mac](/ar/platforms/mac/remote). - أنت بحاجة إلى **أي جهاز macOS** مسجّل الدخول إلى Messages. ولا **يجب** أن يكون Mac mini - - أي جهاز Mac يكفي. **استخدم [BlueBubbles](/ar/channels/bluebubbles)** (موصى به) لـ iMessage - يعمل خادم BlueBubbles على macOS، بينما يمكن أن تعمل Gateway على Linux أو في مكان آخر. + أنت تحتاج إلى **أي جهاز macOS** مسجّل الدخول إلى Messages. ولا **يشترط** أن يكون Mac mini - + أي جهاز Mac يعمل. **استخدم [BlueBubbles](/ar/channels/bluebubbles)** (موصى به) بالنسبة إلى iMessage - يعمل خادم BlueBubbles على macOS، بينما يمكن لـ Gateway أن يعمل على Linux أو في مكان آخر. إعدادات شائعة: - - شغّل Gateway على Linux/VPS، وشغّل خادم BlueBubbles على أي Mac مسجل الدخول إلى Messages. - - شغّل كل شيء على جهاز Mac إذا كنت تريد أبسط إعداد على جهاز واحد. + - شغّل Gateway على Linux/VPS، وشغّل خادم BlueBubbles على أي جهاز Mac مسجّل الدخول إلى Messages. + - شغّل كل شيء على جهاز Mac إذا أردت أبسط إعداد على جهاز واحد. - الوثائق: [BlueBubbles](/ar/channels/bluebubbles)، [Nodes](/ar/nodes)، + المستندات: [BlueBubbles](/ar/channels/bluebubbles)، [Nodes](/ar/nodes)، [الوضع البعيد على Mac](/ar/platforms/mac/remote). - - نعم. يمكن لـ **Mac mini تشغيل Gateway**، ويمكن لـ MacBook Pro الاتصال به - بوصفه **node** ‏(جهازًا مرافقًا). لا تشغّل Nodes الـ Gateway - بل توفر - قدرات إضافية مثل الشاشة/الكاميرا/Canvas و`system.run` على ذلك الجهاز. + + نعم. يمكن لـ **Mac mini أن يشغّل Gateway**، ويمكن لـ MacBook Pro أن يتصل كـ + **node** (جهاز مرافق). لا تشغّل Nodes الـ Gateway - بل توفر + قدرات إضافية مثل screen/camera/canvas و`system.run` على ذلك الجهاز. - نمط شائع: + النمط الشائع: - - Gateway على Mac mini (دائم التشغيل). - - يشغّل MacBook Pro تطبيق macOS أو مضيف node ويُقترن مع Gateway. - - استخدم `openclaw nodes status` / `openclaw nodes list` لرؤيته. + - Gateway على Mac mini (يعمل دائمًا). + - يشغّل MacBook Pro تطبيق macOS أو مضيف node ويقترن بالـ Gateway. + - استخدم `openclaw nodes status` / `openclaw nodes list` لمشاهدته. - الوثائق: [Nodes](/ar/nodes)، [CLI الخاص بـ Nodes](/cli/nodes). + المستندات: [Nodes](/ar/nodes)، [CLI الخاص بـ Nodes](/cli/nodes). - **لا يُنصح** بـ Bun. فنحن نرى أخطاء وقت تشغيل، خاصة مع WhatsApp وTelegram. - استخدم **Node** للحصول على بوابات مستقرة. + لا يُنصح باستخدام Bun. نرى أخطاء وقت تشغيل، خاصةً مع WhatsApp وTelegram. + استخدم **Node** من أجل gateways مستقرة. - وإذا كنت لا تزال تريد التجربة باستخدام Bun، فافعل ذلك على Gateway غير إنتاجية - من دون WhatsApp/Telegram. + إذا كنت لا تزال تريد التجريب باستخدام Bun، فافعل ذلك على gateway غير إنتاجية + ومن دون WhatsApp/Telegram. - - القيمة `channels.telegram.allowFrom` هي **معرّف مستخدم Telegram البشري المرسِل** (رقمي). وليست اسم مستخدم البوت. + + `channels.telegram.allowFrom` هو **معرّف مستخدم Telegram للمرسل البشري** (رقمي). وليس اسم مستخدم bot. - تقبل التهيئة الأولية إدخال `@username` وتحله إلى معرّف رقمي، لكن تفويض OpenClaw يستخدم المعرفات الرقمية فقط. + يقبل الإدخال الأولي إدخال `@username` ويحوّله إلى معرّف رقمي، لكن تفويض OpenClaw يستخدم المعرفات الرقمية فقط. - الطريقة الأكثر أمانًا (من دون بوت خارجي): + الطريقة الأكثر أمانًا (من دون bot طرف ثالث): - - أرسل رسالة خاصة إلى البوت، ثم شغّل `openclaw logs --follow` واقرأ `from.id`. + - أرسل رسالة خاصة إلى bot لديك، ثم شغّل `openclaw logs --follow` واقرأ `from.id`. Bot API الرسمي: - - أرسل رسالة خاصة إلى البوت، ثم اطلب `https://api.telegram.org/bot/getUpdates` واقرأ `message.from.id`. + - أرسل رسالة خاصة إلى bot لديك، ثم استدعِ `https://api.telegram.org/bot/getUpdates` واقرأ `message.from.id`. طرف ثالث (أقل خصوصية): @@ -791,15 +792,15 @@ x-i18n: - نعم، عبر **التوجيه متعدد الوكلاء**. اربط WhatsApp **DM** لكل مرسل (peer من النوع `kind: "direct"`، مع sender E.164 مثل `+15551234567`) بمعرّف `agentId` مختلف، حتى يحصل كل شخص على مساحة العمل الخاصة به ومخزن الجلسات الخاص به. وستظل الردود تصدر من **حساب WhatsApp نفسه**، ويظل التحكم في الوصول إلى DM (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) عامًا لكل حساب WhatsApp. راجع [التوجيه متعدد الوكلاء](/ar/concepts/multi-agent) و[WhatsApp](/ar/channels/whatsapp). + نعم، عبر **التوجيه متعدد الوكلاء**. اربط **DM** الخاصة بكل مُرسِل في WhatsApp (القرين `kind: "direct"`، والمرسل بصيغة E.164 مثل `+15551234567`) بـ `agentId` مختلف، حتى يحصل كل شخص على مساحة عمله ومخزن جلساته الخاصين. وستظل الردود تصدر من **حساب WhatsApp نفسه**، كما أن التحكم في الوصول إلى DM (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) يكون عامًا لكل حساب WhatsApp. راجع [التوجيه متعدد الوكلاء](/ar/concepts/multi-agent) و[WhatsApp](/ar/channels/whatsapp). - نعم. استخدم التوجيه متعدد الوكلاء: أعطِ كل وكيل نموذجه الافتراضي الخاص، ثم اربط المسارات الواردة (حساب الموفر أو peers محددين) بكل وكيل. يوجد مثال للإعداد في [التوجيه متعدد الوكلاء](/ar/concepts/multi-agent). راجع أيضًا [النماذج](/ar/concepts/models) و[الإعداد](/ar/gateway/configuration). + نعم. استخدم التوجيه متعدد الوكلاء: امنح كل وكيل نموذجه الافتراضي الخاص، ثم اربط المسارات الواردة (حساب المزوّد أو الأقران المحددون) بكل وكيل. يوجد مثال للإعدادات في [التوجيه متعدد الوكلاء](/ar/concepts/multi-agent). راجع أيضًا [النماذج](/ar/concepts/models) و[التكوين](/ar/gateway/configuration). - نعم. يدعم Homebrew نظام Linux ‏(Linuxbrew). إعداد سريع: + نعم. يدعم Homebrew نظام Linux (Linuxbrew). إعداد سريع: ```bash /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" @@ -808,25 +809,25 @@ x-i18n: brew install ``` - إذا كنت تشغّل OpenClaw عبر systemd، فتأكد من أن PATH في الخدمة يتضمن `/home/linuxbrew/.linuxbrew/bin` (أو البادئة الخاصة بك في brew) حتى تُحل الأدوات المثبتة عبر `brew` داخل non-login shells. - كما أن الإصدارات الحديثة تضيف مسبقًا أدلة user bin الشائعة إلى خدمات Linux systemd (مثل `~/.local/bin`، و`~/.npm-global/bin`، و`~/.local/share/pnpm`، و`~/.bun/bin`) وتحترم `PNPM_HOME` و`NPM_CONFIG_PREFIX` و`BUN_INSTALL` و`VOLTA_HOME` و`ASDF_DATA_DIR` و`NVM_DIR` و`FNM_DIR` عند ضبطها. + إذا كنت تشغّل OpenClaw عبر systemd، فتأكد من أن PATH الخاص بالخدمة يتضمن `/home/linuxbrew/.linuxbrew/bin` (أو بادئة brew لديك) بحيث يتم العثور على الأدوات المثبتة عبر `brew` في shell غير تسجيل الدخول. + كما أن الإصدارات الحديثة تسبق أيضًا أدلة المستخدم الشائعة bin على خدمات Linux systemd (مثل `~/.local/bin` و`~/.npm-global/bin` و`~/.local/share/pnpm` و`~/.bun/bin`) وتحترم `PNPM_HOME` و`NPM_CONFIG_PREFIX` و`BUN_INSTALL` و`VOLTA_HOME` و`ASDF_DATA_DIR` و`NVM_DIR` و`FNM_DIR` عندما تكون مضبوطة. - - - **التثبيت القابل للاختراق (git):** نسخة مصدر كاملة، قابلة للتعديل، والأفضل للمساهمين. - تقوم بتشغيل عمليات البناء محليًا ويمكنك ترقيع الشيفرة/الوثائق. - - **npm install:** تثبيت CLI عام، من دون مستودع، والأفضل لمن يريد "تشغيله فقط". + + - **تثبيت git القابل للاختراق:** نسخة مصدر كاملة، قابلة للتعديل، والأفضل للمساهمين. + أنت تشغّل البناء محليًا ويمكنك ترقيع الشيفرة/المستندات. + - **npm install:** تثبيت CLI عام، بدون مستودع، والأفضل لمن يريد "تشغيله فقط." تأتي التحديثات من npm dist-tags. - الوثائق: [البدء](/ar/start/getting-started)، [التحديث](/ar/install/updating). + المستندات: [البدء](/ar/start/getting-started)، [التحديث](/ar/install/updating). - - نعم. ثبّت النوع الآخر، ثم شغّل Doctor حتى تشير خدمة gateway إلى نقطة الدخول الجديدة. - هذا **لا يحذف بياناتك** - بل يغير فقط تثبيت شيفرة OpenClaw. وستظل الحالة - (`~/.openclaw`) ومساحة العمل (`~/.openclaw/workspace`) من دون مساس. + + نعم. ثبّت النكهة الأخرى، ثم شغّل Doctor بحيث تشير خدمة gateway إلى نقطة الدخول الجديدة. + هذا **لا يحذف بياناتك** - بل يغيّر فقط تثبيت شيفرة OpenClaw. تبقى حالتك + (`~/.openclaw`) ومساحة عملك (`~/.openclaw/workspace`) كما هما. من npm إلى git: @@ -847,66 +848,66 @@ x-i18n: openclaw gateway restart ``` - يكتشف Doctor عدم تطابق نقطة دخول خدمة gateway ويعرض إعادة كتابة إعداد الخدمة ليتوافق مع التثبيت الحالي (استخدم `--repair` في الأتمتة). + يكتشف Doctor عدم تطابق نقطة دخول خدمة gateway ويعرض إعادة كتابة إعدادات الخدمة لتطابق التثبيت الحالي (استخدم `--repair` في الأتمتة). - نصائح النسخ الاحتياطي: راجع [استراتيجية النسخ الاحتياطي](#where-things-live-on-disk). + نصائح النسخ الاحتياطي: راجع [استراتيجية النسخ الاحتياطي](#مكان-وجود-الأشياء-على-القرص). - الإجابة المختصرة: **إذا أردت موثوقية 24/7 فاستخدم VPS**. وإذا أردت - أقل قدر من الاحتكاك وكنت متقبلًا للنوم/إعادة التشغيل، فشغّلها محليًا. + الإجابة المختصرة: **إذا كنت تريد موثوقية 24/7، فاستخدم VPS**. وإذا كنت تريد + أقل احتكاك ولا تمانع السكون/إعادة التشغيل، فشغّله محليًا. - **الحاسوب المحمول (Gateway محلية)** + **الحاسوب المحمول (Gateway محلي)** - **الإيجابيات:** لا تكلفة خادم، وصول مباشر إلى الملفات المحلية، نافذة متصفح مرئية. - - **السلبيات:** النوم/انقطاع الشبكة = انقطاعات، تحديثات/إعادات تشغيل النظام تقطع العمل، ويجب أن يبقى الجهاز مستيقظًا. + - **السلبيات:** السكون/انقطاع الشبكة = انقطاعات، تحديثات/إعادات تشغيل النظام تقطع العمل، ويجب أن يبقى الجهاز مستيقظًا. **VPS / السحابة** - - **الإيجابيات:** دائم التشغيل، شبكة مستقرة، لا توجد مشكلات نوم الحاسوب المحمول، أسهل في إبقائه قيد التشغيل. - - **السلبيات:** غالبًا يعمل من دون واجهة (استخدم لقطات الشاشة)، وصول بعيد إلى الملفات فقط، ويجب عليك استخدام SSH للتحديثات. + - **الإيجابيات:** يعمل دائمًا، شبكة مستقرة، لا توجد مشكلات سكون الحاسوب المحمول، وأسهل في إبقائه قيد التشغيل. + - **السلبيات:** غالبًا يعمل headless (استخدم لقطات الشاشة)، وصول بعيد إلى الملفات فقط، ويجب عليك استخدام SSH للتحديثات. - **ملاحظة خاصة بـ OpenClaw:** تعمل WhatsApp/Telegram/Slack/Mattermost/Discord جيدًا من VPS. والمفاضلة الحقيقية الوحيدة هي **متصفح headless** مقابل نافذة مرئية. راجع [المتصفح](/ar/tools/browser). + **ملاحظة خاصة بـ OpenClaw:** تعمل WhatsApp/Telegram/Slack/Mattermost/Discord جميعها جيدًا من VPS. والمفاضلة الحقيقية الوحيدة هي **المتصفح headless** مقابل النافذة المرئية. راجع [المتصفح](/ar/tools/browser). - **الافتراضي الموصى به:** VPS إذا سبق أن واجهت انقطاعات في gateway. أما الوضع المحلي فهو ممتاز عندما تستخدم جهاز Mac بنشاط وتريد وصولًا محليًا إلى الملفات أو أتمتة واجهة مستخدم مع متصفح مرئي. + **الافتراضي الموصى به:** VPS إذا سبق أن واجهت انقطاعات gateway. أما المحلي فممتاز عندما تستخدم جهاز Mac بنشاط وتريد وصولًا إلى الملفات المحلية أو أتمتة UI مع متصفح مرئي. - ليس مطلوبًا، لكنه **موصى به للموثوقية والعزل**. + ليس مطلوبًا، لكنه **موصى به من أجل الموثوقية والعزل**. - - **مضيف مخصص (VPS/Mac mini/Pi):** دائم التشغيل، انقطاعات أقل بسبب النوم/إعادة التشغيل، أذونات أنظف، أسهل في الإبقاء عليه قيد التشغيل. - - **حاسوب محمول/مكتبي مشترك:** جيد تمامًا للاختبار والاستخدام النشط، لكن توقّع توقفات عندما ينام الجهاز أو يُحدَّث. + - **مضيف مخصص (VPS/Mac mini/Pi):** يعمل دائمًا، انقطاعات أقل بسبب السكون/إعادة التشغيل، أذونات أنظف، وأسهل في إبقائه قيد التشغيل. + - **حاسوب محمول/مكتبي مشترك:** مناسب تمامًا للاختبار والاستخدام النشط، لكن توقّع توقفات عند سكون الجهاز أو تحديثه. - إذا أردت أفضل ما في العالمين، فأبقِ Gateway على مضيف مخصص وأقرِن حاسوبك المحمول بوصفه **node** لأدوات الشاشة/الكاميرا/exec المحلية. راجع [Nodes](/ar/nodes). + إذا كنت تريد أفضل ما في العالمين، فأبقِ Gateway على مضيف مخصص واقرن حاسوبك المحمول كـ **node** من أجل أدوات الشاشة/الكاميرا/exec المحلية. راجع [Nodes](/ar/nodes). ولإرشادات الأمان، اقرأ [الأمان](/ar/gateway/security). - OpenClaw خفيف الوزن. بالنسبة إلى Gateway أساسية + قناة دردشة واحدة: + OpenClaw خفيف. بالنسبة إلى Gateway أساسي + قناة دردشة واحدة: - - **الحد الأدنى المطلق:** ‏1 vCPU، و1GB RAM، ونحو 500MB من القرص. - - **الموصى به:** ‏1-2 vCPU، و2GB RAM أو أكثر لهامش إضافي (للسجلات، والوسائط، وتعدد القنوات). وقد تكون أدوات Node وأتمتة المتصفح شرهة للموارد. + - **الحد الأدنى المطلق:** 1 vCPU و1GB RAM وحوالي 500MB قرص. + - **الموصى به:** 1-2 vCPU و2GB RAM أو أكثر كهامش (للسجلات والوسائط والقنوات المتعددة). قد تكون أدوات Node وأتمتة المتصفح شرهة للموارد. - نظام التشغيل: استخدم **Ubuntu LTS** ‏(أو أي Debian/Ubuntu حديث). فهذا هو المسار الأكثر اختبارًا للتثبيت على Linux. + نظام التشغيل: استخدم **Ubuntu LTS** (أو أي Debian/Ubuntu حديث). فهذا هو مسار تثبيت Linux الأكثر اختبارًا. - الوثائق: [Linux](/ar/platforms/linux)، [استضافة VPS](/ar/vps). + المستندات: [Linux](/ar/platforms/linux)، [استضافة VPS](/ar/vps). - - نعم. تعامل مع VM بالطريقة نفسها التي تتعامل بها مع VPS: يجب أن تكون دائمًا قيد التشغيل، قابلة للوصول، وتملك - ذاكرة RAM كافية لـ Gateway وأي channels تقوم بتفعيلها. + + نعم. تعامل مع VM كما تتعامل مع VPS: يجب أن تكون قيد التشغيل دائمًا، ويمكن الوصول إليها، وبها ما يكفي من + الذاكرة لـ Gateway وأي قنوات تقوم بتمكينها. - إرشادات أساسية: + الإرشادات الأساسية: - - **الحد الأدنى المطلق:** ‏1 vCPU و1GB RAM. - - **الموصى به:** ‏2GB RAM أو أكثر إذا كنت تشغّل عدة channels، أو أتمتة متصفح، أو أدوات وسائط. + - **الحد الأدنى المطلق:** 1 vCPU و1GB RAM. + - **الموصى به:** 2GB RAM أو أكثر إذا كنت تشغّل قنوات متعددة أو أتمتة متصفح أو أدوات وسائط. - **نظام التشغيل:** Ubuntu LTS أو Debian/Ubuntu حديث آخر. - إذا كنت على Windows، فإن **WSL2 هو أسهل إعداد بنمط VM** ويتمتع بأفضل توافق + إذا كنت على Windows، فإن **WSL2 هو أسهل إعداد على نمط VM** ويتمتع بأفضل توافق مع الأدوات. راجع [Windows](/ar/platforms/windows)، [استضافة VPS](/ar/vps). وإذا كنت تشغّل macOS داخل VM، فراجع [macOS VM](/ar/install/macos-vm). @@ -917,83 +918,82 @@ x-i18n: - OpenClaw هو مساعد AI شخصي تشغّله على أجهزتك الخاصة. فهو يرد على أسطح المراسلة التي تستخدمها بالفعل (WhatsApp، Telegram، Slack، Mattermost، Discord، Google Chat، Signal، iMessage، WebChat، وchannel plugins المجمعة مثل QQ Bot)، ويمكنه أيضًا تنفيذ الصوت + Canvas حي على المنصات المدعومة. وتمثل **Gateway** طبقة التحكم الدائمة التشغيل؛ أما المساعد فهو المنتج نفسه. + OpenClaw هو مساعد AI شخصي تشغّله على أجهزتك الخاصة. يرد على أسطح المراسلة التي تستخدمها بالفعل (WhatsApp وTelegram وSlack وMattermost وDiscord وGoogle Chat وSignal وiMessage وWebChat، إضافةً إلى channel plugins المضمّنة مثل QQ Bot) ويمكنه أيضًا القيام بالصوت + Canvas حي على المنصات المدعومة. **Gateway** هو مستوى التحكم الذي يعمل دائمًا؛ أما المساعد فهو المنتج. - OpenClaw ليس "مجرد غلاف لـ Claude". بل هو **طبقة تحكم local-first** تتيح لك تشغيل - مساعد قادر على **عتادك أنت**، يمكن الوصول إليه من تطبيقات الدردشة التي تستخدمها بالفعل، مع - جلسات ذات حالة، وذاكرة، وأدوات - من دون تسليم التحكم في سير عملك إلى + OpenClaw ليس "مجرد غلاف حول Claude". بل هو **مستوى تحكم محلي أولًا** يتيح لك تشغيل + مساعد قادر على **أجهزتك الخاصة**، ويمكن الوصول إليه من تطبيقات الدردشة التي تستخدمها بالفعل، مع + جلسات ذات حالة، وذاكرة، وأدوات - من دون تسليم التحكم في سير العمل لديك إلى SaaS مستضاف. أبرز المزايا: - **أجهزتك، بياناتك:** شغّل Gateway حيثما تريد (Mac أو Linux أو VPS) واحتفظ - بمساحة العمل + سجل الجلسات محليًا. - - **قنوات حقيقية، لا sandbox ويب:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage/etc، - بالإضافة إلى الصوت عبر الهاتف المحمول وCanvas على المنصات المدعومة. - - **غير مرتبط بموفر واحد للنماذج:** استخدم Anthropic وOpenAI وMiniMax وOpenRouter وغيرها، مع توجيه - وتبديل احتياطي لكل وكيل. - - **خيار محلي بالكامل:** شغّل نماذج محلية بحيث **يمكن أن تبقى كل البيانات على جهازك** إذا أردت. - - **توجيه متعدد الوكلاء:** وكلاء منفصلون لكل قناة أو حساب أو مهمة، ولكلٍ منها - مساحة عمل وافتراضيات خاصة. - - **مفتوح المصدر وقابل للاختراق:** افحصه، ووسّعه، واستضفه ذاتيًا من دون ارتهان لمورّد. + بمساحة العمل + محفوظات الجلسات محليًا. + - **قنوات حقيقية، وليس sandbox ويب:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage/إلخ، + إضافةً إلى الصوت المحمول وCanvas على المنصات المدعومة. + - **محايد تجاه النماذج:** استخدم Anthropic وOpenAI وMiniMax وOpenRouter وغيرها، مع توجيه + احتياطي وفصل حسب الوكيل. + - **خيار محلي فقط:** شغّل نماذج محلية بحيث **يمكن أن تبقى كل البيانات على جهازك** إذا أردت. + - **توجيه متعدد الوكلاء:** افصل الوكلاء حسب القناة أو الحساب أو المهمة، ولكل واحد + مساحة عمله وافتراضياته الخاصة. + - **مفتوح المصدر وقابل للاختراق:** افحصه ووسّعه واستضفه ذاتيًا من دون ارتهان لمزوّد. - الوثائق: [Gateway](/ar/gateway)، [القنوات](/ar/channels)، [تعدد الوكلاء](/ar/concepts/multi-agent)، + المستندات: [Gateway](/ar/gateway)، [القنوات](/ar/channels)، [تعدد الوكلاء](/ar/concepts/multi-agent)، [الذاكرة](/ar/concepts/memory). - + مشاريع أولى جيدة: - أنشئ موقعًا إلكترونيًا (WordPress أو Shopify أو موقعًا ثابتًا بسيطًا). - - اصنع نموذجًا أوليًا لتطبيق هاتف محمول (المخطط، الشاشات، خطة API). - - نظّم الملفات والمجلدات (تنظيف، تسمية، ووسوم). - - اربط Gmail وأتمتة الملخصات أو المتابعات. + - أنشئ نموذجًا أوليًا لتطبيق جوال (مخطط، شاشات، خطة API). + - نظّم الملفات والمجلدات (تنظيف، تسمية، وسم). + - اربط Gmail وأتمت الملخصات أو المتابعات. - يمكنه التعامل مع مهام كبيرة، لكنه يعمل أفضل عندما تقسّمها إلى مراحل - وتستخدم وكلاء فرعيين للعمل المتوازي. + يمكنه التعامل مع مهام كبيرة، لكنه يعمل بأفضل شكل عندما تقسّمها إلى مراحل + وتستخدم sub agents للعمل المتوازي. - - المكاسب اليومية غالبًا ما تبدو هكذا: + + عادةً ما تبدو المكاسب اليومية هكذا: - **إحاطات شخصية:** ملخصات للبريد الوارد والتقويم والأخبار التي تهمك. - - **البحث وصياغة المسودات:** بحث سريع، وملخصات، ومسودات أولى للرسائل أو الوثائق. - - **التذكيرات والمتابعات:** تنبيهات وقوائم مراجعة مدفوعة بـ cron أو heartbeat. - - **أتمتة المتصفح:** تعبئة النماذج، وجمع البيانات، وتكرار مهام الويب. - - **التنسيق بين الأجهزة:** أرسل مهمة من هاتفك، ودع Gateway تنفذها على خادم، ثم أعد النتيجة إلى الدردشة. + - **البحث والصياغة:** بحث سريع وملخصات ومسودات أولى لرسائل البريد أو المستندات. + - **التذكيرات والمتابعات:** تنبيهات وقوائم تحقق مدفوعة عبر cron أو heartbeat. + - **أتمتة المتصفح:** ملء النماذج وجمع البيانات وتكرار المهام على الويب. + - **التنسيق بين الأجهزة:** أرسل مهمة من هاتفك، ودع Gateway ينفذها على خادم، ثم استلم النتيجة في الدردشة. - - نعم بالنسبة إلى **البحث، والتأهيل، وصياغة المسودات**. إذ يمكنه فحص المواقع، وبناء قوائم مختصرة، - وتلخيص العملاء المحتملين، وكتابة مسودات للتواصل أو نصوص إعلانية. + + نعم فيما يخص **البحث والتأهيل والصياغة**. يمكنه فحص المواقع، وبناء قوائم مختصرة، + وتلخيص العملاء المحتملين، وكتابة مسودات للتواصل أو نصوص إعلانات. - أما **عمليات التواصل أو تشغيل الإعلانات**، فأبقِ إنسانًا ضمن الحلقة. تجنب الرسائل غير المرغوب فيها، واتبع القوانين المحلية - وسياسات المنصات، وراجع أي شيء قبل إرساله. وأكثر الأنماط أمانًا هو أن يدع - OpenClaw يصوغ المسودة ثم توافق أنت عليها. + أما بالنسبة إلى **التواصل أو تشغيل الإعلانات**، فأبقِ إنسانًا في الحلقة. تجنّب الرسائل المزعجة، والتزم بالقوانين المحلية + وسياسات المنصات، وراجع أي شيء قبل إرساله. النمط الأكثر أمانًا هو أن يدع OpenClaw يكتب المسودة ثم توافق أنت عليها. - الوثائق: [الأمان](/ar/gateway/security). + المستندات: [الأمان](/ar/gateway/security). - + OpenClaw هو **مساعد شخصي** وطبقة تنسيق، وليس بديلًا عن IDE. استخدم - Claude Code أو Codex لأسرع حلقة برمجة مباشرة داخل المستودع. واستخدم OpenClaw عندما - تريد ذاكرة دائمة، ووصولًا عبر الأجهزة، وتنسيقًا للأدوات. + Claude Code أو Codex للحصول على أسرع حلقة برمجة مباشرة داخل المستودع. واستخدم OpenClaw عندما + تريد ذاكرة دائمة، ووصولًا عبر الأجهزة، وتنسيق الأدوات. المزايا: - **ذاكرة + مساحة عمل دائمة** عبر الجلسات - - **وصول متعدد المنصات** ‏(WhatsApp، Telegram، TUI، WebChat) - - **تنسيق الأدوات** ‏(المتصفح، والملفات، والجدولة، والخطافات) - - **Gateway دائمة التشغيل** ‏(شغّلها على VPS، وتفاعل معها من أي مكان) - - **Nodes** للمتصفح/الشاشة/الكاميرا/exec المحلي + - **وصول متعدد المنصات** (WhatsApp وTelegram وTUI وWebChat) + - **تنسيق الأدوات** (المتصفح، الملفات، الجدولة، hooks) + - **Gateway تعمل دائمًا** (شغّلها على VPS، وتفاعل معها من أي مكان) + - **Nodes** من أجل المتصفح/الشاشة/الكاميرا/exec المحلي - العرض: [https://openclaw.ai/showcase](https://openclaw.ai/showcase) + عرض توضيحي: [https://openclaw.ai/showcase](https://openclaw.ai/showcase) @@ -1002,68 +1002,68 @@ x-i18n: - استخدم overrides مُدارة بدل تعديل نسخة المستودع. ضع تغييراتك في `~/.openclaw/skills//SKILL.md` (أو أضف مجلدًا عبر `skills.load.extraDirs` في `~/.openclaw/openclaw.json`). ترتيب الأولوية هو `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → المجمّعة → `skills.load.extraDirs`، لذا فإن overrides المُدارة لا تزال تتقدم على Skills المجمعة من دون لمس git. وإذا كنت تحتاج إلى تثبيت المهارة عالميًا لكن تريد أن تكون مرئية فقط لبعض الوكلاء، فأبقِ النسخة المشتركة في `~/.openclaw/skills` وتحكم في الظهور عبر `agents.defaults.skills` و`agents.list[].skills`. ولا ينبغي أن تعيش في المستودع وتُرسل على هيئة PRs إلا التعديلات الجديرة بالرفع للمشروع. + استخدم التجاوزات المُدارة بدلًا من تعديل نسخة المستودع. ضع تغييراتك في `~/.openclaw/skills//SKILL.md` (أو أضف مجلدًا عبر `skills.load.extraDirs` في `~/.openclaw/openclaw.json`). الأولوية هي `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → المضمّن → `skills.load.extraDirs`، لذلك تظل التجاوزات المُدارة متقدمة على Skills المضمّنة من دون لمس git. وإذا كنت تحتاج إلى تثبيت المهارة عالميًا لكن تريد ظهورها لبعض الوكلاء فقط، فاحتفظ بالنسخة المشتركة في `~/.openclaw/skills` وتحكم في الظهور عبر `agents.defaults.skills` و`agents.list[].skills`. أما التعديلات الجديرة بالإرسال upstream فقط فينبغي أن تعيش في المستودع وتُرسل كـ PRs. - نعم. أضف أدلة إضافية عبر `skills.load.extraDirs` في `~/.openclaw/openclaw.json` (أدنى أولوية). ترتيب الأولوية الافتراضي هو `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → المجمّعة → `skills.load.extraDirs`. ويثبّت `clawhub` افتراضيًا في `./skills`، ويتعامل OpenClaw مع ذلك بوصفه `/skills` في الجلسة التالية. وإذا كان يجب أن تكون المهارة مرئية فقط لوكلاء معينين، فاقرن ذلك مع `agents.defaults.skills` أو `agents.list[].skills`. + نعم. أضف أدلة إضافية عبر `skills.load.extraDirs` في `~/.openclaw/openclaw.json` (أدنى أولوية). ترتيب الأولوية الافتراضي هو `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → المضمّن → `skills.load.extraDirs`. يقوم `clawhub` بالتثبيت في `./skills` افتراضيًا، ويتعامل OpenClaw مع ذلك على أنه `/skills` في الجلسة التالية. وإذا كان يجب أن تظهر المهارة لوكلاء معينين فقط، فاقرن ذلك بـ `agents.defaults.skills` أو `agents.list[].skills`. الأنماط المدعومة اليوم هي: - - **وظائف Cron**: يمكن للوظائف المعزولة ضبط override للنموذج لكل وظيفة. - - **الوكلاء الفرعيون**: وجّه المهام إلى وكلاء منفصلين لديهم نماذج افتراضية مختلفة. + - **وظائف Cron**: يمكن للوظائف المعزولة تعيين تجاوز `model` لكل وظيفة. + - **Sub-agents**: وجّه المهام إلى وكلاء منفصلين لهم نماذج افتراضية مختلفة. - **التبديل عند الطلب**: استخدم `/model` لتبديل نموذج الجلسة الحالية في أي وقت. - راجع [وظائف Cron](/ar/automation/cron-jobs)، [التوجيه متعدد الوكلاء](/ar/concepts/multi-agent)، و[أوامر الشرطة المائلة](/ar/tools/slash-commands). + راجع [وظائف Cron](/ar/automation/cron-jobs)، [التوجيه متعدد الوكلاء](/ar/concepts/multi-agent)، و[أوامر Slash](/ar/tools/slash-commands). - - استخدم **الوكلاء الفرعيين** للمهام الطويلة أو المتوازية. يعمل الوكلاء الفرعيون في جلستهم الخاصة، - ويعيدون ملخصًا، ويحافظون على استجابة الدردشة الرئيسية. + + استخدم **sub-agents** للمهام الطويلة أو المتوازية. تعمل sub-agents في جلساتها الخاصة، + وتعيد ملخصًا، وتحافظ على استجابة الدردشة الرئيسية. - اطلب من البوت "spawn a sub-agent for this task" أو استخدم `/subagents`. - واستخدم `/status` في الدردشة لمعرفة ما الذي تقوم به Gateway الآن (وما إذا كانت مشغولة). + اطلب من bot أن "ينشئ sub-agent لهذه المهمة" أو استخدم `/subagents`. + واستخدم `/status` في الدردشة لمعرفة ما الذي يقوم به Gateway الآن (وما إذا كان مشغولًا). - نصيحة بشأن الرموز: تستهلك كل من المهام الطويلة والوكلاء الفرعيين رموزًا. وإذا كانت التكلفة مصدر قلق، فاضبط - نموذجًا أرخص للوكلاء الفرعيين عبر `agents.defaults.subagents.model`. + نصيحة حول الرموز: المهام الطويلة وsub-agents كلاهما يستهلكان الرموز. إذا كانت التكلفة مقلقة، فاضبط + نموذجًا أرخص لـ sub-agents عبر `agents.defaults.subagents.model`. - الوثائق: [الوكلاء الفرعيون](/ar/tools/subagents)، [المهام الخلفية](/ar/automation/tasks). + المستندات: [Sub-agents](/ar/tools/subagents)، [المهام الخلفية](/ar/automation/tasks). - - استخدم ربط الخيوط. يمكنك ربط خيط Discord بوكيل فرعي أو بهدف جلسة بحيث تبقى الرسائل اللاحقة في ذلك الخيط على الجلسة المرتبطة. + + استخدم روابط الخيوط. يمكنك ربط خيط Discord بهدف subagent أو session بحيث تبقى الرسائل اللاحقة في ذلك الخيط ضمن الجلسة المرتبطة. التدفق الأساسي: - - نفّذ spawn باستخدام `sessions_spawn` مع `thread: true` (واختياريًا `mode: "session"` للمتابعة الدائمة). - - أو اربط يدويًا باستخدام `/focus `. + - أنشئ عبر `sessions_spawn` باستخدام `thread: true` (واختياريًا `mode: "session"` للمتابعة الدائمة). + - أو اربط يدويًا عبر `/focus `. - استخدم `/agents` لفحص حالة الربط. - استخدم `/session idle ` و`/session max-age ` للتحكم في إلغاء التركيز التلقائي. - استخدم `/unfocus` لفصل الخيط. - الإعداد المطلوب: + الإعدادات المطلوبة: - الافتراضيات العامة: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`. - - تجاوزات Discord: ‏`channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`. - - ربط تلقائي عند الـ spawn: اضبط `channels.discord.threadBindings.spawnSubagentSessions: true`. + - تجاوزات Discord: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`. + - الربط التلقائي عند الإنشاء: اضبط `channels.discord.threadBindings.spawnSubagentSessions: true`. - الوثائق: [الوكلاء الفرعيون](/ar/tools/subagents)، [Discord](/ar/channels/discord)، [مرجع الإعداد](/ar/gateway/configuration-reference)، [أوامر الشرطة المائلة](/ar/tools/slash-commands). + المستندات: [Sub-agents](/ar/tools/subagents)، [Discord](/ar/channels/discord)، [مرجع التكوين](/ar/gateway/configuration-reference)، [أوامر Slash](/ar/tools/slash-commands). - - تحقق أولًا من مسار مقدم الطلب الذي تم حله: + + تحقق أولًا من مسار الطالب الذي تم حله: - - يفضّل تسليم الوكيل الفرعي في وضع الاكتمال أي خيط أو مسار محادثة مرتبط عندما يكون موجودًا. - - إذا كان أصل الاكتمال يحمل قناة فقط، فإن OpenClaw يعود إلى المسار المخزن لجلسة مقدم الطلب (`lastChannel` / `lastTo` / `lastAccountId`) حتى ينجح التسليم المباشر. - - إذا لم يوجد مسار مرتبط ولا مسار مخزن صالح، فقد يفشل التسليم المباشر وتعود النتيجة إلى التسليم المؤجل ضمن الجلسة بدلًا من النشر الفوري في الدردشة. - - لا تزال الأهداف غير الصالحة أو القديمة قادرة على فرض الرجوع إلى الطابور أو فشل التسليم النهائي. - - إذا كان آخر رد مرئي للمساعد من الوكيل الابن هو الرمز الصامت الدقيق `NO_REPLY` / `no_reply`، أو بالضبط `ANNOUNCE_SKIP`، فإن OpenClaw يتعمد حجب الإعلان بدلًا من نشر تقدم قديم. - - إذا انتهت مهلة الوكيل الابن بعد استدعاءات أدوات فقط، فقد يختصر الإعلان ذلك إلى ملخص موجز للتقدم الجزئي بدلًا من إعادة عرض خرج الأدوات الخام. + - يفضّل تسليم subagent في وضع الإكمال أي خيط أو مسار محادثة مرتبط عند وجوده. + - إذا كان أصل الإكمال يحمل قناة فقط، يعود OpenClaw إلى المسار المخزن لجلسة الطالب (`lastChannel` / `lastTo` / `lastAccountId`) بحيث يظل التسليم المباشر ممكنًا. + - إذا لم يوجد مسار مرتبط ولا مسار مخزن صالح، فقد يفشل التسليم المباشر وتعود النتيجة إلى تسليم الجلسة عبر الطابور بدلًا من النشر الفوري في الدردشة. + - قد تؤدي الأهداف غير الصالحة أو القديمة أيضًا إلى السقوط إلى الطابور أو فشل التسليم النهائي. + - إذا كان آخر رد مساعد مرئي للطفل هو الرمز الصامت المطابق تمامًا `NO_REPLY` / `no_reply`، أو المطابق تمامًا `ANNOUNCE_SKIP`، فإن OpenClaw يتعمد كتم الإعلان بدلًا من نشر تقدم أقدم لم يعد صالحًا. + - إذا انتهت مهلة الطفل بعد استدعاءات أدوات فقط، فقد يختصر الإعلان ذلك إلى ملخص قصير للتقدم الجزئي بدلًا من إعادة عرض مخرجات الأدوات الخام. التصحيح: @@ -1071,18 +1071,18 @@ x-i18n: openclaw tasks show ``` - الوثائق: [الوكلاء الفرعيون](/ar/tools/subagents)، [المهام الخلفية](/ar/automation/tasks)، [أدوات الجلسات](/ar/concepts/session-tool). + المستندات: [Sub-agents](/ar/tools/subagents)، [المهام الخلفية](/ar/automation/tasks)، [أدوات الجلسة](/ar/concepts/session-tool). - يعمل Cron داخل عملية Gateway. فإذا لم تكن Gateway تعمل باستمرار، + تعمل Cron داخل عملية Gateway. إذا لم يكن Gateway يعمل بشكل مستمر، فلن تعمل الوظائف المجدولة. قائمة تحقق: - - تأكد من أن cron مفعّل (`cron.enabled`) وأن `OPENCLAW_SKIP_CRON` غير مضبوط. - - تحقق من أن Gateway تعمل 24/7 (من دون نوم/إعادة تشغيل). + - أكد أن cron مفعّلة (`cron.enabled`) وأن `OPENCLAW_SKIP_CRON` غير مضبوط. + - تحقق من أن Gateway يعمل 24/7 (من دون سكون/إعادة تشغيل). - تحقق من إعدادات المنطقة الزمنية للوظيفة (`--tz` مقابل المنطقة الزمنية للمضيف). التصحيح: @@ -1092,21 +1092,21 @@ x-i18n: openclaw cron runs --id --limit 50 ``` - الوثائق: [وظائف Cron](/ar/automation/cron-jobs)، [الأتمتة والمهام](/ar/automation). + المستندات: [وظائف Cron](/ar/automation/cron-jobs)، [الأتمتة والمهام](/ar/automation). - - تحقق أولًا من وضع التسليم: + + تحقق من وضع التسليم أولًا: - - `--no-deliver` / `delivery.mode: "none"` يعني أنه لا يُتوقع أي رسالة خارجية. - - غياب هدف إعلان (`channel` / `to`) أو عدم صلاحيته يعني أن المشغّل تخطى التسليم الخارجي. - - تعني أخطاء مصادقة القناة (`unauthorized`, `Forbidden`) أن المشغّل حاول التسليم لكن بيانات الاعتماد منعته. - - تُعامل النتيجة المعزولة الصامتة (`NO_REPLY` / `no_reply` فقط) على أنها غير قابلة للتسليم عمدًا، لذلك يحجب المشغّل أيضًا التسليم الاحتياطي المؤجل. + - `--no-deliver` / `delivery.mode: "none"` يعني أنه لا يُتوقع إرسال أي رسالة خارجية. + - الهدف المفقود أو غير الصالح للإعلان (`channel` / `to`) يعني أن المشغّل تخطى التسليم الصادر. + - فشل مصادقة القناة (`unauthorized`, `Forbidden`) يعني أن المشغّل حاول التسليم لكن بيانات الاعتماد منعته. + - النتيجة المعزولة الصامتة (`NO_REPLY` / `no_reply` فقط) تُعامل على أنها غير قابلة للتسليم عمدًا، لذا يكتم المشغّل أيضًا تسليم الطابور الاحتياطي. - بالنسبة إلى وظائف cron المعزولة، يملك المشغّل مسؤولية التسليم النهائي. ومن المتوقع - أن يعيد الوكيل ملخصًا نصيًا عاديًا ليرسله المشغّل. و`--no-deliver` يبقي - تلك النتيجة داخلية؛ ولا يسمح للوكيل بالإرسال مباشرة باستخدام + بالنسبة إلى وظائف cron المعزولة، يملك المشغّل التسليم النهائي. من المتوقع + أن يعيد الوكيل ملخصًا نصيًا عاديًا كي يرسله المشغّل. يحافظ `--no-deliver` + على بقاء النتيجة داخلية؛ ولا يسمح للوكيل بالإرسال مباشرةً باستخدام أداة الرسائل بدلًا من ذلك. التصحيح: @@ -1116,27 +1116,27 @@ x-i18n: openclaw tasks show ``` - الوثائق: [وظائف Cron](/ar/automation/cron-jobs)، [المهام الخلفية](/ar/automation/tasks). + المستندات: [وظائف Cron](/ar/automation/cron-jobs)، [المهام الخلفية](/ar/automation/tasks). - - عادةً ما يكون هذا مسار تبديل النموذج المباشر، وليس جدولة مكررة. + + غالبًا ما يكون هذا هو مسار التبديل الحي للنموذج، وليس جدولة مكررة. - يمكن لـ cron المعزول حفظ تسليم نموذج وقت التشغيل وإعادة المحاولة عندما - يطلق التشغيل النشط `LiveSessionModelSwitchError`. وتحافظ - إعادة المحاولة على الموفر/النموذج المُبدّل، وإذا كان التبديل يحمل override جديدًا لملف تعريف المصادقة، فإن cron - تحفظه أيضًا قبل إعادة المحاولة. + يمكن لـ cron المعزول أن يحفظ تحويل نموذج وقت التشغيل ويعيد المحاولة عندما + يرمي التشغيل النشط `LiveSessionModelSwitchError`. وتحافظ إعادة المحاولة على + المزوّد/النموذج بعد التبديل، وإذا حمل التبديل تجاوزًا جديدًا لملف تعريف المصادقة، + فإن cron يحفظه أيضًا قبل إعادة المحاولة. قواعد الاختيار ذات الصلة: - - يفوز override نموذج خطاف Gmail أولًا عند الاقتضاء. + - يتقدم تجاوز نموذج hook الخاص بـ Gmail أولًا عندما يكون منطبقًا. - ثم `model` لكل وظيفة. - - ثم أي override مخزن لنموذج جلسة cron. - - ثم الاختيار العادي لنموذج الوكيل/الافتراضي. + - ثم أي تجاوز نموذج مخزن لجلسة cron. + - ثم الاختيار العادي لنموذج الوكيل/النموذج الافتراضي. - تكون حلقة إعادة المحاولة محدودة. فبعد المحاولة الأولية وإعادتَي تبديل، - يجهض cron بدلًا من الدوران بلا نهاية. + حلقة إعادة المحاولة محدودة. بعد المحاولة الأولية إضافةً إلى محاولتي تبديل، + تتوقف cron بدلًا من الاستمرار إلى ما لا نهاية. التصحيح: @@ -1145,12 +1145,12 @@ x-i18n: openclaw tasks show ``` - الوثائق: [وظائف Cron](/ar/automation/cron-jobs)، [CLI الخاص بـ cron](/cli/cron). + المستندات: [وظائف Cron](/ar/automation/cron-jobs)، [CLI الخاص بـ cron](/cli/cron). - - استخدم أوامر `openclaw skills` الأصلية أو أسقِط Skills في مساحة العمل الخاصة بك. واجهة Skills في macOS غير متاحة على Linux. + + استخدم أوامر `openclaw skills` الأصلية أو أسقط Skills داخل مساحة العمل لديك. واجهة Skills في macOS غير متاحة على Linux. تصفح Skills على [https://clawhub.ai](https://clawhub.ai). ```bash @@ -1164,39 +1164,39 @@ x-i18n: openclaw skills check ``` - تؤدي عمليات التثبيت الأصلية باستخدام `openclaw skills install` إلى الكتابة داخل الدليل `skills/` - في مساحة العمل النشطة. ولا تثبّت CLI المنفصل `clawhub` إلا إذا كنت تريد نشر - Skills الخاصة بك أو مزامنتها. وبالنسبة إلى التثبيتات المشتركة بين الوكلاء، ضع المهارة ضمن + يكتب `openclaw skills install` الأصلي داخل دليل `skills/` + في مساحة العمل النشطة. ثبّت CLI المنفصل `clawhub` فقط إذا كنت تريد نشر أو + مزامنة Skills الخاصة بك. وبالنسبة إلى التثبيتات المشتركة عبر الوكلاء، ضع Skill ضمن `~/.openclaw/skills` واستخدم `agents.defaults.skills` أو - `agents.list[].skills` إذا أردت تضييق أي الوكلاء يستطيعون رؤيتها. + `agents.list[].skills` إذا أردت تضييق الوكلاء الذين يمكنهم رؤيتها. - + نعم. استخدم مجدول Gateway: - **وظائف Cron** للمهام المجدولة أو المتكررة (تستمر عبر إعادة التشغيل). - - **Heartbeat** للفحوصات الدورية الخاصة بـ "الجلسة الرئيسية". + - **Heartbeat** لفحوصات دورية لـ "الجلسة الرئيسية". - **وظائف معزولة** لوكلاء مستقلين ينشرون ملخصات أو يسلّمون إلى الدردشات. - الوثائق: [وظائف Cron](/ar/automation/cron-jobs)، [الأتمتة والمهام](/ar/automation)، + المستندات: [وظائف Cron](/ar/automation/cron-jobs)، [الأتمتة والمهام](/ar/automation)، [Heartbeat](/ar/gateway/heartbeat). - - ليس مباشرة. تُضبط Skills الخاصة بـ macOS بواسطة `metadata.openclaw.os` مع الثنائيات المطلوبة، ولا تظهر Skills في system prompt إلا عندما تكون مؤهلة على **مضيف Gateway**. وعلى Linux، لن تُحمّل Skills التي تعمل فقط على `darwin` (مثل `apple-notes` و`apple-reminders` و`things-mac`) ما لم تتجاوز هذا التقييد. + + ليس مباشرةً. يتم تقييد Skills الخاصة بـ macOS عبر `metadata.openclaw.os` إضافةً إلى الثنائيات المطلوبة، ولا تظهر Skills في system prompt إلا عندما تكون مؤهلة على **مضيف Gateway**. وعلى Linux، لن يتم تحميل Skills الخاصة بـ `darwin` فقط (مثل `apple-notes` و`apple-reminders` و`things-mac`) ما لم تتجاوز هذا التقييد. لديك ثلاثة أنماط مدعومة: **الخيار A - شغّل Gateway على جهاز Mac (الأبسط).** - شغّل Gateway حيث توجد ثنائيات macOS، ثم اتصل من Linux في [الوضع البعيد](#gateway-ports-already-running-and-remote-mode) أو عبر Tailscale. وستحمّل Skills بشكل طبيعي لأن مضيف Gateway هو macOS. + شغّل Gateway حيث توجد ثنائيات macOS، ثم اتصل من Linux في [الوضع البعيد](#gateway-ports-already-running-and-remote-mode) أو عبر Tailscale. تُحمَّل Skills بشكل طبيعي لأن مضيف Gateway هو macOS. - **الخيار B - استخدم macOS node (من دون SSH).** - شغّل Gateway على Linux، وأقرن macOS node (تطبيق شريط القوائم)، واضبط **Node Run Commands** على "Always Ask" أو "Always Allow" على جهاز Mac. ويمكن لـ OpenClaw أن يعامل Skills الخاصة بـ macOS على أنها مؤهلة عندما تكون الثنائيات المطلوبة موجودة على الـ node. ويشغّل الوكيل تلك Skills عبر أداة `nodes`. وإذا اخترت "Always Ask"، فإن الموافقة على "Always Allow" في المطالبة تضيف ذلك الأمر إلى قائمة السماح. + **الخيار B - استخدم node macOS (من دون SSH).** + شغّل Gateway على Linux، واقرن node لـ macOS (تطبيق شريط القوائم)، واضبط **Node Run Commands** على "Always Ask" أو "Always Allow" على جهاز Mac. يمكن لـ OpenClaw أن يعامل Skills الخاصة بـ macOS فقط على أنها مؤهلة عندما تكون الثنائيات المطلوبة موجودة على node. يشغّل الوكيل هذه Skills عبر أداة `nodes`. وإذا اخترت "Always Ask"، فإن الموافقة على "Always Allow" في المطالبة تضيف ذلك الأمر إلى allowlist. - **الخيار C - توكيل ثنائيات macOS عبر SSH (متقدم).** - أبقِ Gateway على Linux، لكن اجعل ثنائيات CLI المطلوبة تُحل إلى أغلفة SSH تعمل على جهاز Mac. ثم تجاوز إعداد المهارة للسماح بـ Linux حتى تظل مؤهلة. + **الخيار C - وكّل ثنائيات macOS عبر SSH (متقدم).** + أبقِ Gateway على Linux، لكن اجعل ثنائيات CLI المطلوبة تُحل إلى أغلفة SSH تُشغّل على جهاز Mac. ثم تجاوز Skill للسماح بـ Linux بحيث تظل مؤهلة. 1. أنشئ غلاف SSH للثنائي (مثال: `memo` لـ Apple Notes): @@ -1207,7 +1207,7 @@ x-i18n: ``` 2. ضع الغلاف على `PATH` على مضيف Linux (مثل `~/bin/memo`). - 3. تجاوز metadata الخاصة بالمهارة (في مساحة العمل أو `~/.openclaw/skills`) للسماح بـ Linux: + 3. تجاوز metadata الخاصة بـ Skill (في workspace أو `~/.openclaw/skills`) للسماح بـ Linux: ```markdown --- @@ -1217,175 +1217,175 @@ x-i18n: --- ``` - 4. ابدأ جلسة جديدة حتى تتجدد لقطة Skills. + 4. ابدأ جلسة جديدة حتى يتم تحديث لقطة Skills. - + ليس مدمجًا حاليًا. الخيارات: - - **Skill / plugin مخصص:** الأفضل للوصول الموثوق إلى API ‏(كل من Notion وHeyGen لهما API). + - **Skill / plugin مخصص:** الأفضل للوصول الموثوق إلى API (لكل من Notion وHeyGen APIs). - **أتمتة المتصفح:** تعمل من دون شيفرة لكنها أبطأ وأكثر هشاشة. - إذا أردت الاحتفاظ بالسياق لكل عميل (سير عمل الوكالات)، فهناك نمط بسيط: + إذا كنت تريد الحفاظ على السياق لكل عميل (سير عمل الوكالات)، فالنمط البسيط هو: - صفحة Notion واحدة لكل عميل (السياق + التفضيلات + العمل النشط). - اطلب من الوكيل جلب تلك الصفحة في بداية الجلسة. - وإذا كنت تريد تكاملًا أصليًا، فافتح طلب ميزة أو ابنِ Skill - تستهدف تلك الـ APIs. + إذا كنت تريد تكاملًا أصليًا، فافتح طلب ميزة أو ابنِ Skill + تستهدف تلك APIs. - تثبيت Skills: + ثبّت Skills: ```bash openclaw skills install openclaw skills update --all ``` - يتم وضع عمليات التثبيت الأصلية في دليل `skills/` ضمن مساحة العمل النشطة. وبالنسبة إلى Skills المشتركة بين الوكلاء، ضعها في `~/.openclaw/skills//SKILL.md`. وإذا كان يجب أن تراها بعض الوكلاء فقط، فاضبط `agents.defaults.skills` أو `agents.list[].skills`. وتتوقع بعض Skills وجود ثنائيات مثبّتة عبر Homebrew؛ وعلى Linux يعني ذلك Linuxbrew (راجع إدخال الأسئلة الشائعة الخاص بـ Homebrew على Linux أعلاه). راجع [Skills](/ar/tools/skills)، و[إعداد Skills](/ar/tools/skills-config)، و[ClawHub](/ar/tools/clawhub). + تصل التثبيتات الأصلية إلى دليل `skills/` في مساحة العمل النشطة. وبالنسبة إلى Skills المشتركة بين الوكلاء، ضعها في `~/.openclaw/skills//SKILL.md`. وإذا كان يجب أن يراها بعض الوكلاء فقط في التثبيت المشترك، فاضبط `agents.defaults.skills` أو `agents.list[].skills`. تتوقع بعض Skills وجود ثنائيات مثبّتة عبر Homebrew؛ وعلى Linux فهذا يعني Linuxbrew (راجع إدخال الأسئلة الشائعة عن Homebrew على Linux أعلاه). راجع [Skills](/ar/tools/skills)، [إعدادات Skills](/ar/tools/skills-config)، و[ClawHub](/ar/tools/clawhub). - - استخدم ملف المتصفح المدمج `user`، الذي يتصل عبر Chrome DevTools MCP: + + استخدم ملف تعريف المتصفح المضمّن `user`، الذي يتصل عبر Chrome DevTools MCP: ```bash openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot ``` - وإذا كنت تريد اسمًا مخصصًا، فأنشئ ملف MCP صريحًا: + وإذا أردت اسمًا مخصصًا، فأنشئ ملف تعريف MCP صريحًا: ```bash openclaw browser create-profile --name chrome-live --driver existing-session openclaw browser --browser-profile chrome-live tabs ``` - هذا المسار محلي على المضيف. وإذا كانت Gateway تعمل في مكان آخر، فإما أن تشغّل مضيف node على جهاز المتصفح أو تستخدم CDP عن بُعد بدلًا من ذلك. + هذا المسار محلي للمضيف. إذا كان Gateway يعمل في مكان آخر، فإما أن تشغّل مضيف node على جهاز المتصفح أو تستخدم CDP بعيدًا بدلًا من ذلك. - الحدود الحالية على `existing-session` / `user`: + الحدود الحالية لـ `existing-session` / `user`: - - الإجراءات تعتمد على ref، وليس على CSS-selector + - الإجراءات تعتمد على المرجع ref، لا على محددات CSS - تتطلب عمليات الرفع `ref` / `inputRef` وتدعم حاليًا ملفًا واحدًا في كل مرة - - لا تزال `responsebody`، وتصدير PDF، واعتراض التنزيلات، والإجراءات الدفعية تحتاج إلى متصفح مُدار أو ملف CDP خام + - لا تزال `responsebody` وتصدير PDF واعتراض التنزيلات والإجراءات الدُفعية تحتاج إلى متصفح مُدار أو ملف تعريف CDP خام -## الحاويات الآمنة والذاكرة +## العزل والذاكرة - - نعم. راجع [الحاويات الآمنة](/ar/gateway/sandboxing). وبالنسبة إلى إعداد Docker تحديدًا (Gateway كاملة داخل Docker أو صور sandbox)، راجع [Docker](/ar/install/docker). + + نعم. راجع [العزل](/ar/gateway/sandboxing). وبالنسبة إلى إعدادات Docker تحديدًا (gateway كاملة داخل Docker أو صور sandbox)، راجع [Docker](/ar/install/docker). - الصورة الافتراضية تضع الأمان أولًا وتعمل باسم المستخدم `node`، ولذلك فهي لا - تتضمن حزم النظام أو Homebrew أو المتصفحات المجمعة. ولإعداد أكمل: + الصورة الافتراضية تعتمد الأمان أولًا وتعمل كمستخدم `node`، لذلك فهي لا + تتضمن حزم النظام أو Homebrew أو المتصفحات المضمّنة. وللحصول على إعداد أكمل: - - اجعل `/home/node` دائمًا باستخدام `OPENCLAW_HOME_VOLUME` حتى تبقى الذاكرات المؤقتة. - - ضمّن تبعيات النظام في الصورة باستخدام `OPENCLAW_DOCKER_APT_PACKAGES`. - - ثبّت متصفحات Playwright عبر CLI المجمعة: + - اجعل `/home/node` دائمًا باستخدام `OPENCLAW_HOME_VOLUME` بحيث تبقى الذاكرات المؤقتة. + - اخبز تبعيات النظام داخل الصورة باستخدام `OPENCLAW_DOCKER_APT_PACKAGES`. + - ثبّت متصفحات Playwright عبر CLI المضمّن: `node /app/node_modules/playwright-core/cli.js install chromium` - - اضبط `PLAYWRIGHT_BROWSERS_PATH` وتأكد من حفظ هذا المسار. + - اضبط `PLAYWRIGHT_BROWSERS_PATH` وتأكد من بقاء المسار دائمًا. - الوثائق: [Docker](/ar/install/docker)، [المتصفح](/ar/tools/browser). + المستندات: [Docker](/ar/install/docker)، [المتصفح](/ar/tools/browser). - - نعم - إذا كانت الحركة الخاصة لديك **رسائل خاصة** وكانت الحركة العامة لديك **مجموعات**. + + نعم - إذا كانت الحركة الخاصة لديك هي **رسائل خاصة** وكانت الحركة العامة **مجموعات**. - استخدم `agents.defaults.sandbox.mode: "non-main"` حتى تعمل جلسات المجموعة/القناة (المفاتيح غير الرئيسية) داخل Docker، بينما تبقى جلسة DM الرئيسية على المضيف. ثم قيّد الأدوات المتاحة في الجلسات ضمن sandbox عبر `tools.sandbox.tools`. + استخدم `agents.defaults.sandbox.mode: "non-main"` بحيث تعمل جلسات المجموعات/القنوات (مفاتيح غير رئيسية) داخل Docker، بينما تبقى جلسة DM الرئيسية على المضيف. ثم قيّد الأدوات المتاحة في الجلسات المعزولة عبر `tools.sandbox.tools`. - شرح الإعداد + مثال إعداد: [المجموعات: رسائل خاصة شخصية + مجموعات عامة](/ar/channels/groups#pattern-personal-dms-public-groups-single-agent) + شرح الإعداد + مثال للتكوين: [المجموعات: رسائل خاصة شخصية + مجموعات عامة](/ar/channels/groups#pattern-personal-dms-public-groups-single-agent) - مرجع الإعداد الأساسي: [إعداد Gateway](/ar/gateway/configuration-reference#agentsdefaultssandbox) + مرجع الإعدادات الأساسي: [تكوين Gateway](/ar/gateway/configuration-reference#agentsdefaultssandbox) - اضبط `agents.defaults.sandbox.docker.binds` على `["host:path:mode"]` (مثل `"/home/user/src:/src:ro"`). تُدمج الروابط العامة + روابط كل وكيل؛ وتُتجاهل روابط كل وكيل عندما تكون `scope: "shared"`. استخدم `:ro` لأي شيء حساس وتذكّر أن الروابط تتجاوز جدران نظام الملفات الخاصة بـ sandbox. + اضبط `agents.defaults.sandbox.docker.binds` على `["host:path:mode"]` (مثل `"/home/user/src:/src:ro"`). تندمج عمليات الربط العامة وعمليات الربط لكل وكيل؛ ويتم تجاهل عمليات الربط لكل وكيل عندما تكون `scope: "shared"`. استخدم `:ro` لأي شيء حساس، وتذكّر أن عمليات الربط تتجاوز جدران نظام الملفات الخاصة بـ sandbox. - يتحقق OpenClaw من مصادر الربط مقارنةً بكل من المسار المُطبع والمسار القانوني الذي يتم حله عبر أعمق سلف موجود. وهذا يعني أن الهروب عبر symlink-parent ما زال يفشل بشكل مغلق حتى عندما لا يكون الجزء الأخير من المسار موجودًا بعد، ولا تزال فحوصات allowed-root تنطبق بعد حل الروابط الرمزية. + يتحقق OpenClaw من مصادر الربط مقابل كل من المسار المطبع والمسار القانوني الذي يُحل عبر أعمق أصل موجود. وهذا يعني أن محاولات الهروب عبر الوالدين القائمين على symlink ما تزال تُغلق بشكل آمن حتى عندما لا يكون المقطع الأخير من المسار موجودًا بعد، كما تستمر فحوصات allowed-root في التطبيق بعد حل symlink. - راجع [الحاويات الآمنة](/ar/gateway/sandboxing#custom-bind-mounts) و[Sandbox مقابل سياسة الأداة مقابل الامتيازات المرتفعة](/ar/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check) للاطلاع على أمثلة وملاحظات السلامة. + راجع [العزل](/ar/gateway/sandboxing#custom-bind-mounts) و[Sandbox vs Tool Policy vs Elevated](/ar/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check) لأمثلة وملاحظات الأمان. - ذاكرة OpenClaw هي مجرد ملفات Markdown في مساحة عمل الوكيل: + ذاكرة OpenClaw ليست سوى ملفات Markdown في مساحة عمل الوكيل: - ملاحظات يومية في `memory/YYYY-MM-DD.md` - - ملاحظات طويلة الأمد منتقاة في `MEMORY.md` (للجلسات الرئيسية/الخاصة فقط) + - ملاحظات طويلة الأمد منسّقة في `MEMORY.md` (للجلسات الرئيسية/الخاصة فقط) - كما يشغّل OpenClaw **تفريغًا صامتًا للذاكرة قبل الضغط** لتذكير النموذج - بكتابة ملاحظات دائمة قبل الضغط التلقائي. ولا يعمل هذا إلا عندما تكون مساحة العمل - قابلة للكتابة (تتخطى sandboxes للقراءة فقط ذلك). راجع [الذاكرة](/ar/concepts/memory). + يشغّل OpenClaw أيضًا **تفريغ ذاكرة صامت قبل الضغط** لتذكير النموذج + بكتابة ملاحظات دائمة قبل الضغط التلقائي. لا يعمل هذا إلا عندما تكون مساحة العمل + قابلة للكتابة (تتخطاه sandboxes للقراءة فقط). راجع [الذاكرة](/ar/concepts/memory). - - اطلب من البوت أن **يكتب الحقيقة في الذاكرة**. فالملاحظات طويلة الأمد مكانها `MEMORY.md`، - والسياق قصير الأمد يذهب إلى `memory/YYYY-MM-DD.md`. + + اطلب من bot أن **يكتب الحقيقة إلى الذاكرة**. الملاحظات طويلة الأمد تنتمي إلى `MEMORY.md`, + أما السياق قصير الأمد فيوضع في `memory/YYYY-MM-DD.md`. - ما زلنا نحسّن هذا المجال. ومن المفيد تذكير النموذج بتخزين الذكريات؛ - فهو يعرف ما الذي يجب فعله. وإذا استمر في النسيان، فتحقق من أن Gateway تستخدم + هذا ما يزال مجالًا نعمل على تحسينه. ومن المفيد تذكير النموذج بتخزين الذكريات؛ + فهو سيعرف ما الذي يجب فعله. وإذا استمر في النسيان، فتحقق من أن Gateway يستخدم مساحة العمل نفسها في كل تشغيل. - الوثائق: [الذاكرة](/ar/concepts/memory)، [مساحة عمل الوكيل](/ar/concepts/agent-workspace). + المستندات: [الذاكرة](/ar/concepts/memory)، [مساحة عمل الوكيل](/ar/concepts/agent-workspace). - تعيش ملفات الذاكرة على القرص وتستمر حتى تحذفها. والحد هو - مساحة التخزين لديك، وليس النموذج. أما **سياق الجلسة** فلا يزال محدودًا بنافذة سياق - النموذج، لذلك قد تُضغط المحادثات الطويلة أو تُقتطع. ولهذا السبب - يوجد بحث الذاكرة - فهو يعيد الأجزاء ذات الصلة فقط إلى السياق. + تعيش ملفات الذاكرة على القرص وتستمر حتى تحذفها. الحد هنا هو + التخزين، وليس النموذج. أما **سياق الجلسة** فلا يزال مقيدًا بنافذة + سياق النموذج، لذا قد تُضغط المحادثات الطويلة أو تُقتطع. ولهذا + يوجد بحث الذاكرة - إذ يعيد فقط الأجزاء ذات الصلة إلى السياق. - الوثائق: [الذاكرة](/ar/concepts/memory)، [السياق](/ar/concepts/context). + المستندات: [الذاكرة](/ar/concepts/memory)، [السياق](/ar/concepts/context). - - نعم فقط إذا كنت تستخدم **OpenAI embeddings**. تغطي Codex OAuth الدردشة/الإكمالات - ولا **تمنح** وصولًا إلى embeddings، لذا فإن **تسجيل الدخول باستخدام Codex (OAuth أو - تسجيل دخول Codex CLI)** لا يفيد في البحث الدلالي في الذاكرة. ولا تزال OpenAI embeddings - تحتاج إلى API key حقيقي (`OPENAI_API_KEY` أو `models.providers.openai.apiKey`). + + فقط إذا كنت تستخدم **OpenAI embeddings**. يغطي Codex OAuth الدردشة/الإكمالات + ولا **يمنح** الوصول إلى embeddings، لذا فإن **تسجيل الدخول عبر Codex (OAuth أو + تسجيل الدخول عبر Codex CLI)** لا يفيد في البحث الدلالي في الذاكرة. لا تزال OpenAI embeddings + تحتاج إلى مفتاح API حقيقي (`OPENAI_API_KEY` أو `models.providers.openai.apiKey`). - إذا لم تضبط موفرًا صراحةً، فإن OpenClaw يختار موفرًا تلقائيًا عندما - يستطيع حل API key (ملفات تعريف المصادقة، أو `models.providers.*.apiKey`، أو متغيرات البيئة). - وهو يفضّل OpenAI إذا أمكن حل مفتاح OpenAI، وإلا Gemini إذا أمكن حل مفتاح Gemini، - ثم Voyage، ثم Mistral. وإذا لم يتوفر مفتاح بعيد، فسيظل - بحث الذاكرة معطلًا حتى تقوم بتهيئته. وإذا كان لديك مسار نموذج محلي - مهيأ وموجود، فإن OpenClaw - يفضّل `local`. كما أن Ollama مدعومة عندما تضبط صراحةً + إذا لم تضبط مزودًا صراحةً، يختار OpenClaw مزودًا تلقائيًا عندما + يستطيع حل مفتاح API (ملفات تعريف المصادقة، أو `models.providers.*.apiKey`، أو متغيرات env). + ويفضّل OpenAI إذا توفّر مفتاح OpenAI، وإلا Gemini إذا توفر مفتاح Gemini، + ثم Voyage، ثم Mistral. وإذا لم يتوفر أي مفتاح بعيد، فإن بحث + الذاكرة يبقى معطّلًا حتى تضبطه. وإذا كان لديك مسار نموذج محلي + مضبوط وموجود، فإن OpenClaw + يفضّل `local`. كما أن Ollama مدعوم عندما تضبط صراحةً `memorySearch.provider = "ollama"`. - وإذا كنت تفضّل البقاء محليًا، فاضبط `memorySearch.provider = "local"` (واختياريًا + إذا كنت تفضل البقاء محليًا، فاضبط `memorySearch.provider = "local"` (واختياريًا `memorySearch.fallback = "none"`). وإذا كنت تريد Gemini embeddings، فاضبط - `memorySearch.provider = "gemini"` ووفّر `GEMINI_API_KEY` (أو + `memorySearch.provider = "gemini"` وقدّم `GEMINI_API_KEY` (أو `memorySearch.remote.apiKey`). نحن ندعم نماذج embedding من **OpenAI وGemini وVoyage وMistral وOllama أو local** - - راجع [الذاكرة](/ar/concepts/memory) للحصول على تفاصيل الإعداد. + - راجع [الذاكرة](/ar/concepts/memory) لمعرفة تفاصيل الإعداد. -## أماكن تخزين الأشياء على القرص +## مكان وجود الأشياء على القرص - لا - **حالة OpenClaw محلية**، لكن **الخدمات الخارجية ما زالت ترى ما ترسله إليها**. + لا - **حالة OpenClaw محلية**، لكن **الخدمات الخارجية لا تزال ترى ما ترسله إليها**. - - **محلية افتراضيًا:** الجلسات، وملفات الذاكرة، والإعداد، ومساحة العمل تعيش على مضيف Gateway - (`~/.openclaw` + دليل مساحة العمل الخاص بك). - - **بعيدة بحكم الضرورة:** الرسائل التي ترسلها إلى موفري النماذج (Anthropic/OpenAI/etc.) تذهب إلى - APIs الخاصة بهم، كما تخزن منصات الدردشة (WhatsApp/Telegram/Slack/etc.) بيانات الرسائل على + - **محلي افتراضيًا:** الجلسات وملفات الذاكرة والإعدادات ومساحة العمل تعيش على مضيف Gateway + (`~/.openclaw` + دليل مساحة العمل لديك). + - **بعيد بالضرورة:** الرسائل التي ترسلها إلى مزودي النماذج (Anthropic/OpenAI/إلخ) تذهب إلى + APIs الخاصة بهم، كما تخزن منصات الدردشة (WhatsApp/Telegram/Slack/إلخ) بيانات الرسائل على خوادمها. - **أنت تتحكم في الأثر:** استخدام النماذج المحلية يبقي المطالبات على جهازك، لكن - حركة القنوات لا تزال تمر عبر خوادم القناة. + حركة القناة لا تزال تمر عبر خوادم تلك القناة. ذو صلة: [مساحة عمل الوكيل](/ar/concepts/agent-workspace)، [الذاكرة](/ar/concepts/memory). @@ -1396,29 +1396,29 @@ x-i18n: | المسار | الغرض | | --------------------------------------------------------------- | ------------------------------------------------------------------ | - | `$OPENCLAW_STATE_DIR/openclaw.json` | الإعداد الرئيسي (JSON5) | + | `$OPENCLAW_STATE_DIR/openclaw.json` | الإعدادات الرئيسية (JSON5) | | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | استيراد OAuth قديم (يُنسخ إلى ملفات تعريف المصادقة عند أول استخدام) | - | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | ملفات تعريف المصادقة (OAuth، وAPI keys، و`keyRef`/`tokenRef` الاختياريان) | - | `$OPENCLAW_STATE_DIR/secrets.json` | حمولة سرية اختيارية مدعومة بملف لموفري `file` SecretRef | - | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | ملف توافق قديم (تُزال منه إدخالات `api_key` الثابتة) | - | `$OPENCLAW_STATE_DIR/credentials/` | حالة الموفر (مثل `whatsapp//creds.json`) | - | `$OPENCLAW_STATE_DIR/agents/` | حالة كل وكيل (agentDir + الجلسات) | - | `$OPENCLAW_STATE_DIR/agents//sessions/` | سجل المحادثة والحالة (لكل وكيل) | - | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | بيانات تعريف الجلسات (لكل وكيل) | + | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | ملفات تعريف المصادقة (OAuth، مفاتيح API، و`keyRef`/`tokenRef` الاختيارية) | + | `$OPENCLAW_STATE_DIR/secrets.json` | حمولة سرية اختيارية معتمدة على الملفات لمزودي `file` ضمن SecretRef | + | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | ملف توافق قديم (تُنظف منه إدخالات `api_key` الثابتة) | + | `$OPENCLAW_STATE_DIR/credentials/` | حالة المزوّد (مثل `whatsapp//creds.json`) | + | `$OPENCLAW_STATE_DIR/agents/` | حالة لكل وكيل (agentDir + sessions) | + | `$OPENCLAW_STATE_DIR/agents//sessions/` | محفوظات المحادثة والحالة (لكل وكيل) | + | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | بيانات الجلسة الوصفية (لكل وكيل) | - المسار القديم لوكيل واحد: `~/.openclaw/agent/*` (يرحّله `openclaw doctor`). + المسار القديم للوكيل الواحد: `~/.openclaw/agent/*` (يرحّله `openclaw doctor`). - أما **مساحة العمل** الخاصة بك (`AGENTS.md`، وملفات الذاكرة، وSkills، إلخ) فهي منفصلة وتُضبط عبر `agents.defaults.workspace` (الافتراضي: `~/.openclaw/workspace`). + أما **مساحة العمل** الخاصة بك (AGENTS.md، ملفات الذاكرة، Skills، إلخ) فهي منفصلة وتُضبط عبر `agents.defaults.workspace` (الافتراضي: `~/.openclaw/workspace`). - + تعيش هذه الملفات في **مساحة عمل الوكيل**، وليس في `~/.openclaw`. - - **مساحة العمل (لكل وكيل):** `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, - `MEMORY.md` (أو البديل القديم `memory.md` عند غياب `MEMORY.md`)، - `memory/YYYY-MM-DD.md`، و`HEARTBEAT.md` اختياريًا. - - **دليل الحالة (`~/.openclaw`)**: الإعداد، وحالة القنوات/الموفّرين، وملفات تعريف المصادقة، والجلسات، والسجلات، + - **مساحة العمل (لكل وكيل)**: `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, + `MEMORY.md` (أو fallback قديم `memory.md` عندما يكون `MEMORY.md` غائبًا)، + `memory/YYYY-MM-DD.md`, و`HEARTBEAT.md` اختياري. + - **دليل الحالة (`~/.openclaw`)**: الإعدادات، حالة القناة/المزوّد، ملفات تعريف المصادقة، الجلسات، السجلات، وSkills المشتركة (`~/.openclaw/skills`). مساحة العمل الافتراضية هي `~/.openclaw/workspace`، ويمكن ضبطها عبر: @@ -1429,42 +1429,42 @@ x-i18n: } ``` - إذا كان البوت "ينسى" بعد إعادة التشغيل، فتأكد من أن Gateway تستخدم - مساحة العمل نفسها في كل تشغيل (وتذكر: الوضع البعيد يستخدم **مساحة عمل مضيف gateway**، - لا مساحة عمل حاسوبك المحمول المحلي). + إذا كان bot "ينسى" بعد إعادة التشغيل، فتأكد من أن Gateway يستخدم مساحة العمل نفسها + في كل إطلاق (وتذكّر: الوضع البعيد يستخدم مساحة عمل **مضيف gateway** + وليس حاسوبك المحمول المحلي). - نصيحة: إذا أردت سلوكًا أو تفضيلًا دائمًا، فاطلب من البوت أن **يكتبه في - AGENTS.md أو MEMORY.md** بدلًا من الاعتماد على سجل الدردشة. + نصيحة: إذا كنت تريد سلوكًا دائمًا أو تفضيلًا، فاطلب من bot أن **يكتبه في + AGENTS.md أو MEMORY.md** بدلًا من الاعتماد على محفوظات الدردشة. راجع [مساحة عمل الوكيل](/ar/concepts/agent-workspace) و[الذاكرة](/ar/concepts/memory). - ضع **مساحة عمل الوكيل** في مستودع git **خاص** وانسخها احتياطيًا إلى مكان - خاص (مثل GitHub الخاص). فهذا يلتقط الذاكرة + ملفات AGENTS/SOUL/USER، - ويسمح لك باستعادة "عقل" المساعد لاحقًا. + ضع **مساحة عمل الوكيل** في مستودع git **خاص** واحتفظ بنسخة احتياطية منه في مكان + خاص (مثل GitHub الخاص). يلتقط هذا الذاكرة + ملفات AGENTS/SOUL/USER، + ويتيح لك استعادة "عقل" المساعد لاحقًا. - **لا** تقم بعمل commit لأي شيء ضمن `~/.openclaw` (بيانات الاعتماد، أو الجلسات، أو الرموز المميزة، أو حمولة الأسرار المشفرة). + **لا** تقم بعمل commit لأي شيء ضمن `~/.openclaw` (بيانات الاعتماد أو الجلسات أو الرموز أو حمولات الأسرار المشفرة). وإذا كنت تحتاج إلى استعادة كاملة، فانسخ كلًا من مساحة العمل ودليل الحالة - كلًا على حدة (راجع سؤال الترحيل أعلاه). + بشكل منفصل (راجع سؤال الترحيل أعلاه). - الوثائق: [مساحة عمل الوكيل](/ar/concepts/agent-workspace). + المستندات: [مساحة عمل الوكيل](/ar/concepts/agent-workspace). - راجع الدليل المخصص: [إلغاء التثبيت](/ar/install/uninstall). + راجع الدليل المخصص: [إزالة التثبيت](/ar/install/uninstall). - نعم. فمساحة العمل هي **cwd افتراضي** ومرساة للذاكرة، وليست sandbox صارمة. - تُحل المسارات النسبية داخل مساحة العمل، لكن المسارات المطلقة يمكنها الوصول إلى - مواقع أخرى على المضيف ما لم يكن sandboxing مفعّلًا. وإذا كنت تحتاج إلى عزل، فاستخدم + نعم. مساحة العمل هي **cwd الافتراضي** ومرساة الذاكرة، وليست sandbox صارمًا. + تُحل المسارات النسبية داخل مساحة العمل، لكن المسارات المطلقة يمكنها الوصول إلى مواقع + أخرى على المضيف ما لم يكن العزل مفعّلًا. وإذا كنت تحتاج إلى عزل، فاستخدم [`agents.defaults.sandbox`](/ar/gateway/sandboxing) أو إعدادات sandbox لكل وكيل. وإذا كنت - تريد أن يكون مستودع ما هو دليل العمل الافتراضي، فاجعل - `workspace` لذلك الوكيل تشير إلى جذر المستودع. ومستودع OpenClaw هو مجرد - شيفرة مصدر؛ فافصل مساحة العمل عنه ما لم تكن تريد عمدًا أن يعمل الوكيل داخله. + تريد أن يكون مستودع ما دليل العمل الافتراضي، فاجعل + `workspace` لذلك الوكيل يشير إلى جذر المستودع. مستودع OpenClaw هو مجرد + شيفرة مصدر؛ أبقِ مساحة العمل منفصلة ما لم تكن تريد عمدًا أن يعمل الوكيل داخله. مثال (المستودع كـ cwd افتراضي): @@ -1481,29 +1481,29 @@ x-i18n: - حالة الجلسة يملكها **مضيف gateway**. فإذا كنت في الوضع البعيد، فإن مخزن الجلسات الذي يهمك موجود على الجهاز البعيد، لا على حاسوبك المحمول المحلي. راجع [إدارة الجلسات](/ar/concepts/session). + تملك **مضيف gateway** حالة الجلسة. إذا كنت في الوضع البعيد، فإن مخزن الجلسات الذي يهمك موجود على الجهاز البعيد، لا على حاسوبك المحمول المحلي. راجع [إدارة الجلسات](/ar/concepts/session). -## أساسيات الإعداد +## أساسيات التكوين - - يقرأ OpenClaw إعداد **JSON5** اختياريًا من `$OPENCLAW_CONFIG_PATH` (الافتراضي: `~/.openclaw/openclaw.json`): + + يقرأ OpenClaw ملف إعدادات **JSON5** اختياريًا من `$OPENCLAW_CONFIG_PATH` (الافتراضي: `~/.openclaw/openclaw.json`): ``` $OPENCLAW_CONFIG_PATH ``` - وإذا كان الملف مفقودًا، فإنه يستخدم افتراضيات آمنة إلى حد ما (بما في ذلك مساحة عمل افتراضية هي `~/.openclaw/workspace`). + إذا كان الملف مفقودًا، فإنه يستخدم افتراضيات آمنة نسبيًا (بما في ذلك مساحة عمل افتراضية هي `~/.openclaw/workspace`). - - يتطلب الربط على غير loopback **مسار مصادقة صالحًا للبوابة**. وهذا يعني عمليًا: + + تتطلب عمليات الربط غير loopback **مسار مصادقة صالحًا للـ gateway**. وعمليًا يعني هذا: - - مصادقة shared-secret: رمز مميز أو كلمة مرور - - `gateway.auth.mode: "trusted-proxy"` خلف موجه عكسي مدرك للهوية مضبوط بشكل صحيح وغير loopback + - مصادقة shared-secret: token أو password + - `gateway.auth.mode: "trusted-proxy"` خلف وكيل عكسي غير loopback ومدرك للهوية ومُضبط بصورة صحيحة ```json5 { @@ -1519,32 +1519,32 @@ x-i18n: ملاحظات: - - لا يفعّل `gateway.remote.token` / `.password` مصادقة البوابة المحلية بمفردهما. - - يمكن أن تستخدم مسارات النداء المحلية `gateway.remote.*` كبديل احتياطي فقط عندما لا تكون `gateway.auth.*` مضبوطة. - - بالنسبة إلى مصادقة كلمة المرور، اضبط `gateway.auth.mode: "password"` مع `gateway.auth.password` (أو `OPENCLAW_GATEWAY_PASSWORD`) بدلًا من ذلك. - - إذا كانت `gateway.auth.token` / `gateway.auth.password` مهيأة صراحةً عبر SecretRef ولم يمكن حلها، فإن الحل يفشل بشكل مغلق (من دون بديل بعيد يُخفي ذلك). - - تتم مصادقة إعدادات Control UI باستخدام `connect.params.auth.token` أو `connect.params.auth.password` (مخزنة في إعدادات التطبيق/الواجهة). أما أوضاع حمل الهوية مثل Tailscale Serve أو `trusted-proxy` فتستخدم رؤوس الطلبات بدلًا من ذلك. وتجنب وضع shared secrets في عناوين URL. - - مع `gateway.auth.mode: "trusted-proxy"`، فإن الموجهات العكسية loopback على المضيف نفسه لا تفي أيضًا بمصادقة trusted-proxy. بل يجب أن يكون الموجه الموثوق مصدرًا غير loopback ومهيأً. + - `gateway.remote.token` / `.password` **لا** يفعّلان مصادقة gateway المحلية بمفردهما. + - يمكن للمسارات المحلية استخدام `gateway.remote.*` كـ fallback فقط عندما تكون `gateway.auth.*` غير مضبوطة. + - بالنسبة إلى مصادقة password، اضبط `gateway.auth.mode: "password"` مع `gateway.auth.password` (أو `OPENCLAW_GATEWAY_PASSWORD`) بدلًا من ذلك. + - إذا كانت `gateway.auth.token` / `gateway.auth.password` مضبوطة صراحةً عبر SecretRef وغير محلولة، فإن الحل يفشل بشكل مغلق (من دون fallback بعيد يخفي المشكلة). + - تتم مصادقة إعدادات Control UI المعتمدة على shared-secret عبر `connect.params.auth.token` أو `connect.params.auth.password` (المخزنين في إعدادات التطبيق/UI). أما الأوضاع المعتمدة على الهوية مثل Tailscale Serve أو `trusted-proxy` فتستخدم رؤوس الطلبات بدلًا من ذلك. تجنب وضع shared secrets في عناوين URL. + - مع `gateway.auth.mode: "trusted-proxy"`، فإن الوكلاء العكسيين على loopback ضمن المضيف نفسه **لا** يفون بمصادقة trusted-proxy. يجب أن يكون trusted proxy مصدرًا غير loopback ومُضبطًا. - - يفرض OpenClaw مصادقة البوابة افتراضيًا، بما في ذلك loopback. وفي المسار الافتراضي المعتاد يعني هذا مصادقة عبر الرمز المميز: فإذا لم يكن هناك مسار مصادقة صريح مهيأ، فإن بدء تشغيل البوابة يحل إلى وضع token ويولّد واحدًا تلقائيًا ويخزنه في `gateway.auth.token`، لذا **يجب على عملاء WS المحليين المصادقة**. وهذا يمنع العمليات المحلية الأخرى من استدعاء Gateway. + + يفرض OpenClaw مصادقة gateway افتراضيًا، بما في ذلك loopback. في المسار الافتراضي العادي يعني هذا مصادقة token: إذا لم يُضبط مسار مصادقة صريح، فإن بدء تشغيل gateway يُحل إلى وضع token ويُنشئ واحدًا تلقائيًا، مع حفظه في `gateway.auth.token`، لذا **يجب على عملاء WS المحليين المصادقة**. هذا يمنع العمليات المحلية الأخرى من استدعاء Gateway. - وإذا كنت تفضّل مسار مصادقة مختلفًا، فيمكنك اختيار وضع كلمة المرور صراحةً (أو، بالنسبة إلى الموجهات العكسية غير loopback والمدركة للهوية، `trusted-proxy`). وإذا **كنت حقًا** تريد loopback مفتوحة، فاضبط `gateway.auth.mode: "none"` صراحةً في إعدادك. ويمكن لـ Doctor أن يولد لك رمزًا مميزًا في أي وقت: `openclaw doctor --generate-gateway-token`. + إذا كنت تفضل مسار مصادقة مختلفًا، فيمكنك اختيار وضع password صراحةً (أو، بالنسبة إلى الوكلاء العكسيين غير loopback والمدركين للهوية، `trusted-proxy`). وإذا **أردت حقًا** loopback مفتوحًا، فاضبط `gateway.auth.mode: "none"` صراحةً في إعداداتك. ويمكن لـ Doctor إنشاء token لك في أي وقت: `openclaw doctor --generate-gateway-token`. - - تراقب Gateway الإعداد وتدعم إعادة التحميل الساخنة: + + يراقب Gateway الإعدادات ويدعم hot-reload: - - `gateway.reload.mode: "hybrid"` (الافتراضي): يطبق التغييرات الآمنة مباشرة، ويعيد التشغيل للتغييرات الحرجة + - `gateway.reload.mode: "hybrid"` (الافتراضي): يطبّق التغييرات الآمنة مباشرةً، ويعيد التشغيل للتغييرات الحرجة - كما أن `hot` و`restart` و`off` مدعومة أيضًا - اضبط `cli.banner.taglineMode` في الإعداد: + اضبط `cli.banner.taglineMode` في الإعدادات: ```json5 { @@ -1556,24 +1556,24 @@ x-i18n: } ``` - - `off`: يُخفي نص الشعار مع إبقاء سطر عنوان الشعار/الإصدار. + - `off`: يُخفي نص الشعار لكنه يُبقي سطر عنوان البانر/الإصدار. - `default`: يستخدم `All your chats, one OpenClaw.` في كل مرة. - - `random`: شعارات طريفة/موسمية متعاقبة (السلوك الافتراضي). - - وإذا كنت لا تريد أي شعار إطلاقًا، فاضبط متغير البيئة `OPENCLAW_HIDE_BANNER=1`. + - `random`: شعارات طريفة/موسمية متناوبة (السلوك الافتراضي). + - إذا أردت عدم وجود بانر مطلقًا، فاضبط env `OPENCLAW_HIDE_BANNER=1`. - تعمل `web_fetch` من دون API key. أما `web_search` فتعتمد على - الموفر الذي اخترته: + يعمل `web_fetch` من دون مفتاح API. أما `web_search` فيعتمد على + المزوّد الذي اخترته: - - يتطلب الموفّرون المدعومون عبر API مثل Brave وExa وFirecrawl وGemini وGrok وKimi وMiniMax Search وPerplexity وTavily إعداد API key المعتاد لديهم. - - Ollama Web Search لا يحتاج إلى مفتاح، لكنه يستخدم مضيف Ollama المهيأ لديك ويتطلب `ollama signin`. + - تتطلب المزوّدات المعتمدة على API مثل Brave وExa وFirecrawl وGemini وGrok وKimi وMiniMax Search وPerplexity وTavily إعداد مفتاح API المعتاد الخاص بها. + - Ollama Web Search لا يحتاج إلى مفتاح، لكنه يستخدم مضيف Ollama الذي قمت بتكوينه ويتطلب `ollama signin`. - DuckDuckGo لا يحتاج إلى مفتاح، لكنه تكامل غير رسمي قائم على HTML. - - SearXNG لا يحتاج إلى مفتاح/ويصلح للاستضافة الذاتية؛ اضبط `SEARXNG_BASE_URL` أو `plugins.entries.searxng.config.webSearch.baseUrl`. + - SearXNG لا يحتاج إلى مفتاح/ويمكن استضافته ذاتيًا؛ اضبط `SEARXNG_BASE_URL` أو `plugins.entries.searxng.config.webSearch.baseUrl`. - **الموصى به:** شغّل `openclaw configure --section web` واختر موفرًا. - بدائل متغيرات البيئة: + **موصى به:** شغّل `openclaw configure --section web` واختر مزودًا. + بدائل البيئة: - Brave: `BRAVE_API_KEY` - Exa: `EXA_API_KEY` @@ -1608,65 +1608,65 @@ x-i18n: }, fetch: { enabled: true, - provider: "firecrawl", // اختياري؛ احذفه للكشف التلقائي + provider: "firecrawl", // اختياري؛ اتركه للكشف التلقائي }, }, }, } ``` - يعيش الآن إعداد web-search الخاص بكل موفر تحت `plugins.entries..config.webSearch.*`. - وما زالت مسارات الموفر القديمة `tools.web.search.*` تُحمّل مؤقتًا للتوافق، لكن لا ينبغي استخدامها في الإعدادات الجديدة. - يعيش إعداد fallback الخاص بـ Firecrawl web-fetch تحت `plugins.entries.firecrawl.config.webFetch.*`. + تعيش إعدادات web-search الخاصة بكل مزوّد الآن تحت `plugins.entries..config.webSearch.*`. + ولا تزال مسارات المزوّد القديمة `tools.web.search.*` تُحمَّل مؤقتًا من أجل التوافق، لكن لا ينبغي استخدامها في الإعدادات الجديدة. + تعيش إعدادات fallback الخاصة بـ Firecrawl web-fetch تحت `plugins.entries.firecrawl.config.webFetch.*`. ملاحظات: - - إذا كنت تستخدم قوائم السماح، فأضف `web_search`/`web_fetch`/`x_search` أو `group:web`. - - تكون `web_fetch` مفعلة افتراضيًا (ما لم تُعطل صراحةً). - - إذا تم حذف `tools.web.fetch.provider`، فإن OpenClaw يكتشف تلقائيًا أول موفر fetch احتياطي جاهز من بيانات الاعتماد المتاحة. والموفر المجمّع اليوم هو Firecrawl. - - تقرأ الخدمات متغيرات البيئة من `~/.openclaw/.env` (أو من بيئة الخدمة). + - إذا كنت تستخدم allowlists، فأضف `web_search`/`web_fetch`/`x_search` أو `group:web`. + - `web_fetch` مفعّلة افتراضيًا (ما لم تُعطَّل صراحةً). + - إذا تُرك `tools.web.fetch.provider` من دون ضبط، فسيكتشف OpenClaw تلقائيًا أول مزوّد fallback جاهز للجلب من بين بيانات الاعتماد المتاحة. المزوّد المضمّن اليوم هو Firecrawl. + - تقرأ daemons متغيرات env من `~/.openclaw/.env` (أو من بيئة الخدمة). - الوثائق: [أدوات الويب](/ar/tools/web). + المستندات: [أدوات الويب](/ar/tools/web). - - يقوم `config.apply` باستبدال **الإعداد بالكامل**. فإذا أرسلت كائنًا جزئيًا، فسيُزال + + يقوم `config.apply` باستبدال **الإعدادات بالكامل**. إذا أرسلت كائنًا جزئيًا، فسيُزال كل شيء آخر. الاستعادة: - استعد من نسخة احتياطية (git أو نسخة من `~/.openclaw/openclaw.json`). - - إذا لم تكن لديك نسخة احتياطية، فأعد تشغيل `openclaw doctor` وأعد تهيئة channels/models. - - إذا كان هذا غير متوقع، فافتح تقرير خطأ وأرفق آخر إعداد معروف أو أي نسخة احتياطية. - - يمكن لوكيل برمجة محلي غالبًا إعادة بناء إعداد صالح من السجلات أو السجل التاريخي. + - إذا لم تكن لديك نسخة احتياطية، فأعد تشغيل `openclaw doctor` وأعد تهيئة القنوات/النماذج. + - إذا كان هذا غير متوقع، فافتح تقرير خطأ وأدرج آخر إعدادات معروفة لديك أو أي نسخة احتياطية. + - غالبًا ما يستطيع وكيل برمجة محلي إعادة بناء إعدادات صالحة من السجلات أو المحفوظات. - لتجنب ذلك: + تجنّب ذلك: - استخدم `openclaw config set` للتغييرات الصغيرة. - - استخدم `openclaw configure` للتحرير التفاعلي. - - استخدم `config.schema.lookup` أولًا عندما لا تكون متأكدًا من المسار الدقيق أو شكل الحقل؛ فهو يعيد عقدة schema سطحية مع ملخصات الأبناء المباشرين للتدرج. - - استخدم `config.patch` للتحرير الجزئي عبر RPC؛ واحتفظ بـ `config.apply` لاستبدال الإعداد الكامل فقط. - - إذا كنت تستخدم أداة `gateway` المخصصة للمالك فقط من داخل تشغيل الوكيل، فستظل ترفض الكتابة إلى `tools.exec.ask` / `tools.exec.security` (بما في ذلك الأسماء القديمة `tools.bash.*` التي تُطبّع إلى مسارات exec المحمية نفسها). + - استخدم `openclaw configure` للتعديلات التفاعلية. + - استخدم `config.schema.lookup` أولًا عندما لا تكون متأكدًا من المسار الدقيق أو شكل الحقل؛ فهو يعيد عقدة schema سطحية مع ملخصات الأبناء المباشرين للتعمق. + - استخدم `config.patch` لتعديلات RPC الجزئية؛ واحتفظ بـ `config.apply` فقط لاستبدال الإعدادات كاملةً. + - إذا كنت تستخدم أداة `gateway` المخصصة للمالك فقط من داخل تشغيل وكيل، فستظل ترفض الكتابات إلى `tools.exec.ask` / `tools.exec.security` (بما في ذلك أسماء `tools.bash.*` القديمة التي تُطبّع إلى المسارات التنفيذية المحمية نفسها). - الوثائق: [الإعداد](/cli/config)، [التكوين](/cli/configure)، [Doctor](/ar/gateway/doctor). + المستندات: [الإعدادات](/cli/config)، [Configure](/cli/configure)، [Doctor](/ar/gateway/doctor). - النمط الشائع هو **Gateway واحدة** (مثل Raspberry Pi) مع **nodes** و**agents**: + النمط الشائع هو **Gateway واحدة** (مثل Raspberry Pi) بالإضافة إلى **nodes** و**agents**: - **Gateway (مركزية):** تملك القنوات (Signal/WhatsApp)، والتوجيه، والجلسات. - - **Nodes (الأجهزة):** تتصل أجهزة Mac/iOS/Android كأجهزة طرفية وتعرض أدوات محلية (`system.run`, `canvas`, `camera`). - - **Agents (العمال):** عقول/مساحات عمل منفصلة لأدوار متخصصة (مثل "عمليات Hetzner" أو "بيانات شخصية"). - - **الوكلاء الفرعيون:** ينشئون عملًا في الخلفية من وكيل رئيسي عندما تريد التوازي. - - **TUI:** يتصل بـ Gateway ويبدّل بين الوكلاء/الجلسات. + - **Nodes (الأجهزة):** تتصل أجهزة Mac/iOS/Android كأجهزة طرفية وتكشف الأدوات المحلية (`system.run`, `canvas`, `camera`). + - **Agents (العمال):** عقول/مساحات عمل منفصلة لأدوار خاصة (مثل "عمليات Hetzner"، "البيانات الشخصية"). + - **Sub-agents:** أنشئ عملًا في الخلفية من وكيل رئيسي عندما تريد التوازي. + - **TUI:** اتصل بـ Gateway وبدّل بين الوكلاء/الجلسات. - الوثائق: [Nodes](/ar/nodes)، [الوصول البعيد](/ar/gateway/remote)، [التوجيه متعدد الوكلاء](/ar/concepts/multi-agent)، [الوكلاء الفرعيون](/ar/tools/subagents)، [TUI](/web/tui). + المستندات: [Nodes](/ar/nodes)، [الوصول البعيد](/ar/gateway/remote)، [التوجيه متعدد الوكلاء](/ar/concepts/multi-agent)، [Sub-agents](/ar/tools/subagents)، [TUI](/web/tui). - + نعم. إنه خيار إعداد: ```json5 @@ -1680,46 +1680,46 @@ x-i18n: } ``` - القيمة الافتراضية هي `false` ‏(headful). ويزيد headless احتمال تفعيل فحوصات مكافحة الروبوتات في بعض المواقع. راجع [المتصفح](/ar/tools/browser). + القيمة الافتراضية هي `false` (مرئي). ويكون الوضع headless أكثر عرضة لإثارة فحوصات مكافحة الروبوت على بعض المواقع. راجع [المتصفح](/ar/tools/browser). - يستخدم headless **محرك Chromium نفسه** ويعمل مع معظم الأتمتة (النماذج، والنقرات، والاستخراج، وتسجيلات الدخول). والفروقات الأساسية: + يستخدم الوضع headless **محرك Chromium نفسه** ويعمل مع معظم الأتمتة (النماذج، النقرات، الاستخراج، تسجيلات الدخول). والفروق الأساسية هي: - - لا توجد نافذة متصفح مرئية (استخدم لقطات الشاشة إذا كنت بحاجة إلى عناصر بصرية). - - بعض المواقع أكثر تشددًا مع الأتمتة في وضع headless (CAPTCHAs، مكافحة الروبوتات). - فمثلًا، يقوم X/Twitter كثيرًا بحظر الجلسات headless. + - لا توجد نافذة متصفح مرئية (استخدم لقطات الشاشة إذا كنت تحتاج إلى مرئيات). + - بعض المواقع أكثر تشددًا تجاه الأتمتة في وضع headless (CAPTCHAs، مكافحة الروبوت). + مثلًا، غالبًا ما يحظر X/Twitter الجلسات headless. - اضبط `browser.executablePath` على ثنائي Brave لديك (أو أي متصفح آخر مبني على Chromium) ثم أعد تشغيل Gateway. - راجع أمثلة الإعداد الكاملة في [المتصفح](/ar/tools/browser#use-brave-or-another-chromium-based-browser). + اضبط `browser.executablePath` على ثنائي Brave لديك (أو أي متصفح قائم على Chromium) ثم أعد تشغيل Gateway. + راجع أمثلة الإعدادات الكاملة في [المتصفح](/ar/tools/browser#use-brave-or-another-chromium-based-browser). -## البوابات البعيدة وnodes +## Gateways البعيدة وnodes - تتم معالجة رسائل Telegram بواسطة **gateway**. وتشغّل gateway الوكيل - وبعد ذلك فقط تستدعي nodes عبر **Gateway WebSocket** عندما تكون هناك حاجة إلى أداة node: + تتم معالجة رسائل Telegram بواسطة **gateway**. تقوم gateway بتشغيل الوكيل + وعندها فقط تستدعي nodes عبر **Gateway WebSocket** عند الحاجة إلى أداة node: Telegram → Gateway → Agent → `node.*` → Node → Gateway → Telegram - لا ترى nodes حركة المرور الواردة من الموفّر؛ فهي تستقبل فقط نداءات node RPC. + لا ترى Nodes حركة المرور الواردة من المزوّد؛ بل تتلقى فقط استدعاءات node RPC. - - الإجابة المختصرة: **أقرِن حاسوبك بوصفه node**. تعمل Gateway في مكان آخر، لكنها تستطيع - استدعاء أدوات `node.*` ‏(الشاشة، والكاميرا، والنظام) على جهازك المحلي عبر Gateway WebSocket. + + الإجابة المختصرة: **اقرن جهازك كـ node**. تعمل Gateway في مكان آخر، لكنها تستطيع + استدعاء أدوات `node.*` (screen وcamera وsystem) على جهازك المحلي عبر Gateway WebSocket. إعداد نموذجي: - 1. شغّل Gateway على المضيف دائم التشغيل (VPS/خادم منزلي). - 2. ضع مضيف Gateway + حاسوبك على tailnet نفسها. - 3. تأكد من أن WS الخاص بـ Gateway قابل للوصول (ربط tailnet أو نفق SSH). + 1. شغّل Gateway على المضيف الذي يعمل دائمًا (VPS/خادم منزلي). + 2. ضع مضيف Gateway + جهازك على tailnet نفسها. + 3. تأكد من إمكانية الوصول إلى Gateway WS (ربط tailnet أو نفق SSH). 4. افتح تطبيق macOS محليًا واتصل في وضع **Remote over SSH** (أو tailnet مباشر) - حتى يستطيع التسجيل بوصفه node. + حتى يتمكن من التسجيل كـ node. 5. وافق على node على Gateway: ```bash @@ -1729,40 +1729,40 @@ x-i18n: لا يلزم أي جسر TCP منفصل؛ إذ تتصل nodes عبر Gateway WebSocket. - تذكير أمني: إقران macOS node يتيح `system.run` على ذلك الجهاز. ولا + تذكير أمني: إقران node macOS يسمح بـ `system.run` على ذلك الجهاز. لا تقرن إلا الأجهزة التي تثق بها، وراجع [الأمان](/ar/gateway/security). - الوثائق: [Nodes](/ar/nodes)، [بروتوكول Gateway](/ar/gateway/protocol)، [الوضع البعيد على macOS](/ar/platforms/mac/remote)، [الأمان](/ar/gateway/security). + المستندات: [Nodes](/ar/nodes)، [بروتوكول Gateway](/ar/gateway/protocol)، [الوضع البعيد في macOS](/ar/platforms/mac/remote)، [الأمان](/ar/gateway/security). تحقق من الأساسيات: - - تعمل Gateway: ‏`openclaw gateway status` - - صحة Gateway: ‏`openclaw status` - - صحة القناة: ‏`openclaw channels status` + - Gateway تعمل: `openclaw gateway status` + - صحة Gateway: `openclaw status` + - صحة القنوات: `openclaw channels status` ثم تحقق من المصادقة والتوجيه: - - إذا كنت تستخدم Tailscale Serve، فتأكد من أن `gateway.auth.allowTailscale` مضبوطة بشكل صحيح. - - إذا كنت تتصل عبر نفق SSH، فتأكد من أن النفق المحلي يعمل ويشير إلى المنفذ الصحيح. - - تأكد من أن قوائم السماح لديك (DM أو group) تتضمن حسابك. + - إذا كنت تستخدم Tailscale Serve، فتأكد من ضبط `gateway.auth.allowTailscale` بشكل صحيح. + - إذا كنت تتصل عبر نفق SSH، فتأكد من أن النفق المحلي قائم ويشير إلى المنفذ الصحيح. + - تأكد من أن allowlists لديك (DM أو group) تتضمن حسابك. - الوثائق: [Tailscale](/ar/gateway/tailscale)، [الوصول البعيد](/ar/gateway/remote)، [القنوات](/ar/channels). + المستندات: [Tailscale](/ar/gateway/tailscale)، [الوصول البعيد](/ar/gateway/remote)، [القنوات](/ar/channels). - + نعم. لا يوجد جسر "bot-to-bot" مدمج، لكن يمكنك توصيل ذلك بعدة طرق موثوقة: - **الأبسط:** استخدم قناة دردشة عادية يمكن لكلا البوتين الوصول إليها (Telegram/Slack/WhatsApp). + **الأبسط:** استخدم قناة دردشة عادية يستطيع botان الوصول إليها (Telegram/Slack/WhatsApp). اجعل Bot A يرسل رسالة إلى Bot B، ثم دع Bot B يرد كالمعتاد. - **جسر CLI (عام):** شغّل نصًا برمجيًا يستدعي Gateway الأخرى باستخدام - `openclaw agent --message ... --deliver`، مستهدفًا دردشة يستمع فيها البوت الآخر. - وإذا كان أحد البوتين على VPS بعيد، فاجعل CLI الخاص بك يشير إلى تلك Gateway البعيدة + **جسر CLI (عام):** شغّل نصًا يستدعي Gateway الأخرى باستخدام + `openclaw agent --message ... --deliver`، مستهدفًا دردشة يصغي فيها bot + الآخر. وإذا كان أحد botين على VPS بعيد، فاجعل CLI لديك يشير إلى تلك Gateway البعيدة عبر SSH/Tailscale (راجع [الوصول البعيد](/ar/gateway/remote)). نمط مثال (شغّله من جهاز يستطيع الوصول إلى Gateway المستهدفة): @@ -1771,63 +1771,63 @@ x-i18n: openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to ``` - نصيحة: أضف حاجزًا حتى لا يدور البوتان في حلقة بلا نهاية (الرد عند الإشارة فقط، أو - قوائم سماح القنوات، أو قاعدة "لا ترد على رسائل البوتات"). + نصيحة: أضف حاجزًا يمنع botين من الدخول في حلقة لا نهائية (رد عند الذكر فقط، + أو allowlists للقناة، أو قاعدة "لا ترد على رسائل bot"). - الوثائق: [الوصول البعيد](/ar/gateway/remote)، [CLI الخاص بالوكيل](/cli/agent)، [إرسال الوكيل](/ar/tools/agent-send). + المستندات: [الوصول البعيد](/ar/gateway/remote)، [CLI الخاص بـ Agent](/cli/agent)، [إرسال Agent](/ar/tools/agent-send). - لا. يمكن لـ Gateway واحدة استضافة عدة وكلاء، لكل منهم مساحة عمله وافتراضيات نموذجه - وتوجيهه الخاص. وهذا هو الإعداد المعتاد، وهو أرخص وأبسط بكثير من تشغيل - VPS واحد لكل وكيل. + لا. يمكن لـ Gateway واحدة استضافة عدة وكلاء، لكل منهم مساحة عمله، وافتراضيات نماذجه، + وتوجيهه. هذا هو الإعداد الطبيعي وهو أرخص بكثير وأبسط من تشغيل + VPS واحدة لكل وكيل. - استخدم VPSes منفصلة فقط عندما تحتاج إلى عزل صارم (حدود أمان) أو إلى - إعدادات مختلفة جدًا لا تريد مشاركتها. وإلا فاحتفظ بـ Gateway واحدة - واستخدم عدة وكلاء أو وكلاء فرعيين. + استخدم VPS منفصلة فقط عندما تحتاج إلى عزل صارم (حدود أمان) أو + إعدادات مختلفة جدًا لا تريد مشاركتها. بخلاف ذلك، أبقِ Gateway واحدة + واستخدم عدة وكلاء أو sub-agents. نعم - تُعد nodes الطريقة الأساسية للوصول إلى حاسوبك المحمول من Gateway بعيدة، وهي - تفتح أكثر من مجرد وصول إلى shell. تعمل Gateway على macOS/Linux ‏(وعلى Windows عبر WSL2) وهي - خفيفة الوزن (يكفي VPS صغير أو جهاز من فئة Raspberry Pi؛ و4 GB RAM أكثر من كافية)، لذا فإن - الإعداد الشائع هو مضيف دائم التشغيل + حاسوبك المحمول بوصفه node. + تفتح أكثر من مجرد وصول shell. تعمل Gateway على macOS/Linux (وWindows عبر WSL2) وهي + خفيفة (يكفي VPS صغير أو جهاز من فئة Raspberry Pi؛ و4 GB RAM أكثر من كافٍ)، لذا من الشائع + إعداد مضيف يعمل دائمًا مع حاسوبك المحمول كـ node. - - **لا حاجة إلى SSH inbound.** تتصل nodes خارجيًا إلى Gateway WebSocket وتستخدم إقران الأجهزة. - - **عناصر تحكم تنفيذ أكثر أمانًا.** يخضع `system.run` لقوائم السماح/الموافقات الخاصة بـ node على ذلك الحاسوب المحمول. - - **أدوات أجهزة أكثر.** تعرض nodes كلًا من `canvas` و`camera` و`screen` بالإضافة إلى `system.run`. + - **لا حاجة إلى SSH وارد.** تتصل nodes خارجيًا إلى Gateway WebSocket وتستخدم إقران الأجهزة. + - **ضوابط تنفيذ أكثر أمانًا.** يتم تقييد `system.run` بقوائم السماح/الموافقات الخاصة بـ node على ذلك الحاسوب المحمول. + - **مزيد من أدوات الجهاز.** تكشف nodes عن `canvas` و`camera` و`screen` إضافةً إلى `system.run`. - **أتمتة متصفح محلية.** أبقِ Gateway على VPS، لكن شغّل Chrome محليًا عبر مضيف node على الحاسوب المحمول، أو اتصل بـ Chrome المحلي على المضيف عبر Chrome MCP. - SSH جيد للوصول المؤقت إلى shell، لكن nodes أبسط لسير العمل المستمر للوكلاء + لا بأس باستخدام SSH للوصول الصدفي إلى shell، لكن nodes أبسط لسير عمل الوكلاء المستمر وأتمتة الأجهزة. - الوثائق: [Nodes](/ar/nodes)، [CLI الخاص بـ Nodes](/cli/nodes)، [المتصفح](/ar/tools/browser). + المستندات: [Nodes](/ar/nodes)، [CLI الخاص بـ Nodes](/cli/nodes)، [المتصفح](/ar/tools/browser). - لا. يجب أن تعمل **بوابة واحدة** فقط لكل مضيف ما لم تكن تشغّل عمدًا ملفات تعريف معزولة (راجع [بوابات متعددة](/ar/gateway/multiple-gateways)). وnodes أجهزة طرفية تتصل - بالبوابة (nodes على iOS/Android، أو "وضع node" في تطبيق شريط القوائم على macOS). أما بالنسبة إلى - مضيفي node عديمي الواجهة والتحكم عبر CLI، فراجع [CLI الخاص بمضيف node](/cli/node). + لا. يجب أن تعمل **gateway واحدة** فقط لكل مضيف ما لم تكن تشغّل ملفات تعريف معزولة عمدًا (راجع [Gateways متعددة](/ar/gateway/multiple-gateways)). Nodes هي أجهزة طرفية تتصل + بالـ gateway (عقد iOS/Android، أو "وضع node" في تطبيق شريط القوائم على macOS). وبالنسبة إلى + مضيفات node headless والتحكم عبر CLI، راجع [CLI الخاص بمضيف Node](/cli/node). يلزم إعادة تشغيل كاملة لتغييرات `gateway` و`discovery` و`canvasHost`. - + نعم. - - `config.schema.lookup`: فحص شجرة إعداد فرعية واحدة مع عقدة schema سطحية، وتلميح UI المطابق، وملخصات الأبناء المباشرين قبل الكتابة - - `config.get`: جلب اللقطة الحالية + hash - - `config.patch`: تحديث جزئي آمن (مفضل لمعظم عمليات تحرير RPC) - - `config.apply`: تحقق + استبدال الإعداد الكامل، ثم إعادة تشغيل - - لا تزال أداة runtime `gateway` المخصصة للمالك فقط ترفض إعادة كتابة `tools.exec.ask` / `tools.exec.security`؛ وتُطبَّع الأسماء القديمة `tools.bash.*` إلى مسارات exec المحمية نفسها + - `config.schema.lookup`: افحص شجرة إعدادات فرعية واحدة مع عقدة schema سطحية وتلميح UI مطابق وملخصات الأبناء المباشرين قبل الكتابة + - `config.get`: اجلب اللقطة الحالية + hash + - `config.patch`: تحديث جزئي آمن (المفضل لمعظم تعديلات RPC)؛ يقوم بـ hot-reload عند الإمكان ويعيد التشغيل عند الحاجة + - `config.apply`: يتحقق من الصلاحية + يستبدل الإعدادات كاملةً؛ يقوم بـ hot-reload عند الإمكان ويعيد التشغيل عند الحاجة + - لا تزال أداة وقت التشغيل `gateway` المخصصة للمالك فقط ترفض إعادة كتابة `tools.exec.ask` / `tools.exec.security`؛ كما تُطبّع أسماء `tools.bash.*` القديمة إلى مسارات exec المحمية نفسها - + ```json5 { agents: { defaults: { workspace: "~/.openclaw/workspace" } }, @@ -1835,27 +1835,27 @@ x-i18n: } ``` - يضبط هذا مساحة العمل لديك ويقيّد من يمكنه تشغيل البوت. + يضبط هذا مساحة العمل لديك ويقيّد من يمكنه تشغيل bot. - - خطوات دنيا: + + الحد الأدنى من الخطوات: - 1. **ثبّت وسجل الدخول على VPS** + 1. **ثبّت + سجّل الدخول على VPS** ```bash curl -fsSL https://tailscale.com/install.sh | sh sudo tailscale up ``` - 2. **ثبّت وسجل الدخول على جهاز Mac** - - استخدم تطبيق Tailscale وسجل الدخول إلى tailnet نفسها. + 2. **ثبّت + سجّل الدخول على Mac** + - استخدم تطبيق Tailscale وسجّل الدخول إلى tailnet نفسها. 3. **فعّل MagicDNS (موصى به)** - - في وحدة تحكم إدارة Tailscale، فعّل MagicDNS حتى يحصل VPS على اسم ثابت. + - في وحدة إدارة Tailscale، فعّل MagicDNS بحيث يكون لـ VPS اسم ثابت. 4. **استخدم اسم مضيف tailnet** - - SSH: ‏`ssh user@your-vps.tailnet-xxxx.ts.net` - - Gateway WS: ‏`ws://your-vps.tailnet-xxxx.ts.net:18789` + - SSH: `ssh user@your-vps.tailnet-xxxx.ts.net` + - Gateway WS: `ws://your-vps.tailnet-xxxx.ts.net:18789` إذا كنت تريد Control UI من دون SSH، فاستخدم Tailscale Serve على VPS: @@ -1863,18 +1863,18 @@ x-i18n: openclaw gateway --tailscale serve ``` - هذا يبقي gateway مربوطة على loopback ويكشف HTTPS عبر Tailscale. راجع [Tailscale](/ar/gateway/tailscale). + يُبقي هذا gateway مرتبطة بـ loopback ويكشف HTTPS عبر Tailscale. راجع [Tailscale](/ar/gateway/tailscale). - - يكشف Serve كلًا من **Control UI + WS الخاصين بـ Gateway**. وتتصل nodes عبر نقطة نهاية Gateway WS نفسها. + + يكشف Serve **Gateway Control UI + WS**. وتتصل nodes عبر نقطة نهاية Gateway WS نفسها. الإعداد الموصى به: 1. **تأكد من أن VPS + Mac على tailnet نفسها**. - 2. **استخدم تطبيق macOS في وضع Remote** (يمكن أن يكون هدف SSH هو اسم مضيف tailnet). - سيقوم التطبيق بعمل نفق لمنفذ Gateway ويتصل بوصفه node. + 2. **استخدم تطبيق macOS في الوضع البعيد** (يمكن أن يكون هدف SSH هو اسم مضيف tailnet). + سيقوم التطبيق بعمل tunnel لمنفذ Gateway والاتصال كـ node. 3. **وافق على node** على gateway: ```bash @@ -1882,34 +1882,34 @@ x-i18n: openclaw devices approve ``` - الوثائق: [بروتوكول Gateway](/ar/gateway/protocol)، [Discovery](/ar/gateway/discovery)، [الوضع البعيد على macOS](/ar/platforms/mac/remote). + المستندات: [بروتوكول Gateway](/ar/gateway/protocol)، [Discovery](/ar/gateway/discovery)، [الوضع البعيد في macOS](/ar/platforms/mac/remote). - إذا كنت تحتاج فقط إلى **أدوات محلية** ‏(الشاشة/الكاميرا/exec) على الحاسوب المحمول الثاني، فأضفه بوصفه - **node**. فهذا يبقي Gateway واحدة ويتجنب تكرار الإعداد. وأدوات node المحلية - حاليًا خاصة بـ macOS فقط، لكننا نخطط لتوسيعها إلى أنظمة تشغيل أخرى. + إذا كنت تحتاج فقط إلى **أدوات محلية** (screen/camera/exec) على الحاسوب المحمول الثاني، فأضفه كـ + **node**. يحافظ ذلك على Gateway واحدة ويتجنب تكرار الإعدادات. أدوات node المحلية + خاصة بـ macOS حاليًا، لكننا نخطط لتوسيعها إلى أنظمة تشغيل أخرى. - لا تثبّت Gateway ثانية إلا عندما تحتاج إلى **عزل صارم** أو إلى بوتين منفصلين بالكامل. + ثبّت Gateway ثانية فقط عندما تحتاج إلى **عزل صارم** أو botين منفصلين تمامًا. - الوثائق: [Nodes](/ar/nodes)، [CLI الخاص بـ Nodes](/cli/nodes)، [بوابات متعددة](/ar/gateway/multiple-gateways). + المستندات: [Nodes](/ar/nodes)، [CLI الخاص بـ Nodes](/cli/nodes)، [Gateways متعددة](/ar/gateway/multiple-gateways). -## متغيرات البيئة وتحميل .env +## متغيرات env وتحميل .env - يقرأ OpenClaw متغيرات البيئة من العملية الأب (shell، أو launchd/systemd، أو CI، إلخ)، ويحمّل أيضًا: + يقرأ OpenClaw متغيرات env من العملية الأب (shell أو launchd/systemd أو CI، إلخ) ويحمّل أيضًا: - `.env` من دليل العمل الحالي - - `.env` عالمية احتياطية من `~/.openclaw/.env` ‏(أي `$OPENCLAW_STATE_DIR/.env`) + - ملف `.env` احتياطي عالمي من `~/.openclaw/.env` (المعروف أيضًا باسم `$OPENCLAW_STATE_DIR/.env`) - لا يقوم أي من ملفي `.env` بتجاوز متغيرات البيئة الموجودة أصلًا. + لا يقوم أي من ملفي `.env` بتجاوز متغيرات env الموجودة أصلًا. - يمكنك أيضًا تعريف متغيرات بيئة داخلية في الإعداد (تُطبق فقط إذا كانت مفقودة من بيئة العملية): + يمكنك أيضًا تعريف متغيرات env مضمنة في الإعدادات (تُطبَّق فقط إذا كانت مفقودة من process env): ```json5 { @@ -1920,15 +1920,15 @@ x-i18n: } ``` - راجع [/environment](/ar/help/environment) للاطلاع على الأولوية الكاملة والمصادر. + راجع [/environment](/ar/help/environment) لمعرفة الأولوية والمصادر بالكامل. - - إصلاحان شائعان: + + هناك إصلاحان شائعان: - 1. ضع المفاتيح المفقودة في `~/.openclaw/.env` حتى يتم التقاطها حتى عندما لا ترث الخدمة بيئة shell الخاصة بك. - 2. فعّل استيراد shell ‏(تسهيل اختياري): + 1. ضع المفاتيح المفقودة في `~/.openclaw/.env` حتى تُلتقط حتى عندما لا ترث الخدمة بيئة shell لديك. + 2. فعّل استيراد shell (ميزة اختيارية للراحة): ```json5 { @@ -1941,35 +1941,35 @@ x-i18n: } ``` - يشغّل هذا shell تسجيل الدخول لديك ويستورد فقط المفاتيح المتوقعة المفقودة (من دون أي تجاوز). مقابلات متغيرات البيئة: + يشغّل هذا login shell لديك ويستورد فقط المفاتيح المتوقعة المفقودة (من دون تجاوز أي شيء). المقابلات في env: `OPENCLAW_LOAD_SHELL_ENV=1`, `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`. - يعرض `openclaw models status` ما إذا كان **استيراد shell env** مفعّلًا. ولا تعني عبارة "Shell env: off" - أن متغيرات البيئة لديك مفقودة - بل تعني فقط أن OpenClaw لن يحمّل - shell تسجيل الدخول لديك تلقائيًا. + تعرض `openclaw models status` ما إذا كان **استيراد shell env** مفعّلًا. وعبارة "Shell env: off" + لا **تعني** أن متغيرات env لديك مفقودة - بل تعني فقط أن OpenClaw لن يحمّل + login shell لديك تلقائيًا. - إذا كانت Gateway تعمل بوصفها خدمة (launchd/systemd)، فلن ترث - بيئة shell الخاصة بك. أصلح ذلك عبر أحد هذه الخيارات: + إذا كانت Gateway تعمل كخدمة (launchd/systemd)، فلن ترث بيئة shell + لديك. أصلح ذلك بإحدى الطرق التالية: - 1. ضع الرمز المميز في `~/.openclaw/.env`: + 1. ضع token في `~/.openclaw/.env`: ``` COPILOT_GITHUB_TOKEN=... ``` 2. أو فعّل استيراد shell (`env.shellEnv.enabled: true`). - 3. أو أضفه إلى كتلة `env` في الإعداد (يُطبق فقط إذا كان مفقودًا). + 3. أو أضفه إلى كتلة `env` في الإعدادات (يُطبّق فقط إذا كان مفقودًا). - ثم أعد تشغيل gateway وأعد الفحص: + ثم أعد تشغيل gateway وتحقق مجددًا: ```bash openclaw models status ``` - تتم قراءة Copilot tokens من `COPILOT_GITHUB_TOKEN` (وأيضًا `GH_TOKEN` / `GITHUB_TOKEN`). + تُقرأ رموز Copilot من `COPILOT_GITHUB_TOKEN` (وأيضًا `GH_TOKEN` / `GITHUB_TOKEN`). راجع [/concepts/model-providers](/ar/concepts/model-providers) و[/environment](/ar/help/environment). @@ -1982,11 +1982,11 @@ x-i18n: أرسل `/new` أو `/reset` كرسالة مستقلة. راجع [إدارة الجلسات](/ar/concepts/session). - - يمكن أن تنتهي صلاحية الجلسات بعد `session.idleMinutes`، لكن هذا **معطل افتراضيًا** (الافتراضي **0**). - اضبطها على قيمة موجبة لتفعيل انتهاء الصلاحية بسبب الخمول. وعند التفعيل، فإن الرسالة **التالية** + + يمكن أن تنتهي صلاحية الجلسات بعد `session.idleMinutes`، لكن هذا **معطّل افتراضيًا** (القيمة الافتراضية **0**). + اضبطه على قيمة موجبة لتمكين انتهاء الصلاحية عند الخمول. وعند التمكين، فإن الرسالة **التالية** بعد فترة الخمول تبدأ معرّف جلسة جديدًا لذلك المفتاح الخاص بالدردشة. - وهذا لا يحذف النصوص - بل يبدأ جلسة جديدة فقط. + لا يحذف هذا النصوص - بل يبدأ جلسة جديدة فقط. ```json5 { @@ -1998,35 +1998,35 @@ x-i18n: - - نعم، عبر **التوجيه متعدد الوكلاء** و**الوكلاء الفرعيين**. يمكنك إنشاء وكيل - منسق واحد وعدة وكلاء عاملين مع مساحات العمل والنماذج الخاصة بهم. + + نعم، عبر **التوجيه متعدد الوكلاء** و**sub-agents**. يمكنك إنشاء وكيل + منسق واحد وعدة وكلاء عمال مع مساحات عمل ونماذج خاصة بهم. - ومع ذلك، يُفضّل النظر إلى هذا على أنه **تجربة ممتعة**. فهو كثيف من ناحية الرموز وغالبًا - أقل كفاءة من استخدام بوت واحد مع جلسات منفصلة. والنموذج المعتاد الذي - نتصوره هو بوت واحد تتحدث إليه، مع جلسات مختلفة للعمل المتوازي. كما يمكن لذلك - البوت أن ينشئ وكلاء فرعيين عند الحاجة. + ومع ذلك، يُنظر إلى هذا على أنه **تجربة ممتعة**. فهو كثيف الرموز وغالبًا + أقل كفاءة من استخدام bot واحد مع جلسات منفصلة. والنموذج المعتاد الذي + نتصوره هو bot واحد تتحدث معه، مع جلسات مختلفة للعمل المتوازي. ويمكن لهذا + bot أيضًا إنشاء sub-agents عند الحاجة. - الوثائق: [التوجيه متعدد الوكلاء](/ar/concepts/multi-agent)، [الوكلاء الفرعيون](/ar/tools/subagents)، [CLI الخاص بالوكلاء](/cli/agents). + المستندات: [التوجيه متعدد الوكلاء](/ar/concepts/multi-agent)، [Sub-agents](/ar/tools/subagents)، [CLI الخاص بالوكلاء](/cli/agents). - - يقتصر سياق الجلسة على نافذة النموذج. ويمكن للدردشات الطويلة، أو مخارج الأدوات الكبيرة، أو - كثرة الملفات أن تؤدي إلى الضغط أو القطع. + + سياق الجلسة محدود بنافذة النموذج. يمكن للمحادثات الطويلة أو مخرجات الأدوات الكبيرة أو كثرة + الملفات أن تؤدي إلى الضغط أو الاقتطاع. ما الذي يساعد: - - اطلب من البوت أن يلخص الحالة الحالية ويكتبها في ملف. - - استخدم `/compact` قبل المهام الطويلة، و`/new` عند تبديل الموضوعات. - - احتفظ بالسياق المهم في مساحة العمل واطلب من البوت قراءته مجددًا. - - استخدم وكلاء فرعيين للعمل الطويل أو المتوازي حتى تبقى الدردشة الرئيسية أصغر. + - اطلب من bot أن يلخّص الحالة الحالية ويكتبها إلى ملف. + - استخدم `/compact` قبل المهام الطويلة، و`/new` عند تغيير الموضوع. + - احتفظ بالسياق المهم في مساحة العمل واطلب من bot قراءته مجددًا. + - استخدم sub-agents للمهام الطويلة أو المتوازية حتى تبقى الدردشة الرئيسية أصغر. - اختر نموذجًا بنافذة سياق أكبر إذا كان هذا يحدث كثيرًا. - استخدم أمر إعادة التعيين: + استخدم أمر reset: ```bash openclaw reset @@ -2046,16 +2046,16 @@ x-i18n: ملاحظات: - - تعرض التهيئة الأولية أيضًا **إعادة تعيين** إذا رأت إعدادًا موجودًا. راجع [التهيئة الأولية (CLI)](/ar/start/wizard). - - إذا كنت تستخدم ملفات تعريف (`--profile` / `OPENCLAW_PROFILE`)، فأعد تعيين كل دليل حالة (الافتراضيات هي `~/.openclaw-`). - - إعادة تعيين Dev: ‏`openclaw gateway --dev --reset` ‏(للتطوير فقط؛ تمسح إعداد dev + بيانات الاعتماد + الجلسات + مساحة العمل). + - يعرض الإدخال الأولي أيضًا **Reset** إذا رأى إعدادات موجودة. راجع [الإدخال الأولي (CLI)](/ar/start/wizard). + - إذا كنت استخدمت ملفات تعريف (`--profile` / `OPENCLAW_PROFILE`)، فأعد تعيين كل دليل حالة (الافتراضي هو `~/.openclaw-`). + - إعادة تعيين Dev: `openclaw gateway --dev --reset` (خاصة بـ dev؛ تمحو إعدادات dev + بيانات الاعتماد + الجلسات + مساحة العمل). - + استخدم أحد هذه الخيارات: - - **ضغط** (يحافظ على المحادثة لكنه يلخص الأدوار الأقدم): + - **الضغط** (يُبقي المحادثة لكنه يلخّص الأدوار الأقدم): ``` /compact @@ -2063,28 +2063,28 @@ x-i18n: أو `/compact ` لتوجيه الملخص. - - **إعادة تعيين** (معرّف جلسة جديد لمفتاح الدردشة نفسه): + - **إعادة التعيين** (معرّف جلسة جديد لنفس مفتاح الدردشة): ``` /new /reset ``` - إذا استمر هذا في الحدوث: + إذا استمر ذلك: - - فعّل أو اضبط **session pruning** ‏(`agents.defaults.contextPruning`) لقص خرج الأدوات القديم. + - فعّل أو اضبط **session pruning** (`agents.defaults.contextPruning`) لقص مخرجات الأدوات القديمة. - استخدم نموذجًا بنافذة سياق أكبر. - الوثائق: [الضغط](/ar/concepts/compaction)، [تشذيب الجلسات](/ar/concepts/session-pruning)، [إدارة الجلسات](/ar/concepts/session). + المستندات: [الضغط](/ar/concepts/compaction)، [تشذيب الجلسات](/ar/concepts/session-pruning)، [إدارة الجلسات](/ar/concepts/session). - هذا خطأ تحقق من الموفر: أصدر النموذج كتلة `tool_use` من دون - `input` المطلوب. وعادةً ما يعني ذلك أن سجل الجلسة قديم أو تالف (غالبًا بعد خيوط طويلة + هذا خطأ تحقق من المزوّد: فقد أصدر النموذج كتلة `tool_use` من دون + `input` المطلوب. وهذا يعني عادةً أن محفوظات الجلسة قديمة أو تالفة (غالبًا بعد سلاسل طويلة أو تغيير في الأداة/schema). - الحل: ابدأ جلسة جديدة باستخدام `/new` (كردة فعل مستقلة). + الحل: ابدأ جلسة جديدة عبر `/new` (رسالة مستقلة). @@ -2103,19 +2103,19 @@ x-i18n: } ``` - إذا كان `HEARTBEAT.md` موجودًا لكنه فارغ فعليًا (يحتوي فقط على أسطر فارغة وعناوين - Markdown مثل `# Heading`)، فإن OpenClaw يتخطى تشغيل heartbeat لتوفير استدعاءات API. - وإذا كان الملف مفقودًا، فإن heartbeat تستمر في العمل ويقرر النموذج ما الذي يجب فعله. + إذا كان `HEARTBEAT.md` موجودًا لكنه فارغ فعليًا (أسطر فارغة فقط وعناوين markdown + مثل `# Heading`)، فإن OpenClaw يتخطى تشغيل heartbeat لتوفير استدعاءات API. + وإذا كان الملف مفقودًا، فسيستمر heartbeat في العمل ويقرّر النموذج ما الذي سيفعله. - تستخدم overrides لكل وكيل `agents.list[].heartbeat`. الوثائق: [Heartbeat](/ar/gateway/heartbeat). + تستخدم التجاوزات لكل وكيل `agents.list[].heartbeat`. المستندات: [Heartbeat](/ar/gateway/heartbeat). - - لا. يعمل OpenClaw على **حسابك الشخصي**، لذا إذا كنت داخل المجموعة، يستطيع OpenClaw رؤيتها. - وبشكل افتراضي، يتم حظر الردود في المجموعات حتى تسمح للمرسلين (`groupPolicy: "allowlist"`). + + لا. يعمل OpenClaw على **حسابك أنت**، لذا إذا كنت موجودًا في المجموعة، فبإمكان OpenClaw رؤيتها. + افتراضيًا، تُحظر الردود في المجموعات حتى تسمح للمرسلين (`groupPolicy: "allowlist"`). - إذا كنت تريد أن يكون **أنت فقط** قادرًا على تحفيز الردود في المجموعة: + إذا كنت تريد أن تتمكن **أنت فقط** من تشغيل الردود في المجموعة: ```json5 { @@ -2131,164 +2131,163 @@ x-i18n: - الخيار 1 (الأسرع): تابع السجلات وأرسل رسالة اختبار في المجموعة: + الخيار 1 (الأسرع): اعرض السجلات مباشرةً وأرسل رسالة اختبار في المجموعة: ```bash openclaw logs --follow --json ``` - ابحث عن `chatId` (أو `from`) المنتهي بـ `@g.us`، مثل: + ابحث عن `chatId` (أو `from`) الذي ينتهي بـ `@g.us`، مثل: `1234567890-1234567890@g.us`. - الخيار 2 (إذا كانت مهيأة/موجودة بالفعل في قائمة السماح): اعرض المجموعات من الإعداد: + الخيار 2 (إذا كان قد تم التكوين/الإدراج في allowlist بالفعل): اعرض المجموعات من الإعدادات: ```bash openclaw directory groups list --channel whatsapp ``` - الوثائق: [WhatsApp](/ar/channels/whatsapp)، [الدليل](/cli/directory)، [السجلات](/cli/logs). + المستندات: [WhatsApp](/ar/channels/whatsapp)، [Directory](/cli/directory)، [السجلات](/cli/logs). - هناك سببان شائعان: + سببان شائعان: - - بوابة الإشارة مفعلة (افتراضيًا). يجب أن تقوم @mention للبوت (أو تطابق `mentionPatterns`). - - لقد هيّأت `channels.whatsapp.groups` من دون `"*"` والمجموعة غير موجودة في قائمة السماح. + - تفعيل قيد الذكر (الافتراضي). يجب أن تقوم بعمل @mention للـ bot (أو أن تطابق `mentionPatterns`). + - لقد قمت بتكوين `channels.whatsapp.groups` بدون `"*"` والمجموعة ليست ضمن allowlist. راجع [المجموعات](/ar/channels/groups) و[رسائل المجموعات](/ar/channels/group-messages). - - تنهار الدردشات المباشرة إلى الجلسة الرئيسية افتراضيًا. أما المجموعات/القنوات فلها مفاتيح جلسات خاصة بها، وموضوعات Telegram / خيوط Discord هي جلسات منفصلة. راجع [المجموعات](/ar/channels/groups) و[رسائل المجموعات](/ar/channels/group-messages). + + تُطوى الدردشات المباشرة إلى الجلسة الرئيسية افتراضيًا. أما المجموعات/القنوات فلها مفاتيح جلسات خاصة بها، كما أن مواضيع Telegram / خيوط Discord هي جلسات منفصلة. راجع [المجموعات](/ar/channels/groups) و[رسائل المجموعات](/ar/channels/group-messages). - - لا توجد حدود صارمة. فالعشرات (بل المئات) لا بأس بها، لكن راقب: + + لا توجد حدود صارمة. العشرات (بل المئات) لا بأس بها، لكن انتبه إلى: - **نمو القرص:** تعيش الجلسات + النصوص تحت `~/.openclaw/agents//sessions/`. - - **تكلفة الرموز:** مزيد من الوكلاء يعني مزيدًا من استخدام النماذج بالتوازي. - - **العبء التشغيلي:** ملفات تعريف مصادقة ومساحات عمل وتوجيه قنوات لكل وكيل. + - **تكلفة الرموز:** المزيد من الوكلاء يعني استخدامًا متزامنًا أكبر للنماذج. + - **العبء التشغيلي:** ملفات تعريف المصادقة لكل وكيل، ومساحات العمل، وتوجيه القنوات. نصائح: - - احتفظ بمساحة عمل **نشطة** واحدة لكل وكيل (`agents.defaults.workspace`). - - قلّم الجلسات القديمة (احذف JSONL أو إدخالات المتجر) إذا ازداد حجم القرص. - - استخدم `openclaw doctor` لاكتشاف مساحات العمل الشاردة وعدم تطابق الملفات الشخصية. + - أبقِ **مساحة عمل نشطة** واحدة لكل وكيل (`agents.defaults.workspace`). + - شذّب الجلسات القديمة (احذف JSONL أو إدخالات المخزن) إذا نما القرص. + - استخدم `openclaw doctor` لاكتشاف مساحات العمل الشاردة وعدم تطابق ملفات التعريف. - - نعم. استخدم **التوجيه متعدد الوكلاء** لتشغيل عدة وكلاء معزولين وتوجيه الرسائل الواردة بحسب - القناة/الحساب/الندّ. Slack مدعوم كقناة ويمكن ربطه بوكلاء محددين. + + نعم. استخدم **التوجيه متعدد الوكلاء** لتشغيل عدة وكلاء معزولين وتوجيه الرسائل الواردة حسب + القناة/الحساب/القرين. Slack مدعومة كقناة ويمكن ربطها بوكلاء محددين. - الوصول إلى المتصفح قوي لكنه ليس "افعل أي شيء يمكن للإنسان فعله" - إذ لا تزال أنظمة مكافحة الروبوتات وCAPTCHAs وMFA + وصول المتصفح قوي، لكنه ليس "افعل كل ما يستطيع الإنسان فعله" - فلا تزال أدوات مكافحة الروبوت وCAPTCHAs وMFA قادرة على حظر الأتمتة. وللحصول على أكثر تحكم موثوق بالمتصفح، استخدم Chrome MCP المحلي على المضيف، - أو استخدم CDP على الجهاز الذي يشغّل المتصفح فعليًا. + أو استخدم CDP على الجهاز الذي يشغّل المتصفح فعلًا. أفضل إعداد عملي: - - مضيف Gateway دائم التشغيل (VPS/Mac mini). + - مضيف Gateway يعمل دائمًا (VPS/Mac mini). - وكيل واحد لكل دور (bindings). - قناة/قنوات Slack مربوطة بتلك الوكلاء. - متصفح محلي عبر Chrome MCP أو node عند الحاجة. - الوثائق: [التوجيه متعدد الوكلاء](/ar/concepts/multi-agent)، [Slack](/ar/channels/slack)، + المستندات: [التوجيه متعدد الوكلاء](/ar/concepts/multi-agent)، [Slack](/ar/channels/slack)، [المتصفح](/ar/tools/browser)، [Nodes](/ar/nodes). -## النماذج: الافتراضيات، والاختيار، والأسماء المستعارة، والتبديل +## النماذج: الافتراضيات، الاختيار، الأسماء المستعارة، التبديل - النموذج الافتراضي في OpenClaw هو ما تضبطه على أنه: + النموذج الافتراضي في OpenClaw هو أي نموذج تضبطه كالتالي: ``` agents.defaults.model.primary ``` - يُشار إلى النماذج بصيغة `provider/model` (مثال: `openai/gpt-5.4`). وإذا حذفت الموفر، فإن OpenClaw تحاول أولًا اسمًا مستعارًا، ثم تطابقًا فريدًا لموفر مهيأ لذلك المعرّف الدقيق للنموذج، وبعد ذلك فقط تعود إلى الموفر الافتراضي المهيأ كمسار توافق قديم. وإذا كان ذلك الموفر لم يعد يعرّض النموذج الافتراضي المهيأ، فإن OpenClaw تعود إلى أول موفر/نموذج مهيأ بدل إظهار افتراضي قديم يعود إلى موفر مُزال. ومع ذلك، ينبغي لك **تعيين** `provider/model` بشكل صريح. + يُشار إلى النماذج بصيغة `provider/model` (مثال: `openai/gpt-5.4`). وإذا حذفت المزوّد، فإن OpenClaw يحاول أولًا اسمًا مستعارًا، ثم مطابقة فريدة لمزوّد مكوَّن لهذا المعرّف الدقيق للنموذج، ثم فقط يعود إلى مزوّد افتراضي مكوَّن كمسار توافق قديم مُهمَل. وإذا لم يعد هذا المزوّد يكشف النموذج الافتراضي المكوَّن، فإن OpenClaw يعود إلى أول مزوّد/نموذج مكوَّن بدلًا من إظهار افتراضي قديم يشير إلى مزوّد أزيل. ومع ذلك يجب عليك **ضبط `provider/model` صراحةً**. - **الافتراضي الموصى به:** استخدم أقوى نموذج من أحدث جيل متاح ضمن مجموعة الموفّرين لديك. - **للوكلاء المزوّدين بالأدوات أو ذوي المدخلات غير الموثوقة:** أعطِ الأولوية لقوة النموذج على التكلفة. - **للدردشة الروتينية/منخفضة المخاطر:** استخدم نماذج احتياطية أرخص ووجّه حسب دور الوكيل. + **الافتراضي الموصى به:** استخدم أقوى نموذج من الجيل الأحدث متاح في مجموعة المزوّدين لديك. + **بالنسبة إلى الوكلاء المفعّلة بالأدوات أو ذات المدخلات غير الموثوقة:** قدّم قوة النموذج على التكلفة. + **بالنسبة إلى الدردشة الروتينية/منخفضة المخاطر:** استخدم نماذج احتياطية أرخص ووجّه حسب دور الوكيل. - لدى MiniMax وثائقها الخاصة: [MiniMax](/ar/providers/minimax) و + لدى MiniMax مستنداتها الخاصة: [MiniMax](/ar/providers/minimax) و [النماذج المحلية](/ar/gateway/local-models). القاعدة العامة: استخدم **أفضل نموذج يمكنك تحمّل تكلفته** للأعمال عالية المخاطر، ونموذجًا أرخص - للدردشة الروتينية أو الملخصات. ويمكنك توجيه النماذج لكل وكيل واستخدام وكلاء فرعيين - لتوازي المهام الطويلة (كل وكيل فرعي يستهلك رموزًا). راجع [النماذج](/ar/concepts/models) و - [الوكلاء الفرعيون](/ar/tools/subagents). + للدردشة الروتينية أو الملخصات. يمكنك توجيه النماذج لكل وكيل واستخدام sub-agents + لموازاة المهام الطويلة (كل sub-agent يستهلك رموزًا). راجع [النماذج](/ar/concepts/models) و + [Sub-agents](/ar/tools/subagents). - تحذير قوي: النماذج الأضعف/المكمّاة بإفراط أكثر عرضة لـ prompt + تحذير قوي: النماذج الأضعف/المكمّمة أكثر تكون أكثر عرضة لـ prompt injection والسلوك غير الآمن. راجع [الأمان](/ar/gateway/security). مزيد من السياق: [النماذج](/ar/concepts/models). - - استخدم **أوامر النماذج** أو حرر فقط حقول **النموذج**. وتجنب استبدال الإعداد كاملًا. + + استخدم **أوامر النموذج** أو عدّل فقط حقول **model**. تجنب الاستبدال الكامل للإعدادات. خيارات آمنة: - `/model` في الدردشة (سريع، لكل جلسة) - - `openclaw models set ...` (يحدّث إعداد النموذج فقط) + - `openclaw models set ...` (يحدّث فقط إعدادات النموذج) - `openclaw configure --section model` (تفاعلي) - عدّل `agents.defaults.model` في `~/.openclaw/openclaw.json` - تجنب `config.apply` مع كائن جزئي ما لم تكن تنوي استبدال الإعداد كله. - وبالنسبة إلى تعديلات RPC، افحص أولًا باستخدام `config.schema.lookup` وفضّل `config.patch`. - تمنحك حمولة lookup المسار المُطبع، ووثائق/قيود schema السطحية، وملخصات الأبناء المباشرين + تجنب `config.apply` مع كائن جزئي ما لم تكن تقصد استبدال الإعدادات كاملةً. + وبالنسبة إلى تعديلات RPC، افحص باستخدام `config.schema.lookup` أولًا وفضّل `config.patch`. تمنحك حمولة lookup المسار المطبع، ووثائق/قيود schema السطحية، وملخصات الأبناء المباشرين. للتحديثات الجزئية. - وإذا كنت قد استبدلت الإعداد بالفعل، فاستعد من نسخة احتياطية أو أعد تشغيل `openclaw doctor` للإصلاح. + وإذا كنت قد كتبت فوق الإعدادات، فاستعدها من نسخة احتياطية أو أعد تشغيل `openclaw doctor` لإصلاحها. - الوثائق: [النماذج](/ar/concepts/models)، [التكوين](/cli/configure)، [الإعداد](/cli/config)، [Doctor](/ar/gateway/doctor). + المستندات: [النماذج](/ar/concepts/models)، [Configure](/cli/configure)، [الإعدادات](/cli/config)، [Doctor](/ar/gateway/doctor). - - نعم. وOllama هي أسهل طريق إلى النماذج المحلية. + + نعم. تُعد Ollama أسهل مسار للنماذج المحلية. أسرع إعداد: 1. ثبّت Ollama من `https://ollama.com/download` - 2. اسحب نموذجًا محليًا مثل `ollama pull glm-4.7-flash` - 3. إذا كنت تريد نماذج سحابية أيضًا، فشغّل `ollama signin` + 2. اسحب نموذجًا محليًا مثل `ollama pull gemma4` + 3. إذا كنت تريد نماذج سحابية أيضًا، شغّل `ollama signin` 4. شغّل `openclaw onboard` واختر `Ollama` 5. اختر `Local` أو `Cloud + Local` ملاحظات: - - يمنحك `Cloud + Local` نماذج سحابية بالإضافة إلى نماذج Ollama المحلية - - النماذج السحابية مثل `kimi-k2.5:cloud` لا تحتاج إلى سحب محلي + - يمنحك `Cloud + Local` نماذج سحابية إضافةً إلى نماذج Ollama المحلية + - لا تحتاج النماذج السحابية مثل `kimi-k2.5:cloud` إلى سحب محلي - للتبديل اليدوي، استخدم `openclaw models list` و`openclaw models set ollama/` - ملاحظة أمنية: النماذج الأصغر أو المكمّاة بشدة أكثر عرضة لـ prompt - injection. ونوصي بشدة باستخدام **نماذج كبيرة** لأي بوت يستطيع استخدام الأدوات. - وإذا كنت لا تزال تريد نماذج صغيرة، ففعّل sandboxing وقوائم سماح صارمة للأدوات. + ملاحظة أمان: النماذج الأصغر أو المكمّمة بشدة أكثر عرضة لـ prompt + injection. نحن نوصي بشدة باستخدام **نماذج كبيرة** لأي bot + يستطيع استخدام الأدوات. وإذا كنت لا تزال تريد نماذج صغيرة، ففعّل العزل وقوائم سماح صارمة للأدوات. - الوثائق: [Ollama](/ar/providers/ollama)، [النماذج المحلية](/ar/gateway/local-models)، - [موفرو النماذج](/ar/concepts/model-providers)، [الأمان](/ar/gateway/security)، - [الحاويات الآمنة](/ar/gateway/sandboxing). + المستندات: [Ollama](/ar/providers/ollama)، [النماذج المحلية](/ar/gateway/local-models)، + [مزودو النماذج](/ar/concepts/model-providers)، [الأمان](/ar/gateway/security)، + [العزل](/ar/gateway/sandboxing). - - - قد تختلف هذه البيئات وقد تتغير بمرور الوقت؛ ولا توجد توصية ثابتة بموفر معين. - - تحقق من إعداد وقت التشغيل الحالي على كل بوابة باستخدام `openclaw models status`. - - بالنسبة إلى الوكلاء الحساسين أمنيًا/المزوّدين بالأدوات، استخدم أقوى نموذج من أحدث جيل متاح. + + - يمكن أن تختلف هذه البيئات وقد تتغير مع الوقت؛ ولا توجد توصية ثابتة بمزوّد بعينه. + - تحقق من إعداد وقت التشغيل الحالي على كل gateway باستخدام `openclaw models status`. + - بالنسبة إلى الوكلاء الحسّاسين أمنيًا/المفعّلين بالأدوات، استخدم أقوى نموذج من الجيل الأحدث متاح. - استخدم أمر `/model` كرسالة مستقلة: + استخدم الأمر `/model` كرسالة مستقلة: ``` /model sonnet @@ -2300,17 +2299,17 @@ x-i18n: /model gemini-flash-lite ``` - هذه هي الأسماء المستعارة المدمجة. ويمكن إضافة أسماء مستعارة مخصصة عبر `agents.defaults.models`. + هذه هي الأسماء المستعارة المضمّنة. ويمكن إضافة أسماء مستعارة مخصصة عبر `agents.defaults.models`. - يمكنك عرض النماذج المتاحة باستخدام `/model` أو `/model list` أو `/model status`. + يمكنك عرض النماذج المتاحة عبر `/model` أو `/model list` أو `/model status`. - يعرض `/model` ‏(وكذلك `/model list`) منتقيًا مدمجًا ومُرقّمًا. اختر حسب الرقم: + يعرض `/model` (و`/model list`) منتقيًا مدمجًا ومرقمًا. اختر بالرقم: ``` /model 3 ``` - ويمكنك أيضًا فرض ملف تعريف مصادقة معين للموفر (لكل جلسة): + يمكنك أيضًا فرض ملف تعريف مصادقة محدد للمزوّد (لكل جلسة): ``` /model opus@anthropic:default @@ -2318,9 +2317,9 @@ x-i18n: ``` نصيحة: يعرض `/model status` الوكيل النشط، وملف `auth-profiles.json` المستخدم، وملف تعريف المصادقة الذي ستتم تجربته بعد ذلك. - كما يعرض نقطة نهاية الموفر المهيأة (`baseUrl`) ووضع API ‏(`api`) عند توفرهما. + كما يعرض نقطة نهاية المزوّد المكوّنة (`baseUrl`) ووضع API (`api`) عند توفرهما. - **كيف ألغي تثبيت ملف تعريف قمت بتعيينه باستخدام @profile؟** + **كيف أفك تثبيت ملف تعريف ثبّتُه باستخدام @profile؟** أعد تشغيل `/model` **من دون** اللاحقة `@profile`: @@ -2328,28 +2327,28 @@ x-i18n: /model anthropic/claude-opus-4-6 ``` - وإذا أردت العودة إلى الافتراضي، فاختره من `/model` (أو أرسل `/model `). - واستخدم `/model status` للتأكد من ملف تعريف المصادقة النشط. + وإذا كنت تريد العودة إلى الافتراضي، فاختره من `/model` (أو أرسل `/model `). + استخدم `/model status` لتأكيد ملف تعريف المصادقة النشط. نعم. اضبط أحدهما كافتراضي وبدّل عند الحاجة: - - **تبديل سريع (لكل جلسة):** استخدم `/model gpt-5.4` للمهام اليومية، و`/model openai-codex/gpt-5.4` للبرمجة باستخدام Codex OAuth. + - **تبديل سريع (لكل جلسة):** `/model gpt-5.4` للمهام اليومية، و`/model openai-codex/gpt-5.4` للبرمجة باستخدام Codex OAuth. - **افتراضي + تبديل:** اضبط `agents.defaults.model.primary` على `openai/gpt-5.4`، ثم بدّل إلى `openai-codex/gpt-5.4` عند البرمجة (أو بالعكس). - - **الوكلاء الفرعيون:** وجّه مهام البرمجة إلى وكلاء فرعيين لديهم نموذج افتراضي مختلف. + - **Sub-agents:** وجّه مهام البرمجة إلى sub-agents ذات نموذج افتراضي مختلف. - راجع [النماذج](/ar/concepts/models) و[أوامر الشرطة المائلة](/ar/tools/slash-commands). + راجع [النماذج](/ar/concepts/models) و[أوامر Slash](/ar/tools/slash-commands). - - استخدم إما تبديلًا لكل جلسة أو افتراضيًا في الإعداد: + + استخدم إما مفتاح تبديل للجلسة أو افتراضيًا في الإعدادات: - **لكل جلسة:** أرسل `/fast on` بينما تستخدم الجلسة `openai/gpt-5.4` أو `openai-codex/gpt-5.4`. - **افتراضي لكل نموذج:** اضبط `agents.defaults.models["openai/gpt-5.4"].params.fastMode` على `true`. - - **ينطبق على Codex OAuth أيضًا:** إذا كنت تستخدم أيضًا `openai-codex/gpt-5.4`، فاضبط العلم نفسه هناك. + - **Codex OAuth أيضًا:** إذا كنت تستخدم أيضًا `openai-codex/gpt-5.4`، فاضبط العلامة نفسها هناك. مثال: @@ -2374,31 +2373,37 @@ x-i18n: } ``` - بالنسبة إلى OpenAI، يُطابق fast mode القيمة `service_tier = "priority"` في طلبات Responses الأصلية المدعومة. وتتغلب قيمة `/fast` الخاصة بالجلسة على افتراضيات الإعداد. + بالنسبة إلى OpenAI، يطابق fast mode القيمة `service_tier = "priority"` في طلبات Responses الأصلية المدعومة. وتتغلب قيمة `/fast` الخاصة بالجلسة على الافتراضيات الموجودة في الإعدادات. - راجع [التفكير وfast mode](/ar/tools/thinking) و[OpenAI fast mode](/ar/providers/openai#openai-fast-mode). + راجع [Thinking وfast mode](/ar/tools/thinking) و[OpenAI fast mode](/ar/providers/openai#openai-fast-mode). - - إذا كانت `agents.defaults.models` مضبوطة، فإنها تصبح **قائمة السماح** لـ `/model` وأي - overrides للجلسة. ويؤدي اختيار نموذج غير موجود في تلك القائمة إلى إرجاع: + + إذا كانت `agents.defaults.models` مضبوطة، فإنها تصبح **allowlist** لـ `/model` وأي + تجاوزات جلسة. ويؤدي اختيار نموذج غير موجود في هذه القائمة إلى إرجاع: ``` Model "provider/model" is not allowed. Use /model to list available models. ``` - يُعاد هذا الخطأ **بدلًا من** رد عادي. والحل: أضف النموذج إلى - `agents.defaults.models`، أو أزل قائمة السماح، أو اختر نموذجًا من `/model list`. + يتم إرجاع هذا الخطأ **بدلًا من** رد عادي. الحل: أضف النموذج إلى + `agents.defaults.models`، أو أزل allowlist، أو اختر نموذجًا من `/model list`. - هذا يعني أن **الموفر غير مهيأ** (لم يُعثر على إعداد موفر MiniMax أو ملف + هذا يعني أن **المزوّد غير مكوّن** (لم يتم العثور على إعداد MiniMax أو ملف تعريف مصادقة)، لذلك لا يمكن حل النموذج. - قائمة تحقق للحل: + قائمة التحقق للإصلاح: - 1. حدّث إلى إصدار حديث من OpenClaw (أو شغّل من المصدر `main`) ثم أعد تشغيل gateway. - 2. تأكد من أن MiniMax مهيأ (عبر المعالج أو JSON)، أو أن مصادقة MiniMax - موجودة \ No newline at end of file + 1. حدّث إلى إصدار OpenClaw حالي (أو شغّل من المصدر `main`)، ثم أعد تشغيل gateway. + 2. تأكد من تكوين MiniMax (عبر المعالج أو JSON)، أو أن مصادقة MiniMax + موجودة في env/ملفات تعريف المصادقة بحيث يمكن حقن المزوّد المطابق + (`MINIMAX_API_KEY` من أجل `minimax`، أو `MINIMAX_OAUTH_TOKEN` أو MiniMax + OAuth المخزن من أجل `minimax-portal`). + 3. استخدم معرّف النموذج الدقيق (حساس لحالة الأحرف) لمسار المصادقة لديك: + `minimax/MiniMax-M2.7` أو `minimax/MiniMax-M2.7-highspeed` لإعداد + API key، أو `minimax-portal/MiniMax-M2.7` / + `minimax-portal/MiniMax-M2.7-highspeed` \ No newline at end of file diff --git a/docs/ar/help/scripts.md b/docs/ar/help/scripts.md index ee14bac18..5aea97189 100644 --- a/docs/ar/help/scripts.md +++ b/docs/ar/help/scripts.md @@ -1,34 +1,60 @@ --- read_when: - - تشغيل البرامج النصية من المستودع - - إضافة أو تغيير البرامج النصية ضمن ‎./scripts -summary: 'برامج المستودع النصية: الغرض، والنطاق، وملاحظات السلامة' -title: البرامج النصية + - تشغيل السكريبتات من المستودع + - إضافة أو تغيير السكريبتات ضمن ./scripts +summary: 'سكريبتات المستودع: الغرض والنطاق وملاحظات السلامة' +title: السكريبتات x-i18n: - generated_at: "2026-04-05T12:45:19Z" + generated_at: "2026-04-08T02:15:44Z" model: gpt-5.4 provider: openai - source_hash: de53d64d91c564931bdd4e8b9f4a8e88646332a07cc2a6bf1d517b89debb29cd + source_hash: 3ecf1e9327929948fb75f80e306963af49b353c0aa8d3b6fa532ca964ff8b975 source_path: help/scripts.md workflow: 15 --- -# البرامج النصية +# السكريبتات -يحتوي الدليل `scripts/` على برامج نصية مساعدة لسير العمل المحلي ومهام التشغيل. -استخدمها عندما تكون المهمة مرتبطة بوضوح ببرنامج نصي؛ وخلاف ذلك، فضّل CLI. +يحتوي الدليل `scripts/` على سكريبتات مساعدة لسير العمل المحلي ومهام التشغيل. +استخدمها عندما تكون المهمة مرتبطة بوضوح بسكريبت؛ وإلا ففضّل استخدام CLI. ## الاصطلاحات -- تكون البرامج النصية **اختيارية** ما لم يُشر إليها في الوثائق أو قوائم التحقق الخاصة بالإصدار. +- السكريبتات **اختيارية** ما لم تتم الإشارة إليها في الوثائق أو قوائم التحقق الخاصة بالإصدار. - فضّل واجهات CLI عندما تكون موجودة (مثال: تستخدم مراقبة المصادقة `openclaw models status --check`). -- افترض أن البرامج النصية خاصة بالمضيف؛ واقرأها قبل تشغيلها على جهاز جديد. +- افترض أن السكريبتات خاصة بالمضيف؛ واقرأها قبل تشغيلها على جهاز جديد. -## البرامج النصية لمراقبة المصادقة +## سكريبتات مراقبة المصادقة -تتم تغطية مراقبة المصادقة في [المصادقة](/gateway/authentication). أما البرامج النصية ضمن `scripts/` فهي إضافات اختيارية لسير عمل الهاتف باستخدام systemd/Termux. +تتم تغطية مراقبة المصادقة في [المصادقة](/ar/gateway/authentication). أما السكريبتات الموجودة ضمن `scripts/` فهي إضافات اختيارية لسير عمل systemd/Termux على الهاتف. -## عند إضافة برامج نصية +## مساعد قراءة GitHub -- أبقِ البرامج النصية مركزة وموثقة. -- أضف إدخالًا قصيرًا في الوثيقة ذات الصلة (أو أنشئ وثيقة إذا كانت مفقودة). +استخدم `scripts/gh-read` عندما تريد أن يستخدم `gh` رمز تثبيت GitHub App المميز لاستدعاءات القراءة ذات النطاق الخاص بالمستودع، مع إبقاء `gh` العادي على تسجيلك الشخصي لعمليات الكتابة. + +متغيرات البيئة المطلوبة: + +- `OPENCLAW_GH_READ_APP_ID` +- `OPENCLAW_GH_READ_PRIVATE_KEY_FILE` + +متغيرات البيئة الاختيارية: + +- `OPENCLAW_GH_READ_INSTALLATION_ID` عندما تريد تخطي البحث عن التثبيت المعتمد على المستودع +- `OPENCLAW_GH_READ_PERMISSIONS` كتجاوز مفصول بفواصل لمجموعة أذونات القراءة الفرعية المطلوب طلبها + +ترتيب حل المستودع: + +- `gh ... -R owner/repo` +- `GH_REPO` +- `git remote origin` + +أمثلة: + +- `scripts/gh-read pr view 123` +- `scripts/gh-read run list -R openclaw/openclaw` +- `scripts/gh-read api repos/openclaw/openclaw/pulls/123` + +## عند إضافة سكريبتات + +- حافظ على تركيز السكريبتات وتوثيقها. +- أضف إدخالًا قصيرًا في الوثيقة ذات الصلة (أو أنشئ واحدة إذا كانت مفقودة). diff --git a/docs/ar/help/testing.md b/docs/ar/help/testing.md index 2e2a64f1d..0d0442cf3 100644 --- a/docs/ar/help/testing.md +++ b/docs/ar/help/testing.md @@ -1,284 +1,285 @@ --- read_when: - - تشغيل الاختبارات محليًا أو في CI - - إضافة اختبارات انحدار لأخطاء النموذج/الموفّر - - تصحيح سلوك gateway + العامل -summary: 'مجموعة الاختبار: أجنحة unit/e2e/live، ومشغلات Docker، وما الذي يغطيه كل اختبار' + - عند تشغيل الاختبارات محليًا أو في CI + - عند إضافة اختبارات تراجعية لأخطاء النموذج/الموفّر + - عند تصحيح سلوك gateway + الوكيل +summary: 'عدة الاختبار: أجنحة unit/e2e/live، ومشغلات Docker، وما الذي يغطيه كل اختبار' title: الاختبار x-i18n: - generated_at: "2026-04-07T07:21:19Z" + generated_at: "2026-04-08T02:18:44Z" model: gpt-5.4 provider: openai - source_hash: 9bd5fbc91435d7acd94758fa4a00af5a80363ddebc715b8731bb508b9e5d6d28 + source_hash: ace2c19bfc350780475f4348264a4b55be2b4ccbb26f0d33b4a6af34510943b5 source_path: help/testing.md workflow: 15 --- # الاختبار -يحتوي OpenClaw على ثلاثة أجنحة Vitest (unit/integration وe2e وlive) ومجموعة صغيرة من مشغلات Docker. +يحتوي OpenClaw على ثلاثة أجنحة Vitest ‏(unit/integration، وe2e، وlive) ومجموعة صغيرة من مشغلات Docker. -هذا المستند هو دليل "كيف نختبر": +هذه الوثيقة هي دليل "كيف نختبر": -- ما الذي يغطيه كل جناح (وما الذي _لا_ يغطيه عمدًا) -- ما الأوامر التي يجب تشغيلها لسير العمل الشائع (محلي، قبل الدفع، التصحيح) -- كيف تكتشف الاختبارات الحية بيانات الاعتماد وتحدد النماذج/الموفّرين -- كيفية إضافة اختبارات انحدار للمشكلات الواقعية المتعلقة بالنموذج/الموفّر +- ما الذي يغطيه كل جناح (وما الذي لا يغطيه عمدًا) +- ما الأوامر التي يجب تشغيلها لمسارات العمل الشائعة (محليًا، قبل الدفع، التصحيح) +- كيف تكتشف الاختبارات الحية بيانات الاعتماد وتختار النماذج/الموفّرين +- كيف تضيف اختبارات تراجعية لمشكلات النماذج/الموفّرين الواقعية -## بداية سريعة +## البدء السريع في معظم الأيام: -- البوابة الكاملة (المتوقعة قبل الدفع): `pnpm build && pnpm check && pnpm test` -- تشغيل أسرع محليًا للجناح الكامل على جهاز ذي موارد جيدة: `pnpm test:max` +- البوابة الكاملة (متوقعة قبل الدفع): `pnpm build && pnpm check && pnpm test` +- تشغيل أسرع للجناح الكامل محليًا على جهاز واسع الموارد: `pnpm test:max` - حلقة مراقبة Vitest مباشرة: `pnpm test:watch` -- الاستهداف المباشر للملفات يوجّه الآن أيضًا مسارات extensions/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- موقع QA المدعوم بـ Docker: `pnpm qa:lab:up` +- استهداف مباشر للملفات يوجّه الآن مسارات extension/channel أيضًا: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- موقع QA مدعوم بـ Docker: `pnpm qa:lab:up` عندما تلمس الاختبارات أو تريد ثقة إضافية: - بوابة التغطية: `pnpm test:coverage` - جناح E2E: `pnpm test:e2e` -عند تصحيح موفّرين/نماذج حقيقية (يتطلب بيانات اعتماد حقيقية): +عند تصحيح موفّرين/نماذج حقيقيين (يتطلب بيانات اعتماد حقيقية): -- الجناح الحي (النماذج + فحوص أدوات/صور gateway): `pnpm test:live` -- استهدف ملف live واحد بهدوء: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- الجناح الحي (فحوصات النماذج + أدوات/صور gateway): `pnpm test:live` +- استهداف ملف حي واحد بهدوء: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -نصيحة: عندما تحتاج حالة فاشلة واحدة فقط، فالأفضل تضييق اختبارات live باستخدام متغيرات بيئة allowlist الموضحة أدناه. +نصيحة: عندما تحتاج إلى حالة فاشلة واحدة فقط، فالأفضل تضييق الاختبارات الحية عبر متغيرات البيئة الخاصة بقائمة السماح الموضحة أدناه. ## أجنحة الاختبار (ما الذي يعمل وأين) -فكّر في الأجنحة على أنها "واقعية متزايدة" (ومعها تزايد عدم الاستقرار/التكلفة): +فكّر في الأجنحة على أنها "تزداد واقعية" (وتزداد معها القابلية للتعطل/التكلفة): -### Unit / integration (الافتراضي) +### Unit / integration ‏(الافتراضي) - الأمر: `pnpm test` -- الإعداد: عشر تشغيلات shards متسلسلة (`vitest.full-*.config.ts`) عبر مشاريع Vitest المحددة الموجودة -- الملفات: قوائم unit/core تحت `src/**/*.test.ts` و`packages/**/*.test.ts` و`test/**/*.test.ts` واختبارات `ui` الخاصة بـ node المدرجة في allowlist والمغطاة بواسطة `vitest.unit.config.ts` +- الإعداد: عشر عمليات shard متتابعة (`vitest.full-*.config.ts`) على مشاريع Vitest المحددة الحالية +- الملفات: قوائم core/unit ضمن `src/**/*.test.ts` و`packages/**/*.test.ts` و`test/**/*.test.ts`، واختبارات `ui` الخاصة بـ node المدرجة في القائمة البيضاء والتي يغطيها `vitest.unit.config.ts` - النطاق: - اختبارات unit خالصة - اختبارات integration داخل العملية (مصادقة gateway، والتوجيه، والأدوات، والتحليل، والإعدادات) - - اختبارات انحدار حتمية للأخطاء المعروفة + - اختبارات تراجعية حتمية للأخطاء المعروفة - التوقعات: - تعمل في CI - - لا حاجة إلى مفاتيح حقيقية + - لا تتطلب مفاتيح حقيقية - يجب أن تكون سريعة ومستقرة - ملاحظة المشاريع: - - أصبح `pnpm test` غير الموجّه يشغّل الآن عشرة إعدادات shards أصغر (`core-unit-src` و`core-unit-security` و`core-unit-ui` و`core-unit-support` و`core-contracts` و`core-bundled` و`core-runtime` و`agentic` و`auto-reply` و`extensions`) بدلًا من عملية root-project أصلية واحدة ضخمة. هذا يقلل ذروة RSS على الأجهزة المزدحمة ويتجنب أن تؤدي أعمال auto-reply/extension إلى تجويع الأجنحة غير ذات الصلة. - - يظل `pnpm test --watch` يستخدم مخطط مشاريع `vitest.config.ts` الأصلي للجذر، لأن حلقة مراقبة متعددة shards ليست عملية. - - `pnpm test` و`pnpm test:watch` و`pnpm test:perf:imports` توجّه أهداف الملفات/الأدلة الصريحة عبر مسارات محددة أولًا، لذلك فإن `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` يتجنب تكلفة بدء root project الكامل. - - يقوم `pnpm test:changed` بتوسيع مسارات git المتغيرة إلى هذه المسارات المحددة نفسها عندما يلمس الفرق ملفات مصدر/اختبار قابلة للتوجيه فقط؛ أما تعديلات config/setup فتعود إلى إعادة تشغيل root-project الواسعة. - - بعض اختبارات `plugin-sdk` و`commands` المختارة تمر أيضًا عبر مسارات خفيفة مخصصة تتخطى `test/setup-openclaw-runtime.ts`؛ بينما تبقى الملفات ذات الحالة/الثقيلة من ناحية بيئة التشغيل على المسارات الحالية. - - تُطابَق أيضًا بعض ملفات المصدر المساعدة المحددة لـ `plugin-sdk` و`commands` في وضع changed مع اختبارات شقيقة صريحة ضمن تلك المسارات الخفيفة، بحيث تتجنب تعديلات المساعدين إعادة تشغيل الجناح الثقيل الكامل لذلك الدليل. - - يحتوي `auto-reply` الآن على ثلاث مجموعات مخصصة: مساعدات core ذات المستوى الأعلى، واختبارات integration من المستوى الأعلى لـ `reply.*`، والشجرة الفرعية `src/auto-reply/reply/**`. وهذا يبقي أكثر أعمال harness الخاصة بالردود ثقلًا بعيدًا عن اختبارات الحالة/الأجزاء/الرموز الرخيصة. -- ملاحظة المشغل المضمّن: - - عندما تغيّر مدخلات اكتشاف أدوات الرسائل أو سياق وقت تشغيل compaction، - حافظ على مستويي التغطية معًا. - - أضف اختبارات انحدار مركزة للمساعدين لحدود التوجيه/التسوية الخالصة. - - وحافظ أيضًا على سلامة أجنحة integration الخاصة بالمشغل المضمّن: + - أصبح `pnpm test` غير المستهدف يشغّل الآن إحدى عشرة إعدادات shard أصغر (`core-unit-src` و`core-unit-security` و`core-unit-ui` و`core-unit-support` و`core-support-boundary` و`core-contracts` و`core-bundled` و`core-runtime` و`agentic` و`auto-reply` و`extensions`) بدلًا من عملية root-project أصلية واحدة ضخمة. وهذا يقلل ذروة RSS على الأجهزة المحمّلة ويمنع أعمال auto-reply/extension من تجويع الأجنحة غير المرتبطة. + - لا يزال `pnpm test --watch` يستخدم مخطط المشروع الأصلي في `vitest.config.ts`، لأن حلقة مراقبة متعددة الـ shard غير عملية. + - يقوم `pnpm test` و`pnpm test:watch` و`pnpm test:perf:imports` بتوجيه أهداف الملفات/الأدلة الصريحة عبر المسارات المحددة أولًا، لذا فإن `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` يتجنب تكلفة بدء root project الكامل. + - يوسّع `pnpm test:changed` مسارات git المتغيرة إلى هذه المسارات المحددة نفسها عندما يمس الفرق فقط ملفات المصدر/الاختبار القابلة للتوجيه؛ أما تعديلات الإعداد/التهيئة فتعود إلى إعادة التشغيل الأوسع لمشروع الجذر. + - يتم أيضًا توجيه اختبارات `plugin-sdk` و`commands` المحددة عبر مسارات خفيفة مخصصة تتخطى `test/setup-openclaw-runtime.ts`؛ أما الملفات الثقيلة ذات الحالة/وقت التشغيل فتبقى على المسارات الحالية. + - كما أن ملفات المصدر المساعدة المحددة في `plugin-sdk` و`commands` تربط تشغيل وضع التغييرات باختبارات شقيقة صريحة ضمن تلك المسارات الخفيفة، بحيث تتجنب تعديلات المساعدات إعادة تشغيل الجناح الثقيل الكامل لذلك الدليل. + - أصبح لدى `auto-reply` الآن ثلاثة buckets مخصصة: مساعدات core من المستوى الأعلى، واختبارات integration العليا `reply.*`، وشجرة `src/auto-reply/reply/**`. وهذا يبقي أثقل أعمال reply harness بعيدًا عن اختبارات الحالة/الأجزاء/الرموز الأرخص. +- ملاحظة المشغّل المضمن: + - عندما تغيّر مدخلات اكتشاف message-tool أو سياق وقت تشغيل compaction، + حافظ على مستويي التغطية كليهما. + - أضف اختبارات تراجعية مركزة للمساعدات عند حدود التوجيه/التطبيع الخالصة. + - واحرص أيضًا على بقاء أجنحة integration الخاصة بالمشغّل المضمن سليمة: `src/agents/pi-embedded-runner/compact.hooks.test.ts`، - `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`، و + و`src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`، و `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - تتحقق هذه الأجنحة من أن المعرّفات المحددة وسلوك compaction لا يزالان يتدفقان - عبر المسارات الحقيقية لـ `run.ts` / `compact.ts`؛ واختبارات المساعدين وحدها - ليست بديلًا كافيًا لهذه المسارات التكاملية. -- ملاحظة pool: - - أصبح إعداد Vitest الأساسي يستخدم `threads` افتراضيًا الآن. - - كما يثبت إعداد Vitest المشترك `isolate: false` ويستخدم المشغل غير المعزول عبر مشاريع الجذر وتهيئات e2e وlive. - - يحتفظ مسار UI الجذري بإعداد `jsdom` والمحسّن الخاص به، لكنه يعمل الآن أيضًا على المشغل المشترك غير المعزول. - - يرث كل shard ضمن `pnpm test` الافتراضيات نفسها `threads` + `isolate: false` من إعداد Vitest المشترك. - - يضيف المشغل المشترك `scripts/run-vitest.mjs` الآن أيضًا `--no-maglev` لعمليات Node الفرعية الخاصة بـ Vitest افتراضيًا لتقليل تقلبات الترجمة في V8 أثناء التشغيلات المحلية الكبيرة. اضبط `OPENCLAW_VITEST_ENABLE_MAGLEV=1` إذا كنت بحاجة إلى المقارنة مع سلوك V8 الافتراضي. + - تتحقق هذه الأجنحة من أن المعرّفات ذات النطاق وسلوك compaction لا يزالان يمران + عبر المسارات الحقيقية `run.ts` / `compact.ts`؛ ولا تُعد اختبارات المساعدات فقط + بديلًا كافيًا عن مسارات integration هذه. +- ملاحظة الـ pool: + - أصبح إعداد Vitest الأساسي يستخدم `threads` افتراضيًا. + - كما أن إعداد Vitest المشترك يثبت `isolate: false` ويستخدم المشغّل غير المعزول عبر مشاريع الجذر وe2e وlive. + - يحتفظ مسار UI الجذري بإعداد `jsdom` والمُحسّن الخاص به، لكنه يعمل الآن أيضًا على المشغّل المشترك غير المعزول. + - يرث كل shard في `pnpm test` الافتراضيات نفسها `threads` + `isolate: false` من إعداد Vitest المشترك. + - يضيف المشغّل المشترك `scripts/run-vitest.mjs` الآن أيضًا `--no-maglev` لعمليات Node الفرعية الخاصة بـ Vitest افتراضيًا لتقليل اهتزازات ترجمة V8 أثناء التشغيلات المحلية الكبيرة. اضبط `OPENCLAW_VITEST_ENABLE_MAGLEV=1` إذا كنت بحاجة إلى المقارنة مع سلوك V8 القياسي. - ملاحظة التكرار المحلي السريع: - - يوجّه `pnpm test:changed` عبر مسارات محددة عندما ترتبط المسارات المتغيرة بوضوح بجناح أصغر. - - يحتفظ `pnpm test:max` و`pnpm test:changed:max` بسلوك التوجيه نفسه، ولكن مع حد أعلى أكبر للعمال. - - أصبح التحجيم التلقائي لعدد العمال محليًا محافظًا عمدًا الآن ويتراجع أيضًا عندما يكون متوسط حمل المضيف مرتفعًا بالفعل، بحيث تُحدث تشغيلات Vitest المتزامنة المتعددة ضررًا أقل افتراضيًا. - - يضع إعداد Vitest الأساسي ملفات projects/config كـ `forceRerunTriggers` بحيث تظل إعادة التشغيل في وضع changed صحيحة عندما تتغير أسلاك الاختبار. - - يبقي الإعداد `OPENCLAW_VITEST_FS_MODULE_CACHE` مفعّلًا على المضيفين المدعومين؛ اضبط `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` إذا كنت تريد موقع cache صريحًا واحدًا من أجل profiling مباشر. + - يوجّه `pnpm test:changed` عبر المسارات المحددة عندما ترتبط المسارات المتغيرة بوضوح بجناح أصغر. + - يحتفظ كل من `pnpm test:max` و`pnpm test:changed:max` بسلوك التوجيه نفسه، فقط مع حد أعلى أكبر للعمال. + - أصبح الضبط التلقائي لعدد العمال محليًا متحفظًا عمدًا الآن ويتراجع أيضًا عندما يكون متوسط حمل المضيف مرتفعًا بالفعل، بحيث تسبب تشغيلات Vitest المتعددة المتزامنة ضررًا أقل افتراضيًا. + - يضع إعداد Vitest الأساسي المشاريع/ملفات الإعداد كـ `forceRerunTriggers` بحيث تبقى إعادة التشغيل في وضع التغييرات صحيحة عند تغير أسلاك الاختبار. + - يُبقي الإعداد `OPENCLAW_VITEST_FS_MODULE_CACHE` مفعّلًا على المضيفين المدعومين؛ اضبط `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` إذا أردت موقع تخزين مؤقت صريحًا واحدًا لأغراض profiling المباشر. - ملاحظة تصحيح الأداء: - يفعّل `pnpm test:perf:imports` تقارير مدة الاستيراد في Vitest بالإضافة إلى مخرجات تفصيل الاستيراد. - - يقيّد `pnpm test:perf:imports:changed` عرض profiling نفسه على الملفات التي تغيّرت منذ `origin/main`. -- يقارن `pnpm test:perf:changed:bench -- --ref ` بين `test:changed` الموجّه ومسار root-project الأصلي لذلك الفرق الملتزم، ويطبع زمن الجدار بالإضافة إلى أقصى RSS على macOS. -- يختبر `pnpm test:perf:changed:bench -- --worktree` الشجرة المتسخة الحالية عبر توجيه قائمة الملفات المتغيرة إلى `scripts/test-projects.mjs` وإعداد Vitest الجذري. - - يكتب `pnpm test:perf:profile:main` ملف profile للمعالج الرئيسي لـ CPU من أجل تكلفة بدء Vitest/Vite والتحويل. - - يكتب `pnpm test:perf:profile:runner` ملفات profile لـ CPU+heap للمشغّل من أجل جناح unit مع تعطيل التوازي على مستوى الملفات. + - ويقصر `pnpm test:perf:imports:changed` عرض profiling نفسه على الملفات المتغيرة منذ `origin/main`. +- يقارن `pnpm test:perf:changed:bench -- --ref ` بين `test:changed` الموجّه ومسار root-project الأصلي لذلك الفرق الملتزم ويطبع زمن التنفيذ إضافة إلى macOS max RSS. +- يقوم `pnpm test:perf:changed:bench -- --worktree` بقياس الشجرة المتسخة الحالية عبر توجيه قائمة الملفات المتغيرة من خلال `scripts/test-projects.mjs` وإعداد root Vitest. + - يكتب `pnpm test:perf:profile:main` ملف تعريف CPU للخيط الرئيسي لوقت بدء Vitest/Vite وأعباء التحويل. + - ويكتب `pnpm test:perf:profile:runner` ملفات تعريف CPU+heap للمشغّل لجناح unit مع تعطيل التوازي على مستوى الملفات. -### E2E (فحص gateway الدخاني) +### E2E ‏(فحص gateway الأساسي) - الأمر: `pnpm test:e2e` - الإعداد: `vitest.e2e.config.ts` - الملفات: `src/**/*.e2e.test.ts` و`test/**/*.e2e.test.ts` - افتراضيات وقت التشغيل: - - يستخدم Vitest `threads` مع `isolate: false`، بما يتطابق مع بقية المستودع. + - يستخدم Vitest ‏`threads` مع `isolate: false`، بما يطابق بقية المستودع. - يستخدم عمالًا تكيفيين (CI: حتى 2، محليًا: 1 افتراضيًا). - - يعمل في الوضع الصامت افتراضيًا لتقليل تكلفة I/O في الطرفية. + - يعمل في الوضع الصامت افتراضيًا لتقليل كلفة I/O الخاصة بالطرفية. - تجاوزات مفيدة: - `OPENCLAW_E2E_WORKERS=` لفرض عدد العمال (بحد أقصى 16). - - `OPENCLAW_E2E_VERBOSE=1` لإعادة تمكين المخرجات التفصيلية في الطرفية. + - `OPENCLAW_E2E_VERBOSE=1` لإعادة تفعيل مخرجات الطرفية التفصيلية. - النطاق: - - سلوك gateway من الطرف إلى الطرف عبر عدة نُسخ - - واجهات WebSocket/HTTP، واقتران العقد، والشبكات الأثقل + - سلوك end-to-end لـ gateway متعدد المثيلات + - أسطح WebSocket/HTTP، واقتران العقد، والشبكات الأثقل - التوقعات: - - يعمل في CI (عند تمكينه في خط الأنابيب) - - لا حاجة إلى مفاتيح حقيقية - - يحتوي على أجزاء متحركة أكثر من اختبارات unit (وقد يكون أبطأ) + - يعمل في CI ‏(عند تفعيله في المسار) + - لا يتطلب مفاتيح حقيقية + - يحتوي على أجزاء متحركة أكثر من اختبارات unit ‏(وقد يكون أبطأ) -### E2E: فحص OpenShell الخلفي الدخاني +### E2E: فحص OpenShell backend الأساسي - الأمر: `pnpm test:e2e:openshell` - الملف: `test/openshell-sandbox.e2e.test.ts` - النطاق: - - يبدأ gateway OpenShell معزولًا على المضيف عبر Docker + - يبدأ OpenShell gateway معزولًا على المضيف عبر Docker - ينشئ sandbox من Dockerfile محلي مؤقت - - يختبر الواجهة الخلفية OpenShell الخاصة بـ OpenClaw عبر `sandbox ssh-config` + تنفيذ SSH حقيقي - - يتحقق من سلوك نظام الملفات canonical البعيد عبر جسر fs الخاص بـ sandbox + - يختبر OpenClaw OpenShell backend عبر `sandbox ssh-config` وSSH exec حقيقيين + - يتحقق من سلوك نظام الملفات canonical البعيد عبر جسر sandbox fs - التوقعات: - - اشتراك اختياري فقط؛ ليس جزءًا من تشغيل `pnpm test:e2e` الافتراضي - - يتطلب CLI محليًا لـ `openshell` بالإضافة إلى daemon Docker يعمل - - يستخدم `HOME` / `XDG_CONFIG_HOME` معزولين، ثم يدمّر gateway الاختباري وsandbox + - اختيارية فقط؛ ليست جزءًا من التشغيل الافتراضي `pnpm test:e2e` + - تتطلب CLI محليًا لـ `openshell` بالإضافة إلى Docker daemon عامل + - تستخدم `HOME` / `XDG_CONFIG_HOME` معزولين، ثم تدمر test gateway وsandbox - تجاوزات مفيدة: - - `OPENCLAW_E2E_OPENSHELL=1` لتمكين الاختبار عند تشغيل جناح e2e الأوسع يدويًا - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` للإشارة إلى binary CLI غير افتراضي أو script wrapper + - `OPENCLAW_E2E_OPENSHELL=1` لتفعيل الاختبار عند تشغيل جناح e2e الأوسع يدويًا + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` للإشارة إلى ملف CLI تنفيذي غير افتراضي أو wrapper script -### Live (موفّرون حقيقيون + نماذج حقيقية) +### Live ‏(موفّرون حقيقيون + نماذج حقيقية) - الأمر: `pnpm test:live` - الإعداد: `vitest.live.config.ts` - الملفات: `src/**/*.live.test.ts` -- الافتراضي: **مفعّل** بواسطة `pnpm test:live` (يضبط `OPENCLAW_LIVE_TEST=1`) +- الافتراضي: **مفعّل** بواسطة `pnpm test:live` ‏(يضبط `OPENCLAW_LIVE_TEST=1`) - النطاق: - "هل يعمل هذا الموفّر/النموذج فعلًا _اليوم_ باستخدام بيانات اعتماد حقيقية؟" - - كشف تغييرات تنسيق الموفّر، وخصائص استدعاء الأدوات، ومشكلات المصادقة، وسلوك حدود المعدل + - التقاط تغييرات تنسيق الموفّر، وخصائص استدعاء الأدوات، ومشكلات المصادقة، وسلوك حدود المعدل - التوقعات: - - غير مستقر في CI بطبيعته (شبكات حقيقية، وسياسات موفّرين حقيقية، وحصص، وأعطال) - - يكلّف أموالًا / يستهلك حدود المعدل + - ليست مستقرة في CI بطبيعتها (شبكات حقيقية، وسياسات موفّرين حقيقية، وحصص، وانقطاعات) + - تكلف مالًا / تستخدم حدود المعدل - يُفضَّل تشغيل مجموعات فرعية ضيقة بدلًا من "كل شيء" -- تستورد تشغيلات live الملف `~/.profile` لالتقاط مفاتيح API الناقصة. -- افتراضيًا، تظل تشغيلات live تعزل `HOME` وتنسخ مواد config/auth إلى home اختباري مؤقت حتى لا تتمكن fixtures الخاصة بـ unit من تعديل `~/.openclaw` الحقيقي لديك. -- اضبط `OPENCLAW_LIVE_USE_REAL_HOME=1` فقط عندما تحتاج عمدًا إلى أن تستخدم اختبارات live دليل home الحقيقي لديك. -- أصبح `pnpm test:live` يستخدم وضعًا أكثر هدوءًا افتراضيًا: فهو يبقي مخرجات التقدم `[live] ...`، لكنه يخفي الإشعار الإضافي الخاص بـ `~/.profile` ويكتم سجلات تمهيد gateway وضجيج Bonjour. اضبط `OPENCLAW_LIVE_TEST_QUIET=0` إذا أردت سجلات البدء الكاملة مجددًا. -- تدوير مفاتيح API (خاص بكل موفّر): اضبط `*_API_KEYS` بتنسيق الفاصلة/الفاصلة المنقوطة أو `*_API_KEY_1` و`*_API_KEY_2` (مثل `OPENAI_API_KEYS` و`ANTHROPIC_API_KEYS` و`GEMINI_API_KEYS`) أو تجاوزًا خاصًا بـ live عبر `OPENCLAW_LIVE_*_KEY`؛ تعيد الاختبارات المحاولة عند استجابات حدود المعدل. -- مخرجات التقدم/النبض: - - تصدر أجنحة live الآن أسطر التقدم إلى stderr بحيث تبدو استدعاءات الموفّر الطويلة نشطة بوضوح حتى عندما يكون التقاط طرفية Vitest هادئًا. - - يعطّل `vitest.live.config.ts` اعتراض طرفية Vitest بحيث تُبث أسطر تقدم الموفّر/gateway فورًا أثناء تشغيلات live. - - اضبط نبضات النماذج المباشرة بواسطة `OPENCLAW_LIVE_HEARTBEAT_MS`. - - اضبط نبضات gateway/probe بواسطة `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. +- تقوم التشغيلات الحية بتحميل `~/.profile` لالتقاط مفاتيح API المفقودة. +- افتراضيًا، لا تزال التشغيلات الحية تعزل `HOME` وتنسخ مواد config/auth إلى home اختبار مؤقت حتى لا تتمكن fixtures الخاصة بـ unit من تعديل `~/.openclaw` الحقيقي. +- اضبط `OPENCLAW_LIVE_USE_REAL_HOME=1` فقط عندما تحتاج عمدًا إلى أن تستخدم الاختبارات الحية دليل home الحقيقي. +- أصبح `pnpm test:live` افتراضيًا الآن أكثر هدوءًا: فهو يبقي على مخرجات التقدم `[live] ...`، لكنه يخفي إشعار `~/.profile` الإضافي ويكتم سجلات تمهيد gateway وضجيج Bonjour. اضبط `OPENCLAW_LIVE_TEST_QUIET=0` إذا أردت استعادة سجلات البدء الكاملة. +- تدوير مفاتيح API ‏(خاص بكل موفّر): اضبط `*_API_KEYS` بتنسيق comma/semicolon أو `*_API_KEY_1` و`*_API_KEY_2` (مثل `OPENAI_API_KEYS` و`ANTHROPIC_API_KEYS` و`GEMINI_API_KEYS`) أو تجاوزًا لكل تشغيل حي عبر `OPENCLAW_LIVE_*_KEY`؛ وتعاد محاولة الاختبارات عند استجابات حدود المعدل. +- مخرجات التقدم/heartbeat: + - تُصدر الأجنحة الحية الآن أسطر التقدم إلى stderr بحيث تبقى استدعاءات الموفّر الطويلة مرئية النشاط حتى عندما يكون التقاط طرفية Vitest هادئًا. + - يعطل `vitest.live.config.ts` اعتراض الطرفية في Vitest بحيث تُبث أسطر تقدم الموفّر/gateway مباشرة أثناء التشغيلات الحية. + - اضبط heartbeat للنماذج المباشرة عبر `OPENCLAW_LIVE_HEARTBEAT_MS`. + - واضبط heartbeat الخاص بـ gateway/probe عبر `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## أي جناح يجب أن أشغّل؟ استخدم جدول القرار هذا: -- تعديل المنطق/الاختبارات: شغّل `pnpm test` (و`pnpm test:coverage` إذا غيّرت الكثير) -- لمس شبكات gateway / بروتوكول WS / الاقتران: أضف `pnpm test:e2e` -- تصحيح "الروبوت الخاص بي متوقف" / الأعطال الخاصة بالموفّر / استدعاء الأدوات: شغّل `pnpm test:live` مضيقًا +- عند تعديل المنطق/الاختبارات: شغّل `pnpm test` ‏(و`pnpm test:coverage` إذا غيّرت الكثير) +- عند لمس شبكات gateway / بروتوكول WS / الاقتران: أضف `pnpm test:e2e` +- عند تصحيح "البوت الخاص بي متوقف" / أعطال خاصة بالموفّر / استدعاء الأدوات: شغّل `pnpm test:live` مضيقًا ## Live: مسح قدرات عقدة Android - الاختبار: `src/gateway/android-node.capabilities.live.test.ts` - السكربت: `pnpm android:test:integration` -- الهدف: استدعاء **كل أمر مُعلن عنه حاليًا** بواسطة عقدة Android متصلة والتحقق من سلوك عقد الأوامر. +- الهدف: استدعاء **كل أمر مُعلن عنه حاليًا** بواسطة عقدة Android متصلة والتحقق من سلوك عقدة الأمر. - النطاق: - إعداد مسبق/يدوي (لا يقوم الجناح بتثبيت التطبيق أو تشغيله أو إقرانه). - - تحقق `node.invoke` في gateway أمرًا بأمر لعقدة Android المحددة. + - تحقق gateway `node.invoke` أمرًا بأمر لعقدة Android المحددة. - الإعداد المسبق المطلوب: - أن يكون تطبيق Android متصلًا ومقترنًا بالفعل مع gateway. - إبقاء التطبيق في الواجهة الأمامية. - - منح الأذونات/موافقة الالتقاط للقدرات التي تتوقع نجاحها. + - منح الأذونات/الموافقة على الالتقاط للقدرات التي تتوقع نجاحها. - تجاوزات الهدف الاختيارية: - `OPENCLAW_ANDROID_NODE_ID` أو `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. -- تفاصيل إعداد Android الكاملة: [تطبيق Android](/ar/platforms/android) +- تفاصيل الإعداد الكاملة لـ Android: [Android App](/ar/platforms/android) -## Live: فحص النموذج الدخاني (مفاتيح الملفات الشخصية) +## Live: فحص النموذج الأساسي (مفاتيح الملفات الشخصية) -تنقسم اختبارات live إلى طبقتين حتى نتمكن من عزل الأعطال: +تنقسم الاختبارات الحية إلى طبقتين حتى نتمكن من عزل الأعطال: -- يخبرنا "النموذج المباشر" ما إذا كان الموفّر/النموذج قادرًا على الرد أصلًا بالمفتاح المعطى. -- يخبرنا "فحص gateway الدخاني" ما إذا كان مسار gateway+agent الكامل يعمل لهذا النموذج (الجلسات، والسجل، والأدوات، وسياسة sandbox، وغير ذلك). +- "النموذج المباشر" يخبرنا ما إذا كان الموفّر/النموذج قادرًا على الإجابة أصلًا باستخدام المفتاح المعطى. +- "فحص Gateway الأساسي" يخبرنا ما إذا كانت منظومة gateway+agent الكاملة تعمل لذلك النموذج (الجلسات، والسجل، والأدوات، وسياسة sandbox، وما إلى ذلك). -### الطبقة 1: إكمال النموذج المباشر (من دون gateway) +### الطبقة 1: إكمال مباشر للنموذج (بدون gateway) - الاختبار: `src/agents/models.profiles.live.test.ts` - الهدف: - تعداد النماذج المكتشفة - استخدام `getApiKeyForModel` لاختيار النماذج التي لديك بيانات اعتماد لها - - تشغيل إكمال صغير لكل نموذج (واختبارات انحدار مستهدفة عند الحاجة) -- كيفية التمكين: - - `pnpm test:live` (أو `OPENCLAW_LIVE_TEST=1` إذا كنت تستدعي Vitest مباشرة) -- اضبط `OPENCLAW_LIVE_MODELS=modern` (أو `all`، وهو اسم مستعار لـ modern) لتشغيل هذا الجناح فعلًا؛ وإلا فسيتم تخطيه لإبقاء `pnpm test:live` مركزًا على فحص gateway الدخاني + - تشغيل إكمال صغير لكل نموذج (واختبارات تراجعية مستهدفة عند الحاجة) +- كيفية التفعيل: + - `pnpm test:live` ‏(أو `OPENCLAW_LIVE_TEST=1` إذا كنت تستدعي Vitest مباشرة) +- اضبط `OPENCLAW_LIVE_MODELS=modern` ‏(أو `all`، وهو اسم بديل لـ modern) لتشغيل هذا الجناح فعليًا؛ وإلا فسيُتخطى ليبقي `pnpm test:live` مركزًا على فحص gateway الأساسي - كيفية اختيار النماذج: - - `OPENCLAW_LIVE_MODELS=modern` لتشغيل allowlist الحديثة (Opus/Sonnet 4.6+، وGPT-5.x + Codex، وGemini 3، وGLM 4.7، وMiniMax M2.7، وGrok 4) - - `OPENCLAW_LIVE_MODELS=all` هو اسم مستعار لـ allowlist الحديثة - - أو `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist مفصولة بفواصل) + - `OPENCLAW_LIVE_MODELS=modern` لتشغيل قائمة السماح الحديثة (Opus/Sonnet 4.6+، وGPT-5.x + Codex، وGemini 3، وGLM 4.7، وMiniMax M2.7، وGrok 4) + - `OPENCLAW_LIVE_MODELS=all` هو اسم بديل لقائمة السماح الحديثة + - أو `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` ‏(قائمة سماح مفصولة بفواصل) - كيفية اختيار الموفّرين: - - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist مفصولة بفواصل) + - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` ‏(قائمة سماح مفصولة بفواصل) - من أين تأتي المفاتيح: - - افتراضيًا: من مخزن الملفات الشخصية وبدائل env + - افتراضيًا: من مخزن الملفات الشخصية وبدائل البيئة - اضبط `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` لفرض **مخزن الملفات الشخصية** فقط -- سبب وجود هذا: - - يفصل بين "API الموفّر معطّل / المفتاح غير صالح" و"خط أنابيب gateway agent معطّل" - - يحتوي على اختبارات انحدار صغيرة ومعزولة (مثال: تشغيلات OpenAI Responses/Codex Responses الخاصة بإعادة reasoning + تدفقات استدعاء الأدوات) +- لماذا هذا موجود: + - يفصل بين "API الموفّر معطوب / المفتاح غير صالح" و"منظومة gateway agent معطوبة" + - يحتوي اختبارات تراجعية صغيرة ومعزولة (مثال: تدفقات replay + tool-call الخاصة بـ OpenAI Responses/Codex Responses reasoning) -### الطبقة 2: فحص gateway + dev agent الدخاني (ما الذي يفعله "@openclaw" فعليًا) +### الطبقة 2: فحص Gateway + وكيل dev الأساسي (ما الذي يفعله "@openclaw" فعليًا) - الاختبار: `src/gateway/gateway-models.profiles.live.test.ts` - الهدف: - تشغيل gateway داخل العملية - - إنشاء/ترقيع جلسة `agent:dev:*` (مع تجاوز النموذج لكل تشغيل) - - التكرار على النماذج التي لها مفاتيح والتحقق من: - - استجابة "ذات معنى" (من دون أدوات) - - عمل استدعاء أداة حقيقي (فحص read) - - فحوص أدوات إضافية اختيارية (فحص exec+read) - - استمرار عمل مسارات الانحدار الخاصة بـ OpenAI (استدعاء أدوات فقط → متابعة) -- تفاصيل الفحص (حتى تتمكن من شرح الأعطال بسرعة): - - فحص `read`: يكتب الاختبار ملف nonce في مساحة العمل ويطلب من العامل أن يستخدم `read` له ويعيد nonce. - - فحص `exec+read`: يطلب الاختبار من العامل أن يكتب nonce باستخدام `exec` في ملف مؤقت، ثم يستخدم `read` له. - - فحص الصورة: يرفق الاختبار PNG مُنشأً (قطة + رمز عشوائي) ويتوقع من النموذج أن يعيد `cat `. + - إنشاء/ترقيع جلسة `agent:dev:*` ‏(مع تجاوز النموذج لكل تشغيل) + - التكرار عبر النماذج ذات المفاتيح والتحقق من: + - استجابة "ذات معنى" ‏(من دون أدوات) + - أن استدعاء أداة حقيقي يعمل (`read` probe) + - probes إضافية اختيارية للأدوات (`exec+read` probe) + - استمرار عمل مسارات OpenAI التراجعية (استدعاء-أداة-فقط → متابعة) +- تفاصيل الـ probe ‏(حتى تتمكن من شرح الأعطال بسرعة): + - probe ‏`read`: يكتب الاختبار ملف nonce في workspace ويطلب من الوكيل `read` له وإرجاع nonce. + - probe ‏`exec+read`: يطلب الاختبار من الوكيل كتابة nonce عبر `exec` في ملف مؤقت، ثم `read` له. + - probe الصورة: يرفق الاختبار PNG مولدًا (`cat` + رمز عشوائي) ويتوقع من النموذج إرجاع `cat `. - مرجع التنفيذ: `src/gateway/gateway-models.profiles.live.test.ts` و`src/gateway/live-image-probe.ts`. -- كيفية التمكين: - - `pnpm test:live` (أو `OPENCLAW_LIVE_TEST=1` إذا كنت تستدعي Vitest مباشرة) +- كيفية التفعيل: + - `pnpm test:live` ‏(أو `OPENCLAW_LIVE_TEST=1` إذا كنت تستدعي Vitest مباشرة) - كيفية اختيار النماذج: - - الافتراضي: allowlist الحديثة (Opus/Sonnet 4.6+، وGPT-5.x + Codex، وGemini 3، وGLM 4.7، وMiniMax M2.7، وGrok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` هو اسم مستعار لـ allowlist الحديثة - - أو اضبط `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (أو قائمة مفصولة بفواصل) للتضييق -- كيفية اختيار الموفّرين (لتجنب "كل شيء في OpenRouter"): - - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist مفصولة بفواصل) -- تكون فحوص الأدوات + الصور مفعلة دائمًا في هذا الاختبار الحي: - - فحص `read` + فحص `exec+read` (ضغط على الأدوات) - - يعمل فحص الصورة عندما يعلن النموذج دعم إدخال الصور - - التدفق (بمستوى عالٍ): - - ينشئ الاختبار PNG صغيرًا يحتوي على "CAT" + رمز عشوائي (`src/gateway/live-image-probe.ts`) - - يرسله عبر `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - - تحلل gateway المرفقات إلى `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - يمرّر العامل المضمّن رسالة مستخدم متعددة الوسائط إلى النموذج - - التحقق: يحتوي الرد على `cat` + الرمز (سماحية OCR: يُسمح بأخطاء طفيفة) + - الافتراضي: قائمة السماح الحديثة (Opus/Sonnet 4.6+، وGPT-5.x + Codex، وGemini 3، وGLM 4.7، وMiniMax M2.7، وGrok 4) + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` هو اسم بديل لقائمة السماح الحديثة + - أو اضبط `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` ‏(أو قائمة مفصولة بفواصل) للتضييق +- كيفية اختيار الموفّرين (لتجنب "كل شيء عبر OpenRouter"): + - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` ‏(قائمة سماح مفصولة بفواصل) +- تكون أدوات وصور probe مفعلة دائمًا في هذا الاختبار الحي: + - probe ‏`read` + probe ‏`exec+read` ‏(ضغط الأدوات) + - يعمل probe الصورة عندما يعلن النموذج دعمه لمدخلات الصور + - التدفق (على مستوى عالٍ): + - يولد الاختبار PNG صغيرًا يحمل "CAT" + رمزًا عشوائيًا (`src/gateway/live-image-probe.ts`) + - يرسله عبر `agent` ‏`attachments: [{ mimeType: "image/png", content: "" }]` + - يحلل Gateway المرفقات إلى `images[]` ‏(`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - يمرر الوكيل المضمن رسالة مستخدم متعددة الوسائط إلى النموذج + - التحقق: تحتوي الاستجابة على `cat` + الرمز (سماحية OCR: يُسمح بأخطاء طفيفة) -نصيحة: لرؤية ما يمكنك اختباره على جهازك (ومعرّفات `provider/model` الدقيقة)، شغّل: +نصيحة: لمعرفة ما الذي يمكنك اختباره على جهازك (ومعرّفات `provider/model` الدقيقة)، شغّل: ```bash openclaw models list openclaw models list --json ``` -## Live: فحص الواجهة الخلفية CLI الدخاني (Codex CLI أو واجهات CLI محلية أخرى) +## Live: فحص CLI backend الأساسي (Claude أو Codex أو Gemini أو غيرها من CLI المحلية) - الاختبار: `src/gateway/gateway-cli-backend.live.test.ts` -- الهدف: التحقق من خط أنابيب Gateway + agent باستخدام واجهة خلفية CLI محلية، من دون لمس إعداداتك الافتراضية. -- التمكين: - - `pnpm test:live` (أو `OPENCLAW_LIVE_TEST=1` إذا كنت تستدعي Vitest مباشرة) +- الهدف: التحقق من منظومة Gateway + agent باستخدام CLI backend محلي، من دون لمس الإعدادات الافتراضية. +- تعيش افتراضيات الفحص الخاصة بكل backend مع تعريف `cli-backend.ts` العائد إلى extension المالكة. +- التفعيل: + - `pnpm test:live` ‏(أو `OPENCLAW_LIVE_TEST=1` إذا كنت تستدعي Vitest مباشرة) - `OPENCLAW_LIVE_CLI_BACKEND=1` - الافتراضيات: - - النموذج: `codex-cli/gpt-5.4` - - الأمر: `codex` - - الوسائط: `["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]` + - الموفّر/النموذج الافتراضي: `claude-cli/claude-sonnet-4-6` + - تأتي سلوكيات command/args/image من بيانات plugin metadata الخاصة بـ CLI backend المالكة. - التجاوزات (اختيارية): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` لإرسال مرفق صورة حقيقي (تُحقن المسارات في التوجيه). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` لتمرير مسارات ملفات الصور كوسائط CLI بدلًا من حقنها في التوجيه. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (أو `"list"`) للتحكم في كيفية تمرير وسائط الصور عندما يكون `IMAGE_ARG` مضبوطًا. - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` لإرسال منعطف ثانٍ والتحقق من تدفق الاستئناف. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` لإرسال مرفق صورة حقيقي (يتم حقن المسارات في المطالبة). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` لتمرير مسارات ملفات الصور كوسائط CLI بدلًا من حقنها في المطالبة. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` ‏(أو `"list"`) للتحكم في كيفية تمرير وسائط الصورة عندما يكون `IMAGE_ARG` مضبوطًا. + - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` لإرسال دورة ثانية والتحقق من تدفق الاستئناف. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` لتعطيل probe الاستمرارية الافتراضي داخل الجلسة نفسها من Claude Sonnet إلى Opus ‏(اضبطه إلى `1` لفرضه عندما يدعم النموذج المحدد هدف تبديل). مثال: @@ -294,28 +295,38 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \ pnpm test:docker:live-cli-backend ``` +وصفات Docker لموفّر واحد: + +```bash +pnpm test:docker:live-cli-backend:claude +pnpm test:docker:live-cli-backend:codex +pnpm test:docker:live-cli-backend:gemini +``` + ملاحظات: -- يوجد مشغل Docker في `scripts/test-live-cli-backend-docker.sh`. -- يشغّل فحص الواجهة الخلفية CLI الحي داخل صورة Docker الخاصة بالمستودع كمستخدم `node` غير الجذر. -- بالنسبة إلى `codex-cli`، فإنه يثبت حزمة Linux الخاصة بـ `@openai/codex` في بادئة قابلة للكتابة ومخزنة مؤقتًا عند `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (الافتراضي: `~/.cache/openclaw/docker-cli-tools`). +- يعيش مشغّل Docker في `scripts/test-live-cli-backend-docker.sh`. +- يشغّل فحص CLI-backend الحي داخل صورة Docker الخاصة بالمستودع بوصف المستخدم غير الجذر `node`. +- يحل بيانات smoke metadata الخاصة بـ CLI من extension المالكة، ثم يثبت حزمة Linux CLI المطابقة (`@anthropic-ai/claude-code` أو `@openai/codex` أو `@google/gemini-cli`) في prefix قابل للكتابة ومخبأ مؤقتًا في `OPENCLAW_DOCKER_CLI_TOOLS_DIR` ‏(الافتراضي: `~/.cache/openclaw/docker-cli-tools`). +- يمارس فحص CLI-backend الحي الآن التدفق نفسه من طرف إلى طرف لـ Claude وCodex وGemini: دورة نصية، ودورة تصنيف صور، ثم استدعاء أداة MCP ‏`cron` يتم التحقق منه عبر gateway CLI. +- يقوم الفحص الافتراضي لـ Claude أيضًا بترقيع الجلسة من Sonnet إلى Opus ويتحقق من أن الجلسة المستأنفة لا تزال تتذكر ملاحظة سابقة. -## Live: فحص ACP bind الدخاني (`/acp spawn ... --bind here`) +## Live: فحص ACP bind الأساسي (`/acp spawn ... --bind here`) - الاختبار: `src/gateway/gateway-acp-bind.live.test.ts` -- الهدف: التحقق من تدفق ربط المحادثة ACP الحقيقي مع عامل ACP حي: +- الهدف: التحقق من تدفق ربط المحادثة ACP الحقيقي مع وكيل ACP حي: - إرسال `/acp spawn --bind here` - - ربط محادثة قناة رسائل اصطناعية في مكانها - - إرسال متابعة عادية على نفس المحادثة - - التحقق من وصول المتابعة إلى نص جلسة ACP المرتبطة -- التمكين: + - ربط محادثة channel اصطناعية في مكانها + - إرسال متابعة عادية على تلك المحادثة نفسها + - التحقق من أن المتابعة تهبط في transcript الخاص بجلسة ACP المرتبطة +- التفعيل: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - الافتراضيات: - - عوامل ACP في Docker: `claude,codex,gemini` - - عامل ACP للاستخدام المباشر مع `pnpm test:live ...`: `claude` - - قناة اصطناعية: سياق محادثة على نمط Slack DM - - الواجهة الخلفية ACP: `acpx` + - وكلاء ACP في Docker: ‏`claude,codex,gemini` + - وكيل ACP لتشغيل `pnpm test:live ...` المباشر: `claude` + - قناة اصطناعية: سياق محادثة بأسلوب Slack DM + - ACP backend: `acpx` - التجاوزات: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` @@ -323,8 +334,8 @@ pnpm test:docker:live-cli-backend - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - ملاحظات: - - يستخدم هذا المسار واجهة `chat.send` في gateway مع حقول synthetic originating-route الخاصة بالمشرف فقط حتى تتمكن الاختبارات من إرفاق سياق قناة الرسائل من دون الادعاء بتسليم خارجي. - - عندما لا يكون `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` مضبوطًا، يستخدم الاختبار سجل العوامل المضمّن في plugin `acpx` المحدد لعامل ACP harness المختار. + - يستخدم هذا المسار سطح gateway ‏`chat.send` مع حقول originating-route اصطناعية خاصة بالمسؤول فقط بحيث تتمكن الاختبارات من إرفاق سياق message-channel من دون التظاهر بتوصيل خارجي. + - عندما لا يكون `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` مضبوطًا، يستخدم الاختبار سجل الوكلاء المضمن المدمج في plugin ‏`acpx` لوكيل ACP التجريبي المحدد. مثال: @@ -340,7 +351,7 @@ OPENCLAW_LIVE_ACP_BIND=1 \ pnpm test:docker:live-acp-bind ``` -وصفات Docker لعامل واحد: +وصفات Docker لوكيل واحد: ```bash pnpm test:docker:live-acp-bind:claude @@ -350,142 +361,142 @@ pnpm test:docker:live-acp-bind:gemini ملاحظات Docker: -- يوجد مشغل Docker في `scripts/test-live-acp-bind-docker.sh`. -- افتراضيًا، يشغّل فحص ACP bind الدخاني مقابل جميع عوامل CLI الحية المدعومة بالتسلسل: `claude` ثم `codex` ثم `gemini`. +- يعيش مشغّل Docker في `scripts/test-live-acp-bind-docker.sh`. +- يشغّل فحص ACP bind الأساسي افتراضيًا على كل وكلاء CLI الحية المدعومة بالتتابع: `claude` ثم `codex` ثم `gemini`. - استخدم `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude` أو `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` أو `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` لتضييق المصفوفة. -- يستورد `~/.profile`، ويجهّز مواد مصادقة CLI المطابقة داخل الحاوية، ويثبت `acpx` في بادئة npm قابلة للكتابة، ثم يثبت CLI الحي المطلوب (`@anthropic-ai/claude-code` أو `@openai/codex` أو `@google/gemini-cli`) إذا كان مفقودًا. -- داخل Docker، يضبط المشغل `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` حتى يحتفظ acpx بمتغيرات env الخاصة بالموفّر من الملف profile المستورد متاحة لواجهة harness CLI الفرعية. +- يقوم بتحميل `~/.profile`، وتهيئة مواد مصادقة CLI المطابقة داخل الحاوية، وتثبيت `acpx` في npm prefix قابل للكتابة، ثم يثبت CLI الحي المطلوب (`@anthropic-ai/claude-code` أو `@openai/codex` أو `@google/gemini-cli`) إذا كان مفقودًا. +- داخل Docker، يضبط المشغّل `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` بحيث يحتفظ acpx بمتغيرات بيئة الموفّر القادمة من profile المحمّل ومتاحة لـ harness CLI الابن. ### وصفات live الموصى بها -تكون allowlist الضيقة والصريحة أسرع وأقل عرضة للتقلب: +قوائم السماح الضيقة والصريحة هي الأسرع والأقل تعرضًا للتعطل: -- نموذج واحد، مباشر (من دون gateway): +- نموذج واحد، مباشر (بدون gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- نموذج واحد، فحص gateway دخاني: +- نموذج واحد، فحص gateway الأساسي: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - استدعاء الأدوات عبر عدة موفّرين: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- تركيز Google (مفتاح Gemini API + Antigravity): - - Gemini (مفتاح API): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - - Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` +- التركيز على Google ‏(مفتاح Gemini API + Antigravity): + - Gemini ‏(مفتاح API): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` + - Antigravity ‏(OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` ملاحظات: -- يستخدم `google/...` Gemini API (مفتاح API). -- يستخدم `google-antigravity/...` جسر Antigravity OAuth (نقطة نهاية عامل على نمط Cloud Code Assist). -- يستخدم `google-gemini-cli/...` Gemini CLI المحلية على جهازك (مصادقة منفصلة وخصائص أدوات مختلفة). +- يستخدم `google/...` واجهة Gemini API ‏(مفتاح API). +- يستخدم `google-antigravity/...` جسر Antigravity OAuth ‏(نقطة نهاية وكيل بأسلوب Cloud Code Assist). +- يستخدم `google-gemini-cli/...` Gemini CLI المحلي على جهازك (مصادقة منفصلة وخصائص أدوات مختلفة). - Gemini API مقابل Gemini CLI: - - API: يستدعي OpenClaw Gemini API المستضافة من Google عبر HTTP (مصادقة مفتاح API / profile)؛ وهذا هو ما يقصده معظم المستخدمين بـ "Gemini". - - CLI: يقوم OpenClaw باستدعاء binary محلي باسم `gemini`؛ ولديه مصادقة خاصة به وقد يتصرف بشكل مختلف (البث/دعم الأدوات/اختلاف الإصدارات). + - API: يستدعي OpenClaw واجهة Gemini API المستضافة من Google عبر HTTP ‏(مصادقة مفتاح API / profile)؛ وهذا ما يقصده معظم المستخدمين عندما يقولون "Gemini". + - CLI: يستدعي OpenClaw ملف `gemini` التنفيذي المحلي؛ وله مصادقته الخاصة وقد يتصرف بشكل مختلف (البث/دعم الأدوات/اختلاف الإصدارات). ## Live: مصفوفة النماذج (ما الذي نغطيه) -لا توجد "قائمة نماذج CI" ثابتة (لأن live اختياري)، ولكن هذه هي النماذج **الموصى بها** للتغطية بانتظام على جهاز تطوير يحتوي على مفاتيح. +لا توجد "قائمة نماذج CI" ثابتة (إذ إن live اختيارية)، لكن هذه هي النماذج **الموصى بها** للتغطية بانتظام على جهاز تطوير يملك مفاتيح. ### مجموعة الفحص الحديثة (استدعاء الأدوات + الصور) -هذا هو تشغيل "النماذج الشائعة" الذي نتوقع أن يبقى عاملًا: +هذا هو تشغيل "النماذج الشائعة" الذي نتوقع أن يستمر في العمل: -- OpenAI (غير Codex): `openai/gpt-5.4` (اختياري: `openai/gpt-5.4-mini`) -- OpenAI Codex: `openai-codex/gpt-5.4` -- Anthropic: `anthropic/claude-opus-4-6` (أو `anthropic/claude-sonnet-4-6`) -- Google (Gemini API): `google/gemini-3.1-pro-preview` و`google/gemini-3-flash-preview` (تجنب نماذج Gemini 2.x الأقدم) -- Google (Antigravity): `google-antigravity/claude-opus-4-6-thinking` و`google-antigravity/gemini-3-flash` -- Z.AI (GLM): `zai/glm-4.7` -- MiniMax: `minimax/MiniMax-M2.7` +- OpenAI ‏(غير Codex): ‏`openai/gpt-5.4` ‏(اختياري: `openai/gpt-5.4-mini`) +- OpenAI Codex: ‏`openai-codex/gpt-5.4` +- Anthropic: ‏`anthropic/claude-opus-4-6` ‏(أو `anthropic/claude-sonnet-4-6`) +- Google ‏(Gemini API): ‏`google/gemini-3.1-pro-preview` و`google/gemini-3-flash-preview` ‏(تجنب نماذج Gemini 2.x الأقدم) +- Google ‏(Antigravity): ‏`google-antigravity/claude-opus-4-6-thinking` و`google-antigravity/gemini-3-flash` +- Z.AI ‏(GLM): ‏`zai/glm-4.7` +- MiniMax: ‏`minimax/MiniMax-M2.7` -شغّل فحص gateway الدخاني مع الأدوات + الصور: +شغّل فحص gateway الأساسي مع الأدوات + الصورة: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` ### الأساس: استدعاء الأدوات (Read + Exec اختياري) -اختر واحدًا على الأقل من كل عائلة موفّرين: +اختر واحدة على الأقل من كل عائلة موفّرين: -- OpenAI: `openai/gpt-5.4` (أو `openai/gpt-5.4-mini`) -- Anthropic: `anthropic/claude-opus-4-6` (أو `anthropic/claude-sonnet-4-6`) -- Google: `google/gemini-3-flash-preview` (أو `google/gemini-3.1-pro-preview`) -- Z.AI (GLM): `zai/glm-4.7` -- MiniMax: `minimax/MiniMax-M2.7` +- OpenAI: ‏`openai/gpt-5.4` ‏(أو `openai/gpt-5.4-mini`) +- Anthropic: ‏`anthropic/claude-opus-4-6` ‏(أو `anthropic/claude-sonnet-4-6`) +- Google: ‏`google/gemini-3-flash-preview` ‏(أو `google/gemini-3.1-pro-preview`) +- Z.AI ‏(GLM): ‏`zai/glm-4.7` +- MiniMax: ‏`minimax/MiniMax-M2.7` تغطية إضافية اختيارية (من الجيد توفرها): -- xAI: `xai/grok-4` (أو أحدث إصدار متاح) -- Mistral: `mistral/`… (اختر نموذجًا واحدًا قادرًا على "tools" ومفعّلًا لديك) -- Cerebras: `cerebras/`… (إذا كان لديك وصول) -- LM Studio: `lmstudio/`… (محلي؛ يعتمد استدعاء الأدوات على وضع API) +- xAI: ‏`xai/grok-4` ‏(أو أحدث إصدار متاح) +- Mistral: ‏`mistral/`… ‏(اختر نموذجًا واحدًا قادرًا على "tools" لديك مفعّلًا) +- Cerebras: ‏`cerebras/`… ‏(إذا كان لديك وصول) +- LM Studio: ‏`lmstudio/`… ‏(محلي؛ يعتمد استدعاء الأدوات على وضع API) ### الرؤية: إرسال صورة (مرفق ← رسالة متعددة الوسائط) -ضمّن نموذجًا واحدًا على الأقل قادرًا على التعامل مع الصور في `OPENCLAW_LIVE_GATEWAY_MODELS` (أحد إصدارات Claude/Gemini/OpenAI القادرة على الرؤية، إلخ) لتشغيل فحص الصورة. +ضمّن نموذجًا واحدًا على الأقل قادرًا على الصور في `OPENCLAW_LIVE_GATEWAY_MODELS` ‏(Claude/Gemini/OpenAI ذات القدرات البصرية، وغيرها) لتفعيل probe الصورة. -### المجمعات / البوابات البديلة +### المجمّعات / البوابات البديلة -إذا كانت لديك مفاتيح مفعّلة، فنحن ندعم أيضًا الاختبار عبر: +إذا كانت لديك مفاتيح مفعلة، فنحن ندعم أيضًا الاختبار عبر: -- OpenRouter: `openrouter/...` (مئات النماذج؛ استخدم `openclaw models scan` للعثور على مرشحين قادرين على الأدوات+الصور) -- OpenCode: `opencode/...` لـ Zen و`opencode-go/...` لـ Go (المصادقة عبر `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) +- OpenRouter: ‏`openrouter/...` ‏(مئات النماذج؛ استخدم `openclaw models scan` للعثور على مرشحين قادرين على الأدوات+الصور) +- OpenCode: ‏`opencode/...` لـ Zen و`opencode-go/...` لـ Go ‏(المصادقة عبر `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -موفّرون إضافيون يمكنك تضمينهم في مصفوفة live (إذا كانت لديك بيانات الاعتماد/الإعدادات): +موفّرون آخرون يمكنك تضمينهم في مصفوفة live ‏(إذا كانت لديك بيانات الاعتماد/الإعدادات): - المضمنة: `openai` و`openai-codex` و`anthropic` و`google` و`google-vertex` و`google-antigravity` و`google-gemini-cli` و`zai` و`openrouter` و`opencode` و`opencode-go` و`xai` و`groq` و`cerebras` و`mistral` و`github-copilot` -- عبر `models.providers` (نقاط نهاية مخصصة): `minimax` (سحابي/API)، بالإضافة إلى أي proxy متوافق مع OpenAI/Anthropic (مثل LM Studio وvLLM وLiteLLM وغيرها) +- عبر `models.providers` ‏(نقاط نهاية مخصصة): `minimax` ‏(سحابي/API)، بالإضافة إلى أي proxy متوافق مع OpenAI/Anthropic ‏(LM Studio، وvLLM، وLiteLLM، وما إلى ذلك) -نصيحة: لا تحاول تثبيت "كل النماذج" بشكل صارم في الوثائق. القائمة الموثوقة هي أي شيء تُعيده `discoverModels(...)` على جهازك + أي مفاتيح متاحة. +نصيحة: لا تحاول ترميز "كل النماذج" في الوثائق بشكل صلب. القائمة المرجعية الموثوقة هي ما تُرجعه `discoverModels(...)` على جهازك + أي مفاتيح متاحة. -## بيانات الاعتماد (لا تلتزم بها أبدًا) +## بيانات الاعتماد (لا تُلتزم أبدًا) -تكتشف اختبارات live بيانات الاعتماد بالطريقة نفسها التي يفعلها CLI. الآثار العملية: +تكتشف الاختبارات الحية بيانات الاعتماد بالطريقة نفسها التي يفعلها CLI. والنتائج العملية لذلك: -- إذا كانت CLI تعمل، فيجب أن تعثر اختبارات live على المفاتيح نفسها. -- إذا قال اختبار live "لا توجد بيانات اعتماد"، فقم بالتصحيح بالطريقة نفسها التي ستصحح بها `openclaw models list` / اختيار النموذج. +- إذا كان CLI يعمل، فيجب أن تجد الاختبارات الحية المفاتيح نفسها. +- إذا قال اختبار حي "لا توجد بيانات اعتماد"، فقم بالتصحيح بالطريقة نفسها التي تُصحّح بها `openclaw models list` / اختيار النموذج. -- ملفات مصادقة التعريفات الخاصة بكل عامل: `~/.openclaw/agents//agent/auth-profiles.json` (وهذا ما تعنيه "مفاتيح الملف الشخصي" في اختبارات live) -- الإعدادات: `~/.openclaw/openclaw.json` (أو `OPENCLAW_CONFIG_PATH`) -- دليل الحالة القديم: `~/.openclaw/credentials/` (يُنسخ إلى home الحي المرحلي عند وجوده، لكنه ليس مخزن مفاتيح الملف الشخصي الرئيسي) -- تقوم تشغيلات live المحلية بنسخ الإعدادات النشطة، وملفات `auth-profiles.json` الخاصة بكل عامل، و`credentials/` القديمة، وأدلة مصادقة CLI الخارجية المدعومة إلى home اختباري مؤقت افتراضيًا؛ وتُزال تجاوزات المسار `agents.*.workspace` / `agentDir` في هذا config المرحلي بحيث تبقى الفحوص بعيدًا عن مساحة العمل الحقيقية على المضيف. +- ملفات المصادقة الشخصية لكل وكيل: `~/.openclaw/agents//agent/auth-profiles.json` ‏(هذا ما تعنيه "profile keys" في الاختبارات الحية) +- الإعدادات: `~/.openclaw/openclaw.json` ‏(أو `OPENCLAW_CONFIG_PATH`) +- دليل الحالة القديم: `~/.openclaw/credentials/` ‏(يُنسخ إلى home الحي المرحلي عند وجوده، لكن ليس مخزن مفاتيح الملفات الشخصية الرئيسي) +- تقوم التشغيلات الحية المحلية بنسخ الإعدادات النشطة وملفات `auth-profiles.json` لكل وكيل و`credentials/` القديمة وأدلة مصادقة CLI الخارجية المدعومة إلى home اختبار مؤقت افتراضيًا؛ وتتخطى homes الحية المرحلية `workspace/` و`sandboxes/`، كما تُزال تجاوزات المسارات `agents.*.workspace` / `agentDir` بحيث تبقى probes بعيدة عن workspace الحقيقي للمضيف. -إذا أردت الاعتماد على مفاتيح env (مثلًا تلك المصدّرة في `~/.profile`)، فشغّل الاختبارات المحلية بعد `source ~/.profile`، أو استخدم مشغلات Docker أدناه (يمكنها تحميل `~/.profile` داخل الحاوية). +إذا كنت تريد الاعتماد على مفاتيح البيئة (مثلًا المصدّرة في `~/.profile`)، فشغّل الاختبارات المحلية بعد `source ~/.profile`، أو استخدم مشغلات Docker أدناه (يمكنها تركيب `~/.profile` داخل الحاوية). -## Deepgram live (نسخ الصوت) +## Deepgram live ‏(نسخ صوتي) - الاختبار: `src/media-understanding/providers/deepgram/audio.live.test.ts` -- التمكين: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` +- التفعيل: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` ## BytePlus coding plan live - الاختبار: `src/agents/byteplus.live.test.ts` -- التمكين: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` +- التفعيل: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` - تجاوز النموذج الاختياري: `BYTEPLUS_CODING_MODEL=ark-code-latest` ## ComfyUI workflow media live - الاختبار: `extensions/comfy/comfy.live.test.ts` -- التمكين: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` +- التفعيل: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - النطاق: - - يختبر مسارات الصور والفيديو و`music_generate` المضمنة في comfy - - يتخطى كل قدرة ما لم يتم ضبط `models.providers.comfy.` - - مفيد بعد تغيير إرسال workflow الخاص بـ comfy، أو polling، أو التنزيلات، أو تسجيل plugin + - يختبر مسارات comfy المضمنة للصور والفيديو و`music_generate` + - يتخطى كل قدرة ما لم يكن `models.providers.comfy.` مهيأ + - مفيد بعد تعديل إرسال workflow في comfy، أو polling، أو التنزيلات، أو تسجيل plugin ## Image generation live - الاختبار: `src/image-generation/runtime.live.test.ts` - الأمر: `pnpm test:live src/image-generation/runtime.live.test.ts` -- الـ Harness: `pnpm test:live:media image` +- الحاضنة: `pnpm test:live:media image` - النطاق: - - يعدّد كل plugin موفّر لتوليد الصور مسجّل - - يحمّل متغيرات env الخاصة بالموفّر الناقصة من shell تسجيل الدخول لديك (`~/.profile`) قبل الفحص - - يستخدم مفاتيح API الحية/من env قبل ملفات المصادقة المخزنة افتراضيًا، بحيث لا تحجب مفاتيح الاختبار القديمة في `auth-profiles.json` بيانات اعتماد shell الحقيقية + - يعدد كل provider plugin مسجل لتوليد الصور + - يحمّل متغيرات بيئة الموفّر المفقودة من login shell الخاص بك (`~/.profile`) قبل الفحص + - يستخدم مفاتيح API الحية/البيئية قبل ملفات المصادقة الشخصية المخزنة افتراضيًا، حتى لا تحجب مفاتيح الاختبار القديمة في `auth-profiles.json` بيانات الاعتماد الحقيقية في shell - يتخطى الموفّرين الذين لا يملكون مصادقة/ملفًا شخصيًا/نموذجًا صالحًا - يشغّل متغيرات توليد الصور القياسية عبر قدرة وقت التشغيل المشتركة: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- الموفّرون المضمنون المغطّون حاليًا: +- الموفّرون المضمنون الحاليون المشمولون: - `openai` - `google` - تضييق اختياري: @@ -493,200 +504,201 @@ pnpm test:docker:live-acp-bind:gemini - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` - سلوك مصادقة اختياري: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` لفرض مصادقة مخزن الملف الشخصي وتجاهل تجاوزات env فقط + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` لفرض مصادقة مخزن الملفات الشخصية وتجاهل التجاوزات البيئية فقط ## Music generation live - الاختبار: `extensions/music-generation-providers.live.test.ts` -- التمكين: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` -- الـ Harness: `pnpm test:live:media music` +- التفعيل: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` +- الحاضنة: `pnpm test:live:media music` - النطاق: - - يختبر مسار موفّر توليد الموسيقى المضمن المشترك + - يختبر مسار music-generation provider المضمن المشترك - يغطي حاليًا Google وMiniMax - - يحمّل متغيرات env الخاصة بالموفّر من shell تسجيل الدخول لديك (`~/.profile`) قبل الفحص - - يستخدم مفاتيح API الحية/من env قبل ملفات المصادقة المخزنة افتراضيًا، بحيث لا تحجب مفاتيح الاختبار القديمة في `auth-profiles.json` بيانات اعتماد shell الحقيقية + - يحمّل متغيرات بيئة الموفّر من login shell الخاص بك (`~/.profile`) قبل الفحص + - يستخدم مفاتيح API الحية/البيئية قبل ملفات المصادقة الشخصية المخزنة افتراضيًا، حتى لا تحجب مفاتيح الاختبار القديمة في `auth-profiles.json` بيانات الاعتماد الحقيقية في shell - يتخطى الموفّرين الذين لا يملكون مصادقة/ملفًا شخصيًا/نموذجًا صالحًا - - يشغّل وضعي وقت التشغيل المعلنين عند توفرهما: - - `generate` بإدخال قائم على prompt فقط + - يشغّل وضعي وقت التشغيل المعلنين كليهما عند توفرهما: + - `generate` مع مدخلات تعتمد على prompt فقط - `edit` عندما يعلن الموفّر `capabilities.edit.enabled` - - التغطية الحالية للمسار المشترك: - - `google`: `generate` و`edit` - - `minimax`: `generate` - - `comfy`: ملف Comfy live منفصل، وليس هذا المسح المشترك + - التغطية الحالية في المسار المشترك: + - `google`: ‏`generate`، ‏`edit` + - `minimax`: ‏`generate` + - `comfy`: ملف Comfy حي منفصل، وليس هذا المسح المشترك - تضييق اختياري: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` - سلوك مصادقة اختياري: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` لفرض مصادقة مخزن الملف الشخصي وتجاهل تجاوزات env فقط + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` لفرض مصادقة مخزن الملفات الشخصية وتجاهل التجاوزات البيئية فقط ## Video generation live - الاختبار: `extensions/video-generation-providers.live.test.ts` -- التمكين: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` -- الـ Harness: `pnpm test:live:media video` +- التفعيل: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` +- الحاضنة: `pnpm test:live:media video` - النطاق: - - يختبر مسار موفّر توليد الفيديو المضمن المشترك - - يحمّل متغيرات env الخاصة بالموفّر من shell تسجيل الدخول لديك (`~/.profile`) قبل الفحص - - يستخدم مفاتيح API الحية/من env قبل ملفات المصادقة المخزنة افتراضيًا، بحيث لا تحجب مفاتيح الاختبار القديمة في `auth-profiles.json` بيانات اعتماد shell الحقيقية + - يختبر مسار video-generation provider المضمن المشترك + - يحمّل متغيرات بيئة الموفّر من login shell الخاص بك (`~/.profile`) قبل الفحص + - يستخدم مفاتيح API الحية/البيئية قبل ملفات المصادقة الشخصية المخزنة افتراضيًا، حتى لا تحجب مفاتيح الاختبار القديمة في `auth-profiles.json` بيانات الاعتماد الحقيقية في shell - يتخطى الموفّرين الذين لا يملكون مصادقة/ملفًا شخصيًا/نموذجًا صالحًا - - يشغّل وضعي وقت التشغيل المعلنين عند توفرهما: - - `generate` بإدخال قائم على prompt فقط - - `imageToVideo` عندما يعلن الموفّر `capabilities.imageToVideo.enabled` ويقبل الموفّر/النموذج المحدد إدخال صور محلية مدعومًا بمخزن مؤقت في المسح المشترك - - `videoToVideo` عندما يعلن الموفّر `capabilities.videoToVideo.enabled` ويقبل الموفّر/النموذج المحدد إدخال فيديو محلي مدعومًا بمخزن مؤقت في المسح المشترك - - موفّرو `imageToVideo` المعلنون حاليًا لكن المتخطون في المسح المشترك: + - يشغّل وضعي وقت التشغيل المعلنين كليهما عند توفرهما: + - `generate` مع مدخلات تعتمد على prompt فقط + - `imageToVideo` عندما يعلن الموفّر `capabilities.imageToVideo.enabled` ويقبل الموفّر/النموذج المحدد إدخال الصور المحلية المعتمد على buffer في المسح المشترك + - `videoToVideo` عندما يعلن الموفّر `capabilities.videoToVideo.enabled` ويقبل الموفّر/النموذج المحدد إدخال الفيديو المحلي المعتمد على buffer في المسح المشترك + - موفّرو `imageToVideo` المعلن عنهم حاليًا لكن المتخطَّين في المسح المشترك: - `vydra` لأن `veo3` المضمن نصي فقط و`kling` المضمن يتطلب URL صورة بعيدًا - - تغطية Vydra الخاصة بالموفّر: + - تغطية Vydra الخاصة بكل موفّر: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - يشغّل ذلك الملف `veo3` لتحويل النص إلى فيديو بالإضافة إلى مسار `kling` يستخدم fixture لعنوان URL صورة بعيد افتراضيًا - - تغطية `videoToVideo` الحالية في live: + - يشغّل هذا الملف `veo3` من نص إلى فيديو بالإضافة إلى مسار `kling` يستخدم fixture لعنوان URL صورة بعيد افتراضيًا + - التغطية الحية الحالية لـ `videoToVideo`: - `runway` فقط عندما يكون النموذج المحدد هو `runway/gen4_aleph` - - موفّرو `videoToVideo` المعلنون حاليًا لكن المتخطون في المسح المشترك: - - `alibaba` و`qwen` و`xai` لأن هذه المسارات تتطلب حاليًا عناوين URL مرجعية بعيدة من نوع `http(s)` / MP4 - - `google` لأن مسار Gemini/Veo المشترك الحالي يستخدم إدخالًا محليًا مدعومًا بمخزن مؤقت، وهذا المسار غير مقبول في المسح المشترك - - `openai` لأن المسار المشترك الحالي يفتقر إلى ضمانات الوصول الخاصة بالمؤسسة الخاصة بـ video inpaint/remix + - موفّرو `videoToVideo` المعلن عنهم حاليًا لكن المتخطَّين في المسح المشترك: + - `alibaba` و`qwen` و`xai` لأن هذه المسارات تتطلب حاليًا عناوين URL مرجعية بعيدة `http(s)` / MP4 + - `google` لأن مسار Gemini/Veo المشترك الحالي يستخدم مدخلات محلية معتمدة على buffer وهذا المسار غير مقبول في المسح المشترك + - `openai` لأن المسار المشترك الحالي يفتقر إلى ضمانات الوصول الخاصة بالمؤسسة لـ video inpaint/remix - تضييق اختياري: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - سلوك مصادقة اختياري: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` لفرض مصادقة مخزن الملف الشخصي وتجاهل تجاوزات env فقط + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` لفرض مصادقة مخزن الملفات الشخصية وتجاهل التجاوزات البيئية فقط ## Media live harness - الأمر: `pnpm test:live:media` - الغرض: - - يشغّل أجنحة live المشتركة للصور والموسيقى والفيديو عبر نقطة دخول أصلية واحدة في المستودع - - يحمّل تلقائيًا متغيرات env الخاصة بالموفّر الناقصة من `~/.profile` - - يضيّق كل جناح تلقائيًا إلى الموفّرين الذين يملكون حاليًا مصادقة قابلة للاستخدام افتراضيًا - - يعيد استخدام `scripts/test-live.mjs`، بحيث يظل سلوك النبض والوضع الهادئ متسقًا + - يشغّل أجنحة image وmusic وvideo الحية المشتركة عبر نقطة دخول أصلية للمستودع + - يحمّل تلقائيًا متغيرات بيئة الموفّر المفقودة من `~/.profile` + - يضيّق تلقائيًا كل جناح إلى الموفّرين الذين لديهم حاليًا مصادقة قابلة للاستخدام افتراضيًا + - يعيد استخدام `scripts/test-live.mjs`، بحيث يبقى سلوك heartbeat والوضع الهادئ متسقًا - أمثلة: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## مشغلات Docker (فحوص "يعمل على Linux" الاختيارية) +## مشغلات Docker ‏(اختيارية لفحوصات "يعمل على Linux") تنقسم مشغلات Docker هذه إلى فئتين: -- مشغلات النماذج الحية: `test:docker:live-models` و`test:docker:live-gateway` يشغّلان فقط ملف live المطابق لمفاتيح الملفات الشخصية داخل صورة Docker الخاصة بالمستودع (`src/agents/models.profiles.live.test.ts` و`src/gateway/gateway-models.profiles.live.test.ts`)، مع تحميل دليل config المحلي ومساحة العمل (واستيراد `~/.profile` إن تم تحميله). نقاط الدخول المحلية المطابقة هي `test:live:models-profiles` و`test:live:gateway-profiles`. -- تستخدم مشغلات Docker الحية حدًا أصغر للفحص الدخاني افتراضيًا حتى يبقى المسح الكامل داخل Docker عمليًا: - يضبط `test:docker:live-models` افتراضيًا `OPENCLAW_LIVE_MAX_MODELS=12`، كما يضبط - `test:docker:live-gateway` افتراضيًا `OPENCLAW_LIVE_GATEWAY_SMOKE=1`، +- مشغلات النماذج الحية: يشغّل `test:docker:live-models` و`test:docker:live-gateway` فقط ملف live الخاص بمفاتيح الملفات الشخصية المطابق لهما داخل صورة Docker الخاصة بالمستودع (`src/agents/models.profiles.live.test.ts` و`src/gateway/gateway-models.profiles.live.test.ts`) مع تركيب دليل الإعدادات المحلي وworkspace ‏(وتحميل `~/.profile` إذا تم تركيبه). ونقطتا الدخول المحليتان المطابقتان هما `test:live:models-profiles` و`test:live:gateway-profiles`. +- تستخدم مشغلات Docker الحية افتراضيًا حدًا أصغر للفحص حتى يظل المسح الكامل في Docker عمليًا: + يستخدم `test:docker:live-models` افتراضيًا `OPENCLAW_LIVE_MAX_MODELS=12`، و + يستخدم `test:docker:live-gateway` افتراضيًا `OPENCLAW_LIVE_GATEWAY_SMOKE=1`، و`OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`، و`OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000`، و - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. تجاوز متغيرات env هذه عندما - تريد صراحةً المسح الأكبر والأشمل. -- يقوم `test:docker:all` ببناء صورة Docker الحية مرة واحدة عبر `test:docker:live-build`، ثم يعيد استخدامها لمساري Docker الحيين. -- مشغلات فحص الحاويات الدخاني: `test:docker:openwebui` و`test:docker:onboard` و`test:docker:gateway-network` و`test:docker:mcp-channels` و`test:docker:plugins` تشغّل حاوية واحدة أو أكثر حقيقية وتتحقق من مسارات integration أعلى مستوى. + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. تجاوز متغيرات البيئة هذه عندما + تريد عمدًا المسح الأكبر والأشمل. +- يقوم `test:docker:all` ببناء صورة Docker الحية مرة واحدة عبر `test:docker:live-build`، ثم يعيد استخدامها للمسارين الحيين في Docker. +- مشغلات الفحص داخل الحاويات: تقلع `test:docker:openwebui` و`test:docker:onboard` و`test:docker:gateway-network` و`test:docker:mcp-channels` و`test:docker:plugins` حاوية واحدة أو أكثر حقيقية وتتحقق من مسارات integration أعلى مستوى. -تقوم مشغلات Docker الخاصة بالنماذج الحية أيضًا بربط وتحميل منازل مصادقة CLI المطلوبة فقط (أو جميع المنازل المدعومة عندما لا يكون التشغيل مضيقًا)، ثم تنسخها إلى home الحاوية قبل التشغيل حتى تتمكن OAuth الخاصة بـ CLI الخارجي من تحديث الرموز من دون تعديل مخزن المصادقة على المضيف: +كما تقوم مشغلات Docker الخاصة بالنماذج الحية بتركيب homes مصادقة CLI المطلوبة فقط (أو جميعها عندما لا يكون التشغيل مضيقًا)، ثم تنسخها إلى home الحاوية قبل التشغيل حتى تتمكن OAuth الخاصة بـ external-CLI من تحديث الرموز دون تعديل مخزن مصادقة المضيف: -- النماذج المباشرة: `pnpm test:docker:live-models` (السكربت: `scripts/test-live-models-docker.sh`) -- فحص ACP bind الدخاني: `pnpm test:docker:live-acp-bind` (السكربت: `scripts/test-live-acp-bind-docker.sh`) -- فحص الواجهة الخلفية CLI الدخاني: `pnpm test:docker:live-cli-backend` (السكربت: `scripts/test-live-cli-backend-docker.sh`) -- Gateway + dev agent: `pnpm test:docker:live-gateway` (السكربت: `scripts/test-live-gateway-models-docker.sh`) -- فحص Open WebUI الحي الدخاني: `pnpm test:docker:openwebui` (السكربت: `scripts/e2e/openwebui-docker.sh`) -- معالج onboarding (TTY، تهيئة كاملة): `pnpm test:docker:onboard` (السكربت: `scripts/e2e/onboard-docker.sh`) -- شبكات Gateway (حاويتان، مصادقة WS + health): `pnpm test:docker:gateway-network` (السكربت: `scripts/e2e/gateway-network-docker.sh`) -- جسر قناة MCP (Gateway مزروع + جسر stdio + فحص إطار إشعارات Claude الخام): `pnpm test:docker:mcp-channels` (السكربت: `scripts/e2e/mcp-channels-docker.sh`) -- Plugins (فحص التثبيت الدخاني + الاسم المستعار `/plugin` + دلالات إعادة تشغيل Claude-bundle): `pnpm test:docker:plugins` (السكربت: `scripts/e2e/plugins-docker.sh`) +- النماذج المباشرة: `pnpm test:docker:live-models` ‏(السكربت: `scripts/test-live-models-docker.sh`) +- فحص ACP bind الأساسي: `pnpm test:docker:live-acp-bind` ‏(السكربت: `scripts/test-live-acp-bind-docker.sh`) +- فحص CLI backend الأساسي: `pnpm test:docker:live-cli-backend` ‏(السكربت: `scripts/test-live-cli-backend-docker.sh`) +- Gateway + وكيل dev: ‏`pnpm test:docker:live-gateway` ‏(السكربت: `scripts/test-live-gateway-models-docker.sh`) +- Open WebUI live smoke: ‏`pnpm test:docker:openwebui` ‏(السكربت: `scripts/e2e/openwebui-docker.sh`) +- معالج onboarding ‏(TTY، والتهيئة الكاملة): `pnpm test:docker:onboard` ‏(السكربت: `scripts/e2e/onboard-docker.sh`) +- شبكات Gateway ‏(حاويتان، ومصادقة WS + السلامة): `pnpm test:docker:gateway-network` ‏(السكربت: `scripts/e2e/gateway-network-docker.sh`) +- جسر قناة MCP ‏(Gateway مهيأ مسبقًا + stdio bridge + فحص Claude raw notification-frame): ‏`pnpm test:docker:mcp-channels` ‏(السكربت: `scripts/e2e/mcp-channels-docker.sh`) +- Plugins ‏(فحص التثبيت + الاسم البديل `/plugin` + دلالات إعادة تشغيل Claude-bundle): ‏`pnpm test:docker:plugins` ‏(السكربت: `scripts/e2e/plugins-docker.sh`) -تقوم مشغلات Docker الخاصة بالنماذج الحية أيضًا بربط checkout الحالي بوضع القراءة فقط -وتجهيزه في workdir مؤقت داخل الحاوية. وهذا يبقي صورة وقت التشغيل -خفيفة مع الاستمرار في تشغيل Vitest على مصدر/config المحليين لديك كما هما. -تتخطى خطوة التجهيز الذاكرات المؤقتة المحلية الكبيرة ومخرجات بناء التطبيقات مثل -`.pnpm-store` و`.worktrees` و`__openclaw_vitest__` وأدلة `.build` المحلية للتطبيقات أو مخرجات Gradle -حتى لا تقضي تشغيلات Docker live دقائق في نسخ آثار خاصة بالجهاز. -كما أنها تضبط `OPENCLAW_SKIP_CHANNELS=1` حتى لا تبدأ فحوص gateway الحية -عمّال القنوات الحقيقية مثل Telegram/Discord وغيرهما داخل الحاوية. -لا يزال `test:docker:live-models` يشغّل `pnpm test:live`، لذا مرّر +كما تقوم مشغلات Docker الخاصة بالنماذج الحية بتركيب النسخة الحالية من المستودع للقراءة فقط +وتهيئتها داخل دليل عمل مؤقت داخل الحاوية. وهذا يبقي صورة وقت التشغيل +نحيفة مع الاستمرار في تشغيل Vitest على المصدر/الإعدادات المحلية الدقيقة لديك. +وتتخطى خطوة التهيئة مخازن التخزين المؤقت المحلية الكبيرة ومخرجات بناء التطبيق مثل +`.pnpm-store` و`.worktrees` و`__openclaw_vitest__` وأدلة `.build` المحلية للتطبيق أو +مجلدات مخرجات Gradle، حتى لا تقضي تشغيلات Docker الحية دقائق في نسخ +أصول خاصة بالجهاز. +كما تضبط `OPENCLAW_SKIP_CHANNELS=1` حتى لا تبدأ probes الحية الخاصة بـ gateway +عمّال قنوات Telegram/Discord/... حقيقيين داخل الحاوية. +ولا يزال `test:docker:live-models` يشغّل `pnpm test:live`، لذا مرّر `OPENCLAW_LIVE_GATEWAY_*` أيضًا عندما تحتاج إلى تضييق أو استبعاد تغطية gateway -الحية من مسار Docker هذا. -يُعد `test:docker:openwebui` فحص توافق دخاني على مستوى أعلى: فهو يبدأ -حاوية gateway لـ OpenClaw مع تمكين نقاط نهاية HTTP المتوافقة مع OpenAI، -ثم يبدأ حاوية Open WebUI مثبتة الإصدار مقابل تلك gateway، ويسجّل الدخول عبر +الحية من مسار Docker ذاك. +أما `test:docker:openwebui` فهو فحص توافق أعلى مستوى: إذ يبدأ +حاوية OpenClaw gateway مع تفعيل نقاط نهاية HTTP المتوافقة مع OpenAI، +ثم يبدأ حاوية Open WebUI مثبتة ضد تلك gateway، ويسجل الدخول عبر Open WebUI، ويتحقق من أن `/api/models` يعرض `openclaw/default`، ثم يرسل -طلب chat حقيقيًا عبر proxy `Open WebUI` الخاص بـ `/api/chat/completions`. +طلب chat حقيقيًا عبر proxy ‏`/api/chat/completions` في Open WebUI. قد يكون التشغيل الأول أبطأ بشكل ملحوظ لأن Docker قد يحتاج إلى سحب -صورة Open WebUI وقد يحتاج Open WebUI إلى إكمال إعداد البدء البارد الخاص به. -يتوقع هذا المسار مفتاح نموذج حيًا صالحًا، ويُعد `OPENCLAW_PROFILE_FILE` -(`~/.profile` افتراضيًا) هو الطريقة الأساسية لتوفيره في التشغيلات عبر Docker. +صورة Open WebUI وقد يحتاج Open WebUI إلى إنهاء إعداد البدء البارد الخاص به. +يتوقع هذا المسار وجود مفتاح نموذج حي صالح، ويُعد `OPENCLAW_PROFILE_FILE` +‏(`~/.profile` افتراضيًا) الوسيلة الأساسية لتوفيره في التشغيلات المعتمدة على Docker. تطبع التشغيلات الناجحة حمولة JSON صغيرة مثل `{ "ok": true, "model": "openclaw/default", ... }`. أما `test:docker:mcp-channels` فهو حتمي عمدًا ولا يحتاج إلى -حساب Telegram أو Discord أو iMessage حقيقي. فهو يشغّل حاوية Gateway مزروعة، -ويبدأ حاوية ثانية تشغّل `openclaw mcp serve`، ثم -يتحقق من اكتشاف المحادثات الموجّهة، وقراءات النصوص، وبيانات تعريف المرفقات، -وسلوك طابور الأحداث الحية، وتوجيه الإرسال الصادر، وإشعارات القنوات + -الأذونات على نمط Claude عبر جسر stdio MCP الحقيقي. ويفحص فحص الإشعارات -إطارات stdio MCP الخام مباشرة بحيث يتحقق الفحص الدخاني مما يصدره الجسر -فعليًا، وليس فقط مما تعرِضه حزمة SDK معينة من عميل ما. +حساب Telegram أو Discord أو iMessage حقيقي. فهو يقلع حاوية Gateway +مهيأة مسبقًا، ويبدأ حاوية ثانية تشغّل `openclaw mcp serve`، ثم +يتحقق من اكتشاف المحادثات الموجّهة، وقراءة transcripts، وmetadata الخاصة بالمرفقات، +وسلوك قائمة الأحداث الحية، وتوجيه الإرسال الصادر، وإشعارات القنوات + +الأذونات بأسلوب Claude عبر جسر stdio MCP الحقيقي. ويفحص تحقق الإشعارات +إطارات stdio MCP الخام مباشرة بحيث يتحقق الفحص مما يصدره الجسر فعليًا، +وليس فقط مما قد تكشفه مجموعة أدوات عميل معينة. -فحص يدوي بلغة عادية لخيط ACP (ليس في CI): +فحص ACP اليدوي للخيوط بلغة طبيعية (ليس ضمن CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- احتفظ بهذا السكربت من أجل سير عمل الانحدار/التصحيح. قد تكون هناك حاجة إليه مرة أخرى للتحقق من توجيه خيوط ACP، لذا لا تحذفه. +- احتفظ بهذا السكربت لمسارات العمل الخاصة بالاختبارات التراجعية/التصحيح. فقد تكون هناك حاجة إليه مرة أخرى للتحقق من توجيه خيوط ACP، لذلك لا تحذفه. -متغيرات env مفيدة: +متغيرات بيئة مفيدة: -- `OPENCLAW_CONFIG_DIR=...` (الافتراضي: `~/.openclaw`) يُحمَّل إلى `/home/node/.openclaw` -- `OPENCLAW_WORKSPACE_DIR=...` (الافتراضي: `~/.openclaw/workspace`) يُحمَّل إلى `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (الافتراضي: `~/.profile`) يُحمَّل إلى `/home/node/.profile` ويُستورد قبل تشغيل الاختبارات -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (الافتراضي: `~/.cache/openclaw/docker-cli-tools`) يُحمَّل إلى `/home/node/.npm-global` لتخزين تثبيتات CLI مؤقتًا داخل Docker -- تُحمَّل أدلة/ملفات مصادقة CLI الخارجية تحت `$HOME` بوضع القراءة فقط تحت `/host-auth...`، ثم تُنسخ إلى `/home/node/...` قبل بدء الاختبارات +- `OPENCLAW_CONFIG_DIR=...` ‏(الافتراضي: `~/.openclaw`) يُركّب إلى `/home/node/.openclaw` +- `OPENCLAW_WORKSPACE_DIR=...` ‏(الافتراضي: `~/.openclaw/workspace`) يُركّب إلى `/home/node/.openclaw/workspace` +- `OPENCLAW_PROFILE_FILE=...` ‏(الافتراضي: `~/.profile`) يُركّب إلى `/home/node/.profile` ويُحمّل قبل تشغيل الاختبارات +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` ‏(الافتراضي: `~/.cache/openclaw/docker-cli-tools`) يُركّب إلى `/home/node/.npm-global` لتثبيتات CLI المخبأة داخل Docker +- تُركّب أدلة/ملفات مصادقة CLI الخارجية تحت `$HOME` للقراءة فقط ضمن `/host-auth...`، ثم تُنسخ إلى `/home/node/...` قبل بدء الاختبارات - الأدلة الافتراضية: `.minimax` - الملفات الافتراضية: `~/.codex/auth.json` و`~/.codex/config.toml` و`.claude.json` و`~/.claude/.credentials.json` و`~/.claude/settings.json` و`~/.claude/settings.local.json` - - تركّب التشغيلات المضيقة للمزوّدين الأدلة/الملفات المطلوبة فقط والمستنتجة من `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - تجاوز ذلك يدويًا عبر `OPENCLAW_DOCKER_AUTH_DIRS=all` أو `OPENCLAW_DOCKER_AUTH_DIRS=none` أو قائمة مفصولة بفواصل مثل `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` + - التشغيلات المضيقة بحسب الموفّر تركّب فقط الأدلة/الملفات المطلوبة المستنتجة من `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - تجاوز يدويًا عبر `OPENCLAW_DOCKER_AUTH_DIRS=all` أو `OPENCLAW_DOCKER_AUTH_DIRS=none` أو قائمة مفصولة بفواصل مثل `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` لتضييق التشغيل - `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` لتصفية الموفّرين داخل الحاوية -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` لضمان أن تأتي بيانات الاعتماد من مخزن الملف الشخصي (وليس env) -- `OPENCLAW_OPENWEBUI_MODEL=...` لاختيار النموذج الذي تعرِضه gateway لفحص Open WebUI الدخاني -- `OPENCLAW_OPENWEBUI_PROMPT=...` لتجاوز prompt فحص nonce المستخدم بواسطة فحص Open WebUI الدخاني +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` لضمان أن بيانات الاعتماد تأتي من مخزن الملفات الشخصية (وليس من البيئة) +- `OPENCLAW_OPENWEBUI_MODEL=...` لاختيار النموذج الذي تعرضه gateway لفحص Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...` لتجاوز مطالبة التحقق بالـ nonce المستخدمة في فحص Open WebUI - `OPENWEBUI_IMAGE=...` لتجاوز وسم صورة Open WebUI المثبتة ## سلامة الوثائق -شغّل فحوص الوثائق بعد تعديلها: `pnpm check:docs`. -وشغّل تحقق الروابط والمراسي الكامل في Mintlify عندما تحتاج أيضًا إلى فحوص عناوين الصفحة الداخلية: `pnpm docs:check-links:anchors`. +شغّل فحوصات الوثائق بعد تعديلها: `pnpm check:docs`. +وشغّل التحقق الكامل من anchors الخاصة بـ Mintlify عندما تحتاج إلى فحوصات عناوين داخل الصفحة أيضًا: `pnpm docs:check-links:anchors`. -## اختبارات الانحدار دون اتصال (آمنة لـ CI) +## اختبار تراجعي دون اتصال (آمن على CI) -هذه اختبارات انحدار "لخط أنابيب حقيقي" من دون موفّرين حقيقيين: +هذه اختبارات تراجعية "لمنظومة حقيقية" من دون موفّرين حقيقيين: -- استدعاء أدوات gateway (OpenAI وهمي، gateway + agent loop حقيقيتان): `src/gateway/gateway.test.ts` (الحالة: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- معالج gateway (WS `wizard.start`/`wizard.next`، مع فرض كتابة config + auth): `src/gateway/gateway.test.ts` (الحالة: "runs wizard over ws and writes auth token config") +- استدعاء أدوات Gateway ‏(OpenAI وهمي، وgateway حقيقية + حلقة agent): ‏`src/gateway/gateway.test.ts` ‏(الحالة: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Gateway wizard ‏(‏`wizard.start`/`wizard.next` عبر WS، ويكتب config + auth المفروضة): ‏`src/gateway/gateway.test.ts` ‏(الحالة: "runs wizard over ws and writes auth token config") -## تقييمات موثوقية العامل (Skills) +## تقييمات موثوقية الوكيل (Skills) -لدينا بالفعل بعض الاختبارات الآمنة لـ CI التي تتصرف مثل "تقييمات موثوقية العامل": +لدينا بالفعل بعض الاختبارات الآمنة على CI التي تتصرف مثل "تقييمات موثوقية الوكيل": -- استدعاء أدوات وهمي عبر gateway + agent loop الحقيقيتين (`src/gateway/gateway.test.ts`). -- تدفقات wizard من الطرف إلى الطرف التي تتحقق من أسلاك الجلسة وتأثيرات الإعدادات (`src/gateway/gateway.test.ts`). +- استدعاء أدوات وهمي عبر gateway الحقيقية + حلقة agent ‏(`src/gateway/gateway.test.ts`). +- تدفقات wizard من طرف إلى طرف تتحقق من توصيل الجلسة وآثار الإعدادات (`src/gateway/gateway.test.ts`). -ما لا يزال مفقودًا بالنسبة إلى Skills (راجع [Skills](/ar/tools/skills)): +ما الذي لا يزال مفقودًا لـ Skills ‏(انظر [Skills](/ar/tools/skills)): -- **اتخاذ القرار:** عندما تُدرج Skills في التوجيه، هل يختار العامل Skill الصحيحة (أو يتجنب غير ذات الصلة)؟ -- **الامتثال:** هل يقرأ العامل `SKILL.md` قبل الاستخدام ويتبع الخطوات/الوسائط المطلوبة؟ -- **عقود سير العمل:** سيناريوهات متعددة المنعطفات تؤكد ترتيب الأدوات، واستمرار سجل الجلسة، وحدود sandbox. +- **اتخاذ القرار:** عندما تُسرد Skills في المطالبة، هل يختار الوكيل Skill الصحيحة (أو يتجنب غير ذات الصلة)؟ +- **الامتثال:** هل يقرأ الوكيل `SKILL.md` قبل الاستخدام ويلتزم بالخطوات/الوسائط المطلوبة؟ +- **عقود مسار العمل:** سيناريوهات متعددة الأدوار تتحقق من ترتيب الأدوات، واستمرار سجل الجلسة، وحدود sandbox. -يجب أن تظل التقييمات المستقبلية حتمية أولًا: +يجب أن تبقى التقييمات المستقبلية حتمية أولًا: -- مشغل سيناريوهات يستخدم موفّرين وهميين لتأكيد استدعاءات الأدوات + ترتيبها، وقراءات ملفات Skills، وأسلاك الجلسة. -- مجموعة صغيرة من السيناريوهات المركزة على Skills (استخدام مقابل تجنّب، والبوابات، وحقن التوجيه). -- تقييمات live اختيارية (محكومة بالبيئة ومشتركة بالاشتراك) فقط بعد اكتمال الجناح الآمن لـ CI. +- مشغّل سيناريوهات يستخدم موفّرين وهميين للتحقق من استدعاءات الأدوات + ترتيبها، وقراءات ملف skill، وتوصيل الجلسة. +- مجموعة صغيرة من السيناريوهات المركزة على skill ‏(استخدم مقابل تجنب، والبوابات، وحقن المطالبات). +- تقييمات حية اختيارية ‏(مفعلة اختياريًا، ومحكومة بمتغيرات البيئة) فقط بعد توفر الجناح الآمن على CI. ## اختبارات العقود (شكل plugin وchannel) -تتحقق اختبارات العقود من أن كل plugin وchannel مسجلين يتوافقان مع -عقد الواجهة الخاص بهما. وهي تتكرر على كل plugins المكتشفة وتشغّل مجموعة من -التحققات الخاصة بالشكل والسلوك. يتخطى مسار unit الافتراضي في `pnpm test` -هذه الملفات المشتركة الخاصة بالحدود والفحوص الدخانية عمدًا؛ شغّل أوامر العقود -صراحةً عندما تلمس أسطح channel أو provider المشتركة. +تتحقق اختبارات العقود من أن كل plugin وchannel مسجلين يطابقان +عقد الواجهة الخاص بهما. فهي تكرّر على جميع plugins المكتشفة وتشغّل مجموعة من +التحققات الخاصة بالشكل والسلوك. ويتخطى مسار unit الافتراضي `pnpm test` +هذه الملفات المشتركة الخاصة بالحدود والفحوصات الأساسية عمدًا؛ شغّل أوامر العقود صراحة +عندما تلمس أسطح channel أو provider المشتركة. ### الأوامر -- جميع العقود: `pnpm test:contracts` +- كل العقود: `pnpm test:contracts` - عقود القنوات فقط: `pnpm test:contracts:channels` - عقود الموفّرين فقط: `pnpm test:contracts:plugins` @@ -694,30 +706,30 @@ Open WebUI، ويتحقق من أن `/api/models` يعرض `openclaw/default`، تقع في `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - الشكل الأساسي لـ plugin (id، والاسم، والقدرات) +- **plugin** - الشكل الأساسي لـ plugin ‏(id، والاسم، والقدرات) - **setup** - عقد معالج الإعداد - **session-binding** - سلوك ربط الجلسة - **outbound-payload** - بنية حمولة الرسالة - **inbound** - معالجة الرسائل الواردة - **actions** - معالجات إجراءات القناة -- **threading** - التعامل مع معرّف الخيط -- **directory** - واجهة API الخاصة بالدليل/القائمة +- **threading** - معالجة معرّف الخيط +- **directory** - API الدليل/القائمة - **group-policy** - فرض سياسة المجموعات -### عقود حالة الموفّر +### عقود حالة الموفّرين تقع في `src/plugins/contracts/*.contract.test.ts`. -- **status** - فحوص حالة القنوات +- **status** - probes حالة القناة - **registry** - شكل سجل plugin -### عقود الموفّر +### عقود الموفّرين تقع في `src/plugins/contracts/*.contract.test.ts`: - **auth** - عقد تدفق المصادقة -- **auth-choice** - اختيار/تحديد المصادقة -- **catalog** - واجهة API لفهرس النماذج +- **auth-choice** - اختيار/انتقاء المصادقة +- **catalog** - API كتالوج النماذج - **discovery** - اكتشاف plugin - **loader** - تحميل plugin - **runtime** - وقت تشغيل الموفّر @@ -726,21 +738,21 @@ Open WebUI، ويتحقق من أن `/api/models` يعرض `openclaw/default`، ### متى تُشغَّل -- بعد تغيير تصديرات `plugin-sdk` أو المسارات الفرعية الخاصة به -- بعد إضافة plugin قناة أو موفّر أو تعديلها +- بعد تغيير صادرات `plugin-sdk` أو المسارات الفرعية +- بعد إضافة أو تعديل channel أو provider plugin - بعد إعادة هيكلة تسجيل plugin أو اكتشافها تعمل اختبارات العقود في CI ولا تتطلب مفاتيح API حقيقية. -## إضافة اختبارات انحدار (إرشادات) +## إضافة اختبارات تراجعية (إرشادات) -عندما تصلح مشكلة موفّر/نموذج تم اكتشافها في live: +عندما تصلح مشكلة في موفّر/نموذج اكتُشفت في live: -- أضف اختبار انحدار آمنًا لـ CI إن أمكن (موفّر وهمي/مزيف، أو التقاط تحويل شكل الطلب الدقيق) -- إذا كانت المشكلة حية بطبيعتها فقط (حدود المعدل، وسياسات المصادقة)، فاجعل اختبار live ضيقًا واختياريًا عبر متغيرات env -- فضّل استهداف أصغر طبقة تلتقط الخطأ: +- أضف اختبارًا تراجعيًا آمنًا على CI إن أمكن (موفّر وهمي/مُحاكى، أو التقط التحويل الدقيق لشكل الطلب) +- إذا كانت بطبيعتها حية فقط (حدود المعدل، وسياسات المصادقة)، فأبقِ الاختبار الحي ضيقًا ومفعّلًا اختياريًا عبر متغيرات البيئة +- افضّل استهداف أصغر طبقة تلتقط الخطأ: - خطأ في تحويل/إعادة تشغيل طلب الموفّر → اختبار النماذج المباشرة - - خطأ في خط أنابيب جلسة/sجل/أداة gateway → فحص gateway live دخاني أو اختبار gateway وهمي وآمن لـ CI + - خطأ في منظومة جلسة/سجل/أداة gateway → فحص gateway الحي الأساسي أو اختبار gateway mock آمن على CI - حاجز اجتياز SecretRef: - - يشتق `src/secrets/exec-secret-ref-id-parity.test.ts` هدفًا نموذجيًا واحدًا لكل فئة SecretRef من بيانات تعريف السجل (`listSecretTargetRegistryEntries()`)، ثم يتحقق من رفض معرّفات exec الخاصة بمقاطع الاجتياز. - - إذا أضفت عائلة هدف SecretRef جديدة من نوع `includeInPlan` في `src/secrets/target-registry-data.ts`، فحدّث `classifyTargetClass` في ذلك الاختبار. يفشل الاختبار عمدًا عند وجود معرّفات أهداف غير مصنفة حتى لا يمكن تخطي الفئات الجديدة بصمت. + - يقوم `src/secrets/exec-secret-ref-id-parity.test.ts` باشتقاق هدف مُعين واحد لكل فئة SecretRef من metadata الخاصة بالسجل (`listSecretTargetRegistryEntries()`)، ثم يتحقق من رفض معرّفات exec لمقاطع الاجتياز. + - إذا أضفت عائلة هدف SecretRef جديدة ضمن `includeInPlan` في `src/secrets/target-registry-data.ts`، فحدّث `classifyTargetClass` في ذلك الاختبار. ويفشل الاختبار عمدًا عند وجود معرّفات أهداف غير مصنفة حتى لا يمكن تخطي الفئات الجديدة بصمت. diff --git a/docs/ar/help/troubleshooting.md b/docs/ar/help/troubleshooting.md index 34c6e2c0a..6354f8341 100644 --- a/docs/ar/help/troubleshooting.md +++ b/docs/ar/help/troubleshooting.md @@ -1,25 +1,25 @@ --- read_when: - - OpenClaw لا يعمل وأنت تحتاج إلى أسرع مسار للإصلاح - - أنت تريد تدفق فرز أولي قبل الغوص في أدلة التشغيل التفصيلية -summary: مركز استكشاف الأخطاء وإصلاحها وفق الأعراض أولًا لـ OpenClaw + - لا يعمل OpenClaw وتحتاج إلى أسرع طريق إلى حل + - تريد مسار فرز أولي قبل التعمق في أدلة التشغيل التفصيلية +summary: مركز استكشاف الأخطاء وإصلاحها في OpenClaw وفقًا للأعراض أولًا title: استكشاف الأخطاء وإصلاحها العام x-i18n: - generated_at: "2026-04-05T12:46:17Z" + generated_at: "2026-04-08T02:16:50Z" model: gpt-5.4 provider: openai - source_hash: 23ae9638af5edf5a5e0584ccb15ba404223ac3b16c2d62eb93b2c9dac171c252 + source_hash: 8abda90ef80234c2f91a51c5e1f2c004d4a4da12a5d5631b5927762550c6d5e3 source_path: help/troubleshooting.md workflow: 15 --- # استكشاف الأخطاء وإصلاحها -إذا لم يكن لديك سوى دقيقتين، فاستخدم هذه الصفحة كبوابة فرز أولية. +إذا كان لديك دقيقتان فقط، فاستخدم هذه الصفحة كنقطة دخول سريعة للفرز الأولي. ## أول 60 ثانية -شغّل هذا التسلسل بالترتيب نفسه: +شغّل هذا التسلسل بالترتيب تمامًا: ```bash openclaw status @@ -33,25 +33,41 @@ openclaw logs --follow المخرجات الجيدة في سطر واحد: -- `openclaw status` ← يعرض القنوات المهيأة ولا توجد أخطاء auth واضحة. -- `openclaw status --all` ← التقرير الكامل موجود وقابل للمشاركة. -- `openclaw gateway probe` ← الهدف المتوقع للبوابة قابل للوصول (`Reachable: yes`). إن `RPC: limited - missing scope: operator.read` يعني تشخيصات متدهورة، وليس فشل اتصال. -- `openclaw gateway status` ← `Runtime: running` و`RPC probe: ok`. -- `openclaw doctor` ← لا توجد أخطاء إعداد/خدمة مانعة. -- `openclaw channels status --probe` ← عندما تكون البوابة قابلة للوصول، يعرض حالة النقل الحية لكل حساب بالإضافة إلى نتائج الفحص/التدقيق مثل `works` أو `audit ok`؛ وإذا كانت - البوابة غير قابلة للوصول، يرجع الأمر إلى ملخصات تعتمد على الإعدادات فقط. -- `openclaw logs --follow` ← نشاط مستقر، ولا توجد أخطاء قاتلة متكررة. +- `openclaw status` → يعرض القنوات المهيأة ولا توجد أخطاء مصادقة واضحة. +- `openclaw status --all` → التقرير الكامل موجود وقابل للمشاركة. +- `openclaw gateway probe` → هدف البوابة المتوقع يمكن الوصول إليه (`Reachable: yes`). يشير `RPC: limited - missing scope: operator.read` إلى تشخيصات متدهورة، وليس إلى فشل في الاتصال. +- `openclaw gateway status` → `Runtime: running` و`RPC probe: ok`. +- `openclaw doctor` → لا توجد أخطاء حاجبة في الإعدادات/الخدمة. +- `openclaw channels status --probe` → إذا كانت البوابة قابلة للوصول، فسيُرجع حالة النقل الحية لكل حساب + بالإضافة إلى نتائج الفحص/التدقيق مثل `works` أو `audit ok`؛ وإذا كانت + البوابة غير قابلة للوصول، يعود الأمر إلى ملخصات تعتمد على الإعدادات فقط. +- `openclaw logs --follow` → نشاط مستقر، ولا توجد أخطاء قاتلة متكررة. -## ‏429 من Anthropic للسياق الطويل +## Anthropic long context 429 إذا رأيت: -`HTTP 429: rate_limit_error: Extra usage is required for long context requests`, -فانتقل إلى [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context). +`HTTP 429: rate_limit_error: Extra usage is required for long context requests` +فانتقل إلى [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/ar/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context). -## فشل تثبيت plugin بسبب غياب openclaw extensions +## تعمل واجهة OpenAI-compatible الخلفية المحلية مباشرة لكنها تفشل في OpenClaw + +إذا كانت واجهة `/v1` الخلفية المحلية أو المستضافة ذاتيًا تستجيب مباشرةً +لاختبارات `/v1/chat/completions` الصغيرة لكنها تفشل مع `openclaw infer model run` أو في +أدوار الوكيل العادية: + +1. إذا كان الخطأ يذكر أن `messages[].content` يتوقع سلسلة نصية، فاضبط + `models.providers..models[].compat.requiresStringContent: true`. +2. إذا استمرت الواجهة الخلفية في الفشل فقط في أدوار وكيل OpenClaw، فاضبط + `models.providers..models[].compat.supportsTools: false` ثم أعد المحاولة. +3. إذا ظلت الاستدعاءات المباشرة الصغيرة تعمل لكن موجّهات OpenClaw الأكبر تتسبب في تعطل + الواجهة الخلفية، فاعتبر المشكلة المتبقية قيدًا من النموذج/الخادم upstream + وتابع في الدليل التفصيلي: + [/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail](/ar/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail) + +## فشل تثبيت plugin مع openclaw extensions مفقودة إذا فشل التثبيت مع `package.json missing openclaw.extensions`، فإن حزمة plugin -تستخدم شكلًا قديمًا لم يعد OpenClaw يقبله. +تستخدم بنية قديمة لم يعد OpenClaw يقبلها. الحل في حزمة plugin: @@ -71,28 +87,28 @@ openclaw logs --follow } ``` -المرجع: [بنية Plugins](/plugins/architecture) +مرجع: [معمارية plugin](/ar/plugins/architecture) ## شجرة القرار ```mermaid flowchart TD - A[OpenClaw is not working] --> B{What breaks first} - B --> C[No replies] - B --> D[Dashboard or Control UI will not connect] - B --> E[Gateway will not start or service not running] - B --> F[Channel connects but messages do not flow] - B --> G[Cron or heartbeat did not fire or did not deliver] - B --> H[Node is paired but camera canvas screen exec fails] - B --> I[Browser tool fails] + A[OpenClaw لا يعمل] --> B{ما أول شيء يتعطل} + B --> C[لا توجد ردود] + B --> D[لوحة المعلومات أو Control UI لا تتصل] + B --> E[البوابة لا تبدأ أو الخدمة لا تعمل] + B --> F[القناة تتصل لكن الرسائل لا تتدفق] + B --> G[Cron أو Heartbeat لم يعمل أو لم يسلّم] + B --> H[تم اقتران العقدة لكن أداة camera canvas screen exec تفشل] + B --> I[أداة Browser تفشل] - C --> C1[/No replies section/] - D --> D1[/Control UI section/] - E --> E1[/Gateway section/] - F --> F1[/Channel flow section/] - G --> G1[/Automation section/] - H --> H1[/Node tools section/] - I --> I1[/Browser section/] + C --> C1[/قسم لا توجد ردود/] + D --> D1[/قسم Control UI/] + E --> E1[/قسم البوابة/] + F --> F1[/قسم تدفق القناة/] + G --> G1[/قسم الأتمتة/] + H --> H1[/قسم أدوات العقدة/] + I --> I1[/قسم Browser/] ``` @@ -105,28 +121,28 @@ flowchart TD openclaw logs --follow ``` - تبدو المخرجات الجيدة كالتالي: + تبدو المخرجات الجيدة كما يلي: - `Runtime: running` - `RPC probe: ok` - تعرض قناتك اتصال النقل، وحيثما كان ذلك مدعومًا، `works` أو `audit ok` في `channels status --probe` - - يظهر المرسل على أنه معتمد (أو أن سياسة الرسائل الخاصة open/allowlist) + - يظهر المرسِل على أنه معتمد (أو أن سياسة الرسائل المباشرة مفتوحة/قائمة السماح) - التواقيع الشائعة في السجلات: + توقيعات السجلات الشائعة: - - `drop guild message (mention required` ← تقييد الإشارة منع الرسالة في Discord. - - `pairing request` ← المرسل غير معتمد وينتظر الموافقة على الاقتران عبر الرسائل الخاصة. - - `blocked` / `allowlist` في سجلات القناة ← تتم تصفية المرسل أو الغرفة أو المجموعة. + - `drop guild message (mention required` → منعت بوابة الإشارة معالجة الرسالة في Discord. + - `pairing request` → المرسل غير معتمد وينتظر الموافقة على الاقتران عبر الرسائل المباشرة. + - `blocked` / `allowlist` في سجلات القناة → تمت تصفية المرسل أو الغرفة أو المجموعة. الصفحات التفصيلية: - - [/gateway/troubleshooting#no-replies](/gateway/troubleshooting#no-replies) - - [/channels/troubleshooting](/channels/troubleshooting) - - [/channels/pairing](/channels/pairing) + - [/gateway/troubleshooting#no-replies](/ar/gateway/troubleshooting#no-replies) + - [/channels/troubleshooting](/ar/channels/troubleshooting) + - [/channels/pairing](/ar/channels/pairing) - + ```bash openclaw status openclaw gateway status @@ -135,38 +151,37 @@ flowchart TD openclaw channels status --probe ``` - تبدو المخرجات الجيدة كالتالي: + تبدو المخرجات الجيدة كما يلي: - يظهر `Dashboard: http://...` في `openclaw gateway status` - `RPC probe: ok` - - لا توجد حلقة auth في السجلات + - لا توجد حلقة مصادقة في السجلات - التواقيع الشائعة في السجلات: + توقيعات السجلات الشائعة: - - `device identity required` ← لا يمكن لسياق HTTP/غير الآمن إكمال مصادقة الجهاز. - - `origin not allowed` ← قيمة `Origin` في المتصفح غير مسموح بها لهدف - البوابة الخاص بـ Control UI. - - `AUTH_TOKEN_MISMATCH` مع تلميحات إعادة المحاولة (`canRetryWithDeviceToken=true`) ← قد تحدث إعادة محاولة واحدة تلقائيًا باستخدام device-token موثوق. - - تعيد تلك المحاولة باستخدام الرمز المخزن مؤقتًا استخدام مجموعة النطاقات المخزنة مع - رمز الجهاز المقترن. بينما تحتفظ الاستدعاءات الصريحة باستخدام `deviceToken` / `scopes` الصريحة - بمجموعة النطاقات المطلوبة الخاصة بها. - - في مسار Control UI غير المتزامن عبر Tailscale Serve، يتم تسلسل المحاولات الفاشلة لنفس - `{scope, ip}` قبل أن يسجل المحدِّد الفشل، لذلك قد تُظهر محاولة سيئة ثانية متزامنة بالفعل - `retry later`. + - `device identity required` → لا يمكن لسياق HTTP/غير الآمن إكمال مصادقة الجهاز. + - `origin not allowed` → لا يُسمح بـ `Origin` الخاص بالمتصفح لهدف بوابة Control UI. + - `AUTH_TOKEN_MISMATCH` مع تلميحات إعادة المحاولة (`canRetryWithDeviceToken=true`) → قد تحدث إعادة محاولة واحدة موثوقة باستخدام رمز الجهاز تلقائيًا. + - تعيد إعادة المحاولة باستخدام الرمز المؤقت استخدام مجموعة النطاقات المخزنة مؤقتًا مع + رمز الجهاز المقترن. أما المستدعون الذين يستخدمون `deviceToken` صريحًا / `scopes` صريحة + فيحتفظون بمجموعة النطاقات المطلوبة الخاصة بهم. + - في مسار Control UI غير المتزامن عبر Tailscale Serve، تتم + موازاة المحاولات الفاشلة لنفس `{scope, ip}` قبل أن يسجّل المحدِّد الفشل، لذلك + قد تُظهر إعادة محاولة سيئة ثانية متزامنة بالفعل `retry later`. - `too many failed authentication attempts (retry later)` من - أصل متصفح localhost ← يتم قفل حالات الفشل المتكررة من `Origin` نفسه مؤقتًا؛ بينما يستخدم أصل localhost آخر مجموعة مستقلة. - - `unauthorized` المتكرر بعد تلك المحاولة ← token/password خاطئ، أو عدم تطابق وضع auth، أو رمز جهاز مقترن قديم. - - `gateway connect failed:` ← واجهة المستخدم تستهدف URL/منفذًا خاطئًا أو بوابة غير قابلة للوصول. + مصدر متصفح localhost → يتم قفل الإخفاقات المتكررة من `Origin` نفسه مؤقتًا؛ بينما يستخدم أصل localhost آخر سلة منفصلة. + - `unauthorized` متكرر بعد إعادة المحاولة تلك → رمز/كلمة مرور خاطئة، أو عدم تطابق وضع المصادقة، أو رمز جهاز مقترن قديم. + - `gateway connect failed:` → تستهدف UI عنوان URL/منفذًا خاطئًا أو بوابة يتعذر الوصول إليها. الصفحات التفصيلية: - - [/gateway/troubleshooting#dashboard-control-ui-connectivity](/gateway/troubleshooting#dashboard-control-ui-connectivity) + - [/gateway/troubleshooting#dashboard-control-ui-connectivity](/ar/gateway/troubleshooting#dashboard-control-ui-connectivity) - [/web/control-ui](/web/control-ui) - - [/gateway/authentication](/gateway/authentication) + - [/gateway/authentication](/ar/gateway/authentication) - + ```bash openclaw status openclaw gateway status @@ -175,27 +190,27 @@ flowchart TD openclaw channels status --probe ``` - تبدو المخرجات الجيدة كالتالي: + تبدو المخرجات الجيدة كما يلي: - `Service: ... (loaded)` - `Runtime: running` - `RPC probe: ok` - التواقيع الشائعة في السجلات: + توقيعات السجلات الشائعة: - - `Gateway start blocked: set gateway.mode=local` أو `existing config is missing gateway.mode` ← وضع البوابة هو remote، أو أن ملف الإعدادات يفتقد علامة الوضع المحلي ويجب إصلاحه. - - `refusing to bind gateway ... without auth` ← ربط غير loopback من دون مسار auth صالح للبوابة (token/password، أو trusted-proxy حيثما يكون مهيأً). - - `another gateway instance is already listening` أو `EADDRINUSE` ← المنفذ مستخدم بالفعل. + - `Gateway start blocked: set gateway.mode=local` أو `existing config is missing gateway.mode` → وضع البوابة هو remote، أو أن ملف الإعدادات يفتقد علامة الوضع المحلي ويجب إصلاحه. + - `refusing to bind gateway ... without auth` → ربط غير loopback بدون مسار مصادقة صالح للبوابة (رمز/كلمة مرور، أو trusted-proxy حيثما كان مهيأً). + - `another gateway instance is already listening` أو `EADDRINUSE` → المنفذ مستخدم بالفعل. الصفحات التفصيلية: - - [/gateway/troubleshooting#gateway-service-not-running](/gateway/troubleshooting#gateway-service-not-running) - - [/gateway/background-process](/gateway/background-process) - - [/gateway/configuration](/gateway/configuration) + - [/gateway/troubleshooting#gateway-service-not-running](/ar/gateway/troubleshooting#gateway-service-not-running) + - [/gateway/background-process](/ar/gateway/background-process) + - [/gateway/configuration](/ar/gateway/configuration) - + ```bash openclaw status openclaw gateway status @@ -204,26 +219,26 @@ flowchart TD openclaw channels status --probe ``` - تبدو المخرجات الجيدة كالتالي: + تبدو المخرجات الجيدة كما يلي: - نقل القناة متصل. - - اجتياز فحوصات الاقتران/قائمة السماح. - - يتم اكتشاف الإشارات عند الحاجة. + - تمر فحوصات الاقتران/قائمة السماح. + - يتم اكتشاف الإشارات حيثما تكون مطلوبة. - التواقيع الشائعة في السجلات: + توقيعات السجلات الشائعة: - - `mention required` ← تقييد الإشارة في المجموعات منع المعالجة. - - `pairing` / `pending` ← مرسل الرسائل الخاصة لم تتم الموافقة عليه بعد. - - `not_in_channel` أو `missing_scope` أو `Forbidden` أو `401/403` ← مشكلة في أذونات القناة أو الرمز المميز. + - `mention required` → منعت بوابة الإشارة في المجموعة المعالجة. + - `pairing` / `pending` → مرسل الرسالة المباشرة غير معتمد بعد. + - `not_in_channel`, `missing_scope`, `Forbidden`, `401/403` → مشكلة في رمز أذونات القناة. الصفحات التفصيلية: - - [/gateway/troubleshooting#channel-connected-messages-not-flowing](/gateway/troubleshooting#channel-connected-messages-not-flowing) - - [/channels/troubleshooting](/channels/troubleshooting) + - [/gateway/troubleshooting#channel-connected-messages-not-flowing](/ar/gateway/troubleshooting#channel-connected-messages-not-flowing) + - [/channels/troubleshooting](/ar/channels/troubleshooting) - + ```bash openclaw status openclaw gateway status @@ -233,30 +248,30 @@ flowchart TD openclaw logs --follow ``` - تبدو المخرجات الجيدة كالتالي: + تبدو المخرجات الجيدة كما يلي: - - تعرض `cron.status` أنها مفعلة مع موعد الاستيقاظ التالي. - - تعرض `cron runs` إدخالات `ok` حديثة. - - Heartbeat مفعّل وليس خارج الساعات النشطة. + - يعرض `cron.status` أنه مفعّل مع وقت الاستيقاظ التالي. + - يعرض `cron runs` إدخالات `ok` حديثة. + - يكون Heartbeat مفعّلًا وليس خارج ساعات النشاط. - التواقيع الشائعة في السجلات: + توقيعات السجلات الشائعة: -- `cron: scheduler disabled; jobs will not run automatically` ← cron معطل. -- `heartbeat skipped` مع `reason=quiet-hours` ← خارج الساعات النشطة المهيأة. -- `heartbeat skipped` مع `reason=empty-heartbeat-file` ← الملف `HEARTBEAT.md` موجود لكنه يحتوي فقط على هيكل فارغ/عناوين فقط. -- `heartbeat skipped` مع `reason=no-tasks-due` ← وضع مهام `HEARTBEAT.md` نشط، لكن لم يحن موعد أي من فواصل المهام بعد. -- `heartbeat skipped` مع `reason=alerts-disabled` ← كل مظاهر عرض heartbeat معطلة (`showOk` و`showAlerts` و`useIndicator` كلها متوقفة). -- `requests-in-flight` ← المسار الرئيسي مشغول؛ وتم تأجيل استيقاظ heartbeat. - `unknown accountId` ← حساب هدف تسليم heartbeat غير موجود. +- `cron: scheduler disabled; jobs will not run automatically` → تم تعطيل cron. +- `heartbeat skipped` مع `reason=quiet-hours` → خارج ساعات النشاط المهيأة. +- `heartbeat skipped` مع `reason=empty-heartbeat-file` → الملف `HEARTBEAT.md` موجود لكنه يحتوي فقط على هيكل فارغ/عناوين فقط. +- `heartbeat skipped` مع `reason=no-tasks-due` → وضع المهام في `HEARTBEAT.md` نشط ولكن لم يحن موعد أي من فواصل المهام بعد. +- `heartbeat skipped` مع `reason=alerts-disabled` → تم تعطيل كل ظهور Heartbeat (`showOk` و`showAlerts` و`useIndicator` كلها معطلة). +- `requests-in-flight` → المسار الرئيسي مشغول؛ تم تأجيل تنبيه Heartbeat. - `unknown accountId` → حساب هدف تسليم Heartbeat غير موجود. الصفحات التفصيلية: - - [/gateway/troubleshooting#cron-and-heartbeat-delivery](/gateway/troubleshooting#cron-and-heartbeat-delivery) - - [/automation/cron-jobs#troubleshooting](/automation/cron-jobs#troubleshooting) - - [/gateway/heartbeat](/gateway/heartbeat) + - [/gateway/troubleshooting#cron-and-heartbeat-delivery](/ar/gateway/troubleshooting#cron-and-heartbeat-delivery) + - [/automation/cron-jobs#troubleshooting](/ar/automation/cron-jobs#troubleshooting) + - [/gateway/heartbeat](/ar/gateway/heartbeat) - + ```bash openclaw status openclaw gateway status @@ -265,28 +280,28 @@ flowchart TD openclaw logs --follow ``` - تبدو المخرجات الجيدة كالتالي: + تبدو المخرجات الجيدة كما يلي: - - العقدة مدرجة على أنها متصلة ومقترنة للدور `node`. - - الإمكانية موجودة للأمر الذي تستدعيه. - - حالة الأذونات ممنوحة لتلك الأداة. + - تظهر العقدة على أنها متصلة ومقترنة للدور `node`. + - توجد capability للأمر الذي تستدعيه. + - حالة الإذن ممنوحة للأداة. - التواقيع الشائعة في السجلات: + توقيعات السجلات الشائعة: - - `NODE_BACKGROUND_UNAVAILABLE` ← اجعل تطبيق العقدة في الواجهة الأمامية. - - `*_PERMISSION_REQUIRED` ← تم رفض إذن نظام التشغيل أو كان مفقودًا. - - `SYSTEM_RUN_DENIED: approval required` ← موافقة exec معلقة. - - `SYSTEM_RUN_DENIED: allowlist miss` ← الأمر غير موجود في قائمة سماح exec. + - `NODE_BACKGROUND_UNAVAILABLE` → اجلب تطبيق العقدة إلى الواجهة الأمامية. + - `*_PERMISSION_REQUIRED` → تم رفض/فقدان إذن نظام التشغيل. + - `SYSTEM_RUN_DENIED: approval required` → موافقة exec معلّقة. + - `SYSTEM_RUN_DENIED: allowlist miss` → الأمر غير موجود في قائمة السماح الخاصة بـ exec. الصفحات التفصيلية: - - [/gateway/troubleshooting#node-paired-tool-fails](/gateway/troubleshooting#node-paired-tool-fails) - - [/nodes/troubleshooting](/nodes/troubleshooting) - - [/tools/exec-approvals](/tools/exec-approvals) + - [/gateway/troubleshooting#node-paired-tool-fails](/ar/gateway/troubleshooting#node-paired-tool-fails) + - [/nodes/troubleshooting](/ar/nodes/troubleshooting) + - [/tools/exec-approvals](/ar/tools/exec-approvals) - + ```bash openclaw config get tools.exec.host openclaw config get tools.exec.security @@ -296,14 +311,14 @@ flowchart TD ما الذي تغيّر: - - إذا لم يتم تعيين `tools.exec.host`، فالقيمة الافتراضية هي `auto`. - - تُحل `host=auto` إلى `sandbox` عندما يكون runtime المعزول نشطًا، وإلى `gateway` خلاف ذلك. - - `host=auto` خاصة بالتوجيه فقط؛ بينما يأتي سلوك "YOLO" من دون مطالبة من `security=full` مع `ask=off` على gateway/node. - - على `gateway` و`node`، تكون القيمة الافتراضية لـ `tools.exec.security` عند عدم التعيين هي `full`. - - تكون القيمة الافتراضية لـ `tools.exec.ask` عند عدم التعيين هي `off`. - - النتيجة: إذا كنت ترى موافقات، فقد تم تشديد بعض السياسات المحلية للمضيف أو الخاصة بكل جلسة على exec بعيدًا عن القيم الافتراضية الحالية. + - إذا لم يتم ضبط `tools.exec.host`، فالقيمة الافتراضية هي `auto`. + - يحل `host=auto` إلى `sandbox` عندما يكون runtime الخاص بـ sandbox نشطًا، وإلى `gateway` خلاف ذلك. + - `host=auto` خاص بالتوجيه فقط؛ أما سلوك "YOLO" بدون مطالبة فيأتي من `security=full` مع `ask=off` على gateway/node. + - في `gateway` و`node`، تكون القيمة الافتراضية لـ `tools.exec.security` عند عدم ضبطها هي `full`. + - تكون القيمة الافتراضية لـ `tools.exec.ask` عند عدم ضبطها هي `off`. + - النتيجة: إذا كنت ترى موافقات، فهذا يعني أن سياسة محلية على المضيف أو خاصة بالجلسة قد شددت exec بعيدًا عن القيم الافتراضية الحالية. - استعد سلوك عدم طلب الموافقة الافتراضي الحالي: + استعد سلوك الوضع الحالي الافتراضي بدون موافقة: ```bash openclaw config set tools.exec.host gateway @@ -314,25 +329,25 @@ flowchart TD بدائل أكثر أمانًا: - - اضبط فقط `tools.exec.host=gateway` إذا كنت تريد فقط توجيهًا مستقرًا للمضيف. - - استخدم `security=allowlist` مع `ask=on-miss` إذا كنت تريد exec على المضيف مع الإبقاء على المراجعة عند عدم التطابق مع قائمة السماح. - - فعّل وضع sandbox إذا كنت تريد أن تُحل `host=auto` مرة أخرى إلى `sandbox`. + - اضبط فقط `tools.exec.host=gateway` إذا كنت تريد مجرد توجيه مستقر على المضيف. + - استخدم `security=allowlist` مع `ask=on-miss` إذا كنت تريد exec على المضيف لكنك ما زلت تريد مراجعة عند الإخفاق في قائمة السماح. + - فعّل وضع sandbox إذا كنت تريد أن يعود `host=auto` إلى `sandbox`. - التواقيع الشائعة في السجلات: + توقيعات السجلات الشائعة: - - `Approval required.` ← الأمر ينتظر `/approve ...`. - - `SYSTEM_RUN_DENIED: approval required` ← موافقة exec على مضيف العقدة معلقة. - - `exec host=sandbox requires a sandbox runtime for this session` ← اختيار sandbox ضمني/صريح لكن وضع sandbox متوقف. + - `Approval required.` → ينتظر الأمر `/approve ...`. + - `SYSTEM_RUN_DENIED: approval required` → موافقة exec على مضيف العقدة معلّقة. + - `exec host=sandbox requires a sandbox runtime for this session` → تم اختيار sandbox ضمنيًا/صراحة لكن وضع sandbox معطل. الصفحات التفصيلية: - - [/tools/exec](/tools/exec) - - [/tools/exec-approvals](/tools/exec-approvals) - - [/gateway/security#runtime-expectation-drift](/gateway/security#runtime-expectation-drift) + - [/tools/exec](/ar/tools/exec) + - [/tools/exec-approvals](/ar/tools/exec-approvals) + - [/gateway/security#runtime-expectation-drift](/ar/gateway/security#runtime-expectation-drift) - + ```bash openclaw status openclaw gateway status @@ -341,37 +356,37 @@ flowchart TD openclaw doctor ``` - تبدو المخرجات الجيدة كالتالي: + تبدو المخرجات الجيدة كما يلي: - - تعرض حالة Browser القيمة `running: true` ومتصفحًا/ملف تعريف مختارًا. - - يبدأ `openclaw`، أو يمكن للمستخدم رؤية علامات تبويب Chrome المحلية. + - تعرض حالة Browser `running: true` ومتصفحًا/ملف تعريف محددًا. + - يبدأ `openclaw`، أو يمكن لـ `user` رؤية علامات تبويب Chrome المحلية. - التواقيع الشائعة في السجلات: + توقيعات السجلات الشائعة: - - `unknown command "browser"` أو `unknown command 'browser'` ← تم تعيين `plugins.allow` ولا يتضمن `browser`. - - `Failed to start Chrome CDP on port` ← فشل تشغيل المتصفح المحلي. - - `browser.executablePath not found` ← مسار الثنائي المهيأ غير صحيح. - - `browser.cdpUrl must be http(s) or ws(s)` ← يستخدم عنوان CDP URL المهيأ مخططًا غير مدعوم. - - `browser.cdpUrl has invalid port` ← يحتوي CDP URL المهيأ على منفذ غير صالح أو خارج النطاق. - - `No Chrome tabs found for profile="user"` ← لا توجد علامات تبويب Chrome محلية مفتوحة لملف تعريف الإرفاق Chrome MCP. - - `Remote CDP for profile "" is not reachable` ← نقطة نهاية CDP البعيدة المهيأة غير قابلة للوصول من هذا المضيف. - - `Browser attachOnly is enabled ... not reachable` أو `Browser attachOnly is enabled and CDP websocket ... is not reachable` ← لا يملك ملف تعريف attach-only هدف CDP حيًا. - - تجاوزات viewport / dark-mode / locale / offline القديمة في ملفات تعريف attach-only أو CDP البعيدة ← شغّل `openclaw browser stop --browser-profile ` لإغلاق جلسة التحكم النشطة وتحرير حالة المحاكاة من دون إعادة تشغيل البوابة. + - `unknown command "browser"` أو `unknown command 'browser'` → تم ضبط `plugins.allow` ولا يتضمن `browser`. + - `Failed to start Chrome CDP on port` → فشل تشغيل المتصفح المحلي. + - `browser.executablePath not found` → مسار الملف التنفيذي المهيأ غير صحيح. + - `browser.cdpUrl must be http(s) or ws(s)` → يستخدم عنوان CDP المهيأ مخططًا غير مدعوم. + - `browser.cdpUrl has invalid port` → يحتوي عنوان CDP المهيأ على منفذ سيئ أو خارج النطاق. + - `No Chrome tabs found for profile="user"` → لا يحتوي ملف تعريف إرفاق Chrome MCP على علامات تبويب Chrome محلية مفتوحة. + - `Remote CDP for profile "" is not reachable` → يتعذر الوصول إلى نقطة نهاية CDP البعيدة المهيأة من هذا المضيف. + - `Browser attachOnly is enabled ... not reachable` أو `Browser attachOnly is enabled and CDP websocket ... is not reachable` → لا يحتوي ملف تعريف attach-only على هدف CDP حي. + - تجاوزات viewport / dark-mode / locale / offline القديمة على ملفات تعريف attach-only أو CDP البعيدة → شغّل `openclaw browser stop --browser-profile ` لإغلاق جلسة التحكم النشطة وتحرير حالة المحاكاة دون إعادة تشغيل البوابة. الصفحات التفصيلية: - - [/gateway/troubleshooting#browser-tool-fails](/gateway/troubleshooting#browser-tool-fails) - - [/tools/browser#missing-browser-command-or-tool](/tools/browser#missing-browser-command-or-tool) - - [/tools/browser-linux-troubleshooting](/tools/browser-linux-troubleshooting) - - [/tools/browser-wsl2-windows-remote-cdp-troubleshooting](/tools/browser-wsl2-windows-remote-cdp-troubleshooting) + - [/gateway/troubleshooting#browser-tool-fails](/ar/gateway/troubleshooting#browser-tool-fails) + - [/tools/browser#missing-browser-command-or-tool](/ar/tools/browser#missing-browser-command-or-tool) + - [/tools/browser-linux-troubleshooting](/ar/tools/browser-linux-troubleshooting) + - [/tools/browser-wsl2-windows-remote-cdp-troubleshooting](/ar/tools/browser-wsl2-windows-remote-cdp-troubleshooting) ## ذو صلة -- [الأسئلة الشائعة](/help/faq) — الأسئلة المتكررة -- [استكشاف أخطاء Gateway وإصلاحها](/gateway/troubleshooting) — المشكلات الخاصة بالبوابة -- [Doctor](/gateway/doctor) — فحوصات الصحة والإصلاحات الآلية -- [استكشاف أخطاء القنوات وإصلاحها](/channels/troubleshooting) — مشكلات اتصال القنوات -- [استكشاف أخطاء الأتمتة وإصلاحها](/automation/cron-jobs#troubleshooting) — مشكلات cron وheartbeat +- [الأسئلة الشائعة](/ar/help/faq) — الأسئلة المتداولة +- [استكشاف أخطاء البوابة وإصلاحها](/ar/gateway/troubleshooting) — المشكلات الخاصة بالبوابة +- [Doctor](/ar/gateway/doctor) — فحوصات الصحة والإصلاحات الآلية +- [استكشاف أخطاء القنوات وإصلاحها](/ar/channels/troubleshooting) — مشكلات اتصال القنوات +- [استكشاف أخطاء الأتمتة وإصلاحها](/ar/automation/cron-jobs#troubleshooting) — مشكلات cron وHeartbeat diff --git a/docs/ar/plugins/architecture.md b/docs/ar/plugins/architecture.md index 8e822acb5..3b223b1f7 100644 --- a/docs/ar/plugins/architecture.md +++ b/docs/ar/plugins/architecture.md @@ -1,184 +1,184 @@ --- read_when: - - إنشاء Plugins أصلية لـ OpenClaw أو تصحيحها - - فهم نموذج إمكانات plugin أو حدود الملكية - - العمل على خط أنابيب تحميل plugin أو السجل - - تنفيذ خطافات وقت تشغيل الموفر أو plugins القنوات + - إنشاء إضافات OpenClaw الأصلية أو تصحيح أخطائها + - فهم نموذج قدرات الإضافة أو حدود الملكية + - العمل على خط أنابيب تحميل الإضافة أو السجل + - تنفيذ خطافات وقت تشغيل المزوّد أو إضافات القنوات sidebarTitle: Internals -summary: 'الأساسيات الداخلية للـ plugin: نموذج الإمكانات، والملكية، والعقود، وخط أنابيب التحميل، ومساعدات وقت التشغيل' -title: الأساسيات الداخلية للـ Plugin +summary: 'الأجزاء الداخلية للإضافة: نموذج القدرات، والملكية، والعقود، وخط أنابيب التحميل، ومساعدات وقت التشغيل' +title: الأجزاء الداخلية للإضافة x-i18n: - generated_at: "2026-04-07T07:23:06Z" + generated_at: "2026-04-08T02:25:07Z" model: gpt-5.4 provider: openai - source_hash: ba93f0a748e46ac7c7b9d10d78260e6e13b6e533d85a0b56f3c1ffa8ee5a3850 + source_hash: c40ecf14e2a0b2b8d332027aed939cd61fb4289a489f4cd4c076c96d707d1138 source_path: plugins/architecture.md workflow: 15 --- -# الأساسيات الداخلية للـ Plugin +# الأجزاء الداخلية للإضافة - هذا هو **مرجع البنية المتعمق**. للاطلاع على الأدلة العملية، راجع: - - [تثبيت plugins واستخدامها](/ar/tools/plugin) — دليل المستخدم - - [البدء](/ar/plugins/building-plugins) — أول برنامج تعليمي لـ plugin - - [Plugins القنوات](/ar/plugins/sdk-channel-plugins) — إنشاء قناة مراسلة - - [Plugins الموفر](/ar/plugins/sdk-provider-plugins) — إنشاء موفر نماذج + هذا هو **مرجع البنية العميقة**. للاطلاع على الأدلة العملية، راجع: + - [تثبيت الإضافات واستخدامها](/ar/tools/plugin) — دليل المستخدم + - [البدء](/ar/plugins/building-plugins) — أول درس تعليمي للإضافات + - [إضافات القنوات](/ar/plugins/sdk-channel-plugins) — إنشاء قناة مراسلة + - [إضافات المزوّدين](/ar/plugins/sdk-provider-plugins) — إنشاء مزوّد نماذج - [نظرة عامة على SDK](/ar/plugins/sdk-overview) — خريطة الاستيراد وواجهة برمجة تطبيقات التسجيل -تغطي هذه الصفحة البنية الداخلية لنظام plugins في OpenClaw. +تغطي هذه الصفحة البنية الداخلية لنظام الإضافات في OpenClaw. -## نموذج الإمكانات العام +## نموذج القدرات العام -الإمكانات هي النموذج العام لـ **plugin أصلية** داخل OpenClaw. كل -plugin أصلية في OpenClaw تسجل نفسها في نوع قدرة واحد أو أكثر: +القدرات هي نموذج **الإضافة الأصلية** العام داخل OpenClaw. تسجل كل +إضافة OpenClaw أصلية مقابل نوع قدرة واحد أو أكثر: -| القدرة | طريقة التسجيل | أمثلة على plugins | -| --------------------- | ------------------------------------------------ | ------------------------------------ | -| استدلال النص | `api.registerProvider(...)` | `openai`، `anthropic` | -| خلفية استدلال CLI | `api.registerCliBackend(...)` | `openai`، `anthropic` | -| الكلام | `api.registerSpeechProvider(...)` | `elevenlabs`، `microsoft` | -| النسخ الفوري | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | -| الصوت الفوري | `api.registerRealtimeVoiceProvider(...)` | `openai` | -| فهم الوسائط | `api.registerMediaUnderstandingProvider(...)` | `openai`، `google` | -| توليد الصور | `api.registerImageGenerationProvider(...)` | `openai`، `google`، `fal`، `minimax` | -| توليد الموسيقى | `api.registerMusicGenerationProvider(...)` | `google`، `minimax` | -| توليد الفيديو | `api.registerVideoGenerationProvider(...)` | `qwen` | -| جلب الويب | `api.registerWebFetchProvider(...)` | `firecrawl` | -| بحث الويب | `api.registerWebSearchProvider(...)` | `google` | -| القناة / المراسلة | `api.registerChannel(...)` | `msteams`، `matrix` | +| القدرة | طريقة التسجيل | أمثلة على الإضافات | +| --------------------- | --------------------------------------------- | ------------------------------------ | +| استدلال النص | `api.registerProvider(...)` | `openai`, `anthropic` | +| خلفية استدلال CLI | `api.registerCliBackend(...)` | `openai`, `anthropic` | +| الكلام | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | +| النسخ الفوري | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | +| الصوت الفوري | `api.registerRealtimeVoiceProvider(...)` | `openai` | +| فهم الوسائط | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | +| توليد الصور | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | +| توليد الموسيقى | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | +| توليد الفيديو | `api.registerVideoGenerationProvider(...)` | `qwen` | +| جلب الويب | `api.registerWebFetchProvider(...)` | `firecrawl` | +| البحث على الويب | `api.registerWebSearchProvider(...)` | `google` | +| القناة / المراسلة | `api.registerChannel(...)` | `msteams`, `matrix` | -تُعد plugin التي تسجل صفرًا من الإمكانات لكنها توفر خطافات أو أدوات أو -خدمات **plugin قديمة تعتمد على الخطافات فقط**. لا يزال هذا النمط مدعومًا بالكامل. +الإضافة التي تسجل صفرًا من القدرات لكنها توفّر خطافات أو أدوات أو +خدمات هي إضافة **قديمة تعتمد على الخطافات فقط**. لا يزال هذا النمط مدعومًا بالكامل. ### موقف التوافق الخارجي -لقد تم اعتماد نموذج الإمكانات في النواة ويُستخدم اليوم من قبل plugins -الأصلية/المضمّنة، لكن توافق plugins الخارجية لا يزال يحتاج إلى معيار أكثر -صرامة من مجرد "تم تصديره، إذن فهو ثابت." +تم اعتماد نموذج القدرات في النواة ويُستخدم اليوم بواسطة الإضافات +المضمّنة/الأصلية، لكن توافق الإضافات الخارجية لا يزال يحتاج إلى معيار أدق من +"إنه مُصدَّر، إذن فهو مجمّد." الإرشادات الحالية: -- **plugins الخارجية الحالية:** حافظ على عمل التكاملات المستندة إلى الخطافات؛ +- **الإضافات الخارجية الحالية:** أبقِ عمليات التكامل المعتمدة على الخطافات تعمل؛ واعتبر ذلك خط الأساس للتوافق -- **plugins الأصلية/المضمّنة الجديدة:** فضّل التسجيل الصريح للإمكانات بدلًا من - الوصولات الخاصة بالمورّد أو التصميمات الجديدة التي تعتمد على الخطافات فقط -- **plugins الخارجية التي تعتمد تسجيل الإمكانات:** هذا مسموح، لكن تعامل مع - أسطح المساعدة الخاصة بالإمكانات على أنها قابلة للتطور ما لم توضح المستندات صراحةً أن - العقد مستقر +- **الإضافات المضمّنة/الأصلية الجديدة:** فضّل تسجيل القدرات الصريح بدلًا من + التوغلات الخاصة بالمورّد أو تصميمات الخطافات فقط الجديدة +- **الإضافات الخارجية التي تتبنى تسجيل القدرات:** هذا مسموح، لكن تعامل مع + أسطح المساعدة الخاصة بالقدرات على أنها تتطور ما لم تضع الوثائق علامة + صريحة على أن العقد مستقر القاعدة العملية: -- واجهات برمجة تطبيقات تسجيل الإمكانات هي الاتجاه المقصود -- تبقى الخطافات القديمة هي المسار الأكثر أمانًا لتجنب الكسر بالنسبة إلى plugins الخارجية أثناء - مرحلة الانتقال -- ليست كل المسارات الفرعية المصدّرة متساوية؛ فافضّل العقد الضيق الموثّق، - وليس صادرات المساعدة العرضية +- واجهات تسجيل القدرات هي الاتجاه المقصود +- تظل الخطافات القديمة هي المسار الأكثر أمانًا لعدم كسر الإضافات الخارجية أثناء + الانتقال +- ليست كل المسارات الفرعية المصدّرة للمساعدات متساوية؛ فضّل العقد الضيق + الموثق، وليس تصديرات المساعدة العرضية -### أشكال plugin +### أشكال الإضافات -يصنّف OpenClaw كل plugin محمّلة إلى شكل بناءً على سلوك التسجيل -الفعلي لها (وليس فقط البيانات الوصفية الثابتة): +يصنّف OpenClaw كل إضافة محمّلة إلى شكل استنادًا إلى سلوك التسجيل الفعلي لها +(وليس فقط البيانات الوصفية الثابتة): -- **plain-capability** -- تسجل نوع قدرة واحدًا بالضبط (مثلًا plugin - موفر فقط مثل `mistral`) -- **hybrid-capability** -- تسجل أنواع قدرات متعددة (مثلًا - `openai` يمتلك استدلال النص والكلام وفهم الوسائط وتوليد +- **plain-capability** -- تسجل نوع قدرة واحدًا فقط (على سبيل المثال + إضافة مزوّد فقط مثل `mistral`) +- **hybrid-capability** -- تسجل عدة أنواع من القدرات (على سبيل المثال + `openai` يملك استدلال النص، والكلام، وفهم الوسائط، وتوليد الصور) -- **hook-only** -- تسجل خطافات فقط (مكتوبة الأنواع أو مخصصة)، بلا إمكانات +- **hook-only** -- تسجل خطافات فقط (مكتوبة الأنواع أو مخصصة)، بلا قدرات أو أدوات أو أوامر أو خدمات -- **non-capability** -- تسجل أدوات أو أوامر أو خدمات أو مسارات، لكن بلا - إمكانات +- **non-capability** -- تسجل أدوات أو أوامر أو خدمات أو مسارات لكن بلا + قدرات -استخدم `openclaw plugins inspect ` لرؤية شكل plugin وتفصيل -إمكاناتها. راجع [مرجع CLI](/cli/plugins#inspect) للتفاصيل. +استخدم `openclaw plugins inspect ` لرؤية شكل الإضافة وتفصيل +القدرات. راجع [مرجع CLI](/cli/plugins#inspect) للتفاصيل. ### الخطافات القديمة -لا يزال الخطاف `before_agent_start` مدعومًا كمسار توافق للـ plugins -التي تعتمد على الخطافات فقط. ولا تزال plugins واقعية قديمة تعتمد عليه. +لا يزال الخطاف `before_agent_start` مدعومًا كمسار توافق للإضافات +المعتمدة على الخطافات فقط. لا تزال إضافات قديمة مستخدمة فعليًا تعتمد عليه. الاتجاه: -- حافظ على عمله +- أبقه يعمل - وثّقه على أنه قديم -- فضّل `before_model_resolve` في أعمال تجاوز النموذج/الموفر -- فضّل `before_prompt_build` في أعمال تعديل prompt -- أزله فقط بعد انخفاض الاستخدام الفعلي ووجود تغطية fixtures تثبت أمان الترحيل +- فضّل `before_model_resolve` لأعمال تجاوز النموذج/المزوّد +- فضّل `before_prompt_build` لأعمال تعديل الموجّه +- أزِله فقط بعد انخفاض الاستخدام الفعلي وتأكيد تغطية الاختبارات الثابتة لسلامة الترحيل ### إشارات التوافق عند تشغيل `openclaw doctor` أو `openclaw plugins inspect `، قد ترى -إحدى هذه التسميات: +إحدى هذه العلامات: | الإشارة | المعنى | | -------------------------- | ------------------------------------------------------------ | -| **config valid** | يتم تحليل الإعداد بنجاح ويتم حل plugins | -| **compatibility advisory** | تستخدم plugin نمطًا مدعومًا لكنه أقدم (مثل `hook-only`) | -| **legacy warning** | تستخدم plugin الخطاف `before_agent_start`، وهو مهمل | -| **hard error** | الإعداد غير صالح أو فشل تحميل plugin | +| **config valid** | يجري تحليل الإعدادات جيدًا وتُحل الإضافات | +| **compatibility advisory** | تستخدم الإضافة نمطًا مدعومًا لكنه أقدم (مثل `hook-only`) | +| **legacy warning** | تستخدم الإضافة `before_agent_start`، وهو مهمل | +| **hard error** | الإعدادات غير صالحة أو فشل تحميل الإضافة | -لن يؤدي كل من `hook-only` و`before_agent_start` إلى كسر plugin الخاصة بك اليوم -- -فـ `hook-only` مجرد تنبيه استشاري، و`before_agent_start` يطلق تحذيرًا فقط. تظهر -هذه الإشارات أيضًا في `openclaw status --all` و`openclaw plugins doctor`. +لن يؤدي `hook-only` ولا `before_agent_start` إلى كسر إضافتك اليوم -- +فـ`hook-only` مجرد تنبيه إرشادي، و`before_agent_start` لا يطلق إلا تحذيرًا. تظهر هذه +الإشارات أيضًا في `openclaw status --all` و`openclaw plugins doctor`. ## نظرة عامة على البنية -يحتوي نظام plugins في OpenClaw على أربع طبقات: +يحتوي نظام الإضافات في OpenClaw على أربع طبقات: 1. **البيان + الاكتشاف** - يعثر OpenClaw على plugins المرشحة من المسارات المضبوطة، وجذور workspace، - وجذور الامتدادات العامة، والامتدادات المضمّنة. يقرأ الاكتشاف ملفات - `openclaw.plugin.json` الأصلية إضافة إلى بيانات الحزم المتوافقة المدعومة أولًا. + يعثر OpenClaw على الإضافات المرشحة من المسارات المهيأة، وجذور مساحات العمل، + وجذور الامتدادات العامة، والامتدادات المضمّنة. يقرأ الاكتشاف بيانات + `openclaw.plugin.json` الأصلية بالإضافة إلى بيانات الحزم المتوافقة أولًا. 2. **التمكين + التحقق** - تحدد النواة ما إذا كانت plugin المكتشفة ممكّنة أو معطّلة أو محظورة أو - مختارة لفتحة حصرية مثل الذاكرة. -3. **التحميل في وقت التشغيل** - يتم تحميل plugins الأصلية لـ OpenClaw داخل العملية عبر jiti وتسجيل - الإمكانات في سجل مركزي. ويتم تطبيع الحزم المتوافقة إلى - سجلات في السجل بدون استيراد شيفرة وقت التشغيل. + تقرر النواة ما إذا كانت الإضافة المكتشفة مفعّلة، أو معطّلة، أو محظورة، أو + مختارة لمنفذ حصري مثل الذاكرة. +3. **التحميل وقت التشغيل** + تُحمَّل إضافات OpenClaw الأصلية داخل العملية عبر jiti وتسجّل + القدرات في سجل مركزي. وتُطبّع الحزم المتوافقة إلى + سجلات في السجل دون استيراد كود وقت التشغيل. 4. **استهلاك الأسطح** - يقرأ باقي OpenClaw السجل لكشف الأدوات والقنوات وإعداد - الموفر والخطافات ومسارات HTTP وأوامر CLI والخدمات. + يقرأ باقي OpenClaw السجل لكشف الأدوات، والقنوات، وإعداد + المزوّد، والخطافات، ومسارات HTTP، وأوامر CLI، والخدمات. -وبالنسبة إلى CLI الخاص بالـ plugin تحديدًا، ينقسم اكتشاف الأمر الجذري إلى مرحلتين: +وبالنسبة إلى CLI الخاص بالإضافة تحديدًا، يُقسَّم اكتشاف الأمر الجذري إلى مرحلتين: - تأتي بيانات وقت التحليل من `registerCli(..., { descriptors: [...] })` -- ويمكن أن تبقى وحدة CLI الحقيقية الخاصة بالـ plugin كسولة وتُسجَّل عند أول استدعاء +- يمكن أن يبقى نموذج CLI الحقيقي للإضافة كسولًا ويُسجَّل عند أول استدعاء -وهذا يُبقي شيفرة CLI المملوكة للـ plugin داخل plugin مع السماح لـ OpenClaw +يبقي ذلك كود CLI المملوك للإضافة داخل الإضافة مع السماح لـ OpenClaw بحجز أسماء الأوامر الجذرية قبل التحليل. الحد التصميمي المهم: -- يجب أن يعمل الاكتشاف + التحقق من الإعداد من **البيان/بيانات schema** - بدون تنفيذ شيفرة plugin -- بينما يأتي سلوك وقت التشغيل الأصلي من مسار `register(api)` الخاص بوحدة plugin +- يجب أن يعمل الاكتشاف والتحقق من الإعدادات اعتمادًا على **بيانات البيان/المخطط** + دون تنفيذ كود الإضافة +- يأتي سلوك وقت التشغيل الأصلي من مسار `register(api)` في وحدة الإضافة -يتيح هذا الفصل لـ OpenClaw التحقق من الإعداد، وشرح plugins المفقودة/المعطّلة، -وبناء تلميحات UI/schema قبل تنشيط وقت التشغيل الكامل. +يسمح هذا الفصل لـ OpenClaw بالتحقق من الإعدادات، وشرح الإضافات المفقودة/المعطلة، +وبناء تلميحات واجهة المستخدم/المخطط قبل تنشيط وقت التشغيل الكامل. -### Plugins القنوات وأداة الرسائل المشتركة +### إضافات القنوات وأداة الرسائل المشتركة -لا تحتاج Plugins القنوات إلى تسجيل أداة send/edit/react منفصلة +لا تحتاج إضافات القنوات إلى تسجيل أداة إرسال/تعديل/تفاعل منفصلة لإجراءات الدردشة العادية. يحتفظ OpenClaw بأداة `message` مشتركة واحدة في النواة، -في حين تمتلك Plugins القنوات الاكتشاف والتنفيذ الخاصين بالقناة وراءها. +وتملك إضافات القنوات الاكتشاف والتنفيذ الخاصين بالقناة وراءها. الحد الحالي هو: -- تمتلك النواة مضيف أداة `message` المشتركة، وربط prompt، ومسك - الجلسة/السلسلة، وتوجيه التنفيذ -- تمتلك Plugins القنوات اكتشاف الإجراءات ذات النطاق، واكتشاف الإمكانات، وأي - أجزاء schema خاصة بالقناة -- تمتلك Plugins القنوات قواعد محادثة الجلسة الخاصة بالموفر، مثل - كيفية ترميز معرّفات المحادثات لمعرّفات السلاسل أو وراثتها من المحادثات الأصلية -- تنفذ Plugins القنوات الإجراء النهائي من خلال محول الإجراءات الخاص بها +- تملك النواة مضيف أداة `message` المشتركة، وربط الموجّه، ومسك + مفاتيح الجلسة/السلسلة، وتوجيه التنفيذ +- تملك إضافات القنوات اكتشاف الإجراءات المقيّدة، واكتشاف القدرات، وأي + أجزاء مخطط خاصة بالقناة +- تملك إضافات القنوات قواعد المحادثة الخاصة بالجلسة بحسب المزوّد، مثل + كيفية ترميز معرّفات المحادثة لمعرّفات السلاسل أو وراثتها من المحادثات الأصلية +- تنفذ إضافات القنوات الإجراء النهائي عبر مهايئ الإجراءات الخاص بها -بالنسبة إلى Plugins القنوات، فإن سطح SDK هو -`ChannelMessageActionAdapter.describeMessageTool(...)`. تسمح مكالمة الاكتشاف -الموحدة هذه للـ plugin بإرجاع إجراءاتها المرئية وإمكاناتها ومساهمات schema -معًا حتى لا تنحرف هذه الأجزاء عن بعضها. +بالنسبة إلى إضافات القنوات، سطح SDK هو +`ChannelMessageActionAdapter.describeMessageTool(...)`. يتيح هذا الاستدعاء +الموحّد للاكتشاف للإضافة أن تعيد إجراءاتها المرئية، وقدراتها، ومساهماتها +في المخطط معًا حتى لا تنفصل هذه الأجزاء عن بعضها. تمرر النواة نطاق وقت التشغيل إلى خطوة الاكتشاف هذه. وتشمل الحقول المهمة: @@ -189,129 +189,124 @@ plugin أصلية في OpenClaw تسجل نفسها في نوع قدرة واح - `sessionKey` - `sessionId` - `agentId` -- قيمة `requesterSenderId` الواردة الموثوقة +- `requesterSenderId` الوارد الموثوق -وهذا مهم للـ plugins الحساسة للسياق. إذ يمكن للقناة إخفاء أو إظهار -إجراءات الرسائل بناءً على الحساب النشط أو الغرفة/السلسلة/الرسالة الحالية أو -هوية الطالب الموثوقة، بدون ترميز فروع خاصة بالقناة داخل أداة `message` -في النواة. +وهذا مهم للإضافات الحساسة للسياق. يمكن للقناة إخفاء أو إظهار +إجراءات الرسائل استنادًا إلى الحساب النشط، أو الغرفة/السلسلة/الرسالة الحالية، أو +هوية الطالب الموثوقة، دون ترميز فروع خاصة بالقناة داخل أداة +`message` في النواة. -ولهذا السبب تظل تغييرات التوجيه في embedded-runner عملًا خاصًا بالـ plugin: -فالمشغّل مسؤول عن تمرير هوية الدردشة/الجلسة الحالية إلى حد -اكتشاف plugin حتى تعرض أداة `message` المشتركة السطح الصحيح المملوك للقناة -في الدورة الحالية. +ولهذا السبب لا تزال تغييرات توجيه العداء المضمّن من عمل الإضافة: إذ يقع على العداء +مسؤولية تمرير هوية الدردشة/الجلسة الحالية إلى حد اكتشاف الإضافة حتى +تكشف أداة `message` المشتركة السطح الصحيح المملوك للقناة للدور الحالي. -أما بالنسبة إلى مساعدات التنفيذ المملوكة للقناة، فيجب على plugins المضمّنة إبقاء -وقت تشغيل التنفيذ داخل وحدات الامتداد المملوكة لها. لم تعد النواة تمتلك -أوقات تشغيل إجراءات الرسائل الخاصة بـ Discord أو Slack أو Telegram أو WhatsApp -ضمن `src/agents/tools`. -كما أننا لا ننشر مسارات فرعية منفصلة `plugin-sdk/*-action-runtime`، ويجب على plugins -المضمّنة استيراد شيفرة وقت التشغيل المحلية الخاصة بها مباشرة من -وحدات الامتداد المملوكة لها. +أما بالنسبة إلى مساعدات التنفيذ المملوكة للقناة، فيجب على الإضافات المضمّنة إبقاء وقت تشغيل +التنفيذ داخل وحدات الامتداد الخاصة بها. لم تعد النواة تملك +أوقات تشغيل إجراءات الرسائل لـ Discord أو Slack أو Telegram أو WhatsApp تحت `src/agents/tools`. +نحن لا ننشر مسارات فرعية منفصلة من `plugin-sdk/*-action-runtime`، ويجب على +الإضافات المضمّنة استيراد كود وقت التشغيل المحلي الخاص بها مباشرة من +الوحدات المملوكة لامتدادها. -وينطبق الحد نفسه عمومًا على أسطح SDK المسماة باسم الموفر: يجب ألّا -تستورد النواة أشرطة راحة خاصة بالقنوات مثل Slack أو Discord أو Signal أو +وينطبق الحد نفسه على وصلات SDK المسماة بأسماء المزوّدين عمومًا: يجب ألا +تستورد النواة أشرطة راحة خاصة بالقنوات لـ Slack أو Discord أو Signal أو WhatsApp أو امتدادات مشابهة. إذا احتاجت النواة إلى سلوك ما، فإما أن تستهلك -شريط `api.ts` / `runtime-api.ts` الخاص بالـ plugin المضمّنة نفسها أو -ترفع الحاجة إلى قدرة عامة ضيقة في SDK المشتركة. +شريط `api.ts` / `runtime-api.ts` الخاص بالإضافة المضمّنة نفسها، أو +ترقّي الحاجة إلى قدرة عامة ضيقة في SDK المشترك. -وبالنسبة إلى استطلاعات الرأي تحديدًا، يوجد مساران للتنفيذ: +وبالنسبة إلى الاستطلاعات تحديدًا، هناك مساران للتنفيذ: -- `outbound.sendPoll` هو خط الأساس المشترك للقنوات التي تناسب نموذج - الاستطلاع الشائع -- `actions.handleAction("poll")` هو المسار المفضل لدلالات الاستطلاع الخاصة بالقناة - أو لمعاملات الاستطلاع الإضافية +- `outbound.sendPoll` هو خط الأساس المشترك للقنوات التي تناسب النموذج + العام للاستطلاع +- `actions.handleAction("poll")` هو المسار المفضل لدلالات الاستطلاع + الخاصة بالقناة أو معلمات الاستطلاع الإضافية -تؤجل النواة الآن تحليل الاستطلاع المشترك إلى ما بعد رفض إرسال الاستطلاع عبر plugin -للإجراء، حتى تتمكن معالجات الاستطلاع المملوكة للـ plugin من قبول -حقول استطلاع خاصة بالقناة دون أن يمنعها محلل الاستطلاع العام أولًا. +تؤجل النواة الآن التحليل المشترك للاستطلاع إلى ما بعد رفض توجيه استطلاع الإضافة +للإجراء، حتى تتمكن معالجات الاستطلاع المملوكة للإضافة من قبول حقول استطلاع +خاصة بالقناة دون أن يمنعها محلل الاستطلاع العام أولًا. -راجع [خط أنابيب التحميل](#load-pipeline) لمعرفة التسلسل الكامل عند بدء التشغيل. +راجع [خط أنابيب التحميل](#load-pipeline) للحصول على تسلسل بدء التشغيل الكامل. -## نموذج ملكية الإمكانات +## نموذج ملكية القدرات -يتعامل OpenClaw مع plugin الأصلية على أنها حد الملكية لـ **شركة** أو -**ميزة**، وليس مجرد حاوية لتكاملات غير مترابطة. +يعامل OpenClaw الإضافة الأصلية على أنها حد الملكية لـ **شركة** أو +**ميزة**، وليس كحقيبة مختلطة من عمليات التكامل غير المرتبطة. وهذا يعني: -- ينبغي عادةً أن تمتلك plugin الشركة جميع الأسطح التي يواجهها OpenClaw من تلك - الشركة -- ينبغي عادةً أن تمتلك plugin الميزة السطح الكامل للميزة التي تقدمها -- يجب أن تستهلك القنوات إمكانات النواة المشتركة بدلًا من إعادة تنفيذ - سلوك الموفر بشكل مخصص +- يجب أن تملك إضافة الشركة عادةً جميع الأسطح المواجهة لـ OpenClaw الخاصة بتلك الشركة +- يجب أن تملك إضافة الميزة عادةً سطح الميزة الكامل الذي تقدمه +- يجب أن تستهلك القنوات القدرات المشتركة في النواة بدلًا من إعادة تنفيذ + سلوك المزوّد بصورة مخصصة أمثلة: -- تمتلك plugin المضمّنة `openai` سلوك موفر نماذج OpenAI وسلوك +- تملك الإضافة المضمّنة `openai` سلوك مزوّد نماذج OpenAI وسلوك OpenAI للكلام + الصوت الفوري + فهم الوسائط + توليد الصور -- تمتلك plugin المضمّنة `elevenlabs` سلوك الكلام الخاص بـ ElevenLabs -- تمتلك plugin المضمّنة `microsoft` سلوك الكلام الخاص بـ Microsoft -- تمتلك plugin المضمّنة `google` سلوك موفر نماذج Google إضافة إلى - سلوك Google لفهم الوسائط + توليد الصور + بحث الويب -- تمتلك plugin المضمّنة `firecrawl` سلوك جلب الويب الخاص بـ Firecrawl -- تمتلك plugins المضمّنة `minimax` و`mistral` و`moonshot` و`zai` - خلفيات فهم الوسائط الخاصة بها -- تمتلك plugin `qwen` المضمّنة سلوك موفر النص في Qwen إضافة إلى - سلوك فهم الوسائط وتوليد الفيديو -- أما plugin `voice-call` فهي plugin ميزة: فهي تمتلك نقل المكالمات والأدوات، - وCLI، والمسارات، وجسر تدفق وسائط Twilio، لكنها تستهلك - إمكانات الكلام المشتركة إضافة إلى النسخ الفوري والصوت الفوري بدلًا من - استيراد plugins المورّدين مباشرة +- تملك الإضافة المضمّنة `elevenlabs` سلوك كلام ElevenLabs +- تملك الإضافة المضمّنة `microsoft` سلوك كلام Microsoft +- تملك الإضافة المضمّنة `google` سلوك مزوّد نماذج Google بالإضافة إلى + سلوك Google لفهم الوسائط + توليد الصور + البحث على الويب +- تملك الإضافة المضمّنة `firecrawl` سلوك جلب الويب لـ Firecrawl +- تملك الإضافات المضمّنة `minimax` و`mistral` و`moonshot` و`zai` + واجهاتها الخلفية لفهم الوسائط +- تملك الإضافة `voice-call` كميزة: نقل المكالمات، والأدوات، + وCLI، والمسارات، وجسر تدفق الوسائط لـ Twilio، لكنها تستهلك قدرات الكلام المشتركة + بالإضافة إلى النسخ الفوري والصوت الفوري بدلًا من استيراد إضافات المورّدين مباشرة الحالة النهائية المقصودة هي: -- يعيش OpenAI في plugin واحدة حتى لو امتد عبر نماذج النص والكلام والصور - وربما الفيديو مستقبلًا -- ويمكن لمورّد آخر أن يفعل الشيء نفسه لسطحه الخاص -- لا تهتم القنوات بأي plugin مورّد تمتلك الموفر؛ فهي تستهلك عقد - الإمكانات المشتركة التي تكشفها النواة +- يعيش OpenAI في إضافة واحدة حتى إذا امتد عبر نماذج النص، والكلام، والصور، + والفيديو مستقبلًا +- يمكن لمورّد آخر أن يفعل الشيء نفسه لمساحة سطحه الخاصة +- لا تهتم القنوات بأي إضافة مورّد تملك المزوّد؛ فهي تستهلك العقد + المشترك للقدرات الذي تكشفه النواة وهذا هو التمييز الأساسي: - **plugin** = حد الملكية -- **capability** = عقد النواة الذي يمكن أن تنفذه أو تستهلكه عدة plugins +- **capability** = عقد النواة الذي يمكن لعدة إضافات تنفيذه أو استهلاكه -لذا إذا أضاف OpenClaw مجالًا جديدًا مثل الفيديو، فالسؤال الأول ليس -"أي موفر يجب أن يرمّز معالجة الفيديو بشكل صلب؟" بل السؤال الأول هو "ما -عقد قدرة الفيديو في النواة؟" وبمجرد وجود هذا العقد، يمكن للـ plugins الخاصة بالمورّدين -التسجيل فيه، ويمكن للـ plugins الخاصة بالقنوات/الميزات استهلاكه. +لذلك إذا أضاف OpenClaw مجالًا جديدًا مثل الفيديو، فالسؤال الأول ليس +"أي مزوّد يجب أن يرمّز التعامل مع الفيديو مباشرة؟" بل السؤال الأول هو +"ما هو عقد قدرة الفيديو في النواة؟" وبمجرد وجود هذا العقد، تستطيع إضافات +المورّدين التسجيل مقابله ويمكن لإضافات القنوات/الميزات استهلاكه. -إذا لم تكن القدرة موجودة بعد، فعادةً ما تكون الخطوة الصحيحة هي: +إذا لم تكن القدرة موجودة بعد، فالخطوة الصحيحة عادة هي: 1. تعريف القدرة المفقودة في النواة -2. كشفها بطريقة مكتوبة الأنواع عبر واجهة برمجة plugin / وقت التشغيل +2. كشفها عبر واجهة برمجة الإضافة/وقت التشغيل بطريقة مكتوبة الأنواع 3. ربط القنوات/الميزات بهذه القدرة -4. والسماح للـ plugins الخاصة بالمورّدين بتسجيل التنفيذات +4. السماح لإضافات المورّدين بتسجيل التنفيذات -وهذا يُبقي الملكية صريحة مع تجنب سلوك في النواة يعتمد على -مورّد واحد أو مسار خاص بـ plugin واحدة. +يبقي هذا الملكية صريحة مع تجنب سلوك في النواة يعتمد على +مورّد واحد أو مسار كود خاص بإضافة واحدة. -### تدرج الإمكانات +### طبقات القدرات -استخدم هذا النموذج الذهني عند تقرير مكان الشيفرة: +استخدم هذا النموذج الذهني عند تقرير مكان الكود: -- **طبقة قدرات النواة**: التنسيق المشترك، والسياسة، والرجوع الاحتياطي، وقواعد دمج - الإعداد، ودلالات التسليم، والعقود المكتوبة -- **طبقة plugin المورّد**: واجهات API الخاصة بالمورّد، والمصادقة، وفهارس النماذج، وتوليف - الكلام، وتوليد الصور، وخلفيات الفيديو مستقبلًا، ونقاط نهاية الاستخدام -- **طبقة plugin القناة/الميزة**: تكاملات Slack/Discord/voice-call/... التي - تستهلك إمكانات النواة وتعرضها على سطح ما +- **طبقة قدرات النواة**: التنسيق المشترك، والسياسات، والاحتياط، وقواعد + دمج الإعدادات، ودلالات التسليم، والعقود المكتوبة الأنواع +- **طبقة إضافة المورّد**: واجهات برمجة التطبيقات الخاصة بالمورّد، والمصادقة، + وكتالوجات النماذج، وتوليف الكلام، وتوليد الصور، وواجهات الفيديو + المستقبلية، ونقاط نهاية الاستخدام +- **طبقة إضافة القناة/الميزة**: تكامل Slack/Discord/voice-call/... إلخ + الذي يستهلك قدرات النواة ويعرضها على سطح ما -على سبيل المثال، يتبع TTS هذا الشكل: +على سبيل المثال، يتبع تحويل النص إلى كلام هذا الشكل: -- تمتلك النواة سياسة TTS وقت الرد، وترتيب الرجوع، والتفضيلات، وتسليم القنوات -- وتملك `openai` و`elevenlabs` و`microsoft` تنفيذات التوليف -- وتستهلك `voice-call` مساعد وقت تشغيل TTS الخاص بالاتصالات الهاتفية +- تملك النواة سياسة TTS وقت الرد، وترتيب الاحتياط، والتفضيلات، وتسليم القناة +- تملك `openai` و`elevenlabs` و`microsoft` تنفيذات التوليف +- تستهلك `voice-call` مساعد وقت تشغيل TTS للهاتف -وينبغي تفضيل هذا النمط أيضًا للإمكانات المستقبلية. +ويجب تفضيل النمط نفسه للقدرات المستقبلية. -### مثال على plugin شركة متعددة الإمكانات +### مثال على إضافة شركة متعددة القدرات -يجب أن تبدو plugin الشركة متماسكة من الخارج. إذا كان لدى OpenClaw عقود مشتركة -للنماذج والكلام والنسخ الفوري والصوت الفوري وفهم الوسائط -وتوليد الصور وتوليد الفيديو وجلب الويب وبحث الويب، -فيمكن لمورّد امتلاك جميع أسطحه في مكان واحد: +يجب أن تبدو إضافة الشركة مترابطة من الخارج. إذا كان لدى OpenClaw عقود مشتركة +للنماذج، والكلام، والنسخ الفوري، والصوت الفوري، وفهم الوسائط، +وتوليد الصور، وتوليد الفيديو، وجلب الويب، والبحث على الويب، +فيمكن للمورّد امتلاك جميع أسطحه في مكان واحد: ```ts import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry"; @@ -365,221 +360,223 @@ const plugin: OpenClawPluginDefinition = { export default plugin; ``` -ما يهم ليس أسماء المساعدات بالضبط. بل الشكل هو المهم: +المهم ليس أسماء المساعدات الدقيقة. المهم هو الشكل: -- plugin واحدة تمتلك سطح المورّد -- لا تزال النواة تمتلك عقود الإمكانات -- تستهلك القنوات وplugins الميزات مساعدات `api.runtime.*`، لا شيفرة المورّد -- ويمكن لاختبارات العقد التحقق من أن plugin سجّلت الإمكانات التي - تدعي امتلاكها +- إضافة واحدة تملك سطح المورّد +- لا تزال النواة تملك عقود القدرات +- تستهلك إضافات القنوات والميزات مساعدات `api.runtime.*`، لا كود المورّد +- يمكن لاختبارات العقد تأكيد أن الإضافة سجلت القدرات التي + تدّعي أنها تملكها -### مثال على القدرة: فهم الفيديو +### مثال قدرة: فهم الفيديو -يعامل OpenClaw بالفعل فهم الصور/الصوت/الفيديو كقدرة مشتركة واحدة. -وينطبق نموذج الملكية نفسه هنا: +يعامل OpenClaw بالفعل فهم الصورة/الصوت/الفيديو على أنه قدرة مشتركة +واحدة. وينطبق نموذج الملكية نفسه هنا: 1. تعرّف النواة عقد فهم الوسائط -2. تسجل plugins الخاصة بالمورّدين `describeImage` و`transcribeAudio` و +2. تسجل إضافات المورّدين `describeImage` و`transcribeAudio` و `describeVideo` حسب الاقتضاء -3. تستهلك القنوات وplugins الميزات سلوك النواة المشترك بدلًا من - الربط المباشر بشيفرة المورّد +3. تستهلك إضافات القنوات والميزات السلوك المشترك في النواة بدلًا من + الربط المباشر مع كود المورّد -وهذا يتجنب ترسيخ افتراضات الفيديو الخاصة بموفّر واحد داخل النواة. فالـ plugin تمتلك -سطح المورّد؛ بينما تمتلك النواة عقد القدرة وسلوك الرجوع الاحتياطي. +هذا يمنع إدخال افتراضات الفيديو الخاصة بمزوّد واحد في النواة. فالإضافة تملك +سطح المورّد؛ والنواة تملك عقد القدرة وسلوك الاحتياط. -كما أن توليد الفيديو يتبع التسلسل نفسه بالفعل: فالنواة تمتلك عقد -القدرة المكتوب ومساعد وقت التشغيل، بينما تسجّل plugins الخاصة بالمورّدين -تنفيذات `api.registerVideoGenerationProvider(...)` له. +ويتبع توليد الفيديو بالفعل هذا التسلسل نفسه: تملك النواة عقد +القدرة المكتوب الأنواع ومساعد وقت التشغيل، وتسجل إضافات المورّدين +تنفيذات `api.registerVideoGenerationProvider(...)` مقابله. -هل تحتاج إلى قائمة إطلاق عملية؟ راجع -[Capability Cookbook](/ar/plugins/architecture). +هل تحتاج إلى قائمة تحقق عملية للنشر؟ راجع +[دليل القدرات](/ar/plugins/architecture). ## العقود وفرضها -سطح واجهة برمجة plugin مكتوب الأنواع ومركزي عمدًا في -`OpenClawPluginApi`. يعرّف هذا العقد نقاط التسجيل المدعومة -ومساعدات وقت التشغيل التي يمكن أن تعتمد عليها plugin. +سطح واجهة برمجة الإضافة مكتوب الأنواع ومركزي عمدًا في +`OpenClawPluginApi`. يعرّف هذا العقد نقاط التسجيل المدعومة و +مساعدات وقت التشغيل التي يمكن أن تعتمد عليها الإضافة. -لماذا هذا مهم: +سبب أهمية هذا: -- يحصل مؤلفو plugins على معيار داخلي واحد مستقر -- يمكن للنواة رفض الملكية المكررة، مثل تسجيل pluginَين لمعرّف الموفر نفسه -- يمكن لبدء التشغيل عرض تشخيصات قابلة للتنفيذ للتسجيلات غير الصحيحة -- يمكن لاختبارات العقد فرض ملكية plugins المضمّنة ومنع الانحراف الصامت +- يحصل مؤلفو الإضافات على معيار داخلي مستقر واحد +- يمكن للنواة رفض الملكية المكررة، مثل تسجيل إضافتين لمعرّف + المزوّد نفسه +- يمكن لبدء التشغيل إظهار تشخيصات عملية للتسجيل غير الصحيح +- يمكن لاختبارات العقد فرض ملكية الإضافات المضمّنة ومنع الانحراف الصامت هناك طبقتان من الفرض: -1. **فرض التسجيل في وقت التشغيل** - يتحقق سجل plugins من التسجيلات أثناء تحميل plugins. أمثلة: - معرّفات الموفّر المكررة، ومعرّفات موفر الكلام المكررة، والتسجيلات - غير الصحيحة تنتج تشخيصات للـ plugin بدلًا من سلوك غير معرّف. +1. **فرض التسجيل وقت التشغيل** + يتحقق سجل الإضافات من التسجيلات أثناء تحميل الإضافات. أمثلة: + تؤدي معرّفات المزوّدين المكررة، ومعرّفات مزوّدي الكلام المكررة، والتسجيلات + غير الصحيحة إلى تشخيصات للإضافة بدلًا من سلوك غير معرّف. 2. **اختبارات العقد** - يتم التقاط plugins المضمّنة في سجلات العقود أثناء تشغيل الاختبارات حتى - يتمكن OpenClaw من فرض الملكية صراحةً. ويُستخدم هذا اليوم لموفري النماذج، - وموفري الكلام، وموفري بحث الويب، وملكية التسجيل المضمّن. + تُلتقط الإضافات المضمّنة في سجلات العقود أثناء تشغيل الاختبارات حتى + يتمكن OpenClaw من تأكيد الملكية صراحة. ويُستخدم هذا اليوم من أجل + مزوّدي النماذج، ومزوّدي الكلام، ومزوّدي البحث على الويب، وملكية التسجيل + المضمّن. -والأثر العملي هو أن OpenClaw يعرف مسبقًا أي plugin تمتلك أي -سطح. وهذا يتيح للنواة والقنوات التركيب بسلاسة لأن الملكية مُعلنة -ومكتوبة وقابلة للاختبار بدلًا من أن تكون ضمنية. +الأثر العملي هو أن OpenClaw يعرف مسبقًا أي إضافة تملك أي +سطح. وهذا يسمح للنواة والقنوات بالتركيب السلس لأن الملكية +معلنة ومكتوبة الأنواع وقابلة للاختبار بدلًا من أن تكون ضمنية. ### ما الذي ينتمي إلى عقد -عقود plugins الجيدة تكون: +العقود الجيدة للإضافات تكون: - مكتوبة الأنواع - صغيرة -- خاصة بقدرة محددة +- خاصة بالقدرة - مملوكة للنواة -- قابلة لإعادة الاستخدام من عدة plugins -- قابلة للاستهلاك من القنوات/الميزات بدون معرفة بالمورّد +- قابلة لإعادة الاستخدام من عدة إضافات +- قابلة للاستهلاك من القنوات/الميزات دون معرفة بالمورّد -أما عقود plugins السيئة فهي: +العقود السيئة للإضافات تكون: -- سياسة خاصة بمورّد مخفية داخل النواة -- منافذ هروب خاصة بـ plugin واحدة تتجاوز السجل -- شيفرة قناة تصل مباشرة إلى تنفيذ مورّد +- سياسة خاصة بالمورّد مخفية في النواة +- مخارج خاصة لإضافة واحدة تتجاوز السجل +- كود القناة الذي يصل مباشرة إلى تنفيذ خاص بمورّد - كائنات وقت تشغيل مخصصة ليست جزءًا من `OpenClawPluginApi` أو `api.runtime` -عند الشك، ارفع مستوى التجريد: عرّف القدرة أولًا، ثم اسمح للـ plugins -بالارتباط بها. +عند الشك، ارفع مستوى التجريد: عرّف القدرة أولًا، ثم دع الإضافات +تتصل بها. ## نموذج التنفيذ -تعمل plugins الأصلية لـ OpenClaw **داخل العملية** مع Gateway. وهي غير -معزولة. وتملك plugin الأصلية المحمّلة حد ثقة على مستوى العملية مماثلًا -لشيفرة النواة. +تعمل إضافات OpenClaw الأصلية **داخل العملية** مع Gateway. وهي ليست +ضمن صندوق حماية. وللإضافة الأصلية المحمّلة حد الثقة نفسه على مستوى العملية مثل +كود النواة. الآثار: -- يمكن لـ plugin الأصلية تسجيل أدوات ومعالجات شبكات وخطافات وخدمات -- يمكن لخلل في plugin أصلية أن يعطل gateway أو يزعزع استقرارها -- plugin أصلية خبيثة تعادل تنفيذ شيفرة عشوائية داخل +- يمكن للإضافة الأصلية تسجيل أدوات ومعالجات شبكة وخطافات وخدمات +- يمكن لخلل في الإضافة الأصلية أن يعطّل البوابة أو يزعزع استقرارها +- تعادل الإضافة الأصلية الخبيثة تنفيذ كود عشوائي داخل عملية OpenClaw -الحزم المتوافقة أكثر أمانًا افتراضيًا لأن OpenClaw يعاملها حاليًا -كحِزم بيانات وصفية/محتوى. وفي الإصدارات الحالية، يعني ذلك في الغالب -Skills المضمّنة. +تكون الحزم المتوافقة أكثر أمانًا افتراضيًا لأن OpenClaw يعاملها حاليًا على +أنها حزم بيانات/محتوى. وفي الإصدارات الحالية، يعني هذا غالبًا +المهارات المضمّنة. -استخدم قوائم السماح ومسارات التثبيت/التحميل الصريحة للـ plugins غير المضمّنة. وتعامل مع -plugins الـ workspace كشيفرة وقت تطوير، لا كافتراضات إنتاج. +استخدم قوائم السماح ومسارات التثبيت/التحميل الصريحة للإضافات غير المضمّنة. وتعامل مع +إضافات مساحة العمل على أنها كود وقت تطوير، لا إعدادات إنتاج افتراضية. -وبالنسبة إلى أسماء حزم workspace المضمّنة، أبقِ معرّف plugin مثبتًا في -اسم npm: `@openclaw/` افتراضيًا، أو لاحقة نوعية معتمدة مثل +بالنسبة إلى أسماء حزم الإضافات المضمّنة في مساحة العمل، أبقِ معرّف الإضافة +مرتبطًا باسم npm: `@openclaw/` افتراضيًا، أو لاحقة نوعية معتمدة مثل `-provider` أو `-plugin` أو `-speech` أو `-sandbox` أو `-media-understanding` عندما -تكشف الحزمة عمدًا دور plugin أضيق. +تكشف الحزمة عمدًا عن دور إضافة أضيق. ملاحظة ثقة مهمة: -- تثق `plugins.allow` في **معرّفات plugins**، لا في مصدرها. -- إن plugin workspace لها المعرّف نفسه الذي لplugin مضمّنة تحجب - النسخة المضمّنة عمدًا عندما تكون plugin workspace هذه مفعلة/مدرجة في قائمة السماح. -- وهذا سلوك طبيعي ومفيد للتطوير المحلي واختبار الترقيعات والإصلاحات العاجلة. +- `plugins.allow` يثق في **معرّفات الإضافات**، وليس في مصدر الأصل. +- تقوم إضافة مساحة عمل لها المعرف نفسه كإضافة مضمّنة بإخفاء + النسخة المضمّنة عمدًا عندما تكون تلك الإضافة في مساحة العمل مفعّلة/مدرجة في قائمة السماح. +- هذا طبيعي ومفيد للتطوير المحلي، واختبار التصحيحات، والإصلاحات العاجلة. ## حد التصدير -يصدّر OpenClaw الإمكانات، لا وسائل راحة التنفيذ. +يُصدّر OpenClaw القدرات، لا وسائل الراحة التنفيذية. -أبقِ تسجيل الإمكانات عامًا. وقلّص صادرات المساعدات غير التعاقدية: +أبقِ تسجيل القدرات عامًا. وقلّص تصديرات المساعدات غير التعاقدية: -- المسارات الفرعية الخاصة بمساعدات plugins المضمّنة -- المسارات الفرعية الخاصة ببنية وقت التشغيل غير المقصود أن تكون API عامة -- مساعدات الراحة الخاصة بالمورّد +- المسارات الفرعية الخاصة بمساعدات الإضافات المضمّنة +- المسارات الفرعية الخاصة بسباكة وقت التشغيل غير المقصود أن تكون واجهة برمجة عامة +- المساعدات المريحة الخاصة بالمورّد - مساعدات الإعداد/التهيئة التي تُعد تفاصيل تنفيذ -لا تزال بعض المسارات الفرعية المساعدة للـ plugins المضمّنة موجودة في خريطة صادرات -SDK المُولَّدة من أجل التوافق وصيانة plugins المضمّنة. من الأمثلة الحالية -`plugin-sdk/feishu`، و`plugin-sdk/feishu-setup`، و`plugin-sdk/zalo`، -و`plugin-sdk/zalo-setup`، والعديد من حدود `plugin-sdk/matrix*`. تعامل مع هذه -على أنها صادرات محجوزة كتفاصيل تنفيذ، لا على أنها نمط SDK موصى به -للـ plugins الخارجية الجديدة. +لا تزال بعض المسارات الفرعية لمساعدات الإضافات المضمّنة موجودة في خريطة تصدير SDK +المولّدة من أجل التوافق وصيانة الإضافات المضمّنة. وتشمل الأمثلة الحالية +`plugin-sdk/feishu` و`plugin-sdk/feishu-setup` و`plugin-sdk/zalo` و +`plugin-sdk/zalo-setup` وعدة وصلات `plugin-sdk/matrix*`. تعامل مع هذه +على أنها تصديرات محجوزة لتفاصيل التنفيذ، وليست النمط الموصى به في SDK +للإضافات الخارجية الجديدة. ## خط أنابيب التحميل -عند بدء التشغيل، يقوم OpenClaw تقريبًا بما يلي: +عند بدء التشغيل، يفعل OpenClaw تقريبًا ما يلي: -1. اكتشاف جذور plugins المرشحة -2. قراءة البيانات الأصلية أو بيانات الحزم المتوافقة وبيانات الحزمة +1. اكتشاف جذور الإضافات المرشحة +2. قراءة بيانات الإضافات الأصلية أو بيانات الحزم المتوافقة وبيانات الحزم 3. رفض المرشحين غير الآمنين -4. تطبيع إعداد plugin (`plugins.enabled`، و`allow`، و`deny`، و`entries`، - و`slots`، و`load.paths`) -5. تحديد التمكين لكل مرشح +4. تطبيع إعدادات الإضافات (`plugins.enabled` و`allow` و`deny` و`entries` و + `slots` و`load.paths`) +5. تقرير التمكين لكل مرشح 6. تحميل الوحدات الأصلية المفعلة عبر jiti -7. استدعاء خطافات `register(api)` الأصلية (أو `activate(api)` — وهو اسم قديم بديل) وجمع التسجيلات في سجل plugin -8. كشف السجل إلى أسطح الأوامر/وقت التشغيل +7. استدعاء خطافات `register(api)` الأصلية (أو `activate(api)` — اسم بديل قديم) وجمع التسجيلات في سجل الإضافات +8. كشف السجل لأسطح الأوامر/وقت التشغيل -`activate` اسم قديم بديل لـ `register` — يحل المحمّل أيهما موجود (`def.register ?? def.activate`) ويستدعيه في النقطة نفسها. تستخدم جميع plugins المضمّنة `register`؛ ويفضل استخدام `register` في plugins الجديدة. +`activate` اسم بديل قديم لـ `register` — يحل أداة التحميل أيّهما موجود (`def.register ?? def.activate`) ويستدعيه في النقطة نفسها. تستخدم جميع الإضافات المضمّنة `register`؛ وفضّل `register` للإضافات الجديدة. -تحدث بوابات الأمان **قبل** تنفيذ وقت التشغيل. يتم حظر المرشحين -عندما يخرج الإدخال من جذر plugin، أو يكون المسار قابلاً للكتابة من الجميع، -أو تبدو ملكية المسار مشبوهة للـ plugins غير المضمّنة. +تحدث بوابات الأمان **قبل** تنفيذ وقت التشغيل. يُحظر المرشحون +عندما يخرج المدخل من جذر الإضافة، أو يكون المسار قابلاً للكتابة عالميًا، أو +تبدو ملكية المسار مريبة للإضافات غير المضمّنة. ### سلوك البيان أولًا -البيان هو مصدر الحقيقة في مستوى التحكم. يستخدمه OpenClaw من أجل: +البيان هو مصدر الحقيقة لمستوى التحكم. يستخدمه OpenClaw من أجل: -- تحديد plugin -- اكتشاف القنوات/Skills/schema الإعداد المعلنة أو إمكانات الحزمة +- تحديد الإضافة +- اكتشاف القنوات/المهارات/مخطط الإعدادات المعلنة أو قدرات الحزمة - التحقق من `plugins.entries..config` -- تعزيز تسميات/عناصر نائبة لـ Control UI -- عرض بيانات التثبيت/الفهرس +- تعزيز تسميات/عناصر نائبة في Control UI +- إظهار بيانات التثبيت/الكتالوج -وبالنسبة إلى plugins الأصلية، فإن وحدة وقت التشغيل هي جزء مستوى البيانات. فهي تسجل -السلوك الفعلي مثل الخطافات أو الأدوات أو الأوامر أو تدفقات الموفر. +بالنسبة إلى الإضافات الأصلية، تكون وحدة وقت التشغيل هي جزء مستوى البيانات. وهي تسجل +السلوك الفعلي مثل الخطافات، أو الأدوات، أو الأوامر، أو تدفقات المزوّد. -### ما الذي يخزنه المحمّل مؤقتًا +### ما الذي تخزنه أداة التحميل مؤقتًا -يحتفظ OpenClaw بذاكرات تخزين مؤقت قصيرة داخل العملية من أجل: +يحتفظ OpenClaw بذاكرات مؤقتة قصيرة داخل العملية من أجل: - نتائج الاكتشاف - بيانات سجل البيان -- سجلات plugins المحمّلة +- سجلات الإضافات المحمّلة -تقلل هذه الذاكرات من أعباء بدء التشغيل المتقطع وتكرار الأوامر. -ومن الآمن اعتبارها ذواكر أداء قصيرة العمر، لا تخزينًا دائمًا. +تقلل هذه الذاكرات المؤقتة من بدء التشغيل المتقطع وتكرار عبء الأوامر. ومن الآمن +اعتبارها ذاكرات مؤقتة قصيرة العمر للأداء، لا تخزينًا دائمًا. ملاحظة أداء: -- اضبط `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` أو - `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1` لتعطيل هذه الذواكر المؤقتة. -- ويمكنك ضبط نوافذ التخزين المؤقت بواسطة `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` و +- عيّن `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` أو + `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1` لتعطيل هذه الذاكرات المؤقتة. +- اضبط نوافذ الذاكرة المؤقتة باستخدام `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` و `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS`. ## نموذج السجل -لا تعدّل plugins المحمّلة مباشرة متغيرات عشوائية عامة في النواة. بل تسجل نفسها في -سجل plugins مركزي. +لا تعدّل الإضافات المحمّلة متغيرات عشوائية في النواة مباشرة. بل تسجّل في +سجل إضافات مركزي. -يتتبع السجل: +يتتبع السجل ما يلي: -- سجلات plugins (الهوية، والمصدر، والمنشأ، والحالة، والتشخيصات) +- سجلات الإضافات (الهوية، والمصدر، والأصل، والحالة، والتشخيصات) - الأدوات -- الخطافات القديمة والخطافات المكتوبة +- الخطافات القديمة والخطافات المكتوبة الأنواع - القنوات -- الموفّرين +- المزوّدون - معالجات Gateway RPC - مسارات HTTP -- مسجلات CLI +- مسجّلات CLI - الخدمات الخلفية -- الأوامر المملوكة للـ plugin +- الأوامر المملوكة للإضافة -ثم تقرأ ميزات النواة من هذا السجل بدلًا من التحدث مباشرة إلى وحدات -plugins. وهذا يُبقي التحميل في اتجاه واحد: +ثم تقرأ ميزات النواة من هذا السجل بدلًا من التحدث إلى وحدات الإضافات +مباشرة. وهذا يبقي التحميل في اتجاه واحد: -- وحدة plugin -> التسجيل في السجل +- وحدة الإضافة -> التسجيل في السجل - وقت تشغيل النواة -> استهلاك السجل -وهذا الفصل مهم لقابلية الصيانة. فهو يعني أن معظم أسطح النواة تحتاج فقط -إلى نقطة تكامل واحدة: "اقرأ السجل"، لا "ضع حالة خاصة لكل وحدة plugin". +وهذا الفصل مهم لقابلية الصيانة. فهو يعني أن معظم أسطح النواة لا +تحتاج إلا إلى نقطة تكامل واحدة: "اقرأ السجل"، لا "خصّص كل وحدة إضافة على حدة". ## نداءات ربط المحادثة -يمكن للـ plugins التي تربط محادثة أن تتفاعل عند حل الموافقة. +يمكن للإضافات التي تربط محادثة أن تتفاعل عند حل الموافقة. -استخدم `api.onConversationBindingResolved(...)` لتلقي نداء بعد الموافقة على -طلب الربط أو رفضه: +استخدم `api.onConversationBindingResolved(...)` لتلقي نداء بعد اعتماد أو رفض +طلب الربط: ```ts export default { @@ -601,126 +598,126 @@ export default { حقول حمولة النداء: -- `status`: إما `"approved"` أو `"denied"` -- `decision`: إما `"allow-once"` أو `"allow-always"` أو `"deny"` -- `binding`: الربط المحلول للطلبات المعتمدة -- `request`: ملخص الطلب الأصلي، وتلميح الفصل، ومعرّف المرسل، وبيانات - المحادثة الوصفية +- `status`: `"approved"` أو `"denied"` +- `decision`: `"allow-once"` أو `"allow-always"` أو `"deny"` +- `binding`: الربط الذي تم حله للطلبات المعتمدة +- `request`: ملخص الطلب الأصلي، وتلميح الفصل، ومعرّف المرسِل، + وبيانات المحادثة -هذا النداء مخصّص للإشعار فقط. ولا يغيّر من يُسمح له بربط +هذا النداء للإشعار فقط. فهو لا يغيّر من يُسمح له بربط محادثة، ويعمل بعد انتهاء معالجة الموافقة في النواة. -## خطافات وقت تشغيل الموفّر +## خطافات وقت تشغيل المزوّد -تملك Plugins الموفر الآن طبقتين: +أصبح لدى إضافات المزوّد الآن طبقتان: -- بيانات وصفية في البيان: `providerAuthEnvVars` للبحث الرخيص عن مصادقة الموفر عبر env - قبل تحميل وقت التشغيل، و`channelEnvVars` للبحث الرخيص عن env/إعداد القناة - قبل تحميل وقت التشغيل، إضافة إلى `providerAuthChoices` لعرض - تسميات onboarding/اختيار المصادقة وبيانات أعلام CLI البسيطة قبل تحميل وقت التشغيل -- خطافات وقت الإعداد: `catalog` / الاسم القديم `discovery` إضافة إلى `applyConfigDefaults` -- خطافات وقت التشغيل: `normalizeModelId`، و`normalizeTransport`، - و`normalizeConfig`، - و`applyNativeStreamingUsageCompat`، و`resolveConfigApiKey`، - و`resolveSyntheticAuth`، و`resolveExternalAuthProfiles`، - و`shouldDeferSyntheticProfileAuth`، - و`resolveDynamicModel`، و`prepareDynamicModel`، و`normalizeResolvedModel`، - و`contributeResolvedModelCompat`، و`capabilities`، - و`normalizeToolSchemas`، و`inspectToolSchemas`, - و`resolveReasoningOutputMode`، و`prepareExtraParams`، و`createStreamFn`, - و`wrapStreamFn`، و`resolveTransportTurnState`, - و`resolveWebSocketSessionPolicy`، و`formatApiKey`، و`refreshOAuth`, - و`buildAuthDoctorHint`، و`matchesContextOverflowError`, - و`classifyFailoverReason`، و`isCacheTtlEligible`, - و`buildMissingAuthMessage`، و`suppressBuiltInModel`، و`augmentModelCatalog`, - و`isBinaryThinking`، و`supportsXHighThinking`, - و`resolveDefaultThinkingLevel`، و`isModernModelRef`، و`prepareRuntimeAuth`, - و`resolveUsageAuth`، و`fetchUsageSnapshot`، و`createEmbeddingProvider`, - و`buildReplayPolicy`, - و`sanitizeReplayHistory`، و`validateReplayTurns`، و`onModelSelected` +- بيانات البيان: `providerAuthEnvVars` للبحث الرخيص عن مصادقة المزوّد + عبر متغيرات البيئة قبل تحميل وقت التشغيل، و`channelEnvVars` للبحث الرخيص + عن إعداد/بيئة القناة قبل تحميل وقت التشغيل، بالإضافة إلى `providerAuthChoices` + للتسميات الرخيصة لخيارات الإعداد/المصادقة وبيانات أعلام CLI قبل تحميل وقت التشغيل +- خطافات وقت الإعداد: `catalog` / الاسم القديم `discovery` بالإضافة إلى `applyConfigDefaults` +- خطافات وقت التشغيل: `normalizeModelId`, `normalizeTransport`, + `normalizeConfig`, + `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, + `resolveSyntheticAuth`, `resolveExternalAuthProfiles`, + `shouldDeferSyntheticProfileAuth`, + `resolveDynamicModel`, `prepareDynamicModel`, `normalizeResolvedModel`, + `contributeResolvedModelCompat`, `capabilities`, + `normalizeToolSchemas`, `inspectToolSchemas`, + `resolveReasoningOutputMode`, `prepareExtraParams`, `createStreamFn`, + `wrapStreamFn`, `resolveTransportTurnState`, + `resolveWebSocketSessionPolicy`, `formatApiKey`, `refreshOAuth`, + `buildAuthDoctorHint`, `matchesContextOverflowError`, + `classifyFailoverReason`, `isCacheTtlEligible`, + `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, + `isBinaryThinking`, `supportsXHighThinking`, + `resolveDefaultThinkingLevel`, `isModernModelRef`, `prepareRuntimeAuth`, + `resolveUsageAuth`, `fetchUsageSnapshot`, `createEmbeddingProvider`, + `buildReplayPolicy`, + `sanitizeReplayHistory`, `validateReplayTurns`, `onModelSelected` -لا يزال OpenClaw يمتلك الحلقة العامة للوكيل، والرجوع الاحتياطي، ومعالجة -النصوص، وسياسة الأدوات. وهذه الخطافات هي سطح الامتداد للسلوك الخاص بالمورّد دون -الحاجة إلى نقل استدلال مخصص كامل. +لا تزال OpenClaw تملك الحلقة العامة للوكيل، والفشل الاحتياطي، ومعالجة النصوص، +وسياسة الأدوات. وتمثل هذه الخطافات سطح الامتداد للسلوك الخاص بالمزوّد دون +الحاجة إلى نقل استدلال مخصص بالكامل. -استخدم `providerAuthEnvVars` في البيان عندما يكون لدى الموفر بيانات اعتماد -مستندة إلى env يجب أن تراها مسارات auth/status/model-picker العامة بدون -تحميل وقت تشغيل plugin. واستخدم `providerAuthChoices` في البيان عندما -تحتاج أسطح onboarding/اختيار المصادقة في CLI إلى معرفة معرّف اختيار الموفر، -وتسميات المجموعة، وربط المصادقة البسيط بعلم واحد دون تحميل وقت تشغيل الموفر. -وأبقِ `envVars` في وقت تشغيل الموفر للتلميحات الموجهة للمشغّل، مثل تسميات -onboarding أو متغيرات إعداد OAuth client-id/client-secret. +استخدم البيان `providerAuthEnvVars` عندما يكون لدى المزوّد بيانات اعتماد +تعتمد على متغيرات البيئة ويجب أن تراها مسارات المصادقة/الحالة/منتقي النماذج العامة +دون تحميل وقت تشغيل الإضافة. واستخدم البيان `providerAuthChoices` عندما +تحتاج أسطح CLI الخاصة بالإعداد/اختيار المصادقة إلى معرفة معرّف اختيار المزوّد، +وتسميات المجموعات، وربط المصادقة البسيط بعلم واحد دون تحميل وقت تشغيل المزوّد. +وأبقِ `envVars` في وقت تشغيل المزوّد لتلميحات موجهة للمشغّل مثل تسميات الإعداد أو +متغيرات إعداد OAuth client-id/client-secret. -واستخدم `channelEnvVars` في البيان عندما تكون لدى القناة مصادقة أو إعداد -مدفوع بـ env يجب أن تراه بدائل shell-env العامة، وفحوصات الإعداد/الحالة، -أو مطالبات الإعداد دون تحميل وقت تشغيل القناة. +استخدم البيان `channelEnvVars` عندما تكون لدى القناة مصادقة أو إعداد يعتمد +على البيئة ويجب أن تراه بدائل shell-env العامة، أو فحوصات config/status، أو +مطالبات الإعداد، دون تحميل وقت تشغيل القناة. ### ترتيب الخطافات واستخدامها -بالنسبة إلى Plugins النماذج/الموفّر، يستدعي OpenClaw الخطافات تقريبًا بهذا الترتيب. -ويُعد عمود "متى يُستخدم" دليل القرار السريع. +بالنسبة إلى إضافات النموذج/المزوّد، يستدعي OpenClaw الخطافات تقريبًا بهذا الترتيب. +ويمثل عمود "متى يُستخدم" دليل القرار السريع. | # | الخطاف | ما الذي يفعله | متى يُستخدم | -| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | نشر إعداد الموفر إلى `models.providers` أثناء توليد `models.json` | عندما يمتلك الموفر فهرسًا أو إعدادات افتراضية لـ base URL | -| 2 | `applyConfigDefaults` | تطبيق الإعدادات الافتراضية العامة المملوكة للموفر أثناء تشكيل الإعداد | عندما تعتمد القيم الافتراضية على وضع المصادقة أو env أو دلالات عائلة نماذج الموفر | -| -- | _(بحث النماذج المضمنة)_ | يحاول OpenClaw أولًا مسار السجل/الفهرس العادي | _(ليس خطاف plugin)_ | -| 3 | `normalizeModelId` | تطبيع الأسماء البديلة القديمة أو المعاينة لمعرّف النموذج قبل البحث | عندما يمتلك الموفر تنظيف الأسماء البديلة قبل الحل القانوني للنموذج | -| 4 | `normalizeTransport` | تطبيع `api` / `baseUrl` لعائلة الموفر قبل التجميع العام للنموذج | عندما يمتلك الموفر تنظيف النقل لمعرّفات موفّر مخصصة ضمن عائلة النقل نفسها | -| 5 | `normalizeConfig` | تطبيع `models.providers.` قبل حل وقت التشغيل/الموفر | عندما يحتاج الموفر إلى تنظيف إعداد يجب أن يعيش مع plugin؛ وتؤمّن مساعدات Google المضمّنة أيضًا تنظيفًا احتياطيًا لإدخالات Google المدعومة | -| 6 | `applyNativeStreamingUsageCompat` | تطبيق إعادة كتابة توافق استخدام البث الأصلي على موفري الإعداد | عندما يحتاج الموفر إلى إصلاحات بيانات وصفية لاستخدام البث الأصلي مدفوعة بنقطة النهاية | -| 7 | `resolveConfigApiKey` | حل مصادقة env-marker لموفري الإعداد قبل تحميل مصادقة وقت التشغيل | عندما يملك الموفر حل API-key عبر env-marker خاصًا به؛ كما يملك `amazon-bedrock` محلل AWS مضمّنًا هنا | -| 8 | `resolveSyntheticAuth` | إظهار مصادقة محلية/مستضافة ذاتيًا أو مستندة إلى الإعداد دون حفظ نص عادي | عندما يستطيع الموفر العمل بعلامة اعتماد صناعية/محلية | -| 9 | `resolveExternalAuthProfiles` | تراكب ملفات مصادقة خارجية مملوكة للموفر؛ تكون `persistence` افتراضيًا `runtime-only` لبيانات اعتماد CLI/app | عندما يعيد الموفر استخدام بيانات اعتماد خارجية دون حفظ رموز تحديث منسوخة | -| 10 | `shouldDeferSyntheticProfileAuth` | إنزال أولوية ملفات placeholder الصناعية المخزنة خلف مصادقة env/config | عندما يخزن الموفر ملفات placeholder صناعية لا ينبغي أن تربح في الترتيب | -| 11 | `resolveDynamicModel` | رجوع متزامن لمعرّفات نماذج مملوكة للموفر ليست موجودة بعد في السجل المحلي | عندما يقبل الموفر أي معرّفات نماذج upstream | -| 12 | `prepareDynamicModel` | تمهيد غير متزامن، ثم يُشغَّل `resolveDynamicModel` مرة أخرى | عندما يحتاج الموفر إلى بيانات وصفية شبكية قبل حل المعرّفات غير المعروفة | -| 13 | `normalizeResolvedModel` | إعادة كتابة نهائية قبل استخدام النموذج المحلول في embedded runner | عندما يحتاج الموفر إلى إعادة كتابة النقل لكنه ما زال يستخدم نقلًا من النواة | -| 14 | `contributeResolvedModelCompat` | تقديم أعلام توافق لنماذج مورّد خلف نقل متوافق آخر | عندما يتعرف الموفر على نماذجه خلف وسائل نقل وكيلة دون الاستيلاء على الموفّر | -| 15 | `capabilities` | بيانات وصفية للنصوص/الأدوات مملوكة للموفر وتستخدمها منطق النواة المشترك | عندما يحتاج الموفر إلى خصائص شاذة في النصوص/عائلة الموفّر | -| 16 | `normalizeToolSchemas` | تطبيع schemas الأدوات قبل أن يراها embedded runner | عندما يحتاج الموفر إلى تنظيف schema خاص بعائلة النقل | -| 17 | `inspectToolSchemas` | إظهار تشخيصات schemas مملوكة للموفر بعد التطبيع | عندما يريد الموفر تحذيرات الكلمات المفتاحية دون تعليم النواة قواعد خاصة بالموفر | -| 18 | `resolveReasoningOutputMode` | اختيار عقد مخرجات reasoning الأصلية مقابل المعلّمة | عندما يحتاج الموفر إلى reasoning/final output معلّمة بدل الحقول الأصلية | -| 19 | `prepareExtraParams` | تطبيع معاملات الطلب قبل مغلفات خيارات البث العامة | عندما يحتاج الموفر إلى معاملات طلب افتراضية أو تنظيف خاص بكل موفر | -| 20 | `createStreamFn` | استبدال مسار البث العادي بالكامل بنقل مخصص | عندما يحتاج الموفر إلى بروتوكول سلكي مخصص، وليس مجرد مغلف | -| 21 | `wrapStreamFn` | مغلف بث بعد تطبيق المغلفات العامة | عندما يحتاج الموفر إلى مغلفات headers/body/model توافقية بدون نقل مخصص | -| 22 | `resolveTransportTurnState` | إرفاق headers أو بيانات وصفية أصلية لكل دورة نقل | عندما يريد الموفر أن ترسل وسائل النقل العامة هوية دورة أصلية خاصة به | -| 23 | `resolveWebSocketSessionPolicy` | إرفاق headers أصلية لـ WebSocket أو سياسة تهدئة للجلسة | عندما يريد الموفر أن تضبط وسائل نقل WS العامة headers الجلسة أو سياسة الرجوع | -| 24 | `formatApiKey` | منسّق ملف المصادقة: الملف المخزن يصبح سلسلة `apiKey` في وقت التشغيل | عندما يخزّن الموفر بيانات مصادقة إضافية ويحتاج شكل رمز وقت تشغيل مخصص | -| 25 | `refreshOAuth` | تجاوز لتحديث OAuth لنقاط تحديث مخصصة أو سياسة فشل التحديث | عندما لا يناسب الموفر أدوات التحديث المشتركة في `pi-ai` | -| 26 | `buildAuthDoctorHint` | تلميح إصلاح يُضاف عند فشل تحديث OAuth | عندما يحتاج الموفر إلى إرشاد إصلاح مصادقة مملوك له بعد فشل التحديث | -| 27 | `matchesContextOverflowError` | مطابق مملوك للموفر لأخطاء تجاوز نافذة السياق | عندما تكون لدى الموفر أخطاء تجاوز خام لا تلتقطها الاستدلالات العامة | -| 28 | `classifyFailoverReason` | تصنيف مملوك للموفر لأسباب الرجوع الاحتياطي | عندما يستطيع الموفر ربط أخطاء API/النقل الخام بحد المعدل/التحميل الزائد/... | -| 29 | `isCacheTtlEligible` | سياسة prompt-cache لموفري proxy/backhaul | عندما يحتاج الموفر إلى بوابة TTL خاصة بالوكيل | -| 30 | `buildMissingAuthMessage` | بديل للرسالة العامة الخاصة بنقص المصادقة | عندما يحتاج الموفر إلى تلميح استرداد خاص به عند فقدان المصادقة | -| 31 | `suppressBuiltInModel` | إخفاء النماذج القديمة upstream مع تلميح خطأ اختياري للمستخدم | عندما يحتاج الموفر إلى إخفاء صفوف upstream قديمة أو استبدالها بتلميح مملوك للمورّد | -| 32 | `augmentModelCatalog` | إلحاق صفوف فهرس صناعية/نهائية بعد الاكتشاف | عندما يحتاج الموفر إلى صفوف توافق أمامي صناعية في `models list` والمنتقيات | -| 33 | `isBinaryThinking` | تبديل reasoning تشغيل/إيقاف للموفرين ثنائيي التفكير | عندما يكشف الموفر تفكيرًا ثنائيًا فقط | -| 34 | `supportsXHighThinking` | دعم `xhigh` reasoning لنماذج مختارة | عندما يريد الموفر `xhigh` فقط لمجموعة فرعية من النماذج | -| 35 | `resolveDefaultThinkingLevel` | مستوى `/think` الافتراضي لعائلة نموذج محددة | عندما يمتلك الموفر سياسة `/think` الافتراضية لعائلة نموذج | -| 36 | `isModernModelRef` | مطابق النموذج الحديث لفلاتر الملفات المباشرة واختيار smoke | عندما يمتلك الموفر مطابقة النموذج المفضل للبث/الاختبار | -| 37 | `prepareRuntimeAuth` | تبديل بيانات اعتماد مضبوطة إلى رمز/مفتاح وقت التشغيل الفعلي قبل الاستدلال مباشرة | عندما يحتاج الموفر إلى تبادل رمز أو بيانات اعتماد طلب قصيرة العمر | -| 38 | `resolveUsageAuth` | حل بيانات اعتماد الاستخدام/الفوترة لـ `/usage` والأسطح ذات الصلة | عندما يحتاج الموفر إلى تحليل رمز استخدام/حصة مخصص أو بيانات اعتماد استخدام مختلفة | -| 39 | `fetchUsageSnapshot` | جلب وتطبيع لقطات الاستخدام/الحصة الخاصة بالموفر بعد حل المصادقة | عندما يحتاج الموفر إلى نقطة نهاية استخدام أو محلل حمولة خاص به | -| 40 | `createEmbeddingProvider` | بناء محول embedding مملوك للموفر للذاكرة/البحث | عندما يجب أن ينتمي سلوك embedding الخاص بالذاكرة إلى plugin الموفر | -| 41 | `buildReplayPolicy` | إرجاع سياسة replay تتحكم في معالجة النصوص لدى الموفر | عندما يحتاج الموفر إلى سياسة نصوص مخصصة (مثل إزالة كتل التفكير) | -| 42 | `sanitizeReplayHistory` | إعادة كتابة تاريخ replay بعد تنظيف النصوص العام | عندما يحتاج الموفر إلى إعادة كتابة خاصة به تتجاوز مساعدات الضغط المشتركة | -| 43 | `validateReplayTurns` | تحقق نهائي من دورات replay أو إعادة تشكيلها قبل embedded runner | عندما يحتاج نقل الموفر إلى تحقق أشد لدورات replay بعد التنقية العامة | -| 44 | `onModelSelected` | تشغيل آثار جانبية مملوكة للموفر بعد الاختيار | عندما يحتاج الموفر إلى telemetry أو حالة مملوكة له عند تنشيط نموذج | +| --- | --------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | `catalog` | نشر إعدادات المزوّد داخل `models.providers` أثناء توليد `models.json` | عندما يملك المزوّد كتالوجًا أو إعدادات افتراضية لـ base URL | +| 2 | `applyConfigDefaults` | تطبيق إعدادات افتراضية عامة مملوكة للمزوّد أثناء تشكيل الإعدادات | عندما تعتمد الإعدادات الافتراضية على وضع المصادقة أو البيئة أو دلالات عائلة نموذج المزوّد | +| -- | _(البحث المضمّن عن النموذج)_ | يحاول OpenClaw أولًا مسار السجل/الكتالوج العادي | _(ليس خطاف إضافة)_ | +| 3 | `normalizeModelId` | تطبيع الأسماء البديلة القديمة أو التجريبية لمعرّف النموذج قبل البحث | عندما يملك المزوّد تنظيف الأسماء البديلة قبل حل النموذج القانوني | +| 4 | `normalizeTransport` | تطبيع `api` / `baseUrl` لعائلة المزوّد قبل التجميع العام للنموذج | عندما يملك المزوّد تنظيف النقل لمعرّفات مزوّد مخصصة ضمن عائلة النقل نفسها | +| 5 | `normalizeConfig` | تطبيع `models.providers.` قبل حل وقت التشغيل/المزوّد | عندما يحتاج المزوّد إلى تنظيف إعدادات يجب أن يعيش مع الإضافة؛ كما تدعم مساعدات Google-family المضمّنة إدخالات Google المدعومة | +| 6 | `applyNativeStreamingUsageCompat` | تطبيق إعادة كتابة توافق استخدام التدفق الأصلي على مزوّدي الإعدادات | عندما يحتاج المزوّد إلى إصلاحات بيانات استخدام التدفق الأصلي المعتمدة على نقطة النهاية | +| 7 | `resolveConfigApiKey` | حل مصادقة env-marker لمزوّدي الإعدادات قبل تحميل مصادقة وقت التشغيل | عندما يملك المزوّد حل API key خاصًا به عبر env-marker؛ و`amazon-bedrock` لديه أيضًا محلل AWS مضمّن هنا | +| 8 | `resolveSyntheticAuth` | إظهار المصادقة المحلية/المستضافة ذاتيًا أو المعتمدة على الإعدادات دون تخزين نص واضح | عندما يستطيع المزوّد العمل باستخدام علامة اعتماد اصطناعية/محلية | +| 9 | `resolveExternalAuthProfiles` | تراكب ملفات المصادقة الخارجية المملوكة للمزوّد؛ والقيمة الافتراضية لـ `persistence` هي `runtime-only` لاعتمادات CLI/app | عندما يعيد المزوّد استخدام اعتمادات مصادقة خارجية دون تخزين رموز تحديث منسوخة | +| 10 | `shouldDeferSyntheticProfileAuth` | خفض أولوية العناصر النائبة الاصطناعية المخزنة خلف المصادقة المعتمدة على env/config | عندما يخزن المزوّد ملفات تعريف اصطناعية نائبة لا يجب أن تفوز بالأولوية | +| 11 | `resolveDynamicModel` | احتياط متزامن لمعرّفات النماذج المملوكة للمزوّد غير الموجودة بعد في السجل المحلي | عندما يقبل المزوّد معرّفات نماذج عشوائية من المنبع | +| 12 | `prepareDynamicModel` | تهيئة غير متزامنة، ثم يعمل `resolveDynamicModel` مرة أخرى | عندما يحتاج المزوّد إلى بيانات شبكة قبل حل المعرّفات غير المعروفة | +| 13 | `normalizeResolvedModel` | إعادة كتابة نهائية قبل أن يستخدم العداء المضمّن النموذج المحلول | عندما يحتاج المزوّد إلى إعادة كتابة للنقل مع الاستمرار في استخدام نقل من النواة | +| 14 | `contributeResolvedModelCompat` | تقديم أعلام توافق لنماذج المورّد خلف نقل متوافق آخر | عندما يتعرف المزوّد على نماذجه عبر عمليات نقل وكيلة دون الاستيلاء على المزوّد | +| 15 | `capabilities` | بيانات نصوص/أدوات مملوكة للمزوّد تستخدمها منطق النواة المشتركة | عندما يحتاج المزوّد إلى خصائص عائلة النصوص/المزوّد | +| 16 | `normalizeToolSchemas` | تطبيع مخططات الأدوات قبل أن يراها العداء المضمّن | عندما يحتاج المزوّد إلى تنظيف المخطط لعائلة النقل | +| 17 | `inspectToolSchemas` | إظهار تشخيصات مخططات مملوكة للمزوّد بعد التطبيع | عندما يريد المزوّد تحذيرات الكلمات المفتاحية دون تعليم النواة قواعد خاصة بالمزوّد | +| 18 | `resolveReasoningOutputMode` | اختيار عقد إخراج الاستدلال الأصلي أو الموسوم | عندما يحتاج المزوّد إلى reasoning/final output موسوم بدلًا من الحقول الأصلية | +| 19 | `prepareExtraParams` | تطبيع معلمات الطلب قبل أغلفة خيارات التدفق العامة | عندما يحتاج المزوّد إلى معلمات طلب افتراضية أو تنظيف معلمات خاص بكل مزوّد | +| 20 | `createStreamFn` | استبدال مسار التدفق العادي بالكامل بنقل مخصص | عندما يحتاج المزوّد إلى بروتوكول wire مخصص، وليس مجرد غلاف | +| 21 | `wrapStreamFn` | غلاف التدفق بعد تطبيق الأغلفة العامة | عندما يحتاج المزوّد إلى أغلفة headers/body/model للتوافق دون نقل مخصص | +| 22 | `resolveTransportTurnState` | إرفاق رؤوس أو بيانات وصفية أصلية خاصة بكل دور من أدوار النقل | عندما يريد المزوّد من عمليات النقل العامة إرسال هوية الدور الأصلية الخاصة به | +| 23 | `resolveWebSocketSessionPolicy` | إرفاق رؤوس WebSocket أصلية أو سياسة تهدئة الجلسة | عندما يريد المزوّد من عمليات نقل WS العامة ضبط رؤوس الجلسة أو سياسة الاحتياط | +| 24 | `formatApiKey` | منسق ملف المصادقة: يصبح الملف المخزن سلسلة `apiKey` وقت التشغيل | عندما يخزن المزوّد بيانات مصادقة إضافية ويحتاج إلى شكل رمز تشغيل مخصص | +| 25 | `refreshOAuth` | تجاوز تحديث OAuth لنقاط تحديث مخصصة أو سياسة فشل التحديث | عندما لا يناسب المزوّد مجددات `pi-ai` المشتركة | +| 26 | `buildAuthDoctorHint` | تلميح إصلاح يُلحق عند فشل تحديث OAuth | عندما يحتاج المزوّد إلى إرشادات إصلاح مصادقة مملوكة له بعد فشل التحديث | +| 27 | `matchesContextOverflowError` | مطابقة تجاوز نافذة السياق المملوكة للمزوّد | عندما تكون لدى المزوّد أخطاء تجاوز أولية قد لا تلتقطها الاستدلالات العامة | +| 28 | `classifyFailoverReason` | تصنيف سبب الفشل الاحتياطي المملوك للمزوّد | عندما يستطيع المزوّد تعيين أخطاء API/النقل الأولية إلى rate-limit/overload/... إلخ | +| 29 | `isCacheTtlEligible` | سياسة ذاكرة الموجّه المؤقتة لمزوّدي proxy/backhaul | عندما يحتاج المزوّد إلى تقييد TTL خاص بالوكيل | +| 30 | `buildMissingAuthMessage` | بديل لرسالة استرداد المصادقة المفقودة العامة | عندما يحتاج المزوّد إلى تلميح استرداد خاص بالمصادقة المفقودة | +| 31 | `suppressBuiltInModel` | إخفاء النماذج المضمّنة القديمة مع تلميح اختياري ظاهر للمستخدم | عندما يحتاج المزوّد إلى إخفاء صفوف منبع قديمة أو استبدالها بتلميح خاص بالمورّد | +| 32 | `augmentModelCatalog` | صفوف كتالوج اصطناعية/نهائية تُضاف بعد الاكتشاف | عندما يحتاج المزوّد إلى صفوف توافق أمامي اصطناعية في `models list` وواجهات الاختيار | +| 33 | `isBinaryThinking` | تبديل تشغيل/إيقاف الاستدلال لمزوّدي التفكير الثنائي | عندما يوفّر المزوّد فقط تشغيل/إيقاف التفكير الثنائي | +| 34 | `supportsXHighThinking` | دعم استدلال `xhigh` لنماذج محددة | عندما يريد المزوّد `xhigh` فقط لمجموعة فرعية من النماذج | +| 35 | `resolveDefaultThinkingLevel` | مستوى `/think` الافتراضي لعائلة نموذج محددة | عندما يملك المزوّد سياسة `/think` الافتراضية لعائلة نموذج | +| 36 | `isModernModelRef` | مطابقة النموذج الحديث لمرشحات ملفات التعريف الحية واختيار smoke | عندما يملك المزوّد مطابقة النموذج المفضل في live/smoke | +| 37 | `prepareRuntimeAuth` | تبادل بيانات اعتماد مهيأة إلى الرمز/المفتاح الفعلي وقت التشغيل قبل الاستدلال مباشرة | عندما يحتاج المزوّد إلى تبادل رمز أو بيانات اعتماد طلب قصيرة العمر | +| 38 | `resolveUsageAuth` | حل بيانات اعتماد الاستخدام/الفوترة من أجل `/usage` والأسطح المشابهة للحالة | عندما يحتاج المزوّد إلى تحليل مخصص لرمز الاستخدام/الحصة أو إلى بيانات اعتماد استخدام مختلفة | +| 39 | `fetchUsageSnapshot` | جلب وتطبيع لقطات الاستخدام/الحصة الخاصة بالمزوّد بعد حل المصادقة | عندما يحتاج المزوّد إلى نقطة نهاية استخدام أو محلل حمولة خاص به | +| 40 | `createEmbeddingProvider` | بناء مهايئ embeddings مملوك للمزوّد من أجل الذاكرة/البحث | عندما ينتمي سلوك embedding للذاكرة إلى إضافة المزوّد | +| 41 | `buildReplayPolicy` | إرجاع سياسة replay تتحكم في معالجة النصوص للمزوّد | عندما يحتاج المزوّد إلى سياسة نصوص مخصصة (مثل إزالة كتل التفكير) | +| 42 | `sanitizeReplayHistory` | إعادة كتابة سجل replay بعد تنظيف النصوص العام | عندما يحتاج المزوّد إلى إعادة كتابة replay خاصة به بعد مساعدات الضغط المشتركة | +| 43 | `validateReplayTurns` | تحقق نهائي من أدوار replay أو إعادة تشكيلها قبل العداء المضمّن | عندما يحتاج نقل المزوّد إلى تحقق أدق من الأدوار بعد التنقية العامة | +| 44 | `onModelSelected` | تشغيل آثار جانبية مملوكة للمزوّد بعد الاختيار | عندما يحتاج المزوّد إلى telemetry أو حالة مملوكة له عندما يصبح النموذج نشطًا | -تتحقق `normalizeModelId` و`normalizeTransport` و`normalizeConfig` أولًا من -plugin الموفّر المطابق، ثم تنتقل إلى plugins الموفّر الأخرى القادرة على الخطافات -حتى تقوم إحداها فعلًا بتغيير معرّف النموذج أو النقل/الإعداد. وهذا يُبقي -الـ shims الخاصة بالأسماء البديلة/التوافقية تعمل بدون أن يضطر المستدعي إلى معرفة -أي plugin مضمّنة تمتلك إعادة الكتابة. وإذا لم يُعِد أي خطاف موفّر كتابة -إدخال إعداد مدعوم من عائلة Google، فإن مُطبّع إعداد Google المضمّن -لا يزال يطبّق هذا التنظيف التوافقي. +يفحص `normalizeModelId` و`normalizeTransport` و`normalizeConfig` أولًا +إضافة المزوّد المطابقة، ثم ينتقل إلى إضافات مزوّدين أخرى قادرة على الخطافات +حتى يغيّر أحدها فعليًا معرّف النموذج أو النقل/الإعدادات. وهذا يبقي +التحويلات البديلة/التوافقية للمزوّدين تعمل دون الحاجة إلى معرفة +المستدعي أي إضافة مضمّنة تملك إعادة الكتابة. وإذا لم تعِد أي خطافات مزوّد +كتابة إدخال إعدادات مدعوم من Google-family، فلا يزال مطبّع إعدادات Google +المضمّن يطبّق تنظيف التوافق ذاك. -إذا كان الموفر يحتاج إلى بروتوكول سلكي مخصص بالكامل أو منفّذ طلبات مخصص، -فهذه فئة مختلفة من الامتداد. وهذه الخطافات مخصصة لسلوك الموفر -الذي لا يزال يعمل ضمن حلقة الاستدلال العادية في OpenClaw. +إذا احتاج المزوّد إلى بروتوكول wire مخصص بالكامل أو منفذ طلبات مخصص بالكامل، +فهذه فئة مختلفة من الامتدادات. فهذه الخطافات مخصصة لسلوك المزوّد +الذي لا يزال يعمل على حلقة الاستدلال العادية في OpenClaw. -### مثال على موفر +### مثال المزوّد ```ts api.registerProvider({ @@ -776,120 +773,119 @@ api.registerProvider({ ### أمثلة مضمّنة -- تستخدم Anthropic الخطافات `resolveDynamicModel` و`capabilities` و`buildAuthDoctorHint`، - و`resolveUsageAuth`، و`fetchUsageSnapshot`، و`isCacheTtlEligible`، - و`resolveDefaultThinkingLevel`، و`applyConfigDefaults`، و`isModernModelRef`، - و`wrapStreamFn` لأنها تمتلك توافق Claude 4.6 المستقبلي، - وتلميحات عائلة الموفر، وإرشاد إصلاح المصادقة، وتكامل نقطة نهاية الاستخدام، - وأهلية prompt-cache، والقيم الافتراضية للإعداد المرتبطة بالمصادقة، وسياسة - التفكير الافتراضي/التكيفي لـ Claude، وتشكيل البث الخاص بـ Anthropic من أجل - headers التجريبية و`/fast` / `serviceTier` و`context1m`. -- تبقى مساعدات البث الخاصة بـ Claude في Anthropic حاليًا ضمن - الحد العام المملوك للـ plugin نفسها `api.ts` / `contract-api.ts`. - ويصدّر سطح الحزمة هذا `wrapAnthropicProviderStream`، و`resolveAnthropicBetas`، - و`resolveAnthropicFastMode`، و`resolveAnthropicServiceTier`، ومنشئي - المغلفات الأدنى مستوى لـ Anthropic بدلًا من توسيع SDK العامة حول قواعد - headers التجريبية لموفر واحد. -- تستخدم OpenAI الخطافات `resolveDynamicModel`، و`normalizeResolvedModel`، - و`capabilities` إضافة إلى `buildMissingAuthMessage`، و`suppressBuiltInModel`، - و`augmentModelCatalog`، و`supportsXHighThinking`، و`isModernModelRef` - لأنها تمتلك التوافق الأمامي لـ GPT-5.4، والتطبيع المباشر من - `openai-completions` إلى `openai-responses`، وتلميحات المصادقة الخاصة بـ Codex، - وإخفاء Spark، وصفوف قائمة OpenAI الصناعية، وسياسة التفكير / - النموذج المباشر لـ GPT-5؛ وتمتلك عائلة البث `openai-responses-defaults` المغلفات - الأصلية المشتركة لـ OpenAI Responses من أجل headers الإسناد، - و`/fast`/`serviceTier`، وإسهاب النص، وبحث الويب الأصلي لـ Codex، +- يستخدم Anthropic كلًا من `resolveDynamicModel` و`capabilities` و`buildAuthDoctorHint` و + `resolveUsageAuth` و`fetchUsageSnapshot` و`isCacheTtlEligible` و + `resolveDefaultThinkingLevel` و`applyConfigDefaults` و`isModernModelRef` و + `wrapStreamFn` لأنه يملك توافق Claude 4.6 الأمامي، + وتلميحات عائلة المزوّد، وإرشادات إصلاح المصادقة، وتكامل نقطة نهاية الاستخدام، + وأهلية ذاكرة الموجّه المؤقتة، والإعدادات الافتراضية الواعية بالمصادقة، + وسياسة التفكير الافتراضية/التكيفية لـ Claude، وتشكيل التدفق الخاص بـ Anthropic من أجل + رؤوس beta، و`/fast` / `serviceTier`، و`context1m`. +- تبقى مساعدات تدفق Anthropic الخاصة بـ Claude داخل وصلة + `api.ts` / `contract-api.ts` العامة الخاصة بالإضافة المضمّنة في الوقت الحالي. يصدّر هذا + سطح الحزمة `wrapAnthropicProviderStream` و`resolveAnthropicBetas` و + `resolveAnthropicFastMode` و`resolveAnthropicServiceTier` والبناة الأدنى + مستوى لأغلفة Anthropic بدلًا من توسيع SDK العام حول قواعد + رؤوس beta الخاصة بمزوّد واحد. +- يستخدم OpenAI `resolveDynamicModel` و`normalizeResolvedModel` و + `capabilities` بالإضافة إلى `buildMissingAuthMessage` و`suppressBuiltInModel` و + `augmentModelCatalog` و`supportsXHighThinking` و`isModernModelRef` + لأنه يملك التوافق الأمامي لـ GPT-5.4، والتطبيع المباشر من + `openai-completions` إلى `openai-responses`، وتلميحات المصادقة الواعية بـ Codex، + وإخفاء Spark، وصفوف قائمة OpenAI الاصطناعية، وسياسة التفكير / + النموذج الحي لـ GPT-5؛ وتملك عائلة التدفق `openai-responses-defaults` + أغلفة OpenAI Responses الأصلية المشتركة لرؤوس الإسناد، + و`/fast`/`serviceTier`، وإسهاب النص، وبحث Codex الأصلي على الويب، وتشكيل حمولة reasoning-compat، وإدارة سياق Responses. -- تستخدم OpenRouter `catalog` إضافة إلى `resolveDynamicModel` و - `prepareDynamicModel` لأن الموفر تمريري وقد يعرض معرّفات نماذج جديدة قبل - تحديث الفهرس الثابت في OpenClaw؛ كما تستخدم +- يستخدم OpenRouter `catalog` بالإضافة إلى `resolveDynamicModel` و + `prepareDynamicModel` لأن المزوّد تمريري وقد يكشف معرّفات + نماذج جديدة قبل تحديث كتالوج OpenClaw الثابت؛ كما يستخدم `capabilities` و`wrapStreamFn` و`isCacheTtlEligible` لإبقاء - headers الطلب والبيانات الوصفية للتوجيه وترقيعات reasoning - وسياسة prompt-cache الخاصة بالموفر خارج النواة. وتأتي سياسة replay الخاصة بها من - عائلة `passthrough-gemini`، بينما تمتلك عائلة البث `openrouter-thinking` - حقن reasoning الوكيل وتخطّي النماذج غير المدعومة / `auto`. -- تستخدم GitHub Copilot `catalog` و`auth` و`resolveDynamicModel` و - `capabilities` إضافة إلى `prepareRuntimeAuth` و`fetchUsageSnapshot` لأنها - تحتاج إلى تسجيل دخول الجهاز المملوك للموفر، وسلوك رجوع النماذج، - وخصائص نصوص Claude، وتبادل GitHub token إلى Copilot token، - ونقطة نهاية استخدام مملوكة للموفر. -- تستخدم OpenAI Codex `catalog`، و`resolveDynamicModel`، - و`normalizeResolvedModel`، و`refreshOAuth`، و`augmentModelCatalog` إضافة إلى - `prepareExtraParams`، و`resolveUsageAuth`، و`fetchUsageSnapshot` لأنها - لا تزال تعمل على وسائل نقل OpenAI الأساسية لكنها تمتلك تطبيع - النقل/base URL، وسياسة رجوع تحديث OAuth، وخيار النقل الافتراضي، - وصفوف فهرس Codex الصناعية، وتكامل نقطة نهاية استخدام ChatGPT؛ وهي - تشارك عائلة البث `openai-responses-defaults` نفسها مع OpenAI المباشر. -- تستخدم Google AI Studio وGemini CLI OAuth الخطافات `resolveDynamicModel`، - و`buildReplayPolicy`، و`sanitizeReplayHistory`، - و`resolveReasoningOutputMode`، و`wrapStreamFn`، و`isModernModelRef` لأن - عائلة replay `google-gemini` تمتلك الرجوع المستقبلي لـ Gemini 3.1، - والتحقق الأصلي من replay في Gemini، وتنقية bootstrap replay، - ووضع مخرجات reasoning المعلّم، ومطابقة النماذج الحديثة، بينما - تمتلك عائلة البث `google-thinking` تطبيع حمولة التفكير في Gemini؛ - كما تستخدم Gemini CLI OAuth الخطافات `formatApiKey`، و`resolveUsageAuth`، و - `fetchUsageSnapshot` لتنسيق الرموز، وتحليلها، وربط نقطة نهاية الحصة. -- تستخدم Anthropic Vertex `buildReplayPolicy` من خلال - عائلة replay `anthropic-by-model` بحيث يبقى تنظيف replay الخاص بـ Claude - محصورًا في معرّفات Claude بدلًا من جميع وسائل نقل `anthropic-messages`. -- تستخدم Amazon Bedrock الخطافات `buildReplayPolicy`، و`matchesContextOverflowError`، - و`classifyFailoverReason`، و`resolveDefaultThinkingLevel` لأنها تمتلك - تصنيف أخطاء Bedrock الخاصة بالاختناق/عدم الجاهزية/تجاوز السياق - لحركة Anthropic-on-Bedrock؛ بينما تشترك سياسة replay الخاصة بها في - الحارس نفسه الخاص بـ Claude فقط `anthropic-by-model`. -- تستخدم OpenRouter وKilocode وOpencode وOpencode Go الخطاف `buildReplayPolicy` - من خلال عائلة replay `passthrough-gemini` لأنها تمرر نماذج Gemini - عبر وسائل نقل متوافقة مع OpenAI وتحتاج إلى - تنقية thought-signature في Gemini بدون تحقق replay أصلي لـ Gemini أو - إعادة كتابة bootstrap. -- تستخدم MiniMax `buildReplayPolicy` من خلال - عائلة replay `hybrid-anthropic-openai` لأن موفرًا واحدًا يمتلك كلًا من - semantics الخاصة برسائل Anthropic وOpenAI-compatible؛ وهي تبقي - إسقاط thinking-block الخاص بـ Claude على جانب Anthropic فقط مع إعادة - تجاوز وضع مخرجات reasoning إلى الوضع الأصلي، وتمتلك عائلة البث `minimax-fast-mode` - إعادة كتابة نماذج الوضع السريع على مسار البث المشترك. -- تستخدم Moonshot `catalog` إضافة إلى `wrapStreamFn` لأنها لا تزال تستخدم - نقل OpenAI المشترك لكنها تحتاج إلى تطبيع حمولة التفكير المملوك للموفر؛ وتمتلك - عائلة البث `moonshot-thinking` ربط config إضافة إلى حالة `/think` بحمولة - التفكير الثنائية الأصلية الخاصة بها. -- تستخدم Kilocode `catalog` و`capabilities` و`wrapStreamFn` و - `isCacheTtlEligible` لأنها تحتاج إلى headers طلب مملوكة للموفر، - وتطبيع حمولة reasoning، وتلميحات نصوص Gemini، وبوابة Anthropic - الخاصة بـ cache-TTL؛ وتُبقي عائلة البث `kilocode-thinking` حقن - Kilo thinking على مسار البث الوكيل المشترك مع تخطي `kilo/auto` وغيرها من - معرّفات نماذج الوكيل التي لا تدعم حمولات reasoning الصريحة. -- تستخدم Z.AI الخطافات `resolveDynamicModel`، و`prepareExtraParams`، و`wrapStreamFn`، - و`isCacheTtlEligible`، و`isBinaryThinking`، و`isModernModelRef`، - و`resolveUsageAuth`، و`fetchUsageSnapshot` لأنها تمتلك رجوع GLM-5، - والقيم الافتراضية لـ `tool_stream`، وتجربة التفكير الثنائية، ومطابقة - النماذج الحديثة، وكلًا من مصادقة الاستخدام وجلب الحصة؛ وتُبقي عائلة البث - `tool-stream-default-on` مغلف `tool_stream` الافتراضي المفعل خارج - الربط اليدوي لكل موفر. -- تستخدم xAI `normalizeResolvedModel`، و`normalizeTransport`، - و`contributeResolvedModelCompat`، و`prepareExtraParams`، و`wrapStreamFn`، - و`resolveSyntheticAuth`، و`resolveDynamicModel`، و`isModernModelRef` - لأنها تمتلك تطبيع النقل الأصلي لـ xAI Responses، وإعادة كتابة - الأسماء البديلة لـ Grok في الوضع السريع، والقيمة الافتراضية `tool_stream`، وتنظيف - strict-tool / reasoning-payload، وإعادة استخدام المصادقة الاحتياطية لأدوات - مملوكة للـ plugin، وحل نماذج Grok المتوافق مستقبلًا، وترقيعات توافق - مملوكة للموفر مثل ملف schema الأدوات الخاص بـ xAI، والكلمات المفتاحية غير - المدعومة في schema، و`web_search` الأصلي، وفك ترميز - معاملات استدعاء الأداة المشفرة بكيانات HTML. -- تستخدم Mistral وOpenCode Zen وOpenCode Go `capabilities` فقط لإبقاء - خصائص النصوص/الأدوات خارج النواة. -- يستخدم موفرو الحزم المضمّنون المعتمدون على `catalog` فقط مثل `byteplus`، - و`cloudflare-ai-gateway`، و`huggingface`، و`kimi-coding`، و`nvidia`، و`qianfan`, - و`synthetic`، و`together`، و`venice`، و`vercel-ai-gateway`، و`volcengine` + رؤوس الطلب الخاصة بالمزوّد، وبيانات التوجيه، وترقيعات الاستدلال، + وسياسة ذاكرة الموجّه المؤقتة خارج النواة. وتأتي سياسة replay الخاصة به من + عائلة `passthrough-gemini`، بينما تملك عائلة التدفق `openrouter-thinking` + حقن الاستدلال عبر الوكيل وتخطي النماذج غير المدعومة و`auto`. +- يستخدم GitHub Copilot `catalog` و`auth` و`resolveDynamicModel` و + `capabilities` بالإضافة إلى `prepareRuntimeAuth` و`fetchUsageSnapshot` لأنه + يحتاج إلى تسجيل دخول الجهاز المملوك للمزوّد، وسلوك احتياط النموذج، وخصائص + نصوص Claude، وتبادل رمز GitHub إلى رمز Copilot، ونقطة نهاية + استخدام مملوكة للمزوّد. +- يستخدم OpenAI Codex `catalog` و`resolveDynamicModel` و + `normalizeResolvedModel` و`refreshOAuth` و`augmentModelCatalog` بالإضافة إلى + `prepareExtraParams` و`resolveUsageAuth` و`fetchUsageSnapshot` لأنه + لا يزال يعمل على عمليات نقل OpenAI الأساسية لكنه يملك تطبيع + النقل/base URL، وسياسة احتياط تحديث OAuth، وخيار النقل الافتراضي، + وصفوف كتالوج Codex الاصطناعية، وتكامل نقطة نهاية استخدام ChatGPT؛ وهو + يشارك عائلة التدفق `openai-responses-defaults` نفسها مع OpenAI المباشر. +- يستخدم Google AI Studio وGemini CLI OAuth كلًا من `resolveDynamicModel` و + `buildReplayPolicy` و`sanitizeReplayHistory` و + `resolveReasoningOutputMode` و`wrapStreamFn` و`isModernModelRef` لأن + عائلة replay `google-gemini` تملك احتياط التوافق الأمامي لـ Gemini 3.1، + والتحقق الأصلي من replay في Gemini، وتنقية replay التمهيدية، ووضع + reasoning-output الموسوم، ومطابقة النموذج الحديث، بينما + تملك عائلة التدفق `google-thinking` تطبيع حمولة تفكير Gemini؛ كما يستخدم + Gemini CLI OAuth أيضًا `formatApiKey` و`resolveUsageAuth` و + `fetchUsageSnapshot` لتنسيق الرمز، وتحليل الرمز، وربط نقطة نهاية الحصة. +- يستخدم Anthropic Vertex `buildReplayPolicy` عبر + عائلة replay `anthropic-by-model` حتى يبقى تنظيف replay الخاص بـ Claude + مقصورًا على معرّفات Claude بدلًا من كل نقل `anthropic-messages`. +- يستخدم Amazon Bedrock `buildReplayPolicy` و`matchesContextOverflowError` و + `classifyFailoverReason` و`resolveDefaultThinkingLevel` لأنه يملك + تصنيف أخطاء Bedrock الخاصة بالخنق/عدم الجاهزية/تجاوز السياق + لحركة Anthropic-on-Bedrock؛ بينما لا تزال سياسة replay الخاصة به تشترك في + حاجز `anthropic-by-model` الخاص بـ Claude فقط. +- يستخدم OpenRouter وKilocode وOpencode وOpencode Go `buildReplayPolicy` + عبر عائلة replay `passthrough-gemini` لأنها توكّل نماذج Gemini + عبر عمليات نقل متوافقة مع OpenAI وتحتاج إلى تنقية توقيع التفكير الخاص بـ Gemini + دون التحقق الأصلي من replay في Gemini أو + إعادة كتابة التمهيد. +- يستخدم MiniMax `buildReplayPolicy` عبر + عائلة replay `hybrid-anthropic-openai` لأن مزوّدًا واحدًا يملك دلالات + Anthropic-message وOpenAI-compatible معًا؛ فهو يبقي إسقاط + كتل التفكير الخاصة بـ Claude على جانب Anthropic بينما يعيد وضع + إخراج الاستدلال إلى الوضع الأصلي، وتملك عائلة التدفق `minimax-fast-mode` + إعادة كتابة نماذج الوضع السريع على مسار التدفق المشترك. +- يستخدم Moonshot `catalog` بالإضافة إلى `wrapStreamFn` لأنه لا يزال يستخدم + نقل OpenAI المشترك لكنه يحتاج إلى تطبيع حمولة التفكير المملوكة للمزوّد؛ وتقوم عائلة + التدفق `moonshot-thinking` بتعيين الإعدادات بالإضافة إلى حالة `/think` + على حمولة التفكير الثنائي الأصلية الخاصة به. +- يستخدم Kilocode `catalog` و`capabilities` و`wrapStreamFn` و + `isCacheTtlEligible` لأنه يحتاج إلى رؤوس طلبات مملوكة للمزوّد، + وتطبيع حمولة الاستدلال، وتلميحات نصوص Gemini، وتقييد TTL لذاكرة Anthropic + المؤقتة؛ وتحافظ عائلة التدفق `kilocode-thinking` على حقن تفكير Kilo + في مسار التدفق الوكيل المشترك مع تخطي `kilo/auto` ومعرّفات + النماذج الوكيلة الأخرى التي لا تدعم حمولة استدلال صريحة. +- يستخدم Z.AI `resolveDynamicModel` و`prepareExtraParams` و`wrapStreamFn` و + `isCacheTtlEligible` و`isBinaryThinking` و`isModernModelRef` و + `resolveUsageAuth` و`fetchUsageSnapshot` لأنه يملك احتياط GLM-5، + والإعدادات الافتراضية لـ `tool_stream`، وتجربة التفكير الثنائي، + ومطابقة النموذج الحديث، وكلًا من مصادقة الاستخدام وجلب الحصة؛ وتحافظ + عائلة التدفق `tool-stream-default-on` على غلاف `tool_stream` الافتراضي خارج + الغراء المكتوب يدويًا لكل مزوّد. +- يستخدم xAI `normalizeResolvedModel` و`normalizeTransport` و + `contributeResolvedModelCompat` و`prepareExtraParams` و`wrapStreamFn` و + `resolveSyntheticAuth` و`resolveDynamicModel` و`isModernModelRef` + لأنه يملك تطبيع نقل xAI Responses الأصلي، وإعادة كتابة الأسماء البديلة + لوضع Grok السريع، و`tool_stream` الافتراضي، وتنظيف strict-tool / + reasoning-payload، وإعادة استخدام مصادقة الاحتياط لأدوات مملوكة للإضافة، + وحل نماذج Grok بالتوافق الأمامي، ورقع التوافق المملوكة للمزوّد مثل + ملف مخطط أدوات xAI، والكلمات المفتاحية غير المدعومة في المخطط، و`web_search` + الأصلي، وفك ترميز وسائط استدعاء الأدوات المشفرة بكيانات HTML. +- يستخدم Mistral وOpenCode Zen وOpenCode Go `capabilities` فقط من أجل + إبقاء خصائص النصوص/الأدوات خارج النواة. +- يستخدم مزوّدو الحزم المضمّنة المعتمدون على الكتالوج فقط، مثل `byteplus` و`cloudflare-ai-gateway` و + `huggingface` و`kimi-coding` و`nvidia` و`qianfan` و + `synthetic` و`together` و`venice` و`vercel-ai-gateway` و`volcengine`، الخطاف `catalog` فقط. -- تستخدم Qwen `catalog` لموفر النص لديها إضافة إلى تسجيلات - فهم الوسائط وتوليد الفيديو المشتركة لأسطحها متعددة الوسائط. -- تستخدم MiniMax وXiaomi `catalog` إضافة إلى خطافات الاستخدام لأن - سلوك `/usage` لديهما مملوك للـ plugin رغم أن الاستدلال لا يزال يعمل عبر - وسائل النقل المشتركة. +- يستخدم Qwen `catalog` لمزوّد النص الخاص به بالإضافة إلى تسجيلات + فهم الوسائط وتوليد الفيديو المشتركة لأسطحه متعددة الوسائط. +- يستخدم MiniMax وXiaomi `catalog` بالإضافة إلى خطافات الاستخدام لأن سلوك + `/usage` الخاص بهما مملوك للإضافة مع أن الاستدلال لا يزال يجري عبر + عمليات النقل المشتركة. ## مساعدات وقت التشغيل -يمكن للـ plugins الوصول إلى مساعدات أساسية مختارة عبر `api.runtime`. وبالنسبة إلى TTS: +يمكن للإضافات الوصول إلى مساعدات مختارة من النواة عبر `api.runtime`. بالنسبة إلى TTS: ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -910,15 +906,14 @@ const voices = await api.runtime.tts.listVoices({ ملاحظات: -- يعيد `textToSpeech` حمولة خرج TTS العادية من النواة لأسطح - الملفات/المذكرات الصوتية. -- يستخدم إعداد النواة `messages.tts` واختيار الموفر. -- يعيد PCM audio buffer + sample rate. ويجب على plugins إعادة التعيين/الترميز من أجل الموفّرين. -- `listVoices` اختيارية لكل موفر. استخدمها لمنتقيات الأصوات المملوكة للمورّد أو لتدفقات الإعداد. -- يمكن أن تتضمن قوائم الأصوات بيانات وصفية أغنى مثل locale والجنس وعلامات الشخصية لمنتقيات واعية بالموفر. -- يدعم OpenAI وElevenLabs الاتصالات الهاتفية اليوم. ولا يدعمها Microsoft. +- يعيد `textToSpeech` حمولة إخراج TTS العادية في النواة لأسطح الملفات/الملاحظات الصوتية. +- يستخدم إعدادات `messages.tts` في النواة واختيار المزوّد. +- يعيد مخزن PCM للصوت + معدل العينة. يجب على الإضافات إعادة أخذ العينات/الترميز للمزوّدات. +- `listVoices` اختيارية لكل مزوّد. استخدمها لمنتقيات الأصوات أو تدفقات الإعداد المملوكة للمورّد. +- يمكن أن تتضمن قوائم الأصوات بيانات وصفية أغنى مثل اللغة والمنطقة، والنوع، ووسوم الشخصية لمنتقيات واعية بالمزوّد. +- يدعم OpenAI وElevenLabs الهاتفية اليوم. ولا يدعمها Microsoft. -يمكن للـ plugins أيضًا تسجيل موفري الكلام عبر `api.registerSpeechProvider(...)`. +يمكن للإضافات أيضًا تسجيل مزوّدي الكلام عبر `api.registerSpeechProvider(...)`. ```ts api.registerSpeechProvider({ @@ -938,14 +933,15 @@ api.registerSpeechProvider({ ملاحظات: -- أبقِ سياسة TTS والرجوع الاحتياطي وتسليم الرد داخل النواة. -- استخدم موفري الكلام لسلوك التوليف المملوك للمورّد. -- يُطبَّع إدخال Microsoft القديم `edge` إلى معرّف الموفر `microsoft`. -- نموذج الملكية المفضل موجه للشركة: يمكن لplugin مورّد واحدة أن تمتلك - موفري النص والكلام والصور والوسائط المستقبلية مع إضافة OpenClaw لعقود هذه الإمكانات. +- أبقِ سياسة TTS، والاحتياط، وتسليم الرد في النواة. +- استخدم مزوّدي الكلام لسلوك التوليف المملوك للمورّد. +- تُطبَّع قيمة الإدخال القديمة `edge` الخاصة بـ Microsoft إلى معرّف المزوّد `microsoft`. +- نموذج الملكية المفضل هو الموجّه للشركة: يمكن لإضافة مورّد واحدة أن تملك + النص والكلام والصورة ومزوّدي الوسائط المستقبليين مع إضافة OpenClaw لعقود + تلك القدرات. -وبالنسبة إلى فهم الصور/الصوت/الفيديو، تسجل plugins موفر -فهم وسائط واحدًا مكتوبًا بدل حاوية key/value عامة: +بالنسبة إلى فهم الصور/الصوت/الفيديو، تسجل الإضافات مزوّد +فهم وسائط واحدًا مكتوب الأنواع بدلًا من كيس مفتاح/قيمة عام: ```ts api.registerMediaUnderstandingProvider({ @@ -959,16 +955,16 @@ api.registerMediaUnderstandingProvider({ ملاحظات: -- أبقِ التنسيق والرجوع الاحتياطي والإعداد وربط القنوات في النواة. -- وأبقِ سلوك المورّد في plugin الموفر. -- يجب أن يبقى التوسع الإضافي مكتوبًا: طرق اختيارية جديدة، وحقول نتائج - اختيارية جديدة، وإمكانات اختيارية جديدة. -- كما أن توليد الفيديو يتبع النمط نفسه بالفعل: - - تمتلك النواة عقد القدرة ومساعد وقت التشغيل - - وتسجل plugins الخاصة بالمورّدين `api.registerVideoGenerationProvider(...)` - - وتستهلك plugins الميزات/القنوات `api.runtime.videoGeneration.*` +- أبقِ التنسيق، والاحتياط، والإعدادات، وربط القنوات في النواة. +- أبقِ سلوك المورّد في إضافة المزوّد. +- يجب أن يبقى التوسع الإضافي مكتوب الأنواع: أساليب اختيارية جديدة، وحقول + نتائج اختيارية جديدة، وقدرات اختيارية جديدة. +- يتبع توليد الفيديو بالفعل النمط نفسه: + - تملك النواة عقد القدرة ومساعد وقت التشغيل + - تسجل إضافات المورّدين `api.registerVideoGenerationProvider(...)` + - تستهلك إضافات الميزة/القناة `api.runtime.videoGeneration.*` -وبالنسبة إلى مساعدات وقت تشغيل فهم الوسائط، يمكن للـ plugins استدعاء: +بالنسبة إلى مساعدات وقت التشغيل لفهم الوسائط، يمكن للإضافات استدعاء: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -983,8 +979,8 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -أما بالنسبة إلى نسخ الصوت، فيمكن للـ plugins استخدام وقت تشغيل فهم الوسائط -أو الاسم القديم STT: +وبالنسبة إلى نسخ الصوت، يمكن للإضافات استخدام وقت تشغيل فهم الوسائط أو +الاسم البديل الأقدم STT: ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ @@ -997,13 +993,13 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ ملاحظات: -- يُعد `api.runtime.mediaUnderstanding.*` السطح المشترك المفضل لـ +- يمثل `api.runtime.mediaUnderstanding.*` السطح المشترك المفضل لـ فهم الصور/الصوت/الفيديو. -- يستخدم إعداد النواة الخاص بالصوت في فهم الوسائط (`tools.media.audio`) وترتيب الرجوع الاحتياطي للموفر. -- يعيد `{ text: undefined }` عند عدم إنتاج خرج نسخ (مثلًا عند تخطي الإدخال/عدم دعمه). +- يستخدم إعدادات الصوت الخاصة بفهم الوسائط في النواة (`tools.media.audio`) وترتيب احتياط المزوّد. +- يعيد `{ text: undefined }` عندما لا يتم إنتاج إخراج نسخ (على سبيل المثال إدخال متخطى/غير مدعوم). - يبقى `api.runtime.stt.transcribeAudioFile(...)` اسمًا بديلًا للتوافق. -يمكن للـ plugins أيضًا إطلاق تشغيلات subagent في الخلفية عبر `api.runtime.subagent`: +يمكن للإضافات أيضًا إطلاق عمليات subagent في الخلفية عبر `api.runtime.subagent`: ```ts const result = await api.runtime.subagent.run({ @@ -1017,13 +1013,15 @@ const result = await api.runtime.subagent.run({ ملاحظات: -- الحقلان `provider` و`model` تجاوزات اختيارية لكل تشغيل، وليسا تغييرات دائمة للجلسة. -- لا يحترم OpenClaw حقلي التجاوز هذين إلا للمستدعين الموثوقين. -- بالنسبة إلى التشغيلات الاحتياطية المملوكة للـ plugin، يجب على المشغلين تفعيل ذلك صراحة عبر `plugins.entries..subagent.allowModelOverride: true`. -- استخدم `plugins.entries..subagent.allowedModels` لتقييد plugins الموثوقة إلى أهداف قانونية محددة من `provider/model`، أو `"*"` للسماح الصريح بأي هدف. -- لا تزال تشغيلات subagent الخاصة بالـ plugins غير الموثوقة تعمل، لكن طلبات التجاوز تُرفض بدلًا من الرجوع بصمت. +- إن `provider` و`model` تجاوزات اختيارية لكل تشغيل، وليسا تغييرات دائمة للجلسة. +- لا يحترم OpenClaw حقول التجاوز هذه إلا للجهات الموثوقة. +- بالنسبة إلى عمليات الاحتياط المملوكة للإضافة، يجب على المشغلين تفعيل + `plugins.entries..subagent.allowModelOverride: true`. +- استخدم `plugins.entries..subagent.allowedModels` لتقييد الإضافات الموثوقة + بأهداف `provider/model` قانونية محددة، أو `"*"` للسماح صراحة بأي هدف. +- لا تزال تشغيلات subagent الخاصة بالإضافات غير الموثوقة تعمل، لكن تُرفض طلبات التجاوز بدلًا من الاحتياط الصامت. -أما بالنسبة إلى بحث الويب، فيمكن للـ plugins استهلاك مساعد وقت التشغيل المشترك بدلًا من +بالنسبة إلى البحث على الويب، يمكن للإضافات استهلاك مساعد وقت التشغيل المشترك بدلًا من الوصول إلى ربط أداة الوكيل: ```ts @@ -1040,14 +1038,14 @@ const result = await api.runtime.webSearch.search({ }); ``` -ويمكن للـ plugins أيضًا تسجيل موفري بحث الويب عبر +يمكن للإضافات أيضًا تسجيل مزوّدي البحث على الويب عبر `api.registerWebSearchProvider(...)`. ملاحظات: -- أبقِ اختيار الموفر، وحل بيانات الاعتماد، ودلالات الطلب المشتركة في النواة. -- استخدم موفري بحث الويب لوسائل النقل الخاصة بالمورّد. -- يُعد `api.runtime.webSearch.*` السطح المشترك المفضل لplugins الميزات/القنوات التي تحتاج إلى سلوك البحث دون الاعتماد على مغلف أداة الوكيل. +- أبقِ اختيار المزوّد، وحل بيانات الاعتماد، ودلالات الطلب المشتركة في النواة. +- استخدم مزوّدي البحث على الويب لعمليات النقل الخاصة بالمورّد. +- يمثل `api.runtime.webSearch.*` السطح المشترك المفضل لإضافات الميزات/القنوات التي تحتاج إلى سلوك بحث من دون الاعتماد على غلاف أداة الوكيل. ### `api.runtime.imageGeneration` @@ -1062,12 +1060,12 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)`: يولد صورة باستخدام سلسلة موفري توليد الصور المضبوطة. -- `listProviders(...)`: يسرد موفري توليد الصور المتاحين وإمكاناتهم. +- `generate(...)`: أنشئ صورة باستخدام سلسلة مزوّدات توليد الصور المهيأة. +- `listProviders(...)`: أعرض مزوّدي توليد الصور المتاحين وقدراتهم. ## مسارات Gateway HTTP -يمكن للـ plugins كشف نقاط نهاية HTTP بواسطة `api.registerHttpRoute(...)`. +يمكن للإضافات كشف نقاط نهاية HTTP باستخدام `api.registerHttpRoute(...)`. ```ts api.registerHttpRoute({ @@ -1084,262 +1082,271 @@ api.registerHttpRoute({ حقول المسار: -- `path`: مسار route ضمن خادم HTTP الخاص بـ gateway. -- `auth`: مطلوب. استخدم `"gateway"` لطلب مصادقة gateway العادية، أو `"plugin"` للمصادقة/التحقق من webhook المُدار بواسطة plugin. -- `match`: اختياري. إما `"exact"` (الافتراضي) أو `"prefix"`. -- `replaceExisting`: اختياري. يسمح للـ plugin نفسها باستبدال تسجيل مسارها الحالي. -- `handler`: أعد `true` عندما يكون المسار قد عالج الطلب. +- `path`: مسار التوجيه تحت خادم HTTP الخاص بـ Gateway. +- `auth`: مطلوب. استخدم `"gateway"` لطلب مصادقة Gateway العادية، أو `"plugin"` لمصادقة/تحقق webhook المُدار بواسطة الإضافة. +- `match`: اختياري. `"exact"` (الافتراضي) أو `"prefix"`. +- `replaceExisting`: اختياري. يسمح للإضافة نفسها باستبدال تسجيل مسارها الحالي. +- `handler`: أعد `true` عندما يتولى المسار معالجة الطلب. ملاحظات: -- تمت إزالة `api.registerHttpHandler(...)` وستسبب خطأ في تحميل plugin. استخدم `api.registerHttpRoute(...)` بدلًا منها. -- يجب على مسارات plugins التصريح بـ `auth` صراحة. -- تُرفض تعارضات `path + match` المطابقة تمامًا ما لم تكن `replaceExisting: true`، ولا يمكن لplugin أن تستبدل مسار plugin أخرى. -- تُرفض المسارات المتداخلة ذات مستويات `auth` المختلفة. أبقِ سلاسل السقوط `exact`/`prefix` ضمن مستوى المصادقة نفسه فقط. -- لا تتلقى المسارات ذات `auth: "plugin"` نطاقات وقت تشغيل operator تلقائيًا. فهي مخصصة لـ webhooks/التحقق من التوقيع الذي تديره plugin، لا لاستدعاءات مساعد Gateway ذات الامتيازات. -- تعمل المسارات ذات `auth: "gateway"` داخل نطاق وقت تشغيل لطلب Gateway، لكن هذا النطاق محافظ عمدًا: - - مصادقة bearer بالسر المشترك (`gateway.auth.mode = "token"` / `"password"`) تُبقي نطاقات وقت تشغيل مسار plugin مثبتة على `operator.write`، حتى لو أرسل المستدعي `x-openclaw-scopes` - - أوضاع HTTP الموثوقة الحاملة للهوية (مثل `trusted-proxy` أو `gateway.auth.mode = "none"` على ingress خاص) لا تحترم `x-openclaw-scopes` إلا عند وجود هذا header صراحة - - إذا غاب `x-openclaw-scopes` في طلبات مسار plugin الحاملة للهوية، يعود نطاق وقت التشغيل إلى `operator.write` -- القاعدة العملية: لا تفترض أن مسار plugin المصادق عبر gateway هو سطح إدارة ضمني. إذا كان مسارك يحتاج إلى سلوك إداري فقط، فاطلب وضع مصادقة حاملًا للهوية ووثّق عقد header الصريح `x-openclaw-scopes`. +- تمت إزالة `api.registerHttpHandler(...)` وسيؤدي إلى خطأ تحميل إضافة. استخدم `api.registerHttpRoute(...)` بدلًا منه. +- يجب أن تعلن مسارات الإضافة `auth` صراحة. +- تُرفض تعارضات `path + match` الدقيقة ما لم يكن `replaceExisting: true`، ولا يمكن لإضافة أن تستبدل مسار إضافة أخرى. +- تُرفض المسارات المتداخلة ذات مستويات `auth` المختلفة. أبقِ سلاسل السقوط `exact`/`prefix` على مستوى المصادقة نفسه فقط. +- لا تتلقى مسارات `auth: "plugin"` **نطاقات وقت تشغيل المشغّل** تلقائيًا. فهي مخصصة لـ webhooks/التحقق من التوقيع المُدار بواسطة الإضافة، وليس لاستدعاءات مساعدة Gateway ذات الامتيازات. +- تعمل مسارات `auth: "gateway"` داخل نطاق وقت تشغيل طلب Gateway، لكن هذا النطاق محافظ عمدًا: + - تبقي مصادقة bearer بالمفتاح المشترك (`gateway.auth.mode = "token"` / `"password"`) نطاقات وقت تشغيل مسارات الإضافة مثبّتة عند `operator.write`، حتى إذا أرسل المستدعي `x-openclaw-scopes` + - تحترم أوضاع HTTP الموثوقة الحاملة للهوية (مثل `trusted-proxy` أو `gateway.auth.mode = "none"` على مدخل خاص) قيمة `x-openclaw-scopes` فقط عندما يكون الرأس موجودًا صراحة + - إذا غاب `x-openclaw-scopes` في طلبات مسارات الإضافة الحاملة للهوية تلك، يعود نطاق وقت التشغيل إلى `operator.write` +- القاعدة العملية: لا تفترض أن مسار إضافة موثّق عبر gateway هو سطح إدارة ضمني. إذا كان مسارك يحتاج إلى سلوك خاص بالمشرف فقط، فاطلب وضع مصادقة حاملًا للهوية ووثّق عقد الرأس `x-openclaw-scopes` الصريح. ## مسارات استيراد Plugin SDK -استخدم المسارات الفرعية لـ SDK بدل استيراد `openclaw/plugin-sdk` الأحادي عند -تأليف plugins: +استخدم المسارات الفرعية لـ SDK بدلًا من استيراد `openclaw/plugin-sdk` +الأحادي عند تأليف الإضافات: -- `openclaw/plugin-sdk/plugin-entry` من أجل عناصر تسجيل plugin الأساسية. -- `openclaw/plugin-sdk/core` من أجل العقد المشترك العام المواجه للـ plugin. -- `openclaw/plugin-sdk/config-schema` من أجل - تصدير Zod schema الجذرية لـ `openclaw.json` (`OpenClawSchema`). -- العناصر الثابتة الخاصة بالقنوات مثل `openclaw/plugin-sdk/channel-setup`، - و`openclaw/plugin-sdk/setup-runtime`، - و`openclaw/plugin-sdk/setup-adapter-runtime`، - و`openclaw/plugin-sdk/setup-tools`، - و`openclaw/plugin-sdk/channel-pairing`، - و`openclaw/plugin-sdk/channel-contract`، - و`openclaw/plugin-sdk/channel-feedback`، - و`openclaw/plugin-sdk/channel-inbound`، - و`openclaw/plugin-sdk/channel-lifecycle`، - و`openclaw/plugin-sdk/channel-reply-pipeline`، - و`openclaw/plugin-sdk/command-auth`، - و`openclaw/plugin-sdk/secret-input`، و - `openclaw/plugin-sdk/webhook-ingress` من أجل ربط - الإعداد/المصادقة/الرد/webhook المشترك. ويُعد `channel-inbound` الموطن المشترك لإلغاء - الارتداد، ومطابقة الإشارة، ومساعدات سياسة الإشارة الواردة، وتنسيق المغلف، - ومساعدات سياق المغلف الوارد. - ويُعد `channel-setup` حد الإعداد الاختياري الضيق. - ويُعد `setup-runtime` سطح إعداد آمنًا لوقت التشغيل يُستخدم بواسطة `setupEntry` / - بدء التشغيل المؤجل، بما في ذلك محولات ترقيع الإعداد الآمنة عند الاستيراد. - ويُعد `setup-adapter-runtime` حد محول إعداد الحساب الواعي بالـ env. - ويُعد `setup-tools` حدًا صغيرًا لمساعدات CLI/archive/docs (`formatCliCommand`, - و`detectBinary`، و`extractArchive`، و`resolveBrewExecutable`، و`formatDocsLink`, - و`CONFIG_DIR`). -- المسارات الخاصة بالمجال مثل `openclaw/plugin-sdk/channel-config-helpers`، - و`openclaw/plugin-sdk/allow-from`، - و`openclaw/plugin-sdk/channel-config-schema`, - و`openclaw/plugin-sdk/telegram-command-config`, - و`openclaw/plugin-sdk/channel-policy`, - و`openclaw/plugin-sdk/approval-runtime`, - و`openclaw/plugin-sdk/config-runtime`, - و`openclaw/plugin-sdk/infra-runtime`, - و`openclaw/plugin-sdk/agent-runtime`, - و`openclaw/plugin-sdk/lazy-runtime`, - و`openclaw/plugin-sdk/reply-history`, - و`openclaw/plugin-sdk/routing`, - و`openclaw/plugin-sdk/status-helpers`, - و`openclaw/plugin-sdk/text-runtime`, - و`openclaw/plugin-sdk/runtime-store`، و - `openclaw/plugin-sdk/directory-runtime` من أجل مساعدات وقت التشغيل/الإعداد المشتركة. - ويُعد `telegram-command-config` الحد العام الضيق لتطبيع/التحقق من - الأوامر المخصصة في Telegram ويبقى متاحًا حتى إذا كان سطح عقد Telegram المضمّن - غير متاح مؤقتًا. - ويُعد `text-runtime` الحد المشترك للنص/markdown/التسجيل، بما في ذلك - إزالة النصوص المرئية للمساعد، ومساعدات عرض/chunking في markdown، ومساعدات الإخفاء، - ومساعدات directive-tag، وأدوات النص الآمن. -- يجب أن تفضّل حدود القنوات الخاصة بالموافقة عقد `approvalCapability` - واحدًا على plugin. ثم تقرأ النواة مصادقة الموافقة وتسليمها وعرضها وتوجيهها - الأصلي عبر هذه القدرة الواحدة بدل خلط سلوك الموافقة في حقول plugin غير ذات الصلة. -- إن `openclaw/plugin-sdk/channel-runtime` مهمل ويظل فقط كشريحة توافق - للـ plugins الأقدم. ويجب على الشيفرة الجديدة استيراد العناصر العامة الأضيق بدلًا منه، - ويجب على شيفرة المستودع ألا تضيف استيرادات جديدة من هذه الشريحة. -- تبقى أساسيات الامتدادات المضمّنة خاصة. ويجب على plugins الخارجية استخدام - المسارات الفرعية `openclaw/plugin-sdk/*` فقط. ويمكن لشيفرة/اختبارات النواة في OpenClaw استخدام - نقاط الدخول العامة في المستودع تحت جذر حزمة plugin مثل `index.js`، و`api.js`، - و`runtime-api.js`، و`setup-entry.js`، وملفات ضيقة النطاق مثل - `login-qr-api.js`. لا تستورد أبدًا `src/*` التابعة لحزمة plugin من النواة أو من امتداد آخر. -- تقسيم نقطة الدخول في المستودع: - `/api.js` هو شريط المساعدات/الأنواع، - و`/runtime-api.js` هو شريط وقت التشغيل فقط، - و`/index.js` هو مدخل plugin المضمّنة، - و`/setup-entry.js` هو مدخل plugin الخاص بالإعداد. -- أمثلة الموفّرين المضمّنة الحالية: - - تستخدم Anthropic `api.js` / `contract-api.js` لمساعدات بث Claude مثل - `wrapAnthropicProviderStream`، ومساعدات beta-header، وتحليل `service_tier`. - - تستخدم OpenAI `api.js` لبناة الموفر، ومساعدات النموذج الافتراضي، وبناة - الموفّر الفوري. - - تستخدم OpenRouter `api.js` لباني الموفر الخاص بها إضافة إلى مساعدات - onboarding/config، في حين لا يزال بإمكان `register.runtime.js` - إعادة تصدير المساعدات العامة `plugin-sdk/provider-stream` للاستخدام المحلي في المستودع. -- تفضّل نقاط الدخول العامة المحمّلة عبر facade لقطة إعداد وقت التشغيل النشطة - عند وجودها، ثم تعود إلى ملف الإعداد المحلول على القرص عندما - لا يكون OpenClaw قد بدأ بعد في تقديم لقطة وقت تشغيل. -- تبقى العناصر العامة المشتركة هي عقد SDK العامة المفضلة. ولا تزال توجد - مجموعة توافقية صغيرة ومحجوزة من حدود المساعدات ذات العلامات التجارية للقنوات المضمّنة. - تعامل مع هذه على أنها حدود للصيانة/التوافق للـ plugins المضمّنة، لا كأهداف استيراد - جديدة للجهات الخارجية؛ ويجب أن تهبط العقود المشتركة الجديدة بين القنوات - على مسارات `plugin-sdk/*` العامة أو على الأشرطة المحلية `api.js` / - `runtime-api.js` الخاصة بالـ plugin. +- `openclaw/plugin-sdk/plugin-entry` من أجل بدائيات تسجيل الإضافات. +- `openclaw/plugin-sdk/core` من أجل العقد العام المشترك المواجه للإضافات. +- `openclaw/plugin-sdk/config-schema` من أجل تصدير مخطط Zod الجذري لـ `openclaw.json` + (`OpenClawSchema`). +- بدائيات القنوات المستقرة مثل `openclaw/plugin-sdk/channel-setup` و + `openclaw/plugin-sdk/setup-runtime` و + `openclaw/plugin-sdk/setup-adapter-runtime` و + `openclaw/plugin-sdk/setup-tools` و + `openclaw/plugin-sdk/channel-pairing` و + `openclaw/plugin-sdk/channel-contract` و + `openclaw/plugin-sdk/channel-feedback` و + `openclaw/plugin-sdk/channel-inbound` و + `openclaw/plugin-sdk/channel-lifecycle` و + `openclaw/plugin-sdk/channel-reply-pipeline` و + `openclaw/plugin-sdk/command-auth` و + `openclaw/plugin-sdk/secret-input` و + `openclaw/plugin-sdk/webhook-ingress` من أجل ربط الإعداد/المصادقة/الرد/webhook المشترك. + يُعد `channel-inbound` الموطن المشترك لـ debounce، ومطابقة mention، + ومساعدات سياسة mention الواردة، وتنسيق envelope الوارد، + ومساعدات سياق envelope الوارد. + يُعد `channel-setup` وصلة الإعداد الاختيارية الضيقة للتثبيت. + يُعد `setup-runtime` سطح الإعداد الآمن لوقت التشغيل المستخدم بواسطة `setupEntry` / + وبدء التشغيل المؤجل، بما في ذلك مهايئات ترقيع الإعداد الآمنة للاستيراد. + يُعد `setup-adapter-runtime` وصلة مهايئ إعداد الحساب الواعية بالبيئة. + يُعد `setup-tools` وصلة المساعدة الصغيرة لـ CLI/الأرشيف/الوثائق (`formatCliCommand`, + `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, + `CONFIG_DIR`). +- المسارات الفرعية النطاقية مثل `openclaw/plugin-sdk/channel-config-helpers` و + `openclaw/plugin-sdk/allow-from` و + `openclaw/plugin-sdk/channel-config-schema` و + `openclaw/plugin-sdk/telegram-command-config` و + `openclaw/plugin-sdk/channel-policy` و + `openclaw/plugin-sdk/approval-gateway-runtime` و + `openclaw/plugin-sdk/approval-handler-adapter-runtime` و + `openclaw/plugin-sdk/approval-handler-runtime` و + `openclaw/plugin-sdk/approval-runtime` و + `openclaw/plugin-sdk/config-runtime` و + `openclaw/plugin-sdk/infra-runtime` و + `openclaw/plugin-sdk/agent-runtime` و + `openclaw/plugin-sdk/lazy-runtime` و + `openclaw/plugin-sdk/reply-history` و + `openclaw/plugin-sdk/routing` و + `openclaw/plugin-sdk/status-helpers` و + `openclaw/plugin-sdk/text-runtime` و + `openclaw/plugin-sdk/runtime-store` و + `openclaw/plugin-sdk/directory-runtime` من أجل مساعدات وقت التشغيل/الإعدادات المشتركة. + يُعد `telegram-command-config` الوصلة العامة الضيقة لتطبيع/التحقق من الأوامر + المخصصة في Telegram، ويبقى متاحًا حتى إذا تعذر مؤقتًا + سطح عقد Telegram المضمّن. + يُعد `text-runtime` وصلة النص/Markdown/التسجيل المشتركة، بما في ذلك + إزالة النص المرئي للمساعد، ومساعدات عرض/تجزئة Markdown، ومساعدات + التنقيح، ومساعدات وسم التوجيهات، وأدوات النص الآمن. +- يجب أن تفضّل الوصلات الخاصة بالقنوات المعتمدة على الموافقة + عقد `approvalCapability` واحدًا على الإضافة. تقرأ النواة بعد ذلك + مصادقة الموافقة، والتسليم، والعرض، والتوجيه الأصلي، وسلوك + المعالج الأصلي الكسول عبر تلك القدرة الواحدة بدلًا من خلط سلوك + الموافقة في حقول غير ذات صلة للإضافة. +- إن `openclaw/plugin-sdk/channel-runtime` مهمل ويبقى فقط كطبقة + توافق للإضافات الأقدم. يجب أن يستورد الكود الجديد البدائيات العامة + الأضيق بدلًا منه، ويجب ألا يضيف كود المستودع استيرادات جديدة + لهذه الطبقة. +- تبقى الأجزاء الداخلية للامتدادات المضمّنة خاصة. يجب على الإضافات الخارجية استخدام + المسارات الفرعية `openclaw/plugin-sdk/*` فقط. يمكن لكود/اختبارات نواة OpenClaw + استخدام نقاط الدخول العامة في المستودع تحت جذر حزمة الإضافة مثل `index.js` و`api.js` و + `runtime-api.js` و`setup-entry.js` والملفات الضيقة النطاق مثل + `login-qr-api.js`. ولا تستورد أبدًا `src/*` لحزمة إضافة من النواة أو من + امتداد آخر. +- تقسيم نقطة دخول المستودع: + يمثّل `/api.js` شريط المساعدات/الأنواع، + ويمثّل `/runtime-api.js` شريط وقت التشغيل فقط، + ويمثّل `/index.js` مدخل الإضافة المضمّنة، + ويمثّل `/setup-entry.js` مدخل إضافة الإعداد. +- أمثلة المزوّدين المضمّنين الحالية: + - يستخدم Anthropic `api.js` / `contract-api.js` لمساعدات تدفق Claude مثل + `wrapAnthropicProviderStream`، ومساعدات رؤوس beta، وتحليل `service_tier`. + - يستخدم OpenAI `api.js` لبناة المزوّد، ومساعدات النموذج الافتراضي، وبناة + المزوّد الفوري. + - يستخدم OpenRouter `api.js` لباني المزوّد الخاص به بالإضافة إلى مساعدات + الإعداد/التهيئة، بينما يظل `register.runtime.js` قادرًا على إعادة تصدير + مساعدات `plugin-sdk/provider-stream` العامة للاستخدام المحلي داخل المستودع. +- تفضّل نقاط الدخول العامة المحمّلة عبر الواجهة + لقطة إعدادات وقت التشغيل النشطة عندما تكون موجودة، ثم تعود إلى + ملف الإعدادات المحلول على القرص عندما لا يكون OpenClaw قد بدأ بعد + في تقديم لقطة وقت تشغيل. +- تظل البدائيات العامة المشتركة هي عقد SDK العام المفضل. ولا تزال توجد + مجموعة توافق صغيرة محجوزة من وصلات المساعدة ذات العلامة القنوية للإضافات المضمّنة. + تعامل معها على أنها وصلات صيانة/توافق للإضافات المضمّنة، لا أهداف استيراد جديدة + لأطراف ثالثة؛ ويجب أن تهبط العقود الجديدة المشتركة بين القنوات على + المسارات العامة `plugin-sdk/*` أو على الأشرطة المحلية للإضافة `api.js` / + `runtime-api.js`. -ملاحظة توافق: +ملاحظة التوافق: -- تجنّب الشريط الجذري `openclaw/plugin-sdk` في الشيفرة الجديدة. -- وفضّل أولًا العناصر الثابتة الضيقة. فالمسارات الفرعية الأحدث الخاصة بالإعداد/الاقتران/الرد/ - feedback/contract/inbound/threading/command/secret-input/webhook/infra/ - allowlist/status/message-tool هي العقد المقصود للأعمال الجديدة على plugins - المضمّنة والخارجية. - ويجب أن ينتمي تحليل/مطابقة الأهداف إلى `openclaw/plugin-sdk/channel-targets`. - كما يجب أن تنتمي بوابات إجراءات الرسائل ومساعدات معرّف رسالة التفاعل إلى +- تجنب شريط `openclaw/plugin-sdk` الجذري في الكود الجديد. +- فضّل البدائيات المستقرة الضيقة أولًا. فالمسارات الفرعية الأحدث للإعداد/الاقتران/الرد/ + والتغذية الراجعة/العقد/الوارد/الترابط/الأوامر/secret-input/webhook/infra/ + وقائمة السماح/الحالة/أداة الرسائل هي العقد المقصود للعمل الجديد على + الإضافات المضمّنة والخارجية. + يجب أن ينتمي التحليل/المطابقة للأهداف إلى `openclaw/plugin-sdk/channel-targets`. + وتنتمي بوابات إجراءات الرسائل ومساعدات message-id الخاصة بالتفاعلات إلى `openclaw/plugin-sdk/channel-actions`. -- لا تُعد أشرطة المساعدات الخاصة بالامتدادات المضمّنة مستقرة افتراضيًا. إذا كانت - المساعدة مطلوبة فقط لامتداد مضمّن، فأبقها خلف الحد المحلي `api.js` أو `runtime-api.js` - الخاص بذلك الامتداد بدل ترقيتها إلى `openclaw/plugin-sdk/`. -- يجب أن تكون حدود المساعدات المشتركة الجديدة عامة لا موسومة باسم قناة. فتحليل - الأهداف المشتركة ينتمي إلى `openclaw/plugin-sdk/channel-targets`؛ بينما تبقى - أساسيات القنوات الخاصة وراء الحد المحلي `api.js` أو `runtime-api.js` - المملوك للـ plugin. -- توجد مسارات فرعية خاصة بالإمكانات مثل `image-generation`, - و`media-understanding`، و`speech` لأن plugins الأصلية/المضمّنة تستخدمها اليوم. - ولا يعني وجودها بحد ذاته أن كل مساعد مُصدَّر هو عقد خارجي - طويل الأمد ومجمّد. +- لا تُعد أشرطة المساعدة الخاصة بالامتدادات المضمّنة مستقرة افتراضيًا. إذا كانت + المساعدة مطلوبة فقط لامتداد مضمّن، فأبقها خلف + الوصلة المحلية لذلك الامتداد `api.js` أو `runtime-api.js` بدلًا من ترقيتها إلى + `openclaw/plugin-sdk/`. +- يجب أن تكون وصلات المساعدة المشتركة الجديدة عامة، لا تحمل علامة قناة. ينتمي + تحليل الأهداف المشترك إلى `openclaw/plugin-sdk/channel-targets`؛ أما + الأجزاء الداخلية الخاصة بالقناة فتبقى خلف الوصلة المحلية `api.js` أو `runtime-api.js` + للإضافة المالكة. +- توجد المسارات الفرعية الخاصة بالقدرات مثل `image-generation` و + `media-understanding` و`speech` لأن الإضافات المضمّنة/الأصلية تستخدمها + اليوم. ولا يعني وجودها بحد ذاته أن كل مساعدة مصدّرة هي عقد خارجي + مجمّد على المدى الطويل. -## Schemas أداة الرسائل +## مخططات أداة الرسائل -يجب أن تمتلك plugins مساهمات schema الخاصة بـ `describeMessageTool(...)` -والخاصة بالقناة. وأبقِ الحقول الخاصة بالمورّد في plugin، لا في النواة المشتركة. +يجب أن تملك الإضافات مساهمات مخطط `describeMessageTool(...)` الخاصة بالقنوات. +أبقِ الحقول الخاصة بالمزوّد في الإضافة، لا في النواة المشتركة. -وبالنسبة إلى أجزاء schema المحمولة المشتركة، أعد استخدام المساعدات العامة المصدّرة عبر +وبالنسبة إلى أجزاء المخطط المحمولة المشتركة، أعد استخدام المساعدات العامة المصدّرة عبر `openclaw/plugin-sdk/channel-actions`: -- `createMessageToolButtonsSchema()` لحِمولات شبكات الأزرار +- `createMessageToolButtonsSchema()` لحِمولات نمط شبكة الأزرار - `createMessageToolCardSchema()` لحِمولات البطاقات المنظمة -إذا كان شكل schema لا معنى له إلا لموفر واحد، فعرّفه في -مصدر تلك plugin نفسها بدل ترقيته إلى SDK المشتركة. +إذا كان شكل المخطط لا معنى له إلا لمزوّد واحد، فعرّفه في +مصدر تلك الإضافة بدلًا من ترقيته إلى SDK المشترك. ## حل أهداف القنوات -يجب أن تمتلك Plugins القنوات دلالات الأهداف الخاصة بالقناة. أبقِ -المضيف المشترك للرسائل الصادرة عامًا، واستخدم سطح محول المراسلة لقواعد -الموفر: +يجب أن تملك إضافات القنوات دلالات الأهداف الخاصة بالقناة. أبقِ مضيف +الإرسال الخارجي عامًا واستخدم سطح مهايئ المراسلة لقواعد المزوّد: -- يقرر `messaging.inferTargetChatType({ to })` ما إذا كان ينبغي معاملة هدف مطبّع - على أنه `direct` أو `group` أو `channel` قبل البحث في الدليل. -- يحدد `messaging.targetResolver.looksLikeId(raw, normalized)` للنواة ما إذا كان ينبغي - تخطي البحث مباشرة إلى حل شبيه بالمعرّف بدلًا من البحث في الدليل. -- تُعد `messaging.targetResolver.resolveTarget(...)` آلية الرجوع الخاصة بالـ plugin عندما - تحتاج النواة إلى حل نهائي مملوك للموفر بعد التطبيع أو بعد فشل الدليل. -- وتمتلك `messaging.resolveOutboundSessionRoute(...)` إنشاء مسار الجلسة الصادر - الخاص بالموفر بعد حل الهدف. +- يقرر `messaging.inferTargetChatType({ to })` ما إذا كان الهدف المطبّع + يجب التعامل معه على أنه `direct` أو `group` أو `channel` قبل البحث في الدليل. +- يخبر `messaging.targetResolver.looksLikeId(raw, normalized)` النواة + ما إذا كان الإدخال يجب أن يتجاوز مباشرة إلى حل شبيه بالمعرّف بدلًا من البحث في الدليل. +- يمثّل `messaging.targetResolver.resolveTarget(...)` احتياط الإضافة عندما + تحتاج النواة إلى حل نهائي مملوك للمزوّد بعد التطبيع أو بعد + فشل الدليل. +- تملك `messaging.resolveOutboundSessionRoute(...)` بناء مسار الجلسة + الخارجي الخاص بالمزوّد بعد حل الهدف. التقسيم الموصى به: - استخدم `inferTargetChatType` لقرارات الفئة التي يجب أن تحدث قبل البحث في الأقران/المجموعات. -- واستخدم `looksLikeId` لفحوص "تعامل مع هذا على أنه معرّف هدف أصلي/صريح". -- واستخدم `resolveTarget` كرجوع خاص بالتطبيع عند الموفر، لا - لبحث واسع في الدليل. -- وأبقِ المعرّفات الأصلية للمورّد مثل معرّفات الدردشة ومعرّفات السلاسل وJIDs - والمقابض ومعرّفات الغرف داخل قيم `target` أو المعاملات الخاصة بالمورّد، لا في - حقول SDK العامة. +- استخدم `looksLikeId` لفحوصات "عامل هذا كمعرّف هدف صريح/أصلي". +- استخدم `resolveTarget` كاحتياط تطبيع خاص بالمزوّد، لا من أجل + بحث واسع في الدليل. +- أبقِ المعرّفات الأصلية للمزوّد مثل معرّفات الدردشة، ومعرّفات السلاسل، وJIDs، + والمعرّفات، ومعرّفات الغرف داخل قيم `target` أو المعلمات الخاصة بالمزوّد، لا في + حقول SDK عامة. -## الأدلة المدعومة بالإعداد +## الأدلة المعتمدة على الإعدادات -يجب أن تُبقي plugins التي تستمد إدخالات الدليل من الإعداد هذا المنطق في -plugin نفسها، وأن تعيد استخدام المساعدات المشتركة من +يجب أن تبقي الإضافات التي تستمد إدخالات الدليل من الإعدادات هذا المنطق داخل +الإضافة وأن تعيد استخدام المساعدات المشتركة من `openclaw/plugin-sdk/directory-runtime`. -استخدم هذا عندما تحتاج قناة إلى أقران/مجموعات مدعومة بالإعداد مثل: +استخدم هذا عندما تحتاج قناة إلى أقران/مجموعات معتمدة على الإعدادات مثل: -- أقران الرسائل المباشرة المدفوعون بقائمة السماح -- خرائط القنوات/المجموعات المضبوطة -- بدائل دليل ثابتة خاصة بالحساب +- أقران الرسائل المباشرة المدفوعة بقائمة السماح +- خرائط القنوات/المجموعات المهيأة +- بدائل دليل ثابتة بنطاق الحساب -تعالج المساعدات المشتركة في `directory-runtime` العمليات العامة فقط: +لا تتعامل المساعدات المشتركة في `directory-runtime` إلا مع العمليات العامة: -- ترشيح الاستعلام -- تطبيق الحد -- إزالة التكرار/التطبيع +- تصفية الاستعلام +- تطبيق الحدود +- إزالة التكرار/مساعدات التطبيع - بناء `ChannelDirectoryEntry[]` -أما فحص الحسابات الخاصة بالقناة وتطبيع المعرّفات فيجب أن يبقيا داخل -تنفيذ plugin. +يجب أن يبقى فحص الحساب الخاص بالقناة وتطبيع المعرّفات داخل +تنفيذ الإضافة. -## فهارس الموفّرين +## كتالوجات المزوّدين -يمكن Plugins الموفّر تعريف فهارس النماذج للاستدلال بواسطة +يمكن لإضافات المزوّد تحديد كتالوجات نماذج للاستدلال باستخدام `registerProvider({ catalog: { run(...) { ... } } })`. -تُعيد `catalog.run(...)` الشكل نفسه الذي يكتبه OpenClaw إلى +يعيد `catalog.run(...)` الشكل نفسه الذي يكتبه OpenClaw إلى `models.providers`: -- `{ provider }` لإدخال موفر واحد -- `{ providers }` لعدة إدخالات موفرين +- `{ provider }` لإدخال مزوّد واحد +- `{ providers }` لعدة إدخالات مزوّدين -استخدم `catalog` عندما تمتلك plugin معرّفات نماذج خاصة بالموفر، أو إعدادات -افتراضية لـ base URL، أو بيانات وصفية للنموذج محكومة بالمصادقة. +استخدم `catalog` عندما تملك الإضافة معرّفات نماذج خاصة بالمزوّد، أو إعدادات +base URL افتراضية، أو بيانات نماذج تعتمد على المصادقة. -تتحكم `catalog.order` في توقيت دمج فهرس plugin نسبةً إلى الموفّرين -الضمنيين المضمّنين في OpenClaw: +يتحكم `catalog.order` في وقت دمج كتالوج الإضافة بالنسبة إلى +المزوّدين الضمنيين المضمّنين في OpenClaw: -- `simple`: موفرو API-key أو env البسطاء -- `profile`: الموفرون الذين يظهرون عند وجود ملفات مصادقة -- `paired`: الموفرون الذين يصطنعون عدة إدخالات موفّرين مرتبطة -- `late`: التمريرة الأخيرة بعد الموفّرين الضمنيين الآخرين +- `simple`: مزوّدون عاديون يعتمدون على API key أو البيئة +- `profile`: مزوّدون يظهرون عند وجود ملفات تعريف مصادقة +- `paired`: مزوّدون يُنشئون عدة إدخالات مزوّدين مرتبطة +- `late`: المرور الأخير، بعد بقية المزوّدين الضمنيين -يربح الموفّر المتأخر عند تعارض المفاتيح، لذا يمكن للـ plugins عمدًا تجاوز -إدخال موفّر مضمّن له معرّف الموفّر نفسه. +يفوز المزوّد اللاحق عند تعارض المفتاح، لذلك يمكن للإضافات عمدًا تجاوز +إدخال مزوّد مضمّن يملك معرّف المزوّد نفسه. التوافق: -- لا يزال `discovery` يعمل كاسم قديم بديل -- إذا تم تسجيل كل من `catalog` و`discovery`، يستخدم OpenClaw `catalog` +- لا يزال `discovery` يعمل كاسم بديل قديم +- إذا سُجِّل كل من `catalog` و`discovery`، يستخدم OpenClaw `catalog` -## فحص القنوات للقراءة فقط +## فحص القناة للقراءة فقط -إذا كانت plugin الخاصة بك تسجل قناة، فافضّل تنفيذ +إذا كانت إضافتك تسجل قناة، ففضّل تنفيذ `plugin.config.inspectAccount(cfg, accountId)` إلى جانب `resolveAccount(...)`. السبب: -- `resolveAccount(...)` هو مسار وقت التشغيل. ويُسمح له بافتراض أن بيانات الاعتماد - قد تحققت بالكامل، ويمكنه الفشل سريعًا عند غياب الأسرار المطلوبة. -- لا ينبغي لمسارات الأوامر المخصصة للقراءة فقط مثل `openclaw status`، و`openclaw status --all`، - و`openclaw channels status`، و`openclaw channels resolve`، وتدفقات doctor/config - للإصلاح أن تحتاج إلى تفعيل بيانات اعتماد وقت التشغيل فقط من أجل - وصف الإعداد. +- يمثل `resolveAccount(...)` مسار وقت التشغيل. ويُسمح له بافتراض أن بيانات الاعتماد + قد جرى تفعيلها بالكامل، ويمكنه الفشل بسرعة عند غياب الأسرار المطلوبة. +- يجب ألا تحتاج مسارات الأوامر للقراءة فقط مثل `openclaw status` و + `openclaw status --all` و`openclaw channels status` و`openclaw channels resolve` وعمليات + doctor/config repair إلى تفعيل بيانات اعتماد وقت التشغيل فقط من أجل + وصف الإعدادات. السلوك الموصى به لـ `inspectAccount(...)`: -- أعد فقط حالة وصفية للحساب. -- حافظ على `enabled` و`configured`. -- أدرج حقول مصدر/حالة بيانات الاعتماد عند الصلة، مثل: - - `tokenSource`، `tokenStatus` - - `botTokenSource`، `botTokenStatus` - - `appTokenSource`، `appTokenStatus` - - `signingSecretSource`، `signingSecretStatus` +- أعد حالة وصفية للحساب فقط. +- احتفظ بـ `enabled` و`configured`. +- أدرج حقول مصدر/حالة بيانات الاعتماد عند الحاجة، مثل: + - `tokenSource`, `tokenStatus` + - `botTokenSource`, `botTokenStatus` + - `appTokenSource`, `appTokenStatus` + - `signingSecretSource`, `signingSecretStatus` - لا تحتاج إلى إعادة قيم الرموز الخام فقط للإبلاغ عن - التوفر للقراءة فقط. يكفي إرجاع `tokenStatus: "available"` (مع - حقل المصدر المطابق) لأوامر على نمط الحالة. -- استخدم `configured_unavailable` عندما تكون بيانات الاعتماد مضبوطة عبر SecretRef لكنها + التوفر للقراءة فقط. يكفي إرجاع `tokenStatus: "available"` (وحقل المصدر + المطابق). +- استخدم `configured_unavailable` عندما تكون بيانات الاعتماد مهيأة عبر SecretRef لكنها غير متاحة في مسار الأمر الحالي. -وهذا يتيح للأوامر المخصصة للقراءة فقط الإبلاغ عن "مضبوطة لكنها غير متاحة في -مسار هذا الأمر" بدل التعطل أو الإبلاغ الخاطئ عن أن الحساب غير مضبوط. +يسمح ذلك للأوامر المخصصة للقراءة فقط بالإبلاغ عن "مهيأ لكن غير متاح في مسار هذا الأمر" +بدلًا من التعطل أو الإبلاغ خطأ أن الحساب غير مهيأ. -## حِزم الحِزم +## حزم الحزم -يمكن أن يحتوي دليل plugin على `package.json` يتضمن `openclaw.extensions`: +قد يتضمن دليل الإضافة ملف `package.json` مع `openclaw.extensions`: ```json { @@ -1351,65 +1358,64 @@ plugin نفسها، وأن تعيد استخدام المساعدات المشت } ``` -يصبح كل إدخال plugin. وإذا كانت الحزمة تسرد عدة امتدادات، يصبح معرّف plugin +يصبح كل إدخال إضافة. وإذا أدرجت الحزمة عدة امتدادات، يصبح معرّف الإضافة `name/`. -إذا كانت plugin الخاصة بك تستورد تبعيات npm، فثبّتها في ذلك الدليل حتى -يكون `node_modules` متاحًا (`npm install` / `pnpm install`). +إذا كانت إضافتك تستورد تبعيات npm، فثبّتها في ذلك الدليل حتى +يصبح `node_modules` متاحًا (`npm install` / `pnpm install`). -حاجز أمان: يجب أن يبقى كل إدخال `openclaw.extensions` داخل دليل plugin +حاجز أمان: يجب أن يبقى كل إدخال في `openclaw.extensions` داخل دليل الإضافة بعد حل الروابط الرمزية. وتُرفض الإدخالات التي تهرب من دليل الحزمة. -ملاحظة أمان: يقوم `openclaw plugins install` بتثبيت تبعيات plugin بواسطة -`npm install --omit=dev --ignore-scripts` (بدون lifecycle scripts وبدون تبعيات تطوير وقت التشغيل). حافظ على أشجار تبعيات plugin -"JS/TS خالصة" وتجنب الحزم التي تتطلب بناءً عبر `postinstall`. +ملاحظة أمان: يثبت `openclaw plugins install` تبعيات الإضافة باستخدام +`npm install --omit=dev --ignore-scripts` (من دون سكربتات دورة الحياة، ومن دون تبعيات تطوير وقت التشغيل). أبقِ أشجار تبعيات الإضافة +"JS/TS خالصة" وتجنب الحزم التي تتطلب بناء `postinstall`. -اختياريًا: يمكن أن يشير `openclaw.setupEntry` إلى وحدة خفيفة مخصصة للإعداد فقط. -وعندما يحتاج OpenClaw إلى أسطح إعداد لـ channel plugin معطّلة، أو -عندما تكون channel plugin مفعّلة لكنها غير مضبوطة بعد، فإنه يحمّل `setupEntry` -بدل مدخل plugin الكامل. وهذا يبقي بدء التشغيل والإعداد أخف -عندما يكون المدخل الرئيسي للـ plugin يوصل أيضًا أدوات أو خطافات أو شيفرة -أخرى مخصصة لوقت التشغيل فقط. +اختياري: يمكن أن يشير `openclaw.setupEntry` إلى وحدة خفيفة خاصة بالإعداد فقط. +عندما يحتاج OpenClaw إلى أسطح إعداد لإضافة قناة معطلة، أو +عندما تكون إضافة القناة مفعلة لكنها لا تزال غير مهيأة، فإنه يحمّل `setupEntry` +بدلًا من مدخل الإضافة الكامل. وهذا يبقي بدء التشغيل والإعداد أخف +عندما يكون مدخل الإضافة الرئيسي لديك يربط أيضًا أدوات أو خطافات أو كودًا +آخر خاصًا بوقت التشغيل فقط. -اختياريًا: يمكن لـ -`openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -إدخال channel plugin في مسار `setupEntry` نفسه خلال مرحلة بدء التشغيل -قبل الاستماع في gateway، حتى عندما تكون القناة مضبوطة بالفعل. +اختياري: يمكن لـ `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` +إدخال إضافة قناة في مسار `setupEntry` نفسه خلال مرحلة +بدء التشغيل السابقة للاستماع في البوابة، حتى عندما تكون القناة مهيأة بالفعل. -استخدم هذا فقط عندما يغطي `setupEntry` بالكامل سطح بدء التشغيل الذي يجب أن -يوجد قبل أن تبدأ gateway في الاستماع. وعمليًا، يعني هذا أن مدخل الإعداد +استخدم هذا فقط عندما يغطي `setupEntry` بالكامل سطح بدء التشغيل الذي يجب أن يوجد +قبل أن تبدأ البوابة في الاستماع. وعمليًا، يعني هذا أن مدخل الإعداد يجب أن يسجل كل قدرة مملوكة للقناة يعتمد عليها بدء التشغيل، مثل: -- تسجيل القناة نفسها -- أي مسارات HTTP يجب أن تكون متاحة قبل أن تبدأ gateway في الاستماع -- أي أساليب Gateway أو أدوات أو خدمات يجب أن توجد خلال هذه النافذة نفسها +- تسجيل القناة نفسه +- أي مسارات HTTP يجب أن تكون متاحة قبل أن تبدأ البوابة في الاستماع +- أي أساليب Gateway أو أدوات أو خدمات يجب أن توجد أثناء النافذة نفسها -إذا كان المدخل الكامل لا يزال يمتلك أي قدرة مطلوبة عند بدء التشغيل، فلا تفعّل -هذا العلم. أبقِ plugin على السلوك الافتراضي ودع OpenClaw يحمّل +إذا كان مدخلك الكامل لا يزال يملك أي قدرة مطلوبة عند بدء التشغيل، فلا تفعّل +هذا العلم. أبقِ الإضافة على السلوك الافتراضي ودع OpenClaw يحمّل المدخل الكامل أثناء بدء التشغيل. -يمكن للقنوات المضمّنة أيضًا نشر مساعدات سطح عقد للإعداد فقط يمكن للنواة -الرجوع إليها قبل تحميل وقت تشغيل القناة الكامل. وسطح الترقية الحالي للإعداد هو: +يمكن للقنوات المضمّنة أيضًا نشر مساعدات سطح عقد خاصة بالإعداد فقط يمكن للنواة +استشارتها قبل تحميل وقت تشغيل القناة الكامل. وسطح الترقية الحالي للإعداد هو: - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -تستخدم النواة هذا السطح عندما تحتاج إلى ترقية إعداد قناة قديم أحادي الحساب -إلى `channels..accounts.*` بدون تحميل مدخل plugin الكامل. +تستخدم النواة هذا السطح عندما تحتاج إلى ترقية إعدادات قناة قديمة بحساب واحد +إلى `channels..accounts.*` دون تحميل مدخل الإضافة الكامل. وتُعد Matrix المثال المضمّن الحالي: فهي تنقل فقط مفاتيح المصادقة/التمهيد إلى -حساب مُرقّى مسمى عندما تكون الحسابات المسماة موجودة بالفعل، ويمكنها -الحفاظ على مفتاح حساب افتراضي غير قانوني مضبوط بدل إنشاء +حساب مُرقّى مسمّى عندما تكون الحسابات المسماة موجودة بالفعل، ويمكنها +الحفاظ على مفتاح حساب افتراضي غير قانوني مهيأ بدلًا من إنشاء `accounts.default` دائمًا. -تُبقي محولات ترقيع الإعداد هذه اكتشاف سطح العقد المضمّن كسولًا. فيبقى -وقت الاستيراد خفيفًا؛ ولا يُحمّل سطح الترقية إلا عند أول استخدام بدل -إعادة الدخول إلى بدء تشغيل القناة المضمّنة عند استيراد الوحدة. +تبقي مهايئات ترقيع الإعداد هذه اكتشاف سطح عقد الإضافة المضمّنة كسولًا. فيبقى +وقت الاستيراد خفيفًا؛ ويُحمَّل سطح الترقية عند أول استخدام فقط بدلًا من +إعادة دخول بدء تشغيل القناة المضمّنة عند استيراد الوحدة. عندما تتضمن أسطح بدء التشغيل هذه أساليب Gateway RPC، فأبقها على -بادئة خاصة بالـ plugin. تبقى مساحات أسماء الإدارة الأساسية (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) محجوزة وتحل دائمًا -إلى `operator.admin` حتى إذا طلبت plugin نطاقًا أضيق. +بادئة خاصة بالإضافة. وتظل مساحات أسماء الإدارة الأساسية (`config.*`, +`exec.approvals.*`, `wizard.*`, `update.*`) محجوزة وتحل دائمًا إلى +`operator.admin`، حتى إذا طلبت الإضافة نطاقًا أضيق. مثال: @@ -1426,10 +1432,10 @@ plugin نفسها، وأن تعيد استخدام المساعدات المشت } ``` -### بيانات فهرس القناة الوصفية +### بيانات كتالوج القنوات الوصفية -يمكن Plugins القنوات الإعلان عن بيانات وصفية للإعداد/الاكتشاف عبر `openclaw.channel` و -تلميحات التثبيت عبر `openclaw.install`. وهذا يُبقي بيانات الفهرس في النواة خالية من البيانات الصلبة. +يمكن لإضافات القنوات الإعلان عن بيانات الإعداد/الاكتشاف الوصفية عبر `openclaw.channel` و +تلميحات التثبيت عبر `openclaw.install`. وهذا يبقي بيانات الكتالوج خارج النواة. مثال: @@ -1457,52 +1463,60 @@ plugin نفسها، وأن تعيد استخدام المساعدات المشت } ``` -حقول `openclaw.channel` المفيدة إضافة إلى المثال الأدنى: +حقول `openclaw.channel` المفيدة إلى جانب المثال الأدنى: -- `detailLabel`: تسمية ثانوية لأسطح الفهرس/الحالة الأكثر غنى -- `docsLabel`: تجاوز نص الرابط الخاص بالمستندات -- `preferOver`: معرّفات plugins/قنوات أقل أولوية يجب أن يتفوق عليها إدخال الفهرس هذا -- `selectionDocsPrefix`، و`selectionDocsOmitLabel`، و`selectionExtras`: أدوات تحكم نصية لأسطح الاختيار -- `markdownCapable`: تضع علامة على القناة بأنها قادرة على markdown من أجل قرارات التنسيق الصادر -- `exposure.configured`: إخفاء القناة من أسطح سرد القنوات المضبوطة عند تعيينها إلى `false` -- `exposure.setup`: إخفاء القناة من منتقيات الإعداد/التهيئة التفاعلية عند تعيينها إلى `false` -- `exposure.docs`: وسم القناة على أنها داخلية/خاصة لأسطح التنقل في المستندات -- `showConfigured` / `showInSetup`: أسماء قديمة بديلة لا تزال مقبولة للتوافق؛ يفضّل `exposure` -- `quickstartAllowFrom`: يدرج القناة ضمن تدفق `allowFrom` القياسي للبدء السريع -- `forceAccountBinding`: يفرض ربط الحساب صراحةً حتى عند وجود حساب واحد فقط -- `preferSessionLookupForAnnounceTarget`: يفضّل البحث في الجلسة عند حل أهداف الإعلانات +- `detailLabel`: تسمية ثانوية لأسطح الكتالوج/الحالة الأكثر غنى +- `docsLabel`: تجاوز نص رابط الوثائق +- `preferOver`: معرّفات الإضافة/القناة ذات الأولوية الأقل التي يجب أن يتفوق عليها إدخال الكتالوج هذا +- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: عناصر تحكم النسخ الخاصة بسطح الاختيار +- `markdownCapable`: يضع علامة على القناة على أنها قادرة على Markdown لقرارات التنسيق الخارجي +- `exposure.configured`: إخفاء القناة من أسطح عرض القنوات المهيأة عندما تكون قيمته `false` +- `exposure.setup`: إخفاء القناة من منتقيات الإعداد/التهيئة التفاعلية عندما تكون قيمته `false` +- `exposure.docs`: وضع علامة على القناة على أنها داخلية/خاصة لأسطح التنقل في الوثائق +- `showConfigured` / `showInSetup`: أسماء بديلة قديمة لا تزال مقبولة للتوافق؛ ويفضّل `exposure` +- `quickstartAllowFrom`: إدخال القناة في تدفق `allowFrom` السريع القياسي +- `forceAccountBinding`: فرض ربط حساب صريح حتى عند وجود حساب واحد فقط +- `preferSessionLookupForAnnounceTarget`: تفضيل البحث في الجلسة عند حل أهداف الإعلان -يمكن لـ OpenClaw أيضًا دمج **فهارس قنوات خارجية** (مثلًا، تصدير سجل MPM). -ضع ملف JSON في أحد المواقع التالية: +يمكن لـ OpenClaw أيضًا دمج **كتالوجات قنوات خارجية** (على سبيل المثال، تصدير +سجل MPM). ضع ملف JSON في أحد المسارات التالية: - `~/.openclaw/mpm/plugins.json` - `~/.openclaw/mpm/catalog.json` - `~/.openclaw/plugins/catalog.json` أو وجّه `OPENCLAW_PLUGIN_CATALOG_PATHS` (أو `OPENCLAW_MPM_CATALOG_PATHS`) إلى -ملف JSON واحد أو أكثر (مفصولة بفاصلة/فاصلة منقوطة/`PATH`). ويجب أن يحتوي كل ملف -على `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. كما يقبل المحلل -القيمتين `"packages"` أو `"plugins"` كأسماء قديمة بديلة للمفتاح `"entries"`. +ملف JSON واحد أو أكثر (مفصولة بفواصل/فواصل منقوطة/`PATH`). يجب أن يحتوي كل ملف +على `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. يقبل المحلل أيضًا `"packages"` أو `"plugins"` كأسماء بديلة قديمة للمفتاح `"entries"`. -## Plugins محرك السياق +## إضافات محرك السياق -تمتلك Plugins محرك السياق تنسيق سياق الجلسة من أجل الإدخال والتجميع -والضغط. سجّلها من plugin الخاصة بك عبر -`api.registerContextEngine(id, factory)`، ثم اختر المحرك النشط بواسطة +تملك إضافات محرك السياق تنسيق سياق الجلسة لعمليات الإدخال، +والتجميع، والضغط. سجّلها من إضافتك باستخدام +`api.registerContextEngine(id, factory)`، ثم حدّد المحرك النشط باستخدام `plugins.slots.contextEngine`. -استخدم هذا عندما تحتاج plugin الخاصة بك إلى استبدال خط أنابيب السياق الافتراضي أو -توسيعه بدل مجرد إضافة بحث ذاكرة أو خطافات. +استخدم هذا عندما تحتاج إضافتك إلى استبدال خط أنابيب السياق الافتراضي أو +توسيعه بدلًا من مجرد إضافة بحث في الذاكرة أو خطافات. ```ts +import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; + export default function (api) { api.registerContextEngine("lossless-claw", () => ({ info: { id: "lossless-claw", name: "Lossless Claw", ownsCompaction: true }, async ingest() { return { ingested: true }; }, - async assemble({ messages }) { - return { messages, estimatedTokens: 0 }; + async assemble({ messages, availableTools, citationsMode }) { + return { + messages, + estimatedTokens: 0, + systemPromptAddition: buildMemorySystemPromptAddition({ + availableTools: availableTools ?? new Set(), + citationsMode, + }), + }; }, async compact() { return { ok: true, compacted: false }; @@ -1511,11 +1525,14 @@ export default function (api) { } ``` -إذا كان المحرك **لا** يمتلك خوارزمية الضغط، فأبقِ `compact()` -منفذة وفوّضها صراحةً: +إذا كان محركك **لا** يملك خوارزمية الضغط، فأبقِ `compact()` +منفذًا وفوّضه صراحة: ```ts -import { delegateCompactionToRuntime } from "openclaw/plugin-sdk/core"; +import { + buildMemorySystemPromptAddition, + delegateCompactionToRuntime, +} from "openclaw/plugin-sdk/core"; export default function (api) { api.registerContextEngine("my-memory-engine", () => ({ @@ -1527,8 +1544,15 @@ export default function (api) { async ingest() { return { ingested: true }; }, - async assemble({ messages }) { - return { messages, estimatedTokens: 0 }; + async assemble({ messages, availableTools, citationsMode }) { + return { + messages, + estimatedTokens: 0, + systemPromptAddition: buildMemorySystemPromptAddition({ + availableTools: availableTools ?? new Set(), + citationsMode, + }), + }; }, async compact(params) { return await delegateCompactionToRuntime(params); @@ -1539,45 +1563,45 @@ export default function (api) { ## إضافة قدرة جديدة -عندما تحتاج plugin إلى سلوك لا يناسب API الحالية، فلا تتجاوز -نظام plugins عبر وصول خاص. أضف القدرة المفقودة. +عندما تحتاج إضافة إلى سلوك لا يناسب واجهة برمجة التطبيقات الحالية، فلا +تتجاوز نظام الإضافات بتوغّل خاص. أضف القدرة المفقودة. التسلسل الموصى به: 1. تعريف عقد النواة - حدّد السلوك المشترك الذي يجب أن تمتلكه النواة: السياسة، والرجوع الاحتياطي، ودمج الإعداد، - ودورة الحياة، والدلالات المواجهة للقنوات، وشكل مساعد وقت التشغيل. -2. إضافة أسطح تسجيل/وقت تشغيل مكتوبة للـ plugins + قرر ما السلوك المشترك الذي يجب أن تملكه النواة: السياسة، والاحتياط، ودمج الإعدادات، + ودورة الحياة، والدلالات المواجهة للقناة، وشكل مساعد وقت التشغيل. +2. إضافة أسطح تسجيل/وقت تشغيل مكتوبة الأنواع للإضافة وسّع `OpenClawPluginApi` و/أو `api.runtime` بأصغر - سطح قدرة مكتوب مفيد. -3. ربط مستهلكي النواة + القنوات/الميزات - يجب أن تستهلك القنوات وplugins الميزات القدرة الجديدة عبر النواة، - لا عبر استيراد تنفيذ مورّد مباشرة. -4. تسجيل تنفيذات المورّدين - ثم تسجل plugins الخاصة بالمورّدين خلفياتها مقابل هذه القدرة. + سطح قدرة مكتوب الأنواع مفيد. +3. ربط مستهلكي النواة + القناة/الميزة + يجب أن تستهلك القنوات وإضافات الميزات القدرة الجديدة عبر النواة، + لا باستيراد تنفيذ مورّد مباشرة. +4. تسجيل تنفيذات المورّد + تسجل إضافات المورّدين بعد ذلك واجهاتها الخلفية مقابل القدرة. 5. إضافة تغطية للعقد - أضف اختبارات حتى تبقى الملكية وشكل التسجيل صريحين مع مرور الوقت. + أضف اختبارات حتى تبقى الملكية وشكل التسجيل صريحين مع الزمن. -هكذا يحافظ OpenClaw على توجهه الواضح دون أن يصبح مقيّدًا بنظرة -موفّر واحد للعالم. راجع [Capability Cookbook](/ar/plugins/architecture) -للحصول على قائمة ملفات عملية ومثال تطبيقي. +هكذا يبقى OpenClaw صاحب رأي دون أن يصبح مشفّرًا مباشرة وفق +رؤية مزوّد واحد. راجع [دليل القدرات](/ar/plugins/architecture) +للاطلاع على قائمة ملفات عملية ومثال تطبيقي. -### قائمة التحقق من القدرة +### قائمة التحقق الخاصة بالقدرات -عند إضافة قدرة جديدة، ينبغي عادةً أن يلمس التنفيذ هذه +عند إضافة قدرة جديدة، يجب أن يلمس التنفيذ عادةً هذه الأسطح معًا: - أنواع عقد النواة في `src//types.ts` -- مساعد المشغّل/وقت التشغيل في النواة في `src//runtime.ts` -- سطح تسجيل API الخاص بالـ plugin في `src/plugins/types.ts` -- ربط سجل plugin في `src/plugins/registry.ts` -- كشف وقت تشغيل plugin في `src/plugins/runtime/*` عندما تحتاج - plugins الميزات/القنوات إلى استهلاكه +- العداء/مساعد وقت التشغيل في النواة في `src//runtime.ts` +- سطح تسجيل واجهة برمجة الإضافة في `src/plugins/types.ts` +- ربط سجل الإضافات في `src/plugins/registry.ts` +- كشف وقت تشغيل الإضافة في `src/plugins/runtime/*` عندما تحتاج + إضافات الميزة/القناة إلى استهلاكها - مساعدات الالتقاط/الاختبار في `src/test-utils/plugin-registration.ts` - تأكيدات الملكية/العقد في `src/plugins/contracts/registry.ts` -- مستندات المشغّل/الـ plugin في `docs/` +- وثائق المشغّل/الإضافة في `docs/` -إذا كان أحد هذه الأسطح مفقودًا، فغالبًا ما يكون ذلك إشارة إلى أن القدرة +إذا كان أحد هذه الأسطح مفقودًا، فغالبًا ما يكون ذلك علامة على أن القدرة لم تُدمج بالكامل بعد. ### قالب القدرة @@ -1614,9 +1638,9 @@ const clip = await api.runtime.videoGeneration.generate({ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); ``` -وهذا يُبقي القاعدة بسيطة: +ويبقي ذلك القاعدة بسيطة: -- تمتلك النواة عقد القدرة + التنسيق -- وتمتلك plugins الخاصة بالمورّدين تنفيذات المورّد -- وتستهلك plugins الميزات/القنوات مساعدات وقت التشغيل -- وتحافظ اختبارات العقد على صراحة الملكية +- تملك النواة عقد القدرة + التنسيق +- تملك إضافات المورّدين تنفيذات المورّد +- تستهلك إضافات الميزة/القناة مساعدات وقت التشغيل +- تُبقي اختبارات العقد الملكية صريحة diff --git a/docs/ar/plugins/sdk-channel-plugins.md b/docs/ar/plugins/sdk-channel-plugins.md index 49d7a4ccf..66ebed797 100644 --- a/docs/ar/plugins/sdk-channel-plugins.md +++ b/docs/ar/plugins/sdk-channel-plugins.md @@ -1,98 +1,114 @@ --- read_when: - - أنت تبني plugin قناة مراسلة جديدة + - أنت تبني إضافة قناة مراسلة جديدة - تريد ربط OpenClaw بمنصة مراسلة - - تحتاج إلى فهم سطح محول ChannelPlugin + - تحتاج إلى فهم سطح محوّل ChannelPlugin sidebarTitle: Channel Plugins -summary: دليل خطوة بخطوة لبناء plugin قناة مراسلة لـ OpenClaw -title: بناء plugins القنوات +summary: دليل خطوة بخطوة لبناء إضافة قناة مراسلة لـ OpenClaw +title: بناء إضافات القنوات x-i18n: - generated_at: "2026-04-07T07:20:16Z" + generated_at: "2026-04-08T02:18:48Z" model: gpt-5.4 provider: openai - source_hash: 0aab6cc835b292c62e33c52ad0c35f989fb1a5b225511e8bdc2972feb3c64f09 + source_hash: d23365b6d92006b30e671f9f0afdba40a2b88c845c5d2299d71c52a52985672f source_path: plugins/sdk-channel-plugins.md workflow: 15 --- -# بناء plugins القنوات +# بناء إضافات القنوات -يرشدك هذا الدليل خلال بناء plugin قناة يربط OpenClaw بمنصة -مراسلة. وبنهاية الدليل سيكون لديك قناة عاملة مع أمان الرسائل الخاصة، -وpairing، وربط الردود في سلاسل، والمراسلة الصادرة. +يرشدك هذا الدليل خلال بناء إضافة قناة تربط OpenClaw بمنصة +مراسلة. وبنهاية هذا الدليل سيكون لديك قناة عاملة تتضمن أمان الرسائل المباشرة، +والاقتران، وتسلسل الردود، والمراسلة الصادرة. - إذا لم تكن قد بنيت أي plugin لـ OpenClaw من قبل، فاقرأ - [البدء](/ar/plugins/building-plugins) أولًا لمعرفة بنية الحزمة الأساسية - وإعداد manifest. + إذا لم تكن قد بنيت أي إضافة OpenClaw من قبل، فاقرأ + [البدء](/ar/plugins/building-plugins) أولًا للاطلاع على البنية الأساسية + للحزمة وإعداد manifest. -## كيف تعمل plugins القنوات +## كيف تعمل إضافات القنوات -لا تحتاج plugins القنوات إلى أدوات send/edit/react خاصة بها. يحتفظ OpenClaw -بأداة `message` واحدة مشتركة في النواة. وتمتلك plugin الخاصة بك ما يلي: +لا تحتاج إضافات القنوات إلى أدوات send/edit/react خاصة بها. يحتفظ OpenClaw +بأداة `message` مشتركة واحدة في النواة. وتملك إضافتك ما يلي: -- **التهيئة** — تحليل الحسابات ومعالج الإعداد -- **الأمان** — سياسة الرسائل الخاصة وallowlists -- **Pairing** — تدفق اعتماد الرسائل الخاصة -- **صياغة الجلسة** — كيفية تعيين معرّفات المحادثة الخاصة بالموفر إلى الدردشات الأساسية ومعرّفات سلاسل الرسائل وبدائل الأصل -- **الصادر** — إرسال النصوص والوسائط واستطلاعات الرأي إلى المنصة -- **الترابط في السلاسل** — كيفية ربط الردود في سلاسل +- **الإعدادات** — حلّ الحسابات ومعالج الإعداد +- **الأمان** — سياسة الرسائل المباشرة وقوائم السماح +- **الاقتران** — تدفق الموافقة على الرسائل المباشرة +- **بنية الجلسة** — كيفية ربط معرّفات المحادثات الخاصة بالمزوّد بالدردشات الأساسية ومعرّفات السلاسل والبدائل الأصلية +- **الصادر** — إرسال النصوص والوسائط والاستطلاعات إلى المنصة +- **التسلسل** — كيفية ربط الردود ضمن السلاسل -تمتلك النواة أداة الرسائل المشتركة، وربط prompt، وشكل مفتاح الجلسة الخارجي، -والتتبّع العام `:thread:`، والإرسال. +تملك النواة أداة الرسائل المشتركة، وربط الموجّهات، وشكل مفتاح الجلسة الخارجي، +وإدارة `:thread:` العامة، والتوزيع. -إذا كانت منصتك تخزّن نطاقًا إضافيًا داخل معرّفات المحادثات، فاحتفظ بهذا التحليل -داخل plugin باستخدام `messaging.resolveSessionConversation(...)`. هذا هو -المدخل القياسي لتعيين `rawId` إلى معرّف المحادثة الأساسي، ومعرّف سلسلة -اختياري، و`baseConversationId` صريح، وأي `parentConversationCandidates`. -عندما تعيد `parentConversationCandidates`، فاحرص على ترتيبها من -الأصل الأضيق إلى المحادثة الأساسية/الأوسع. +إذا كانت منصتك تخزن نطاقًا إضافيًا داخل معرّفات المحادثات، فاحتفظ بهذا التحليل +داخل الإضافة باستخدام `messaging.resolveSessionConversation(...)`. هذا هو +الخطاف القياسي لتحويل `rawId` إلى معرّف المحادثة الأساسي، ومعرّف السلسلة الاختياري، +و`baseConversationId` الصريح، وأي `parentConversationCandidates`. +عندما تُرجع `parentConversationCandidates`، احرص على ترتيبها من +الأصل الأضيق إلى المحادثة الأوسع/الأساسية. -يمكن أيضًا لـ plugins المضمّنة التي تحتاج إلى التحليل نفسه قبل إقلاع سجل القنوات -أن تعرض ملف `session-key-api.ts` أعلى المستوى مع -تصدير `resolveSessionConversation(...)` مطابق. تستخدم النواة هذا السطح الآمن -للتمهيد فقط عندما لا يكون سجل plugin وقت التشغيل متاحًا بعد. +يمكن أيضًا للإضافات المضمّنة التي تحتاج إلى التحليل نفسه قبل إقلاع +سجل القنوات أن تعرض ملف `session-key-api.ts` على المستوى الأعلى مع +تصدير مطابق `resolveSessionConversation(...)`. تستخدم النواة هذا السطح +الآمن للإقلاع فقط عندما لا يكون سجل الإضافات وقت التشغيل متاحًا بعد. -يبقى `messaging.resolveParentConversationCandidates(...)` متاحًا كبديل -توافقي قديم عندما تحتاج plugin فقط إلى بدائل الأصل فوق -المعرّف العام/الخام. وإذا وُجد كلا المدخلين، تستخدم النواة +يبقى `messaging.resolveParentConversationCandidates(...)` متاحًا +كبديل توافق قديم عندما تحتاج الإضافة فقط إلى بدائل أصلية فوق +المعرّف العام/الخام. إذا وُجد الخطافان معًا، تستخدم النواة `resolveSessionConversation(...).parentConversationCandidates` أولًا ولا -تعود إلى `resolveParentConversationCandidates(...)` إلا عندما يحذفها -المدخل القياسي. +تعود إلى `resolveParentConversationCandidates(...)` إلا عندما يتجاهلها +الخطاف القياسي. -## الموافقات وإمكانات القناة +## الموافقات وقدرات القناة -معظم plugins القنوات لا تحتاج إلى شيفرة خاصة بالموافقات. +لا تحتاج معظم إضافات القنوات إلى تعليمات برمجية خاصة بالموافقات. -- تمتلك النواة `/approve` في الدردشة نفسها، وحمولات أزرار الموافقة المشتركة، والتسليم الاحتياطي العام. -- فضّل كائن `approvalCapability` واحدًا على plugin القناة عندما تحتاج القناة إلى سلوك خاص بالموافقات. -- يمثّل `approvalCapability.authorizeActorAction` و`approvalCapability.getActionAvailabilityState` مدخل التفويض القياسي للموافقات. -- إذا كانت قناتك تعرض موافقات exec أصلية، فنفّذ `approvalCapability.getActionAvailabilityState` حتى عندما تعيش وسيلة النقل الأصلية بالكامل تحت `approvalCapability.native`. تستخدم النواة هذا المدخل الخاص بالتوافر للتمييز بين `enabled` و`disabled`، وتقرير ما إذا كانت القناة البادئة تدعم الموافقات الأصلية، وتضمين القناة في إرشادات fallback الخاصة بالعميل الأصلي. -- استخدم `outbound.shouldSuppressLocalPayloadPrompt` أو `outbound.beforeDeliverPayload` لسلوك دورة حياة الحمولات الخاص بالقناة مثل إخفاء مطالبات الموافقة المحلية المكررة أو إرسال مؤشرات الكتابة قبل التسليم. -- استخدم `approvalCapability.delivery` فقط للتوجيه الأصلي للموافقات أو كبت fallback. -- استخدم `approvalCapability.render` فقط عندما تحتاج القناة فعلًا إلى حمولات موافقة مخصصة بدلًا من المصيّر المشترك. -- استخدم `approvalCapability.describeExecApprovalSetup` عندما تريد القناة أن يشرح رد المسار المعطّل مفاتيح التهيئة الدقيقة المطلوبة لتمكين موافقات exec الأصلية. يتلقى المدخل `{ channel, channelLabel, accountId }`؛ ويجب على القنوات ذات الحسابات المسماة عرض مسارات بنطاق الحساب مثل `channels..accounts..execApprovals.*` بدلًا من القيم الافتراضية على المستوى الأعلى. -- إذا كانت القناة تستطيع استنتاج هويات رسائل خاصة ثابتة شبيهة بالمالك من التهيئة الحالية، فاستخدم `createResolvedApproverActionAuthAdapter` من `openclaw/plugin-sdk/approval-runtime` لتقييد `/approve` في الدردشة نفسها دون إضافة منطق خاص بالموافقات إلى النواة. -- إذا كانت القناة تحتاج إلى تسليم موافقات أصلية، فأبقِ شيفرة القناة مركزة على تطبيع الهدف ومدخلات وسيلة النقل. استخدم `createChannelExecApprovalProfile` و`createChannelNativeOriginTargetResolver` و`createChannelApproverDmTargetResolver` و`createApproverRestrictedNativeApprovalCapability` و`createChannelNativeApprovalRuntime` من `openclaw/plugin-sdk/approval-runtime` حتى تمتلك النواة تصفية الطلبات والتوجيه وإزالة التكرار والانتهاء والاشتراك في البوابة. -- يجب على قنوات الموافقات الأصلية تمرير كل من `accountId` و`approvalKind` عبر هذه المساعدات. يحافظ `accountId` على تقييد سياسة الموافقات متعددة الحسابات بنطاق حساب الروبوت الصحيح، ويحافظ `approvalKind` على إتاحة سلوك exec مقابل plugin للقناة دون فروع ثابتة في النواة. -- حافظ على نوع معرّف الموافقة المُسلَّم من البداية إلى النهاية. يجب على العملاء الأصليين ألا - يخمّنوا أو يعيدوا كتابة توجيه موافقات exec مقابل plugin اعتمادًا على حالة محلية في القناة. -- يمكن لأنواع الموافقات المختلفة أن تعرض عمدًا أسطحًا أصلية مختلفة. - أمثلة مضمّنة حالية: - - يحتفظ Slack بإتاحة توجيه الموافقات الأصلية لكل من معرّفات exec وplugin. - - يحتفظ Matrix بتوجيه الرسائل الخاصة/القنوات الأصلي لموافقات exec فقط ويترك - موافقات plugin على مسار `/approve` المشترك داخل الدردشة نفسها. -- ما يزال `createApproverRestrictedNativeApprovalAdapter` موجودًا كغلاف توافق، لكن الشيفرة الجديدة يجب أن تفضّل باني الإمكانات وتعرض `approvalCapability` على plugin. +- تملك النواة الأمر `/approve` داخل الدردشة نفسها، وحمولات أزرار الموافقة المشتركة، وآلية التسليم العامة البديلة. +- فضّل استخدام كائن `approvalCapability` واحد في إضافة القناة عندما تحتاج القناة إلى سلوك خاص بالموافقة. +- تمت إزالة `ChannelPlugin.approvals`. ضع حقائق تسليم/أصلية/عرض/مصادقة الموافقة في `approvalCapability`. +- يقتصر `plugin.auth` على login/logout فقط؛ ولم تعد النواة تقرأ خطافات مصادقة الموافقة من ذلك الكائن. +- يشكّل كل من `approvalCapability.authorizeActorAction` و`approvalCapability.getActionAvailabilityState` سطح مصادقة الموافقة القياسي. +- استخدم `approvalCapability.getActionAvailabilityState` لتوافر مصادقة الموافقة داخل الدردشة نفسها. +- إذا كانت قناتك تعرض موافقات exec أصلية، فاستخدم `approvalCapability.getExecInitiatingSurfaceState` لحالة السطح المُطلِق/العميل الأصلي عندما تختلف عن مصادقة الموافقة داخل الدردشة نفسها. تستخدم النواة هذا الخطاف الخاص بـ exec للتمييز بين `enabled` و`disabled`، ولتحديد ما إذا كانت القناة المُطلِقة تدعم موافقات exec الأصلية، ولتضمين القناة في إرشادات بدائل العميل الأصلي. يملأ `createApproverRestrictedNativeApprovalCapability(...)` هذا للحالة الشائعة. +- استخدم `outbound.shouldSuppressLocalPayloadPrompt` أو `outbound.beforeDeliverPayload` لسلوك دورة حياة الحمولة الخاص بالقناة مثل إخفاء مطالبات الموافقة المحلية المكررة أو إرسال مؤشرات الكتابة قبل التسليم. +- استخدم `approvalCapability.delivery` فقط لتوجيه الموافقة الأصلية أو منع التسليم البديل. +- استخدم `approvalCapability.nativeRuntime` للحقائق الأصلية للموافقة المملوكة للقناة. احرص على إبقائه كسولًا في نقاط دخول القناة الساخنة باستخدام `createLazyChannelApprovalNativeRuntimeAdapter(...)`، الذي يمكنه استيراد وحدة وقت التشغيل عند الطلب مع استمرار قدرة النواة على تجميع دورة حياة الموافقة. +- استخدم `approvalCapability.render` فقط عندما تحتاج القناة فعلًا إلى حمولات موافقة مخصصة بدلًا من العارض المشترك. +- استخدم `approvalCapability.describeExecApprovalSetup` عندما تريد القناة أن يشرح رد مسار التعطيل مفاتيح الإعداد الدقيقة اللازمة لتمكين موافقات exec الأصلية. يتلقى الخطاف `{ channel, channelLabel, accountId }`؛ ويجب على القنوات ذات الحسابات المسمّاة عرض مسارات على مستوى الحساب مثل `channels..accounts..execApprovals.*` بدلًا من الإعدادات الافتراضية العليا. +- إذا كانت القناة تستطيع استنتاج هويات DM مستقرة شبيهة بالمالك من الإعدادات الحالية، فاستخدم `createResolvedApproverActionAuthAdapter` من `openclaw/plugin-sdk/approval-runtime` لتقييد `/approve` داخل الدردشة نفسها دون إضافة منطق أساسي خاص بالموافقة. +- إذا احتاجت القناة إلى تسليم موافقة أصلية، فأبقِ تعليمات القناة البرمجية مركّزة على تطبيع الهدف وحقائق النقل/العرض. استخدم `createChannelExecApprovalProfile` و`createChannelNativeOriginTargetResolver` و`createChannelApproverDmTargetResolver` و`createApproverRestrictedNativeApprovalCapability` من `openclaw/plugin-sdk/approval-runtime`. ضع الحقائق الخاصة بالقناة خلف `approvalCapability.nativeRuntime`، ويفضل عبر `createChannelApprovalNativeRuntimeAdapter(...)` أو `createLazyChannelApprovalNativeRuntimeAdapter(...)`، حتى تتمكن النواة من تجميع المعالج وامتلاك تصفية الطلبات والتوجيه وإزالة التكرار والانتهاء والاشتراك في البوابة وإشعارات التوجيه إلى مكان آخر. ينقسم `nativeRuntime` إلى عدة أسطح أصغر: +- `availability` — ما إذا كان الحساب مضبوطًا وما إذا كان ينبغي التعامل مع الطلب +- `presentation` — تحويل نموذج عرض الموافقة المشترك إلى حمولات أصلية معلقة/محسومة/منتهية أو إجراءات نهائية +- `transport` — تجهيز الأهداف وإرسال/تحديث/حذف رسائل الموافقة الأصلية +- `interactions` — خطافات bind/unbind/clear-action اختيارية للأزرار أو التفاعلات الأصلية +- `observe` — خطافات اختيارية لتشخيصات التسليم +- إذا احتاجت القناة إلى كائنات مملوكة لوقت التشغيل مثل عميل أو رمز أو تطبيق Bolt أو مستقبل webhook، فسجّلها عبر `openclaw/plugin-sdk/channel-runtime-context`. يتيح سجل runtime-context العام للنواة تهيئة معالجات مدفوعة بالقدرات من حالة بدء تشغيل القناة دون إضافة غراء تغليف خاص بالموافقة. +- لا تلجأ إلى `createChannelApprovalHandler` أو `createChannelNativeApprovalRuntime` ذوي المستوى الأدنى إلا عندما لا يكون السطح المدفوع بالقدرات معبّرًا بما يكفي بعد. +- يجب على قنوات الموافقة الأصلية تمرير كل من `accountId` و`approvalKind` عبر هذه المساعدات. يحافظ `accountId` على حصر سياسة الموافقة متعددة الحسابات ضمن حساب البوت الصحيح، ويحافظ `approvalKind` على إتاحة سلوك موافقات exec مقابل الإضافة للقناة دون فروع مضمنة صراحة في النواة. +- أصبحت النواة الآن تملك إشعارات إعادة توجيه الموافقات أيضًا. يجب ألا ترسل إضافات القنوات رسائل متابعة خاصة بها من نوع "تم إرسال الموافقة إلى الرسائل المباشرة / إلى قناة أخرى" من `createChannelNativeApprovalRuntime`؛ بل اعرض بدلًا من ذلك توجيه الأصل + الرسائل المباشرة للموافق عبر مساعدات قدرة الموافقة المشتركة واترك للنواة تجميع عمليات التسليم الفعلية قبل نشر أي إشعار إلى الدردشة المُطلِقة. +- حافظ على نوع معرّف الموافقة المسلَّم من البداية إلى النهاية. يجب ألا + يخمّن العملاء الأصليون أو يعيدوا كتابة توجيه موافقة exec مقابل الإضافة من حالة محلية بالقناة. +- يمكن لأنواع الموافقة المختلفة أن تعرض عمدًا أسطحًا أصلية مختلفة. + الأمثلة المضمّنة الحالية: + - يحتفظ Slack بإتاحة توجيه الموافقة الأصلية لكل من معرّفات exec والإضافة. + - يحتفظ Matrix بالتوجيه نفسه داخل الرسائل المباشرة/القناة وواجهة تفاعل reactions لموافقات exec + والإضافة، مع الاستمرار في السماح لاختلاف المصادقة حسب نوع الموافقة. +- ما يزال `createApproverRestrictedNativeApprovalAdapter` موجودًا كغلاف توافق، لكن التعليمات البرمجية الجديدة يجب أن تفضّل مُنشئ القدرات وأن تعرض `approvalCapability` على الإضافة. -بالنسبة إلى نقاط دخول القنوات الساخنة، فضّل المسارات الفرعية الأضيق وقت التشغيل عندما تحتاج -إلى جزء واحد فقط من هذه المجموعة: +لنقاط دخول القنوات الساخنة، فضّل المسارات الفرعية الأضيق لوقت التشغيل عندما +تحتاج جزءًا واحدًا فقط من هذه العائلة: - `openclaw/plugin-sdk/approval-auth-runtime` - `openclaw/plugin-sdk/approval-client-runtime` - `openclaw/plugin-sdk/approval-delivery-runtime` +- `openclaw/plugin-sdk/approval-gateway-runtime` +- `openclaw/plugin-sdk/approval-handler-adapter-runtime` +- `openclaw/plugin-sdk/approval-handler-runtime` - `openclaw/plugin-sdk/approval-native-runtime` - `openclaw/plugin-sdk/approval-reply-runtime` +- `openclaw/plugin-sdk/channel-runtime-context` وبالمثل، فضّل `openclaw/plugin-sdk/setup-runtime`، و`openclaw/plugin-sdk/setup-adapter-runtime`، @@ -105,88 +121,88 @@ x-i18n: وبالنسبة إلى الإعداد تحديدًا: - يغطي `openclaw/plugin-sdk/setup-runtime` مساعدات الإعداد الآمنة لوقت التشغيل: - محولات رقع الإعداد الآمنة للاستيراد (`createPatchedAccountSetupAdapter`, + محوّلات تصحيح الإعداد الآمنة للاستيراد (`createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, - `createSetupInputPresenceValidator`)، ومخرجات ملاحظات البحث، - و`promptResolvedAllowFrom`، و`splitSetupEntries`، وبناة - proxy الإعداد المفوّض -- يمثّل `openclaw/plugin-sdk/setup-adapter-runtime` - مدخل المحول الضيق الواعي بمتغيرات البيئة لـ `createEnvPatchedAccountSetupAdapter` -- يغطي `openclaw/plugin-sdk/channel-setup` بناة الإعداد ذي التثبيت الاختياري - بالإضافة إلى بعض الأوليات الآمنة للإعداد: - `createOptionalChannelSetupSurface`، و`createOptionalChannelSetupAdapter`، + `createSetupInputPresenceValidator`)، ومخرجات ملاحظات lookup، + و`promptResolvedAllowFrom`، و`splitSetupEntries`، ومنشئات + setup-proxy المفوّضة +- يمثّل `openclaw/plugin-sdk/setup-adapter-runtime` سطح المحوّل + الضيق الواعي بالبيئة لـ `createEnvPatchedAccountSetupAdapter` +- يغطي `openclaw/plugin-sdk/channel-setup` منشئات الإعداد ذات التثبيت الاختياري + بالإضافة إلى بعض العناصر الأولية الآمنة للإعداد: + `createOptionalChannelSetupSurface` و`createOptionalChannelSetupAdapter`، -إذا كانت قناتك تدعم إعدادًا أو مصادقة مدفوعين بمتغيرات البيئة ويجب أن تعرف -تدفقات بدء التشغيل/التهيئة العامة أسماء متغيرات البيئة تلك قبل تحميل وقت التشغيل، -فصرّح بها في manifest الخاص بـ plugin باستخدام `channelEnvVars`. واحتفظ -بـ `envVars` وقت تشغيل القناة أو الثوابت المحلية لنسخة المشغّل فقط. -`createOptionalChannelSetupWizard`، و`DEFAULT_ACCOUNT_ID`، -و`createTopLevelChannelDmPolicy`، و`setSetupChannelEnabled`، و +إذا كانت قناتك تدعم الإعداد أو المصادقة المعتمدين على env وكان ينبغي لتدفقات +البدء/الإعدادات العامة معرفة أسماء env هذه قبل تحميل وقت التشغيل، فصرّح بها في +manifest الإضافة باستخدام `channelEnvVars`. واحتفظ بـ `envVars` الخاصة بوقت تشغيل القناة +أو الثوابت المحلية للنصوص الموجهة للمشغّل فقط. +`createOptionalChannelSetupWizard` و`DEFAULT_ACCOUNT_ID`، +و`createTopLevelChannelDmPolicy` و`setSetupChannelEnabled` و `splitSetupEntries` -- استخدم المدخل الأوسع `openclaw/plugin-sdk/setup` فقط عندما تحتاج أيضًا إلى - مساعدات الإعداد/التهيئة المشتركة الأثقل مثل +- استخدم السطح الأوسع `openclaw/plugin-sdk/setup` فقط عندما تحتاج أيضًا إلى + مساعدات الإعداد/الضبط المشتركة الأثقل مثل `moveSingleAccountChannelSectionToDefaultAccount(...)` -إذا كانت قناتك تريد فقط الإعلان عن "ثبّت هذه plugin أولًا" في أسطح الإعداد، +إذا كانت قناتك تريد فقط الإعلان "ثبّت هذه الإضافة أولًا" في أسطح الإعداد، ففضّل `createOptionalChannelSetupSurface(...)`. يفشل -المحول/المعالج المولدان إغلاقًا على كتابات التهيئة والإنهاء، ويعيدان استخدام -رسالة "التثبيت مطلوب" نفسها عبر التحقق والإنهاء ونسخة روابط المستندات. +المحوّل/المعالج المولّد بطريقة مغلقة عند كتابة الإعدادات والإنهاء، ويعيدان استخدام +رسالة "التثبيت مطلوب" نفسها عبر التحقق والإنهاء ونصوص روابط الوثائق. -وبالنسبة إلى المسارات الساخنة الأخرى للقناة، فضّل المساعدات الضيقة على الأسطح القديمة الأوسع: +لمسارات القنوات الساخنة الأخرى، فضّل المساعدات الضيقة على الأسطح +القديمة الأوسع: - `openclaw/plugin-sdk/account-core`، و`openclaw/plugin-sdk/account-id`، و`openclaw/plugin-sdk/account-resolution`، و - `openclaw/plugin-sdk/account-helpers` للتهيئة متعددة الحسابات + `openclaw/plugin-sdk/account-helpers` من أجل إعدادات الحسابات المتعددة والرجوع إلى الحساب الافتراضي - `openclaw/plugin-sdk/inbound-envelope` و - `openclaw/plugin-sdk/inbound-reply-dispatch` لربط - المسار/الظرف الوارد والتسجيل ثم الإرسال + `openclaw/plugin-sdk/inbound-reply-dispatch` لتوجيه/غلاف الوارد + وربط التسجيل والتوزيع - `openclaw/plugin-sdk/messaging-targets` لتحليل/مطابقة الأهداف - `openclaw/plugin-sdk/outbound-media` و - `openclaw/plugin-sdk/outbound-runtime` لتحميل الوسائط مع - مفوّضي الهوية/الإرسال الصادر -- `openclaw/plugin-sdk/thread-bindings-runtime` لدورة حياة - روابط سلاسل الرسائل وتسجيل المحول -- `openclaw/plugin-sdk/agent-media-payload` فقط عندما يكون - تخطيط حقول حمولة الوكيل/الوسائط القديم لا يزال مطلوبًا -- `openclaw/plugin-sdk/telegram-command-config` لتطبيع - الأوامر المخصصة في Telegram والتحقق من التكرار/التعارض وعقد - تهيئة الأوامر المستقر في fallback + `openclaw/plugin-sdk/outbound-runtime` لتحميل الوسائط بالإضافة إلى + مفوّضات الهوية/الإرسال الصادرة +- `openclaw/plugin-sdk/thread-bindings-runtime` لدورة حياة ربط السلاسل + وتسجيل المحوّلات +- `openclaw/plugin-sdk/agent-media-payload` فقط عندما يكون تخطيط حقل + agent/media القديم ما يزال مطلوبًا +- `openclaw/plugin-sdk/telegram-command-config` من أجل التطبيع والتحقق من التكرارات/التعارضات + الخاصة بأوامر Telegram المخصصة، وعقد إعداد الأوامر المستقر كبديل -يمكن للقنوات التي تعتمد على المصادقة فقط أن تتوقف غالبًا عند المسار الافتراضي: تتعامل النواة مع الموافقات وتعرض plugin فقط إمكانات الصادر/المصادقة. ويجب على قنوات الموافقات الأصلية مثل Matrix وSlack وTelegram ووسائط الدردشة المخصصة استخدام المساعدات الأصلية المشتركة بدلًا من بناء دورة حياة الموافقات الخاصة بها. +يمكن للقنوات الخاصة بالمصادقة فقط عادةً أن تكتفي بالمسار الافتراضي: تتولى النواة الموافقات وتعرض الإضافة فقط قدرات الصادر/المصادقة. أما قنوات الموافقة الأصلية مثل Matrix وSlack وTelegram ووسائط الدردشة المخصصة فينبغي أن تستخدم المساعدات الأصلية المشتركة بدلًا من بناء دورة حياة الموافقة بنفسها. -## سياسة الذكر في الوارد +## سياسة الإشارة الواردة -أبقِ التعامل مع الذكر في الرسائل الواردة مقسّمًا إلى طبقتين: +احرص على فصل التعامل مع الإشارات الواردة إلى طبقتين: -- جمع الأدلة المملوك لـ plugin +- جمع الأدلة المملوك للإضافة - تقييم السياسة المشتركة استخدم `openclaw/plugin-sdk/channel-inbound` للطبقة المشتركة. -ملائم للمنطق المحلي في plugin: +ملائم للمنطق المحلي في الإضافة: -- اكتشاف الرد على الروبوت -- اكتشاف الاقتباس من الروبوت -- فحوصات المشاركة في سلسلة الرسائل +- اكتشاف الرد على البوت +- اكتشاف الاقتباس من البوت +- فحوص مشاركة السلسلة - استبعاد رسائل الخدمة/النظام -- الذاكرات المخبئية الأصلية للمنصة اللازمة لإثبات مشاركة الروبوت +- الذاكرات المؤقتة الأصلية للمنصة اللازمة لإثبات مشاركة البوت ملائم للمساعد المشترك: - `requireMention` -- نتيجة الذكر الصريح -- allowlist الذكر الضمني +- نتيجة الإشارة الصريحة +- قائمة السماح الخاصة بالإشارة الضمنية - تجاوز الأوامر - قرار التخطي النهائي التدفق المفضل: -1. احسب حقائق الذكر المحلية. -2. مرر هذه الحقائق إلى `resolveInboundMentionDecision({ facts, policy })`. -3. استخدم `decision.effectiveWasMentioned` و`decision.shouldBypassMention` و`decision.shouldSkip` في بوابة الوارد. +1. احسب حقائق الإشارة المحلية. +2. مرّر هذه الحقائق إلى `resolveInboundMentionDecision({ facts, policy })`. +3. استخدم `decision.effectiveWasMentioned` و`decision.shouldBypassMention` و`decision.shouldSkip` في بوابة الوارد لديك. ```typescript import { @@ -225,8 +241,8 @@ const decision = resolveInboundMentionDecision({ if (decision.shouldSkip) return; ``` -يكشف `api.runtime.channel.mentions` عن مساعدات الذكر المشتركة نفسها من أجل -plugins القنوات المضمّنة التي تعتمد بالفعل على حقن وقت التشغيل: +يكشف `api.runtime.channel.mentions` عن مساعدات الإشارة المشتركة نفسها +لإضافات القنوات المضمّنة التي تعتمد بالفعل على حقن وقت التشغيل: - `buildMentionRegexes` - `matchesMentionPatterns` @@ -234,18 +250,18 @@ plugins القنوات المضمّنة التي تعتمد بالفعل على - `implicitMentionKindWhen` - `resolveInboundMentionDecision` -تبقى المساعدات الأقدم `resolveMentionGating*` على -`openclaw/plugin-sdk/channel-inbound` كتصديرات توافق فقط. ويجب أن تستخدم الشيفرة الجديدة -`resolveInboundMentionDecision({ facts, policy })`. +تبقى مساعدات `resolveMentionGating*` الأقدم على +`openclaw/plugin-sdk/channel-inbound` كتصديرات توافق فقط. ويجب على +التعليمات البرمجية الجديدة استخدام `resolveInboundMentionDecision({ facts, policy })`. -## الشرح العملي +## شرح عملي - أنشئ ملفات plugin القياسية. الحقل `channel` في `package.json` هو - ما يجعل هذه plugin قناة. وللاطلاع على سطح بيانات تعريف الحزمة الكامل، - راجع [إعداد plugin والتهيئة](/ar/plugins/sdk-setup#openclawchannel): + أنشئ ملفات الإضافة القياسية. إن حقل `channel` في `package.json` هو + ما يجعل هذه إضافة قناة. وللاطلاع على سطح بيانات تعريف الحزمة الكامل، + راجع [إعداد الإضافة والضبط](/ar/plugins/sdk-setup#openclawchannel): ```json package.json @@ -294,9 +310,9 @@ plugins القنوات المضمّنة التي تعتمد بالفعل على - - تحتوي الواجهة `ChannelPlugin` على العديد من أسطح المحولات الاختيارية. ابدأ - بالحد الأدنى — `id` و`setup` — ثم أضف المحولات عند الحاجة. + + تحتوي الواجهة `ChannelPlugin` على العديد من أسطح المحوّلات الاختيارية. ابدأ + بالحد الأدنى — `id` و`setup` — وأضف المحوّلات حسب الحاجة. أنشئ `src/channel.ts`: @@ -306,7 +322,7 @@ plugins القنوات المضمّنة التي تعتمد بالفعل على createChannelPluginBase, } from "openclaw/plugin-sdk/channel-core"; import type { OpenClawConfig } from "openclaw/plugin-sdk/channel-core"; - import { acmeChatApi } from "./client.js"; // عميل API الخاص بمنصتك + import { acmeChatApi } from "./client.js"; // your platform API client type ResolvedAccount = { accountId: string | null; @@ -347,7 +363,7 @@ plugins القنوات المضمّنة التي تعتمد بالفعل على }, }), - // أمان الرسائل الخاصة: من يمكنه مراسلة الروبوت + // DM security: who can message the bot security: { dm: { channelKey: "acme-chat", @@ -357,7 +373,7 @@ plugins القنوات المضمّنة التي تعتمد بالفعل على }, }, - // Pairing: تدفق الاعتماد لجهات الاتصال الجديدة في الرسائل الخاصة + // Pairing: approval flow for new DM contacts pairing: { text: { idLabel: "Acme Chat username", @@ -368,10 +384,10 @@ plugins القنوات المضمّنة التي تعتمد بالفعل على }, }, - // الترابط في السلاسل: كيفية تسليم الردود + // Threading: how replies are delivered threading: { topLevelReplyToMode: "reply" }, - // الصادر: إرسال الرسائل إلى المنصة + // Outbound: send messages to the platform outbound: { attachedResults: { sendText: async (params) => { @@ -391,24 +407,24 @@ plugins القنوات المضمّنة التي تعتمد بالفعل على }); ``` - - بدلًا من تنفيذ واجهات المحولات منخفضة المستوى يدويًا، تمرر - خيارات تصريحية ويقوم الباني بتركيبها: + + بدلًا من تنفيذ واجهات المحوّلات منخفضة المستوى يدويًا، تمرّر + خيارات تصريحية ويقوم المنشئ بتركيبها: | الخيار | ما الذي يربطه | | --- | --- | - | `security.dm` | محلّل أمان الرسائل الخاصة ضمن النطاق من حقول التهيئة | - | `pairing.text` | تدفق pairing للرسائل الخاصة المعتمد على النص مع تبادل الرموز | - | `threading` | محلّل وضع الرد (ثابت، أو ضمن نطاق الحساب، أو مخصص) | - | `outbound.attachedResults` | دوال الإرسال التي تعيد بيانات تعريف النتيجة (معرّفات الرسائل) | + | `security.dm` | محلّل أمان DM مقيّد من حقول الإعداد | + | `pairing.text` | تدفق اقتران DM قائم على النص مع تبادل الرموز | + | `threading` | محلّل وضع reply-to (ثابت، أو مقيد بالحساب، أو مخصص) | + | `outbound.attachedResults` | دوال الإرسال التي ترجع بيانات تعريف النتيجة (معرّفات الرسائل) | - يمكنك أيضًا تمرير كائنات محولات خام بدلًا من الخيارات التصريحية + يمكنك أيضًا تمرير كائنات محوّلات خام بدلًا من الخيارات التصريحية إذا كنت تحتاج إلى تحكم كامل. - + أنشئ `index.ts`: ```typescript index.ts @@ -446,20 +462,20 @@ plugins القنوات المضمّنة التي تعتمد بالفعل على ضع واصفات CLI المملوكة للقناة في `registerCliMetadata(...)` حتى يتمكن OpenClaw من عرضها في المساعدة الجذرية دون تفعيل وقت تشغيل القناة الكامل، - بينما تلتقط عمليات التحميل الكاملة العادية الواصفات نفسها لتسجيل الأوامر - الفعلي. واحتفظ بـ `registerFull(...)` للأعمال الخاصة بوقت التشغيل فقط. - إذا كان `registerFull(...)` يسجل أساليب RPC للبوابة، فاستخدم - بادئة خاصة بـ plugin. تبقى نطاقات الإدارة الأساسية (`config.*`، - و`exec.approvals.*`، و`wizard.*`، و`update.*`) محجوزة وتُحل دائمًا - إلى `operator.admin`. - يتعامل `defineChannelPluginEntry` مع تقسيم أوضاع التسجيل تلقائيًا. راجع - [نقاط الدخول](/ar/plugins/sdk-entrypoints#definechannelpluginentry) لكل + بينما تلتقط التحميلات الكاملة العادية الواصفات نفسها لتسجيل الأوامر الفعلي. + واحتفظ بـ `registerFull(...)` للعمل الخاص بوقت التشغيل فقط. + إذا كان `registerFull(...)` يسجّل طرائق Gateway RPC، فاستخدم + بادئة خاصة بالإضافة. تظل مساحات أسماء إدارة النواة (`config.*`، + و`exec.approvals.*`، و`wizard.*`، و`update.*`) محجوزة وتُحل دائمًا إلى + `operator.admin`. + يعالج `defineChannelPluginEntry` تقسيم وضع التسجيل تلقائيًا. راجع + [نقاط الدخول](/ar/plugins/sdk-entrypoints#definechannelpluginentry) للاطلاع على جميع الخيارات. - أنشئ `setup-entry.ts` للتحميل الخفيف أثناء onboarding: + أنشئ `setup-entry.ts` للتحميل الخفيف أثناء الإعداد الأولي: ```typescript setup-entry.ts import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core"; @@ -469,27 +485,27 @@ plugins القنوات المضمّنة التي تعتمد بالفعل على ``` يحمّل OpenClaw هذا بدلًا من نقطة الدخول الكاملة عندما تكون القناة معطلة - أو غير مهيأة. وهو يتجنب سحب شيفرة وقت تشغيل ثقيلة أثناء تدفقات الإعداد. - راجع [الإعداد والتهيئة](/ar/plugins/sdk-setup#setup-entry) للتفاصيل. + أو غير مضبوطة. وهذا يتجنب سحب تعليمات وقت تشغيل ثقيلة أثناء تدفقات الإعداد. + راجع [الإعداد والضبط](/ar/plugins/sdk-setup#setup-entry) للتفاصيل. - تحتاج plugin الخاصة بك إلى تلقي الرسائل من المنصة وإعادة توجيهها إلى + تحتاج إضافتك إلى استقبال الرسائل من المنصة وتمريرها إلى OpenClaw. النمط المعتاد هو webhook يتحقق من الطلب - ويرسله عبر معالج الوارد الخاص بقناتك: + ويوزعه عبر معالج الوارد الخاص بقناتك: ```typescript registerFull(api) { api.registerHttpRoute({ path: "/acme-chat/webhook", - auth: "plugin", // مصادقة مُدارة بواسطة plugin (تحقق من التواقيع بنفسك) + auth: "plugin", // plugin-managed auth (verify signatures yourself) handler: async (req, res) => { const event = parseWebhookPayload(req); - // يقوم معالج الوارد لديك بإرسال الرسالة إلى OpenClaw. - // يعتمد الربط الدقيق على SDK الخاصة بمنصتك — - // راجع مثالًا حقيقيًا في حزمة plugin Microsoft Teams أو Google Chat المضمّنة. + // Your inbound handler dispatches the message to OpenClaw. + // The exact wiring depends on your platform SDK — + // see a real example in the bundled Microsoft Teams or Google Chat plugin package. await handleAcmeChatInbound(api, event); res.statusCode = 200; @@ -501,16 +517,16 @@ plugins القنوات المضمّنة التي تعتمد بالفعل على ``` - التعامل مع الرسائل الواردة خاص بالقناة. كل plugin قناة تمتلك - مسار الوارد الخاص بها. انظر إلى plugins القنوات المضمّنة - (مثل حزمة plugin Microsoft Teams أو Google Chat) للاطلاع على أنماط حقيقية. + التعامل مع الرسائل الواردة خاص بالقناة. كل إضافة قناة تملك + مسار الوارد الخاص بها. انظر إلى إضافات القنوات المضمّنة + (مثل حزمة إضافة Microsoft Teams أو Google Chat) للاطلاع على أنماط حقيقية. -اكتب اختبارات موضوعة بجانب الشيفرة في `src/channel.test.ts`: +اكتب اختبارات متجاورة في `src/channel.test.ts`: ```typescript src/channel.test.ts import { describe, it, expect } from "vitest"; @@ -548,7 +564,7 @@ plugins القنوات المضمّنة التي تعتمد بالفعل على pnpm test -- /acme-chat/ ``` - وبالنسبة إلى مساعدات الاختبار المشتركة، راجع [الاختبار](/ar/plugins/sdk-testing). + للاطلاع على مساعدات الاختبار المشتركة، راجع [الاختبار](/ar/plugins/sdk-testing). @@ -557,46 +573,46 @@ plugins القنوات المضمّنة التي تعتمد بالفعل على ``` /acme-chat/ -├── package.json # بيانات تعريف openclaw.channel -├── openclaw.plugin.json # Manifest مع مخطط التهيئة +├── package.json # openclaw.channel metadata +├── openclaw.plugin.json # Manifest with config schema ├── index.ts # defineChannelPluginEntry ├── setup-entry.ts # defineSetupPluginEntry -├── api.ts # التصديرات العامة (اختياري) -├── runtime-api.ts # تصديرات وقت التشغيل الداخلية (اختياري) +├── api.ts # Public exports (optional) +├── runtime-api.ts # Internal runtime exports (optional) └── src/ - ├── channel.ts # ChannelPlugin عبر createChatChannelPlugin - ├── channel.test.ts # الاختبارات - ├── client.ts # عميل API الخاص بالمنصة - └── runtime.ts # مخزن وقت التشغيل (إذا لزم) + ├── channel.ts # ChannelPlugin via createChatChannelPlugin + ├── channel.test.ts # Tests + ├── client.ts # Platform API client + └── runtime.ts # Runtime store (if needed) ``` ## موضوعات متقدمة - - أوضاع رد ثابتة، أو ضمن نطاق الحساب، أو مخصصة + + أوضاع reply ثابتة أو مقيّدة بالحساب أو مخصصة describeMessageTool واكتشاف الإجراءات - + inferTargetChatType وlooksLikeId وresolveTarget - TTS وSTT والوسائط وsubagent عبر api.runtime + TTS وSTT والوسائط والوكيل الفرعي عبر api.runtime -لا تزال بعض المداخل المساعدة المضمّنة موجودة لصيانة plugins المضمّنة -والتوافق. وهي ليست النمط الموصى به لـ plugins القنوات الجديدة؛ +لا تزال بعض أسطح المساعدات المضمّنة موجودة لصيانة الإضافات المضمّنة +وللتوافق. وهي ليست النمط الموصى به لإضافات القنوات الجديدة؛ فضّل المسارات الفرعية العامة للقناة/الإعداد/الرد/وقت التشغيل من سطح SDK -المشترك ما لم تكن تصون عائلة plugin المضمّنة تلك مباشرة. +المشترك ما لم تكن تصون عائلة تلك الإضافات المضمّنة مباشرة. ## الخطوات التالية -- [Provider Plugins](/ar/plugins/sdk-provider-plugins) — إذا كانت plugin الخاصة بك توفر النماذج أيضًا -- [نظرة عامة على SDK](/ar/plugins/sdk-overview) — المرجع الكامل لاستيرادات المسارات الفرعية +- [إضافات المزوّد](/ar/plugins/sdk-provider-plugins) — إذا كانت إضافتك توفّر أيضًا نماذج +- [نظرة عامة على SDK](/ar/plugins/sdk-overview) — مرجع كامل لواردات المسارات الفرعية - [اختبار SDK](/ar/plugins/sdk-testing) — أدوات الاختبار واختبارات العقود -- [Manifest الخاص بـ plugin](/ar/plugins/manifest) — مخطط manifest الكامل +- [Manifest الإضافة](/ar/plugins/manifest) — مخطط manifest الكامل diff --git a/docs/ar/plugins/sdk-migration.md b/docs/ar/plugins/sdk-migration.md index d225cc90d..09a491272 100644 --- a/docs/ar/plugins/sdk-migration.md +++ b/docs/ar/plugins/sdk-migration.md @@ -1,107 +1,130 @@ --- read_when: - - ترى التحذير OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED - - ترى التحذير OPENCLAW_EXTENSION_API_DEPRECATED - - أنت تحدّث إضافة إلى بنية الإضافات الحديثة + - أنت ترى التحذير OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED + - أنت ترى التحذير OPENCLAW_EXTENSION_API_DEPRECATED + - أنت تقوم بتحديث إضافة إلى معمارية الإضافات الحديثة - أنت تصون إضافة OpenClaw خارجية sidebarTitle: Migrate to SDK -summary: الانتقال من طبقة التوافق العكسي القديمة إلى plugin SDK الحديث +summary: الانتقال من طبقة التوافق العكسي القديمة إلى Plugin SDK الحديثة title: ترحيل Plugin SDK x-i18n: - generated_at: "2026-04-07T07:20:37Z" + generated_at: "2026-04-08T02:18:21Z" model: gpt-5.4 provider: openai - source_hash: 3691060e9dc00ca8bee49240a047f0479398691bd14fb96e9204cc9243fdb32c + source_hash: 155a8b14bc345319c8516ebdb8a0ccdea2c5f7fa07dad343442996daee21ecad source_path: plugins/sdk-migration.md workflow: 15 --- # ترحيل Plugin SDK -انتقل OpenClaw من طبقة توافق عكسي واسعة إلى بنية إضافات حديثة ذات عمليات -استيراد مركزة وموثقة. إذا كانت إضافتك قد بُنيت قبل البنية الجديدة، فسيساعدك -هذا الدليل على ترحيلها. +انتقل OpenClaw من طبقة توافق عكسي واسعة إلى معمارية إضافات حديثة +ذات عمليات استيراد مركزة وموثقة. إذا كانت إضافتك قد بُنيت قبل +المعمارية الجديدة، فسيساعدك هذا الدليل على الترحيل. ## ما الذي يتغير -كان نظام الإضافات القديم يوفر سطحين مفتوحين على مصراعيهما يتيحان للإضافات -استيراد أي شيء تحتاجه من نقطة دخول واحدة: +كان نظام الإضافات القديم يوفر سطحين واسعين ومفتوحين يتيحان للإضافات استيراد +أي شيء تحتاج إليه من نقطة دخول واحدة: -- **`openclaw/plugin-sdk/compat`** — استيراد واحد يعيد تصدير عشرات من - المساعدات. وقد تم تقديمه لإبقاء الإضافات القديمة المعتمدة على hooks عاملة - أثناء بناء بنية الإضافات الجديدة. -- **`openclaw/extension-api`** — جسر منح الإضافات وصولًا مباشرًا إلى - المساعدات على جانب المضيف مثل مشغّل الوكيل المضمّن. +- **`openclaw/plugin-sdk/compat`** — استيراد واحد يعيد تصدير عشرات + الأدوات المساعدة. وقد تم تقديمه لإبقاء الإضافات الأقدم المعتمدة على الخطافات تعمل بينما + كانت معمارية الإضافات الجديدة قيد الإنشاء. +- **`openclaw/extension-api`** — جسر يمنح الإضافات وصولًا مباشرًا إلى + أدوات جانب المضيف مثل مشغّل الوكيل المضمن. -كلا السطحين الآن **مهملان**. لا يزالان يعملان في وقت التشغيل، لكن يجب ألا -تستخدمهما الإضافات الجديدة، ويجب أن ترحّل الإضافات الحالية قبل أن تزيلهما -النسخة الرئيسية التالية. +كلا السطحين أصبح الآن **مهملًا**. ما زالا يعملان في وقت التشغيل، لكن +يجب ألا تستخدمهما الإضافات الجديدة، وينبغي أن تهاجر الإضافات الحالية قبل أن تزيلهما +الإصدار الرئيسي التالي. - ستتم إزالة طبقة التوافق العكسي في إصدار رئيسي مستقبلي. - الإضافات التي لا تزال تستورد من هذه الأسطح ستتعطل عند حدوث ذلك. + ستُزال طبقة التوافق العكسي في إصدار رئيسي مستقبلي. + وستتعطل الإضافات التي ما تزال تستورد من هذه الأسطح عند حدوث ذلك. -## لماذا تغير هذا +## لماذا تغيّر هذا تسبب النهج القديم في مشكلات: -- **بدء تشغيل بطيء** — كان استيراد مساعد واحد يحمّل عشرات الوحدات غير - المرتبطة -- **اعتماديات دائرية** — جعلت إعادة التصدير الواسعة من السهل إنشاء دورات - استيراد -- **سطح API غير واضح** — لم تكن هناك طريقة لمعرفة أي التصديرات مستقرة - وأيها داخلية +- **بدء تشغيل بطيء** — كان استيراد أداة مساعدة واحدة يحمّل عشرات الوحدات غير المرتبطة +- **تبعيات دائرية** — جعلت إعادة التصدير الواسعة من السهل إنشاء دورات استيراد +- **سطح API غير واضح** — لم تكن هناك طريقة لمعرفة أي التصديرات مستقرة وأيها داخلية -يصلح plugin SDK الحديث هذا: كل مسار استيراد (`openclaw/plugin-sdk/\`) -هو وحدة صغيرة مكتفية ذاتيًا ذات غرض واضح وعقد موثق. +تصلح Plugin SDK الحديثة هذا: كل مسار استيراد (`openclaw/plugin-sdk/\`) +هو وحدة صغيرة مستقلة بذاتها ذات غرض واضح وعقد موثق. -كما أزيلت أيضًا فواصل الراحة القديمة الخاصة بالمزوّدين للقنوات المضمّنة. -فالاستيرادات مثل `openclaw/plugin-sdk/slack` و`openclaw/plugin-sdk/discord` و -`openclaw/plugin-sdk/signal` و`openclaw/plugin-sdk/whatsapp`، -وفواصل المساعدات ذات العلامات الخاصة بالقنوات، و -`openclaw/plugin-sdk/telegram-core` كانت اختصارات خاصة بالمستودع الأحادي، -وليست عقود إضافات مستقرة. استخدم بدلًا من ذلك مسارات SDK عامة ضيقة. داخل -workspace الإضافات المضمّنة، أبقِ المساعدات المملوكة للمزوّد في `api.ts` -أو `runtime-api.ts` الخاصين بتلك الإضافة. +كما أُزيلت أيضًا طبقات الراحة القديمة لموفري القنوات المجمعة. فالاستيرادات +مثل `openclaw/plugin-sdk/slack` و`openclaw/plugin-sdk/discord`، +و`openclaw/plugin-sdk/signal` و`openclaw/plugin-sdk/whatsapp`، +وطبقات الأدوات المساعدة الموسومة بالقناة، و +`openclaw/plugin-sdk/telegram-core` كانت اختصارات داخلية خاصة بالمستودع الأحادي، وليست +عقود إضافات مستقرة. استخدم بدلًا منها المسارات الفرعية العامة الضيقة في SDK. وداخل +مساحة عمل الإضافات المجمعة، احتفظ بالأدوات المساعدة المملوكة للموفر في +`api.ts` أو `runtime-api.ts` الخاصين بتلك الإضافة. -أمثلة المزوّدات المضمّنة الحالية: +أمثلة موفّرين مجمّعين حالية: -- تحتفظ Anthropic بمساعدات البث الخاصة بـ Claude في الفاصل الخاص بها - `api.ts` / `contract-api.ts` -- تحتفظ OpenAI بمنشئات المزوّد، ومساعدات النموذج الافتراضي، ومنشئات المزوّد - الفوري في `api.ts` الخاص بها -- تحتفظ OpenRouter بمنشئ المزوّد ومساعدات onboarding/config في - `api.ts` الخاص بها +- يحتفظ Anthropic بأدوات مساعدة البث الخاصة بـ Claude في طبقة + `api.ts` / `contract-api.ts` الخاصة به +- يحتفظ OpenAI ببناة الموفر، وأدوات مساعدة النموذج الافتراضي، وبناة + الموفّر الآني في `api.ts` الخاص به +- يحتفظ OpenRouter بباني الموفر وأدوات مساعدة التهيئة/الإعداد في + `api.ts` الخاص به ## كيفية الترحيل - - إذا كانت إضافتك تستخدم `openclaw/plugin-sdk/windows-spawn`، فإن أغلفة - Windows من نوع `.cmd`/`.bat` غير المحلولة تفشل الآن بشكل مغلق ما لم تمرّر + + تعرض إضافات القنوات القادرة على الموافقة الآن سلوك الموافقة الأصلي من خلال + `approvalCapability.nativeRuntime` بالإضافة إلى سجل سياق وقت التشغيل المشترك. + + التغييرات الأساسية: + + - استبدل `approvalCapability.handler.loadRuntime(...)` بـ + `approvalCapability.nativeRuntime` + - انقل المصادقة/التسليم الخاصة بالموافقة من البنية القديمة `plugin.auth` / + `plugin.approvals` إلى `approvalCapability` + - تمت إزالة `ChannelPlugin.approvals` من عقد + الإضافات العامة للقنوات؛ انقل حقول التسليم/الأصلية/العرض إلى `approvalCapability` + - يظل `plugin.auth` مخصصًا فقط لتدفقات تسجيل الدخول/الخروج الخاصة بالقناة؛ أما خطافات + مصادقة الموافقة فيه فلم تعد تُقرأ من النواة + - سجّل كائنات وقت التشغيل المملوكة للقناة، مثل العملاء أو الرموز أو تطبيقات + Bolt، عبر `openclaw/plugin-sdk/channel-runtime-context` + - لا ترسل إشعارات إعادة توجيه مملوكة للإضافة من معالجات الموافقة الأصلية؛ + فالنواة تمتلك الآن إشعارات "تم التوجيه إلى مكان آخر" المستندة إلى نتائج التسليم الفعلية + - عند تمرير `channelRuntime` إلى `createChannelManager(...)`، وفّر + سطح `createPluginRuntime().channel` حقيقيًا. يتم رفض القوالب الجزئية. + + راجع `/plugins/sdk-channel-plugins` للاطلاع على التخطيط الحالي + لقدرة الموافقة. + + + + + إذا كانت إضافتك تستخدم `openclaw/plugin-sdk/windows-spawn`، + فإن ملفات `.cmd`/`.bat` غير المحلولة في Windows تفشل الآن بشكل مغلق ما لم تمرر صراحةً `allowShellFallback: true`. ```typescript - // Before + // قبل const program = applyWindowsSpawnProgramPolicy({ candidate }); - // After + // بعد const program = applyWindowsSpawnProgramPolicy({ candidate, - // Only set this for trusted compatibility callers that intentionally - // accept shell-mediated fallback. + // اضبط هذا فقط للمتصلين المتوافقين الموثوقين الذين يقبلون عمدًا + // الرجوع الاحتياطي عبر الصدفة. allowShellFallback: true, }); ``` - إذا لم يكن المستدعي لديك يعتمد عمدًا على الرجوع الاحتياطي عبر shell، فلا - تضبط `allowShellFallback` وتعامل مع الخطأ المطروح بدلًا من ذلك. + إذا لم يكن المتصل لديك يعتمد عمدًا على الرجوع الاحتياطي عبر الصدفة، فلا تضبط + `allowShellFallback` وتعامل مع الخطأ المطروح بدلًا من ذلك. - - ابحث في إضافتك عن عمليات استيراد من أي من السطحين المهملين: + + ابحث في إضافتك عن الاستيرادات من أي من السطحين المهملين: ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -110,38 +133,38 @@ workspace الإضافات المضمّنة، أبقِ المساعدات الم - - يطابق كل تصدير من السطح القديم مسار استيراد حديثًا محددًا: + + يرتبط كل تصدير من السطح القديم بمسار استيراد حديث محدد: ```typescript - // Before (deprecated backwards-compatibility layer) + // قبل (طبقة توافق عكسي مهملة) import { createChannelReplyPipeline, createPluginRuntimeStore, resolveControlCommandGate, } from "openclaw/plugin-sdk/compat"; - // After (modern focused imports) + // بعد (استيرادات حديثة ومركزة) import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline"; import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth"; ``` - بالنسبة إلى المساعدات على جانب المضيف، استخدم وقت تشغيل الإضافة المحقون - بدلًا من الاستيراد المباشر: + بالنسبة إلى أدوات جانب المضيف، استخدم وقت تشغيل الإضافة المحقون بدلًا من الاستيراد + المباشر: ```typescript - // Before (deprecated extension-api bridge) + // قبل (جسر extension-api مهمل) import { runEmbeddedPiAgent } from "openclaw/extension-api"; const result = await runEmbeddedPiAgent({ sessionId, prompt }); - // After (injected runtime) + // بعد (وقت تشغيل محقون) const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt }); ``` - ينطبق النمط نفسه على مساعدات الجسر القديمة الأخرى: + ينطبق النمط نفسه على أدوات الجسر القديمة الأخرى: - | الاستيراد القديم | المكافئ الحديث | + | الاستيراد القديم | البديل الحديث | | --- | --- | | `resolveAgentDir` | `api.runtime.agent.resolveAgentDir` | | `resolveAgentWorkspaceDir` | `api.runtime.agent.resolveAgentWorkspaceDir` | @@ -149,11 +172,11 @@ workspace الإضافات المضمّنة، أبقِ المساعدات الم | `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` | | `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` | | `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` | - | مساعدات مخزن الجلسات | `api.runtime.agent.session.*` | + | أدوات مساعدة مخزن الجلسات | `api.runtime.agent.session.*` | - + ```bash pnpm build pnpm test -- my-plugin/ @@ -161,202 +184,207 @@ workspace الإضافات المضمّنة، أبقِ المساعدات الم -## مرجع مسار الاستيراد +## مرجع مسارات الاستيراد | مسار الاستيراد | الغرض | التصديرات الأساسية | | --- | --- | --- | - | `plugin-sdk/plugin-entry` | مساعد نقطة دخول الإضافة القانوني | `definePluginEntry` | - | `plugin-sdk/core` | إعادة تصدير قديمة جامعة لتعريفات/منشئات إدخال القنوات | `defineChannelPluginEntry`, `createChatChannelPlugin` | - | `plugin-sdk/config-schema` | تصدير مخطط الإعدادات الجذري | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | مساعد إدخال مزوّد واحد | `defineSingleProviderPluginEntry` | - | `plugin-sdk/channel-core` | تعريفات ومنشئات إدخال قنوات مركزة | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | مساعدات معالج الإعداد المشتركة | مطالبات قائمة السماح، ومنشئات حالة الإعداد | - | `plugin-sdk/setup-runtime` | مساعدات وقت تشغيل الإعداد | محولات تصحيح الإعداد الآمنة للاستيراد، ومساعدات ملاحظات البحث، و`promptResolvedAllowFrom`، و`splitSetupEntries`، ووكلاء الإعداد المفوضون | - | `plugin-sdk/setup-adapter-runtime` | مساعدات محول الإعداد | `createEnvPatchedAccountSetupAdapter` | - | `plugin-sdk/setup-tools` | مساعدات أدوات الإعداد | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | مساعدات الحسابات المتعددة | مساعدات قائمة الحسابات/الإعدادات/بوابة الإجراءات | - | `plugin-sdk/account-id` | مساعدات معرّف الحساب | `DEFAULT_ACCOUNT_ID`، وتطبيع معرّف الحساب | - | `plugin-sdk/account-resolution` | مساعدات البحث عن الحساب | مساعدات البحث عن الحساب + الرجوع الاحتياطي الافتراضي | - | `plugin-sdk/account-helpers` | مساعدات حساب ضيقة | مساعدات قائمة الحسابات/إجراءات الحساب | - | `plugin-sdk/channel-setup` | محولات معالج الإعداد | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`، بالإضافة إلى `DEFAULT_ACCOUNT_ID` و`createTopLevelChannelDmPolicy` و`setSetupChannelEnabled` و`splitSetupEntries` | - | `plugin-sdk/channel-pairing` | أساسيات الاقتران عبر DM | `createChannelPairingController` | - | `plugin-sdk/channel-reply-pipeline` | توصيل بادئة الرد + الكتابة | `createChannelReplyPipeline` | - | `plugin-sdk/channel-config-helpers` | مصانع محولات الإعدادات | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | منشئات مخطط الإعدادات | أنواع مخطط إعدادات القناة | - | `plugin-sdk/telegram-command-config` | مساعدات إعداد أوامر Telegram | تطبيع أسماء الأوامر، وتشذيب الوصف، والتحقق من التكرار/التعارض | - | `plugin-sdk/channel-policy` | حل سياسات المجموعات/DM | `resolveChannelGroupRequireMention` | + | `plugin-sdk/plugin-entry` | أداة مساعد إدخال الإضافة القياسية | `definePluginEntry` | + | `plugin-sdk/core` | إعادة تصدير جامعة قديمة لتعريفات/بناة إدخال القنوات | `defineChannelPluginEntry`, `createChatChannelPlugin` | + | `plugin-sdk/config-schema` | تصدير مخطط التكوين الجذري | `OpenClawSchema` | + | `plugin-sdk/provider-entry` | أداة مساعد إدخال موفر واحد | `defineSingleProviderPluginEntry` | + | `plugin-sdk/channel-core` | تعريفات وبناة إدخال القنوات المركزة | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | + | `plugin-sdk/setup` | أدوات مساعدة مشتركة لمعالج الإعداد | مطالبات قائمة السماح، وبناة حالة الإعداد | + | `plugin-sdk/setup-runtime` | أدوات مساعدة وقت تشغيل الإعداد | مهايئات تصحيح الإعداد الآمنة للاستيراد، وأدوات مساعدة ملاحظات البحث، و`promptResolvedAllowFrom` و`splitSetupEntries` ووكلاء الإعداد المفوضون | + | `plugin-sdk/setup-adapter-runtime` | أدوات مساعدة لمهايئات الإعداد | `createEnvPatchedAccountSetupAdapter` | + | `plugin-sdk/setup-tools` | أدوات مساعدة لأدوات الإعداد | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | + | `plugin-sdk/account-core` | أدوات مساعدة متعددة الحسابات | أدوات مساعدة قائمة الحسابات/التكوين/بوابة الإجراءات | + | `plugin-sdk/account-id` | أدوات مساعدة لمعرّف الحساب | `DEFAULT_ACCOUNT_ID`، وتطبيع معرّف الحساب | + | `plugin-sdk/account-resolution` | أدوات مساعدة للبحث عن الحساب | أدوات مساعدة للبحث عن الحساب + الرجوع الافتراضي | + | `plugin-sdk/account-helpers` | أدوات مساعدة ضيقة للحساب | أدوات مساعدة قائمة الحسابات/إجراءات الحساب | + | `plugin-sdk/channel-setup` | مهايئات معالج الإعداد | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`، بالإضافة إلى `DEFAULT_ACCOUNT_ID` و`createTopLevelChannelDmPolicy` و`setSetupChannelEnabled` و`splitSetupEntries` | + | `plugin-sdk/channel-pairing` | بدائيات إقران الرسائل الخاصة | `createChannelPairingController` | + | `plugin-sdk/channel-reply-pipeline` | أسلاك بادئة الرد وحالة الكتابة | `createChannelReplyPipeline` | + | `plugin-sdk/channel-config-helpers` | مصانع مهايئات التكوين | `createHybridChannelConfigAdapter` | + | `plugin-sdk/channel-config-schema` | بناة مخطط التكوين | أنواع مخطط تكوين القناة | + | `plugin-sdk/telegram-command-config` | أدوات مساعدة لتكوين أوامر Telegram | تطبيع أسماء الأوامر، وتشذيب الوصف، والتحقق من التكرار/التعارض | + | `plugin-sdk/channel-policy` | حل سياسات المجموعات/الرسائل الخاصة | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | تتبع حالة الحساب | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | مساعدات الظرف الوارد | مساعدات المسار المشترك + منشئ الظرف | - | `plugin-sdk/inbound-reply-dispatch` | مساعدات الرد الوارد | مساعدات التسجيل والإرسال المشتركة | - | `plugin-sdk/messaging-targets` | تحليل أهداف المراسلة | مساعدات تحليل/مطابقة الأهداف | - | `plugin-sdk/outbound-media` | مساعدات الوسائط الصادرة | تحميل الوسائط الصادرة المشتركة | - | `plugin-sdk/outbound-runtime` | مساعدات وقت التشغيل الصادر | مساعدات الهوية الصادرة/التفويض بالإرسال | - | `plugin-sdk/thread-bindings-runtime` | مساعدات ربط السلاسل | دورة حياة ربط السلاسل ومساعدات المحول | - | `plugin-sdk/agent-media-payload` | مساعدات حمولة الوسائط القديمة | منشئ حمولة وسائط الوكيل لتخطيطات الحقول القديمة | - | `plugin-sdk/channel-runtime` | حشوة توافق مهملة | أدوات وقت تشغيل القنوات القديمة فقط | + | `plugin-sdk/inbound-envelope` | أدوات مساعدة لأغلفة الوارد | أدوات مساعدة مشتركة للمسارات وبناء الأظرف | + | `plugin-sdk/inbound-reply-dispatch` | أدوات مساعدة لردود الوارد | أدوات مساعدة مشتركة للتسجيل والإرسال | + | `plugin-sdk/messaging-targets` | تحليل أهداف المراسلة | أدوات مساعدة لتحليل/مطابقة الأهداف | + | `plugin-sdk/outbound-media` | أدوات مساعدة للوسائط الصادرة | تحميل الوسائط الصادرة المشتركة | + | `plugin-sdk/outbound-runtime` | أدوات مساعدة لوقت التشغيل الصادر | أدوات مساعدة لهوية الإرسال/وكيل الإرسال | + | `plugin-sdk/thread-bindings-runtime` | أدوات مساعدة لربط السلاسل | دورة حياة ربط السلاسل وأدوات المهايئات | + | `plugin-sdk/agent-media-payload` | أدوات مساعدة قديمة لحمولات الوسائط | باني حمولة وسائط الوكيل لتخطيطات الحقول القديمة | + | `plugin-sdk/channel-runtime` | طبقة توافق مهملة | أدوات وقت تشغيل القناة القديمة فقط | | `plugin-sdk/channel-send-result` | أنواع نتائج الإرسال | أنواع نتائج الرد | - | `plugin-sdk/runtime-store` | تخزين الإضافات الدائم | `createPluginRuntimeStore` | - | `plugin-sdk/runtime` | مساعدات وقت تشغيل واسعة | مساعدات وقت التشغيل/التسجيل/النسخ الاحتياطي/تثبيت الإضافات | - | `plugin-sdk/runtime-env` | مساعدات بيئة وقت تشغيل ضيقة | مساعدات المسجل/بيئة وقت التشغيل، والمهلة، وإعادة المحاولة، والتراجع | - | `plugin-sdk/plugin-runtime` | مساعدات وقت تشغيل الإضافات المشتركة | مساعدات أوامر/‏hooks/‏http/‏التفاعل للإضافات | - | `plugin-sdk/hook-runtime` | مساعدات مسار hooks | مساعدات مسار webhook/internal hook المشتركة | - | `plugin-sdk/lazy-runtime` | مساعدات وقت التشغيل الكسول | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | مساعدات العمليات | مساعدات التنفيذ المشتركة | - | `plugin-sdk/cli-runtime` | مساعدات وقت تشغيل CLI | تنسيق الأوامر، والانتظار، ومساعدات الإصدار | - | `plugin-sdk/gateway-runtime` | مساعدات Gateway | عميل Gateway ومساعدات تصحيح حالة القناة | - | `plugin-sdk/config-runtime` | مساعدات الإعدادات | مساعدات تحميل/كتابة الإعدادات | - | `plugin-sdk/telegram-command-config` | مساعدات أوامر Telegram | مساعدات تحقق مستقرة للرجوع الاحتياطي لأوامر Telegram عندما يكون سطح عقد Telegram المضمّن غير متاح | - | `plugin-sdk/approval-runtime` | مساعدات مطالبة الموافقة | حمولة موافقة التنفيذ/الإضافة، ومساعدات قدرة/ملف تعريف الموافقة، ومساعدات التوجيه/وقت التشغيل الأصلي للموافقة | - | `plugin-sdk/approval-auth-runtime` | مساعدات مصادقة الموافقة | حلّ المُوافق، ومصادقة الإجراء داخل المحادثة نفسها | - | `plugin-sdk/approval-client-runtime` | مساعدات عميل الموافقة | مساعدات ملف تعريف/تصفية الموافقة الأصلية للتنفيذ | - | `plugin-sdk/approval-delivery-runtime` | مساعدات تسليم الموافقة | محولات قدرة/تسليم الموافقة الأصلية | - | `plugin-sdk/approval-native-runtime` | مساعدات هدف الموافقة | مساعدات ربط هدف/حساب الموافقة الأصلية | - | `plugin-sdk/approval-reply-runtime` | مساعدات رد الموافقة | مساعدات حمولة رد الموافقة للتنفيذ/الإضافة | - | `plugin-sdk/security-runtime` | مساعدات الأمان | مساعدات الثقة المشتركة، وبوابات DM، والمحتوى الخارجي، وجمع الأسرار | - | `plugin-sdk/ssrf-policy` | مساعدات سياسة SSRF | مساعدات قائمة سماح المضيف وسياسة الشبكة الخاصة | - | `plugin-sdk/ssrf-runtime` | مساعدات وقت تشغيل SSRF | مساعدات pinned-dispatcher وguarded fetch وسياسة SSRF | - | `plugin-sdk/collection-runtime` | مساعدات ذاكرة التخزين المؤقت المحدودة | `pruneMapToMaxSize` | - | `plugin-sdk/diagnostic-runtime` | مساعدات بوابات التشخيص | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | - | `plugin-sdk/error-runtime` | مساعدات تنسيق الأخطاء | `formatUncaughtError`, `isApprovalNotFoundError`، ومساعدات رسم الأخطاء | - | `plugin-sdk/fetch-runtime` | مساعدات fetch/proxy المغلفة | `resolveFetch`، ومساعدات الوكيل | - | `plugin-sdk/host-runtime` | مساعدات تطبيع المضيف | `normalizeHostname`, `normalizeScpRemoteHost` | - | `plugin-sdk/retry-runtime` | مساعدات إعادة المحاولة | `RetryConfig`, `retryAsync`، ومشغلات السياسات | + | `plugin-sdk/runtime-store` | تخزين دائم للإضافة | `createPluginRuntimeStore` | + | `plugin-sdk/runtime` | أدوات مساعدة واسعة لوقت التشغيل | أدوات وقت التشغيل/التسجيل/النسخ الاحتياطي/تثبيت الإضافات | + | `plugin-sdk/runtime-env` | أدوات ضيقة لبيئة وقت التشغيل | أدوات التسجيل/بيئة وقت التشغيل، والمهلة، وإعادة المحاولة، والتراجع التدريجي | + | `plugin-sdk/plugin-runtime` | أدوات مساعدة مشتركة لوقت تشغيل الإضافة | أدوات مساعدة لأوامر/خطافات/HTTP/تفاعل الإضافات | + | `plugin-sdk/hook-runtime` | أدوات مساعدة لمسار الخطافات | أدوات مساعدة مشتركة لمسار خطافات الويب/الداخلية | + | `plugin-sdk/lazy-runtime` | أدوات مساعدة لوقت التشغيل الكسول | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | أدوات مساعدة للعمليات | أدوات مساعدة مشتركة للتنفيذ | + | `plugin-sdk/cli-runtime` | أدوات مساعدة لوقت تشغيل CLI | تنسيق الأوامر، والانتظارات، وأدوات مساعدة الإصدارات | + | `plugin-sdk/gateway-runtime` | أدوات مساعدة للبوابة | عميل البوابة وأدوات مساعدة تصحيح حالة القنوات | + | `plugin-sdk/config-runtime` | أدوات مساعدة للتكوين | أدوات مساعدة لتحميل/كتابة التكوين | + | `plugin-sdk/telegram-command-config` | أدوات مساعدة لأوامر Telegram | أدوات مساعدة مستقرة احتياطيًا للتحقق من أوامر Telegram عندما لا يكون سطح عقد Telegram المجمّع متاحًا | + | `plugin-sdk/approval-runtime` | أدوات مساعدة لمطالبات الموافقة | حمولة موافقة التنفيذ/الإضافة، وأدوات مساعدة قدرة/ملف تعريف الموافقة، وأدوات مساعدة التوجيه/وقت التشغيل للموافقة الأصلية | + | `plugin-sdk/approval-auth-runtime` | أدوات مساعدة لمصادقة الموافقة | حل الموافق، ومصادقة الإجراء في الدردشة نفسها | + | `plugin-sdk/approval-client-runtime` | أدوات مساعدة لعميل الموافقة | أدوات مساعدة ملف التعريف/المرشحات لموافقة التنفيذ الأصلية | + | `plugin-sdk/approval-delivery-runtime` | أدوات مساعدة لتسليم الموافقة | مهايئات قدرة/تسليم الموافقة الأصلية | + | `plugin-sdk/approval-gateway-runtime` | أدوات مساعدة لبوابة الموافقة | أداة مساعدة مشتركة لحل بوابة الموافقة | + | `plugin-sdk/approval-handler-adapter-runtime` | أدوات مساعدة لمهايئات الموافقة | أدوات مساعدة خفيفة لتحميل مهايئات الموافقة الأصلية لنقاط إدخال القنوات الساخنة | + | `plugin-sdk/approval-handler-runtime` | أدوات مساعدة لمعالجات الموافقة | أدوات أوسع لوقت تشغيل معالجات الموافقة؛ فَضّل الطبقات الأضيق للمهايئات/البوابة عندما تكفي | + | `plugin-sdk/approval-native-runtime` | أدوات مساعدة لهدف الموافقة | أدوات مساعدة ربط الهدف/الحساب للموافقة الأصلية | + | `plugin-sdk/approval-reply-runtime` | أدوات مساعدة لردود الموافقة | أدوات مساعدة لحمولات رد الموافقة على التنفيذ/الإضافة | + | `plugin-sdk/channel-runtime-context` | أدوات مساعدة لسياق وقت تشغيل القناة | أدوات مساعدة عامة لتسجيل/جلب/مراقبة سياق وقت تشغيل القناة | + | `plugin-sdk/security-runtime` | أدوات مساعدة للأمان | أدوات مساعدة مشتركة للثقة، وبوابات الرسائل الخاصة، والمحتوى الخارجي، وتجميع الأسرار | + | `plugin-sdk/ssrf-policy` | أدوات مساعدة لسياسة SSRF | أدوات مساعدة لقائمة سماح المضيف وسياسة الشبكة الخاصة | + | `plugin-sdk/ssrf-runtime` | أدوات مساعدة لوقت تشغيل SSRF | أدوات مساعدة للمُرسِل المثبت، والجلب المحروس، وسياسات SSRF | + | `plugin-sdk/collection-runtime` | أدوات مساعدة لذاكرة التخزين المحدودة | `pruneMapToMaxSize` | + | `plugin-sdk/diagnostic-runtime` | أدوات مساعدة لبوابات التشخيص | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | + | `plugin-sdk/error-runtime` | أدوات مساعدة لتنسيق الأخطاء | `formatUncaughtError`, `isApprovalNotFoundError`، وأدوات رسم الأخطاء | + | `plugin-sdk/fetch-runtime` | أدوات مساعدة للجلب/الوكيل المغلف | `resolveFetch`، وأدوات مساعدة الوكيل | + | `plugin-sdk/host-runtime` | أدوات مساعدة لتطبيع المضيف | `normalizeHostname`, `normalizeScpRemoteHost` | + | `plugin-sdk/retry-runtime` | أدوات مساعدة لإعادة المحاولة | `RetryConfig`, `retryAsync`، ومشغلات السياسات | | `plugin-sdk/allow-from` | تنسيق قائمة السماح | `formatAllowFromLowercase` | - | `plugin-sdk/allowlist-resolution` | تعيين مدخلات قائمة السماح | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | بوابات الأوامر ومساعدات سطح الأوامر | `resolveControlCommandGate`، ومساعدات تفويض المرسل، ومساعدات سجل الأوامر | - | `plugin-sdk/secret-input` | تحليل مدخلات الأسرار | مساعدات مدخلات الأسرار | - | `plugin-sdk/webhook-ingress` | مساعدات طلبات webhook | أدوات هدف webhook | - | `plugin-sdk/webhook-request-guards` | مساعدات حراسة جسم webhook | مساعدات قراءة/تحديد جسم الطلب | - | `plugin-sdk/reply-runtime` | وقت تشغيل الرد المشترك | الإرسال الوارد، ونبضات القلب، ومخطط الرد، والتقطيع | - | `plugin-sdk/reply-dispatch-runtime` | مساعدات ضيقة لإرسال الرد | مساعدات الإنهاء + إرسال المزوّد | - | `plugin-sdk/reply-history` | مساعدات سجل الرد | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/allowlist-resolution` | ربط مدخلات قائمة السماح | `mapAllowlistResolutionInputs` | + | `plugin-sdk/command-auth` | بوابات الأوامر وأدوات سطح الأوامر | `resolveControlCommandGate`، وأدوات مساعدة تفويض المرسل، وأدوات سجل الأوامر | + | `plugin-sdk/secret-input` | تحليل المدخلات السرية | أدوات مساعدة للمدخلات السرية | + | `plugin-sdk/webhook-ingress` | أدوات مساعدة لطلبات Webhook | أدوات مساعدة لهدف Webhook | + | `plugin-sdk/webhook-request-guards` | أدوات مساعدة لحراسة طلبات Webhook | أدوات مساعدة لقراءة/تقييد جسم الطلب | + | `plugin-sdk/reply-runtime` | وقت تشغيل الرد المشترك | الإرسال الوارد، والنبض، ومخطط الرد، والتجزئة | + | `plugin-sdk/reply-dispatch-runtime` | أدوات ضيقة لإرسال الرد | الإنهاء + أدوات مساعدة إرسال الموفر | + | `plugin-sdk/reply-history` | أدوات مساعدة لسجل الرد | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | تخطيط مراجع الرد | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | مساعدات تقطيع الرد | مساعدات تقطيع النص/markdown | - | `plugin-sdk/session-store-runtime` | مساعدات مخزن الجلسات | مساعدات مسار المخزن + updated-at | - | `plugin-sdk/state-paths` | مساعدات مسارات الحالة | مساعدات الحالة ودليل OAuth | - | `plugin-sdk/routing` | مساعدات التوجيه/مفتاح الجلسة | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`، ومساعدات تطبيع مفتاح الجلسة | - | `plugin-sdk/status-helpers` | مساعدات حالة القناة | منشئات ملخص حالة القناة/الحساب، وافتراضيات حالة وقت التشغيل، ومساعدات بيانات تعريف المشكلات | - | `plugin-sdk/target-resolver-runtime` | مساعدات محلل الهدف | مساعدات محلل الهدف المشتركة | - | `plugin-sdk/string-normalization-runtime` | مساعدات تطبيع السلاسل | مساعدات تطبيع slug/string | - | `plugin-sdk/request-url` | مساعدات URL الطلب | استخراج URLات نصية من مدخلات شبيهة بالطلبات | - | `plugin-sdk/run-command` | مساعدات الأوامر الموقّتة | مشغّل أوامر موقّت مع stdout/stderr مطبّعين | - | `plugin-sdk/param-readers` | قارئات المعاملات | قارئات معاملات الأدوات/CLI الشائعة | - | `plugin-sdk/tool-send` | استخراج إرسال الأداة | استخراج حقول هدف الإرسال القانونية من وسائط الأداة | - | `plugin-sdk/temp-path` | مساعدات المسارات المؤقتة | مساعدات مسارات التنزيل المؤقتة المشتركة | - | `plugin-sdk/logging-core` | مساعدات التسجيل | مسجل النظام الفرعي ومساعدات التنقيح | - | `plugin-sdk/markdown-table-runtime` | مساعدات جداول Markdown | مساعدات وضع جدول Markdown | - | `plugin-sdk/reply-payload` | أنواع رد الرسائل | أنواع حمولة الرد | - | `plugin-sdk/provider-setup` | مساعدات إعداد مزوّد محلي/مستضاف ذاتيًا منسّقة | مساعدات اكتشاف/إعداد المزوّد المستضاف ذاتيًا | - | `plugin-sdk/self-hosted-provider-setup` | مساعدات مركزة لإعداد مزوّدات مستضافة ذاتيًا متوافقة مع OpenAI | مساعدات اكتشاف/إعداد المزوّد المستضاف ذاتيًا نفسها | - | `plugin-sdk/provider-auth-runtime` | مساعدات المصادقة في وقت تشغيل المزوّد | مساعدات حل مفتاح API في وقت التشغيل | - | `plugin-sdk/provider-auth-api-key` | مساعدات إعداد مفتاح API للمزوّد | مساعدات onboarding/كتابة ملف التعريف لمفتاح API | - | `plugin-sdk/provider-auth-result` | مساعدات نتيجة مصادقة المزوّد | منشئ auth-result قياسي لـ OAuth | - | `plugin-sdk/provider-auth-login` | مساعدات تسجيل الدخول التفاعلي للمزوّد | مساعدات تسجيل الدخول التفاعلي المشتركة | - | `plugin-sdk/provider-env-vars` | مساعدات متغيرات البيئة للمزوّد | مساعدات البحث عن متغيرات بيئة مصادقة المزوّد | - | `plugin-sdk/provider-model-shared` | مساعدات مشتركة للنموذج/إعادة التشغيل للمزوّد | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`، ومنشئات سياسة إعادة التشغيل المشتركة، ومساعدات نقاط نهاية المزوّد، ومساعدات تطبيع معرّف النموذج | - | `plugin-sdk/provider-catalog-shared` | مساعدات كتالوج المزوّد المشتركة | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-onboard` | تصحيحات onboarding للمزوّد | مساعدات إعدادات onboarding | - | `plugin-sdk/provider-http` | مساعدات HTTP للمزوّد | مساعدات HTTP/قدرات نقاط النهاية العامة للمزوّد | - | `plugin-sdk/provider-web-fetch` | مساعدات web-fetch للمزوّد | مساعدات تسجيل/ذاكرة التخزين المؤقت لمزوّد web-fetch | - | `plugin-sdk/provider-web-search-contract` | مساعدات عقد web-search للمزوّد | مساعدات ضيقة لعقد إعدادات/بيانات اعتماد web-search مثل `enablePluginInConfig` و`resolveProviderWebSearchPluginConfig` وضبط/جلب بيانات الاعتماد المحدودة | - | `plugin-sdk/provider-web-search` | مساعدات web-search للمزوّد | مساعدات تسجيل/ذاكرة التخزين المؤقت/وقت التشغيل لمزوّد web-search | - | `plugin-sdk/provider-tools` | مساعدات توافق أدوات/مخططات المزوّد | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`، وتنظيف مخطط Gemini + التشخيصات، ومساعدات توافق xAI مثل `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | مساعدات استخدام المزوّد | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage`، ومساعدات استخدام مزوّد أخرى | - | `plugin-sdk/provider-stream` | مساعدات أغلفة تدفق المزوّد | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`، وأنواع أغلفة التدفق، ومساعدات الأغلفة المشتركة لـ Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/reply-chunking` | أدوات مساعدة لتجزئة الرد | أدوات مساعدة لتجزئة النص/Markdown | + | `plugin-sdk/session-store-runtime` | أدوات مساعدة لمخزن الجلسات | أدوات مساعدة لمسار المخزن ووقت آخر تحديث | + | `plugin-sdk/state-paths` | أدوات مساعدة لمسارات الحالة | أدوات مساعدة لأدلة الحالة وOAuth | + | `plugin-sdk/routing` | أدوات مساعدة للتوجيه/مفاتيح الجلسة | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`، وأدوات تطبيع مفاتيح الجلسة | + | `plugin-sdk/status-helpers` | أدوات مساعدة لحالة القناة | بناة ملخصات حالة القناة/الحساب، وافتراضات حالة وقت التشغيل، وأدوات بيانات تعريف المشكلات | + | `plugin-sdk/target-resolver-runtime` | أدوات مساعدة لحل الأهداف | أدوات مساعدة مشتركة لحل الأهداف | + | `plugin-sdk/string-normalization-runtime` | أدوات مساعدة لتطبيع السلاسل | أدوات مساعدة لتطبيع الـ slug/السلاسل | + | `plugin-sdk/request-url` | أدوات مساعدة لعناوين URL للطلبات | استخراج عناوين URL النصية من المدخلات الشبيهة بالطلبات | + | `plugin-sdk/run-command` | أدوات مساعدة للأوامر المؤقتة | مشغّل أوامر مؤقت مع stdout/stderr مطبعين | + | `plugin-sdk/param-readers` | قارئات المعاملات | قارئات شائعة لمعاملات الأدوات/CLI | + | `plugin-sdk/tool-send` | استخراج إرسال الأدوات | استخراج حقول هدف الإرسال القياسية من وسائط الأدوات | + | `plugin-sdk/temp-path` | أدوات مساعدة للمسارات المؤقتة | أدوات مساعدة مشتركة لمسارات تنزيل الملفات المؤقتة | + | `plugin-sdk/logging-core` | أدوات مساعدة للتسجيل | مسجل النظام الفرعي وأدوات الإخفاء | + | `plugin-sdk/markdown-table-runtime` | أدوات مساعدة لجداول Markdown | أدوات مساعدة لأنماط جداول Markdown | + | `plugin-sdk/reply-payload` | أنواع ردود الرسائل | أنواع حمولة الرد | + | `plugin-sdk/provider-setup` | أدوات مساعدة منسقة لإعداد الموفّرين المحليين/المستضافين ذاتيًا | أدوات مساعدة لاكتشاف/تكوين الموفّرين المستضافين ذاتيًا | + | `plugin-sdk/self-hosted-provider-setup` | أدوات مركزة لإعداد الموفّرين المستضافين ذاتيًا المتوافقين مع OpenAI | أدوات مساعدة الاكتشاف/التكوين نفسها للموفّرين المستضافين ذاتيًا | + | `plugin-sdk/provider-auth-runtime` | أدوات مساعدة لمصادقة موفر وقت التشغيل | أدوات مساعدة لحل مفاتيح API في وقت التشغيل | + | `plugin-sdk/provider-auth-api-key` | أدوات مساعدة لإعداد مفتاح API للموفر | أدوات مساعدة لتهيئة/كتابة ملفات تعريف مفتاح API | + | `plugin-sdk/provider-auth-result` | أدوات مساعدة لنتائج مصادقة الموفر | باني قياسي لنتائج مصادقة OAuth | + | `plugin-sdk/provider-auth-login` | أدوات مساعدة لتسجيل الدخول التفاعلي للموفر | أدوات مساعدة مشتركة لتسجيل الدخول التفاعلي | + | `plugin-sdk/provider-env-vars` | أدوات مساعدة لمتغيرات بيئة الموفر | أدوات مساعدة للبحث عن متغيرات بيئة مصادقة الموفر | + | `plugin-sdk/provider-model-shared` | أدوات مساعدة مشتركة لنماذج/إعادة تشغيل الموفّر | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`، وبناة سياسات الإعادة المشتركة، وأدوات مساعدة لنقاط نهاية الموفّر، وأدوات تطبيع معرّفات النماذج | + | `plugin-sdk/provider-catalog-shared` | أدوات مساعدة مشتركة لفهرس الموفّر | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | + | `plugin-sdk/provider-onboard` | تصحيحات تهيئة الموفّر | أدوات مساعدة لتكوين التهيئة | + | `plugin-sdk/provider-http` | أدوات مساعدة HTTP للموفّر | أدوات مساعدة عامة لقدرات HTTP/نقاط النهاية الخاصة بالموفّر | + | `plugin-sdk/provider-web-fetch` | أدوات مساعدة جلب الويب للموفّر | أدوات مساعدة لتسجيل/تخزين موفّر web-fetch | + | `plugin-sdk/provider-web-search-contract` | أدوات مساعدة لعقد بحث الويب للموفّر | أدوات ضيقة لعقد تكوين/اعتماد بحث الويب مثل `enablePluginInConfig` و`resolveProviderWebSearchPluginConfig` وأدوات ضبط/جلب بيانات الاعتماد المقيّدة | + | `plugin-sdk/provider-web-search` | أدوات مساعدة لبحث الويب للموفّر | أدوات مساعدة لتسجيل/تخزين/وقت تشغيل موفّر بحث الويب | + | `plugin-sdk/provider-tools` | أدوات مساعدة لتوافق الأدوات/المخططات للموفّر | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`، وتنظيف مخططات Gemini + التشخيصات، وأدوات توافق xAI مثل `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | أدوات مساعدة لاستخدام الموفّر | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage`، وأدوات مساعدة أخرى لاستخدام الموفّر | + | `plugin-sdk/provider-stream` | أدوات مساعدة لأغلفة بث الموفّر | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`، وأنواع أغلفة البث، وأدوات مساعدة مشتركة لأغلفة Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | | `plugin-sdk/keyed-async-queue` | طابور async مرتب | `KeyedAsyncQueue` | - | `plugin-sdk/media-runtime` | مساعدات الوسائط المشتركة | مساعدات جلب/تحويل/تخزين الوسائط بالإضافة إلى منشئات حمولة الوسائط | - | `plugin-sdk/media-generation-runtime` | مساعدات مشتركة لتوليد الوسائط | مساعدات الرجوع الاحتياطي المشتركة، واختيار المرشحين، ورسائل غياب النموذج لتوليد الصور/الفيديو/الموسيقى | - | `plugin-sdk/media-understanding` | مساعدات فهم الوسائط | أنواع مزوّدات فهم الوسائط بالإضافة إلى تصديرات مساعدات الصور/الصوت المواجهة للمزوّد | - | `plugin-sdk/text-runtime` | مساعدات النص المشتركة | إزالة النص المرئي للمساعد، ومساعدات عرض/تقطيع/جداول markdown، ومساعدات التنقيح، ومساعدات علامات التوجيه، وأدوات النص الآمن، ومساعدات النص/التسجيل ذات الصلة | - | `plugin-sdk/text-chunking` | مساعدات تقطيع النص | مساعد تقطيع النص الصادر | - | `plugin-sdk/speech` | مساعدات Speech | أنواع مزوّدات Speech بالإضافة إلى مساعدات التوجيه، والسجل، والتحقق المواجهة للمزوّد | - | `plugin-sdk/speech-core` | النواة المشتركة لـ Speech | أنواع مزوّدات Speech، والسجل، والتوجيهات، والتطبيع | - | `plugin-sdk/realtime-transcription` | مساعدات النسخ الفوري | أنواع المزوّدات ومساعدات السجل | - | `plugin-sdk/realtime-voice` | مساعدات الصوت الفوري | أنواع المزوّدات ومساعدات السجل | - | `plugin-sdk/image-generation-core` | النواة المشتركة لتوليد الصور | أنواع توليد الصور، والرجوع الاحتياطي، والمصادقة، ومساعدات السجل | - | `plugin-sdk/music-generation` | مساعدات توليد الموسيقى | أنواع المزوّد/الطلب/النتيجة لتوليد الموسيقى | - | `plugin-sdk/music-generation-core` | النواة المشتركة لتوليد الموسيقى | أنواع توليد الموسيقى، ومساعدات الرجوع الاحتياطي، والبحث عن المزوّد، وتحليل model-ref | - | `plugin-sdk/video-generation` | مساعدات توليد الفيديو | أنواع المزوّد/الطلب/النتيجة لتوليد الفيديو | - | `plugin-sdk/video-generation-core` | النواة المشتركة لتوليد الفيديو | أنواع توليد الفيديو، ومساعدات الرجوع الاحتياطي، والبحث عن المزوّد، وتحليل model-ref | - | `plugin-sdk/interactive-runtime` | مساعدات الرد التفاعلي | تطبيع/تقليل حمولة الرد التفاعلي | - | `plugin-sdk/channel-config-primitives` | أساسيات إعدادات القناة | أساسيات ضيقة لمخطط إعدادات القناة | - | `plugin-sdk/channel-config-writes` | مساعدات كتابة إعدادات القناة | مساعدات تفويض كتابة إعدادات القناة | - | `plugin-sdk/channel-plugin-common` | تمهيد القناة المشترك | تصديرات تمهيد الإضافة المشتركة للقنوات | - | `plugin-sdk/channel-status` | مساعدات حالة القناة | مساعدات اللقطة/الملخص المشتركة لحالة القناة | - | `plugin-sdk/allowlist-config-edit` | مساعدات إعدادات قائمة السماح | مساعدات تحرير/قراءة إعدادات قائمة السماح | - | `plugin-sdk/group-access` | مساعدات وصول المجموعات | مساعدات قرارات وصول المجموعات المشتركة | - | `plugin-sdk/direct-dm` | مساعدات Direct-DM | مساعدات المصادقة/الحراسة المشتركة لـ Direct-DM | - | `plugin-sdk/extension-shared` | مساعدات الإضافات المشتركة | أساسيات مساعدات القناة/الحالة السلبية والوكيل المحيطي | - | `plugin-sdk/webhook-targets` | مساعدات أهداف webhook | سجل أهداف webhook ومساعدات تثبيت المسارات | - | `plugin-sdk/webhook-path` | مساعدات مسار webhook | مساعدات تطبيع مسار webhook | - | `plugin-sdk/web-media` | مساعدات وسائط الويب المشتركة | مساعدات تحميل الوسائط البعيدة/المحلية | - | `plugin-sdk/zod` | إعادة تصدير Zod | إعادة تصدير `zod` لمستهلكي plugin SDK | - | `plugin-sdk/memory-core` | مساعدات memory-core المضمّنة | سطح مساعدات مدير الذاكرة/الإعداد/الملفات/CLI | - | `plugin-sdk/memory-core-engine-runtime` | واجهة وقت تشغيل محرك الذاكرة | واجهة وقت تشغيل فهرسة/بحث الذاكرة | + | `plugin-sdk/media-runtime` | أدوات مساعدة مشتركة للوسائط | أدوات مساعدة لجلب/تحويل/تخزين الوسائط بالإضافة إلى بناة حمولات الوسائط | + | `plugin-sdk/media-generation-runtime` | أدوات مساعدة مشتركة لتوليد الوسائط | أدوات مساعدة مشتركة للتحويل الاحتياطي، واختيار المرشحين، ورسائل النماذج المفقودة لتوليد الصور/الفيديو/الموسيقى | + | `plugin-sdk/media-understanding` | أدوات مساعدة لفهم الوسائط | أنواع موفري فهم الوسائط بالإضافة إلى تصديرات أدوات مساعدة الصور/الصوت المواجهة للموفّر | + | `plugin-sdk/text-runtime` | أدوات مساعدة مشتركة للنص | إزالة النص المرئي للمساعد، وأدوات عرض/تجزئة/جداول Markdown، وأدوات الإخفاء، وأدوات وسم التوجيهات، وأدوات النص الآمن، وأدوات ذات صلة بالنص/التسجيل | + | `plugin-sdk/text-chunking` | أدوات مساعدة لتجزئة النص | أداة مساعدة لتجزئة النص الصادر | + | `plugin-sdk/speech` | أدوات مساعدة للكلام | أنواع موفري الكلام بالإضافة إلى تصديرات أدوات مساعدة التوجيهات والسجل والتحقق المواجهة للموفّر | + | `plugin-sdk/speech-core` | نواة كلام مشتركة | أنواع موفري الكلام، والسجل، والتوجيهات، والتطبيع | + | `plugin-sdk/realtime-transcription` | أدوات مساعدة للنسخ الفوري | أنواع الموفّرين وأدوات السجل | + | `plugin-sdk/realtime-voice` | أدوات مساعدة للصوت الفوري | أنواع الموفّرين وأدوات السجل | + | `plugin-sdk/image-generation-core` | نواة مشتركة لتوليد الصور | أنواع توليد الصور، والتحويل الاحتياطي، والمصادقة، وأدوات السجل | + | `plugin-sdk/music-generation` | أدوات مساعدة لتوليد الموسيقى | أنواع موفّر/طلب/نتيجة توليد الموسيقى | + | `plugin-sdk/music-generation-core` | نواة مشتركة لتوليد الموسيقى | أنواع توليد الموسيقى، وأدوات التحويل الاحتياطي، والبحث عن الموفّر، وتحليل مراجع النماذج | + | `plugin-sdk/video-generation` | أدوات مساعدة لتوليد الفيديو | أنواع موفّر/طلب/نتيجة توليد الفيديو | + | `plugin-sdk/video-generation-core` | نواة مشتركة لتوليد الفيديو | أنواع توليد الفيديو، وأدوات التحويل الاحتياطي، والبحث عن الموفّر، وتحليل مراجع النماذج | + | `plugin-sdk/interactive-runtime` | أدوات مساعدة للردود التفاعلية | تطبيع/اختزال حمولات الردود التفاعلية | + | `plugin-sdk/channel-config-primitives` | بدائيات تكوين القنوات | بدائيات ضيقة لمخطط تكوين القناة | + | `plugin-sdk/channel-config-writes` | أدوات مساعدة لكتابة تكوين القنوات | أدوات مساعدة لتفويض كتابة تكوين القنوات | + | `plugin-sdk/channel-plugin-common` | تمهيد مشترك للقنوات | تصديرات تمهيد مشتركة لإضافات القنوات | + | `plugin-sdk/channel-status` | أدوات مساعدة لحالة القنوات | أدوات مساعدة مشتركة لالتقاط/تلخيص حالة القناة | + | `plugin-sdk/allowlist-config-edit` | أدوات مساعدة لتكوين قائمة السماح | أدوات مساعدة لتحرير/قراءة تكوين قائمة السماح | + | `plugin-sdk/group-access` | أدوات مساعدة للوصول إلى المجموعات | أدوات مساعدة مشتركة لاتخاذ قرارات وصول المجموعات | + | `plugin-sdk/direct-dm` | أدوات مساعدة للرسائل الخاصة المباشرة | أدوات مساعدة مشتركة لمصادقة/حراسة الرسائل الخاصة المباشرة | + | `plugin-sdk/extension-shared` | أدوات مساعدة مشتركة للإضافات | بدائيات القنوات/الحالة السلبية والمساعد الوكيل المحيط | + | `plugin-sdk/webhook-targets` | أدوات مساعدة لأهداف Webhook | سجل أهداف Webhook وأدوات تثبيت المسارات | + | `plugin-sdk/webhook-path` | أدوات مساعدة لمسارات Webhook | أدوات مساعدة لتطبيع مسارات Webhook | + | `plugin-sdk/web-media` | أدوات مساعدة مشتركة لوسائط الويب | أدوات مساعدة لتحميل الوسائط البعيدة/المحلية | + | `plugin-sdk/zod` | إعادة تصدير Zod | `zod` معاد تصديره لمستهلكي Plugin SDK | + | `plugin-sdk/memory-core` | أدوات memory-core المجمعة | سطح أدوات مساعدة مدير/تكوين/ملفات/CLI الخاصة بالذاكرة | + | `plugin-sdk/memory-core-engine-runtime` | واجهة وقت تشغيل لمحرك الذاكرة | واجهة وقت تشغيل فهرسة/بحث الذاكرة | | `plugin-sdk/memory-core-host-engine-foundation` | محرك الأساس لمضيف الذاكرة | تصديرات محرك الأساس لمضيف الذاكرة | - | `plugin-sdk/memory-core-host-engine-embeddings` | محرك embeddings لمضيف الذاكرة | تصديرات محرك embeddings لمضيف الذاكرة | + | `plugin-sdk/memory-core-host-engine-embeddings` | محرك التضمين لمضيف الذاكرة | تصديرات محرك التضمين لمضيف الذاكرة | | `plugin-sdk/memory-core-host-engine-qmd` | محرك QMD لمضيف الذاكرة | تصديرات محرك QMD لمضيف الذاكرة | | `plugin-sdk/memory-core-host-engine-storage` | محرك التخزين لمضيف الذاكرة | تصديرات محرك التخزين لمضيف الذاكرة | - | `plugin-sdk/memory-core-host-multimodal` | مساعدات متعددة الوسائط لمضيف الذاكرة | مساعدات متعددة الوسائط لمضيف الذاكرة | - | `plugin-sdk/memory-core-host-query` | مساعدات استعلام مضيف الذاكرة | مساعدات استعلام مضيف الذاكرة | - | `plugin-sdk/memory-core-host-secret` | مساعدات أسرار مضيف الذاكرة | مساعدات أسرار مضيف الذاكرة | - | `plugin-sdk/memory-core-host-events` | مساعدات سجل أحداث مضيف الذاكرة | مساعدات سجل أحداث مضيف الذاكرة | - | `plugin-sdk/memory-core-host-status` | مساعدات حالة مضيف الذاكرة | مساعدات حالة مضيف الذاكرة | - | `plugin-sdk/memory-core-host-runtime-cli` | وقت تشغيل CLI لمضيف الذاكرة | مساعدات وقت تشغيل CLI لمضيف الذاكرة | - | `plugin-sdk/memory-core-host-runtime-core` | وقت تشغيل النواة لمضيف الذاكرة | مساعدات وقت تشغيل النواة لمضيف الذاكرة | - | `plugin-sdk/memory-core-host-runtime-files` | مساعدات ملفات/وقت تشغيل مضيف الذاكرة | مساعدات ملفات/وقت تشغيل مضيف الذاكرة | - | `plugin-sdk/memory-host-core` | اسم مستعار لوقت تشغيل نواة مضيف الذاكرة | اسم مستعار محايد للمورّد لمساعدات وقت تشغيل نواة مضيف الذاكرة | - | `plugin-sdk/memory-host-events` | اسم مستعار لسجل أحداث مضيف الذاكرة | اسم مستعار محايد للمورّد لمساعدات سجل أحداث مضيف الذاكرة | - | `plugin-sdk/memory-host-files` | اسم مستعار لملفات/وقت تشغيل مضيف الذاكرة | اسم مستعار محايد للمورّد لمساعدات ملفات/وقت تشغيل مضيف الذاكرة | - | `plugin-sdk/memory-host-markdown` | مساعدات markdown المُدارة | مساعدات managed-markdown المشتركة للإضافات المجاورة للذاكرة | + | `plugin-sdk/memory-core-host-multimodal` | أدوات مساعدة متعددة الوسائط لمضيف الذاكرة | أدوات مساعدة متعددة الوسائط لمضيف الذاكرة | + | `plugin-sdk/memory-core-host-query` | أدوات مساعدة للاستعلام في مضيف الذاكرة | أدوات مساعدة للاستعلام في مضيف الذاكرة | + | `plugin-sdk/memory-core-host-secret` | أدوات مساعدة للأسرار في مضيف الذاكرة | أدوات مساعدة للأسرار في مضيف الذاكرة | + | `plugin-sdk/memory-core-host-events` | أدوات مساعدة لسجل أحداث مضيف الذاكرة | أدوات مساعدة لسجل أحداث مضيف الذاكرة | + | `plugin-sdk/memory-core-host-status` | أدوات مساعدة لحالة مضيف الذاكرة | أدوات مساعدة لحالة مضيف الذاكرة | + | `plugin-sdk/memory-core-host-runtime-cli` | وقت تشغيل CLI لمضيف الذاكرة | أدوات مساعدة وقت تشغيل CLI لمضيف الذاكرة | + | `plugin-sdk/memory-core-host-runtime-core` | وقت تشغيل النواة لمضيف الذاكرة | أدوات مساعدة وقت تشغيل النواة لمضيف الذاكرة | + | `plugin-sdk/memory-core-host-runtime-files` | أدوات مساعدة للملفات/وقت التشغيل لمضيف الذاكرة | أدوات مساعدة للملفات/وقت التشغيل لمضيف الذاكرة | + | `plugin-sdk/memory-host-core` | اسم مستعار لوقت تشغيل نواة مضيف الذاكرة | اسم مستعار محايد للمورّد لأدوات وقت تشغيل نواة مضيف الذاكرة | + | `plugin-sdk/memory-host-events` | اسم مستعار لسجل أحداث مضيف الذاكرة | اسم مستعار محايد للمورّد لأدوات سجل أحداث مضيف الذاكرة | + | `plugin-sdk/memory-host-files` | اسم مستعار لملفات/وقت تشغيل مضيف الذاكرة | اسم مستعار محايد للمورّد لأدوات ملفات/وقت تشغيل مضيف الذاكرة | + | `plugin-sdk/memory-host-markdown` | أدوات مساعدة لـ markdown المُدار | أدوات مساعدة مشتركة لـ markdown المُدار للإضافات المجاورة للذاكرة | | `plugin-sdk/memory-host-search` | واجهة بحث الذاكرة النشطة | واجهة وقت تشغيل كسولة لمدير بحث الذاكرة النشطة | - | `plugin-sdk/memory-host-status` | اسم مستعار لحالة مضيف الذاكرة | اسم مستعار محايد للمورّد لمساعدات حالة مضيف الذاكرة | - | `plugin-sdk/memory-lancedb` | مساعدات memory-lancedb المضمّنة | سطح مساعدات memory-lancedb | - | `plugin-sdk/testing` | أدوات الاختبار | مساعدات ومحاكيات الاختبار | + | `plugin-sdk/memory-host-status` | اسم مستعار لحالة مضيف الذاكرة | اسم مستعار محايد للمورّد لأدوات حالة مضيف الذاكرة | + | `plugin-sdk/memory-lancedb` | أدوات memory-lancedb المجمعة | سطح أدوات مساعدة memory-lancedb | + | `plugin-sdk/testing` | أدوات الاختبار | أدوات الاختبار والمحاكاة | -هذا الجدول هو عمدًا المجموعة الفرعية الشائعة للترحيل، وليس سطح SDK الكامل. -القائمة الكاملة التي تضم أكثر من 200 نقطة دخول موجودة في +هذا الجدول هو عمدًا مجموعة الترحيل الشائعة، وليس سطح SDK الكامل. +وتوجد القائمة الكاملة التي تضم أكثر من 200 نقطة إدخال في `scripts/lib/plugin-sdk-entrypoints.json`. -ولا تزال تلك القائمة تتضمن بعض فواصل مساعدات الإضافات المضمّنة مثل -`plugin-sdk/feishu` و`plugin-sdk/feishu-setup` و`plugin-sdk/zalo` و -`plugin-sdk/zalo-setup` و`plugin-sdk/matrix*`. وتظل هذه مُصدّرة من أجل -صيانة الإضافات المضمّنة والتوافق، لكنها حُذفت عمدًا من جدول الترحيل الشائع -وليست الهدف الموصى به لشيفرة الإضافات الجديدة. +ما تزال تلك القائمة تتضمن بعض طبقات أدوات المساعدة الخاصة بالإضافات المجمعة مثل +`plugin-sdk/feishu` و`plugin-sdk/feishu-setup` و`plugin-sdk/zalo`، +و`plugin-sdk/zalo-setup` و`plugin-sdk/matrix*`. وما تزال هذه المداخل مُصدَّرة +لصيانة الإضافات المجمعة والتوافق، لكنها أُزيلت عمدًا من +جدول الترحيل الشائع وليست الهدف الموصى به +لكود الإضافات الجديد. -تنطبق القاعدة نفسها على عائلات المساعدات المضمّنة الأخرى مثل: +تنطبق القاعدة نفسها على عائلات الأدوات المجمعة الأخرى مثل: -- مساعدات دعم المتصفح: `plugin-sdk/browser-cdp` و`plugin-sdk/browser-config-runtime` و`plugin-sdk/browser-config-support` و`plugin-sdk/browser-control-auth` و`plugin-sdk/browser-node-runtime` و`plugin-sdk/browser-profiles` و`plugin-sdk/browser-security-runtime` و`plugin-sdk/browser-setup-tools` و`plugin-sdk/browser-support` -- Matrix: `plugin-sdk/matrix*` -- LINE: `plugin-sdk/line*` -- IRC: `plugin-sdk/irc*` -- أسطح المساعدات/الإضافات المضمّنة مثل `plugin-sdk/googlechat`، - و`plugin-sdk/zalouser`، و`plugin-sdk/bluebubbles*`، - و`plugin-sdk/mattermost*`، و`plugin-sdk/msteams`، - و`plugin-sdk/nextcloud-talk`، و`plugin-sdk/nostr`، و`plugin-sdk/tlon`، - و`plugin-sdk/twitch`، - و`plugin-sdk/github-copilot-login`، و`plugin-sdk/github-copilot-token`، - و`plugin-sdk/diagnostics-otel`، و`plugin-sdk/diffs`، و`plugin-sdk/llm-task`، - و`plugin-sdk/thread-ownership`، و`plugin-sdk/voice-call` +- أدوات دعم المتصفح: `plugin-sdk/browser-cdp` و`plugin-sdk/browser-config-runtime` و`plugin-sdk/browser-config-support` و`plugin-sdk/browser-control-auth` و`plugin-sdk/browser-node-runtime` و`plugin-sdk/browser-profiles` و`plugin-sdk/browser-security-runtime` و`plugin-sdk/browser-setup-tools` و`plugin-sdk/browser-support` +- Matrix: ‏`plugin-sdk/matrix*` +- LINE: ‏`plugin-sdk/line*` +- IRC: ‏`plugin-sdk/irc*` +- أسطح الأدوات/الإضافات المجمعة مثل `plugin-sdk/googlechat`، + و`plugin-sdk/zalouser` و`plugin-sdk/bluebubbles*`, + و`plugin-sdk/mattermost*` و`plugin-sdk/msteams`, + و`plugin-sdk/nextcloud-talk` و`plugin-sdk/nostr` و`plugin-sdk/tlon`, + و`plugin-sdk/twitch`, + و`plugin-sdk/github-copilot-login` و`plugin-sdk/github-copilot-token`, + و`plugin-sdk/diagnostics-otel` و`plugin-sdk/diffs` و`plugin-sdk/llm-task`, + و`plugin-sdk/thread-ownership` و`plugin-sdk/voice-call` -يكشف `plugin-sdk/github-copilot-token` حاليًا عن سطح مساعدات الرموز الضيق -`DEFAULT_COPILOT_API_BASE_URL`، +يكشف `plugin-sdk/github-copilot-token` حاليًا عن +سطح أدوات الرموز الضيق `DEFAULT_COPILOT_API_BASE_URL`، و`deriveCopilotApiBaseUrlFromToken`، و`resolveCopilotApiToken`. -استخدم أضيق استيراد يطابق المهمة. إذا لم تتمكن من العثور على تصدير، +استخدم أضيق استيراد يطابق المهمة. وإذا لم تتمكن من العثور على تصدير، فتحقق من المصدر في `src/plugin-sdk/` أو اسأل في Discord. ## الجدول الزمني للإزالة -| متى | ما الذي يحدث | -| ---------------------- | ----------------------------------------------------------------- | -| **الآن** | تصدر الأسطح المهملة تحذيرات في وقت التشغيل | -| **الإصدار الرئيسي التالي** | ستُزال الأسطح المهملة؛ وستفشل الإضافات التي لا تزال تستخدمها | +| متى | ما الذي يحدث | +| ---------------------- | ----------------------------------------------------------------------- | +| **الآن** | تُصدر الأسطح المهملة تحذيرات في وقت التشغيل | +| **الإصدار الرئيسي التالي** | ستُزال الأسطح المهملة؛ وستفشل الإضافات التي ما تزال تستخدمها | -تم ترحيل كل الإضافات الأساسية بالفعل. يجب أن ترحّل الإضافات الخارجية قبل -الإصدار الرئيسي التالي. +لقد تم بالفعل ترحيل جميع الإضافات الأساسية. ويجب أن تهاجر الإضافات الخارجية +قبل الإصدار الرئيسي التالي. ## كتم التحذيرات مؤقتًا @@ -371,9 +399,9 @@ OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run ## ذو صلة -- [البدء](/ar/plugins/building-plugins) — أنشئ أول إضافة لك -- [نظرة عامة على SDK](/ar/plugins/sdk-overview) — مرجع كامل لعمليات الاستيراد عبر المسارات الفرعية -- [إضافات القنوات](/ar/plugins/sdk-channel-plugins) — بناء إضافات القنوات -- [إضافات المزوّدات](/ar/plugins/sdk-provider-plugins) — بناء إضافات المزوّدات -- [الآليات الداخلية للإضافات](/ar/plugins/architecture) — نظرة معمقة على البنية -- [بيان الإضافة](/ar/plugins/manifest) — مرجع مخطط البيان +- [Getting Started](/ar/plugins/building-plugins) — أنشئ إضافتك الأولى +- [SDK Overview](/ar/plugins/sdk-overview) — مرجع كامل لاستيراد المسارات الفرعية +- [Channel Plugins](/ar/plugins/sdk-channel-plugins) — بناء إضافات القنوات +- [Provider Plugins](/ar/plugins/sdk-provider-plugins) — بناء إضافات الموفّرين +- [Plugin Internals](/ar/plugins/architecture) — تعمق في المعمارية +- [Plugin Manifest](/ar/plugins/manifest) — مرجع مخطط البيان diff --git a/docs/ar/plugins/sdk-overview.md b/docs/ar/plugins/sdk-overview.md index 11a2d6aa6..ebd96bde9 100644 --- a/docs/ar/plugins/sdk-overview.md +++ b/docs/ar/plugins/sdk-overview.md @@ -1,33 +1,33 @@ --- read_when: - - تحتاج إلى معرفة أي مسار فرعي من SDK يجب الاستيراد منه + - تحتاج إلى معرفة المسار الفرعي في SDK الذي يجب الاستيراد منه - تريد مرجعًا لجميع أساليب التسجيل على OpenClawPluginApi - - تبحث عن export محدد في SDK + - تبحث عن تصدير محدد في SDK sidebarTitle: SDK Overview -summary: خريطة الاستيراد، ومرجع API التسجيل، وبنية SDK +summary: خريطة الاستيراد، ومرجع API للتسجيل، وبنية SDK title: نظرة عامة على Plugin SDK x-i18n: - generated_at: "2026-04-07T07:21:02Z" + generated_at: "2026-04-08T02:18:17Z" model: gpt-5.4 provider: openai - source_hash: 533bc3027ed8ad50b706518a4f58e75f6ef717fc8b36f242e928cae54d20985f + source_hash: c5a41bd82d165dfbb7fbd6e4528cf322e9133a51efe55fa8518a7a0a626d9d30 source_path: plugins/sdk-overview.md workflow: 15 --- # نظرة عامة على Plugin SDK -يُعد plugin SDK العقد typed بين plugins وcore. هذه الصفحة هي -المرجع الخاص بـ **ما يجب استيراده** و**ما الذي يمكنك تسجيله**. +Plugin SDK هو العقد المطبّع بين الإضافات والنواة. هذه الصفحة هي +المرجع الخاص بـ **ما الذي يجب استيراده** و**ما الذي يمكنك تسجيله**. **هل تبحث عن دليل عملي؟** - - أول plugin؟ ابدأ من [البدء](/ar/plugins/building-plugins) - - Channel plugin؟ راجع [Channel Plugins](/ar/plugins/sdk-channel-plugins) - - Provider plugin؟ راجع [Provider Plugins](/ar/plugins/sdk-provider-plugins) + - أول إضافة؟ ابدأ من [البدء](/ar/plugins/building-plugins) + - إضافة قناة؟ راجع [إضافات القنوات](/ar/plugins/sdk-channel-plugins) + - إضافة موفّر؟ راجع [إضافات الموفّرات](/ar/plugins/sdk-provider-plugins) -## اصطلاحات الاستيراد +## اصطلاح الاستيراد استورد دائمًا من مسار فرعي محدد: @@ -36,39 +36,39 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` -كل مسار فرعي عبارة عن وحدة صغيرة مستقلة بذاتها. وهذا يُبقي بدء التشغيل سريعًا -ويمنع مشكلات التبعيات الدائرية. بالنسبة إلى مساعدات الإدخال/البناء الخاصة بالقنوات، -فضّل `openclaw/plugin-sdk/channel-core`; وأبقِ `openclaw/plugin-sdk/core` للسطح -الأوسع الشامل والمساعدات المشتركة مثل +كل مسار فرعي هو وحدة صغيرة ومستقلة بذاتها. يحافظ هذا على سرعة بدء التشغيل +ويمنع مشكلات التبعيات الدائرية. بالنسبة إلى أدوات الإدخال/البناء الخاصة بالقنوات، +فضّل `openclaw/plugin-sdk/channel-core`؛ واحتفظ بـ `openclaw/plugin-sdk/core` من أجل +السطح الأشمل والمظلّي والمساعدات المشتركة مثل `buildChannelConfigSchema`. -لا تضف ولا تعتمد على نقاط ربط تسهيلية مسماة باسم المزود مثل -`openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, -`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp` أو -نقاط ربط مساعدة تحمل العلامة الخاصة بالقناة. يجب أن تؤلف plugins المضمنة -المسارات الفرعية العامة من SDK داخل ملفات `api.ts` أو `runtime-api.ts` الخاصة بها، ويجب على core -إما استخدام هذه الملفات المحلية الخاصة بالـ plugin أو إضافة عقد SDK عام ضيق -عندما تكون الحاجة فعلًا عابرة للقنوات. +لا تضف ولا تعتمد على مسارات تسهيلية مسماة على اسم الموفّر مثل +`openclaw/plugin-sdk/slack` أو `openclaw/plugin-sdk/discord`، +أو `openclaw/plugin-sdk/signal` أو `openclaw/plugin-sdk/whatsapp`، أو +مسارات مساعدات تحمل علامة قناة محددة. يجب على الإضافات المضمّنة أن تركّب +مسارات SDK الفرعية العامة داخل ملفات `api.ts` أو `runtime-api.ts` الخاصة بها، ويجب على النواة +إما استخدام هذه الملفات المحلية للإضافة أو إضافة عقد SDK عام ضيّق +عندما تكون الحاجة عابرة للقنوات فعلًا. -لا تزال خريطة export المولدة تحتوي على مجموعة صغيرة من -نقاط الربط المساعدة للـ plugins المضمنة مثل `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, -`plugin-sdk/zalo`, `plugin-sdk/zalo-setup`, و`plugin-sdk/matrix*`. وهذه -المسارات الفرعية موجودة فقط لصيانة plugins المضمنة ولأغراض التوافق؛ وهي -مستبعدة عمدًا من الجدول الشائع أدناه وليست مسار الاستيراد الموصى به -للـ plugins الخارجية الجديدة. +لا تزال خريطة التصدير المولدة تحتوي على مجموعة صغيرة من +مسارات المساعدات الخاصة بالإضافات المضمّنة مثل `plugin-sdk/feishu` و`plugin-sdk/feishu-setup`، +و`plugin-sdk/zalo` و`plugin-sdk/zalo-setup` و`plugin-sdk/matrix*`. هذه +المسارات الفرعية موجودة فقط لصيانة الإضافات المضمّنة والتوافق؛ وهي +مستبعدة عمدًا من الجدول الشائع أدناه وليست مسار الاستيراد +الموصى به للإضافات الخارجية الجديدة. ## مرجع المسارات الفرعية -أكثر المسارات الفرعية استخدامًا، مجمعة حسب الغرض. والقائمة الكاملة المولدة التي تضم +أكثر المسارات الفرعية استخدامًا، مجمّعة حسب الغرض. القائمة الكاملة المولدة والتي تضم أكثر من 200 مسار فرعي موجودة في `scripts/lib/plugin-sdk-entrypoints.json`. -لا تزال مسارات المساعدة المحجوزة الخاصة بالـ plugins المضمنة تظهر في تلك القائمة المولدة. -تعامل معها على أنها أسطح تنفيذية/توافقية ما لم تروّج صفحة توثيق -لأحدها صراحةً على أنه عام. +لا تزال المسارات الفرعية المحجوزة الخاصة بمساعدات الإضافات المضمّنة تظهر في تلك القائمة المولدة. +تعامل مع هذه المسارات على أنها تفاصيل تنفيذ/أسطح توافق إلا إذا +روّجت لها صفحة توثيق صراحة على أنها عامة. -### إدخال plugin +### إدخال الإضافة -| المسار الفرعي | أهم exports | +| المسار الفرعي | الصادرات الأساسية | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `plugin-sdk/plugin-entry` | `definePluginEntry` | | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | @@ -77,281 +77,286 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; - | المسار الفرعي | أهم exports | + | المسار الفرعي | الصادرات الأساسية | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/config-schema` | export مخطط Zod الجذر لـ `openclaw.json` ‏(`OpenClawSchema`) | + | `plugin-sdk/config-schema` | تصدير مخطط Zod الجذر لـ `openclaw.json` (`OpenClawSchema`) | | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`، بالإضافة إلى `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | مساعدات wizard المشتركة للإعداد، ومطالبات allowlist، وبناة حالة الإعداد | + | `plugin-sdk/setup` | مساعدات معالج الإعداد المشتركة، ومطالبات قائمة السماح، وبناة حالة الإعداد | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | مساعدات إعدادات/بوابة إجراءات متعددة الحسابات، ومساعدات fallback الخاصة بالحساب الافتراضي | + | `plugin-sdk/account-core` | مساعدات تكوين/بوابة إجراء الحسابات المتعددة ومساعدات الرجوع إلى الحساب الافتراضي | | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`، ومساعدات تطبيع معرّف الحساب | - | `plugin-sdk/account-resolution` | مساعدات البحث عن الحساب + fallback الافتراضي | - | `plugin-sdk/account-helpers` | مساعدات ضيقة لقوائم الحسابات/إجراءات الحساب | + | `plugin-sdk/account-resolution` | مساعدات البحث عن الحساب + الرجوع إلى الافتراضي | + | `plugin-sdk/account-helpers` | مساعدات ضيقة لقائمة الحسابات/إجراءات الحساب | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | أنواع مخطط إعدادات القناة | - | `plugin-sdk/telegram-command-config` | مساعدات تطبيع/تحقق أوامر Telegram المخصصة مع fallback لعقد مجمّع | + | `plugin-sdk/channel-config-schema` | أنواع مخطط تكوين القناة | + | `plugin-sdk/telegram-command-config` | مساعدات تطبيع/تحقق للأوامر المخصصة في Telegram مع رجوع إلى العقدة المضمّنة | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | مساعدات مشتركة لبناء route + envelope للوارد | - | `plugin-sdk/inbound-reply-dispatch` | مساعدات مشتركة لتسجيل وإرسال الردود الواردة | + | `plugin-sdk/inbound-envelope` | مساعدات بناء المسار والمغلف المشترك للرسائل الواردة | + | `plugin-sdk/inbound-reply-dispatch` | مساعدات التسجيل والإرسال المشتركة للرسائل الواردة | | `plugin-sdk/messaging-targets` | مساعدات تحليل/مطابقة الأهداف | - | `plugin-sdk/outbound-media` | مساعدات مشتركة لتحميل الوسائط الصادرة | - | `plugin-sdk/outbound-runtime` | مساعدات هوية الصادر/تفويض الإرسال | - | `plugin-sdk/thread-bindings-runtime` | مساعدات دورة حياة thread-binding وadapter | - | `plugin-sdk/agent-media-payload` | باني قديم لحمولة وسائط الوكيل | - | `plugin-sdk/conversation-runtime` | مساعدات الربط بالمحادثة/الخيط، والاقتران، والربط المُعد | - | `plugin-sdk/runtime-config-snapshot` | مساعد لقطة إعدادات وقت التشغيل | - | `plugin-sdk/runtime-group-policy` | مساعدات تحليل group-policy في وقت التشغيل | - | `plugin-sdk/channel-status` | مساعدات مشتركة للقطات/ملخصات حالة القناة | - | `plugin-sdk/channel-config-primitives` | بدائيات ضيقة لمخطط إعدادات القناة | - | `plugin-sdk/channel-config-writes` | مساعدات تفويض كتابة إعدادات القناة | - | `plugin-sdk/channel-plugin-common` | exports تمهيدية مشتركة لـ Channel plugin | - | `plugin-sdk/allowlist-config-edit` | مساعدات قراءة/تحرير إعدادات allowlist | - | `plugin-sdk/group-access` | مساعدات مشتركة لقرارات الوصول إلى المجموعات | - | `plugin-sdk/direct-dm` | مساعدات مشتركة لمصادقة/حراسة الرسائل الخاصة المباشرة | - | `plugin-sdk/interactive-runtime` | مساعدات تطبيع/تقليص حمولة الرد التفاعلي | - | `plugin-sdk/channel-inbound` | مساعدات إزالة ارتداد الوارد، ومطابقة الإشارات، وسياسة الإشارة، وenvelope | - | `plugin-sdk/channel-send-result` | أنواع نتائج الرد | + | `plugin-sdk/outbound-media` | مساعدات تحميل الوسائط الصادرة المشتركة | + | `plugin-sdk/outbound-runtime` | مساعدات هوية/تفويض الإرسال الصادر | + | `plugin-sdk/thread-bindings-runtime` | مساعدات دورة حياة وموائمات ربط الخيوط | + | `plugin-sdk/agent-media-payload` | باني حمولة وسائط الوكيل القديم | + | `plugin-sdk/conversation-runtime` | مساعدات المحادثة/ربط الخيوط/الإقران/الربط المهيأ | + | `plugin-sdk/runtime-config-snapshot` | مساعد أخذ لقطة من تكوين وقت التشغيل | + | `plugin-sdk/runtime-group-policy` | مساعدات حل سياسة المجموعة في وقت التشغيل | + | `plugin-sdk/channel-status` | مساعدات اللقطة/الملخص المشتركة لحالة القناة | + | `plugin-sdk/channel-config-primitives` | بدائيات ضيقة لمخطط تكوين القناة | + | `plugin-sdk/channel-config-writes` | مساعدات تفويض كتابة تكوين القناة | + | `plugin-sdk/channel-plugin-common` | صادرات تمهيدية مشتركة لإضافات القنوات | + | `plugin-sdk/allowlist-config-edit` | مساعدات قراءة/تحرير تكوين قائمة السماح | + | `plugin-sdk/group-access` | مساعدات مشتركة لاتخاذ قرار وصول المجموعة | + | `plugin-sdk/direct-dm` | مساعدات مشتركة لمصادقة/حماية الرسائل المباشرة المباشرة | + | `plugin-sdk/interactive-runtime` | مساعدات تطبيع/اختزال حمولة الرد التفاعلي | + | `plugin-sdk/channel-inbound` | مساعدات إزالة الارتداد، ومطابقة الذكر، وسياسة الذكر للرسائل الواردة، ومساعدات المغلف | + | `plugin-sdk/channel-send-result` | أنواع نتيجة الرد | | `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` | | `plugin-sdk/channel-targets` | مساعدات تحليل/مطابقة الأهداف | | `plugin-sdk/channel-contract` | أنواع عقد القناة | - | `plugin-sdk/channel-feedback` | توصيل feedback/reaction | - | `plugin-sdk/channel-secret-runtime` | مساعدات ضيقة لعقود الأسرار مثل `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment` وأنواع أهداف الأسرار | + | `plugin-sdk/channel-feedback` | أسلاك التغذية الراجعة/التفاعلات | + | `plugin-sdk/channel-secret-runtime` | مساعدات ضيقة لعقد الأسرار مثل `collectSimpleChannelFieldAssignments` و`getChannelSurface` و`pushAssignment` وأنواع أهداف الأسرار | - - | المسار الفرعي | أهم exports | + + | المسار الفرعي | الصادرات الأساسية | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/provider-setup` | مساعدات إعداد منتقاة للمزودات المحلية/المستضافة ذاتيًا | - | `plugin-sdk/self-hosted-provider-setup` | مساعدات إعداد مركزة لمزودات OpenAI-compatible المستضافة ذاتيًا | - | `plugin-sdk/cli-backend` | قيم افتراضية لـ CLI backend + ثوابت watchdog | - | `plugin-sdk/provider-auth-runtime` | مساعدات وقت التشغيل لتحليل API key الخاصة بـ Provider plugins | - | `plugin-sdk/provider-auth-api-key` | مساعدات onboarding/كتابة profile لمفتاح API مثل `upsertApiKeyProfile` | - | `plugin-sdk/provider-auth-result` | باني auth-result قياسي لـ OAuth | - | `plugin-sdk/provider-auth-login` | مساعدات تسجيل دخول تفاعلية مشتركة لـ Provider plugins | - | `plugin-sdk/provider-env-vars` | مساعدات البحث عن متغيرات البيئة لمصادقة المزود | + | `plugin-sdk/provider-setup` | مساعدات منسقة لإعداد الموفّرات المحلية/المستضافة ذاتيًا | + | `plugin-sdk/self-hosted-provider-setup` | مساعدات إعداد مركزة لموفّرات مستضافة ذاتيًا متوافقة مع OpenAI | + | `plugin-sdk/cli-backend` | القيم الافتراضية للواجهة الخلفية لـ CLI + ثوابت المراقبة | + | `plugin-sdk/provider-auth-runtime` | مساعدات حل مفاتيح API وقت التشغيل لإضافات الموفّرات | + | `plugin-sdk/provider-auth-api-key` | مساعدات الإلحاق/الكتابة في الملف الشخصي لمفتاح API مثل `upsertApiKeyProfile` | + | `plugin-sdk/provider-auth-result` | باني نتيجة مصادقة OAuth القياسي | + | `plugin-sdk/provider-auth-login` | مساعدات تسجيل الدخول التفاعلية المشتركة لإضافات الموفّرات | + | `plugin-sdk/provider-env-vars` | مساعدات البحث عن متغيرات بيئة مصادقة الموفّر | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`، وبناة replay-policy المشتركون، ومساعدات endpoint للمزود، ومساعدات تطبيع model-id مثل `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`، وبناة سياسة الإعادة المشتركة، ومساعدات نقطة نهاية الموفّر، ومساعدات تطبيع معرّف النموذج مثل `normalizeNativeXaiModelId` | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | مساعدات عامة لقدرات HTTP/endpoint الخاصة بالمزود | - | `plugin-sdk/provider-web-fetch` | مساعدات التسجيل/cache لمزود web-fetch | - | `plugin-sdk/provider-web-search-contract` | مساعدات ضيقة لعقود إعدادات/بيانات اعتماد web-search مثل `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`، ومعينات set/get لبيانات اعتماد محددة النطاق | - | `plugin-sdk/provider-web-search` | مساعدات التسجيل/cache/وقت التشغيل لمزود web-search | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`، وتنظيف/تشخيص مخطط Gemini، ومساعدات توافق xAI مثل `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | `fetchClaudeUsage` وما شابه | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`، وأنواع stream wrapper، ومساعدات wrappers المشتركة لـ Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-onboard` | مساعدات تعديل إعدادات onboarding | - | `plugin-sdk/global-singleton` | مساعدات singleton/map/cache محلية للعملية | + | `plugin-sdk/provider-http` | مساعدات عامة لقدرات HTTP/نقطة النهاية الخاصة بالموفّر | + | `plugin-sdk/provider-web-fetch-contract` | مساعدات ضيقة لعقود تكوين/اختيار web-fetch مثل `enablePluginInConfig` و`WebFetchProviderPlugin` | + | `plugin-sdk/provider-web-fetch` | مساعدات تسجيل/ذاكرة التخزين المؤقت لموفّر web-fetch | + | `plugin-sdk/provider-web-search-contract` | مساعدات ضيقة لعقود تكوين/بيانات اعتماد web-search مثل `enablePluginInConfig` و`resolveProviderWebSearchPluginConfig` وضبط/جلب بيانات الاعتماد ذات النطاق | + | `plugin-sdk/provider-web-search` | مساعدات التسجيل/الذاكرة المؤقتة/وقت التشغيل لموفّر web-search | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`، وتنظيف مخطط Gemini + التشخيصات، ومساعدات التوافق مع xAI مثل `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | `fetchClaudeUsage` وما شابهها | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`، وأنواع مغطيات البث، ومساعدات المغطيات المشتركة لـ Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-onboard` | مساعدات ترقيع تكوين الإعداد الأولي | + | `plugin-sdk/global-singleton` | مساعدات القيم المفردة/الخرائط/الذاكرات المؤقتة المحلية للعملية | - | المسار الفرعي | أهم exports | + | المسار الفرعي | الصادرات الأساسية | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`، ومساعدات سجل الأوامر، ومساعدات تفويض المرسل | - | `plugin-sdk/approval-auth-runtime` | مساعدات تحليل approver ومصادقة الإجراء في نفس الدردشة | - | `plugin-sdk/approval-client-runtime` | مساعدات ملفات التعريف/المرشحات الأصلية لـ exec approval | - | `plugin-sdk/approval-delivery-runtime` | محولات القدرات/التسليم الأصلية لـ approval | - | `plugin-sdk/approval-native-runtime` | مساعدات الهدف الأصلي لـ approval + ربط الحساب | - | `plugin-sdk/approval-reply-runtime` | مساعدات حمولة الرد لـ exec/plugin approval | - | `plugin-sdk/command-auth-native` | مصادقة الأوامر الأصلية + مساعدات الهدف الأصلي للجلسة | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`، ومساعدات سجل الأوامر، ومساعدات تفويض المرسِل | + | `plugin-sdk/approval-auth-runtime` | مساعدات حل الموافقين ومصادقة الإجراء في نفس الدردشة | + | `plugin-sdk/approval-client-runtime` | مساعدات الملف الشخصي/المرشح للموافقات الأصلية لـ exec | + | `plugin-sdk/approval-delivery-runtime` | موائمات قدرات/تسليم الموافقات الأصلية | + | `plugin-sdk/approval-gateway-runtime` | مساعد مشترك لحل بوابة الموافقات | + | `plugin-sdk/approval-handler-adapter-runtime` | مساعدات خفيفة لتحميل موائم الموافقات الأصلية لنقاط إدخال القنوات الساخنة | + | `plugin-sdk/approval-handler-runtime` | مساعدات أوسع لوقت تشغيل معالج الموافقات؛ فضّل المسارات الأضيق الخاصة بالموائم/البوابة عندما تكون كافية | + | `plugin-sdk/approval-native-runtime` | مساعدات الهدف الأصلي للموافقات + ربط الحساب | + | `plugin-sdk/approval-reply-runtime` | مساعدات حمولة رد موافقات exec/الإضافة | + | `plugin-sdk/command-auth-native` | مساعدات مصادقة الأوامر الأصلية + أهداف الجلسات الأصلية | | `plugin-sdk/command-detection` | مساعدات مشتركة لاكتشاف الأوامر | - | `plugin-sdk/command-surface` | تطبيع نص الأمر ومساعدات سطح الأمر | + | `plugin-sdk/command-surface` | تطبيع جسم الأمر ومساعدات سطح الأوامر | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | مساعدات ضيقة لتجميع عقود الأسرار لأسطح أسرار القناة/الـ plugin | - | `plugin-sdk/secret-ref-runtime` | مساعدات ضيقة لـ `coerceSecretRef` وأنواع SecretRef لتحليل عقود الأسرار/الإعدادات | - | `plugin-sdk/security-runtime` | مساعدات مشتركة للثقة، وتقييد DM، والمحتوى الخارجي، وتجميع الأسرار | - | `plugin-sdk/ssrf-policy` | مساعدات allowlist للمضيف وسياسة SSRF للشبكات الخاصة | - | `plugin-sdk/ssrf-runtime` | مساعدات pinned-dispatcher وfetch المحروس بـ SSRF وسياسة SSRF | - | `plugin-sdk/secret-input` | مساعدات تحليل مدخلات الأسرار | - | `plugin-sdk/webhook-ingress` | مساعدات طلب/هدف webhook | - | `plugin-sdk/webhook-request-guards` | مساعدات حجم جسم الطلب/المهلة | + | `plugin-sdk/channel-secret-runtime` | مساعدات ضيقة لتجميع عقود الأسرار لأسطح أسرار القناة/الإضافة | + | `plugin-sdk/secret-ref-runtime` | مساعدات ضيقة لـ `coerceSecretRef` وكتابة SecretRef لتحليل عقود الأسرار/التكوين | + | `plugin-sdk/security-runtime` | مساعدات مشتركة للثقة، وبوابات الرسائل المباشرة، والمحتوى الخارجي، وتجميع الأسرار | + | `plugin-sdk/ssrf-policy` | مساعدات قائمة السماح للمضيف وسياسة SSRF للشبكات الخاصة | + | `plugin-sdk/ssrf-runtime` | مساعدات المرسِل المثبّت، والجلب المحمي بـ SSRF، وسياسة SSRF | + | `plugin-sdk/secret-input` | مساعدات تحليل إدخال الأسرار | + | `plugin-sdk/webhook-ingress` | مساعدات طلب/هدف Webhook | + | `plugin-sdk/webhook-request-guards` | مساعدات حجم جسم الطلب/المهلة الزمنية | - | المسار الفرعي | أهم exports | + | المسار الفرعي | الصادرات الأساسية | | --- | --- | - | `plugin-sdk/runtime` | مساعدات واسعة لوقت التشغيل/التسجيل/النسخ الاحتياطي/تثبيت plugin | - | `plugin-sdk/runtime-env` | مساعدات ضيقة لبيئة وقت التشغيل، وlogger، والمهلة، وإعادة المحاولة، وbackoff | + | `plugin-sdk/runtime` | مساعدات عامة لوقت التشغيل/السجلات/النسخ الاحتياطي/تثبيت الإضافات | + | `plugin-sdk/runtime-env` | مساعدات ضيقة لبيئة وقت التشغيل، والمسجل، والمهلة، وإعادة المحاولة، وbackoff | + | `plugin-sdk/channel-runtime-context` | مساعدات عامة لتسجيل والبحث عن سياق وقت تشغيل القناة | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | مساعدات مشتركة لأوامر/خطافات/HTTP/التفاعلية الخاصة بالـ plugin | - | `plugin-sdk/hook-runtime` | مساعدات مشتركة لخطوط webhook/internal hook | - | `plugin-sdk/lazy-runtime` | مساعدات الاستيراد/الربط الكسول لوقت التشغيل مثل `createLazyRuntimeModule`, `createLazyRuntimeMethod`, و`createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | مساعدات تنفيذ العمليات | - | `plugin-sdk/cli-runtime` | مساعدات تنسيق CLI، والانتظار، والإصدار | - | `plugin-sdk/gateway-runtime` | مساعدات عميل Gateway وتعديل حالة القناة | - | `plugin-sdk/config-runtime` | مساعدات تحميل/كتابة الإعدادات | - | `plugin-sdk/telegram-command-config` | مساعدات تطبيع أسماء/أوصاف أوامر Telegram والتحقق من التكرار/التعارض، حتى عند عدم توفر سطح عقد Telegram المضمّن | - | `plugin-sdk/approval-runtime` | مساعدات exec/plugin approval، وبناة approval-capability، ومساعدات المصادقة/profile، ومساعدات التوجيه/وقت التشغيل الأصلية | - | `plugin-sdk/reply-runtime` | مساعدات مشتركة لوقت تشغيل الوارد/الرد، والتجزئة، والإرسال، وheartbeat، ومخطط الرد | + | `plugin-sdk/plugin-runtime` | مساعدات مشتركة لأوامر/خطافات/http/التفاعل الخاصة بالإضافةات | + | `plugin-sdk/hook-runtime` | مساعدات مشتركة لمسار Webhook/الخطافات الداخلية | + | `plugin-sdk/lazy-runtime` | مساعدات الاستيراد/الربط الكسول لوقت التشغيل مثل `createLazyRuntimeModule` و`createLazyRuntimeMethod` و`createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | مساعدات تنفيذ العملية | + | `plugin-sdk/cli-runtime` | مساعدات التنسيق والانتظار والإصدار لـ CLI | + | `plugin-sdk/gateway-runtime` | مساعدات عميل البوابة وترقيعات حالة القناة | + | `plugin-sdk/config-runtime` | مساعدات تحميل/كتابة التكوين | + | `plugin-sdk/telegram-command-config` | تطبيع اسم/وصف أمر Telegram وفحوصات التكرار/التعارض، حتى عند غياب سطح عقد Telegram المضمّن | + | `plugin-sdk/approval-runtime` | مساعدات موافقات exec/الإضافة، وبناة قدرات الموافقة، ومساعدات المصادقة/الملف الشخصي، ومساعدات التوجيه/وقت التشغيل الأصلية | + | `plugin-sdk/reply-runtime` | مساعدات مشتركة لوقت تشغيل الوارد/الرد، والتجزئة، والإرسال، والنبض، ومخطط الرد | | `plugin-sdk/reply-dispatch-runtime` | مساعدات ضيقة لإرسال/إنهاء الرد | - | `plugin-sdk/reply-history` | مساعدات مشتركة لسجل الرد قصير النافذة مثل `buildHistoryContext`, `recordPendingHistoryEntry`, و`clearHistoryEntriesIfEnabled` | + | `plugin-sdk/reply-history` | مساعدات مشتركة لسجل الردود ذي النافذة القصيرة مثل `buildHistoryContext` و`recordPendingHistoryEntry` و`clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | | `plugin-sdk/reply-chunking` | مساعدات ضيقة لتجزئة النص/Markdown | - | `plugin-sdk/session-store-runtime` | مساعدات مسار مخزن الجلسة + updated-at | - | `plugin-sdk/state-paths` | مساعدات مسارات الحالة/OAuth | - | `plugin-sdk/routing` | مساعدات route/session-key وربط الحساب مثل `resolveAgentRoute`, `buildAgentSessionKey`, و`resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | مساعدات مشتركة لملخصات حالة القناة/الحساب، والقيم الافتراضية لحالة وقت التشغيل، ومساعدات بيانات issue الوصفية | - | `plugin-sdk/target-resolver-runtime` | مساعدات مشتركة لتحليل الأهداف | - | `plugin-sdk/string-normalization-runtime` | مساعدات تطبيع slug/string | + | `plugin-sdk/session-store-runtime` | مساعدات مسار مخزن الجلسة و`updated-at` | + | `plugin-sdk/state-paths` | مساعدات مسارات الحالة/دليل OAuth | + | `plugin-sdk/routing` | مساعدات المسار/مفتاح الجلسة/ربط الحساب مثل `resolveAgentRoute` و`buildAgentSessionKey` و`resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | مساعدات مشتركة لملخص حالة القناة/الحساب، والقيم الافتراضية لحالة وقت التشغيل، ومساعدات بيانات تعريف المشكلات | + | `plugin-sdk/target-resolver-runtime` | مساعدات مشتركة لحل الأهداف | + | `plugin-sdk/string-normalization-runtime` | مساعدات تطبيع السلاسل/slug | | `plugin-sdk/request-url` | استخراج عناوين URL النصية من مدخلات شبيهة بـ fetch/request | - | `plugin-sdk/run-command` | مُشغّل أوامر موقّت بنتائج stdout/stderr مطبّعة | + | `plugin-sdk/run-command` | مشغل أوامر مؤقت بنتائج stdout/stderr مطبعة | | `plugin-sdk/param-readers` | قارئات معلمات شائعة للأدوات/CLI | - | `plugin-sdk/tool-send` | استخراج حقول هدف الإرسال القياسية من وسيطات الأداة | - | `plugin-sdk/temp-path` | مساعدات مشتركة لمسارات التنزيل المؤقت | - | `plugin-sdk/logging-core` | مساعدات logger الخاصة بالأنظمة الفرعية وإخفاء البيانات | - | `plugin-sdk/markdown-table-runtime` | مساعدات وضع جداول Markdown | + | `plugin-sdk/tool-send` | استخراج حقول هدف الإرسال القياسية من وسائط الأداة | + | `plugin-sdk/temp-path` | مساعدات مشتركة لمسار التنزيل المؤقت | + | `plugin-sdk/logging-core` | مساعدات المسجل الفرعي والتنقيح | + | `plugin-sdk/markdown-table-runtime` | مساعدات أوضاع جداول Markdown | | `plugin-sdk/json-store` | مساعدات صغيرة لقراءة/كتابة حالة JSON | - | `plugin-sdk/file-lock` | مساعدات file-lock قابلة لإعادة الدخول | - | `plugin-sdk/persistent-dedupe` | مساعدات cache لإزالة التكرار مدعومة بالقرص | - | `plugin-sdk/acp-runtime` | مساعدات وقت تشغيل ACP/session وإرسال الرد | - | `plugin-sdk/agent-config-primitives` | بدائيات ضيقة لمخطط إعدادات وقت تشغيل الوكيل | - | `plugin-sdk/boolean-param` | قارئ مرن لمعامل boolean | - | `plugin-sdk/dangerous-name-runtime` | مساعدات تحليل مطابقة الأسماء الخطرة | - | `plugin-sdk/device-bootstrap` | مساعدات bootstrap للجهاز ورمز الاقتران | - | `plugin-sdk/extension-shared` | بدائيات مساعدة مشتركة للقنوات السلبية، والحالة، والـ ambient proxy | - | `plugin-sdk/models-provider-runtime` | مساعدات الرد لأمر `/models`/المزود | + | `plugin-sdk/file-lock` | مساعدات إعادة الدخول لقفل الملفات | + | `plugin-sdk/persistent-dedupe` | مساعدات ذاكرة التخزين المؤقت لإزالة التكرار المدعومة بالقرص | + | `plugin-sdk/acp-runtime` | مساعدات ACP وقت التشغيل/الجلسة وإرسال الرد | + | `plugin-sdk/agent-config-primitives` | بدائيات ضيقة لمخطط تكوين وقت تشغيل الوكيل | + | `plugin-sdk/boolean-param` | قارئ معلمات منطقي مرن | + | `plugin-sdk/dangerous-name-runtime` | مساعدات حل مطابقة الأسماء الخطرة | + | `plugin-sdk/device-bootstrap` | مساعدات bootstrap للجهاز ورمز الإقران | + | `plugin-sdk/extension-shared` | بدائيات مشتركة لمساعدات القنوات السلبية، والحالة، والوكيل المحيط | + | `plugin-sdk/models-provider-runtime` | مساعدات أوامر `/models` / ردود الموفّر | | `plugin-sdk/skill-commands-runtime` | مساعدات سرد أوامر Skills | - | `plugin-sdk/native-command-registry` | مساعدات السجل الأصلي للأوامر/البناء/التسلسل | - | `plugin-sdk/provider-zai-endpoint` | مساعدات اكتشاف endpoint لـ Z.A.I | - | `plugin-sdk/infra-runtime` | مساعدات أحداث النظام/heartbeat | - | `plugin-sdk/collection-runtime` | مساعدات صغيرة لـ cache محدود | - | `plugin-sdk/diagnostic-runtime` | مساعدات الأعلام التشخيصية والأحداث | - | `plugin-sdk/error-runtime` | رسم الأخطاء، والتنسيق، ومساعدات تصنيف الأخطاء المشتركة، و`isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | مساعدات fetch مغلف، وproxy، والبحث المثبت | + | `plugin-sdk/native-command-registry` | مساعدات سجل/بناء/تسلسل الأوامر الأصلية | + | `plugin-sdk/provider-zai-endpoint` | مساعدات اكتشاف نقطة نهاية Z.A.I | + | `plugin-sdk/infra-runtime` | مساعدات أحداث النظام/النبض | + | `plugin-sdk/collection-runtime` | مساعدات صغيرة لذاكرة تخزين مؤقتة محدودة | + | `plugin-sdk/diagnostic-runtime` | مساعدات أعلام التشخيص والأحداث | + | `plugin-sdk/error-runtime` | مساعدات رسم الأخطاء، والتنسيق، وتصنيف الأخطاء المشتركة، و`isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | مساعدات fetch المغلّفة، والوكيل، والبحث المثبّت | | `plugin-sdk/host-runtime` | مساعدات تطبيع اسم المضيف ومضيف SCP | - | `plugin-sdk/retry-runtime` | إعدادات إعادة المحاولة ومساعدات مشغّل الإعادة | - | `plugin-sdk/agent-runtime` | مساعدات دليل الوكيل/الهوية/workspace | - | `plugin-sdk/directory-runtime` | query/dedup للأدلة المدعومة بالإعدادات | + | `plugin-sdk/retry-runtime` | مساعدات تكوين إعادة المحاولة ومشغّل إعادة المحاولة | + | `plugin-sdk/agent-runtime` | مساعدات دليل/هوية/مساحة عمل الوكيل | + | `plugin-sdk/directory-runtime` | استعلام/إزالة تكرار الدليل المدعوم بالتكوين | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | - | المسار الفرعي | أهم exports | + | المسار الفرعي | الصادرات الأساسية | | --- | --- | - | `plugin-sdk/media-runtime` | مساعدات مشتركة لجلب/تحويل/تخزين الوسائط بالإضافة إلى بناة حمولة الوسائط | - | `plugin-sdk/media-generation-runtime` | مساعدات مشتركة لفشل-over في توليد الوسائط، واختيار candidates، ورسائل النماذج المفقودة | - | `plugin-sdk/media-understanding` | أنواع مزود فهم الوسائط بالإضافة إلى exports مساعدة موجهة للمزود للصورة/الصوت | - | `plugin-sdk/text-runtime` | مساعدات مشتركة للنص/Markdown/التسجيل مثل إزالة النص المرئي للمساعد، ومساعدات render/chunking/table الخاصة بـ Markdown، ومساعدات إخفاء البيانات، وdirective-tag، وأدوات النص الآمن | + | `plugin-sdk/media-runtime` | مساعدات مشتركة لجلب/تحويل/تخزين الوسائط بالإضافة إلى بناة حمولات الوسائط | + | `plugin-sdk/media-generation-runtime` | مساعدات مشتركة للإخفاق المرحلي في توليد الوسائط، واختيار المرشحين، ورسائل النماذج المفقودة | + | `plugin-sdk/media-understanding` | أنواع موفّر فهم الوسائط بالإضافة إلى صادرات مساعدات الصور/الصوت المواجهة للموفّر | + | `plugin-sdk/text-runtime` | مساعدات مشتركة للنص/Markdown/السجلات مثل إزالة النص المرئي للمساعد، ومساعدات عرض/تجزئة/جداول Markdown، ومساعدات التنقيح، ووسوم التوجيه، وأدوات النص الآمن | | `plugin-sdk/text-chunking` | مساعد تجزئة النص الصادر | - | `plugin-sdk/speech` | أنواع مزود الكلام بالإضافة إلى exports موجهة للمزود خاصة بالتوجيه، والسجل، والتحقق | - | `plugin-sdk/speech-core` | أنواع مشتركة لمزود الكلام، والسجل، والتوجيه، ومساعدات التطبيع | - | `plugin-sdk/realtime-transcription` | أنواع مزود النسخ الفوري ومساعدات السجل | - | `plugin-sdk/realtime-voice` | أنواع مزود الصوت الفوري ومساعدات السجل | - | `plugin-sdk/image-generation` | أنواع مزود توليد الصور | - | `plugin-sdk/image-generation-core` | أنواع مشتركة لتوليد الصور، والفشل-over، والمصادقة، ومساعدات السجل | - | `plugin-sdk/music-generation` | أنواع الطلب/النتيجة/المزود لتوليد الموسيقى | - | `plugin-sdk/music-generation-core` | أنواع مشتركة لتوليد الموسيقى، ومساعدات failover، والبحث عن المزود، وتحليل model-ref | - | `plugin-sdk/video-generation` | أنواع الطلب/النتيجة/المزود لتوليد الفيديو | - | `plugin-sdk/video-generation-core` | أنواع مشتركة لتوليد الفيديو، ومساعدات failover، والبحث عن المزود، وتحليل model-ref | - | `plugin-sdk/webhook-targets` | سجل أهداف webhook ومساعدات تثبيت المسارات | - | `plugin-sdk/webhook-path` | مساعدات تطبيع مسار webhook | + | `plugin-sdk/speech` | أنواع موفّر الكلام بالإضافة إلى مساعدات التوجيه، والسجل، والتحقق المواجهة للموفّر | + | `plugin-sdk/speech-core` | أنواع موفّر الكلام المشتركة، والسجل، والتوجيه، ومساعدات التطبيع | + | `plugin-sdk/realtime-transcription` | أنواع موفّر النسخ الفوري ومساعدات السجل | + | `plugin-sdk/realtime-voice` | أنواع موفّر الصوت الفوري ومساعدات السجل | + | `plugin-sdk/image-generation` | أنواع موفّر توليد الصور | + | `plugin-sdk/image-generation-core` | أنواع توليد الصور المشتركة، والإخفاق المرحلي، والمصادقة، ومساعدات السجل | + | `plugin-sdk/music-generation` | أنواع موفّر/طلب/نتيجة توليد الموسيقى | + | `plugin-sdk/music-generation-core` | أنواع توليد الموسيقى المشتركة، ومساعدات الإخفاق المرحلي، والبحث عن الموفّر، وتحليل مرجع النموذج | + | `plugin-sdk/video-generation` | أنواع موفّر/طلب/نتيجة توليد الفيديو | + | `plugin-sdk/video-generation-core` | أنواع توليد الفيديو المشتركة، ومساعدات الإخفاق المرحلي، والبحث عن الموفّر، وتحليل مرجع النموذج | + | `plugin-sdk/webhook-targets` | سجل أهداف Webhook ومساعدات تثبيت المسارات | + | `plugin-sdk/webhook-path` | مساعدات تطبيع مسار Webhook | | `plugin-sdk/web-media` | مساعدات مشتركة لتحميل الوسائط البعيدة/المحلية | - | `plugin-sdk/zod` | إعادة export لـ `zod` لمستهلكي Plugin SDK | + | `plugin-sdk/zod` | إعادة تصدير `zod` لمستهلكي Plugin SDK | | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | - | المسار الفرعي | أهم exports | + | المسار الفرعي | الصادرات الأساسية | | --- | --- | - | `plugin-sdk/memory-core` | سطح مساعد memory-core المضمّن لمساعدات manager/config/file/CLI | - | `plugin-sdk/memory-core-engine-runtime` | واجهة وقت تشغيل لفهرسة/بحث الذاكرة | - | `plugin-sdk/memory-core-host-engine-foundation` | exports محرك الأساس لمضيف الذاكرة | - | `plugin-sdk/memory-core-host-engine-embeddings` | exports محرك embeddings لمضيف الذاكرة | - | `plugin-sdk/memory-core-host-engine-qmd` | exports محرك QMD لمضيف الذاكرة | - | `plugin-sdk/memory-core-host-engine-storage` | exports محرك التخزين لمضيف الذاكرة | - | `plugin-sdk/memory-core-host-multimodal` | مساعدات متعددة الوسائط لمضيف الذاكرة | - | `plugin-sdk/memory-core-host-query` | مساعدات الاستعلام لمضيف الذاكرة | + | `plugin-sdk/memory-core` | سطح مساعد memory-core المضمّن لمساعدات المدير/التكوين/الملف/CLI | + | `plugin-sdk/memory-core-engine-runtime` | واجهة وقت التشغيل لفهرسة/بحث الذاكرة | + | `plugin-sdk/memory-core-host-engine-foundation` | صادرات محرك الأساس لمضيف الذاكرة | + | `plugin-sdk/memory-core-host-engine-embeddings` | صادرات محرك embeddings لمضيف الذاكرة | + | `plugin-sdk/memory-core-host-engine-qmd` | صادرات محرك QMD لمضيف الذاكرة | + | `plugin-sdk/memory-core-host-engine-storage` | صادرات محرك التخزين لمضيف الذاكرة | + | `plugin-sdk/memory-core-host-multimodal` | مساعدات الوسائط المتعددة لمضيف الذاكرة | + | `plugin-sdk/memory-core-host-query` | مساعدات استعلام مضيف الذاكرة | | `plugin-sdk/memory-core-host-secret` | مساعدات الأسرار لمضيف الذاكرة | - | `plugin-sdk/memory-core-host-events` | مساعدات سجل أحداث مضيف الذاكرة | + | `plugin-sdk/memory-core-host-events` | مساعدات دفتر أحداث مضيف الذاكرة | | `plugin-sdk/memory-core-host-status` | مساعدات حالة مضيف الذاكرة | - | `plugin-sdk/memory-core-host-runtime-cli` | مساعدات CLI الخاصة بوقت تشغيل مضيف الذاكرة | - | `plugin-sdk/memory-core-host-runtime-core` | مساعدات core لوقت تشغيل مضيف الذاكرة | + | `plugin-sdk/memory-core-host-runtime-cli` | مساعدات CLI وقت التشغيل لمضيف الذاكرة | + | `plugin-sdk/memory-core-host-runtime-core` | مساعدات وقت التشغيل الأساسية لمضيف الذاكرة | | `plugin-sdk/memory-core-host-runtime-files` | مساعدات الملفات/وقت التشغيل لمضيف الذاكرة | - | `plugin-sdk/memory-host-core` | اسم مستعار محايد للمورّد لمساعدات core لوقت تشغيل مضيف الذاكرة | - | `plugin-sdk/memory-host-events` | اسم مستعار محايد للمورّد لمساعدات سجل أحداث مضيف الذاكرة | + | `plugin-sdk/memory-host-core` | اسم مستعار محايد للمورّد لمساعدات وقت التشغيل الأساسية لمضيف الذاكرة | + | `plugin-sdk/memory-host-events` | اسم مستعار محايد للمورّد لمساعدات دفتر أحداث مضيف الذاكرة | | `plugin-sdk/memory-host-files` | اسم مستعار محايد للمورّد لمساعدات الملفات/وقت التشغيل لمضيف الذاكرة | - | `plugin-sdk/memory-host-markdown` | مساعدات managed-Markdown مشتركة للـ plugins القريبة من الذاكرة | - | `plugin-sdk/memory-host-search` | واجهة وقت تشغيل الذاكرة النشطة للوصول إلى search-manager | + | `plugin-sdk/memory-host-markdown` | مساعدات Markdown المُدار المشتركة للإضافات المجاورة للذاكرة | + | `plugin-sdk/memory-host-search` | واجهة وقت تشغيل الذاكرة النشطة للوصول إلى مدير البحث | | `plugin-sdk/memory-host-status` | اسم مستعار محايد للمورّد لمساعدات حالة مضيف الذاكرة | | `plugin-sdk/memory-lancedb` | سطح مساعد memory-lancedb المضمّن | - + | العائلة | المسارات الفرعية الحالية | الاستخدام المقصود | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | مساعدات دعم Browser plugin المضمّن (`browser-support` يبقى barrel التوافقية) | + | المتصفح | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | مساعدات دعم إضافة المتصفح المضمّنة (`browser-support` يبقى الشريط المتوافق) | | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | سطح مساعد/وقت تشغيل Matrix المضمّن | | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | سطح مساعد/وقت تشغيل LINE المضمّن | | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | سطح مساعد IRC المضمّن | - | مساعدات خاصة بالقنوات | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | نقاط ربط التوافق/المساعدة للقنوات المضمنة | - | مساعدات خاصة بالمصادقة/الـ plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | نقاط ربط مساعدة للميزات/الـ plugins المضمنة؛ ويقوم `plugin-sdk/github-copilot-token` حاليًا بتصدير `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken`, و`resolveCopilotApiToken` | + | مساعدات خاصة بالقنوات | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | مسارات توافق/مساعدات القنوات المضمّنة | + | مساعدات خاصة بالمصادقة/الإضافة | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | مسارات مساعدات الميزات/الإضافات المضمّنة؛ يصدّر `plugin-sdk/github-copilot-token` حاليًا `DEFAULT_COPILOT_API_BASE_URL` و`deriveCopilotApiBaseUrlFromToken` و`resolveCopilotApiToken` | ## API التسجيل -يتلقى callback الخاص بـ `register(api)` كائن `OpenClawPluginApi` يحوي -هذه الأساليب: +يتلقى استدعاء `register(api)` كائن `OpenClawPluginApi` بهذه +الأساليب: ### تسجيل القدرات | الأسلوب | ما الذي يسجله | | ------------------------------------------------ | -------------------------------- | -| `api.registerProvider(...)` | الاستدلال النصي (LLM) | -| `api.registerCliBackend(...)` | CLI inference backend محلي | -| `api.registerChannel(...)` | قناة مراسلة | -| `api.registerSpeechProvider(...)` | تحويل النص إلى كلام / توليف STT | +| `api.registerProvider(...)` | استدلال النص (LLM) | +| `api.registerCliBackend(...)` | واجهة خلفية محلية للاستدلال عبر CLI | +| `api.registerChannel(...)` | قناة مراسلة | +| `api.registerSpeechProvider(...)` | تحويل النص إلى كلام / توليف STT | | `api.registerRealtimeTranscriptionProvider(...)` | نسخ فوري متدفق | -| `api.registerRealtimeVoiceProvider(...)` | جلسات صوت فوري ثنائية الاتجاه | -| `api.registerMediaUnderstandingProvider(...)` | تحليل الصور/الصوت/الفيديو | -| `api.registerImageGenerationProvider(...)` | توليد الصور | -| `api.registerMusicGenerationProvider(...)` | توليد الموسيقى | -| `api.registerVideoGenerationProvider(...)` | توليد الفيديو | -| `api.registerWebFetchProvider(...)` | مزود جلب / scrape للويب | -| `api.registerWebSearchProvider(...)` | البحث على الويب | +| `api.registerRealtimeVoiceProvider(...)` | جلسات صوت فورية ثنائية الاتجاه | +| `api.registerMediaUnderstandingProvider(...)` | تحليل الصور/الصوت/الفيديو | +| `api.registerImageGenerationProvider(...)` | توليد الصور | +| `api.registerMusicGenerationProvider(...)` | توليد الموسيقى | +| `api.registerVideoGenerationProvider(...)` | توليد الفيديو | +| `api.registerWebFetchProvider(...)` | موفّر Web fetch / scrape | +| `api.registerWebSearchProvider(...)` | البحث على الويب | ### الأدوات والأوامر | الأسلوب | ما الذي يسجله | | ------------------------------- | --------------------------------------------- | | `api.registerTool(tool, opts?)` | أداة وكيل (مطلوبة أو `{ optional: true }`) | -| `api.registerCommand(def)` | أمر مخصص (يتجاوز LLM) | +| `api.registerCommand(def)` | أمر مخصص (يتجاوز LLM) | ### البنية التحتية | الأسلوب | ما الذي يسجله | | ---------------------------------------------- | --------------------------------------- | -| `api.registerHook(events, handler, opts?)` | event hook | -| `api.registerHttpRoute(params)` | endpoint ‏HTTP في Gateway | -| `api.registerGatewayMethod(name, handler)` | أسلوب Gateway RPC | -| `api.registerCli(registrar, opts?)` | أمر CLI فرعي | -| `api.registerService(service)` | خدمة في الخلفية | -| `api.registerInteractiveHandler(registration)` | معالج تفاعلي | -| `api.registerMemoryPromptSupplement(builder)` | قسم إضافي من prompt مجاور للذاكرة | -| `api.registerMemoryCorpusSupplement(adapter)` | corpus إضافي لبحث/قراءة الذاكرة | +| `api.registerHook(events, handler, opts?)` | خطاف حدث | +| `api.registerHttpRoute(params)` | نقطة نهاية HTTP للبوابة | +| `api.registerGatewayMethod(name, handler)` | أسلوب RPC للبوابة | +| `api.registerCli(registrar, opts?)` | أمر فرعي في CLI | +| `api.registerService(service)` | خدمة خلفية | +| `api.registerInteractiveHandler(registration)` | معالج تفاعلي | +| `api.registerMemoryPromptSupplement(builder)` | قسم إضافي للمطالبات المجاورة للذاكرة | +| `api.registerMemoryCorpusSupplement(adapter)` | corpus إضافي لبحث/قراءة الذاكرة | -تظل مساحات أسماء الإدارة الأساسية المحجوزة (`config.*`, `exec.approvals.*`, `wizard.*`, -`update.*`) دائمًا عند `operator.admin`، حتى إذا حاول plugin تعيين -نطاق أضيق لأسلوب gateway. ويفضل استخدام بادئات خاصة بالـ plugin -للأساليب المملوكة له. +تظل مساحات أسماء الإدارة الأساسية المحجوزة (`config.*` و`exec.approvals.*` و`wizard.*`، +و`update.*`) دائمًا `operator.admin`، حتى إذا حاولت إضافة تعيين +نطاق أضيق لأسلوب البوابة. فضّل البادئات الخاصة بالإضافة +للأساليب التي تملكها الإضافة. ### بيانات تعريف تسجيل CLI -يقبل `api.registerCli(registrar, opts?)` نوعين من بيانات التعريف العليا: +يقبل `api.registerCli(registrar, opts?)` نوعين من بيانات التعريف في المستوى الأعلى: -- `commands`: جذور أوامر صريحة يملكها registrar +- `commands`: جذور أوامر صريحة يملكها المُسجِّل - `descriptors`: واصفات أوامر وقت التحليل المستخدمة لمساعدة CLI الجذرية، - والتوجيه، والتسجيل الكسول لـ CLI الخاص بالـ plugin + والتوجيه، وتسجيل CLI الكسول للإضافة -إذا كنت تريد أن يبقى أمر plugin محمّلًا بكسل في مسار CLI الجذري العادي، -فقدّم `descriptors` تغطي كل جذر أمر من المستوى الأعلى يكشفه -ذلك registrar. +إذا كنت تريد أن يظل أمر الإضافة محمّلًا بكسل في المسار الجذري العادي لـ CLI، +فقدّم `descriptors` تغطي كل جذر أمر من المستوى الأعلى يكشفه ذلك +المُسجِّل. ```typescript api.registerCli( @@ -363,7 +368,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "Manage Matrix accounts, verification, devices, and profile state", + description: "إدارة حسابات Matrix، والتحقق، والأجهزة، وحالة الملف الشخصي", hasSubcommands: true, }, ], @@ -371,128 +376,134 @@ api.registerCli( ); ``` -استخدم `commands` وحدها فقط عندما لا تحتاج إلى تسجيل CLI جذري كسول. -يظل مسار التوافق eager هذا مدعومًا، لكنه لا يثبت -عناصر نائبة مدعومة بـ descriptor للتحميل الكسول وقت التحليل. +استخدم `commands` وحده فقط عندما لا تحتاج إلى تسجيل CLI جذري كسول. +لا يزال هذا المسار التوافقي المتعجل مدعومًا، لكنه لا يثبت +عناصر نائبة مدعومة بالواصفات من أجل التحميل الكسول وقت التحليل. -### تسجيل CLI backend +### تسجيل الواجهة الخلفية لـ CLI -يتيح `api.registerCliBackend(...)` للـ plugin امتلاك الإعداد الافتراضي لـ -AI CLI backend محلي مثل `codex-cli`. +يتيح `api.registerCliBackend(...)` لإضافة أن تملك التكوين الافتراضي لواجهة خلفية +محلية لـ CLI للذكاء الاصطناعي مثل `codex-cli`. -- يصبح `id` الخاص بالـ backend بادئة المزوّد في مراجع النماذج مثل `codex-cli/gpt-5`. -- تستخدم `config` الخاصة بالـ backend الشكل نفسه الموجود في `agents.defaults.cliBackends.`. -- تظل إعدادات المستخدم هي الغالبة. يدمج OpenClaw ‏`agents.defaults.cliBackends.` فوق - القيمة الافتراضية للـ plugin قبل تشغيل CLI. -- استخدم `normalizeConfig` عندما يحتاج backend إلى إعادة كتابة توافقية بعد الدمج - (مثل تطبيع أشكال flags القديمة). +- يصبح `id` الخاص بالواجهة الخلفية بادئة الموفّر في مراجع النماذج مثل `codex-cli/gpt-5`. +- يستخدم `config` الخاص بالواجهة الخلفية الشكل نفسه المستخدم في `agents.defaults.cliBackends.`. +- يظل تكوين المستخدم هو الغالب. يدمج OpenClaw `agents.defaults.cliBackends.` فوق + القيمة الافتراضية للإضافة قبل تشغيل CLI. +- استخدم `normalizeConfig` عندما تحتاج الواجهة الخلفية إلى إعادة كتابة توافقية بعد الدمج + (على سبيل المثال، تطبيع أشكال الأعلام القديمة). -### الخانات الحصرية +### الفتحات الحصرية | الأسلوب | ما الذي يسجله | | ------------------------------------------ | ------------------------------------- | -| `api.registerContextEngine(id, factory)` | محرك سياق (واحد فقط نشط في كل مرة) | -| `api.registerMemoryPromptSection(builder)` | باني قسم prompt للذاكرة | -| `api.registerMemoryFlushPlan(resolver)` | محلل خطة flush للذاكرة | -| `api.registerMemoryRuntime(runtime)` | محول وقت تشغيل الذاكرة | +| `api.registerContextEngine(id, factory)` | محرك السياق (واحد نشط في كل مرة) | +| `api.registerMemoryCapability(capability)` | قدرة الذاكرة الموحدة | +| `api.registerMemoryPromptSection(builder)` | باني قسم مطالبة الذاكرة | +| `api.registerMemoryFlushPlan(resolver)` | محلّل خطة تفريغ الذاكرة | +| `api.registerMemoryRuntime(runtime)` | موائم وقت تشغيل الذاكرة | -### محولات embedding الخاصة بالذاكرة +### موائمات تضمين الذاكرة | الأسلوب | ما الذي يسجله | | ---------------------------------------------- | ---------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | محول embedding للذاكرة للـ plugin النشط | +| `api.registerMemoryEmbeddingProvider(adapter)` | موائم تضمين ذاكرة للإضافة النشطة | -- `registerMemoryPromptSection`, `registerMemoryFlushPlan`, و - `registerMemoryRuntime` حصرية لـ Memory plugins. -- يتيح `registerMemoryEmbeddingProvider` للـ memory plugin النشط تسجيل - معرّف محول embedding واحد أو أكثر (مثل `openai`, `gemini`، أو معرّف - مخصص يعرّفه plugin). -- تُحل إعدادات المستخدم مثل `agents.defaults.memorySearch.provider` و - `agents.defaults.memorySearch.fallback` مقابل معرّفات المحولات المسجلة تلك. +- `registerMemoryCapability` هو API الإضافة الحصرية المفضلة الخاصة بذاكرة الذاكرة. +- قد يكشف `registerMemoryCapability` أيضًا `publicArtifacts.listArtifacts(...)` + بحيث تتمكن الإضافات المرافقة من استهلاك مصنوعات الذاكرة المصدّرة عبر + `openclaw/plugin-sdk/memory-host-core` بدلًا من الوصول إلى التخطيط الخاص + لإضافة ذاكرة محددة. +- `registerMemoryPromptSection` و`registerMemoryFlushPlan` و + `registerMemoryRuntime` هي APIs حصرية متوافقة مع الإصدارات القديمة لإضافات الذاكرة. +- يتيح `registerMemoryEmbeddingProvider` لإضافة الذاكرة النشطة تسجيل + معرّف واحد أو أكثر لموائمات التضمين (مثل `openai` أو `gemini` أو معرّف + مخصص تعرّفه الإضافة). +- يُحل تكوين المستخدم مثل `agents.defaults.memorySearch.provider` و + `agents.defaults.memorySearch.fallback` مقابل معرّفات الموائمات المسجلة هذه. ### الأحداث ودورة الحياة | الأسلوب | ما الذي يفعله | | -------------------------------------------- | ----------------------------- | -| `api.on(hookName, handler, opts?)` | hook دورة حياة typed | -| `api.onConversationBindingResolved(handler)` | callback عند تحليل ربط المحادثة | +| `api.on(hookName, handler, opts?)` | خطاف دورة حياة مطبّع | +| `api.onConversationBindingResolved(handler)` | استدعاء رد رابط المحادثة | -### دلالات قرارات الـ hook +### دلالات قرارات الخطافات -- `before_tool_call`: إرجاع `{ block: true }` نهائي. وبمجرد أن يضبطه أي معالج، يتم تخطي المعالجات الأقل أولوية. -- `before_tool_call`: إرجاع `{ block: false }` يُعامل على أنه بدون قرار (مثل حذف `block`) وليس كتجاوز. -- `before_install`: إرجاع `{ block: true }` نهائي. وبمجرد أن يضبطه أي معالج، يتم تخطي المعالجات الأقل أولوية. -- `before_install`: إرجاع `{ block: false }` يُعامل على أنه بدون قرار (مثل حذف `block`) وليس كتجاوز. -- `reply_dispatch`: إرجاع `{ handled: true, ... }` نهائي. وبمجرد أن يدّعي أي معالج الإرسال، يتم تخطي المعالجات الأقل أولوية ومسار إرسال النموذج الافتراضي. -- `message_sending`: إرجاع `{ cancel: true }` نهائي. وبمجرد أن يضبطه أي معالج، يتم تخطي المعالجات الأقل أولوية. -- `message_sending`: إرجاع `{ cancel: false }` يُعامل على أنه بدون قرار (مثل حذف `cancel`) وليس كتجاوز. +- `before_tool_call`: إرجاع `{ block: true }` نهائي. بمجرد أن يضبطه أي معالج، يتم تخطي المعالجات ذات الأولوية الأقل. +- `before_tool_call`: إرجاع `{ block: false }` يُعامل على أنه لا قرار (مثل حذف `block`)، وليس كتجاوز. +- `before_install`: إرجاع `{ block: true }` نهائي. بمجرد أن يضبطه أي معالج، يتم تخطي المعالجات ذات الأولوية الأقل. +- `before_install`: إرجاع `{ block: false }` يُعامل على أنه لا قرار (مثل حذف `block`)، وليس كتجاوز. +- `reply_dispatch`: إرجاع `{ handled: true, ... }` نهائي. بمجرد أن يطالب أي معالج بالإرسال، يتم تخطي المعالجات ذات الأولوية الأقل ومسار إرسال النموذج الافتراضي. +- `message_sending`: إرجاع `{ cancel: true }` نهائي. بمجرد أن يضبطه أي معالج، يتم تخطي المعالجات ذات الأولوية الأقل. +- `message_sending`: إرجاع `{ cancel: false }` يُعامل على أنه لا قرار (مثل حذف `cancel`)، وليس كتجاوز. ### حقول كائن API | الحقل | النوع | الوصف | | ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | -| `api.id` | `string` | معرّف plugin | -| `api.name` | `string` | اسم العرض | -| `api.version` | `string?` | إصدار plugin ‏(اختياري) | -| `api.description` | `string?` | وصف plugin ‏(اختياري) | -| `api.source` | `string` | مسار مصدر plugin | -| `api.rootDir` | `string?` | الدليل الجذري لـ plugin ‏(اختياري) | -| `api.config` | `OpenClawConfig` | لقطة الإعدادات الحالية (لقطة وقت تشغيل داخل الذاكرة النشطة عندما تكون متاحة) | -| `api.pluginConfig` | `Record` | إعدادات خاصة بالـ plugin من `plugins.entries..config` | -| `api.runtime` | `PluginRuntime` | [مساعدات وقت التشغيل](/ar/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | logger محدود النطاق (`debug`, `info`, `warn`, `error`) | -| `api.registrationMode` | `PluginRegistrationMode` | وضع التحميل الحالي؛ و`"setup-runtime"` هي نافذة بدء التشغيل/الإعداد الخفيفة قبل الإدخال الكامل | -| `api.resolvePath(input)` | `(string) => string` | تحليل المسار نسبةً إلى جذر plugin | +| `api.id` | `string` | معرّف الإضافة | +| `api.name` | `string` | اسم العرض | +| `api.version` | `string?` | إصدار الإضافة (اختياري) | +| `api.description` | `string?` | وصف الإضافة (اختياري) | +| `api.source` | `string` | مسار مصدر الإضافة | +| `api.rootDir` | `string?` | الدليل الجذري للإضافة (اختياري) | +| `api.config` | `OpenClawConfig` | لقطة التكوين الحالية (لقطة وقت التشغيل النشطة داخل الذاكرة عند توفرها) | +| `api.pluginConfig` | `Record` | تكوين خاص بالإضافة من `plugins.entries..config` | +| `api.runtime` | `PluginRuntime` | [مساعدات وقت التشغيل](/ar/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | مسجّل ذو نطاق (`debug`, `info`, `warn`, `error`) | +| `api.registrationMode` | `PluginRegistrationMode` | وضع التحميل الحالي؛ `"setup-runtime"` هي نافذة بدء التشغيل/الإعداد الخفيفة قبل الإدخال الكامل | +| `api.resolvePath(input)` | `(string) => string` | حل المسار نسبةً إلى جذر الإضافة | -## اصطلاحات الوحدات الداخلية +## اصطلاح الوحدات الداخلية -داخل plugin الخاص بك، استخدم ملفات barrel محلية للاستيراد الداخلي: +داخل إضافتك، استخدم ملفات barrel محلية للاستيرادات الداخلية: ``` my-plugin/ - api.ts # Exports عامة للمستهلكين الخارجيين - runtime-api.ts # Exports داخلية فقط لوقت التشغيل - index.ts # نقطة إدخال plugin - setup-entry.ts # إدخال خفيف خاص بالإعداد فقط (اختياري) + api.ts # الصادرات العامة للمستهلكين الخارجيين + runtime-api.ts # صادرات وقت تشغيل داخلية فقط + index.ts # نقطة إدخال الإضافة + setup-entry.ts # إدخال خفيف للإعداد فقط (اختياري) ``` - لا تستورد plugin الخاص بك أبدًا عبر `openclaw/plugin-sdk/` - من كود الإنتاج. وجّه عمليات الاستيراد الداخلية عبر `./api.ts` أو + لا تستورد إضافتك الخاصة أبدًا من خلال `openclaw/plugin-sdk/` + من كود الإنتاج. وجّه الاستيرادات الداخلية عبر `./api.ts` أو `./runtime-api.ts`. مسار SDK هو العقد الخارجي فقط. -تفضّل الآن الأسطح العامة للـ plugins المضمنة المحمّلة عبر facade (`api.ts`, `runtime-api.ts`, -`index.ts`, `setup-entry.ts`، وملفات الإدخال العامة المشابهة) استخدام -لقطة إعدادات وقت التشغيل النشطة عندما يكون OpenClaw يعمل بالفعل. وإذا لم تكن -هناك لقطة وقت تشغيل متاحة بعد، فسترجع إلى ملف الإعدادات المحلول على القرص. +تفضّل الآن الأسطح العامة للإضافات المضمّنة المحمّلة عبر الواجهة (`api.ts` و`runtime-api.ts`، +و`index.ts` و`setup-entry.ts`، وملفات الإدخال العامة المشابهة) +لقطة تكوين وقت التشغيل النشطة عندما يكون OpenClaw قيد التشغيل بالفعل. وإذا لم تكن +لقطة وقت التشغيل موجودة بعد، فإنها ترجع إلى ملف التكوين المحلول على القرص. -يمكن لـ Provider plugins أيضًا كشف barrel عقد محلي ضيق خاص بالـ plugin عندما يكون -المساعد مقصودًا أن يكون خاصًا بالمزود ولا ينتمي بعد إلى مسار فرعي عام في SDK. -المثال المضمّن الحالي: يحتفظ مزود Anthropic بمساعدات تدفق Claude -داخل نقطة الربط العامة الخاصة به `api.ts` / `contract-api.ts` بدلًا من -ترقية منطق ترويسات Anthropic beta و`service_tier` إلى عقد عام -`plugin-sdk/*`. +يمكن لإضافات الموفّرات أيضًا كشف ملف barrel محلي ضيق خاص بالإضافة عندما يكون +المساعد خاصًا بالموفّر عمدًا ولا ينتمي بعد إلى مسار فرعي عام في SDK. +المثال المضمّن الحالي: يحتفظ موفّر Anthropic بمساعدات بث Claude +الخاصة به في سطحه العام `api.ts` / `contract-api.ts` بدلًا من +ترقية منطق رؤوس Anthropic التجريبية و`service_tier` إلى عقد +عام من `plugin-sdk/*`. -أمثلة مضمنة حالية أخرى: +أمثلة مضمّنة حالية أخرى: -- `@openclaw/openai-provider`: يصدّر `api.ts` بناة المزودات، - ومساعدات النماذج الافتراضية، وبناة مزودات الوقت الفعلي -- `@openclaw/openrouter-provider`: يصدّر `api.ts` باني المزود بالإضافة إلى - مساعدات onboarding/config +- `@openclaw/openai-provider`: يصدّر `api.ts` بُناة الموفّر، + ومساعدات النموذج الافتراضي، وبناة الموفّر الفوري +- `@openclaw/openrouter-provider`: يصدّر `api.ts` باني الموفّر بالإضافة إلى + مساعدات الإعداد الأولي/التكوين - يجب أيضًا على كود الإنتاج الخاص بالامتدادات تجنب استيرادات - `openclaw/plugin-sdk/`. وإذا كان أحد المساعدات مشتركًا فعلًا، فقم بترقيته إلى مسار فرعي - محايد في SDK مثل `openclaw/plugin-sdk/speech`, `.../provider-model-shared` أو أي - سطح موجّه للقدرات بدلًا من ربط pluginين معًا. + يجب أيضًا على كود الإنتاج في الامتدادات تجنّب الاستيراد من `openclaw/plugin-sdk/`. + إذا كان المساعد مشتركًا فعلًا، فقم بترقيته إلى مسار فرعي محايد في SDK + مثل `openclaw/plugin-sdk/speech` أو `.../provider-model-shared` أو سطح آخر + موجّه للقدرات بدلًا من ربط إضافتين معًا. ## ذو صلة -- [Entry Points](/ar/plugins/sdk-entrypoints) — خيارات `definePluginEntry` و`defineChannelPluginEntry` -- [Runtime Helpers](/ar/plugins/sdk-runtime) — المرجع الكامل لمساحة الأسماء `api.runtime` -- [Setup and Config](/ar/plugins/sdk-setup) — التغليف، وmanifest، ومخططات الإعدادات -- [Testing](/ar/plugins/sdk-testing) — أدوات الاختبار وقواعد lint -- [SDK Migration](/ar/plugins/sdk-migration) — الترحيل من الأسطح المهجورة -- [Plugin Internals](/ar/plugins/architecture) — البنية العميقة ونموذج القدرات +- [نقاط الإدخال](/ar/plugins/sdk-entrypoints) — خيارات `definePluginEntry` و`defineChannelPluginEntry` +- [مساعدات وقت التشغيل](/ar/plugins/sdk-runtime) — المرجع الكامل لمساحة الاسم `api.runtime` +- [الإعداد والتكوين](/ar/plugins/sdk-setup) — الحزم، وmanifestات، ومخططات التكوين +- [الاختبار](/ar/plugins/sdk-testing) — أدوات الاختبار وقواعد lint +- [ترحيل SDK](/ar/plugins/sdk-migration) — الترحيل من الأسطح القديمة المهملة +- [الداخلية الخاصة بالإضافات](/ar/plugins/architecture) — بنية عميقة ونموذج القدرات diff --git a/docs/ar/providers/google.md b/docs/ar/providers/google.md index 2817af2c1..4ede645f3 100644 --- a/docs/ar/providers/google.md +++ b/docs/ar/providers/google.md @@ -1,30 +1,30 @@ --- read_when: - تريد استخدام نماذج Google Gemini مع OpenClaw - - تحتاج إلى تدفق المصادقة عبر مفتاح API أو OAuth -summary: إعداد Google Gemini ‏(مفتاح API + OAuth، وتوليد الصور، وفهم الوسائط، والبحث على الويب) + - تحتاج إلى تدفق المصادقة بمفتاح API أو OAuth +summary: إعداد Google Gemini ‏(مفتاح API وOAuth، وإنشاء الصور، وفهم الوسائط، والبحث على الويب) title: Google (Gemini) x-i18n: - generated_at: "2026-04-07T07:21:24Z" + generated_at: "2026-04-08T02:17:12Z" model: gpt-5.4 provider: openai - source_hash: 36cc7c7d8d19f6d4a3fb223af36c8402364fc309d14ffe922bd004203ceb1754 + source_hash: e9e558f5ce35c853e0240350be9a1890460c5f7f7fd30b05813a656497dee516 source_path: providers/google.md workflow: 15 --- # Google (Gemini) -يوفر Google plugin الوصول إلى نماذج Gemini عبر Google AI Studio، بالإضافة إلى -توليد الصور، وفهم الوسائط (الصور/الصوت/الفيديو)، والبحث على الويب عبر +يوفر plugin Google إمكانية الوصول إلى نماذج Gemini عبر Google AI Studio، بالإضافة إلى +إنشاء الصور، وفهم الوسائط (الصور/الصوت/الفيديو)، والبحث على الويب عبر Gemini Grounding. -- المزود: `google` +- الموفر: `google` - المصادقة: `GEMINI_API_KEY` أو `GOOGLE_API_KEY` -- API: ‏Google Gemini API -- مزود بديل: `google-gemini-cli` ‏(OAuth) +- API: Google Gemini API +- موفر بديل: `google-gemini-cli` ‏(OAuth) -## البدء السريع +## بداية سريعة 1. اضبط مفتاح API: @@ -53,17 +53,17 @@ openclaw onboard --non-interactive \ --gemini-api-key "$GEMINI_API_KEY" ``` -## OAuth ‏(Gemini CLI) +## OAuth (Gemini CLI) -يستخدم مزود بديل باسم `google-gemini-cli` مصادقة PKCE OAuth بدلًا من مفتاح -API. وهذا تكامل غير رسمي؛ وقد أفاد بعض المستخدمين بوجود قيود -على الحسابات. استخدمه على مسؤوليتك الخاصة. +يستخدم موفر بديل باسم `google-gemini-cli` مصادقة PKCE OAuth بدلًا من مفتاح API. +هذا تكامل غير رسمي؛ وقد أبلغ بعض المستخدمين عن +قيود على الحساب. استخدمه على مسؤوليتك الخاصة. -- النموذج الافتراضي: `google-gemini-cli/gemini-3.1-pro-preview` -- الاسم البديل: `gemini-cli` -- متطلب التثبيت: توفر Gemini CLI محليًا باسم `gemini` - - Homebrew: ‏`brew install gemini-cli` - - npm: ‏`npm install -g @google/gemini-cli` +- النموذج الافتراضي: `google-gemini-cli/gemini-3-flash-preview` +- الاسم المستعار: `gemini-cli` +- متطلب التثبيت المسبق: أن يكون Gemini CLI المحلي متاحًا باسم `gemini` + - Homebrew: `brew install gemini-cli` + - npm: `npm install -g @google/gemini-cli` - تسجيل الدخول: ```bash @@ -75,48 +75,48 @@ openclaw models auth login --provider google-gemini-cli --set-default - `OPENCLAW_GEMINI_OAUTH_CLIENT_ID` - `OPENCLAW_GEMINI_OAUTH_CLIENT_SECRET` -(أو متغيرات `GEMINI_CLI_*` البديلة.) +(أو الصيغ `GEMINI_CLI_*`.) إذا فشلت طلبات Gemini CLI OAuth بعد تسجيل الدخول، فاضبط -`GOOGLE_CLOUD_PROJECT` أو `GOOGLE_CLOUD_PROJECT_ID` على مضيف gateway ثم +`GOOGLE_CLOUD_PROJECT` أو `GOOGLE_CLOUD_PROJECT_ID` على مضيف البوابة ثم أعد المحاولة. إذا فشل تسجيل الدخول قبل بدء تدفق المتصفح، فتأكد من أن الأمر المحلي `gemini` -مثبّت وموجود على `PATH`. يدعم OpenClaw كلًا من تثبيتات Homebrew -وتثبيتات npm العامة، بما في ذلك تخطيطات Windows/npm الشائعة. +مثبّت وموجود على `PATH`. يدعم OpenClaw كلاً من عمليات التثبيت عبر Homebrew +وعمليات التثبيت العامة عبر npm، بما في ذلك تخطيطات Windows/npm الشائعة. -ملاحظات استخدام JSON في Gemini CLI: +ملاحظات استخدام Gemini CLI JSON: - يأتي نص الرد من الحقل `response` في JSON الخاص بـ CLI. -- تعود معلومات الاستخدام إلى `stats` عندما يترك CLI الحقل `usage` فارغًا. -- يتم تطبيع `stats.cached` إلى `cacheRead` في OpenClaw. -- إذا كان `stats.input` مفقودًا، فإن OpenClaw يستنتج رموز الإدخال من +- يعود الاستخدام إلى `stats` عندما يترك CLI الحقل `usage` فارغًا. +- تتم تسوية `stats.cached` إلى OpenClaw `cacheRead`. +- إذا كان `stats.input` مفقودًا، فإن OpenClaw يشتق رموز الإدخال من `stats.input_tokens - stats.cached`. -## القدرات +## الإمكانات -| القدرة | مدعومة | -| ---------------------- | ----------------- | -| إكمالات الدردشة | نعم | -| توليد الصور | نعم | -| توليد الموسيقى | نعم | -| فهم الصور | نعم | -| نسخ الصوت | نعم | -| فهم الفيديو | نعم | -| البحث على الويب (Grounding) | نعم | -| التفكير/الاستدلال | نعم (Gemini 3.1+) | +| الإمكانية | مدعومة | +| --------------------- | ---------------- | +| إكمالات الدردشة | نعم | +| إنشاء الصور | نعم | +| إنشاء الموسيقى | نعم | +| فهم الصور | نعم | +| نسخ الصوت | نعم | +| فهم الفيديو | نعم | +| البحث على الويب (Grounding) | نعم | +| التفكير/الاستدلال | نعم (Gemini 3.1+) | -## إعادة استخدام ذاكرة Gemini المؤقتة مباشرة +## إعادة استخدام ذاكرة Gemini المؤقتة المباشرة -بالنسبة إلى تشغيلات Gemini API المباشرة (`api: "google-generative-ai"`)، يقوم OpenClaw الآن -بتمرير معرّف `cachedContent` المضبوط إلى طلبات Gemini. +بالنسبة إلى التشغيلات المباشرة لـ Gemini API ‏(`api: "google-generative-ai"`)، يقوم OpenClaw الآن +بتمرير معرّف `cachedContent` المهيأ إلى طلبات Gemini. -- اضبط المعلمات لكل نموذج أو بشكل عام باستخدام +- اضبط معلمات لكل نموذج أو معلمات عامة باستخدام `cachedContent` أو `cached_content` القديم - إذا وُجد الاثنان، تكون الأولوية لـ `cachedContent` - مثال على القيمة: `cachedContents/prebuilt-context` -- يتم تطبيع استخدام إصابة ذاكرة Gemini المؤقتة إلى `cacheRead` في OpenClaw من - `cachedContentTokenCount` الصادر من المصدر +- تتم تسوية استخدام إصابة الذاكرة المؤقتة في Gemini إلى OpenClaw `cacheRead` من + `cachedContentTokenCount` الصادر من الخدمة upstream مثال: @@ -136,21 +136,21 @@ openclaw models auth login --provider google-gemini-cli --set-default } ``` -## توليد الصور +## إنشاء الصور -يضبط مزود توليد الصور المضمّن `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-gemini-cli` المعتمد على OAuth فقط هو سطح منفصل -للاستدلال النصي. أما توليد الصور، وفهم الوسائط، وGemini Grounding فتبقى على -معرّف المزود `google`. +يُعد الموفر `google-gemini-cli` المعتمد على OAuth فقط واجهة منفصلة +للاستدلال النصي. أما إنشاء الصور، وفهم الوسائط، وGemini Grounding فتبقى على +معرّف الموفر `google`. -لاستخدام Google بوصفه مزود الصور الافتراضي: +لاستخدام Google كموفر الصور الافتراضي: ```json5 { @@ -164,20 +164,20 @@ openclaw models auth login --provider google-gemini-cli --set-default } ``` -راجع [توليد الصور](/ar/tools/image-generation) لمعلمات -الأداة المشتركة، واختيار المزود، وسلوك failover. +راجع [إنشاء الصور](/ar/tools/image-generation) للتعرّف على +معلمات الأداة المشتركة، واختيار الموفر، وسلوك التبديل الاحتياطي. -## توليد الفيديو +## إنشاء الفيديو -يسجل Google plugin المضمّن أيضًا توليد الفيديو عبر الأداة المشتركة +يسجل plugin `google` المضمن أيضًا إنشاء الفيديو عبر الأداة المشتركة `video_generate`. - نموذج الفيديو الافتراضي: `google/veo-3.1-fast-generate-preview` -- الأوضاع: من نص إلى فيديو، ومن صورة إلى فيديو، وتدفقات مرجعية لفيديو واحد +- الأوضاع: نص إلى فيديو، وصورة إلى فيديو، وتدفقات مرجعية لفيديو واحد - يدعم `aspectRatio` و`resolution` و`audio` -- حد المدة الحالي: **من 4 إلى 8 ثوانٍ** +- القيد الحالي للمدة: **من 4 إلى 8 ثوانٍ** -لاستخدام Google بوصفه مزود الفيديو الافتراضي: +لاستخدام Google كموفر الفيديو الافتراضي: ```json5 { @@ -191,22 +191,22 @@ openclaw models auth login --provider google-gemini-cli --set-default } ``` -راجع [توليد الفيديو](/ar/tools/video-generation) لمعلمات -الأداة المشتركة، واختيار المزود، وسلوك failover. +راجع [إنشاء الفيديو](/ar/tools/video-generation) للتعرّف على +معلمات الأداة المشتركة، واختيار الموفر، وسلوك التبديل الاحتياطي. -## توليد الموسيقى +## إنشاء الموسيقى -يسجل Google plugin المضمّن أيضًا توليد الموسيقى عبر الأداة المشتركة +يسجل plugin `google` المضمن أيضًا إنشاء الموسيقى عبر الأداة المشتركة `music_generate`. - نموذج الموسيقى الافتراضي: `google/lyria-3-clip-preview` - يدعم أيضًا `google/lyria-3-pro-preview` -- عناصر التحكم في prompt: ‏`lyrics` و`instrumental` +- عناصر التحكم في الموجّه: `lyrics` و`instrumental` - تنسيق الإخراج: `mp3` افتراضيًا، بالإضافة إلى `wav` على `google/lyria-3-pro-preview` -- مدخلات مرجعية: حتى 10 صور +- المدخلات المرجعية: حتى 10 صور - يتم فصل التشغيلات المدعومة بالجلسات عبر تدفق المهمة/الحالة المشترك، بما في ذلك `action: "status"` -لاستخدام Google بوصفه مزود الموسيقى الافتراضي: +لاستخدام Google كموفر الموسيقى الافتراضي: ```json5 { @@ -220,11 +220,11 @@ openclaw models auth login --provider google-gemini-cli --set-default } ``` -راجع [توليد الموسيقى](/ar/tools/music-generation) لمعلمات -الأداة المشتركة، واختيار المزود، وسلوك failover. +راجع [إنشاء الموسيقى](/ar/tools/music-generation) للتعرّف على +معلمات الأداة المشتركة، واختيار الموفر، وسلوك التبديل الاحتياطي. -## ملاحظة حول البيئة +## ملاحظة البيئة -إذا كان Gateway يعمل كخدمة daemon ‏(launchd/systemd)، فتأكد من أن `GEMINI_API_KEY` +إذا كانت البوابة تعمل كخدمة خلفية (launchd/systemd)، فتأكد من أن `GEMINI_API_KEY` متاح لتلك العملية (على سبيل المثال، في `~/.openclaw/.env` أو عبر `env.shellEnv`). diff --git a/docs/ar/providers/index.md b/docs/ar/providers/index.md index 0ab8e437c..34cc34979 100644 --- a/docs/ar/providers/index.md +++ b/docs/ar/providers/index.md @@ -1,28 +1,28 @@ --- read_when: - - تريد اختيار مزوّد نموذج - - تحتاج إلى نظرة عامة سريعة على واجهات LLM الخلفية المدعومة -summary: مزوّدو النماذج (LLMs) الذين يدعمهم OpenClaw -title: دليل المزوّدين + - تريد اختيار موفر نموذج + - تحتاج إلى نظرة عامة سريعة على الواجهات الخلفية المدعومة لـ LLM +summary: موفرو النماذج (LLMs) الذين يدعمهم OpenClaw +title: دليل الموفرين x-i18n: - generated_at: "2026-04-07T07:21:18Z" + generated_at: "2026-04-08T02:17:25Z" model: gpt-5.4 provider: openai - source_hash: 39d9ace35fd9452a4fb510fd980d251b6e51480e4647f051020bee2f1f2222e1 + source_hash: e7bee5528b7fc9a982b3d0eaa4930cb77f7bded19a47aec00572b6fcbd823a70 source_path: providers/index.md workflow: 15 --- -# مزودو النماذج +# موفرو النماذج -يمكن لـ OpenClaw استخدام العديد من مزوّدي LLM. اختر مزوّدًا، ثم صادق، ثم اضبط +يمكن لـ OpenClaw استخدام العديد من موفري LLM. اختر موفرًا، ثم أكمل المصادقة، ثم اضبط النموذج الافتراضي بصيغة `provider/model`. هل تبحث عن وثائق قنوات الدردشة (WhatsApp/Telegram/Discord/Slack/Mattermost (plugin)/إلخ)؟ راجع [القنوات](/ar/channels). -## البدء السريع +## بداية سريعة -1. صادق مع المزوّد (عادةً عبر `openclaw onboard`). +1. أكمل المصادقة مع الموفر (عادةً عبر `openclaw onboard`). 2. اضبط النموذج الافتراضي: ```json5 @@ -31,13 +31,13 @@ x-i18n: } ``` -## وثائق المزوّدين +## وثائق الموفرين - [Alibaba Model Studio](/ar/providers/alibaba) - [Amazon Bedrock](/ar/providers/bedrock) - [Anthropic (API + Claude CLI)](/ar/providers/anthropic) - [Arcee AI (نماذج Trinity)](/ar/providers/arcee) -- [BytePlus (دولي)](/ar/concepts/model-providers#byteplus-international) +- [BytePlus (الدولي)](/ar/concepts/model-providers#byteplus-international) - [Chutes](/ar/providers/chutes) - [ComfyUI](/ar/providers/comfy) - [Cloudflare AI Gateway](/ar/providers/cloudflare-ai-gateway) @@ -49,6 +49,7 @@ x-i18n: - [Google (Gemini)](/ar/providers/google) - [Groq (استدلال LPU)](/ar/providers/groq) - [Hugging Face (Inference)](/ar/providers/huggingface) +- [inferrs (نماذج محلية)](/ar/providers/inferrs) - [Kilocode](/ar/providers/kilocode) - [LiteLLM (بوابة موحدة)](/ar/providers/litellm) - [MiniMax](/ar/providers/minimax) @@ -68,7 +69,7 @@ x-i18n: - [StepFun](/ar/providers/stepfun) - [Synthetic](/ar/providers/synthetic) - [Together AI](/ar/providers/together) -- [Venice (Venice AI، يركّز على الخصوصية)](/ar/providers/venice) +- [Venice (Venice AI، مع التركيز على الخصوصية)](/ar/providers/venice) - [Vercel AI Gateway](/ar/providers/vercel-ai-gateway) - [Vydra](/ar/providers/vydra) - [vLLM (نماذج محلية)](/ar/providers/vllm) @@ -79,18 +80,18 @@ x-i18n: ## صفحات النظرة العامة المشتركة -- [متغيرات مضمّنة إضافية](/ar/providers/models#additional-bundled-provider-variants) - Anthropic Vertex وCopilot Proxy وGemini CLI OAuth -- [توليد الصور](/ar/tools/image-generation) - أداة `image_generate` المشتركة، واختيار المزوّد، والرجوع الاحتياطي -- [توليد الموسيقى](/ar/tools/music-generation) - أداة `music_generate` المشتركة، واختيار المزوّد، والرجوع الاحتياطي -- [توليد الفيديو](/ar/tools/video-generation) - أداة `video_generate` المشتركة، واختيار المزوّد، والرجوع الاحتياطي +- [المتغيرات المضمنة الإضافية](/ar/providers/models#additional-bundled-provider-variants) - Anthropic Vertex وCopilot Proxy وGemini CLI OAuth +- [إنشاء الصور](/ar/tools/image-generation) - الأداة المشتركة `image_generate`، واختيار الموفر، وسلوك التبديل الاحتياطي +- [إنشاء الموسيقى](/ar/tools/music-generation) - الأداة المشتركة `music_generate`، واختيار الموفر، وسلوك التبديل الاحتياطي +- [إنشاء الفيديو](/ar/tools/video-generation) - الأداة المشتركة `video_generate`، واختيار الموفر، وسلوك التبديل الاحتياطي -## مزودو النسخ +## موفرو النسخ الصوتي -- [Deepgram (نسخ صوتي)](/ar/providers/deepgram) +- [Deepgram (نسخ الصوت)](/ar/providers/deepgram) ## أدوات المجتمع -- [Claude Max API Proxy](/ar/providers/claude-max-api-proxy) - وكيل مجتمع لبيانات اعتماد اشتراك Claude (تحقق من سياسة/شروط Anthropic قبل الاستخدام) +- [Claude Max API Proxy](/ar/providers/claude-max-api-proxy) - وكيل مجتمعي لبيانات اعتماد اشتراك Claude (تحقق من سياسة Anthropic/الشروط قبل الاستخدام) -للاطلاع على كتالوج المزوّدين الكامل (xAI وGroq وMistral وما إلى ذلك) والإعدادات المتقدمة، -راجع [مزوّدو النماذج](/ar/concepts/model-providers). +للاطلاع على فهرس الموفرين الكامل (xAI وGroq وMistral وما إلى ذلك) والإعدادات المتقدمة، +راجع [موفرو النماذج](/ar/concepts/model-providers). diff --git a/docs/ar/providers/inferrs.md b/docs/ar/providers/inferrs.md new file mode 100644 index 000000000..1298b027a --- /dev/null +++ b/docs/ar/providers/inferrs.md @@ -0,0 +1,180 @@ +--- +read_when: + - تريد تشغيل OpenClaw مقابل خادم inferrs محلي + - أنت تقدّم Gemma أو نموذجًا آخر عبر inferrs + - تحتاج إلى علامات التوافق الدقيقة في OpenClaw لـ inferrs +summary: تشغيل OpenClaw عبر inferrs ‏(خادم محلي متوافق مع OpenAI) +title: inferrs +x-i18n: + generated_at: "2026-04-08T02:18:16Z" + model: gpt-5.4 + provider: openai + source_hash: d84f660d49a682d0c0878707eebe1bc1e83dd115850687076ea3938b9f9c86c6 + source_path: providers/inferrs.md + workflow: 15 +--- + +# inferrs + +يمكن لـ [inferrs](https://github.com/ericcurtin/inferrs) تقديم نماذج محلية خلف +واجهة `/v1` API متوافقة مع OpenAI. يعمل OpenClaw مع `inferrs` عبر +مسار `openai-completions` العام. + +من الأفضل حاليًا التعامل مع `inferrs` على أنه واجهة خلفية مخصصة +ذاتية الاستضافة متوافقة مع OpenAI، وليس plugin موفر مخصصًا في OpenClaw. + +## بداية سريعة + +1. ابدأ `inferrs` مع نموذج. + +مثال: + +```bash +inferrs serve gg-hf-gg/gemma-4-E2B-it \ + --host 127.0.0.1 \ + --port 8080 \ + --device metal +``` + +2. تحقّق من أن الخادم قابل للوصول. + +```bash +curl http://127.0.0.1:8080/health +curl http://127.0.0.1:8080/v1/models +``` + +3. أضف إدخال موفر صريحًا في OpenClaw ووجّه النموذج الافتراضي إليه. + +## مثال إعداد كامل + +يستخدم هذا المثال Gemma 4 على خادم `inferrs` محلي. + +```json5 +{ + agents: { + defaults: { + model: { primary: "inferrs/gg-hf-gg/gemma-4-E2B-it" }, + models: { + "inferrs/gg-hf-gg/gemma-4-E2B-it": { + alias: "Gemma 4 (inferrs)", + }, + }, + }, + }, + models: { + mode: "merge", + providers: { + inferrs: { + baseUrl: "http://127.0.0.1:8080/v1", + apiKey: "inferrs-local", + api: "openai-completions", + models: [ + { + id: "gg-hf-gg/gemma-4-E2B-it", + name: "Gemma 4 E2B (inferrs)", + reasoning: false, + input: ["text"], + cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, + contextWindow: 131072, + maxTokens: 4096, + compat: { + requiresStringContent: true, + }, + }, + ], + }, + }, + }, +} +``` + +## لماذا يهم `requiresStringContent` + +تقبل بعض مسارات Chat Completions في `inferrs` فقط +`messages[].content` كسلسلة نصية، وليس كمصفوفات منظَّمة لأجزاء المحتوى. + +إذا فشلت تشغيلات OpenClaw مع خطأ مثل: + +```text +messages[1].content: invalid type: sequence, expected a string +``` + +فضبط: + +```json5 +compat: { + requiresStringContent: true +} +``` + +سيقوم OpenClaw بتسطيح أجزاء المحتوى النصية الخالصة إلى سلاسل نصية عادية قبل إرسال +الطلب. + +## ملاحظة Gemma ومخطط الأدوات + +تقبل بعض التركيبات الحالية من `inferrs` + Gemma طلبات +`/v1/chat/completions` المباشرة الصغيرة، لكنها لا تزال تفشل في أدوار +runtime الكاملة للوكيل في OpenClaw. + +إذا حدث ذلك، فجرّب هذا أولًا: + +```json5 +compat: { + requiresStringContent: true, + supportsTools: false +} +``` + +يعطّل هذا سطح مخطط الأدوات في OpenClaw لهذا النموذج ويمكن أن يقلل ضغط +الموجّه على الواجهات الخلفية المحلية الأكثر صرامة. + +إذا ظلت الطلبات المباشرة الصغيرة تعمل لكن أدوار الوكيل العادية في OpenClaw لا تزال +تتعطل داخل `inferrs`، فعادةً ما تكون المشكلة المتبقية +سلوكًا من النموذج/الخادم upstream وليس من طبقة النقل في OpenClaw. + +## اختبار smoke يدوي + +بعد الإعداد، اختبر الطبقتين كلتيهما: + +```bash +curl http://127.0.0.1:8080/v1/chat/completions \ + -H 'content-type: application/json' \ + -d '{"model":"gg-hf-gg/gemma-4-E2B-it","messages":[{"role":"user","content":"What is 2 + 2?"}],"stream":false}' + +openclaw infer model run \ + --model inferrs/gg-hf-gg/gemma-4-E2B-it \ + --prompt "What is 2 + 2? Reply with one short sentence." \ + --json +``` + +إذا نجح الأمر الأول لكن فشل الثاني، فاستخدم ملاحظات استكشاف الأخطاء وإصلاحها +أدناه. + +## استكشاف الأخطاء وإصلاحها + +- فشل `curl /v1/models`: `inferrs` لا يعمل، أو يتعذر الوصول إليه، أو أنه + غير مربوط بالمضيف/المنفذ المتوقع. +- `messages[].content ... expected a string`: اضبط + `compat.requiresStringContent: true`. +- تنجح استدعاءات `/v1/chat/completions` المباشرة الصغيرة، لكن يفشل `openclaw infer model run`: + جرّب `compat.supportsTools: false`. +- لم يعد OpenClaw يتلقى أخطاء مخطط، لكن `inferrs` لا يزال يتعطل في أدوار + الوكيل الأكبر: تعامل مع ذلك على أنه قيد في `inferrs` أو في النموذج من upstream وخفف + ضغط الموجّه أو بدّل الواجهة الخلفية/النموذج المحلي. + +## سلوك على نمط الوكيل + +يُعامَل `inferrs` على أنه واجهة خلفية `/v1` متوافقة مع OpenAI على نمط الوكيل، وليس +كنقطة نهاية OpenAI أصلية. + +- لا ينطبق هنا تشكيل الطلبات الخاص بـ OpenAI الأصلي فقط +- لا يوجد `service_tier`، ولا Responses `store`، ولا تلميحات ذاكرة التخزين المؤقت للموجّه، ولا + تشكيل حمولة توافق الاستدلال الخاصة بـ OpenAI +- لا يتم حقن ترويسات الإسناد المخفية في OpenClaw (`originator` و`version` و`User-Agent`) + على عناوين `inferrs` الأساسية المخصصة + +## راجع أيضًا + +- [النماذج المحلية](/ar/gateway/local-models) +- [استكشاف أخطاء البوابة وإصلاحها](/ar/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail) +- [موفرو النماذج](/ar/concepts/model-providers) diff --git a/docs/ar/providers/mistral.md b/docs/ar/providers/mistral.md index a0422f2e4..ff2025e50 100644 --- a/docs/ar/providers/mistral.md +++ b/docs/ar/providers/mistral.md @@ -1,23 +1,23 @@ --- read_when: - تريد استخدام نماذج Mistral في OpenClaw - - تحتاج إلى onboarding لمفتاح Mistral API وmodel refs -summary: استخدم نماذج Mistral ونسخ Voxtral مع OpenClaw + - تحتاج إلى إعداد Mistral بمفتاح API ومراجع النماذج +summary: استخدم نماذج Mistral ونسخ Voxtral الصوتي مع OpenClaw title: Mistral x-i18n: - generated_at: "2026-04-05T12:53:24Z" + generated_at: "2026-04-08T02:18:30Z" model: gpt-5.4 provider: openai - source_hash: 8f61b9e0656dd7e0243861ddf14b1b41a07c38bff27cef9ad0815d14c8e34408 + source_hash: 4e32a0eb2a37dba6383ba338b06a8d0be600e7443aa916225794ccb0fdf46aee source_path: providers/mistral.md workflow: 15 --- # Mistral -يدعم OpenClaw مزود Mistral لكل من توجيه النماذج النصية/الصور (`mistral/...`) ونسخ -الصوت عبر Voxtral في فهم الوسائط. -كما يمكن استخدام Mistral في embeddings الخاصة بالذاكرة (`memorySearch.provider = "mistral"`). +يدعم OpenClaw موفر Mistral لكلٍّ من توجيه النماذج النصية/المرئية (`mistral/...`) ونسخ +الصوت عبر Voxtral ضمن فهم الوسائط. +كما يمكن استخدام Mistral لتضمينات الذاكرة (`memorySearch.provider = "mistral"`). ## إعداد CLI @@ -27,7 +27,7 @@ openclaw onboard --auth-choice mistral-api-key openclaw onboard --mistral-api-key "$MISTRAL_API_KEY" ``` -## مقتطف تكوين (مزوّد LLM) +## مقتطف إعدادات (موفر LLM) ```json5 { @@ -36,21 +36,21 @@ openclaw onboard --mistral-api-key "$MISTRAL_API_KEY" } ``` -## كتالوج LLM المضمّن +## فهرس LLM المضمن -يشحن OpenClaw حاليًا كتالوج Mistral المضمّن التالي: +يشحن OpenClaw حاليًا فهرس Mistral المضمن التالي: -| مرجع النموذج | الإدخال | السياق | الحد الأقصى للخرج | ملاحظات | -| ---------------------------------- | ------------ | ------- | ----------------- | ------------------------- | -| `mistral/mistral-large-latest` | نص، صورة | 262,144 | 16,384 | النموذج الافتراضي | -| `mistral/mistral-medium-2508` | نص، صورة | 262,144 | 8,192 | Mistral Medium 3.1 | -| `mistral/mistral-small-latest` | نص، صورة | 128,000 | 16,384 | نموذج أصغر متعدد الوسائط | -| `mistral/pixtral-large-latest` | نص، صورة | 128,000 | 32,768 | Pixtral | -| `mistral/codestral-latest` | نص | 256,000 | 4,096 | للبرمجة | -| `mistral/devstral-medium-latest` | نص | 262,144 | 32,768 | Devstral 2 | -| `mistral/magistral-small` | نص | 128,000 | 40,000 | يدعم الاستدلال | +| مرجع النموذج | الإدخال | السياق | الحد الأقصى للإخراج | ملاحظات | +| -------------------------------- | ------------ | ------- | ------------------- | ----------------------------------------------------------------- | +| `mistral/mistral-large-latest` | نص، صورة | 262,144 | 16,384 | النموذج الافتراضي | +| `mistral/mistral-medium-2508` | نص، صورة | 262,144 | 8,192 | Mistral Medium 3.1 | +| `mistral/mistral-small-latest` | نص، صورة | 128,000 | 16,384 | Mistral Small 4؛ استدلال قابل للضبط عبر `reasoning_effort` في API | +| `mistral/pixtral-large-latest` | نص، صورة | 128,000 | 32,768 | Pixtral | +| `mistral/codestral-latest` | نص | 256,000 | 4,096 | للبرمجة | +| `mistral/devstral-medium-latest` | نص | 262,144 | 32,768 | Devstral 2 | +| `mistral/magistral-small` | نص | 128,000 | 40,000 | مع تمكين الاستدلال | -## مقتطف تكوين (نسخ الصوت باستخدام Voxtral) +## مقتطف إعدادات (نسخ الصوت باستخدام Voxtral) ```json5 { @@ -65,11 +65,22 @@ openclaw onboard --mistral-api-key "$MISTRAL_API_KEY" } ``` +## الاستدلال القابل للضبط (`mistral-small-latest`) + +يشير `mistral/mistral-small-latest` إلى Mistral Small 4 ويدعم [الاستدلال القابل للضبط](https://docs.mistral.ai/capabilities/reasoning/adjustable) على Chat Completions API عبر `reasoning_effort` (تقلل `none` التفكير الإضافي في المخرجات إلى الحد الأدنى؛ بينما يعرض `high` آثار التفكير الكاملة قبل الإجابة النهائية). + +يربط OpenClaw مستوى **thinking** في الجلسة بـ API الخاص بـ Mistral: + +- **off** / **minimal** → `none` +- **low** / **medium** / **high** / **xhigh** / **adaptive** → `high` + +لا تستخدم النماذج الأخرى في فهرس Mistral المضمن هذا المعامل؛ واصل استخدام نماذج `magistral-*` عندما تريد سلوك Mistral الأصلي المعتمد على الاستدلال أولًا. + ## ملاحظات -- تستخدم مصادقة Mistral القيمة `MISTRAL_API_KEY`. -- تكون القيمة الافتراضية لعنوان URL الأساسي للمزوّد هي `https://api.mistral.ai/v1`. -- النموذج الافتراضي في onboarding هو `mistral/mistral-large-latest`. +- تستخدم مصادقة Mistral المتغير `MISTRAL_API_KEY`. +- يكون عنوان URL الأساسي للموفر افتراضيًا `https://api.mistral.ai/v1`. +- النموذج الافتراضي في الإعداد الأولي هو `mistral/mistral-large-latest`. - نموذج الصوت الافتراضي لفهم الوسائط في Mistral هو `voxtral-mini-latest`. -- يستخدم مسار نسخ الوسائط المسار `/v1/audio/transcriptions`. -- يستخدم مسار embeddings الخاصة بالذاكرة المسار `/v1/embeddings` ‏(النموذج الافتراضي: `mistral-embed`). +- يستخدم مسار نسخ الوسائط `/v1/audio/transcriptions`. +- يستخدم مسار تضمينات الذاكرة `/v1/embeddings` (النموذج الافتراضي: `mistral-embed`). diff --git a/docs/ar/providers/models.md b/docs/ar/providers/models.md index d2e19f153..28a0aea3c 100644 --- a/docs/ar/providers/models.md +++ b/docs/ar/providers/models.md @@ -1,27 +1,27 @@ --- read_when: - - تريد اختيار مزوّد نموذج + - تريد اختيار موفّر نموذج - تريد أمثلة إعداد سريعة لمصادقة LLM + اختيار النموذج -summary: مزوّدو النماذج (LLMs) الذين يدعمهم OpenClaw -title: البدء السريع لمزوّد النماذج +summary: موفّرات النماذج (LLMs) التي يدعمها OpenClaw +title: البدء السريع لموفّر النموذج x-i18n: - generated_at: "2026-04-07T07:21:28Z" + generated_at: "2026-04-08T02:18:28Z" model: gpt-5.4 provider: openai - source_hash: 500191bfe853241096f97928ced2327a13b6f7f62003cb7452b24886c272e6ba + source_hash: 59ee4c2f993fe0ae05fe34f52bc6f3e0fc9a76b10760f56b20ad251e25ee9f20 source_path: providers/models.md workflow: 15 --- -# مزودو النماذج +# موفّرات النماذج -يمكن لـ OpenClaw استخدام العديد من مزوّدي LLM. اختر واحدًا، ثم صادق، ثم اضبط +يمكن لـ OpenClaw استخدام العديد من موفّرات LLM. اختر واحدًا، وقم بالمصادقة، ثم عيّن النموذج الافتراضي بصيغة `provider/model`. ## البدء السريع (خطوتان) -1. صادق مع المزوّد (عادةً عبر `openclaw onboard`). -2. اضبط النموذج الافتراضي: +1. قم بالمصادقة مع الموفّر (عادةً عبر `openclaw onboard`). +2. عيّن النموذج الافتراضي: ```json5 { @@ -29,18 +29,18 @@ x-i18n: } ``` -## المزوّدون المدعومون (المجموعة الابتدائية) +## الموفّرون المدعومون (مجموعة البداية) - [Alibaba Model Studio](/ar/providers/alibaba) - [Anthropic (API + Claude CLI)](/ar/providers/anthropic) - [Amazon Bedrock](/ar/providers/bedrock) -- [BytePlus (دولي)](/ar/concepts/model-providers#byteplus-international) +- [BytePlus (International)](/ar/concepts/model-providers#byteplus-international) - [Chutes](/ar/providers/chutes) - [ComfyUI](/ar/providers/comfy) - [Cloudflare AI Gateway](/ar/providers/cloudflare-ai-gateway) - [fal](/ar/providers/fal) - [Fireworks](/ar/providers/fireworks) -- [نماذج GLM](/ar/providers/glm) +- [GLM models](/ar/providers/glm) - [MiniMax](/ar/providers/minimax) - [Mistral](/ar/providers/mistral) - [Moonshot AI (Kimi + Kimi Coding)](/ar/providers/moonshot) @@ -57,11 +57,11 @@ x-i18n: - [xAI](/ar/providers/xai) - [Z.AI](/ar/providers/zai) -## متغيرات المزوّدات المضمّنة الإضافية +## متغيرات موفّرات إضافية مضمّنة -- `anthropic-vertex` - دعم Anthropic ضمن Google Vertex بشكل ضمني عندما تكون بيانات اعتماد Vertex متاحة؛ لا يوجد خيار مصادقة onboarding منفصل +- `anthropic-vertex` - دعم Anthropic ضمني على Google Vertex عند توفر بيانات اعتماد Vertex؛ لا يوجد خيار مصادقة منفصل أثناء الإعداد الأولي - `copilot-proxy` - جسر Copilot Proxy محلي لـ VS Code؛ استخدم `openclaw onboard --auth-choice copilot-proxy` -- `google-gemini-cli` - تدفق OAuth غير رسمي لـ Gemini CLI؛ يتطلب تثبيت `gemini` محليًا (`brew install gemini-cli` أو `npm install -g @google/gemini-cli`)؛ النموذج الافتراضي هو `google-gemini-cli/gemini-3.1-pro-preview`؛ استخدم `openclaw onboard --auth-choice google-gemini-cli` أو `openclaw models auth login --provider google-gemini-cli --set-default` +- `google-gemini-cli` - تدفق OAuth غير رسمي لـ Gemini CLI؛ يتطلب تثبيت `gemini` محليًا (`brew install gemini-cli` أو `npm install -g @google/gemini-cli`)؛ النموذج الافتراضي هو `google-gemini-cli/gemini-3-flash-preview`؛ استخدم `openclaw onboard --auth-choice google-gemini-cli` أو `openclaw models auth login --provider google-gemini-cli --set-default` -للاطلاع على كتالوج المزوّدين الكامل (xAI وGroq وMistral وما إلى ذلك) والإعدادات المتقدمة، -راجع [مزوّدو النماذج](/ar/concepts/model-providers). +للاطلاع على كتالوج الموفّرات الكامل (xAI وGroq وMistral وغيرها) والتكوين المتقدم، +راجع [موفّرات النماذج](/ar/concepts/model-providers). diff --git a/docs/ar/providers/nvidia.md b/docs/ar/providers/nvidia.md index 1d7a2c1a5..56bb45511 100644 --- a/docs/ar/providers/nvidia.md +++ b/docs/ar/providers/nvidia.md @@ -1,35 +1,35 @@ --- read_when: - - أنت تريد استخدام نماذج NVIDIA في OpenClaw - - أنت تحتاج إلى إعداد NVIDIA_API_KEY -summary: استخدم API المتوافقة مع OpenAI من NVIDIA في OpenClaw + - أنت تريد استخدام النماذج المفتوحة في OpenClaw مجانًا + - تحتاج إلى إعداد NVIDIA_API_KEY +summary: استخدم API المتوافق مع OpenAI من NVIDIA في OpenClaw title: NVIDIA x-i18n: - generated_at: "2026-04-05T12:53:27Z" + generated_at: "2026-04-08T02:18:31Z" model: gpt-5.4 provider: openai - source_hash: a24c5e46c0cf0fbc63bf09c772b486dd7f8f4b52e687d3b835bb54a1176b28da + source_hash: b00f8cedaf223a33ba9f6a6dd8cf066d88cebeea52d391b871e435026182228a source_path: providers/nvidia.md workflow: 15 --- # NVIDIA -توفر NVIDIA واجهة API متوافقة مع OpenAI عند `https://integrate.api.nvidia.com/v1` لنماذج Nemotron وNeMo. قم بالمصادقة باستخدام مفتاح API من [NVIDIA NGC](https://catalog.ngc.nvidia.com/). +توفر NVIDIA واجهة API متوافقة مع OpenAI على `https://integrate.api.nvidia.com/v1` للنماذج المفتوحة مجانًا. قم بالمصادقة باستخدام مفتاح API من [build.nvidia.com](https://build.nvidia.com/settings/api-keys). ## إعداد CLI -قم بتصدير المفتاح مرة واحدة، ثم شغّل onboarding واضبط نموذج NVIDIA: +صدّر المفتاح مرة واحدة، ثم شغّل التهيئة واضبط نموذج NVIDIA: ```bash export NVIDIA_API_KEY="nvapi-..." openclaw onboard --auth-choice skip -openclaw models set nvidia/nvidia/llama-3.1-nemotron-70b-instruct +openclaw models set nvidia/nvidia/nemotron-3-super-120b-a12b ``` -إذا كنت لا تزال تمرر `--token`، فتذكر أنه سيظهر في سجل shell ومخرجات `ps`؛ لذا فضّل متغير البيئة عندما يكون ذلك ممكنًا. +إذا كنت ما تزال تمرر `--token`، فتذكر أنه يُحفَظ في سجل الصدفة ومخرجات `ps`؛ ويفضل استخدام متغير البيئة عند الإمكان. -## مقتطف إعدادات +## مقتطف التكوين ```json5 { @@ -44,7 +44,7 @@ openclaw models set nvidia/nvidia/llama-3.1-nemotron-70b-instruct }, agents: { defaults: { - model: { primary: "nvidia/nvidia/llama-3.1-nemotron-70b-instruct" }, + model: { primary: "nvidia/nvidia/nemotron-3-super-120b-a12b" }, }, }, } @@ -52,14 +52,15 @@ openclaw models set nvidia/nvidia/llama-3.1-nemotron-70b-instruct ## معرّفات النماذج -| مرجع النموذج | الاسم | السياق | الحد الأقصى للخرج | -| ---------------------------------------------------- | ----------------------------------------- | ------- | ----------------- | -| `nvidia/nvidia/llama-3.1-nemotron-70b-instruct` | NVIDIA Llama 3.1 Nemotron 70B Instruct | 131,072 | 4,096 | -| `nvidia/meta/llama-3.3-70b-instruct` | Meta Llama 3.3 70B Instruct | 131,072 | 4,096 | -| `nvidia/nvidia/mistral-nemo-minitron-8b-8k-instruct` | NVIDIA Mistral NeMo Minitron 8B Instruct | 8,192 | 2,048 | +| مرجع النموذج | الاسم | السياق | الحد الأقصى للإخراج | +| ------------------------------------------ | ---------------------------- | ------- | ---------- | +| `nvidia/nvidia/nemotron-3-super-120b-a12b` | NVIDIA Nemotron 3 Super 120B | 262,144 | 8,192 | +| `nvidia/moonshotai/kimi-k2.5` | Kimi K2.5 | 262,144 | 8,192 | +| `nvidia/minimaxai/minimax-m2.5` | Minimax M2.5 | 196,608 | 8,192 | +| `nvidia/z-ai/glm5` | GLM 5 | 202,752 | 8,192 | ## ملاحظات -- نقطة نهاية `/v1` متوافقة مع OpenAI؛ استخدم مفتاح API من NVIDIA NGC. -- يتم تمكين المزوّد تلقائيًا عند ضبط `NVIDIA_API_KEY`. -- يكون الفهرس المضمّن ثابتًا؛ وتكون التكاليف الافتراضية في المصدر هي `0`. +- نقطة نهاية `/v1` متوافقة مع OpenAI؛ استخدم مفتاح API من [build.nvidia.com](https://build.nvidia.com/). +- يتم تمكين الموفّر تلقائيًا عند تعيين `NVIDIA_API_KEY`. +- الفهرس المجمّع ثابت؛ وتكون التكاليف مضبوطة افتراضيًا على `0` في المصدر. diff --git a/docs/ar/providers/ollama.md b/docs/ar/providers/ollama.md index 7db3d1592..289aed30b 100644 --- a/docs/ar/providers/ollama.md +++ b/docs/ar/providers/ollama.md @@ -1,45 +1,45 @@ --- read_when: - تريد تشغيل OpenClaw مع نماذج سحابية أو محلية عبر Ollama - - تحتاج إلى إرشادات إعداد وتهيئة Ollama -summary: تشغيل OpenClaw مع Ollama ‏(النماذج السحابية والمحلية) + - تحتاج إلى إرشادات إعداد وتكوين Ollama +summary: تشغيل OpenClaw مع Ollama (النماذج السحابية والمحلية) title: Ollama x-i18n: - generated_at: "2026-04-05T12:54:06Z" + generated_at: "2026-04-08T02:19:04Z" model: gpt-5.4 provider: openai - source_hash: 337b8ec3a7756e591e6d6f82e8ad13417f0f20c394ec540e8fc5756e0fc13c29 + source_hash: 222ec68f7d4bb29cc7796559ddef1d5059f5159e7a51e2baa3a271ddb3abb716 source_path: providers/ollama.md workflow: 15 --- # Ollama -Ollama هي بيئة تشغيل LLM محلية تجعل من السهل تشغيل النماذج مفتوحة المصدر على جهازك. يتكامل OpenClaw مع API الأصلية لـ Ollama ‏(`/api/chat`)، ويدعم البث واستدعاء الأدوات، ويمكنه الاكتشاف التلقائي لنماذج Ollama المحلية عندما تفعّل ذلك باستخدام `OLLAMA_API_KEY` ‏(أو ملف تعريف مصادقة) ولا تعرّف إدخالًا صريحًا لـ `models.providers.ollama`. +Ollama هو بيئة تشغيل محلية لـ LLM تجعل من السهل تشغيل النماذج مفتوحة المصدر على جهازك. يتكامل OpenClaw مع API الأصلي لـ Ollama (`/api/chat`)، ويدعم البث واستدعاء الأدوات، ويمكنه اكتشاف نماذج Ollama المحلية تلقائيًا عندما تختار ذلك عبر `OLLAMA_API_KEY` (أو ملف تعريف مصادقة) ولا تعرّف إدخال `models.providers.ollama` صريحًا. -**مستخدمو Ollama البعيدة**: لا تستخدم عنوان URL المتوافق مع OpenAI لمسار `/v1` ‏(`http://host:11434/v1`) مع OpenClaw. فهذا يكسر استدعاء الأدوات، وقد تخرج النماذج JSON الأدوات الخام كنص عادي. استخدم بدلًا من ذلك عنوان API الأصلي لـ Ollama: ‏`baseUrl: "http://host:11434"` ‏(من دون `/v1`). +**مستخدمو Ollama البعيد**: لا تستخدم عنوان URL المتوافق مع OpenAI الخاص بـ `/v1` (`http://host:11434/v1`) مع OpenClaw. فهذا يعطّل استدعاء الأدوات وقد تُخرج النماذج JSON الأدوات الخام كنص عادي. استخدم بدلًا من ذلك عنوان URL الخاص بـ API الأصلي لـ Ollama: ‏`baseUrl: "http://host:11434"` (من دون `/v1`). -## بدء سريع +## البدء السريع -### Onboarding ‏(موصى به) +### الإعداد الأولي (مستحسن) -أسرع طريقة لإعداد Ollama هي عبر onboarding: +أسرع طريقة لإعداد Ollama هي عبر الإعداد الأولي: ```bash openclaw onboard ``` -اختر **Ollama** من قائمة الموفّرين. ستقوم onboarding بما يلي: +اختر **Ollama** من قائمة الموفّرين. سيقوم الإعداد الأولي بما يلي: -1. ستسأل عن base URL الخاص بـ Ollama الذي يمكن الوصول إلى مثيلك من خلاله (الافتراضي `http://127.0.0.1:11434`). -2. ستتيح لك الاختيار بين **Cloud + Local** ‏(النماذج السحابية والنماذج المحلية) أو **Local** ‏(النماذج المحلية فقط). -3. ستفتح تدفق تسجيل دخول في المتصفح إذا اخترت **Cloud + Local** ولم تكن قد سجلت الدخول إلى ollama.com. -4. ستكتشف النماذج المتاحة وتقترح القيم الافتراضية. -5. ستنفذ `pull` للنموذج المحدد تلقائيًا إذا لم يكن متاحًا محليًا. +1. سيسألك عن عنوان URL الأساسي لـ Ollama الذي يمكن الوصول إلى المثيل من خلاله (الافتراضي `http://127.0.0.1:11434`). +2. يتيح لك اختيار **Cloud + Local** (نماذج سحابية ونماذج محلية) أو **Local** (نماذج محلية فقط). +3. يفتح تدفق تسجيل دخول عبر المتصفح إذا اخترت **Cloud + Local** ولم تكن قد سجلت الدخول إلى ollama.com. +4. يكتشف النماذج المتاحة ويقترح الإعدادات الافتراضية. +5. يسحب النموذج المحدد تلقائيًا إذا لم يكن متاحًا محليًا. -كما يُدعم الوضع غير التفاعلي: +الوضع غير التفاعلي مدعوم أيضًا: ```bash openclaw onboard --non-interactive \ @@ -47,7 +47,7 @@ openclaw onboard --non-interactive \ --accept-risk ``` -يمكنك اختياريًا تحديد base URL أو نموذج مخصص: +يمكنك اختياريًا تحديد عنوان URL أساسي مخصص أو نموذج مخصص: ```bash openclaw onboard --non-interactive \ @@ -59,12 +59,12 @@ openclaw onboard --non-interactive \ ### الإعداد اليدوي -1. ثبّت Ollama: ‏[https://ollama.com/download](https://ollama.com/download) +1. ثبّت Ollama: [https://ollama.com/download](https://ollama.com/download) -2. نفّذ `pull` لنموذج محلي إذا كنت تريد استدلالًا محليًا: +2. اسحب نموذجًا محليًا إذا كنت تريد استدلالًا محليًا: ```bash -ollama pull glm-4.7-flash +ollama pull gemma4 # أو ollama pull gpt-oss:20b # أو @@ -77,28 +77,28 @@ ollama pull llama3.3 ollama signin ``` -4. شغّل onboarding واختر `Ollama`: +4. شغّل الإعداد الأولي واختر `Ollama`: ```bash openclaw onboard ``` -- `Local`: النماذج المحلية فقط -- `Cloud + Local`: النماذج المحلية بالإضافة إلى النماذج السحابية -- النماذج السحابية مثل `kimi-k2.5:cloud` و`minimax-m2.5:cloud` و`glm-5:cloud` **لا** تتطلب تنفيذ `ollama pull` محليًا +- `Local`: نماذج محلية فقط +- `Cloud + Local`: نماذج محلية بالإضافة إلى نماذج سحابية +- النماذج السحابية مثل `kimi-k2.5:cloud` و`minimax-m2.7:cloud` و`glm-5.1:cloud` لا **تتطلب** `ollama pull` محليًا يقترح OpenClaw حاليًا: -- الافتراضي المحلي: `glm-4.7-flash` -- القيم الافتراضية السحابية: `kimi-k2.5:cloud` و`minimax-m2.5:cloud` و`glm-5:cloud` +- الافتراضي المحلي: `gemma4` +- الإعدادات الافتراضية السحابية: `kimi-k2.5:cloud` و`minimax-m2.7:cloud` و`glm-5.1:cloud` -5. إذا كنت تفضل الإعداد اليدوي، ففعّل Ollama لـ OpenClaw مباشرة (أي قيمة تعمل؛ لا تتطلب Ollama مفتاحًا حقيقيًا): +5. إذا كنت تفضّل الإعداد اليدوي، فقم بتمكين Ollama مباشرة لـ OpenClaw (أي قيمة تعمل؛ لا يتطلب Ollama مفتاحًا حقيقيًا): ```bash # تعيين متغير البيئة export OLLAMA_API_KEY="ollama-local" -# أو التهيئة في ملف الإعداد +# أو التكوين في ملف التكوين openclaw config set models.providers.ollama.apiKey "ollama-local" ``` @@ -106,41 +106,41 @@ openclaw config set models.providers.ollama.apiKey "ollama-local" ```bash openclaw models list -openclaw models set ollama/glm-4.7-flash +openclaw models set ollama/gemma4 ``` -7. أو اضبط القيمة الافتراضية في الإعداد: +7. أو عيّن الإعداد الافتراضي في التكوين: ```json5 { agents: { defaults: { - model: { primary: "ollama/glm-4.7-flash" }, + model: { primary: "ollama/gemma4" }, }, }, } ``` -## اكتشاف النماذج (موفّر ضمني) +## اكتشاف النماذج (الموفّر الضمني) -عندما تضبط `OLLAMA_API_KEY` ‏(أو ملف تعريف مصادقة) و**لا** تعرّف `models.providers.ollama`، يكتشف OpenClaw النماذج من مثيل Ollama المحلي على `http://127.0.0.1:11434`: +عندما تعيّن `OLLAMA_API_KEY` (أو ملف تعريف مصادقة) و**لا** تعرّف `models.providers.ollama`، يكتشف OpenClaw النماذج من مثيل Ollama المحلي على `http://127.0.0.1:11434`: -- يستعلم `/api/tags` -- يستخدم عمليات lookup من نوع `/api/show` بأفضل جهد لقراءة `contextWindow` عند التوفر -- يوسم `reasoning` باستخدام heuristics لأسماء النماذج (`r1` أو `reasoning` أو `think`) -- يضبط `maxTokens` على الحد الأقصى الافتراضي للرموز في Ollama الذي يستخدمه OpenClaw +- يستعلم عن `/api/tags` +- يستخدم عمليات بحث `/api/show` بأفضل جهد لقراءة `contextWindow` عند توفره +- يضع علامة `reasoning` باستخدام استدلال يعتمد على اسم النموذج (`r1` أو `reasoning` أو `think`) +- يضبط `maxTokens` على الحد الأقصى الافتراضي للرموز في Ollama المستخدم من قبل OpenClaw - يضبط جميع التكاليف على `0` -وهذا يتجنب إدخالات النماذج اليدوية مع إبقاء الفهرس متوافقًا مع مثيل Ollama المحلي. +يؤدي ذلك إلى تجنب إدخالات النماذج اليدوية مع إبقاء الكتالوج متوافقًا مع مثيل Ollama المحلي. -لرؤية النماذج المتاحة: +لمعرفة النماذج المتاحة: ```bash ollama list openclaw models list ``` -لإضافة نموذج جديد، ما عليك سوى تنفيذ `pull` له باستخدام Ollama: +لإضافة نموذج جديد، ما عليك سوى سحبه عبر Ollama: ```bash ollama pull mistral @@ -148,9 +148,9 @@ ollama pull mistral سيتم اكتشاف النموذج الجديد تلقائيًا وسيصبح متاحًا للاستخدام. -إذا ضبطت `models.providers.ollama` صراحة، فسيتم تخطي الاكتشاف التلقائي وسيتعين عليك تعريف النماذج يدويًا (راجع أدناه). +إذا عيّنت `models.providers.ollama` صراحة، فسيتم تخطي الاكتشاف التلقائي، ويجب عليك تعريف النماذج يدويًا (انظر أدناه). -## الإعداد +## التكوين ### إعداد أساسي (اكتشاف ضمني) @@ -162,9 +162,9 @@ export OLLAMA_API_KEY="ollama-local" ### إعداد صريح (نماذج يدوية) -استخدم الإعداد الصريح عندما: +استخدم التكوين الصريح عندما: -- تعمل Ollama على مضيف/منفذ آخر. +- يعمل Ollama على مضيف/منفذ آخر. - تريد فرض نوافذ سياق أو قوائم نماذج محددة. - تريد تعريفات نماذج يدوية بالكامل. @@ -193,11 +193,11 @@ export OLLAMA_API_KEY="ollama-local" } ``` -إذا كان `OLLAMA_API_KEY` مضبوطًا، يمكنك حذف `apiKey` من إدخال الموفّر وسيملؤه OpenClaw من أجل فحوصات التوافر. +إذا كان `OLLAMA_API_KEY` معيّنًا، فيمكنك حذف `apiKey` من إدخال الموفّر وسيقوم OpenClaw بملئه من أجل فحوصات التوفر. -### Base URL مخصص (إعداد صريح) +### عنوان URL أساسي مخصص (تكوين صريح) -إذا كانت Ollama تعمل على مضيف أو منفذ مختلفين (يؤدي الإعداد الصريح إلى تعطيل الاكتشاف التلقائي، لذا عرّف النماذج يدويًا): +إذا كان Ollama يعمل على مضيف أو منفذ مختلفين (يعطّل التكوين الصريح الاكتشاف التلقائي، لذا عرّف النماذج يدويًا): ```json5 { @@ -205,8 +205,8 @@ export OLLAMA_API_KEY="ollama-local" providers: { ollama: { apiKey: "ollama-local", - baseUrl: "http://ollama-host:11434", // بدون /v1 - استخدم عنوان API الأصلي لـ Ollama - api: "ollama", // اضبطه صراحة لضمان سلوك استدعاء الأدوات الأصلي + baseUrl: "http://ollama-host:11434", // بدون /v1 - استخدم عنوان URL الخاص بـ API الأصلي لـ Ollama + api: "ollama", // عيّنه صراحة لضمان سلوك استدعاء الأدوات الأصلي }, }, }, @@ -214,12 +214,12 @@ export OLLAMA_API_KEY="ollama-local" ``` -لا تضف `/v1` إلى عنوان URL. فالمسار `/v1` يستخدم الوضع المتوافق مع OpenAI، حيث لا يكون استدعاء الأدوات موثوقًا. استخدم عنوان Ollama الأساسي من دون لاحقة مسار. +لا تضف `/v1` إلى عنوان URL. يستخدم المسار `/v1` الوضع المتوافق مع OpenAI، حيث لا يكون استدعاء الأدوات موثوقًا. استخدم عنوان URL الأساسي لـ Ollama من دون لاحقة مسار. ### اختيار النموذج -بمجرد التهيئة، تصبح كل نماذج Ollama لديك متاحة: +بمجرد التكوين، ستكون جميع نماذج Ollama الخاصة بك متاحة: ```json5 { @@ -236,24 +236,24 @@ export OLLAMA_API_KEY="ollama-local" ## النماذج السحابية -تتيح لك النماذج السحابية تشغيل نماذج مستضافة سحابيًا (مثل `kimi-k2.5:cloud` و`minimax-m2.5:cloud` و`glm-5:cloud`) إلى جانب نماذجك المحلية. +تتيح لك النماذج السحابية تشغيل نماذج مستضافة سحابيًا (على سبيل المثال `kimi-k2.5:cloud` و`minimax-m2.7:cloud` و`glm-5.1:cloud`) إلى جانب نماذجك المحلية. -لاستخدام النماذج السحابية، اختر وضع **Cloud + Local** أثناء الإعداد. ويتحقق المعالج مما إذا كنت مسجل الدخول ويفتح تدفق تسجيل دخول في المتصفح عند الحاجة. وإذا تعذّر التحقق من المصادقة، يعود المعالج إلى القيم الافتراضية للنماذج المحلية. +لاستخدام النماذج السحابية، اختر وضع **Cloud + Local** أثناء الإعداد. يتحقق المعالج مما إذا كنت قد سجلت الدخول ويفتح تدفق تسجيل دخول عبر المتصفح عند الحاجة. إذا تعذر التحقق من المصادقة، فسيعود المعالج إلى الإعدادات الافتراضية للنماذج المحلية. يمكنك أيضًا تسجيل الدخول مباشرة على [ollama.com/signin](https://ollama.com/signin). ## Ollama Web Search -يدعم OpenClaw أيضًا **Ollama Web Search** بوصفه موفّر `web_search` -مدمجًا. +يدعم OpenClaw أيضًا **Ollama Web Search** كموفّر +`web_search` مضمّن. -- يستخدم مضيف Ollama المهيأ لديك (`models.providers.ollama.baseUrl` عندما - يكون مضبوطًا، وإلا `http://127.0.0.1:11434`). +- يستخدم مضيف Ollama المهيأ لديك (`models.providers.ollama.baseUrl` عند + تعيينه، وإلا `http://127.0.0.1:11434`). - لا يحتاج إلى مفتاح. -- يتطلب أن تكون Ollama قيد التشغيل وأن تكون قد سجلت الدخول عبر `ollama signin`. +- يتطلب أن يكون Ollama قيد التشغيل وأن تكون قد سجلت الدخول عبر `ollama signin`. اختر **Ollama Web Search** أثناء `openclaw onboard` أو -`openclaw configure --section web`، أو اضبط: +`openclaw configure --section web`، أو عيّن: ```json5 { @@ -267,13 +267,13 @@ export OLLAMA_API_KEY="ollama-local" } ``` -للحصول على التفاصيل الكاملة الخاصة بالإعداد والسلوك، راجع [Ollama Web Search](/tools/ollama-search). +للحصول على تفاصيل الإعداد والسلوك الكاملة، راجع [Ollama Web Search](/ar/tools/ollama-search). ## متقدم ### نماذج الاستدلال -يتعامل OpenClaw افتراضيًا مع النماذج التي تحمل أسماء مثل `deepseek-r1` أو `reasoning` أو `think` على أنها قادرة على الاستدلال: +يعامل OpenClaw النماذج ذات الأسماء مثل `deepseek-r1` أو `reasoning` أو `think` على أنها قادرة على الاستدلال افتراضيًا: ```bash ollama pull deepseek-r1:32b @@ -281,19 +281,19 @@ ollama pull deepseek-r1:32b ### تكاليف النماذج -Ollama مجانية وتعمل محليًا، لذلك تُضبط جميع تكاليف النماذج على $0. +Ollama مجاني ويعمل محليًا، لذا يتم تعيين جميع تكاليف النماذج إلى $0. -### تهيئة البث +### تكوين البث -يستخدم تكامل OpenClaw مع Ollama **API الأصلية لـ Ollama** ‏(`/api/chat`) افتراضيًا، والتي تدعم بالكامل البث واستدعاء الأدوات في الوقت نفسه. ولا حاجة إلى أي إعداد خاص. +يستخدم تكامل OpenClaw مع Ollama **API الأصلي لـ Ollama** (`/api/chat`) افتراضيًا، وهو يدعم بالكامل البث واستدعاء الأدوات في الوقت نفسه. لا يلزم أي تكوين خاص. #### الوضع القديم المتوافق مع OpenAI -**استدعاء الأدوات ليس موثوقًا في الوضع المتوافق مع OpenAI.** استخدم هذا الوضع فقط إذا كنت تحتاج إلى تنسيق OpenAI من أجل proxy ولا تعتمد على سلوك استدعاء الأدوات الأصلي. +**استدعاء الأدوات ليس موثوقًا في الوضع المتوافق مع OpenAI.** استخدم هذا الوضع فقط إذا كنت بحاجة إلى تنسيق OpenAI من أجل وكيل ولا تعتمد على سلوك استدعاء الأدوات الأصلي. -إذا كنت تحتاج إلى استخدام نقطة النهاية المتوافقة مع OpenAI بدلًا من ذلك (مثلًا خلف proxy لا يدعم إلا تنسيق OpenAI)، فاضبط `api: "openai-completions"` صراحة: +إذا كنت بحاجة إلى استخدام نقطة النهاية المتوافقة مع OpenAI بدلًا من ذلك (مثلًا خلف وكيل لا يدعم إلا تنسيق OpenAI)، فعيّن `api: "openai-completions"` صراحة: ```json5 { @@ -311,9 +311,9 @@ Ollama مجانية وتعمل محليًا، لذلك تُضبط جميع تك } ``` -قد لا يدعم هذا الوضع البث + استدعاء الأدوات في وقت واحد. وقد تحتاج إلى تعطيل البث باستخدام `params: { streaming: false }` في إعداد النموذج. +قد لا يدعم هذا الوضع البث + استدعاء الأدوات في الوقت نفسه. قد تحتاج إلى تعطيل البث باستخدام `params: { streaming: false }` في تكوين النموذج. -عندما يُستخدم `api: "openai-completions"` مع Ollama، يحقن OpenClaw القيمة `options.num_ctx` افتراضيًا حتى لا تعود Ollama بصمت إلى نافذة سياق مقدارها 4096. وإذا كان proxy/upstream لديك يرفض حقول `options` غير المعروفة، فقم بتعطيل هذا السلوك: +عند استخدام `api: "openai-completions"` مع Ollama، يحقن OpenClaw القيمة `options.num_ctx` افتراضيًا حتى لا يعود Ollama بصمت إلى نافذة سياق قدرها 4096. إذا كان وكيلك/خادمك الصاعد يرفض حقول `options` غير المعروفة، فعطّل هذا السلوك: ```json5 { @@ -333,19 +333,19 @@ Ollama مجانية وتعمل محليًا، لذلك تُضبط جميع تك ### نوافذ السياق -بالنسبة إلى النماذج المكتشفة تلقائيًا، يستخدم OpenClaw نافذة السياق التي يبلّغ عنها Ollama عندما تكون متاحة، وإلا فإنه يعود إلى نافذة سياق Ollama الافتراضية التي يستخدمها OpenClaw. ويمكنك تجاوز `contextWindow` و`maxTokens` في إعداد الموفّر الصريح. +بالنسبة إلى النماذج المكتشفة تلقائيًا، يستخدم OpenClaw نافذة السياق التي يبلغ عنها Ollama عند توفرها، وإلا فإنه يعود إلى نافذة سياق Ollama الافتراضية المستخدمة من قبل OpenClaw. يمكنك تجاوز `contextWindow` و`maxTokens` في تكوين الموفّر الصريح. ## استكشاف الأخطاء وإصلاحها ### لم يتم اكتشاف Ollama -تأكد من أن Ollama قيد التشغيل وأنك قد ضبطت `OLLAMA_API_KEY` ‏(أو ملف تعريف مصادقة)، وأنك **لم** تعرّف إدخالًا صريحًا لـ `models.providers.ollama`: +تأكد من أن Ollama قيد التشغيل وأنك عيّنت `OLLAMA_API_KEY` (أو ملف تعريف مصادقة)، وأنك **لم** تعرّف إدخال `models.providers.ollama` صريحًا: ```bash ollama serve ``` -وتأكد من أن API قابلة للوصول: +وتأكد من أن API يمكن الوصول إليه: ```bash curl http://localhost:11434/api/tags @@ -353,26 +353,26 @@ curl http://localhost:11434/api/tags ### لا توجد نماذج متاحة -إذا لم يكن نموذجك مدرجًا، فإما: +إذا لم يكن نموذجك مدرجًا، فإما أن: -- أن تنفّذ `pull` للنموذج محليًا، أو -- أن تعرّف النموذج صراحة في `models.providers.ollama`. +- تسحب النموذج محليًا، أو +- تعرّف النموذج صراحة في `models.providers.ollama`. لإضافة نماذج: ```bash -ollama list # عرض ما هو مثبت -ollama pull glm-4.7-flash +ollama list # اعرض ما هو مثبّت +ollama pull gemma4 ollama pull gpt-oss:20b ollama pull llama3.3 # أو نموذج آخر ``` ### تم رفض الاتصال -تحقق من أن Ollama تعمل على المنفذ الصحيح: +تحقق من أن Ollama يعمل على المنفذ الصحيح: ```bash -# تحقق مما إذا كانت Ollama تعمل +# تحقق مما إذا كان Ollama قيد التشغيل ps aux | grep ollama # أو أعد تشغيل Ollama @@ -381,6 +381,6 @@ ollama serve ## راجع أيضًا -- [موفرو النماذج](/concepts/model-providers) - نظرة عامة على جميع الموفّرين -- [اختيار النموذج](/concepts/models) - كيفية اختيار النماذج -- [التهيئة](/gateway/configuration) - المرجع الكامل للإعداد +- [موفّرات النماذج](/ar/concepts/model-providers) - نظرة عامة على جميع الموفّرين +- [اختيار النموذج](/ar/concepts/models) - كيفية اختيار النماذج +- [التكوين](/ar/gateway/configuration) - المرجع الكامل للتكوين diff --git a/docs/ar/refactor/qa.md b/docs/ar/refactor/qa.md new file mode 100644 index 000000000..c523e2cfb --- /dev/null +++ b/docs/ar/refactor/qa.md @@ -0,0 +1,534 @@ +--- +x-i18n: + generated_at: "2026-04-08T02:19:16Z" + model: gpt-5.4 + provider: openai + source_hash: 0e156cc8e2fe946a0423862f937754a7caa1fe7e6863b50a80bff49a1c86e1e8 + source_path: refactor/qa.md + workflow: 15 +--- + +# إعادة هيكلة QA + +الحالة: تم إنجاز الترحيل التأسيسي. + +## الهدف + +نقل QA في OpenClaw من نموذج تعريف منقسم إلى مصدر حقيقة واحد: + +- بيانات السيناريو الوصفية +- الموجّهات المرسلة إلى النموذج +- الإعداد والتنظيف +- منطق أداة التشغيل +- التأكيدات ومعايير النجاح +- العناصر الناتجة وتلميحات التقرير + +الحالة النهائية المطلوبة هي أداة QA عامة تقوم بتحميل ملفات تعريف سيناريو قوية بدلًا من ترميز معظم السلوك بشكل ثابت في TypeScript. + +## الحالة الحالية + +المصدر الأساسي للحقيقة موجود الآن في `qa/scenarios.md`. + +تم تنفيذ ما يلي: + +- `qa/scenarios.md` + - حزمة QA القياسية + - هوية المشغّل + - مهمة الانطلاق + - بيانات السيناريو الوصفية + - روابط المعالِجات +- `extensions/qa-lab/src/scenario-catalog.ts` + - محلّل حزمة markdown + تحقق zod +- `extensions/qa-lab/src/qa-agent-bootstrap.ts` + - عرض الخطة من حزمة markdown +- `extensions/qa-lab/src/qa-agent-workspace.ts` + - يزرع ملفات توافق مولّدة بالإضافة إلى `QA_SCENARIOS.md` +- `extensions/qa-lab/src/suite.ts` + - يختار السيناريوهات القابلة للتنفيذ عبر روابط المعالِجات المعرّفة في markdown +- بروتوكول ناقل QA + UI + - مرفقات مضمنة عامة لعرض الصور/الفيديو/الصوت/الملفات + +الأسطح المنقسمة المتبقية: + +- `extensions/qa-lab/src/suite.ts` + - لا يزال يملك معظم منطق المعالِجات المخصصة القابلة للتنفيذ +- `extensions/qa-lab/src/report.ts` + - لا يزال يشتق بنية التقرير من مخرجات runtime + +لذا تم إصلاح انقسام مصدر الحقيقة، لكن التنفيذ لا يزال يعتمد في الغالب على المعالِجات بدلًا من أن يكون تصريحيًا بالكامل. + +## كيف يبدو سطح السيناريو الحقيقي + +تُظهر قراءة الحزمة الحالية بضع فئات مميزة من السيناريوهات. + +### تفاعل بسيط + +- خط أساس القناة +- خط أساس الرسائل المباشرة +- متابعة مترابطة +- تبديل النموذج +- استكمال الموافقة +- التفاعل/التحرير/الحذف + +### تعديل الإعدادات وruntime + +- تصحيح config لتعطيل skill +- إيقاظ إعادة تشغيل تطبيق config +- قلب قدرة إعادة تشغيل config +- فحص انجراف مخزون runtime + +### تأكيدات نظام الملفات والمستودع + +- تقرير اكتشاف المصدر/الوثائق +- بناء Lobster Invaders +- البحث عن عنصر ناتج صورة مولّدة + +### تنظيم الذاكرة + +- استدعاء الذاكرة +- أدوات الذاكرة في سياق القناة +- احتياط فشل الذاكرة +- ترتيب ذاكرة الجلسة +- عزل ذاكرة السلسلة +- اكتساح أحلام الذاكرة + +### تكامل الأدوات وplugin + +- استدعاء أدوات plugin الخاصة بـ MCP +- ظهور skill +- تثبيت skill ساخن +- إنشاء صور أصلي +- دورة كاملة للصورة +- فهم الصورة من المرفق + +### متعدد الأدوار ومتعدد الأطراف + +- تسليم إلى وكيل فرعي +- تجميع توليف الوكيل الفرعي +- تدفقات بأسلوب الاسترداد بعد إعادة التشغيل + +هذه الفئات مهمة لأنها تحدد متطلبات DSL. لا تكفي قائمة مسطحة من موجّه + نص متوقع. + +## الاتجاه + +### مصدر حقيقة واحد + +استخدم `qa/scenarios.md` بوصفه مصدر الحقيقة المؤلف. + +يجب أن تظل الحزمة: + +- قابلة للقراءة البشرية أثناء المراجعة +- قابلة للتحليل آليًا +- غنية بما يكفي لقيادة: + - تنفيذ الحزمة + - تمهيد مساحة عمل QA + - بيانات تعريف QA Lab في UI + - موجّهات الوثائق/الاكتشاف + - توليد التقارير + +### تنسيق التأليف المفضّل + +استخدم markdown باعتباره التنسيق الأعلى، مع YAML منظّم بداخله. + +البنية الموصى بها: + +- YAML frontmatter + - id + - title + - surface + - tags + - مراجع الوثائق + - مراجع الشيفرة + - تجاوزات النموذج/الموفر + - المتطلبات المسبقة +- أقسام نثرية + - الهدف + - الملاحظات + - تلميحات التصحيح +- كتل YAML مسوّرة + - setup + - steps + - assertions + - cleanup + +وهذا يوفّر: + +- قابلية قراءة أفضل في PR من JSON ضخم +- سياقًا أغنى من YAML صرف +- تحليلًا صارمًا وتحقق zod + +يكون JSON الخام مقبولًا فقط بوصفه صيغة وسيطة مولّدة. + +## البنية المقترحة لملف السيناريو + +مثال: + +````md +--- +id: image-generation-roundtrip +title: Image generation roundtrip +surface: image +tags: [media, image, roundtrip] +models: + primary: openai/gpt-5.4 +requires: + tools: [image_generate] + plugins: [openai, qa-channel] +docsRefs: + - docs/help/testing.md + - docs/concepts/model-providers.md +codeRefs: + - extensions/qa-lab/src/suite.ts + - src/gateway/chat-attachments.ts +--- + +# Objective + +Verify generated media is reattached on the follow-up turn. + +# Setup + +```yaml scenario.setup +- action: config.patch + patch: + agents: + defaults: + imageGenerationModel: + primary: openai/gpt-image-1 +- action: session.create + key: agent:qa:image-roundtrip +``` + +# Steps + +```yaml scenario.steps +- action: agent.send + session: agent:qa:image-roundtrip + message: | + Image generation check: generate a QA lighthouse image and summarize it in one short sentence. +- action: artifact.capture + kind: generated-image + promptSnippet: Image generation check + saveAs: lighthouseImage +- action: agent.send + session: agent:qa:image-roundtrip + message: | + Roundtrip image inspection check: describe the generated lighthouse attachment in one short sentence. + attachments: + - fromArtifact: lighthouseImage +``` + +# Expect + +```yaml scenario.expect +- assert: outbound.textIncludes + value: lighthouse +- assert: requestLog.matches + where: + promptIncludes: Roundtrip image inspection check + imageInputCountGte: 1 +- assert: artifact.exists + ref: lighthouseImage +``` +```` + +## قدرات أداة التشغيل التي يجب أن يغطيها DSL + +استنادًا إلى الحزمة الحالية، تحتاج أداة التشغيل العامة إلى أكثر من مجرد تنفيذ الموجّهات. + +### إجراءات البيئة والإعداد + +- `bus.reset` +- `gateway.waitHealthy` +- `channel.waitReady` +- `session.create` +- `thread.create` +- `workspace.writeSkill` + +### إجراءات دور الوكيل + +- `agent.send` +- `agent.wait` +- `bus.injectInbound` +- `bus.injectOutbound` + +### إجراءات الإعدادات وruntime + +- `config.get` +- `config.patch` +- `config.apply` +- `gateway.restart` +- `tools.effective` +- `skills.status` + +### إجراءات الملفات والعناصر الناتجة + +- `file.write` +- `file.read` +- `file.delete` +- `file.touchTime` +- `artifact.captureGeneratedImage` +- `artifact.capturePath` + +### إجراءات الذاكرة وcron + +- `memory.indexForce` +- `memory.searchCli` +- `doctor.memory.status` +- `cron.list` +- `cron.run` +- `cron.waitCompletion` +- `sessionTranscript.write` + +### إجراءات MCP + +- `mcp.callTool` + +### التأكيدات + +- `outbound.textIncludes` +- `outbound.inThread` +- `outbound.notInRoot` +- `tool.called` +- `tool.notPresent` +- `skill.visible` +- `skill.disabled` +- `file.contains` +- `memory.contains` +- `requestLog.matches` +- `sessionStore.matches` +- `cron.managedPresent` +- `artifact.exists` + +## المتغيرات ومراجع العناصر الناتجة + +يجب أن يدعم DSL المخرجات المحفوظة والمراجع اللاحقة. + +أمثلة من الحزمة الحالية: + +- إنشاء سلسلة، ثم إعادة استخدام `threadId` +- إنشاء جلسة، ثم إعادة استخدام `sessionKey` +- إنشاء صورة، ثم إرفاق الملف في الدور التالي +- إنشاء سلسلة علامة إيقاظ، ثم التأكيد على ظهورها لاحقًا + +القدرات المطلوبة: + +- `saveAs` +- `${vars.name}` +- `${artifacts.name}` +- مراجع مكتوبة النوع للمسارات، ومفاتيح الجلسة، ومعرّفات السلاسل، والعلامات، ومخرجات الأدوات + +من دون دعم المتغيرات، ستظل أداة التشغيل تسرّب منطق السيناريو إلى TypeScript. + +## ما الذي يجب أن يبقى كمنافذ هروب + +ليست أداة تشغيل تصريحية نقية بالكامل واقعية في المرحلة 1. + +بعض السيناريوهات بطبيعتها كثيفة التنسيق: + +- اكتساح أحلام الذاكرة +- إيقاظ إعادة تشغيل تطبيق config +- قلب قدرة إعادة تشغيل config +- حل عنصر الصورة المولّد حسب الطابع الزمني/المسار +- تقييم تقرير الاكتشاف + +يجب أن تستخدم هذه السيناريوهات معالِجات مخصصة صريحة في الوقت الحالي. + +القاعدة الموصى بها: + +- 85-90% تصريحي +- خطوات `customHandler` صريحة للباقي الصعب +- معالِجات مخصصة مسماة وموثقة فقط +- لا شيفرة مضمنة مجهولة داخل ملف السيناريو + +يبقي ذلك المحرك العام نظيفًا مع السماح بالتقدم. + +## التغيير المعماري + +### الحالي + +يعد markdown الخاص بالسيناريو بالفعل مصدر الحقيقة لـ: + +- تنفيذ الحزمة +- ملفات تمهيد مساحة العمل +- فهرس سيناريو QA Lab في UI +- بيانات التقرير الوصفية +- موجّهات الاكتشاف + +التوافق المولّد: + +- لا تزال مساحة العمل المزروعة تتضمن `QA_KICKOFF_TASK.md` +- لا تزال مساحة العمل المزروعة تتضمن `QA_SCENARIO_PLAN.md` +- تتضمن مساحة العمل المزروعة الآن أيضًا `QA_SCENARIOS.md` + +## خطة إعادة الهيكلة + +### المرحلة 1: أداة التحميل والمخطط + +تمت. + +- تمت إضافة `qa/scenarios.md` +- تمت إضافة محلّل لمحتوى حزمة markdown YAML المسماة +- تم التحقق باستخدام zod +- تم تحويل المستهلكين إلى الحزمة المحللة +- تمت إزالة `qa/seed-scenarios.json` و`qa/QA_KICKOFF_TASK.md` على مستوى المستودع + +### المرحلة 2: المحرك العام + +- تقسيم `extensions/qa-lab/src/suite.ts` إلى: + - أداة تحميل + - محرك + - سجل إجراءات + - سجل تأكيدات + - معالِجات مخصصة +- الإبقاء على الدوال المساعدة الحالية كعمليات للمحرك + +المُنجَز: + +- ينفذ المحرك السيناريوهات التصريحية البسيطة + +ابدأ بالسيناريوهات التي تتكون غالبًا من موجّه + انتظار + تأكيد: + +- متابعة مترابطة +- فهم الصورة من المرفق +- ظهور skill واستدعاؤها +- خط أساس القناة + +المُنجَز: + +- أول سيناريوهات حقيقية معرّفة في markdown تُشحن عبر المحرك العام + +### المرحلة 4: ترحيل السيناريوهات المتوسطة + +- دورة كاملة لإنشاء الصور +- أدوات الذاكرة في سياق القناة +- ترتيب ذاكرة الجلسة +- تسليم إلى وكيل فرعي +- تجميع توليف الوكيل الفرعي + +المُنجَز: + +- إثبات المتغيرات والعناصر الناتجة وتأكيدات الأدوات وتأكيدات سجل الطلبات + +### المرحلة 5: إبقاء السيناريوهات الصعبة على المعالِجات المخصصة + +- اكتساح أحلام الذاكرة +- إيقاظ إعادة تشغيل تطبيق config +- قلب قدرة إعادة تشغيل config +- انجراف مخزون runtime + +المُنجَز: + +- تنسيق التأليف نفسه، لكن مع كتل خطوات مخصصة صريحة عند الحاجة + +### المرحلة 6: حذف خريطة السيناريوهات المرمّزة ثابتًا + +بمجرد أن تصبح تغطية الحزمة جيدة بما يكفي: + +- إزالة معظم التفرعات الخاصة بالسيناريوهات في TypeScript من `extensions/qa-lab/src/suite.ts` + +## دعم Fake Slack / الوسائط الغنية + +ناقل QA الحالي يركز على النص أولًا. + +الملفات ذات الصلة: + +- `extensions/qa-channel/src/protocol.ts` +- `extensions/qa-lab/src/bus-state.ts` +- `extensions/qa-lab/src/bus-queries.ts` +- `extensions/qa-lab/src/bus-server.ts` +- `extensions/qa-lab/web/src/ui-render.ts` + +اليوم يدعم ناقل QA: + +- النص +- التفاعلات +- السلاسل + +ولا يقوم بعد بنمذجة مرفقات الوسائط المضمنة. + +### عقد النقل المطلوب + +أضف نموذج مرفقات ناقل QA عامًا: + +```ts +type QaBusAttachment = { + id: string; + kind: "image" | "video" | "audio" | "file"; + mimeType: string; + fileName?: string; + inline?: boolean; + url?: string; + contentBase64?: string; + width?: number; + height?: number; + durationMs?: number; + altText?: string; + transcript?: string; +}; +``` + +ثم أضف `attachments?: QaBusAttachment[]` إلى: + +- `QaBusMessage` +- `QaBusInboundMessageInput` +- `QaBusOutboundMessageInput` + +### لماذا العام أولًا + +لا تبنِ نموذج وسائط خاصًا بـ Slack فقط. + +بدلًا من ذلك: + +- نموذج نقل QA عام واحد +- عدة عارِضات فوقه + - دردشة QA Lab الحالية + - ويب Fake Slack مستقبلي + - أي عروض نقل وهمية أخرى + +يمنع هذا ازدواجية المنطق ويسمح لسيناريوهات الوسائط بأن تظل غير مرتبطة بوسيلة نقل معينة. + +### أعمال UI المطلوبة + +حدّث UI الخاص بـ QA لعرض: + +- معاينة صورة مضمنة +- مشغل صوت مضمن +- مشغل فيديو مضمن +- شريحة مرفق ملف + +يمكن لـ UI الحالي بالفعل عرض السلاسل والتفاعلات، لذا يجب أن يضاف عرض المرفقات فوق نموذج بطاقة الرسالة نفسه. + +### أعمال السيناريو التي يتيحها نقل الوسائط + +بمجرد تدفق المرفقات عبر ناقل QA، يمكننا إضافة سيناريوهات دردشة وهمية أغنى: + +- رد بصورة مضمنة في Fake Slack +- فهم مرفق صوتي +- فهم مرفق فيديو +- ترتيب مختلط للمرفقات +- رد في سلسلة مع الاحتفاظ بالوسائط + +## التوصية + +يجب أن تكون كتلة التنفيذ التالية: + +1. إضافة أداة تحميل سيناريو markdown + مخطط zod +2. توليد الفهرس الحالي من markdown +3. ترحيل بعض السيناريوهات البسيطة أولًا +4. إضافة دعم مرفقات ناقل QA عام +5. عرض صورة مضمنة في UI الخاص بـ QA +6. ثم التوسع إلى الصوت والفيديو + +هذا هو أصغر مسار يثبت الهدفين معًا: + +- QA عام معرّف في markdown +- أسطح مراسلة وهمية أغنى + +## أسئلة مفتوحة + +- ما إذا كان يجب أن تسمح ملفات السيناريو بقوالب موجّهات markdown مضمنة مع استبدال المتغيرات +- ما إذا كان يجب أن يكون setup/cleanup أقسامًا مسماة أو مجرد قوائم إجراءات مرتبة +- ما إذا كان يجب أن تكون مراجع العناصر الناتجة مكتوبة النوع بقوة في المخطط أو معتمدة على السلاسل +- ما إذا كان يجب أن تعيش المعالِجات المخصصة في سجل واحد أو في سجلات بحسب السطح +- ما إذا كان يجب أن يظل ملف التوافق JSON المولّد محفوظًا في المستودع أثناء الترحيل diff --git a/docs/ar/reference/session-management-compaction.md b/docs/ar/reference/session-management-compaction.md index 374c9bba6..6365a6380 100644 --- a/docs/ar/reference/session-management-compaction.md +++ b/docs/ar/reference/session-management-compaction.md @@ -1,32 +1,32 @@ --- read_when: - - تحتاج إلى تصحيح معرّفات الجلسات أو JSONL الخاص بالنص التفريغي أو حقول sessions.json + - تحتاج إلى تصحيح أخطاء معرّفات الجلسات أو JSONL الخاص بالنصوص أو حقول sessions.json - أنت تغيّر سلوك الضغط التلقائي أو تضيف أعمال ترتيب "ما قبل الضغط" - - تريد تنفيذ عمليات تفريغ الذاكرة أو الأدوار النظامية الصامتة -summary: 'شرح متعمق: مخزن الجلسات + النصوص التفريغية، ودورة الحياة، والضغط (التلقائي) داخليًا' -title: شرح متعمق لإدارة الجلسات + - تريد تنفيذ عمليات تفريغ الذاكرة أو الدورات النظامية الصامتة +summary: 'شرح تفصيلي: مخزن الجلسات + النصوص، ودورة الحياة، وبواطن الضغط (التلقائي) الداخلي' +title: شرح تفصيلي لإدارة الجلسات x-i18n: - generated_at: "2026-04-07T07:22:22Z" + generated_at: "2026-04-08T02:19:36Z" model: gpt-5.4 provider: openai - source_hash: e379d624dd7808d3af25ed011079268ce6a9da64bb3f301598884ad4c46ab091 + source_hash: cb1a4048646486693db8943a9e9c6c5bcb205f0ed532b34842de3d0346077454 source_path: reference/session-management-compaction.md workflow: 15 --- -# إدارة الجلسات والضغط (شرح متعمق) +# إدارة الجلسات والضغط (شرح تفصيلي) -تشرح هذه الوثيقة كيف يدير OpenClaw الجلسات من البداية إلى النهاية: +يوضح هذا المستند كيف يدير OpenClaw الجلسات من البداية إلى النهاية: - **توجيه الجلسات** (كيف تُربط الرسائل الواردة بـ `sessionKey`) - **مخزن الجلسات** (`sessions.json`) وما الذي يتتبعه -- **الاحتفاظ بالنص التفريغي** (`*.jsonl`) وبنيته -- **نظافة النص التفريغي** (إصلاحات خاصة بالمزوّد قبل التشغيل) +- **استمرارية النص** (`*.jsonl`) وبنيته +- **نظافة النص** (إصلاحات خاصة بالموفر قبل التشغيل) - **حدود السياق** (نافذة السياق مقابل الرموز المتتبعة) - **الضغط** (الضغط اليدوي + الضغط التلقائي) وأين يمكن ربط أعمال ما قبل الضغط -- **الترتيب الصامت** (مثلًا، عمليات كتابة الذاكرة التي يجب ألا تنتج مخرجات مرئية للمستخدم) +- **الترتيب الصامت** (مثل عمليات كتابة الذاكرة التي لا ينبغي أن تنتج مخرجات مرئية للمستخدم) -إذا كنت تريد أولًا نظرة عامة على مستوى أعلى، فابدأ من: +إذا كنت تريد أولًا نظرة عامة أعلى مستوى، فابدأ من: - [/concepts/session](/ar/concepts/session) - [/concepts/compaction](/ar/concepts/compaction) @@ -37,38 +37,38 @@ x-i18n: --- -## مصدر الحقيقة: Gateway +## مصدر الحقيقة: البوابة -صُمم OpenClaw حول **عملية Gateway واحدة** تملك حالة الجلسة. +تم تصميم OpenClaw حول **عملية Gateway واحدة** تمتلك حالة الجلسة. -- يجب على واجهات المستخدم (تطبيق macOS وControl UI على الويب وTUI) الاستعلام من Gateway عن قوائم الجلسات وأعداد الرموز. -- في الوضع البعيد، تكون ملفات الجلسات على المضيف البعيد؛ لذا فإن "فحص ملفات Mac المحلية لديك" لن يعكس ما يستخدمه Gateway. +- يجب على واجهات المستخدم (تطبيق macOS، وواجهة الويب Control UI، وTUI) الاستعلام من البوابة عن قوائم الجلسات وعدد الرموز. +- في الوضع البعيد، تكون ملفات الجلسة على المضيف البعيد؛ لذا فإن "فحص ملفات Mac المحلية" لن يعكس ما تستخدمه البوابة. --- -## طبقتا الاحتفاظ +## طبقتا الاستمرارية -يحتفظ OpenClaw بالجلسات على طبقتين: +يحفظ OpenClaw الجلسات في طبقتين: 1. **مخزن الجلسات (`sessions.json`)** - خريطة مفتاح/قيمة: `sessionKey -> SessionEntry` - صغيرة، قابلة للتغيير، وآمنة للتحرير (أو حذف الإدخالات) - - تتتبع بيانات الجلسة الوصفية (معرّف الجلسة الحالي، وآخر نشاط، والمبدلات، وعدادات الرموز، وما إلى ذلك) + - تتتبع بيانات تعريف الجلسة (معرّف الجلسة الحالي، وآخر نشاط، والمفاتيح البديلة، وعدادات الرموز، وما إلى ذلك) -2. **النص التفريغي (`.jsonl`)** - - نص تفريغي بإلحاق فقط مع بنية شجرية (للإدخالات `id` و`parentId`) - - يخزّن المحادثة الفعلية + استدعاءات الأدوات + ملخصات الضغط - - يُستخدم لإعادة بناء سياق النموذج للأدوار المستقبلية +2. **النص (`.jsonl`)** + - نص إضافي فقط ببنية شجرية (تحتوي الإدخالات على `id` + `parentId`) + - يخزن المحادثة الفعلية + استدعاءات الأدوات + ملخصات الضغط + - يُستخدم لإعادة بناء سياق النموذج للدورات المستقبلية --- ## المواقع على القرص -لكل وكيل، على مضيف Gateway: +لكل وكيل، على مضيف البوابة: - المخزن: `~/.openclaw/agents//sessions/sessions.json` -- النصوص التفريغية: `~/.openclaw/agents//sessions/.jsonl` - - جلسات مواضيع Telegram: `.../-topic-.jsonl` +- النصوص: `~/.openclaw/agents//sessions/.jsonl` + - جلسات موضوعات Telegram: ‏`.../-topic-.jsonl` يحل OpenClaw هذه المسارات عبر `src/config/sessions.ts`. @@ -76,23 +76,23 @@ x-i18n: ## صيانة المخزن وعناصر التحكم في القرص -يحتوي الاحتفاظ بالجلسات على عناصر تحكم صيانة تلقائية (`session.maintenance`) لـ `sessions.json` وعناصر النص التفريغي: +تحتوي استمرارية الجلسة على عناصر تحكم صيانة تلقائية (`session.maintenance`) لـ `sessions.json` وعناصر النص: -- `mode`: `warn` (الافتراضي) أو `enforce` +- `mode`: ‏`warn` (افتراضي) أو `enforce` - `pruneAfter`: حد عمر الإدخالات القديمة (الافتراضي `30d`) -- `maxEntries`: حد أقصى للإدخالات في `sessions.json` (الافتراضي `500`) -- `rotateBytes`: تدوير `sessions.json` عندما يصبح كبيرًا جدًا (الافتراضي `10mb`) -- `resetArchiveRetention`: مدة الاحتفاظ بأرشيفات النص التفريغي `*.reset.` (الافتراضي: نفس `pruneAfter`؛ و`false` يعطّل التنظيف) +- `maxEntries`: الحد الأقصى للإدخالات في `sessions.json` (الافتراضي `500`) +- `rotateBytes`: تدوير `sessions.json` عند زيادة حجمه (الافتراضي `10mb`) +- `resetArchiveRetention`: مدة الاحتفاظ بأرشيفات النص `*.reset.` (الافتراضي: نفس `pruneAfter`؛ وتعطّل `false` التنظيف) - `maxDiskBytes`: ميزانية اختيارية لدليل الجلسات -- `highWaterBytes`: الهدف الاختياري بعد التنظيف (الافتراضي `80%` من `maxDiskBytes`) +- `highWaterBytes`: هدف اختياري بعد التنظيف (الافتراضي `80%` من `maxDiskBytes`) -ترتيب الفرض لتنظيف ميزانية القرص (`mode: "enforce"`): +ترتيب التنفيذ لتنظيف ميزانية القرص (`mode: "enforce"`): -1. إزالة أقدم عناصر النص التفريغي المؤرشفة أو اليتيمة أولًا. -2. إذا بقي الاستخدام أعلى من الهدف، تُزال أقدم إدخالات الجلسة وملفات نصوصها التفريغية. +1. إزالة أقدم عناصر النص المؤرشفة أو اليتيمة أولًا. +2. إذا ظل الاستخدام فوق الهدف، يتم إخراج أقدم إدخالات الجلسات وملفات النص الخاصة بها. 3. الاستمرار حتى يصبح الاستخدام عند `highWaterBytes` أو أقل. -في `mode: "warn"`، يبلّغ OpenClaw عن عمليات الإزالة المحتملة لكنه لا يغيّر المخزن/الملفات. +في `mode: "warn"`، يبلغ OpenClaw عن عمليات الإخراج المحتملة لكنه لا يغير المخزن/الملفات. شغّل الصيانة عند الطلب: @@ -103,43 +103,43 @@ openclaw sessions cleanup --enforce --- -## جلسات Cron وسجلات التشغيل +## جلسات cron وسجلات التشغيل -تنشئ تشغيلات cron المعزولة أيضًا إدخالات جلسات/نصوصًا تفريغية، ولها عناصر تحكم احتفاظ مخصصة: +تنشئ عمليات cron المعزولة أيضًا إدخالات/نصوص جلسات، ولها عناصر تحكم احتفاظ مخصصة: - `cron.sessionRetention` (الافتراضي `24h`) يزيل جلسات تشغيل cron المعزولة القديمة من مخزن الجلسات (`false` يعطّل ذلك). -- `cron.runLog.maxBytes` + `cron.runLog.keepLines` يقلّمان ملفات `~/.openclaw/cron/runs/.jsonl` (الافتراضيات: `2_000_000` بايت و`2000` سطر). +- `cron.runLog.maxBytes` + `cron.runLog.keepLines` يقتطعان ملفات `~/.openclaw/cron/runs/.jsonl` (الافتراضيان: `2_000_000` بايت و`2000` سطر). --- -## مفاتيح الجلسات (`sessionKey`) +## مفاتيح الجلسة (`sessionKey`) يحدد `sessionKey` _أي حاوية محادثة_ أنت فيها (التوجيه + العزل). -أنماط شائعة: +الأنماط الشائعة: - الدردشة الرئيسية/المباشرة (لكل وكيل): `agent::` (الافتراضي `main`) -- مجموعة: `agent:::group:` -- غرفة/قناة (Discord/Slack): `agent:::channel:` أو `...:room:` -- Cron: `cron:` -- Webhook: `hook:` (إلا إذا تم تجاوزه) +- المجموعة: `agent:::group:` +- الغرفة/القناة (Discord/Slack): ‏`agent:::channel:` أو `...:room:` +- Cron: ‏`cron:` +- Webhook: ‏`hook:` (ما لم يتم تجاوزه) -القواعد القانونية موثقة في [/concepts/session](/ar/concepts/session). +القواعد القياسية موثقة في [/concepts/session](/ar/concepts/session). --- -## معرّفات الجلسات (`sessionId`) +## معرّفات الجلسة (`sessionId`) -يشير كل `sessionKey` إلى `sessionId` حالي (ملف النص التفريغي الذي تتابع فيه المحادثة). +يشير كل `sessionKey` إلى `sessionId` حالي (ملف النص الذي يواصل المحادثة). -قواعد عملية: +قواعد عامة: -- **إعادة التعيين** (`/new` و`/reset`) تنشئ `sessionId` جديدًا لذلك `sessionKey`. -- **إعادة التعيين اليومية** (افتراضيًا الساعة 4:00 صباحًا بالتوقيت المحلي على مضيف gateway) تنشئ `sessionId` جديدًا عند الرسالة التالية بعد حد إعادة التعيين. -- **انتهاء الخمول** (`session.reset.idleMinutes` أو القديم `session.idleMinutes`) ينشئ `sessionId` جديدًا عندما تصل رسالة بعد نافذة الخمول. عند ضبط اليومي + الخمول معًا، يفوز أول ما ينتهي. -- **حارس تشعب الأصل للخيط** (`session.parentForkMaxTokens`، والافتراضي `100000`) يتخطى تشعيب النص التفريغي للأصل عندما تكون جلسة الأصل كبيرة جدًا بالفعل؛ ويبدأ الخيط الجديد من الصفر. اضبطه على `0` للتعطيل. +- **إعادة الضبط** (`/new`، ‏`/reset`) تنشئ `sessionId` جديدًا لذلك `sessionKey`. +- **إعادة الضبط اليومية** (الافتراضي 4:00 صباحًا بالتوقيت المحلي على مضيف البوابة) تنشئ `sessionId` جديدًا عند الرسالة التالية بعد حد إعادة الضبط. +- **انتهاء المهلة بسبب الخمول** (`session.reset.idleMinutes` أو القديم `session.idleMinutes`) ينشئ `sessionId` جديدًا عندما تصل رسالة بعد نافذة الخمول. وعند ضبط اليومي + الخمول معًا، يفوز الذي ينتهي أولًا. +- **حارس تشعب الأصل في السلسلة** (`session.parentForkMaxTokens`، الافتراضي `100000`) يتجاوز تشعيب نص الأصل عندما تكون الجلسة الأصلية كبيرة جدًا بالفعل؛ فتبدأ السلسلة الجديدة من الصفر. اضبط `0` للتعطيل. -تفصيل تنفيذي: يحدث القرار في `initSessionState()` في `src/auto-reply/reply/session.ts`. +تفصيل تنفيذي: يتم اتخاذ القرار في `initSessionState()` في `src/auto-reply/reply/session.ts`. --- @@ -147,46 +147,46 @@ openclaw sessions cleanup --enforce نوع قيمة المخزن هو `SessionEntry` في `src/config/sessions.ts`. -حقول أساسية (ليست شاملة): +الحقول الأساسية (غير شاملة): -- `sessionId`: معرّف النص التفريغي الحالي (يُشتق اسم الملف منه ما لم يُضبط `sessionFile`) +- `sessionId`: معرّف النص الحالي (يُشتق اسم الملف من هذا ما لم يتم تعيين `sessionFile`) - `updatedAt`: طابع زمني لآخر نشاط -- `sessionFile`: تجاوز اختياري صريح لمسار النص التفريغي -- `chatType`: `direct | group | room` (يساعد واجهات المستخدم وسياسة الإرسال) -- `provider` و`subject` و`room` و`space` و`displayName`: بيانات وصفية لتسمية المجموعة/القناة -- المبدلات: +- `sessionFile`: تجاوز مسار نص صريح اختياري +- `chatType`: ‏`direct | group | room` (يساعد واجهات المستخدم وسياسة الإرسال) +- `provider` و`subject` و`room` و`space` و`displayName`: بيانات تعريف لتسمية المجموعات/القنوات +- المفاتيح البديلة: - `thinkingLevel` و`verboseLevel` و`reasoningLevel` و`elevatedLevel` - `sendPolicy` (تجاوز لكل جلسة) - اختيار النموذج: - `providerOverride` و`modelOverride` و`authProfileOverride` -- عدادات الرموز (أفضل جهد / تعتمد على المزوّد): +- عدادات الرموز (أفضل جهد / حسب الموفّر): - `inputTokens` و`outputTokens` و`totalTokens` و`contextTokens` - `compactionCount`: عدد مرات اكتمال الضغط التلقائي لهذا `sessionKey` -- `memoryFlushAt`: طابع زمني لآخر تفريغ ذاكرة قبل الضغط +- `memoryFlushAt`: الطابع الزمني لآخر تفريغ ذاكرة قبل الضغط - `memoryFlushCompactionCount`: عدد مرات الضغط عند آخر تشغيل للتفريغ -المخزن آمن للتحرير، لكن Gateway هو المرجع: فقد يعيد كتابة الإدخالات أو إعادة ترطيبها أثناء تشغيل الجلسات. +المخزن آمن للتحرير، لكن البوابة هي الجهة المخولة: قد تعيد كتابة الإدخالات أو إعادة ترطيبها أثناء تشغيل الجلسات. --- -## بنية النص التفريغي (`*.jsonl`) +## بنية النص (`*.jsonl`) -تُدار النصوص التفريغية بواسطة `SessionManager` من `@mariozechner/pi-coding-agent`. +تُدار النصوص بواسطة `SessionManager` الخاص بـ `@mariozechner/pi-coding-agent`. الملف بصيغة JSONL: -- السطر الأول: ترويسة الجلسة (`type: "session"`، وتتضمن `id` و`cwd` و`timestamp` و`parentSession` الاختياري) +- السطر الأول: ترويسة الجلسة (`type: "session"`، وتتضمن `id` و`cwd` و`timestamp` و`parentSession` اختياريًا) - ثم: إدخالات الجلسة مع `id` + `parentId` (شجرة) أنواع إدخالات بارزة: - `message`: رسائل المستخدم/المساعد/`toolResult` -- `custom_message`: رسائل محقونة من الإضافة _تدخل_ إلى سياق النموذج (ويمكن إخفاؤها من واجهة المستخدم) -- `custom`: حالة إضافة لا تدخل إلى سياق النموذج +- `custom_message`: رسائل محقونة من الإضافات _تدخل_ في سياق النموذج (ويمكن إخفاؤها من واجهة المستخدم) +- `custom`: حالة إضافة _لا تدخل_ في سياق النموذج - `compaction`: ملخص ضغط محفوظ مع `firstKeptEntryId` و`tokensBefore` -- `branch_summary`: ملخص محفوظ عند التنقل داخل فرع شجري +- `branch_summary`: ملخص محفوظ عند التنقل في فرع شجري -يتعمد OpenClaw **عدم** "إصلاح" النصوص التفريغية؛ إذ يستخدم Gateway `SessionManager` لقراءتها وكتابتها. +يتعمد OpenClaw **عدم** "إصلاح" النصوص؛ إذ تستخدم البوابة `SessionManager` لقراءتها/كتابتها. --- @@ -194,13 +194,13 @@ openclaw sessions cleanup --enforce هناك مفهومان مختلفان مهمان: -1. **نافذة سياق النموذج**: الحد الصارم لكل نموذج (الرموز المرئية للنموذج) -2. **عدادات مخزن الجلسات**: إحصاءات متدحرجة مكتوبة في `sessions.json` (تُستخدم في `/status` ولوحات المعلومات) +1. **نافذة سياق النموذج**: حد صارم لكل نموذج (الرموز المرئية للنموذج) +2. **عدادات مخزن الجلسات**: إحصاءات متدحرجة تُكتب في `sessions.json` (تُستخدم في `/status` ولوحات المعلومات) إذا كنت تضبط الحدود: -- تأتي نافذة السياق من كتالوج النموذج (ويمكن تجاوزها عبر الإعدادات). -- إن `contextTokens` في المخزن قيمة تقديرية/إبلاغية في وقت التشغيل؛ فلا تعاملها كضمان صارم. +- تأتي نافذة السياق من فهرس النماذج (ويمكن تجاوزها عبر التكوين). +- إن `contextTokens` في المخزن هو قيمة تقديرية/تقارير وقت تشغيل؛ فلا تتعامل معه كضمان صارم. للمزيد، راجع [/token-use](/ar/reference/token-use). @@ -208,54 +208,55 @@ openclaw sessions cleanup --enforce ## الضغط: ما هو -يلخص الضغط المحادثة الأقدم في إدخال `compaction` محفوظ داخل النص التفريغي، مع إبقاء الرسائل الحديثة سليمة. +يلخّص الضغط المحادثة الأقدم في إدخال `compaction` محفوظ في النص ويحافظ على الرسائل الحديثة كما هي. -بعد الضغط، ترى الأدوار المستقبلية: +بعد الضغط، ترى الدورات المستقبلية: - ملخص الضغط - الرسائل بعد `firstKeptEntryId` -الضغط **دائم** (على عكس تقليم الجلسة). راجع [/concepts/session-pruning](/ar/concepts/session-pruning). +الضغط **دائم** (على عكس تقليم الجلسات). راجع [/concepts/session-pruning](/ar/concepts/session-pruning). -## حدود كتل الضغط واقتران الأدوات +## حدود أجزاء الضغط وإقران الأدوات -عندما يقسّم OpenClaw نصًا تفريغيًا طويلًا إلى كتل ضغط، فإنه يُبقي -استدعاءات أدوات المساعد مقترنةً بإدخالات `toolResult` المطابقة لها. +عندما يقسم OpenClaw نصًا طويلًا إلى أجزاء ضغط، فإنه يحافظ +على اقتران استدعاءات أدوات المساعد مع إدخالات `toolResult` المطابقة لها. -- إذا وقع تقسيم حصة الرموز بين استدعاء أداة ونتيجته، يحرّك OpenClaw - الحد إلى رسالة استدعاء أداة المساعد بدلًا من فصل الزوج. -- إذا كانت كتلة `toolResult` لاحقة ستدفع الكتلة فوق الهدف لولا ذلك، - فإن OpenClaw يحتفظ بتلك الكتلة المعلقة للأداة ويُبقي الذيل غير الملخّص - سليمًا. -- لا تُبقي كتل استدعاء الأدوات المجهضة/الخاطئة انقسامًا معلقًا مفتوحًا. +- إذا وقع تقسيم حصة الرموز بين استدعاء أداة ونتيجتها، فإن OpenClaw + يزيح الحد إلى رسالة استدعاء أداة المساعد بدلًا من فصل + الزوج. +- إذا كانت كتلة `toolResult` اللاحقة ستدفع الجزء فوق الهدف، + فإن OpenClaw يحافظ على كتلة الأداة المعلقة هذه ويبقي الذيل غير الملخَّص + كما هو. +- لا تُبقي كتل استدعاء الأدوات الملغاة/الخاطئة انقسامًا معلقًا مفتوحًا. --- ## متى يحدث الضغط التلقائي (وقت تشغيل Pi) -في وكيل Pi المضمّن، يُفعّل الضغط التلقائي في حالتين: +في وكيل Pi المضمن، يتم تشغيل الضغط التلقائي في حالتين: -1. **استرداد الفيض**: يعيد النموذج خطأ فيض سياق - (`request_too_large` و`context length exceeded` و`input exceeds the maximum -number of tokens` و`input token count exceeds the maximum number of input -tokens` و`input is too long for the model` و`ollama error: context length -exceeded` وأشكالًا مشابهة خاصة بالمزوّد) ← ضغط ← إعادة محاولة. -2. **صيانة العتبة**: بعد دور ناجح، عندما: +1. **استرداد تجاوز الحد**: يعيد النموذج خطأ تجاوز سياق + (`request_too_large` أو `context length exceeded` أو `input exceeds the maximum +number of tokens` أو `input token count exceeds the maximum number of input +tokens` أو `input is too long for the model` أو `ollama error: context length +exceeded`، وأشكالًا مشابهة بصياغة الموفّر) ← ضغط ← إعادة محاولة. +2. **صيانة الحد**: بعد دورة ناجحة، عندما: `contextTokens > contextWindow - reserveTokens` حيث: - `contextWindow` هي نافذة سياق النموذج -- `reserveTokens` هي مساحة احتياطية مخصصة للمطالبات + مخرج النموذج التالي +- `reserveTokens` هي مساحة احتياطية محفوظة للمطالبات + خرج النموذج التالي هذه دلالات وقت تشغيل Pi (يستهلك OpenClaw الأحداث، لكن Pi هو من يقرر متى يضغط). --- -## إعدادات الضغط (`reserveTokens` و`keepRecentTokens`) +## إعدادات الضغط (`reserveTokens`، ‏`keepRecentTokens`) -توجد إعدادات ضغط Pi في إعدادات Pi: +تعيش إعدادات الضغط في Pi ضمن إعدادات Pi: ```json5 { @@ -267,92 +268,106 @@ exceeded` وأشكالًا مشابهة خاصة بالمزوّد) ← ضغط } ``` -يفرض OpenClaw أيضًا حدًا أدنى آمنًا للتشغيلات المضمّنة: +يفرض OpenClaw أيضًا حدًا أدنى آمنًا للتشغيلات المضمنة: - إذا كان `compaction.reserveTokens < reserveTokensFloor`، يرفع OpenClaw القيمة. - الحد الأدنى الافتراضي هو `20000` رمز. -- اضبط `agents.defaults.compaction.reserveTokensFloor: 0` لتعطيل الحد الأدنى. -- إذا كانت أعلى أصلًا، يتركها OpenClaw كما هي. +- اضبط `agents.defaults.compaction.reserveTokensFloor: 0` لتعطيل هذا الحد. +- إذا كانت القيمة أعلى بالفعل، فإن OpenClaw يتركها كما هي. -السبب: ترك مساحة كافية لأعمال "ترتيب" متعددة الأدوار (مثل كتابات الذاكرة) قبل أن يصبح الضغط أمرًا لا مفر منه. +السبب: ترك مساحة كافية لـ "أعمال الترتيب" متعددة الدورات (مثل كتابات الذاكرة) قبل أن يصبح الضغط حتميًا. -التنفيذ: `ensurePiCompactionReserveTokens()` في `src/agents/pi-settings.ts` -(ويُستدعى من `src/agents/pi-embedded-runner.ts`). +التنفيذ: ‏`ensurePiCompactionReserveTokens()` في `src/agents/pi-settings.ts` +(يُستدعى من `src/agents/pi-embedded-runner.ts`). --- -## الواجهات الظاهرة للمستخدم +## موفّرو ضغط قابلون للتوصيل + +يمكن للإضافات تسجيل موفر ضغط عبر `registerCompactionProvider()` في API الخاص بالإضافة. عندما يتم تعيين `agents.defaults.compaction.provider` إلى معرّف موفر مسجل، يقوم امتداد الحماية بتفويض التلخيص إلى ذلك الموفر بدلًا من خط أنابيب `summarizeInStages` المضمن. + +- `provider`: معرّف إضافة موفر ضغط مسجلة. اتركه غير معيّن لاستخدام تلخيص LLM الافتراضي. +- يؤدي تعيين `provider` إلى فرض `mode: "safeguard"`. +- تتلقى الموفّرات تعليمات الضغط نفسها وسياسة الحفاظ على المعرّفات نفسها كما في المسار المضمن. +- ما تزال الحماية تحافظ على سياق لاحقة الدورات الحديثة والدورات المنقسمة بعد خرج الموفّر. +- إذا فشل الموفّر أو أعاد نتيجة فارغة، يعود OpenClaw تلقائيًا إلى التلخيص المضمن باستخدام LLM. +- تُعاد إشارات الإيقاف/انتهاء المهلة كما هي (ولا تُبتلع) احترامًا لإلغاء المستدعي. + +المصدر: `src/plugins/compaction-provider.ts`، ‏`src/agents/pi-hooks/compaction-safeguard.ts`. + +--- + +## الأسطح المرئية للمستخدم يمكنك ملاحظة الضغط وحالة الجلسة عبر: - `/status` (في أي جلسة دردشة) -- `openclaw status` (CLI) +- `openclaw status` ‏(CLI) - `openclaw sessions` / `sessions --json` -- الوضع المفصل: `🧹 Auto-compaction complete` + عدد مرات الضغط +- الوضع المطول: ‏`🧹 Auto-compaction complete` + عدد مرات الضغط --- ## الترتيب الصامت (`NO_REPLY`) -يدعم OpenClaw الأدوار "الصامتة" للمهام الخلفية التي يجب ألا يرى فيها المستخدم مخرجات وسيطة. +يدعم OpenClaw الدورات "الصامتة" للمهام الخلفية حيث يجب ألا يرى المستخدم خرجًا وسيطًا. -الاتفاقية: +الاصطلاح: -- يبدأ المساعد مخرجاته بالرمز الصامت الدقيق `NO_REPLY` / - `no_reply` للدلالة على "لا تُرسل ردًا إلى المستخدم". -- يقوم OpenClaw بإزالة/كبت هذا في طبقة التسليم. -- يكون كبت الرمز الصامت الدقيق غير حساس لحالة الأحرف، لذا يُحتسب كل من `NO_REPLY` و - `no_reply` عندما تكون الحمولة كاملةً مجرد الرمز الصامت. -- هذا مخصص فقط للأدوار الخلفية الحقيقية/من دون تسليم؛ وليس اختصارًا +- يبدأ المساعد خرجه بالرمز الصامت الدقيق `NO_REPLY` / + `no_reply` للإشارة إلى "لا تسلّم ردًا إلى المستخدم". +- يقوم OpenClaw بإزالة/كتم ذلك في طبقة التسليم. +- يكون كتم الرمز الصامت الدقيق غير حساس لحالة الأحرف، لذلك يُحتسب كل من `NO_REPLY` و + `no_reply` عندما تكون الحمولة بأكملها مجرد الرمز الصامت. +- هذا مخصص فقط للدورات الخلفية الحقيقية/التي لا يتم فيها التسليم؛ وليس اختصارًا لطلبات المستخدم العادية القابلة للتنفيذ. -اعتبارًا من `2026.1.10`، يكبت OpenClaw أيضًا **البث المسودّي/الكتابة** -عندما تبدأ كتلة جزئية بـ `NO_REPLY`، حتى لا تُسرّب العمليات الصامتة -مخرجات جزئية في منتصف الدور. +اعتبارًا من `2026.1.10`، يقوم OpenClaw أيضًا بكتم **البث المرحلي/مؤشر الكتابة** عندما يبدأ +جزء جزئي بـ `NO_REPLY`، حتى لا تتسرب العمليات الصامتة إلى خرج جزئي في منتصف الدورة. --- -## "تفريغ الذاكرة" قبل الضغط (منفّذ) +## "تفريغ الذاكرة" قبل الضغط (منفذ) -الهدف: قبل حدوث الضغط التلقائي، شغّل دورًا وكيليًا صامتًا يكتب حالة دائمة -إلى القرص (مثل `memory/YYYY-MM-DD.md` في مساحة عمل الوكيل) حتى لا يتمكن الضغط من +الهدف: قبل حدوث الضغط التلقائي، يتم تشغيل دورة وكيلية صامتة تكتب حالة +دائمة إلى القرص (مثل `memory/YYYY-MM-DD.md` في مساحة عمل الوكيل) بحيث لا يستطيع الضغط محو السياق الحرج. -يستخدم OpenClaw نهج **التفريغ قبل العتبة**: +يستخدم OpenClaw نهج **التفريغ قبل الحد**: 1. راقب استخدام سياق الجلسة. -2. عندما يتجاوز "عتبة ناعمة" (أقل من عتبة ضغط Pi)، شغّل توجيهًا صامتًا - من نوع "اكتب الذاكرة الآن" إلى الوكيل. +2. عندما يتجاوز "حدًا مرنًا" (أقل من حد ضغط Pi)، شغّل توجيهًا صامتًا + "اكتب الذاكرة الآن" إلى الوكيل. 3. استخدم الرمز الصامت الدقيق `NO_REPLY` / `no_reply` حتى لا يرى المستخدم - شيئًا. + أي شيء. -الإعداد (`agents.defaults.compaction.memoryFlush`): +التكوين (`agents.defaults.compaction.memoryFlush`): - `enabled` (الافتراضي: `true`) - `softThresholdTokens` (الافتراضي: `4000`) -- `prompt` (رسالة المستخدم لدور التفريغ) -- `systemPrompt` (مطالبة نظام إضافية تُلحق بدور التفريغ) +- `prompt` (رسالة المستخدم لدورة التفريغ) +- `systemPrompt` (مطالبة نظام إضافية تُلحق بدورة التفريغ) ملاحظات: -- تتضمن المطالبة/مطالبة النظام الافتراضيتان تلميح `NO_REPLY` لكبت +- تتضمن المطالبة الافتراضية/مطالبة النظام الافتراضية تلميح `NO_REPLY` لكتم التسليم. -- يعمل التفريغ مرة واحدة لكل دورة ضغط (ويُتتبّع في `sessions.json`). -- يعمل التفريغ فقط لجلسات Pi المضمّنة (تتخطاه واجهات CLI الخلفية). -- يُتخطى التفريغ عندما تكون مساحة عمل الجلسة للقراءة فقط (`workspaceAccess: "ro"` أو `"none"`). -- راجع [الذاكرة](/ar/concepts/memory) لمعرفة تخطيط ملفات مساحة العمل وأنماط الكتابة. +- يعمل التفريغ مرة واحدة لكل دورة ضغط (ويتم تتبعه في `sessions.json`). +- يعمل التفريغ فقط لجلسات Pi المضمنة (تتجاوزها الواجهات الخلفية لـ CLI). +- يتم تجاوز التفريغ عندما تكون مساحة عمل الجلسة للقراءة فقط (`workspaceAccess: "ro"` أو `"none"`). +- راجع [Memory](/ar/concepts/memory) لتخطيط ملفات مساحة العمل وأنماط الكتابة. -يكشف Pi أيضًا hook باسم `session_before_compact` في API الإضافات، لكن منطق -التفريغ في OpenClaw يعيش اليوم على جانب Gateway. +يكشف Pi أيضًا عن خطاف `session_before_compact` في API الامتداد، لكن منطق +التفريغ في OpenClaw يعيش حاليًا على جانب البوابة. --- ## قائمة التحقق لاستكشاف الأخطاء وإصلاحها -- مفتاح الجلسة خاطئ؟ ابدأ من [/concepts/session](/ar/concepts/session) وأكّد `sessionKey` في `/status`. -- عدم تطابق بين المخزن والنص التفريغي؟ أكّد مضيف Gateway ومسار المخزن من `openclaw status`. -- ضغط متكرر مزعج؟ تحقّق من: +- هل مفتاح الجلسة خاطئ؟ ابدأ من [/concepts/session](/ar/concepts/session) وأكد قيمة `sessionKey` في `/status`. +- هل يوجد عدم تطابق بين المخزن والنص؟ أكد مضيف البوابة ومسار المخزن من `openclaw status`. +- هل هناك تكرار مفرط للضغط؟ تحقق من: - نافذة سياق النموذج (صغيرة جدًا) - - إعدادات الضغط (قد يسبب `reserveTokens` المرتفع جدًا بالنسبة إلى نافذة النموذج ضغطًا أبكر) - - تضخم `toolResult`: فعّل/اضبط تقليم الجلسة -- تسرّب الأدوار الصامتة؟ أكّد أن الرد يبدأ بـ `NO_REPLY` (رمز دقيق غير حساس لحالة الأحرف) وأنك تستخدم إصدارًا يتضمن إصلاح كبت البث. + - إعدادات الضغط (`reserveTokens` المرتفعة جدًا بالنسبة لنافذة النموذج قد تسبب ضغطًا أبكر) + - تضخم نتائج الأدوات: فعّل/اضبط تقليم الجلسة +- هل تتسرب الدورات الصامتة؟ تأكد من أن الرد يبدأ بـ `NO_REPLY` (رمز دقيق غير حساس لحالة الأحرف) وأنك تستخدم إصدارًا يتضمن إصلاح كتم البث. diff --git a/docs/ar/reference/test.md b/docs/ar/reference/test.md index 6c525db1f..ee12fb8ec 100644 --- a/docs/ar/reference/test.md +++ b/docs/ar/reference/test.md @@ -1,77 +1,77 @@ --- read_when: - - تشغيل الاختبارات أو إصلاحها -summary: كيفية تشغيل الاختبارات محليًا (vitest) ومتى تستخدم وضعي force/coverage + - عند تشغيل الاختبارات أو إصلاحها +summary: كيفية تشغيل الاختبارات محليًا (vitest) ومتى تستخدم أوضاع force/coverage title: الاختبارات x-i18n: - generated_at: "2026-04-07T07:22:04Z" + generated_at: "2026-04-08T02:19:21Z" model: gpt-5.4 provider: openai - source_hash: a25236a707860307cc324f32752ad13a53e448bee9341d8df2e11655561e841c + source_hash: f7c19390f7577b3a29796c67514c96fe4c86c9fa0c7686cd4e377c6e31dcd085 source_path: reference/test.md workflow: 15 --- # الاختبارات -- عدة الاختبار الكاملة (المجموعات، المباشر، Docker): [الاختبار](/ar/help/testing) +- عدة الاختبار الكاملة (الأجنحة، وlive، وDocker): [الاختبار](/ar/help/testing) -- `pnpm test:force`: يقتل أي عملية بوابة متبقية تحتفظ بمنفذ التحكم الافتراضي، ثم يشغّل مجموعة Vitest الكاملة بمنفذ بوابة معزول حتى لا تتصادم اختبارات الخادم مع نسخة قيد التشغيل. استخدم هذا عندما يترك تشغيل سابق للبوابة المنفذ 18789 مشغولًا. -- `pnpm test:coverage`: يشغّل مجموعة اختبارات الوحدات مع تغطية V8 ‏(عبر `vitest.unit.config.ts`). الحدود العامة هي 70% للأسطر/الفروع/الدوال/العبارات. تستبعد التغطية نقاط الدخول الثقيلة تكامليًا (ربط CLI، وجسور gateway/telegram، وخادم webchat الثابت) للحفاظ على تركيز الهدف على المنطق القابل لاختبار الوحدات. -- `pnpm test:coverage:changed`: يشغّل تغطية اختبارات الوحدات فقط للملفات التي تغيّرت منذ `origin/main`. -- `pnpm test:changed`: يوسّع مسارات git المتغيرة إلى مسارات Vitest محددة النطاق عندما يلمس الفرق فقط ملفات المصدر/الاختبار القابلة للتوجيه. أما تغييرات الإعداد/التهيئة فتعود إلى تشغيل مشاريع الجذر الأصلية بحيث تعيد تعديلات التوصيل التشغيل على نطاق واسع عند الحاجة. -- `pnpm test`: يوجّه أهداف الملفات/الأدلة الصريحة عبر مسارات Vitest محددة النطاق. أمّا التشغيلات غير المستهدفة فتنفّذ الآن عشرة إعدادات شظايا متسلسلة (`vitest.full-core-unit-src.config.ts`, `vitest.full-core-unit-security.config.ts`, `vitest.full-core-unit-ui.config.ts`, `vitest.full-core-unit-support.config.ts`, `vitest.full-core-contracts.config.ts`, `vitest.full-core-bundled.config.ts`, `vitest.full-core-runtime.config.ts`, `vitest.full-agentic.config.ts`, `vitest.full-auto-reply.config.ts`, `vitest.full-extensions.config.ts`) بدلًا من عملية مشروع جذر عملاقة واحدة. -- توجَّه الآن ملفات اختبار `plugin-sdk` و `commands` المحددة عبر مسارات خفيفة مخصصة تُبقي فقط `test/setup.ts`، وتترك الحالات الثقيلة من جهة وقت التشغيل على مساراتها الحالية. -- كما تقوم ملفات المصدر المساعدة المحددة في `plugin-sdk` و `commands` أيضًا بربط `pnpm test:changed` باختبارات شقيقة صريحة في تلك المسارات الخفيفة، بحيث تتجنب التعديلات الصغيرة على المساعدات إعادة تشغيل المجموعات الثقيلة المدعومة بوقت التشغيل. -- تنقسم `auto-reply` الآن أيضًا إلى ثلاثة إعدادات مخصصة (`core`, `top-level`, `reply`) حتى لا تهيمن عدة الردود على اختبارات الحالة/الرمز/المساعد الأخف على المستوى الأعلى. -- يستخدم إعداد Vitest الأساسي الآن افتراضيًا `pool: "threads"` و `isolate: false`، مع تمكين المشغّل المشترك غير المعزول عبر إعدادات المستودع. +- `pnpm test:force`: يقتل أي عملية gateway متبقية تحتجز منفذ التحكم الافتراضي، ثم يشغّل جناح Vitest الكامل بمنفذ gateway معزول حتى لا تتعارض اختبارات الخادم مع مثيل قيد التشغيل. استخدم هذا عندما يترك تشغيل gateway سابق المنفذ 18789 مشغولًا. +- `pnpm test:coverage`: يشغّل جناح unit مع تغطية V8 ‏(عبر `vitest.unit.config.ts`). الحدود العامة هي 70% للأسطر/الفروع/الدوال/التعليمات. تستثني التغطية نقاط الدخول الثقيلة على مستوى integration ‏(توصيلات CLI، وجسور gateway/telegram، وخادم webchat الثابت) للإبقاء على الهدف مركزًا على المنطق القابل للاختبار بوحدة. +- `pnpm test:coverage:changed`: يشغّل تغطية unit فقط للملفات المتغيرة منذ `origin/main`. +- `pnpm test:changed`: يوسّع مسارات git المتغيرة إلى مسارات Vitest محددة عندما يمس الفرق فقط ملفات المصدر/الاختبار القابلة للتوجيه. أما تغييرات config/setup فتعود إلى تشغيل root projects الأصلي بحيث تعيد تعديلات التوصيل التشغيل على نطاق واسع عند الحاجة. +- `pnpm test`: يوجّه أهداف الملفات/الأدلة الصريحة عبر مسارات Vitest محددة. أما التشغيلات غير المستهدفة فتنفذ الآن إحدى عشرة إعدادات shard متتابعة (`vitest.full-core-unit-src.config.ts` و`vitest.full-core-unit-security.config.ts` و`vitest.full-core-unit-ui.config.ts` و`vitest.full-core-unit-support.config.ts` و`vitest.full-core-support-boundary.config.ts` و`vitest.full-core-contracts.config.ts` و`vitest.full-core-bundled.config.ts` و`vitest.full-core-runtime.config.ts` و`vitest.full-agentic.config.ts` و`vitest.full-auto-reply.config.ts` و`vitest.full-extensions.config.ts`) بدلًا من عملية root-project ضخمة واحدة. +- تُوجَّه الآن ملفات الاختبار المحددة في `plugin-sdk` و`commands` عبر مسارات خفيفة مخصصة تُبقي فقط `test/setup.ts`، بينما تبقى الحالات الثقيلة على مستوى runtime في مساراتها الحالية. +- كما تربط ملفات المصدر المساعدة المحددة في `plugin-sdk` و`commands` بين `pnpm test:changed` واختبارات شقيقة صريحة في تلك المسارات الخفيفة، بحيث تتجنب تعديلات المساعدات الصغيرة إعادة تشغيل الأجنحة الثقيلة المدعومة بـ runtime. +- ينقسم `auto-reply` الآن أيضًا إلى ثلاثة إعدادات مخصصة (`core` و`top-level` و`reply`) حتى لا تهيمن حاضنة reply على اختبارات الحالة/الرمز/المساعدات الأخف في المستوى الأعلى. +- أصبح إعداد Vitest الأساسي يستخدم افتراضيًا `pool: "threads"` و`isolate: false`، مع تفعيل المشغّل المشترك غير المعزول عبر إعدادات المستودع. - `pnpm test:channels` يشغّل `vitest.channels.config.ts`. - `pnpm test:extensions` يشغّل `vitest.extensions.config.ts`. -- `pnpm test:extensions`: يشغّل مجموعات الإضافات/Plugins. -- `pnpm test:perf:imports`: يفعّل تقارير مدة الاستيراد + تفصيلات الاستيراد في Vitest، مع الاستمرار في استخدام توجيه المسارات المحددة النطاق لأهداف الملفات/الأدلة الصريحة. -- `pnpm test:perf:imports:changed`: يطبّق profiling الاستيراد نفسه، ولكن فقط للملفات التي تغيّرت منذ `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` يقيس أداء مسار الوضع المتغير الموجّه مقابل تشغيل مشروع الجذر الأصلي لنفس فرق git الملتزم. -- `pnpm test:perf:changed:bench -- --worktree` يقيس مجموعة تغييرات worktree الحالية من دون عمل commit أولًا. -- `pnpm test:perf:profile:main`: يكتب ملف تعريف CPU للخيط الرئيسي في Vitest ‏(`.artifacts/vitest-main-profile`). -- `pnpm test:perf:profile:runner`: يكتب ملفات تعريف CPU + heap لمشغّل الوحدات (`.artifacts/vitest-runner-profile`). -- تكامل Gateway: الاشتراك اختياري عبر `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` أو `pnpm test:gateway`. -- `pnpm test:e2e`: يشغّل اختبارات smoke الشاملة للبوابة (إقران WS/HTTP/node متعدد النسخ). يستخدم افتراضيًا `threads` + `isolate: false` مع عمّال متكيّفين في `vitest.e2e.config.ts`; اضبطه عبر `OPENCLAW_E2E_WORKERS=` وعيّن `OPENCLAW_E2E_VERBOSE=1` للحصول على سجلات مطوّلة. -- `pnpm test:live`: يشغّل الاختبارات المباشرة للمزوّدين (minimax/zai). يتطلب مفاتيح API و `LIVE=1` (أو `*_LIVE_TEST=1` الخاص بالمزوّد) لإزالة التخطي. -- `pnpm test:docker:openwebui`: يبدأ OpenClaw + Open WebUI داخل Docker، ويسجّل الدخول عبر Open WebUI، ويفحص `/api/models`، ثم يشغّل دردشة حقيقية عبر الوكيل من خلال `/api/chat/completions`. يتطلب مفتاح نموذج مباشر قابلًا للاستخدام (مثل OpenAI في `~/.profile`)، ويسحب صورة Open WebUI خارجية، ولا يُتوقع أن يكون مستقرًا في CI مثل مجموعات الوحدات/e2e العادية. -- `pnpm test:docker:mcp-channels`: يبدأ حاوية Gateway مهيأة مسبقًا وحاوية عميل ثانية تشغّل `openclaw mcp serve`، ثم يتحقق من اكتشاف المحادثات الموجّهة، وقراءات النصوص، وبيانات تعريف المرفقات، وسلوك قائمة انتظار الأحداث المباشرة، وتوجيه الإرسال الصادر، وإشعارات القناة + الأذونات على نمط Claude عبر جسر stdio الحقيقي. يقرأ تأكيد إشعارات Claude إطارات MCP الخام لـ stdio مباشرةً بحيث يعكس اختبار smoke ما يصدره الجسر فعلًا. +- `pnpm test:extensions`: يشغّل أجنحة extension/plugin. +- `pnpm test:perf:imports`: يفعّل تقارير مدة الاستيراد + تفصيل الاستيراد في Vitest، مع الاستمرار في استخدام توجيه المسارات المحددة لأهداف الملفات/الأدلة الصريحة. +- `pnpm test:perf:imports:changed`: profiling الاستيراد نفسه، ولكن فقط للملفات المتغيرة منذ `origin/main`. +- `pnpm test:perf:changed:bench -- --ref ` يقيس مسار الوضع المتغير الموجّه مقابل تشغيل root-project الأصلي للفرق نفسه في git بعد الالتزام. +- `pnpm test:perf:changed:bench -- --worktree` يقيس مجموعة تغييرات worktree الحالية من دون الالتزام أولًا. +- `pnpm test:perf:profile:main`: يكتب ملف CPU profile لخيط Vitest الرئيسي (`.artifacts/vitest-main-profile`). +- `pnpm test:perf:profile:runner`: يكتب ملفات CPU + heap profiles لمشغّل unit ‏(`.artifacts/vitest-runner-profile`). +- Gateway integration: تفعيل اختياري عبر `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` أو `pnpm test:gateway`. +- `pnpm test:e2e`: يشغّل اختبارات الفحص الأساسية end-to-end لـ gateway ‏(تعدد المثيلات، وWS/HTTP، واقتران العقد). يستخدم افتراضيًا `threads` + `isolate: false` مع عمال تكيفيين في `vitest.e2e.config.ts`؛ اضبطه عبر `OPENCLAW_E2E_WORKERS=` واضبط `OPENCLAW_E2E_VERBOSE=1` للحصول على سجلات تفصيلية. +- `pnpm test:live`: يشغّل اختبارات الموفّرين الحية (`minimax`/`zai`). يتطلب مفاتيح API و`LIVE=1` ‏(أو `*_LIVE_TEST=1` الخاص بكل موفّر) لإلغاء التخطي. +- `pnpm test:docker:openwebui`: يبدأ OpenClaw + Open WebUI داخل Docker، ويسجل الدخول عبر Open WebUI، ويفحص `/api/models`، ثم يشغّل دردشة حقيقية عبر proxy من خلال `/api/chat/completions`. ويتطلب مفتاح نموذج حي صالحًا (مثل OpenAI في `~/.profile`)، ويجلب صورة Open WebUI خارجية، ولا يُتوقع أن يكون مستقرًا في CI مثل أجنحة unit/e2e العادية. +- `pnpm test:docker:mcp-channels`: يبدأ حاوية Gateway مهيأة مسبقًا وحاوية عميل ثانية تشغّل `openclaw mcp serve`، ثم يتحقق من اكتشاف المحادثات الموجّهة، وقراءة transcript، وmetadata الخاصة بالمرفقات، وسلوك قائمة الأحداث الحية، وتوجيه الإرسال الصادر، وإشعارات القنوات + الأذونات بأسلوب Claude عبر جسر stdio الحقيقي. ويقرأ تحقق إشعارات Claude إطارات stdio MCP الخام مباشرة بحيث يعكس الفحص ما يصدره الجسر فعليًا. ## بوابة PR المحلية -لفحوصات الهبوط/البوابة المحلية لـ PR، شغّل: +لإجراء فحوصات بوابة/الهبوط الخاصة بـ PR محليًا، شغّل: - `pnpm check` - `pnpm build` - `pnpm test` - `pnpm check:docs` -إذا كان `pnpm test` غير مستقر على مضيف محمّل، فأعد تشغيله مرة واحدة قبل اعتباره تراجعًا، ثم اعزله باستخدام `pnpm test `. وبالنسبة إلى المضيفين المقيّدين بالذاكرة، استخدم: +إذا تعطل `pnpm test` بشكل متقطع على مضيف محمّل، فأعد تشغيله مرة واحدة قبل اعتباره تراجعًا، ثم اعزله باستخدام `pnpm test `. وبالنسبة للمضيفين ذوي الذاكرة المحدودة، استخدم: - `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test` - `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed` -## معيار زمن استجابة النموذج (مفاتيح محلية) +## قياس زمن استجابة النموذج (مفاتيح محلية) -البرنامج النصي: [`scripts/bench-model.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-model.ts) +السكربت: [`scripts/bench-model.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-model.ts) الاستخدام: - `source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10` -- متغيرات البيئة الاختيارية: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY` +- متغيرات بيئة اختيارية: `MINIMAX_API_KEY` و`MINIMAX_BASE_URL` و`MINIMAX_MODEL` و`ANTHROPIC_API_KEY` - المطالبة الافتراضية: “Reply with a single word: ok. No punctuation or extra text.” -آخر تشغيل (2025-12-31، ‏20 تشغيلًا): +آخر تشغيل (2025-12-31، 20 تشغيلًا): -- median لـ minimax: ‏1279ms ‏(الحد الأدنى 1114، الحد الأقصى 2431) -- median لـ opus: ‏2454ms ‏(الحد الأدنى 1224، الحد الأقصى 3170) +- median لـ minimax هو 1279ms ‏(الحد الأدنى 1114، والحد الأقصى 2431) +- median لـ opus هو 2454ms ‏(الحد الأدنى 1224، والحد الأقصى 3170) -## معيار بدء تشغيل CLI +## قياس بدء تشغيل CLI -البرنامج النصي: [`scripts/bench-cli-startup.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-cli-startup.ts) +السكربت: [`scripts/bench-cli-startup.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-cli-startup.ts) الاستخدام: @@ -90,41 +90,41 @@ x-i18n: - `pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu` - `pnpm tsx scripts/bench-cli-startup.ts --json` -الإعدادات المسبقة: +المجموعات المسبقة: -- `startup`: ‏`--version`، ‏`--help`، ‏`health`، ‏`health --json`، ‏`status --json`، ‏`status` -- `real`: ‏`health`، ‏`status`، ‏`status --json`، ‏`sessions`، ‏`sessions --json`، ‏`agents list --json`، ‏`gateway status`، ‏`gateway status --json`، ‏`gateway health --json`، ‏`config get gateway.port` -- `all`: كلا الإعدادين المسبقين +- `startup`: ‏`--version` و`--help` و`health` و`health --json` و`status --json` و`status` +- `real`: ‏`health` و`status` و`status --json` و`sessions` و`sessions --json` و`agents list --json` و`gateway status` و`gateway status --json` و`gateway health --json` و`config get gateway.port` +- `all`: كلتا المجموعتين المسبقتين -يتضمن الخرج `sampleCount`، وavg، وp50، وp95، والحدين الأدنى/الأقصى، وتوزيع exit-code/signal، وملخصات أعلى RSS لكل أمر. ويكتب `--cpu-prof-dir` / `--heap-prof-dir` الاختياري ملفات تعريف V8 لكل تشغيل بحيث يستخدم القياس الزمني والتقاط ملفات التعريف المشغّل نفسه. +يتضمن الإخراج `sampleCount`، وavg، وp50، وp95، وmin/max، وتوزيع exit-code/signal، وملخصات max RSS لكل أمر. وتكتب الخيارات `--cpu-prof-dir` / `--heap-prof-dir` ملفات V8 profile لكل تشغيل بحيث يستخدم الالتقاط الزمني وprofile الحاضنة نفسها. -اتفاقيات الخرج المحفوظ: +اصطلاحات الإخراج المحفوظ: -- يكتب `pnpm test:startup:bench:smoke` العنصر المستهدف لاختبار smoke في `.artifacts/cli-startup-bench-smoke.json` -- يكتب `pnpm test:startup:bench:save` عنصر المجموعة الكاملة في `.artifacts/cli-startup-bench-all.json` باستخدام `runs=5` و `warmup=1` -- يحدّث `pnpm test:startup:bench:update` ملف baseline المثبّت في `test/fixtures/cli-startup-bench.json` باستخدام `runs=5` و `warmup=1` +- يكتب `pnpm test:startup:bench:smoke` ملف smoke المستهدف في `.artifacts/cli-startup-bench-smoke.json` +- يكتب `pnpm test:startup:bench:save` ملف الجناح الكامل في `.artifacts/cli-startup-bench-all.json` باستخدام `runs=5` و`warmup=1` +- يحدّث `pnpm test:startup:bench:update` baseline fixture الملتزم في `test/fixtures/cli-startup-bench.json` باستخدام `runs=5` و`warmup=1` -الملف المثبّت: +الـ fixture الملتزم: - `test/fixtures/cli-startup-bench.json` -- حدّثه باستخدام `pnpm test:startup:bench:update` -- قارن النتائج الحالية بالملف باستخدام `pnpm test:startup:bench:check` +- حدّثه عبر `pnpm test:startup:bench:update` +- قارن النتائج الحالية مع الـ fixture عبر `pnpm test:startup:bench:check` -## E2E للتهيئة (Docker) +## Onboarding E2E ‏(Docker) -Docker اختياري؛ وهذا مطلوب فقط لاختبارات smoke الخاصة بالتهيئة داخل الحاويات. +Docker اختياري؛ وهذا مطلوب فقط لاختبارات onboarding الأساسية المعتمدة على الحاويات. -تدفق بدء تشغيل كامل من الصفر داخل حاوية Linux نظيفة: +تدفق البدء البارد الكامل داخل حاوية Linux نظيفة: ```bash scripts/e2e/onboard-docker.sh ``` -يقود هذا البرنامج النصي المعالج التفاعلي عبر pseudo-tty، ويتحقق من ملفات الإعداد/مساحة العمل/الجلسة، ثم يبدأ البوابة ويشغّل `openclaw health`. +يقود هذا السكربت المعالج التفاعلي عبر pseudo-tty، ويتحقق من ملفات config/workspace/session، ثم يبدأ gateway ويشغّل `openclaw health`. -## اختبار smoke لاستيراد QR ‏(Docker) +## فحص QR import الأساسي (Docker) -يضمن أن `qrcode-terminal` يُحمّل ضمن بيئات Node المدعومة في Docker ‏(Node 24 افتراضيًا، وNode 22 متوافق): +يضمن تحميل `qrcode-terminal` تحت بيئات Node المدعومة في Docker ‏(Node 24 افتراضي، وNode 22 متوافق): ```bash pnpm test:docker:qr diff --git a/docs/ar/tools/acp-agents.md b/docs/ar/tools/acp-agents.md index 78cf997e6..abaacecc7 100644 --- a/docs/ar/tools/acp-agents.md +++ b/docs/ar/tools/acp-agents.md @@ -1,161 +1,161 @@ --- read_when: - - تشغيل coding harnesses عبر ACP + - تشغيل حاضنات البرمجة عبر ACP - إعداد جلسات ACP مرتبطة بالمحادثة على قنوات المراسلة - ربط محادثة قناة رسائل بجلسة ACP مستمرة - - استكشاف أخطاء الواجهة الخلفية لـ ACP وتوصيل الإضافة وإصلاحها + - استكشاف مشكلات الواجهة الخلفية لـ ACP وتوصيلات plugin وإصلاحها - تشغيل أوامر `/acp` من الدردشة -summary: استخدم جلسات وقت تشغيل ACP لـ Codex وClaude Code وCursor وGemini CLI وOpenClaw ACP ووكلاء harness آخرين +summary: استخدم جلسات تشغيل ACP لـ Codex وClaude Code وCursor وGemini CLI وOpenClaw ACP ووكلاء الحاضنة الآخرين title: وكلاء ACP x-i18n: - generated_at: "2026-04-07T07:24:22Z" + generated_at: "2026-04-08T02:22:49Z" model: gpt-5.4 provider: openai - source_hash: fb651ab39b05e537398623ee06cb952a5a07730fc75d3f7e0de20dd3128e72c6 + source_hash: 71c7c0cdae5247aefef17a0029360950a1c2987ddcee21a1bb7d78c67da52950 source_path: tools/acp-agents.md workflow: 15 --- # وكلاء ACP -تتيح جلسات [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) لـ OpenClaw تشغيل coding harnesses خارجية (مثل Pi، وClaude Code، وCodex، وCursor، وCopilot، وOpenClaw ACP، وOpenCode، وGemini CLI، وغيرها من harnesses المدعومة عبر ACPX) من خلال إضافة واجهة خلفية لـ ACP. +تتيح جلسات [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) لـ OpenClaw تشغيل حاضنات برمجة خارجية (مثل Pi وClaude Code وCodex وCursor وCopilot وOpenClaw ACP وOpenCode وGemini CLI وغيرها من حاضنات ACPX المدعومة) عبر plugin واجهة خلفية لـ ACP. -إذا طلبت من OpenClaw بلغة طبيعية "شغّل هذا في Codex" أو "ابدأ Claude Code في سلسلة محادثة"، فيجب على OpenClaw توجيه هذا الطلب إلى وقت تشغيل ACP (وليس وقت تشغيل الوكيل الفرعي الأصلي). يتم تتبع كل عملية spawn لجلسة ACP باعتبارها [مهمة في الخلفية](/ar/automation/tasks). +إذا طلبت من OpenClaw بلغة عادية "شغّل هذا في Codex" أو "ابدأ Claude Code في سلسلة محادثة"، فيفترض أن يوجّه OpenClaw هذا الطلب إلى وقت تشغيل ACP (وليس إلى وقت تشغيل الوكيل الفرعي الأصلي). يتم تتبع كل عملية إنشاء جلسة ACP باعتبارها [مهمة في الخلفية](/ar/automation/tasks). -إذا كنت تريد أن يتصل Codex أو Claude Code كعميل MCP خارجي مباشرةً +إذا كنت تريد أن يتصل Codex أو Claude Code مباشرةً كعميل MCP خارجي بمحادثات قنوات OpenClaw الموجودة، فاستخدم [`openclaw mcp serve`](/cli/mcp) بدلًا من ACP. -## أي صفحة أريد؟ +## ما الصفحة التي أريدها؟ -هناك ثلاث واجهات متقاربة يسهل الخلط بينها: +هناك ثلاثة أسطح متقاربة يسهل الخلط بينها: | أنت تريد أن... | استخدم هذا | ملاحظات | | ---------------------------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------- | -| تشغيل Codex أو Claude Code أو Gemini CLI أو harness خارجي آخر _عبر_ OpenClaw | هذه الصفحة: وكلاء ACP | جلسات مرتبطة بالدردشة، و`/acp spawn`، و`sessions_spawn({ runtime: "acp" })`، والمهام الخلفية، وعناصر تحكم وقت التشغيل | -| عرض جلسة OpenClaw Gateway _كخادم_ ACP لمحرر أو عميل | [`openclaw acp`](/cli/acp) | وضع الجسر. يتحدث IDE/العميل عبر ACP إلى OpenClaw عبر stdio/WebSocket | -| إعادة استخدام AI CLI محلي كنموذج احتياطي نصي فقط | [CLI Backends](/ar/gateway/cli-backends) | ليس ACP. لا أدوات OpenClaw، ولا عناصر تحكم ACP، ولا وقت تشغيل harness | +| تشغيل Codex أو Claude Code أو Gemini CLI أو حاضنة خارجية أخرى _عبر_ OpenClaw | هذه الصفحة: وكلاء ACP | جلسات مرتبطة بالدردشة، و`/acp spawn`، و`sessions_spawn({ runtime: "acp" })`، والمهام في الخلفية، وعناصر تحكم وقت التشغيل | +| عرض جلسة OpenClaw Gateway _باعتبارها_ خادم ACP لمحرر أو عميل | [`openclaw acp`](/cli/acp) | وضع الجسر. يتحدث IDE/العميل مع OpenClaw عبر ACP باستخدام stdio/WebSocket | +| إعادة استخدام AI CLI محلي كنموذج احتياطي نصي فقط | [الواجهات الخلفية لـ CLI](/ar/gateway/cli-backends) | ليس ACP. لا توجد أدوات OpenClaw ولا عناصر تحكم ACP ولا وقت تشغيل للحاضنة | -## هل يعمل هذا مباشرة؟ +## هل يعمل هذا مباشرةً دون إعداد إضافي؟ -عادةً نعم. +عادةً، نعم. -- تأتي التثبيتات الجديدة الآن مع تفعيل إضافة وقت التشغيل المضمّنة `acpx` افتراضيًا. -- تفضّل الإضافة المضمّنة `acpx` الثنائية المثبتة والمثبت إصدارها محليًا ضمن الإضافة. -- عند بدء التشغيل، يفحص OpenClaw هذه الثنائية ويصلحها ذاتيًا عند الحاجة. -- ابدأ بـ `/acp doctor` إذا كنت تريد فحص جاهزية سريعًا. +- تأتي التثبيتات الجديدة الآن مع plugin وقت التشغيل المضمّن `acpx` مفعّلًا افتراضيًا. +- يفضّل plugin `acpx` المضمّن ثنائي `acpx` المثبّت محليًا داخل plugin. +- عند بدء التشغيل، يفحص OpenClaw هذا الثنائي ويصلحه ذاتيًا إذا لزم الأمر. +- ابدأ بـ `/acp doctor` إذا كنت تريد فحصًا سريعًا للجاهزية. -ما الذي قد يحدث مع أول استخدام: +ما الذي قد يحدث مع أول استخدام رغم ذلك: -- قد يتم جلب مهايئ harness الهدف عند الطلب عبر `npx` في أول مرة تستخدم فيها ذلك الـ harness. -- يجب أن تكون مصادقة المورّد موجودة أيضًا على المضيف لذلك الـ harness. -- إذا لم يكن لدى المضيف وصول إلى npm/الشبكة، فقد تفشل عمليات الجلب الأولى للمهايئات إلى أن يتم تسخين الذاكرات المؤقتة مسبقًا أو تثبيت المهايئ بطريقة أخرى. +- قد يتم جلب مهيئ الحاضنة المستهدفة عند الطلب باستخدام `npx` في أول مرة تستخدم فيها تلك الحاضنة. +- يجب أن يكون توثيق المورّد موجودًا على المضيف لتلك الحاضنة. +- إذا لم يكن لدى المضيف وصول إلى npm/الشبكة، فقد يفشل جلب المهيئات عند أول تشغيل إلى أن تُسخّن الذاكرات المؤقتة مسبقًا أو يُثبَّت المهيئ بطريقة أخرى. أمثلة: -- `/acp spawn codex`: يجب أن يكون OpenClaw جاهزًا لتمهيد `acpx`، لكن قد يظل مهايئ Codex ACP بحاجة إلى جلب أولي. -- `/acp spawn claude`: الأمر نفسه بالنسبة إلى مهايئ Claude ACP، بالإضافة إلى مصادقة Claude على ذلك المضيف. +- `/acp spawn codex`: ينبغي أن يكون OpenClaw جاهزًا لتهيئة `acpx`، لكن قد يظل مهيئ Codex ACP بحاجة إلى جلب أولي. +- `/acp spawn claude`: نفس الفكرة بالنسبة إلى مهيئ Claude ACP، إضافةً إلى توثيق Claude على ذلك المضيف. -## تدفق تشغيل سريع للمشغّل +## تدفق التشغيل السريع -استخدم هذا عندما تريد دليلًا عمليًا لأوامر `/acp`: +استخدم هذا عندما تريد دليلاً عمليًا لتشغيل `/acp`: 1. أنشئ جلسة: - `/acp spawn codex --bind here` - `/acp spawn codex --mode persistent --thread auto` 2. اعمل في المحادثة أو السلسلة المرتبطة (أو استهدف مفتاح تلك الجلسة صراحةً). -3. افحص حالة وقت التشغيل: +3. تحقّق من حالة وقت التشغيل: - `/acp status` 4. اضبط خيارات وقت التشغيل حسب الحاجة: - `/acp model ` - `/acp permissions ` - `/acp timeout ` -5. وجّه جلسة نشطة من دون استبدال السياق: +5. وجّه جلسة نشطة دون استبدال السياق: - `/acp steer tighten logging and continue` 6. أوقف العمل: - `/acp cancel` (إيقاف الدور الحالي)، أو - - `/acp close` (إغلاق الجلسة + إزالة الروابط) + - `/acp close` (إغلاق الجلسة + إزالة الارتباطات) -## بدء سريع للبشر +## البدء السريع للبشر -أمثلة على طلبات طبيعية: +أمثلة على الطلبات الطبيعية: - "اربط قناة Discord هذه بـ Codex." -- "ابدأ جلسة Codex مستمرة في سلسلة هنا وأبقها مركزة." +- "ابدأ جلسة Codex مستمرة في سلسلة محادثة هنا وأبقها مركّزة." - "شغّل هذا كجلسة Claude Code ACP لمرة واحدة ولخّص النتيجة." -- "اربط دردشة iMessage هذه بـ Codex واحتفظ بالمتابعات في مساحة العمل نفسها." -- "استخدم Gemini CLI لهذه المهمة في سلسلة، ثم احتفظ بالمتابعات في السلسلة نفسها." +- "اربط دردشة iMessage هذه بـ Codex وأبقِ المتابعات في مساحة العمل نفسها." +- "استخدم Gemini CLI لهذه المهمة في سلسلة محادثة، ثم أبقِ المتابعات في السلسلة نفسها." -ما الذي يجب أن يفعله OpenClaw: +ما الذي ينبغي أن يفعله OpenClaw: -1. اختيار `runtime: "acp"`. -2. حل هدف harness المطلوب (`agentId`، مثل `codex`). -3. إذا طُلب الربط بالمحادثة الحالية وكانت القناة النشطة تدعم ذلك، فاربط جلسة ACP بهذه المحادثة. -4. وإلا، إذا طُلب ربط سلسلة محادثة وكانت القناة الحالية تدعم ذلك، فاربط جلسة ACP بالسلسلة. -5. وجّه رسائل المتابعة المرتبطة إلى جلسة ACP نفسها حتى يتم إلغاء التركيز/الإغلاق/الانتهاء. +1. يختار `runtime: "acp"`. +2. يحلّ هدف الحاضنة المطلوب (`agentId`، مثل `codex`). +3. إذا طُلِب الربط بالمحادثة الحالية وكانت القناة النشطة تدعمه، يربط جلسة ACP بهذه المحادثة. +4. بخلاف ذلك، إذا طُلِب الربط بسلسلة محادثة وكانت القناة الحالية تدعمه، يربط جلسة ACP بهذه السلسلة. +5. يوجّه رسائل المتابعة المرتبطة إلى جلسة ACP نفسها إلى أن يتم إلغاء التركيز عنها أو إغلاقها أو انتهاء صلاحيتها. ## ACP مقابل الوكلاء الفرعيين -استخدم ACP عندما تريد وقت تشغيل harness خارجيًا. واستخدم الوكلاء الفرعيين عندما تريد تشغيلات مفوّضة أصلية لـ OpenClaw. +استخدم ACP عندما تريد وقت تشغيل لحاضنة خارجية. واستخدم الوكلاء الفرعيين عندما تريد تشغيلات مفوّضة أصلية في OpenClaw. -| المجال | جلسة ACP | تشغيل وكيل فرعي | -| -------------- | --------------------------------------- | --------------------------------- | -| وقت التشغيل | إضافة واجهة خلفية لـ ACP (مثل acpx) | وقت تشغيل الوكيل الفرعي الأصلي في OpenClaw | -| مفتاح الجلسة | `agent::acp:` | `agent::subagent:` | -| الأوامر الرئيسية | `/acp ...` | `/subagents ...` | -| أداة spawn | `sessions_spawn` مع `runtime:"acp"` | `sessions_spawn` (وقت التشغيل الافتراضي) | +| المجال | جلسة ACP | تشغيل وكيل فرعي | +| --------------- | ---------------------------------- | ------------------------------------ | +| وقت التشغيل | plugin واجهة خلفية لـ ACP (مثل acpx) | وقت تشغيل الوكيل الفرعي الأصلي في OpenClaw | +| مفتاح الجلسة | `agent::acp:` | `agent::subagent:` | +| الأوامر الرئيسية | `/acp ...` | `/subagents ...` | +| أداة الإنشاء | `sessions_spawn` مع `runtime:"acp"` | `sessions_spawn` (وقت التشغيل الافتراضي) | راجع أيضًا [الوكلاء الفرعيون](/ar/tools/subagents). ## كيف يشغّل ACP ‏Claude Code -بالنسبة إلى Claude Code عبر ACP، تكون الطبقات كالتالي: +عند تشغيل Claude Code عبر ACP، تكون البنية كالتالي: -1. مستوى التحكم في جلسة OpenClaw ACP -2. إضافة وقت التشغيل المضمّنة `acpx` -3. مهايئ Claude ACP -4. آلية وقت التشغيل/الجلسة على جهة Claude +1. مستوى التحكم في جلسات OpenClaw ACP +2. plugin وقت التشغيل المضمّن `acpx` +3. مهيئ Claude ACP +4. آليات وقت التشغيل/الجلسة الخاصة بـ Claude تمييز مهم: -- ACP Claude عبارة عن جلسة harness مع عناصر تحكم ACP، واستئناف الجلسة، وتتبع المهام في الخلفية، وإمكانية اختيارية للربط بالمحادثة/السلسلة. -- الواجهات الخلفية لـ CLI هي بيئات تشغيل احتياطية نصية فقط محلية ومنفصلة. راجع [CLI Backends](/ar/gateway/cli-backends). +- Claude عبر ACP هو جلسة حاضنة مع عناصر تحكم ACP، واستئناف الجلسة، وتتبع المهام في الخلفية، وإمكانية ربط المحادثة/سلسلة المحادثة اختياريًا. +- الواجهات الخلفية لـ CLI هي أوقات تشغيل احتياطية محلية منفصلة تعمل بالنص فقط. راجع [الواجهات الخلفية لـ CLI](/ar/gateway/cli-backends). بالنسبة إلى المشغّلين، القاعدة العملية هي: -- إذا كنت تريد `/acp spawn`، أو جلسات قابلة للربط، أو عناصر تحكم وقت التشغيل، أو عمل harness مستمرًا: استخدم ACP +- إذا كنت تريد `/acp spawn` أو جلسات قابلة للربط أو عناصر تحكم لوقت التشغيل أو عمل حاضنة مستمر: استخدم ACP - إذا كنت تريد احتياطيًا نصيًا محليًا بسيطًا عبر CLI الخام: استخدم الواجهات الخلفية لـ CLI ## الجلسات المرتبطة -### الربط بالمحادثة الحالية +### الارتباطات بالمحادثة الحالية -استخدم `/acp spawn --bind here` عندما تريد أن تصبح المحادثة الحالية مساحة عمل ACP دائمة من دون إنشاء سلسلة فرعية. +استخدم `/acp spawn --bind here` عندما تريد أن تصبح المحادثة الحالية مساحة عمل ACP دائمة دون إنشاء سلسلة محادثة فرعية. السلوك: -- يواصل OpenClaw امتلاك نقل القناة، والمصادقة، والأمان، والتسليم. -- تُثبَّت المحادثة الحالية على مفتاح جلسة ACP الذي تم إنشاؤه. +- يظل OpenClaw مسؤولًا عن نقل القناة، والتوثيق، والسلامة، والتسليم. +- تُثبَّت المحادثة الحالية على مفتاح جلسة ACP المنشأة. - تُوجَّه رسائل المتابعة في تلك المحادثة إلى جلسة ACP نفسها. - يعيد `/new` و`/reset` تعيين جلسة ACP المرتبطة نفسها في مكانها. -- يغلق `/acp close` الجلسة ويزيل ربط المحادثة الحالية. +- يغلق `/acp close` الجلسة ويزيل ارتباط المحادثة الحالية. -ماذا يعني هذا عمليًا: +ما الذي يعنيه هذا عمليًا: -- يحافظ `--bind here` على سطح الدردشة نفسه. في Discord، تبقى القناة الحالية هي القناة الحالية. -- يمكن أن ينشئ `--bind here` مع ذلك جلسة ACP جديدة إذا كنت تبدأ عملًا جديدًا. يقوم الربط بإلحاق تلك الجلسة بالمحادثة الحالية. -- لا ينشئ `--bind here` سلسلة Discord فرعية أو موضوع Telegram بحد ذاته. -- يمكن لوقت تشغيل ACP مع ذلك أن يملك دليل عمل خاصًا به (`cwd`) أو مساحة عمل على القرص يديرها backend. تكون مساحة عمل وقت التشغيل هذه منفصلة عن سطح الدردشة ولا تعني وجود سلسلة رسائل جديدة. -- إذا أجريت spawn إلى وكيل ACP مختلف ولم تمرر `--cwd`، فسيرث OpenClaw مساحة عمل **الوكيل الهدف** افتراضيًا، وليس مساحة عمل طالب الطلب. +- `--bind here` يبقي نفس سطح الدردشة. على Discord، تظل القناة الحالية هي القناة الحالية. +- يمكن أن ينشئ `--bind here` جلسة ACP جديدة إذا كنت تنشئ عملًا جديدًا. يربط هذا الخيار تلك الجلسة بالمحادثة الحالية. +- لا ينشئ `--bind here` سلسلة Discord فرعية أو موضوع Telegram من تلقاء نفسه. +- يمكن لوقت تشغيل ACP أن يملك مع ذلك دليل عمل (`cwd`) خاصًا به أو مساحة عمل يديرها في الواجهة الخلفية على القرص. مساحة عمل وقت التشغيل هذه منفصلة عن سطح الدردشة ولا تعني وجود سلسلة رسائل جديدة. +- إذا أنشأت جلسة لوكيل ACP مختلف ولم تمرر `--cwd`، فسيرث OpenClaw مساحة عمل **الوكيل المستهدف** افتراضيًا، وليس مساحة عمل الطالب. - إذا كان مسار مساحة العمل الموروثة هذا مفقودًا (`ENOENT`/`ENOTDIR`)، فسيعود OpenClaw إلى `cwd` الافتراضي للواجهة الخلفية بدلًا من إعادة استخدام الشجرة الخاطئة بصمت. -- إذا كانت مساحة العمل الموروثة موجودة لكن لا يمكن الوصول إليها (مثل `EACCES`)، فستُرجع عملية spawn خطأ الوصول الحقيقي بدلًا من إسقاط `cwd`. +- إذا كانت مساحة العمل الموروثة موجودة لكن تعذر الوصول إليها (مثل `EACCES`)، فستعيد عملية الإنشاء خطأ الوصول الحقيقي بدلًا من إسقاط `cwd`. النموذج الذهني: -- سطح الدردشة: المكان الذي يواصل فيه الأشخاص الحديث (`Discord channel`، `Telegram topic`، `iMessage chat`) +- سطح الدردشة: المكان الذي يواصل فيه الناس الحديث (`Discord channel`، `Telegram topic`، `iMessage chat`) - جلسة ACP: حالة وقت تشغيل Codex/Claude/Gemini الدائمة التي يوجّه إليها OpenClaw -- سلسلة/موضوع فرعي: سطح رسائل إضافي اختياري لا يُنشأ إلا بواسطة `--thread ...` -- مساحة عمل وقت التشغيل: موقع نظام الملفات الذي يعمل فيه الـ harness (`cwd`، نسخة المستودع المحلية، مساحة العمل التي تديرها الواجهة الخلفية) +- سلسلة/موضوع فرعي: سطح مراسلة إضافي اختياري يُنشأ فقط بواسطة `--thread ...` +- مساحة عمل وقت التشغيل: موقع نظام الملفات الذي تعمل فيه الحاضنة (`cwd`، أو مستودع تم سحبه، أو مساحة عمل للواجهة الخلفية) أمثلة: @@ -165,81 +165,81 @@ x-i18n: دعم الربط بالمحادثة الحالية: -- يمكن لقنوات الدردشة/الرسائل التي تعلن دعم الربط بالمحادثة الحالية استخدام `--bind here` عبر مسار الربط المشترك للمحادثات. -- يمكن للقنوات ذات دلالات السلاسل/الموضوعات المخصصة مع ذلك توفير جعل معياري خاص بالقناة خلف الواجهة المشتركة نفسها. +- يمكن لقنوات الدردشة/الرسائل التي تعلن دعم ربط المحادثة الحالية استخدام `--bind here` عبر مسار ربط المحادثة المشترك. +- يمكن للقنوات ذات دلالات السلاسل/الموضوعات المخصصة أن توفّر مع ذلك تسوية خاصة بالقناة خلف الواجهة المشتركة نفسها. - يعني `--bind here` دائمًا "اربط المحادثة الحالية في مكانها". -- تستخدم عمليات الربط العامة بالمحادثة الحالية مخزن الربط المشترك في OpenClaw وتبقى بعد عمليات إعادة تشغيل البوابة العادية. +- تستخدم الارتباطات العامة للمحادثة الحالية مخزن الربط المشترك في OpenClaw وتستمر عبر عمليات إعادة تشغيل البوابة العادية. ملاحظات: -- إن `--bind here` و `--thread ...` متنافيان في `/acp spawn`. -- في Discord، يربط `--bind here` القناة أو السلسلة الحالية في مكانها. لا تكون `spawnAcpSessions` مطلوبة إلا عندما يحتاج OpenClaw إلى إنشاء سلسلة فرعية من أجل `--thread auto|here`. -- إذا لم تكشف القناة النشطة روابط ACP للمحادثة الحالية، فسيُرجع OpenClaw رسالة واضحة بعدم الدعم. -- أسئلة `resume` و"جلسة جديدة" هي أسئلة خاصة بجلسة ACP، وليست أسئلة خاصة بالقناة. يمكنك إعادة استخدام حالة وقت التشغيل أو استبدالها من دون تغيير سطح الدردشة الحالي. +- `--bind here` و`--thread ...` متنافيان في `/acp spawn`. +- على Discord، يربط `--bind here` القناة الحالية أو السلسلة الحالية في مكانها. لا تكون `spawnAcpSessions` مطلوبة إلا عندما يحتاج OpenClaw إلى إنشاء سلسلة فرعية لـ `--thread auto|here`. +- إذا كانت القناة النشطة لا تعرض ارتباطات ACP للمحادثة الحالية، فسيعيد OpenClaw رسالة واضحة بعدم الدعم. +- أسئلة `resume` و"الجلسة الجديدة" هي أسئلة تخص جلسات ACP، وليست أسئلة تخص القنوات. يمكنك إعادة استخدام حالة وقت التشغيل أو استبدالها دون تغيير سطح الدردشة الحالي. -### الجلسات المرتبطة بالسلسلة +### الجلسات المرتبطة بسلسلة محادثة -عندما تكون روابط السلاسل مفعّلة لمهايئ قناة، يمكن ربط جلسات ACP بالسلاسل: +عندما تكون ارتباطات السلاسل مفعّلة لمهايئ القناة، يمكن ربط جلسات ACP بسلاسل المحادثة: -- يربط OpenClaw سلسلةً بجلسة ACP مستهدفة. +- يربط OpenClaw سلسلة محادثة بجلسة ACP مستهدفة. - تُوجَّه رسائل المتابعة في تلك السلسلة إلى جلسة ACP المرتبطة. -- يُسلَّم خرج ACP إلى السلسلة نفسها. -- تؤدي عملية unfocus/close/archive/انتهاء المهلة عند الخمول أو انتهاء max-age إلى إزالة الربط. +- يتم تسليم مخرجات ACP إلى سلسلة المحادثة نفسها. +- تؤدي إزالة التركيز أو الإغلاق أو الأرشفة أو انتهاء مهلة الخمول أو انتهاء الحد الأقصى للعمر إلى إزالة الارتباط. -يعتمد دعم ربط السلاسل على المهايئ. وإذا لم يكن مهايئ القناة النشطة يدعم روابط السلاسل، فسيُرجع OpenClaw رسالة واضحة بعدم الدعم/عدم التوفر. +يعتمد دعم ربط السلاسل على المهايئ. إذا لم يكن مهايئ القناة النشطة يدعم ارتباطات السلاسل، فسيعيد OpenClaw رسالة واضحة تفيد بعدم الدعم/التوفر. -أعلام الميزات المطلوبة لـ ACP المرتبط بالسلسلة: +علامات الميزات المطلوبة لـ ACP المرتبط بالسلسلة: - `acp.enabled=true` -- `acp.dispatch.enabled` مفعّل افتراضيًا (عيّنه إلى `false` لإيقاف توجيه ACP مؤقتًا) -- تمكين علم spawn الخاص بجلسات ACP في مهايئ القناة (بحسب المهايئ) +- يكون `acp.dispatch.enabled` مفعّلًا افتراضيًا (اضبطه على `false` لإيقاف توجيه ACP مؤقتًا) +- تفعيل علامة إنشاء سلاسل ACP في مهايئ القناة (خاصة بالمهايئ) - Discord: `channels.discord.threadBindings.spawnAcpSessions=true` - Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true` ### القنوات التي تدعم السلاسل -- أي مهايئ قناة يكشف قدرة ربط الجلسات/السلاسل. +- أي مهايئ قناة يكشف قدرة ربط الجلسة/السلسلة. - الدعم المضمّن الحالي: - سلاسل/قنوات Discord - - موضوعات Telegram (موضوعات المنتدى في المجموعات/المجموعات الفائقة وموضوعات الرسائل المباشرة) -- يمكن لقنوات الإضافات إضافة الدعم عبر واجهة الربط نفسها. + - مواضيع Telegram (مواضيع المنتدى في المجموعات/المجموعات الفائقة ومواضيع الرسائل الخاصة) +- يمكن لقنوات plugin إضافة الدعم عبر واجهة الربط نفسها. -## إعدادات خاصة بالقناة +## الإعدادات الخاصة بالقنوات -بالنسبة إلى مسارات العمل غير المؤقتة، قم بتهيئة روابط ACP المستمرة في إدخالات `bindings[]` ذات المستوى الأعلى. +للتدفقات غير المؤقتة، اضبط ارتباطات ACP المستمرة في إدخالات `bindings[]` ذات المستوى الأعلى. ### نموذج الربط -- يحدد `bindings[].type="acp"` ربط محادثة ACP مستمر. -- يحدد `bindings[].match` المحادثة المستهدفة: - - قناة أو سلسلة Discord: ‏`match.channel="discord"` + ‏`match.peer.id=""` - - موضوع منتدى Telegram: ‏`match.channel="telegram"` + ‏`match.peer.id=":topic:"` - - دردشة مباشرة/مجموعة BlueBubbles: ‏`match.channel="bluebubbles"` + ‏`match.peer.id=""` - فضّل `chat_id:*` أو `chat_identifier:*` للروابط الجماعية المستقرة. - - دردشة مباشرة/مجموعة iMessage: ‏`match.channel="imessage"` + ‏`match.peer.id=""` - فضّل `chat_id:*` للروابط الجماعية المستقرة. +- تشير `bindings[].type="acp"` إلى ربط محادثة ACP مستمر. +- تحدد `bindings[].match` المحادثة المستهدفة: + - قناة أو سلسلة Discord: `match.channel="discord"` + `match.peer.id=""` + - موضوع منتدى Telegram: `match.channel="telegram"` + `match.peer.id=":topic:"` + - دردشة BlueBubbles فردية/جماعية: `match.channel="bluebubbles"` + `match.peer.id=""` + فضّل `chat_id:*` أو `chat_identifier:*` لارتباطات المجموعات المستقرة. + - دردشة iMessage فردية/جماعية: `match.channel="imessage"` + `match.peer.id=""` + فضّل `chat_id:*` لارتباطات المجموعات المستقرة. - `bindings[].agentId` هو معرّف وكيل OpenClaw المالك. - توجد تجاوزات ACP الاختيارية تحت `bindings[].acp`: - - `mode` ‏(`persistent` أو `oneshot`) + - `mode` (`persistent` أو `oneshot`) - `label` - `cwd` - `backend` ### القيم الافتراضية لوقت التشغيل لكل وكيل -استخدم `agents.list[].runtime` لتعريف القيم الافتراضية لـ ACP مرة واحدة لكل وكيل: +استخدم `agents.list[].runtime` لتعريف قيم ACP الافتراضية مرة واحدة لكل وكيل: - `agents.list[].runtime.type="acp"` -- `agents.list[].runtime.acp.agent` ‏(معرّف harness، مثل `codex` أو `claude`) +- `agents.list[].runtime.acp.agent` (معرّف الحاضنة، مثل `codex` أو `claude`) - `agents.list[].runtime.acp.backend` - `agents.list[].runtime.acp.mode` - `agents.list[].runtime.acp.cwd` -ترتيب أسبقية التجاوز للجلسات المرتبطة بـ ACP: +ترتيب أولوية التجاوز لجلسات ACP المرتبطة: -1. ‏`bindings[].acp.*` -2. ‏`agents.list[].runtime.acp.*` -3. القيم الافتراضية العامة لـ ACP ‏(مثل `acp.backend`) +1. `bindings[].acp.*` +2. `agents.list[].runtime.acp.*` +3. القيم الافتراضية العامة لـ ACP (مثل `acp.backend`) مثال: @@ -323,14 +323,14 @@ x-i18n: السلوك: -- يضمن OpenClaw وجود جلسة ACP المهيأة قبل الاستخدام. -- تُوجَّه الرسائل في تلك القناة أو الموضوع إلى جلسة ACP المهيأة. +- يضمن OpenClaw وجود جلسة ACP المضبوطة قبل استخدامها. +- تُوجَّه الرسائل في تلك القناة أو الموضوع إلى جلسة ACP المضبوطة. - في المحادثات المرتبطة، يعيد `/new` و`/reset` تعيين مفتاح جلسة ACP نفسه في مكانه. -- تظل روابط وقت التشغيل المؤقتة (مثل تلك التي تنشئها تدفقات التركيز على السلسلة) مطبّقة حيثما كانت موجودة. -- بالنسبة إلى عمليات spawn عبر وكلاء ACP من دون `cwd` صريح، يرث OpenClaw مساحة عمل الوكيل الهدف من إعدادات الوكيل. -- تعود مسارات مساحات العمل الموروثة المفقودة إلى `cwd` الافتراضي للواجهة الخلفية؛ أما إخفاقات الوصول إلى المسارات الموجودة فتظهر كأخطاء spawn. +- تستمر ارتباطات وقت التشغيل المؤقتة (مثل تلك التي تنشئها تدفقات التركيز على السلسلة) في التطبيق عند وجودها. +- في عمليات إنشاء ACP بين وكلاء مختلفين من دون `cwd` صريح، يرث OpenClaw مساحة عمل الوكيل المستهدف من إعدادات الوكيل. +- تعود مسارات مساحة العمل الموروثة المفقودة إلى `cwd` الافتراضي للواجهة الخلفية؛ أما حالات فشل الوصول غير المفقودة فتظهر كأخطاء إنشاء. -## بدء جلسات ACP ‏(الواجهات) +## بدء جلسات ACP (الواجهات) ### من `sessions_spawn` @@ -348,29 +348,29 @@ x-i18n: ملاحظات: -- تكون القيمة الافتراضية لـ `runtime` هي `subagent`، لذا عيّن `runtime: "acp"` صراحةً لجلسات ACP. -- إذا حُذف `agentId`، يستخدم OpenClaw القيمة `acp.defaultAgent` إذا كانت مهيأة. -- يتطلب `mode: "session"` وجود `thread: true` للاحتفاظ بمحادثة مرتبطة مستمرة. +- القيمة الافتراضية لـ `runtime` هي `subagent`، لذا اضبط `runtime: "acp"` صراحةً لجلسات ACP. +- إذا تم حذف `agentId`، يستخدم OpenClaw القيمة `acp.defaultAgent` عند ضبطها. +- يتطلب `mode: "session"` وجود `thread: true` للإبقاء على محادثة مرتبطة مستمرة. تفاصيل الواجهة: -- `task` ‏(مطلوب): المطالبة الأولية المرسلة إلى جلسة ACP. -- `runtime` ‏(مطلوب لـ ACP): يجب أن يكون `"acp"`. -- `agentId` ‏(اختياري): معرّف harness الهدف لـ ACP. يعود إلى `acp.defaultAgent` إذا كان مضبوطًا. -- `thread` ‏(اختياري، الافتراضي `false`): طلب تدفق ربط السلسلة عند الدعم. -- `mode` ‏(اختياري): ‏`run` ‏(مرة واحدة) أو `session` ‏(مستمر). +- `task` (مطلوب): الموجّه الأولي المرسل إلى جلسة ACP. +- `runtime` (مطلوب لـ ACP): يجب أن يكون `"acp"`. +- `agentId` (اختياري): معرّف حاضنة ACP المستهدفة. يعود إلى `acp.defaultAgent` إذا تم ضبطه. +- `thread` (اختياري، الافتراضي `false`): طلب تدفق ربط السلسلة عند دعمه. +- `mode` (اختياري): `run` (مرة واحدة) أو `session` (مستمر). - القيمة الافتراضية هي `run` - - إذا كانت `thread: true` وحُذف `mode`، فقد يستخدم OpenClaw سلوكًا مستمرًا افتراضيًا بحسب مسار وقت التشغيل + - إذا كانت `thread: true` وتم حذف الوضع، فقد يستخدم OpenClaw سلوكًا مستمرًا افتراضيًا بحسب مسار وقت التشغيل - يتطلب `mode: "session"` وجود `thread: true` -- `cwd` ‏(اختياري): دليل العمل المطلوب لوقت التشغيل (ويتحقق منه backend/سياسة وقت التشغيل). إذا حُذف، ترث عملية spawn لـ ACP مساحة عمل الوكيل الهدف عند تهيئتها؛ وتعود المسارات الموروثة المفقودة إلى القيم الافتراضية للواجهة الخلفية، بينما تُرجع أخطاء الوصول الحقيقية. -- `label` ‏(اختياري): تسمية موجهة للمشغّل تُستخدم في نص الجلسة/اللافتة. -- `resumeSessionId` ‏(اختياري): استئناف جلسة ACP موجودة بدلًا من إنشاء أخرى جديدة. يعيد الوكيل تشغيل سجل محادثاته عبر `session/load`. يتطلب `runtime: "acp"`. -- `streamTo` ‏(اختياري): تقوم القيمة `"parent"` ببث ملخصات تقدّم التشغيل الأولي لـ ACP إلى جلسة الطالب كأحداث نظام. - - عند التوفر، قد تتضمن الاستجابات المقبولة `streamLogPath` الذي يشير إلى سجل JSONL ضمن نطاق الجلسة (`.acp-stream.jsonl`) يمكنك تتبعه لمعرفة سجل الترحيل الكامل. +- `cwd` (اختياري): دليل عمل وقت التشغيل المطلوب (ويتم التحقق منه وفق سياسة الواجهة الخلفية/وقت التشغيل). إذا تم حذفه، يرث إنشاء ACP مساحة عمل الوكيل المستهدف عند ضبطها؛ وتعود المسارات الموروثة المفقودة إلى القيم الافتراضية للواجهة الخلفية، بينما تُعاد أخطاء الوصول الحقيقية. +- `label` (اختياري): تسمية موجّهة للمشغّل تُستخدم في نص الجلسة/الشعار. +- `resumeSessionId` (اختياري): استئناف جلسة ACP موجودة بدلًا من إنشاء جلسة جديدة. يعيد الوكيل تشغيل سجل محادثته عبر `session/load`. يتطلب `runtime: "acp"`. +- `streamTo` (اختياري): تؤدي القيمة `"parent"` إلى بث ملخصات تقدم تشغيل ACP الأولي إلى جلسة الطالب كأحداث نظام. + - عند التوفر، تتضمن الاستجابات المقبولة `streamLogPath` الذي يشير إلى سجل JSONL خاص بالجسلة (`.acp-stream.jsonl`) يمكنك مراقبته للاطلاع على سجل الترحيل الكامل. ### استئناف جلسة موجودة -استخدم `resumeSessionId` لمتابعة جلسة ACP سابقة بدلًا من البدء من جديد. يعيد الوكيل تشغيل سجل محادثته عبر `session/load`، لذلك يلتقط العمل مع السياق الكامل لما سبق. +استخدم `resumeSessionId` لمتابعة جلسة ACP سابقة بدلًا من البدء من جديد. يعيد الوكيل تشغيل سجل محادثته عبر `session/load`، بحيث يواصل العمل مع كامل السياق السابق. ```json { @@ -383,41 +383,41 @@ x-i18n: حالات الاستخدام الشائعة: -- تسليم جلسة Codex من الكمبيوتر المحمول إلى الهاتف — اطلب من وكيلك متابعة العمل من حيث توقفت -- متابعة جلسة برمجة بدأتَها تفاعليًا في CLI، ولكن الآن بصورة غير تفاعلية عبر وكيلك -- متابعة عمل انقطع بسبب إعادة تشغيل البوابة أو انتهاء مهلة الخمول +- تسليم جلسة Codex من حاسوبك المحمول إلى هاتفك — اطلب من وكيلك متابعة العمل من حيث توقفت +- متابعة جلسة برمجة بدأت بها بشكل تفاعلي في CLI، ولكن الآن بدون واجهة مباشرة عبر وكيلك +- استكمال العمل الذي انقطع بسبب إعادة تشغيل البوابة أو انتهاء مهلة الخمول ملاحظات: - يتطلب `resumeSessionId` وجود `runtime: "acp"` — ويعيد خطأ إذا استُخدم مع وقت تشغيل الوكيل الفرعي. -- يستعيد `resumeSessionId` سجل المحادثة الأعلى مستوى لـ ACP؛ وما تزال `thread` و`mode` تطبقان بشكل طبيعي على جلسة OpenClaw الجديدة التي تنشئها، لذلك ما يزال `mode: "session"` يتطلب `thread: true`. -- يجب أن يدعم الوكيل الهدف `session/load` ‏(كل من Codex وClaude Code يدعمان ذلك). -- إذا لم يُعثر على معرّف الجلسة، تفشل عملية spawn برسالة خطأ واضحة — ولا يوجد تراجع صامت إلى جلسة جديدة. +- يعيد `resumeSessionId` سجل محادثة ACP الصاعد؛ ولا يزال `thread` و`mode` يُطبّقان بشكل طبيعي على جلسة OpenClaw الجديدة التي تنشئها، لذا يظل `mode: "session"` يتطلب `thread: true`. +- يجب أن يدعم الوكيل المستهدف `session/load` (ويدعمه كل من Codex وClaude Code). +- إذا لم يتم العثور على معرّف الجلسة، تفشل عملية الإنشاء مع خطأ واضح — دون عودة صامتة إلى جلسة جديدة. -### اختبار smoke للمشغّل +### اختبار دخاني للمشغّل -استخدم هذا بعد نشر البوابة عندما تريد فحصًا مباشرًا سريعًا يثبت أن spawn لـ ACP -يعمل فعليًا من طرف إلى طرف، وليس مجرد اجتياز اختبارات الوحدات. +استخدم هذا بعد نشر البوابة عندما تريد فحصًا حيًا سريعًا يثبت أن إنشاء ACP +يعمل فعلًا من طرف إلى طرف، وليس فقط أنه ينجح في اختبارات الوحدة. البوابة الموصى بها: -1. تحقّق من إصدار/commit البوابة المنشورة على المضيف الهدف. -2. أكّد أن المصدر المنشور يتضمن قبول نسب ACP في - `src/gateway/sessions-patch.ts` ‏(`subagent:* or acp:* sessions`). -3. افتح جلسة جسر ACPX مؤقتة إلى وكيل مباشر (مثل +1. تحقّق من إصدار/التزام البوابة المنشورة على المضيف المستهدف. +2. أكّد أن المصدر المنشور يتضمن قبول سلالة ACP في + `src/gateway/sessions-patch.ts` (`subagent:* or acp:* sessions`). +3. افتح جلسة جسر ACPX مؤقتة إلى وكيل حي (مثل `razor(main)` على `jpclawhq`). -4. اطلب من ذلك الوكيل استدعاء `sessions_spawn` بالقيم التالية: +4. اطلب من ذلك الوكيل استدعاء `sessions_spawn` باستخدام: - `runtime: "acp"` - `agentId: "codex"` - `mode: "run"` - المهمة: `Reply with exactly LIVE-ACP-SPAWN-OK` -5. تحقّق من أن الوكيل يبلّغ بما يلي: +5. تحقّق من أن الوكيل يبلغ عن: - `accepted=yes` - `childSessionKey` حقيقي - - لا يوجد خطأ تحقق + - عدم وجود خطأ تحقق 6. نظّف جلسة جسر ACPX المؤقتة. -مثال على مطالبة إلى الوكيل المباشر: +مثال على موجّه إلى الوكيل الحي: ```text Use the sessions_spawn tool now with runtime: "acp", agentId: "codex", and mode: "run". @@ -427,29 +427,29 @@ Then report only: accepted=; childSessionKey=; error=; childSessionKey=; error=; childSessionKey=; error=; childSessionKey=; error=` | -| `/acp steer` | إرسال توجيه إلى جلسة قيد التشغيل. | `/acp steer --session support inbox prioritize failing tests` | -| `/acp close` | إغلاق الجلسة وفك ربط أهداف السلسلة. | `/acp close` | -| `/acp status` | عرض الواجهة الخلفية، والوضع، والحالة، وخيارات وقت التشغيل، والقدرات. | `/acp status` | -| `/acp set-mode` | تعيين وضع وقت التشغيل للجلسة الهدف. | `/acp set-mode plan` | -| `/acp set` | كتابة عامة لخيار من خيارات إعداد وقت التشغيل. | `/acp set model openai/gpt-5.4` | -| `/acp cwd` | تعيين تجاوز دليل العمل لوقت التشغيل. | `/acp cwd /Users/user/Projects/repo` | -| `/acp permissions` | تعيين ملف سياسة الموافقات. | `/acp permissions strict` | -| `/acp timeout` | تعيين مهلة وقت التشغيل (بالثواني). | `/acp timeout 120` | -| `/acp model` | تعيين تجاوز نموذج وقت التشغيل. | `/acp model anthropic/claude-opus-4-6` | -| `/acp reset-options` | إزالة تجاوزات خيارات وقت التشغيل للجلسة. | `/acp reset-options` | -| `/acp sessions` | سرد جلسات ACP الحديثة من المخزن. | `/acp sessions` | -| `/acp doctor` | صحة الواجهة الخلفية، والقدرات، والإصلاحات القابلة للتنفيذ. | `/acp doctor` | -| `/acp install` | طباعة خطوات تثبيت وتمكين حتمية. | `/acp install` | +| الأمر | ما الذي يفعله | مثال | +| ------------------ | ---------------------------------------------------------- | ----------------------------------------------------------- | +| `/acp spawn` | إنشاء جلسة ACP؛ مع ربط اختياري للمحادثة الحالية أو ربط بسلسلة. | `/acp spawn codex --bind here --cwd /repo` | +| `/acp cancel` | إلغاء الدور الجاري للجلسة المستهدفة. | `/acp cancel agent:codex:acp:` | +| `/acp steer` | إرسال توجيه إلى جلسة قيد التشغيل. | `/acp steer --session support inbox prioritize failing tests` | +| `/acp close` | إغلاق الجلسة وفك ربط أهداف السلاسل. | `/acp close` | +| `/acp status` | عرض الواجهة الخلفية والوضع والحالة وخيارات وقت التشغيل والقدرات. | `/acp status` | +| `/acp set-mode` | تعيين وضع وقت التشغيل للجلسة المستهدفة. | `/acp set-mode plan` | +| `/acp set` | كتابة خيار إعداد عام لوقت التشغيل. | `/acp set model openai/gpt-5.4` | +| `/acp cwd` | تعيين تجاوز دليل عمل وقت التشغيل. | `/acp cwd /Users/user/Projects/repo` | +| `/acp permissions` | تعيين ملف سياسة الموافقة. | `/acp permissions strict` | +| `/acp timeout` | تعيين مهلة وقت التشغيل (بالثواني). | `/acp timeout 120` | +| `/acp model` | تعيين تجاوز نموذج وقت التشغيل. | `/acp model anthropic/claude-opus-4-6` | +| `/acp reset-options` | إزالة تجاوزات خيارات وقت التشغيل للجلسة. | `/acp reset-options` | +| `/acp sessions` | سرد جلسات ACP الحديثة من المخزن. | `/acp sessions` | +| `/acp doctor` | سلامة الواجهة الخلفية، والقدرات، والإصلاحات القابلة للتنفيذ. | `/acp doctor` | +| `/acp install` | طباعة خطوات تثبيت وتمكين حتمية. | `/acp install` | -يقرأ `/acp sessions` المخزن للجلسة الحالية المرتبطة أو جلسة الطالب الحالية. وتحل الأوامر التي تقبل رموز `session-key` أو `session-id` أو `session-label` الأهداف عبر اكتشاف جلسات البوابة، بما في ذلك جذور `session.store` المخصصة لكل وكيل. +يقرأ `/acp sessions` المخزن للجلسة المرتبطة الحالية أو جلسة الطالب الحالية. تحل الأوامر التي تقبل رموز `session-key` أو `session-id` أو `session-label` الأهداف عبر اكتشاف جلسات البوابة، بما في ذلك الجذور المخصصة لـ `session.store` لكل وكيل. ## ربط خيارات وقت التشغيل -يحتوي `/acp` على أوامر تسهيلية ومُعيّن عام. +تحتوي `/acp` على أوامر مريحة وأداة تعيين عامة. العمليات المكافئة: -- يربط `/acp model ` بمفتاح إعداد وقت التشغيل `model`. -- يربط `/acp permissions ` بمفتاح إعداد وقت التشغيل `approval_policy`. -- يربط `/acp timeout ` بمفتاح إعداد وقت التشغيل `timeout`. -- يحدّث `/acp cwd ` تجاوز `cwd` لوقت التشغيل مباشرة. -- يمثّل `/acp set ` المسار العام. - - حالة خاصة: إذا كان `key=cwd` فإنه يستخدم مسار تجاوز `cwd`. -- يمسح `/acp reset-options` كل تجاوزات وقت التشغيل للجلسة الهدف. +- يطابق `/acp model ` مفتاح إعداد وقت التشغيل `model`. +- يطابق `/acp permissions ` مفتاح إعداد وقت التشغيل `approval_policy`. +- يطابق `/acp timeout ` مفتاح إعداد وقت التشغيل `timeout`. +- يحدّث `/acp cwd ` تجاوز `cwd` لوقت التشغيل مباشرةً. +- يشكّل `/acp set ` المسار العام. + - حالة خاصة: يستخدم `key=cwd` مسار تجاوز cwd. +- يزيل `/acp reset-options` جميع تجاوزات وقت التشغيل للجلسة المستهدفة. -## دعم harness في acpx ‏(الحالي) +## دعم حاضنات acpx (الحالي) -الأسماء المستعارة المضمّنة الحالية لـ harness في acpx: +الأسماء المستعارة المضمّنة الحالية للحاضنات في acpx: - `claude` - `codex` - `copilot` -- `cursor` ‏(Cursor CLI: ‏`cursor-agent acp`) +- `cursor` (Cursor CLI: `cursor-agent acp`) - `droid` - `gemini` - `iflow` @@ -598,10 +598,10 @@ Then report only: accepted=; childSessionKey=; error=`، لكن منفذ الهروب الخام هذا هو ميزة في acpx CLI (وليس المسار المعتاد لـ `agentId` في OpenClaw). +يمكن لاستخدام CLI المباشر لـ acpx أيضًا استهداف مهيئات اعتباطية عبر `--agent `، لكن منفذ الهروب الخام هذا هو ميزة في CLI الخاص بـ acpx (وليس مسار `agentId` المعتاد في OpenClaw). ## الإعداد المطلوب @@ -611,7 +611,7 @@ Then report only: accepted=; childSessionKey=; error=; childSessionKey=; error=; childSessionKey=; error=; childSessionKey=; error=` ثم يعيد التحقق. -يمكنك تجاوز الأمر/الإصدار في إعداد الإضافة: +يمكنك تجاوز الأمر/الإصدار في إعداد plugin: ```json { @@ -735,28 +735,28 @@ openclaw plugins install ./path/to/local/acpx-plugin ملاحظات: -- يقبل `command` مسارًا مطلقًا أو نسبيًا أو اسم أمر (`acpx`). +- يقبل `command` مسارًا مطلقًا أو مسارًا نسبيًا أو اسم أمر (`acpx`). - تُحل المسارات النسبية انطلاقًا من دليل مساحة عمل OpenClaw. - يؤدي `expectedVersion: "any"` إلى تعطيل المطابقة الصارمة للإصدار. -- عندما يشير `command` إلى ثنائية/مسار مخصص، يتم تعطيل التثبيت التلقائي المحلي ضمن الإضافة. -- يظل بدء تشغيل OpenClaw غير حاجز أثناء تنفيذ فحص صحة الواجهة الخلفية. +- عندما يشير `command` إلى ثنائي/مسار مخصص، يتم تعطيل التثبيت التلقائي المحلي داخل plugin. +- يظل بدء تشغيل OpenClaw غير معيق أثناء تنفيذ فحص سلامة الواجهة الخلفية. -راجع [الإضافات](/ar/tools/plugin). +راجع [Plugins](/ar/tools/plugin). ### التثبيت التلقائي للتبعيات -عند تثبيت OpenClaw عالميًا عبر `npm install -g openclaw`، تُثبَّت تبعيات وقت تشغيل acpx -(الثنائيات الخاصة بالمنصة) تلقائيًا -عبر خطاف postinstall. وإذا فشل التثبيت التلقائي، فستبدأ البوابة بشكل طبيعي -وتبلّغ عن التبعية المفقودة عبر `openclaw acp doctor`. +عند تثبيت OpenClaw عالميًا باستخدام `npm install -g openclaw`، يتم تثبيت +تبعيات وقت التشغيل الخاصة بـ acpx (الثنائيات الخاصة بالنظام الأساسي) تلقائيًا +عبر خطاف postinstall. إذا فشل التثبيت التلقائي، فستبدأ البوابة بشكل طبيعي +وستبلّغ عن التبعية المفقودة عبر `openclaw acp doctor`. -### جسر MCP لأدوات الإضافات +### جسر MCP لأدوات plugin -افتراضيًا، لا تعرض جلسات ACPX **أدوات** الإضافات المسجلة في OpenClaw إلى -ACP harness. +افتراضيًا، لا تكشف جلسات ACPX **عن** أدوات OpenClaw المسجلة بواسطة plugin +إلى حاضنة ACP. -إذا كنت تريد أن تستدعي وكلاء ACP مثل Codex أو Claude Code أدوات -إضافات OpenClaw المثبتة مثل استدعاء/تخزين الذاكرة، ففعّل الجسر المخصص: +إذا كنت تريد أن تتمكن وكلاء ACP مثل Codex أو Claude Code من استدعاء +أدوات OpenClaw المثبّتة بواسطة plugin مثل memory recall/store، فعِّل الجسر المخصص: ```bash openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true @@ -764,51 +764,61 @@ openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true ما الذي يفعله هذا: -- يحقن خادم MCP مضمّنًا باسم `openclaw-plugin-tools` ضمن - تمهيد جلسة ACPX. -- يكشف أدوات الإضافات المسجلة أصلًا بواسطة إضافات OpenClaw - المثبتة والمفعّلة. -- يُبقي هذه الميزة صريحة ومعطّلة افتراضيًا. +- يحقن خادم MCP مضمّنًا باسم `openclaw-plugin-tools` في تهيئة جلسة ACPX. +- يكشف أدوات plugin المسجلة بالفعل بواسطة plugins OpenClaw المثبّتة والمفعّلة. +- يبقي الميزة صريحة ومُعطّلة افتراضيًا. ملاحظات الأمان والثقة: -- يوسّع هذا سطح أدوات ACP harness. -- لا يحصل وكلاء ACP إلا على أدوات الإضافات النشطة أصلًا في البوابة. -- تعامل مع هذا على أنه نفس حد الثقة الذي ينطبق على السماح لتلك الإضافات بالتنفيذ داخل - OpenClaw نفسه. -- راجع الإضافات المثبتة قبل تفعيله. +- يؤدي هذا إلى توسيع سطح الأدوات في حاضنة ACP. +- لا يحصل وكلاء ACP إلا على الوصول إلى أدوات plugin النشطة بالفعل في البوابة. +- تعامل مع هذا باعتباره الحد نفسه من الثقة الذي ينطبق على السماح لتلك plugins بالتنفيذ داخل OpenClaw نفسه. +- راجع plugins المثبّتة قبل تفعيله. -تظل `mcpServers` المخصصة تعمل كما كانت من قبل. إن جسر أدوات الإضافات المضمّن هو -ميزة راحة إضافية اختيارية، وليس بديلًا عن إعداد خادم MCP العام. +تظل `mcpServers` المخصصة تعمل كما كانت من قبل. جسر أدوات plugin المضمّن هو +وسيلة راحة إضافية اختيارية، وليس بديلًا عن إعداد خادم MCP العام. -## إعداد الأذونات +### إعداد مهلة وقت التشغيل -تعمل جلسات ACP بصورة غير تفاعلية — لا يوجد TTY للموافقة أو الرفض على مطالبات أذونات كتابة الملفات وتنفيذ shell. توفّر إضافة acpx مفتاحي إعداد يتحكمان في كيفية التعامل مع الأذونات: +يضبط plugin `acpx` المضمّن مهلة أدوار وقت التشغيل المضمّن افتراضيًا على 120 +ثانية. يمنح هذا الحاضنات الأبطأ مثل Gemini CLI وقتًا كافيًا لإكمال +بدء تشغيل ACP والتهيئة. تجاوز هذا إذا كان مضيفك يحتاج إلى حد مختلف +لوقت التشغيل: -هذه الأذونات الخاصة بـ ACPX harness منفصلة عن موافقات التنفيذ في OpenClaw ومنفصلة عن أعلام تجاوز المورّد في CLI-backend مثل Claude CLI ‏`--permission-mode bypassPermissions`. تمثل ACPX ‏`approve-all` مفتاح كسر الزجاج على مستوى harness لجلسات ACP. +```bash +openclaw config set plugins.entries.acpx.config.timeoutSeconds 180 +``` + +أعد تشغيل البوابة بعد تغيير هذه القيمة. + +## إعدادات الأذونات + +تعمل جلسات ACP بشكل غير تفاعلي — لا توجد TTY للموافقة على مطالبات أذونات كتابة الملفات وتنفيذ shell أو رفضها. يوفّر plugin ‏acpx مفتاحَي إعداد يتحكمان في كيفية التعامل مع الأذونات: + +هذه الأذونات الخاصة بحاضنات ACPX منفصلة عن موافقات تنفيذ OpenClaw ومنفصلة عن علامات تجاوز المورّد في الواجهات الخلفية لـ CLI مثل Claude CLI `--permission-mode bypassPermissions`. وتمثل ACPX ‏`approve-all` مفتاح الكسر الطارئ على مستوى الحاضنة لجلسات ACP. ### `permissionMode` -يتحكم في العمليات التي يمكن لوكيل harness تنفيذها من دون مطالبة. +يتحكم في العمليات التي يمكن لوكيل الحاضنة تنفيذها دون مطالبة. -| القيمة | السلوك | -| --------------- | -------------------------------------------------------- | -| `approve-all` | الموافقة التلقائية على جميع عمليات كتابة الملفات وأوامر shell. | -| `approve-reads` | الموافقة التلقائية على عمليات القراءة فقط؛ أما الكتابة والتنفيذ فتتطلبان مطالبات. | -| `deny-all` | رفض جميع مطالبات الأذونات. | +| القيمة | السلوك | +| ---------------- | ------------------------------------------------------- | +| `approve-all` | الموافقة التلقائية على جميع عمليات كتابة الملفات وأوامر shell. | +| `approve-reads` | الموافقة التلقائية على القراءات فقط؛ تتطلب الكتابة والتنفيذ مطالبات. | +| `deny-all` | رفض جميع مطالبات الأذونات. | ### `nonInteractivePermissions` -يتحكم فيما يحدث عندما يفترض أن تظهر مطالبة أذونات ولكن لا يوجد TTY تفاعلي متاح (وهو الحال دائمًا بالنسبة إلى جلسات ACP). +يتحكم في ما يحدث عندما كان من المفترض عرض مطالبة إذن ولكن لا توجد TTY تفاعلية متاحة (وهو الحال دائمًا في جلسات ACP). -| القيمة | السلوك | -| ------ | ------------------------------------------------------------------ | -| `fail` | إجهاض الجلسة مع `AcpRuntimeError`. **(الافتراضي)** | -| `deny` | رفض الإذن بصمت والمتابعة (تراجع سلس). | +| القيمة | السلوك | +| ------ | ---------------------------------------------------------------- | +| `fail` | إيقاف الجلسة مع `AcpRuntimeError`. **(الافتراضي)** | +| `deny` | رفض الإذن بصمت والمتابعة (تدهور سلس). | ### الإعداد -قم بالتعيين عبر إعداد الإضافة: +اضبطه عبر إعداد plugin: ```bash openclaw config set plugins.entries.acpx.config.permissionMode approve-all @@ -817,27 +827,27 @@ openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail أعد تشغيل البوابة بعد تغيير هذه القيم. -> **مهم:** يستخدم OpenClaw حاليًا القيم الافتراضية `permissionMode=approve-reads` و`nonInteractivePermissions=fail`. وفي جلسات ACP غير التفاعلية، يمكن أن تفشل أي عملية كتابة أو تنفيذ تؤدي إلى مطالبة إذن بالخطأ `AcpRuntimeError: Permission prompt unavailable in non-interactive mode`. +> **مهم:** يستخدم OpenClaw حاليًا افتراضيًا `permissionMode=approve-reads` و`nonInteractivePermissions=fail`. في جلسات ACP غير التفاعلية، قد تفشل أي عملية كتابة أو تنفيذ تؤدي إلى مطالبة إذن مع `AcpRuntimeError: Permission prompt unavailable in non-interactive mode`. > -> إذا كنت بحاجة إلى تقييد الأذونات، فعيّن `nonInteractivePermissions` إلى `deny` حتى تتراجع الجلسات بسلاسة بدلًا من أن تتعطل. +> إذا كنت بحاجة إلى تقييد الأذونات، فاضبط `nonInteractivePermissions` على `deny` حتى تتدهور الجلسات بسلاسة بدلًا من أن تتعطل. ## استكشاف الأخطاء وإصلاحها -| العرض | السبب المحتمل | الإصلاح | -| -------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ACP runtime backend is not configured` | إضافة الواجهة الخلفية مفقودة أو معطّلة. | ثبّت إضافة الواجهة الخلفية وفعّلها، ثم شغّل `/acp doctor`. | -| `ACP is disabled by policy (acp.enabled=false)` | تم تعطيل ACP عالميًا. | عيّن `acp.enabled=true`. | -| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | تم تعطيل التوجيه من رسائل السلاسل العادية. | عيّن `acp.dispatch.enabled=true`. | -| `ACP agent "" is not allowed by policy` | الوكيل غير موجود في قائمة السماح. | استخدم `agentId` مسموحًا به أو حدّث `acp.allowedAgents`. | -| `Unable to resolve session target: ...` | رمز مفتاح/معرّف/تسمية غير صحيح. | شغّل `/acp sessions`، وانسخ المفتاح/التسمية بدقة، ثم أعد المحاولة. | -| `--bind here requires running /acp spawn inside an active ... conversation` | استُخدم `--bind here` من دون محادثة نشطة قابلة للربط. | انتقل إلى الدردشة/القناة المستهدفة وأعد المحاولة، أو استخدم spawn غير مرتبط. | -| `Conversation bindings are unavailable for .` | لا يملك المهايئ قدرة ربط ACP بالمحادثة الحالية. | استخدم `/acp spawn ... --thread ...` عند الدعم، أو هيئ `bindings[]` على المستوى الأعلى، أو انتقل إلى قناة مدعومة. | -| `--thread here requires running /acp spawn inside an active ... thread` | استُخدم `--thread here` خارج سياق سلسلة. | انتقل إلى السلسلة المستهدفة أو استخدم `--thread auto`/`off`. | -| `Only can rebind this channel/conversation/thread.` | يمتلك مستخدم آخر هدف الربط النشط. | أعد الربط بصفتك المالك أو استخدم محادثة أو سلسلة مختلفة. | -| `Thread bindings are unavailable for .` | لا يملك المهايئ قدرة ربط السلاسل. | استخدم `--thread off` أو انتقل إلى مهايئ/قناة مدعومة. | -| `Sandboxed sessions cannot spawn ACP sessions ...` | وقت تشغيل ACP يعمل على جهة المضيف؛ جلسة الطالب تعمل داخل sandbox. | استخدم `runtime="subagent"` من جلسات sandboxed، أو شغّل ACP spawn من جلسة غير sandboxed. | -| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | تم طلب `sandbox="require"` لوقت تشغيل ACP. | استخدم `runtime="subagent"` عندما يكون sandbox مطلوبًا، أو استخدم ACP مع `sandbox="inherit"` من جلسة غير sandboxed. | -| Missing ACP metadata for bound session | بيانات تعريف ACP قديمة/محذوفة للجلسة المرتبطة. | أعد الإنشاء باستخدام `/acp spawn`، ثم أعد الربط/تركيز السلسلة. | -| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | تمنع `permissionMode` عمليات الكتابة/التنفيذ في جلسة ACP غير تفاعلية. | عيّن `plugins.entries.acpx.config.permissionMode` إلى `approve-all` ثم أعد تشغيل البوابة. راجع [إعداد الأذونات](#permission-configuration). | -| تفشل جلسة ACP مبكرًا مع خرج قليل | تُحظر مطالبات الأذونات بواسطة `permissionMode`/`nonInteractivePermissions`. | تحقق من سجلات البوابة للعثور على `AcpRuntimeError`. للحصول على أذونات كاملة، عيّن `permissionMode=approve-all`؛ وللتراجع السلس، عيّن `nonInteractivePermissions=deny`. | -| تتوقف جلسة ACP إلى أجل غير مسمى بعد إكمال العمل | انتهت عملية harness لكن جلسة ACP لم تبلغ عن الاكتمال. | راقب عبر `ps aux \| grep acpx`; واقتل العمليات القديمة يدويًا. | +| العَرَض | السبب المرجّح | الإصلاح | +| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ACP runtime backend is not configured` | plugin الواجهة الخلفية مفقود أو معطّل. | ثبّت plugin الواجهة الخلفية وفعّله، ثم شغّل `/acp doctor`. | +| `ACP is disabled by policy (acp.enabled=false)` | تم تعطيل ACP عالميًا. | اضبط `acp.enabled=true`. | +| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | تم تعطيل التوجيه من رسائل السلاسل العادية. | اضبط `acp.dispatch.enabled=true`. | +| `ACP agent "" is not allowed by policy` | الوكيل ليس ضمن قائمة السماح. | استخدم `agentId` مسموحًا به أو حدّث `acp.allowedAgents`. | +| `Unable to resolve session target: ...` | رمز مفتاح/معرّف/تسمية غير صحيح. | شغّل `/acp sessions`، وانسخ المفتاح/التسمية بدقة، ثم أعد المحاولة. | +| `--bind here requires running /acp spawn inside an active ... conversation` | استُخدم `--bind here` بدون وجود محادثة نشطة قابلة للربط. | انتقل إلى الدردشة/القناة المستهدفة وأعد المحاولة، أو استخدم إنشاءً غير مرتبط. | +| `Conversation bindings are unavailable for .` | يفتقر المهايئ إلى قدرة ربط ACP بالمحادثة الحالية. | استخدم `/acp spawn ... --thread ...` عند الدعم، أو اضبط `bindings[]` ذات المستوى الأعلى، أو انتقل إلى قناة مدعومة. | +| `--thread here requires running /acp spawn inside an active ... thread` | استُخدم `--thread here` خارج سياق سلسلة. | انتقل إلى السلسلة المستهدفة أو استخدم `--thread auto`/`off`. | +| `Only can rebind this channel/conversation/thread.` | يملك مستخدم آخر هدف الربط النشط. | أعد الربط بصفتك المالك أو استخدم محادثة أو سلسلة أخرى. | +| `Thread bindings are unavailable for .` | يفتقر المهايئ إلى قدرة ربط السلاسل. | استخدم `--thread off` أو انتقل إلى مهايئ/قناة مدعومين. | +| `Sandboxed sessions cannot spawn ACP sessions ...` | وقت تشغيل ACP يعمل على المضيف؛ وجلسة الطالب داخل sandbox. | استخدم `runtime="subagent"` من الجلسات داخل sandbox، أو شغّل إنشاء ACP من جلسة خارج sandbox. | +| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | طُلِب `sandbox="require"` لوقت تشغيل ACP. | استخدم `runtime="subagent"` إذا كان العزل الإلزامي مطلوبًا، أو استخدم ACP مع `sandbox="inherit"` من جلسة خارج sandbox. | +| Missing ACP metadata for bound session | بيانات تعريف ACP قديمة/محذوفة للجلسة المرتبطة. | أعد الإنشاء باستخدام `/acp spawn`، ثم أعد الربط/التركيز على السلسلة. | +| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | يمنع `permissionMode` عمليات الكتابة/التنفيذ في جلسة ACP غير تفاعلية. | اضبط `plugins.entries.acpx.config.permissionMode` على `approve-all` وأعد تشغيل البوابة. راجع [إعدادات الأذونات](#permission-configuration). | +| ACP session fails early with little output | يتم حظر مطالبات الأذونات بواسطة `permissionMode`/`nonInteractivePermissions`. | تحقّق من سجلات البوابة بحثًا عن `AcpRuntimeError`. للحصول على أذونات كاملة، اضبط `permissionMode=approve-all`؛ وللتدهور السلس، اضبط `nonInteractivePermissions=deny`. | +| ACP session stalls indefinitely after completing work | انتهت عملية الحاضنة لكن جلسة ACP لم تُبلغ عن الاكتمال. | راقب باستخدام `ps aux \| grep acpx`; واقتل العمليات العالقة يدويًا. | diff --git a/docs/ar/tools/exec-approvals.md b/docs/ar/tools/exec-approvals.md index e65e0aad5..30b2d0f9f 100644 --- a/docs/ar/tools/exec-approvals.md +++ b/docs/ar/tools/exec-approvals.md @@ -1,70 +1,70 @@ --- read_when: - - ضبط موافقات exec أو قوائم السماح - - تنفيذ تجربة مستخدم موافقات exec في تطبيق macOS - - مراجعة مطالبات الخروج من sandbox وآثارها -summary: موافقات exec وقوائم السماح ومطالبات الخروج من sandbox + - عند تكوين موافقات exec أو قوائم السماح + - عند تنفيذ واجهة مستخدم موافقة exec في تطبيق macOS + - عند مراجعة مطالبات الخروج من العزل وتبعاتها +summary: موافقات exec، قوائم السماح، ومطالبات الخروج من العزل title: موافقات Exec x-i18n: - generated_at: "2026-04-06T03:14:23Z" + generated_at: "2026-04-08T02:22:46Z" model: gpt-5.4 provider: openai - source_hash: 39e91cd5c7615bdb9a6b201a85bde7514327910f6f12da5a4b0532bceb229c22 + source_hash: 6041929185bab051ad873cc4822288cb7d6f0470e19e7ae7a16b70f76dfc2cd9 source_path: tools/exec-approvals.md workflow: 15 --- # موافقات Exec -تمثل موافقات exec **حاجز الحماية للتطبيق المرافق / مستضيف العقدة** للسماح لوكيل داخل sandbox بتشغيل -أوامر على مستضيف حقيقي (`gateway` أو `node`). فكّر فيها على أنها قفل أمان: -لا يُسمح بالأوامر إلا عندما تتفق السياسة + قائمة السماح + (اختياريًا) موافقة المستخدم كلها. -تأتي موافقات exec **بالإضافة** إلى سياسة الأدوات وتقييد elevated (إلا إذا كانت elevated مضبوطة على `full`، إذ يتم تجاوز الموافقات). -السياسة الفعلية هي **الأكثر تقييدًا** بين `tools.exec.*` والقيم الافتراضية للموافقات؛ وإذا تم حذف أحد حقول الموافقات، تُستخدم قيمة `tools.exec`. -يستخدم exec على المستضيف أيضًا حالة الموافقات المحلية على ذلك الجهاز. إن كانت قيمة -`ask: "always"` المحلية على المستضيف في `~/.openclaw/exec-approvals.json` مضبوطة، فسيستمر -إظهار المطالبة حتى لو طلبت الجلسة أو الإعدادات الافتراضية `ask: "on-miss"`. -استخدم `openclaw approvals get`، أو `openclaw approvals get --gateway`، أو +تُعد موافقات exec **وسيلة الحماية في التطبيق المرافق / مضيف العقدة** للسماح لوكيل معزول بتشغيل +الأوامر على مضيف فعلي (`gateway` أو `node`). فكّر فيها كأنها قفل أمان: +لا يُسمح بالأوامر إلا عندما تتفق السياسة + قائمة السماح + (اختياريًا) موافقة المستخدم جميعًا. +تُستخدم موافقات exec **بالإضافة** إلى سياسة الأدوات وبوابة elevated (إلا إذا كانت قيمة elevated هي `full`، إذ يتم عندها تجاوز الموافقات). +السياسة الفعلية هي **الأكثر تقييدًا** بين `tools.exec.*` والإعدادات الافتراضية للموافقات؛ إذا تم حذف حقل من حقول الموافقات، تُستخدم قيمة `tools.exec`. +يستخدم exec على المضيف أيضًا حالة الموافقات المحلية على تلك الآلة. تؤدي قيمة +`ask: "always"` المحلية للمضيف في `~/.openclaw/exec-approvals.json` إلى استمرار ظهور المطالبات حتى إذا +كانت إعدادات الجلسة أو التكوين الافتراضية تطلب `ask: "on-miss"`. +استخدم `openclaw approvals get` أو `openclaw approvals get --gateway` أو `openclaw approvals get --node ` لفحص السياسة المطلوبة، -ومصادر سياسة المستضيف، والنتيجة الفعلية. +ومصادر سياسة المضيف، والنتيجة الفعلية. إذا كانت واجهة التطبيق المرافق **غير متاحة**، فإن أي طلب يتطلب مطالبة -يُحسم بواسطة **البديل ask** (والافتراضي هو deny). +يُحسم بواسطة **الرجوع الاحتياطي للسؤال** (الافتراضي: الرفض). -يمكن لعملاء الموافقة الأصليين في الدردشة أيضًا عرض وسائل خاصة بكل قناة على -رسالة الموافقة المعلقة. على سبيل المثال، يمكن لـ Matrix إنشاء اختصارات تفاعلات على -مطالبة الموافقة (`✅` للسماح مرة واحدة، و`❌` للرفض، و`♾️` للسماح دائمًا عند التوفر) -مع الإبقاء على أوامر `/approve ...` في الرسالة كبديل. +يمكن لعملاء الموافقة الأصليين في الدردشة أيضًا عرض عناصر تفاعل خاصة بالقناة على +رسالة الموافقة المعلقة. على سبيل المثال، يمكن لـ Matrix تهيئة اختصارات التفاعل على +مطالبة الموافقة (`✅` للسماح مرة واحدة، و`❌` للرفض، و`♾️` للسماح دائمًا عند توفره) +مع الإبقاء على أوامر `/approve ...` في الرسالة كخيار احتياطي. ## أين ينطبق ذلك -تُفرض موافقات exec محليًا على مستضيف التنفيذ: +تُفرض موافقات exec محليًا على مضيف التنفيذ: -- **مستضيف gateway** → عملية `openclaw` على جهاز البوابة -- **مستضيف node** → مشغل العقدة (تطبيق macOS المرافق أو مستضيف عقدة بدون واجهة) +- **مضيف gateway** ← عملية `openclaw` على جهاز gateway +- **مضيف node** ← مشغّل العقدة (تطبيق macOS المرافق أو مضيف عقدة بدون واجهة) ملاحظة حول نموذج الثقة: -- يُعد المستدعون المصادق عليهم عبر البوابة مشغلين موثوقين لتلك البوابة. -- توسّع العقد المقترنة هذه القدرة الخاصة بالمشغّل الموثوق إلى مستضيف العقدة. -- تقلل موافقات exec من مخاطر التنفيذ العرضي، لكنها ليست حدًا للمصادقة لكل مستخدم. -- تربط التشغيلات الموافق عليها على مستضيف العقدة سياق تنفيذ قياسيًا: `cwd` القياسي، و`argv` الدقيق، وربط `env` - عند وجوده، ومسار الملف التنفيذي المثبّت عند الاقتضاء. -- بالنسبة إلى shell scripts واستدعاءات الملفات المباشرة للمفسر/وقت التشغيل، يحاول OpenClaw أيضًا ربط - معامل ملف محلي ملموس واحد. إذا تغيّر هذا الملف المرتبط بعد الموافقة ولكن قبل التنفيذ، +- يُعد المستدعون المصادق عليهم من قبل Gateway مشغّلين موثوقين لذلك الـ Gateway. +- توسّع العقد المقترنة هذه القدرة التشغيلية الموثوقة إلى مضيف العقدة. +- تقلل موافقات exec من خطر التنفيذ العرضي، لكنها ليست حدًا للمصادقة لكل مستخدم. +- ترتبط عمليات التشغيل المعتمدة على مضيف العقدة بسياق تنفيذ أساسي: cwd أساسي، وargv مطابق، وربط env + عند وجوده، ومسار ملف تنفيذي مثبت عند الاقتضاء. +- بالنسبة إلى نصوص shell البرمجية والاستدعاءات المباشرة لملفات المفسر/بيئة التشغيل، يحاول OpenClaw أيضًا ربط + مُعامل ملف محلي ملموس واحد. إذا تغيّر هذا الملف المرتبط بعد الموافقة ولكن قبل التنفيذ، يُرفض التشغيل بدلًا من تنفيذ محتوى منجرف. -- هذا الربط للملفات هو عمدًا بأفضل جهد ممكن، وليس نموذجًا دلاليًا كاملًا لكل - مسارات تحميل المفسرات/أوقات التشغيل. إذا تعذر على وضع الموافقة تحديد ملف محلي ملموس واحد بالضبط +- يظل ربط الملفات هذا عمدًا على أساس أفضل جهد، وليس نموذجًا دلاليًا كاملًا لكل + مسار تحميل خاص بالمفسر/بيئة التشغيل. إذا تعذر على وضع الموافقة تحديد ملف محلي ملموس واحد بالضبط لربطه، فإنه يرفض إنشاء تشغيل مدعوم بالموافقة بدلًا من الادعاء بتغطية كاملة. -الانقسام في macOS: +تقسيم macOS: -- **خدمة مستضيف node** تمرر `system.run` إلى **تطبيق macOS** عبر IPC محلي. -- **تطبيق macOS** يفرض الموافقات + ينفذ الأمر في سياق واجهة المستخدم. +- تقوم **خدمة مضيف node** بتمرير `system.run` إلى **تطبيق macOS** عبر IPC محلي. +- يقوم **تطبيق macOS** بفرض الموافقات + تنفيذ الأمر ضمن سياق واجهة المستخدم. ## الإعدادات والتخزين -توجد الموافقات في ملف JSON محلي على مستضيف التنفيذ: +تعيش الموافقات في ملف JSON محلي على مضيف التنفيذ: `~/.openclaw/exec-approvals.json` @@ -103,30 +103,30 @@ x-i18n: } ``` -## وضع "YOLO" من دون موافقة +## وضع "YOLO" بدون موافقة -إذا كنت تريد أن يعمل exec على المستضيف من دون مطالبات موافقة، فيجب فتح **طبقتَي** السياسة كلتيهما: +إذا كنت تريد تشغيل exec على المضيف دون مطالبات موافقة، فيجب عليك فتح **طبقتي** السياسة كلتيهما: - سياسة exec المطلوبة في إعدادات OpenClaw (`tools.exec.*`) -- سياسة الموافقات المحلية على المستضيف في `~/.openclaw/exec-approvals.json` +- سياسة الموافقات المحلية على المضيف في `~/.openclaw/exec-approvals.json` -هذا هو الآن سلوك المستضيف الافتراضي ما لم تُحكم تقييده صراحة: +هذا هو الآن سلوك المضيف الافتراضي ما لم تشدده صراحةً: -- `tools.exec.security`: ‏`full` على `gateway`/`node` -- `tools.exec.ask`: ‏`off` -- قيمة `askFallback` على المستضيف: ‏`full` +- `tools.exec.security`: `full` على `gateway`/`node` +- `tools.exec.ask`: `off` +- `askFallback` على المضيف: `full` تمييز مهم: -- يختار `tools.exec.host=auto` مكان تشغيل exec: داخل sandbox عند توفره، وإلا على gateway. -- ويختار وضع YOLO كيفية الموافقة على exec على المستضيف: `security=full` بالإضافة إلى `ask=off`. -- في وضع YOLO، لا يضيف OpenClaw بوابة موافقة منفصلة قائمة على الكشف الإرشادي عن تمويه الأوامر فوق سياسة exec على المستضيف المضبوطة. -- لا يجعل `auto` توجيه gateway تجاوزًا مجانيًا من جلسة داخل sandbox. يُسمح بطلب `host=node` لكل استدعاء من `auto`، ولا يُسمح بـ `host=gateway` من `auto` إلا عندما لا يكون هناك runtime نشط لـ sandbox. إذا كنت تريد قيمة افتراضية ثابتة غير auto، فاضبط `tools.exec.host` أو استخدم `/exec host=...` صراحة. +- يحدد `tools.exec.host=auto` مكان تشغيل exec: داخل العزل عند توفره، وإلا على gateway. +- يحدد YOLO كيفية اعتماد exec على المضيف: `security=full` مع `ask=off`. +- في وضع YOLO، لا يضيف OpenClaw بوابة موافقة استدلالية منفصلة لإخفاء الأوامر فوق سياسة exec على المضيف المكوّنة. +- لا يجعل `auto` توجيه gateway تجاوزًا مجانيًا من جلسة معزولة. يُسمح بطلب `host=node` لكل استدعاء من `auto`، ويُسمح بـ `host=gateway` من `auto` فقط عندما لا تكون هناك بيئة تشغيل عزل نشطة. إذا كنت تريد إعدادًا افتراضيًا ثابتًا غير auto، فاضبط `tools.exec.host` أو استخدم `/exec host=...` صراحةً. إذا كنت تريد إعدادًا أكثر تحفظًا، فأعد تشديد أي من الطبقتين إلى `allowlist` / `on-miss` أو `deny`. -إعداد دائم على مستضيف gateway لتعطيل كل المطالبات: +إعداد دائم لـ gateway-host مع "عدم المطالبة مطلقًا": ```bash openclaw config set tools.exec.host gateway @@ -135,7 +135,7 @@ openclaw config set tools.exec.ask off openclaw gateway restart ``` -ثم اضبط ملف الموافقات على المستضيف ليتطابق: +ثم اضبط ملف موافقات المضيف ليتطابق: ```bash openclaw approvals set --stdin <<'EOF' @@ -150,7 +150,7 @@ openclaw approvals set --stdin <<'EOF' EOF ``` -وبالنسبة إلى مستضيف node، طبّق ملف الموافقات نفسه على تلك العقدة بدلًا من ذلك: +بالنسبة إلى مضيف node، طبّق ملف الموافقات نفسه على تلك العقدة بدلًا من ذلك: ```bash openclaw approvals set --node --stdin <<'EOF' @@ -165,39 +165,39 @@ openclaw approvals set --node --stdin <<'EOF' EOF ``` -اختصار خاص بالجلسة فقط: +اختصار على مستوى الجلسة فقط: - يغيّر `/exec security=full ask=off` الجلسة الحالية فقط. -- يُعد `/elevated full` اختصارًا للطوارئ يتجاوز أيضًا موافقات exec لتلك الجلسة. +- يعد `/elevated full` اختصارًا للطوارئ يتجاوز أيضًا موافقات exec لتلك الجلسة. -إذا ظل ملف الموافقات على المستضيف أكثر تقييدًا من الإعدادات، فستظل سياسة المستضيف الأكثر تشددًا هي السارية. +إذا ظل ملف موافقات المضيف أكثر تقييدًا من الإعدادات، فستظل سياسة المضيف الأكثر تقييدًا هي السارية. -## عناصر التحكم في السياسة +## مفاتيح السياسة ### الأمان (`exec.security`) -- **deny**: حظر كل طلبات exec على المستضيف. -- **allowlist**: السماح فقط بالأوامر الموجودة في قائمة السماح. +- **deny**: حظر جميع طلبات exec على المضيف. +- **allowlist**: السماح فقط للأوامر الموجودة في قائمة السماح. - **full**: السماح بكل شيء (مكافئ لـ elevated). -### Ask (`exec.ask`) +### السؤال (`exec.ask`) -- **off**: عدم إظهار مطالبة مطلقًا. -- **on-miss**: إظهار مطالبة فقط عندما لا تطابق قائمة السماح. -- **always**: إظهار مطالبة لكل أمر. -- لا يؤدي trust الدائم `allow-always` إلى إخفاء المطالبات عندما يكون وضع ask الفعلي هو `always` +- **off**: عدم عرض أي مطالبة مطلقًا. +- **on-miss**: عرض مطالبة فقط عندما لا تتطابق قائمة السماح. +- **always**: عرض مطالبة لكل أمر. +- الثقة الدائمة `allow-always` لا تمنع ظهور المطالبات عندما يكون وضع السؤال الفعلي هو `always` -### Ask fallback (`askFallback`) +### الرجوع الاحتياطي للسؤال (`askFallback`) -إذا كانت المطالبة مطلوبة ولكن لا توجد واجهة مستخدم قابلة للوصول، فإن البديل يقرر: +إذا كانت المطالبة مطلوبة ولكن لا يمكن الوصول إلى واجهة مستخدم، فإن آلية الرجوع الاحتياطي تقرر: - **deny**: حظر. -- **allowlist**: السماح فقط إذا طابقت قائمة السماح. +- **allowlist**: السماح فقط إذا تطابقت قائمة السماح. - **full**: السماح. -### تقوية eval المضمنة للمفسر (`tools.exec.strictInlineEval`) +### تقوية eval المضمن للمفسر (`tools.exec.strictInlineEval`) -عندما تكون `tools.exec.strictInlineEval=true`، يعامل OpenClaw صيغ eval المضمنة على أنها تتطلب موافقة فقط حتى لو كان ملف المفسر التنفيذي نفسه موجودًا في قائمة السماح. +عندما تكون القيمة `tools.exec.strictInlineEval=true`، يتعامل OpenClaw مع صيغ eval البرمجية المضمنة على أنها تتطلب الموافقة فقط حتى لو كان ملف المفسر نفسه ضمن قائمة السماح. أمثلة: @@ -209,19 +209,18 @@ EOF - `lua -e` - `osascript -e` -هذا دفاع إضافي لطبقة التفسير بالنسبة إلى محمّلات المفسرات التي لا ترتبط بوضوح -بمعامل ملف واحد ثابت. في الوضع الصارم: +هذا دفاع إضافي للمحمّلات الخاصة بالمفسرات التي لا ترتبط بوضوح بملف ثابت واحد. في الوضع الصارم: - لا تزال هذه الأوامر تحتاج إلى موافقة صريحة؛ -- ولا يؤدي `allow-always` إلى حفظ إدخالات جديدة في قائمة السماح لها تلقائيًا. +- لا يؤدي `allow-always` إلى حفظ إدخالات جديدة في قائمة السماح لها تلقائيًا. ## قائمة السماح (لكل وكيل) -تكون قوائم السماح **لكل وكيل**. إذا كان هناك عدة وكلاء، فبدّل الوكيل الذي تقوم -بتحريره في تطبيق macOS. الأنماط هي **مطابقات glob غير حساسة لحالة الأحرف**. -ويجب أن تُحل الأنماط إلى **مسارات ملفات تنفيذية** (ويتم تجاهل الإدخالات التي تحتوي على الاسم الأساسي فقط). -تُرحّل إدخالات `agents.default` القديمة إلى `agents.main` عند التحميل. -ولا تزال سلاسل shell مثل `echo ok && pwd` تتطلب أن يحقق كل مقطع من المستوى الأعلى قواعد قائمة السماح. +تكون قوائم السماح **لكل وكيل**. إذا كان هناك عدة وكلاء، فبدّل الوكيل الذي +تقوم بتحريره في تطبيق macOS. تكون الأنماط **مطابقات glob غير حساسة لحالة الأحرف**. +يجب أن تُحل الأنماط إلى **مسارات ملفات تنفيذية** (تُتجاهل الإدخالات التي تحتوي على الاسم الأساسي فقط). +تُنقل إدخالات `agents.default` القديمة إلى `agents.main` عند التحميل. +لا تزال سلاسل shell مثل `echo ok && pwd` تتطلب أن يستوفي كل جزء علوي قواعد قائمة السماح. أمثلة: @@ -231,43 +230,43 @@ EOF يتتبع كل إدخال في قائمة السماح: -- **id** UUID ثابت يُستخدم لهوية واجهة المستخدم (اختياري) +- **id** معرّف UUID ثابت يُستخدم لهوية واجهة المستخدم (اختياري) - **آخر استخدام** طابع زمني - **آخر أمر مستخدم** -- **آخر مسار محلول** +- **آخر مسار تم حله** -## Auto-allow لـ CLIs الخاصة بـ Skills +## السماح التلقائي لـ CLI الخاصة بـ Skills -عند تفعيل **Auto-allow skill CLIs**، تُعامل الملفات التنفيذية المشار إليها من Skills معروفة -على أنها موجودة في قائمة السماح على العقد (عقدة macOS أو مستضيف عقدة بدون واجهة). يستخدم هذا -`skills.bins` عبر Gateway RPC لجلب قائمة ملفات skill bin. عطّل هذا إذا كنت تريد قوائم سماح يدوية صارمة. +عند تمكين **السماح التلقائي لـ CLI الخاصة بـ Skills**، تُعامل الملفات التنفيذية المشار إليها بواسطة Skills المعروفة +على أنها مدرجة في قائمة السماح على العقد (عقدة macOS أو مضيف عقدة بدون واجهة). يستخدم هذا +`skills.bins` عبر Gateway RPC لجلب قائمة ملفات bin الخاصة بالمهارات. عطّل هذا إذا كنت تريد قوائم سماح يدوية صارمة. ملاحظات ثقة مهمة: -- هذه **قائمة سماح ضمنية للتيسير**، منفصلة عن إدخالات قائمة السماح اليدوية للمسارات. -- وهي مخصّصة لبيئات المشغّلين الموثوقين حيث تقع البوابة والعقدة ضمن حدود الثقة نفسها. -- إذا كنت تحتاج إلى ثقة صريحة صارمة، فأبقِ `autoAllowSkills: false` واستخدم إدخالات قائمة السماح اليدوية للمسارات فقط. +- هذه **قائمة سماح ضمنية للتسهيل**، منفصلة عن إدخالات قائمة سماح المسارات اليدوية. +- وهي مخصصة لبيئات المشغّلين الموثوقين حيث يكون Gateway والعقدة ضمن حدود الثقة نفسها. +- إذا كنت تحتاج إلى ثقة صريحة صارمة، فأبقِ `autoAllowSkills: false` واستخدم إدخالات قائمة سماح المسارات اليدوية فقط. ## Safe bins (stdin-only) -يعرّف `tools.exec.safeBins` قائمة صغيرة من الملفات التنفيذية **المقتصرة على stdin** (مثل `cut`) -والتي يمكن تشغيلها في وضع allowlist **من دون** إدخالات صريحة في قائمة السماح. ترفض safe bins -وسائط الملفات الموضعية والرموز الشبيهة بالمسارات، لذا يمكنها العمل فقط على الدفق الوارد. -تعامل مع هذا على أنه مسار سريع ضيق لفلاتر الدفق، وليس قائمة ثقة عامة. -**لا** تضف ملفات المفسرات أو أوقات التشغيل التنفيذية (مثل `python3` أو `node` أو `ruby` أو `bash` أو `sh` أو `zsh`) إلى `safeBins`. -إذا كان بإمكان أمر ما تقييم الشيفرة أو تنفيذ أوامر فرعية أو قراءة ملفات بطبيعته، ففضّل إدخالات قائمة سماح صريحة مع إبقاء مطالبات الموافقة مفعلة. -يجب أن تعرّف safe bins المخصصة ملف تعريف صريحًا في `tools.exec.safeBinProfiles.`. -ويكون التحقق حتميًا من شكل argv فقط (من دون فحوصات لوجود الملفات في نظام ملفات المستضيف)، -مما يمنع سلوك oracle لوجود الملفات الناتج عن فروق السماح/المنع. -تُرفض الخيارات الموجهة للملفات بالنسبة إلى safe bins الافتراضية (مثل `sort -o` و`sort --output`, -و`sort --files0-from` و`sort --compress-program` و`sort --random-source`, -و`sort --temporary-directory`/`-T`، و`wc --files0-from`، و`jq -f/--from-file`, +يحدد `tools.exec.safeBins` قائمة صغيرة من الملفات الثنائية **الخاصة بـ stdin فقط** (مثل `cut`) +التي يمكنها التشغيل في وضع allowlist **من دون** إدخالات صريحة في قائمة السماح. ترفض Safe bins +وسائط الملفات الموضعية والرموز الشبيهة بالمسارات، لذلك لا يمكنها العمل إلا على الدفق الوارد. +تعامل مع ذلك كمسار سريع ضيق لمرشحات الدفق، وليس كقائمة ثقة عامة. +**لا** تضف ملفات مفسرات أو بيئات تشغيل ثنائية (مثل `python3` و`node` و`ruby` و`bash` و`sh` و`zsh`) إلى `safeBins`. +إذا كان بإمكان الأمر تقييم تعليمات برمجية، أو تنفيذ أوامر فرعية، أو قراءة ملفات بطبيعته، ففضّل إدخالات قائمة السماح الصريحة وأبقِ مطالبات الموافقة مفعّلة. +يجب أن تحدد Safe bins المخصصة ملف تعريف صريحًا في `tools.exec.safeBinProfiles.`. +يكون التحقق حتميًا استنادًا إلى شكل argv فقط (من دون فحوصات لوجود الملفات على نظام المضيف)، مما +يمنع سلوك تسريب معلومات وجود الملفات من خلال اختلافات السماح/الرفض. +تُرفض الخيارات الموجهة للملفات بالنسبة إلى Safe bins الافتراضية (مثل `sort -o` و`sort --output`، +و`sort --files0-from` و`sort --compress-program` و`sort --random-source`، +و`sort --temporary-directory`/`-T`، و`wc --files0-from`، و`jq -f/--from-file`، و`grep -f/--file`). -وتفرض safe bins أيضًا سياسة صريحة لكل ملف تنفيذي على مستوى الأعلام بالنسبة إلى الخيارات التي تكسر -سلوك stdin-only (مثل `sort -o/--output/--compress-program` وأعلام grep التكرارية). -ويتم التحقق من الخيارات الطويلة بأسلوب fail-closed في وضع safe-bin: تُرفض الأعلام غير المعروفة -والاختصارات الغامضة. -الأعلام الممنوعة بحسب ملف تعريف safe-bin: +تفرض Safe bins أيضًا سياسة صريحة لكل ملف ثنائي على مستوى العلامات للخيارات التي تكسر سلوك +stdin-only (مثل `sort -o/--output/--compress-program` وعلامات grep التكرارية). +تُتحقق الخيارات الطويلة وفق مبدأ الفشل المغلق في وضع safe-bin: تُرفض العلامات غير المعروفة +والاختصارات الملتبسة. +العلامات المرفوضة حسب ملف تعريف safe-bin: [//]: # "SAFE_BIN_DENIED_FLAGS:START" @@ -278,33 +277,34 @@ EOF [//]: # "SAFE_BIN_DENIED_FLAGS:END" -وتفرض safe bins أيضًا معاملة رموز argv على أنها **نص حرفي** وقت التنفيذ (من دون globbing -ولا توسيع `$VARS`) لمقاطع stdin-only، بحيث لا يمكن استخدام أنماط مثل `*` أو `$HOME/...` +تُجبر Safe bins أيضًا رموز argv على أن تُعامل كـ **نص حرفي** في وقت التنفيذ (من دون globbing +ومن دون توسيع `$VARS`) بالنسبة إلى المقاطع الخاصة بـ stdin فقط، بحيث لا يمكن استخدام أنماط مثل `*` أو `$HOME/...` لتهريب قراءات الملفات. -كما يجب أن تُحل safe bins من أدلة ملفات تنفيذية موثوق بها (القيم الافتراضية للنظام بالإضافة إلى -`tools.exec.safeBinTrustedDirs` الاختيارية). ولا تُعامل إدخالات `PATH` على أنها موثوقة تلقائيًا. -إن أدلة safe-bin الافتراضية الموثوقة محدودة عمدًا: `/bin`، `/usr/bin`. -إذا كان الملف التنفيذي الخاص بـ safe-bin لديك موجودًا في مسارات مدير الحزم/المستخدم (مثل -`/opt/homebrew/bin` أو `/usr/local/bin` أو `/opt/local/bin` أو `/snap/bin`)، فأضفها صراحة +يجب أيضًا أن تُحل Safe bins من أدلة ملفات ثنائية موثوقة (الإعدادات الافتراضية للنظام بالإضافة إلى +`tools.exec.safeBinTrustedDirs` الاختيارية). لا تُعد إدخالات `PATH` موثوقة تلقائيًا أبدًا. +أدلة Safe-bin الموثوقة الافتراضية محدودة عمدًا: `/bin`، `/usr/bin`. +إذا كان الملف التنفيذي لـ safe-bin موجودًا في مسارات مدير الحزم/المستخدم (مثل +`/opt/homebrew/bin` أو `/usr/local/bin` أو `/opt/local/bin` أو `/snap/bin`)، فأضفها صراحةً إلى `tools.exec.safeBinTrustedDirs`. -لا يُسمح تلقائيًا بسلاسل shell وعمليات إعادة التوجيه في وضع allowlist. +لا يُسمح تلقائيًا بتسلسل shell وإعادات التوجيه في وضع allowlist. -يُسمح بسلاسل shell (`&&` و`||` و`;`) عندما يحقق كل مقطع من المستوى الأعلى متطلبات قائمة السماح -(بما في ذلك safe bins أو auto-allow الخاصة بـ skill). ولا تزال عمليات إعادة التوجيه غير مدعومة في وضع allowlist. -ويُرفض command substitution (`$()` / backticks) أثناء تحليل allowlist، بما في ذلك داخل +يُسمح بتسلسل shell (`&&` و`||` و`;`) عندما يستوفي كل جزء علوي متطلبات قائمة السماح +(بما في ذلك safe bins أو السماح التلقائي للمهارات). تظل إعادات التوجيه غير مدعومة في وضع allowlist. +يُرفض استبدال الأوامر (`$()` / backticks) أثناء تحليل allowlist، بما في ذلك داخل علامات الاقتباس المزدوجة؛ استخدم علامات اقتباس مفردة إذا كنت تحتاج إلى نص `$()` حرفي. -في موافقات تطبيق macOS المرافق، يُعامل نص shell الخام الذي يحتوي على صياغات تحكم shell أو التوسيع -(`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) على أنه عدم تطابق مع allowlist ما لم -يكن ملف shell التنفيذي نفسه موجودًا في قائمة السماح. -بالنسبة إلى مغلفات shell (`bash|sh|zsh ... -c/-lc`)، تُختزل تجاوزات env ضمن نطاق الطلب إلى -قائمة سماح صغيرة وصريحة (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`). -وبالنسبة إلى قرارات allow-always في وضع allowlist، فإن مغلفات الإرسال المعروفة -(`env`, `nice`, `nohup`, `stdbuf`, `timeout`) تحفظ مسارات الملفات التنفيذية الداخلية بدلًا -من مسارات المغلفات. كما يتم أيضًا فك multiplexers الخاصة بالـ shell (`busybox`, `toybox`) في حالة applets الخاصة بالـ shell (`sh`, `ash`، إلخ) بحيث تُحفَظ الملفات التنفيذية الداخلية بدلًا من ملفات multiplexer التنفيذية. وإذا تعذر -فك غلاف أو multiplexer بأمان، فلا يتم حفظ أي إدخال في قائمة السماح تلقائيًا. -إذا وضعت مفسرات مثل `python3` أو `node` في قائمة السماح، ففضّل `tools.exec.strictInlineEval=true` بحيث يظل inline eval يتطلب موافقة صريحة. في الوضع الصارم، لا يزال `allow-always` قادرًا على حفظ استدعاءات مفسر/سكريبت غير ضارة، لكن الوسائط الحاملة لـ inline-eval لا تُحفَظ تلقائيًا. +في موافقات تطبيق macOS المرافق، يُعامل نص shell الخام الذي يحتوي على بنية تحكم أو توسيع shell +(`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) على أنه عدم تطابق مع allowlist إلا إذا +كان الملف الثنائي لـ shell نفسه موجودًا في allowlist. +بالنسبة إلى أغلفة shell (`bash|sh|zsh ... -c/-lc`)، تُخفض تجاوزات env على مستوى الطلب إلى +قائمة سماح صريحة صغيرة (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`). +بالنسبة إلى قرارات allow-always في وضع allowlist، تحفظ أغلفة الإرسال المعروفة +(`env`, `nice`, `nohup`, `stdbuf`, `timeout`) مسارات الملفات التنفيذية الداخلية بدلًا من مسارات +الأغلفة. كما تُفك أيضًا أغلفة تعدد shell (`busybox`, `toybox`) بالنسبة إلى تطبيقات shell الصغيرة (`sh`, `ash`, +وغيرها) بحيث تُحفظ الملفات التنفيذية الداخلية بدلًا من الملفات الثنائية الخاصة بالمضاعِف. إذا تعذر فك غلاف أو +مضاعِف بأمان، فلا يُحفَظ أي إدخال في allowlist تلقائيًا. +إذا أضفت مفسرات مثل `python3` أو `node` إلى allowlist، ففضّل `tools.exec.strictInlineEval=true` حتى يظل eval المضمن يتطلب موافقة صريحة. في الوضع الصارم، لا يزال بإمكان `allow-always` حفظ استدعاءات مفسر/نص برمجي غير ضارة، لكن حوامل inline-eval لا تُحفَظ تلقائيًا. -القيم الافتراضية لـ safe bins: +Safe bins الافتراضية: [//]: # "SAFE_BIN_DEFAULTS:START" @@ -312,214 +312,213 @@ EOF [//]: # "SAFE_BIN_DEFAULTS:END" -لا يشمل ذلك `grep` و`sort` في القائمة الافتراضية. إذا فعّلتهما صراحة، فأبقِ إدخالات قائمة سماح صريحة -لسير العمل غير المعتمد على stdin الخاص بهما. -بالنسبة إلى `grep` في وضع safe-bin، قدّم النمط باستخدام `-e`/`--regexp`؛ -ويُرفض الشكل الموضعي للنمط حتى لا يمكن تهريب معاملات الملفات بوصفها معاملات موضعية غامضة. +لا يوجد `grep` و`sort` في القائمة الافتراضية. إذا قمت بتمكينهما صراحةً، فأبقِ إدخالات allowlist صريحة من أجل +سير العمل غير المعتمد على stdin. +بالنسبة إلى `grep` في وضع safe-bin، وفّر النمط باستخدام `-e`/`--regexp`؛ +يُرفض شكل النمط الموضعي حتى لا يمكن تهريب معاملات الملفات كمعاملات موضعية ملتبسة. ### Safe bins مقابل allowlist -| الموضوع | `tools.exec.safeBins` | Allowlist (`exec-approvals.json`) | -| ---------------- | ------------------------------------------------------ | ------------------------------------------------------------ | -| الهدف | السماح التلقائي لفلاتر stdin الضيقة | الوثوق الصريح بملفات تنفيذية محددة | -| نوع المطابقة | اسم الملف التنفيذي + سياسة argv الخاصة بـ safe-bin | نمط glob لمسار الملف التنفيذي المحلول | -| نطاق الوسائط | مقيّد بملف تعريف safe-bin وقواعد الرموز الحرفية | المطابقة على المسار فقط؛ أما الوسائط فهي ضمن مسؤوليتك | -| أمثلة شائعة | `head`, `tail`, `tr`, `wc` | `jq`, `python3`, `node`, `ffmpeg`, CLIs مخصصة | -| أفضل استخدام | تحويلات نصية منخفضة المخاطر في خطوط الأنابيب | أي أداة ذات سلوك أوسع أو آثار جانبية | +| الموضوع | `tools.exec.safeBins` | allowlist (`exec-approvals.json`) | +| ---------------- | ------------------------------------------------------ | ----------------------------------------------------------- | +| الهدف | السماح التلقائي لمرشحات stdin الضيقة | الثقة الصريحة في ملفات تنفيذية محددة | +| نوع المطابقة | اسم الملف التنفيذي + سياسة argv الخاصة بـ safe-bin | نمط glob لمسار الملف التنفيذي الذي تم حله | +| نطاق الوسائط | مقيّد بملف تعريف safe-bin وقواعد الرموز الحرفية | مطابقة المسار فقط؛ أما الوسائط فهي مسؤوليتك | +| أمثلة نموذجية | `head`, `tail`, `tr`, `wc` | `jq`, `python3`, `node`, `ffmpeg`, CLI مخصصة | +| أفضل استخدام | تحويلات نصية منخفضة المخاطر داخل خطوط الأنابيب | أي أداة ذات سلوك أوسع أو آثار جانبية | -موقع الإعدادات: +موقع التكوين: - تأتي `safeBins` من الإعدادات (`tools.exec.safeBins` أو لكل وكيل `agents.list[].tools.exec.safeBins`). - تأتي `safeBinTrustedDirs` من الإعدادات (`tools.exec.safeBinTrustedDirs` أو لكل وكيل `agents.list[].tools.exec.safeBinTrustedDirs`). -- تأتي `safeBinProfiles` من الإعدادات (`tools.exec.safeBinProfiles` أو لكل وكيل `agents.list[].tools.exec.safeBinProfiles`). وتتجاوز مفاتيح ملفات التعريف لكل وكيل المفاتيح العامة. -- تعيش إدخالات allowlist في `~/.openclaw/exec-approvals.json` المحلي على المستضيف تحت `agents..allowlist` (أو عبر Control UI / `openclaw approvals allowlist ...`). -- يحذر `openclaw security audit` باستخدام `tools.exec.safe_bins_interpreter_unprofiled` عندما تظهر ملفات المفسر/وقت التشغيل التنفيذية في `safeBins` من دون ملفات تعريف صريحة. -- يمكن لـ `openclaw doctor --fix` إنشاء إدخالات `safeBinProfiles.` المخصصة المفقودة تلقائيًا على شكل `{}` (راجعها وشدّدها بعد ذلك). ولا يتم إنشاء ملفات تعريف ملفات المفسرات/أوقات التشغيل التنفيذية تلقائيًا. +- تأتي `safeBinProfiles` من الإعدادات (`tools.exec.safeBinProfiles` أو لكل وكيل `agents.list[].tools.exec.safeBinProfiles`). تتجاوز مفاتيح ملفات التعريف لكل وكيل المفاتيح العامة. +- تعيش إدخالات allowlist في `~/.openclaw/exec-approvals.json` المحلي على المضيف تحت `agents..allowlist` (أو عبر Control UI / `openclaw approvals allowlist ...`). +- يحذر `openclaw security audit` بواسطة `tools.exec.safe_bins_interpreter_unprofiled` عندما تظهر ملفات مفسرات/بيئات تشغيل ثنائية في `safeBins` من دون ملفات تعريف صريحة. +- يمكن لـ `openclaw doctor --fix` إنشاء إدخالات `safeBinProfiles.` المخصصة المفقودة على شكل `{}` (راجعها وشددها بعد ذلك). لا تُنشأ ملفات مفسرات/بيئات التشغيل الثنائية تلقائيًا. مثال على ملف تعريف مخصص: __OC_I18N_900004__ -إذا فعّلت `jq` صراحة ضمن `safeBins`، فإن OpenClaw لا يزال يرفض builtin المسمى `env` في وضع safe-bin -بحيث لا يستطيع `jq -n env` تفريغ بيئة عملية المستضيف من دون مسار allowlist صريح +إذا قمت صراحةً بإضافة `jq` إلى `safeBins`، فسيظل OpenClaw يرفض builtin المسمى `env` في وضع safe-bin +حتى لا يتمكن `jq -n env` من تفريغ بيئة عملية المضيف من دون مسار allowlist صريح أو مطالبة موافقة. -## التحرير عبر Control UI +## التحرير في Control UI -استخدم بطاقة **Control UI → Nodes → Exec approvals** لتحرير الإعدادات الافتراضية، -والتجاوزات لكل وكيل، وقوائم السماح. اختر نطاقًا (Defaults أو وكيلًا)، وعدّل السياسة، -وأضف/أزل أنماط allowlist، ثم **احفظ**. تعرض واجهة المستخدم بيانات **آخر استخدام** -لكل نمط حتى تتمكن من الحفاظ على القائمة مرتبة. +استخدم بطاقة **Control UI → Nodes → Exec approvals** لتحرير الإعدادات الافتراضية، وتجاوزات +كل وكيل، وقوائم السماح. اختر نطاقًا (الإعدادات الافتراضية أو وكيلًا)، وعدّل السياسة، +وأضف/أزل أنماط allowlist، ثم انقر **حفظ**. تعرض الواجهة بيانات **آخر استخدام** +لكل نمط حتى تتمكن من إبقاء القائمة مرتبة. -يختار محدد الهدف **Gateway** (الموافقات المحلية) أو **Node**. -ويجب أن تعلن العقد عن `system.execApprovals.get/set` (تطبيق macOS أو مستضيف عقدة بدون واجهة). -إذا كانت العقدة لا تعلن عن موافقات exec بعد، فحرّر ملفها المحلي -`~/.openclaw/exec-approvals.json` مباشرة. +يختار محدد الهدف **Gateway** (الموافقات المحلية) أو **Node**. يجب على العقد +الإعلان عن `system.execApprovals.get/set` (تطبيق macOS أو مضيف عقدة بدون واجهة). +إذا لم تعلن العقدة عن موافقات exec بعد، فحرر ملفها المحلي +`~/.openclaw/exec-approvals.json` مباشرةً. -CLI: يدعم `openclaw approvals` التحرير للبوابة أو للعقدة (راجع [CLI الخاص بالموافقات](/cli/approvals)). +CLI: يدعم `openclaw approvals` التحرير على gateway أو node (راجع [CLI للموافقات](/cli/approvals)). ## تدفق الموافقة -عندما تكون المطالبة مطلوبة، تبث البوابة `exec.approval.requested` إلى عملاء المشغل. -وتقوم Control UI وتطبيق macOS بحسمها عبر `exec.approval.resolve`، ثم تمرر البوابة -الطلب الموافق عليه إلى مستضيف العقدة. +عندما تكون المطالبة مطلوبة، يبث gateway الحدث `exec.approval.requested` إلى عملاء المشغّلين. +يقوم Control UI وتطبيق macOS بحلها عبر `exec.approval.resolve`، ثم يمرر gateway +الطلب المعتمد إلى مضيف node. -بالنسبة إلى `host=node`، تتضمن طلبات الموافقة حمولة `systemRunPlan` قياسية. وتستخدم البوابة -هذه الخطة باعتبارها سياق الأمر/‏cwd/الجلسة الموثوق عند تمرير طلبات `system.run` -الموافق عليها. +بالنسبة إلى `host=node`، تتضمن طلبات الموافقة حمولة `systemRunPlan` أساسية. يستخدم gateway +هذه الخطة كسياق موثوق للأمر/cwd/الجلسة عند تمرير طلبات `system.run` +المعتمدة. -وهذا مهم لتأخر الموافقة غير المتزامنة: +وهذا مهم بالنسبة إلى زمن انتظار الموافقة غير المتزامنة: -- يقوم مسار exec الخاص بالعقدة بإعداد خطة قياسية واحدة مسبقًا -- ويخزن سجل الموافقة تلك الخطة وبيانات الربط الخاصة بها -- وبعد الموافقة، يعيد الاستدعاء النهائي الممرر لـ `system.run` استخدام الخطة المخزنة - بدلًا من الوثوق بتعديلات لاحقة من المستدعي -- وإذا غيّر المستدعي `command` أو `rawCommand` أو `cwd` أو `agentId` أو - `sessionKey` بعد إنشاء طلب الموافقة، ترفض البوابة - التشغيل الممرر بسبب عدم تطابق الموافقة +- يقوم مسار exec الخاص بالعقدة بإعداد خطة أساسية واحدة مسبقًا +- يخزّن سجل الموافقة هذه الخطة وبيانات الربط الخاصة بها +- بمجرد الموافقة، تعيد مكالمة `system.run` النهائية الممرّرة استخدام الخطة المخزنة + بدلًا من الثقة في تعديلات المستدعي اللاحقة +- إذا غيّر المستدعي `command` أو `rawCommand` أو `cwd` أو `agentId` أو + `sessionKey` بعد إنشاء طلب الموافقة، يرفض gateway + التشغيل الممرّر باعتباره عدم تطابق في الموافقة -## أوامر المفسرات/أوقات التشغيل +## أوامر المفسر/بيئة التشغيل -تكون تشغيلات المفسرات/أوقات التشغيل المدعومة بالموافقة محافظة عمدًا: +تكون عمليات تشغيل المفسر/بيئة التشغيل المدعومة بالموافقة محافظة عمدًا: -- يتم دائمًا ربط سياق `argv/cwd/env` الدقيق. -- يتم ربط shell script المباشر وأشكال ملفات وقت التشغيل المباشرة بأفضل جهد ممكن إلى لقطة - ملف محلي ملموس واحد. -- يتم فك صيغ مغلفات مدير الحزم الشائعة التي ما زالت تُحل إلى ملف محلي مباشر واحد (مثل +- يُربط دائمًا سياق argv/cwd/env المطابق. +- تُربط صيغ نصوص shell البرمجية المباشرة وصيغ ملفات بيئة التشغيل المباشرة، بأفضل جهد، بلقطة ملف محلي ملموس واحد. +- تُفك صيغ أغلفة مديري الحزم الشائعة التي ما تزال تُحل إلى ملف محلي مباشر واحد (مثل `pnpm exec` و`pnpm node` و`npm exec` و`npx`) قبل الربط. -- إذا تعذر على OpenClaw تحديد ملف محلي ملموس واحد بالضبط لأمر مفسر/وقت تشغيل - (مثل package scripts، أو صيغ eval، أو سلاسل التحميل الخاصة بوقت تشغيل معيّن، أو الصيغ - متعددة الملفات الغامضة)، فيُرفض التنفيذ المدعوم بالموافقة بدلًا من الادعاء بتغطية دلالية - لا يملكها. -- بالنسبة إلى مثل هذه التدفقات، ففضّل sandboxing، أو حدًا منفصلًا للمستضيف، أو سير عمل - موثوقًا وصريحًا باستخدام allowlist/full حيث يقبل المشغّل الدلالات الأوسع لوقت التشغيل. +- إذا تعذر على OpenClaw تحديد ملف محلي ملموس واحد بالضبط لأمر مفسر/بيئة تشغيل + (مثل نصوص الحزم البرمجية، وصيغ eval، وسلاسل التحميل الخاصة ببيئات التشغيل، أو الصيغ متعددة الملفات الملتبسة)، + فيُرفض التنفيذ المدعوم بالموافقة بدلًا من الادعاء بتغطية دلالية لا يمتلكها. +- بالنسبة إلى سير العمل هذا، ففضّل العزل، أو حدًا منفصلًا للمضيف، أو سير عمل صريحًا موثوقًا + يعتمد على allowlist/full حيث يقبل المشغّل الدلالات الأوسع لبيئة التشغيل. -عندما تكون الموافقات مطلوبة، تعيد أداة exec فورًا معرّف موافقة. استخدم هذا المعرّف -لربط أحداث النظام اللاحقة (`Exec finished` / `Exec denied`). وإذا لم يصل أي قرار قبل انتهاء المهلة، -يُعامل الطلب على أنه انتهاء مهلة للموافقة ويُعرض بوصفه سبب رفض. +عندما تكون الموافقات مطلوبة، تعيد أداة exec فورًا معرّف موافقة. استخدم هذا المعرف +لربط أحداث النظام اللاحقة (`Exec finished` / `Exec denied`). إذا لم يصل أي قرار قبل +انتهاء المهلة، يُعامل الطلب على أنه انتهاء مهلة الموافقة ويُعرض كسبب للرفض. ### سلوك تسليم المتابعة -بعد انتهاء exec غير متزامن تمت الموافقة عليه، يرسل OpenClaw دور `agent` متابعًا إلى الجلسة نفسها. +بعد انتهاء exec غير المتزامن المعتمد، يرسل OpenClaw متابعة من نوع `agent` إلى الجلسة نفسها. -- إذا كان هناك هدف تسليم خارجي صالح (قناة قابلة للتسليم بالإضافة إلى الهدف `to`)، فإن تسليم المتابعة يستخدم تلك القناة. -- في تدفقات webchat فقط أو تدفقات الجلسات الداخلية من دون هدف خارجي، يبقى تسليم المتابعة داخل الجلسة فقط (`deliver: false`). -- إذا طلب مستدعٍ صراحة تسليمًا خارجيًا صارمًا من دون قناة خارجية قابلة للحل، يفشل الطلب بالخطأ `INVALID_REQUEST`. -- إذا كانت `bestEffortDeliver` مفعلة ولم يمكن حل قناة خارجية، يُخفَّض التسليم إلى داخل الجلسة فقط بدلًا من الفشل. +- إذا كان هناك هدف تسليم خارجي صالح (قناة قابلة للتسليم مع الهدف `to`)، يستخدم تسليم المتابعة تلك القناة. +- في تدفقات webchat فقط أو الجلسات الداخلية التي لا تحتوي على هدف خارجي، يبقى تسليم المتابعة على مستوى الجلسة فقط (`deliver: false`). +- إذا طلب مستدعٍ صراحةً تسليمًا خارجيًا صارمًا من دون قناة خارجية قابلة للحل، يفشل الطلب بالرمز `INVALID_REQUEST`. +- إذا كان `bestEffortDeliver` مفعّلًا ولم يمكن حل أي قناة خارجية، فيُخفض التسليم إلى مستوى الجلسة فقط بدلًا من الفشل. -يتضمن مربع حوار التأكيد: +يتضمن مربع حوار التأكيد ما يلي: - الأمر + الوسائط -- `cwd` +- cwd - معرّف الوكيل -- مسار الملف التنفيذي المحلول -- بيانات المستضيف + السياسة +- مسار الملف التنفيذي الذي تم حله +- بيانات المضيف + السياسة الإجراءات: -- **Allow once** → التشغيل الآن -- **Always allow** → الإضافة إلى allowlist + التشغيل -- **Deny** → الحظر +- **السماح مرة واحدة** ← تشغيل الآن +- **السماح دائمًا** ← الإضافة إلى allowlist + التشغيل +- **رفض** ← حظر ## تمرير الموافقة إلى قنوات الدردشة -يمكنك تمرير مطالبات موافقة exec إلى أي قناة دردشة (بما في ذلك قنوات الإضافات) والموافقة -عليها باستخدام `/approve`. ويستخدم ذلك مسار التسليم الصادر العادي. +يمكنك تمرير مطالبات موافقة exec إلى أي قناة دردشة (بما في ذلك قنوات plugin) واعتمادها +باستخدام `/approve`. يستخدم هذا مسار التسليم الصادر المعتاد. -الإعدادات: +التكوين: __OC_I18N_900005__ الرد في الدردشة: __OC_I18N_900006__ -يتعامل الأمر `/approve` مع كل من موافقات exec وموافقات الإضافات. وإذا لم يطابق المعرّف أي موافقة exec معلقة، فإنه يتحقق تلقائيًا من موافقات الإضافات بدلًا من ذلك. +يتعامل الأمر `/approve` مع كلٍّ من موافقات exec وموافقات plugin. إذا لم يطابق المعرّف أي موافقة exec معلّقة، فإنه يتحقق تلقائيًا من موافقات plugin بدلًا من ذلك. -### تمرير موافقات الإضافات +### تمرير موافقة plugin -يستخدم تمرير موافقات الإضافات مسار التسليم نفسه الذي تستخدمه موافقات exec لكنه يملك -إعداداته المستقلة الخاصة تحت `approvals.plugin`. ولا يؤثر تفعيل أحدهما أو تعطيله في الآخر. +يستخدم تمرير موافقة plugin مسار التسليم نفسه الذي تستخدمه موافقات exec، لكن لديه +تكوين مستقل خاص به تحت `approvals.plugin`. لا يؤثر تمكين أحدهما أو تعطيله في الآخر. __OC_I18N_900007__ -يكون شكل الإعداد مطابقًا لـ `approvals.exec`: تعمل `enabled` و`mode` و`agentFilter`, -و`sessionFilter`، و`targets` بالطريقة نفسها. +شكل التكوين مطابق لـ `approvals.exec`: تعمل `enabled` و`mode` و`agentFilter`، +و`sessionFilter` و`targets` بالطريقة نفسها. -تعرض القنوات التي تدعم الردود التفاعلية المشتركة أزرار الموافقة نفسها لكل من exec -وموافقات الإضافات. أما القنوات التي لا تملك واجهة تفاعلية مشتركة فتعود إلى النص العادي مع -تعليمات `/approve`. +تعرض القنوات التي تدعم الردود التفاعلية المشتركة أزرار الموافقة نفسها لكل من موافقات exec و +plugin. أما القنوات التي لا تدعم واجهة تفاعلية مشتركة فترجع إلى النص العادي مع +إرشادات `/approve`. -### الموافقات داخل الدردشة نفسها على أي قناة +### الموافقات من الدردشة نفسها على أي قناة -عندما ينشأ طلب موافقة exec أو موافقة إضافة من سطح دردشة قابل للتسليم، يمكن الآن للدردشة نفسها -الموافقة عليه باستخدام `/approve` افتراضيًا. وينطبق هذا على قنوات مثل Slack وMatrix و -Microsoft Teams بالإضافة إلى تدفقات Web UI وواجهة الطرفية الموجودة مسبقًا. +عندما ينشأ طلب موافقة exec أو plugin من سطح دردشة قابل للتسليم، يمكن للدردشة نفسها +الآن اعتماده باستخدام `/approve` افتراضيًا. ينطبق هذا على قنوات مثل Slack وMatrix و +Microsoft Teams بالإضافة إلى تدفقات Web UI وواجهة الطرفية الحالية. -يستخدم مسار الأوامر النصية المشتركة هذا نموذج مصادقة القناة العادي لتلك المحادثة. فإذا كانت -الدردشة الأصلية تستطيع بالفعل إرسال الأوامر واستقبال الردود، فلن تعود طلبات الموافقة بحاجة إلى -محوّل تسليم أصلي منفصل لكي تظل معلقة. +يستخدم مسار الأوامر النصية المشتركة هذا نموذج المصادقة المعتاد للقناة ضمن تلك المحادثة. إذا كان +بإمكان الدردشة الأصلية إرسال الأوامر واستقبال الردود بالفعل، فلن تعود طلبات الموافقة بحاجة إلى +مهايئ تسليم أصلي منفصل لمجرد البقاء معلقة. -يدعم Discord وTelegram أيضًا `/approve` داخل الدردشة نفسها، لكن هاتين القناتين لا تزالان -تستخدمان قائمة الموافقين المحلولة الخاصة بهما من أجل التفويض حتى عندما يكون تسليم الموافقة الأصلي معطلًا. +يدعم Discord وTelegram أيضًا `/approve` داخل الدردشة نفسها، لكن هاتين القناتين تواصلان استخدام +قائمة الموافقين التي تم حلها للتخويل حتى عندما يكون تسليم الموافقات الأصلي معطلًا. -وبالنسبة إلى Telegram وعملاء الموافقة الأصليين الآخرين الذين يستدعون Gateway مباشرة، -فإن هذا البديل مقيد عمدًا بإخفاقات "لم يتم العثور على الموافقة". ولا تؤدي -حالة رفض/خطأ حقيقية في موافقة exec إلى إعادة المحاولة بصمت بوصفها موافقة إضافة. +بالنسبة إلى Telegram وغيره من عملاء الموافقة الأصليين الذين يستدعون Gateway مباشرةً، +فإن هذا الرجوع الاحتياطي يظل مقيدًا عمدًا بحالات فشل "الموافقة غير موجودة". أما +أي رفض/خطأ حقيقي لموافقة exec فلا يُعاد توجيهه بصمت كموافقة plugin. -### تسليم الموافقة الأصلي +### التسليم الأصلي للموافقات -يمكن لبعض القنوات أيضًا أن تعمل كعملاء موافقة أصليين. ويضيف العملاء الأصليون رسائل خاصة للموافقين، وتوزيعًا إلى الدردشة الأصلية، -وتجربة مستخدم تفاعلية خاصة بالقناة للموافقة فوق مسار `/approve` المشترك داخل الدردشة نفسها. +يمكن لبعض القنوات أيضًا أن تعمل كعملاء موافقة أصليين. يضيف العملاء الأصليون رسائل الموافقين الخاصة، +والتوزيع على الدردشة الأصلية، وواجهة مستخدم تفاعلية خاصة بالقناة للموافقة فوق +تدفق `/approve` المشترك داخل الدردشة نفسها. -عندما تكون بطاقات/أزرار الموافقة الأصلية متاحة، تكون هذه الواجهة الأصلية هي -المسار الأساسي الموجّه إلى الوكيل. ويجب ألا يعرض الوكيل أيضًا أمر -`/approve` عاديًا مكررًا في الدردشة إلا إذا كانت نتيجة الأداة تشير إلى أن -الموافقات عبر الدردشة غير متاحة أو أن الموافقة اليدوية هي المسار المتبقي الوحيد. +عندما تكون بطاقات/أزرار الموافقة الأصلية متاحة، تكون واجهة المستخدم الأصلية تلك هي المسار الأساسي +المواجه للوكيل. لا ينبغي للوكيل أيضًا أن يكرر أمر دردشة +عاديًا من نوع `/approve` إلا إذا كانت نتيجة الأداة تشير إلى أن موافقات الدردشة غير متاحة أو +أن الموافقة اليدوية هي المسار الوحيد المتبقي. النموذج العام: -- لا تزال سياسة exec على المستضيف هي التي تقرر ما إذا كانت موافقة exec مطلوبة +- ما تزال سياسة exec على المضيف هي التي تقرر ما إذا كانت موافقة exec مطلوبة - يتحكم `approvals.exec` في تمرير مطالبات الموافقة إلى وجهات دردشة أخرى - يتحكم `channels..execApprovals` في ما إذا كانت تلك القناة تعمل كعميل موافقة أصلي -يقوم عملاء الموافقة الأصليون تلقائيًا بتفعيل التسليم الخاص بالرسائل الخاصة أولًا عندما تكون جميع الشروط التالية صحيحة: +يقوم عملاء الموافقة الأصليون بتمكين التسليم أولًا إلى الرسائل الخاصة تلقائيًا عندما تكون كل الشروط التالية صحيحة: -- تدعم القناة تسليم الموافقة الأصلي -- يمكن حل الموافقين من `execApprovals.approvers` الصريح أو من مصادر الاحتياط الموثقة +- تدعم القناة تسليم الموافقات الأصلي +- يمكن حل الموافقين من `execApprovals.approvers` الصريح أو من مصادر الرجوع الاحتياطي الموثقة لتلك القناة -- تكون `channels..execApprovals.enabled` غير مضبوطة أو `"auto"` +- تكون قيمة `channels..execApprovals.enabled` غير معيّنة أو `"auto"` -اضبط `enabled: false` لتعطيل عميل موافقة أصلي صراحة. واضبط `enabled: true` لفرض -تفعيله عندما يتم حل الموافقين. ويظل التسليم العام إلى الدردشة الأصلية صريحًا عبر +اضبط `enabled: false` لتعطيل عميل موافقة أصلي صراحةً. واضبط `enabled: true` لفرض +تمكينه عندما يمكن حل الموافقين. يظل التسليم العام إلى الدردشة الأصلية صريحًا عبر `channels..execApprovals.target`. -الأسئلة الشائعة: [لماذا توجد إعداداتان لموافقة exec فيما يتعلق بموافقات الدردشة؟](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals) +الأسئلة الشائعة: [لماذا توجد إعداداتان لموافقة exec لموافقات الدردشة؟](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals) -- Discord: ‏`channels.discord.execApprovals.*` -- Slack: ‏`channels.slack.execApprovals.*` -- Telegram: ‏`channels.telegram.execApprovals.*` +- Discord: `channels.discord.execApprovals.*` +- Slack: `channels.slack.execApprovals.*` +- Telegram: `channels.telegram.execApprovals.*` -تضيف عملاء الموافقة الأصليون هؤلاء التوجيه إلى الرسائل الخاصة والخيار الاختياري لإرسال الرسائل إلى القناة فوق -مسار `/approve` المشترك داخل الدردشة نفسها وأزرار الموافقة المشتركة. +تضيف عملاء الموافقة الأصليون هؤلاء توجيه الرسائل الخاصة والتوزيع الاختياري على القنوات فوق +تدفق `/approve` المشترك داخل الدردشة نفسها وأزرار الموافقة المشتركة. السلوك المشترك: -- تستخدم الدردشات القابلة للتسليم مثل Slack وMatrix وMicrosoft Teams نموذج مصادقة القناة العادي - بالنسبة إلى `/approve` داخل الدردشة نفسها -- عندما يتم التفعيل التلقائي لعميل موافقة أصلي، يكون هدف التسليم الأصلي الافتراضي هو الرسائل الخاصة للموافقين -- بالنسبة إلى Discord وTelegram، لا يمكن إلا للموافقين المحلولين الموافقة أو الرفض +- تستخدم Slack وMatrix وMicrosoft Teams وغيرها من الدردشات القابلة للتسليم نموذج مصادقة القناة المعتاد + من أجل `/approve` داخل الدردشة نفسها +- عندما يتم تمكين عميل موافقة أصلي تلقائيًا، يكون هدف التسليم الأصلي الافتراضي هو الرسائل الخاصة للموافقين +- بالنسبة إلى Discord وTelegram، لا يمكن الموافقة أو الرفض إلا من قبل الموافقين الذين تم حلهم - يمكن أن يكون الموافقون في Discord صريحين (`execApprovals.approvers`) أو مستنتجين من `commands.ownerAllowFrom` -- يمكن أن يكون الموافقون في Telegram صريحين (`execApprovals.approvers`) أو مستنتجين من إعدادات المالك الموجودة (`allowFrom`، بالإضافة إلى `defaultTo` للرسائل المباشرة حيثما كان مدعومًا) +- يمكن أن يكون الموافقون في Telegram صريحين (`execApprovals.approvers`) أو مستنتجين من إعدادات المالك الحالية (`allowFrom`، بالإضافة إلى `defaultTo` للرسائل المباشرة حيثما كان ذلك مدعومًا) - يمكن أن يكون الموافقون في Slack صريحين (`execApprovals.approvers`) أو مستنتجين من `commands.ownerAllowFrom` -- تحافظ أزرار Slack الأصلية على نوع معرّف الموافقة، بحيث يمكن لمعرّفات `plugin:` حل موافقات الإضافات - من دون طبقة بديلة ثانية محلية في Slack -- يكون التوجيه الأصلي للرسائل الخاصة/القنوات في Matrix خاصًا بـ exec فقط؛ وتبقى موافقات الإضافات في Matrix على - مسار `/approve` المشترك داخل الدردشة نفسها ومسارات التمرير الاختيارية `approvals.plugin` -- لا يحتاج الطالب إلى أن يكون موافقًا -- يمكن للدردشة الأصلية الموافقة مباشرة باستخدام `/approve` عندما كانت تلك الدردشة تدعم الأوامر والردود بالفعل -- تقوم أزرار الموافقة الأصلية في Discord بالتوجيه بحسب نوع معرّف الموافقة: تذهب معرّفات `plugin:` مباشرة - إلى موافقات الإضافات، ويذهب كل شيء آخر إلى موافقات exec -- تتبع أزرار الموافقة الأصلية في Telegram مسار الاحتياط المحدود نفسه من exec إلى plugin كما في `/approve` +- تحافظ الأزرار الأصلية في Slack على نوع معرّف الموافقة، بحيث يمكن لمعرّفات `plugin:` حل موافقات plugin + من دون طبقة رجوع احتياطي ثانية محلية خاصة بـ Slack +- يتعامل توجيه الرسائل الخاصة/القنوات الأصلي في Matrix واختصارات التفاعل مع كلٍّ من موافقات exec وplugin؛ + بينما يظل تخويل plugin صادرًا من `channels.matrix.dm.allowFrom` +- لا يحتاج مقدّم الطلب إلى أن يكون من الموافقين +- يمكن للدردشة الأصلية الموافقة مباشرةً باستخدام `/approve` عندما تكون تلك الدردشة تدعم بالفعل الأوامر والردود +- تقوم أزرار الموافقة الأصلية في Discord بالتوجيه حسب نوع معرّف الموافقة: تنتقل معرّفات `plugin:` مباشرةً + إلى موافقات plugin، وكل ما عدا ذلك ينتقل إلى موافقات exec +- تتبع أزرار الموافقة الأصلية في Telegram نفس الرجوع الاحتياطي المحدود من exec إلى plugin كما في `/approve` - عندما يفعّل `target` الأصلي التسليم إلى الدردشة الأصلية، تتضمن مطالبات الموافقة نص الأمر - تنتهي صلاحية موافقات exec المعلقة بعد 30 دقيقة افتراضيًا -- إذا لم يتمكن أي مشغّل UI أو عميل موافقة مضبوط من قبول الطلب، تعود المطالبة إلى `askFallback` +- إذا لم تتمكن أي واجهة مستخدم للمشغّل أو عميل موافقة مكوّن من قبول الطلب، تعود المطالبة إلى `askFallback` -يستخدم Telegram افتراضيًا الرسائل الخاصة للموافقين (`target: "dm"`). ويمكنك التبديل إلى `channel` أو `both` عندما -تريد أن تظهر مطالبات الموافقة أيضًا في دردشة/موضوع Telegram الأصلية. وبالنسبة إلى موضوعات منتديات Telegram، -يحافظ OpenClaw على الموضوع من أجل مطالبة الموافقة والمتابعة التي تلي الموافقة. +يفترض Telegram استخدام الرسائل الخاصة للموافقين (`target: "dm"`). يمكنك التبديل إلى `channel` أو `both` عندما +تريد أن تظهر مطالبات الموافقة في دردشة/موضوع Telegram الأصلي أيضًا. بالنسبة إلى مواضيع منتديات Telegram، +يحافظ OpenClaw على الموضوع لمطالبة الموافقة ولمتابعة ما بعد الموافقة. راجع: @@ -530,38 +529,38 @@ Microsoft Teams بالإضافة إلى تدفقات Web UI وواجهة الط __OC_I18N_900008__ ملاحظات أمنية: -- وضع Unix socket هو `0600`، ويتم تخزين الرمز المميز في `exec-approvals.json`. -- فحص النظير بنفس UID. -- challenge/response ‏(nonce + HMAC token + request hash) + TTL قصير. +- وضع Unix socket هو `0600`، ويُخزّن الرمز المميز في `exec-approvals.json`. +- فحص النظير ذي المعرّف UID نفسه. +- تحدٍّ/استجابة (nonce + HMAC token + request hash) + TTL قصير. ## أحداث النظام -يتم عرض دورة حياة Exec على شكل رسائل نظام: +تظهر دورة حياة Exec كرسائل نظام: - `Exec running` (فقط إذا تجاوز الأمر عتبة إشعار التشغيل) - `Exec finished` - `Exec denied` -تُنشر هذه الرسائل إلى جلسة الوكيل بعد أن تبلغ العقدة بالحدث. -وتصدر موافقات exec على مستضيف gateway أحداث دورة الحياة نفسها عندما ينتهي الأمر (واختياريًا عندما يستغرق مدة أطول من العتبة). -وتعيد عمليات exec المقيدة بالموافقة استخدام معرّف الموافقة باعتباره `runId` في هذه الرسائل لتسهيل الربط. +تُنشر هذه الرسائل إلى جلسة الوكيل بعد أن تُبلغ العقدة عن الحدث. +تصدر موافقات exec على gateway-host أحداث دورة الحياة نفسها عندما ينتهي الأمر (واختياريًا عندما يستمر التشغيل مدة أطول من العتبة). +تعيد عمليات exec المقيدة بالموافقة استخدام معرّف الموافقة باعتباره `runId` في هذه الرسائل لسهولة الربط. ## سلوك الموافقة المرفوضة عند رفض موافقة exec غير متزامنة، يمنع OpenClaw الوكيل من إعادة استخدام -المخرجات الناتجة عن أي تشغيل سابق للأمر نفسه في الجلسة. ويتم تمرير سبب الرفض -مع إرشادات صريحة تفيد بعدم وجود مخرجات للأمر، مما يمنع -الوكيل من الادعاء بوجود مخرجات جديدة أو إعادة تكرار الأمر المرفوض مع -نتائج قديمة من تشغيل ناجح سابق. +المخرجات من أي تشغيل سابق للأمر نفسه في الجلسة. يُمرَّر سبب الرفض +مع إرشادات صريحة تفيد بعدم وجود أي مخرجات للأمر، مما يمنع +الوكيل من الادعاء بوجود مخرجات جديدة أو تكرار الأمر المرفوض مع +نتائج قديمة من تشغيل سابق ناجح. -## الآثار +## التبعات -- إن **full** قوي جدًا؛ ويفضل استخدام قوائم السماح عندما يكون ذلك ممكنًا. +- إن **full** قوي جدًا؛ ففضّل allowlists متى أمكن. - يبقيك **ask** ضمن الحلقة مع السماح بموافقات سريعة. -- تمنع قوائم السماح لكل وكيل انتقال موافقات وكيل ما إلى الآخرين. -- لا تنطبق الموافقات إلا على طلبات exec على المستضيف من **مرسلين مخولين**. ولا يستطيع المرسلون غير المخولين إصدار `/exec`. -- يُعد `/exec security=full` وسيلة راحة على مستوى الجلسة للمشغلين المخولين، ويتجاوز الموافقات عمدًا. - ولحظر exec على المستضيف بشكل صارم، اضبط أمان الموافقات على `deny` أو امنع أداة `exec` عبر سياسة الأدوات. +- تمنع allowlists لكل وكيل تسرب موافقات وكيل إلى وكلاء آخرين. +- لا تنطبق الموافقات إلا على طلبات exec على المضيف من **مرسلين مخولين**. لا يمكن للمرسلين غير المخولين إصدار `/exec`. +- يعد `/exec security=full` وسيلة مريحة على مستوى الجلسة للمشغّلين المخولين ويتجاوز الموافقات بحكم التصميم. + ولحظر exec على المضيف حظرًا صارمًا، اضبط أمان الموافقات على `deny` أو ارفض أداة `exec` عبر سياسة الأدوات. ذو صلة: @@ -572,6 +571,6 @@ __OC_I18N_900008__ ## ذو صلة - [Exec](/ar/tools/exec) — أداة تنفيذ أوامر shell -- [Sandboxing](/ar/gateway/sandboxing) — أوضاع sandbox والوصول إلى مساحة العمل +- [العزل](/ar/gateway/sandboxing) — أوضاع العزل والوصول إلى مساحة العمل - [الأمان](/ar/gateway/security) — نموذج الأمان والتقوية -- [Sandbox مقابل Tool Policy مقابل Elevated](/ar/gateway/sandbox-vs-tool-policy-vs-elevated) — متى تستخدم كل واحد منها +- [العزل مقابل سياسة الأدوات مقابل Elevated](/ar/gateway/sandbox-vs-tool-policy-vs-elevated) — متى تستخدم كل واحد منها